hatch3r 2.1.0 → 2.2.0

package/dist/content/rules/hatch3r-dynamic-stack-verification.md

@@ -0,0 +1,114 @@
+---
+id: hatch3r-dynamic-stack-verification
+type: rule
+description: Runtime-evidence gates for stacks with no static type layer (plain-JS Vue, dynamic persistence) — smoke-mount changed components, dormant-collection-read ratchet, runtime smoke evidence on module-boundary changes; a green lint+build+mock-suite proves a layer, not the system.
+scope: conditional
+globs: "**/*.vue,**/*.js,**/*.mjs,**/*.cjs,**/*.jsx,**/composables/**,**/stores/**"
+tags: [review, implementation, testing]
+precedence: high
+quality_charter: agents/shared/quality-charter.md
+cache_friendly: true
+---
+# Dynamic Stack Verification
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ5 (Testability)
+
+## Applicability Gate
+
+The globs above over-attach by construction: editor rule-scoping is glob-only, while "no static type layer" is a project property no glob can express. Self-resolve on activation — exit early when a compiler already validates the consumer side of the changed file:
+
+1. **Checked JS:** the changed `.js`/`.mjs`/`.cjs`/`.jsx` file is reached by a `tsconfig.json` or `jsconfig.json` (`include`/`files`) that enables `checkJs` → skip.
+2. **Typed SFC:** the changed Vue SFC declares `<script lang="ts">` or `<script setup lang="ts">` → skip.
+3. **Pragma coverage:** a `// @ts-check` or `/* @flow */` pragma covers the changed file → skip.
+
+When a checker is authoritative, defer to the compiler gates (`tsc --noEmit`, `vue-tsc`, `flow check`) and the rules that govern typed code. Record the skip in one review-note line — `dynamic-stack-verification: skipped (vue-tsc covers file)` — so "gate passed" and "gate not applicable" stay distinguishable. This rule exists for the residue: files where no compiler validates cross-module contracts, so contract drift reaches runtime unflagged.
+
+## Layer-vs-System
+
+Lint, build, and a mocked test suite each prove one layer; none proves the system. Drift classes that pass all three in a typeless stack and fail only at runtime:
+
+- **Client↔server field-name drift** — the server renames `userId` → `user_id`; the client bundle still builds.
+- **Event-name drift** — the emitter renames `order:placed` → `order.placed`; every listener still lints green.
+- **Store-key drift** — a state key is renamed in the store; consumers read `undefined` without a single thrown error.
+- **i18n-key drift** — an interpolated key no longer resolves; the UI renders the raw key string.
+- **Persisted collection-name drift** — writes target `orders`, reads target `order`; both queries execute without error against empty results.
+
+Empirical anchor: a static type layer flags ~15% of shipped JavaScript bugs (Gao/Bird/Barr, ICSE 2017 — References). A stack that forgoes that layer substitutes runtime evidence for it — not nothing. Report a green lint+build+mock-suite as a layer-level result, never as system verification.
+
+## Smoke-Mount Gate
+
+Every changed component mounts in the test runner — Vue Test Utils `mount()` or Testing Library `render` — with minimal REAL plumbing, not a fully stubbed shell:
+
+- **Store:** the real store plugin via `global.plugins`, or `provide` keyed by the REAL injection key the component injects — a stub keyed to a guessed shape defeats the gate.
+- **i18n:** a real i18n instance with the default locale loaded.
+- **Props:** the component's required props at realistic values.
+
+Minimal assertion — both clauses required:
+
+1. the component constructs without throwing, and
+2. one expected node is present (`wrapper.find('[data-test="..."]').exists()` / `screen.getByRole(...)`).
+
+```js
+const wrapper = mount(OrderSummary, {
+  props: { orderId: 'ord_123' },
+  global: { plugins: [store, i18n] }, // real store, real injection keys
+})
+expect(wrapper.find('[data-test="order-total"]').exists()).toBe(true)
+```
+
+Why mount, not import: `mount()` executes `setup()`, computed store access, and injection resolution immediately, so store-shape mismatches, missing injection keys, and prop-contract breaks surface at mount time — before any interaction is scripted.
+
+**Severity:** missing smoke-mount on a changed component = Warning; on a route-level component (a router target) = Critical.
+
+This gate is the floor BELOW the visual/behavioral mandates in `rules/hatch3r-testability.md` and `rules/hatch3r-ux-states-and-flows.md` — both stay authoritative for their depth (test-class mandates, state-flow and visual coverage); this gate adds only the construct-against-real-contracts floor beneath them.
+
+## Dynamic i18n Keys
+
+Static extraction cannot see interpolated keys (`t('status.' + value)`, template-literal keys). The verification contract is owned by `rules/hatch3r-i18n.md` → Dynamic Keys: a test iterating the full value set and asserting each resolved key exists in the default locale, or a co-located comment enumerating the concrete keys.
+
+Typeless-stack addendum: with no enum type constraining the interpolated value, the full-value-set key-existence test is the only available proof — treat every dynamic i18n call site in the diff as unverified until it carries one.
+
+## Dormant-Collection-Read Ratchet
+
+No compiler links a string-named write site to its read site. Per changed module:
+
+1. **Inventory (grep-derived):** collect persistence identifiers — collection/table/model names — at call sites in the changed module: `collection('x')`, `.from('x')`, `db.x`, `model('X')` (e.g. `grep -nE "collection\(|\.from\(|db\.\w|model\(" <changed-module>`).
+2. **Classify each identifier's edge:**
+   - **written-and-read** — both sides exist in the codebase; the pairing is the proof.
+   - **written-never-read** — data persisted that no code consumes.
+   - **read-never-written** — a consumer waiting on data no code produces.
+3. **Resolve every one-sided (dormant) edge** with exactly one of:
+   - **runtime proof** — a smoke test executing that read/write path against a real or emulated store, or
+   - **a co-located annotation** — `// dormant-by-design: <reason>` (external writer, scheduled job, analytics consumer, migration in flight).
+
+An identifier resolved from a variable (`db[collectionVar]`, `collection(name)`) cannot be inventoried statically — list the call site itself as a dormant edge until a runtime proof covers it.
+
+**Ratchet mechanics (Betterer-style — References):**
+
+- The count of unproven dormant edges per module is a committed baseline.
+- A PR MUST NOT increase the count — fail the check on new violations.
+- An improvement shrinks the baseline in the same PR.
+- A deliberate increase requires an explicit baseline-update step with a written rationale in the PR description.
+- Report before/after counts in the review verdict.
+
+## Boundary-Change Runtime Evidence
+
+A client↔server or module-boundary change — changed exports, HTTP request/response shapes, event names, store contracts — requires ONE piece of captured runtime evidence crossing the changed boundary, cited in the review verdict:
+
+- an executed request/response transcript (curl output, recorded fetch, HAR excerpt),
+- a mounted-flow console log or screenshot exercising the changed contract, or
+- a seeded local run whose output shows the boundary round-trip.
+
+Evidence MUST postdate the diff — a transcript captured before the change proves the old contract, not the new one. A green build is not that evidence: each side passing against its own mock proves agreement with the mock, not agreement between the sides (contract-testing rationale — Pact, References). Deep-context scoring already weights this change class +2 (`rules/hatch3r-deep-context.md`, complexity signal "Module-boundary or client↔server contract change in files with no static type coverage").
+
+**Severity:** boundary change with zero runtime evidence = Warning; on payment, auth, or data-mutation paths = Critical.
+
+## References
+
+- Vue Test Utils — crash course + Testing Vuex guide: https://test-utils.vuejs.org/guide/essentials/a-crash-course.html and https://test-utils.vuejs.org/guide/advanced/vuex.html (accessed 2026-07-08, T1, current) — 3-line mount smoke; real store via `global.plugins`; mount executes store access.
+- Testing Library — Vue Testing Library intro: https://testing-library.com/docs/vue-testing-library/intro/ (accessed 2026-07-08, T1, current) — tests resemble the way the software is used.
+- Gao, Bird, Barr — "To Type or Not to Type: Quantifying Detectable Bugs in JavaScript" (ICSE 2017): https://earlbarr.com/publications/typestudy.pdf (accessed 2026-07-08, T1 peer-reviewed, canonical) — a static type layer detects ~15% of shipped JS bugs (CI 11.5–18.5%); 2022 follow-up as currency pointer: https://arxiv.org/abs/2203.11115.
+- Pact — "How Pact works": https://docs.pact.io/getting_started/how_pact_works (accessed 2026-07-08, T1, page updated 2024-12-23) — mocked suites pass while the real provider differs.
+- i18next-parser — README: https://github.com/i18next/i18next-parser (accessed 2026-07-08, T2, repository archived 2026-02-22) — documents the dynamic-key blind spot in static extraction.
+- knip: https://knip.dev (accessed 2026-07-08, T2, current) — dynamic references as the static-reachability failure class.
+- Betterer: https://phenomnomnominal.github.io/betterer (accessed 2026-07-08, T2, current) — baseline snapshot, fail-on-worse, shrink-on-better.

