hatch3r 2.1.0 → 2.2.0

package/dist/content/rules/hatch3r-iteration-summary.md

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-iteration-summary
 type: rule
-description: 9-section iteration summary template emitted by every orchestrator command and meaningful skill run — status, outcome, done/not-done, fan-out + cost, verifications, gates, pillar impact, open questions, learnings captured.
+description: Recap-contract iteration summary — every orchestrator command and meaningful skill run closes with a 1-2 line recap (status, outcome, files/sub-agents/gates/cost-delta telemetry) plus exception lines that fire only on non-default outcomes; silence asserts the default.
 tags: [iteration, summary, telemetry, floor:content-quality]
 precedence: high
 scope: always
@@ -12,46 +12,56 @@ scope: always
 
 ## When Required
 
-Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) AND every meaningful skill run (`/h4tcher-*` or `/hatch3r-*` that mutates state) MUST emit the 9-section block as the final user-facing output.
+Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) AND every meaningful skill run (`/h4tcher-*` or `/hatch3r-*` that mutates state) MUST close with the recap-contract Iteration Summary as the final user-facing output. The block opens with the literal heading `## Iteration Summary` — the stable extraction anchor for downstream consumers. Governance anchor: CONSTITUTION §6 Decision 23, superseded in place 2026-07-06 (the recap contract replaces the former sectioned template).
 
 ## Pre-Execution Cost Preview
 
-Every orchestrator command MUST emit a one-block cost preview BEFORE its first sub-agent dispatch (Decision 24 at the user-facing surface), so the user sees the cost envelope before any agent spawns:
+Every orchestrator command MUST emit the pre-dispatch cost preview defined at `rules/hatch3r-cost-visibility.md` → Pre-Execution Estimate BEFORE its first sub-agent dispatch (Decision 24 at the user-facing surface). That rule owns the preview schema — do not restate it here. Commands wire the preview as an explicit pre-dispatch step (e.g., `commands/hatch3r-workflow.md` Step 0.5); the recap's cost facet closes the loop by reporting deltas against it.
 
-```yaml
-cost_preview:
-  expected_sa_count: <integer>
-  estimated_input_tokens_static_frame: <integer>
-  triage_tier: 1 | 2 | 3
-  web_research_budget: <integer queries, 0 if none>
-  estimated_duration_min: <integer>
+## The Recap
+
+Under the `## Iteration Summary` heading, the body is a 1-2 line recap:
+
+```
+Line 1:  **<SUCCESS|PARTIAL|FAILED|BLOCKED>** — <one outcome sentence naming the work object and end state>
+Line 2:  files <N> (+<added>/−<removed>) · sa <actual>/<expected> · gates <passed>/<run> · cost Δ<tok%>% tok / Δ<min%>% min · tier <1|2|3>
 ```
 
-Calibrate the fields to the triage tier (see `rules/hatch3r-deep-context`); source token estimates from `src/pipeline/observability.ts` / `src/pipeline/costEstimator.ts`. The post-run §2 "Fan-out + Cost" section closes the loop by reporting actuals + `delta_percent` against this preview. Commands wire the preview as an explicit pre-dispatch step (e.g., `commands/hatch3r-workflow.md` Step 0.5).
+Status enum reused from `agents/shared/quality-charter.md` §11. Facet order fixed (machine-parseable). `+<added>/−<removed>` are diff line totals (lines added/removed) across the changed files. `sa <actual>/<expected>` carries the fan-out count; **rationale stays a dispatch-time emission** per `rules/hatch3r-fan-out-discipline.md` (validate-fanout-emission unaffected). Merge condition: line 2 folds into line 1 parenthesized when ≥3 facets at rest (files 0, sa 0, gates 0); at-rest facets fold away except `files`, `sa`, and `tier` — e.g. `**SUCCESS** — Explained adapter precedence (read-only: files 0 · sa 0 · tier 1)`.
+
+## Exception Lines
+
+Below the recap, a line appears ONLY when its firing condition holds. An absent exception line is a positive claim of its Silent-when default — silence asserts the default. Each entry is a single line; `Cost:` is the one multi-line exception (its fenced YAML follows the line).
 
-## The 9 Sections
+| Line | Format | Fires when | Gate preserved | Silent-when |
+|---|---|---|---|---|
+| Not done | `Not done: <item> [— deferred: <why> \| unverified: <what>]; …` | any scope item not done/deferred/unverified | charter honesty; handoff Work Remaining | full scope completed |
+| Blockers | `Blockers: <blocker or open question>; …` | any open blocker | old §8; handoff Blockers | none open |
+| Open findings | `Open findings: <finding_id> <sev> — <disposition>; …` | any findings-ledger row folds non-terminal, or terminal as `escalated`/`surfaced`, at recap time | findings-ledger run-exit invariant (`rules/hatch3r-findings-ledger.md`) | no ledger file for this run, or every row folds to done/deferred/declined/accepted-risk/already-resolved |
+| Default applied | `Default applied: <question summary> → option <N> (<one-line reason>)` — format unchanged from the superseded template, one per default | ASK default exercised | **P8 B1** | no default taken |
+| Gates failed | `Gates failed: <gate>: <one-line cause>; …` | recap gates shows failure | P1 actionability | all gates passed |
+| Cost | `Cost: flagged_for_review: true` + fenced cost_actuals/delta YAML (the one multi-line exception) | any delta > 25% absolute | **Decision 24** / cost-visibility AC5 | deltas within ±25% (recap Δ facet suffices; telemetry persists regardless) |
+| Confidence | `Confidence: <high\|medium\|low> — <basis>[. <D13 action string verbatim>]` | review loop ran OR confidence < high OR status ≠ SUCCESS | D13 mapping; reviewer-calibration; anti-inflation | SUCCESS + high + direct measurement + no loop |
+| User-Accepted Bypass | `User-Accepted Bypass: yes — <verbatim reason ≤200 chars>` + JSONL append | accepted low-confidence PASS | D13 bypass record | no bypass |
+| Learnings | `Learnings: consulted <ids> · surfaced <ids> · captured <ids>` (omit empty facets) | any facet non-empty | learning-system gates | no INDEX / zero matches / nothing captured |
+| Tier | `formatTierUpgradeNote` output verbatim (one-liner, `src/pipeline/pipelineContext.ts:647-655`) | mid-run tier upgrade | D7-14 | no upgrade |
+| Duplication | `Duplication: <n> match(es), closest <path>, overlap <none\|partial\|high>` or `Duplication: scan skipped (<reason>)` | scan matched OR skipped | anti-duplication silent-failure | scan ran clean |
+| Next (optional, never gated) | `Next: <one-line suggested action>` | concrete next step exists | charter optional-sections precedent | nothing to suggest |
 
