create-pmos 0.505.0 → 0.507.0

package/workspace/lib/past.js

@@ -0,0 +1,353 @@
+'use strict';
+/* past.js — ask PMOS about the past (initiative ask-the-past). THE ONE RETRIEVAL LAYER over what PMOS already wrote down about earlier
+ * choices: "why did we drop X?", "when did we decide Y?", and "did we decide this before?" for a new idea. lib/decision-ledger.js
+ * (decision memory) and the initiative chat both read through it; nobody writes a second matcher.
+ *
+ * PURE. Takes the text of the records and returns passages, each with the line it rests on. No filesystem, no git, no network, no model.
+ * Same input → the same output. lib/past-cli.js does the reading (`pmos past ask|check|verify`).
+ *
+ * WHAT IS AN ENTRY. One thing that was decided, rejected or recorded, cut where the file itself cuts it:
+ *   decision     DECISIONS.md, one `### Dnn — title` section                       id Dnn
+ *   amendment    DECISIONS.md, one dated bullet of the amendment log              ids: the D-ids it names
+ *   adr          okf/products/pmos/adr/dNN-*.md, the whole file                   id Dnn
+ *   pm-decision  pm-decisions.md, one `## YYYY-MM-DD — title` entry
+ *   out-of-scope planning/out-of-scope/*.md, the whole file (a declined request)
+ *   initiative   planning/initiatives/*.md, the record: its title, status, why
+ *   discovery    discoveries.md, one `## ` entry (the run log; weighs less)
+ *   meeting      a decision caught in a meeting note, not marked wrong or deleted  (records, from the per-user state folder)
+ *   claim        a Jev claim the claims ledger holds                               (records)
+ *   ticket       a Jira ticket draft                                               (records)
+ * A record that cannot be read is not an entry; the CLI says which sources it read and which were not on this machine.
+ *
+ * HOW A PASSAGE IS FOUND. Words, not similarity of meaning: the question's content words (stop words and question words out, a light
+ * stem) are scored BM25 over each entry, its title counting three times. "Drop", "reject", "retire", "remove", "decline" and their kin are
+ * one family, so "why did we drop X" finds "X was retired". A D-id in the question ("D66") finds that decision first. Nothing is inferred.
+ *
+ * HONEST CONFIDENCE. An answer's confidence is the share of the question's distinct content (by weight) that the best entry holds:
+ *   high    ≥ 0.75 of it, and a second entry agrees (≥ 0.5)
+ *   medium  ≥ 0.6
+ *   low     ≥ 0.45  (shown, with "a weak match")
+ *   none    under 0.45, or no content word at all → "No record found". It never guesses.
+ *
+ * WHAT A HIT IS. { kind, id?, path, line, title, date, quote, ref: 'path:line', score, cover, status?, supersededBy? }. `quote` is the
+ * line's own text, verbatim (cut at 220 characters), so lib/ai-guard.js check() finds it at `ref`. A superseded or amended decision says
+ * so (from lib/decision-ledger.js when present, else from the ADR's own `superseded_by` / `amended_by` keys): an answer never quotes a
+ * dead decision as live.
+ *
+ *   build(files, records?)        → corpus   files: [{ path, text }] (repository Markdown); records: [{ kind, ref, title, text, date, quote? }]
+ *   search(corpus, question, o)   → { hits: [hit], none, confidence, terms }   o: { limit = 5, kinds }
+ *   repeats(corpus, idea, o)      → { hits, none, confidence }   only what was decided or declined (not the run log); the shape decision
+ *                                   memory reads: [{ kind, path, line, quote, date, id?, score }], ranked, none: true when nothing passes
+ *   verify(corpus, text)          → { refs: [{ ref, ok, why? }], ok }   every `path:line` an answer cites is one the corpus holds
+ *   isPastAsk(text)               → whether a message asks about the past ("why did we…", "did we ever…", "what did we decide…")
+ *   statusOf(corpus, id)          → { status, supersededBy, amendedBy } for a D-id
+ */
+
+const STOP = new Set(('a an and are as at be been being but by can could did do does doing done for from had has have having how i if in into '
+  + 'is it its me my no not of on or our ours should so than that the their them then there these they this those to too us was we were '
+  + 'what when where which who whom whose why will with would you your yours ever again any some all about over also just very really '
+  + 'pmos decide decided decision decisions choose chose chosen pick picked go went make made said say says tell told know think thought '
+  + 'don doesn didn isn aren wasn weren won haven hasn cannot must every need needs '
+  + 'one two use used using get got thing things way still now new old before after earlier first last').split(' '));
+/* One family: a "why did we drop X" question meets the words the records use for it. */
+const FAMILY = {
+  drop: ['drop', 'dropp', 'retir', 'remov', 'reject', 'declin', 'deprecat', 'cut', 'kill', 'delet', 'revert', 'abandon', 'repeal', 'lift', 'out-of-scope', 'scrap', 'stop', 'supersed'],
+};
+const FAMILY_OF = new Map();
+for (const [k, list] of Object.entries(FAMILY)) for (const w of list) FAMILY_OF.set(w, k);
+const KIND_WEIGHT = { decision: 1.15, adr: 1.0, amendment: 0.95, 'pm-decision': 1.0, 'out-of-scope': 1.1, initiative: 0.85, meeting: 1.0, claim: 0.6, ticket: 0.7, discovery: 0.55 };
+const DECIDED = new Set(['decision', 'adr', 'amendment', 'pm-decision', 'out-of-scope', 'initiative', 'meeting']);
+const QUOTE_MAX = 220;
+const TITLE_X = 3;
+const K1 = 1.2, B = 0.75;
+const CONF = { high: 0.75, medium: 0.6, low: 0.45 };
+
+/** A light stem: enough that "retired", "retiring" and "retire" meet, never so much that two words merge. */
+function stem(w) {
+  let s = w;
+  if (s.length > 5 && s.endsWith('ies')) s = s.slice(0, -3) + 'y';
+  else if (s.length > 5 && /(ing|ion)$/.test(s)) s = s.slice(0, -3);
+  else if (s.length > 4 && s.endsWith('ed')) s = s.slice(0, -2);
+  else if (s.length > 4 && s.endsWith('es') && !s.endsWith('ses')) s = s.slice(0, -2);
+  else if (s.length > 3 && s.endsWith('s') && !s.endsWith('ss')) s = s.slice(0, -1);
+  if (s.length > 4 && s.endsWith('e')) s = s.slice(0, -1);
+  return s;
+}
+const fold = (t) => String(t == null ? '' : t).toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '');
+function words(t) { return fold(t).replace(/\bout of scope\b/g, 'out-of-scope').match(/[a-z0-9][a-z0-9-]*[a-z0-9]|[a-z0-9]/g) || []; }
+/** A word as the index holds it: a D-id stays whole ("d66"), a family word becomes its family, else its stem. */
+function termOf(w) {
+  const d = /^d0*(\d{2,3})$/.exec(w); if (d) return 'd' + d[1];
+  if (w === 'out-of-scope') return 'drop';
+  const s = stem(w);
+  for (const [root, fam] of FAMILY_OF) if (s === root || s.startsWith(root) && s.length - root.length <= 3) return fam;
+  return s;
+}
+function termsOf(text, { keepStop = false } = {}) {
+  const out = [];
+  for (const w of words(text)) {
+    if (w.includes('-')) { for (const p of w.split('-')) if (p && (keepStop || !STOP.has(p)) && p.length > 1) out.push(termOf(p)); if (w === 'out-of-scope') out.push('drop'); continue; }
+    if (!keepStop && STOP.has(w)) continue;
+    if (w.length < 2 && !/\d/.test(w)) continue;
+    out.push(termOf(w));
+  }
+  return out;
+}
+const did = (s) => { const m = /\bD0*(\d{2,3})\b/i.exec(String(s || '')); return m ? 'D' + (m[1].length < 2 ? '0' + m[1] : m[1]) : null; };
+const dids = (s) => [...new Set((String(s || '').match(/\bD\d{2,3}\b/g) || []))];
+const isoOf = (s) => { const m = /\b(20\d{2}-\d{2}-\d{2})\b/.exec(String(s || '')); return m ? m[1] : null; };
+
+/* ── frontmatter (one-line `key: value`, as lib/related-docs.js reads it) ── */
+function front(text) {
+  const m = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(String(text || ''));
+  if (!m) return { fm: {}, bodyLine: 1 };
+  const fm = {};
+  for (const l of m[1].split('\n')) { const k = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(l); if (k) fm[k[1]] = k[2].replace(/^["']|["']$/g, '').trim(); }
+  return { fm, bodyLine: m[0].split('\n').length };
+}
+
+/* ── cutting files into entries ── */
+function sections(path, text, re, make) {
+  const lines = String(text || '').split('\n');
+  const out = [];
+  let cur = null, fence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s{0,3}(```|~~~)/.test(lines[i])) fence = !fence;
+    const m = !fence && re.exec(lines[i]);
+    if (m) { if (cur) out.push(cur); cur = make(m, i + 1); if (cur) cur.lines = [lines[i]]; continue; }
+    if (cur) { if (/^#{1,2}\s/.test(lines[i]) && !fence) { out.push(cur); cur = null; continue; } cur.lines.push(lines[i]); }
+  }
+  if (cur) out.push(cur);
+  return out.map((e) => ({ ...e, path, text: e.lines.join('\n') }));
+}
+function wholeFile(path, text, kind, extra = {}) {
+  const { fm, bodyLine } = front(text);
+  const lines = String(text || '').split('\n');
+  const h1 = lines.findIndex((l, i) => i >= bodyLine - 1 && /^#\s+/.test(l));
+  const title = fm.title || (h1 >= 0 ? lines[h1].replace(/^#\s+/, '') : path.split('/').pop().replace(/\.md$/, ''));
+  return { kind, path, line: h1 >= 0 ? h1 + 1 : bodyLine, title, date: isoOf(fm.date) || isoOf(fm.timestamp), text: lines.slice(bodyLine - 1).join('\n'), lines: lines.slice(bodyLine - 1), from: bodyLine, fm, ...extra };
+}
+function entriesOf(file) {
+  const p = file.path, t = file.text;
+  if (p === 'DECISIONS.md') {
+    const dec = sections(p, t, /^###\s+(D\d{2,3})\s+[—–-]\s+(.+?)\s*$/, (m, line) => ({ kind: 'decision', id: m[1], title: m[1] + ' — ' + m[2], line, from: line }));
+    const amend = [];
+    const lines = String(t).split('\n');
+    const logAt = lines.findIndex((l) => /^##\s+Amendment log/i.test(l));
+    if (logAt >= 0) for (let i = logAt + 1; i < lines.length; i++) {
+      const m = /^-\s+(20\d{2}-\d{2}-\d{2})\s+[—–-]\s+(.+)$/.exec(lines[i]);
+      if (!m) continue;
+      const ids = dids(m[2]);
+      amend.push({ kind: 'amendment', id: ids[0] || null, ids, path: p, line: i + 1, from: i + 1, date: m[1], title: 'Amendment ' + m[1] + (ids.length ? ' (' + ids.join(', ') + ')' : ''), text: m[2], lines: [lines[i]] });
+    }
+    return dec.concat(amend);
+  }
+  if (p === 'pm-decisions.md') return sections(p, t, /^##\s+(20\d{2}-\d{2}-\d{2})\s+[—–-]\s+(.+?)\s*$/, (m, line) => ({ kind: 'pm-decision', title: m[2], date: m[1], line, from: line, ids: dids(m[2]) }));
+  if (p === 'discoveries.md') return sections(p, t, /^##\s+(.+?)\s*$/, (m, line) => ({ kind: 'discovery', title: m[1], date: isoOf(m[1]), line, from: line }));
+  let m = /^okf\/products\/pmos\/adr\/(d\d{2,3})[-.]/i.exec(p);
+  if (m) { const e = wholeFile(p, t, 'adr'); e.id = 'D' + m[1].slice(1).replace(/^0(?=\d{2})/, ''); return [e]; }
+  if (/^planning\/out-of-scope\/(?!README\.md$|index\.md$)[^/]+\.md$/.test(p)) {
+    const e = wholeFile(p, t, 'out-of-scope');
+    const dl = /^-\s*date:\s*(.+)$/m.exec(e.text); if (dl && !e.date) e.date = isoOf(dl[1]);
+    return [e];
+  }
+  if (/^planning\/initiatives\/[^/]+\.md$/.test(p) && !/\/(index|README)\.md$/.test(p)) {
+    const e = wholeFile(p, t, 'initiative');
+    e.id = e.fm.id || null; e.status = e.fm.status || '';
+    // the record's own words about where it stands count as text (a "status:" line often holds the why of a drop)
+    if (e.status) e.text = e.title + '\n' + e.status + '\n' + e.text;
+    return [e];
+  }
+  return [];
+}
+
+/* ── the index ── */
+function indexEntry(e) {
+  const tTerms = termsOf(e.title || ''), bTerms = termsOf(e.text || '');
+  const tf = new Map();
+  for (const w of tTerms) tf.set(w, (tf.get(w) || 0) + TITLE_X);
+  for (const w of bTerms) tf.set(w, (tf.get(w) || 0) + 1);
+  for (const x of e.ids || (e.id ? [e.id] : [])) { const k = 'd' + String(x).slice(1).replace(/^0(?=\d)/, ''); tf.set(k, (tf.get(k) || 0) + TITLE_X); }
+  e.tf = tf; e.len = tTerms.length * TITLE_X + bTerms.length;
+  return e;
+}
+
+/** files: [{ path, text }]; records: [{ kind, ref, title, text, date, quote?, line? }] from the per-user state folder. */
+function build(files, records = []) {
+  const entries = [];
+  const adrMeta = new Map();
+  for (const f of files || []) {
+    if (!f || typeof f.path !== 'string') continue;
+    for (const e of entriesOf(f)) entries.push(e);
+  }
+  for (const e of entries) if (e.kind === 'adr' && e.id) adrMeta.set(e.id, { superseded_by: e.fm.superseded_by || e.fm.supersededBy || '', amended_by: e.fm.amended_by || '', status: e.fm.status || '' });
+  for (const r of records || []) {
+    if (!r || !r.ref || !(r.text || r.title)) continue;
+    const m = /^(.*):(\d+)$/.exec(String(r.ref));
+    entries.push({ kind: r.kind || 'meeting', path: m ? m[1] : String(r.ref), line: m ? +m[2] : (r.line || 1), from: m ? +m[2] : 1, title: String(r.title || r.text).slice(0, 160), date: isoOf(r.date) || null,
+      text: String(r.text || ''), lines: [String(r.quote || r.text || '')], fixedQuote: r.quote || null, ids: dids(r.text) });
+  }
+  // decision status: lib/decision-ledger.js (decision memory) when it is here, else the ADR's own keys
+  let ledger = null;
+  try {
+    const DL = require('./decision-ledger.js');
+    const dec = (files || []).find((f) => f && f.path === 'DECISIONS.md');
+    if (DL && typeof DL.parse === 'function' && dec) {
+      ledger = DL.parse(dec.text, { path: 'DECISIONS.md' });
+      if (typeof DL.addAdr === 'function') for (const f of files || []) if (f && /^okf\/products\/pmos\/adr\//.test(f.path)) DL.addAdr(ledger, f);
+    }
+  } catch { ledger = null; }
+  const status = new Map();
+  if (ledger && ledger.decisions instanceof Map) for (const d of ledger.decisions.values()) status.set(d.id, { status: d.status || 'active', supersededBy: d.supersededBy || [], amendedBy: d.amendedBy || [], ...(d.partial ? { partial: true } : {}) });
+  // the ADR's own keys fill in what the ledger does not say (or stand alone when there is no ledger)
+  for (const [id, a] of adrMeta) {
+    const sup = dids(a.superseded_by), am = dids(a.amended_by), had = status.get(id);
+    if (had && had.status !== 'active') continue;
+    const st = sup.length || /supersed|revert/i.test(a.status) ? 'superseded' : am.length ? 'amended' : 'active';
+    if (had && st === 'active') continue;
+    status.set(id, { status: st, supersededBy: sup, amendedBy: am });
+  }
+  for (const e of entries) indexEntry(e);
+  const df = new Map();
+  for (const e of entries) for (const w of e.tf.keys()) df.set(w, (df.get(w) || 0) + 1);
+  const avg = entries.reduce((s, e) => s + e.len, 0) / Math.max(1, entries.length);
+  const lineSet = new Map();
+  const recPaths = new Set(entries.map((e) => e.path));
+  for (const f of files || []) if (f && typeof f.path === 'string' && recPaths.has(f.path)) lineSet.set(f.path, String(f.text || '').split('\n').length);
+  for (const r of records || []) if (r && r.ref) { const m = /^(.*):(\d+)$/.exec(String(r.ref)); const p = m ? m[1] : String(r.ref); lineSet.set(p, Math.max(lineSet.get(p) || 0, m ? +m[2] + 2 : 3)); }
+  const kinds = {};
+  for (const e of entries) kinds[e.kind] = (kinds[e.kind] || 0) + 1;
+  return { entries, df, avg, n: entries.length, status, lineSet, kinds, ledger: !!ledger };
+}
+
+const idf = (C, w) => { const n = C.df.get(w) || 0; return Math.log(1 + (C.n - n + 0.5) / (n + 0.5)); };
+function bm25(C, e, q) {
+  let s = 0;
+  for (const w of q) {
+    const f = e.tf.get(w); if (!f) continue;
+    s += idf(C, w) * (f * (K1 + 1)) / (f + K1 * (1 - B + B * e.len / C.avg));
+  }
+  return s;
+}
+/** The line of the entry that holds most of the question (by weight): its own number and its own words. */
+function bestLine(C, e, q, at = 0) {
+  if (e.fixedQuote) return { line: e.line, quote: clip(e.fixedQuote) };
+  let best = { line: e.line, quote: clip((e.lines || [])[0] || e.title), w: -1 };
+  const ls = e.lines || [];
+  for (let i = at; i < Math.min(ls.length, at + WINDOW); i++) {
+    const raw = ls[i]; if (!raw || !raw.trim() || /^---\s*$/.test(raw)) continue;
+    const have = new Set(termsOf(raw));
+    let w = 0; for (const t of q) if (have.has(t)) w += idf(C, t);
+    if (w > best.w + 1e-9) best = { line: e.from + i, quote: clip(raw), w };
+  }
+  return best;
+}
+function clip(s) {
+  let t = String(s == null ? '' : s).trim().replace(/^[-*>#\s]+/, '').trim();
+  if (t.length > QUOTE_MAX) { t = t.slice(0, QUOTE_MAX); const sp = t.lastIndexOf(' '); if (sp > QUOTE_MAX * 0.6) t = t.slice(0, sp); }
+  return t;
+}
+
+const WINDOW = 4;
+/** The terms of the entry's title, joined with the best run of WINDOW lines (by how many of the question's terms it holds). */
+function local(e, q) {
+  const title = new Set(termsOf(e.title || ''));
+  for (const x of e.ids || (e.id ? [e.id] : [])) title.add('d' + String(x).slice(1).replace(/^0(?=\d)/, ''));
+  const ls = e.lines || [];
+  const per = ls.map((l) => new Set(termsOf(l)));
+  let best = { n: -1, terms: title, at: 0 };
+  for (let i = 0; i < Math.max(1, per.length); i++) {
+    const u = new Set(title);
+    for (let j = i; j < Math.min(per.length, i + WINDOW); j++) for (const t of per[j]) u.add(t);
+    let n = 0; for (const t of q) if (u.has(t)) n++;
+    if (n > best.n) best = { n, terms: u, at: i };
+  }
+  return best;
+}
+
+function statusOf(C, id) { return (C && C.status && C.status.get(id)) || null; }
+
+function rank(C, text, { limit = 5, kinds = null } = {}) {
+  const all = termsOf(text);
+  const q = [...new Set(all)];
+  if (!q.length) return { hits: [], none: true, confidence: 'none', terms: [] };
+  // the weight of what was asked: the family word counts less than the subject (it says how, not what)
+  const wq = (t) => idf(C, t) * (t === 'drop' ? 0.35 : 1);
+  const total = q.reduce((s, t) => s + wq(t), 0) || 1;
+  const asked = new Set(q.filter((t) => /^d\d{2,3}$/.test(t)));
+  const scored = [];
+  for (const e of C.entries) {
+    if (kinds && !kinds.has(e.kind)) continue;
+    let s = bm25(C, e, q);
+    if (!s) continue;
+    s *= (KIND_WEIGHT[e.kind] || 0.8);
+    // a D-id the question names finds that decision first
+    if (asked.size && [...(e.ids || (e.id ? [e.id] : []))].some((d) => asked.has('d' + String(d).slice(1).replace(/^0(?=\d)/, '')))) s *= 2.5;
+    scored.push({ e, s });
+  }
+  scored.sort((a, b) => b.s - a.s);
+  // what the question asks must sit TOGETHER: in the title, or within a few lines of each other (a long record that names each word
+  // somewhere is not an answer). The cover is that local share, and it is what the confidence reads.
+  const pool = scored.slice(0, 60);
+  for (const x of pool) {
+    const L = local(x.e, q);
+    let have = 0; for (const t of q) if (L.terms.has(t)) have += wq(t);
+    x.cover = have / total; x.verb = !q.includes('drop') || L.terms.has('drop'); x.at = L.at;
+    x.s *= (0.4 + x.cover) * (x.verb ? 1 : 0.85);
+  }
+  scored.length = 0;
+  scored.push(...pool);
+  scored.sort((a, b) => b.s - a.s || String(a.e.path).localeCompare(String(b.e.path)) || a.e.line - b.e.line);
+  // one hit per decision: the section, its ADR and its amendment lines are the same decision; keep the best of each, then the next one
+  const seen = new Set(), hits = [];
+  for (const x of scored) {
+    const key = x.e.kind === 'amendment' ? x.e.path + ':' + x.e.line : (x.e.id && (x.e.kind === 'decision' || x.e.kind === 'adr') ? 'D:' + x.e.id : x.e.path + ':' + x.e.line);
+    if (seen.has(key)) continue; seen.add(key);
+    const b = bestLine(C, x.e, q, x.at);
+    const st = x.e.id && (x.e.kind === 'decision' || x.e.kind === 'adr') ? statusOf(C, x.e.id) : null;
+    hits.push({ kind: x.e.kind, ...(x.e.id ? { id: x.e.id } : {}), path: x.e.path, line: b.line, ref: x.e.path + ':' + b.line, title: x.e.title, date: x.e.date || null, quote: b.quote,
+      score: Math.round(x.s * 1000) / 1000, cover: Math.round(x.cover * 100) / 100, ...(x.verb ? {} : { dropSaid: false }), ...(x.e.kind === 'initiative' && x.e.status ? { recordStatus: clip(x.e.status) } : {}),
+      ...(st && st.status !== 'active' ? { status: st.status, supersededBy: st.supersededBy, amendedBy: st.amendedBy, ...(st.partial ? { partial: true } : {}) } : {}) });
+    if (hits.length >= limit) break;
+  }
+  const top = hits[0];
+  let confidence = 'none';
+  if (top) {
+    if (top.dropSaid === false && top.cover >= CONF.low) confidence = 'low';
+    else if (top.cover >= CONF.high && hits.slice(1).some((h) => h.cover >= 0.5)) confidence = 'high';
+    else if (top.cover >= CONF.medium) confidence = 'medium';
+    else if (top.cover >= CONF.low) confidence = 'low';
+  }
+  const none = confidence === 'none';
+  return { hits: none ? [] : hits.filter((h) => h.cover >= CONF.low * 0.8), none, confidence, terms: q };
+}
+
+/** "why did we drop X?" → the passages that answer it, best first. */
+function search(C, question, o = {}) { return rank(C, question, { limit: o.limit || 5, kinds: o.kinds ? new Set(o.kinds) : null }); }
+
+/** A new idea → what was decided or declined about it before. The run log is not a decision; an idea is long, so it is cut to its
+ *  12 most telling words first (the words rarest across the records), and the bar is the same honest one. */
+function repeats(C, idea, o = {}) {
+  // a word no record holds still counts (rarest of all): an idea made of new words is not a repeat, however well one old word matches
+  const q = [...new Set(termsOf(idea))].sort((a, b) => idf(C, b) - idf(C, a) || a.localeCompare(b)).slice(0, o.words || 12);
+  const r = rank(C, q.join(' '), { limit: o.limit || 5, kinds: new Set(o.kinds || [...DECIDED]) });
+  return { hits: r.hits, none: r.none, confidence: r.confidence, terms: r.terms };
+}
+
+/** Every `path:line` an answer cites must be one the records hold, at a line that exists. */
+function verify(C, text) {
+  const refs = [];
+  const re = /(?:^|[\s(`[])((?:state:)?[A-Za-z0-9_./-]+\.(?:md|jsonl|json)):(\d+)\b/g;
+  let m;
+  while ((m = re.exec(String(text || '')))) {
+    const p = m[1].replace(/^\.\//, ''), line = +m[2];
+    const n = C.lineSet.get(p);
+    refs.push(n == null ? { ref: p + ':' + line, ok: false, why: 'not a record PMOS read' } : line < 1 || line > n ? { ref: p + ':' + line, ok: false, why: 'that line is not in the file' } : { ref: p + ':' + line, ok: true });
+  }
+  return { refs, ok: refs.length > 0 && refs.every((r) => r.ok) };
+}
+
+const ASK_RE = /(\bwhy (did|didn'?t|had) (we|i|you|pmos|the team)\b|\bwhy (was|were) .{1,80}\b(dropped|rejected|retired|removed|declined|chosen|picked|stopped|cut|killed|reverted|deprecated|decided|added|made|changed)\b|\bwhy (did|do) we (ever )?(decide|choose|pick|drop|stop|reject|retire|remove)\b|\bwhen did (we|i|you|pmos)\b|\bdid (we|i|you) (ever|already|decide|drop|try|reject|retire)\b|\bha(ve|s) (we|i|you|pmos) (ever|already) (decided|dropped|tried|rejected|retired|discussed|done)\b|\bwhat did (we|i|you) decide\b|\b(we|i) decided (this|that|it) before\b|\bis (this|that|it) a repeat\b|\bask (pmos )?(about )?the past\b)/i;
+const isPastAsk = (text) => { const s = String(text == null ? '' : text).trim(); return !s.startsWith('/') && ASK_RE.test(s); };
+
+module.exports = { build, search, repeats, verify, isPastAsk, statusOf, termsOf, stem, entriesOf, CONF, KIND_WEIGHT, QUOTE_MAX };

package/workspace/lib/pmos-verbs.js

@@ -56,6 +56,9 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): briefing-source-flow added it through the same table.
   source: Object.freeze({ module: 'source-cli.js', run: null, guide: 'data-freshness.md',
     help: 'pmos source save|status|show — the stored read of each tool the Briefing uses: Mail, Slack, Confluence and the rest (pmos source help)' }),
+  // Not a pm-os-absorb verb (run: null): ask-the-past added it through the same table.
+  past: Object.freeze({ module: 'past-cli.js', run: null, guide: 'ask-the-past.md',
+    help: 'pmos past ask|check|verify|sources … — why did we decide or drop something: the records that say so, each with its line (pmos past help)' }),
   // Not a pm-os-absorb verb (run: null): Home's Mentions A+ (premium-agreed-design) added it through the same table.
   mention: Object.freeze({ module: 'mention-cli.js', run: null, guide: 'home.md',
     help: 'pmos mention list|draft — Home\'s Mentions: what waits on you, and the proposed reply Claude changes from a chat (pmos mention help)' }),
@@ -78,6 +81,12 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): feedback batch 12 items 2, 3 and 4 (Claude proposes, the one ✦) added it through the same table.
   propose: Object.freeze({ module: 'propose-cli.js', run: null, guide: 'claude-proposes.md',
     help: 'pmos propose look|found|date|done|name|status … — what Claude\'s run files under an initiative\'s ✦ for the PM to keep or drop (pmos propose help)' }),
+  // Not a pm-os-absorb verb (run: null): the AI-ideas round (2026-11-03) added it through the same table: the kill switch and audit of lib/ai-guard.js.
+  ai: Object.freeze({ module: 'ai-cli.js', run: null, guide: 'claude-proposes.md',
+    help: 'pmos ai status|off|on|log … — the AI jobs: their kill switch, replay state and audit (pmos ai help)' }),
+  // Not a pm-os-absorb verb (run: null): the AI-ideas round (2026-11-03, feature 5, plan-rehearsal) added it through the same table.
+  rehearse: Object.freeze({ module: 'rehearse-cli.js', run: null, guide: 'rehearse.md',
+    help: 'pmos rehearse move|end|cut|log … — what a change would break or help in other initiatives, goals and dates, before the PM approves it (pmos rehearse help)' }),
   // Not a pm-os-absorb verb (run: null): Grill and Forecast part G-A (Claude grills an initiative by itself) added it through the same table.
   grill: Object.freeze({ module: 'grill-cli.js', run: null, guide: 'claude-proposes.md',
     help: 'pmos grill find|voices|status|mode|cap|spend … — what Claude\'s grill run files under an initiative\'s ✦, and when it grills and what it may spend (pmos grill help)' }),
@@ -87,6 +96,9 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): batch 16 item 7 (Your impact) added it through the same table.
   impact: Object.freeze({ module: 'impact-cli.js', run: null, guide: 'your-impact.md',
     help: 'pmos impact add|end|status … — what Claude\'s impact run files for you to check, ✓ real or ✕ not real (pmos impact help)' }),
+  // Not a pm-os-absorb verb (run: null): initiative weekly-drift-check added it through the same table.
+  drift: Object.freeze({ module: 'drift-cli.js', run: null, guide: 'what-you-missed.md',
+    help: 'pmos drift show|replay|status — the weekly check for quiet drift: what it would show, its replay on your real records, and its last result (pmos drift help)' }),
   driver: Object.freeze({ module: 'driver-cli.js', run: null, guide: 'initiative-driver.md',
     help: 'pmos driver propose|status|keep|return|drop|pause|resume|mode … — the Initiative Driver: drafts for you to keep, send back or drop (pmos driver help)' }),
   // Not a pm-os-absorb verb (run: null): initiative horizon-scan added it through the same table; horizon-scan-portfolio added section, propose, setting and --boards.

package/workspace/lib/proposal-runs.js

@@ -71,6 +71,7 @@ function create(deps) {
   const active = new Map();   // run → { ws, ini, dir, session, why }
   const warn = deps.warn || (() => {});
   const lastScan = new Map(); // ws → ms of the last morning-check scan
+  const pastSeen = new Set(); // ws|initiative: the "You decided this before" look ran (ask-the-past)
 
   function ended(run, r, now = Date.now()) {
     const a = active.get(run); if (!a) return;
@@ -170,6 +171,24 @@ function create(deps) {
     return null;
   }
 
+  /* ask-the-past: a new initiative that repeats what was decided or declined before gets one "You decided this before" finding under its ✦
+   * (lib/past-repeat.js, through lib/ai-guard.js). Deterministic and local: no session, no model. Once per initiative while the server runs;
+   * a second pass files the same id, so a restart repeats nothing the PM sees. */
+  function pastOnce(w, dir, ini) {
+    const k = w.id + '|' + ini;
+    if (pastSeen.has(k) || !w.root) return;
+    pastSeen.add(k);
+    let row = {};
+    try { row = (deps.rowOf && deps.rowOf(w, ini)) || {}; } catch { row = {}; }
+    let board = '';
+    try { board = (deps.boardOf && deps.boardOf(w, ini)) || ''; } catch { board = ''; }
+    const PRP = require('./past-repeat.js');
+    let runtime = null;
+    try { runtime = require('./state-root.js').defaultRoot(); } catch { runtime = null; }
+    Promise.resolve().then(() => PRP.file({ root: w.root, dir, runtime, ws: w.id, board, ini, title: row.title || ini, intent: row.intent || '', env: deps.env || process.env }))
+      .catch((e) => warn('you decided this before', e));
+  }
+
   function stop(run) { const a = active.get(run); if (a && a.session && deps.stop) deps.stop(a.session); }
 
   function tick({ now = Date.now(), env } = {}) {
@@ -188,6 +207,7 @@ function create(deps) {
       try { created = deps.created(w) || []; } catch { created = []; }
       for (const c of created) {
         if (!c || !c.initiative || String(c.at || '') < epoch || F.looks.has(c.initiative)) continue;
+        pastOnce(w, dir, c.initiative);
         const r = start({ ws: w.id, ini: c.initiative, why: 'populate', press: false, now });
         if (r.ok) return { started: c.initiative, why: 'populate' };
         if (r.held) return { held: true };   // the governor said wait: the next tick tries again

package/workspace/lib/rehearse-cli.js

@@ -0,0 +1,102 @@
+'use strict';
+/* rehearse-cli.js — `pmos rehearse`: what a change would break or help, before the PM approves it (initiative plan-rehearsal).
+ *
+ *   pmos rehearse move <task> --by <days> | --start YYYY-MM-DD [--due YYYY-MM-DD] | --due YYYY-MM-DD   a task's dates change
+ *   pmos rehearse end <initiative> --to YYYY-MM-DD                                                    an initiative's end changes
+ *   pmos rehearse cut <task|initiative>                                                               what if we cut this
+ *   pmos rehearse log [--n N]                                                                         the last rehearsals (the audit)
+ *   every command takes --json and --root <repository>
+ *
+ * It reads through lib/rehearse-read.js, runs lib/rehearse.js and shows only the effects lib/ai-guard.js lets through (lib/rehearse-guard.js).
+ * It changes nothing: the one write is the audit line in <runtime>/ai-audit.jsonl. The PM approves the change in their own words; only
+ * then does the session make it, with `pmos task set`, `pmos task state` or the PM's own act. Exit codes: 0 done, 1 off or refused,
+ * 2 usage. Nothing is sent. */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const RH = require('./rehearse.js');
+
+const COMMANDS = { rehearse: ['move', 'end', 'cut', 'log'] };
+const USAGE = [
+  'usage: pmos rehearse move|end|cut|log — what a change would break or help, before the PM approves it. Nothing changes.',
+  '  pmos rehearse move <task> --by <days>                       the task moves later (or earlier, with a minus) by whole days',
+  '  pmos rehearse move <task> --start YYYY-MM-DD [--due YYYY-MM-DD] | --due YYYY-MM-DD',
+  '  pmos rehearse end <initiative> --to YYYY-MM-DD               the initiative\'s end date changes',
+  '  pmos rehearse cut <task|initiative>                          what if we cut this',
+  '  pmos rehearse log [--n N]                                    the last rehearsals',
+  'Each effect names the record it comes from. Show it to the PM, and make the change only after the PM says yes.',
+];
+const VALUE = new Set(['by', 'start', 'due', 'to', 'root', 'today', 'n']);
+const BOOL = new Set(['json']);
+
+function parse(args) {
+  const pos = [], flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const m = /^--([a-z-]+)(?:=(.*))?$/.exec(args[i]);
+    if (!m) { pos.push(args[i]); continue; }
+    if (m[2] !== undefined) flags[m[1]] = m[2];
+    else if (VALUE.has(m[1]) && args[i + 1] !== undefined && !/^--[a-z]/.test(args[i + 1])) flags[m[1]] = args[++i];
+    else flags[m[1]] = true;
+  }
+  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 runtimeOf = (env) => require('./state-root.js').defaultRoot({ env });
+
+async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), env = process.env, stateDir = null, snapshot = null } = {}) {
+  const args = argv[0] === 'rehearse' ? argv.slice(1) : argv.slice();
+  const verb = args[0];
+  if (!verb || ['help', '--help', '-h'].includes(verb)) { for (const l of USAGE) say(l); return verb ? 0 : 1; }
+  if (!COMMANDS.rehearse.includes(verb)) { say(`unknown rehearse command "${verb}" — one of ${COMMANDS.rehearse.join(', ')}`); return 2; }
+  const { pos, flags } = parse(args.slice(1));
+  for (const k of Object.keys(flags)) if (!VALUE.has(k) && !BOOL.has(k)) { say(`unknown option --${k}`); return 2; }
+  for (const k of Object.keys(flags)) if (VALUE.has(k) && flags[k] === true) { say(`--${k} needs a value`); return 2; }
+  const json = !!flags.json, runtime = stateDir || runtimeOf(env);
+  const G = require('./rehearse-guard.js'), AG = require('./ai-guard.js');
+
+  if (verb === 'log') {
+    const n = Math.min(200, Math.max(1, Number(flags.n) || 10));
+    const lines = AG.readAudit(runtime, { job: G.JOB, limit: 2000 }).filter((l) => l.event === 'start' || l.event === 'end' || l.event === 'off' || l.event === 'held').slice(-n * 2);
+    if (json) { say(JSON.stringify({ ok: true, lines })); return 0; }
+    if (!lines.length) { say('No rehearsal yet.'); return 0; }
+    for (const l of lines) say(`${String(l.at).slice(0, 16).replace('T', ' ')} ${l.event}${l.change ? ' ' + l.change.kind + ' ' + (l.change.task || l.change.ini || '') : ''}${l.filed != null ? ' · ' + l.filed + ' shown, ' + l.dropped + ' dropped' : ''}${l.why ? ' · ' + l.why : ''}`);
+    return 0;
+  }
+
+  const usage = { move: 'usage: pmos rehearse move <task> --by <days> | --start YYYY-MM-DD [--due YYYY-MM-DD] | --due YYYY-MM-DD', end: 'usage: pmos rehearse end <initiative> --to YYYY-MM-DD', cut: 'usage: pmos rehearse cut <task|initiative>' }[verb];
+  if (pos.length !== 1) { say(usage); return 2; }
+  const allowed = { move: ['by', 'start', 'due'], end: ['to'], cut: [] }[verb];
+  for (const k of ['by', 'start', 'due', 'to']) if (flags[k] !== undefined && !allowed.includes(k)) { say(`--${k} is not an option of ${verb}`); return 2; }
+  const fail = (error, code = 1) => { if (json) say(JSON.stringify({ ok: false, error })); else say('✗ ' + error); return code; };
+
+  // the kill switch first: an off rehearsal reads nothing
+  const off = AG.off(G.JOB, { env, settingsDir: runtime });
+  if (off) { AG.audit(runtime, { job: G.JOB, version: G.VERSION, event: 'off', why: off }); return fail('rehearsals are off: ' + off + '. `pmos ai on rehearse` turns them on.'); }
+
+  const root = flags.root ? path.resolve(cwd, flags.root) : repoRoot(cwd);
+  const snap = snapshot || require('./rehearse-read.js').snapshotOf(root, { today: typeof flags.today === 'string' ? flags.today : undefined });
+  const id = pos[0];
+  let change;
+  if (verb === 'move') {
+    if (flags.by !== undefined && !/^-?\d+$/.test(String(flags.by))) return fail('--by takes whole days, e.g. --by 3 or --by -2', 2);
+    change = { kind: 'move', task: id, ...(flags.by !== undefined ? { days: Number(flags.by) } : {}), ...(flags.start ? { start: flags.start } : {}), ...(flags.due ? { due: flags.due } : {}) };
+  } else if (verb === 'end') change = { kind: 'end', ini: id, to: flags.to };
+  else change = (snap.rows || []).some((r) => r.id === id) ? { kind: 'cut', ini: id } : { kind: 'cut', task: id };
+
+  const r = RH.rehearse(snap, change);
+  if (!r.ok) return fail(r.error, /^(say how|--)/.test(r.error) ? 2 : 1);
+  const g = await G.guarded(r, { root, stateDir: runtime, env });
+  if (g.off) return fail('rehearsals are off: ' + g.off);
+  if (g.held) return fail('the rehearsal replay did not pass, so nothing is shown: ' + (g.failed || []).map((f) => f.name + ' (' + f.why + ')').join('; ') + '. `pmos ai status` shows it.');
+  const shown = { ...r, effects: g.effects, counts: { breaks: 0, helps: 0, moves: 0 } };
+  for (const e of shown.effects) shown.counts[e.tone]++;
+  if (json) { say(JSON.stringify({ ok: true, change, effects: shown.effects, counts: shown.counts, dropped: g.dropped.length, missing: r.missing, changed: false })); return 0; }
+  for (const l of RH.textOf(shown).slice(0, -1)) say(l);
+  if (g.dropped.length) say(`${g.dropped.length === 1 ? '1 effect is' : g.dropped.length + ' effects are'} not shown: PMOS could not find its source at the line it cites.`);
+  say(RH.textOf(shown).slice(-1)[0]);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/rehearse-guard.js

@@ -0,0 +1,81 @@
+'use strict';
+/* rehearse-guard.js — a rehearsal's effects through the shared door, lib/ai-guard.js (initiative ai-job-guard): the kill switch, the
+ * replay gate, the citation check and the audit. Nothing here duplicates the guard; this file only says what a rehearsal files and
+ * which recorded cases it must pass.
+ *
+ *   JOB · VERSION                          'rehearse', and the version of the engine's output (bump it when lib/rehearse.js changes)
+ *   proposalsOf(result) → [proposal]       one ai-guard proposal per effect: its text, its sources, its tone in data
+ *   cases(fixture?) → [replay case]        the recorded snapshot fixtures/rehearse-replay.json, replayed through the engine
+ *   fixture(file?) → { root, snap }        that snapshot, its cited files written to a temporary folder (root), its sources computed from them
+ *   guarded(result, o) → Promise<{ off?, held?, effects, dropped }>
+ *       o: { root, stateDir (the runtime folder), env, run }. Runs the replay first when this version has not passed it, then files
+ *       the effects. An effect whose source the guard cannot find at its line is dropped and never shown (proven only).
+ *
+ * The audit lines go to <runtime>/ai-audit.jsonl with the job `rehearse`; `pmos ai log rehearse` reads them, and `pmos ai off rehearse`
+ * (or PMOS_AI_REHEARSE=off, or PMOS_AI=off) turns rehearsals off. */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const AG = require('./ai-guard.js');
+const RH = require('./rehearse.js');
+const RR = require('./rehearse-read.js');
+
+const JOB = 'rehearse';
+const VERSION = '2';
+const MAX = 40;
+const FIXTURE = path.join(__dirname, '..', 'fixtures', 'rehearse-replay.json');
+const TITLE = { breaks: 'Breaks', helps: 'Helps', moves: 'Moves with it' };
+
+const idOf = (e) => 'rh:' + e.kind + ':' + crypto.createHash('sha1').update(e.text).digest('hex').slice(0, 12);
+function proposalsOf(r) {
+  if (!r || !r.ok) return [];
+  return r.effects.map((e) => ({
+    id: idOf(e), title: TITLE[e.tone] + ': ' + e.kind, say: e.text,
+    confidence: new Set(e.evidence.map((s) => s.ref)).size >= 2 ? 'high' : 'medium',
+    claims: [{ text: e.text, sources: e.evidence.map((s) => ({ label: s.label, ref: s.ref, quote: s.quote || '' })) }],
+    data: { tone: e.tone, kind: e.kind, ini: e.ini || null, task: e.task || null, goal: e.goal || null, program: e.program || null },
+  }));
+}
+
+function fixture(file = FIXTURE) {
+  const snap = JSON.parse(fs.readFileSync(file, 'utf8'));
+  // the files its sources cite, written where the guard can read them at their lines
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pmos-rehearse-replay-'));
+  for (const [name, lines] of Object.entries(snap.contents || {})) fs.writeFileSync(path.join(root, path.basename(name)), lines.join('\n') + '\n');
+  const f = snap.files || {}, abs = (x) => path.join(root, x);
+  delete snap.contents;
+  snap.refs = RR.refsOf(root, snap, { links: abs(f.links), krs: abs(f.krs), programs: abs(f.programs), records: Object.fromEntries(Object.entries(f.records || {}).map(([k, v]) => [k, abs(v)])) });
+  return { root, snap };
+}
+/** The recorded cases: the engine on a fixed snapshot, never a model. */
+function cases(F = fixture()) {
+  const { snap } = F;
+  const run = (change, edit) => async () => proposalsOf(RH.rehearse(edit ? edit(JSON.parse(JSON.stringify(snap))) : snap, change));
+  return [
+    { name: 'a change nothing waits on says nothing', run: run({ kind: 'move', task: 'b2', days: 1 }), expect: { none: true } },
+    { name: 'a later task moves another initiative, a milestone and a Jira ticket, with the link lines', run: run({ kind: 'move', task: 'a1', days: 5 }), expect: { min: 5, cites: ['rehearse-links.jsonl', 'rehearse-programs.jsonl'] } },
+    { name: 'cutting an initiative names the goal it moves and what waited on it', run: run({ kind: 'cut', ini: 'checkout' }), expect: { min: 3, cites: ['rehearse-krs.jsonl', 'rehearse-checkout.txt', 'rehearse-links.jsonl'] } },
+    { name: 'a link broken before the change is not blamed on it', run: run({ kind: 'end', ini: 'checkout', to: '2026-11-25' }, (s) => { s.tasks[2].start = '2026-11-18'; return s; }), expect: { none: true } },
+  ];
+}
+
+async function guarded(result, o = {}) {
+  const env = o.env || process.env, stateDir = o.stateDir, run = o.run || 'rh-' + crypto.randomBytes(4).toString('hex');
+  const off = AG.off(JOB, { env, settingsDir: stateDir });
+  if (off) { AG.audit(stateDir, { job: JOB, version: VERSION, run, event: 'off', why: off }); return { off, effects: [], dropped: [] }; }
+  if (!AG.ready(stateDir, JOB, VERSION)) {
+    const F = fixture(), rp = await AG.replay(JOB, VERSION, cases(F), { root: F.root, stateDir, max: MAX });
+    try { fs.rmSync(F.root, { recursive: true, force: true }); } catch { /* a temporary folder */ }
+    if (!rp.ok) return { held: true, failed: rp.failed, effects: [], dropped: [] };
+  }
+  AG.audit(stateDir, { job: JOB, version: VERSION, run, event: 'start', change: result.change, effects: result.effects.length });
+  const P = proposalsOf(result), byId = new Map(P.map((p, i) => [p.id, result.effects[i]]));
+  let shown = [];
+  const got = await AG.file({ job: JOB, version: VERSION, run, root: o.root, stateDir, settingsDir: stateDir, env, max: MAX }, P, async (filed) => { shown = filed.map((p) => byId.get(p.id)).filter(Boolean); });
+  if (got.off) return { off: got.off, effects: [], dropped: [] };
+  if (got.held) return { held: true, effects: [], dropped: [] };
+  return { effects: shown, dropped: got.dropped || [] };
+}
+
+module.exports = { JOB, VERSION, MAX, FIXTURE, proposalsOf, fixture, cases, guarded };