@sabaiway/agent-workflow-kit 10.6.0 → 11.1.0

package/CHANGELOG.md

@@ -4,6 +4,139 @@ 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.
 
+## 11.1.0 — the bootstrap offers enforcement on every project, and the advisor closes the loop (AD-131)
+
+Bootstrap steps 8–9 (the enforcement scripts + the pre-commit hook) used to decide by the step-1
+recon — a Python, Go or Rust project was denied the caps gate, the archivers and the hook for no
+proven reason, then `upgrade` reported `skipped-no-node-evidence` on the very tree the bootstrap left
+bare. The scripts are dependency-free Node the agent host already runs for step 7's navigator.
+Contract: `node-evidence.md` rev 2 (S8–S10 bound).
+
+**The offer, on every project.** `references/modes/bootstrap.md` steps 8–9 offer the scripts and the
+hook preview-first with a one-line why: the bootstrap seeds on `package-json` OR
+`deployed-node-scripts` OR the fact that the agent host is running the kit; the only skip condition
+is that the agent host cannot run them; the residual is stated (the hook runs `node scripts/<x>.mjs`,
+so a committer without `node` on PATH gets the hook's own loud failure). `deploy-tail.md` carries the
+same sentence once; the Windsurf launcher's step list names the offer once and copies nothing
+unconditionally; the by-hand "Non-Node projects follow the policy by hand" claims left the READMEs.
+The step-1 recon is a stack fact, never the criterion.
+
+**The advisor's `enforcement` item.** On a `docs/ai` tree whose node evidence answers `none` and
+whose `scripts/` is absent or holds no basename of the kit's own bundle (listed at run time through
+the probe's own `scriptsBundleRoot` seam, never a hardcoded list), Recommendations renders ONE
+optional offer: the exact bootstrap tail as a `HAND-APPLY:` line with both paths shell-quoted.
+Every other cell is silence or a stated skip naming the path — `package-json` /
+`deployed-node-scripts` render nothing and never list the bundle; a wrong-kind path, an unreadable
+probe (`<root>: <code> on <rel>`), an existing, linked or unreadable destination each skip by name;
+no `docs/ai` renders nothing. The probe spawns no git; the installer's refusal over a hook it did not
+write is stated in the posture note (pinned). The commit-guard item's installer-absent skip carries
+its own 155-char remedy (deploy the scripts, bootstrap steps 8–9, install the hook, re-run) on ANY
+evidence — never "run upgrade first".
+
+**A declined offer leaves no false claim.** Every install claim in the family is conditional on
+the yes — `installed on a yes` in the READMEs and the seeded `changelog.md` / `decisions.md`
+templates, `where installed` in the seeded `agent_rules.md`, `and the enforcement offer was
+accepted` in both visibility contracts — pinned by one (file, literal, count) table in
+`test/enforcement-offer-docs.test.mjs`; the visible wiring of `package.json` scripts is conditional
+on an existing `package.json` AND an accepted offer; on a no the docs command slots of
+`env_commands.md` and `AGENTS.md` carry a note (the caps + index gate run from the agent's own skill
+copy; the archive rotations need the scripts deployed) and never the skill's absolute path.
+
+**Pins, unchanged scripts.** The deployed scripts' basename fallback (no or a malformed
+`package.json` → the directory basename) was already there — `install-git-hooks.test.mjs` and
+`archiver-structure.test.mjs` pin it with a package.json-named control; no script changed.
+
+**Measured on itself (the first-pass-quality series' acceptance metric).** Executed delegated on ONE
+held codex session, eight accounted dispatches, every fold through it. Diff council: round 1 codex
+revise 0 blockers + 3 majors, agy SHIP, lens 0 + 2 majors; rounds 2–3 resolved the decline-path
+subarea at altitude; round 4 CLEAN from all three — four rounds against the 13-round baseline
+(AD-130). Three fold-induced findings, each caught by a test or gate before a receipt attested it.
+
+## 11.0.0 — the per-fold walk is a record, the cap is a refusal at the round table's own signal, and the fingerprint argv has one home (AD-130)
+
+Plan 2's two attestation rounds on CONVERGED bytes each found one member of the kit's own robustness
+list that the executor never received: the tagged sweep row got its brief, the untagged suite and
+generator rows did not. Nothing asked "does the tag cover the row" before the dispatch, nothing
+recorded the adversarial walk a fold owes, and past the round table's `cap reached` / `crossover`
+signal nothing refused the next round — on the release-run feature the table printed CROSSOVER from
+round 2 for eleven rounds and nothing acted on it. Rungs 4 and 5 of the first-pass-quality series
+close that, and the two fingerprint classes plan 1 measured RED (Issue-023 / Issue-024) close with
+them. Contracts: `robustness-literals.md` rev 2 (S10–S11 bound), `plan-review-loop/index.md` rev 6
+(S30–S33 bound), `release-run/index.md` rev 2.
+
+**Coverage is the generator's second mode.** `robustness-brief.mjs --plan <plan> --coverage` judges
+every `create`/`modify` row except a document (`.md`, `.txt`) or the shipped list itself: a class is
+PRESENT when the row file's BYTES carry a member literal of kind env/flag/ref/syscall/errno/argv as a
+BOUNDED token (a comment counts, `state` members are never searched), `uncovered` = present minus
+tagged, a `delete` row and an absent file are LISTED, a sweep row is judged over every path the facts
+leaf expands (`expandSweepPaths`, one home in `plan-shape-facts.mjs`); exit 0 covered / 1 naming each
+`row:class:literal` / 2 on a row file the 1 MiB no-follow read cannot deliver. Measured on itself: the
+first run over this very plan named `R01:spawn-outcome:ENOENT` and the tag grew before the next
+dispatch. `references/modes/robustness-brief.md` states the mode, its read surface and the bounds.
+
+**Every fold owes a walk, recorded.** `flow-writer internal-attestation <planId> --walk <file>` reads a
+closed JSON walk (`{ listVersion, rows: [{ id, class, checked }] }`) relative to the git COMMON dir,
+derives the obligation from the ADOPTED plan (every judged row, every class in TAGGED ∪ PRESENT needs a
+non-empty `checked`), records `uncovered` and never refuses on it; `round-open` for every round after
+the first refuses without an authoritative walk-carrying attestation at round N's coordinates, and
+`--justification` lifts that refusal as an echoed INPUT whose durable trail is the attestation's
+absence. A plan with no judgeable row owes no walk; a plan that lost adoption coverage fails closed
+by name (`resolveAdoptedPlan`, one home).
+
+**The cap is the round table's own signal, and terminal is digest equality.** The new pure leaf
+`tools/flow-round-gates.mjs` (`blockingItems`, `roundsForSignal`, `capIssue`, `walkIssue`,
+`escalationIssue`, `validateWalk`; `signalFor` imported from `review-rounds.mjs`, never modified)
+builds one round per authoritative head from its LANDED dispatches; on `cap reached` or `crossover`
+only, `round-open` refuses unless every blocking ITEM of every landed receipt of the latest head is
+covered by a disposition whose `findingDigest` equals `sha256(itemText)` — text mode the wrapper's own
+line, schema mode the `issue` field verbatim — and prints every uncovered item beside its digest. An
+enumeration failure on a readable manifest falls back to the `>= 1` floor with an ADVISORY; the
+checks run cap → walk → floor in the lock-free pass and again on the locked snapshot.
+
+**A finding with no proven narrow fix is never queued; a lost manifest is a record.** `round-land
+--dispose queued --finding <quote> --claim <invariant> --proof-kind consult-attestation|red-proof
+--proof-digest <d>` mints only on `decideFoldScope` ACCEPT `new-invariant`, with `debtId`/`debtDigest`
+DERIVED from the ONE resolved queue row `fold-scope` now returns (`normalize` exported, one home); a
+consult-attestation proof binds through `proposedFixDigest === sha256(itemDigest + "\n" + claim)`, a
+red-proof through the head's `base`, the tree `round-land` runs on and the row's `proof` field. The
+fourth arm `escalated --finding <quote> --override-digest <d>` resolves a `maintainer-override` of THIS round's vetoing
+receipt; the FIFTH arm `custody-lost --receipt <receiptDigest>` mints only on a REAL loss (`absent |
+foreign | error | malformed | foreign-identity | swapped`), covers every item of that receipt for the
+cap and is recordable whenever the loss is real. `flow-record-shape.mjs` admits `walk`, the queued
+trio (all-or-none), `escalated` and `custody-lost`; `FLOW_SCHEMA_VERSION` does not move.
+
+**The fingerprint argv has one home.** `core-evidence.mjs` exports `FINGERPRINT_CACHED_DIFF_ARGV` /
+`FINGERPRINT_UNSTAGED_DIFF_ARGV` carrying `--no-ext-diff --no-textconv --ignore-submodules=none`;
+`flow-delta-proof.mjs` imports them; both wrappers' bash twins (`emit_fingerprint_payload`,
+`assemble_code_diff`, the no-diff preflight) carry the flags, mirrored into `bridges/`, and
+`test/review-fingerprint-parity.test.mjs` EXTRACTS the preflight line and proves it on real git with a
+gitlink under `diff.ignoreSubmodules=all`. Issue-023 and Issue-024 close; `commit-guard`'s
+content-free refusal 2 narrows to a fail-closed backstop with a generic message that names no flag
+and no config key (`references/modes/commit-guard.md`).
+
+**Tests and records.** New suite `flow-round-gates.test.mjs`; the touched suites (`robustness-brief`,
+`flow-record`, `flow-writer`, `flow-dogfood.integration`, `core-evidence-hostile`,
+`commit-guard-content-free`, `review-fingerprint-parity`, `package-content` — the tarball pin 284 →
+285 — and `fold-scope`) green with real git; thirteen red-proof cases (34 `core-evidence red-proof`
+re-observations on the parked pre-fix trees); the source-size baseline re-recorded under one stated reason. Every fold of the three diff
+rounds rode the delegate's held session (AD-127): fourteen accounted dispatches, one session.
+
+### BREAKING
+
+- **Minimum bridge versions: codex-cli-bridge 3.7.0, antigravity-cli-bridge 5.6.0.** The fingerprint
+  domain moves on a repository configuring `textconv` (neutralised by `--no-textconv`) or
+  `diff.ignoreSubmodules` / `submodule.<name>.ignore` in `.git/config` or `.gitmodules` (both overridden
+  by `--ignore-submodules=none`): a kit-11 receipt and a pre-3.7.0 / pre-5.6.0 wrapper receipt hash the
+  same tree differently. `init` and `upgrade`
+  refresh a placed bridge (`bin/install.mjs`); a bridge never placed is never placed by them.
+- **`round-land --dispose queued` changes its operands:** `--debt-id` / `--debt-digest` are gone;
+  `--claim`, `--proof-kind` and `--proof-digest` are required together with `--finding`.
+- **`round-open` refuses where `--justification` used to lift:** past the round table's signal the
+  cap is never lifted by a justification; a missing walk is.
+- **The one-way door:** a flow store carrying any post-rung record form — an `internal-attestation`
+  with `walk`, a `queued` disposition with `claim`/`proofKind`/`proofDigest`, an `escalated` or a
+  `custody-lost` disposition — reads under kit >= 11 only. A pre-rung store still reads.
+
 ## 10.6.0 — a fold on delegated code rides the delegate's held session, judged from the ledger the kit already mints (AD-127)
 
 The 2026-08-30 `release-run` execution took thirteen diff-review rounds, and every fold was made by