package/dist/content/rules/hatch3r-dynamic-stack-verification.mdc

@@ -0,0 +1,109 @@
+---
+description: Runtime-evidence gates for stacks with no static type layer (plain-JS Vue, dynamic persistence) — smoke-mount changed components, dormant-collection-read ratchet, runtime smoke evidence on module-boundary changes; a green lint+build+mock-suite proves a layer, not the system.
+globs: ["**/*.vue", "**/*.js", "**/*.mjs", "**/*.cjs", "**/*.jsx", "**/composables/**", "**/stores/**"]
+alwaysApply: false
+precedence: high
+---
+# Dynamic Stack Verification
+
+**Pillars:** P2 (Scientific & Practical Quality), CQ5 (Testability)
+
+## Applicability Gate
+
+The globs above over-attach by construction: editor rule-scoping is glob-only, while "no static type layer" is a project property no glob can express. Self-resolve on activation — exit early when a compiler already validates the consumer side of the changed file:
+
+1. **Checked JS:** the changed `.js`/`.mjs`/`.cjs`/`.jsx` file is reached by a `tsconfig.json` or `jsconfig.json` (`include`/`files`) that enables `checkJs` → skip.
+2. **Typed SFC:** the changed Vue SFC declares `<script lang="ts">` or `<script setup lang="ts">` → skip.
+3. **Pragma coverage:** a `// @ts-check` or `/* @flow */` pragma covers the changed file → skip.
+
+When a checker is authoritative, defer to the compiler gates (`tsc --noEmit`, `vue-tsc`, `flow check`) and the rules that govern typed code. Record the skip in one review-note line — `dynamic-stack-verification: skipped (vue-tsc covers file)` — so "gate passed" and "gate not applicable" stay distinguishable. This rule exists for the residue: files where no compiler validates cross-module contracts, so contract drift reaches runtime unflagged.
+
+## Layer-vs-System
+
+Lint, build, and a mocked test suite each prove one layer; none proves the system. Drift classes that pass all three in a typeless stack and fail only at runtime:
+
+- **Client↔server field-name drift** — the server renames `userId` → `user_id`; the client bundle still builds.
+- **Event-name drift** — the emitter renames `order:placed` → `order.placed`; every listener still lints green.
+- **Store-key drift** — a state key is renamed in the store; consumers read `undefined` without a single thrown error.
+- **i18n-key drift** — an interpolated key no longer resolves; the UI renders the raw key string.
+- **Persisted collection-name drift** — writes target `orders`, reads target `order`; both queries execute without error against empty results.
+
+Empirical anchor: a static type layer flags ~15% of shipped JavaScript bugs (Gao/Bird/Barr, ICSE 2017 — References). A stack that forgoes that layer substitutes runtime evidence for it — not nothing. Report a green lint+build+mock-suite as a layer-level result, never as system verification.
+
+## Smoke-Mount Gate
+
+Every changed component mounts in the test runner — Vue Test Utils `mount()` or Testing Library `render` — with minimal REAL plumbing, not a fully stubbed shell:
+
+- **Store:** the real store plugin via `global.plugins`, or `provide` keyed by the REAL injection key the component injects — a stub keyed to a guessed shape defeats the gate.
+- **i18n:** a real i18n instance with the default locale loaded.
+- **Props:** the component's required props at realistic values.
+
+Minimal assertion — both clauses required:
+
+1. the component constructs without throwing, and
+2. one expected node is present (`wrapper.find('[data-test="..."]').exists()` / `screen.getByRole(...)`).
+
+```js
+const wrapper = mount(OrderSummary, {
+  props: { orderId: 'ord_123' },
+  global: { plugins: [store, i18n] }, // real store, real injection keys
+})
+expect(wrapper.find('[data-test="order-total"]').exists()).toBe(true)
+```
+
+Why mount, not import: `mount()` executes `setup()`, computed store access, and injection resolution immediately, so store-shape mismatches, missing injection keys, and prop-contract breaks surface at mount time — before any interaction is scripted.
+
+**Severity:** missing smoke-mount on a changed component = Warning; on a route-level component (a router target) = Critical.
+
+This gate is the floor BELOW the visual/behavioral mandates in `rules/hatch3r-testability.md` and `rules/hatch3r-ux-states-and-flows.md` — both stay authoritative for their depth (test-class mandates, state-flow and visual coverage); this gate adds only the construct-against-real-contracts floor beneath them.
+
+## Dynamic i18n Keys
+
+Static extraction cannot see interpolated keys (`t('status.' + value)`, template-literal keys). The verification contract is owned by `rules/hatch3r-i18n.md` → Dynamic Keys: a test iterating the full value set and asserting each resolved key exists in the default locale, or a co-located comment enumerating the concrete keys.
+
+Typeless-stack addendum: with no enum type constraining the interpolated value, the full-value-set key-existence test is the only available proof — treat every dynamic i18n call site in the diff as unverified until it carries one.
+
+## Dormant-Collection-Read Ratchet
+
+No compiler links a string-named write site to its read site. Per changed module:
+
+1. **Inventory (grep-derived):** collect persistence identifiers — collection/table/model names — at call sites in the changed module: `collection('x')`, `.from('x')`, `db.x`, `model('X')` (e.g. `grep -nE "collection\(|\.from\(|db\.\w|model\(" <changed-module>`).
+2. **Classify each identifier's edge:**
+   - **written-and-read** — both sides exist in the codebase; the pairing is the proof.
+   - **written-never-read** — data persisted that no code consumes.
+   - **read-never-written** — a consumer waiting on data no code produces.
+3. **Resolve every one-sided (dormant) edge** with exactly one of:
+   - **runtime proof** — a smoke test executing that read/write path against a real or emulated store, or
+   - **a co-located annotation** — `// dormant-by-design: <reason>` (external writer, scheduled job, analytics consumer, migration in flight).
+
+An identifier resolved from a variable (`db[collectionVar]`, `collection(name)`) cannot be inventoried statically — list the call site itself as a dormant edge until a runtime proof covers it.
+
+**Ratchet mechanics (Betterer-style — References):**
+
+- The count of unproven dormant edges per module is a committed baseline.
+- A PR MUST NOT increase the count — fail the check on new violations.
+- An improvement shrinks the baseline in the same PR.
+- A deliberate increase requires an explicit baseline-update step with a written rationale in the PR description.
+- Report before/after counts in the review verdict.
+
+## Boundary-Change Runtime Evidence
+
+A client↔server or module-boundary change — changed exports, HTTP request/response shapes, event names, store contracts — requires ONE piece of captured runtime evidence crossing the changed boundary, cited in the review verdict:
+
+- an executed request/response transcript (curl output, recorded fetch, HAR excerpt),
+- a mounted-flow console log or screenshot exercising the changed contract, or
+- a seeded local run whose output shows the boundary round-trip.
+
+Evidence MUST postdate the diff — a transcript captured before the change proves the old contract, not the new one. A green build is not that evidence: each side passing against its own mock proves agreement with the mock, not agreement between the sides (contract-testing rationale — Pact, References). Deep-context scoring already weights this change class +2 (`rules/hatch3r-deep-context.md`, complexity signal "Module-boundary or client↔server contract change in files with no static type coverage").
+
+**Severity:** boundary change with zero runtime evidence = Warning; on payment, auth, or data-mutation paths = Critical.
+
+## References
+
+- Vue Test Utils — crash course + Testing Vuex guide: https://test-utils.vuejs.org/guide/essentials/a-crash-course.html and https://test-utils.vuejs.org/guide/advanced/vuex.html (accessed 2026-07-08, T1, current) — 3-line mount smoke; real store via `global.plugins`; mount executes store access.
+- Testing Library — Vue Testing Library intro: https://testing-library.com/docs/vue-testing-library/intro/ (accessed 2026-07-08, T1, current) — tests resemble the way the software is used.
+- Gao, Bird, Barr — "To Type or Not to Type: Quantifying Detectable Bugs in JavaScript" (ICSE 2017): https://earlbarr.com/publications/typestudy.pdf (accessed 2026-07-08, T1 peer-reviewed, canonical) — a static type layer detects ~15% of shipped JS bugs (CI 11.5–18.5%); 2022 follow-up as currency pointer: https://arxiv.org/abs/2203.11115.
+- Pact — "How Pact works": https://docs.pact.io/getting_started/how_pact_works (accessed 2026-07-08, T1, page updated 2024-12-23) — mocked suites pass while the real provider differs.
+- i18next-parser — README: https://github.com/i18next/i18next-parser (accessed 2026-07-08, T2, repository archived 2026-02-22) — documents the dynamic-key blind spot in static extraction.
+- knip: https://knip.dev (accessed 2026-07-08, T2, current) — dynamic references as the static-reachability failure class.
+- Betterer: https://phenomnomnominal.github.io/betterer (accessed 2026-07-08, T2, current) — baseline snapshot, fail-on-worse, shrink-on-better.

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

