chore: add phase0 architecture guardrails and docs taxonomy

.github/workflows/pr.yml

@@ -50,5 +50,8 @@ jobs:
       - name: Format Check
         run: cargo make format-check
 
+      - name: Architecture Guardrails
+        run: cargo make architecture-check
+
       - name: Verify Publish Readiness
         run: cargo publish --dry-run --locked

.github/workflows/release.yml

@@ -110,6 +110,9 @@ jobs:
       - name: Format Check
         run: cargo make format-check
 
+      - name: Architecture Guardrails
+        run: cargo make architecture-check
+
       - name: Verify Publish Readiness
         run: cargo publish --dry-run --locked
 

AGENTS.md

@@ -0,0 +1,138 @@
+# AGENTS.md
+
+## Purpose
+This file defines how contributors and coding agents should work in this repository.
+It combines contribution rules, engineering best practices, and the target architecture direction.
+
+## Scope and Priority
+When making changes, follow this order:
+1. Correctness and user safety.
+2. Architectural direction (vertical slices + hexagonal boundaries).
+3. Existing contribution and lint rules.
+4. Minimal, reviewable diffs.
+
+## Project Context
+- `strest` is a high-performance load testing CLI.
+- Use is only valid for infrastructure you own or are explicitly authorized to test.
+- Main docs:
+  - `README.md`
+  - `CONTRIBUTING.md`
+  - `docs/guides/USAGE.md`
+  - `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.
+2. Keep changes tight and atomic.
+3. Update docs and `CHANGELOG.md` for user-visible behavior changes.
+4. Run required checks.
+5. Submit a concise PR with rationale and tradeoffs.
+
+### Required Checks
+```bash
+cargo make format
+cargo make clippy
+cargo make test
+```
+
+If WASM is touched:
+```bash
+cargo make test-wasm
+```
+
+If dependencies change:
+```bash
+cargo make audit
+cargo make deny
+```
+
+## Engineering Best Practices
+
+### Error Handling and Safety
+- Do not use `unwrap`, `expect`, `todo!`, or panic-driven control flow in production code.
+- Return typed errors (`AppError` and specific error variants) with actionable context.
+- Prefer explicit validation at boundaries.
+
+### Code Quality
+- No `#[allow(...)]` unless explicitly approved.
+- Keep functions focused; split orchestration from transformation logic.
+- Add tests for behavior changes, not just happy paths.
+- Preserve determinism where possible (especially metrics, replay, and distributed orchestration).
+
+### Performance and Concurrency
+- Avoid unnecessary allocations and cloning on hot paths.
+- Be explicit about async cancellation and shutdown behavior.
+- Avoid hidden blocking in async flows.
+
+### Documentation
+- Keep CLI/config docs aligned with behavior.
+- If a flag or output contract changes, update docs in the same PR.
+
+## Architecture Goal
+Target architecture is **vertical slices with hexagonal ports/adapters**.
+
+### Target Layers
+- `domain`: business models, policies, invariants.
+- `application`: use cases and orchestration against ports.
+- `adapters` (infrastructure): CLI, config parsing, HTTP/protocol transport, distributed wire IO, UI/charts/sinks, WASM/plugin runtime.
+
+### Dependency Rules (Desired)
+- `domain` must not depend on infrastructure frameworks (`clap`, `reqwest`, `tokio`, `ratatui`, `crossterm`).
+- `application` depends on `domain` + port traits, not concrete infra implementations.
+- `adapters` may depend on infra crates and implement application ports.
+- Entry points compose concrete adapters into use cases.
+
+## Transitional Rules for Current Codebase
+The repository is migrating. During migration:
+
+1. Do not introduce new deep coupling to `TesterArgs`.
+- New core/business logic should accept typed command/config structs, not raw CLI structs.
+
+2. Treat `src/args` as an adapter boundary.
+- CLI parsing and clap concerns stay there.
+- Avoid placing new domain policy there.
+
+3. Prefer anti-corruption mapping at boundaries.
+- Map CLI/config inputs into domain/application commands early.
+
+4. Keep vertical behavior grouped.
+- New features should fit a slice (`local_run`, `distributed_run`, `replay_compare`) instead of scattering across horizontal modules.
+
+5. Use branch-by-abstraction.
+- Add ports + adapters first, then migrate call sites incrementally.
+
+## Suggested Slice Ownership
+- `local_run`: run execution, protocol traffic, local metrics lifecycle.
+- `distributed_run`: controller/agent coordination, aggregation, distributed execution.
+- `replay_compare`: replay windows, snapshots, comparison flows.
+- `shared_kernel`: minimal shared value objects only.
+
+## PR Acceptance Checklist
+A PR is ready when:
+- Behavior is correct and tests pass.
+- Diff is scoped and understandable.
+- Lint/format/test checks pass.
+- Docs/changelog are updated when needed.
+- New code does not increase infra-domain coupling.
+- Any architectural compromise is called out with follow-up plan.
+
+## Anti-Patterns to Avoid
+- Passing `TesterArgs` through new domain/application APIs.
+- Mixing UI/sink/charts wiring directly inside core policy logic.
+- Embedding config precedence as ad-hoc mutation order across modules.
+- Adding new cross-cutting flags without explicit boundary mapping.
+
+## Preferred Change Pattern
+For new behavior, aim for this sequence:
+1. Define domain model/policy.
+2. Define application use-case input/output and ports.
+3. Implement or adapt infrastructure adapter.
+4. Wire in entry layer.
+5. Add tests at unit and integration level.
+
+## Notes for Agents
+- Optimize for small, reversible, evidence-backed changes.
+- If architecture and delivery conflict, preserve behavior first, then add a migration seam.
+- Mention architectural impact explicitly in PR summaries.

