@sabaiway/agent-workflow-kit 1.33.0 → 1.34.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.34.0 — Onboarding UX: one batched setup prompt, honest installer messaging, the visible accelerator funnel, and the consent-gated gates seeder (AD-042)
+
+A **feature** release (first-contact flow + a new consent-gated writer; deployment-lineage head
+stays `1.3.0` — no migration). First contact now interrupts once instead of three times, the
+opt-in accelerators are discoverable from every happy path, and a project's own verification
+commands can be seeded into `docs/ai/gates.json` behind an explicit per-entry yes:
+
+- **F11 — ONE batched setup prompt.** Bootstrap asks the three setup questions (visibility /
+  conversational language / attribution) as one structured multi-question prompt where supported
+  (`AskUserQuestion`, up to 4 questions per call), records each answer individually, and writes
+  nothing until all are answered (`references/modes/bootstrap.md` preamble + steps 2–4;
+  `references/contracts.md` · `references/shared/deploy-tail.md` · `launchers/windsurf-workflow.md`
+  reworded to match). Upgrade batches its two migration asks the same way ONLY when BOTH
+  `AGENTS.md` blocks are missing (a pre-1.1.0 deployment), collects them in step 6 BEFORE the
+  migrations apply, and never re-asks a collected answer (`references/modes/upgrade.md`); the four
+  migration files are untouched — their own ask stays the standalone fallback. New
+  `test/ask-contract.test.mjs` pins the wording across all 7 files and holds the kit↔memory
+  `references/contracts.md` ask paragraph byte-identical (a hand-lockstep pair, deliberately not a
+  sync-mirrors family).
+- **F12 — the installer says what a returning user needs.** `bin/install.mjs` prints a restart
+  hint on every run over a PRE-existing install ("restart the session so the agent reloads the
+  refreshed kit files") — on the verb path, at most once per run, surviving even the fatal
+  engine-install abort — and replaces the false "Claude Code / Codex / Devin Desktop all use the
+  same /agent-workflow-kit" claim with the real per-agent matrix (Codex invokes via its `/skills`
+  menu and may auto-trigger) in `--help` AND the final next-steps block. Pinned in
+  `bin/install.test.mjs`.
+- **F10a — the opt-in funnel is visible.** The welcome-mat ladder
+  (`references/shared/report-footer.md`) gains caveat-aware rungs: velocity when the allowlist is
+  unseeded, `agents` when no cheap-lane vehicle is placed, `hook` when gates are DECLARED
+  (non-empty — file presence alone would misfire on the empty seed) but the hook is unwired; the
+  two new signals ride the existing status envelope (`tools/family-registry.mjs`
+  `surveyCheapAgents` + `surveyGateHook.declaredGates` → `tools/view-model.mjs` →
+  `tools/renderers.mjs` — no new helper call). Bootstrap step 11 ends on a compact
+  optional-accelerators block (velocity · agents · gates seeding + hook · set-recipe;
+  preview-first, nothing runs without a yes), and `help` output gains a matching "Tune" tail
+  (`tools/commands.mjs` — no new mode, no new kind; the router SKILL.md is untouched). New
+  `test/report-footer-rotation.test.mjs` pins one shorthand ladder literal across
+  upgrade + bootstrap; the `gate-approve-hook` fixture is refreshed to the live 10-gate shape.
+- **F10b — the consent-gated `gates.json` seeder (the seeding↔hook trust chain).** New
+  `tools/seed-gates.mjs`: dry-run by default (prints the derived `{ id, title, cmd }` entries,
+  writes NOTHING; declining leaves the file byte-identical); `--apply [--only <id>]…` appends
+  exactly the consented entries — append-only (never modifies or removes an existing entry),
+  id-collision refusal, validator-checked (it imports the runner's `validateDeclaration`; the
+  runner never imports it), stamp-gated apply, and OUTSIDE every velocity tier (a consent-per-run
+  writer is never pre-approved). Offered candidates are terminating verification classes only
+  (test / lint / type-check / build) — release/publish/deploy scripts, watch/serve modes, and
+  MUTATING variants (`lint:fix`, `test:update`, bodies carrying `--fix`/`--write`/`-w`/`-u`)
+  never enter the offer; commands are package-manager-aware (npm/pnpm/yarn). The review-state
+  candidate is included ONLY when `docs/ai/orchestration.json` declares reviewed/council on
+  `plan-execution.review` (the slot the checker enforces), with the resolved QUOTED path. Every
+  preview prints the trust-chain disclosure: the hook auto-approves byte-exact declared commands —
+  seeding and hook wiring are two separate consents. The hardened atomic write core is extracted
+  into `tools/atomic-write.mjs` (exclusive-create tmp+rename, TOCTOU re-check, symlink STOPs) and
+  shared with `tools/orchestration-write.mjs` (public API unchanged). The consent-seed protocol
+  lives in `references/modes/gates.md`; `references/modes/review-state.md` step 3 now names the
+  seeder path ("by hand OR the explicit-consent seeder — never without consent").
+- **AD-039 amendment (documented, AD-042):** `test/router-contract.test.mjs` `routerPlusMode`
+  28672 → 29696 — the F11 upgrade batching caveat is +422 B of new contract text against 154 B of
+  headroom; the router itself is byte-identical. Tarball 116 → 118 files
+  (`test/package-content.test.mjs` count + payload pins for the seeder pair).
+
 ## 1.33.0 — The agent-rules lens region: render + reconcile from the engine canon (AD-041)
 
 A **feature** release (new shipped tool + wiring; deployment-lineage head stays `1.3.0` — the

package/README.md

@@ -234,7 +234,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents four named recipes for composing the bridges into plan → execute → review — **Solo / Reviewed / Council / Delegated** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready), and offers the choice. The orchestrator runs it via the bridge skills and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/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 review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand** (never auto-seeded). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
+| `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
 | `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. Prints to stdout; `--out` writes **one scratch file only** (gitignored / outside the repo — a tracked or not-ignored in-repo path is refused). Never commits, 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. |
 | `/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. |

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

package/bin/install.mjs

@@ -303,7 +303,8 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
 After install, invoke the skill in your agent, inside a project:
   first time in the project  ->  /agent-workflow-kit
   project already has it     ->  /agent-workflow-kit upgrade
-  (Claude Code / Codex / Devin Desktop all use the same /agent-workflow-kit.)
+  Per agent: Claude Code -> /agent-workflow-kit; Devin Local -> /agent-workflow-kit;
+  Codex -> its /skills menu -> agent-workflow-kit (Codex may also auto-trigger it).
 
 Re-running this npx command updates the kit's own files; /agent-workflow-kit
 upgrade then migrates a project's deployment to that version.`);
