@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/judgment-gen.js

@@ -1,8 +1,9 @@
 /**
  * lib/judgment-gen.js — judgment projections (S04).
  *
- * records → REGISTER.md, LEDGER.md, OBJECTIVE.md, positions/<slug>.md, and
- * the OKF bundle root index.md. Projections are PURE OUTPUT: generation
+ * records → REGISTER.md, LEDGER.md, OBJECTIVE.md, SITUATION.md,
+ * people/<slug>.md, positions/<slug>.md, and the OKF bundle root index.md.
+ * Projections are PURE OUTPUT: generation
  * reads only records — never an existing projection — so any hand-edit is
  * overwritten by the next regeneration and there are no preserved sections
  * (curated prose is `note` records rendered at their anchors).
@@ -22,7 +23,12 @@ import {
   readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, existsSync, readdirSync,
 } from 'node:fs';
 import { join } from 'node:path';
-import { createJudgmentStore } from './judgment/store/index.js';
+import {
+  createJudgmentStore,
+  effectiveStore,
+  goalCutoverComplete,
+} from './judgment/store/index.js';
+import { buildSupersessionIndex } from './judgment/trace.js';
 
 function atomicWrite(path, content) {
   const tmp = `${path}.tmp.${process.pid}`;
@@ -50,17 +56,26 @@ function smartmemoryTeamId(cwd) {
  * Load everything projection-relevant from the store into a plain snapshot,
  * so the generator core stays pure.
  */
