@sabaiway/agent-workflow-kit 1.27.0 → 1.29.0

package/CHANGELOG.md

@@ -4,6 +4,55 @@ 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.
 
+## 1.29.0 — Velocity scope C: an opt-in PreToolUse gate-approval hook
+
+A **feature** release (ships the bundled bridges unchanged at **2.1.0**). The shipped, probe-proven
+closure of the velocity trust-posture residual ([[AD-021]] scope C, recorded in **AD-037**) — a
+new opt-in `.claude/` writer, the family's third:
+
+- **`/agent-workflow-kit hook`** (`tools/gate-hook.mjs`) — places a **self-contained** hook runtime
+  (`references/hooks/gate-approve.mjs` → `.claude/hooks/agent-workflow-gates.mjs`; no kit imports, so
+  the placed copy survives an uninstall) and wires ONE `PreToolUse` "Bash" entry into
+  `.claude/settings.json`. Velocity writer discipline verbatim: `--dry-run` default, deployment-gated
+  `--apply`, symlink-safe, refuses unsafe modes in either settings file, merge-don't-clobber,
+  idempotent, never `settings.local.json`, never commits. Place-file-FIRST-then-wire; a malformed
+  existing `hooks` shape or a diverged-and-unwired target file is a STOP with zero writes (it refuses
+  to wire an unknown script as a hook); the target is re-verified no-follow immediately before wiring.
+- **The hook's decision ladder**, read against `docs/ai/gates.json` LIVE per call (one declaration,
+  two consumers with *Mode: gates* — editing gates.json never needs re-wiring): **(a)** a command
+  BYTE-EXACT to a declared gate `cmd` (trim-only; never a pattern — the rejected AD-021 shape),
+  invoked from the project root, under `default`/`acceptEdits` → `allow`; **(b)** a seeded-read-only
+  command carrying a documented runtime residual (output redirection, command/process substitution
+  `$(…)`/`` ` ``/`<(…)`, or the `--output` write-flag family — matched as a whole-command substring so
+  a quoted/escaped form can't hide it) → `ask`, overriding a settings allow rule (**proven live** on
+  Claude Code 2.1.185); **(c)** else no decision. Never `deny`. Fail-safe is **decoupled**: a broken
+  `gates.json` disables only (a), the guard keeps running; every anomaly exits 0, never 2. Validation
+  parity with the runner (`_README` included) — an invalid declaration approves nothing.
+- **Integration.** `/.claude/hooks/` joins the hidden-mode footprint registry; `uninstall` gains the
+  hook seam (reports the settings edit + preserves a still-wired or non-bundle file, removes only a
+  byte-identical unwired one and cleans an emptied `.claude/hooks/`, all lstat-no-follow + AD-011
+  preflight; the wired-probe reads DECODED settings JSON so an escaped `\/` path still counts as
+  wired); `status` gains one row (wired / file placed / declaration present) through the full
+  surface→view-model→renderers pipeline; the velocity residual notice + SKILL/README point at the
+  shipped hook instead of a "deferred" one. Kit-only; the runtime + writer ride the tarball.
+- **Review.** Council at the diff converged over four rounds (codex + agy, grounded): every finding
+  closed one obfuscation-of-a-string-scan class (process substitution, quoted/escaped `--output`,
+  JSON-escaped `\/`) or a TOCTOU/symlink window — folded by code with red→green regressions; the
+  final round was codex **ship** + agy **SHIP**, 0 blockers / 0 majors.
+
+## 1.28.0 — Lens-mirror guards the checked-vs-unchecked plan boundary
+
+A **feature** release (template + test only; ships the bundled bridges unchanged at **2.1.0**).
+The kit's half of the §9 sharpening:
+
+- **`references/templates/agent_rules.md` (B5)** — the byte-identical sharpened lens bullet (see
+  the memory 1.9.0 entry): a plan carries only checked syntax plus literal fixture/schema
+  fragments a named test validates; un-run, logic-bearing syntax never lives in plan prose.
+- **`test/lens-mirror.test.mjs`** — Set-1 gains the two new tokens `checked syntax` +
+  `logic-bearing`, pinned inside the lens region of all four files (engine planning §9, engine
+  procedures, both templates); template byte-identity unchanged; non-vacuity proven by an
+  injected red→green (a broken token fails the guard twice over — region + byte-identity).
+
 ## 1.27.0 — Cost-tiered execution: the `gates` runner + the `agents` cheap-lane writer
 
 A **feature** release (ships the bundled bridges unchanged at **2.1.0**). Two new modes move

package/README.md

@@ -235,8 +235,9 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + backend readiness (default Reviewed when a backend is ready, Council on request, slot-aware incl. Delegated) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same). `--override <slot>=<recipe>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit uninstall` | opt-in, any time | **guarded teardown** — the inverse of `init` / `setup`. Removes only what's **provably ours** (managed skill dirs + bridge wrappers; in a project, the hidden-mode git-ignore block it added + the pre-commit hook it installed); **never deletes** your `docs/ai` / `AGENTS.md` (prints the exact `rm` to run by hand) or your `.claude/settings.json` (prints an **edit** — remove the attribution key, review any velocity `permissions.*` — never an `rm`). Always `--dry-run` first; preflight-then-mutate; never commits. |
-| `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a redirection/command-substitution residual remains, closed by a deferred hook); a direct commit/push/publish still asks. `--dry-run` first. |
+| `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
+| `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. Preview by default; never writes `settings.local.json`; never commits. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 

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: '1.27.0'
+  version: '1.29.0'
 ---
 
 # agent-workflow-kit
