@sabaiway/agent-workflow-kit 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,110 @@ 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.
 
+## 4.4.0 — the guard stops charging you for answers it already has (AD-082)
+
+**If the agent keeps asking you to approve its own `2>/dev/null`, this release is for you.** Two
+things changed, and neither refuses anything.
+
+**1. The ask now talks to the AGENT, not only to you.** Until now, when the guard stopped a read
+carrying a redirection it explained itself in *your* approval dialog — and the agent that composed the
+command never heard a word of it. So it composed the same shape again next turn. The ask now also
+carries a hint back to the agent naming the lane that would not have prompted at all. Nothing is
+blocked and nothing new is approved; if your host does not support the field, you get exactly the old
+behaviour. **You should see the same class of prompt arrive less often, not disappear** — the honest
+claim, stated because the alternative would be a promise this cannot keep.
+
+**2. Two lanes so several small questions stop becoming one composed shell.**
+
+- **`path-inventory.mjs` (new).** Does this exist, what type is it, how big, how many lines, what is
+  in that directory, what does this small config say — for any number of paths, in ONE call, promptless.
+  **A path that does not exist is a normal answer** (`exists:false`, exit 0), because "does either of
+  these exist" is a question whose interesting answer is "no", and a tool that errors on it sends you
+  straight back to writing a shell one-liner. Symlinks are reported by type and never followed;
+  binaries are reported, never decoded; every bound names itself instead of truncating quietly.
+- **`repo-search.mjs --paths-file`.** The pattern half already had a file lane; the TARGET half did
+  not, so a path containing a backtick or `$(` could not be searched without a prompt however you
+  quoted it. Now it can. Both lane files are excluded from the search itself, by real path.
+
+**What you must do to get the promptless part.** Re-run `/agent-workflow-kit velocity --kit-tools`.
+Allow rules are values already written into your `.claude/settings.json`; upgrading the kit does not
+edit them. The advisor now tells you exactly which entries you are missing.
+
+**Also in this release:** the guard's recovery advice is derived per tool (it used to name
+`--pattern-file` for every scanned tool, which was wrong the moment a second one existed), and it now
+names both possibilities — pass the byte out of band if it is part of an argument, drop it if it is a
+real redirect — because the guard cannot tell those apart and should not pretend to.
+
+**One consequence worth knowing about.** The guard's scanned-tool match is a substring match across
+the command, deliberately inclusive because an over-match only ever costs an extra prompt. Adding a
+second tool extends that: a command that merely MENTIONS `path-inventory.mjs` and carries a
+redirection now asks where it previously got no decision at all. That is the same licensed over-ask
+`repo-search.mjs` has had since 4.2.0, on one more path string.
+
+**One rule worth knowing if you pass paths to either tool.** A target must name exactly one thing:
+no empty value, no NUL byte, no `..` component (Node collapses it before the filesystem is consulted,
+so the tool could answer about a different file than you named). A trailing `/` or `/.` is not
+rejected — it asserts "this is a directory", exactly as it does to your shell. Awkward names are
+still supported: spaces at the edges, backticks, control bytes — that is what the file lanes carry.
+
+**Not in this release, deliberately.** A guard rung that DENIES instead of asking was designed,
+reviewed and withdrawn — for the second time — because a command substitution can embed an arbitrary
+command with no separator byte, so any such refusal can destroy work it never meant to touch. The
+guard still never denies.
+
+## 4.3.0 — the coverage gate no longer certifies evidence it cannot bind to your tree (AD-081)
+
+**Read this if you have ever run `coverage-check --check` on its own.** Until now it read whatever
+LCOV happened to be at the fixed path and gave you a verdict. Nothing tied that file to the tree it
+was judging.
+
+**The harmless direction is the one you may have already seen:** you add tests, re-run the checker
+alone, and it prints the *identical* failure list and the *identical* `lcov-sha256` — because the
+LCOV is produced by your `unit-tests` gate and nothing regenerated it.
+
+**The same mechanism prints a false PASS,** and that is why this shipped as a fix. Run the suite,
+append one executable line, re-run the checker alone: it certifies "every changed Node line is
+covered". LCOV carries no executability signal, so a line that did not exist when the suite ran has
+no `DA` entry and reads as *non-executable* — nothing to cover.
+
+**What changed: a coverage VERDICT is now an outcome of `run-gates --final`, and nowhere else.**
+That run already owns the artifact end to end — it deletes the LCOV before any gate starts, so inside
+it "this came from this tree" is a fact rather than a hope. It now mints a random nonce and records
+the attempt as a one-way commitment over `{nonce, tree fingerprint, base}`; the checker recomputes
+that commitment and refuses to certify without it. The commitment is also the only place your base
+commit is bound, so an identical dirty diff at a moved `HEAD` no longer looks like the same tree.
+
+**Three outcomes replace two — and your findings are unchanged:**
+
+- inside `--final` → the verdict, exactly as before;
+- anywhere else → `attested=no` and `NO VERDICT`, exit 0, with **every finding still printed**;
+- a context describing a different tree, or matching no recorded attempt → `REFUSED`, exit 1.
+
+**Uncovered lines still exit 1 and are still listed `file:line`.** Nothing that was red turns green;
+only the *attestation* is withdrawn where it was never earned — which is why this is a minor release.
+
+**Two more places where a green could hide:** the runner no longer trusts the checker's exit status,
+because that code is 0 both when it certifies and when it withholds — it now reads one anchored
+`attested=` line, so **a run that actually consumed an LCOV can no longer mint a green receipt
+without certifying it**. (A run that produced no LCOV at all still records a green receipt with
+`lcovSha256: null` and a loud `skipped-no-lcov`, exactly as before — that path is unchanged.) And a
+plain run prints the withheld verdict aloud instead of leaving a PASS row standing over a claim
+nobody made.
+
+**Stated honestly — what this does NOT cover.** Whoever runs both processes can still forge the store
+or the code; that is the same self-discipline posture the receipts have always had. And "the run owns
+the artifact" is exclusive **by convention over a fixed path, not enforced**: if something else writes
+that path while a `--final` is in flight — a second `run-gates`, a hand-run `--only unit-tests`, an
+orphaned test process — the verdict can still land on evidence this run did not produce. Closing that
+needs a per-attempt artifact path, which means your `unit-tests` gate cmd would have to reference
+`$AW_LCOV_FILE`; it is queued rather than rushed into a release, because this is verification code.
+Your base commit is likewise persisted nowhere, so `commit-guard` stays fingerprint-only.
+
+**What IS gone** is the false green that needs no second process and nobody trying: evidence that
+simply predates your edit. That is the case that was observed live, and it is pinned by a regression
+test that was watched failing before the fix existed.
+
+
 ## 4.2.0 — a search whose pattern contains `>` no longer has to ask (AD-080)
 
 **Read this if you have ever approved `grep -rn "=>" src`.** 4.1.0 explained why that prompt cannot

