simt-dev 0.2.0 → 0.2.2

package/src/commands/init.mjs

@@ -11,7 +11,7 @@
 //   2. scan for conflicts  does it contradict a ruling
 //   3. block on conflicts  unless --accept-conflicts
 //   4. plan everything     manifest + region, dry
-//   5. branch and tag      a named escape hatch, before the first write
+//   5. branch and tag      an opt-in escape hatch (--backup), before the first write
 //   6. write               only with --yes
 // Never commits, never pushes (ADR-001).
 
@@ -20,7 +20,7 @@ import { promisify } from 'node:util';
 import { mkdir, readFile, symlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
-import { EXIT, emit, fail, isJson, note } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson, note } from '../output/index.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { rulePaths, scanDocument, summarise } from '../projection/conflicts.mjs';
 import { MANIFEST, buildManifest, manifestPath, readManifest, writeManifest, planGates } from '../projection/manifest.mjs';
@@ -44,6 +44,7 @@ import { plan, provenanceDigest, PRIMARY_TARGET, LOCAL_PROFILE_DIR } from '../pr
 import { parse as parseRegion } from '../projection/markers.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
+import { packageVersion, hasNpm } from '../package-version.mjs';
 
 const run = promisify(execFile);
 
@@ -59,6 +60,11 @@ export async function initCommand(positional, flags) {
   }
 
   const sha = await provenanceDigest();
