simt-dev 0.2.0 → 0.2.1

package/src/ci/workflow.mjs

@@ -50,6 +50,7 @@ import { PACKAGE_ROOT } from '../workspace.mjs';
 import { PACKAGE_NAME, WORKFLOW_FILE_NAME } from '../name.mjs';
 import { renderLocator } from '../locate.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 
 /** Directory whose presence means this repo runs GitHub Actions. */
 export const WORKFLOWS_DIR = '.github/workflows';
@@ -169,12 +170,16 @@ function skeleton(name, steps, { matrix = null } = {}) {
   const job = matrix?.node ? '\${{ matrix.os }} node \${{ matrix.node }}' : name;
   return `name: ${name}
 
+# Pull requests only, and that is a decision rather than a default.
+#
+# A gate that runs on every push re-runs itself for every commit that pushes a
+# branch forward, including the ones nobody asked it about, and its verdict has to
+# be cleared before the next one lands. \`pull_request\` asks one question — may this
+# merge — and answers it once. \`main\` here is the branch protection list, not a
+# trigger: the gate that has to pass is the one the pull request runs, and the one
+# on \`main\` is whatever CI the repository already has there.
 on:
   pull_request:
-  push:
-    branches:
-      - main
-      - master
 
 # Read-only is enough to check a repo, and a gate job does not need to write to it.
 permissions:
@@ -235,7 +240,7 @@ function indent(text, spaces) {
  * @param {{own?: boolean}} [options]
  * @returns {string} YAML, LF-terminated
  */
-export function renderWorkflow({ own = false } = {}) {
+export function renderWorkflow({ own = false, npm = true, version } = {}) {
   if (own) {
     const floor = nodeFloor();
     return `${header(true)}${skeleton(
@@ -267,17 +272,34 @@ export function renderWorkflow({ own = false } = {}) {
     )}\n`;
   }
 
-  const locator = renderLocator('check --root "$ROOT"', {
-    remedy: `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`,
-  });
+  const v = version ?? packageVersion();
+  // The install step is the whole of S35's consumer CI: a repository with npm pins
+  // simt-dev as a devDependency and `npm ci` restores it; one without (Gradle,
+  // Connect IQ) has no node_modules to pin in, so CI installs the same pinned global
+  // binary the machine remedy names. The two must agree, or the gate passes in one
+  // place and cannot start in the other.
+  const install = npm
+    ? [
+        '      - name: install dependencies',
+        '        # `npm ci` needs a lockfile; a repo without one is still gated, not skipped.',
+        '        run: npm ci || npm install',
+      ]
+    : [
+        '      - name: install the pinned gate binary',
+        '        # No node_modules to pin in, so a pinned global install: the same bytes',
+        '        # the machine remedy names, so the gate cannot pass locally and fail here.',
+        `        run: npm i -g ${PACKAGE_NAME}@${v}`,
+      ];
+  const remedy = npm
+    ? `REMEDY run: npm i -D ${PACKAGE_NAME}   (the gate runs from the pinned dependency)`
+    : `REMEDY run: npm i -g ${PACKAGE_NAME}@${v}   (the gate runs from a pinned global install)`;
+  const locator = renderLocator('check --root "$ROOT"', { remedy });
   return `${header(false)}${skeleton(
     `${CLI} check`,
     [
       uses('checkout'),
       setupNode(nodeFloor()),
-      '      - name: install dependencies',
-      '        # \`npm ci\` needs a lockfile; a repo without one is still gated, not skipped.',
-      '        run: npm ci || npm install',
+      ...install,
       `      - name: ${CLI} check`,
       '        run: |',
       indent(`set -eu\nROOT="\${GITHUB_WORKSPACE}"\n${locator}`, 10),

package/src/commands/graph.mjs

@@ -7,11 +7,17 @@
 // the offending node, the file it disagrees with, and both numbers.
 
 import { EXIT, emit, fail, isJson } from '../output/index.mjs';
-import { loadRegistry, REGISTRY_PATH } from '../graph/load.mjs';
+import { loadRegistry } from '../graph/load.mjs';
+import { CLI } from '../name.mjs';
 
 export async function lintCommand(positional, flags) {
-  const path = positional[0] ?? REGISTRY_PATH;
-  const { ok, registry, errors, warnings, verified, workspace } = await loadRegistry(path, flags);
+  // The resolved path comes back from the loader, because when no positional is given it
+  // falls back to the member that holds the registry in this workspace (ADR-061) - and the
+  // reader should see where it actually looked, not a constant that no longer exists.
+  const { ok, registry, errors, warnings, verified, workspace, path } = await loadRegistry(
+    positional[0] ?? null,
+    flags,
+  );
 
   if (isJson(flags)) {
     emit(
@@ -40,7 +46,10 @@ export async function lintCommand(positional, flags) {
   }
 
   if (!registry) {
-    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY);
+    // The default remedy for this exit code is `run: simt-dev graph lint`, which from
+    // inside `graph lint` is circular: the reader just ran it and got this. Name the
+    // argument the command takes, because an explicit path is the way out (ADR-061).
+    return fail(errors[0] ?? `${path}: unreadable`, EXIT.REGISTRY, `run: ${CLI} graph lint <path-to-registry>`);
   }
 
   const lines = [

package/src/commands/help.mjs

@@ -4,7 +4,8 @@ import { CLI } from '../name.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
-                           --accept-conflicts; never commits or pushes)
+                           --accept-conflicts; in place unless --backup;
+                           never commits or pushes)
 ${CLI} doctor                 classify a repo and check config health
 ${CLI} check                  the gate: projection drift, manifest validity, policy
 ${CLI} sync [--yes]           regenerate the projection (idempotent)
@@ -19,6 +20,10 @@ ${CLI} skills brief --task    tier-1 pre-assembled brief  <- the common case
 ${CLI} skills show <name>     tier-2 body (respects --max-bytes)
 ${CLI} skills why <name>      the signal chain that selected it
 ${CLI} skills find <query>    search across capability and keyword
+${CLI} skills eval [corpus]   measure the resolver against a gold corpus
+                           (reports precision and recall; exits non-zero on
+                            regression; without an argument, the corpus in this
+                            checkout)
 ${CLI} skills install <name>  pin a skill into the repo as a local override
                            (dry-run unless --yes; a multi-variant skill needs
                            --variant or --from rather than a guess)
@@ -26,9 +31,15 @@ ${CLI} skills install <name>  pin a skill into the repo as a local override
 ${CLI} rules list             the rule catalogue (--root marks what applies to a repo)
 ${CLI} rules show <id>        one rule body
 ${CLI} rules why <id|ADR-NNN> the decision that settled it, and whether it is still in force
+                           (--all prints every ruling, not the first two)
 ${CLI} hooks install [--yes]   install the shared dispatcher; report what it would run
                            (dry-run unless --yes; refuses to take over routing git
                             already uses, and --yes is that consent)
+${CLI} hooks status            what each git event routes to, and whether it is wired
+${CLI} hooks run <event>       run one event's gates now, as git would
+                           (pre-commit, pre-push, post-merge, ...)
+${CLI} graph lint              check the skill registry against the skills on disk
+                           (byte counts, dangling edges, unresolvable variants)
 ${CLI} ci                     simt-dev's own .github files: create or refresh them
                            (dry-run unless --yes; refreshes the templates' own copies
                             and no repository else's)
@@ -55,9 +66,16 @@ const FLAGS = `--json                 structured output
                         file, then the sibling heuristic if it verifies)
 --dry-run               report what would change, change nothing
 --yes                   assume yes; required in automation, never prompts
---all                   ignore the budget and resolve everything
+--check                 report drift and write nothing (sync, ci)
+--all                   ignore a cap: every ruling of a record, or the skills budget
 --variant <id>          which body of a multi-variant skill to use
---from <repo/path>      install from a declared source by name`;
+--from <repo/path>      install from a declared source by name
+--list                  print the MCP tool surface without reading stdin (mcp)
+--accept-conflicts      init: adopt rules that collide with hand-written ones
+--backup                init: tag the pre-adoption commit and branch onto
+                        simt-dev/adopt before writing (the undo path)
+--help                  this text
+--version               the version, and the SHA it was built from`;
 
 const PRINCIPLES = `design rules:
   deterministic       same repo + same task = same answer, forever
@@ -78,7 +96,7 @@ export async function help(argv) {
     [
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
       '',
-      'usage: simt-dev <command> [args] [flags]',
+      `usage: ${CLI} <command> [args] [flags]`,
       '',
       'commands:',
       COMMANDS,

package/src/commands/hooks.mjs

@@ -13,19 +13,20 @@
 // foreign hook is found by asking git rather than by reading config.
 
 import { execFile } from 'node:child_process';
-import { chmod, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, relative } from 'node:path';
 import { promisify } from 'node:util';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { MANIFEST, readManifest } from '../projection/manifest.mjs';
 import { EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, fileFor, renderChainedShim, renderShim } from '../hooks/shim.mjs';
-import { readHooksPath, readHooksState } from '../compare/hooksstate.mjs';
+import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { knownGates } from '../hooks/resolve.mjs';
 import { runGates } from '../hooks/dispatcher.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
+import { packageVersion, hasNpm } from '../package-version.mjs';
 
 const exec = promisify(execFile);
 
@@ -70,12 +71,6 @@ async function runHook(args, flags) {
   return result.failed ? EXIT.FAIL : EXIT.OK;
 }
 
-const GATE_KEY = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
-
-function gateCount(manifest, event) {
-  return (manifest?.gates?.[GATE_KEY[event]] ?? []).length;
-}
-
 /**
  * The path to write into a chained shim: relative to the repository's top level
  * wherever the hook lives inside it.
@@ -106,19 +101,6 @@ async function relativeTarget(root, target) {
   return rel === '' || rel.startsWith('..') ? resolved : rel;
 }
 
-/**
- * Whether a missing shim for this event is a defect.
- *
- * A repo that declares no gate for an event has no reason to want a shim for it,
- * so its absence is the correct end state. A repo with NO manifest is different:
- * we do not know what it wants, so we cannot rule the shim out - absence of
- * knowledge is not a decision.
- */
-function wantsShim(manifest, exists, event) {
-  if (!exists) return true;
-  return gateCount(manifest, event) > 0;
-}
-
 async function installHooks(root, flags) {
   const { manifest, exists, error } = await readManifest(root);
   if (error) return fail(`${MANIFEST_FILE}: ${error}`, EXIT.CONFIG);
@@ -126,7 +108,8 @@ async function installHooks(root, flags) {
     return fail(`${root} has no ${MANIFEST_FILE}; gates must be declared before hooks can run them`, EXIT.CONFIG, `run: ${CLI} init --root ${root}`);
   }
 
-  const state = await readHooksState(root, { declaresGate: (e) => wantsShim(manifest, exists, e) });
+  const declaresGate = (event) => wantsShim(manifest, exists, event);
+  const state = await readHooksState(root, { declaresGate });
   const current = state.current;
   const wants = HOOKS_DIR;
 
@@ -139,30 +122,19 @@ async function installHooks(root, flags) {
   // for a plan and then `--yes` - advice that printed a plan and wrote anyway.
   const mode = writeMode(flags);
 
+  // The release this install renders, and the kind of repository it installs into: the
+  // remedy a shim prints when it cannot find the binary must name the install that
+  // actually works here — a devDependency where package.json exists, a pinned global
+  // install where there is no node_modules to pin in.
+  const version = packageVersion();
+  const npm = await hasNpm(root);
+
   // Only install a shim for an event that declares at least one gate. A shim with
   // an empty gate list enforces nothing, yet merely existing it REPLACES whatever
   // git was running - so installing one over a working hand-written hook is a
   // downgrade dressed as an upgrade. `init` already says this in prose; install
   // has to agree, or the two commands describe different tools.
   const wanted = EVENTS.filter((e) => gateCount(manifest, e) > 0);
-  if (wanted.length === 0) {
-    if (isJson(flags)) {
-      emitJson({ ok: false, command: 'hooks install', root, nothingToEnforce: true, filesWritten: false });
-      return EXIT.FAIL;
-    }
-    emit(
-      [
-        `repo     ${root}`,
-        '',
-        `BLOCKED  ${root} declares no gate it can run, so there is nothing to enforce.`,
-        '         Installing shims anyway would stop running whatever git runs now',
-        '         and replace it with a gate that checks nothing.',
-        `REMEDY  add the gates this repo can actually run to ${MANIFEST_FILE}, then re-run.`,
-      ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
-    );
-    return EXIT.FAIL;
-  }
 
   // Foreign hooks on events this tool does NOT gate. Routing replaces the whole
   // directory git reads from, so these have to be carried across explicitly or they
@@ -179,7 +151,21 @@ async function installHooks(root, flags) {
   // Keying this on the event vocabulary instead of on the manifest cost a repository
   // git-lfs hook: pre-push is a gated event in general, but this repo declares no
   // pre-push gate, so nothing replaces its hook and routing would have dropped it.
-  const chained = [
+  // A chained shim and the hook it chains must be two different files.
+  //
+  // `foreignHooks` lists every executable file in the directory git reads hooks from -
+  // and when that directory is this tool's own, a file a person dropped in there is
+  // listed too. Chaining it means writing a shim at `.simt-hooks/<name>` whose TARGET is
+  // `.simt-hooks/<name>`: the same path. The shim overwrites the hook it was written to
+  // preserve and then runs itself, so the hook stops working and git recurses in a loop
+  // nothing reports. Confirmed at the previous release, which printed
+  // `UPDATED .simt-hooks/mine (chained: runs .simt-hooks/mine)`.
+  //
+  // So such a hook is not chained. It is not stopped either - nothing overwrites it, so
+  // git keeps running it - and it is reported as what it is below.
+  const chainable = (event, target) => target !== fileFor(event);
+
+  const candidates = [
     // Already chained by an earlier install, read back off disk: re-rendered from the
     // file's own contents so the bytes cannot drift on a second run.
     ...(await Promise.all(
@@ -198,12 +184,71 @@ async function installHooks(root, flags) {
         .filter((f) => gateCount(manifest, f.event) === 0)
         .map(async (f) => ({ event: f.event, target: await relativeTarget(root, f.path) })),
     )),
-  ].reduce((all, c) => (all.some((x) => x.event === c.event) ? all : [...all, c]), []);
+  ];
+
+  const chained = candidates
+    .filter((c) => chainable(c.event, c.target))
+    .reduce((all, c) => (all.some((x) => x.event === c.event) ? all : [...all, c]), []);
+
+  // Hooks that keep running untouched because chaining them was impossible. Separate
+  // from `chained` because the notes below say opposite things about the two: one runs
+  // the hook for you, the other leaves it alone and it still runs. Reporting both as
+  // "stopped running" - which is what this did - was false for this one and would push an
+  // operator to restore a hook that is already running.
+  const leftRunning = candidates.filter((c) => !chainable(c.event, c.target));
+
+  // Shims this tool wrote for an event the manifest no longer gates.
+  //
+  // `install` only ever ADDED files, so dropping a gate from the manifest left its shim
+  // on disk: still routed through `core.hooksPath`, still `PRESENT` in `hooks status`,
+  // and enforcing nothing. That is the exact harm the refusal below is written to
+  // prevent - reached by the sanctioned path rather than by the blocked one.
+  //
+  // It was a dead end rather than only a defect. With the LAST gate removed there is
+  // nothing to install, so `install` refused and wrote nothing, leaving the shim, the
+  // routing, and a remedy - "add the gates this repo can actually run" - telling a
+  // reader to undo the change they had just made, for a gate that may be gone because
+  // the script it ran was deleted. The only way out was to re-declare the gate and
+  // delete the file by hand.
+  //
+  // Read from `state.installed`, which describes every shim this install is responsible
+  // for, and not from `state.staleOurs`: that loop skips a shim the moment it matches
+  // what this run would render, so a *current* shim for an ungated event never reaches
+  // it - which is the common case here and the one that matters. `ours` on each entry is
+  // what keeps a file a person wrote in this directory from being deleted on their
+  // behalf; `wanted` and `chained` are what this run writes, so what is left is exactly
+  // the set nothing else here touches.
+  const obsolete = state.installed.filter(
+    (i) => i.present && i.ours && !wanted.includes(i.event) && !chained.some((c) => c.event === i.event),
+  );
+
+  // Nothing to write and nothing to take away is the only refusal. It sits after
+  // `obsolete` because a repository whose last gate just left the manifest has
+  // something to take away, and blocking that one left no way out except undoing
+  // the change by hand - see the note on `obsolete`.
+  if (wanted.length === 0 && obsolete.length === 0) {
+    if (isJson(flags)) {
+      emitJson({ ok: false, command: 'hooks install', root, nothingToEnforce: true, filesWritten: false });
+      return EXIT.FAIL;
+    }
+    emit(
+      [
+        `repo     ${root}`,
+        '',
+        `BLOCKED  ${root} declares no gate it can run, so there is nothing to enforce.`,
+        '         Installing shims anyway would stop running whatever git runs now',
+        '         and replace it with a gate that checks nothing.',
+        `REMEDY  add the gates this repo can actually run to ${MANIFEST_FILE}, then re-run.`,
+      ].join('\n'),
+      { maxBytes: flags.maxBytes ?? 0 },
+    );
+    return EXIT.FAIL;
+  }
 
   const plan = [];
   for (const event of wanted) {
     const path = join(root, fileFor(event));
-    const source = renderShim(event);
+    const source = renderShim(event, { npm, version });
     const existing = await readIfExists(path);
     if (existing === source) {
       plan.push({ file: fileFor(event), action: 'unchanged' });
@@ -224,7 +269,26 @@ async function installHooks(root, flags) {
       note: `chained: runs ${c.target}`,
     });
   }
-  const pathAction = current === wants ? 'unchanged' : current === null ? 'created' : 'updated';
+  for (const h of obsolete) {
+    plan.push({
+      file: fileFor(h.event),
+      action: 'removed',
+      // Named in the plan because the reader approving this write is about to lose a
+      // file, and "REMOVED pre-push" does not say why - which is the difference between
+      // agreeing with it and discovering later that a gate had been dropped by accident.
+      note: `no gate for ${h.event} in ${MANIFEST_FILE}; the shim enforced nothing`,
+    });
+  }
+  const routed = wanted.length > 0 || chained.length > 0;
+
+  // The routing this install leaves behind, which is not always `wants`. A repository
+  // that removed its last gate has no shims to route to, and leaving `core.hooksPath`
+  // pointed at the directory would stop its own hooks running - the plan has to say so,
+  // because a plan that prints "core.hooksPath updated .simt-hooks -> .simt-hooks" while
+  // the command unsets it is worse than no plan.
+  const leaves = routed ? wants : null;
+  const pathAction =
+    leaves === current ? 'unchanged' : leaves === null ? 'removed' : current === null ? 'created' : 'updated';
 
   // Refuse to take over routing git is already using without explicit consent.
   // Two cases, and the second one is the one that bites: core.hooksPath already
@@ -238,7 +302,7 @@ async function installHooks(root, flags) {
       ? state.foreign.map((f) => `  git runs ${f.event} at ${f.path} (${f.bytes} bytes)`)
       : [`  existing ${HOOKS_PATH_KEY} = ${current}`];
     if (isJson(flags)) {
-      emitJson({ ok: false, command: 'hooks install', root, currentHooksPath: current, wouldSet: wants, takeover: true, foreign: state.foreign, plan, filesWritten: false });
+      emitJson({ ok: false, command: 'hooks install', root, currentHooksPath: current, wouldSet: leaves, takeover: true, foreign: state.foreign, plan, filesWritten: false });
       return EXIT.FAIL;
     }
     emit(
@@ -258,14 +322,20 @@ async function installHooks(root, flags) {
 
   if (!mode.apply) {
     if (isJson(flags)) {
-      emitJson({ ok: true, command: 'hooks install', root, dryRun: true, currentHooksPath: current, wouldSet: wants, plan, filesWritten: false });
+      // `leaves`, not `wants`. A plan that would remove the last shim also un-routes
+      // git, and a payload promising to set a directory the command is about to unset
+      // is the same lie in a shape a machine reads.
+      emitJson({ ok: true, command: 'hooks install', root, dryRun: true, currentHooksPath: current, wouldSet: leaves, plan, filesWritten: false });
       return EXIT.OK;
     }
     emit(
       renderPlan(
         root,
         current,
-        wants,
+        // `leaves`, for the same reason the `--json` payload uses it: this plan says
+        // REMOVED beside the last shim, and a reader of it is entitled to read that
+        // the routing is going too, rather than being told it is unchanged.
+        leaves,
         pathAction,
         plan,
         mode.dryRun
@@ -281,7 +351,7 @@ async function installHooks(root, flags) {
   await mkdir(join(root, HOOKS_DIR), { recursive: true });
   for (const event of wanted) {
     const path = join(root, fileFor(event));
-    await writeFile(path, renderShim(event));
+    await writeFile(path, renderShim(event, { npm, version }));
     await chmod(path, 0o755);
   }
   for (const c of chained) {
@@ -289,7 +359,19 @@ async function installHooks(root, flags) {
     await writeFile(path, renderChainedShim(c.event, c.target));
     await chmod(path, 0o755);
   }
-  await exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
+  for (const h of obsolete) {
+    await rm(join(root, fileFor(h.event)));
+  }
+
+  // `core.hooksPath` tells git to read ONE directory for EVERY event, so leaving it
+  // pointing at a directory of no shims stops the repository's own hooks - the ones in
+  // `.git/hooks` that predate this tool - from running, silently. Unsetting it is the
+  // only way back, and this is the only place that knows the last shim just left.
+  if (routed) {
+    await exec('git', ['config', HOOKS_PATH_KEY, wants], { cwd: root });
+  } else if (current === wants) {
+    await exec('git', ['config', '--unset', HOOKS_PATH_KEY], { cwd: root });
+  }
 
   const notes = [];
   const chainedEvents = new Set(chained.map((c) => c.event));
@@ -299,28 +381,62 @@ async function installHooks(root, flags) {
     // chained and genuinely stopped running. Saying "stopped running" about both would
     // be wrong about the first, and it would push an operator to restore a hook that is
     // already being run for them.
-    notes.push(
-      chainedEvents.has(f.event)
-        ? `chained ${f.event}: ${fileFor(f.event)} runs ${f.path} (${f.bytes} bytes), so it keeps running`
-        : `stopped running ${f.event} at ${f.path} (${f.bytes} bytes); the file is still on disk, untouched - declare it in ${MANIFEST_FILE} gates.commands to have the dispatcher run it`,
-    );
+    if (chainedEvents.has(f.event)) {
+      notes.push(
+        `chained ${f.event}: ${fileFor(f.event)} runs ${f.path} (${f.bytes} bytes), so it keeps running`,
+      );
+    } else if (leftRunning.some((c) => c.event === f.event)) {
+      // A third case, and the one that was misreported: a hook this tool could not chain
+      // because the shim would have had to run itself. Nothing overwrote it, so it still
+      // runs - which is the opposite of what the branch below says.
+      notes.push(
+        `${f.event} at ${f.path} (${f.bytes} bytes) is in this tool's own hooks directory, so it cannot be chained to itself and was left untouched; it keeps running`,
+      );
+    } else {
+      notes.push(
+        `stopped running ${f.event} at ${f.path} (${f.bytes} bytes); the file is still on disk, untouched - declare it in ${MANIFEST_FILE} gates.commands to have the dispatcher run it`,
+      );
+    }
   }
   if (state.foreign.length === 0 && takeover) {
     notes.push(`replaced an existing core.${HOOKS_PATH_KEY} (${current}); the old hooks are still on disk, untouched`);
   }
+  for (const h of obsolete) {
+    notes.push(
+      `removed ${fileFor(h.event)}: ${MANIFEST_FILE} declares no ${h.event} gate, so the shim enforced nothing and still replaced git's own hook`,
+    );
+  }
+  if (leaves === null && current !== null) {
+    notes.push(
+      `unset ${HOOKS_PATH_KEY}; git reads its hooks from .git/hooks again, so the repository's own hooks run`,
+    );
+  }
 
   if (isJson(flags)) {
-    emitJson({ ok: true, command: 'hooks install', root, hooksPath: wants, previousHooksPath: current, plan, filesWritten: true, notes });
+    emitJson({ ok: true, command: 'hooks install', root, hooksPath: leaves, previousHooksPath: current, plan, filesWritten: true, notes });
     return EXIT.OK;
   }
-  emit(renderPlan(root, current, wants, pathAction, plan, 'WROTE    shims and set core.hooksPath', manifest), { maxBytes: flags.maxBytes ?? 0 });
+  emit(
+    renderPlan(
+      root,
+      current,
+      leaves,
+      pathAction,
+      plan,
+      routed ? 'WROTE    shims and set core.hooksPath' : 'WROTE    no shims remain; core.hooksPath unset',
+      manifest,
+    ),
+    { maxBytes: flags.maxBytes ?? 0 },
+  );
   for (const n of notes) note(`note     ${n}`);
   note(`note     never committed or pushed (ADR-001); review, then commit yourself`);
   return EXIT.OK;
 }
 
+// `wants` is null when this install removes the last shim, and "null" is not what a
+  // reader should read in a plan that says REMOVED next to it.
 function renderPlan(root, current, wants, pathAction, plan, headline, manifest) {
-  const lines = [`repo     ${root}`, `${HOOKS_PATH_KEY.padEnd(15)} ${pathAction}  ${current ?? '(unset)'} -> ${wants}`, ''];
+  const lines = [`repo     ${root}`, `${HOOKS_PATH_KEY.padEnd(15)} ${pathAction}  ${current ?? '(unset)'} -> ${wants ?? '(unset)'}`, ''];
   for (const p of plan) lines.push(`${p.action.toUpperCase().padEnd(9)} ${p.file}${p.note ? `   (${p.note})` : ''}`);
   lines.push('', headline);
   lines.push(`gates    preCommit = ${describeGates(manifest, 'preCommit')}`);

package/src/commands/index.mjs

@@ -15,6 +15,7 @@ import {
   briefCommand as skillsBrief,
   showCommand as skillsShow,
   whyCommand as skillsWhy,
+  evalCommand as skillsEval,
 } from './skills.mjs';
 import { syncCommand, checkCommand } from './sync.mjs';
 import { initCommand } from './init.mjs';
@@ -44,6 +45,50 @@ const GROUPS = new Map([
   ['hooks', 'status'],
 ]);
 
+/**
+ * Every command this binary dispatches, in one place.
+ *
+ * It was a literal inside `dispatch`, which is why `help` and the CLI could disagree:
+ * nothing could enumerate the real list, so `--help` was a hand-maintained template and
+ * three working commands (`graph lint`, `hooks status`, `hooks run`) were never written
+ * into it. A list that cannot be read cannot be checked, and the reader of `--help` is
+ * an agent choosing a command — the one consumer with no way to discover the omission
+ * except by guessing.
+ *
+ * Module scope so `test/cli.test.mjs` can assert help against it. Module scope is also
+ * just correct: nothing in the map depends on the call.
+ */
+const IMPLEMENTED = {
+  doctor: runDoctor,
+  'graph lint': lintCommand,
+  'skills index': skillsIndex,
+  'skills find': skillsFind,
+  'skills brief': skillsBrief,
+  'skills show': skillsShow,
+  'skills why': skillsWhy,
+  'skills eval': skillsEval,
+  'skills install': installCommand,
+  'rules list': rulesList,
+  'rules show': rulesShow,
+  'rules why': rulesWhy,
+  sync: syncCommand,
+  check: checkCommand,
+  init: initCommand,
+  ci: ciCommand,
+  'hooks install': (args, flags) => hooksCommand('install', args, flags),
+  'hooks status': (args, flags) => hooksCommand('status', args, flags),
+  'hooks run': (args, flags) => hooksCommand('run', args, flags),
+  compare: compareCommand,
+  upgrade: upgradeCommand,
+  mcp: mcpCommand,
+};
+
+/**
+ * The dispatchable command paths, sorted. The authoritative answer to "what can this
+ * binary do", as opposed to the answer `--help` gives.
+ */
+export const COMMANDS = Object.keys(IMPLEMENTED).sort();
+
 export async function dispatch(argv) {
   const { flags, positional } = parseOrExit(argv);
 
@@ -76,29 +121,6 @@ export async function dispatch(argv) {
     );
   }
   const args = positional.slice(offset);
-  const IMPLEMENTED = {
-    doctor: runDoctor,
-    'graph lint': lintCommand,
-    'skills index': skillsIndex,
-    'skills find': skillsFind,
-    'skills brief': skillsBrief,
-    'skills show': skillsShow,
-    'skills why': skillsWhy,
-    'skills install': installCommand,
-    'rules list': rulesList,
-    'rules show': rulesShow,
-    'rules why': rulesWhy,
-    sync: syncCommand,
-    check: checkCommand,
-    init: initCommand,
-    ci: ciCommand,
-    'hooks install': (args, flags) => hooksCommand('install', args, flags),
-    'hooks status': (args, flags) => hooksCommand('status', args, flags),
-    'hooks run': (args, flags) => hooksCommand('run', args, flags),
-    compare: compareCommand,
-    upgrade: upgradeCommand,
-    mcp: mcpCommand,
-  };
   const run = IMPLEMENTED[path];
   if (run) return run(args, flags);
   return fail(`unknown command \`${path}\``, EXIT.USAGE);
@@ -117,34 +139,20 @@ function commandPath(first, second) {
   if (second === undefined) return `${first} ${group}`;
   // Reject a second token that is not a subcommand of this group, rather than
   // silently routing `simt-dev skills nonsense` to the default subcommand.
+  //
+  // Read from IMPLEMENTED rather than from a second list. The list existed because
+  // there was no way to enumerate what dispatch could run — `IMPLEMENTED` was an
+  // object literal inside `dispatch()` — and a hand-kept copy of it had already
+  // drifted: it carried `doctor`, which `commandPath` can never match, because
+  // `doctor` is not a group and this branch is only reached when `GROUPS.has(first)`.
+  // Two lists of the same fact is the defect S15 was about in the help text.
   const key = `${first} ${second}`;
-  if (!STEPS.has(key) && !KNOWN_SUBS.has(key)) {
+  if (!STEPS.has(key) && !(key in IMPLEMENTED)) {
     return null;
   }
   return key;
 }
 
-/**
- * Subcommands implemented now, so they must not be rejected as unknown.
- * Implemented paths live here; declared-but-unimplemented ones live in STEPS.
- */
-const KNOWN_SUBS = new Set([
-  'doctor',
-  'graph lint',
-  'skills index',
-  'skills find',
-  'skills brief',
-  'skills show',
-  'skills why',
-  'skills install',
-  'rules list',
-  'rules show',
-  'rules why',
-  'hooks install',
-  'hooks status',
-  'hooks run',
-]);
-
 function parseOrExit(argv) {
   const parsed = parse(argv);
   if (!parsed.ok) return { flags: {}, positional: [] };