-1. **Request** — verbatim restatement of the user's ask in one sentence
-2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` + `cost: { estimated_input_tokens, actual_input_tokens, estimated_duration_min, actual_duration_min, delta_percent }`
-3. **Web Research** — every URL fetched with access date + trust tier (per `agents/shared/rigor-contract.md`); count 0 acceptable if 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 Decision 17
-7. **Verification Commands** — exact commands run with exit codes + key output lines (≤200 chars)
-8. **Open Questions / Blockers** — explicit None if fully closed. When an ASK gate's default-if-no-response was exercised this run, this section MUST carry one `Default applied: <question summary> → option <N> (<one-line reason>)` line per default taken (the operational counterpart to `agents/shared/user-question-protocol.md` → Operationalising Default-if-no-Response step 3); absence of the line when a default was applied is a P8 B1 gate failure
-9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run; cross-reference `rules/hatch3r-learning-system.md`
+Charter-field mapping: Status + Outcome → line 1; Done → outcome + files facet; the rest → exception lines. Learning-system's "citing zero when `applies-to` matched is a gate failure" becomes fired-condition-with-no-line.
 
-## Required Fields per quality-charter §11
+## Handoff Mapping
 
-- **Status:** closed enum SUCCESS | PARTIAL | FAILED | BLOCKED
-- **Outcome:** one sentence
-- **Done / Not Done / Deferred / Unverified:** explicit lists
-- **Confidence + basis:** one of direct measurement | sampled observation | inference from analogue
-- **Consulted Learnings:** IDs of `.hatch3r/learnings/` entries the bound agents (implementer / reviewer / researcher / fixer) read this run per the `rules/hatch3r-learning-system.md` Mandatory Consultation Gate; `none` when INDEX.md is absent or zero `applies-to` rows matched. Distinct from §9 Learnings Captured (entries written this run). Citing zero when `applies-to` matched is a gate failure.
+Handoff surfaces (`rules/hatch3r-handoff-readiness.md`, `skills/hatch3r-handoff-prepare/SKILL.md`, `agents/hatch3r-handoff-preparer.md`) derive their fields from the recap:
+
+- **Work Done** ← recap outcome (line 1) + files facet
+- **Work Remaining** ← `Not done:` line; absent ⇒ `None — full scope completed`
+- **Blockers** ← `Blockers:` line; absent ⇒ `None`
+- **Open Findings** ← `Open findings:` line; absent ⇒ none
 
 ## Confidence-to-Action Mapping (D13)
 
-When a review loop ran this turn, the §5 Confidence line MUST append the action guidance for the loop's terminal confidence level (`reviewLoopConfidence` in `src/pipeline/reviewLoop.ts`). This is the canonical confidence-to-action text — `confidenceExplanation` in `src/pipeline/reviewLoop.ts` returns these exact three strings, so the typed helper and this user-facing rule stay byte-identical (the strings are no longer reachable only from a unit test, closing D13-SA13.2-F2):
+When a review loop ran this turn, the `Confidence:` exception line MUST append the action guidance for the loop's terminal confidence level (`reviewLoopConfidence` in `src/pipeline/reviewLoop.ts`). This is the canonical confidence-to-action text — `confidenceExplanation` in `src/pipeline/reviewLoop.ts` returns these exact three strings, so the typed helper and this user-facing rule stay byte-identical (the strings are no longer reachable only from a unit test, closing D13-SA13.2-F2):
 
 - **high** — The fix was correct on the first attempt. Human review is optional but recommended for critical code paths.
 - **medium** — The fix required one round of corrections, which is normal for moderately complex changes. A brief human review is recommended.
@@ -61,7 +71,7 @@ Omit the mapping when no review loop ran (e.g. a Tier 1 typo edit with no review
 
 ## Pattern Rationale (D13 in-flow teaching — default-ON at Tier ≥ 2)
 
-In-flow teaching is the default, not opt-in: at Tier ≥ 2 (non-trivial / novel orchestrations) the orchestrator MUST emit a `## Pattern Rationale` block before the Iteration Summary, teaching the user each framework pattern applied this turn — closing the knowledge-transfer gap surfaced by D13 SA13.4 (F5/F6: sub-agent reasoning is summarized away before it reaches the user, so the user learns nothing unless the orchestrator teaches at its own surface). One SHORT line per applied pattern with rule citation + pillar served + plain-language reason:
+At Tier ≥ 2 the orchestrator MUST emit a `## Pattern Rationale` block before the Iteration Summary — one SHORT line per framework pattern applied this turn (rule citation + pillar served + plain-language reason), so sub-agent reasoning reaches the user instead of being summarized away (D13 SA13.4 F5/F6):
 
 ```
 pattern_rationale:
@@ -71,38 +81,26 @@ pattern_rationale:
     why: <≤1 sentence plain language>
 ```
 
-Emission policy:
-
-- **Default-ON at Tier ≥ 2:** emit one line for each mutated file that applies a named rule the user did not request explicitly. A Tier ≥ 2 turn that applied at least one such pattern and omits the block is a P5 gate failure (same enforcement class as the §9 Validation Gate).
-- **Tier 1 exemption:** Tier 1 trivial edits (typo, frontmatter-only, single-line clarification) skip the block — no pattern is taught, so no field appears, preserving token budget. This mirrors the Tier-1 exemption in `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header).
-- **No-pattern case:** when a Tier ≥ 2 turn applied no named rule beyond what the user requested, emit `pattern_rationale: none (no implicit pattern applied)` rather than dropping the field, so the block's absence is never ambiguous.
-- **`--quiet` opt-out:** the `--quiet` CLI flag suppresses the block at the user surface (same precedent as cost data in `rules/hatch3r-cost-visibility.md` → "appears in user-facing iteration summaries by default … suppressing via the `--quiet` CLI flag"). Suppression is user-surface only; it does not weaken the Tier ≥ 2 emission contract for default (non-`--quiet`) runs.
+Emission policy: one line per mutated file that applies a named rule the user did not request explicitly; a Tier ≥ 2 turn that applied at least one such pattern and omits the block is a P5 gate failure (same enforcement class as the Validation Gate below). Tier 1 trivial edits (typo, frontmatter-only, single-line clarification) skip the block, mirroring the Tier-1 exemption in `rules/hatch3r-agent-orchestration.md` → Per-Turn Pipeline-State Header. When a Tier ≥ 2 turn applied no named rule beyond the request, emit `pattern_rationale: none (no implicit pattern applied)` so absence is never ambiguous. A triggered plan/act split (`agents/shared/efficiency-patterns.md` P4) is recorded here as an entry carrying `plan_act_split: triggered`; a skipped split stays silent — silence asserts the skip. The `--quiet` CLI flag suppresses the block at the user surface only (same precedent as cost data in `rules/hatch3r-cost-visibility.md`); suppression does not weaken the Tier ≥ 2 emission contract for default runs.
 
 ## User-Accepted Bypass Record (D13)
 
-When the user explicitly accepts a low-confidence PASS at an ASK checkpoint (per the gate-failure rule in the Confidence Propagation Contract used by every core orchestrator), the orchestrator MUST:
-
-1. Emit `User-Accepted Bypass: yes` in §8 (Open Questions / Blockers) with the bypass reason verbatim from the user reply.
-2. Append a single line to `.hatch3r/bypass-log.jsonl` (one JSON object per line — append-only, never rewritten):
+When the user explicitly accepts a low-confidence PASS at an ASK checkpoint (per the Confidence Propagation Contract used by every core orchestrator), the orchestrator MUST (1) emit the `User-Accepted Bypass:` exception line with the bypass reason verbatim from the user reply, and (2) append one JSON object line to `.hatch3r/bypass-log.jsonl` (append-only, never rewritten; atomic append via the `src/merge/safeWrite.ts` pattern — temp+rename then concat):
 
 ```json