@@ -83,7 +83,7 @@ The OpenAPI / AsyncAPI / GraphQL SDL `info.version` MUST be aligned to the relea
 
 On stable endpoints:
 
-- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking.
+- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking. Remedy: façade contract-hold (`rules/hatch3r-contract-census.md`) — keep the key emitted, hard-null it behind the façade, delete only at the contract phase.
 - **Deprecation header (RFC 9745)** — emit `Deprecation: @1735689600` (Unix-time) or `Deprecation: Tue, 20 May 2025 00:00:00 GMT` (IMF-fixdate) on retiring endpoints.
 - **Sunset header (RFC 8594)** — emit `Sunset: Tue, 31 Dec 2025 23:59:59 GMT` (IMF-fixdate only) on retiring endpoints. Sunset date MUST be later than Deprecation date.
 - **Migration link** — emit `Link: <https://api.example.com/docs/migration>; rel="deprecation"` + `Link: <…>; rel="sunset"`.

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

@@ -78,7 +78,7 @@ The OpenAPI / AsyncAPI / GraphQL SDL `info.version` MUST be aligned to the relea
 
 On stable endpoints:
 
-- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking.
+- **Additive schema** — new fields are optional; default values are documented; consumers ignore unknown fields. Removing a field is breaking; renaming is breaking. Remedy: façade contract-hold (`rules/hatch3r-contract-census.md`) — keep the key emitted, hard-null it behind the façade, delete only at the contract phase.
 - **Deprecation header (RFC 9745)** — emit `Deprecation: @1735689600` (Unix-time) or `Deprecation: Tue, 20 May 2025 00:00:00 GMT` (IMF-fixdate) on retiring endpoints.
 - **Sunset header (RFC 8594)** — emit `Sunset: Tue, 31 Dec 2025 23:59:59 GMT` (IMF-fixdate only) on retiring endpoints. Sunset date MUST be later than Deprecation date.
 - **Migration link** — emit `Link: <https://api.example.com/docs/migration>; rel="deprecation"` + `Link: <…>; rel="sunset"`.

