simt-dev 0.7.1 → 0.8.0

package/src/commands/spec.mjs

@@ -21,98 +21,100 @@
  * @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', 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-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', summary: 'write the Simt-Agent into each harness agents file', writes: 'repo', flags: ["yes","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', 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 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', 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 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', 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: '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', 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: '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', 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: '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', 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: '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', 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"], },
+  { 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', 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: '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', 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: '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', 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"], },
+  { 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', 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"], },
+  { 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', 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: [], },
+  { 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: [], },
 ];
 
 
@@ -149,3 +151,17 @@ 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,26 +1,38 @@
-// `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, present } 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 = commandRoot(flags, args);
-  if (flags.line !== true) {
-    return fail('status needs --line', EXIT.USAGE, `run: ${CLI} status --line --root ${root}`);
+  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

package/src/commands/sync.mjs

@@ -29,7 +29,8 @@ 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';
@@ -326,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

package/src/commands/tests.mjs

@@ -5,19 +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, 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';
+import { coverage } from '../index/coverage.mjs';
+import { HISTORY, importsOf, parseCoverage, testEdges } from '../index/tests.mjs';
 import { commandRoot } from '../repo-root.mjs';
-
-const exec = promisify(execFile);
+import { git } from '../sys/git.mjs';
 
 const COVERAGE_PATHS = [
   'coverage/lcov.info',
@@ -36,7 +34,7 @@ export async function testsCommand(args, 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),
@@ -50,13 +48,16 @@ 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);
@@ -125,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,10 +63,10 @@ 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'));
     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,29 +163,29 @@ 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'));

package/src/commands/upgrade.mjs

@@ -26,12 +26,14 @@
 //      default resolved the workspace and a dry run inside one repo planned all sixteen.
 
 import { mkdir } from 'node:fs/promises';
-import { commitJournal, journaledWriteFile } from '../journal.mjs';
+import { commitJournal } from '../journal.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
 import { invalidateCheckCache } from '../status.mjs';
 
 import { basename, dirname, resolve } from 'node:path';
 
 import { EXIT, emit, emitJson, fail, isJson, note, writeMode } from '../output/index.mjs';
+import { namedRoot } from '../repo-root.mjs';
 import { provenanceDigest, plan } from '../projection/project.mjs';
 import { MANIFEST, MANIFEST_COMMENT, manifestPath, manifestText, readManifest, writeManifest } from '../projection/manifest.mjs';
 import { diffField, emitDiffs, readBefore } from '../diff.mjs';
@@ -42,7 +44,7 @@ import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
 export async function upgradeCommand(positional, flags) {
-  const explicit = flags.root ?? positional[0];
+  const explicit = namedRoot(flags, positional);
 
   // `--all` is a claim about SCOPE, so it is checked rather than inferred. "All" of
   // nothing is a contradiction, and defaulting it to the current directory would make
@@ -179,12 +181,14 @@ export async function upgradeCommand(positional, flags) {
         // `undo` in one consumer must never reach into another (R49).
         const journal = [];
         const { targets } = await plan(p.path);
+        const targetChanges = [];
         for (const t of targets) {
           if (t.action === 'unchanged' || t.action === 'malformed') continue;
-          await mkdir(dirname(t.path), { recursive: true });
-          await journaledWriteFile(p.path, journal, t.path, t.text);
+          targetChanges.push(change({ path: t.path, before: await readBefore(t.path), after: t.text, owner: 'upgrade', reason: t.action }));
           writtenFiles.add(t.file);
         }
+        // The caller's journal, committed once when the workspace walk ends.
+        await applyPlan(p.path, targetChanges, { mode: { apply: true }, journal, commit: false });
         const { manifest } = await readManifest(p.path);
         // Preserve what the repo chose; refresh what simt-dev generates. $comment is
         // ours - it describes this file's provenance - so carrying the previous copy

package/src/commands/why.mjs

@@ -5,10 +5,8 @@
 // is `git ls-files`. The index is not rebuilt: governance is the records, and
 // writing the cache to answer a question would change the tree.
 
-import { execFile } from 'node:child_process';
 import { readFile, readdir } 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 { CLI } from '../name.mjs';
@@ -16,18 +14,15 @@ import { FORMATTABLE, GATES } from '../hooks/gates.mjs';
 import { loadManifest } from '../manifest/schema.mjs';
 import { decisionsDir } from '../decisions/dir.mjs';
 import {
-  decisionHits,
-  scopeHits,
+  governs,
   scopePaths,
-  sortHits,
   sourceRoots,
   unresolvedAffects,
 } from '../index/govern.mjs';
-import { splitFrontmatter } from '../memory/decide.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 import { listPromotedLessons } from '../memory/lessons.mjs';
 import { commandRoot } from '../repo-root.mjs';
-
-const exec = promisify(execFile);
+import { gitPaths } from '../sys/git.mjs';
 
 const RULE_DIRS = ['rules', 'rules/stacks', 'rules/mdc', '.simt/profiles'];
 
@@ -43,8 +38,7 @@ export async function whyCommand(args, flags, commands = []) {
   if (!target) return reportUnresolved(root, flags, unresolvedAffects(records, ctx));
   if (!files.has(target)) return fail(`not in the tree: ${target}`, EXIT.USAGE, `pass a path git tracks`);
   const corpus = await loadCorpus(root);
-  const { hits } = decisionHits(records, target, ctx);
-  const items = sortHits([...hits, ...scopeHits(target, corpus)]);
+  const items = governs(target, { records, ...corpus, ctx });
   const payload = { ok: true, command: 'why', root, path: target, items };
   if (isJson(flags)) {
     emitJson(payload);
@@ -72,8 +66,7 @@ export async function tracked(root) {
   try {
     // `-z`: without it git C-quotes a non-ASCII path and the reader's real
     // filename never matches it (review 0003 Q39).
-    const { stdout } = await exec('git', ['ls-files', '-z'], { cwd: root, maxBuffer: 16 << 20 });
-    return { files: stdout.split('\0').filter(Boolean) };
+    return { files: await gitPaths(root, ['ls-files']) };
   } catch (error) {
     return {
       error: fail(
@@ -99,7 +92,7 @@ export async function decisionRecords(root) {
   const records = [];
   for (const name of names) {
     const text = await readFile(join(dir, name), 'utf8');
-    const { body } = splitFrontmatter(text);
+    const { body } = parseFrontmatter(text);
     const id = /^ADR-\d{3,}/i.exec(name)[0].toUpperCase();
     const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? id;
     const title = heading.replace(/^ADR-\d{3,}\s*[—–-]\s*/i, '').trim();