@rungs/cli 0.3.1 → 0.4.0

package/src/help.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 dependency-free: the docs claim gate imports this exact authority in a
+ * fresh land worktree where ignored package dependencies are deliberately absent.
+ *
+ * The README's table is still hand-kept and still a second inventory. That is a known cost, not an
+ * oversight — see WI-004.
+ */
+export 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'],
+  ['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 → verify the merged tree → advance, or refuse and park it'],
+  ['worktrees [path]', 'which worktrees are merged, prunable, or merged and still dirty'],
+];
+
+/** Every flag the parser honours. A flag absent here is a flag nobody can find. */
+export const FLAGS: [flag: string, blurb: string][] = [
+  ['--dry-run', 'report what would happen, write nothing'],
+  ['--explain', "doctor: also run the detectors over what this repo already has"],
+  ['--confirm-paradigm', 'add: install a module this repo already solves another way'],
+  ['--confirm-conflict', 'add: install a module that declares a conflict with one already here'],
+  ['--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'],
+];

package/src/lifecycle.ts

@@ -4,9 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { parse } from 'smol-toml';
 import type { Manifest } from './types.ts';
-import { contentHash, emittedFiles, registerGates } from './add.ts';
+import { contentHash, emittedFiles, moduleEmissionCandidates, preflightModuleEmissions, registerGates } from './add.ts';
 import { resolveParams, substitute, type Params } from './substitute.ts';
 import { loadRegistry } from './check.ts';
+import { preflightEmittedPaths, resolveEmittedPath, UnsafeEmittedPathError } from './emitted-path.ts';
+import { semanticText } from './text.ts';
 
 const SRC = dirname(fileURLToPath(import.meta.url));
 