@@ -388,6 +389,23 @@ const main = async () => {
     : 'installed';
   console.log(`[agent-workflow-kit] ${verb} v${version} -> ${tildify(target)}`);
 
+  // F12 restart hint — any run over a PRE-EXISTING install (every cmp outcome, incl. the legacy
+  // unstamped one) leaves an already-open agent session still holding the PREVIOUS kit files in
+  // memory (mirrors the SKILL.md "restart the session" note the memory-miss paths already carry).
+  // Printed AT MOST ONCE per run: here on the verb path — so it survives the fatal engine abort
+  // below — with the final next-steps block as the carrier only if this line did not print.
+  const restartHintState = { pending: wasPresent };
+  const printRestartHint = () => {
+    if (!restartHintState.pending) return;
+    restartHintState.pending = false;
+    console.log(
+      `[agent-workflow-kit] the kit was already installed here — an agent session that was ` +
+        `already open is still running the previous kit files; restart the session so the agent ` +
+        `reloads the refreshed kit files.`,
+    );
+  };
+  printRestartHint();
+
   // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
   // it restores locally modified/deleted files), and whether npx served a cached build is NOT
   // observable here (no network), so the note never claims it; the @latest hint is conditional.
@@ -506,10 +524,13 @@ const main = async () => {
   // This command (de)installed the *kit* globally. Deploying it into a project is a
   // separate, in-agent step — and which sub-command depends on whether that project
   // already has the kit. Spell both out so it's unambiguous (see README "Use").
+  printRestartHint(); // carrier fallback — a no-op when the verb path already printed it
   console.log(`
 Next — open your agent inside a project and run the skill:
   • first time in this project  ->  /agent-workflow-kit
   • project already has the kit  ->  /agent-workflow-kit upgrade
+  • per agent: Claude Code -> /agent-workflow-kit · Devin Local -> /agent-workflow-kit ·
+    Codex -> its /skills menu -> agent-workflow-kit (Codex may also auto-trigger it)
 
 This command only installs/updates the kit itself (in ${tildify(target)}).
 To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`);

package/capability.json

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

package/launchers/windsurf-workflow.md

@@ -22,7 +22,9 @@ reinvent any of it here; the kit's `SKILL.md` is the single source of truth.
    - No `docs/ai/` in this project → **bootstrap**.
    - `docs/ai/` already exists → ask the user whether to run **upgrade** instead.
 3. Execute every step from `SKILL.md` for THIS repository:
-   - Recon (read-only) → **ask the user: visible or hidden** (wait for the answer) →
+   - Recon (read-only) → **ask the three setup questions (visible-or-hidden / language /
+     attribution) as ONE structured multi-question prompt; record each answer individually,
+     write nothing until ALL are answered** →
      create `AGENTS.md` (+ `CLAUDE.md` symlink) from `<KIT_DIR>/references/templates/` →
      deploy `docs/ai/` → copy `<KIT_DIR>/references/scripts/*.mjs` (Node projects) →
      wire/hide per visibility → install the pre-commit hook → stamp `docs/ai/.workflow-version`.

package/package.json

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

@@ -5,8 +5,9 @@ language**, and **agent attribution** — each have a contract below. `SKILL.md`
 main procedure stays lean; load this file when you need the full rule for a contract (e.g. while
 filling the matching `AGENTS.md` block, or when an `upgrade` migration touches it).
 
-Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion`
-in Claude Code), otherwise in prose — and always wait for the answer before writing.
+Ask the three as **ONE structured multi-question prompt where your agent supports it**
+(`AskUserQuestion` in Claude Code, up to 4 questions per call), otherwise in prose; record each
+answer individually — and write nothing until ALL are answered.
 
 ---
 

package/references/modes/bootstrap.md

@@ -4,7 +4,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.
 
-> The three setup questions (steps 2–4) are decisions only the user can make and are hard to reverse after a commit. Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion` in Claude Code — one option per choice, recommended one first), otherwise in prose — and **wait for the answer before writing anything**.
+> The three setup questions (steps 2–4) are decisions only the user can make and are hard to reverse after a commit. Ask them as **ONE structured multi-question prompt where your agent supports it** (`AskUserQuestion` in Claude Code — up to 4 questions per call, one option per choice, recommended one first), otherwise in prose; **record each answer individually** — and **write nothing until ALL are answered**.
 
 1. **Recon (read-only).** Before writing anything:
    - `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → stack, package manager, scripts.
@@ -13,10 +13,10 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
-   - **First-contact orientation — say this before the first question (read-only).** In 1–2 plain lines, tell the user what this is — a portable memory & workflow system for this repo, so future sessions boot from a small structured memory instead of re-reading everything — and that they can run **`/agent-workflow-kit help`** any time to see every command. This is the "start here"; keep it to a sentence or two, then ask the visibility question.
-2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` — one managed block covering the full AI/agent footprint, never the machine-global excludes). See [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract).
-3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](${CLAUDE_SKILL_DIR}/references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
-4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](${CLAUDE_SKILL_DIR}/references/contracts.md#attribution-contract).
+   - **First-contact orientation — say this before the first question (read-only).** In 1–2 plain lines, tell the user what this is — a portable memory & workflow system for this repo, so future sessions boot from a small structured memory instead of re-reading everything — and that they can run **`/agent-workflow-kit help`** any time to see every command. This is the "start here"; keep it to a sentence or two, then ask the three setup questions (the step-2 batched prompt).
+2. **Choose visibility — ask the batched prompt NOW (all three questions, per the preamble above) and wait until every answer is in.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` — one managed block covering the full AI/agent footprint, never the machine-global excludes). See [Visibility contract](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract).
+3. **Choose conversational language — answered in the step-2 batch.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 5). See [Communication contract](${CLAUDE_SKILL_DIR}/references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
+4. **Choose agent attribution — answered in the step-2 batch.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](${CLAUDE_SKILL_DIR}/references/contracts.md#attribution-contract).
 5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
 6. **Deploy `docs/ai/`.** Create every `docs/ai/` file + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/` (the template loop deploys each non-`AGENTS.md` template — the `.md` docs **and** the two seeded, user-editable strict-JSON configs: **`docs/ai/orchestration.json`** (the per-project recipe defaults the `procedures` advisor reads) and **`docs/ai/gates.json`** (the project's gate declaration — an empty list to fill with its own verification commands, consumed by `${CLAUDE_SKILL_DIR}/references/modes/gates.md`)). Keep each `.md` file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`); the `.json` seeds carry no frontmatter (the docs cap-validator globs `*.md` only, so they are inherently skipped).
 7. **Fill templates** per the table below.
@@ -36,7 +36,12 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
     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 in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, 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; `${CLAUDE_SKILL_DIR}/references/modes/velocity.md`) or, once gates are declared, `/agent-workflow-kit hook` (auto-approve your own declared gate commands; `${CLAUDE_SKILL_DIR}/references/modes/hook.md`) 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 in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`). **After the footer, present ONE compact optional-accelerators block** — every entry preview-first, a one-line why each, nothing runs without a yes:
+    - `/agent-workflow-kit velocity` — routine read-only commands stop prompting (incl. the `--kit-tools` tier for the kit's own read-only tools; `${CLAUDE_SKILL_DIR}/references/modes/velocity.md`);
+    - `/agent-workflow-kit agents` — cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage; `${CLAUDE_SKILL_DIR}/references/modes/agents.md`);
+    - **gates seeding + hook** — offer to seed `docs/ai/gates.json` from the commands recon already recorded (step 1), via the consent-gated preview in `${CLAUDE_SKILL_DIR}/references/modes/gates.md` — this block is where that offer fires; then, once gates are declared, `/agent-workflow-kit hook` auto-approves exactly those declared commands (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`);
+    - `/agent-workflow-kit set-recipe` — put a ready review backend to work on plans and diffs (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`).
+    Then **ask before committing** — never auto-commit.
 
 Fill strategy:
 

package/references/modes/gates.md

@@ -12,6 +12,8 @@ The declaration is **seeded at bootstrap** (the template loop, `${CLAUDE_SKILL_D
 
 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 — `${CLAUDE_SKILL_DIR}/references/modes/hook.md`: the SAME declaration, a second consumer; editing gates.json needs no re-wiring.
 
-**Candidate line — the review-receipt gate (opt-in, never auto-seeded; AD-021).** Projects that configure a reviewed/council `plan-execution.review` recipe can declare the AD-038 review-state check as one more gate — the exact candidate `{ id, title, cmd }` line and its contract live under `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` (step 3). The template `gates.json` stays EMPTY; adding the line is the maintainer's explicit consent, by hand.
+**Candidate line — the review-receipt gate (opt-in, never auto-seeded; AD-021).** Projects that configure a reviewed/council `plan-execution.review` recipe can declare the AD-038 review-state check as one more gate — the exact candidate `{ id, title, cmd }` line and its contract live under `${CLAUDE_SKILL_DIR}/references/modes/review-state.md` (step 3). The template `gates.json` stays EMPTY; adding the line is the maintainer's explicit consent — by hand, or through the consent-gated seeder below (AD-042).
 
-**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.
+**Consent-gated seeding — a separate WRITER CLI, not part of the runner (AD-042).** Bootstrap recon already records the project's own daily commands; the seeder turns them into a preview of `{ id, title, cmd }` entries. Protocol: run `node ${CLAUDE_SKILL_DIR}/tools/seed-gates.mjs --cwd <project>` (dry-run by default — prints the derived entries and **writes NOTHING**; declining leaves the file byte-identical), show the user the EXACT entries (`AskUserQuestion` preview where supported, prose otherwise), and only on an explicit yes run it again with `--apply [--only <id>]…` — it **appends exactly the consented entries** (append-only: existing entries are never modified or removed; an id collision is refused loudly; a malformed declaration is never written over). Only terminating verification commands are offered (test / lint / type-check / build — never dev/watch/serve, never a formatter write-mode, never a release/publish/deploy script), commands are package-manager-aware, and the review-state candidate above is included automatically when the project's orchestration config declares reviewed/council on `plan-execution.review`. **Disclose before the yes** (the preview prints it): once the approval hook is wired, it auto-approves byte-exact declared gate commands — seeding and hook wiring are two separate consents.
+
+**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 · the seeder is a separate consent-per-run CLI — preview-first, append-only, never pre-approved by any velocity tier.

package/references/modes/review-state.md

@@ -6,7 +6,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/review-state.mjs [--check] [--json]`:
 
 1. Plain run → the human report: resolved recipe + source, plan-in-flight, tree fingerprint, per-backend receipt state (current / stale / ungrounded / missing) with verdict + grounding + timestamp.
 2. **`--check`** → the gate exit code. The **normative exit contract lives in the tool header** (the single home — do not re-enumerate it elsewhere): exit 0 for a solo-resolved recipe (configured, or degraded there — no ready reviewer), no plan in flight (the `docs/plans` naming convention: `queue.md` and `EXECUTE-`/`FEEDBACK-`-prefixed or `PROMPT`/`prompt`/`handoff`-carrying names are scratch), a clean tree, a non-git cwd, or every recipe-named backend receipted **current + grounded**; exit 1 when a backend is missing, **stale** (ANY edit after its review moves the fingerprint), or grounded:false under reviewed/council. **Presence, not unanimity:** verdict adjudication (ship/revise, the divergence crossover) stays orchestrator judgment — the gate only proves the configured backends really reviewed THIS tree. Plan/diff receipts and continuations (`agy-review --continue`) are **informational-only**: after a fold, only a **fresh grounded re-run** (`codex-review code`; `agy-review code --facts @f`) restores green.
-3. **Wire it as a gate by hand — never auto-seeded (AD-021).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate.
+3. **Wire it as a gate by hand OR via the explicit-consent seeder — never without consent (AD-021/AD-042).** The candidate line for your own `docs/ai/gates.json`: `{ "id": "review-state", "title": "Review receipts current for the uncommitted tree", "cmd": "node <path-to-this-skill>/tools/review-state.mjs --check" }` — with the path your project actually reaches the kit by, QUOTED so a path with spaces survives, executable from the project root. The consent-gated seeder (`${CLAUDE_SKILL_DIR}/references/modes/gates.md`, consent-seed section) offers exactly this entry — path resolved and quoted — ONLY when your `docs/ai/orchestration.json` declares `reviewed`/`council` on `plan-execution.review` (the slot this checker enforces); it writes nothing without your explicit yes. Once declared, the opt-in `${CLAUDE_SKILL_DIR}/references/modes/hook.md` auto-approves it like any other declared gate.
 
 **Human residual (stated, accepted):** `git commit --no-verify` and receipt-file deletion/forgery remain possible — this is a self-discipline mechanism against silent process drift, not a security boundary.
 

package/references/modes/status.md

@@ -14,6 +14,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/family-registry.mjs --json [--dir <project>]
    - **recipes** — the effective recipe per slot (detail → `/agent-workflow-kit procedures` / `recipes`); a `recipes.detectError` → say the backends couldn't be checked, so recipes floored at solo.
    - **attribution** — `includeCoAuthoredBy` effective; call out a **local override** only when `local` is non-null **and** differs from `project` (a `null` `local` means the key is absent there, so the project value stands — that is not an override).
    - **velocity** — the effective `permissions.defaultMode` + whether an allowlist is seeded (detail → `/agent-workflow-kit velocity`).
+   - **cheap agents** — how many of the kit's cheap-lane subagent vehicles are placed (`agents.placed` of `agents.bundled`; zero placed → the optional `/agent-workflow-kit agents` opt-in).
+   - **gate hook** — wired / hook file placed / declaration present, plus **`hook.declaredGates`** (0 = absent or an empty list; `null` = present but unreadable → say *couldn't be counted*, never a number; detail → `/agent-workflow-kit hook` and the gates guide).
    - Any area's **`error`** field → surface it **loudly** in plain language; the rest of `status` still renders (never a crash).
 4. **Bridges (host, one line)** (from `bridges[]`): per bridge — readiness + wrapper PATH-presence; render each wrapper's `state` as *on PATH* (`present`) / *not on PATH* (`missing`) / *couldn't check* (`unknown`) (detail → `/agent-workflow-kit backends` / `setup`). **No default-model claim.** "credentials present" means a marker file exists, not a live login.
 

package/references/modes/upgrade.md

@@ -48,9 +48,9 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
    - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology and orchestration-recipes) whether it was *added*, was *already present* (nothing changed), or was *skipped because the entry point is over its line limit* (the cap-refusal soft-skip from step 3, with its reason); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/` or found it *already present*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
-   - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity`).
+   - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
-6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
+6. **Collect the migration answers FIRST, then apply.** If `AGENTS.md` is missing BOTH the *Communication language* and *Attribution* blocks — i.e. both blocks are missing (a pre-1.1.0 deployment) — ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks (its own "Ask the user" step is the standalone fallback); a single missing block keeps its single ask (step 7). Then apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`. (An answer already collected by the step-6 batched prompt is carried in — never re-asked here.)
 8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 **placed-bridge refresh** lines (pasted verbatim) and the step-3 **agent-rules lens** outcome (same outcome set as step 4) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing**.

package/references/shared/deploy-tail.md

@@ -19,7 +19,7 @@ The non-obvious traps — scan these before bootstrapping or upgrading. Each is
 
 ## Setup contracts
 
-The three setup choices — **visibility** (step 2), **conversational language** (step 3), and **agent attribution** (step 4) — each have a full contract in [`references/contracts.md`](${CLAUDE_SKILL_DIR}/references/contracts.md). Load it when you need the complete rule (e.g. while filling the matching `AGENTS.md` block, or when an `upgrade` migration touches one). Defaults, in brief: visibility = `visible` (committed); language = whatever the user is already writing in; attribution = `off`. Ask each as a structured multiple-choice prompt where supported (`AskUserQuestion` in Claude Code), otherwise in prose.
+The three setup choices — **visibility** (step 2), **conversational language** (step 3), and **agent attribution** (step 4) — each have a full contract in [`references/contracts.md`](${CLAUDE_SKILL_DIR}/references/contracts.md). Load it when you need the complete rule (e.g. while filling the matching `AGENTS.md` block, or when an `upgrade` migration touches one). Defaults, in brief: visibility = `visible` (committed); language = whatever the user is already writing in; attribution = `off`. Ask the three as ONE structured multi-question prompt where supported (`AskUserQuestion` in Claude Code, up to 4 questions per call), otherwise in prose; record each answer individually — and write nothing until ALL are answered.
 
 ---
 

package/references/shared/report-footer.md

@@ -74,8 +74,9 @@ the rest of the report — and the commit gate — proceeds.
 
 **Welcome mat — the last line(s) of the footer.** After the version block and the backend-status
 line, print *"Run `/agent-workflow-kit help` to see every command."* then **one** recommended next
-step, chosen **caveat-aware** from signals already in hand (the version block's notes + the
-backend-status line — no new helper call) in this priority order:
+step, chosen **caveat-aware** from signals already in hand (the version block's notes, the settings
+areas of the same `--json` envelope, and the backend-status line — no new helper call) in this
+priority order:
 1. a member is **behind** (a behind-class `installed[].notes` caveat fired — any member, the bridges
    included) → *refresh the behind member first*, quoting **that note's own recovery command
    verbatim** (a memory/engine note carries its `npx …@latest init` + restart the session; a bridge
@@ -87,8 +88,14 @@ backend-status line — no new helper call) in this priority order:
 3. else **a backend is ready but the orchestration config is still all-Solo** (no `reviewed` /
    `council` / `delegated` slot anywhere — inspect `docs/ai/orchestration.json`, or read the
    procedures advisor's resolved recipes) → *put it to work with `/agent-workflow-kit recipes`*;
-4. else (a backend is ready **and** a backend-backed recipe is already selected) → the optional
-   *`/agent-workflow-kit velocity`* opt-in (never run it without a yes).
+4. else **the velocity allowlist is not yet seeded** (the envelope's velocity settings show zero
+   allow entries) → the optional *`/agent-workflow-kit velocity`* opt-in (never run it without a
+   yes);
+5. else **the cheap-lane agent vehicles are not placed** (the envelope's agents settings show zero
+   placed) → the optional *`/agent-workflow-kit agents`* opt-in (never run it without a yes);
+6. else **gates are declared but the approval hook is not wired** (the envelope's hook settings:
+   at least one declared gate, wired = no) → the optional *`/agent-workflow-kit hook`* opt-in
+   (never run it without a yes). If no rung applies, the help line above stands alone.
 
 Keep it compact — a few short lines, plain language, no kit-internal terms.
 

package/tools/atomic-write.mjs

@@ -0,0 +1,106 @@
+// atomic-write.mjs — the family's ONE hardened atomic-write core for kit writers that target a
+// file under a project's docs/ai/. Extracted from orchestration-write.mjs (the only full
+// implementation of the discipline, AD-042) and parameterized by (rel, body, stop identity) so
+// BOTH consumers run the same guarded flow with zero drift:
+//   • orchestration-write.mjs — docs/ai/orchestration.json (public API unchanged);
+//   • seed-gates.mjs          — docs/ai/gates.json (the consent-gated seeder).
+//
+// The discipline (verbatim from the source implementation):
+//   - DEPLOYMENT GATE first: refuse to scatter a file into a repo with no docs/ai/ — STOP loud.
+//   - refuse a SYMLINKED leaf — a rename would silently replace the link target.
+//   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
+//     docs/ or docs/ai/ PARENT, not just the leaf, and refuses any escape outside cwd.
+//   - atomic: write a UNIQUE *.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
+//   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
+//   - tmp cleaned up on any failure after its creation.
+//   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
+//
+// Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are
+// unit-testable. NEVER imported by a read-only module (procedures.mjs — pinned by an import guard).
+
+import { lstatSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+
+export const ATOMIC_WRITE_STOP = 'ATOMIC_WRITE_STOP';
+const defaultStop = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'AtomicWriteStop', code: ATOMIC_WRITE_STOP });
+
+// lstat without following symlinks; null when absent. A non-ENOENT error propagates (never fail open).
+export const lstatNoFollow = (path, lstat = lstatSync) => {
+  try {
+    return lstat(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// Deployment gate — never scatter a file into a non-deployed repo. lstat, NOT existsSync:
+// existsSync FOLLOWS a symlink, so a DANGLING `docs/ai` symlink would read as "absent" and
+// mislabel a broken/symlinked deployment as "no deployment". lstat the leaf instead: a true
+// ENOENT → no deployment (STOP, run init); a symlink or non-directory → STOP loud.
+// `noun` names what the caller writes ("a config" / "a gate declaration") so each consumer's STOP
+// message stays exactly as its own tests pinned it.
+export const assertDocsAiDeployment = (cwd, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const stop = opts.stop ?? defaultStop;
+  const noun = opts.noun ?? 'a file';
+  const rel = opts.rel ?? 'under docs/ai';
+  const docsAi = join(cwd, 'docs', 'ai');
+  const docsAiStat = lstatNoFollow(docsAi, lstat);
+  if (docsAiStat === null) {
+    throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${rel}`);
+  }
+  if (docsAiStat.isSymbolicLink()) {
+    throw stop(`docs/ai is a symlink — refusing to write ${noun} through it (run init/bootstrap in a real deployment)`);
+  }
+  if (!docsAiStat.isDirectory()) {
+    throw stop(`docs/ai exists but is not a directory — refusing to write ${rel}`);
+  }
+};
+
+// writeDocsAiFileAtomic(cwd, rel, body, deps, opts) → { writtenPath: rel } on success; THROWS the
+// caller's typed STOP (via opts.stop) or a native fs error otherwise. `body` arrives pre-serialized
+// (each consumer owns its canonical serialization).
+export const writeDocsAiFileAtomic = (cwd, rel, body, deps = {}, opts = {}) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const writeFile = deps.writeFile ?? writeFileSync;
+  const rename = deps.rename ?? renameSync;
+  const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
+  const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
+  const stop = opts.stop ?? defaultStop;
+  const guard = (target) => assertContainedRealPath(cwd, target, { lstat });
+
+  assertDocsAiDeployment(cwd, deps, { ...opts, rel });
+
+  const dst = join(cwd, rel);
+  // Refuse a symlinked leaf with a CLEAR message before the generic traversal guard fires (a rename
+  // would silently replace the link rather than the file the user thinks they are editing).
+  const leaf = lstatNoFollow(dst, lstat);
+  if (leaf && leaf.isSymbolicLink()) {
+    throw stop(`${rel} is a symlink — refusing to replace it (a write would clobber the link target)`);
+  }
+  // Guard the dst + a unique tmp SIBLING: refuses a symlinked docs/ or docs/ai/ parent, and any escape.
+  guard(dst);
+  const tmp = `${dst}.${rand()}.tmp`;
+  guard(tmp);
+
+  // Exclusive-create (wx): never clobber a leftover tmp (a stray collision is surfaced, not silently
+  // overwritten). The random suffix makes a collision effectively impossible; wx makes it impossible-loud.
+  writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
+  try {
+    // TOCTOU re-check: the parent chain + the leaf may have changed since the pre-checks above.
+    guard(dst);
+    const leafAgain = lstatNoFollow(dst, lstat);
+    if (leafAgain && leafAgain.isSymbolicLink()) {
+      throw stop(`${rel} became a symlink — refusing to replace it`);
+    }
+    rename(tmp, dst);
+  } catch (err) {
+    rm(tmp); // never leave a temp file behind on failure
+    throw err;
+  }
+  return { writtenPath: rel };
+};

package/tools/commands.mjs

@@ -96,7 +96,7 @@ const CATALOG = [
     invocation: invocationOf('gates'),
     group: 'Inspect',
     kind: PROJECT_EXEC,
-    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line.',
+    oneLine: 'Run the project’s own declared gate commands (docs/ai/gates.json) as one batch — a PASS/FAIL table, one summary line. The mode itself writes nothing; a separate consent-gated seeder can propose entries from your project’s own scripts (preview first, written only on your yes).',
   },
   {
     key: 'setup',
@@ -212,6 +212,19 @@ const KIND_TAG = {
 };
 const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
 
+// The "Tune" tail — the opt-in accelerator funnel, rendered AFTER the catalog groups. NOT a new
+// catalog key or mode (the frozen CATALOG + GROUP_ORDER stay; the router SKILL.md is untouched):
+// the same four entries the bootstrap accelerators block presents, one line of why each.
+const TUNE_TAIL = Object.freeze([
+  '',
+  'Tune — opt-in accelerators (consent-first: every writer previews before writing; nothing runs without your yes)',
+  `  ${BARE_INVOCATION} velocity      routine read-only commands stop prompting (incl. the --kit-tools tier for the kit's own read-only tools)`,
+  `  ${BARE_INVOCATION} agents        cheap-model subagents take the mechanical work (sweeps, changelog skeletons, gate triage)`,
+  `  ${BARE_INVOCATION} gates         run your declared gates (docs/ai/gates.json) as one batch; its guide also offers the consent-gated seeding preview — writes only on your yes`,
+  `  ${BARE_INVOCATION} hook          auto-approve exactly your declared gate commands (byte-exact matches only)`,
+  `  ${BARE_INVOCATION} set-recipe    put a ready review backend to work on plans and diffs`,
+]);
+
 // formatHelp() → the grouped, kind-tagged human index. Deterministic; groups in GROUP_ORDER, modes in
 // catalog order within each group. The header states the index itself is read-only.
 export const formatHelp = () => {
@@ -229,6 +242,7 @@ export const formatHelp = () => {
       lines.push(`  ${pad(c.invocation, invocWidth)}  ${KIND_TAG[c.kind] ?? c.kind}  ${c.oneLine}`);
     }
   }
+  lines.push(...TUNE_TAIL);
   return lines.join('\n');
 };
 

package/tools/family-registry.mjs

@@ -47,7 +47,10 @@ import {
 // 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';
+import { GATES_REL, loadDeclaration } from './run-gates.mjs';
+// The cheap-agents writer's own bundle reader + placement planner — reused by the settings survey
+// (one implementation, never a drifting copy; cheap-agents imports only node builtins, no cycle).
+import { readBundledAgents, planPlacement } from './cheap-agents.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
@@ -456,21 +459,50 @@ export const surveyGateHook = (dir, deps = {}) => {
     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 });
+    // How many gates are actually DECLARED — the welcome-mat hook rung keys on a non-empty
+    // declaration (a fresh bootstrap seeds gates.json EMPTY, so file presence alone would misfire).
+    // 0 = absent or empty list; null = present but unreadable/malformed (unknown — never a false
+    // count, and never an area-wide error: the wired/placed probes still report; the validation
+    // REASON is preserved beside the null so status never renders a bare question mark).
+    const declaration = (() => {
+      try {
+        const res = loadDeclaration(d, deps);
+        return { declaredGates: res.outcome === 'loaded' ? res.gates.length : 0 };
+      } catch (err) {
+        return { declaredGates: null, declarationError: localizeError(err) };
+      }
+    })();
     return {
       wired: isHookWired(project.data) || isHookWired(local.data),
       filePlaced: Boolean(exists(join(d, GATE_HOOK_FILE_REL))),
       declarationPresent: Boolean(exists(join(d, GATES_REL))),
+      ...declaration,
     };
   } catch (err) {
     return { error: localizeError(err) };
   }
 };
 
+// cheap agents: the kit-placed .claude/agents/ vehicles (Mode: agents) — how many of the bundled
+// cheap-lane definitions are present in the project. A customized copy counts as PLACED (it exists;
+// the writer preserves it) — the welcome-mat agents rung keys on zero placed. Read-only; REUSES the
+// writer's own bundle reader + placement planner (cheap-agents.mjs — one implementation).
+export const surveyCheapAgents = (dir, deps = {}) => {
+  try {
+    const templates = readBundledAgents(deps);
+    const plan = planPlacement(templates, resolve(dir), deps);
+    return { bundled: templates.length, placed: plan.filter((p) => p.action !== 'place').length };
+  } 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),
+  agents: surveyCheapAgents(dir, deps),
   hook: surveyGateHook(dir, deps),
 });
 

package/tools/orchestration-write.mjs

@@ -4,94 +4,24 @@
 // can never reach a writer" is a STRUCTURAL invariant (an import-split test pins it), not just an
 // assertion. Splitting the writer out of the schema/read module keeps the read surface fs-write-free.
 //
-// writeConfig is hardened (mirrors the setup-backends posture):
-//   - DEPLOYMENT GATE first: refuse to scatter a config into a repo with no docs/ai/ — STOP loud,
-//     pointing at init/bootstrap (a config without a deployment is meaningless + surprising).
-//   - refuse a SYMLINKED leaf (orchestration.json itself a symlink) — a rename would silently replace
-//     the link target.
-//   - guard the dst + the tmp sibling with assertContainedRealPath (fs-safe) — refuses a symlinked
-//     docs/ or docs/ai/ PARENT, not just the leaf, and refuses any escape outside cwd.
-//   - atomic: write a UNIQUE *.json.<rand>.tmp opened EXCLUSIVE-CREATE (wx), then rename over the dst.
-//   - RE-CHECK the parent chain + the leaf immediately before the rename (TOCTOU).
-//   - LAST-WRITER-WINS: local, single-user; no cross-process lock (documented, not silently assumed).
+// The hardened write flow (deployment gate → symlink STOPs → containment guard → exclusive-create
+// tmp + rename with a TOCTOU re-check → tmp cleanup; LAST-WRITER-WINS, documented) lives in the
+// shared atomic-write core (tools/atomic-write.mjs, extracted from this module — AD-042) and is
+// consumed here with this module's own STOP identity, so the public API + error contract are
+// unchanged (this file's tests pin them, characterize-first).
 //
 // Dependency-free, Node >= 18. Every fs primitive is injectable (deps.*) so the guards are unit-testable.
 
-import { lstatSync, writeFileSync, renameSync, rmSync } from 'node:fs';
-import { randomBytes } from 'node:crypto';
-import { join } from 'node:path';
-import { assertContainedRealPath } from './fs-safe.mjs';
 import { CONFIG_REL, serializeConfig } from './orchestration-config.mjs';
+import { writeDocsAiFileAtomic } from './atomic-write.mjs';
 
 // A typed STOP — a deliberate refusal we surface (deployment gate / symlinked leaf), distinct from a
 // native fs error. `Object.assign(new Error(), { code })`, the codebase's typed-error idiom (no classes).
 export const ORCH_WRITE_STOP = 'ORCH_WRITE_STOP';
 const stop = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'OrchWriteStop', code: ORCH_WRITE_STOP });
 
