create-pmos 0.505.0 → 0.507.0

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 };

package/workspace/lib/decision-memory.js

@@ -0,0 +1,237 @@
+'use strict';
+/* decision-memory.js — Claude remembers every decision and why, and says so when a plan goes against one (decision memory, part 2).
+ *
+ * IT IS THE GRILL'S `decision` ANGLE, not a new feature. A grill run (lib/grill-runs.js, skill grill) reads the initiative's plan, PRD and
+ * open ✦, lists the decisions that stand (`pmos grill decisions`), and files a contradiction with `pmos grill find decision`. The finding
+ * waits under the initiative's ✦ like every grill finding: the PM keeps, drops or undoes it. It never blocks anything: no gate reads it.
+ *
+ * WHAT A RUN FILES (one JSON object):
+ *   { "decision": "D79", "quote": "<the decision's own words, verbatim>",
+ *     "plan": { "label": "Checkout PRD", "ref": "planning/prd/checkout-prd.md:42", "quote": "<the plan's words at that line, verbatim>" },
+ *     "conflict": "<how the plan goes against it, one line>", "recommend": "keep" | "change" | "drop", "next": "<one next step>",
+ *     "confidence": "high" | "medium", "rank"?: 1-9 }
+ *   keep    keep the decision: change the plan
+ *   change  the plan is right and the decision is old: write a new decision that amends it
+ *   drop    the decision no longer holds: write a new decision that supersedes it
+ *
+ * THE GUARDRAILS, before anything is shown (in this order; each refusal says why):
+ *   1. the switch      grill mode off, PMOS_DECISION_MEMORY=off, or the shared kill switch (lib/ai-guard.js off)
+ *   2. a live decision the decision is in the ledger (lib/decision-ledger.js) and still stands. A superseded or reverted decision is refused
+ *                      with the decision that replaced it, so Claude never pushes back with a dead decision
+ *   3. verbatim        the decision's quote is in its own text, and the plan's quote is at its ref (±2 lines); nothing is paraphrased
+ *   4. honest          confidence is high or medium. Low is left out: quiet by default. High needs both sides verified (2 refs)
+ *   5. replayed        the real supersede pairs replay through the same check (replayCases) and pass for this VERSION, else everything
+ *                      is held (lib/ai-guard.js ready/file)
+ *   6. audited         every filing, refusal and hold is one line of <state>/ai-audit.jsonl (lib/ai-guard.js audit)
+ *
+ *   JOB · VERSION · versionOf(L)
+ *   fileRun(o, bodies) → Promise<exit code>   what `pmos grill find decision` runs
+ *   offWhy(env) → '' | why                     this angle's own switch
+ *   checkFinding(L, input, { root, read }) → { prop } | { error }   PURE apart from reading the plan file at its ref
+ *   toGrill(prop, input) → the grill proposal for lib/proposals.js (group grill, type decision, section check)
+ *   replayCases(L, { root }) → [case]          the real supersede pairs as lib/ai-guard.js replay cases
+ *   pairsOf(L) → [{ newer, older }]            the supersede pairs the replay uses
+ *   plansIn(root, inis) → [{ ini, board, path, sig }]   each running initiative's PRD, for the grill's `plan` trigger
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const DL = require('./decision-ledger.js');
+
+const JOB = 'decision-memory';
+const VERSION = '1';
+const RECOMMEND = Object.freeze({ keep: 'Keep {D}: change the plan', change: 'Change {D}: write a decision that amends it', drop: 'Drop {D}: write a decision that supersedes it' });
+const LIM = { quote: 400, conflict: 200, next: 140, label: 80, ref: 300 };
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const one = (v, n) => String(v == null ? '' : v).replace(/\s+/g, ' ').trim().slice(0, n);
+const hash = (s) => crypto.createHash('sha1').update(String(s)).digest('hex').slice(0, 10);
+const flagOff = (v) => /^(off|0|false|no)$/i.test(String(v || '').trim());
+const offWhy = (env = process.env) => (flagOff(env.PMOS_DECISION_MEMORY) ? 'decision memory is off (PMOS_DECISION_MEMORY)' : '');
+
+/* path:line → { file, line } when it is a repository path; else null */
+function refOf(ref) {
+  const m = /^([^:\s][^:]*?):(\d+)$/.exec(String(ref || '').trim());
+  if (!m || path.isAbsolute(m[1]) || m[1].split(/[\\/]/).includes('..')) return null;
+  return { file: m[1], line: Number(m[2]) };
+}
+/* The quote is at the ref, within ±2 lines (case and white space ignored), as lib/ai-guard.js checks it. */
+function quoteAt(root, ref, quote, read) {
+  const r = refOf(ref); if (!r) return false;
+  let text; try { text = read(path.join(root, r.file)); } catch { return false; }
+  const lines = String(text).split('\n'), q = DL.norm(quote);
+  if (q.length < 12) return false;
+  const win = DL.norm(lines.slice(Math.max(0, r.line - 3), r.line + 2).join(' '));
+  return win.includes(q);
+}
+/* The source lib/ai-guard.js re-checks against the raw file: the raw text of the line the quote starts on (markdown kept, so the guard's
+ * own match is exact), at most 200 characters. The quote Claude wrote, checked with the markdown ignored, stays in `say`. */
+function rawSource(root, file, nearLine, quote, read) {
+  let lines = [];
+  try { lines = String(read(path.join(root, file))).split('\n'); } catch { return null; }
+  const head = DL.norm(quote).slice(0, 30);
+  for (let i = Math.max(0, nearLine - 3); i < Math.min(lines.length, nearLine + 2); i++) {
+    if (DL.norm(lines[i]).includes(head)) { const t = lines[i].trim().slice(0, 200).trim(); return t.length >= 12 ? { ref: `${file}:${i + 1}`, quote: t } : null; }
+  }
+  return null;
+}
+
+/** → { prop } | { error }. prop is the lib/ai-guard.js proposal shape. */
+function checkFinding(L, input, { root = '.', read = (f) => fs.readFileSync(f, 'utf8'), ini = '' } = {}) {
+  if (!L) return { error: 'no DECISIONS.md in this repository: there is nothing to check against' };
+  if (!isObj(input)) return { error: 'the finding is a JSON object' };
+  const id = /^D\d{2,3}$/.test(String(input.decision || '')) ? String(input.decision).replace(/^D(\d)$/, 'D0$1') : '';
+  const d = id && L.decisions.get(id);
+  if (!d) return { error: `decision is a D-id in the ledger (pmos grill decisions); "${one(input.decision, 20)}" is not` };
+  if (d.status === 'reverted') return { error: `${id} was reverted: it is not a decision to push back with` };
+  if (d.status === 'superseded') {
+    const now = DL.current(L, id);
+    return { error: `${id} was superseded by ${d.supersededBy.join(', ')}: check the plan against ${now.join(', ') || d.supersededBy.join(', ')} instead` };
+  }
+  const quote = one(input.quote, LIM.quote);
+  if (!DL.quoted(L, id, quote)) return { error: `quote is ${id}'s own words, verbatim (12 characters or more); it is not in ${id}` };
+  const plan = isObj(input.plan) ? input.plan : null;
+  if (!plan || !one(plan.label, LIM.label) || !refOf(plan.ref)) return { error: 'plan is { label, ref: "<path>:<line>", quote }: where the plan says it' };
+  const pquote = one(plan.quote, LIM.quote);
+  if (!quoteAt(root, plan.ref, pquote, read)) return { error: `plan.quote is not at ${one(plan.ref, 80)} (±2 lines): quote the plan's own words` };
+  const conflict = one(input.conflict, LIM.conflict);
+  if (!conflict) return { error: 'conflict is one line: how the plan goes against the decision' };
+  const rec = String(input.recommend || '');
+  if (!RECOMMEND[rec]) return { error: 'recommend is keep, change or drop' };
+  const next = one(input.next, LIM.next);
+  if (!next) return { error: 'next is the one next step the PM can take (it becomes a task on ✓)' };
+  const conf = String(input.confidence || '');
+  if (conf === 'low' || conf === 'none') return { error: 'low confidence is left out: file a contradiction only when you would bet on it' };
+  if (conf !== 'high' && conf !== 'medium') return { error: 'confidence is high or medium' };
+  const dline = DL.lineOf(L, id, quote), pr = refOf(plan.ref);
+  const dsrc = rawSource(root, d.path, dline, quote, read) || { ref: `${d.path}:${dline}`, quote };
+  const psrc = rawSource(root, pr.file, pr.line, pquote, read) || { ref: one(plan.ref, LIM.ref), quote: pquote };
+  const rank = Number.isInteger(input.rank) && input.rank >= 1 && input.rank <= 9 ? input.rank : 2;
+  const pfile = pr.file;
+  const prop = {
+    id: 'pr-' + hash([ini, 'grill', 'decision', id, pfile].join('|')),
+    title: one(`Earlier decision: ${conflict}`, 200),
+    say: one(`${id}${d.date ? ' (' + d.date + ')' : ''} says "${quote}". ${one(plan.label, LIM.label)} says "${pquote}". Keep ${id} and change the plan, change ${id}, or drop it. Claude suggests: ${RECOMMEND[rec].replace('{D}', id)}.`, 900),
+    confidence: conf,
+    claims: [
+      { text: `${id} · ${d.title}`, sources: [{ label: id, ...dsrc }] },
+      { text: conflict, sources: [{ label: one(plan.label, LIM.label), ...psrc }] },
+    ],
+    data: { angle: 'decision', decision: id, recommend: rec, next, rank, confidence: conf },
+  };
+  return { prop };
+}
+
+/** The grill proposal lib/proposals.js stores, from a checked prop. */
+function toGrill(prop) {
+  const d = prop.data;
+  return { id: prop.id, group: 'grill', type: 'decision', section: 'check', title: one(prop.title, 200), why: one(prop.say + ' Next: ' + d.next, 1100),
+    sources: prop.claims.flatMap((c) => c.sources.map((s) => ({ label: s.label, ref: s.ref }))), items: [], data: { ...d } };
+}
+
+/** The supersede pairs the replay uses: newer → older, both in the ledger. */
+const pairsOf = (L) => (L ? L.pairs.filter((p) => p.rel === 'supersedes').map((p) => ({ newer: p.newer, older: p.older })) : []);
+
+/* The first verbatim sentence of a decision's text that sits on one line (not a heading), for a replayed finding. */
+function firstQuote(d) {
+  for (const raw of d.text.split('\n').slice(1)) {
+    const t = raw.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1').replace(/^[\s>*-]+/, '').trim();
+    if (!t || /^#/.test(t) || t.length < 24) continue;
+    return ((t.match(/^.{24,}?[.;:](?=\s|$)/) || [t])[0]).slice(0, 160).trim();
+  }
+  return d.title;
+}
+
+/**
+ * The real supersede pairs as replay cases. For each pair (newer N supersedes older O) the replay files a recorded finding that a plan
+ * quoting N goes against O, twice:
+ *   before N   the ledger as it stood before N was added: O stands, so the finding is filed (Claude does push back)
+ *   after N    today's ledger: O is superseded, so the finding is refused and names N (Claude never pushes back with a dead decision)
+ * The plan side quotes N's own text at its own line, so the verbatim check is real too. No model is called.
+ */
+function replayCases(L, { root = '.', read } = {}) {
+  const cases = [];
+  const opts = { root, ...(read ? { read } : {}) };
+  // filed: the finding as a proposal. refused: nothing, and the refusal must name the decision that replaced it (else the case throws)
+  const filed = (led, f) => async () => { const r = checkFinding(led, f, opts); return r.prop ? [r.prop] : []; };
+  const refused = (led, f, names) => async () => {
+    const r = checkFinding(led, f, opts);
+    if (r.prop) return [r.prop];
+    if (!names.some((x) => r.error.includes(x))) throw new Error(`refused for another reason: ${r.error}`);
+    return [];
+  };
+  for (const { newer, older } of pairsOf(L)) {
+    const N = L.decisions.get(newer), O = L.decisions.get(older);
+    if (!N || !O) continue;
+    const pq = firstQuote(N), oq = firstQuote(O);
+    const finding = { decision: older, quote: oq, plan: { label: newer, ref: `${N.path}:${DL.lineOf(L, newer, pq)}`, quote: pq }, conflict: `${newer} goes against ${older}`, recommend: 'drop', next: `Record that ${newer} supersedes ${older}`, confidence: 'high' };
+    const before = DL.asOf(L, newer), was = before.decisions.get(older);
+    // an older decision already superseded before N (D64 replaced D24 before D66 did) is refused before N too, naming the earlier successor
+    if (was && was.status === 'superseded') cases.push({ name: `${newer} → ${older}: before ${newer}, ${older} was already superseded by ${was.supersededBy.join(', ')}`, run: refused(before, finding, was.supersededBy), expect: { none: true } });
+    else cases.push({ name: `${newer} → ${older}: before ${newer}, Claude pushes back`, run: filed(before, finding), expect: { filed: 1, cites: [O.path] } });
+    cases.push({ name: `${newer} → ${older}: after ${newer}, ${older} is not quoted as live`, run: refused(L, finding, [newer]), expect: { none: true } });
+  }
+  return cases;
+}
+
+/**
+ * Each running initiative's PRD and a signature of its text, for the grill's `plan` trigger (lib/grill-runs.js). The PRD is the record's
+ * `prd_path` (planning/initiatives/<id>.md); a record or PRD that cannot be read, or a path outside the repository, is left out.
+ * inis: [{ ini, board }] → [{ ini, board, path, sig }]
+ */
+function plansIn(root, inis, { read = (f) => fs.readFileSync(f, 'utf8') } = {}) {
+  const fmOf = require('./related-docs').frontmatter;
+  const out = [];
+  for (const x of inis || []) {
+    if (!x || !/^[A-Za-z0-9][\w.-]{0,120}$/.test(String(x.ini || ''))) continue;
+    let prd = '';
+    try { prd = String(fmOf(read(path.join(root, 'planning', 'initiatives', x.ini + '.md'))).prd_path || '').trim(); } catch { continue; }
+    if (!prd || path.isAbsolute(prd) || prd.split(/[\\/]/).includes('..')) continue;
+    let text; try { text = read(path.join(root, prd)); } catch { continue; }
+    out.push({ ini: x.ini, board: x.board || '', path: prd, sig: hash(text) });
+  }
+  return out;
+}
+
+/** The version the replay pass is recorded for: this module's VERSION and the supersede pairs it replays, so a new decision replays again. */
+const versionOf = (L) => VERSION + '-' + hash(JSON.stringify(pairsOf(L)));
+
+/**
+ * `pmos grill find decision`: check each finding, then hand the good ones to lib/ai-guard.js, which holds them until the replay of this
+ * version passed (the replay runs here when it has not), checks the evidence again, audits, and calls deliver. deliver appends the grill
+ * proposal to the initiative's ✦ ledger, as `pmos grill find` does for the other angles. → exit code: 0 filed or nothing to file, 1 refused.
+ * o: { root, file (proposals.jsonl), run, ini, board, env, now, say, P (the proposals fold), settingsDir (Settings, for the kill switch) }
+ */
+async function fileRun(o, bodies) {
+  const say = o.say || (() => {}), env = o.env || process.env;
+  const PR = require('./proposals.js'), AG = require('./ai-guard.js');
+  const off = offWhy(env); if (off) { say('✗ ' + off); return 1; }
+  const L = DL.load(o.root);
+  const stateDir = path.dirname(o.file), version = versionOf(L);
+  const props = []; let bad = 0;
+  for (const b of bodies) {
+    const c = checkFinding(L, b, { root: o.root, ini: o.ini });
+    if (c.error) { say('✗ refused: ' + c.error); bad++; try { AG.audit(stateDir, { job: JOB, version, run: o.run, event: 'dropped', why: c.error.slice(0, 200) }); } catch { /* the audit never stops a run */ } continue; }
+    props.push(c.prop);
+  }
+  if (!props.length) return bad ? 1 : 0;
+  if (!AG.ready(stateDir, JOB, version)) {
+    const rp = await AG.replay(JOB, version, replayCases(L, { root: o.root }), { root: o.root, stateDir });
+    if (!rp.ok) { say('✗ held: the replay of the real supersede pairs failed (' + rp.failed.slice(0, 3).map((f) => f.name + ': ' + f.why).join('; ') + '). Nothing is shown'); return 1; }
+  }
+  const P = o.P || PR.fold(PR.readLines(o.file)), kept = PR.keptIds(P);
+  const res = await AG.file({ job: JOB, version, run: o.run, root: o.root, stateDir, ...(o.settingsDir ? { settingsDir: o.settingsDir } : {}), env, max: 3 }, props, async (accepted) => {
+    for (const p of accepted) {
+      const g = toGrill(p);
+      if (P.drops.has(PR.sigOf(g))) { say(`dropped ${g.id}: the PM dropped this from the same evidence`); continue; }
+      if (kept.has(g.id)) { say(`kept ${g.id}: the PM kept it already`); continue; }
+      fs.appendFileSync(o.file, JSON.stringify({ at: new Date(o.now || Date.now()).toISOString(), by: null, kind: 'propose', ini: o.ini, board: o.board || '', run: o.run, ...g }) + '\n');
+      say(`filed ${g.id} · decision · ${g.title}`);
+    }
+  });
+  if (res.off) { say('✗ ' + res.off); return 1; }
+  if (res.held) { say('✗ held: the replay has not passed for this version. Nothing is shown'); return 1; }
+  for (const d of res.dropped || []) { say(`✗ refused ${d.id}: ${d.why}`); bad++; }
+  return bad ? 1 : 0;
+}
+
+module.exports = { JOB, VERSION, versionOf, fileRun, plansIn, RECOMMEND, offWhy, checkFinding, toGrill, replayCases, pairsOf, refOf, quoteAt, firstQuote };

package/workspace/lib/drift-cli.js

@@ -0,0 +1,98 @@
+'use strict';
+/* drift-cli.js — `pmos drift`: the weekly "What would I have missed" check from a terminal (initiative weekly-drift-check; lib/drift.js).
+ *
+ *   pmos drift show [--weeks <n>] [--json]   what the check would have shown for each of the last n weeks (default 4) of THIS repository.
+ *                                            It reads only and writes nothing.
+ *   pmos drift replay [--json]               the replay of the last 4 weeks of this repository's real records (PRD R6). It checks that no week
+ *                                            has more than three items and that every quote is at the line it cites, runs the shared guard's
+ *                                            replay (lib/ai-guard.js), and writes one replay line to your own ledger. This product's items show
+ *                                            on Home only after a replay that passed.
+ *   pmos drift status [--json]               the last weekly result and the replays on record.
+ *
+ * Run it in the product's repository. The weekly run itself needs no command: the server runs it each Monday. Nothing here changes a task,
+ * an initiative or a ticket, and nothing is sent. Exit codes: 0 done, 1 refused or the replay failed, 2 usage. */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const D = require('./drift.js');
+const R = require('./drift-runs.js');
+const Facts = require('./drift-facts.js');
+
+const COMMANDS = { drift: ['show', 'replay', 'status'] };
+const USAGE = [
+  'usage: pmos drift show|replay|status — the weekly check for quiet drift (What would I have missed)',
+  '  pmos drift show [--weeks <n>] [--json]   what each of the last n weeks (default 4) would have shown for this repository; writes nothing',
+  '  pmos drift replay [--json]               replay the last 4 weeks of this repository on its real records; its items show on Home only after this passes',
+  '  pmos drift status [--json]               the last weekly result and the replays on record',
+  'The weekly run starts by itself each Monday. Nothing is changed in a task, an initiative or Jira, and nothing is sent.',
+];
+
+function parse(args) {
+  const pos = [], flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (!a.startsWith('--')) { pos.push(a); continue; }
+    const k = a.slice(2);
+    if (k === 'json') flags.json = true;
+    else { flags[k] = args[i + 1] !== undefined && !String(args[i + 1]).startsWith('--') ? args[++i] : ''; }
+  }
+  return { pos, flags };
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; } catch { return cwd; }
+}
+const itemLine = (it) => `  ✦ ${it.title}\n    ${it.say}\n${it.claims.map((c) => '      · ' + c.text + ' [' + c.sources.map((s) => s.ref).join(', ') + ']').join('\n')}`;
+
+async function run(argv, { say = (s) => console.log(s), env = process.env, cwd = process.cwd(), now = Date.now(), runtime, product } = {}) {
+  const args = argv[0] === 'drift' ? argv.slice(1) : argv.slice();
+  const sub = args[0];
+  if (!sub || ['help', '--help', '-h'].includes(sub)) { for (const l of USAGE) say(l); return sub ? 0 : 1; }
+  if (!COMMANDS.drift.includes(sub)) { say(`unknown drift command "${sub}". Use one of: ${COMMANDS.drift.join(', ')}`); return 2; }
+  const { pos, flags } = parse(args.slice(1));
+  if (pos.length) { say(`✗ pmos drift ${sub} takes no argument`); return 2; }
+  for (const k of Object.keys(flags)) if (k !== 'json' && !(k === 'weeks' && sub === 'show')) { say(`✗ --${k} is not an option of pmos drift ${sub}`); return 2; }
+  const dir = D.dirOf(runtime || require('./state-root.js').defaultRoot({ env }));
+
+  if (sub === 'status') {
+    const F = D.read(dir), last = F.weeks[F.weeks.length - 1] || null;
+    const reps = F.replays.map((r) => ({ at: r.at, version: r.version, ws: r.ws, ok: r.ok, failed: (r.failed || []).length }));
+    if (flags.json) { say(JSON.stringify({ ok: true, version: D.VERSION, last, replays: reps })); return 0; }
+    say(last ? `Last week checked: the week of ${last.week} · ${last.items.length ? last.items.length + ' to look at' : 'quiet'}${last.held ? ' · held by the guard' : ''}` : 'No week checked yet.');
+    say(reps.length ? reps.map((r) => `Replay ${r.at} · ${r.version} · ${r.ok ? 'passed' : r.failed + ' failed'}`).join('\n') : 'No replay yet: run pmos drift replay in each product.');
+    return 0;
+  }
+
+  const root = repoRoot(cwd);
+  const p = product || (() => {
+    const stateDir = require('./driver.js').stateDirOf(root);
+    return { w: { id: require('./driver.js').wsIdOf(root), name: path.basename(root), root }, stateDir };
+  })();
+  if (!p.stateDir) { say('✗ this repository has no PMOS state folder (pmos/state, state or .pmos)'); return 1; }
+
+  if (sub === 'show') {
+    const n = flags.weeks === undefined ? R.REPLAY_WEEKS : Number(flags.weeks);
+    if (!Number.isInteger(n) || n < 1 || n > 12) { say('✗ --weeks is a whole number from 1 to 12'); return 2; }
+    const facts = [Facts.factsOf(p.w, { stateDir: p.stateDir, rows: p.rows })];
+    const weeks = R.simulate(facts, R.lastWeeks(now, n), { weeks: [], drops: D.read(dir).drops });
+    if (flags.json) { say(JSON.stringify({ ok: true, weeks: weeks.map((w) => ({ week: w.week, items: w.items })), notRead: facts[0].notRead })); return 0; }
+    for (const w of weeks) say(`Week of ${w.week}: ${w.items.length ? '' : 'quiet, nothing shown'}${w.items.length ? '\n' + w.items.map(itemLine).join('\n') : ''}`);
+    if (facts[0].notRead.length) say('Not read: ' + facts[0].notRead.join(', '));
+    return 0;
+  }
+
+  // replay
+  const rep = R.replay({ products: [p], now, F: D.read(dir) });
+  let guard = { ok: null, failed: [] };
+  let AG = null; try { AG = require('./ai-guard.js'); } catch { AG = null; }
+  if (AG) { try { guard = await R.guardReplay(AG, p, rep.weeks, rep.facts[0]); } catch (e) { guard = { ok: false, failed: [{ name: 'guard', why: String((e && e.message) || e).slice(0, 200) }] }; } }
+  else guard = { ok: false, failed: [{ name: 'guard', why: 'the shared guard (lib/ai-guard.js) is not installed, so nothing can show yet' }] };
+  const ok = rep.ok && guard.ok === true;
+  const failed = rep.failed.concat((guard.failed || []).map((f) => ({ week: f.name, why: f.why })));
+  D.append(dir, { kind: 'replay', version: D.VERSION, ws: [p.w.id], product: p.w.name, weeks: rep.weeks.map((w) => ({ week: w.week, ids: w.items.map((it) => it.id) })), ok, failed: failed.slice(0, 40) }, new Date(now).toISOString());
+  if (flags.json) { say(JSON.stringify({ ok, weeks: rep.weeks.map((w) => ({ week: w.week, items: w.items })), failed, notRead: rep.notRead })); return ok ? 0 : 1; }
+  for (const w of rep.weeks) say(`Week of ${w.week}: ${w.items.length ? '' : 'quiet, nothing shown'}${w.items.length ? '\n' + w.items.map(itemLine).join('\n') : ''}`);
+  if (rep.notRead.length) say('Not read: ' + rep.notRead.join(', '));
+  say(ok ? `✓ replay passed for ${p.w.name}: its items can show on Home from the next weekly run.` : `✗ replay did not pass for ${p.w.name}:\n` + failed.map((f) => '  - ' + (f.week ? f.week + ': ' : '') + f.why).join('\n'));
+  return ok ? 0 : 1;
+}
+
+module.exports = { run, COMMANDS, USAGE };