package/dist/content/rules/hatch3r-findings-ledger.md

@@ -0,0 +1,129 @@
+---
+id: hatch3r-findings-ledger
+type: rule
+description: Write-ahead findings ledger — every review-loop finding is registered on disk before fix dispatch, folds to a terminal disposition at run exit, and survives interruption; no finding ends a run pending.
+tags: [orchestration, review, floor:protocol]
+precedence: high
+scope: always
+---
+# hatch3r Findings Ledger
+
+**Pillars:** P2 (Scientific & Practical Quality), P8 (Clarification & Fan-out Discipline)
+
+This rule closes one failure class: review-loop findings that are registered in chat but never implemented — Suggestions dropped on clean exits, findings lost at loop exhaustion, sub-agent death, or context compaction, and cross-iteration finding identity reduced to a bare unresolved-count. The fix is a write-ahead ledger: every finding is persisted to disk BEFORE the fixer that would address it is dispatched — the ordering Temporal applies to workflow commands (persisted before execution; `docs.temporal.io/encyclopedia/event-history`, accessed 2026-07-08) — and disk state, not chat context, is the recovery source after interruption (durable file/JSON state over context, per Anthropic's long-running-agent harness guidance; `anthropic.com/engineering/effective-harnesses-for-long-running-agents`, accessed 2026-07-08). At run exit every row folds to exactly one terminal disposition; no finding ends a run pending.
+
+## Store & Format
+
+One JSONL file per run: `.hatch3r/findings/<YYYY-MM-DD>-<command>-<run8>.jsonl`, where `<run8>` is the first 8 hex chars of the run's `correlation_id` (`rules/hatch3r-agent-orchestration.md` → Correlation ID) and `<command>` is the invoking command's short name — the `hatch3r-` prefix dropped (e.g. `workflow`, `pr-resolve`). Append-only; atomic append via the `src/merge/safeWrite.ts` pattern (temp+rename then concat) — the same convention as `.hatch3r/bypass-log.jsonl`.
+
+- **Full-row snapshots.** Every append is a complete row, never a partial patch. **Fold rule: last line per `finding_id` wins.** Any reader reconstructs current state by folding the file top to bottom.
+- **Closure marker.** A final marker row with `"finding_id":"run-exit"` closes a file. Closed = last line is `run-exit` AND the fold is all-terminal. The marker row carries `ts`, `run_id`, `command`, `iteration`, and `finding_id` only.
+- **Committed, not gitignored.** `.hatch3r/findings/` gets no gitignore entry — matching the `.hatch3r/review-findings/` + `todo.md` team-memory precedent — so open findings are visible in the PR diff. Degradation: in a repo with a blanket `.hatch3r/` ignore, interruption-proofing stays (same machine) but team visibility is lost.
+
+Row schema (JSON keys):
+
+| Key | Value |
+|---|---|
+| `ts` | ISO-8601 UTC append time |
+| `run_id` | `<run8>` |
+| `command` | the filename's `<command>` token |
+| `iteration` | review-loop iteration number at append time |
+| `finding_id` | `<run8>-F<seq>` — see Finding IDs |
+| `severity` | `Critical \| Warning \| Suggestion` |
+| `source` | `reviewer \| specialist \| edge-case-ledger \| pr-comment \| spec-review` |
+| `file` | `path:line`, or `issue#N` for board-scoped findings |
+| `summary` | ≤200 chars |
+| `disposition` | `registered` → `targeted \| deferred \| declined \| accepted-risk \| escalated \| already-resolved \| surfaced` |
+| `status` | `pending` → `in-fix` → `done \| failed \| never-attempted` |
+| `closure_ref` | commit SHA, fixer `Findings addressed` quote, todo.md anchor, quoted user reply ≤100 chars, or `review-findings/<id>` |
+
+`status: done` with `closure_ref: null` is ILLEGAL — closure always names its evidence.
+
+## Finding IDs
+
+`finding_id` = `<run8>-F<seq>`; the orchestrator assigns `<seq>` in registration order (F1, F2, …). The reviewer is stateless, so ID continuity is the orchestrator's job: it passes the prior iteration's findings table (`finding_id`, file, summary, status) in every re-review prompt. The reviewer's severity tables carry an `ID` column — reuse the supplied ID for a persisting finding; write `new` for a first appearance (the orchestrator assigns the next `F<seq>`) — plus a `Resolved since last iteration: <ids | none>` line below the tables. Identity heuristic when uncertain: same file + same defect class = same ID. This contract is mirrored in `agents/hatch3r-reviewer.md` → Finding IDs; keep the two aligned when either changes.
+
+## Write Points
+
+| Point | Trigger | Appends |
+|---|---|---|
+| **W1 write-ahead** | reviewer verdict parsed, BEFORE any fixer dispatch — every iteration | new Critical/Warning rows as `targeted`/`pending`; new Suggestions as `registered`/`pending`; one `registered`/`pending` Warning row per reviewer `deferred:` partial-review remainder (summary = the unreviewed item), so unreviewed surfaces survive the session |
+| **W2 per-iteration reconciliation** | after fixer return AND re-review | fixed-and-confirmed rows flip to `done` + `closure_ref`; attempted-but-still-failing rows to `failed`; rows the re-review reports resolved without this run's fix to `already-resolved` |
+| **W3 loop-exit reconciliation** | every exit path: clean, max-iterations, DESIGN_OBJECTION, user abort | resolve every non-terminal row to a legal terminal (Run-Exit Invariant), then append the `run-exit` marker row |
+| **W4 sub-agent-death flush** | the retry/BLOCKED_OTHER path of sub-agent-failure handling (`rules/hatch3r-agent-orchestration.md`) | flush in-flight rows — `in-fix` → `failed`, reason noted in `closure_ref` — before the retry and again before the ASK; a retry that lands re-flips the row at W2 (last line wins) |
+| **W5 Suggestion terminalization** | at W3 | every Suggestion row goes terminal — grammar in Suggestion Handling |
+
+At fixer dispatch the orchestrator appends each targeted row's `pending` → `in-fix` snapshot — the in-flight state W4 flushes. Run-start side task, with W1's first append: create `.hatch3r/findings/` when absent, then run the Hygiene prune.
+
+## Run-Exit Invariant
+
+After W3, zero rows fold to `status: pending` or `in-fix`, and zero rows fold to `disposition: registered`. Every folded row lands on one of the legal terminals:
+
+- (a) `targeted` + `done` + `closure_ref`
+- (b) `already-resolved`
+- (c) `deferred` — with a todo.md anchor in `closure_ref`
+- (d) `declined` or `accepted-risk` — user-attested only: each requires a quoted user reply in `closure_ref`; an autonomous run cannot produce them (`agents/shared/user-question-protocol.md` → Unattested product decision)
+- (e) `escalated` — with an open ASK recorded; legal only when the run's own status is not SUCCESS (unattended runs take this path and exit PARTIAL)
+- (f) `surfaced` — Suggestion severity only; the ID appears on the recap's `Open findings:` line
+
+A Critical/Warning finding that cannot reach (a)–(d) forces an ASK. Terminal `status` pairs mechanically with the outcome: `done` = this run's fix landed (`closure_ref` required); `failed` = attempted and not landed (never a resting terminal alone — the disposition must still reach (c)–(e)); `never-attempted` = closed without a fix attempt this run (`deferred`, `declined`, `accepted-risk`, `escalated`, `surfaced`, `already-resolved`).
+
+## Suggestion Handling
+
+Suggestions register once, at first appearance (W1, `registered`/`pending`); a reviewer repeating one in a later iteration causes no re-append — unless its severity changed, which appends a new full-row snapshot (same `finding_id`, new severity). At W3 every Suggestion row goes terminal (W5) via exactly one of:
+
+- `surfaced` — the ID is printed on the Iteration Summary's `Open findings:` line (`rules/hatch3r-iteration-summary.md` → Exception Lines). This is the never-silently-dropped guarantee: a clean exit still names every unaddressed Suggestion. Unattended default.
+- `deferred` — the user chose deferral; `closure_ref` = the todo.md anchor.
+- `declined` — the user declined; `closure_ref` = the quoted user reply (≤100 chars).
+
+## Session-Start Surfacing
+
+`agents/hatch3r-handoff-loader.md` owns this step. At session start the loader scans `.hatch3r/findings/*.jsonl` (skips silently when the directory is absent), skips closed files, folds each remaining file, and lists open rows — non-terminal rows plus rows terminal as `escalated`/`surfaced` — as `id · severity · file · summary · disposition`. A ledger file older than 14 days that still folds open rows is flagged stale, with three closure options: close as declined with reason "stale", re-defer to todo.md, or resume the work. This scan is the self-healing detector for runs that died before W3: whatever a crash left open re-surfaces next session instead of staying lost.
+
+## Handoff Integration
+
+No handoff-schema change. `agents/hatch3r-handoff-preparer.md` folds the active run's ledger in its collect-state step, and that fold is authoritative for the handoff's Work Remaining `Open findings` bullet at composition time — the handoff inherits open findings from the same fold every other consumer reads. The recap's `Open findings:` exception line (`rules/hatch3r-iteration-summary.md` → Exception Lines) is cross-check provenance, not the source: when it agrees with the fold the preparer copies it verbatim; when it is absent or disagrees (stale recap, mid-session interrupt) the fold wins and the bullet notes `(fold-derived; last recap stale or absent)`; zero open rows ⇒ no bullet. Composition procedure lives in `agents/hatch3r-handoff-preparer.md`, mirrored in `skills/hatch3r-handoff-prepare/SKILL.md` — keep the three aligned when any changes.
+
+## Store Boundaries
+
+Three stores, three jobs. Writes flow ledger-outward — the ledger is written first; the other stores derive from it, never the reverse.
+
+| Store | Role |
+|---|---|
+| `.hatch3r/findings/` (this ledger) | Execution-lifecycle write-ahead log. Run-scoped; carries ALL severities; the source of truth for "is anything open?" |
+| `.hatch3r/review-findings/` | Cross-PR reviewer memory of RESOLVED Critical/Warning findings. Its post-loop append DERIVES from the ledger fold — each entry cites its `finding_id` — never the reverse |
+| `todo.md` | Human follow-up backlog. A `deferred` row's `closure_ref` is the todo.md anchor; the todo bullet carries `[ledger: <finding_id>]`; after deferral the board owns the item (the ledger row is terminal) |
+
+## Hygiene
+
+- The owning orchestrator closes its own file at W3. A dead run's file is never closed by another run — the loader surfaces it (Session-Start Surfacing) for a user decision.
+- Prune at any run's W1: when more than 20 closed files exist, or any closed file is older than 30 days, delete the oldest closed files down to those bounds. Git history preserves pruned files; open files are never pruned.
+
+## Worked Example
+
+A 2-iteration `hatch3r-workflow` run (`run8` = `a3f81c2e`, file `.hatch3r/findings/2026-07-08-workflow-a3f81c2e.jsonl`): iteration 1 registers one Critical, one Warning, one Suggestion; the fixer takes the first two; iteration 2's re-review confirms both resolved; the Suggestion terminalizes as `surfaced`, so the recap prints `Open findings: a3f81c2e-F3 Suggestion — surfaced`.
+
+```jsonl
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F3","severity":"Suggestion","source":"reviewer","file":"src/auth/session.ts:41","summary":"Extract shared cookie-parse helper","disposition":"registered","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:38Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"in-fix","closure_ref":null}
+{"ts":"2026-07-08T14:02:38Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"in-fix","closure_ref":null}
+{"ts":"2026-07-08T14:11:02Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"done","closure_ref":"fixer: Findings addressed — a3f81c2e-F1 timingSafeEqual"}
+{"ts":"2026-07-08T14:11:02Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"done","closure_ref":"fixer: Findings addressed — a3f81c2e-F2 expiry-branch test added"}
+{"ts":"2026-07-08T14:11:30Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F3","severity":"Suggestion","source":"reviewer","file":"src/auth/session.ts:41","summary":"Extract shared cookie-parse helper","disposition":"surfaced","status":"never-attempted","closure_ref":null}
+{"ts":"2026-07-08T14:11:31Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"run-exit"}
+```
+
+## Pillar Service
+
+- P2 — findings become falsifiable disk records with evidence-bearing closure (`closure_ref` names a commit, quote, or anchor), and the fold answers "is anything open?" from disk rather than from memory.
+- P8 — `declined`/`accepted-risk` require quoted user attestation, and an open Critical/Warning forces an ASK — autonomy never absorbs a product decision silently.
+
+## References
+
+- Anthropic — Effective harnesses for long-running agents: durable file/JSON state over context; session-start re-read; session-end clean-state sweep. `anthropic.com/engineering/effective-harnesses-for-long-running-agents` (accessed 2026-07-08; T1, published 2025-11-26)
+- Anthropic — Harness design for long-running application development: success criteria written before implementation; files as the inter-agent channel. `anthropic.com/engineering/harness-design-long-running-apps` (accessed 2026-07-08; T1, published 2026-03-24)
+- OASIS — SARIF 2.1.0 Errata 01: `result.kind` open-by-default; `suppression.status: underReview` is never a final state. `docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html` (accessed 2026-07-08; T1, canonical spec, 2023-08-28)
+- DefectDojo — Finding status definitions: risk-accepted carries a revisit pointer; dispositions carry cross-round semantics. `docs.defectdojo.com/triage_findings/findings_workflows/finding_status_definitions/` (accessed 2026-07-08; T2, current)
+- Temporal — Event history / workflow execution: commands persisted before execution; a closed execution has exactly one terminal status. `docs.temporal.io/encyclopedia/event-history` (accessed 2026-07-08; T1, current)

package/dist/content/rules/hatch3r-findings-ledger.mdc

@@ -0,0 +1,129 @@
+---
+id: hatch3r-findings-ledger
+type: rule
+description: Write-ahead findings ledger — every review-loop finding is registered on disk before fix dispatch, folds to a terminal disposition at run exit, and survives interruption; no finding ends a run pending.
+tags: [orchestration, review, floor:protocol]
+precedence: high
+alwaysApply: true
+---
+# hatch3r Findings Ledger
+
+**Pillars:** P2 (Scientific & Practical Quality), P8 (Clarification & Fan-out Discipline)
+
+This rule closes one failure class: review-loop findings that are registered in chat but never implemented — Suggestions dropped on clean exits, findings lost at loop exhaustion, sub-agent death, or context compaction, and cross-iteration finding identity reduced to a bare unresolved-count. The fix is a write-ahead ledger: every finding is persisted to disk BEFORE the fixer that would address it is dispatched — the ordering Temporal applies to workflow commands (persisted before execution; `docs.temporal.io/encyclopedia/event-history`, accessed 2026-07-08) — and disk state, not chat context, is the recovery source after interruption (durable file/JSON state over context, per Anthropic's long-running-agent harness guidance; `anthropic.com/engineering/effective-harnesses-for-long-running-agents`, accessed 2026-07-08). At run exit every row folds to exactly one terminal disposition; no finding ends a run pending.
+
+## Store & Format
+
+One JSONL file per run: `.hatch3r/findings/<YYYY-MM-DD>-<command>-<run8>.jsonl`, where `<run8>` is the first 8 hex chars of the run's `correlation_id` (`rules/hatch3r-agent-orchestration.md` → Correlation ID) and `<command>` is the invoking command's short name — the `hatch3r-` prefix dropped (e.g. `workflow`, `pr-resolve`). Append-only; atomic append via the `src/merge/safeWrite.ts` pattern (temp+rename then concat) — the same convention as `.hatch3r/bypass-log.jsonl`.
+
+- **Full-row snapshots.** Every append is a complete row, never a partial patch. **Fold rule: last line per `finding_id` wins.** Any reader reconstructs current state by folding the file top to bottom.
+- **Closure marker.** A final marker row with `"finding_id":"run-exit"` closes a file. Closed = last line is `run-exit` AND the fold is all-terminal. The marker row carries `ts`, `run_id`, `command`, `iteration`, and `finding_id` only.
+- **Committed, not gitignored.** `.hatch3r/findings/` gets no gitignore entry — matching the `.hatch3r/review-findings/` + `todo.md` team-memory precedent — so open findings are visible in the PR diff. Degradation: in a repo with a blanket `.hatch3r/` ignore, interruption-proofing stays (same machine) but team visibility is lost.
+
+Row schema (JSON keys):
+
+| Key | Value |
+|---|---|
+| `ts` | ISO-8601 UTC append time |
+| `run_id` | `<run8>` |
+| `command` | the filename's `<command>` token |
+| `iteration` | review-loop iteration number at append time |
+| `finding_id` | `<run8>-F<seq>` — see Finding IDs |
+| `severity` | `Critical \| Warning \| Suggestion` |
+| `source` | `reviewer \| specialist \| edge-case-ledger \| pr-comment \| spec-review` |
+| `file` | `path:line`, or `issue#N` for board-scoped findings |
+| `summary` | ≤200 chars |
+| `disposition` | `registered` → `targeted \| deferred \| declined \| accepted-risk \| escalated \| already-resolved \| surfaced` |
+| `status` | `pending` → `in-fix` → `done \| failed \| never-attempted` |
+| `closure_ref` | commit SHA, fixer `Findings addressed` quote, todo.md anchor, quoted user reply ≤100 chars, or `review-findings/<id>` |
+
+`status: done` with `closure_ref: null` is ILLEGAL — closure always names its evidence.
+
+## Finding IDs
+
+`finding_id` = `<run8>-F<seq>`; the orchestrator assigns `<seq>` in registration order (F1, F2, …). The reviewer is stateless, so ID continuity is the orchestrator's job: it passes the prior iteration's findings table (`finding_id`, file, summary, status) in every re-review prompt. The reviewer's severity tables carry an `ID` column — reuse the supplied ID for a persisting finding; write `new` for a first appearance (the orchestrator assigns the next `F<seq>`) — plus a `Resolved since last iteration: <ids | none>` line below the tables. Identity heuristic when uncertain: same file + same defect class = same ID. This contract is mirrored in `agents/hatch3r-reviewer.md` → Finding IDs; keep the two aligned when either changes.
+
+## Write Points
+
+| Point | Trigger | Appends |
+|---|---|---|
+| **W1 write-ahead** | reviewer verdict parsed, BEFORE any fixer dispatch — every iteration | new Critical/Warning rows as `targeted`/`pending`; new Suggestions as `registered`/`pending`; one `registered`/`pending` Warning row per reviewer `deferred:` partial-review remainder (summary = the unreviewed item), so unreviewed surfaces survive the session |
+| **W2 per-iteration reconciliation** | after fixer return AND re-review | fixed-and-confirmed rows flip to `done` + `closure_ref`; attempted-but-still-failing rows to `failed`; rows the re-review reports resolved without this run's fix to `already-resolved` |
+| **W3 loop-exit reconciliation** | every exit path: clean, max-iterations, DESIGN_OBJECTION, user abort | resolve every non-terminal row to a legal terminal (Run-Exit Invariant), then append the `run-exit` marker row |
+| **W4 sub-agent-death flush** | the retry/BLOCKED_OTHER path of sub-agent-failure handling (`rules/hatch3r-agent-orchestration.md`) | flush in-flight rows — `in-fix` → `failed`, reason noted in `closure_ref` — before the retry and again before the ASK; a retry that lands re-flips the row at W2 (last line wins) |
+| **W5 Suggestion terminalization** | at W3 | every Suggestion row goes terminal — grammar in Suggestion Handling |
+
+At fixer dispatch the orchestrator appends each targeted row's `pending` → `in-fix` snapshot — the in-flight state W4 flushes. Run-start side task, with W1's first append: create `.hatch3r/findings/` when absent, then run the Hygiene prune.
+
+## Run-Exit Invariant
+
+After W3, zero rows fold to `status: pending` or `in-fix`, and zero rows fold to `disposition: registered`. Every folded row lands on one of the legal terminals:
+
+- (a) `targeted` + `done` + `closure_ref`
+- (b) `already-resolved`
+- (c) `deferred` — with a todo.md anchor in `closure_ref`
+- (d) `declined` or `accepted-risk` — user-attested only: each requires a quoted user reply in `closure_ref`; an autonomous run cannot produce them (`agents/shared/user-question-protocol.md` → Unattested product decision)
+- (e) `escalated` — with an open ASK recorded; legal only when the run's own status is not SUCCESS (unattended runs take this path and exit PARTIAL)
+- (f) `surfaced` — Suggestion severity only; the ID appears on the recap's `Open findings:` line
+
+A Critical/Warning finding that cannot reach (a)–(d) forces an ASK. Terminal `status` pairs mechanically with the outcome: `done` = this run's fix landed (`closure_ref` required); `failed` = attempted and not landed (never a resting terminal alone — the disposition must still reach (c)–(e)); `never-attempted` = closed without a fix attempt this run (`deferred`, `declined`, `accepted-risk`, `escalated`, `surfaced`, `already-resolved`).
+
+## Suggestion Handling
+
+Suggestions register once, at first appearance (W1, `registered`/`pending`); a reviewer repeating one in a later iteration causes no re-append — unless its severity changed, which appends a new full-row snapshot (same `finding_id`, new severity). At W3 every Suggestion row goes terminal (W5) via exactly one of:
+
+- `surfaced` — the ID is printed on the Iteration Summary's `Open findings:` line (`rules/hatch3r-iteration-summary.md` → Exception Lines). This is the never-silently-dropped guarantee: a clean exit still names every unaddressed Suggestion. Unattended default.
+- `deferred` — the user chose deferral; `closure_ref` = the todo.md anchor.
+- `declined` — the user declined; `closure_ref` = the quoted user reply (≤100 chars).
+
+## Session-Start Surfacing
+
+`agents/hatch3r-handoff-loader.md` owns this step. At session start the loader scans `.hatch3r/findings/*.jsonl` (skips silently when the directory is absent), skips closed files, folds each remaining file, and lists open rows — non-terminal rows plus rows terminal as `escalated`/`surfaced` — as `id · severity · file · summary · disposition`. A ledger file older than 14 days that still folds open rows is flagged stale, with three closure options: close as declined with reason "stale", re-defer to todo.md, or resume the work. This scan is the self-healing detector for runs that died before W3: whatever a crash left open re-surfaces next session instead of staying lost.
+
+## Handoff Integration
+
+No handoff-schema change. `agents/hatch3r-handoff-preparer.md` folds the active run's ledger in its collect-state step, and that fold is authoritative for the handoff's Work Remaining `Open findings` bullet at composition time — the handoff inherits open findings from the same fold every other consumer reads. The recap's `Open findings:` exception line (`rules/hatch3r-iteration-summary.md` → Exception Lines) is cross-check provenance, not the source: when it agrees with the fold the preparer copies it verbatim; when it is absent or disagrees (stale recap, mid-session interrupt) the fold wins and the bullet notes `(fold-derived; last recap stale or absent)`; zero open rows ⇒ no bullet. Composition procedure lives in `agents/hatch3r-handoff-preparer.md`, mirrored in `skills/hatch3r-handoff-prepare/SKILL.md` — keep the three aligned when any changes.
+
+## Store Boundaries
+
+Three stores, three jobs. Writes flow ledger-outward — the ledger is written first; the other stores derive from it, never the reverse.
+
+| Store | Role |
+|---|---|
+| `.hatch3r/findings/` (this ledger) | Execution-lifecycle write-ahead log. Run-scoped; carries ALL severities; the source of truth for "is anything open?" |
+| `.hatch3r/review-findings/` | Cross-PR reviewer memory of RESOLVED Critical/Warning findings. Its post-loop append DERIVES from the ledger fold — each entry cites its `finding_id` — never the reverse |
+| `todo.md` | Human follow-up backlog. A `deferred` row's `closure_ref` is the todo.md anchor; the todo bullet carries `[ledger: <finding_id>]`; after deferral the board owns the item (the ledger row is terminal) |
+
+## Hygiene
+
+- The owning orchestrator closes its own file at W3. A dead run's file is never closed by another run — the loader surfaces it (Session-Start Surfacing) for a user decision.
+- Prune at any run's W1: when more than 20 closed files exist, or any closed file is older than 30 days, delete the oldest closed files down to those bounds. Git history preserves pruned files; open files are never pruned.
+
+## Worked Example
+
+A 2-iteration `hatch3r-workflow` run (`run8` = `a3f81c2e`, file `.hatch3r/findings/2026-07-08-workflow-a3f81c2e.jsonl`): iteration 1 registers one Critical, one Warning, one Suggestion; the fixer takes the first two; iteration 2's re-review confirms both resolved; the Suggestion terminalizes as `surfaced`, so the recap prints `Open findings: a3f81c2e-F3 Suggestion — surfaced`.
+
+```jsonl
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:11Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F3","severity":"Suggestion","source":"reviewer","file":"src/auth/session.ts:41","summary":"Extract shared cookie-parse helper","disposition":"registered","status":"pending","closure_ref":null}
+{"ts":"2026-07-08T14:02:38Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"in-fix","closure_ref":null}
+{"ts":"2026-07-08T14:02:38Z","run_id":"a3f81c2e","command":"workflow","iteration":1,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"in-fix","closure_ref":null}
+{"ts":"2026-07-08T14:11:02Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F1","severity":"Critical","source":"reviewer","file":"src/auth/session.ts:88","summary":"Session token compared with non-constant-time equality","disposition":"targeted","status":"done","closure_ref":"fixer: Findings addressed — a3f81c2e-F1 timingSafeEqual"}
+{"ts":"2026-07-08T14:11:02Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F2","severity":"Warning","source":"reviewer","file":"src/auth/session.ts:97","summary":"New expiry branch has no test","disposition":"targeted","status":"done","closure_ref":"fixer: Findings addressed — a3f81c2e-F2 expiry-branch test added"}
+{"ts":"2026-07-08T14:11:30Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"a3f81c2e-F3","severity":"Suggestion","source":"reviewer","file":"src/auth/session.ts:41","summary":"Extract shared cookie-parse helper","disposition":"surfaced","status":"never-attempted","closure_ref":null}
+{"ts":"2026-07-08T14:11:31Z","run_id":"a3f81c2e","command":"workflow","iteration":2,"finding_id":"run-exit"}
+```
+
+## Pillar Service
+
+- P2 — findings become falsifiable disk records with evidence-bearing closure (`closure_ref` names a commit, quote, or anchor), and the fold answers "is anything open?" from disk rather than from memory.
+- P8 — `declined`/`accepted-risk` require quoted user attestation, and an open Critical/Warning forces an ASK — autonomy never absorbs a product decision silently.
+
+## References
+
+- Anthropic — Effective harnesses for long-running agents: durable file/JSON state over context; session-start re-read; session-end clean-state sweep. `anthropic.com/engineering/effective-harnesses-for-long-running-agents` (accessed 2026-07-08; T1, published 2025-11-26)
+- Anthropic — Harness design for long-running application development: success criteria written before implementation; files as the inter-agent channel. `anthropic.com/engineering/harness-design-long-running-apps` (accessed 2026-07-08; T1, published 2026-03-24)
+- OASIS — SARIF 2.1.0 Errata 01: `result.kind` open-by-default; `suppression.status: underReview` is never a final state. `docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html` (accessed 2026-07-08; T1, canonical spec, 2023-08-28)
+- DefectDojo — Finding status definitions: risk-accepted carries a revisit pointer; dispositions carry cross-round semantics. `docs.defectdojo.com/triage_findings/findings_workflows/finding_status_definitions/` (accessed 2026-07-08; T2, current)
+- Temporal — Event history / workflow execution: commands persisted before execution; a closed execution has exactly one terminal status. `docs.temporal.io/encyclopedia/event-history` (accessed 2026-07-08; T1, current)

package/dist/content/rules/hatch3r-handoff-readiness.md

@@ -50,6 +50,6 @@ Effect: self-assessed confidence becomes a track-record signal rather than a sin
 ## Cross-references
 
 - Body sections schema: `.hatch3r/handoffs/README.md`
-- Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
+- Iteration Summary recap contract (Work Done ← recap outcome + files facet; Work Remaining ← `Not done:` line, absent ⇒ `None — full scope completed`; Blockers ← `Blockers:` line, absent ⇒ `None`): `rules/hatch3r-iteration-summary.md`
 - Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
 - Quality charter (confidence levels): `agents/shared/quality-charter.md`

package/dist/content/rules/hatch3r-handoff-readiness.mdc

@@ -45,6 +45,6 @@ Effect: self-assessed confidence becomes a track-record signal rather than a sin
 ## Cross-references
 
 - Body sections schema: `.hatch3r/handoffs/README.md`
-- Iteration Summary contract (populates Work Done / Work Remaining / Blockers): `rules/hatch3r-iteration-summary.md`
+- Iteration Summary recap contract (Work Done ← recap outcome + files facet; Work Remaining ← `Not done:` line, absent ⇒ `None — full scope completed`; Blockers ← `Blockers:` line, absent ⇒ `None`): `rules/hatch3r-iteration-summary.md`
 - Injection-pattern catalog: `agents/shared/injection-patterns.md` Section B
 - Quality charter (confidence levels): `agents/shared/quality-charter.md`

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

@@ -27,6 +27,10 @@ cache_friendly: true
 - Never concatenate translated fragments to build sentences — each complete sentence is a single translation key.
 - Maintain a string extraction workflow (e.g., `i18next-parser`, `vue-i18n-extract`) that runs in CI to flag unused and missing keys.
 
+### Dynamic Keys
+
+String extraction cannot see interpolated keys (`t('status.' + value)`, template-literal keys). Every dynamic-key call site either (a) has a test iterating the full value set and asserting each resolved key exists in the default locale (`i18n.te(key)` or equivalent), or (b) carries a co-located comment enumerating the concrete keys for the parser. CI extraction reports count dynamic call sites as unverified, never as passing. Verification pattern owner: `rules/hatch3r-dynamic-stack-verification.md` → Dynamic i18n Keys.
+
 ## RTL Support
 
 - Use CSS logical properties exclusively: `margin-inline-start` (not `margin-left`), `padding-inline-end` (not `padding-right`), `inset-inline-start` (not `left`), `text-align: start` (not `text-align: left`).

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

@@ -22,6 +22,10 @@ alwaysApply: false
 - Never concatenate translated fragments to build sentences — each complete sentence is a single translation key.
 - Maintain a string extraction workflow (e.g., `i18next-parser`, `vue-i18n-extract`) that runs in CI to flag unused and missing keys.
 
+### Dynamic Keys
+
+String extraction cannot see interpolated keys (`t('status.' + value)`, template-literal keys). Every dynamic-key call site either (a) has a test iterating the full value set and asserting each resolved key exists in the default locale (`i18n.te(key)` or equivalent), or (b) carries a co-located comment enumerating the concrete keys for the parser. CI extraction reports count dynamic call sites as unverified, never as passing. Verification pattern owner: `rules/hatch3r-dynamic-stack-verification.md` → Dynamic i18n Keys.
+
 ## RTL Support
 
 - Use CSS logical properties exclusively: `margin-inline-start` (not `margin-left`), `padding-inline-end` (not `padding-right`), `inset-inline-start` (not `left`), `text-align: start` (not `text-align: left`).