hatch3r 1.9.0 → 2.0.0

package/dist/content/rules/hatch3r-rust-patterns.md

@@ -0,0 +1,107 @@
+---
+id: hatch3r-rust-patterns
+type: rule
+description: Rust conventions covering 2024 edition idioms, error handling with thiserror/anyhow, ownership patterns, async with Tokio, testing, and Cargo workspaces
+scope: conditional
+globs: "**/*.rs,**/Cargo.toml,**/Cargo.lock,**/rustfmt.toml,**/.rustfmt.toml,**/clippy.toml,**/.clippy.toml,**/rust-toolchain,**/rust-toolchain.toml"
+tags: [implementation, lang:rust]
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Rust Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Rust crate or workspace. Detection signals: `Cargo.toml` at repo root, `*.rs` source files, or `rust-toolchain.toml` pinning a specific toolchain.
+
+## Rust Language Floor
+
+- Target the Rust 2024 edition (`edition = "2024"` in `Cargo.toml`). Adopted patterns: `let-else`, async closures, `if let` chains. Pin the toolchain in `rust-toolchain.toml` to the latest stable for reproducible builds.
+- Treat `cargo clippy --all-targets --all-features -- -D warnings` as a build gate. Configure `clippy.toml` with `msrv` and project-specific lints (`disallowed-methods`, `cognitive-complexity`).
+- Format with `cargo fmt --all -- --check` in CI. Use `rustfmt.toml` to pin style (e.g., `edition = "2024"`, `imports_granularity = "Crate"`).
+- Treat `cargo doc --no-deps --document-private-items` warnings as errors — missing doc on public items blocks merge.
+
+## Project Layout
+
+- Single crate: `src/lib.rs` for library code, `src/main.rs` or `src/bin/<name>.rs` for binaries. Avoid mixing — separate library and binary into a workspace.
+- Cargo workspaces for multi-crate repos: top-level `Cargo.toml` with `[workspace]`, crates under `crates/<name>/`. Use `[workspace.dependencies]` for shared version pinning.
+- Public API exposed via `pub use` re-exports in `lib.rs` — internal modules stay `pub(crate)`. Stop exporting implementation details accidentally.
+- Avoid `#[allow(...)]` outside test code. When unavoidable, comment with the reason and link to a tracking issue.
+
+## Error Handling
+
+- Library crates: define typed errors with `thiserror` (`#[derive(Error)]`). Implement `std::error::Error` and `Display`; do not implement them manually.
+- Binary crates: use `anyhow::Result<T>` for top-level error propagation with `.context("...")` annotations. Convert library errors via `From` impls or the `?` operator.
+- Never `unwrap()` or `expect()` in library code outside test fixtures. Use `.ok_or(...)` / `.ok_or_else(...)` to convert `Option` to `Result`.
+- Use `Result<T, E>` consistently. Never use `panic!` for recoverable errors. `assert!` in production code is a smell — convert to typed errors.
+
+## Ownership & Borrowing
+
+- Prefer owned `String` and `Vec<T>` in function signatures when the function will store the value. Use `&str` / `&[T]` for read-only inspection — Clippy's `needless_pass_by_value` flags violations.
+- Use `Cow<'_, str>` when the function may or may not modify the input. Stop cloning to "make the borrow checker happy".
+- For shared ownership: `Arc<T>` across threads, `Rc<T>` single-threaded. Wrap interior mutability with `Mutex`, `RwLock`, `parking_lot::Mutex` (no poisoning) — never `RefCell` across threads.
+- Document lifetime parameters when they affect the public API. Names like `'a` are placeholders; rename to `'src` / `'cfg` / `'req` when the meaning is non-trivial.
+
+## Async with Tokio
+
+- Tokio is the async-runtime floor for most projects (`tokio = "1"` with the `rt-multi-thread` feature). Use `async-std` only if a specific dependency requires it; document the reason.
+- Mark the entrypoint with `#[tokio::main(flavor = "multi_thread", worker_threads = N)]` for binaries. For tests, `#[tokio::test]` with the `current_thread` flavor unless the test exercises real parallelism.
+- Never block in async code — `std::sync::Mutex::lock` blocks; use `tokio::sync::Mutex` for async-aware locking. CPU-bound work goes through `tokio::task::spawn_blocking`.
+- Cancellation: prefer structured concurrency via `tokio::select!` + `CancellationToken`. Avoid dropping `JoinHandle` to "cancel" — the task continues running until it yields.
+- Timeouts: wrap I/O with `tokio::time::timeout(duration, fut)`. Tokio futures are cancel-safe only at `await` points — design around that.
+
+## Testing
+
+- Unit tests in `#[cfg(test)] mod tests { ... }` blocks next to the code. Integration tests in `tests/<name>.rs` at the crate root.
+- Property-based testing with `proptest` for parser / serializer / state-machine logic. `proptest!` generates random inputs and shrinks failing cases.
+- Snapshot testing with `insta` for serialized output (JSON, OpenAPI, generated code). Update snapshots through PR review — never blanket-update.
+- Mocking: `mockall` for trait-based mocking. Hand-rolled fakes are fine when the trait has ≤3 methods. Avoid `mock_it` / `faux` (less maintained).
+- Coverage: `cargo llvm-cov` for coverage reports. Floor: 80% line coverage in `src/`, 90% for critical modules (security, billing, persistence).
+- Fuzz testing with `cargo-fuzz` (`#[no_main] fuzz_target!`) for untrusted-input parsers. At least one fuzz target per public-facing parser.
+
+## Concurrency Idioms
+
+- For parallel CPU work: rayon (`rayon::iter::*`). Avoid threading directly with `std::thread::spawn` outside of long-running infrastructure (e.g., a background worker pool).
+- For async fan-out: `tokio::task::JoinSet` (preferred over `FuturesUnordered` for managed cancellation) or `futures::stream::buffered_unordered`. Bound concurrency explicitly — never spawn unbounded.
+- Channels: `tokio::sync::mpsc` (async), `crossbeam_channel` (sync, high-throughput). `std::sync::mpsc` is legacy — use the alternatives.
+- Shared state with `Arc<RwLock<T>>` — keep critical sections small. Holding a lock across an `.await` is a deadlock risk; the compiler does not flag it.
+
+## Performance
+
+- Profile with `cargo flamegraph` (Linux/macOS) or `samply` (cross-platform) before optimizing. Optimizing without a profile is guessing.
+- Use `cargo bench` with `criterion` for micro-benchmarks. Pin baselines in `target/criterion/` and compare in CI.
+- Compile-time flags: `RUSTFLAGS="-C target-cpu=native"` for binaries pinned to a known deployment environment. Cross-compiled binaries leave `target-cpu=native` off.
+- Release profile in `Cargo.toml`:
+  ```toml
+  [profile.release]
+  lto = "thin"
+  codegen-units = 1
+  strip = true
+  ```
+- Inline functions only after profiling. `#[inline]` hints, not commands; over-inlining bloats the binary and slows compilation.
+
+## Dependency Hygiene
+
+- Pin `Cargo.lock` for binary crates; ignore for library crates. The `cargo lock-not-in-vcs` warning calls this out.
+- Vulnerability scanning: `cargo audit` in CI against the RustSec advisory database. Block merge on advisory matches without an acknowledged remediation.
+- License compliance: `cargo deny check licenses` with an allowlist in `deny.toml`. Block GPL contamination via the allowlist.
+- Supply-chain: prefer crates with named maintainers, recent activity (≤6 months since last release), and >100 downloads/day. Pin transitive dependencies via `Cargo.lock` and re-verify on every `cargo update`.
+
+## Unsafe Code
+
+- `unsafe` blocks require a `// SAFETY:` comment explaining why the invariant holds. Reviewer cannot approve `unsafe` without the rationale.
+- Clippy lint `clippy::missing_safety_doc` is a build gate for `unsafe fn` declarations.
+- Prefer safe abstractions even if they cost performance. Optimize after profiling, with a measurable target.
+
+## References
+
+- Rust 2024 edition: https://doc.rust-lang.org/edition-guide/rust-2024/index.html (accessed 2026-05-27, official-docs)
+- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/ (accessed 2026-05-27, official-docs)
+- Tokio tutorial: https://tokio.rs/tokio/tutorial (accessed 2026-05-27, official-docs)
+- Cargo Book: https://doc.rust-lang.org/cargo/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Rust services (Axum/Tonic).
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `cargo llvm-cov`.
+- `rules/hatch3r-observability-logging.md` — `tracing` crate integration with the canonical logging contract.

