create-pmos 0.51.0 → 0.53.0

package/workspace/lib/plan-ledgers.js

@@ -0,0 +1,85 @@
+'use strict';
+/* plan-ledgers.js — the four ledgers of the planning layer, where each one lives, and its one-stat signature
+ * (pm-os-absorb, D86, PRD R24).
+ *
+ *   LEDGERS                → { [name]: { file, writer, run } }   plan-items, placements, measurements, issues
+ *   ledgerPath(root, name) → absolute path of that ledger for the repository of `root`
+ *   ledgerSig(root, name)  → sha1 of size:mtime:ino, or 'none' when the file does not exist
+ *   readLines(root, name)  → { lines: [{ n, rec }], bad: [{ n, why }] }   every line in file order, n counts from 1;
+ *                            no workflow engine → bad: [{ n: 0, why: 'engine missing: …' }]
+ *   notBuilt(what, run)    → the refusal a writer stub returns before its run has built it
+ *
+ * THE LINE ENVELOPE, the same in all four (lib/plan-items.js set it): { v: 1, eid, ev, …the event's fields…, by, via,
+ * at }. `eid` is 12 × [0-9a-z]; `by` is pm:<slug> | agent:unknown | agent:<session>; `via` is ui | cli; `at` is an ISO
+ * UTC time. The writer sets v, eid, by, via and at; a caller never sends them.
+ *
+ * Each ledger has ONE writer module (the `writer` below), and attribution comes from the call path inside that module,
+ * never from a field (lib/plan-items.js is the pattern). This file holds only what the four share, so a new writer, the
+ * checker (scripts/check-plan-ledgers.js), the board cache and the seam test read one list.
+ *
+ * ONE LEDGER PER REPOSITORY. The path is the runs directory (`planning/runs/` for PMOS-self, `pmos/state/` in a kit
+ * repository) of the MAIN working tree of `root`, whichever worktree writes — the same rule as plan-items.js
+ * ledgerRoot. A writer exercised from a linked worktree therefore writes into the main tree: tests use the synthetic
+ * repositories of plan-test-repos.js, never this checkout.
+ *
+ * Nothing here reads a ledger's lines or writes one. Nothing is cached (D33).
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const planTree = require('./plan-tree.js');
+const consoleState = require('./console-state');
+
+const LEDGERS = Object.freeze({
+  'plan-items': Object.freeze({ file: 'plan-items.jsonl', writer: 'workspace/lib/plan-items.js', run: 1 }),
+  placements: Object.freeze({ file: 'placements.jsonl', writer: 'workspace/lib/placements.js', run: 2 }),
+  measurements: Object.freeze({ file: 'measurements.jsonl', writer: 'workspace/lib/measurements.js', run: 2 }),
+  issues: Object.freeze({ file: 'issues.jsonl', writer: 'workspace/lib/issues.js', run: 5 }),
+});
+
+function spec(name) {
+  const s = Object.prototype.hasOwnProperty.call(LEDGERS, name) ? LEDGERS[name] : null;
+  if (!s) throw new Error(`plan-ledgers: no ledger named ${JSON.stringify(name)}`);
+  return s;
+}
+
+/** The runs directory of the main working tree of `root`. Throws when the workflow engine is not installed. */
+function runsDir(root) {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded.engine.layout(planTree.mainTree(path.resolve(String(root)))).runsDir;
+}
+
+function ledgerPath(root, name) { return path.join(runsDir(root), spec(name).file); }
+
+function ledgerSig(root, name) {
+  let st;
+  try { st = fs.statSync(ledgerPath(root, name)); } catch { return 'none'; }
+  return crypto.createHash('sha1').update(`${st.size}:${st.mtimeMs}:${st.ino}`).digest('hex');
+}
+
+/** Every line of a ledger, parsed, in file order; a line that is not a JSON object is named in `bad`, never thrown. */
+function readLines(root, name) {
+  let file;
+  // A missing workflow engine is NOT an empty ledger: it comes back as a bad line (n 0), so every reader's flags show it
+  // and a fold test cannot pass vacuously in a worktree without the vendored engine.
+  try { file = ledgerPath(root, name); } catch (e) { return { lines: [], bad: [{ n: 0, why: 'engine missing: ' + ((e && e.message) || String(e)) }] }; }
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return { lines: [], bad: [] }; }
+  const lines = []; const bad = [];
+  text.split('\n').forEach((raw, i) => {
+    if (!raw.trim()) return;
+    let rec = null;
+    try { rec = JSON.parse(raw); } catch { bad.push({ n: i + 1, why: 'not JSON' }); return; }
+    if (!rec || typeof rec !== 'object' || Array.isArray(rec)) bad.push({ n: i + 1, why: 'not a JSON object' });
+    else lines.push({ n: i + 1, rec });
+  });
+  return { lines, bad };
+}
+
+/** The refusal of a writer whose run has not built it yet: the same shape as every writer refusal. */
+function notBuilt(what, run) {
+  return { ok: false, status: 501, error: `${what} arrives in Run ${run} of pm-os-absorb`, index: null };
+}
+
+module.exports = { LEDGERS, runsDir, ledgerPath, ledgerSig, readLines, notBuilt };

