simt-dev 0.7.0 → 0.8.0

package/src/commands/undo.mjs

@@ -11,24 +11,21 @@
 // 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 { 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;
   }
 
@@ -64,7 +61,6 @@ export async function undoCommand(positional, flags) {
         '',
         `would restore ${files} file(s)${keys > 0 ? ` and ${keys} git config key(s)` : ''}; apply with: ${CLI} undo --yes`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -73,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) {
@@ -92,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;
   }
@@ -106,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);

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
@@ -216,8 +220,12 @@ export async function upgradeCommand(positional, flags) {
     }
   }
 
+  // One verdict, stated once. `ok` used to be `skipped === 0`, so a workspace with a
+  // repo that never adopted answered ok:false and exited 0: the document and the process
+  // disagreed, and a caller had no way to tell which one was the answer (review 0003 Q65).
+  const code = exitFor(plans, failed);
   const payload = {
-    ok: summary.skipped === 0 && failed.length === 0,
+    ok: code === EXIT.OK,
     command: 'upgrade',
     root,
     shape: found.shape,
@@ -232,7 +240,7 @@ export async function upgradeCommand(positional, flags) {
 
   if (isJson(flags)) {
     emitJson(payload);
-    return exitFor(plans, failed);
+    return code;
   }
 
   emit(render(plans, summary, { root, shape: found.shape, source: target.source, sha, applied, failed }));
@@ -256,7 +264,7 @@ export async function upgradeCommand(positional, flags) {
   } else {
     note('note     every consumer already runs this simt-dev');
   }
-  return exitFor(plans, failed);
+  return code;
 }
 
 /**

package/src/commands/why.mjs

@@ -5,33 +5,30 @@
 // 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, MANIFEST_FILE } from '../name.mjs';
+import { CLI } from '../name.mjs';
 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';
-
-const exec = promisify(execFile);
+import { commandRoot } from '../repo-root.mjs';
+import { gitPaths } from '../sys/git.mjs';
 
 const RULE_DIRS = ['rules', 'rules/stacks', 'rules/mdc', '.simt/profiles'];
 
 export async function whyCommand(args, flags, commands = []) {
   if (args.length > 1) return fail(`unknown why argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} why [path]`);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const listed = await tracked(root);
   if (listed.error) return listed.error;
   const files = new Set(listed.files);
@@ -41,26 +38,25 @@ 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, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = items.map((item) => `${item.kind.padEnd(10)}${item.id}  ${item.detail}`);
-  emit(lines.length > 0 ? lines.join('\n') : 'none', { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.length > 0 ? lines.join('\n') : 'none');
   return EXIT.OK;
 }
 
 function reportUnresolved(root, flags, unresolved) {
   const payload = { ok: true, command: 'why', root, unresolved };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = unresolved.map((item) => `UNRESOLVED-AFFECTS  ${item.token}  ${item.id}`);
-  emit([`unresolved  ${unresolved.length}`, ...lines].join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit([`unresolved  ${unresolved.length}`, ...lines].join('\n'));
   return EXIT.OK;
 }
 
@@ -70,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(
@@ -97,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();
@@ -172,8 +167,7 @@ export async function lessonScopes(root) {
 
 async function gateCommands(root) {
   try {
-    const parsed = JSON.parse(await readFile(join(root, MANIFEST_FILE), 'utf8'));
-    const commands = parsed?.gates?.commands;
+    const commands = (await loadManifest(root)).manifest?.gates?.commands;
     return commands && typeof commands === 'object' ? commands : {};
   } catch {
     return {};

package/src/compare/hooksstate.mjs

@@ -6,16 +6,15 @@
 // duplicated-source-of-truth problem the tool exists to remove. `compare` reads it
 // for N repos, so it must not shell out per repo per event.
 
-import { execFile } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
-import { promisify } from 'node:util';
 
 import { CHAIN_MARKER, EVENTS, HOOKS_DIR, HOOKS_PATH_KEY, SHIM_MARKER, fileFor, renderChainedShim, renderShim } from '../hooks/shim.mjs';
 import { foreignHooks, resolveHooksDir } from '../hooks/where.mjs';
 import { packageVersion, hasNpm } from '../package-version.mjs';
 import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
+import { gitText } from '../sys/git.mjs';
 
 /**
  * The Node manager id for this repository, or null without a package.json.
@@ -34,8 +33,6 @@ async function nodeManagerFor(root) {
   return resolveNodeRunner({ facts: detected.facts, packageManager }).id;
 }
 
-const exec = promisify(execFile);
-
 /**
  * The chained shim at `path`, read back out of the file itself.
  *
@@ -120,8 +117,7 @@ export function wantsShim(manifest, exists, event) {
 /** `core.hooksPath`, or null when unset or the repo is not a git repo. */
 export async function readHooksPath(root) {
   try {
-    const { stdout } = await exec('git', ['config', '--get', HOOKS_PATH_KEY], { cwd: root });
-    const value = stdout.trim();
+    const value = await gitText(root, ['config', '--get', HOOKS_PATH_KEY]);
     return value === '' ? null : value;
   } catch {
     return null;

package/src/compare/learn.mjs

@@ -19,7 +19,9 @@ import { mapCapped, DEFAULT_CONCURRENCY } from './parallel.mjs';
 
 import { policiesFor } from '../agenthooks/policy.mjs';
 import { DEL_R_TOLERANCE, parseAblationArmName } from '../bench/ablate.mjs';
-import { compareArms, evaluateRunRecord, loadPrices, loadRunRecords } from '../bench/report.mjs';
+import { evaluateRunRecord, loadPrices } from '../measure/metrics.mjs';
+import { loadRunRecords } from '../measure/records.mjs';
+import { compareArms } from '../measure/stats.mjs';
 import { GATES } from '../hooks/gates.mjs';
 import { readLedger } from '../ledger/index.mjs';
 import { readLessonCandidates } from '../memory/lessons.mjs';

package/src/compare/row.mjs

@@ -21,7 +21,6 @@ import { checkTargets, PRIMARY_TARGET } from '../projection/project.mjs';
 import { manifestDrift, readManifest } from '../projection/manifest.mjs';
 import { loadRules, select } from '../projection/rules.mjs';
 import { resolvePacks } from '../packs.mjs';
-import { knownGates } from '../hooks/resolve.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { readHooksState, wantsShim } from './hooksstate.mjs';
 import { CLI } from '../name.mjs';
@@ -421,4 +420,3 @@ export function summarise(rows, extra = {}) {
   };
 }
 
-export { knownGates };

package/src/context.mjs

@@ -0,0 +1,64 @@
+// The per-run memo a command reads its repository through (review 0003 Q67).
+//
+// `check` did the same work twice in one run: `fingerprint(root)` at two sites, a
+// manifest read that `manifestDrift` repeated, and a rules load that every consumer
+// paid for again. Each fingerprint spawns `git ls-files` and walks the tree once per
+// glob fact, so the second call was never cheap - it was invisible.
+//
+// The cache lives for one command, not for the process. `bench` writes manifests and
+// rewrites trees mid-run; a process-lifetime memo would hand a benchmark the answer
+// for a repository it had just changed, which is the one way a cache can be worse
+// than no cache. A caller that wants a fresh answer makes a fresh context.
+//
+// A rejected computation is not cached: a transient failure (a git lock, a permission
+// error) should not become the answer for the rest of the run, and every one of these
+// readers is safe to retry.
+
+import { fingerprint } from './resolve/fingerprint.mjs';
+import { readManifest } from './projection/manifest.mjs';
+import { loadRules, provenanceDigest } from './projection/rules.mjs';
+
+/**
+ * One repository, read once per question.
+ *
+ * Each accessor is a promise, and two calls with the same key share it rather than
+ * racing: the first caller to ask starts the work, and everyone else awaits it.
+ *
+ * @param {string} root the repository this context answers for
+ */
+export function repoContext(root) {
+  const cache = new Map();
+  const counts = { hits: 0, misses: 0 };
+
+  const once = (key, compute) => {
+    if (cache.has(key)) {
+      counts.hits += 1;
+      return cache.get(key);
+    }
+    counts.misses += 1;
+    const pending = Promise.resolve()
+      .then(compute)
+      .catch((error) => {
+        // Not cached, or one failed read would answer every later caller.
+        cache.delete(key);
+        throw error;
+      });
+    cache.set(key, pending);
+    return pending;
+  };
+
+  return {
+    root,
+    /** What the cache did, for a test or a measurement - never printed by a command. */
+    get stats() {
+      return { ...counts, entries: cache.size };
+    },
+    fingerprint: () => once('fingerprint', () => fingerprint(root)),
+    // The legacy shape, because that is what the commands print: `error` is the
+    // unreadable-file case and every caller already renders it. Memoising the loader's
+    // `problems` array here instead gave doctor `undefined` where it tests for null.
+    manifest: () => once('manifest', () => readManifest(root)),
+    rules: () => once('rules', () => loadRules(root)),
+    digest: () => once('digest', () => provenanceDigest()),
+  };
+}

package/src/decisions/index-doc.mjs

@@ -0,0 +1,46 @@
+// The decisions index document, rendered from the records (review 0003 Q91).
+//
+// The file was 590 hand-written lines: a table of every ADR kept in step by whoever
+// remembered. It agreed with the records until it did not, and nothing read it, so
+// nothing noticed - the failure the generated rule regions exist to prevent, one
+// directory over. The table is output now: this module renders it, `simt rules
+// decisions --yes` writes it, and test/decisions-index.test.mjs fails on drift.
+//
+// The narrative that trailed the table moved to docs/architecture/history.md: prose a
+// reader consults is not prose a command rewrites.
+
+const HEADER = `# Decisions
+
+Architecture decision records for the SIMT development ecosystem. One canonical home per
+decision; nothing here is duplicated into a repo's \`AGENTS.md\`.
+
+A decision is superseded by writing a new ADR with a higher number and editing the old
+record's status line — never by editing the ruling in place.
+
+This table is generated from the records: \`simt rules decisions --yes\` writes it, and
+\`test/decisions-index.test.mjs\` fails when it drifts. The history behind the numbers is
+in [architecture/history.md](architecture/history.md).
+
+| ADR | Decision | Status |
+|---|---|---|
+`;
+
+/**
+ * The index document, from the records.
+ *
+ * Ordered by number, not by filename: the number IS the order, and a directory listing
+ * is not (`ADR-100` sorts before `ADR-99` as text).
+ *
+ * @param {{id: string, title: string, status: string, file: string}[]} rows
+ * @returns {string}
+ */
+export function renderDecisionsIndex(rows) {
+  const ordered = [...rows].sort((a, b) => number(a.id) - number(b.id));
+  const lines = ordered.map((row) => `| [${number(row.id)}](decisions/${row.file}) | ${row.title} | ${row.status} |`);
+  return `${HEADER}${lines.join('\n')}\n`;
+}
+
+/** `ADR-007` -> `007`, the number the table and the ordering both use. */
+function number(id) {
+  return id.replace(/^ADR-/i, '').padStart(3, '0');
+}

package/src/decisions/index.mjs

@@ -28,7 +28,8 @@ import { packageVersion } from '../package-version.mjs';
 // evaluation would read an initialising binding on one of the two load
 // orders. Every use below happens at runtime, when both sides are loaded.
 import { COMMANDS } from '../commands/index.mjs';
-import { PARTIAL_CLAUSE, parseDecisionFrontmatter, splitFrontmatter } from '../memory/decide.mjs';
+import { PARTIAL_CLAUSE, parseDecisionFrontmatter } from '../memory/decide.mjs';
+import { parseFrontmatter } from '../text/frontmatter.mjs';
 import { affectsTokens } from '../index/govern.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -189,7 +190,7 @@ export function citations(text) {
  */
 export function parseDecision(file, text, { all = false } = {}) {
   const fm = parseDecisionFrontmatter(text);
-  const { body } = splitFrontmatter(text);
+  const { body } = parseFrontmatter(text);
   const fileId = /^ADR-(\d{3,})/i.exec(file)?.[0]?.toUpperCase();
   const heading = /^#\s+(.*)$/m.exec(body)?.[1] ?? null;
   const headId = heading ? /^(ADR-\d{3,})/i.exec(heading)?.[1]?.toUpperCase() : null;

package/src/diff.mjs

@@ -49,7 +49,7 @@ export async function readBefore(path) {
 export function emitDiffs(pairs, flags) {
   if (isJson(flags)) return;
   const text = renderDiffs(pairs);
-  if (text !== '') emit(text, { maxBytes: flags.maxBytes ?? 0 });
+  if (text !== '') emit(text);
 }
 
 /** The `--diff` bytes for a JSON payload: absent entirely without the flag, so

package/src/distill/distill.mjs

@@ -35,6 +35,7 @@ import {
 
 export const DEFAULT_BUDGET = 2048;
 import { LOCAL_DIR } from '../state.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const DISTILL_DIR = join(LOCAL_DIR, 'distilled');
 
@@ -175,7 +176,7 @@ export async function distillTarget(args, flags) {
     );
   }
 
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const source = await resolveTarget(target, root, flags);
   if (source.exit !== undefined) return source.exit;
 
@@ -192,6 +193,16 @@ export async function distillTarget(args, flags) {
   const cached = flags.refresh === true ? null : await readFile(absProposal, 'utf8').catch(() => null);
   if (cached !== null) {
     const fields = parseExistingFrontmatter(cached);
+    let faults = [];
+    if (typeof fields.faults === 'string') {
+      try {
+        const parsedFaults = JSON.parse(fields.faults);
+        if (Array.isArray(parsedFaults)) faults = parsedFaults.map(String);
+      } catch {
+        // A malformed faults line is not a reason to refuse the proposal; the proposal
+        // still says it is unverified, and `--refresh` re-derives the list.
+      }
+    }
     return {
       ok: true,
       command: 'distill',
@@ -201,6 +212,7 @@ export async function distillTarget(args, flags) {
       budget: Number(fields.budget ?? budget),
       citations: countCitations(cached),
       verified: fields.verified !== 'false',
+      faults,
       metric: { note: METRIC_NOTE },
       proposal: { path: relProposal, state: 'cached', bytes: Buffer.byteLength(cached, 'utf8') },
     };
@@ -227,6 +239,7 @@ export async function distillTarget(args, flags) {
       engine: provenance,
       budget,
       verified: faults.length === 0,
+      faults,
     }) + `\n${outcome.body}\n`;
 
   await mkdir(join(root, DISTILL_DIR), { recursive: true });

package/src/distill/engine.mjs

@@ -167,7 +167,7 @@ export function verifyCitations(body, sourceLineCount) {
 }
 
 /** The proposal file's frontmatter. No wall-clock value here: byte-stable (P4). */
-export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory }) {
+export function proposalFrontmatter({ source, digest, engine, budget, prompt, verified, verdict, advisory, faults = [] }) {
   return [
     '---',
     `source: ${source}`,
@@ -178,6 +178,10 @@ export function proposalFrontmatter({ source, digest, engine, budget, prompt, ve
     verdict ? `verdict: ${verdict}` : null,
     advisory ? 'advisory: true' : null,
     verified === false ? 'verified: false' : 'verified: true',
+    // The faults belong to the proposal, not only to the report that wrote it: a cached
+    // proposal re-read without them reported `verified:false` and nothing to fix
+    // (review 0003 Q52).
+    Array.isArray(faults) && faults.length > 0 ? `faults: ${JSON.stringify(faults)}` : null,
     'status: proposal',
     '---',
     '',

package/src/docs/commands.mjs

@@ -0,0 +1,65 @@
+// The README's command list, rendered from the spec (review 0003 Q60).
+//
+// The README carried the fifth copy of the command list this review found. The other
+// four now come from `spec.mjs`; this one could not, because a README line is a sentence
+// for a reader rather than a table row for a parser. It does not need to be: a row's
+// `path` is the command and its `summary` is already one phrase, written for help. So the
+// list is rendered from those two fields, and `test/docs.test.mjs` fails when the README
+// and the spec stop agreeing.
+//
+// The group comment is the first word of the path, which is what a reader scans for. The
+// order is the order the spec lists groups in, so a new group lands where its author put
+// it rather than wherever it sorts.
+import { SPEC } from '../commands/spec.mjs';
+import { CLI } from '../name.mjs';
+
+export const README_FILE = 'README.md';
+export const BEGIN = '<!-- simt:commands:begin -->';
+export const END = '<!-- simt:commands:end -->';
+
+/** The fenced command list, markers included, exactly as the README must carry it. */
+export function renderCommandBlock() {
+  const groups = new Map();
+  for (const row of SPEC) {
+    const group = row.path.split(' ')[0];
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group).push(row);
+  }
+  // The invocation, not the path: `brief` without `"<task>"` is a command a reader has
+  // to go and look up, which is what the hand-written list it replaced was for.
+  const command = (row) => `${row.path}${row.usage === undefined ? '' : ` ${row.usage}`}`;
+  const width = Math.max(...SPEC.map((row) => command(row).length));
+  const lines = [];
+  for (const [group, rows] of groups) {
+    lines.push('', `# ${group}`);
+    for (const row of [...rows].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+      lines.push(`${CLI} ${command(row).padEnd(width)}  # ${row.summary}`);
+    }
+  }
+  // The first group's leading blank line would sit directly under the fence, which reads
+  // as a stray newline in the block rather than a separation.
+  if (lines[0] === '') lines.shift();
+  return [
+    BEGIN,
+    '<!-- Rendered from the spec by `simt docs readme --yes`; do not edit by hand. -->',
+    '',
+    '```sh',
+    ...lines,
+    '```',
+    END,
+  ].join('\n');
+}
+
+/**
+ * Replace the region between the markers, or return null when the file carries none.
+ *
+ * Null rather than an appended block: a README without the markers has the list somewhere
+ * else, and writing a second one beside it is the duplicated list this rendering exists
+ * to remove.
+ */
+export function replaceBlock(text, block) {
+  const start = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  if (start === -1 || end === -1 || end < start) return null;
+  return `${text.slice(0, start)}${block}${text.slice(end + END.length)}`;
+}