-// lstat without following symlinks; null when absent. A non-ENOENT error propagates (never fail open).
-const lstatNoFollow = (path, lstat) => {
-  try {
-    return lstat(path);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    throw err;
-  }
-};
-
 // writeConfig(cwd, config, deps) → { writtenPath } on success; THROWS a typed STOP (no deployment /
 // symlinked leaf) or a native fs error otherwise. The tmp is cleaned up on any failure after its
 // creation. config is serialized canonically (serializeConfig: 2-space, _README-first, trailing NL).
-export const writeConfig = (cwd, config, deps = {}) => {
-  const lstat = deps.lstat ?? lstatSync;
-  const writeFile = deps.writeFile ?? writeFileSync;
-  const rename = deps.rename ?? renameSync;
-  const rm = deps.rm ?? ((p) => rmSync(p, { force: true }));
-  const rand = deps.rand ?? (() => randomBytes(6).toString('hex'));
-  const guard = (target) => assertContainedRealPath(cwd, target, { lstat });
-
-  // Deployment gate — never scatter a config into a non-deployed repo (mirror velocity / setup). lstat,
-  // NOT existsSync: existsSync FOLLOWS a symlink, so a DANGLING `docs/ai` symlink would read as "absent"
-  // and mislabel a broken/symlinked deployment as "no deployment". lstat the leaf instead: a true ENOENT
-  // → no deployment (STOP, run init); a symlink or non-directory → STOP loud (never write through it).
-  const docsAi = join(cwd, 'docs', 'ai');
-  const docsAiStat = lstatNoFollow(docsAi, lstat);
-  if (docsAiStat === null) {
-    throw stop(`no agent-workflow deployment here (docs/ai is absent) — run init/bootstrap before writing ${CONFIG_REL}`);
-  }
-  if (docsAiStat.isSymbolicLink()) {
-    throw stop(`docs/ai is a symlink — refusing to write a config through it (run init/bootstrap in a real deployment)`);
-  }
-  if (!docsAiStat.isDirectory()) {
-    throw stop(`docs/ai exists but is not a directory — refusing to write ${CONFIG_REL}`);
-  }
-
-  const dst = join(cwd, CONFIG_REL);
-  // Refuse a symlinked leaf with a CLEAR message before the generic traversal guard fires (a rename
-  // would silently replace the link rather than the file the user thinks they are editing).
-  const leaf = lstatNoFollow(dst, lstat);
-  if (leaf && leaf.isSymbolicLink()) {
-    throw stop(`${CONFIG_REL} is a symlink — refusing to replace it (a write would clobber the link target)`);
-  }
-  // Guard the dst + a unique tmp SIBLING: refuses a symlinked docs/ or docs/ai/ parent, and any escape.
-  guard(dst);
-  const tmp = `${dst}.${rand()}.tmp`;
-  guard(tmp);
-
-  const body = serializeConfig(config);
-  // Exclusive-create (wx): never clobber a leftover tmp (a stray collision is surfaced, not silently
-  // overwritten). The random suffix makes a collision effectively impossible; wx makes it impossible-loud.
-  writeFile(tmp, body, { encoding: 'utf8', flag: 'wx' });
-  try {
-    // TOCTOU re-check: the parent chain + the leaf may have changed since the pre-checks above.
-    guard(dst);
-    const leafAgain = lstatNoFollow(dst, lstat);
-    if (leafAgain && leafAgain.isSymbolicLink()) {
-      throw stop(`${CONFIG_REL} became a symlink — refusing to replace it`);
-    }
-    rename(tmp, dst);
-  } catch (err) {
-    rm(tmp); // never leave a temp file behind on failure
-    throw err;
-  }
-  return { writtenPath: CONFIG_REL };
-};
+export const writeConfig = (cwd, config, deps = {}) =>
+  writeDocsAiFileAtomic(cwd, CONFIG_REL, serializeConfig(config), deps, { stop, noun: 'a config' });

