@rungs/cli 0.1.0 → 0.1.2

package/src/cli.ts

@@ -31,13 +31,35 @@ const STATE_LABEL: Record<DetectResult['state'], string> = {
   unknown: c.red('unknown'),
 };
 
-function cmdModules() {
+function cmdModules(showParams = false) {
   const mods = loadAllModules(MODULES);
   console.log(c.bold(`\n${mods.length} modules\n`));
   for (const m of mods) {
     const deps = m.requires.length ? c.dim(` ← ${m.requires.join(', ')}`) : '';
     console.log(`  ${c.bold(m.name.padEnd(14))} rung ${m.rung}${deps}`);
     console.log(`  ${' '.repeat(14)} ${c.dim(m.summary)}`);
+    // Rendered from the manifest at the moment it is asked for, never written down. A committed
+    // parameter table would be correct the day it was generated and silently wrong the day a
+    // default moved — which is the failure this flag exists to answer (WI-006).
+    if (!showParams) continue;
+    for (const [name, spec] of Object.entries(m.params)) {
+      const shown = spec.default === undefined ? c.dim('(none)') : JSON.stringify(spec.default);
+      const notes = [
+        spec.allowed ? `one of ${spec.allowed.map(String).join(' · ')}` : '',
+        // Behavioural parameters never appear as {{token}}, so a reader hunting for one in a
+        // template would conclude the parameter was dead. Say so where they meet it.
+        spec.consumed_by ? `behavioural — changes what \`${spec.consumed_by}\` does, not a template` : '',
+        spec.required ? 'required' : '',
+      ].filter(Boolean);
+      console.log(`  ${' '.repeat(14)} ${c.cyan(`${m.name}.${name}`.padEnd(30))} ${c.dim('=')} ${shown}`);
+      if (spec.description) console.log(`  ${' '.repeat(16)} ${c.dim(firstSentence(spec.description))}`);
+      for (const n of notes) console.log(`  ${' '.repeat(16)} ${c.dim(n)}`);
+    }
+    if (Object.keys(m.params).length) console.log();
+  }
+  if (showParams) {
+    console.log(c.dim('  Set one with `--set module.param=value` on `add` or `init`; either spelling works.'));
+    console.log(c.dim('  Resolved values are recorded in `.ai/rungs.toml`. See docs/design/parameters.md.\n'));
   }
 
   const issues = auditModules(mods);
@@ -67,7 +89,7 @@ function cmdDoctor(target: string) {
 
   const params = resolveParams(mods, Object.fromEntries(
     Object.entries(record?.modules ?? {}).flatMap(([n, e]) => (e.params ? [[n, e.params]] : [])),
-  ));
+  ), root);
   const skillsDir = record?.harnesses.includes('claude') === false ? '.agents/skills' : '.claude/skills';
   const results = mods.map((m) => {
     const installed = record?.modules[m.name];
@@ -130,6 +152,33 @@ function cmdDoctor(target: string) {
   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 — only that files are where a'));
   console.log(c.dim("  module's files would be. Signatures under-detect on purpose.\n"));
+
+  // `doctor` is the command the README makes the entry point, and it used to stop on the sentence
+  // above — fifteen `absent` lines and nothing to do next. The recommendation is deliberately a
+  // **single** command, and never the maximal one: the brief names selling rung 5 to a rung-1 repo
+  // as the most likely way this tool does harm, so a repo with nothing is pointed at `tracked`
+  // rather than at the fifteen things it could install (WI-005).
+  const theirs = byState('theirs');
+  console.log(c.bold('  Next\n'));
+  if (ours) {
+    const behind = results.some((r) => r.ours?.stale.length || r.ours?.missing.length);
+    console.log(
+      behind
+        ? `  ${c.cyan('rungs upgrade --apply')}  ${c.dim('— bring the stale and missing files up to date')}`
+        : `  ${c.cyan('rungs check')}           ${c.dim('— run the gates this repo already registered')}`,
+    );
+    console.log(c.dim(`  Add more with \`rungs add <module>\`; \`rungs modules\` lists the set.\n`));
+  } else if (theirs.length) {
+    const names = theirs.map((r) => r.module).slice(0, 3).join(' ');
+    console.log(`  ${c.cyan(`rungs add ${names}`)}  ${c.dim('— adopt what you already built, in place')}`);
+    console.log(c.dim('  Nothing is overwritten. Files you already have are kept and reported as'));
+    console.log(c.dim('  yours; only what is missing gets written.\n'));
+  } else {
+    console.log(`  ${c.cyan('rungs init . tracked')}   ${c.dim('— instructions · gates · backlog · findings · adr · session')}`);
+    console.log(c.dim('  `tracked` is the rung for more than one thing in flight. `minimal` is just'));
+    console.log(c.dim('  the entry document; higher profiles cost more than they return until the'));
+    console.log(c.dim('  problem they answer actually exists. `rungs modules` lists all fifteen.\n'));
+  }
   return 0;
 }
 
@@ -145,7 +194,29 @@ function cmdAdd(names: string[], root: string, dryRun: boolean, harnesses: Harne
     return 1;
   }
   const pulled = order.filter((m) => !names.includes(m.name));
-  const params = resolveParams(mods);
+
+  // `--set module.param=value`. Without it the first real install into a repo
+  // that already had a backlog would have created a second one beside it —
+  // `docs/backlog/` next to `docs/.ai/backlog/` — which is the "two places to
+  // look" failure this whole tool is against, arriving through the installer.
+  //
+  // Values arrive already split from their flag, in either spelling. A malformed
+  // key is refused rather than skipped: `--set root=x` used to be dropped in
+  // silence, so the install proceeded with the default and looked successful.
+  const overrides: Record<string, Record<string, unknown>> = {};
+  for (const raw of flagValues['--set'] ?? []) {
+    const [key, ...rhs] = raw.split('=');
+    const [modName, param] = key.split('.');
+    if (!modName || !param || !rhs.length) {
+      console.log(c.red(`\n  --set expects module.param=value, got: ${raw}\n`));
+      return 1;
+    }
+    (overrides[modName] ??= {})[param] = rhs.join('=');
+  }
+  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}`));
+  }
   const skillsDir = harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
 
   console.log(c.bold(`\nrungs add ${names.join(' ')} → ${root}${dryRun ? c.yellow('  (dry run)') : ''}\n`));
@@ -217,6 +288,14 @@ function cmdRender(root: string, harnesses: Harness[], stamp: string) {
     console.log(`  ${e.rule.padEnd(24)} ${e.harness.padEnd(10)} ${e.target ?? c.yellow('not emitted')}${lost}`);
   }
   console.log(c.dim(`\n  ${entries.length} rendering(s) → .ai/render-report.md\n`));
+  // A bare `0 rendering(s)` reads as a completed edit. It is the answer a user gets after editing a
+  // parameter in `.ai/rungs.toml` and running this — the thing the record's header used to tell
+  // them to do — so the zero case has to say what it did not do, not just how much of it (WI-003).
+  if (entries.length === 0) {
+    console.log(c.yellow('  Nothing to render.') + c.dim(' This command re-emits path-scoped rules from `.ai/rules/`.'));
+    console.log(c.dim('  It does not re-substitute parameters — a changed value in `.ai/rungs.toml`'));
+    console.log(c.dim('  does not rewrite a file that already exists.\n'));
+  }
   return 0;
 }
 
@@ -345,9 +424,103 @@ function cmdEject(root: string, dryRun: boolean) {
   return 0;
 }
 
+/**
+ * Flags that carry a value, and therefore consume the token after them unless it is attached with
+ * `=`. Everything else is a bare switch.
+ *
+ * This exists because the split below used to be two filters — `startsWith('--')` into flags,
+ * everything else into positionals — which has no concept of a value. `--set backlog.root=x` then
+ * left `backlog.root=x` sitting in the positionals, `--into` took the last positional as its
+ * target, and the user's actual path was reported back to them as an unknown module. Both
+ * spellings now work, and the value never reaches `args` (WI-002).
+ */
+const VALUE_FLAGS = new Set(['--set']);
+
+/**
+ * The command surface, defined once and rendered into `--help`.
+ *
+ * It was a template literal listing eight of the nine commands — `setup git` was missing entirely —
+ * beside a README table listing all nine, which is two hand-kept inventories of one fact. They had
+ * already drifted, in both directions: help omitted a real command, and three real flags appeared
+ * in neither. Keep this table beside the switch it describes, and add a row when you add a `case`.
+ *
+ * The README's table is still hand-kept and still a second inventory. That is a known cost, not an
+ * oversight — see WI-004.
+ */
+const COMMANDS: [usage: string, blurb: string][] = [
+  ['init [path] [profile]', 'scaffold a repo — minimal · tracked · disciplined · hardened · fleet'],
+  ['doctor [path]', 'detect what a repo already has, installed or not'],
+  ['add <module…> [--into p]', 'install modules, resolving dependencies and adopting what exists'],
+  ['check [path] [tier]', 'run the registered gates and record the ledger'],
+  ['render [path]', 're-emit path-scoped rules per harness'],
+  ['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'],
+];
+
+/** Every flag the parser honours. A flag absent here is a flag nobody can find. */
+const FLAGS: [flag: string, blurb: string][] = [
+  ['--dry-run', 'report what would happen, write nothing'],
+  ['--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'],
+  ['--apply', 'upgrade: write the changes, rather than preview them'],
+  ['--fast, --full', 'check: pick the gate tier, as the positional also does'],
+  ['--params', 'modules: show every module parameter, its default and its allowed values'],
+  ['--copilot', 'also emit Copilot instruction files'],
+];
+
+function renderHelp(): string {
+  const pad = Math.max(...COMMANDS.map(([u]) => u.length)) + 2;
+  const fpad = Math.max(...FLAGS.map(([f]) => f.length)) + 2;
+  return [
+    ``,
+    `${c.bold('rungs')} — installs and maintains a repository's agentic development system`,
+    ``,
+    ...COMMANDS.map(([u, b]) => `  ${c.bold(`rungs ${u.split(' ')[0]}`)}${u.slice(u.split(' ')[0].length).padEnd(pad - u.split(' ')[0].length)} ${c.dim(b)}`),
+    ``,
+    ...FLAGS.map(([f, b]) => `  ${c.dim(f.padEnd(fpad))} ${c.dim(b)}`),
+    ``,
+  ].join('\n');
+}
+
 const [, , cmd, ...rest] = process.argv;
