create-pmos 0.179.0 → 0.181.0

package/workspace/lib/report-setups.js

@@ -0,0 +1,743 @@
+'use strict';
+/* report-setups.js — the recurring reports a PM has set up, the proposals PMOS makes for them and the reports it finds
+ * (initiative report-workspace, PRD sections 2 to 4). THE ONE WRITER and THE ONE FOLD of <state>/report-setups.jsonl.
+ *
+ *   LEDGER · EVENTS · OUTPUTS · CADENCES · FINDER_SOURCES · LIMITS
+ *   ledgerFile(root) · stateDir(root)            <state> is `pmos/state` in a kit repository, `planning` in PMOS-self (report-draft.js stateRel)
+ *   append(file, line, { now })                  → the line written. THE SINGLE WRITER. `v` and `at` are set here.
+ *   readLines(file) · fold(lines)                → the current state (see FOLD)
+ *   checkProposal(input)                         → { ok, proposal } | { ok: false, error }   the shape of a proposal, as an agent files it
+ *   patternOf(name, pattern) · slugOf(name)      the stable key of a found report; the id a name makes
+ *   scheduleLabel(schedule) · scheduleOf(setup)  the plain phrase, and the schedule-logic.js form of a setup's schedule
+ *   firstSlot(schedule, now) · initialLastRun(schedule, now) · nextDraftAt(schedule, lastRun, now)     the bi-weekly parity (below)
+ *   definitionText(setup, { product, now }) · writeDefinition(root, setup, { now })     the definition a setup writes
+ *   setUp(root, input, opts) · change(root, id, patch, opts) · pause / resume / remove(root, id, opts)    the PM's presses
+ *   scheduleFor(setup) · registerSchedule(store, setup, opts) · unregisterSchedule(store, setup)         the draft-only schedule
+ *   askStart / askChange / askCancel / askEnd / fileProposal(file, …)         the Ask box
+ *   fileFinding / dismissFinding / setFinder / findStart / findEnd           the weekly finder
+ *   migrate(root, { runtimeDir, wsId, isHome, titleOf, now })      the dashboard schedules, once
+ *   dashboardKeys(root)                                            the dashboard keys the old schedule tick leaves alone (migrated, or held by a setup)
+ *   writeDocument(root, setup, slot, markdown, { now })            <state>/reports/<id>/<slot>.md for a dashboard-sourced setup
+ *
+ * THE LINES. Every line is { v: 1, ev, …, at, by? }. Who wrote a line is the call path (lib/actor.js), never an argument:
+ *   setup           { id, name, purpose, audience, source: 'work'|'dashboard:<key>', output, schedule, sources[], sections[], learned_from, fixes[],
+ *                     product, ws, last_run, def_sha, from? }      the PM pressed Set up. `from` is { ask } or { finding }
+ *   change          { id, …the fields that changed }              the PM edited a recurring report
+ *   pause · resume · remove  { id }
+ *   drafted         { id, slot, path }                            a dashboard-sourced setup made its document (this is its last run)
+ *   ask-start       { ask, text, ws }                             the PM typed a request in the Ask box
+ *   proposal        { ask, proposal }                             the report-setup run filed ONE proposal (a second one revises it)
+ *   proposal-change { ask, text }                                 the PM asked for a correction; a second run revises the same proposal
+ *   proposal-cancel { ask }
+ *   ask-end         { ask, ok, error? }                           the run ended (a failed run says why)
+ *   find-start · find-end   { run, ok?, error?, found? }          one weekly finder run
+ *   finding         { id, run, pattern, name, why, evidence[], confidence, proposal }
+ *   finding-dismiss { id?, pattern }                              "Not a report": the pattern is not proposed again
+ *   finder          { cadence?, sources? }                        the finder settings: weekly | off, and the four sources
+ *   migrated        { keys[], count }                             the one-time move of the dashboard schedules
+ *
+ * FOLD. { setups: Map id → setup, asks: Map, findings: Map, dismissed: { patterns, names }, finder: { cadence, sources }, finds: [], migrated }.
+ * A later line wins field by field; a `remove` drops the setup; a line that does not parse, or names an unknown event, is skipped.
+ *
+ * THE BI-WEEKLY PARITY. lib/schedule-logic.js fires a bi-weekly schedule on the first matching weekday slot that is at least 12.5 days after
+ * lastRun. A schedule added on a Monday would therefore draft on the Wednesday two weeks out, whatever week the session is in. With an
+ * `anchor` (the date of the next session) the first draft is the draft day on or just before the anchor, and lastRun is set 14 days before
+ * it: the slot a week before it is 7 days from lastRun, so it does not fire, and the first slot is exact.
+ *
+ * NOTHING HERE SENDS ANYTHING. A setup writes a definition, registers a draft-only schedule (skill report-template, which drafts a file) and
+ * appends a line. The factory never writes here (D65): a proposal is data, and only a PM press sets a report up.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const logic = require('./schedule-logic.js');
+const reportDraft = require('./report-draft.js');
+const docSync = require('./doc-sync.js');
+
+const LEDGER = 'report-setups.jsonl';
+const EVENTS = Object.freeze(['setup', 'change', 'pause', 'resume', 'remove', 'drafted', 'ask-start', 'proposal', 'proposal-change', 'proposal-cancel', 'ask-end',
+  'find-start', 'find-end', 'finding', 'finding-dismiss', 'finder', 'migrated']);
+const OUTPUTS = Object.freeze(['google-slides', 'google-doc', 'google-sheets', 'confluence', 'pdf']);
+const CADENCES = Object.freeze(['daily', 'weekly', 'bi-weekly', 'monthly']);
+const DAYS = Object.freeze(['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']);
+const FINDER_CADENCES = Object.freeze(['weekly', 'off']);
+const FINDER_SOURCES = Object.freeze(['calendar', 'slack', 'mail', 'drive']);
+const FINDER_DEFAULTS = Object.freeze({ calendar: true, slack: true, mail: false, drive: true });
+const EVIDENCE_KINDS = Object.freeze(['mail', 'calendar', 'slack', 'drive', 'confluence']);
+const CONFIDENCE = Object.freeze(['likely', 'not-sure']);
+const LIMITS = Object.freeze({ name: 80, purpose: 400, audience: 120, text: 1000, sources: 12, sections: 12, fixes: 8, found: 8, evidence: 6, findings: 5, asks: 20 });
+const ID_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const ASK_RE = /^ask-[0-9a-f]{10}$/;
+const FINDING_RE = /^rf-[0-9a-f]{10}$/;
+const RUN_RE = /^frun-[0-9a-f]{10}$/;
+const PATTERN_RE = /^[a-z0-9][a-z0-9:._ -]{1,119}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const TIME_RE = /^([01]?\d|2[0-3]):[0-5]\d$/;
+const FRAME = reportDraft.FRAME;
+const DASH_RE = /^dashboard:(portfolio|(board|initiative):[A-Za-z0-9._-]{1,80})$/;
+const DAY_MS = 86400000;
+
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const oneLine = (v, max) => typeof v === 'string' && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n\x00-\x08\x0b-\x1f]/.test(v);
+const newId = (prefix, bytes = 5) => `${prefix}-${crypto.randomBytes(bytes).toString('hex')}`;
+const refuse = (status, error) => ({ ok: false, status, error });
+const iso = (now) => new Date(now == null ? Date.now() : now).toISOString();
+const pad = (n) => String(n).padStart(2, '0');
+const localDay = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+/** 21 October 2026, written in full (a report never says "next week"). */
+const longDate = (d) => `${d.getDate()} ${MONTHS[d.getMonth()]} ${d.getFullYear()}`;
+
+// ── the one writer, and the read ─────────────────────────────────────────────────────────────────────
+/** <root>/<state>: `pmos/state` in a kit repository, `planning` in PMOS-self. */
+function stateDir(root) { const abs = path.resolve(String(root)); return path.join(abs, reportDraft.stateRel(abs)); }
+function ledgerFile(root) { return path.join(stateDir(root), LEDGER); }
+
+/** THE SINGLE WRITER of report-setups.jsonl. `v` and `at` are set here; a caller never chooses them. */
+function append(file, line, { now, by } = {}) {
+  if (!file) throw new Error('report-setups: no ledger file');
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`report-setups: unknown event ${JSON.stringify(line && line.ev)}`);
+  const out = { ...line, v: 1, at: iso(now), ...(by ? { by } : {}) };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(out) + '\n');
+  return out;
+}
+function readLines(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 l = JSON.parse(raw); if (isObj(l) && EVENTS.includes(l.ev)) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+
+// ── names and keys ─────────────────────────────────────────────────────────────────────────────────
+/** The id a name makes: lower-case words joined by "-", starting with a letter, at most 40 characters. */
+function slugOf(name) {
+  let s = String(name == null ? '' : name).normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  if (!s) s = 'report';
+  if (!/^[a-z]/.test(s)) s = 'r-' + s;
+  s = s.slice(0, 40).replace(/-+$/g, '');
+  return s || 'report';
+}
+/** The stable key of a found report: the agent's own `pattern` (lower-cased, spaces folded), else `name:<slug of the name>`. */
+function patternOf(name, pattern) {
+  const p = String(pattern == null ? '' : pattern).trim().toLowerCase().replace(/\s+/g, ' ');
+  if (p && PATTERN_RE.test(p)) return p;
+  return 'name:' + slugOf(name);
+}
+
+// ── shapes ───────────────────────────────────────────────────────────────────────────────────────────
+function checkSchedule(x) {
+  const s = isObj(x) ? x : {};
+  if (!CADENCES.includes(s.cadence)) return { ok: false, error: `schedule.cadence is one of ${CADENCES.join(', ')}` };
+  const out = { cadence: s.cadence, time: '09:00' };
+  if (s.time != null && s.time !== '') {
+    if (!TIME_RE.test(String(s.time))) return { ok: false, error: 'schedule.time is HH:MM, 24-hour' };
+    const [h, m] = String(s.time).split(':'); out.time = `${pad(+h)}:${m}`;
+  }
+  if (s.cadence === 'weekly' || s.cadence === 'bi-weekly') {
+    out.day = s.day == null || s.day === '' ? 'Mon' : s.day;
+    if (!DAYS.includes(out.day)) return { ok: false, error: `schedule.day is one of ${DAYS.join(', ')}` };
+  }
+  if (s.cadence === 'monthly') {
+    out.dayOfMonth = s.dayOfMonth == null || s.dayOfMonth === '' ? 1 : +s.dayOfMonth;
+    if (!(Number.isInteger(out.dayOfMonth) && out.dayOfMonth >= 1 && out.dayOfMonth <= 28)) return { ok: false, error: 'schedule.dayOfMonth is a whole number from 1 to 28' };
+  }
+  out.anchor = null;
+  if (s.anchor != null && s.anchor !== '') {
+    if (!DATE_RE.test(String(s.anchor)) || Number.isNaN(Date.parse(s.anchor + 'T00:00:00Z'))) return { ok: false, error: 'schedule.anchor is a date, YYYY-MM-DD (the next session)' };
+    out.anchor = String(s.anchor);
+  }
+  return { ok: true, schedule: out };
+}
+
+function listOf(v, max, item, what) {
+  if (v == null) return { ok: true, list: [] };
+  if (!Array.isArray(v)) return { ok: false, error: `${what} is a list` };
+  if (v.length > max) return { ok: false, error: `${what} holds at most ${max} items` };
+  const list = [];
+  for (const x of v) { if (!oneLine(x, item)) return { ok: false, error: `each of ${what} is one line of 1 to ${item} characters` }; list.push(x.trim()); }
+  return { ok: true, list };
+}
+
+/** The shape of a proposal as an agent files it and the PM edits it. */
+function checkProposal(input) {
+  const x = isObj(input) ? input : {};
+  if (!oneLine(x.name, LIMITS.name)) return { ok: false, error: `name is one line of 1 to ${LIMITS.name} characters` };
+  if (!oneLine(x.purpose, LIMITS.purpose)) return { ok: false, error: `purpose is one line of 1 to ${LIMITS.purpose} characters` };
+  if (!oneLine(x.audience, LIMITS.audience)) return { ok: false, error: `audience is one line of 1 to ${LIMITS.audience} characters` };
+  const source = x.source == null || x.source === '' ? 'work' : x.source;
+  if (source !== 'work' && !DASH_RE.test(String(source))) return { ok: false, error: 'source is work, or dashboard:portfolio, dashboard:board:<id> or dashboard:initiative:<id>' };
+  if (!OUTPUTS.includes(x.output)) return { ok: false, error: `output is one of ${OUTPUTS.join(', ')}` };
+  const sch = checkSchedule(x.schedule);
+  if (!sch.ok) return sch;
+  const sources = listOf(x.sources, LIMITS.sources, 200, 'sources'); if (!sources.ok) return sources;
+  const sections = listOf(x.sections, LIMITS.sections, 60, 'sections'); if (!sections.ok) return sections;
+  const fixes = listOf(x.fixes, LIMITS.fixes, 200, 'fixes'); if (!fixes.ok) return fixes;
+  if (x.learned_from != null && x.learned_from !== '' && !oneLine(x.learned_from, LIMITS.text)) return { ok: false, error: `learned_from is one line of at most ${LIMITS.text} characters` };
+  const found = [];
+  if (x.found != null) {
+    if (!Array.isArray(x.found) || x.found.length > LIMITS.found) return { ok: false, error: `found is a list of at most ${LIMITS.found} items` };
+    for (const f of x.found) {
+      if (!isObj(f) || !oneLine(f.text, 240) || !EVIDENCE_KINDS.concat(['repo', 'note']).includes(f.kind) || (f.when != null && f.when !== '' && !oneLine(f.when, 60))) return { ok: false, error: 'each found item is { kind, text, when? }: kind mail, calendar, slack, drive, confluence, repo or note; text one line of up to 240 characters' };
+      found.push({ kind: f.kind, text: f.text.trim(), when: f.when ? f.when.trim() : null });
+    }
+  }
+  if (x.product != null && x.product !== '' && !oneLine(x.product, 80)) return { ok: false, error: 'product is one line of at most 80 characters' };
+  const clean = (s) => String(s).replace(/["\\]/g, "'").trim();
+  return { ok: true, proposal: {
+    name: x.name.trim(), purpose: x.purpose.trim(), audience: clean(x.audience), source, output: x.output, schedule: sch.schedule,
+    sources: sources.list, sections: sections.list.length ? sections.list : FRAME.slice(), learned_from: x.learned_from ? x.learned_from.trim() : null,
+    fixes: fixes.list, found, ...(x.product ? { product: clean(x.product) } : {}),
+  } };
+}
+
+function checkEvidence(list) {
+  if (!Array.isArray(list) || !list.length || list.length > LIMITS.evidence) return { ok: false, error: `evidence is a list of 1 to ${LIMITS.evidence} items` };
+  const out = [];
+  for (const e of list) {
+    if (!isObj(e) || !EVIDENCE_KINDS.includes(e.kind) || !oneLine(e.text, 240)) return { ok: false, error: `each evidence item is { kind, text }: kind ${EVIDENCE_KINDS.join(', ')}; text one line of up to 240 characters` };
+    out.push({ kind: e.kind, text: e.text.trim() });
+  }
+  return { ok: true, evidence: out };
+}
+
+// ── the fold ─────────────────────────────────────────────────────────────────────────────────────────
+const SETUP_FIELDS = ['name', 'purpose', 'audience', 'output', 'schedule', 'sources', 'sections', 'learned_from', 'fixes', 'product', 'def_sha'];
+
+function fold(lines) {
+  const st = { setups: new Map(), asks: new Map(), findings: new Map(), dismissed: { patterns: new Set(), names: new Set() },
+    finder: { cadence: 'weekly', sources: { ...FINDER_DEFAULTS } }, finds: [], migrated: null };
+  for (const l of lines || []) {
+    if (!isObj(l)) continue;
+    switch (l.ev) {
+      case 'setup': {
+        if (!ID_RE.test(String(l.id || '')) || st.setups.has(l.id)) break;
+        st.setups.set(l.id, { id: l.id, name: l.name, purpose: l.purpose, audience: l.audience, source: l.source || 'work', output: l.output, schedule: l.schedule,
+          sources: l.sources || [], sections: l.sections || FRAME.slice(), learned_from: l.learned_from || null, fixes: l.fixes || [], product: l.product || null,
+          ws: l.ws || null, status: 'active', created_at: l.at, last_run: l.last_run || l.at, def_sha: l.def_sha || null, from: l.from || null, migrated: !!l.migrated, drafted: [] });
+        if (l.from && l.from.ask) st.asks.delete(l.from.ask);
+        if (l.from && l.from.finding && st.findings.has(l.from.finding)) st.findings.get(l.from.finding).state = 'set-up';
+        break;
+      }
+      case 'change': {
+        const s = st.setups.get(l.id); if (!s) break;
+        for (const k of SETUP_FIELDS) if (Object.prototype.hasOwnProperty.call(l, k)) s[k] = l[k];
+        s.changed_at = l.at;
+        break;
+      }
+      case 'pause': { const s = st.setups.get(l.id); if (s) s.status = 'paused'; break; }
+      case 'resume': { const s = st.setups.get(l.id); if (s) { s.status = 'active'; if (l.last_run) s.last_run = l.last_run; } break; }
+      case 'remove': st.setups.delete(l.id); break;
+      case 'drafted': { const s = st.setups.get(l.id); if (s) { s.last_run = l.at; s.drafted.push({ slot: l.slot, at: l.at, path: l.path || null }); } break; }
+      case 'ask-start':
+        if (ASK_RE.test(String(l.ask || ''))) st.asks.set(l.ask, { id: l.ask, text: l.text, ws: l.ws || null, state: 'running', changed: false, proposal: null, error: null, started: l.at, changes: [] });
+        break;
+      case 'proposal': { const a = st.asks.get(l.ask); if (a && isObj(l.proposal)) { a.proposal = l.proposal; a.state = 'ready'; a.error = null; } break; }
+      case 'proposal-change': { const a = st.asks.get(l.ask); if (a) { a.state = 'running'; a.changed = true; a.changes.push(l.text); a.error = null; } break; }
+      case 'proposal-cancel': st.asks.delete(l.ask); break;
+      case 'ask-end': {
+        const a = st.asks.get(l.ask); if (!a) break;
+        if (l.ok && a.proposal) { a.state = 'ready'; break; }
+        a.state = a.proposal ? 'ready' : 'failed';
+        a.error = l.ok ? 'The run ended without a proposal. Ask again.' : (l.error || 'The run failed.');
+        break;
+      }
+      case 'find-start': st.finds.push({ run: l.run, start: l.at, end: null, ok: null, error: null, found: 0 }); break;
+      case 'find-end': { const f = st.finds.find((x) => x.run === l.run); if (f) { f.end = l.at; f.ok = !!l.ok; f.error = l.error || null; f.found = l.found || 0; } break; }
+      case 'finding':
+        if (FINDING_RE.test(String(l.id || '')) && !st.findings.has(l.id)) st.findings.set(l.id, { id: l.id, run: l.run || null, pattern: l.pattern, name: l.name, why: l.why, evidence: l.evidence || [], confidence: l.confidence, proposal: l.proposal, at: l.at, state: 'open' });
+        break;
+      case 'finding-dismiss': {
+        const f = l.id ? st.findings.get(l.id) : null;
+        if (f) f.state = 'dismissed';
+        const pat = l.pattern || (f && f.pattern);
+        if (pat) st.dismissed.patterns.add(pat);
+        const nm = f && f.name ? slugOf(f.name) : (l.name ? slugOf(l.name) : null);
+        if (nm) st.dismissed.names.add(nm);
+        break;
+      }
+      case 'finder':
+        if (FINDER_CADENCES.includes(l.cadence)) st.finder.cadence = l.cadence;
+        if (isObj(l.sources)) for (const k of FINDER_SOURCES) if (typeof l.sources[k] === 'boolean') st.finder.sources[k] = l.sources[k];
+        break;
+      case 'migrated': st.migrated = { at: l.at, keys: Array.isArray(l.keys) ? l.keys : [], count: l.count || 0 }; break;
+      default: break;
+    }
+  }
+  return st;
+}
+
+const stateOf = (root) => fold(readLines(ledgerFile(root)));
+const openFindings = (st) => [...st.findings.values()].filter((f) => f.state === 'open' && !isDismissed(st, f.pattern, f.name));
+function isDismissed(st, pattern, name) { return st.dismissed.patterns.has(pattern) || (name != null && st.dismissed.names.has(slugOf(name))); }
+
+// ── schedules: the label, the form schedule-logic reads, and the bi-weekly parity ─────────────────────────────
+const plural = { Mon: 'Mondays', Tue: 'Tuesdays', Wed: 'Wednesdays', Thu: 'Thursdays', Fri: 'Fridays', Sat: 'Saturdays', Sun: 'Sundays' };
+function scheduleLabel(s) {
+  if (!isObj(s)) return '';
+  const t = s.time || '09:00';
+  if (s.cadence === 'daily') return `Daily at ${t}`;
+  if (s.cadence === 'weekly') return `Weekly, ${plural[s.day] || 'Mondays'} ${t}`;
+  if (s.cadence === 'bi-weekly') return `Every other ${(plural[s.day] || 'Mondays').replace(/s$/, '')} at ${t}`;
+  if (s.cadence === 'monthly') return `Monthly, day ${s.dayOfMonth || 1} at ${t}`;
+  return s.cadence || '';
+}
+/** A setup's schedule in the form lib/schedule-logic.js reads. */
+const scheduleOf = (setup, lastRun) => ({ cadence: setup.schedule.cadence, day: setup.schedule.day, dayOfMonth: setup.schedule.dayOfMonth, time: setup.schedule.time, enabled: setup.status === 'active', lastRun: lastRun == null ? setup.last_run || null : lastRun });
+const addDays = (d, n) => { const x = new Date(d); x.setDate(x.getDate() + n); return x; };
+const localMidnight = (d) => { const x = new Date(d); x.setHours(0, 0, 0, 0); return x; };
+function atTime(d, time) { const m = /^(\d{1,2}):(\d{2})$/.exec(String(time || '09:00')) || [0, 9, 0]; const x = new Date(d); x.setHours(+m[1], +m[2], 0, 0); return x; }
+
+/**
+ * The first draft slot of a bi-weekly schedule with an anchor: the draft day on or just before the first session on or after today.
+ * Sessions are the anchor and every 14th day after it. Anything else has no fixed first slot: null.
+ */
+function firstSlot(schedule, now = new Date()) {
+  if (!schedule || schedule.cadence !== 'bi-weekly' || !schedule.anchor || !DATE_RE.test(schedule.anchor)) return null;
+  const [y, m, d] = schedule.anchor.split('-').map(Number);
+  let session = new Date(y, m - 1, d);
+  const today = localMidnight(now);
+  let guard = 0;
+  while (session < today && guard++ < 400) session = addDays(session, 14);
+  const want = Math.max(0, DAYS.indexOf(schedule.day)) + 1;       // Mon=1 … Sun=7 → JS getDay() 1…6, 0
+  const idx = want % 7;
+  let slot = atTime(session, schedule.time);
+  for (let i = 0; i < 7 && slot.getDay() !== idx; i++) slot = addDays(slot, -1);
+  return slot;
+}
+/** The lastRun to store so that the first draft is exact. With an anchor, 14 days before the first slot; otherwise now. */
+function initialLastRun(schedule, now = new Date()) {
+  const slot = firstSlot(schedule, now);
+  return slot ? addDays(slot, -14).toISOString() : new Date(now).toISOString();
+}
+/** The next moment this schedule drafts, as a Date, or null. A slot already due (not drafted yet) answers that slot. */
+function nextDraftAt(schedule, lastRun, now = new Date()) {
+  const base = { cadence: schedule.cadence, day: schedule.day, dayOfMonth: schedule.dayOfMonth, time: schedule.time, enabled: true, lastRun: lastRun || null };
+  if (logic.isDue(base, now)) return logic.lastSlot(base, now);
+  let cursor = new Date(now);
+  for (let i = 0; i < 80; i++) {
+    const s = logic.nextSlot(base, cursor);
+    if (!s) return null;
+    if (logic.isDue(base, new Date(s.getTime() + 60000))) return s;
+    cursor = s;
+  }
+  return null;
+}
+
+// ── the definition ───────────────────────────────────────────────────────────────────────────────────
+const SECTION_NOTES = Object.freeze({
+  headline: 'Headline. One or two sentences: the one thing the readers must know this cycle.',
+  timeline: 'Timeline. The dated items, written in full (14 October 2026, never "next week").',
+  initiatives: 'Initiatives. One block for each initiative. Each note covers Done, In progress, Next and the key open item.',
+  new: 'New since last report. What is new in the window, each with its date. The PM writes the release notes in `report.changelog`.',
+  decided: 'Decided this cycle. The decisions, marked Decided or Acknowledged.',
+  needs: 'Needs your call. Asks to the readers in `report.asks`: what, who, by when. Write "None this cycle" when there are none; never drop the section.',
+  sources: 'Sources reached and not reached.',
+});
+const OUTPUT_WORDS = Object.freeze({ 'google-slides': 'a Google Slides deck', 'google-doc': 'a Google Doc', 'google-sheets': 'a Google Sheets spreadsheet', confluence: 'a Confluence page', pdf: 'a PDF' });
+
+function scheduleSentence(s, now) {
+  const first = firstSlot(s, now);
+  const base = scheduleLabel(s) + '.';
+  if (s.cadence === 'bi-weekly' && s.anchor && first) return `${base} The first draft is ${WEEKDAYS[first.getDay()]} ${longDate(first)}, for the session on ${longDate(new Date(s.anchor + 'T00:00:00'))}.`;
+  return base;
+}
+
+function definitionText(setup, { product, now = new Date() } = {}) {
+  const q = (v) => `"${String(v == null ? '' : v).replace(/["\\]/g, "'")}"`;
+  const prod = setup.product || product || null;
+  const date = localDay(new Date(now));
+  const list = (a, none) => (a && a.length ? a.map((x) => `- ${x}`).join('\n') : none);
+  const dash = setup.source !== 'work';
+  return [
+    '---', 'type: Reference', `title: ${q(setup.name + ' definition')}`,
+    `description: ${q(`The ${setup.name} report. pmos report draft reads the frontmatter; the report-template skill reads the prose.`)}`,
+    `timestamp: ${date}`, `cadence: ${setup.id}`, `audience: ${q(setup.audience)}`, ...(prod ? [`product: ${q(prod)}`] : []),
+    `sections: [${FRAME.join(', ')}]`, 'status: draft', `output: ${setup.output}`, `source: ${setup.source}`, '---', '',
+    `# ${setup.name} definition`, '',
+    `This file defines the ${setup.name} report. PMOS drafts it on a schedule; the PM issues it. Nothing is sent. Only the PM changes \`status\` to \`stable\`.`, '',
+    '## Purpose', '', setup.purpose, '',
+    '## Audience', '', `${setup.audience}. Needs your call holds asks to them only, each with who and by when.`, '',
+    '## Output', '', `The finished report is ${OUTPUT_WORDS[setup.output] || setup.output}. PMOS keeps the report as a document in this repository; a copy is made only when the PM presses Create the copy.`, '',
+    '## Schedule', '', scheduleSentence(setup.schedule, now), '',
+    '## Sources', '', list(setup.sources, dash ? `- The dashboard ${setup.source.slice('dashboard:'.length)}, as its report frame reads it.` : '- The local ledgers that `pmos report draft` reads.'), '',
+    '## Sections', '', 'The script writes the frame and every number. The agent writes only the notes.', '',
+    ...FRAME.map((id, i) => `${i + 1}. ${SECTION_NOTES[id]}`), '',
+    '## Learned from earlier copies', '', setup.learned_from || 'None yet. Add what the earlier copies show after the first cycle.', '',
+    '## Fixes this report applies', '', list(setup.fixes, '- None yet.'), '',
+    '## Length and tone', '', 'One or two sentences for each block note. Plain words, short sentences. No numbers in notes: the script writes them.', '',
+  ].join('\n');
+}
+const shaOf = (text) => crypto.createHash('sha256').update(String(text)).digest('hex').slice(0, 16);
+
+function definitionFile(root, id) { return path.join(path.resolve(String(root)), reportDraft.definitionPath(root, id)); }
+
+/** Write the definition. `keep: true` (a change) leaves a file the PM edited since the last write alone. → { ok, path, sha, kept? } */
+function writeDefinition(root, setup, { now, keep, expectSha } = {}) {
+  const file = definitionFile(root, setup.id);
+  const text = definitionText(setup, { product: path.basename(path.resolve(String(root))), now: now == null ? new Date() : new Date(now) });
+  let cur = null;
+  try { cur = fs.readFileSync(file, 'utf8'); } catch { cur = null; }
+  if (cur != null && keep && expectSha && shaOf(cur) !== expectSha) return { ok: true, path: reportDraft.definitionPath(root, setup.id), sha: expectSha, kept: true };
+  if (cur != null && !keep) return refuse(409, `${reportDraft.definitionPath(root, setup.id)} exists already. Nothing was written`);
+  const tmp = `${file}.tmp-${crypto.randomBytes(6).toString('hex')}`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(tmp, text, { flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* not made */ }
+    return refuse(500, 'could not write the definition; nothing was written: ' + String((e && e.message) || e).slice(0, 160));
+  }
+  return { ok: true, path: reportDraft.definitionPath(root, setup.id), sha: shaOf(text) };
+}
+
+/** Every definition in the repository: { id, path, audience, product, sections, errors, status, output, source, title }. Read-only. */
+function definitionsOf(root) {
+  const abs = path.resolve(String(root));
+  const dir = path.join(abs, reportDraft.stateRel(abs), 'reports', 'definitions');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((f) => /\.md$/.test(f)).sort(); } catch { names = []; }
+  const out = [];
+  for (const f of names) {
+    const id = f.slice(0, -3);
+    if (!ID_RE.test(id)) continue;
+    const d = reportDraft.readDefinition(abs, id);
+    let fm = {};
+    try {
+      const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(fs.readFileSync(path.join(dir, f), 'utf8'));
+      for (const line of (m ? m[1] : '').split(/\r?\n/)) { const kv = /^([A-Za-z_][\w-]*):\s*(.*?)\s*$/.exec(line); if (kv) fm[kv[1]] = kv[2].replace(/^["']|["']$/g, ''); }
+    } catch { fm = {}; }
+    out.push({ id, path: d.path, audience: d.audience, product: d.product, sections: d.sections, errors: d.errors, status: fm.status || null, output: fm.output || null, source: fm.source || null, title: fm.title || id });
+  }
+  return out;
+}
+
+// ── the draft-only schedule ──────────────────────────────────────────────────────────────────────────
+/** The schedule store the server keeps (server.js readSchedules / writeSchedules), or a file-backed one for a test. */
+function fileScheduleStore(file) {
+  return {
+    read() { try { const a = JSON.parse(fs.readFileSync(file, 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; } },
+    write(list) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, JSON.stringify(list)); },
+  };
+}
+/** The registered schedule of a setup (skill report-template, args = the id), or null. */
+function scheduleFor(store, setup, wsId) {
+  if (!store || typeof store.read !== 'function') return null;
+  return store.read().find((s) => s && s.skill === 'report-template' && s.args === setup.id && (!wsId || s.ws === wsId)) || null;
+}
+/**
+ * Register the draft-only schedule of a work-sourced setup: the report-template skill with the setup's id as its args. It only drafts a file.
+ * A dashboard-sourced setup has no entry here: the tick in lib/routes-report-setups.js drafts it from its own line.
+ */
+function registerSchedule(store, setup, { wsId, lastRun, now = new Date() } = {}) {
+  if (!store || typeof store.write !== 'function') return { ok: false, error: 'there is no schedule store' };
+  const norm = logic.normalizeSchedule({ name: `${setup.name} (draft)`, cadence: setup.schedule.cadence, day: setup.schedule.day, dayOfMonth: setup.schedule.dayOfMonth,
+    time: setup.schedule.time, skill: 'report-template', args: setup.id });
+  if (!norm.ok) return { ok: false, error: norm.error };
+  const list = store.read();
+  const have = list.find((s) => s && s.skill === 'report-template' && s.args === setup.id && (!wsId || s.ws === wsId));
+  if (have) return { ok: true, schedule: have, existed: true };
+  const sched = { id: 'sc-' + Date.now().toString(36) + crypto.randomBytes(2).toString('hex'), ws: wsId || null, ...norm.schedule, profile: null,
+    lastRun: lastRun || now.toISOString(), lastStatus: null, setup: setup.id };
+  sched.nextRun = nextDraftAt(sched, sched.lastRun, now) ? nextDraftAt(sched, sched.lastRun, now).toISOString() : null;
+  list.unshift(sched);
+  store.write(list);
+  return { ok: true, schedule: sched };
+}
+function updateSchedule(store, setup, wsId, patch) {
+  if (!store) return null;
+  const list = store.read();
+  const s = list.find((x) => x && x.skill === 'report-template' && x.args === setup.id && (!wsId || x.ws === wsId));
+  if (!s) return null;
+  Object.assign(s, patch);
+  store.write(list);
+  return s;
+}
+function unregisterSchedule(store, setup, wsId) {
+  if (!store) return false;
+  const list = store.read();
+  const keep = list.filter((x) => !(x && x.skill === 'report-template' && x.args === setup.id && (!wsId || x.ws === wsId)));
+  if (keep.length === list.length) return false;
+  store.write(keep);
+  return true;
+}
+
+// ── the presses ──────────────────────────────────────────────────────────────────────────────────────
+function freeId(root, st, name) {
+  const base = slugOf(name);
+  const taken = (id) => st.setups.has(id) || fs.existsSync(definitionFile(root, id)) || fs.existsSync(path.join(stateDir(root), 'reports', id));
+  if (!taken(base)) return base;
+  for (let n = 2; n < 100; n++) { const id = `${base.slice(0, 36)}-${n}`; if (!taken(id)) return id; }
+  return `${base.slice(0, 30)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+/**
+ * Set up a recurring report. `input` is a proposal (checkProposal) plus `from: { ask } | { finding }`. Writes the definition, registers the
+ * draft-only schedule (work source), appends the `setup` line. → { ok, setup, first_draft: { slot, at } | null } | { ok: false, status, error }
+ * opts: { by, now, wsId, scheduleStore, lastRun (the old schedule's, for a migration), id }
+ */
+function setUp(root, input, opts = {}) {
+  const c = checkProposal(input);
+  if (!c.ok) return refuse(400, c.error);
+  const p = c.proposal;
+  const now = opts.now == null ? new Date() : new Date(opts.now);
+  const file = ledgerFile(root);
+  const st = fold(readLines(file));
+  const id = opts.id || freeId(root, st, p.name);
+  if (!ID_RE.test(id)) return refuse(400, 'the id is lower-case letters, digits and "-"');
+  if (st.setups.has(id)) return refuse(409, `${id} is set up already`);
+  const from = isObj(input.from) ? (input.from.ask ? { ask: String(input.from.ask) } : input.from.finding ? { finding: String(input.from.finding) } : null) : null;
+  const setup = { id, ...p, status: 'active', product: p.product || path.basename(path.resolve(String(root))) };
+  const lastRun = opts.lastRun || initialLastRun(p.schedule, now);
+  const def = writeDefinition(root, setup, { now });
+  if (!def.ok) return def;
+  if (p.source === 'work') {
+    const reg = registerSchedule(opts.scheduleStore, setup, { wsId: opts.wsId, lastRun, now });
+    if (!reg.ok) return refuse(500, reg.error);
+  }
+  append(file, { ev: 'setup', id, name: p.name, purpose: p.purpose, audience: p.audience, source: p.source, output: p.output, schedule: p.schedule, sources: p.sources,
+    sections: p.sections, learned_from: p.learned_from, fixes: p.fixes, product: setup.product, ws: opts.wsId || null, last_run: lastRun, def_sha: def.sha,
+    ...(from ? { from } : {}), ...(opts.migrated ? { migrated: true } : {}) }, { now, by: opts.by });
+  const next = nextDraftAt(p.schedule, lastRun, now);
+  const folded = fold(readLines(file)).setups.get(id);
+  return { ok: true, setup: folded, definition: def.path, first_draft: next ? { slot: localDay(next), at: next.toISOString(), day: next.getDay() } : null };
+}
+
+/** The PM edits a recurring report. `patch` is any of name, purpose, audience, output, schedule, sources, sections, learned_from, fixes. */
+function change(root, id, patch, opts = {}) {
+  const file = ledgerFile(root);
+  const st = fold(readLines(file));
+  const cur = st.setups.get(id);
+  if (!cur) return refuse(404, `no recurring report ${String(id).slice(0, 40)}`);
+  const merged = checkProposal({ ...cur, ...(isObj(patch) ? patch : {}) });
+  if (!merged.ok) return refuse(400, merged.error);
+  const now = opts.now == null ? new Date() : new Date(opts.now);
+  const fields = {};
+  for (const k of ['name', 'purpose', 'audience', 'output', 'schedule', 'sources', 'sections', 'learned_from', 'fixes']) {
+    if (Object.prototype.hasOwnProperty.call(patch || {}, k) && JSON.stringify(merged.proposal[k]) !== JSON.stringify(cur[k])) fields[k] = merged.proposal[k];
+  }
+  if (!Object.keys(fields).length) return { ok: true, setup: cur, unchanged: true };
+  const next = { ...cur, ...fields };
+  const def = writeDefinition(root, next, { now, keep: true, expectSha: cur.def_sha });
+  if (!def.ok) return def;
+  if (fields.schedule && cur.source === 'work') {
+    const norm = logic.normalizeSchedule({ name: `${next.name} (draft)`, cadence: next.schedule.cadence, day: next.schedule.day, dayOfMonth: next.schedule.dayOfMonth, time: next.schedule.time, skill: 'report-template', args: id });
+    if (norm.ok) updateSchedule(opts.scheduleStore, next, opts.wsId, { cadence: norm.schedule.cadence, day: norm.schedule.day, dayOfMonth: norm.schedule.dayOfMonth, time: norm.schedule.time,
+      lastRun: initialLastRun(next.schedule, now), name: norm.schedule.name });
+  } else if (fields.name && cur.source === 'work') updateSchedule(opts.scheduleStore, next, opts.wsId, { name: `${next.name} (draft)` });
+  const lastRun = fields.schedule ? initialLastRun(next.schedule, now) : undefined;
+  append(file, { ev: 'change', id, ...fields, ...(lastRun ? { last_run: lastRun } : {}), def_sha: def.sha }, { now, by: opts.by });
+  return { ok: true, setup: fold(readLines(file)).setups.get(id), definition_kept: !!def.kept };
+}
+
+function setStatus(root, id, ev, opts = {}) {
+  const file = ledgerFile(root);
+  const cur = fold(readLines(file)).setups.get(id);
+  if (!cur) return refuse(404, `no recurring report ${String(id).slice(0, 40)}`);
+  if (ev === 'pause' && cur.status === 'paused') return { ok: true, setup: cur, unchanged: true };
+  if (ev === 'resume' && cur.status === 'active') return { ok: true, setup: cur, unchanged: true };
+  const now = opts.now == null ? new Date() : new Date(opts.now);
+  let lastRun;
+  if (ev === 'resume') lastRun = cur.schedule.cadence === 'bi-weekly' ? initialLastRun(cur.schedule, now) : now.toISOString();
+  if (cur.source === 'work') updateSchedule(opts.scheduleStore, cur, opts.wsId, ev === 'pause' ? { enabled: false } : { enabled: true, lastRun });
+  append(file, { ev, id, ...(lastRun ? { last_run: lastRun } : {}) }, { now, by: opts.by });
+  return { ok: true, setup: fold(readLines(file)).setups.get(id) };
+}
+const pause = (root, id, opts) => setStatus(root, id, 'pause', opts);
+const resume = (root, id, opts) => setStatus(root, id, 'resume', opts);
+function remove(root, id, opts = {}) {
+  const file = ledgerFile(root);
+  const cur = fold(readLines(file)).setups.get(id);
+  if (!cur) return refuse(404, `no recurring report ${String(id).slice(0, 40)}`);
+  if (cur.source === 'work') unregisterSchedule(opts.scheduleStore, cur, opts.wsId);
+  append(file, { ev: 'remove', id }, { now: opts.now, by: opts.by });
+  return { ok: true };
+}
+
+// ── the Ask box ──────────────────────────────────────────────────────────────────────────────────────
+function askStart(file, { text, ws, by, now }) {
+  if (!oneLine(String(text || '').replace(/\s+/g, ' '), LIMITS.text)) return refuse(400, `say what report you want, in up to ${LIMITS.text} characters`);
+  const st = fold(readLines(file));
+  if (st.asks.size >= LIMITS.asks) return refuse(409, 'there are too many open requests. Cancel one first');
+  const ask = newId('ask');
+  append(file, { ev: 'ask-start', ask, text: String(text).replace(/\s+/g, ' ').trim(), ws: ws || null }, { now, by });
+  return { ok: true, id: ask };
+}
+function askChange(file, { id, text, by, now }) {
+  if (!oneLine(String(text || '').replace(/\s+/g, ' '), LIMITS.text)) return refuse(400, `say what to change, in up to ${LIMITS.text} characters`);
+  const a = fold(readLines(file)).asks.get(id);
+  if (!a) return refuse(404, 'no such request');
+  if (a.state === 'running') return refuse(409, 'PMOS is still working on this request');
+  append(file, { ev: 'proposal-change', ask: id, text: String(text).replace(/\s+/g, ' ').trim() }, { now, by });
+  return { ok: true, ask: a };
+}
+function askCancel(file, { id, by, now }) {
+  if (!fold(readLines(file)).asks.has(id)) return refuse(404, 'no such request');
+  append(file, { ev: 'proposal-cancel', ask: id }, { now, by });
+  return { ok: true };
+}
+function askEnd(file, { id, ok, error, now }) {
+  const a = fold(readLines(file)).asks.get(id);
+  if (!a) return { ok: true, gone: true };
+  append(file, { ev: 'ask-end', ask: id, ok: !!ok, ...(error ? { error: String(error).slice(0, 300) } : {}) }, { now });
+  return { ok: true };
+}
+/** The report-setup run files ONE proposal for its ask. A second one revises it. */
+function fileProposal(file, { ask, proposal, by, now }) {
+  const st = fold(readLines(file));
+  const a = st.asks.get(ask);
+  if (!a) return refuse(404, 'that request is not open');
+  if (a.state !== 'running') return refuse(409, 'that request has its proposal already');
+  const c = checkProposal(proposal);
+  if (!c.ok) return refuse(400, c.error);
+  append(file, { ev: 'proposal', ask, proposal: c.proposal }, { now, by });
+  return { ok: true, result: 'filed' };
+}
+
+// ── the finder ───────────────────────────────────────────────────────────────────────────────────────
+function findStart(file, { now } = {}) { const run = newId('frun'); append(file, { ev: 'find-start', run }, { now }); return run; }
+function findEnd(file, { run, ok, error, now }) {
+  const st = fold(readLines(file));
+  const found = openFindings(st).filter((f) => f.run === run).length;
+  append(file, { ev: 'find-end', run, ok: !!ok, found, ...(error ? { error: String(error).slice(0, 300) } : {}) }, { now });
+  return found;
+}
+/** A found report. Refuses a dismissed pattern (`dismissed`), a repeat (`duplicate`) and a report already set up (`duplicate`). */
+function fileFinding(file, input, { run, by, now } = {}) {
+  const x = isObj(input) ? input : {};
+  if (!oneLine(x.name, LIMITS.name)) return refuse(400, `name is one line of 1 to ${LIMITS.name} characters`);
+  if (!oneLine(x.why, 300)) return refuse(400, 'why is one line of 1 to 300 characters');
+  if (!CONFIDENCE.includes(x.confidence)) return refuse(400, `confidence is ${CONFIDENCE.join(' or ')}`);
+  const ev = checkEvidence(x.evidence); if (!ev.ok) return refuse(400, ev.error);
+  const pr = checkProposal(x.proposal); if (!pr.ok) return refuse(400, pr.error);
+  const st = fold(readLines(file));
+  const pattern = patternOf(x.name, x.pattern);
+  if (isDismissed(st, pattern, x.name)) return { ok: false, status: 409, error: 'dismissed', result: 'dismissed' };
+  const slug = slugOf(x.name);
+  const dup = [...st.findings.values()].some((f) => f.state === 'open' && (f.pattern === pattern || slugOf(f.name) === slug))
+    || [...st.setups.values()].some((s) => slugOf(s.name) === slug || s.id === slug);
+  if (dup) return { ok: false, status: 409, error: 'duplicate', result: 'duplicate' };
+  const mine = [...st.findings.values()].filter((f) => f.run && f.run === run).length;
+  if (run && mine >= LIMITS.findings) return refuse(409, `this run filed ${LIMITS.findings} findings already; file no more`);
+  const id = newId('rf');
+  append(file, { ev: 'finding', id, run: run || null, pattern, name: x.name.trim(), why: x.why.trim(), evidence: ev.evidence, confidence: x.confidence, proposal: pr.proposal }, { now, by });
+  return { ok: true, result: 'filed', id };
+}
+function dismissFinding(file, { id, by, now }) {
+  const f = fold(readLines(file)).findings.get(id);
+  if (!f) return refuse(404, 'no such finding');
+  append(file, { ev: 'finding-dismiss', id, pattern: f.pattern }, { now, by });
+  return { ok: true };
+}
+function setFinder(file, { cadence, sources, by, now }) {
+  const line = {};
+  if (cadence !== undefined) { if (!FINDER_CADENCES.includes(cadence)) return refuse(400, `cadence is ${FINDER_CADENCES.join(' or ')}`); line.cadence = cadence; }
+  if (sources !== undefined) {
+    if (!isObj(sources)) return refuse(400, 'sources is { calendar, slack, mail, drive }: true or false');
+    line.sources = {};
+    for (const [k, v] of Object.entries(sources)) {
+      if (!FINDER_SOURCES.includes(k) || typeof v !== 'boolean') return refuse(400, `sources hold ${FINDER_SOURCES.join(', ')}, each true or false`);
+      line.sources[k] = v;
+    }
+  }
+  if (!Object.keys(line).length) return refuse(400, 'say a cadence or sources');
+  append(file, { ev: 'finder', ...line }, { now, by });
+  return { ok: true, finder: fold(readLines(file)).finder };
+}
+
+// ── the documents ────────────────────────────────────────────────────────────────────────────────────
+/** `<state>/reports/<id>/<slot>.md` for a dashboard-sourced setup: the dashboard's report frame as a document. Refuses an existing or issued slot. */
+function writeDocument(root, setup, slot, markdown, { now, record = true } = {}) {
+  if (!DATE_RE.test(String(slot))) return refuse(400, 'the slot is a date');
+  const abs = path.resolve(String(root));
+  const rel = reportDraft.draftPath(abs, setup.id, slot);
+  const file = path.join(abs, rel);
+  const issues = require('./issues.js');
+  if (issues.isIssued(issues.readIssues(abs), setup.id, slot)) return refuse(409, `${setup.id} ${slot} is issued and frozen. Nothing was written`);
+  if (fs.existsSync(file)) return refuse(409, `${rel} exists already. Nothing was written`);
+  const tmp = `${file}.tmp-${crypto.randomBytes(6).toString('hex')}`;
+  try { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(tmp, markdown, { flag: 'wx' }); fs.renameSync(tmp, file); }
+  catch (e) { try { fs.unlinkSync(tmp); } catch { /* not made */ } return refuse(500, 'could not write the document: ' + String((e && e.message) || e).slice(0, 160)); }
+  if (record) append(ledgerFile(abs), { ev: 'drafted', id: setup.id, slot, path: rel }, { now });
+  return { ok: true, path: rel };
+}
+
+/** The markdown of a dashboard-sourced document: a frame (lib/report-frame.js frameOf) as headings and bullets. */
+function frameMarkdown(setup, F, slot, now) {
+  const q = (v) => `"${String(v == null ? '' : v).replace(/["\\]/g, "'")}"`;
+  const out = ['---', 'type: Reference', `title: ${q(`${setup.name} ${slot}`)}`, `description: ${q(`The ${setup.name} report for ${slot}, drafted from a dashboard. Nothing was sent.`)}`,
+    `timestamp: ${localDay(new Date(now))}`, `cadence: ${setup.id}`, `slot: ${slot}`, 'status: draft', `output: ${setup.output}`, `source: ${setup.source}`, 'made_by: schedule', '---', '',
+    `# ${F.title} for ${F.audience}, ${F.today}`, '', '## Headline', '', F.headline, '', '## Sections', ''];
+  for (const s of F.sections) { out.push(`### ${s.title}`, '', `- ${s.line} [reported]`); for (const n of s.nums) out.push(`- ${n} [reported]`); out.push(''); }
+  out.push('## Needs your call', '');
+  if (F.needs.length) for (const n of F.needs) out.push(`- ${n} [reported]`); else out.push('Nothing needs your call in this scope.');
+  out.push('', '## Sources', '', `${F.sources.length ? F.sources.join('; ') : 'none'}. Read on ${F.today}.`, '');
+  return out.join('\n');
+}
+
+// ── the migration ────────────────────────────────────────────────────────────────────────────────────
+const DASH_PLAN = Object.freeze({ weekly: { cadence: 'weekly', day: 'Mon', time: '08:00' }, monthly: { cadence: 'monthly', dayOfMonth: 1, time: '08:00' } });
+const dashTitle = (key) => (key === 'portfolio' ? 'Portfolio' : `${key.startsWith('board:') ? 'Board' : 'Initiative'}: ${key.slice(key.indexOf(':') + 1)}`);
+const keyOfSource = (source) => String(source || '').replace(/^dashboard:/, '');
+
+/**
+ * Move the dashboard schedules (<runtimeDir>/report-dashboards/schedules.json) into recurring reports, once. The old file is read and never
+ * written again: it stays as the migration record. A `migrated` line is the marker; a second call changes nothing.
+ * opts: { runtimeDir, wsId, isHome, titleOf(key), outbox (the folded outbox entries), now, by }
+ */
+function migrate(root, opts = {}) {
+  const file = ledgerFile(root);
+  const st = fold(readLines(file));
+  if (st.migrated) return { ok: true, already: true, count: 0, keys: st.migrated.keys };
+  const rs = require('./report-schedules.js');
+  const mine = Object.values(rs.readSchedules(opts.runtimeDir || '')).filter((s) => (s.ws ? s.ws === opts.wsId : !!opts.isHome));
+  const keys = [];
+  const now = opts.now == null ? new Date() : new Date(opts.now);
+  for (const s of mine) {
+    const plan = DASH_PLAN[s.plan];
+    if (!plan) continue;
+    const key = s.key;
+    const source = `dashboard:${key}`;
+    if ([...st.setups.values()].some((x) => x.source === source)) { keys.push(key); continue; }
+    const title = (typeof opts.titleOf === 'function' && opts.titleOf(key)) || dashTitle(key);
+    const r = setUp(root, { name: title, purpose: `The ${title} dashboard as a report for ${s.audience}.`, audience: s.audience, source, output: 'pdf', schedule: plan,
+      sources: [`The ${title} dashboard`], sections: FRAME.slice(), learned_from: 'Moved from the dashboard schedule.', fixes: [] },
+    { now, by: opts.by, wsId: opts.wsId, lastRun: s.lastRun || now.toISOString(), id: freeId(root, fold(readLines(file)), 'dashboard-' + key.replace(/[:]/g, '-')), migrated: true });
+    if (r.ok) keys.push(key);
+  }
+  // Its drafts in the outbox become draft documents, so none is lost when the Drafts tab goes.
+  for (const e of opts.outbox || []) {
+    if (!e || e.made_by !== 'schedule' || !e.schedule_key || e.state === 'sent' || !keys.includes(e.schedule_key)) continue;
+    const setup = [...fold(readLines(file)).setups.values()].find((x) => x.source === `dashboard:${e.schedule_key}`);
+    if (!setup) continue;
+    const slot = localDay(new Date(Date.parse(e.created_at || e.at || now)));
+    const md = ['---', 'type: Reference', `title: "${String(e.subject || setup.name).replace(/["\\]/g, "'")}"`, `timestamp: ${localDay(now)}`, `cadence: ${setup.id}`, `slot: ${slot}`, 'status: draft',
+      `output: ${setup.output}`, `source: ${setup.source}`, 'made_by: schedule', '---', '', `# ${e.subject || setup.name}`, '', String(e.body || ''), ''].join('\n');
+    writeDocument(root, setup, slot, md, { now, record: false });
+  }
+  append(file, { ev: 'migrated', keys, count: keys.length }, { now, by: opts.by });
+  return { ok: true, already: false, count: keys.length, keys };
+}
+const migratedKeys = (root) => { const m = stateOf(root).migrated; return new Set(m ? m.keys : []); };
+/** The dashboard keys the old schedule tick must leave alone: the migrated ones, and every key a dashboard-sourced setup holds now. */
+function dashboardKeys(root) {
+  const st = stateOf(root);
+  const keys = new Set(st.migrated ? st.migrated.keys : []);
+  for (const s of st.setups.values()) if (String(s.source).startsWith('dashboard:')) keys.add(keyOfSource(s.source));
+  return keys;
+}
+
+module.exports = {
+  LEDGER, EVENTS, OUTPUTS, CADENCES, DAYS, FINDER_CADENCES, FINDER_SOURCES, FINDER_DEFAULTS, EVIDENCE_KINDS, CONFIDENCE, LIMITS, ID_RE, ASK_RE, FINDING_RE, RUN_RE, FRAME,
+  ledgerFile, stateDir, append, readLines, fold, stateOf, openFindings, isDismissed, slugOf, patternOf, checkProposal, checkEvidence, checkSchedule,
+  scheduleLabel, scheduleOf, firstSlot, initialLastRun, nextDraftAt, definitionText, writeDefinition, definitionsOf, definitionFile, shaOf,
+  fileScheduleStore, scheduleFor, registerSchedule, updateSchedule, unregisterSchedule,
+  setUp, change, pause, resume, remove, askStart, askChange, askCancel, askEnd, fileProposal, findStart, findEnd, fileFinding, dismissFinding, setFinder,
+  writeDocument, frameMarkdown, migrate, migratedKeys, dashboardKeys, dashTitle, keyOfSource, longDate, localDay,
+};