package/tools/presentation.mjs

@@ -41,6 +41,7 @@ export const SETTINGS_LABELS = Object.freeze({
   recipes: 'recipes',
   attribution: 'attribution',
   velocity: 'velocity',
+  agents: 'cheap agents',
   hook: 'gate hook',
 });
 

package/tools/renderers.mjs

@@ -101,11 +101,19 @@ const renderSettings = (vm, { color, glyph }) => {
   else if (s.velocity) {
     lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}defaultMode=${String(s.velocity.defaultMode)} · allow project/local=${s.velocity.allow.project}/${s.velocity.allow.local}`);
   }
-  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present.
+  // cheap agents — the kit-placed .claude/agents/ vehicles: placed count vs the bundle.
+  if (s.agents?.error) lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}error: ${s.agents.error}`);
+  else if (s.agents) {
+    lines.push(`  ${pad(SETTINGS_LABELS.agents, SETTINGS_COL)}placed=${s.agents.placed}/${s.agents.bundled}`);
+  }
+  // gate hook — the opt-in PreToolUse gate-approval hook: wired / file placed / declaration present /
+  // declared gate count (null → '?' — unknown is shown as unknown, never as a number).
   if (s.hook?.error) lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}error: ${s.hook.error}`);
   else if (s.hook) {
     const yn = (b) => (b ? 'yes' : 'no');
-    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)}`);
+    // A null count carries its preserved validation reason — never a silent bare "?".
+    const declared = s.hook.declaredGates ?? (s.hook.declarationError ? `? (${s.hook.declarationError})` : '?');
+    lines.push(`  ${pad(SETTINGS_LABELS.hook, SETTINGS_COL)}wired=${yn(s.hook.wired)} · file=${yn(s.hook.filePlaced)} · gates.json=${yn(s.hook.declarationPresent)} · declared=${declared}`);
   }
   return lines;
 };

