hatch3r 1.8.0 → 2.0.0

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/{rules → dist/content/rules}/hatch3r-secrets-management.md

@@ -2,8 +2,10 @@
 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*"
-tags: [security]
+scope: conditional
+globs: "**/.env*,**/*secret*,**/*credential*,**/*token*,**/config/**,**/.gitignore,**/vault/**,**/*auth*.config*"
+tags: [floor:security]
+precedence: critical
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -36,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.
@@ -55,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.
@@ -65,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`.
@@ -74,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/{rules → dist/content/rules}/hatch3r-secrets-management.mdc

@@ -2,6 +2,7 @@
 description: Secret management, rotation, and secure handling patterns for the project
 globs: ["**/.env*", "**/*secret*", "**/*credential*", "**/*token*", "**/config/**", "**/.gitignore", "**/vault/**", "**/*auth*.config*"]
 alwaysApply: false
+precedence: critical
 ---
 # Secrets Management
 
@@ -32,6 +33,8 @@ alwaysApply: false
 
 ## 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.
@@ -51,6 +54,8 @@ alwaysApply: false
 
 ## 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.
@@ -61,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`.
@@ -70,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.

package/{rules → dist/content/rules}/hatch3r-security-patterns.md

@@ -2,8 +2,10 @@
 id: hatch3r-security-patterns
 type: rule
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
-scope: "**/auth/**,**/security/**,**/middleware/**,**/*auth*,**/*guard*,**/*policy*,**/*permission*,**/*sanitiz*,**/*validat*"
-tags: [security]
+scope: conditional
+globs: "**/security/**,**/*guard*,**/*policy*,**/*permission*,**/*sanitiz*,**/*validat*"
+tags: [floor:security]
+precedence: critical
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
@@ -28,12 +30,7 @@ cache_friendly: true
 
 ## Authentication Enforcement
 
-- Auth middleware on every route by default. Public routes require explicit opt-out with code review justification.
-- Token validation: pin allowed algorithms (reject `none`), enforce expiry (`exp`), verify audience (`aud`) and issuer (`iss`) claims. Reject tokens failing any check.
-- Session security: `HttpOnly`, `Secure`, `SameSite=Strict` (or `Lax` with justification) cookies. Rotate session ID on privilege change (login, role switch).
-- Multi-factor authentication for sensitive operations: admin actions, payment, account deletion, API key generation.
-- Rate-limit authentication endpoints (login, token refresh, password reset). Lock accounts or add progressive delays after repeated failures.
-- Invalidate all sessions on password change. Provide "sign out everywhere" capability.
+Authentication and authorization patterns (auth middleware, token validation, session security, MFA/AAL mapping, rate-limiting auth endpoints) are owned canonically by `rules/hatch3r-auth-patterns.md`. That rule activates on `**/auth/**`, `**/login/**`, `**/session/**`, `**/middleware/**`, and related globs; this rule no longer restates them, so the two no longer double-fire on the same files. For OWASP A07 in the web-app context see the §A07 section below.
 
 ## Fail-Closed Defaults
 
@@ -137,6 +134,8 @@ cache_friendly: true
 
 ## OWASP Top 10 2025 (Web Application Security)
 
