create-pmos 0.38.8 → 0.40.0

package/workspace/lib/claims.js

@@ -0,0 +1,605 @@
+'use strict';
+/* claims.js — the claims ledger and the local checks (claims-ledger C2–C7).
+ *
+ * WHAT IT DOES. It reads the documents and config files of a repository, classifies each (lib/doc-profiles.js),
+ * extracts SHORT STATEMENTS from them by structure (a lineage path, a requirement id, a rubric weight, a cited
+ * decision, a link, a date), and verifies each statement LOCALLY against the truth the repository already holds:
+ * the decisions file, the initiative records, the PRD's own requirement list, git. It sends nothing anywhere.
+ *
+ * WHAT A CLAIM ENDS AS.
+ *   verified      the truth source agrees.
+ *   contradicted  the truth source says otherwise; `truth` says what it says.
+ *   stale         a document it derives from changed after it did, or its `stale_after` date has passed.
+ *   undecided     structure cannot decide it (a counterpart that does not name this document, a rubric with no
+ *                 weights table). Stage 3 may hand an undecided claim to a model; this stage only reports it.
+ *
+ * WHY IT IS CHEAP. Reads are limited to files whose mtime or size moved; unchanged hashes skip extraction; a
+ * changed file re-verifies itself and the documents that cite it, and no others; the ledger gains a line only when
+ * a claim's status, truth or text changed, so a repeat run appends nothing.
+ *
+ * WHAT IT NEVER DOES. It does not edit a repository document, a decision or an acceptance. Its one write into the
+ * repository is `claims.jsonl`, appended through lib/sink.js. Its caches (stamps, index) live in the per-user
+ * runtime directory, outside every repository.
+ *
+ * WHAT IT CANNOT SEE. Prose with no structured statement is not extracted. A *Consistent* verdict means consistent
+ * by structure and ledger; the page says so.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+const { classify, extOf, IN_SCOPE_EXT, REFERENCES } = require('./doc-profiles');
+const { createSinkGuard } = require('./sink');
+
+const MAX_FILES = 4000;
+const MAX_DOC_BYTES = 400 * 1024;
+const STALE_SECS = 3600;                 // a source must be newer than its dependent by this much to make it stale
+const WEIGHT_TOLERANCE = 0.011;
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.next', 'dist', 'build', 'vendor']);
+const REQ_RE = /^\s*[-*]\s+\*\*([A-Z]{1,3}\d{1,3})\b[^*]*\*\*/;
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const nowISO = () => new Date().toISOString();
+
+/* ── git, asynchronously. The existing git helpers use spawnSync and block the event loop; a poller must not. ── */
+function git(root, args) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd: root, maxBuffer: 64 << 20, timeout: 20000, encoding: 'utf8' }, (err, out) => resolve(err ? null : out));
+  });
+}
+
+/* ── reading ───────────────────────────────────────────────────────────────────────────────────── */
+function walk(root) {
+  const found = [];
+  (function go(dir, rel) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) go(path.join(dir, e.name), r); }
+      else found.push(r);
+    }
+  })(root, '');
+  return found;
+}
+async function listScope(root) {
+  // Tracked files AND new files nobody has added yet (an agent's output), minus whatever .gitignore excludes.
+  const out = await git(root, ['ls-files', '-z', '--cached', '--others', '--exclude-standard']);
+  const all = out ? out.split('\0').filter(Boolean) : walk(root);
+  const files = all.filter((r) => IN_SCOPE_EXT.has(extOf(r)) && !r.split('/').some((s) => SKIP_DIRS.has(s))).sort();
+  return { files: files.slice(0, MAX_FILES), total: files.length, truncated: files.length > MAX_FILES };
+}
+
+/** Last change time (epoch seconds) per path: git's latest commit that touched it, or the mtime for a dirty file. */
+async function lastChanges(root, dirty) {
+  const map = new Map();
+  const out = await git(root, ['log', '-n', '4000', '--format=%x01%ct', '--name-only']);
+  if (out) {
+    let t = 0;
+    for (const line of out.split('\n')) {
+      if (line.startsWith('\u0001')) { t = Number(line.slice(1)) || 0; continue; }
+      if (line && !map.has(line)) map.set(line, t);
+    }
+  }
+  for (const rel of dirty) {
+    try { map.set(rel, Math.floor(fs.statSync(path.join(root, rel)).mtimeMs / 1000)); } catch { /* deleted */ }
+  }
+  return map;
+}
+async function dirtyFiles(root) {
+  const out = await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+  if (!out) return new Set();
+  const set = new Set();
+  for (const ent of out.split('\0')) { if (ent.length > 3) set.add(ent.slice(3)); }
+  return set;
+}
+
+/* ── small parsers ─────────────────────────────────────────────────────────────────────────────── */
+function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const fm = {};
+  if (!m) return fm;
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) fm[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+/* A value as a person wrote it: `backticks`, **bold** and quotes are decoration, not part of the value. */
+const cleanValue = (v) => String(v == null ? '' : v).trim().replace(/^[`*"']+|[`*"']+$/g, '').trim();
+/* An initiative id as written in a bullet: the first token, without the decoration that often follows it. */
+const idOf = (v) => cleanValue(v).split(/[\s`·,;(]/)[0];
+/* A placeholder is not a claim: "(set per initiative)", "<per-use>", "TBD". */
+const isPlaceholder = (v) => /^[<(\[{].*[>)\]}]$/.test(String(v).trim()) || /\b(per[- ]use|per initiative|tbd|n\/a|none yet)\b/i.test(String(v));
+/** `- key: value` lines in the document's Identity block (the first 80 lines after the frontmatter). */
+function bodyKeys(text) {
+  const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+  const keys = {};
+  for (const line of body.split(/\r?\n/).slice(0, 80)) {
+    const kv = /^\s*[-*]\s+([A-Za-z_][\w -]*?):\s*(.*)$/.exec(line);
+    if (kv && !(kv[1].toLowerCase() in keys)) keys[kv[1].toLowerCase().replace(/\s+/g, '_')] = cleanValue(kv[2]);
+  }
+  return keys;
+}
+function linksOf(text) {
+  const out = [];
+  const re = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  let m;
+  while ((m = re.exec(text.replace(/```[\s\S]*?```/g, '')))) out.push(m[1]);
+  return out;
+}
+/** Resolve a link or path to a repo-relative path, or null when it is external, an anchor, or leaves the repository. */
+function resolveRef(docRel, target) {
+  const t = String(target || '').trim();
+  if (!t || /^(?:[a-z][a-z0-9+.-]*:|#|\/\/)/i.test(t)) return null;
+  let clean;
+  try { clean = decodeURI(t.split('#')[0].split('?')[0]); } catch { return null; }
+  if (!clean) return null;
+  const p = clean.startsWith('/') ? clean.slice(1) : path.posix.join(path.posix.dirname(docRel), clean);
+  const norm = path.posix.normalize(p);
+  return norm.startsWith('..') ? null : norm;
+}
+/* The first file a value points at: a markdown link, else the first token that looks like a path to a .md file.
+ * Anything else ("paired", "(set per use)") points at nothing, and is not guessed at. */
+const firstLinkPath = (docRel, value) => {
+  const v = String(value || '');
+  const m = /\]\(([^)\s]+)\)/.exec(v);
+  if (m) return resolveRef(docRel, m[1]);
+  const t = /([\w./-]+\.md)\b/.exec(v.replace(/[`*]/g, ''));
+  if (!t) return null;
+  // A bare path in a bullet is written from the repository root; a bare file name is beside the document.
+  return t[1].includes('/') ? resolveRef(docRel, '/' + t[1].replace(/^\/+/, '')) : resolveRef(docRel, t[1]);
+};
+const headingsOf = (text) => Array.from(text.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)).map((m) => m[1].toLowerCase());
+const norm = (p) => (p ? path.posix.normalize(String(p).replace(/^\/+/, '')) : '');
+
+/* Every weights table in a rubric, as [{sum, rows}]. The Weight column is found by its header, so a table that
+ * puts it second (Dimension | Weight | Score) and one that puts it third (# | dimension | weight) both read. A rubric
+ * may hold two tables (a second round of dimensions); each is checked on its own. */
+function rubricWeights(text) {
+  const lines = text.split('\n');
+  const tables = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\s*\|/.test(lines[i])) continue;
+    const cells = lines[i].split('|').slice(1, -1).map((c) => c.trim().toLowerCase());
+    const col = cells.findIndex((c) => /^\**weight\**$/.test(c));
+    if (col < 0) continue;
+    const rows = [];
+    let j = i + 1;
+    if (/^\s*\|[\s:|-]+\|\s*$/.test(lines[j] || '')) j++;
+    for (; j < lines.length && /^\s*\|/.test(lines[j]); j++) {
+      const rowCells = lines[j].split('|').slice(1, -1);
+      if (rowCells.some((c) => /^\**total\**$/i.test(c.trim()))) continue;          // the Total row is not a dimension
+      const cell = (rowCells[col] || '').replace(/[*`%\s]/g, '');
+      if (/^(?:0?\.\d+|1(?:\.0+)?)$/.test(cell)) rows.push(Number(cell));
+    }
+    if (rows.length) tables.push({ sum: Math.round(rows.reduce((a, b) => a + b, 0) * 1000) / 1000, rows: rows.length });
+    i = j;
+  }
+  return tables;
+}
+
+/* ── extraction: structure only, by type ───────────────────────────────────────────────────────── */
+function extract(rel, text, cls, fm, body) {
+  const out = [];
+  const add = (kind, subject, statement, extra = {}) => out.push({ doc: rel, kind, subject: String(subject), text: String(statement).slice(0, 220), refs: [], ...extra });
+
+  const seen = new Set();
+  for (const t of linksOf(text)) {
+    const r = resolveRef(rel, t);
+    if (!r || seen.has(r) || seen.size >= 40) continue;
+    seen.add(r);
+    add('link', r, `links to ${r}`, { refs: [r] });
+  }
+  if (/^\d{4}-\d{2}-\d{2}/.test(fm.stale_after || '')) add('time', 'stale_after', `stale_after ${fm.stale_after.slice(0, 10)}`, { value: fm.stale_after.slice(0, 10) });
+
+  const type = cls.type;
+  if (type === 'Config') {
+    if (extOf(rel) === 'json') {
+      let err = null;
+      try { JSON.parse(text); } catch (e) { err = (e && e.message) || 'parse error'; }
+      add('syntax', 'json', 'is valid JSON', { value: err });
+    }
+    return out;
+  }
+  if (type === 'Initiative' && fm.id) {
+    for (const key of ['prd_path', 'rubric_path', 'explainer_path', 'brief_path', 'doc_path']) {
+      if (fm[key] && !isPlaceholder(fm[key])) add('lineage', key, `${key} is ${fm[key]}`, { value: norm(fm[key]), initiative: fm.id, refs: [norm(fm[key]), 'init:' + fm.id] });
+    }
+    add('anchor', 'parent_kr', 'has an anchor', { value: fm.parent_kr || '' });
+  }
+  if (type === 'PRD') {
+    const ids = new Map();
+    for (const line of text.split('\n')) {
+      const m = REQ_RE.exec(line);
+      if (m) { ids.set(m[1], (ids.get(m[1]) || 0) + 1); }
+    }
+    for (const [id, n] of ids) add('req', id, `requirement ${id}`, { value: n });
+    const iid = idOf(body.initiative_id || fm.initiative_id);
+    if (iid && !isPlaceholder(iid)) add('prd_initiative', iid, `names initiative ${iid}`, { value: iid, refs: ['init:' + iid] });
+    if (body.rubric) { const p = firstLinkPath(rel, body.rubric); if (p) add('prd_rubric', p, `names rubric ${p}`, { value: p, refs: [p] }); }
+    const cited = new Set();
+    for (const m of text.matchAll(/\[D(\d{1,3})\b[^\]]*\]\([^)]*\)/g)) cited.add(Number(m[1]));
+    for (const n of cited) add('decision', 'D' + n, `cites decision D${n}`, { value: n, refs: ['decisions'] });
+    const hs = headingsOf(text);
+    for (const seg of ['identity', 'requirements']) add('segment', seg, `has a ${seg} section`, { value: hs.some((h) => h.includes(seg)) });
+  }
+  if (type === 'Rubric') {
+    const tables = rubricWeights(text);
+    if (!tables.length) add('weights', 'sum', 'dimension weights sum to 1.00', { value: null, rows: 0 });
+    tables.forEach((t, i) => add('weights', tables.length > 1 ? 'table ' + (i + 1) : 'sum', tables.length > 1 ? `weights table ${i + 1} sums to 1.00` : 'dimension weights sum to 1.00', { value: t.sum, rows: t.rows }));
+    const rf = body.rubric_for ? firstLinkPath(rel, body.rubric_for) : null;
+    if (rf) add('rubric_for', rf, `is the rubric for ${rf}`, { value: rf, refs: [rf] });
+    const iid = idOf(body.initiative_id || fm.initiative_id);
+    if (iid && !isPlaceholder(iid)) add('prd_initiative', iid, `names initiative ${iid}`, { value: iid, refs: ['init:' + iid] });
+    const hs = headingsOf(text);
+    for (const seg of ['dimensions', 'sprint contract']) add('segment', seg, `has a ${seg} section`, { value: hs.some((h) => h.includes(seg)) });
+  }
+  if (type === 'Story') {
+    const iid = idOf(fm.initiative_id || body.initiative_id);
+    const cited = new Set();
+    for (const m of text.matchAll(/\b([A-RT-Z]{1,3}\d{1,3})\b/g)) cited.add(m[1]);
+    for (const id of Array.from(cited).slice(0, 40)) add('story_ref', id, `cites requirement ${id}`, { value: iid || '', refs: iid ? ['init:' + iid] : [] });
+  }
+  if (type === 'ADR') {
+    const m = /(?:^|\/)d(\d{1,3})-/i.exec(rel);
+    if (m) {
+      const n = Number(m[1]);
+      add('adr_number', 'D' + n, `is decision D${n}`, { value: n, refs: ['decisions'] });
+      add('adr_title', 'D' + n, 'title starts with its decision number', { value: fm.title || '', n });
+    }
+  }
+  return out;
+}
+
+/* ── the truth sources ─────────────────────────────────────────────────────────────────────────── */
+function loadDecisions(root, files) {
+  const ids = new Set();
+  let available = false;
+  const dec = files.find((f) => f.toLowerCase() === 'decisions.md');
+  if (dec) {
+    available = true;
+    let t = '';
+    try { t = fs.readFileSync(path.join(root, dec), 'utf8'); } catch { /* unreadable: treated as empty */ }
+    for (const m of t.matchAll(/^###\s+D(\d{1,3})\b/gm)) ids.add(Number(m[1]));
+    for (const m of t.matchAll(/\*\*D(\d{1,3})\*\*/g)) ids.add(Number(m[1]));
+  }
+  for (const f of files) {
+    const m = /(?:^|\/)adr\/d(\d{1,3})-[^/]+\.md$/i.exec(f);
+    if (m) { available = true; ids.add(Number(m[1])); }
+  }
+  return { ids, available, file: dec || null };
+}
+
+/* ── verification ──────────────────────────────────────────────────────────────────────────────── */
+const date = (secs) => new Date(secs * 1000).toISOString().slice(0, 16).replace('T', ' ');
+
+function verifyClaim(c, ctx) {
+  const doc = ctx.docs.get(c.doc);
+  const V = (status, truth, source, sentence) => ({ status, truth: truth || null, source: source || null, sentence });
+  const exists = (r) => ctx.exists(r);
+  switch (c.kind) {
+    case 'link':
+      return exists(c.subject) ? V('verified') : V('contradicted', 'there is no such file', null, `${c.doc} links to ${c.subject}, which does not exist.`);
+    case 'time': {
+      const today = new Date(ctx.now).toISOString().slice(0, 10);
+      return c.value < today ? V('stale', `that date passed`, null, `${c.doc} says it is current until ${c.value}. That date has passed.`) : V('verified');
+    }
+    case 'syntax':
+      return c.value ? V('contradicted', c.value, null, `${c.doc} is not valid JSON: ${c.value}.`) : V('verified');
+    case 'anchor':
+      return c.value ? V('verified') : V('contradicted', 'no anchor is set', null, `The initiative record ${c.doc} has no anchor (parent_kr).`);
+    case 'lineage': {
+      if (!exists(c.value)) return V('contradicted', 'there is no such file', null, `The initiative record ${c.doc} says ${c.subject} is ${c.value}, but there is no such file.`);
+      const target = ctx.docs.get(c.value);
+      if (target && (c.subject === 'prd_path' || c.subject === 'rubric_path')) {
+        const named = idOf(target.body.initiative_id || target.fm.initiative_id);
+        if (named && named !== c.initiative) return V('undecided', `it names initiative ${named}`, c.value, `${c.doc} points ${c.subject} at ${c.value}, but that file names initiative ${named}, not ${c.initiative}. It may be shared on purpose.`);
+        if (!named) return V('undecided', 'the file does not name this initiative', c.value, `${c.value} does not say which initiative it belongs to, so the link from ${c.doc} cannot be confirmed from its side.`);
+      }
+      return V('verified');
+    }
+    case 'req':
+      return c.value > 1 ? V('undecided', `the id appears ${c.value} times`, null, `${c.doc} uses requirement id ${c.subject} ${c.value} times, so a story or rubric that cites ${c.subject} cannot say which one it means.`) : V('verified');
+    case 'segment':
+      return c.value ? V('verified') : V('undecided', 'the section is missing', null, `${c.doc} has no ${c.subject} section, which the template for its type expects. It may predate the template.`);
+    case 'weights':
+      if (c.value === null) return V('undecided', 'no weights table was found', null, `${c.doc}: no dimension weights were found, so their sum cannot be checked.`);
+      return Math.abs(c.value - 1) <= WEIGHT_TOLERANCE ? V('verified') : V('contradicted', `the weights sum to ${c.value}`, null, `The weights in ${c.doc} sum to ${c.value}, not 1.00.`);
+    case 'prd_initiative': {
+      if (!ctx.initiatives.size) return null;
+      const rec = ctx.initiatives.get(c.value);
+      if (!rec) return V('contradicted', 'there is no initiative record with that id', null, `${c.doc} names initiative ${c.value}, but no initiative record has that id.`);
+      const role = doc && doc.cls.type === 'Rubric' ? 'rubric_path' : 'prd_path';
+      if (!rec.fm[role]) return V('undecided', `the initiative record has no ${role}`, rec.rel, `${c.doc} names initiative ${c.value}, whose record does not list it under ${role}.`);
+      if (norm(rec.fm[role]) !== c.doc) return V('undecided', `the record's ${role} is ${norm(rec.fm[role])}`, rec.rel, `${c.doc} names initiative ${c.value}, but that record's ${role} is ${norm(rec.fm[role])}. This may be a second document for the same initiative.`);
+      return V('verified');
+    }
+    case 'prd_rubric': {
+      if (!exists(c.value)) return V('contradicted', 'there is no such file', null, `${c.doc} names the rubric ${c.value}, but there is no such file.`);
+      const r = ctx.docs.get(c.value);
+      const back = r && r.body.rubric_for ? firstLinkPath(c.value, r.body.rubric_for) : null;
+      if (back && back !== c.doc) return V('contradicted', `the rubric says it is for ${back}`, c.value, `${c.doc} names ${c.value} as its rubric, but that rubric says it is for ${back}.`);
+      if (!back) return V('undecided', 'the rubric does not name this PRD', c.value, `${c.value} does not say which PRD it grades, so the link from ${c.doc} cannot be confirmed from its side.`);
+      return V('verified');
+    }
+    case 'rubric_for': {
+      if (!exists(c.value)) return V('contradicted', 'there is no such file', null, `${c.doc} says it is the rubric for ${c.value}, but there is no such file.`);
+      const p = ctx.docs.get(c.value);
+      const back = p && p.body.rubric ? firstLinkPath(c.value, p.body.rubric) : null;
+      if (back && back !== c.doc) return V('contradicted', `the PRD names ${back} as its rubric`, c.value, `${c.doc} says it grades ${c.value}, but that PRD names ${back} as its rubric.`);
+      if (!back) return V('undecided', 'the PRD does not name this rubric', c.value, `${c.value} does not name ${c.doc} as its rubric, so the link cannot be confirmed from the PRD's side.`);
+      return V('verified');
+    }
+    case 'decision':
+    case 'adr_number': {
+      if (!ctx.decisions.available) return null;
+      return ctx.decisions.ids.has(c.value) ? V('verified', null, ctx.decisions.file)
+        : V('contradicted', `no decision D${c.value} in ${ctx.decisions.file || 'the decisions file'} or the ADR folder`, ctx.decisions.file,
+          c.kind === 'decision' ? `${c.doc} cites decision D${c.value}, which is not in the decisions file or the ADR folder.` : `${c.doc} is decision D${c.value}, which the decisions file does not record.`);
+    }
+    case 'adr_title': {
+      const m = /^\s*D0*(\d{1,3})\b/i.exec(c.value);
+      return m && Number(m[1]) === c.n ? V('verified') : V('contradicted', `the title is "${String(c.value).slice(0, 60)}"`, null, `${c.doc} is decision D${c.n}, but its title does not start with D${c.n}.`);
+    }
+    case 'story_ref': {
+      const rec = ctx.initiatives.get(c.value);
+      const prdRel = rec && rec.fm.prd_path ? norm(rec.fm.prd_path) : null;
+      const prd = prdRel ? ctx.docs.get(prdRel) : null;
+      if (!prd) return V('undecided', 'no PRD was found for this story', null, `${c.doc} cites ${c.subject}, but no PRD could be found for it to be checked against.`);
+      const have = prd.claims.some((x) => x.kind === 'req' && x.subject === c.subject);
+      if (!prd.claims.some((x) => x.kind === 'req')) return V('undecided', 'the PRD lists no requirement ids', prdRel, `${prdRel} lists no requirement ids, so ${c.subject} in ${c.doc} cannot be checked.`);
+      return have ? V('verified', null, prdRel) : V('contradicted', `${prdRel} has no requirement ${c.subject}`, prdRel, `${c.doc} cites requirement ${c.subject}, which ${prdRel} does not have.`);
+    }
+    default:
+      return null;
+  }
+}
+
+/** Sources a document derives from, as repo-relative paths: a rubric and a story from their PRD; a PRD from the
+ *  explainer and brief its initiative names. Used for the freshness rule and for finding dependents. */
+function derivesFrom(rel, ctx) {
+  const d = ctx.docs.get(rel);
+  if (!d) return [];
+  const t = d.cls.type;
+  const out = new Set();
+  const iid = idOf(d.body.initiative_id || d.fm.initiative_id);
+  const rec = iid ? ctx.initiatives.get(iid) : null;
+  if (t === 'Rubric') {
+    const rf = d.body.rubric_for ? firstLinkPath(rel, d.body.rubric_for) : null;
+    if (rf) out.add(rf); else if (rec && rec.fm.prd_path) out.add(norm(rec.fm.prd_path));
+  }
+  if (t === 'Story' && rec && rec.fm.prd_path) out.add(norm(rec.fm.prd_path));
+  if (t === 'PRD' && rec) for (const k of ['explainer_path', 'brief_path']) if (rec.fm[k]) out.add(norm(rec.fm[k]));
+  return Array.from(out).filter((p) => ctx.exists(p) && p !== rel);
+}
+
+function derivedClaims(rel, ctx) {
+  const out = [];
+  for (const src of derivesFrom(rel, ctx)) {
+    const mine = ctx.lastChange.get(rel), theirs = ctx.lastChange.get(src);
+    const claim = { doc: rel, kind: 'freshness', subject: src, text: `derives from ${src}`, refs: [src] };
+    let r;
+    if (mine == null || theirs == null) r = { status: 'verified', truth: null, source: src, sentence: null, note: 'no change times known' };
+    else if (theirs > mine + STALE_SECS) r = { status: 'stale', truth: `${src} changed ${date(theirs)}; this document last changed ${date(mine)}`, source: src, sentence: `${src} changed after ${rel} did (${date(theirs)} against ${date(mine)}). ${rel} may no longer agree with it.` };
+    else r = { status: 'verified', truth: null, source: src, sentence: null };
+    out.push({ claim, result: r });
+  }
+  return out;
+}
+
+/* ── the ledger: append-only events, folded by claim id ───────────────────────────────────────── */
+function foldLedger(file) {
+  const map = new Map();
+  let raw = '';
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return map; }
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    let e; try { e = JSON.parse(line); } catch { continue; }      // a torn line is skipped, never fatal
+    if (e && e.type === 'claim' && e.claim_id) map.set(e.claim_id, e);
+  }
+  return map;
+}
+const claimId = (c) => sha(c.doc + '|' + c.kind + '|' + c.subject).slice(0, 12);
+
+/* ── the cache (per-user runtime directory) ───────────────────────────────────────────────────── */
+function readJson(f, dflt) { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return dflt; } }
+function writeJson(f, v) {
+  try { fs.mkdirSync(path.dirname(f), { recursive: true }); const tmp = f + '.' + process.pid + '.tmp'; fs.writeFileSync(tmp, JSON.stringify(v)); fs.renameSync(tmp, f); }
+  catch { /* a cache that cannot be written only costs a full read next time */ }
+}
+
+/**
+ * Run one check.
+ *
+ * What the ledger holds: every claim that is NOT verified, and every change back to verified. A claim that
+ * verifies the first time it is seen is not written, because a first run over a large repository would otherwise
+ * put thousands of lines into a tracked file. How many claims verified, and what each document was compared with,
+ * is kept per document in the per-user cache and read back by `buildView`.
+ *
+ * @param {object} a
+ * @param {string} a.root          repository root
+ * @param {string} a.cacheDir      per-user runtime directory for this repository
+ * @param {string} a.ledgerFile    where claims.jsonl lives
+ * @param {boolean} [a.sweep]      re-verify every document (the periodic time-rule pass)
+ * @param {number} [a.now]
+ */
+async function check({ root, cacheDir, ledgerFile, sweep = false, now = Date.now() }) {
+  const scope = await listScope(root);
+  const stampsFile = path.join(cacheDir, 'stamps.json');
+  const indexFile = path.join(cacheDir, 'index.json');
+  const stamps = readJson(stampsFile, {});
+  const index = readJson(indexFile, {});
+  const nextStamps = {};
+  const changed = new Set();
+  const present = new Set(scope.files);
+  const fresh = new Map();                                        // rel → text, for files read this run
+  let reads = 0;
+
+  // 1 · read only what moved
+  for (const rel of scope.files) {
+    let st; try { st = fs.statSync(path.join(root, rel)); } catch { continue; }
+    if (!st.isFile() || st.size > MAX_DOC_BYTES) continue;
+    const prev = stamps[rel];
+    if (prev && prev.m === st.mtimeMs && prev.s === st.size && index[rel]) { nextStamps[rel] = prev; continue; }
+    let text; try { text = fs.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    reads++;
+    const h = sha(text);
+    nextStamps[rel] = { m: st.mtimeMs, s: st.size, h };
+    if (prev && prev.h === h && index[rel]) continue;               // touched, not changed
+    changed.add(rel);
+    fresh.set(rel, text);
+    index[rel] = { h };
+  }
+  const removed = Object.keys(index).filter((r) => !present.has(r) || !nextStamps[r]);
+  for (const r of removed) { changed.add(r); delete index[r]; }
+
+  // 2 · parse what changed; build the initiative records and the "named by" map
+  const files = scope.files.filter((r) => nextStamps[r] && index[r]);
+  for (const rel of fresh.keys()) {
+    const text = fresh.get(rel);
+    index[rel].fm = extOf(rel) === 'md' ? frontmatter(text) : {};
+    index[rel].body = extOf(rel) === 'md' ? bodyKeys(text) : {};
+  }
+  const initiatives = new Map();
+  const named = new Map();
+  for (const rel of files) {
+    const fm = index[rel].fm || {};
+    if (fm.type === 'Initiative' && fm.id) {
+      initiatives.set(fm.id, { rel, fm });
+      for (const key of ['prd_path', 'rubric_path', 'explainer_path', 'brief_path', 'doc_path']) {
+        if (fm[key]) { const p = norm(fm[key]); named.set(p, (named.get(p) || []).concat([{ role: key, id: fm.id }])); }
+      }
+    }
+  }
+
+  // 3 · classify and extract: changed files from their text; an unchanged file only if an initiative record now names it
+  const readText = (rel) => (fresh.has(rel) ? fresh.get(rel) : (() => { try { return fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return null; } })());
+  const extractNow = (rel, text) => {
+    const ent = index[rel];
+    ent.cls = classify({ rel, fm: ent.fm, text, named });
+    ent.claims = extract(rel, text, ent.cls, ent.fm, ent.body);
+    ent.claims.forEach((c) => { c.claim_id = claimId(c); });
+  };
+  for (const rel of files) {
+    const ent = index[rel];
+    if (fresh.has(rel) || !ent.cls) { const t = readText(rel); if (t != null) extractNow(rel, t); continue; }
+    const c2 = classify({ rel, fm: ent.fm, text: '', named });
+    if (c2.classified && c2.type !== ent.cls.type) { const t = readText(rel); if (t != null) { extractNow(rel, t); changed.add(rel); } }
+  }
+  const docs = new Map();
+  for (const rel of files) { const e = index[rel]; if (e && e.cls) docs.set(rel, { cls: e.cls, fm: e.fm, body: e.body, claims: e.claims || [] }); }
+
+  // 4 · truth sources and time
+  const dirty = await dirtyFiles(root);
+  const lastChange = await lastChanges(root, dirty);
+  const decisions = loadDecisions(root, files);
+  const ctx = { docs, initiatives, decisions, now, lastChange, exists: (r) => nextStamps[r] != null || fs.existsSync(path.join(root, r)) };
+
+  // 5 · who is affected: the changed files, the documents that cite them, and no others
+  const tokens = new Set();
+  for (const r of changed) {
+    tokens.add(r);
+    for (const [id, rec] of initiatives) if (rec.rel === r) tokens.add('init:' + id);
+  }
+  for (const [id] of initiatives) if (changed.has(initiatives.get(id).rel)) tokens.add('init:' + id);
+  if ((decisions.file && changed.has(decisions.file)) || Array.from(changed).some((r) => /(?:^|\/)adr\/d\d+-/i.test(r))) tokens.add('decisions');
+  const affected = new Set();
+  for (const [rel, d] of docs) {
+    if (sweep || changed.has(rel)) { affected.add(rel); continue; }
+    if (d.claims.some((c) => c.kind === 'time')) { affected.add(rel); continue; }     // the time rule is applied on every run
+    if (d.claims.some((c) => (c.refs || []).some((t) => tokens.has(t)))) { affected.add(rel); continue; }
+    if (derivesFrom(rel, ctx).some((s) => tokens.has(s))) affected.add(rel);
+  }
+
+  // 6 · verify the affected documents; append only what is not verified, or has changed back to verified
+  const folded = foldLedger(ledgerFile);
+  const guard = createSinkGuard({ sink: ledgerFile, what: 'claims' });
+  const events = [];
+  const seenIds = new Set();
+  const stamp = new Date(now).toISOString();
+  for (const rel of affected) {
+    const d = docs.get(rel);
+    const items = d.claims.map((c) => ({ claim: c, result: verifyClaim(c, ctx) })).filter((x) => x.result);
+    for (const x of derivedClaims(rel, ctx)) { x.claim.claim_id = claimId(x.claim); items.push(x); }
+    const compared = new Set();
+    for (const { claim, result } of items) {
+      seenIds.add(claim.claim_id);
+      for (const r of claim.refs || []) if (!r.startsWith('init:') && r !== 'decisions' && r !== rel && ctx.exists(r)) compared.add(r);
+      if (result.source && result.source !== rel) compared.add(result.source);
+      if (['decision', 'adr_number'].includes(claim.kind) && decisions.file) compared.add(decisions.file);
+      if (claim.kind === 'prd_initiative') { const rec = initiatives.get(claim.value); if (rec) compared.add(rec.rel); }
+      const prev = folded.get(claim.claim_id);
+      if (!prev && result.status === 'verified') continue;                     // verified on first sight: not written
+      if (prev && prev.status === result.status && (prev.truth || null) === (result.truth || null) && prev.text === claim.text && (prev.sentence || null) === (result.sentence || null)) continue;
+      events.push({
+        type: 'claim', claim_id: claim.claim_id, doc: rel, doc_type: d.cls.type, kind: claim.kind, subject: claim.subject, text: claim.text,
+        status: result.status, truth: result.truth || null, source: result.source || null, sentence: result.sentence || null,
+        as_of: lastChange.get(rel) ? new Date(lastChange.get(rel) * 1000).toISOString() : null, verified_at: stamp, at: stamp,
+      });
+    }
+    index[rel].v = { verified: items.filter((x) => x.result.status === 'verified').length, total: items.length, compared: Array.from(compared).sort(), at: stamp };
+  }
+  // a claim that is gone from an affected or removed document is withdrawn, not forgotten
+  for (const [id, e] of folded) {
+    if (e.status === 'withdrawn' || e.status === 'verified' || seenIds.has(id)) continue;
+    if (affected.has(e.doc) || removed.includes(e.doc)) events.push({ ...e, status: 'withdrawn', truth: null, sentence: null, verified_at: stamp, at: stamp });
+  }
+  let appended = 0;
+  try { for (const e of events) { guard.appendLine(ledgerFile, e); appended++; } }
+  catch (e) { return { ok: false, error: 'the claims could not be recorded — ' + String((e && e.message) || e).slice(0, 200) }; }
+
+  writeJson(stampsFile, nextStamps);
+  writeJson(indexFile, index);
+  const view = buildView({ ledgerFile, index, scope, now });
+  return { ok: true, ...view, run: { changed: changed.size, affected: affected.size, affected_docs: Array.from(affected).sort().slice(0, 200), appended, reads, sweep, files: files.length } };
+}
+
+/* ── the view: what the page shows, from the folded ledger and the per-document cache ─────────── */
+function buildView({ ledgerFile, index, scope, now = Date.now() }) {
+  const folded = foldLedger(ledgerFile);
+  const byDoc = new Map();
+  for (const e of folded.values()) {
+    if (e.status === 'withdrawn' || e.status === 'verified') continue;
+    if (!byDoc.has(e.doc)) byDoc.set(e.doc, []);
+    byDoc.get(e.doc).push(e);
+  }
+  const rank = { contradicted: 0, stale: 1, undecided: 2 };
+  const docsOut = [];
+  let problems = 0, stale = 0, undecided = 0, verified = 0, unclassified = 0, internalOnly = 0;
+  for (const [rel, ent] of Object.entries(index)) {
+    if (!ent.cls) continue;
+    const claims = (byDoc.get(rel) || []).sort((a, b) => rank[a.status] - rank[b.status]);
+    const cls = ent.cls;
+    const count = (st) => claims.filter((c) => c.status === st).length;
+    const v = ent.v || { verified: 0, compared: [] };
+    const entry = {
+      rel, type: cls.type, via: cls.via, classified: !!cls.classified,
+      references: REFERENCES[cls.type] || [],
+      compared_with: v.compared || [],
+      problems: count('contradicted'), stale: count('stale'), undecided: count('undecided'), verified: v.verified || 0,
+      findings: claims.slice(0, 30).map((c) => ({ kind: c.kind, status: c.status, sentence: c.sentence || c.text, truth: c.truth, source: c.source })),
+    };
+    docsOut.push(entry);
+    problems += entry.problems; stale += entry.stale; undecided += entry.undecided; verified += entry.verified;
+    if (!cls.classified) unclassified++;
+    else if (!REFERENCES[cls.type]) internalOnly++;
+  }
+  docsOut.sort((a, b) => (b.problems - a.problems) || (b.stale - a.stale) || (b.undecided - a.undecided) || a.rel.localeCompare(b.rel));
+  const checked = docsOut.length;
+  const verdict = !checked ? 'not-checked' : problems ? 'problems' : 'consistent';
+  return {
+    verdict,
+    counts: { documents: checked, problems, stale, undecided, verified, unclassified, internal_only: internalOnly, truncated: !!(scope && scope.truncated) },
+    docs: docsOut, as_of: new Date(now).toISOString(),
+  };
+}
+
+/** The current view without running a check: from the per-user cache and the folded ledger. */
+function readView({ cacheDir, ledgerFile, now = Date.now() }) {
+  const index = readJson(path.join(cacheDir, 'index.json'), null);
+  if (!index) return { verdict: 'not-checked', counts: { documents: 0, problems: 0, stale: 0, undecided: 0, verified: 0, unclassified: 0, internal_only: 0, truncated: false }, docs: [], as_of: null };
+  return buildView({ ledgerFile, index, scope: null, now });
+}
+
+module.exports = { readView, idOf, cleanValue, check, buildView, extract, verifyClaim, foldLedger, listScope, frontmatter, bodyKeys, resolveRef, rubricWeights, loadDecisions, STALE_SECS };