package/README.md

@@ -239,7 +239,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit sandbox-masks` | any time | **cosmetic exclude lane for sandbox device masks** — an OS sandbox (Claude Code) injects character-device masks into the work tree as untracked `git status` noise; the review domain already ignores them **by construction** (never-committable untracked classes — char/block devices, FIFOs, sockets — are excluded from the fingerprint, the assembled review payload, and the clean checks). This mode hides them from `git status` too: flagless = read-only probe (derives the CURRENT mask set from the unfiltered walk + lstat — never a frozen list — and revalidates fenced entries, loudly flagging one that became a real path); `--apply` = consent-gated FULL-BLOCK replace of its own fenced block in `git rev-parse --git-path info/exclude` (stale masks drop by construction; `--clear` always means REMOVE the block — it takes precedence over the derivation). Writes ONLY its fence — never `.gitignore`, never global config; symlinked/non-regular exclude paths and malformed fences fail closed. Watch note: a real file at an excluded path is silently skipped by bulk staging (`git add -A`/`git add .`) — delete the stale line first; the probe flags exactly this case. |
 | `/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 coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — **certifies coverage ONLY inside the `--final` run that owns the lcov** (ownership is exclusive by CONVENTION over the fixed path, not enforced — a concurrent writer to it is a stated residual, queued as LCOV-EXCLUSIVE-OWNERSHIP): an artifact on disk proves nothing about the tree it came from, so a standalone run prints its findings and states `attested=no` / `NO VERDICT` rather than a PASS (an lcov that predates an edit would otherwise certify a line the suite never executed). The runner passes a nonce whose one-way commitment over `{nonce, fingerprint, base}` is the `final-start.attempt` it recorded; a context describing another tree, or matching no recorded attempt, is a REFUSAL, never a verdict. Findings are unchanged — 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) — 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, the worktrees-dir hand-apply-first grant advice, or the agents hidden-mode reconcile follow-up) · 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. |

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "4.2.0",
+  "version": "4.4.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/hooks/gate-approve.mjs

@@ -45,6 +45,12 @@
 //   (d) everything else → NO decision: exit 0, no output — the normal permission flow proceeds
 //       unchanged. The hook NEVER emits `deny`.
 //
+// EVERY ASK ALSO CARRIES A CALLER-FACING HINT (`additionalContext`). The ask itself goes to the
+// HUMAN and its reason never reaches the caller that composed the command — so the guard knew the
+// right lane and could not say it, which is the one thing every withdrawn deny design was buying.
+// The hint is that channel without the refusal, and a host that ignores the field degrades to
+// silence, i.e. to the previous behaviour. See the note above `HINT_CORE`.
+//
 // WHY THERE IS NO DENY RUNG, AND WHY THE DIRECTION IS RETIRED (kit 4.0.0 built one, AD-078
 // removed it; the class was closed from the other side instead). The withdrawn rung refused a
 // seeded read-only command that provably DISCARDED its output, on the argument that such a refusal
