@rungs/cli 0.1.2 → 0.2.0

package/src/cli.ts

@@ -3,11 +3,14 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import { auditModules, loadAllModules } from './manifest.ts';
 import { detect, scanRepo } from './detect.ts';
-import { addModule, adoptableGates, registerGates, resolveInstallOrder, writeInstallRecord } from './add.ts';
+import { addModule, adoptableGates, blockedByParadigm, registerGates, resolveInstallOrder, writeInstallRecord } from './add.ts';
 import { render, writeReport, type Harness } from './render.ts';
 import { resolveParams } from './substitute.ts';
-import { appendLedger, ledgerQuestions, loadRegistry, runGates } from './check.ts';
+import { appendLedger, type GateRun, ledgerQuestions, loadRegistry, runGates, UnknownTierError } from './check.ts';
 import { applyUpgrade, eject, planUpgrade, PROFILES, readRecord, setupGit } from './lifecycle.ts';
+import { explain, IN_SCOPE as EXPLAINABLE } from './explain.ts';
+import { applyArchive, planArchive } from './backlog.ts';
+import { existsSync } from 'node:fs';
 import type { DetectResult, Manifest } from './types.ts';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -65,7 +68,7 @@ function cmdModules(showParams = false) {
   const issues = auditModules(mods);
   console.log();
   if (issues.length === 0) {
-    console.log(c.green('  audit clean') + c.dim(' — every parameter accounted for, every gate has a table and a why'));
+    console.log(c.green('  audit clean') + c.dim(' — every parameter accounted for; every gate has a table, a why, and a declared applicability'));
   } else {
     console.log(c.red(`  ${issues.length} issue(s):`));
     for (const i of issues) console.log(`    ${c.yellow(i.module)} ${c.dim(i.kind)} — ${i.detail}`);
@@ -74,7 +77,7 @@ function cmdModules(showParams = false) {
   return issues.length === 0 ? 0 : 1;
 }
 
-function cmdDoctor(target: string) {
+function cmdDoctor(target: string, doExplain = false) {
   const root = resolve(target);
   const mods = loadAllModules(MODULES);
   console.log(c.bold(`\nrungs doctor — ${root}\n`));
@@ -153,6 +156,11 @@ function cmdDoctor(target: string) {
   console.log(c.dim('  system is good, complete, or working — only that files are where a'));
   console.log(c.dim("  module's files would be. Signatures under-detect on purpose.\n"));
 
+  reportLedger(root);
+
+  if (doExplain) reportExplain(mods, results, root, files);
+  else advertiseAnalysis(results);
+
   // `doctor` is the command the README makes the entry point, and it used to stop on the sentence
   // above — fifteen `absent` lines and nothing to do next. The recommendation is deliberately a
   // **single** command, and never the maximal one: the brief names selling rung 5 to a rung-1 repo
@@ -186,6 +194,101 @@ function firstSentence(s: string): string {
   return s.trim().replace(/\s+/g, ' ').split(/(?<=\.)\s/)[0];
 }
 
+/**
+ * Say that the analysis exists, and how much of it there is. Never what it
+ * found (WI-049).
+ *
+ * `--explain` is the capability both external reviews called the strongest
+ * thing here, and plain `doctor` printed no occurrence of the string `explain`
+ * — it was reachable only from `--help`. WI-038 put the *findings* behind a flag
+ * for a measured reason: 114 on `hexguard` would bury the `Next` line that
+ * WI-005 exists to protect. The flag was never the problem; the silence was.
+ *
+ * **It reports scope, not findings, and it runs no engine.** The first version
+ * printed a finding count, which meant running the detectors on the plain path.
+ * Measured on `rift-forge` 2026-08-16: plain `doctor` went from **1.6s to
+ * 16.8s** warm — a 10× tax on the entry point to advertise a flag. WI-049's
+ * plan named this outcome in advance and named this fallback.
+ *
+ * So the number is the one detection already computed. It claims what it can
+ * prove: these are things the repo has, and our checks can read them. It does
+ * not claim anything was found, because finding out costs the 15 seconds.
+ */
+function advertiseAnalysis(results: DetectResult[]) {
+  const inScope = results.filter((r) => EXPLAINABLE.has(r.state)).length;
+  if (!inScope) return;
+
+  console.log(c.bold('  Analysis\n'));
+  console.log(`  ${inScope} of these are things this repo already has, and can be checked against it.`);
+  console.log(`  ${c.cyan('rungs doctor --explain')}   ${c.dim('— evidenced findings, and the incident behind each check')}\n`);
+}
+
+/**
+ * The defect half of `doctor` (WI-038). Every line carries a path and a count
+ * or a quote; there is no score, grade, bar, or maturity label anywhere, and
+ * there is not going to be — ADR-0005 tier C refuses composites permanently,
+ * and a single word over incommensurable signals is the purest form of the
+ * probe-encoding-a-guess the corpus warns about.
+ *
+ * The incident is attached to each detector rather than to each finding: it is
+ * why the check exists, not what was found, and repeating it per row would bury
+ * the evidence under the provenance.
+ */
+function reportExplain(mods: Manifest[], results: DetectResult[], root: string, files: string[]) {
+  const { reported, skipped, scope } = explain(mods, results, root, files);
+
+  console.log(c.bold('  What it also checked\n'));
+
+  if (!scope.length) {
+    console.log(c.dim('  Nothing — detectors run only over what this repo already has, and'));
+    console.log(c.dim('  detection found no equivalent of any module. There is nothing here to'));
+    console.log(c.dim('  check that would not be checking our conventions against your repo.\n'));
+    return;
+  }
+
+  const total = reported.reduce((n, r) => n + r.findings.length, 0);
+  console.log(
+    c.dim(`  ran the detectors for ${scope.length} module(s) this repo already has: `) + c.dim(scope.join(' ')) + '\n',
+  );
+
+  for (const r of reported) {
+    const n = r.findings.length;
+    console.log(`  ${c.yellow(r.gate.padEnd(34))} ${c.bold(String(n))} ${n === 1 ? 'finding' : 'findings'}`);
+    for (const f of r.findings.slice(0, 4)) {
+      console.log(c.dim(`      ${f.file ? `${f.file}: ` : ''}${f.message}`));
+    }
+    if (n > 4) console.log(c.dim(`      …and ${n - 4} more`));
+    if (r.why) console.log(c.dim(`      why: ${firstSentence(r.why)}`));
+    console.log();
+  }
+
+  if (!total) {
+    console.log(c.dim('  No detector fired. That is not a clean bill of health — see below.\n'));
+  }
+
+  // Pins. ADR-0005's rule that green must never read as verified applies with
+  // more force here than in the ledger: this pass runs our checks over content
+  // written to somebody else's conventions, and the honest failure mode is a
+  // sound finding in a frame the repo never adopted.
+  console.log(c.dim('  This is not an audit, and it is deliberately incomplete:'));
+  console.log(c.dim('  · Detectors ran only for modules this repo already has an equivalent of.'));
+  console.log(c.dim("  · They read rungs-shaped inputs. A finding may be true and framed against"));
+  console.log(c.dim('    a convention you never adopted — that is our defect, not yours.'));
+  if (skipped.command) {
+    console.log(c.dim(`  · ${skipped.command} command gate(s) not run. rungs does not execute commands in a repo it is only reading.`));
+  }
+  if (skipped.undeclared.length) {
+    console.log(c.dim(`  · ${skipped.undeclared.length} gate(s) never said whether they can read a repo like yours, so they did not: ${skipped.undeclared.join(' ')}`));
+  }
+  if (skipped.unimplemented.length) {
+    console.log(c.dim(`  · ${skipped.unimplemented.length} declared gate(s) have no engine and were skipped, never passed: ${skipped.unimplemented.join(' ')}`));
+  }
+  for (const e of skipped.errored) {
+    console.log(c.dim(`  · ${e.gate} could not run here (${e.message}) — a fact about this pass, not about your repo.`));
+  }
+  console.log();
+}
+
 function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harness[], stamp: string) {
   const mods = loadAllModules(MODULES);
   const { order, missing } = resolveInstallOrder(names, mods);
@@ -222,9 +325,74 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
   console.log(c.bold(`\nrungs add ${names.join(' ')} → ${root}${dryRun ? c.yellow('  (dry run)') : ''}\n`));
   if (pulled.length) console.log(c.dim(`  pulled in by dependency: ${pulled.map((m) => m.name).join(', ')}\n`));
 
+  // ADR-0004 state 5: a repo that solves this module's problem a different way
+  // gets the comparison and a stop, not an install beside what it already runs.
+  //
+  // The state existed in the ADR and in `doctor` and nowhere else, so `add`
+  // wrote straight over it — for every paradigm, since the CLI shipped
+  // (WI-043, from F-014). Measured 2026-08-16: a repo with `.github/ISSUE_TEMPLATE/`
+  // reported `backlog paradigm · external-tracker`, and `add backlog` then wrote
+  // `docs/`, `AGENTS.md`, `.ai/` and 12 gates without mentioning it once.
+  //
+  // Unlike `--confirm-threshold` above, this refusal **also applies under
+  // `--dry-run`**. A preview that installs what the real run refuses is a
+  // preview of a different command.
+  const scanned = scanRepo(root);
+  const paradigms = new Set(
+    order.map((m) => detect(m, root, scanned)).filter((r) => r.state === 'paradigm').map((r) => r.module),
+  );
+  const overridden = flags.has('--confirm-paradigm');
+  const blocked = overridden ? new Map<string, string>() : blockedByParadigm(order, paradigms);
+
+  // An override that prints nothing is indistinguishable from a detection that
+  // found nothing, and the two want opposite follow-ups.
+  if (overridden && paradigms.size) {
+    for (const name of paradigms) {
+      const p = detect(order.find((m) => m.name === name)!, root, scanned).paradigm!;
+      console.log(
+        c.yellow(`  ${name}: installing over an existing ${p.id}`) +
+          c.dim(` (${p.matched[0]}) — --confirm-paradigm`),
+      );
+    }
+    console.log(c.dim('      You will have two systems for one job. That is a choice, not a merge.\n'));
+  }
+
+  // Re-resolve from what survives rather than filtering `order` in place. A
+  // dependency is only ever pulled in *for* something; `add backlog` on an
+  // issue-tracker repo was still writing `instructions` and `gates`, which
+  // nobody asked for and which were pulled in solely for the module being
+  // refused. Recomputing the closure drops them, and keeps anything a *surviving*
+  // request still needs.
+  let toInstall = order;
+  if (blocked.size) {
+    for (const mod of order) {
+      const cause = blocked.get(mod.name);
+      if (!cause) continue;
+      if (cause === mod.name) {
+        const p = detect(mod, root, scanned).paradigm!;
+        console.log(c.yellow(`  ${mod.name}: this repo already does this another way — ${p.id}`));
+        console.log(c.dim(`      matched ${p.matched[0]}`));
+        for (const line of (p.note ?? '').trim().split('\n')) console.log(c.dim(`      ${line || ''}`));
+        if (p.compare) console.log(c.dim(`      compare: ${p.compare}`));
+      } else {
+        console.log(c.yellow(`  ${mod.name}: not installed — it requires ${cause}.`));
+      }
+    }
+    toInstall = resolveInstallOrder(names.filter((n) => !blocked.has(n)), mods).order;
+    const dropped = order.filter((m) => !toInstall.includes(m) && !blocked.has(m.name));
+    if (dropped.length) {
+      console.log(c.dim(`      ${dropped.map((m) => m.name).join(', ')} not written — pulled in only for the above`));
+    }
+    console.log(
+      c.dim(`\n  Pass --confirm-paradigm to install anyway.`) +
+        (toInstall.length ? c.dim(' Continuing with the rest.\n') : c.dim(' Nothing was written.\n')),
+    );
+    if (!toInstall.length) return 1;
+  }
+
   const installed: Manifest[] = [];
   const wrote = new Map<string, Set<string>>();
-  for (const mod of order) {
+  for (const mod of toInstall) {
     if (mod.threshold?.confirm && !dryRun && !flags.has('--confirm-threshold')) {
       console.log(
         c.yellow(`  ${mod.name}: requires ${mod.threshold.minimum}+ ${mod.threshold.metric}.`) +
@@ -300,9 +468,35 @@ function cmdRender(root: string, harnesses: Harness[], stamp: string) {
 }
 
 function cmdCheck(root: string, tier: string | undefined, stamp: string) {
-  const runs = runGates(root, tier);
+  let runs: GateRun[];
+  try {
+    runs = runGates(root, tier);
+  } catch (e) {
+    // ADR-0008. A tier nobody declared used to select nothing and exit as though
+    // the gates had passed — the one failure mode a release step cannot have.
+    if (!(e instanceof UnknownTierError)) throw e;
+    console.log(c.yellow(`\n  unknown tier "${e.requested}"`) + c.dim(` — this repo declares ${e.declared.join(', ')}.`));
+    console.log(c.dim('  Nothing ran. Use `rungs check` to run every registered gate.\n'));
+    return 1;
+  }
   if (!runs.length) {
-    console.log(c.yellow('\n  no gates registered — is this a rungs repo?\n'));
+    // Two situations printed the same sentence, and it was the wrong one for the case that
+    // actually happens: a registry full of `fast` gates filtered by `--full` asked "is this a
+    // rungs repo?" about a repo holding 25 of them, and `cut-release` told every consumer to
+    // gate a release on exactly that command (F-020). Blame the filter when there is one.
+    //
+    // Hooks are excluded because a hook fires on a tool call rather than in the runner: it is
+    // registered, and no tier value could ever have selected it. Counting it here would offer
+    // the reader a gate that changing the tier cannot reach.
+    const runnable = loadRegistry(root).gates.filter((g) => !g.trigger);
+    if (runnable.length && tier) {
+      const tiers = [...new Set(runnable.map((g) => g.tier).filter(Boolean))];
+      console.log(c.yellow(`\n  no gates in the ${tier} tier — ${runnable.length} are registered`) +
+        c.dim(` (${tiers.length ? tiers.join(', ') : 'none tiered'}).`));
+      console.log(c.dim('  Nothing ran. Use `rungs check` to run every registered gate.\n'));
+    } else {
+      console.log(c.yellow('\n  no gates registered — is this a rungs repo?\n'));
+    }
     return 1;
   }
   appendLedger(root, runs, stamp);
@@ -334,25 +528,82 @@ function cmdCheck(root: string, tier: string | undefined, stamp: string) {
     );
   }
 
+  console.log();
+  return n('fail') + n('unimplemented') + n('error') > 0 ? 1 : 0;
+}
+
+/**
+ * ADR-0005 tier B: the two questions the ledger can ask without judgement.
+ *
+ * This printed from `check` and belonged in `doctor`, which is what both the
+ * ADR and the README say (F-012). The ADR does not merely name the command, it
+ * gives the reason: *"They must be pull (`doctor`), never push; no output
+ * during normal runs."* `check` is the normal run — it is what CI and every
+ * pre-merge habit invoke — so printing there was the push the tier was written
+ * to forbid, arriving inside the feature that forbade it.
+ */
+function reportLedger(root: string) {
   const { gates } = loadRegistry(root);
   const q = ledgerQuestions(root, gates);
-  if (q.neverFired.length || q.alwaysFires.length) {
-    console.log(c.bold(`\n  Ledger questions ${c.dim(`(${q.runs} recorded runs)`)}`));
-    for (const g of q.neverFired.slice(0, 3)) {
-      console.log(`    ${c.cyan(g.id)} has never fired. ${c.dim(firstSentence(g.why ?? ''))}`);
-      console.log(c.dim('      Is that still a risk here, or is the gate scoped too narrowly?'));
-    }
-    for (const g of q.alwaysFires.slice(0, 3)) {
-      console.log(`    ${c.cyan(g.id)} fails ${g.rate}. ${c.dim('Red by default is a gate people learn to bypass.')}`);
-    }
-    console.log(
-      c.dim('\n    These are questions, not verdicts. The ledger records whether a gate ran'),
-    );
-    console.log(c.dim('    and whether it fired — never whether it is valuable. Gates invoked'));
-    console.log(c.dim('    directly, and CI runs, are not counted.'));
+  if (!q.neverFired.length && !q.alwaysFires.length) return;
+
+  console.log(c.bold(`  Ledger questions ${c.dim(`(${q.runs} recorded runs)`)}`));
+  for (const g of q.neverFired.slice(0, 3)) {
+    console.log(`    ${c.cyan(g.id)} has never fired. ${c.dim(firstSentence(g.why ?? ''))}`);
+    console.log(c.dim('      Is that still a risk here, or is the gate scoped too narrowly?'));
   }
-  console.log();
-  return n('fail') + n('unimplemented') + n('error') > 0 ? 1 : 0;
+  for (const g of q.alwaysFires.slice(0, 3)) {
+    console.log(`    ${c.cyan(g.id)} fails ${g.rate}. ${c.dim('Red by default is a gate people learn to bypass.')}`);
+  }
+  console.log(c.dim('\n    These are questions, not verdicts. The ledger records whether a gate ran'));
+  console.log(c.dim('    and whether it fired — never whether it is valuable. Gates invoked'));
+  console.log(c.dim('    directly, and CI runs, are not counted.\n'));
+}
+
+function cmdBacklogArchive(root: string, dryRun: boolean) {
+  const record = readRecord(root);
+  const configured = record?.modules['backlog']?.params?.root;
+  const backlogRoot = `docs/${configured ?? 'backlog'}`;
+
+  if (!existsSync(join(root, ...backlogRoot.split('/'), 'items'))) {
+    console.log(c.red(`\n  no backlog at ${backlogRoot}/items\n`));
+    return 1;
+  }
+
+  const plan = planArchive(root, backlogRoot);
+  console.log(c.bold(`\nrungs backlog archive → ${root}${dryRun ? c.yellow('  (dry run)') : ''}\n`));
+
+  for (const h of plan.held) console.log(c.yellow(`  held  ${h.file}`) + c.dim(` — ${h.reason}`));
+  if (plan.held.length) console.log();
+
+  if (!plan.moves.length) {
+    console.log(c.dim('  nothing to archive — no item is done or rejected.\n'));
+    return 0;
+  }
+
+  const byStatus = new Map<string, number>();
+  for (const m of plan.moves) byStatus.set(m.status, (byStatus.get(m.status) ?? 0) + 1);
+  console.log(
+    `  ${c.bold(String(plan.moves.length))} item(s) — ${[...byStatus].map(([s, n]) => `${n} ${s}`).join(' · ')}`,
+  );
+  for (const m of plan.moves.slice(0, 5)) console.log(c.dim(`      ${m.from} → ${m.to}`));
+  if (plan.moves.length > 5) console.log(c.dim(`      …and ${plan.moves.length - 5} more`));
+
+  const touched = plan.rewrites.filter((r) => r.links);
+  const links = touched.reduce((n, r) => n + r.links, 0);
+  console.log(`\n  ${c.bold(String(links))} link(s) repointed across ${touched.length} file(s)`);
+  for (const r of touched.slice(0, 5)) console.log(c.dim(`      ${r.file} (${r.links})`));
+  if (touched.length > 5) console.log(c.dim(`      …and ${touched.length - 5} more`));
+
+  if (dryRun) {
+    console.log(c.dim('\n  Nothing written. Drop --dry-run to apply.\n'));
+    return 0;
+  }
+
+  applyArchive(root, plan);
+  console.log(c.green(`\n  archived ${plan.moves.length} item(s)`) + c.dim(' — ids stay spent and every citation still resolves.'));
+  console.log(c.dim('  Run `rungs check` to confirm.\n'));
+  return 0;
 }
 
 function cmdInit(root: string, profile: string, dryRun: boolean, harnesses: Harness[], stamp: string) {
@@ -395,9 +646,18 @@ function cmdUpgrade(root: string, apply: boolean) {
     }
   }
 
-  if (apply && stale) {
-    const written = applyUpgrade(root, mods, record, plan);
-    console.log(c.green(`\n  updated ${written} file(s)`));
+  // Not `apply && stale`. A module version that only adds a gate has no stale
+  // file, so the whole apply step was skipped and the registry silently kept the
+  // old block — F-016, measured on a scratch consumer where `session` 1.1.0 →
+  // 1.2.0 added a gate and `rungs check` went on running the previous twenty.
+  if (apply) {
+    const { written, gates, recorded } = applyUpgrade(root, mods, record, plan);
+    const parts = [
+      written ? `${written} file(s)` : '',
+      gates ? `${gates} gate registration(s)` : '',
+      recorded ? `${recorded} record line(s)` : '',
+    ].filter(Boolean);
+    console.log(c.green(`\n  updated ${parts.length ? parts.join(' · ') : 'nothing'}`));
   }
   console.log(
     `\n  ${stale} to update · ${diverged} diverged\n` +
@@ -457,11 +717,14 @@ const COMMANDS: [usage: string, blurb: string][] = [
   ['eject [path]', 'materialise the engines; stop depending on rungs'],
   ['setup git [path]', 'install the merge drivers .gitattributes names'],
   ['modules', 'list the module set and audit the manifests'],
+  ['backlog archive [path]', 'move finished items to archive/, repointing every link'],
 ];
 
 /** Every flag the parser honours. A flag absent here is a flag nobody can find. */
 const FLAGS: [flag: string, blurb: string][] = [
   ['--dry-run', 'report what would happen, write nothing'],
+  ['--explain', "doctor: also run the detectors over what this repo already has"],
+  ['--confirm-paradigm', 'add: install a module this repo already solves another way'],
   ['--into <path>', 'add: install into this repo instead of the working directory'],
   ['--set m.param=value', 'add/init: override a module parameter. Repeatable'],
   ['--confirm-threshold', 'add: install a module whose rung is above this repo'],
@@ -547,7 +810,14 @@ switch (cmd) {
   case 'modules':
     process.exit(cmdModules(flags.has('--params')));
   case 'doctor':
-    process.exit(cmdDoctor(args[0] ?? process.cwd()));
+    process.exit(cmdDoctor(args[0] ?? process.cwd(), flags.has('--explain')));
+  case 'backlog': {
+    if (args[0] !== 'archive') {
+      console.log(c.red(`\n  unknown: rungs backlog ${args[0] ?? ''}`) + c.dim('\n  The only subcommand is `archive`.\n'));
+      process.exit(1);
+    }
+    process.exit(cmdBacklogArchive(resolve(args[1] ?? process.cwd()), flags.has('--dry-run')));
+  }
   case 'check': {
     const tier = args[1] ?? (flags.has('--full') ? 'full' : flags.has('--fast') ? 'fast' : undefined);
     process.exit(cmdCheck(resolve(args[0] ?? process.cwd()), tier, STAMP));