simt-dev 0.2.2 → 0.3.1

package/src/commands/hooks.mjs

@@ -19,7 +19,7 @@ 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 { EVENTS, HOOKS_DIR, 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 { knownGates } from '../hooks/resolve.mjs';
@@ -222,11 +222,29 @@ async function installHooks(root, flags) {
     (i) => i.present && i.ours && !wanted.includes(i.event) && !chained.some((c) => c.event === i.event),
   );
 
+  // The claim check is not one of EVENTS. Those shims do not forward git's
+  // arguments, and commit-msg's only argument is the message. It is installed
+  // when the repository sets gates.evidence, and removed when that setting goes,
+  // because a shim that stays after the setting left still replaces git's own hook.
+  const evidenceDeclared = manifest?.gates?.evidence === 'warn' || manifest?.gates?.evidence === 'block';
+  const evidenceFile = fileFor('commit-msg');
+  const evidenceExisting = await readIfExists(join(root, evidenceFile));
+  const evidenceSource = evidenceDeclared ? renderEvidenceShim({ npm, version }) : null;
+  const evidenceOurs = evidenceExisting !== null && evidenceExisting.includes(SHIM_MARKER);
+  if (!evidenceDeclared && evidenceOurs) obsolete.push({ event: 'commit-msg' });
+  // A foreign commit-msg would otherwise be chained onto the same path. The chain
+  // is written after this shim, so it would replace the claim check and the check
+  // would never run. The repository's hook stays on disk and the note says it stopped.
+  if (evidenceDeclared) {
+    const at = chained.findIndex((c) => c.event === 'commit-msg');
+    if (at !== -1) chained.splice(at, 1);
+  }
+
   // 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 (wanted.length === 0 && obsolete.length === 0 && !evidenceDeclared) {
     if (isJson(flags)) {
       emitJson({ ok: false, command: 'hooks install', root, nothingToEnforce: true, filesWritten: false });
       return EXIT.FAIL;
@@ -276,10 +294,20 @@ async function installHooks(root, flags) {
       // 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`,
+      note:
+        h.event === 'commit-msg'
+          ? `gates.evidence is unset, so the claim check stopped`
+          : `no gate for ${h.event} in ${MANIFEST_FILE}; the shim enforced nothing`,
+    });
+  }
+  if (evidenceSource) {
+    plan.push({
+      file: evidenceFile,
+      action: evidenceExisting === evidenceSource ? 'unchanged' : evidenceExisting === null ? 'created' : 'updated',
+      note: 'commit-msg checks a verification claim against the ledger',
     });
   }
-  const routed = wanted.length > 0 || chained.length > 0;
+  const routed = wanted.length > 0 || chained.length > 0 || evidenceDeclared;
 
   // 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`
