create-pmos 0.52.0 → 0.53.0

package/workspace/lib/report-draft.js

@@ -0,0 +1,579 @@
+'use strict';
+/* report-draft.js — THE ONE DRAFTER of a cadence report: the per-initiative blocks since the last issue, the markdown,
+ * the PM's notes, and the draft file (pm-os-absorb Run 5, PRD R22, R24; D86 point 3 as ruled on 2026-10-05:
+ * one block per initiative active in the window, covering everything since the last issue).
+ *
+ *   draftOf(root, { cadence, slot, now, health })  → the fixtures/report-api/draft.json shape | { ok: false, status, error }
+ *   render(draft, { notes })                       → markdown; each block carries its note markers (below)
+ *   writeDraft(root, draft, { actor, notes })      → { ok: true, path, sha } | { ok: false, status, error }
+ *   readNotes(markdown)                            → { [initiativeId]: text }   (frozen here, not a stub)
+ *   noteBlock(id, text)                            → the marker pair with the text between (frozen here)
+ *
+ * WHO CALLS WHAT:
+ *   - 5A fills draftOf, render and writeDraft, and `pmos report draft <cadence> [<slot>]` calls them.
+ *   - 5C's routes call them: GET /api/report/draft → draftOf; POST /api/report/draft (Draft now, Redraft) →
+ *     writeDraft(root, draftOf(…), { actor: <requirePagePress actor>, notes: readNotes(<the file now>) });
+ *     POST /api/report/note → readNotes, set one id, writeDraft. ONLY writeDraft writes the file.
+ *   - 5B's skill (report-biweekly.skill) runs `pmos report draft biweekly` and writes prose ONLY between note markers.
+ *     It never appends a "## Later run HH:MM" section: a Redraft rewrites the file and keeps every note.
+ *
+ * THE FILE: planning/reports/<cadence>/<slot>.md, where <cadence> is the skill id suffix (`report-biweekly` →
+ * `biweekly`, the same spelling as the issues line). A slot that isIssued (lib/issues.js) is frozen: writeDraft
+ * refuses it with 409.
+ *
+ * THE NOTE MARKERS (frozen):
+ *   <!-- pmos:note <initiative-id> -->
+ *   …the PM's or the skill's prose, any lines…
+ *   <!-- /pmos:note -->
+ *   One pair per block; an id appears at most once; text is kept byte-for-byte across a Redraft (trimmed of the one
+ *   newline after the open marker and before the close marker).
+ *
+ * WHAT draftOf FOLDS (Run 5, slice 5A). Local files only, no git fetch and no model (X18):
+ *   - the window: since the last issue of this cadence before the slot (lib/issues.js), else report_cycle_days back
+ *     from `now` (X20). Two calls with the same inputs and `now` give the same draft; another `now`, another window;
+ *   - one block per work-lane initiative active in the window (scripts/lane-defs.js group `work`, D86 point 4): in Now,
+ *     or with an item line, a horizon move, a gate or a lifecycle line in the window. Off track and at risk first, then
+ *     the Roadmap order. Stage from initiative-display.js displayOf; health from `health` (a function of the health
+ *     ctx, or a map by id; tests inject it) else lib/health.js healthOf. An off-track or at-risk block with no reason
+ *     at its level refuses the whole draft (422);
+ *   - progress from plan-items (proposed items never count; an item the factory join marks integrated counts done);
+ *     a measured value only from a measurements line whose source is `<path>@<sha>` (no KR is computed here);
+ *   - the Timeline strip from item-spans.js, the PM's own acts under Decided this cycle (a pending proposal never),
+ *     Needs your call from the asks note, for the definition's audience only (X23), and the sources.
+ * The definition `<state>/reports/definitions/<cadence>.md` gives `audience` and `sections` (readDefinition). Besides
+ * the block notes, two notes belong to the report: `report.headline` (the agent's headline) and `report.asks`. A note
+ * whose initiative left the window is kept under "Notes kept from an earlier draft", so no note is ever dropped.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const ledgers = require('./plan-ledgers.js');
+const consoleState = require('./console-state');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const placements = require('./placements.js');
+const measurements = require('./measurements.js');
+const issues = require('./issues.js');
+const factoryJoin = require('./factory-join.js');
+const healthLib = require('./health.js');
+const display = require('./initiative-display.js');
+const itemSpans = require('./item-spans.js');
+const actorLib = require('./actor.js');
+const reviewGate = require('./review-gate.js');
+const { readRules } = require('./plan-rules.js');
+
+const NOTE_OPEN = (id) => `<!-- pmos:note ${id} -->`;
+const NOTE_CLOSE = '<!-- /pmos:note -->';
+const NOTE_RE = /<!-- pmos:note ([a-z0-9][a-z0-9._-]*) -->\n?([\s\S]*?)\n?<!-- \/pmos:note -->/g;
+/** The ids readNotes reads back. A writer refuses any other id, and any text that holds a marker (writeDraft). */
+const NOTE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const MARKER_RE = /<!-- \/?pmos:note[ >]/;
+
+function readNotes(markdown) {
+  const out = {};
+  if (typeof markdown !== 'string') return out;
+  for (const m of markdown.matchAll(NOTE_RE)) if (!Object.prototype.hasOwnProperty.call(out, m[1])) out[m[1]] = m[2];
+  return out;
+}
+
+function noteBlock(id, text) {
+  return `${NOTE_OPEN(id)}\n${text == null ? '' : String(text)}\n${NOTE_CLOSE}`;
+}
+
+// ── constants and small helpers ──────────────────────────────────────────────────────────────────────
+/** The two notes that belong to the report, not to an initiative: the agent's headline and its asks to the audience. */
+const HEADLINE_NOTE = 'report.headline';
+const ASKS_NOTE = 'report.asks';
+/** The frame, in its frozen order (D78 as amended by D86 point 3). A definition's `sections` must name these. */
+const FRAME = Object.freeze(['headline', 'timeline', 'initiatives', 'new', 'decided', 'needs', 'sources']);
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const SOURCE_RE = /^[^@\s]+@[0-9a-f]{7,40}$/;
+const DAY = 86400000;
+const SEVERITY = { off: 3, 'at-risk': 2, unknown: 1, on: 0 };
+const LEVEL_WORD = { off: 'Off track', 'at-risk': 'At risk', unknown: 'Unknown', on: 'On track' };
+const HORIZON_WORD = { now: 'Now', next: 'Next', later: 'Later' };
+const HORIZONS = ['now', 'next', 'later'];
+const LIFECYCLE_WORD = { 'on-hold': 'put on hold', held: 'put on hold', closed: 'closed', cancelled: 'cancelled', active: 'reopened' };
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const has = (o, k) => !!o && Object.prototype.hasOwnProperty.call(o, k);
+const isStr = (v) => typeof v === 'string';
+const refuse = (status, error) => ({ ok: false, status, error, index: null });
+const isDate = (s) => isStr(s) && DATE_RE.test(s) && new Date(s + 'T00:00:00Z').toISOString().slice(0, 10) === s;
+const toMs = (v) => (typeof v === 'number' ? v : Date.parse(String(v == null ? '' : v)));
+const iso = (t) => new Date(t).toISOString().replace('.000Z', 'Z');
+const dayOf = (t) => new Date(t).toISOString().slice(0, 10);
+const cap = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** 16 Oct, from a date or a time. */
+const short = (v) => { const t = toMs(isStr(v) && DATE_RE.test(v) ? v + 'T00:00:00Z' : v); if (!Number.isFinite(t)) return String(v); const d = new Date(t); return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`; };
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+
+function engine() {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded.engine;
+}
+/** `pmos/state` in a kit repository, `planning` in PMOS-self: the `<state>` the report skill names. */
+function stateRel(root) { return engine().layout(path.resolve(String(root))).kit ? 'pmos/state' : 'planning'; }
+/** The draft file of a slot, repository-relative. */
+function draftPath(root, cadence, slot) { return `${stateRel(root)}/reports/${cadence}/${slot}.md`; }
+function definitionPath(root, cadence) { return `${stateRel(root)}/reports/definitions/${cadence}.md`; }
+
+/** Every JSON object line of a file; anything else is skipped. A missing file reads empty. Nothing is cached (D33). */
+function readJsonl(file) {
+  let text;
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { rows: [], exists: false, bad: 0 }; }
+  const rows = []; let bad = 0;
+  for (const raw of text.split('\n')) {
+    if (!raw.trim()) continue;
+    try { const r = JSON.parse(raw); if (r && typeof r === 'object' && !Array.isArray(r)) rows.push(r); else bad++; } catch { bad++; }
+  }
+  return { rows, exists: true, bad };
+}
+
+// ── the definition: structured frontmatter for the script, prose for the agent ─────────────────────────
+/**
+ * `<state>/reports/definitions/<cadence>.md`. The script reads `cadence`, `audience` and `sections` from its
+ * frontmatter; the body is for the agent (report-biweekly.skill). No file is not an error: the frame is the default
+ * and Needs your call stays empty, because no audience is named (X23).
+ */
+function readDefinition(root, cadence) {
+  const rel = definitionPath(root, cadence);
+  const out = { path: rel, exists: false, cadence: null, audience: null, sections: FRAME.slice(), errors: [] };
+  let text;
+  try { text = fs.readFileSync(path.join(path.resolve(String(root)), rel), 'utf8'); } catch { return out; }
+  out.exists = true;
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+  if (!fm) { out.errors.push('it has no frontmatter'); return out; }
+  const map = {};
+  let listKey = null;
+  for (const raw of fm[1].split(/\r?\n/)) {
+    const item = /^\s+-\s+(.*)$/.exec(raw) || /^-\s+(.*)$/.exec(raw);
+    if (item && listKey) { map[listKey].push(unquote(item[1])); continue; }
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(raw);
+    if (!kv) continue;
+    const [, k, v] = kv;
+    if (v === '') { map[k] = []; listKey = k; continue; }
+    listKey = null;
+    map[k] = /^\[.*\]$/.test(v.trim()) ? v.trim().slice(1, -1).split(',').map((x) => unquote(x)).filter(Boolean) : unquote(v);
+  }
+  out.cadence = isStr(map.cadence) ? map.cadence : null;
+  if (out.cadence !== cadence) out.errors.push(`its cadence is ${JSON.stringify(out.cadence)}, not ${cadence}`);
+  out.audience = isStr(map.audience) && map.audience.trim() ? map.audience.trim() : null;
+  if (!out.audience) out.errors.push('it names no audience, so Needs your call stays empty (X23)');
+  if (Array.isArray(map.sections)) {
+    const got = map.sections.map((s) => String(s).trim());
+    if (got.join(',') !== FRAME.join(',')) out.errors.push(`its sections must be ${FRAME.join(', ')}, in that order; the script writes that frame`);
+    out.sections = FRAME.slice();
+  } else out.errors.push('it lists no sections; the script writes the default frame');
+  return out;
+}
+function unquote(s) {
+  const t = String(s).trim();
+  return (/^"(.*)"$/.exec(t) || /^'(.*)'$/.exec(t) || [null, t])[1].trim();
+}
+
+// ── git, read-only and local (X18: never a fetch) ────────────────────────────────────────────────────
+function git(root, args) {
+  try { return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 }); }
+  catch { return null; }
+}
+/** When each initiative record first appeared in history: { [id]: ISO time }. One `git log` for the whole folder. */
+function recordsAdded(root, initDir) {
+  const rel = path.relative(root, initDir).split(path.sep).join('/');
+  const out = git(root, ['log', '--diff-filter=A', '--format=%x01%cI', '--name-only', '--', rel]);
+  const added = {};
+  if (!out) return added;
+  let at = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('\x01')) { at = line.slice(1).trim(); continue; }
+    const m = /([^/]+)\.md$/.exec(line.trim());
+    if (!m || !at) continue;
+    const t = Date.parse(at);
+    if (Number.isFinite(t) && (!has(added, m[1]) || t < Date.parse(added[m[1]]))) added[m[1]] = iso(t);
+  }
+  return added;
+}
+/** The age of the remote refs: the time of the last fetch, read from FETCH_HEAD, or null. Nothing is fetched. */
+function lastFetch(root) {
+  const dir = git(root, ['rev-parse', '--git-common-dir']);
+  if (!dir) return null;
+  try { return iso(fs.statSync(path.resolve(root, dir.trim(), 'FETCH_HEAD')).mtimeMs); } catch { return null; }
+}
+
+// ── health: injected or derived ──────────────────────────────────────────────────────────────────────
+/** `health` is a function of the ctx, or a map { [id]: { level, reasons } }; else lib/health.js healthOf. */
+function healthFor(health, ctx) {
+  let h;
+  if (typeof health === 'function') h = health(ctx);
+  else if (health && typeof health === 'object' && has(health, ctx.id)) h = health[ctx.id];
+  else h = healthLib.healthOf(ctx);
+  const level = h && has(SEVERITY, h.level) ? h.level : 'unknown';
+  const reasons = (h && Array.isArray(h.reasons) ? h.reasons : []).filter((r) => r && isStr(r.text) && r.text.trim())
+    .map((r) => ({ level: has(SEVERITY, r.level) ? r.level : 'unknown', code: String(r.code || ''), text: r.text.trim(), source: String(r.source || '') }));
+  return { level, reasons };
+}
+
+// ── the fold ────────────────────────────────────────────────────────────────────────────────────────
+function draftOf(root, { cadence, slot, now, health } = {}) {
+  if (!isStr(cadence) || !CADENCE_RE.test(cadence)) return refuse(400, 'cadence must be a report id such as biweekly');
+  const nowMs = now == null ? Date.now() : toMs(now);
+  if (!Number.isFinite(nowMs)) return refuse(400, 'now must be a time');
+  const theSlot = slot == null ? dayOf(nowMs) : slot;
+  if (!isDate(theSlot)) return refuse(400, 'slot must be a date, YYYY-MM-DD');
+  let E;
+  try { E = engine(); } catch (e) { return refuse(500, String((e && e.message) || e).slice(0, 200)); }
+  const abs = path.resolve(String(root));
+  const L = E.layout(abs);
+  if (!isDir(L.initiatives)) return refuse(404, `${abs} holds no initiative records; name a PMOS repository with --root`);
+  const main = planTree.mainTree(abs);
+  const relMain = (f) => path.relative(main, f).split(path.sep).join('/');
+  const relHere = (f) => path.relative(abs, f).split(path.sep).join('/');
+  const rules = readRules(abs);
+  const cycle = rules.report_cycle_days;
+  const def = readDefinition(abs, cadence);
+  const rel = draftPath(abs, cadence, theSlot);
+
+  // The window: since the last issue of this cadence before this slot (since_last_issue), else report_cycle_days back.
+  const iss = issues.readIssues(abs);
+  const prior = iss.issues.filter((r) => r.cadence === cadence && r.slot < theSlot)
+    .reduce((a, b) => (!a || String(b.at) >= String(a.at) ? b : a), null);
+  const fromMs = prior ? Date.parse(prior.at) : nowMs - cycle * DAY;
+  const window = { from: prior ? prior.at : iso(fromMs), to: iso(nowMs), since: prior ? 'last_issue' : 'cycle_days' };
+  const inWin = (at) => { const t = toMs(at); return Number.isFinite(t) && t > fromMs && t <= nowMs; };
+  const issuedHere = iss.issues.find((r) => r.cadence === cadence && r.slot === theSlot) || null;
+
+  // The work-lane records (D86 point 4: the lanes scripts/lane-defs.js groups as work; never a hard-coded list).
+  const defs = E.lanesFor(abs).defs || {};
+  const range = E.historyRange(abs);
+  const workRows = E.listInitiatives(abs).map((id) => { try { return E.computeWorkflow(id, { root: abs, range }); } catch { return null; } })
+    .filter((r) => r && r.ok && has(defs, r.lane) && defs[r.lane].group === 'work');
+  // A block's note marker carries its id, and readNotes reads back only NOTE_ID_RE ids: a record named outside that
+  // class would lose its note on the next Redraft, so it gets no block and Sources names it instead.
+  const rows = workRows.filter((r) => NOTE_ID_RE.test(r.id));
+  const noMarker = workRows.filter((r) => !NOTE_ID_RE.test(r.id)).map((r) => r.id).sort(byText);
+  const titleOf = new Map(rows.map((r) => [r.id, r.title || r.id]));
+
+  const fold = planItems.readFold(abs, { now: nowMs });
+  const plc = placements.readPlacements(abs, { now: nowMs, rules, records: rows });
+  const mea = measurements.readMeasurements(abs);
+  const fj = factoryJoin.joinFactory(abs);
+  const acc = readJsonl(path.join(L.runsDir, 'acceptances.jsonl'));
+  const evs = readJsonl(path.join(L.runsDir, 'evals.jsonl'));
+  const life = readJsonl(path.join(L.runsDir, 'lifecycle.jsonl'));
+  const added = recordsAdded(abs, L.initiatives);
+  let existing = null;
+  try { existing = fs.readFileSync(path.join(abs, rel), 'utf8'); } catch { existing = null; }
+  const notes = readNotes(existing);
+
+  const itemsOf = (id) => fold.order.map((x) => fold.items[x]).filter((it) => it && it.initiative === id);
+  const blocks = [];
+  for (const row of rows) {
+    const id = row.id;
+    const its = itemsOf(id);
+    const placement = has(plc.byInit, id) ? plc.byInit[id] : null;
+    const horizon = placements.horizonOf(plc, id);
+    const moves = plc.moves.filter((m) => m.init === id && inWin(m.at));
+    const gates = [
+      ...acc.rows.filter((a) => a.initiative_id === id && a.accepted === true && inWin(a.accepted_at || a.at)).map((a) => ({ gate: 'acceptance', at: String(a.accepted_at || a.at) })),
+      // A review gate passed only on a passing verdict (review-gate.js: FAIL and SKIPPED never count); eval rows carry recorded_at.
+      ...evs.rows.filter((e) => e.initiative_id === id && reviewGate.isReviewPass(e.verdict, e.score) && inWin(e.recorded_at || e.at))
+        .map((e) => ({ gate: 'review', at: String(e.recorded_at || e.at) })),
+    ].sort((a, b) => byText(a.at, b.at) || byText(a.gate, b.gate));
+    const lifeHere = life.rows.filter((l) => l.initiative_id === id && inWin(l.at));
+    const touched = its.some((it) => it.history.some((h) => inWin(h.at)));
+    if (row.stopped && Number.isFinite(toMs(row.stopped.at)) && toMs(row.stopped.at) <= fromMs) continue;
+    const active = (placement && horizon === 'now') || touched || moves.length || gates.length || lifeHere.length;
+    if (!active) continue;
+
+    const narrowed = { items: Object.fromEntries(its.map((it) => [it.id, it])), order: its.map((it) => it.id),
+      batches: (fold.batches || []).filter((b) => b.initiative === id), flags: (fold.flags || []).filter((f) => f.initiative === id) };
+    const lastAcc = acc.rows.filter((a) => a.initiative_id === id && a.accepted === true).pop() || null;
+    const measurement = row.anchor ? measurements.latest(mea, String(row.anchor).split(' ')[0]) : null;
+    const factory = factoryJoin.factoryOf(fj, id);
+    const ctx = { id, row, fold: narrowed, placement, measurement, factory, rules, now: nowMs };
+    const h = healthFor(health, ctx);
+    if ((h.level === 'off' || h.level === 'at-risk') && !h.reasons.some((r) => r.level === h.level)) {
+      return refuse(422, `${id} reads ${LEVEL_WORD[h.level].toLowerCase()} with no reason. A block that is off track or at risk must say why, so no draft was made`);
+    }
+    const disp = display.displayOf(row, {
+      lifecycle: row.stopped ? { state: row.stopped.state, reason: row.stopped.reason || null, at: row.stopped.at || null } : null,
+      acceptance: lastAcc ? { at: String(lastAcc.accepted_at || lastAcc.at || ''), by: actorLib.pageName(lastAcc.by || (lastAcc.pm ? `pm:${lastAcc.pm}` : null)) } : null,
+      handoff: null, fold: narrowed, placement, rules, now: nowMs,
+    });
+
+    const integrated = new Set(((factory && factory.items) || []).filter((w) => w && w.integrated && w.plan_item).map((w) => w.plan_item));
+    const real = its.filter((it) => !it.proposed);
+    const isDone = (it) => it.state === 'done' || integrated.has(it.id);
+    const doneNow = real.filter((it) => it.state === 'done' && inWin(it.doneAt));
+    const done = real.filter(isDone).length;
+    const today = dayOf(nowMs);
+    const horizonEnd = dayOf(nowMs + cycle * DAY);
+    const open = real.filter((it) => !isDone(it));
+    const carried = open.filter((it) => it.due && it.due < today)
+      .sort((a, b) => byText(a.due, b.due) || byText(a.id, b.id)).map((it) => ({ id: it.id, title: it.title, due: it.due }));
+    const stageIds = planTree.stageIdsFor(abs, id);
+    const stageIdx = (s) => { const k = stageIds.indexOf(s); return k === -1 ? stageIds.length : k; };
+    const ordered = open.slice().sort((a, b) => (stageIdx(a.stage) - stageIdx(b.stage)) || (a.order - b.order)
+      || byText(String(a.createdAt), String(b.createdAt)) || byText(a.id, b.id));
+    const dated = ordered.filter((it) => [it.start, it.due].some((d) => d && d >= today && d <= horizonEnd));
+    const coming = dated.length ? { basis: 'dates', list: dated } : { basis: 'order', list: ordered.slice(0, 3) };
+    const m = measurement && SOURCE_RE.test(String(measurement.source)) ? measurement : null;
+
+    blocks.push({
+      id, title: titleOf.get(id),
+      stage: cap(disp.stage || row.stage || 'unknown'),
+      health: { level: h.level, reasons: h.reasons },
+      progress: { done, total: real.length, delta: doneNow.length,
+        label: real.length ? `${done} of ${real.length} (+${doneNow.length})` : planTree.progressLabel(0, 0, its.length - real.length) },
+      measure: m ? { anchor: String(row.anchor).split(' ')[0], value: m.value, target: m.target, unit: m.unit, as_of: m.as_of, source: m.source } : null,
+      last_cycle: {
+        done: doneNow.map((it) => ({ id: it.id, title: it.title })),
+        gates,
+        moves: moves.map((mv) => ({ from: mv.from, to: mv.to, at: mv.at })),
+        carried,
+      },
+      coming_cycle: { basis: coming.basis, items: coming.list.map((it) => ({ id: it.id, title: it.title, start: it.start || null, due: it.due || null })) },
+      note: has(notes, id) ? notes[id] : '',
+      _order: [SEVERITY[h.level], HORIZONS.indexOf(horizon), placement ? placement.rank : Infinity],
+    });
+  }
+  // Off track and at risk first; then Now, Next, Later in their Roadmap order; then the id.
+  blocks.sort((a, b) => (b._order[0] - a._order[0]) || (a._order[1] - b._order[1]) || (a._order[2] - b._order[2]) || byText(a.id, b.id));
+  for (const b of blocks) delete b._order;
+
+  // The Timeline strip, frozen at fold time: one row per block with dated items, one span per stage.
+  const timeline = { from: dayOf(fromMs), to: dayOf(nowMs + cycle * DAY), today: dayOf(nowMs), rows: [] };
+  for (const b of blocks) {
+    const spans = itemSpans.spansOf(itemsOf(b.id).filter((it) => !it.proposed));
+    if (!spans.length) continue;
+    const stageIds = planTree.stageIdsFor(abs, b.id);
+    const byStage = new Map();
+    for (const s of spans) { const k = s.stage || ''; if (!byStage.has(k)) byStage.set(k, []); byStage.get(k).push(s); }
+    const keys = [...byStage.keys()].sort((x, y) => ((stageIds.indexOf(x) + 1 || 99) - (stageIds.indexOf(y) + 1 || 99)) || byText(x, y));
+    timeline.rows.push({
+      id: b.id, title: b.title,
+      spans: keys.map((k) => ({ stage: k || null, ...itemSpans.initiativeSpan(byStage.get(k)), milestone: false })),
+      milestones: [...new Set(spans.filter((s) => s.milestone).map((s) => s.due))].sort(),
+    });
+  }
+
+  const newSince = rows.filter((r) => has(added, r.id) && inWin(added[r.id]))
+    .map((r) => ({ id: r.id, title: titleOf.get(r.id), at: added[r.id] })).sort((a, b) => byText(a.at, b.at) || byText(a.id, b.id));
+
+  // Decided this cycle: the PM's own acts in the window, after the fact. A pending decision (an agent's proposal, a
+  // batch not kept yet) is never here and never in the body: it reaches the PM as a Cycle review row (R22.4).
+  const work = new Set(rows.map((r) => r.id));
+  const decided = [];
+  const plcRel = relMain(ledgers.ledgerPath(abs, 'placements'));
+  for (const mv of plc.moves) {
+    if (work.has(mv.init) && inWin(mv.at) && isStr(mv.by) && mv.by.startsWith('pm:')) decided.push({ text: `${titleOf.get(mv.init)} moved to ${HORIZON_WORD[mv.to] || mv.to}`, at: mv.at, source: plcRel });
+  }
+  for (const l of life.rows) {
+    if (work.has(l.initiative_id) && inWin(l.at) && has(LIFECYCLE_WORD, l.state)) decided.push({ text: `${titleOf.get(l.initiative_id)} ${LIFECYCLE_WORD[l.state]}`, at: String(l.at), source: relHere(path.join(L.runsDir, 'lifecycle.jsonl')) });
+  }
+  for (const a of acc.rows) {
+    const at = a.accepted_at || a.at;
+    if (work.has(a.initiative_id) && a.accepted === true && inWin(at)) decided.push({ text: `Acceptance recorded for ${titleOf.get(a.initiative_id)}`, at: String(at), source: relHere(path.join(L.runsDir, 'acceptances.jsonl')) });
+  }
+  const kept = new Map();
+  for (const id of fold.order) {
+    const it = fold.items[id];
+    if (!it || !work.has(it.initiative)) continue;
+    for (const hh of it.history) if (hh.ev === 'kept' && inWin(hh.at) && isStr(hh.by) && hh.by.startsWith('pm:')) {
+      const k = kept.get(hh.eid) || { init: it.initiative, at: hh.at, n: 0 };
+      k.n++; kept.set(hh.eid, k);
+    }
+  }
+  const piRel = relMain(ledgers.ledgerPath(abs, 'plan-items'));
+  for (const k of kept.values()) decided.push({ text: `${titleOf.get(k.init)}: ${plural(k.n, 'item', 'items')} an agent proposed kept`, at: k.at, source: piRel });
+  decided.sort((a, b) => byText(a.at, b.at) || byText(a.text, b.text));
+
+  // Needs your call: the agent's asks to the named audience only (X23), read back from the draft's own note.
+  const asks = def.audience && has(notes, ASKS_NOTE)
+    ? notes[ASKS_NOTE].split('\n').map((l) => /^\s*[-*]\s+(.+)$/.exec(l)).filter(Boolean).map((mm) => ({ text: mm[1].trim(), audience: def.audience }))
+    : [];
+
+  // Sources reached and not reached. Local files only; the remote refs are named with their age and never fetched.
+  const reached = [];
+  const notReached = [];
+  for (const name of ['plan-items', 'placements', 'measurements', 'issues']) {
+    const f = ledgers.ledgerPath(abs, name);
+    if (fs.existsSync(f)) reached.push(relMain(f));
+  }
+  for (const [f, r] of [['acceptances.jsonl', acc], ['evals.jsonl', evs], ['lifecycle.jsonl', life]]) {
+    if (r.exists) reached.push(relHere(path.join(L.runsDir, f)));
+    if (r.bad) notReached.push({ source: relHere(path.join(L.runsDir, f)), why: `${plural(r.bad, 'line', 'lines')} could not be read` });
+  }
+  if (def.exists) reached.push(def.path);
+  else notReached.push({ source: def.path, why: 'no definition; the default frame is used and no audience is named' });
+  for (const e of def.errors) if (def.exists) notReached.push({ source: def.path, why: e });
+  const unreadable = (list, rel2) => { const n = list.filter((f) => f.kind === 'unreadable' || f.kind === 'unparseable').length; if (n) notReached.push({ source: rel2, why: `${plural(n, 'line', 'lines')} could not be read` }); };
+  unreadable(fold.flags || [], piRel);
+  unreadable(plc.flags || [], plcRel);
+  unreadable(mea.flags || [], relMain(ledgers.ledgerPath(abs, 'measurements')));
+  unreadable(iss.flags || [], relMain(ledgers.ledgerPath(abs, 'issues')));
+  // A tracker is refreshed by the tracker-refresh skill (an agent, D71), never by this script (X19). Its evidence is a
+  // MOVE of a tracker-owned item that carries `file:` evidence outside what PMOS writes (the skill's rule 8). Any other
+  // plan-items line (a set, a PM move, a move citing a ledger) is not evidence that the tracker was read: counting it
+  // would let the ledger confirm itself.
+  const pmosWritten = (ref) => /\.jsonl$/.test(ref) || /(^|\/)(runs|reports)\//.test(ref);
+  const isEvidence = (h) => h.ev === 'moved' && h.evidence && h.evidence.kind === 'file' && isStr(h.evidence.ref) && !pmosWritten(h.evidence.ref);
+  const trackerItems = fold.order.map((x) => fold.items[x]).filter((it) => it && work.has(it.initiative) && isStr(it.owner) && it.owner.startsWith('tracker:'));
+  if (trackerItems.length) {
+    const seen = trackerItems.flatMap((it) => it.history.filter(isEvidence).map((h) => String(h.at))).sort();
+    const lastSeen = seen.length ? seen.pop() : null;
+    if (lastSeen && inWin(lastSeen)) reached.push('tracker (file evidence on tracker-owned moves in plan-items)');
+    else notReached.push({ source: 'tracker', why: lastSeen ? `not refreshed since ${short(lastSeen)}` : 'no refresh with file evidence on record' });
+  }
+  const fetched = lastFetch(abs);
+  if (fetched) reached.push(`remote refs (last fetch ${short(fetched)}; not fetched for this draft)`);
+  else notReached.push({ source: 'remote refs', why: 'never fetched; this draft reads local refs only' });
+  for (const id of noMarker) notReached.push({ source: relHere(path.join(L.initiatives, `${id}.md`)), why: 'no block: a note needs a record name of lower-case letters, digits, ".", "_" or "-"; rename the record' });
+
+  const moved = blocks.filter((b) => b.progress.delta || b.last_cycle.done.length || b.last_cycle.gates.length || b.last_cycle.moves.length).length;
+  const off = blocks.filter((b) => b.health.level === 'off').length;
+  const risk = blocks.filter((b) => b.health.level === 'at-risk').length;
+  const headline = !blocks.length ? 'No initiative was active in this window.'
+    : [`${plural(moved, 'initiative', 'initiatives')} moved`, off ? `${off} ${off === 1 ? 'is' : 'are'} off track` : null,
+      risk ? `${risk} ${risk === 1 ? 'is' : 'are'} at risk` : null].filter(Boolean).join('; ') + '.';
+
+  return {
+    ok: true, cadence, slot: theSlot, window, path: rel,
+    issued: issuedHere ? { at: issuedHere.at, by: actorLib.pageName(issuedHere.by), sha: issuedHere.sha, path: issuedHere.path } : null,
+    headline, timeline, blocks, new_since_last: newSince, decided, needs_your_call: asks,
+    sources: { reached, not_reached: notReached, definition: { path: def.exists ? def.path : null, audience: def.audience } },
+  };
+}
+
+// ── the markdown ────────────────────────────────────────────────────────────────────────────────────
+const esc = (s) => String(s == null ? '' : s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+function render(draft, { notes } = {}) {
+  if (!draft || draft.ok === false) return '';
+  const n = notes && typeof notes === 'object' ? notes : {};
+  const noteOf = (id, fallback) => (has(n, id) ? n[id] : (fallback == null ? '' : fallback));
+  const name = cap(draft.cadence);
+  const audience = draft.sources && draft.sources.definition ? draft.sources.definition.audience : null;
+  const out = [];
+  const push = (...l) => out.push(...l);
+  push('---', 'type: Reference', `title: "${name} report ${draft.slot}"`,
+    `description: "The ${draft.cadence} report for ${draft.slot}. pmos report draft writes every number; prose goes only between the note markers."`,
+    `timestamp: ${draft.window.to}`, `cadence: ${draft.cadence}`, `slot: ${draft.slot}`,
+    `window: "${draft.window.from} to ${draft.window.to} (${draft.window.since === 'last_issue' ? 'since the last issue' : 'report_cycle_days back'})"`,
+    '---', '', `# ${name} report ${draft.slot}`, '');
+
+  push('## Headline', '', draft.headline, '', noteBlock(HEADLINE_NOTE, noteOf(HEADLINE_NOTE)), '');
+
+  push('## Timeline', '', `Frozen at ${draft.window.to}. ${short(draft.timeline.from)} to ${short(draft.timeline.to)}; today is ${short(draft.timeline.today)}.`, '');
+  if (draft.timeline.rows.length) {
+    push('| Initiative | Stage | Start | Due | Milestones |', '|---|---|---|---|---|');
+    for (const r of draft.timeline.rows) {
+      r.spans.forEach((s, i) => push(`| ${i ? '' : esc(r.title)} | ${esc(s.stage || '-')} | ${s.start || '-'} | ${s.due || '-'} | ${i ? '' : (r.milestones.map(short).join(', ') || '-')} |`));
+    }
+  } else push('No initiative in this report has dated items.');
+  push('');
+
+  push('## Initiatives', '');
+  if (!draft.blocks.length) push('No initiative was active in this window.', '');
+  for (const b of draft.blocks) {
+    push(`### ${b.title} (${b.id})`, '');
+    const reason = b.health.reasons.find((r) => r.level === b.health.level);
+    push(`Stage: ${b.stage} · ${LEVEL_WORD[b.health.level]}${reason ? `: ${reason.text}` : ''} · ${b.progress.label}`);
+    if (b.measure) push('', `Measured: ${b.measure.anchor} ${b.measure.value}${b.measure.unit || ''}${b.measure.target == null ? '' : ` of ${b.measure.target}${b.measure.unit || ''}`}, as of ${b.measure.as_of} (${b.measure.source})`);
+    push('', '**Last cycle**', '');
+    const lc = b.last_cycle;
+    push(`- Done: ${lc.done.length ? lc.done.map((x) => `${x.title} (${x.id})`).join('; ') : 'none'}`);
+    push(`- Gates passed: ${lc.gates.length ? lc.gates.map((g) => `${g.gate}, ${short(g.at)}`).join('; ') : 'none'}`);
+    push(`- Horizon moves: ${lc.moves.length ? lc.moves.map((m) => `${HORIZON_WORD[m.from] || 'none'} to ${HORIZON_WORD[m.to] || m.to}, ${short(m.at)}`).join('; ') : 'none'}`);
+    push(`- Overdue, carried over: ${lc.carried.length ? lc.carried.map((x) => `${x.title}, due ${short(x.due)}`).join('; ') : 'none'}`);
+    push('', `**Coming cycle** (${b.coming_cycle.basis === 'dates' ? 'items that start or fall due' : 'the next 3 by order'})`, '');
+    if (!b.coming_cycle.items.length) push('- none');
+    for (const x of b.coming_cycle.items) push(`- ${x.title}${x.start ? `, starts ${short(x.start)}` : ''}${x.due ? `, due ${short(x.due)}` : ''}`);
+    push('', noteBlock(b.id, noteOf(b.id, b.note)), '');
+  }
+
+  push('## New since last report', '');
+  if (!draft.new_since_last.length) push('None.');
+  for (const x of draft.new_since_last) push(`- ${x.title} (${x.id}), ${short(x.at)}`);
+  push('');
+
+  push('## Decided this cycle', '');
+  if (!draft.decided.length) push('None.');
+  for (const x of draft.decided) push(`- ${x.text}, ${short(x.at)} (${x.source})`);
+  push('');
+
+  push('## Needs your call', '');
+  if (audience) push(`For ${audience} only.`, '', noteBlock(ASKS_NOTE, noteOf(ASKS_NOTE)));
+  else push('The definition names no audience, so this report asks nothing. The Cycle review card asks the PM.');
+  push('');
+
+  push('## Sources reached and not reached', '', '**Reached**', '');
+  if (!draft.sources.reached.length) push('- none');
+  for (const s of draft.sources.reached) push(`- ${s}`);
+  push('', '**Not reached**', '');
+  if (!draft.sources.not_reached.length) push('- none');
+  for (const s of draft.sources.not_reached) push(`- ${s.source}: ${s.why}`);
+  push('');
+
+  // Every note is kept, byte for byte: a note whose initiative left the window moves here instead of being lost.
+  const placed = new Set([HEADLINE_NOTE, ...(audience ? [ASKS_NOTE] : []), ...draft.blocks.map((b) => b.id)]);
+  const orphans = Object.keys(n).filter((k) => !placed.has(k)).sort(byText);
+  if (orphans.length) {
+    push('## Notes kept from an earlier draft', '', 'These initiatives are not in this window. Their notes are kept as they were written.', '');
+    for (const k of orphans) push(noteBlock(k, n[k]), '');
+  }
+  return out.join('\n');
+}
+
+// ── the one writer of the draft file ───────────────────────────────────────────────────────────────────
+/**
+ * Write `draft` as markdown, keeping every note. `notes` defaults to the notes of the file on disk, so a Redraft that
+ * passes none still keeps them. `fresh: true` (`pmos report draft` without --redraft) refuses a slot that has a draft
+ * already (409), from local state only (X18). An issued slot is frozen: 409.
+ */
+function writeDraft(root, draft, { actor, notes, fresh } = {}) {
+  if (!draft || draft.ok === false) return draft && draft.status ? draft : refuse(400, 'there is no draft to write');
+  if (!actorLib.valid(actor)) return refuse(403, 'a draft is written by an actor from the call path; nothing was written');
+  if (!isStr(draft.cadence) || !CADENCE_RE.test(draft.cadence) || !isDate(draft.slot)) return refuse(400, 'the draft has no valid cadence and slot');
+  const abs = path.resolve(String(root));
+  if (!isDir(abs)) return refuse(404, `${abs} is not a directory; nothing was written`);
+  let rel;
+  try { rel = draftPath(abs, draft.cadence, draft.slot); } catch (e) { return refuse(500, String((e && e.message) || e).slice(0, 200)); }
+  if (draft.path !== rel) return refuse(400, `the draft names ${draft.path}; this repository keeps it at ${rel}`);
+  const iss = issues.readIssues(abs);
+  if (issues.isIssued(iss, draft.cadence, draft.slot)) return refuse(409, `${draft.cadence} ${draft.slot} is issued and frozen. Nothing was written. Draft the next slot.`);
+  const file = path.join(abs, rel);
+  let st = null;
+  try { st = fs.lstatSync(file); } catch { st = null; }
+  if (st && !st.isFile()) return refuse(403, `${rel} is not a regular file; nothing was written`);
+  if (st && fresh) return refuse(409, `a draft for ${draft.cadence} ${draft.slot} exists at ${rel}. Nothing was written`);
+  let kept = notes;
+  if (kept == null) { try { kept = readNotes(fs.readFileSync(file, 'utf8')); } catch { kept = {}; } }
+  if (!kept || typeof kept !== 'object' || Array.isArray(kept)) return refuse(400, 'notes must be an object of note texts by id; nothing was written');
+  // Refuse what readNotes cannot read back byte for byte, so a Redraft never drops or cuts a note (C6).
+  const badId = [...(Array.isArray(draft.blocks) ? draft.blocks.map((b) => b && b.id) : []), ...Object.keys(kept)].find((id) => !isStr(id) || !NOTE_ID_RE.test(id));
+  if (badId !== undefined) return refuse(400, `${JSON.stringify(badId)} cannot carry a note: use lower-case letters, digits, ".", "_" or "-". Nothing was written`);
+  const marked = Object.keys(kept).find((id) => kept[id] != null && MARKER_RE.test(String(kept[id])));
+  if (marked !== undefined) return refuse(400, `the note for ${marked} holds a note marker (<!-- pmos:note or <!-- /pmos:note). Remove it from the note. Nothing was written`);
+  const md = render(draft, { notes: kept });
+  const tmp = `${file}.tmp-${crypto.randomBytes(6).toString('hex')}`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, md, { flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* not made */ }
+    return refuse(500, 'could not write the draft; nothing was written: ' + String((e && e.message) || e).slice(0, 160));
+  }
+  return { ok: true, path: rel, sha: issues.blobSha(Buffer.from(md, 'utf8')) };
+}
+
+module.exports = {
+  draftOf, render, writeDraft, readNotes, noteBlock, NOTE_OPEN, NOTE_CLOSE, NOTE_RE, NOTE_ID_RE,
+  readDefinition, stateRel, draftPath, definitionPath, FRAME, HEADLINE_NOTE, ASKS_NOTE,
+};