package/tools/review-state.mjs

@@ -5,7 +5,8 @@
 // resolves the effective `plan-execution.review` recipe (the advisor's single-source readers),
 // recomputes the CURRENT canonical uncommitted-state fingerprint, and reports — per recipe-named
 // backend — whether a FRESH, grounded, current-fingerprint receipt exists. `--check` turns the
-// report into a gate exit code (declare it in docs/ai/gates.json — by hand; never auto-seeded).
+// report into a gate exit code (declare it in docs/ai/gates.json — by hand OR via the
+// explicit-consent seeder, tools/seed-gates.mjs — never without consent, AD-021/AD-042).
 //
 // Normative `--check` exit contract (the single home of this list — SKILL.md points here):
 //   exit 0  when the resolved plan-execution.review recipe is solo (configured, or degraded there —
@@ -353,7 +354,8 @@ presence + verdict + grounding for the CURRENT tree. Plan/diff-mode receipts and
 --check exits 0/1 per the normative contract in the tool header: 0 for solo / no plan in flight /
 a clean tree / not-a-git-tree / all recipe-named backends receipted-current-and-grounded; 1 when a
 recipe-named backend is missing, stale (edited after review), or grounded:false under
-reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) — never auto-seeded.
+reviewed/council. Declare it as a project gate by hand (docs/ai/gates.json) or via the
+explicit-consent seeder (tools/seed-gates.mjs) — never without consent.
 
 Read-only: never writes, never commits, never runs a subscription CLI; spawns read-only git queries.
 Human residual: git commit --no-verify and receipt-file deletion remain possible — this is a

