unknown-knowledge 2.1.0 → 3.0.0-rc.1

package/payload/engine/lib/load-stores.js

@@ -68,6 +68,8 @@
  *                               // from either end: resolving a concept surfaces
  *                               // its declaring leaves structurally, with no
  *                               // dependence on whether any term text matches
+ *     supersedingLeaves: Map leaf id -> [direct successor identities],
+ *                               // derived from relates.supersedes; never stored
  *     refs:      [{ from, type, to, file, path, resolved }], // cross-ref graph
  *     diagnostics: [{ severity, code, file, path, message }],
  *     ok,                       // true iff no error-severity diagnostic
@@ -1333,6 +1335,17 @@ function buildLeavesByConcept(ctx) {
   return sortedMap(index);
 }
 
+/** Disposable inverse of the authoritative leaf supersedes edges, one hop. */
+function buildSupersedingLeaves(ctx) {
+  const index = new Map();
+  for (const ref of ctx.refs) {
+    if (ref.type !== 'relates.supersedes' || !ctx.leaves.has(ref.from) || !ctx.leaves.has(ref.to)) continue;
+    if (!index.has(ref.to)) index.set(ref.to, new Set());
+    index.get(ref.to).add(ref.from);
+  }
+  return sortedMap(new Map([...index].map(([id, successors]) => [id, [...successors].sort(compare)])));
+}
+
 /** Resolve every collected edge; a miss is an unresolved-ref error. */
 function resolveRefs(ctx) {
   for (const ref of ctx.refs) {
@@ -1422,6 +1435,7 @@ export function loadStores(root) {
     phoenix: sortedMap(ctx.phoenix),
     pointers,
     leavesByConcept,
+    supersedingLeaves: buildSupersedingLeaves(ctx),
     refs: ctx.refs,
     diagnostics: ctx.diagnostics,
     ok: ctx.diagnostics.every((d) => d.severity !== 'error'),

package/payload/engine/lib/preflight.js

@@ -0,0 +1,122 @@
+/**
+ * Preflight orchestration (UCS-953): compute fresh Verdicts, assemble the
+ * command result, and optionally append quarantine findings. Verdict rules
+ * stay in verdicts.js; this layer owns counts, the numeric exit contract,
+ * and logging. It never renders or writes to stdout/stderr.
+ */
+import { healthSummary } from './load-stores.js';
+import { computeVerdicts } from './verdicts.js';
+import { EXIT_CODES } from './exit-codes.js';
+import { compare } from './validate-record.js';
+import { createEntry } from './log-entry.js';
+import { timeCheckStatus } from './time-verdicts.js';
+
+/** finding.schema.json conceptRef — `consulted` only carries conforming ids. */
+const CONCEPT_REF = /^K-[0-9]+$/;
+
+// -------------------------------------------- quarantine findings (KK-13)
+
+/**
+ * Append one engine-attributed quarantine finding per quarantined concept
+ * (capture content policy §3.4: concept ids, codes, and paths only).
+ * Returns the root-relative fragment paths, sorted.
+ */
+function logQuarantines(root, verdicts, today) {
+  const logged = [];
+  for (const v of verdicts) {
+    if (v.verdict !== 'quarantined') continue;
+    const codes = [...new Set(v.evidence.map((e) => e.code))].sort(compare);
+    const paths = [...new Set(v.evidence.flatMap((e) => [e.file, e.source]).filter(Boolean))].sort(compare);
+    const { file } = createEntry({
+      root, log: 'findings', date: today,
+      fields: {
+        trigger: 'quarantine',
+        session: 'engine/preflight.js',
+        summary: `preflight quarantined ${v.concept}: ${codes.join(', ')} (${paths.join(', ')})`,
+        ...(CONCEPT_REF.test(v.concept) ? { consulted: { concepts: [v.concept] } } : {}),
+      },
+    });
+    logged.push(file);
+  }
+  return logged.sort(compare);
+}
+
+/**
+ * @param {object} model freshly loaded Store
+ * @param {object} options
+ * @param {string} options.repoRoot repo root for source pointers
+ * @param {string[] | null} [options.concepts] normalized concept ids
+ * @param {string[] | null} [options.leaves] normalized leaf accession ids
+ * @param {string | null} [options.today] injected calendar date
+ * @param {boolean} [options.log] append quarantine findings (requires today)
+ * @returns {{ payload: object, exitCode: number }}
+ * @throws when computation or logging cannot complete; a partial logged run
+ * may already have appended findings. Let the CLI guard report incompletion.
+ */
+export function runPreflight(model, { repoRoot, concepts = null, leaves = null, today = null, log = false }) {
+  // Verdict computation owns the store-wide degradation decision; the
+  // orchestration projects the returned health into the existing wire shape.
+  const { health: fullHealth, storeVerdict, verdicts, leafVerdicts } = computeVerdicts(model, {
+    concepts, leaves, repoRoot, today,
+  });
+  const health = healthSummary(fullHealth);
+  const storeErrors = fullHealth.errors
+    .map(({ code, file, path, message }) => ({ code, file, path, message }));
+
+  // Empty/omitted --concepts AND --leaves: store-health-only — exit on the
+  // store verdict alone (§7); no per-record check runs, so no per-record
+  // verdict exists. Either flag alone selects that flag's records; both
+  // select both, because "which concepts" and "which leaves" are two
+  // questions and a run may legitimately ask one, the other, or both.
+  const wantConcepts = !!concepts && concepts.length > 0;
+  const wantLeaves = !!leaves && leaves.length > 0;
+  const storeHealthOnly = !wantConcepts && !wantLeaves;
+
+  // Counted TOGETHER, over both verdict lists. Splitting the counts would let
+  // a run exit 0 on clean concepts while a requested leaf was quarantined —
+  // the gate reading as clean about the half of the question it liked.
+  const all = [...verdicts, ...leafVerdicts];
+  const counts = {
+    trusted: all.filter((v) => v.verdict === 'trusted').length,
+    quarantined: all.filter((v) => v.verdict === 'quarantined').length,
+    unknown: all.filter((v) => v.verdict === 'unknown').length,
+    // Counted separately (UCS-1150) so a stale leaf is visible in the tally
+    // rather than absorbed into a class that means something else. `ok`
+    // below still requires trusted === all.length, so a stale leaf gates.
+    stale: all.filter((v) => v.verdict === 'stale').length,
+  };
+  const logged = log ? logQuarantines(model.root, verdicts, today) : null;
+
+  const ok = storeHealthOnly
+    ? storeVerdict === 'trusted'
+    : storeVerdict === 'trusted' && counts.trusted === all.length;
+  const payload = {
+    ok,
+    // The mode names what was ASKED. `leaves` and `concepts+leaves` are new
+    // (UCS-1149); a run that named only concepts reads exactly as it did
+    // before, so no existing consumer sees a shape it did not ask for.
+    mode: storeHealthOnly
+      ? 'store-health'
+      : [wantConcepts ? 'concepts' : null, wantLeaves ? 'leaves' : null].filter(Boolean).join('+'),
+    'store-verdict': storeVerdict,
+    'store-health': health,
+    ...(storeErrors.length ? { 'store-errors': storeErrors } : {}),
+    counts,
+    verdicts,
+    // Present only when leaves were asked about, for the same reason `mode`
+    // still says `concepts`: a --concepts-only run's JSON is unchanged.
+    // `time-check` rides the same condition — leaves are the only records the
+    // time facet governs, so a concepts-only run has no time check to report
+    // and inventing one would answer a question nobody asked. When leaves
+    // ARE asked about, it is always present: a run that computed no freshness
+    // verdicts must never look like one that checked and found them fresh.
+    ...(wantLeaves ? { 'time-check': timeCheckStatus(today), 'leaf-verdicts': leafVerdicts } : {}),
+    ...(logged ? { logged } : {}),
+  };
+  // Unknown includes store-wide failure and skipped checks. Stale and
+  // quarantined are completed findings; only checked success exits cleanly.
+  const exitCode = storeVerdict !== 'trusted' || counts.unknown > 0
+    ? EXIT_CODES.FAILURE
+    : counts.quarantined > 0 || counts.stale > 0 ? EXIT_CODES.FINDINGS : EXIT_CODES.CLEAN;
+  return { payload, exitCode };
+}

package/payload/engine/lib/time-verdicts.js

@@ -231,7 +231,7 @@ export function timeVerdict(record, today) {
     return {
       ...base,
       verdict: TIME_VERDICTS.SKIPPED,
-      reason: 'skipped — pass --today YYYY-MM-DD to enable time verdicts; diffable output never reads the wall clock (D-012)',
+      reason: timeCheckStatus(null),
     };
   }
   if (verified === null) {
@@ -252,7 +252,7 @@ export function timeVerdict(record, today) {
       age,
       verdict: TIME_VERDICTS.STALE,
       stale: true,
-      reason: `verified ${age} day(s) ago, past the ${limit}-day limit for ${volatility} knowledge — re-verify against the cited sources, or treat the claim as unverified (UCS-1150)`,
+      reason: `verified ${age} day(s) ago, past the ${limit}-day limit for ${volatility} knowledge (UCS-1150)`,
     };
   }
   // Only `stable` and `volatile` reach here — `static` returned above and
@@ -270,13 +270,12 @@ export function timeVerdict(record, today) {
  *
  * Every projection that can demote on time must SAY whether it computed
  * verdicts, and it must say so in one wording — a surface that phrased its own
- * skip notice would eventually phrase it as silence. Mirrors the audit's
- * `checks['stale-last-verified']` string exactly, so a reader who has seen one
- * recognizes the other.
+ * skip notice would eventually phrase it as silence. Reports the missing
+ * input as a fact; recovery wording belongs to the protocol (D-011).
  *
  * @param {string|null} today the injected date, or null
  * @returns {string}
  */
 export const timeCheckStatus = (today) => (today
   ? `checked against --today ${today} (stale after ${VOLATILITY_LIMITS.stable} days for stable, ${VOLATILITY_LIMITS.volatile} for volatile; static never stales)`
-  : 'skipped — pass --today YYYY-MM-DD to enable; diffable output never reads the wall clock (D-012)');
+  : 'skipped — no evaluation date supplied; diffable output never reads the wall clock (D-012)');

package/payload/engine/lib/verdicts.js

@@ -0,0 +1,260 @@
+/**
+ * Deterministic Verdict computation (UCS-947, D-011).
+ *
+ * Joins the validators to a freshly loaded Store. The library owns the
+ * store-wide degradation decision for both concepts and leaves, including
+ * their promotion and time rules. No results are cached and no logs are
+ * written; callers retain rendering, logging, and exit-code handling.
+ */
+import { isPrePromotionStatus, leafIdentityOf, leafStage, selectConcepts, selectLeaves, storeHealth } from './load-stores.js';
+import { compare } from './validate-record.js';
+import { runChecks } from '../commands/validate.js';
+import { validateValues } from '../commands/validate-values.js';
+import { TIME_VERDICTS, timeVerdict } from './time-verdicts.js';
+
+/**
+ * Compute requested Verdicts using the loader's single health model.
+ * Empty or omitted selections request store health only, never all records.
+ * On an unhealthy Store every requested id degrades to unknown, including
+ * ids that could not load. Healthy Stores reject unknown ids through the
+ * loader's selectors. Dates are injected; the wall clock is never read.
+ *
+ * @param {object} model freshly loaded Store; reload after Store edits
+ * @param {object} options
+ * @param {string} options.repoRoot repo root used to resolve source pointers
+ * @param {string[] | null} [options.concepts] normalized concept ids
+ * @param {string[] | null} [options.leaves] normalized leaf accession ids
+ * @param {string | null} [options.today] injected ISO calendar date
+ * @returns {{ health: ReturnType<typeof storeHealth>, storeVerdict: string, verdicts: object[], leafVerdicts: object[] }}
+ */
+export function computeVerdicts(model, { repoRoot, concepts = null, leaves = null, today = null }) {
+  const health = storeHealth(model);
+  const verdicts = concepts?.length
+    ? (health.ok ? computeConceptVerdicts(model, concepts, repoRoot) : degradeAll(model, concepts, health.errorCount))
+    : [];
+  const leafVerdicts = leaves?.length
+    ? (health.ok ? computeLeafVerdicts(model, leaves, repoRoot, today) : degradeAllLeaves(model, leaves, today, health.errorCount))
+    : [];
+  return { health, storeVerdict: health.ok ? 'trusted' : 'unknown', verdicts, leafVerdicts };
+}
+
+/**
+ * Stable next-action codes, shared by JSON and human output (UCS-954).
+ * Conduct is keyed by these codes in protocol/AGENTS.md, never rendered here.
+ * Changing a code is a breaking CLI contract change (D-021).
+ */
+const NEXT_ACTIONS = Object.freeze({
+  trusted: 'proceed',
+  quarantined: 'repair-evidence',
+  'unknown-status': 'review-status',
+  'unknown-stage': 'review-stage',
+  'unknown-store': 'repair-store',
+  // The Time facet (UCS-1150). A stale leaf is not broken and its checks did
+  // run — the action is re-verification against the sources, which is a
+  // steward's job rather than a repair.
+  stale: 'reverify-leaf',
+  // A leaf that asked to be governed by time and gave nothing to measure from.
+  // Its verdict can only ever be `undated`, so the fix is the missing field.
+  'unknown-undated': 'supply-verified-date',
+  // No --today was injected, so no freshness verdict was computed at all.
+  'unknown-skipped': 'supply-evaluation-date',
+});
+
+// ---------------------------------------------------------- verdict joining
+
+/**
+ * Join both validators' results to the requested concepts — one verdict per
+ * concept. Only called on a healthy store (the store-wide degradation path
+ * never reaches the validators: their checks would not have run).
+ */
+function computeConceptVerdicts(model, ids, repoRoot) {
+  const structural = runChecks(model, repoRoot);
+  const values = validateValues(model, null, repoRoot); // full run; attribution below
+
+  return selectConcepts(model, ids).map(({ id, record }) => {
+    const status = record.status ?? null;
+    // Evidence: error-severity findings from either validator, plus value
+    // hard errors (unknown-kind, source-missing, …) — all attributable to
+    // this concept, all reasons not to trust it (quarantine, per §4).
+    const evidence = [
+      ...structural
+        .filter((f) => f.id === id && f.severity === 'error')
+        .map(({ code, file, path, message }) => ({ check: 'structural', code, severity: 'error', file, path, message })),
+      ...values.findings
+        .filter((f) => f.concept === id && f.severity === 'error')
+        .map(({ code, file, path, source, value, message }) => ({ check: 'value', code, severity: 'error', file, path, ...(source ? { source } : {}), ...(value !== undefined ? { value } : {}), message })),
+      ...values.hardErrors
+        .filter((e) => e.concept === id)
+        .map(({ code, file, path, source, message }) => ({ check: 'value', code, severity: 'hard-error', file, path, ...(source ? { source } : {}), message })),
+    ].sort((a, b) => compare(a.check, b.check) || compare(a.path ?? '', b.path ?? '')
+      || compare(a.code, b.code) || compare(a.value ?? '', b.value ?? ''));
+
+    if (evidence.length) {
+      return {
+        concept: id, status, verdict: 'quarantined',
+        reason: `${evidence.length} error-severity check result(s) attributable to this concept — see evidence`,
+        'next-action': NEXT_ACTIONS.quarantined,
+        evidence,
+      };
+    }
+    if (isPrePromotionStatus(status)) {
+      return {
+        concept: id, status, verdict: 'unknown',
+        reason: `status "${status}" — structural checks only (§3.5); the value checks were skipped, so nothing certifies the claims`,
+        'next-action': NEXT_ACTIONS['unknown-status'],
+        evidence,
+      };
+    }
+    return {
+      concept: id, status, verdict: 'trusted',
+      reason: 'every attributable check ran clean this run',
+      'next-action': NEXT_ACTIONS.trusted,
+      evidence,
+    };
+  }).sort((a, b) => compare(a.concept, b.concept));
+}
+
+/**
+ * Leaf verdicts (UCS-1149) — the same three verdicts, computed for leaves.
+ *
+ * A leaf earns a verdict on the same two questions a concept does, asked of the
+ * evidence a leaf actually has:
+ *
+ *   quarantined  error-severity structural findings attributable to this leaf —
+ *                an unminted facet value, a citation with no authority tier, a
+ *                cross-reference that does not resolve. There is no value-check
+ *                half: value checks diff a descriptor against source code, and
+ *                a leaf carries no descriptor. Its evidence is structural only,
+ *                which is stated rather than silently implied by an empty list.
+ *   unknown      `facets.stage` is missing or pre-promotion — the SAME predicate the
+ *                concept path calls, so a draft leaf and a draft concept cannot
+ *                be verdicted differently by two surfaces that both think they
+ *                are asking one question. This is preflight's half of the
+ *                draft-stage contract; the resolver's half is the downrank.
+ *   trusted      neither.
+ *
+ * Attribution is by the finding's `id`, which for a leaf is its identity — its
+ * accession (UCS-1142/1147) — so a leaf is matched by the same string the
+ * validator names it by, not by a second guess at its id space.
+ */
+function computeLeafVerdicts(model, ids, repoRoot, today) {
+  const structural = runChecks(model, repoRoot);
+
+  return selectLeaves(model, ids).map((entry) => {
+    const id = entry.identity;
+    const stage = leafStage(entry.record);
+    const time = timeVerdict(entry.record, today);
+    const base = { leaf: id, stage, time };
+    const evidence = structural
+      .filter((f) => f.id === id && f.severity === 'error')
+      .map(({ code, file, path, message }) => ({ check: 'structural', code, severity: 'error', file, path, message }))
+      .sort((a, b) => compare(a.path ?? '', b.path ?? '') || compare(a.code, b.code));
+
+    if (evidence.length) {
+      return {
+        ...base, verdict: 'quarantined',
+        reason: `${evidence.length} error-severity check result(s) attributable to this leaf — see evidence`,
+        'next-action': NEXT_ACTIONS.quarantined,
+        evidence,
+      };
+    }
+    if (stage === null || isPrePromotionStatus(stage)) {
+      return {
+        ...base, verdict: 'unknown',
+        reason: stage === null
+          ? 'missing review stage (facets.stage) — this leaf has no declared promotion state'
+          : `stage "${stage}" — this leaf is pre-promotion; its declared stage does not establish reviewed evidence`,
+        'next-action': NEXT_ACTIONS['unknown-stage'],
+        evidence,
+      };
+    }
+    // The Time facet (UCS-1150). Asked AFTER stage, because a leaf that no
+    // moderator has promoted is unverified for a reason that outranks its age:
+    // re-dating a draft would not make it trusted. A promoted leaf, though, is
+    // exactly the one whose freshness is the remaining question.
+    //
+    // `stale` is its OWN verdict class rather than a mapping onto `unknown` or
+    // `quarantined`, and the choice is the ticket's ("trusted/stale verdicts").
+    // The existing three each mean something a stale leaf is not: nothing about
+    // it is broken (quarantined), and its checks did run and returned a
+    // definite answer (unknown). Folding it into either would tell a steward to
+    // do the wrong thing — repair evidence that is fine, or pass a flag they
+    // already passed — and would make the leaf-verdicts surface dishonest about
+    // what it computed. It gates like the others: only trusted reads as clean.
+    if (time.stale) {
+      return {
+        ...base, verdict: 'stale',
+        reason: time.reason,
+        'next-action': NEXT_ACTIONS.stale,
+        evidence,
+      };
+    }
+    // A leaf under time governance whose freshness could not be computed is
+    // NOT trusted. Two ways that happens, and they need different actions: the
+    // leaf is missing its date (`undated`), or this run never injected one
+    // (`skipped`). Both are unknown-class — a check that never ran is never a
+    // silent pass — and each says which fix applies.
+    if (time.verdict === TIME_VERDICTS.UNDATED || time.verdict === TIME_VERDICTS.SKIPPED) {
+      return {
+        ...base, verdict: 'unknown',
+        reason: time.reason,
+        'next-action': NEXT_ACTIONS[`unknown-${time.verdict}`],
+        evidence,
+      };
+    }
+    return {
+      ...base, verdict: 'trusted',
+      reason: 'every attributable check ran clean this run',
+      'next-action': NEXT_ACTIONS.trusted,
+      evidence,
+    };
+  }).sort((a, b) => compare(a.leaf, b.leaf));
+}
+
+/**
+ * Store-wide failure: no check ran — every requested LEAF verdict is unknown.
+ *
+ * Ids are resolved through `leafIdentityOf`, the same lookup the healthy path's
+ * `selectLeaves` uses, so a leaf that IS in the store reports under its own
+ * identity whether the store loaded clean or not. An id that resolves to
+ * nothing keys on the caller's spelling instead — see below.
+ */
+function degradeAllLeaves(model, ids, today, errors) {
+  // De-duplicated by IDENTITY, like selectLeaves: naming one leaf twice is one
+  // leaf, and emitting two verdict rows for it would have a caller reconciling
+  // two answers about a single record. An
+  // id that resolves to nothing keys on the caller's spelling instead — on a
+  // store this broken the leaf may simply have failed to load, so echoing back
+  // what was asked for is more honest than inventing an identity, and two
+  // distinct unresolved ids stay two rows.
+  const seen = new Set();
+  const out = [];
+  for (const id of ids) {
+    const identity = leafIdentityOf(model, id) ?? id;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    const record = model.leaves.get(identity)?.record;
+    out.push({
+      leaf: identity, stage: leafStage(record),
+      // The time verdict travels on the degraded path too, computed from
+      // whatever loaded. A key that vanished on a broken store would make a
+      // consumer's presence check mean two things at once.
+      time: timeVerdict(record, today),
+      verdict: 'unknown',
+      reason: `store-wide failure: the loader reported ${errors} error(s) — no check ran for any leaf (single health model, PRD §4)`,
+      'next-action': NEXT_ACTIONS['unknown-store'],
+      evidence: [],
+    });
+  }
+  return out.sort((a, b) => compare(a.leaf, b.leaf));
+}
+
+/** Store-wide failure: no check ran — every requested verdict is unknown. */
+function degradeAll(model, ids, errors) {
+  return ids.map((id) => ({
+    concept: id, status: model.concepts.get(id)?.record.status ?? null, verdict: 'unknown',
+    reason: `store-wide failure: the loader reported ${errors} error(s) — no check ran for any concept (single health model, PRD §4)`,
+    'next-action': NEXT_ACTIONS['unknown-store'],
+    evidence: [],
+  })).sort((a, b) => compare(a.concept, b.concept));
+}

package/payload/engine/reverse-staged.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/reverse-staged.js'),
+  ]);
+  process.exitCode = await boot('reverse-staged', command);
+} catch (error) {
+  process.stderr.write(`reverse-staged: internal failure — the engine could not be loaded\n${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+}

package/payload/hooks/pre-commit

@@ -8,11 +8,8 @@
 # Protocol compliance is a property of the mechanism, not of agent
 # obedience: the same validator CI runs, run before the commit exists.
 #
-# Not a test seam. The tested surface is the wrapped command
-# (`engine/validate.js`, tests/validate.test.js); testing it IS testing
-# this hook, because this file adds nothing to test. Wiring is reviewed
-# the way the per-IDE wrappers are — read it once, confirm it is a
-# pointer, and trust the command it points at.
+# Installed-hook behavior is exercised with real Git commits in
+# tests/commit-gate.test.js; command tests alone do not prove the wiring.
 #
 # Wire it (the client's own git config — the kit never writes .git/):
 #   ln -s ../../unknown-knowledge/hooks/pre-commit .git/hooks/pre-commit
@@ -20,11 +17,14 @@
 # opts in: seeding a hook is not installing one.
 #
 # Exit codes are the engine's, propagated verbatim (PRD §5):
-#   0 — the store is structurally sound; the commit proceeds.
+#   0 — both whole-store validators are clean; the commit proceeds.
 #   1 — the check ran and found something; the commit is refused.
 #   2 — the check never ran; the commit is refused. A check that never
 #       ran is a blocking defect, never a silent pass.
 #
+# Both validators read one isolated Git index snapshot. Unstaged and untracked
+# evidence cannot affect the result; preparation or cleanup failure exits 2.
+#
 # KIT_DIR names the seeded root when it is not the default; UK_ROOT names
 # the repo root when the hook runs from elsewhere. Both are location
 # arguments, never gate arguments — neither can turn the check off.
@@ -33,5 +33,5 @@ set -u
 KIT_DIR="${KIT_DIR:-unknown-knowledge}"
 UK_ROOT="${UK_ROOT:-.}"
 
-node "$UK_ROOT/$KIT_DIR/engine/validate.js" --root "$UK_ROOT"
+node "$UK_ROOT/$KIT_DIR/engine/commit-check.js" --root "$UK_ROOT"
 exit $?

package/payload/hooks/reverse-lookup

@@ -1,66 +1,12 @@
 #!/bin/sh
-# unknown-knowledge reverse-lookup hook — automatic attribution (UCS-1157).
-#
-# THIN BY CONSTRUCTION, exactly like the pre-commit hook: it collects the
-# touched paths git already knows about and hands them to one engine
-# command, exiting with that command's code, unchanged. It reads no leaf,
-# joins nothing, and decides nothing — `engine/resolve.js --paths` is what
-# answers "which leaves and concepts govern this file", and the answer is
-# its output, not this script's.
-#
-# This is the AGENTS.md ACT step (attribute before committing) made
-# automatic. An agent can forget to run the reverse lookup; a hook cannot.
-# That is the whole point: the protocol rides along invisibly rather than
-# depending on anyone remembering it.
-#
-# Not a test seam. The tested surface is the wrapped command
-# (`engine/resolve.js --paths`, tests/resolve.test.js and
-# tests/typed-edges.test.js) — this file adds no behavior to test, and the
-# wiring is reviewed like the per-IDE wrappers.
-#
-# Wire it with an EVENT-NAMED symlink — git runs a hook only if its
-# filename is one of the events git fires, and `reverse-lookup` is not one
-# of them. That matters most under `core.hooksPath` pointed at the seeded
-# directory: git looks there for event names only, so this file would sit
-# next to `pre-commit` and never fire. Give it an event:
-#
-#   ln -s ../../unknown-knowledge/hooks/reverse-lookup .git/hooks/prepare-commit-msg
-#
-# (`prepare-commit-msg` runs after the index is staged and before the
-# message editor opens, which is when attribution is still actionable. Git
-# passes it the message file and source as arguments; this script ignores
-# them and reads the staged diff itself.) Under `core.hooksPath` wiring,
-# call it explicitly from your `pre-commit` instead. Either way, wiring it
-# into git is the client's own act — the seeded artifact is the script.
-#
-# Exit codes are the engine's, propagated verbatim (PRD §5):
-#   0 — the lookup ran (including a zero-hit lookup, which is a real
-#       answer: nothing in the store governs these files).
-#   2 — the lookup never ran.
-# `resolve.js` never exits 1: reporting what governs a path is not a
-# finding, and this hook is attribution, never a gate. What it prints is
-# what the ACT step obliges you to act on.
-#
-# With no staged changes there is nothing to attribute, so the hook exits
-# 0 without invoking the engine — `--paths` with an empty list is a usage
-# error (exit 2), and an empty diff is not a failure.
-#
-# git's own status is checked BEFORE the join. In a pipeline the shell
-# reports the LAST command's status, so `git diff | paste` would report
-# paste's success even when git failed — leaving PATHS empty and the hook
-# exiting 0 on a lookup that never ran. That is the silent pass this whole
-# design refuses, so the two steps are separate and git's code is read.
+# Advisory attribution, including prior governance of deletions and renames.
+# Install explicitly as .git/hooks/prepare-commit-msg (an event Git runs).
+# The versioned engine owns Git parsing, isolated snapshots and resolution;
+# actual installed-hook commit tests exercise that behavior end to end.
+# Exit 0: attributed, or no staged changes. Exit 2: attribution failed.
+# Attribution never narrows either whole-store validator or proves a store edit.
 set -u
-
 KIT_DIR="${KIT_DIR:-unknown-knowledge}"
 UK_ROOT="${UK_ROOT:-.}"
-
-STAGED=$(git diff --cached --name-only --diff-filter=ACMR) || {
-  echo "reverse-lookup: git diff failed — the staged paths could not be read, so the lookup never ran" >&2
-  exit 2
-}
-[ -z "$STAGED" ] && exit 0
-PATHS=$(printf '%s' "$STAGED" | paste -sd, -)
-
-node "$UK_ROOT/$KIT_DIR/engine/resolve.js" --paths "$PATHS" --root "$UK_ROOT"
+node "$UK_ROOT/$KIT_DIR/engine/reverse-staged.js" --root "$UK_ROOT"
 exit $?