@rungs/cli 0.1.3 → 0.3.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { dirname as dirname6, join as join11, resolve as resolve3 } from "node:path";
+import { dirname as dirname9, join as join14, resolve as resolve5 } from "node:path";
 
 // src/manifest.ts
 import { readdirSync as readdirSync2, readFileSync, statSync as statSync2 } from "node:fs";
@@ -106,6 +106,7 @@ function loadManifest(dir) {
     params: raw.params ?? {},
     gates: raw.gates ?? [],
     detect: raw.detect ?? {},
+    skills: raw.skills ?? {},
     provenance: raw.provenance,
     threshold: raw.threshold,
     dir
@@ -161,6 +162,13 @@ function auditModules(mods) {
       if (!g.why?.trim()) {
         issues.push({ module: mod.name, kind: "gate-no-why", detail: `gate '${g.id}' has no 'why'` });
       }
+      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;
@@ -209,9 +217,9 @@ function resolveParams(mods, overrides = {}, repoRoot) {
   }
   return out;
 }
-function markers(targetPath, module, version) {
+function markers(targetPath2, module, version) {
   const hash = /\.(toml|ya?ml|gitignore|gitattributes|sh|ps1|conf|properties)$|(^|\/)\.(gitignore|gitattributes)$/.test(
-    targetPath
+    targetPath2
   );
   return hash ? { begin: `# rungs:begin ${module}@${version}`, end: `# rungs:end ${module}` } : { begin: `<!-- rungs:begin ${module}@${version} -->`, end: `<!-- rungs:end ${module} -->` };
 }
@@ -225,8 +233,8 @@ function mergeBlock(existing, fragment, module) {
     const after = existing.slice(e.index + e[0].length);
     return `${before}${fragment.trim()}${after}`;
   }
-  const sep2 = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
-  return `${existing}${sep2}${fragment.trim()}
+  const sep3 = existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${sep3}${fragment.trim()}
 `;
 }
 
@@ -267,7 +275,7 @@ function addModule(mod, repoRoot, params, opts = {}) {
     const base = join3(mod.dir, "skills");
     const dir = opts.skillsDir ?? ".claude/skills";
     for (const rel of walk(base)) {
-      write(`${dir}/${rel}`, sub(readFileSync2(join3(base, rel), "utf8")), "skill");
+      write(`${dir}/${rel}`, withOptedInExtensions(mod, rel, sub(readFileSync2(join3(base, rel), "utf8"))), "skill");
     }
   }
   if (has("fragments")) {
@@ -346,6 +354,18 @@ var gateEntry = (mod) => (g) => {
   if (g.why) lines.push(`why    = """${g.why.trim()}"""`);
   return lines.join("\n");
 };
+function blockedByParadigm(order, paradigms) {
+  const blocked = /* @__PURE__ */ new Map();
+  for (const mod of order) {
+    if (paradigms.has(mod.name)) {
+      blocked.set(mod.name, mod.name);
+      continue;
+    }
+    const dep = mod.requires.find((d) => blocked.has(d));
+    if (dep) blocked.set(mod.name, blocked.get(dep));
+  }
+  return blocked;
+}
 function resolveInstallOrder(requested, all) {
   const byName = new Map(all.map((m) => [m.name, m]));
   const order = [];
@@ -379,6 +399,19 @@ function resolveInstallOrder(requested, all) {
 }
 var contentHash = (s) => createHash("sha256").update(s.replace(/\r\n/g, "\n")).digest("hex").slice(0, 12);
 var SHARED = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".gitignore", ".gitattributes", ".ai/gates.toml"]);
+function withOptedInExtensions(mod, rel, content) {
+  const name = rel.split(/[\\/]/)[0];
+  const extensions = mod.skills?.[name]?.extensions;
+  if (!extensions || !Object.keys(extensions).length) return content;
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return content;
+  const added = Object.entries(extensions).filter(([k]) => !new RegExp(`^${k}:`, "m").test(m[1])).map(([k, v]) => `${k}: ${v}`);
+  if (!added.length) return content;
+  return content.replace(/^---\n[\s\S]*?\n---/, `---
+${m[1]}
+${added.join("\n")}
+---`);
+}
 function emittedFiles(mod, params, skillsDir = ".claude/skills") {
   const out = /* @__PURE__ */ new Map();
   const sub = (t) => substitute(t, mod.name, params);
@@ -392,7 +425,9 @@ function emittedFiles(mod, params, skillsDir = ".claude/skills") {
     for (const rel of walk(base)) {
       const target = sub(prefix + rel).split("\\").join("/");
       if (SHARED.has(target)) continue;
-      out.set(target, sub(readFileSync2(join3(base, rel), "utf8")));
+      let content = sub(readFileSync2(join3(base, rel), "utf8"));
+      if (dir === "skills") content = withOptedInExtensions(mod, rel, content);
+      out.set(target, content);
     }
   }
   return out;
@@ -816,21 +851,146 @@ function writeReport(repoRoot, entries, harnesses, stamp) {
 // src/check.ts
 import { appendFileSync, existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
 import { execSync as execSync3 } from "node:child_process";
-import { dirname as dirname4, join as join9 } from "node:path";
+import { dirname as dirname5, join as join10 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parse2 } from "smol-toml";
 
 // src/engines.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
-import { join as join8, dirname as dirname3, resolve as resolve2 } from "node:path";
+import { join as join9, dirname as dirname4, resolve as resolve2 } from "node:path";
+import { parse as parseToml } from "smol-toml";
+
+// src/selftest.ts
+import { mkdirSync as mkdirSync3, mkdtempSync, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname as dirname3, join as join6 } from "node:path";
+function targetPath(table) {
+  const t = Array.isArray(table) ? table[0] ?? {} : table ?? {};
+  const pattern = t.file ?? [t.scan ?? []].flat()[0] ?? "**/*.md";
+  if (!pattern.includes("*")) return pattern;
+  return pattern.replace(/\*\*\//g, "probe/").replace(/\/\*\*/g, "/probe").replace(/\*/g, "probe").replace(/probe\.probe$/, "probe.md");
+}
+function build(root, table, fx, input) {
+  const write = (rel, body) => {
+    const full = join6(root, rel);
+    mkdirSync3(dirname3(full), { recursive: true });
+    writeFileSync3(full, body);
+    return rel;
+  };
+  if (typeof input === "string") return [write(targetPath(table), `${input}
+`)];
+  if (!fx || typeof fx !== "object") return null;
+  if (fx.packages && typeof fx.packages === "object") {
+    return Object.entries(fx.packages).map(
+      ([rel, version]) => write(rel, JSON.stringify({ name: rel.replace(/\W/g, "-"), version }))
+    );
+  }
+  if (Array.isArray(fx.fragments) && typeof fx.version === "string") {
+    const dir = fx.dir ?? "changelog.d";
+    const written = fx.fragments.map((n) => write(`${dir}/${n}`, `# ${n}
+`));
+    written.push(write("package.json", JSON.stringify({ version: fx.version })));
+    return written;
+  }
+  if (typeof fx.matching_files === "number") {
+    const base = fx.location ?? dirname3(targetPath(table));
+    const marker = fx.exempt ? `<!-- ${fx.exempt} -->
+` : "";
+    return Array.from(
+      { length: fx.matching_files },
+      (_, i) => write(join6(base === "." ? "" : base, `probe-${i}.md`), `${marker}# probe ${i}
+`)
+    );
+  }
+  const contentKeys = ["frontmatter", "sections", "opening", "body", "row", "table"];
+  if (contentKeys.some((k) => k in fx)) {
+    const parts = [];
+    if (fx.table) parts.push(`## ${fx.table}`, "");
+    if (fx.frontmatter && typeof fx.frontmatter === "object") {
+      parts.push("---");
+      for (const [k, v] of Object.entries(fx.frontmatter)) parts.push(`${k}: ${v}`);
+      parts.push("---", "");
+    }
+    if (fx.opening) parts.push(String(fx.opening), "");
+    for (const s of fx.sections ?? []) parts.push(`## ${s}`, "", "text", "");
+    if (fx.row && typeof fx.row === "object") {
+      const cols = Object.keys(fx.row);
+      parts.push(
+        `| ${cols.join(" | ")} |`,
+        `| ${cols.map(() => "---").join(" | ")} |`,
+        `| ${cols.map((c2) => fx.row[c2]).join(" | ")} |`,
+        ""
+      );
+    }
+    if (fx.body) parts.push(String(fx.body), "");
+    return [write(fx.file ?? targetPath(table), `${parts.join("\n")}
+`)];
+  }
+  return null;
+}
+var CONTEXT_FREE = /* @__PURE__ */ new Set([
+  "frontmatter-schema",
+  "sections",
+  "file-budget",
+  "register-schema",
+  "file-population",
+  "changelog-freshness",
+  "computed-claim"
+]);
+function deparam(spec, dir) {
+  const walk3 = (v) => typeof v === "string" ? v.replace(/\{\{[^}]+\}\}/g, dir) : Array.isArray(v) ? v.map(walk3) : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk3(x)])) : v;
+  return walk3(spec);
+}
+function runSelfTests(gateId, engine, table, blocks) {
+  const out = [];
+  for (const b of blocks) {
+    const expect = b.expect === "fail" ? "fail" : "pass";
+    if (!CONTEXT_FREE.has(engine)) {
+      out.push({ gate: gateId, expect, outcome: "unrun", detail: `${engine} fixtures need context the fixture does not carry` });
+      continue;
+    }
+    if (!(engine in ENGINES)) {
+      out.push({ gate: gateId, expect, outcome: "unrun", detail: `engine '${engine}' not implemented` });
+      continue;
+    }
+    const root = mkdtempSync(join6(tmpdir(), "rungs-selftest-"));
+    try {
+      const files = build(root, table, b.fixture, b.input);
+      let spec = b.fixture?.opted_in ? Array.isArray(table) ? table.map((s) => ({ ...s, extensions_opted_in: b.fixture.opted_in })) : { ...table, extensions_opted_in: b.fixture.opted_in } : table;
+      if (Array.isArray(b.fixture?.fragments)) spec = deparam(spec, b.fixture.dir ?? "changelog.d");
+      if (Array.isArray(b.fixture?.exclude)) {
+        const ex = b.fixture.exclude;
+        spec = Array.isArray(spec) ? spec.map((s) => ({ ...s, exclude: ex })) : { ...spec, exclude: ex };
+      }
+      if (!files) {
+        out.push({ gate: gateId, expect, outcome: "unrun", detail: `no builder for fixture ${JSON.stringify(b.fixture).slice(0, 60)}` });
+        continue;
+      }
+      let findings;
+      try {
+        findings = ENGINES[engine](spec, root, files).findings;
+      } catch (e) {
+        out.push({ gate: gateId, expect, outcome: "unrun", detail: `engine threw: ${e.message}`.slice(0, 90) });
+        continue;
+      }
+      const fired = findings.length > 0;
+      out.push(
+        fired === (expect === "fail") ? { gate: gateId, expect, outcome: "ok" } : { gate: gateId, expect, outcome: "mismatch", detail: `expected ${expect}, ${fired ? `fired: ${findings[0].message}`.slice(0, 80) : "did not fire"}` }
+      );
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+  return out;
+}
 
 // src/engines2.ts
 import { readFileSync as readFileSync5 } from "node:fs";
 import { execSync } from "node:child_process";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 var read = (root, rel) => {
   try {
-    return readFileSync5(join6(root, rel), "utf8");
+    return readFileSync5(join7(root, rel), "utf8");
   } catch {
     return "";
   }
@@ -924,40 +1084,44 @@ var renderFreshness = (t, root, files) => {
 var registerSchema = (t, root, files) => {
   const findings = [];
   let examined = 0;
-  const targets = t.file ? [t.file] : expand(files, t.scan);
-  for (const rel of targets) {
-    const text = read(root, rel);
-    if (!text) continue;
-    for (const table of parseTables(text)) {
-      if (t.table && !sectionOf(text, table.headerLine).toLowerCase().includes(String(t.table).toLowerCase())) continue;
-      const cols = t.required_cols ?? t.table_columns ?? [];
-      const present = cols.filter(
-        (c2) => table.headers.some((h) => h.toLowerCase() === String(c2).toLowerCase())
-      );
-      if (cols.length && present.length < Math.max(2, Math.ceil(cols.length / 2))) continue;
-      for (const c2 of cols) {
-        if (!present.includes(c2)) findings.push({ file: rel, message: `register table missing column '${c2}'` });
-      }
-      for (const row of table.rows) {
-        if (Object.values(row).every((v) => !v || v === "\u2014")) continue;
-        examined++;
-        for (const [key, values] of Object.entries(t.enum ?? {})) {
-          const v = strip(row[key]);
-          if (v && !values.map(String).includes(v)) {
-            findings.push({ file: rel, message: `${key}='${v}' not one of ${values.join(", ")}` });
-          }
-        }
-        for (const c2 of t.non_empty ?? []) {
-          if (!strip(row[c2])) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' is empty` });
+  const specs = [t, ...Object.values(t).filter((v) => v && typeof v === "object" && !Array.isArray(v) && v.table)];
+  for (const t2 of specs) {
+    const targets = t2.file ?? specs[0].file ? [t2.file ?? specs[0].file] : expand(files, t2.scan);
+    for (const rel of targets) {
+      const text = read(root, rel);
+      if (!text) continue;
+      for (const table of parseTables(text)) {
+        const heading = sectionOf(text, table.headerLine).replace(/^#+\s*/, "").trim().toLowerCase();
+        if (t2.table && !heading.startsWith(String(t2.table).toLowerCase())) continue;
+        const cols = t2.required_cols ?? t2.table_columns ?? [];
+        const present = cols.filter(
+          (c2) => table.headers.some((h) => h.toLowerCase() === String(c2).toLowerCase())
+        );
+        if (cols.length && present.length < Math.max(2, Math.ceil(cols.length / 2))) continue;
+        for (const c2 of cols) {
+          if (!present.includes(c2)) findings.push({ file: rel, message: `register table missing column '${c2}'` });
         }
-        for (const cond of t.conditional ?? []) {
-          const matches = Object.entries(cond.when ?? {}).every(([k, v]) => strip(row[k]) === String(v));
-          if (!matches) continue;
-          for (const c2 of cond.non_empty ?? []) {
-            const v = strip(row[c2]);
-            if (!v) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' required when ${JSON.stringify(cond.when)}` });
-            else if (cond.min_words?.[c2] && v.split(/\s+/).length < cond.min_words[c2]) {
-              findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' is too thin to be a reason` });
+        for (const row of table.rows) {
+          if (Object.values(row).every((v) => !v || v === "\u2014")) continue;
+          examined++;
+          for (const [key, values] of Object.entries(t2.enum ?? {})) {
+            const v = strip(row[key]);
+            if (v && !values.map(String).includes(v)) {
+              findings.push({ file: rel, message: `${key}='${v}' not one of ${values.join(", ")}` });
+            }
+          }
+          for (const c2 of t2.non_empty ?? []) {
+            if (!strip(row[c2])) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' is empty` });
+          }
+          for (const cond of t2.conditional ?? []) {
+            const matches = Object.entries(cond.when ?? {}).every(([k, v]) => strip(row[k]) === String(v));
+            if (!matches) continue;
+            for (const c2 of cond.non_empty ?? []) {
+              const v = strip(row[c2]);
+              if (!v) findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' required when ${JSON.stringify(cond.when)}` });
+              else if (cond.min_words?.[c2] && v.split(/\s+/).length < cond.min_words[c2]) {
+                findings.push({ file: rel, message: `row ${firstCell(row)}: '${c2}' is too thin to be a reason` });
+              }
             }
           }
         }
@@ -1073,6 +1237,16 @@ var crossReference = (t, root, files) => {
   }
   return { findings, examined: skills.length };
 };
+function landedWork(root, branch, base) {
+  const git2 = (cmd2) => execSync(`git ${cmd2}`, { cwd: root, stdio: "pipe" }).toString().trim();
+  try {
+    const tip = git2(`rev-parse ${branch}`);
+    if (tip === git2(`rev-parse ${base}`)) return false;
+    return git2(`log ${base} --merges --format=%P`).split("\n").some((line) => line.trim().split(/\s+/).slice(1).includes(tip));
+  } catch {
+    return true;
+  }
+}
 var gitStatusReconcile = (t, root, files) => {
   const findings = [];
   let merged;
@@ -1094,7 +1268,7 @@ var gitStatusReconcile = (t, root, files) => {
     const status = text.match(new RegExp(`^${t.status_field ?? "status"}:\\s*(\\S+)`, "m"))?.[1];
     if (!branch || !status) continue;
     examined++;
-    if (merged.has(branch) && (t.pre_review_statuses ?? []).includes(status)) {
+    if (merged.has(branch) && (t.pre_review_statuses ?? []).includes(status) && landedWork(root, branch, t.integration_branch ?? "main")) {
       findings.push({ file: rel, message: `branch ${branch} is merged but status is '${status}'` });
     }
   }
@@ -1106,8 +1280,10 @@ var computedClaim = (t, root, files) => {
   let examined = 0;
   for (const spec of specs) {
     const values = /* @__PURE__ */ new Map();
+    const excluded = (rel) => (spec.exclude ?? []).some((p) => matchAny([rel], p).length > 0);
     for (const src of spec.sources ?? []) {
       for (const rel of matchAny(files, src.file)) {
+        if (excluded(rel)) continue;
         const text = read(root, rel);
         let v;
         if (src.path && rel.endsWith(".json")) {
@@ -1126,8 +1302,9 @@ var computedClaim = (t, root, files) => {
     }
     const distinct = new Set(values.values());
     if (spec.rule === "all-agree" && distinct.size > 1) {
+      const where = [...values.entries()].map(([rel, v]) => `${rel}=${v}`).join(", ");
       findings.push({
-        message: `${spec.id} disagrees across ${values.size} locations: ${[...distinct].join(", ")} \u2014 run \`${spec.autofix}\``
+        message: `${spec.id} disagrees across ${values.size} locations: ${where}` + (spec.autofix ? ` \u2014 run \`${spec.autofix}\`` : "") + (spec.exclude?.length ? "" : ". If one of these is versioned independently, list it in `exclude`.")
       });
     }
   }
@@ -1137,16 +1314,54 @@ var computedClaim = (t, root, files) => {
 // src/engines3.ts
 import { readFileSync as readFileSync6 } from "node:fs";
 import { execSync as execSync2 } from "node:child_process";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 var read2 = (root, rel) => {
   try {
-    return readFileSync6(join7(root, rel), "utf8");
+    return readFileSync6(join8(root, rel), "utf8");
   } catch {
     return "";
   }
 };
 var expand2 = (files, p, f = []) => [...new Set((p ?? f).flatMap((x) => matchAny(files, x)))];
 var escapeRe2 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function versionParts(s) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(s.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function versionCmp(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+var changelogFreshness = (t, root, files) => {
+  const specs = Array.isArray(t) ? t : [t];
+  const findings = [];
+  let examined = 0;
+  for (const spec of specs) {
+    const src = spec.version ?? {};
+    let current = null;
+    for (const rel of matchAny(files, src.file ?? "package.json")) {
+      try {
+        const raw = (src.path ?? "version").split(".").reduce((o, k) => o?.[k], JSON.parse(read2(root, rel)));
+        current = versionParts(String(raw ?? ""));
+      } catch {
+      }
+      if (current) break;
+    }
+    if (!current) continue;
+    for (const rel of expand2(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 \u2014 it was consumed by an earlier release and should have been deleted`
+        });
+      }
+    }
+  }
+  return { findings, examined };
+};
 var exempted2 = (text, marker) => !!marker && new RegExp(`${escapeRe2(marker)}\\s*\\S`).test(text);
 function tableRows(text, near) {
   const lines = text.split("\n");
@@ -1266,11 +1481,52 @@ var mergeDriverCheck = (t, root) => {
   }
   return { findings, examined: declared.length };
 };
+var boardReconcile = (t, root, _files) => {
+  const rel = t.file;
+  const text = read2(root, rel);
+  if (!text) return { findings: [{ message: `board not found at ${rel}` }], examined: 0 };
+  if (exempted2(text, t.exempt_marker)) return { findings: [], examined: 0 };
+  const groups = t.groups ?? {};
+  const dir = rel.split("/").slice(0, -1).join("/");
+  const findings = [];
+  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;
+    if (!Object.hasOwn(groups, heading)) continue;
+    examined++;
+    const target = `${dir}/${link[1]}`.replace(/[^/]+\/\.\.\//g, "");
+    const item = read2(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(" | ")})`
+      });
+    }
+  }
+  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 };
+};
 
 // src/engines.ts
 var read3 = (root, rel) => {
   try {
-    return readFileSync7(join8(root, rel), "utf8");
+    return readFileSync7(join9(root, rel), "utf8");
   } catch {
     return "";
   }
@@ -1289,10 +1545,12 @@ var fileBudget = (t, root, files) => {
   const findings = [];
   let examined = 0;
   for (const rel of targets) {
-    if (excluded.has(rel) || !existsSync6(join8(root, rel))) continue;
+    if (excluded.has(rel) || !existsSync6(join9(root, rel))) continue;
     examined++;
     const n = loadedLines(read3(root, rel));
-    if (n > t.max_lines) findings.push({ file: rel, message: `${n} lines, budget ${t.max_lines}` });
+    if (n > t.max_lines) {
+      findings.push({ file: rel, message: `${n} loaded lines (blank lines and comments excluded), budget ${t.max_lines}` });
+    }
   }
   return { findings, examined };
 };
@@ -1304,10 +1562,11 @@ var sections = (t, root, files) => {
     const targets = dropGenerated(root, spec.file ? [spec.file] : expand3(files, spec.scan));
     const excluded = new Set(expand3(files, spec.exclude, []));
     for (const rel of targets) {
-      if (excluded.has(rel) || !existsSync6(join8(root, rel))) continue;
+      if (excluded.has(rel) || !existsSync6(join9(root, rel))) continue;
       examined++;
       const text = read3(root, rel);
-      const heads = [...text.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)].map((m) => m[1]);
+      const matches = [...text.matchAll(/^(#{1,6})\s+(.+?)\s*$/gm)];
+      const heads = matches.map((m) => m[2]);
       for (const want of spec.required ?? []) {
         const idx = heads.findIndex((h) => h.toLowerCase().startsWith(String(want).toLowerCase()));
         if (idx === -1) {
@@ -1315,8 +1574,9 @@ var sections = (t, root, files) => {
           continue;
         }
         if (spec.non_empty) {
-          const after = text.split(new RegExp(`^#{1,6}\\s+${escapeRe3(heads[idx])}\\s*$`, "m"))[1] ?? "";
-          const body = after.split(/^#{1,6}\s+/m)[0].replace(/<!--[\s\S]*?-->/g, "").trim();
+          const level = matches[idx][1].length;
+          const after = text.slice(matches[idx].index + matches[idx][0].length);
+          const body = after.split(new RegExp(`^#{1,${level}}\\s+`, "m"))[0].replace(/<!--[\s\S]*?-->/g, "").trim();
           if (!body) findings.push({ file: rel, message: `section '${want}' is empty` });
         }
       }
@@ -1346,21 +1606,70 @@ var frontmatterSchema = (t, root, files) => {
         if (!keys.includes(req)) findings.push({ file: rel, message: `missing '${req}'` });
       }
       if (spec.allowed) {
+        const optedIn = spec.extensions_allowed_from ? optedInExtensions(rel, spec) : /* @__PURE__ */ new Set();
         for (const k of keys) {
-          if (!spec.allowed.includes(k)) findings.push({ file: rel, message: `non-spec key '${k}'` });
+          if (spec.allowed.includes(k) || optedIn.has(k)) continue;
+          findings.push({ file: rel, message: `non-spec key '${k}'` });
         }
       }
+      const field2 = (k) => m[1].match(new RegExp(`^${k}:\\s*(.+)$`, "m"))?.[1].trim().replace(/^["']|["']$/g, "");
       for (const [key, values] of Object.entries(spec.enum ?? {})) {
-        const v = m[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1].trim().replace(/^["']|["']$/g, "");
+        const v = field2(key);
         if (v && !values.map(String).includes(v)) {
           findings.push({ file: rel, message: `${key}='${v}' not one of ${values.join(", ")}` });
         }
       }
+      for (const pair of spec.reciprocal?.pairs ?? []) {
+        const from = field2(pair.from);
+        if (!from) continue;
+        const target = expand3(files, spec.scan).find((r) => r.includes(from.replace(/\.md$/, "")));
+        if (!target) {
+          findings.push({ file: rel, message: `${pair.from} names '${from}', which is not a record here` });
+          continue;
+        }
+        const back = read3(root, target).match(/^---\n([\s\S]*?)\n---/)?.[1] ?? "";
+        const id = field2("id") ?? "";
+        if (!new RegExp(`^${pair.to}:\\s*.*${escapeRe3(id)}`, "m").test(back)) {
+          findings.push({ file: rel, message: `${pair.from} \u2192 ${from}, but it does not name this record back in '${pair.to}'` });
+        }
+      }
+      for (const [status, requires] of Object.entries(spec.reciprocal?.required_when ?? {})) {
+        if (field2("status") === status && !field2(String(requires))) {
+          findings.push({ file: rel, message: `status is '${status}' but '${requires}' is absent` });
+        }
+      }
     }
   }
   return { findings, examined };
 };
+function resolvesHere(root, rel, href) {
+  const from = dirname4(rel);
+  const decoded = decodeURIComponent(href);
+  if (existsSync6(resolve2(root, from, decoded))) return true;
+  const stripped = decoded.replace(/:\d+(?::\d+)?$/, "");
+  return stripped !== decoded && existsSync6(resolve2(root, from, stripped));
+}
+function backtickedPaths(rel, text, root, hints) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const raw = m[1].trim();
+    if (seen.has(raw) || !hints.some((h) => raw.includes(h))) continue;
+    seen.add(raw);
+    if (raw.startsWith("/")) continue;
+    if (/[*?{}#\s]|^\w+:/.test(raw)) continue;
+    if (!raw.includes("/")) continue;
+    if (!/\.[a-z0-9]{1,5}$/i.test(raw)) continue;
+    const bare = raw.replace(/^\.\//, "");
+    if (!existsSync6(join9(root, bare)) && !existsSync6(resolve2(root, dirname4(rel), bare))) {
+      out.push({ message: `stale path in a code span \u2192 ${raw}` });
+    }
+  }
+  return out;
+}
 var linkIntegrity = (t, root, files) => {
+  if (Array.isArray(t)) t = t[0] ?? {};
+  const checks = t.check ?? ["relative_markdown_links"];
   const scan = expand3(files, t.scan, ["**/*.md"]);
   const excluded = new Set(expand3(files, t.exclude, []));
   const findings = [];
@@ -1370,11 +1679,14 @@ var linkIntegrity = (t, root, files) => {
     const text = read3(root, rel);
     examined++;
     if (/path-ok:\s*\S/.test(text)) continue;
+    if (checks.includes("backticked_paths")) {
+      findings.push(...backtickedPaths(rel, text, root, t.path_hint ?? ["/"]).map((f) => ({ ...f, file: rel })));
+    }
+    if (!checks.includes("relative_markdown_links")) continue;
     const scannable = text.replace(/`+[^`\n]*`+/g, (s) => " ".repeat(s.length));
     for (const m of scannable.matchAll(/\]\((?!https?:|#|mailto:)([^)\s#]+)/g)) {
       if (/\{\{[a-z_.]+\}\}/.test(m[1])) continue;
-      const target = resolve2(root, dirname3(rel), decodeURIComponent(m[1]));
-      if (!existsSync6(target)) findings.push({ file: rel, message: `broken link \u2192 ${m[1]}` });
+      if (!resolvesHere(root, rel, m[1])) findings.push({ file: rel, message: `broken link \u2192 ${m[1]}` });
     }
   }
   return { findings, examined };
@@ -1392,13 +1704,17 @@ var filePopulation = (t, root, files) => {
   const findings = [];
   const failAt = t.fail_at ?? Infinity;
   if (hits.length >= failAt) {
-    findings.push({ message: `${hits.length} matching file(s), threshold ${failAt} (e.g. ${hits[0]})` });
+    const scanned = [t.scan ?? []].flat();
+    findings.push({
+      message: `${hits.length} matching file(s), threshold ${failAt} (e.g. ${hits[0]})` + (scanned.length ? ` \u2014 matched against ${scanned.join(", ")}` : "")
+    });
   }
   return { findings, examined: hits.length };
 };
 var gateMeta = (_t, root) => {
   const findings = [];
-  const registry = join8(root, ".ai", "gates.toml");
+  let unrun = 0;
+  const registry = join9(root, ".ai", "gates.toml");
   if (!existsSync6(registry)) return { findings, examined: 0 };
   const text = readFileSync7(registry, "utf8");
   const entries = [...text.matchAll(/\[\[gates\]\][\s\S]*?(?=\n\[\[gates\]\]|\n# rungs:end|$)/g)].map((m) => m[0]);
@@ -1409,7 +1725,7 @@ var gateMeta = (_t, root) => {
     const table = entry.match(/^table\s*=\s*"(.+)"/m)?.[1];
     if (!id || kind !== "declared" || !table) continue;
     examined++;
-    const tablePath = join8(dirname3(new URL(import.meta.url).pathname.slice(1)), "..", "modules", dirname3(table), "gates", table.split("/").pop());
+    const tablePath = join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules", dirname4(table), "gates", table.split("/").pop());
     const src = existsSync6(tablePath) ? readFileSync7(tablePath, "utf8") : "";
     const forGate = [...src.matchAll(/\[\[self_test\]\][\s\S]*?(?=\n\[\[|\n\[|$)/g)].map((m) => m[0]).filter((b) => b.includes(`gate   = "${id}"`) || b.includes(`gate    = "${id}"`) || b.includes(`gate = "${id}"`));
     for (const direction of ["pass", "fail"]) {
@@ -1417,10 +1733,61 @@ var gateMeta = (_t, root) => {
         findings.push({ message: `gate '${id}' has no self-test expecting '${direction}'` });
       }
     }
+    const engine = entry.match(/^engine\s*=\s*"(.+)"/m)?.[1];
+    const parsed = parseTable(tablePath, table.split("/")[0]);
+    if (engine && parsed) {
+      const blocks = (Array.isArray(parsed.self_test) ? parsed.self_test : []).filter((b) => b?.gate === id).map((b) => ({ expect: String(b.expect), input: b.input, fixture: b.fixture }));
+      for (const r of runSelfTests(id, engine, parsed[tableKeyFor(engine)] ?? parsed, blocks)) {
+        if (r.outcome === "mismatch") findings.push({ message: `self-test for '${id}' ${r.detail}` });
+        else if (r.outcome === "unrun") unrun++;
+      }
+    }
   }
+  if (unrun) console.error(`      ${unrun} self-test fixture(s) have no builder and did not run \u2014 not passes (F-018)`);
   return { findings, examined };
 };
+function optedInExtensions(rel, spec) {
+  if (Array.isArray(spec.extensions_opted_in)) return new Set(spec.extensions_opted_in.map(String));
+  const name = rel.split("/").slice(-2)[0];
+  if (!name) return /* @__PURE__ */ new Set();
+  try {
+    const mods = loadAllModules(join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules"));
+    const owner = mods.find((m) => m.skills?.[name]?.extensions);
+    return new Set(Object.keys(owner?.skills?.[name]?.extensions ?? {}));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
 var escapeRe3 = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function parseTable(path, module) {
+  if (!existsSync6(path)) return null;
+  try {
+    const mods = loadAllModules(join9(dirname4(new URL(import.meta.url).pathname.slice(1)), "..", "modules"));
+    const params = resolveParams(mods, {}, ".");
+    return parseToml(substitute(readFileSync7(path, "utf8"), module, params));
+  } catch {
+    return null;
+  }
+}
+var tableKeyFor = (engine) => ({
+  "file-budget": "file_budget",
+  "frontmatter-schema": "frontmatter_schema",
+  "link-integrity": "link_integrity",
+  "file-population": "file_population",
+  "render-freshness": "render_freshness",
+  "register-schema": "register_schema",
+  "self-declared-closure": "self_declared_closure",
+  "filename-schema": "filename_schema",
+  "cross-reference": "cross_reference",
+  "git-status-reconcile": "merged_status",
+  "computed-claim": "computed_claim",
+  "term-ownership": "term_ownership",
+  "rule-propagation": "rule_propagation",
+  "git-state": "git_state",
+  "merge-driver-check": "merge_driver_check",
+  "board-reconcile": "board_reconcile",
+  "changelog-freshness": "changelog_freshness"
+})[engine] ?? engine;
 var ENGINES = {
   "file-budget": fileBudget,
   sections,
@@ -1439,27 +1806,50 @@ var ENGINES = {
   "term-ownership": termOwnership,
   "rule-propagation": rulePropagation,
   "git-state": gitState,
-  "merge-driver-check": mergeDriverCheck
+  "merge-driver-check": mergeDriverCheck,
+  "board-reconcile": boardReconcile,
+  "changelog-freshness": changelogFreshness
 };
 function isImplemented(engine) {
   return engine in ENGINES;
 }
 
 // src/check.ts
-var MODULES = join9(dirname4(fileURLToPath(import.meta.url)), "..", "modules");
+var MODULES = join10(dirname5(fileURLToPath(import.meta.url)), "..", "modules");
 function loadRegistry(repoRoot) {
-  const path = join9(repoRoot, ".ai", "gates.toml");
+  const path = join10(repoRoot, ".ai", "gates.toml");
   if (!existsSync7(path)) return { runner: {}, gates: [] };
   const raw = parse2(readFileSync8(path, "utf8"));
   return { runner: raw.runner ?? {}, gates: raw.gates ?? [] };
 }
-function runGates(repoRoot, tier, now = () => Date.now()) {
-  const { gates } = loadRegistry(repoRoot);
+function tierSelects(runnerTiers, requested, gateTier) {
+  if (!gateTier) return true;
+  const at = runnerTiers.indexOf(requested);
+  const of = runnerTiers.indexOf(gateTier);
+  if (at < 0 || of < 0) return gateTier === requested;
+  return of <= at;
+}
+var UnknownTierError = class extends Error {
+  requested;
+  declared;
+  constructor(requested, declared) {
+    super(`unknown tier "${requested}"`);
+    this.requested = requested;
+    this.declared = declared;
+  }
+};
+function runGates(repoRoot, tier, now = () => Date.now(), only) {
+  const { runner, gates } = loadRegistry(repoRoot);
+  const runnerTiers = Array.isArray(runner?.tiers) ? runner.tiers : [];
+  if (tier && runnerTiers.length && !runnerTiers.includes(tier)) {
+    throw new UnknownTierError(tier, runnerTiers);
+  }
   const files = walk(repoRoot);
   const runs = [];
   for (const g of gates) {
     if (g.trigger) continue;
-    if (tier && g.tier && g.tier !== tier) continue;
+    if (only && !only.has(g.id)) continue;
+    if (tier && !tierSelects(runnerTiers, tier, g.tier)) continue;
     const started = now();
     let status = "pass";
     let findings = [];
@@ -1515,7 +1905,7 @@ function runGates(repoRoot, tier, now = () => Date.now()) {
 function loadTable(ref, repoRoot) {
   if (!ref) return null;
   const [mod, file] = ref.split("/");
-  const path = join9(MODULES, mod, "gates", file);
+  const path = join10(MODULES, mod, "gates", file);
   if (!existsSync7(path)) return null;
   try {
     return parse2(substitute(readFileSync8(path, "utf8"), mod, installedParams(repoRoot)));
@@ -1527,7 +1917,7 @@ var paramCache = null;
 function installedParams(repoRoot) {
   if (paramCache?.root === repoRoot) return paramCache.params;
   const defaults = resolveParams(loadAllModules(MODULES), {}, repoRoot);
-  const recordPath = join9(repoRoot, ".ai", "rungs.toml");
+  const recordPath = join10(repoRoot, ".ai", "rungs.toml");
   if (existsSync7(recordPath)) {
     try {
       const rec = parse2(readFileSync8(recordPath, "utf8"));
@@ -1558,17 +1948,18 @@ var tableKey = (engine) => ({
   "term-ownership": "term_ownership",
   "rule-propagation": "rule_propagation",
   "git-state": "git_state",
-  "merge-driver-check": "merge_driver_check"
+  "merge-driver-check": "merge_driver_check",
+  "board-reconcile": "board_reconcile"
 })[engine] ?? engine;
 function appendLedger(repoRoot, runs, stamp) {
   const { runner } = loadRegistry(repoRoot);
   if (runner.ledger === false) return;
-  const path = join9(repoRoot, ".ai", ".gate-ledger.jsonl");
+  const path = join10(repoRoot, ".ai", ".gate-ledger.jsonl");
   const lines = runs.map((r) => JSON.stringify({ at: stamp, id: r.id, status: r.status, ms: r.ms, examined: r.examined })).join("\n");
   appendFileSync(path, lines + "\n");
 }
 function ledgerQuestions(repoRoot, gates) {
-  const path = join9(repoRoot, ".ai", ".gate-ledger.jsonl");
+  const path = join10(repoRoot, ".ai", ".gate-ledger.jsonl");
   if (!existsSync7(path)) return { neverFired: [], alwaysFires: [], runs: 0 };
   const rows = readFileSync8(path, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
   const by = /* @__PURE__ */ new Map();
@@ -1585,12 +1976,12 @@ function ledgerQuestions(repoRoot, gates) {
 }
 
 // src/lifecycle.ts
-import { copyFileSync, existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync9, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname5, join as join10 } from "node:path";
+import { copyFileSync, existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname6, join as join11 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { execSync as execSync4 } from "node:child_process";
 import { parse as parse3 } from "smol-toml";
-var SRC = dirname5(fileURLToPath2(import.meta.url));
+var SRC = dirname6(fileURLToPath2(import.meta.url));
 var PROFILES = {
   minimal: ["instructions"],
   tracked: ["instructions", "gates", "backlog", "findings", "adr", "session"],
@@ -1599,7 +1990,7 @@ var PROFILES = {
   fleet: ["instructions", "gates", "backlog", "findings", "adr", "session", "ci", "specs", "workflows", "skills", "audit", "release", "doc-authority", "concurrency", "design-sync"]
 };
 function readRecord(repoRoot) {
-  const p = join10(repoRoot, ".ai", "rungs.toml");
+  const p = join11(repoRoot, ".ai", "rungs.toml");
   if (!existsSync8(p)) return null;
   try {
     const raw = parse3(readFileSync9(p, "utf8"));
@@ -1620,7 +2011,7 @@ function planUpgrade(repoRoot, mods, record) {
     const kept = new Set(installed.kept?.files ?? []);
     for (const [rel, wouldEmit] of emitted) {
       if (kept.has(rel)) continue;
-      const full = join10(repoRoot, rel);
+      const full = join11(repoRoot, rel);
       if (!existsSync8(full)) {
         files.push({ rel, state: "missing" });
         continue;
@@ -1639,18 +2030,63 @@ function applyUpgrade(repoRoot, mods, record, plan) {
   const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes("claude") ? ".claude/skills" : ".agents/skills";
   let written = 0;
+  const rewritten = /* @__PURE__ */ new Map();
   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 = join10(repoRoot, f.rel);
-      mkdirSync3(dirname5(full), { recursive: true });
-      writeFileSync3(full, emitted.get(f.rel));
+      const full = join11(repoRoot, f.rel);
+      const content = emitted.get(f.rel);
+      mkdirSync4(dirname6(full), { recursive: true });
+      writeFileSync4(full, content);
+      if (!rewritten.has(mod.name)) rewritten.set(mod.name, /* @__PURE__ */ new Map());
+      rewritten.get(mod.name).set(f.rel, contentHash(content));
       written++;
     }
   }
-  return written;
+  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) ?? /* @__PURE__ */ new Map() }))
+  );
+  return { written, gates: gateActions.length, recorded };
+}
+function updateRecordAfterUpgrade(repoRoot, updates) {
+  const path = join11(repoRoot, ".ai", "rungs.toml");
+  if (!existsSync8(path) || !updates.length) return 0;
+  const lines = readFileSync9(path, "utf8").split("\n");
+  const byModule = new Map(updates.map((u) => [u.module, u]));
+  let changed = 0;
+  let current = null;
+  const out = [];
+  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);
+  }
+  writeFileSync4(path, out.join("\n"));
+  return changed;
 }
 function paramsFrom(record) {
   const out = {};
@@ -1660,7 +2096,7 @@ function paramsFrom(record) {
   return out;
 }
 function eject(repoRoot, mods, dryRun = false) {
-  const dest = join10(repoRoot, ".rungs");
+  const dest = join11(repoRoot, ".rungs");
   const engines = ["glob.ts", "engines.ts", "engines2.ts"];
   const { gates } = loadRegistry(repoRoot);
   const declared = gates.filter((g) => g.kind === "declared" && g.table);
@@ -1670,23 +2106,23 @@ function eject(repoRoot, mods, dryRun = false) {
   for (const t of tables) actions.push(`.rungs/tables/${t.replace("/", "-").replace(/.toml$/, ".json")}`);
   actions.push(".rungs/run-gate.mjs", ".ai/gates.toml (rewritten to command gates)");
   if (dryRun) return { actions, gates: declared.length };
-  mkdirSync3(join10(dest, "tables"), { recursive: true });
-  for (const f of engines) copyFileSync(join10(SRC, f), join10(dest, f));
+  mkdirSync4(join11(dest, "tables"), { recursive: true });
+  for (const f of engines) copyFileSync(join11(SRC, f), join11(dest, f));
   const record = readRecord(repoRoot);
   const params = resolveParams(mods, record ? paramsFrom(record) : {}, repoRoot);
   for (const t of tables) {
     const [mod, file] = t.split("/");
-    const src = join10(SRC, "..", "modules", mod, "gates", file);
+    const src = join11(SRC, "..", "modules", mod, "gates", file);
     if (!existsSync8(src)) continue;
     try {
       const parsed = parse3(substitute(readFileSync9(src, "utf8"), mod, params));
-      writeFileSync3(join10(dest, "tables", `${mod}-${file.replace(/\.toml$/, ".json")}`), JSON.stringify(parsed, null, 2));
+      writeFileSync4(join11(dest, "tables", `${mod}-${file.replace(/\.toml$/, ".json")}`), JSON.stringify(parsed, null, 2));
     } catch {
     }
   }
-  writeFileSync3(join10(dest, "run-gate.mjs"), RUNNER);
-  writeFileSync3(join10(dest, "README.md"), EJECT_README);
-  const registry = join10(repoRoot, ".ai", "gates.toml");
+  writeFileSync4(join11(dest, "run-gate.mjs"), RUNNER);
+  writeFileSync4(join11(dest, "README.md"), EJECT_README);
+  const registry = join11(repoRoot, ".ai", "gates.toml");
   let text = readFileSync9(registry, "utf8");
   for (const g of declared) {
     text = text.replace(
@@ -1695,7 +2131,7 @@ function eject(repoRoot, mods, dryRun = false) {
 command = "node .rungs/run-gate.mjs ${g.id}"`
     );
   }
-  writeFileSync3(registry, `${text}
+  writeFileSync4(registry, `${text}
 # Ejected: gates above run from .rungs/ and no longer need rungs installed.
 `);
   return { actions, gates: declared.length };
@@ -1749,7 +2185,7 @@ itself to whoever finds it.
 To go back, delete this directory and re-run \`rungs add\`.
 `;
 function setupGit(repoRoot, dryRun = false) {
-  const attrs = join10(repoRoot, ".gitattributes");
+  const attrs = join11(repoRoot, ".gitattributes");
   if (!existsSync8(attrs)) return { drivers: [], rerere: false };
   const drivers = [...new Set([...readFileSync9(attrs, "utf8").matchAll(/merge=(rungs-[\w-]+)/g)].map((m) => m[1]))];
   const done = [];
@@ -1777,9 +2213,433 @@ function setupGit(repoRoot, dryRun = false) {
   return { drivers: done, rerere };
 }
 
+// src/explain.ts
+var isRunnable = (g) => g.kind !== "command" && !g.trigger && !!g.engine;
+var IN_SCOPE = /* @__PURE__ */ new Set(["theirs", "ours-current", "ours-diverged"]);
+var FOREIGN_SAFE = /* @__PURE__ */ new Set(["repo-content"]);
+function explain(mods, results, repoRoot, files) {
+  return explainWith(ENGINES, mods, results, repoRoot, files);
+}
+function explainWith(engines, mods, results, repoRoot, files) {
+  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 = [];
+  const 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;
+      }
+      if (!isOurs) {
+        if (!g.applicability) {
+          skipped.undeclared.push(g.id);
+          continue;
+        }
+        if (!FOREIGN_SAFE.has(g.applicability)) continue;
+      }
+      if (!(g.engine in engines)) {
+        skipped.unimplemented.push(g.id);
+        continue;
+      }
+      const table = loadTable(g.table ? `${mod.name}/${g.table.replace(/^gates\//, "")}` : void 0, 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) => s?.id)) {
+          const mine = section.filter((s) => !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) {
+        skipped.errored.push({ gate: g.id, message: e.message });
+      }
+    }
+  }
+  return { reported: collapseDuplicates(reported), skipped, scope };
+}
+function collapseDuplicates(reported) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Map();
+  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;
+}
+
+// src/backlog.ts
+import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync10, renameSync, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname7, join as join12, relative as relative2, resolve as resolve3, sep as sep2 } from "node:path";
+var FINISHED = /* @__PURE__ */ new Set(["done", "rejected"]);
+var field = (text, name) => text.match(new RegExp(`^${name}:\\s*(\\S+)`, "m"))?.[1] ?? "";
+var posix = (p) => p.split(sep2).join("/");
+var LINK = /\]\((?!https?:|#|mailto:)([^)\s#]+)((?:#[^)\s]*)?)\)/g;
+function planArchive(repoRoot, backlogRoot = "docs/backlog") {
+  const itemsDir = join12(repoRoot, ...backlogRoot.split("/"), "items");
+  const archiveDir = join12(repoRoot, ...backlogRoot.split("/"), "archive");
+  const moves = [];
+  const held = [];
+  const files = walk(repoRoot);
+  const items = files.filter((f) => posix(f).startsWith(posix(relative2(repoRoot, itemsDir)) + "/") && f.endsWith(".md"));
+  for (const rel of items) {
+    const base = posix(rel).split("/").pop();
+    if (/^(README|TEMPLATE)\.md$/i.test(base)) continue;
+    const text = readFileSync10(join12(repoRoot, rel), "utf8");
+    const status = field(text, "status");
+    const id = field(text, "id");
+    if (!FINISHED.has(status)) continue;
+    if (field(text, "type") === "epic") {
+      const children = (text.match(/^children:\s*\[(.*)\]/m)?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+      const archived = files.filter((f) => posix(f).startsWith(posix(relative2(repoRoot, archiveDir)) + "/") && f.endsWith(".md"));
+      const unfinished = children.filter((c2) => {
+        const f = items.find((i) => i.includes(`${c2}-`)) ?? archived.find((i) => i.includes(`${c2}-`));
+        return !f || !FINISHED.has(field(readFileSync10(join12(repoRoot, f), "utf8"), "status"));
+      });
+      if (unfinished.length) {
+        held.push({ file: rel, reason: `epic with unfinished children: ${unfinished.join(", ")}` });
+        continue;
+      }
+    }
+    moves.push({
+      id,
+      status,
+      from: rel,
+      to: posix(join12(relative2(repoRoot, archiveDir), posix(rel).split("/").pop()))
+    });
+  }
+  const moved = new Map(moves.map((m) => [resolve3(repoRoot, m.from), m.to]));
+  const rewrites = [];
+  for (const rel of files) {
+    if (!isRewritable(rel)) continue;
+    const links = retargets(repoRoot, rel, moved).length;
+    if (links || moved.has(resolve3(repoRoot, rel))) rewrites.push({ file: rel, links });
+  }
+  return { root: backlogRoot, moves, rewrites, held };
+}
+function isRewritable(rel) {
+  const p = posix(rel);
+  if (!p.endsWith(".md")) return false;
+  return !/^modules\/[^/]+\/(files|fragments)\//.test(p) && !p.startsWith("node_modules/");
+}
+function retargets(repoRoot, rel, moved) {
+  const oldDir = dirname7(resolve3(repoRoot, rel));
+  const selfMoved = moved.get(resolve3(repoRoot, rel));
+  const newDir = dirname7(resolve3(repoRoot, selfMoved ?? rel));
+  const out = [];
+  for (const m of readFileSync10(join12(repoRoot, rel), "utf8").matchAll(LINK)) {
+    const href = m[1];
+    if (href.includes("{{")) continue;
+    const target = resolve3(oldDir, decodeURIComponent(href));
+    const targetMoved = moved.get(target);
+    if (!targetMoved && !selfMoved) continue;
+    if (!targetMoved && !existsSync9(target)) continue;
+    const targetNew = targetMoved ? resolve3(repoRoot, targetMoved) : target;
+    const to = posix(relative2(newDir, targetNew));
+    if (to !== posix(href)) out.push({ href, to });
+  }
+  return out;
+}
+function applyArchive(repoRoot, plan) {
+  const moved = new Map(plan.moves.map((m) => [resolve3(repoRoot, m.from), m.to]));
+  for (const rel of walk(repoRoot)) {
+    if (!isRewritable(rel)) continue;
+    const edits = retargets(repoRoot, rel, moved);
+    if (!edits.length) continue;
+    const path = join12(repoRoot, rel);
+    let text = readFileSync10(path, "utf8");
+    text = text.replace(LINK, (whole, href, anchor) => {
+      const edit = edits.find((e) => e.href === href);
+      return edit ? `](${edit.to}${anchor})` : whole;
+    });
+    writeFileSync5(path, text);
+  }
+  for (const m of plan.moves) {
+    const to = join12(repoRoot, ...m.to.split("/"));
+    mkdirSync5(dirname7(to), { recursive: true });
+    renameSync(join12(repoRoot, m.from), to);
+  }
+}
+
+// src/concurrency.ts
+import { existsSync as existsSync10, mkdtempSync as mkdtempSync2, readFileSync as readFileSync11, rmSync as rmSync2, writeFileSync as writeFileSync6, unlinkSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { hostname } from "node:os";
+import { join as join13, resolve as resolve4, dirname as dirname8, basename as basename2 } from "node:path";
+import { tmpdir as tmpdir2 } from "node:os";
+function loopParams(root) {
+  const p = installedParams(root).concurrency ?? {};
+  const integration = String(p.integration_branch ?? "main");
+  const greenPrefix = String(p.green_prefix ?? "green/");
+  return {
+    integration,
+    // The green ref marks the last *verified* merge of the integration branch,
+    // so it is prefix + that branch — not prefix + whatever you are cutting.
+    greenRef: `${greenPrefix}${integration}`,
+    integPrefix: String(p.integ_prefix ?? "integ/")
+  };
+}
+function git(root, args2) {
+  return execFileSync("git", args2, { cwd: root, stdio: "pipe", encoding: "utf8" }).trim();
+}
+function gitOk(root, args2) {
+  try {
+    git(root, args2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function revParse(root, ref) {
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+  } catch {
+    return null;
+  }
+}
+function sessionStart(root, branch, at, dryRun = false) {
+  const { integration, greenRef } = loopParams(root);
+  const lines = [];
+  if (!branch) return { ok: false, lines: ["a branch name is required: `rungs session start <branch> [path]`"] };
+  if (revParse(root, `refs/heads/${branch}`)) {
+    return { ok: false, lines: [`branch '${branch}' already exists \u2014 pick another name, or check out the worktree that holds it`] };
+  }
+  const green = revParse(root, `refs/heads/${greenRef}`);
+  const base = green ? greenRef : integration;
+  const baseSha = green ?? revParse(root, integration);
+  if (!baseSha) return { ok: false, lines: [`neither '${greenRef}' nor '${integration}' resolves \u2014 is this the right repo?`] };
+  if (green) {
+    lines.push(`base ${greenRef} (${baseSha.slice(0, 8)}) \u2014 the last verified merge`);
+  } else {
+    lines.push(`no ${greenRef} ref yet \u2014 cutting from the tip of ${integration} (${baseSha.slice(0, 8)}) instead.`);
+    lines.push(`That tip has not been verified by a land. The first successful \`rungs land\` creates ${greenRef}.`);
+  }
+  const path = resolve4(at ?? join13(dirname8(root), `${basename2(root)}-${branch.replace(/[^\w.-]+/g, "-")}`));
+  if (existsSync10(path)) return { ok: false, lines: [`${path} already exists \u2014 rungs never writes over a directory it did not create`] };
+  lines.push(`worktree ${path}`);
+  lines.push(`branch   ${branch}`);
+  if (dryRun) return { ok: true, lines };
+  try {
+    git(root, ["worktree", "add", "-b", branch, path, baseSha]);
+  } catch (e) {
+    return { ok: false, lines: [...lines, `git refused: ${String(e.stderr ?? e.message).trim().split("\n").slice(-2).join(" ")}`] };
+  }
+  return { ok: true, lines };
+}
+function preflight(root) {
+  const { integration } = loopParams(root);
+  if (!revParse(root, integration)) return { ok: false, lines: [`'${integration}' does not resolve \u2014 is this the right repo?`] };
+  let base;
+  try {
+    base = git(root, ["merge-base", "HEAD", integration]);
+  } catch {
+    return { ok: false, lines: [`no merge base between HEAD and ${integration}; nothing to compare`] };
+  }
+  const names = (args2) => new Set(git(root, args2).split("\n").map((s) => s.trim()).filter(Boolean));
+  const theirs = names(["diff", "--name-only", base, integration]);
+  const mine = /* @__PURE__ */ new Set([
+    ...names(["diff", "--name-only", base, "HEAD"]),
+    ...names(["diff", "--name-only", "HEAD"]),
+    ...names(["diff", "--name-only", "--cached"])
+  ]);
+  const ahead = Number(git(root, ["rev-list", "--count", `${base}..${integration}`]));
+  const overlap = [...mine].filter((f) => theirs.has(f)).sort();
+  const lines = [
+    `${integration} is ${ahead} commit(s) ahead of your base, touching ${theirs.size} file(s).`,
+    `You have touched ${mine.size} file(s).`
+  ];
+  if (!overlap.length) {
+    lines.push("No overlap. The commit count is not the signal \u2014 these two sets not intersecting is.");
+    return { ok: true, lines };
+  }
+  lines.push(`${overlap.length} file(s) changed on both sides:`);
+  for (const f of overlap.slice(0, 20)) lines.push(`  ${f}`);
+  if (overlap.length > 20) lines.push(`  \u2026and ${overlap.length - 20} more`);
+  lines.push("Merge sooner rather than later. Shared code is a scheduling problem, not a tooling one.");
+  return { ok: true, lines };
+}
+function lockPath(root) {
+  return join13(git(root, ["rev-parse", "--git-common-dir"]).replace(/^\.git$/, join13(root, ".git")), "rungs-land.lock");
+}
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e?.code === "EPERM";
+  }
+}
+function land(root, branch, runner, dryRun = false) {
+  const { integration, greenRef, integPrefix } = loopParams(root);
+  const lines = [];
+  if (!branch) return { ok: false, lines: ["a branch name is required: `rungs land <branch>`"] };
+  const head = revParse(root, `refs/heads/${branch}`);
+  if (!head) return { ok: false, lines: [`branch '${branch}' does not exist`] };
+  const before = revParse(root, `refs/heads/${integration}`);
+  if (!before) return { ok: false, lines: [`'${integration}' does not resolve`] };
+  const lp = lockPath(root);
+  if (existsSync10(lp)) {
+    try {
+      const held = JSON.parse(readFileSync11(lp, "utf8"));
+      if (held.host === hostname() && alive(held.pid)) {
+        return {
+          ok: false,
+          lines: [
+            `another land is in progress: pid ${held.pid} on ${held.host}, landing '${held.branch}' since ${held.started}.`,
+            "Concurrent landing is refused, not silently merged."
+          ]
+        };
+      }
+      lines.push(`taking over a stale lock from pid ${held.pid} (${held.started}) \u2014 that process is gone.`);
+    } catch {
+      lines.push("an unreadable lock file was replaced.");
+    }
+  }
+  if (dryRun) {
+    lines.push(`would merge ${branch} (${head.slice(0, 8)}) onto ${integration} (${before.slice(0, 8)}) via ${integPrefix}${branch}, verify, then advance.`);
+    return { ok: true, lines };
+  }
+  const lock = { pid: process.pid, host: hostname(), started: (/* @__PURE__ */ new Date()).toISOString(), branch };
+  writeFileSync6(lp, JSON.stringify(lock));
+  const scratch = mkdtempSync2(join13(tmpdir2(), "rungs-land-"));
+  const parked = `${integPrefix}${branch}`;
+  try {
+    git(root, ["worktree", "add", "--detach", scratch, before]);
+    try {
+      git(scratch, ["-c", "user.email=rungs@localhost", "-c", "user.name=rungs", "merge", "--no-ff", "-m", `land ${branch}`, head]);
+    } catch (e) {
+      const conflicts = (() => {
+        try {
+          return git(scratch, ["diff", "--name-only", "--diff-filter=U"]).split("\n").filter(Boolean);
+        } catch {
+          return [];
+        }
+      })();
+      lines.push(`merge conflict \u2014 ${integration} is unchanged.`);
+      for (const f of conflicts.slice(0, 15)) lines.push(`  ${f}`);
+      lines.push("Reconcile generated artifacts by regenerating, never by merging text.");
+      return { ok: false, lines };
+    }
+    const merged = git(scratch, ["rev-parse", "HEAD"]);
+    const res = runner(scratch);
+    lines.push(`merged tree ${merged.slice(0, 8)} \u2014 ${res.pass} pass \xB7 ${res.failing.length} fail`);
+    if (res.failing.length) {
+      const ids = new Set(res.failing.map((f) => f.id));
+      let base = null;
+      try {
+        git(scratch, ["reset", "--hard", before]);
+        base = runner(scratch, ids);
+      } catch {
+        base = null;
+      }
+      const attributable = base !== null && base.failing.length + base.pass >= ids.size;
+      const baseFindings = new Map((base?.failing ?? []).map((f) => [f.id, new Set(f.findings)]));
+      const introduced = [];
+      const inherited = [];
+      for (const f of res.failing) {
+        const seen = attributable ? baseFindings.get(f.id) ?? /* @__PURE__ */ new Set() : null;
+        const fresh = seen ? f.findings.filter((x) => !seen.has(x)) : f.findings;
+        if (fresh.length) introduced.push({ id: f.id, findings: fresh });
+        else inherited.push(f);
+      }
+      for (const f of inherited) {
+        lines.push(`  inherited  ${f.id}${f.findings[0] ? ` \u2014 ${f.findings[0]}` : ""}`);
+      }
+      for (const f of introduced) {
+        lines.push(`  INTRODUCED ${f.id}${f.findings[0] ? ` \u2014 ${f.findings[0]}` : ""}`);
+        for (const extra of f.findings.slice(1, 4)) lines.push(`             ${extra}`);
+      }
+      if (base === null) {
+        lines.push("  The merge base could not be gated, so nothing here is attributable and all of it blocks.");
+      } else if (!attributable) {
+        lines.push("  Some gates could not be attributed against the merge base, so they block. We do not land on an unknown.");
+      }
+      if (introduced.length) {
+        git(root, ["update-ref", `refs/heads/${parked}`, merged]);
+        lines.push(
+          `${introduced.length} introduced by this branch. ${integration} is unchanged, and the merged tree is parked on '${parked}' \u2014 fix it there and land again.`
+        );
+        return { ok: false, lines };
+      }
+      lines.push(
+        `${inherited.length} failure(s), all already red on ${integration} before this branch. Landing anyway \u2014 they are not this branch's to fix, and blocking on them is how a gate gets bypassed.`
+      );
+      git(scratch, ["reset", "--hard", merged]);
+    }
+    try {
+      git(root, ["update-ref", `refs/heads/${integration}`, merged, before]);
+    } catch {
+      git(root, ["update-ref", `refs/heads/${parked}`, merged]);
+      return {
+        ok: false,
+        lines: [
+          ...lines,
+          `${integration} moved while this land was verifying, so the advance was refused rather than overwriting it.`,
+          `Your verified merge is parked on '${parked}'. Re-run \`rungs land ${branch}\` to rebuild it on the new tip.`
+        ]
+      };
+    }
+    git(root, ["update-ref", `refs/heads/${greenRef}`, merged]);
+    lines.push(`${integration} \u2192 ${merged.slice(0, 8)}, and ${greenRef} now marks it verified.`);
+    if (revParse(root, `refs/heads/${parked}`)) git(root, ["update-ref", "-d", `refs/heads/${parked}`]);
+    return { ok: true, lines };
+  } finally {
+    try {
+      git(root, ["worktree", "remove", "--force", scratch]);
+    } catch {
+      rmSync2(scratch, { recursive: true, force: true });
+      try {
+        git(root, ["worktree", "prune"]);
+      } catch {
+      }
+    }
+    try {
+      unlinkSync(lp);
+    } catch {
+    }
+  }
+}
+function worktrees(root) {
+  const { integration } = loopParams(root);
+  const out = git(root, ["worktree", "list", "--porcelain"]);
+  const rows = [];
+  for (const block of out.split("\n\n").filter((b) => b.trim())) {
+    const path = block.match(/^worktree (.+)$/m)?.[1];
+    const branch = block.match(/^branch refs\/heads\/(.+)$/m)?.[1];
+    if (!path || !branch || branch === integration) continue;
+    const merged = gitOk(root, ["merge-base", "--is-ancestor", branch, integration]);
+    let dirty = false;
+    try {
+      dirty = git(path, ["status", "--porcelain"]).length > 0;
+    } catch {
+      dirty = false;
+    }
+    rows.push({ path, branch, merged, dirty });
+  }
+  return { rows, integration };
+}
+
 // src/cli.ts
-var HERE = dirname6(fileURLToPath3(import.meta.url));
-var MODULES2 = join11(HERE, "..", "modules");
+import { existsSync as existsSync11 } from "node:fs";
+var HERE = dirname9(fileURLToPath3(import.meta.url));
+var MODULES2 = join14(HERE, "..", "modules");
 var c = {
   dim: (s) => `\x1B[2m${s}\x1B[0m`,
   bold: (s) => `\x1B[1m${s}\x1B[0m`,
@@ -1828,7 +2688,7 @@ ${mods.length} modules
   const issues = auditModules(mods);
   console.log();
   if (issues.length === 0) {
-    console.log(c.green("  audit clean") + c.dim(" \u2014 every parameter accounted for, every gate has a table and a why"));
+    console.log(c.green("  audit clean") + c.dim(" \u2014 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)} \u2014 ${i.detail}`);
@@ -1836,8 +2696,8 @@ ${mods.length} modules
   console.log();
   return issues.length === 0 ? 0 : 1;
 }
-function cmdDoctor(target) {
-  const root = resolve3(target);
+function cmdDoctor(target, doExplain = false) {
+  const root = resolve5(target);
   const mods = loadAllModules(MODULES2);
   console.log(c.bold(`
 rungs doctor \u2014 ${root}
@@ -1906,6 +2766,9 @@ rungs doctor \u2014 ${root}
   console.log(c.dim("  This reports presence, never quality. It cannot tell whether an adopted"));
   console.log(c.dim("  system is good, complete, or working \u2014 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);
   const theirs = byState("theirs");
   console.log(c.bold("  Next\n"));
   if (ours) {
@@ -1931,6 +2794,58 @@ rungs doctor \u2014 ${root}
 function firstSentence(s) {
   return s.trim().replace(/\s+/g, " ").split(/(?<=\.)\s/)[0];
 }
+function advertiseAnalysis(results) {
+  const inScope = results.filter((r) => IN_SCOPE.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("\u2014 evidenced findings, and the incident behind each check")}
+`);
+}
+function reportExplain(mods, results, root, files) {
+  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 \u2014 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(`      \u2026and ${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 \u2014 see below.\n"));
+  }
+  console.log(c.dim("  This is not an audit, and it is deliberately incomplete:"));
+  console.log(c.dim("  \xB7 Detectors ran only for modules this repo already has an equivalent of."));
+  console.log(c.dim("  \xB7 They read rungs-shaped inputs. A finding may be true and framed against"));
+  console.log(c.dim("    a convention you never adopted \u2014 that is our defect, not yours."));
+  if (skipped.command) {
+    console.log(c.dim(`  \xB7 ${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(`  \xB7 ${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(`  \xB7 ${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(`  \xB7 ${e.gate} could not run here (${e.message}) \u2014 a fact about this pass, not about your repo.`));
+  }
+  console.log();
+}
 function cmdAdd(names, root, dryRun, harnesses, stamp) {
   const mods = loadAllModules(MODULES2);
   const { order, missing } = resolveInstallOrder(names, mods);
@@ -1953,6 +2868,29 @@ function cmdAdd(names, root, dryRun, harnesses, stamp) {
     }
     (overrides[modName] ??= {})[param] = rhs.join("=");
   }
+  for (const [modName, vals] of Object.entries(overrides)) {
+    const mod = mods.find((m) => m.name === modName);
+    if (!mod) {
+      console.log(
+        c.red(`
+  --set names a module that does not exist: ${modName}`) + c.dim(`
+  Known: ${mods.map((m) => m.name).join(", ")}
+`)
+      );
+      return 1;
+    }
+    for (const k of Object.keys(vals)) {
+      if (!(k in mod.params)) {
+        const known = Object.keys(mod.params);
+        console.log(
+          c.red(`
+  --set names a parameter ${modName} does not have: ${k}`) + c.dim(`
+  ${known.length ? `${modName} takes: ${known.join(", ")}` : `${modName} takes no parameters`}`) + c.dim("\n  `rungs modules --params` lists every parameter and its default.\n")
+        );
+        return 1;
+      }
+    }
+  }
   const params = resolveParams(mods, overrides, root);
   for (const [m, vals] of Object.entries(overrides)) {
     for (const [k, v] of Object.entries(vals)) console.log(c.dim(`  set ${m}.${k} = ${v}`));
@@ -1963,9 +2901,50 @@ rungs add ${names.join(" ")} \u2192 ${root}${dryRun ? c.yellow("  (dry run)") :
 `));
   if (pulled.length) console.log(c.dim(`  pulled in by dependency: ${pulled.map((m) => m.name).join(", ")}
 `));
+  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 ? /* @__PURE__ */ new Map() : blockedByParadigm(order, paradigms);
+  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]}) \u2014 --confirm-paradigm`)
+      );
+    }
+    console.log(c.dim("      You will have two systems for one job. That is a choice, not a merge.\n"));
+  }
+  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 \u2014 ${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 \u2014 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 \u2014 pulled in only for the above`));
+    }
+    console.log(
+      c.dim(`
+  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 = [];
   const wrote = /* @__PURE__ */ new Map();
-  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}.`) + c.dim(" Skipped \u2014 pass --confirm-threshold to install it.\n")
@@ -2030,10 +3009,70 @@ rungs render \u2014 ${root}
   }
   return 0;
 }
+function report(r) {
+  console.log();
+  for (const l of r.lines) console.log(`  ${r.ok ? l : c.yellow(l)}`);
+  console.log();
+  return r.ok ? 0 : 1;
+}
+function landRunner(dir, only) {
+  const runs = runGates(dir, void 0, void 0, only);
+  const failing = runs.filter((r) => r.status === "fail" || r.status === "error");
+  return {
+    pass: runs.filter((r) => r.status === "pass").length,
+    // `file: message`, so the same broken link in the same file is the same
+    // finding across two runs, and a *new* one is visibly not.
+    failing: failing.map((r) => ({
+      id: r.id,
+      findings: r.findings.map((f) => `${f.file ? `${f.file}: ` : ""}${f.message}`)
+    }))
+  };
+}
+function cmdWorktrees(root) {
+  const { rows, integration } = worktrees(root);
+  console.log(c.bold(`
+rungs worktrees \u2014 merged into ${integration}?
+`));
+  if (!rows.length) {
+    console.log(c.dim("  no linked worktrees. `rungs session start <branch>` creates one.\n"));
+    return 0;
+  }
+  for (const w of rows) {
+    const state = w.merged && w.dirty ? c.red("merged \xB7 DIRTY") : w.merged ? c.green("merged \xB7 prunable") : c.dim("in flight");
+    console.log(`  ${state.padEnd(28)} ${w.branch.padEnd(30)} ${c.dim(w.path)}`);
+  }
+  const risky = rows.filter((w) => w.merged && w.dirty);
+  const prunable = rows.filter((w) => w.merged && !w.dirty);
+  console.log();
+  if (risky.length) {
+    console.log(c.red(`  ${risky.length} worktree(s) hold uncommitted work on a branch that already landed.`));
+    console.log(c.dim("  That is where work actually gets lost. Commit it somewhere or decide to drop it."));
+  }
+  if (prunable.length) console.log(c.dim(`  ${prunable.length} prunable. Removing a worktree is your call, not this command's.`));
+  console.log();
+  return 0;
+}
 function cmdCheck(root, tier, stamp) {
-  const runs = runGates(root, tier);
+  let runs;
+  try {
+    runs = runGates(root, tier);
+  } catch (e) {
+    if (!(e instanceof UnknownTierError)) throw e;
+    console.log(c.yellow(`
+  unknown tier "${e.requested}"`) + c.dim(` \u2014 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 \u2014 is this a rungs repo?\n"));
+    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(`
+  no gates in the ${tier} tier \u2014 ${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 \u2014 is this a rungs repo?\n"));
+    }
     return 1;
   }
   appendLedger(root, runs, stamp);
@@ -2060,26 +3099,67 @@ rungs check \u2014 ${root}${tier ? ` (${tier} tier)` : ""}
       c.yellow("\n  Unimplemented gates are not passes.") + c.dim(" A registry reporting green because most of its\n  gates do nothing is the worst failure this tool could have, so they block.")
     );
   }
+  console.log();
+  return n("fail") + n("unimplemented") + n("error") > 0 ? 1 : 0;
+}
+function reportLedger(root) {
   const { gates } = loadRegistry(root);
   const q = ledgerQuestions(root, gates);
-  if (q.neverFired.length || q.alwaysFires.length) {
-    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?"));
-    }
-    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 \u2014 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 \u2014 never whether it is valuable. Gates invoked"));
+  console.log(c.dim("    directly, and CI runs, are not counted.\n"));
+}
+function cmdBacklogArchive(root, dryRun) {
+  const record = readRecord(root);
+  const configured = record?.modules["backlog"]?.params?.root;
+  const backlogRoot = `docs/${configured ?? "backlog"}`;
+  if (!existsSync11(join14(root, ...backlogRoot.split("/"), "items"))) {
+    console.log(c.red(`
+  no backlog at ${backlogRoot}/items
+`));
+    return 1;
+  }
+  const plan = planArchive(root, backlogRoot);
+  console.log(c.bold(`
+rungs backlog archive \u2192 ${root}${dryRun ? c.yellow("  (dry run)") : ""}
+`));
+  for (const h of plan.held) console.log(c.yellow(`  held  ${h.file}`) + c.dim(` \u2014 ${h.reason}`));
+  if (plan.held.length) console.log();
+  if (!plan.moves.length) {
+    console.log(c.dim("  nothing to archive \u2014 no item is done or rejected.\n"));
+    return 0;
+  }
+  const byStatus = /* @__PURE__ */ new Map();
+  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) \u2014 ${[...byStatus].map(([s, n]) => `${n} ${s}`).join(" \xB7 ")}`
+  );
+  for (const m of plan.moves.slice(0, 5)) console.log(c.dim(`      ${m.from} \u2192 ${m.to}`));
+  if (plan.moves.length > 5) console.log(c.dim(`      \u2026and ${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(`
+  ${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(`      \u2026and ${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(`
+  archived ${plan.moves.length} item(s)`) + c.dim(" \u2014 ids stay spent and every citation still resolves."));
+  console.log(c.dim("  Run `rungs check` to confirm.\n"));
+  return 0;
 }
 function cmdInit(root, profile, dryRun, harnesses, stamp) {
   if (readRecord(root)) {
@@ -2122,10 +3202,15 @@ rungs upgrade \u2014 ${root}${apply ? "" : c.yellow("  (preview)")}
       console.log(`      ${c.yellow("diverged")} ${f.rel} ${c.dim("\u2014 yours, left alone")}`);
     }
   }
-  if (apply && stale) {
-    const written = applyUpgrade(root, mods, record, plan);
+  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(`
-  updated ${written} file(s)`));
+  updated ${parts.length ? parts.join(" \xB7 ") : "nothing"}`));
   }
   console.log(
     `
@@ -2161,10 +3246,17 @@ var COMMANDS = [
   ["upgrade [path]", "move to newer module versions, never touching what you edited"],
   ["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"]
+  ["modules", "list the module set and audit the manifests"],
+  ["backlog archive [path]", "move finished items to archive/, repointing every link"],
+  ["session start <branch>", "cut a branch and worktree from the last verified merge"],
+  ["preflight [path]", "did the integration branch change files you changed?"],
+  ["land <branch>", "merge \u2192 verify the merged tree \u2192 advance, or refuse and park it"],
+  ["worktrees [path]", "which worktrees are merged, prunable, or merged and still dirty"]
 ];
 var FLAGS = [
   ["--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"],
@@ -2231,21 +3323,36 @@ 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(`
+  unknown: rungs backlog ${args[0] ?? ""}`) + c.dim("\n  The only subcommand is `archive`.\n"));
+      process.exit(1);
+    }
+    process.exit(cmdBacklogArchive(resolve5(args[1] ?? process.cwd()), flags.has("--dry-run")));
+  }
   case "check": {
     const tier = args[1] ?? (flags.has("--full") ? "full" : flags.has("--fast") ? "fast" : void 0);
-    process.exit(cmdCheck(resolve3(args[0] ?? process.cwd()), tier, STAMP));
+    process.exit(cmdCheck(resolve5(args[0] ?? process.cwd()), tier, STAMP));
   }
   case "init": {
     const profile = args[1] ?? "tracked";
-    process.exit(cmdInit(resolve3(args[0] ?? process.cwd()), profile, flags.has("--dry-run"), HARNESSES, STAMP));
+    process.exit(cmdInit(resolve5(args[0] ?? process.cwd()), profile, flags.has("--dry-run"), HARNESSES, STAMP));
   }
   case "upgrade":
-    process.exit(cmdUpgrade(resolve3(args[0] ?? process.cwd()), flags.has("--apply")));
+    process.exit(cmdUpgrade(resolve5(args[0] ?? process.cwd()), flags.has("--apply")));
   case "eject":
-    process.exit(cmdEject(resolve3(args[0] ?? process.cwd()), flags.has("--dry-run")));
+    process.exit(cmdEject(resolve5(args[0] ?? process.cwd()), flags.has("--dry-run")));
   case "setup": {
-    const r = setupGit(resolve3(args[1] ?? process.cwd()), flags.has("--dry-run"));
+    if (args[0] !== "git") {
+      console.log(
+        c.red(`
+  unknown: rungs setup ${args[0] ?? ""}`.trimEnd()) + c.dim("\n  The only subcommand is `git`, and the path comes after it: `rungs setup git [path]`.\n")
+      );
+      process.exit(1);
+    }
+    const r = setupGit(resolve5(args[1] ?? process.cwd()), flags.has("--dry-run"));
     console.log(
       r.drivers.length ? `
   installed ${r.drivers.length} merge driver(s): ${r.drivers.join(", ")}` + (r.rerere ? c.dim(" \xB7 rerere on") : "") + c.dim("\n  Declared drivers were inert until now \u2014 a fresh clone needs this once.\n") : c.dim("\n  no rungs merge drivers declared in .gitattributes\n")
@@ -2253,11 +3360,25 @@ switch (cmd) {
     process.exit(0);
   }
   case "render":
-    process.exit(cmdRender(resolve3(args[0] ?? process.cwd()), HARNESSES, STAMP));
+    process.exit(cmdRender(resolve5(args[0] ?? process.cwd()), HARNESSES, STAMP));
+  case "session": {
+    if (args[0] !== "start") {
+      console.log(c.red(`
+  unknown: rungs session ${args[0] ?? ""}`.trimEnd()) + c.dim("\n  The only subcommand is `start`: `rungs session start <branch> [path]`.\n"));
+      process.exit(1);
+    }
+    process.exit(report(sessionStart(process.cwd(), args[1], args[2], flags.has("--dry-run"))));
+  }
+  case "preflight":
+    process.exit(report(preflight(resolve5(args[0] ?? process.cwd()))));
+  case "land":
+    process.exit(report(land(process.cwd(), args[0], landRunner, flags.has("--dry-run"))));
+  case "worktrees":
+    process.exit(cmdWorktrees(resolve5(args[0] ?? process.cwd())));
   case "add": {
     const target = flags.has("--into") ? args[args.length - 1] : process.cwd();
     const names = flags.has("--into") ? args.slice(0, -1) : args;
-    process.exit(cmdAdd(names, resolve3(target), flags.has("--dry-run"), HARNESSES, STAMP));
+    process.exit(cmdAdd(names, resolve5(target), flags.has("--dry-run"), HARNESSES, STAMP));
   }
   default: {
     const wantedHelp = cmd === void 0 || cmd === "help" || cmd === "--help" || cmd === "-h";