hatch3r 2.1.0 → 2.2.0

package/dist/content/commands/hatch3r-design-system-create.md

@@ -0,0 +1,254 @@
+---
+id: hatch3r-design-system-create
+type: command
+orchestrator: true
+agentPipeline: [hatch3r-researcher, hatch3r-implementer, hatch3r-ui, hatch3r-ux]
+description: "Create a project design system from brand assets or an elicitation dialog — DTCG 2025.10 token emission, 3-tier taxonomy (primitive → semantic → component), OKLCH ramps, dual output design.md + design-tokens.json, gated on WCAG 2.2 AA contrast, 100% theme parity, and 0 dangling aliases."
+argument-hint: "[brand-asset-path]"
+tags: [implementation, ui, design-system, floor:ui-ux]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+efficiency_tier: standard
+triage_tiers: [1, 2, 3]
+sub_agents_spawned:
+  count: 4
+  rationale: One hatch3r-researcher extracts palette + convention seeds from brand assets (Tier 2/3 only); one hatch3r-implementer writes design-tokens.json + docs/design.md + emission targets (all file mutation flows through the implementer per the Mandatory Delegation Directive); hatch3r-ui and hatch3r-ux run in parallel as the two mandatory validation gates — read-only over the same generated files with disjoint checklist rows. Research → implement → gate are the only serialization edges; every alias resolves into one token graph, so generation stays single-implementer by shared-state dependency, never by token cost. Cost-dominance per CONSTITUTION §2 P8.
+---
+
+## §0 Detect Ambiguity (P8 B1)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → §0 Detect Ambiguity. Per-command triggers: (a) neither a brand-asset path nor an explicit request for the elicitation dialog is present; (b) the Step 1 detect verdict is `reuse` — an existing system is in scope and overwriting it is irreversible; (c) theme set undeclared (light + dark pair vs + high-contrast third set per `rules/hatch3r-theming.md`); (d) emission target undeclared (DTCG JSON only vs + Tailwind v4 `@theme` vs + CSS custom properties); (e) brand hue count ambiguous (one primary vs primary + secondary + accent — each hue gets its own ramp). Proceed without asking ONLY when the asset-vs-dialog path, theme set, and emission target are all explicit. B1 directive: `rules/hatch3r-clarification-default.md`.
+
+## Agent Pipeline
+
+| Stage | Agent(s) | Parallel | Required |
+|-------|----------|----------|----------|
+| 1. Detect existing design system | Orchestrator (inline; runs `hatch3r-design-system-detect` skill, read-only) | No | Yes |
+| 2. Intake / elicitation + ASK gate | Orchestrator (inline) | No | Yes |
+| 3. Brand/asset research | `hatch3r-researcher` | Per asset class | Tier 2/3 only |
+| 4. Generate tokens + docs | `hatch3r-implementer` | No — single token graph | Yes |
+| 5. Validate CQ1 + CQ2 gates | `hatch3r-ui` + `hatch3r-ux` | Yes | Yes |
+| 6. Docs check + Iteration Summary | Orchestrator (inline) | No | Yes |
+
+**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): Stage 5 runs `hatch3r-ui` and `hatch3r-ux` concurrently — both are read-only over the same generated files, their gate rows are disjoint (contrast/alias/parity vs focus-indicator/target-size), and aggregation is deterministic (union of findings). Stage 3 fans out one researcher per asset class (palette + logo vs screenshot corpus vs Figma/tokens-studio export) when Tier 3 supplies more than one. Stage 4 stays single-implementer: every alias resolves into one token graph — shared mutable state, so the no-parallel-writers condition binds; a dependency edge, not a token-cost serialization.
+
+---
+
+# Design System Create -- Brand Assets or Elicitation Dialog → DTCG Tokens + design.md
+
+Creates a project- or workspace-wide design system from brand assets (logo, brand-color list, screenshots, Figma export, tokens-studio JSON) or, when no assets exist, from a structured elicitation dialog. Dual output: `design-tokens.json` (DTCG Format Module 2025.10 — `$type`/`$value`, `{group.token}` aliases) and `docs/design.md` (principles, palette + OKLCH ramps, taxonomy diagram, theme table, usage examples, embedded Accessibility Report). A run passes only when every blocking row of the Step 5 gate table holds: WCAG 2.2 AA contrast on 100% of semantic fg/bg pairs in every theme, 100% theme parity, 0 dangling aliases, 0 component→primitive direct references.
+
+Use `/hatch3r-design-system-create` when the detect verdict is `create` or `extend`. Use the `hatch3r-design-system-detect` skill alone to inventory an existing system without generating; use the `hatch3r-ui-ux-verify` skill to audit built UI against a system that already exists.
+
+---
+
+## Argument Parsing
+
+Optional positional argument: `<brand-asset-path>` — a file or directory of brand assets.
+
+- If supplied: Step 2 reads assets from that path; the elicitation dialog covers only the intake fields the assets leave unanswered.
+- If omitted: Step 2 runs the full elicitation dialog (primary hue, neutral temperature, density, radius scale, motion preference, theme set).
+
+---
+
+## Step 0: Triage
+
+Classify before delegating, using the Light / Standard / Deep vocabulary in `agents/shared/triage-vocabulary.md` (`triage_tiers: [1, 2, 3]` maps 1 = Light, 2 = Standard, 3 = Deep).
+
+- **Tier 1 (Light)** — complete assets (brand hues + neutral readable without research), a single light + dark pair, detect verdict `create`. No researcher: one `hatch3r-implementer` + the two parallel gates.
+- **Tier 2 (Standard)** — the elicitation dialog is needed (no assets, or assets answer only part of the Step 2 intake table) OR the detect verdict is `extend`. One `hatch3r-researcher` pass over whatever assets exist + implementer + gates.
+- **Tier 3 (Deep)** — Figma/tokens-studio import, multi-brand palette, monorepo (workspace-wide token package), or a third theme (high-contrast). One researcher per asset class in parallel + implementer + gates.
+
+An undeclared theme set or emission target fires the §0 gate before tiering. Classify upward on uncertainty (highest-tier rule, `agents/shared/triage-vocabulary.md`).
+
+### Step 0.5: Emit Pre-Execution Cost Preview
+
+Before the Step 2 ASK gate, emit the cost preview per `rules/hatch3r-cost-visibility.md`:
+
+```yaml
+cost_estimate:
+  expected_sa_count: <0-2 researchers by tier + 1 implementer + 2 validation gates>
+  estimated_input_tokens_static_frame: <int>
+  estimated_web_research_queries: <int>   # 0-2 — only for Figma/tokens-studio field-mapping checks
+  triage_tier: light | standard | deep
+  estimated_duration_min: <int>
+```
+
+Post-execution actuals + delta land in the Step 6 Iteration Summary recap per `rules/hatch3r-cost-visibility.md`.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Effort Override. Per-command slot: a complete-assets single-pair run misread as Deep because a stray tokens-studio JSON sits in the repo — force `--effort=light`.
+
+---
+
+## Step 1: Detect First (mandatory, read-only)
+
+Invoke the `hatch3r-design-system-detect` skill inline and consume its Design System Inventory (`.audit-workspace/design-system-inventory.md`). This command never re-implements detection — it reads the inventory's token source, color space, component library, and responsive strategy verbatim and treats them as ground truth for Steps 3–4.
+
+Verdict routing (the inventory's `Verdict:` line):
+
+| Verdict | Route |
+|---------|-------|
+| `reuse` | HALT with an actionable pointer: print the existing token source + component library and exit — this command never overwrites a working design system. To audit it instead, run the `hatch3r-ui-ux-verify` skill. |
+| `extend` | Scope generation to the inventory's gaps only (e.g. missing dark theme, missing component tier, hex → OKLCH migration). Existing token names are read-only inputs; the inventory's canonical token-source location overrides the greenfield default. |
+| `create` | Full pipeline, Steps 2–6. |
+
+If the inventory flags multiple token sources, the run is BLOCKED until the maintainer names the canonical one (the detect skill's reconciliation rule) — writing a new source beside them would break the DTCG single-source-of-truth mandate.
+
+---
+
+## Step 2: Intake / Elicitation + ASK Checkpoint (only mutation gate)
+
+Fill the intake table from `<brand-asset-path>` where the assets answer a field; run the structured dialog for the rest. Cache for the Step 4 implementer prompt.
+
+| Input | Default if unspecified | Notes |
+|-------|------------------------|-------|
+| Brand assets | none → full dialog | logo, brand-color list, screenshots, Figma export, tokens-studio JSON |
+| Brand hue(s) | (required — assets or dialog) | 1–3 hues; each hue gets its own OKLCH ramp |
+| Neutral temperature | pure gray | warm / cool / pure — hue bias of the neutral ramp |
+| Density | comfortable | compact / comfortable / spacious — base of the spacing scale |
+| Radius scale | 4px base | none / 4px / 8px / full-round tiers |
+| Motion | 200ms ease + reduced-motion variant | per `rules/hatch3r-theming.md` |
+| Theme set | light + dark | + high-contrast (≥7:1 text, ≥3:1 non-text) per `rules/hatch3r-theming.md` |
+| Emission target | DTCG JSON | + Tailwind v4 `@theme` / + CSS custom properties, per the detect inventory |
+| Token-source location | `tokens/design-tokens.json` (greenfield) | the inventory's canonical location wins on `extend` |
+
+Present ONE consolidated ASK confirming the intake summary — the only mutation gate:
+
+```
+hatch3r-design-system-create — Tier {1|2|3}, verdict: {create|extend}
+
+Intake summary:
+  brand hues: {n} ({oklch values or dialog answers})
+  neutral: {warm|cool|pure} · density: {…} · radius: {…} · motion: {…}
+  themes: light + dark {+ high-contrast}
+  emission: DTCG JSON {+ @theme} {+ CSS vars}
+  taxonomy: primitive → semantic → component
+  output: {token-source location} + docs/design.md
+```
+
+ASK per `agents/shared/user-question-protocol.md`: `accept` — generate and gate; `edit` — change an intake field first; `skip` — cancel, write nothing. After `accept`, the run is autonomous through Step 6.
+
+---
+
+## Step 3: Token Architecture (+ Tier 2/3 asset research)
+
+**Tier 2/3 research (sub-agent delegation).** Delegate asset analysis to `hatch3r-researcher` via the Task tool — one researcher per asset class, in parallel (read-only per that agent's contract). Brief: extract candidate brand hues as OKLCH, spacing/radius conventions visible in screenshots, and a tokens-studio → DTCG field mapping when an export is present. Findings feed the Step 4 implementer prompt. Tier 1 skips this stage — the assets already answer the intake table.
+
+**Taxonomy (all tiers).** Three tiers, aligned with `rules/hatch3r-theming.md` token layering and `rules/hatch3r-component-conventions.md`:
+
+1. **Primitive** — raw scales, no theme awareness: OKLCH ramps (`gray.100`…`gray.900`, `brand.100`…), spacing, radius, type scale.
+2. **Semantic** — role tokens (`color.surface`, `color.text-primary`, `color.border`, `color.brand`, `color.error/success/warning`) aliasing primitives; the theme-switching layer.
+3. **Component** — `btn.text`, `input.border`, … aliasing semantic tokens only.
+
+**Hard rule:** a component token never references a primitive token directly — every component alias resolves through the semantic tier (blocking row, Step 5). This constraint is what makes theme switching a semantic-tier-only override.
+
+---
+
+## Step 4: Generate (sub-agent delegation)
+
+Delegate to `hatch3r-implementer` via the Task tool. ALL file writes flow through the implementer per the Mandatory Delegation Directive — the orchestrator writes nothing inline.
+
+The implementer prompt MUST include the detect inventory, the confirmed intake, the Step 3 research findings, and this contract:
+
+**OKLCH ramps (per brand hue + neutral):** a lightness ramp per hue (10 steps, L ≈ 0.98 → 0.15); for text-role steps hold L fixed and adjust C/H toward the Step 5 contrast thresholds (the apcach pattern — in OKLCH, contrast tracks ΔL, so L placement is the contrast control). Reduce chroma 10–20% on dark-theme surface ramps per `rules/hatch3r-theming.md`.
+
+**DTCG emission (the token-source file):** Format Module 2025.10 — every token carries `$type` + `$value`; aliases use `{group.token}` syntax; groups mirror the 3-tier taxonomy; default location `tokens/design-tokens.json` on greenfield, the inventory's canonical location on `extend`.
+
+**Themes:** light + dark (+ high-contrast when confirmed) as semantic-tier override sets with IDENTICAL semantic key sets — a key present in one theme and absent in another is a blocking Step 5 failure.
+
+**Adapter emission (per detect inventory):** Tailwind v4 `@theme` block and/or `:root` CSS custom properties are generated FROM the DTCG file (Style Dictionary-compatible naming) — derived outputs, never a second authored source.
+
+**Docs:** `docs/design.md` per the Step 6 contract.
+
+Also include: all `scope: always` rule directives; the confidence expression requirement (verbatim, high/medium/low per `agents/shared/quality-charter.md` §1); the boundary "do NOT create branches, commits, or PRs". Await the structured result; capture `Files changed` and the `Delegation proof ID` per file.
+
+---
+
+## Step 5: Validate (parallel sub-agent gates)
+
+After the implementer returns, delegate `hatch3r-ui` and `hatch3r-ux` via the Task tool in parallel. `hatch3r-ui` owns the contrast, alias, parity, reference, and APCA rows (CQ1 acceptance bar: `agents/hatch3r-ui.md` audit checklist); `hatch3r-ux` owns the focus-indicator and touch-target rows (interaction affordances, CQ2). Each prompt carries the generated file paths + its gate rows:
+
+| Gate | Threshold | Blocking |
+|---|---|---|
+| WCAG 2.2 AA contrast (4.5:1 text / 3:1 large + non-text) | 100% of semantic fg/bg pairs, every theme | Yes |
+| Focus-indicator contrast ≥3:1 | 100% of interactive component tokens | Yes |
+| Touch-target sizing tokens ≥44px | 100% | Yes |
+| Dangling aliases | 0 | Yes |
+| Theme parity (identical semantic key set per theme) | 100% | Yes |
+| Component→primitive direct references | 0 | Yes |
+| APCA (Lc ≥60 body / ≥45 large) | advisory | No — recorded in a11y report |
+
+The 44px sizing-token row sits above the WCAG 2.2 AA SC 2.5.8 floor (24×24 CSS px) — size tokens are authored to the platform-HIG bar so consuming components inherit it. A blocking-row failure routes back through `hatch3r-implementer` (max 1 regeneration pass), then re-gates the failed rows only. A persistent blocking failure ends the run at `PARTIAL` with the system flagged not-merge-ready. APCA readings below Lc 60/45 land in the design.md Accessibility Report — advisory, never a halt.
+
+---
+
+## Step 6: Docs + Iteration Summary
+
+Verify `docs/design.md` (written by the Step 4 implementer) carries: principles (the confirmed intake decisions restated as statements), palette + per-hue OKLCH ramp tables, the 3-tier taxonomy diagram, a theme table (semantic keys × themes), usage examples per emission target, and an embedded Accessibility Report (WCAG pass matrix per theme + the APCA advisory readings). Emit the runtime `sub_agents_spawned: {count, rationale}` block with the actual spawn count per `rules/hatch3r-fan-out-discipline.md`.
+
+### End-of-Turn Delegation Attestation (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → End-of-Turn Delegation Attestation. Per-command mutated-file slot: `{token-source location}`, `docs/design.md`, emission-target files — all `via hatch3r-implementer`.
+
+### Iteration Summary (mandatory output)
+
+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.
+
+```markdown
+## Iteration Summary
+
+**SUCCESS** — Created 2-theme OKLCH design system (1 brand hue + neutral, 3-tier DTCG tokens); ui + ux gates PASS 6/6 blocking rows.
+files 3 (+486/−0) · sa 4/4 · gates 6/6 · cost Δ−8% tok / Δ+3% min · tier 2
+Not done: APCA Lc 58 on `color.text-secondary` (dark) — advisory, recorded in the design.md Accessibility Report
+Next: import the token file into the build (Tailwind `@theme` / Style Dictionary) and point component authors at docs/design.md.
+```
+
+Status decision rules:
+- **SUCCESS** — tokens + docs written, all blocking gate rows PASS, verdict-scoped outputs complete.
+- **PARTIAL** — generated, but a blocking row failed after the single regeneration pass, or a verification command failed.
+- **FAILED** — the implementer returned BLOCKED; nothing written.
+- **BLOCKED** — detect verdict `reuse`, multiple token sources unreconciled, or an intake contradiction the maintainer must rule on.
+
+---
+
+## Per-Turn Pipeline-State Header (Bypass Protection)
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Per-Turn Pipeline-State Header. Phase mapping: `1` = detect + intake + confirm, `2` = research + implementer generation, `3` = parallel gates + docs + summary. Tier 1 complete-asset runs are exempt per the Tier 1 exemption.
+
+---
+
+## Error Handling
+
+- **Asset unreadable or unsupported format** — name the supported classes (logo image, brand-color list, screenshots, Figma export, tokens-studio JSON) and fall back to the elicitation dialog for the missing fields; never infer a brand hue from a filename.
+- **Multiple token sources in the detect inventory** — BLOCKED until the maintainer names the canonical source (Step 1).
+- **Researcher returns low-confidence hue extraction** — re-open the ASK with the OKLCH candidates as numbered options (residual-ambiguity re-ask per the frame §0); never silently pick one.
+- **Persistent blocking-gate failure after the regeneration pass** — end at PARTIAL, not-merge-ready flag, gate findings quoted verbatim in the Iteration Summary.
+
+## Guardrails
+
+1. **One ASK gate.** Step 2 is the only user-facing checkpoint; after `accept`, the run proceeds through Step 6 (residual-ambiguity re-asks per frame §0 excepted).
+2. **No commit or push.** Generated files are left staged for human review; git operations are out of scope.
+3. **Detect before create.** Step 1 is never skipped; a `reuse` verdict halts the run — this command never overwrites an existing design system.
+4. **Single authored source.** The DTCG file is the only hand-authored token source; `@theme` / CSS-vars outputs are derived from it and regenerated, never edited in place.
+5. **No raw color values outside the primitive tier.** Semantic and component tokens are aliases only (`rules/hatch3r-theming.md` token layering).
+6. **Both gates are mandatory.** A run is never declared SUCCESS without `hatch3r-ui` AND `hatch3r-ux` PASS on every blocking row they own.
+
+## Resumability (Decision 27/30)
+
+design-system-create serializes on the research → generate → gate edges, so checkpoint at the stage boundary — an interrupted run re-enters at the first incomplete stage rather than regenerating the token file it already wrote.
+
+> Orchestration boilerplate: see `commands/shared/orchestration-frame.md` → Checkpoint Contract. Per-command slots: workspace `.design-system-workspace/`; step range the Step 1 → Step 6 progression; `wave` = the researcher-batch index in Step 3, then the regeneration-pass index in Step 5; snapshot/rollback paths the token-source file, `docs/design.md`, and every emission-target file the Step 4 implementer touches. Write points: after the Step 1 inventory read, after the Step 2 accept gate, after each Step 3 researcher return, after the Step 4 implementer return, and after each Step 5 gate verdict.
+
+## References
+
+- [W3C Design Tokens Format Module 2025.10](https://www.designtokens.org/tr/drafts/format/) (accessed 2026-07-08, W3C Design Tokens Community Group, official-docs) — `$type`/`$value` token shape, `{group.token}` alias syntax, group nesting, and the single-source mandate; source for the Step 4 emission contract.
+- [Design Tokens specification reaches first stable version](https://www.w3.org/community/design-tokens/2025/10/28/design-tokens-specification-reaches-first-stable-version/) (accessed 2026-07-08, W3C Design Tokens CG, official-docs) — confirms 2025.10 as the first stable release; the version the emission contract pins.
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) (accessed 2026-07-08, W3C, official-docs) — SC 1.4.3 contrast minimums (4.5:1 / 3:1 large), SC 1.4.11 non-text contrast 3:1, SC 2.5.8 target size 24×24; the Step 5 blocking thresholds and the floor the 44px token row exceeds.
+- [apcach](https://github.com/antiflasher/apcach) (accessed 2026-07-08, named-maintainer library, established-library) — composing OKLCH colors to a target contrast by holding L and adjusting C/H; pattern source for the Step 4 ramp recipe and the APCA advisory row (Lc 60 body / 45 large).
+- [Style Dictionary — DTCG support](https://styledictionary.com/info/dtcg/) (accessed 2026-07-08, Style Dictionary maintainers, established-library) — DTCG-input transform surface and derived multi-platform outputs; basis for the derived-emission (never second-source) guardrail.
+- [uxKero/anydesign](https://github.com/uxKero/anydesign) (accessed 2026-07-08, named maintainer, independent-analysis) — prior art: elicitation-dialog → design-system generation; structural source for the Step 2 dialog field set.
+- [arvindrk/extract-design-system](https://github.com/arvindrk/extract-design-system) (accessed 2026-07-08, named maintainer, independent-analysis) — prior art: palette/spacing extraction from existing assets and screenshots; structural source for the Step 3 researcher brief.
+
+Cross-references: `skills/hatch3r-design-system-detect/SKILL.md` (mandatory Step 1 inventory producer) · `rules/hatch3r-theming.md` (token layering, theme sets, dark-theme chroma reduction) · `rules/hatch3r-component-conventions.md` (how downstream components consume the tokens) · `rules/hatch3r-accessibility-standards.md` (WCAG 2.2 AA criteria behind the Step 5 rows) · `agents/hatch3r-ui.md` (CQ1 acceptance bar).

package/dist/content/commands/hatch3r-diagnose.md

@@ -100,7 +100,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the Step 6 Iteration 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 actuals + delta land in the Step 6 Iteration Summary recap (cost facet; full blocks on the `Cost:` exception line beyond ±25%) per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
 
 ### Effort Override (Decision 17)
 
@@ -166,7 +166,7 @@ Each fixer prompt MUST include:
 4. The confidence expression requirement (verbatim).
 5. Explicit: do NOT create branches, commits, or PRs — the fixer's standing boundary; this command stops before commit for human review.
 
-Await the fixer's structured result. Capture its `Delegation proof ID` per file (quoted verbatim in the Step 6 attestation) and its `Reviewer re-run required` signal. When a fix touches framework source under `src/`, honor the fixer's reviewer-loop continuation signal — but this command does not run the full Phase 3 review loop; it surfaces `Reviewer re-run required: true` as a Suggested Next Action in Step 6 rather than auto-spawning a reviewer.
+Await the fixer's structured result. Capture its `Delegation proof ID` per file (quoted verbatim in the Step 6 attestation) and its `Reviewer re-run required` signal. When a fix touches framework source under `src/`, honor the fixer's reviewer-loop continuation signal — but this command does not run the full Phase 3 review loop; it surfaces `Reviewer re-run required: true` on the `Next:` line of the Step 6 recap rather than auto-spawning a reviewer.
 
 ---
 
@@ -180,26 +180,18 @@ Re-run the relevant Step 1 probe(s) to confirm the fix cleared the symptom: re-r
 
 ### 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., "Diagnosed manifest schema drift; migrated .hatch3r/hatch.json to schemaVersion 3; hatch3r status now clean."}
-
-**Done:**
-- {finding} → fixed via hatch3r-fixer (proof: {id}); verified by {re-run command} exit 0
-
-**Not Done / Deferred / Unverified:**
-- (or: `None — full scope completed`)
-
-**Open Questions / Blockers:**
-- (or: `None`)
-
-**Fan-out + Cost:** sub_agents_spawned: { count, rationale } + cost_estimate / cost_actuals / delta
-**Confidence:** {high | medium | low} — {basis from researcher + fixer outputs}
-**Suggested Next Action:** {one line — e.g., "Commit the manifest migration; re-run /hatch3r-diagnose if drift reappears."}
+**PARTIAL** — Diagnosed manifest schema drift; migrated .hatch3r/hatch.json to schemaVersion 3; primary symptom resolved (hatch3r status re-run clean); second symptom not yet reproduced.
+files 1 (+3/−1) · sa 3/3 · gates 2/2 · cost Δ−8% tok / Δ+5% min · tier 3
+Blockers: second symptom (intermittent sync stall) not reproduced against the captured state bundle — needs a failing transcript
+Confidence: medium — primary fix verified by re-run probe; residual symptom unreproduced.
+Next: commit the manifest migration; re-run /hatch3r-diagnose if the stall recurs.
 ```
 
 Status decision rules:

package/dist/content/commands/hatch3r-feature-plan.md

@@ -29,7 +29,7 @@ sub_agents_spawned:
 | 2. Document Generation | `hatch3r-docs-writer` (spec, ADRs) | Yes | Yes |
 | 3. Todo Generation | Orchestrator (inline) | No | Yes |
 
-**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.
 
 # Feature Plan — Single Feature Specification from Idea to Board-Ready Epic
 
@@ -86,7 +86,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the iteration 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)
 
@@ -527,30 +527,18 @@ feature-plan is long-running — a Tier 3 cross-cutting feature fans out four pa
 
 ## 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.
-- **Post-execution `cost_actuals` + `delta`** — appended to the iteration 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: 13` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): Tier 1 ≈ 2 (reduced researcher set + docs-writer); Tier 2 ≈ 6; Tier 3 up to 13 (4-5 parallel researcher modes + docs-writer + the 9 CQ vector specialists advising pre-write). 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-handoff.md

@@ -25,7 +25,7 @@ sub_agents_spawned:
 
 The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task tool. The other four subcommands (`resume`, `list`, `complete`, `prune`) run inline within this command — they read, list, transition status, or archive files and do not require a sub-agent.
 
-**Parallel-safety conditions** (per `rules/hatch3r-agent-orchestration.md` §Parallel Safety): any parallel fan-out 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): any parallel fan-out holds all three — read-only or disjoint writes (file- and contract-level), deterministic aggregation, no shared mutable state.
 
 ## Learnings Consultation
 
@@ -59,7 +59,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the Iteration 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)
 
@@ -162,30 +162,18 @@ ID                                              STATUS         BRANCH
 
 ## 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 `prepare` subcommand invokes `hatch3r-handoff-preparer`. Inline subcommands emit a one-line `expected_sa_count: 0` cost note.
-- **Post-execution `cost_actuals` + `delta`** — appended to the Iteration 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: 1` × tier heuristic in `rules/hatch3r-cost-visibility.md` Pre-Execution Estimate): `prepare` ≈ 1 (one preparer delegation); `resume` ≈ 0 (inline drift check + status transition); `list`/`complete`/`prune` ≈ 0 (filesystem read or single-file rename). This command is local-only — `estimated_web_research_queries` is always 0. 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-healthcheck.md

@@ -33,7 +33,7 @@ This command discovers the module taxonomy via static analysis, then delegates i
 | 4. Issue Creation | Orchestrator (GitHub MCP) | No | Yes |
 | 5. Board Sync | Orchestrator (Projects v2 sync) | No | Yes |
 
-**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.
 
 All issue operations MUST follow the Projects v2 Enforcement rules defined in `hatch3r-board-shared`.
 
@@ -61,7 +61,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the Step 6 finalization 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)
 
@@ -384,30 +384,18 @@ healthcheck is long-running — module discovery (Step 2) seeds a per-module hat
 
 ## 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 the Pre-Execution Cost Preview above before the first module audit-authoring dispatch (Step 4).
-- **Post-execution `cost_actuals` + `delta`** — appended to the Step 6 finalization 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`, which is the static floor; actual fan-out scales with discovered module count per `rules/fan-out-discipline.md` P8 B2): one `hatch3r-implementer` Task per module sub-issue body + `hatch3r-ui` (CQ1) + `hatch3r-security` (CQ3 supply-chain slice) for the two cross-cutting axes. Tier 2 (module count ≤8) and Tier 3 (module count >8) both bound the parallel module batch by `max_phase4_parallel`. 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-incident-response.md

@@ -91,7 +91,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the iteration summary's Fan-out + Cost section per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`; estimation primitives from `src/pipeline/costEstimator.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`; estimation primitives from `src/pipeline/costEstimator.ts`.
 
 ### Effort Override (Decision 17)
 
@@ -171,23 +171,11 @@ Commit message format: `docs: post-mortem for {incident-slug}` (post-mortem + ru
 
 ## 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`.
 
 ---
 

package/dist/content/commands/hatch3r-migration-plan.md

@@ -29,7 +29,7 @@ sub_agents_spawned:
 | 2. Impact Analysis | `hatch3r-architect` | No | Yes |
 | 3. Plan Generation | `hatch3r-docs-writer` | No | Yes |
 
-**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.
 
 # Migration Plan — Dependency or Framework Upgrade from Assessment to Phased Execution
 
@@ -83,7 +83,7 @@ cost_estimate:
   estimated_duration_min: <int>
 ```
 
-Post-execution actuals + delta land in the iteration 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 actuals + delta land in the Iteration Summary recap (cost facet; full blocks on the `Cost:` exception line beyond ±25%) per `rules/hatch3r-cost-visibility.md` Post-Execution Actuals. Token telemetry sources from `src/pipeline/observability.ts`.
 
 ### Effort Override (Decision 17)
 
@@ -390,30 +390,18 @@ migration-plan is long-running — a Tier 3 multi-major-version or framework mig
 
 ## 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; both land in the Iteration Summary recap (cost facet; full blocks 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.
-- **Post-execution `cost_actuals` + `delta`** — appended to the iteration summary's Fan-out + Cost section per `rules/hatch3r-iteration-summary.md` §2.
+- **Post-execution `cost_actuals` + `delta`** — appended to the Iteration Summary recap (cost facet; full blocks 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 ≈ 1 (two researchers, architect skipped when no breaking changes); Tier 2 ≈ 3 (two parallel researchers + architect, docs-writer); Tier 3 up to 3 (same fan-out, deeper changelog + incremental-vs-direct analysis). 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`.