@sabaiway/agent-workflow-kit 14.33.0 → 14.34.0

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.
 

package/tools/ensure-executor.mjs

@@ -1,9 +1,9 @@
 // ensure-executor.mjs — the EIGHTH upgrade ensure, fifth in the fixed order right after `vehicles`:
-// the placed executor vehicle (.claude/agents/executor.md) re-derived from docs/ai/vehicles.json.
-// The agents writer PLACES the vehicle on consent; this ensure never does — it only keeps a placed
-// body equal to the one derived from the settings, and a hand edit is replaced, never preserved.
+// the placed executor vehicle (.claude/agents/executor.md) judged against the body derived from
+// docs/ai/vehicles.json. It never writes: the agents writer PLACES the vehicle on consent, and a placed
+// body that differs is reported `pending` — the advisor's executor-vehicle.differing item re-derives it.
 //
-// The state table, in the order the cells are proven (the write is the LAST step):
+// The state table, in the order the cells are proven:
 // | cell | .claude, .claude/agents | placed path | docs/ai/vehicles.json | answer | read before answering |
 // |------|-------------------------|-------------|-----------------------|--------|-----------------------|
 // | 0 | a symlink or not a directory | any | any | failed / wrong-node-kind | nothing |
@@ -12,30 +12,27 @@
 // | 3 | directories | regular file | unreadable (malformed, read or lstat error) | failed / vehicle-settings-unreadable | the settings only |
 // | 4 | directories | regular file | present or absent | failed / bundle-unreadable when the bundled template cannot be read | settings, bundle |
 // | 5 | directories | regular file, bytes equal to the derived body | present or absent | already-current | settings, bundle, placed file |
-// | 6 | directories | regular file, bytes differ | present or absent | dry-run would-re-derive; apply re-derived, or failed / write-refused | settings, bundle, placed file |
+// | 6 | directories | regular file, bytes differ (executorBodyDiffers) | present or absent | pending, on the dry run and the run alike | settings, bundle, placed file |
 // | 7 | an lstat of `.claude`, `.claude/agents` or the placed path throwing other than ENOENT, or the read of the placed file throwing | | | NOT caught: the error propagates to the CLI's catch-all (`unexpected-error`) | |
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
+import { lstatSync } from 'node:fs';
 import { join } from 'node:path';