CHANGELOG.md

@@ -16,7 +16,7 @@ The format is based on Keep a Changelog, and this project follows SemVer.
 - Added opinionated preset subcommands: `strest quick`, `strest soak`, `strest spike`, and `strest distributed --agents=<N>`.
 - Preset commands now map to sensible defaults while preserving all existing advanced flag workflows.
 - Grouped high-frequency CLI flags under `Common Options` in `--help` for faster discoverability; kept advanced flags available unchanged.
-- Documented “99% paths” explicitly in `docs/USAGE.md` to reduce onboarding friction while preserving the full advanced surface.
+- Documented “99% paths” explicitly in `docs/guides/USAGE.md` to reduce onboarding friction while preserving the full advanced surface.
 - Fixed replay/export flow metrics ingestion so `response_bytes` and `in_flight_ops` are preserved when reading metrics logs.
 - Updated metrics log writing/parsing to include `response_bytes` and `in_flight_ops` columns, with backward compatibility for older 5-column logs.
 - Extended JSON/JSONL summary exports with flow aggregates: `total_response_bytes`, `avg_response_bytes_per_sec`, `max_in_flight_ops`, and `last_in_flight_ops`.
@@ -45,7 +45,7 @@ Released: 2026-02-11
 
 Released: 2026-02-11
 
-- Split README into `docs/USAGE.md` and `docs/ADVANCED.md` and shortened the top-level README.
+- Split README into `docs/guides/USAGE.md` and `docs/guides/ADVANCED.md` and shortened the top-level README.
 - Refactored internal error handling and reduced redundant allocations in request sources.
 - Split large modules into smaller units across replay, distributed controller, wasm scripting, and app error paths for maintainability.
 - Simplified startup wiring by moving entry/main orchestration into clearer module boundaries.

CONTRIBUTING.md

@@ -38,6 +38,7 @@ Examples:
 cargo make format
 cargo make clippy
 cargo make test
+cargo make architecture-check
 ```
 
 If you touched WASM:
@@ -61,6 +62,7 @@ git checkout -b feat/my-change
 cargo make format
 cargo make clippy
 cargo make test
+# cargo make architecture-check
 # cargo make test-wasm   # if WASM touched
 # cargo make audit       # if deps changed
 # cargo make deny        # if deps changed
@@ -84,6 +86,7 @@ Use this structure:
 - cargo make format
 - cargo make clippy
 - cargo make test
+- cargo make architecture-check
 - cargo make test-wasm (if applicable)
 - cargo make audit (if deps changed)
 - cargo make deny (if deps changed)

Makefile.toml

@@ -42,6 +42,12 @@ workspace = false
 command = "cargo"
 args = ["check", "--workspace", "--all", "${@}"]
 
+[tasks.architecture-check]
+description = "Enforce architecture boundaries and print coupling metrics"
+workspace = false
+command = "bash"
+args = ["scripts/check_architecture.sh"]
+
 [tasks.fuzz]
 description = "Run fuzzing tests on specified targets"
 workspace = false

README.md

@@ -43,7 +43,7 @@ strest --config strest.toml -t 30 --no-tui --summary --no-charts
 ## Screenshots
 
 <div style="text-align: center;">
-  <img src="docs/screenshot.png" alt="CLI Screenshot" width="1000" />
+  <img src="docs/assets/images/screenshot.png" alt="CLI Screenshot" width="1000" />
 </div>
 
 Charts focus on signal:
@@ -52,12 +52,13 @@ Charts focus on signal:
 - Throughput + inflight reveal saturation and ramp behavior.
 - Error breakdown separates timeouts, transport errors, and non-expected status codes.
 
-Full gallery: `docs/USAGE.md#charts`.
+Full gallery: `docs/guides/USAGE.md#charts`.
 
 ## Docs
 
-- `docs/USAGE.md` for CLI, flags, configs, and charts.
-- `docs/ADVANCED.md` for replay, WASM, profiling, distributed mode, and sinks.
+- `docs/README.md` for documentation index and structure.
+- `docs/guides/USAGE.md` for CLI, flags, configs, and charts.
+- `docs/guides/ADVANCED.md` for replay, WASM, profiling, distributed mode, and sinks.
 
 ## Contributions
 

