@sabaiway/agent-workflow-kit 10.5.0 → 11.0.0

package/references/modes/robustness-brief.md

@@ -0,0 +1,61 @@
+### Mode: robustness-brief
+
+<!-- opt-in-capability: none — a read-only generator over a plan file and the kit's own list -->
+
+Read-only **executor-brief generator** — it turns a ledger row's `robust:<class>[,<class>]` tag into
+the block of concrete robustness literals the executor must prove BEFORE the first line of code.
+Measured 2026-08-30: a diff correct to its contract took 13 review rounds, each finding one more
+standard invariant (a git location variable, a sequencer ref, `%B`'s newline, `textconv`, fsync, a
+no-process spawn error) that nobody had written into the brief. The list is data
+(`${CLAUDE_SKILL_DIR}/references/robustness-literals.json`, versioned, language-neutral); this mode
+renders it, so a retro extends the list instead of a reviewer re-finding a member.
+
+**What it reads.** The plan file named by `--plan`, opened as a regular file no-follow through the
+kit's capped descriptor read (1 MiB — a plan is capped at 100 lines) with its realpath required
+under the realpath of the cwd (the project root the advisor renders the command from; no git is
+asked): an absolute path outside, a `..` traversal out of it, a symlink leading out, a non-regular file and
+an over-cap plan each refuse **exit 2** by name — the generator PRINTS row text, so unlike
+plan-shape-cli's unbounded no-follow read it is bounded. The plan is judged on every rule of plan-shape's structural half (headings, section caps,
+row grammar, ids, bytes, lexical containment, sweep form, duplicate paths, the total line, the
+acceptance and governing-spec presence rules) over EMPTY facts (`{}` — never undefined); the
+facts-bound half — realpath containment and sweep expansion — stays `plan-shape --check`'s. A plan
+that fails the structural half is refused, never half-rendered. And the kit's own list through its
+reader leaf (a list that fails the closed schema is refused by name; the tag grammar is that leaf's
+`parseRobustTag`, ONE home). Nothing else: no git, no project config, no network.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/robustness-brief.mjs --plan <plan> [--row <id>] [--coverage]`:
+
+1. Plain run → the Markdown block, ready to paste into the dispatch brief: a header naming the list
+   version and the plan path; then, for every tagged row, its id and path, and per tagged class the
+   class's `prove` sentence followed by its members as `literal — note (source)`. Every
+   plan-derived path — the header's and each row's — is rendered through the kit's string display
+   escape (`escapeForDisplay`), so no output line carries a raw control byte, U+2028 or U+2029; a
+   U+FFFD passes as the printable replacement character (stated, not escaped). The brief is built
+   whole before a byte is printed — never a partial brief. **Exit 0.** A plan with no `robust:`
+   token prints ONE stated line and still exits 0 — an untagged ledger is a fact about the plan, not
+   a failure of the tool. A row whose tag the grammar refuses (`no-class`, `empty-class`,
+   `duplicate-class`, `invalid-class`, `multiple-tags`) or names an unknown class id is **exit 1**
+   naming the row — never a zero-tags success.
+2. **`--row <id>`** → the block for that one row (the slice brief of a subagent or a delegated
+   dispatch). **Exit 1** when the row is absent from the ledger or carries no tag, so a brief can
+   never be assembled from a row that names nothing to prove.
+3. **Exit 1** also when the plan fails the structural half (the refusal lines are printed first);
+   **exit 2** usage — every operand is validated at parse: an unknown argument, an uncontained or
+   over-cap `--plan` (above), a malformed-UTF-8 plan (`malformed-utf8` — a genuine U+FFFD passes)
+   and a list the reader refuses by name (the tool's own installation, the plan-shape-facts precedent) are usage.
+4. Where it belongs (procedures.md `plan-execution` step 2): the dispatch brief — delegated or
+   subagent — carries the generated block for every tagged row; the procedures advisor renders the
+   populated command in the plan-execution render. Tag a row by writing `robust:<class>` in its
+   responsibility sentence; `plan-shape --check` refuses a class id the list does not carry
+   (`robust-class`) and leaves an untagged row unjudged.
+5. **`--coverage`** judges every valid `create`/`modify` row except `.md`/`.txt` documents and the shipped list itself. A class is PRESENT when the row file's bytes carry a bounded member token of kind env/flag/ref/syscall/errno/argv; `state` is never searched, `uncovered = present − tagged`, delete and absent rows are listed, and sweep rows union every path expanded by `plan-shape-facts`' one glob compiler. Reads use the same 1 MiB capped no-follow primitive. The table exits `0` when covered, `1` with each `row:class:literal` when uncovered, and `2` on a named row-read refusal. Bootstrap: for rows up to the row that lands this mode, apply the rule by hand; thereafter run coverage before every dispatch and before `flow-writer adoption`.
+
+**Honest bounds (stated, accepted):** the tag is the author's claim — the tool cannot know that an
+untagged row touches git, the reviewer still can; the list names classes and carries only MEASURED
+members, so a fact of someone else's runtime that nobody has measured yet is not in it until a retro
+adds it with its `source`; `source` is provenance of the measurement, not a path an installed kit
+opens; a class with only `state` members is blind and can never be PRESENT. The block informs the
+brief and never judges a diff — the hostile harness and the diff review stay the last line.
+
+**Invariants:** read-only · never writes · never commits · spawns nothing · the plain run reads the plan file and the kit list; `--coverage` additionally reads every judged row file through the capped no-follow read and the repository's regular-file listing for sweep expansion — nothing else, still no git, no spawn and no write · exit 0 printed / 1 refused / 2 usage ·
+`main(argv, deps)` returns, never exits.

package/references/modes/velocity.md

@@ -36,6 +36,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 - `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/review-rounds-cli.mjs --artifact <plan>` (wildcard — the read-only round table over the review receipts, the verdict half of the per-round emission the `procedures` advisor names every round; the path argument is resolved and compared, never opened as a pattern, so it rides the settings-level posture like the rest)
+- `node ${CLAUDE_SKILL_DIR}/tools/control-bytes.mjs --check` (wildcard — the read-only control-byte gate over the work tree: read-only git queries and descriptor-bound reads, no write API; the agent's own hand run before the declared gate runs it)
+- `node ${CLAUDE_SKILL_DIR}/tools/robustness-brief.mjs --plan <plan>` (wildcard — the read-only executor-brief generator over a plan and the kit's shipped literal list; no write API and no process spawn)
 - `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).
 - `node ${CLAUDE_SKILL_DIR}/tools/source-size-check.mjs --check` — **EXACT byte-string only**, and only this READ-ONLY mode: the tool's `--write-baseline` and `--adopt` modes WRITE (the recorded ratchet, and a gate declaration) and are deliberately uncovered — they still prompt, always. Every other form, `--cwd` included, keeps prompting. **What it covers, precisely:** the agent's own direct invocation. It is **not** the byte-string a DECLARED gate carries — the fill emits that path double-quoted (a kit path with a space must survive), and a seedable allow rule may carry no quotes at all, so the two spellings cannot be one string; a declared gate is auto-approved by the opt-in hook instead, byte-exact against `docs/ai/gates.json`.
 - 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.)

