@sabaiway/agent-workflow-kit 14.32.0 → 14.34.0

package/references/modes/velocity.md

@@ -8,7 +8,7 @@
 
 Requires: ${CLAUDE_SKILL_DIR}/references/shared/command-shapes.md
 
-The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes only `.claude/settings.json`**, on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below) — its closure is **shipped, opt-in: `${CLAUDE_SKILL_DIR}/references/modes/hook.md`**.
+The opt-in onboarding **velocity profile** — it seeds a fixed, audited **read-only** Claude Code allowlist into `.claude/settings.json` so an agent stops idling on approval prompts for routine read-only commands while the maintainer is away. It is the family's **first programmatic `.claude/settings.json` writer** (attribution stayed an agent-driven prose merge). **In-agent, opt-in, writes `.claude/settings.json`** — its `--worktrees` mode alone writes `.claude/settings.local.json` plus the created parent — on one hard rule: **it never allowlists `commit`/`push`/`publish`** — so a direct commit/push/publish still ASKs; the only caveat is the trust-posture residual (below) — its closure is **shipped, opt-in: `${CLAUDE_SKILL_DIR}/references/modes/hook.md`**.
 
 **Version-status routing (like the other writer modes):** read `docs/ai/.workflow-version` first — not-deployed → bootstrap; stamp < `4.0.0` → `upgrade`; stamp > head / unparseable → STOP. The tool enforces this in code too (`--apply` STOPs unless the stamp is the lineage head).
 
@@ -17,8 +17,8 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 1. **`--dry-run` first, always** (the default — changes nothing). It prints: the fixed read-only core it would add; the apply ask rule it would add (step 3); a **read-only advisory** that lists your `package.json` `scripts` as **unaudited candidates you may add BY HAND** (inspect each first) to `.claude/settings.json` / `settings.local.json` — the tool **never** writes them and flags obviously-mutating names as "do not add"; any **pre-existing non-read-only `Bash(...)` entries** to consider removing by hand; and the honest residual notice (below). It STOPs (zero writes) on a symlinked `.claude` / non-regular `settings.json`, malformed settings JSON, or an unsafe `permissions.defaultMode` — `bypassPermissions` or anything outside `default`/`acceptEdits`/`plan`, present in **either** `settings.json` or `settings.local.json`.
 2. **Ask the opt-ins** via **`AskUserQuestion` where supported** — two separate choices, the safe option FIRST in each. First the **`--kit-tools` tier** (separate from `acceptEdits`; **"core only" remains the default answer** — seed the tier only on an explicit yes, then add `--kit-tools` to the `--apply` re-run). Then the `acceptEdits` opt-in:
    - **"Keep per-edit approval prompts (recommended)"** — seed only the read-only allowlist; file edits still prompt.
