@sabaiway/agent-workflow-kit 14.11.0 → 14.12.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.
 
+## 14.12.0 — the upgrade offers the kit's own checkers as gates of your project, each only where it can run (AD-158)
+
+**The kit's own checkers can now be declared as gates of your project without a hand edit.** Until 14.12.0 no
+preview offered `control-bytes`, `plan-shape`, `spec-check` or `spec-coverage`, and the `control-bytes` document
+told a user to paste its entry into `docs/ai/gates.json` by hand. 14.12.0 adds a declare verb that previews them, and the
+upgrade's `tier` step now shows them as a fourth entry, `checker-gates-declared`, and writes them on the same one yes.
+No new upgrade item, no migration note and no lineage change: a project already at lineage `4.0.0` is offered them on
+its next upgrade. Story S4 of the epic `CONSUMERS-MOVE-ONTO-THE-FULL-FLOW`; contract
+`docs/ai/specs/kit/tier/checker-gates/` (new).
+
+- **`tools/checker-gates.mjs --cwd <project> [--apply] [--only <id>]…`.** Without a flag it writes nothing and
+  prints one line per checker: `declared`, `id-taken` (a gate with that id runs something else), `probe-unreadable`,
+  `not-applicable`, `offered` or `withheld`, with a detail where one applies; under an offered checker, its paste-ready
+  `entry:` line. The gates-file disclosure is printed once whenever a checker is offered or written. `--apply`
+  writes the offered entries; `--only <id>` (repeatable) narrows the write, and an id that is not offered is a usage
+  error. Exit 0 done, 1 one named refusal on stderr, 2 usage. A second `--apply` writes nothing.
+- **Each checker is offered only where it runs by design.** `control-bytes --check` needs a `.git` directory or
+  gitfile at the project root; `plan-shape --check --in-flight` is offered on any deployment; `spec-check --all`
+  needs a regular `docs/ai/specs/index.md`; `spec-coverage --check` needs a regular `docs/ai/spec-coverage.json`
+  and that store root. The command names the installed tool by its absolute, double-quoted path; a kit path that
+  cannot be written into a command withholds every checker that would be offered, by name, and writes nothing.
+- **Your declaration is only added to.** The write keeps every existing entry's value and order and the `_README`,
+  places each new entry as `gates-init` does (before a trailing coverage checker), must pass the declaration's
+  validation, and is atomic. A checker already declared in the form the verb writes, under any id, reads
+  `declared`. A missing, symlinked, non-regular, unreadable, unparseable or
+  invalid `docs/ai/gates.json`, or one whose coverage checker is already inert, misplaced or declared twice, is
+  reported by one name and nothing is written. The verb never removes an entry: an entry it wrote is removed by hand.
+- **The upgrade relays the preview before the ask.** While `checker-gates-declared` is offered, the `tier` step shows
+  the verb's lines, the disclosure and each `entry:` line included, before its one question.
+- **A matrix of only the kit's checkers is not project verification.** These four now count as kit-owned checkers,
+  so the kit's recommendations report a `docs/ai/gates.json` holding nothing else as carrying no
+  project-verification gate, as they already did for a lone `source-size` gate.
+- **The documents stop saying "declare it by hand".** `references/modes/gates.md` gains the checkers' paragraph,
+  `references/modes/control-bytes.md` step 3 names `--only control-bytes` beside its paste-ready line, and
+  `doc-parity` is no longer described as a project gate: it checks only the kit's own package. `epic-shape` and
+  `queue-audit` take a project operand, so they are not offered.
+
 ## 14.11.0 — the upgrade offers the epic and task settings and the epic store in one preview, and remembers a no (AD-157)
 
 **An upgraded project is now offered the epic tier's settings and store instead of being left to find them.** Up to

package/README.md