package/references/robustness-literals.json

@@ -0,0 +1,107 @@
+{
+  "schema": 1,
+  "version": 1,
+  "classes": [
+    {
+      "id": "git-location",
+      "prove": "Prove that every git query reaches the intended repository: every GIT_-named variable is stripped before cwd discovery, the git-dir, common-dir and work-tree identities agree between the ambient and the stripped discovery, and the hermetic environment is the fixtures' own, never a consumer's.",
+      "members": [
+        { "literal": "GIT_", "kind": "env", "note": "Strip every ASCII-case-insensitive git location variable before cwd discovery.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_DIR", "kind": "env", "note": "An ambient git directory can redirect discovery to another repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_WORK_TREE", "kind": "env", "note": "An ambient work-tree override can pair one git directory with another tree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_COMMON_DIR", "kind": "env", "note": "An ambient common directory can redirect shared repository state.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_INDEX_FILE", "kind": "env", "note": "A pre-commit hook can name a temporary or copied index.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_PREFIX", "kind": "env", "note": "A hook inherits the prefix git measured for its invocation.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_CONFIG_PARAMETERS", "kind": "env", "note": "Command-line git configuration reaches hooks through this variable.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "GIT_EXEC_PATH", "kind": "env", "note": "A hook-shaped environment carries git's executable path.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "HOME", "kind": "env", "note": "Pin the home directory for hermetic git configuration.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "XDG_CONFIG_HOME", "kind": "env", "note": "Pin the XDG configuration home beside HOME.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_GLOBAL", "kind": "env", "note": "Disable the host's global git configuration file.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_SYSTEM", "kind": "env", "note": "Disable the host's system git configuration file.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_CONFIG_NOSYSTEM", "kind": "env", "note": "Tell git not to consult system configuration.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_ATTR_NOSYSTEM", "kind": "env", "note": "Tell git not to consult system attributes.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "LC_ALL", "kind": "env", "note": "Pin git's diagnostic language before matching its answers.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "PATH", "kind": "env", "note": "A supplied PATH is honored and an omitted PATH borrows the process value.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--absolute-git-dir", "kind": "argv", "note": "Compare the ambient and stripped git-directory identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--git-common-dir", "kind": "argv", "note": "Compare the ambient and stripped common-directory identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "--show-toplevel", "kind": "argv", "note": "Compare the ambient and stripped work-tree identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "work-tree", "kind": "state", "note": "All three ambient and stripped identities agree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "not-a-repository", "kind": "state", "note": "Both discoveries report that cwd reaches no repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "error", "kind": "state", "note": "A probe, process result, path identity or answer failed closed.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "redirected", "kind": "state", "note": "Ambient and stripped discovery reach different repository identities.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "no-work-tree", "kind": "state", "note": "The git directory agrees but names no work tree.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "env-only", "kind": "state", "note": "Only the ambient git environment reaches a repository.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "GIT_MAX_BUFFER", "kind": "state", "note": "Every declared non-test git spawn buffer under agent-workflow-kit/tools/ uses the 256 MiB GIT_MAX_BUFFER; git-env.mjs declares it and every other scanned use imports it.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "git-operation-state",
+      "prove": "Prove that an interrupted or conflicted git operation cannot be mistaken for an ordinary clean work tree.",
+      "members": [
+        { "literal": "rebase-apply", "kind": "state", "note": "A stopped git am leaves the apply-backend directory even when ordinary diffs are clean.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "rebase-merge", "kind": "state", "note": "A stopped rebase on the merge backend leaves this directory and REBASE_HEAD while status names the conflicted path.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "MERGE_HEAD", "kind": "ref", "note": "A merge in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "CHERRY_PICK_HEAD", "kind": "ref", "note": "A cherry-pick in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "REVERT_HEAD", "kind": "ref", "note": "A revert in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "REBASE_HEAD", "kind": "ref", "note": "A rebase in progress leaves this sequencer reference.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "index.lock", "kind": "state", "note": "A held index lock blocks writes while read-only index queries still answer.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 1", "kind": "state", "note": "The conflicted path carries the common-ancestor index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 2", "kind": "state", "note": "The conflicted path carries the current-side index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged stage 3", "kind": "state", "note": "The conflicted path carries the other-side index stage.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "unmerged path twice", "kind": "state", "note": "Git 2.43 lists one conflicted path once per unmerged side; git am and bisect leave none of the four sequencer refs above.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" }
+      ]
+    },
+    {
+      "id": "git-read-flags",
+      "prove": "Prove that host git configuration, attributes and output framing cannot hide bytes or paths from a read.",
+      "members": [
+        { "literal": "status.showUntrackedFiles", "kind": "flag", "note": "Porcelain status can hide untracked files when this config is no.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "core.autocrlf", "kind": "flag", "note": "Work-tree CRLF and blob LF can compare clean under this config.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "core.symlinks", "kind": "flag", "note": "A host can materialize a tracked symlink as a placeholder regular file.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "--no-textconv", "kind": "flag", "note": "Disable textconv so configured filters cannot erase staged content from a diff.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "--ignore-submodules=none", "kind": "flag", "note": "Override a host config that hides every submodule change.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "-z", "kind": "flag", "note": "Use NUL framing for path-bearing git output.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "--exclude-standard", "kind": "flag", "note": "Apply repository ignore rules only where the query explicitly intends them.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "%B", "kind": "flag", "note": "Raw subject and body output carries its terminating newline and needs explicit framing.", "source": "scripts/check-ascii-letters.mjs" },
+        { "literal": "LC_ALL=C", "kind": "env", "note": "Pin git's own diagnostic wording before matching it.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "spawn-outcome",
+      "prove": "Prove that every process-launch and process-result state is handled explicitly and never collapses into an empty success.",
+      "members": [
+        { "literal": "ENOENT", "kind": "errno", "note": "The executable may be absent from PATH before a child starts.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "EACCES", "kind": "errno", "note": "The executable or a required path may be present but inaccessible.", "source": "agent-workflow-kit/tools/fs-safe.mjs" },
+        { "literal": "EPERM", "kind": "errno", "note": "A sandbox or host policy may refuse the attempted process or filesystem operation.", "source": "agent-workflow-kit/tools/fs-safe.mjs" },
+        { "literal": "signal", "kind": "state", "note": "A child killed by a signal has no ordinary exit status.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "synchronous throw", "kind": "state", "note": "An injected or native runner can throw before returning a process result.", "source": "agent-workflow-kit/tools/control-bytes.mjs" },
+        { "literal": "exit 128", "kind": "state", "note": "Git's own not-a-repository or no-work-tree wording classifies only the matching exit 128 answer.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "empty answer", "kind": "state", "note": "A zero exit with no identity text is an error, never a repository path.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "maxBuffer", "kind": "state", "note": "A declared output ceiling is shared rather than silently truncated or copied.", "source": "agent-workflow-kit/tools/git-env.mjs" }
+      ]
+    },
+    {
+      "id": "durable-write",
+      "prove": "Prove that a durable write binds the intended regular file, publishes atomically and refuses an existing exclusive target.",
+      "members": [
+        { "literal": "O_NOFOLLOW", "kind": "syscall", "note": "Refuse a symlink leaf at descriptor open.", "source": "agent-workflow-kit/tools/fs-read-nofollow.mjs" },
+        { "literal": "O_NONBLOCK", "kind": "syscall", "note": "Prevent a hostile FIFO from blocking a descriptor open forever.", "source": "agent-workflow-kit/tools/fs-read-nofollow.mjs" },
+        { "literal": "fsync", "kind": "syscall", "note": "Sync the temporary file before rename and the directory after publication where supported.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "rename", "kind": "syscall", "note": "Publish the fully written temporary file atomically after fsync.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "wx", "kind": "flag", "note": "Open a temporary file or lock with exclusive creation.", "source": "scripts/release/release-run.mjs" },
+        { "literal": "EEXIST", "kind": "errno", "note": "An existing exclusive lock is a named busy state, never permission to clobber.", "source": "scripts/release/release-run.mjs" }
+      ]
+    },
+    {
+      "id": "bytes-not-strings",
+      "prove": "Prove that byte-domain identities remain bytes until a deliberate lossless decoding boundary.",
+      "members": [
+        { "literal": "undecoded", "kind": "state", "note": "Path records remain Buffer slices through NUL framing.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "NUL", "kind": "state", "note": "Git path records are split on the byte delimiter rather than whitespace or lines.", "source": "agent-workflow-kit/tools/git-env.mjs" },
+        { "literal": "partial UTF-8 sequence", "kind": "state", "note": "A file can be observed while its last multibyte sequence is incomplete.", "source": "agent-workflow-kit/tools/hostile-git-harness.test.mjs" },
+        { "literal": "raw control byte", "kind": "state", "note": "A report line must never carry a raw line-breaking control character.", "source": "agent-workflow-kit/tools/repo-lex.mjs" },
+        { "literal": "U+FFFD", "kind": "state", "note": "Lossy decoding can fold distinct invalid byte sequences to the replacement character.", "source": "agent-workflow-kit/tools/repo-lex.mjs" }
+      ]
+    }
+  ]
+}

package/tools/changed-surface.mjs

@@ -14,7 +14,7 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024; // a full-tree diff can be large; never truncate
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 
 // ── the CLOSED changed-path classification rule (AD-046 Decision 5; no heuristics) ───────────────
 

package/tools/commands.mjs

@@ -224,6 +224,20 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Check that every configured review backend has receipted the current uncommitted tree with a fresh grounded review; --check turns it into a gate exit code.',
   },
+  {
+    key: 'control-bytes',
+    invocation: invocationOf('control-bytes'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Refuse any raw control byte (C0 or DEL; TAB, LF, CR admitted) in the work tree — a path name, a regular file\'s content unless a git attribute says binary, a symlink target; --check is the gate spelling of the same report and exit code.',
+  },
+  {
+    key: 'robustness-brief',
+    invocation: invocationOf('robustness-brief'),
+    group: 'Orchestrate',
+    kind: READ_ONLY,
+    oneLine: 'Generate the concrete robustness literals for every tagged row in a plan, or for one selected row.',
+  },
   {
     key: 'receipt-deadline',
     invocation: invocationOf('receipt-deadline'),

package/tools/commit-guard.mjs

@@ -34,8 +34,8 @@
 //      reason verbatim — a foreign worktree's chain stays advisory; the armed state extends the
 //      PASS line;
 //   4. re-computes the review-state decision (the ship-receipt arm) — a missing/vetoed ship
-//      receipt refuses. The env it hands over is SANITIZED (receipts/evidence/flow-store producer
-//      seams stripped) so a poisoned override can neither redirect nor mask any store this guard
+//      receipt refuses. The env it hands over is SANITIZED; four producer seams are stripped:
+//      receipts/evidence/flow-store/delegation-store. A poisoned override can neither redirect nor mask any store this guard
 //      reads.
 // `git commit --no-verify` stays the stated residual (a self-discipline mechanism, not a security
 // boundary). Read-only; dependency-free; Node >= 22. No side effects on import.
@@ -54,11 +54,12 @@ import {
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
+import { GIT_MAX_BUFFER, resolveGitLocation } from './git-env.mjs';
+import { escapeForDisplay } from './repo-lex.mjs';
 
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 const sha = (text) => createHash('sha256').update(text).digest('hex');
 
-const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 const gitLine = (args, cwd) => {
   const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
   if (r.error || r.status !== 0) return null;
@@ -201,28 +202,38 @@ const flowAdvisoryLines = (flow) => (flow.present && flow.armed
   : []);
 
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
-  const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
-  if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
-  // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
+  // FIRST of all: WHICH repository. The location is a closed six-state table judged by realpath
+  // agreement (the git-env leaf); every state but work-tree refuses by its own name — a redirecting
+  // GIT_DIR, a killed or absent git, a bare repository — instead of guarding another tree or
+  // passing a tree git could not describe. A pre-commit hook's own env agrees and passes.
+  const location = resolveGitLocation(cwd, { env });
+  if (location.state !== 'work-tree') {
+    // The cause can carry a repository PATH (a newline-bearing one included) — escaped, ONE line.
+    return { code: 1, lines: [`commit-guard: REFUSED — the git location is ${location.state} (${escapeForDisplay(location.cause)}) — nothing is guarded until git names one work tree from ${escapeForDisplay(cwd)}`] };
+  }
+  const rootTop = location.top;
+  // NEXT: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
   // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
   // would send the operator down a recovery they must redo.
-  const working = computeWorkingState(cwd);
+  const working = computeWorkingState(cwd, { env });
+  if (working === null) return { code: 1, lines: ['commit-guard: REFUSED — the working state is undecidable (a git query failed or was killed) — nothing is guarded'] };
   const indexLag = decideIndexLag(working);
   if (indexLag !== null) return indexLag;
-  const fingerprint = computeTreeFingerprint(cwd);
+  const fingerprint = computeTreeFingerprint(cwd, { env });
+  if (fingerprint === null) return { code: 1, lines: ['commit-guard: REFUSED — the tree fingerprint is undecidable (a git query failed or was killed) — nothing is guarded'] };
   // The CONTENT-FREE lanes — the second pure tree property, decided here for the same reason the
   // index lag is: no store read can answer it. A payload with no bytes states nothing about what
   // this commit will carry, and its fingerprint is the ONE value every clean moment of every
   // repository shares, so a receipt found at it was minted by some other moment, possibly at
   // another base. Such evidence must therefore decide NOTHING here — neither refuse nor attest
   // (the same fact flow-check-rungs.mjs applies to a red final). The index tells the two lanes
-  // apart, and `computeWorkingState` probes it with --ignore-submodules=none precisely so a
-  // config-hidden gitlink cannot pass for a clean one.
+  // apart. The payload runs --no-textconv and --ignore-submodules=none, so a config-hidden gitlink
+  // rides it; the arm stays because a content-free payload over a dirty index is undecidable by any receipt.
   const contentFree = fingerprint === CONTENT_FREE_FINGERPRINT;
   if (contentFree && working.stagedDirty) {
     return {
       code: 1,
-      lines: [`commit-guard: REFUSED — the index carries staged content the fingerprint domain cannot see (a submodule gitlink hidden from \`git diff\` by \`submodule.<name>.ignore\` or \`diff.ignoreSubmodules\`), so no final receipt can describe what this commit will carry. Recovery: clear that ignore setting (or set it to \`none\`) until \`git diff --cached --no-ext-diff\` shows the change, then re-run node ${FINAL_RUN_TOOL} --final`],
+      lines: [`commit-guard: REFUSED — the index carries staged content the payload cannot see, so no final receipt can describe what this commit will carry. Recovery: make the staged change visible to \`git diff --cached\`, then re-run node ${FINAL_RUN_TOOL} --final`],
     };
   }
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE
@@ -323,6 +334,7 @@ export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   delete reviewEnv.AW_REVIEW_RECEIPTS;
   delete reviewEnv.AW_CORE_EVIDENCE;
   delete reviewEnv.AW_FLOW_STORE;
+  delete reviewEnv.AW_DELEGATION_STORE;
   const review = decideCheck(buildState({ cwd, env: reviewEnv }));
   if (review.code !== 0) {
     return { code: 1, lines: [`commit-guard: REFUSED — the review obligations are not satisfied: ${review.reason}`] };
@@ -354,7 +366,7 @@ the LATEST completed run-gates --final receipt — refusing on { no receipt for
 latest attempt · before≠after · declaration content drift · evidence-hash drift · lcov drift ·
 a flow-store refusal (a PRESENT store's open own chain / base motion / coverage — verbatim; no
 store file = byte-exact pre-flow behavior) · unsatisfied review obligations (the review-state
-decision, over a sanitized env — receipts/evidence/flow-store seams stripped) }. Wire it into
+decision, over a sanitized env — receipts/evidence/flow-store/delegation-store seams stripped) }. Wire it into
 pre-commit; \`git commit --no-verify\` stays the stated residual (self-discipline, not a security
 boundary).
 

package/tools/control-bytes.mjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+// control-bytes.mjs — the read-only control-byte gate over the WORK TREE (the contract:
+// docs/ai/specs/kit/control-bytes.md; the mode: references/modes/control-bytes.md). Measured
+// 2026-08-30: an editor wrote a raw NUL into a test source, git classed the file as binary, the
+// letter-level checker skipped the blob by kind, and the byte reached a reviewer one round later.
+// This tool makes that byte a mechanical refusal: it judges BYTES, never letters, over tracked plus
+// untracked-not-ignored paths — the name always, a regular file's content unless a git attribute
+// says binary, a symlink's target string without following it — and refuses, never skips, on
+// anything it cannot judge. main(argv, deps) returns { code, lines } and never exits; every spawn,
+// fs and env read is injectable; the CLI half prints and sets the exit code. Read-only: it writes
+// nothing and spawns only the git argv declared below (plus the location leaf's rev-parse probes).
+
+import { closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { isDirectRun } from './direct-run.mjs';
+import { probeRegularFileNoFollow, readFileBytesNoFollowCapped } from './fs-read-nofollow.mjs';
+import { GIT_MAX_BUFFER, parseIndexEntries, resolveGitLocation, withGitPath } from './git-env.mjs';
+import { isRefusedControlByte, renderPathForDisplay } from './repo-lex.mjs';
+
+export const READ_CAP = 16 * 1024 * 1024;
+// The exact read-only git argv this tool spawns — pinned by the kit read-only tier registry.
+export const CONTROL_BYTES_GIT_ARGV = Object.freeze([
+  Object.freeze(['ls-files', '-s', '-z']),
+  Object.freeze(['ls-files', '--others', '--exclude-standard', '-z']),
+  Object.freeze(['check-attr', '--stdin', '-z', 'binary', 'diff']),
+  Object.freeze(['config', '--type=bool', '--get', 'core.symlinks']),
+  Object.freeze(['ls-files', '-v', '-z']),
+]);
+const [TRACKED_ARGV, UNTRACKED_ARGV, ATTRIBUTES_ARGV, SYMLINKS_ARGV, SPARSE_ARGV] = CONTROL_BYTES_GIT_ARGV;
+export const defaultIo = Object.freeze({ open: openSync, fstat: fstatSync, read: readSync, close: closeSync, constants: fsConstants, lstat: lstatSync, readlink: readlinkSync, realpath: realpathSync, stat: statSync });
+
+const USAGE = `usage: node control-bytes.mjs [--check] [--cwd <dir>]
+  Refuses any raw C0 or DEL byte (TAB, LF, CR admitted) in the work tree: a path's name, a regular
+  file's content (unless its git attribute says binary or -diff) or a symlink's target string.
+  --cwd <dir>   anchor at that directory's work-tree root (default: the process cwd)
+  --check       the gate spelling; the plain run prints the same report and shares the exit table
+  exit 0 clean · 1 a finding or a refusal · 2 usage`;
+
+const NUL = Buffer.from([0]);
+const render = renderPathForDisplay;
+// Every DYNAMIC diagnostic (a location cause, git stderr, an fs error code, a user argument) rides
+// the same renderer as paths before it reaches a line — SAFE (never a raw byte or U+FFFD), while
+// injectivity is promised for NAMES only: a string-originated diagnostic folds invalid bytes first.
+const safe = (text) => render(Buffer.isBuffer(text) ? text : Buffer.from(String(text), 'utf8'));
+const refusalLine = (message) => `control-bytes: REFUSED — ${message}`;
+const absent = (path, tracked) => `${render(path)}: absent (${tracked ? 'tracked but missing from the work tree — stage the deletion with git rm or git add -A, or it' : 'git named it, it'} vanished before the read)`;
+const unreadable = (path, why) => `${render(path)}: unreadable (${safe(why)})`;
+const hexByte = (byte) => `0x${byte.toString(16).padStart(2, '0')}`;
+const errorCode = (err) => err?.code ?? err?.message ?? String(err);
+
+const parseArgs = (argv, io) => {
+  const opts = { check: false, cwd: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--check') {
+      opts.check = true;
+      continue;
+    }
+    if (arg === '--cwd') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) return { error: '--cwd needs a directory' };
+      try {
+        if (!io.stat(value).isDirectory()) return { error: `--cwd ${safe(value)} is not a directory` };
+      } catch (err) {
+        return { error: `--cwd ${safe(value)}: ${safe(errorCode(err))}` };
+      }
+      opts.cwd = value;
+      i += 1;
+      continue;
+    }
+    return { error: `unknown argument: ${safe(arg)}` };
+  }
+  return opts;
+};
+
+// One git query → { stdout } or { failure } — a synchronous throw, ENOENT, a signal and an exit
+// outside `ok` are four named failures, never a silent empty answer.
+const gitQuery = (run, args, { cwd, env, input }, ok = [0]) => {
+  let r;
+  try {
+    r = run('git', args, { cwd, env: withGitPath(env), input, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  } catch (err) {
+    return { failure: `git ${args.join(' ')} threw synchronously (${safe(err?.message ?? err)})` };
+  }
+  if (r.error) return { failure: `git ${args.join(' ')} could not run (${safe(errorCode(r.error))})${r.error.code === 'ENOENT' ? ' — git is not on PATH' : ''}` };
+  if (r.signal) return { failure: `git ${args.join(' ')} was killed by ${safe(r.signal)}` };
+  const stderr = String(r.stderr ?? '').trim();
+  if (!ok.includes(r.status)) return { failure: `git ${args.join(' ')} exited ${r.status}${stderr ? ` (${safe(stderr)})` : ''}` };
+  return { stdout: Buffer.isBuffer(r.stdout) ? r.stdout : Buffer.from(r.stdout ?? '') };
+};
+
+const splitZ = (buf) => {
+  const out = [];
+  for (let start = 0; start < buf.length;) {
+    let end = buf.indexOf(0, start);
+    if (end === -1) end = buf.length;
+    if (end > start) out.push(buf.subarray(start, end));
+    start = end + 1;
+  }
+  return out;
+};
+
+// `check-attr --stdin -z` answers path NUL attribute NUL value NUL; `binary` set or `diff` unset
+// is git's own "binary" — the content skip, keyed by the path's exact bytes.
+const attributeSkips = (stdout) => {
+  const skips = new Set();
+  const fields = splitZ(stdout);
+  for (let i = 0; i + 2 < fields.length; i += 3) {
+    const [path, attribute, value] = [fields[i], fields[i + 1].toString('utf8'), fields[i + 2].toString('utf8')];
+    if ((attribute === 'binary' && value === 'set') || (attribute === 'diff' && value === 'unset')) skips.add(path.toString('hex'));
+  }
+  return skips;
+};
+
+const kindOfMode = (mode) => (mode === '120000' ? 'symlink' : mode === '160000' ? 'gitlink' : mode === '100644' || mode === '100755' ? 'file' : null);
+// An UNTRACKED entry git names with a trailing slash is its nested-repository rule (the `nested/`
+// line): name-only, like a gitlink, and counted as a skip by kind beside the never-committable stat
+// classes. A directory at a slash-less entry is a leaf that changed kind — a refusal.
+const kindOfStat = (st, nested) => (st.isSymbolicLink() ? 'symlink' : st.isFile() ? 'file' : st.isDirectory() ? (nested ? 'nested-repository' : 'directory') : 'never-committable');
+
+export const main = (argv, deps = {}) => {
+  const io = { ...defaultIo, ...(deps.io ?? {}) };
+  const run = deps.spawn ?? spawnSync;
+  const env = deps.env ?? process.env;
+  const opts = parseArgs(argv, io);
+  if (opts.error) return { code: 2, lines: [`control-bytes: usage — ${opts.error}`, USAGE] };
+  const cwd = opts.cwd ?? deps.cwd ?? process.cwd();
+  const location = resolveGitLocation(cwd, { spawn: run, env, realpath: io.realpath });
+  if (location.state !== 'work-tree') return { code: 1, lines: [refusalLine(`the git location is ${location.state} — ${safe(location.cause)}`)] };
+  const top = location.top;
+  const git = (args, input, ok) => gitQuery(run, args, { cwd: top, env, input }, ok);
+  const tracked = git(TRACKED_ARGV);
+  if (tracked.failure) return { code: 1, lines: [refusalLine(tracked.failure)] };
+  const entries = parseIndexEntries(tracked.stdout);
+  const unmerged = entries.filter((e) => e.stage !== 0).length;
+  if (unmerged > 0) return { code: 1, lines: [refusalLine(`the git index is UNMERGED (${unmerged} conflict-stage entr(ies)) — resolve the conflict, then re-run`)] };
+  const others = git(UNTRACKED_ARGV);
+  if (others.failure) return { code: 1, lines: [refusalLine(others.failure)] };
+  const domain = [...entries.map((e) => ({ path: e.path, mode: e.mode })), ...splitZ(others.stdout).map((path) => ({ path, mode: null }))]
+    .sort((a, b) => Buffer.compare(a.path, b.path));
+  if (domain.length === 0) return { code: 1, lines: [refusalLine(`the domain is EMPTY — no tracked and no untracked-not-ignored path under ${render(Buffer.from(top))}`)] };
+  const attributes = git(ATTRIBUTES_ARGV, Buffer.concat(domain.flatMap((d) => [d.path, NUL])));
+  if (attributes.failure) return { code: 1, lines: [refusalLine(attributes.failure)] };
+  const skipByAttribute = attributeSkips(attributes.stdout);
+  // core.symlinks: exit 1 = unset = git's default (true); `false` = the host materialises a tracked
+  // symlink as a regular file holding the target bytes — refusing it there would refuse forever.
+  const symlinks = git(SYMLINKS_ARGV, undefined, [0, 1]);
+  if (symlinks.failure) return { code: 1, lines: [refusalLine(symlinks.failure)] };
+  const symlinksMaterialised = symlinks.stdout.toString('utf8').trim() === 'false';
+  // Sparse checkouts: a tracked path whose skip-worktree bit is set (`ls-files -v`, a tag that
+  // uppercases to S — core-evidence's rule) may be ABSENT by design: a counted skip, never a refusal.
+  const sparse = git(SPARSE_ARGV);
+  if (sparse.failure) return { code: 1, lines: [refusalLine(sparse.failure)] };
+  const sparseSkip = new Set();
+  for (const record of splitZ(sparse.stdout)) {
+    if (record.length > 2 && String.fromCharCode(record[0]).toUpperCase() === 'S') sparseSkip.add(record.subarray(2).toString('hex'));
+  }
+
+  const findings = [];
+  const refusals = [];
+  const skippedByAttribute = [];
+  let skippedByKind = 0;
+  const judge = (bytes, surface, path) => {
+    let first = -1;
+    let count = 0;
+    for (let i = 0; i < bytes.length; i += 1) {
+      if (!isRefusedControlByte(bytes[i])) continue;
+      if (first === -1) first = i;
+      count += 1;
+    }
+    if (first !== -1) findings.push(`${render(path)} ${surface} offset ${first}: ${hexByte(bytes[first])}${count > 1 ? ` (+${count - 1} more)` : ''}`);
+  };
+  // An ABSENT path: a sparse (skip-worktree) tracked one is a counted skip; every other refuses.
+  const settleAbsent = (path, tracked) => {
+    if (tracked && sparseSkip.has(path.toString('hex'))) skippedByKind += 1;
+    else refusals.push(absent(path, tracked));
+  };
+  // A descriptor read's outcome, settled: ok judges the bytes on `surface`; anything else refuses.
+  const settle = (read, path, tracked, surface, named) => {
+    if (read.outcome === 'ok') {
+      if (read.bytes) judge(read.bytes, surface, path);
+      return true;
+    }
+    if (read.outcome === 'over-cap') refusals.push(`${render(path)}: over the read cap (${READ_CAP} bytes) — the gate read cap+1 bytes on the descriptor and stopped; ${surface === 'content' ? 'declare the path binary in .gitattributes or shrink it' : 'restore the link or shorten its target'}`);
+    else if (read.outcome === 'absent') settleAbsent(path, tracked);
+    else if (read.outcome === 'foreign') refusals.push(unreadable(path, `a ${read.className} where git named a ${named}`));
+    else refusals.push(unreadable(path, read.code));
+    return false;
+  };
+  for (const { path, mode } of domain) {
+    judge(path, 'name', path);
+    // Filesystem calls drop git's nested-repository trailing slash: lstat on a slash-terminated
+    // name FOLLOWS a symlink standing there (POSIX), which would skip a swapped link unjudged.
+    const fsPath = path[path.length - 1] === 0x2f ? path.subarray(0, path.length - 1) : path;
+    const full = Buffer.concat([Buffer.from(`${top}/`), fsPath]);
+    const tracked = mode !== null;
+    let kind = null;
+    if (tracked) {
+      kind = kindOfMode(mode);
+      if (kind === null) {
+        refusals.push(unreadable(path, `index mode ${mode} names no readable kind`));
+        continue;
+      }
+    } else {
+      try {
+        kind = kindOfStat(io.lstat(full), path[path.length - 1] === 0x2f);
+      } catch (err) {
+        if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+        else refusals.push(unreadable(path, errorCode(err)));
+        continue;
+      }
+    }
+    if (kind === 'gitlink') continue;
+    if (kind === 'directory') {
+      refusals.push(unreadable(path, 'a directory where git named a file'));
+      continue;
+    }
+    if (kind === 'never-committable' || kind === 'nested-repository') {
+      skippedByKind += 1;
+      continue;
+    }
+    if (kind === 'symlink') {
+      let leafIsFile = false;
+      if (symlinksMaterialised) {
+        try {
+          leafIsFile = io.lstat(full).isFile();
+        } catch (err) {
+          if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+          else refusals.push(unreadable(path, errorCode(err)));
+          continue;
+        }
+      }
+      if (leafIsFile) {
+        settle(readFileBytesNoFollowCapped(full, READ_CAP, io), path, tracked, 'symlink-target', 'symlink');
+        continue;
+      }
+      try {
+        judge(io.readlink(full, { encoding: 'buffer' }), 'symlink-target', path);
+      } catch (err) {
+        if (err?.code === 'ENOENT') settleAbsent(path, tracked);
+        else refusals.push(unreadable(path, err?.code === 'EINVAL' ? 'not a symlink where git named one' : errorCode(err)));
+      }
+      continue;
+    }
+    // An attribute skip covers the CONTENT only: the leaf still owes the descriptor's kind check.
+    const skipped = skipByAttribute.has(path.toString('hex'));
+    const read = skipped ? probeRegularFileNoFollow(full, io) : readFileBytesNoFollowCapped(full, READ_CAP, io);
+    if (settle(read, path, tracked, 'content', 'file') && skipped) skippedByAttribute.push(path);
+  }
+  const lines = [
+    `control-bytes: work tree ${render(Buffer.from(top))}`,
+    `paths judged: ${domain.length} · skipped by attribute: ${skippedByAttribute.length} · skipped by kind: ${skippedByKind} · findings: ${findings.length}`,
+    ...skippedByAttribute.map((path) => `skipped by attribute: ${render(path)}`),
+    ...findings,
+    ...refusals.map(refusalLine),
+  ];
+  return { code: findings.length > 0 || refusals.length > 0 ? 1 : 0, lines };
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = main(process.argv.slice(2));
+  (result.code === 2 ? process.stderr : process.stdout).write(`${result.lines.join('\n')}\n`);
+  process.exitCode = result.code;
+}