-const flags = new Set(rest.filter((r) => r.startsWith('--')));
-const args = rest.filter((r) => !r.startsWith('--'));
+
+const flags = new Set<string>();
+const args: string[] = [];
+const flagValues: Record<string, string[]> = {};
+/** A value-flag left without a value. Reported by the command, so `--help` still works. */
+let missingValue: string | null = null;
+
+for (let i = 0; i < rest.length; i++) {
+  const token = rest[i];
+  if (!token.startsWith('--')) {
+    args.push(token);
+    continue;
+  }
+  const eq = token.indexOf('=');
+  const name = eq === -1 ? token : token.slice(0, eq);
+  if (!VALUE_FLAGS.has(name)) {
+    // The bare name, not the raw token, so `--copilot=yes` still answers `flags.has('--copilot')`.
+    flags.add(name);
+    continue;
+  }
+  // Attached form first; otherwise the next token, unless that is itself a flag — `--set --dry-run`
+  // is a missing value, not a value of `--dry-run`.
+  const next = rest[i + 1];
+  const value = eq === -1 ? (next === undefined || next.startsWith('--') ? undefined : rest[++i]) : token.slice(eq + 1);
+  if (value === undefined) missingValue = name;
+  else (flagValues[name] ??= []).push(value);
+}
+
+/**
+ * A positional shaped like `module.param=value` was meant to be an override and was not claimed by
+ * `--set`. No path, module, profile or tier has that shape, so it is unambiguously a mistake —
+ * refuse it by name rather than letting a command interpret it as something else.
+ */
+const strayOverride = args.find((a) => /^[a-z][a-z0-9_-]*\.[a-z][a-z0-9_]*=/.test(a));
+
 // Dates come from the caller, never from inside a render: a timestamp baked
 // into generated output makes every run a diff.
 const STAMP = process.env.RUNGS_DATE ?? new Date().toISOString().slice(0, 10);
