create-pmos 0.134.0 → 0.135.0

package/workspace/lib/routes-boards.js

@@ -0,0 +1,734 @@
+'use strict';
+/* routes-boards.js — console3 Initiatives: Portfolio, Board and Initiative, with a workflow per board
+ * (c3-initiative-boards; planning/prd/c3-initiative-boards-prd.md "Model", "State", "API contract").
+ *
+ *   GET  /api/boards                                  → { ok, boards: [portfolio row] }         every workspace; `ws` is ignored
+ *   GET  /api/boards/board?ws&board                   → { ok, board, counts: { total, byStage, byStatus }, asks, nextRelease, recent }
+ *   GET  /api/boards/backlog?ws&board&q&stage&status&owner&horizon&anchor&view&sort&offset&limit
+ *                                                     → { ok, total, offset, limit, rows, facets: { stage, status, owner, horizon } }
+ *   GET  /api/boards/columns?ws&board&q&owner&cap     → { ok, columns: [{ stage, cat, hint, count, rows }] }
+ *   GET  /api/boards/initiative?ws&board&id           → { ok, row, board, history, tools }
+ *   GET  /api/boards/asks?ws&board&state              → { ok, asks }                            state: open (default) | accepted | declined | all
+ *   GET  /api/boards/sprints?ws&board                 → { ok, source: jira|none, readAt, sprints }
+ *   GET  /api/boards/items?ws&board                   → { ok, build, jira, items, initiatives }   PMOS tasks + Jira items (Build and deliver only)
+ *   POST /api/boards/create        { ws, name, domain?, template }                       → { ok, board }
+ *   POST /api/boards/workflow      { ws, board, stages, moveRemoved?, sprints? }        → { ok, board, moved }
+ *   POST /api/boards/move          { ws, board, id, to, why? }                           → { ok, row, warnings }
+ *   POST /api/boards/assign        { ws, id, to }                                        → { ok }
+ *   POST /api/boards/asks/add      { ws, board, line, source? }                          → { ok, ask, draft }
+ *   POST /api/boards/asks/accept   { ws, board, ask, title, lane, anchor, intent?, id? } → { ok, initiative, stage }
+ *   POST /api/boards/asks/decline  { ws, board, ask, why }                               → { ok }
+ *   POST /api/boards/asks/more     { ws, board, ask, note? }                             → { ok }
+ *   POST /api/boards/settings      { ws, board, buildDeliver?, jira?, offer?, defTpl? }       → { ok, board }
+ *   POST /api/boards/ini-workflow  { ws, board, id, template?, stages, moveTo? }         → { ok, row, moved }
+ *   POST /api/boards/tasks/add     { ws, board, initiative, title, type?, epic?, start?, due?, owner? } → { ok, item }
+ *   POST /api/boards/tasks/state   { ws, board, task, state }                            → { ok, item }
+ *   POST /api/boards/tasks/reschedule { ws, board, task, days }                          → { ok, item }
+ * (console3-initiatives-parity, planning/prd/console3-initiatives-parity-prd.md: the workflow belongs to each initiative, a board
+ *  says whether it builds and delivers, and PMOS tasks live on the board. All of it is append-only in the same ledger.)
+ *
+ * THE MODEL is scripts/boards.js (pure). This file reads, folds and appends.
+ *
+ * BOARDS OF A WORKSPACE. The default board (the repository; id = the workspace id), one board per `products/<domain>/`
+ * folder (id = the folder name), and every board the ledger created. An initiative belongs to the default board, or to
+ * the domain board whose folder holds its record, until an `assign` or an accepted ask puts it on another board.
+ *
+ * STATE. <stateDirFor(w)>/boards.jsonl, append-only, one per repository. With no state folder the reads use the
+ * defaults and every write answers 409 with the reason (stateDirFor is called without `create`).
+ *
+ * ROWS come from lib/initiative-rows.js rowsFor (the cached derivation; never a scan per request) and the Roadmap row
+ * of routes-initiatives.js rowOf, mapped to the PRD row and cached per repository by the read signature. Until the first
+ * derivation of a repository lands, a read answers 202 { ok: true, pending: true } (the Portfolio marks that board
+ * `pending`), and a write that needs the rows answers 202 { ok: false, pending: true, error }.
+ * Row fields with no source are null, never guessed: `owner` is the record's own `owner:` frontmatter; `start`/`end`
+ * are the span of the initiative's dated plan items (lib/item-spans.js); `status` is done (accepted, closed or
+ * cancelled), late (health off track, or `end` before today), at risk (health at risk), else on track.
+ *
+ * THE PMOS-SELF BOARD is the default board of the workspace whose root is the PMOS checkout the server is embedded in
+ * (server.js EMBEDDED_SELF, passed as ctx.selfRoot). Its stages are the nine derived stage names (read-only); a move or
+ * a workflow edit there is refused with 409 "PMOS keeps its derived ladder".
+ *
+ * WHO WRITES. Every POST passes pm-guard requirePagePress. A new initiative is made only by lib/initiative-writer.js
+ * createInitiative (it refuses an unanchored create). Nothing here reads or writes Jira: sprints come from the cached
+ * snapshots of lib/jira-status.js.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const rowsLib = require('./initiative-rows.js');
+const writer = require('./initiative-writer.js');
+const itemSpans = require('./item-spans.js');
+const jiraStatus = require('./jira-status.js');
+const routesInit = require('./routes-initiatives.js');
+const jiraTickets = require('./jira-tickets.js');
+const { repoScript } = require('./repo-script.js');
+const B = require(repoScript('boards.js'));
+const intake = require(repoScript('intake.js'));
+
+const LEDGER = 'boards.jsonl';
+const SELF_REFUSAL = 'PMOS keeps its derived ladder: its stages come from scripts/workflow-state.js, so a move or a workflow edit is refused here';
+const NO_STATE = 'This repository has no PMOS state folder (pmos/state, state or .pmos). Boards read with the defaults, and nothing is saved until the folder exists.';
+const PENDING = 'The initiatives are being read. Ask again in a few seconds.';
+const ONE_LINE = (v, max) => typeof v === 'string' && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n\x00-\x08\x0b-\x1f]/.test(v);
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const today = () => new Date().toISOString().slice(0, 10);
+
+// ── the ledger ────────────────────────────────────────────────────────────────────────────────────
+function ledgerFile(ctx, w) {
+  const d = ctx.stateDirFor ? ctx.stateDirFor(w) : null;
+  return d ? path.join(d, LEDGER) : null;
+}
+function readLedger(ctx, w) {
+  const f = ledgerFile(ctx, w);
+  if (!f) return [];
+  try { return fs.readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { return []; }
+}
+function append(file, actor, ev) {
+  const line = { at: new Date().toISOString(), by: actor.by, ...ev };
+  fs.appendFileSync(file, JSON.stringify(line) + '\n');
+  return line;
+}
+
+// ── boards of a workspace ─────────────────────────────────────────────────────────────────────────
+const isSelf = (ctx, w) => !!(ctx.selfRoot && w && path.resolve(w.root) === path.resolve(ctx.selfRoot));
+
+function domainsOf(root) {
+  try {
+    return fs.readdirSync(path.join(root, 'products'), { withFileTypes: true })
+      .filter((d) => d.isDirectory() && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(d.name)).map((d) => d.name).sort();
+  } catch { return []; }
+}
+
+function boardsOf(ctx, w, folded) {
+  const self = isSelf(ctx, w);
+  const base = [{ id: w.id, name: w.name || path.basename(w.root), domain: null, kind: 'default' }];
+  for (const d of domainsOf(w.root)) if (d !== w.id) base.push({ id: d, name: d, domain: d, kind: 'domain' });
+  const known = new Set(base.map((b) => b.id));
+  for (const [id, b] of folded.boards) if (!known.has(id) && b.created) { base.push({ id, name: b.name || id, domain: b.domain || null, kind: 'created' }); known.add(id); }
+  return base.map((b0) => {
+    const led = folded.boards.get(b0.id) || {};
+    const selfBoard = self && b0.kind === 'default';
+    const template = selfBoard ? 'pmos' : (B.WORKFLOW_TEMPLATES[led.template] ? led.template : 'product');
+    const workflow = selfBoard ? B.SELF_LADDER.map((s) => ({ ...s })) : (Array.isArray(led.workflow) && led.workflow.length ? led.workflow : B.templateWorkflow(template));
+    const set = B.boardSettings({ ...led, template, self: selfBoard });
+    return {
+      ws: w.id, id: b0.id, name: typeof led.name === 'string' && led.name ? led.name : b0.name, domain: 'domain' in led ? led.domain : b0.domain,
+      kind: b0.kind, template, templateEdited: selfBoard ? false : B.isTemplateEdited(template, workflow), workflow, self: selfBoard,
+      tracker: led.tracker || (set.jira ? `Jira · ${set.jira}` : null), sprints: !!led.sprints || (set.build && !!set.jira),
+      build: set.build, buildDeliver: set.build, jira: set.jira, offer: set.offer, defTpl: set.defTpl,
+    };
+  });
+}
+
+function boardIdOf(rowBase, boards, folded, w) {
+  const a = folded.assigns.get(rowBase.id);
+  if (a && boards.some((b) => b.id === a)) return a;
+  if (rowBase.domainFolder && boards.some((b) => b.id === rowBase.domainFolder && b.kind === 'domain')) return rowBase.domainFolder;
+  return w.id;
+}
+
+// ── rows ──────────────────────────────────────────────────────────────────────────────────────────
+const rowCache = new Map();   // root → { key, rows }
+
+function frontmatter(root, rel) {
+  if (!rel) return {};
+  let text = '';
+  try { text = fs.readFileSync(path.isAbsolute(rel) ? rel : path.join(root, rel), 'utf8'); } catch { return {}; }
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*?)\s*$/.exec(line);
+    if (kv) out[kv[1]] = kv[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function statusOf(rec, healthLevel, end, day) {
+  if (rec.accepted || (rec.stopped && ['closed', 'cancelled'].includes(rec.stopped.state))) return 'done';
+  if (healthLevel === 'off' || (end && end < day)) return 'late';
+  if (healthLevel === 'at-risk') return 'at risk';
+  return 'on track';
+}
+
+/** The board-independent part of every work row of a repository, cached by the read signature. */
+function baseRows(w) {
+  const got = rowsLib.rowsFor(w.root);
+  if (got.pending) return { pending: true };
+  if (!got.ok) return { ok: false, error: got.error || 'the initiatives could not be read' };
+  const day = today();
+  const sig = routesInit.sigOf(w.root);
+  sig.records = rowsLib.answerSig(got);
+  const cacheKey = JSON.stringify(sig) + day;
+  const hit = rowCache.get(w.root);
+  if (hit && hit.key === cacheKey) return { ok: true, rows: hit.rows };
+  const F = routesInit.frameOf(w, got.rows, { now: Date.now(), sessions: [] });
+  const itemsBy = new Map();
+  for (const it of Object.values(F.fold.items || {})) {
+    if (!it || !it.initiative) continue;
+    if (!itemsBy.has(it.initiative)) itemsBy.set(it.initiative, []);
+    itemsBy.get(it.initiative).push(it);
+  }
+  const rows = [];
+  const seen = new Set();
+  for (const id of Object.values(F.placed.order).flat()) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const rec = F.byId.get(id);
+    if (!rec || !F.placed.byInit[id] || (rec.group && rec.group !== 'work')) continue;
+    let r;
+    try { r = routesInit.rowOf(F, rec); } catch { continue; }
+    const fm = frontmatter(w.root, rec.record);
+    let span = null;
+    try { span = itemSpans.initiativeSpan(itemSpans.spansOf(itemsBy.get(id) || [])); } catch { span = null; }
+    const end = span ? span.due || null : null;
+    const prd = fm.prd_path || null;
+    const hasSpec = !!(prd && fs.existsSync(path.join(w.root, prd)));
+    const relRec = String(rec.record || '').split(path.sep).join('/');
+    const dm = /^products\/([^/]+)\//.exec(relRec);
+    rows.push({
+      id, title: r.title, lane: r.lane || null,
+      owner: fm.owner ? String(fm.owner) : null,
+      anchor: r.anchor || null, horizon: r.horizon || null, rank: Number.isInteger(r.rank) ? r.rank : null, dormant: !!r.dormant,
+      status: statusOf(rec, r.health && r.health.level, end, day),
+      health: r.health ? r.health.level : null,
+      start: span ? span.start || null : null, end,
+      progress: r.progress && r.progress.total ? Math.round((r.progress.done / r.progress.total) * 100) / 100 : null,   // a fraction 0..1, as the PRD row reads
+      progressLabel: r.progress ? (r.progress.label || `${r.progress.done} of ${r.progress.total}`) : null,
+      updated: r.last_activity || null,
+      reading: B.readingOf(r.nine_stages, { accepted: !!rec.accepted }),
+      lifecycle: rec.stopped ? rec.stopped.state : null,
+      hasSpec, record: relRec || null, domainFolder: dm ? dm[1] : null,
+    });
+  }
+  rowCache.set(w.root, { key: cacheKey, rows });
+  return { ok: true, rows };
+}
+
+/** The PRD row of one base row on one board. */
+function boardRow(board, base, folded) {
+  const s = B.stageOf(board, base.id, base.reading, folded);
+  const wf = B.workflowOf(board, base.id, folded);
+  const cat = B.catOf({ workflow: wf }, s.stage);
+  const row = {
+    id: base.id, title: base.title, lane: base.lane, stage: s.stage, cat, owner: base.owner, anchor: base.anchor,
+    horizon: base.horizon, status: base.status, start: base.start, end: base.end, progress: base.progress, warnings: [],
+    rank: base.rank, health: base.health, updated: base.updated, reading: base.reading, stageSource: s.source, lifecycle: base.lifecycle,
+    template: B.templateOf(board, base.id, folded), workflow: wf.map((x) => ({ name: x.name, cat: x.cat })),
+  };
+  const w = [];
+  if (s.source === 'move') {
+    const last = [...folded.moves].reverse().find((m) => m.board === board.id && m.id === base.id);
+    if (last && last.to === s.stage) for (const x of last.warnings || []) if (/^Skipped /.test(x)) w.push(x);
+  }
+  for (const x of B.cardWarnings(board, row, { hasSpec: base.hasSpec })) if (!w.includes(x)) w.push(x);
+  row.warnings = w;
+  return row;
+}
+
+/** Everything a read of one workspace needs. */
+function frameFor(ctx, w) {
+  const folded = B.fold(readLedger(ctx, w));
+  const boards = boardsOf(ctx, w, folded);
+  return { w, folded, boards };
+}
+function rowsOfBoard(fr, board, base) {
+  return base.filter((r) => boardIdOf(r, fr.boards, fr.folded, fr.w) === board.id).map((r) => boardRow(board, r, fr.folded));
+}
+
+function readReleases(ctx) {
+  if (!ctx.runtimeDir) return [];
+  try {
+    const R = require(repoScript('releases.js'));
+    return R.foldReleases(fs.readFileSync(path.join(ctx.runtimeDir, 'releases', 'releases.jsonl'), 'utf8').split('\n').filter(Boolean));
+  } catch { return []; }
+}
+/** The next release that carries an initiative of the board: the earliest release (or deploy) date from today on. */
+function nextReleaseOf(releases, ids) {
+  const day = today();
+  let best = null;
+  for (const r of releases) {
+    if (!(r.initiative_ids || []).some((x) => ids.has(x))) continue;
+    const at = r.release_at || r.deploy_at;
+    if (!at || at.slice(0, 10) < day) continue;
+    if (!best || at < best.at) best = { id: r.id, type: r.type, at };
+  }
+  return best;
+}
+const openAsks = (folded, boardId) => [...folded.asks.values()].filter((a) => a.board === boardId && a.state === 'open').length;
+const pageAsk = (a) => ({ ...a, by: actorLib.pageName(a.by) });
+const pageMove = (m) => ({ ...m, by: actorLib.pageName(m.by) });
+
+/** The work items of a board: its PMOS tasks (the ledger) and, with Build and deliver on, the Jira items of its initiatives
+ * (the ticket drafts this repository pushed, with the status of the cached readings; read-only, no dates or people). */
+function itemsOf(w, fr, board, rows) {
+  const ids = new Set(rows.map((x) => x.id));
+  const out = [];
+  const jiraKeys = new Set();
+  if (board.build) {
+    for (const row of rows) {
+      let d = null;
+      let snap = null;
+      try { d = jiraTickets.readDraft(w.root, row.id); } catch { d = null; }
+      if (!d) continue;
+      try { snap = jiraStatus.readSnapshot(w.root, row.id); } catch { snap = null; }
+      const reading = (k) => (snap && snap.tickets && snap.tickets.get ? snap.tickets.get(k) : null) || null;
+      const epicKey = /^[A-Za-z][A-Za-z0-9_]*-\d+$/.test(String((d.fm && d.fm.epic) || '')) ? String(d.fm.epic).toUpperCase() : null;
+      if (epicKey) {
+        const rd = reading(epicKey);
+        out.push({ uid: epicKey, key: epicKey, kind: 'Epic', src: 'jira', title: (rd && rd.summary) || row.title, status: B.itemStatus(rd && rd.status, rd && rd.category), blocked: !!(rd && rd.flagged), owner: null, ini: row.id, epic: null, start: null, end: null, ref: null, board: board.id });
+        jiraKeys.add(epicKey);
+      }
+      for (const t of d.tickets || []) {
+        if (!t.jira || jiraKeys.has(t.jira)) continue;
+        const rd = reading(t.jira);
+        out.push({ uid: t.jira, key: t.jira, kind: ['Story', 'Task', 'Bug'].includes(t.type) ? t.type : 'Task', src: 'jira', title: (rd && rd.summary) || t.summary || t.jira,
+          status: B.itemStatus(rd && rd.status, rd && rd.category), blocked: !!(rd && rd.flagged), owner: null, ini: row.id, epic: epicKey, start: null, end: null, ref: null, board: board.id });
+        jiraKeys.add(t.jira);
+      }
+    }
+  }
+  for (const t of fr.folded.tasks.values()) if (t.board === board.id && ids.has(t.initiative)) out.push(B.taskItem(t));
+  return B.rollupItems(out);
+}
+
+// ── HTTP ──────────────────────────────────────────────────────────────────────────────────────────
+function wsOf(ctx, wsParam) {
+  const w = ctx.getWs(wsParam || null);
+  if (!w || (wsParam && w.id !== wsParam)) return null;
+  return w;
+}
+const fail = (ctx, res, status, error, extra = {}) => { ctx.json(res, { ok: false, error, ...extra }, status); return true; };
+
+function portfolio(ctx) {
+  const list = ctx.workspaceList ? ctx.workspaceList() : [];
+  const releases = readReleases(ctx);
+  const out = [];
+  for (const w of list) {
+    let fr;
+    try { fr = frameFor(ctx, w); } catch (e) { out.push({ ws: w.id, id: w.id, name: w.name, error: String((e && e.message) || e).slice(0, 160) }); continue; }
+    let base = null;
+    let pending = false;
+    let error = null;
+    try {
+      const b = baseRows(w);
+      if (b.pending) pending = true; else if (!b.ok) error = b.error; else base = b.rows;
+    } catch (e) { error = String((e && e.message) || e).slice(0, 160); }
+    for (const board of fr.boards) {
+      const entry = { ...board, health: null, counts: null, asks: openAsks(fr.folded, board.id), nextRelease: null };
+      if (pending) entry.pending = true;
+      if (error) entry.error = error;
+      if (base) {
+        const rows = rowsOfBoard(fr, board, base);
+        const c = B.counts(rows, board.workflow);
+        entry.health = B.health(rows);
+        entry.counts = { total: c.total, open: c.open, byCat: c.byCat, risk: c.risk, late: c.late };
+        entry.nextRelease = nextReleaseOf(releases, new Set(rows.map((r) => r.id)));
+      }
+      out.push(entry);
+    }
+  }
+  return { ok: true, today: today(), boards: out };
+}
+
+/** Resolve ws + board of a GET, and the board's rows; answers and returns null when it cannot. */
+function boardRead(ctx, res, url, { rows = true } = {}) {
+  const w = wsOf(ctx, url.searchParams.get('ws'));
+  if (!w) { fail(ctx, res, 404, 'no such workspace'); return null; }
+  const fr = frameFor(ctx, w);
+  const bid = url.searchParams.get('board') || w.id;
+  const board = fr.boards.find((b) => b.id === bid);
+  if (!board) { fail(ctx, res, 404, `no board ${bid} in this workspace`); return null; }
+  if (!rows) return { w, fr, board, rows: null };
+  const b = baseRows(w);
+  if (b.pending) { ctx.json(res, { ok: true, pending: true, ws: w.id, board: board.id }, 202); return null; }
+  if (!b.ok) { fail(ctx, res, 500, b.error); return null; }
+  return { w, fr, board, base: b.rows, rows: rowsOfBoard(fr, board, b.rows) };
+}
+
+const READS = {
+  '/api/boards/board': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    const c = B.counts(r.rows, r.board.workflow);
+    const recent = r.fr.folded.moves.filter((m) => m.board === r.board.id).slice(-10).reverse().map(pageMove);
+    ctx.json(res, { ok: true, board: { ...r.board, health: B.health(r.rows) }, counts: { total: c.total, open: c.open, byStage: c.byStage, byStatus: c.byStatus, byCat: c.byCat },
+      asks: openAsks(r.fr.folded, r.board.id), nextRelease: nextReleaseOf(readReleases(ctx), new Set(r.rows.map((x) => x.id))), recent });
+  },
+  '/api/boards/backlog': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    const q = Object.fromEntries(['q', 'stage', 'status', 'owner', 'horizon', 'anchor', 'cat', 'view', 'sort', 'offset', 'limit', 'me'].map((k) => [k, url.searchParams.get(k)]));
+    if (!q.me) q.me = actorLib.PM_SLUG;
+    const out = B.filterRows(r.rows, { ...q, stages: r.board.workflow.map((s) => s.name) });
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, ...out });
+  },
+  '/api/boards/columns': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    let cap = Number.parseInt(url.searchParams.get('cap'), 10);
+    if (!Number.isFinite(cap) || cap < 0) cap = 8;
+    cap = Math.min(cap, 100);
+    const q = (url.searchParams.get('q') || '').trim().toLowerCase();
+    const owner = url.searchParams.get('owner');
+    let rows = r.rows;
+    if (q) rows = rows.filter((x) => String(x.title).toLowerCase().includes(q) || x.id.includes(q));
+    if (owner) rows = rows.filter((x) => (owner === 'none' ? !x.owner : String(x.owner || '').toLowerCase() === owner.toLowerCase()));
+    rows = B.filterRows(rows, { view: 'all', sort: 'rank', limit: rows.length || 1, all: true }).rows;
+    const columns = r.board.workflow.map((s) => {
+      const inCol = rows.filter((x) => x.stage === s.name);
+      return { stage: s.name, cat: s.cat, hint: s.hint || '', count: inCol.length, rows: inCol.slice(0, cap) };
+    });
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, columns });
+  },
+  '/api/boards/initiative': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    const id = url.searchParams.get('id') || '';
+    const base = r.base.find((x) => x.id === id);
+    if (!base) return fail(ctx, res, 404, `no work-lane initiative ${id} in this workspace`);
+    const own = r.fr.boards.find((b) => b.id === boardIdOf(base, r.fr.boards, r.fr.folded, r.w)) || r.board;
+    const row = boardRow(own, base, r.fr.folded);
+    const F = r.fr.folded;
+    const history = [];
+    for (const m of F.moves) if (m.id === id) history.push({ kind: m.via === 'move' ? 'move' : m.via, ...pageMove(m) });
+    for (const e of F.events) {
+      if (e.kind === 'assign' && e.id === id) history.push({ kind: 'assign', at: e.at || null, by: actorLib.pageName(e.by || null), board: e.board || null, to: e.to });
+      if (e.kind === 'ini-workflow' && e.id === id && Array.isArray(e.stages)) history.push({ kind: 'workflow', at: e.at || null, by: actorLib.pageName(e.by || null), board: e.board || null, template: e.template || null, stages: e.stages.map((x) => x && x.name).filter(Boolean) });
+    }
+    history.sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')));
+    const kind = row.template && B.INI_TEMPLATES[row.template] ? B.INI_TEMPLATES[row.template].kind : own.template;
+    const tools = (B.TOOLS[kind] || B.TOOLS.product)[row.cat] || [];
+    ctx.json(res, { ok: true, ws: r.w.id, row, board: own, history, tools, toolsByCat: B.TOOLS[kind] || B.TOOLS.product });
+  },
+  '/api/boards/asks': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url, { rows: false });
+    if (!r) return;
+    const state = url.searchParams.get('state') || 'open';
+    if (!['open', 'accepted', 'declined', 'all'].includes(state)) return fail(ctx, res, 400, 'state is open, accepted, declined or all');
+    const asks = [...r.fr.folded.asks.values()].filter((a) => a.board === r.board.id && (state === 'all' || a.state === state))
+      .sort((a, b) => String(b.at || '').localeCompare(String(a.at || ''))).map(pageAsk);
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, asks });
+  },
+  '/api/boards/items': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, build: r.board.build, jira: r.board.jira, items: itemsOf(r.w, r.fr, r.board, r.rows),
+      initiatives: r.rows.map((x) => ({ id: x.id, title: x.title, stage: x.stage, cat: x.cat, status: x.status, owner: x.owner, horizon: x.horizon, start: x.start, end: x.end, progress: x.progress, template: x.template })) });
+  },
+  '/api/boards/sprints': (ctx, res, url) => {
+    const r = boardRead(ctx, res, url);
+    if (!r) return;
+    const ids = new Set(r.rows.map((x) => x.id));
+    const snaps = [];
+    try {
+      for (const q of jiraStatus.linkedInitiatives(r.w.root).filter((x) => x.linked)) {
+        const s = jiraStatus.readSnapshot(r.w.root, q.initiative);
+        if (s) snaps.push({ initiative: q.initiative, fetchedAt: s.fetchedAt, tickets: s.tickets });
+      }
+    } catch { /* no snapshot yet */ }
+    ctx.json(res, { ok: true, ws: r.w.id, board: r.board.id, ...B.sprintsOf(snaps, (id) => ids.has(id)) });
+  },
+};
+
+// ── writes ────────────────────────────────────────────────────────────────────────────────────────
+/** The workspace, its frame and the named board of a POST body; answers and returns null when it cannot. */
+function postFrame(ctx, res, body, { needBoard = true } = {}) {
+  const w = wsOf(ctx, typeof body.ws === 'string' ? body.ws : null);
+  if (!w) { fail(ctx, res, 404, 'no such workspace'); return null; }
+  const fr = frameFor(ctx, w);
+  let board = null;
+  if (needBoard) {
+    const bid = typeof body.board === 'string' && body.board ? body.board : null;
+    if (!bid) { fail(ctx, res, 400, 'board is required'); return null; }
+    board = fr.boards.find((b) => b.id === bid);
+    if (!board) { fail(ctx, res, 404, `no board ${bid} in this workspace`); return null; }
+  }
+  return { w, fr, board, file: ledgerFile(ctx, w) };
+}
+function needRows(ctx, res, w) {
+  const b = baseRows(w);
+  if (b.pending) { ctx.json(res, { ok: false, pending: true, ws: w.id, error: PENDING }, 202); return null; }
+  if (!b.ok) { fail(ctx, res, 500, b.error); return null; }
+  return b.rows;
+}
+const slug = (s) => String(s || '').toLowerCase().normalize('NFKD').replace(/[^\x00-\x7f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/, '');
+
+/** The Build and deliver settings of a create or settings body: { value } (only the keys sent) or { error }. */
+function settingsOf(body, board) {
+  const v = {};
+  const bd = body.buildDeliver != null ? body.buildDeliver : body.build;
+  if (bd != null) { if (typeof bd !== 'boolean') return { error: 'buildDeliver is true or false' }; v.buildDeliver = bd; }
+  if (body.jira != null && body.jira !== '') {
+    if (typeof body.jira !== 'string' || !/^[A-Za-z][A-Za-z0-9_]{0,19}$/.test(body.jira.trim())) return { error: 'jira is a Jira project key: a letter, then letters, digits or _ (at most 20)' };
+    v.jira = body.jira.trim().toUpperCase();
+  } else if (body.jira === '') v.jira = null;
+  const build = 'buildDeliver' in v ? v.buildDeliver : board ? board.build : true;
+  if (body.offer != null) {
+    if (!Array.isArray(body.offer) || !body.offer.length || body.offer.some((k) => !B.INI_TEMPLATES[k])) return { error: `offer is a list of templates: ${Object.keys(B.INI_TEMPLATES).join(', ')}` };
+    const blocked = body.offer.filter((k) => !build && B.templateBuilds(k));
+    if (blocked.length) return { error: `${blocked.join(', ')} need Build and deliver on` };
+    v.offer = [...new Set(body.offer)];
+  }
+  if (body.defTpl != null) {
+    if (!B.INI_TEMPLATES[body.defTpl]) return { error: `defTpl is one of ${Object.keys(B.INI_TEMPLATES).join(', ')}` };
+    const offer = v.offer || (board ? board.offer : Object.keys(B.INI_TEMPLATES));
+    if (!offer.includes(body.defTpl)) return { error: `defTpl must be a template the board offers (${offer.join(', ')})` };
+    if (!build && B.templateBuilds(body.defTpl)) return { error: `${body.defTpl} needs Build and deliver on` };
+    v.defTpl = body.defTpl;
+  }
+  return { value: v };
+}
+
+const WRITES = {
+  '/api/boards/create': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body, { needBoard: false });
+    if (!p) return;
+    if (!ONE_LINE(body.name, 60)) return fail(ctx, res, 400, 'give a board name of 1 to 60 characters on one line');
+    if (!B.WORKFLOW_TEMPLATES[body.template]) return fail(ctx, res, 400, `template must be one of ${Object.keys(B.WORKFLOW_TEMPLATES).join(', ')}`);
+    if (body.domain != null && body.domain !== '' && !ONE_LINE(body.domain, 60)) return fail(ctx, res, 400, 'domain is one line of at most 60 characters');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const name = body.name.trim();
+    if (p.fr.boards.some((b) => b.name.toLowerCase() === name.toLowerCase())) return fail(ctx, res, 409, `a board named "${name}" exists already in this workspace`);
+    const ids = new Set(p.fr.boards.map((b) => b.id));
+    const stem = slug(name) || 'board';
+    let id = stem;
+    for (let n = 2; ids.has(id); n++) id = `${stem}-${n}`;
+    const workflow = B.templateWorkflow(body.template);
+    const set = settingsOf(body, null);
+    if (set.error) return fail(ctx, res, 400, set.error);
+    const ev = { kind: 'board', op: 'create', board: id, name, domain: body.domain ? String(body.domain).trim() : null, template: body.template, workflow, sprints: false, tracker: null };
+    for (const k of ['buildDeliver', 'jira', 'offer', 'defTpl']) if (k in set.value) ev[k] = set.value[k];
+    if (ev.buildDeliver !== false && ev.jira) { ev.tracker = `Jira · ${ev.jira}`; ev.sprints = true; }
+    append(p.file, g.actor, ev);
+    const board = boardsOf(ctx, p.w, B.fold(readLedger(ctx, p.w))).find((b) => b.id === id);
+    ctx.json(res, { ok: true, board });
+  },
+  '/api/boards/workflow': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (p.board.self) return fail(ctx, res, 409, SELF_REFUSAL);
+    if (body.sprints != null && typeof body.sprints !== 'boolean') return fail(ctx, res, 400, 'sprints is true or false');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const rowsByStage = {};
+    for (const r of rowsOfBoard(p.fr, p.board, base)) (rowsByStage[r.stage] = rowsByStage[r.stage] || []).push(r.id);
+    const ed = B.applyWorkflowEdit(p.board, body.stages, body.moveRemoved, rowsByStage);
+    if (!ed.ok) return fail(ctx, res, ed.status, ed.error);
+    const ev = { kind: 'workflow', board: p.board.id, stages: ed.workflow, renamed: ed.renamed, moved: ed.moved };
+    if (typeof body.sprints === 'boolean') ev.sprints = body.sprints;
+    append(p.file, g.actor, ev);
+    const board = boardsOf(ctx, p.w, B.fold(readLedger(ctx, p.w))).find((b) => b.id === p.board.id);
+    ctx.json(res, { ok: true, board, moved: ed.moved });
+  },
+  '/api/boards/move': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (p.board.self) return fail(ctx, res, 409, SELF_REFUSAL);
+    const wfOwn = typeof body.id === 'string' ? B.workflowOf(p.board, body.id, p.fr.folded) : p.board.workflow;
+    if (typeof body.to !== 'string' || !wfOwn.some((s) => s.name === body.to)) {
+      return fail(ctx, res, 400, `"${body.to}" is not a stage of this ${wfOwn === p.board.workflow ? 'board' : 'initiative'}'s workflow (${wfOwn.map((s) => s.name).join(', ')})`);
+    }
+    if (body.why != null && (typeof body.why !== 'string' || body.why.length > 500)) return fail(ctx, res, 400, 'why is text of at most 500 characters');
+    if (typeof body.id !== 'string' || !body.id) return fail(ctx, res, 400, 'id is required');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const b0 = base.find((r) => r.id === body.id);
+    if (!b0 || boardIdOf(b0, p.fr.boards, p.fr.folded, p.w) !== p.board.id) return fail(ctx, res, 404, `no initiative ${body.id} on this board`);
+    const before = boardRow(p.board, b0, p.fr.folded);
+    const warnings = B.moveWarnings(p.board, before, before.stage, body.to, { hasSpec: b0.hasSpec });
+    append(p.file, g.actor, { kind: 'move', board: p.board.id, id: body.id, from: before.stage, to: body.to, why: body.why || '', warnings });
+    const row = boardRow(p.board, b0, B.fold(readLedger(ctx, p.w)));
+    ctx.json(res, { ok: true, row, warnings });
+  },
+  '/api/boards/assign': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body, { needBoard: false });
+    if (!p) return;
+    if (typeof body.id !== 'string' || !body.id) return fail(ctx, res, 400, 'id is required');
+    const to = p.fr.boards.find((b) => b.id === body.to);
+    if (!to) return fail(ctx, res, 404, `no board ${body.to} in this workspace`);
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const b0 = base.find((r) => r.id === body.id);
+    if (!b0) return fail(ctx, res, 404, `no work-lane initiative ${body.id} in this workspace`);
+    append(p.file, g.actor, { kind: 'assign', board: boardIdOf(b0, p.fr.boards, p.fr.folded, p.w), id: body.id, to: to.id });
+    ctx.json(res, { ok: true });
+  },
+  '/api/boards/asks/add': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (!ONE_LINE(body.line, 500)) return fail(ctx, res, 400, 'line is one line of 1 to 500 characters');
+    if (body.source != null && !ONE_LINE(body.source, 120)) return fail(ctx, res, 400, 'source is one line of at most 120 characters');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const draft = intake.intakeDraft({ line: body.line, root: p.w.root });
+    const id = `ask-${crypto.randomBytes(5).toString('hex')}`;
+    append(p.file, g.actor, { kind: 'ask', board: p.board.id, ask: id, line: body.line.trim(), source: body.source ? body.source.trim() : null, draft });
+    const ask = B.fold(readLedger(ctx, p.w)).asks.get(id);
+    ctx.json(res, { ok: true, ask: pageAsk(ask), draft });
+  },
+  '/api/boards/asks/accept': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    const a = p.fr.folded.asks.get(body.ask);
+    if (!a || a.board !== p.board.id) return fail(ctx, res, 404, `no ask ${body.ask} on this board`);
+    if (a.state !== 'open') return fail(ctx, res, 409, `ask ${a.id} is ${a.state} already`);
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const input = { title: body.title, lane: body.lane, anchor: body.anchor };
+    for (const k of ['intent', 'id']) if (body[k] != null && body[k] !== '') input[k] = body[k];
+    const r = writer.createInitiative(p.w.root, input, { actor: g.actor });
+    if (!r.ok) return fail(ctx, res, r.status || 400, r.error, { field: r.field || null });
+    const tpl = p.board.defTpl && B.INI_TEMPLATES[p.board.defTpl] ? p.board.defTpl : null;
+    const ownWf = tpl && tpl !== p.board.template ? B.INI_TEMPLATES[tpl].stages.map((x) => ({ name: x.name, cat: x.cat, hint: x.hint || '' })) : null;
+    const stage = (ownWf || p.board.workflow)[0].name;
+    append(p.file, g.actor, { kind: 'ask-accept', board: p.board.id, ask: a.id, initiative: r.id, stage });
+    if (ownWf) append(p.file, g.actor, { kind: 'ini-workflow', board: p.board.id, id: r.id, template: tpl, stages: ownWf, moved: null });
+    rowsLib.invalidate(p.w.root);
+    rowCache.delete(p.w.root);
+    if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(p.w.id);
+    ctx.json(res, { ok: true, initiative: { id: r.id, path: r.path }, stage });
+  },
+  '/api/boards/asks/more': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    const a = p.fr.folded.asks.get(body.ask);
+    if (!a || a.board !== p.board.id) return fail(ctx, res, 404, `no ask ${body.ask} on this board`);
+    if (a.state !== 'open') return fail(ctx, res, 409, `ask ${a.id} is ${a.state} already`);
+    if (body.note != null && body.note !== '' && !ONE_LINE(body.note, 500)) return fail(ctx, res, 400, 'note is one line of at most 500 characters');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    append(p.file, g.actor, { kind: 'ask-more', board: p.board.id, ask: a.id, note: body.note ? String(body.note).trim() : '' });
+    ctx.json(res, { ok: true });
+  },
+  '/api/boards/settings': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (p.board.self) return fail(ctx, res, 409, SELF_REFUSAL);
+    const set = settingsOf(body, p.board);
+    if (set.error) return fail(ctx, res, 400, set.error);
+    if (!Object.keys(set.value).length) return fail(ctx, res, 400, 'say what changes: buildDeliver, jira, offer or defTpl');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const ev = { kind: 'board', op: 'settings', board: p.board.id, ...set.value };
+    const build = 'buildDeliver' in set.value ? set.value.buildDeliver : p.board.build;
+    const jira = 'jira' in set.value ? set.value.jira : p.board.jira;
+    ev.tracker = build && jira ? `Jira · ${jira}` : null;
+    ev.sprints = !!(build && jira);
+    append(p.file, g.actor, ev);
+    const board = boardsOf(ctx, p.w, B.fold(readLedger(ctx, p.w))).find((b) => b.id === p.board.id);
+    ctx.json(res, { ok: true, board });
+  },
+  '/api/boards/ini-workflow': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (p.board.self) return fail(ctx, res, 409, SELF_REFUSAL);
+    if (typeof body.id !== 'string' || !body.id) return fail(ctx, res, 400, 'id is required');
+    if (body.template != null && body.template !== '' && !p.board.offer.includes(body.template)) return fail(ctx, res, 400, `${p.board.name} does not offer the template "${body.template}" (it offers ${p.board.offer.join(', ')})`);
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const b0 = base.find((r) => r.id === body.id);
+    if (!b0 || boardIdOf(b0, p.fr.boards, p.fr.folded, p.w) !== p.board.id) return fail(ctx, res, 404, `no initiative ${body.id} on this board`);
+    const before = boardRow(p.board, b0, p.fr.folded);
+    const stagesIn = Array.isArray(body.stages) ? body.stages.map((x) => (isObj(x) && x.was != null && !before.workflow.some((s) => s.name === x.was) ? { ...x, was: null } : x)) : body.stages;
+    const ed = B.applyIniWorkflow(p.board, B.workflowOf(p.board, body.id, p.fr.folded), before.stage, body.template || null, stagesIn, body.moveTo);
+    if (!ed.ok) return fail(ctx, res, ed.status, ed.error);
+    append(p.file, g.actor, { kind: 'ini-workflow', board: p.board.id, id: body.id, template: ed.template, stages: ed.workflow, renamed: ed.renamed, moved: ed.moved });
+    const row = boardRow(p.board, b0, B.fold(readLedger(ctx, p.w)));
+    ctx.json(res, { ok: true, row, moved: ed.moved });
+  },
+  '/api/boards/tasks/add': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    if (!ONE_LINE(body.title, 200)) return fail(ctx, res, 400, 'title is one line of 1 to 200 characters');
+    if (typeof body.initiative !== 'string' || !body.initiative) return fail(ctx, res, 400, 'initiative is required');
+    if (body.type != null && !['Task', 'Epic'].includes(body.type)) return fail(ctx, res, 400, 'type is Task or Epic');
+    for (const k of ['start', 'due']) if (body[k] != null && body[k] !== '' && !/^\d{4}-\d{2}-\d{2}$/.test(String(body[k]))) return fail(ctx, res, 400, `${k} is a day, YYYY-MM-DD`);
+    if (body.owner != null && body.owner !== '' && !ONE_LINE(body.owner, 80)) return fail(ctx, res, 400, 'owner is one line of at most 80 characters');
+    if (body.epic != null && body.epic !== '' && !ONE_LINE(body.epic, 80)) return fail(ctx, res, 400, 'epic is one line of at most 80 characters');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const base = needRows(ctx, res, p.w);
+    if (!base) return;
+    const b0 = base.find((r) => r.id === body.initiative);
+    if (!b0 || boardIdOf(b0, p.fr.boards, p.fr.folded, p.w) !== p.board.id) return fail(ctx, res, 404, `no initiative ${body.initiative} on this board`);
+    const id = `task-${crypto.randomBytes(5).toString('hex')}`;
+    const start = body.start || B.shiftDay(today(), 1);
+    const due = body.due || B.shiftDay(start, 7);
+    append(p.file, g.actor, { kind: 'task', board: p.board.id, task: id, type: body.type || 'Task', initiative: body.initiative, title: body.title.trim(), epic: body.epic ? String(body.epic).trim() : null,
+      owner: body.owner ? String(body.owner).trim() : actorLib.pageName(g.actor.by), state: 'To do', start, due });
+    const t = B.taskOf(B.fold(readLedger(ctx, p.w)), id);
+    ctx.json(res, { ok: true, item: B.rollupItems([B.taskItem(t)])[0] });
+  },
+  '/api/boards/tasks/state': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    const t = B.taskOf(p.fr.folded, body.task);
+    if (!t || t.board !== p.board.id) return fail(ctx, res, 404, `no PMOS task ${body.task} on this board`);
+    if (!B.TASK_STATES.includes(body.state)) return fail(ctx, res, 400, `state is one of ${B.TASK_STATES.join(', ')}`);
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    append(p.file, g.actor, { kind: 'task-update', board: p.board.id, task: t.id, state: body.state, why: 'status move' });
+    const t2 = B.taskOf(B.fold(readLedger(ctx, p.w)), t.id);
+    ctx.json(res, { ok: true, item: B.rollupItems([B.taskItem(t2)])[0] });
+  },
+  '/api/boards/tasks/reschedule': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    const t = B.taskOf(p.fr.folded, body.task);
+    if (!t || t.board !== p.board.id) return fail(ctx, res, 404, `no PMOS task ${body.task} on this board`);
+    const days = Number(body.days);
+    if (!Number.isInteger(days) || days === 0 || Math.abs(days) > 730) return fail(ctx, res, 400, 'days is a whole number of days, not 0, at most 730 either way');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    const start = B.shiftDay(t.start || B.shiftDay(t.due || today(), -7), days);
+    const due = B.shiftDay(t.due || B.shiftDay(t.start || today(), 7), days);
+    append(p.file, g.actor, { kind: 'task-update', board: p.board.id, task: t.id, start, due, why: `rescheduled ${days > 0 ? '+' : ''}${days} days` });
+    const t2 = B.taskOf(B.fold(readLedger(ctx, p.w)), t.id);
+    ctx.json(res, { ok: true, item: B.rollupItems([B.taskItem(t2)])[0] });
+  },
+  '/api/boards/asks/decline': (ctx, res, body, g) => {
+    const p = postFrame(ctx, res, body);
+    if (!p) return;
+    const a = p.fr.folded.asks.get(body.ask);
+    if (!a || a.board !== p.board.id) return fail(ctx, res, 404, `no ask ${body.ask} on this board`);
+    if (a.state !== 'open') return fail(ctx, res, 409, `ask ${a.id} is ${a.state} already`);
+    if (!ONE_LINE(body.why, 500)) return fail(ctx, res, 400, 'a decline needs a reason (why) of 1 to 500 characters');
+    if (!p.file) return fail(ctx, res, 409, NO_STATE);
+    append(p.file, g.actor, { kind: 'ask-decline', board: p.board.id, ask: a.id, why: body.why.trim() });
+    ctx.json(res, { ok: true });
+  },
+};
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  if (req.method === 'GET') {
+    if (p === '/api/boards') { ctx.json(res, portfolio(ctx)); return true; }
+    const fn = READS[p];
+    if (!fn) return fail(ctx, res, 404, 'not found');
+    fn(ctx, res, url);
+    return true;
+  }
+  if (req.method !== 'POST') return fail(ctx, res, 405, 'GET or POST only');
+  const fn = WRITES[p];
+  if (!fn) return fail(ctx, res, 404, 'not found');
+  const got = await ctx.readJson(req);
+  if (!got.ok) return fail(ctx, res, 400, 'invalid JSON body');
+  const body = got.body;
+  if (!isObj(body)) return fail(ctx, res, 400, 'the body must be a JSON object');
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) return fail(ctx, res, g.status, g.error);
+  fn(ctx, res, body, g);
+  return true;
+}
+
+/** The board of each initiative of a workspace, for other routes (Reports): { boards: [{ id, title }], of(id) → board id }.
+ * Rows still being read fall back to the ledger's assignment, else the default board. */
+function boardIndex(ctx, w) {
+  const fr = frameFor(ctx, w);
+  const got = baseRows(w);
+  const byId = new Map();
+  if (got.ok) for (const r of got.rows) byId.set(r.id, boardIdOf(r, fr.boards, fr.folded, w));
+  return { boards: fr.boards.map((b) => ({ id: b.id, title: b.name })), of: (id) => byId.get(id) || boardIdOf({ id }, fr.boards, fr.folded, w) };
+}
+
+module.exports = { prefixes: ['/api/boards'], handle, boardIndex, boardsOf, baseRows, boardRow, portfolio, SELF_REFUSAL, NO_STATE };