@sabaiway/agent-workflow-kit 1.36.0 → 1.37.1

package/CHANGELOG.md

@@ -4,6 +4,59 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.37.1 — Fix: the fold-completeness probe on Node 18/20 counted pattern-filtered SKIP lines as executed tests
+
+A **patch** release (one product fix + its pinned fixtures; no other change). On Node 18/20 —
+versions the kit supports — `node --test --test-name-pattern` EMITS every non-matching test as
+`ok N - <name> # SKIP test name does not match pattern` (newer Node omits them), so the 1.37.0
+probe parser counted those lines as real matches: a `testId` whose pattern matches NOTHING was
+reported **resolvable with a green baseline**, and the fold-completeness gate green-vouched a test
+that never ran — defeating the gate's purpose on exactly those Node versions. Caught by the CI
+matrix (node 18 + 20) on the 1.37.0 release commit; invisible on newer local Node.
+
+- `parseProbeOutput` now ignores any TAP result line carrying a **SKIP/TODO directive** — a skipped
+  test was not executed, on any Node version; a real test name containing a literal `# skip` would
+  only fail CLOSED (unresolvable), never open.
+- New pinned fixtures: the node-18/20 pattern-filter TAP shape (nomatch → unresolvable; a matched
+  test among skipped ones still resolves), a lowercase `# skip`, and a `# TODO` directive.
+
+## 1.37.0 — Fold-safety completion: a fixable-bug requires its test, and a coverage gate attests the fold against the changed code (AD-046)
+
+A **feature** release (deployment-lineage head stays `1.3.0` — no migration). AD-045's ledger computed
+WHEN a review loop stops; this release mechanizes **"a fold carries no new bug"** — M2 + M3a of
+DEBT-TEST-COMPLETENESS. **No mutation testing ships** — that half was researched and shelved (see the
+honest-limits note below).
+
+- **M2 — testId enforcement (ledger schema v2).** A `fixable-bug` triage classification now REQUIRES a
+  `testId` (`<test-file>#<test-name-pattern>` — a `#` separator with both halves non-empty; the writer
+  validates FORMAT only, staying hermetic). Schema 1→2 with per-version validation: historical v1
+  records stay valid on read, a mixed ledger reads back clean; the writer emits v2 only; `decideStop`
+  is untouched.
+- **M3a — the fold-completeness tool pair (read/run split, mirroring the ledger's read/write split).**
+  `tools/fold-completeness-run.mjs` — the SOLE tree-toucher + result writer: ONE suite run under
+  `NODE_V8_COVERAGE` (the coverage dir lives OUTSIDE the work tree), the changed surface classified by
+  a CLOSED extension rule (assessable JS · unsupported TS/JSX fails the gate closed · out-of-domain
+  docs/config listed loudly, never blocking), every bound testId probed shell-free for resolvability +
+  a GREEN baseline, and ONE machine-only record bound to BOTH the tree fingerprint AND the sorted
+  fixable-bug testId set — either moving makes the record stale. `tools/fold-completeness.mjs` — the
+  read-only `--status` / `--check` gate (fail-closed; the normative exit contract lives in its header,
+  the single home) that never imports the runner (import-split test).
+- **Command surface** — the `fold-completeness` catalog entry (a writer) + `### Mode: fold-completeness`
+  + its mode reference. **Consumer seeding is deliberately ON HOLD**: the signal is JS/V8-only in v1,
+  so the consent-gated seeder does not offer this gate yet — wire it by hand (the mode-ref carries the
+  candidate `gates.json` line and the hold's reason).
+- **Activity-aware canon pointer (with engine 1.14.0)** — the procedures advisor renders the ledger
+  pointer (record / `--status` / `--check`) for `plan-execution` ONLY, plus an unconditional
+  triage-classification bullet (`fixable-bug / inherent-layer-residual / escalate`) for every
+  review-backed activity.
+- **Honest limits (stated in the tool headers, like `review-state`'s):** coverage proves EXECUTION, not
+  assertion — the per-fold proof remains the red→green test discipline (M2), the coverage run is the
+  whole-surface prefilter; records/testIds are forgeable (a self-discipline mechanism, not a security
+  boundary); line-entry granularity (same-line branch gaps are out of scope without an AST).
+  **Mutation (M3b) was researched and SHELVED** — bounded local-boundary mutation did not catch the
+  motivating interaction bug and is not language-independent; records carry a reserved EMPTY `mutation`
+  shape and the checker fails CLOSED on any record carrying mutation data.
+
 ## 1.36.0 — Review-round ledger: the prose crossover-stop becomes a computed signal (AD-045)
 
 A **feature** release (deployment-lineage head stays `1.3.0` — no migration). The review-loop

package/README.md

@@ -236,6 +236,8 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
 | `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit review-ledger` | any time | **review-round ledger** — turns the review-loop stop rule into a **computed** signal: record each plan-execution review round + its triage into a JSONL ledger inside the git dir (never committable), and read the stop decision (`converged > resolved-residual > triage-required > continue`) from the records — never from a remembered rule. `--status` replaces the hand-composed per-round tally; `--check` is a fail-closed gate exit code for `docs/ai/gates.json` (by hand or via the consent-gated seeder). A `fixable-bug` triage **requires its red→green `testId`** (schema v2; older records stay valid on read). The writer refuses a round past the hard-max, while a triage is pending, or without a grounded review receipt. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit fold-completeness` | any time | **fold-completeness gate** — attests the review loop's folded fixes against the changed code: the runner executes your suite ONCE under `NODE_V8_COVERAGE`, checks every changed executable line is **executed** and every bound `testId` resolves + starts GREEN, and appends one result record bound to BOTH the tree fingerprint AND the sorted testId set (either moving stales it — re-run after the last edit); the separate read-only checker (`--status` / `--check`) turns the record into a fail-closed gate. Honest residuals: coverage proves **execution, not assertion** (the per-fold proof stays the red→green `testId` discipline), and records are forgeable — self-discipline, not a security boundary. v1 scope is JS/V8: changed TS/JSX fails closed, docs/config changes are listed but never block, and **no mutation testing ships**. Wire the gate by hand — the consent-gated seeder deliberately does not offer it yet (JS-only hold). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.36.0'
+  version: '1.37.1'
 ---
 
 # agent-workflow-kit
@@ -81,7 +81,7 @@ Before acting, read `docs/ai/.workflow-version` (the project's stamp) to decide
 1. **Project deployment** — `docs/ai/.workflow-version` vs the lineage head (`1.3.0`). This is the **only** axis this skill compares.
 2. **Kit freshness** — this skill's own files vs the published npm package. That is the **npx installer's** job: `npx @sabaiway/agent-workflow-kit@latest init` (it refuses a stale-cache downgrade by comparing the version on disk — **no network**). This skill never checks npm, and the package version is **not** the lineage head.
 
-**Refreshed the kit but nothing changed?** The skill you are running is whatever was on disk when the session started. After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files (the slash command + this `SKILL.md`).
+**Refreshed the kit but nothing changed?** After `npx @sabaiway/agent-workflow-kit@latest init` updates `~/.claude/skills/agent-workflow-kit/`, **restart the session** so the agent reloads the new skill files.
 
 ### Mode: help
 
@@ -159,11 +159,15 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/grounding.md` before actin
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/review-ledger.md` before acting.
 
+### Mode: fold-completeness
+
+writer — read `${CLAUDE_SKILL_DIR}/references/modes/fold-completeness.md` before acting.
+
 ---
 
 ## References
 
-- [`references/modes/`](${CLAUDE_SKILL_DIR}/references/modes/) — one file per mode (the router lines above point here); [`references/shared/`](${CLAUDE_SKILL_DIR}/references/shared/) — the shared point-of-use contracts (report footer · composition hand-off · deploy tail).
+- [`references/modes/`](${CLAUDE_SKILL_DIR}/references/modes/) — one file per mode; [`references/shared/`](${CLAUDE_SKILL_DIR}/references/shared/) — the shared point-of-use contracts (report footer · composition hand-off · deploy tail).
 - [`references/contracts.md`](${CLAUDE_SKILL_DIR}/references/contracts.md) — the three setup contracts.
 - [`references/templates/`](${CLAUDE_SKILL_DIR}/references/templates/) — the `AGENTS.md` + `docs/ai/` templates + seeded configs; [`references/scripts/`](${CLAUDE_SKILL_DIR}/references/scripts/) — the Node enforcement scripts; [`migrations/`](${CLAUDE_SKILL_DIR}/migrations/) — per-version upgrade steps; [`launchers/`](${CLAUDE_SKILL_DIR}/launchers/) — non-Claude agent launchers.
 - [`tools/`](${CLAUDE_SKILL_DIR}/tools/) — the family-wide tooling; each tool's contract lives with its mode file and its own header; bridge mirrors under [`bridges/`](${CLAUDE_SKILL_DIR}/bridges/).

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.36.0",
+  "version": "1.37.1",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.36.0",
+  "version": "1.37.1",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/fold-completeness.md

@@ -0,0 +1,22 @@
+### Mode: fold-completeness
+
+The FOLD-COMPLETENESS gate (M3a / AD-046, DEBT-TEST-COMPLETENESS) — the sibling of the review-round ledger: the ledger computes WHEN the plan-execution review loop stops; this tool pair verifies that the tests the loop's folds bind to ACTUALLY pin the changed code. One recorded coverage run proves (a) every changed executable line is executed by the suite and (b) every `fixable-bug` bound testId resolves and starts GREEN; a read-only checker turns the recorded result into a gate exit code.
+
+**Two tools — the read/run split:**
+
+1. **Runner** — `node ${CLAUDE_SKILL_DIR}/tools/fold-completeness-run.mjs [--suite "<cmd>"] [--cwd <dir>]` — the SOLE tree-toucher and the SOLE result writer. One run over the in-flight plan-execution loop's dirty tree: resolve the loop (the single in-flight plan stem — 0 or >1 plans is a typed refusal), classify the changed surface by a CLOSED extension rule (assessable JS / unsupported TS-JSX / out-of-domain), run the suite ONCE under `NODE_V8_COVERAGE` (the coverage dir lives OUTSIDE the work tree — no repo artifacts), map every changed executable line to covered/uncovered from the V8 report itself, probe each bound testId once (shell-free spawn) for resolvability + a green baseline, and append ONE machine-only record — bound to BOTH the tree fingerprint AND the sorted `fixable-bug` testId set — to `<git dir>/agent-workflow-fold-completeness.jsonl` (never committable by construction; `AW_FOLD_RESULTS` overrides).
+2. **Read-only checker** — `node ${CLAUDE_SKILL_DIR}/tools/fold-completeness.mjs [--check | --status | --json]` — never runs tests, never touches the tree, never imports the runner (an import-split test pins the structural split). `--status` (default) is the human report; **`--check` is the gate exit code — the normative exit contract lives in the CHECKER's tool header (the single home — do not re-enumerate it elsewhere)**; `--json` is the structured state + decision.
+
+**Wire the gate BY HAND, once, BEFORE the round's runner run.** The candidate line for your own `docs/ai/gates.json`: `{ "id": "fold-completeness", "title": "Fold-completeness — every changed executable line executed by tests (M3a)", "cmd": "node \"<path-to-this-skill>/tools/fold-completeness.mjs\" --check" }` — the path your project reaches the kit by, kept inside the escaped quotes so a path with spaces survives. Wiring comes FIRST because where `docs/ai` is tracked, the gate-file edit itself moves the tree fingerprint — wiring after a run stales the record you just wrote. The consent-gated seeder does NOT offer this entry yet — a deliberate v1 hold: the signal is JS/V8-only, and offering it to a project whose source the runner cannot assess would seed a gate that can only fail closed; seeder offering arrives with a language-aware verification profile.
+
+**Run-then-check usage (each plan-execution round):** run the runner AFTER the round's LAST edit — any later tree edit (a source fix, a doc touch, a gate-file tweak) moves the fingerprint and requires a re-run — then the wired `--check` attests it. Staleness is by BOTH bindings: a tree edit moves the fingerprint, and a new `fixable-bug` triage moves the bound-testId set — either makes the previous record STALE, so a green check always attests the CURRENT tree against the CURRENT fold set.
+
+**Suite + bound-test commands:** the suite command defaults to the `unit-tests` gate `cmd` in the project's `docs/ai/gates.json`; absent that, `--suite "<cmd>"` (or `AW_FOLD_SUITE_CMD`) is REQUIRED — refused loudly otherwise. Bound-test probes default to the `node --test --test-name-pattern` shape over the testId halves (`<test-file>#<test-name-pattern>`); a consumer on another runner sets `AW_FOLD_BOUND_CMD` — a JSON ARRAY of argv strings with `{file}` / `{pattern}` placeholder substitution, spawned WITHOUT a shell (testId content never reaches a shell). Note: the suite's own child processes must inherit `NODE_V8_COVERAGE` for their lines to count (node child spawns inherit it by default; a test runner that scrubs its child env needs consumer configuration).
+
+**v1 scope (stated):** assessable = `.mjs` / `.cjs` / `.js`, excluding test files (`*.test.*` / `*.spec.*`); changed `.ts` / `.tsx` / `.jsx` / `.mts` / `.cts` files are recorded as unsupported and FAIL the gate CLOSED — the signal never vouches for JS-family source it cannot assess; everything else (docs/config the suite does not execute) is recorded out-of-domain and LOUDLY listed, never gate-blocking. Executability is V8-derived: a changed assessable file entirely absent from the coverage report is RED at file level ("never imported" must not read as "nothing executable").
+
+**Mutation is NOT shipped (v1).** The result record carries a reserved, always-empty `mutation` shape; the shipped runner performs NO mutation and never modifies a source file, and the checker FAILS CLOSED on a record carrying ANY mutation data (such a record was not produced by this runner version). The researched mutation half was shelved: a bounded operator set tests local expression boundaries, not the cross-module interactions that produce real fold bugs, and it is not language-independent. The `AW_FOLD_MUTANTS_MAX` / `AW_FOLD_HUNK_MUTANTS_MAX` / `AW_FOLD_TIME_BUDGET_S` budgets are parsed and recorded but inert in v1 (reserved).
+
+**Honest residuals (stated, accepted — exactly like review-state's / review-ledger's):** coverage proves EXECUTION, not assertion — an executed-but-unasserted line still reads covered; the per-fold proof remains the M2 discipline (a `fixable-bug` testId written red→green, probed green here), the coverage run is the whole-surface prefilter; the result records, testIds, and ledgers are forgeable (`git commit --no-verify`, file editing) — a self-discipline mechanism against silent process drift, NOT a security boundary.
+
+**Invariants:** the checker is read-only · never commits · never runs a subscription CLI · spawns read-only `git` queries only · the SOLE tree-toucher + result writer is `fold-completeness-run.mjs`, which the checker NEVER imports (read/run split, import-split test) · the runner's only writes land OUTSIDE the work tree (the coverage temp dir + the git-dir result ledger) — the tree fingerprint is byte-identical before and after a run.

package/references/modes/review-ledger.md

@@ -11,7 +11,7 @@ The review-round **LEDGER** (DEBT-REVIEW-CAP / AD-045) — it turns the prose re
 
 2. **Writer** — `node ${CLAUDE_SKILL_DIR}/tools/review-ledger-write.mjs record|classify --json '<payload>'` (the SOLE writer, over the shared `atomic-write` core):
    - `record` appends one round — `{ loop, round, origins, backends, findings }` (activity defaults to `plan-execution`). **The teeth (Decision 5):** it REFUSES (typed STOP) to append a round WHILE `decideStop` on the existing records is `triage-required` (an UNCLASSIFIED surviving blocking finding at/after the cap), and refuses ANY round beyond the **hard-max ceiling of 3** unconditionally. **Integrity binding (Decision 7):** each NON-degraded backend needs a grounded **code** receipt (from `codex-review code` / `agy-review code --facts @f`) for the current tree — a round cannot be recorded for a tree no bridge reviewed.
-   - `classify` appends one triage — each surviving blocking finding classified `fixable-bug` / `inherent-layer-residual` / `escalate`. **This is what BREAKS the deadlock:** once every surviving blocking finding is classified, `record` permits the next round (a `fixable-bug` classification lets the fix round run — no deadlock).
+   - `classify` appends one triage — each surviving blocking finding classified `fixable-bug` / `inherent-layer-residual` / `escalate`. **A `fixable-bug` REQUIRES a `testId`** (M2/AD-046, schema v2) — the red→green test that pins the fold, formatted `<test-file>#<test-name-pattern>` (a `#` separator, both halves non-empty; no file-suffix rule); `inherent-layer-residual` / `escalate` may omit it. The writer validates the FORMAT only. **This is what BREAKS the deadlock:** once every surviving blocking finding is classified, `record` permits the next round (a `fixable-bug` classification lets the fix round run — no deadlock).
 
 **The computed stop (`decideStop`, precedence `converged > resolved-residual > triage-required > continue`).** Machine fields only (counts, `class`, `accepted`, `fingerprint`), never free-text:
 - **converged** — every recipe-named backend present, **non-degraded, at 0 blockers + 0 majors** in the latest round, at the current tree fingerprint. **"Surviving blocking finding" = a blocker OR a major** (a minor never forces triage).

package/tools/commands.mjs

@@ -182,6 +182,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Record each review round and read the computed crossover-stop for the plan-execution loop (converged / accepted-residual / triage-required); --check turns it into a gate exit code and forces a triage before over-running the review.',
   },
+  {
+    key: 'fold-completeness',
+    invocation: invocationOf('fold-completeness'),
+    group: 'Orchestrate',
+    kind: WRITER,
+    oneLine: 'Verify the review loop’s folded fixes are pinned by tests — one recorded coverage run proves every changed executable line is executed and each bound test starts green; --check turns the result into a gate exit code.',
+  },
 ];
 
 // Deep-freeze: freeze the array AND every entry, so the catalog is genuinely immutable at runtime

package/tools/fold-completeness-run.mjs

@@ -0,0 +1,531 @@
+#!/usr/bin/env node
+// fold-completeness-run.mjs — the M3 fold-completeness RUNNER (AD-046, DEBT-TEST-COMPLETENESS). It is
+// the SOLE tree-toucher and the SOLE writer of the fold-completeness result ledger, the write half of
+// the family read/write split (mirrors review-ledger-write.mjs): fold-completeness.mjs (the schema +
+// result reader + the read-only `--check` gate) NEVER imports this module — an import-split test pins
+// that. This module imports the read core the OTHER direction (the result schema + reader + the shared
+// bound-testId collector) and appends records through the shared hardened atomic-write core.
+//
+// One run, over the in-flight plan-execution loop's dirty tree:
+//   1. resolve the loop = the single in-flight plan stem (0 or >1 → typed refusal);
+//   2. classify the changed surface (Decision 5, a CLOSED extension rule — assessable JS / unsupported
+//      TS-JSX / out-of-domain) and derive per-file changed line ranges;
+//   3. M3a — run the suite ONCE under NODE_V8_COVERAGE (a dir OUTSIDE the work tree, Decision 8) and
+//      map every changed executable line to covered/uncovered via V8 innermost-range-wins (Decision 6);
+//   4. probe each of the loop's fixable-bug bound testIds once (Decision 3 / 10, shell-free) for
+//      resolvability + a green baseline;
+//   5. append ONE machine-only result record, bound to BOTH the tree fingerprint AND the sorted
+//      fixable-bug testId set (Decision 9), to <git dir>/agent-workflow-fold-completeness.jsonl.
+// The researched mutation half (M3b) was SHELVED — bounded local-boundary mutation adds too little
+// over coverage and is not language-independent — so the `mutation` field stays the reserved empty shape.
+//
+// HONEST residuals (see fold-completeness.mjs header for the full list): coverage proves execution not
+// assertion; testIds/records are forgeable (a self-discipline mechanism, not a security boundary);
+// TS/JSX source is out of scope v1. Dependency-free, Node >= 18. No side effects on import.
+
+import { readFileSync, readdirSync, mkdtempSync, rmSync, realpathSync, lstatSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { tmpdir } from 'node:os';
+import { pathToFileURL, fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
+import { computeTreeFingerprint, plansInFlight } from './review-state.mjs';
+import { resolveLedgerPath, readLedger } from './review-ledger.mjs';
+import {
+  RESULT_SCHEMA_VERSION,
+  resolveResultsPath,
+  validateRunRecord,
+  collectBoundTestIds,
+} from './fold-completeness.mjs';
+
+const ACTIVITY = 'plan-execution';
+const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff / full-suite TAP can be large; never truncate
+
+// A typed STOP — a deliberate refusal we surface (loop derivation / a malformed override / a malformed
+// record / an fs error), distinct from a native fs error. The codebase's typed-error idiom (no classes).
+export const FOLD_RUN_STOP = 'FOLD_RUN_STOP';
+const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'FoldRunStop', code: FOLD_RUN_STOP });
+const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
+
+const isoNow = () => new Date().toISOString();
+
+// Node sets NODE_TEST_CONTEXT for any process running UNDER `node --test`; a fresh `node --test` that
+// inherits it silently SKIPS running its files (the recursive-run guard). The runner spawns `node
+// --test` for the suite + the bound-test probes, so it MUST strip that var — otherwise, whenever the
+// runner is itself invoked from within a test context (e.g. this kit's own fold-completeness-run
+// tests, or a consumer's), the child runs nothing and every file reads as uncovered. Unset in normal
+// (non-test) invocation, so stripping is a no-op there.
+const childTestEnv = (env, extra = {}) => {
+  const out = { ...env, ...extra };
+  delete out.NODE_TEST_CONTEXT;
+  return out;
+};
+
+// ── Decision 5: the CLOSED changed-path classification rule (no heuristics) ───────────────────────
+
+const TEST_FILE_RE = /\.(test|spec)\.[^./]+$/; // a.test.mjs, b.spec.js, c.test.cjs, d.spec.ts
+const ASSESSABLE_EXT = new Set(['.mjs', '.cjs', '.js']);
+const UNSUPPORTED_EXT = new Set(['.ts', '.tsx', '.jsx', '.mts', '.cts']);
+
+// classifyChangedPath(rel) → 'assessable' | 'unsupported' | 'out-of-domain' | 'excluded-test'.
+export const classifyChangedPath = (rel) => {
+  const base = rel.split('/').pop();
+  if (TEST_FILE_RE.test(base)) return 'excluded-test';
+  const dot = base.lastIndexOf('.');
+  const ext = dot >= 0 ? base.slice(dot) : '';
+  if (ASSESSABLE_EXT.has(ext)) return 'assessable';
+  if (UNSUPPORTED_EXT.has(ext)) return 'unsupported';
+  return 'out-of-domain';
+};
+
+// ── unified-diff → new-side changed line numbers (line numbers only; content lines are ignored) ───
+
+const DIFF_HUNK_RE = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/;
+
+// parseUnifiedDiff(diffText) → Map<rel, number[]>. Robust against a content line that happens to look
+// like a `+++ ` header: a `+++ ` line is a FILE header only in the header region (right after a
+// `diff --git`, before any `@@`); inside a hunk body it is ignored. New-side lines come purely from the
+// `@@` headers, so no content-line disambiguation is needed for the line numbers themselves.
+export const parseUnifiedDiff = (diffText) => {
+  const map = new Map();
+  let current = null;
+  let inHeader = false;
+  for (const line of String(diffText).split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      current = null;
+      inHeader = true;
+      continue;
+    }
+    if (inHeader && line.startsWith('--- ')) continue;
+    if (inHeader && line.startsWith('+++ ')) {
+      const p = line.slice(4).trim();
+      current = p === '/dev/null' ? null : p.startsWith('b/') ? p.slice(2) : p;
+      inHeader = false;
+      continue;
+    }
+    const m = DIFF_HUNK_RE.exec(line);
+    if (m) {
+      inHeader = false;
+      if (current == null) continue;
+      const start = Number(m[1]);
+      const count = m[2] === undefined ? 1 : Number(m[2]);
+      if (count > 0) {
+        const arr = map.get(current) ?? [];
+        for (let i = 0; i < count; i += 1) arr.push(start + i);
+        map.set(current, arr);
+      }
+    }
+  }
+  for (const [k, v] of map) map.set(k, [...new Set(v)].sort((a, b) => a - b));
+  return map;
+};
+
+// ── Decision 6: V8 coverage → uncovered changed lines (innermost-range-wins) ──────────────────────
+
+// lineStartOffsets(sourceText) → char offset of each line start (index i == line i+1). Splitting on
+// '\n' keeps any trailing '\r' inside the line length, so CRLF offsets stay correct.
+export const lineStartOffsets = (sourceText) => {
+  const offs = [0];
+  for (let i = 0; i < sourceText.length; i += 1) if (sourceText[i] === '\n') offs.push(i + 1);
+  return offs;
+};
+
+// effectiveCount(ranges, offset) → the execution count of the SMALLEST (innermost) range containing
+// offset; 0 when no range contains it (absent from this process's report). This is the v8-to-istanbul
+// rule reduced to Node built-ins: a nested count-0 block shadows its executed parent.
+export const effectiveCount = (ranges, offset) => {
+  let best = null;
+  for (const r of ranges) {
+    if (r.startOffset <= offset && offset < r.endOffset) {
+      const width = r.endOffset - r.startOffset;
+      if (best === null || width < best.width) best = { width, count: r.count };
+    }
+  }
+  return best === null ? 0 : best.count;
+};
+
+// computeUncoveredLines({ perProcessRanges, sourceText, changedLines }) → the sorted changed lines that
+// NO process executed. perProcessRanges is one flat range-list per process (process isolation); a line
+// is covered iff ANY process gives its first non-whitespace char a positive effective count. Blank /
+// whitespace-only lines are never executable and never flagged. Callers handle file-absent (an empty
+// perProcessRanges means the file never loaded — a file-level RED decided by the caller, not here).
+//
+// GRANULARITY (stated residual, codex R1 → inherent-layer-residual): this is LINE-ENTRY coverage — the
+// question "was this line entered by some test?", the same granularity c8 reports as line coverage. A
+// same-line uncovered sub-branch (the false arm of `a ? b : c`, the RHS of `a && b()`) is NOT flagged
+// when the line's leading statement executed — flagging it would need branch/AST analysis, and a naive
+// "any count-0 char on the line" rule would FALSE-POSITIVE on an inline uncalled-function definition
+// (`const f = () => never()`, whose body span is count-0 though the assignment ran), i.e. exactly the
+// churn the plan's PRIMARY RISK warns against. Same-line branch gaps would need branch-level analysis
+// (the shelved mutation half / a future parser-backed signal), not M3a line coverage. Chasing sub-line
+// precision here without an AST is explicitly out of scope — a stated residual.
+export const computeUncoveredLines = ({ perProcessRanges, sourceText, changedLines }) => {
+  const offs = lineStartOffsets(sourceText);
+  const total = sourceText.length;
+  const uncovered = [];
+  for (const n of changedLines) {
+    const start = offs[n - 1];
+    if (start === undefined) continue; // a changed line beyond EOF (defensive; should not happen)
+    const end = offs[n] ?? total;
+    const rel = sourceText.slice(start, end).search(/\S/);
+    if (rel < 0) continue; // blank / whitespace-only → not executable
+    const offset = start + rel;
+    const covered = perProcessRanges.some((ranges) => effectiveCount(ranges, offset) > 0);
+    if (!covered) uncovered.push(n);
+  }
+  return [...new Set(uncovered)].sort((a, b) => a - b);
+};
+
+// ── Decision 3 / 10: the bound-test probe ─────────────────────────────────────────────────────────
+
+const PROBE_RESULT_RE = /^(?:ok|not ok) \d+ - (.*)$/; // a column-0 TAP result line
+const PROBE_FAIL_RE = /^# fail (\d+)$/;
+const PROBE_DIRECTIVE_RE = /#\s*(?:skip|todo)\b/i; // a TAP SKIP/TODO directive — the test did NOT run
+
+// parseProbeOutput({ stdout, code, fileArg }) → { resolvable, executed, baselineGreen }. A node:test
+// run with a pattern that matches NOTHING emits only a file-wrapper result whose description is the
+// file path itself (`ok N - <file>`) on newer node — but node 18/20 ALSO emit every pattern-FILTERED
+// test as `ok N - <name> # SKIP test name does not match pattern`, so a result line carrying a TAP
+// SKIP/TODO directive must never count: the test was not executed, and counting it green-vouches a
+// nonexistent testId on exactly the node versions the kit supports (caught by CI's 18/20 matrix).
+// So `resolvable` = at least one column-0, directive-free result whose description is not the file we
+// passed; `baselineGreen` = resolvable AND the run was green (exit 0 and `# fail 0`). The wrapper is
+// matched by BASENAME, not literally: node normalizes the echoed path ('./x' → 'x', or an absolute
+// path), so a literal desc===fileArg compare would count the wrapper as a real match and falsely
+// report resolvable/green (codex R1). A basename compare is invariant to ./ / abs / rel; a real test
+// name colliding with the file's basename — or containing a literal "# skip" — is absurd and would
+// only fail CLOSED (mark unresolvable), never open.
+export const parseProbeOutput = ({ stdout, code, fileArg }) => {
+  let matched = 0;
+  let failCount = null;
+  const wanted = basename(String(fileArg).trim());
+  for (const line of String(stdout).split('\n')) {
+    const m = PROBE_RESULT_RE.exec(line);
+    if (m && !PROBE_DIRECTIVE_RE.test(m[1]) && basename(m[1].trim()) !== wanted) matched += 1;
+    const f = PROBE_FAIL_RE.exec(line.trim());
+    if (f) failCount = Number(f[1]);
+  }
+  const resolvable = matched > 0;
+  const fails = failCount ?? (code === 0 ? 0 : 1);
+  return { resolvable, executed: matched, baselineGreen: resolvable && code === 0 && fails === 0 };
+};
+
+// defaultBoundArgv(file, pattern) → the shell-free node:test argv (testId content never reaches a shell).
+export const defaultBoundArgv = (file, pattern) => ['node', '--test', '--test-reporter', 'tap', '--test-name-pattern', pattern, file];
+
+// resolveBoundArgv(env) → (file, pattern) => argv[]. Default = the node:test shape; AW_FOLD_BOUND_CMD
+// overrides with a JSON array of argv strings using {file}/{pattern} placeholders (the universality
+// escape hatch — a consumer on another runner). A malformed override is a typed refusal, never a
+// silent fallback to a shell. Substitution uses function replacers so a `$` in a testId is literal.
+export const resolveBoundArgv = (env = process.env) => {
+  const raw = env.AW_FOLD_BOUND_CMD;
+  if (!raw) return (file, pattern) => defaultBoundArgv(file, pattern);
+  let tmpl;
+  try {
+    tmpl = JSON.parse(raw);
+  } catch (err) {
+    throw stop(`AW_FOLD_BOUND_CMD is not valid JSON (${err.message}) — expected a JSON array of argv strings`);
+  }
+  if (!Array.isArray(tmpl) || tmpl.length === 0 || !tmpl.every((a) => typeof a === 'string')) {
+    throw stop('AW_FOLD_BOUND_CMD must be a non-empty JSON array of argv strings with {file}/{pattern} placeholders');
+  }
+  return (file, pattern) => tmpl.map((a) => a.replace(/\{file\}/g, () => file).replace(/\{pattern\}/g, () => pattern));
+};
+
+// ── the changed surface (git-driven) ──────────────────────────────────────────────────────────────
+
+const runGit = (args, cwd) => spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, encoding: 'utf8', windowsHide: true });
+const gitStdout = (args, cwd) => {
+  const r = runGit(args, cwd);
+  return r.error || r.status > 1 ? null : r.stdout;
+};
+const readFileSafe = (path) => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+const canon = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+};
+// A changed assessable LEAF is assessed only if it is a REGULAR file. lstat (no-follow): a symlinked
+// or non-regular *.mjs must NEVER be read/canonicalized — following it could read outside the work
+// tree or HANG on a FIFO/device (codex R2). A non-regular leaf fails closed (routed to `unsupported`).
+const isRegularLeaf = (abs) => {
+  try {
+    return lstatSync(abs).isFile();
+  } catch {
+    return false;
+  }
+};
+
+// computeChangedSurface(root) → { assessable: Map<rel, number[]>, unsupported: [rel], outOfDomain: [rel] }.
+// Domain = the review-payload domain (tracked working-vs-HEAD changes + untracked-not-ignored files),
+// classified by the CLOSED rule. Tracked changed lines come from `git diff HEAD -U0`; an untracked file
+// is wholly new, so all its lines are "changed".
+export const computeChangedSurface = (root) => {
+  const trackedDiff = gitStdout(['diff', 'HEAD', '--unified=0', '--no-color', '--no-ext-diff', '--no-renames'], root)
+    ?? gitStdout(['diff', '--unified=0', '--no-color', '--no-ext-diff', '--no-renames'], root) // no HEAD yet (unborn branch)
+    ?? '';
+  const trackedLines = parseUnifiedDiff(trackedDiff);
+  const untrackedZ = gitStdout(['ls-files', '--others', '--exclude-standard', '-z'], root) ?? '';
+  const untracked = untrackedZ.split('\0').filter(Boolean);
+
+  const assessable = new Map();
+  const unsupported = [];
+  const outOfDomain = [];
+  const place = (rel, cls, lines) => {
+    if (cls === 'excluded-test') return;
+    if (cls === 'assessable') {
+      if (isRegularLeaf(join(root, rel))) assessable.set(rel, lines);
+      else unsupported.push(rel); // a symlinked / non-regular source → fail closed, never followed
+      return;
+    }
+    if (cls === 'unsupported') unsupported.push(rel);
+    else outOfDomain.push(rel);
+  };
+  for (const [rel, lines] of trackedLines) place(rel, classifyChangedPath(rel), lines);
+  for (const rel of untracked) {
+    const cls = classifyChangedPath(rel);
+    if (cls !== 'assessable') {
+      place(rel, cls, []);
+      continue;
+    }
+    // Guard the leaf BEFORE reading — never follow a symlink to count an untracked file's lines.
+    const abs = join(root, rel);
+    if (!isRegularLeaf(abs)) {
+      unsupported.push(rel);
+      continue;
+    }
+    const src = readFileSafe(abs);
+    const count = src == null || src.length === 0 ? 0 : src.split('\n').length;
+    assessable.set(rel, Array.from({ length: count }, (_, i) => i + 1));
+  }
+  return { assessable, unsupported: unsupported.sort(), outOfDomain: outOfDomain.sort() };
+};
+
+// ── coverage (run the suite once under NODE_V8_COVERAGE, outside the tree) ─────────────────────────
+
+// readCoverage(covDir) → Map<canonicalAbsPath, Array<Array<range>>> — one flat range-list per process.
+const readCoverage = (covDir) => {
+  const byPath = new Map();
+  let files;
+  try {
+    files = readdirSync(covDir);
+  } catch {
+    return byPath;
+  }
+  for (const f of files) {
+    if (!f.endsWith('.json')) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(join(covDir, f), 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!parsed || !Array.isArray(parsed.result)) continue;
+    for (const entry of parsed.result) {
+      if (typeof entry.url !== 'string' || !entry.url.startsWith('file:')) continue;
+      let abs;
+      try {
+        abs = canon(fileURLToPath(entry.url));
+      } catch {
+        continue;
+      }
+      const ranges = [];
+      for (const fn of entry.functions ?? []) for (const r of fn.ranges ?? []) ranges.push({ startOffset: r.startOffset, endOffset: r.endOffset, count: r.count });
+      if (!byPath.has(abs)) byPath.set(abs, []);
+      byPath.get(abs).push(ranges);
+    }
+  }
+  return byPath;
+};
+
+// ── suite command discovery (Decision 10) ─────────────────────────────────────────────────────────
+
+const GATES_REL = 'docs/ai/gates.json';
+const resolveSuiteCmd = (root, env, explicit) => {
+  if (explicit) return explicit;
+  if (env.AW_FOLD_SUITE_CMD) return env.AW_FOLD_SUITE_CMD;
+  const raw = readFileSafe(join(root, GATES_REL));
+  if (raw) {
+    try {
+      const gate = (JSON.parse(raw).gates ?? []).find((g) => g && g.id === 'unit-tests');
+      if (gate && typeof gate.cmd === 'string') return gate.cmd;
+    } catch {
+      /* fall through to the loud refusal */
+    }
+  }
+  throw stop(`cannot resolve the suite command — no unit-tests gate in ${GATES_REL}; pass --suite "<cmd>" or set AW_FOLD_SUITE_CMD`);
+};
+
+// ── the append primitive (whole-file read → add one JSONL line → atomic rewrite) ─────────────────
+
+const appendRecord = (resultsPath, record) => {
+  let existing = '';
+  try {
+    existing = readFileSync(resultsPath, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') existing = '';
+    else throw stop(`cannot read the result ledger before appending (${(err && err.code) || (err && err.message) || err}) — refusing to overwrite it (fail closed)`);
+  }
+  const prefix = existing === '' ? '' : existing.endsWith('\n') ? existing : `${existing}\n`;
+  const body = `${prefix}${JSON.stringify(record)}\n`;
+  writeContainedFileAtomic(dirname(resultsPath), resultsPath, body, {}, { stop, label: resultsPath });
+  return { writtenPath: resultsPath, record };
+};
+
+// ── the run ───────────────────────────────────────────────────────────────────────────────────────
+
+const budgetsFromEnv = (env) => ({
+  mutantsMax: Number.parseInt(env.AW_FOLD_MUTANTS_MAX ?? '200', 10) || 200,
+  hunkMutantsMax: Number.parseInt(env.AW_FOLD_HUNK_MUTANTS_MAX ?? '25', 10) || 25,
+  timeBudgetS: Number.parseInt(env.AW_FOLD_TIME_BUDGET_S ?? '600', 10) || 600,
+});
+
+// runFoldCompleteness({ cwd, env, suiteCmd }) → { writtenPath, record }. THROWS a typed STOP (loop
+// derivation / suite discovery / a malformed record / an fs error) or a native fs error.
+export const runFoldCompleteness = ({ cwd = process.cwd(), env = process.env, suiteCmd } = {}) => {
+  const root = gitStdout(['rev-parse', '--show-toplevel'], cwd);
+  if (root == null) throw stop('not a git work tree — nothing to assess');
+  const rootTop = root.replace(/\r?\n$/, '');
+
+  // Decision: the loop = the single in-flight plan stem; 0 or >1 → refuse (ambiguous).
+  const plans = plansInFlight(rootTop);
+  if (plans.length === 0) throw stop('no plan in flight (docs/plans/ holds no active plan) — nothing to assess');
+  if (plans.length > 1) throw stop(`more than one plan in flight (${plans.join(', ')}) — ambiguous loop id; resolve to one active plan`);
+  const loop = plans[0].replace(/\.md$/, '');
+
+  const fingerprint = computeTreeFingerprint(cwd);
+  const cmd = resolveSuiteCmd(rootTop, env, suiteCmd);
+  const boundArgv = resolveBoundArgv(env); // resolves BEFORE any spawn (a malformed override refuses loudly)
+  const budgets = budgetsFromEnv(env);
+
+  const { assessable, unsupported, outOfDomain } = computeChangedSurface(rootTop);
+
+  // M3a: run the suite once under coverage in a dir OUTSIDE the work tree (Decision 8), then map.
+  const covDir = mkdtempSync(join(tmpdir(), 'agent-workflow-fold-cov-'));
+  let coverage;
+  try {
+    const suite = spawnSync('bash', ['-c', cmd], { cwd: rootTop, env: childTestEnv(env, { NODE_V8_COVERAGE: covDir }), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    if (suite.error && suite.error.code === 'ENOENT') throw stop('bash is unavailable — the suite command is a bash command line');
+    coverage = readCoverage(covDir);
+  } finally {
+    rmSync(covDir, { recursive: true, force: true });
+  }
+  const uncoveredChanged = [];
+  for (const [rel, lines] of assessable) {
+    const perProc = coverage.get(canon(join(rootTop, rel)));
+    if (!perProc || perProc.length === 0) {
+      uncoveredChanged.push({ file: rel, line: null }); // absent from coverage → file-level RED (Decision 6)
+      continue;
+    }
+    const src = readFileSafe(join(rootTop, rel));
+    if (src == null) continue;
+    for (const n of computeUncoveredLines({ perProcessRanges: perProc, sourceText: src, changedLines: lines })) uncoveredChanged.push({ file: rel, line: n });
+  }
+
+  // Decision 3 / 10: probe each fixable-bug bound testId once (shell-free).
+  const ledgerPath = resolveLedgerPath(cwd, env);
+  const { records: reviewRecords } = ledgerPath ? readLedger(ledgerPath) : { records: [] };
+  const boundTestIds = collectBoundTestIds(reviewRecords, { activity: ACTIVITY, loop });
+  const testIds = boundTestIds.map((id) => {
+    const at = id.indexOf('#');
+    const file = id.slice(0, at);
+    const pattern = id.slice(at + 1);
+    const argv = boundArgv(file, pattern);
+    const res = spawnSync(argv[0], argv.slice(1), { cwd: rootTop, env: childTestEnv(env), encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    return { id, ...parseProbeOutput({ stdout: res.stdout ?? '', code: res.error ? 1 : res.status ?? 1, fileArg: file }) };
+  });
+
+  const record = {
+    schema: RESULT_SCHEMA_VERSION,
+    loop,
+    fingerprint,
+    boundTestIds,
+    testIds,
+    unsupported,
+    outOfDomain,
+    coverage: { uncoveredChanged },
+    mutation: { total: 0, killed: 0, survived: [], skipped: 0, killSetBasis: null }, // reserved — mutation not shipped (shelved)
+    budgets,
+    timestamp: isoNow(),
+  };
+  const v = validateRunRecord(record);
+  if (!v.ok) throw stop(`refusing to write a malformed result record: ${v.reason}`);
+
+  const resultsPath = resolveResultsPath(cwd, env);
+  if (resultsPath == null) throw stop('cannot resolve the result-ledger path — not a git work tree and AW_FOLD_RESULTS is unset');
+  return appendRecord(resultsPath, record);
+};
+
+// ── CLI ───────────────────────────────────────────────────────────────────────────────────────────
+
+const HELP = `fold-completeness-run — the M3 fold-completeness RUNNER (agent-workflow family, AD-046).
+
+Usage:
+  node fold-completeness-run.mjs [--suite "<cmd>"] [--cwd <dir>]
+
+Runs the in-flight plan-execution loop's suite ONCE under coverage, maps every changed executable line
+to covered/uncovered, probes each fixable-bug bound testId for resolvability + a green baseline, and
+appends one result record to <git dir>/${'agent-workflow-fold-completeness.jsonl'} (AW_FOLD_RESULTS
+overrides). The read-only gate is a SEPARATE tool: node fold-completeness.mjs --check / --status / --json.
+
+Suite command: --suite "<cmd>" or AW_FOLD_SUITE_CMD, else the unit-tests gate cmd in docs/ai/gates.json.
+Bound-test runs default to node --test --test-name-pattern (shell-free); AW_FOLD_BOUND_CMD overrides
+with a JSON argv array using {file}/{pattern}. Budgets: AW_FOLD_MUTANTS_MAX / AW_FOLD_HUNK_MUTANTS_MAX /
+AW_FOLD_TIME_BUDGET_S (recorded but inert — the mutation half is not shipped).
+
+Exit codes: 0 written; 1 a typed STOP (loop derivation / suite discovery / malformed record / fs error);
+2 usage.`;
+
+const parseArgs = (argv) => {
+  const opts = { cwd: undefined, suite: undefined };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--cwd') {
+      opts.cwd = argv[i + 1];
+      if (opts.cwd === undefined) throw usageFail('--cwd needs a directory');
+      i += 1;
+    } else if (a === '--suite') {
+      opts.suite = argv[i + 1];
+      if (opts.suite === undefined) throw usageFail('--suite needs a command');
+      i += 1;
+    } else {
+      throw usageFail(`unknown argument: ${a}`);
+    }
+  }
+  return opts;
+};
+
+export const main = (argv, ctx = {}) => {
+  const cwd0 = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const opts = parseArgs(argv);
+    const { writtenPath, record } = runFoldCompleteness({ cwd: opts.cwd ?? cwd0, env, suiteCmd: opts.suite });
+    const uncovered = record.coverage.uncoveredChanged.length;
+    const unresolved = record.testIds.filter((t) => !t.resolvable || !t.baselineGreen).length;
+    return {
+      code: 0,
+      stdout: `fold-completeness-run: recorded a run for loop "${record.loop}" (${record.boundTestIds.length} bound testId(s), ${unresolved} unresolved/red, ${uncovered} uncovered changed line(s), ${record.unsupported.length} unsupported, ${record.outOfDomain.length} out-of-domain) → ${writtenPath}`,
+      stderr: '',
+    };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `fold-completeness-run: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+  process.exitCode = r.code;
+}

package/tools/fold-completeness.mjs

@@ -0,0 +1,364 @@
+#!/usr/bin/env node
+// fold-completeness.mjs — the read-only FOLD-COMPLETENESS checker behind `/agent-workflow-kit
+// fold-completeness` (M3, AD-046, DEBT-TEST-COMPLETENESS). It is the sibling gate of
+// review-ledger.mjs: the ledger computes the review-loop crossover-stop; this tool computes whether
+// the tests that the loop's folds bind to ACTUALLY pin the changed code. It reads the result ledger
+// the runner writes (fold-completeness-run.mjs — the SOLE tree-toucher + result writer), recomputes
+// the canonical uncommitted-state fingerprint, resolves the plan-execution.review recipe + the
+// in-flight plan, and decides `--check` fail-closed. It NEVER runs tests, NEVER mutates, and NEVER
+// imports the runner — an import-split test pins that structural invariant (the read half owns the
+// result SCHEMA + reader; the runner imports them the other direction, mirroring review-ledger /
+// review-ledger-write).
+//
+// Normative `--check` exit contract (the single home of this list — SKILL.md / the mode file point
+// here). The gate is plan-EXECUTION-scoped, filtered to the in-flight plan's filename stem:
+//   exit 0  when the resolved plan-execution.review recipe is solo (configured, or degraded there);
+//           when no plan is in flight; when the tree is clean; when the cwd is not a git work tree;
+//           and when the in-flight plan-execution loop has a CURRENT run record whose BOTH bindings
+//           match — the tree fingerprint AND the sorted fixable-bug testId set recorded in the run —
+//           with every bound testId resolvable + baseline-green, 0 uncovered changed lines, 0 changed
+//           unsupported-source files, and the reserved EMPTY mutation shape (v1 ships no mutation).
+//   exit 1  for any DIRTY in-flight plan-execution loop lacking such a current run record — including
+//           the stale-fingerprint case (a tree edit moves the fingerprint) and the same-fingerprint/
+//           new-testId case (a triage recorded after the run moves the bound-testId set, Decision 9) —
+//           or a run naming an unresolvable/red-baseline bound test, an uncovered changed line, a
+//           changed unsupported-source file, or ANY mutation data (v1 ships no mutation — such a record
+//           was not produced by this runner version; fail closed); when MORE THAN ONE plan is in
+//           flight (ambiguous loop id). Fail-CLOSED (unknown state, never a fail-open pass) on a
+//           detector failure, an unreadable/malformed result or review ledger, or a corrupt run set —
+//           the only detector-independent green is an EXPLICIT configured solo. Changed OUT-OF-DOMAIN
+//           files (docs/config the suite does not execute) are LOUDLY listed but never gate-blocking
+//           (Decision 5): guarding what the tool cannot assess with a red gate is a pretend-mechanism.
+//
+// HONEST residuals (accepted, documented — exactly like review-state's / review-ledger's): coverage
+// proves execution, not assertion; NO mutation signal ships in v1 — the researched mutation half was
+// shelved, the record's `mutation` field is a reserved empty shape (a record carrying ANY mutation
+// data fails the check closed); the result records, testIds, and the ledger are forgeable
+// (`git commit --no-verify`, file editing) — a self-discipline mechanism against silent process
+// drift, NOT a security boundary. TS/JSX source is out of scope v1 (a changed unsupported-source
+// file fails the gate closed rather than be vouched for).
+//
+// Read-only: never writes, never commits, never runs a subscription CLI. It DOES spawn read-only
+// `git` queries (via the reused review-state fingerprint reader + a git-dir resolver). Dependency-
+// free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { detectBackends } from './detect-backends.mjs';
+import { resolveActivityRecipe, planRecipe, DISPLAY_ALIASES } from './recipes.mjs';
+import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
+import { computeTreeFingerprint, isTreeClean, plansInFlight } from './review-state.mjs';
+import { resolveLedgerPath, readLedger, filterLoopRecords } from './review-ledger.mjs';
+
+export const RESULTS_BASENAME = 'agent-workflow-fold-completeness.jsonl';
+export const RESULT_SCHEMA_VERSION = 1;
+const ACTIVITY = 'plan-execution';
+const SLOT = 'review';
+
+// ── git-dir resolution (read-only queries; the ledger lives in the git dir, uncommittable) ──────
+
+const gitLine = (args, cwd) => {
+  const r = spawnSync('git', args, { cwd, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  return r.stdout.toString('utf8').replace(/\r?\n$/, '');
+};
+
+const gitRoot = (cwd) => gitLine(['rev-parse', '--show-toplevel'], cwd);
+
+// The result-ledger path: AW_FOLD_RESULTS overrides (mirrors AW_REVIEW_LEDGER); else <git dir>/basename.
+export const resolveResultsPath = (cwd, env = process.env) => {
+  if (env.AW_FOLD_RESULTS) return env.AW_FOLD_RESULTS;
+  const gitDir = gitLine(['rev-parse', '--absolute-git-dir'], cwd);
+  return gitDir == null ? null : join(gitDir, RESULTS_BASENAME);
+};
+
+// ── the bound fixable-bug testId set (the SINGLE source of truth — runner + checker share it) ────
+
+// collectBoundTestIds(reviewRecords, { activity, loop }) → the sorted, de-duplicated testIds of the
+// loop's fixable-bug classifications. Pure over review-ledger records. Both the runner (which records
+// the set as a binding) and the checker (which recomputes it for the staleness check) call THIS, so
+// the two can never drift (Decision 9: same-fingerprint/new-testId is stale).
+export const collectBoundTestIds = (reviewRecords, { activity = ACTIVITY, loop } = {}) => {
+  const ids = new Set();
+  for (const r of filterLoopRecords(reviewRecords, { activity, loop })) {
+    if (r.kind !== 'triage') continue;
+    for (const c of r.classifications) if (c.class === 'fixable-bug' && typeof c.testId === 'string' && c.testId.length > 0) ids.add(c.testId);
+  }
+  return [...ids].sort();
+};
+
+// ── result-record schema (machine fields only; the runner refuses to write a malformed record) ───
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
+const isNonNegInt = (v) => Number.isInteger(v) && v >= 0;
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+
+// validateRunRecord(obj) → { ok, reason }. The `reason` names the exact failed check so the
+// malformed-line surface and the per-check named tests can assert it. Mutation is reserved and must
+// stay the empty shape in v1 (the mutation half is shelved); the schema carries the fields so a
+// record validates uniformly and decideCheck enforces the exact reserved shape.
+export const validateRunRecord = (obj) => {
+  if (!isPlainObject(obj)) return { ok: false, reason: 'not an object' };
+  if (obj.schema !== RESULT_SCHEMA_VERSION) return { ok: false, reason: `schema must be ${RESULT_SCHEMA_VERSION}` };
+  if (!isNonEmptyString(obj.loop)) return { ok: false, reason: 'missing loop' };
+  if (!(obj.fingerprint === null || isNonEmptyString(obj.fingerprint))) return { ok: false, reason: 'fingerprint must be null or a non-empty string' };
+  if (!isStringArray(obj.boundTestIds)) return { ok: false, reason: 'boundTestIds must be an array of strings' };
+  if (!Array.isArray(obj.testIds)) return { ok: false, reason: 'testIds must be an array' };
+  for (const t of obj.testIds) {
+    if (!isPlainObject(t) || !isNonEmptyString(t.id)) return { ok: false, reason: 'each testId entry needs an id' };
+    if (typeof t.resolvable !== 'boolean' || typeof t.baselineGreen !== 'boolean') return { ok: false, reason: `testId ${t.id} needs boolean resolvable + baselineGreen` };
+    if (!isNonNegInt(t.executed)) return { ok: false, reason: `testId ${t.id} executed must be a non-negative integer` };
+  }
+  if (!isStringArray(obj.unsupported)) return { ok: false, reason: 'unsupported must be an array of strings' };
+  if (!isStringArray(obj.outOfDomain)) return { ok: false, reason: 'outOfDomain must be an array of strings' };
+  if (!isPlainObject(obj.coverage) || !Array.isArray(obj.coverage.uncoveredChanged)) return { ok: false, reason: 'coverage.uncoveredChanged must be an array' };
+  for (const u of obj.coverage.uncoveredChanged) {
+    if (!isPlainObject(u) || !isNonEmptyString(u.file)) return { ok: false, reason: 'each uncoveredChanged entry needs a file' };
+    if (!(u.line === null || (Number.isInteger(u.line) && u.line >= 1))) return { ok: false, reason: `uncoveredChanged ${u.file} line must be null or an integer >= 1` };
+  }
+  const m = obj.mutation;
+  if (!isPlainObject(m) || !isNonNegInt(m.total) || !isNonNegInt(m.killed) || !Array.isArray(m.survived) || !isNonNegInt(m.skipped)) {
+    return { ok: false, reason: 'mutation must be { total, killed, survived[], skipped, killSetBasis }' };
+  }
+  if (!(m.killSetBasis === null || isNonEmptyString(m.killSetBasis))) return { ok: false, reason: 'mutation.killSetBasis must be null or a non-empty string' };
+  if (!isPlainObject(obj.budgets)) return { ok: false, reason: 'budgets must be an object' };
+  if (!isNonEmptyString(obj.timestamp)) return { ok: false, reason: 'missing timestamp' };
+  return { ok: true };
+};
+
+// readResults(path) → { records, malformed, malformedReasons, readError }. Absent file → empty (no run
+// yet). A non-ENOENT read error surfaces as readError so callers fail CLOSED (mirrors readLedger).
+export const readResults = (path, readFile = readFileSync) => {
+  let raw;
+  try {
+    raw = readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { records: [], malformed: 0, malformedReasons: [] };
+    return { records: [], malformed: 0, malformedReasons: [], readError: (err && err.code) || (err && err.message) || 'read failed' };
+  }
+  const records = [];
+  const malformedReasons = [];
+  for (const line of raw.split('\n')) {
+    if (line.trim() === '') continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      malformedReasons.push(`unparseable JSON (${err.message})`);
+      continue;
+    }
+    const v = validateRunRecord(parsed);
+    if (v.ok) records.push(parsed);
+    else malformedReasons.push(v.reason);
+  }
+  return { records, malformed: malformedReasons.length, malformedReasons };
+};
+
+// filterLoopResults(records, loop) → the run records of ONE loop, order preserved (latest is last).
+export const filterLoopResults = (records, loop) => records.filter((r) => r.loop === loop);
+
+// ── the check + report core ─────────────────────────────────────────────────────────────────────
+
+// buildFoldState({ cwd, env, detect }) → everything both renders need. Pure I/O at the edges; every
+// project-relative read anchors at the git work-tree ROOT when one exists (the fingerprint is
+// root-anchored — the same discipline review-state / review-ledger use).
+export const buildFoldState = ({ cwd, env = process.env, detect = detectBackends } = {}) => {
+  const root = gitRoot(cwd) ?? cwd;
+  const { config, source: configSource } = loadConfig(root);
+  let detection = [];
+  let detectionWarning = null;
+  try {
+    detection = detect();
+  } catch (err) {
+    detectionWarning = `backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; the review recipe floors at solo.`;
+  }
+  const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
+  const { dispatch } = planRecipe(resolved.recipe, detection);
+  const requiredBackends = dispatch.map((d) => DISPLAY_ALIASES[d.backend] ?? d.backend);
+  const plans = plansInFlight(root);
+  const fingerprint = computeTreeFingerprint(cwd);
+  const clean = fingerprint == null ? null : isTreeClean(cwd);
+  const resultsPath = resolveResultsPath(cwd, env);
+  const resultRead = resultsPath ? readResults(resultsPath) : { records: [], malformed: 0, malformedReasons: [] };
+  const reviewPath = resolveLedgerPath(cwd, env);
+  const reviewRead = reviewPath ? readLedger(reviewPath) : { records: [], malformed: 0, malformedReasons: [] };
+  return {
+    resolved,
+    configSource,
+    requiredBackends,
+    plans,
+    fingerprint,
+    clean,
+    resultsPath,
+    resultRecords: resultRead.records,
+    resultMalformed: resultRead.malformed,
+    resultReadError: resultRead.readError,
+    reviewPath,
+    reviewRecords: reviewRead.records,
+    reviewMalformed: reviewRead.malformed,
+    reviewReadError: reviewRead.readError,
+    detectionWarning,
+  };
+};
+
+const sameSet = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+// The reserved (and, in v1, only legal) mutation key set — sorted for the sameSet comparison.
+const RESERVED_MUTATION_KEYS = ['killSetBasis', 'killed', 'skipped', 'survived', 'total'];
+const renderUncovered = (u) => (u.line === null ? `${u.file} (absent from coverage)` : `${u.file}:${u.line}`);
+
+// The normative --check decision (the header contract, in order) → { code, reason }. The checker is
+// PURE over (record, current fingerprint, review ledger) — it recomputes NO coverage/mutation.
+export const decideCheck = (state) => {
+  // A detector failure is UNKNOWN state, not "no reviewer ready" — fail closed (like review-ledger).
+  const explicitSolo = state.resolved.recipe === 'solo' && state.resolved.source === 'config' && !state.resolved.degradedFrom;
+  if (state.detectionWarning && !explicitSolo) return { code: 1, reason: `cannot verify fold-completeness — ${state.detectionWarning}` };
+  if (state.resolved.recipe === 'solo') {
+    const why = state.resolved.degradedFrom ? `resolved ${ACTIVITY}.${SLOT} recipe degrades to solo here (${state.resolved.reason})` : `resolved ${ACTIVITY}.${SLOT} recipe is solo`;
+    return { code: 0, reason: `${why} — no fold-completeness run required` };
+  }
+  if (state.plans.length === 0) return { code: 0, reason: 'no plan in flight (docs/plans/ holds no active plan) — no fold-completeness run required' };
+  if (state.plans.length > 1) return { code: 1, reason: `more than one plan in flight (${state.plans.join(', ')}) — ambiguous loop id; resolve to one active plan` };
+  if (state.fingerprint == null) return { code: 0, reason: 'not a git work tree — nothing to assess' };
+  if (state.clean === true) return { code: 0, reason: 'the working tree is clean — nothing to assess' };
+  // Fail CLOSED on any ledger the reader could not fully trust (a dropped line could hide a defect).
+  if (state.resultReadError) return { code: 1, reason: `cannot read the result ledger (${state.resultReadError}) — failing closed; inspect ${state.resultsPath}` };
+  if (state.resultMalformed > 0) return { code: 1, reason: `the result ledger has ${state.resultMalformed} malformed line(s) — failing closed; inspect ${state.resultsPath}` };
+  if (state.reviewReadError) return { code: 1, reason: `cannot read the review ledger (${state.reviewReadError}) — failing closed; inspect ${state.reviewPath}` };
+  if (state.reviewMalformed > 0) return { code: 1, reason: `the review ledger has ${state.reviewMalformed} malformed line(s) — failing closed; inspect ${state.reviewPath}` };
+
+  const loop = state.plans[0].replace(/\.md$/, '');
+  const runs = filterLoopResults(state.resultRecords, loop);
+  if (runs.length === 0) return { code: 1, reason: `dirty plan-execution loop "${loop}" but no fold-completeness run recorded — run fold-completeness-run.mjs` };
+  const latest = runs[runs.length - 1];
+
+  // Decision 9 — the double binding. A tree edit moves the fingerprint; a new fixable-bug triage moves
+  // the bound-testId set. Either mismatch is STALE (the run no longer describes the committable tree).
+  if (latest.fingerprint !== state.fingerprint) return { code: 1, reason: `no fold-completeness run for the current tree (the tree was edited after the run) — re-run fold-completeness-run.mjs after the last edit` };
+  const currentBound = collectBoundTestIds(state.reviewRecords, { activity: ACTIVITY, loop });
+  if (!sameSet(latest.boundTestIds, currentBound)) return { code: 1, reason: `a fixable-bug testId was triaged after the run (the bound-testId set changed) — re-run fold-completeness-run.mjs` };
+  // Fail CLOSED if the run's probe set does not cover its bound-testId set EXACTLY. A well-formed
+  // runner record always probes every bound testId (one testIds[] entry per boundTestId), but a record
+  // with missing/extra/duplicate probes is untrustworthy — proving "0 unresolvable, 0 red" over an
+  // EMPTY (or partial) probe set proves nothing about the bound tests (codex R1).
+  const probedIds = latest.testIds.map((t) => t.id).sort();
+  if (!sameSet(probedIds, latest.boundTestIds)) return { code: 1, reason: `the run's probe set does not match its bound-testId set (${probedIds.length} probe(s) for ${latest.boundTestIds.length} bound testId(s)) — failing closed; re-run fold-completeness-run.mjs` };
+
+  // A changed unsupported-source file → fail closed: the signal never vouches for JS-family source it
+  // cannot assess (TS/JSX out of scope v1, Decision 5).
+  if (latest.unsupported.length > 0) return { code: 1, reason: `changed unsupported-source file(s) the signal cannot assess (TS/JSX out of scope v1): ${latest.unsupported.join(', ')}` };
+  const unresolvable = latest.testIds.filter((t) => !t.resolvable).map((t) => t.id);
+  if (unresolvable.length > 0) return { code: 1, reason: `unresolvable bound testId(s) — the pattern selects no test: ${unresolvable.join(', ')}` };
+  const redBaseline = latest.testIds.filter((t) => t.resolvable && !t.baselineGreen).map((t) => t.id);
+  if (redBaseline.length > 0) return { code: 1, reason: `bound test(s) with a red baseline (the fold is not complete): ${redBaseline.join(', ')}` };
+  if (latest.coverage.uncoveredChanged.length > 0) return { code: 1, reason: `uncovered changed line(s) — changed code no test executed: ${latest.coverage.uncoveredChanged.map(renderUncovered).join(', ')}` };
+  // v1 ships NO mutation (the mutation half was shelved): the shipped runner only ever writes the
+  // reserved empty shape, so a record carrying ANY mutation data was not produced by this runner
+  // version (forged, or a version-skewed ledger — e.g. an older placed checker reading a newer
+  // runner's ledger) — fail closed rather than vouch for a signal v1 cannot have computed. The rule
+  // is the EXACT reserved shape (key set + empty values): an extra key would smuggle mutation data
+  // past a known-fields-only check.
+  const m = latest.mutation;
+  const emptyReservedShape =
+    sameSet(Object.keys(m).sort(), RESERVED_MUTATION_KEYS) &&
+    m.total === 0 && m.killed === 0 && m.skipped === 0 && m.survived.length === 0 && m.killSetBasis === null;
+  if (!emptyReservedShape) {
+    return { code: 1, reason: `the run record's mutation field is not the reserved empty shape (${m.total} total / ${m.killed} killed / ${m.survived?.length ?? '?'} survived / ${m.skipped} skipped) but v1 ships no mutation — not a record this runner version produced; re-run fold-completeness-run.mjs` };
+  }
+
+  const notes = [];
+  if (latest.outOfDomain.length > 0) notes.push(`out-of-domain changes not assessed (non-blocking): ${latest.outOfDomain.join(', ')}`);
+  return { code: 0, reason: `fold-completeness verified for loop "${loop}" (fingerprint + bound-testId set current, coverage + baseline green)${notes.length ? ` — ${notes.join('; ')}` : ''}` };
+};
+
+// ── rendering ─────────────────────────────────────────────────────────────────────────────────
+
+const runLine = (r) => {
+  const tests = r.testIds.length ? r.testIds.map((t) => `${t.id}${t.resolvable ? (t.baselineGreen ? '✓' : ' red-baseline') : ' unresolvable'}`).join(', ') : '(no bound tests)';
+  const uncov = r.coverage.uncoveredChanged.length ? r.coverage.uncoveredChanged.map(renderUncovered).join(', ') : 'none';
+  return [
+    `  latest run — fingerprint ${r.fingerprint}`,
+    `    bound testIds: ${tests}`,
+    `    uncovered changed: ${uncov}`,
+    `    unsupported: ${r.unsupported.length ? r.unsupported.join(', ') : 'none'} · out-of-domain: ${r.outOfDomain.length ? r.outOfDomain.join(', ') : 'none'}`,
+    `    mutation: ${r.mutation.total} total / ${r.mutation.killed} killed / ${r.mutation.survived.length} survived / ${r.mutation.skipped} skipped`,
+  ].join('\n');
+};
+
+const formatHuman = (state, check) => {
+  const src = state.configSource === 'config' ? `from ${CONFIG_REL}` : 'computed default';
+  const lines = [
+    `fold-completeness — ${ACTIVITY}.${SLOT} = ${state.resolved.recipe} (${src})${state.requiredBackends.length ? ` → ${state.requiredBackends.join(' + ')}` : ''}`,
+  ];
+  if (state.detectionWarning) lines.push(`  ⚠ ${state.detectionWarning}`);
+  lines.push(`  plan in flight: ${state.plans.length ? state.plans.join(', ') : '(none)'}`);
+  if (state.fingerprint == null) lines.push('  tree: not a git work tree');
+  else if (state.clean === true) lines.push('  tree: clean (nothing to assess)');
+  else lines.push(`  tree fingerprint: ${state.fingerprint}`);
+  lines.push(`  result ledger: ${state.resultsPath ?? '(unresolvable — no git dir)'} (${state.resultRecords.length} record(s)${state.resultMalformed ? `, ${state.resultMalformed} malformed — inspect the file` : ''})`);
+  if (state.plans.length === 1) {
+    const loop = state.plans[0].replace(/\.md$/, '');
+    const runs = filterLoopResults(state.resultRecords, loop);
+    if (runs.length > 0) lines.push(runLine(runs[runs.length - 1]));
+  }
+  lines.push(`  check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`);
+  return lines.join('\n');
+};
+
+const HELP = `fold-completeness — read-only FOLD-COMPLETENESS checker (agent-workflow family, AD-046).
+
+Usage:
+  node fold-completeness.mjs [--check | --status | --json]
+
+Reads the result ledger the runner writes (<git dir>/${RESULTS_BASENAME}; AW_FOLD_RESULTS overrides),
+resolves the effective ${ACTIVITY}.${SLOT} recipe, recomputes the canonical uncommitted-state
+fingerprint, and decides whether the in-flight plan-execution loop's changed code is pinned by tests.
+
+--status (default) → the human report: resolved recipe, plan-in-flight, the latest run summary, verdict.
+--check → the gate exit code. The normative exit contract lives in the tool header (the single home):
+  exit 0 for solo / no plan in flight / a clean tree / not-a-git-tree / a CURRENT run whose fingerprint
+  AND bound-testId set both match, with resolvable+green bound tests, 0 uncovered changed lines, 0
+  changed unsupported source, and the reserved empty mutation shape; exit 1 otherwise (stale/missing
+  run, an unresolvable/red bound test, an uncovered line, changed TS/JSX, any mutation data — v1 ships
+  no mutation, >1 plan, an unreadable/malformed ledger, or a detector failure). Out-of-domain changes
+  are listed, never blocking.
+--json → the structured state + decision.
+
+The runner is a SEPARATE tool (fold-completeness-run.mjs) — this read-only checker never imports it.
+Human residual: git commit --no-verify and ledger editing remain possible — a self-discipline mechanism.
+
+Exit codes: 0 pass (or plain report); 1 check failed or config error (loud); 2 usage.`;
+
+const KNOWN_ARGS = new Set(['--help', '-h', '--check', '--status', '--json']);
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const env = ctx.env ?? process.env;
+  const detect = ctx.detect ?? detectBackends;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
+    if (unknown !== undefined) throw fail(2, `unknown argument: ${unknown}`);
+    const state = buildFoldState({ cwd, env, detect });
+    const check = decideCheck(state);
+    if (argv.includes('--json')) {
+      return { code: argv.includes('--check') ? check.code : 0, stdout: JSON.stringify({ ...state, check }, null, 2), stderr: '' };
+    }
+    if (argv.includes('--check')) {
+      return { code: check.code, stdout: `fold-completeness check: ${check.code === 0 ? 'PASS' : 'FAIL'} — ${check.reason}`, stderr: '' };
+    }
+    return { code: 0, stdout: formatHuman(state, check), stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `fold-completeness: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : `${r.stdout}\n`);
+  if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : `${r.stderr}\n`);
+  process.exitCode = r.code;
+}

package/tools/procedures.mjs

@@ -198,7 +198,10 @@ const backendSetLabel = (backends) =>
 // REQUIRED per-round structured emission {round N · finding-origin tally · per-backend verdict}. Only a
 // review slot can resolve reviewed|council (execute floors at solo|delegated), so gate on the recipe.
 const REVIEW_RECIPES = new Set(['reviewed', 'council']);
-const reviewLoopAdvice = (slots) =>
+// activity-aware (AD-046): the triage classification vocabulary rides EVERY review-backed activity;
+// the LEDGER pointer renders ONLY for plan-execution — the ledger is plan-execution-scoped (AD-045),
+// and pointing plan-authoring at it would send rounds of the wrong activity into the code loop's gate.
+const reviewLoopAdvice = (slots, activity) =>
   slots.some((s) => REVIEW_RECIPES.has(s.recipe))
     ? [
         'Review-loop economics (planning.md §9 · orchestration.md §4) — the review this recipe runs:',
@@ -206,6 +209,12 @@ const reviewLoopAdvice = (slots) =>
         '  • Backend divergence (one backend grounded-ships while another keeps revising mechanics) IS the crossover stop.',
         '  • Route an all-mechanics/CI or prose-only artifact to a thin plan + diff-review; run a self-consistency read before every re-review.',
         '  • Each round MUST emit {round N · finding-origin tally (first-draft / fold-induced / mechanics) · per-backend verdict} so the crossover is a computed signal.',
+        '  • At the cap, classify every surviving blocking finding: fixable-bug (fold ONCE as a red→green test, re-review) / inherent-layer-residual (document + raise to an acceptance criterion) / escalate (the maintainer decides); a minor never forces triage.',
+        ...(activity === 'plan-execution'
+          ? [
+              '  • The computed instrument for THIS loop: record each round + triage via review-ledger (record / classify); read the stop with review-ledger --status (its render replaces the hand-composed tally); gate the commit with review-ledger --check.',
+            ]
+          : []),
       ]
     : [];
 
@@ -302,7 +311,7 @@ const formatHuman = ({ activity, section, slots, warnings, plans }) => {
   }
   const grounding = groundingPreStepAdvice(activity, slots, plans);
   if (grounding.length) lines.push('', ...grounding);
-  const advice = reviewLoopAdvice(slots);
+  const advice = reviewLoopAdvice(slots, activity);
   if (advice.length) lines.push('', ...advice);
   lines.push('', ...costLanesAdvice());
   if (warnings.length) {
@@ -320,7 +329,7 @@ const buildJson = ({ activity, section, slots, configSource, warnings, plans })
     // `contracts` is the ADDITIVE per-dispatch driving-contract field (empty for solo).
     slots.map((s) => [s.slot, { recipe: s.recipe, source: s.source, degradedFrom: s.degradedFrom, reason: s.reason, backends: s.backends, contracts: s.contracts }]),
   ),
-  reviewLoop: reviewLoopAdvice(slots),
+  reviewLoop: reviewLoopAdvice(slots, activity),
   // ADDITIVE (AD-038): the populated grounding pre-step, structured (empty when agy is not dispatched).
   groundingPreStep: groundingPreStepAdvice(activity, slots, plans),
   // ADDITIVE (cost-tiered execution): the unconditional cost-lane advisory, structured.

package/tools/review-ledger-write.mjs

@@ -155,9 +155,11 @@ export const recordTriage = (params, deps = {}) => {
   if (ledgerPath == null) throw stop('cannot resolve the ledger path — not a git work tree and AW_REVIEW_LEDGER is unset');
   if (!(Number.isInteger(round) && round >= 1)) throw stop(`round must be an integer >= 1 (got ${round})`);
   const fingerprint = deps.computeFingerprint ? deps.computeFingerprint(cwd) : computeTreeFingerprint(cwd);
-  // Normalize each classification: testId "defaults null" (Decision 8), note defaults to '' — an
-  // absent optional field is FILLED, never rejected as malformed (agy R3). A non-array is left as-is
-  // for validateRecord to reject with a typed STOP (never a raw .map TypeError).
+  // Normalize each classification: an absent testId → null, an absent note → '' — an absent optional
+  // field is FILLED, never rejected as malformed (agy R3). Under schema v2 (M2/AD-046) a fixable-bug
+  // normalized to a null testId then FAILS validateRecord below (a typed STOP naming the rule + the
+  // red-test-first fix) — the test-per-fold binding rides the existing validate path. A non-array is
+  // left as-is for validateRecord to reject with a typed STOP (never a raw .map TypeError).
   const normalized = Array.isArray(classifications) ? classifications.map((c) => ({ ...c, testId: c?.testId ?? null, note: c?.note ?? '' })) : classifications;
   const record = { schema: SCHEMA_VERSION, loop, activity, kind: 'triage', round, fingerprint, classifications: normalized, timestamp: timestamp ?? isoNow() };
   const v = validateRecord(record);
@@ -195,7 +197,9 @@ record   appends one review round. The JSON payload carries { loop, round, origi
          triage is required, beyond the hard-max ceiling of ${HARD_MAX} rounds, or when a non-degraded
          backend lacks a grounded code receipt for the current tree.
 classify appends one triage record. The JSON payload carries { loop, round, classifications } (each
-         { findingKey, class, accepted, testId, note }). This is what permits the next round.
+         { findingKey, class, accepted, testId, note }). A fixable-bug REQUIRES a testId — the
+         red→green test that pins the fold, formatted "<test-file>#<test-name-pattern>" (write it
+         first); inherent-layer-residual / escalate may omit it. This is what permits the next round.
 
 The read-only checker is a SEPARATE tool: node review-ledger.mjs --check / --status / --json.
 Exit codes: 0 written; 1 a typed STOP (teeth / malformed / missing receipt / fs error); 2 usage.`;

package/tools/review-ledger.mjs

@@ -70,7 +70,14 @@ const SLOT = 'review';
 // forces triage. Shared with the writer (which imports it) — the writer-only hard-max ceiling lives
 // there, never here (it is not a decideStop input).
 export const REVIEW_CAP = 2;
-export const SCHEMA_VERSION = 1;
+// SCHEMA_VERSION is what the WRITER emits (M2/AD-046: a fixable-bug triage requires a non-null,
+// well-formed testId — the red→green test that pins the fold). The READER tolerates every
+// SUPPORTED_SCHEMAS version under its own per-version rules, so historical/live v1 ledgers never
+// retroactively become malformed (Decision 2 — a malformed line cascades fail-closed refusals in the
+// writer teeth AND the --check gate). v1 records keep the AD-045 rule (testId optional, unenforced);
+// only v2 enforces the test-per-fold binding. decideStop never reads testId (not a decideStop input).
+export const SCHEMA_VERSION = 2;
+const SUPPORTED_SCHEMAS = new Set([1, 2]);
 
 // The record vocabulary — the single home of every enum the schema validates.
 const ACTIVITIES_SET = new Set(['plan-authoring', 'plan-execution']);
@@ -112,6 +119,17 @@ const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArr
 const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 const isNonNegInt = (v) => Number.isInteger(v) && v >= 0;
 
+// testId FORMAT (Decision 3): "<repo-relative test file>#<test-name-pattern>" — a "#" separator with
+// BOTH halves non-empty. NO file-suffix rule: a suffix check would itself be a special case and would
+// block a consumer's own naming (e.g. `.spec.js`; agy R1). The reader validates FORMAT only (it stays
+// hermetic); the fold-completeness gate validates RESOLVABILITY via a bound-test probe run.
+const TESTID_SEPARATOR = '#';
+const isWellFormedTestId = (v) => {
+  if (typeof v !== 'string') return false;
+  const at = v.indexOf(TESTID_SEPARATOR);
+  return at > 0 && at < v.length - 1; // separator present, both halves non-empty
+};
+
 // validateRound(obj) → { ok, reason }. Structural checks + the two internal-consistency invariants:
 // the per-backend findings-by-severity equal that backend's counts, and the origins tally equals the
 // aggregation of findings[].origin.
@@ -161,16 +179,25 @@ const validateRound = (obj) => {
   return { ok: true };
 };
 
-// validateTriage(obj) → { ok, reason }.
-const validateTriage = (obj) => {
+// validateTriage(obj, schema) → { ok, reason }. `schema` selects the per-version testId rule (v1
+// tolerant / v2 the test-per-fold binding) — the shared structural checks run in both versions.
+const validateTriage = (obj, schema = SCHEMA_VERSION) => {
   if (!Array.isArray(obj.classifications) || obj.classifications.length === 0) return { ok: false, reason: 'triage: classifications must be a non-empty array' };
   for (const c of obj.classifications) {
     if (!isPlainObject(c) || !isNonEmptyString(c.findingKey)) return { ok: false, reason: 'triage: each classification needs a findingKey' };
     if (!CLASSES.has(c.class)) return { ok: false, reason: `triage: classification ${c.findingKey} bad class "${c.class}"` };
     if (typeof c.accepted !== 'boolean') return { ok: false, reason: `triage: classification ${c.findingKey} missing boolean accepted` };
-    // testId "defaults null" (Decision 8) — an ABSENT key is accepted (treated as null), never
-    // rejected as malformed (agy R3). The writer normalizes it to null in the stored record.
+    // Structural (BOTH versions): testId is null/absent or a non-empty string — an ABSENT key is
+    // treated as null, never rejected here (agy R3). The writer normalizes it to null when stored.
     if (!(c.testId === undefined || c.testId === null || isNonEmptyString(c.testId))) return { ok: false, reason: `triage: classification ${c.findingKey} testId must be null/absent or a non-empty string` };
+    // Schema v2 (M2/AD-046) — the test-per-fold binding: a fixable-bug MUST carry a testId (the
+    // red→green test that pins the fold), and ANY present testId must be well-formed. v1 keeps the
+    // AD-045 rule (testId optional, unenforced) so historical/live v1 ledgers never become malformed.
+    if (schema >= 2) {
+      const present = isNonEmptyString(c.testId);
+      if (c.class === 'fixable-bug' && !present) return { ok: false, reason: `triage: classification ${c.findingKey} is a fixable-bug but carries no testId — record the red→green test that pins the fold (write it first)` };
+      if (present && !isWellFormedTestId(c.testId)) return { ok: false, reason: `triage: classification ${c.findingKey} testId "${c.testId}" is malformed — expected "<test-file>#<test-name-pattern>" (a "#" separator, both halves non-empty)` };
+    }
     if (typeof c.note !== 'string') return { ok: false, reason: `triage: classification ${c.findingKey} note must be a string` };
   }
   return { ok: true };
@@ -181,14 +208,14 @@ const validateTriage = (obj) => {
 // malformed-line surface and the per-check named tests can assert it.
 export const validateRecord = (obj) => {
   if (!isPlainObject(obj)) return { ok: false, reason: 'not an object' };
-  if (obj.schema !== SCHEMA_VERSION) return { ok: false, reason: `schema must be ${SCHEMA_VERSION}` };
+  if (!SUPPORTED_SCHEMAS.has(obj.schema)) return { ok: false, reason: `schema must be one of ${[...SUPPORTED_SCHEMAS].join(', ')}` };
   if (!isNonEmptyString(obj.loop)) return { ok: false, reason: 'missing loop' };
   if (!ACTIVITIES_SET.has(obj.activity)) return { ok: false, reason: `bad activity "${obj.activity}"` };
   if (!KINDS_SET.has(obj.kind)) return { ok: false, reason: `bad kind "${obj.kind}"` };
   if (!(Number.isInteger(obj.round) && obj.round >= 1)) return { ok: false, reason: 'round must be an integer >= 1' };
   if (!(obj.fingerprint === null || isNonEmptyString(obj.fingerprint))) return { ok: false, reason: 'fingerprint must be null or a non-empty string' };
   if (!isNonEmptyString(obj.timestamp)) return { ok: false, reason: 'missing timestamp' };
-  return obj.kind === 'round' ? validateRound(obj) : validateTriage(obj);
+  return obj.kind === 'round' ? validateRound(obj) : validateTriage(obj, obj.schema);
 };
 
 // readLedger(path) → { records, malformed, malformedReasons }. Absent file → empty (no review ran).