package/README.md

@@ -117,12 +117,12 @@ your-repo/
     ├── tech_reference.md  ← configs & patterns
     ├── pages/             ← one spec per page/route
     └── history/           ← changelog archive (HOT→WARM→COLD)
-  + scripts/               ← caps · index · archive (Node path)
-  + pre-commit hook        ← keeps it all honest    (Node path)
+  + scripts/               ← caps · index · archive (installed on a yes)
+  + pre-commit hook        ← keeps it all honest    (installed on a yes)
 ```
 
 The Markdown memory is **stack-agnostic**; the `scripts/` + pre-commit hook are the **Node path**
-(dependency-free, `node --test`). Non-Node projects keep the same policy by hand.
+(dependency-free, `node --test`). They are offered on every project because the agent host runs them; a committer without Node on PATH gets a loud hook failure.
 
 Two **visibility** modes, chosen at deploy time: **visible** (committed with the repo) or **hidden**
 (same files in-tree but git-ignored via the project-local `.git/info/exclude`, so the repo "looks
@@ -225,7 +225,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 
 | Command | When | What happens |
 |---------|------|--------------|
-| `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
+| `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → offers enforcement (installed on a yes) → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps — then prints a **read-only** one-line backend-status line (what's set up vs missing); refreshes the already-placed bridges from the kit's bundled copies (never installs a new one — set one up with `/agent-workflow-kit setup`) |
 | `/agent-workflow-kit help` | any time | **read-only command index** — every command, grouped (Inspect / Configure / Orchestrate / Lifecycle) and tagged read-only / writer / guarded. The discoverable entry point, and where any unrecognized invocation lands (always read-only — a garbage invocation never writes). Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
@@ -270,7 +270,7 @@ It **never auto-commits** and **never overwrites** an existing `AGENTS.md` witho
 - **Plan lifecycle** — a capped plan (goal and boundary, module ledger, verification), ephemeral plan files, and a mandatory Cleanup phase.
 - **No silent failures** — every guard that rejects an action logs structured context.
 
-Enforcement ships as dependency-free **Node** scripts (`node --test`, no package manager assumed). Non-Node projects follow the same policy by hand.
+The dependency-free **Node** enforcement scripts (`node --test`, no package manager assumed) and their hook are offered on every project because the agent host runs them; a committer without Node on PATH gets a loud hook failure.
 
 ---
 
@@ -284,7 +284,8 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
    on /agent-workflow-kit in a repo, the kit:
    ├─ delegates ─▶ memory substrate   (healthy copy, else bundled fallback)
    ├─ injects   ─▶ workflow methodology  (live from the installed engine)
-   ├─ deploys   ─▶ AGENTS.md + docs/ai/ + Node scripts + pre-commit hook
+   ├─ deploys   ─▶ AGENTS.md + docs/ai/
+   │               + Node scripts + pre-commit hook (installed on a yes)
    ├─ detects   ─▶ optional backends   (codex / agy, read-only)
    └─ sets up   ─▶ a bridge (opt-in)   (place skill + link wrappers)
 ```

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: '10.6.0'
+  version: '11.1.0'
 ---
 
 # agent-workflow-kit
