create-pmos 0.123.0 → 0.125.0

package/workspace/lib/routes-pm-items.js

@@ -0,0 +1,216 @@
+'use strict';
+/* routes-pm-items.js — the PM's own work items and jobs to be done (planning-flows run 1 and 2, UI slice).
+ *
+ *   GET  /api/pm-items                     → { ok, today, lists: { waiting, today, week, triage, later }, jobs, items }
+ *   POST /api/pm-items/add    { line }     → { ok, item }            one line: the parser (lib/pm-items.js) reads the parts
+ *   POST /api/pm-items/edit   { id, fields }→ { ok, item }            fields: title, due, priority, waiting_on, job
+ *   POST /api/pm-items/remove { id }       → { ok, undo_ms }         deleted (created here) or dropped (imported)
+ *   POST /api/pm-items/undo   { id }       → { ok, item } | 409      restores the last removal inside the 8 s window
+ *   POST /api/pm-items/done   { id }       → { ok }                  folds to item.done + done_at;  /reopen undoes it
+ *   POST /api/pm-items/park   { id }       → { ok }                  parked: true, placed in Later;  /unpark clears it
+ *   POST /api/pm-items/move   { id, list } → { ok }                  list_override, one of the five lists
+ *   POST /api/pm-items/steps/add  { id, text, who? } → { ok, step }  outward steps are forced to agent-drafts
+ *   POST /api/pm-items/steps/who  { step_id, who }   → { ok, who }
+ *   POST /api/pm-items/steps/plan { id }             → { ok, step }  one PM-only review step for now
+ *   POST /api/pm-jobs/add     { line }     → { ok, job }             one line: "when …, I want …, so …" (lib/jobs-to-be-done.js)
+ *   POST /api/pm-jobs/edit    { id, fields }→ { ok, job }            fields: when, want, so
+ *   POST /api/pm-jobs/delete  { id, reassign_to? } → { ok, reassigned }   items move to reassign_to, or to none
+ *
+ * STATE. Two append-only files under <runtime>/pm-items/: items.jsonl and jobs.jsonl. Every write is one appended line
+ * through pm-items.appendEvent, the single writer, and the GET folds the whole file again. Nothing is read from Jira.
+ *
+ * WHO WRITES. Every POST passes pm-guard requirePagePress: the page only, with the Origin and nonce checks. An agent
+ * session cannot add, edit or remove the PM's items; that is the boundary the PRD sets for run 1.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const guard = require('./pm-guard.js');
+const pmItems = require('./pm-items.js');
+const jobs = require('./jobs-to-be-done.js');
+const steps = require('./item-steps.js');
+
+const FIELDS = ['title', 'due', 'priority', 'waiting_on', 'job'];
+const JOB_FIELDS = ['when', 'want', 'so'];
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+const dirOf = (ctx) => path.join(ctx.runtimeDir, 'pm-items');
+const itemsFile = (ctx) => path.join(dirOf(ctx), 'items.jsonl');
+const stepsFile = (ctx) => path.join(dirOf(ctx), 'steps.jsonl');
+const jobsFile = (ctx) => path.join(dirOf(ctx), 'jobs.jsonl');
+const newId = (prefix) => `${prefix}-${crypto.randomBytes(6).toString('hex')}`;
+
+// The current view, folded from the files. `now` decides placement, so tests can pin the day.
+function view(itemLines, jobLines, now, stepLines = []) {
+  const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  const byItem = steps.foldSteps(stepLines).byItem;
+  const items = pmItems.fold(itemLines).map((i) => ({ ...i, steps: byItem[i.id] || [] }));
+  const currentJobs = jobs.foldJobs(jobLines).map((j) => ({ ...j, ...jobs.progress(j.id, items) }));
+  const lists = Object.fromEntries(pmItems.LISTS.map((l) => [l, []]));
+  for (const it of items) lists[pmItems.placement(it, today)].push(it);
+  return { ok: true, today: today.toISOString().slice(0, 10), lists, jobs: currentJobs, items };
+}
+
+// Each operation returns { status, body, events } and writes nothing itself; the caller appends `events`.
+function checkFields(fields, allowed) {
+  if (!fields || typeof fields !== 'object') return 'fields must be an object';
+  for (const k of Object.keys(fields)) {
+    if (!allowed.includes(k)) return `${k} cannot be set here`;
+  }
+  if ('due' in fields && fields.due !== null && !DATE_RE.test(String(fields.due))) return 'due must be YYYY-MM-DD or null';
+  if ('priority' in fields && fields.priority !== null && !/^P[1-3]$/.test(String(fields.priority))) return 'priority must be P1, P2, P3 or null';
+  return null;
+}
+
+function addItem(line, now) {
+  const parsed = pmItems.parseLine(line, now);
+  if (!parsed.title) return { status: 400, body: { ok: false, error: 'the line needs a title' } };
+  const id = newId('item');
+  const fields = { title: parsed.title, due: parsed.due, priority: parsed.priority, waiting_on: parsed.waiting_on, job: null };
+  return { status: 200, body: { ok: true, item: { id, ...fields, source: 'local' } }, events: [{ event: 'created', id, fields, source: 'local' }] };
+}
+
+function editItem(body, itemLines) {
+  const err = checkFields(body.fields, FIELDS);
+  if (err) return { status: 400, body: { ok: false, error: err } };
+  const item = pmItems.fold(itemLines).find((i) => i.id === body.id);
+  if (!item) return { status: 404, body: { ok: false, error: 'no such item' } };
+  return { status: 200, body: { ok: true, item: { ...item, ...body.fields } }, events: [{ event: 'edited', id: body.id, fields: body.fields }] };
+}
+
+function removeItem(body, itemLines, now) {
+  const item = pmItems.fold(itemLines).find((i) => i.id === body.id);
+  if (!item) return { status: 404, body: { ok: false, error: 'no such item' } };
+  return { status: 200, body: { ok: true, undo_ms: pmItems.UNDO_MS }, events: [pmItems.removalEvent(item, now)] };
+}
+
+function undoItem(body, itemLines, now) {
+  const restore = pmItems.undoEvent(itemLines, body.id, now);
+  if (!restore) return { status: 409, body: { ok: false, error: 'nothing to undo for this item (the window is 8 seconds)' } };
+  return { status: 200, body: { ok: true, item: { id: body.id, ...restore.fields, source: restore.source } }, events: [restore] };
+}
+
+const findItem = (itemLines, id) => pmItems.fold(itemLines).find((i) => i.id === id);
+const noItem = { status: 404, body: { ok: false, error: 'no such item' } };
+
+function flagItem(body, itemLines, events) {
+  const item = findItem(itemLines, body.id);
+  if (!item) return noItem;
+  return { status: 200, body: { ok: true }, events: typeof events === 'function' ? events(item) : events };
+}
+const doneItem = (b, l) => flagItem(b, l, [{ event: 'done', id: b.id }]);
+const reopenItem = (b, l) => flagItem(b, l, [{ event: 'reopened', id: b.id }]);
+const parkItem = (b, l) => flagItem(b, l, [{ event: 'edited', id: b.id, fields: { parked: true, list_override: null } }]);
+const unparkItem = (b, l) => flagItem(b, l, [{ event: 'edited', id: b.id, fields: { parked: false } }]);
+function moveItem(b, l) {
+  if (!pmItems.LISTS.includes(b.list)) return { status: 400, body: { ok: false, error: 'list must be one of ' + pmItems.LISTS.join(', ') } };
+  return flagItem(b, l, [{ event: 'edited', id: b.id, fields: { list_override: b.list, parked: false } }]);
+}
+
+function addStepRoute(b, itemLines) {
+  if (!findItem(itemLines, b.id)) return noItem;
+  const id = newId('step');
+  const r = steps.addStep(b.id, b.text, b.who, id);
+  if (!r.ok) return { status: 400, body: r };
+  return { status: 200, body: { ok: true, step: { id, text: r.event.text, who: r.event.who }, forced: r.forced }, events: [r.event] };
+}
+function stepWho(b, stepLines) {
+  const r = steps.setWho(stepLines, b.step_id, b.who);
+  if (!r.ok) return { status: r.error === 'no such step' ? 404 : 400, body: r };
+  return { status: 200, body: { ok: true, who: r.who, forced: r.forced }, events: [r.event] };
+}
+// PLACEHOLDER. Agent planning of steps needs the run 7 reply path (an agent session answering through the reply
+// verb). Until then this makes ONE step, 'Review: <title>', for the PM only, and only when the PM calls it.
+function planSteps(b, itemLines) {
+  const item = findItem(itemLines, b.id);
+  if (!item) return noItem;
+  // With an agent's reply (from the reply path), parse it: a step that sends something to a person is forced to
+  // agent-drafts by the planner. Without one, fall back to the single review step for the PM.
+  if (b.reply !== undefined) {
+    const plan = require('../../scripts/step-planner.js').parsePlanReply(b.reply);
+    if (!plan.ok) return { status: 400, body: { ok: false, error: plan.error } };
+    const added = plan.steps.map((st) => steps.addStep(b.id, st.text, st.who, newId('step')));
+    return { status: 200, body: { ok: true, steps: added.map((r) => ({ id: r.event.id, text: r.event.text, who: r.event.who })) }, events: added.map((r) => r.event) };
+  }
+  const id = newId('step');
+  const r = steps.addStep(b.id, 'Review: ' + item.title, 'you', id);
+  return { status: 200, body: { ok: true, step: { id, text: r.event.text, who: 'you' } }, events: [r.event] };
+}
+
+function addJob(line) {
+  const d = jobs.draftJob(line);
+  if (!d.when && !d.want && !d.so) return { status: 400, body: { ok: false, error: 'write the job as: when …, I want …, so …' } };
+  const id = newId('job');
+  return { status: 200, body: { ok: true, job: { id, ...d } }, events: [{ event: 'created', id, fields: d }] };
+}
+
+function editJob(body, jobLines) {
+  const err = checkFields(body.fields, JOB_FIELDS);
+  if (err) return { status: 400, body: { ok: false, error: err } };
+  if (!jobs.foldJobs(jobLines).find((j) => j.id === body.id)) return { status: 404, body: { ok: false, error: 'no such job' } };
+  return { status: 200, body: { ok: true }, events: [{ event: 'edited', id: body.id, fields: body.fields }] };
+}
+
+function deleteJob(body, jobLines, itemLines, now) {
+  if (!jobs.foldJobs(jobLines).find((j) => j.id === body.id)) return { status: 404, body: { ok: false, error: 'no such job' } };
+  const reassignTo = body.reassign_to || null;
+  if (reassignTo && !jobs.foldJobs(jobLines).find((j) => j.id === reassignTo)) return { status: 400, body: { ok: false, error: 'reassign_to is not a job' } };
+  const r = jobs.deleteJob(body.id, pmItems.fold(itemLines), reassignTo, now);
+  // Items go to the new job through the item file, and the job's deletion goes to the job file.
+  // Each event names its own file: the job's deletion goes to jobs.jsonl, the item edits to items.jsonl.
+  const events = r.events.map((ev) => ({ ...ev, _file: ev.event === 'deleted' ? 'jobs' : 'items' }));
+  return { status: 200, body: { ok: true, reassigned: r.reassigned }, events };
+}
+
+const ROUTES = {
+  'POST /api/pm-items/add': (b, ctx) => ({ ...addItem(b.line, new Date()), file: 'items' }),
+  'POST /api/pm-items/edit': (b, ctx) => ({ ...editItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/remove': (b, ctx) => ({ ...removeItem(b, ctx.itemLines, new Date()), file: 'items' }),
+  'POST /api/pm-items/undo': (b, ctx) => ({ ...undoItem(b, ctx.itemLines, new Date()), file: 'items' }),
+  'POST /api/pm-items/done': (b, ctx) => ({ ...doneItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/reopen': (b, ctx) => ({ ...reopenItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/park': (b, ctx) => ({ ...parkItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/unpark': (b, ctx) => ({ ...unparkItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/move': (b, ctx) => ({ ...moveItem(b, ctx.itemLines), file: 'items' }),
+  'POST /api/pm-items/steps/add': (b, ctx) => ({ ...addStepRoute(b, ctx.itemLines), file: 'steps' }),
+  'POST /api/pm-items/steps/who': (b, ctx) => ({ ...stepWho(b, ctx.stepLines), file: 'steps' }),
+  'POST /api/pm-items/steps/plan': (b, ctx) => ({ ...planSteps(b, ctx.itemLines), file: 'steps' }),
+  'POST /api/pm-jobs/add': (b) => ({ ...addJob(b.line), file: 'jobs' }),
+  'POST /api/pm-jobs/edit': (b, ctx) => ({ ...editJob(b, ctx.jobLines), file: 'jobs' }),
+  'POST /api/pm-jobs/delete': (b, ctx) => ({ ...deleteJob(b, ctx.jobLines, ctx.itemLines, new Date()), file: 'items' }),
+};
+
+function prepare(ctx, now = new Date()) {
+  return { itemLines: pmItems.readLines(itemsFile(ctx)), jobLines: pmItems.readLines(jobsFile(ctx)), stepLines: pmItems.readLines(stepsFile(ctx)), now };
+}
+
+module.exports = {
+  prefixes: ['/api/pm-items', '/api/pm-jobs'],
+  view, doneItem, reopenItem, parkItem, unparkItem, moveItem, addStepRoute, stepWho, planSteps, addItem, editItem, removeItem, undoItem, addJob, editJob, deleteJob, checkFields, ROUTES, prepare,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p === '/api/pm-items' && req.method === 'GET') {
+      const c = prepare(ctx);
+      ctx.json(res, view(c.itemLines, c.jobLines, c.now, c.stepLines));
+      return true;
+    }
+    const key = `${req.method} ${p}`;
+    if (!ROUTES[key]) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const body = got.body || {};
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+    const c = prepare(ctx);
+    const r = ROUTES[key](body, c);
+    if (r.status === 200 && r.events) {
+      for (const ev of r.events) {
+        const which = ev._file || r.file;
+        const { _file, ...line } = ev;
+        pmItems.appendEvent(which === 'jobs' ? jobsFile(ctx) : which === 'steps' ? stepsFile(ctx) : itemsFile(ctx), line, c.now);
+      }
+    }
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};

package/workspace/lib/routes-records.js

@@ -0,0 +1,61 @@
+'use strict';
+/* routes-records.js — ideas, hypotheses, the decision log, KR metrics and bets (console3 wave E1a).
+ *
+ *   GET  /api/records/<kind>                       → { ok, kind, records }     the folded list
+ *   POST /api/records/<kind>/add  { fields, why? } → { ok, rid }               kind: ideas | hypotheses | decisions | kr-metrics | bets
+ *   POST /api/records/<kind>/edit { rid, fields, why? } → { ok }
+ *   POST /api/records/kr-metrics/reading { rid, at, value } → { ok }           one actual reading of a KR metric
+ *
+ * STATE: planning/records/<kind>.jsonl, written only through scripts/records (which uses scripts/trust/ledger.js).
+ * WHO WRITES: every POST passes pm-guard requirePagePress; an agent session cannot add or edit these records.
+ */
+const path = require('path');
+const guard = require('./pm-guard.js');
+const records = require(path.join(__dirname, '..', '..', 'scripts', 'records', 'index.js'));
+const ledger = require(path.join(__dirname, '..', '..', 'scripts', 'trust', 'ledger.js'));
+
+const rootOf = (ctx) => (ctx && ctx.recordsDir) || path.join(ctx.repoRoot || path.join(__dirname, '..', '..'), 'planning', 'records');
+const UI = () => ledger.actorFrom({ ui: true });
+const bad = (status, error, reasons) => ({ status, body: { ok: false, error, reasons } });
+
+/** Pure handlers: (root, body) -> { status, body }. The press check happens before these. */
+function listRecords(root, kind) {
+  if (!records.kindNames().includes(kind)) return bad(404, 'unknown record kind: ' + kind);
+  return { status: 200, body: { ok: true, kind, records: records.list(root, kind) } };
+}
+function addRecord(root, kind, body) {
+  if (!records.kindNames().includes(kind)) return bad(404, 'unknown record kind: ' + kind);
+  const r = records.add(root, kind, (body && body.fields) || {}, UI(), body && body.why);
+  return r.ok ? { status: 200, body: { ok: true, rid: r.rid } } : bad(400, r.reasons.join('; '), r.reasons);
+}
+function editRecord(root, kind, body) {
+  if (!records.kindNames().includes(kind)) return bad(404, 'unknown record kind: ' + kind);
+  const r = records.edit(root, kind, body && body.rid, (body && body.fields) || {}, UI(), body && body.why);
+  return r.ok ? { status: 200, body: { ok: true } } : bad(r.reasons[0].startsWith('no such') ? 404 : 400, r.reasons.join('; '), r.reasons);
+}
+function readingRecord(root, body) {
+  const r = records.addReading(root, body && body.rid, { at: body && body.at, value: body && body.value }, UI(), body && body.why);
+  return r.ok ? { status: 200, body: { ok: true } } : bad(400, r.reasons.join('; '), r.reasons);
+}
+
+module.exports = {
+  prefixes: ['/api/records'],
+  listRecords, addRecord, editRecord, readingRecord, rootOf,
+  handle: async (req, res, url, ctx) => {
+    const m = url.pathname.match(/^\/api\/records\/([a-z-]+)(?:\/(add|edit|reading))?$/);
+    if (!m) return false;
+    const [, kind, verb] = m;
+    if (req.method === 'GET' && !verb) { const r = listRecords(rootOf(ctx), kind); ctx.json(res, r.body, r.status); return true; }
+    if (req.method !== 'POST' || !verb) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const body = got.body || {};
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+    const r = verb === 'add' ? addRecord(rootOf(ctx), kind, body)
+      : verb === 'edit' ? editRecord(rootOf(ctx), kind, body)
+      : kind === 'kr-metrics' ? readingRecord(rootOf(ctx), body) : bad(404, 'readings belong to kr-metrics');
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};

package/workspace/lib/routes-releases.js

@@ -0,0 +1,129 @@
+'use strict';
+/* routes-releases.js — console3 wave A4: releases, read side.
+ *
+ *   GET  /api/releases                     → { ok, releases, board }   each release carries gapFlags, freezeWarning (null), tags
+ *   POST /api/releases/create  { initiative_ids, type, deploy_at, release_at } → { ok, release }
+ *   POST /api/releases/edit    { id, fields }   fields: initiative_ids, type, deploy_at, release_at, fix_version, accepted
+ *   POST /api/releases/delete  { id }           refused while the release has initiatives assigned
+ *   POST /api/releases/summary { id, lines }    lines: [{ text, source }]; stored only when every line is cited
+ *
+ * STATE. One append-only file, <runtime>/releases/releases.jsonl, folded on every read (scripts/releases.js).
+ * The Jira board name lives in <runtime>/releases/board.json ({ name, tags, map }); it is empty until the PM sets it.
+ * BOUNDARY. PMOS never reads Jira and holds no Jira credential: tickets come from the cached status snapshots an agent
+ * read saved (jira-status.js). A release record never writes a Jira tag. The tag needs the PM's acceptance first
+ * (the `accepted` field); creating the tag is not built. No calendar hold, no customer note: those are outbox actions.
+ * WHO WRITES. Every POST passes pm-guard requirePagePress.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const guard = require('./pm-guard.js');
+const R = require('../../scripts/releases.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const dirOf = (ctx) => path.join(ctx.runtimeDir, 'releases');
+const file = (ctx) => path.join(dirOf(ctx), 'releases.jsonl');
+const newId = () => `rel-${crypto.randomBytes(5).toString('hex')}`;
+const bad = (error, status = 400) => ({ status, body: { ok: false, error } });
+
+function readLines(f) {
+  try { return fs.readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { return []; }
+}
+// The board setting. Empty by default: detection then answers 'board not set'. No naming pattern is ever guessed.
+function readBoard(ctx) {
+  try {
+    const b = JSON.parse(fs.readFileSync(path.join(dirOf(ctx), 'board.json'), 'utf8'));
+    const name = typeof b.name === 'string' ? b.name.trim() : '';
+    return name ? { name, tags: Array.isArray(b.tags) ? b.tags.map(String) : [], map: b.map && typeof b.map === 'object' ? b.map : {} } : null;
+  } catch { return null; }
+}
+// Tickets from the cached Jira snapshots (read-only, no Jira call). A reading saved before fixVersion was carried has no
+// fixVersion list; it is left out, so it cannot raise a false gap flag.
+function cachedTickets(root, jiraStatus) {
+  const out = [];
+  try {
+    for (const q of jiraStatus.linkedInitiatives(root).filter((x) => x.linked)) {
+      const snap = jiraStatus.readSnapshot(root, q.initiative);
+      if (!snap) continue;
+      for (const t of snap.tickets.values()) if (Array.isArray(t.fixVersion)) out.push({ ...t, initiative_id: q.initiative });
+    }
+  } catch { /* no snapshots yet */ }
+  return out;
+}
+
+function view(lines, tickets, board, rule = null) {
+  const releases = R.foldReleases(lines).map((r) => ({
+    ...r, gapFlags: R.gapFlags(r, tickets), freezeWarning: R.freezeWarning(r, rule), tags: R.detectTags(r, board),
+  }));
+  return { ok: true, releases, board: board ? { name: board.name } : null };
+}
+
+const isIdList = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string' && x);
+
+// Each operation returns { status, body, events } and writes nothing itself.
+function createRelease(body, id = newId()) {
+  if (body.initiative_ids !== undefined && !isIdList(body.initiative_ids)) return bad('initiative_ids must be a list of initiative ids');
+  let rel;
+  try { rel = R.newRelease({ id, initiative_ids: body.initiative_ids || [], type: body.type, deploy_at: body.deploy_at, release_at: body.release_at }); } catch (e) { return bad(e.message); }
+  return { status: 200, body: { ok: true, release: rel }, events: [{ event: 'created', ...rel }] };
+}
+
+function editRelease(body, lines) {
+  const f = body.fields;
+  if (!f || typeof f !== 'object' || Array.isArray(f)) return bad('fields must be an object');
+  for (const k of Object.keys(f)) if (!R.EDITABLE.includes(k)) return bad(`${k} cannot be set here`);
+  if (!R.foldReleases(lines).find((r) => r.id === body.id)) return bad('no such release', 404);
+  if ('initiative_ids' in f && !isIdList(f.initiative_ids)) return bad('initiative_ids must be a list of initiative ids');
+  if ('type' in f && !R.TYPES.includes(f.type)) return bad(`type must be one of ${R.TYPES.join('|')}`);
+  for (const k of ['deploy_at', 'release_at']) if (k in f && f[k] !== null && Number.isNaN(Date.parse(f[k]))) return bad(`${k} must be a date or null`);
+  if ('fix_version' in f && f.fix_version !== null && typeof f.fix_version !== 'string') return bad('fix_version must be text or null');
+  if ('accepted' in f && typeof f.accepted !== 'boolean') return bad('accepted must be true or false');
+  return { status: 200, body: { ok: true }, events: [{ event: 'edited', id: body.id, fields: f }] };
+}
+
+function deleteRelease(body, lines) {
+  const r = R.foldReleases(lines).find((x) => x.id === body.id);
+  if (!r) return bad('no such release', 404);
+  if (r.initiative_ids.length) return bad(`not deleted: ${r.initiative_ids.length} initiative(s) are assigned; remove them first`, 409);
+  return { status: 200, body: { ok: true }, events: [{ event: 'deleted', id: body.id }] };
+}
+
+function summarizeRelease(body, lines) {
+  if (!R.foldReleases(lines).find((r) => r.id === body.id)) return bad('no such release', 404);
+  if (!Array.isArray(body.lines)) return bad('lines must be a list of { text, source }');
+  const cited = R.citedSummary(body.lines);
+  if (!cited.ok) return { status: 422, body: { ok: false, error: 'every line needs a source: fact, estimate, assumption, reported or a ticket key', refused: cited.refused } };
+  const clean = body.lines.map((l) => ({ text: String(l.text == null ? '' : l.text), source: l.source }));
+  return { status: 200, body: { ok: true, lines: clean }, events: [{ event: 'summary', id: body.id, lines: clean }] };
+}
+
+const ROUTES = {
+  'POST /api/releases/create': (b) => createRelease(b),
+  'POST /api/releases/edit': (b, c) => editRelease(b, c.lines),
+  'POST /api/releases/delete': (b, c) => deleteRelease(b, c.lines),
+  'POST /api/releases/summary': (b, c) => summarizeRelease(b, c.lines),
+};
+
+module.exports = {
+  prefixes: ['/api/releases'],
+  view, createRelease, editRelease, deleteRelease, summarizeRelease, readBoard, cachedTickets, ROUTES,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p === '/api/releases' && req.method === 'GET') {
+      const jiraStatus = require('./jira-status.js');
+      ctx.json(res, view(readLines(file(ctx)), cachedTickets(ctx.root || ROOT, jiraStatus), readBoard(ctx)));
+      return true;
+    }
+    const key = `${req.method} ${p}`;
+    if (!ROUTES[key]) return false;
+    const got = await ctx.readJson(req);
+    if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+    const body = got.body || {};
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+    const r = ROUTES[key](body, { lines: readLines(file(ctx)) });
+    if (r.status === 200 && r.events) for (const ev of r.events) R.appendRelease(file(ctx), ev);
+    ctx.json(res, r.body, r.status);
+    return true;
+  },
+};

