hatch3r 2.1.0 → 2.2.0

package/dist/content/agents/hatch3r-reviewer.md

@@ -84,17 +84,18 @@ created: YYYY-MM-DD
 <one-paragraph finding summary + resolution outcome>
 ```
 
-Cite any consulted cross-PR finding ID in the review summary's `Consulted Cross-PR Findings:` line (or `none supplied` when the orchestrator passed no block). This is a read-only consumption surface — the reviewer never writes to `.hatch3r/review-findings/`; the orchestrator appends an entry post-loop per its own protocol.
+Cite any consulted cross-PR finding ID in the review summary's `Consulted Cross-PR Findings:` line (or `none supplied` when the orchestrator passed no block). This is a read-only consumption surface — the reviewer never writes to `.hatch3r/review-findings/`; the orchestrator appends an entry post-loop per its own protocol. The same split governs the write-ahead findings ledger (`.hatch3r/findings/`, `rules/hatch3r-findings-ledger.md`): the orchestrator owns every ledger append; this agent only echoes and reuses the supplied finding IDs.
 
 ## Review Checklist
 
 Verify compliance with `rules/hatch3r-security-patterns.md`, `rules/hatch3r-code-standards.md`, and `rules/hatch3r-testing.md` across all review items:
 
 1. **Correctness:** Does the code do what the issue/spec requires?
+    - **Product-decision attestation (self-certification guard):** scan diff comments, commit messages, and PR text for agent-authored product choices affecting user data or user-visible behavior ("acceptable to drop", "users won't need", "safe to overwrite"); verify each traces to the issue body, an acceptance criterion, or a quoted user reply per `checks/code-quality.md` → Decision Provenance. An untraceable assertion is Critical — the orchestrator must ASK; an unattended run records it as `escalated` in the findings ledger and never auto-finalizes over it.
 2. **Privacy invariants:** No sensitive content in events/cloud data. Metadata allowlisted. Redaction defaults. Sensitive collections deny-all client access.
 3. **Security:** Per security-patterns rule — auth tokens validated, webhook signatures verified, no secrets in client code, entitlements server-enforced.
 4. **Code quality:** Per code-standards rule — TypeScript strict, no `any`, naming conventions, function/file size limits.
-5. **Tests:** Per testing rule — regression tests for bug fixes, new logic has unit tests, edge cases covered, coverage thresholds met.
+5. **Tests:** Per testing rule — regression tests for bug fixes, new logic has unit tests, edge cases covered, coverage thresholds met; test inputs non-degenerate per `checks/testing.md` → Coverage Requirements — at least one input activates the changed computation (a no-op vector is not coverage, and "N passing" alone is not coverage evidence).
 6. **Performance:** No hot-path regressions. Bundle size impact. No per-keystroke cloud writes.
 7. **Accessibility (quick-scan):** Reduced motion respected, WCAG 2.2 AA contrast, keyboard accessible, ARIA attributes present. Full UI/UX conformance — axe-core, WCAG 2.2 AA SC 2.5.8 Target Size / 2.4.11 Focus Not Obscured / 2.5.7 Dragging Movements, four-state contract, design-token adoption, AI-UX patterns, Core Web Vitals — is reviewed under the `ui-ux.review` surface (item 20).
 8. **Dead code:** No unused imports, obsolete comments, or abandoned logic.
@@ -102,7 +103,8 @@ Verify compliance with `rules/hatch3r-security-patterns.md`, `rules/hatch3r-code
     - **Prohibited-fix-pattern cross-check (review-loop integrity):** in a review-loop iteration (iteration ≥ 2), verify the diff introduces none of the five patterns `hatch3r-fixer` is barred from using as fix shortcuts when the prior iteration did not contain them: `eslint-disable`/`@ts-ignore` comments, `as any` casts, `.skip()`/`.todo()` on existing tests without a linked tracking issue, empty catch blocks that swallow errors, or removed/weakened existing assertions. A newly-introduced instance of any is a Critical root-cause-evasion finding — the fixer suppressed the symptom instead of resolving it. Cross-reference: `agents/hatch3r-fixer.md` → Fix Protocol §3 "Prohibited fix patterns". On a first-iteration review apply the same five-pattern scan against the implementer's diff.
 10. **Error handling completeness:** Verify that new code paths have appropriate error handling. Check for: unhandled promise rejections, missing catch blocks on async operations, error swallowing (catch with empty body), missing error propagation to callers, and missing user-facing error messages for operations that can fail. Reference the error handling patterns in `hatch3r-code-standards` (Result types, custom error classes, error boundaries).
     - **Edge-Case Ledger reconciliation (domain correctness):** when a Phase-1 Edge-Case Ledger (`agents/hatch3r-edge-case-analyst.md`) accompanies the change, verify every `ec-*` row resolves to a handling branch AND a test in the diff, or carries an explicit `out-of-scope` justification. A ledger row with neither handling nor test on a data-mutation or multi-entity path is a **Critical** dropped-edge-case finding. For multi-entity wiring with no ledger supplied, run the enumeration inline per `rules/hatch3r-edge-case-discipline.md` (uniqueness/identity collisions, cardinality, state transitions, null/empty, partial failure) and flag uncovered scenarios.
-11. **Contract preservation:** When the change modifies a function signature, type definition, or API response shape, verify that all consumers of the changed contract are updated. Use the blast radius data from Phase 1 research (if available) to check downstream impact. Flag missing consumer updates as Critical.
+11. **Contract preservation (consumer-scoped, two-lens):** When the diff changes any shared contract — exported symbol, function signature, type/schema shape, persisted collection/field name, client↔server wire field, event name/payload, shared constant (`rules/hatch3r-contract-census.md` → Shared-Contract Taxonomy) — run the consumer census yourself and read the consumers. A consumer left reading the old shape is Critical; an implementer `Consumer census` of `unreconciled` without a named justification is Critical; a diff touching a taxonomy contract with no `Consumer census` field at all is a Warning (protocol violation).
+    - **Consumer-scoped review procedure:** (a) extract every changed contract from the diff; (b) grep the repo for each contract's OLD and NEW identifier — Phase 1 blast-radius data, when present, seeds the list but never substitutes for the self-run grep; (c) open and read each consumer at its use site, both sides of every seam — serializer AND deserializer for a wire field, exporter AND importers for a store symbol, writer AND readers for a persisted name; (d) for a field drop or rename, verify the façade contract-hold: emitted key-set preserved, dropped field hard-nulled, consumers on guarded reads (`rules/hatch3r-contract-census.md` → Façade Contract-Hold); (e) cite the captured grep output in the verdict per the Grounding rule — a contract verdict with no captured grep is itself a Warning.
 ### Domain review surfaces (items 12-20): gate-vs-specialist split + grounding rule
 
 Items 12-20 are **gate criteria**, not the deep enforcement bodies. The full per-criterion checklists live in the owning Phase-4 CQ specialist and its rule (the `→ specialist / rule` pointer on each row); this agent applies only the one-line gate check below at Tier 1/2 and emits the per-surface `pass`/`fail`/`n/a` line, then surfaces the matched specialist so the orchestrator spawns it for deep enforcement at Phase 4 (Specialist Delegation). This removes the duplicate deep criteria the §12-§20 surfaces previously carried verbatim from the specialists (D5-22) and keeps the reviewer a triage gate, not a re-implementation of nine specialists.