@@ -272,7 +278,16 @@ export const matchSeededCorePrefix = (command) => {
 // review killed it: it would pull ANY unrelated `repo-search.mjs` into rung (b2), turning a
 // pre-existing NO decision into an ASK — a change to a decision path this release has no business
 // touching.
-export const SCANNED_TOOL_PATHS = Object.freeze(['agent-workflow-kit/tools/repo-search.mjs']);
+// The RECOVERY is per tool, not a constant. When repo-search was the only entry the reason named the
+// literal `--pattern-file`, and that was wrong the moment a second tool joined: wrong for a tool with
+// no such flag, and already incomplete for repo-search itself once its TARGET half gained a lane. An
+// ask whose named recovery does not exist is worse than an ask with no advice, so the advice is
+// derived from whichever tool matched.
+export const SCANNED_TOOL_LANES = Object.freeze({
+  'agent-workflow-kit/tools/repo-search.mjs': '--pattern-file / --paths-file',
+  'agent-workflow-kit/tools/path-inventory.mjs': '--paths-file',
+});
+export const SCANNED_TOOL_PATHS = Object.freeze(Object.keys(SCANNED_TOOL_LANES));
 
 // Quotes stripped and separators canonicalised, so a relative, absolute, quoted or Windows-separated
 // spelling all compare the same. SUBSTRING, not equality, and scanned across EVERY token rather than
@@ -282,10 +297,13 @@ export const SCANNED_TOOL_PATHS = Object.freeze(['agent-workflow-kit/tools/repo-
 // surface this exists to cover, while a spurious match merely over-asks — so inclusiveness wins.
 const canonicalToken = (token) => token.replace(/["']/gu, '').replace(/\\/gu, '/');
 
-export const matchScannedToolPrefix = (command) => {
+export const matchScannedToolPrefix = (command) => matchScannedTools(command)[0] ?? null;
+
+// ALL matches, not just the first. A command naming two scanned tools would otherwise be advised
+// about whichever happens to sit earlier in the registry, and the residual may belong to the other.
+export const matchScannedTools = (command) => {
   const tokens = tokenizeCommand(command).map(canonicalToken);
-  const hit = SCANNED_TOOL_PATHS.find((path) => tokens.some((token) => token.includes(path)));
-  return hit ?? null;
+  return SCANNED_TOOL_PATHS.filter((path) => tokens.some((token) => token.includes(path)));
 };
 
 // String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
@@ -381,6 +399,35 @@ export const isReadLaneCommand = (command) => {
   });
 };
 
+// ── the caller-facing hint (rides an ask; refuses nothing) ────────────────────────────
+//
+// WHY THIS EXISTS, AND WHY IT IS NOT A DENY. An ask is answered by the HUMAN: `permissionDecisionReason`
+// is context for THEIR dialog and never reaches the caller that composed the command. So for the whole
+// life of this guard it has known the right lane and had no way to say it — which is the single reason
+// every withdrawn deny design looked attractive, since a deny is refusal-shaped and does reach the
+// caller. `additionalContext` is the same channel without the refusal. Probed live on 2026-07-28 with
+// a throwaway hook: a distinct marker was delivered to the model on `allow`, on `ask`, AND on no
+// decision at all.
+// FAIL-SAFE BY CONSTRUCTION: a host that does not honour the field simply drops it, which is exactly
+// the behaviour that existed before — silence. Nothing is refused, so a hint that is wrong for a
+// particular command costs the caller a sentence, never their work. That is the property no deny
+// design could ever claim.
+export const HINT_CORE = 'agent-workflow: this read left the promptless lane — a plain read-only command with no redirection, no banner and no quotes stays inside it. If the byte is a decoration you do not need, drop it and re-issue; if it is ordinary text inside an argument, a search belongs in `repo-search.mjs` (`--pattern-file`), and several path questions (exists / size / line count / listing / small-file contents) are ONE `path-inventory.mjs` call. If the byte is a deliberate operator, keep it and confirm by hand.';
+
+// The hint must not GUESS which of the two causes produced the residual — the guard cannot tell a
+// byte that is ordinary text inside an argument from a real shell operator, and pretending otherwise
+// is the exact claim AD-079 closed. So it names BOTH recoveries and lets the caller pick: the one
+// that fits is always present, and the one that does not costs a clause.
+// The hint never tells the caller to delete an operator it cannot read the intent of: dropping a
+// real `> report.json` would change what the command DOES, and a guard that silently edits meaning is
+// the failure this whole area was built to avoid. It names the out-of-band lane, notes that these
+// tools already bound and print their own result (so a decoration is usually redundant), and leaves a
+// deliberate operator to the human confirmation that already exists.
+const hintForScannedTools = (tools) => {
+  const lanes = tools.map((tool) => `\`${tool}\` → ${SCANNED_TOOL_LANES[tool]}`).join('; ');
+  return `agent-workflow: the residual guard stopped this. If the byte is part of an ARGUMENT, pass it out of band — ${lanes} — and its bytes then never enter the command string, so this guard has nothing to scan (whether the clean form still prompts depends on your settings allow rules, which this hook does not read). If the byte is a decoration you do not need, drop it: these tools bound and print their own result. If it is a deliberate operator, keep it and confirm by hand — that is what the prompt is for.`;
+};
+
 // ── the decision ladder (pure core) ───────────────────────────────────────────────────
 
 export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gates, readLaneOn = false }) => {
@@ -404,19 +451,23 @@ export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gate
       return {
         permissionDecision: DECISION_ASK,
         permissionDecisionReason: `agent-workflow residual guard: read-only-seeded "${corePrefix}" carries ${residualClasses.join(' + ')} — a settings allow rule cannot see runtime shape; confirm by hand`,
+        additionalContext: HINT_CORE,
       };
     }
   }
   // (b2) the same guard over the scanned kit tools. The refusal NAMES the lane that avoids it, so a
   // caller who picked the inline lane for a shell-significant pattern is corrected by the mechanism
   // rather than expected to have remembered the rule.
-  const scannedTool = matchScannedToolPrefix(trimmed);
-  if (scannedTool !== null) {
+  const scannedTools = matchScannedTools(trimmed);
+  if (scannedTools.length > 0) {
     const residualClasses = detectResidualClasses(trimmed);
     if (residualClasses.length > 0) {
+      const named = scannedTools.map((tool) => `"${tool}"`).join(' + ');
+      const lanes = [...new Set(scannedTools.map((tool) => SCANNED_TOOL_LANES[tool]))].join(' / ');
       return {
         permissionDecision: DECISION_ASK,
-        permissionDecisionReason: `agent-workflow residual guard: "${scannedTool}" carries ${residualClasses.join(' + ')} — pass the pattern with --pattern-file (its bytes then never enter the command string), or confirm by hand if the byte is really part of the invocation`,
+        permissionDecisionReason: `agent-workflow residual guard: ${named} carries ${residualClasses.join(' + ')} — pass the byte-carrying argument out of band with ${lanes} (its bytes then never enter the command string), or confirm by hand if the byte is really part of the invocation`,
+        additionalContext: hintForScannedTools(scannedTools),
       };
     }
   }

package/references/modes/coverage-check.md

@@ -6,6 +6,7 @@ The **final-run checker** (strip-the-kit D3(c)+(d)) — two deterministic arms o
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/coverage-check.mjs --check [--cwd <dir>]`:
 
+0. **Attestation precondition (the provenance arm).** An lcov on disk carries no evidence of the tree it came from, so reading one and issuing a verdict certifies whatever happens to be there — the false GREEN direction is the dangerous one, because a line appended AFTER the suite ran has no `DA` entry and therefore reads non-executable ("nothing to cover"). Provenance is a CONSEQUENCE in exactly one context: a `run-gates --final` run deletes the artifact before any gate spawns. That runner mints a random nonce and writes `final-start.attempt` as a ONE-WAY COMMITMENT over `{nonce, tree fingerprint, base}`; the raw nonce rides the environment to this child, which recomputes the commitment and requires the record to carry it. Neither half suffices alone — a bare nonce is unverifiable, a persisted attempt id is reconstructible from public repo state — and the commitment is also the only place the BASE is bound, since no record stores it. The raw nonce is stripped from the red-proof probe environment so no descendant retains a live capability. Outcomes: **attested** → the coverage verdict is issued; **no handshake** → `attested=no` + `NO VERDICT` (exit 0, findings still printed, uncovered lines still exit 1 — the findings contract is unchanged); **a handshake describing another tree or matching no recorded attempt** → `REFUSED` (exit 1), never a verdict in either direction. One fully anchored `coverage-check: attested=<yes|no>` machine line rides every run, on the same exactly-once contract as the sha line. Stated residuals, both named rather than implied: (a) an operator who runs both processes can forge the store or the code — the kit's standing self-discipline posture, not a security boundary; (b) **"the run owns the artifact" is exclusive by CONVENTION over the fixed path, not enforced** — a writer outside the run (a second `run-gates`, a hand-run `--only unit-tests`, an orphaned test process) can place foreign evidence between the deletion and the checker's read, and every check then agrees. Closing (b) needs an attempt-unique artifact path, which the runner can name but the declared producer cmd must reference — queued as LCOV-EXCLUSIVE-OWNERSHIP. What this arm removes is the false green that needs no second process and nobody trying: evidence that predates the edit.
 1. **Coverage arm (D3(d)):** every CHANGED executable Node line (`.mjs`/`.cjs`/`.js`, tracked working-vs-HEAD changes + untracked-not-ignored files) must be covered — uncovered lines are LISTED `file:line` and fail; a changed file ABSENT from the lcov map is a file-level red (never "non-executable" by silence); changed out-of-domain files (e.g. `.sh`) and unsupported-source files (e.g. `.ts`) are LISTED — the claim is narrowed honestly, not widened. NO lcov file at the path = a LOUD `skipped-no-lcov` (exit 0, stated — produce the file via the unit-tests gate's lcov reporters); a symlink at the path is a refusal (lstat, no-follow).
 2. **Red-proof arm (D3(c)):** every authoritative current-base `red-proof` declaration must verify — the bound test file exists (deleted fails), its content sha256 matches the declaration (custody), the test resolves (zero-match fails) and runs green N/N NOW, and the declaration's pre-fix fingerprint differs from the current tree (equal = reuse/forgery, refused). A malformed evidence store fails CLOSED.
 

package/references/modes/velocity.md

@@ -33,11 +33,12 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 - `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd ${PROJECT_ROOT}` (wildcard — the read-only deployment advisor; its rendered apply one-liners are writers and still prompt)
 - `node ${CLAUDE_SKILL_DIR}/tools/manifest/validate.mjs --strict <skill-dir>` (wildcard)
 - `node ${CLAUDE_SKILL_DIR}/tools/release-scan.mjs <path>` (wildcard)
-- `node ${CLAUDE_SKILL_DIR}/tools/repo-search.mjs --pattern <literal> --path <p>` (wildcard — the LITERAL search lane; for a pattern carrying a shell-significant byte use `--pattern-file <p>` instead, so the bytes never enter the command string. This is the ONE tier tool that DOES carry hook residual coverage — see the honesty note below)
+- `node ${CLAUDE_SKILL_DIR}/tools/repo-search.mjs --pattern <literal> --path <p>` (wildcard — the LITERAL search lane; for a pattern carrying a shell-significant byte use `--pattern-file <p>` instead, and for a TARGET PATH carrying one use `--paths-file <p>` — either way the bytes never enter the command string. one of the TWO tier tools that carry hook residual coverage — see the honesty note below)
+- `node ${CLAUDE_SKILL_DIR}/tools/path-inventory.mjs --path <p>` (wildcard — the read-only inventory lane: exists / type / size / `wc -l` lines / one-level listing / small-file contents for N paths in ONE call, so small path questions never need a composed shell. `--paths-file <p>` is its out-of-band target lane; hook residual coverage as with repo-search)
 - `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs --cwd ${PROJECT_ROOT}` — **EXACT byte-string only**, and honestly **project-exec, not read-only**: it runs YOUR declared `docs/ai/gates.json` commands — the same trust boundary the opt-in hook grants byte-exact per-cmd. A wildcard would be BROADER than that boundary (`--cwd <dir>` executes another project's declared gates), so the bare cwd-defaulting form, any other `--cwd`, `--only`, and **`--final`** forms all still prompt (`--final` WRITES the final-run receipt into the core-evidence store — a recording run is never auto-approved).
 - Writer previews, **exact arg-free dry-run byte-strings only** (the SEEDED tier byte-string is the arg-free preview of each): `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs` · `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs` — every `--apply`/`--write`/`--yes` still prompts, always. (`gate-hook` also has a **`--read-lane`** flagged preview — the opt-in read-only compound lane, `${CLAUDE_SKILL_DIR}/references/modes/hook.md`; that flagged form is NOT the seeded arg-free byte-string, so it may **prompt once** — it IS a consent flow, stated, no silent cap.)
 
-Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with ONE deliberate exception, `repo-search.mjs`**, whose invocation prefix is in the hook's scanned list precisely because it takes caller-supplied argument bytes: a real redirection or command substitution on ITS invocation raises the ask, and the refusal names the `--pattern-file` lane that avoids it. It is NOT in the seeded core, so it never inherits the read-lane compound allow. Every other tier entry: the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
+Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with TWO deliberate exceptions, `repo-search.mjs` and `path-inventory.mjs`**, whose prefixes are in the hook's scanned list because they take caller-supplied argument bytes: a redirection or substitution on THEIR invocation raises the ask, whose reason names that tool's out-of-band lane (`--pattern-file` / `--paths-file`) — context for the HUMAN deciding, not a message to the caller. Neither is in the seeded core, so neither inherits the read-lane allow. Every other tier entry: the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
 
 **Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
 

package/references/shared/command-shapes.md

@@ -1,30 +1,31 @@
 ### Command shapes — the promptless bar for instructed reads & probes
 
-When a mode doc tells you to read a file or probe project state WITHOUT prescribing the exact
-command (a recon read, the version-stamp read, any "check X" instruction), the shape is yours —
-and improvised shapes are where approval prompts come from. The bar:
+When a mode doc tells you to read a file or probe state WITHOUT prescribing the exact command (a
+recon read, the version-stamp read, any "check X"), the shape is yours — and improvised shapes are
+where approval prompts come from. The bar:
 
-- **Reads ride the host's file-read tool** (Read/Grep/Glob in Claude Code, or your agent's
-  equivalent) whenever one exists — a file-read tool never fires a shell approval prompt.
+- **Reads ride the host's file-read tool** (Read/Grep/Glob, or your agent's equivalent) whenever one
+  exists — a file-read tool never fires a shell approval prompt.
 - **No file-read tool → ONE plain undecorated command per probe:** no `;`/`&&` compounds, no
-  redirects, no pipes, no command substitution — one probe per invocation. This applies the
-  deployed agent-rules lens’s «plain pipeline per call» discipline here as a stricter
-  single-command shape. Any decorated or chained form falls outside this contract’s baseline
-  guarantee; behavior is then host/config-dependent — it may prompt, an opt-in read-lane may
-  auto-approve a vetted compound, and command substitution may even slip past a prefix allow
-  rule. The plain single-command shape is the only shell fallback this contract treats as
-  promptless by construction.
-- **Improvised file writes ride the host's file-edit tools** (Write/Edit or the equivalent) —
-  never an ad-hoc heredoc or shell-redirect write.
+  redirects, no pipes, no command substitution — one probe per invocation (the lens’s «plain pipeline
+  per call», stricter). A decorated or chained form is outside this contract’s guarantee: behavior is
+  host/config-dependent — it may prompt, an opt-in read-lane may auto-approve a vetted compound, and
+  command substitution may even slip past a prefix allow rule. The plain single-command shape is the
+  only shell fallback that is promptless by construction.
+- **Improvised file writes ride the host's file-edit tools** (Write/Edit or equivalent) — never an
+  ad-hoc heredoc or shell-redirect write.
 - **Searching for TEXT is its own case.** A pattern carrying `>`, `` ` `` or `$(` prompts on a
-  seeded-core command however it is quoted — the guard scans the raw string and a quote-stripped
-  copy. Quoting is not a workaround. (`|`/`&&` do not trip it.) Use the host's search tool if it has
-  one; else, where the kit tier is seeded, `node <kit>/tools/repo-search.mjs --pattern <literal>`,
-  switching to `--pattern-file <path>` for a byte-carrying pattern — written with the file-write tool
-  above, so its bytes never enter the command string; else one plain command, accepting the prompt.
-  A wrong lane earns a refusal that NAMES the file lane. Residual: a bare `grep` still prompts, and
-  the file lane needs promptless host writes.
+  seeded-core command however quoted — the guard scans the raw string and a quote-stripped copy.
+  Quoting is not a workaround. (`|`/`&&` do not trip it.) Use the host's search tool if it has
+  one; else, with the kit tier seeded, `node <kit>/tools/repo-search.mjs --pattern <literal>`,
+  switching to `--pattern-file <path>` for a byte-carrying pattern and `--paths-file <path>` for a
+  byte-carrying TARGET — written with the file-write tool above, so their bytes never enter the
+  command string; else one plain command, taking the prompt. A wrong lane earns an ask naming the
+  right lane back to YOU, not just the human. **PATH questions too:** exists / size / lines / listing
+  (file text needs `--contents`), any number of paths, is ONE
+  `node <kit>/tools/path-inventory.mjs --path <p>` — not a bannered compound. Residual: a bare `grep` still prompts, and the file lanes need
+  promptless writes.
 
-**Scope — improvised shapes only.** The executable commands a mode doc itself prescribes (the
-`node …/tools/…` dispatch lines, `--apply` lanes, install/symlink steps) are OUTSIDE this
-contract: run them exactly as prescribed, as plain single invocations.
+**Scope — improvised shapes only.** The commands a mode doc itself prescribes (`node …/tools/…`
+dispatch lines, `--apply` lanes, install/symlink steps) are OUTSIDE this contract: run them exactly
+as prescribed, as plain single invocations.

package/tools/coverage-check.mjs

@@ -117,6 +117,68 @@ export const keyFor = (rootTop, rel) => {
   }
 };
 
+// ── the attestation handshake (the provenance precondition) ───────────────────────────────────────
+// An LCOV on disk carries NO evidence of the tree it was produced from, so reading one and issuing
+// a verdict certifies whatever happens to be there. The STALE-FAILURE direction was observed live
+// (2026-07-27, an identical failure list and sha after tests were added); the FALSE GREEN — the
+// dangerous one — was reproduced HERMETICALLY: a line appended after the suite ran has no DA entry,
+// and lcov.mjs:9-13 states that reads as non-executable, i.e. "nothing to cover".
+//
+// Provenance is a CONSEQUENCE inside exactly one context: a `run-gates --final` run deletes the
+// artifact before any gate spawns, so anything present came from that run. The runner mints a random
+// nonce and writes `final-start.attempt` as a one-way COMMITMENT over {nonce, fingerprint, base};
+// the raw nonce rides the environment to this child, which recomputes the commitment and requires
+// the record to carry it. Neither half suffices alone: a bare nonce is unverifiable (any later value
+// would do), a persisted attempt id alone is replayable (it is reconstructible from public repo
+// state, which is how the first two designs certified foreign evidence). The commitment also BINDS
+// THE BASE, which is persisted nowhere else — the only way a base check is possible at all.
+//
+// Residual, stated: an operator who runs both processes can forge the store or the code. That is the
+// kit's standing posture (review-state.mjs HUMAN residual), not a new weakening. What this removes
+// is the ACCIDENTAL false green — an interrupted run plus an ordinary later test run, nobody trying.
+export const ATTEST_NONCE_ENV = 'AW_FINAL_ATTEST_NONCE';
+export const ATTEST_FINGERPRINT_ENV = 'AW_FINAL_ATTEST_FINGERPRINT';
+export const ATTEST_BASE_ENV = 'AW_FINAL_ATTEST_BASE';
+const ATTEST_ENV_VARS = Object.freeze([ATTEST_NONCE_ENV, ATTEST_FINGERPRINT_ENV, ATTEST_BASE_ENV]);
+
+// The commitment bytes: newline-joined, which is unambiguous because every field is hex or empty
+// (the nonce and fingerprint by construction, the base a git object id or '' on an unborn branch).
+export const commitmentFor = (nonce, fingerprint, base) =>
+  createHash('sha256').update(`${nonce}\n${fingerprint}\n${base ?? ''}`).digest('hex');
+
+// A child of this process must never inherit a LIVE capability: the red-proof arm spawns `node --test`
+// probes, and a detached descendant holding the raw nonce could attest later.
+export const withoutAttestEnv = (env) => {
+  const out = { ...env };
+  for (const key of ATTEST_ENV_VARS) delete out[key];
+  return out;
+};
+
+// → { attesting: true } | { attesting: false, reason } | { refusal } — a refusal is an exit-1
+// identity failure (the runner handed a context that no longer describes this tree), DISTINCT from
+// the ordinary non-attesting case, which is exit 0 and merely withholds the verdict.
+// Exported as a test seam (the keyFor idiom): the undecidable-identity arm below cannot be reached
+// through the CLI, where a resolvable work tree is a precondition of getting this far.
+export const attestationState = ({ env, records, fingerprint, base }) => {
+  const nonce = env[ATTEST_NONCE_ENV];
+  if (typeof nonce !== 'string' || nonce === '') {
+    return { attesting: false, reason: 'no final-run attestation context — a verdict is issued only inside the run that owns the lcov (run-gates.mjs --final); findings below are informational' };
+  }
+  const passedFingerprint = env[ATTEST_FINGERPRINT_ENV] ?? '';
+  const passedBase = env[ATTEST_BASE_ENV] ?? '';
+  if (fingerprint == null) {
+    return { refusal: 'the attestation context cannot be verified — this tree has no computable fingerprint' };
+  }
+  if (passedFingerprint !== fingerprint || passedBase !== (base ?? '')) {
+    return { refusal: `the tree MOVED under the final run (the attestation context describes ${passedFingerprint.slice(0, 12)}…@${passedBase.slice(0, 12) || 'unborn'}, this tree is ${fingerprint.slice(0, 12)}…@${(base ?? '').slice(0, 12) || 'unborn'}) — a gate changed the working tree after the suite produced the lcov; re-run run-gates.mjs --final` };
+  }
+  const want = commitmentFor(nonce, fingerprint, base ?? '');
+  if (!records.some((r) => r.kind === 'final-start' && r.attempt === want)) {
+    return { refusal: 'the attestation context matches no recorded final-run attempt — the evidence store lost or never received the start record; re-run run-gates.mjs --final' };
+  }
+  return { attesting: true };
+};
+
 // ── the red-proof verification arm (D3(c)) ────────────────────────────────────────────────────────
 
 // verifyRedProofs({ rootTop, cwd, env }) → { failures: [...], verified: n } | { storeFailure }.
@@ -175,6 +237,12 @@ export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const lcovPath = resolveLcovPath(cwd, env);
   const lines = [];
   let failed = false;
+  // The identity is read BEFORE the coverage arm and again AFTER it: a single up-front comparison
+  // leaves a window in which the tree moves between the surface walk and the verdict.
+  const identityBefore = { fingerprint: computeTreeFingerprint(cwd), base: resolveBase(cwd) };
+  const storePath = resolveEvidencePath(cwd, env);
+  const storeRecords = storePath ? readEvidence(storePath).records : [];
+  const attestBefore = attestationState({ env, records: storeRecords, ...identityBefore });
   const cov = checkCoverage({ rootTop, lcovPath });
   // The machine line the final-run receipt binds (M2): the sha of the exact bytes THIS check
   // consumed — `none` states loudly that no lcov was read.
@@ -189,7 +257,8 @@ export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
       for (const f of cov.failures) lines.push(`  ${f}`);
     }
   }