-   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — and the residual guard for the seeded core ships as the opt-in PreToolUse hook (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`; probe-proven on the `--output` family — current engine builds already intercept redirection/substitution upstream). The approval **floor** (never auto-approved, with or without the tier): every writer `--apply`/`--write`/`--yes` still prompts; clobber-protection STOPs still stop; the three release asks (commit/push/publish) stay maintainer-owned. Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes only `.claude/settings.json`.
-3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json`. Every apply — flagless, `--kit-tools`, `--bridge-tier` — also appends one ask rule, `Bash(node *apply-danger-check.mjs*--apply*)`, to `permissions.ask` once, beside any ask entries already there: the rule exists so all work can stay in auto mode: without it auto mode refuses a harness apply (the `apply:` line of each harness item the advisor renders) and the user must leave auto mode for it; with it the harness shows its usual dialog. The rule allows nothing, and `--autonomy` leaves it in place. When you name the rule to the user, lead with this purpose.
+   - **"Auto-accept file edits (`defaultMode: acceptEdits`)"** — present the honest FULL posture: it auto-applies Edit/Write AND auto-runs `mkdir`/`touch`/`mv`/`cp` in the working dir, is paired with the read-only allowlist, and — stated plainly — a settings-level allow rule is a **trust posture, not a sandbox**: a read-only entry can still write a file via output redirection, and (Claude Code's allow rules do not inspect command substitution) could in principle run another command via `cmd $(…)`. velocity **never adds `commit`/`push`/`publish` as allow rules** — so a direct `git push` still ASKs — and the residual guard for the seeded core ships as the opt-in PreToolUse hook (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`; probe-proven on the `--output` family — current engine builds already intercept redirection/substitution upstream). The approval **floor** (never auto-approved, with or without the tier): every writer `--apply`/`--write`/`--yes` still prompts; clobber-protection STOPs still stop; the three release asks (commit/push/publish) stay maintainer-owned. Note also that a `defaultMode` in `settings.local.json` would override this project-level write (local > project), since velocity writes `.claude/settings.json` here — its `--worktrees` mode alone writes `.claude/settings.local.json`, and only its one grant entry.
+3. **Only on an explicit yes**, re-run with `--apply` (add `--accept-edits` only if they chose the second option). It merges-don't-clobber (preserves `includeCoAuthoredBy`, every key, and existing allow entries) and writes **only** `.claude/settings.json` (the `--worktrees` mode below is the one exception). Every apply — flagless, `--kit-tools`, `--bridge-tier` — also appends one ask rule, `Bash(node *apply-danger-check.mjs*--apply*)`, to `permissions.ask` once, beside any ask entries already there: the rule exists so all work can stay in auto mode: without it auto mode refuses a harness apply (the `apply:` line of each harness item the advisor renders) and the user must leave auto mode for it; with it the harness shows its usual dialog. The rule allows nothing, and `--autonomy` leaves it in place. When you name the rule to the user, lead with this purpose.
 4. **Surface delegation-readiness, read-only.** If they want a step run Delegated, set it with `/agent-workflow-kit set-recipe --set plan-execution.execute=delegated` (`${CLAUDE_SKILL_DIR}/references/modes/set-recipe.md`) or by hand-editing `docs/ai/orchestration.json`; **velocity itself never writes the orchestration config.**
 
 **The `--kit-tools` tier (opt-in).** On top of the read-only core, `--kit-tools` seeds an audited kit-tool tier — every path **resolved absolute from the running skill at seed time**, so the posture is **fail-safe**: a moved or reinstalled skill leaves a stale rule that simply **prompts again** (re-run velocity to reseed; nothing widens silently). A seeded entry equals its covered dispatch line below with `${CLAUDE_SKILL_DIR}` replaced by the resolved skill dir and `${PROJECT_ROOT}` by this project's resolved root, **UNQUOTED** — a quoted path is a different byte string and will still prompt (a dead rule, not a hole). The covered dispatch lines (this list IS the documented-invocation source):
@@ -43,7 +43,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs [--dry-run | --apply] [
 
 Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with TWO deliberate exceptions, `repo-search.mjs` and `path-inventory.mjs`**, whose prefixes are in the hook's scanned list because they take caller-supplied argument bytes: a redirection or substitution on THEIR invocation raises the ask, whose reason names that tool's out-of-band lane (`--pattern-file` / `--paths-file`) — context for the HUMAN deciding, not a message to the caller. Neither is in the seeded core, so neither inherits the read-lane allow. Every other tier entry: the opt-in hook's residual ask-net guards only the seeded read-only CORE prefixes, so the tier rides the same settings-level residual posture as the core (redirection / command substitution are not inspectable at the settings layer; see the residual notice). A skill or project path that cannot survive UNQUOTED in a byte-exact rule (spaces, metacharacters, non-POSIX) **STOPs the tier up front with a clear error** — nothing is seeded. Anything you want covered beyond the tier — such paths, this repo's own relative-path spellings, other tools — stays a **BY-HAND add** to your settings, with the path your project actually reaches the kit by. Pre-existing `node …` allow entries that do NOT match the seeded tier byte-forms stay flagged by the advisory for hand review.
 
-**Invariants:** creates `.claude/` if absent and writes **only** `.claude/settings.json` (no other file); **never** allowlists commit/push/publish; **never** writes `settings.local.json`; never commits; opt-in `acceptEdits`, never silent.
+**Invariants:** creates `.claude/` if absent and writes `.claude/settings.json`, and with `--worktrees` alone `.claude/settings.local.json` plus the created parent (no other file); **never** allowlists commit/push/publish; never commits; opt-in `acceptEdits`, never silent.
 
 **Every settings-derived RUNTIME claim on this mode's surfaces is host-conditional.** Whether a host applies the `sandbox.*` settings keys is **not knowable from here** — a settings-native host honors them; an IDE/session-imposed sandbox was observed ignoring `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` in BOTH scopes. So every statement about what a settings key DOES at run time is stated **`where the host honors the settings sandbox keys`**, never promised — the bridge tier's exclusion routing; the autonomy render's `allowedDomains` / `allowWrite` / `allowUnsandboxedCommands` / `excludedCommands` degrade lines over FOREIGN keys; and equally the render's claims about the keys it writes ITSELF (the `sandbox:` line, the `fs_outside_repo` confinement note, the network prompt-on-egress and credentials-coverage degrades), which is where a clean deployment reads a promise. The qualifier rides every such line, and one notice naming the unknown closes **every** `--autonomy` render, clean settings included. A malformed `allowWrite` (not an array, or an entry that is not a non-empty string) is reported as unreadable rather than assumed empty — as UNVERIFIABLE, never as a weakening: nothing may be claimed about what a value the tool cannot read would widen.
 
@@ -61,7 +61,9 @@ Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with
 
 **Read-side invocation shape (why routine reads prompt, and the fix).** The same rule binds EVERY prefix allow entry, seeded read-only core included: a **compound chain** (`grep … && …`, `;`/`|`-joined reads), an **env-var prefix** (`FOO=bar grep …`), a **`$`/`${…}`/`$(…)` expansion**, or an **inline `node -e '…'`** never matches a prefix rule — so read *compounds* keep prompting at the settings layer even when each command is individually seeded. The mechanism that clears them is the opt-in **read-lane** in the PreToolUse hook (`${CLAUDE_SKILL_DIR}/references/modes/hook.md`): it auto-approves a compound whose every separator-split segment is a plain seeded read-only core command with **zero shell metaprogramming**. A scripted probe stays allow-listable by being a **WRITTEN scratch file run as `node <file>`** (a byte-exact declared gate, or a kit-tool tier entry) — **never** `node -e '…'`, which is unclassifiable and always prompts.
 
-**Exit codes:** `0` done / dry-run; `1` a precondition STOP (stamp not current, unsafe mode, malformed settings, symlinked `.claude` / non-regular target); `2` bad arguments.
+**The `--worktrees` grant (own opt-in, its own mode).** Run `node ${CLAUDE_SKILL_DIR}/tools/velocity-profile.mjs --worktrees [--apply] [--cwd <dir>]`. It writes ONE `sandbox.filesystem.allowWrite` entry, the worktrees parent itself (`docs/ai/worktrees.json` `parentDir`, else the repository's own parent; home-relative under the home), into this copy's `.claude/settings.local.json` alone, and creates the parent when it is missing. It never writes `.claude/settings.json`, seeds no core and no ask rule, and cannot be combined with `--autonomy`, `--kit-tools`, `--bridge-tier` or `--accept-edits`. A parent that is the home or holds it is refused (`VELOCITY_WORKTREES_HOME`), nothing written. **Where the host honors the settings sandbox keys**, every sandboxed command of this copy, and of every worktree provisioned from it, can then write the whole parent dir, sibling repositories under it included, for every later session. Narrow it BEFORE the first apply: point `parentDir` at a dedicated dir — no apply removes an entry, so an earlier one stays until you delete it. The advisor's `worktrees-dir` item runs it through the danger check on the chat yes.
+
+**Exit codes:** `0` done / dry-run; `1` a precondition STOP (stamp not current, unsafe mode, malformed settings, symlinked `.claude` / non-regular target, a worktrees parent that is the home or holds it); `2` bad arguments.
 
 ---
 

package/references/modes/worktrees.md

@@ -213,16 +213,17 @@ stated skip), and the ancestor chain is verified even when the leaf is ABSENT (a
 `docs/` or `docs/ai` never reads as plain absence). `--dir` overrides per invocation.
 
 **Host-specific consent (zero-prompt only where the host honors it):** every sibling-dir mutation
-runs a REAL create+delete writability probe first. An unwritable parent prints both the
-settings-native line (`sandbox.filesystem.allowWrite` in `.claude/settings.json`) and the full
-terminal command. On a settings-native host that honors the key, adding the parent can make later
-provision/cleanup promptless. On a harness-managed host that ignores project settings, grant the
-narrow parent through the host/session controls; if that is unavailable, use the printed terminal
-command for each operation. The `recommendations` mode surfaces this lane and converges it two ways:
+runs a REAL create+delete writability probe first. An unwritable parent prints the `worktrees-dir`
+check line and the full terminal command. The agent runs that check line and, on the chat yes on
+its result, its apply line by the consent route: one `sandbox.filesystem.allowWrite` entry naming
+the parent, written to this copy's `.claude/settings.local.json` only; where the host honors the
+key, later provision/cleanup then run promptless. When the check refuses, prints nothing to
+change, or grants a dir that does not hold the command's target, use the printed terminal command
+for each operation. The `recommendations` mode surfaces this lane and converges it two ways:
 a declared `sandbox.filesystem.allowWrite` entry covering the probed parent (either settings
-scope), or — on a host that ignores that key — the neutral dir-bound acknowledgement its
-consent-gated apply one-liner records into `docs/ai/acks.json` (`worktreesDirAck`; the dry-run
-preview prints the exact `--apply`). Neither is proof of write
+scope), or — on a host that ignores that key — the neutral dir-bound acknowledgement
+`worktreesDirAck` in `docs/ai/acks.json`, recorded by the `ack-write` line the item's `recipe:`
+line carries, the fallback instead of the grant. Neither is proof of write
 capability: the create+delete probe above stays the runtime truth, and the ack binds to the
 resolved probe dir, so the item re-fires only when that resolved dir changes.
 

package/references/shared/composition-handoff.md

@@ -2,14 +2,14 @@
 
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
-  answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
+  answers** (visibility / language / attribution — memory is told to skip its step-4 settings write; the `attribution` item of step 11 sets it) to `agent-workflow-memory`, which writes
   `docs/ai/` + `AGENTS.md` (carrying the **three empty pointer pairs** — `workflow:methodology`,
   `workflow:orchestration` and `workflow:autonomy`) + **`.memory-version`**. The kit then **reconciles
   the bounded pointers** (below) and writes the kit-fallback **`.workflow-version`**. → **both stamps** present. In **hidden** mode the kit is the **single
   hide authority**: after the hand-off it runs `tools/hide-footprint.mjs` (bootstrap step 9 — `${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`), which **absorbs
   memory's project-local footprint lines** into the one canonical `.git/info/exclude` block and adds
-  the external footprint — so there is **no machine-global write** at any step (a stale memory's
-  residual global block is cleaned via the upgrade reconcile, below).
+  the external footprint — so the hide makes **no machine-global write** (a stale memory's
+  residual global block is the advisor's footprint-global item).
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`) from its own
   bundled assets — whose entry-point template now ships **three empty pointer pairs** (`workflow:methodology`
   + `workflow:orchestration` + `workflow:autonomy`) the kit reconciles + fills — and writes **`.workflow-version`** only.

package/references/shared/deploy-tail.md

@@ -3,9 +3,9 @@
 The non-obvious traps — scan these before bootstrapping or upgrading. Each is also enforced inline in the bootstrap/upgrade procedures (`${CLAUDE_SKILL_DIR}/references/modes/bootstrap.md`, `${CLAUDE_SKILL_DIR}/references/modes/upgrade.md`); this is the consolidated high-signal list.
 
 - **Source vs target directory.** Templates and scripts are read from the skill's own dir (`${CLAUDE_SKILL_DIR}/` in Claude Code, the `SKILL.md` folder elsewhere). The **working directory is the target project** — never write kernel files back into the skill.
-- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code you **must** also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent). Other tools: disable their equivalent co-author/footer setting.
+- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code the advisor's `attribution` item sets the harness setting in the project's `.claude/settings.json`, on the user's yes after its check. Other tools: disable their equivalent co-author/footer setting.
 - **Hidden mode must never touch `package.json`.** Editing it is a *tracked* change and leaks the whole system. Hidden mode wires nothing into `package.json`; the pre-commit hook (untracked in `.git/hooks/`) calls `node scripts/<x>.mjs` directly. After hiding, **verify `git status` shows the artifacts as ignored**.
-- **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
+- **Hidden mode is project-local, and the hide tool owns the known footprint.** `tools/hide-footprint.mjs` writes **one managed block** in the **project-local `.git/info/exclude`** — never the machine-global `core.excludesFile` (which would silently affect every repo on the host; **AD-014** amends **AD-006**; only its `--remove-global` mode, the `footprint-global` item, edits that file). It hides the kit's own artifacts **and** the known external AI/agent footprint (the `KNOWN_FOOTPRINT` table in [contracts](${CLAUDE_SKILL_DIR}/references/contracts.md#visibility-contract)). A **tracked** file is **never silently un-tracked** — the tool prints the `git rm --cached` it will not run. Never leak its internal marker / asks terms to the user; translate every outcome to plain language.
 - **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
 - **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, **stop and ask** the user to merge vs replace — don't clobber. A non-marker hook stays; moving it aside is the user's step.
 - **Unrecognized invocations are read-only.** Only a **known** subcommand reaches its mode; the **bare** invocation bootstraps (and an existing `docs/ai/` makes it ask upgrade-vs-bootstrap first, never overwrite); **any other / ambiguous** token routes to `help` (read-only). A garbage invocation never writes. The mapping is pinned by `tools/commands.mjs` `routeInvocation` (unit-tested) — don't hand-route around it.

package/references/templates/vehicles.json

@@ -1,5 +1,5 @@
 {
-  "_README": "The executor vehicle's model, effort and fallback as a project setting, read by the kit's vehicle-settings readers into one posture, which the placed executor's body follows: the agents writer and the upgrade run derive it from model and effort, and fallback names the model of the one retry; seeded once and never clobbered, hand-edited as three bare tokens with fallback differing from model.",
+  "_README": "The executor vehicle's model, effort and fallback as a project setting, read by the kit's vehicle-settings readers into one posture, which the placed executor's body follows: the agents writer derives it from model and effort, the upgrade reports a differing body as pending, and fallback names the model of the one retry; seeded once and never clobbered, hand-edited as three bare tokens with fallback differing from model.",
   "executor": {
     "model": "opus",
     "effort": "high",

package/tools/apply-danger-check.mjs

@@ -12,7 +12,8 @@ import {
   writeAutonomyProfile, writeVelocityProfile,
 } from './velocity-profile.mjs';
 import { KIT_GROUNDING_TOOL, bundledSandboxRecipe, usedBridges } from './bridge-sandbox-recipe.mjs';
-import { mergeAllowWrite, stateDirsOf } from './bridge-state-dirs.mjs';
+import { homeRelative, mergeAllowWrite, stateDirsOf } from './bridge-state-dirs.mjs';
+import { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { HOOK_FILE_REL, HOOKS_DIR, buildHookSettingsEntry, mergeHookEntry, writeGateHook } from './gate-hook.mjs';
 import { STATE_BLOCK_HOOK_FILE_REL, buildStopHookEntry, mergeStopEntry, writeStateBlockHook } from './state-block-hook.mjs';
@@ -24,6 +25,8 @@ import { SKILL_FILES, claudeDirOf, skillTargets } from './jev-facts.mjs';
 import { findOnPath } from './detect-backends.mjs';
 import { consoleArgv } from './write-lanes.mjs';
 import { BUNDLED_SCRIPT_NAMES, INSTALLER_REL, SCRIPTS_REL, formatPlan, planGitHooks } from './git-hooks.mjs';
+import { ATTRIBUTION_HIDDEN, ATTRIBUTION_KEY, writeAttribution } from './attribution.mjs';
+import { globalRemovalOf, planGlobalRemoval } from './hide-footprint.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { dirCovers as covers } from './declared-paths.mjs';
 
@@ -34,10 +37,13 @@ const RESEED_VARIANTS = ['gate-hook.marker-stale', 'read-lane.stale'];
 const HOOK_VARIANTS = ['gate-hook', 'read-lane.missing', ...RESEED_VARIANTS];
 const STOP = 'state-block';
 const MCP_VARIANTS = ['mcp-channel', 'mcp-channel.differing'];
-const AGENT_VARIANTS = ['agents', 'executor-vehicle'];
+const AGENT_VARIANTS = ['agents', 'executor-vehicle', 'executor-vehicle.differing'];
 const GIT_VARIANTS = ['enforcement', 'commit-guard'];
+const WORKTREES = 'worktrees-dir';
+const ATTRIBUTION = 'attribution';
+const FOOTPRINT = 'footprint-global';
 const VARIANTS = [...VELOCITY_VARIANTS, 'autonomy-render', ...HOOK_VARIANTS, STOP, ...MCP_VARIANTS, ...AGENT_VARIANTS,
-  ...SKILL_VARIANTS, ...GIT_VARIANTS];
+  ...SKILL_VARIANTS, ...GIT_VARIANTS, WORKTREES, ATTRIBUTION, FOOTPRINT];
 const HOOK_KEYS = ['hooks.PreToolUse', 'hooks.Stop'];
 const CREDENTIALS = 'sandbox.credentials.envVars';
 const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -67,10 +73,12 @@ export const KEY_TABLE = Object.freeze({
   [ENABLED_KEY]: 4,
   [SERVERS_KEY]: 4,
   [CREDENTIALS]: 5,
+  [ATTRIBUTION_KEY]: 5,
 });
-const SCALARS = ['permissions.defaultMode', 'sandbox.enabled', 'sandbox.autoAllowBashIfSandboxed'];
+const SCALARS = ['permissions.defaultMode', 'sandbox.enabled', 'sandbox.autoAllowBashIfSandboxed', ATTRIBUTION_KEY];
 const valid = (key, value, element = false) => {
   if (key.startsWith(`${SERVERS_KEY}.`) || key === SERVERS_KEY) return object(value);
+  if (key === ATTRIBUTION_KEY) return object(value) || typeof value === 'boolean';
   if (key === 'permissions.defaultMode') return typeof value === 'string';
   if (SCALARS.includes(key)) return typeof value === 'boolean';
   if (!element) return Array.isArray(value) && value.every((entry) => valid(key, entry, true));
@@ -148,6 +156,7 @@ export const judgeChange = ({ variant, files, scope }) => {
   }
   return { entries, refused };
 };
+const footprintPlan = (facts, deps) => (deps.planGlobalRemoval ?? planGlobalRemoval)({ env: facts.env, home: facts.home }, facts.root, { home: facts.home });
 const writerFacts = (facts, deps) => ({
   ...deps, ...facts,
   detect: deps.detect ?? facts.detect,
@@ -181,7 +190,12 @@ export const scopeOf = (variant, facts, deps = {}) => {
     set('permissions.ask', RENDER_OWNED_REDLINE_RULES);
     set('permissions.deny', RENDER_OWNED_REDLINE_RULES);
     allowed[CREDENTIALS] = (value) => value.mode === 'deny';
-  } else if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
+  } else if (variant === ATTRIBUTION) set(ATTRIBUTION_KEY, [ATTRIBUTION_HIDDEN]);
+  const grantDir = variant === WORKTREES ? worktreesGrantDir(facts.root, facts) : null;
+  if (grantDir !== null && !worktreesGrantHoldsHome(grantDir, facts.home, facts)) {
+    set('sandbox.filesystem.allowWrite', [homeRelative(grantDir, facts.home)]);
+  }
+  if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
   else if (variant === STOP) set('hooks.Stop', [buildStopHookEntry()]);
   else if (MCP_VARIANTS.includes(variant)) {
     set(`${SERVERS_KEY}.${SERVER_NAME}`, [buildServerEntry(join(facts.toolsDir, 'mcp-server.mjs'))]);
@@ -192,9 +206,13 @@ export const scopeOf = (variant, facts, deps = {}) => {
     claudeDir: facts.claudeDir ?? claudeDirOf(facts.env, facts.home, facts.platform).dir }) : [];
   const filePaths = HOOK_VARIANTS.includes(variant) ? [join(facts.root, HOOK_FILE_REL)]
     : variant === STOP ? [join(facts.root, STATE_BLOCK_HOOK_FILE_REL)] : [];
-  const directories = SKILL_VARIANTS.includes(variant) ? [] : [join(facts.root, CLAUDE_DIR)];
+  const directories = SKILL_VARIANTS.includes(variant) || variant === FOOTPRINT ? [] : [join(facts.root, CLAUDE_DIR)];
+  const globalFile = variant === FOOTPRINT ? footprintPlan(facts, deps)?.source : undefined;
+  if (globalFile) filePaths.push(globalFile);
   if (HOOK_VARIANTS.includes(variant) || variant === STOP) directories.push(join(facts.root, HOOKS_DIR));
   if (AGENT_VARIANTS.includes(variant)) directories.push(join(facts.root, AGENTS_DIR));
+  const existingAncestor = grantDir === null ? null : nearestExistingDir(grantDir, facts);
+  for (let at = grantDir; at !== existingAncestor; at = dirname(at)) directories.push(at);
   for (const target of targets) {
     for (let at = target.root; at !== target.base && covers(target.base, at); at = dirname(at)) directories.push(at);
     filePaths.push(target.path);
@@ -209,10 +227,11 @@ export const scopeOf = (variant, facts, deps = {}) => {
   return {
     admitsRun: (argv) => runs !== null && equal(argv, runs),
     admits: ({ path, key, change, value }) => {
-      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL : path === SETTINGS_FILE;
-      const gains = variant === 'bridge-tier' || HOOK_KEYS.includes(key) || key === ENABLED_KEY || key === CREDENTIALS
+      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL
+        : path === (variant === WORKTREES ? SETTINGS_LOCAL_FILE : SETTINGS_FILE);
+      const gains = variant === 'bridge-tier' || variant === WORKTREES || HOOK_KEYS.includes(key) || key === ENABLED_KEY || key === CREDENTIALS
         || (VELOCITY_VARIANTS.includes(variant) && key === 'permissions.ask');
-      return correctFile && (!gains || change === 'added') && Boolean(allowed[key]?.(value));
+      return correctFile && (!gains || change === 'added') && !(key === ATTRIBUTION_KEY && change === 'removed') && Boolean(allowed[key]?.(value));
     },
     admitsPath: (path, directory = false) => directory ? directories.includes(path)
       : filePaths.includes(path) || (AGENT_VARIANTS.includes(variant) && covers(join(facts.root, AGENTS_DIR), path)),
@@ -220,10 +239,11 @@ export const scopeOf = (variant, facts, deps = {}) => {
 };
 
 const jsonAt = (path) => existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+const regularBytes = (path) => lstatSync(path, { throwIfNoEntry: false })?.isFile() ? readFileSync(path) : undefined;
 const halted = (lines) => Object.assign(new Error(lines.join('\n')), { code: 'CHECK_HALTED', lines });
 const maskedFiles = (variant, facts) => {
   const paths = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render' || HOOK_VARIANTS.includes(variant)
-    || variant === STOP ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
+    || variant === STOP || variant === WORKTREES || variant === ATTRIBUTION ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
   return paths.flatMap((path) => lstatSync(join(facts.root, path), { throwIfNoEntry: false })?.isCharacterDevice()
     ? [`masked: ${path}`] : []);
 };
@@ -231,6 +251,7 @@ export const plannedChange = (variant, facts, deps = {}) => {
   const files = [];
   const writes = [];
   const temporaries = [];
+  const created = [];
   let runs = null;
   const writerDeps = writerFacts(facts, deps);
   const addFile = (path, before, after) => {
@@ -264,13 +285,12 @@ export const plannedChange = (variant, facts, deps = {}) => {
       if (plan.wirePlanned) addFile(SETTINGS_FILE, plan.projectSettings.data, mergeHookEntry(plan.projectSettings.data));
       const path = join(facts.root, HOOK_FILE_REL);
       if (plan.placePlanned) writes.push({ path, bytes: plan.bundleContent });
-      if (plan.reseedPlanned) writes.push({ path, bytes: plan.bundleContent, replaces: readFileSync(path) });
+      if (plan.reseedPlanned) writes.push({ path, bytes: plan.bundleContent });
     } else if (variant === STOP) {
       const plan = writeStateBlockHook({ cwd: facts.root, dryRun: true }, writerDeps);
       if (plan.mergePlanned) addFile(SETTINGS_FILE, plan.projectSettings.data, mergeStopEntry(plan.projectSettings.data));
       const path = join(facts.root, STATE_BLOCK_HOOK_FILE_REL);
-      if (plan.placement === 'create') writes.push({ path, bytes: plan.bundleContent });
-      if (plan.placement === 'replace') writes.push({ path, bytes: plan.bundleContent, replaces: readFileSync(path) });
+      if (['create', 'replace'].includes(plan.placement)) writes.push({ path, bytes: plan.bundleContent });
     } else if (MCP_VARIANTS.includes(variant)) {
       const result = writeMcp({ cwd: facts.root, dryRun: true, replace: variant === 'mcp-channel.differing' }, writerDeps);
       const { plan, registration } = result;
@@ -295,6 +315,22 @@ export const plannedChange = (variant, facts, deps = {}) => {
       const plan = (deps.planGitHooks ?? planGitHooks)({ root: facts.root, variant, toolsDir: facts.toolsDir });
       for (const copy of plan.copies.filter(({ action }) => action === 'created')) writes.push({ path: copy.path, bytes: copy.bytes });
       runs = { argv: plan.runs.shown, line: formatPlan(plan).at(-1) };
+    } else if (variant === WORKTREES) {
+      const plan = writeVelocityProfile({ cwd: facts.root, dryRun: true, worktrees: true }, writerDeps);
+      const before = plan.localSettings.data ?? null;
+      addFile(SETTINGS_LOCAL_FILE, before, mergeAllowWrite(before ?? {}, plan.worktreesDirToAdd));
+      created.push(...plan.worktreesDirsToCreate);
+    } else if (variant === ATTRIBUTION) {
+      const plan = writeAttribution({ cwd: facts.root, dryRun: true }, writerDeps);
+      if (plan.planned) addFile(SETTINGS_FILE, plan.before, plan.after);
+    } else if (variant === FOOTPRINT) {
+      const plan = footprintPlan(facts, deps);
+      if (plan !== null) {
+        const bytes = readFileSync(plan.source, 'latin1');
+        const core = globalRemovalOf(bytes);
+        const matches = plan.before === bytes && core !== null && equal(plan.removedLines, core.removedLines) && plan.after === core.after;
+        writes.push({ path: plan.source, bytes: Buffer.from(plan.after, 'latin1'), replaces: Buffer.from(plan.before, 'latin1'), removes: plan.removedLines, matches });
+      }
     } else throw new Error(`unsupported variant: ${variant}`);
   } catch (error) {
     throw error.code === 'CHECK_HALTED' ? error : halted([error.message]);
@@ -304,6 +340,7 @@ export const plannedChange = (variant, facts, deps = {}) => {
   for (const path of [...changedFiles.map(({ path }) => join(facts.root, path)), ...writes.map(({ path }) => path)]) {
     for (let parent = dirname(path); !existsSync(parent); parent = dirname(parent)) directories.add(parent);
   }
+  for (const path of created) directories.add(path);
   return { files, writes, temporaries, directories: [...directories], runs };
 };
 
@@ -328,8 +365,13 @@ export const checkApply = (variant, facts, deps = {}) => {
       reason: `beyond the declared scope of ${variant}` });
   };
   for (const write of plan.writes) {
-    const replaces = write.replaces === undefined ? '' : ` — replaces sha256:${sha(write.replaces)}`;
+    const old = write.replaces ?? (write.directory ? undefined : regularBytes(write.path));
+    const replaces = old === undefined ? '' : ` — replaces sha256:${sha(old)}`;
     pathLine(write.path, false, `writes: ${display(write.path)} sha256:${sha(write.bytes)}${replaces}`);
+    for (const line of write.removes ?? []) lines.push(`removes: ${line}`);
+    if (write.matches === false) {
+      refused.push({ path: display(write.path), key: display(write.path), reason: 'the plan is not the one the file\'s own bytes give' });
+    }
   }
   for (const path of plan.directories) pathLine(path, true, `writes: ${display(path)}/ created`);
   lines.push(...plan.temporaries);
@@ -388,7 +430,7 @@ export const main = (argv, io = {}) => {
     platform: resolved.platform, claudeDir: args['claude-dir'] };
   let result;
   try {
-    result = checkApply(args.variant, facts, { detect: resolved.detect, planGitHooks: resolved.planGitHooks });
+    result = checkApply(args.variant, facts, { detect: resolved.detect, planGitHooks: resolved.planGitHooks, planGlobalRemoval: resolved.planGlobalRemoval });
   } catch (error) {
     for (const line of error.lines ?? [error.message]) resolved.log(line);
     return 3;

package/tools/attribution.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// attribution.mjs — the writer of the advisor's `attribution` item: when the project's AGENTS.md block
+// reads off, it sets Claude Code's `attribution` setting in the project .claude/settings.json so the
+// harness adds no Co-Authored-By trailer, PR text or session link. Preview by default; --apply writes.
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CLAUDE_DIR, EXPECTED_WORKFLOW_VERSION, SETTINGS_FILE, preflightVelocityProfile } from './velocity-profile.mjs';
+import { formatJson } from './gate-hook.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+export const ATTRIBUTION_KEY = 'attribution';
+export const LEGACY_ATTRIBUTION_KEY = 'includeCoAuthoredBy';
+// The one form the writer writes: `false` would make a CLI older than v2.1.281 skip the whole file.
+export const ATTRIBUTION_HIDDEN = Object.freeze({ commit: '', pr: '', sessionUrl: false });
+export const ATTRIBUTION_MALFORMED = 'ATTRIBUTION_MALFORMED';
+export const ATTRIBUTION_STAMP = 'ATTRIBUTION_STAMP';
+export const ATTRIBUTION_SHARED_NOTICE = `notice: ${SETTINGS_FILE} is the project-scope settings file — in a visible deployment it is committed and shared with everyone on this project, as the AGENTS.md block is`;
+
+const EXIT_OK = 0;
+const EXIT_REFUSED = 1;
+const EXIT_USAGE = 2;
+const USAGE = 'usage: attribution [--cwd <root>] [--apply]';
+const CHOICE_LINE = /^> \*\*Agent attribution: ([^*\s]+)\*\*/mu;
+const CHOICES = ['off', 'on'];
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasOwn = (object, key) => isObject(object) && Object.hasOwn(object, key);
+const refusal = (code, message) => Object.assign(new Error(`${code}: ${message}`), { code, exitCode: EXIT_REFUSED });
+const usageError = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+
+// off, on, or null for an absent file, an absent line or another value; any other read failure throws.
+export const readAttributionChoice = (root, deps = {}) => {
+  let text;
+  try {
+    text = String((deps.readFile ?? readFileSync)(join(root, 'AGENTS.md'), 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  const value = text.match(CHOICE_LINE)?.[1];
+  return CHOICES.includes(value) ? value : null;
+};
+
+// Per key, the local file's value while it carries the key, else the project's; an object is taken whole.
+export const effectiveAttribution = (project, local) => Object.fromEntries([ATTRIBUTION_KEY, LEGACY_ATTRIBUTION_KEY]
+  .map((key) => [key, hasOwn(local, key) ? local[key] : project?.[key]])
+  .filter(([, value]) => value !== undefined));
+
+export const attributionHidesText = (effective) => {
+  const value = effective?.[ATTRIBUTION_KEY];
+  if (value === false) return true;
+  if (isObject(value) && value.commit === '' && value.pr === '') return true;
+  const setsText = hasOwn(value, 'commit') || hasOwn(value, 'pr');
+  return !setsText && effective?.[LEGACY_ATTRIBUTION_KEY] === false;
+};
+
+// The wrong-typed key of one settings file, or null: attribution is an object or a boolean, the legacy key a boolean.
+export const wrongTypedKey = (data) => {
+  if (hasOwn(data, ATTRIBUTION_KEY) && !isObject(data[ATTRIBUTION_KEY]) && typeof data[ATTRIBUTION_KEY] !== 'boolean') {
+    return `${ATTRIBUTION_KEY} must be an object or a boolean`;
+  }
+  if (hasOwn(data, LEGACY_ATTRIBUTION_KEY) && typeof data[LEGACY_ATTRIBUTION_KEY] !== 'boolean') return `${LEGACY_ATTRIBUTION_KEY} must be a boolean`;
+  return null;
+};
+
+export const writeAttribution = ({ cwd, dryRun = true } = {}, deps = {}) => {
+  const root = resolve(cwd ?? deps.cwd ?? process.cwd());
+  const preflight = preflightVelocityProfile({ cwd: root }, deps);
+  const before = preflight.projectSettings.data ?? null;
+  const malformed = wrongTypedKey(before);
+  if (malformed) throw refusal(ATTRIBUTION_MALFORMED, `${SETTINGS_FILE}: ${malformed} — nothing written`);
+  const planned = !attributionHidesText(effectiveAttribution(before, preflight.localSettings.data));
+  const after = planned ? { ...before, [ATTRIBUTION_KEY]: { ...ATTRIBUTION_HIDDEN } } : before;
+  const result = { root, planned, wrote: false, before, after, claudeDirAbsent: preflight.claudeDirAbsent };
+  if (dryRun || !planned) return result;
+  if (!preflight.stampOk) {
+    throw refusal(ATTRIBUTION_STAMP, `not a deployed agent-workflow project at lineage ${EXPECTED_WORKFLOW_VERSION} (found ${preflight.stamp ?? 'none'}) — run /agent-workflow-kit upgrade first`);
+  }
+  if (preflight.claudeDirAbsent) (deps.mkdir ?? mkdirSync)(join(root, CLAUDE_DIR), { recursive: true });
+  (deps.writeFile ?? writeFileSync)(join(root, SETTINGS_FILE), formatJson(after, preflight.projectSettings.eol ?? '\n'), 'utf8');
+  return { ...result, wrote: true };
+};
+
+export const formatResult = (result, dryRun) => {
+  if (!result.planned) return ['nothing to change: the settings already hide the trailer and the PR text'];
+  const object = JSON.stringify(ATTRIBUTION_HIDDEN);
+  return dryRun ? [`would set ${ATTRIBUTION_KEY} (${SETTINGS_FILE}): ${object}`, ATTRIBUTION_SHARED_NOTICE]
+    : [`set ${ATTRIBUTION_KEY} (${SETTINGS_FILE}): ${object}`];
+};
+
+export const parseArgs = (argv) => {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  const args = { help: false, apply: false, cwd: undefined };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--apply') args.apply = true;
+    else if (flag === '--cwd') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) throw usageError('--cwd takes a value');
+      args.cwd = value;
+      index += 1;
+    } else throw usageError(`unknown argument: ${flag}`);
+  }
+  return args;
+};
+
+export const main = (argv = process.argv.slice(2), deps = {}) => {
+  const log = deps.log ?? console.log;
+  const errlog = deps.errlog ?? console.error;
+  let args;
+  try {
+    args = parseArgs(argv);
+    if (args.help) {
+      log(USAGE);
+      return EXIT_OK;
+    }
+    args.root = resolve(deps.cwd ?? process.cwd(), args.cwd ?? '.');
+    if (!statSync(args.root, { throwIfNoEntry: false })?.isDirectory()) throw usageError(`--cwd is not a directory: ${args.root}`);
+  } catch (error) {
+    errlog(error.message);
+    errlog(USAGE);
+    return EXIT_USAGE;
+  }
+  try {
+    const result = writeAttribution({ cwd: args.root, dryRun: !args.apply }, deps);
+    for (const line of formatResult(result, !args.apply)) log(line);
+    return EXIT_OK;
+  } catch (error) {
+    errlog(error?.message ?? String(error));
+    return EXIT_REFUSED;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/cheap-agents-read.mjs

@@ -135,6 +135,18 @@ export const executorTemplate = (posture, deps = {}) => {
   return { name: EXECUTOR_VEHICLE, content: deriveExecutorBody(bundled.content, posture), rederive: true };
 };
 
+// The executor ensure's cell 6: a regular placed executor whose bytes differ from the body derived from
+// the settings; the placed file's read failure throws.
+export const executorBodyDiffers = (projectDir, deps = {}) => {
+  const fs = readFsDeps(deps);
+  const abs = join(projectDir, EXECUTOR_VEHICLE_REL);
+  const stat = lstatNoFollow(abs, fs);
+  if (stat === null || stat.isSymbolicLink() || !stat.isFile()) return false;
+  const { posture } = readExecutorPosture(projectDir, deps);
+  if (posture === null) return false;
+  return fs.readFile(abs, UTF8) !== executorTemplate(posture, deps).content;
+};
+
 const READ_ONLY_TOOLS = new Set(['Read', 'Grep', 'Glob']);
 
 // The YAML subset a vehicle's frontmatter is read with: a bare scalar, a single- or double-quoted

package/tools/commit-guard.mjs

@@ -41,9 +41,7 @@
 // boundary). Read-only; dependency-free; Node >= 22. No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
-import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { isDirectRun } from './direct-run.mjs';
 import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
@@ -54,25 +52,14 @@ import {
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
-import { GIT_MAX_BUFFER, resolveGitLocation } from './git-env.mjs';
+import { resolveGitLocation } from './git-env.mjs';
 import { escapeForDisplay } from './repo-lex.mjs';
 
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 const sha = (text) => createHash('sha256').update(text).digest('hex');
 
-const gitLine = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
-  if (r.error || r.status !== 0) return null;
-  return r.stdout.toString('utf8').replace(/\r?\n$/, '');
-};
-
-// resolveGitHooksPath(projectDir) → the ABSOLUTE hooks dir git itself reports (a linked worktree
-// answers with ITS OWN hooks path — never a hardcoded `.git/hooks`), or null outside a git tree.
-// The one home consumers (the recommendations guard-install probe) read instead of re-deriving it.
-export const resolveGitHooksPath = (projectDir) => {
-  const line = gitLine(['rev-parse', '--git-path', 'hooks'], projectDir);
-  return line == null ? null : resolve(projectDir, line);
-};
+// The hooks-path question and the pre-commit reader live in git-hooks.mjs, their writer's home.
+export { resolveGitHooksPath, readPreCommitState, canonicalGuardLineRe, INSTALLER_MARKER_RE } from './git-hooks.mjs';
 
 // How many offending paths the index-lag refusal names before it states a remainder count: enough
 // to act on, bounded so a wide lag cannot bury a pre-commit hook's output.

package/tools/ensure-configs.mjs

@@ -5,7 +5,7 @@
 //   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
 //   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
 //   vehicles       docs/ai/vehicles.json       seed-if-missing (same)
-//   executor       .claude/agents/executor.md  re-derived from docs/ai/vehicles.json when its bytes differ; absent stays absent
+//   executor       .claude/agents/executor.md  judged against docs/ai/vehicles.json, never written: a differing body is pending
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
 //   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, refreshed only on
 //                  + docs/ai/specs/index.md    a shipped prior body, an edited one replaced only on the
@@ -80,16 +80,16 @@ Usage:
   --help, -h    this help
 
 Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
-refreshed in place. Four ops refresh instead: the orchestration onboarding note, only while it still
+refreshed in place. Three ops refresh instead: the orchestration onboarding note, only while it still
 matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer reader
 and checker pairs, only while a file's bytes are a body a release shipped (an edited file is
 preserved, the writes that depend on it — the spec store root included — are withheld behind it,
-and ONE printed replace line replaces every edited file only on the user's yes); the placed executor
-vehicle (.claude/agents/executor.md), re-derived from docs/ai/vehicles.json
-whenever its bytes differ from the derived body (a hand edit is replaced, never preserved; an absent
-file is never placed here); and the navigator index — a GENERATED artifact, regenerated
+and ONE printed replace line replaces every edited file only on the user's yes); and the navigator index — a GENERATED artifact, regenerated
 whenever it is missing or stale; where a module the project's hook loads is not the bundled one,
 the project's own checker judges the navigator and a write it rejects is put back byte for byte.
+The executor ensure writes nothing: a placed .claude/agents/executor.md whose bytes differ from the
+body derived from docs/ai/vehicles.json is pending — the advisor's executor-vehicle.differing item
+changes it on your yes; an absent file is never placed here.
 The enforcement-script ensure detects an older ADR-store layout FIRST and instructs the opt-in
 migration instead of seeding.