@@ -246,7 +246,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — **certifies coverage ONLY inside the `--final` run that owns the lcov** (ownership is exclusive by CONVENTION over the fixed path, not enforced — a concurrent writer to it is a stated residual, queued as LCOV-EXCLUSIVE-OWNERSHIP): an artifact on disk proves nothing about the tree it came from, so a standalone run prints its findings and states `attested=no` / `NO VERDICT` rather than a PASS (an lcov that predates an edit would otherwise certify a line the suite never executed). `attested=` claims a verdict was ISSUED, pass or fail — a run over uncovered lines still reads `attested=yes` and still exits 1, and a run whose coverage arm never executed (no lcov) reads `attested=no` even inside `--final`, because nothing was read and nothing is certified. The runner passes a nonce whose one-way commitment over `{nonce, fingerprint, base}` is the `final-start.attempt` it recorded; a context describing another tree, or matching no recorded attempt, is a REFUSAL, never a verdict. Findings are unchanged — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
 | `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — makes the commit capture the whole current working tree, so «verified» and «about to be committed» are the same bytes (the receipt itself has a stated residual — see the mode doc). FIRST it refuses an **INDEX that lags the verified working tree** (the gates and the fingerprint describe the WORKING tree while `git commit` takes the INDEX alone, and the fingerprint cannot tell them apart — so a lagging index used to ship a strict subset of what was verified): unstaged tracked paths or reviewable untracked-not-ignored paths, named up to a bounded cap with the remainder stated, a dirty tracked **submodule** named separately with its own recovery, and fail-closed on an undecidable probe. This deliberately blocks a partial commit. Then it binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |
 | `/agent-workflow-kit recommendations` | any time (every `upgrade` ends with it) | **read-only deployment advisor** (AD-044) — computes what in THIS deployment is configured sub-optimally (allowlist not seeded, autonomy render drifted, OS sandbox unavailable, gates undeclared, bridge friction, sandbox-mask clutter, an unacknowledged sandbox recipe, a feature-spec layer never adopted) and renders **verdict-first**: one composed verdict line (does anything need attention?), then each item as **{severity · what · one-line benefit · an optional `recipe:` line (the sandbox-lane live recipe, the worktrees-dir hand-apply-first grant advice, the agents hidden-mode reconcile follow-up, or the spec-adoption decline preview) · the exact consent-gated apply one-liner}**. The agent PRESENTS the section in the user's conversational language — every fact and count, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request — and runs EXACTLY the rendered one-liners only on your yes, surfacing each item's posture note first. Renders **present-even-when-empty** (`no recommendations — flow optimal.`); a failed probe degrades to a stated skip line. Registry strings are fact-true frozen one-line data (posture/risk notes live in the mode doc at the consent moment); the kit never seeds `sandbox.network.allowedDomains` / `filesystem.allowWrite` (**HAND-APPLY** territory), and the sandbox-lane item's convergence is a neutral fingerprint acknowledgement recorded by a consent-gated ack writer into `docs/ai/acks.json` — never a security key (the recipe is documented per bridge in `capability.json` `networkHosts` + `writableDirs`). `--cwd` is required (the target project is explicit); never writes, never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is a gate exit code for `docs/ai/gates.json`. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit doc-parity` | any time | **read-only doc-parity lint** (AD-049) — kills the doc-drift class where a mode-contract doc silently lags a code constant (a `--check` doc still reading `300` after the diff cap moved to `400`): a **closed, exported registry** binds each live constant (review caps, schema versions, the ledger's own class/scope vocabulary, and the autonomy-doctor EXIT/status/trusted-dir contract) to the exact token its `references/modes/*.md` contract must carry, and asserts the CURRENT value renders into every bound file — a drifted doc, an unreadable file, or an absent token **fails closed**. The values are sourced from the live imports (never re-typed), so the lint can't itself go stale; adding a binding is adding a checked entry (closed-world, edit-safe). `--check` is the gate exit code a kit maintainer runs: the lint checks the kit's own package. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit dispatch` | any time | **the delegation engine** — makes "how much does delegating a sub-task actually buy?" a measured number instead of a feeling. `check <file>` validates a sub-task brief's contract block and exits 0/1 naming the first violated field — **form only**: whether the task is genuinely bounded, its design decided and its acceptance adequate stays your judgment, and a well-formed absurdity passes here by construction. `advise --step-class <c>` answers the question that comes BEFORE that one — which vehicle should carry this kind of sub-task, whether it is even present on this machine, and what the ledger has already recorded for threads of that class (finished, failed, closed without a fold, and still open — counted separately) — and it decides nothing: it refuses no dispatch, gates no verb, and a choice that diverges from the advice is noted rather than blocked. It reads the filesystem only: nothing is launched to find out what is installed, an absent ledger prints "no recorded history", an unreadable one prints the store's own words, and either way the advice still prints. The same block appears as a footer under a form-valid `check` — never under a refusal, so it can never hide one. `register` pre-registers an acceptance wave (step classes, pairing key, minimum observations per class, the mean and first-pass thresholds) so the bar can never be chosen after the results it judges — immutable per wave. `observe` records ONE hand-written observation (`solo-construction`, the baseline whose ratio is 1 by construction — except over a scope measuring zero bytes, which has no ratio at all and is recorded ineligible by name — or `self-reported`) — delegated numbers are never hand-written, they are derived. The writer verbs are where that derivation happens: `open` puts a delegated thread on the record with every mint-time field copied from the brief's own header, refusing a deadline the wrapper's cap plus its kill grace would not fit inside, and recording whether the tree it started from was clean against the thread's base — HEAD by default, or the tree `--checkpoint <oid>` names, so the second task of a story is measured over the first one's uncommitted work instead of opening dirty (a dirty one makes the result honestly unmeasurable rather than quietly counted), while `--task <brief>` also records which task brief the thread carries out and the files that brief lists, refusing, since the last commit, a task thread whose files overlap by path prefix those of an open task thread or of a folded thread of another brief (`files-overlap`), and a mix of the two kinds — an untasked open beside an open task thread or, for a `code` open of backend `codex`, after a task fold, and a task open beside an open untasked thread (`mixed-open`), refusing at open a Files path the snapshot scope can never hold (`task-files-scope`), and measuring a task thread over its files alone, so `return` and `fold` refuse a changed path that no open or folded task thread on the same base claims (`out-of-files`); `await` waits for that one dispatch to answer and writes nothing — only the finished receipt satisfies it, a run still holding the nonce means keep waiting, and a wait that runs out says so with its own exit code, names whether the deadline or your own timeout ended it, and authorizes nothing: a wait that ended without an answer is a question for you, never permission to dispatch again; `return` absorbs the receipt the wrapper minted — only a finished one, checked against the contract it actually ran, its deadline and its own report, and refused outright when the tree hides changes from git or moves while the return is being computed — and derives the bytes from git rather than from anyone's claim; `fold` is the acceptance, and it refuses if the tree moved since the return — precisely, it re-confirms **equality of the visible canonical payload**, which is a change detector rather than a cryptographic identity of the tree: under the default head base that payload's untracked section is unframed and carries no file mode, so a content or symlink target that imitates the marker opening the next entry can alias two trees, and making an untracked file executable moves nothing (both named as residuals in the mode doc, with the fix queued); under a checkpoint base it is one indexed diff that carries modes. A change set carrying a binary, a non-regular path, a submodule, or a symlink whose target is not valid UTF-8 is **refused** at `return` and `fold` — CONSERVATIVELY, rather than promise what the default head payload may not be able to follow — and the same refusals hold for a checkpoint thread. `degrade` closes a thread that never earned a fold, on the record and with its reason. `aggregate` prints one wave: the registered thresholds, every observation as context, and per step class the finished threads — a folded success with git-provable bytes contributes its ratio, one whose bytes are unprovable is excluded from the mean but still counts in the first-pass rate, and a failed thread, a degrade-closed one, or one folded after failing acceptance each count as a real zero. Below the registered minimum nothing is computed (insufficient); at or above it is computed and labeled PILOT evidence. It REFUSES rather than guessing: no pre-registration, an unfinished thread in scope, a recorded refusal-to-delegate that never opened a thread, or an ambiguous wave each stop the computation by name. `handoff-return --slug <s>` closes the worktree loop after `land --prepare`: it re-attests that main still holds exactly the prepared tree under the same HEAD (both recorded in the handoff at prepare time), prints the satellite handoff's user-owned content byte for byte with its boundaries, byte lengths and the main-owned destinations each part folds into, prints the handoff digest and both OIDs as its proof, states the after-the-fold order (a fold landed after the gates leaves them stale), and records ONE self-reported worktree-stream observation only when the whole prepared change set is measurable — a deletion, a rename, a symlink, a submodule or a mode-only change ends with a named NOT RECORDED instead, never a partial number. Appends only to its own ledger inside the git dir (never committable); it also writes `handoff-return`'s `write-tree` tree object and, for a checkpoint measurement, the leaf's OWN temporary index file and the blobs its forced adds store — never a ref, never the real index; never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit worktrees` | any time | **parallel feature worktrees** — run several features in DIFFERENT agent sessions on one repo, zero interference on working-tree files (the ONE exception is the dependency cache, below): `provision <slug> --plan <file>` creates a sibling git worktree on branch `aw/<slug>` and populates it (registry-derived footprint copy-if-missing — a tracked file is never overwritten; EXACTLY ONE seeded feature plan; the `handoff-<slug>.md` record from minute zero; `node_modules` symlinked where the link stays ignored — a shared MUTABLE dependency cache: writes through it hit MAIN's node_modules; for isolation run the printed isolated-install command (`--install` only PRINTS it; on `--resume` run the printed unlink-first recovery first — printed only for a link whose RAW TARGET is MAIN's `node_modules`, since a foreign or unreadable link is reported as such with no removal advised); absolute root-pinned gate commands rebased on untracked copies only, and only while their bytes equal the MAIN source or its rebased form — user-modified copies stay untouched); `list` is read-only (slug, branch, base, dirty, handoff); `prompt <slug>` is read-only too and re-prints the satellite's cold-start prompt — the same text `provision` ends its report with: where the worktree is, its ONE seeded plan, the handoff as the one channel back, MAIN's orientation (shared series index, landing) and, under its own heading because it is probed on the satellite, that checkout's install posture — every value derived LIVE rather than replayed from the frozen provision record, a recorded value that no longer matches NAMED as a divergence (with the cause its source makes likely) instead of printed as the runnable one, every offered command marked with WHO runs it (`MAIN $ …` for the landing, `HERE $ …` for this checkout's own install, a posture with nothing to run staying prose), and a control character in any rendered value a typed STOP rather than a forged prompt line; `land <slug> --prepare` locks the common git dir, fail-closes on divergence or incomplete satellite state, transfers the complete accepted satellite diff onto a CLEAN main, runs sync plus the declared gates, and reports HEAD/TRANSFER/PREPARED OIDs — the commit ALWAYS stays a dialogue ask; `cleanup <slug>` takes the same lock and removes a LANDED worktree only after live landed-verification against main HEAD, while `--abandon` is the ONE destructive arm (destroys unlanded work; **no preview step** on any writer). The parent dir is the `docs/ai/worktrees.json` `parentDir` setting (default: the repo's sibling parent); an unwritable parent degrades to printed maintainer-pasted commands, and the one-time host consent that makes it promptless surfaces via `recommendations`. Never commits, never pushes, never runs a subscription CLI. |
 | `/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. |

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". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
 disable-model-invocation: true
 metadata:
-  version: '14.11.0'
+  version: '14.12.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.11.0",
+  "version": "14.12.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/modes/control-bytes.md

@@ -65,12 +65,15 @@ that directory's work-tree root):
    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
+3. **Declare it as a gate — never without consent (AD-021/D9).** `node
+   ${CLAUDE_SKILL_DIR}/tools/checker-gates.mjs --cwd <project> --only control-bytes --apply` writes
+   this one entry while the kit offers it; without `--only control-bytes --apply` the same command
+   previews and writes nothing. The upgrade's `tier` ask writes it on your explicit yes. The candidate
+   line to paste into your own `docs/ai/gates.json` instead: `{ "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. 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

package/references/modes/doc-parity.md

@@ -6,7 +6,7 @@ The DOC-PARITY lint (BUGFREE-3 / AD-049, session-economics item (b)) — the det
 
 **Run** — `node ${CLAUDE_SKILL_DIR}/tools/doc-parity.mjs [--check | --json]`:
 - default → the per-binding report (each `constant → file` marked ✓/✗).
-- **`--check`** → the gate exit code (0 consistent, 1 drift). Declare it as a project gate by hand in `docs/ai/gates.json`.
+- **`--check`** → the gate exit code (0 consistent, 1 drift): the lint checks the kit's own package, the gate a kit maintainer runs.
 - `--json` → the structured result.
 
 **What it checks (the closed registry).** The tokens are IMPORTED live from the tools — never re-typed in the lint — so the registry itself can never go stale:

package/references/modes/gates.md

@@ -23,7 +23,9 @@ Declared gates can also be **auto-approved** (no permission prompt on a byte-exa
 
 **Candidate line — the source-size gate (opt-in, never auto-seeded).** A project declaring the source-size practice (`docs/ai/source-size.json`) can declare its checker as one more gate, offered **only over a MINTED practice** — an absent config has nothing to offer, an authored-but-unminted one is withheld by name rather than declaring a gate that would refuse. Adoption is ONE consented verb, `node ${CLAUDE_SKILL_DIR}/tools/source-size-check.mjs --adopt --reason "<text>" [--cwd <project>]`: it mints the record and declares this gate and NOTHING else, is idempotent once adopted, and with no config refuses with the exact file to author (the practice's one manual step). The advisor surfaces it as the `source-size` item, reading a declared cmd as one of THREE claims rather than a yes/no — **canonical** (this copy — answered), **tool-elsewhere** (the same shape resolving to a DIFFERENT real copy — a vendored deployment, converging on a `source-size-copy` acknowledgement, never on `--adopt`, which would collide on the declared id), **not-the-tool** (a gate merely CARRYING the id is a squatter: rename it, or repoint its cmd at this `--check` form) — in that precedence. An unminted record stays the same attention outcome for either copy, and no acknowledgement silences it.
 
-**Consent-gated filling — the init preview, not part of the runner (D9).** The template `gates.json` is seeded EMPTY; FILLING it is a consented preview at init (`node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>`, dry-run by default — prints the derived entries and **writes NOTHING**; `--apply [--only <id>]…` writes exactly the consented entries on your explicit yes; add-only, id collisions refused). **Placement, not blind appending:** a consented entry lands at the END, except that a non-checker entry goes **BEFORE** a trailing canonical coverage checker — that checker must stay last, so appending after it would write a declaration the validator refuses, leaving a hand edit as the only lane on any final-capable declaration. Existing entries are never modified, removed or reordered. The offer derivation is **closed-world** (AD-052): only a terminating-class script NAME (test / lint / type-check / build — never dev/watch/serve, never a write-mode or release/publish/deploy variant) whose BODY is a member of the literal runner allowlist is offered — membership, never blocklist screening: the worst case is a legit command not offered, never a dangerous one offered. The offered cmd is the uniform hook-free **`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`** — `exec` runs a command, not a named script, so no pre/post hook can fire (npm/pnpm/yarn alike; never `<pm> run <name>`, which re-exposes hooks), and the Corepack env prefix blocks a hostile `packageManager` pin from fetching the PM binary before exec. npm is pinned `--offline --script-shell /bin/sh`; pnpm/yarn refuse an absent runner without network (a user-installed cache/global/PATH runner executing is user machine state — part of the disclosed residual); a family without a verified fail-closed exec contract is WITHHELD loudly. A screened-out body is always named — and when nothing but kit checkers remains, the preview says so in plain words: the offer carries **no project-verification gate at all**. **Disclose before the yes** (the preview prints it): gates.json is a PRIVILEGED file — the wired hook auto-approves byte-exact declared commands — and a script gate runs project-controlled tooling the preview does not sandbox (safe-by-construction = the OFFER DERIVATION). At upgrade the only gates.json writer is the consented legacy migration (`${CLAUDE_SKILL_DIR}/references/modes/upgrade.md`).
+**Candidate lines — the kit's own checkers (opt-in, one consented verb).** `control-bytes`, `plan-shape`, `spec-check` and `spec-coverage` can each be declared as a gate of your project: `node ${CLAUDE_SKILL_DIR}/tools/checker-gates.mjs --cwd <project>` previews them and writes nothing. Each is offered only over a state where its checker runs by design: `control-bytes` over a `.git` directory or gitfile at the project root, `plan-shape` on any deployment, `spec-check` over a regular `docs/ai/specs/index.md`, `spec-coverage` over a regular `docs/ai/spec-coverage.json` beside that store root. An offered checker prints its paste-ready entry line; the upgrade's `tier` ask writes the offered entries on your explicit yes — add-only, placed by the rule below, not stamp-gated, after the preview printed the disclosure below. An entry it wrote is removed by hand from `docs/ai/gates.json`: the verb never un-declares. `epic-shape` and `queue-audit` take a project operand and `doc-parity` checks only the kit's own package, so none of them is offered.
+
+**Consent-gated filling — the init preview, not part of the runner (D9).** The template `gates.json` is seeded EMPTY; FILLING it is a consented preview at init (`node ${CLAUDE_SKILL_DIR}/tools/gates-init.mjs --cwd <project>`, dry-run by default — prints the derived entries and **writes NOTHING**; `--apply [--only <id>]…` writes exactly the consented entries on your explicit yes; add-only, id collisions refused). **Placement, not blind appending:** a consented entry lands at the END, except that a non-checker entry goes **BEFORE** a trailing canonical coverage checker — that checker must stay last, so appending after it would write a declaration the validator refuses, leaving a hand edit as the only lane on any final-capable declaration. Existing entries are never modified, removed or reordered. The offer derivation is **closed-world** (AD-052): only a terminating-class script NAME (test / lint / type-check / build — never dev/watch/serve, never a write-mode or release/publish/deploy variant) whose BODY is a member of the literal runner allowlist is offered — membership, never blocklist screening: the worst case is a legit command not offered, never a dangerous one offered. The offered cmd is the uniform hook-free **`COREPACK_ENABLE_NETWORK=0 <pm> exec -- <allowlisted-body>`** — `exec` runs a command, not a named script, so no pre/post hook can fire (npm/pnpm/yarn alike; never `<pm> run <name>`, which re-exposes hooks), and the Corepack env prefix blocks a hostile `packageManager` pin from fetching the PM binary before exec. npm is pinned `--offline --script-shell /bin/sh`; pnpm/yarn refuse an absent runner without network (a user-installed cache/global/PATH runner executing is user machine state — part of the disclosed residual); a family without a verified fail-closed exec contract is WITHHELD loudly. A screened-out body is always named — and when nothing but kit checkers remains, the preview says so in plain words: the offer carries **no project-verification gate at all**. **Disclose before the yes** (the preview prints it): gates.json is a PRIVILEGED file — the wired hook auto-approves byte-exact declared commands — and a script gate runs project-controlled tooling the preview does not sandbox (safe-by-construction = the OFFER DERIVATION). At upgrade, step 3's run-list changes an existing gates.json only through the consented legacy migration and, under the `tier` ask, `tools/checker-gates.mjs` (`${CLAUDE_SKILL_DIR}/references/modes/upgrade.md`).
 
 **The coverage PRODUCER and the canonical checker are declared together or not at all.** `coverage-check` READS an lcov; something must WRITE it, and a checker with no producer PASSES (`skipped-no-lcov`) certifying nothing. A **producer** is a CLOSED set of full command forms, never a substring probe: the suite body `node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination="${AW_GIT_DIR:?exported by run-gates}/agent-workflow-lcov.info" --test-reporter=spec --test-reporter-destination=stdout` (optionally + the project's own test paths), bare or behind ONE verified per-PM `exec` wrapper. A cmd that merely MENTIONS the destination (in an `echo`, as a bare substring) or carries a PARTIAL flag set is **not** one. The tail must be path-shaped — path/glob/quoting bytes only, nothing that could sequence, redirect or substitute a command, no plain leading `-`. **Residual:** the screen judges SOURCE bytes — brace *sequence* expansion can produce others (`{Y..a}`), though bash never re-scans an expansion result as syntax, so such a byte is literal argument data, not an operator; the leading-`-` rule is first-order only (`'--flag'`, `{path,--flag}` pass); neither proves the lcov SURVIVES — "producer" means *configured with the reporters*, and a run producing none is caught at runtime as `skipped-no-lcov`. The destination rides `AW_GIT_DIR`, exported to every gate child on plain and `--final` runs alike (`AW_LCOV_FILE` is `--final`-only), so one cmd survives the unmet-producer preflight in both modes; the `:?` is the required-parameter form, so a hand-run with `AW_GIT_DIR` unset or empty fails naming it instead of writing the lcov to the filesystem ROOT (a STALE exported value is not caught), and the preflight counts it as a reference (a `${VAR:-…}` fallback stays unmatched). Recognition is APPEND-ONLY — every destination form the kit has emitted stays a producer, so an earlier kit's declaration never re-reads as customized; emission uses the newest alone. Recognition never WIDENS: a suite the closed set cannot express declares itself with **`"lcovProducer": true`** — the ONE other way to be a producer. Only the literal `true` claims (a string is a loud refusal); the claim binds the DECLARATION, never the run (a marked gate producing no lcov still ends `skipped-no-lcov` / `attested=no`); and it is FORWARD-ONLY — an older kit rejects a marker-carrying declaration by name (exit 5) instead of reading a claim it cannot honor. On BOTH declaration paths: the fill preview WIRES those reporters onto a `node --test` body — the one allowlist member producing lcov unaided, every other body is emitted unchanged — WITHHOLDS the `coverage-check` candidate, with a named note, when neither the offer nor the declaration carries a producer; and `--apply` REFUSES a checker with no producer, a checker that is not LAST (an ORDERING refusal about entries that are ALREADY declared — reorder by hand; the fill places new entries before a trailing checker but never reorders what it did not write), or a SECOND canonical checker. The legacy migration likewise never ADDS the checker into a producer-less declaration, and reports an already-declared one as INERT. A producer declared AFTER the checker leaves it just as inert (it reads nothing, or stale bytes) — ORDER is the rule. An already-declared inert pair, and a matrix of nothing but kit checkers, are surfaced by the advisor's `gates-inert` item (`${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`); its cause-A remedy is the fill preview when the checker is LAST and the project's own scripts yield an offerable producer (the placement rule lands it before the checker), and HAND-APPLY otherwise.
 

package/references/modes/upgrade.md

@@ -48,7 +48,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
    **What the spec-layer ensure does.** A deployment older than the feature-spec layer lacks `scripts/spec-schema.mjs` and `docs/ai/specs/index.md`, and its deployed `check-docs-size.mjs` predates the store collapse. In ONE order: the reader pair, then the checker pair — each seeded when absent and REFRESHED only while a file's bytes are a body a release shipped (an append-only digest catalog → `refreshed`; an edited body is preserved verbatim and withholds the writes that depend on it, the checker lane waiting on a byte-current reader pair); the store root is seeded from the bundled template, date rendered, ONLY behind a checker pair current after the run — an older or edited checker renders the store row by row and reds the hook's `--check-index`, so behind a custom checker the store root is NOT seeded and the line names the remedy (copy the pair from `${CLAUDE_SKILL_DIR}/references/scripts/` by hand, re-run). One token by precedence: `seeded` > `refreshed` > `customized-preserved` (an edited pair, and this run wrote nothing) > `already-present`; `skipped-no-node-evidence` only when neither a root `package.json` nor any kit-seeded `scripts/*.mjs` is present (the same Node-evidence probe the enforcement-script ensure uses; an unreadable probe is `failed` / `node-evidence-unverifiable`); every line states what this run did, and a write that stops partway names what landed. The legacy-ADR instruct never withholds it. **The adoption state this seed leaves behind is reported, never assumed:** the Recommendations section (step 4 / 8) carries the `spec-adoption` item — `not adopted` (the store is absent: the seed offered, the decline a named hand-apply alternative), `adopting` (a store with no live contract: the decline offered), silenced by a recorded decline (`ack-write --lane spec-adoption`), and a store the probe cannot read is a stated skip — and `status` prints the same state on its own line.
 
-   **`gates-migration` — legacy gates.json migration (consented preview — D8).** An EXISTING declaration may still carry the retired review-ledger / fold-completeness checks. Run the preview (dry-run — writes NOTHING), show the user the exact plan, and only on an explicit yes re-run it with `--apply`: canonical legacy entries (matched by their documented single-invocation cmd forms) are REMOVED, the canonical `unit-tests` cmd gains the built-in lcov reporters, and the coverage-check gate is ADDED last — atomic and COMPLETE, so the migrated declaration satisfies `run-gates --final`. **The checker rides a PRODUCER or is not declared at all** (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`): with no gate producing the lcov it reads, the migration does NOT add it, an already-declared one is reported INERT, the result is not called final-run-capable, and the preview prints the paste-ready suite cmd to declare by hand — nothing is ever removed for you. CUSTOMIZED entries are NEVER auto-touched: the preview names each with a paste-ready recovery, and the commit guard must NOT be installed until they are resolved. This is the ONLY gates.json writer at upgrade (the consented FILL preview runs at init).
+   **`gates-migration` — legacy gates.json migration (consented preview — D8).** An EXISTING declaration may still carry the retired review-ledger / fold-completeness checks. Run the preview (dry-run — writes NOTHING), show the user the exact plan, and only on an explicit yes re-run it with `--apply`: canonical legacy entries (matched by their documented single-invocation cmd forms) are REMOVED, the canonical `unit-tests` cmd gains the built-in lcov reporters, and the coverage-check gate is ADDED last — atomic and COMPLETE, so the migrated declaration satisfies `run-gates --final`. **The checker rides a PRODUCER or is not declared at all** (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`): with no gate producing the lcov it reads, the migration does NOT add it, an already-declared one is reported INERT, the result is not called final-run-capable, and the preview prints the paste-ready suite cmd to declare by hand — nothing is ever removed for you. CUSTOMIZED entries are NEVER auto-touched: the preview names each with a paste-ready recovery, and the commit guard must NOT be installed until they are resolved. Of step 3's run-list, only this migration and `tools/checker-gates.mjs` under the `tier` ask change an existing gates.json (the FILL preview runs at init).
 
    **`bridges` — placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
    `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
@@ -95,7 +95,9 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    `offered`: yes re-runs it and every other offered `apply:` line with `--apply`; no re-runs it
    with `--decline`. `story-sessions-section` `offered`: run its preview line and relay its lines
    (Communication `planned` too) before the ask; `declined`: relay the lens story-sessions absent note
-   as the recorded decline, without its preview command, and put no ask for it. A Communication absent
+   as the recorded decline, without its preview command, and put no ask for it. `checker-gates-declared`
+   `offered`: run its preview line and relay its lines, the disclosure and each `entry:` line included,
+   before the ask. A Communication absent
    note beside a `present` or `declined` one keeps its own ask, after the insert's full preview
    (the insert is indivisible). In an upgrade this governs the composition handoff's lens ask. A
    `refused` item, or a non-zero exit of any command the ask runs, STOPs the upgrade before the

package/references/scripts/migrate-gates.mjs

@@ -157,7 +157,7 @@ export const isCoverageProducerGate = (gate) => {
 // A cmd makes exactly ONE of three claims about a given tool, and collapsing them into a boolean is
 // what makes a VENDORED copy of the tool read as "the tool is not declared at all" — a false
 // absence, with a remedy (adopt it) that then collides with the entry already there:
-//   • canonical      — this tool's `--check` invocation, resolving to THIS copy of it
+//   • canonical      — this tool's invocation with its tail (`--check` by default), resolving to THIS copy
 //   • tool-elsewhere — the same invocation shape, resolving to a DIFFERENT real copy
 //   • not-the-tool   — anything else: another command, a masked form, an inadmissible token, or a
 //                      path nothing can resolve
@@ -195,16 +195,18 @@ const bareTokenSafe = (text) => text.length > 0 && ![...text].some((ch) => {
 
 const RE_META = /[.*+?^${}()|[\]\\]/g;
 
-// checkerClaimTool(basename, canonicalPath) → the screen for ONE tool. The shape is the STRICT full
-// command — `node` + ONE (quoted or bare) path token + the exact basename + ` --check` + END — so a
-// masked form (`--check --help`, `--check || true`, a prefix command) is never any claim at all.
-// Separators are PLAIN SPACES, not \s: a newline between the tokens is not a command a runner would
-// execute as written. The basename is regex-escaped here, never by the caller — a caller-escaped
-// literal is one forgotten backslash away from a dot matching any byte.
-export const checkerClaimTool = (basename, canonicalPath) => {
+// checkerClaimTool(basename, canonicalPath, tail) → the screen for ONE tool. The shape is the STRICT
+// full command — `node` + ONE (quoted or bare) path token + the exact basename + the exact argument
+// tail (`--check` by default) + END — so a masked form (`--check --help`, `--check || true`, a prefix
+// command) or a reordered tail is never any claim at all. Separators are PLAIN SPACES, not \s: a
+// newline between the tokens is not a command a runner would execute as written. The basename and
+// every tail token are regex-escaped here, never by the caller — a caller-escaped literal is one
+// forgotten backslash away from a dot matching any byte.
+export const checkerClaimTool = (basename, canonicalPath, tail = '--check') => {
   const safe = basename.replace(RE_META, '\\$&');
+  const args = tail.split(' ').map((token) => token.replace(RE_META, '\\$&')).join(' +');
   return Object.freeze({
-    re: new RegExp(`^node +(?:"((?:[^"]*[/\\\\])?${safe})"|((?:[^\\s"]*[/\\\\])?${safe})) +--check$`),
+    re: new RegExp(`^node +(?:"((?:[^"]*[/\\\\])?${safe})"|((?:[^\\s"]*[/\\\\])?${safe})) +${args}$`),
     canonical: canonicalPath,
   });
 };

package/tools/checker-claim.mjs

@@ -1,4 +1,4 @@
-// checker-claim.mjs — what a declared gate cmd CLAIMS about one of the kit's own `--check` tools,
+// checker-claim.mjs — what a declared gate cmd CLAIMS about one of the kit's own checker tools,
 // as three named outcomes instead of a boolean. A LEAF: node built-ins only, so every surface that
 // must recognize a tool invocation (the source-size matcher, the advisor's probes, the standalone
 // migration's twin) decides through ONE screen.
@@ -17,7 +17,7 @@ import { isAbsolute, join } from 'node:path';
 // A cmd makes exactly ONE of three claims about a given tool, and collapsing them into a boolean is
 // what makes a VENDORED copy of the tool read as "the tool is not declared at all" — a false
 // absence, with a remedy (adopt it) that then collides with the entry already there:
-//   • canonical      — this tool's `--check` invocation, resolving to THIS copy of it
+//   • canonical      — this tool's invocation with its tail (`--check` by default), resolving to THIS copy
 //   • tool-elsewhere — the same invocation shape, resolving to a DIFFERENT real copy
 //   • not-the-tool   — anything else: another command, a masked form, an inadmissible token, or a
 //                      path nothing can resolve
@@ -55,16 +55,18 @@ const bareTokenSafe = (text) => text.length > 0 && ![...text].some((ch) => {
 
 const RE_META = /[.*+?^${}()|[\]\\]/g;
 
-// checkerClaimTool(basename, canonicalPath) → the screen for ONE tool. The shape is the STRICT full
-// command — `node` + ONE (quoted or bare) path token + the exact basename + ` --check` + END — so a
-// masked form (`--check --help`, `--check || true`, a prefix command) is never any claim at all.
-// Separators are PLAIN SPACES, not \s: a newline between the tokens is not a command a runner would
-// execute as written. The basename is regex-escaped here, never by the caller — a caller-escaped
-// literal is one forgotten backslash away from a dot matching any byte.
-export const checkerClaimTool = (basename, canonicalPath) => {
+// checkerClaimTool(basename, canonicalPath, tail) → the screen for ONE tool. The shape is the STRICT
+// full command — `node` + ONE (quoted or bare) path token + the exact basename + the exact argument
+// tail (`--check` by default) + END — so a masked form (`--check --help`, `--check || true`, a prefix
+// command) or a reordered tail is never any claim at all. Separators are PLAIN SPACES, not \s: a
+// newline between the tokens is not a command a runner would execute as written. The basename and
+// every tail token are regex-escaped here, never by the caller — a caller-escaped literal is one
+// forgotten backslash away from a dot matching any byte.
+export const checkerClaimTool = (basename, canonicalPath, tail = '--check') => {
   const safe = basename.replace(RE_META, '\\$&');
+  const args = tail.split(' ').map((token) => token.replace(RE_META, '\\$&')).join(' +');
   return Object.freeze({
-    re: new RegExp(`^node +(?:"((?:[^"]*[/\\\\])?${safe})"|((?:[^\\s"]*[/\\\\])?${safe})) +--check$`),
+    re: new RegExp(`^node +(?:"((?:[^"]*[/\\\\])?${safe})"|((?:[^\\s"]*[/\\\\])?${safe})) +${args}$`),
     canonical: canonicalPath,
   });
 };

package/tools/checker-gates-read.mjs

@@ -0,0 +1,156 @@
+// checker-gates-read.mjs — the READ-ONLY leaf of the kit-owned checker gates: the frozen candidate
+// table, the precondition probes, the declaration read and the one derivation the declare verb and
+// the profile-gap detector both call. Governing contract: docs/ai/specs/kit/tier/checker-gates/
+// (part checker-gates-read). No CLI (refuseDirectRun); nothing here writes.
+import { lstatSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { CHECKER_CLAIM, classifyCheckerClaim, dqUnsafePath } from './checker-claim.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { GATES_REL, KIT_CHECKER_CLAIMS, coverageDeclarationDefects, validateDeclaration } from './gates-declaration.mjs';
+import { escapeForLine, isLineUnsafe } from './source-size-core.mjs';
+
+const DEPLOYMENT_CHAIN = ['.', 'docs', 'docs/ai'];
+const NOT_APPLICABLE_CODES = new Set(['ENOENT', 'ENOTDIR']);
+const OK = 'ok';
+const ABSENT = 'absent';
+const FOREIGN = 'foreign';
+const SYMLINK_CLASS = 'symlink';
+const GIT_DIR = Object.freeze({ rel: '.git', kinds: ['directory', 'file'], what: 'a directory or a regular gitfile' });
+const STORE_ROOT = Object.freeze({ rel: 'docs/ai/specs/index.md', kinds: ['file'], what: 'a regular file' });
+const COVERAGE_SCOPE = Object.freeze({ rel: 'docs/ai/spec-coverage.json', kinds: ['file'], what: 'a regular file' });
+
+export const CANDIDATE_STATES = Object.freeze({
+  declared: 'declared',
+  idTaken: 'id-taken',
+  probeUnreadable: 'probe-unreadable',
+  notApplicable: 'not-applicable',
+  offered: 'offered',
+  withheld: 'withheld',
+});
+
+const lstatOf = (deps) => deps.lstatSync ?? lstatSync;
+
+export const isDeployed = (root, deps) => {
+  try {
+    return DEPLOYMENT_CHAIN.every((path, index) => {
+      const stat = lstatOf(deps)(resolve(root, path));
+      if (stat.isSymbolicLink()) return false;
+      return index < DEPLOYMENT_CHAIN.length - 1 || stat.isDirectory();
+    });
+  } catch {
+    return false;
+  }
+};
+
+const kindAt = (path, lstat) => {
+  try {
+    const stat = lstat(path);
+    if (stat.isSymbolicLink()) return { kind: SYMLINK_CLASS };
+    if (stat.isDirectory()) return { kind: 'directory' };
+    return { kind: stat.isFile() ? 'file' : 'other' };
+  } catch (error) {
+    if (NOT_APPLICABLE_CODES.has(error?.code)) return { kind: ABSENT };
+    return { unreadable: String(error?.code ?? error?.message ?? error) };
+  }
+};
+
+// A probe answers {} when its checker runs by design over the tree, else the state and its detail.
+const requiring = (...requirements) => (root, deps) => {
+  const judged = requirements.map((requirement) => ({ requirement, ...kindAt(resolve(root, requirement.rel), lstatOf(deps)) }));
+  const unreadable = judged.find((item) => item.unreadable !== undefined);
+  if (unreadable) {
+    return { state: CANDIDATE_STATES.probeUnreadable, detail: `${unreadable.requirement.rel}: ${unreadable.unreadable}` };
+  }
+  const missing = judged.find(({ requirement, kind }) => !requirement.kinds.includes(kind));
+  if (missing) return { state: CANDIDATE_STATES.notApplicable, detail: `${missing.requirement.rel} is not ${missing.requirement.what}` };
+  return {};
+};
+
+const candidate = (id, title, probe) => Object.freeze({ id, title, probe });
+
+export const CHECKER_GATE_CANDIDATES = Object.freeze([
+  candidate('control-bytes', 'No raw control byte in the work tree', requiring(GIT_DIR)),
+  candidate('plan-shape', 'Plans in flight keep the structural planning shape', requiring()),
+  candidate('spec-check', 'Feature-spec store structure — the whole store', requiring(STORE_ROOT)),
+  candidate(
+    'spec-coverage',
+    'No work without a specification — every in-scope tool is governed by a contract, or named in the shrink-only debt',
+    requiring(COVERAGE_SCOPE, STORE_ROOT),
+  ),
+]);
+
+const claimOf = (id) => KIT_CHECKER_CLAIMS.find((claim) => claim.id === id);
+
+const refusal = (name, detail) => (detail === undefined ? { refusal: name } : { refusal: name, detail: String(detail) });
+
+const attempt = (read) => {
+  try {
+    return { value: read() };
+  } catch (error) {
+    return { error };
+  }
+};
+
+const readDeclaration = (root, deps) => {
+  const read = readRegularFileNoFollow(resolve(root, GATES_REL), deps);
+  if (read.outcome === ABSENT) return refusal('declaration-absent');
+  if (read.outcome === FOREIGN) {
+    return read.className === SYMLINK_CLASS ? refusal('declaration-symlink') : refusal('declaration-not-regular', read.className);
+  }
+  if (read.outcome !== OK) return refusal('declaration-unreadable', read.code);
+  const parsed = attempt(() => JSON.parse(read.content));
+  if (parsed.error) return refusal('declaration-malformed', parsed.error.message);
+  const validated = attempt(() => validateDeclaration(parsed.value));
+  if (validated.error) return refusal('declaration-invalid', validated.error.message);
+  const gates = validated.value;
+  const defects = coverageDeclarationDefects(gates, root);
+  if (defects.length > 0) return refusal('declaration-coverage-defect', defects[0].message);
+  return { declaration: Object.hasOwn(parsed.value, '_README') ? { readme: parsed.value._README, gates } : { gates } };
+};
+
+const claimState = ({ id, screen }, gates, root) => {
+  const claimed = gates.some((gate) => {
+    const claim = classifyCheckerClaim(screen, gate.cmd, root);
+    return claim === CHECKER_CLAIM.CANONICAL || claim === CHECKER_CLAIM.ELSEWHERE;
+  });
+  if (claimed) return { state: CANDIDATE_STATES.declared };
+  const taken = gates.find((gate) => gate.id === id);
+  return taken ? { state: CANDIDATE_STATES.idTaken, detail: taken.cmd } : {};
+};
+
+const toolPathOf = ({ basename, screen }, deps) => join(deps.kitToolsDir ?? dirname(screen.canonical), basename);
+const isUnrenderable = (path) => dqUnsafePath(path) || isLineUnsafe(path);
+
+const judgeCandidate = ({ id, title, probe }, rendered, gates, root, deps) => {
+  const claimed = claimState(claimOf(id), gates, root);
+  if (claimed.state) return claimed;
+  const probed = probe(root, deps);
+  if (probed.state) return probed;
+  if (rendered.unrenderable) return { state: CANDIDATE_STATES.withheld };
+  return { state: CANDIDATE_STATES.offered, entry: JSON.stringify({ id, title, cmd: rendered.cmd }) };
+};
+
+const shapeOf = (id, { state, entry = null, detail }) => (detail === undefined ? { id, state, entry } : { id, state, entry, detail });
+
+export const judgeCheckerGates = (root, deps = {}) => {
+  if (!isDeployed(root, deps)) return refusal('no-deployment');
+  const loaded = readDeclaration(root, deps);
+  if (loaded.refusal) return loaded;
+  const rendered = CHECKER_GATE_CANDIDATES.map(({ id }) => {
+    const claim = claimOf(id);
+    const path = toolPathOf(claim, deps);
+    return isUnrenderable(path) ? { unrenderable: path } : { cmd: `node "${path}" ${claim.tail}` };
+  });
+  const judged = CHECKER_GATE_CANDIDATES.map((entry, index) => judgeCandidate(entry, rendered[index], loaded.declaration.gates, root, deps));
+  const firstWithheld = judged.findIndex(({ state }) => state === CANDIDATE_STATES.withheld);
+  const named = (item, index) => (index === firstWithheld
+    ? { ...item, detail: `the kit path cannot be rendered into a command: ${escapeForLine(rendered[index].unrenderable)}` }
+    : item);
+  return {
+    declaration: loaded.declaration,
+    candidates: CHECKER_GATE_CANDIDATES.map(({ id }, index) => shapeOf(id, named(judged[index], index))),
+  };
+};
+
+refuseDirectRun(import.meta.url);

package/tools/checker-gates.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// checker-gates.mjs — the declare verb of the kit-owned checker gates: previews the candidates the
+// read leaf judges and, on --apply, writes the offered ones add-only into docs/ai/gates.json.
+// Governing contract: docs/ai/specs/kit/tier/checker-gates/ (part checker-gates-verb).
+// main(argv, deps) returns, never exits, never asks.
+import { resolve } from 'node:path';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic } from './atomic-write.mjs';
+import { safeLine } from './carriers.mjs';
+import { CANDIDATE_STATES, judgeCheckerGates } from './checker-gates-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { GATES_REL, coverageDeclarationDefects, validateDeclaration } from './gates-declaration.mjs';
+import { TRUST_CHAIN_DISCLOSURE, placeEntries } from './gates-init.mjs';
+
+const LF = String.fromCharCode(10);
+const ARGV_OFFSET = 2;
+const EXIT_SUCCESS = 0;
+const EXIT_REFUSAL = 1;
+const EXIT_USAGE = 2;
+const CWD_FLAG = '--cwd';
+const APPLY_FLAG = '--apply';
+const ONLY_FLAG = '--only';
+const HELP_FLAGS = new Set(['--help', '-h']);
+const APPLIED = 'applied';
+const INDENT = '  ';
+const JSON_INDENT = 2;
+const NOUN = 'a gate declaration';
+
+export const OUTCOME_LINES = Object.freeze({
+  candidate: (id, word, detail) => `${id}: ${word}${detail ? ` — ${safeLine(detail)}` : ''}`,
+  entry: (json) => `${INDENT}entry: ${json}`,
+  disclosure: () => TRUST_CHAIN_DISCLOSURE,
+  refusal: (name, detail) => `checker-gates: refused — ${name}${detail ? `: ${safeLine(detail)}` : ''}`,
+  usage: (problem) => `usage: checker-gates.mjs --cwd DIR [--apply] [--only ID]... — ${safeLine(problem)}`,
+  onlyNotOffered: (ids, offered) => `${ONLY_FLAG} names ids not offered: ${ids.join(', ')} (offered: ${offered.join(', ') || 'none'})`,
+  help: () => [
+    'checker-gates.mjs --cwd DIR [--apply] [--only ID]...',
+    'Previews the kit-owned checker gates the project in DIR can declare; writes nothing by default.',
+    '--apply writes the offered entries into docs/ai/gates.json, add-only; --only ID narrows the write.',
+    'Exit codes: 0 done, 1 one named refusal, 2 usage.',
+  ].join(LF),
+});
+
+const result = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+const refuse = (name, detail) => result(EXIT_REFUSAL, '', OUTCOME_LINES.refusal(name, detail));
+const causeOf = (error) => String(error?.message ?? error);
+
+const parseArgs = (argv) => {
+  if (argv.length === 1 && HELP_FLAGS.has(argv[0])) return { help: true };
+  const options = { only: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    const value = argv[index + 1];
+    if (flag === CWD_FLAG) {
+      if (options.cwd !== undefined) return { problem: `${CWD_FLAG} given twice` };
+      if (value === undefined || value.startsWith('-')) return { problem: `${CWD_FLAG} needs a directory` };
+      options.cwd = value;
+      index += 1;
+    } else if (flag === APPLY_FLAG) {
+      if (options.apply) return { problem: `${APPLY_FLAG} given twice` };
+      options.apply = true;
+    } else if (flag === ONLY_FLAG) {
+      if (value === undefined || value.startsWith('-')) return { problem: `${ONLY_FLAG} needs a gate id` };
+      if (!options.only.includes(value)) options.only.push(value);
+      index += 1;
+    } else {
+      return { problem: `unknown argument ${flag}` };
+    }
+  }
+  if (options.cwd === undefined) return { problem: `${CWD_FLAG} is required` };
+  return { cwd: options.cwd, apply: Boolean(options.apply), only: options.only };
+};
+
+export const mergeCheckerGates = (loaded, selected, root) => {
+  const readme = Object.hasOwn(loaded, 'readme') ? { _README: loaded.readme } : {};
+  const merged = { ...readme, gates: placeEntries(loaded.gates, selected, root) };
+  validateDeclaration(merged);
+  const defects = coverageDeclarationDefects(merged.gates, root);
+  if (defects.length > 0) return { refusal: 'coverage-defect', detail: defects[0].message };
+  return { merged, body: `${JSON.stringify(merged, null, JSON_INDENT)}${LF}` };
+};
+
+const renderLines = (candidates) => {
+  const disclose = candidates.some(({ state }) => state === CANDIDATE_STATES.offered || state === APPLIED);
+  const lines = candidates.flatMap(({ id, state, entry, detail }) => (state === CANDIDATE_STATES.offered
+    ? [OUTCOME_LINES.candidate(id, state, detail), OUTCOME_LINES.entry(entry)]
+    : [OUTCOME_LINES.candidate(id, state, detail)]));
+  return disclose ? [OUTCOME_LINES.disclosure(), ...lines] : lines;
+};
+
+const writeSelected = (root, judged, selected, deps) => {
+  const merge = mergeCheckerGates(judged.declaration, selected.map(({ entry }) => JSON.parse(entry)), root);
+  if (merge.refusal) return { refusal: refuse(merge.refusal, merge.detail) };
+  try {
+    writeDocsAiFileAtomic(root, GATES_REL, merge.body, deps, { noun: NOUN, rel: GATES_REL });
+  } catch (error) {
+    return { refusal: refuse('write-failed', causeOf(error)) };
+  }
+  const written = new Set(selected.map(({ id }) => id));
+  return { candidates: judged.candidates.map((item) => (written.has(item.id) ? { ...item, state: APPLIED, entry: null } : item)) };
+};
+
+const runVerb = (options, deps) => {
+  const root = resolve(options.cwd);
+  try {
+    assertDocsAiDeployment(root, deps, { noun: NOUN, rel: GATES_REL });
+  } catch (error) {
+    return refuse('no-deployment', causeOf(error));
+  }
+  const judged = judgeCheckerGates(root, deps);
+  if (judged.refusal) return refuse(judged.refusal, judged.detail);
+  const offered = judged.candidates.filter(({ state }) => state === CANDIDATE_STATES.offered);
+  const offeredIds = offered.map(({ id }) => id);
+  const unknown = options.only.filter((id) => !offeredIds.includes(id));
+  if (unknown.length > 0) return result(EXIT_USAGE, '', OUTCOME_LINES.usage(OUTCOME_LINES.onlyNotOffered(unknown, offeredIds)));
+  const selected = options.only.length > 0 ? offered.filter(({ id }) => options.only.includes(id)) : offered;
+  if (!options.apply || selected.length === 0) return result(EXIT_SUCCESS, renderLines(judged.candidates).join(LF));
+  const written = writeSelected(root, judged, selected, deps);
+  if (written.refusal) return written.refusal;
+  return result(EXIT_SUCCESS, renderLines(written.candidates).join(LF));
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = parseArgs(argv);
+  if (parsed.help) return result(EXIT_SUCCESS, OUTCOME_LINES.help());
+  if (parsed.problem) return result(EXIT_USAGE, '', OUTCOME_LINES.usage(parsed.problem));
+  return runVerb(parsed, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const outcome = main(process.argv.slice(ARGV_OFFSET));
+  if (outcome.stdout) console.log(outcome.stdout);
+  if (outcome.stderr) console.error(outcome.stderr);
+  process.exitCode = outcome.code;
+}

package/tools/direct-run.mjs

@@ -67,6 +67,8 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   'set-recipe-roster.mjs': '/agent-workflow-kit set-recipe',
   // The read half of the tier offer: the upgrade's step-3 `tier` item runs the offer that uses it.
   'reference-profile.mjs': '/agent-workflow-kit upgrade',
+  // The read half of the checker-gates verb: the same step-3 `tier` item runs the verb that uses it.
+  'checker-gates-read.mjs': '/agent-workflow-kit upgrade',
 });
 
 // The frozen refusal line. One line, names the module, names the command.

package/tools/doc-parity.mjs

@@ -330,8 +330,8 @@ read only from the surface anchored between the doc's advisor-matrix begin/end m
 elsewhere in the doc can neither stand in for it nor mask its drift, and a drifted header inside the
 anchor fails closed rather than falling through to another table.
 
---check exits 0/1 as a gate (declare it in docs/ai/gates.json by hand). --json prints the structured
-result. Default prints the per-binding report.
+--check exits 0/1 as a gate over the kit's own package, the gate a kit maintainer runs. --json prints
+the structured result. Default prints the per-binding report.
 
 Read-only: never writes, never commits, spawns nothing. Exit codes: 0 pass (or plain report); 1 drift
 (under --check) or error; 2 usage.`;

package/tools/gates-declaration.mjs

@@ -9,6 +9,7 @@
 import { readFileSync, lstatSync, realpathSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CHECKER_CLAIM, checkerClaimTool, classifyCheckerClaim } from './checker-claim.mjs';
 import { fail, loadConfig, CONFIG_REL } from './orchestration-config.mjs';
 import { isCoverageProducerGate } from './coverage-producer.mjs';
 import { matchesSourceSizeGate } from './source-size-core.mjs';
@@ -224,8 +225,21 @@ export const isReviewDependentGate = (gate, projectDir) =>
 // "does this declaration verify the PROJECT?" through the review-dependent predicate alone read a
 // matrix of nothing but that gate as project verification. Three surfaces asked it, each knowing a
 // different half; this is the one home, so a future kit checker is added once.
+// KIT_CHECKER_CLAIMS is the one statement of the four declarable kit checkers' basenames, tails and
+// canonical paths (docs/ai/specs/kit/tier/checker-gates/, part checker-claim-tail).
+const kitCheckerClaim = (id, basename, tail) => Object.freeze({
+  id, basename, tail, screen: checkerClaimTool(basename, fileURLToPath(new URL(`./${basename}`, import.meta.url)), tail),
+});
+export const KIT_CHECKER_CLAIMS = Object.freeze([
+  kitCheckerClaim('control-bytes', 'control-bytes.mjs', '--check'),
+  kitCheckerClaim('plan-shape', 'plan-shape-cli.mjs', '--check --in-flight'),
+  kitCheckerClaim('spec-check', 'spec-check-cli.mjs', '--all'),
+  kitCheckerClaim('spec-coverage', 'spec-coverage-cli.mjs', '--check'),
+]);
+
 export const isKitOwnedCheckerGate = (gate, projectDir) =>
-  isReviewDependentGate(gate, projectDir) || matchesSourceSizeGate(gate.cmd, projectDir);
+  isReviewDependentGate(gate, projectDir) || matchesSourceSizeGate(gate.cmd, projectDir)
+  || KIT_CHECKER_CLAIMS.some(({ screen }) => classifyCheckerClaim(screen, gate.cmd, projectDir) === CHECKER_CLAIM.CANONICAL);
 
 // ── the pregate subset derivation (#66 / Decision 7 — ONE home for producer and factory) ─────
 

package/tools/gates-init.mjs

@@ -4,9 +4,9 @@
 // explicitly-consenting prose (the init/bootstrap flows and the gates.md consent-fill section) —
 // it is NOT a routable mode token, it sits OUTSIDE every velocity allowlist tier (a
 // consent-per-run writer is never pre-approved), and the shipped gates.json TEMPLATE stays EMPTY
-// (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through this
-// preview, never auto-seeding. ONE lifecycle contract: this preview runs at INIT; at UPGRADE the
-// only gates.json writer is the consented legacy migration.
+// (AD-021/AD-038): a populated declaration is per-entry maintainer consent recorded through a
+// consented writer (this preview among them), never auto-seeding. This preview runs at INIT; at UPGRADE step 3's
+// run-list changes entries only through the consented legacy migration and, under `tier`, checker-gates.mjs.
 //
 // What it offers (the derivation invariants, test-pinned) — CLOSED-WORLD since AD-052: an entry
 // is offered only when every axis is proven safe by MEMBERSHIP in a finite, test-guarded set,

package/tools/profile-gaps.mjs

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { CANDIDATE_STATES, isDeployed, judgeCheckerGates } from './checker-gates-read.mjs';
 import { CONFIG_REL, validateConfig } from './orchestration-config.mjs';
 import { TIER_TARGETS } from './reference-profile.mjs';
 import {
@@ -16,8 +17,10 @@ const GAP_ID = 'story-sessions-section';
 const SLOTS_ID = 'epic-task-slots';
 const STORE_ID = 'epic-store-seeded';
 const STORE_PATH = 'docs/ai/epics';
-const DEPLOYMENT_CHAIN = ['.', 'docs', 'docs/ai'];
+const CHECKER_GATES_ID = 'checker-gates-declared';
 const TIER_PREVIEW_PATH = fileURLToPath(new URL('./tier-preview.mjs', import.meta.url));
+const CHECKER_GATES_PATH = fileURLToPath(new URL('./checker-gates.mjs', import.meta.url));
+const UNDECIDED_STATES = [CANDIDATE_STATES.idTaken, CANDIDATE_STATES.probeUnreadable, CANDIDATE_STATES.withheld];
 const STORY_ID = 'story-sessions';
 const TEMPLATE_CANON = 'template';
 const ENCODING = 'utf8';
@@ -97,18 +100,6 @@ const detectStorySessions = ({ root, deps }) => {
   return { verdict: VERDICTS.absent };
 };
 
-const isDeployed = (root, deps) => {
-  try {
-    return DEPLOYMENT_CHAIN.every((path, index) => {
-      const stat = deps.lstatSync(resolve(root, path));
-      if (stat.isSymbolicLink()) return false;
-      return index < DEPLOYMENT_CHAIN.length - 1 || stat.isDirectory();
-    });
-  } catch {
-    return false;
-  }
-};
-
 const parseConfig = (bytes) => {
   let parsed;
   try {
@@ -163,10 +154,19 @@ const detectStore = ({ root, deps }) => {
   return { verdict: VERDICTS.present };
 };
 
+const detectCheckerGates = ({ root, deps }) => {
+  const judged = judgeCheckerGates(root, deps);
+  if (judged.refusal) return reportUndecidable(judged.refusal);
+  if (judged.candidates.some(({ state }) => state === CANDIDATE_STATES.offered)) return { verdict: VERDICTS.absent };
+  const undecided = judged.candidates.find(({ state }) => UNDECIDED_STATES.includes(state));
+  return undecided ? reportUndecidable(undecided.state) : { verdict: VERDICTS.present };
+};
+
 const tierPreview = (root) => buildInsertPreview(root, TIER_PREVIEW_PATH);
 
 export const PROFILE_GAPS = Object.freeze([
   Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: (root) => buildInsertPreview(root) }),
   Object.freeze({ id: SLOTS_ID, detect: detectSlots, apply: tierPreview }),
   Object.freeze({ id: STORE_ID, detect: detectStore, apply: tierPreview }),
+  Object.freeze({ id: CHECKER_GATES_ID, detect: detectCheckerGates, apply: (root) => buildInsertPreview(root, CHECKER_GATES_PATH) }),
 ]);