-import { writeContainedFileAtomic } from './atomic-write.mjs';
-import { composeFailure, composeOutcome, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
-import { assertDirSafe, AGENTS_DIR, CLAUDE_DIR, CHEAP_AGENTS_SYMLINK, EXECUTOR_VEHICLE_REL, executorTemplate, readExecutorPosture } from './cheap-agents-read.mjs';
+import { composeFailure, composeOutcome, probeSeedTarget } from './ensure-ops.mjs';
+import { assertDirSafe, AGENTS_DIR, CLAUDE_DIR, CHEAP_AGENTS_SYMLINK, EXECUTOR_VEHICLE_REL, executorBodyDiffers, executorTemplate, readExecutorPosture } from './cheap-agents-read.mjs';
 import { VEHICLES_REL } from './vehicle-settings.mjs';
 
 export const EXECUTOR_OP = 'executor';
 
 const BUNDLE_DIR = ['references', 'agents'];
-const ENCODING = 'utf8';
 
 const ok = (token, lines) => composeOutcome(EXECUTOR_OP, token, lines, false);
 const loud = (cause, ...lines) => composeFailure(EXECUTOR_OP, cause, ...lines);
 const causeOf = (err) => String((err && err.message) || err);
 
-export const ensureExecutor = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+export const ensureExecutor = ({ cwd, kitRoot, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
-  const read = deps.readFile ?? readFileSync;
 
   try {
     assertDirSafe(join(cwd, CLAUDE_DIR), CLAUDE_DIR, { lstat });
@@ -59,29 +56,15 @@ export const ensureExecutor = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     return loud('vehicle-settings-unreadable', `${EXECUTOR_VEHICLE_REL}: ${reason} — nothing written; fix ${VEHICLES_REL} by hand, then re-run`);
   }
 
-  let body;
+  const bundleDeps = { ...deps, bundleDir: join(kitRoot, ...BUNDLE_DIR) };
   try {
-    body = executorTemplate(posture, { ...deps, bundleDir: join(kitRoot, ...BUNDLE_DIR) }).content;
+    executorTemplate(posture, bundleDeps);
   } catch (err) {
     return loud('bundle-unreadable', `${EXECUTOR_VEHICLE_REL}: the bundled executor template could not be read, so nothing was written — reinstall the kit. ${causeOf(err)}`);
   }
 
-  const existing = read(target, ENCODING);
-  if (existing === body) {
+  if (!executorBodyDiffers(cwd, bundleDeps)) {
     return ok('already-current', [`${EXECUTOR_VEHICLE_REL}: the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}, source ${posture.source}) — nothing written`]);
   }
-  if (dryRun) {
-    return ok('would-re-derive', [`${EXECUTOR_VEHICLE_REL}: differs from the body derived from ${VEHICLES_REL} — would be rewritten (a hand edit is replaced, never preserved)`]);
-  }
-
-  let result;
-  try {
-    result = writeContainedFileAtomic(cwd, target, body, deps, { label: EXECUTOR_VEHICLE_REL });
-  } catch (err) {
-    return loud('write-refused', `${EXECUTOR_VEHICLE_REL}: ${causeOf(err)}`);
-  }
-  return ok('re-derived', [
-    `${EXECUTOR_VEHICLE_REL}: rewritten to the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}) — a hand edit was replaced; set the model in ${VEHICLES_REL}`,
-    ...tmpNote(EXECUTOR_VEHICLE_REL, result.tmpLeftBehind),
-  ]);
+  return ok('pending', [`${EXECUTOR_VEHICLE_REL}: differs from the body derived from ${VEHICLES_REL} — nothing written; the advisor's executor-vehicle.differing item re-derives it on your yes`]);
 };

package/tools/ensure-vocabulary.mjs

@@ -18,9 +18,8 @@ export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', '
 // ensure's pair refresh (reader or checker) — a deployed script on a body a release shipped,
 // rewritten to the bundled one; a custom body is rewritten only by the replace run the user's yes
 // starts (--replace-custom), never by a plain run.
-// `re-derived` is the executor ensure rewriting a placed executor whose bytes differ from the body derived from docs/ai/vehicles.json.
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated', 're-derived']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate', 'would-re-derive']);
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -33,6 +32,7 @@ export const ENSURE_TOKENS = Object.freeze([
   'already-current',
   'already-present',
   'not-placed',
+  'pending',
   'customized-preserved',
   'malformed-preserved',
   'skipped-no-node-evidence',
@@ -80,7 +80,7 @@ export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'note-refreshed',
   'refreshed',
   'regenerated',
-  're-derived',
+  'pending',
   'already-current',
   'customized-preserved',
   'malformed-preserved',

package/tools/git-hooks.mjs

@@ -2,7 +2,8 @@
 // git-hooks.mjs — the thin writer of the two git-hook items (`enforcement`, `commit-guard`): it copies
 // the bundled scripts create-only and spawns the project's own scripts/install-git-hooks.mjs, which
 // decides the hook at the write. The leaf decides nothing about the hook: the danger check binds the
-// copies and the installer bytes this dry run answers, never git's hooks dir.
+// copies and the installer bytes this dry run answers, never git's hooks dir. It is also the home of the
+// one pre-commit reader, which the commit-guard apply runs after the installer to verify the arm.
 import { lstatSync, readFileSync, readdirSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
@@ -11,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { writeProjectFileCreateOnly } from './atomic-write.mjs';
 import { NODE_EVIDENCE_SCRIPTS } from './node-evidence.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { isDirectRun } from './direct-run.mjs';
 
 const TOOLS = dirname(fileURLToPath(import.meta.url));
@@ -39,6 +41,34 @@ const nodeAt = (path, lstat) => {
 const isPlainDir = (node) => node !== null && node.isDirectory() && !node.isSymbolicLink();
 const isFile = (node) => node !== null && node.isFile() && !node.isSymbolicLink();
 
+// The absolute hooks dir git itself reports (a linked worktree's own, core.hooksPath), or null outside a git tree.
+export const resolveGitHooksPath = (projectDir, env = process.env) => {
+  const result = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: projectDir, env, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) return null;
+  return resolve(projectDir, result.stdout.toString('utf8').replace(/\r?\n$/, ''));
+};
+
+export const INSTALLER_MARKER_RE = /:install-git-hooks\.mjs$/m;
+const escapeRe = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// Armed means the exact line the installer writes on the kit's own guard path; a commented or lookalike line is not.
+export const canonicalGuardLineRe = (toolsDir = TOOLS) => new RegExp(`^node "${escapeRe(join(toolsDir, 'commit-guard.mjs'))}" --check$`, 'm');
+
+// The one reader of git's pre-commit: whose hook it is, and whether the canonical guard line arms it.
+export const readPreCommitState = (root, deps = {}) => {
+  const hooksPath = (deps.gitHooksPath ?? resolveGitHooksPath)(root, deps.env);
+  if (hooksPath === null) return { state: 'no-hooks-dir', armed: false };
+  const path = join(hooksPath, 'pre-commit');
+  let hook;
+  try {
+    (deps.lstat ?? lstatSync)(path);
+    hook = String((deps.readFile ?? readFileSync)(path, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { state: 'absent', armed: false };
+    return { state: 'unreadable', code: error?.code ?? String(error?.message ?? error), path, armed: false };
+  }
+  return { state: INSTALLER_MARKER_RE.test(hook) ? 'managed' : 'unmanaged', armed: canonicalGuardLineRe(deps.toolsDir).test(hook) };
+};
+
 // The dry run: what the apply copies and the installer it runs, with the bytes of each.
 export const planGitHooks = ({ root, variant, toolsDir = TOOLS, lstat = lstatSync, readFile = readFileSync }) => {
   const scripts = join(root, SCRIPTS_REL);
@@ -115,7 +145,7 @@ const rollBack = (plan, created, io) => {
 
 export const applyGitHooks = (plan, io = {}) => {
   const resolved = { lstat: lstatSync, unlink: unlinkSync, rmdir: rmdirSync, readdir: readdirSync, env: process.env,
-    log: console.log, error: console.error, writeFile: writeProjectFileCreateOnly,
+    log: console.log, error: console.error, writeFile: writeProjectFileCreateOnly, toolsDir: TOOLS,
     spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
   const created = [];
   const leftovers = [];
@@ -145,7 +175,15 @@ export const applyGitHooks = (plan, io = {}) => {
   const child = resolved.spawn(plan.runs.argv, { cwd: plan.root, env: resolved.env, stdio: 'inherit' });
   if (child.status !== 0) return fail([`installer exited ${child.status ?? child.signal ?? child.error?.code}`]);
   for (const path of leftovers) resolved.error(`not removed: ${path}`);
-  return EXIT_OK;
+  if (plan.variant !== 'commit-guard') return EXIT_OK;
+  // An installer older than the arm ignores --commit-guard and still exits 0, so the arm is read back under its env.
+  const hooksDir = resolveGitHooksPath(plan.root, resolved.env);
+  const hook = readPreCommitState(plan.root, { env: resolved.env, toolsDir: resolved.toolsDir, gitHooksPath: () => hooksDir });
+  if (hook.state === 'no-hooks-dir' || hook.armed) return EXIT_OK;
+  const path = join(hooksDir, 'pre-commit');
+  resolved.error(hook.state === 'unreadable' ? `${path} is unreadable (${hook.code}) after the installer exited 0`
+    : `${path} carries no commit-guard line after the installer exited 0 — an installer older than the arm ignores --commit-guard; refreshing ${INSTALLER_REL} from the kit's references/scripts/ copy is your own step`);
+  return EXIT_INCOMPLETE;
 };
 
 export const parseArgs = (argv) => {