@sabaiway/agent-workflow-kit 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -4,6 +4,96 @@ 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.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
+be fixed inside the guard. This release stops routing the search through the guard at all.
+
+**New: `tools/repo-search.mjs`** — a literal, read-only repository search with two lanes.
+
+- `--pattern <literal>` for an ordinary pattern.
+- `--pattern-file <path>` for a pattern containing `>`, `` ` `` or `$(` — the bytes the residual scan
+  actually matches (`|` and `&&` do not trip it; they only take a command off the compound
+  read-lane). Write the pattern with your host's file-write tool and pass the plain path. **The
+  pattern's bytes never enter the command string**, so the scan has nothing to scan. That is not
+  obfuscation — encoding would disguise bytes that stay on the shell surface where bash can still run
+  them; these leave the surface entirely.
+
+**You do not have to remember which lane to use.** The tool's invocation prefix is now in the hook's
+scanned list, so picking the inline lane for a byte-carrying pattern earns a refusal that NAMES
+`--pattern-file`. A wrong choice costs one guiding prompt; it never costs silence.
+
+**The hook gained coverage, it did not lose any.** A non-core command never reached the residual scan
+before — that is exactly why a plain kit tool is promptless — so a real redirection or command
+substitution on this tool's own invocation would have gone unexamined. It is examined now, by the
+UNCHANGED scan run over one more prefix. Nothing about what a byte MEANS was re-litigated; AD-079
+stands, and the tool is deliberately NOT in the seeded read-only core, so it inherits no compound
+read-lane allow.
+
+**Scope, kept narrow on purpose.** Literal search only — an arbitrary synchronous regex cannot be
+bounded by checks between work units, so the class is removed rather than mitigated. Only regular
+files are read (a FIFO or device read hangs and defeats every bound). Any bound that fires returns a
+structured `incomplete` naming which bound it was — never a silent empty result. The pattern file is
+excluded from its own search by resolved path, so an exotic query cannot match itself.
+
+**Honest residual.** Nothing forces the lane on a caller who ignores it: a bare `grep` prompts exactly
+as before. A literal inline `$(` is still indistinguishable from an active one, permanently — use the
+file lane. Bytes in search PATHS still over-ask. And promptlessness rests on your settings honouring
+the tool's allow rule: the hook returning "no decision" is not the same as an allow.
+
 ## 4.1.0 — why the gate hook still over-asks, established rather than assumed (AD-079)
 
 **Read this if the hook has ever made you approve `grep -rn "=>" src` or a plain read wearing

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.1.0'
+  version: '4.3.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "4.1.0",
+  "version": "4.3.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

@@ -261,6 +261,33 @@ export const matchSeededCorePrefix = (command) => {
   return matched ? matched.join(' ') : null;
 };
 
+// Kit tools whose invocations rung (b) scans even though they are NOT in the seeded read-only core.
+// The distinction is deliberate and load-bearing: CORING one of these would also hand it the
+// rung (c) read-lane allow, which is exactly what a tool taking caller-supplied arguments must not
+// have. This SEPARATE list buys the residual coverage without that side effect.
+//
+// AD-079 line: this is the SAME unchanged scan run over a different prefix — it never asks what a
+// byte MEANS, so it is on the permitted side. Nothing here parses or deletes a span.
+// KIT-QUALIFIED, forward-slash canonical. Matching on the bare basename was the first attempt and
+// 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']);
+
+// 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
+// just the one after `node`: both reviewers found the strict form under-inclusive, one through node
+// flags (`node --no-warnings <tool>`), one through an operator attached to the path
+// (`node <tool>>out`). A missed invocation silently restores the unscanned behaviour on exactly the
+// 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) => {
+  const tokens = tokenizeCommand(command).map(canonicalToken);
+  const hit = SCANNED_TOOL_PATHS.find((path) => tokens.some((token) => token.includes(path)));
+  return hit ?? null;
+};
+
 // String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
 // substring scan (never a whitespace-token check — a token check misses `"--output=f"` / `'>' f`
 // where the quotes are still in the string but the shell will strip them). A quoted metacharacter
@@ -380,6 +407,19 @@ export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gate
       };
     }
   }
+  // (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 residualClasses = detectResidualClasses(trimmed);
+    if (residualClasses.length > 0) {
+      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`,
+      };
+    }
+  }
   // (c) read-lane allow — opt-in (lanes.json), mode-fenced like (a) but cwd-agnostic (a read is a
   // read from any directory). Runs AFTER (b), so a residual-carrying core command still ASKs.
   if (readLaneOn === true && ALLOW_PERMISSION_MODES.includes(permissionMode) && isReadLaneCommand(trimmed)) {

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,10 +33,11 @@ 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/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** — 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 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.
 
 **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

@@ -16,6 +16,14 @@ and improvised shapes are where approval prompts come from. The bar:
   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.
+- **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.
 
 **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

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;

package/tools/repo-search.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+// repo-search.mjs — the promptless repository search lane (LITERAL search, read-only).
+//
+// WHY THIS EXISTS. A search whose pattern carries a shell-significant byte (`>`, `` ` ``, `$(`)
+// cannot be issued as a seeded-core command without raising the residual ASK: the guard scans the
+// raw command string AND a quote-stripped copy, so no quoting protects the byte. That is not a bug
+// to fix in the guard — AD-079 closed that direction on four verified counterexamples. This tool
+// routes around it instead, in two lanes:
+//
+//   lane 1  --pattern <literal>        for a pattern with no shell-significant byte
+//   lane 2  --pattern-file <path>      the pattern's bytes NEVER enter the command string
+//
+// The selection rule is enforced by the hook, not by memory: this tool's invocation is in the
+// hook's scanned list, so choosing lane 1 for a byte-carrying pattern earns an ASK whose reason
+// names lane 2. A wrong choice costs one guiding prompt; it never costs silence.
+//
+// CONTRACT
+//   LITERAL only — no regex dialect, and none is planned for this slice: a bounded walk cannot
+//   interrupt a catastrophically backtracking RegExp call, so the class is removed, not mitigated.
+//   Multiline patterns DO match (the search runs over the whole decoded buffer; a hit reports the
+//   line it starts on).
+//   Four outcomes, never collapsed: matches (0), no matches (0 with an explicitly empty result),
+//   INCOMPLETE (3, naming the bound that fired), invalid input (2), I/O failure (1).
+//   CONTAINMENT is decided on the REAL path, never lexically — a symlinked ancestor resolves out of
+//   the root while passing every `..` check, and on Windows `relative()` across drives returns an
+//   absolute path that contains no `..` at all.
+//   Every file is opened NO-FOLLOW and NON-BLOCKING, then `fstat`-ed on the descriptor actually
+//   opened: an lstat-then-read pair loses to a swap between the two calls, and the swapped-in FIFO
+//   is precisely the blocking read this tool promises cannot happen.
+//   Directories are walked INCREMENTALLY with the budget checked before each entry — reading and
+//   sorting a whole directory first is unbounded work in exactly the case bounds exist for.
+//
+//   THREAT MODEL, stated rather than implied. Explicit `--path`/`--pattern-file` targets are
+//   resolved (so a symlink INSIDE the root is followed by design) and then containment-checked on
+//   the real path; the WALK never traverses a symlink at all. What is NOT defended against is an
+//   adversary mutating the tree DURING the walk: a directory swapped for a symlink between its
+//   lstat and its opendir would be traversed, and closing that needs descriptor-relative traversal
+//   (`openat` semantics) which dependency-free Node does not expose. This tool searches a workspace
+//   its own agent controls; concurrent hostile mutation is out of scope, and saying so is the
+//   honest close — an unstated residual would be the defect.
+//   Pure reader — no writes, no subprocess, no network. Dependency-free, Node >= 22, no side
+//   effects on import (the isDirectRun idiom).
+
+import { openSync, fstatSync, readSync, closeSync, opendirSync, realpathSync, lstatSync, constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve, relative, isAbsolute, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const EXIT_OK = 0;
+export const EXIT_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_INCOMPLETE = 3;
+
+export const DEFAULT_MAX_RESULTS = 200;
+export const DEFAULT_MAX_FILE_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_WALK_BUDGET = 20000;
+// Hard ceilings: a caller-supplied bound may lower these, never raise them. Without a ceiling the
+// bounds are advisory, which is the same as absent.
+export const HARD_MAX_RESULTS = 100000;
+export const HARD_MAX_FILE_BYTES = 64 * 1024 * 1024;
+const BINARY_SNIFF_BYTES = 8192;
+// Characters of context kept on EACH side of a match, and a HARD ceiling on the whole snippet.
+// The ceiling is the load-bearing one: bounding only the context still lets a huge --pattern-file
+// matched in many places accumulate, because the match itself rode into every snippet. With a total
+// cap the stored size per match is a constant, so no size of pattern or file can grow it.
+const SNIPPET_CONTEXT = 200;
+const SNIPPET_MAX = 512;
+const NEVER_WALKED = Object.freeze(['.git', 'node_modules']);
+// O_NOFOLLOW refuses a symlinked leaf at open time; O_NONBLOCK means a FIFO that slipped in returns
+// instead of hanging. Both are POSIX; on a platform lacking them the flags degrade to 0 and the
+// fstat check below is the remaining guard.
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+const NONBLOCK = constants.O_NONBLOCK ?? 0;
+const OPEN_FLAGS = constants.O_RDONLY | NOFOLLOW | NONBLOCK;
+
+class UsageError extends Error {}
+class IoError extends Error {}
+
+// The pattern is echoed as a DIGEST plus a byte length — never as a first content line. A first
+// line cannot separate two multiline patterns that share it, and it is unsafe for NUL/control
+// bytes; a digest separates them and survives any byte.
+export const patternDigest = (pattern) => {
+  const buf = Buffer.from(pattern, 'utf8');
+  return { digest: createHash('sha256').update(buf).digest('hex').slice(0, 16), bytes: buf.length };
+};
+
+// Exactly ONE trailing line ending is stripped — CRLF as one unit: a pattern file written by an
+// editor almost always ends in one, while a pattern that deliberately ends in a blank line keeps it.
+// Leaving a stray `\r` would make the search silently fail against LF content, which is the worst
+// possible failure mode for a tool whose whole job is finding text.
+export const resolvePattern = (raw) => {
+  if (raw.endsWith('\r\n')) return raw.slice(0, -2);
+  return raw.endsWith('\n') ? raw.slice(0, -1) : raw;
+};
+
+// `Number()` turns a long digit string into Infinity, which would disable the very bound being
+// parsed. Safe-integer and a hard ceiling are both required.
+export const parseCount = (raw, flag, ceiling) => {
+  if (!/^\d{1,15}$/u.test(raw ?? '')) throw new UsageError(`${flag} needs a plain non-negative integer, got: ${raw ?? '(missing)'}`);
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n)) throw new UsageError(`${flag} is not a safe integer: ${raw}`);
+  if (n > ceiling) throw new UsageError(`${flag} exceeds the hard ceiling ${ceiling}: ${raw}`);
+  return n;
+};
+
+const parseArgs = (argv) => {
+  const opts = { pattern: null, patternFile: null, paths: [], max: DEFAULT_MAX_RESULTS, maxBytes: DEFAULT_MAX_FILE_BYTES, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new UsageError(`${arg} requires a value`);
+      return argv[i];
+    };
+    if (arg === '--pattern') opts.pattern = next();
+    else if (arg === '--pattern-file') opts.patternFile = next();
+    else if (arg === '--path') opts.paths.push(next());
+    else if (arg === '--max') opts.max = parseCount(next(), '--max', HARD_MAX_RESULTS);
+    else if (arg === '--max-bytes') opts.maxBytes = parseCount(next(), '--max-bytes', HARD_MAX_FILE_BYTES);
+    else if (arg === '--json') opts.json = true;
+    else throw new UsageError(`unknown argument: ${arg} (see --help)`);
+  }
+  if (opts.pattern !== null && opts.patternFile !== null) {
+    throw new UsageError('--pattern and --pattern-file are mutually exclusive — the lane must be unambiguous');
+  }
+  if (opts.pattern === null && opts.patternFile === null) throw new UsageError('one of --pattern or --pattern-file is required');
+  if (opts.paths.length === 0) opts.paths.push('.');
+  return opts;
+};
+
+// Containment on the REAL path. A lexical check passes `link/secret.txt` whenever `link` resolves
+// outside, and on Windows a cross-drive `relative()` returns an absolute path carrying no `..` —
+// both were live review findings, not hypotheticals.
+export const resolveTarget = (realRoot, target) => {
+  const lexical = resolve(realRoot, target);
+  let real;
+  try {
+    real = realpathSync(lexical);
+  } catch (err) {
+    if (err?.code === 'ENOENT') throw new IoError(`no such path: ${target}`);
+    throw new IoError(`cannot resolve ${target} (${err?.code ?? err?.message ?? err})`);
+  }
+  const rel = relative(realRoot, real);
+  if (rel !== '' && (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`))) {
+    throw new IoError(`target resolves outside the search root: ${target}`);
+  }
+  return real;
+};
+
+// Open → fstat the DESCRIPTOR → read bounded. The descriptor is what was actually opened, so a swap
+// after the check cannot substitute a different node; O_NOFOLLOW refuses a symlinked leaf outright.
+const readRegularFile = (abs, maxBytes, state, io = {}) => {
+  const open = io.open ?? openSync;
+  const fstat = io.fstat ?? fstatSync;
+  const read = io.read ?? readSync;
+  const close = io.close ?? closeSync;
+  let fd;
+  try {
+    fd = open(abs, OPEN_FLAGS);
+  } catch (err) {
+    // ELOOP is a symlink refused by O_NOFOLLOW — a counted skip, not an error.
+    if (err?.code === 'ELOOP') state.skipped.symlinks += 1;
+    else state.skipped.unreadable += 1;
+    return null;
+  }
+  try {
+    const stat = fstat(fd);
+    if (!stat.isFile()) {
+      state.skipped.special += 1;
+      return null;
+    }
+    if (stat.size > maxBytes) {
+      state.skipped.large += 1;
+      // A skipped file is NOT a silent omission: the search is incomplete and says which bound did
+      // it. Reporting it only as a counter would let a partial search read as "no matches".
+      if (state.incomplete === null) {
+        state.incomplete = { bound: 'max-file-bytes', detail: `at least one file exceeds ${maxBytes} byte(s) and was not searched` };
+      }
+      return null;
+    }
+    const buf = Buffer.allocUnsafe(stat.size);
+    let got = 0;
+    while (got < stat.size) {
+      const n = read(fd, buf, got, stat.size - got, got);
+      if (n <= 0) break;
+      got += n;
+    }
+    // A short read means the file changed under us. Returning the partial buffer would let a
+    // truncated file come back as a confident "no matches" — the file is classified unreadable
+    // instead, which is counted and visible.
+    if (got !== stat.size) {
+      state.skipped.unreadable += 1;
+      return null;
+    }
+    return buf;
+  } catch {
+    state.skipped.unreadable += 1;
+    return null;
+  } finally {
+    close(fd);
+  }
+};
+
+const isBinary = (buf) => buf.subarray(0, BINARY_SNIFF_BYTES).includes(0);
+
+// Whole-buffer search, so a MULTILINE pattern matches; the line number is derived from the offset.
+// The newline cursor is carried ACROSS matches rather than recounted from zero for each one — with
+// the result cap at six figures, recounting is quadratic in the file length and burns the event
+// loop on exactly the large files a search is aimed at.
+const searchBuffer = (buf, pattern, relPath, state) => {
+  const text = buf.toString('utf8');
+  let from = 0;
+  let line = 1;
+  let counted = 0;
+  for (;;) {
+    const at = text.indexOf(pattern, from);
+    if (at === -1) return;
+    if (state.matches.length >= state.max) {
+      state.incomplete = { bound: 'max-results', detail: `stopped at ${state.max} result(s); more may exist` };
+      return;
+    }
+    for (let i = counted; i < at; i += 1) if (text.charCodeAt(i) === 10) line += 1;
+    counted = at;
+    // A pattern that STARTS on a newline would otherwise take that same byte as its own line start
+    // and report an empty snippet; searching back from the byte BEFORE it reports the line the match
+    // actually begins on.
+    const back = text.charCodeAt(at) === 10 ? Math.max(0, at - 1) : at;
+    const lineStart = text.lastIndexOf('\n', back) + 1;
+    // The snippet must span the WHOLE match: taking the line end from the match's START truncates a
+    // multiline pattern at its first newline, so the snippet could exclude the very text that
+    // matched (`\nbeta` in "alpha\nbeta" reported "alpha"). It is taken from the match's END.
+    const lineEndRaw = text.indexOf('\n', at + pattern.length);
+    const lineEnd = lineEndRaw === -1 ? text.length : lineEndRaw;
+    // The snippet is WINDOWED around the match, not the whole line. A minified file is one enormous
+    // line, and storing it per match turns a 200-result search into hundreds of megabytes — the
+    // bound has to apply to what is kept, not only to how many are kept.
+    const from0 = Math.max(lineStart, at - SNIPPET_CONTEXT);
+    const to0 = Math.min(lineEnd, at + pattern.length + SNIPPET_CONTEXT);
+    const windowed = `${from0 > lineStart ? '…' : ''}${text.slice(from0, to0)}${to0 < lineEnd ? '…' : ''}`;
+    const snippet = windowed.length > SNIPPET_MAX ? `${windowed.slice(0, SNIPPET_MAX - 1)}…` : windowed;
+    state.matches.push({ file: relPath, line, text: snippet });
+    from = at + Math.max(1, pattern.length);
+  }
+};
+
+const spend = (state) => {
+  if (state.walked >= state.walkBudget) {
+    if (state.incomplete === null) {
+      state.incomplete = { bound: 'walk-budget', detail: `stopped after ${state.walkBudget} entries; the tree was not fully traversed` };
+    }
+    return false;
+  }
+  state.walked += 1;
+  return true;
+};
+
+const walk = (root, abs, pattern, state, isExplicitTarget = false) => {
+  if (state.incomplete !== null || !spend(state)) return;
+
+  let stat;
+  try {
+    stat = (state.io.lstat ?? lstatSync)(abs);
+  } catch {
+    state.skipped.unreadable += 1;
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    state.skipped.symlinks += 1;
+    return;
+  }
+  if (stat.isDirectory()) {
+    // The default prune never applies to a directory the caller NAMED: `--path node_modules` asking
+    // for nothing back, silently, is a worse answer than searching it.
+    if (!isExplicitTarget && NEVER_WALKED.includes(abs.split(sep).pop())) return;
+    let dir;
+    try {
+      dir = (state.io.opendir ?? opendirSync)(abs);
+    } catch {
+      state.skipped.unreadable += 1;
+      return;
+    }
+    try {
+      // Incremental: the budget is consulted before each entry, so one enormous directory cannot
+      // force unbounded work (or unbounded memory) before the first check.
+      for (;;) {
+        const entry = dir.readSync();
+        if (entry === null) break;
+        if (state.incomplete !== null) break;
+        walk(root, join(abs, entry.name), pattern, state);
+      }
+    } finally {
+      dir.closeSync();
+    }
+    return;
+  }
+  if (state.excludePath !== null && abs === state.excludePath) {
+    state.skipped.patternFile += 1;
+    return;
+  }
+  const buf = readRegularFile(abs, state.maxBytes, state, state.io);
+  if (buf === null) return;
+  if (isBinary(buf)) {
+    state.skipped.binary += 1;
+    return;
+  }
+  searchBuffer(buf, pattern, relative(root, abs) || abs, state);
+};
+
+// `io` injects the filesystem primitives so the failure branches — a vanished entry, an unopenable
+// directory, a symlink refused by O_NOFOLLOW, a file truncated mid-read — are reachable from tests.
+// Every one of them is a COUNTED skip in production, and a counted skip that no test ever exercises
+// is indistinguishable from a silent one.
+export const search = ({ root, pattern, paths, max, maxBytes, excludePath = null, walkBudget = DEFAULT_WALK_BUDGET, io = {} }) => {
+  const state = {
+    matches: [],
+    incomplete: null,
+    skipped: { symlinks: 0, binary: 0, special: 0, unreadable: 0, large: 0, patternFile: 0 },
+    excludePath,
+    io,
+    walked: 0,
+    walkBudget,
+    max,
+    maxBytes,
+  };
+  for (const target of paths) {
+    // The target list is bounded too: a caller passing thousands of --path values would otherwise
+    // spend unbounded work resolving them while walk() returns immediately.
+    if (state.incomplete !== null) break;
+    walk(root, resolveTarget(root, target), pattern, state, true);
+  }
+  return {
+    pattern: patternDigest(pattern),
+    matches: state.matches,
+    incomplete: state.incomplete,
+    skipped: state.skipped,
+    scanned: state.walked,
+  };
+};
+
+const formatResult = (result) => {
+  const lines = [
+    `repo-search — literal pattern sha256:${result.pattern.digest} (${result.pattern.bytes} byte(s)) · ${result.scanned} entr(ies) scanned`,
+  ];
+  for (const m of result.matches) lines.push(`${m.file}:${m.line}: ${m.text}`);
+  if (result.matches.length === 0) lines.push('  no matches');
+  const skips = Object.entries(result.skipped).filter(([, n]) => n > 0);
+  if (skips.length) lines.push(`  skipped: ${skips.map(([k, n]) => `${k}=${n}`).join(', ')}`);
+  if (result.incomplete) lines.push(`  ⚠ INCOMPLETE (${result.incomplete.bound}): ${result.incomplete.detail}`);
+  return lines.join('\n');
+};
+
+const HELP = `repo-search — literal repository search that never has to ride a shell metacharacter.
+
+Usage:
+  node repo-search.mjs --pattern <literal> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
+  node repo-search.mjs --pattern-file <path> [--path <p>]... [--max <n>] [--max-bytes <n>] [--json]
+
+--pattern-file is the lane for a pattern carrying shell-significant bytes (\`>\`, \`$(\`, a backtick):
+its bytes never enter the command string, so the residual guard has nothing to scan. Write the file
+with your host's file-write tool, then pass the plain path here, and delete it when you are done —
+this tool never writes.
+
+LITERAL only, multiline patterns supported. Reads regular files only, opened no-follow. Skipped
+entries (symlinks, non-regular, binary, oversized, unreadable) are counted and reported, never
+dropped silently; an oversized file additionally makes the whole search INCOMPLETE.
+
+Exit codes: 0 search completed (matches or an explicitly empty result) · 1 I/O failure or refusal ·
+2 usage / invalid input · 3 completed but INCOMPLETE (a bound fired; the bound is named).`;
+
+export const main = (argv, ctx = {}) => {
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: EXIT_OK, stdout: HELP, stderr: '', result: null };
+    const root = realpathSync(resolve(ctx.cwd ?? process.cwd()));
+    const opts = parseArgs(argv);
+    let raw;
+    let excludePath = null;
+    if (opts.patternFile !== null) {
+      excludePath = resolveTarget(root, opts.patternFile);
+      const state = { skipped: { symlinks: 0, special: 0, unreadable: 0, large: 0 }, incomplete: null };
+      const buf = readRegularFile(excludePath, HARD_MAX_FILE_BYTES, state);
+      if (buf === null) throw new IoError(`cannot read --pattern-file ${opts.patternFile} as a regular file`);
+      raw = buf.toString('utf8');
+    } else {
+      raw = opts.pattern;
+    }
+    const pattern = opts.patternFile !== null ? resolvePattern(raw) : raw;
+    if (pattern === '') throw new UsageError('the pattern is empty — it would match every line of every file');
+
+    const result = search({ root, pattern, paths: opts.paths, max: opts.max, maxBytes: opts.maxBytes, excludePath });
+    const stdout = opts.json ? JSON.stringify(result, null, 2) : formatResult(result);
+    return { code: result.incomplete ? EXIT_INCOMPLETE : EXIT_OK, stdout, stderr: '', result };
+  } catch (err) {
+    if (err instanceof UsageError) return { code: EXIT_USAGE, stdout: '', stderr: `repo-search: ${err.message}`, result: null };
+    if (err instanceof IoError) return { code: EXIT_ERROR, stdout: '', stderr: `repo-search: ${err.message}`, result: null };
+    return { code: EXIT_ERROR, stdout: '', stderr: `repo-search: ${err?.message ?? err}`, result: null };
+  }
+};
+
+const emitResult = (r) => {
+  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;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) emitResult(main(process.argv.slice(2)));

package/tools/run-gates.mjs

@@ -34,8 +34,14 @@ import { createHash, randomUUID } from 'node:crypto';
 import { computeTreeFingerprint } from './review-state.mjs';
 // The D3(a) final receipt rides the core-evidence SOLE WRITER (the sole-writer boundary — this
 // runner never opens the store itself) + the canonical per-kind serialization its hashes bind.
-import { appendEvidenceRecord, resolveEvidencePath, readEvidence, canonicalKindSerialization, EVIDENCE_SCHEMA_VERSION } from './core-evidence.mjs';
-import { LCOV_BASENAME } from './coverage-check.mjs';
+import { appendEvidenceRecord, resolveEvidencePath, readEvidence, canonicalKindSerialization, EVIDENCE_SCHEMA_VERSION, resolveBase } from './core-evidence.mjs';
+import {
+  LCOV_BASENAME,
+  commitmentFor,
+  ATTEST_NONCE_ENV,
+  ATTEST_FINGERPRINT_ENV,
+  ATTEST_BASE_ENV,
+} from './coverage-check.mjs';
 
 // The per-project declaration (strict JSON, hand-editable). cwd-relative — errors show a path the
 // user can open (the orchestration-config CONFIG_REL idiom).
@@ -196,10 +202,19 @@ export const selectGates = (gates, onlyIds) => {
 // silently attest against the wrong git dir or lcov instead of the computed one.
 export const RESERVED_PRODUCER_ENV = Object.freeze(['AW_GIT_DIR', 'AW_LCOV_FILE']);
 
+// The attestation variables ride the same STRIP but are NOT producer variables: a producer variable
+// is something a gate cmd may legitimately reference, and a missing one refuses the run up front.
+// A capability is the opposite — no gate may reference it, exactly one gate is handed it, and every
+// other child (and any descendant it spawns) must see it absent, host-set copies included, or that
+// descendant could certify a foreign lcov later. Conflating the two lists made a gate that merely
+// MENTIONS the name refuse the whole run.
+export const RESERVED_CAPABILITY_ENV = Object.freeze([ATTEST_NONCE_ENV, ATTEST_FINGERPRINT_ENV, ATTEST_BASE_ENV]);
+
 export const spawnGateViaBash = (cmd, cwd, extraEnv = {}) => {
   const env = { ...process.env };
   delete env.NODE_TEST_CONTEXT;
   for (const name of RESERVED_PRODUCER_ENV) delete env[name];
+  for (const name of RESERVED_CAPABILITY_ENV) delete env[name];
   return spawnSync('bash', ['-c', cmd], { cwd, env: { ...env, ...extraEnv }, encoding: 'utf8', maxBuffer: MAX_GATE_OUTPUT_BYTES });
 };
 
@@ -327,13 +342,22 @@ const matchesCanonicalCheck = (check, cmd, projectDir) => {
   }
 };
 
+// canonicalCheckerGates(gates, projectDir) → every gate that IS the canonical coverage-check. The
+// count is load-bearing twice over: --final refuses more than one (the attestation capability would
+// reach more than one process) and this predicate must refuse the same declaration, or a consumer
+// would advertise final-capability for a declaration --final then rejects.
+export const canonicalCheckerGates = (gates, projectDir) =>
+  gates.filter((g) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], g.cmd, projectDir));
+
 // isFinalCapableDeclaration(gates, projectDir) → whether --final would accept this declaration