package/workspace/lib/plan-rules.js

@@ -0,0 +1,72 @@
+'use strict';
+/* plan-rules.js — the numbers the planning layer reads (pm-os-absorb, PRD R24): planning/plan-rules.json.
+ *
+ *   readRules(root)        → { stall_days, dormant_days, report_cycle_days, now_cap, via_required_from, …other keys }
+ *   readRulesDetail(root)  → { rules, path, errors, unknown }   the same read, with what was wrong with the file
+ *
+ * One reader, so the Today ranking, the health rules, day one and the report window cannot each keep their own copy
+ * of "5 days". The file is committed with the repository and read from the tree that is shown (`root`), not from the
+ * main tree: a branch that changes a rule sees its own value. PMOS-self keeps it at planning/plan-rules.json; a kit
+ * repository at pmos/state/plan-rules.json. No file is not an error: every key reads its default (the PRD's values).
+ *
+ * A value that is not valid reads its default, and the reason is in `errors`; readRules never throws, because a
+ * typo in a rules file must not take the Today count or a report down with it. A key this reader does not know is
+ * passed through unchanged and named in `unknown` (a run that adds a key adds it to KEYS with its check). Keys that
+ * start with `_` are comments. Nothing is cached (D33): the file is small.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// via_required_from (Run 2, R25(4), map-spec X10): the ISO UTC time from which a PM-only line must carry `via`.
+// scripts/check-pm-lines.js fails a newer line without one and reports each older line once, never failing it.
+// null means no time is set yet: every PM-only line is older, so none fails for a missing via.
+const DEFAULTS = Object.freeze({ stall_days: 5, dormant_days: 45, report_cycle_days: 14, now_cap: null, via_required_from: null });
+const posInt = (v) => Number.isInteger(v) && v > 0;
+const isoUtc = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/.test(v) && !Number.isNaN(Date.parse(v));
+/** Each known key and the check its value must pass. */
+const KEYS = Object.freeze({
+  stall_days: { ok: posInt, want: 'a whole number of days, 1 or more' },
+  dormant_days: { ok: posInt, want: 'a whole number of days, 1 or more' },
+  report_cycle_days: { ok: posInt, want: 'a whole number of days, 1 or more' },
+  now_cap: { ok: (v) => v === null || posInt(v), want: 'null (no cap) or a whole number, 1 or more' },
+  via_required_from: { ok: (v) => v === null || isoUtc(v), want: 'null (not set yet) or an ISO UTC time such as 2026-10-20T09:00:00Z' },
+});
+const CANDIDATES = [['planning', 'plan-rules.json'], ['pmos', 'state', 'plan-rules.json']];
+
+/** The rules file of `root`, or null when it has none. */
+function rulesPath(root) {
+  for (const parts of CANDIDATES) {
+    const f = path.join(path.resolve(String(root || '.')), ...parts);
+    try { if (fs.statSync(f).isFile()) return f; } catch { /* not this layout */ }
+  }
+  return null;
+}
+
+/** Check a parsed rules object. Returns the rules with every bad or missing known key at its default. */
+function validate(obj) {
+  const rules = { ...DEFAULTS };
+  const errors = [];
+  const unknown = [];
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return { rules, errors: ['the rules file is not a JSON object'], unknown };
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith('_')) continue;
+    const spec = KEYS[k];
+    if (!spec) { unknown.push(k); rules[k] = v; continue; }
+    if (spec.ok(v)) rules[k] = v;
+    else errors.push(`${k} is ${JSON.stringify(v)}; it must be ${spec.want}. The default ${JSON.stringify(DEFAULTS[k])} is used.`);
+  }
+  return { rules, errors, unknown };
+}
+
+function readRulesDetail(root) {
+  const f = rulesPath(root);
+  if (!f) return { rules: { ...DEFAULTS }, path: null, errors: [], unknown: [] };
+  let obj;
+  try { obj = JSON.parse(fs.readFileSync(f, 'utf8')); }
+  catch (e) { return { rules: { ...DEFAULTS }, path: f, errors: [`${f} could not be read as JSON: ${String((e && e.message) || e).slice(0, 160)}`], unknown: [] }; }
+  return { ...validate(obj), path: f };
+}
+
+function readRules(root) { return readRulesDetail(root).rules; }
+
+module.exports = { DEFAULTS, KEYS, rulesPath, validate, readRules, readRulesDetail };

