create-pmos 0.134.0 → 0.136.0

package/workspace/lib/engine/boards.js

@@ -0,0 +1,542 @@
+'use strict';
+/* boards.js — the model of console3 Initiatives boards and workflows (c3-initiative-boards; PRD "Model", "State").
+ * Pure: no file, no network, no clock read unless the caller passes none. workspace/lib/routes-boards.js does the I/O.
+ *
+ *   CATEGORIES · WORKFLOW_TEMPLATES · TOOLS · SELF_LADDER · READING_CAT
+ *   templateWorkflow(name)                      → a fresh copy of a template's stages [{ name, cat, hint }]
+ *   isTemplateEdited(template, workflow)        → true when the stages differ from the template's (names or categories)
+ *   fold(events)                                → { boards, moves, assigns, asks, stages, events }
+ *   readingOf(nineStages, { accepted })         → the nine-stage key the reading names (scripts/nine-stages.js output)
+ *   deriveStage(board, reading)                 → the stage name a reading maps to on this board's workflow
+ *   stageOf(board, id, reading, folded)         → { stage, source: 'move'|'derived' }
+ *   moveWarnings(board, row, from, to, facts)   → ['Skipped Plan', 'No spec yet', 'No anchor']
+ *   cardWarnings(board, row, facts)             → the warnings a card shows where it stands now (no Skipped)
+ *   applyWorkflowEdit(board, stages, moveRemoved, rowsByStage) → { ok, workflow, renamed, removed, moved } | { ok:false, status, error }
+ *   filterRows(rows, query)                     → { total, offset, limit, rows, facets }
+ *   health(rows)                                → 'ok' | 'warn' | 'bad'
+ *   counts(rows, workflow)                      → { total, open, byCat, byStage, byStatus, risk, late }
+ *   sprintsOf(snapshots, onBoard)               → { source, readAt, sprints }
+ *   INI_TEMPLATES · isBuildStage · templateBuilds · boardSettings(board)   the per-initiative workflows (console3-initiatives-parity)
+ *   workflowOf(board, id, folded)               → the stages an initiative runs: its own (ini-workflow), else the board's
+ *   applyIniWorkflow(board, wfNow, stage, template, stages, moveTo) → { ok, template, workflow, moved } | { ok:false, status, error }
+ *   taskOf(folded, id) · TASK_STATES · shiftDay(iso, days)   PMOS tasks on a board
+ *   itemStatus(status, category) · taskItem(task) · rollupItems(items)   work items (PMOS tasks and Jira items) in one shape
+ *
+ * THE LEDGER. One append-only file per repository, <state dir>/boards.jsonl. A line is { at, by, kind, board, ... }:
+ *   board        { op: 'create'|'settings', name?, domain?, template?, workflow?, sprints?, tracker? }
+ *   workflow     { stages: [{ name, cat, hint }], renamed: { old: new }, moved: [{ id, from, to }], sprints? }
+ *   move         { id, from, to, why, warnings }
+ *   assign       { id, to }                               (`board` is the board it left, or null)
+ *   ask          { ask, line, source, draft }
+ *   ask-accept   { ask, initiative, stage }
+ *   ask-decline  { ask, why }
+ *   ask-more     { ask, note }                            the asker is prompted for more detail; the ask stays open
+ *   board op 'create'|'settings' may also carry { buildDeliver, jira, offer, defTpl } (Build and deliver, true when missing; the Jira project key, the templates
+ *                new initiatives may pick, the template they start with)
+ *   ini-workflow { id, template, stages: [{ name, cat, hint }], moved: { from, to } | null }   one initiative's own workflow
+ *   task         { task, type: Task|Epic, initiative, title, epic, owner, state, start, due }  a PMOS task (or PMOS epic) on the board
+ *   task-update  { task, state?, start?, due?, why }                                           a status move or a reschedule
+ * Nothing is deleted. A line that is not an object with a known kind is skipped.
+ *
+ * STAGE OF AN INITIATIVE on a team board: the last move recorded for it on that board (a workflow edit's `moved` and an
+ * ask-accept count as moves; a rename carries the move along). With none, it is derived from the nine-stage reading:
+ * discover|ideate → first Discover stage; strategize|prioritize|plan → first Plan; build|deliver → first Do;
+ * monitor|evaluate → first Learn. A workflow with no stage in that category uses the nearest earlier category, else
+ * its first stage.
+ */
+
+const CATEGORIES = Object.freeze(['Discover', 'Plan', 'Do', 'Learn']);
+
+const st = (name, cat, hint) => Object.freeze({ name, cat, hint });
+const WORKFLOW_TEMPLATES = Object.freeze({
+  product: Object.freeze([
+    st('Discover', 'Discover', 'Find the problem worth solving and the evidence for it.'),
+    st('Plan', 'Plan', 'Write the spec, agree the done-criteria and place it on the roadmap.'),
+    st('Build & Deliver', 'Do', 'Build, test and release.'),
+    st('Monitor & Evaluate', 'Learn', 'Read the outcome against the anchor and decide what is next.'),
+  ]),
+  project: Object.freeze([
+    st('Plan', 'Plan', 'Agree the scope, the owner and the dates.'),
+    st('Execute', 'Do', 'Do the work and track it.'),
+    st('Close', 'Learn', 'Confirm the result and record what was learned.'),
+  ]),
+  simple: Object.freeze([
+    st('To do', 'Plan', 'Not started.'),
+    st('Doing', 'Do', 'In progress.'),
+    st('Done', 'Learn', 'Finished.'),
+  ]),
+});
+
+/* The workflows an initiative can run (console3-initiatives-parity). product, project and simple are the board templates;
+ * fix, research and content are initiative-only. A template with a Build or Deliver stage needs a board with Build and
+ * deliver on. `kind` picks the stage tools (product, project, simple). */
+const INI_TEMPLATES = Object.freeze({
+  product: Object.freeze({ name: 'Product', kind: 'product', use: 'Product work that ships: discovery through to evaluating what shipped.', stages: WORKFLOW_TEMPLATES.product }),
+  fix: Object.freeze({ name: 'Quick fix', kind: 'product', use: 'A small, known change: plan it, build it, ship it, check it.', stages: Object.freeze([st('Plan', 'Plan', ''), st('Build & Deliver', 'Do', ''), st('Evaluate', 'Learn', '')]) }),
+  research: Object.freeze({ name: 'Research only', kind: 'product', use: 'Learn before committing. Nothing gets built in this initiative.', stages: Object.freeze([st('Discover', 'Discover', ''), st('Plan', 'Plan', ''), st('Evaluate', 'Learn', '')]) }),
+  content: Object.freeze({ name: 'Content and launch', kind: 'project', use: 'Pages, campaigns and launches that a team or an agency produces.', stages: Object.freeze([st('Discover', 'Discover', ''), st('Plan', 'Plan', ''), st('Produce', 'Do', ''), st('Launch', 'Do', ''), st('Evaluate', 'Learn', '')]) }),
+  project: Object.freeze({ name: 'Project', kind: 'project', use: 'Someone who only manages a project: plan it, run it, close it.', stages: WORKFLOW_TEMPLATES.project }),
+  simple: Object.freeze({ name: 'Simple', kind: 'simple', use: 'A plain to-do flow for small or personal work.', stages: WORKFLOW_TEMPLATES.simple }),
+});
+const isBuildStage = (s) => /^(build|deliver)/i.test(String((s && s.name) || s || ''));
+const templateBuilds = (k) => !!INI_TEMPLATES[k] && INI_TEMPLATES[k].stages.some(isBuildStage);
+/** A board's Build and deliver settings, with the defaults of a board that never set them: buildDeliver is true when the
+ * ledger line does not carry it (the stage-records thread reads the same field the same way), every template the board may run is offered, and new initiatives start with
+ * the board's own template. */
+function boardSettings(board) {
+  const b = board || {};
+  const build = typeof b.buildDeliver === 'boolean' ? b.buildDeliver : true;
+  const allowed = Object.keys(INI_TEMPLATES).filter((k) => build || !templateBuilds(k));
+  let offer = Array.isArray(b.offer) ? b.offer.filter((k) => allowed.includes(k)) : allowed;
+  if (!offer.length) offer = allowed;
+  const tpl = INI_TEMPLATES[b.template] ? b.template : 'product';
+  let defTpl = typeof b.defTpl === 'string' && offer.includes(b.defTpl) ? b.defTpl : (offer.includes(tpl) ? tpl : offer[0]);
+  if (!defTpl) defTpl = 'simple';
+  const jira = build ? (typeof b.jira === 'string' && b.jira ? b.jira : (/^Jira · (.+)$/.exec(b.tracker || '') || [])[1] || null) : null;
+  return { build, jira, offer, defTpl };
+}
+
+/* The PMOS-self board: the nine stage names of scripts/nine-stages.js, read-only, each in its category. */
+const READING_CAT = Object.freeze({
+  discover: 'Discover', ideate: 'Discover',
+  strategize: 'Plan', prioritize: 'Plan', plan: 'Plan',
+  build: 'Do', deliver: 'Do',
+  monitor: 'Learn', evaluate: 'Learn',
+});
+const NINE = ['discover', 'ideate', 'strategize', 'prioritize', 'plan', 'build', 'deliver', 'monitor', 'evaluate'];
+const NINE_LABEL = { discover: 'Discover', ideate: 'Ideate', strategize: 'Strategize', prioritize: 'Prioritize', plan: 'Plan', build: 'Build', deliver: 'Deliver', monitor: 'Monitor', evaluate: 'Evaluate' };
+const SELF_LADDER = Object.freeze(NINE.map((k) => st(NINE_LABEL[k], READING_CAT[k], 'Derived by scripts/workflow-state.js; not moved by hand.')));
+
+/* The stage tools of each category, per template: the initiative page shows these first and the rest behind
+ * "More tools". `id` names the page section or tool the UI opens. */
+const T = (id, label) => Object.freeze({ id, label });
+const TOOLS = Object.freeze({
+  product: {
+    Discover: [T('ideas', 'Ideas'), T('hypotheses', 'Hypotheses'), T('notes', 'Notes')],
+    Plan: [T('prd', 'PRD'), T('rubric', 'Done-criteria'), T('breakdown', 'Breakdown'), T('placement', 'Roadmap place')],
+    Do: [T('breakdown', 'Breakdown'), T('tickets', 'Tickets'), T('releases', 'Releases')],
+    Learn: [T('measurements', 'Measurements'), T('evaluation', 'Evaluation'), T('history', 'History')],
+  },
+  project: {
+    Discover: [T('notes', 'Notes')],
+    Plan: [T('brief', 'Brief'), T('breakdown', 'Breakdown'), T('timeline', 'Timeline')],
+    Do: [T('breakdown', 'Breakdown'), T('tickets', 'Tickets'), T('timeline', 'Timeline')],
+    Learn: [T('notes', 'Notes'), T('history', 'History')],
+  },
+  simple: {
+    Discover: [T('notes', 'Notes')],
+    Plan: [T('notes', 'Notes')],
+    Do: [T('breakdown', 'Breakdown')],
+    Learn: [T('history', 'History')],
+  },
+  pmos: {
+    Discover: [T('ideas', 'Ideas'), T('notes', 'Notes')],
+    Plan: [T('prd', 'PRD'), T('rubric', 'Done-criteria'), T('breakdown', 'Breakdown')],
+    Do: [T('breakdown', 'Breakdown'), T('tickets', 'Tickets'), T('releases', 'Releases')],
+    Learn: [T('evaluation', 'Evaluation'), T('measurements', 'Measurements'), T('history', 'History')],
+  },
+});
+
+const STATUSES = Object.freeze(['on track', 'at risk', 'late', 'done']);
+const VIEWS = Object.freeze(['now', 'mine', 'risk', 'noowner', 'all']);
+const KINDS = new Set(['board', 'workflow', 'move', 'assign', 'ask', 'ask-accept', 'ask-decline', 'ask-more', 'ini-workflow', 'task', 'task-update']);
+const TASK_STATES = Object.freeze(['To do', 'In progress', 'In review', 'Done']);
+
+const copyStages = (stages) => stages.map((s) => ({ name: s.name, cat: s.cat, hint: s.hint || '' }));
+function templateWorkflow(name) {
+  const t = WORKFLOW_TEMPLATES[name];
+  return t ? copyStages(t) : null;
+}
+function isTemplateEdited(template, workflow) {
+  const t = WORKFLOW_TEMPLATES[template];
+  if (!t || !Array.isArray(workflow)) return false;
+  if (t.length !== workflow.length) return true;
+  return t.some((s, i) => s.name !== workflow[i].name || s.cat !== workflow[i].cat);
+}
+
+const key = (board, id) => `${board}\u0000${id}`;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/** Fold the ledger lines (objects or JSON strings), oldest first. */
+function fold(events) {
+  const boards = new Map();        // board id → { id, name?, domain?, template?, workflow?, sprints?, tracker?, created }
+  const moves = [];                // every move-like event, oldest first: { at, by, board, id, from, to, why, warnings, via }
+  const assigns = new Map();       // initiative id → board id
+  const asks = new Map();          // ask id → { id, board, line, source, draft, at, by, state, initiative, stage, why, closedAt }
+  const stages = new Map();        // key(board, id) → stage name (the last move)
+  const iniWorkflows = new Map();  // key(board, id) → { template, stages } (the initiative's own workflow)
+  const tasks = new Map();         // task id → { id, board, initiative, title, epic, owner, state, start, due, at, by, history }
+  const list = [];
+  for (let e of Array.isArray(events) ? events : []) {
+    if (typeof e === 'string') { try { e = JSON.parse(e); } catch { continue; } }
+    if (!isObj(e) || !KINDS.has(e.kind)) continue;
+    list.push(e);
+    const b = typeof e.board === 'string' ? e.board : null;
+    if (e.kind === 'board' && b) {
+      const cur = boards.get(b) || { id: b, created: null };
+      if (e.op === 'create' && !cur.created) cur.created = { at: e.at || null, by: e.by || null };
+      for (const k of ['name', 'domain', 'template', 'sprints', 'tracker', 'buildDeliver', 'jira', 'offer', 'defTpl']) if (k in e) cur[k] = e[k];
+      if (Array.isArray(e.workflow)) cur.workflow = copyStages(e.workflow);
+      boards.set(b, cur);
+    } else if (e.kind === 'workflow' && b && Array.isArray(e.stages)) {
+      const cur = boards.get(b) || { id: b, created: null };
+      cur.workflow = copyStages(e.stages);
+      if ('sprints' in e) cur.sprints = !!e.sprints;
+      boards.set(b, cur);
+      const renamed = isObj(e.renamed) ? e.renamed : {};
+      if (Object.keys(renamed).length) {
+        for (const [k, v] of stages) if (k.startsWith(b + '\u0000') && renamed[v]) stages.set(k, renamed[v]);
+      }
+      for (const m of Array.isArray(e.moved) ? e.moved : []) {
+        if (!m || typeof m.id !== 'string' || typeof m.to !== 'string') continue;
+        stages.set(key(b, m.id), m.to);
+        moves.push({ at: e.at || null, by: e.by || null, board: b, id: m.id, from: m.from || null, to: m.to, why: 'stage removed', warnings: [], via: 'workflow' });
+      }
+    } else if (e.kind === 'move' && b && typeof e.id === 'string' && typeof e.to === 'string') {
+      stages.set(key(b, e.id), e.to);
+      moves.push({ at: e.at || null, by: e.by || null, board: b, id: e.id, from: e.from || null, to: e.to, why: e.why || '', warnings: Array.isArray(e.warnings) ? e.warnings : [], via: 'move' });
+    } else if (e.kind === 'assign' && typeof e.id === 'string' && typeof e.to === 'string') {
+      assigns.set(e.id, e.to);
+    } else if (e.kind === 'ask' && b && typeof e.ask === 'string' && !asks.has(e.ask)) {
+      asks.set(e.ask, { id: e.ask, board: b, line: String(e.line || ''), source: e.source || null, draft: e.draft || null, at: e.at || null, by: e.by || null, state: 'open', initiative: null, stage: null, why: null, closedAt: null });
+    } else if (e.kind === 'ask-accept' && typeof e.ask === 'string' && asks.has(e.ask)) {
+      const a = asks.get(e.ask);
+      if (a.state !== 'open') continue;
+      Object.assign(a, { state: 'accepted', initiative: e.initiative || null, stage: e.stage || null, closedAt: e.at || null });
+      if (typeof e.initiative === 'string') {
+        assigns.set(e.initiative, a.board);
+        if (typeof e.stage === 'string') {
+          stages.set(key(a.board, e.initiative), e.stage);
+          moves.push({ at: e.at || null, by: e.by || null, board: a.board, id: e.initiative, from: null, to: e.stage, why: 'accepted from triage', warnings: [], via: 'ask-accept' });
+        }
+      }
+    } else if (e.kind === 'ask-more' && typeof e.ask === 'string' && asks.has(e.ask)) {
+      const a = asks.get(e.ask);
+      if (a.state === 'open') { a.needMore = true; a.moreNote = typeof e.note === 'string' ? e.note : ''; a.moreAt = e.at || null; }
+    } else if (e.kind === 'ini-workflow' && b && typeof e.id === 'string' && Array.isArray(e.stages) && e.stages.length) {
+      const k = key(b, e.id);
+      iniWorkflows.set(k, { template: typeof e.template === 'string' ? e.template : null, stages: copyStages(e.stages) });
+      const renamed = isObj(e.renamed) ? e.renamed : {};
+      if (stages.has(k) && renamed[stages.get(k)]) stages.set(k, renamed[stages.get(k)]);
+      if (isObj(e.moved) && typeof e.moved.to === 'string') {
+        stages.set(k, e.moved.to);
+        moves.push({ at: e.at || null, by: e.by || null, board: b, id: e.id, from: e.moved.from || null, to: e.moved.to, why: 'stage removed from its workflow', warnings: [], via: 'ini-workflow' });
+      }
+    } else if (e.kind === 'task' && b && typeof e.task === 'string' && typeof e.initiative === 'string' && !tasks.has(e.task)) {
+      tasks.set(e.task, { id: e.task, board: b, initiative: e.initiative, kind: e.type === 'Epic' ? 'Epic' : 'Task', title: String(e.title || ''), epic: typeof e.epic === 'string' && e.epic ? e.epic : null,
+        owner: typeof e.owner === 'string' && e.owner ? e.owner : null, state: TASK_STATES.includes(e.state) ? e.state : 'To do',
+        start: typeof e.start === 'string' ? e.start : null, due: typeof e.due === 'string' ? e.due : null, at: e.at || null, by: e.by || null, history: [] });
+    } else if (e.kind === 'task-update' && typeof e.task === 'string' && tasks.has(e.task)) {
+      const t = tasks.get(e.task);
+      if (TASK_STATES.includes(e.state)) t.state = e.state;
+      if (typeof e.start === 'string') t.start = e.start;
+      if (typeof e.due === 'string') t.due = e.due;
+      t.history.push({ at: e.at || null, by: e.by || null, state: e.state || null, start: e.start || null, due: e.due || null, why: e.why || '' });
+    } else if (e.kind === 'ask-decline' && typeof e.ask === 'string' && asks.has(e.ask)) {
+      const a = asks.get(e.ask);
+      if (a.state !== 'open') continue;
+      Object.assign(a, { state: 'declined', why: e.why || '', closedAt: e.at || null });
+    }
+  }
+  return { boards, moves, assigns, asks, stages, iniWorkflows, tasks, events: list };
+}
+
+/** The stages an initiative runs on a board: its own workflow when one is recorded, else the board's. */
+function workflowOf(board, id, folded) {
+  if (board && board.self) return (board.workflow || []);
+  const own = folded && folded.iniWorkflows ? folded.iniWorkflows.get(key(board.id, id)) : null;
+  return own ? own.stages : ((board && board.workflow) || []);
+}
+/** The template of an initiative's own workflow record, or null when it runs the board's workflow. */
+function templateOf(board, id, folded) {
+  const own = folded && folded.iniWorkflows ? folded.iniWorkflows.get(key(board.id, id)) : null;
+  return own ? own.template : null;
+}
+const taskOf = (folded, id) => (folded && folded.tasks ? folded.tasks.get(id) || null : null);
+/* ── work items: PMOS tasks and Jira items, one shape ── */
+const ITEM_PROGRESS = Object.freeze({ 'To do': 0, 'In progress': 0.45, 'In review': 0.8, Done: 1 });
+/** A Jira status (and its category) as one of the four item statuses. */
+function itemStatus(status, category) {
+  const s = String(status || '');
+  if (category === 'done' || /\b(done|closed|resolved|released)\b/i.test(s)) return 'Done';
+  if (/review|\bqa\b|test/i.test(s)) return 'In review';
+  if (category === 'doing' || /progress|doing|block|started/i.test(s)) return 'In progress';
+  return 'To do';
+}
+/** A PMOS task as a work item. */
+function taskItem(t) {
+  return { uid: t.id, key: '', kind: t.kind === 'Epic' ? 'Epic' : 'Task', src: 'pmos', title: t.title, status: t.state, blocked: false, owner: t.owner || null,
+    ini: t.initiative, epic: t.epic || null, start: t.start || null, end: t.due || null, ref: t.id, board: t.board };
+}
+/** Progress per item, and an epic's status, progress, blocked flag and dates rolled up from its items. Mutates and returns items. */
+function rollupItems(items) {
+  for (const w of items) w.progress = ITEM_PROGRESS[w.status] || 0;
+  for (const e of items.filter((w) => w.kind === 'Epic')) {
+    const kids = items.filter((w) => w.epic && w.epic === e.uid);
+    if (!kids.length) continue;
+    e.progress = Math.round((kids.reduce((n, w) => n + w.progress, 0) / kids.length) * 100) / 100;
+    e.status = kids.every((w) => w.status === 'Done') ? 'Done' : kids.some((w) => w.status !== 'To do') ? 'In progress' : 'To do';
+    e.blocked = kids.some((w) => w.blocked);
+    const starts = kids.map((w) => w.start).filter(Boolean).sort();
+    const ends = kids.map((w) => w.end).filter(Boolean).sort();
+    if (!e.start && starts.length) e.start = starts[0];
+    if (!e.end && ends.length) e.end = ends[ends.length - 1];
+  }
+  return items;
+}
+
+/** An ISO day moved by whole days ('2026-10-11', 3 → '2026-10-14'). */
+function shiftDay(iso, days) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso || ''));
+  if (!m) return null;
+  const d = new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]) + Number(days || 0)));
+  return d.toISOString().slice(0, 10);
+}
+
+/** The nine-stage key a reading names: the current stage, else (accepted) evaluate, else the last done, else the first used. */
+function readingOf(nine, { accepted = false } = {}) {
+  const list = Array.isArray(nine) ? nine : [];
+  const cur = list.find((s) => s && s.status === 'current');
+  if (cur) return cur.key;
+  if (accepted) return 'evaluate';
+  const done = list.filter((s) => s && s.status === 'done');
+  if (done.length) return done[done.length - 1].key;
+  const used = list.find((s) => s && s.status !== 'skipped');
+  return used ? used.key : 'discover';
+}
+
+function deriveStage(board, reading) {
+  const wf = (board && board.workflow) || [];
+  if (!wf.length) return null;
+  const cat = READING_CAT[reading] || 'Discover';
+  for (let i = CATEGORIES.indexOf(cat); i >= 0; i--) {
+    const s = wf.find((x) => x.cat === CATEGORIES[i]);
+    if (s) return s.name;
+  }
+  return wf[0].name;
+}
+
+function stageOf(board, id, reading, folded) {
+  if (board && board.self) return { stage: NINE_LABEL[reading] || NINE_LABEL.discover, source: 'derived' };
+  const wf = workflowOf(board, id, folded);
+  const moved = folded && folded.stages ? folded.stages.get(key(board.id, id)) : null;
+  if (moved && wf.some((s) => s.name === moved)) return { stage: moved, source: 'move' };
+  return { stage: deriveStage({ workflow: wf }, reading), source: 'derived' };
+}
+
+const catOf = (board, stage) => { const s = ((board && board.workflow) || []).find((x) => x.name === stage); return s ? s.cat : null; };
+
+/** Validate one initiative's workflow edit. wfNow = the stages it runs now; stage = where it stands. A removed current stage
+ * needs moveTo (a stage of the new workflow); a renamed one carries the initiative along. A Build or Deliver stage needs a
+ * board with Build and deliver on. */
+function applyIniWorkflow(board, wfNow, stage, template, stages, moveTo) {
+  const bad = (error, status = 400) => ({ ok: false, status, error });
+  if (board && board.self) return bad('PMOS keeps its derived ladder: its stages come from scripts/workflow-state.js and are not edited here', 409);
+  if (template != null && template !== '' && !INI_TEMPLATES[template]) return bad(`template must be one of ${Object.keys(INI_TEMPLATES).join(', ')}`);
+  const ed = applyWorkflowEdit({ workflow: wfNow }, stages, null, {});
+  if (!ed.ok) return ed;
+  if (!boardSettings(board).build && ed.workflow.some(isBuildStage)) return bad(`Build and Deliver stages need a board with Build and deliver on; ${(board && board.name) || 'this board'} has it off`);
+  let moved = null;
+  if (stage && !ed.workflow.some((s) => s.name === stage) && !ed.renamed[stage]) {
+    if (typeof moveTo !== 'string' || !ed.workflow.some((s) => s.name === moveTo)) return bad(`the initiative is in "${stage}", which the new workflow removes: say which stage it moves to (moveTo)`);
+    moved = { from: stage, to: moveTo };
+  }
+  return { ok: true, template: template || null, workflow: ed.workflow, renamed: ed.renamed, moved };
+}
+
+/** Order rules: warnings, never a block. facts = { hasSpec }. */
+function moveWarnings(board, row, from, to, facts = {}) {
+  const wf = (row && Array.isArray(row.workflow) && row.workflow.length ? row.workflow : (board && board.workflow)) || [];
+  const catTo = (wf.find((s) => s.name === to) || {}).cat || null;
+  const out = [];
+  const a = wf.findIndex((s) => s.name === from);
+  const b = wf.findIndex((s) => s.name === to);
+  if (a >= 0 && b > a + 1) for (let i = a + 1; i < b; i++) out.push(`Skipped ${wf[i].name}`);
+  if (row && row.lane === 'feature' && catTo === 'Do' && !facts.hasSpec) out.push('No spec yet');
+  if (row && !row.anchor) out.push('No anchor');
+  return out;
+}
+function cardWarnings(board, row, facts = {}) {
+  return moveWarnings(board, row, null, row && row.stage, facts);
+}
+
+const NAME_MAX = 40;
+/** Validate a workflow edit and say what it moves. rowsByStage: { stageName: [initiative id] } of the board now. */
+function applyWorkflowEdit(board, stages, moveRemoved, rowsByStage) {
+  const bad = (error, status = 400) => ({ ok: false, status, error });
+  if (board && board.self) return bad('PMOS keeps its derived ladder: its stages come from scripts/workflow-state.js and are not edited here', 409);
+  if (!Array.isArray(stages) || !stages.length) return bad('a workflow needs at least one stage');
+  const old = ((board && board.workflow) || []).map((s) => s.name);
+  const next = [];
+  const seen = new Set();
+  const renamed = {};
+  const wasSeen = new Set();
+  for (const [i, s] of stages.entries()) {
+    if (!isObj(s)) return bad(`stage ${i + 1} must be { name, cat }`);
+    const name = typeof s.name === 'string' ? s.name.trim().replace(/\s+/g, ' ') : '';
+    if (!name) return bad(`stage ${i + 1} needs a name`);
+    if (name.length > NAME_MAX || /[\u0000-\u001f]/.test(name)) return bad(`stage ${i + 1}: a name is one line of at most ${NAME_MAX} characters`);
+    if (seen.has(name.toLowerCase())) return bad(`two stages are named "${name}"; names must be unique`);
+    seen.add(name.toLowerCase());
+    if (!CATEGORIES.includes(s.cat)) return bad(`stage "${name}": cat must be one of ${CATEGORIES.join(', ')}`);
+    if (s.hint != null && (typeof s.hint !== 'string' || s.hint.length > 200)) return bad(`stage "${name}": hint is text of at most 200 characters`);
+    if (s.was != null) {
+      if (typeof s.was !== 'string' || !old.includes(s.was)) return bad(`stage "${name}": was must name a current stage (${old.join(', ')})`);
+      if (wasSeen.has(s.was)) return bad(`two stages say they were "${s.was}"`);
+      wasSeen.add(s.was);
+      if (s.was !== name) renamed[s.was] = name;
+    }
+    next.push({ name, cat: s.cat, hint: typeof s.hint === 'string' ? s.hint : '', was: s.was == null ? null : s.was });
+  }
+  const kept = new Set();
+  for (const s of next) kept.add(s.was != null ? s.was : s.name);
+  // a stage named like an old one with no `was` keeps it, unless another stage already carries that old one by `was`
+  const removed = old.filter((n) => !kept.has(n));
+  const targets = new Set(next.map((s) => s.name));
+  const mr = isObj(moveRemoved) ? moveRemoved : {};
+  const moved = [];
+  for (const r of removed) {
+    const held = (rowsByStage && rowsByStage[r]) || [];
+    if (!held.length) continue;
+    const to = mr[r];
+    if (typeof to !== 'string' || !to) return bad(`"${r}" holds ${held.length} initiative(s): say where they go (moveRemoved["${r}"])`);
+    if (!targets.has(to)) return bad(`moveRemoved["${r}"] must name a stage of the new workflow, not "${to}"`);
+    for (const id of held) moved.push({ id, from: r, to });
+  }
+  return { ok: true, workflow: next.map(({ name, cat, hint }) => ({ name, cat, hint })), renamed, removed, moved };
+}
+
+// ── backlog ─────────────────────────────────────────────────────────────────────────────────────────
+const HZ = { now: 0, next: 1, later: 2 };
+const SORTS = ['rank', 'id', 'title', 'stage', 'status', 'owner', 'horizon', 'end', 'start', 'updated', 'progress'];
+const listParam = (v) => (v == null || v === '' ? null : String(v).split(',').map((x) => x.trim()).filter(Boolean));
+const lc = (v) => String(v == null ? '' : v).toLowerCase();
+
+function viewFilter(view, me) {
+  const mine = new Set([lc(me), lc(me ? `pm:${me}` : '')].filter(Boolean));
+  switch (view) {
+    case 'now': return (r) => (r.horizon === 'now' || r.horizon === 'next') && r.status !== 'done';
+    case 'mine': return (r) => !!r.owner && mine.has(lc(r.owner)) && r.status !== 'done';
+    case 'risk': return (r) => r.status === 'at risk' || r.status === 'late';
+    case 'noowner': return (r) => !r.owner && r.status !== 'done';
+    default: return () => true;
+  }
+}
+
+function facetOf(rows, field) {
+  const m = new Map();
+  for (const r of rows) { const k = r[field] == null ? '' : String(r[field]); m.set(k, (m.get(k) || 0) + 1); }
+  // { value: count }, most first; a missing value counts under 'none', the word the filters take for it.
+  return Object.fromEntries([...m.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([k, n]) => [k === '' ? 'none' : k, n]));
+}
+
+/**
+ * query = { q, stage, status, owner, horizon, anchor (each a comma list), view, sort ('-' prefix = descending), offset,
+ * limit, me, stages (the workflow's stage names, for the stage sort) }. Facets count the rows after the view and the
+ * search, before the stage/status/owner/horizon/anchor filters, so each filter shows what choosing it would give.
+ */
+function filterRows(rows, query = {}) {
+  const view = VIEWS.includes(query.view) ? query.view : 'now';
+  const q = lc(query.q).trim();
+  let base = (rows || []).filter(viewFilter(view, query.me));
+  if (q) base = base.filter((r) => lc(r.title).includes(q) || lc(r.id).includes(q) || lc(r.anchor).includes(q) || lc(r.owner).includes(q));
+  const facets = { stage: facetOf(base, 'stage'), status: facetOf(base, 'status'), owner: facetOf(base, 'owner'), horizon: facetOf(base, 'horizon'), anchor: facetOf(base, 'anchor'), cat: facetOf(base, 'cat') };
+  let out = base;
+  for (const f of ['stage', 'status', 'owner', 'horizon', 'anchor', 'cat']) {
+    const want = listParam(query[f]);
+    if (!want) continue;
+    const set = new Set(want.map(lc));
+    out = out.filter((r) => set.has(r[f] == null ? 'none' : lc(r[f])));
+  }
+  let sort = typeof query.sort === 'string' && query.sort ? query.sort : 'rank';
+  const desc = sort.startsWith('-');
+  if (desc) sort = sort.slice(1);
+  if (!SORTS.includes(sort)) sort = 'rank';
+  const stageIdx = new Map((query.stages || []).map((s, i) => [s, i]));
+  const statusIdx = new Map(STATUSES.map((s, i) => [s, i]));
+  const nul = (v) => (v == null ? '￿' : v);
+  const cmpBy = {
+    rank: (a, b) => ((HZ[a.horizon] ?? 3) - (HZ[b.horizon] ?? 3)) || ((a.rank ?? 1e9) - (b.rank ?? 1e9)) || a.id.localeCompare(b.id),
+    id: (a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }),
+    owner: (a, b) => String(nul(a.owner)).localeCompare(String(nul(b.owner))) || a.id.localeCompare(b.id),
+    horizon: (a, b) => ((HZ[a.horizon] ?? 3) - (HZ[b.horizon] ?? 3)) || a.id.localeCompare(b.id),
+    title: (a, b) => String(a.title).localeCompare(String(b.title)) || a.id.localeCompare(b.id),
+    stage: (a, b) => ((stageIdx.get(a.stage) ?? 1e9) - (stageIdx.get(b.stage) ?? 1e9)) || a.id.localeCompare(b.id),
+    status: (a, b) => ((statusIdx.get(a.status) ?? 9) - (statusIdx.get(b.status) ?? 9)) || a.id.localeCompare(b.id),
+    end: (a, b) => String(nul(a.end)).localeCompare(String(nul(b.end))) || a.id.localeCompare(b.id),
+    start: (a, b) => String(nul(a.start)).localeCompare(String(nul(b.start))) || a.id.localeCompare(b.id),
+    updated: (a, b) => String(b.updated || '').localeCompare(String(a.updated || '')) || a.id.localeCompare(b.id),
+    progress: (a, b) => (pct(a) - pct(b)) || a.id.localeCompare(b.id),
+  };
+  out = out.slice().sort(cmpBy[sort]);
+  if (desc) out.reverse();
+  let limit = Number.parseInt(query.limit, 10);
+  if (!Number.isFinite(limit) || limit < 1) limit = 25;
+  if (!query.all) limit = Math.min(limit, 100);   // `all` is for the server's own callers (the kanban columns), never a URL parameter
+  let offset = Number.parseInt(query.offset, 10);
+  if (!Number.isFinite(offset) || offset < 0) offset = 0;
+  return { view, sort: (desc ? '-' : '') + sort, total: out.length, offset, limit, rows: out.slice(offset, offset + limit), facets };
+}
+const pct = (r) => (typeof r.progress === 'number' ? r.progress : -1);
+
+/** Board health from its rows: bad when a quarter or more of the open rows are late; warn when any is late or at risk. */
+function health(rows) {
+  const open = (rows || []).filter((r) => r.status !== 'done');
+  const late = open.filter((r) => r.status === 'late').length;
+  const risk = open.filter((r) => r.status === 'at risk').length;
+  if (open.length && late / open.length >= 0.25) return 'bad';
+  if (late || risk) return 'warn';
+  return 'ok';
+}
+
+function counts(rows, workflow) {
+  const byCat = Object.fromEntries(CATEGORIES.map((c) => [c, 0]));
+  const byStage = Object.fromEntries((workflow || []).map((s) => [s.name, 0]));
+  const byStatus = Object.fromEntries(STATUSES.map((s) => [s, 0]));
+  let open = 0;
+  for (const r of rows || []) {
+    if (r.cat && r.cat in byCat) byCat[r.cat]++;
+    if (r.stage != null) byStage[r.stage] = (byStage[r.stage] || 0) + 1;
+    if (r.status in byStatus) byStatus[r.status]++;
+    if (r.status !== 'done') open++;
+  }
+  return { total: (rows || []).length, open, byCat, byStage, byStatus, risk: byStatus['at risk'], late: byStatus.late };
+}
+
+/**
+ * The Jira sprints of a board from the cached status snapshots (lib/jira-status.js readSnapshot), read-only.
+ * snapshots: [{ initiative, fetchedAt, tickets: Map|[] of readings }]; onBoard(initiativeId) → boolean.
+ * A ticket with no sprint (the backlog) is in no sprint. source is 'none' when no snapshot of the board was read.
+ */
+function sprintsOf(snapshots, onBoard = () => true) {
+  const byName = new Map();
+  let readAt = null;
+  let any = false;
+  for (const s of snapshots || []) {
+    if (!s || !onBoard(s.initiative)) continue;
+    any = true;
+    if (s.fetchedAt && (!readAt || s.fetchedAt > readAt)) readAt = s.fetchedAt;
+    const tickets = s.tickets instanceof Map ? [...s.tickets.values()] : Array.isArray(s.tickets) ? s.tickets : [];
+    for (const t of tickets) {
+      if (!t || !t.sprint || !t.sprint.name) continue;
+      const name = String(t.sprint.name);
+      if (!byName.has(name)) byName.set(name, { name, state: t.sprint.state || null, issues: [], counts: { todo: 0, doing: 0, done: 0 } });
+      const sp = byName.get(name);
+      const category = ['todo', 'doing', 'done'].includes(t.category) ? t.category : 'todo';
+      sp.issues.push({ key: t.key, summary: t.summary || '', status: t.status || '', category, initiative: s.initiative });
+      sp.counts[category]++;
+    }
+  }
+  const order = { active: 0, future: 1, closed: 2 };
+  const sprints = [...byName.values()].sort((a, b) => ((order[a.state] ?? 3) - (order[b.state] ?? 3)) || a.name.localeCompare(b.name));
+  for (const sp of sprints) sp.issues.sort((a, b) => a.key.localeCompare(b.key, undefined, { numeric: true }));
+  return { source: any ? 'jira' : 'none', readAt, sprints };
+}
+
+module.exports = {
+  CATEGORIES, WORKFLOW_TEMPLATES, TOOLS, SELF_LADDER, READING_CAT, STATUSES, VIEWS, SORTS,
+  templateWorkflow, isTemplateEdited, fold, readingOf, deriveStage, stageOf, catOf, moveWarnings, cardWarnings,
+  applyWorkflowEdit, filterRows, health, counts, sprintsOf, key,
+  INI_TEMPLATES, TASK_STATES, isBuildStage, templateBuilds, boardSettings, workflowOf, templateOf, applyIniWorkflow, taskOf, shiftDay,
+  ITEM_PROGRESS, itemStatus, taskItem, rollupItems,
+};