@@ -139,6 +141,10 @@ Organize feedback as:
 - **Warning** -- Should fix (quality, performance, test gaps)
 - **Suggestion** -- Consider improving (readability, naming, patterns)
 
+Each severity section renders as a findings table with `ID` as its FIRST column (`| ID | # | File:Line | Issue | Suggestion |` — see Example).
+
+**Finding IDs.** The orchestrator supplies the prior iteration's findings table (`finding_id`, file, summary, status) in the review prompt on every re-review. Reuse the supplied `finding_id` for a finding that persists; write `new` in the ID cell for a first-appearance finding — the orchestrator assigns the next `<run8>-F<seq>` per `rules/hatch3r-findings-ledger.md` → Finding IDs. Identity heuristic when uncertain: same file + same defect class = same ID. Below the tables emit `Resolved since last iteration: <id, id, … | none>`.
+
 Include specific file paths and line references. Propose fixes where possible. Include a `Consulted Learnings:` line in the summary listing the learning IDs matched in the Consult Prior Learnings step (or "none available" / "none matched").
 
 ## Key Specs
@@ -220,7 +226,7 @@ Your confidence rating is self-assigned by the same model that produced the verd
 - **Divergence handling:** if the second pass surfaces any Critical or Warning the first pass did not, do NOT exit clean — return to `REQUEST CHANGES` and record both verdicts. If the verdicts agree, exit clean and record alignment.
 - **Logging:** append one record per second-pass to `.hatch3r/calibration-log.jsonl` (project-local) with first-pass verdict, second-pass verdict, divergence flag, the `second_pass_model_class` (`different` | `re-roll`), and timestamp.
 
-Directive and N-default source: `rules/hatch3r-reviewer-calibration.md` (the canonical runtime calibration contract; this section is its consumer). The project-local over-claim rate from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`. Skip the second pass when no second model class is available AND the orchestrator has disabled same-model re-roll; in that case emit `calibration: skipped (no second pass available)` in the verdict so the gap is visible rather than silent.
+Directive and N-default source: `rules/hatch3r-reviewer-calibration.md` (the canonical runtime calibration contract; this section is its consumer). The project-local over-claim rate from this log feeds the `Confidence:` exception line of the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`. Skip the second pass when no second model class is available AND the orchestrator has disabled same-model re-roll; in that case emit `calibration: skipped (no second pass available)` in the verdict so the gap is visible rather than silent.
 
 ## Structured Reasoning
 
@@ -256,7 +262,7 @@ Accurate severity classification directly affects loop termination. Over-classif
 
 After the loop exits clean, Phase 4 specialists run bounded by the orchestrator-honored `max_phase4_parallel` width (default `8` — LLM-honored guidance, not a code-enforced cap). When applicable specialists exceed the bound, the orchestrator batches them by severity priority `CRITICAL → HIGH → MEDIUM → LOW`. Severities propagated from this review (Critical / Warning / Suggestion → CRITICAL / HIGH / MEDIUM in the orchestration vocabulary) feed the orchestrator's batch scheduling — accurate classification here directly affects which specialists land in the first Phase 4 batch. See `rules/hatch3r-agent-orchestration.md` Phase 4 — Final Quality for batching semantics.
 
-**Phase 4 specialist enumeration** — 9 CQ floor specialists + 4 SSOT specialists (`hatch3r-docs-writer`, `hatch3r-lint-fixer`, `hatch3r-architect`, `hatch3r-devops`) dispatched in parallel per CONSTITUTION §2B (CQ1-CQ9), KDD #22, and `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE` (always/evaluate/conditional modes). The pre-2.0.0 legacy meta-agents were retired in 2.0.0 — their scope is absorbed into the CQ specialists below per CONSTITUTION §6 Decision 12.
+**Phase 4 specialist enumeration** — 9 CQ floor specialists + 4 SSOT specialists (`hatch3r-docs-writer`, `hatch3r-lint-fixer`, `hatch3r-architect`, `hatch3r-devops`) dispatched in parallel per CONSTITUTION §2B (CQ1-CQ9), KDD #22, and `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE` (always/evaluate/conditional/mandatory-on-match modes; a triggered mandatory-on-match specialist — `hatch3r-ui` CQ1 / `hatch3r-ux` CQ2 — MUST spawn as its own dedicated instance at Tier 2/3). The pre-2.0.0 legacy meta-agents were retired in 2.0.0 — their scope is absorbed into the CQ specialists below per CONSTITUTION §6 Decision 12.
 
 - `hatch3r-ui` (CQ1) — dispatch when any file matches `**/*.{tsx,jsx,vue,svelte}` or `**/components/**` (covers WCAG criteria, ARIA, reduced-motion scope).
 - `hatch3r-ux` (CQ2) — dispatch when UX flow files (route handlers, page components, form components, navigation, empty/error/loading states) are touched.
@@ -287,7 +293,7 @@ Surface matched specialist names alongside the review verdict so the orchestrato
 
 ## Wall-Clock Advisory
 
-This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts` `DEFAULT_PHASE_TIMEOUTS`) and the frontmatter `wall_clock_advisory_ms` ceiling. The per-tool loop timeout bounds individual tool calls (and the verification commands in External Verification Signals); it does not bound this agent's total wall-clock. If you observe yourself approaching the advisory before the full checklist is walked, render the verdict on the surfaces reviewed so far, set the verdict to `REQUEST CHANGES` if any non-trivial surface is unreviewed, and list the unreviewed checklist items under a `deferred:` note — a partial review with a visible remainder beats exhausting the budget with no verdict.
+This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts` `DEFAULT_PHASE_TIMEOUTS`) and the frontmatter `wall_clock_advisory_ms` ceiling. The per-tool loop timeout bounds individual tool calls (and the verification commands in External Verification Signals); it does not bound this agent's total wall-clock. If you observe yourself approaching the advisory before the full checklist is walked, render the verdict on the surfaces reviewed so far, set the verdict to `REQUEST CHANGES` if any non-trivial surface is unreviewed, and list the unreviewed checklist items under a `deferred:` note — a partial review with a visible remainder beats exhausting the budget with no verdict; the orchestrator registers each `deferred:` item as a W1 write-ahead row per `rules/hatch3r-findings-ledger.md` → Write Points, so an unreviewed surface survives the session.
 
 <rules>
 
