hatch3r 1.9.0 → 2.0.0

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

@@ -0,0 +1,93 @@
+---
+description: SwiftUI and Swift conventions covering Swift 6 concurrency, @Observable + @Bindable, navigation stacks, Swift Package Manager, modular architecture, and XCTest
+globs: ["**/*.swift", "**/*.swiftinterface", "**/Package.swift", "**/Package.resolved", "**/*.xcodeproj/**", "**/*.xcworkspace/**", "**/Info.plist", "**/*.entitlements", "**/Tuist/**", "**/Project.swift", "**/Workspace.swift", "**/ios/**", "**/macos/**", "**/visionOS/**", "**/watchOS/**", "**/tvOS/**"]
+alwaysApply: false
+---
+# SwiftUI Patterns
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ8 (Maintainability Quality)
+
+> Applies when the project ships a SwiftUI/UIKit app or Swift package. Detection signals: `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, or `*.swift` files at repo root.
+
+## Swift Language Floor
+
+- Target Swift 6.0+ with strict concurrency checking enabled (`SWIFT_STRICT_CONCURRENCY=complete`). Data-race-safety is the default; opt-out (`@unchecked Sendable`) requires a code comment justifying thread-safety reasoning.
+- Adopt `async/await` throughout. Wrap legacy completion-handler APIs with `withCheckedThrowingContinuation` at the boundary; do not propagate completion-handler signatures into new code.
+- Use `Sendable` conformance for types crossing actor boundaries. `actor` for shared mutable state; `MainActor`-isolated types for UI state.
+- Strict typing: no `Any` outside of bridging code. Prefer `some Protocol` (opaque return types) over existential `any Protocol` when the concrete type is known at compile time.
+
+## SwiftUI App Architecture
+
+- Use `@Observable` macro (Swift 5.9+) for view-model state classes; `@Bindable` for two-way binding in views. `ObservableObject` + `@Published` is legacy — migrate during regular refactors.
+- Pick ONE app-state pattern per app and document it in `docs/architecture.md`:
+  - **MV (Model–View) with `@Observable`** — recommended default. View-models are simple `@Observable` classes; views observe by reference.
+  - **TCA (The Composable Architecture)** — when the team wants unidirectional data flow with reducers + effects.
+  - **MVVM with Combine** — when the team already has heavy Combine investment. Avoid in greenfield code.
+- View body is a pure function of state. Never perform side effects in `body`; use `.task { ... }` or `.onChange(of:) { ... }` modifiers.
+- Compose small `View` types — a view exceeding 200 lines is a refactor signal. Extract subviews and use `@ViewBuilder` for conditional content.
+
+## Navigation
+
+- Use `NavigationStack` (iOS 16+) with path-driven navigation: bind a `[Destination]` path to the stack and push routes by appending to the array. `NavigationView` is deprecated — migrate.
+- Type the navigation destination via `navigationDestination(for:)` modifiers. Avoid `NavigationLink(destination:)` for stack-pushed views — it bypasses path binding.
+- Deep links: parse incoming URLs in the `.onOpenURL { ... }` modifier on the root view and update the navigation path. Test universal links on a real device — simulators do not honor associated-domains entitlements reliably.
+- Sheets and popovers via `.sheet(item:)` with an `Identifiable` payload — never pass a `Bool` and a separate state variable.
+
+## Concurrency
+
+- Long-running work: `Task { ... }` for fire-and-forget, `await Task { ... }.value` for cancelable async work. Always check `Task.isCancelled` inside loops.
+- Detached tasks (`Task.detached`) only when you need to escape MainActor isolation; document why in a comment. They inherit no priority or actor isolation.
+- `TaskGroup` for parallel fan-out: prefer `withThrowingTaskGroup` for error propagation. Limit concurrency explicitly (`group.addTask` with a semaphore) when the workload could overload the network or disk.
+- Use AsyncStream / AsyncSequence for event streams. Wrap delegate-based APIs (CLLocationManager, etc.) with `AsyncStream.makeStream(of:)` rather than maintaining ad-hoc callback caches.
+
+## Modular Architecture
+
+- Swift Package Manager (SPM) is the dependency floor. Vendor packages via local Swift packages, not CocoaPods or Carthage (both in maintenance for new projects).
+- Project structure (Tuist or hand-rolled):
+  - `App/` — main app target (UI + composition root only).
+  - `Features/<Feature>/` — feature modules, each its own SwiftPM target.
+  - `Core/` — shared utilities, networking, persistence.
+- Each feature module exports a public API via `public` types; everything else is `internal`. Cross-feature imports go through `Core/` interfaces.
+- Tuist (`Project.swift`, `Workspace.swift`) for multi-target projects above 5 modules. Hand-managed `.xcodeproj` files are merge-conflict prone — Tuist regenerates them deterministically.
+
+## Performance
+
+- Profile with Instruments (Time Profiler, Allocations, SwiftUI). Target 60fps on the oldest supported device class.
+- Avoid heavy work in `View.body`. Cache derived values with `@State` initialized via `init` or compute once in `.task { ... }`.
+- Lists: `List` with stable `Identifiable` IDs and `id: \.id` explicit key paths. Use `LazyVStack` inside `ScrollView` for non-Sectioned lists.
+- Images: `AsyncImage` for network images, `Image(systemName:)` for SF Symbols. For high-frequency reload, use `nuke` or `Kingfisher` with disk cache configured.
+- View identity: stable IDs prevent SwiftUI from re-creating views on every state change. `ForEach(items, id: \.id)` — never use `ForEach(items.indices)` for mutable arrays.
+
+## Accessibility
+
+- Every interactive view has an `.accessibilityLabel(_:)`, `.accessibilityHint(_:)`, and an appropriate `.accessibilityIdentifier(_:)` for UI tests.
+- Group decorative views with `.accessibilityElement(children: .ignore)` so VoiceOver does not stop on every visual element.
+- Dynamic Type: prefer `.font(.body)` and the semantic font modifiers over fixed-point sizes. Test with the largest accessibility size (`accessibility5`).
+- Reduced Motion: gate animations on `@Environment(\.accessibilityReduceMotion)` — disable parallax, springy bounces, and decorative transitions when set.
+
+## Testing
+
+- Unit tests with XCTest (`*Tests/`). Use `swift-testing` (Swift 6) for new test suites when you need parameterized tests, traits, or parallel execution semantics.
+- UI tests with XCUITest under `*UITests/`. Use accessibility identifiers for query stability — never use text labels for selectors.
+- Snapshot tests via `swift-snapshot-testing` (pointfreeco) for SwiftUI view regressions. Configure per-device snapshots in CI.
+- Mock HTTP with `URLProtocol` subclass or `swift-openapi-generator` mock transport. Never hit real network in unit tests.
+
+## Builds & Distribution
+
+- Sign with App Store Connect API keys, not Apple ID password. Configure via `xcrun altool --apiKey` or fastlane `app_store_connect_api_key`.
+- Bitcode is removed (Xcode 14+) — do not enable. dSYM archive every release for crash symbolication; upload to Crashlytics / Sentry / TestFlight automatically in CI.
+- App size: enable `SWIFT_OPTIMIZATION_LEVEL=-O` for release builds. Track size via `xcodebuild -resultBundlePath` JSON output in CI.
+- TestFlight for beta distribution. Use external groups for QA, internal groups for engineering — never share builds via plain `.ipa` files.
+
+## References
+
+- Swift 6 concurrency: https://www.swift.org/migration/documentation/migrationguide/ (accessed 2026-05-27, official-docs)
+- SwiftUI `@Observable`: https://developer.apple.com/documentation/observation (accessed 2026-05-27, official-docs)
+- NavigationStack: https://developer.apple.com/documentation/swiftui/navigationstack (accessed 2026-05-27, official-docs)
+- swift-testing: https://developer.apple.com/xcode/swift-testing/ (accessed 2026-05-27, official-docs)
+
+## Cross-References
+
+- `rules/hatch3r-component-conventions.md` — four-state surface contract maps to SwiftUI `phase`-based async views.
+- `rules/hatch3r-testing.md` — coverage thresholds and determinism rules apply to XCTest / swift-testing.
+- `rules/hatch3r-accessibility-standards.md` — WCAG mapping for SwiftUI `accessibility*` modifiers.

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

@@ -0,0 +1,115 @@
+---
+id: hatch3r-testability-rule
+type: rule
+description: CQ5 Testability Quality measurement rule — per-feature test-class mandate map, real-deal ratio floor, AI eval coverage, mutation kill rate, specialist routing to hatch3r-testability
+scope: conditional
+globs: "src/**,**/__tests__/**,**/tests/**,**/test/**,**/*.test.*,**/*.spec.*,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
+tags: [review, testing, floor:content-quality]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Testability Quality (CQ5)
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ5 (Testability Quality)
+
+## Scope
+
+This rule binds the CQ5 measurement set across end-user code that hatch3r generates AND the framework's own test tree. It complements (does not duplicate) `rules/hatch3r-testing.md` (broad coverage + determinism + flaky-test policy). This rule owns:
+
+- The per-feature test-class mandate map.
+- The real-deal-first ratio floor.
+- The AI feature eval coverage gate.
+- The mutation-kill-rate gate on critical paths.
+- Specialist routing to `agents/hatch3r-testability.md` (CQ5 reviewer / gate + test authoring).
+
+## Per-Feature Test-Class Mandate Map
+
+Source: pillar CQ5 (see `agents/shared/principles.md`) + `rules/hatch3r-testing.md` mandate table. Every changed feature is classified, and the mandated test class MUST be present. Missing the mandated class is a CRITICAL finding from the specialist.
+
+| Feature class | Mandated test class | Tooling per ecosystem |
+|---------------|---------------------|-----------------------|
+| Parser (input deserialization, file format, protocol) | Fuzz | jazzer.js (JS), libfuzzer (Rust), atheris (Python), Jazzer (JVM) |
+| Payment (settlement, refund, ledger) | Mutation | Stryker (JS/TS), Pitest (JVM), mutmut (Python), mutpy (Python) |
+| RPC boundary (gRPC, GraphQL, REST consumer/provider) | Contract | Pact (cross-language), Schemathesis (OpenAPI), buf curl (protobuf) |
+| State machine (workflow, transition graph) | Property | fast-check (JS/TS), Hypothesis (Python), ScalaCheck (JVM) |
+| UI (component, page render) | Visual regression | Playwright with toHaveScreenshot, Percy, Chromatic, Loki |
+| AI feature (prompt-driven, model-driven) | Golden + adversarial + regression eval | Inspect AI, promptfoo, Anthropic Workbench evals, Braintrust |
+
+## Real-Deal-First Ratio
+
+The floor: ≥80% of integration tests use real services (test database, in-process emulator, sandboxed external API) rather than mocks. Mocks are admitted only with a `// MOCK: <reason>` comment naming a specific reason from this allowlist:
+
+- `// MOCK: External service has no sandbox (vendor confirmed)`
+- `// MOCK: Network unreachable in CI (offline build)`
+- `// MOCK: Time-source isolation (controlled clock)`
+- `// MOCK: Side-effect quarantine (irreversible operation)`
+- `// MOCK: Performance budget (test pack must run <5min)`
+
+Reasons outside the allowlist fail the audit-checklist item 2. Framework-level mock helpers (`vi.mock`, `jest.mock`, `unittest.mock.patch`, `mockito.when`) are detected by import-statement grep against the per-language pattern map.
+
+## AI Feature Eval Coverage
+
+Every AI feature surface (prompt-driven, model-driven, agent-driven) MUST carry three eval sets per `rules/hatch3r-ai-evals.md`, at 100% coverage:
+
+- **Golden set** — known-good inputs with expected outputs; regression marker on every model/prompt change.
+- **Adversarial set** — prompt injections, boundary inputs, malformed payloads; verifies refusal + safe-failure behavior.
+- **Regression set** — historical bug reproductions; ensures fixed bugs stay fixed.
+
+CI wires the evals on prompt/model changes; the CI gate exits non-zero on regression. Hallucination is tracked as an SLI per Anthropic engineering guidance (cited under References on the source rule).
+
+## Mutation Kill Rate
+
+On critical paths (payment, auth, anything labelled `critical` per maturity tier), the mutation kill-rate floor is read from repo config (not from this rule's defaults). Default per-tier floors per CONSTITUTION §6 Decision 4:
+
+| Tier | Mutation kill-rate floor on critical paths |
+|------|--------------------------------------------|
+| solo | Not required |
+| team | ≥60% |
+| scaleup | ≥75% |
+| enterprise | ≥85% |
+
+Tier escalation raises the floor; the previous baseline does not survive without re-measurement. Out-of-cycle floor changes require a documented baseline reset to keep wave-to-wave comparison valid.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Test code added, modified, or removed | `agents/hatch3r-testability.md` (CQ5 reviewer / gate) |
+| New feature in a mandate-map class needs test authoring | `agents/hatch3r-testability.md` (author + gate) |
+| Coverage threshold or test-runner config modified | `agents/hatch3r-testability.md` |
+| AI feature surface added or model/prompt change | `agents/hatch3r-testability.md` + `rules/hatch3r-ai-evals.md` |
+| Mutation kill-rate floor change proposed | `agents/hatch3r-testability.md` with baseline-reset documentation |
+
+The CQ5 specialist authors mandated tests, reviews coverage, and gates releases; `agents/hatch3r-testability.md` writes tests AND measures mandate compliance, blocking releases that miss the floor.
+
+## 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>` = CQ5. The `proof_trace` excerpt is the test-file:line citation + runner-output for the measurement 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`. CQ5 Action per status:
+
+- `CRITICAL`: Block release on mandate-map miss OR AI-eval-coverage <100%.
+- `FINDINGS`: Block merge on real-deal-ratio drop, coverage threshold miss, mutation kill-rate floor breach, or unowned flaky test.
+- `PASS`: Surface in iteration summary.
+
+## When to Invoke
+
+- Every PR that modifies test code, removes tests, or introduces a feature in a mandate-map class.
+- Every Implementer pre-write check — confirms the mandated test class before writing so `agents/hatch3r-testability.md` produces the right shape on first pass.
+- Every Verifier pre-merge gate immediately before `gh pr merge` on protected branches; status must be PASS to allow merge on auth/payment paths.
+- D03 or D22 audit cycles, and any maturity-tier escalation per `hatch3r config maturity`.
+- AI feature release gate before a prompt/model bump ships to production traffic.
+- Quarterly audit on real-deal ratio drift — even with no PRs to test code, mock accretion over time silently degrades the ratio against the 80% floor.
+
+## References
+
+- Pillar CQ5 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The test-coverage-quality audit domain (testability domain).
+- `agents/hatch3r-testability.md` (CQ5 reviewer / gate).
+- `agents/hatch3r-testability.md` (CQ5 test-authoring + gate agent — single owner).
+- `rules/hatch3r-testing.md` (broad coverage + determinism + flaky policy).
+- `rules/hatch3r-ai-evals.md` (golden + adversarial + regression eval requirements).
+- `rules/hatch3r-contract-testing.md` (Pact + Schemathesis pattern).

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

@@ -0,0 +1,110 @@
+---
+description: CQ5 Testability Quality measurement rule — per-feature test-class mandate map, real-deal ratio floor, AI eval coverage, mutation kill rate, specialist routing to hatch3r-testability
+globs: ["src/**", "**/__tests__/**", "**/tests/**", "**/test/**", "**/*.test.*", "**/*.spec.*", "**/vitest.config.*", "**/jest.config.*", "**/cypress.config.*"]
+alwaysApply: false
+precedence: high
+---
+# Testability Quality (CQ5)
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ5 (Testability Quality)
+
+## Scope
+
+This rule binds the CQ5 measurement set across end-user code that hatch3r generates AND the framework's own test tree. It complements (does not duplicate) `rules/hatch3r-testing.md` (broad coverage + determinism + flaky-test policy). This rule owns:
+
+- The per-feature test-class mandate map.
+- The real-deal-first ratio floor.
+- The AI feature eval coverage gate.
+- The mutation-kill-rate gate on critical paths.
+- Specialist routing to `agents/hatch3r-testability.md` (CQ5 reviewer / gate + test authoring).
+
+## Per-Feature Test-Class Mandate Map
+
+Source: pillar CQ5 (see `agents/shared/principles.md`) + `rules/hatch3r-testing.md` mandate table. Every changed feature is classified, and the mandated test class MUST be present. Missing the mandated class is a CRITICAL finding from the specialist.
+
+| Feature class | Mandated test class | Tooling per ecosystem |
+|---------------|---------------------|-----------------------|
+| Parser (input deserialization, file format, protocol) | Fuzz | jazzer.js (JS), libfuzzer (Rust), atheris (Python), Jazzer (JVM) |
+| Payment (settlement, refund, ledger) | Mutation | Stryker (JS/TS), Pitest (JVM), mutmut (Python), mutpy (Python) |
+| RPC boundary (gRPC, GraphQL, REST consumer/provider) | Contract | Pact (cross-language), Schemathesis (OpenAPI), buf curl (protobuf) |
+| State machine (workflow, transition graph) | Property | fast-check (JS/TS), Hypothesis (Python), ScalaCheck (JVM) |
+| UI (component, page render) | Visual regression | Playwright with toHaveScreenshot, Percy, Chromatic, Loki |
+| AI feature (prompt-driven, model-driven) | Golden + adversarial + regression eval | Inspect AI, promptfoo, Anthropic Workbench evals, Braintrust |
+
+## Real-Deal-First Ratio
+
+The floor: ≥80% of integration tests use real services (test database, in-process emulator, sandboxed external API) rather than mocks. Mocks are admitted only with a `// MOCK: <reason>` comment naming a specific reason from this allowlist:
+
+- `// MOCK: External service has no sandbox (vendor confirmed)`
+- `// MOCK: Network unreachable in CI (offline build)`
+- `// MOCK: Time-source isolation (controlled clock)`
+- `// MOCK: Side-effect quarantine (irreversible operation)`
+- `// MOCK: Performance budget (test pack must run <5min)`
+
+Reasons outside the allowlist fail the audit-checklist item 2. Framework-level mock helpers (`vi.mock`, `jest.mock`, `unittest.mock.patch`, `mockito.when`) are detected by import-statement grep against the per-language pattern map.
+
+## AI Feature Eval Coverage
+
+Every AI feature surface (prompt-driven, model-driven, agent-driven) MUST carry three eval sets per `rules/hatch3r-ai-evals.md`, at 100% coverage:
+
+- **Golden set** — known-good inputs with expected outputs; regression marker on every model/prompt change.
+- **Adversarial set** — prompt injections, boundary inputs, malformed payloads; verifies refusal + safe-failure behavior.
+- **Regression set** — historical bug reproductions; ensures fixed bugs stay fixed.
+
+CI wires the evals on prompt/model changes; the CI gate exits non-zero on regression. Hallucination is tracked as an SLI per Anthropic engineering guidance (cited under References on the source rule).
+
+## Mutation Kill Rate
+
+On critical paths (payment, auth, anything labelled `critical` per maturity tier), the mutation kill-rate floor is read from repo config (not from this rule's defaults). Default per-tier floors per CONSTITUTION §6 Decision 4:
+
+| Tier | Mutation kill-rate floor on critical paths |
+|------|--------------------------------------------|
+| solo | Not required |
+| team | ≥60% |
+| scaleup | ≥75% |
+| enterprise | ≥85% |
+
+Tier escalation raises the floor; the previous baseline does not survive without re-measurement. Out-of-cycle floor changes require a documented baseline reset to keep wave-to-wave comparison valid.
+
+## Specialist Agent Routing
+
+| Trigger | Route to |
+|---------|----------|
+| Test code added, modified, or removed | `agents/hatch3r-testability.md` (CQ5 reviewer / gate) |
+| New feature in a mandate-map class needs test authoring | `agents/hatch3r-testability.md` (author + gate) |
+| Coverage threshold or test-runner config modified | `agents/hatch3r-testability.md` |
+| AI feature surface added or model/prompt change | `agents/hatch3r-testability.md` + `rules/hatch3r-ai-evals.md` |
+| Mutation kill-rate floor change proposed | `agents/hatch3r-testability.md` with baseline-reset documentation |
+
+The CQ5 specialist authors mandated tests, reviews coverage, and gates releases; `agents/hatch3r-testability.md` writes tests AND measures mandate compliance, blocking releases that miss the floor.
+
+## 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>` = CQ5. The `proof_trace` excerpt is the test-file:line citation + runner-output for the measurement 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`. CQ5 Action per status:
+
+- `CRITICAL`: Block release on mandate-map miss OR AI-eval-coverage <100%.
+- `FINDINGS`: Block merge on real-deal-ratio drop, coverage threshold miss, mutation kill-rate floor breach, or unowned flaky test.
+- `PASS`: Surface in iteration summary.
+
+## When to Invoke
+
+- Every PR that modifies test code, removes tests, or introduces a feature in a mandate-map class.
+- Every Implementer pre-write check — confirms the mandated test class before writing so `agents/hatch3r-testability.md` produces the right shape on first pass.
+- Every Verifier pre-merge gate immediately before `gh pr merge` on protected branches; status must be PASS to allow merge on auth/payment paths.
+- D03 or D22 audit cycles, and any maturity-tier escalation per `hatch3r config maturity`.
+- AI feature release gate before a prompt/model bump ships to production traffic.
+- Quarterly audit on real-deal ratio drift — even with no PRs to test code, mock accretion over time silently degrades the ratio against the 80% floor.
+
+## References
+
+- Pillar CQ5 (measurement set + specialist owner; see `agents/shared/principles.md`).
+- The test-coverage-quality audit domain (testability domain).
+- `agents/hatch3r-testability.md` (CQ5 reviewer / gate).
+- `agents/hatch3r-testability.md` (CQ5 test-authoring + gate agent — single owner).
+- `rules/hatch3r-testing.md` (broad coverage + determinism + flaky policy).
+- `rules/hatch3r-ai-evals.md` (golden + adversarial + regression eval requirements).
+- `rules/hatch3r-contract-testing.md` (Pact + Schemathesis pattern).

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

@@ -2,7 +2,8 @@
 id: hatch3r-testing
 type: rule
 description: Coverage thresholds, mocking strategy, property-based testing, mutation-score targets, flaky test quarantine, and snapshot test discipline
-scope: "**/*.test.*,**/*.spec.*,**/__tests__/**,**/tests/**,**/test/**,**/*.cy.*,**/playwright/**,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
+scope: conditional
+globs: "**/*.test.*,**/*.spec.*,**/__tests__/**,**/tests/**,**/test/**,**/*.cy.*,**/playwright/**,**/vitest.config.*,**/jest.config.*,**/cypress.config.*"
 tags: [review, orchestration]
 precedence: high
 quality_charter: agents/shared/quality-charter.md
@@ -187,6 +188,8 @@ Reviewers verify each PR satisfies the required test classes for the code class
 | LLM feature | eval (via `hatch3r-ai-feature`) + unit on adapter + integration on fallback chain |
 | Background job | unit + integration with poison-message handling |
 
+Each edge case enumerated per `rules/hatch3r-edge-case-discipline.md` (and the Edge-Case Ledger from `agents/hatch3r-edge-case-analyst.md`) maps to a required test class in the mandate map above — a feature whose suite exercises only the happy path is a coverage gap.
+
 ## References
 
 - Stryker (mutation testing): https://stryker-mutator.io/

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

@@ -183,6 +183,8 @@ Reviewers verify each PR satisfies the required test classes for the code class
 | LLM feature | eval (via `hatch3r-ai-feature`) + unit on adapter + integration on fallback chain |
 | Background job | unit + integration with poison-message handling |
 
+Each edge case enumerated per `rules/hatch3r-edge-case-discipline.md` (and the Edge-Case Ledger from `agents/hatch3r-edge-case-analyst.md`) maps to a required test class in the mandate map above — a feature whose suite exercises only the happy path is a coverage gap.
+
 ## References
 
 - Stryker (mutation testing): https://stryker-mutator.io/

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

@@ -10,6 +10,8 @@ cache_friendly: true
 ---
 # Theming & Dark Mode
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## Color System
 
 - Define all colors as semantic CSS custom properties (`--color-surface`, `--color-text-primary`, `--color-text-secondary`, `--color-border`, `--color-brand`, `--color-error`, `--color-success`, `--color-warning`).

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

@@ -5,6 +5,8 @@ alwaysApply: false
 ---
 # Theming & Dark Mode
 
+**Pillars:** P2 (Scientific & Practical Quality), CQ1 (UI Quality)
+
 ## Color System
 
 - Define all colors as semantic CSS custom properties (`--color-surface`, `--color-text-primary`, `--color-text-secondary`, `--color-border`, `--color-brand`, `--color-error`, `--color-success`, `--color-warning`).

package/dist/content/rules/hatch3r-tool-currency.md

@@ -0,0 +1,91 @@
+---
+id: hatch3r-tool-currency
+type: rule
+description: CLI-tool version pinning, vendor-release research cadence (≤90 days), CVE feed acknowledgement (≤90 days), and release-readiness gate for any new tool added to src/cliTools/
+scope: conditional
+globs: "src/cliTools/**,skills/hatch3r-cli-*/SKILL.md,.audit-workspace/**"
+tags: [security, currency, maintenance]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# CLI Tool Currency
+
+**Pillars:** P3 (Adapter & External Tool Currency), CQ3 (Security Quality)
+
+## Scope
+
+This rule binds every CLI tool entry in `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` and every per-tool skill under `skills/hatch3r-cli-{id}/SKILL.md`. Tier-1 entries are unconditionally installed; tier-2 entries are conditional per `src/cliTools/triggers.ts`; tier-3 entries are user-opt-in. The currency policy below applies tier-wide; only the staleness threshold varies per tier.
+
+## Vendor-Release Research Cadence
+
+Source of truth: pillar P3 (see `agents/shared/principles.md`) — "vendor changelogs ≤12 months old, CVE feeds ≤90 days old, staleness >90 days for any tier-1 tool is a Medium finding". The CLI-tooling-recency audit domain owns the per-cycle verification.
+
+Per-cycle research-date promotion is required for every tool listed in the registry. The audit workspace `.audit-workspace/current-insights.json::d21_tool_research_dates.{tool_id}` must carry an ISO date ≤90 days from cycle start. Records >120 days from cycle start trigger a regression-gate failure per the audit Regression Gates table.
+
+| Tier | Staleness threshold | Action on breach |
+|------|---------------------|------------------|
+| Tier 1 (unconditional, e.g. `ripgrep`, `fd`, `jq`, `gh`, `delta`) | 90 days | Medium finding; block cycle close until research-date updated |
+| Tier 2 (conditional, e.g. `qsv`, `playwright`, `duckdb`) | 120 days | Medium finding when trigger fires; Info otherwise |
+| Tier 3 (opt-in) | 180 days | Low finding; surface for cycle backlog |
+
+## CVE Feed Acknowledgement
+
+Every cycle MUST inspect the upstream advisory feed for each registered tool:
+
+- GitHub Security Advisories (`https://github.com/{owner}/{repo}/security/advisories`) — primary feed for tools published on GitHub.
+- NVD CVE feed (`https://nvd.nist.gov/vuln/search/results?form_type=Basic&search_type=all&query={tool}`) — backstop for non-GitHub tools.
+- Vendor security mailing lists where the vendor publishes there in preference to GHSA (e.g. `oss-security@lists.openwall.com`).
+
+The `securityNote` field on the registry entry MUST be populated when an unfixed advisory ≤90 days old applies, with the GHSA-id and required mitigation. Existing examples to mirror: `jq` (advisory roster on `jqlang/jq`), `gh` (GHSA-crc3-h8v6-qh57 pre-2.92.0). Missing CVE check is a High finding per CONSTITUTION §2 P3.
+
+## Version Pinning Policy
+
+Registry entries declare install commands per OS / package manager (`brew`, `apt`, `scoop`, `cargo`, etc.). The pinning rules:
+
+- Production CI workflows MUST pin the tool's binary version when the install command supports it (e.g. `brew install jq@1.7`, `cargo install ripgrep --version 14.1.0 --locked`, `gh ext install owner/repo@v1.2.3`).
+- GitHub Actions step entries that consume a CLI tool MUST SHA-pin the action emitting the install (40-char commit SHA), per `rules/hatch3r-secrets-management.md` and CONSTITUTION §2B CQ3 supply-chain floor.
+- Local-developer install commands MAY omit a version pin (homebrew tracks vendor-current); the registry MUST document the last-verified vendor release tag in `lastVendorReleaseTag` (proposal field — populate when adding the tool) so audit cycles can detect drift.
+- A tool whose vendor stops publishing releases (cadence `stable` + last release >18 months) is escalated to D21 SA21.7 for replacement evaluation; the alternative-tool monitor in `src/cliTools/triggers.ts` records candidate replacements.
+
+## Release-Readiness Gate for New Tools
+
+Adding a new tool to `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` MUST satisfy every gate below before the PR merges. The gate set is enforced by the D21 audit checklist and the `validate-cli-skills.ts` CI gate:
+
+1. **Vendor verification** — record the upstream repository URL, current release tag, release date (ISO), and license SPDX identifier on the registry entry.
+2. **Web-research recency** — the audit-workspace research-date for the tool MUST be ≤14 days from PR open date; older research requires re-verification.
+3. **CVE scan** — inspect GHSA + NVD for advisories ≤180 days old; populate `securityNote` if any unfixed advisory matches, else record `null` with a comment citing the search date.
+4. **Skill parity** — a matching `skills/hatch3r-cli-{id}/SKILL.md` with frontmatter (`id`, `type=skill`, `description`, `tags`), Quick Start, and Step pattern exists; `npm run validate:cli-skills` exits 0.
+5. **Tier assignment justification** — the registry entry's `tier` field is documented inline: Tier 1 needs evidence of unconditional value (>80% of recommended workflows); Tier 2 needs at least one named trigger from `Tier2Trigger`; Tier 3 needs a use-case statement.
+6. **Install-command coverage** — install commands present for `mac` / `linux` / `win` keys covering the CI matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`); WSL is treated as `linux`.
+7. **Capability matrix** — `src/adapters/canonical.ts` renders the skill to all 3 adapter outputs (cursor, claude, copilot); the per-adapter render path is tested in `src/__tests__/adapters/{name}.test.ts`.
+8. **Alternative-tool comparison** — the PR body lists at least 2 named alternatives considered (with rejection rationale citing measurable trade-offs); avoids tool-duplication per `rules/hatch3r-anti-duplication.md`.
+9. **Probe binary registration** — the `probe` field on the registry entry names the binary used by `detectInstalled()`; the probe MUST be the exact executable name printed by the install command output (e.g. `rg` for ripgrep, `fd` for fd, `jq` for jq).
+10. **Iteration-summary entry** — the addition emits one row in `rules/hatch3r-iteration-summary.md` §Changes Made with the registry-entry diff link, per the iteration-summary template.
+
+## Removing or Demoting a Tool
+
+A tool moves to `deprecated: true` (proposal field) or out of `AVAILABLE_CLI_TOOLS` only when ALL hold:
+
+- Vendor archived the upstream repository OR last release >24 months AND cadence `stable` no longer holds.
+- A named alternative tool already in the registry covers ≥95% of the same use cases.
+- A documented migration note in `skills/hatch3r-cli-{old}/SKILL.md` points users to the replacement and lists at least 1 example of the replacement command for each top-level recipe.
+
+Demotion is irreversible at the audit-cycle granularity per `rules/hatch3r-clarification-default.md` B1 — confirm with the framework owner via the user-question protocol before merging the PR.
+
+## Cross-Cycle Currency Records
+
+The audit execution-insights store (key `d21_tool_research_dates`) holds the per-cycle research-date promotion log; per pillar P3 and the CLI-tooling-recency domain's SA21.7, the promotion is the only audit artifact that survives between cycles. Wave-level findings in `.audit-workspace/wave-{N}/` are ephemeral.
+
+## D09 + D21 Boundary
+
+The platform-adapters audit domain (D09) audits the per-adapter render of `hatch3r-cli-{id}` skills. The CLI-tooling-recency domain (D21) audits whether the underlying tool registry is current, accurate, and safe. A render-path bug routes to D09; a stale-tool finding routes to D21. Cross-cycle escalation between D09 and D21 happens via the registry-vs-skills drift check in D21 SA21.7 — drift is a Medium finding regardless of which side is out of sync.
+
+## References
+
+- Pillar P3 (currency policy + Decision 21 capability matrix metric; see `agents/shared/principles.md`).
+- Decision 26 (Conventional Commits + supply-chain floor + CI matrix).
+- The CLI-tooling-recency audit domain (per-category sub-agent checklists).
+- `src/cliTools/registry.ts` (`AVAILABLE_CLI_TOOLS` schema + tier definitions + cadence enum).
+- `src/cliTools/triggers.ts` (tier-2 conditional evaluation + alternative-tool monitor).
+- `scripts/validate-cli-skills.ts` (CI gate verifying registry-vs-skill drift).

package/dist/content/rules/hatch3r-tool-currency.mdc

@@ -0,0 +1,86 @@
+---
+description: CLI-tool version pinning, vendor-release research cadence (≤90 days), CVE feed acknowledgement (≤90 days), and release-readiness gate for any new tool added to src/cliTools/
+globs: ["src/cliTools/**", "skills/hatch3r-cli-*/SKILL.md", ".audit-workspace/**"]
+alwaysApply: false
+precedence: high
+---
+# CLI Tool Currency
+
+**Pillars:** P3 (Adapter & External Tool Currency), CQ3 (Security Quality)
+
+## Scope
+
+This rule binds every CLI tool entry in `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` and every per-tool skill under `skills/hatch3r-cli-{id}/SKILL.md`. Tier-1 entries are unconditionally installed; tier-2 entries are conditional per `src/cliTools/triggers.ts`; tier-3 entries are user-opt-in. The currency policy below applies tier-wide; only the staleness threshold varies per tier.
+
+## Vendor-Release Research Cadence
+
+Source of truth: pillar P3 (see `agents/shared/principles.md`) — "vendor changelogs ≤12 months old, CVE feeds ≤90 days old, staleness >90 days for any tier-1 tool is a Medium finding". The CLI-tooling-recency audit domain owns the per-cycle verification.
+
+Per-cycle research-date promotion is required for every tool listed in the registry. The audit workspace `.audit-workspace/current-insights.json::d21_tool_research_dates.{tool_id}` must carry an ISO date ≤90 days from cycle start. Records >120 days from cycle start trigger a regression-gate failure per the audit Regression Gates table.
+
+| Tier | Staleness threshold | Action on breach |
+|------|---------------------|------------------|
+| Tier 1 (unconditional, e.g. `ripgrep`, `fd`, `jq`, `gh`, `delta`) | 90 days | Medium finding; block cycle close until research-date updated |
+| Tier 2 (conditional, e.g. `qsv`, `playwright`, `duckdb`) | 120 days | Medium finding when trigger fires; Info otherwise |
+| Tier 3 (opt-in) | 180 days | Low finding; surface for cycle backlog |
+
+## CVE Feed Acknowledgement
+
+Every cycle MUST inspect the upstream advisory feed for each registered tool:
+
+- GitHub Security Advisories (`https://github.com/{owner}/{repo}/security/advisories`) — primary feed for tools published on GitHub.
+- NVD CVE feed (`https://nvd.nist.gov/vuln/search/results?form_type=Basic&search_type=all&query={tool}`) — backstop for non-GitHub tools.
+- Vendor security mailing lists where the vendor publishes there in preference to GHSA (e.g. `oss-security@lists.openwall.com`).
+
+The `securityNote` field on the registry entry MUST be populated when an unfixed advisory ≤90 days old applies, with the GHSA-id and required mitigation. Existing examples to mirror: `jq` (advisory roster on `jqlang/jq`), `gh` (GHSA-crc3-h8v6-qh57 pre-2.92.0). Missing CVE check is a High finding per CONSTITUTION §2 P3.
+
+## Version Pinning Policy
+
+Registry entries declare install commands per OS / package manager (`brew`, `apt`, `scoop`, `cargo`, etc.). The pinning rules:
+
+- Production CI workflows MUST pin the tool's binary version when the install command supports it (e.g. `brew install jq@1.7`, `cargo install ripgrep --version 14.1.0 --locked`, `gh ext install owner/repo@v1.2.3`).
+- GitHub Actions step entries that consume a CLI tool MUST SHA-pin the action emitting the install (40-char commit SHA), per `rules/hatch3r-secrets-management.md` and CONSTITUTION §2B CQ3 supply-chain floor.
+- Local-developer install commands MAY omit a version pin (homebrew tracks vendor-current); the registry MUST document the last-verified vendor release tag in `lastVendorReleaseTag` (proposal field — populate when adding the tool) so audit cycles can detect drift.
+- A tool whose vendor stops publishing releases (cadence `stable` + last release >18 months) is escalated to D21 SA21.7 for replacement evaluation; the alternative-tool monitor in `src/cliTools/triggers.ts` records candidate replacements.
+
+## Release-Readiness Gate for New Tools
+
+Adding a new tool to `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` MUST satisfy every gate below before the PR merges. The gate set is enforced by the D21 audit checklist and the `validate-cli-skills.ts` CI gate:
+
+1. **Vendor verification** — record the upstream repository URL, current release tag, release date (ISO), and license SPDX identifier on the registry entry.
+2. **Web-research recency** — the audit-workspace research-date for the tool MUST be ≤14 days from PR open date; older research requires re-verification.
+3. **CVE scan** — inspect GHSA + NVD for advisories ≤180 days old; populate `securityNote` if any unfixed advisory matches, else record `null` with a comment citing the search date.
+4. **Skill parity** — a matching `skills/hatch3r-cli-{id}/SKILL.md` with frontmatter (`id`, `type=skill`, `description`, `tags`), Quick Start, and Step pattern exists; `npm run validate:cli-skills` exits 0.
+5. **Tier assignment justification** — the registry entry's `tier` field is documented inline: Tier 1 needs evidence of unconditional value (>80% of recommended workflows); Tier 2 needs at least one named trigger from `Tier2Trigger`; Tier 3 needs a use-case statement.
+6. **Install-command coverage** — install commands present for `mac` / `linux` / `win` keys covering the CI matrix (`ubuntu-latest`, `macos-latest`, `windows-latest`); WSL is treated as `linux`.
+7. **Capability matrix** — `src/adapters/canonical.ts` renders the skill to all 3 adapter outputs (cursor, claude, copilot); the per-adapter render path is tested in `src/__tests__/adapters/{name}.test.ts`.
+8. **Alternative-tool comparison** — the PR body lists at least 2 named alternatives considered (with rejection rationale citing measurable trade-offs); avoids tool-duplication per `rules/hatch3r-anti-duplication.md`.
+9. **Probe binary registration** — the `probe` field on the registry entry names the binary used by `detectInstalled()`; the probe MUST be the exact executable name printed by the install command output (e.g. `rg` for ripgrep, `fd` for fd, `jq` for jq).
+10. **Iteration-summary entry** — the addition emits one row in `rules/hatch3r-iteration-summary.md` §Changes Made with the registry-entry diff link, per the iteration-summary template.
+
+## Removing or Demoting a Tool
+
+A tool moves to `deprecated: true` (proposal field) or out of `AVAILABLE_CLI_TOOLS` only when ALL hold:
+
+- Vendor archived the upstream repository OR last release >24 months AND cadence `stable` no longer holds.
+- A named alternative tool already in the registry covers ≥95% of the same use cases.
+- A documented migration note in `skills/hatch3r-cli-{old}/SKILL.md` points users to the replacement and lists at least 1 example of the replacement command for each top-level recipe.
+
+Demotion is irreversible at the audit-cycle granularity per `rules/hatch3r-clarification-default.md` B1 — confirm with the framework owner via the user-question protocol before merging the PR.
+
+## Cross-Cycle Currency Records
+
+The audit execution-insights store (key `d21_tool_research_dates`) holds the per-cycle research-date promotion log; per pillar P3 and the CLI-tooling-recency domain's SA21.7, the promotion is the only audit artifact that survives between cycles. Wave-level findings in `.audit-workspace/wave-{N}/` are ephemeral.
+
+## D09 + D21 Boundary
+
+The platform-adapters audit domain (D09) audits the per-adapter render of `hatch3r-cli-{id}` skills. The CLI-tooling-recency domain (D21) audits whether the underlying tool registry is current, accurate, and safe. A render-path bug routes to D09; a stale-tool finding routes to D21. Cross-cycle escalation between D09 and D21 happens via the registry-vs-skills drift check in D21 SA21.7 — drift is a Medium finding regardless of which side is out of sync.
+
+## References
+
+- Pillar P3 (currency policy + Decision 21 capability matrix metric; see `agents/shared/principles.md`).
+- Decision 26 (Conventional Commits + supply-chain floor + CI matrix).
+- The CLI-tooling-recency audit domain (per-category sub-agent checklists).
+- `src/cliTools/registry.ts` (`AVAILABLE_CLI_TOOLS` schema + tier definitions + cadence enum).
+- `src/cliTools/triggers.ts` (tier-2 conditional evaluation + alternative-tool monitor).
+- `scripts/validate-cli-skills.ts` (CI gate verifying registry-vs-skill drift).