@rungs/cli 0.1.3 → 0.3.0

package/src/engines3.ts

@@ -15,6 +15,72 @@ const expand = (files: string[], p: string[] | undefined, f: string[] = []) =>
   [...new Set((p ?? f).flatMap((x) => matchAny(files, x)))];
 const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+/** `1.2.3` → [1,2,3]; anything else → null. Deliberately not a semver parser. */
+export function versionParts(s: string): number[] | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(s.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+export function versionCmp(a: number[], b: number[]): number {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * `changelog-freshness` — a consumed fragment that was never deleted.
+ *
+ * Fragments are consumed at release time, not archived: one left behind appears
+ * in the next release too, where it reads as unreleased work. `cut-release` §3
+ * has said so in prose since it was written, and prose did not hold it —
+ * `changelog.d/0.1.1.md` survived two releases and was still there at 0.2.0
+ * preparation (F-022). So the rule becomes mechanical.
+ *
+ * A fragment is stale when its filename names a version **below** the version
+ * being prepared. Files whose names are not versions are ignored rather than
+ * reported: the module's own fixtures use `42.feature.md`, and a gate that
+ * refuses a naming convention it was not asked about is a gate people disable.
+ */
+export const changelogFreshness: Engine = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings: Finding[] = [];
+  let examined = 0;
+
+  for (const spec of specs) {
+    const src = spec.version ?? {};
+    let current: number[] | null = null;
+    for (const rel of matchAny(files, src.file ?? 'package.json')) {
+      try {
+        const raw = (src.path ?? 'version')
+          .split('.')
+          .reduce((o: any, k: string) => o?.[k], JSON.parse(read(root, rel)));
+        current = versionParts(String(raw ?? ''));
+      } catch {
+        /* unparseable is not a stale fragment */
+      }
+      if (current) break;
+    }
+    // Without a version to compare against there is no claim to make. Saying
+    // nothing is right; passing loudly would not be.
+    if (!current) continue;
+
+    for (const rel of expand(files, spec.fragments, [])) {
+      const name = rel.split('/').pop()!.replace(/\.md$/, '');
+      const v = versionParts(name);
+      if (!v) continue;
+      examined++;
+      if (versionCmp(v, current) < 0) {
+        findings.push({
+          file: rel,
+          message:
+            spec.message?.trim() ||
+            `fragment names ${name}, below the ${current.join('.')} being prepared — it was consumed by an earlier release and should have been deleted`,
+        });
+      }
+    }
+  }
+
+  return { findings, examined };
+};
+
 /** An exemption marker is ignored unless it states a reason. */
 const exempted = (text: string, marker?: string) =>
   !!marker && new RegExp(`${escapeRe(marker)}\\s*\\S`).test(text);
@@ -192,3 +258,84 @@ export const mergeDriverCheck: Engine = (t, root) => {
   }
   return { findings, examined: declared.length };
 };