-  const red = verifyRedProofs({ rootTop, cwd, env });
+  // The probes must never inherit a live attestation capability (a detached descendant could keep it).
+  const red = verifyRedProofs({ rootTop, cwd, env: withoutAttestEnv(env) });
   if (red.storeFailure) {
     failed = true;
     lines.push(`coverage-check: FAIL — ${red.storeFailure}`);
@@ -202,7 +271,24 @@ export const runCheck = ({ cwd = process.cwd(), env = process.env } = {}) => {
       lines.push(`coverage-check: ${red.verified} red-proof record(s) verified green N/N with custody intact`);
     }
   }
-  if (!failed && !cov.skipped && cov.failures.length === 0) {
+  // Re-read the identity AFTER the coverage arm and re-decide: the attestation must describe the
+  // tree the verdict was actually computed over, not the one it started over.
+  const identityAfter = { fingerprint: computeTreeFingerprint(cwd), base: resolveBase(cwd) };
+  const attestAfter = attestationState({ env, records: storeRecords, ...identityAfter });
+  const attestation = attestBefore.refusal ? attestBefore : attestAfter;
+  const attesting = attestation.attesting === true && attestBefore.attesting === true;
+  // EXACTLY ONE fully anchored machine line, the lcov-sha256 contract's sibling — the runner binds
+  // it, so a missing/duplicated/injected one is an integrity failure rather than a silent green.
+  lines.push(`coverage-check: attested=${attesting ? 'yes' : 'no'}`);
+  if (attestation.refusal) {
+    failed = true;
+    lines.push(`coverage-check: REFUSED — ${attestation.refusal}`);
+  } else if (!attesting) {
+    lines.push(`coverage-check: NO VERDICT — ${attestation.reason}`);
+  }
+  // The attestation gates ONLY the coverage claim. Every pre-existing fail-closed refusal above
+  // (symlinked lcov, malformed evidence store, unmet red-proof obligation) keeps its own exit 1.
+  if (attesting && !failed && !cov.skipped && cov.failures.length === 0) {
     lines.push('coverage-check: PASS — every changed Node line is covered');
   }
   return { code: failed ? 1 : 0, lines };
@@ -225,9 +311,21 @@ An absent lcov file is a LOUD skipped-no-lcov (exit 0 — NO coverage check ran,
 symlinked lcov path, an uncovered line, a broken red-proof obligation, or a malformed evidence
 store fails (exit 1).
 
+A coverage VERDICT is issued ONLY inside the run that owns the artifact's lifetime: run-gates
+--final deletes the lcov before any gate spawns and hands this checker an attestation context
+(a nonce whose one-way commitment over {nonce, fingerprint, base} is the final-start attempt id).
+One anchored machine line rides every run: coverage-check: attested=<yes|no>.
+  attested=yes → the verdict, exactly as before.
+  attested=no  → NO VERDICT (exit 0): findings are still printed, uncovered lines still exit 1;
+                 only the PASS attestation is withheld.
+  REFUSED (exit 1) → the context describes another tree, or matches no recorded attempt.
+Residual, stated: ownership of the fixed path is CONVENTION, not enforcement — a concurrent writer
+to it can still place foreign evidence (queued as LCOV-EXCLUSIVE-OWNERSHIP).
+
 Sandbox-safe: no network; writes nothing; spawns read-only git queries and the bound-test
-probes (node --test, shell-free) — the D4 sandbox lane.
-Read-only. Exit codes: 0 pass/skipped-loud; 1 fail; 2 usage.`;
+probes (node --test, shell-free) — the D4 sandbox lane. The attestation variables are consumed and
+removed from this process's environment before anything spawns, so no child inherits the capability.
+Read-only. Exit codes: 0 pass / no-verdict / skipped-loud; 1 fail or REFUSED; 2 usage.`;
 
 export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
@@ -253,7 +351,17 @@ export const main = (argv, ctx = {}) => {
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
-  const r = main(process.argv.slice(2));
+  // The capability is CONSUMED here: snapshot it, then remove it from this process's environment
+  // before anything spawns. Every `git` query and every bound-test probe below inherits
+  // process.env, so leaving it in place would hand a live attestation context to each of them —
+  // and a detached descendant could then certify a foreign lcov long after this run ended.
+  const attest = Object.fromEntries(
+    [ATTEST_NONCE_ENV, ATTEST_FINGERPRINT_ENV, ATTEST_BASE_ENV]
+      .filter((k) => process.env[k] !== undefined)
+      .map((k) => [k, process.env[k]]),
+  );
+  for (const k of Object.keys(attest)) delete process.env[k];
+  const r = main(process.argv.slice(2), { env: { ...process.env, ...attest } });
   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;