create-pmos 0.516.0 → 0.518.0

package/workspace/lib/report-engine.js

@@ -0,0 +1,779 @@
+'use strict';
+/* report-engine.js — THE REPORT ENGINE (design E, agreed by Wawan 2026-11-03 "Build."; canvas In development EgN1–EgN4, brief
+ * /mnt/project-files/intelligence-grill/brief-E-R-build.md). One path for every report, ad hoc from a chat line or recurring from a definition,
+ * any domain:
+ *
+ *     brief → read → find → answer → render
+ *
+ * THERE IS NO FRAME. Nothing in this file holds a section list. The writer (skills/report-write.skill, an agent) chooses the outline of each
+ * report from its readers and their question; a recurring report keeps the outline its readers agreed (the last issued issue's sections) and the
+ * writer still adds or drops a section when the findings call for it. What this file fixes is only the discipline:
+ *   - the answer comes first and carries a reading;
+ *   - every figure in the writer's words is a reading token {{r:<id>}}, so it is sourced and dated by construction (a bare number is refused);
+ *   - the ask names who and by, or lays out the options;
+ *   - the gaps are named, never silent;
+ *   - an addition beyond the ask (why, so what, now what, since last issue, what would change it, what we don't know, what else is here, the next
+ *     question) is drawn only when it cites a reading.
+ *
+ * THE FILES, next to the draft, <state>/reports/<id>/<slot>.*  (each written atomically; the two rule ledgers are append-only):
+ *   <slot>.brief.json     step 1, briefOf: readers, the question(s), the window, the sources by name, the last issue, the agreed outline, the
+ *                         carried asks, the rules (voice, parts turned off). Derived, never asked. No section list.
+ *   <slot>.readings.json  step 2, readingsOf: { readings: [{ id, value, unit, at, source, how, label, … }], gaps: [{ source, reason, affects }] }
+ *   <slot>.findings.json  step 3, findingsOf: { findings: [{ id, kind, text, readings, weight, question }], none }. none → no draft.
+ *   <slot>.report.json    step 4, written by the report-write skill through `pmos report write` (checkReport refuses one with no answer or a bare figure)
+ *   <slot>.checks.json    step 6, checkReport: the six substance checks, then the form checks of lib/report-checks.js
+ *   <slot>.md             step 5, renderMarkdown: the document the Library, the reader's Document tab and the exports read
+ *   the deck              step 5, deckOf: drawn on demand from report.json in the report's look (lib/report-pyramid.js lookOf = the saved design
+ *                         D<n> as a theme). The reader, the PDF and the PPTX are the same slides.
+ *   rules.jsonl           { ev: 'add'|'remove', n, kind, text, part, from, at, by } — what the readers taught the writer (step 8)
+ *   asks.jsonl            { ev: 'closed', text, at, by } — a carried ask is carried into every next brief until the PM closes it with ✓
+ *
+ *   paths(root, id, slot)                   → the absolute and repository-relative paths above
+ *   briefOf(root, id, { slot, ask, readers, sources, now }) → { ok, brief } | { ok: false, status, error }
+ *   readingsOf(root, brief, { add, gaps, keep, now })      → { ok, readings, gaps } | refusal      (add = readings the writer filed)
+ *   findingsOf(brief, readings, { prior, add })            → { findings, none }
+ *   resolve(text, readings)                 → text with every {{r:…}} written out; unresolved ids come back in .missing
+ *   checkReport(report, { brief, readings, findings, markdown }) → [{ id, pass, reason, hard }]
+ *   renderMarkdown(report, { brief, readings }) → the document
+ *   deckOf(report, { brief, readings, look }) → { slides, look, name }  (lib/report-pyramid.js deckHtml draws it)
+ *   make(root, id, opts)                    → steps 1–3 written: { ok, brief, readings, findings, paths }
+ *   write(root, id, slot, report, { actor, now }) → steps 4–6 written: { ok, path, checks } | refusal (422 with the failed checks)
+ *   engineReportOf(absMd)                   → { report, brief, readings } for a draft the engine wrote, else null
+ *   addRule / removeRule / rulesOf, closeAsk
+ *
+ * WHO WRITES. No model runs here. A brief, its readings from local files and its findings are derived by the script; readings from a connector
+ * (Jira, BigQuery/GA4, …) or a document are read by the writer in the interactive agent runtime and filed with `pmos report read --add`, each with
+ * its source, date and how it was read. A source the brief names that nothing read is a gap. The PM issues (lib/report-cli.js, unchanged).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const READING_ID_RE = /^[a-z0-9][a-z0-9._-]{0,80}$/;
+const SOURCE_ID_RE = /^[a-z0-9][a-z0-9._-]{0,40}$/;
+const TOKEN_RE = /\{\{r:([a-z0-9][a-z0-9._-]{0,80})(?:\|(of|n|value|label))?\}\}/g;
+const DAY = 86400000;
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const CYCLE_DAYS = { daily: 1, weekly: 7, biweekly: 14, 'bi-weekly': 14, monthly: 30, quarterly: 91 };
+const LIMITS = Object.freeze({ readings: 2000, findings: 60, sections: 30, blocks: 40, rows: 60, cols: 12, text: 2000, title: 240, rules: 60 });
+/** The parts beyond the ask (frame EgN3), in the order the document and the deck draw them. */
+const BEYOND = Object.freeze([
+  ['why', 'Why'], ['so_what', 'So what'], ['now_what', 'Now what'], ['since', 'Since the last issue'],
+  ['would_change', 'What would change it'], ['unknown', 'What we don’t know'], ['else', 'What else is here'], ['next_question', 'The next question'],
+]);
+const BEYOND_KEYS = BEYOND.map(([k]) => k);
+/** The default voice of every report, from Wawan's own design turns of 21 October 2026 (frame EgN3). A brief may narrow it, never widen it. */
+const VOICE = Object.freeze([
+  'Neutral and straightforward sentences.',
+  'The number in the sentence, its source under it.',
+  'Coherent, succinct, synthesized: one thought per slide, one claim per paragraph.',
+  'No audience confusion: a leadership report does not carry the engineering appendix; it links to it.',
+  'Dates in full.',
+  'The mood is never happier than the data: 0% is written as 0%, with its why.',
+]);
+const RULE_KINDS = Object.freeze(['voice', 'wording', 'off', 'keep']);
+const BLOCK_KINDS = Object.freeze(['p', 'list', 'table', 'bars', 'options', 'quote']);
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string';
+const str = (v) => (isStr(v) ? v : v == null ? '' : String(v));
+const refuse = (status, error, extra = {}) => ({ ok: false, status, error, ...extra });
+const isDate = (s) => isStr(s) && DATE_RE.test(s) && new Date(s + 'T00:00:00Z').toISOString().slice(0, 10) === s;
+const dayOf = (t) => new Date(t).toISOString().slice(0, 10);
+const addDays = (ymd, n) => dayOf(Date.parse(ymd + 'T00:00:00Z') + n * DAY);
+/** "21 October 2026" from YYYY-MM-DD or an ISO time (the dates-in-full rule). */
+function full(v) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(str(v));
+  return m ? `${Number(m[3])} ${MONTHS[Number(m[2]) - 1]} ${m[1]}` : str(v);
+}
+const slugOf = (s) => str(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+const clip = (s, n) => { const t = str(s).replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1).replace(/\s+\S*$/, '') + '…' : t; };
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex').slice(0, 12);
+
+function readJson(file) { try { const o = JSON.parse(fs.readFileSync(file, 'utf8')); return isObj(o) ? o : null; } catch { return null; } }
+function readJsonl(file) {
+  let text; try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) { if (!raw.trim()) continue; try { const o = JSON.parse(raw); if (isObj(o)) out.push(o); } catch { /* skipped */ } }
+  return out;
+}
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, data, { flag: 'wx' });
+  fs.renameSync(tmp, file);
+}
+const writeJson = (file, o) => writeAtomic(file, JSON.stringify(o, null, 2) + '\n');
+function appendLine(file, o) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.appendFileSync(file, JSON.stringify(o) + '\n'); }
+
+// lazy: report-draft.js loads the kit engine, which a pure caller (the renderer in a test) never needs
+const RD = () => require('./report-draft.js');
+const issuesLib = () => require('./issues.js');
+
+function stateRel(root) { try { return RD().stateRel(root); } catch { return fs.existsSync(path.join(path.resolve(String(root)), 'pmos', 'state')) ? 'pmos/state' : 'planning'; } }
+
+// ── paths ───────────────────────────────────────────────────────────────────────────────────────────────────────────
+function paths(root, id, slot) {
+  if (!ID_RE.test(str(id))) throw new Error('the report id is lower case letters, digits and dashes, at most 40, starting with a letter');
+  if (slot != null && !isDate(slot)) throw new Error('the slot is a date, YYYY-MM-DD');
+  const abs = path.resolve(String(root));
+  const relDir = `${stateRel(abs)}/reports/${id}`;
+  const dir = path.join(abs, relDir);
+  const at = (ext) => (slot ? { abs: path.join(dir, `${slot}${ext}`), rel: `${relDir}/${slot}${ext}` } : null);
+  return { root: abs, dir, relDir, md: at('.md'), brief: at('.brief.json'), readings: at('.readings.json'), findings: at('.findings.json'),
+    report: at('.report.json'), checks: at('.checks.json'), rules: path.join(dir, 'rules.jsonl'), asks: path.join(dir, 'asks.jsonl') };
+}
+
+// ── the rules the readers taught (step 8) and the carried asks ─────────────────────────────────────────────────────────
+function rulesOf(root, id) {
+  const rows = readJsonl(paths(root, id).rules);
+  const live = new Map();
+  for (const r of rows) {
+    if (r.ev === 'add' && Number.isInteger(r.n) && RULE_KINDS.includes(r.kind)) live.set(r.n, { n: r.n, kind: r.kind, text: str(r.text), part: r.part || null, from: str(r.from) || null, at: r.at || null });
+    else if (r.ev === 'remove' && Number.isInteger(r.n)) live.delete(r.n);
+  }
+  return [...live.values()].sort((a, b) => a.n - b.n);
+}
+function addRule(root, id, { kind, text, part, from, by, now } = {}) {
+  if (!RULE_KINDS.includes(kind)) return refuse(400, `the kind is one of ${RULE_KINDS.join(', ')}`);
+  if (kind === 'off' || kind === 'keep') { if (!BEYOND_KEYS.includes(part)) return refuse(400, `a ${kind} rule names a part beyond the ask: ${BEYOND_KEYS.join(', ')}`); }
+  else if (!str(text).trim() || str(text).length > 300 || /[\r\n]/.test(str(text))) return refuse(400, 'the rule is one line of at most 300 characters');
+  const all = readJsonl(paths(root, id).rules);
+  if (rulesOf(root, id).length >= LIMITS.rules) return refuse(409, `a report keeps at most ${LIMITS.rules} rules; remove one first`);
+  const n = all.reduce((m, r) => Math.max(m, Number.isInteger(r.n) ? r.n : 0), 0) + 1;
+  const line = { ev: 'add', n, kind, text: str(text).trim() || null, part: part || null, from: str(from).slice(0, 120) || null, at: new Date(now || Date.now()).toISOString(), by: str(by) || null };
+  appendLine(paths(root, id).rules, line);
+  return { ok: true, rule: line };
+}
+function removeRule(root, id, n, { by, now } = {}) {
+  if (!rulesOf(root, id).some((r) => r.n === Number(n))) return refuse(404, `there is no rule ${n}`);
+  appendLine(paths(root, id).rules, { ev: 'remove', n: Number(n), at: new Date(now || Date.now()).toISOString(), by: str(by) || null });
+  return { ok: true };
+}
+function closedAsks(root, id) { return new Set(readJsonl(paths(root, id).asks).filter((r) => r.ev === 'closed').map((r) => str(r.text).trim().toLowerCase())); }
+function closeAsk(root, id, text, { by, now } = {}) {
+  if (!str(text).trim()) return refuse(400, 'name the ask to close');
+  appendLine(paths(root, id).asks, { ev: 'closed', text: str(text).trim(), at: new Date(now || Date.now()).toISOString(), by: str(by) || null });
+  return { ok: true };
+}
+
+// ── step 1 · the brief ──────────────────────────────────────────────────────────────────────────────────────────────
+/** A definition's "## Sources" bullets as named sources. A bullet that names the ledgers is the pmos source. */
+function sourcesFromText(lines) {
+  const out = [];
+  for (const raw of lines) {
+    const t = str(raw).replace(/^[-*]\s+/, '').trim();
+    if (!t) continue;
+    let kind = 'document', id = slugOf(t.split(/[,(—:]/)[0]) || 'source';
+    const file = /(?:^|\s|`)((?:pmos\/|planning\/|docs\/)?[\w./-]+\.(?:md|json|jsonl|csv|html))\b/.exec(t);
+    if (file) { if (!out.some((s) => s.ref === file[1])) out.push({ id: slugOf(path.basename(file[1]).replace(/\.[a-z]+$/i, '')).slice(0, 40) || 'document', kind: 'document', name: clip(t, 200), ref: file[1] }); continue; }
+    if (/\bledgers?\b|\bpmos\b/i.test(t) && !/\bjira\b|\bga4\b|bigquery/i.test(t)) { kind = 'pmos'; id = 'pmos'; }
+    else if (/\bga4\b|bigquery|\bevents?\b/i.test(t)) { kind = 'connector'; id = 'ga4'; }
+    else if (/\bjira\b/i.test(t)) { kind = 'connector'; id = 'jira'; }
+    else if (/\bconfluence\b|\bslack\b|\bmail\b|\bcalendar\b|\bdrive\b|\bnew relic\b|\bservicenow\b/i.test(t)) kind = 'connector';
+    if (!out.some((s) => s.id === id)) out.push({ id, kind, name: clip(t, 200) });
+  }
+  return out;
+}
+function sectionLines(text, heading) {
+  const m = new RegExp(`\\n## ${heading}\\r?\\n([\\s\\S]*?)(?=\\n## |$)`).exec(str(text));
+  return m ? m[1].split(/\r?\n/).filter((l) => /^\s*[-*]\s+/.test(l)) : [];
+}
+/** --source kind:ref → a named source. kinds: pmos · pack (a readings file under the state dir) · connector:<name> · document:<path> */
+function parseSource(spec) {
+  const m = /^(pmos|pack|connector|document):?([^=]*)(?:=(.+))?$/.exec(str(spec).trim());
+  if (!m) return null;
+  const name = m[3] ? clip(m[3], 200) : null;
+  if (m[1] === 'pmos') return { id: 'pmos', kind: 'pmos', name: name || 'PMOS ledgers' };
+  const ref = m[2].trim();
+  if (!ref) return null;
+  if (m[1] === 'connector') return { id: slugOf(ref).slice(0, 40) || 'connector', kind: 'connector', name: name || ref };
+  return { id: slugOf(path.basename(ref).replace(/\.[a-z]+$/i, '')).slice(0, 40) || m[1], kind: m[1], name: name || path.basename(ref), ref };
+}
+function latestPlan(root, id) {
+  const dir = path.join(paths(root, id).dir, 'structure', 'versions');
+  let names = []; try { names = fs.readdirSync(dir).filter((f) => /^S\d+\.json$/.test(f)); } catch { return null; }
+  names.sort((a, b) => Number(a.slice(1, -5)) - Number(b.slice(1, -5)));
+  return names.length ? { plan: readJson(path.join(dir, names[names.length - 1])), file: names[names.length - 1] } : null;
+}
+/** The issued slots of a report, newest last (lib/issues.js). */
+function issuedSlots(root, id) {
+  try { return issuesLib().readIssues(root).issues.filter((i) => i.cadence === id).map((i) => i.slot).sort(); } catch { return []; }
+}
+/** The headings of a document the engine did not write: the agreed outline of an older issue. */
+const headingsOf = (md) => str(md).replace(/^---[\s\S]*?\n---\n?/, '').split('\n').filter((l) => /^## /.test(l)).map((l) => l.slice(3).trim()).filter(Boolean);
+
+function briefOf(root, id, { slot, ask, readers, sources, now = Date.now() } = {}) {
+  if (!ID_RE.test(str(id))) return refuse(400, 'the report id is lower case letters, digits and dashes, at most 40, starting with a letter');
+  const today = slot || dayOf(now);
+  if (!isDate(today)) return refuse(400, 'the slot is a date, YYYY-MM-DD');
+  const abs = path.resolve(String(root));
+  const P = paths(abs, id, today);
+  const from = [];
+  const brief = { v: 1, id, slot: today, title: null, readers: null, question: null, questions: [], decision: null, window: null, sources: [], recurring: false,
+    cycle_days: null, agreed_outline: [], earlier_outline: [], last_issue: null, carried_asks: [], rules: [], voice: VOICE.slice(), from };
+
+  // the definition: readers, the question (its purpose), the sources, the cadence
+  let def = null; let defText = '';
+  try { def = RD().readDefinition(abs, id); } catch { def = null; }
+  if (def && def.exists) {
+    try { defText = fs.readFileSync(path.join(abs, def.path), 'utf8'); } catch { defText = ''; }
+    from.push(def.path);
+    brief.recurring = true;
+    brief.title = def.name || null;
+    brief.readers = def.audience || null;
+    if (def.purpose) brief.question = def.purpose;
+    brief.sources.push(...sourcesFromText(sectionLines(defText, 'Sources')));
+    const cad = /\ncadence:\s*["']?([a-z-]+)/.exec(defText);
+    const sched = /\n## Schedule\r?\n\r?\n([^\n]+)/.exec(defText);
+    const word = (sched && /daily|weekly|biweekly|bi-weekly|monthly|quarterly/i.exec(sched[1])) || (cad && /daily|weekly|biweekly|monthly/.exec(cad[1]));
+    brief.cycle_days = word ? CYCLE_DAYS[word[0].toLowerCase()] || null : null;
+  }
+  // the saved structure plan: its purpose block is the brief's intake; its section plan is not read (the writer chooses the outline)
+  const pl = latestPlan(abs, id);
+  if (pl && pl.plan && isObj(pl.plan.purpose)) {
+    const pu = pl.plan.purpose;
+    from.push(`${P.relDir}/structure/versions/${pl.file}`);
+    if (!brief.readers && pu.readers) brief.readers = str(pu.readers);
+    if (pu.decision) brief.decision = str(pu.decision);
+    if (Array.isArray(pu.questions)) brief.questions.push(...pu.questions.map(str).filter(Boolean));
+    brief.recurring = brief.recurring || !!pu.cadence;
+  }
+  // the recurring report's setup (lib/report-setups.js): its name and readers
+  try {
+    const setup = require('./report-setups.js').stateOf(abs).setups.get(id);
+    if (setup) { from.push(`setup:${id}`); brief.title = brief.title || setup.name || null; brief.readers = brief.readers || setup.audience || null; brief.recurring = true; }
+  } catch { /* no setups ledger */ }
+  // the chat line: an ad hoc report's question, or a sharper question for this issue
+  if (str(ask).trim()) { from.push('chat'); brief.question = clip(ask, 400); }
+  if (str(readers).trim()) { from.push('readers'); brief.readers = clip(readers, 300); }
+  for (const s of (Array.isArray(sources) ? sources : [])) { const x = isObj(s) ? s : parseSource(s); if (x && !brief.sources.some((y) => y.id === x.id)) brief.sources.push(x); }
+  if (!brief.question && brief.decision) brief.question = brief.decision;
+  if (!brief.question && !brief.questions.length) {
+    return refuse(404, def && def.exists ? `the definition of ${id} names no purpose, so the report has no question. Give one: --ask "<the question>"` : `there is no report named ${id}. For an ad hoc report give its question: --ask "<the question>"`);
+  }
+  if (!brief.questions.length || brief.questions[0] !== brief.question) brief.questions = [brief.question, ...brief.questions.filter((q) => q !== brief.question)].filter(Boolean);
+  brief.readers = brief.readers || 'You';
+  brief.title = brief.title || clip(brief.question.replace(/\?$/, ''), 80);
+  // no source named: the PMOS ledgers are the one PMOS always reaches
+  if (!brief.sources.length) brief.sources.push({ id: 'pmos', kind: 'pmos', name: 'PMOS ledgers' });
+
+  // the last issue: the window opens there, its outline is the agreed one, its asks are carried
+  const issued = issuedSlots(abs, id).filter((s) => s < today);
+  const last = issued.length ? issued[issued.length - 1] : null;
+  brief.last_issue = last;
+  brief.window = { from: last ? addDays(last, 1) : addDays(today, -((brief.cycle_days || 7) - 1)), to: today };
+  if (last) {
+    const LP = paths(abs, id, last);
+    const prior = readJson(LP.report.abs);
+    if (prior && Array.isArray(prior.sections)) brief.agreed_outline = prior.sections.map((s) => str(s.title)).filter(Boolean);
+    // an issue the engine did not write shows the shape the readers saw, as an example only: it was the old fixed frame, not an agreed outline
+    else { try { brief.earlier_outline = headingsOf(fs.readFileSync(LP.md.abs, 'utf8')); } catch { brief.earlier_outline = []; } }
+    const closed = closedAsks(abs, id);
+    const asks = prior && isObj(prior.ask) && prior.ask.text ? [prior.ask] : [];
+    const carried = prior && Array.isArray(prior.carried) ? prior.carried : [];
+    for (const a of carried.concat(asks)) {
+      const t = str(a.text).trim();
+      if (t && !closed.has(t.toLowerCase()) && !brief.carried_asks.some((x) => x.text === t)) brief.carried_asks.push({ text: t, who: str(a.who) || null, by: isDate(a.by) ? a.by : null, since: last });
+    }
+    from.push(LP.md.rel);
+  }
+  brief.rules = rulesOf(abs, id);
+  for (const r of brief.rules) if (r.kind === 'voice' || r.kind === 'wording') brief.voice.push(r.text);
+  return { ok: true, brief };
+}
+
+// ── step 2 · the readings ───────────────────────────────────────────────────────────────────────────────────────────
+/** One reading, checked. Every reading has id, value, at and source; a reading from outside PMOS also says how it was read. */
+function checkReading(r, sourceIds) {
+  if (!isObj(r)) return 'a reading is an object';
+  if (!READING_ID_RE.test(str(r.id))) return `reading id ${JSON.stringify(r.id)} is lower case letters, digits, dot, dash or underscore`;
+  if (!(typeof r.value === 'number' && Number.isFinite(r.value)) && !(isStr(r.value) && r.value.trim() && r.value.length <= 80)) return `reading ${r.id}: value is a number or a short text`;
+  if (!isStr(r.at) || !/^\d{4}-\d{2}-\d{2}/.test(r.at)) return `reading ${r.id}: at is the date it was read or measured, YYYY-MM-DD`;
+  if (!SOURCE_ID_RE.test(str(r.source))) return `reading ${r.id}: source names one of the brief's sources`;
+  if (sourceIds && !sourceIds.has(r.source)) return `reading ${r.id}: source ${r.source} is not a source of this brief (${[...sourceIds].join(', ')}); add it with --source`;
+  if (r.source !== 'pmos' && !str(r.how).trim()) return `reading ${r.id}: how says how it was read (the query, the filter, the field)`;
+  for (const k of ['n', 'of', 'target']) if (r[k] != null && !(typeof r[k] === 'number' && Number.isFinite(r[k]))) return `reading ${r.id}: ${k} is a number`;
+  return null;
+}
+function cleanReading(r) {
+  const o = { id: r.id, value: r.value, unit: str(r.unit).slice(0, 12) || null, at: r.at.slice(0, 10), source: r.source, how: str(r.how).slice(0, 300) || null, label: str(r.label).slice(0, 160) || null };
+  for (const k of ['n', 'of', 'target']) if (typeof r[k] === 'number') o[k] = r[k];
+  if (r.better === 'lower' || r.better === 'higher') o.better = r.better;
+  if (r.flag) o.flag = clip(r.flag, 200);
+  if (r.filed) o.filed = true;
+  return o;
+}
+/** The PMOS ledgers as readings: what lib/report-draft.js folds (its readers stay; its frame does not). */
+function ledgerReadings(root, brief, now) {
+  const RDm = RD();
+  const d = RDm.draftOf(root, { cadence: brief.id, slot: brief.slot, now });
+  if (!d || d.ok === false) return { readings: [], gaps: [{ source: 'pmos', reason: clip((d && d.error) || 'the ledgers could not be read', 200), affects: [] }] };
+  const at = brief.slot; const out = [];
+  for (const b of d.blocks || []) {
+    const base = `${b.id}`.toLowerCase().replace(/[^a-z0-9._-]/g, '-');
+    if (b.progress && b.progress.total) out.push({ id: `${base}.done`, value: b.progress.done, of: b.progress.total, unit: 'items', at, source: 'pmos', how: 'plan items done of total', label: `${b.title}: items done` });
+    if (b.health && b.health.level) out.push({ id: `${base}.health`, value: { off: 'off track', 'at-risk': 'at risk', unknown: 'unknown', on: 'on track' }[b.health.level] || b.health.level, at, source: 'pmos', how: 'lib/health.js', label: `${b.title}: health`, ...(b.health.level === 'off' || b.health.level === 'at-risk' ? { flag: (b.health.reasons || []).map((x) => x.text).join('; ') || b.health.level } : {}) });
+    if (b.measure && typeof b.measure.value === 'number') out.push({ id: `${base}.${String(b.measure.anchor || 'kr').toLowerCase()}`, value: b.measure.value, unit: b.measure.unit || null, ...(typeof b.measure.target === 'number' ? { target: b.measure.target } : {}), at: b.measure.as_of || at, source: 'pmos', how: `measurement ${b.measure.source}`, label: `${b.title}: ${b.measure.anchor}` });
+    const carried = (b.last_cycle && b.last_cycle.carried) || [];
+    const overdue = carried.filter((c) => c.due && c.due < brief.slot);
+    if (overdue.length) out.push({ id: `${base}.overdue`, value: overdue.length, unit: 'items', at, source: 'pmos', how: 'carried plan items past their due date', label: `${b.title}: items overdue`, flag: overdue.map((c) => `${c.title}, due ${full(c.due)}`).join('; ') });
+    const coming = ((b.coming_cycle && b.coming_cycle.items) || []).filter((c) => c.due && c.due >= brief.slot && c.due <= addDays(brief.slot, 14));
+    if (coming.length) out.push({ id: `${base}.due-soon`, value: coming.length, unit: 'items', at, source: 'pmos', how: 'plan items due within 14 days', label: `${b.title}: items due within 14 days`, flag: coming.map((c) => `${c.title}, due ${full(c.due)}`).join('; ') });
+  }
+  return { readings: out, gaps: [] };
+}
+/** A readings pack: a JSON or JSONL file under the state dir whose lines are readings (what a connector run filed). */
+function packReadings(root, src, sourceIds) {
+  const abs = path.resolve(String(root));
+  const file = path.resolve(abs, str(src.ref));
+  if (!file.startsWith(abs + path.sep)) return { readings: [], gaps: [{ source: src.id, reason: 'the pack is outside the repository', affects: [] }] };
+  let text; try { text = fs.readFileSync(file, 'utf8'); } catch { return { readings: [], gaps: [{ source: src.id, reason: `${src.ref} could not be read`, affects: [] }] }; }
+  let rows = [];
+  try { const o = JSON.parse(text); rows = Array.isArray(o) ? o : isObj(o) && Array.isArray(o.readings) ? o.readings : [o]; } catch { rows = text.split('\n').filter((l) => l.trim()).map((l) => { try { return JSON.parse(l); } catch { return null; } }); }
+  const readings = []; let skipped = 0;
+  for (const r of rows) { const x = isObj(r) ? { source: src.id, how: `pack ${src.ref}`, ...r } : null; if (x && !checkReading(x, sourceIds)) readings.push(cleanReading(x)); else skipped++; }
+  return { readings, gaps: skipped ? [{ source: src.id, reason: `${skipped} line(s) of ${src.ref} are not readings (id, value, at)`, affects: [] }] : [] };
+}
+
+function readingsOf(root, brief, { add = [], gaps = [], keep = null, now = Date.now() } = {}) {
+  if (!isObj(brief)) return refuse(400, 'no brief');
+  const ids = new Set(brief.sources.map((s) => s.id));
+  const byId = new Map(); const gapList = [];
+  const put = (r) => byId.set(r.id, r);
+  // what the writer filed earlier for this slot stays, unless filed again
+  for (const r of (keep && Array.isArray(keep.readings) ? keep.readings : [])) if (r.filed && !checkReading(r, ids)) put(cleanReading(r));
+  for (const s of brief.sources) {
+    if (s.kind === 'pmos') { const x = ledgerReadings(root, brief, now); x.readings.forEach((r) => put(cleanReading(r))); gapList.push(...x.gaps); }
+    else if (s.kind === 'pack') { const x = packReadings(root, s, ids); x.readings.forEach(put); gapList.push(...x.gaps); }
+  }
+  for (const r of (Array.isArray(add) ? add : [])) {
+    const why = checkReading(r, ids);
+    if (why) return refuse(422, why);
+    put(cleanReading({ ...r, filed: true }));
+  }
+  if (byId.size > LIMITS.readings) return refuse(422, `a report holds at most ${LIMITS.readings} readings`);
+  const filedGaps = (keep && Array.isArray(keep.gaps) ? keep.gaps.filter((g) => g.filed) : []).concat((Array.isArray(gaps) ? gaps : []).map((g) => ({ ...g, filed: true })));
+  for (const g of filedGaps) {
+    if (!isObj(g) || !ids.has(str(g.source)) || !str(g.reason).trim()) return refuse(422, 'a gap is { source, reason, affects } and names a source of the brief');
+    gapList.push({ source: g.source, reason: clip(g.reason, 200), affects: Array.isArray(g.affects) ? g.affects.map(str).slice(0, 20) : [], filed: true });
+  }
+  const readings = [...byId.values()];
+  for (let i = gapList.length - 1; i >= 0; i--) if (gapList.findIndex((g) => g.source === gapList[i].source && g.reason === gapList[i].reason) < i) gapList.splice(i, 1);
+  // a source the brief names that nothing read is a gap, never silence
+  for (const s of brief.sources) {
+    if (!readings.some((r) => r.source === s.id) && !gapList.some((g) => g.source === s.id)) {
+      gapList.push({ source: s.id, reason: s.kind === 'connector' || s.kind === 'document' ? `not read in this run: the writer reads ${s.name} and files its readings with pmos report read --from <file>` : `${s.name} gave no reading`, affects: [] });
+    }
+  }
+  return { ok: true, at: new Date(now).toISOString(), readings, gaps: gapList };
+}
+
+// ── step 3 · the findings ───────────────────────────────────────────────────────────────────────────────────────────
+const fmtNum = (v) => (typeof v === 'number' ? (Number.isInteger(v) ? v.toLocaleString('en-GB') : (Math.round(v * 10) / 10).toLocaleString('en-GB')) : str(v));
+/** A unit the figure carries in a sentence: a symbol or a measure. A count's noun (attempts, items, sessions) is the writer's word, never repeated. */
+const SHOWN_UNIT = /^(?:%|pp|x|[a-zA-Z$€£]{1,3}|seconds?|minutes?|hours?|days?|weeks?|months?|years?)$/;
+function valueText(r, mode) {
+  if (!r) return '';
+  const u = r.unit && SHOWN_UNIT.test(r.unit) ? (r.unit === '%' ? '%' : ' ' + r.unit) : '';
+  if (mode === 'n') return typeof r.n === 'number' ? fmtNum(r.n) : fmtNum(r.value);
+  if (mode === 'label') return r.label || r.id;
+  if (mode === 'of') return typeof r.of === 'number' ? `${fmtNum(r.n != null ? r.n : r.value)} of ${fmtNum(r.of)}` : fmtNum(r.value) + u;
+  if (mode === 'value') return fmtNum(r.value);
+  return fmtNum(r.value) + (typeof r.value === 'number' ? u : '');
+}
+function findingsOf(brief, readings, { prior = null, add = [] } = {}) {
+  const R = Array.isArray(readings && readings.readings) ? readings.readings : [];
+  const byId = new Map(R.map((r) => [r.id, r]));
+  const out = [];
+  const push = (f) => { if (out.length < LIMITS.findings) out.push({ id: `f${out.length + 1}`, ...f }); };
+  const lab = (r) => r.label || r.id;
+  // vs the last issue: the same reading moved
+  const before = new Map((prior && Array.isArray(prior.readings) ? prior.readings : []).map((r) => [r.id, r]));
+  for (const r of R) {
+    const p = before.get(r.id);
+    if (p && typeof r.value === 'number' && typeof p.value === 'number' && r.value !== p.value) push({ kind: 'vs-last-issue', text: `${lab(r)} moved from ${valueText(p)} to ${valueText(r)} since ${full(p.at)}`, readings: [r.id], weight: 0.7 });
+    else if (p && isStr(r.value) && r.value !== p.value) push({ kind: 'vs-last-issue', text: `${lab(r)} is ${r.value}, it was ${p.value} on ${full(p.at)}`, readings: [r.id], weight: 0.7 });
+  }
+  // vs the target
+  for (const r of R) {
+    if (typeof r.value !== 'number' || typeof r.target !== 'number') continue;
+    const behind = r.better === 'lower' ? r.value > r.target : r.value < r.target;
+    if (behind) push({ kind: 'vs-target', text: `${lab(r)} is ${valueText(r)}, against a target of ${valueText({ ...r, value: r.target })}`, readings: [r.id], weight: 0.8 });
+  }
+  // vs plan, due and anomalies: a reading its reader flagged
+  for (const r of R) {
+    if (!r.flag) continue;
+    const kind = /\.health$/.test(r.id) ? 'vs-plan' : /\.(overdue|due-soon)$/.test(r.id) ? 'due' : 'anomaly';
+    push({ kind, text: `${lab(r)}: ${valueText(r)}. ${r.flag}`, readings: [r.id], weight: kind === 'vs-plan' ? 0.85 : kind === 'anomaly' ? 0.8 : 0.6 });
+  }
+  // the asks carried from the last issue
+  for (const a of (brief && brief.carried_asks) || []) push({ kind: 'carried', text: `Carried from ${full(a.since)}: ${a.text}${a.who ? ` (${a.who}${a.by ? `, by ${full(a.by)}` : ''})` : ''}`, readings: [], weight: 0.75 });
+  // what the writer found that answers the readers' question (it cites the readings it rests on)
+  for (const f of (Array.isArray(add) ? add : [])) {
+    if (!isObj(f) || !str(f.text).trim()) return refuse(422, 'a finding is { text, readings: [<reading id>…], kind?, question? }');
+    const refs = Array.isArray(f.readings) ? f.readings.map(str) : [];
+    if (!refs.length) return refuse(422, `the finding "${clip(f.text, 60)}" cites no reading`);
+    const miss = refs.filter((x) => !byId.has(x));
+    if (miss.length) return refuse(422, `the finding "${clip(f.text, 60)}" cites ${miss.join(', ')}, which is not a reading`);
+    push({ kind: ['vs-target', 'vs-plan', 'vs-last-issue', 'answers-question', 'anomaly', 'due'].includes(f.kind) ? f.kind : 'answers-question', text: clip(f.text, 400), readings: refs,
+      weight: typeof f.weight === 'number' && f.weight >= 0 && f.weight <= 1 ? f.weight : 0.9, ...(f.question ? { question: clip(f.question, 300) } : {}), filed: true });
+  }
+  out.sort((a, b) => b.weight - a.weight);
+  out.forEach((f, i) => { f.id = `f${i + 1}`; });
+  return { findings: out, none: out.length === 0 };
+}
+
+// ── tokens ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+function resolve(text, readings) {
+  const byId = readings instanceof Map ? readings : new Map((Array.isArray(readings) ? readings : (readings && readings.readings) || []).map((r) => [r.id, r]));
+  const missing = []; const used = [];
+  const out = str(text).replace(TOKEN_RE, (all, id, mode) => { const r = byId.get(id); if (!r) { missing.push(id); return all; } used.push(id); return valueText(r, mode); });
+  const res = new String(out); // eslint-disable-line no-new-wrappers
+  return Object.assign(res, { missing, used });
+}
+const tokensIn = (text) => [...str(text).matchAll(TOKEN_RE)].map((m) => m[1]);
+/** A figure in the writer's own words: a digit left once tokens, full dates, ISO dates, ticket keys, ids such as KR-A1, H2, Q4, D64, v5 and S1 are out. */
+function bareFigures(text) {
+  const t = str(text).replace(TOKEN_RE, ' ')
+    .replace(new RegExp(`\\b\\d{1,2} (?:${MONTHS.join('|')}) \\d{4}\\b`, 'g'), ' ')
+    .replace(new RegExp(`\\b(?:${MONTHS.join('|')}) \\d{4}\\b`, 'g'), ' ')
+    .replace(/\b\d{4}-\d{2}-\d{2}\b/g, ' ')
+    .replace(/\b[A-Z][A-Z0-9]*-[A-Z]?\d+\b/g, ' ')
+    .replace(/\b[A-Za-z]+\d+[A-Za-z0-9]*\b/g, ' ')
+    .replace(/https?:\/\/\S+/g, ' ');
+  return t.match(/\d[\d,.]*/g) || [];
+}
+
+// ── the report model (step 4): its shape ────────────────────────────────────────────────────────────────────────────
+/** Every text the writer wrote in a report, with where it sits. */
+function textsOf(report) {
+  const out = [];
+  const add = (where, t) => { if (isStr(t) && t) out.push({ where, text: t }); };
+  add('title', report.title);
+  if (isObj(report.answer)) { add('answer', report.answer.text); (report.answer.supports || []).forEach((s, i) => add(`answer.supports[${i}]`, s)); }
+  (report.sections || []).forEach((s, i) => {
+    add(`sections[${i}].title`, s.title);
+    (s.blocks || []).forEach((b, j) => {
+      const w = `sections[${i}].blocks[${j}]`;
+      add(w, b.text); (b.items || []).forEach((x) => add(w, x));
+      (b.columns || []).forEach((x) => add(w, x));
+      (b.rows || []).forEach((row) => (Array.isArray(row) ? row : []).forEach((c) => add(w, str(c))));
+      (b.options || []).forEach((o) => { add(w, o && o.name); add(w, o && o.text); });
+    });
+  });
+  if (isObj(report.ask)) { add('ask', report.ask.text); (report.ask.options || []).forEach((o) => add('ask.options', str(o))); }
+  if (isObj(report.beyond)) for (const k of BEYOND_KEYS) { const v = report.beyond[k]; (Array.isArray(v) ? v : [v]).forEach((x) => add(`beyond.${k}`, x)); }
+  return out;
+}
+function shapeError(report) {
+  if (!isObj(report)) return 'the report is a JSON object';
+  if (!isStr(report.title) || !report.title.trim() || report.title.length > LIMITS.title || /[\r\n]/.test(report.title)) return `title is one sentence of at most ${LIMITS.title} characters`;
+  if (!isObj(report.answer) || !isStr(report.answer.text) || !report.answer.text.trim()) return 'answer.text is the governing thought, the answer the readers need';
+  if (report.answer.supports != null && (!Array.isArray(report.answer.supports) || report.answer.supports.length > 5 || report.answer.supports.some((s) => !isStr(s)))) return 'answer.supports is a list of at most 5 sentences';
+  if (!Array.isArray(report.sections) || report.sections.length > LIMITS.sections) return `sections is a list of at most ${LIMITS.sections} (any titles, any order: the writer chooses)`;
+  const seen = new Set();
+  for (const [i, s] of report.sections.entries()) {
+    if (!isObj(s) || !isStr(s.title) || !s.title.trim() || /[\r\n]/.test(s.title)) return `sections[${i}] has a one-line title`;
+    const id = str(s.id) || slugOf(s.title);
+    if (seen.has(id)) return `two sections share the id ${id}`;
+    seen.add(id);
+    if (!Array.isArray(s.blocks) || s.blocks.length > LIMITS.blocks) return `sections[${i}].blocks is a list of at most ${LIMITS.blocks}`;
+    for (const [j, b] of s.blocks.entries()) {
+      if (!isObj(b) || !BLOCK_KINDS.includes(b.kind)) return `sections[${i}].blocks[${j}].kind is one of ${BLOCK_KINDS.join(', ')}`;
+      if ((b.kind === 'p' || b.kind === 'quote') && (!isStr(b.text) || b.text.length > LIMITS.text)) return `sections[${i}].blocks[${j}] is { kind: '${b.kind}', text }`;
+      if (b.kind === 'list' && (!Array.isArray(b.items) || !b.items.every(isStr))) return `sections[${i}].blocks[${j}] is { kind: 'list', items: [text…] }`;
+      if (b.kind === 'table' && (!Array.isArray(b.columns) || !b.columns.length || b.columns.length > LIMITS.cols || !Array.isArray(b.rows) || b.rows.length > LIMITS.rows || b.rows.some((r) => !Array.isArray(r) || r.length !== b.columns.length))) return `sections[${i}].blocks[${j}] is { kind: 'table', columns: [...], rows: [[one cell per column]…] } (at most ${LIMITS.rows} rows)`;
+      if (b.kind === 'bars' && (!Array.isArray(b.rows) || !b.rows.length || b.rows.length > 20 || b.rows.some((r) => !Array.isArray(r) || r.length !== 2 || !isStr(r[0]) || tokensIn(r[1]).length !== 1))) return `sections[${i}].blocks[${j}] is { kind: 'bars', rows: [[label, "{{r:<id>}}"]…] }: each bar is one reading`;
+      if (b.kind === 'options' && (!Array.isArray(b.options) || b.options.length < 2 || b.options.length > 4 || b.options.some((o) => !isObj(o) || !isStr(o.name)))) return `sections[${i}].blocks[${j}] is { kind: 'options', options: [{ name, text }…] } with 2 to 4 options`;
+    }
+  }
+  if (report.ask != null) {
+    if (!isObj(report.ask) || !isStr(report.ask.text) || !report.ask.text.trim()) return 'ask is null or { text, who, by, options }';
+    if (report.ask.by != null && !isDate(report.ask.by)) return 'ask.by is a date, YYYY-MM-DD';
+    if (report.ask.options != null && (!Array.isArray(report.ask.options) || report.ask.options.length > 3 || !report.ask.options.every(isStr))) return 'ask.options is a list of at most 3';
+  }
+  if (report.beyond != null) {
+    if (!isObj(report.beyond)) return 'beyond is an object of the parts beyond the ask';
+    for (const k of Object.keys(report.beyond)) if (!BEYOND_KEYS.includes(k)) return `beyond.${k} is not a part; the parts are ${BEYOND_KEYS.join(', ')}`;
+  }
+  if (report.questions != null && (!Array.isArray(report.questions) || report.questions.some((q) => !isObj(q) || !isStr(q.question)))) return 'questions is a list of { question, answered_in, gap }';
+  return null;
+}
+
+// ── step 6 · the checks: substance first ────────────────────────────────────────────────────────────────────────────
+function checkReport(report, { brief = null, readings = null, markdown = null } = {}) {
+  const bad = shapeError(report);
+  if (bad) return [{ id: 'shape', pass: false, hard: true, reason: bad }];
+  const R = Array.isArray(readings && readings.readings) ? readings.readings : [];
+  const byId = new Map(R.map((r) => [r.id, r]));
+  const gaps = Array.isArray(readings && readings.gaps) ? readings.gaps : [];
+  const out = [];
+  // 1 · there is an answer: a sentence with a reading in it
+  const answerRefs = tokensIn(report.title).concat(tokensIn(report.answer.text)).filter((id) => byId.has(id));
+  out.push(answerRefs.length
+    ? { id: 'answer', pass: true, hard: true, reason: `the title and the answer carry ${answerRefs.length} reading(s)` }
+    : { id: 'answer', pass: false, hard: true, reason: 'neither the title nor the answer carries a reading, so there is no answer to show. Put the number that answers the question in the title: {{r:<id>}}' });
+  // 2 · each question of the brief is answered or named as a gap
+  const qs = brief && Array.isArray(brief.questions) ? brief.questions : [];
+  const mapped = new Map((report.questions || []).map((q) => [str(q.question).trim().toLowerCase(), q]));
+  const sectionIds = new Set((report.sections || []).map((s) => str(s.id) || slugOf(s.title)));
+  const open = qs.slice(1).filter((q) => { const m = mapped.get(q.trim().toLowerCase()); return !m || !((m.answered_in === 'answer' || sectionIds.has(str(m.answered_in))) || str(m.gap).trim()); });
+  out.push(open.length ? { id: 'questions', pass: false, hard: false, reason: `${open.length} question(s) of the brief are neither answered nor named as a gap: ${open.slice(0, 2).map((q) => `"${clip(q, 60)}"`).join(', ')}` }
+    : { id: 'questions', pass: true, hard: false, reason: qs.length > 1 ? `the ${qs.length} questions of the brief are answered or named as gaps` : 'the answer answers the brief\'s question' });
+  // 3 · every figure has a reading; every reading has a source and a date
+  const texts = textsOf(report);
+  const missing = new Set(); const bare = [];
+  for (const t of texts) { for (const id of tokensIn(t.text)) if (!byId.has(id)) missing.add(id); const f = bareFigures(t.text); if (f.length) bare.push({ where: t.where, figs: f }); }
+  const undated = R.filter((r) => !r.source || !r.at);
+  out.push(missing.size || bare.length || undated.length
+    ? { id: 'readings', pass: false, hard: true, reason: [missing.size ? `${missing.size} token(s) name no reading: ${[...missing].slice(0, 4).join(', ')}` : '', bare.length ? `${bare.length} place(s) carry a figure that is not a reading (${bare.slice(0, 3).map((b) => `${b.where}: ${b.figs.slice(0, 2).join(', ')}`).join('; ')}); file it as a reading and write {{r:<id>}}` : '', undated.length ? `${undated.length} reading(s) have no source or date` : ''].filter(Boolean).join('. ') }
+    : { id: 'readings', pass: true, hard: true, reason: 'every figure is a reading with its source and date' });
+  // 4 · since the last issue (from issue 2)
+  const since = isObj(report.beyond) ? report.beyond.since : null;
+  out.push(!brief || !brief.last_issue ? { id: 'since', pass: true, hard: false, reason: 'the first issue: nothing to compare with yet' }
+    : str(Array.isArray(since) ? since.join(' ') : since).trim() ? { id: 'since', pass: true, hard: false, reason: `says what moved since ${full(brief.last_issue)}` }
+      : { id: 'since', pass: false, hard: false, reason: `the readers got an issue on ${full(brief.last_issue)}; say what moved since (beyond.since)` });
+  // 5 · the ask has who and by, or the options
+  const a = report.ask;
+  out.push(!a ? { id: 'ask', pass: true, hard: false, reason: 'no ask this time' }
+    : (a.who && a.by) || (Array.isArray(a.options) && a.options.length >= 2) ? { id: 'ask', pass: true, hard: false, reason: a.who && a.by ? `${a.who}, by ${full(a.by)}` : `${a.options.length} options laid out` }
+      : { id: 'ask', pass: false, hard: false, reason: 'the ask names neither who and by when, nor the options' });
+  // 6 · each addition beyond the ask has a reading (what we don't know rests on the gaps)
+  const weak = [];
+  if (isObj(report.beyond)) for (const k of BEYOND_KEYS) {
+    const v = report.beyond[k]; const t = (Array.isArray(v) ? v : [v]).filter((x) => isStr(x) && x.trim());
+    if (!t.length) continue;
+    if (k === 'unknown') { if (!gaps.length && !t.some((x) => tokensIn(x).length)) weak.push(k); continue; }
+    if (!t.every((x) => tokensIn(x).some((id) => byId.has(id)))) weak.push(k);
+  }
+  out.push(weak.length ? { id: 'beyond', pass: false, hard: false, reason: `${weak.map((k) => BEYOND.find((b) => b[0] === k)[1]).join(', ')} cite${weak.length === 1 ? 's' : ''} no reading; leave a part out when no reading backs it` }
+    : { id: 'beyond', pass: true, hard: false, reason: 'each addition beyond the ask cites a reading' });
+  // then the form checks of a report document
+  if (markdown != null) { try { for (const c of require('./report-checks.js').reportChecks(markdown, { listed: [] })) out.push({ ...c, hard: false, form: true }); } catch { /* the form checks are advisory */ } }
+  return out;
+}
+
+// ── step 5 · render: one model → the document and the deck ──────────────────────────────────────────────────────────
+function sourceLine(ids, byId, brief) {
+  const names = new Map(((brief && brief.sources) || []).map((s) => [s.id, s.name]));
+  const seen = new Map();
+  for (const id of ids) { const r = byId.get(id); if (!r) continue; const k = r.source; if (!seen.has(k)) seen.set(k, new Set()); seen.get(k).add(r.at); }
+  if (!seen.size) return '';
+  return 'Source: ' + [...seen].map(([s, ats]) => `${names.get(s) || s}, ${[...ats].sort().map(full).join(' and ')}`).join('; ') + '.';
+}
+const mdCell = (s) => str(s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+function blockMd(b, rs, byId, brief) {
+  const r = (t) => String(resolve(t, byId));
+  const used = []; const take = (t) => { used.push(...tokensIn(t)); return r(t); };
+  let body = '';
+  if (b.kind === 'p') body = take(b.text);
+  else if (b.kind === 'quote') body = '> ' + take(b.text);
+  else if (b.kind === 'list') body = b.items.map((x) => `- ${take(x)}`).join('\n');
+  else if (b.kind === 'table') body = `| ${b.columns.map((c) => mdCell(take(c))).join(' | ')} |\n|${b.columns.map(() => '---').join('|')}|\n` + b.rows.map((row) => `| ${row.map((c) => mdCell(take(str(c)))).join(' | ')} |`).join('\n');
+  else if (b.kind === 'bars') body = `| ${mdCell(b.title || 'Item')} | Value |\n|---|---:|\n` + b.rows.map(([l, v]) => `| ${mdCell(take(l))} | ${take(v)} |`).join('\n');
+  else if (b.kind === 'options') body = b.options.map((o, i) => `- **Option ${'ABCD'[i]}: ${take(o.name)}.** ${take(str(o.text))}`).join('\n');
+  const src = sourceLine(used, byId, brief);
+  return body + (src ? `\n\n*${src}*` : '');
+}
+function beyondParts(report) {
+  const out = [];
+  if (!isObj(report.beyond)) return out;
+  for (const [k, label] of BEYOND) {
+    const v = report.beyond[k]; const t = (Array.isArray(v) ? v : [v]).filter((x) => isStr(x) && x.trim());
+    if (t.length) out.push({ key: k, label, texts: t });
+  }
+  return out;
+}
+function renderMarkdown(report, { brief = null, readings = null, now = Date.now() } = {}) {
+  const R = Array.isArray(readings && readings.readings) ? readings.readings : [];
+  const byId = new Map(R.map((r) => [r.id, r]));
+  const r = (t) => String(resolve(t, byId));
+  const title = r(report.title);
+  const q = (s) => JSON.stringify(str(s));
+  const lines = ['---', 'type: Reference', `title: ${q(title)}`, `description: ${q(clip(r(report.answer.text), 200))}`, `timestamp: ${new Date(now).toISOString()}`];
+  if (brief) {
+    lines.push(`report: ${brief.id}`, `slot: ${brief.slot}`, `window: ${q(`${brief.window.from} to ${brief.window.to}`)}`, `audience: ${q(brief.readers)}`);
+    if (brief.recurring) lines.push(`cadence: ${brief.id}`);
+  }
+  lines.push('status: draft', 'engine: e1', '---', '', `# ${title}`, '');
+  if (brief) lines.push(`For ${brief.readers}. ${periodOf(brief, R)}.`, '');
+  const ansIds = tokensIn(report.answer.text).concat(...(report.answer.supports || []).map(tokensIn), tokensIn(report.title));
+  lines.push(`**In one minute.** ${r(report.answer.text)}`, '');
+  for (const s of report.answer.supports || []) lines.push(`- ${r(s)}`);
+  if ((report.answer.supports || []).length) lines.push('');
+  const src = sourceLine(ansIds, byId, brief);
+  if (src) lines.push(`*${src}*`, '');
+  if (report.ask) {
+    lines.push(`**${report.ask.title ? r(report.ask.title) : 'Needs your call'}:** ${stop(r(report.ask.text))}${report.ask.who ? ` Who: ${r(report.ask.who)}.` : ''}${report.ask.by ? ` By ${full(report.ask.by)}.` : ''}`, '');
+    (report.ask.options || []).forEach((o, i) => lines.push(`- Option ${'ABC'[i]}: ${r(o)}`));
+    if ((report.ask.options || []).length) lines.push('');
+  }
+  for (const s of report.sections) {
+    lines.push(`## ${r(s.title)}`, '');
+    for (const b of s.blocks) lines.push(blockMd(b, null, byId, brief), '');
+  }
+  for (const p of beyondParts(report)) {
+    lines.push(`## ${p.label}`, '');
+    if (p.texts.length === 1) lines.push(r(p.texts[0])); else for (const t of p.texts) lines.push(`- ${r(t)}`);
+    const s2 = sourceLine(p.texts.flatMap(tokensIn), byId, brief);
+    lines.push(...(s2 ? ['', `*${s2}*`] : []), '');
+  }
+  const gaps = Array.isArray(readings && readings.gaps) ? readings.gaps : [];
+  const used = new Set(textsOf(report).flatMap((t) => tokensIn(t.text)));
+  const names = new Map(((brief && brief.sources) || []).map((x) => [x.id, x.name]));
+  const reached = new Map();
+  for (const x of R) if (used.has(x.id)) { if (!reached.has(x.source)) reached.set(x.source, { n: 0, ats: new Set(), how: new Set() }); const e = reached.get(x.source); e.n++; e.ats.add(x.at); if (x.how) e.how.add(x.how); }
+  lines.push('## Sources', '');
+  if (!reached.size) lines.push('- None of the readings were used.');
+  for (const [s, e] of reached) lines.push(`- **${names.get(s) || s}** (source: ${s}): ${e.n} reading(s), read ${[...e.ats].sort().map(full).join(', ')}.${e.how.size ? ` How: ${[...e.how].slice(0, 3).join('; ')}.` : ''}`);
+  if (gaps.length) {
+    lines.push('', '**Not reached**', '');
+    for (const g of gaps) lines.push(`- **${names.get(g.source) || g.source}** (source: ${g.source}): ${g.reason}.`);
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+
+const stop = (t) => (/[.?!]$/.test(t) ? t : t + '.');
+/** The period a report covers: a recurring report's window; an ad hoc report's, the dates of its readings. */
+function periodOf(brief, R) {
+  const span = (a, b) => (a === b ? full(a) : `${full(a)} to ${full(b)}`);
+  if (brief.recurring || !R.length) return span(brief.window.from, brief.window.to);
+  const ats = R.map((x) => x.at).sort();
+  return 'Data of ' + span(ats[0], ats[ats.length - 1]);
+}
+/** The deck of an engine report: the same model, drawn as slides (lib/report-pyramid.js deckHtml and lib/report-export.js pptx draw it). */
+function deckOf(report, { brief = null, readings = null, look = null } = {}) {
+  const R = Array.isArray(readings && readings.readings) ? readings.readings : [];
+  const byId = new Map(R.map((r) => [r.id, r]));
+  const r = (t) => String(resolve(t, byId));
+  const srcOf = (ids) => sourceLine(ids, byId, brief).replace(/\.$/, '');
+  const slides = [];
+  const titleText = clip(r(report.title), 160);
+  slides.push({ kind: 'title', tag: [brief && brief.title, brief && brief.readers ? `for ${brief.readers}` : ''].filter(Boolean).join(' · ') || 'Report', title: titleText, size: titleText.length > 60 ? 48 : 64,
+    sub: brief ? periodOf(brief, R) : '', source: srcOf(tokensIn(report.title)) });
+  const supports = (report.answer.supports || []).map((s) => { const t = r(s); const m = /^([^:]{3,80}):\s+(.+)$/.exec(t); return m ? { head: m[1], text: m[2] } : { head: t, text: '' }; });
+  const ask = report.ask ? { question: r(report.ask.text), who: report.ask.who ? r(report.ask.who) : (brief && brief.readers) || '', by: report.ask.by ? full(report.ask.by) : null, options: (report.ask.options || []).map(r), more: '' } : null;
+  slides.push({ kind: 'answer', tag: 'The answer', title: clip(r(report.answer.text), 200), lead: '', supports, ask,
+    source: srcOf(tokensIn(report.answer.text).concat(...(report.answer.supports || []).map(tokensIn))) });
+  for (const s of report.sections) {
+    // a section goes on as many slides as its blocks need: a long table is cut at 8 rows, and a block that would run under the footer starts a new slide
+    const chunks = [[]]; let used = 0;
+    const put = (b) => { const h = blockHeight(b); if (chunks[chunks.length - 1].length && used + h > SLIDE_ROOM) { chunks.push([]); used = 0; } chunks[chunks.length - 1].push(b); used += h; };
+    for (const b of s.blocks) {
+      if (b.kind === 'table' && b.rows.length > 8) for (let i = 0; i < b.rows.length; i += 8) put({ ...b, rows: b.rows.slice(i, i + 8) });
+      else put(b);
+    }
+    const real = chunks.filter((c) => c.length);
+    real.forEach((blocks, i) => {
+      const ids = blocks.flatMap((b) => textsOf({ title: '', answer: { text: '' }, sections: [{ title: '', blocks: [b] }] }).flatMap((t) => tokensIn(t.text)));
+      slides.push({ kind: 'section', title: clip(r(s.title), 160) + (i ? ' (continued)' : ''), blocks: blocks.map((b) => drawBlock(b, r, byId)), source: srcOf(ids) });
+    });
+  }
+  const parts = beyondParts(report);
+  for (let i = 0; i < parts.length; i += 4) {
+    const chunk = parts.slice(i, i + 4);
+    // the title is a finding, as on every slide: the first part's own sentence
+    slides.push({ kind: 'beyond', tag: 'Beyond the question', title: clip(r(chunk[0].texts[0]), 160), items: chunk.map((p) => ({ head: p.label, text: clip(p.texts.map(r).join(' '), 260) })),
+      source: srcOf(chunk.flatMap((p) => p.texts.flatMap(tokensIn))) });
+  }
+  if (ask && (ask.options.length || ask.who)) slides.push({ kind: 'ask', tag: 'Needs your call', title: clip(ask.by ? `Decide by ${ask.by}: ${ask.question.replace(/\?$/, '')}` : ask.question, 200), ask, source: 'Source: the readings above' });
+  const names = new Map(((brief && brief.sources) || []).map((x) => [x.id, x.name]));
+  const used = new Set(textsOf(report).flatMap((t) => tokensIn(t.text)));
+  const reached = [...new Set(R.filter((x) => used.has(x.id)).map((x) => x.source))].map((s) => `${names.get(s) || s}, read ${[...new Set(R.filter((x) => x.source === s && used.has(x.id)).map((x) => x.at))].sort().map(full).join(', ')}`);
+  const nr = (Array.isArray(readings && readings.gaps) ? readings.gaps : []).map((g) => ({ source: names.get(g.source) || g.source, why: g.reason }));
+  slides.push({ kind: 'sources', title: `Every number comes from ${reached.length === 1 ? 'one source' : `${reached.length} sources`}${nr.length ? `; ${nr.length === 1 ? 'one source was' : `${nr.length} sources were`} not reached` : ''}`, reached, notReached: nr, source: 'Source: the readings of this report' });
+  slides.forEach((s, i) => { s.n = i + 1; });
+  return { slides, look: look || null, name: r(report.title), engine: true };
+}
+/** The room under a slide's title, and what a block takes of it (1280 x 720 frames, lib/report-pyramid.js css). */
+const SLIDE_ROOM = 440;
+function blockHeight(b) {
+  if (b.kind === 'p' || b.kind === 'quote') return 30 * Math.ceil(str(b.text).length / 105) + 16;
+  if (b.kind === 'list') return b.items.reduce((h, x) => h + 30 * Math.ceil(str(x).length / 105) + 14, 10);
+  if (b.kind === 'options') return b.options.length * 48 + 10;
+  if (b.kind === 'table') return 56 + b.rows.length * 48;
+  if (b.kind === 'bars') return b.rows.length * 33 + 14;
+  return 40;
+}
+/** One block as the slide draws it: plain text, resolved. */
+function drawBlock(b, r, byId) {
+  if (b.kind === 'p' || b.kind === 'quote') return { kind: 'p', text: r(b.text) };
+  if (b.kind === 'list') return { kind: 'list', items: b.items.map(r) };
+  if (b.kind === 'table') return { kind: 'table', columns: b.columns.map(r), rows: b.rows.map((row) => row.map((c) => r(str(c)))) };
+  if (b.kind === 'options') return { kind: 'list', items: b.options.map((o, i) => `Option ${'ABCD'[i]}: ${r(o.name)}${o.text ? '. ' + r(o.text) : ''}`) };
+  // bars: each bar is one reading; the scale is the largest value (100 for percentages that fit)
+  const rows = b.rows.map(([l, v]) => { const id = tokensIn(v)[0]; const x = byId.get(id); return { label: r(l), text: r(v), value: x && typeof x.value === 'number' ? x.value : 0, unit: x ? x.unit : null }; });
+  const max = rows.every((x) => x.unit === '%' && x.value <= 100) ? 100 : Math.max(1, ...rows.map((x) => x.value));
+  return { kind: 'bars', rows: rows.map((x) => ({ ...x, share: Math.max(0, Math.min(1, x.value / max)) })) };
+}
+
+// ── the steps, written ──────────────────────────────────────────────────────────────────────────────────────────────
+function isIssued(root, id, slot) { return issuedSlots(root, id).includes(slot); }
+/** Steps 1–3: the brief, the readings, the findings, written next to the draft. Filed readings and findings are kept across a re-read. */
+function make(root, id, { slot, ask, readers, sources, add, gaps, addFindings, now = Date.now() } = {}) {
+  const abs = path.resolve(String(root));
+  const day = slot || dayOf(now);
+  let P; try { P = paths(abs, id, day); } catch (e) { return refuse(400, e.message); }
+  if (isIssued(abs, id, day)) return refuse(409, `${id} ${day} is issued; it is frozen`);
+  const old = readJson(P.brief.abs);
+  // a re-read keeps the brief's chat question and named sources unless new ones are given
+  const b = briefOf(abs, id, { slot: day, now, ask: ask || (old && old.from && old.from.includes('chat') ? old.question : undefined), readers: readers || (old && old.from && old.from.includes('readers') ? old.readers : undefined),
+    sources: [...(old ? old.sources.filter((s) => s.kind === 'pack' || s.kind === 'connector' || s.kind === 'document') : []), ...(sources || [])] });
+  if (!b.ok) return b;
+  const rd = readingsOf(abs, b.brief, { add, gaps, keep: readJson(P.readings.abs), now });
+  if (!rd.ok) return rd;
+  const priorSlot = b.brief.last_issue;
+  const prior = priorSlot ? readJson(paths(abs, id, priorSlot).readings.abs) : null;
+  const oldF = readJson(P.findings.abs);
+  const keepFiled = (oldF && Array.isArray(oldF.findings) ? oldF.findings.filter((f) => f.filed && f.readings.every((x) => rd.readings.some((r) => r.id === x))) : []);
+  const fd = findingsOf(b.brief, rd, { prior, add: keepFiled.concat(Array.isArray(addFindings) ? addFindings : []) });
+  if (fd.ok === false) return fd;
+  writeJson(P.brief.abs, b.brief);
+  writeJson(P.readings.abs, { at: rd.at, readings: rd.readings, gaps: rd.gaps });
+  writeJson(P.findings.abs, fd);
+  return { ok: true, brief: b.brief, readings: { readings: rd.readings, gaps: rd.gaps }, findings: fd, paths: { brief: P.brief.rel, readings: P.readings.rel, findings: P.findings.rel, report: P.report.rel, md: P.md.rel } };
+}
+
+/** Steps 4–6: the writer's report.json, checked, then the document rendered. A report with no answer, or a figure that is not a reading, is refused. */
+function write(root, id, slot, report, { now = Date.now() } = {}) {
+  const abs = path.resolve(String(root));
+  let P; try { P = paths(abs, id, slot); } catch (e) { return refuse(400, e.message); }
+  if (isIssued(abs, id, slot)) return refuse(409, `${id} ${slot} is issued; it is frozen`);
+  const brief = readJson(P.brief.abs); const readings = readJson(P.readings.abs); const findings = readJson(P.findings.abs);
+  if (!brief || !readings) return refuse(409, `read it first: pmos report make ${id}${slot ? ' --slot ' + slot : ''}`);
+  if (findings && findings.none) return refuse(422, 'there is no finding, so there is no draft: nothing to report this cycle', { none: true });
+  const pre = checkReport(report, { brief, readings });
+  const hardFail = pre.filter((c) => c.hard && !c.pass);
+  if (hardFail.length) return refuse(422, hardFail.map((c) => `${c.id}: ${c.reason}`).join(' · '), { checks: pre });
+  const clean = { ...report, sections: report.sections.map((s) => ({ ...s, id: str(s.id) || slugOf(s.title) })), carried: brief.carried_asks || [], v: 1, at: new Date(now).toISOString() };
+  const md = renderMarkdown(clean, { brief, readings, now });
+  const checks = checkReport(clean, { brief, readings, markdown: md });
+  writeJson(P.report.abs, clean);
+  writeAtomic(P.md.abs, md);
+  writeJson(P.checks.abs, { at: new Date(now).toISOString(), checks, sha: sha(md) });
+  return { ok: true, path: P.md.rel, report: P.report.rel, checks };
+}
+
+/** The engine's model behind a draft, when the engine wrote it: { report, brief, readings, checks } | null. absMd = <state>/reports/<id>/<slot>.md */
+function engineReportOf(absMd) {
+  const m = /^(.*)\.md$/.exec(str(absMd));
+  if (!m) return null;
+  const report = readJson(m[1] + '.report.json');
+  if (!report) return null;
+  return { report, brief: readJson(m[1] + '.brief.json'), readings: readJson(m[1] + '.readings.json'), checks: readJson(m[1] + '.checks.json') };
+}
+/** The engine deck of a draft in its look, or null when the engine did not write it. */
+function engineDeckOf(absMd, look) {
+  const e = engineReportOf(absMd);
+  if (!e || shapeError(e.report)) return null;
+  return deckOf(e.report, { brief: e.brief, readings: e.readings, look });
+}
+
+module.exports = {
+  ID_RE, BEYOND, BEYOND_KEYS, VOICE, RULE_KINDS, BLOCK_KINDS, LIMITS,
+  paths, briefOf, readingsOf, findingsOf, resolve, tokensIn, bareFigures, checkReport, shapeError, renderMarkdown, deckOf, make, write,
+  engineReportOf, engineDeckOf, rulesOf, addRule, removeRule, closeAsk, parseSource, sourcesFromText, full, valueText,
+};