package/tools/seed-gates.mjs

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+// seed-gates.mjs — the consent-gated docs/ai/gates.json seeder (AD-042). Reached ONLY through
+// explicitly-consenting prose (the bootstrap accelerators block and the gates.md consent-seed
+// 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.
+//
+// What it offers (the derivation invariants, test-pinned):
+//   • sources: discoverGateCandidates over package.json scripts (velocity-profile.mjs stays
+//     read-only; THIS module owns the offer mapping) + the conditional review-state candidate;
+//   • warn-flagged candidates (release/publish/deploy/push/version/commit/tag, pre*/post*) NEVER
+//     enter the offer — excluded, not offered-with-a-warning;
+//   • only TERMINATING verification classes are offered (test / lint / type-check / build) —
+//     never dev/start/watch/serve/preview, never a formatter write-mode;
+//   • commands are package-manager-aware (packageManager field, else lockfile probe, else npm);
+//   • ids derive kebab-case from script names (build:prod → build-prod) and every offered entry
+//     passes the runner's validateDeclaration (the seeder imports the validator — NEVER the
+//     reverse: run-gates.mjs stays a runner that writes nothing);
+//   • the review-state candidate appears ONLY when docs/ai/orchestration.json DECLARES
+//     reviewed/council on plan-execution.review — the slot the checker enforces — with the
+//     resolved, QUOTED tool path (spaces survive; executes from the project root).
+//
+// Write discipline: preview (dry-run) is the DEFAULT and writes NOTHING — a declined offer leaves
+// the file byte-identical. `--apply` appends EXACTLY the consented entries (`--only <id>`
+// repeatable) through the shared atomic-write core (tools/atomic-write.mjs — exclusive-create
+// tmp+rename, TOCTOU re-check, symlink STOPs): append-only, never modifies or removes an existing
+// entry, refuses id collisions, refuses a malformed declaration (never writes over what it cannot
+// parse). Deployment-gated: docs/ai presence (lstat, no-follow) on EVERY run; the
+// .workflow-version == lineage-head stamp gate on --apply only (the velocity/gate-hook precedent).
+//
+// Exit codes: 0 done / dry-run; 1 precondition STOP (no deployment, stamp, symlink, malformed
+// declaration, id collision); 2 usage. Dependency-free, Node >= 18. No side effects on import.
+
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { discoverGateCandidates, EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
+import { GATES_REL, validateDeclaration } from './run-gates.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { assertDocsAiDeployment, writeDocsAiFileAtomic, lstatNoFollow } from './atomic-write.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const KIT_ROOT = resolve(HERE, '..');
+const TEMPLATE_PATH = join(KIT_ROOT, 'references', 'templates', 'gates.json');
+const REVIEW_STATE_TOOL = join(KIT_ROOT, 'tools', 'review-state.mjs');
+const STAMP_REL = join('docs', 'ai', '.workflow-version');
+
+const EXIT_OK = 0;
+const EXIT_PRECONDITION = 1;
+const EXIT_USAGE = 2;
+
+export const SEED_GATES_STOP = 'SEED_GATES_STOP';
+const stop = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SeedGatesStop', code: SEED_GATES_STOP, exitCode: EXIT_PRECONDITION });
+const usageFail = (message) =>
+  Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: EXIT_USAGE });
+
+// The trust-chain disclosure (AD-042) — printed with EVERY preview, token-pinned by the tests: a
+// consent-seeded command becomes auto-approvable only after TWO explicit consents.
+export const TRUST_CHAIN_DISCLOSURE =
+  'Disclosure: once the optional approval hook is wired (/agent-workflow-kit hook), it ' +
+  'auto-approves byte-exact declared gate commands from the project root — seeding (this consent) ' +
+  'and hook wiring (its own consent) are two separate yeses.';
+
+const USAGE = `usage: seed-gates [--dry-run | --apply] [--only <id>]... [--cwd <dir>] [--help]
+
+Consent-gated seeder for the project's own docs/ai/gates.json. Default is --dry-run: prints the
+derived { id, title, cmd } entries and writes NOTHING. --apply APPENDS exactly the consented
+entries (--only <id> selects a subset; append-only — existing entries are never modified or
+removed, an id collision is refused). Only terminating verification commands are offered
+(test / lint / type-check / build); release/publish/deploy scripts and watch/serve modes never
+enter the offer. ${TRUST_CHAIN_DISCLOSURE}`;
+
+// ── candidate classification (the LOCKED derivation invariants) ────────────────────────
+// The derived cmd (`<pm> run <name>`) is bash-interpolated by the gate runner and can become
+// hook-auto-approvable, so only shell-SAFE script names ever enter the offer: a name carrying
+// whitespace or any shell metacharacter (`test:ci && echo pwn`) is screened out entirely.
+const SAFE_SCRIPT_NAME_PATTERN = /^[A-Za-z0-9:_.-]+$/;
+const TERMINATING_CLASS_PATTERN = /^(test|lint|type-?check|types|tsc|build)([:._-]|$)/i;
+// Non-terminating screening is TOKEN-set based, position-independent (never an anchored regex —
+// the anchored form missed `build:preview` and a bare `vite preview` body): a non-terminating
+// token in ANY name segment, or as ANY bare/dashed body word, disqualifies; `watch` disqualifies
+// as a substring anywhere (watchAll, --watchAll). Conservative on purpose — a screened-out script
+// can still be declared by hand; a wrongly-included one would become hook-auto-approvable.
+const NON_TERMINATING_TOKENS = new Set(['dev', 'start', 'serve', 'watch', 'preview']);
+// A terminating-looking NAME can still hide release work in its BODY (`"test": "npm publish"`):
+// the same token classes the warn-name screen rejects are rejected as bare body words too — an
+// offered cmd is hook-auto-approvable, so a dangerous body must never ride a clean name.
+const DANGEROUS_BODY_TOKENS = new Set(['release', 'publish', 'deploy', 'push', 'version', 'commit', 'tag']);
+const WATCH_ANYWHERE_PATTERN = /watch/i;
+const wordOf = (raw) => raw.toLowerCase().replace(/^-+/, '').split('=')[0];
+const hasTokenIn = (text, splitter, tokens) =>
+  String(text)
+    .split(splitter)
+    .some((part) => tokens.has(wordOf(part)));
+const isNonTerminatingName = (name) =>
+  hasTokenIn(name, /[:._-]/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(name);
+const isNonTerminatingBody = (body) =>
+  hasTokenIn(body, /\s+/, NON_TERMINATING_TOKENS) || WATCH_ANYWHERE_PATTERN.test(body);
+const isDangerousBody = (body) => hasTokenIn(body, /\s+/, DANGEROUS_BODY_TOKENS);
+// A MUTATING VARIANT of a terminating class never enters the offer — a hook-auto-approvable gate
+// must never be a writer. Screened on BOTH axes: the script NAME (lint:fix, test:update,
+// build:write, test:snapshot) and the script BODY's write-mode flags (eslint --fix,
+// prettier --write / -w, jest -u / --updateSnapshot, tsc -w). Conservative by design: an excluded
+// candidate can still be declared by hand — a wrongly-included one would be silently auto-approved.
+const MUTATING_VARIANT_NAME_PATTERN = /(^|[:._-])(fix|write|update|snapshot)([:._-]|$)/i;
+const MUTATING_BODY_FLAG_PATTERN = /(^|\s)(--fix|--write|--update(?:-snapshot)?|--updateSnapshot|-w|-u)(=|\s|$)/;
+
+export const kebabIdOf = (name) =>
+  String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+// package manager: the package.json `packageManager` field wins, else the lockfile probe, else npm.
+export const detectPackageManager = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const exists = deps.exists ?? existsSync;
+  const fromField = (() => {
+    try {
+      const pkg = JSON.parse(String(read(join(cwd, 'package.json'), 'utf8')));
+      const pm = typeof pkg.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
+      return pm === 'pnpm' || pm === 'yarn' || pm === 'npm' ? pm : null;
+    } catch {
+      return null;
+    }
+  })();
+  if (fromField) return fromField;
+  if (exists(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (exists(join(cwd, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+};
+
+// The script-derived offer entries. Order = package.json scripts order (the offer the user reads).
+export const deriveScriptEntries = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const pkg = (() => {
+    try {
+      return JSON.parse(String(read(join(cwd, 'package.json'), 'utf8')));
+    } catch {
+      return null; // no/unreadable package.json → no script candidates (an honest empty offer)
+    }
+  })();
+  const pm = detectPackageManager(cwd, deps);
+  const seen = new Set();
+  const bodyOf = (name) => String(pkg?.scripts?.[name] ?? '');
+  return discoverGateCandidates(pkg ?? {})
+    .filter((c) => !c.warn) // warn-flagged NEVER enter the offer
+    .filter((c) => SAFE_SCRIPT_NAME_PATTERN.test(c.scriptName)) // shell-safe names only, FIRST
+    .filter((c) => TERMINATING_CLASS_PATTERN.test(c.scriptName))
+    .filter((c) => !isNonTerminatingName(c.scriptName))
+    .filter((c) => !MUTATING_VARIANT_NAME_PATTERN.test(c.scriptName) && !MUTATING_BODY_FLAG_PATTERN.test(bodyOf(c.scriptName)))
+    .filter((c) => !isNonTerminatingBody(bodyOf(c.scriptName)))
+    .filter((c) => !isDangerousBody(bodyOf(c.scriptName)))
+    .map((c) => ({
+      id: kebabIdOf(c.scriptName),
+      title: `Project script: ${pm} run ${c.scriptName}`,
+      cmd: `${pm} run ${c.scriptName}`,
+    }))
+    .filter((e) => {
+      if (!e.id || seen.has(e.id)) return false; // an empty or duplicate derived id never enters the offer
+      seen.add(e.id);
+      return true;
+    });
+};
+
+// The conditional review-state candidate — keyed on the SLOT the checker enforces
+// (plan-execution.review, tools/review-state.mjs), read via the shared config reader. Offered only
+// when the config DECLARES reviewed/council there; solo configs and a council-on-plan-authoring-only
+// config never see it. The cmd carries the resolved, QUOTED tool path and passes the validator.
+// Double-quote-unsafe shell metacharacters: inside `"…"` bash still expands `$`, backticks and
+// backslashes, and a `"` breaks the quoting entirely. A candidate cmd is hook-auto-approvable, so a
+// path that cannot be safely double-quoted is WITHHELD with a loud note — never offered wrongly.
+const DQ_UNSAFE_PATH_PATTERN = /["$`\\\r\n]/;
+
+export const reviewStateCandidate = (cwd, deps = {}) => {
+  const toolPath = deps.reviewStateTool ?? REVIEW_STATE_TOOL;
+  try {
+    const { config } = loadConfig(resolve(cwd), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const declared = config?.['plan-execution']?.review;
+    if (declared !== 'reviewed' && declared !== 'council') return { candidate: null, note: null };
+    if (DQ_UNSAFE_PATH_PATTERN.test(toolPath)) {
+      return {
+        candidate: null,
+        note:
+          `the review-state candidate was withheld: the resolved kit path contains shell ` +
+          `metacharacters that do not survive double-quoting (${toolPath}) — declare the gate ` +
+          `by hand per references/modes/review-state.md step 3`,
+      };
+    }
+    return {
+      candidate: {
+        id: 'review-state',
+        title: 'Review receipts current for the uncommitted tree',
+        cmd: `node "${toolPath}" --check`,
+      },
+      note: null,
+    };
+  } catch (err) {
+    return {
+      candidate: null,
+      note: `orchestration config unreadable (${err.message}) — the review-state candidate was not evaluated`,
+    };
+  }
+};
+
+// Every --only id must name an OFFERED entry — enforced in BOTH paths (dry-run and apply), before
+// any empty-offer shortcut, so a typo is a loud usage error, never a silent filter or a silent
+// "nothing to offer" success.
+const assertOnlyIdsOffered = (offer, onlyIds = []) => {
+  const offered = new Set(offer.entries.map((e) => e.id));
+  const unknown = onlyIds.filter((id) => !offered.has(id));
+  if (unknown.length) {
+    throw usageFail(`--only names ids not in the offer: ${unknown.join(', ')} (offered: ${[...offered].join(', ') || 'none'})`);
+  }
+};
+
+// The full offer: script entries + the conditional review-state candidate (last), plus loud notes.
+export const buildOffer = (cwd, deps = {}) => {
+  const entries = deriveScriptEntries(cwd, deps);
+  const { candidate, note } = reviewStateCandidate(cwd, deps);
+  return {
+    entries: candidate ? [...entries, candidate] : entries,
+    notes: note ? [note] : [],
+  };
+};
+
+// The RUNNABLE apply invocation for a given project — this tool has no bin and no mode token, so
+// the consent step must print the real command, never a bare `seed-gates`. Consent integrity: a
+// previewed --only subset is carried into the hint VERBATIM (ids are shell-safe by construction —
+// kebabIdOf output / the fixed `review-state`), so following the hint can never widen the consent.
+// Paths that do not survive double-quoting (the reviewStateCandidate screen, same pattern) make
+// this return null — the preview then falls back to a generic, unquoted instruction.
+export const applyInvocationFor = (cwd, onlyIds = []) => {
+  const ownPath = fileURLToPath(import.meta.url);
+  if (DQ_UNSAFE_PATH_PATTERN.test(ownPath) || DQ_UNSAFE_PATH_PATTERN.test(cwd)) return null;
+  const only = onlyIds.map((id) => ` --only ${id}`).join('');
+  return `node "${ownPath}" --cwd "${cwd}" --apply${only}`;
+};
+
+const GENERIC_APPLY_HINT = 're-run this same command with --apply [--only <id>]...';
+
+export const formatPreview = (offer, applyInvocation = null, { explicitOnly = false } = {}) => {
+  const lines = ['[agent-workflow-kit] gates seeding preview (dry-run — nothing was written):'];
+  if (!offer.entries.length) {
+    lines.push('  nothing to offer — no seedable terminating verification scripts were found.');
+  }
+  for (const e of offer.entries) {
+    lines.push(`  ${e.id}: ${e.cmd}   (${e.title})`);
+  }
+  for (const note of offer.notes) lines.push(`  note: ${note}`);
+  if (offer.entries.length) {
+    const suffix = explicitOnly ? '' : ' [--only <id>]...';
+    lines.push(`  apply exactly the entries you consent to: ${applyInvocation ?? GENERIC_APPLY_HINT}${applyInvocation ? suffix : ''}`);
+  }
+  lines.push(`  ${TRUST_CHAIN_DISCLOSURE}`);
+  return lines.join('\n');
+};
+
+// ── the existing declaration (append-only source) ──────────────────────────────────────
+const loadExistingDeclaration = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  const lstat = deps.lstat ?? lstatSync;
+  const full = join(cwd, GATES_REL);
+  const leaf = lstatNoFollow(full, lstat);
+  if (leaf === null) return { outcome: 'missing' };
+  // Refuse a symlinked leaf HERE, before any read/parse — the atomic core would refuse it at write
+  // time anyway, but the honest STOP names the symlink, not a misleading parse error on its target.
+  if (leaf.isSymbolicLink()) {
+    throw stop(`${GATES_REL} is a symlink — refusing to touch it (a write would clobber the link target)`);
+  }
+  const parsed = (() => {
+    try {
+      return JSON.parse(String(read(full, 'utf8')));
+    } catch (err) {
+      throw stop(`${GATES_REL}: malformed JSON (${err.message}) — fix it by hand; the seeder never writes over a declaration it cannot parse`);
+    }
+  })();
+  const gates = (() => {
+    try {
+      return validateDeclaration(parsed);
+    } catch (err) {
+      throw stop(`${err.message} — fix it by hand; the seeder never writes over an invalid declaration`);
+    }
+  })();
+  return { outcome: 'loaded', readme: typeof parsed._README === 'string' ? parsed._README : undefined, gates };
+};
+
+const templateReadme = (deps = {}) => {
+  const read = deps.readTemplate ?? readFileSync;
+  try {
+    const parsed = JSON.parse(String(read(TEMPLATE_PATH, 'utf8')));
+    if (typeof parsed._README !== 'string') throw new Error('template has no _README');
+    return parsed._README;
+  } catch (err) {
+    throw stop(`the bundled gates.json template is unreadable (${err.message}) — the kit install is incomplete`);
+  }
+};
+
+const readStampValue = (cwd, deps = {}) => {
+  const read = deps.readFile ?? readFileSync;
+  try {
+    const v = String(read(join(cwd, STAMP_REL), 'utf8')).trim();
+    return v.length ? v : null;
+  } catch {
+    return null;
+  }
+};
+
+// ── apply (append exactly the consented entries) ───────────────────────────────────────
+export const applySeed = ({ cwd, onlyIds = [] }, deps = {}) => {
+  assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
+  const stampValue = readStampValue(cwd, deps);
+  if (stampValue !== EXPECTED_WORKFLOW_VERSION) {
+    throw stop(
+      `--apply is deployment-gated: ${STAMP_REL} is ${stampValue ?? 'absent'} but this kit expects ` +
+        `${EXPECTED_WORKFLOW_VERSION} (the preview works on any deployment; run upgrade first)`,
+    );
+  }
+  const offer = buildOffer(cwd, deps);
+  assertOnlyIdsOffered(offer, onlyIds); // BEFORE the empty-offer return — a typo is never masked
+  if (!offer.entries.length) return { outcome: 'nothing' };
+  const selected = onlyIds.length ? offer.entries.filter((e) => onlyIds.includes(e.id)) : offer.entries;
+
+  const existing = loadExistingDeclaration(cwd, deps);
+  const existingGates = existing.outcome === 'loaded' ? existing.gates : [];
+  const existingIds = new Set(existingGates.map((g) => g.id));
+  const collisions = selected.filter((e) => existingIds.has(e.id)).map((e) => e.id);
+  if (collisions.length) {
+    throw stop(
+      `id collision — already declared in ${GATES_REL}: ${collisions.join(', ')} (append-only: the ` +
+        `seeder never modifies or removes an existing entry; pick the others with --only, or edit by hand)`,
+    );
+  }
+
+  const merged = {
+    _README: existing.outcome === 'loaded' && existing.readme !== undefined ? existing.readme : templateReadme(deps),
+    gates: [...existingGates, ...selected],
+  };
+  validateDeclaration(merged); // every written declaration passes the runner's validator, always
+  const body = `${JSON.stringify(merged, null, 2)}\n`;
+  const { writtenPath } = writeDocsAiFileAtomic(cwd, GATES_REL, body, deps, { stop, noun: 'a gate declaration' });
+  return { outcome: 'written', writtenPath, appended: selected.map((e) => e.id) };
+};
+
+// ── CLI ────────────────────────────────────────────────────────────────────────────────
+export const parseArgs = (argv) => {
+  const parsed = argv.reduce(
+    (acc, a, i) => {
+      if (acc.skip) return { ...acc, skip: false };
+      if (a === '--help' || a === '-h') return { ...acc, help: true };
+      // A consent-gated writer never lets a later flag silently decide whether it mutates:
+      // mixed --dry-run/--apply is a usage error, whichever order they arrive in.
+      if (a === '--dry-run') {
+        if (acc.apply === true) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: false, dryRunExplicit: true };
+      }
+      if (a === '--apply') {
+        if (acc.dryRunExplicit) throw usageFail('--dry-run and --apply are mutually exclusive — pick one');
+        return { ...acc, apply: true };
+      }
+      if (a === '--cwd') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) throw usageFail('--cwd needs a value: --cwd <dir>');
+        return { ...acc, cwd: value, skip: true };
+      }
+      if (a === '--only') {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-')) throw usageFail('--only needs a gate id');
+        return { ...acc, only: [...acc.only, value], skip: true };
+      }
+      throw usageFail(`unknown argument: ${a}`);
+    },
+    { help: false, apply: false, dryRunExplicit: false, cwd: undefined, only: [], skip: false },
+  );
+  return parsed;
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const error = deps.error ?? console.error;
+  try {
+    const args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    const cwd = resolve(args.cwd ?? process.cwd());
+    assertDocsAiDeployment(cwd, deps, { stop, noun: 'a gate declaration', rel: GATES_REL });
+    if (!args.apply) {
+      const offer = buildOffer(cwd, deps);
+      assertOnlyIdsOffered(offer, args.only); // a dry-run --only typo is loud too
+      const filtered = args.only.length ? { ...offer, entries: offer.entries.filter((e) => args.only.includes(e.id)) } : offer;
+      log(formatPreview(filtered, applyInvocationFor(cwd, args.only), { explicitOnly: args.only.length > 0 }));
+      return EXIT_OK;
+    }
+    const result = applySeed({ cwd, onlyIds: args.only }, deps);
+    if (result.outcome === 'nothing') {
+      log('[agent-workflow-kit] nothing to offer — no seedable terminating verification scripts were found; wrote nothing.');
+      return EXIT_OK;
+    }
+    log(`[agent-workflow-kit] appended ${result.appended.length} consented gate(s) to ${GATES_REL}: ${result.appended.join(', ')}`);
+    log(`[agent-workflow-kit] ${TRUST_CHAIN_DISCLOSURE}`);
+    return EXIT_OK;
+  } catch (err) {
+    error(err?.message ?? String(err));
+    return err?.exitCode ?? EXIT_PRECONDITION;
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) process.exit(main(process.argv.slice(2)));

package/tools/velocity-profile.mjs

@@ -364,8 +364,12 @@ const isScriptMap = (scripts) => Boolean(scripts) && typeof scripts === 'object'
 const isMutatingScriptName = (name) =>
   MUTATING_SCRIPT_NAME_PATTERN.test(name) || MUTATING_SCRIPT_HOOK_PATTERN.test(name);
 
+// `scriptName` is ADDITIVE (AD-042): the seed-gates offer layer maps a candidate to a
+// package-manager-aware `{ id, title, cmd }` and needs the raw script name for that derivation;
+// `command` stays the advisory's own npm-run spelling (this fn is otherwise unchanged).
 const makeGateCandidate = (name) => ({
   command: `${NPM_RUN_COMMAND} ${name}`,
+  scriptName: name,
   addByHand: ADD_BY_HAND,
   ...(isMutatingScriptName(name) ? { warn: DO_NOT_ADD_WARNING } : {}),
 });

package/tools/view-model.mjs

@@ -65,6 +65,12 @@ const velocityVm = (v) => {
   return { defaultMode: v.defaultMode ?? null, allow: { project: v.allowEntries?.project ?? 0, local: v.allowEntries?.local ?? 0 } };
 };
 
+const agentsVm = (a) => {
+  if (!a) return null;
+  if (a.error) return { error: a.error };
+  return { bundled: a.bundled ?? 0, placed: a.placed ?? 0 };
+};
+
 const hookVm = (h) => {
   if (!h) return null;
   if (h.error) return { error: h.error };
@@ -72,6 +78,12 @@ const hookVm = (h) => {
     wired: Boolean(h.wired),
     filePlaced: Boolean(h.filePlaced),
     declarationPresent: Boolean(h.declarationPresent),
+    // 0 = absent/empty declaration; null = unreadable/malformed OR an envelope predating the
+    // field — unknown reads as unknown, never as a count (the welcome-mat hook rung keys on > 0).
+    declaredGates: h.declaredGates ?? null,
+    // The preserved validation reason for a null count (null when absent) — rendered beside the
+    // unknown marker so a malformed declaration is never a silent bare "?".
+    declarationError: h.declarationError ?? null,
   };
 };
 
@@ -81,6 +93,7 @@ const settingsVm = (s) =>
         recipes: recipesVm(s.recipes),
         attribution: attributionVm(s.attribution),
         velocity: velocityVm(s.velocity),
+        agents: agentsVm(s.agents),
         hook: hookVm(s.hook),
       }
     : null;