create-pmos 0.46.0 → 0.48.0

package/workspace/lib/live-notes.js

@@ -0,0 +1,890 @@
+'use strict';
+/* live-notes.js — map the talking points of a conversation to initiatives, as proposals only (jev-live-notes, Run 1).
+ *
+ * THE UNIT IS A SEGMENT: one short run of text, a time, an optional speaker, a pointer to where it came from. Nothing
+ * here records audio or depends on one source. A segment is placed against the repository's open initiatives and
+ * given a relation (D71's words plus `answers`), a scope flag and a confirmed flag, then appended to a ledger.
+ *
+ * THREE PATHS, ONE OUTPUT SHAPE.
+ *   agent-only (the default): the engine writes what to ask an agent session; the answers come back as
+ *     `LIVENOTE {json}` lines and are checked here. No outside service.
+ *   jev-agent (Run 5): when ALL THREE gates hold — a key, D79 consent for the repository, and the "live notes may use
+ *     Jev" switch — and no sender is injected, the same prompt asks the PM's own agent session to make the two choices
+ *     with the Typesafe skill (the route `judgment.js` already uses) and to mark each answer `"by":"jev"`. The
+ *     workspace sends nothing itself; no new server egress, so D79 is not amended.
+ *   jev: the same three gates, through the `ask` function a caller injects. This file requires no network module,
+ *     and no command injects one: a server-side send of live talk needs a decision that amends D79.
+ *
+ * WHAT IT NEVER DOES. It creates, edits, accepts or closes no initiative and writes no decision. Its only writes into
+ * the repository are the session ledger (`<state>/live-notes/<session>.jsonl`, through lib/sink.js) and, on close,
+ * one section appended to the day's requirements note (D71). The raw transcript lives only in the per-user runtime
+ * directory and is deleted on close, or after a retention the PM sets. A result is advisory and is shown in words.
+ *
+ * KNOWN WEAKNESS, KEPT VISIBLE. The relation, scope, confirmed and answers questions are asked in the same request as
+ * the initiative choice, so they refer to "the initiative this point is most about". That is the indirection Jev is
+ * documented to handle less well. A weak or inconsistent initiative choice is re-asked once and, if still weak, is
+ * kept as a flagged proposal rather than a match. Whether this holds on real talk is the override rate's question.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { scan } = require('./secret-scan');
+const { createSinkGuard } = require('./sink');
+
+const MAX_CHOICE = 255;                 // the documented cap on options in one Choice
+const MAX_ANSWER_QS = 3;                // open questions asked about per segment
+const REJECTED_LIMIT = 2;
+const UNREACHABLE_LIMIT = 3;
+const MAX_QUOTE = 160;
+const MIN_SEGMENT_CHARS = 8;
+const RELATIONS = ['validates', 'clarifies', 'extends', 'contradicts', 'answers', 'none'];
+const RELATION_HELP = {
+  validates: 'The point supports or confirms something the initiative already says.',
+  clarifies: 'The point explains or sharpens something the initiative already says.',
+  extends: 'The point adds something the initiative does not yet cover.',
+  contradicts: 'The point conflicts with, or invalidates, something the initiative says.',
+  answers: 'The point answers a question the initiative has left open.',
+  none: 'The point has no clear relation to the initiative.',
+};
+const LANES = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'];   // the code profile's six (D56, D58, D60)
+const MAX_NOTE = 600;
+const MAX_TITLE = 80;
+const MAX_CITE_FILE = 400 * 1024;
+const STOP = new Set('about above after again also been being from have into just more most only other over some such than that their them then there these they this those very what when where which while will with would your you are and but for not the was were can could should how why who has had its our out all any'.split(' '));
+
+const sha = (s) => crypto.createHash('sha1').update(String(s)).digest('hex');
+const nowISO = (t) => new Date(t == null ? Date.now() : t).toISOString();
+const oneLine = (s) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+
+/** Words, never the number. Below 0.5 the claim is not made. */
+const band = (p) => (p >= 0.85 ? 'very likely' : p >= 0.65 ? 'likely' : p >= 0.5 ? 'possible' : 'unlikely');
+
+/* ── the gates ─────────────────────────────────────────────────────────────────────────────────── */
+function gates({ key, consent, live }) {
+  const missing = [];
+  if (!key) missing.push('key');
+  if (!consent) missing.push('consent');
+  if (!live) missing.push('live');
+  return { open: missing.length === 0, missing };
+}
+const GATE_WORDS = {
+  key: 'No TypeSafe key is saved.',
+  consent: 'Validation is not switched on for this repository.',
+  live: 'Live notes are not switched on to use Jev.',
+};
+const gateSentence = (missing) => missing.map((m) => GATE_WORDS[m]).join(' ');
+
+/* ── per-user switch: default OFF, kept outside every repository ─────────────────────────────── */
+const readJson = (f, d) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+function writeJson(f, v) {
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = f + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(v));
+  fs.renameSync(tmp, f);
+}
+const switchFile = (runtimeDir) => path.join(runtimeDir, 'live-notes', 'settings.json');
+function getSwitch(runtimeDir, root) {
+  const s = readJson(switchFile(runtimeDir), {});
+  const r = s && s.repos && s.repos[root];
+  return { live: !!(r && r.live === true), retention_days: r && Number.isFinite(r.retention_days) && r.retention_days > 0 ? Math.min(r.retention_days, 365) : 0 };
+}
+function setSwitch(runtimeDir, root, { live, retention_days }) {
+  const s = readJson(switchFile(runtimeDir), {});
+  const prev = getSwitch(runtimeDir, root);
+  const repos = { ...(s && s.repos), [root]: {
+    live: typeof live === 'boolean' ? live : prev.live,
+    retention_days: Number.isFinite(retention_days) && retention_days >= 0 ? Math.min(retention_days, 365) : prev.retention_days,
+  } };
+  writeJson(switchFile(runtimeDir), { repos });
+  return getSwitch(runtimeDir, root);
+}
+
+/* ── reading the repository (read-only) ────────────────────────────────────────────────────────── */
+function frontmatter(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  const fm = {};
+  if (!m) return fm;
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) fm[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return fm;
+}
+const stateDirIn = (root) => (fs.existsSync(path.join(root, 'pmos', 'state')) ? path.join(root, 'pmos', 'state') : path.join(root, 'planning'));
+const rel = (root, f) => path.relative(root, f).split(path.sep).join('/');
+
+/** An entry is a path prefix, or a `*` pattern on the path (the same rule as the repository exclusions). */
+function isExcluded(exclude, relPath) {
+  const p = String(relPath).replace(/\\/g, '/');
+  return (exclude || []).some((e) => {
+    if (e.includes('*')) {
+      const re = new RegExp('^' + e.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
+      return re.test(p);
+    }
+    return p === e || p.startsWith(e.endsWith('/') ? e : e + '/');
+  });
+}
+
+/** Initiatives not stopped under D70 (the latest lifecycle line wins; `active` reopens). */
+function loadInitiatives(root) {
+  const dir = path.join(root, 'planning', 'initiatives');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)); } catch { /* none */ }
+  const stopped = new Map();
+  const lf = path.join(root, 'planning', 'runs', 'lifecycle.jsonl');
+  let raw = '';
+  try { raw = fs.readFileSync(lf, 'utf8'); } catch { /* none */ }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let e = null; try { e = JSON.parse(line); } catch { continue; }
+    if (e && e.initiative_id) stopped.set(e.initiative_id, e.state);
+  }
+  const all = [];
+  for (const f of files.sort()) {
+    let text = '';
+    try { text = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; }
+    const fm = frontmatter(text);
+    const id = fm.id || f.replace(/\.md$/, '');
+    const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+    const para = body.split(/\n\s*\n/).map((p) => p.trim()).find((p) => p && !/^#/.test(p) && !/^[-*]\s/.test(p)) || '';
+    all.push({ id, title: fm.title || id, anchor: fm.parent_kr || '', prd: fm.prd_path || '', intent: oneLine(para).slice(0, 240), state: stopped.get(id) || 'active' });
+  }
+  const open = all.filter((i) => i.state === 'active');
+  return { open, stopped: all.filter((i) => i.state !== 'active').map((i) => i.id) };
+}
+
+/** Filter the open set in code. `anchor` is exact (`domain:pmos`, `health:tech`, a KR id). Past the Choice cap: stop, never truncate. */
+function shortlist(open, { anchor = null } = {}) {
+  const list = anchor ? open.filter((i) => i.anchor === anchor) : open.slice();
+  if (list.length > MAX_CHOICE) {
+    return { ok: false, count: list.length, error: `${list.length} open initiatives match, and one Choice holds at most ${MAX_CHOICE}. Narrow it with an anchor (for example domain:<id>); nothing was truncated.` };
+  }
+  return { ok: true, list };
+}
+
+/** Open questions by structure: the top-level items under an "Open questions" or "Open points" heading. */
+function openQuestionsOf(prdText) {
+  const lines = String(prdText || '').split(/\r?\n/);
+  const out = [];
+  let level = 0;
+  for (const line of lines) {
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) {
+      if (level && h[1].length <= level) break;
+      if (!level && /^open (questions|points)\b/i.test(h[2].trim())) level = h[1].length;
+      continue;
+    }
+    if (!level) continue;
+    const m = /^(?:\d+[.)]|[-*])\s+(.*)$/.exec(line);
+    if (m) out.push(oneLine(m[1].replace(/\*\*|__|`/g, '')).slice(0, 300));
+  }
+  return out.filter(Boolean);
+}
+function attachQuestions(root, items, exclude) {
+  return items.map((i) => {
+    let qs = [];
+    if (i.prd && !isExcluded(exclude, i.prd)) {
+      try { qs = openQuestionsOf(fs.readFileSync(path.join(root, i.prd), 'utf8')); } catch { /* no PRD */ }
+    }
+    return { ...i, questions: qs };
+  });
+}
+
+/* ── the request ───────────────────────────────────────────────────────────────────────────────── */
+const terms = (s) => new Set(String(s).toLowerCase().match(/[a-z][a-z0-9-]{3,}/g)?.filter((w) => !STOP.has(w)) || []);
+const overlap = (a, b) => { let n = 0; for (const t of a) if (b.has(t)) n++; return n; };
+
+/** Deterministic shuffle: Jev leans toward the first option, so the order changes with the pass. */
+function shuffled(arr, seed) {
+  return arr.map((x, i) => [sha(seed + '|' + i + '|' + (x.id || x)), x]).sort((a, b) => (a[0] < b[0] ? -1 : 1)).map((p) => p[1]);
+}
+
+/** The open questions worth asking about for this segment: ranked by shared words in code, a bounded few. */
+function pickQuestions(items, text) {
+  const t = terms(text);
+  const all = [];
+  for (const i of items) (i.questions || []).forEach((q, n) => all.push({ initiative: i.id, n: n + 1, text: q, score: overlap(t, terms(q)) }));
+  return all.filter((q) => q.score > 0).sort((a, b) => b.score - a.score || (a.initiative + a.n < b.initiative + b.n ? -1 : 1)).slice(0, MAX_ANSWER_QS);
+}
+
+function requestFor(segment, items, pass = 0) {
+  const asked = pickQuestions(items, segment.text);
+  const ordered = shuffled(items, segment.id + '#' + pass);
+  const criteria = {};
+  for (const i of ordered) criteria[i.id] = oneLine(i.title + (i.intent ? ' — ' + i.intent : '')).slice(0, 300);
+  criteria.none = 'None of these initiatives.';
+  const rel = {};
+  for (const r of shuffled(RELATIONS, segment.id + '@' + pass)) rel[r] = RELATION_HELP[r];
+  const questions = {
+    initiative: { type: 'choice', instructions: 'Which initiative is this talking point about?', criteria },
+    relation: { type: 'choice', instructions: 'How does the talking point relate to the initiative it is most about?', criteria: rel },
+    in_scope: { type: 'noul', instructions: 'The talking point is inside the stated scope of the initiative it is most about.' },
+    confirmed: { type: 'noul', instructions: 'The speaker states this as decided or agreed, not as an idea, a question or an opinion.' },
+  };
+  asked.forEach((q, k) => { questions['answers_' + (k + 1)] = { type: 'noul', instructions: `The talking point answers this open question: "${q.text}"` }; });
+  const state = 'TALKING POINT:\n' + (segment.speaker ? segment.speaker + ': ' : '') + segment.text;
+  return { state, questions, asked };
+}
+
+/* ── answers → proposal ────────────────────────────────────────────────────────────────────────── */
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1 ? v : NaN);
+function choiceOf(a, allowed) {
+  if (!a || a.type !== 'choice' || typeof a.choice !== 'string' || !allowed.includes(a.choice)) return null;
+  const p = a.probabilities && Number.isFinite(a.probabilities[a.choice]) ? a.probabilities[a.choice] : num(a.confidence);
+  return { choice: a.choice, p: Number.isFinite(p) ? p : 0, confidence: num(a.confidence) };
+}
+function weak(c) { return !c || c.p < 0.5 || (c.confidence != null && c.confidence < 0.5); }
+
+function mapJev(answers, req, ids) {
+  const ini = choiceOf(answers && answers.initiative, ids.concat('none'));
+  const rel = choiceOf(answers && answers.relation, RELATIONS);
+  const scope = num(answers && answers.in_scope && answers.in_scope.noul);
+  const conf = num(answers && answers.confirmed && answers.confirmed.noul);
+  if (!ini || !rel || !Number.isFinite(scope) || !Number.isFinite(conf)) return null;
+  let best = null;
+  req.asked.forEach((q, k) => {
+    const v = num(answers['answers_' + (k + 1)] && answers['answers_' + (k + 1)].noul);
+    if (Number.isFinite(v) && v >= 0.65 && (!best || v > best.p)) best = { initiative: q.initiative, n: q.n, text: q.text, p: v };
+  });
+  return { ini, rel, scope, conf, answered: best };
+}
+
+/** The proposal fields shared by both paths. `flags` records anything the PM should read twice. */
+function proposalFrom(m, ctx) {
+  const flags = ctx.flags.slice();
+  let initiative = m.ini.choice;
+  if (weak(m.ini) || ctx.inconsistent) { flags.push(ctx.inconsistent ? 'initiative-choice-inconsistent' : 'initiative-choice-weak'); initiative = 'none'; }
+  let relation = m.rel.choice;
+  let answers_question = null;
+  if (m.answered && initiative === m.answered.initiative) {
+    answers_question = { initiative: m.answered.initiative, n: m.answered.n, text: m.answered.text.slice(0, 200), band: band(m.answered.p) };
+    relation = 'answers';
+  } else if (relation === 'answers') { relation = 'clarifies'; flags.push('answers-without-a-named-question'); }
+  if (initiative === 'none') relation = 'none';
+  return {
+    initiative, initiative_band: band(m.ini.p),
+    relation, relation_band: band(m.rel.p),
+    in_scope: m.scope >= 0.5, scope_band: band(m.scope),
+    confidence: m.conf >= 0.85 ? 'confirmed' : 'unconfirmed',
+    answers_question, flags,
+  };
+}
+
+/** `LIVENOTE {json}` lines from an agent session. Anything off-shape is rejected, never repaired. */
+const JUDGES = ['jev', 'agent'];
+function parseAgentAnswers(text, ids) {
+  const out = new Map(); const rejected = [];
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = /^\s*LIVENOTE\s+(\{.*\})\s*$/.exec(line);
+    if (!m) continue;
+    let o = null; try { o = JSON.parse(m[1]); } catch { rejected.push('not JSON'); continue; }
+    const ok = o && typeof o.segment === 'string' && (o.initiative === 'none' || ids.includes(o.initiative)) && RELATIONS.includes(o.relation)
+      && typeof o.in_scope === 'boolean' && typeof o.confirmed === 'boolean' && Number.isFinite(o.confidence) && o.confidence >= 0 && o.confidence <= 1
+      && (o.by === undefined || JUDGES.includes(o.by));
+    if (!ok) { rejected.push(String(o && o.segment || '?')); continue; }
+    out.set(o.segment, o);
+  }
+  return { answers: out, rejected };
+}
+function proposalFromAgent(o, { jevAllowed = false } = {}) {
+  const flags = [];
+  // An answer that says Jev made it, when the gates were not open, is kept and flagged, never hidden: the text has
+  // already left the machine, and the PM is the one who needs to know.
+  if (o.by === 'jev' && !jevAllowed) flags.push('jev-used-without-gates');
+  let relation = o.initiative === 'none' ? 'none' : o.relation;
+  const a = o.answers && typeof o.answers === 'string' ? o.answers : null;
+  if (relation === 'answers' && !a) { relation = 'clarifies'; flags.push('answers-without-a-named-question'); }
+  return {
+    initiative: o.initiative, initiative_band: band(o.confidence), relation, relation_band: band(o.confidence),
+    in_scope: o.in_scope, scope_band: band(o.confidence), confidence: o.confirmed && o.confidence >= 0.85 ? 'confirmed' : 'unconfirmed',
+    answers_question: a ? { initiative: o.initiative, n: null, text: a.slice(0, 200), band: band(o.confidence) } : null, flags,
+    judged_by: o.by === 'jev' ? 'jev' : 'agent',
+  };
+}
+
+/** The prompt an agent session answers. With `jev`, the session is asked to make the two choices with the Typesafe skill. */
+const JEV_AGENT_LINES = [
+  'Use the Typesafe skill (/typesafe:typesafe-ai) to choose the initiative and the relation for each talking point: one Choice question for the initiative ids plus "none", one for the relation words.',
+  'Send only the talking point\'s words and the option list. Do not send a speaker\'s name, a file, or a key. The words leave this machine for the Typesafe service, which needs TYPESAFE_API_KEY.',
+  'Give Jev\'s probability for its choice as "confidence" and write "by":"jev". If the skill or the key is missing, or a call fails, say so, decide yourself, and write "by":"agent".',
+];
+function agentPrompt(segments, items, { jev = false } = {}) {
+  const lines = ['For each talking point below, decide which initiative it is about, how it relates, whether it is in that initiative\'s scope, and whether the speaker stated it as decided.'];
+  if (jev) lines.push(...JEV_AGENT_LINES);
+  else lines.push('Decide yourself; no outside service is used for these points. Write "by":"agent".');
+  lines.push('Initiatives (use the id, or "none"):');
+  for (const i of items) {
+    lines.push(`- ${i.id}: ${oneLine(i.title)}${i.intent ? ' — ' + i.intent : ''}`);
+    (i.questions || []).slice(0, 5).forEach((q, n) => lines.push(`    open question ${n + 1}: ${q}`));
+  }
+  lines.push(`relation is one of: ${RELATIONS.join(', ')}. Use "answers" only when the point answers a named open question, and name it in "answers".`);
+  lines.push('Print one line per talking point, exactly like this, one JSON object per line (confidence is yours, 0 to 1):');
+  lines.push(`  e.g. LIVENOTE {"segment":"<id>","initiative":"<id or none>","relation":"<one of the words>","in_scope":true,"confirmed":false,"answers":null,"confidence":0.7,"by":"${jev ? 'jev' : 'agent'}"}`);
+  lines.push('Talking points:');
+  // With Jev the speaker is left out of the prompt, so it cannot be sent by mistake.
+  for (const s of segments) lines.push(`[${s.id}] ${s.speaker && !jev ? s.speaker + ': ' : ''}${s.text}`);
+  return lines.join('\n');
+}
+
+
+/* ── Run 3: the agent's context note and candidate draft, by tier ────────────────────────────────── */
+const MODEL_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'pmos-model.js'), path.join(__dirname, 'engine', 'pmos-model.js')];
+function modelCore() { for (const p of MODEL_PATHS) { try { if (fs.existsSync(p)) return require(p); } catch { /* not loadable */ } } return null; }
+
+/** The latest row per segment (a pending row is superseded by the proposal that answers it). */
+function foldSegments(rows) { const m = new Map(); for (const r of rows) if (r.row === 'segment') m.set(r.segment, r); return m; }
+function foldCandidates(rows) { const m = new Map(); for (const r of rows) if (r.row === 'candidate') m.set(r.candidate, r); return m; }
+function acceptedInitiatives(root) {
+  const out = new Set();
+  let raw = ''; try { raw = fs.readFileSync(path.join(root, 'planning', 'runs', 'acceptances.jsonl'), 'utf8'); } catch { return out; }
+  for (const line of raw.split('\n')) { if (!line.trim()) continue; try { const e = JSON.parse(line); if (e && e.accepted === true && e.initiative_id) out.add(e.initiative_id); } catch { /* torn */ } }
+  return out;
+}
+
+/** What needs a note, and on which tier. Tagging itself is `fast` and is not listed. */
+function contextPlan({ root, rows, items = [] }) {
+  const accepted = acceptedInitiatives(root);
+  const byId = new Map(items.map((i) => [i.id, i]));
+  const plan = { tagging_tier: 'fast', context: [], candidates: [] };
+  const decided = new Set(rows.filter((r) => r.row === 'context').map((r) => r.segment));
+  for (const [id, r] of foldSegments(rows)) {
+    if (r.status !== 'proposed' || r.initiative === 'none' || !r.initiative) continue;
+    const reasons = [];
+    if (r.relation === 'contradicts') reasons.push('it contradicts the initiative');
+    if (r.relation === 'answers') reasons.push('it answers a named open question');
+    if (r.in_scope === false) reasons.push('it is outside the initiative\'s scope');
+    if (r.flags && r.flags.length) reasons.push('it carries a flag (' + r.flags.join(', ') + ')');
+    if (!reasons.length) continue;
+    const ini = byId.get(r.initiative);
+    const deep = r.relation === 'contradicts' && accepted.has(r.initiative);
+    plan.context.push({ segment: id, initiative: r.initiative, relation: r.relation, reasons, tier: deep ? 'deep' : 'balanced',
+      why: deep ? 'a contradiction of an initiative the PM has accepted: a mistake here is costly to find later' : 'a short note from the initiative\'s own text',
+      read: [ini && ini.prd, 'planning/initiatives/' + r.initiative + '.md'].filter(Boolean), done: decided.has(id) });
+  }
+  const drafted = new Set(rows.filter((r) => r.row === 'candidate_draft').map((r) => r.candidate));
+  for (const [cid, c] of foldCandidates(rows)) plan.candidates.push({ candidate: cid, segments: c.segments, topic_terms: c.topic_terms, tier: 'deep', why: 'drafting a new initiative\'s title and lane: the work where a mistake is costly', done: drafted.has(cid) });
+  return plan;
+}
+
+function parseLines(text, tag) {
+  const out = []; const bad = [];
+  const re = new RegExp('^\\s*' + tag + '\\s+(\\{.*\\})\\s*$');
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = re.exec(line); if (!m) continue;
+    try { out.push(JSON.parse(m[1])); } catch { bad.push('not JSON'); }
+  }
+  return { entries: out, rejected: bad };
+}
+const parseContext = (text) => parseLines(text, 'LIVECONTEXT');
+const parseDrafts = (text) => parseLines(text, 'LIVECANDIDATE');
+
+/** A citation must name a real file inside the repository, not excluded, and quote it exactly. */
+function checkCite(root, exclude, c) {
+  if (!c || typeof c.path !== 'string' || typeof c.quote !== 'string' || c.quote.trim().length < 8) return 'a citation needs a path and a quotation of at least 8 characters';
+  const relp = c.path.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (relp.split('/').includes('..')) return 'a citation path may not leave the repository';
+  if (isExcluded(exclude, relp)) return 'the cited file is excluded';
+  const abs = path.resolve(root, relp);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return 'a citation path may not leave the repository';
+  let st; try { st = fs.lstatSync(abs); } catch { return 'the cited file does not exist: ' + relp; }
+  if (!st.isFile() || st.isSymbolicLink() || st.size > MAX_CITE_FILE) return 'the cited file cannot be read as a plain document: ' + relp;
+  const text = fs.readFileSync(abs, 'utf8');
+  return text.includes(c.quote) ? null : 'the quotation is not an exact part of ' + relp;
+}
+
+/* ── segments in ───────────────────────────────────────────────────────────────────────────────── */
+const PRIVATE_SOURCE = /\b(private|personal|confidential|hr)\b/i;
+function normalizeSegments(raw, { source = 'input', now = Date.now(), prefix = 's' } = {}) {
+  return raw.map((r, i) => {
+    const o = typeof r === 'string' ? { text: r } : (r || {});
+    const text = oneLine(o.text);
+    return {
+      id: typeof o.id === 'string' && o.id ? o.id : prefix + (i + 1),
+      text, at: o.at ? nowISO(Date.parse(o.at) || now) : nowISO(now),
+      speaker: o.speaker ? oneLine(o.speaker).slice(0, 60) : null,
+      source: oneLine(o.source || source).slice(0, 120),
+      private: o.private === true || PRIVATE_SOURCE.test(String(o.source || '')),
+    };
+  }).filter((s) => s.text.length >= MIN_SEGMENT_CHARS);
+}
+
+/** A transcript, with or without `Name:` speaker prefixes, as segments. Deterministic: the same text gives the same ids. */
+const SEG_MAX = 400;
+function segmentsFromTranscript(text, { source = 'transcript', now = Date.now() } = {}) {
+  const out = [];
+  let speaker = null; let buf = [];
+  const flush = () => {
+    const body = oneLine(buf.join(' ')); buf = [];
+    if (!body) return;
+    const sentences = body.split(/(?<=[.!?])\s+/);
+    let cur = '';
+    const push = (t) => { const x = oneLine(t); if (x.length >= MIN_SEGMENT_CHARS) out.push({ id: 't' + sha(speaker + '|' + x).slice(0, 10), text: x, speaker, source, at: nowISO(now) }); };
+    for (const sen of sentences) {
+      if (sen.length > SEG_MAX) { if (cur) { push(cur); cur = ''; } for (let i = 0; i < sen.length; i += SEG_MAX) push(sen.slice(i, i + SEG_MAX)); continue; }
+      if ((cur + ' ' + sen).trim().length > SEG_MAX) { push(cur); cur = sen; } else cur = (cur + ' ' + sen).trim();
+      if (cur.length >= 60) { push(cur); cur = ''; }
+    }
+    if (cur) push(cur);
+  };
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = /^([A-Z][\w .'’-]{0,40}):\s+(.*)$/.exec(line.trim());
+    if (m && !/^(https?|ftp)$/i.test(m[1])) { flush(); speaker = oneLine(m[1]); buf.push(m[2]); }
+    else if (!line.trim()) { flush(); speaker = null; }   // after a blank line the speaker is unknown, not the last one
+    else buf.push(line.trim());
+  }
+  flush();
+  // the same text said by the same speaker twice in one transcript stays one segment
+  const seen = new Set();
+  return out.filter((x) => (seen.has(x.id) ? false : (seen.add(x.id), true)));
+}
+
+const quoteOf = (text) => {
+  const first = (/^(.*?[.!?])(\s|$)/.exec(text) || [, text])[1];
+  const q = first.length > MAX_QUOTE ? first.slice(0, MAX_QUOTE - 1).trimEnd() + '…' : first;
+  return q;
+};
+
+/* ── sessions ──────────────────────────────────────────────────────────────────────────────────── */
+function sessionPaths({ root, runtimeDir, session }) {
+  const dir = path.join(runtimeDir, 'live-notes', session);
+  return { dir, transcript: path.join(dir, 'transcript.jsonl'), state: path.join(dir, 'state.json'), ledger: path.join(stateDirIn(root), 'live-notes', session + '.jsonl') };
+}
+const newSessionId = (now) => 'ln-' + nowISO(now).replace(/[-:]/g, '').replace(/\..*/, '').toLowerCase() + '-' + crypto.randomBytes(2).toString('hex');
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,60}$/;
+
+function readLedger(file) {
+  let raw = ''; try { raw = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  return raw.split('\n').filter((l) => l.trim()).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+/**
+ * Open (or resume) a session.
+ * @param {object} a
+ * @param {string} a.root, a.runtimeDir
+ * @param {string} [a.session]
+ * @param {string|null} [a.key]     the TypeSafe key, or null. Never written anywhere.
+ * @param {{consent:boolean, live:boolean}} [a.flags]
+ * @param {string[]} [a.exclude]
+ * @param {string|null} [a.anchor]
+ * @param {Function|null} [a.ask]   injected sender. Absent: agent-only, or jev-agent when the gates hold. No command injects one.
+ * @param {object} [a.askOpts]
+ * @param {Map|null} [a.agentAnswers]
+ */
+function openSession({ root, runtimeDir, session = null, key = null, flags = {}, exclude = [], anchor = null, ask = null, askOpts = {}, agentAnswers = null, now = Date.now() }) {
+  if (session && !SAFE_ID.test(session)) throw new Error('a session id is letters, digits, dots, dashes and underscores');
+  const id = session || newSessionId(now);
+  const P = sessionPaths({ root, runtimeDir, session: id });
+  fs.mkdirSync(path.dirname(P.ledger), { recursive: true });
+  const guard = createSinkGuard({ sink: P.ledger, what: 'live-notes' });
+  const append = (row) => guard.appendLine(P.ledger, { ...row, session: id, at: nowISO(row.at) });
+  const st0 = readJson(P.state, null);
+  const state = st0 || { started: nowISO(now), rejected: 0, unreachable: 0, paused: null, n: 0, candidates: {}, closed: false };
+  if (readLedger(P.ledger).some((r) => r.row === 'close')) state.closed = true;
+  const g = gates({ key: !!key, consent: !!flags.consent, live: !!flags.live });
+  const jevPath = g.open && typeof ask === 'function';
+  const route = jevPath ? 'jev' : g.open ? 'jev-agent' : 'agent-only';
+  const loaded = loadInitiatives(root);
+  const sl = shortlist(loaded.open, { anchor });
+  const items = sl.ok ? attachQuestions(root, sl.list, exclude) : [];
+  const ids = items.map((i) => i.id);
+  const save = () => writeJson(P.state, state);
+
+  if (!st0 && !readLedger(P.ledger).some((r) => r.row === 'session')) {
+    append({ row: 'session', at: now, path: route, gates_missing: g.missing, anchor, shortlist: ids.length, stopped_excluded: loaded.stopped.length, shortlist_error: sl.ok ? null : sl.error });
+  }
+  if (!st0 && !state.closed) save();
+
+  async function ask1(segment, pass) {
+    const req = requestFor(segment, items, pass);
+    const res = await ask({ key, state: req.state, questions: req.questions, ...askOpts });
+    return { req, res };
+  }
+  const failure = (res, at) => {
+    if (res.status === 401) { state.rejected++; state.unreachable = 0; } else { state.unreachable++; state.rejected = 0; }
+    if (state.rejected >= REJECTED_LIMIT) state.paused = { reason: 'The service rejected the key twice, so Jev is paused for this session. The agent-only path continues.', at: nowISO(at) };
+    else if (state.unreachable >= UNREACHABLE_LIMIT) state.paused = { reason: 'The service could not be reached three times in a row, so Jev is paused for this session. The agent-only path continues.', at: nowISO(at) };
+    if (state.paused) append({ row: 'pause', at, reason: state.paused.reason });
+  };
+
+  /** Process segments. Returns one result per segment, in order. */
+  async function add(raw, opts = {}) {
+    const result = { path: null, rows: [], withheld: [], pending: [], failed: 0, prompt: null, paused: state.paused, gates_missing: g.missing };
+    if (state.closed) throw new Error('this session is closed');
+    if (!sl.ok) { result.error = sl.error; return result; }
+    if (!items.length) { result.error = 'There are no open initiatives to place a talking point against.'; return result; }
+    const segs = normalizeSegments(raw, { source: opts.source || 'input', now: opts.now || Date.now(), prefix: 's' + (state.n + 1) + '-' });
+    const usable = [];
+    const known = opts.dedupe ? new Set(readLedger(P.ledger).filter((r) => r.hash).map((r) => r.hash)) : null;
+    result.skipped_duplicates = 0;
+    for (const s of segs) {
+      if (known && known.has(sha(s.text))) { result.skipped_duplicates++; continue; }
+      state.n++;
+      const hits = scan(s.text);
+      if (hits.length || s.private) {
+        const reason = hits.length ? 'matched the secret scan (' + hits.join(', ') + ')' : 'the source is marked private';
+        append({ row: 'withheld', at: s.at, segment: s.id, hash: sha(s.text), pointer: { kind: 'live', source: s.source, id: s.id }, reason });
+        result.withheld.push({ id: s.id, reason });
+        continue;
+      }
+      usable.push(s);
+    }
+    // the raw words: runtime directory only, never the repository
+    if (usable.length) {
+      fs.mkdirSync(P.dir, { recursive: true });
+      fs.appendFileSync(P.transcript, usable.map((s) => JSON.stringify(s)).join('\n') + '\n');
+    }
+    const useJev = jevPath && !state.paused;
+    result.path = useJev ? 'jev' : route === 'jev-agent' ? 'jev-agent' : 'agent-only';
+    const pendingSegs = [];
+    for (const s of usable) {
+      const pointer = { kind: 'live', source: s.source, id: s.id, at: s.at, speaker: s.speaker };
+      let prop = null; let model = null; let by = 'agent';
+      if (useJev && !state.paused) {
+        by = 'jev';
+        let { req, res } = await ask1(s, 0);
+        if (!res.ok) { result.failed++; failure(res, Date.now()); pendingSegs.push(s); continue; }
+        state.rejected = 0; state.unreachable = 0;
+        let m = mapJev(res.answers, req, ids);
+        model = res.model || null;
+        let inconsistent = false;
+        if (m && weak(m.ini)) {
+          const again = await ask1(s, 1);
+          if (again.res.ok) {
+            const m2 = mapJev(again.res.answers, again.req, ids);
+            if (m2 && m2.ini.choice !== m.ini.choice) inconsistent = true;
+            if (m2 && !inconsistent) m = m2;
+            model = again.res.model || model;
+          } else { result.failed++; failure(again.res, Date.now()); }
+        }
+        if (!m) { append({ row: 'unreadable', at: s.at, segment: s.id, pointer }); result.rows.push({ segment: s.id, status: 'unreadable' }); continue; }
+        prop = proposalFrom(m, { flags: [], inconsistent });
+      } else {
+        const a = (opts.agentAnswers || agentAnswers || new Map()).get(s.id);
+        if (!a) { pendingSegs.push(s); continue; }
+        prop = proposalFromAgent(a);
+      }
+      const row = { row: 'segment', at: s.at, segment: s.id, hash: sha(s.text), pointer, quote: quoteOf(s.text), path: by === 'jev' ? 'jev' : 'agent-only', model, ...prop, status: 'proposed' };
+      append(row);
+      result.rows.push(row);
+    }
+    if (pendingSegs.length) {
+      for (const s of pendingSegs) {
+        const row = { row: 'segment', at: s.at, segment: s.id, hash: sha(s.text), pointer: { kind: 'live', source: s.source, id: s.id, at: s.at, speaker: s.speaker }, quote: quoteOf(s.text), path: 'agent-only', model: null, initiative: null, relation: null, in_scope: null, confidence: 'unconfirmed', flags: ['unanswered'], status: 'pending' };
+        append(row);
+        result.rows.push(row);
+        result.pending.push(s.id);
+      }
+      result.prompt = agentPrompt(pendingSegs, items, { jev: g.open && !jevPath });
+    }
+    groupCandidates();
+    result.paused = state.paused;
+    save();
+    return result;
+  }
+
+  /** Apply an agent's answers to segments still pending: appends a proposed row for each; the pending row stays. */
+  function answer(map) {
+    const latest = new Map();
+    for (const r of readLedger(P.ledger)) if (r.row === 'segment') latest.set(r.segment, r);
+    const done = []; const unknown = [];
+    for (const [segId, a] of map) {
+      const prev = latest.get(segId);
+      if (!prev || prev.status !== 'pending') { unknown.push(segId); continue; }
+      const prop = proposalFromAgent(a, { jevAllowed: g.open });
+      const row = { row: 'segment', at: prev.at, segment: segId, hash: prev.hash, pointer: prev.pointer, quote: prev.quote, path: prop.judged_by === 'jev' ? 'jev-agent' : 'agent-only', model: null, ...prop, status: 'proposed' };
+      append(row); done.push(row);
+    }
+    if (done.length) groupCandidates();
+    return { answered: done, unknown };
+  }
+
+  /** Unmatched segments about one topic become one candidate. Never an initiative record. */
+  function groupCandidates() {
+    const rows = readLedger(P.ledger).filter((r) => r.row === 'segment' && r.status === 'proposed' && r.initiative === 'none');
+    let transcript = [];
+    try { transcript = fs.readFileSync(P.transcript, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)); } catch { /* none */ }
+    const textOf = new Map(transcript.map((s) => [s.id, s.text]));
+    const groups = [];
+    for (const r of rows) {
+      const t = terms(textOf.get(r.segment) || r.quote);
+      const g = groups.find((x) => overlap(t, x.terms) >= 2);
+      if (g) { g.ids.push(r.segment); for (const w of t) g.terms.add(w); } else groups.push({ ids: [r.segment], terms: new Set(t) });
+    }
+    const prior = priorRejections(root, exclude);
+    for (const g of groups) {
+      if (g.ids.length < 2) continue;
+      const cid = 'c-' + g.ids[0];
+      const sig = g.ids.join(',');
+      if (state.candidates[cid] === sig) continue;
+      const topic = [...g.terms].slice(0, 8);
+      append({ row: 'candidate', candidate: cid, segments: g.ids, topic_terms: topic, status: 'proposed',
+        prior_rejection_check: prior.check(topic) });
+      state.candidates[cid] = sig;
+    }
+  }
+
+  /** Run 3: what an agent should write, on which tier. Recorded in the D75 ledger only where the PM opted in. */
+  function plan() {
+    const p = contextPlan({ root, rows: readLedger(P.ledger), items });
+    const core = modelCore();
+    if (core && core.logDecision) {
+      for (const x of p.context) if (!x.done) core.logDecision(root, { kind: 'live-notes-plan', step: 'context-note', segment: x.segment, tier: x.tier, by: 'live-notes' });
+      for (const x of p.candidates) if (!x.done) core.logDecision(root, { kind: 'live-notes-plan', step: 'candidate-draft', candidate: x.candidate, tier: x.tier, by: 'live-notes' });
+    }
+    return p;
+  }
+
+  /** Run 3: a context note, checked. The proposal row is never touched; the note is a row of its own. */
+  function addContext(entries) {
+    const rows = readLedger(P.ledger);
+    const planned = new Map(contextPlan({ root, rows, items }).context.map((x) => [x.segment, x]));
+    const accepted = []; const rejected = [];
+    for (const e of entries) {
+      const why = (m) => rejected.push({ segment: e && e.segment, reason: m });
+      if (!e || typeof e.segment !== 'string') { why('no segment named'); continue; }
+      const x = planned.get(e.segment);
+      if (!x) { why('that point needs no note, or does not exist'); continue; }
+      if (typeof e.note !== 'string' || !oneLine(e.note) || oneLine(e.note).length > MAX_NOTE) { why('a note is 1 to ' + MAX_NOTE + ' characters'); continue; }
+      if (typeof e.settled !== 'boolean') { why('say whether the initiative\'s own text settled the point (settled: true or false)'); continue; }
+      if (!Array.isArray(e.cites) || !e.cites.length || e.cites.length > 5) { why('a note cites 1 to 5 passages of the repository'); continue; }
+      const bad = e.cites.map((c) => checkCite(root, exclude, c)).find(Boolean);
+      if (bad) { why(bad); continue; }
+      const row = { row: 'context', at: Date.now(), segment: e.segment, initiative: x.initiative, note: oneLine(e.note), settled: e.settled, tier: x.tier,
+        cites: e.cites.map((c) => ({ path: c.path.replace(/\\/g, '/').replace(/^\/+/, ''), quote: oneLine(c.quote).slice(0, 200) })), status: 'proposed' };
+      append(row); accepted.push(row);
+    }
+    return { accepted, rejected };
+  }
+
+  /** Run 3: a title and lane for a candidate. A proposal; an initiative exists only if the PM presses through the router. */
+  function addDrafts(entries) {
+    const rows = readLedger(P.ledger);
+    const cands = foldCandidates(rows);
+    const prior = priorRejections(root, exclude);
+    const accepted = []; const rejected = [];
+    for (const e of entries) {
+      const why = (m) => rejected.push({ candidate: e && e.candidate, reason: m });
+      if (!e || !cands.has(e.candidate)) { why('no such candidate in this session'); continue; }
+      const title = oneLine(e.title);
+      if (!title || title.length > MAX_TITLE) { why('a title is 1 to ' + MAX_TITLE + ' characters'); continue; }
+      if (!LANES.includes(e.lane)) { why('lane is one of: ' + LANES.join(', ')); continue; }
+      const row = { row: 'candidate_draft', at: Date.now(), candidate: e.candidate, title, lane: e.lane, tier: 'deep', status: 'proposed',
+        prior_rejection_check: prior.check([...terms(title)]), next_step: 'a proposal only: an initiative exists when the PM presses through pmos-router' };
+      append(row); accepted.push(row);
+    }
+    return { accepted, rejected };
+  }
+
+  /** The PM's accept, change or reject. Appended; never overwrites a proposal. */
+  function decide({ segment, action, initiative = null, relation = null, by = 'pm' }) {
+    if (!['accept', 'change', 'reject'].includes(action)) throw new Error('action is accept, change or reject');
+    const prop = readLedger(P.ledger).filter((r) => r.row === 'segment' && r.segment === segment).pop();
+    if (!prop) throw new Error('no such segment in this session: ' + segment);
+    if (prop.status !== 'proposed') throw new Error('that segment has no proposal yet, so there is nothing to accept or change');
+    if (action === 'change') {
+      if (initiative && initiative !== 'none' && !ids.includes(initiative)) throw new Error('that initiative is not in the shortlist');
+      if (relation && !RELATIONS.includes(relation)) throw new Error('relation is one of: ' + RELATIONS.join(', '));
+      if (!initiative && !relation) throw new Error('a change names an initiative, a relation, or both');
+    }
+    const row = { row: 'decision', segment, action, by, proposed_by: prop.path === 'jev' || prop.path === 'jev-agent' ? 'jev' : 'agent', was: { initiative: prop.initiative, relation: prop.relation },
+      now: action === 'change' ? { initiative: initiative || prop.initiative, relation: relation || prop.relation } : null, overridden: action !== 'accept' };
+    append(row);
+    return row;
+  }
+
+  /** Close: a summary section in the day's requirements note, then the transcript goes (or is dated to go). */
+  function close({ retentionDays = 0, at = Date.now() } = {}) {
+    if (state.closed) return { already: true };
+    const rows = readLedger(P.ledger);
+    const latest = new Map();
+    for (const r of rows) if (r.row === 'segment') latest.set(r.segment, r);
+    const decisions = new Map();
+    for (const r of rows) if (r.row === 'decision') decisions.set(r.segment, r);
+    const cands = new Map();
+    for (const r of rows) if (r.row === 'candidate') cands.set(r.candidate, r);
+    const ctx = new Map(); for (const r of rows) if (r.row === 'context') ctx.set(r.segment, r);
+    const drafts = new Map(); for (const r of rows) if (r.row === 'candidate_draft') drafts.set(r.candidate, r);
+    const note = writeNote({ root, session: id, at, items: [...latest.values()], decisions, ctx, drafts, candidates: [...cands.values()], withheld: rows.filter((r) => r.row === 'withheld').length, path: route, paused: state.paused });
+    append({ row: 'close', at, segments: latest.size, note: note.rel, transcript_kept_until: retentionDays > 0 ? nowISO(at + retentionDays * 86400000) : null });
+    state.closed = true;
+    if (retentionDays > 0) writeJson(path.join(P.dir, 'expires.json'), { at: nowISO(at + retentionDays * 86400000) });
+    else { try { fs.rmSync(P.dir, { recursive: true, force: true }); } catch { /* reported by the test */ } return { note: note.rel, transcript: 'deleted' }; }
+    save();
+    return { note: note.rel, transcript: 'kept until ' + nowISO(at + retentionDays * 86400000) };
+  }
+
+  return { id, paths: P, items, shortlistError: sl.ok ? null : sl.error, path: route, gates: g, add, answer, plan, addContext, addDrafts, decide, close, ledger: () => readLedger(P.ledger), state: () => ({ ...state }) };
+}
+
+/** Delete transcripts whose retention has passed. */
+function purgeExpired(runtimeDir, now = Date.now()) {
+  const base = path.join(runtimeDir, 'live-notes');
+  let n = 0;
+  let entries = []; try { entries = fs.readdirSync(base, { withFileTypes: true }); } catch { return 0; }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const x = readJson(path.join(base, e.name, 'expires.json'), null);
+    if (x && Date.parse(x.at) <= now) { fs.rmSync(path.join(base, e.name), { recursive: true, force: true }); n++; }
+  }
+  return n;
+}
+
+/** The prior-rejection check the router makes, against planning/out-of-scope/. A hit is information, never a veto. */
+function priorRejections(root, exclude) {
+  const dir = path.join(root, 'planning', 'out-of-scope');
+  let files = [];
+  try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !/^(README|index|log)\.md$/i.test(f)); } catch { /* none */ }
+  const docs = [];
+  for (const f of files) {
+    const r = 'planning/out-of-scope/' + f;
+    if (isExcluded(exclude, r)) continue;
+    try { const t = fs.readFileSync(path.join(dir, f), 'utf8'); docs.push({ path: r, title: frontmatter(t).title || f, terms: terms(t) }); } catch { /* skip */ }
+  }
+  return {
+    check: (topic) => {
+      const topicSet = new Set(topic);
+      const matches = docs.map((d) => ({ path: d.path, title: d.title, shared: overlap(topicSet, d.terms) })).filter((m) => m.shared >= 2).sort((a, b) => b.shared - a.shared).slice(0, 3);
+      return { ran: true, source: 'planning/out-of-scope', documents_read: docs.length, found: matches.length, matches };
+    },
+  };
+}
+
+/* ── the day's requirements note (D71's shape; append, never overwrite) ──────────────────────────── */
+function writeNote({ root, session, at, items, decisions, ctx = new Map(), drafts = new Map(), candidates, withheld, path: pathName, paused }) {
+  const day = nowISO(at).slice(0, 10); const hm = nowISO(at).slice(11, 16);
+  const dir = path.join(stateDirIn(root), 'requirements');
+  const file = path.join(dir, day + '.md');
+  const word = { contradicts: 'contradicts', answers: 'answers an open question of', validates: 'validates', clarifies: 'clarifies', extends: 'extends' };
+  const line = (r) => {
+    const dec = decisions.get(r.segment);
+    const where = r.initiative && r.initiative !== 'none' ? `${word[r.relation] || r.relation} \`${r.initiative}\` (${r.relation_band})` : 'matches no initiative';
+    const tail = dec ? ` — PM: ${dec.action}${dec.now ? ' → ' + [dec.now.initiative, dec.now.relation].filter(Boolean).join(' / ') : ''}` : '';
+    const c = ctx.get(r.segment);
+    const more = c ? `\n  - context (${c.tier}; ${c.settled ? 'the initiative\'s text settles it' : 'the initiative\'s text does not settle it'}): ${c.note} [${c.cites.map((x) => x.path).join(', ')}]` : '';
+    return `- "${r.quote}" — ${where}; ${r.confidence}${r.in_scope === false ? '; outside scope' : ''}; pointer: live · ${r.pointer.source} · ${r.pointer.id} · ${r.at}${tail}${more}`;
+  };
+  const answered = items.filter((r) => r.status === 'proposed');
+  const body = [];
+  body.push(`## Live notes ${hm} (session ${session})`, '');
+  body.push(`Proposals only: nothing here is a decision. Path: ${pathName}.${paused ? ' ' + paused.reason : ''}`, '');
+  body.push('### New or changed requirements', ...(answered.filter((r) => ['extends', 'clarifies', 'none'].includes(r.relation)).map(line) || []), '');
+  body.push('### Validations and contradictions', ...answered.filter((r) => ['validates', 'contradicts'].includes(r.relation)).sort((a, b) => (a.relation === 'contradicts' ? -1 : 1) - (b.relation === 'contradicts' ? -1 : 1)).map(line), '');
+  body.push('### Open questions', ...answered.filter((r) => r.relation === 'answers').map((r) => line(r) + (r.answers_question ? `; answers: ${r.answers_question.text}` : '')),
+    ...candidates.map((c) => { const d = drafts.get(c.candidate); return `- Possible new initiative (${c.segments.length} points about: ${c.topic_terms.join(', ')}); prior-rejection check found ${c.prior_rejection_check.found}.${d ? ` Draft: "${d.title}" (${d.lane} lane; prior-rejection check on the title found ${d.prior_rejection_check.found}). A proposal; the PM presses through pmos-router to create it.` : ''}`; }), '');
+  body.push('### Sources reached and not reached', `- live conversation: ${items.length} point(s) proposed, ${items.filter((r) => r.status === 'pending').length} still unanswered, ${withheld} withheld (secret-shaped or private-marked, not read further).`, '');
+  fs.mkdirSync(dir, { recursive: true });
+  let exists = false;
+  try { const ls = fs.lstatSync(file); if (ls.isSymbolicLink() || ls.nlink > 1) throw new Error('the requirements note is a link, so nothing was written'); exists = true; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  if (exists) {
+    fs.appendFileSync(file, '\n' + body.join('\n'));
+  } else {
+    const head = ['---', 'type: Reference', `title: "Requirement note ${day}"`, 'description: "Requirements found in the PM\'s sources since the previous note."',
+      `generated: {by: pmos/live-notes, at: "${nowISO(at)}"}`, `sources: [{resource: "live-notes/${session}", title: "live conversation"}]`, 'status: draft', '---', '', `# Requirement note ${day}`, '', ''];
+    fs.writeFileSync(file, head.join('\n') + body.join('\n'));
+  }
+  return { rel: rel(root, file) };
+}
+
+
+/* ── Run 2: the ranked list (N12) and the two routes' logic, without a page ──────────────────────── */
+const BAND_RANK = { 'very likely': 3, likely: 2, possible: 1, unlikely: 0 };
+const WEAK_BANDS = new Set(['possible', 'unlikely']);
+const SECTION_TITLES = {
+  contradictions: 'Contradictions', answers: 'Answers an open question', confirmations: 'Confirmed or validated', rest: 'Other points',
+  needs_read: 'Needs your read', unmatched: 'Matches no initiative', pending: 'Not yet answered',
+};
+const SECTION_ORDER = ['contradictions', 'answers', 'confirmations', 'rest', 'needs_read', 'unmatched', 'pending'];
+
+function rank(rows) {
+  const segs = foldSegments(rows);
+  const decisions = new Map(); for (const r of rows) if (r.row === 'decision') decisions.set(r.segment, r);
+  const ctx = new Map(); for (const r of rows) if (r.row === 'context') ctx.set(r.segment, r);
+  const drafts = new Map(); for (const r of rows) if (r.row === 'candidate_draft') drafts.set(r.candidate, r);
+  const sections = Object.fromEntries(SECTION_ORDER.map((k) => [k, []]));
+  for (const [id, r] of segs) {
+    const d = decisions.get(id); const c = ctx.get(id);
+    const item = { segment: id, quote: r.quote, status: r.status, initiative: r.initiative, relation: r.relation, relation_band: r.relation_band || null, initiative_band: r.initiative_band || null,
+      in_scope: r.in_scope, confidence: r.confidence, flags: r.flags || [], answers_question: r.answers_question || null, path: r.path, at: r.at,
+      decision: d ? { action: d.action, now: d.now, overridden: d.overridden } : null,
+      context: c ? { note: c.note, settled: c.settled, tier: c.tier, cites: c.cites.map((x) => x.path) } : null };
+    let key;
+    if (r.status === 'pending') key = 'pending';
+    else if (!r.initiative || r.initiative === 'none') key = 'unmatched';
+    else if ((r.flags && r.flags.length) || WEAK_BANDS.has(r.relation_band) || WEAK_BANDS.has(r.initiative_band)) key = 'needs_read';
+    else if (r.relation === 'contradicts') key = 'contradictions';
+    else if (r.relation === 'answers') key = 'answers';
+    else if (r.confidence === 'confirmed' || r.relation === 'validates') key = 'confirmations';
+    else key = 'rest';
+    sections[key].push(item);
+  }
+  const score = (x) => (BAND_RANK[x.relation_band] != null ? BAND_RANK[x.relation_band] : -1) * 4 + (BAND_RANK[x.initiative_band] != null ? BAND_RANK[x.initiative_band] : -1);
+  for (const k of SECTION_ORDER) sections[k].sort((a, b) => score(b) - score(a) || (a.at < b.at ? -1 : a.at > b.at ? 1 : 0) || (a.segment < b.segment ? -1 : 1));
+  const paused = rows.filter((r) => r.row === 'pause').pop() || null;
+  const cands = [...foldCandidates(rows).values()].map((c) => { const d = drafts.get(c.candidate); return { candidate: c.candidate, segments: c.segments, topic_terms: c.topic_terms, prior_rejection_found: c.prior_rejection_check ? c.prior_rejection_check.found : null, draft: d ? { title: d.title, lane: d.lane } : null }; });
+  return {
+    sections: SECTION_ORDER.map((k) => ({ key: k, title: SECTION_TITLES[k], items: sections[k] })).filter((x) => x.items.length),
+    candidates: cands,
+    withheld: rows.filter((r) => r.row === 'withheld').length,          // a count only: the text is never shown
+    paused: paused ? { reason: paused.reason, at: paused.at } : null,
+    path: (rows.find((r) => r.row === 'session') || {}).path || null,
+    closed: rows.some((r) => r.row === 'close'),
+    counts: { points: segs.size, pending: sections.pending.length },
+  };
+}
+
+/** The repository's sessions, from its ledgers. Reads only. */
+function sessionsOf(root) {
+  const dir = path.join(stateDirIn(root), 'live-notes');
+  let files = []; try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')).sort(); } catch { return []; }
+  return files.map((f) => {
+    const rows = readLedger(path.join(dir, f));
+    const segs = foldSegments(rows);
+    const first = rows.find((r) => r.row === 'session');
+    const pause = rows.filter((r) => r.row === 'pause').pop();
+    return { session: f.replace(/\.jsonl$/, ''), started: first ? first.at : null, path: first ? first.path : null, closed: rows.some((r) => r.row === 'close'),
+      points: segs.size, pending: [...segs.values()].filter((r) => r.status === 'pending').length, decided: rows.filter((r) => r.row === 'decision').length,
+      withheld: rows.filter((r) => r.row === 'withheld').length, paused: pause ? pause.reason : null };
+  });
+}
+const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,60}$/;
+/** GET: the sessions, or one session ranked. Reads only; writes nothing. */
+function apiList({ root, session = null }) {
+  if (!root) return { ok: false, status: 400, error: 'no repository' };
+  if (!session) return { ok: true, sessions: sessionsOf(root), note: 'Proposals only. Nothing here is a decision.' };
+  if (!SESSION_RE.test(session)) return { ok: false, status: 400, error: 'that is not a session id' };
+  const file = path.join(stateDirIn(root), 'live-notes', session + '.jsonl');
+  if (!fs.existsSync(file)) return { ok: false, status: 404, error: 'no such session in this repository' };
+  return { ok: true, session, ranked: rank(readLedger(file)), note: 'Proposals only. Nothing here is a decision.' };
+}
+/** POST: append the PM's accept, change or reject. Nothing else is written. */
+function apiDecide({ root, runtimeDir, session, segment, action, initiative = null, relation = null, exclude = [] }) {
+  if (!root) return { ok: false, status: 400, error: 'no repository' };
+  if (!SESSION_RE.test(String(session || ''))) return { ok: false, status: 400, error: 'that is not a session id' };
+  if (!fs.existsSync(path.join(stateDirIn(root), 'live-notes', session + '.jsonl'))) return { ok: false, status: 404, error: 'no such session in this repository' };
+  try {
+    const s = openSession({ root, runtimeDir, session, key: null, flags: {}, exclude, ask: null });
+    const row = s.decide({ segment, action, initiative, relation, by: 'pm' });
+    return { ok: true, decision: row };
+  } catch (e) { return { ok: false, status: 400, error: String((e && e.message) || e) }; }
+}
+
+/* ── the override rate (N13): the first measure, never an accuracy claim ─────────────────────────── */
+function overrideRate(rows) {
+  const by = {};
+  const seg = new Map();
+  for (const r of rows) if (r.row === 'segment' && r.status === 'proposed') seg.set(r.segment, r);
+  const dec = new Map();
+  for (const r of rows) if (r.row === 'decision') dec.set(r.segment, r);
+  for (const [id, s] of seg) {
+    const p = s.path === 'jev' || s.path === 'jev-agent' ? s.path : 'agent-only';
+    by[p] = by[p] || { proposed: 0, decided: 0, overridden: 0 };
+    by[p].proposed++;
+    const d = dec.get(id);
+    if (d) { by[p].decided++; if (d.overridden) by[p].overridden++; }
+  }
+  for (const p of Object.keys(by)) by[p].override_rate = by[p].decided ? by[p].overridden / by[p].decided : null;
+  return by;
+}
+
+module.exports = { rank, sessionsOf, apiList, apiDecide, segmentsFromTranscript, contextPlan, parseContext, parseDrafts, checkCite, LANES, openSession, purgeExpired, getSwitch, setSwitch, gates, gateSentence, band, shortlist, loadInitiatives, openQuestionsOf, requestFor,
+  mapJev, parseAgentAnswers, agentPrompt, normalizeSegments, overrideRate, readLedger, sessionPaths, stateDirIn, isExcluded, RELATIONS, MAX_CHOICE, REJECTED_LIMIT, UNREACHABLE_LIMIT };