@@ -273,6 +273,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/run-gates.mjs [--cwd <project>] [--only <id>
 
 The declaration is **seeded at bootstrap** (the template loop, step 6) and **ensured-if-missing on upgrade** from THIS kit's own template twin (*Mode: upgrade* step 3) — independent of the installed memory substrate's age; an existing file is always **preserved byte-for-byte**. It is deliberately **not** a delegation-required memory asset: gates are optional, and absence is an honest runner outcome, not a deployment failure.
 
+Declared gates can also be **auto-approved** (no permission prompt on a byte-exact invocation from the project root) via the opt-in PreToolUse hook — *Mode: hook*: the SAME declaration, a second consumer; editing gates.json needs no re-wiring.
+
 **Invariants:** the runner writes nothing · never commits · never runs a subscription CLI · executes only the project's OWN declared commands (never a kit-invented one) · the bash contract fails loud, never reinterprets.
 
 ### Mode: bootstrap
@@ -311,7 +313,7 @@ The declaration is **seeded at bootstrap** (the template loop, step 6) and **ens
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
-11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
+11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then print the **report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts above, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat ends on **one** recommended next step — including the optional, opt-in `/agent-workflow-kit velocity` (a read-only allowlist so routine read-only commands stop prompting; *Mode: velocity*) or, once gates are declared, `/agent-workflow-kit hook` (auto-approve your own declared gate commands; *Mode: hook*) when nothing more pressing applies, never run without a yes. Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -511,7 +513,7 @@ It classifies every surface into four classes and acts accordingly:
 
 ### Mode: velocity
 
-The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below), closed by the deferred hook.
+The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below) — its closure is **shipped, opt-in: *Mode: hook***.
 
 **Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `1.3.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
 
@@ -520,7 +522,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
 2. **Ask the `acceptEdits` opt-in** via **`AskUserQuestion` where supported**, the safe option FIRST:
    - **"Keep per-edit approval prompts (recommended)"** — seed only the read-only allowlist; file edits still prompt.
-   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — but that same redirection/substitution residual means they are not *fully* closed until the deferred PreToolUse hook (family backlog). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
+   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — and the residual guard for the seeded core ships as the opt-in PreToolUse hook (*Mode: hook*; probe-proven on the `--output` family — current engine builds already intercept redirection/substitution upstream). Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
 3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json`.
 4. **Surface delegation-readiness, read-only.** If they want a step run Delegated, set it with `/agent-workflow-kit set-recipe --set plan-execution.execute=delegated` (*Mode: set-recipe*) or by hand-editing `docs/ai/orchestration.json`; **velocity itself never writes the orchestration config.**
 
