simt-dev 0.7.0 → 0.8.0

package/src/commands/spec.mjs

@@ -0,0 +1,167 @@
+// 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[]} [aliases] spellings that resolve to this row, never listed in help
+ * @property {string} [mcp] the MCP tool name that answers this row, when one does
+ */
+
+/** @type {SpecRow[]} */
+export const SPEC = [
+  { path: 'agent-hook', usage: '<event> --harness', summary: 'the harness entry point: decide one tool call, or deliver the prompt packet', aliases: ['harness hook'], flags: ["diff","harness"], },
+  { path: 'agent-hooks install', usage: '--yes', summary: "write this repository's policies into each harness hooks file", writes: 'repo', aliases: ['harness install'], 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', usage: '--yes', 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', usage: '--yes', 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', usage: '--yes', 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', usage: '--yes', summary: 'mine tasks out of a repository history', writes: 'repo', flags: ["yes","all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench probes', usage: '--yes', summary: 'run the deterministic probes against a workspace', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench report', usage: '[--compare a b]', summary: 'summarise the runs recorded in the vault', defaultFor: 'bench', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench run', usage: '--yes', summary: 'run agents against the mined tasks', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'bench variants', usage: '--yes', summary: 'run one task across its variant prompts', flags: ["all","arm","compare","cross-group","harness","labels","model","regrade","replace","reps","task"], },
+  { path: 'brief', usage: '"<task>"', 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', usage: '<bash|zsh|fish>', summary: 'print a bash, zsh or fish completion script generated from this spec', flags: [], },
+  { path: 'decide', usage: '"<title>" --yes', summary: 'scaffold a numbered decision record with its frontmatter', writes: 'repo', flags: ["yes","check","diff","dry-run","paths","supersedes","task"], },
+  { path: 'distill', usage: '<skill|doc>', summary: 'turn a repository into a skill or rule proposal', flags: [], },
+  { path: 'docs readme', summary: 'render the README command list from the spec', writes: 'repo', defaultFor: 'docs', flags: ["yes","diff"], },
+  { path: 'doctor', usage: '[--fix]', 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', usage: '<msg-file>', summary: 'a commit message claiming a run this tree does not have', flags: [], },
+  { path: 'explain', usage: '<CODE>', summary: 'what one check finding code means, and how to fix it', flags: [], },
+  { path: 'gate', usage: '--changed', summary: 'the tests a change reaches, and only those', flags: ["changed"], },
+  { path: 'graph lint', usage: '[--spec agentskills]', summary: 'check the skill registry against the skills on disk', defaultFor: 'graph', aliases: ['skills lint'], flags: ["spec"], },
+  { path: 'harness detect', usage: '[--user]', summary: 'which harness is installed, and what it carries', defaultFor: 'harness', flags: ["at","reader","table","user"], },
+  { path: 'harness loaders', usage: '[--table]', summary: 'the instruction files each harness loads, and what they cost', flags: ["at","reader","table","user"], },
+  { path: 'hooks install', usage: '--yes', summary: 'install the shared dispatcher and report what it would run', writes: 'repo', flags: ["yes","diff","dry-run"], },
+  { path: 'hooks run', usage: '<event>', 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', usage: '[--yes] [--diff]', summary: 'render the one ignore list into every harness ignore file', flags: ["diff"], },
+  { path: 'impact', usage: '<file|symbol>', summary: 'who a change reaches: importers, their tests and the contract', flags: [], },
+  { path: 'index', usage: '[--embed]', summary: 'rebuild the local file index from git blob hashes', flags: ["allow-remote","embed"], },
+  { path: 'init', usage: '[path]', summary: 'adopt this repository: manifest, region, hooks, agents and agent-hooks', writes: 'repo', flags: ["yes","accept-conflicts","backup","diff","harness","agents","surfaces"], },
+  { path: 'lease', usage: '[<paths>] --session', 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', usage: '<id> --yes', summary: 'promote one lesson candidate into docs/lessons', flags: ["diff","expires","paths","task"], },
+  { path: 'local doctor', usage: '[--allow-remote]', summary: 'the local model endpoints, and whether they answer', defaultFor: 'local', flags: ["allow-remote"], },
+  { path: 'map', usage: '--task "<task>"', 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', usage: '[--list]', 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', usage: '[dir] [--require-measured]', summary: 'lint a rule pack in the working directory', defaultFor: 'pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack new', usage: '<name> --source <spec>', summary: 'scaffold a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'pack publish', usage: '[dir] --yes', summary: 'publish a rule pack', flags: ["diff","require-measured","source"], },
+  { path: 'plan done', usage: '<id> [<sha>] --yes', 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', usage: '[<id>]', 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', usage: '<claude|gemini|cursor|opencode>', summary: 'generate a harness package from the same tables the hooks use', aliases: ['harness plugin'], flags: ["diff","out"], },
+  { path: 'pr-body', usage: '[--base <ref>]', mcp: { name: 'pr_body', flags: ['base'] }, summary: 'the pull request body: evidence, decisions, gate state and residual risk', flags: ["base"], },
+  { path: 'review', usage: '[--local]', 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', usage: '[--root <path>]', mcp: { name: 'rules_list', flags: [] }, summary: 'the rule catalogue, marked with what applies to this repository', defaultFor: 'rules', flags: ["all"], },
+  { path: 'rules show', usage: '<id>', summary: 'one rule body', flags: ["all"], },
+  { path: 'rules why', usage: '<id|ADR-NNN> [--all]', mcp: { name: 'rules_why', flags: [] }, summary: 'the decision that settled a rule, and whether it is still in force', flags: ["all"], },
+  { path: 'shared install', usage: '--yes', 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', usage: '--task "<task>"', mcp: { name: 'skills_brief', flags: ['all', 'task'] }, summary: 'the packet for a task, read from the skill registry', aliases: ['skills select'], flags: ["all", "plan", "task"], },
+  { path: 'skills compile', usage: '[<name>]', summary: 'compile a skill to the Agent Skills standard', flags: [], },
+  { path: 'skills eval', usage: '[corpus]', summary: 'score the skill registry against transcripts', flags: ["all","plan"], },
+  { path: 'skills find', usage: '<query>', 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', aliases: ['skills list'], flags: ["all","plan"], },
+  { path: 'skills install', usage: '<name> --yes', summary: 'install skills into the workspace', writes: 'repo', flags: ["yes","diff","from","variant"], },
+  { path: 'skills show', usage: '<name>', mcp: { name: 'skills_show', flags: [] }, summary: 'one skill packet', flags: ["all","plan"], },
+  { path: 'skills why', usage: '<name>', mcp: { name: 'skills_why', flags: [] }, summary: 'which skill covers a task', flags: ["all","plan"], },
+  { path: 'slice abandon', usage: '<id>', summary: 'remove a slice worktree, delete its branch, and return the row', aliases: ['plan abandon'], flags: ["session","test","type"], },
+  { path: 'slice finish', usage: '<id> --yes', summary: 'run the gates, commit the slice and record its evidence', writes: 'repo', aliases: ['plan finish'], 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', usage: '<id> --yes  |  -- "<text>"', summary: 'give a slice its worktree, branch and brief; -- starts one from a prompt, no row', defaultFor: 'slice', aliases: ['plan start'], flags: ["id","session","test","type"], },
+  { path: 'status', usage: '[--line]', summary: 'the repository snapshot, or one line of the last check', flags: ["line"], },
+  { path: 'sync', usage: '[--explain] --yes', summary: 're-render the generated regions from the rule content', writes: 'repo', flags: ["yes","check","diff","dry-run"], },
+  { path: 'tests', usage: '<path> [--cochange]', summary: 'the tests that exercise a file', flags: ["cochange"], },
+  { path: 'tokens', usage: '[--repos] [--session]', summary: 'count tokens per instruction file and per skill', aliases: ['harness cost'], flags: ["repos","session"], },
+  { path: 'undo', usage: '--yes', summary: 'restore the last journaled set of writes, if untouched', writes: 'repo', flags: ["yes","diff"], },
+  { path: 'upgrade', usage: '--yes', summary: 'replace this installation with the pinned release', writes: 'repo', flags: ["yes","all","diff","workspace"], },
+  { path: 'why', usage: '[path]', 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]]));
+
+/**
+ * The spellings this binary answers that are not paths (review 0003 Q81).
+ *
+ * A rename costs every script and every habit a reader already has, so a new name
+ * arrives as an alias instead of a replacement: the path stays the dispatch key, help
+ * lists the path, and the alias resolves before the registry is consulted. An alias is
+ * deliberately absent from help and from the generated docs — the point of a second
+ * spelling is that the reader who already knows it can type it, not that a new reader
+ * has to choose between two names for one command.
+ */
+export const ALIASES = new Map(
+  SPEC.flatMap((row) => (row.aliases ?? []).map((alias) => [alias, row.path])),
+);

package/src/commands/status.mjs

@@ -1,35 +1,44 @@
-// `simt status --line`
+// `simt status [--line]`
 //
-// One line from the last `check`, for shell prompts, tmux and agent status
-// lines: `simt PASS ✓rules ✓hooks 3/3gates`. The line is the gate state *as
-// of the last check* — it reads only `.simt/check.json` plus one
-// `git rev-parse HEAD`, so it answers in milliseconds while `check` itself
-// takes the time projection takes.
+// Two questions, one command. `--line` is for shell prompts, tmux and agent status lines:
+// one line from the last `check`, read only from `.simt/check.json` plus one
+// `git rev-parse HEAD`, so it answers in milliseconds while `check` itself takes the time
+// projection takes. Bare `status` is the aggregate a UI's home view asks for - last
+// check, git hooks, agent hooks, evidence for the tree on disk, active leases, tracker
+// state, the last journal set - and it was a usage error until review 0003 Q82.
 //
-// Bare `status` is a usage error, the way `plan` without a subcommand is: the
-// only mode this command has is `--line`, and running something else by
-// default would invent a second answer to what the status is.
+// The line's cache lives in `status.mjs`; the aggregate lives in `status-snapshot.mjs`.
+// Both report the gate *as of the last check* rather than measuring: a status command
+// that ran the gate would cost what the gate costs, and a prompt that waited for it is a
+// prompt nobody reads.
 
-import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, isJson, present } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { currentHead, readCheckCache, renderStatusLine } from '../status.mjs';
+import { renderSnapshot, statusSnapshot } from '../status-snapshot.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function statusCommand(args, flags) {
-  const root = flags.root ?? args[0] ?? process.cwd();
-  if (flags.line !== true) {
-    return fail('status needs --line', EXIT.USAGE, `run: ${CLI} status --line --root ${root}`);
+  const root = commandRoot(flags, args);
+  if (flags.line === true) return statusLine(root, flags);
+
+  const snapshot = await statusSnapshot(root);
+  const code = snapshot.ok ? EXIT.OK : EXIT.FAIL;
+  if (isJson(flags)) {
+    emitJson(snapshot);
+    return code;
   }
+  emit(renderSnapshot(snapshot));
+  return code;
+}
 
+async function statusLine(root, flags) {
   const record = await readCheckCache(root);
   if (record === null) {
     // 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,7 +19,8 @@
 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';
@@ -28,12 +29,14 @@ import { surfacesLine } from '../projection/surfaces.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 { commitJournal } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { buildCacheRecord, hooksSummary, invalidateCheckCache, writeCheckCache } from '../status.mjs';
 import { computeLock, readLock } from '../projection/lock.mjs';
 import { runDeclaredChecks } from '../kernel/checks.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.
  *
@@ -123,7 +126,7 @@ export const CHECK_NON_BLOCKING = new Set([
 ]);
 
 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);
 
@@ -324,19 +327,18 @@ export async function syncCommand(positional, flags) {
       await writeManifest(root, manifestPlan.manifest, journal);
       note(`wrote    ${manifestPlan.file} (generated field(s) ${manifestPlan.stale.join(', ')})`);
     }
-    for (const t of changed) {
-      // Three of the four rule surfaces live in directories that do not exist yet in a
-      // repository that has only ever been written to by hand. `init` grew its own
-      // 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. 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}`);
-    }
+    // The parent is derived from the target, never from the surface table, so a future
+    // surface with a deeper path needs no change here. Three of the four rule surfaces
+    // live in directories that do not exist yet in a repository that has only ever been
+    // written to by hand, and the first `sync` after a surface was added failed with
+    // ENOENT on the second target having already written the first.
+    const targetChanges = await Promise.all(
+      changed.map(async (t) =>
+        change({ path: t.path, before: await readBefore(t.path), after: t.text, owner: 'sync', reason: 'the region is stale' }),
+      ),
+    );
+    await applyPlan(root, targetChanges, { mode, journal, commit: false });
+    for (const t of changed) note(`wrote    ${t.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
@@ -409,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);
   }
@@ -544,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.
@@ -568,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.
@@ -603,14 +606,14 @@ 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)));
 
@@ -652,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,
@@ -678,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

@@ -5,18 +5,17 @@
 // batch. Coverage is read only from a fixed list of paths. History is the last
 // 200 non-merge commits, which is a map and not the whole changelog.
 
-import { execFile } from 'node:child_process';
 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 { isTestPath } from '../testing/paths.mjs';
 import { blobTexts, isIndexStale, langOf, readEdges, readFiles, reindex } from '../index/store.mjs';
-import { HISTORY, importsOf, parseCoverage, testEdges, testsFor } from '../index/tests.mjs';
-
-const exec = promisify(execFile);
+import { coverage } from '../index/coverage.mjs';
+import { HISTORY, importsOf, parseCoverage, testEdges } from '../index/tests.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { git } from '../sys/git.mjs';
 
 const COVERAGE_PATHS = [
   'coverage/lcov.info',
@@ -31,11 +30,11 @@ 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;
-  const [stored, texts, coverage, commits] = await Promise.all([
+  const [stored, texts, reports, commits] = await Promise.all([
     readEdges(root),
     testBlobs(root, files),
     coverageTexts(root),
@@ -49,20 +48,23 @@ export async function testsCommand(args, flags) {
     if (!text) continue;
     imports.push(...importsOf(file.path, text, langOf(file.path), paths));
   }
-  const edges = testEdges({ files, imports, coverage, commits });
+  const edges = testEdges({ files, imports, coverage: reports, commits });
   const target = args[0];
   if (!target) return summarise(root, flags, edges);
   if (!paths.has(target)) {
     return fail(`not in the index: ${target}`, EXIT.USAGE, `pass a path ${CLI} index knows`);
   }
-  const tests = testsFor(target, edges, { cochange: flags.cochange === true });
+  const tests = coverage({ files, imports, coverage: reports, commits }, [target], {
+    transitive: false,
+    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,11 +76,7 @@ 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;
 }
 
@@ -128,10 +126,9 @@ async function coverageTexts(root) {
 async function history(root) {
   let stdout = '';
   try {
-    ({ stdout } = await exec('git', ['log', '-n', String(HISTORY), '--no-merges', '--name-only', '--pretty=format:%x1e'], {
-      cwd: root,
+    stdout = await git(root, ['log', '-n', String(HISTORY), '--no-merges', '--name-only', '--pretty=format:%x1e'], {
       maxBuffer: 16 << 20,
-    }));
+    });
   } catch {
     return [];
   }

package/src/commands/tokens.mjs

@@ -35,15 +35,10 @@ import {
 } from '../measure/context.mjs';
 import { measureSession } from '../measure/session.mjs';
 import { sharedTotals } from '../projection/shared.mjs';
-
-/** `1234567`, never `1,234,567`. `toLocaleString` output depends on the locale, and
- *  this command exists so two machines produce two numbers a pull request can diff. */
-function plain(n) {
-  return String(n);
-}
+import { plainNumber } from '../util/fs.mjs';
 
 function files(n) {
-  return n === 1 ? '1 file' : `${plain(n)} files`;
+  return n === 1 ? '1 file' : `${plainNumber(n)} files`;
 }
 
 export async function tokensCommand(positional, flags) {
@@ -68,12 +63,12 @@ export async function tokensCommand(positional, flags) {
     }
     const lines = [
       `tokens   ${session.path}  (session)`,
-      `rules       ${plain(session.rules.bytes)} B  ~${plain(session.rules.tokens)} tokens  (${plain(session.rules.share)}%)`,
-      `file reads  ${plain(session.fileReads.bytes)} B  ~${plain(session.fileReads.tokens)} tokens  (${plain(session.fileReads.share)}%)`,
-      `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`,
+      `rules       ${plainNumber(session.rules.bytes)} B  ~${plainNumber(session.rules.tokens)} tokens  (${plainNumber(session.rules.share)}%)`,
+      `file reads  ${plainNumber(session.fileReads.bytes)} B  ~${plainNumber(session.fileReads.tokens)} tokens  (${plainNumber(session.fileReads.share)}%)`,
+      `tool output ${plainNumber(session.toolOutput.bytes)} B  ~${plainNumber(session.toolOutput.tokens)} tokens  (${plainNumber(session.toolOutput.share)}%)`,
+      `total       ${plainNumber(session.total.bytes)} B  ~${plainNumber(session.total.tokens)} tokens`,
     ];
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -140,27 +135,27 @@ export async function tokensCommand(positional, flags) {
 
   const lines = [];
   if (flags.repos) {
-    lines.push(`tokens   ${root}  ${plain(summary.roots)} repositories  (${target.source})`);
+    lines.push(`tokens   ${root}  ${plainNumber(summary.roots)} repositories  (${target.source})`);
     for (const row of rows) {
-      const budget = row.budget.over ? `  over budget by ${plain(row.budget.overBy)} B` : '';
+      const budget = row.budget.over ? `  over budget by ${plainNumber(row.budget.overBy)} B` : '';
       lines.push(
-        `${row.name}  generated ${plain(row.generatedBytes)} B  duplicate ${plain(row.redundancy.duplicateBytes)} B  unique ${plain(row.redundancy.uniqueBytes)} B${budget}`,
+        `${row.name}  generated ${plainNumber(row.generatedBytes)} B  duplicate ${plainNumber(row.redundancy.duplicateBytes)} B  unique ${plainNumber(row.redundancy.uniqueBytes)} B${budget}`,
       );
       for (const finding of row.findings) lines.push(`note     ${row.name}: ${finding}`);
     }
     const share =
       summary.generatedBytes === 0 ? 0 : Math.round((summary.duplicateBytes / summary.generatedBytes) * 100);
     lines.push(
-      `totals   generated ${plain(summary.generatedBytes)} B  duplicate ${plain(summary.duplicateBytes)} B (${plain(share)}% of generated)  unique ${plain(summary.uniqueBytes)} B  repeat ${plain(summary.repeatBytes)} B  ~${plain(summary.tokens)} tokens`,
+      `totals   generated ${plainNumber(summary.generatedBytes)} B  duplicate ${plainNumber(summary.duplicateBytes)} B (${plainNumber(share)}% of generated)  unique ${plainNumber(summary.uniqueBytes)} B  repeat ${plainNumber(summary.repeatBytes)} B  ~${plainNumber(summary.tokens)} tokens`,
     );
     // Only when there is a copy to count. The line a reader sees most is the one that
     // says what their whole estate loads, and adding a second number to it that is
     // usually zero is how a report stops being read.
     if (summary.sharedBytes > 0) {
       lines.push(
-        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  estate total ${plain(summary.estateBytes)} B`,
+        `shared   ${plainNumber(summary.sharedBytes)} B carried once in ${plainNumber(summary.sharedFiles.length)} user-level file(s)  estate total ${plainNumber(summary.estateBytes)} B`,
       );
-      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plainNumber(f.bytes)} B  ${plainNumber(f.rules)} rule(s)`);
     }
   } else {
     const row = rows[0];
@@ -168,31 +163,31 @@ export async function tokensCommand(positional, flags) {
     lines.push(`state    ${row.adoption}  surfaces ${row.surfaces.length === 0 ? '(AGENTS.md only)' : row.surfaces.join(', ')}`);
     for (const channel of row.channels) {
       lines.push(
-        `${channel.channel.padEnd(9)}${files(channel.files)}  ${plain(channel.generatedBytes)} B generated  ${plain(channel.readerBytes)} B read`,
+        `${channel.channel.padEnd(9)}${files(channel.files)}  ${plainNumber(channel.generatedBytes)} B generated  ${plainNumber(channel.readerBytes)} B read`,
       );
     }
-    const verdict = row.budget.over ? `over by ${plain(row.budget.overBy)} B` : 'within budget';
+    const verdict = row.budget.over ? `over by ${plainNumber(row.budget.overBy)} B` : 'within budget';
     lines.push(
-      `always-on ${plain(row.generatedBytes)} B generated  ~${plain(row.generatedTokens)} tokens  budget ${plain(row.budget.bytes)} B  ${verdict}`,
+      `always-on ${plainNumber(row.generatedBytes)} B generated  ~${plainNumber(row.generatedTokens)} tokens  budget ${plainNumber(row.budget.bytes)} B  ${verdict}`,
     );
     // The same reason as the `--repos` line, and it matters more here: measuring one
     // repository is the default, so a reader who owns the workspace copy and never saw it
     // counted would read a saving their own session does not get.
     if (summary.sharedBytes > 0) {
       lines.push(
-        `shared   ${plain(summary.sharedBytes)} B carried once in ${plain(summary.sharedFiles.length)} user-level file(s)  always-on for you: ${plain(summary.estateBytes)} B`,
+        `shared   ${plainNumber(summary.sharedBytes)} B carried once in ${plainNumber(summary.sharedFiles.length)} user-level file(s)  always-on for you: ${plainNumber(summary.estateBytes)} B`,
       );
-      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plain(f.bytes)} B  ${plain(f.rules)} rule(s)`);
+      for (const f of summary.sharedFiles) lines.push(`  ${f.path}  ${plainNumber(f.bytes)} B  ${plainNumber(f.rules)} rule(s)`);
     }
     lines.push(
-      `redundant ${plain(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plain(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plain(row.redundancy.uniqueBytes)} B unique of ${plain(row.redundancy.blockBytes)} B counted in blocks`,
+      `redundant ${plainNumber(row.redundancy.duplicateBytes)} B repeats an earlier repository  ${plainNumber(row.redundancy.repeatBytes)} B repeats an earlier document here  ${plainNumber(row.redundancy.uniqueBytes)} B unique of ${plainNumber(row.redundancy.blockBytes)} B counted in blocks`,
     );
     for (const finding of row.findings) lines.push(`note     ${finding}`);
   }
   lines.push(
-    `mcp      tools/list ${plain(mcp.bytes)} B of ${plain(mcp.tools)} tools  (the same for every repository, so it is not in any total)`,
+    `mcp      tools/list ${plainNumber(mcp.bytes)} B of ${plainNumber(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;
 }