@@ -362,6 +390,12 @@ async function installHooks(root, flags) {
   for (const h of obsolete) {
     await rm(join(root, 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 writeFile(path, evidenceSource);
+    await chmod(path, 0o755);
+  }
 
   // `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
@@ -385,6 +419,10 @@ async function installHooks(root, flags) {
       notes.push(
         `chained ${f.event}: ${fileFor(f.event)} runs ${f.path} (${f.bytes} bytes), so it keeps running`,
       );
+    } else if (f.event === 'commit-msg' && evidenceDeclared) {
+      notes.push(
+        `stopped running commit-msg at ${f.path} (${f.bytes} bytes); the claim check replaced it, and the file is still on disk, untouched`,
+      );
     } 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
@@ -403,7 +441,9 @@ async function installHooks(root, flags) {
   }
   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`,
+      h.event === 'commit-msg'
+        ? `removed ${fileFor(h.event)}: ${MANIFEST_FILE} no longer sets gates.evidence, so the claim check stopped replacing git's own commit-msg`
+        : `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) {

package/src/commands/impact.mjs

@@ -0,0 +1,205 @@
+// `simt impact` reports who a file or an export reaches (R23, ADR-096).
+//
+// Importers, the tests that cover them, the decisions and rules that govern
+// 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, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { discover } from '../compare/discover.mjs';
+import { extract } from '../index/extract.mjs';
+import { importEdges, readEntries } from '../index/gate.mjs';
+import {
+  contractReferences,
+  dependents,
+  filesExporting,
+  isContractPath,
+  ownersOf,
+  relatedContracts,
+} from '../index/impact.mjs';
+import { decisionHits, scopeHits, sortHits, sourceRoots } from '../index/govern.mjs';
+import { decisionRecords, ruleScopes } from './why.mjs';
+import { resolveWorkspace } from '../workspace.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;
+
+export async function impactCommand(args, flags, commands = []) {
+  if (args.length > 1) return fail(`unknown impact argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const target = args[0];
+  if (!target) return fail(`a file or a symbol is required`, EXIT.USAGE, `run: ${CLI} impact <file|symbol>`);
+  const root = flags.root ?? process.cwd();
+  const listed = await tracked(root);
+  if (listed.error) return listed.error;
+  const files = new Set(listed.files);
+  const entries = await readEntries(root, files);
+  const imports = importEdges(entries);
+  const symbols = entries.flatMap((entry) => (entry.lang ? extract(entry.path, entry.text, entry.lang).symbols : []));
+  const resolved = resolveTarget(target, files, symbols);
+  if (resolved.error) return resolved.error;
+  const reach = dependents(resolved.file, imports);
+  const governs = await governance(root, resolved.file, files, commands);
+  const owners = await readOwners(root, resolved.file);
+  const contracts = await contractsFor(root, listed.files, resolved, reach.importers);
+  const consumers = await consumersFor(root, flags, basename(root), contracts);
+  const truncated = reach.truncated || consumers.truncated;
+  const payload = {
+    ok: true,
+    command: 'impact',
+    root,
+    file: resolved.file,
+    symbol: resolved.symbol,
+    importers: reach.importers,
+    tests: reach.tests,
+    governs,
+    owners,
+    consumers: consumers.references,
+    truncated,
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(render(payload), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function resolveTarget(target, files, symbols) {
+  if (files.has(target)) return { file: target, symbol: '' };
+  const exported = filesExporting(target, symbols);
+  if (exported.length === 1) return { file: exported[0], symbol: target };
+  if (exported.length === 0) {
+    return { error: fail(`not a file or an export: ${target}`, EXIT.USAGE, `pass a path git tracks, or the name of one export`) };
+  }
+  return {
+    error: fail(
+      `${target} is exported by ${exported.join(', ')}`,
+      EXIT.USAGE,
+      `pass the path of the export you mean`,
+    ),
+  };
+}
+
+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 })]);
+}
+
+async function readOwners(root, file) {
+  for (const path of ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']) {
+    try {
+      return ownersOf(await readFile(join(root, path), 'utf8'), file);
+    } catch {
+      // The next location may hold the file. GitHub reads the first that exists.
+    }
+  }
+  return [];
+}
+
+async function contractsFor(root, files, resolved, importers) {
+  const contracts = [];
+  for (const path of files) {
+    if (!isContractPath(path) && !mightSniff(path)) continue;
+    let text = '';
+    try {
+      text = await readFile(join(root, path), 'utf8');
+    } catch {
+      continue;
+    }
+    if (!isContractPath(path) && !sniffs(text)) continue;
+    contracts.push({ path, text });
+  }
+  return relatedContracts(contracts, { file: resolved.file, symbol: resolved.symbol, importers });
+}
+
+async function consumersFor(root, flags, repoName, contracts) {
+  if (contracts.length === 0) return { references: [], truncated: false };
+  const workspace = await resolveWorkspace(flags);
+  if (!workspace.root) return { references: [], truncated: false };
+  const found = await discover(workspace.root);
+  if (found.shape !== 'workspace') return { references: [], truncated: false };
+  const here = resolve(root);
+  const files = [];
+  let truncated = false;
+  for (const repo of found.repos) {
+    if (resolve(repo) === here) continue;
+    const listed = await tracked(repo);
+    if (listed.error) continue;
+    const name = basename(repo);
+    let read = 0;
+    for (const path of listed.files) {
+      if (!textExt(path)) continue;
+      if (read >= FILE_CAP) {
+        truncated = true;
+        break;
+      }
+      read += 1;
+      try {
+        const text = await readFile(join(repo, path), 'utf8');
+        if (text.length > READ_CAP) continue;
+        files.push({ repo: name, path, text });
+      } catch {
+        // A file git lists and the worktree no longer has is not a consumer.
+      }
+    }
+  }
+  const refs = contractReferences(contracts, repoName, files);
+  return { references: refs.references, truncated: truncated || refs.truncated };
+}
+
+function render(payload) {
+  const lines = [`file      ${payload.file}`];
+  if (payload.symbol) lines.push(`symbol    ${payload.symbol}`);
+  for (const path of payload.importers) lines.push(`importer  ${path}`);
+  for (const path of payload.tests) lines.push(`test      ${path}`);
+  for (const hit of payload.governs) lines.push(`${hit.kind.padEnd(10)}${hit.id}  ${hit.detail}`);
+  for (const owner of payload.owners) lines.push(`owner     ${owner}`);
+  for (const consumer of payload.consumers) lines.push(`consumer  ${consumer.repo}/${consumer.path}  ${consumer.contract}`);
+  if (payload.truncated) lines.push('truncated  1');
+  return lines.join('\n');
+}
+
+function mightSniff(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  const ext = base.slice(dot + 1).toLowerCase();
+  return ext === 'json' || ext === 'yaml' || ext === 'yml';
+}
+
+function sniffs(text) {
+  const head = text.slice(0, 500);
+  return head.includes('"openapi"') || head.includes('"$schema"');
+}
+
+function textExt(file) {
+  const base = file.slice(file.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return false;
+  return TEXT_EXT.has(base.slice(dot + 1).toLowerCase());
+}
+
+async function tracked(root) {
+  try {
+    const { stdout } = await exec('git', ['ls-files'], { cwd: root, maxBuffer: 16 << 20 });
+    return { files: stdout.split('\n').filter(Boolean) };
+  } catch (error) {
+    return {
+      error: fail(
+        `could not read the tree (${error.message})`,
+        EXIT.UNSUPPORTED,
+        'run this inside a git repository',
+      ),
+    };
+  }
+}

package/src/commands/index.mjs

@@ -29,13 +29,30 @@ import { syncCommand, checkCommand } from './sync.mjs';
 import { initCommand } from './init.mjs';
 import { ciCommand } from './ci.mjs';
 import { hooksCommand } from './hooks.mjs';
+import { agentHookCommand, agentHooksCommand } from './agenthook.mjs';
 import { compareCommand } from './compare.mjs';
 import { upgradeCommand } from './upgrade.mjs';
 import { mcpCommand } from './mcp.mjs';
 import { installCommand } from './skillsinstall.mjs';
 import { listCommand as rulesList, showCommand as rulesShow, whyCommand as rulesWhy } from './rules.mjs';
 import { tokensCommand } from './tokens.mjs';
-import { harnessCommand } from './harness.mjs';
+import { harnessCommand, harnessLoadersCommand } from './harness.mjs';
+import {
+  benchMineCommand,
+  benchRunCommand,
+  benchReportCommand,
+  benchAblateCommand,
+  benchProbesCommand,
+} from './bench.mjs';
+import { planCommand } from './plan.mjs';
+import { sharedPlanCommand, sharedInstallCommand, sharedWarning } from './shared.mjs';
+import { evidenceCommand } from './evidence.mjs';
+import { indexCommand } from './repoindex.mjs';
+import { mapCommand } from './map.mjs';
+import { testsCommand } from './tests.mjs';
+import { whyCommand } from './why.mjs';
+import { gateCommand } from './gate.mjs';
+import { impactCommand } from './impact.mjs';
 import { parse } from '../argv.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { resolveWorkspace } from '../workspace.mjs';
@@ -53,7 +70,15 @@ const GROUPS = new Map([
   ['graph', 'lint'],
   ['rules', 'list'],
   ['hooks', 'status'],
+  ['plan', 'status'],
+  ['agent-hooks', 'status'],
   ['harness', 'detect'],
+  ['bench', 'mine'],
+  // ADR-084. `shared` is the one group whose default writes nothing, and it is `plan` for
+  // the same reason `skills`'s is `index`: the read answers "what would this do, and
+  // where", and `install` — the subcommand that touches a reader's home directory — is the
+  // one that needs `--yes` before it does anything.
+  ['shared', 'plan'],
 ]);
 
 /**
@@ -84,14 +109,36 @@ export const IMPLEMENTED = {
   'rules why': rulesWhy,
   sync: syncCommand,
   check: checkCommand,
+  'plan status': (args, flags) => planCommand('status', args, flags),
+  'plan next': (args, flags) => planCommand('next', args, flags),
+  'plan done': (args, flags) => planCommand('done', args, flags),
+  'shared plan': sharedPlanCommand,
+  'shared install': sharedInstallCommand,
+  evidence: evidenceCommand,
+  index: indexCommand,
+  map: mapCommand,
+  tests: testsCommand,
+  why: (args, flags) => whyCommand(args, flags, COMMANDS),
+  gate: gateCommand,
+  impact: (args, flags) => impactCommand(args, flags, COMMANDS),
+  'evidence check': (args, flags) => evidenceCommand(['check', ...args], flags),
   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),
+  'agent-hook': agentHookCommand,
+  'agent-hooks install': (args, flags) => agentHooksCommand('install', args, flags),
+  'agent-hooks status': (args, flags) => agentHooksCommand('status', args, flags),
   compare: compareCommand,
   tokens: tokensCommand,
   'harness detect': harnessCommand,
+  'harness loaders': harnessLoadersCommand,
+  'bench mine': benchMineCommand,
+  'bench run': benchRunCommand,
+  'bench report': benchReportCommand,
+  'bench ablate': benchAblateCommand,
+  'bench probes': benchProbesCommand,
   upgrade: upgradeCommand,
   mcp: mcpCommand,
 };
@@ -196,6 +243,13 @@ async function runDoctor(positional, flags) {
   // answer confidently wrong, so the answer is reported rather than inferred
   // (ADR-014).
   const ws = await resolveWorkspace(flags);
+  // The shared file this repository hands rules to (ADR-084). Asked here and nowhere else
+  // because it is the one thing about a repository that is true of the reader's machine
+  // rather than of the tree: `check` must not read `$HOME`, so `doctor` is the only command
+  // that can notice a region that dropped rules into a file nobody has. Reported, never
+  // blocking — a stale copy costs a reader some of their rules, which is worth knowing and
+  // is not this repository's gate failing.
+  const shared = await sharedWarning(root, result.manifest ?? null, flags);
 
   // Under `--json` the document is the whole report, so it has to carry both
   // failures the text path reports AND the workspace answer the text path prints.
@@ -230,6 +284,7 @@ async function runDoctor(positional, flags) {
         detail: ws.detail,
         error: ws.error ?? null,
       },
+      shared,
       ...(failure ?? {}),
     });
     return code;
@@ -252,6 +307,10 @@ async function runDoctor(positional, flags) {
       }`,
       `manifest ${result.manifest ? (result.manifest.error ?? result.manifest.id ?? 'present') : '(absent)'}`,
       `workspace ${ws.root ?? '(none)'}  (${ws.source}: ${ws.detail})`,
+      // Printed only when this repository handed rules to a workspace copy: a line in
+      // every `doctor` is a line in every reader's terminal, and the reader who has
+      // nothing to install is not served by one (ADR-084).
+      ...(shared.declared ? [`shared    ${shared.state}  ${shared.detail}`] : []),
     ].join('\n'),
     { maxBytes: flags.maxBytes ?? 0 },
   );

package/src/commands/map.mjs

@@ -0,0 +1,91 @@
+// `simt map` ranks the files a task is most likely to touch (R22, ADR-091).
+// The cache is read, and rebuilt once when it is empty, because a map of no
+// files is not an answer. The rebuild writes the gitignored index, which is
+// the same cache `simt index` writes.
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { readEdges, readFiles, readSymbols, reindex } from '../index/store.mjs';
+import { DEFAULT_BUDGET, formatRecall, measureRecall, rankFiles, renderMap } from '../index/map.mjs';
+
+const LEVELS = new Set(['outline', 'names', 'signatures']);
+
+export async function mapCommand(args, flags) {
+  if (args.length > 0) return fail(`unknown map argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} map`);
+  const root = flags.root ?? process.cwd();
+  if (flags.recall === true) return recall(root, flags);
+  const level = flags.level ?? 'outline';
+  if (!LEVELS.has(level)) {
+    return fail(`unknown level ${level}`, EXIT.USAGE, 'use outline, names or signatures');
+  }
+  const budget = flags.budget === undefined ? DEFAULT_BUDGET : Number(flags.budget);
+  if (!Number.isInteger(budget) || budget < 0) {
+    return fail(`budget must be a non-negative integer`, EXIT.USAGE, `run: ${CLI} map --budget 2048`);
+  }
+  const loaded = await loadGraph(root);
+  if (loaded.error) return loaded.error;
+  const task = typeof flags.task === 'string' ? flags.task : '';
+  const ranked = rankFiles({ ...loaded, task });
+  const rendered = renderMap(ranked, loaded.symbols, { level, budget });
+  const payload = {
+    ok: true,
+    command: 'map',
+    root,
+    level,
+    budget,
+    shown: rendered.shown,
+    total: rendered.total,
+    truncated: rendered.truncated,
+    files: rendered.files,
+    text: rendered.text,
+  };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `level    ${level}`,
+    `shown    ${rendered.shown}`,
+    `total    ${rendered.total}`,
+    `budget   ${budget}`,
+  ];
+  if (rendered.text) lines.push(rendered.text);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function recall(root, flags) {
+  let result;
+  try {
+    result = await measureRecall(root);
+  } catch (error) {
+    return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
+  }
+  const payload = { ok: true, command: 'map', root, recall: result };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  emit(formatRecall(result), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function loadGraph(root) {
+  let files = await readFiles(root);
+  if (files.length === 0) {
+    try {
+      await reindex(root);
+    } catch (error) {
+      return {
+        error: fail(
+          `could not map this repository (${error.message})`,
+          EXIT.UNSUPPORTED,
+          'run this inside a git repository',
+        ),
+      };
+    }
+    files = await readFiles(root);
+  }
+  const [symbols, edges] = await Promise.all([readSymbols(root), readEdges(root)]);
+  return { files, symbols, edges };
+}

package/src/commands/plan.mjs

@@ -0,0 +1,99 @@
+import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.mjs';
+import { formatCounts, planDone, planNext, planStatus } from '../plan/index.mjs';
+import { CLI } from '../name.mjs';
+
+// Preview unless --yes, and --dry-run wins even then. A tracker row marked done
+// for a commit that was never written is a claim the next reader will believe.
+
+export async function planCommand(sub, args, flags) {
+  const root = flags.root ?? process.cwd();
+  if (sub === 'status') return runStatus(root, flags);
+  if (sub === 'next') return runNext(root, args[0] ?? null, flags);
+  if (sub === 'done') {
+    if (!args[0]) return fail('plan done needs a slice id', EXIT.USAGE, `run: ${CLI} plan next`);
+    return runDone(root, args[0], args[1] ?? null, flags);
+  }
+  if (!sub) {
+    return fail('plan needs a subcommand', EXIT.USAGE, `run: ${CLI} plan status  |  ${CLI} plan next  |  ${CLI} plan done <id>`);
+  }
+  return fail(`unknown plan subcommand ${sub}`, EXIT.USAGE, `run: ${CLI} plan status`);
+}
+
+async function runStatus(root, flags) {
+  const result = await planStatus(root);
+  if (result.error) return fail(result.error, EXIT.USAGE, result.remedy);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'plan status', ...result });
+    return EXIT.OK;
+  }
+  const lines = [`repo     ${root}`, `template ${result.template}`, `dirs     ${result.directories.join(', ')}`];
+  if (result.documents.length === 0) lines.push(`(no tracker in ${result.directories.join(' or ')})`);
+  for (const doc of result.documents) {
+    lines.push(`${doc.name}  slices=${doc.slices}  ${formatCounts(doc.counts, result.stateOrder)}`);
+  }
+  lines.push('', `total    ${formatCounts(result.totals, result.stateOrder) || '-'}`);
+  lines.push(`ready    ${result.ready}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function runNext(root, id, flags) {
+  const result = await planNext(root, id);
+  if (result.error) return fail(result.error, EXIT.USAGE, result.remedy);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'plan next', ...result });
+    return EXIT.OK;
+  }
+  if (!result.next) {
+    const lines = [`repo     ${root}`, result.reason];
+    if (result.blocked?.length) {
+      lines.push('', 'blocked:');
+      for (const row of result.blocked) {
+        const unknown = row.unknownDependencies.length ? `  unknown: ${row.unknownDependencies.join(', ')}` : '';
+        lines.push(`  ${row.id}  ${row.doc}  depends on: ${row.dependsOn || '(none)'}${unknown}`);
+      }
+    }
+    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const next = result.next;
+  const head = [
+    `repo     ${root}`,
+    `slice    ${next.id}  ${next.doc}`,
+    `state    ${next.state}`,
+    `depends  ${next.dependsOn || '(none)'}`,
+    `bytes    ${next.sectionBytes}`,
+    '',
+    next.section || '(no section for this id)',
+  ];
+  emit(head.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+async function runDone(root, id, sha, flags) {
+  const mode = writeMode(flags);
+  const result = await planDone(root, id, {
+    sha,
+    test: flags.test ?? null,
+    state: flags.state ?? null,
+    dryRun: !mode.apply,
+  });
+  if (result.error) return fail(result.error, EXIT.USAGE, result.remedy);
+  if (isJson(flags)) {
+    emitJson({ ok: true, command: 'plan done', ...result });
+    return EXIT.OK;
+  }
+  const lines = [`repo     ${root}`];
+  if (result.dryRun) {
+    lines.push(`dry-run  ${result.id}  ${result.doc}  line ${result.line}`);
+    lines.push(result.wouldChange ? `would    ${result.from} -> ${result.to}` : `state    ${result.from}`);
+    if (result.remedy) lines.push(`apply    ${result.remedy}`);
+  } else {
+    lines.push(`changed  ${result.changed ? 'yes' : 'no'}  ${result.id}  ${result.doc}  line ${result.line}`);
+    lines.push(result.from === result.to ? `state    ${result.to}` : `state    ${result.from} -> ${result.to}`);
+  }
+  if (result.evidenceRecorded) lines.push(`evidence ${result.sha}${result.test ? `  test: ${result.test}` : ''}`);
+  else if (result.evidenceNote) lines.push(`note     ${result.evidenceNote}`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}

package/src/commands/repoindex.mjs

@@ -0,0 +1,52 @@
+// `simt index` rebuilds the local cache from git. The cache is not repository
+// content: it is gitignored, and a second run with the same blobs writes the same
+// rows (ADR-089).
+
+import { execFile } from 'node:child_process';
+
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { CLI } from '../name.mjs';
+import { JSONL_FILE, SQLITE_FILE, reindex } from '../index/store.mjs';
+
+export async function indexCommand(args, flags) {
+  if (args.length > 0) return fail(`unknown index argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} index`);
+  const root = flags.root ?? process.cwd();
+  let result;
+  try {
+    result = await reindex(root);
+  } catch (error) {
+    return fail(
+      `could not index this repository (${error.message})`,
+      EXIT.UNSUPPORTED,
+      'run this inside a git repository',
+    );
+  }
+  const file = result.backend === 'sqlite' ? SQLITE_FILE : JSONL_FILE;
+  const ignored = await isIgnored(root, file);
+  const payload = { ok: true, command: 'index', root, file, ignored, ...result };
+  if (isJson(flags)) {
+    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    return EXIT.OK;
+  }
+  const lines = [
+    `index    ${result.backend}`,
+    `files    ${result.files}`,
+    `updated  ${result.updated}`,
+    `removed  ${result.removed}`,
+    `symbols  ${result.symbols}`,
+    `edges    ${result.edges}`,
+    `ms       ${result.ms}`,
+  ];
+  if (result.parsers === 'missing') lines.push('note     index.parsers did not load, so the built-in extractors ran');
+  if (!ignored) lines.push(`note     ${file} is not gitignored, and the cache is not meant to be committed`);
+  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  return EXIT.OK;
+}
+
+function isIgnored(root, file) {
+  return new Promise((resolve) => {
+    execFile('git', ['check-ignore', '-q', '--', file], { cwd: root }, (error) => {
+      resolve(!error);
+    });
+  });
+}