+  // The release this adoption records, and the kind of repository it is adopting: the
+  // version goes into the manifest pin and the rendered gate, and the kind decides how
+  // a repository without node_modules obtains the binary in CI.
+  const version = packageVersion();
+  const npm = await hasNpm(root);
   const existing = await readManifest(root);
   const { manifest: current, exists, error } = existing;
   if (error) {
@@ -70,8 +76,12 @@ export async function initCommand(positional, flags) {
   // a repository declared five and could run two, which would have blocked every
   // commit once hooks were installed.
   const capability = await readCapability(root);
-  const { dropped } = planGates(detected.stack, capability);
-  const manifest = buildManifest({ root, stack: detected.stack, sha, existing: current, capability });
+  // `facts` carries the ecosystem rows (has-cargo-toml, ...) — the same signal set that
+  // selects this repo's profiles, so one marker file reaches both the region the reader
+  // gets and the gates its commits run. Without it the ecosystem rows never fire here
+  // and a fresh Rust repo is adopted with gates it cannot run.
+  const { dropped, commands } = planGates(detected.stack, capability, detected.facts);
+  const manifest = buildManifest({ root, stack: detected.stack, sha, version, existing: current, capability, facts: detected.facts });
   const findings = await scanRepo(root);
   const summary = summarise(findings);
   const projected = await plan(root, flags);
@@ -141,6 +151,12 @@ export async function initCommand(positional, flags) {
     // adoption: an existing manifest keeps its gates on purpose, so its drops would
     // describe proposals that were never made.
     droppedGates: exists ? [] : dropped,
+    // Commands a FRESH manifest declares under gates.commands. The plan must show them:
+    // a command that lands in the manifest without appearing here is a silent write,
+    // and the reader would approve it by reading the diff afterwards — the review step
+    // this tool exists to make unnecessary. On an existing manifest nothing is seeded
+    // (the repo's declaration owns that field), so the empty list is deliberate.
+    seededCommands: exists ? [] : Object.entries(commands).map(([gate, command]) => ({ gate, command })),
     surfaces: projected.surfaces,
     surfaceSource: projected.surfaceSource,
     pointers: pointerPlan.map((p) => ({ file: p.file, to: p.to, readers: p.readers, state: p.state })),
@@ -193,6 +209,24 @@ export async function initCommand(positional, flags) {
     git: null,
   };
 
+  // A surface this build does not know cannot be written to. Checked before the rule
+  // branch, and named for what it is: `init --surfaces` accepts a list, a reader
+  // mistypes one, and the misspelling used to be reported as an unprojectable rule with
+  // a remedy about substitution keys — the one problem on this path that had no
+  // substitution keys anywhere near it.
+  const surfaceProblems = projected.surfaceProblems ?? [];
+  if (surfaceProblems.length > 0) {
+    payload.ok = false;
+    payload.blockedBy = 'surface-problem';
+    for (const p of surfaceProblems) note(`PROBLEM  ${p}`);
+    if (isJson(flags)) emitJson(payload);
+    return fail(
+      `${surfaceProblems.length} surface(s) cannot be resolved (${surfaceProblems[0]})`,
+      EXIT.FAIL,
+      `pass a known surface id to --surfaces, or omit it to take the default`,
+    );
+  }
+
   // A `.mdc` rule that cannot render is a defect in this build. Adopting a repo
   // without it would leave the family half-retired, and the user would have no way
   // to tell which half from the diff.
@@ -200,7 +234,7 @@ export async function initCommand(positional, flags) {
     payload.ok = false;
     payload.blockedBy = 'mdc-problem';
     for (const p of mdcProblems) note(`PROBLEM  ${p}`);
-    if (isJson(flags)) emit(`${JSON.stringify(payload, null, 2)}\n`);
+    if (isJson(flags)) emitJson(payload);
     return fail(
       `${mdcProblems.length} canonical .mdc rule(s) cannot be projected (${mdcProblems[0]})`,
       EXIT.FAIL,
@@ -215,9 +249,9 @@ export async function initCommand(positional, flags) {
     payload.ok = false;
     payload.blockedBy = 'conflict';
     if (isJson(flags)) {
-      emit(`${JSON.stringify(payload, null, 2)}\n`);
+      emitJson(payload);
     } else {
-      emit(render(payload, manifest));
+      emit(render(payload, manifest, { npm, version }));
       note('');
       note(
         `blocked  ${summary.conflicts} conflict${summary.conflicts === 1 ? '' : 's'}; nothing written`,
@@ -237,8 +271,8 @@ export async function initCommand(positional, flags) {
   if (malformed.length > 0) {
     payload.ok = false;
     payload.blockedBy = 'malformed-region';
-    if (isJson(flags)) emit(`${JSON.stringify(payload, null, 2)}\n`);
-    else emit(render(payload, manifest));
+    if (isJson(flags)) emitJson(payload);
+    else emit(render(payload, manifest, { npm, version }));
     return fail(
       `${malformed.length} target(s) have a malformed generated region (${malformed[0].file}: ${malformed[0].reason})`,
       EXIT.FAIL,
@@ -248,9 +282,9 @@ export async function initCommand(positional, flags) {
 
   // Step 4/5: report everything, then make changes only when told to.
   if (isJson(flags)) {
-    if (!apply) emit(`${JSON.stringify(payload, null, 2)}\n`);
+    if (!apply) emitJson(payload);
   } else {
-    emit(render(payload, manifest));
+    emit(render(payload, manifest, { npm, version }));
   }
   if (!apply) {
     note('');
@@ -262,9 +296,40 @@ export async function initCommand(positional, flags) {
     return EXIT.OK;
   }
 
-  const git = await establishEscapeHatch(root);
+  // The escape hatch is opt-in (ADR-063): plan 0002 §8.2 item 3 said "always", and the
+  // tool complied, but consumers kept reporting the branch switch as a surprise. The
+  // default now writes in place on the branch the reader already has — `git diff` still
+  // shows the full adoption, and nothing is tagged or branched. `--backup` restores the
+  // tag and the branch for readers who want the named undo path.
+  const git = flags.backup
+    ? await establishEscapeHatch(root)
+    : { branch: null, tag: null, from: null, notes: [] };
   payload.git = git;
   for (const message of git.notes) note(`note     ${message}`);
+  if (!flags.backup) {
+    note(
+      'in place   no backup tag or adopt branch created; the adoption is written on your current branch - git diff shows it and git checkout -- . discards it; re-run with --backup for the tag and the branch',
+    );
+  }
+  // The operations that succeeded, not just the ones that failed.
+  //
+  // With --backup, `init` moves the reader onto a different branch and writes a tag
+  // into their repository. Both were once reported only under `--json`, so the run —
+  // the one almost everybody reads — did not say that the branch under them had
+  // changed. A reader who ran the documented escape hatch and then committed would be
+  // committing to a branch they had not chosen, and nothing in the output told them
+  // that had happened.
+  //
+  // The plan's heading is "Nothing is silent", so whatever the run does to git state —
+  // or deliberately does not — the output names it and the command that undoes it.
+  // `notes` carried the failures because a failure is the kind of thing an operator
+  // notices; a success is not.
+  if (git.tag !== null) {
+    note(`tagged   ${git.tag} at the pre-adoption commit; \`git reset --hard ${git.tag}\` returns this repository to what it was`);
+  }
+  if (git.branch !== null && git.from !== null) {
+    note(`branch   switched to ${git.branch}; ${git.from} is untouched and \`git checkout ${git.from}\` returns to it`);
+  }
 
   await writeManifest(root, manifest);
   note(`wrote    ${MANIFEST_FILE} (${manifestAction})`);
@@ -304,7 +369,7 @@ export async function initCommand(positional, flags) {
   // guaranteed to be misled.
   if (payload.ci.action === 'create') {
     await mkdir(dirname(join(root, payload.ci.file)), { recursive: true });
-    await writeFile(join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own }));
+    await writeFile(join(root, payload.ci.file), renderWorkflow({ own: payload.ci.own, npm, version }));
     note(`wrote    ${payload.ci.file} (create; yours to edit from here, simt-dev will not rewrite it)`);
   }
   if (payload.dependabot.action === 'create') {
@@ -378,7 +443,7 @@ export async function initCommand(positional, flags) {
   }
   payload.written = true;
 
-  if (isJson(flags)) emit(`${JSON.stringify(payload, null, 2)}\n`);
+  if (isJson(flags)) emitJson(payload);
 
   note('');
   note(`next     ${CLI} sync --yes, then ${CLI} check in CI. Commit when you are happy with the diff.`);
@@ -423,13 +488,14 @@ async function scanRepo(root) {
 }
 
 /**
- * A named escape hatch before the first write, per plan 0001. Both operations are
- * best-effort: a repo that is not a git repo, or has no commits yet, must still be
+ * The opt-in escape hatch before the first write, taken when --backup is passed
+ * (ADR-063 amended plan 0002 §8.2 item 3 from "always" to on request). Both operations
+ * are best-effort: a repo that is not a git repo, or has no commits yet, must still be
  * adoptable. Failure is reported as a note rather than blocking, because refusing
  * to initialise an unborn repo would be worse than proceeding without a backup.
  */
 async function establishEscapeHatch(root) {
-  const result = { branch: null, tag: null, notes: [] };
+  const result = { branch: null, tag: null, from: null, notes: [] };
   const isRepo = await git(root, ['rev-parse', '--is-inside-work-tree']);
   if (!isRepo.ok) {
     result.notes.push('not a git work tree; no backup branch or tag created');
@@ -457,6 +523,10 @@ async function establishEscapeHatch(root) {
 
   const current = await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']);
   if (current.ok && current.stdout.trim() !== ADOPT_BRANCH) {
+    // Recorded rather than re-read by the caller: only this function knows what the
+    // branch was before it moved it, and a second `rev-parse` would answer with the new
+    // value and make every "you were on X" line read as "you were on Y".
+    result.from = current.stdout.trim();
     const branch = await git(root, ['checkout', '-b', ADOPT_BRANCH]);
     if (branch.ok) result.branch = ADOPT_BRANCH;
     else result.notes.push(`could not create branch ${ADOPT_BRANCH}: ${branch.stderr.trim()}`);
@@ -477,7 +547,7 @@ async function git(cwd, args) {
 }
 
 /** Every line is a decision with a reason. Nothing is silent. */
-function render(payload, manifest) {
+function render(payload, manifest, { npm = true, version } = {}) {
   const lines = [
     `repo        ${payload.root}`,
     `stack       ${payload.stack.length > 0 ? payload.stack.join(', ') : '(undetected)'}`,
@@ -518,6 +588,12 @@ function render(payload, manifest) {
     lines.push(`  ${'dropped'.padEnd(9)} gate ${d.gate}: ${d.why}`);
     lines.push(`            remedy: ${d.remedy}`);
   }
+  // A seed is a write, and the same rule as for dropped gates applies: the reader must
+  // see the line or they approve it from the diff afterwards. Naming the manifest field
+  // keeps the line actionable — this is where the reader edits it if the default is wrong.
+  for (const s of payload.seededCommands ?? []) {
+    lines.push(`  ${'seeded'.padEnd(9)} gates.commands["${s.gate}"] = ${s.command}`);
+  }
   lines.push(
     `  ${'profiles'.padEnd(9)} ${LOCAL_PROFILE_DIR}/*.md  ` +
       `repo-local profiles are selected by the same matcher (ADR-013)`,
@@ -532,8 +608,12 @@ function render(payload, manifest) {
     // on it would understate the edit the reader is approving. A baseline is the
     // opposite case to AGENTS.md in the one way that matters here — it is placed FIRST,
     // so the repo's own settings below it keep winning (ADR-025).
+    // A nested `apps/web/AGENTS.md` is the same kind of target as the root's, so the
+    // test is the suffix and not the exact path: a monorepo's package region holds
+    // hand-written content too, and describing it as a generated rule file would be
+    // the wrong contract for a reader who has prose above the markers.
     const caption =
-      target.file === PRIMARY_TARGET
+      target.file.endsWith(PRIMARY_TARGET)
         ? 'hand-written content outside the markers is never modified'
         : target.kind === 'baseline'
           ? 'a region placed first, so your own settings below it still win (ADR-025)'
@@ -560,7 +640,7 @@ function render(payload, manifest) {
   // a reader can tell "this repo does not use GitHub Actions" from "this repo was
   // not offered the gate".
   if (payload.ci.action === 'create') {
-    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own }).length} bytes`);
+    lines.push(`  ${'create'.padEnd(9)} ${payload.ci.file}  ${renderWorkflow({ own: payload.ci.own, npm, version }).length} bytes`);
     lines.push(
       payload.ci.own
         ? `            this repository is simt-dev's own; ${CLI} ci --yes refreshes this copy when the gate changes`

package/src/commands/mcp.mjs

@@ -13,9 +13,9 @@ import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
-import { EXIT, emit, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { TOOLS } from '../mcp/tools.mjs';
-import { PROTOCOL_VERSION, serve } from '../mcp/server.mjs';
+import { PROTOCOL_VERSION, SUPPORTED_VERSIONS, serve } from '../mcp/server.mjs';
 import { CLI } from '../name.mjs';
 
 export async function mcpCommand(positional, flags) {
@@ -23,12 +23,27 @@ export async function mcpCommand(positional, flags) {
 
   if (flags.list === true) {
     if (isJson(flags)) {
-      emit(`${JSON.stringify({ ok: true, protocolVersion: PROTOCOL_VERSION, version, tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) }, null, 2)}\n`);
+      emitJson({
+        ok: true,
+        protocolVersion: PROTOCOL_VERSION,
+        protocolVersions: SUPPORTED_VERSIONS,
+        version,
+        // The output schema and the read-only annotation travel with the tool here too:
+        // a reader listing the surface should see the same contract a call returns,
+        // rather than discovering the shape by making one.
+        tools: TOOLS.map(({ name, description, inputSchema, outputSchema, annotations }) => ({
+          name,
+          description,
+          inputSchema,
+          ...(outputSchema ? { outputSchema } : {}),
+          annotations,
+        })),
+      });
       return EXIT.OK;
     }
     emit(
       [
-        `simt-dev ${version} - MCP surface over stdio (protocol ${PROTOCOL_VERSION})`,
+        `simt-dev ${version} - MCP surface over stdio (protocols ${SUPPORTED_VERSIONS.join(', ')})`,
         '',
         `${TOOLS.length} read-only tools:`,
         ...TOOLS.map((t) => `  ${t.name.padEnd(16)} ${t.description.split('.')[0]}`),
@@ -44,7 +59,7 @@ export async function mcpCommand(positional, flags) {
   }
 
   try {
-    return await serve(TOOLS, { version });
+    return await serve(TOOLS, { packageVersion: version });
   } catch (error) {
     return fail(`mcp transport failed: ${error.message}`, EXIT.FAIL, `run: ${CLI} mcp --list to check the surface loads`);
   }

package/src/commands/rules.mjs

@@ -14,8 +14,9 @@
 // one, because "this rule has no decision behind it" is exactly the fact a
 // reviewer needs and exactly the fact an empty output would hide.
 
-import { EXIT, emit, fail, isJson } from '../output/index.mjs';
+import { EXIT, emit, emitJson, fail, isJson } from '../output/index.mjs';
 import { loadRules, select } from '../projection/project.mjs';
+import { loadMdcRules } from '../projection/mdc.mjs';
 import { fingerprint } from '../resolve/fingerprint.mjs';
 import { byId, citations, loadDecisions, redactEstate } from '../decisions/index.mjs';
 import { nearMatches } from '../resolve/near.mjs';
@@ -23,9 +24,18 @@ import { CLI } from '../name.mjs';
 
 const kb = (bytes) => `${(bytes / 1000).toFixed(1)}k`;
 
-/** `simt-applies` is the string "always" for core and an array for profiles. */
+/**
+ * `simt-applies` is the string "always" for core and an array for profiles.
+ *
+ * An opt-in rule has an EMPTY array, and `-` is a true reading of that which answers
+ * none of the questions a reader has. `simt-opt-in` is why it is empty — detection cannot
+ * distinguish a repository with the problem from one without it, so the repository
+ * declares it — and that is the fact worth printing. It only became visible when the
+ * per-surface rules entered this catalogue; before that the rule was not listed at all.
+ */
 function appliesLabel(rule) {
   if (rule.applies === 'always') return 'always';
+  if (rule.optIn === true) return 'opt-in (the repo declares it)';
   if (Array.isArray(rule.applies)) return rule.applies.join(',') || '-';
   return '-';
 }
@@ -38,7 +48,37 @@ function sorted(rules) {
 async function load(root) {
   const rules = await loadRules(root ?? null);
   const broken = rules.filter((r) => r.error);
-  return { rules, broken };
+  return { rules: [...rules, ...(await loadPerSurfaceRules())], broken };
+}
+
+/**
+ * The `.mdc` rules, in the shape this file's three commands print.
+ *
+ * `loadRules` reads `rules/*.md` and `rules/stacks/*.md`, which is every rule that is a
+ * *stack profile* — and the four per-surface rules are not that. They are projected by
+ * `ruleBodies` inside `desiredRegion` rather than by `select`, so they were invisible to
+ * `rules list`, `rules show` and `rules why`: a reader could be told by an agent to run
+ * `simt rules why test-gate` and be met with "no rule with that id", for a rule that was
+ * in their own `AGENTS.md` at the time.
+ *
+ * Deliberately NOT added to `loadRules`. That function's result is `select`ed and
+ * `render`ed into the region, so putting these there would project every one of them
+ * twice — once as a profile section and once as `## Process: <id>` — which is the
+ * duplication ADR-046 exists to prevent. The catalogue is the right layer for this: it is
+ * a view, and a view may be wider than what one projection writes.
+ */
+async function loadPerSurfaceRules() {
+  const mdc = await loadMdcRules();
+  return mdc.map((r) => ({
+    ...r,
+    // These have no `simt-title`; their `description` is what a reader sees in the
+    // generated file, so it is the title here rather than a column of blanks.
+    title: r.title ?? r.description ?? null,
+    // `mdc` rather than `central`: the column exists so a reader can tell where a rule
+    // came from, and "central" is true of all of them and useless for this distinction.
+    origin: 'per-surface',
+    fallback: false,
+  }));
 }
 
 // --- list ---------------------------------------------------------------------
@@ -52,30 +92,25 @@ export async function listCommand(args, flags) {
   const selection = root ? await selectionFor(rules, root) : null;
 
   if (isJson(flags)) {
-    emit(
-      `${JSON.stringify(
-        {
-          ok: broken.length === 0,
-          command: 'rules list',
-          root,
-          rules: sorted(rules).map((r) => ({
-            id: r.id,
-            title: r.title,
-            origin: r.origin,
-            source: r.source,
-            applies: r.applies,
-            fallback: r.fallback,
-            bytes: r.bytes,
-            error: r.error,
-            adrs: citations(r.body),
-            selected: selection ? selection.selected.has(r.id) : null,
-          })),
-          notes: selection?.notes ?? [],
-        },
-        null,
-        2,
-      )}\n`,
-      { maxBytes: flags.maxBytes ?? 0 },
+    emitJson(
+      {
+                ok: broken.length === 0,
+                command: 'rules list',
+                root,
+                rules: sorted(rules).map((r) => ({
+                  id: r.id,
+                  title: r.title,
+                  origin: r.origin,
+                  source: r.source,
+                  applies: r.applies,
+                  fallback: r.fallback,
+                  bytes: r.bytes,
+                  error: r.error,
+                  adrs: citations(r.body),
+                  selected: selection ? selection.selected.has(r.id) : null,
+                })),
+                notes: selection?.notes ?? [],
+              },
     );
     return broken.length === 0 ? EXIT.OK : EXIT.FAIL;
   }
@@ -148,7 +183,7 @@ export async function showCommand(args, flags) {
 
   const adrs = citations(rule.body);
   if (isJson(flags)) {
-    emit(`${JSON.stringify({ ok: !rule.error, ...rule, adrs }, null, 2)}\n`, { maxBytes: flags.maxBytes ?? 0 });
+    emitJson({ ok: !rule.error, ...rule, adrs }, { maxBytes: flags.maxBytes ?? 0 });
     return rule.error ? EXIT.FAIL : EXIT.OK;
   }
 
@@ -182,7 +217,7 @@ export async function whyCommand(args, flags) {
   if (!what) return fail('rules why needs a rule id or an ADR id', EXIT.USAGE, `usage: ${CLI} rules why <rule-id|ADR-NNN>`);
 
   const { rules, broken } = await load(flags.root ?? null);
-  const { ok, decisions, errors } = await loadDecisions();
+  const { ok, decisions, errors } = await loadDecisions({ all: flags.all === true });
   if (!ok) return fail(errors[0], EXIT.CONFIG, 'the decision records must be readable for provenance to work');
 
   return what.match(/^ADR-\d{3}$/i)
@@ -198,21 +233,16 @@ async function ruleDirection(id, rules, decisions, flags, broken) {
   const index = byId(decisions);
 
   if (isJson(flags)) {
-    emit(
-      `${JSON.stringify(
-        {
-          ok: true,
-          command: 'rules why',
-          rule: rule.id,
-          source: rule.source,
-          origin: rule.origin,
-          adrs: cited.map((c) => index.get(c) ?? { id: c, missing: true }),
-          uncited: cited.length === 0,
-        },
-        null,
-        2,
-      )}\n`,
-      { maxBytes: flags.maxBytes ?? 0 },
+    emitJson(
+      {
+                ok: true,
+                command: 'rules why',
+                rule: rule.id,
+                source: rule.source,
+                origin: rule.origin,
+                adrs: cited.map((c) => index.get(c) ?? { id: c, missing: true }),
+                uncited: cited.length === 0,
+              },
     );
     return EXIT.OK;
   }
@@ -273,22 +303,17 @@ async function adrDirection(adr, rules, decisions, flags) {
     // effective ruling is carried alongside rather than instead: the record asked about
     // is still named, and what is in force is named separately.
     const replacement = d.supersededBy ? decisions.find((x) => x.id === d.supersededBy) : null;
-    emit(
-      `${JSON.stringify(
-        {
-          ok: true,
-          command: 'rules why',
-          adr: d,
-          supersededBy: replacement ? { id: replacement.id, title: replacement.title } : null,
-          inForce: replacement
-            ? { id: replacement.id, status: replacement.status, summary: replacement.summary }
-            : { id: d.id, status: d.status, summary: d.summary },
-          rules: restates.map((r) => r.id),
-        },
-        null,
-        2,
-      )}\n`,
-      { maxBytes: flags.maxBytes ?? 0 },
+    emitJson(
+      {
+                ok: true,
+                command: 'rules why',
+                adr: d,
+                supersededBy: replacement ? { id: replacement.id, title: replacement.title } : null,
+                inForce: replacement
+                  ? { id: replacement.id, status: replacement.status, summary: replacement.summary }
+                  : { id: d.id, status: d.status, summary: d.summary },
+                rules: restates.map((r) => r.id),
+              },
     );
     return EXIT.OK;
   }
@@ -342,6 +367,17 @@ async function adrDirection(adr, rules, decisions, flags) {
   if (effective.summary.ruled.length > 0) {
     lines.push('', replacement ? 'ruled now' : 'ruled');
     for (const r of effective.summary.ruled) lines.push(`  - ${redactEstate(r)}`);
+    // The count, because the excerpt above is two rulings and a record may carry eight.
+    // Without it the header reads as a claim about everything the record settled, which
+    // is how a reader goes looking for a ruling that was never printed and concludes it
+    // does not exist.
+    const shown = effective.summary.ruled.length;
+    const total = effective.summary.rulingCount ?? shown;
+    if (total > shown) {
+      lines.push(
+        `  (${shown} of ${total} rulings shown; the rest: ${CLI} rules why ${effective.id} --all)`,
+      );
+    }
   }
   if (effective.summary.rejected.length > 0) {
     // The rejected alternatives are the part a reader cannot reconstruct. A ruling is