-{"ts": "<ISO-8601>", "command": "<hatch3r-* name>", "verdict": "low", "user_reason": "<verbatim ≤200 chars>", "files": ["<paths>"], "session_id": "<id>"}
+{"ts": "<ISO-8601 UTC>", "command": "<hatch3r-* name>", "verdict": "low", "user_reason": "<verbatim ≤200 chars, no PII>", "files": ["<paths>"], "session_id": "<host session id, else unknown>"}
 ```
 
-Schema: `ts` ISO-8601 UTC timestamp; `command` the orchestrator command id; `verdict` always `low` (no bypass on high/medium per the contract); `user_reason` the user's verbatim acceptance string (truncated at 200 chars, no PII); `files` mutated file list; `session_id` the host runtime's session id when available, `unknown` otherwise. Atomic append via `src/merge/safeWrite.ts` pattern (temp+rename then concat). Absence of the line on a recorded bypass is a P5 gate failure.
+Absence of the line on a recorded bypass is a P5 gate failure.
 
 ## Validation Gate
 
-A skill or command that omits the 9-section block fails the lifecycle gate (`.claude/rules/capability-lifecycle.md`). Prose substitution is rejected. The orchestrator catches the omission before declaring SUCCESS.
+A run fails the gate when the recap is missing, when any registry row's firing condition holds with no corresponding exception line, or when prose is substituted for the recap grammar. Registry-row checking is an explicit pre-status step: before declaring status, the orchestrator walks the table above and emits each line whose firing condition holds — the omission is caught before SUCCESS is declared.
 
 ## Emission-Rate Telemetry (current status: per-run gate only; cross-run rate not yet wired)
 
-The validation gate above asserts the 9-section block is present per run. It does NOT measure the emission rate across runs, and no automated cross-run measurement exists today.
-
-The SPACE-shaped activity/performance instrumentation (`src/pipeline/spaceTelemetry.ts`, Decision 24 sibling of cost-visibility) provides the recording primitive `recordSpaceMetric`, the in-process aggregator `getSpaceSummary`, and the across-runs reader `loadSpaceMetricsFromDisk`, but they are not invoked on the iteration-summary path: orchestrator commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, and no command, skill, hook, or `src/` code emits an `iterationSummaryEmitted` metric. The cross-run emission-rate loop is therefore unwired — a future capability, not a live measurement (origin: D10-SA10.8-F-6; gap corrected D10-18). The module records on the `activity` and `performance` axes only; its `satisfaction` and `communication` axes are reserved with no feeder, so "SPACE" names the data shape, not full five-axis coverage (D10-40).
-
-To wire it, a host-runtime bridge (a Claude Code / Cursor / Copilot post-turn hook or an MCP shim) would need to call `recordSpaceMetric({ metricId: "iterationSummaryEmitted", axis: "activity", value: <1 if the 9-section block was produced else 0> })` after each orchestrator/meaningful-skill turn, persisting one JSONL line per run to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; the audit cycle could then read the persisted JSONL across runs via `loadSpaceMetricsFromDisk` + `summarizeSpaceMetricRecords` (NOT `getSpaceSummary`, which sees only the current process's ring buffer) to check the CONSTITUTION §2 P5 "Sub-agent count emission on delegating artifacts: 100%" target against observed runs instead of only mandating it. `recordSpaceMetric` already honours the Silent Failure Contract (telemetry I/O routes through `src/pipeline/failureLog.ts` and never throws), so building the bridge adds no failure surface. Until that bridge ships, P5 emission compliance is enforced by the per-run validation gate above plus audit-cycle spot checks, not by an aggregate metric.
+The Validation Gate asserts recap presence per run; no automated cross-run emission-rate measurement exists today. `src/pipeline/spaceTelemetry.ts` provides `recordSpaceMetric`, `loadSpaceMetricsFromDisk`, and `summarizeSpaceMetricRecords`, but nothing on the iteration-summary path invokes them — commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, so the cross-run loop is a future capability, not a live measurement (origin D10-SA10.8-F-6; gap corrected D10-18). The module records only the `activity` and `performance` axes; `satisfaction` and `communication` are reserved with no feeder, so "SPACE" names the data shape, not five-axis coverage (D10-40). Wiring requires a host-runtime post-turn bridge emitting an `iterationSummaryEmitted` metric to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; until then, P5 emission compliance rests on the per-run gate plus audit-cycle spot checks.
 
 ## Pillar Service
-- P5 — standardised reporting prevents drift across orchestrators
-- P7 — cost section surfaces token + duration deltas to user per Decision 24
+- P5 — one standardised recap plus an auditable exception-line registry prevents drift across orchestrators
+- P7 — the recap cost facet surfaces token + duration deltas per Decision 24 at a fraction of the former template's token footprint

package/dist/content/rules/hatch3r-iteration-summary.mdc

@@ -1,7 +1,7 @@
 ---
 id: hatch3r-iteration-summary
 type: rule
-description: 9-section iteration summary template emitted by every orchestrator command and meaningful skill run — status, outcome, done/not-done, fan-out + cost, verifications, gates, pillar impact, open questions, learnings captured.
+description: Recap-contract iteration summary — every orchestrator command and meaningful skill run closes with a 1-2 line recap (status, outcome, files/sub-agents/gates/cost-delta telemetry) plus exception lines that fire only on non-default outcomes; silence asserts the default.
 tags: [iteration, summary, telemetry, floor:content-quality]
 precedence: high
 alwaysApply: true
@@ -12,46 +12,56 @@ alwaysApply: true
 
 ## When Required
 
-Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) AND every meaningful skill run (`/h4tcher-*` or `/hatch3r-*` that mutates state) MUST emit the 9-section block as the final user-facing output.
+Every orchestrator command (`commands/hatch3r-*.md` with `orchestrator: true`) AND every meaningful skill run (`/h4tcher-*` or `/hatch3r-*` that mutates state) MUST close with the recap-contract Iteration Summary as the final user-facing output. The block opens with the literal heading `## Iteration Summary` — the stable extraction anchor for downstream consumers. Governance anchor: CONSTITUTION §6 Decision 23, superseded in place 2026-07-06 (the recap contract replaces the former sectioned template).
 
 ## Pre-Execution Cost Preview
 
-Every orchestrator command MUST emit a one-block cost preview BEFORE its first sub-agent dispatch (Decision 24 at the user-facing surface), so the user sees the cost envelope before any agent spawns:
+Every orchestrator command MUST emit the pre-dispatch cost preview defined at `rules/hatch3r-cost-visibility.md` → Pre-Execution Estimate BEFORE its first sub-agent dispatch (Decision 24 at the user-facing surface). That rule owns the preview schema — do not restate it here. Commands wire the preview as an explicit pre-dispatch step (e.g., `commands/hatch3r-workflow.md` Step 0.5); the recap's cost facet closes the loop by reporting deltas against it.
 
-```yaml
-cost_preview:
-  expected_sa_count: <integer>
-  estimated_input_tokens_static_frame: <integer>
-  triage_tier: 1 | 2 | 3
-  web_research_budget: <integer queries, 0 if none>
-  estimated_duration_min: <integer>
+## The Recap
+
+Under the `## Iteration Summary` heading, the body is a 1-2 line recap:
+
+```
+Line 1:  **<SUCCESS|PARTIAL|FAILED|BLOCKED>** — <one outcome sentence naming the work object and end state>
+Line 2:  files <N> (+<added>/−<removed>) · sa <actual>/<expected> · gates <passed>/<run> · cost Δ<tok%>% tok / Δ<min%>% min · tier <1|2|3>
 ```
 
