@rungs/cli 0.3.0 → 0.4.0

package/src/engines3.ts

@@ -1,12 +1,14 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
 import { matchAny } from './glob.ts';
 import type { Engine, Finding } from './engines.ts';
+import { readVersionSource } from './version-source.ts';
+import { semanticText } from './text.ts';
 
 const read = (root: string, rel: string) => {
   try {
-    return readFileSync(join(root, rel), 'utf8');
+    return semanticText(readFileSync(join(root, rel), 'utf8'));
   } catch {
     return '';
   }
@@ -34,10 +36,15 @@ export function versionCmp(a: number[], b: number[]): number {
  * `changelog.d/0.1.1.md` survived two releases and was still there at 0.2.0
  * preparation (F-022). So the rule becomes mechanical.
  *
- * A fragment is stale when its filename names a version **below** the version
- * being prepared. Files whose names are not versions are ignored rather than
- * reported: the module's own fixtures use `42.feature.md`, and a gate that
- * refuses a naming convention it was not asked about is a gate people disable.
+ * The repository also states the last version whose fragments were consumed.
+ * That boundary must equal the package version in a steady tree, and a fragment
+ * at or below it is stale. Equality is what closes F-025: after a release, the
+ * forgotten fragment and package version are equal, so comparing only those two
+ * values cannot tell preparation from already-consumed work.
+ *
+ * Files whose names are not versions are ignored rather than reported: the
+ * module's own fixtures use `42.feature.md`, and a gate that refuses a naming
+ * convention it was not asked about is a gate people disable.
  */
 export const changelogFreshness: Engine = (t, root, files) => {
   const specs = Array.isArray(t) ? t : [t];
@@ -45,34 +52,119 @@ export const changelogFreshness: Engine = (t, root, files) => {
   let examined = 0;
 
   for (const spec of specs) {
-    const src = spec.version ?? {};
+    const sources = Array.isArray(spec.versions)
+      ? spec.versions
+      : [spec.version ?? { file: 'package.json', path: 'version' }];
     let current: number[] | null = null;
-    for (const rel of matchAny(files, src.file ?? 'package.json')) {
-      try {
-        const raw = (src.path ?? 'version')
-          .split('.')
-          .reduce((o: any, k: string) => o?.[k], JSON.parse(read(root, rel)));
-        current = versionParts(String(raw ?? ''));
-      } catch {
-        /* unparseable is not a stale fragment */
+    let currentSource = '';
+    const versionProblems: Finding[] = [];
+    for (const source of sources) {
+      for (const rel of matchAny(files, source.file ?? 'package.json')) {
+        const result = readVersionSource(root, rel, source);
+        if (!result.ok) {
+          versionProblems.push({ file: rel, message: `release version source ${result.reason}` });
+          continue;
+        }
+        const parsed = versionParts(result.value);
+        if (!parsed) {
+          versionProblems.push({
+            file: rel,
+            message: `release version source must contain a three-part numeric version; found ${JSON.stringify(result.value)}`,
+          });
+          continue;
+        }
+        current = parsed;
+        if (current) {
+          currentSource = rel;
+          break;
+        }
       }
       if (current) break;
     }
-    // Without a version to compare against there is no claim to make. Saying
-    // nothing is right; passing loudly would not be.
-    if (!current) continue;
+    const marker = spec.consumed_through ?? 'changelog.d/CONSUMED_THROUGH';
+    const markerExists = existsSync(join(root, marker));
+    if (!markerExists) {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' is missing — create it with 'none' if no release has consumed fragments, or the exact last consumed version`,
+      });
+      continue;
+    }
+
+    examined++;
+    const markerRaw = read(root, marker);
+    const markerValue = markerRaw.endsWith('\r\n')
+      ? markerRaw.slice(0, -2)
+      : markerRaw.endsWith('\n')
+        ? markerRaw.slice(0, -1)
+        : markerRaw;
+
+    if (markerValue === 'UNINITIALIZED') {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' is UNINITIALIZED — replace it with 'none' if no release has consumed fragments, or the exact last consumed version`,
+      });
+      continue;
+    }
+
+    const firstRelease = markerValue === 'none';
+    // `versionParts` intentionally trims package metadata. The marker is a
+    // one-token schema, so validate its complete content before reusing that
+    // parser; whitespace, a BOM or a second newline must not become valid.
+    const consumed = firstRelease || !/^\d+\.\d+\.\d+$/.test(markerValue)
+      ? null
+      : versionParts(markerValue);
+    if (!firstRelease && !consumed) {
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker '${marker}' must contain exactly 'none' or a three-part numeric version; found ${JSON.stringify(markerValue)}`,
+      });
+      continue;
+    }
+
+    findings.push(...versionProblems);
+
+    // Without a package version there used to be no claim to make. A concrete
+    // consumption boundary changes that: its steady-state equality cannot be
+    // checked, so reporting green would make the new state assertion vacuous.
+    if (!current) {
+      if (consumed) {
+        findings.push({
+          file: sources[0]?.file ?? 'package.json',
+          message:
+            `cannot reconcile consumed-through ${markerValue} because none of the declared version sources contains a three-part numeric version`,
+        });
+      }
+      continue;
+    }
+
+    if (consumed && versionCmp(consumed, current) !== 0) {
+      const relation = versionCmp(consumed, current) < 0 ? 'below' : 'above';
+      findings.push({
+        file: marker,
+        message:
+          `release consumption marker names ${markerValue}, ${relation} version ${current.join('.')} in ${currentSource} — they must match in a steady tree; advance both during reversible release preparation`,
+      });
+    }
 
     for (const rel of expand(files, spec.fragments, [])) {
       const name = rel.split('/').pop()!.replace(/\.md$/, '');
       const v = versionParts(name);
       if (!v) continue;
       examined++;
-      if (versionCmp(v, current) < 0) {
+      const belowPackage = versionCmp(v, current) < 0;
+      const alreadyConsumed = consumed ? versionCmp(v, consumed) <= 0 : false;
+      if (belowPackage || alreadyConsumed) {
         findings.push({
           file: rel,
           message:
             spec.message?.trim() ||
-            `fragment names ${name}, below the ${current.join('.')} being prepared — it was consumed by an earlier release and should have been deleted`,
+            (alreadyConsumed
+              ? `fragment names ${name}, at or below consumed-through ${markerValue} — it was already assembled and should have been deleted`
+              : `fragment names ${name}, below package version ${current.join('.')} — it belongs to an earlier release and should have been deleted`),
         });
       }
     }
@@ -213,7 +305,7 @@ export const rulePropagation: Engine = (t, root, files) => {
 export const gitState: Engine = (t, root) => {
   let out: string;
   try {
-    out = execSync('git worktree list --porcelain', { cwd: root, stdio: 'pipe' }).toString();
+    out = execFileSync('git', ['worktree', 'list', '--porcelain'], { cwd: root, stdio: 'pipe' }).toString();
   } catch {
     // Not a git repo, or git unavailable. An unattributable result blocks:
     // we do not land on an unknown.
@@ -248,7 +340,8 @@ export const mergeDriverCheck: Engine = (t, root) => {
   for (const driver of required) {
     let configured = '';
     try {
-      configured = execSync(`git config --get merge.${driver}.driver`, { cwd: root, stdio: 'pipe' }).toString().trim();
+      // Driver names come from `.gitattributes`, so they reach this as data.
+      configured = execFileSync('git', ['config', '--get', `merge.${driver}.driver`], { cwd: root, stdio: 'pipe' }).toString().trim();
     } catch {
       /* absent config exits non-zero, which is the finding */
     }
@@ -338,4 +431,3 @@ export const boardReconcile: Engine = (t, root, _files) => {
 
   return { findings, examined };
 };
-

package/src/explain.ts

@@ -1,6 +1,7 @@
 import { ENGINES, type Finding } from './engines.ts';
-import { loadTable, tableKey } from './check.ts';
+import { loadTable } from './check.ts';
 import type { DetectResult, Manifest } from './types.ts';
+import { selectEngineTable } from './engine-table.ts';
 
 /**
  * `doctor` answers a *presence* question — which of our modules does this repo
@@ -138,12 +139,7 @@ export function explainWith(
       }
 
       try {
-        const key = tableKey(g.engine!);
-        let section = table[key] ?? table;
-        if (Array.isArray(section) && section.some((s: any) => s?.id)) {
-          const mine = section.filter((s: any) => !s.id || g.id.includes(s.id));
-          if (mine.length) section = mine;
-        }
+        const section = selectEngineTable(table, g.engine!, g.id);
         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 });

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

@@ -1,12 +1,14 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+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);
@@ -334,8 +393,13 @@ export function setupGit(repoRoot: string, dryRun = false) {
         : 'git merge-file -L ours -L base -L theirs %A %O %B';
     if (!dryRun) {
       try {
-        execSync(`git config merge.${d}.name "rungs ${d.replace('rungs-', '')} driver"`, { cwd: repoRoot, stdio: 'pipe' });
-        execSync(`git config merge.${d}.driver ${JSON.stringify(cmd)}`, { cwd: repoRoot, stdio: 'pipe' });
+        // argv, not a shell string. The `rungs-generated` driver command carries
+        // single quotes, a literal `\n` and `%A %O %B`, and it was being handed
+        // to a shell through `JSON.stringify` — quoting that happens to survive
+        // cmd.exe and does not survive bash the same way. The same class of bug
+        // as F-033, found in the same sweep.
+        execFileSync('git', ['config', `merge.${d}.name`, `rungs ${d.replace('rungs-', '')} driver`], { cwd: repoRoot, stdio: 'pipe' });
+        execFileSync('git', ['config', `merge.${d}.driver`, cmd], { cwd: repoRoot, stdio: 'pipe' });
       } catch {
         continue;
       }
@@ -345,7 +409,7 @@ export function setupGit(repoRoot: string, dryRun = false) {
   let rerere = false;
   if (!dryRun) {
     try {
-      execSync('git config rerere.enabled true', { cwd: repoRoot, stdio: 'pipe' });
+      execFileSync('git', ['config', 'rerere.enabled', 'true'], { cwd: repoRoot, stdio: 'pipe' });
       rerere = true;
     } catch {
       /* not a git repo */

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;
 }