create-pmos 0.504.0 → 0.506.0

package/workspace/lib/ai-guard.js

@@ -0,0 +1,314 @@
+'use strict';
+/* ai-guard.js — THE ONE DOOR every AI job's output passes before the PM sees it (the AI-ideas round, 2026-11-03: decision memory,
+ * the weekly what-I'd-miss check, ask about the past, and the features after them). A job runs in the PM's usual background Claude
+ * session (lib/headless.js, as grill does). It may file only proposals, and each one goes through file() below:
+ *
+ *   kill switch → replay gate → check each proposal → audit → deliver(accepted)
+ *
+ * THE PROPOSAL (the only thing a job may file):
+ *   { id, title, say, confidence: 'high'|'medium'|'low'|'none',
+ *     claims: [{ text, sources: [{ label, ref, quote }] }], data? }
+ *   ref is `path:line` relative to the repository root, or `state:<file>:line` for a ledger in the job's state folder. Other refs
+ *   (`jira:KEY`, a URL) are kept as context but are unverified. confidence 'none' is "no record": claims may be empty, and that is a
+ *   valid, complete answer.
+ *
+ * THE RULES (check):
+ *   propose-only    a key named write, apply, ops, patch, send, command or exec anywhere in the proposal rejects it
+ *   every claim     at least 1 verified source: the quote (12+ characters) is found within ±2 lines of ref, case and spacing ignored
+ *   honest          'high' needs 2 or more distinct verified refs; 'none' must have no claims
+ *   bounded         at most `max` proposals per run (default 3); the rest are dropped, in the order given
+ *
+ * THE REPLAY GATE: a job's (job, version) shows nothing until replay() has passed for it. A replay runs the job's own cases (its
+ * deterministic part or a recorded model output, never the model) and the guard's negative cases made from the job's first filed
+ * proposal: a fabricated quote, a missing source, a ref outside the repository and a write key. Each of those must be dropped.
+ *
+ * THE KILL SWITCH: PMOS_AI=off (every job), PMOS_AI_<JOB>=off (one job, dashes as underscores), Settings 'ai.on' false, or the job
+ * in Settings 'ai.off'. `pmos ai off [job]` and `pmos ai on [job]` set the Settings ones.
+ *
+ * THE AUDIT: <stateDir>/ai-audit.jsonl, one line per event { at, job, version?, run?, event, ... }. Events: start, filed, dropped,
+ * held, off, replay, end. No line holds a file body or a key: only ids, refs, reasons and counts.
+ *
+ *   off(job, { env, settingsDir }) → null | reason
+ *   check(p, { root, stateDir }) → { ok, p, errors }
+ *   replay(job, version, cases, { root, stateDir }) → Promise<{ ok, failed: [{ name, why }] }>
+ *   ready(stateDir, job, version) → bool
+ *   file({ job, version, run, root, stateDir, settingsDir?, env?, max? }, proposals, deliver) → Promise<{ filed, dropped, held?, off? }>
+ *   audit(stateDir, line) · readAudit(stateDir, { job?, limit? }) → [line] · status({ stateDir, settingsDir, env }) → summary
+ *   setOff(settingsDir, job | null, off) → { ok } | { ok: false, error }
+ */
+const fs = require('fs');
+const path = require('path');
+
+const AUDIT = 'ai-audit.jsonl';
+const REPLAYS = 'ai-replays.json';
+const MAX = 3;
+const QUOTE_MIN = 12;
+const NEAR = 2;
+const CONF = ['high', 'medium', 'low', 'none'];
+const WRITE_KEYS = new Set(['write', 'apply', 'ops', 'patch', 'send', 'command', 'exec']);
+const JOB_ID = /^[a-z][a-z0-9-]{1,40}$/;
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/;
+
+const flagOff = (v) => /^(off|0|false|no)$/i.test(String(v == null ? '' : v).trim());
+const one = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
+const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\s+/g, ' ').trim();
+const envName = (job) => 'PMOS_AI_' + String(job).toUpperCase().replace(/-/g, '_');
+
+/* ── kill switch ─────────────────────────────────────────────────────────────────────────── */
+
+function settings(settingsDir) {
+  if (!settingsDir) return { on: true, off: [] };
+  try {
+    const S = require('./settings-store.js');
+    const offList = S.get(settingsDir, 'ai.off');
+    return { on: S.get(settingsDir, 'ai.on') !== false, off: Array.isArray(offList) ? offList : [] };
+  } catch { return { on: true, off: [] }; }
+}
+
+/** null when the job may run; else the reason it is off. */
+function off(job, { env = process.env, settingsDir = null } = {}) {
+  if (flagOff((env || {}).PMOS_AI)) return 'every AI job is off (PMOS_AI)';
+  if (job && flagOff((env || {})[envName(job)])) return `${job} is off (${envName(job)})`;
+  const s = settings(settingsDir);
+  if (!s.on) return 'every AI job is off (Settings)';
+  if (job && s.off.includes(job)) return `${job} is off (Settings)`;
+  return null;
+}
+
+function setOff(settingsDir, job, isOff) {
+  const S = require('./settings-store.js');
+  if (!job) return S.set(settingsDir, 'ai.on', !isOff);
+  if (!JOB_ID.test(String(job))) return { ok: false, error: `${JSON.stringify(String(job))} is not a job id (lowercase letters, digits and dashes)` };
+  const cur = settings(settingsDir).off.filter((x) => x !== job);
+  return S.set(settingsDir, 'ai.off', isOff ? [...cur, job].sort() : cur);
+}
+
+/* ── the citation check ──────────────────────────────────────────────────────────────────── */
+
+function linesOf(abs, cache) {
+  if (cache.has(abs)) return cache.get(abs);
+  let L = null;
+  try { const st = fs.statSync(abs); if (st.isFile() && st.size <= 20e6) L = fs.readFileSync(abs, 'utf8').split('\n'); } catch { /* unreadable: unverified */ }
+  cache.set(abs, L);
+  return L;
+}
+
+/** Where a ref points: { abs, line } for a verifiable ref, { context: true } for jira:/http refs, { error } otherwise. */
+function resolveRef(ref, { root, stateDir }) {
+  const r = String(ref || '').trim();
+  if (!r) return { error: 'a source has no ref' };
+  if (/^(https?:\/\/|jira:|slack:|mail:|calendar:)/i.test(r)) return { context: true };
+  const m = /^(state:)?(.+):(\d+)$/.exec(r);
+  if (!m) return { error: `ref ${JSON.stringify(one(r, 80))} is not path:line` };
+  const base = m[1] ? stateDir : root;
+  if (!base) return { error: `ref ${JSON.stringify(one(r, 80))} names a folder this run has none of` };
+  const baseAbs = path.resolve(base);
+  const abs = path.resolve(baseAbs, m[2]);
+  if (abs !== baseAbs && !abs.startsWith(baseAbs + path.sep)) return { error: `ref ${JSON.stringify(one(r, 80))} is outside the ${m[1] ? 'state folder' : 'repository'}` };
+  return { abs, line: Number(m[3]) };
+}
+
+function quoteAt(L, line, quote) {
+  const q = norm(quote);
+  if (!L || line < 1 || line > L.length) return false;
+  const from = Math.max(0, line - 1 - NEAR), to = Math.min(L.length, line + NEAR);
+  return norm(L.slice(from, to).join(' ')).includes(q);
+}
+
+function writeKey(v, depth = 0) {
+  if (!v || typeof v !== 'object' || depth > 8) return null;
+  for (const [k, x] of Object.entries(v)) {
+    if (WRITE_KEYS.has(String(k).toLowerCase())) return k;
+    const deep = writeKey(x, depth + 1);
+    if (deep) return deep;
+  }
+  return null;
+}
+
+/** Check one proposal. Pure apart from reading the cited files. → { ok, p (normalized), errors } */
+function check(p, { root, stateDir, cache = new Map() } = {}) {
+  const errors = [];
+  if (!p || typeof p !== 'object' || Array.isArray(p)) return { ok: false, p: null, errors: ['a proposal must be an object'] };
+  const wk = writeKey(p);
+  if (wk) errors.push(`propose-only: the key "${wk}" names a write`);
+  const id = String(p.id || '').trim();
+  if (!ID.test(id)) errors.push('id is missing or has characters other than letters, digits and . _ : -');
+  const title = one(p.title, 200), say = one(p.say, 1200);
+  if (!title) errors.push('title is empty');
+  if (!say) errors.push('say is empty');
+  const confidence = String(p.confidence || '').trim();
+  if (!CONF.includes(confidence)) errors.push(`confidence must be one of ${CONF.join(', ')}`);
+  const claimsIn = p.claims == null ? [] : p.claims;
+  if (!Array.isArray(claimsIn)) errors.push('claims must be a list');
+  const claims = [];
+  const verifiedRefs = new Set();
+  (Array.isArray(claimsIn) ? claimsIn : []).slice(0, 20).forEach((c, i) => {
+    const text = one(c && c.text, 600);
+    if (!text) { errors.push(`claim ${i + 1} has no text`); return; }
+    const srcIn = Array.isArray(c.sources) ? c.sources.slice(0, 8) : [];
+    if (!srcIn.length) { errors.push(`claim ${i + 1} cites no source`); return; }
+    const sources = [];
+    let verified = 0;
+    for (const s of srcIn) {
+      const ref = one(s && s.ref, 300), quote = String((s && s.quote) || '').slice(0, 2000), label = one(s && s.label, 120) || ref;
+      const at = resolveRef(ref, { root, stateDir });
+      if (at.error) { errors.push(`claim ${i + 1}: ${at.error}`); continue; }
+      if (at.context) { sources.push({ label, ref, quote: one(quote, 400), verified: false }); continue; }
+      if (norm(quote).length < QUOTE_MIN) { errors.push(`claim ${i + 1}: the quote for ${ref} is shorter than ${QUOTE_MIN} characters`); continue; }
+      if (!quoteAt(linesOf(at.abs, cache), at.line, quote)) { errors.push(`claim ${i + 1}: the quote is not at ${ref}`); continue; }
+      sources.push({ label, ref, quote: one(quote, 400), verified: true });
+      verifiedRefs.add(ref);
+      verified++;
+    }
+    if (!verified) { errors.push(`claim ${i + 1} has no verified source`); return; }
+    claims.push({ text, sources });
+  });
+  if (confidence === 'none' && Array.isArray(claimsIn) && claimsIn.length) errors.push('confidence none ("no record") must have no claims');
+  if (confidence && confidence !== 'none' && Array.isArray(claimsIn) && !claimsIn.length) errors.push('a proposal with claims must cite them; use confidence none for "no record"');
+  if (confidence === 'high' && verifiedRefs.size < 2) errors.push('confidence high needs 2 or more distinct verified sources');
+  const data = p.data && typeof p.data === 'object' && !Array.isArray(p.data) ? p.data : undefined;
+  if (errors.length) return { ok: false, p: null, errors };
+  return { ok: true, p: { id, title, say, confidence, claims, ...(data ? { data } : {}) }, errors: [] };
+}
+
+/* ── audit ───────────────────────────────────────────────────────────────────────────────── */
+
+function audit(stateDir, line) {
+  if (!stateDir) return;
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.appendFileSync(path.join(stateDir, AUDIT), JSON.stringify({ at: new Date().toISOString(), ...line }) + '\n', { mode: 0o600 });
+  } catch { /* the audit never stops a run; a failed append is lost, never thrown */ }
+}
+
+function readAudit(stateDir, { job = null, limit = 200 } = {}) {
+  let text = '';
+  try { text = fs.readFileSync(path.join(stateDir, AUDIT), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const s of text.split('\n')) {
+    if (!s.trim()) continue;
+    try { const o = JSON.parse(s); if (!job || o.job === job) out.push(o); } catch { /* a torn line */ }
+  }
+  return out.slice(-limit);
+}
+
+/* ── the replay gate ─────────────────────────────────────────────────────────────────────── */
+
+function readReplays(stateDir) {
+  try { const o = JSON.parse(fs.readFileSync(path.join(stateDir, REPLAYS), 'utf8')); return o && typeof o === 'object' ? o : {}; } catch { return {}; }
+}
+function writeReplays(stateDir, o) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  const f = path.join(stateDir, REPLAYS), tmp = f + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(o, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, f);
+}
+const keyOf = (job, version) => `${job}@${version}`;
+
+function ready(stateDir, job, version) {
+  const r = readReplays(stateDir)[keyOf(job, version)];
+  return !!(r && r.ok === true);
+}
+
+/* What the guard alone would file from a list: the same checks as file(), without the gate, audit or deliver. */
+function sift(list, opts) {
+  const cache = new Map(), filed = [], dropped = [];
+  const arr = Array.isArray(list) ? list : [];
+  for (const [i, p] of arr.entries()) {
+    const id = p && p.id ? String(p.id) : `#${i + 1}`;
+    if (filed.length >= (opts.max || MAX)) { dropped.push({ id, why: `over the ${opts.max || MAX} proposals a run may file` }); continue; }
+    const c = check(p, { ...opts, cache });
+    if (c.ok) filed.push(c.p); else dropped.push({ id, why: c.errors.join('; ') });
+  }
+  return { filed, dropped };
+}
+
+/* The guard's own negative cases, made from a proposal that passed. Each must be dropped. */
+function negatives(p) {
+  const clone = () => JSON.parse(JSON.stringify(p));
+  const first = (q) => q.claims[0].sources.find((s) => s.verified !== false) || q.claims[0].sources[0];
+  const out = [];
+  if (!p.claims || !p.claims.length) return out;
+  { const q = clone(); first(q).quote = 'this sentence was never written anywhere in the sources ' + Date.now(); out.push({ name: 'a fabricated quote is dropped', p: q }); }
+  { const q = clone(); q.claims[0].sources = []; out.push({ name: 'a claim with no source is dropped', p: q }); }
+  { const q = clone(); first(q).ref = '../../etc/passwd:1'; out.push({ name: 'a ref outside the repository is dropped', p: q }); }
+  { const q = clone(); q.data = { ...(q.data || {}), apply: { op: 'set' } }; out.push({ name: 'a write key is dropped', p: q }); }
+  return out;
+}
+
+function expectFails(name, expect, got) {
+  const e = expect || {};
+  if (e.none && got.filed.length) return `expected nothing filed, got ${got.filed.length}`;
+  if (Number.isInteger(e.filed) && got.filed.length !== e.filed) return `expected ${e.filed} filed, got ${got.filed.length}${got.dropped.length ? ' (dropped: ' + one(got.dropped.map((d) => d.why).join(' | '), 300) + ')' : ''}`;
+  if (Number.isInteger(e.min) && got.filed.length < e.min) return `expected at least ${e.min} filed, got ${got.filed.length}`;
+  if (Array.isArray(e.ids)) for (const id of e.ids) if (!got.filed.some((p) => p.id === id)) return `expected ${id} to be filed`;
+  if (Array.isArray(e.cites)) for (const c of e.cites) if (!got.filed.some((p) => p.claims.some((cl) => cl.sources.some((s) => s.verified && s.ref.split(':').slice(0, -1).join(':').replace(/^state:/, '') === c)))) return `expected a verified citation of ${c}`;
+  if (Array.isArray(e.dropped)) for (const sub of e.dropped) if (!got.dropped.some((d) => d.why.includes(sub))) return `expected a drop that says "${sub}"`;
+  return null;
+}
+
+/** Run a job's replay cases plus the guard's negatives; record the result for (job, version). */
+async function replay(job, version, cases, { root, stateDir, max = MAX } = {}) {
+  const failed = [];
+  let seed = null;
+  if (!JOB_ID.test(String(job || ''))) return { ok: false, failed: [{ name: 'job', why: 'the job id is not valid' }] };
+  if (!Array.isArray(cases) || !cases.length) failed.push({ name: '(cases)', why: 'a job needs at least 1 replay case' });
+  for (const c of Array.isArray(cases) ? cases : []) {
+    const name = one(c && c.name, 120) || '(unnamed)';
+    let list;
+    try { list = await c.run(); } catch (e) { failed.push({ name, why: 'the case threw: ' + one(e && e.message, 200) }); continue; }
+    const got = sift(list, { root, stateDir, max });
+    const why = expectFails(name, c.expect, got);
+    if (why) failed.push({ name, why });
+    if (!seed) seed = got.filed.find((p) => p.claims.length) || null;
+  }
+  if (seed) for (const n of negatives(seed)) {
+    const got = sift([n.p], { root, stateDir, max });
+    if (got.filed.length) failed.push({ name: n.name, why: 'the guard filed it' });
+  } else if (!failed.length) failed.push({ name: '(negatives)', why: 'no case filed a cited proposal, so the guard could not test its own drops; add a case that files one' });
+  const ok = !failed.length;
+  if (stateDir) {
+    const all = readReplays(stateDir);
+    all[keyOf(job, version)] = { ok, at: new Date().toISOString(), cases: (cases || []).length, failed: failed.slice(0, 20) };
+    try { writeReplays(stateDir, all); } catch { /* an unwritten pass keeps the gate shut: the safe side */ }
+    audit(stateDir, { job, version: String(version), event: 'replay', ok, failed: failed.map((f) => f.name + ': ' + one(f.why, 160)).slice(0, 10) });
+  }
+  return { ok, failed };
+}
+
+/* ── the door ────────────────────────────────────────────────────────────────────────────── */
+
+async function file(o, proposals, deliver) {
+  const { job, version, run = null, root, stateDir, settingsDir = stateDir, env = process.env, max = MAX } = o || {};
+  const base = { job, version: String(version), ...(run ? { run } : {}) };
+  if (!JOB_ID.test(String(job || ''))) return { filed: [], dropped: [], error: 'the job id is not valid' };
+  const why = off(job, { env, settingsDir });
+  if (why) { audit(stateDir, { ...base, event: 'off', why }); return { filed: [], dropped: [], off: why }; }
+  const list = Array.isArray(proposals) ? proposals : [];
+  if (!ready(stateDir, job, version)) {
+    audit(stateDir, { ...base, event: 'held', n: list.length, why: 'no passing replay for this version' });
+    return { filed: [], dropped: [], held: true };
+  }
+  const got = sift(list, { root, stateDir, max });
+  for (const d of got.dropped) audit(stateDir, { ...base, event: 'dropped', id: d.id, why: one(d.why, 400) });
+  if (!got.filed.length) { audit(stateDir, { ...base, event: 'end', filed: 0, dropped: got.dropped.length }); return { filed: [], dropped: got.dropped }; }
+  try { await deliver(got.filed); } catch (e) {
+    audit(stateDir, { ...base, event: 'end', filed: 0, dropped: got.dropped.length, error: 'deliver failed: ' + one(e && e.message, 200) });
+    return { filed: [], dropped: got.dropped, error: 'deliver failed' };
+  }
+  for (const p of got.filed) audit(stateDir, { ...base, event: 'filed', id: p.id, confidence: p.confidence, refs: p.claims.flatMap((c) => c.sources.map((s) => s.ref)).slice(0, 12) });
+  audit(stateDir, { ...base, event: 'end', filed: got.filed.length, dropped: got.dropped.length });
+  return { filed: got.filed.map((p) => p.id), dropped: got.dropped };
+}
+
+/** What `pmos ai status` shows: the switch, each job's replay state and its last run. */
+function status({ stateDir, settingsDir = stateDir, env = process.env } = {}) {
+  const s = settings(settingsDir), reps = readReplays(stateDir), lines = readAudit(stateDir, { limit: 2000 });
+  const jobs = {};
+  for (const [k, r] of Object.entries(reps)) { const [job, version] = k.split('@'); (jobs[job] = jobs[job] || { job }).replay = { version, ok: r.ok, at: r.at }; }
+  for (const l of lines) if (l.job && l.event === 'end') (jobs[l.job] = jobs[l.job] || { job: l.job }).last = { at: l.at, filed: l.filed, dropped: l.dropped };
+  for (const j of Object.values(jobs)) j.off = off(j.job, { env, settingsDir });
+  return { on: !flagOff((env || {}).PMOS_AI) && s.on, settingsOff: s.off, jobs: Object.values(jobs).sort((a, b) => a.job.localeCompare(b.job)) };
+}
+
+module.exports = { AUDIT, REPLAYS, MAX, QUOTE_MIN, off, setOff, check, replay, ready, file, audit, readAudit, status, envName, resolveRef };

