hatch3r 1.8.0 → 2.0.0

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

@@ -2,8 +2,10 @@
 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.*"
-tags: [core]
+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
 cache_friendly: true
 ---
@@ -186,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/{rules → dist/content/rules}/hatch3r-testing.mdc

@@ -2,6 +2,7 @@
 description: Coverage thresholds, mocking strategy, property-based testing, mutation-score targets, flaky test quarantine, and snapshot test discipline
 globs: ["**/*.test.*", "**/*.spec.*", "**/__tests__/**", "**/tests/**", "**/test/**", "**/*.cy.*", "**/playwright/**", "**/vitest.config.*", "**/jest.config.*", "**/cypress.config.*"]
 alwaysApply: false
+precedence: high
 ---
 # Testing Standards
 
@@ -182,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/{rules → dist/content/rules}/hatch3r-theming.md

@@ -4,12 +4,14 @@ type: rule
 description: Theming, dark mode, and color system conventions for the project
 scope: conditional
 globs: "src/**/*.vue,src/**/*.tsx,src/**/*.jsx,src/**/*.css,src/**/*.scss,**/*theme*,**/*color*"
-tags: [implementation, lang:typescript]
+tags: [implementation, floor:ui-ux, lang:typescript]
 quality_charter: agents/shared/quality-charter.md
 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/{rules → 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).

package/{rules → dist/content/rules}/hatch3r-tooling-hierarchy.md

@@ -2,18 +2,19 @@
 id: hatch3r-tooling-hierarchy
 type: rule
 description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
-scope: "**/.agents/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/.windsurf/**,**/hatch.json,**/.claude/**"
-tags: [core]
+scope: conditional
+globs: "**/.hatch3r/**,**/mcp/**,**/mcp.json,**/.cursor/**,**/.github/copilot*,**/hatch.json,**/.claude/**"
+tags: [orchestration]
 quality_charter: agents/shared/quality-charter.md
 cache_friendly: true
 ---
 # Tooling Hierarchy
 
-## A. Platform MCP-First (when available)
+**Pillars:** P3 (Adapter & External Tool Currency), P7 (Speed & Token Efficiency)
 
-**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
+## A. Platform MCP-First (when available)
 
-Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
+**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations. Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -25,11 +26,7 @@ Read `platform` from `.agents/hatch.json` to determine which platform tools to u
 
 ### Platform CLI Fallback Reference
 
-**Fallback to the platform CLI only when:**
-- The MCP tool catalog lacks the specific capability.
-- An MCP call fails repeatedly and the CLI provides a viable alternative.
-
-**Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
+**Fallback to the platform CLI only when** the MCP tool catalog lacks the capability, or an MCP call fails repeatedly and the CLI provides a viable alternative. **Never** use the CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
@@ -54,17 +51,21 @@ Read `platform` from `.agents/hatch.json` to determine which platform tools to u
 Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
 
 **When to use:**
-- Working with any external dependency.
+- Working with any external dependency, or reviewing code that uses third-party libraries.
 - Verifying API signatures, configuration options, or migration paths.
-- Reviewing code that uses third-party libraries.
-- Writing tests with external test frameworks.
-- Debugging errors from external libraries.
+- Writing tests with external test frameworks, or debugging errors from external libraries.
 
 **When NOT to use:**
 - Internal project specs — use project docs.
 - Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
 - General programming concepts not tied to a specific library.
 
+**Fallback when documentation MCP is unavailable:**
+If no documentation MCP server (e.g., Context7) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Fall back to web research (§C) for the library's official docs, then read the installed version's type definitions in `node_modules` (or the language equivalent).
+- Note in your output when a version-specific lookup would have been valuable (e.g., "Context7 lookup recommended for the express@5 migration but not available").
+- Do NOT assert API signatures from memory — flag any unverified third-party API as needing confirmation.
+
 ## C. Web Research for External Context
 
 Use web search to retrieve current, real-world information not available in project docs or library documentation.
@@ -72,20 +73,17 @@ Use web search to retrieve current, real-world information not available in proj
 **When to use:**
 - Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
 - Breaking changes or deprecations in upcoming dependency versions.
-- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Current best practices for architecture, deployment, or tooling, including comparing alternatives against current community consensus.
 - Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
-- Comparing alternative approaches or tools with current community consensus.
 
 **When NOT to use:**
 - Questions answerable from project specs or codebase exploration.