-Calibrate the fields to the triage tier (see `rules/hatch3r-deep-context`); source token estimates from `src/pipeline/observability.ts` / `src/pipeline/costEstimator.ts`. The post-run §2 "Fan-out + Cost" section closes the loop by reporting actuals + `delta_percent` against this preview. Commands wire the preview as an explicit pre-dispatch step (e.g., `commands/hatch3r-workflow.md` Step 0.5).
+Status enum reused from `agents/shared/quality-charter.md` §11. Facet order fixed (machine-parseable). `+<added>/−<removed>` are diff line totals (lines added/removed) across the changed files. `sa <actual>/<expected>` carries the fan-out count; **rationale stays a dispatch-time emission** per `rules/hatch3r-fan-out-discipline.md` (validate-fanout-emission unaffected). Merge condition: line 2 folds into line 1 parenthesized when ≥3 facets at rest (files 0, sa 0, gates 0); at-rest facets fold away except `files`, `sa`, and `tier` — e.g. `**SUCCESS** — Explained adapter precedence (read-only: files 0 · sa 0 · tier 1)`.
+
+## Exception Lines
+
+Below the recap, a line appears ONLY when its firing condition holds. An absent exception line is a positive claim of its Silent-when default — silence asserts the default. Each entry is a single line; `Cost:` is the one multi-line exception (its fenced YAML follows the line).
 
-## The 9 Sections
+| Line | Format | Fires when | Gate preserved | Silent-when |
+|---|---|---|---|---|
+| Not done | `Not done: <item> [— deferred: <why> \| unverified: <what>]; …` | any scope item not done/deferred/unverified | charter honesty; handoff Work Remaining | full scope completed |
+| Blockers | `Blockers: <blocker or open question>; …` | any open blocker | old §8; handoff Blockers | none open |
+| Open findings | `Open findings: <finding_id> <sev> — <disposition>; …` | any findings-ledger row folds non-terminal, or terminal as `escalated`/`surfaced`, at recap time | findings-ledger run-exit invariant (`rules/hatch3r-findings-ledger.md`) | no ledger file for this run, or every row folds to done/deferred/declined/accepted-risk/already-resolved |
+| Default applied | `Default applied: <question summary> → option <N> (<one-line reason>)` — format unchanged from the superseded template, one per default | ASK default exercised | **P8 B1** | no default taken |
+| Gates failed | `Gates failed: <gate>: <one-line cause>; …` | recap gates shows failure | P1 actionability | all gates passed |
+| Cost | `Cost: flagged_for_review: true` + fenced cost_actuals/delta YAML (the one multi-line exception) | any delta > 25% absolute | **Decision 24** / cost-visibility AC5 | deltas within ±25% (recap Δ facet suffices; telemetry persists regardless) |
+| Confidence | `Confidence: <high\|medium\|low> — <basis>[. <D13 action string verbatim>]` | review loop ran OR confidence < high OR status ≠ SUCCESS | D13 mapping; reviewer-calibration; anti-inflation | SUCCESS + high + direct measurement + no loop |
+| User-Accepted Bypass | `User-Accepted Bypass: yes — <verbatim reason ≤200 chars>` + JSONL append | accepted low-confidence PASS | D13 bypass record | no bypass |
+| Learnings | `Learnings: consulted <ids> · surfaced <ids> · captured <ids>` (omit empty facets) | any facet non-empty | learning-system gates | no INDEX / zero matches / nothing captured |
+| Tier | `formatTierUpgradeNote` output verbatim (one-liner, `src/pipeline/pipelineContext.ts:647-655`) | mid-run tier upgrade | D7-14 | no upgrade |
+| Duplication | `Duplication: <n> match(es), closest <path>, overlap <none\|partial\|high>` or `Duplication: scan skipped (<reason>)` | scan matched OR skipped | anti-duplication silent-failure | scan ran clean |
+| Next (optional, never gated) | `Next: <one-line suggested action>` | concrete next step exists | charter optional-sections precedent | nothing to suggest |
 
-1. **Request** — verbatim restatement of the user's ask in one sentence
-2. **Fan-out + Cost** — `sub_agents_spawned: { count, rationale }` + `cost: { estimated_input_tokens, actual_input_tokens, estimated_duration_min, actual_duration_min, delta_percent }`
-3. **Web Research** — every URL fetched with access date + trust tier (per `agents/shared/rigor-contract.md`); count 0 acceptable if 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 Decision 17
-7. **Verification Commands** — exact commands run with exit codes + key output lines (≤200 chars)
-8. **Open Questions / Blockers** — explicit None if fully closed. When an ASK gate's default-if-no-response was exercised this run, this section MUST carry one `Default applied: <question summary> → option <N> (<one-line reason>)` line per default taken (the operational counterpart to `agents/shared/user-question-protocol.md` → Operationalising Default-if-no-Response step 3); absence of the line when a default was applied is a P8 B1 gate failure
-9. **Learnings Captured** — IDs of any learnings written to `.hatch3r/learnings/` this run; cross-reference `rules/hatch3r-learning-system.md`
+Charter-field mapping: Status + Outcome → line 1; Done → outcome + files facet; the rest → exception lines. Learning-system's "citing zero when `applies-to` matched is a gate failure" becomes fired-condition-with-no-line.
 
-## Required Fields per quality-charter §11
+## Handoff Mapping
 
-- **Status:** closed enum SUCCESS | PARTIAL | FAILED | BLOCKED
-- **Outcome:** one sentence
-- **Done / Not Done / Deferred / Unverified:** explicit lists
-- **Confidence + basis:** one of direct measurement | sampled observation | inference from analogue
-- **Consulted Learnings:** IDs of `.hatch3r/learnings/` entries the bound agents (implementer / reviewer / researcher / fixer) read this run per the `rules/hatch3r-learning-system.md` Mandatory Consultation Gate; `none` when INDEX.md is absent or zero `applies-to` rows matched. Distinct from §9 Learnings Captured (entries written this run). Citing zero when `applies-to` matched is a gate failure.
+Handoff surfaces (`rules/hatch3r-handoff-readiness.md`, `skills/hatch3r-handoff-prepare/SKILL.md`, `agents/hatch3r-handoff-preparer.md`) derive their fields from the recap:
+
+- **Work Done** ← recap outcome (line 1) + files facet
+- **Work Remaining** ← `Not done:` line; absent ⇒ `None — full scope completed`
+- **Blockers** ← `Blockers:` line; absent ⇒ `None`
+- **Open Findings** ← `Open findings:` line; absent ⇒ none
 
 ## Confidence-to-Action Mapping (D13)
 
-When a review loop ran this turn, the §5 Confidence line MUST append the action guidance for the loop's terminal confidence level (`reviewLoopConfidence` in `src/pipeline/reviewLoop.ts`). This is the canonical confidence-to-action text — `confidenceExplanation` in `src/pipeline/reviewLoop.ts` returns these exact three strings, so the typed helper and this user-facing rule stay byte-identical (the strings are no longer reachable only from a unit test, closing D13-SA13.2-F2):
+When a review loop ran this turn, the `Confidence:` exception line MUST append the action guidance for the loop's terminal confidence level (`reviewLoopConfidence` in `src/pipeline/reviewLoop.ts`). This is the canonical confidence-to-action text — `confidenceExplanation` in `src/pipeline/reviewLoop.ts` returns these exact three strings, so the typed helper and this user-facing rule stay byte-identical (the strings are no longer reachable only from a unit test, closing D13-SA13.2-F2):
 
 - **high** — The fix was correct on the first attempt. Human review is optional but recommended for critical code paths.
 - **medium** — The fix required one round of corrections, which is normal for moderately complex changes. A brief human review is recommended.