package/workspace/lib/briefing-premium-agent.js

@@ -17,6 +17,7 @@ const headless = require('./headless.js');
 const Goal = require('./goal-chat.js');
 const ReportChat = require('./report-chat.js');
 const ProgramChat = require('./program-chat.js');
+const PastChat = require('./past-chat.js');
 const WorkflowChat = require('./workflow-chat.js');
 const IniChat = require('./initiative-chat.js');
 
@@ -221,6 +222,8 @@ function chat({ runtimeDir, key, text, model, context, sessions, wsId, iniInfo,
   if (cmd) { const b = Goal.begin({ runtimeDir, key, text: cmd.text, now }); if (b.error) return fail(400, b.error); msg = b.prompt; goal = b.id; }
   // D99: the New workflow chat (Settings › Workflows) carries the workflow rule on every message (lib/workflow-chat.js)
   else if (WorkflowChat.isKey(key) && !q.startsWith('/')) msg = WorkflowChat.wrap(q);
+  // ask-the-past: "why did we drop X?" in any chat carries the past rule: answer from `pmos past ask`, cite every line, "No record found" when none
+  else if (PastChat.isAsk(q)) msg = PastChat.wrap(q);
   // bug 2026-10-25: in a live initiative chat, a message about a stage, a workflow or a move carries the initiative's workflow and stage, read now
   else if (alive && /^init:/.test(key) && IniChat.isAsk(q)) msg = IniChat.wrap(q, info(), iniId(key));
   // premium-reports-from-chat R1: a message about a report, a chart or a dashboard carries the pmos-report rule (lib/report-chat.js)

package/workspace/lib/decision-ledger.js

@@ -0,0 +1,236 @@
+'use strict';
+/* decision-ledger.js — every locked decision, what it says, and whether it still stands (decision memory, part 1).
+ *
+ * PURE apart from load(): text in, ledger out. No model, no network. Same input → the same ledger.
+ *
+ * WHERE IT READS. DECISIONS.md: one decision per `### D<nn> — <title>` heading, its text until the next heading, and the dated
+ * `## Amendment log` lines ("- 2026-06-29 — Added D40 …"). ADR files (okf/products/pmos/adr/d<nn>-*.md) add their frontmatter typed keys
+ * `supersedes:` / `amended_by:` when they carry them.
+ *
+ * WHAT A RELATION IS. Only what the text says, clause by clause (a clause ends at `.`, `;` or a new line):
+ *   supersedes   "Supersedes D26 …", "supersedes D20's 3-consecutive rule", "drop the D79 decision", "D29 REVERTED"
+ *   superseded   "Superseded … by [D40]" written inside the older decision (the older one names its successor)
+ *   amends       "Amends D17", "D03 not superseded — amended", "narrows D38"
+ * A clause that says "No decision superseded", "supersedes nothing", "does not supersede", "without superseding" or "not superseded"
+ * makes no supersede edge (it may still make an `amends` edge). In the amendment log the clause belongs to the decision the line adds.
+ *
+ * STATUS. superseded when a later decision supersedes it, reverted when the log says so, amended when a later decision amends it,
+ * else active. A decision that is only partly superseded ("as the calibration standard") is still `superseded`: a pushback must quote the
+ * decision that replaced it, not the old one. `partial: true` says the rest of it still stands.
+ *
+ *   parse(text, { path }) → ledger { path, decisions: Map id → d, pairs: [{ newer, older, rel, line }] }
+ *     d: { id, n, title, line, end, text, date, status, partial, supersededBy: [], supersedes: [], amendedBy: [], amends: [] }
+ *   addAdr(ledger, { path, text })          the ADR frontmatter's typed keys, as more pairs
+ *   load(root, { fs }) → ledger | null      DECISIONS.md at the root, plus the ADR folder when it exists
+ *   asOf(ledger, id) → ledger               the ledger as it stood before decision `id` was added (it and every later one removed)
+ *   current(ledger, id) → [id]              the decisions that stand in for `id` now (itself when it is active)
+ *   quoted(ledger, id, quote) → bool        the quote is in that decision's text (case and white space ignored)
+ *   lineOf(ledger, id, quote) → line        the file line the quote starts on (for a path:line ref)
+ *   index(ledger, { all }) → [line]         one line per decision: "D40 · active · DECISIONS.md:159 · <title>"
+ */
+const path = require('path');
+
+const HEAD = /^###\s+(D(\d{2,3}))\s+[—–-]+\s+(.+?)\s*$/;
+const LOG_HEAD = /^##\s+Amendment log/i;
+const LOG_LINE = /^-\s+(\d{4}-\d{2}-\d{2})\s+[—–-]+\s+(.*)$/;
+const DID = /\bD(\d{2,3})\b/g;
+const NO_SUP = /\b(no (prior |p0 )?decision (is )?superseded|supersedes nothing|does not supersede|without superseding|not superseded|no decision is superseded|nothing superseded)\b/i;
+const norm = (s) => String(s || '').replace(/\]\([^)]*\)/g, ']').replace(/[*_`>#\[\]]/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+const idOf = (n) => 'D' + String(n).padStart(2, '0');
+const uniq = (a) => [...new Set(a)];
+
+/* Split a block of text into clauses with the line each starts on. */
+function clauses(lines, firstLine) {
+  const out = [];
+  lines.forEach((raw, i) => {
+    // drop markdown link targets so "[D40](#d40--…)" reads as "D40"
+    const t = String(raw).replace(/\]\([^)]*\)/g, ']').replace(/\*\*/g, '');
+    for (const c of t.split(/(?<=[.;])\s+|;\s*/)) if (c.trim()) out.push({ text: c, line: firstLine + i });
+  });
+  return out;
+}
+const idsIn = (s) => uniq([...String(s).matchAll(DID)].map((m) => idOf(m[1])));
+/* The ids named after a keyword in a clause (the words that follow it). */
+function after(clause, re) {
+  const m = re.exec(clause); if (!m) return [];
+  return idsIn(clause.slice(m.index + m[0].length));
+}
+
+/* The relations one clause states, for the decision `self`. → [{ newer, older, rel }] */
+function relationsOf(self, clause) {
+  const out = [];
+  // a parenthetical aside ("(the kit's contract, D54/D55, is unchanged)") and a tail after a dash are not what the clause decides
+  const c = String(clause).replace(/\((?:[^()]|\([^()]*\))*\)/g, ' ').split(/\s[—–]\s|\s--\s/)[0];
+  const neg = NO_SUP.test(c);
+  // "Superseded … by D40" — the older decision names its successor
+  const sb = /\bsuperseded\b[^.;]*?\bby\b/i.exec(c);
+  if (sb && !neg) for (const id of idsIn(c.slice(sb.index + sb[0].length)).slice(0, 1)) if (id !== self) out.push({ newer: id, older: self, rel: 'supersedes' });
+  if (!sb && !neg) {
+    for (const id of after(c, /\b(supersedes|supersede|replaces|retires|drops?)\b/i)) if (id !== self) out.push({ newer: self, older: id, rel: 'supersedes' });
+    // "D20 … is superseded" written in the newer decision
+    const sx = /\b(D\d{2,3})\b[^.;]{0,80}?\b(is|are)\s+\**superseded\b/i.exec(c);
+    if (sx && idOf(sx[1].slice(1)) !== self) out.push({ newer: self, older: idOf(sx[1].slice(1)), rel: 'supersedes' });
+    for (const m of c.matchAll(/\bdrop(?:s|ped)? the (D\d{2,3})\b/gi)) if (idOf(m[1].slice(1)) !== self) out.push({ newer: self, older: idOf(m[1].slice(1)), rel: 'supersedes' });
+  }
+  for (const id of after(c, /\b(amends|amended|narrows|widens)\b/i)) if (id !== self && !out.some((r) => r.older === id)) out.push({ newer: self, older: id, rel: 'amends' });
+  const am = /\b(D\d{2,3}) not superseded\s*[—–-]+\s*amended\b/i.exec(c);
+  if (am && idOf(am[1].slice(1)) !== self) out.push({ newer: self, older: idOf(am[1].slice(1)), rel: 'amends' });
+  return out;
+}
+
+function parse(text, { path: file = 'DECISIONS.md' } = {}) {
+  const lines = String(text || '').split('\n');
+  const decisions = new Map();
+  const pairs = [], dates = new Map();
+  let cur = null, inLog = false;
+  const close = (end) => { if (cur) { cur.end = end; cur.text = lines.slice(cur.line - 1, end).join('\n'); } };
+  const mk = (h, i) => ({ id: idOf(h[2]), n: Number(h[2]), title: h[3].trim(), path: file, line: i + 1, end: 0, text: '', date: '', status: 'active', partial: false, supersededBy: [], supersedes: [], amendedBy: [], amends: [] });
+  lines.forEach((l, i) => {
+    const h = HEAD.exec(l);
+    if (h) { close(i); cur = mk(h, i); if (!decisions.has(cur.id)) decisions.set(cur.id, cur); return; }
+    if (LOG_HEAD.test(l)) { close(i); cur = null; inLog = true; return; }
+    if (/^##\s/.test(l) && cur) { close(i); cur = null; }
+  });
+  close(lines.length);
+  // relations inside each decision's own text
+  for (const d of decisions.values()) {
+    for (const c of clauses(d.text.split('\n').slice(1), d.line + 1)) for (const r of relationsOf(d.id, c.text)) pairs.push({ ...r, line: c.line, where: d.path, clause: c.text });
+  }
+  // the amendment log: each line belongs to the decision it adds ("Added D40 …"); a "D29 REVERTED" line reverts it
+  if (inLog) {
+    const start = lines.findIndex((l) => LOG_HEAD.test(l));
+    for (let i = start + 1; i < lines.length; i++) {
+      // a log line may hold two entries run together ("… superseded.- 2026-06-29 — …"); split them
+      for (const part of lines[i].split(/(?<=\.)-\s+(?=\d{4}-\d{2}-\d{2})/)) {
+        const m = LOG_LINE.exec(part.startsWith('-') ? part : '- ' + part); if (!m) continue;
+        const date = m[1], body = m[2].replace(/\*\*/g, '');
+        const rv = /\b(D\d{2,3})\s+REVERTED\b/.exec(body);
+        if (rv) { const d = decisions.get(idOf(rv[1].slice(1))); if (d) { d.status = 'reverted'; d.revertedAt = date; } continue; }
+        const added = /\b(?:Added|Landed)\s+(D\d{2,3})\b/.exec(body);
+        if (!added) continue;
+        const self = idOf(added[1].slice(1)), d = decisions.get(self);
+        if (d && !d.date) d.date = date;
+        if (!d) dates.set(self, date);
+        // the parenthetical summary of what was added is not a relation; read the clauses after it
+        const rest = body.replace(/\((?:[^()]|\([^()]*\))*\)/g, ' ');
+        for (const c of clauses([rest], i + 1)) for (const r of relationsOf(self, c.text)) pairs.push({ ...r, line: i + 1, where: file, clause: c.text });
+      }
+    }
+  }
+  const L = finish({ path: file, decisions, pairs });
+  L.dates = dates;   // the log dates of decisions recorded only as an ADR, for addAdr
+  return L;
+}
+
+/* Dedupe the pairs, keep only pairs between known decisions where the newer one is newer, and set each decision's status. */
+function finish(L) {
+  const seen = new Set(), pairs = [], raw = L.raw || L.pairs;
+  for (const p of raw) {
+    const a = L.decisions.get(p.newer), b = L.decisions.get(p.older);
+    if (!a || !b || a.n <= b.n) continue;
+    const k = p.newer + '>' + p.older + ':' + p.rel;
+    // a supersede wins over an amend of the same pair
+    if (p.rel === 'amends' && seen.has(p.newer + '>' + p.older + ':supersedes')) continue;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    if (p.rel === 'supersedes') { const j = pairs.findIndex((q) => q.newer === p.newer && q.older === p.older && q.rel === 'amends'); if (j >= 0) pairs.splice(j, 1); }
+    pairs.push(p);
+  }
+  for (const d of L.decisions.values()) { d.supersededBy = []; d.supersedes = []; d.amendedBy = []; d.amends = []; if (d.status !== 'reverted') d.status = 'active'; d.partial = false; }
+  for (const p of pairs) {
+    const a = L.decisions.get(p.newer), b = L.decisions.get(p.older);
+    if (p.rel === 'supersedes') { a.supersedes.push(b.id); b.supersededBy.push(a.id); } else { a.amends.push(b.id); b.amendedBy.push(a.id); }
+  }
+  for (const d of L.decisions.values()) {
+    if (d.status === 'reverted') continue;
+    if (d.supersededBy.length) {
+      d.status = 'superseded';
+      // "superseded as the calibration standard", "the rule of D69 point 3": the rest of the decision still stands
+      d.partial = pairs.filter((p) => p.older === d.id && p.rel === 'supersedes').some((p) => /\b(as the|point \d|rule of|for pmos-self|still stand)/i.test(p.clause || ''));
+    } else if (d.amendedBy.length) d.status = 'amended';
+  }
+  return { path: L.path, decisions: L.decisions, pairs, raw, dates: L.dates };
+}
+
+/* ADR frontmatter: `supersedes: [okf/…/d20-….md]` or `amended_by: …` (one-line lists of paths or ids). */
+function addAdr(L, { path: file, text }) {
+  const self = /\/d(\d{2,3})-[^/]*\.md$/i.exec(String(file || ''));
+  if (!L || !self) return L;
+  const id = idOf(self[1]);
+  const fm = /^---\n([\s\S]*?)\n---/.exec(String(text || ''));
+  if (!fm) return L;
+  const more = [];
+  if (!L.decisions.has(id)) {
+    // a decision recorded only as its ADR (the DECISIONS.md body names it in the amendment log alone)
+    const all = String(text).split('\n'), start = fm[0].split('\n').length;
+    const t = /^title:\s*"?(.*?)"?\s*$/m.exec(fm[1]);
+    const title = (t ? t[1] : id).replace(/^D\d{2,3}\s*[—–-]+\s*/, '');
+    const d = { id, n: Number(self[1]), title, path: file, line: start + 1, end: all.length, text: all.slice(start).join('\n'), date: (L.dates && L.dates.get(id)) || (/^timestamp:\s*(\d{4}-\d{2}-\d{2})/m.exec(fm[1]) || [])[1] || '',
+      status: 'active', partial: false, supersededBy: [], supersedes: [], amendedBy: [], amends: [] };
+    L.decisions.set(id, d);
+    for (const c of clauses(d.text.split('\n'), d.line)) for (const r of relationsOf(id, c.text)) more.push({ ...r, line: c.line, where: file, clause: c.text });
+  }
+  for (const line of fm[1].split('\n')) {
+    const m = /^(supersedes|amended_by|amends):\s*(.*)$/.exec(line); if (!m) continue;
+    const ids = uniq([...m[2].matchAll(/\bd(\d{2,3})\b/gi)].map((x) => idOf(x[1])));
+    for (const o of ids) {
+      if (m[1] === 'supersedes') more.push({ newer: id, older: o, rel: 'supersedes', line: 1, where: file });
+      else if (m[1] === 'amends') more.push({ newer: id, older: o, rel: 'amends', line: 1, where: file });
+      else more.push({ newer: o, older: id, rel: 'amends', line: 1, where: file });
+    }
+  }
+  return finish({ ...L, raw: [...(L.raw || L.pairs), ...more] });
+}
+
+function load(root, { fs = require('fs') } = {}) {
+  const file = path.join(root, 'DECISIONS.md');
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+  let L = parse(text, { path: 'DECISIONS.md' });
+  const adr = path.join(root, 'okf', 'products', 'pmos', 'adr');
+  let names = [];
+  try { names = fs.readdirSync(adr).filter((n) => /^d\d{2,3}-.*\.md$/i.test(n)); } catch { names = []; }
+  for (const n of names) { try { L = addAdr(L, { path: 'okf/products/pmos/adr/' + n, text: fs.readFileSync(path.join(adr, n), 'utf8') }); } catch { /* an unreadable ADR adds nothing */ } }
+  return L;
+}
+
+/** The ledger as it stood before `id` was added: it and every later decision removed, the statuses read again. */
+function asOf(L, id) {
+  const cut = L.decisions.get(id); if (!cut) return L;
+  const decisions = new Map();
+  for (const [k, d] of L.decisions) if (d.n < cut.n) decisions.set(k, { ...d });
+  return finish({ path: L.path, decisions, raw: (L.raw || L.pairs).filter((p) => decisions.has(p.newer) && decisions.has(p.older)) });
+}
+
+/** The decisions that stand in for `id` now: itself when it stands, else what superseded it (followed to the end of the chain). */
+function current(L, id, seen = new Set()) {
+  const d = L.decisions.get(id); if (!d || seen.has(id)) return [];
+  seen.add(id);
+  if (d.status !== 'superseded') return [id];
+  return uniq(d.supersededBy.flatMap((n) => current(L, n, seen)));
+}
+
+function quoted(L, id, quote) {
+  const d = L.decisions.get(id), q = norm(quote);
+  return !!(d && q.length >= 12 && norm(d.text).includes(q));
+}
+function lineOf(L, id, quote) {
+  const d = L.decisions.get(id); if (!d) return 0;
+  const q = norm(quote).slice(0, 40);
+  const own = d.text.split('\n');
+  for (let i = 0; i < own.length; i++) if (norm(own[i]).includes(q)) return d.line + i;
+  return d.line;
+}
+
+function index(L, { all = false } = {}) {
+  const out = [];
+  for (const d of [...L.decisions.values()].sort((a, b) => a.n - b.n)) {
+    if (!all && (d.status === 'superseded' && !d.partial || d.status === 'reverted')) continue;
+    const note = d.status === 'superseded' ? ` (superseded by ${d.supersededBy.join(', ')}${d.partial ? '; the rest stands' : ''})`
+      : d.status === 'amended' ? ` (amended by ${d.amendedBy.join(', ')})` : d.status === 'reverted' ? ' (reverted)' : '';
+    out.push(`${d.id} · ${d.status} · ${d.path}:${d.line}${d.date ? ' · ' + d.date : ''} · ${d.title}${note}`);
+  }
+  return out;
+}
+
+module.exports = { parse, addAdr, load, asOf, current, quoted, lineOf, index, relationsOf, norm };