+
+/**
+ * The board's grouping must agree with each item's own `status` field.
+ *
+ * `git-status-reconcile` already reconciles a **branch** against that field, and
+ * this repo cites it constantly as proof that typed bookkeeping decays. Nothing
+ * reconciled the **board** — so on 2026-08-16 `BACKLOG.md` filed fourteen items
+ * under `Proposed` and `Planned` whose files all read `status: done`, nine of
+ * them linking into `archive/`. The board said *proposed* about a document in
+ * the directory for work that can no longer change.
+ *
+ * It was found by an outside reviewer asserting the framework research was done.
+ * They were right; the board would have told them otherwise. That is the same
+ * failure the whole module exists to prevent, one layer up, in the file every
+ * session opens first.
+ *
+ * Only table rows are read. The board's prose deliberately discusses finished
+ * work, and a paragraph is not a claim about status.
+ */
+export const boardReconcile: Engine = (t, root, _files) => {
+  const rel = t.file as string;
+  const text = read(root, rel);
+  if (!text) return { findings: [{ message: `board not found at ${rel}` }], examined: 0 };
+  if (exempted(text, t.exempt_marker)) return { findings: [], examined: 0 };
+
+  const groups: Record<string, string[]> = t.groups ?? {};
+  const dir = rel.split('/').slice(0, -1).join('/');
+  const findings: Finding[] = [];
+  let heading = '';
+  let examined = 0;
+
+  for (const line of text.split('\n')) {
+    const h = /^##\s+(.+?)\s*$/.exec(line);
+    if (h) {
+      heading = h[1];
+      continue;
+    }
+    if (!line.startsWith('|')) continue;
+
+    const link = /^\|\s*\[[^\]]+\]\(([^)]+)\)/.exec(line);
+    if (!link) continue; // separator, header, or an empty `| — |` placeholder
+
+    // An undeclared heading is narrative, not a status group. The board's later
+    // sections are prose with their own tables — "The first-user path", closed
+    // 2026-08-15, tabulates seven finished items and says so in the heading.
+    //
+    // Reporting those was this gate's first behaviour and it was wrong: measured
+    // 2026-08-16, it produced seven findings against a document that is correct.
+    // The plan's requirement that every undeclared heading be reported was aimed
+    // at a *typo* hiding rows from the check, and it caught legitimate prose
+    // instead. That case is covered exactly, below, by requiring each declared
+    // group to appear — a misspelled `Propsed` makes `Proposed` go missing.
+    if (!Object.hasOwn(groups, heading)) continue;
+
+    examined++;
+    const target = `${dir}/${link[1]}`.replace(/[^/]+\/\.\.\//g, '');
+    const item = read(root, target);
+    if (!item) {
+      findings.push({ file: rel, message: `row under '${heading}' links to a missing file: ${link[1]}` });
+      continue;
+    }
+    const status = /^status:\s*(\S+)/m.exec(item)?.[1] ?? '';
+    if (!groups[heading].includes(status)) {
+      findings.push({
+        file: rel,
+        message: `${link[1]} is under '${heading}' but its status is '${status}' (expected ${groups[heading].join(' | ')})`,
+      });
+    }
+  }
+
+  // Every declared group must actually appear. This is the typo check: a board
+  // whose `Proposed` heading is misspelled would otherwise drop those rows
+  // silently, which is exactly what the group map exists to prevent.
+  const seen = new Set([...text.matchAll(/^##\s+(.+?)\s*$/gm)].map((m) => m[1]));
+  for (const g of Object.keys(groups)) {
+    if (!seen.has(g)) findings.push({ file: rel, message: `declared group '${g}' has no heading in the board` });
+  }
+
+  return { findings, examined };
+};
+

package/src/explain.ts

@@ -0,0 +1,189 @@
+import { ENGINES, type Finding } from './engines.ts';
+import { loadTable, tableKey } from './check.ts';
+import type { DetectResult, Manifest } from './types.ts';
+
+/**
+ * `doctor` answers a *presence* question — which of our modules does this repo
+ * already have an equivalent of. The question a repo actually arrives with is a
+ * *defect* question: which of my agent rules say MUST and have nothing checking
+ * them, how many near-identical CI workflows do I have, which topics have two
+ * documents claiming authority.
+ *
+ * Those detectors were already written. They ship as gates inside modules and
+ * ran only after installation, over rungs-managed content — so the analysis was
+ * gated behind installing the thing the analysis exists to justify, which is
+ * backwards for a tool whose primary case is retrofit (WI-038).
+ *
+ * Nothing here is new detection. It is the same `ENGINES` table the runner
+ * uses, over a registry synthesized in memory from the module manifests rather
+ * than read from `.ai/gates.toml`, which an unmanaged repo does not have.
+ */
+
+export interface DetectorFinding {
+  module: string;
+  gate: string;
+  /** The extracted incident behind the gate, from the manifest. */
+  why?: string;
+  findings: Finding[];
+  examined: number;
+}
+
+export interface ExplainResult {
+  reported: DetectorFinding[];
+  /** Gates skipped, by reason — printed, because a silent skip reads as a pass. */
+  skipped: { command: number; unimplemented: string[]; undeclared: string[]; errored: { gate: string; message: string }[] };
+  /** Modules whose detectors ran at all. */
+  scope: string[];
+}
+
+type EngineTable = Record<string, (t: any, root: string, files: string[]) => { findings: Finding[]; examined: number }>;
+
+/**
+ * A `command` gate runs a shell command the *repo* owns. On a repo that never
+ * installed rungs there is no registry to own one, but a module can still
+ * declare one — and executing an arbitrary command against somebody else's
+ * checkout because they typed a read-only-sounding flag is not a thing this
+ * tool gets to do. Skipped, and counted, never run.
+ */
+const isRunnable = (g: Manifest['gates'][number]) => g.kind !== 'command' && !g.trigger && !!g.engine;
+
+/**
+ * Which modules' detectors are allowed to run.
+ *
+ * **Only what the repo already has.** ADR-0004 biased detection signatures
+ * toward false negatives; the same bias applies here for a stronger reason —
+ * these engines read rungs-shaped inputs, so on a foreign repo a
+ * technically-correct finding can still be framed against a convention the repo
+ * never adopted. A module the repo has no equivalent of has nothing to check,
+ * and running it anyway produces exactly the confident noise that loses an
+ * adoption wedge.
+ *
+ * `paradigm` is excluded too: the repo solves that problem a different way, and
+ * measuring their solution against our shape is the same error with a nastier
+ * tone.
+ */
+export const IN_SCOPE: ReadonlySet<string> = new Set(['theirs', 'ours-current', 'ours-diverged']);
+
+/**
+ * Which declared applicability may run against a repo that is not ours.
+ *
+ * This was two hard-coded sets of **engine names** in this file, and the
+ * knowledge lived nowhere near the gates it governed: adding a gate on
+ * `file-population` silently made it foreign-safe, and adding one on a new
+ * engine silently made it not, with nothing at either declaration saying so.
+ * It is now a required field on each gate — see `Applicability` in `types.ts`
+ * for what the three cases mean and which measurement produced them.
+ */
+const FOREIGN_SAFE: ReadonlySet<string> = new Set(['repo-content']);
+
+export function explain(
+  mods: Manifest[],
+  results: DetectResult[],
+  repoRoot: string,
+  files: string[],
+): ExplainResult {
+  return explainWith(ENGINES, mods, results, repoRoot, files);
+}
+
+/**
+ * `explain` with the engine table injected, so the scope rules above can be
+ * tested without a repo on disk. Those rules are the whole safety argument of
+ * this pass; testing them through fifteen real manifests would test the
+ * manifests instead.
+ */
+export function explainWith(
+  engines: EngineTable,
+  mods: Manifest[],
+  results: DetectResult[],
+  repoRoot: string,
+  files: string[],
+): ExplainResult {
+  const inScope = results.filter((r) => IN_SCOPE.has(r.state));
+  const scope = inScope.map((r) => r.module);
+  const stateOf = new Map(inScope.map((r) => [r.module, r.state]));
+  const reported: DetectorFinding[] = [];
+  const skipped: ExplainResult['skipped'] = { command: 0, unimplemented: [], undeclared: [], errored: [] };
+
+  for (const name of scope) {
+    const mod = mods.find((m) => m.name === name);
+    if (!mod) continue;
+    const isOurs = stateOf.get(name) !== 'theirs';
+
+    for (const g of mod.gates) {
+      if (!isRunnable(g)) {
+        if (g.kind === 'command') skipped.command++;
+        continue;
+      }
+      // No default. A gate that has not said whether it can read a foreign repo
+      // does not read one, and is named — silence resolving to "safe" is how the
+      // 71 mis-framed findings of WI-038's first version happened.
+      if (!isOurs) {
+        if (!g.applicability) {
+          skipped.undeclared.push(g.id);
+          continue;
+        }
+        if (!FOREIGN_SAFE.has(g.applicability)) continue;
+      }
+      if (!(g.engine! in engines)) {
+        // Same rule as the runner: an engine named and missing is an unknown,
+        // and an unknown is never reported as clean.
+        skipped.unimplemented.push(g.id);
+        continue;
+      }
+
+      const table = loadTable(g.table ? `${mod.name}/${g.table.replace(/^gates\//, '')}` : undefined, repoRoot);
+      if (!table) {
+        skipped.errored.push({ gate: g.id, message: `table '${g.table ?? '(none)'}' not found` });
+        continue;
+      }
+
+      try {
+        const key = tableKey(g.engine!);
+        let section = table[key] ?? table;
+        if (Array.isArray(section) && section.some((s: any) => s?.id)) {
+          const mine = section.filter((s: any) => !s.id || g.id.includes(s.id));
+          if (mine.length) section = mine;
+        }
+        const r = engines[g.engine!](section, repoRoot, files);
+        if (r.findings.length) {
+          reported.push({ module: mod.name, gate: g.id, why: g.why, findings: r.findings, examined: r.examined });
+        }
+      } catch (e: any) {
+        // An engine that throws on a foreign repo's shapes is a fact about this
+        // pass, not about the repo. Reported as ours, not as their finding.
+        skipped.errored.push({ gate: g.id, message: e.message });
+      }
+    }
+  }
+
+  return { reported: collapseDuplicates(reported), skipped, scope };
+}
+
+/**
+ * Two gate ids that produce the identical finding set are one check reported
+ * twice, and on a repo with 112 broken links that is 224 lines of the same
+ * thing. `gates-links-resolve` and `gates-paths-exist` currently run the same
+ * markdown-link scan — F-007 in `docs/backlog/FINDINGS.md`, open before this
+ * pass existed and unchanged by it.
+ *
+ * Collapsed here rather than fixed there on purpose: the duplication is a defect
+ * in the gate set, this is a defect in *reading* the gate set, and a reporting
+ * layer that hides a registry problem is how the registry problem survives. The
+ * merged row names both ids, so the duplication stays visible to anyone who
+ * looks at the output — which is the point.
+ */
+export function collapseDuplicates(reported: DetectorFinding[]): DetectorFinding[] {
+  const out: DetectorFinding[] = [];
+  const seen = new Map<string, DetectorFinding>();
+  for (const r of reported) {
+    const key = `${r.module} ${r.findings.map((f) => `${f.file ?? ''}|${f.message}`).join('')}`;
+    const prior = seen.get(key);
+    if (prior) {
+      prior.gate = `${prior.gate} + ${r.gate}`;
+      continue;
+    }
+    seen.set(key, r);
+    out.push(r);
+  }
+  return out;
+}

package/src/lifecycle.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { parse } from 'smol-toml';
 import type { Manifest } from './types.ts';
-import { contentHash, emittedFiles } from './add.ts';
+import { contentHash, emittedFiles, registerGates } from './add.ts';
 import { resolveParams, substitute, type Params } from './substitute.ts';
 import { loadRegistry } from './check.ts';
 
@@ -89,18 +89,105 @@ export function applyUpgrade(repoRoot: string, mods: Manifest[], record: Install
   const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
   let written = 0;
+  // Only files this run rewrote. A diverged file is not in here, which is what
+  // keeps its recorded hash — and therefore its protection — intact (F-017).
+  const rewritten = new Map<string, Map<string, string>>();
   for (const item of plan) {
     const mod = mods.find((m) => m.name === item.module)!;
     const emitted = emittedFiles(mod, params, skillsDir);
     for (const f of item.files) {
       if (f.state !== 'stale' && f.state !== 'missing') continue;
       const full = join(repoRoot, f.rel);
+      const content = emitted.get(f.rel)!;
       mkdirSync(dirname(full), { recursive: true });
-      writeFileSync(full, emitted.get(f.rel)!);
+      writeFileSync(full, content);
+      if (!rewritten.has(mod.name)) rewritten.set(mod.name, new Map());
+      rewritten.get(mod.name)!.set(f.rel, contentHash(content));
       written++;
     }
   }
-  return written;
+
+  // F-016. Upgrading rewrote a module's **files** and never its **gates**, so a
+  // module version that added, removed or renamed one left the registry on the
+  // old block and told the user the upgrade succeeded. Reproduced 2026-08-16
+  // against a scratch consumer: `session` 1.1.0 → 1.2.0 with a new gate, and
+  // `.ai/gates.toml` kept `rungs:begin session@1.1.0` and 20 entries.
+  //
+  // Registration is by whole merge block, so this fixes removal too — a gate
+  // dropped from a manifest leaves the registry with the block that replaces it.
+  // Idempotent, and cheap enough to run for every module in the plan rather than
+  // only the ones whose files happened to be stale.
+  const upgraded = plan.map((p) => mods.find((m) => m.name === p.module)!).filter(Boolean);
+  const gateActions = upgraded.length ? registerGates(upgraded, repoRoot, false) : [];
+
+  const recorded = updateRecordAfterUpgrade(
+    repoRoot,
+    upgraded.map((m) => ({ module: m.name, version: m.version, hashes: rewritten.get(m.name) ?? new Map() })),
+  );
+
+  return { written, gates: gateActions.length, recorded };
+}
+
+/**
+ * Update `.ai/rungs.toml` in place after an upgrade: the version each module
+ * moved to, and a new hash for each file this run actually rewrote.
+ *
+ * **Surgical, and text-level, on purpose.** F-017: `upgrade` left the record
+ * naming the old version, so a repo on 1.2.0 described itself to its owner as
+ * 1.1.0 and `planUpgrade` offered the same move forever. The obvious fix —
+ * calling `writeInstallRecord` — is worse than the bug: it re-derives the whole
+ * record and hashes **every emitted file that exists**, which would stamp our
+ * hash onto a file the user had diverged. That file would then match its record
+ * and be silently reclassified from `diverged` to `current`, so the next upgrade
+ * would overwrite the edit rungs promises never to touch.
+ *
+ * So: only the lines that must change, and only for files we wrote. Everything
+ * else — the header comment, kept-file lists, and the hash of every file we did
+ * not touch — is left exactly as it was.
+ */
+export function updateRecordAfterUpgrade(
+  repoRoot: string,
+  updates: { module: string; version: string; hashes: Map<string, string> }[],
+): number {
+  const path = join(repoRoot, '.ai', 'rungs.toml');
+  if (!existsSync(path) || !updates.length) return 0;
+
+  const lines = readFileSync(path, 'utf8').split('\n');
+  const byModule = new Map(updates.map((u) => [u.module, u]));
+  let changed = 0;
+  let current: { module: string; hashes: boolean } | null = null;
+
+  const out: string[] = [];
+  for (const line of lines) {
+    const header = /^\[modules\.([^\].]+)(\.[^\]]+)?\]/.exec(line);
+    if (header) {
+      current = byModule.has(header[1]) ? { module: header[1], hashes: header[2] === '.hashes' } : null;
+      out.push(line);
+      continue;
+    }
+
+    if (current && !current.hashes && /^version\s*=/.test(line)) {
+      const next = `version = "${byModule.get(current.module)!.version}"`;
+      if (next !== line) changed++;
+      out.push(next);
+      continue;
+    }
+
+    if (current?.hashes) {
+      const entry = /^"([^"]+)"\s*=/.exec(line);
+      const replacement = entry && byModule.get(current.module)!.hashes.get(entry[1]);
+      if (replacement) {
+        out.push(`"${entry[1]}" = "${replacement}"`);
+        changed++;
+        continue;
+      }
+    }
+
+    out.push(line);
+  }
+
+  writeFileSync(path, out.join('\n'));
+  return changed;
 }
 
 function paramsFrom(record: InstallRecord): Params {

package/src/manifest.ts

@@ -21,6 +21,7 @@ export function loadManifest(dir: string): Manifest {
     params: (raw.params ?? {}) as Record<string, ParamSpec>,
     gates: raw.gates ?? [],
     detect: raw.detect ?? {},
+    skills: raw.skills ?? {},
     provenance: raw.provenance,
     threshold: raw.threshold,
     dir,
@@ -61,7 +62,7 @@ export function usedParams(dir: string): Set<string> {
 
 export interface ManifestIssue {
   module: string;
-  kind: 'dead-param' | 'undeclared-param' | 'dep-missing' | 'gate-no-table' | 'gate-no-why';
+  kind: 'dead-param' | 'undeclared-param' | 'dep-missing' | 'gate-no-table' | 'gate-no-why' | 'gate-no-applicability';
   detail: string;
 }
 
@@ -102,6 +103,17 @@ export function auditModules(mods: Manifest[]): ManifestIssue[] {
       if (!g.why?.trim()) {
         issues.push({ module: mod.name, kind: 'gate-no-why', detail: `gate '${g.id}' has no 'why'` });
       }
+      // WI-052. `doctor --explain` will not run an undeclared gate against a repo
+      // that is not ours, so an author who forgets this silently loses their gate
+      // on exactly the repos the analysis exists for. Caught here, where the
+      // module is written, rather than as a skip line nobody reads.
+      if (g.kind === 'declared' && !g.applicability) {
+        issues.push({
+          module: mod.name,
+          kind: 'gate-no-applicability',
+          detail: `gate '${g.id}' does not declare applicability (repo-content | our-artifacts | our-schema)`,
+        });
+      }
     }
   }
   return issues;