@@ -183,6 +183,14 @@ guarded — read `${CLAUDE_SKILL_DIR}/references/modes/bridge-settings.md` befor
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` before acting.
 
+### Mode: control-bytes
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/control-bytes.md` before acting.
+
+### Mode: robustness-brief
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/robustness-brief.md` before acting.
+
 ### Mode: receipt-deadline
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/receipt-deadline.md` before acting.

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its headless behaviour.
 metadata:
-  version: '5.5.0'
+  version: '5.6.0'
 ---
 
 # antigravity-cli-bridge

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -343,7 +343,7 @@ DEFAULT_AGY_REVIEW_MODEL="Gemini 3.7 Flash (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="5.5.0"  # aw-version-anchor
+AW_BRIDGE_VERSION="5.6.0"  # aw-version-anchor
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # D5 control-byte screen — IMMEDIATELY after resolution, BEFORE the off-frontier advisory (or any
@@ -867,8 +867,8 @@ warn_never_committable_untracked() {
 # implements the SAME serialization in node — cross-checked by the kit's
 # review-fingerprint-parity.test.mjs.
 emit_fingerprint_payload() {
-  git diff --cached --no-ext-diff
-  git diff --no-ext-diff
+  git diff --cached --no-ext-diff --no-textconv --ignore-submodules=none
+  git diff --no-ext-diff --no-textconv --ignore-submodules=none
   local path
   while IFS= read -r -d '' path; do
     if [[ -L "$path" ]]; then
@@ -1556,10 +1556,10 @@ assemble_code_diff() {
   emit_status_porcelain_filtered
   echo
   echo "=== staged diff (git diff --cached) ==="
-  git diff --cached --no-ext-diff
+  git diff --cached --no-ext-diff --no-textconv --ignore-submodules=none
   echo
   echo "=== unstaged diff (git diff) ==="
-  git diff --no-ext-diff
+  git diff --no-ext-diff --no-textconv --ignore-submodules=none
   echo
   echo "=== untracked file contents ==="
   local path
@@ -1834,7 +1834,7 @@ else
     cd "$(git rev-parse --show-toplevel)"
     # No-diff preflight — never spend a run on a clean tree. Never-committable untracked masks do
     # not count: the FILTERED domain is the review surface.
-    if git diff --quiet && git diff --cached --quiet && ! has_reviewable_untracked; then
+    if git diff --quiet --no-ext-diff --no-textconv --ignore-submodules=none && git diff --cached --quiet --no-ext-diff --no-textconv --ignore-submodules=none && ! has_reviewable_untracked; then
       echo "agy-review: no uncommitted changes to review — the working tree is clean." >&2
       warn_never_committable_untracked
       exit 0

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "provides": ["review", "probe"],
   "posture": { "model": "Gemini 3.7 Flash (High)" },
   "roles": {

package/bridges/codex-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '3.6.0'
+  version: '3.7.0'
 ---
 
 # codex-cli-bridge

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -372,7 +372,7 @@ CHATGPT_LOGIN_GUARD="Logged in using ChatGPT"
 # receipt this wrapper mints; scripts/release/version-sync.mjs bumps it under the one-anchor-per-file
 # rule, so a release can never leave it behind (the AD-053 drift class).
 AW_RECEIPT_BACKEND="codex"
-AW_BRIDGE_VERSION="3.6.0"  # aw-version-anchor
+AW_BRIDGE_VERSION="3.7.0"  # aw-version-anchor
 # The kill grace handed to timeout(1) as --kill-after, and recorded in the receipt as killGraceS:
 # ONE constant, so the number the ledger checks against the dispatch deadline is the number the run
 # actually applied.

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -284,7 +284,7 @@ DEFAULT_CODEX_EFFORT="xhigh"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by codex-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="codex"
-AW_BRIDGE_VERSION="3.6.0"  # aw-version-anchor
+AW_BRIDGE_VERSION="3.7.0"  # aw-version-anchor
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
 CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # Generous hard cap for a slow xhigh review (subscription latency varies).
@@ -527,8 +527,8 @@ warn_never_committable_untracked() {
 # implements the SAME serialization in node — cross-checked by the kit's
 # review-fingerprint-parity.test.mjs.
 emit_fingerprint_payload() {
-  git diff --cached --no-ext-diff
-  git diff --no-ext-diff
+  git diff --cached --no-ext-diff --no-textconv --ignore-submodules=none
+  git diff --no-ext-diff --no-textconv --ignore-submodules=none
   local path
   while IFS= read -r -d '' path; do
     if [[ -L "$path" ]]; then
@@ -811,10 +811,10 @@ assemble_code_diff() {
   emit_status_porcelain_filtered
   echo
   echo "=== staged diff (git diff --cached) ==="
-  git diff --cached --no-ext-diff
+  git diff --cached --no-ext-diff --no-textconv --ignore-submodules=none
   echo
   echo "=== unstaged diff (git diff) ==="
-  git diff --no-ext-diff
+  git diff --no-ext-diff --no-textconv --ignore-submodules=none
   echo
   echo "=== untracked file contents ==="
   local path
@@ -923,7 +923,7 @@ case "$mode" in
   code)
     # No-diff preflight — never spend a subscription run on a clean tree. Never-committable
     # untracked masks do not count: the FILTERED domain is the review surface.
-    if git diff --quiet && git diff --cached --quiet && ! has_reviewable_untracked; then
+    if git diff --quiet --no-ext-diff --no-textconv --ignore-submodules=none && git diff --cached --quiet --no-ext-diff --no-textconv --ignore-submodules=none && ! has_reviewable_untracked; then
       echo "codex-review: no uncommitted changes to review — the working tree is clean." >&2
       warn_never_committable_untracked
       exit 0

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "posture": { "model": "gpt-5.6-sol", "effort": "xhigh", "tier": null },
   "provides": ["execute", "review"],
   "roles": {

package/capability.json

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

package/launchers/windsurf-workflow.md

@@ -26,8 +26,8 @@ reinvent any of it here; the kit's `SKILL.md` is the single source of truth.
      attribution) as ONE structured multi-question prompt; record each answer individually,
      write nothing until ALL are answered** →
      create `AGENTS.md` (+ `CLAUDE.md` symlink) from `<KIT_DIR>/references/templates/` →
-     deploy `docs/ai/` → copy `<KIT_DIR>/references/scripts/*.mjs` (Node projects) →
-     wire/hide per visibility → install the pre-commit hook → stamp `docs/ai/.workflow-version`.
+     deploy `docs/ai/` → offer the enforcement scripts + pre-commit hook (on a yes: copy `<KIT_DIR>/references/scripts/*.mjs`, install the hook) →
+     wire/hide per visibility → stamp `docs/ai/.workflow-version`.
 4. Report what was filled with real data vs left as TODO, then **ask before committing** —
    never auto-commit.
 

package/package.json

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

@@ -17,7 +17,7 @@ The user chooses at bootstrap whether the AI artifacts are visible in the repo o
 **explicit up-front question** (bootstrap step 2), never an assumed default. The two modes then
 diverge:
 
-- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
+- **visible** — artifacts are committed. When a `package.json` exists and the enforcement offer was accepted, wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`); add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`) either way. This is the canonical model.
 - **hidden** (in-tree) — same files on disk, but the repo "looks normal": the AI/agent footprint is git-ignored via **one managed block in the project-local `.git/info/exclude`** (resolved with `git rev-parse --git-path info/exclude` — never the machine-global `core.excludesFile`, which would affect every repo on the host; **AD-014** amends **AD-006**). The kit's `tools/hide-footprint.mjs` is the single writer: it covers `KIT_OWN_PATHS ∪ the present subset of KNOWN_FOOTPRINT` (the full footprint table below — the kit's own artifacts **and** every other AI/agent tool's files). Per path: a **tracked** file → **ASK** (an exclude does nothing for it; only `git rm --cached` un-tracks it — the tool prints that command and never runs it); an untracked path already covered by a **tracked `.gitignore`** → dropped (redundant); a **present** file whose name is generic enough to be ambiguous (`falsePositiveRisk`) → **ASK**; everything else → **hidden**. `asks` are excluded from the block unless explicitly opted in. **Verify** treats a path as hidden only when it is **untracked AND ignored by our project-local block** (or a tracked `.gitignore`) — being ignored by the global excludes does **not** count. Re-running re-derives the block wholesale (sorted/deduped) → a clean re-run is a **zero-diff** no-op. On an existing global-excludes deployment the tool **detects + reports the residual legacy machine-global block and keeps it by default** (a harmless double-ignore; the local block wins precedence); removal is the explicit `--remove-global` (it prints the removed lines as a restorable backup), which **the agent only runs after asking** — another of the user's hidden repos on the same host may rely on the same root-anchored global lines. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly. Windows is supported (text edit, no symlinks; CRLF preserved).
 
 **Visibility changes what git sees — never how the agent works (the load-bearing invariant).** Both modes carry the **same** working memory and run the **same** session protocol: `docs/ai` and the deployed workflow artifacts (`AGENTS.md`, the added `scripts/`) are read at session start and maintained on task completion **identically** whether visible or hidden. (Hidden mode git-ignores a *wider* footprint — other AI/agent tools' files too — but that is only a **visibility** surface; the working memory the agent actually reads and maintains is `docs/ai` plus those artifacts.) Hidden mode only makes the repo *look* normal to git; it is **never** a license to skip, defer, or down-prioritise a doc/state update. The single difference is the destination: in hidden mode those updates live on disk and never enter a commit (the footprint is excluded), so a commit there carries only the project's own tracked files while `docs/ai` is still kept current locally — **git-ignored ≠ optional-to-maintain**. An agent that reads "git-ignored / `git status` clean" and infers the working memory is optional has the model backwards. (This is why bootstrap/upgrade never wire hidden-mode docs into a commit, yet the session protocol still mandates maintaining them.)

package/references/modes/bootstrap.md

@@ -1,6 +1,6 @@
 ### Mode: bootstrap
 
-<!-- opt-in-capability: none — the deployment action itself; the advisor only renders inside an existing deployment -->
+<!-- opt-in-capability: enforcement -->
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKILL_DIR}/references/shared/composition-handoff.md · ${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md · ${CLAUDE_SKILL_DIR}/references/shared/command-shapes.md
 
@@ -23,9 +23,9 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
 6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` + the seed `adr/` store + the seed `specs/` store from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys every template except `AGENTS.md`, `adr-record.md` and `SPEC_TEMPLATE.md` — the latter two are skill-home authoring references, never deployed). This deploys the HOT ADR window **`docs/ai/decisions.md`** and the seed navigator **`docs/ai/adr/log.md`** (its `adr/` subdir copies in wholesale), the spec store root **`docs/ai/specs/index.md`** (its `specs/` subdir copies in wholesale), the `.md` docs, **and** the three seeded, user-editable strict-JSON configs: **`docs/ai/orchestration.json`** (the per-project recipe defaults the `procedures` advisor reads), **`docs/ai/gates.json`** (the project's gate declaration — seeded as the no-consent EMPTY list; FILLING it is the consented `gates-init` preview, `${CLAUDE_SKILL_DIR}/references/modes/gates.md`), and **`docs/ai/autonomy.json`** (the per-project autonomy policy — seeded SPARSE with the onboarding note only, so it is exactly the computed defaults until the user declares levels via `/agent-workflow-kit set-autonomy` or by hand). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); the `.json` seeds carry no frontmatter (the docs cap-validator globs `*.md` only, so they are inherently skipped).
 7. **Fill templates** per the table below. **Then materialize the navigator, as the last `docs/ai` step:** the entry point declares `docs/ai/index.md` always-loaded and it is a GENERATED artifact with no template, so run `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<project>` and relay its one outcome line (`ensure-index: regenerated` / `already-current`, or a `write-refused` / `probe-failed` line naming the offending path — either is a STOP: resolve it before reporting the deploy, since the navigator the entry point declares does not exist yet). The generator runs from **this skill's own directory**, so a project with **no Node runtime** is covered too: the agent host runs it, and step 8's copy is not a precondition.
-8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
-9. **Wire / hide** per visibility (see [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting. Once the gate declaration is final-run-capable, the installer's optional consented `--commit-guard <kit commit-guard.mjs path>` arm binds commits to the green `run-gates --final` receipt (the Recommendations advisor surfaces the exact one-liner).
-   - **visible** — wire the `package.json` scripts + add the minimal `.gitignore`. **Do not run the hide tool.**
+8. **Offer enforcement on every project, preview-first.** Explain in one line that the dependency-free Node scripts are available because the agent host already runs their step-7 navigator; the only skip condition is that the agent host cannot run them. Preview the source and destination list and ask; on a yes copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. On a no, skip the hook in step 9 and say so; the docs command slots then name no project-local command — fill `env_commands.md` and the `Docs caps + index freshness` row of `AGENTS.md` with the same note: the caps + index gate run from the agent's own skill copy (the step-7 `--root=<project>` form) and the archive rotations need the scripts deployed. Never write the skill's absolute path into a deployed doc. They self-configure (project name from `package.json` or, without one, the directory basename; hierarchical/on-demand sections auto-discovered). The hook calls `node scripts/<x>.mjs` directly, so a committer without `node` on PATH gets the hook's own loud failure.
+9. **Wire / hide** per visibility (see [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). When the user accepts the enforcement offer, install the pre-commit hook: `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting. Once the gate declaration is final-run-capable, the installer's optional consented `--commit-guard <kit commit-guard.mjs path>` arm binds commits to the green `run-gates --final` receipt (the Recommendations advisor surfaces the exact one-liner).
+   - **visible** — when a `package.json` exists and the offer was accepted, wire its scripts (never create one for this); add the minimal `.gitignore` either way. **Do not run the hide tool.**
    - **hidden** — run the kit's hide writer (one managed block in the **project-local** `.git/info/exclude`, covering the kit's own artifacts **and** every known AI/agent tool's footprint — never the machine-global excludes): `node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --dry-run` **first** (changes nothing, prints the plan), then the same without `--dry-run`. Handle what it surfaces, in plain language (never the tool's internal terms):
      - A path it reports as **already committed** can't be hidden by ignoring it and is **never un-tracked silently** — show the user the printed `git rm --cached <path>`, let them decide, then opt it in with `--include=<path>`.
      - A **present file with a generic name** it flags (e.g. `GEMINI.md`) → ask before `--include=<path>`.
@@ -58,5 +58,5 @@ Fill strategy:
 | `tech_reference.md` | Carry over real configs/patterns found in deps. |
 | `active_plan.md`, `handover.md` | TODO seed (e.g. "Bootstrap session — fill domain sections after first real work"). |
 | `decisions.md` | The HOT ADR window — seed `AD-001` (adopting this memory system), newest at the bottom. |
-| `adr/log.md` | The seed navigator — deployed as-is (the generator over the seeded HOT); regenerated by `archive-decisions.mjs`, never hand-edited. |
+| `adr/log.md` | The seed navigator — deployed as-is (the generator over the seeded HOT); regenerated by `archive-decisions.mjs` where the enforcement scripts are deployed (installed on a yes), otherwise it stays the seed — never hand-edited either way. |
 | `known_issues.md`, `changelog.md`, `pages/shared-patterns.md` | Empty template / first bootstrap entry. |

package/references/modes/commit-guard.md

@@ -7,7 +7,7 @@ The **read-only pre-commit guard** (strip-the-kit D10) — the last line of the
 Run `node ${CLAUDE_SKILL_DIR}/tools/commit-guard.mjs --check [--cwd <dir>]` — it refuses, each with a named recovery, on:
 
 1. **an INDEX that lags the verified working tree** — the gates and the fingerprint both describe the WORKING tree, while `git commit` builds the commit from the INDEX alone, and the fingerprint domain is identical whether a hunk sits staged or unstaged (staging a lone tracked modification does not even move it). So this arm runs FIRST, before the fingerprint is computed: it refuses when the working tree holds anything the index does not — tracked paths differing between index and worktree, or reviewable untracked-not-ignored paths (the SAME never-committable stat filter the fingerprint applies; ignored paths never refuse). An index entry carrying **skip-worktree** or **assume-unchanged** is invisible to `git diff`, so those entries are compared DIRECTLY against the worktree (type, symlink target, executable bit where `core.fileMode` says so, and the blob oid through git's own clean filters) — a de-materialised skip-worktree path is an ordinary sparse checkout and never refuses, while a missing assume-unchanged path does. The submodule probe forces `--ignore-submodules=none`, so `diff.ignoreSubmodules` / `submodule.<name>.ignore` cannot erase a dirty submodule from the comparison. Offending paths are named in THREE categories — plain lagging paths, paths held back by an index bit, and submodules — because their recoveries differ; ONE shared cap spans all of them, each category reserves a slot so no clause is ever nameless, the remainder is stated once, and every path is rendered as one escaped line. Recovery is ONE ordered sequence, and `git add -A` alone is NOT it: a bit-carrying entry must have its `skip-worktree` / `assume-unchanged` bit cleared FIRST (scoped to the paths the refusal names — never to everything `git ls-files -v` reports, which includes de-materialised sparse paths whose deletions would then be staged), then `git add -A`, then re-run `run-gates --final` at its RESOLVED path beside this tool, then commit the WHOLE tree. The listed paths are capped, so the loop is the completion signal: re-run the guard until it names none. A tracked **submodule** the index cannot prove current is named separately with its own recovery — commit or clean inside the submodule and stage the gitlink — because a root-level `git add -A` cannot capture a submodule's internal worktree changes. A submodule whose gitlink itself carries one of those index bits is **not probed at all**: it lags by construction. That is a deliberate REDUCTION — three consecutive review rounds each found a new way for a nested probe to answer "clean" wrongly (inherited superproject `GIT_*`, status config blindness, the submodule's OWN flagged entries, a symlink standing in for the directory) — and it stays a CONVERGING refusal, since clearing the bit is a recovery the guard prints and then falls silent on. An UNflagged submodule is judged by the ordinary probe exactly as before. **Fail-closed:** an undecidable git probe refuses with its own named cause, never a silent pass;
-2. **a CONTENT-FREE fingerprint over a DIRTY index** — the payload carries no bytes while the index really carries a change, which means staged content the fingerprint domain cannot see: a submodule gitlink hidden from `git diff` by `submodule.<name>.ignore` or `diff.ignoreSubmodules`. No receipt can describe what that commit will carry, so the guard refuses and names the CONFIGURATION as the recovery — clear the ignore setting (or set it to `none`) until `git diff --cached --no-ext-diff` shows the change, then re-run `run-gates --final`. Re-staging is not the recovery: the change is already staged;
+2. **a CONTENT-FREE fingerprint over a DIRTY index** — the payload carries no bytes while the index really carries a change: staged content the payload cannot see. No receipt can describe what that commit will carry, so the guard refuses fail-closed. Recovery names no flag or config key: make the staged change visible to `git diff --cached`, then re-run the resolved `run-gates --final`; re-staging alone is not the recovery because the change is already staged;
 3. no completed final record for the CURRENT fingerprint (the tree moved after the final run — any edit re-stales it);
 4. a RED latest attempt (a dead green never revives — the latest attempt at a fingerprint is authoritative);
 5. fingerprint before ≠ after on the receipt (the tree moved UNDER the final run);
@@ -24,7 +24,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/commit-guard.mjs --check [--cwd <dir>]` —
 
 **Boundary — what «the commit captures the tree» means for submodules.** The guard proves the SUPERPROJECT commit captures the SUPERPROJECT working tree. A superproject commit stores a submodule as a gitlink OID and never captures its file content — that content is the submodule's own commit boundary. The dirty-submodule refusal is therefore a best-effort COURTESY beyond the guard's boundary, and its completeness is bounded by what the submodule itself reports: a file held behind a `skip-worktree` / `assume-unchanged` bit in the SUBMODULE's own index is invisible to the submodule's status and so to this refusal. Deepening the nested probe was tried and abandoned — three consecutive review rounds each produced a new way for it to answer wrongly — so the honest contract is the boundary, not a completeness claim. Tracked as its own class.
 
-**Stated residual — the fingerprint can still be blinded by config.** Refusal 1 makes the COMMIT capture the whole current working tree. It does not make the RECEIPT unforgeable: `computeFingerprintPayload` still runs its diffs without `--ignore-submodules=none`, so under `diff.ignoreSubmodules=all` a submodule can be changed and its gitlink staged AFTER a green `--final` while the fingerprint stays put, and the stale receipt is reused. That is a receipt-collision defect, not an under-capture one — no commit ships less than the working tree because of it — and closing it means moving the node payload and both bash twins together (the AD-044 lockstep). Tracked as its own class. **Narrowed:** the case where the hidden gitlink is the ONLY staged change is now closed by refusal 2 — there the payload is empty and the index is not, which is decidable without touching the payload definition. A hidden gitlink riding ALONGSIDE other visible changes still produces an ordinary fingerprint and still reuses its receipt; that remainder is what the lockstep owns.
+**Stated residual — the payload flags close the config-blind class.** The fingerprint argv in the ONE node home, `core-evidence.mjs`, carries `--no-textconv --ignore-submodules=none` beside `--no-ext-diff`; both bash twins are parity-pinned to that set for their fingerprint and review-payload diffs, so host textconv and submodule-ignore configuration cannot hide staged bytes. Refusal 2 remains the fail-closed backstop for any DIRTY index whose staged content the payload still cannot see: it names making the change visible to `git diff --cached` and re-running the final gate, without guessing a flag or configuration key.
 
 **Human residual (stated, accepted):** `git commit --no-verify` bypasses any pre-commit hook — a self-discipline mechanism, not a security boundary.
 

package/references/modes/control-bytes.md

@@ -0,0 +1,91 @@
+### Mode: control-bytes
+
+<!-- opt-in-capability: none — a read-only gate entry; declaring the gate matrix is covered by gates-declaration -->
+
+Read-only **control-byte gate** over the work tree — it makes *"a raw control byte in a source"* a
+mechanical refusal instead of a reviewer's find. Measured 2026-08-30: an editor tool wrote a raw NUL
+into a test source, git classed the file as binary, and a NUL-carrying blob is exactly what a
+letter-level checker skips by kind. This mode judges BYTES, never letters, so it is language-neutral:
+every consumer of the kit can declare it, whatever language the project is written in.
+
+**What it judges.** The review-payload domain over the WORK TREE, from the work-tree root: tracked
+paths (`git ls-files -z`) plus untracked-not-ignored paths (`git ls-files --others --exclude-standard
+-z`). Three surfaces per path, in this order: the NAME is always judged; a regular file's CONTENT is
+judged unless the attribute skip below covers it (the skip covers content only); a symlink's TARGET
+string is always judged and the link is never followed. A path's kind is the index mode for a tracked
+path (`git ls-files -s -z`; a gitlink is name-only) and the lstat for an untracked one; the descriptor
+the read opens must report the same kind, or the path is unreadable. The predicate is over raw bytes:
+any byte in 0x00–0x08, 0x0B, 0x0C, 0x0E–0x1F or 0x7F refuses; TAB, LF and CR are the only admitted C0
+bytes; bytes at or above 0x80 are not judged (UTF-8 validity and C1 controls are not this tool's
+business). A finding names the path, the surface, the byte offset and the byte in hex; the render is
+injective — bytes decode as UTF-8 where valid, a control or line-separator code point (and a valid
+U+FFFD) renders as `\u{XXXX}`, an invalid byte as `\xNN`, a backslash as `\\` — so no output line carries a raw control
+byte or U+FFFD and two names differing only in an unrenderable byte render differently.
+
+**Binary by KIND, never by guess.** A path whose git attribute says `binary` or `-diff` has its
+CONTENT skipped by kind and is NAMED in the summary (one `git check-attr --stdin -z binary diff`
+over the whole domain — git's own answer, global and system attributes files included, because the
+tool runs under your env); its name and target are still judged. There is no extension allow-list
+and no size heuristic — a NUL in an unattributed file is the finding this gate exists for. A fixture
+that genuinely needs a control byte keeps it as an escape in source (`\x00`, `String.fromCharCode(0)`):
+the runtime string is byte-identical and the SOURCE stays clean. A never-committable stat class
+(device, FIFO, socket) and an untracked nested repository (git's `nested/` entry) are skipped by
+kind and counted — name judged, no content surface. On a host that materialises symlinks
+(`core.symlinks=false`) a tracked symlink's placeholder file is judged as its target string.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/control-bytes.mjs [--check] [--cwd <dir>]` (`--cwd` anchors at
+that directory's work-tree root):
+
+1. Plain run → the human report: the work-tree root, the counts (paths judged · skipped by attribute,
+   each named · skipped by kind · findings), then every finding as one line
+   `<path> <surface> offset <n>: 0x<hex>` (`(+N more)` when that surface carries more than one) —
+   under the SAME exit table as `--check`: the plain run is never a silent 0.
+2. **`--check`** → the gate spelling: the same report (counts, the named attribute skips, the
+   finding lines), then the gate exit code. **Exit 0** clean. **Exit 1** on a finding OR on a refusal —
+   refusals never pass and never skip silently, each with its own message: an UNREADABLE path
+   (EACCES, EIO, a descriptor whose kind disagrees with the named kind — distinct from an ABSENT
+   path git named that vanished before the read; a TRACKED absent path with the skip-worktree bit is
+   a sparse checkout, skipped by kind and counted); a git command that fails, is killed by a signal or
+   is not on PATH; an UNMERGED index; an EMPTY domain; a file over the read cap (16 MiB — read as at
+   most cap+1 bytes on the descriptor, never trusting the fstat size, so a file that grows after the
+   fstat still refuses; the message names the cap and the path); a git LOCATION that is not a work
+   tree. The location is a closed table of six states shared with the fingerprint and index
+   consumers through the kit's git-location leaf, judged on the REALPATH identity of the git dir,
+   the common dir and the work-tree top under the ambient env against the discovery from cwd with
+   every variable whose upper-cased name starts with `GIT_` removed (a case-insensitive host honours
+   `git_dir` too): `work-tree` (all three agree) proceeds; `not-a-repository` (git
+   itself answers not-a-git-repository, exit 128); `error` (ENOENT, a synchronous throw, a signal, a
+   realpath that cannot resolve, any other non-zero or unparsable answer); `redirected` (any of the
+   three differs — `GIT_WORK_TREE` at a second tree with the same git dir, or `GIT_COMMON_DIR` at a
+   second repository); `no-work-tree` (the git
+   dir agrees but `--show-toplevel` fails: bare, or cwd inside `.git`); `env-only` (the ambient env
+   reaches a repository the stripped discovery does not) — each refuses by its own state name. A
+   pre-commit hook's own env (`GIT_INDEX_FILE`, `GIT_PREFIX`, `GIT_CONFIG_PARAMETERS`,
+   `GIT_EXEC_PATH`) agrees and passes: the check is agreement, never a variable ban. **Exit 2**
+   usage — every operand is validated at parse; an unknown argument is usage. Every content read is
+   descriptor-bound (open, fstat, read on the descriptor), never a path read that a symlink swap
+   could redirect.
+3. **Wire it as a gate by hand — never without consent (AD-021/D9).** The candidate line for your
+   own `docs/ai/gates.json`: `{ "id": "control-bytes", "title": "No raw control byte in the work
+   tree", "cmd": "node \"<path-to-this-skill>/tools/control-bytes.mjs\" --check" }` — with the path
+   your project actually reaches the kit by, double-quoted inside the JSON string so a path with
+   spaces survives, executable from the project root. `gates-init` does not offer this entry; the full consent-fill contract for the
+   matrix is in `${CLAUDE_SKILL_DIR}/references/modes/gates.md`. Once declared, the opt-in
+   `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate.
+
+**Honest bounds (stated, accepted):** the work tree is judged at the moment of the read — a byte
+written after the run is caught on the next run, which is why the gate belongs in the pre-commit
+matrix; the attribute is the only "binary" signal, so a binary file with no attribute refuses until
+the project declares it; the tool reports and never edits — the remedy is the escape in source; a
+checkout PATH that is itself not valid UTF-8 is unreachable by any Node consumer (cwd is a string
+before git ever answers) and a non-UTF-8 LINKED git dir or common dir path refuses as `error` — a
+stated bound, not a case this tool judges; `O_NOFOLLOW` guards the
+LEAF only — a parent directory swapped for a symlink between git's answer and the open redirects the
+read (Node exposes no `openat2`/component-wise no-follow walk), so a mid-run parent swap is the same
+moment-of-the-read race bound as a byte written after the run: caught on the next run, inside the
+work tree the gate's verdict still refuses-or-reports, never silently skips.
+
+**Invariants:** read-only · never writes · never commits · spawns read-only `git` queries only
+(`ls-files`, `check-attr`, `config --get core.symlinks`, `rev-parse`) · judges bytes, never decoded text · skips by kind only, every
+skip named or counted · exit 0 clean / 1 finding or refusal / 2 usage · `main(argv, deps)` returns,
+never exits.