@@ -25,7 +27,15 @@ export interface InstallRecord {
 }
 
 export function readRecord(repoRoot: string): InstallRecord | null {
-  const p = join(repoRoot, '.ai', 'rungs.toml');
+  const resolved = resolveEmittedPath(repoRoot, 'rungs', '.ai/rungs.toml');
+  if (resolved.leafAlias) {
+    throw new UnsafeEmittedPathError(
+      'rungs',
+      '.ai/rungs.toml',
+      'the install record is a symlink or junction leaf and will not be used as configuration',
+    );
+  }
+  const p = resolved.absolute;
   if (!existsSync(p)) return null;
   try {
     const raw = parse(readFileSync(p, 'utf8')) as any;
@@ -59,16 +69,26 @@ export function planUpgrade(repoRoot: string, mods: Manifest[], record: InstallR
   const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
   const items: UpgradeItem[] = [];
+  const installedMods = mods.filter((mod) => record.modules[mod.name]);
+
+  // Parameters in the install record are untrusted input to this newer CLI.
+  // Validate every installed module before examining any one of them, so a
+  // later unsafe target cannot make a partial plan look usable.
+  preflightModuleEmissions(installedMods, repoRoot, params, skillsDir);
 
-  for (const mod of mods) {
+  for (const mod of installedMods) {
     const installed = record.modules[mod.name];
-    if (!installed) continue;
     const emitted = emittedFiles(mod, params, skillsDir);
     const files: UpgradeItem['files'] = [];
     const kept = new Set(installed.kept?.files ?? []);
     for (const [rel, wouldEmit] of emitted) {
       if (kept.has(rel)) continue;   // never ours; upgrade does not touch it
-      const full = join(repoRoot, rel);
+      const resolved = resolveEmittedPath(repoRoot, mod.name, rel);
+      const full = resolved.absolute;
+      if (resolved.leafAlias) {
+        files.push({ rel, state: 'diverged' });
+        continue;
+      }
       if (!existsSync(full)) {
         files.push({ rel, state: 'missing' });
         continue;
@@ -88,21 +108,58 @@ export function planUpgrade(repoRoot: string, mods: Manifest[], record: InstallR
 export function applyUpgrade(repoRoot: string, mods: Manifest[], record: InstallRecord, plan: UpgradeItem[]) {
   const params = resolveParams(mods, paramsFrom(record), repoRoot);
   const skillsDir = record.harnesses.includes('claude') ? '.claude/skills' : '.agents/skills';
+  const prepared = plan.map((item) => {
+    const mod = mods.find((candidate) => candidate.name === item.module);
+    if (!mod) throw new Error(`upgrade plan names unknown module '${item.module}'`);
+    const emitted = emittedFiles(mod, params, skillsDir);
+    const files = item.files.map((file) => {
+      const resolved = resolveEmittedPath(repoRoot, mod.name, file.rel);
+      if ((file.state === 'stale' || file.state === 'missing') && resolved.leafAlias) {
+        throw new UnsafeEmittedPathError(
+          mod.name,
+          file.rel,
+          'the destination is a symlink or junction leaf and upgrade will not write through it',
+        );
+      }
+      if ((file.state === 'stale' || file.state === 'missing') && !emitted.has(resolved.target)) {
+        throw new Error(`module '${mod.name}' upgrade plan names target '${file.rel}' that the module does not emit`);
+      }
+      return { ...file, target: resolved.target, absolute: resolved.absolute };
+    });
+    return { item, mod, emitted, files };
+  });
+
+  // Rebuild and validate the complete emission set at apply time.  Callers may
+  // retain or manufacture a plan, so application never trusts planning to have
+  // happened in this process or against this filesystem.
+  const writable = new Set(
+    prepared.flatMap(({ mod, files }) =>
+      files
+        .filter((file) => file.state === 'stale' || file.state === 'missing')
+        .map((file) => `${mod.name}\0${file.target}`),
+    ),
+  );
+  preflightEmittedPaths(repoRoot, [
+    ...moduleEmissionCandidates(prepared.map(({ mod }) => mod), params, skillsDir).map((candidate) =>
+      writable.has(`${candidate.moduleName}\0${candidate.target}`)
+        ? { ...candidate, writeExisting: true }
+        : candidate,
+    ),
+    { moduleName: prepared[0]?.mod.name ?? 'upgrade', target: '.ai/rungs.toml', writeExisting: true },
+  ]);
+
   let written = 0;
   // Only files this run rewrote. A diverged file is not in here, which is what
   // keeps its recorded hash — and therefore its protection — intact (F-017).
   const rewritten = new Map<string, Map<string, string>>();
-  for (const item of plan) {
-    const mod = mods.find((m) => m.name === item.module)!;
-    const emitted = emittedFiles(mod, params, skillsDir);
-    for (const f of item.files) {
+  for (const { mod, emitted, files } of prepared) {
+    for (const f of files) {
       if (f.state !== 'stale' && f.state !== 'missing') continue;
-      const full = join(repoRoot, f.rel);
-      const content = emitted.get(f.rel)!;
-      mkdirSync(dirname(full), { recursive: true });
-      writeFileSync(full, content);
+      const content = emitted.get(f.target)!;
+      mkdirSync(dirname(f.absolute), { recursive: true });
+      writeFileSync(f.absolute, content);
       if (!rewritten.has(mod.name)) rewritten.set(mod.name, new Map());
-      rewritten.get(mod.name)!.set(f.rel, contentHash(content));
+      rewritten.get(mod.name)!.set(f.target, contentHash(content));
       written++;
     }
   }
@@ -117,7 +174,7 @@ export function applyUpgrade(repoRoot: string, mods: Manifest[], record: Install
   // dropped from a manifest leaves the registry with the block that replaces it.
   // Idempotent, and cheap enough to run for every module in the plan rather than
   // only the ones whose files happened to be stale.
-  const upgraded = plan.map((p) => mods.find((m) => m.name === p.module)!).filter(Boolean);
+  const upgraded = prepared.map(({ mod }) => mod);
   const gateActions = upgraded.length ? registerGates(upgraded, repoRoot, false) : [];
 
   const recorded = updateRecordAfterUpgrade(
@@ -149,10 +206,14 @@ export function updateRecordAfterUpgrade(
   repoRoot: string,
   updates: { module: string; version: string; hashes: Map<string, string> }[],
 ): number {
-  const path = join(repoRoot, '.ai', 'rungs.toml');
+  const path = preflightEmittedPaths(repoRoot, [
+    { moduleName: updates[0]?.module ?? 'upgrade', target: '.ai/rungs.toml', writeExisting: true },
+  ])[0].absolute;
   if (!existsSync(path) || !updates.length) return 0;
 
-  const lines = readFileSync(path, 'utf8').split('\n');
+  const original = readFileSync(path, 'utf8');
+  const newline = original.match(/\r\n|\r|\n/)?.[0] ?? '\n';
+  const lines = semanticText(original).split('\n');
   const byModule = new Map(updates.map((u) => [u.module, u]));
   let changed = 0;
   let current: { module: string; hashes: boolean } | null = null;
@@ -177,8 +238,9 @@ export function updateRecordAfterUpgrade(
       const entry = /^"([^"]+)"\s*=/.exec(line);
       const replacement = entry && byModule.get(current.module)!.hashes.get(entry[1]);
       if (replacement) {
-        out.push(`"${entry[1]}" = "${replacement}"`);
-        changed++;
+        const next = `"${entry[1]}" = "${replacement}"`;
+        if (next !== line) changed++;
+        out.push(next);
         continue;
       }
     }
@@ -186,7 +248,8 @@ export function updateRecordAfterUpgrade(
     out.push(line);
   }
 
-  writeFileSync(path, out.join('\n'));
+  const updated = out.join(newline);
+  if (changed > 0 && updated !== original) writeFileSync(path, updated);
   return changed;
 }
 
@@ -212,7 +275,7 @@ export function eject(repoRoot: string, mods: Manifest[], dryRun = false) {
   // The first version copied `check.ts` and `manifest.ts` too, which pull in the
   // TOML parser — so an ejected repo crashed on a module it could not resolve.
   // An exit that does not work is not an exit.
-  const engines = ['glob.ts', 'engines.ts', 'engines2.ts'];
+  const engines = ['glob.ts', 'text.ts', 'engine-table.ts', 'engines.ts', 'engines2.ts'];
   const { gates } = loadRegistry(repoRoot);
   const declared = gates.filter((g) => g.kind === 'declared' && g.table);
   const tables = [...new Set(declared.map((g) => g.table!))];
@@ -267,6 +330,7 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ENGINES } from './engines.ts';
+import { selectEngineTable } from './engine-table.ts';
 import { walk } from './glob.ts';
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -283,12 +347,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', '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));
-  if (mine.length) section = mine;
-}
+const section = selectEngineTable(raw, engine, id);
 const r = ENGINES[engine](section, root, walk(root));
 for (const f of r.findings) console.error(\`  \${f.file ? f.file + ': ' : ''}\${f.message}\`);
 process.exit(r.findings.length ? 1 : 0);

package/src/manifest.ts

@@ -28,12 +28,48 @@ export function loadManifest(dir: string): Manifest {
   };
 
   // `[provenance]` is required and validated (ADR-0003). A module with no
-  // traceable source is one somebody invented, and `doctor` cannot ask its
-  // questions without the incident.
+  // traceable source is one somebody invented, and that is the thing CLAUDE.md's
+  // evidence rule exists to prevent.
+  //
+  // F-037: the schema had exactly one shape, and it *asserted extraction* —
+  // `sources`, `patterns` and `incident`, all required. A module authored
+  // outside this package has none of the three, and the only way past the
+  // validator was prose in fields whose names claim a pedigree it does not
+  // have. It never blocked anyone: any non-empty string loads, which is the
+  // worse outcome, because nothing then distinguished an honest "none" from an
+  // invented incident. All fifteen bundled modules were extracted, so the case
+  // had never been exercised and the first author outside them was quietly
+  // invited to make something up.
+  //
+  // So the distinction is declared rather than written around, and a designed
+  // module may not carry the extracted module's fields. **Half a claim is the
+  // failure mode**: a `sources` line naming the repo that inspired a module
+  // reads, to every later reader, exactly like a repo that paid for it.
   const p = manifest.provenance;
-  if (!p?.sources?.length) throw new Error(`${name}: [provenance].sources is required`);
-  if (!p?.patterns?.length) throw new Error(`${name}: [provenance].patterns is required`);
-  if (!p?.incident?.trim()) throw new Error(`${name}: [provenance].incident is required`);
+  if (!p) throw new Error(`${name}: [provenance] is required`);
+  const kind = p.kind ?? 'extracted';
+  if (kind !== 'extracted' && kind !== 'designed') {
+    throw new Error(`${name}: [provenance].kind must be 'extracted' or 'designed', not '${kind}'`);
+  }
+  if (kind === 'extracted') {
+    if (!p.sources?.length) throw new Error(`${name}: [provenance].sources is required`);
+    if (!p.patterns?.length) throw new Error(`${name}: [provenance].patterns is required`);
+    if (!p.incident?.trim()) throw new Error(`${name}: [provenance].incident is required`);
+  } else {
+    if (!p.rationale?.trim()) {
+      throw new Error(`${name}: [provenance].rationale is required when kind = "designed" — say why it exists, in the first person`);
+    }
+    if (p.incident?.trim()) {
+      throw new Error(`${name}: [provenance].incident belongs to an extracted module; a designed one has no incident to name`);
+    }
+    if (p.sources?.length) {
+      throw new Error(`${name}: [provenance].sources belongs to an extracted module; cite influences in the rationale instead`);
+    }
+    // `patterns` is deliberately still allowed. A designed module may implement
+    // patterns from the catalogue, and the catalogue entries are themselves
+    // evidenced — citing one claims nothing about this module's own history.
+  }
+  manifest.provenance = { ...p, kind };
 
   return manifest;
 }

package/src/render.ts

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { walk } from './glob.ts';
+import { preflightEmittedPaths, resolveEmittedPath, type EmittedPathCandidate } from './emitted-path.ts';
+import { semanticText } from './text.ts';
 
 export type Harness = 'claude' | 'copilot' | 'cursor' | 'agents-md';
 
@@ -20,12 +22,18 @@ export interface RenderEntry {
   dropped?: string[];
 }
 
+export interface ProspectiveRule {
+  moduleName: string;
+  target: string;
+  content: string;
+}
+
 const DO_NOT_EDIT = (source: string) =>
   `Generated by \`rungs render\` from ${source}. Do not edit — your changes are overwritten.`;
 
 /** Parse `.ai/rules/*.md`: the neutral source ADR-0001 renders from. */
 export function readRules(repoRoot: string): Rule[] {
-  const dir = join(repoRoot, '.ai', 'rules');
+  const dir = resolveEmittedPath(repoRoot, 'render', '.ai/rules').absolute;
   const rules: Rule[] = [];
   let files: string[];
   try {
@@ -34,21 +42,26 @@ export function readRules(repoRoot: string): Rule[] {
     return rules;
   }
   for (const rel of files) {
-    const raw = readFileSync(join(dir, rel), 'utf8');
-    const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
-    if (!m) continue;
-    const [, fm, body] = m;
-    rules.push({
-      file: rel,
-      description: scalar(fm, 'description'),
-      paths: list(fm, 'paths'),
-      enforcement: scalar(fm, 'enforcement'),
-      body: body.trim(),
-    });
+    const raw = semanticText(readFileSync(join(dir, rel), 'utf8'));
+    const rule = parseRule(rel, raw);
+    if (rule) rules.push(rule);
   }
   return rules;
 }
 
+function parseRule(file: string, raw: string): Rule | null {
+  const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return null;
+  const [, fm, body] = m;
+  return {
+    file,
+    description: scalar(fm, 'description'),
+    paths: list(fm, 'paths'),
+    enforcement: scalar(fm, 'enforcement'),
+    body: body.trim(),
+  };
+}
+
 function scalar(fm: string, key: string): string | undefined {
   const folded = fm.match(new RegExp(`^${key}:\\s*>-?\\s*\\n([\\s\\S]*?)(?=\\n\\S|$)`, 'm'));
   if (folded) return folded[1].split('\n').map((l) => l.trim()).filter(Boolean).join(' ');
@@ -127,10 +140,40 @@ function commonDirPrefix(paths: string[]): string | null {
   return dirs.every((d) => d === first) && first.includes('/') ? first : null;
 }
 
-export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
+interface PreparedRender {
+  entries: RenderEntry[];
+  outputs: { entry: RenderEntry; absolute: string; content: string }[];
+  routingOnly: Rule[];
+}
+
+function prepareRender(
+  repoRoot: string,
+  harnesses: Harness[],
+  prospective: ProspectiveRule[] = [],
+  preceding: EmittedPathCandidate[] = [],
+): PreparedRender {
   const rules = readRules(repoRoot);
+  const owners = new Map(rules.map((rule) => [rule.file, 'render']));
+  const occupied = new Set(rules.map((rule) => `.ai/rules/${rule.file}`));
+
+  // Model the installer's no-overwrite rule: an existing source remains the
+  // one rendered.  New prospective rules are considered in module order, just
+  // as addModule will create the first and keep any later collision.
+  for (const pending of prospective) {
+    const source = resolveEmittedPath(repoRoot, pending.moduleName, pending.target);
+    if (occupied.has(source.target) || existsSync(source.absolute)) continue;
+    occupied.add(source.target);
+    if (!source.target.startsWith('.ai/rules/')) continue;
+    const file = source.target.slice('.ai/rules/'.length);
+    const rule = parseRule(file, pending.content);
+    if (!rule) continue;
+    rules.push(rule);
+    owners.set(file, pending.moduleName);
+  }
+
   const entries: RenderEntry[] = [];
   const routingOnly: Rule[] = [];
+  const planned: { entry: RenderEntry; target: string; content: string; owner: string }[] = [];
 
   for (const rule of rules) {
     for (const harness of harnesses) {
@@ -140,23 +183,62 @@ export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
         if (harness === 'agents-md') routingOnly.push(rule);
         continue;
       }
-      const full = join(repoRoot, out.target);
-      mkdirSync(dirname(full), { recursive: true });
-      writeFileSync(full, out.content);
-      entries.push({ rule: rule.file, harness, target: out.target, dropped: out.dropped });
+      const entry = { rule: rule.file, harness, target: out.target, dropped: out.dropped };
+      entries.push(entry);
+      planned.push({ entry, target: out.target, content: out.content, owner: owners.get(rule.file) ?? 'render' });
     }
   }
 
+  const candidates = [
+    ...preceding,
+    ...planned.map((out) => ({ moduleName: out.owner, target: out.target, writeExisting: true })),
+    ...(harnesses.includes('agents-md')
+      ? [{ moduleName: 'render', target: 'AGENTS.md', shared: true, writeExisting: true }]
+      : []),
+    { moduleName: 'render', target: '.ai/render-report.md', writeExisting: true },
+  ];
+  const resolved = preflightEmittedPaths(repoRoot, candidates);
+  return {
+    entries,
+    outputs: planned.map((out, index) => ({
+      entry: out.entry,
+      content: out.content,
+      absolute: resolved[preceding.length + index].absolute,
+    })),
+    routingOnly,
+  };
+}
+
+/** Validate all current and would-be post-install render outputs without writing. */
+export function preflightRender(
+  repoRoot: string,
+  harnesses: Harness[],
+  prospective: ProspectiveRule[] = [],
+  preceding: EmittedPathCandidate[] = [],
+): void {
+  prepareRender(repoRoot, harnesses, prospective, preceding);
+}
+
+export function render(repoRoot: string, harnesses: Harness[]): RenderEntry[] {
+  const prepared = prepareRender(repoRoot, harnesses);
+
+  for (const output of prepared.outputs) {
+    mkdirSync(dirname(output.absolute), { recursive: true });
+    writeFileSync(output.absolute, output.content);
+  }
+
   // The report said root AGENTS.md "gets a pointer" and nothing wrote one — a
   // degradation notice that was itself a silent drop, in the function whose
   // whole job is not to have those. Written now, as a managed block.
-  writeRoutingBlock(repoRoot, routingOnly, harnesses);
-  return entries;
+  writeRoutingBlock(repoRoot, prepared.routingOnly, harnesses);
+  return prepared.entries;
 }
 
 function writeRoutingBlock(repoRoot: string, rules: Rule[], harnesses: Harness[]) {
   if (!harnesses.includes('agents-md')) return;
-  const target = join(repoRoot, 'AGENTS.md');
+  const target = preflightEmittedPaths(repoRoot, [
+    { moduleName: 'render', target: 'AGENTS.md', shared: true, writeExisting: true },
+  ])[0].absolute;
   if (!existsSync(target)) return;
   const begin = '<!-- rungs:begin rules-routing -->';
   const end = '<!-- rungs:end rules-routing -->';
@@ -217,6 +299,9 @@ export function writeReport(repoRoot: string, entries: RenderEntry[], harnesses:
     '',
   );
   const content = lines.join('\n');
-  writeFileSync(join(repoRoot, '.ai', 'render-report.md'), content);
+  const target = preflightEmittedPaths(repoRoot, [
+    { moduleName: 'render', target: '.ai/render-report.md', writeExisting: true },
+  ])[0].absolute;
+  writeFileSync(target, content);
   return content;
 }

package/src/selftest.ts

@@ -1,4 +1,5 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { ENGINES, type Finding } from './engines.ts';
@@ -68,6 +69,49 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
   if (typeof input === 'string') return [write(targetPath(table), `${input}\n`)];
   if (!fx || typeof fx !== 'object') return null;
 
+  // A branch delta plus the companion files it carries. Unlike content-only
+  // fixtures this needs a real repository: the engine deliberately observes
+  // committed, staged, unstaged and untracked Git state rather than trusting a
+  // fixture's list as the answer.
+  if (Array.isArray(fx.changed) && Array.isArray(fx.fragments)) {
+    const git = (...args: string[]) =>
+      execFileSync('git', args, { cwd: root, stdio: 'pipe' }).toString().trim();
+    const changed = fx.changed.map(String);
+    git('init', '-q', '-b', 'main', '.');
+    git('config', 'user.email', 'selftest@rungs.local');
+    git('config', 'user.name', 'rungs-selftest');
+    const written = [write('.fixture-base', 'base\n')];
+    if (changed.length && typeof fx.inherited_exempt === 'string') {
+      written.push(write(
+        changed[0],
+        `// ${fx.inherited_exempt}\nexport const fixtureState = 'base';\n`,
+      ));
+    }
+    git('add', '--all');
+    git('commit', '-q', '-m', 'base');
+    git('switch', '-q', '-c', 'fixture/change');
+
+    for (const [index, rel] of changed.entries()) {
+      const evidence = index === 0 && typeof fx.exempt === 'string'
+        ? fx.exempt
+        : index === 0 && typeof fx.inherited_exempt === 'string'
+          ? fx.inherited_exempt
+          : undefined;
+      const body = evidence
+        ? `// ${evidence}\nexport const fixtureState = 'branch';\n`
+        : 'fixture change\n';
+      written.push(write(rel, body));
+    }
+    const changelogDir = fx.dir ?? 'changelog.d';
+    for (const rel of fx.fragments) {
+      const concrete = String(rel).replace(/\{\{changelog_dir\}\}/g, changelogDir);
+      written.push(write(concrete, '# fixture fragment\n'));
+    }
+    git('add', '--all');
+    git('commit', '-q', '-m', 'fixture change');
+    return [...new Set(written)];
+  }
+
   // A set of manifests and the version each states — the computed-claim shapes.
   // `{ "package.json": "1.2.0", "site/package.json": "1.1.0" }`.
   if (fx.packages && typeof fx.packages === 'object') {
@@ -76,6 +120,26 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
     );
   }
 
+  // Format-aware release-version sources. Values are rendered into the real
+  // source shape so one fixture can prove JSON, TOML and Directory.Build.props
+  // all participate in the same comparison.
+  if (fx.versions && typeof fx.versions === 'object') {
+    return Object.entries(fx.versions).map(([rel, version]) => {
+      const value = String(version).replace(/"/g, '\\"');
+      if (rel.endsWith('.toml')) return write(rel, `[project]\nversion = "${value}"\n`);
+      if (rel.endsWith('.props')) {
+        return write(rel, `<Project><PropertyGroup><Version>${String(version)}</Version></PropertyGroup></Project>\n`);
+      }
+      return write(rel, JSON.stringify({ name: rel.replace(/\W/g, '-'), version }));
+    });
+  }
+
+  // Raw version-source fixtures preserve malformed documents and missing or
+  // non-scalar values exactly; normalising them would erase the failure under test.
+  if (fx.version_files && typeof fx.version_files === 'object') {
+    return Object.entries(fx.version_files).map(([rel, content]) => write(rel, String(content)));
+  }
+
   // Named files in a parameterised directory, plus the version they are judged
   // against — the changelog shapes. `dir` is stated by the fixture rather than
   // assumed here, because the self-test sees the module's *raw* table and a
@@ -87,7 +151,19 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
     // `changelog.d/*.md` does not match. The gate then reports "did not fire"
     // about the harness rather than the fixture.
     const written = fx.fragments.map((n: string) => write(`${dir}/${n}`, `# ${n}\n`));
-    written.push(write('package.json', JSON.stringify({ version: fx.version })));
+    if (fx.version_file === 'Directory.Build.props') {
+      written.push(write('Directory.Build.props', `<Project><PropertyGroup><Version>${fx.version}</Version></PropertyGroup></Project>\n`));
+    } else if (fx.version_file === 'pyproject.toml') {
+      written.push(write('pyproject.toml', `[project]\nversion = "${fx.version}"\n`));
+    } else {
+      written.push(write('package.json', JSON.stringify({ version: fx.version })));
+    }
+    // `consumed_through` is intentionally presence-sensitive: omitting it builds
+    // the missing-marker failure, while an empty string builds the blank-marker
+    // failure. Truthiness would collapse both into the same fixture.
+    if ('consumed_through' in fx) {
+      written.push(write(`${dir}/CONSUMED_THROUGH`, `${fx.consumed_through}\n`));
+    }
     return written;
   }
 
@@ -128,8 +204,9 @@ function build(root: string, table: any, fx: any, input?: string): string[] | nu
 }
 
 /**
- * Engines whose verdict depends **only on the content of the file the fixture
- * describes**, so a fixture can be executed faithfully in an empty directory.
+ * Engines whose verdict can be reproduced completely by a fixture builder.
+ * Most depend only on content in an empty directory; `change-requires-file`
+ * gets the explicit Git repository built above.
  *
  * The rest need context the fixture does not carry, and running them anyway
  * produces confident nonsense. `gates-links-resolve`'s `pass` fixture is
@@ -152,6 +229,7 @@ const CONTEXT_FREE: ReadonlySet<string> = new Set([
   'register-schema',
   'file-population',
   'changelog-freshness',
+  'change-requires-file',
   'computed-claim',
 ]);
 
@@ -168,7 +246,7 @@ const CONTEXT_FREE: ReadonlySet<string> = new Set([
  */
 function deparam<T>(spec: T, dir: string): T {
   const walk = (v: any): any =>
-    typeof v === 'string' ? v.replace(/\{\{[^}]+\}\}/g, dir)
+    typeof v === 'string' ? v.replace(/\{\{changelog_dir\}\}/g, dir)
       : Array.isArray(v) ? v.map(walk)
       : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]))
       : v;
@@ -205,12 +283,11 @@ export function runSelfTests(
       // Same bridge, for paths: a fixture that names a parameterised directory
       // has to hand the spec the same literal it wrote the files into.
       if (Array.isArray(b.fixture?.fragments)) spec = deparam(spec, b.fixture.dir ?? 'changelog.d');
-      // And for `exclude`, which is the thing under test in half these fixtures:
-      // the table ships it empty by default, so a fixture proving exclusion works
-      // has to set it, exactly as a repo would.
-      if (Array.isArray(b.fixture?.exclude)) {
-        const ex = b.fixture.exclude;
-        spec = Array.isArray(spec) ? spec.map((s: any) => ({ ...s, exclude: ex })) : { ...spec, exclude: ex };
+      if (Array.isArray(b.fixture?.changed)) {
+        const base = b.fixture.base_branch ?? 'main';
+        spec = Array.isArray(spec)
+          ? spec.map((s: any) => ({ ...s, base_branch: base }))
+          : { ...spec, base_branch: base };
       }
       if (!files) {
         out.push({ gate: gateId, expect, outcome: 'unrun', detail: `no builder for fixture ${JSON.stringify(b.fixture).slice(0, 60)}` });

package/src/storage-key.ts

@@ -0,0 +1,20 @@
+/**
+ * A conservative, locale-independent key for one already-separated storage
+ * segment that may move between a case-sensitive checkout, Windows, and
+ * default case-insensitive macOS APFS.
+ *
+ * NFKD exposes compatibility forms, while the lower/upper sequence expands
+ * multi-code-point case forms such as sharp-S. The final normalization catches
+ * decompositions introduced by case conversion itself.
+ *
+ * Do not pass a complete path or ref here. Compatibility decomposition can
+ * turn U+FF3C or U+FF0F into a separator; callers must split first so folding
+ * cannot manufacture path structure.
+ */
+export function canonicalCaselessSegmentKey(segment: string): string {
+  return segment.normalize('NFKD').toLowerCase().toUpperCase().normalize('NFKD');
+}
+
+export function canonicalCaselessSegmentEqual(left: string, right: string): boolean {
+  return canonicalCaselessSegmentKey(left) === canonicalCaselessSegmentKey(right);
+}