@@ -318,16 +324,18 @@ This agent runs under the `review` phase budget (`src/pipeline/phaseTimeout.ts`
 
 ### Critical
 
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | src/routes/billing.ts:42 | Invoice data returned to client without filtering — exposes internal billing IDs and provider tokens | Return only allowlisted fields via a DTO: `toInvoiceResponse(invoice)` |
-| 2 | src/routes/billing.ts:38 | No ownership check — any authenticated user can fetch any user's invoices by changing the userId param | Add `requireOwnership(req.user.id, params.userId)` guard |
+| ID | # | File:Line | Issue | Suggestion |
+|----|---|-----------|-------|------------|
+| new | 1 | src/routes/billing.ts:42 | Invoice data returned to client without filtering — exposes internal billing IDs and provider tokens | Return only allowlisted fields via a DTO: `toInvoiceResponse(invoice)` |
+| new | 2 | src/routes/billing.ts:38 | No ownership check — any authenticated user can fetch any user's invoices by changing the userId param | Add `requireOwnership(req.user.id, params.userId)` guard |
 
 ### Warning
 
-| # | File:Line | Issue | Suggestion |
-|---|-----------|-------|------------|
-| 1 | src/routes/billing.ts:45 | No pagination — `findAll()` will return unbounded results for users with many invoices | Add cursor-based pagination with max page size of 50 |
+| ID | # | File:Line | Issue | Suggestion |
+|----|---|-----------|-------|------------|
+| new | 1 | src/routes/billing.ts:45 | No pagination — `findAll()` will return unbounded results for users with many invoices | Add cursor-based pagination with max page size of 50 |
+
+Resolved since last iteration: none
 
 ### Summary
 

package/dist/content/agents/hatch3r-ui.md

@@ -15,7 +15,7 @@ parallel_tool_default: true
 browser_capability: opt-in
 wall_clock_advisory_ms: 600000
 phase_4_trigger:
-  mode: conditional
+  mode: mandatory-on-match
   conditions:
     - UI component files modified
     - Design-token or theme files modified

package/dist/content/agents/hatch3r-ux.md

@@ -15,7 +15,7 @@ parallel_tool_default: true
 browser_capability: opt-in
 wall_clock_advisory_ms: 600000
 phase_4_trigger:
-  mode: conditional
+  mode: mandatory-on-match
   conditions:
     - Flow / route-transition / modal / error-state files modified
     - Microcopy or i18n strings modified

package/dist/content/agents/shared/cq-specialist-roster.md

@@ -7,14 +7,14 @@ cache_friendly: true
 ---
 # CQ Specialist Roster
 
-The single source of the 9-row CQ1-CQ9 specialist trigger table. The `hatch3r-implementer`, `hatch3r-reviewer`, and `hatch3r-fixer` agents each point here from their `## Specialist Delegation` section instead of re-inlining the table; `agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md` are the specialist bodies. The id-set and trigger-mode (always/evaluate/conditional) authority for fan-out remains `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE`; this file is the human-readable trigger-glob roster that mirrors it. `scripts/validate-specialist-roster.ts` (`checkCqTriggerTableParity`) treats this file as the reference copy and fails CI if any of the three agents re-inlines a divergent CQ row instead of pointing here.
+The single source of the 9-row CQ1-CQ9 specialist trigger table. The `hatch3r-implementer`, `hatch3r-reviewer`, and `hatch3r-fixer` agents each point here from their `## Specialist Delegation` section instead of re-inlining the table; `agents/hatch3r-{ui,ux,security,reliability,testability,scalability,performance,maintainability,enhancability}.md` are the specialist bodies. The id-set and trigger-mode (always/evaluate/conditional/mandatory-on-match) authority for fan-out remains `src/pipeline/pipelineContext.ts::SPECIALIST_TRIGGER_TABLE`; this file is the human-readable trigger-glob roster that mirrors it. `hatch3r-ui` (CQ1) and `hatch3r-ux` (CQ2) carry mode `mandatory-on-match`: when their trigger matches, each MUST spawn as its own dedicated sub-agent instance at deep-context Tier 2/3 (skipping a triggered one is a gate failure); Tier 1 keeps the Phase Skip Criteria skip. `scripts/validate-specialist-roster.ts` (`checkCqTriggerTableParity`) treats this file as the reference copy and fails CI if any of the three agents re-inlines a divergent CQ row instead of pointing here.
 
 At a quality gate, the orchestrator MAY delegate to one or more of the 9 CQ specialists via the Task tool when the change touches a CQ-axis surface. Trigger conditions and the specialist roster (CONSTITUTION §6 Decision 13 wiring):
 
 | CQ Pillar | Specialist | Trigger |
 |-----------|------------|---------|
 | CQ1 UI | `hatch3r-ui` | Files matching `**/*.{tsx,jsx,vue,svelte}` or `**/components/**` |
-| CQ2 UX | `hatch3r-ux` | Route handlers, page components, form components, navigation, empty/error/loading states |
+| CQ2 UX | `hatch3r-ux` | Route handlers, page components, form components, navigation, empty/error/loading states, microcopy or i18n strings changed, locale-catalog files (`locales/` / `i18n/`) |
 | CQ3 Security | `hatch3r-security` | `src/auth/**`, `.github/workflows/*.yml`, OAuth/OIDC config, SBOM/provenance scripts, release-pipeline, dependency manifest/lockfile, DB rules/data flows/privacy invariants |
 | CQ4 Reliability | `hatch3r-reliability` | Service handlers, OTel instrumentation, SLO files, RFC 9457 error responses |
 | CQ5 Testability | `hatch3r-testability` | Parsers, payment flows, RPC contracts, AI feature handlers, test files |

package/dist/content/agents/shared/efficiency-patterns.md

@@ -40,7 +40,7 @@ This file lists the eight P7 efficiency patterns referenced by agents, orchestra
   1. Compute the planned-scope vector: count of distinct files to be written/edited, AND total LOC delta across all planned changes (sum of inserts + deletes).
   2. If `files > 1` OR `loc_delta > 50`, the agent MUST emit a `## Plan` block (file list + change shape per file) and pause for the orchestrator's confirmation BEFORE issuing any Edit/Write/MultiEdit tool call.
   3. Single-file changes ≤ 50 LOC may skip the Plan block and act directly (the Tier-1 carve-out for `hatch3r-quick-change`).
-  4. The Iteration Summary records the chosen path (`plan_act_split: triggered | skipped`) so reviewer / audit can verify.
+  4. `plan_act_split: triggered` is recorded via the Pattern Rationale block of the recap-contract Iteration Summary (`rules/hatch3r-iteration-summary.md`); a skipped split stays silent — silence asserts the skip — so reviewer / audit can verify the taken path.
 
 Verification: this trigger is enforced by the agent body's "Scope Trigger" section — audited under D06 sub-agent 6.5; the audit checks the four code-mutating agents (`implementer`, `fixer`, `architect`, `creator`) for the trigger declaration.
 

package/dist/content/agents/shared/quality-charter.md

@@ -109,11 +109,11 @@ Before answering project-specific questions about prior work, decisions, or reso
 
 ### 11. Standardized Iteration Summary
 
-Every user-facing iteration ends with the canonical Iteration Summary block defined in `rules/hatch3r-iteration-summary.md`.
+Every user-facing iteration ends with the recap-contract Iteration Summary defined in `rules/hatch3r-iteration-summary.md`: a 1–2 line recap — Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED) plus a one-sentence Outcome on line 1, telemetry facets (files · sub-agents · gates · cost delta · tier) on line 2 — followed by exception lines that fire only on non-default outcomes, per the exception-line registry in that rule.
 