-- Standard library API questions (use documentation MCP instead).
-- Internal project decisions (use project ADRs).
+- Standard library API questions (use documentation MCP instead), or internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.agents/hatch.json`), web research cannot be performed. In this case:
-- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
+If no web search MCP server (e.g., `brave-search`) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available"), and flag security-sensitive decisions that would benefit from current advisory data.
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
-- Flag security-sensitive decisions that would benefit from current advisory data.
 - Do NOT silently skip web research — surface the limitation so the user can decide whether to enable it.
 
 ## D. Browser Verification for UI Changes
@@ -96,26 +94,26 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 - Verifying UI component changes render as specified in the design or acceptance criteria.
 - Reproducing and confirming fixes for visually observable bugs.
 - Accessibility auditing (keyboard nav, contrast, focus indicators).
-- Frontend performance profiling (CPU, frame rate, memory).
-- Capturing screenshot evidence for PRs.
+- Frontend performance profiling (CPU, frame rate, memory), and capturing screenshot evidence for PRs.
 
 **When NOT to use:**
 - Pure backend or API changes with no visual impact.
 - Configuration or infrastructure changes.
 - Code refactors that do not alter rendered output.
 
-**Available tools:**
-- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
-- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+**Fallback when browser MCP is unavailable:**
+If no browser automation MCP server is configured, defer interactive verification:
+- For accessibility, run an in-process axe-core check (`@axe-core/playwright`, `jest-axe`, or `axe-core` in a jsdom test) in the test suite to catch violations without a live browser.
+- Note in your output that visual/UI confirmation was skipped and recommend manual review before merge — do NOT silently skip it.
+
+**Available tools:** IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor); Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
 
 ## E. Knowledge Augmentation Priority
 
-When seeking information, follow this priority order:
+When seeking information, follow this priority order, combining sources when valuable (e.g., read the spec, then verify external API usage with docs MCP, then check for recent advisories via web research):
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
-3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+2. **Codebase exploration** (code search, semantic code search) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns. Falls back to web research + installed type definitions when unavailable (§B).
 4. **Web research** — current events, best practices, security advisories, novel problems.
-5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
-
-Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass; falls back to in-process axe-core for a11y when unavailable (§D).

package/{rules → dist/content/rules}/hatch3r-tooling-hierarchy.mdc

@@ -1,15 +1,15 @@
 ---
 description: Platform MCP-first priority, documentation MCP for library APIs, web research for CVEs, and browser MCP for UI verification with fallback guidance
-globs: ["**/.agents/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/.windsurf/**", "**/hatch.json", "**/.claude/**"]
+globs: ["**/.hatch3r/**", "**/mcp/**", "**/mcp.json", "**/.cursor/**", "**/.github/copilot*", "**/hatch.json", "**/.claude/**"]
 alwaysApply: false
 ---
 # Tooling Hierarchy
 
-## A. Platform MCP-First (when available)
+**Pillars:** P3 (Adapter & External Tool Currency), P7 (Speed & Token Efficiency)
 
-**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations.
+## A. Platform MCP-First (when available)
 
-Read `platform` from `.agents/hatch.json` to determine which platform tools to use.
+**Prefer platform MCP tools over the platform CLI** when the MCP server provides typed tools with structured input/output. Use them as the primary interface for issue tracker and repository operations. Read `platform` from `.hatch3r/hatch.json` to determine which platform tools to use.
 
 ### Prerequisites
 
@@ -21,11 +21,7 @@ Read `platform` from `.agents/hatch.json` to determine which platform tools to u
 
 ### Platform CLI Fallback Reference
 
-**Fallback to the platform CLI only when:**
-- The MCP tool catalog lacks the specific capability.
-- An MCP call fails repeatedly and the CLI provides a viable alternative.
-
-**Never** use the platform CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
+**Fallback to the platform CLI only when** the MCP tool catalog lacks the capability, or an MCP call fails repeatedly and the CLI provides a viable alternative. **Never** use the CLI for operations that have a direct MCP equivalent (issue CRUD, PR/MR CRUD, search, labels).
 
 | Action | GitHub | Azure DevOps | GitLab |
 |--------|--------|--------------|--------|
@@ -50,17 +46,21 @@ Read `platform` from `.agents/hatch.json` to determine which platform tools to u
 Use documentation MCP (e.g., Context7) to retrieve up-to-date, version-specific documentation for external libraries and frameworks. This prevents hallucinated APIs and outdated patterns.
 
 **When to use:**
-- Working with any external dependency.
+- Working with any external dependency, or reviewing code that uses third-party libraries.
 - Verifying API signatures, configuration options, or migration paths.
-- Reviewing code that uses third-party libraries.
-- Writing tests with external test frameworks.
-- Debugging errors from external libraries.
+- Writing tests with external test frameworks, or debugging errors from external libraries.
 
 **When NOT to use:**
 - Internal project specs — use project docs.
 - Internal codebase patterns — use Grep, SemanticSearch, or exploration tools.
 - General programming concepts not tied to a specific library.
 
+**Fallback when documentation MCP is unavailable:**
+If no documentation MCP server (e.g., Context7) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Fall back to web research (§C) for the library's official docs, then read the installed version's type definitions in `node_modules` (or the language equivalent).
+- Note in your output when a version-specific lookup would have been valuable (e.g., "Context7 lookup recommended for the express@5 migration but not available").
+- Do NOT assert API signatures from memory — flag any unverified third-party API as needing confirmation.
+
 ## C. Web Research for External Context
 
 Use web search to retrieve current, real-world information not available in project docs or library documentation.
@@ -68,20 +68,17 @@ Use web search to retrieve current, real-world information not available in proj
 **When to use:**
 - Latest security advisories, CVEs, or vulnerability disclosures for dependencies.
 - Breaking changes or deprecations in upcoming dependency versions.
-- Current best practices for architecture patterns, deployment strategies, or tooling.
+- Current best practices for architecture, deployment, or tooling, including comparing alternatives against current community consensus.
 - Novel problems with no match in docs (e.g., obscure error messages, platform-specific quirks).
-- Comparing alternative approaches or tools with current community consensus.
 
 **When NOT to use:**
 - Questions answerable from project specs or codebase exploration.
-- Standard library API questions (use documentation MCP instead).
-- Internal project decisions (use project ADRs).
+- Standard library API questions (use documentation MCP instead), or internal project decisions (use project ADRs).
 
 **Fallback when web search is unavailable:**
-If no web search MCP server is configured (e.g., `brave-search` is not in `mcp.servers` in `.agents/hatch.json`), web research cannot be performed. In this case:
-- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available").
+If no web search MCP server (e.g., `brave-search`) is in `mcp.servers` in `.hatch3r/hatch.json`:
+- Note in your output when web research would have been valuable (e.g., "Web research recommended for CVE verification but not available"), and flag security-sensitive decisions that would benefit from current advisory data.
 - Rely more heavily on Context7 documentation MCP and codebase exploration.
-- Flag security-sensitive decisions that would benefit from current advisory data.
 - Do NOT silently skip web research — surface the limitation so the user can decide whether to enable it.
 
 ## D. Browser Verification for UI Changes
@@ -92,26 +89,26 @@ Use browser automation MCP tools to visually verify UI changes after automated t
 - Verifying UI component changes render as specified in the design or acceptance criteria.
 - Reproducing and confirming fixes for visually observable bugs.
 - Accessibility auditing (keyboard nav, contrast, focus indicators).
-- Frontend performance profiling (CPU, frame rate, memory).
-- Capturing screenshot evidence for PRs.
+- Frontend performance profiling (CPU, frame rate, memory), and capturing screenshot evidence for PRs.
 
 **When NOT to use:**
 - Pure backend or API changes with no visual impact.
 - Configuration or infrastructure changes.
 - Code refactors that do not alter rendered output.
 
-**Available tools:**
-- IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor).
-- Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
+**Fallback when browser MCP is unavailable:**
+If no browser automation MCP server is configured, defer interactive verification:
+- For accessibility, run an in-process axe-core check (`@axe-core/playwright`, `jest-axe`, or `axe-core` in a jsdom test) in the test suite to catch violations without a live browser.
+- Note in your output that visual/UI confirmation was skipped and recommend manual review before merge — do NOT silently skip it.
+
+**Available tools:** IDE-native browser MCP (e.g., `cursor-ide-browser` in Cursor); Playwright MCP (`@anthropic/mcp-playwright`) for cross-editor browser automation.
 
 ## E. Knowledge Augmentation Priority
 
-When seeking information, follow this priority order:
+When seeking information, follow this priority order, combining sources when valuable (e.g., read the spec, then verify external API usage with docs MCP, then check for recent advisories via web research):
 
 1. **Project specs and ADRs** — authoritative for project-specific behavior, constraints, and decisions.
-2. **Codebase exploration** (code search tools, semantic code search) — ground truth for current implementation.
-3. **Documentation MCP** — authoritative for external library/framework APIs and patterns.
+2. **Codebase exploration** (code search, semantic code search) — ground truth for current implementation.
+3. **Documentation MCP** — authoritative for external library/framework APIs and patterns. Falls back to web research + installed type definitions when unavailable (§B).
 4. **Web research** — current events, best practices, security advisories, novel problems.
-5. **Browser verification** — visual confirmation of UI changes after automated tests pass.
-
-Combine sources when valuable: read the spec first, then verify external API usage with docs MCP, then check for recent advisories via web research.
+5. **Browser verification** — visual confirmation of UI changes after automated tests pass; falls back to in-process axe-core for a11y when unavailable (§D).