+Subsection order and titles follow the official OWASP Top 10:2025 release (https://owasp.org/Top10/2025/, accessed 2026-06-05). The 2025 list reorders the 2021 set: Security Misconfiguration rises to A02, A03 becomes Software Supply Chain Failures (an expansion of 2021's Vulnerable and Outdated Components), and Injection moves to A05.
+
 ### A01 — Broken Access Control
 
 - Enforce access control server-side. Client-side checks are UX, not security.
@@ -146,7 +145,32 @@ cache_friendly: true
 - Rate-limit API access to minimize automated IDOR scanning and credential stuffing.
 - Log access control failures and alert on repeated violations from the same identity.
 
-### A02 — Cryptographic Failures
+### A02 — Security Misconfiguration
+
+- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
+- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
+- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
+- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
+- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
+- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
+
+### A03 — Software Supply Chain Failures
+
+Expands 2021's Vulnerable and Outdated Components to cover the full dependency, build, and distribution chain — third-party code, build tools, CI/CD systems, and package registries.
+
+- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
+- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
+- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
+  - **GitHub:** Dependabot alerts and security advisories
+  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
+  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
+- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
+- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
+- Verify package provenance: prefer signed packages, scoped registries, and `npm ci` over `npm install`. Reject `npx -y` on untrusted names (typosquatting / dependency confusion).
+- Harden the build pipeline itself: pin CI actions by commit SHA, restrict who can modify pipeline config, and treat build secrets as production credentials.
+- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
+
+### A04 — Cryptographic Failures
 
 - Classify data by sensitivity (PII, financial, health, credentials). Apply encryption requirements per classification.
 - Encrypt data in transit (TLS 1.2+ mandatory, prefer 1.3) and at rest (AES-256 or equivalent).
@@ -155,7 +179,7 @@ cache_friendly: true
 - Generate cryptographic keys with secure random sources (`crypto.randomBytes`, not `Math.random`). Never hard-code keys or IVs.
 - Disable caching for responses containing sensitive data (`Cache-Control: no-store`).
 
-### A03 — Injection
+### A05 — Injection
 
 - Use parameterized queries or prepared statements for all database operations. Zero tolerance for string concatenation with user input in queries.
 - Apply context-aware output encoding: HTML entities, URL encoding, JavaScript escaping, CSS escaping, LDAP escaping — matched to the output context.
@@ -163,7 +187,7 @@ cache_friendly: true
 - Use `LIMIT` and pagination in queries to prevent mass data disclosure via injection.
 - For OS command execution: avoid entirely if possible. If necessary, use parameterized APIs (not shell interpolation) with strict input validation.
 
-### A04 — Insecure Design
+### A06 — Insecure Design
 
 - Use threat modeling during design phase (STRIDE, attack trees, or equivalent). Identify trust boundaries and abuse cases before writing code.
 - Establish and enforce secure design patterns: separation of concerns, defense in depth, least privilege, fail-closed.
@@ -171,28 +195,7 @@ cache_friendly: true
 - Design rate limiting, resource quotas, and cost controls into the architecture — not as afterthoughts.
 - Establish secure development lifecycle (SDL) practices: security requirements, design review, code review, testing.
 
-### A05 — Security Misconfiguration
-
-- Harden all environments: remove default accounts, disable unused features/ports/services, remove sample applications.
-- Use identical security configuration across development, staging, and production. Differences in security settings between environments mask vulnerabilities.
-- Automate configuration verification: infrastructure-as-code with security baselines, configuration scanning in CI.
-- Send security headers on every response (HSTS, CSP, X-Content-Type-Options, X-Frame-Options). Centralize in middleware.
-- Review cloud permissions quarterly. Remove unused IAM roles, security groups, and service accounts.
-- Disable detailed error messages in production. Use generic error responses with correlation IDs for debugging.
-
-### A06 — Vulnerable and Outdated Components
-
-- Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
-- Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
-- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
-  - **GitHub:** Dependabot alerts and security advisories
-  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
-  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
-- Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
-- Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
-- Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
-
-### A07 — Identification and Authentication Failures
+### A07 — Authentication Failures
 
 - Implement multi-factor authentication for privileged accounts and sensitive operations.
 - Enforce password complexity requirements: minimum 8 characters, check against breached password databases (Have I Been Pwned API).
@@ -201,7 +204,7 @@ cache_friendly: true
 - Never expose session IDs in URLs. Use secure, HttpOnly, SameSite cookies.
 - Implement account lockout with notification after repeated failed attempts.
 
-### A08 — Software and Data Integrity Failures
+### A08 — Software or Data Integrity Failures
 
 - Verify integrity of all software updates, dependencies, and CI/CD pipeline artifacts using digital signatures or checksums.
 - Use lockfiles and verify their integrity. `npm ci` (not `npm install`) in CI for deterministic builds that fail on lockfile drift.
@@ -213,7 +216,7 @@ cache_friendly: true
   - **Azure DevOps:** Pin pipeline tasks by exact version (e.g., `task@2`)
   - **GitLab CI:** Pin included templates by SHA or tag reference
 
-### A09 — Security Logging and Monitoring Failures
+### A09 — Security Logging and Alerting Failures
 
 - Log all authentication events (success, failure, lockout), access control failures, input validation failures, and security-relevant business events.
 - Use structured logging with correlation IDs. Include: timestamp, severity, event type, user identity (if available), source IP, resource accessed, outcome.