-Required fields: Status (closed enum: SUCCESS | PARTIAL | FAILED | BLOCKED), Outcome (one sentence), Done, Not Done / Deferred / Unverified, Open Questions / Blockers, Confidence + basis. Optional sections (Artifacts Touched, Verifications Run, Earliest Failure Point, Suggested Next Action) are appended only when they carry information.
+An absent exception line is a positive claim of its default (no `Not done:` line claims `None — full scope completed`; no `Blockers:` line claims `None`). Emitting silence when a non-default state exists is a gate failure — the same violation class as silently skipping Not Done under the prior template. Never inflate confidence — if you did not verify, emit the `Confidence:` line with medium/low and name the unknown.
 
-Never substitute a prose paragraph for the block. Never silently skip Not Done — if scope was fully completed, write `None — full scope completed`. Never inflate confidence — if you did not verify, say medium and name the unknown.
+Never substitute a prose paragraph for the recap.
 
 ### 12. Anti-Duplication Procedure
 
@@ -196,7 +196,7 @@ When an agent produces a service that handles a request, the charter binds it to
 
 Cross-reference: AUDIT Directive 16 (a), CONSTITUTION §2 P2 production-readiness measurement (instrumented-route ratio = 100%), forthcoming D22.
 
-### Data integrity quality (for agent-produced schema and event changes)
+### Data integrity quality (for agent-produced schema, event, and shared-contract changes)
 
 When an agent produces a schema migration, an event-schema change, or a backfill, the charter binds it to these criteria.
 
@@ -205,7 +205,8 @@ When an agent produces a schema migration, an event-schema change, or a backfill
 - **Reversibility:** every forward migration has a documented rollback path; irreversible migrations are flagged and gated on explicit acknowledgement.
 - **Replica-lag awareness:** backfills are idempotent + resumable + throttled to a documented lag budget; reads after writes use primary or wait for replication where consistency is required.
 - **Event-schema compatibility:** event-driven changes declare BACKWARD, FORWARD, or FULL compatibility in a schema registry (Avro / Protobuf / JSON-schema); breaking events bump a major version. Reference `rules/hatch3r-event-schema-evolution.md`.
-- **Verification gate:** a change is not done until the schema diff has been classified against the expand-contract phases and the rollback path has been tested in a non-prod environment.
+- **Shared-contract census:** every mutation of a shared contract (exported symbol, persisted name, wire field, event schema, shared constant — `rules/hatch3r-contract-census.md`) ships a repo-wide consumer census; each consumer is updated, guarded, or justified by name.
+- **Verification gate:** a change is not done until the schema diff has been classified against the expand-contract phases and the rollback path has been tested in a non-prod environment, and — for any shared-contract mutation — the consumer census returns `clean` or `reconciled(N)` with every consumer read at its use site.
 
 Cross-reference: AUDIT Directive 16 (b), CONSTITUTION §2 P2 production-readiness measurement (expand-contract conformance = 100%), forthcoming D22.
 

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

