simt-dev 0.7.0 → 0.8.0

package/src/commands/lessons.mjs

@@ -17,12 +17,13 @@ import {
   promoteLesson,
   readLessonCandidates,
 } from '../memory/lessons.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function lessonsListCommand(args, flags) {
   if (args.length > 0) {
     return fail(`unknown lessons argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons`);
   }
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   // Pure: listing must not capture. Capture used to run here, so `list` wrote
   // to the store it was reading and a read-only question had write side
   // effects. Capturing is `lessons capture` now (review 0003 Q36).
@@ -48,7 +49,7 @@ export async function lessonsListCommand(args, flags) {
   };
 
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
   }
 
@@ -81,7 +82,7 @@ export async function lessonsListCommand(args, flags) {
 
   for (const err of errors) lines.push(`error       ${err}`);
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return errors.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
@@ -96,7 +97,7 @@ export async function lessonsCaptureCommand(args, flags) {
   if (args.length > 0) {
     return fail(`unknown lessons capture argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} lessons capture`);
   }
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const fromLedger = await captureFromLedger(root);
   const reverts = await captureRevertedCommits(root);
 
@@ -109,7 +110,7 @@ export async function lessonsCaptureCommand(args, flags) {
     captured: [...fromLedger, ...reverts],
   };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = [
@@ -120,7 +121,7 @@ export async function lessonsCaptureCommand(args, flags) {
   for (const c of payload.captured) {
     lines.push(`  ${c.id}  ${c.kind}  ${c.summary}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -128,7 +129,7 @@ export async function lessonsReviewCommand(args, flags) {
   if (args.length > 1) {
     return fail(`unknown lessons review argument ${args[1]}`, EXIT.USAGE, `run: ${CLI} lessons review [<id>] [--yes]`);
   }
-  const root = resolve(flags.root ?? process.cwd());
+  const root = resolve(commandRoot(flags));
   const mode = writeMode(flags);
   const parsedPaths = parsePathList(flags.paths);
   const paths = parsedPaths.length > 0 ? parsedPaths : undefined;
@@ -173,7 +174,7 @@ export async function lessonsReviewCommand(args, flags) {
   };
 
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
 
@@ -185,7 +186,7 @@ export async function lessonsReviewCommand(args, flags) {
     result.markdown.trimEnd(),
   ];
 
-  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);
   if (!mode.apply) {

package/src/commands/local.mjs

@@ -8,6 +8,7 @@ import { resolve } from 'node:path';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI, MANIFEST_FILE } from '../name.mjs';
 import { probeLocal } from '../local/client.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 function formatRoleLine(role, report) {
   if (!report) return `${role.padEnd(8)} (unset)`;
@@ -55,7 +56,7 @@ function remedyFor(result) {
 }
 
 export async function localDoctorCommand(args, flags) {
-  const root = resolve(flags.root ?? args[0] ?? process.cwd());
+  const root = resolve(commandRoot(flags, args));
   const allowRemote = flags.allowRemote === true;
   const result = await probeLocal(root, { allowRemote });
 
@@ -86,7 +87,6 @@ export async function localDoctorCommand(args, flags) {
         findings: result.findings,
         ...(error ? { error, remedy, exitCode: code } : {}),
       },
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return code;
   }
@@ -99,7 +99,7 @@ export async function localDoctorCommand(args, flags) {
     `sockets  ${result.socketsOpened}`,
   ];
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
 
   if (!result.ok) {
     return fail(error, code, remedy);

package/src/commands/map.mjs

@@ -5,7 +5,7 @@
 // `build` on are ones a person typed at a terminal, where a few hundred
 // milliseconds is not a bar to meet.
 
-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 { isIndexStale, readEdges, readEmbeddings, readFiles, readFts, readSymbols, reindex, searchFtsBm25 } from '../index/store.mjs';
 import {
@@ -16,12 +16,13 @@ import {
   rankFiles,
   renderMap,
 } from '../index/map.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 const LEVELS = new Set(['outline', 'names', 'signatures']);
 
 export async function mapCommand(args, flags) {
   if (args.length > 0) return fail(`unknown map argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} map`);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (flags.recall === true) return recall(root, flags);
   const level = flags.level ?? 'outline';
   if (!LEVELS.has(level)) {
@@ -31,9 +32,9 @@ export async function mapCommand(args, flags) {
   if (!Number.isInteger(budget) || budget < 0) {
     return fail(`budget must be a non-negative integer`, EXIT.USAGE, `run: ${CLI} map --budget 2048`);
   }
-  const loaded = await loadGraph(root);
-  if (loaded.error) return loaded.error;
   const task = typeof flags.task === 'string' ? flags.task : '';
+  const loaded = await loadGraph(root, { task, embed: flags.embed === true });
+  if (loaded.error) return loaded.error;
   const bm25 = task.trim().length > 0 ? await searchFtsBm25(root, task, { fts: loaded.fts }) : [];
   const queryVector =
     flags.embed === true && loaded.embeddings.length > 0
@@ -44,12 +45,19 @@ export async function mapCommand(args, flags) {
       : null;
   const ranked = rankFiles({ ...loaded, bm25, queryVector, task });
   const rendered = renderMap(ranked, loaded.symbols, { level, budget });
+  // What the ranking is an answer to. `graph-only` says no file or symbol mentioned the
+  // task and the list is the graph hub; reading that as a hit is how `map --task
+  // zebracorn` looked useful (review 0003 Q52).
+  const matched = ranked.filter((row) => (row.score ?? 0) > 0).length;
+  const basis = task.trim().length === 0 ? 'no-task' : matched > 0 ? 'matched' : 'graph-only';
   const payload = {
     ok: true,
     command: 'map',
     root,
     level,
     budget,
+    matched,
+    basis,
     shown: rendered.shown,
     total: rendered.total,
     truncated: rendered.truncated,
@@ -57,17 +65,18 @@ export async function mapCommand(args, flags) {
     text: rendered.text,
   };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = [
     `level    ${level}`,
+    `basis    ${basis}${basis === 'graph-only' ? ' (no file or symbol mentions this task; the list is the graph hub)' : ''}`,
     `shown    ${rendered.shown}`,
     `total    ${rendered.total}`,
     `budget   ${budget}`,
   ];
   if (rendered.text) lines.push(rendered.text);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -82,11 +91,7 @@ async function recall(root, flags) {
     return fail(`could not measure recall (${error.message})`, EXIT.UNSUPPORTED, `run ${CLI} index in a git repository`);
   }
   const payload = { ok: true, command: 'map', root, recall: result };
-  if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
-    return EXIT.OK;
-  }
-  emit(formatRecall(result), { maxBytes: flags.maxBytes ?? 0 });
+  present(payload, () => formatRecall(result), flags);
   return EXIT.OK;
 }
 
@@ -104,8 +109,12 @@ async function recall(root, flags) {
  * first prompt in a fresh clone wait, and a prompt that takes a minute to appear is
  * how a hook gets uninstalled. The next prompt gets the packet, and a command a
  * person typed at a terminal always builds what it needs.
+ *
+ * FTS bodies and stored vectors load only when the caller names them (review 0003
+ * Q76): BM25 runs in SQLite, so the graph read pays for files, symbols and edges
+ * and nothing more.
  */
-export async function loadGraph(root, { build = true } = {}) {
+export async function loadGraph(root, { build = true, task = '', embed = false } = {}) {
   if (build) {
     try {
       await reindex(root);
@@ -119,12 +128,13 @@ export async function loadGraph(root, { build = true } = {}) {
       };
     }
   }
+  const wantFts = String(task ?? '').trim().length > 0;
   const [files, symbols, edges, fts, embeddings] = await Promise.all([
     readFiles(root),
     readSymbols(root),
     readEdges(root),
-    readFts(root),
-    readEmbeddings(root),
+    wantFts ? readFts(root) : Promise.resolve([]),
+    embed === true ? readEmbeddings(root) : Promise.resolve([]),
   ]);
   // A present index that cannot be read is named, not served as empty
   // (review 0003 Q44): `cold` is "nothing here", `broken` is "something is

package/src/commands/mcp.mjs

@@ -9,17 +9,14 @@
 // misconfigured the command needs to be able to ask what it exposes without hanging, and
 // a command that only speaks when spoken to cannot answer that.
 
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { TOOLS } from '../mcp/tools.mjs';
 import { PROTOCOL_VERSION, SUPPORTED_VERSIONS, serve } from '../mcp/server.mjs';
 import { CLI } from '../name.mjs';
+import { packageVersion } from '../package-version.mjs';
 
 export async function mcpCommand(positional, flags) {
-  const { version } = await packageVersion();
+  const version = packageVersion();
 
   if (flags.list === true) {
     if (isJson(flags)) {
@@ -53,7 +50,6 @@ export async function mcpCommand(positional, flags) {
         '',
         `serve them with: ${positional[0] ?? `${CLI} mcp`}`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
@@ -63,16 +59,4 @@ export async function mcpCommand(positional, flags) {
   } catch (error) {
     return fail(`mcp transport failed: ${error.message}`, EXIT.FAIL, `run: ${CLI} mcp --list to check the surface loads`);
   }
-}
-
-async function packageVersion() {
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkg = JSON.parse(await readFile(join(here, '..', '..', 'package.json'), 'utf8'));
-    return { version: pkg.version };
-  } catch {
-    // A missing version must not stop the server: the client already knows which
-    // build it launched, and a hard failure here would look like a protocol bug.
-    return { version: 'unknown' };
-  }
 }

package/src/commands/pack.mjs

@@ -28,6 +28,7 @@ import {
 } from '../packs/manage.mjs';
 import { readManifest } from '../projection/manifest.mjs';
 import { diffField, emitDiffs } from '../diff.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function packCommand(sub, args, flags) {
   if (sub === 'new') return packNew(args, flags);
@@ -40,9 +41,13 @@ export async function packCommand(sub, args, flags) {
  * Where a lint or publish resolves its pack: the positional directory, the
  * `--root`, or the working directory. `hooks` reads the same three in the same
  * order, so the two commands cannot disagree about which directory was meant.
+ *
+ * The positional wins, as this always said it did. The code read `--root` first,
+ * so `pack lint .simt/packs/a --root ../b` judged `b` while the prose and the
+ * command's own usage promised `a` (review 0003 Q58).
  */
 function packDir(args, flags) {
-  return resolve(flags.root ?? args[0] ?? process.cwd());
+  return resolve(args[0] ?? commandRoot(flags));
 }
 
 /**
@@ -98,7 +103,7 @@ async function packNew(args, flags) {
     return fail(sourceProblem, EXIT.USAGE, 'a pack source names where the bytes come from: `npm:<package>` or `git+https://…`');
   }
 
-  const dir = join(resolve(flags.root ?? process.cwd()), name);
+  const dir = join(resolve(commandRoot(flags)), name);
   const files = scaffoldPack({ name, source });
   const { apply, dryRun } = writeMode(flags);
   // A scaffold always creates into a directory that must not exist, so every
@@ -129,7 +134,6 @@ async function packNew(args, flags) {
         '',
         dryRun ? 'DRY-RUN  no files written' : `PLAN     nothing written; apply with: ${CLI} pack new ${name} --source ${source} --yes`,
       ].join('\n'),
-      { maxBytes: flags.maxBytes ?? 0 },
     );
     // After the report: the report says what, the diff shows it (R50).
     emitDiffs(diffs, flags);
@@ -149,7 +153,6 @@ async function packNew(args, flags) {
       '',
       `WROTE    ${files.length} scaffold file(s); write the rule, then: ${CLI} pack lint ${dir}`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
@@ -187,7 +190,7 @@ async function packLint(args, flags) {
     lines.push(`                        remedy: ${f.remedy}`);
   }
   lines.push('', ok ? 'PASSED   the pack is well-formed' : `FAILED   ${findings.length} finding(s)`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return ok ? EXIT.OK : EXIT.FAIL;
 }
 
@@ -247,7 +250,7 @@ async function packPublish(args, flags) {
   } else {
     lines.push('', `FAILED   ${result.findings.length} finding(s)`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   if (result.ok && apply && result.published) {
     note(`note     never committed or pushed by this tool (ADR-001); the registry now has the bytes, the repos still need vendoring`);
   }

package/src/commands/plan.mjs

@@ -3,12 +3,13 @@ import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.m
 import { formatCounts, planDone, planNext, planStatus } from '../plan/index.mjs';
 import { diffField, emitDiffs } from '../diff.mjs';
 import { CLI } from '../name.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 // Preview unless --yes, and --dry-run wins even then. A tracker row marked done
 // for a commit that was never written is a claim the next reader will believe.
 
 export async function planCommand(sub, args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (sub === 'status') return runStatus(root, flags);
   if (sub === 'next') return runNext(root, args[0] ?? null, flags);
   if (sub === 'done') {
@@ -35,7 +36,7 @@ async function runStatus(root, flags) {
   }
   lines.push('', `total    ${formatCounts(result.totals, result.stateOrder) || '-'}`);
   lines.push(`ready    ${result.ready}`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -55,7 +56,7 @@ async function runNext(root, id, flags) {
         lines.push(`  ${row.id}  ${row.doc}  depends on: ${row.dependsOn || '(none)'}${unknown}`);
       }
     }
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
   const next = result.next;
@@ -68,7 +69,7 @@ async function runNext(root, id, flags) {
     '',
     next.section || '(no section for this id)',
   ];
-  emit(head.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(head.join('\n'));
   return EXIT.OK;
 }
 
@@ -104,7 +105,7 @@ async function runDone(root, id, sha, flags) {
   }
   if (result.evidenceRecorded) lines.push(`evidence ${result.sha}${result.test ? `  test: ${result.test}` : ''}`);
   else if (result.evidenceNote) lines.push(`note     ${result.evidenceNote}`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);
   return EXIT.OK;

package/src/commands/plugin.mjs

@@ -10,6 +10,7 @@ import { EXIT, emit, emitJson, fail, isJson, writeMode } from '../output/index.m
 import { CLI } from '../name.mjs';
 import { buildPackage, PLUGIN_KINDS } from '../plugins.mjs';
 import { diffField, emitDiffs } from '../diff.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function pluginCommand(args, flags) {
   const kind = args[0];
@@ -27,7 +28,7 @@ export async function pluginCommand(args, flags) {
   }
 
   const { apply } = writeMode(flags);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   const plan = await buildPackage(kind, { root, out, apply });
 
   // The `--diff` pairs: the generated files, created or refreshed (R50). The
@@ -68,7 +69,6 @@ export async function pluginCommand(args, flags) {
         ? `WROTE    ${plan.files.length} generated file(s) plus the runtime`
         : `PLAN     nothing written; apply with: ${CLI} plugin ${kind} --out ${out} --yes`,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   // After the report: the report says what, the diff shows it (R50).
   emitDiffs(diffs, flags);

package/src/commands/prbody.mjs

@@ -12,9 +12,10 @@
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { buildPrBody, renderPrBody } from '../prbody.mjs';
+import { commandRoot } from '../repo-root.mjs';
 
 export async function prBodyCommand(args, flags) {
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   if (args.length > 0) {
     return fail(`pr-body takes no positional arguments`, EXIT.USAGE, `run: ${CLI} pr-body [--base <ref>]`);
   }
@@ -36,10 +37,9 @@ export async function prBodyCommand(args, flags) {
         verdict: report.verdict,
         unreviewed: report.unreviewed,
       },
-      { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 },
     );
     return EXIT.OK;
   }
-  emit(renderPrBody(report), { maxBytes: flags.maxBytes ?? 0 });
+  emit(renderPrBody(report));
   return EXIT.OK;
 }

package/src/commands/repoindex.mjs

@@ -2,15 +2,15 @@
 // content: it is gitignored, and a second run with the same blobs writes the same
 // rows (ADR-089).
 
-import { execFile } from 'node:child_process';
-
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { CLI } from '../name.mjs';
 import { JSONL_FILE, SQLITE_FILE, reindex } from '../index/store.mjs';
+import { commandRoot } from '../repo-root.mjs';
+import { git } from '../sys/git.mjs';
 
 export async function indexCommand(args, flags) {
   if (args.length > 0) return fail(`unknown index argument ${args[0]}`, EXIT.USAGE, `run: ${CLI} index`);
-  const root = flags.root ?? process.cwd();
+  const root = commandRoot(flags);
   let result;
   try {
     result = await reindex(root, {
@@ -31,7 +31,7 @@ export async function indexCommand(args, flags) {
   const ignored = await isIgnored(root, file);
   const payload = { ok: true, command: 'index', root, file, ignored, ...result };
   if (isJson(flags)) {
-    emitJson(payload, { pretty: flags.pretty === true, maxBytes: flags.maxBytes ?? 0 });
+    emitJson(payload);
     return EXIT.OK;
   }
   const lines = [
@@ -46,14 +46,15 @@ export async function indexCommand(args, flags) {
   ];
   if (result.parsers === 'missing') lines.push('note     index.parsers did not load, so the built-in extractors ran');
   if (!ignored) lines.push(`note     ${file} is not gitignored, and the cache is not meant to be committed`);
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
-function isIgnored(root, file) {
-  return new Promise((resolve) => {
-    execFile('git', ['check-ignore', '-q', '--', file], { cwd: root }, (error) => {
-      resolve(!error);
-    });
-  });
+async function isIgnored(root, file) {
+  try {
+    await git(root, ['check-ignore', '-q', '--', file]);
+    return true;
+  } catch {
+    return false;
+  }
 }

package/src/commands/review.mjs

@@ -23,7 +23,7 @@ export async function reviewCommand(args, flags, commands = []) {
   if (typeof result === 'number') return result;
 
   if (isJson(flags)) {
-    emitJson(result, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson(result);
     return EXIT.OK;
   }
 
@@ -60,6 +60,6 @@ export async function reviewCommand(args, flags, commands = []) {
   }
   if (result.metric) lines.push(`metric    ${result.metric.note}`);
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }

package/src/commands/rules.mjs

@@ -15,7 +15,11 @@
 // reviewer needs and exactly the fact an empty output would hide.
 
 import { readdir } from 'node:fs/promises';
+import { repoContext } from '../context.mjs';
 import { join } from 'node:path';
+import { renderDecisionsIndex } from '../decisions/index-doc.mjs';
+import { applyPlan, change } from '../write/plan.mjs';
+import { readBefore } from '../diff.mjs';
 import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { loadRules, select } from '../projection/project.mjs';
 import { loadMdcRules } from '../projection/mdc.mjs';
@@ -49,8 +53,8 @@ function sorted(rules) {
   return [...rules].sort((a, b) => a.id.localeCompare(b.id));
 }
 
-async function load(root) {
-  const rules = await loadRules(root ?? null);
+async function load(root, ctx = repoContext(root)) {
+  const rules = await ctx.rules();
   const broken = rules.filter((r) => r.error);
   return { rules: [...rules, ...(await loadPerSurfaceRules())], broken };
 }
@@ -153,12 +157,12 @@ export async function listCommand(args, flags) {
     if (locals.length > 0) lines.push('', `local profiles come from ${locals.map((r) => r.source).join(', ')}`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return broken.length === 0 ? EXIT.OK : EXIT.FAIL;
 }
 
-async function selectionFor(rules, root) {
-  const { stack, facts } = await fingerprint(root);
+async function selectionFor(rules, root, ctx = repoContext(root)) {
+  const { stack, facts } = await ctx.fingerprint();
   const { selected, notes } = select(rules, stack, facts);
   return { selected: new Set(selected.map((r) => r.id)), notes };
 }
@@ -210,9 +214,11 @@ async function loadDecisionsFor(root, all) {
 }
 
 /** The catalogue both surfaces answer from: every rule, its decisions, and the selection. */
-export async function rulesCatalogue(root, { selectFor = null } = {}) {
-  const { rules, broken } = await load(root);
-  const selection = selectFor ? await selectionFor(rules, selectFor) : null;
+export async function rulesCatalogue(root, { selectFor = null, ctx = null } = {}) {
+  const { rules, broken } = await load(root, ctx ?? repoContext(root));
+  // `selectFor` is a different repository: the caller asked for the catalogue here and
+  // the selection there, so it gets its own context rather than this repository answer.
+  const selection = selectFor ? await selectionFor(rules, selectFor, repoContext(selectFor)) : null;
   return {
     rules: sorted(rules).map((r) => ({
       id: r.id,
@@ -236,8 +242,8 @@ export async function rulesCatalogue(root, { selectFor = null } = {}) {
  * The provenance facts for one rule or one decision record, in the shape the
  * JSON documents carry. Text renders from the same facts; nothing re-derives.
  */
-export async function rulesWhyFacts(root, what, { all = false } = {}) {
-  const { rules } = await load(root);
+export async function rulesWhyFacts(root, what, { all = false, ctx = null } = {}) {
+  const { rules } = await load(root, ctx ?? repoContext(root));
   if (/^ADR-\d{3,}$/i.test(what)) {
     const id = what.toUpperCase();
     const { ok, decisions, errors, origins } = await loadDecisionsFor(root, all);
@@ -312,7 +318,7 @@ export async function showCommand(args, flags) {
 
   const adrs = citations(rule.body);
   if (isJson(flags)) {
-    emitJson({ ok: !rule.error, ...rule, adrs }, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: !rule.error, ...rule, adrs });
     return rule.error ? EXIT.FAIL : EXIT.OK;
   }
 
@@ -329,7 +335,6 @@ export async function showCommand(args, flags) {
       '',
       rule.body,
     ].join('\n'),
-    { maxBytes: flags.maxBytes ?? 0 },
   );
   return rule.error ? EXIT.FAIL : EXIT.OK;
 }
@@ -370,7 +375,7 @@ function ruleDirection(facts, flags) {
       '  this rule cites no decision, so nothing settles it and nothing can overturn it.',
       '  Either cite the ADR that produced it, or accept that it is this repo\'s own policy.',
     );
-    emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+    emit(lines.join('\n'));
     return EXIT.OK;
   }
 
@@ -395,7 +400,7 @@ function ruleDirection(facts, flags) {
     lines.push('', `shares a decision with ${facts.others.join(', ')}`);
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }
 
@@ -486,7 +491,7 @@ function adrDirection(facts, flags) {
     );
   }
 
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   // A superseded record is not a failure; it is the supersession rule working.
   // The caller asked a question and got a true answer.
   return EXIT.OK;
@@ -519,6 +524,22 @@ export async function decisionsCommand(args, flags) {
       file: d.file,
     }));
 
+  // The index is output, not authorship (review 0003 Q91): the table is rendered from
+  // the same records this command lists, so a new ADR cannot leave it behind. The
+  // write is journaled like every other repo-file write, so `undo` restores the old
+  // table - the index is not internal state even though it is generated.
+  if (flags.yes === true) {
+    const rootDir = root ?? process.cwd();
+    const index = join(rootDir, 'docs', 'decisions-index.md');
+    await applyPlan(
+      rootDir,
+      [change({ path: index, before: await readBefore(index), after: renderDecisionsIndex(rows), owner: 'rules decisions', reason: 'the index follows the decision files' })],
+      { mode: { apply: true }, label: 'rules decisions' },
+    );
+    emit(`wrote docs/decisions-index.md (${rows.length} decisions)`);
+    return EXIT.OK;
+  }
+
   if (isJson(flags)) {
     emitJson({ ok: true, command: 'rules decisions', root, decisions: rows });
     return EXIT.OK;
@@ -534,6 +555,6 @@ export async function decisionsCommand(args, flags) {
     const head = r.status.length > 80 ? `${r.status.slice(0, 80)}...` : r.status;
     lines.push(`${r.id.padEnd(8)}  ${r.origin.padEnd(7)}  ${r.title} — ${head}`);
   }
-  emit(lines.join('\n'), { maxBytes: flags.maxBytes ?? 0 });
+  emit(lines.join('\n'));
   return EXIT.OK;
 }