@@ -61,7 +71,7 @@ Omit the mapping when no review loop ran (e.g. a Tier 1 typo edit with no review
 
 ## Pattern Rationale (D13 in-flow teaching — default-ON at Tier ≥ 2)
 
-In-flow teaching is the default, not opt-in: at Tier ≥ 2 (non-trivial / novel orchestrations) the orchestrator MUST emit a `## Pattern Rationale` block before the Iteration Summary, teaching the user each framework pattern applied this turn — closing the knowledge-transfer gap surfaced by D13 SA13.4 (F5/F6: sub-agent reasoning is summarized away before it reaches the user, so the user learns nothing unless the orchestrator teaches at its own surface). One SHORT line per applied pattern with rule citation + pillar served + plain-language reason:
+At Tier ≥ 2 the orchestrator MUST emit a `## Pattern Rationale` block before the Iteration Summary — one SHORT line per framework pattern applied this turn (rule citation + pillar served + plain-language reason), so sub-agent reasoning reaches the user instead of being summarized away (D13 SA13.4 F5/F6):
 
 ```
 pattern_rationale:
@@ -71,38 +81,26 @@ pattern_rationale:
     why: <≤1 sentence plain language>
 ```
 
-Emission policy:
-
-- **Default-ON at Tier ≥ 2:** emit one line for each mutated file that applies a named rule the user did not request explicitly. A Tier ≥ 2 turn that applied at least one such pattern and omits the block is a P5 gate failure (same enforcement class as the §9 Validation Gate).
-- **Tier 1 exemption:** Tier 1 trivial edits (typo, frontmatter-only, single-line clarification) skip the block — no pattern is taught, so no field appears, preserving token budget. This mirrors the Tier-1 exemption in `rules/hatch3r-agent-orchestration.md` (Per-Turn Pipeline-State Header).
-- **No-pattern case:** when a Tier ≥ 2 turn applied no named rule beyond what the user requested, emit `pattern_rationale: none (no implicit pattern applied)` rather than dropping the field, so the block's absence is never ambiguous.
-- **`--quiet` opt-out:** the `--quiet` CLI flag suppresses the block at the user surface (same precedent as cost data in `rules/hatch3r-cost-visibility.md` → "appears in user-facing iteration summaries by default … suppressing via the `--quiet` CLI flag"). Suppression is user-surface only; it does not weaken the Tier ≥ 2 emission contract for default (non-`--quiet`) runs.
+Emission policy: one line per mutated file that applies a named rule the user did not request explicitly; a Tier ≥ 2 turn that applied at least one such pattern and omits the block is a P5 gate failure (same enforcement class as the Validation Gate below). Tier 1 trivial edits (typo, frontmatter-only, single-line clarification) skip the block, mirroring the Tier-1 exemption in `rules/hatch3r-agent-orchestration.md` → Per-Turn Pipeline-State Header. When a Tier ≥ 2 turn applied no named rule beyond the request, emit `pattern_rationale: none (no implicit pattern applied)` so absence is never ambiguous. A triggered plan/act split (`agents/shared/efficiency-patterns.md` P4) is recorded here as an entry carrying `plan_act_split: triggered`; a skipped split stays silent — silence asserts the skip. The `--quiet` CLI flag suppresses the block at the user surface only (same precedent as cost data in `rules/hatch3r-cost-visibility.md`); suppression does not weaken the Tier ≥ 2 emission contract for default runs.
 
 ## User-Accepted Bypass Record (D13)
 
-When the user explicitly accepts a low-confidence PASS at an ASK checkpoint (per the gate-failure rule in the Confidence Propagation Contract used by every core orchestrator), the orchestrator MUST:
-
-1. Emit `User-Accepted Bypass: yes` in §8 (Open Questions / Blockers) with the bypass reason verbatim from the user reply.
-2. Append a single line to `.hatch3r/bypass-log.jsonl` (one JSON object per line — append-only, never rewritten):
+When the user explicitly accepts a low-confidence PASS at an ASK checkpoint (per the Confidence Propagation Contract used by every core orchestrator), the orchestrator MUST (1) emit the `User-Accepted Bypass:` exception line with the bypass reason verbatim from the user reply, and (2) append one JSON object line to `.hatch3r/bypass-log.jsonl` (append-only, never rewritten; atomic append via the `src/merge/safeWrite.ts` pattern — temp+rename then concat):
 
 ```json
-{"ts": "<ISO-8601>", "command": "<hatch3r-* name>", "verdict": "low", "user_reason": "<verbatim ≤200 chars>", "files": ["<paths>"], "session_id": "<id>"}
+{"ts": "<ISO-8601 UTC>", "command": "<hatch3r-* name>", "verdict": "low", "user_reason": "<verbatim ≤200 chars, no PII>", "files": ["<paths>"], "session_id": "<host session id, else unknown>"}
 ```
 
-Schema: `ts` ISO-8601 UTC timestamp; `command` the orchestrator command id; `verdict` always `low` (no bypass on high/medium per the contract); `user_reason` the user's verbatim acceptance string (truncated at 200 chars, no PII); `files` mutated file list; `session_id` the host runtime's session id when available, `unknown` otherwise. Atomic append via `src/merge/safeWrite.ts` pattern (temp+rename then concat). Absence of the line on a recorded bypass is a P5 gate failure.
+Absence of the line on a recorded bypass is a P5 gate failure.
 
 ## Validation Gate
 
-A skill or command that omits the 9-section block fails the lifecycle gate (`.claude/rules/capability-lifecycle.md`). Prose substitution is rejected. The orchestrator catches the omission before declaring SUCCESS.
+A run fails the gate when the recap is missing, when any registry row's firing condition holds with no corresponding exception line, or when prose is substituted for the recap grammar. Registry-row checking is an explicit pre-status step: before declaring status, the orchestrator walks the table above and emits each line whose firing condition holds — the omission is caught before SUCCESS is declared.
 
 ## Emission-Rate Telemetry (current status: per-run gate only; cross-run rate not yet wired)
 
-The validation gate above asserts the 9-section block is present per run. It does NOT measure the emission rate across runs, and no automated cross-run measurement exists today.
-
-The SPACE-shaped activity/performance instrumentation (`src/pipeline/spaceTelemetry.ts`, Decision 24 sibling of cost-visibility) provides the recording primitive `recordSpaceMetric`, the in-process aggregator `getSpaceSummary`, and the across-runs reader `loadSpaceMetricsFromDisk`, but they are not invoked on the iteration-summary path: orchestrator commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, and no command, skill, hook, or `src/` code emits an `iterationSummaryEmitted` metric. The cross-run emission-rate loop is therefore unwired — a future capability, not a live measurement (origin: D10-SA10.8-F-6; gap corrected D10-18). The module records on the `activity` and `performance` axes only; its `satisfaction` and `communication` axes are reserved with no feeder, so "SPACE" names the data shape, not full five-axis coverage (D10-40).
-
-To wire it, a host-runtime bridge (a Claude Code / Cursor / Copilot post-turn hook or an MCP shim) would need to call `recordSpaceMetric({ metricId: "iterationSummaryEmitted", axis: "activity", value: <1 if the 9-section block was produced else 0> })` after each orchestrator/meaningful-skill turn, persisting one JSONL line per run to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; the audit cycle could then read the persisted JSONL across runs via `loadSpaceMetricsFromDisk` + `summarizeSpaceMetricRecords` (NOT `getSpaceSummary`, which sees only the current process's ring buffer) to check the CONSTITUTION §2 P5 "Sub-agent count emission on delegating artifacts: 100%" target against observed runs instead of only mandating it. `recordSpaceMetric` already honours the Silent Failure Contract (telemetry I/O routes through `src/pipeline/failureLog.ts` and never throws), so building the bridge adds no failure surface. Until that bridge ships, P5 emission compliance is enforced by the per-run validation gate above plus audit-cycle spot checks, not by an aggregate metric.
+The Validation Gate asserts recap presence per run; no automated cross-run emission-rate measurement exists today. `src/pipeline/spaceTelemetry.ts` provides `recordSpaceMetric`, `loadSpaceMetricsFromDisk`, and `summarizeSpaceMetricRecords`, but nothing on the iteration-summary path invokes them — commands and skills are LLM-interpreted markdown with no binding to compiled `src/`, so the cross-run loop is a future capability, not a live measurement (origin D10-SA10.8-F-6; gap corrected D10-18). The module records only the `activity` and `performance` axes; `satisfaction` and `communication` are reserved with no feeder, so "SPACE" names the data shape, not five-axis coverage (D10-40). Wiring requires a host-runtime post-turn bridge emitting an `iterationSummaryEmitted` metric to `.hatch3r/telemetry/space-<YYYY-MM-DD>.jsonl`; until then, P5 emission compliance rests on the per-run gate plus audit-cycle spot checks.
 
 ## Pillar Service
-- P5 — standardised reporting prevents drift across orchestrators
-- P7 — cost section surfaces token + duration deltas to user per Decision 24
+- P5 — one standardised recap plus an auditable exception-line registry prevents drift across orchestrators
+- P7 — the recap cost facet surfaces token + duration deltas per Decision 24 at a fraction of the former template's token footprint

package/dist/content/rules/hatch3r-learning-system.md

@@ -97,9 +97,9 @@ Before answering project-specific questions, these agents MUST read `.hatch3r/le
 - `hatch3r-researcher`
 - `hatch3r-fixer`
 
-Bound agents cite consulted entry IDs in the iteration summary's `Open Questions / Blockers` or a dedicated `Consulted Learnings:` line. Citing zero entries when `applies-to` matched is a gate failure visible at audit time.
+Bound agents cite consulted entry IDs in the `consulted` facet of the Iteration Summary's `Learnings:` exception line (`Learnings: consulted <ids> · …` per `rules/hatch3r-iteration-summary.md` → Exception Lines). Citing zero entries when `applies-to` matched is a fired condition with no line — a gate failure visible at audit time.
 
-When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: consultation step is recorded as "no learnings available" in the iteration summary and the agent proceeds.
+When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: the `Learnings:` line stays silent in the Iteration Summary — silence asserts "no learnings available" per the recap contract — and the agent proceeds.
 
 ### Consultation Efficiency
 
@@ -108,7 +108,7 @@ The gate above binds at task start; these heuristics bound its token cost (D6-17
 1. **Scan the INDEX table first.** Read `.hatch3r/learnings/INDEX.md` and match each row's `Topic` + `Applies-To` against the current task; read the full body only for matched rows. Do not read every learning file body.
 2. **Limit surfaced learnings to 5 per consultation.** When more than 5 match, prioritize by `confidence` (high > medium > low) then `created` (recent first).
 3. **Consult once per task.** When an upstream step already consulted for this task (e.g. `hatch3r-board-pickup` Step 6, before delegation), the orchestrator passes the matched learnings to sub-agents as prompt enrichment instead of re-consulting per sub-agent.
-4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — record "no learnings available" and proceed (same recording as the empty-INDEX case above).
+4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — proceed under the same silent default as the empty-INDEX case above.
 
 ### Mid-Task Consult Content Security (ASI06)
 
@@ -122,9 +122,9 @@ The Injection Gate above is the deterministic JS read-path scan; a mid-task cons
 
 The Mandatory Consultation Gate fires once, before work starts (write-then-consult). State-of-art assistants additionally surface knowledge *during* the edit (ambient-teach). To close that gap without runtime support, bound agents surface relevant learnings inline as they touch files:
 
-- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline in the iteration summary BEFORE completing the edit (not only at Step 0).
+- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline — via the `surfaced` facet of the Iteration Summary's `Learnings:` exception line — BEFORE completing the edit (not only at Step 0).
 - **Relevant-learning criteria** (any one qualifies): (1) **path overlap** — the edited path matches the learning's `applies-to` glob; (2) **applies-to match** — an explicit module/path-prefix hit; (3) **semantic overlap** — the edit intent matches the learning `topic` (e.g. editing a retry path while a `topic: retry-backoff` learning exists).
-- **Surfacing format:** add a `Surfaced Learnings:` line to the iteration summary citing the entry IDs and a one-clause why-relevant; cite zero only when none matched.
+- **Surfacing format:** cite the entry IDs in the `surfaced` facet of the Iteration Summary's `Learnings:` exception line with a one-clause why-relevant; when none matched the facet is omitted — silence asserts zero.
 - **Bound agents:** `hatch3r-implementer`, `hatch3r-fixer` (the code-mutating agents whose edits benefit most). This complements — does not replace — the once-per-run Consultation Gate above.
 
 ## Auto-Consolidation
@@ -157,7 +157,7 @@ When a trigger fires:
 
 1. The capturing agent writes a new file `.hatch3r/learnings/<id>.md` with the structured frontmatter and a body paragraph (rule + Why + How to apply).
 2. The agent regenerates `.hatch3r/learnings/INDEX.md` from the directory contents.
-3. The iteration summary records the captured learning ID under `Learnings Captured`.
+3. The Iteration Summary records the captured learning ID in the `captured` facet of the `Learnings:` exception line.
 
 Project-local; learnings never escape the project boundary. The canonical framework repository's `agents/` and `rules/` do not consume project learnings.
 

package/dist/content/rules/hatch3r-learning-system.mdc

@@ -97,9 +97,9 @@ Before answering project-specific questions, these agents MUST read `.hatch3r/le
 - `hatch3r-researcher`
 - `hatch3r-fixer`
 
-Bound agents cite consulted entry IDs in the iteration summary's `Open Questions / Blockers` or a dedicated `Consulted Learnings:` line. Citing zero entries when `applies-to` matched is a gate failure visible at audit time.
+Bound agents cite consulted entry IDs in the `consulted` facet of the Iteration Summary's `Learnings:` exception line (`Learnings: consulted <ids> · …` per `rules/hatch3r-iteration-summary.md` → Exception Lines). Citing zero entries when `applies-to` matched is a fired condition with no line — a gate failure visible at audit time.
 
-When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: consultation step is recorded as "no learnings available" in the iteration summary and the agent proceeds.
+When `.hatch3r/learnings/INDEX.md` does not exist or contains zero entries: the `Learnings:` line stays silent in the Iteration Summary — silence asserts "no learnings available" per the recap contract — and the agent proceeds.
 
 ### Consultation Efficiency
 
@@ -108,7 +108,7 @@ The gate above binds at task start; these heuristics bound its token cost (D6-17
 1. **Scan the INDEX table first.** Read `.hatch3r/learnings/INDEX.md` and match each row's `Topic` + `Applies-To` against the current task; read the full body only for matched rows. Do not read every learning file body.
 2. **Limit surfaced learnings to 5 per consultation.** When more than 5 match, prioritize by `confidence` (high > medium > low) then `created` (recent first).
 3. **Consult once per task.** When an upstream step already consulted for this task (e.g. `hatch3r-board-pickup` Step 6, before delegation), the orchestrator passes the matched learnings to sub-agents as prompt enrichment instead of re-consulting per sub-agent.
-4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — record "no learnings available" and proceed (same recording as the empty-INDEX case above).
+4. **Skip below 3 files.** When `.hatch3r/learnings/` holds fewer than 3 entries, consultation overhead exceeds value — proceed under the same silent default as the empty-INDEX case above.
 
 ### Mid-Task Consult Content Security (ASI06)
 
@@ -122,9 +122,9 @@ The Injection Gate above is the deterministic JS read-path scan; a mid-task cons
 
 The Mandatory Consultation Gate fires once, before work starts (write-then-consult). State-of-art assistants additionally surface knowledge *during* the edit (ambient-teach). To close that gap without runtime support, bound agents surface relevant learnings inline as they touch files:
 
-- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline in the iteration summary BEFORE completing the edit (not only at Step 0).
+- **Trigger:** while editing, when the file or pattern being changed matches a captured learning, surface that learning inline — via the `surfaced` facet of the Iteration Summary's `Learnings:` exception line — BEFORE completing the edit (not only at Step 0).
 - **Relevant-learning criteria** (any one qualifies): (1) **path overlap** — the edited path matches the learning's `applies-to` glob; (2) **applies-to match** — an explicit module/path-prefix hit; (3) **semantic overlap** — the edit intent matches the learning `topic` (e.g. editing a retry path while a `topic: retry-backoff` learning exists).
-- **Surfacing format:** add a `Surfaced Learnings:` line to the iteration summary citing the entry IDs and a one-clause why-relevant; cite zero only when none matched.
+- **Surfacing format:** cite the entry IDs in the `surfaced` facet of the Iteration Summary's `Learnings:` exception line with a one-clause why-relevant; when none matched the facet is omitted — silence asserts zero.
 - **Bound agents:** `hatch3r-implementer`, `hatch3r-fixer` (the code-mutating agents whose edits benefit most). This complements — does not replace — the once-per-run Consultation Gate above.
 
 ## Auto-Consolidation
@@ -157,7 +157,7 @@ When a trigger fires:
 
 1. The capturing agent writes a new file `.hatch3r/learnings/<id>.md` with the structured frontmatter and a body paragraph (rule + Why + How to apply).
 2. The agent regenerates `.hatch3r/learnings/INDEX.md` from the directory contents.
-3. The iteration summary records the captured learning ID under `Learnings Captured`.
+3. The Iteration Summary records the captured learning ID in the `captured` facet of the `Learnings:` exception line.
 
 Project-local; learnings never escape the project boundary. The canonical framework repository's `agents/` and `rules/` do not consume project learnings.
 

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

@@ -75,4 +75,4 @@ Apply layered verification from cheapest to most thorough; stop at the cheapest
 
 Pick one schema-management tool per project and commit the schema declaration to the repo. Greenfield default: Atlas (50+ destructive/locking linters, auto-generated down migrations, GitHub Actions approval policies) or dbmate (plain-SQL portability with first-class `-- migrate:down`). Existing-project default: whatever already ships migrations in the repo. Acceptable tools: Atlas, Prisma Migrate (forward-only — surface to reviewer), Drizzle Kit (forward-only — surface), Flyway 11+, Liquibase 4.27+ Pro, sqitch, Alembic, Knex, dbmate, Bytebase. Run a migration linter in CI — Atlas analyze, `squawk` for raw Postgres SQL — fail the PR on destructive operations without an explicit `IRREVERSIBLE:` annotation.
 
-Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics).
+Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics), `hatch3r-contract-census` (in-code analog: façade contract-hold for field drop/rename outside the database).

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

@@ -70,4 +70,4 @@ Apply layered verification from cheapest to most thorough; stop at the cheapest
 
 Pick one schema-management tool per project and commit the schema declaration to the repo. Greenfield default: Atlas (50+ destructive/locking linters, auto-generated down migrations, GitHub Actions approval policies) or dbmate (plain-SQL portability with first-class `-- migrate:down`). Existing-project default: whatever already ships migrations in the repo. Acceptable tools: Atlas, Prisma Migrate (forward-only — surface to reviewer), Drizzle Kit (forward-only — surface), Flyway 11+, Liquibase 4.27+ Pro, sqitch, Alembic, Knex, dbmate, Bytebase. Run a migration linter in CI — Atlas analyze, `squawk` for raw Postgres SQL — fail the PR on destructive operations without an explicit `IRREVERSIBLE:` annotation.
 
-Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics).
+Cross-references: see `hatch3r-data-classification` (PII / encrypted-column migration requirements), `hatch3r-feature-flags` (read-path switchover gating), `hatch3r-observability-metrics` (backfill progress metrics), `hatch3r-contract-census` (in-code analog: façade contract-hold for field drop/rename outside the database).