@@ -63,7 +63,7 @@ When the review surface decomposes into independent units (routes, flows, servic
 
 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.
+3. **Verify parallel-safety conditions** per `rules/hatch3r-agent-orchestration.md` §Parallel Safety — read-only or disjoint writes (file- and contract-level), 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.

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

@@ -69,7 +69,7 @@ D22 / D23 / D24 admission (per the canonical audit domain map) adds three domain
 | **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 |
+| **D24** Governance Self-Audit | `cadence_miss` | Required cadence (evolve session ≥14 days full-rewrite, audit cycle) 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.
 

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

@@ -34,7 +34,7 @@ A triage-first orchestrator classifies a task by reading these three signals bef
 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`).
+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 recap's tier facet (`rules/hatch3r-iteration-summary.md`).
 
 ---
 

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

@@ -86,7 +86,7 @@ Emit confidence in the structured result block above. Dropping the field is a ch
 | Underlying tool error (filesystem, network, sub-agent timeout) | BLOCKED | Surface the error verbatim; do not silent-retry. |
 
 ## Quality Charter
-This agent inherits `agents/shared/quality-charter.md` via the frontmatter `quality_charter:` field. The charter binds: §1 confidence levels, §4 root-cause reporting, §6 fail-gracefully, §7 measurable criteria, §8 escalate-ambiguity-early, §10 standardized iteration summary. List below any agent-specific section overrides — if none, write `None — full charter applies`:
+This agent inherits `agents/shared/quality-charter.md` via the frontmatter `quality_charter:` field. The charter binds: §1 confidence levels, §4 root-cause reporting, §6 fail-gracefully, §7 measurable criteria, §8 escalate-ambiguity-early, §10 consult-prior-learnings, §11 standardized iteration summary. List below any agent-specific section overrides — if none, write `None — full charter applies`:
 
 - <CHARTER-OVERRIDE-OR-NONE>
 ```

package/dist/content/agents/shared/user-question-protocol.md

@@ -16,6 +16,7 @@ This protocol defines how hatch3r agents and commands surface clarifying or tria
 
 - **Ambiguous requirement** — the request maps to two or more reasonable interpretations that produce different code.
 - **Irreversible decision** — deleting data, renaming a public API, dropping a column, force-pushing a branch.
+- **Unattested product decision** — the change deletes or transforms user data, or changes user-visible behavior beyond the issue's acceptance criteria, and no user statement (this session, the issue body, or a linked acceptance criterion) authorizes the choice. An agent-authored code comment, PR description, or reviewer note is not attestation — it is self-certification. Surface the ASK; a sub-agent returns `BLOCKED_AMBIGUITY`; an unattended run records the finding as `escalated` in the findings ledger (`rules/hatch3r-findings-ledger.md`) and exits PARTIAL — fail-closed, mirroring `commands/hatch3r-release.md` → "hold — never auto-publish".
 - **Branching path** — two or more viable approaches with materially different cost, scope, or risk.
 - **Conflicting constraints** — requirements that cannot all hold (e.g., "no new dependencies" and "use library X").
 - **Missing acceptance criteria** — no testable definition of done for the requested change.
@@ -110,12 +111,12 @@ The "Default if no response" line is mandatory in every plain-text fallback ques
 
 1. **Detect non-response.** If a question goes unanswered within the host runtime's question window (Claude Code: idle session timeout; Cursor: AskUserQuestion timeout; Copilot Workspace: prompt-cycle gap), or if the user replies "you decide" / "default" / empty, treat as non-response.
 2. **Apply the safe default.** Pick the option declared on the `Default if no response: <option number>` line — the lowest-blast-radius reversible choice the question's author named.
-3. **Log the default-taken decision.** Emit in the Iteration Summary §8 (Open Questions / Blockers) a single line: `Default applied: <question summary> → option <N> (<one-line reason>)`. This is the operational counterpart to the prose mandate — every agent / command ASK output that exercises the default MUST log the decision. The §8 line is a required field of the canonical Iteration Summary template (`rules/hatch3r-iteration-summary.md` → The 9 Sections, item 8), and the catching-gate ownership is named in `rules/hatch3r-clarification-default.md` → How to ask — those two files are the enforcing surface for this step.
+3. **Log the default-taken decision.** Emit in the Iteration Summary the `Default applied:` exception line (a registered line of the recap contract), one per default: `Default applied: <question summary> → option <N> (<one-line reason>)`. This is the operational counterpart to the prose mandate — every agent / command ASK output that exercises the default MUST log the decision. The `Default applied:` line is a registered exception line of the recap-contract Iteration Summary (`rules/hatch3r-iteration-summary.md` → Exception Lines), and the catching-gate ownership is named in `rules/hatch3r-clarification-default.md` → How to ask — those two files are the enforcing surface for this step.
 4. **Never silent-pick.** If no `Default if no response: <option>` line was emitted with the question (an authoring bug per the rules in this file), return `BLOCKED_AMBIGUITY` in the structured result rather than guessing.
 
-The §8 log is the audit-visible evidence that the default-if-no-response contract was honored; absence of the log when a default was applied is a P8 B1 gate failure. Runtime emission of the §8 line is orchestrator-produced interpreted markdown, so no static gate can verify it fired — D05 (prompt-engineering) and D13 (human-AI collaboration) audit-cycle spot checks plus the per-run Iteration Summary validation gate are the enforcement, not a compiled check.
+The `Default applied:` line is the audit-visible evidence that the default-if-no-response contract was honored; absence of the line when a default was applied is a P8 B1 gate failure. Runtime emission of the `Default applied:` line is orchestrator-produced interpreted markdown, so no static gate can verify it fired — D05 (prompt-engineering) and D13 (human-AI collaboration) audit-cycle spot checks plus the per-run Iteration Summary validation gate are the enforcement, not a compiled check.
 
-The contract has a single named owner so it is not re-declared per command: the always-on, `precedence: high` rule `rules/hatch3r-clarification-default.md` (`scope: always`) binds every `commands/hatch3r-*.md` orchestrator and mutating skill corpus-wide, and that rule's "How to ask" section is the catching gate. An individual command body therefore need not repeat the default-handling vocabulary to be bound by it — the rule + this protocol + the Iteration Summary §8 template are the three-anchor owner set, and a command inherits the contract by being in scope. Treat a command that *does* restate it as a convenience, not the source of truth.
+The contract has a single named owner so it is not re-declared per command: the always-on, `precedence: high` rule `rules/hatch3r-clarification-default.md` (`scope: always`) binds every `commands/hatch3r-*.md` orchestrator and mutating skill corpus-wide, and that rule's "How to ask" section is the catching gate. An individual command body therefore need not repeat the default-handling vocabulary to be bound by it — the rule + this protocol + the `Default applied:` exception line of the recap-contract Iteration Summary are the three-anchor owner set, and a command inherits the contract by being in scope. Treat a command that *does* restate it as a convenience, not the source of truth.
 
 ## Cross-Phase Aggregation
 

package/dist/content/checks/code-quality.md

@@ -50,3 +50,14 @@ Review criteria for evaluating code quality in pull requests.
 - `[RECOMMENDED]` No N+1 query patterns in data fetching code.
 - `[RECOMMENDED]` Large collections use pagination or streaming, not full in-memory loading.
 - `[RECOMMENDED]` Expensive operations (crypto, compression, network) are not performed synchronously in request handlers.
+
+## Decision Provenance
+
+- `[CRITICAL]` Every product-behavior assertion in the diff — a comment, commit message, or PR sentence claiming a choice about user data or user-visible behavior ("acceptable to drop", "users won't need", "safe to overwrite") — cites its source: issue number, acceptance-criterion line, or quoted user reply. An assertion with no citable source is self-certification: verdict REQUEST CHANGES plus an ASK to the user.
+- `[RECOMMENDED]` Migration and data-transform files name the approving decision (issue / acceptance criterion / ADR reference) in the file header comment.
+
+## Shared Contracts and Constants
+
+- `[CRITICAL]` A shared constant (rate, default, threshold, enum value) consumed by more than one feature has exactly one defining module; the diff introduces no second independent definition of the same value, and a changed value is edited at its single owner. Verify by grepping the constant name AND the literal value across the repo.
+- `[CRITICAL]` Every changed shared contract (exported symbol, persisted collection/field name, wire field, event name) has a consumer census in the implementation result: each repo-wide consumer of the old identifier is updated, guarded, or justified by name (`rules/hatch3r-contract-census.md`).
+- `[RECOMMENDED]` An intentional divergence from a shared constant's value carries an inline ADR comment naming the owner constant and the reason for the local value.

package/dist/content/checks/security.md

@@ -59,3 +59,8 @@ Review criteria for evaluating security posture in pull requests.
 
 - `[CRITICAL]` Error responses to clients do not include stack traces, internal paths, or database details.
 - `[RECOMMENDED]` Security-relevant errors (auth failures, permission denials) are logged with the five fields an incident responder needs — timestamp, actor/subject identifier, action attempted, resource, and outcome — and never the secret or credential that was rejected.
+
+## Environment Gating
+
+- `[CRITICAL]` Dangerous capabilities (debug endpoints, seed/reset scripts, auth bypasses, mock modes, destructive CLI verbs) are gated by an allowlist of named non-production environments — never by a `NODE_ENV !== 'production'` (or equivalent) denylist. An unset, misspelled, or unrecognized environment value takes the deny branch.
+- `[RECOMMENDED]` The application asserts at startup that its resolved environment value is a member of a closed known-environment enum and refuses to start on an unrecognized value.

package/dist/content/checks/testing.md

@@ -15,8 +15,10 @@ Review criteria for evaluating test coverage and quality in pull requests.
 - `[CRITICAL]` Every new public function or method has at least one unit test.
 - `[CRITICAL]` Code coverage does not decrease from the base branch. New code must be tested.
 - `[CRITICAL]` Bug fix PRs include a regression test that fails without the fix and passes with it.
+- `[CRITICAL]` E2E and integration inputs are non-degenerate: for each changed behavior, at least one test input activates the computation (non-zero rates/amounts, ≥2 records on merge/dedup paths, non-empty collections at every pipeline stage) and the assertion distinguishes the activated result from the no-op result. Named vectors: `rules/hatch3r-testing.md` → Degenerate-Input Guard.
 - `[RECOMMENDED]` Critical path functions (auth, payments, data mutations) have > 90% branch coverage.
 - `[RECOMMENDED]` Edge cases are explicitly tested: empty inputs, boundary values, error conditions, null/undefined.
+- `[RECOMMENDED]` Coverage claims name behaviors, not counts — "N passing" is evidence only when paired with which changed behaviors those N tests activate.
 
 ## Test Quality
 

package/dist/content/commands/board/pickup-delegation-multi.md

@@ -63,7 +63,7 @@ After the shared epic-level research, score each sub-issue individually and run
 
 ### 6b.3. Execute Level-by-Level With Parallel Sub-Agents
 
-Worktree isolation applies here identically to the batch path: when ≥2 implementers run concurrently in a level on a Tier 2/3 run and the platform writes into the orchestrator's tree, isolate each implementer per **Step 6c.3-iso** (`--isolate=auto|on|off`, default `auto`) and integrate via the merge protocol in Step 6b.4. Sub-issues in an epic share file overlap more often than standalone batch issues, so the missed-overlap risk that isolation removes is higher here.
+Worktree isolation applies here identically to the batch path: when ≥2 implementers run concurrently in a level on a Tier 2/3 run and the platform writes into the orchestrator's tree, isolate each implementer per **Step 6c.3-iso** (`--isolate=auto|on|off`, default `auto`) and integrate via the merge protocol in Step 6b.4. Sub-issues in an epic share file overlap more often than standalone batch issues, so the missed-overlap risk that isolation removes is higher here. Seam constraints apply identically to the epic path when sub-issues share a contract — assign per Step 6c.2 item 4.
 
 For each dependency level, starting at Level 1:
 
@@ -116,7 +116,7 @@ For batches of multiple standalone issues (selected via batch mode in Step 1d or
 2. Group issues by dependency level:
    - **Level 1:** Issues with no dependencies on other issues in the batch (can start immediately). Most standalone issues will be Level 1.
    - **Level N:** Issues that depend on other issues in levels < N.
-3. Within each level, all issues are parallelizable (no mutual dependencies — conflicts were moved to separate levels in Step 3).
+3. Within each level, all issues are parallelizable (no mutual dependencies — conflicts were moved to separate levels in Step 3); levels may be adjusted by the contract-overlap cross-check in Step 6c.2 item 4.
 
 ### 6c.2. Context Gathering (Parallel Researchers)
 
@@ -135,6 +135,13 @@ Unlike epics (which share a single researcher), standalone issues in a batch are
 
 3. **Await all researchers.** Collect structured outputs. Each researcher's output feeds exclusively into its corresponding implementer in Step 6c.3. For Tier 2/3 issues, present elicitation questions to the user and await answers before proceeding.
 
+4. **Contract-overlap cross-check + seam-owner assignment:** union the per-issue Breaking Change Candidates tables; any contract (matching location/symbol/name) appearing in ≥2 issues of the same level is a contract collision that Step 3 item 5 either predicted or missed. Resolve before dispatch:
+   - (a) exactly one issue — the one whose acceptance criteria REQUIRE the contract mutation — becomes the seam owner and lands emitter + all consumer reconciliation in one diff;
+   - (b) every peer issue's Step 6c.3 prompt gains the line `Seam constraint: contract <X> is owned by issue #<N> this batch — consume the current shape; do not mutate it`;
+   - (c) when two issues both require mutating the same contract, move the later one to the next dependency level so it consumes the owner's landed shape (`rules/hatch3r-contract-census.md` → Seam-Owner Protocol).
+
+   Record owner assignments; they are re-checked in Step 6c.4.
+
 ### 6c.3-iso. Optional Worktree Isolation (Parallel Implementers, Filesystem Platforms)
 
 Step 3 collision detection predicts file overlap and moves overlapping issues to sequential levels. That prediction is fallible: a missed overlap (Step 3.4) puts two implementers into the orchestrator's single working tree, where concurrent writes to the same file silently clobber each other before the Step 6c.4 post-hoc merge can run. Worktree isolation converts the *predicted* disjointness into *physical* disjointness — each implementer writes into its own `git worktree`, so two implementers cannot touch the same on-disk file even when Step 3 missed the overlap. The existing Step 6c.4 merge protocol becomes the integration step plus the residual-conflict handler for whatever Step 3 missed.
@@ -169,6 +176,7 @@ For each dependency level, starting at Level 1:
    - **Reference conventions** from `similar-implementation` output (Tier 2/3) — triggers the implementer's Convention Lock step.
    - **Resolved requirements** from `requirements-elicitation` answers (Tier 2/3).
    - **Blast radius data** from enhanced `codebase-impact` (Tier 3).
+   - **Seam constraints** from Step 6c.2 item 4 (when assigned).
    - Documentation references relevant to this issue.
    - Instruction to follow the **hatch3r-implementer agent protocol**.
    - All `scope: always` rule directives from `rules/` — subagents do not inherit rules automatically.
@@ -195,9 +203,10 @@ After all implementer sub-agents complete across all levels:
 2. **File conflict resolution:** When parallel sub-agents modify the same file, apply this resolution protocol:
    - **Disjoint regions:** Accept both changes (non-overlapping edits to different functions/sections).
    - **Overlapping regions:** If changes touch the same lines or function, merge manually using the sub-agent that modified the larger scope as the base, then apply the smaller-scope change on top. Run tests after merge.
-   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts.
+   - **Semantic conflicts:** If two sub-agents make contradictory changes to the same interface, type, or contract, halt and surface both changes to the user with the conflict description. Do not auto-resolve semantic conflicts. A semantic conflict on a contract with an assigned seam owner (Step 6c.2 item 4) means a peer violated its seam constraint — name the violating lane when surfacing.
    - **Prevention:** Step 3 (collision detection) should move file-overlapping issues to sequential dependency levels. Conflicts at this stage indicate a missed overlap in Step 3.4.
-3. Verify no regressions between parallel sub-agent outputs.
+3. **Consumer-census verification per lane:** read each implementer's `Consumer census` field. Any `unreconciled` without a named justification → spawn `hatch3r-fixer` for that lane before the Stage-1 review. Then run the cross-lane check: for every contract a seam owner changed, grep the OTHER lanes' diffs for the old identifier — a peer still emitting or reading the old shape violated its seam constraint; route the reconciliation to the seam owner (one diff owns the contract), never patch it in the merge.
+4. Verify no regressions between parallel sub-agent outputs.
 
 ### 6c.5. Post-Implementation Quality Pipeline
 
@@ -206,13 +215,13 @@ After all implementations complete, run the two-stage quality pipeline across th
 **Stage 1 — Review Loop (sequential):**
 
 1. Spawn **`hatch3r-reviewer`** — code review of ALL changes across the batch. Include the full diff and acceptance criteria for each issue. The reviewer sub-agent output MUST include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 4 can evaluate it deterministically.
-2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes — append the W1 write-ahead rows before the fixer dispatch (`rules/hatch3r-findings-ledger.md` → Write Points). When fixes touch shared or public interfaces, also include:
    - **Blast radius data** from Step 6c.2 (if available) — so the fixer knows which consumers and contracts must be preserved.
    - **Reference conventions** from Step 6c.2 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the confidence-aware gate passes. Evaluate the gate per the canonical **Confidence-Aware Review Gate** in `agents/shared/confidence-gate.md`, passing in the resolved `--confidence-floor` (`any` | `medium` | `high`) routed here from `hatch3r-board-pickup` → Confidence Floor. At the default `any` floor: **0 Critical + 0 Warning AND reviewer confidence != low**; if reviewer confidence is low with no Critical/Warning findings, trigger a second reviewer pass before exiting and do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS. At floor `medium` the pass surface is unchanged; at floor `high` a `medium`-confidence clean verdict also forces a second pass (and any low-confidence finding triggers an ASK) — apply the floor-tier branches from the shared gate, do not collapse them to the `any` row.
    After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
-5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed — the ASK lists the open `finding_id`s with legal closures; reconcile the ledger to the run-exit invariant (W3) on exit (`rules/hatch3r-findings-ledger.md` → W3 loop-exit reconciliation); unattended runs record open findings as `escalated` and exit PARTIAL.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**
 
@@ -225,9 +234,10 @@ Launch as many independent sub-agents in parallel as the platform supports.
 **Always evaluate (spawn when applicable):**
 - **hatch3r-docs-writer** — spawn when any changes affect public APIs, architectural patterns, or user-facing behavior.
 
-**Conditional specialists (spawn when triggered by any issue in the batch):**
+**Triggered specialists (spawn when triggered by any issue in the batch):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-ui** (CQ1) — spawn when any issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-ui** (CQ1, mandatory-on-match) — spawn when any implementer's changed files across the batch match the `hatch3r-ui` row of the specialist trigger table (`shouldTriggerSpecialist` / `SPECIALIST_TRIGGER_TABLE` in `src/pipeline/pipelineContext.ts`; prose mirror: `rules/hatch3r-agent-orchestration.md` → Phase 4 Specialist Trigger Table). A match at Tier 2/3 mandates a dedicated `hatch3r-ui` instance regardless of issue labels — skipping it is a gate failure. `area:ui` / `area:a11y` labels are an early planning signal, not a dispatch gate: their absence never skips a matched specialist.
+- **hatch3r-ux** (CQ2, mandatory-on-match) — spawn when any changed file in the batch matches the `hatch3r-ux` row of the same trigger table (flow / route-transition / modal / error-state files, microcopy/i18n strings). When triggered at Tier 2/3, a dedicated `hatch3r-ux` instance is a hard mandate (never merged into the `hatch3r-ui` spawn).
 - **hatch3r-performance** (CQ7) — spawn when any issue has `area:performance` label.
 
 Await all specialist sub-agents. Apply their feedback before proceeding to Step 7.

package/dist/content/commands/board/pickup-delegation.md

@@ -72,13 +72,13 @@ After implementation completes, run the two-stage quality pipeline. Use the Task
 **Stage 1 — Review Loop (sequential):**
 
 1. Spawn **`hatch3r-reviewer`** — code review of all changes. Include the diff and acceptance criteria in the prompt. The reviewer sub-agent output MUST include a top-level `confidence: high | medium | low` field (not just per-finding) so the gate in step 4 can evaluate it deterministically.
-2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes. When fixes touch shared or public interfaces, also include:
+2. If the reviewer reports Critical or Warning findings, spawn **`hatch3r-fixer`** with the reviewer output to apply fixes — append the W1 write-ahead rows before the fixer dispatch (`rules/hatch3r-findings-ledger.md` → Write Points). When fixes touch shared or public interfaces, also include:
    - **Blast radius data** from Step 6a.1 (if available) — so the fixer knows which consumers and contracts must be preserved.
    - **Reference conventions** from Step 6a.1 (if available) — so the fixer maintains established patterns when applying fixes.
 3. Re-spawn **`hatch3r-reviewer`** to verify fixes.
 4. Repeat steps 2-3 for a maximum of **3 iterations** until the confidence-aware gate passes. Evaluate the gate per the canonical **Confidence-Aware Review Gate** in `agents/shared/confidence-gate.md`, passing in the resolved `--confidence-floor` (`any` | `medium` | `high`) routed here from `hatch3r-board-pickup` → Confidence Floor. At the default `any` floor: **0 Critical + 0 Warning AND reviewer confidence != low**; if reviewer confidence is low with no Critical/Warning findings, trigger a second reviewer pass before exiting and do not exit until the second pass returns non-low confidence OR the user explicitly accepts the low-confidence PASS. At floor `medium` the pass surface is unchanged; at floor `high` a `medium`-confidence clean verdict also forces a second pass (and any low-confidence finding triggers an ASK) — apply the floor-tier branches from the shared gate, do not collapse them to the `any` row.
    After each reviewer iteration, assess the reviewer's findings confidence: if the reviewer rates any finding as low-confidence, flag it separately in the ASK prompt so the user can prioritize human review of uncertain findings.
-5. If still not clean after 3 iterations, **ASK** the user how to proceed.
+5. If still not clean after 3 iterations, **ASK** the user how to proceed — the ASK lists the open `finding_id`s with legal closures; reconcile the ledger to the run-exit invariant (W3) on exit (`rules/hatch3r-findings-ledger.md` → W3 loop-exit reconciliation); unattended runs record open findings as `escalated` and exit PARTIAL.
 
 **Stage 2 — Final Quality (parallel, after review loop is clean):**
 
@@ -91,9 +91,10 @@ Launch as many independent sub-agents in parallel as the platform supports.
 **Always evaluate (spawn when applicable):**
 - **hatch3r-docs-writer** — spawn when changes affect public APIs, architectural patterns, or user-facing behavior. Skip silently if no documentation impact.
 
-**Conditional specialists (spawn when triggered):**
+**Triggered specialists (spawn when triggered):**
 - **hatch3r-lint-fixer** — spawn when lint errors are present after implementation.
-- **hatch3r-ui** (CQ1) — spawn when issue has `area:ui` or `area:a11y` labels.
+- **hatch3r-ui** (CQ1, mandatory-on-match) — spawn when the implementer's changed files match the `hatch3r-ui` row of the specialist trigger table (`shouldTriggerSpecialist` / `SPECIALIST_TRIGGER_TABLE` in `src/pipeline/pipelineContext.ts`; prose mirror: `rules/hatch3r-agent-orchestration.md` → Phase 4 Specialist Trigger Table). A match at Tier 2/3 mandates a dedicated `hatch3r-ui` instance regardless of issue labels — skipping it is a gate failure. `area:ui` / `area:a11y` labels are an early planning signal, not a dispatch gate: their absence never skips a matched specialist.
+- **hatch3r-ux** (CQ2, mandatory-on-match) — spawn when the changed files match the `hatch3r-ux` row of the same trigger table (flow / route-transition / modal / error-state files, microcopy/i18n strings). When triggered at Tier 2/3, a dedicated `hatch3r-ux` instance is a hard mandate (never merged into the `hatch3r-ui` spawn).
 - **hatch3r-performance** (CQ7) — spawn when issue has `area:performance` label or changes touch hot paths.
 
 Each specialist sub-agent prompt MUST include:

package/dist/content/commands/hatch3r-api-spec.md

@@ -30,7 +30,7 @@ sub_agents_spawned:
 | 3. Spec Generation | `hatch3r-docs-writer` | No | Yes |
 | 4. Validation | `hatch3r-reviewer` | No | Yes (if validate mode) |
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes, deterministic aggregation, no shared mutable state.
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): every parallel fan-out above holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 # API Specification Generator — OpenAPI from Code or Code-vs-Spec Drift Detection
 
@@ -88,7 +88,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the Step 8 output summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
+Post-execution, the delta figure lands in the Iteration Summary recap (cost facet); full blocks surface on the `Cost:` exception line beyond ±25%, per `rules/hatch3r-cost-visibility.md`. Token telemetry sources from `src/pipeline/observability.ts`.
 
 ### Effort Override (Decision 17)
 
@@ -350,30 +350,18 @@ api-spec is long-running — a Tier 3 full-codebase scan runs the hatch3r-resear
 
 ## Iteration Summary (mandatory output)
 
-Emit the canonical 9-section iteration summary per `rules/hatch3r-iteration-summary.md` as the final user-facing output. The validation gate at `.claude/rules/capability-lifecycle.md` blocks SUCCESS declarations without this block (CONSTITUTION §6 Decision 23).
-
-The 9 sections:
-
-1. **Request** — verbatim restatement of the user's ask in one sentence.
-2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` plus the `cost_estimate` / `cost_actuals` / `delta` blocks (see Cost Visibility below).
-3. **Web Research** — every URL fetched with access date + trust tier per `agents/shared/rigor-contract.md` (0 acceptable when no research was needed).
-4. **Files Mutated** — list with diff summary (lines added / removed / files created).
-5. **Gates Passed / Failed** — explicit list per `.claude/rules/capability-lifecycle.md` Gate Checklist.
-6. **Pillar Impact Attribution** — `progress_toward_pillar: <axis>.<pillar_id>+<delta>` per CONSTITUTION §6 Decision 17.
-7. **Verification Commands** — exact commands run with exit codes plus key output lines (≤200 chars).
-8. **Open Questions / Blockers** — explicit `None` if fully closed.
-9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run per `rules/hatch3r-learning-system.md`.
+Close the run with the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`: a 1–2 line recap (status, outcome, files · sub-agents · gates · cost delta) plus every exception line whose firing condition holds — silence asserts the default. Omitting the recap fails that rule's Validation Gate (CONSTITUTION §6 Decision 23, superseded in place 2026-07-06).
 
 ### Cost Visibility (Decision 24)
 
-> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; both land in Section 2 above.
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Cost Estimate for the 5-field `cost_estimate` schema and the post-execution `cost_actuals` + `delta` contract; the delta figure lands in the Iteration Summary recap (cost facet); full blocks surface on the `Cost:` exception line beyond ±25%, per `rules/hatch3r-cost-visibility.md`.
 
 ## Cost estimate (Decision 24)
 
 This command emits cost transparency per `rules/hatch3r-cost-visibility.md` and CONSTITUTION §6 Decision 24/29:
 
 - **Pre-execution `cost_estimate`** — emitted in Step 0.5 before the first researcher dispatch (Step 3 endpoint discovery).
-- **Post-execution `cost_actuals` + `delta`** — appended to the Step 8 output summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+- **Post-execution `cost_actuals` + `delta`** — the delta figure lands in the Iteration Summary recap (cost facet); full blocks surface on the `Cost:` exception line beyond ±25%, per `rules/hatch3r-cost-visibility.md`.
 
 Per-tier `expected_sa_count` calibration (from frontmatter `sub_agents_spawned.count: 3` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 0 (inline single-endpoint edit); Tier 2 ≈ 2 (researcher scans routes + docs-writer assembles); Tier 3 up to 3 (researcher + docs-writer + reviewer validation in validate/drift mode). Deltas beyond 25% absolute value carry `flagged_for_review: true`. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.ts`.
 

package/dist/content/commands/hatch3r-auth-scaffold.md

@@ -186,30 +186,17 @@ Run the project verification gates and record exit codes: `npm test` (or the pro
 
 ### Iteration Summary (mandatory output)
 
-Emit the canonical iteration summary per `rules/hatch3r-iteration-summary.md`:
+Close the run with the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`: a 1–2 line recap (status, outcome, files · sub-agents · gates · cost delta) plus every exception line whose firing condition holds — silence asserts the default. Omitting the recap fails that rule's Validation Gate (CONSTITUTION §6 Decision 23, superseded in place 2026-07-06).
+
+Worked example for this domain:
 
 ```markdown
 ## Iteration Summary
 
-**Status:** SUCCESS | PARTIAL | FAILED | BLOCKED
-**Outcome:** {one sentence — e.g., "Scaffolded OAuth 2.1 + OIDC + hashed-PAT auth for orders-api; security gate PASS."}
-
-**Done:**
-- src/auth/oauth/* → authorization-code + PKCE flow via hatch3r-implementer (proof: {id})
-- src/auth/oidc/* → ID-token validation (iss/aud/nonce/JWKS) via hatch3r-implementer (proof: {id})
-- src/auth/pat/* → Argon2id-hashed PAT issue/verify via hatch3r-implementer (proof: {id})
-
-**Not Done / Deferred / Unverified:**
-- `.env.example` placeholders — populate real issuer + client_secret before first run
-- (or: `None — full scope completed`)
-
-**Open Questions / Blockers:**
-- (or: `None`)
-
-**Fan-out + Cost:** sub_agents_spawned: { count, rationale } + cost_estimate / cost_actuals / delta
-**Pillar Impact Attribution:** progress_toward_pillar: content-quality.CQ3+{delta}
-**Confidence:** {high | medium | low} — {basis from implementer output + security gate verdict}
-**Suggested Next Action:** {one line — e.g., "Populate .env, then wire the OIDC callback route into the service router."}
+**SUCCESS** — Scaffolded OAuth 2.1 + OIDC + hashed-PAT auth for orders-api; security gate PASS on both modes.
+files 9 (+412/−0) · sa 4/4 · gates 3/3 · cost Δ+6% tok / Δ+2% min · tier 2
+Not done: `.env.example` placeholders — deferred: populate real issuer + client_secret before first run
+Next: wire the OIDC callback route into the service router.
 ```
 
 Status decision rules: