@sabaiway/agent-workflow-kit 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.
 
+## 3.13.0 — the commit guard proves the INDEX carries the verified tree (AD-074)
+
+`commit-guard --check` now refuses an index that lags the working tree, so «verified» and «about to
+be committed» are the same bytes by construction instead of by operator discipline.
+
+The gap it closes was real and it fired: the gates and the tree fingerprint both describe the
+WORKING tree, while `git commit` builds the commit from the INDEX alone — and against an
+otherwise-empty index the fingerprint is byte-identical whether a hunk sits staged or unstaged. A
+lagging index therefore passed every gate and every guard arm, and the commit shipped a strict
+subset of what was verified. The kit's own 3.12.0 release commit did exactly that: a fix landed
+without its regression arm, and only the publish dispatcher's dirty-tree refusal caught it, one step
+later.
+
+- **A new FIRST refusal, ahead of the fingerprint.** It fires on tracked paths differing
+  index↔worktree or on reviewable untracked-not-ignored paths — the same never-committable stat
+  filter the fingerprint applies, so ignored paths and device/FIFO/socket nodes never refuse. It runs
+  first because its recovery re-stages the tree and re-mints the receipt, which re-decides every arm
+  below it.
+- **The message is actionable and bounded.** Offending paths are named up to a cap with the
+  remainder stated, each rendered through the same escaper the review-state report uses, so no
+  filename can break or forge an output line. The recovery is the complete whole-tree sequence
+  (`git add -A`, re-run `--final`, commit the whole tree) — a truncated list cannot serve as a
+  complete `git add -- <paths>` argument.
+- **The probes cannot be blinded by configuration or index bits.** Entries carrying `skip-worktree`
+  or `assume-unchanged` are invisible to `git diff`, so they are compared directly against the
+  worktree — type, symlink target, executable bit where `core.fileMode` applies, and the blob oid
+  through git's own clean filters. A de-materialised skip-worktree path is an ordinary sparse
+  checkout and never refuses; a missing assume-unchanged path does. The submodule probe forces
+  `--ignore-submodules=none`, so `diff.ignoreSubmodules` cannot erase a dirty submodule either.
+- **A tracked submodule the index cannot prove current is named separately, with its own recovery**
+  (commit or clean inside the submodule, then stage the gitlink): a root-level `git add -A` cannot
+  reach a submodule's own worktree, so offering it there would be a recovery known in advance to
+  fail. A submodule whose gitlink itself carries one of those index bits is not probed at all — it
+  lags by construction. That reduction is deliberate: three review rounds each found a new way for a
+  nested probe to answer "clean" wrongly, so the guard stops asking rather than accumulate patches.
+  It stays a converging refusal (clear the bit and the guard falls silent), and an unflagged
+  submodule is judged exactly as before.
+- **Fail-closed.** An undecidable git probe refuses with its own named cause. The guard's claim is
+  that the committed bytes ARE the verified bytes; it cannot make that claim about a tree it failed
+  to read.
+
+**Behaviour change worth knowing:** a deliberate partial commit is now blocked. `git commit --only
+<path>` hands the hook a temporary index carrying less than the verified tree — precisely the
+blindness this closes — so it refuses. No opt-out flag exists, deliberately: a flag that suspends
+the arm would suspend the guard's whole claim. `git commit --no-verify` remains the stated residual.
+`git commit -a` is unaffected when it captures the whole verified tree, and refuses when a reviewable
+untracked path would be left behind.
+
+The tree fingerprint itself is unchanged — making it stage-sensitive would have closed the same gap
+at the cost of the lockstep with the wrappers' bash twin. Internally, one new computation of the
+index↔worktree split now serves both this arm and `isTreeClean`, so the two can never disagree.
+
+**Stated residual.** This makes the COMMIT capture the whole current working tree; it does not make
+the RECEIPT unforgeable. The fingerprint payload still runs its diffs without
+`--ignore-submodules=none`, so under `diff.ignoreSubmodules=all` a submodule can be changed and its
+gitlink staged after a green final run while the fingerprint stays put, and the stale receipt is
+reused. That is a receipt collision, not an under-capture — no commit ships less than the working
+tree because of it — and closing it means moving the node payload and both bash twins in one
+release. Tracked as its own class, deliberately not folded here.
+
 ## 3.12.0 — `--resume` tolerates the session's work: the verify proves per placed path (AD-073)
 
 `provision --resume` no longer refuses a satellite you have worked in. The closing slice of the

package/README.md

@@ -240,7 +240,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/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. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). Prints to stdout; `--out` writes **one scratch file only** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all refused. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit core-evidence` | any time | **the ONE loop-evidence writer** (strip-the-kit) — every core evidence record lands in a single append-only JSONL store inside the git dir (never committable; versioned schema, latest-per-key supersession, byte-identical duplicates refused, malformed lines fail every reader closed). `red-proof "<file>#<pattern>"` declares an observed-red **BEFORE a bugfix** (N/N red runs + content custody + base + the pre-fix fingerprint; green/mixed/timeout are DISTINGUISHED refusals — nothing written); `degrade --backend --reason` is the ONLY escape for an unavailable review backend (per-tree, never all backends); `summary` renders the whole loop state statelessly (gate result · per-backend verdicts · red-proofs · degrades) — no ledger, no rounds, nothing remembered. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
-| `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
+| `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — makes the commit capture the whole current working tree, so «verified» and «about to be committed» are the same bytes (the receipt itself has a stated residual — see the mode doc). FIRST it refuses an **INDEX that lags the verified working tree** (the gates and the fingerprint describe the WORKING tree while `git commit` takes the INDEX alone, and the fingerprint cannot tell them apart — so a lagging index used to ship a strict subset of what was verified): unstaged tracked paths or reviewable untracked-not-ignored paths, named up to a bounded cap with the remainder stated, a dirty tracked **submodule** named separately with its own recovery, and fail-closed on an undecidable probe. This deliberately blocks a partial commit. Then it binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
 | `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (the sandbox-lane live recipe, or the worktrees-dir hand-apply-first grant advice) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit worktrees` | any time | **parallel feature worktrees** — run several features in DIFFERENT agent sessions on one repo, zero interference on working-tree files (the ONE exception is the dependency cache, below): `provision <slug> --plan <file>` creates a sibling git worktree on branch `aw/<slug>` and populates it (registry-derived footprint copy-if-missing — a tracked file is never overwritten; EXACTLY ONE seeded feature plan; the `handoff-<slug>.md` record from minute zero; `node_modules` symlinked where the link stays ignored — a shared MUTABLE dependency cache: writes through it hit MAIN's node_modules; for isolation run the printed isolated-install command (`--install` only PRINTS it; on `--resume` run the printed unlink-first recovery first); absolute root-pinned gate commands rebased on untracked copies only, and only while their bytes equal the MAIN source or its rebased form — user-modified copies stay untouched); `list` is read-only (slug, branch, base, dirty, handoff); `land <slug> --prepare` locks the common git dir, fail-closes on divergence or incomplete satellite state, transfers the complete accepted satellite diff onto a CLEAN main, runs sync plus the declared gates, and reports HEAD/TRANSFER/PREPARED OIDs — the commit ALWAYS stays a dialogue ask; `cleanup <slug>` takes the same lock and removes a LANDED worktree only after live landed-verification against main HEAD, while `--abandon` is the ONE destructive arm (destroys unlanded work; **no preview step** on any writer). The parent dir is the `docs/ai/worktrees.json` `parentDir` setting (default: the repo's sibling parent); an unwritable parent degrades to printed maintainer-pasted commands, and the one-time host consent that makes it promptless surfaces via `recommendations`. Never commits, never pushes, never runs a subscription CLI. |

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: '3.12.0'
+  version: '3.13.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "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/commit-guard.md

@@ -4,16 +4,23 @@ The **read-only pre-commit guard** (strip-the-kit D10) — the last line of the
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/commit-guard.mjs --check [--cwd <dir>]` — it refuses, each with a named recovery, on:
 