-// (every canonical core check present + the checker LAST) — the ONE home consumers (the
-// recommendations guard-install probe) read instead of re-deriving the rule.
+// (every canonical core check present + EXACTLY ONE canonical checker + that checker LAST) — the
+// ONE home consumers (the recommendations guard-install probe, the worktrees report) read instead
+// of re-deriving the rule.
 export const isFinalCapableDeclaration = (gates, projectDir) => {
   if (!Array.isArray(gates) || gates.length === 0) return false;
   const missing = FINAL_CORE_CHECKS.filter((c) => !gates.some((g) => matchesCanonicalCheck(c, g.cmd, projectDir)));
   if (missing.length > 0) return false;
+  if (canonicalCheckerGates(gates, projectDir).length !== 1) return false;
   return matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gates[gates.length - 1].cmd, projectDir);
 };
 const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
@@ -389,6 +413,13 @@ export const runCli = (argv, deps = {}) => {
       if (missing.length > 0) {
         throw fail(EXIT.malformed, `--final refuses a weakened declaration — missing the canonical core check(s): ${missing.map((c) => c.name).join(', ')} (each must be ONE plain --check invocation of the kit's OWN tool in ${GATES_REL} — a masked form, a compound, or a lookalike path never counts)`);
       }
+      // EXACTLY ONE canonical checker. Two gates may carry the same canonical cmd under different
+      // ids, and the capability is handed to every match — so without this the "exactly one gate
+      // holds it" guarantee is prose, and an extra copy would run with a live attestation context.
+      const canonicalCheckers = canonicalCheckerGates(declaration.gates, projectDir);
+      if (canonicalCheckers.length > 1) {
+        throw fail(EXIT.malformed, `--final refuses the declaration — ${canonicalCheckers.length} gates are the canonical coverage-check (${canonicalCheckers.map((g) => JSON.stringify(g.id)).join(', ')}); exactly ONE may be, or the attestation context would be handed to more than one process`);
+      }
       const lastGate = declaration.gates[declaration.gates.length - 1];
       if (!matchesCanonicalCheck(FINAL_CORE_CHECKS[1], lastGate.cmd, projectDir)) {
         throw fail(EXIT.malformed, `--final refuses the declaration — the CANONICAL coverage-check gate must be the LAST declared gate (nothing may run after the checker consumed the lcov; "${lastGate.id}" is declared last)`);
@@ -430,7 +461,29 @@ export const runCli = (argv, deps = {}) => {
     }
     // --final needs the pre-run fingerprint (the receipt binds before == after == current).
     const finalFingerprintBefore = opts.final ? fingerprint(projectDir) : null;
-    const finalAttempt = opts.final ? randomUUID() : null;
+    const finalBase = opts.final ? resolveBase(projectDir) ?? '' : null;
+    // The attestation handshake (see coverage-check.mjs): a fresh random nonce rides the child
+    // environment, and the attempt id this run records is the one-way COMMITMENT over it plus the
+    // identity. Persisting only the commitment is what makes the context unreproducible from the
+    // repository afterwards — a plain recorded id is public, and attesting from one let an ordinary
+    // interrupted run certify a later run's lcov. The commitment is also the only place the BASE is
+    // bound, since no record stores it.
+    const finalNonce = opts.final ? randomUUID() : null;
+    const finalAttempt = opts.final ? commitmentFor(finalNonce, finalFingerprintBefore ?? '', finalBase) : null;
+    if (opts.final) {
+      // ONLY the canonical checker receives the capability — the same predicate the --final preflight
+      // uses to recognise it. Every other gate gets the producer variables and nothing else.
+      gateSpawn = (cmd, cwd2) => {
+        const producers = { AW_GIT_DIR: gitDir, AW_LCOV_FILE: join(gitDir, LCOV_BASENAME) };
+        if (!matchesCanonicalCheck(FINAL_CORE_CHECKS[1], cmd, projectDir)) return spawn(cmd, cwd2, producers);
+        return spawn(cmd, cwd2, {
+          ...producers,
+          [ATTEST_NONCE_ENV]: finalNonce,
+          [ATTEST_FINGERPRINT_ENV]: finalFingerprintBefore ?? '',
+          [ATTEST_BASE_ENV]: finalBase,
+        });
+      };
+    }
     let finalError = null;
     let startEvidenceHashes = null;
     if (opts.final) {
@@ -458,6 +511,19 @@ export const runCli = (argv, deps = {}) => {
     const results = runGates(selected, { cwd: projectDir, spawn: gateSpawn, log, now });
     for (const line of formatTable(results)) log(line);
     const allGreen = results.every((result) => result.ok);
+    // A green gate's stdout is deliberately not echoed — the table IS the report. But the checker
+    // exits 0 both when it certifies and when it WITHHOLDS a verdict, so on a plain run the table
+    // would read PASS over a coverage claim that was never made: the same false reassurance one
+    // layer up from the defect this whole mechanism exists to close. Surface it, and only it.
+    if (!opts.final) {
+      const checkerAt = selected.findIndex((gate) => matchesCanonicalCheck(FINAL_CORE_CHECKS[1], gate.cmd, projectDir));
+      const checkerRow = checkerAt === -1 ? null : results[checkerAt];
+      if (checkerRow?.ok && /^coverage-check: attested=no$/m.test(String(checkerRow.stdout ?? ''))) {
+        log(`── ${checkerRow.id} — NO COVERAGE VERDICT (the gate passed; it did not certify)`);
+        for (const line of String(checkerRow.stdout).split(/\r?\n/).filter((l) => /^coverage-check: (NO VERDICT|skipped-no-lcov)/.test(l))) log(line);
+        log('   A coverage verdict is issued only by run-gates.mjs --final, which owns the lcov for the whole run.');
+      }
+    }
     if (opts.final) {
       // The checker's verbatim diagnostics surface even on green — skipped-no-lcov and the
       // out-of-domain/unsupported lists must never vanish into a suppressed green stdout.
@@ -493,6 +559,22 @@ export const runCli = (argv, deps = {}) => {
         const shaLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => shaLineRe.test(l));
         const shaValue = shaLines.length === 1 ? shaLineRe.exec(shaLines[0])[1] : null;
         const lcovSha256 = shaValue !== null && shaValue !== 'none' ? shaValue : null;
+        // The attestation line, on the SAME exactly-one-anchored-line contract as the sha: a green
+        // exit status alone never proves the checker certified anything — it exits 0 both when it
+        // attests and when it withholds a verdict. Without this arm a gate that removed the start
+        // record mid-run would yield a green receipt carrying no coverage claim at all.
+        const attestLineRe = /^coverage-check: attested=(yes|no)$/;
+        const attestLines = String(checkerRow?.stdout ?? '').split(/\r?\n/).filter((l) => attestLineRe.test(l));
+        const attested = attestLines.length === 1 ? attestLineRe.exec(attestLines[0])[1] : null;
+        if (allGreen && integrityFailure === null && lcovSha256 !== null) {
+          if (attestLines.length !== 1) {
+            integrityFailure = attestLines.length === 0
+              ? 'the coverage-check gate printed no attested= line — whether coverage was certified is unknowable (fail closed)'
+              : `the coverage-check gate printed ${attestLines.length} attested= lines — exactly ONE full machine line binds the receipt`;
+          } else if (attested !== 'yes') {
+            integrityFailure = 'the coverage-check gate consumed an lcov but did NOT certify it — the final run reached the checker without a valid attestation context';
+          }
+        }
         if (allGreen && integrityFailure === null) {
           if (shaLines.length !== 1) {
             integrityFailure = shaLines.length === 0
@@ -543,7 +625,10 @@ export const runCli = (argv, deps = {}) => {
         logError(`[run-gates] --final could not write its receipt: ${err.message}`);
       }
     }
-    log(composeSummaryLine({ status: allGreen ? 'ok' : 'fail', results }));
+    // The summary line is the MACHINE report, so it must agree with the exit code: an integrity
+    // failure mints a RED receipt and exits finalFailed, and a line still saying status=ok there
+    // would be a silent green in the one place a reader parses instead of reads.
+    log(composeSummaryLine({ status: allGreen && finalError === null ? 'ok' : 'fail', results }));
     if (finalError) return EXIT.finalFailed;
     return allGreen ? EXIT.ok : EXIT.fail;
   } catch (err) {

package/tools/velocity-profile.mjs

@@ -144,6 +144,11 @@ export const KIT_READONLY_TOOLS = Object.freeze([
   KIT_RUN_GATES_TOOL,
   'tools/manifest/validate.mjs',
   'tools/release-scan.mjs',
+  // The literal search lane. It is in the tier for the ordinary reason (a pure reader the agent
+  // calls constantly), and its promptlessness additionally depends on it: a non-core command gets
+  // NO decision from the hook, which is not the same as an allow, so without this rule the lane
+  // falls through to whatever the host policy happens to be.
+  'tools/repo-search.mjs',
 ]);
 // Writer previews: ONLY writers whose ARG-FREE invocation is a documented dry-run ("Default is
 // --dry-run" in their usage) seed an EXACT preview byte-string — every --apply/--write/--yes keeps