simt-dev 0.6.3 → 0.7.1

package/src/commands/spec.mjs

@@ -0,0 +1,151 @@
+// The command spec: one row per path this binary dispatches (review 0003 Q60).
+//
+// The list of commands existed in four places that disagreed - the dispatch map, a
+// hand-written `--help` template, the completions table and the README - so a command
+// could work and be undiscoverable, or be documented and absent. A row here is the one
+// place a command is declared; `src/commands/index.mjs` derives its dispatchable paths
+// and group defaults from it, and `test/spec.test.mjs` fails when the registry and the
+// spec stop agreeing in either direction.
+//
+// The fields that only some consumers need (`tier`, `writes`, `args`, `flags`) arrive
+// with the slices that read them: help (Q61), validation (Q62), MCP (Q66). A field no
+// code reads is a field that drifts, and a wrong `writes` claim is worse than none.
+//
+// `defaultFor` marks the subcommand a bare group resolves to. It sits on the row that
+// IS the default rather than on a separate map, so the reason for a default lives beside
+// the command it names - `skills` alone indexes because the read is the safe default,
+// `slice` alone starts because an id-less `start` fails before it writes anything.
+
+/**
+ * @typedef {object} SpecRow
+ * @property {string} path the dispatch key: `status`, or `group subcommand`
+ * @property {string} summary one phrase, printed by help and by the generated docs
+ * @property {string} [defaultFor] the group whose bare form resolves to this row
+ * @property {string} [mcp] the MCP tool name that answers this row, when one does
+ */
+
+/** @type {SpecRow[]} */
+export const SPEC = [
+  { path: 'agent-hook', summary: 'the harness entry point: decide one tool call, or deliver the prompt packet', flags: ["diff","harness"], },
+  { path: 'agent-hooks install', summary: "write this repository's policies into each harness hooks file", writes: 'repo', flags: ["yes","diff","harness"], },
+  { path: 'agent-hooks status', summary: 'what each harness will run, and what is not trusted yet', defaultFor: 'agent-hooks', flags: ["diff","harness"], },
+  { path: 'agents install', summary: 'write the Simt-Agent into each harness agents file', writes: 'repo', flags: ["yes","diff","harness"], },
+  // A group like `agent-hooks`: `install` writes the agent file into each harness's own
+  // directory and `status` reports what a harness carries. The default is the read.
+  { path: 'agents status', summary: 'what each harness carries, and what is not installed yet', defaultFor: 'agents', flags: ["diff","harness"], },
+  { path: 'bench ablate', summary: 'measure one arm of the brief against its ablation', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench critic', summary: 'score the review critic against the labelled bench set', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench export', summary: 'write the sealed bench corpus as one signed document', writes: 'repo', flags: ["yes","all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench import', summary: 'verify a sealed corpus and load it into the vault', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench mine', summary: 'mine tasks out of a repository history', writes: 'repo', defaultFor: 'bench', flags: ["yes","all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench probes', summary: 'run the deterministic probes against a workspace', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench report', summary: 'summarise the runs recorded in the vault', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench run', summary: 'run agents against the mined tasks', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench variants', summary: 'run one task across its variant prompts', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'brief', mcp: { name: 'brief', flags: ['budget', 'paths', 'task'] }, summary: 'the packet for a task: rules, skills and the files it names, within a budget', flags: ["budget","explain","paths","task"], },
+  { path: 'check', mcp: { name: 'check', flags: [] }, summary: 'report stale or missing generated regions and every check finding', flags: ["check","diff","dry-run"], },
+  { path: 'ci', summary: "refresh simt-dev's own .github workflow and Dependabot files", flags: ["check","diff"], },
+  { path: 'compare', mcp: { name: 'compare', flags: [] }, summary: 'the adoption and drift matrix across every sibling repository', flags: [], },
+  { path: 'completions', summary: 'print a bash, zsh or fish completion script generated from this spec', flags: [], },
+  { path: 'decide', summary: 'scaffold a numbered decision record with its frontmatter', writes: 'repo', flags: ["yes","check","diff","dry-run","paths","supersedes","task"], },
+  { path: 'distill', summary: 'turn a repository into a skill or rule proposal', flags: [], },
+  { path: 'doctor', mcp: { name: 'doctor', flags: [] }, summary: 'report what is wrong with this installation', writes: 'repo', flags: ["yes","diff","fix"], },
+  { path: 'evidence', summary: 'the runs recorded against the tree on disk', flags: [], },
+  { path: 'evidence check', summary: 'a commit message claiming a run this tree does not have', flags: [], },
+  { path: 'explain', summary: 'what one check finding code means, and how to fix it', flags: [], },
+  { path: 'gate', summary: 'the tests a change reaches, and only those', flags: ["changed"], },
+  { path: 'graph lint', summary: 'check the skill registry against the skills on disk', defaultFor: 'graph', flags: ["spec"], },
+  { path: 'harness detect', summary: 'which harness is installed, and what it carries', defaultFor: 'harness', flags: ["at","reader","table","user"], },
+  { path: 'harness loaders', summary: 'the instruction files each harness loads, and what they cost', flags: ["at","reader","table","user"], },
+  { path: 'hooks install', summary: 'install the shared dispatcher and report what it would run', writes: 'repo', flags: ["yes","diff","dry-run"], },
+  { path: 'hooks run', summary: "run one git event's gates now, as git would", writes: 'repo', flags: ["yes","diff","dry-run"], },
+  { path: 'hooks status', summary: 'what each git event routes to, and whether it is wired', defaultFor: 'hooks', flags: ["diff","dry-run"], },
+  { path: 'ignore', summary: 'render the one ignore list into every harness ignore file', flags: ["diff"], },
+  { path: 'impact', summary: 'who a change reaches: importers, their tests and the contract', flags: [], },
+  { path: 'index', summary: 'rebuild the local file index from git blob hashes', flags: ["allow-remote","embed"], },
+  { path: 'init', summary: 'adopt this repository: manifest, region, hooks and toolchain pins', writes: 'repo', flags: ["yes","accept-conflicts","backup","diff","surfaces"], },
+  { path: 'lease', summary: 'claim files for one session, or list the claims', flags: ["harness","session","ttl"], },
+  { path: 'lessons capture', summary: 'scan the ledger and history for new lesson candidates', flags: ["diff","expires","paths","task"], },
+  { path: 'lessons list', summary: 'deterministic lesson candidates and the promoted lessons', defaultFor: 'lessons', flags: ["diff","expires","paths","task"], },
+  { path: 'lessons review', summary: 'promote one lesson candidate into docs/lessons', flags: ["diff","expires","paths","task"], },
+  { path: 'local doctor', summary: 'the local model endpoints, and whether they answer', defaultFor: 'local', flags: ["allow-remote"], },
+  { path: 'map', summary: 'the files a task is most likely to touch, within a byte budget', flags: ["allow-remote","budget","embed","level","recall","task"], values: { level: ['outline', 'names', 'signatures'] }, },
+  { path: 'mcp', summary: 'serve the read-only MCP surface over stdio', flags: ["list"], },
+  // Plan 0003 R45. The default is the read: `pack` alone lints the working directory,
+  // the way `skills` alone indexes and `graph` alone lints.
+  { path: 'pack lint', summary: 'lint a rule pack in the working directory', defaultFor: 'pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack new', summary: 'scaffold a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack publish', summary: 'publish a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'plan done', mcp: { name: 'plan_done', flags: ['state', 'test'] }, summary: 'mark one tracker row complete, with its SHA and its evidence', flags: ["diff","state","test"], },
+  { path: 'plan next', mcp: { name: 'plan_next', flags: [] }, summary: "one ready slice's section, or the one named", flags: ["diff","state","test"], },
+  { path: 'plan status', summary: 'count the tracker rows', defaultFor: 'plan', flags: ["diff","state","test"], },
+  { path: 'plugin', summary: 'generate a harness package from the same tables the hooks use', flags: ["diff","out"], },
+  { path: 'pr-body', mcp: { name: 'pr_body', flags: ['base'] }, summary: 'the pull request body: evidence, decisions, gate state and residual risk', flags: ["base"], },
+  { path: 'review', summary: 'review the staged diff against the estate rules', flags: [], },
+  { path: 'rules decisions', summary: 'every known decision, and which layer each came from', writes: 'repo', flags: ["yes","all"], },
+  { path: 'rules list', mcp: { name: 'rules_list', flags: [] }, summary: 'the rule catalogue, marked with what applies to this repository', defaultFor: 'rules', flags: ["all"], },
+  { path: 'rules show', summary: 'one rule body', flags: ["all"], },
+  { path: 'rules why', mcp: { name: 'rules_why', flags: [] }, summary: 'the decision that settled a rule, and whether it is still in force', flags: ["all"], },
+  { path: 'shared install', summary: 'install the shared rules into a reader home directory', writes: 'repo', flags: ["yes","diff"], },
+  // 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.
+  { path: 'shared plan', summary: 'what the shared install would write, and where', writes: 'repo', defaultFor: 'shared', flags: ["yes","diff"], },
+  { path: 'skills brief', mcp: { name: 'skills_brief', flags: ['all', 'task'] }, summary: 'the packet for a task, read from the skill registry', flags: ["all", "plan", "task"], },
+  { path: 'skills compile', summary: 'compile a skill to the Agent Skills standard', flags: [], },
+  { path: 'skills eval', summary: 'score the skill registry against transcripts', flags: ["all","plan"], },
+  { path: 'skills find', mcp: { name: 'skills_find', flags: [] }, summary: 'skills that match a query', flags: ["all","plan"], },
+  { path: 'skills index', mcp: { name: 'skills_index', flags: [] }, summary: 'rebuild the skill index', defaultFor: 'skills', flags: ["all","plan"], },
+  { path: 'skills install', summary: 'install skills into the workspace', writes: 'repo', flags: ["yes","diff","from","variant"], },
+  { path: 'skills show', mcp: { name: 'skills_show', flags: [] }, summary: 'one skill packet', flags: ["all","plan"], },
+  { path: 'skills why', mcp: { name: 'skills_why', flags: [] }, summary: 'which skill covers a task', flags: ["all","plan"], },
+  { path: 'slice abandon', summary: 'remove a slice worktree, delete its branch, and return the row', flags: ["session","test","type"], },
+  { path: 'slice finish', summary: 'run the gates, commit the slice and record its evidence', writes: 'repo', flags: ["yes","session","test","type"], },
+  // Plan 0003 R53. Both halves write, so a bare `slice` has no read to default to.
+  // `start` is the default because with the id it is missing it fails with a usage error
+  // before anything is created - the one default here that cannot mutate.
+  { path: 'slice start', summary: 'give a slice its own worktree, branch and brief', defaultFor: 'slice', flags: ["session","test","type"], },
+  { path: 'status', summary: 'gate state from the last check', flags: ["line"], },
+  { path: 'sync', summary: 're-render the generated regions from the rule content', writes: 'repo', flags: ["yes","check","diff","dry-run"], },
+  { path: 'tests', summary: 'the tests that exercise a file', flags: ["cochange"], },
+  { path: 'tokens', summary: 'count tokens per instruction file and per skill', flags: ["repos","session"], },
+  { path: 'undo', summary: 'restore the last journaled set of writes, if untouched', writes: 'repo', flags: ["yes","diff"], },
+  { path: 'upgrade', summary: 'replace this installation with the pinned release', writes: 'repo', flags: ["yes","all","diff","workspace"], },
+  { path: 'why', summary: 'what governs a file: decisions, rules, skills, gates and lessons', flags: [], },
+];
+
+
+/**
+ * Which tier a command belongs to, decided by its group: the commands a reader reaches
+ * for while working are core and appear in `--help`; the rest are advanced and appear
+ * under `help --all`. A tier is a presentation fact, not a permission, so a command
+ * cannot be missing from both pages - `test/help.test.mjs` checks that every path is on
+ * one of them (review 0003 Q61).
+ */
+const CORE_GROUPS = new Set(['brief', 'check', 'gate', 'graph', 'hooks', 'impact', 'init', 'map', 'plan', 'rules', 'skills', 'slice', 'status', 'sync', 'tests', 'why']);
+
+/** The tier a path is listed under: `core` or `advanced`. */
+export function tierOf(path) {
+  return CORE_GROUPS.has(path.split(' ')[0]) ? 'core' : 'advanced';
+}
+
+/**
+ * The tools that answer a question no command asks.
+ *
+ * `federation_query` reads the federation config and consults a sibling repository
+ * directly (src/federation/query.mjs). There is no CLI verb for it, so giving it a spec
+ * row would advertise a command this binary cannot dispatch; leaving it undeclared is
+ * how a tool list and a command list drift apart. It is listed here with the reason
+ * instead, and test/mcp-spec.test.mjs accepts a tool without a row only when this table
+ * says why.
+ */
+export const MCP_ONLY = [
+  { tool: 'federation_query', why: 'a transport-only read: no command in this binary asks a sibling repository a question' },
+];
+
+/** The dispatchable paths, sorted - the answer to "what can this binary do". */
+export const SPEC_PATHS = SPEC.map((row) => row.path).sort();
+
+/** group -> the subcommand its bare form resolves to. */
+export const GROUP_DEFAULTS = new Map(SPEC.filter((row) => row.defaultFor !== undefined).map((row) => [row.defaultFor, row.path.split(' ')[1]]));

package/src/commands/status.mjs

@@ -10,12 +10,13 @@
 // only mode this command has is `--line`, and running something else by
 // default would invent a second answer to what the status is.
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { currentHead, readCheckCache, renderStatusLine } from '../status.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function statusCommand(args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
+  const root = commandRoot(flags, args);
   if (flags.line !== true) {
     return fail('status needs --line', EXIT.USAGE, `run: ${CLI} status --line --root ${root}`);
   }
@@ -25,11 +26,7 @@ export async function statusCommand(args, flags) {
     // Informational, not a failure: a repository that never ran `check` — or
     // one a writer just invalidated — has no state to report, and a prompt
     // that errored until the first check would train its reader to ignore it.
-    if (isJson(flags)) {
-      emitJson({ ok: true, command: 'status', root, line: null, cached: false, stale: false });
-      return EXIT.OK;
-    }
-    emit('simt no cache - run check');
+    present({ ok: true, command: 'status', root, line: null, cached: false, stale: false }, () => 'simt no cache - run check', flags);
     return EXIT.OK;
   }
 

package/src/commands/sync.mjs

@@ -19,22 +19,23 @@
 import { mkdir, readFile, stat, symlink, unlink } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
-import { plan, checkTargets, checkTarget, provenanceDigest, loadRules, select, pointerTargets, pointerState } from '../projection/project.mjs';
+import { repoContext } from '../context.mjs';
+import { plan, checkTargets, checkTarget, select, pointerTargets, pointerState } from '../projection/project.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { manifestDrift, readManifest, unrunnableGates, buildManifest, writeManifest, withGenerated, manifestText, manifestPath } from '../projection/manifest.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { readCapability } from '../hooks/capability.mjs';
 import { surfacesLine } from '../projection/surfaces.mjs';
-import { CLI } from '../name.mjs';
-import { MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
+import { CLI, LOCK_FILE, MANIFEST_FILE, MANIFEST_LEGACY } from '../name.mjs';
 import { assertVersionPin, packageVersion } from '../package-version.mjs';
 import { resolvePacks } from '../packs.mjs';
 import { commitJournal, journaledWriteFile } from '../journal.mjs';
 import { buildCacheRecord, hooksSummary, invalidateCheckCache, writeCheckCache } from '../status.mjs';
-import { computeLock, readLock, LOCK_FILE } from '../projection/lock.mjs';
+import { computeLock, readLock } from '../projection/lock.mjs';
 import { runDeclaredChecks } from '../kernel/checks.mjs';
-import { DECISIONS_DIR } from '../decisions/index.mjs';
+import { decisionsCutoff, decisionsDir } from '../decisions/dir.mjs';
 import { lintDecisions } from '../memory/decide.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 /** Findings `sync` reports and does not fail on.
  *
@@ -64,6 +65,12 @@ export const SYNC_NON_BLOCKING = new Set([
   'budget-cut',
   'file-lines-warn',
   'check-unbuilt',
+  // Review 0003 Q28: the tsconfig strictness findings. The base file is repo-owned —
+  // init no longer writes it, so neither can `sync` — and both findings' remedies are
+  // a decision about the repo's own compiler policy, not a missing file. Blocking on
+  // them would fail every fresh TypeScript adoption over a file the tool does not write.
+  'inert',
+  'inconsistent',
 ]);
 
 /**
@@ -101,10 +108,24 @@ export const SYNC_NON_BLOCKING = new Set([
 // (ADR-083). It says the projection was cut to fit a ceiling this repository set, so the
 // remedy is a decision about the number — and a cut the repository asked for by declaring
 // a budget is the tool working, not a repository in need of a file.
-export const CHECK_NON_BLOCKING = new Set(['orphaned', 'pack-unpinned', 'budget', 'budget-cut', 'file-lines-warn', 'check-unbuilt']);
+// `inert` and `inconsistent` are here for review 0003 Q28: the base file is repo-owned,
+// so the gate reports the state of the repo's own compiler policy without failing it.
+// A fresh TypeScript adoption has neither file in a state the tool can repair, and a
+// gate that reddens on a policy decision is one the repo satisfies by choosing, not by
+// running a command.
+export const CHECK_NON_BLOCKING = new Set([
+  'orphaned',
+  'pack-unpinned',
+  'budget',
+  'budget-cut',
+  'file-lines-warn',
+  'check-unbuilt',
+  'inert',
+  'inconsistent',
+]);
 
 export async function syncCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
   const checkOnly = flags.check === true;
   const mode = writeMode(flags);
 
@@ -153,6 +174,10 @@ export async function syncCommand(positional, flags) {
     );
   }
 
+  // A dangling cross-reference does not stop the projection: the region renders, and one
+  // unreachable reference is a defect to report, not a reason to withhold the rest.
+  for (const p of result.crossRefs ?? []) note(`PROBLEM ${p}`);
+
   const broken = result.targets.filter((t) => t.action === 'malformed');
   if (broken.length > 0) {
     const first = broken[0];
@@ -307,23 +332,13 @@ export async function syncCommand(positional, flags) {
       // mkdir; `sync` did not, so the first `sync` after a surface was added failed with
       // ENOENT on the second target and had already written the first. The parent is
       // derived from the target, never from the surface table, so a future surface with a
-      // deeper path needs no change here.
+      // deeper path needs no change here. The lock is one of these targets (Q29): it
+      // reaches this loop like every other file, so a deleted lock is a write the plan
+      // shows and the journal records.
       await mkdir(dirname(t.path), { recursive: true });
       await journaledWriteFile(root, journal, t.path, t.text);
       note(`wrote    ${t.file}`);
     }
-    const lock = await computeLock(root, flags);
-    const lockText = `${JSON.stringify(lock, null, 2)}\n`;
-    let previousLock = null;
-    try {
-      previousLock = await readFile(join(root, LOCK_FILE), 'utf8');
-    } catch (error) {
-      if (error.code !== 'ENOENT') throw error;
-    }
-    if (previousLock !== lockText) {
-      await journaledWriteFile(root, journal, join(root, LOCK_FILE), lockText);
-      note(`wrote    ${LOCK_FILE}`);
-    }
     await commitJournal(root, 'sync', journal);
     // The regions moved, so the last `check` no longer describes this tree.
     // Invalidated rather than refreshed: `sync` does not run gates, checkers
@@ -396,7 +411,7 @@ export async function syncCommand(positional, flags) {
           : `would write ${changed.length + pointersAdded.length + (manifestChanged ? 1 : 0)} file(s); apply with: ${CLI} sync --yes`,
       );
     }
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
   }
@@ -531,8 +546,9 @@ async function gateCwdFindings(root, manifest) {
 // reports 77. The command below renders these facts for terminals; the tool
 // returns them as JSON. The CLI keeps its field names; the tool adopts them.
 export async function checkRepo(root, opts = {}) {
-  const findings = await checkTargets(root, opts);
-  const rules = await loadRules(root);
+  const ctx = opts.ctx ?? repoContext(root);
+  const findings = await checkTargets(root, { ...opts, ctx });
+  const rules = await ctx.rules();
 
   // A rule file with no id would be projected without a traceable source, so it
   // is a gate failure rather than a warning: `rules why` could not resolve it.
@@ -555,7 +571,7 @@ export async function checkRepo(root, opts = {}) {
   // A declared gate this repo cannot run fails closed on every commit once hooks are
   // installed. Reported here rather than left to `hooks status`, so the repo is red
   // before anyone installs anything rather than after.
-  const { manifest, exists } = await readManifest(root);
+  const { manifest, exists } = await ctx.manifest();
   // The gates slot, counted — not just reported — so the line can print run/total.
   // A cwd finding names a declared gate that will not run, so it counts with the
   // unrunnable; an unknown-gate-cwd names no declared gate, so it does not.
@@ -590,24 +606,26 @@ export async function checkRepo(root, opts = {}) {
     // hand either: the next `init` puts simt-dev's own bytes back and the formatter
     // takes them away again. Reporting it here is what stops that being a surprise
     // discovered at upgrade time.
-    const { stack } = await fingerprint(root);
-    const drift = await manifestDrift(root, stack, await provenanceDigest());
+    const { stack } = await ctx.fingerprint();
+    const drift = await manifestDrift(root, stack, await ctx.digest());
     if (drift) findings.push(drift);
   }
   if (opts.frozen) findings.push(...(await frozenFindings(root, opts)));
   // The checkers a selected rule declared (ADR-088). They read the rule source,
   // not the folded region, so a line that left the prompt is still the line that runs.
-  const fp = await fingerprint(root);
+  const fp = await ctx.fingerprint();
   const { selected } = select(rules.filter((r) => r.error === null), fp.stack ?? [], fp.facts ?? []);
   findings.push(...(await runDeclaredChecks(root, selected, manifest ?? null)));
 
-  const decisionsDir = join(root, 'docs', 'decisions');
-  const decisionLint = await lintDecisions(decisionsDir, {
-    allowHistorical: resolve(decisionsDir) === DECISIONS_DIR,
+  // Q55: one resolution shared with `decide --check`, so the two commands
+  // cannot disagree about whose records these are or which are historical.
+  const relDecisionsDir = await decisionsDir(root);
+  const decisionLint = await lintDecisions(join(root, relDecisionsDir), {
+    historicalCutoff: await decisionsCutoff(root),
   });
   findings.push(
     ...decisionLint.findings.map((f) => ({
-      file: ['docs', 'decisions', f.file].join('/'),
+      file: [relDecisionsDir, f.file].join('/'),
       status: f.status,
       detail: f.detail,
       remedy: f.remedy,
@@ -637,7 +655,7 @@ export async function checkRepo(root, opts = {}) {
 }
 
 export async function checkCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
   const { ok, findings } = await checkRepo(root, flags);
   const payload = {
     ok,
@@ -663,7 +681,6 @@ export async function checkCommand(positional, flags) {
         return f.remedy ? [head, `${' '.repeat(11)}remedy: ${f.remedy}`] : [head];
       })
       .join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return ok ? EXIT.OK : EXIT.FAIL;
 }

package/src/commands/tests.mjs

@@ -10,11 +10,12 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { isTestPath } from '../bench/mine.mjs';
-import { blobTexts, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
+import { blobTexts, isIndexStale, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
 import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const exec = promisify(execFile);
 
@@ -31,7 +32,7 @@ const COVERAGE_PATHS = [
 
 export async function testsCommand(args, flags) {
   if (args.length > 1) return fail(`unknown tests argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} tests [path]`);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const loaded = await loadFiles(root);
   if (loaded.error) return loaded.error;
   const { files } = loaded;
@@ -58,11 +59,11 @@ export async function testsCommand(args, flags) {
   const tests = testsFor(target, edges, { cochange: flags.cochange === true });
   const payload = { ok: true, command: 'tests', root, path: target, tests };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = [`tests    ${tests.length}`, ...tests];
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -74,17 +75,16 @@ function summarise(root, flags, edges) {
     else if (edge.kind === 'cochange') cochange += 1;
   }
   const payload = { ok: true, command: 'tests', root, test, cochange };
-  if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
-    return EXIT.OK;
-  }
-  emit(`test      ${test}\ncochange  ${cochange}`, { maxBytes: flags.maxBytes ?? 0 });
+  present(payload, () => `test      ${test}\ncochange  ${cochange}`, flags);
   return EXIT.OK;
 }
 
 async function loadFiles(root) {
   let files = await readFiles(root);
-  if (files.length === 0) {
+  // An empty index has nothing to answer from; a stale one has yesterday's
+  // tree (review 0003 Q42). Either way the refresh is incremental, so a
+  // current repository pays for one `git ls-files -s`, not a rebuild.
+  if (files.length === 0 || (await isIndexStale(root))) {
     try {
       await reindex(root);
     } catch (error) {

package/src/commands/tokens.mjs

@@ -73,7 +73,7 @@ export async function tokensCommand(positional, flags) {
       `tool output ${plain(session.toolOutput.bytes)} B  ~${plain(session.toolOutput.tokens)} tokens  (${plain(session.toolOutput.share)}%)`,
       `total       ${plain(session.total.bytes)} B  ~${plain(session.total.tokens)} tokens`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -193,6 +193,6 @@ export async function tokensCommand(positional, flags) {
     `mcp      tools/list ${plain(mcp.bytes)} B of ${plain(mcp.tools)} tools  (the same for every repository, so it is not in any total)`,
   );
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/undo.mjs

@@ -1,62 +1,66 @@
 // `simt undo [--yes] [--json]`
 //
 // Restore the last journaled set of writes (plan 0003 R49): every file the last
-// writing run changed goes back to its pre-run bytes, and files the run created
-// are deleted. A run that wrote nothing leaves no set, so there is nothing to
-// restore and the command says so.
+// writing run changed goes back to its pre-run bytes, files the run created
+// are deleted, and git config keys the run set go back to their pre-run
+// values (review 0003 Q22). A run that wrote nothing leaves no set, so there
+// is nothing to restore and the command says so.
 //
 // The safety is the journal's, not the flag's: when any file in the set no
 // longer matches the bytes the run left, the whole undo is refused — restoring
 // the rest around a hand edit would silently merge two authors' intentions.
 // Like every other writer this command previews without `--yes`.
 
-import { EXIT, emit, emitJson, isJson, writeMode } from '../output/index.mjs';
+import { EXIT, emit, emitJson, isJson, writeMode, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
-import { listJournalSets, readJournalSet, undoLastJournalSet } from '../journal.mjs';
+import { beforeText, entryLabel, listJournalSets, readGitValue, readJournalSet, undoLastJournalSet } from '../journal.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
 import { join } from 'node:path';
 import { invalidateCheckCache } from '../status.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function undoCommand(positional, flags) {
-  const root = flags.root ?? positional[0] ?? process.cwd();
+  const root = commandRoot(flags, positional);
   const mode = writeMode(flags);
 
   const [id] = await listJournalSets(root);
   if (!id) {
-    if (isJson(flags)) {
-      emitJson({ ok: true, command: 'undo', root, set: null, restored: [], dryRun: !mode.apply });
-      return EXIT.OK;
-    }
-    emit('nothing to undo: no journaled writes', { maxBytes: flags.maxBytes ?? 0 });
+    present({ ok: true, command: 'undo', root, set: null, restored: [], dryRun: !mode.apply }, () => 'nothing to undo: no journaled writes', flags);
     return EXIT.OK;
   }
 
   const set = await readJournalSet(root, id);
-  const paths = set.entries.map((e) => e.path);
+  const labels = set.entries.map(entryLabel);
   // The `--diff` pairs: what the tree holds now against what the restore
-  // would put back. A null beforeBytes is a file the run created, so the
-  // restore deletes it — the after side is empty (R50).
+  // would put back. A null before is a file the run created (or a key it
+  // set from unset), so the restore deletes it — the after side is empty
+  // (R50).
   const diffs =
     flags.diff === true
       ? await Promise.all(
-        set.entries.map(async (e) => ({
-          path: e.path,
-          before: await readBefore(join(root, e.path)),
-          after: e.beforeBytes ?? null,
-        })),
+        set.entries.map(async (e) => {
+          if (e.kind === 'git-config') {
+            return { path: entryLabel(e), before: await readGitValue(root, e.key), after: e.before ?? null };
+          }
+          return { path: e.path, before: await readBefore(join(root, e.path)), after: beforeText(e) };
+        }),
       )
       : [];
 
   if (!mode.apply) {
     if (isJson(flags)) {
-      emitJson({ ok: true, command: 'undo', root, set: id, restores: paths, dryRun: true, ...diffField(diffs, flags) });
+      emitJson({ ok: true, command: 'undo', root, set: id, restores: labels, dryRun: true, ...diffField(diffs, flags) });
       return EXIT.OK;
     }
+    const files = set.entries.filter((e) => e.kind !== 'git-config').length;
+    const keys = set.entries.length - files;
     emit(
-      [`last write  ${set.command} (${id})`, ...paths.map((p) => `restore   ${p}`), '', `would restore ${paths.length} file(s); apply with: ${CLI} undo --yes`].join(
-        '\n',
-      ),
-      { maxBytes: flags.maxBytes ?? 0 },
+      [
+        `last write  ${set.command} (${id})`,
+        ...labels.map((p) => `restore   ${p}`),
+        '',
+        `would restore ${files} file(s)${keys > 0 ? ` and ${keys} git config key(s)` : ''}; apply with: ${CLI} undo --yes`,
+      ].join('\n'),
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -65,11 +69,7 @@ export async function undoCommand(positional, flags) {
 
   const result = await undoLastJournalSet(root);
   if (result.empty) {
-    if (isJson(flags)) {
-      emitJson({ ok: true, command: 'undo', root, set: null, restored: [] });
-      return EXIT.OK;
-    }
-    emit('nothing to undo: no journaled writes', { maxBytes: flags.maxBytes ?? 0 });
+    present({ ok: true, command: 'undo', root, set: null, restored: [] }, () => 'nothing to undo: no journaled writes', flags);
     return EXIT.OK;
   }
   if (result.refused) {
@@ -84,7 +84,6 @@ export async function undoCommand(positional, flags) {
         '',
         'nothing was restored; re-run the writing command or merge by hand, then undo again',
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.FAIL;
   }
@@ -98,7 +97,6 @@ export async function undoCommand(positional, flags) {
   }
   emit(
     [`undone    ${result.set}`, ...result.restored.map((p) => `restored  ${p}`)].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);