-1. no completed final record for the CURRENT fingerprint (the tree moved after the final run — any edit re-stales it);
-2. a RED latest attempt (a dead green never revives — the latest attempt at a fingerprint is authoritative);
-3. fingerprint before ≠ after on the receipt (the tree moved UNDER the final run);
-4. a LATER `final-start` whose attempt never completed (interrupted run / failed receipt append — an attempt of unknown outcome never lets an earlier green stand);
-5. declaration content drift (the current `docs/ai/gates.json` {id, cmd} array no longer matches the receipt's recorded one);
-6. evidence-hash drift (the store's canonical red-proof/degrade serializations moved under the receipt) or lcov drift (the consumed file's sha moved or vanished);
-7. unsatisfied review obligations — the SAME normative decision `review-state --check` computes (configured recipe backends, ship-class-only on the latest normal receipt, veto, the explicit degrade escape), recomputed over a SANITIZED env: the guard resolves FIXED git-dir paths for its own reads and ignores `AW_REVIEW_RECEIPTS`/`AW_CORE_EVIDENCE` (producer test seams are never guard inputs — a forged out-of-repo store never satisfies).
+1. **an INDEX that lags the verified working tree** — the gates and the fingerprint both describe the WORKING tree, while `git commit` builds the commit from the INDEX alone, and the fingerprint domain is identical whether a hunk sits staged or unstaged (staging a lone tracked modification does not even move it). So this arm runs FIRST, before the fingerprint is computed: it refuses when the working tree holds anything the index does not — tracked paths differing between index and worktree, or reviewable untracked-not-ignored paths (the SAME never-committable stat filter the fingerprint applies; ignored paths never refuse). An index entry carrying **skip-worktree** or **assume-unchanged** is invisible to `git diff`, so those entries are compared DIRECTLY against the worktree (type, symlink target, executable bit where `core.fileMode` says so, and the blob oid through git's own clean filters) — a de-materialised skip-worktree path is an ordinary sparse checkout and never refuses, while a missing assume-unchanged path does. The submodule probe forces `--ignore-submodules=none`, so `diff.ignoreSubmodules` / `submodule.<name>.ignore` cannot erase a dirty submodule from the comparison. Offending paths are named in THREE categories — plain lagging paths, paths held back by an index bit, and submodules — because their recoveries differ; ONE shared cap spans all of them, each category reserves a slot so no clause is ever nameless, the remainder is stated once, and every path is rendered as one escaped line. Recovery is ONE ordered sequence, and `git add -A` alone is NOT it: a bit-carrying entry must have its `skip-worktree` / `assume-unchanged` bit cleared FIRST (scoped to the paths the refusal names — never to everything `git ls-files -v` reports, which includes de-materialised sparse paths whose deletions would then be staged), then `git add -A`, then re-run `run-gates --final` at its RESOLVED path beside this tool, then commit the WHOLE tree. The listed paths are capped, so the loop is the completion signal: re-run the guard until it names none. A tracked **submodule** the index cannot prove current is named separately with its own recovery — commit or clean inside the submodule and stage the gitlink — because a root-level `git add -A` cannot capture a submodule's internal worktree changes. A submodule whose gitlink itself carries one of those index bits is **not probed at all**: it lags by construction. That is a deliberate REDUCTION — three consecutive review rounds each found a new way for a nested probe to answer "clean" wrongly (inherited superproject `GIT_*`, status config blindness, the submodule's OWN flagged entries, a symlink standing in for the directory) — and it stays a CONVERGING refusal, since clearing the bit is a recovery the guard prints and then falls silent on. An UNflagged submodule is judged by the ordinary probe exactly as before. **Fail-closed:** an undecidable git probe refuses with its own named cause, never a silent pass;
+2. no completed final record for the CURRENT fingerprint (the tree moved after the final run — any edit re-stales it);
+3. a RED latest attempt (a dead green never revives — the latest attempt at a fingerprint is authoritative);
+4. fingerprint before ≠ after on the receipt (the tree moved UNDER the final run);
+5. a LATER `final-start` whose attempt never completed (interrupted run / failed receipt append — an attempt of unknown outcome never lets an earlier green stand);
+6. declaration content drift (the current `docs/ai/gates.json` {id, cmd} array no longer matches the receipt's recorded one);
+7. evidence-hash drift (the store's canonical red-proof/degrade serializations moved under the receipt) or lcov drift (the consumed file's sha moved or vanished);
+8. unsatisfied review obligations — the SAME normative decision `review-state --check` computes (configured recipe backends, ship-class-only on the latest normal receipt, veto, the explicit degrade escape), recomputed over a SANITIZED env: the guard resolves FIXED git-dir paths for its own reads and ignores `AW_REVIEW_RECEIPTS`/`AW_CORE_EVIDENCE` (producer test seams are never guard inputs — a forged out-of-repo store never satisfies).
 
 **Wiring:** this repo's dogfood rides `scripts/install-git-hooks.mjs`; a consumer install is a consented surface (init/recommendations) — the hook INSTALLER resolves the installed kit location at install time and writes the RESOLVED invocation into the hook it places (no runtime guessing). The final-run ordering that keeps the guard green is D13: stage everything FIRST → run the reviews on the staged tree → `run-gates --final` → commit immediately (any index/worktree mutation after the final run re-stales the receipt).
 
+**The deliberate partial commit is BLOCKED — stated, accepted.** Refusal 1 means staging a subset on purpose no longer commits: a pathspec commit (`git commit --only <path>`, `git commit <path>`) hands the hook a temporary index carrying less than the verified tree, and that is exactly the capture blindness this arm closes. No opt-out flag exists, deliberately — the guard's whole claim is that the committed bytes ARE the verified bytes, and a flag that suspends it would suspend the claim. An intentional partial commit stays `--no-verify` territory.
+
+**Boundary — what «the commit captures the tree» means for submodules.** The guard proves the SUPERPROJECT commit captures the SUPERPROJECT working tree. A superproject commit stores a submodule as a gitlink OID and never captures its file content — that content is the submodule's own commit boundary. The dirty-submodule refusal is therefore a best-effort COURTESY beyond the guard's boundary, and its completeness is bounded by what the submodule itself reports: a file held behind a `skip-worktree` / `assume-unchanged` bit in the SUBMODULE's own index is invisible to the submodule's status and so to this refusal. Deepening the nested probe was tried and abandoned — three consecutive review rounds each produced a new way for it to answer wrongly — so the honest contract is the boundary, not a completeness claim. Tracked as its own class.
+
+**Stated residual — the fingerprint can still be blinded by config.** Refusal 1 makes the COMMIT capture the whole current working tree. It does not make the RECEIPT unforgeable: `computeFingerprintPayload` still runs its diffs without `--ignore-submodules=none`, so under `diff.ignoreSubmodules=all` a submodule can be changed and its gitlink staged AFTER a green `--final` while the fingerprint stays put, and the stale receipt is reused. That is a receipt-collision defect, not an under-capture one — no commit ships less than the working tree because of it — and closing it means moving the node payload and both bash twins together (the AD-044 lockstep). Tracked as its own class.
+
 **Human residual (stated, accepted):** `git commit --no-verify` bypasses any pre-commit hook — a self-discipline mechanism, not a security boundary.
 
 **Invariants:** read-only · re-runs nothing · fixed git-dir reads (env overrides ignored) · exit 0 pass / 1 refused (reason + recovery named) / 2 usage.

package/tools/commands.mjs

@@ -222,7 +222,7 @@ const CATALOG = [
     invocation: invocationOf('commit-guard'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'The read-only pre-commit guard: binds the LATEST completed run-gates --final receipt to the CURRENT tree — refusing on any fingerprint, declaration, evidence-hash, or lcov drift, a dangling later attempt, or unsatisfied review obligations; re-runs no gate or test.',
+    oneLine: 'The read-only pre-commit guard: FIRST refuses an INDEX that lags the working tree — so the commit cannot ship less than was verified, which deliberately blocks a partial commit (--no-verify stays the residual) — then binds the LATEST completed run-gates --final receipt to the CURRENT tree, refusing on any fingerprint, declaration, evidence-hash, or lcov drift, a dangling later attempt, or unsatisfied review obligations; re-runs no gate or test.',
   },
   {
     key: 'doc-parity',

package/tools/commit-guard.mjs

@@ -2,6 +2,15 @@
 // commit-guard.mjs — the read-only pre-commit guard (strip-the-kit 2.5, D10). It re-runs NO
 // gate/test subprocess: the heavy D3(b)/(c)/(d) verification lives in `run-gates --final`, whose
 // receipt this guard binds. `--check`:
+//   0. refuses an INDEX that lags the verified working tree — FIRST, before the fingerprint is
+//      computed. The gates and the fingerprint describe the WORKING tree while `git commit` builds
+//      the commit from the INDEX alone, and the fingerprint domain is identical either way, so
+//      without this arm a lagging index ships a strict SUBSET of what was verified. Refuses on
+//      tracked paths differing index↔worktree or reviewable untracked-not-ignored paths (the same
+//      never-committable filter the fingerprint applies; ignored paths never refuse), naming them
+//      up to INDEX_LAG_PATH_CAP with the remainder stated. A dirty tracked SUBMODULE is named
+//      separately with its own recovery. Fail-closed on an undecidable probe. This BLOCKS the
+//      deliberate partial commit by design — `--no-verify` is the stated residual, not a flag;
 //   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing);
 //   2. reads the LATEST completed final-run record from the core-evidence store (only the latest
 //      attempt at a fingerprint is authoritative — a green receipt is DEAD once a later attempt at
@@ -18,11 +27,11 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { computeTreeFingerprint, buildState, decideCheck } from './review-state.mjs';
-import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization } from './core-evidence.mjs';
+import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
+import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization, computeWorkingState } from './core-evidence.mjs';
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 
@@ -44,10 +53,130 @@ export const resolveGitHooksPath = (projectDir) => {
   return line == null ? null : resolve(projectDir, line);
 };
 
+// How many offending paths the index-lag refusal names before it states a remainder count: enough
+// to act on, bounded so a wide lag cannot bury a pre-commit hook's output.
+export const INDEX_LAG_PATH_CAP = 10;
+
+// The recovery must name the run-gates the CONSUMER actually has. A repo-relative literal is only
+// correct inside this monorepo; every installed deployment keeps the tool beside this file. Shell-
+// quoted, because an install path carrying a space or a metacharacter would otherwise render an
+// instruction that is unrunnable at best and dangerous to paste at worst.
+const FINAL_RUN_TOOL = shellQuoteArg(fileURLToPath(new URL('./run-gates.mjs', import.meta.url)));
+
+// ONE budget across every named category — a per-category cap would print 2× the stated number.
+const renderBudgeted = (paths, budget) => ({
+  text: paths.slice(0, Math.max(budget, 0)).map(quoteReportName).join(', '),
+  used: Math.min(paths.length, Math.max(budget, 0)),
+});
+
+// The ONE ordered recovery plan — text and executable `argv` built from the SAME structure, so a
+// test can run exactly what the operator is shown instead of reconstructing its own commands.
+// Order matters: the submodule step first (staging and re-running --final before it would stale the
+// fresh receipt at once), then the index bits, because `git add -A` CANNOT restage a skip-worktree
+// or assume-unchanged entry — printing it alone is a recovery that silently does nothing. The two
+// bits get SEPARATE commands: one `update-index` invocation carrying both flags applies only one.
+// The text points at `git ls-files -v` rather than pasting names — the displayed list is capped,
+// and a name safe to display is not automatically safe to paste into a shell.
+export const buildIndexLagRecovery = (state) => {
+  const flags = state.flaggedPaths ?? [];
+  const steps = [];
+  if (state.unstagedSubmodulePaths.length > 0) {
+    steps.push({ text: 'commit or clean INSIDE every dirty submodule named above and stage its gitlink — a root-level git add -A cannot reach a submodule\'s own worktree' });
+  }
+  for (const [bit, key] of [['--no-skip-worktree', 'skipWorktree'], ['--no-assume-unchanged', 'assumeUnchanged']]) {
+    const affected = flags.filter((flag) => flag[key]);
+    if (affected.length === 0) continue;
+    // Scoped to the LAGGING paths only, never to `git ls-files -v`: that set also holds every
+    // de-materialised sparse-checkout entry, and clearing THEIR bit before `git add -A` would stage
+    // their deletions. The cap is handled by iteration, not by a wider enumeration. The executable
+    // form is offered ONLY when every affected name survives a byte round-trip — a lossily decoded
+    // name would address a DIFFERENT path, so there the text stands alone and says so.
+    const exact = affected.every((flag) => flag.exactName);
+    steps.push({
+      text: `clear the ${bit.slice(5)} bit on the bit-carrying path(s) named above — it is what makes git add -A a no-op on them — with git update-index ${bit} -- <path>, for those paths ONLY (never every entry git ls-files -v reports: that set includes de-materialised sparse paths whose deletions would then be staged)${exact ? '' : '; at least one of these names carries bytes that do not decode cleanly, so the name shown above is LOSSY and this refusal cannot give you a runnable command for it — its record is visible in git ls-files -v -z, and clearing that one is a by-hand step'}`,
+      ...(exact ? { argv: ['update-index', bit, '--', ...affected.map((flag) => flag.rel)] } : {}),
+    });
+  }
+  steps.push({ text: 'run git add -A from the work-tree root', argv: ['add', '-A'] });
+  steps.push({ text: `re-run node ${FINAL_RUN_TOOL} --final` });
+  steps.push({ text: 'commit the WHOLE tree' });
+  return steps;
+};
+
+// decideIndexLag(state) → a refusal, or null when the index already carries the verified tree.
+// The gates and the fingerprint both describe the WORKING tree; `git commit` takes the INDEX, and
+// the fingerprint domain cannot tell the two apart — so without this arm a lagging index ships a
+// strict subset of what was verified (it did, on 2026-07-25). FAIL-CLOSED on an undecidable probe:
+// the guard's whole claim is that the committed bytes ARE the verified bytes, and it cannot make
+// that claim about a tree it failed to read.
+export const decideIndexLag = (state) => {
+  if (state == null) {
+    return { code: 1, lines: ['commit-guard: REFUSED — the index/worktree comparison could not be decided (a git probe failed); re-run inside the work tree and inspect `git status` by hand before committing'] };
+  }
+  // THREE categories, because they take DIFFERENT recoveries. A bit-carrying path folded into the
+  // plain list would be un-actionable: its clause is the only one whose recovery is not `git add -A`,
+  // and on cap overflow the plain paths could hide every one of them.
+  const flaggedSet = new Set((state.flaggedPaths ?? []).map((flag) => flag.rel));
+  const all = [...state.unstagedPaths, ...state.untrackedPaths];
+  const plain = all.filter((rel) => !flaggedSet.has(rel));
+  const bitCarrying = all.filter((rel) => flaggedSet.has(rel));
+  const submodules = state.unstagedSubmodulePaths;
+  const total = plain.length + bitCarrying.length + submodules.length;
+  if (total === 0) return null;
+  // Every non-empty category reserves a slot before the budget is spent — a clause that names no
+  // path cannot deliver the recovery it exists to state.
+  const groups = [plain, bitCarrying, submodules];
+  const rendered = [];
+  let spent = 0;
+  groups.forEach((group, index) => {
+    if (group.length === 0) {
+      rendered[index] = { text: '', used: 0 };
+      return;
+    }
+    const stillToReserve = groups.slice(index + 1).filter((later) => later.length > 0).length;
+    rendered[index] = renderBudgeted(group, INDEX_LAG_PATH_CAP - spent - stillToReserve);
+    spent += rendered[index].used;
+  });
+  const hidden = total - spent;
+  const remainder = hidden > 0 ? `, plus ${hidden} further path(s) not listed` : '';
+  const clauses = [];
+  if (plain.length > 0) {
+    clauses.push(`paths the index does not carry: ${rendered[0].text}`);
+  }
+  if (bitCarrying.length > 0) {
+    clauses.push(`path(s) held back by a skip-worktree / assume-unchanged index bit: ${rendered[1].text}`);
+  }
+  if (submodules.length > 0) {
+    clauses.push(`tracked submodule(s) not proven current: ${rendered[2].text}`);
+  }
+  // ONE ordered recovery, and every step must actually converge. The submodule step comes FIRST:
+  // staging and re-running --final before it would stale the fresh receipt at once. The index-bit
+  // step comes next, because `git add -A` CANNOT restage a skip-worktree / assume-unchanged entry —
+  // printing it alone would be a recovery that silently does nothing. It deliberately points at
+  // `git ls-files -v` rather than pasting names: the list above is capped, and a filename safe to
+  // display is not automatically safe to paste into a shell.
+  const steps = buildIndexLagRecovery(state);
+  // The iterate-until-silent hint must also fire when the CAP hid work — otherwise a truncated
+  // list of submodules with no index bits would send the operator to --final and commit while
+  // unnamed ones are still unhandled.
+  const converge = hidden > 0 || (state.flaggedPaths ?? []).length > 0
+    ? ' The listed paths are capped: re-run this guard after each pass and it names the next batch, until it names none — that is the completion signal.'
+    : '';
+  return {
+    code: 1,
+    lines: [`commit-guard: REFUSED — the index does NOT carry the whole CURRENT working tree, so this commit would leave part of it behind: ${clauses.join('; ')}${remainder}. To recover, in order: ${steps.map((step, i) => `(${i + 1}) ${step.text}`).join('; ')}. An intentional partial commit stays git commit --no-verify.${converge}`],
+  };
+};
+
 // runGuard({ cwd, env }) → { code, lines }. Every refusal names its recovery.
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
+  // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
+  // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
+  // would send the operator down a recovery they must redo.
+  const indexLag = decideIndexLag(computeWorkingState(cwd));
+  if (indexLag !== null) return indexLag;
   const fingerprint = computeTreeFingerprint(cwd);
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE
   // in the committing shell must never redirect the LAST line of defense to a forged artifact
@@ -128,11 +257,13 @@ const HELP = `commit-guard — the read-only pre-commit guard (agent-workflow fa
 Usage:
   node commit-guard.mjs --check [--cwd <dir>]
 
-Re-runs NOTHING: recomputes the current tree fingerprint and binds the LATEST completed
-run-gates --final receipt — refusing on { no receipt for this tree · a red latest attempt ·
-before≠after · declaration content drift · evidence-hash drift · lcov drift · unsatisfied review
-obligations (the review-state decision) }. Wire it into pre-commit; \`git commit --no-verify\`
-stays the stated residual (self-discipline, not a security boundary).
+Re-runs NOTHING: refuses an INDEX that lags the verified working tree (FIRST — unstaged tracked
+paths, reviewable untracked paths, or a dirty tracked submodule, each named with its recovery;
+this deliberately blocks a partial commit), then recomputes the current tree fingerprint and binds
+the LATEST completed run-gates --final receipt — refusing on { no receipt for this tree · a red
+latest attempt · before≠after · declaration content drift · evidence-hash drift · lcov drift ·
+unsatisfied review obligations (the review-state decision) }. Wire it into pre-commit;
+\`git commit --no-verify\` stays the stated residual (self-discipline, not a security boundary).
 
 Exit codes: 0 pass; 1 refused (reason named); 2 usage.`;
 

package/tools/core-evidence.mjs

@@ -152,29 +152,240 @@ export const computeTreeFingerprint = (cwd, fsx) => {
   return payload == null ? null : createHash('sha256').update(payload).digest('hex');
 };
 
-// Clean = nothing staged, nothing unstaged, no REVIEWABLE untracked-not-ignored paths — the same
-// never-committable filter as the fingerprint, so the two can never disagree about a masks-only
-// tree. Anchored at the work-tree ROOT (ls-files is cwd-scoped). Null when not decidable.
-export const isTreeClean = (cwd, { lstat = lstatSync } = {}) => {
-  const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
-  if (top == null) return null;
-  const staged = gitRaw(['diff', '--cached', '--quiet'], top);
-  const unstaged = gitRaw(['diff', '--quiet'], top);
-  if (staged.error || unstaged.error || staged.status > 1 || unstaged.status > 1) return null;
-  const untrackedZ = gitBuf(['ls-files', '--others', '--exclude-standard', '-z'], top);
-  if (untrackedZ == null) return null;
-  const reviewable = untrackedZ
-    .toString('utf8')
-    .split('\0')
-    .filter(Boolean)
-    .filter((rel) => {
+// The index↔worktree split the fingerprint deliberately CANNOT see: the payload above concatenates
+// the staged and unstaged diffs, so against an otherwise-empty index a hunk moving into the index
+// leaves it byte-identical — while `git commit` builds the commit from the INDEX alone. This is the
+// ONE computation of that split; isTreeClean and the commit guard's index-lag arm both read it, so
+// they can never disagree about what "the index carries the verified tree" means. Submodule paths
+// are separated because a root-level `git add -A` cannot reach a submodule's own worktree, so they
+// need their own recovery. Anchored at the work-tree ROOT (ls-files is cwd-scoped); null when not
+// decidable — every consumer treats that as fail-closed, never as clean.
+const LS_FILES_TAG_SKIP_WORKTREE = 'S';
+const GITLINK_MODE = '160000';
+const SYMLINK_MODE = '120000';
+const EXECUTABLE_MODE = '100755';
+const OWNER_EXECUTE_BIT = 0o100;
+// `ls-files -v` lowercases the tag for assume-unchanged; skip-worktree is `S`, and an entry
+// carrying BOTH bits prints lowercase `s` (live-pinned by test). The skip test is therefore
+// case-INSENSITIVE — a case-sensitive one would lose skip-worktree on such an entry and turn a
+// legitimate sparse checkout into an endless refusal.
+const isAssumeUnchangedTag = (tag) => tag >= 'a' && tag <= 'z';
+const isSkipWorktreeTag = (tag) => tag.toUpperCase() === LS_FILES_TAG_SKIP_WORKTREE;
+
+// `git diff` SKIPS index entries carrying skip-worktree or assume-unchanged, so such a path can
+// hold worktree bytes the gates read while `git commit` takes the stale INDEX blob — the same
+// capture blindness one layer down, and invisible to the plain probe. Those entries are therefore
+// compared DIRECTLY against the worktree. A MISSING skip-worktree path is an ordinary sparse
+// checkout and never a lag; a missing assume-unchanged path is one. Gitlinks belong to the
+// submodule lane. Any probe that cannot answer counts the path as lagging (fail-safe).
+const flaggedIndexLag = (top, runGit, lstat, readlink) => {
+  const buf = (args) => {
+    const r = runGit(args, top);
+    return r.error || r.status !== 0 ? null : r.stdout;
+  };
+  const splitZ = (b) => b.toString('utf8').split('\0').filter(Boolean);
+  // Git emits raw path BYTES. Decoding to UTF-8 first turns a name carrying invalid bytes into a
+  // DIFFERENT path, whose lstat then answers ENOENT — which for a skip-worktree entry reads as a
+  // de-materialised sparse path and lets a stale index walk through. So each record keeps its
+  // original slice and a name that does not survive a byte round-trip is lagging by construction.
+  const splitZBytes = (b) => {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < b.length; i += 1) {
+      if (b[i] !== 0) continue;
+      if (i > start) out.push(b.subarray(start, i));
+      start = i + 1;
+    }
+    if (start < b.length) out.push(b.subarray(start));
+    return out;
+  };
+  const decodesExactly = (slice) => Buffer.from(slice.toString('utf8'), 'utf8').equals(slice);
+  const taggedZ = buf(['ls-files', '-v', '-z']);
+  if (taggedZ == null) return null;
+  // The two bits are INDEPENDENT — an entry can carry both (which is what lowercases the `S`), so
+  // they travel as a pair and the recovery clears whichever are actually set.
+  const flagged = splitZBytes(taggedZ)
+    .map((record) => {
+      const tag = record.subarray(0, 1).toString('utf8');
+      const pathBytes = record.subarray(2);
+      return {
+        rel: pathBytes.toString('utf8'),
+        pathBytes,
+        exactName: decodesExactly(pathBytes),
+        skipWorktree: isSkipWorktreeTag(tag),
+        assumeUnchanged: isAssumeUnchangedTag(tag),
+      };
+    })
+    .filter(({ skipWorktree, assumeUnchanged }) => skipWorktree || assumeUnchanged);
+  if (flagged.length === 0) return { paths: [], submodules: [], flagged: [] };
+  const stagedZ = buf(['ls-files', '-s', '-z']);
+  if (stagedZ == null) return null;
+  const entries = new Map();
+  for (const line of splitZ(stagedZ)) {
+    const tab = line.indexOf('\t');
+    if (tab === -1) continue;
+    const [mode, oid] = line.slice(0, tab).split(' ');
+    entries.set(line.slice(tab + 1), { mode, oid });
+  }
+  // `git diff` honours core.fileMode; mirroring it keeps a false-mode host (WSL, network mounts)
+  // from reading every executable bit as a lag. Exit 1 is the only "unset" (git's default is true);
+  // any other failure leaves the comparison undecidable rather than guessing.
+  const boolConfig = (key) => {
+    const r = runGit(['config', '--type=bool', '--get', key], top);
+    if (r.error || (r.status !== 0 && r.status !== 1)) return null; // undecidable — never guessed
+    return r.status === 1 || r.stdout.toString('utf8').trim() !== 'false'; // exit 1 = unset = git's default true
+  };
+  const honoursFileMode = boolConfig('core.fileMode');
+  // On a host without symlink support git materialises a symlink as a REGULAR FILE holding the
+  // target bytes; demanding a real link there would refuse forever.
+  const materialisesSymlinks = boolConfig('core.symlinks');
+  if (honoursFileMode === null || materialisesSymlinks === null) return null;
+  const lagging = [];
+  const laggingSubmodules = [];
+  const laggingFlags = [];
+  for (const { rel, pathBytes, exactName, skipWorktree, assumeUnchanged } of flagged) {
+    const entry = entries.get(rel);
+    if (entry === undefined) continue;
+    const isGitlink = entry.mode === GITLINK_MODE;
+    // Every path this loop reports needs its index bits cleared before ANY staging command can
+    // pick it up — `git add -A` alone is a recovery that silently does nothing here.
+    const lag = () => {
+      (isGitlink ? laggingSubmodules : lagging).push(rel);
+      laggingFlags.push({ rel, skipWorktree, assumeUnchanged, exactName });
+    };
+    // Probed by RAW BYTES, never by the decoded name: a lossy decode addresses a DIFFERENT path,
+    // and answering ENOENT for it would either wave a stale index through or — worse — call a
+    // legitimately absent sparse entry "lagging", whose prescribed bit-clear plus `git add -A`
+    // would then stage its DELETION.
+    const absPath = Buffer.concat([Buffer.from(top), Buffer.from(sep), pathBytes]);
+    let stat = null;
+    let absent = false;
+    try {
+      stat = lstat(absPath);
+    } catch (err) {
+      // ONLY a genuine absence is the sparse-checkout case; EACCES / EIO leave the path unproven,
+      // and an unproven path can never be waved through as "not materialised".
+      absent = err != null && err.code === 'ENOENT';
+    }
+    if (stat === null) {
+      if (!absent || !skipWorktree) lag();
+      continue;
+    }
+    if (!exactName) {
+      // Materialised, but the name cannot be addressed through an argv string, so it can never be
+      // PROVEN current — fail-safe. Absence was already decided above, on the real bytes.
+      lag();
+      continue;
+    }
+    // A flagged GITLINK is hidden from `git diff` too, so the submodule lane would never see it —
+    // and it is deliberately NOT proven current here. Three consecutive review rounds each found a
+    // new way for a nested probe to answer "clean" wrongly (inherited superproject GIT_*, status
+    // config blindness, the submodule's OWN flagged entries, a symlink standing in for the
+    // directory). The set was not shrinking, so the verdict is REDUCTION rather than another patch:
+    // a materialised flagged gitlink LAGS by construction. It is a refusal, never an endless one —
+    // the printed recovery (clear the bit, then git add -A) converges, and an UNflagged submodule
+    // is unaffected because the ordinary --ignore-submodules=none probe still judges it.
+    if (isGitlink) {
+      lag();
+      continue;
+    }
+    if (entry.mode === SYMLINK_MODE && !stat.isSymbolicLink() && !materialisesSymlinks) {
+      // The placeholder file's RAW bytes are the stored target — no filters ever apply to a link.
+      const placeholder = runGit(['hash-object', '--no-filters', '-t', 'blob', '--', join(top, rel)], top);
+      if (placeholder.error || placeholder.status !== 0 || placeholder.stdout.toString('utf8').trim() !== entry.oid) lag();
+      continue;
+    }
+    if (entry.mode === SYMLINK_MODE || stat.isSymbolicLink()) {
+      if (entry.mode !== SYMLINK_MODE || !stat.isSymbolicLink()) {
+        lag();
+        continue;
+      }
+      let target = null;
+      try {
+        target = readlink(join(top, rel));
+      } catch {
+        target = null;
+      }
+      if (target === null) {
+        lag(); // an unreadable link can never be proven current — fail-safe
+        continue;
+      }
+      const hashed = runGit(['hash-object', '-t', 'blob', '--stdin'], top, target);
+      if (hashed.error || hashed.status !== 0 || hashed.stdout.toString('utf8').trim() !== entry.oid) lag();
+      continue;
+    }
+    if (!stat.isFile()) {
+      lag();
+      continue;
+    }
+    // Git canonicalises the executable mode on the OWNER bit alone — a file with only group/other
+    // exec set is still `100644` to git, so testing 0o111 would call a stale index current.
+    if (honoursFileMode && (entry.mode === EXECUTABLE_MODE) !== ((stat.mode & OWNER_EXECUTE_BIT) !== 0)) {
+      lag();
+      continue;
+    }
+    const hashed = runGit(['hash-object', '--path', rel, '--', join(top, rel)], top);
+    if (hashed.error || hashed.status !== 0 || hashed.stdout.toString('utf8').trim() !== entry.oid) lag();
+  }
+  return { paths: lagging, submodules: laggingSubmodules, flagged: laggingFlags };
+};
+
+export const computeWorkingState = (cwd, { lstat = lstatSync, readlink = readlinkSync, runGit = null } = {}) => {
+  const run = runGit ?? ((args, dir, input, env) => spawnSync('git', args, { cwd: dir, input, env: env ?? process.env, maxBuffer: GIT_MAX_BUFFER, windowsHide: true }));
+  const topRun = run(['rev-parse', '--show-toplevel'], cwd);
+  if (topRun.error || topRun.status !== 0) return null;
+  const top = topRun.stdout.toString('utf8').replace(/\r?\n$/, '');
+  // `--ignore-submodules=none` on the staged probe too: a config-hidden STAGED gitlink would
+  // otherwise make stagedDirty false, and isTreeClean would call such a tree clean.
+  const staged = run(['diff', '--cached', '--quiet', '--ignore-submodules=none'], top);
+  // ONLY 0 or 1 is a usable answer: a signal-killed probe reports status null, which the old
+  // `> 1` guard let through as "nothing staged" — a fail-OPEN the whole arm cannot afford.
+  if (staged.error || (staged.status !== 0 && staged.status !== 1)) return null;
+  const buf = (args) => {
+    const r = run(args, top);
+    return r.error || r.status !== 0 ? null : r.stdout;
+  };
+  // The FULL probe forces submodules back in: diff.ignoreSubmodules / submodule.<n>.ignore would
+  // otherwise erase a dirty submodule from the comparison entirely.
+  const changedZ = buf(['diff', '--name-only', '-z', '--ignore-submodules=none']);
+  const plainZ = buf(['diff', '--name-only', '-z', '--ignore-submodules=all']);
+  const untrackedZ = buf(['ls-files', '--others', '--exclude-standard', '-z']);
+  if (changedZ == null || plainZ == null || untrackedZ == null) return null;
+  const split = (b) => b.toString('utf8').split('\0').filter(Boolean);
+  const changed = split(changedZ);
+  const plain = new Set(split(plainZ));
+  const flagged = flaggedIndexLag(top, run, lstat, readlink);
+  if (flagged == null) return null;
+  const unstaged = changed.filter((rel) => plain.has(rel));
+  const submodules = changed.filter((rel) => !plain.has(rel));
+  return {
+    stagedDirty: staged.status === 1,
+    unstagedPaths: [...unstaged, ...flagged.paths.filter((rel) => !unstaged.includes(rel))],
+    unstagedSubmodulePaths: [...submodules, ...flagged.submodules.filter((rel) => !submodules.includes(rel))],
+    // Which lagging paths carry index bits, and which — `git add -A` cannot restage these at all.
+    flaggedPaths: flagged.flagged,
+    untrackedPaths: split(untrackedZ).filter((rel) => {
       try {
         return !isNeverCommittableStat(lstat(join(top, rel)));
       } catch {
         return true;
       }
-    });
-  return staged.status === 0 && unstaged.status === 0 && reviewable.length === 0;
+    }),
+  };
+};
+
+// Clean = nothing staged, nothing unstaged, no REVIEWABLE untracked-not-ignored paths — the same
+// never-committable filter as the fingerprint, so the two can never disagree about a masks-only
+// tree. Null when not decidable.
+export const isTreeClean = (cwd, fsx) => {
+  const state = computeWorkingState(cwd, fsx);
+  if (state == null) return null;
+  return (
+    !state.stagedDirty &&
+    state.unstagedPaths.length === 0 &&
+    state.unstagedSubmodulePaths.length === 0 &&
+    state.untrackedPaths.length === 0
+  );
 };
 
 // ── the review-receipt read path + attesting predicate (ONE home) ────────────────────────────────