feat: finalize phase 7 hexagonal boundaries and add technical architecture patterns

AGENTS.md

@@ -21,7 +21,6 @@ When making changes, follow this order:
   - `docs/guides/ADVANCED.md`
   - `docs/architecture/README.md`
   - `docs/architecture/ard/ARCHITECTURE_OVERVIEW.md`
-  - `docs/architecture/ard/ARCHITECTURE_RISKS_HEXAGONAL_PLAN.md`
 
 ## Required Contribution Workflow
 1. Create a scoped branch.

CHANGELOG.md

@@ -5,6 +5,14 @@ The format is based on Keep a Changelog, and this project follows SemVer.
 
 ## Unreleased
 
+- Completed Phase 7 of the hexagonal migration by removing direct `TesterArgs` coupling from the application layer (`application::commands`, `application::local_run`, `application::distributed_run`) and tightening adapter-boundary mapping in entry planning.
+- Added architecture guardrails that fail checks when `src/application` reintroduces `TesterArgs` or `crate::args` imports.
+- Removed remaining non-test direct `distributed -> app` and `application -> app` imports by introducing explicit runtime ports and shared summary-output utilities, so orchestration flows now route via application/adapters seams.
+- Added migration validation coverage for all run-plan feature routes (local, distributed controller/agent, replay, compare, cleanup, dump-urls, service) and distributed/local application dispatch seams.
+- Updated architecture docs to a current flow-focused overview with explicit mode-by-mode call chains.
+- Added technical architecture docs across ARD/ADR/patterns covering type-level invariants/newtypes, invalid-state elimination, cache/inlining guidance, dispatch strategy (static-first), and low-lock concurrency patterns using `Arc`, atomics, channels, and `ArcShift`.
+- Removed legacy migration-risk and baseline-metrics ARD documents and updated doc indexes/references accordingly.
+
 ## 0.1.9
 
 Released: 2026-02-13

docs/README.md

@@ -10,10 +10,11 @@ This folder is organized by concern:
 ## Architecture
 
 - `docs/architecture/README.md`: architecture document taxonomy and conventions.
-- `docs/architecture/ard/ARCHITECTURE_OVERVIEW.md`: generated module/dependency overview.
-- `docs/architecture/ard/ARCHITECTURE_RISKS_HEXAGONAL_PLAN.md`: architecture risks and phased migration plan.
-- `docs/architecture/ard/ARCHITECTURE_BASELINE_METRICS.md`: migration baseline coupling metrics.
+- `docs/architecture/ard/ARCHITECTURE_OVERVIEW.md`: current mode-by-mode call-flow overview.
+- `docs/architecture/ard/ARCHITECTURE_TECHNICAL_GUIDE.md`: technical implementation guide for invariants, dispatch, and concurrency.
 - `docs/architecture/adr/ADR-0001-hexagonal-vertical-slices.md`: accepted architecture decision.
+- `docs/architecture/adr/ADR-0002-type-safety-dispatch-concurrency.md`: accepted technical decision for type safety, dispatch, and low-lock concurrency.
+- `docs/architecture/patterns/type-safety-performance-concurrency.md`: technical patterns for type invariants, dispatch, cache behavior, and lock-free concurrency.
 
 ## Assets
 

docs/architecture/README.md

@@ -13,9 +13,9 @@ This directory is split by architecture document type.
 ## Current Canonical Docs
 
 - `docs/architecture/ard/ARCHITECTURE_OVERVIEW.md`
-- `docs/architecture/ard/ARCHITECTURE_RISKS_HEXAGONAL_PLAN.md`
-- `docs/architecture/ard/ARCHITECTURE_BASELINE_METRICS.md`
+- `docs/architecture/ard/ARCHITECTURE_TECHNICAL_GUIDE.md`
 - `docs/architecture/adr/ADR-0001-hexagonal-vertical-slices.md`
+- `docs/architecture/adr/ADR-0002-type-safety-dispatch-concurrency.md`
 
 ## Naming Conventions
 

docs/architecture/adr/ADR-0001-hexagonal-vertical-slices.md

@@ -8,8 +8,6 @@
 
 `strest` currently works as a modular monolith, but core behavior is coupled to adapter concerns, especially CLI (`TesterArgs`) and runtime IO wiring. The migration target is vertical slices with explicit ports/adapters boundaries, without a big-bang rewrite.
 
-The primary risks are documented in `docs/architecture/ard/ARCHITECTURE_RISKS_HEXAGONAL_PLAN.md`.
-
 ## Decision
 
 Adopt a phased migration architecture with these boundaries:
@@ -51,3 +49,4 @@ Adopt a phased migration architecture with these boundaries:
 - Phase 1 introduces typed commands and mapping from CLI args.
 - Phase 2 moves config precedence to explicit override policies.
 - Later phases extract local/distributed/replay slices behind ports.
+- Detailed technical execution guidance is captured in `ADR-0002-type-safety-dispatch-concurrency.md`.

docs/architecture/adr/ADR-0002-type-safety-dispatch-concurrency.md

@@ -0,0 +1,54 @@
+# ADR-0002: Type-Safe APIs, Static-First Dispatch, and Low-Lock Concurrency
+
+- Status: Accepted
+- Date: 2026-02-14
+- Deciders: strest maintainers
+
+## Context
+
+After Phase 7 boundary migration, architecture seams are established (`entry -> application -> adapters -> slices`).
+
+The next risk is implementation drift inside those seams:
+- invariants moving back to ad-hoc runtime checks
+- overuse of dynamic dispatch on hot paths
+- lock contention in concurrent execution paths
+
+## Decision
+
+Adopt these technical architecture rules:
+
+1. Type-safety first
+- Encode invariants in types (newtypes/enums) at system boundaries.
+- Prefer APIs that cannot represent invalid combinations.
+
+2. Static dispatch by default
+- Use static/generic dispatch for core orchestration and hot paths.
+- Use dynamic dispatch only at explicit runtime-extension boundaries.
+
+3. Low-lock concurrency
+- Prefer `Arc`, atomics, and channels for high-frequency coordination.
+- Use `ArcShift` for read-mostly shared snapshots in manual controller flows.
+- Avoid lock scopes that cross `.await`.
+
+4. Performance policy
+- Optimize for cache behavior and allocation discipline first.
+- Use explicit inlining annotations only with profiling evidence.
+
+## Consequences
+
+### Positive
+- Stronger compile-time guarantees for config and execution state.
+- Lower overhead on core execution paths.
+- Better concurrency behavior under distributed/high-load scenarios.
+- Clearer review criteria for architecture-sensitive changes.
+
+### Tradeoffs
+- More up-front type modeling work.
+- Possible binary-size increase from monomorphization in generic paths.
+- Requires discipline to keep dynamic dispatch limited to boundary seams.
+
+## Follow-up
+
+- Keep the implementation guidance in `docs/architecture/ard/ARCHITECTURE_TECHNICAL_GUIDE.md`.
+- Keep reusable rule summaries in `docs/architecture/patterns/type-safety-performance-concurrency.md`.
+- Enforce boundary constraints through existing architecture checks and code review.

docs/architecture/adr/README.md

@@ -4,6 +4,11 @@ Architecture Decision Records.
 
 Use this folder for accepted and superseded architectural decisions. Each ADR should capture context, decision, consequences, and follow-up.
 
+Current docs:
+
+- `ADR-0001-hexagonal-vertical-slices.md`
+- `ADR-0002-type-safety-dispatch-concurrency.md`
+
 Naming:
 
 - `ADR-<number>-<slug>.md`