-function loadSnapshot(cwd) {
-  const store = createJudgmentStore(cwd);
+export function loadSnapshot(cwd) {
+  const rawStore = createJudgmentStore(cwd);
+  const store = effectiveStore(rawStore);
+  // Prebuilt index: derivePositionStatus otherwise rescans every other slug's
+  // chain per call, making this whole-store pass O(n^2) (COMP-JUDGMENT-PRECEDENT).
+  const supersession = buildSupersessionIndex(store);
   const positions = store.listPositionSlugs().map((slug) => ({
     slug,
     chain: store.readPositionChain(slug),
-    status: store.derivePositionStatus(slug),
+    status: store.derivePositionStatus(slug, supersession),
   }));
   return {
     positions,
     joints: store.listJoints(),
     ledger: store.readLedgerEvents(),
+    people: store.listPeople(),
+    situationEntities: store.listSituationEntities(),
+    goalChain: store.readGoalChain(),
+    goalState: store.readGoalState(),
+    goalCutoverComplete: goalCutoverComplete(store),
     teamId: smartmemoryTeamId(cwd),
   };
 }
@@ -75,11 +90,22 @@ function renderNotes(notes) {
   return notes.map((n) => `> **${n.title}** — ${n.body ?? ''}`.trimEnd()).join('\n\n');
 }
 
+// Plain YAML scalars that need no quoting: no leading/trailing space, none
+// of the indicator/structure characters that would change the parse. Risky
+// titles (e.g. "Jane: CEO") are emitted JSON-quoted, which is valid YAML
+// double-quote style.
+const YAML_PLAIN_SAFE_RE = /^[A-Za-z0-9](?:[A-Za-z0-9 _./()-]*[A-Za-z0-9_./()-])?$/;
+
+function yamlScalar(value) {
+  const s = String(value);
+  return YAML_PLAIN_SAFE_RE.test(s) ? s : JSON.stringify(s);
+}
+
 function okfFrontmatter({ type, title, timestamp, resource }) {
   const lines = ['---'];
   if (type) lines.push(`type: ${type}`);
   else lines.push('okf_version: "0.1"');
-  lines.push(`title: ${title}`);
+  lines.push(`title: ${yamlScalar(title)}`);
   if (timestamp) lines.push(`timestamp: "${timestamp}"`);
   if (resource) lines.push(`resource: "${resource}"`);
   lines.push('smartmemory:');
@@ -94,6 +120,194 @@ function buildResource(teamId, providerId) {
   return `smartmemory://${encodeURIComponent(teamId)}/${encodeURIComponent(providerId)}`;
 }
 
+function auditValue(value) {
+  const encoded = JSON.stringify(value);
+  return encoded === undefined ? String(value) : encoded;
+}
+
+function renderTraceLines(trace = [], { prefix = '  - ' } = {}) {
+  return trace.map((entry) => {
+    const prior = Object.entries(entry.prior ?? {})
+      .map(([key, value]) => `${key}=${auditValue(value)}`)
+      .join(', ');
+    return `${prefix}corrected from ${prior} at ${entry.corrected_at ?? 'unknown'}`;
+  });
+}
+
+function renderRecordedAndRemoval(entry, { prefix = '  - ' } = {}) {
+  const lines = [];
+  lines.push(`${prefix}recorded at ${entry.provenance?.written_at ?? 'unknown'}`);
+  if (entry.removed) {
+    lines.push(`${prefix}removed at ${entry.removed.at ?? 'unknown'} — ${entry.removed.reason}`);
+  }
+  return lines;
+}
+
+function renderAuditedFact(fact) {
+  const lines = [`- **${fact.id}** ${fact.text}`];
+  lines.push(`  - channel: \`${fact.channel}\``);
+  if (fact.via !== undefined) lines.push(`  - via: ${fact.via}`);
+  lines.push(`  - at: ${fact.at}`);
+  lines.push(...renderTraceLines(fact.trace));
+  return lines.join('\n');
+}
+
+const PERSON_SECTIONS = ['role', 'life', 'stated', 'revealed'];
+
+function sectionTitle(section) {
+  return section[0].toUpperCase() + section.slice(1);
+}
+
+function orderedPairLabel(left, right) {
+  const suffix = (id) => Number.parseInt(String(id).replace(/^[^0-9]+/, ''), 10);
+  const ids = [left, right].sort((a, b) => suffix(a) - suffix(b) || a.localeCompare(b));
+  return `${ids[0]} ↔ ${ids[1]}`;
+}
+
+function renderPerson(person) {
+  const lifecycle = person.facts.some((fact) => fact.channel === 'said') ? 'spoken' : 'stub';
+  const parts = [okfFrontmatter({
+    type: 'person',
+    title: person.display_name,
+    timestamp: person.provenance?.written_at,
+  })];
+  parts.push('');
+  parts.push(`# ${person.display_name}`);
+  parts.push('');
+  parts.push(`**Lifecycle:** ${lifecycle}`);
+  parts.push(`**Record:** \`${person.slug}\``);
+
+  const factsById = new Map(person.facts.map((fact) => [fact.id, fact]));
+  const rendered = new Set();
+  for (const section of PERSON_SECTIONS) {
+    parts.push('');
+    parts.push(`## ${sectionTitle(section)}`);
+    parts.push('');
+    const sectionLines = [];
+    for (const fact of person.facts.filter((entry) => entry.section === section)) {
+      if (rendered.has(fact.id)) continue;
+      const paired = fact.diverges_with ? factsById.get(fact.diverges_with) : null;
+      const isStatedRevealedPair = (
+        section === 'stated'
+        && paired?.section === 'revealed'
+        && paired.diverges_with === fact.id
+      );
+      sectionLines.push(renderAuditedFact(fact));
+      rendered.add(fact.id);
+      if (isStatedRevealedPair) {
+        sectionLines.push(renderAuditedFact(paired));
+        sectionLines.push(`  - divergence pair: ${orderedPairLabel(fact.id, paired.id)}`);
+        rendered.add(paired.id);
+      }
+    }
+    parts.push(sectionLines.length > 0 ? sectionLines.join('\n') : 'No facts recorded.');
+  }
+
+  parts.push('');
+  parts.push('## Edges');
+  parts.push('');
+  if (person.edges.length === 0) {
+    parts.push('None.');
+  } else {
+    for (const edge of person.edges) {
+      parts.push(`- **${edge.id}** \`${edge.removed ? 'removed' : 'active'}\` — ${edge.kind} → [${edge.to}](${edge.to}.md)`);
+      parts.push(...renderRecordedAndRemoval(edge));
+    }
+  }
+
+  parts.push('');
+  parts.push('## Open fields');
+  parts.push('');
+  if (person.open_fields.length === 0) {
+    parts.push('None.');
+  } else {
+    for (const field of person.open_fields) {
+      parts.push(`- **${field.id}** \`${field.status}\` — ${field.name}`);
+      parts.push(`  - filled_by: ${field.filled_by ?? '—'}`);
+      parts.push(`  - recorded at ${field.provenance?.written_at ?? 'unknown'}`);
+      parts.push(...renderTraceLines(field.trace));
+    }
+  }
+
+  parts.push('');
+  parts.push('## Load links');
+  parts.push('');
+  if (person.load_links.length === 0) {
+    parts.push('None.');
+  } else {
+    for (const link of person.load_links) {
+      parts.push(`- **${link.id}** \`${link.removed ? 'removed' : 'active'}\` — fact ${link.fact} carries ${link.carries}`);
+      parts.push(...renderRecordedAndRemoval(link));
+    }
+  }
+  return parts.join('\n') + '\n';
+}
+
+function latestWrittenAt(records) {
+  return records
+    .map((record) => record.provenance?.written_at)
+    .filter(Boolean)
+    .sort()
+    .at(-1);
+}
+
+function renderSituation(snapshot) {
+  const entities = [...(snapshot.situationEntities ?? [])].sort((a, b) => (
+    a.display_name.localeCompare(b.display_name) || a.slug.localeCompare(b.slug)
+  ));
+  const parts = [okfFrontmatter({
+    type: 'situation',
+    title: 'Situation',
+    timestamp: latestWrittenAt(entities),
+  })];
+  parts.push('');
+  parts.push('# Situation');
+  if (entities.length === 0) {
+    parts.push('');
+    parts.push('No situation entities recorded.');
+  }
+  for (const entity of entities) {
+    parts.push('');
+    parts.push(`## ${entity.display_name} (\`${entity.slug}\`)`);
+    parts.push('');
+    parts.push('### Facts');
+    parts.push('');
+    if (entity.facts.length === 0) {
+      parts.push('None.');
+    } else {
+      for (const fact of entity.facts) parts.push(renderAuditedFact(fact));
+    }
+
+    parts.push('');
+    parts.push('### Owed');
+    parts.push('');
+    if (entity.owed.length === 0) {
+      parts.push('None.');
+    } else {
+      for (const owed of entity.owed) {
+        parts.push(`> **OWED ${owed.id} · ${owed.status}** ${owed.name}`);
+        parts.push(`> - why load-bearing: ${owed.why_load_bearing}`);
+        parts.push(`> - filled_by: ${owed.filled_by ?? '—'}`);
+        parts.push(`> - recorded at ${owed.provenance?.written_at ?? 'unknown'}`);
+        parts.push(...renderTraceLines(owed.trace, { prefix: '> - ' }));
+      }
+    }
+
+    parts.push('');
+    parts.push('### Load links');
+    parts.push('');
+    if (entity.load_links.length === 0) {
+      parts.push('None.');
+    } else {
+      for (const link of entity.load_links) {
+        parts.push(`- **${link.id}** \`${link.removed ? 'removed' : 'active'}\` — fact ${link.fact} carries ${link.carries}`);
+        parts.push(...renderRecordedAndRemoval(link));
+      }
+    }
+  }
+  return parts.join('\n') + '\n';
+}
+
 function renderClaim(claim) {
   const lines = [`- **${claim.id}** \`[${claim.grounding}]\`${claim.owner_locked ? ' `[owner-locked]`' : ''} ${claim.text}`];
   if (Array.isArray(claim.supports) && claim.supports.length > 0) {
@@ -218,6 +432,7 @@ const EVENT_DETAIL_KEYS = [
   'refs', 'rejected', 'conviction', 'trigger', 'open_joints', 'prediction',
   'disposition', 'recall_verdict', 'attribution', 'prediction_ref',
   'prediction_grade', 'reason', 'rank_change', 'elicitation',
+  'intent_id', 'tool', 'op', 'rests_on',
 ];
 
 function renderLedger(snapshot) {
@@ -248,8 +463,118 @@ function renderLedger(snapshot) {
   return parts.join('\n') + '\n';
 }
 
+function renderGoalClause(clause) {
+  const lines = [`- **${clause.id}** ${clause.text}`];
+  lines.push(`  - channel: \`${clause.channel}\``);
+  if (clause.via !== undefined) lines.push(`  - via: ${clause.via}`);
+  const citation = clause.elicitation;
+  lines.push(
+    `  - elicitation: asked "${citation.asked}" (answered ${citation.answered_at}, ref ${citation.answer_ref})`,
+  );
+  lines.push(...renderTraceLines(clause.trace));
+  return lines.join('\n');
+}
+
+function tableCell(value) {
+  return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+}
+
+function renderGoalObjective(snapshot) {
+  const chain = snapshot.goalChain ?? [];
+  const current = chain.at(-1);
+  if (!current) {
+    return [
+      okfFrontmatter({ type: 'goal', title: 'Objective' }),
+      '',
+      '# Objective',
+      '',
+      'No goal recorded.',
+    ].join('\n') + '\n';
+  }
+
+  const state = snapshot.goalState ?? { joints: [], load_links: [] };
+  const parts = [okfFrontmatter({
+    type: 'goal',
+    title: 'Objective',
+    timestamp: current.provenance?.written_at,
+  })];
+  parts.push('');
+  parts.push('# Objective');
+  parts.push('');
+  parts.push(`**Current version:** v${current.version}`);
+  const draft = (
+    ['import', 'migration'].includes(current.provenance?.via)
+    && !current.ratification
+  );
+  if (draft) {
+    parts.push('');
+    parts.push('**DRAFT HEALTH WARNING:** This imported/migrated goal is not owner-ratified.');
+  }
+
+  parts.push('');
+  parts.push(`## Current clauses (v${current.version})`);
+  parts.push('');
+  for (const clause of current.clauses) parts.push(renderGoalClause(clause));
+
+  parts.push('');
+  parts.push('## Ratification citation');
+  parts.push('');
+  if (current.ratification) {
+    parts.push(`- asked "${current.ratification.asked}"`);
+    parts.push(`- quote: "${current.ratification.quote}"`);
+    parts.push(
+      `- answered ${current.ratification.answered_at}, ref ${current.ratification.answer_ref}`,
+    );
+  } else {
+    parts.push('None — imported/migrated draft.');
+  }
+
+  parts.push('');
+  parts.push('## Goal joints');
+  parts.push('');
+  if ((state.joints ?? []).length === 0) {
+    parts.push('None.');
+  } else {
+    for (const link of state.joints) {
+      parts.push(`- **${link.id}** \`${link.removed ? 'removed' : 'active'}\` — [${link.joint}](REGISTER.md#${link.joint})`);
+      parts.push(...renderRecordedAndRemoval(link));
+    }
+  }
+
+  parts.push('');
+  parts.push('## Load-link bill');
+  parts.push('');
+  if ((state.load_links ?? []).length === 0) {
+    parts.push('None.');
+  } else {
+    for (const link of state.load_links) {
+      const version = Number(/^v([1-9][0-9]*)#/.exec(link.clause)?.[1]);
+      const versionMark = version === current.version ? 'current version' : 'superseded version';
+      parts.push(`- **${link.id}** \`${link.removed ? 'removed' : 'active'}\` — ${link.clause} \`${versionMark}\` carries ${link.carries}`);
+      parts.push(...renderRecordedAndRemoval(link));
+    }
+  }
+
+  parts.push('');
+  parts.push('## Trajectory');
+  parts.push('');
+  parts.push('| Version | Date | Provocation | Diff note | Wording fix |');
+  parts.push('|---|---|---|---|---|');
+  for (const version of chain) {
+    const provocation = version.provocation?.quote ?? 'unknown (migrated)';
+    const wordingFix = version.clauses.some((clause) => (clause.trace?.length ?? 0) > 0)
+      ? 'yes'
+      : 'no';
+    parts.push(
+      `| v${version.version} | ${tableCell(version.provenance?.written_at ?? 'unknown')} | ${tableCell(provocation)} | ${tableCell(version.diff_note)} | ${wordingFix} |`,
+    );
+  }
+  return parts.join('\n') + '\n';
+}
+
 function renderObjective(snapshot) {
-  const objective = snapshot.positions.find((p) => p.slug === 'objective');
+  if (snapshot.goalCutoverComplete) return renderGoalObjective(snapshot);
+  const objective = (snapshot.positions ?? []).find((p) => p.slug === 'objective');
   if (objective) return renderPosition(objective, snapshot);
   return [
     okfFrontmatter({ type: 'position', title: 'objective' }),
@@ -261,6 +586,9 @@ function renderObjective(snapshot) {
 }
 
 function renderIndex(snapshot) {
+  const positions = (snapshot.positions ?? []).filter(
+    (position) => !(snapshot.goalCutoverComplete && position.slug === 'objective'),
+  );
   const parts = [okfFrontmatter({ type: null, title: 'Judgment canon' })];
   parts.push('');
   parts.push('# Judgment canon (generated)');
@@ -270,11 +598,11 @@ function renderIndex(snapshot) {
   parts.push('- [Register](REGISTER.md)');
   parts.push('- [Ledger](LEDGER.md)');
   parts.push('- [Objective](OBJECTIVE.md)');
-  if (snapshot.positions.length) {
+  if (positions.length) {
     parts.push('');
     parts.push('## Positions');
     parts.push('');
-    for (const p of snapshot.positions) {
+    for (const p of positions) {
       parts.push(`- [${p.slug}](positions/${p.slug}.md) — ${p.status}`);
     }
   }
@@ -293,14 +621,40 @@ export function generateFromRecords(snapshot, { now } = {}) { // eslint-disable-
     'docs/judgment/REGISTER.md': renderRegister(snapshot),
     'docs/judgment/LEDGER.md': renderLedger(snapshot),
     'docs/judgment/OBJECTIVE.md': renderObjective(snapshot),
+    'docs/judgment/SITUATION.md': renderSituation(snapshot),
     'docs/judgment/index.md': renderIndex(snapshot),
   };
-  for (const position of snapshot.positions) {
+  for (const person of [...(snapshot.people ?? [])].sort((a, b) => a.slug.localeCompare(b.slug))) {
+    files[`docs/judgment/people/${person.slug}.md`] = renderPerson(person);
+  }
+  for (const position of (snapshot.positions ?? [])) {
+    if (snapshot.goalCutoverComplete && position.slug === 'objective') continue;
     files[`docs/judgment/positions/${position.slug}.md`] = renderPosition(position, snapshot);
   }
   return files;
 }
 
+const MANAGED_MARKDOWN_DIRS = [
+  'docs/judgment/people',
+  'docs/judgment/positions',
+];
+
+function managedStaleProjections(cwd, files) {
+  const stale = [];
+  for (const relDir of MANAGED_MARKDOWN_DIRS) {
+    const dir = join(cwd, relDir);
+    if (!existsSync(dir)) continue;
+    const entries = readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const rel = `${relDir}/${entry.name}`;
+      if (!(rel in files)) stale.push(rel);
+    }
+  }
+  return stale;
+}
+
 /**
  * Regenerate every projection from records on disk. Atomic per file.
  * @returns {{ files: string[] }} relative paths written
@@ -312,6 +666,9 @@ export function regenerateProjections(cwd) {
     mkdirSync(join(path, '..'), { recursive: true });
     atomicWrite(path, content);
   }
+  for (const rel of managedStaleProjections(cwd, files)) {
+    unlinkSync(join(cwd, rel));
+  }
   return { files: Object.keys(files) };
 }
 
@@ -325,18 +682,14 @@ export function checkProjectionRoundtrip(cwd) {
   const diffs = [];
   for (const [rel, content] of Object.entries(files)) {
     const path = join(cwd, rel);
-    const onDisk = existsSync(path) ? readFileSync(path, 'utf8') : null;
-    if (onDisk !== content) diffs.push(rel);
-  }
-  // Orphan detection: a projection file the generator no longer emits (stale
-  // position projection, leftover from an older generator) is drift too.
-  const positionsDir = join(cwd, 'docs', 'judgment', 'positions');
-  if (existsSync(positionsDir)) {
-    for (const f of readdirSync(positionsDir)) {
-      if (!f.endsWith('.md')) continue;
-      const rel = `docs/judgment/positions/${f}`;
-      if (!(rel in files)) diffs.push(`${rel} (orphan — not emitted by the generator)`);
+    if (!existsSync(path)) {
+      diffs.push(`${rel} (missing)`);
+      continue;
     }
+    if (readFileSync(path, 'utf8') !== content) diffs.push(`${rel} (drift)`);
+  }
+  for (const rel of managedStaleProjections(cwd, files)) {
+    diffs.push(`${rel} (orphan — not emitted by the generator)`);
   }
   return { fixedPoint: diffs.length === 0, diffs };
 }

package/lib/judgment-verify.js

@@ -0,0 +1,153 @@
+/**
+ * Combined drift verification for the judgment canon.
+ *
+ * The inventory, projection roundtrip, and record attestation are evaluated
+ * under the writer's advisory lock so a legitimate write cannot expose a
+ * partially-published canon to the verifier.
+ */
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+} from 'node:fs';
+import { join, posix } from 'node:path';
+
+import { readManifest, recordFileSet, verifyRecords } from './judgment-attest.js';
+import {
+  checkProjectionRoundtrip,
+  generateFromRecords,
+  loadSnapshot,
+} from './judgment-gen.js';
+import { withJudgmentLock } from './judgment-writer.js';
+
+const JUDGMENT_REL = 'docs/judgment';
+const MANIFEST_REL = `${JUDGMENT_REL}/.attest.json`;
+const RECORDS_REL = `${JUDGMENT_REL}/records`;
+const STRUCTURAL_DIRS = [
+  RECORDS_REL,
+  `${JUDGMENT_REL}/people`,
+  `${JUDGMENT_REL}/positions`,
+];
+// The legitimate depth-1 dirs under records/. Anything else there (e.g. a
+// Bash-created `records/garbage/`) is drift. Deeper legitimate dirs — such as
+// `records/positions/<slug>/` — are admitted by expectedTree's parent-walk over
+// the real record files, so this list stays exact rather than blanket-exempting
+// every nested path.
+const RECORD_STRUCTURAL_DIRS = [
+  'goal', 'intents', 'joints', 'people', 'positions', 'predictions', 'situation',
+].map((name) => `${RECORDS_REL}/${name}`);
+
+function expectedTree(cwd) {
+  // Derive the expected projection set from the SAME snapshot builder that
+  // checkProjectionRoundtrip uses (loadSnapshot, exported from judgment-gen).
+  // Reconstructing it here would be a mirror that silently diverges into false
+  // tree drift the moment loadSnapshot changes.
+  const projections = Object.keys(generateFromRecords(loadSnapshot(cwd)));
+  const records = recordFileSet(cwd);
+  // The manifest is NOT in this set: it lives at .compose/judgment-attest.json,
+  // outside the tree being inventoried.
+  const files = new Set([...projections, ...records]);
+  const directories = new Set([JUDGMENT_REL, ...STRUCTURAL_DIRS, ...RECORD_STRUCTURAL_DIRS]);
+
+  for (const relPath of files) {
+    let parent = posix.dirname(relPath);
+    while (parent.startsWith(`${JUDGMENT_REL}/`)) {
+      directories.add(parent);
+      parent = posix.dirname(parent);
+    }
+  }
+
+  return { files, directories };
+}
+
+function inventoryTree(cwd, expected) {
+  const root = join(cwd, ...JUDGMENT_REL.split('/'));
+  if (!existsSync(root)) return [];
+
+  const rootStat = lstatSync(root);
+  if (rootStat.isSymbolicLink()) {
+    return [{ path: JUDGMENT_REL, kind: 'symlink' }];
+  }
+  if (!rootStat.isDirectory()) {
+    return [{ path: JUDGMENT_REL, kind: 'unexpected' }];
+  }
+
+  const drift = [];
+
+  function walk(absDir, relDir) {
+    const entries = readdirSync(absDir)
+      .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+
+    for (const name of entries) {
+      const absPath = join(absDir, name);
+      const relPath = `${relDir}/${name}`;
+      const stat = lstatSync(absPath);
+
+      if (stat.isSymbolicLink()) {
+        drift.push({ path: relPath, kind: 'symlink' });
+        continue;
+      }
+
+      if (stat.isDirectory()) {
+        // An EMPTY unexpected dir is not reported: it holds no canon, and
+        // UndoLog.restore unlinks files without removing their directories, so a
+        // rolled-back op legitimately leaves e.g. an empty positions/<slug>/.
+        // Flagging those would false-RED on correct behaviour. A non-empty stray
+        // dir is still caught — every file inside it fails the file rule below.
+        if (!expected.directories.has(relPath) && readdirSync(absPath).length > 0) {
+          drift.push({ path: relPath, kind: 'unexpected' });
+        }
+        walk(absPath, relPath);
+        continue;
+      }
+
+      if (!stat.isFile() || !expected.files.has(relPath)) {
+        drift.push({ path: relPath, kind: 'unexpected' });
+      }
+    }
+  }
+
+  walk(root, JUDGMENT_REL);
+  drift.sort((a, b) => {
+    if (a.path !== b.path) return a.path < b.path ? -1 : 1;
+    return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+  });
+  return drift;
+}
+
+/**
+ * True when this project has no judgment canon at all — no `docs/judgment/`
+ * tree and no attestation baseline. There is nothing to verify, so verification
+ * must pass: most Compose projects never adopt the judgment layer, and a
+ * gate that fails them would break every pre-push and ship in those repos.
+ *
+ * This is NOT the same as a deleted canon. The baseline lives outside
+ * `docs/judgment/**` (at `.compose/judgment-attest.json`), so wiping the canon
+ * leaves the manifest behind — `hasNoCanon` is false and every record it
+ * remembers surfaces as `removed` drift.
+ */
+function hasNoCanon(cwd) {
+  return !existsSync(join(cwd, ...JUDGMENT_REL.split('/')))
+    && readManifest(cwd) === null;
+}
+
+export async function verifyJudgmentCanon(cwd) {
+  return withJudgmentLock(cwd, async () => {
+    if (hasNoCanon(cwd)) {
+      return { ok: true, treeDrift: [], projectionDrift: [], recordDrift: [] };
+    }
+
+    const treeDrift = inventoryTree(cwd, expectedTree(cwd));
+    const projection = checkProjectionRoundtrip(cwd);
+    const records = verifyRecords(cwd);
+    const projectionDrift = projection.diffs;
+    const recordDrift = records.drift;
+
+    return {
+      ok: treeDrift.length === 0 && projection.fixedPoint && records.ok,
+      treeDrift,
+      projectionDrift,
+      recordDrift,
+    };
+  });
+}