@@ -540,6 +542,31 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/cheap-agents.mjs [--dry-run | --apply] [--cw
 
 **Invariants:** writer (writes only `.claude/agents/`) · preview by default · a diverged existing file is reported and preserved, never clobbered · never touches settings · never commits · vehicles are pinned to `model: haiku` + `effort: low` + read-only tools (content-tested).
 
+### Mode: hook
+
+The opt-in **gate-approval PreToolUse hook** — the family's third `.claude/` writer (velocity discipline), and the shipped closure of the velocity trust-posture residual (**AD-021 scope C, probe-proven in AD-037**). It places a **self-contained** hook runtime at `.claude/hooks/agent-workflow-gates.mjs` (no kit imports — it keeps working if the kit is uninstalled) and wires ONE `PreToolUse` `"Bash"` entry into `.claude/settings.json`. Per Bash call the hook then walks a decision ladder, first match wins:
+
+- **Auto-approve** a command **byte-identical** (leading/trailing trim only — no whitespace collapsing, no quote/glob/variable interpretation, no prefix or pattern matching, ever: patterns are what made AD-021 auto-seeding rejected) to a gate `cmd` declared in `docs/ai/gates.json` — read **LIVE on every call** (editing gates.json never needs re-wiring; one declaration, two consumers with *Mode: gates*) — invoked **from the project root** (gates run from the root by contract; the same bytes from a subdirectory are NOT approved) and under `default`/`acceptEdits` permission mode (an approval never loosens `plan`/`bypassPermissions`).
+- **Ask** on a command whose leading tokens match the velocity **seeded read-only core** when it carries the documented runtime residual — output redirection, command substitution, or the bounded `--output` write-flag family — surfacing a human prompt even where a seeded allow rule would have silently approved (**hook `ask` overrides an allow rule — proven live**: on Claude Code 2.1.185 a seeded `Bash(git log:*)` silently wrote a file via `git log --output=…`; with the hook wired the same call prompts). Detection is string-level and conservative: a quoted metacharacter may over-ask, never under-allow.
+- **Stay silent otherwise** — the normal permission flow proceeds unchanged. The hook **never emits `deny`**; nothing is hard-blocked.
+
+**Honest residual status (AD-037):** current engine builds already intercept `>` redirection and `$()` substitution upstream (observed headless on 2.1.185); the **`--output` family was proven open** and is the seam this hook demonstrably closes. The guard still covers all three documented classes (defense-in-depth — engine behavior may vary across surfaces/versions). **Fail-safe, decoupled:** a missing/broken/invalid `gates.json` disables ONLY gate auto-approval — the residual guard keeps running; every anomaly path exits 0 (the hook is never the blocker or the noise — the `gates` runner reports a broken declaration at its own point of use). **Not a sandbox:** it closes the named residual for the seeded core and auto-approves declared gates; it does not police arbitrary commands or user-added rules.
+
+**Trust posture (state it plainly when asking consent):** the hook removes the PROMPT only for commands the human already declared in `docs/ai/gates.json` — the same trust boundary as the `gates` runner, which executes them with the caller's privileges. **gates.json thereby becomes a privileged file**: whoever can edit it can get its commands auto-approved. An invalid declaration approves NOTHING (strict parse, exact validation parity with the runner).
+
+**Version-status routing** like the other writer modes (stamp head `1.3.0`; `--apply` enforces it in code).
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs [--dry-run | --apply] [--cwd <dir>]`:
+
+1. **`--dry-run` first, always** (the default — changes nothing): previews the placement and the exact settings entry it would merge. It STOPs (zero writes) on: a symlinked `.claude` / `.claude/hooks` / target file / non-regular `settings.json`; malformed settings JSON; a **malformed existing `hooks` shape** (never a merge-through-clobber); an unsafe `permissions.defaultMode` in **either** settings file; or a target hook file with **different** content while our entry is not wired (**it refuses to wire an unknown script as a PreToolUse hook** — the recovery is named: delete the file to reseed from the bundle).
+2. **Ask consent** via **`AskUserQuestion` where supported**, the no-change option first: keep prompting for gate commands, or place + wire the hook — presenting the trust posture above in plain language.
+3. **Only on an explicit yes**, re-run with `--apply`. It places the file FIRST, then wires settings (a wired-but-missing entry would error on every Bash call); merge-don't-clobber (foreign hooks/matchers/keys and existing permissions preserved; re-apply never duplicates); **settings hot-reload — the hook is active for new Bash calls, no session restart needed**. An identical existing file is *already current*; a diverged-but-already-wired file is reported, never clobbered or unwired.
+4. **Hidden-mode deployments:** after apply, run the hide-footprint reconcile (`node ${CLAUDE_SKILL_DIR}/tools/hide-footprint.mjs --dir <project> --reconcile`) — `/.claude/hooks/` is in the known-footprint registry; the apply report reminds you.
+
+**Invariants:** writes ONLY `.claude/hooks/agent-workflow-gates.mjs` + `.claude/settings.json` · never `settings.local.json` · never commits · exact-match approval only (no patterns) · never `deny` · never auto-wired by `init`/`upgrade` (placement stays opt-in — the AD-011/AD-034 boundary: init/upgrade may refresh placed things, never place new ones).
+
+**Exit codes:** `0` done / dry-run (incl. the reported diverged-but-wired state); `1` a precondition STOP; `2` bad arguments.
+
 ---
 
 ## Gotchas

package/capability.json

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

package/package.json

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

@@ -27,6 +27,7 @@ diverge:
 |---|---|---|---|---|
 | `/.claude/skills/` | Claude Code | dir | no | local-dev skills; absorbs the AD-013 one-off |
 | `/.claude/agents/` | Claude Code | dir | no | project subagent definitions (incl. the kit-placed cheap-lane vehicles) |
+| `/.claude/hooks/` | Claude Code | dir | no | project hooks (incl. the kit-placed gate-approval hook) |
 | `/.cursor/rules/` | Cursor | dir | no | project rule files |
 | `/.cursorrules` | Cursor (legacy) | file | **yes** | legacy single-file rules |
 | `/.codeium/` | Codeium/Windsurf | dir | no | home-scoped launchers live under `~/`, out of scope |

package/references/hooks/gate-approve.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+// gate-approve.mjs — the agent-workflow PreToolUse gate-approval hook. Bundled at
+// references/hooks/gate-approve.mjs; PLACED (copied) by `/agent-workflow-kit hook` to
+// <project>/.claude/hooks/agent-workflow-gates.mjs and wired as a `PreToolUse` "Bash" hook in
+// .claude/settings.json.
+//
+// SELF-CONTAINED by contract: the placed copy must run on machines without the kit — no kit
+// imports, dependency-free, Node >= 18, no side effects on import. Two constants are baked
+// FROZEN COPIES of the velocity-profile.mjs exports (a placed file cannot import the kit):
+// SEEDED_READONLY_CORE ≡ UNIVERSAL_READONLY_ALLOWLIST and RESIDUAL_FORMS ≡
+// RUNTIME_RESIDUAL_FORMS — drift-guarded by the kit's test/gate-hook-core-parity.test.mjs.
+//
+// It reads <project root>/docs/ai/gates.json LIVE on every invocation (AD-035: one declaration,
+// two consumers — editing gates.json never requires re-wiring). The project root resolves from
+// $CLAUDE_PROJECT_DIR (the stdin `cwd` may be a subdirectory), falling back to the stdin `cwd`
+// only when the env is absent.
+//
+// Decision ladder for every Bash PreToolUse call — first match wins:
+//   (a) declared-gate EXACT match → allow. Byte-identical (leading/trailing trim only — no
+//       whitespace collapsing, no quote/glob/variable interpretation, no prefix or pattern
+//       matching: patterns are exactly what made AD-021 auto-seeding fragile) to one declared
+//       gate `cmd`, AND the stdin `cwd` realpath-resolves to the project root (gates run FROM
+//       THE ROOT by contract — the same bytes from a subdirectory resolve relative paths
+//       differently), AND permission_mode is `default`/`acceptEdits` (an allow never loosens
+//       `plan`/`bypassPermissions`).
+//   (b) residual guard → ask. The command's leading tokens match the SEEDED read-only core AND
+//       the command carries a documented runtime residual (output redirection, command
+//       substitution, the bounded `--output` write-flag family) that a settings-level allow
+//       rule cannot see. Most-restrictive-wins: this surfaces a human prompt even where a
+//       seeded allow rule would have silently approved. Detection is deliberately string-level
+//       and conservative (no shell parsing in a dependency-free hook): a quoted metacharacter
+//       may over-ASK, never under-allow. Covers the kit-SEEDED core only, never arbitrary
+//       user-added rules.
+//   (c) everything else → NO decision: exit 0, no output — the normal permission flow proceeds
+//       unchanged. The hook NEVER emits `deny`.
+//
+// Fail-safe invariant, decoupled per function: a DECLARATION anomaly (missing / unreadable /
+// malformed / schema-invalid gates.json) disables ONLY exact-gate approval (a) — the residual
+// guard (b) needs no declaration and keeps running (a broken gates.json must not silently
+// reopen the seeded-allowlist hole). Only an INPUT anomaly (unparseable stdin, non-Bash
+// tool_name) disables the whole hook. EVERY anomaly path exits 0 — never exit 2 (exit 2 is an
+// immediate block; a hook that fires on every Bash call must never become the blocker or the
+// noise — run-gates.mjs already yells about a broken declaration at its own point of use).
+//
+// Trust posture: this hook only removes the PROMPT for commands the human already declared in
+// gates.json — the same trust boundary as run-gates.mjs, which executes those commands with the
+// caller's privileges. gates.json is thereby a privileged file; an invalid declaration approves
+// NOTHING (strict-parse-or-no-decision).
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const HOOK_EVENT_NAME = 'PreToolUse';
+export const BASH_TOOL_NAME = 'Bash';
+export const GATES_REL = 'docs/ai/gates.json';
+export const PROJECT_DIR_ENV = 'CLAUDE_PROJECT_DIR';
+export const DECISION_ALLOW = 'allow';
+export const DECISION_ASK = 'ask';
+// The only modes an `allow` may be emitted under — an allowlist, so an unknown future mode is
+// fenced closed by default. The residual guard (b) is NOT mode-fenced: an `ask` never loosens.
+export const ALLOW_PERMISSION_MODES = Object.freeze(['default', 'acceptEdits']);
+
+// Baked frozen copy of velocity-profile.mjs UNIVERSAL_READONLY_ALLOWLIST (the audited read-only
+// core velocity seeds as settings allow rules). Drift-guarded — never edit here alone.
+export const SEEDED_READONLY_CORE = Object.freeze([
+  'Bash(git status:*)',
+  'Bash(git diff:*)',
+  'Bash(git log:*)',
+  'Bash(git show:*)',
+  'Bash(git ls-files:*)',
+  'Bash(git check-ignore:*)',
+  'Bash(git branch --list:*)',
+  'Bash(npm view:*)',
+  'Bash(npm ls:*)',
+  'Bash(npm outdated:*)',
+  'Bash(ls:*)',
+  'Bash(cat:*)',
+  'Bash(head:*)',
+  'Bash(tail:*)',
+  'Bash(wc:*)',
+  'Bash(readlink:*)',
+  'Bash(which:*)',
+  'Bash(grep:*)',
+]);
+
+// Baked frozen copy of velocity-profile.mjs RUNTIME_RESIDUAL_FORMS (the documented residual a
+// settings-level allow rule cannot see). Drift-guarded — never edit here alone.
+export const RESIDUAL_FORMS = Object.freeze({
+  writeRedirections: Object.freeze(['>', '>>', '1>', '2>', '&>', '>|']),
+  // `$(…)` + backtick + process substitution `<(…)` all RUN a nested command (`>(…)` is caught by
+  // the `>` redirection scan). Bare `<` is input redirection (reads a file — read-only commands may
+  // already do that), so it is deliberately NOT here.
+  commandSubstitutions: Object.freeze(['$(', '`', '<(']),
+  // The `--output` write-flag family, matched as a raw SUBSTRING of the whole command (never a
+  // whitespace-token check): the hook sees the pre-shell command string, so `--output=f`,
+  // `"--output=f"`, `'--output' f`, and `\--output` must all trip it — over-asking on a benign
+  // `--output-indicator` is the safe direction (never under-allow a real write flag through quotes).
+  boundedWriteFlags: Object.freeze(['--output']),
+});
+
+export const RESIDUAL_CLASS_REDIRECTION = 'output redirection';
+export const RESIDUAL_CLASS_SUBSTITUTION = 'command substitution';
+export const RESIDUAL_CLASS_OUTPUT_FLAG = 'a bounded --output write flag';
+
+const EXIT_OK = 0;
+const UTF8 = 'utf8';
+const BASH_ALLOW_PATTERN = /^Bash\((.+):\*\)$/u;
+const WHITESPACE_PATTERN = /\s+/u;
+const GATE_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const GATE_CMD_NEWLINE_PATTERN = /[\r\n]/u;
+const GATE_KEYS = Object.freeze(['id', 'title', 'cmd']);
+const README_KEY = '_README';
+const GATES_KEY = 'gates';
+
+// ── declaration (validation parity with run-gates.mjs) ────────────────────────────────
+
+// Self-contained restatement of run-gates.mjs `validateDeclaration`, at EXACT parity including
+// the optional `_README` string — a declaration the runner accepts is never rejected here (else
+// every template-shaped declaration would approve nothing), and one the runner rejects never
+// approves anything. Returns a boolean shape instead of throwing: anomalies go dark, not loud.
+export const validateDeclarationShape = (parsed) => {
+  const invalid = { ok: false };
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return invalid;
+  for (const key of Object.keys(parsed)) {
+    if (key !== README_KEY && key !== GATES_KEY) return invalid;
+  }
+  if (parsed[README_KEY] !== undefined && typeof parsed[README_KEY] !== 'string') return invalid;
+  if (!Array.isArray(parsed[GATES_KEY])) return invalid;
+  const seenIds = new Set();
+  for (const gate of parsed[GATES_KEY]) {
+    if (gate === null || typeof gate !== 'object' || Array.isArray(gate)) return invalid;
+    for (const key of Object.keys(gate)) {
+      if (!GATE_KEYS.includes(key)) return invalid;
+    }
+    for (const key of GATE_KEYS) {
+      if (typeof gate[key] !== 'string' || gate[key].trim() === '') return invalid;
+    }
+    if (GATE_CMD_NEWLINE_PATTERN.test(gate.cmd)) return invalid;
+    if (!GATE_ID_PATTERN.test(gate.id)) return invalid;
+    if (seenIds.has(gate.id)) return invalid;
+    seenIds.add(gate.id);
+  }
+  return { ok: true, gates: parsed[GATES_KEY] };
+};
+
+// Read + strictly validate the LIVE declaration. Any declaration anomaly returns null — ladder
+// (a) goes dark while the residual guard (b) keeps running (the decoupled fail-safe invariant).
+export const readDeclarationGates = (projectRoot, deps = {}) => {
+  const readFile = deps.readFile ?? readFileSync;
+  if (typeof projectRoot !== 'string' || projectRoot === '') return null;
+  try {
+    const validated = validateDeclarationShape(JSON.parse(readFile(join(projectRoot, GATES_REL), UTF8)));
+    return validated.ok ? validated.gates : null;
+  } catch {
+    return null;
+  }
+};
+
+// ── seeded-core prefix + residual detection (ladder b) ────────────────────────────────
+
+const getAllowCommandPrefix = (pattern) => {
+  const match = pattern.match(BASH_ALLOW_PATTERN);
+  return match ? match[1] : undefined;
+};
+
+const tokenizeCommand = (command) => command.trim().split(WHITESPACE_PATTERN).filter(Boolean);
+
+const CORE_PREFIX_TOKEN_LISTS = Object.freeze(
+  SEEDED_READONLY_CORE.map(getAllowCommandPrefix)
+    .filter(Boolean)
+    .map((prefix) => Object.freeze(tokenizeCommand(prefix))),
+);
+
+// `Bash(git status:*)` approves `git status <anything>` at a word boundary — the guard matches
+// the same way: a core pattern's tokens must be the command's LEADING tokens exactly.
+export const matchSeededCorePrefix = (command) => {
+  const tokens = tokenizeCommand(command);
+  const matched = CORE_PREFIX_TOKEN_LISTS.find(
+    (prefixTokens) =>
+      prefixTokens.length <= tokens.length && prefixTokens.every((token, index) => tokens[index] === token),
+  );
+  return matched ? matched.join(' ') : null;
+};
+
+// String-level, conservative: the hook sees the PRE-SHELL command string, so every class is a raw
+// substring scan (never a whitespace-token check — a token check misses `"--output=f"` / `'>' f`
+// where the quotes are still in the string but the shell will strip them). A quoted metacharacter
+// or write flag may over-ASK, never under-allow (no shell parsing in a dependency-free hook).
+export const detectResidualClasses = (command) => {
+  const classes = [];
+  if (RESIDUAL_FORMS.writeRedirections.some((form) => command.includes(form))) {
+    classes.push(RESIDUAL_CLASS_REDIRECTION);
+  }
+  if (RESIDUAL_FORMS.commandSubstitutions.some((form) => command.includes(form))) {
+    classes.push(RESIDUAL_CLASS_SUBSTITUTION);
+  }
+  if (RESIDUAL_FORMS.boundedWriteFlags.some((flag) => command.includes(flag))) {
+    classes.push(RESIDUAL_CLASS_OUTPUT_FLAG);
+  }
+  return classes;
+};
+
+// ── the decision ladder (pure core) ───────────────────────────────────────────────────
+
+export const decideBashCall = ({ command, permissionMode, cwdIsProjectRoot, gates }) => {
+  const trimmed = command.trim();
+  // (a) declared-gate exact match — all three invariants (declaration valid, cwd = project
+  // root, mode in the allow fence) must hold; otherwise fall through, never error.
+  if (Array.isArray(gates) && cwdIsProjectRoot === true && ALLOW_PERMISSION_MODES.includes(permissionMode)) {
+    const declaredGate = gates.find((gate) => gate.cmd.trim() === trimmed);
+    if (declaredGate !== undefined) {
+      return {
+        permissionDecision: DECISION_ALLOW,
+        permissionDecisionReason: `agent-workflow gates: byte-exact match of declared gate "${declaredGate.id}" (${GATES_REL}), invoked from the project root`,
+      };
+    }
+  }
+  // (b) residual guard — no declaration needed; not mode-fenced (an ask never loosens).
+  const corePrefix = matchSeededCorePrefix(trimmed);
+  if (corePrefix !== null) {
+    const residualClasses = detectResidualClasses(trimmed);
+    if (residualClasses.length > 0) {
+      return {
+        permissionDecision: DECISION_ASK,
+        permissionDecisionReason: `agent-workflow residual guard: read-only-seeded "${corePrefix}" carries ${residualClasses.join(' + ')} — a settings allow rule cannot see runtime shape; confirm by hand`,
+      };
+    }
+  }
+  // (c) no decision — the normal permission flow proceeds unchanged.
+  return null;
+};
+
+// ── stdin-driven main ─────────────────────────────────────────────────────────────────
+
+const resolveRealpath = (maybePath, realpath) => {
+  if (typeof maybePath !== 'string' || maybePath === '') return null;
+  try {
+    return realpath(maybePath);
+  } catch {
+    return null;
+  }
+};
+
+// Parse one PreToolUse stdin payload and run the ladder. Returns the decision object or null
+// (null → no output, exit 0). Injectable deps keep the tests hermetic.
+export const runHook = (rawInput, deps = {}) => {
+  const env = deps.env ?? process.env;
+  const realpath = deps.realpath ?? realpathSync;
+  const parseInput = () => {
+    try {
+      return JSON.parse(rawInput);
+    } catch {
+      return null;
+    }
+  };
+  const input = parseInput();
+  // Input anomaly → the WHOLE hook goes dark (distinct from a declaration anomaly, which only
+  // darkens ladder (a)).
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) return null;
+  if (input.tool_name !== BASH_TOOL_NAME) return null;
+  const command = input.tool_input === null || typeof input.tool_input !== 'object' ? undefined : input.tool_input.command;
+  if (typeof command !== 'string' || command.trim() === '') return null;
+
+  const envRoot = env[PROJECT_DIR_ENV];
+  const projectRoot =
+    typeof envRoot === 'string' && envRoot !== '' ? envRoot : typeof input.cwd === 'string' ? input.cwd : null;
+  const rootReal = resolveRealpath(projectRoot, realpath);
+  const cwdReal = resolveRealpath(input.cwd, realpath);
+  return decideBashCall({
+    command,
+    permissionMode: input.permission_mode,
+    cwdIsProjectRoot: rootReal !== null && cwdReal !== null && rootReal === cwdReal,
+    gates: readDeclarationGates(projectRoot, deps),
+  });
+};
+
+export const formatDecision = (decision) =>
+  JSON.stringify({ hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME, ...decision } });
+
+const readStdin = async () => {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString(UTF8);
+};
+
+export const main = async () => {
+  // Exit 0 on EVERY path — never exit 2 (an immediate block), never a top-level throw: this
+  // fires on every Bash call and must never become the blocker or the noise.
+  try {
+    const decision = runHook(await readStdin());
+    if (decision !== null) process.stdout.write(`${formatDecision(decision)}\n`);
+  } catch {
+    // Deliberately dark: anomalies are the runner's job to report at its own point of use.
+  }
+  return EXIT_OK;
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main().then((code) => process.exit(code));

package/references/templates/agent_rules.md

@@ -65,7 +65,7 @@ Before proposing changes or committing, review against:
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic is the trigger to write the test instead.
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.

package/tools/commands.mjs

@@ -119,6 +119,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Place bundled cheap-model subagent definitions for mechanical work — sweeps, changelog skeletons, gate triage (Claude Code; opt-in; preview first).',
   },