@@ -355,9 +528,24 @@ const HARNESSES: Harness[] = flags.has('--copilot')
   ? ['claude', 'copilot', 'agents-md']
   : (['claude', 'agents-md'] as Harness[]);
 
+// Both refusals run before dispatch, because either one means the argv the user typed is not the
+// argv any command would act on. Silently proceeding is what made the original failure so opaque.
+if (missingValue) {
+  console.log(c.red(`\n  ${missingValue} expects a value — ${missingValue} module.param=value\n`));
+  process.exit(1);
+}
+if (strayOverride) {
+  console.log(
+    c.red(`\n  stray override: ${strayOverride}`) +
+      c.dim(`\n  Nothing claimed it, so it would be read as a path or a module name.`) +
+      c.dim(`\n  Did you mean: --set ${strayOverride}\n`),
+  );
+  process.exit(1);
+}
+
 switch (cmd) {
   case 'modules':
-    process.exit(cmdModules());
+    process.exit(cmdModules(flags.has('--params')));
   case 'doctor':
     process.exit(cmdDoctor(args[0] ?? process.cwd()));
   case 'check': {
@@ -390,22 +578,13 @@ switch (cmd) {
     const names = flags.has('--into') ? args.slice(0, -1) : args;
     process.exit(cmdAdd(names, resolve(target), flags.has('--dry-run'), HARNESSES, STAMP));
   }
-  default:
-    console.log(`
-${c.bold('rungs')} — installs and maintains a repository's agentic development system
-
-  ${c.bold('rungs init')} [path] [profile]      scaffold a repo — minimal · tracked · disciplined · hardened · fleet
-  ${c.bold('rungs doctor')} [path]              detect what a repo already has, installed or not
-  ${c.bold('rungs add')} <module…> [--into p]   install modules, resolving dependencies and adopting what exists
-  ${c.bold('rungs check')} [path] [tier]        run the registered gates and record the ledger
-  ${c.bold('rungs render')} [path]              re-emit path-scoped rules per harness
-  ${c.bold('rungs upgrade')} [path]             move to newer module versions, never touching what you edited
-  ${c.bold('rungs eject')} [path]               materialise the engines; stop depending on rungs
-  ${c.bold('rungs modules')}                    list the module set and audit the manifests
-
-  ${c.dim('--dry-run   report what would happen, write nothing')}
-  ${c.dim('--apply     upgrade only: write the changes')}
-  ${c.dim('--copilot   also emit Copilot instruction files')}
-`);
-    process.exit(cmd ? 1 : 0);
+  default: {
+    // Help is a success, and an unknown command is not. Both used to land here and exit on
+    // `cmd ? 1 : 0`, which made `rungs --help` — a command that did exactly what was asked —
+    // report failure to anything checking the status (WI-004).
+    const wantedHelp = cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h';
+    if (!wantedHelp) console.log(c.red(`\n  unknown command: ${cmd}`));
+    console.log(renderHelp());
+    process.exit(wantedHelp ? 0 : 1);
+  }
 }

package/src/engines.ts

@@ -9,6 +9,7 @@ import {
   idIntegrity,
   registerSchema,
   renderFreshness,
+  selfDeclaredClosure,
 } from './engines2.ts';
 import { gitState, mergeDriverCheck, rulePropagation, termOwnership } from './engines3.ts';
 
@@ -148,14 +149,20 @@ const linkIntegrity: Engine = (t, root, files) => {
   for (const rel of scan) {
     if (excluded.has(rel)) continue;
     const text = read(root, rel);
-    // A file with unsubstituted placeholders is a **template**, and its links
-    // resolve only once installed. Found by running this against the rungs repo
-    // itself, where `modules/*/fragments/AGENTS.md` was reported for a broken
-    // link to `{{path}}/README.md` — a path that is not meant to exist here.
-    if (/\{\{[a-z_.]+\}\}/.test(text)) continue;
     examined++;
     if (/path-ok:\s*\S/.test(text)) continue;
-    for (const m of text.matchAll(/\]\((?!https?:|#|mailto:)([^)\s#]+)/g)) {
+    // A link written inside a code span is prose *quoting* a link — most often a document
+    // explaining that some link is wrong. Blanked rather than removed, so every offset after it
+    // is unchanged and the reported text still matches what the author sees.
+    const scannable = text.replace(/`+[^`\n]*`+/g, (s) => ' '.repeat(s.length));
+    for (const m of scannable.matchAll(/\]\((?!https?:|#|mailto:)([^)\s#]+)/g)) {
+      // An unsubstituted placeholder makes a **template** link, which resolves only once
+      // installed. This test used to sit on the whole file, and one token anywhere in a document
+      // exempted every link in it: 16 non-excluded files, including eight that ship to consumer
+      // repos, silently stopped being checked. A green gate and a skipped file looked identical.
+      // The case the file-level skip was written for — `modules/*/fragments/AGENTS.md` linking
+      // `{{path}}/README.md` — is already excluded by path in `link_integrity.exclude` (WI-008).
+      if (/\{\{[a-z_.]+\}\}/.test(m[1])) continue;
       const target = resolve(root, dirname(rel), decodeURIComponent(m[1]));
       if (!existsSync(target)) findings.push({ file: rel, message: `broken link → ${m[1]}` });
     }
@@ -237,6 +244,7 @@ export const ENGINES: Record<string, Engine> = {
   'id-integrity': idIntegrity,
   'render-freshness': renderFreshness,
   'register-schema': registerSchema,
+  'self-declared-closure': selfDeclaredClosure,
   'filename-schema': filenameSchema,
   'cross-reference': crossReference,
   'git-status-reconcile': gitStatusReconcile,

package/src/engines2.ts

@@ -167,6 +167,76 @@ export const registerSchema: Engine = (t, root, files) => {
   return { findings, examined };
 };
 
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * An open finding must not declare itself fixed in its own detail section.
+ *
+ * This is deliberately a text-only contradiction check. It does not inspect
+ * code or infer that a fix really shipped; those questions are repository-
+ * specific and a guessed probe would be confidently wrong. A section may
+ * contain a reasoned `closure-ok:` marker when only a part of the observation
+ * was addressed. The table owns the headings, id shape, and verdict phrases so
+ * the engine remains useful for registers that use a different prefix or
+ * detail heading.
+ */
+export const selfDeclaredClosure: Engine = (t, root, files) => {
+  const findings: Finding[] = [];
+  let examined = 0;
+  const targets = t.file ? [t.file] : expand(files, t.scan ?? ['docs/**/FINDINGS.md']);
+  const idPattern = t.id_pattern ?? '[A-Z]{1,6}-\\d{1,4}';
+  const openRow = new RegExp(t.open_row_pattern ?? `^\\|\\s*\\[?(${idPattern})\\]`, 'gmu');
+  const detailHeading = new RegExp(t.detail_heading_pattern ?? `^###\\s+(${idPattern})\\s+—\\s+`, 'gmu');
+  const verdicts = (t.declares_fixed ?? [
+    '\\*\\*Fixed[.,)*]',
+    '\\*\\*Fixed\\s+(?:in|by|the\\s+same\\s+day|\\d{4}-\\d{2}-\\d{2})',
+    '\\*\\*Implemented in this change\\.?\\*\\*',
+    '\\*\\*fixed in the pass that found it\\*\\*',
+  ]).map((p: string) => new RegExp(p, 'iu'));
+
+  for (const rel of targets) {
+    const text = read(root, rel);
+    if (!text) continue;
+    const openStart = headingIndex(text, t.open_heading ?? 'Open');
+    const closedStart = headingIndex(text, t.closed_heading ?? 'Closed');
+    const detailStart = headingIndex(text, t.detail_heading ?? 'Detail');
+    if (openStart < 0 || closedStart < 0 || detailStart < 0 || closedStart <= openStart || detailStart < closedStart) continue;
+
+    const open = new Set<string>();
+    for (const match of text.slice(openStart, closedStart).matchAll(openRow)) open.add(match[1]);
+    if (!open.size) continue;
+
+    const detail = text.slice(detailStart);
+    const headings = [...detail.matchAll(detailHeading)];
+    for (let i = 0; i < headings.length; i++) {
+      const id = headings[i][1];
+      if (!open.has(id)) continue;
+      examined++;
+      const start = headings[i].index ?? 0;
+      const end = headings[i + 1]?.index ?? detail.length;
+      const section = detail.slice(start, end);
+      const marker = t.exempt_marker ?? 'closure-ok:';
+      if (new RegExp(`<!--\\s*${escapeRe(marker)}\\s*\\S`, 'u').test(section)) continue;
+      const body = section.slice(section.indexOf('\n') + 1);
+      for (const verdict of verdicts) {
+        const match = verdict.exec(body);
+        if (!match) continue;
+        const before = body.slice(Math.max(0, match.index - (t.citation_window ?? 120)), match.index);
+        const cited = [...before.matchAll(new RegExp(`(${idPattern})[^.]{0,${t.citation_window ?? 120}}$`, 'gu'))].at(-1)?.[1];
+        if (cited && cited !== id) continue;
+        findings.push({ file: rel, message: `${id} is open but its detail declares it fixed: ${body.slice(match.index, match.index + 60).split('\n')[0].trim()}` });
+        break;
+      }
+    }
+  }
+  return { findings, examined };
+};
+
+function headingIndex(text: string, heading: string): number {
+  const re = new RegExp(`^#{1,6}\\s+${escapeRe(heading)}\\s*$`, 'imu');
+  return text.search(re);
+}
+
 const strip = (v?: string) => (v ?? '').replace(/[`*\[\]]/g, '').split('(')[0].trim();
 const firstCell = (row: Record<string, string>) => strip(Object.values(row)[0]) || '?';
 

package/src/lifecycle.ts

@@ -56,7 +56,7 @@ export interface UpgradeItem {
  * clobber deliberate edits or refuse to move anything.
  */
 export function planUpgrade(repoRoot: string, mods: Manifest[], record: InstallRecord): UpgradeItem[] {
-  const params = resolveParams(mods, paramsFrom(record));
+  const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
   const items: UpgradeItem[] = [];
 
@@ -86,7 +86,7 @@ export function planUpgrade(repoRoot: string, mods: Manifest[], record: InstallR
 
 /** Applies only `stale` and `missing`. Divergence is a decision, not an error. */
 export function applyUpgrade(repoRoot: string, mods: Manifest[], record: InstallRecord, plan: UpgradeItem[]) {
-  const params = resolveParams(mods, paramsFrom(record));
+  const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
   let written = 0;
   for (const item of plan) {
@@ -145,7 +145,7 @@ export function eject(repoRoot: string, mods: Manifest[], dryRun = false) {
   // — which is the same promise ADR-0002 makes about installation, kept on the
   // way out. Parameters are substituted now, for the same reason.
   const record = readRecord(repoRoot);
-  const params = resolveParams(mods, record ? paramsFrom(record) : {});
+  const params = resolveParams(mods, record ? paramsFrom(record) : {}, repoRoot);
   for (const t of tables) {
     const [mod, file] = t.split('/');
     const src = join(SRC, '..', 'modules', mod, 'gates', file);
@@ -196,7 +196,7 @@ if (!engine || !ENGINES[engine]) { console.error(\`gate \${id}: engine '\${engin
 // Tables were converted to JSON when this was ejected, so nothing here needs a
 // TOML parser — or any dependency at all beyond Node itself.
 const raw = JSON.parse(readFileSync(join(here, 'tables', table.replace('/', '-').replace(/\\.toml$/, '.json')), 'utf8'));
-const KEYS = { 'file-budget': 'file_budget', 'frontmatter-schema': 'frontmatter_schema', 'link-integrity': 'link_integrity', 'file-population': 'file_population', 'gate-meta': 'gate_meta', 'render-freshness': 'render_freshness', 'register-schema': 'register_schema', 'filename-schema': 'filename_schema', 'cross-reference': 'cross_reference', 'git-status-reconcile': 'merged_status', 'computed-claim': 'computed_claim' };
+const KEYS = { 'file-budget': 'file_budget', 'frontmatter-schema': 'frontmatter_schema', 'link-integrity': 'link_integrity', 'file-population': 'file_population', 'gate-meta': 'gate_meta', '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' };
 let section = raw[KEYS[engine] ?? engine] ?? raw;
 if (Array.isArray(section) && section.some((s) => s?.id)) {
   const mine = section.filter((s) => !s.id || id.includes(s.id));

package/src/substitute.ts

@@ -1,3 +1,4 @@
+import { basename, resolve } from 'node:path';
 import type { Manifest } from './types.ts';
 
 export type Params = Record<string, Record<string, unknown>>;
@@ -26,25 +27,55 @@ function format(v: unknown): string {
   return String(v);
 }
 
-/** Defaults from every manifest, with explicit overrides applied on top. */
-export function resolveParams(mods: Manifest[], overrides: Params = {}): Params {
-  const out: Params = {};
+/**
+ * Facts about the target repository, addressable from a default as `{{repo.<key>}}`.
+ *
+ * `repo` is a **reserved namespace, not a module**, which is what keeps it clear of
+ * `modules/README.md` rule 9b — referencing a module you have not declared is an undeclared
+ * coupling, but every module already sits in a repository, so there is nothing to declare.
+ *
+ * Deliberately one key. `git_remote` and `branch` were considered and left out: nothing consumes
+ * them, and rule 9e is about the knob wired to nothing that stays invisible until someone compares
+ * every module at once.
+ */
+function repoFacts(repoRoot?: string): Record<string, unknown> {
+  return repoRoot ? { dirname: basename(resolve(repoRoot)) } : {};
+}
+
+/**
+ * Defaults from every manifest, with explicit overrides applied on top.
+ *
+ * `repoRoot` is optional only so a caller with no repository in hand can still read defaults. When
+ * it is absent `{{repo.dirname}}` does not resolve, and `substitute` leaves the token visible
+ * rather than emitting an empty string — the same bias as every other unresolved reference, and
+ * the reason a missing root shows up as a wrong-looking file instead of a silently blank heading.
+ */
+export function resolveParams(mods: Manifest[], overrides: Params = {}, repoRoot?: string): Params {
+  const out: Params = { repo: repoFacts(repoRoot) };
   for (const m of mods) {
     out[m.name] = {};
     for (const [k, spec] of Object.entries(m.params)) out[m.name][k] = spec.default;
   }
-  // A default may itself reference another module's parameter, e.g. findings'
-  // register living at `docs/{{backlog.root}}/FINDINGS.md`. Resolve after all
-  // defaults are in place, and only one level — a chain would be a template
-  // language arriving through the back door.
+
+  // **Overrides go on before cross-module references resolve.** They were
+  // applied last, which meant a default referencing another module's parameter
+  // had already baked in that module's *default* — so installing into hexguard
+  // with `--set backlog.root=.ai/backlog` put the findings register at
+  // `docs/.ai/backlog/FINDINGS.md` and left every link to it pointing at
+  // `docs/backlog/FINDINGS.md`. The gate caught it on the first real install;
+  // nothing in a scratch repo could have, because nothing there overrides.
+  for (const [mod, vals] of Object.entries(overrides)) {
+    out[mod] = { ...(out[mod] ?? {}), ...vals };
+  }
+
+  // A default may reference another module's parameter, e.g. findings' register
+  // living at `docs/{{backlog.root}}/FINDINGS.md`. One level only — a chain
+  // would be a template language arriving through the back door.
   for (const m of mods) {
     for (const [k, v] of Object.entries(out[m.name])) {
       if (typeof v === 'string' && v.includes('{{')) out[m.name][k] = substitute(v, m.name, out);
     }
   }
-  for (const [mod, vals] of Object.entries(overrides)) {
-    out[mod] = { ...(out[mod] ?? {}), ...vals };
-  }
   return out;
 }