docs/README.md

@@ -0,0 +1,21 @@
+# Documentation Index
+
+This folder is organized by concern:
+
+## Guides
+
+- `docs/guides/USAGE.md`: CLI usage, flags, configs, charts, and operational workflows.
+- `docs/guides/ADVANCED.md`: replay, WASM, profiling, distributed mode, and sinks.
+
+## 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/adr/ADR-0001-hexagonal-vertical-slices.md`: accepted architecture decision.
+
+## Assets
+
+- `docs/assets/images/`: UI and docs images.
+- `docs/assets/charts/`: chart screenshot gallery assets.

docs/architecture/README.md

@@ -0,0 +1,25 @@
+# Architecture Docs
+
+This directory is split by architecture document type.
+
+## Categories
+
+- `docs/architecture/ard/`: architecture reference and discovery docs.
+- `docs/architecture/adr/`: accepted architecture decisions.
+- `docs/architecture/srs/`: system requirements specifications.
+- `docs/architecture/rfc/`: architecture proposals under review.
+- `docs/architecture/patterns/`: reusable architectural patterns and guidance.
+
+## 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/adr/ADR-0001-hexagonal-vertical-slices.md`
+
+## Naming Conventions
+
+- ADRs: `ADR-<number>-<slug>.md`
+- RFCs: `RFC-<number>-<slug>.md`
+- SRS docs: `<slice-or-capability>-srs.md`
+- Patterns: `<pattern-name>.md`

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

@@ -0,0 +1,53 @@
+# ADR-0001: Vertical Slices with Hexagonal Boundaries
+
+- Status: Accepted
+- Date: 2026-02-13
+- Deciders: strest maintainers
+
+## Context
+
+`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:
+
+1. Layer model
+- `domain`: business models, invariants, and policies.
+- `application`: use cases orchestrating domain through ports.
+- `adapters`: infrastructure implementations (CLI, config, transport, distributed IO, output, WASM).
+
+2. Dependency rules
+- `domain` must not depend on infrastructure frameworks (`clap`, `reqwest`, `tokio`, `ratatui`, `crossterm`).
+- `application` must not depend directly on `clap`.
+- `adapters` may depend on infra crates and implement ports for application use cases.
+
+3. Transitional rules
+- Do not introduce new deep coupling to `TesterArgs` in core logic.
+- Treat `src/args` as a CLI adapter boundary.
+- Prefer anti-corruption mapping from CLI/config into typed commands at entry boundaries.
+- Keep behavior grouped by vertical slices (`local_run`, `distributed_run`, `replay_compare`).
+
+4. Guardrail enforcement
+- Add repository guardrail script: `scripts/check_architecture.sh`.
+- Run guardrails in CI for pull requests and release validation.
+- Track coupling baseline metrics (`crate::args` references, `TesterArgs` references).
+
+## Consequences
+
+### Positive
+- Architectural drift is blocked early in CI.
+- Migration progress is measurable by coupling metrics.
+- New use-case code can be tested with lower adapter coupling.
+
+### Tradeoffs
+- Temporary dual pathways (legacy + new boundaries) increase short-term complexity.
+- Additional CI checks add maintenance overhead.
+
+## Follow-up
+
+- 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.

docs/architecture/adr/README.md

@@ -0,0 +1,9 @@
+# ADR
+
+Architecture Decision Records.
+
+Use this folder for accepted and superseded architectural decisions. Each ADR should capture context, decision, consequences, and follow-up.
+
+Naming:
+
+- `ADR-<number>-<slug>.md`

docs/architecture/ard/ARCHITECTURE_BASELINE_METRICS.md

@@ -0,0 +1,30 @@
+# Architecture Baseline Metrics
+
+_Snapshot date: 2026-02-13_
+
+This baseline is used to track migration progress toward vertical slices with hexagonal boundaries.
+
+## Counting Method
+
+- Scope: `src/**/*.rs`.
+- Excludes tests: `**/tests/**`, `**/tests.rs`, `**/test_*.rs`, `**/*_test.rs`.
+- Source of truth: `scripts/check_architecture.sh`.
+
+## Baseline
+
+- `non_test_rust_files`: `209`
+- `files_referencing_crate_args`: `71`
+- `files_referencing_tester_args`: `62`
+
+## Top Cross-Module Edges (Top 10)
+
+- `distributed -> args` (`22`)
+- `distributed -> error` (`18`)
+- `app -> error` (`17`)
+- `charts -> error` (`16`)
+- `app -> metrics` (`16`)
+- `config -> error` (`13`)
+- `charts -> metrics` (`13`)
+- `app -> args` (`12`)
+- `config -> args` (`11`)
+- `protocol -> args` (`10`)