package/workspace/lib/plan-tree.js

@@ -0,0 +1,367 @@
+'use strict';
+/* plan-tree.js — the stages an initiative's breakdown hangs under, and the layout the Breakdown pane draws.
+ *
+ * pm-os-absorb Run 1 (PRD R4, R5, R6, R18, R19). Pure apart from reading the initiative record and the
+ * repository's profile: the caller passes the folded ledger (lib/plan-items.js) and the ladder
+ * (lib/console-state.js `ladder()`), and this module groups them. Nothing here writes, and nothing is cached
+ * (D33): every answer is derived from what the caller read on this request.
+ *
+ * WHY THE STAGES ARE NOT A LIST OF THEIR OWN. A stage header groups the steps `scripts/workflow-state.js`
+ * derives for the initiative's lane and profile (R4). The step keys come from the engine (lane-defs
+ * RUNG_RULES), and the suite asserts that STAGE_GROUPS partitions them exactly, so a rung added to the
+ * engine without a stage here fails a test instead of disappearing from the tree.
+ *
+ * The owed row of a stage is the first step of its group that is still open — not done, n/a or unknown —
+ * and it is DERIVED: it ticks itself when the ladder sees its evidence, and nobody can edit it.
+ */
+const fs = require('fs');
+const path = require('path');
+const consoleState = require('./console-state');
+const factoryJoin = require('./factory-join.js');
+
+const STAGE_GROUPS = Object.freeze({
+  'product-code': [
+    { id: 'intake', label: 'Intake', steps: ['route', 'anchor', 'prototype', 'understand'] },
+    { id: 'spec', label: 'Spec', steps: ['spec', 'priors'] },
+    { id: 'contract', label: 'Contract', steps: ['contract'] },
+    { id: 'build', label: 'Build', steps: ['build', 'quality'] },
+    { id: 'evaluate', label: 'Evaluate', steps: ['review', 'explain', 'accept', 'outcome'] },
+  ],
+  'pm-artifacts': [
+    { id: 'intake', label: 'Intake', steps: ['route', 'anchor'] },
+    { id: 'brief', label: null, steps: ['brief'] },        // the lane's brief_label, capitalised: "Problem brief"
+    { id: 'draft', label: null, steps: ['draft'] },        // the lane's draft_label: "PRD", "Change specification"
+    { id: 'evaluate', label: 'Evaluate', steps: ['review', 'approved'] },
+    { id: 'handoff', label: 'Handoff', steps: ['handoff'] },   // dropped for a lane whose rungs have no handoff
+  ],
+});
+// The noun an owed row names. `brief` and `draft` read the lane's own label at run time.
+const STEP_NOUN = Object.freeze({
+  route: 'routing', anchor: 'anchor', prototype: 'prototype', understand: 'explainer', spec: 'spec', priors: 'priors',
+  contract: 'contract', build: 'build', quality: 'checks', review: 'review', explain: 'run explainer', accept: 'acceptance',
+  outcome: 'outcome check', brief: '<brief_label>', draft: '<draft_label>', approved: 'approval', handoff: 'handoff',
+});
+// Who owes the step. Everything not named here is the agent's.
+const OWED_ACTOR = Object.freeze({ accept: 'you', approved: 'you', outcome: 'you', handoff: 'you' });
+const OPEN = (s) => !['done', 'na', 'unknown'].includes(s);
+const DONE_WINDOW_MS = 14 * 86400000;
+// An initiative id is a record file name. Shared with lib/plan-items.js, which re-exports it.
+const INIT_RE = /^[A-Za-z0-9][\w.-]{0,119}$/;
+const STATE_LABEL = { todo: 'Todo', doing: 'Doing', review: 'Review', done: 'Done' };
+
+function engine() {
+  const loaded = consoleState.loadEngine();
+  if (!loaded.ok) throw new Error(loaded.error);
+  return loaded.engine;
+}
+
+/**
+ * The main working tree of the repository `root` sits in. A linked worktree (an agent started by Hand to
+ * agent on a new branch runs in one) has a `.git` FILE naming its gitdir, whose `commondir` leads back to the
+ * main repository's `.git`. Filesystem reads only — no git process, because this runs on every poll.
+ *
+ * A `.git` FILE is followed ONLY for a real linked worktree of a non-bare repository whose main tree exists.
+ * Everything else keeps `root`: a submodule and a `--separate-git-dir` repository have no `commondir`; a worktree
+ * of a bare repository has a common directory that is not named `.git`. Following those would put the ledger
+ * outside the repository (or inside a git directory), where git, CI and every other clone never see it.
+ */
+function mainTree(root) {
+  const dotgit = path.join(root, '.git');
+  let st;
+  try { st = fs.statSync(dotgit); } catch { return root; }
+  if (st.isDirectory()) return root;
+  let m = null;
+  try { m = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotgit, 'utf8')); } catch { return root; }
+  if (!m) return root;
+  const gitdir = path.resolve(root, m[1].trim());
+  let common;
+  try { common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim()); }
+  catch { return root; }                                   // a submodule or a separate git directory
+  if (path.basename(common) !== '.git') return root;       // a worktree of a bare repository
+  const main = path.dirname(common);
+  try { if (!fs.statSync(path.join(main, '.git')).isDirectory()) return root; } catch { return root; }
+  return main;
+}
+
+/** The initiative record, looked up in this tree first and then in the main tree. null when neither has it. */
+function recordPath(root, initiative) {
+  if (typeof initiative !== 'string' || !INIT_RE.test(initiative)) return null;
+  // The folder's README.md and index.md are not records: the same rule as the engine's listInitiatives().
+  if (initiative === 'README' || initiative === 'index') return null;
+  const eng = engine();
+  const roots = [root];
+  const main = mainTree(root);
+  if (main !== root) roots.push(main);
+  for (const r of roots) {
+    const file = path.join(eng.layout(r).initiatives, `${initiative}.md`);
+    try { if (fs.statSync(file).isFile()) return file; } catch { /* try the next tree */ }
+  }
+  return null;
+}
+
+/** The repository's profile, the initiative's lane (as workflow-state.js resolves it) and the lane definitions. */
+function profileAndLane(root, initiative) {
+  const eng = engine();
+  const { profile, defs } = eng.lanesFor(root);
+  const file = recordPath(root, initiative);
+  let fm = {};
+  if (file) { try { fm = eng.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {}; } catch { fm = {}; } }
+  const declared = String(fm.lane || '').trim();
+  // An unknown or missing lane is the profile's strictest, exactly as workflow-state.js computes `effLane`.
+  const fallback = profile === 'pm-artifacts' ? 'prd' : 'feature';
+  const lane = declared && defs[declared] ? declared : fallback;
+  return { profile, lane, defs, record: file };
+}
+
+const cap = (s) => (s && /^[a-z]/.test(s) ? s[0].toUpperCase() + s.slice(1) : s);
+
+/** The stages of this initiative, in order: [{ id, label, steps }]. */
+function stagesFor(root, initiative) {
+  const { profile, lane, defs } = profileAndLane(root, initiative);
+  if (profile !== 'pm-artifacts') return STAGE_GROUPS['product-code'].map((g) => ({ ...g, steps: g.steps.slice() }));
+  const def = defs[lane] || defs.prd;
+  const out = [];
+  for (const g of STAGE_GROUPS['pm-artifacts']) {
+    if (g.id === 'handoff' && !(def.rungs || []).includes('handoff')) continue;
+    const label = g.id === 'brief' ? cap(def.brief_label) : g.id === 'draft' ? cap(def.draft_label) : g.label;
+    out.push({ id: g.id, label, steps: g.steps.slice() });
+  }
+  return out;
+}
+function stageIdsFor(root, initiative) { return stagesFor(root, initiative).map((s) => s.id); }
+
+/** A stage id from an id or a label, case- and space-insensitive. null when it names no stage of this initiative. */
+function resolveStage(root, initiative, idOrLabel) {
+  const norm = (s) => String(s == null ? '' : s).toLowerCase().replace(/\s+/g, ' ').trim();
+  const want = norm(idOrLabel);
+  if (!want) return null;
+  for (const s of stagesFor(root, initiative)) if (norm(s.id) === want || norm(s.label) === want) return s.id;
+  return null;
+}
+
+/** The noun an owed row uses for a step, with the lane's own brief and draft labels filled in. */
+function nounFor(key, def) {
+  if (key === 'brief') return (def && def.brief_label) || 'brief';
+  if (key === 'draft') return (def && def.draft_label) || 'draft';
+  return STEP_NOUN[key] || key;
+}
+
+/**
+ * The owed row of a stage: the first step of its group that is still open. null when every step is done,
+ * n/a or unknown — those neither block nor count as owed (R3, R4).
+ */
+function owedFor(group, steps, def) {
+  const byKey = new Map((steps || []).map((s) => [s.key, s]));
+  for (const key of group.steps) {
+    const s = byKey.get(key);
+    if (!s || !OPEN(s.status)) continue;
+    const noun = nounFor(key, def);
+    const actor = OWED_ACTOR[key] || 'agent';
+    return { key, noun, actor, status: s.status, next: s.next || null, label: `Owed: ${noun} · ${actor}` };
+  }
+  return null;
+}
+
+/**
+ * The progress label (R6), shared by the layout, the fold's progressOf and the CLI. Proposed and withdrawn items never
+ * count; when nothing is kept yet but an agent proposed items, it says so instead of a bare "no breakdown".
+ */
+function progressLabel(done, total, proposed) {
+  if (total) return `${done} of ${total}`;
+  return proposed ? `no breakdown · ${proposed} proposed` : 'no breakdown';
+}
+
+const byLabel = (by) => {
+  const s = String(by || '');
+  if (/^pm:/.test(s)) return 'you';
+  const m = /^agent:(sess-\d+)\./.exec(s);
+  if (m) return `agent · ${m[1]}`;
+  if (s === 'agent:unknown') return 'agent (unknown)';
+  return s || 'unknown';
+};
+
+/** One history entry as a sentence. `stageLabelOf(id)` names a stage. */
+function historyText(h, stageLabelOf) {
+  const lab = (id) => (stageLabelOf && stageLabelOf(id)) || id;
+  const st = (s) => STATE_LABEL[s] || s;
+  if (h.ev === 'planned') return `added in ${lab(h.stage)}`;
+  if (h.ev === 'moved') {
+    const ev = h.evidence ? ` with evidence ${h.evidence.kind}:${h.evidence.ref}` : '';
+    return `moved to ${st(h.to)}${ev}`;
+  }
+  if (h.ev === 'flagged') return h.blocked ? `blocked: ${h.reason}` : 'unblocked';
+  if (h.ev === 'withdrawn') return 'withdrawn';
+  if (h.ev === 'kept') return 'kept';
+  if (h.ev === 'set') {
+    const f = h.fields || {};
+    const parts = [];
+    for (const k of Object.keys(f)) {
+      const v = f[k];
+      if (k === 'stage') parts.push(`moved to stage ${lab(v)}`);
+      else if (k === 'order') parts.push('reordered');
+      else if (k === 'title') parts.push(`renamed to "${v}"`);
+      else if (k === 'due' || k === 'start') parts.push(v ? `${k} set to ${v}` : `${k} cleared`);
+      else if (k === 'owner') parts.push(`owner set to ${v}`);
+      else if (k === 'after') parts.push(Array.isArray(v) && v.length ? `after ${v.join(', ')}` : 'predecessors cleared');
+      else if (k === 'milestone') parts.push(v ? 'marked a milestone' : 'no longer a milestone');
+      else if (k === 'note') parts.push(v ? 'note changed' : 'note cleared');
+      else parts.push(`${k} changed`);
+    }
+    return parts.join('; ') || 'changed';
+  }
+  return h.ev;
+}
+
+const treeOrder = (a, b) => (a.order - b.order) || String(a.createdAt).localeCompare(String(b.createdAt)) || a.id.localeCompare(b.id);
+
+/** What a plan item reads when it was dragged to Done and the factory has not integrated its work item (R7). */
+const NOT_MERGED_LABEL = 'Done · your call · not merged';
+
+/**
+ * The factory join applied to the items of one initiative (PRD R7, D86 point 1; pm-os-absorb Run 4).
+ *
+ * A plan item that a work item materializes (its `declared` line names it as `plan_item`) carries
+ * `factory: { item, state, integrated, pr, notMerged, label }`. Once that work item is integrated (`pmos verify-work`
+ * saw its trailer on the default branch), the plan item reads Done with no hand edit: state `done`, and its Done time
+ * is the integration's unless it was already Done. A plan item moved to Done whose work item is NOT integrated stays
+ * Done, the PM's call, and says so (`notMerged`, `label`). The plan-items ledger is not written: the factory's own
+ * `integrated` line is the evidence (D86 point 1), so this is applied on every read. A withdrawn work item is not a
+ * join. An item no work item names is returned unchanged and gains no key, so the layout's shape holds for it.
+ */
+function withFactory(root, initiative, fold, items) {
+  let entry = null;
+  try { entry = factoryJoin.factoryOf(factoryJoin.joinFactory(root, { initiative, fold }), initiative); } catch { entry = null; }
+  if (!entry || !entry.items.length) return items;
+  const byPlan = new Map();
+  for (const w of entry.items) if (w.plan_item && w.state !== 'withdrawn' && !byPlan.has(w.plan_item)) byPlan.set(w.plan_item, w);
+  return items.map((it) => {
+    const w = byPlan.get(it.id);
+    if (!w) return it;
+    const notMerged = !w.integrated && it.state === 'done';
+    const factory = { item: w.id, state: w.state, integrated: !!w.integrated, pr: w.pr || null, notMerged, label: notMerged ? NOT_MERGED_LABEL : null };
+    if (!w.integrated) return { ...it, factory };
+    const doneAt = it.state === 'done' ? it.doneAt : (w.integrated_at || it.doneAt || null);
+    return { ...it, state: 'done', doneAt, noEvidence: false, late: false, factory };
+  });
+}
+
+/**
+ * The Breakdown layout of one initiative (the shape the pane draws; see the Run 1 plan §2.2).
+ *
+ * @param {object} o
+ * @param {string} o.root        the workspace root
+ * @param {string} o.initiative  the initiative id
+ * @param {object} o.fold        planItems.fold() result for the repository's ledger
+ * @param {object|null} o.ladder consoleState.ladder() result, or null for the fast path (no owed rows)
+ * @param {number} [o.now]
+ */
+function layout({ root, initiative, fold, ladder, now }) {
+  const t = Number.isFinite(now) ? now : Date.now();
+  const { profile, lane, defs } = profileAndLane(root, initiative);
+  const def = profile === 'pm-artifacts' ? (defs[lane] || defs.prd) : null;
+  const stages = stagesFor(root, initiative);
+  const stageIds = stages.map((s) => s.id);
+  const labelOf = (id) => { const s = stages.find((x) => x.id === id); return s ? s.label : id; };
+  const ladderIncluded = ladder !== null && ladder !== undefined;
+  let steps = null;
+  let ladderState = null;
+  if (ladderIncluded) {
+    if (ladder && ladder.ok && ladder.row && Array.isArray(ladder.row.steps)) {
+      steps = ladder.row.steps;
+      ladderState = { ok: true, error: null };
+    } else {
+      ladderState = { ok: false, error: (ladder && (ladder.error || (ladder.empty ? `no ladder for ${initiative}` : null))) || 'the ladder could not be derived' };
+    }
+  }
+
+  const mine = withFactory(root, initiative, fold,
+    (fold.order || []).map((id) => fold.items[id]).filter((it) => it && it.initiative === initiative));
+  const gone = new Set(fold.withdrawnIds || []);
+  const items = {};
+  const flags = [];
+  for (const it of mine) {
+    const stageKnown = stageIds.includes(it.stage);
+    if (!stageKnown) flags.push({ kind: 'unknown-stage', line: null, eid: null, item: it.id, message: `${it.id} names stage "${it.stage}", which this initiative's lane does not have — shown under Other` });
+    const { movedVia, ...shown } = it;   // movedVia stays in the fold (needsFor reads it); the pane does not
+    items[it.id] = {
+      ...shown, stageKnown, byLabel: byLabel(it.updatedBy),
+      // A withdrawn predecessor is not shown: the sheet then sends the list without it, and the writer lets it go.
+      after: it.after.filter((x) => !gone.has(x)),
+      // A planned entry carries its stage in the fold so its sentence can say where it was added; the pane gets
+      // the §1.4 history keys and the sentence, not the stage.
+      history: it.history.map(({ stage, ...h }) => ({ ...h, byLabel: byLabel(h.by), text: historyText({ ...h, stage }, labelOf) })),
+    };
+  }
+  const visibleItems = mine;
+  const counted = (list) => list.filter((it) => !it.proposed);
+
+  let firstOpenSeen = false;
+  const stageRows = stages.map((s) => {
+    const inStage = visibleItems.filter((it) => it.stage === s.id).sort(treeOrder);
+    const real = counted(inStage);
+    const total = real.length;
+    const done = real.filter((it) => it.state === 'done').length;
+    const proposed = inStage.length - real.length;
+    const row = { id: s.id, label: s.label };
+    let owed = null;
+    if (steps) owed = owedFor(s, steps, def);
+    row.visible = total > 0 || proposed > 0 || owed !== null;
+    // A stage before the first open step is `done`; every stage after it is `later`, even one whose own steps
+    // are all done, because the work reaches it in ladder order. Without the ladder (`ladder=0`) `current`,
+    // `state` and `owed` are not derived, so they are left out: the client keeps them from its last full
+    // response. A ladder that was asked for but failed gives `current:false`, `state:null`, `owed:null`.
+    if (steps) {
+      const current = owed !== null && !firstOpenSeen;
+      row.current = current;
+      row.state = current ? 'current' : (firstOpenSeen ? 'later' : 'done');
+      if (owed !== null) firstOpenSeen = true;
+    } else if (ladderIncluded) {
+      row.current = false;
+      row.state = null;
+    }
+    Object.assign(row, { done, total, proposed, count: total > 0 ? `${done} of ${total}` : null });
+    if (ladderIncluded) row.owed = owed;
+    row.items = inStage.map((it) => it.id);
+    return row;
+  });
+  const otherItems = visibleItems.filter((it) => !stageIds.includes(it.stage)).sort(treeOrder);
+
+  const real = counted(visibleItems);
+  const pDone = real.filter((it) => it.state === 'done').length;
+  const progress = { done: pDone, total: real.length, proposed: visibleItems.length - real.length,
+    label: progressLabel(pDone, real.length, visibleItems.length - real.length) };
+
+  const stageIdx = (id) => { const i = stageIds.indexOf(id); return i === -1 ? stageIds.length : i; };
+  const boardSort = (a, b) => (stageIdx(a.stage) - stageIdx(b.stage)) || treeOrder(a, b);
+  const board = { todo: [], doing: [], review: [], done: [], doneOlder: 0 };
+  for (const st of ['todo', 'doing', 'review', 'done']) {
+    let list = visibleItems.filter((it) => it.state === st);
+    if (st === 'done') {
+      const recent = list.filter((it) => it.doneAt && Date.parse(it.doneAt) >= t - DONE_WINDOW_MS);
+      board.doneOlder = list.length - recent.length;
+      list = recent;
+    }
+    board[st] = list.sort(boardSort).map((it) => it.id);
+  }
+
+  const batches = (fold.batches || []).filter((b) => b.initiative === initiative)
+    .map((b) => ({ key: b.by, by: b.by, byLabel: b.byLabel, count: b.count, items: b.items.slice(), firstAt: b.firstAt, lastAt: b.lastAt }));
+  for (const f of fold.flags || []) {
+    if (f.initiative && f.initiative !== initiative) continue;
+    flags.push({ kind: f.kind, line: f.line, eid: f.eid, item: f.item, message: f.message });
+  }
+  const withdrawnCount = (fold.withdrawnIds || []).filter((id) => id.startsWith(initiative + '.')
+    && /^[0-9a-z]{10}$/.test(id.slice(initiative.length + 1))).length;
+
+  const out = { profile, lane, ladderIncluded };
+  if (ladderIncluded) out.ladder = ladderState;
+  Object.assign(out, {
+    progress, stages: stageRows, other: { items: otherItems.map((it) => it.id) }, items, board, batches, flags, withdrawnCount,
+  });
+  return out;
+}
+
+module.exports = {
+  STAGE_GROUPS, STEP_NOUN, OWED_ACTOR, OPEN, DONE_WINDOW_MS, INIT_RE, NOT_MERGED_LABEL, withFactory,
+  mainTree, recordPath, profileAndLane, stagesFor, stageIdsFor, resolveStage, owedFor, nounFor, byLabel, progressLabel, layout, historyText,
+};