package/workspace/lib/routes-report-facts.js

@@ -0,0 +1,84 @@
+'use strict';
+/* routes-report-facts.js — GET /api/report-families/facts[?ws=] (console3 wave D).
+ *
+ *   { ok, facts: { project:[sections], product:[...], communications:[...], periodic:[...] }, sources }
+ *
+ * The report families view (report-families-view.js) reads its sections from ctx.reportFacts[<family id>]. This route builds
+ * them from the data that exists and from nothing else (scripts/report-families.js buildFamily copies what it is given):
+ *   - project  > progress    one claim per open initiative that has a promised date (scripts/signals/facts.js readRepoFacts:
+ *                            the initiative record's `promised`), label fact, source the record's path;
+ *   - periodic > highlights  one claim per release (<runtime>/releases/releases.jsonl folded by scripts/releases.js),
+ *                            label fact, source that file.
+ * Every other section is empty, on purpose: no forecast, risk, decision, ask or metric record exists to read yet.
+ * Read-only. The repository read is slow (it derives each initiative's stage from git), so a successful read is kept 5 minutes. */
+const fs = require('fs');
+const path = require('path');
+const RF = require('../../scripts/report-families.js');
+const { foldReleases } = require('../../scripts/releases.js');
+
+const prefixes = ['/api/report-families/facts'];
+const TTL = 5 * 60 * 1000;
+const memo = new Map();   // root -> { at, inis }
+
+function repoInis(root, opts) {
+  const hit = memo.get(root);
+  const now = (opts && opts.clock) ? opts.clock() : Date.now();
+  if (hit && now - hit.at < TTL) return hit.inis;
+  const { readRepoFacts } = require('../../scripts/signals/facts.js');
+  const inis = (readRepoFacts(root, {}).inis || []).map((i) => ({ id: i.id, title: i.title, promised: i.promised, done: !!i.done }));
+  memo.set(root, { at: now, inis });
+  return inis;
+}
+
+function readReleases(runtimeDir) {
+  const f = path.join(runtimeDir, 'releases', 'releases.jsonl');
+  let lines = [];
+  try { lines = fs.readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { return { file: f, releases: [] }; }
+  return { file: f, releases: foldReleases(lines) };
+}
+
+/** Pure: (initiatives, releases, { releasesFile }) -> { facts, sources }. A source with no rows adds no claim. */
+function buildFacts(inis, releases, opts = {}) {
+  const progress = (inis || []).filter((i) => i && !i.done && i.promised)
+    .map((i) => ({ id: 'ini:' + i.id, text: `${i.title || i.id}: promised ${i.promised}`, label: 'fact', source: `planning/initiatives/${i.id}.md` }));
+  const highlights = (releases || []).map((r) => ({
+    id: 'rel:' + r.id, text: `Release ${r.fix_version || r.id} (${r.type})${r.release_at ? ', ' + String(r.release_at).slice(0, 10) : ''}`,
+    label: 'fact', source: opts.releasesFile || 'releases/releases.jsonl' }));
+  return {
+    facts: {
+      project: RF.buildFamily('project', { progress }),
+      product: RF.buildFamily('product', {}),
+      communications: RF.buildFamily('communications', {}),
+      periodic: RF.buildFamily('periodic', { highlights }),
+    },
+    sources: { initiatives_with_promise: progress.length, releases: highlights.length },
+  };
+}
+
+/** Pure handler over (opts: { root, runtimeDir, loadInis }) -> { code, body }. */
+function factsOf(opts = {}) {
+  try {
+    const inis = (opts.loadInis || repoInis)(opts.root, opts);
+    const rel = opts.runtimeDir ? readReleases(opts.runtimeDir) : { file: null, releases: [] };
+    return { code: 200, body: { ok: true, ...buildFacts(inis, rel.releases, { releasesFile: rel.file ? path.relative(opts.root || '', rel.file) || rel.file : undefined }) } };
+  } catch (e) {
+    return { code: 500, body: { ok: false, error: 'report facts could not be read: ' + (e && e.message ? e.message : String(e)) } };
+  }
+}
+
+module.exports = {
+  prefixes, buildFacts, factsOf,
+  handle: async (req, res, url, ctx) => {
+    if (url.pathname !== '/api/report-families/facts') return false;
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    let root;
+    try { const w = ctx.getWs && ctx.getWs(url.searchParams.get('ws') || null); root = w && w.root; } catch { root = null; }
+    const useRoot = root || path.resolve(__dirname, '..', '..');
+    let inis;
+    try { inis = ((await require('./facts-async.js').readFactsAsync(useRoot)).inis || []).map((i) => ({ id: i.id, title: i.title, promised: i.promised, done: !!i.done })); }
+    catch (e) { ctx.json(res, { ok: false, error: 'report facts could not be read: ' + (e && e.message ? e.message : String(e)) }, 500); return true; }
+    const out = factsOf({ root: useRoot, runtimeDir: ctx.runtimeDir, loadInis: () => inis });
+    ctx.json(res, out.body, out.code);
+    return true;
+  },
+};

package/workspace/lib/routes-report-families.js

@@ -0,0 +1,32 @@
+'use strict';
+/* routes-report-families.js — console3 wave B4: the four report families and the claims check.
+ *
+ *   GET  /api/report-families         → { ok, families, labels, required }
+ *   POST /api/report-families/check   { family, variant?, sections, known_keys?, absent_keys?, stale_keys? }
+ *                                    → { ok, blocked, reasons, warnings, sections, ... }
+ * Pure. The check reads nothing from disk and writes nothing. There is no send and no issue route in this wave. */
+const RF = require('../../scripts/report-families.js');
+
+const prefixes = ['/api/report-families'];
+const strs = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined);
+
+module.exports = {
+  prefixes,
+  handle: async (req, res, url, ctx) => {
+    const p = url.pathname;
+    if (p === '/api/report-families' && req.method === 'GET') {
+      ctx.json(res, { ok: true, families: RF.FAMILIES, labels: RF.LABELS, required: RF.REQUIRED });
+      return true;
+    }
+    if (p === '/api/report-families/check' && req.method === 'POST') {
+      const got = await ctx.readJson(req);
+      if (!got.ok) { ctx.json(res, { ok: false, error: 'invalid JSON body' }, 400); return true; }
+      const b = got.body || {};
+      if (!Array.isArray(b.sections)) { ctx.json(res, { ok: false, error: 'sections must be a list' }, 400); return true; }
+      const out = RF.sendCheck({ family: b.family, variant: b.variant, sections: b.sections, knownKeys: strs(b.known_keys), absentKeys: strs(b.absent_keys), staleKeys: strs(b.stale_keys) });
+      ctx.json(res, out, out.ok ? 200 : 400);
+      return true;
+    }
+    return false;
+  },
+};