unknown-knowledge 2.1.0 → 3.0.0-rc.1

package/payload/engine/commands/resolve.js

@@ -5,6 +5,7 @@
  *
  *   node payload/engine/resolve.js <query terms...> [--json] [--root <dir>]
  *   node payload/engine/resolve.js --paths <file1,file2> [--json] [--root <dir>]
+ *   node payload/engine/resolve.js --path <file> [--path <file>...] [--json] [--root <dir>]
  *   node payload/engine/resolve.js --doc <document> [--json] [--root <dir>]
  *
  * ONE ENTRY POINT, THREE INPUT SHAPES (UCS-1156). A query, a set of repo paths,
@@ -86,6 +87,14 @@
  *             immediately around a hit, and depth 2 is most of the store
  *             arriving unranked
  *
+ * Incoming supersession (UCS-1226) adds a separate `superseded-by` array to
+ * leaf results, including document gather and scope exclusions. References
+ * carry id/notation/heading/file, stage/time/downranked/demotions, and applies
+ * (declared jurisdictions, empty means universal). No content, score, trust
+ * verdict, or nested edges: callers compare scope, preflight targets, and read
+ * sources. All direct successors are sorted by accession, never by recency.
+ * The inverse is rebuilt from relates.supersedes at load; no reciprocal authoring.
+ *
  * Knowledge entry points now join STRUCTURALLY as well as textually: a leaf
  * that declares a concept surfaces under it whether or not any term text
  * matches, so knowledge stops depending on two authors choosing the same words.
@@ -164,7 +173,7 @@
  * localized enough to act on. The stopword list is pinned and shipped in the
  * engine (lib/decomposition.js), never configurable per run.
  *
- * --paths mode — reverse lookup over BOTH pointer families: "which concepts
+ * Paths mode (--path or legacy --paths) — reverse lookup over BOTH pointer families: "which concepts
  * point at these files, and which leaves govern them" (UCS-1151). The join runs
  * over concept source-of-truth pointers and over leaf `paths` declarations, so
  * a diff-shaped input surfaces the knowledge that governs the files before an
@@ -173,17 +182,18 @@
  * nested under a FOLDER pointer (§3.1). Folder-ness is read from the
  * filesystem, not from the name — `src/api.v2` is a directory whose extname is
  * ".v2" — and from the name only when the pointer is gone, since a diff names
- * deleted paths; see folderPointerTest. Paths are normalized with path.posix
- * semantics (dots resolved, separators collapsed, backslashes converted,
- * absolute paths relativized against the store root) so attribution survives
- * the forms real tooling emits. An entry naming the repo root is a usage
+ * deleted paths; see folderPointerTest. Paths use path.posix semantics (dots
+ * resolved, separators collapsed, absolute paths relativized against the store
+ * root). Legacy --paths trims whitespace and converts backslashes; --path keeps
+ * both literal and takes one complete name per argument, without comma splitting.
+ * An entry naming the repo root is a usage
  * error, never a silently dropped lookup. A lookup, not subset validation (no
  * D-012 conflict). Paths are deduped and sorted ascending.
  *
  * Zero resolution is a NORMAL outcome (PRD §7 — common in month one): exit 0