+  {
+    key: 'hook',
+    invocation: invocationOf('hook'),
+    group: 'Configure',
+    kind: WRITER,
+    oneLine: 'Auto-approve your own declared gate commands (docs/ai/gates.json) via a Claude Code hook — exact matches only, previews first (opt-in).',
+  },
   {
     key: 'recipes',
     invocation: invocationOf('recipes'),
@@ -164,8 +171,8 @@ export const kindOf = (key) => byKey.get(key)?.kind ?? null;
 // (`upgrade`) OR the full slash form (`/agent-workflow-kit upgrade`); the first word is significant
 // and trailing args are ignored. Precise semantics:
 //   undefined / null / '' / whitespace-only / the exact bare invocation → 'bootstrap'
-//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/uninstall/help)
-//     → that mode
+//   a known first token (upgrade/status/setup/backends/recipes/procedures/velocity/agents/hook/
+//     gates/set-recipe/uninstall/help) → that mode
 //   anything else (unrecognized / ambiguous) → 'help'  (read-only — NEVER a writer/guarded mode)
 export const routeInvocation = (token) => {
   if (token == null) return BARE_INVOCATION_MODE;

package/tools/family-registry.mjs

@@ -44,6 +44,10 @@ import {
   readSettingsFile,
   resolveEffectiveMode,
 } from './velocity-profile.mjs';
+// The gate-hook writer's own wired-detection + placed path — reused by the settings survey (one
+// implementation; gate-hook imports only node builtins + velocity-profile, so no cycle).
+import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mjs';
+import { GATES_REL } from './run-gates.mjs';
 // The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
 // forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
 // nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
@@ -438,11 +442,32 @@ export const surveyVelocity = (dir, deps = {}) => {
   }
 };
 
+// gate hook: the opt-in PreToolUse gate-approval hook (Mode: hook) — wired (the settings entry, in
+// EITHER settings file: the hooks contract merges both), the placed hook file, and the gate
+// declaration it consumes. Read-only; the wired-detection is REUSED from the writer (gate-hook.mjs
+// isHookWired — one implementation, never a drifting copy).
+export const surveyGateHook = (dir, deps = {}) => {
+  try {
+    const d = resolve(dir);
+    const exists = deps.exists ?? existsSync;
+    const project = readSettingsFile(join(d, SETTINGS_FILE), { ...deps, cwd: d });
+    const local = readSettingsFile(join(d, SETTINGS_LOCAL_FILE), { ...deps, cwd: d });
+    return {
+      wired: isHookWired(project.data) || isHookWired(local.data),
+      filePlaced: Boolean(exists(join(d, GATE_HOOK_FILE_REL))),
+      declarationPresent: Boolean(exists(join(d, GATES_REL))),
+    };
+  } catch (err) {
+    return { error: localizeError(err) };
+  }
+};
+
 // the project-scoped settings survey (needs a project dir). Each area is independently localized-on-error.
 export const surveySettings = (dir, deps = {}) => ({
   recipes: surveyRecipes(dir, deps),
   attribution: surveyAttribution(dir, deps),
   velocity: surveyVelocity(dir, deps),
+  hook: surveyGateHook(dir, deps),
 });
 
 // bridges: HOST-scoped (no project needed). Wrapper command NAMES come from FAMILY_MEMBERS[].wrapperCmds