package/dist/content/rules/hatch3r-rust-patterns.mdc

@@ -0,0 +1,102 @@
+---
+description: Rust conventions covering 2024 edition idioms, error handling with thiserror/anyhow, ownership patterns, async with Tokio, testing, and Cargo workspaces
+globs: ["**/*.rs", "**/Cargo.toml", "**/Cargo.lock", "**/rustfmt.toml", "**/.rustfmt.toml", "**/clippy.toml", "**/.clippy.toml", "**/rust-toolchain", "**/rust-toolchain.toml"]
+alwaysApply: false
+---
+# Rust Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a Rust crate or workspace. Detection signals: `Cargo.toml` at repo root, `*.rs` source files, or `rust-toolchain.toml` pinning a specific toolchain.
+
+## Rust Language Floor
+
+- Target the Rust 2024 edition (`edition = "2024"` in `Cargo.toml`). Adopted patterns: `let-else`, async closures, `if let` chains. Pin the toolchain in `rust-toolchain.toml` to the latest stable for reproducible builds.
+- Treat `cargo clippy --all-targets --all-features -- -D warnings` as a build gate. Configure `clippy.toml` with `msrv` and project-specific lints (`disallowed-methods`, `cognitive-complexity`).
+- Format with `cargo fmt --all -- --check` in CI. Use `rustfmt.toml` to pin style (e.g., `edition = "2024"`, `imports_granularity = "Crate"`).
+- Treat `cargo doc --no-deps --document-private-items` warnings as errors — missing doc on public items blocks merge.
+
+## Project Layout
+
+- Single crate: `src/lib.rs` for library code, `src/main.rs` or `src/bin/<name>.rs` for binaries. Avoid mixing — separate library and binary into a workspace.
+- Cargo workspaces for multi-crate repos: top-level `Cargo.toml` with `[workspace]`, crates under `crates/<name>/`. Use `[workspace.dependencies]` for shared version pinning.
+- Public API exposed via `pub use` re-exports in `lib.rs` — internal modules stay `pub(crate)`. Stop exporting implementation details accidentally.
+- Avoid `#[allow(...)]` outside test code. When unavoidable, comment with the reason and link to a tracking issue.
+
+## Error Handling
+
+- Library crates: define typed errors with `thiserror` (`#[derive(Error)]`). Implement `std::error::Error` and `Display`; do not implement them manually.
+- Binary crates: use `anyhow::Result<T>` for top-level error propagation with `.context("...")` annotations. Convert library errors via `From` impls or the `?` operator.
+- Never `unwrap()` or `expect()` in library code outside test fixtures. Use `.ok_or(...)` / `.ok_or_else(...)` to convert `Option` to `Result`.
+- Use `Result<T, E>` consistently. Never use `panic!` for recoverable errors. `assert!` in production code is a smell — convert to typed errors.
+
+## Ownership & Borrowing
+
+- Prefer owned `String` and `Vec<T>` in function signatures when the function will store the value. Use `&str` / `&[T]` for read-only inspection — Clippy's `needless_pass_by_value` flags violations.
+- Use `Cow<'_, str>` when the function may or may not modify the input. Stop cloning to "make the borrow checker happy".
+- For shared ownership: `Arc<T>` across threads, `Rc<T>` single-threaded. Wrap interior mutability with `Mutex`, `RwLock`, `parking_lot::Mutex` (no poisoning) — never `RefCell` across threads.
+- Document lifetime parameters when they affect the public API. Names like `'a` are placeholders; rename to `'src` / `'cfg` / `'req` when the meaning is non-trivial.
+
+## Async with Tokio
+
+- Tokio is the async-runtime floor for most projects (`tokio = "1"` with the `rt-multi-thread` feature). Use `async-std` only if a specific dependency requires it; document the reason.
+- Mark the entrypoint with `#[tokio::main(flavor = "multi_thread", worker_threads = N)]` for binaries. For tests, `#[tokio::test]` with the `current_thread` flavor unless the test exercises real parallelism.
+- Never block in async code — `std::sync::Mutex::lock` blocks; use `tokio::sync::Mutex` for async-aware locking. CPU-bound work goes through `tokio::task::spawn_blocking`.
+- Cancellation: prefer structured concurrency via `tokio::select!` + `CancellationToken`. Avoid dropping `JoinHandle` to "cancel" — the task continues running until it yields.
+- Timeouts: wrap I/O with `tokio::time::timeout(duration, fut)`. Tokio futures are cancel-safe only at `await` points — design around that.
+
+## Testing
+
+- Unit tests in `#[cfg(test)] mod tests { ... }` blocks next to the code. Integration tests in `tests/<name>.rs` at the crate root.
+- Property-based testing with `proptest` for parser / serializer / state-machine logic. `proptest!` generates random inputs and shrinks failing cases.
+- Snapshot testing with `insta` for serialized output (JSON, OpenAPI, generated code). Update snapshots through PR review — never blanket-update.
+- Mocking: `mockall` for trait-based mocking. Hand-rolled fakes are fine when the trait has ≤3 methods. Avoid `mock_it` / `faux` (less maintained).
+- Coverage: `cargo llvm-cov` for coverage reports. Floor: 80% line coverage in `src/`, 90% for critical modules (security, billing, persistence).
+- Fuzz testing with `cargo-fuzz` (`#[no_main] fuzz_target!`) for untrusted-input parsers. At least one fuzz target per public-facing parser.
+
+## Concurrency Idioms
+
+- For parallel CPU work: rayon (`rayon::iter::*`). Avoid threading directly with `std::thread::spawn` outside of long-running infrastructure (e.g., a background worker pool).
+- For async fan-out: `tokio::task::JoinSet` (preferred over `FuturesUnordered` for managed cancellation) or `futures::stream::buffered_unordered`. Bound concurrency explicitly — never spawn unbounded.
+- Channels: `tokio::sync::mpsc` (async), `crossbeam_channel` (sync, high-throughput). `std::sync::mpsc` is legacy — use the alternatives.
+- Shared state with `Arc<RwLock<T>>` — keep critical sections small. Holding a lock across an `.await` is a deadlock risk; the compiler does not flag it.
+
+## Performance
+
+- Profile with `cargo flamegraph` (Linux/macOS) or `samply` (cross-platform) before optimizing. Optimizing without a profile is guessing.
+- Use `cargo bench` with `criterion` for micro-benchmarks. Pin baselines in `target/criterion/` and compare in CI.
+- Compile-time flags: `RUSTFLAGS="-C target-cpu=native"` for binaries pinned to a known deployment environment. Cross-compiled binaries leave `target-cpu=native` off.
+- Release profile in `Cargo.toml`:
+  ```toml
+  [profile.release]
+  lto = "thin"
+  codegen-units = 1
+  strip = true
+  ```
+- Inline functions only after profiling. `#[inline]` hints, not commands; over-inlining bloats the binary and slows compilation.
+
+## Dependency Hygiene
+
+- Pin `Cargo.lock` for binary crates; ignore for library crates. The `cargo lock-not-in-vcs` warning calls this out.
+- Vulnerability scanning: `cargo audit` in CI against the RustSec advisory database. Block merge on advisory matches without an acknowledged remediation.
+- License compliance: `cargo deny check licenses` with an allowlist in `deny.toml`. Block GPL contamination via the allowlist.
+- Supply-chain: prefer crates with named maintainers, recent activity (≤6 months since last release), and >100 downloads/day. Pin transitive dependencies via `Cargo.lock` and re-verify on every `cargo update`.
+
+## Unsafe Code
+
+- `unsafe` blocks require a `// SAFETY:` comment explaining why the invariant holds. Reviewer cannot approve `unsafe` without the rationale.
+- Clippy lint `clippy::missing_safety_doc` is a build gate for `unsafe fn` declarations.
+- Prefer safe abstractions even if they cost performance. Optimize after profiling, with a measurable target.
+
+## References
+
+- Rust 2024 edition: https://doc.rust-lang.org/edition-guide/rust-2024/index.html (accessed 2026-05-27, official-docs)
+- Rust API Guidelines: https://rust-lang.github.io/api-guidelines/ (accessed 2026-05-27, official-docs)
+- Tokio tutorial: https://tokio.rs/tokio/tutorial (accessed 2026-05-27, official-docs)
+- Cargo Book: https://doc.rust-lang.org/cargo/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-api-design.md` — REST/GraphQL/gRPC contract floors apply to Rust services (Axum/Tonic).
+- `rules/hatch3r-testing.md` — coverage thresholds carry over to `cargo llvm-cov`.
+- `rules/hatch3r-observability-logging.md` — `tracing` crate integration with the canonical logging contract.

