simt-dev 0.7.1 → 0.8.0

package/src/commands/ci.mjs

@@ -18,9 +18,8 @@
 // commands owns which file would be learning about ownership twice to learn nothing
 // new, and the next .github file would arrive with a third command to remember.
 
-import { mkdir, readFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { readFile } from 'node:fs/promises';
+import { applyPlan, change } from '../write/plan.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 
 import { EXIT, emit, emitJson, isJson, note, writeMode } from '../output/index.mjs';
@@ -39,7 +38,7 @@ import { commandRoot } from '../repo-root.mjs';
 function targets() {
   return [
     { key: 'workflow', file: WORKFLOW_FILE, plan: planWorkflow, render: () => renderWorkflow({ own: true }) },
-    { key: 'dependabot', file: DEPENDABOT_FILE, plan: planDependabot, render: (plan) => renderDependabot(plan.facts ?? [], { stack: plan.stack ?? [], own: true }) },
+    { key: 'dependabot', file: DEPENDABOT_FILE, plan: planDependabot, render: (plan) => renderDependabot(plan.facts ?? [], { stack: plan.stack ?? [], own: true, root: plan.root }) },
   ];
 }
 
@@ -153,19 +152,18 @@ export async function ciCommand(positional, flags) {
     return EXIT.OK;
   }
 
-  // Journaled so `undo` restores this run (R49).
-  const journal = [];
+  // Journaled so `undo` restores this run (R49). The renderer takes the plan because
+  // detection-driven content is a function of this repo's facts: a dependabot config
+  // rendered without them would watch nothing, which is the same silent-nothing the
+  // detection ruling exists to stop.
+  const changes = [];
   for (const { key, plan, render } of targets()) {
     const p = plans.find((x) => x.key === key);
     if (p.action === 'unchanged') continue;
-    await mkdir(dirname(p.path), { recursive: true });
-    // The renderer takes the plan because detection-driven content is a function of
-    // this repo's facts: a dependabot config rendered without them would watch
-    // nothing, which is the same silent-nothing the detection ruling exists to stop.
-    await journaledWriteFile(root, journal, p.path, render(p));
-    note(`wrote    ${p.file} (${p.action}; the template and this copy now agree)`);
+    changes.push(change({ path: p.path, before: await readBefore(p.path), after: render(p), owner: 'ci', reason: 'the template and this copy now agree' }));
   }
-  await commitJournal(root, 'ci', journal);
+  await applyPlan(root, changes, { mode, label: 'ci' });
+  for (const c of changes) note(`wrote    ${c.path.replace(`${root}/`, '')} (${c.action}; ${c.reason})`);
   if (isJson(flags)) {
     emitJson(
       {

package/src/commands/docs.mjs

@@ -0,0 +1,88 @@
+// `simt docs readme` — put the README's command list back in step with the spec.
+//
+// Shape copied from `ci` and `ignore`: the plan is printed first, nothing is written
+// without `--yes`, `--diff` shows the same plan as a unified diff, and `undo` restores
+// it. The rendering itself lives in `src/docs/commands.mjs` so a test can compare the
+// README against it without running this command.
+
+import { join } from 'node:path';
+
+import { EXIT, fail, present, writeMode } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
+import { diffField, emitDiffs, readBefore } from '../diff.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { BEGIN, END, README_FILE, renderCommandBlock, replaceBlock } from '../docs/commands.mjs';
+
+export async function docsCommand(sub, args, flags) {
+  if (sub !== 'readme') {
+    return fail(`unknown docs page \`${sub}\``, EXIT.USAGE, `run: ${CLI} docs readme`);
+  }
+  const root = commandRoot(flags);
+  const path = join(root, README_FILE);
+
+  let before;
+  try {
+    before = await readBefore(path);
+  } catch (error) {
+    return fail(
+      `${README_FILE} could not be read: ${error.message}`,
+      EXIT.FAIL,
+      `fix the file's permissions, then re-run: ${CLI} docs readme`,
+    );
+  }
+  if (before === null) {
+    return fail(`no ${README_FILE} in ${root}`, EXIT.FAIL, `run this where ${README_FILE} is`);
+  }
+
+  const after = replaceBlock(before, renderCommandBlock());
+  if (after === null) {
+    return fail(
+      `${README_FILE} carries no ${BEGIN} ... ${END} region`,
+      EXIT.FAIL,
+      `put the two marker lines where the command list belongs, then: ${CLI} docs readme --yes`,
+    );
+  }
+
+  const mode = writeMode(flags);
+  const action = after === before ? 'unchanged' : 'write';
+  const payload = {
+    ok: true,
+    command: 'docs',
+    page: 'readme',
+    root,
+    file: README_FILE,
+    action,
+    written: mode.apply && action === 'write',
+  };
+
+  if (action === 'unchanged') {
+    present(payload, () => `current  ${README_FILE}`, flags);
+    return EXIT.OK;
+  }
+
+  const diff = [{ path: README_FILE, before, after }];
+  if (!mode.apply) {
+    // A rehearsal says which flag it is waiting for, because "not written" is the same
+    // sentence for `--dry-run` and for a missing `--yes`, and the two have different fixes.
+    present(
+      { ...payload, ...diffField(diff, flags) },
+      () => `plan  ${README_FILE}: the command list follows the spec${mode.dryRun ? ' (--dry-run)' : ' (re-run with --yes to write)'}`,
+      flags,
+    );
+    emitDiffs(diff, flags);
+    return EXIT.OK;
+  }
+
+  await applyPlan(root, [change({ path, before, after, owner: 'docs readme', reason: 'the command list follows the spec' })], {
+    mode,
+    label: 'docs readme',
+  });
+  present(
+    { ...payload, ...diffField(diff, flags) },
+    () => `write  ${README_FILE}  (${Buffer.byteLength(after)} bytes)`,
+    flags,
+  );
+  emitDiffs(diff, flags);
+  return EXIT.OK;
+}

package/src/commands/gate.mjs

@@ -13,12 +13,15 @@ import { promisify } from 'node:util';
 
 import { EXIT, emit, emitJson, fail, isJson, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { detectTestRunner } from '../bench/mine.mjs';
+import { detectTestRunner } from '../testing/runners.mjs';
 import { compactOutput } from '../index/compact.mjs';
-import { readImportEdges, selectTests } from '../index/gate.mjs';
+import { coverage } from '../index/coverage.mjs';
+import { readImportEdges } from '../index/gate.mjs';
 import { langOf, packageOf } from '../index/store.mjs';
 import { localRel } from '../state.mjs';
 import { commandRoot } from '../repo-root.mjs';
+import { gitPaths } from '../sys/git.mjs';
+import { cmp } from '../util/sort.mjs';
 
 const exec = promisify(execFile);
 
@@ -65,7 +68,7 @@ export async function gateCommand(args, flags) {
   const files = new Set(listed.files);
   for (const file of changed) files.add(file);
   const edges = await readImportEdges(root, files);
-  const selected = selectTests(changed, edges);
+  const selected = coverage({ imports: edges }, changed);
   // Q40: the selection explains itself. `unmatched` names explicit paths the
   // tracked tree does not carry (untracked but present, so the run proceeds);
   // `graph` is `unresolved` when a language has edges but none of them reaches
@@ -199,8 +202,7 @@ async function tracked(root) {
   try {
     // `-z`: without it git C-quotes a non-ASCII path (`src/\303\274n...`) and
     // the reader's real filename never matches it (review 0003 Q39).
-    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root, maxBuffer: 16 << 20 });
-    return { files: stdout.split('\0').filter(Boolean) };
+    return { files: await gitPaths(root, ['ls-files']) };
   } catch (error) {
     return {
       error: fail(
@@ -214,9 +216,9 @@ async function tracked(root) {
 
 async function changedFiles(root) {
   try {
-    const { stdout } = await exec('git', ['diff', '--name-only', '-z', 'HEAD'], { cwd: root, maxBuffer: 8 << 20 });
-    const untracked = await exec('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd: root, maxBuffer: 8 << 20 });
-    return { files: [...new Set([...stdout.split('\0'), ...untracked.stdout.split('\0')].filter(Boolean))].sort() };
+    const files = await gitPaths(root, ['diff', '--name-only', 'HEAD'], { maxBuffer: 8 << 20 });
+    const untracked = await gitPaths(root, ['ls-files', '--others', '--exclude-standard'], { maxBuffer: 8 << 20 });
+    return { files: [...new Set([...files, ...untracked])].sort() };
   } catch (error) {
     return {
       error: fail(
@@ -228,8 +230,3 @@ async function changedFiles(root) {
   }
 }
 
-function cmp(a, b) {
-  if (a < b) return -1;
-  if (a > b) return 1;
-  return 0;
-}

package/src/commands/harness.mjs

@@ -100,13 +100,13 @@ async function scan(root, { mcp = false } = {}) {
   const rows = [];
   for (const s of SURFACES) {
     for (const dir of s.configDirs ?? []) {
-      if (await present(root, dir)) {
+      if (await isDirectory(root, dir)) {
         rows.push(row(dir, s.label, { id: s.id, verified: s.verified ?? null, readsAgentsMd: s.readsAgentsMd, rule: s.rule }));
       }
     }
   }
   for (const c of CANDIDATE_DIRS) {
-    if (await present(root, c.dir)) {
+    if (await isDirectory(root, c.dir)) {
       rows.push(row(c.dir, c.harness, { readsAgentsMd: c.readsAgentsMd ?? null, readsAgentsMdNote: c.readsAgentsMdNote ?? null, verified: c.verified ?? null }));
     }
   }
@@ -115,7 +115,7 @@ async function scan(root, { mcp = false } = {}) {
   return { root, rows };
 }
 
-async function present(root, dir) {
+async function isDirectory(root, dir) {
   try {
     return (await stat(join(root, dir))).isDirectory();
   } catch {

package/src/commands/help.mjs

@@ -4,6 +4,9 @@ import { parse, rawJsonFlag } from '../argv.mjs';
 import { CLI, MANIFEST_FILE, STATE_DIR } from '../name.mjs';
 import { SESSION_ENV } from '../agenthooks/policy.mjs';
 import { DEFAULT_DIRECTORIES, DEFAULT_TEMPLATE } from '../plan/template.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { readManifest } from '../projection/manifest.mjs';
+import { assertVersionPin } from '../package-version.mjs';
 
 const COMMANDS = `${CLI} init [path]            adopt or scaffold a repo into the ecosystem
                            (dry-run unless --yes; conflicts block without
@@ -242,6 +245,7 @@ ${CLI} pack publish [dir] [--yes]
                            publish an npm-sourced pack to the registry
                            (dry-run unless --yes; skips a version already live;
                            a git-sourced pack names the tag-and-push instead)
+${CLI} docs readme --yes      render the README command list from the spec
 ${CLI} mcp                    the read-only surface as MCP tools over stdio
                            (--list prints it without reading stdin; init, sync,
                            upgrade and the installers stay CLI-only by design)`;
@@ -294,6 +298,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --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)
+--no-agents             init: skip the agent files and the agent-hooks in one flag;
+                        the standalone agents / agent-hooks install commands remain
 --spec <name>           graph lint: also check every skill against a named
                         specification (one exists: agentskills)
 --user                  harness detect: also report the directories in your home
@@ -313,7 +319,9 @@ const FLAGS = `--json                 structured output (compact; one document,
 --harness <id>          bench run: adapter to invoke (claude, codex, gemini, opencode,
                          cursor, aider, gold, noop; default: gold);
                          agent-hook: which dialect to answer in (claude, cursor,
-                         codex, antigravity)
+                         codex, antigravity); agent-hooks / agents install: which
+                         reader to write (one, not all); init: narrows the agent
+                         files and the agent-hooks to one reader
 --model <id>            bench run: model identifier recorded and passed to the adapter
 --reps <n>              bench run: repetitions per task and arm (default: 3)
 --regrade <run>         bench run: re-grade a stored run from its archived agent patch
@@ -321,6 +329,8 @@ const FLAGS = `--json                 structured output (compact; one document,
 --test <cmd>            plan done / slice finish: the test command that closes the row
 --state <name>          plan done: target state (default: Complete)
 --type <name>           slice finish: the Conventional Commits type (default: feat)
+--id <name>             slice start: the slice id when -- starts one from a prompt
+                        (default: a slug of the prompt text)
 --ttl <seconds>         lease: how long a claim lasts (default: 3600)
 --level <name>          map: detail level (outline, names, signatures)
 --supersedes <spec>     decide: superseded ADR or ruling (ADR-NNN or ADR-NNN:<ruling>[:<kind>]; repeatable)
@@ -385,6 +395,13 @@ export async function help(argv, dispatched) {
     emitJson(SPEC.map(specRow));
     return 0;
   }
+  // The standard page is where a reader asks "what can this do, and where do I start".
+  // A repository that has not been adopted, or that pins a version this binary is not,
+  // has a prerequisite worth stating before the catalogue: no manifest means init is the
+  // first move, a stale pin means sync is the fix. Fully ready, the page stands on its
+  // own and the banner is nothing.
+  const banner = await prerequisiteBanner(flags, positional);
+  const bannerLines = banner === null ? [] : ['', banner, ''];
   // `--all` prints every command and every flag; the default page lists the core tier and
   // says where the rest is. A reader asking "what can this do" needs the shape, not 23 KB
   // of flag reference (review 0003 Q61).
@@ -394,7 +411,7 @@ export async function help(argv, dispatched) {
         'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
         '',
         `usage: ${CLI} <command> [args] [flags]`,
-        '',
+        ...bannerLines,
         'commands:',
         COMMANDS,
         '',
@@ -423,7 +440,7 @@ export async function help(argv, dispatched) {
       'simt-dev - shared agent rules, skills and gates for a repo ecosystem',
       '',
       `usage: ${CLI} <command> [args] [flags]`,
-      '',
+      ...bannerLines,
       'commands:',
       ...[...groups].map(([group, subs]) => `  ${CLI} ${group} <${subs.join('|')}>`),
       ...bare.map((row) => `  ${CLI} ${row.path.padEnd(8)} ${row.summary.length > 46 ? `${row.summary.slice(0, 43)}...` : row.summary}`),
@@ -435,6 +452,30 @@ export async function help(argv, dispatched) {
   return 0;
 }
 
+/**
+ * The prerequisite line for the standard help page, or null when the repository is fully
+ * ready. No manifest (or one that cannot be read) means the adoption has not happened and
+ * `init` is the first move; a manifest that pins a version the running binary is not means
+ * `sync` is the fix. These are the two states in which a reader opening help is about to
+ * run a command that would fail in a predictable way, so the page says so before it lists
+ * the commands.
+ */
+async function prerequisiteBanner(flags, positional) {
+  const root = commandRoot(flags, positional);
+  const { manifest, exists, error } = await readManifest(root);
+  if (!exists) {
+    return `prerequisite  no ${MANIFEST_FILE} here; run: ${CLI} init <path>`;
+  }
+  if (error !== null) {
+    return `prerequisite  ${MANIFEST_FILE} cannot be read (${error}); run: ${CLI} init <path>`;
+  }
+  const stale = assertVersionPin(manifest);
+  if (stale !== null) {
+    return `prerequisite  ${stale}; run: ${CLI} sync`;
+  }
+  return null;
+}
+
 async function version() {
   const { describeVersion } = await import('../package-version.mjs');
   return `${describeVersion()}\n`;

package/src/commands/hooks.mjs

@@ -14,7 +14,8 @@
 
 import { mkdir, readFile, readdir, realpath, rm, stat } from 'node:fs/promises';
 import { repoContext } from '../context.mjs';
-import { commitJournal, journaledGitConfig, journaledRemoveFile, journaledWriteFile } from '../journal.mjs';
+import { commitJournal, journaledGitConfig, journaledRemoveFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { invalidateCheckCache } from '../status.mjs';
 import { isAbsolute, join, relative } from 'node:path';
@@ -23,13 +24,13 @@ import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/i
 import { MANIFEST, readManifest } from '../projection/manifest.mjs';
 import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_DIR_LEGACY, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderEvidenceShim, renderShim } from '../hooks/shim.mjs';
 import { GATE_KEY, gateCount, readHooksPath, readHooksState, wantsShim } from '../compare/hooksstate.mjs';
-import { GATES } from '../hooks/gates.mjs';
-import { gateNames } from '../hooks/gates.mjs';
+import { gateNames, getGate } from '../hooks/gates.mjs';
 import { renderGateReport, runGates } from '../hooks/dispatcher.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
 import { commandRoot } from '../repo-root.mjs';
+import { readIfExists } from '../util/fs.mjs';
 
 export async function hooksCommand(sub, args, flags) {
   const root = commandRoot(flags, args);
@@ -374,26 +375,31 @@ export async function applyHooksInstall(root, planned, journal) {
   const wrote = [];
   const removed = [];
   await mkdir(join(root, HOOKS_DIR), { recursive: true });
+  const hookChanges = [];
   for (const event of wanted) {
     const path = join(root, fileFor(event));
-    await journaledWriteFile(root, journal, path, renderShim(event, { npm, manager, version }), { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: renderShim(event, { npm, manager, version }), owner: 'hooks install', reason: event, mode: 0o755 }));
     wrote.push(fileFor(event));
   }
   for (const c of chained) {
     const path = join(root, fileFor(c.event));
-    await journaledWriteFile(root, journal, path, renderChainedShim(c.event, c.target), { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: renderChainedShim(c.event, c.target), owner: 'hooks install', reason: c.event, mode: 0o755 }));
     wrote.push(fileFor(c.event));
   }
   for (const h of obsolete) {
-    await journaledRemoveFile(root, journal, join(root, fileFor(h.event)));
+    const obsoletePath = join(root, fileFor(h.event));
+    hookChanges.push(
+      change({ path: obsoletePath, kind: 'remove', before: await readBefore(obsoletePath), after: null, owner: 'hooks install', reason: h.event }),
+    );
     wrote.push(fileFor(h.event));
   }
   // After the chain loop, so a chained commit-msg cannot replace the claim check.
   if (evidenceSource) {
     const path = join(root, evidenceFile);
-    await journaledWriteFile(root, journal, path, evidenceSource, { mode: 0o755 });
+    hookChanges.push(change({ path, before: await readBefore(path), after: evidenceSource, owner: 'hooks install', reason: 'the evidence shim', mode: 0o755 }));
     wrote.push(evidenceFile);
   }
+  await applyPlan(root, hookChanges, { mode: { apply: true }, journal, commit: false });
   // `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
@@ -416,6 +422,7 @@ export async function applyHooksInstall(root, planned, journal) {
     await rm(join(root, HOOKS_DIR_LEGACY), { recursive: true });
   }
   return { wrote, removed };
+
 }
 
 /**
@@ -749,7 +756,7 @@ function describeGates(manifest, key) {
   const list = manifest?.gates?.[key];
   if (!Array.isArray(list) || list.length === 0) return '(none declared)';
   return list.map((name) => {
-    const gate = GATES[name];
+    const gate = getGate(name, manifest?.gates?.commands);
     return gate ? name : `${name} (UNKNOWN - the hook will fail)`;
   }).join(', ');
 }
@@ -818,7 +825,7 @@ async function hooksStatus(root, flags, ctx = repoContext(root)) {
     lines.push('', 'would run:');
     for (const key of ['preCommit', 'prePush']) {
       for (const name of manifest?.gates?.[key] ?? []) {
-        const known = GATES[name];
+        const known = getGate(name, commands);
         // A declared command wins for every kind, so the status must say so too —
         // printing "run script" for a gate the dispatcher will shell out to `./gradlew`
         // for is the same one-question-two-answers defect ADR-018 was written about.
@@ -837,7 +844,7 @@ async function hooksStatus(root, flags, ctx = repoContext(root)) {
     if (undeclared.length > 0) {
       lines.push('', `declared but never run: ${undeclared.join(', ')}`);
     }
-    const unknown = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])].filter((n) => !GATES[n]);
+    const unknown = [...(manifest?.gates?.preCommit ?? []), ...(manifest?.gates?.prePush ?? [])].filter((n) => !getGate(n, commands));
     if (unknown.length > 0) {
       lines.push('', `unknown gates (the hook will fail): ${unknown.join(', ')}`);
       lines.push(`known gates: ${gateNames().join(', ')}`);
@@ -869,8 +876,9 @@ function collectProblems({ exists, current, installed, manifest, foreign = [] })
   if (exists) {
     for (const key of ['preCommit', 'prePush']) {
       for (const name of manifest?.gates?.[key] ?? []) {
-        if (!GATES[name]) problems.push(`gate "${name}" in ${key} is not a known gate`);
-        else if (GATES[name].kind === 'command' && !manifest?.gates?.commands?.[name]) {
+        const gate = getGate(name, manifest?.gates?.commands);
+        if (!gate) problems.push(`gate "${name}" in ${key} is not a known gate`);
+        else if (gate.kind === 'command' && !manifest?.gates?.commands?.[name]) {
           problems.push(`gate "${name}" in ${key} is a command gate with no declared command; the hook will fail`);
         }
       }
@@ -878,11 +886,3 @@ function collectProblems({ exists, current, installed, manifest, foreign = [] })
   }
   return problems;
 }
-
-async function readIfExists(path) {
-  try {
-    return await readFile(path, 'utf8');
-  } catch {
-    return null;
-  }
-}

package/src/commands/ignore.mjs

@@ -11,7 +11,7 @@ import { join } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { CLAUDE_SETTINGS, IGNORE_FILE, parseIgnoreList, planIgnore } from '../ignore.mjs';
 import { commandRoot } from '../repo-root.mjs';
@@ -125,12 +125,16 @@ export async function ignoreCommand(args, flags) {
 
   // Journaled so `undo` restores this run (R49). Every note writes to stderr,
   // so the `--json` document remains the only bytes on stdout.
-  const journal = [];
-  for (const t of changed) {
-    await journaledWriteFile(root, journal, join(root, t.path), t.after);
-    note(`wrote    ${t.path} (${t.action})`);
-  }
-  await commitJournal(root, 'ignore', journal);
+  await applyPlan(
+    root,
+    await Promise.all(
+      changed.map(async (t) =>
+        change({ path: t.path, before: await readBefore(join(root, t.path)), after: t.after, owner: 'ignore', reason: t.action }),
+      ),
+    ),
+    { mode: { apply: true }, label: 'ignore' },
+  );
+  for (const t of changed) note(`wrote    ${t.path} (${t.action})`);
 
   if (isJson(flags)) emitJson(payload(true));
   // After the report: the report says what, the diff shows it (R50).

package/src/commands/impact.mjs

@@ -4,10 +4,8 @@
 // the file, the CODEOWNERS line, and — when a workspace is configured —
 // another repository that references a contract this change touches.
 
-import { execFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { basename, join, resolve } from 'node:path';
-import { promisify } from 'node:util';
 
 import { EXIT, fail, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
@@ -22,12 +20,12 @@ import {
   ownersOf,
   relatedContracts,
 } from '../index/impact.mjs';
-import { decisionHits, scopeHits, sortHits, sourceRoots } from '../index/govern.mjs';
+import { governs, sourceRoots } from '../index/govern.mjs';
 import { decisionRecords, ruleScopes } from './why.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
 import { commandRoot } from '../repo-root.mjs';
+import { gitPaths } from '../sys/git.mjs';
 
-const exec = promisify(execFile);
 const TEXT_EXT = new Set(['js', 'mjs', 'cjs', 'jsx', 'ts', 'tsx', 'json', 'yaml', 'yml', 'md', 'toml', 'xml', 'py', 'go', 'kt', 'java', 'rs']);
 const READ_CAP = 256 * 1024;
 const FILE_CAP = 2000;
@@ -88,8 +86,7 @@ async function governance(root, file, files, commands) {
   const records = await decisionRecords(root);
   const rules = await ruleScopes(root);
   const ctx = { files, commands: new Set(commands), roots: sourceRoots(files) };
-  const { hits } = decisionHits(records, file, ctx);
-  return sortHits([...hits, ...scopeHits(file, { rules })]);
+  return governs(file, { records, rules, ctx });
 }
 
 async function readOwners(root, file) {
@@ -190,8 +187,7 @@ async function tracked(root) {
   try {
     // `-z`: without it git C-quotes a non-ASCII path and the reader's real
     // filename never matches it (review 0003 Q39).
-    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root, maxBuffer: 16 << 20 });
-    return { files: stdout.split('\0').filter(Boolean) };
+    return { files: await gitPaths(root, ['ls-files']) };
   } catch (error) {
     return {
       error: fail(

package/src/commands/index.mjs

@@ -1,6 +1,6 @@
 // Command registry and dispatch.
 //
-// Every command named in docs/plans/0002-simt-dev-cli.md section 5 is registered
+// Every command named in docs/research/0002-simt-dev-cli.md section 5 is registered
 // here from day one. A command that is declared but not yet implemented exits
 // UNSUPPORTED with a pointer to its implementation step; it never silently
 // succeeds. An agent that calls `simt compare` on an unreleased build must get a
@@ -21,9 +21,10 @@ import {
   jsonFailMode,
   jsonIndentDefault,
   maxBytesLimit,
+  withOutputState,
 } from '../output/index.mjs';
 import { help } from './help.mjs';
-import { GROUP_DEFAULTS, SPEC, SPEC_PATHS } from './spec.mjs';
+import { ALIASES, GROUP_DEFAULTS, SPEC, SPEC_PATHS } from './spec.mjs';
 import { parse, rawJsonFlag } from '../argv.mjs';
 import { CLI } from '../name.mjs';
 import { packageVersion } from '../package-version.mjs';
@@ -44,7 +45,10 @@ const DECLARED = new Map(SPEC.map((row) => [row.path, new Set(row.flags ?? [])])
 /** path -> the values a flag of that path accepts, where the set is closed. */
 const VALUES = new Map(SPEC.map((row) => [row.path, row.values ?? {}]));
 
-const GLOBAL_FLAGS = new Set(['root', 'json', 'pretty', 'help', 'version', 'maxBytes']);
+// `dashdash` is the parser's record that `--` appeared, not a flag any reader typed:
+// it is an envelope fact like `root`, so the per-command declaration check skips it
+// and lets the one command that reads it (slice start) act on it.
+export const GLOBAL_FLAGS = new Set(['root', 'json', 'pretty', 'help', 'version', 'maxBytes', 'dashdash']);
 
 /**
  * Every command this binary dispatches, in one place.
@@ -149,6 +153,12 @@ export const IMPLEMENTED = {
   // Plan 0003 R54. A bare command: paths claim, no paths list, so the argument itself
   // is the mode and there is no group to resolve.
   lease: async () => (await import('./lease.mjs')).leaseCommand,
+  // Review 0003 Q60. The README's command list is the last copy of the command table
+  // the spec owns; the renderer lives in src/docs so a test can hold the file to it.
+  'docs readme': async () => {
+    const { docsCommand } = await import('./docs.mjs');
+    return (args, flags) => docsCommand('readme', args, flags);
+  },
   distill: async () => (await import('./distill.mjs')).distillCommand,
   // R25 machinery needs the runnable command names for Affects command tokens,
   // same wiring `why` and `impact` get through their lambdas.
@@ -245,8 +255,25 @@ export const IMPLEMENTED = {
   },
 };
 
+/**
+ * Resolve one command path to its handler, its declared flags and its closed value sets.
+ *
+ * The library surface needs the same answer `dispatch` gets and must not build a second
+ * registry to get it: a command reachable from the CLI and absent from `run` is the drift
+ * `test/spec.test.mjs` exists to catch, and it would be invisible here (review 0003 Q63).
+ */
+export async function resolveCommand(path) {
+  const load = IMPLEMENTED[path];
+  if (!load) return null;
+  return {
+    run: await load(),
+    declared: DECLARED.get(path) ?? new Set(),
+    values: VALUES.get(path) ?? {},
+  };
+}
+
 /** The release that turns the tolerated flag into a usage error (review 0003 Q62). */
-export const DEPRECATION_RELEASE = '0.8.0';
+export const DEPRECATION_RELEASE = '0.9.0';
 
 /**
  * Whether a tolerance that ends at `removedIn` has ended, comparing the way versions
@@ -275,7 +302,18 @@ export function refusesAt(removedIn, version) {
  */
 export const COMMANDS = SPEC_PATHS;
 
+/**
+ * Dispatch one argv.
+ *
+ * The state is per call: an MCP server and the tests both dispatch more than once in a
+ * process, and a shared envelope let one run's ceiling, notices and command path land in
+ * another run's document (review 0003 Q63/Q65).
+ */
 export async function dispatch(argv) {
+  return withOutputState(() => dispatchInState(argv));
+}
+
+async function dispatchInState(argv) {
   const { flags, positional, parseError } = parseOrExit(argv);
   // One run, one set of notices: a process can dispatch repeatedly (review 0003 Q62).
   clearWarnings();
@@ -383,10 +421,14 @@ export async function dispatch(argv) {
  * Normalise argv into a registry key, or null when unrecognised.
  * A group with an omitted subcommand resolves to that group's default, so
  * `simt skills` is `simt skills index`.
+ *
+ * An alias resolves here rather than as a second registry entry: the spec path stays the
+ * one dispatch key, so an alias cannot load a different handler or escape the flag
+ * declaration the path carries (review 0003 Q81).
  */
 function commandPath(first, second) {
   if (first === undefined) return null;
-  if (!GROUPS.has(first)) return first;
+  if (!GROUPS.has(first)) return ALIASES.get(first) ?? first;
 
   const group = GROUPS.get(first);
   if (second === undefined) return `${first} ${group}`;
@@ -400,10 +442,8 @@ function commandPath(first, second) {
   // `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 (!(key in IMPLEMENTED)) {
-    return null;
-  }
-  return key;
+  if (key in IMPLEMENTED) return key;
+  return ALIASES.get(key) ?? null;
 }
 
 function parseOrExit(argv) {