package/dist/content/rules/hatch3r-reviewer-calibration.md

@@ -64,7 +64,7 @@ Append exactly one record per second pass to `.hatch3r/calibration-log.jsonl` (p
 {"timestamp":"<ISO-8601>","first_pass_verdict":"PASS","second_pass_verdict":"PASS|REQUEST CHANGES","divergent":false,"second_pass_model_class":"different|re-roll","consecutive_clean_count":5,"trigger":"cadence|high-risk"}
 ```
 
-`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`.
+`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the `Confidence:` exception line of the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`.
 
 ## Unavailability (visible skip, never silent)
 
@@ -79,6 +79,6 @@ Skip the second pass ONLY when no second model class is available AND the orches
 
 - `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration — the consuming agent body that invokes this contract (accessed 2026-05-28, trust tier: canonical).
 - The across-cycle calibration protocol §Runtime complement (F13.2-F1) — the across-cycle measurement loop this runtime bound complements (accessed 2026-05-28, trust tier: canonical).
-- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence` field (accessed 2026-05-28, trust tier: canonical).
+- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence:` exception line (accessed 2026-05-28, trust tier: canonical).
 - Tian, Z. et al. "Overconfidence in LLM-as-a-Judge: Diagnosis and Confidence-Driven Solution" (arxiv:2508.06225). `https://arxiv.org/abs/2508.06225` (accessed 2026-06-09, peer-reviewed-methodology). Evidence that an LLM judge's predicted confidence significantly overstates realized correctness (the Overconfidence Phenomenon), so a self-reported clean PASS is structurally over-trusted — motivating the out-of-band second pass.
 - Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024 (arxiv:2310.01798). `https://arxiv.org/abs/2310.01798` (accessed 2026-06-06, peer-reviewed-methodology). Evidence that same-model self-critique shares the generator's blind spot, motivating the different-model-class setup recommendation in Action and the lowered safety-class `N=1` second-pass cadence (D23-2).

package/dist/content/rules/hatch3r-reviewer-calibration.mdc

@@ -64,7 +64,7 @@ Append exactly one record per second pass to `.hatch3r/calibration-log.jsonl` (p
 {"timestamp":"<ISO-8601>","first_pass_verdict":"PASS","second_pass_verdict":"PASS|REQUEST CHANGES","divergent":false,"second_pass_model_class":"different|re-roll","consecutive_clean_count":5,"trigger":"cadence|high-risk"}
 ```
 
-`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the iteration-summary `Confidence` field per `rules/hatch3r-iteration-summary.md`.
+`consecutive_clean_count` is the post-increment cross-run count at firing time; `trigger` records which Trigger branch fired (`high-risk` when the diff touched a safety-class surface and the second pass fired on the first clean PASS under the `N=1` fast path). `second_pass_model_class` is `different` for a cross-family second pass or `re-roll` for the same-family fallback; a `re-roll` record corresponds to a `calibration: degraded (same-family re-roll)` verdict annotation per Action. The project-local over-claim rate derived from this log feeds the `Confidence:` exception line of the recap-contract Iteration Summary per `rules/hatch3r-iteration-summary.md`.
 
 ## Unavailability (visible skip, never silent)
 
@@ -79,6 +79,6 @@ Skip the second pass ONLY when no second model class is available AND the orches
 
 - `agents/hatch3r-reviewer.md` §Runtime Confidence Calibration — the consuming agent body that invokes this contract (accessed 2026-05-28, trust tier: canonical).
 - The across-cycle calibration protocol §Runtime complement (F13.2-F1) — the across-cycle measurement loop this runtime bound complements (accessed 2026-05-28, trust tier: canonical).
-- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence` field (accessed 2026-05-28, trust tier: canonical).
+- `rules/hatch3r-iteration-summary.md` — consumes the project-local over-claim rate for the `Confidence:` exception line (accessed 2026-05-28, trust tier: canonical).
 - Tian, Z. et al. "Overconfidence in LLM-as-a-Judge: Diagnosis and Confidence-Driven Solution" (arxiv:2508.06225). `https://arxiv.org/abs/2508.06225` (accessed 2026-06-09, peer-reviewed-methodology). Evidence that an LLM judge's predicted confidence significantly overstates realized correctness (the Overconfidence Phenomenon), so a self-reported clean PASS is structurally over-trusted — motivating the out-of-band second pass.
 - Huang, J. et al. "Large Language Models Cannot Self-Correct Reasoning Yet." ICLR 2024 (arxiv:2310.01798). `https://arxiv.org/abs/2310.01798` (accessed 2026-06-06, peer-reviewed-methodology). Evidence that same-model self-critique shares the generator's blind spot, motivating the different-model-class setup recommendation in Action and the lowered safety-class `N=1` second-pass cadence (D23-2).

package/dist/content/rules/hatch3r-security-patterns.md

@@ -40,6 +40,10 @@ Authentication and authorization patterns (auth middleware, token validation, se
 - Circuit breakers for downstream service failures. Degrade gracefully rather than retrying indefinitely or passing errors upstream.
 - Health checks and readiness probes must not expose sensitive configuration or internal topology.
 - Disable debug endpoints, verbose logging, and source maps in production builds. Gate behind feature flags if needed in staging.
+- **Dangerous-capability environment gates are allowlists, never denylists.** A capability that must not run in production — debug endpoint, seed/reset script, test-auth bypass, destructive CLI verb, mock-payment mode — is gated by an explicit allowlist of named safe environments (`const ALLOWED = ['development','test']; if (!ALLOWED.includes(env)) refuse`).
+  - The denylist form `if (process.env.NODE_ENV !== 'production')` is the named anti-pattern: an unset, misspelled, or novel environment value (`stage`, `prod-eu`, `undefined` in a fresh container) evaluates as "not production" and ENABLES the capability.
+  - Unknown environment fails closed: an absent or unrecognized value takes the deny branch.
+  - Assert at startup that the resolved environment is a member of the project's known-environment enum; refuse to boot otherwise.
 
 ## CSRF Protection
 

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

@@ -35,6 +35,10 @@ Authentication and authorization patterns (auth middleware, token validation, se
 - Circuit breakers for downstream service failures. Degrade gracefully rather than retrying indefinitely or passing errors upstream.
 - Health checks and readiness probes must not expose sensitive configuration or internal topology.
 - Disable debug endpoints, verbose logging, and source maps in production builds. Gate behind feature flags if needed in staging.
+- **Dangerous-capability environment gates are allowlists, never denylists.** A capability that must not run in production — debug endpoint, seed/reset script, test-auth bypass, destructive CLI verb, mock-payment mode — is gated by an explicit allowlist of named safe environments (`const ALLOWED = ['development','test']; if (!ALLOWED.includes(env)) refuse`).
+  - The denylist form `if (process.env.NODE_ENV !== 'production')` is the named anti-pattern: an unset, misspelled, or novel environment value (`stage`, `prod-eu`, `undefined` in a fresh container) evaluates as "not production" and ENABLES the capability.
+  - Unknown environment fails closed: an absent or unrecognized value takes the deny branch.
+  - Assert at startup that the resolved environment is a member of the project's known-environment enum; refuse to boot otherwise.
 
 ## CSRF Protection
 

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

@@ -143,6 +143,20 @@ Every test must be deterministic. Mandates:
 - **Database state:** Integration tests set up and tear down within the test via helpers. Never depend on database state from a previous test. Enforce tenancy isolation via per-test schema or transaction rollback.
 - **Testcontainers** pinned by image digest, not tag.
 
+## Degenerate-Input Guard
+
+A test whose input turns the computation under test into a no-op verifies wiring, not behavior. Canonical degenerate vectors:
+
+- A 0%-interest loan (interest math never executes).
+- A one-record merge (no conflict branch).
+- An empty-array pipeline (every stage vacuously passes).
+- A zero-quantity or zero-price order (totals stay 0).
+- A same-source-and-target move (no-op transfer).
+- `now()` timestamps against expiry logic (never expires).
+- Single-user fixtures against cross-tenant checks.
+
+**Requirement:** for each changed behavior, at least one input **activates** the computation, and the assertion distinguishes the activated result from the degenerate baseline (the two expected outputs differ). **Reviewer treatment:** a suite green only on degenerate vectors is a Warning; on payment, auth, or data-mutation paths, Critical. "N passing" is evidence only when paired with which changed behaviors those N tests activate.
+
 ## Error Path Coverage
 
 Error handling code is often under-tested because developers focus on happy paths. Enforce minimum error coverage:

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

@@ -138,6 +138,20 @@ Every test must be deterministic. Mandates:
 - **Database state:** Integration tests set up and tear down within the test via helpers. Never depend on database state from a previous test. Enforce tenancy isolation via per-test schema or transaction rollback.
 - **Testcontainers** pinned by image digest, not tag.
 
+## Degenerate-Input Guard
+
+A test whose input turns the computation under test into a no-op verifies wiring, not behavior. Canonical degenerate vectors:
+
+- A 0%-interest loan (interest math never executes).
+- A one-record merge (no conflict branch).
+- An empty-array pipeline (every stage vacuously passes).
+- A zero-quantity or zero-price order (totals stay 0).
+- A same-source-and-target move (no-op transfer).
+- `now()` timestamps against expiry logic (never expires).
+- Single-user fixtures against cross-tenant checks.
+
+**Requirement:** for each changed behavior, at least one input **activates** the computation, and the assertion distinguishes the activated result from the degenerate baseline (the two expected outputs differ). **Reviewer treatment:** a suite green only on degenerate vectors is a Warning; on payment, auth, or data-mutation paths, Critical. "N passing" is evidence only when paired with which changed behaviors those N tests activate.
+
 ## Error Path Coverage
 
 Error handling code is often under-tested because developers focus on happy paths. Enforce minimum error coverage:

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

@@ -61,7 +61,7 @@ Adding a new tool to `src/cliTools/registry.ts::AVAILABLE_CLI_TOOLS` MUST satisf
 7. **Capability matrix** — `src/adapters/canonical.ts` renders the skill to all 3 adapter outputs (cursor, claude, copilot); the per-adapter render path is tested in `src/__tests__/adapters/{name}.test.ts`.
 8. **Alternative-tool comparison** — the PR body lists at least 2 named alternatives considered (with rejection rationale citing measurable trade-offs); avoids tool-duplication per `rules/hatch3r-anti-duplication.md`.
 9. **Probe binary registration** — the `probe` field on the registry entry names the binary used by `detectInstalled()`; the probe MUST be the exact executable name printed by the install command output (e.g. `rg` for ripgrep, `fd` for fd, `jq` for jq).
-10. **Iteration-summary entry** — the addition emits one row in `rules/hatch3r-iteration-summary.md` §Changes Made with the registry-entry diff link, per the iteration-summary template.
+10. **Iteration-summary entry** — the addition emits one line in the recap-contract Iteration Summary citing the registry-entry diff link, per `rules/hatch3r-iteration-summary.md`.
 
 ## Removing or Demoting a Tool