package/dist/content/rules/hatch3r-scalability.md

@@ -0,0 +1,137 @@
+---
+id: hatch3r-scalability-rule
+type: rule
+description: CQ6 Scalability Quality measurement rule — stateless-handler ratio, back-pressure pattern adoption, idempotency-key adoption on POST/PUT/PATCH, queue offloading for >1s ops, pool sizing per concurrency profile
+scope: conditional
+globs: "**/handlers/**,**/routes/**,**/services/**,**/api/**,**/workers/**,**/queues/**,**/jobs/**,**/middleware/**,**/handler*,**/route*,**/worker*,**/queue*"
+tags: [review, scalability, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Scalability Quality (CQ6)
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ6 (Scalability Quality)
+
+## Scope
+
+This rule binds the CQ6 measurement set across end-user services that hatch3r-generated agents produce. It owns:
+
+- The stateless-handler ratio floor on user-facing routes.
+- The back-pressure pattern adoption gate on high-fan-out endpoints.
+- The Idempotency-Key adoption floor on POST/PUT/PATCH endpoints.
+- The queue-based offloading gate for >1s operations.
+- The database connection pool sizing rule per concurrency profile.
+- Specialist routing to `agents/hatch3r-scalability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-resilience-patterns.md` (circuit breakers + retry-with-jitter + timeouts on outbound calls). Resilience is failure handling; scalability is horizontal-growth capability.
+
+## CQ6 Threshold Set
+
+Source: pillar CQ6 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle; missing measurement is a Medium finding minimum.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| Stateless-handler ratio | ≥95% on user-facing routes | Static scan: in-memory session state, module-level mutable globals, sticky-session assumptions in `app/`, `src/handlers/`, `src/routes/`, `pages/api/`, `apps/api/` |
+| Back-pressure pattern adoption | 100% on high-fan-out endpoints | Named pattern (semaphore, queue depth limit, rejection threshold) with documented thresholds |
+| Idempotency-Key adoption | 100% on POST/PUT/PATCH endpoints | Stripe pattern — header acceptance + dedup-result storage + named TTL |
+| Queue-based offloading | 100% for operations >1s | Background-job system + retry policy + dead-letter queue (DLQ) |
+| Connection pool sizing | Per concurrency profile | `pool_size = expected_concurrent_requests × avg_query_time / target_p99` per `agents/hatch3r-scalability.md` §Pool sizing |
+| Horizontal-scaling validation | Load tests at target scale | p99 latency within budget; no resource-pool exhaustion |
+
+## Stateless-Handler Pattern
+
+A handler is stateless when ALL hold:
+
+- No module-level mutable globals (`let counter = 0` at module scope; `Map` instances re-used across requests).
+- No in-process session storage (sessions stored in Redis, JWT, cookie store — externalized per `rules/hatch3r-auth-patterns.md`).
+- No sticky-session assumption (no logic that depends on the same physical instance handling consecutive requests from the same client).
+- No file-system cache at module scope (caches MUST live in Redis or a distributed store).
+
+Per-request request-scoped state is fine. The test is: can two requests from the same client land on different instances and both succeed? If yes, stateless.
+
+## Back-Pressure Pattern
+
+A handler is back-pressured when it explicitly bounds in-flight work. Allowed patterns:
+
+- **Semaphore** — fixed concurrency cap per handler; new requests reject 429 once the cap is reached.
+- **Queue depth limit** — work pushed onto a queue with a max depth; producer rejects when full.
+- **Rejection threshold** — load-shedding when p99 latency exceeds a documented budget.
+- **Token bucket** — rate-limit per client identifier with named refill rate.
+
+Implicit back-pressure (relying on TCP backlog, OS file-descriptor exhaustion, or queue-server overflow) does not satisfy this rule. The handler MUST cite the pattern name + threshold value in a comment near the entry point.
+
+## Idempotency-Key Adoption
+
+Source: Stripe `Idempotency-Key` header pattern (https://docs.stripe.com/api/idempotent_requests). On every POST/PUT/PATCH endpoint:
+
+1. Accept the `Idempotency-Key` request header (UUID v4 client-generated).
+2. On first observation, persist the request hash + response to a dedup store (Redis with TTL ≥24h, or database table with TTL index).
+3. On repeat observation within TTL, return the persisted response without re-executing the operation.
+4. Document the TTL in the handler comment + the API spec.
+
+Endpoints that explicitly DO NOT mutate state (GET, HEAD, OPTIONS) do not require the key. Endpoints that are inherently idempotent (DELETE with same target) MUST still accept the key for client convenience.
+
+## Queue-Based Offloading
+
+Operations >1s wall-clock MUST be moved off the request path:
+
+- **Job queue** — Sidekiq, BullMQ, Celery, Hangfire, Quartz; named retry policy (exponential backoff with jitter; max attempts; DLQ).
+- **Async response pattern** — return 202 Accepted with a `Location` header pointing to a status endpoint; client polls or uses webhook callback.
+- **Server-Sent Events / WebSocket** — for streaming progress on long operations.
+
+Synchronous handlers performing >1s work without offloading are a CRITICAL finding from the specialist. The 1s threshold is measured at p95 of historical traffic; not the modal time.
+
+## Database Connection Pool Sizing
+
+Pool size = `expected_concurrent_requests × avg_query_time / target_p99`. Audit pool-size config against:
+
+- `expected_concurrent_requests` = handler concurrency × instance count × steady-state RPS share.
+- `avg_query_time` = p50 query time from observability — cite the data source.
+- `target_p99` = SLO budget for handler latency — cite the SLO declaration.
+
+Over-sizing the pool exhausts the database's `max_connections`; under-sizing queues requests and inflates p99. The formula MUST appear in a comment in the pool-init code, with the three values populated from the current measurement.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Handler / route definition added or modified | `agents/hatch3r-scalability.md` (CQ6 review / gate) |
+| Queue client / connection-pool config modified | `agents/hatch3r-scalability.md` |
+| Session storage / cache-layer change | `agents/hatch3r-scalability.md` + `rules/hatch3r-auth-patterns.md` |
+| New endpoint that performs >1s work, accepts POST/PUT/PATCH, or runs on a horizontally-scaled tier | `agents/hatch3r-scalability.md` (Implementer pre-write) |
+| Load-test pre-release | `agents/hatch3r-scalability.md` |
+| Capacity-planning audit (new tenant, marketing event, geographic expansion) | `agents/hatch3r-scalability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ6. The `proof_trace` excerpt is the handler:line citation + measurement for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ6 Action per status:
+
+- `CRITICAL`: Sync >1s op without offloading; missing Idempotency-Key on POST/PUT/PATCH; sticky-session dependency on horizontally-scaled tier.
+- `FINDINGS`: Stateless-handler ratio <95%; missing back-pressure on high-fan-out endpoint; pool sizing without formula.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## Irreversibility Trigger
+
+Any recommendation that increases connection-pool sizes, changes queue topology (visibility timeout, partition count, DLQ binding), or removes a sticky-session strategy is irreversible at production traffic. These changes MUST go through `agents/shared/user-question-protocol.md` per `rules/hatch3r-clarification-default.md` B1 before action.
+
+## When to Invoke
+
+- Every PR that adds or modifies request handlers, route definitions, queue clients, or connection-pool config.
+- Every new endpoint that performs >1s work, accepts POST/PUT/PATCH, or runs on a horizontally-scaled tier.
+- Every change touching session storage, cache layers, or background-job systems.
+- Capacity-planning audits when service traffic projections change (new tenant onboarding, marketing event, geographic expansion).
+- Load-test pre-release before any release that claims horizontal-scaling capability or a new concurrency tier.
+
+## References
+
+- Pillar CQ6 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The content-quality-foundation audit domain (reliability + scalability foundation).
+- `agents/hatch3r-scalability.md` (CQ6 reviewer / gate).
+- `rules/hatch3r-resilience-patterns.md` (failure-handling patterns — distinct from horizontal-growth).
+- `rules/hatch3r-auth-patterns.md` (externalized session storage).
+- Stripe `Idempotency-Key` reference: https://docs.stripe.com/api/idempotent_requests.

package/dist/content/rules/hatch3r-scalability.mdc

@@ -0,0 +1,132 @@
+---
+description: CQ6 Scalability Quality measurement rule — stateless-handler ratio, back-pressure pattern adoption, idempotency-key adoption on POST/PUT/PATCH, queue offloading for >1s ops, pool sizing per concurrency profile
+globs: ["**/handlers/**", "**/routes/**", "**/services/**", "**/api/**", "**/workers/**", "**/queues/**", "**/jobs/**", "**/middleware/**", "**/handler*", "**/route*", "**/worker*", "**/queue*"]
+alwaysApply: false
+precedence: high
+---
+# Scalability Quality (CQ6)
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ6 (Scalability Quality)
+
+## Scope
+
+This rule binds the CQ6 measurement set across end-user services that hatch3r-generated agents produce. It owns:
+
+- The stateless-handler ratio floor on user-facing routes.
+- The back-pressure pattern adoption gate on high-fan-out endpoints.
+- The Idempotency-Key adoption floor on POST/PUT/PATCH endpoints.
+- The queue-based offloading gate for >1s operations.
+- The database connection pool sizing rule per concurrency profile.
+- Specialist routing to `agents/hatch3r-scalability.md`.
+
+This complements (does not duplicate) `rules/hatch3r-resilience-patterns.md` (circuit breakers + retry-with-jitter + timeouts on outbound calls). Resilience is failure handling; scalability is horizontal-growth capability.
+
+## CQ6 Threshold Set
+
+Source: pillar CQ6 (see `agents/shared/principles.md`). Every threshold below is measurable per audit cycle; missing measurement is a Medium finding minimum.
+
+| Threshold | Target | Measurement source |
+|-----------|--------|--------------------|
+| Stateless-handler ratio | ≥95% on user-facing routes | Static scan: in-memory session state, module-level mutable globals, sticky-session assumptions in `app/`, `src/handlers/`, `src/routes/`, `pages/api/`, `apps/api/` |
+| Back-pressure pattern adoption | 100% on high-fan-out endpoints | Named pattern (semaphore, queue depth limit, rejection threshold) with documented thresholds |
+| Idempotency-Key adoption | 100% on POST/PUT/PATCH endpoints | Stripe pattern — header acceptance + dedup-result storage + named TTL |
+| Queue-based offloading | 100% for operations >1s | Background-job system + retry policy + dead-letter queue (DLQ) |
+| Connection pool sizing | Per concurrency profile | `pool_size = expected_concurrent_requests × avg_query_time / target_p99` per `agents/hatch3r-scalability.md` §Pool sizing |
+| Horizontal-scaling validation | Load tests at target scale | p99 latency within budget; no resource-pool exhaustion |
+
+## Stateless-Handler Pattern
+
+A handler is stateless when ALL hold:
+
+- No module-level mutable globals (`let counter = 0` at module scope; `Map` instances re-used across requests).
+- No in-process session storage (sessions stored in Redis, JWT, cookie store — externalized per `rules/hatch3r-auth-patterns.md`).
+- No sticky-session assumption (no logic that depends on the same physical instance handling consecutive requests from the same client).
+- No file-system cache at module scope (caches MUST live in Redis or a distributed store).
+
+Per-request request-scoped state is fine. The test is: can two requests from the same client land on different instances and both succeed? If yes, stateless.
+
+## Back-Pressure Pattern
+
+A handler is back-pressured when it explicitly bounds in-flight work. Allowed patterns:
+
+- **Semaphore** — fixed concurrency cap per handler; new requests reject 429 once the cap is reached.
+- **Queue depth limit** — work pushed onto a queue with a max depth; producer rejects when full.
+- **Rejection threshold** — load-shedding when p99 latency exceeds a documented budget.
+- **Token bucket** — rate-limit per client identifier with named refill rate.
+
+Implicit back-pressure (relying on TCP backlog, OS file-descriptor exhaustion, or queue-server overflow) does not satisfy this rule. The handler MUST cite the pattern name + threshold value in a comment near the entry point.
+
+## Idempotency-Key Adoption
+
+Source: Stripe `Idempotency-Key` header pattern (https://docs.stripe.com/api/idempotent_requests). On every POST/PUT/PATCH endpoint:
+
+1. Accept the `Idempotency-Key` request header (UUID v4 client-generated).
+2. On first observation, persist the request hash + response to a dedup store (Redis with TTL ≥24h, or database table with TTL index).
+3. On repeat observation within TTL, return the persisted response without re-executing the operation.
+4. Document the TTL in the handler comment + the API spec.
+
+Endpoints that explicitly DO NOT mutate state (GET, HEAD, OPTIONS) do not require the key. Endpoints that are inherently idempotent (DELETE with same target) MUST still accept the key for client convenience.
+
+## Queue-Based Offloading
+
+Operations >1s wall-clock MUST be moved off the request path:
+
+- **Job queue** — Sidekiq, BullMQ, Celery, Hangfire, Quartz; named retry policy (exponential backoff with jitter; max attempts; DLQ).
+- **Async response pattern** — return 202 Accepted with a `Location` header pointing to a status endpoint; client polls or uses webhook callback.
+- **Server-Sent Events / WebSocket** — for streaming progress on long operations.
+
+Synchronous handlers performing >1s work without offloading are a CRITICAL finding from the specialist. The 1s threshold is measured at p95 of historical traffic; not the modal time.
+
+## Database Connection Pool Sizing
+
+Pool size = `expected_concurrent_requests × avg_query_time / target_p99`. Audit pool-size config against:
+
+- `expected_concurrent_requests` = handler concurrency × instance count × steady-state RPS share.
+- `avg_query_time` = p50 query time from observability — cite the data source.
+- `target_p99` = SLO budget for handler latency — cite the SLO declaration.
+
+Over-sizing the pool exhausts the database's `max_connections`; under-sizing queues requests and inflates p99. The formula MUST appear in a comment in the pool-init code, with the three values populated from the current measurement.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Handler / route definition added or modified | `agents/hatch3r-scalability.md` (CQ6 review / gate) |
+| Queue client / connection-pool config modified | `agents/hatch3r-scalability.md` |
+| Session storage / cache-layer change | `agents/hatch3r-scalability.md` + `rules/hatch3r-auth-patterns.md` |
+| New endpoint that performs >1s work, accepts POST/PUT/PATCH, or runs on a horizontally-scaled tier | `agents/hatch3r-scalability.md` (Implementer pre-write) |
+| Load-test pre-release | `agents/hatch3r-scalability.md` |
+| Capacity-planning audit (new tenant, marketing event, geographic expansion) | `agents/hatch3r-scalability.md` |
+
+## Per-Finding Output Format
+
+Every finding emitted under this rule uses the CQ per-finding rigor-field schema per `rules/hatch3r-cq-rule-frame.md` → Per-Finding Output Format (rigor-contract fields per `agents/shared/rigor-contract.md`), with `<N>` = CQ6. The `proof_trace` excerpt is the handler:line citation + measurement for the threshold that produced the finding.
+
+## Severity Mapping
+
+The Specialist-Status to canonical-severity map (`CRITICAL` → Critical, `FINDINGS` → High + Medium, `PASS` → Low + Info) is the shared CQ frame per `rules/hatch3r-cq-rule-frame.md` → Specialist-Status to Canonical-Severity Map, sourced from `agents/shared/severity-mapping.md`. CQ6 Action per status:
+
+- `CRITICAL`: Sync >1s op without offloading; missing Idempotency-Key on POST/PUT/PATCH; sticky-session dependency on horizontally-scaled tier.
+- `FINDINGS`: Stateless-handler ratio <95%; missing back-pressure on high-fan-out endpoint; pool sizing without formula.
+- `PASS`: All thresholds met; surface in iteration summary.
+
+## Irreversibility Trigger
+
+Any recommendation that increases connection-pool sizes, changes queue topology (visibility timeout, partition count, DLQ binding), or removes a sticky-session strategy is irreversible at production traffic. These changes MUST go through `agents/shared/user-question-protocol.md` per `rules/hatch3r-clarification-default.md` B1 before action.
+
+## When to Invoke
+
+- Every PR that adds or modifies request handlers, route definitions, queue clients, or connection-pool config.
+- Every new endpoint that performs >1s work, accepts POST/PUT/PATCH, or runs on a horizontally-scaled tier.
+- Every change touching session storage, cache layers, or background-job systems.
+- Capacity-planning audits when service traffic projections change (new tenant onboarding, marketing event, geographic expansion).
+- Load-test pre-release before any release that claims horizontal-scaling capability or a new concurrency tier.
+
+## References
+
+- Pillar CQ6 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The content-quality-foundation audit domain (reliability + scalability foundation).
+- `agents/hatch3r-scalability.md` (CQ6 reviewer / gate).
+- `rules/hatch3r-resilience-patterns.md` (failure-handling patterns — distinct from horizontal-growth).
+- `rules/hatch3r-auth-patterns.md` (externalized session storage).
+- Stripe `Idempotency-Key` reference: https://docs.stripe.com/api/idempotent_requests.

package/dist/content/rules/hatch3r-secrets-management.md

@@ -2,7 +2,8 @@
 id: hatch3r-secrets-management
 type: rule
 description: Secret management, rotation, and secure handling patterns for the project
-scope: "**/.env*,**/*secret*,**/*credential*,**/*token*,**/config/**,**/.gitignore,**/vault/**,**/*auth*.config*"
+scope: conditional
+globs: "**/.env*,**/*secret*,**/*credential*,**/*token*,**/config/**,**/.gitignore,**/vault/**,**/*auth*.config*"
 tags: [floor:security]
 precedence: critical
 quality_charter: agents/shared/quality-charter.md
@@ -37,6 +38,8 @@ cache_friendly: true
 
 ## Cloud Secret Managers
 
+> Maturity tier: team+ — solo projects may keep secrets in a local `.env` outside git. A managed vault earns its cost once a second engineer, a deployed environment, or a compliance audit enters the picture.
+
 - **AWS Secrets Manager:** Store secrets as JSON key-value pairs. Use IAM policies to scope access per service/role. Enable automatic rotation with Lambda rotation functions. Use `aws-sdk` `GetSecretValue` at runtime — never bake secrets into container images or deployment artifacts.
 - **GCP Secret Manager:** Store each secret as a versioned resource. Grant `secretmanager.secretAccessor` role per service account with resource-level IAM. Access secrets via `@google-cloud/secret-manager` client library at startup. Use secret versions (not `latest` in production) for auditability.
 - **Azure Key Vault:** Store secrets, keys, and certificates. Use Managed Identity for authentication — no credentials needed to access the vault. Apply access policies per application identity. Enable soft-delete and purge protection.
@@ -56,6 +59,8 @@ cache_friendly: true
 
 ## OIDC Trust-Policy Conditions (Cloud Auth)
 
+> Maturity tier: team+ — solo projects with no CI-to-cloud federation may defer. OIDC trust-policy hardening matters once CI deploys to a shared cloud account; before that, scoped local credentials are acceptable.
+
 Long-lived cloud secrets (`AWS_ACCESS_KEY_ID`, `GOOGLE_APPLICATION_CREDENTIALS` JSON file, Azure SP password) in CI are an anti-pattern in 2026. GitHub OIDC issues a per-run JWT; the cloud provider's trust policy exchanges it for short-lived credentials scoped to the workflow.
 
 - **Branch + environment conditions are required.** The `sub` claim must be matched to a specific `(repository, ref, environment)` triple. PR workflows assume a read-only role; main-branch workflows assume the production role.
@@ -66,6 +71,8 @@ Long-lived cloud secrets (`AWS_ACCESS_KEY_ID`, `GOOGLE_APPLICATION_CREDENTIALS`
 
 ## Secret Manager Mandate
 
+> Maturity tier: scaleup+ — team projects may run a single vault per environment; scaleup adds per-service IAM/IRSA scoping and automated rotation. Solo projects skip this section.
+
 Every production secret lives in a managed vault — AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or a SaaS equivalent (Doppler, 1Password Secrets Automation, Infisical). Direct `.env`-file secret storage is permitted only for local development, and the file is never committed.
 
 - Repository ships `.env.example` only — a template with placeholder values and per-variable descriptions. Actual `.env` is in `.gitignore`.
@@ -75,6 +82,8 @@ Every production secret lives in a managed vault — AWS Secrets Manager, GCP Se
 
 ## Certificate Automation
 
+> Maturity tier: team+ — solo projects with a single managed-cert endpoint may defer the monitoring + SPKI-pinning controls. Cert-manager and pager alerts become mandatory once a team owns more than one TLS endpoint.
+
 TLS certificate expiry is a recurring outage class — manual renewal is forbidden in production. Automate via ACME.
 
 - **Kubernetes:** `cert-manager` with a `ClusterIssuer` pointing at Let's Encrypt (production) or a private ACME server. Use HTTP-01 or DNS-01 solver per environment.

package/dist/content/rules/hatch3r-secrets-management.mdc

@@ -33,6 +33,8 @@ precedence: critical
 
 ## Cloud Secret Managers
 
+> Maturity tier: team+ — solo projects may keep secrets in a local `.env` outside git. A managed vault earns its cost once a second engineer, a deployed environment, or a compliance audit enters the picture.
+
 - **AWS Secrets Manager:** Store secrets as JSON key-value pairs. Use IAM policies to scope access per service/role. Enable automatic rotation with Lambda rotation functions. Use `aws-sdk` `GetSecretValue` at runtime — never bake secrets into container images or deployment artifacts.
 - **GCP Secret Manager:** Store each secret as a versioned resource. Grant `secretmanager.secretAccessor` role per service account with resource-level IAM. Access secrets via `@google-cloud/secret-manager` client library at startup. Use secret versions (not `latest` in production) for auditability.
 - **Azure Key Vault:** Store secrets, keys, and certificates. Use Managed Identity for authentication — no credentials needed to access the vault. Apply access policies per application identity. Enable soft-delete and purge protection.
@@ -52,6 +54,8 @@ precedence: critical
 
 ## OIDC Trust-Policy Conditions (Cloud Auth)
 
+> Maturity tier: team+ — solo projects with no CI-to-cloud federation may defer. OIDC trust-policy hardening matters once CI deploys to a shared cloud account; before that, scoped local credentials are acceptable.
+
 Long-lived cloud secrets (`AWS_ACCESS_KEY_ID`, `GOOGLE_APPLICATION_CREDENTIALS` JSON file, Azure SP password) in CI are an anti-pattern in 2026. GitHub OIDC issues a per-run JWT; the cloud provider's trust policy exchanges it for short-lived credentials scoped to the workflow.
 
 - **Branch + environment conditions are required.** The `sub` claim must be matched to a specific `(repository, ref, environment)` triple. PR workflows assume a read-only role; main-branch workflows assume the production role.
@@ -62,6 +66,8 @@ Long-lived cloud secrets (`AWS_ACCESS_KEY_ID`, `GOOGLE_APPLICATION_CREDENTIALS`
 
 ## Secret Manager Mandate
 
+> Maturity tier: scaleup+ — team projects may run a single vault per environment; scaleup adds per-service IAM/IRSA scoping and automated rotation. Solo projects skip this section.
+
 Every production secret lives in a managed vault — AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, or a SaaS equivalent (Doppler, 1Password Secrets Automation, Infisical). Direct `.env`-file secret storage is permitted only for local development, and the file is never committed.
 
 - Repository ships `.env.example` only — a template with placeholder values and per-variable descriptions. Actual `.env` is in `.gitignore`.
@@ -71,6 +77,8 @@ Every production secret lives in a managed vault — AWS Secrets Manager, GCP Se
 
 ## Certificate Automation
 
+> Maturity tier: team+ — solo projects with a single managed-cert endpoint may defer the monitoring + SPKI-pinning controls. Cert-manager and pager alerts become mandatory once a team owns more than one TLS endpoint.
+
 TLS certificate expiry is a recurring outage class — manual renewal is forbidden in production. Automate via ACME.
 
 - **Kubernetes:** `cert-manager` with a `ClusterIssuer` pointing at Let's Encrypt (production) or a private ACME server. Use HTTP-01 or DNS-01 solver per environment.