- * with an explicit empty result plus the fallback conduct (search within
- * survey-scope.yaml; append a retrieval-miss finding only if the topic
- * plausibly should be mapped). Exit codes (PRD §5): 0 = the lookup ran (hits
+ * with an explicit empty result plus a pointer to the canonical recovery
+ * protocol (preflight, catalog recovery, then survey-scoped fallback).
+ * Exit codes (PRD §5): 0 = the lookup ran (hits
  * or none), 2 = usage/engine failure — a lookup that never ran is a failure,
  * never a silent empty result. The resolver emits no findings, so it never
  * exits 1; gating on store health is preflight's job. Store health is still
@@ -225,6 +235,7 @@ import { loadSuppressions } from '../lib/suppressions.js';
 
 export const USAGE = `usage: node payload/engine/resolve.js <query terms...> [--json] [--root <dir>] [--today <YYYY-MM-DD>]
        node payload/engine/resolve.js --paths <file1,file2> [--json] [--root <dir>] [--today <YYYY-MM-DD>]
+       node payload/engine/resolve.js --path <file> [--path <file>...] [--json] [--root <dir>] [--today <YYYY-MM-DD>]
        node payload/engine/resolve.js --doc <document> [--json] [--root <dir>] [--today <YYYY-MM-DD>]`;
 
 // The concept ladder and the draft downrank moved to lib/scoring.js (UCS-1152)
@@ -415,10 +426,8 @@ function confusables(model, record) {
  * OUTGOING edges only. The ticket says the resolver expands over relates edges
  * FROM a hit, and outgoing is what this leaf's author asserted: a leaf declares
  * what IT depends on, what IT contradicts. An incoming edge is somebody else's
- * claim about this leaf, which is a genuinely useful thing to see and a
- * different question — it belongs to whatever surface presents "what cites
- * this", where it can be labeled as such rather than blended into the leaf's
- * own assertions.
+ * claim about this leaf. Incoming supersession is published separately as
+ * `superseded-by` (UCS-1226), never blended into the leaf's own assertions.
  *
  * Neighbors resolve through `leafIdentityOf`, the one lookup every surface
  * asks — so an edge citing a leaf by its retired notation reaches nothing here
@@ -473,7 +482,7 @@ function relatesNeighborhood(model, record) {
  * are exactly the ones whose whole contract is that they are STABLE keys that
  * may be null.
  */
-function publishLeaf(model, entry, today) {
+function leafMetadata(entry, today) {
   const { file, record: leaf } = entry;
   const stage = leafStage(leaf);
   const provenance = leaf.provenance;
@@ -564,10 +573,19 @@ function publishLeaf(model, entry, today) {
     // reading one answer.
     time,
     file,
-    // The one-hop structural neighborhood (UCS-1151) — every leaf the resolver
-    // publishes carries it, so "any hit carries its relates neighborhood" is
-    // true by construction rather than by remembering to attach it per mode.
-    [RELATES_FIELD]: relatesNeighborhood(model, leaf),
+  };
+}
+
+/** One shared projection; successors are navigation, never recursively expanded. */
+function publishLeaf(model, entry, today) {
+  return {
+    ...leafMetadata(entry, today),
+    [RELATES_FIELD]: relatesNeighborhood(model, entry.record),
+    'superseded-by': (model.supersedingLeaves.get(entry.identity) ?? []).map((id) => {
+      const successor = model.leaves.get(id);
+      const { excerpt, provenance, ...metadata } = leafMetadata(successor, today);
+      return { ...metadata, applies: [...leafJurisdictions(successor.record)].sort(compare) };
+    }),
   };
 }
 
@@ -866,6 +884,7 @@ function applyScope(scored, jurisdictions) {
       file: leaf.file,
       applies: leaf.applies,
       asked,
+      'superseded-by': leaf['superseded-by'],
       reason: `declares applies.jurisdictions [${leaf.applies.join(', ')}] — the query is scoped to [${asked.join(', ')}], which this leaf does not cover (UCS-1152)`,
     });
   }
@@ -1028,19 +1047,21 @@ function resolveQuery(model, terms, today) {
  * lookup failed or the store is simply silent on the topic, and those demand
  * different next steps.
  */
-const ZERO_RESOLUTION_CONDUCT = 'zero resolution is a normal outcome (PRD §7): fall back to search within survey-scope.yaml; append a retrieval-miss finding only if this topic plausibly should be mapped (an unmapped area the scope excludes is expected, not a miss)';
+const ZERO_RESOLUTION_CONDUCT = 'zero resolution is a normal outcome (PRD §7): preflight store health, recover through relevant catalogs, then search unresolved tasks through the survey map bounded by repo-root survey-scope.yaml. Record recovered wording as retrieval-struggle, missing in-scope evidence as retrieval-miss, and excluded topics as expected absence. Follow protocol/AGENTS.md for layout and recovery rules.';
 
 // ---------------------------------------------------------------- paths mode
 
 /**
  * Normalize a path to the repo-root-relative posix form pointers use (§9.1):
- * backslashes become '/', `..`/`.`/`//` resolve away (path.posix semantics),
+ * `..`/`.`/`//` resolve away (path.posix semantics),
  * trailing slashes drop, and absolute paths relativize against `root`.
+ * Legacy --paths also trims whitespace and converts backslashes to '/'. With
+ * --path, those bytes are literal filename data on both sides of the join.
  * Wrong normalization is wrong ATTRIBUTION — `a/b/../c.ts` must hit the file
  * pointer `a/c.ts`, not the folder pointer `a/b`.
  */
-function normPath(root, p) {
-  let path = posix.normalize(p.trim().replace(/\\/g, '/'));
+function normPath(root, p, literal = false) {
+  let path = posix.normalize(literal ? p : p.trim().replace(/\\/g, '/'));
   if (posix.isAbsolute(path)) path = posix.relative(root.replace(/\\/g, '/'), path);
   path = path.replace(/\/+$/, '');
   return path === '.' ? '' : path;
@@ -1088,20 +1109,21 @@ function folderPointerTest(repoRoot) {
   };
 }
 
-function resolvePaths(model, rawPaths, repoRoot, today) {
+function resolvePaths(model, rawPaths, repoRoot, today, literal = false) {
+  const flag = literal ? '--path' : '--paths';
   // Pointers are repo-root-relative (§9.1), so both sides normalize against
   // the repo root — the KK-08 two-root convention (model.root may be the
   // nested unknown-knowledge/ store dir in a seeded repo).
   // An entry that normalizes away (empty, ".", "src/..") names the repo root,
   // not a path inside it. Dropping it silently would shrink the lookup the
   // caller asked for — a lookup that never ran, wearing a clean exit.
-  const rootish = rawPaths.filter((p) => normPath(repoRoot, p) === '');
+  const rootish = rawPaths.filter((p) => normPath(repoRoot, p, literal) === '');
   if (rootish.length) {
-    throw new UsageError(`--paths entries ${rootish.map((p) => JSON.stringify(p)).join(', ')} name the repo root, not a path inside it — name the files or directories the change touched`);
+    throw new UsageError(`${flag} entries ${rootish.map((p) => JSON.stringify(p)).join(', ')} name the repo root, not a path inside it — name the files or directories the change touched`);
   }
-  const paths = [...new Set(rawPaths.map((p) => normPath(repoRoot, p)))].sort(compare);
+  const paths = [...new Set(rawPaths.map((p) => normPath(repoRoot, p, literal)))].sort(compare);
   if (!paths.length) {
-    throw new UsageError('--paths must name at least one path — a lookup that never ran is a failure, never a silent empty result');
+    throw new UsageError(`${flag} must name at least one path — a lookup that never ran is a failure, never a silent empty result`);
   }
   const isFolderPointer = folderPointerTest(repoRoot);
   // Leaf `paths` are the second pointer family (UCS-1151), indexed once for the
@@ -1123,7 +1145,7 @@ function resolvePaths(model, rawPaths, repoRoot, today) {
    * the validator is where the author is told to fix it.
    */
   const governs = (pointer, path) => {
-    const p = normPath(repoRoot, pointer);
+    const p = normPath(repoRoot, pointer, literal);
     if (p === '') return false;
     return path === p || (isFolderPointer(p) && path.startsWith(`${p}/`));
   };
@@ -1332,6 +1354,7 @@ function renderDoc(payload) {
       // applicability the reader has to act on, not a detail of the hit.
       if (g['scope-mismatch']) lines.push(`    scope-mismatch: ${g['scope-mismatch']}`);
       for (const d of g.demotions) lines.push(`    demoted (${d.reason}): ${d.detail}`);
+      lines.push(...renderSuccessors(g, '    '));
     }
     lines.push('');
   }
@@ -1363,15 +1386,19 @@ function parseArgs(argv) {
   const { options, positionals } = parseFlags(argv, {
     boolean: ['json'],
     value: ['root', 'today', 'doc'],
-    repeatable: ['paths'],
-    // Query terms arrive as bare arguments; --paths is the reverse lookup;
+    repeatable: ['paths', 'path'],
+    // Query terms arrive as bare arguments; --path/--paths are reverse lookup;
     // --doc is the third input shape (UCS-1156).
     positionals: true,
   });
+  if (options.path && options.paths) {
+    throw new UsageError('cannot combine --path and --paths — choose complete paths or legacy comma-separated lists');
+  }
   const opts = {
     json: !!options.json,
     root: options.root ?? process.cwd(),
-    paths: options.paths ? options.paths.flatMap((v) => v.split(',')) : null,
+    paths: options.path ?? (options.paths ? options.paths.flatMap((v) => v.split(',')) : null),
+    literalPaths: !!options.path,
     doc: options.doc ?? null,
     terms: positionals,
     // The injected date the time verdicts are measured against (UCS-1150).
@@ -1390,14 +1417,14 @@ function parseArgs(argv) {
   // a query — so it is a usage error rather than a silently-preferred mode.
   const shapes = [
     opts.terms.length ? 'query terms' : null,
-    opts.paths ? '--paths' : null,
+    opts.paths ? (opts.literalPaths ? '--path' : '--paths') : null,
     opts.doc ? '--doc' : null,
   ].filter(Boolean);
   if (shapes.length > 1) {
-    throw new UsageError(`give exactly one input shape, got ${shapes.join(' and ')} — a query, --paths, or --doc`);
+    throw new UsageError(`give exactly one input shape, got ${shapes.join(' and ')} — a query, --path/--paths, or --doc`);
   }
   if (!shapes.length) {
-    throw new UsageError('nothing to resolve — give query terms, --paths, or --doc');
+    throw new UsageError('nothing to resolve — give query terms, --path/--paths, or --doc');
   }
   return opts;
 }
@@ -1430,7 +1457,15 @@ function renderRelates(leaf, indent = '      ') {
     if (!neighbors.length) continue;
     lines.push(`${indent}${kind}: ${neighbors.map((n) => `${n.id ?? n.notation} "${n.heading ?? '?'}"`).join(', ')}`);
   }
-  return lines;
+  return [...lines, ...renderSuccessors(leaf, indent)];
+}
+
+/** Incoming claims remain navigation: applicability and target preflight are required. */
+function renderSuccessors(leaf, indent) {
+  return (leaf['superseded-by'] ?? []).map((successor) =>
+    `${indent}superseded-by: ${successor.id} "${successor.heading ?? '?'}" (${successor.file})`
+    + ` [stage: ${successor.stage ?? 'unknown'}; time: ${successor.time.verdict}; jurisdictions: ${successor.applies.join(', ') || 'universal'}]`
+    + ' — verify applicability, preflight this target, and read its source before selecting an answer');
 }
 
 /**
@@ -1508,6 +1543,7 @@ function renderExclusions(payload, lines) {
   for (const x of payload.exclusions) {
     lines.push(`  ${x.id ? `${x.id}  ` : ''}${x.notation}  ${x.heading}  (${x.file})`);
     lines.push(`    ${x.reason}`);
+    lines.push(...renderSuccessors(x, '    '));
   }
   lines.push('');
 }
@@ -1659,7 +1695,7 @@ export function main(argv) {
     } else if (opts.paths) {
       payload = {
         mode: 'paths', 'time-check': timeCheck, 'store-health': health,
-        paths: resolvePaths(model, opts.paths, opts.root, opts.today),
+        paths: resolvePaths(model, opts.paths, opts.root, opts.today, opts.literalPaths),
       };
     } else {
       payload = {

package/payload/engine/commands/reverse-staged.js

@@ -0,0 +1,30 @@
+/** Informational attribution of the proposed commit and its prior governance. */
+import process from 'node:process';
+import { parseArgs as parseFlags, runCli } from '../lib/cli.js';
+import { EXIT_CODES } from '../lib/exit-codes.js';
+import { withCommitSnapshot } from '../lib/commit-snapshot.js';
+
+export const USAGE = 'usage: reverse-staged [--root <repo-root>]';
+
+/** @param {string[]} argv @returns {Promise<number>} */
+export async function main(argv) {
+  const { options } = parseFlags(argv, { value: ['root'] });
+  return withCommitSnapshot(options.root ?? process.cwd(), async ({ candidate, before, changedPaths }) => {
+    const paths = changedPaths();
+    if (!paths.length) return EXIT_CODES.CLEAN;
+    // Materialize both before publishing attribution. The installed runtime
+    // reads only immutable evidence within the shared cleanup lifetime.
+    const origins = [['candidate', candidate]];
+    if (before) origins.push(['before', before.materialize()]);
+    let outcome = EXIT_CODES.CLEAN;
+    for (const [origin, snapshot] of origins) {
+      process.stdout.write(`staged attribution: ${origin} ${snapshot.tree}\n`);
+      const status = await runCli('reverse-staged', async (args) => {
+        const { main: resolve } = await import('./resolve.js');
+        return resolve(args);
+      }, { usage: USAGE, argv: ['--root', snapshot.root, '--json', ...paths.map((path) => `--path=${path}`)] });
+      outcome = Math.max(outcome, status);
+    }
+    return outcome;
+  }, { skipUnchanged: true });
+}

package/payload/engine/commands/validate-values.js

@@ -61,8 +61,8 @@
  * 2 engine failure / check-never-ran.
  */
 import process from 'node:process';
-import { readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { healthSummary, loadStores, isPrePromotionStatus, normalizeConceptIds, selectConcepts, storeHealth, UnknownConceptsError } from '../lib/load-stores.js';
 import { locateKitRoot } from '../lib/kit-root.js';
@@ -116,11 +116,27 @@ function checkDescriptor(ctx, concept, descriptor, i) {
 
   let input;
   try {
+    // Governed evidence stays inside --root, including through symlinks.
+    // Check before reading so a failed structural pointer cannot still feed
+    // host bytes to the value validator during a snapshot check.
+    const target = resolve(ctx.root, descriptor.source);
+    const outside = (root, path) => {
+      const rel = relative(root, path);
+      return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+    };
+    if (outside(resolve(ctx.root), target)
+      || outside(realpathSync(ctx.root), realpathSync(target))) {
+      never('source-missing', `source ${JSON.stringify(descriptor.source)} resolves outside the repo root`);
+      return;
+    }
     input = readsDirectory
       ? listDirectory(join(ctx.root, descriptor.source))
       : readFileSync(join(ctx.root, descriptor.source), 'utf8');
   } catch (error) {
-    never('source-missing', `cannot ${readsDirectory ? 'list source directory' : 'read source'} ${JSON.stringify(descriptor.source)}: ${error.message}`);
+    // A filesystem message includes the absolute (possibly temporary) root.
+    // The declared source and stable error code identify the repair without
+    // making the same candidate emit different diagnostics on every run.
+    never('source-missing', `cannot ${readsDirectory ? 'list source directory' : 'read source'} ${JSON.stringify(descriptor.source)}: ${error.code ?? error.message}`);
     return;
   }
 

package/payload/engine/commands/validate.js

@@ -42,7 +42,7 @@
  *   missing-citation  a knowledge-leaf citation whose source is empty — an
  *                     unsourced claim is not promotable (§3.2); presence and
  *                     minItems are schema checks upstream
- *   ref-cycle         a decision supersedes chain that loops (§3.3 chains
+ *   ref-cycle         a decision or leaf supersedes chain that loops (§3.3 chains
  *                     must be acyclic; supersedes/superseded-by mirror pairs
  *                     are legitimate, so only supersedes edges are walked)
  *   unregistered-value  a governed facet value absent from its registry
@@ -1204,6 +1204,55 @@ function checkGraduations(model, push) {
   }
 }
 
+/**
+ * Tarjan components identify EVERY cyclic leaf, including overlapping cycles
+ * whose cross-edges a back-edge-only walk misses. Findings use the existing
+ * ref-cycle contract, attributed per leaf so isolated target preflight works.
+ */
+function checkLeafSupersessionCycles(model, push) {
+  const index = new Map();
+  const low = new Map();
+  const stack = [];
+  const active = new Set();
+  const targets = (id) => strings(model.leaves.get(id)?.record?.relates?.supersedes)
+    .filter((to) => model.leaves.has(to)).sort(compare);
+
+  const visit = (id) => {
+    index.set(id, index.size);
+    low.set(id, index.get(id));
+    stack.push(id);
+    active.add(id);
+    for (const to of targets(id)) {
+      if (!index.has(to)) {
+        visit(to);
+        low.set(id, Math.min(low.get(id), low.get(to)));
+      } else if (active.has(to)) {
+        low.set(id, Math.min(low.get(id), index.get(to)));
+      }
+    }
+    if (low.get(id) !== index.get(id)) return;
+    const members = [];
+    let member;
+    do {
+      member = stack.pop();
+      active.delete(member);
+      members.push(member);
+    } while (member !== id);
+    if (members.length === 1 && !targets(id).includes(id)) return;
+    members.sort(compare);
+    for (const cyclic of members) {
+      push({
+        severity: 'error', code: 'ref-cycle', id: cyclic,
+        file: model.leaves.get(cyclic).file, path: 'relates.supersedes',
+        message: `supersedes cycle includes: ${members.join(', ')} — leaf chains must be acyclic (UCS-1226)`,
+      });
+    }
+  };
+  for (const id of [...model.leaves.keys()].sort(compare)) {
+    if (!index.has(id)) visit(id);
+  }
+}
+
 function checkDecisionCycles(model, push) {
   const seen = new Set(); // canonical cycle keys — each loop reported once
   const color = new Map(); // 0/undefined = white, 1 = on stack, 2 = done
@@ -1264,6 +1313,7 @@ export function runChecks(model, repoRoot = model.root) {
   checkEditions(model, push);
   checkGraduations(model, push);
   checkDecisionCycles(model, push);
+  checkLeafSupersessionCycles(model, push);
   findings.sort((a, b) =>
     compare(a.file, b.file) || compare(a.path, b.path) || compare(a.code, b.code) || compare(a.id, b.id));
   return findings;

package/payload/engine/commit-check.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Load failures must report failure (2), never findings (1).
+try {
+  const [{ boot }, command] = await Promise.all([
+    import('./lib/boot.js'),
+    import('./commands/commit-check.js'),
+  ]);
+  process.exitCode = await boot('commit-check', command);
+} catch (error) {
+  process.stderr.write(`commit-check: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/engine/lib/commit-snapshot.js

@@ -0,0 +1,155 @@
+/** Raw Git objects as disposable evidence; never checkout filters or client code. */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import process from 'node:process';
+
+/**
+ * @typedef {{root: string, tree: string}} TreeSnapshot
+ * @typedef {{candidate: TreeSnapshot, before: null | {tree: string, materialize: () => TreeSnapshot}, changedPaths: () => string[]}} CommitSnapshot
+ *
+ * The callback owns no files. Candidate evidence and optional before evidence
+ * share this lifetime; immutable tree IDs pin provenance for later attribution.
+ * Before materialization is lazy: commit validation checks only the candidate.
+ * @param {string} repoRoot
+ * @param {(snapshot: CommitSnapshot) => Promise<number>} check
+ * @param {{skipUnchanged?: boolean}} [options] Attribution can skip an empty diff.
+ */
+export async function withCommitSnapshot(repoRoot, check, { skipUnchanged = false } = {}) {
+  const temporary = mkdtempSync(join(tmpdir(), 'unknown-knowledge-commit-'));
+  const env = { ...process.env, GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' };
+  const git = (args, { missing = false } = {}) => {
+    const result = spawnSync('git', ['-c', 'core.fsmonitor=false', '-C', repoRoot, ...args], { env, maxBuffer: 64 * 1024 * 1024 });
+    if (missing && result.status === 1) return null;
+    if (result.status !== 0) throw new Error(`snapshot: git ${args[0]} failed: ${result.error?.message ?? result.stderr.toString().trim()}`);
+    return result.stdout;
+  };
+  try {
+    repoRoot = realpathSync(repoRoot);
+    const top = git(['rev-parse', '--show-toplevel']).toString().replace(/\n$/, '');
+    if (realpathSync(top) !== repoRoot) {
+      throw new Error('snapshot: --root must be the Git repository root');
+    }
+    let beforeTree = null;
+    if (git(['rev-parse', '--verify', '--quiet', 'HEAD'], { missing: true })) {
+      beforeTree = git(['rev-parse', '--verify', 'HEAD^{tree}']).toString().trim();
+    } else {
+      // Only an absent branch is an unborn HEAD. A broken existing ref must
+      // never be interpreted as an empty before snapshot.
+      const ref = git(['symbolic-ref', 'HEAD']).toString().trim();
+      if (git(['show-ref', '--verify', '--quiet', ref], { missing: true }) !== null) {
+        throw new Error('snapshot: HEAD exists but its tree could not be read');
+      }
+    }
+    // write-tree may refresh index metadata: give it a private copy, including
+    // Git's alternate index during a path-limited commit.
+    const index = git(['rev-parse', '--git-path', 'index']).toString().replace(/\n$/, '');
+    const privateIndex = join(temporary, 'index');
+    try {
+      copyFileSync(resolve(repoRoot, index), privateIndex);
+    } catch (error) {
+      // A new repo may have no index yet. Git writes the empty tree from the
+      // absent private index; other missing/unreadable indexes still fail.
+      if (error.code !== 'ENOENT' || beforeTree !== null) throw error;
+    }
+    env.GIT_INDEX_FILE = privateIndex;
+    const tree = git(['write-tree']).toString().trim();
+    const candidate = { root: join(temporary, 'candidate'), tree };
+    let beforeSnapshot;
+    const before = beforeTree === null ? null : {
+      tree: beforeTree,
+      materialize: () => {
+        if (!beforeSnapshot) {
+          const root = join(temporary, 'before');
+          materializeTree(root, beforeTree, git);
+          beforeSnapshot = { root, tree: beforeTree };
+        }
+        return beforeSnapshot;
+      },
+    };
+    let pathsCache;
+    const changedPaths = () => {
+      if (pathsCache) return pathsCache;
+      const base = beforeTree ?? git(['hash-object', '-w', '-t', 'tree', '--stdin']).toString().trim();
+      // Pin similarity and exhaustive-search limits: host diff.renameLimit
+      // must not change the path set for the same immutable trees.
+      const bytes = git(['diff-tree', '--no-commit-id', '--name-status', '-r', '-z', '--no-ext-diff', '--no-textconv', '--find-renames=50%', '--find-copies=50%', '--find-copies-harder', '-l1000', base, tree, '--']);
+      const text = bytes.toString();
+      if (!Buffer.from(text).equals(bytes)) throw new Error('snapshot: non-UTF-8 changed paths cannot be attributed faithfully');
+      if (text && !text.endsWith('\0')) throw new Error('snapshot: incomplete Git change records');
+      const records = text ? text.slice(0, -1).split('\0') : [];
+      const paths = [];
+      for (let i = 0; i < records.length;) {
+        const status = records[i++];
+        if (!/^(?:[ADMT]|[RC]\d+)$/.test(status)) throw new Error(`snapshot: unsupported Git change status ${JSON.stringify(status)}`);
+        const count = /^[RC]/.test(status) ? 2 : 1;
+        for (let n = 0; n < count; n += 1) {
+          const path = records[i++];
+          if (!path) throw new Error('snapshot: incomplete Git change records');
+          paths.push(path);
+        }
+      }
+      pathsCache = [...new Set(paths)];
+      return pathsCache;
+    };
+    if (skipUnchanged && changedPaths().length === 0) return 0;
+    materializeTree(candidate.root, tree, git);
+    return await check({ candidate, before, changedPaths });
+  } finally {
+    try {
+      rmSync(temporary, { recursive: true, force: true, maxRetries: 3 });
+    } catch (error) {
+      throw new Error(`snapshot cleanup failed at ${JSON.stringify(temporary)}: ${error.message}`, { cause: error });
+    }
+  }
+}
+
+function materializeTree(snapshotRoot, tree, git) {
+  mkdirSync(snapshotRoot);
+  const listing = git(['ls-tree', '-rz', '--full-tree', tree]);
+  const text = listing.toString();
+  if (!Buffer.from(text).equals(listing)) throw new Error('snapshot: non-UTF-8 Git paths cannot be materialized faithfully');
+  const entries = text.split('\0').filter(Boolean);
+  const links = [];
+  for (const entry of entries) {
+    const [header, path] = [entry.slice(0, entry.indexOf('\t')), entry.slice(entry.indexOf('\t') + 1)];
+    const [mode, type, object] = header.split(' ');
+    if (type !== 'blob' || !['100644', '100755', '120000'].includes(mode)) {
+      throw new Error(`snapshot: unsupported Git entry ${JSON.stringify(path)} (${mode})`);
+    }
+    const target = resolve(snapshotRoot, path);
+    if (outside(snapshotRoot, target) || target === snapshotRoot) throw new Error('snapshot: Git path escapes its root');
+    mkdirSync(dirname(target), { recursive: true });
+    const bytes = git(['cat-file', 'blob', object]);
+    if (mode === '120000') {
+      const link = bytes.toString();
+      if (!Buffer.from(link).equals(bytes)) {
+        throw new Error(`snapshot: non-UTF-8 symlink target at ${JSON.stringify(path)} cannot be materialized faithfully`);
+      }
+      if (isAbsolute(link) || outside(snapshotRoot, resolve(dirname(target), link))) {
+        throw new Error(`snapshot: symlink ${JSON.stringify(path)} points outside the candidate`);
+      }
+      links.push({ link, target });
+    } else {
+      writeFileSync(target, bytes, { mode: Number.parseInt(mode, 8), flag: 'wx' });
+    }
+  }
+  for (const { link, target } of links) symlinkSync(link, target);
+  // Check complete link chains before either validator can read a store.
+  for (const entry of entries.filter((entry) => entry.startsWith('120000 '))) {
+    const path = entry.slice(entry.indexOf('\t') + 1);
+    try {
+      if (outside(realpathSync(snapshotRoot), realpathSync(join(snapshotRoot, path)))) {
+        throw new Error(`snapshot: symlink ${JSON.stringify(path)} resolves outside the candidate`);
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error; // dangling evidence remains missing
+    }
+  }
+}
+
+function outside(root, target) {
+  const path = relative(root, target);
+  return path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path);
+}

package/payload/engine/lib/coverage.js

@@ -842,6 +842,7 @@ function gatherRollup(joined) {
         ? `declares applies.jurisdictions [${leaf.applies.join(', ')}] — the document is scoped to [${scopes.join(', ')}], which this leaf does not cover; verify applicability (UCS-1156)`
         : null,
       demotions: leaf.demotions,
+      'superseded-by': leaf['superseded-by'],
     });
   }
   return rollup.sort((a, b) =>

package/payload/engine/lib/kit-root.js

@@ -22,7 +22,8 @@
  *
  * Both repos look identical from here. Picking either silently reads one Store
  * and ignores the other — a confident wrong answer, which is the failure class
- * this engine exists to prevent. So an ambiguous layout REFUSES: every surface
+ * this engine exists to prevent. An explicit .unknown-knowledge.json selection settles this choice across all surfaces.
+ * Without that selection, an ambiguous layout REFUSES: every surface
  * fails identically (exit 2) and names both candidates, rather than four
  * surfaces agreeing on one Store while the audit quietly reads the other.
  *
@@ -33,13 +34,16 @@
  * Stores absent entirely is not an error: the loader reports missing-store
  * warnings and the audit proposes every anchor.
  */
-import { statSync } from 'node:fs';
+import { statSync, lstatSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { EngineRefusal } from './engine-refusal.js';
 
 /** The §9.1/D-016 seeded kit directory name. Renames are a later seam. */
 export const KIT_DIR_DEFAULT = 'unknown-knowledge';
 
+/** Versioned selection for repositories containing both supported layouts. */
+export const KIT_LAYOUT_FILE = '.unknown-knowledge.json';
+
 /** The human-confirmed survey boundary (§6), written at the kit root. */
 export const SCOPE_FILE = 'survey-scope.yaml';
 
@@ -83,13 +87,31 @@ export class AmbiguousKitLayout extends EngineRefusal {
  *   both exist, so no surface can know which Store is authoritative
  */
 export function locateKit(root) {
+  const selection = join(root, KIT_LAYOUT_FILE);
+  const selectionStat = lstatSync(selection, { throwIfNoEntry: false });
+  if (selectionStat) {
+    if (!selectionStat.isFile()) throw new AmbiguousKitLayout(`${KIT_LAYOUT_FILE} must be a regular JSON file`);
+    let config;
+    try {
+      config = JSON.parse(readFileSync(selection, 'utf8'));
+    } catch (error) {
+      throw new AmbiguousKitLayout(`${KIT_LAYOUT_FILE} could not be read as JSON: ${error.message}`, { cause: error });
+    }
+    if (!config || Array.isArray(config) || Object.keys(config).length !== 1
+      || !['.', KIT_DIR_DEFAULT].includes(config.kitRoot)) {
+      throw new AmbiguousKitLayout(`${KIT_LAYOUT_FILE} must contain only "kitRoot", set to "." or "${KIT_DIR_DEFAULT}"`);
+    }
+    const kitRoot = join(root, config.kitRoot);
+    if (!isDir(kitRoot)) throw new AmbiguousKitLayout(`${KIT_LAYOUT_FILE} selects a missing kit directory`);
+    return { kitRoot, kitPrefixes: [...(config.kitRoot === '.' ? KIT_ZONE_AT_ROOT : [KIT_DIR_DEFAULT]), KIT_LAYOUT_FILE] };
+  }
   const nested = join(root, KIT_DIR_DEFAULT);
   if (isDir(nested)) {
     if (looksLikeStoreRoot(root)) {
       throw new AmbiguousKitLayout(
         `two candidate kit roots under ${JSON.stringify(root)}: the seeded ${KIT_DIR_DEFAULT}/ and stores at the root itself. `
         + 'Which one is authoritative is not knowable from here, and guessing would let the reverse audit read a different '
-        + 'store than the validators (PRD §4, single health model). Point --root at the intended kit root, or remove the stale one.',
+        + 'store than the validators (PRD §4, single health model). Select the authoritative layout with .unknown-knowledge.json (kitRoot: "." or "unknown-knowledge"), or remove the stale one. Keep --root at the repository root.',
       );
     }
     return { kitRoot: nested, kitPrefixes: [KIT_DIR_DEFAULT] };