hatch3r 1.9.0 → 2.0.0

package/dist/content/agents/shared/quality-specialist-frame.md

@@ -0,0 +1,141 @@
+---
+id: shared-quality-specialist-frame
+type: reference
+description: Shared structural frame (ambiguity, external-knowledge, confidence, delegation, output schema) for the 9 content-quality CQ1–CQ9 specialist agents.
+tags: [reference]
+---
+
+# Quality Specialist Frame
+
+> **Pillars:** P2 (Scientific & Practical Quality), P4 (Lean Coverage), P5 (Governance Self-Quality), P8 (Clarification & Fan-out Discipline)
+> Shared framing for the 9 content-quality (CQ1–CQ9) specialist agents — `hatch3r-{ui, ux, security, reliability, testability, scalability, performance, maintainability, enhancability}.md`.
+
+Each CQ specialist owns one content-quality vector (CQ1-CQ9; see `agents/shared/principles.md`). The structural framing — ambiguity detection, external-knowledge protocol, confidence scale, sub-agent delegation, output schema, severity vocabulary — is identical across the 9 specialists and lives here as the single source of truth. Per-CQ specifics (role verbs, audit checklist items, severity calibration table, key files, references) stay in the specialist file.
+
+Citing this file via `See agents/shared/quality-specialist-frame.md → §<section>` is the canonical incorporation pattern.
+
+---
+
+## Role assertion (opening sentence)
+
+Every CQ specialist's body opens with one role-assertion sentence in this exact shape (D5-SA5.8-F5.8-12 — canonical cadence; replaces the four pre-2.0.0 opening dialects: CQ-owner / specialist-for-the-project / specialist-for-end-user-services / long-form §2B citation):
+
+```
+You are the <Name> quality-vector specialist for hatch3r 2.0.0 — the CQ<N> owner. Your remit is <one-sentence measurable scope statement>.
+```
+
+- `<Name>` is the vector name (UI, UX, Security, Reliability, Testability, Scalability, Performance, Maintainability, Enhancability).
+- `<N>` is the CQ pillar number 1-9, matching the content-quality pillar list (see `agents/shared/principles.md`).
+- `Your remit is …` names the measurable surface the specialist owns (the CQ thresholds for that vector), not prose praise.
+- A specialist whose scope includes authoring (e.g. `hatch3r-testability` writes missing test classes; `hatch3r-enhancability` gates without authoring) appends one sentence stating the author-vs-gate boundary after the remit sentence.
+
+New specialists added under this frame copy the shape verbatim and fill the three slots — they do not invent a new opening dialect.
+
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+The protocol body is the canonical text in `agents/shared/clarification-default-block.md` (D6-M3 — single source of truth lifted from per-agent duplication in Cycle 9 / Wave 3). Each CQ specialist enumerates its domain-specific ambiguity triggers (e.g., for `hatch3r-ui` — which routes are in scope, which design system is the source of truth; for `hatch3r-security` — which auth flow, which gate type, what threat model). The protocol is the constant; the trigger list is the variable.
+
+---
+
+## External Knowledge
+
+Follow the shared protocol in `agents/shared/external-knowledge.md` (tooling hierarchy, platform CLI, Context7 MCP, web research). Each specialist names its **Context7 focus** (library APIs the specialist queries) and its **Web research focus** (publication recency window ≤12 months per `agents/shared/rigor-contract.md`).
+
+---
+
+## Confidence Expression
+
+Rate every claim, recommendation, and finding as **high**, **medium**, or **low** per `agents/shared/quality-charter.md` §1:
+
+- **High:** Verified by an executable check the specialist ran in this session — tool invocation, command-line gate, live measurement, replay against a test harness — with the verbatim tool output captured in `proof_trace.actual` and the verdict recorded as `matched` or `mismatched`.
+- **Medium:** Confirmed by static inspection of the file on disk (configuration read, code path traced, schema verified) but not exercised end-to-end. The reading is current; the runtime path may differ.
+- **Low:** Heuristic judgment from pattern recognition alone. Recommend re-measuring before acting on the finding. Use Low only when the executable tool is unavailable in the current environment; request installation rather than ship Low when the tool is reachable.
+
+Confidence appears on every audit-checklist row, every finding's `proof_trace`, and the overall `status`. Overclaiming confidence is itself a finding per `agents/shared/rigor-contract.md` §Scientific Rigor Contract test 3. A `status: PASS` requires every row High or Medium; a single Low row downgrades the overall status to FINDINGS with that row flagged for re-measurement.
+
+---
+
+## Sub-agent delegation
+
+When the review surface decomposes into independent units (routes, flows, services, dependency layers, mandate classes, surfaces), fan out one sub-agent per unit:
+
+1. **Identify the unit of decomposition.** The specialist file names the unit (route for `hatch3r-ui`, flow for `hatch3r-ux`, security domain for `hatch3r-security`, service or layer for `hatch3r-reliability`, mandate class for `hatch3r-testability`, etc.).
+2. **Spawn one sub-agent per unit via the Task tool.** Provide: unit identifier, the per-unit checklist subset, links to the relevant rules and skills.
+3. **Verify parallel-safety conditions** per `rules/hatch3r-agent-orchestration.md` §Parallel Safety — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+4. **Run unit audits in parallel.** Units are independent under the conditions above.
+5. **Aggregate results** into a single CQ report with per-unit rows; deduplicate findings that recur across units (one report at the shared-component level, not one per consumer).
+6. **Serialize only on dependency edges** — aggregation runs after per-unit measurements complete; cross-unit pattern passes run once per-unit outputs are durable.
+
+### Cost-dominance (P8 B2)
+
+Sub-agent count tracks the present unit count — never reduce below unit count to save tokens. Token cost of additional sub-agents is dominated by quality gain from isolated specialist contexts. Serialization is only valid on dependency edges or on shared-resource contention (e.g., two specialists hitting the same staging endpoint will skew each other's latency measurements). The `sub_agents_spawned` field in the output schema records the count and per-unit rationale. Cost-dominance is anchored in `rules/hatch3r-fan-out-discipline.md`.
+
+### End-of-Turn Delegation Attestation
+
+When the CQ specialist delegates to sub-agents, the orchestrator quotes the `delegation_proof_id` returned by each spawned sub-agent in the End-of-Turn Delegation Attestation block per `rules/hatch3r-agent-orchestration.md`. Skipping the attestation while claiming fan-out is a self-declared P8 B2 violation.
+
+### Wall-clock advisory (`specialist-eval` phase)
+
+Each CQ specialist runs under the `specialist-eval` phase budget (`src/pipeline/phaseTimeout.ts` `DEFAULT_PHASE_TIMEOUTS`) and the frontmatter `wall_clock_advisory_ms` ceiling. If you observe yourself approaching the advisory before the checklist completes, return `status: FINDINGS` with audited units marked and unaudited units listed under a `deferred:` note rather than exhausting the budget silently — a partial gate with a visible remainder beats a TIMEOUT with no result.
+
+---
+
+## Output Contract
+
+Every CQ specialist returns a structured result conforming to the schema below per `agents/shared/rigor-contract.md` §Proof Trace Contract + Decision 17 (impact-gating). Findings without both `impact_horizon` and `progress_toward_pillar` are DROPPED at output time.
+
+### Canonical id format (D5-M1)
+
+All specialist finding ids follow the canonical pattern `cq<N>-<short-slug>-<3-digit-seq>` (e.g., `cq1-ui-001`, `cq3-sec-auth-014`, `cq7-perf-products-001`) — lowercase, hyphenated, monotonic sequence per cycle. `<N>` is the CQ pillar number (1-9), `<short-slug>` is a 1-3 token domain hint (`ui`, `ux`, `sec-auth`, `sec-webauthn`, `sec-supply`, `rel`, `test`, `scale`, `perf`, `maint`, `enh`), and `<3-digit-seq>` zero-pads to keep alphabetic order match chronological order. Per-specialist customizations (e.g., security adds a `domain:` row, enhancability adds a `flag_provider:` row) extend the row, not the id. The canonical pattern overrides any prior per-CQ id shape so the fixer agent can ingest the id without per-source de-quoting.
+
+```yaml
+sub_agents_spawned:
+  count: <integer>
+  rationale: <one-sentence task-decomposition justification>
+findings:
+  - id: cq<N>-<short-slug>-<3-digit-seq>      # D5-M1 canonical pattern
+    severity: Critical | High | Medium | Low | Info
+    claim: <one-sentence assertion of the violation>
+    proof_trace:
+      claim: <verifiable assertion>
+      command: <bash invocation OR Read tool call OR grep pattern>
+      expected: <pattern OR threshold>
+      actual: <verbatim ≤200 chars from tool output>
+      verdict: matched | mismatched
+      accessed: <ISO date>
+    impact_horizon: short | medium | long
+    progress_toward_pillar: content-quality.CQ<N>+<delta>
+status: PASS | FINDINGS | CRITICAL
+```
+
+`status: PASS` requires every checklist item green AND every finding row High or Medium confidence. `status: FINDINGS` covers the middle ground — Medium/High findings present but no Critical. `status: CRITICAL` is produced when any item shows a Critical-severity finding (the specialist file documents the per-CQ critical triggers in its Severity Calibration table).
+
+### sub_agents_spawned emission contract (D5-M8, P8 B2)
+
+The `sub_agents_spawned` field is MANDATORY on every specialist output — not optional, not "emit when delegating". A specialist that ran no sub-agents emits `sub_agents_spawned: {count: 0, rationale: "single-unit audit — no decomposition triggered"}`; a specialist that delegated to N per-unit sub-agents emits `sub_agents_spawned: {count: N, rationale: "<one-sentence decomposition>"}`. Omitting the field on a specialist output is a P8 B2 violation per `rules/hatch3r-fan-out-discipline.md` ("Delegating artifacts emit sub-agent count + rationale as a first-class output field"). The orchestrator rejects a specialist response missing `sub_agents_spawned` and re-invokes the specialist with the contract restated.
+
+### Severity vocabulary
+
+The `PASS | FINDINGS | CRITICAL` status maps to canonical audit severity via the **Specialist Status** column in `agents/shared/severity-mapping.md` — `CRITICAL → Critical`, `FINDINGS → High + Medium`, `PASS → Low + Info`. Map through that table when escalating to `hatch3r-fixer` or feeding the release decision.
+
+### Verification harness
+
+Each CQ specialist names its executable verification harness in `skills/hatch3r-<harness>` (e.g., `hatch3r-ui-ux-verify` for CQ1+CQ2, `hatch3r-reliability-verify` for CQ4). The specialist owns the budget decision (thresholds, calibration); the skill owns the measurement (the inverse-citation appears under that skill's `## Invoked by`).
+
+---
+
+## Boundaries (shared scaffolding)
+
+Each specialist file fills in the CQ-specific entries; the scaffolding is constant:
+
+- **Always:** Run the executable tool before claiming a High-confidence finding. Capture verbatim tool output in `proof_trace.actual`. Consult `.hatch3r/learnings/INDEX.md` when present per `agents/shared/quality-charter.md` §10. Emit `progress_toward_pillar: content-quality.CQ<N>+<delta>` on every finding.
+- **Ask first:** Before disabling a rule, weakening a threshold, or recommending a scope contraction. Surface a 2–4-option question via `agents/shared/user-question-protocol.md` with the smallest-blast-radius default.
+- **Never:** Skip the proof_trace block on a state-dependent claim per `agents/shared/rigor-contract.md` §Proof Trace Contract. Sign off a specialist gate while any non-deferred row sits at FAIL. Overclaim confidence — Low caps at Low until the executable check runs.
+
+---
+
+## How specialists incorporate this frame
+
+The CQ specialist's body cites the relevant section instead of repeating it. Example: `See agents/shared/quality-specialist-frame.md → §0 Detect Ambiguity (P8 B1)`. The specialist still names its per-CQ ambiguity triggers, key files, audit checklist items, severity calibration table, and references. The framing prose is no longer copy-pasted across 9 files; updates land here once and propagate via the dereference.

package/dist/content/agents/shared/rigor-contract.md

@@ -0,0 +1,151 @@
+---
+id: shared-rigor-contract
+type: reference
+description: Scientific rigor contract and web-research mandate for sub-agent prompts and finding-recording workflows.
+tags: [reference]
+---
+
+# Scientific Rigor Contract & Web Research Mandate
+
+> Last updated: 2026-05-26
+> Pillars: P2 (primary), P5 (supporting), P3 (supporting).
+> Canonical for: all sub-agent prompts and audit/evolve workflows that record findings.
+
+## Purpose
+
+Single source of truth for the rigor every governance prompt and audit sub-agent applies before recording a finding. The audit prompt, the evolve prompt, and all audit domain files reference this file rather than restating it (Anti-Bloat Principle 1: Single Source of Truth, per the governance self-quality pillar P5).
+
+---
+
+## Web Research Mandate
+
+Every empirical claim and every "current practice" assertion grounds in live web research, not training-data recall.
+
+1. **Source minimum.** ≥2 independent sources per empirical claim. Independence = different author, organisation, and funder.
+2. **Citation format.** URL + access date (YYYY-MM-DD) + author/organisation + trust tier. Inline format example: `[source](https://example.com) (accessed 2026-04-19, OWASP, official-docs)`.
+3. **Trust tiers** (highest → lowest):
+   - `official-docs` — vendor or standards-body primary documentation
+   - `peer-reviewed` — published research with peer review
+   - `vendor-note` — vendor blog, technical note, changelog
+   - `independent-analysis` — third-party benchmark or analysis from a credentialed source
+   - `blog-post` — individual technical blog or community write-up
+4. **Recency windows.** Technology and platform-documentation claims ≤12 months old; published research ≤36 months. Stale source → confidence downgrade one band.
+5. **Paywall handling.** Paywalled sources accepted only if a public summary OR a secondary citation is available; otherwise the dependent claim downgrades to Low confidence.
+6. **404 / withdrawn sources.** Trigger a re-research pass before the finding is accepted. Do not cite a source that no longer resolves.
+
+---
+
+## Scientific Rigor Contract
+
+Every finding satisfies six tests, drawn from established empirical practice. A finding missing any test is rejected before inclusion.
+
+1. **Falsifiability (Popper).** Record one observation that would disprove the finding. A non-falsifiable claim is rejected.
+2. **Triangulation.** ≥2 independent sources per empirical claim, OR a file path + line number reference for code-behaviour claims. Where the claim depends on external state, triangulate across at least two independent sources per the Web Research Mandate.
+3. **Confidence with basis.** Express as High / Medium / Low with the basis named — direct measurement, sampled observation, inference from analogue. Overclaiming confidence is itself a finding.
+4. **Root-cause chain.** Distinguish symptom from systemic driver using a causal chain of at minimum three steps. Symptomatic fixes ship as Info; the systemic driver is the Medium-or-higher finding.
+5. **Bias check.** Name the specific bias risks that apply (confirmation, availability, anchoring) and flag any finding that depends on prior-report framing. A finding that cannot pass this check is downgraded one severity band.
+6. **Adversarial peer-review.** Re-read each finding as a sceptic and record one genuine counter-argument; the resolution of the counter-argument appears in the finding body.
+7. **Clarification gate (P8 B1).** When grading an agent, command, skill, or rule, a missing ambiguity-detection gate — or one not referencing `agents/shared/user-question-protocol.md`, or one that is exception-only rather than default — is a finding at **Medium minimum**. For entry-point agents and always-on rules, the minimum severity is **High**. Per the Clarification-First Verification behavioral charter directive and the clarification & fan-out discipline pillar P8 B1.
+
+---
+
+## Required Finding Output Schema
+
+Every **individual sub-agent finding** written to `.audit-workspace/D{N}-SA{M}.findings.md` AND every EVOLVE proposal block carries this YAML-style header before the prose body. **Synthesis files** (`.audit-workspace/D{N}-synthesis.md`) are aggregations and MUST instead open with a domain-level metadata block (see §Synthesis File Header Schema below); per-finding rigor details are referenced by finding ID, not restated per finding in synthesis.
+
+```
+confidence: high | medium | low
+confidence_basis: <one phrase — direct measurement | sampled observation | inference from analogue>
+falsifiability: <observation that would disprove this finding>
+causal_chain: <step1 → step2 → step3 (≥3 links, symptom → driver → root)>
+bias_check: <named bias(es) considered + mitigation>
+counter_argument: <one genuine sceptic position + the resolution>
+sources:
+  - url: https://...
+    accessed: YYYY-MM-DD
+    author: <author or organisation>
+    trust_tier: official-docs | peer-reviewed | vendor-note | independent-analysis | blog-post
+impact_horizon: short | medium | long  # 2.0.0 (Decision 17) — mandatory pre-triage filter
+progress_toward_pillar: <axis>.<pillar_id>+<delta>  # 2.0.0 (Decision 17) — e.g., "governance.P5+0.15" or "content-quality.CQ3+0.20"
+```
+
+The body of the finding may then describe the issue, file references, recommendation, and effort per the host prompt's finding format (the audit prompt's Tier 3 finding format or the evolve prompt's proposal format).
+
+---
+
+## Schema Enforcement
+
+- The audit prompt's `Shallow Finding Detector` rejects any finding lacking the schema header or with a single-source empirical claim (unless the source is `official-docs` AND the claim is platform-specific).
+- The evolve prompt's rejection filters reject any finding that cannot answer all six contract tests.
+- The audit-execute `Finding Registry` carries `confidence`, `causal_chain_depth`, and `sources` fields forward through the execution lifecycle. Missing fields block Phase 1 Triage.
+- The audit-execute `Sub-Agent Failure Handling` retries any sub-agent whose findings contain placeholder values (e.g. `confidence_basis: "based on analysis"` without a named basis).
+
+---
+
+## Impact-Gated Registration (Decision 17 — added 2026-05-26)
+
+Findings without both `impact_horizon` and `progress_toward_pillar` are DROPPED at sub-agent output time before orchestrator triage. The audit signals framework-level progress, not analytical depth without payoff. The impact-gating behavioral charter directive and Pillar Compliance Test Q5/Q6 encode the enforcement.
+
+---
+
+## Proof Trace Contract (Decision 9 — added 2026-05-26)
+
+For every state-dependent claim (file existence, file content, grep match, type-check pass, test output, command exit code), emit a `proof_trace:` block under the finding body containing:
+
+```yaml
+proof_trace:
+  claim: <one-sentence assertion>
+  command: <bash invocation OR Read tool call OR grep pattern>
+  expected: <pattern OR quoted output>
+  actual: <verbatim ≤200 chars from command output>
+  verdict: matched | mismatched
+  accessed: <YYYY-MM-DD>
+```
+
+Sub-agents that omit proof_trace on state-dependent claims trigger Shallow Finding Detector. The reviewer sub-agent's Pass 1.5 reads proof_trace blocks to verify implementation against documented runtime state. Citation alone insufficient — verification commands close the loop.
+
+---
+
+## Per-Domain Source Targets
+
+Default research targets per audit domain (overridable in domain-specific source-set blocks):
+
+| Domain group | Primary sources | Recency window |
+|--------------|-----------------|----------------|
+| D1 / D3 / D8 (code patterns) | Current best-practice references for the specific pattern | 12 months |
+| D9 (platform adapters) | Official platform documentation + changelog diff vs prior cycle | 12 months |
+| D15 (security) | OWASP ASI current revision + CVE feeds + vendor security advisories | 12 months |
+| D17 (competition) | Competitor product docs ≤6 months + GitHub-stars trajectory + third-party benchmarks | 6 months |
+| D19 (Claude Code) | Current Claude Code documentation (hooks, settings.json schema, skill format, Agent Teams API) | 12 months |
+| All other domains | At minimum, verify any external references (tool docs, standards) are current | 12 months |
+
+---
+
+## Pillar Service
+
+This template serves the framework's North Star through:
+
+- **P2 Scientific & Practical Quality (primary).** The six-test contract operationalises P2 at the per-finding level for every audit sub-agent and every EVOLVE proposal.
+- **P5 Governance Self-Quality (supporting).** Single source of truth eliminates duplication across the audit prompt, the evolve prompt, and the audit domain files.
+- **P3 Adapter & External Tool Currency (supporting).** Web Research Mandate enforces source-and-date capture for platform docs, CLI tool releases, and CVE feeds (per the adapter & external tool currency pillar P3).
+
+Pillar Compliance Test answers: (1) P2 primary, P5 / P3 supporting. (2) Measurable improvement — every finding gains 6 enforcement gates and a 7-field schema; placeholder findings are detectable and retryable. (3) Net governance size impact: +85 lines for this file, offset by reference-instead-of-restate across the audit/evolve prompts and domain files.
+
+---
+
+## Synthesis File Header Schema
+
+Domain synthesis files (`.audit-workspace/D{N}-synthesis.md`) open with a single metadata block, not per-finding rigor headers:
+
+```yaml
+domain: D{N}
+cycle: {cycle_number}
+date: YYYY-MM-DD
+framework_version: {version}
+commit: {short_sha}
+rigor_contract: applied | partial | n/a
+sub_agents:
+  - SA{N}.{M} Name (count findings)
+```
+
+Per-finding rigor lives in `.audit-workspace/D{N}-SA{M}.findings.md`; synthesis references findings by ID.

package/dist/content/agents/shared/severity-mapping.md

@@ -0,0 +1,92 @@
+---
+id: shared-severity-mapping
+type: reference
+description: Canonical severity-vocabulary mapping across reviewer, fixer, security-auditor, check criteria, and the 9 content-quality specialists.
+tags: [reference]
+---
+
+# Severity Vocabulary Canonical Mapping
+
+> Last updated: 2026-06-05
+> Pillars: P2 (primary), P4 (supporting).
+> Canonical for: agents/hatch3r-reviewer.md, agents/hatch3r-fixer.md, the 9 CQ quality-vector specialists (agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md), checks/*.md.
+
+## Purpose
+
+Single source of truth for severity vocabulary alignment across all hatch3r content artifacts. Audit findings (the canonical audit severity taxonomy) use 5 buckets: Critical, High, Medium, Low, Info. Other artifacts (reviewer agent, security auditor, check criteria) use their own vocabularies. This file maps them so the fixer agent can consume any source's output and map to the canonical bucket.
+
+## 6-Column Canonical Map
+
+| Audit Severity (canonical) | Reviewer Verdict | Reviewer Level | Security-Auditor Severity | Check Criteria Tag | Specialist Status |
+|----------------------------|------------------|----------------|---------------------------|--------------------|-------------------|
+| Critical                   | DESIGN_OBJECTION | Critical       | Critical                  | [CRITICAL]         | CRITICAL          |
+| High                       | REQUEST CHANGES  | Critical       | High                      | [CRITICAL]         | FINDINGS          |
+| Medium                     | REQUEST CHANGES  | Warning        | Medium                    | [RECOMMENDED]      | FINDINGS          |
+| Low                        | APPROVE          | Suggestion     | Low                       | [RECOMMENDED]      | PASS              |
+| Info                       | APPROVE          | Suggestion     | (n/a)                     | (n/a)              | PASS              |
+
+## Mapping Rationale
+
+- **Critical (canonical)** maps to `DESIGN_OBJECTION` because both express a fundamental, unfixable-by-iteration problem requiring architectural intervention. Reviewer Level `Critical` also maps when paired with `REQUEST CHANGES` and the issue is a security or correctness blocker.
+- **High (canonical)** maps to `REQUEST CHANGES` + Reviewer Level `Critical`. The reviewer's `Critical` level covers both canonical Critical and High; disambiguation uses verdict (`DESIGN_OBJECTION` → Critical, `REQUEST CHANGES` → High) and finding nature (architectural vs. quality gap).
+- **Medium (canonical)** maps to `REQUEST CHANGES` + Reviewer Level `Warning` and Security-Auditor `Medium`. These are quality gaps that block the current cycle but not the release.
+- **Low (canonical)** maps to `APPROVE` + Reviewer Level `Suggestion`. The reviewer approves but flags improvements. Security-Auditor `Low` is the equivalent severity for security-domain findings.
+- **Info (canonical)** has no Security-Auditor or Check-Criteria equivalent because those vocabularies do not enumerate a no-action observation tier.
+- **Specialist Status (PASS | FINDINGS | CRITICAL)** is the 3-value vocabulary emitted by the 9 CQ quality-vector specialists (`agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md`). `CRITICAL` maps to canonical Critical (any item shows a Critical-severity finding → DESIGN_OBJECTION-equivalent block). `FINDINGS` covers the canonical High + Medium band (Medium/High findings present, no Critical → REQUEST CHANGES). `PASS` maps to canonical Low + Info (every checklist item green or advisory-only → APPROVE). The collapse of two canonical buckets into one specialist value is intentional: specialists gate merge readiness, not finding-by-finding triage, so they emit a coarser status that the fixer re-expands via this row.
+
+## Consumer Contract
+
+- **hatch3r-fixer**: When ingesting findings from any source, MUST map source vocabulary to the canonical Audit Severity column before applying its action policy. Critical → blocking fix; High → blocking fix; Medium → fix in current cycle; Low → fix or defer per scope; Info → log, no action.
+- **hatch3r-reviewer**: Output uses Reviewer Verdict + Reviewer Level columns. Map to canonical via this table when escalating to fixer or audit.
+- **hatch3r-security** (CQ3 specialist): Output uses Security-Auditor Severity column. Map to canonical via this table when emitting findings.
+- **check criteria authors** (checks/*.md): Use Check Criteria Tag column. Map to canonical for severity-rollup reports.
+- **CQ quality-vector specialists** (`agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md`): Output uses the Specialist Status column (PASS | FINDINGS | CRITICAL). Map to canonical via this table when escalating to fixer or feeding the release decision.
+- **canonical audit severity taxonomy**: Defines the canonical Audit Severity column. This mapping table is the cross-vocabulary reference.
+- **audit-execute regression gate**: The "Severity Vocab" gate enforces that every modified `.md` content file either uses canonical buckets or references this file.
+
+## Edge Cases
+
+- **Reviewer `Critical` overlaps two canonical buckets.** Disambiguation rule: use `DESIGN_OBJECTION` verdict for canonical Critical, `REQUEST CHANGES` + Critical level for canonical High. When unclear, default to Critical (conservative for fixer blocking-action policy).
+- **Check Criteria has only two tags.** `[CRITICAL]` covers canonical Critical + High; `[RECOMMENDED]` covers canonical Medium + Low. Severity-rollup reports must use the worst-case canonical mapping for `[CRITICAL]` tags (treat as canonical Critical until disambiguated by file/line context).
+- **Security-Auditor has no Info tier.** Security findings of observation-only nature must be either omitted from audit output or flagged as Low with a `confidence: low` qualifier per the Confidence Expression section of `agents/hatch3r-security.md`.
+- **A11y-Auditor WCAG vocabulary.** `Critical/Major/Minor` maps to canonical `Critical/Medium/Low` (WCAG A blockers → Critical; AA violations → Medium; advisory AA/AAA → Low). No direct High equivalent — escalate Major to High when the violation blocks a critical user journey.
+- **Dependency-Auditor CVSS vocabulary.** CVSS-derived Critical (≥9.0) / High (7.0–8.9) / Medium (4.0–6.9) / Low (<4.0) aligns 1:1 with canonical audit severity. No mapping translation required.
+
+## 2.0.0 Domain Vocabulary Extensions (Decision 19)
+
+D22 / D23 / D24 admission (per the canonical audit domain map) adds three domain-specific severity vocabularies. Each row maps to the canonical Audit Severity column above.
+
+| Domain | Source vocabulary | Bucket meaning | Canonical map |
+|--------|-------------------|----------------|---------------|
+| **D22** Content Architecture | `obsolete` | Artifact serves no current pillar AND has zero cross-references | Critical (remove via D16-SA16.3 threshold) |
+| **D22** Content Architecture | `merge_candidate` | ≥80% conceptual overlap with another artifact AND removal threshold not met | High (merge the overlapping artifacts) |
+| **D22** Content Architecture | `drift` | Artifact frontmatter or body diverges from current pillar definitions | Medium |
+| **D22** Content Architecture | `gap` | Pillar is under-represented in the content corpus (per web-comparison findings) | Medium (CL-2 candidate) |
+| **D22** Content Architecture | `coverage_low` | Pillar served by <2 artifacts but pillar surface area expects ≥2 | Low |
+| **D23** Agentic Engineering Trends | `lagging` | hatch3r lacks a pattern adopted by ≥2 reputable comparables in ≤6 months | High |
+| **D23** Agentic Engineering Trends | `trailing` | hatch3r implements a pattern but ≥1 sub-element behind comparable | Medium |
+| **D23** Agentic Engineering Trends | `leading` | hatch3r ahead of all comparables on a pattern | Info (record as Strength) |
+| **D24** Governance Self-Audit | `invariant_violation` | A constitution invariant (e.g., lean threshold, anti-slop, pillar coverage) is broken | Critical |
+| **D24** Governance Self-Audit | `process_drift` | Audit cycle deviated from the audit-execute Phase contract | High |
+| **D24** Governance Self-Audit | `traceability_gap` | A change landed without a finding-registry entry or §8 amendment trail | Medium |
+| **D24** Governance Self-Audit | `cadence_miss` | Required cadence (re-envision ≥14 days, audit cycle, evolve) overdue | Low |
+
+The Specialist Status column from the 6-Column Canonical Map applies to D22/D23/D24 SAs (PASS | FINDINGS | CRITICAL coarse status) — the bucket-level mapping above is the per-finding-row resolution within each SA's output. Consumers (fixer, reviewer) map the source bucket to canonical Audit Severity before applying action policy, identical to the Consumer Contract for existing domains.
+
+## Cross-Domain Severity Escalation Rules
+
+A finding's source bucket maps to canonical Audit Severity per the table above. Two escalation rules then re-evaluate the row before it ships to the finding registry:
+
+1. **Multi-domain compound rule.** A finding cited by ≥2 domain SAs (cross-domain dependency per the compound-system audit domain) escalates one canonical band (Medium → High, High → Critical). Rationale: cross-domain surface area indicates systemic driver, not symptom. The escalation is recorded in the finding's `cross_domain_citations` registry field; bands cap at Critical.
+2. **CQ pillar regression rule.** A finding that introduces a measurable regression on a CQ1-CQ9 pillar threshold (per the content-quality (CQ) pillars and their specialist agents) escalates one canonical band regardless of source bucket. The CQ specialist's `Specialist Status` column already collapses to PASS | FINDINGS | CRITICAL — the escalation re-expands to the canonical band the regression actually represents per the regression evidence file path + line cited in the finding body.
+
+Escalations chain: a CQ regression cited by ≥2 domain SAs receives two single-band escalations (capped at Critical). De-escalation is not permitted via these rules — a Critical never falls to High through this protocol; only the bias-check downgrade in the rigor contract (`agents/shared/rigor-contract.md` §Scientific Rigor Contract item 5) can reduce a severity band.
+
+## Verification
+
+This file lives at `agents/shared/severity-mapping.md`. Enforcement is the inverse of a citation-count floor: `scripts/validate-severity-vocabulary.ts` (run via `npm run validate:severity-vocabulary`, wired into `npm run validate`) scans `.md` files under `agents/`, `checks/`, `commands/`, `rules/`, `skills/`, `hooks/`, and `governance/` for off-canonical severity terms (Moderate, Major, Minor, Blocker, etc.) in a structured severity context (frontmatter `severity:`, severity-labeled table cells, `Severity:`/`Level:` pairs, bracket tags). A file that emits any such term MUST reference this file (basename `severity-mapping.md`) as the documented opt-out, or the scan emits a `SEVERITY-MAPPING-MISS` plus per-occurrence `SEVERITY-OFF-CANONICAL` error (exit 1). The set of referencing files is therefore demand-driven — it grows only when an artifact actually emits an off-canonical term — not a fixed minimum. The mapping doc's own absence at the canonical path makes the scan exit clean on a default-root run (the opt-out can no longer be relied on), so this file's presence is itself the enabling precondition.
+
+## Pillar Service
+
+- **P2 Scientific Quality (primary):** Canonical mapping eliminates ambiguity in fixer bucketing — finder output is round-trippable through the fix pipeline without information loss.
+- **P4 Lean Coverage (supporting):** Single source of truth replaces 5 partial vocabularies (reviewer, security-auditor, check-criteria, CVSS/WCAG auditors, CQ-specialist status); consumers reference instead of restating.

package/dist/content/agents/shared/triage-vocabulary.md

@@ -0,0 +1,46 @@
+---
+id: shared-triage-vocabulary
+type: reference
+description: Canonical Light/Standard/Deep triage-tier vocabulary — maps the three effort tiers to severity, complexity, effort, sub-agent count, and research depth so every triage-first workflow shares one calibration.
+tags: [reference]
+---
+
+# Triage Vocabulary
+
+> **Pillars:** P7 (Speed & Token Efficiency), P8 (Clarification & Fan-out Discipline), P2 (Scientific & Practical Quality)
+> Single source of truth for the Light / Standard / Deep triage tiers. Triage-first orchestrators (`orchestrator: true` commands per `agents/shared/efficiency-patterns.md` → P3) classify each task into one tier before delegating; this file is the shared mapping they calibrate against.
+
+The tier names (Light / Standard / Deep) and the numeric `triage_tiers: [1, 2, 3]` frontmatter array are two spellings of the same three tiers: `1 = Light`, `2 = Standard`, `3 = Deep`. The user `--effort=light|standard|deep` flag (PRD Decision 17) forces a named tier and bypasses auto-classification. This file binds the named spelling, the numeric spelling, and the `--effort` flag values to one calibration so a tier classified in one workflow means the same depth in another.
+
+---
+
+## Tier mapping
+
+| Tier | When to use | Complexity | Effort | Depth | Sub-agent count | Examples |
+|------|-------------|------------|--------|-------|-----------------|----------|
+| **Light** (`1`, `--effort=light`) | Single-module change with a clear, testable acceptance criterion; no architectural decision; reversible. | 1 module touched. | S — minutes to ~1 hour. | Reduced fan-out: 1–2 researchers; skip ADR generation; single standalone todo entry, not an epic. | ~2 (reduced researcher set + writer). | Typo fix, single-function edit, frontmatter-only change, copy tweak. |
+| **Standard** (`2`, `--effort=standard`) | Feature touching 2–5 modules with sub-tasks; ADR generated only if an architectural decision arises mid-flow. | 2–5 modules touched. | M — hours to ~1 day. | Standard pipeline: all parallel researcher modes; ADR-on-demand. | ~6 (researcher modes + writer + on-demand specialist gates). | Add an endpoint to an existing service, extend an existing schema additively, wire a new component into an existing flow. |
+| **Deep** (`3`, `--effort=deep`) | Cross-cutting work: new architecture, multiple integrations, or a breaking change; confirm scope with the user before writing files. | New architecture or breaking change spanning >5 modules / multiple subsystems. | L — multi-day. | Full pipeline: deep research, all researcher modes, full specialist fan-out, mandatory ADR. Confirm scope via `agents/shared/user-question-protocol.md` before writing. | Up to 13 (4–5 parallel researcher modes + writer + the 9 CQ vector specialists advising pre-write). | New subsystem, breaking API/schema migration, cross-service integration, framework-wide refactor. |
+
+The sub-agent counts are calibration anchors, not caps. P8 (`rules/hatch3r-fan-out-discipline.md`) governs the actual width: fan out to the true count of independent units even when it exceeds the tier anchor, and never serialize independent work to hit a lower count. The `expected_sa_count` field that orchestrators emit (per `rules/hatch3r-cost-visibility.md`) derives its preview from this column; a post-run delta beyond 25% absolute carries `flagged_for_review: true`.
+
+---
+
+## Auto-tiering inputs
+
+A triage-first orchestrator classifies a task by reading these three signals before delegating, then picks the highest tier any signal selects:
+
+1. **Module span** — count of distinct modules the change touches: 1 → Light, 2–5 → Standard, >5 → Deep.
+2. **Decision class** — additive/reversible → Light or Standard; introduces an architectural decision, a new integration, or a breaking change → Deep.
+3. **Acceptance-criteria clarity** — a single clear AC keeps a task Light or Standard; missing/ambiguous AC fires the P8 B1 clarification gate (`.claude/rules/clarification-default.md`) before tiering, since an unclassifiable task cannot be tiered.
+
+Auto-tiering can misclassify (a single-module task scored Deep, or a cross-cutting task scored Light). The `--effort` flag is the documented recovery path; record the chosen tier in the iteration summary `triage_tier` field (`rules/hatch3r-iteration-summary.md`).
+
+---
+
+## Cross-references
+
+- **Severity vs tier are orthogonal.** Tier is task *effort* (how much pipeline to run); severity is finding *blast radius* (how bad a defect is). A Light task can surface a Critical finding, and a Deep task can close only Low findings. Map findings on the Critical / High / Medium / Low / Info taxonomy per `agents/shared/quality-charter.md` §14 (Severity Discipline), which delegates the canonical taxonomy to `agents/shared/severity-mapping.md`. Do not collapse the two axes — a Critical finding does not promote a Light task to Deep; it triggers the severity action policy on its own track.
+- **Triage-first contract** — `agents/shared/efficiency-patterns.md` → P3 (the `orchestrator: true` requirement for a `triage_tiers` array + a Triage/Tier/Scale Assessment heading).
+- **Fan-out width** — `rules/hatch3r-fan-out-discipline.md` (P8 B2): sub-agent count tracks unit count, not tier label.
+- **Decision 17** — the `triage_tiers` frontmatter array + `--effort` override contract (governance PRD §Key Design Decisions, Decision 17).

package/dist/content/agents/shared/user-content-templates.md

@@ -10,9 +10,13 @@ cache_friendly: true
 
 Canonical reference for the body and frontmatter shapes `hatch3r-creator` produces when a user invokes `/hatch3r-create`. Five sections, one per artifact type. Each provides the minimum frontmatter (YAML), a body skeleton with `<PLACEHOLDER>` substitution slots, and notes on required versus optional fields. Placeholder convention: `<NAME>` is replaced at composition time; `[<TAG-1>, <TAG-2>]` indicates an array.
 
+The `type` field appears in the Required list and skeleton of all five sections, but the author never sets it by hand: `composeArtifactFile` (`src/content/userContent.ts`) re-pins `derived.type = artifact.type` from the type branch the user already selected at Step 1.1, so a user-supplied value is authoritatively overridden. It is listed as Required because every on-disk artifact carries it, not because the user types it (D20-SA20.1-F20.1.C1).
+
 ### 1. Agent Skeleton
 
-**Path:** `.hatch3r/overrides/agents/<NAME>.md`. **Required:** `id`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present).
+**Path:** `.hatch3r/overrides/agents/<NAME>.md`. **Required:** `id`, `type`, `description`, `model`, `tags`. **Optional:** `protected` (always `false` for user agents), `quality_charter` (auto-injected), `adapters` (restricts adapter propagation when present), `tools` (per-agent allow/deny allowlist — when `tools.allow` cardinality exceeds 3, a **Security baseline:** body reference is required, see below).
+
+**Security baseline (tool-grant inheritance).** A user agent that grants more than 3 tools in `tools.allow` MUST cite `rules/hatch3r-security-patterns.md` in a `**Security baseline:**` body line and inherit its deny-by-default posture (no unscoped `Bash`, no destructive subcommands, secrets via `${env:VAR}` only). `hatch3r-creator` surfaces a gentle warning when a wide `tools.allow` ships without this citation; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`). Without this slot a broad tool grant is an unbounded-grant risk (audit Cycle 10 F20.2.A3).
 
 ```yaml
 ---
@@ -21,15 +25,21 @@ type: agent
 description: <DESCRIPTION>
 model: <MODEL>
 tags: [<TAG-1>, <TAG-2>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
 
+The `pillars:` array carries the governance-axis (P1–P8) or content-quality-axis (CQ1–CQ9) ids the artifact serves. Required by the strict pillar-declaration gate in `runUserContentGates` (`src/content/userContent.ts`); omit the field only if the body carries a `**Pillars:**` line instead. Values outside the P1–P8 ∪ CQ1–CQ9 union are rejected at save time (`validateStructuredPillars`).
+
 ```markdown
 You are <ROLE-STATEMENT> for the project. You receive <INPUT-SUMMARY> and produce <OUTPUT-SUMMARY>.
 
 Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<context>`, `<rules>` tags wrap role, runtime state, and constraints.
 
+## §0 Detect Ambiguity (P8 B1)
+Before any action, scan the request for unresolved scope, target, irreversibility, or constraint conflicts. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` before proceeding — default path, not exception. Proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable.
+
 <task>
 ## Your Role
 - <BULLET-1>
@@ -54,10 +64,11 @@ Prompt structure follows `agents/shared/prompt-structure.md` — `<task>`, `<con
 ## Boundaries
 - **Always:** <ALWAYS-1>
 - **Never:** <NEVER-1>
+- **Security baseline:** inherits `rules/hatch3r-security-patterns.md` (deny-by-default tools, no destructive subcommands, secrets via `${env:VAR}`). Required line when `tools.allow` grants more than 3 tools.
 </rules>
 
 ## Confidence Expression
-Per `agents/shared/quality-charter.md` §1 and `governance/audit/templates/rigor-contract.md`, rate every recommendation and decision as **high**, **medium**, or **low** confidence and name the basis (direct measurement, sampled observation, inference from analogue).
+Per `agents/shared/quality-charter.md` §1 and `agents/shared/rigor-contract.md`, rate every recommendation and decision as **high**, **medium**, or **low** confidence and name the basis (direct measurement, sampled observation, inference from analogue).
 
 - **High:** Verified against the specific code/document path read this turn (<FILE-OR-FIXTURE-VERIFIED>).
 - **Medium:** Pattern-based on convention or analogue (<NAMED-PATTERN-OR-ANALOGUE>); not fully traced.
@@ -82,9 +93,11 @@ This agent inherits `agents/shared/quality-charter.md` via the frontmatter `qual
 
 The three sections above (Confidence Expression, Failure Modes, Quality Charter) are required on every user-authored agent. `hatch3r-creator` injects placeholders during composition and reports `gentleWarnings` when any section is missing or left unsubstituted at save time.
 
+**§0 ambiguity gate (D13-10).** The `## §0 Detect Ambiguity` block above (or any `user-question-protocol.md` reference) is required so a user agent opens with a clarification-first gate, matching CONSTITUTION §2 P5 ambiguity-gate coverage (agents/skills/commands) at 100%. `hatch3r-creator` surfaces a gentle warning when a user agent ships without it; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`, the agent/skill branch of `runUserContentGates`).
+
 ### 2. Skill Skeleton
 
-**Path:** `.hatch3r/overrides/skills/<NAME>/SKILL.md` inside a new directory created via `mkdir -p`. The layout matches the canonical pattern at `skills/hatch3r-<name>/SKILL.md`. **Required:** `id`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
+**Path:** `.hatch3r/overrides/skills/<NAME>/SKILL.md` inside a new directory created via `mkdir -p`. The layout matches the canonical pattern at `skills/hatch3r-<name>/SKILL.md`. **Required:** `id`, `type`, `description`, `tags`. **Optional:** `quality_charter` (auto-injected).
 
 ```yaml
 ---
@@ -92,6 +105,7 @@ id: <NAME>
 type: skill
 description: <DESCRIPTION>
 tags: [<TAG-1>, <TAG-2>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -101,11 +115,15 @@ quality_charter: agents/shared/quality-charter.md
 
 ## Quick Start
 Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
 - [ ] Step 1: <STEP-1-TITLE>
 - [ ] Step 2: <STEP-2-TITLE>
 - [ ] Step 3: <STEP-3-TITLE>
 - [ ] Step 4: Verification
 
+## §0 Detect Ambiguity (P8 B1)
+Before any action, scan the request for unresolved scope, target, irreversibility, or constraint conflicts. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` before proceeding — default path, not exception. Proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable.
+
 ## Step 1: <STEP-1-TITLE>
 <STEP-1-BODY>
 
@@ -121,11 +139,13 @@ Run `<VERIFICATION-COMMAND>`. The skill is complete when:
 2. <ACCEPTANCE-CRITERION-2>
 ```
 
-Recommended step count: 3-7. Skills with more than 7 steps trigger a gentle warning suggesting decomposition.
+Recommended step count: 3-7 (the §0 ambiguity gate does not count toward the limit). Skills with more than 7 steps trigger a gentle warning suggesting decomposition.
+
+**§0 ambiguity gate (D13-10).** The `## §0 Detect Ambiguity` block above (or any `user-question-protocol.md` reference) is required so a user skill that drives an agentic workflow opens with a clarification-first gate, matching CONSTITUTION §2 P5 ambiguity-gate coverage (agents/skills/commands) at 100%. `hatch3r-creator` surfaces a gentle warning when a user skill ships without it; at maturity tier `team`/`scaleup`/`enterprise` the warning is promoted to a strict gate per F20.2.A1's tier-aware floor (gate path: `src/content/userContent.ts`, the agent/skill branch of `runUserContentGates`).
 
 ### 3. Rule Skeleton
 
-**Path:** `.hatch3r/overrides/rules/<NAME>.md` plus the auto-generated companion `.hatch3r/overrides/rules/<NAME>.mdc`. The `.md` is canonical; `.mdc` is generated by `saveUserContent` using the `.md → .mdc` scope transform from `rules/hatch3r-content-authoring.md`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
+**Path:** `.hatch3r/overrides/rules/<NAME>.md` plus the auto-generated companion `.hatch3r/overrides/rules/<NAME>.mdc`. The `.md` is canonical; `.mdc` is generated by `saveUserContent` using the `.md → .mdc` scope transform implemented in `src/content/userContent.ts`. **Required:** `id`, `type`, `description`, `scope`, `tags`. **Required when scope=conditional:** `globs`. **Optional:** `precedence` (default `normal`), `quality_charter` (auto-injected).
 
 Three scope shapes (pick one):
 
@@ -144,6 +164,7 @@ scope: <SHAPE-A-VALUE-OR-SHAPE-B-CSV-OR-conditional>
 globs: "<GLOB-CSV>"          # required for Shape C; omit for A/B
 precedence: <PRECEDENCE>     # Shape C only; default normal
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -164,7 +185,7 @@ quality_charter: agents/shared/quality-charter.md
 <POSITIVE-AND-NEGATIVE-EXAMPLES>
 ```
 
-The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a strict gate). The `.mdc` companion has different frontmatter — `saveUserContent` derives it from the `.md` scope shape per the table in `rules/hatch3r-content-authoring.md`.
+The body bytes of `.md` and `.mdc` must match exactly (paired-file parity is a strict gate). The `.mdc` companion has different frontmatter — `saveUserContent` derives it from the `.md` scope shape per the transform implemented in `src/content/userContent.ts`.
 
 ### 4. Command Skeleton
 
@@ -178,6 +199,7 @@ type: command
 orchestrator: false
 description: <DESCRIPTION>
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -191,6 +213,7 @@ orchestrator: true
 agentPipeline: [<AGENT-ID-1>, <AGENT-ID-2>]
 description: <DESCRIPTION>
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -239,13 +262,13 @@ Use the Task tool to invoke <AGENT-ID-1>. Pass collected slots as structured inp
 - <GUARDRAIL-1>
 ```
 
-The §0 block is required on every user-authored orchestrator command per CONSTITUTION §2 P8 B1 (Clarification-First, Default-Path). It must reference `agents/shared/user-question-protocol.md` verbatim — `hatch3r-creator` rejects orchestrator commands whose §0 block is missing the reference (strict gate, see D20 SA20.1 audit checklist).
+Every user-authored orchestrator command MUST contain the §0 block above per CONSTITUTION §2 P8 B1 (Clarification-First, Default-Path), and the block should reference `agents/shared/user-question-protocol.md` verbatim. This is a live runtime strict gate: `runUserContentGates` (`src/content/userContent.ts`) rejects any `orchestrator: true` command whose body lacks a `## §0` / `## Step 0` heading or a `user-question-protocol` reference, at every maturity tier (D20-F20.1.B1, shipped). `hatch3r-creator` also emits the skeleton above at composition time, so authoring discipline and the runtime gate reinforce each other. The same §0 gate extends to user agents and skills (gentle at `solo`, strict at `team`+) per D13-10 — see the agent and skill skeleton notes above and the agent/skill branch of `runUserContentGates`.
 
 The strict gate `validateCommandOrchestratorFrontmatter` (`src/cli/commands/validate.ts:171`) rejects `orchestrator: true` without a non-empty `agentPipeline` array.
 
 ### 5. Hook Skeleton
 
-**Path:** `.hatch3r/overrides/hooks/<NAME>.md`. **Required:** `id`, `type`, `event`, `agent`, `description`, `tags`. **Optional:** `globs` (file-save filtering), `condition`, `quality_charter` (auto-injected). **Event enum:** `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push`, enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
+**Path:** `.hatch3r/overrides/hooks/<NAME>.md`. **Required:** `id`, `type`, `event`, `agent`, `description`, `tags`. **Optional:** `globs` (file-save filtering), `condition`, `quality_charter` (auto-injected). **Event enum:** `pre-commit | post-merge | ci-failure | file-save | session-start | pre-push | worktree-create | worktree-remove` (8 values), enforced by `isValidHookEvent` (`src/hooks/types.ts:30`).
 
 ```yaml
 ---
@@ -256,6 +279,7 @@ agent: <AGENT-ID>
 description: <DESCRIPTION>
 globs: "<GLOB-CSV>"
 tags: [<TAG-1>]
+pillars: [<P1-OR-CQ1-PILLAR-ID>]
 quality_charter: agents/shared/quality-charter.md
 ---
 ```
@@ -276,6 +300,8 @@ When this hook fires, the assigned agent should:
 
 The `agent` field must reference an existing agent — canonical (e.g., `lint-fixer` resolves to `agents/hatch3r-lint-fixer.md`) or under `.hatch3r/overrides/agents/`. Missing references are rejected at strict-gate time.
 
+**Transitive trust warning (D20-M6).** A hook fires its referenced agent with that agent's declared tool grants. When `agent: <AGENT-ID>` resolves to a user-authored agent under `.hatch3r/overrides/agents/`, the hook inherits whatever `tools.allowed` set that user agent declared — a broad allowlist on the referenced agent silently widens the hook's blast radius. `hatch3r-creator` surfaces a gentle warning when a hook references a user-authored agent (rather than a canonical `agents/hatch3r-*.md` agent) so authors verify the downstream tool grants are intentional. Mitigation: prefer canonical agents for hooks, or pin the referenced user agent to a narrow `tools.allowed` list with a cited `**Security baseline:**` per §1.
+
 ## Reference Implementations
 
 For each user type, mirror the canonical shape below — minus the `hatch3r-` filename prefix; the user-tier path is always under `.hatch3r/overrides/{type}/`: