create-pmos 0.14.0 → 0.16.0

package/workspace/public/pm/data.js

@@ -0,0 +1,877 @@
+/* pm/data.js — the real-state adapter for the four-panel workspace.
+ *
+ * Every panel module renders from `state`. This module is the ONLY thing that puts real repository
+ * state into it. It reads exclusively from this server's own origin over relative URLs — there is
+ * no other host, no client library, no dependency — and in FIXTURE mode it does not read at all.
+ *
+ * ── The failure it exists to prevent ────────────────────────────────────────────────────────
+ * The PRD names it "the beautiful shell": seed data rendering in both modes, so the comparator's
+ * diff is clean and nothing is connected. Two rules keep that impossible here:
+ *   1. `FIXTURE` short-circuits every function below before any fetch. Fixture mode makes NO
+ *      network calls, so a fixture render is provably not a real read wearing a costume.
+ *   2. Nothing in this file falls back to `fixture.js` seed data. The only thing imported from it
+ *      is `C` — the semantic colour tokens — because a second copy of `var(--warning)` in this file
+ *      is exactly the kind of duplicate that drifts.
+ *
+ * ── The honesty contract ────────────────────────────────────────────────────────────────────
+ * The server's own contract is `{ok:true,empty:true}` (a successful read of nothing → CALM) ·
+ * `{ok:true,…}` (data) · `{ok:false,error}` (a failed read → RED). This module preserves the
+ * distinction rather than collapsing it:
+ *   · a failed read of an initiative becomes `{readError}` on the record, which panel 3 renders as
+ *     its red block carrying the server's own message. It never becomes an empty tree.
+ *   · a failed read of the board leaves the board absent, which panel 2 renders as its own empty
+ *     state — and the failure is reported on the record of whatever the PM then selects.
+ *   · a field with no source is `null`. Not zero, not an empty string standing in for a value, and
+ *     never a plausible-looking guess. `— not tracked` is the surface's job, not this file's.
+ *
+ * ── What is derived here, and by what rule ──────────────────────────────────────────────────
+ * PMOS has no task entity, so a phase's tasks are DERIVED (PRD, "Tasks"):
+ *   · the phase SET comes from the initiative's lane;
+ *   · each phase folds a fixed set of the workflow engine's twelve rungs, so every rung's evidence
+ *     lands in exactly one phase and none is dropped;
+ *   · a task's status comes from that phase's rungs — `done` where they passed, `blocked` where
+ *     one is blocking, `doing` where one is current, else `todo`. A phase whose rungs carry no
+ *     evidence at all reads `todo`, NEVER `done`;
+ *   · an `## Tasks` section authored in the initiative record overrides the derivation entirely.
+ * Nothing is invented per initiative: every task's instruction, expectation and evaluation is the
+ * engine's own text for the rung it belongs to.
+ *
+ * ── The one thing this file refuses to do ───────────────────────────────────────────────────
+ * Linking an artifact records a DECLARATION (`{artifact_path, kind, target}` appended to
+ * `artifact-links.jsonl`). It makes no outbound request, because PMOS holds no credential. The
+ * sync panel therefore reports an unconfigured connector rather than a difference summary it never
+ * read — `state.connectors` is published empty, which is what makes panel 3's two approval buttons
+ * inert. A "2 sections differ" line over a destination nobody contacted is the watermelon this
+ * repo has a word for.
+ */
+
+import { state, setState, subscribe, FIXTURE } from './state.js';
+import { C } from './fixture.js';
+
+/* ── transport ──────────────────────────────────────────────────────────────────────────────
+ * Relative URLs only. The server's origin/host allowlist 403s a page served from anywhere else,
+ * so a relative path is both the simplest form and the only one that can work.
+ */
+
+const q = (params) => Object.entries(params)
+  .filter(([, v]) => v !== null && v !== undefined && v !== '')
+  .map(([k, v]) => encodeURIComponent(k) + '=' + encodeURIComponent(v)).join('&');
+
+/** GET JSON. Resolves to `{ok:false,error}` on any transport failure — never throws at the caller. */
+async function getJson(path, params) {
+  const url = params ? path + '?' + q(params) : path;
+  let res;
+  try { res = await fetch(url); }
+  catch (e) { return { ok: false, error: 'could not reach the workspace server — ' + msg(e) }; }
+  let body;
+  try { body = await res.json(); }
+  catch { return { ok: false, error: url + ' returned a body that is not JSON (HTTP ' + res.status + ')' }; }
+  // The console family returns HTTP 200 even for {ok:false} — the body carries the reason. A
+  // non-2xx with a JSON body is still that body's failure to report.
+  if (!res.ok && body && body.ok !== false) return { ok: false, error: 'HTTP ' + res.status + ' from ' + url };
+  return body;
+}
+
+async function postJson(path, body) {
+  let res;
+  try {
+    res = await fetch(path, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+    });
+  } catch (e) { return { ok: false, error: 'could not reach the workspace server — ' + msg(e) }; }
+  try { return await res.json(); }
+  catch { return { ok: false, error: path + ' returned a body that is not JSON (HTTP ' + res.status + ')' }; }
+}
+
+const msg = (e) => (e && e.message ? e.message : String(e));
+
+/* ── the lane → phase model (PRD, "Tasks") ──────────────────────────────────────────────────
+ * PHASES is the phase SET per lane, verbatim from the PRD. RUNGS maps each phase to the engine
+ * rungs it folds. Every lane's mapping covers all twelve rungs exactly once — that is the property
+ * that makes the fold lossless: no rung's evidence is dropped, and none is counted twice.
+ */
+
+const PHASES = {
+  feature: ['intake', 'spec', 'contract', 'build', 'eval', 'accepted'],
+  discovery: ['intake', 'explore', 'synthesize', 'decide'],
+  chore: ['intake', 'fix', 'verify'],
+  incident: ['intake', 'contain', 'record', 'verify'],
+  content: ['intake', 'draft', 'review', 'publish'],
+  prototype: ['intake', 'specimens', 'grill', 'dispose'],
+};
+
+const RUNGS = {
+  feature: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors'],
+    spec: ['spec'], contract: ['contract'], build: ['build', 'quality'],
+    eval: ['review', 'explain'], accepted: ['accept'],
+  },
+  discovery: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors', 'spec', 'contract'],
+    explore: ['build', 'quality'], synthesize: ['review'], decide: ['explain', 'accept'],
+  },
+  chore: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors', 'spec', 'contract'],
+    fix: ['build', 'quality'], verify: ['review', 'explain', 'accept'],
+  },
+  incident: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors'],
+    contain: ['build', 'quality'], record: ['spec', 'contract', 'review'], verify: ['explain', 'accept'],
+  },
+  content: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors'],
+    draft: ['spec', 'contract', 'build', 'quality'], review: ['review'], publish: ['explain', 'accept'],
+  },
+  prototype: {
+    intake: ['route', 'anchor', 'prototype', 'understand', 'priors', 'spec', 'contract'],
+    specimens: ['build', 'quality'], grill: ['review', 'explain'], dispose: ['accept'],
+  },
+};
+
+const laneOf = (lane) => (PHASES[lane] ? lane : 'feature');
+
+/**
+ * The status a phase inherits from the rungs it folds.
+ *
+ * `na` and `unknown` are DECIDED BY NOBODY and are excluded from the roll-up rather than counted
+ * as failures. `quality` is permanently `unknown` by the engine's own design — it never claims a
+ * test result it did not run — so counting it as not-done would mean the build phase could never
+ * read done on any initiative, forever. The engine's own `stage` derivation ignores it for exactly
+ * this reason.
+ *
+ * A phase whose rungs carry NO evidence is `pending`, checked before anything else: a rung the
+ * engine found nothing for must never roll up to `done`.
+ */
+function phaseRungStatus(rungs) {
+  if (!rungs.length) return 'pending';
+  if (rungs.every((r) => !r.evidence)) return 'pending';
+  if (rungs.some((r) => r.status === 'blocked')) return 'blocked';
+  if (rungs.some((r) => r.status === 'current')) return 'current';
+  const decided = rungs.filter((r) => r.status !== 'na' && r.status !== 'unknown');
+  if (decided.length && decided.every((r) => r.status === 'done')) return 'done';
+  return 'pending';
+}
+
+/** The rung that explains the phase: the blocker, else the current one, else the last with evidence. */
+function decidingRung(rungs) {
+  return rungs.find((r) => r.status === 'blocked')
+    || rungs.find((r) => r.status === 'current')
+    || [...rungs].reverse().find((r) => r.evidence)
+    || rungs[rungs.length - 1] || null;
+}
+
+/** Task statuses per phase status — the PRD's rule, spread over the three derived tasks. */
+const TASK_STATUS = {
+  done: ['done', 'done', 'done'],
+  current: ['done', 'doing', 'todo'],
+  blocked: ['blocked', 'todo', 'todo'],
+  pending: ['todo', 'todo', 'todo'],
+};
+
+/**
+ * The three derived tasks for one phase. Each field is the engine's own text for the rungs this
+ * phase folds — the instruction is what the engine says to DO, the expectation is what it says it
+ * LOOKED FOR, the evaluation names the rule that decides. A field with no source is null and the
+ * task pane renders it empty; it is never filled with a sentence that sounds like evidence.
+ */
+function derivedTasks(phase, rungs, ctx) {
+  const s = phaseRungStatus(rungs);
+  const lead = decidingRung(rungs) || {};
+  const titles = s === 'blocked'
+    ? ['resolve the ' + phase + ' blocker', 'produce the ' + phase + ' output', 'record the result']
+    : ['read the inputs for ' + phase, 'produce the ' + phase + ' output', 'record the result'];
+  const evidence = rungs.filter((r) => r.evidence).map((r) => r.key + ': ' + r.evidence).join(' · ') || null;
+  const inputs = [ctx.record, ctx.prd, ctx.rubric].filter(Boolean).join(' · ') || null;
+  const rules = rungs.map((r) => r.rule).filter(Boolean);
+  return titles.map((title, i) => ({
+    title,
+    status: (TASK_STATUS[s] || TASK_STATUS.pending)[i],
+    // The engine's own action for the phase — except on the first task, whose job IS the reading,
+    // so it names the files rather than repeating the action. Neither is authored prose: one is the
+    // engine's sentence, the other is a list of paths the record declares.
+    instruction: (i === 0 && inputs ? 'Read ' + inputs : null) || lead.next || lead.evidence || null,
+    input: inputs,
+    expect: evidence,
+    evalNote: rules.length
+      ? 'workflow rule ' + rules.join(', ') + ' decides this phase'
+      : 'the workflow engine derives this phase from ' + rungs.map((r) => r.key).join(', '),
+    // The produced artifact, when the engine named a path in its own evidence. Never guessed:
+    // an artifact the engine did not name is "no artifact yet", which the task pane says in words.
+    output: i === 1 ? (pathIn(lead.evidence) || pathIn(lead.next) || null) : null,
+  }));
+}
+
+/** The first repo-relative path inside an engine message, or null. Used only for a task's `output`. */
+function pathIn(text) {
+  const m = String(text || '').match(/\b(?:planning|prototype|workspace|okf|skills|build-skills)\/[\w./-]+\.\w+/);
+  return m ? m[0] : null;
+}
+
+/** The `steps[]` panel 3 reads: one entry per lane phase, carrying the folded rungs' evidence. */
+function phaseSteps(lane, ladderSteps) {
+  const L = laneOf(lane);
+  const by = {};
+  for (const s of ladderSteps || []) by[s.key] = s;
+  return PHASES[L].map((phase) => {
+    const rungs = (RUNGS[L][phase] || []).map((k) => by[k]).filter(Boolean);
+    const lead = decidingRung(rungs) || {};
+    return {
+      k: phase,
+      s: phaseRungStatus(rungs),
+      t: lead.evidence || '',
+      action: lead.next || null,
+      cmd: pathIn(lead.next) || pathIn(lead.evidence) || null,
+    };
+  });
+}
+
+/* ── record derivation ──────────────────────────────────────────────────────────────────────── */
+
+/** The `pills` row: lane, then the resolved anchor or an honest rejection, then a declared flow. */
+function pillsFor({ lane, anchor, flow }) {
+  const out = [];
+  if (lane) out.push({ t: lane, c: C.pur });
+  if (anchor && anchor.canonical) out.push({ t: anchor.canonical, c: C.mut });
+  else if (anchor && anchor.status === 'unknown') out.push({ t: 'anchor unread', c: C.wrn });
+  else out.push({ t: 'unanchored', c: C.wrn });
+  // The `flow` pill ships only when the record declares one. No record in this repository does, and
+  // inventing `adlc-feature` to fill the slot would be stating a workflow that was never chosen.
+  if (flow) out.push({ t: 'flow ' + flow, c: C.inf });
+  return out;
+}
+
+/**
+ * The footer tuple `[stage, note, colour]` and the dot beside every row in panel 2. `stage` is the
+ * engine's, never a `status:` string — there is no stage field to read (D64/the record README) and
+ * a status nobody maintains is a board that lies.
+ */
+function l2For(row) {
+  if (!row) return ['—', 'ladder not derived yet', C.mut];
+  const blockers = (row.blockers || []).length;
+  if (row.accepted) return [row.stage || 'accepted', 'accepted', C.suc];
+  if (blockers) return [row.stage || '—', '✗ ' + blockers + ' blocked', C.des];
+  if (row.next) return [row.stage || '—', '→ ' + row.next.step + ' owed', C.wrn];
+  return [row.stage || '—', 'no next step recorded', C.mut];
+}
+
+/** The `answer` banner — the engine's own `next`, with a tone derived from the blockers. */
+function answerFor(row) {
+  if (!row) return null;
+  if (!row.next) {
+    return row.accepted
+      ? { tone: 'ok', text: 'accepted — the ladder is complete.' }
+      : { tone: 'info', text: 'the engine reports no next step for this initiative.' };
+  }
+  return {
+    tone: (row.blockers || []).length ? 'bad' : 'warn',
+    text: row.next.action || row.next.why || '',
+  };
+}
+
+/** The Review-Gate line, read off the `review` rung — no verdict is not a pass. */
+function evalFor(ladderSteps) {
+  const r = (ladderSteps || []).find((s) => s.key === 'review');
+  if (!r || r.status !== 'done' || !r.evidence) return null;
+  return { pass: /^PASS/i.test(r.evidence), text: r.evidence };
+}
+
+/** A live session, in the shape panel 2 and panel 4 read. `shown` is the server's own derived state. */
+function sessionRow(s) {
+  const label = s.shown === 'quiet' && Number.isFinite(s.quietMs)
+    ? 'quiet ' + Math.max(1, Math.round(s.quietMs / 60000)) + 'm'
+    : (s.shown === 'needs' ? 'needs you' : s.shown);
+  return { name: s.name, st: s.shown, label, profile: s.profile_id || null, id: s.id };
+}
+
+/**
+ * External references. Two sources, both declarations and neither a reading: the record's own
+ * `handoff_*` frontmatter (parsed by lib/handoff.js, whose `connected` is the literal false on
+ * every path it has), and the rows the PM added by hand into `initiative-links.jsonl`.
+ */
+function linksFor(payload) {
+  const out = [];
+  const h = payload.links && payload.links.links;
+  for (const l of h || []) {
+    out.push({ kind: l.kind, label: l.declared, path: l.href || l.declared, st: l.state_text || l.state });
+  }
+  for (const r of (payload.declarations && payload.declarations.links) || []) {
+    out.push({ kind: r.kind, label: r.label, path: r.target, st: 'declared · not connected' });
+  }
+  return out;
+}
+
+/** Artifacts, with any declared external destination attached. */
+function artsFor(payload) {
+  const dest = new Map();
+  for (const r of (payload.declarations && payload.declarations.artifacts) || []) {
+    dest.set(r.artifact_path, { kind: r.kind, target: r.target });   // a later row supersedes an earlier
+  }
+  return (payload.artifacts || []).map((a) => {
+    const d = dest.get(a.path);
+    return d ? { role: a.role, path: a.path, dest: d } : { role: a.role, path: a.path };
+  });
+}
+
+/** The full record panel 3 renders, from one `/api/initiative` payload. */
+function recordFrom(payload) {
+  if (!payload || payload.ok === false) {
+    const error = (payload && payload.error) || 'the initiative could not be read';
+    return { readError: error, l2: ['read failed', error.slice(0, 60), C.des] };
+  }
+  const fm = payload.frontmatter || {};
+  const row = (payload.ladder && payload.ladder.ok && payload.ladder.row) || null;
+  const scope = (payload.ladder && payload.ladder.scope) || null;
+  const lane = fm.lane || (row && row.lane) || null;
+  const steps = row ? phaseSteps(lane, row.steps) : [];
+  const ctx = { record: payload.record, prd: fm.prd_path || null, rubric: fm.rubric_path || null };
+  // Authored tasks win over derivation, per phase (PRD, "Tasks"). Their absence is not a defect.
+  const authored = payload.tasks || {};
+  const tasks = {};
+  const byKey = {};
+  for (const s of (row && row.steps) || []) byKey[s.key] = s;
+  for (const st of steps) {
+    const rungs = (RUNGS[laneOf(lane)][st.k] || []).map((k) => byKey[k]).filter(Boolean);
+    tasks[st.k] = Array.isArray(authored[st.k]) && authored[st.k].length
+      ? authored[st.k]
+      : derivedTasks(st.k, rungs, ctx);
+  }
+  const rec = {
+    tag: fm.title || (row && row.title) || '',
+    stage: row ? row.stage : null,
+    flow: fm.flow || null,
+    pills: pillsFor({ lane, anchor: payload.anchor, flow: fm.flow || null }),
+    // What the ladder was DERIVED ON, which is exactly what the footer sentence claims.
+    branch: scope ? scope.branch : null,
+    answer: answerFor(row),
+    steps,
+    tasks,
+    sessions: (payload.sessions || []).map(sessionRow),
+    links: linksFor(payload),
+    arts: artsFor(payload),
+    eval: evalFor(row && row.steps),
+    l2: l2For(row),
+  };
+  if (!row) {
+    rec.noLadder = payload.absent
+      ? 'No initiative record on this board — the artifacts below are what the library can see; no loop position is claimed.'
+      : 'No loop position could be derived for this initiative.';
+    if (!rec.answer) {
+      rec.answer = { tone: 'warn', text: 'File an initiative record — artifacts exist, but no loop position is claimed.' };
+    }
+    rec.pills = payload.absent ? [{ t: 'no record', c: C.wrn }] : rec.pills;
+    rec.l2 = payload.absent ? ['—', 'no record', C.wrn] : rec.l2;
+  }
+  if (!rec.sessions.length) {
+    rec.noSess = (payload.session_trees || []).length
+      ? 'No sessions on this initiative — normal, not an error.'
+      : 'No working tree is on initiative/' + payload.id + ' — a normal state.';
+  }
+  return rec;
+}
+
+/* ── the board (panel 2), from the spine + the library ──────────────────────────────────────── */
+
+/** A LIGHT record: everything the board can show without deriving a ladder per initiative. */
+function lightRecord(rec, artifacts) {
+  return {
+    tag: rec.title || '',
+    stage: null,
+    flow: null,
+    pills: pillsFor({ lane: rec.lane, anchor: rec.anchorHint || null, flow: null }),
+    branch: null,
+    answer: null,
+    steps: [],
+    sessions: [],
+    links: [],
+    arts: (artifacts || []).map((a) => ({ role: a.role, path: a.path })),
+    eval: null,
+    // Not "todo" and not "done": the ladder for this initiative has not been derived. Deriving all
+    // of them costs one `git log` per record — ~30 s on this repository — and a board that froze
+    // the PM's terminals to colour its dots would be a worse answer than a grey one.
+    l2: ['—', 'ladder not derived yet — open it to derive', C.mut],
+    lite: true,
+  };
+}
+
+/**
+ * Fold `/api/console?name=spine` into the board's groups.
+ *
+ * A group is one Objective+KR pair, which is the prototype's own model (one group, one optional KR
+ * sub-row). Its `gid` therefore carries BOTH ids: the collapse key in panel 2 is `product|gid`, so
+ * three groups all calling themselves `O1` would fold and unfold as one.
+ */
+function groupsFromSpine(spine) {
+  const groups = [];
+  for (const o of spine.objectives || []) {
+    const total = (o.krs || []).reduce((n, k) => n + k.initiatives.length, 0) + ((o.direct || []).length);
+    for (const kr of o.krs || []) {
+      if (!kr.initiatives.length) continue;
+      groups.push({
+        gid: o.id + '/' + kr.id, idc: C.fg, gname: o.name, gct: String(total),
+        hasKr: true, krid: kr.id, krname: kr.name,
+        krct: String(kr.initiatives.length),
+        slugs: kr.initiatives.map((i) => i.id),
+      });
+    }
+    if ((o.direct || []).length) {
+      groups.push({
+        gid: o.id, idc: C.fg, gname: o.name, gct: String(total), hasKr: false,
+        slugs: o.direct.map((i) => i.id),
+      });
+    }
+  }
+  for (const b of spine.budgets || []) {
+    groups.push({
+      gid: b.id, idc: C.inf, gname: 'health budget — upkeep, not a bet',
+      gct: String(b.initiatives.length), hasKr: false, slugs: b.initiatives.map((i) => i.id),
+    });
+  }
+  // D59: rejected work is FILED, never hidden. It is the last group and it says what it is.
+  groups.push({
+    gid: 'unanchored', dyn: true, idc: C.wrn,
+    gname: 'no resolvable anchor — rejected work under D59',
+    gct: String((spine.unanchored || []).length), hasKr: false,
+    slugs: (spine.unanchored || []).map((i) => i.id),
+  });
+  return groups;
+}
+
+/* ── the workspace registry ─────────────────────────────────────────────────────────────────── */
+
+const products = new Map();   // product name → {name, ws, root, count, board, records}
+let productOrder = [];
+
+/** Group registered working trees into products: several worktrees of one repo share a `repo_key`. */
+function foldWorkspaces(rows) {
+  const byRepo = new Map();
+  for (const w of rows || []) {
+    const key = w.repo_key || w.root;
+    if (!byRepo.has(key)) {
+      byRepo.set(key, {
+        name: w.repo_name || w.name, ws: w.id, root: w.root, trees: [],
+        // The server derived this from the tree's `origin` remote (git-info.originUrl). It is read
+        // here and never re-derived: a second opinion about what a repository IS would be a second
+        // thing to keep true, and this one is the one that did the read.
+        kind: w.kind === 'github' ? 'github' : 'local', remote: w.remote || null,
+      });
+    }
+    const p = byRepo.get(key);
+    p.trees.push(w);
+    // The main worktree is the product's identity; prefer its id for reads scoped to `ws` — and its
+    // remote, since a linked worktree of the same repo answers with the same origin anyway.
+    if (w.root === key) {
+      p.ws = w.id;
+      p.kind = w.kind === 'github' ? 'github' : 'local';
+      p.remote = w.remote || null;
+    }
+  }
+  // Two distinct repositories can share a basename. Disambiguating with the parent directory keeps
+  // both rows on the board rather than silently merging one into the other.
+  const seen = new Map();
+  const out = [];
+  for (const p of byRepo.values()) {
+    let name = p.name;
+    if (seen.has(name)) {
+      const parent = String(p.root).split('/').slice(-2, -1)[0] || '';
+      name = parent ? parent + '/' + name : name + ' (' + p.ws + ')';
+    }
+    seen.set(p.name, true);
+    out.push({ ...p, name });
+  }
+  return out;
+}
+
+/** Load one product's board: the spine (structure) joined with the library (artifacts). */
+async function loadBoard(prod) {
+  const [spine, lib] = await Promise.all([
+    getJson('/api/console', { name: 'spine', ws: prod.ws }),
+    getJson('/api/library', { ws: prod.ws }),
+  ]);
+  if (spine.ok === false) {
+    prod.error = spine.error || 'the initiative spine could not be read';
+    prod.board = [];
+    prod.records = {};
+    prod.count = null;
+    return prod;
+  }
+  const artsById = new Map();
+  for (const i of (lib && lib.initiatives) || []) artsById.set(i.id, i.artifacts || []);
+
+  const groups = groupsFromSpine(spine);
+  const records = {};
+  const note = (rec, anchorHint) => {
+    records[rec.id] = lightRecord({ ...rec, anchorHint }, artsById.get(rec.id));
+  };
+  for (const o of spine.objectives || []) {
+    for (const kr of o.krs || []) for (const r of kr.initiatives) note(r, { canonical: o.key + '/' + kr.key });
+    for (const r of o.direct || []) note(r, { canonical: o.key });
+  }
+  for (const b of spine.budgets || []) for (const r of b.initiatives) note(r, { canonical: b.id });
+  for (const r of spine.unanchored || []) note(r, null);
+
+  // The library can see initiatives the SPINE has no record for: artifacts that group into a unit
+  // with no `planning/initiatives/<id>.md` behind them. They get their own group rather than being
+  // folded into `unanchored`, because the two are different facts and the panel says different
+  // things about them — "this record declares no resolvable anchor" (rejected under D59) is not
+  // "there is no record at all" (real files, no loop position claimed). Dropping them was never an
+  // option: they are documents that exist.
+  // Counted BEFORE the orphans are merged in — see `prod.count` below.
+  const spineCount = Object.keys(records).length;
+  const known = new Set(Object.keys(records));
+  const orphans = [...artsById.keys()].filter((id) => !known.has(id)).sort();
+  if (orphans.length) {
+    groups.push({
+      gid: 'no record', dyn: true, idc: C.wrn,
+      gname: 'artifacts with no initiative record — no loop position is claimed',
+      gct: String(orphans.length), hasKr: false, slugs: orphans,
+    });
+    for (const id of orphans) {
+      records[id] = {
+        ...lightRecord({ id, title: '', lane: null }, artsById.get(id)),
+        pills: [{ t: 'no record', c: C.wrn }],
+        l2: ['—', 'no record', C.wrn],
+      };
+    }
+  }
+
+  prod.error = null;
+  prod.board = groups;
+  prod.records = records;
+  // THE COUNT ON PANEL 1 IS THE SPINE'S, NOT THE RECORD MAP'S. `records` deliberately holds two
+  // different populations — the initiatives the spine placed, and the orphan groups above, which
+  // the very next panel labels "artifacts with no initiative record — no loop position is claimed".
+  // Sizing the row off the merged map made panel 1 read `176 initiatives` on a repository holding
+  // 138 placed records and 38 orphans: two numbers on one screen disagreeing, with the headline one
+  // inflated by 27% with items the app itself refuses to call initiatives. Panel 2 still shows the
+  // orphans, under their own honest heading; the row counts what it says it counts.
+  prod.count = spineCount;
+  prod.unrecorded = orphans.length;
+  return prod;
+}
+
+/** Publish every loaded product's board and records into state, in one patch. */
+function publishBoards() {
+  const board = {};
+  let records = {};
+  for (const name of productOrder) {
+    const p = products.get(name);
+    if (!p || !p.board) continue;
+    board[name] = p.board;
+    records = { ...records, ...p.records };
+  }
+  setState({ board, records: { ...records, ...(hydrated) } });
+}
+
+/* Hydrated (fully derived) records live apart from the light ones so that a board reload cannot
+ * silently downgrade the initiative the PM is looking at back to its light form. */
+const hydrated = Object.create(null);
+
+/* ── hydration: one initiative, fully derived ───────────────────────────────────────────────── */
+
+const inFlight = new Set();
+
+/* THE READ CLOCK, and why it lives here rather than in the renderer.
+ *
+ * Panel 3's footer says "derived on <branch> · as of <time>". That line's whole job is provenance:
+ * WHEN was what you are looking at read. It was first shipped as the design's literal `12:41:03` —
+ * a time at which nothing ever happened — and then fixed by calling the clock inside `footer()`,
+ * which measured the RENDER instead. The panel re-renders on any state change (a session poll, a
+ * theme toggle, a tab opening), while `hydrate` runs once per slug per page life — so the line
+ * advanced, untouched data underneath it, and read `as of 17:11:57` over a payload fetched twenty
+ * seconds earlier. A true measurement of the wrong event is still a false claim.
+ *
+ * So the stamp is taken HERE, at the instant the payload lands, and carried on the record. The
+ * renderer prints what it is given and owns no clock. */
+function readStamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+async function hydrate(slug) {
+  if (FIXTURE || !slug || inFlight.has(slug)) return null;
+  const prod = products.get(currentProductName());
+  const ws = prod ? prod.ws : null;
+  inFlight.add(slug);
+  try {
+    const payload = await getJson('/api/initiative', { id: slug, ws });
+    // Stamped after the await, on the line that follows the read — a failed read is still a read,
+    // and its footer ("read failed · as of …") is entitled to say when it was attempted.
+    const asOf = readStamp();
+    hydrated[slug] = { ...recordFrom(payload), asOf };
+    setState((s) => ({ records: { ...s.records, [slug]: hydrated[slug] } }));
+    return payload;
+  } finally { inFlight.delete(slug); }
+}
+
+function currentProductName() {
+  if (state.product && products.has(state.product)) return state.product;
+  return productOrder[0] || null;
+}
+
+/* ── sessions ───────────────────────────────────────────────────────────────────────────────
+ * Polled rather than pushed. The WebSocket that carries `sessions` frames belongs to panel 4's
+ * terminal module, which owns the attach/input protocol; opening a SECOND socket here to read a
+ * list would put two connections on the same server for one fact. A 4 s poll of a local endpoint
+ * is cheaper than the duplicate protocol and cannot disagree with itself.
+ */
+
+let pollTimer = null;
+
+async function pollSessions() {
+  if (FIXTURE) return;
+  const out = await getJson('/api/sessions');
+  if (out && Array.isArray(out.sessions)) {
+    setState({ sessions: out.sessions, runningCount: liveCount(out.sessions) });
+  }
+  schedulePoll();
+}
+
+function liveCount(rows) {
+  let n = 0;
+  for (const s of rows || []) if (s && (s.shown === 'working' || s.shown === 'needs')) n++;
+  for (const k in state.extraSess || {}) {
+    for (const s of state.extraSess[k] || []) {
+      // Started in this window and not yet visible in the server's list — counted once, by name.
+      if (s && (s.st === 'working' || s.st === 'needs') && !(rows || []).some((r) => r && r.name === s.name)) n++;
+    }
+  }
+  return n;
+}
+
+function schedulePoll() {
+  if (pollTimer) clearTimeout(pollTimer);
+  pollTimer = setTimeout(() => {
+    if (typeof document !== 'undefined' && document.hidden) { schedulePoll(); return; }
+    pollSessions();
+  }, 4000);
+}
+
+/* ══════════════════════════════════════════════════════════════════════════════════════════════
+ *  The exported surface. Every one of these is called by a panel module BY NAME — the signatures
+ *  are the panels', not this file's, and none of them may change without changing the caller.
+ * ════════════════════════════════════════════════════════════════════════════════════════════ */
+
+/**
+ * panel-repos.js — `loadRepos()`. The repository list, with a real initiative count per row.
+ * Each product's board is loaded here rather than lazily, because the count on the row IS the
+ * board's size: a row that said "— initiatives" until it was clicked would be a row that has not
+ * read anything.
+ *
+ * `kind` is the SERVER's answer, not a guess made here: /api/workspaces reports `remote` (the tree's
+ * `origin` URL, or null) and the `github`/`local` label derived from it, so a row says `github` only
+ * where a GitHub remote was actually read. It used to be hardcoded `local` on every row, which was
+ * honest but blind; inferring it from the presence of a `.git` folder — the other tempting fix —
+ * would put a provenance label on a row that no read supports.
+ */
+export async function loadRepos() {
+  if (FIXTURE) return [];
+  const out = await getJson('/api/workspaces');
+  const rows = foldWorkspaces(out && out.workspaces);
+  productOrder = rows.map((r) => r.name);
+  for (const r of rows) products.set(r.name, Object.assign(products.get(r.name) || {}, r));
+  await Promise.all(rows.map((r) => loadBoard(products.get(r.name))));
+  publishBoards();
+  const first = currentProductName();
+  const p = first ? products.get(first) : null;
+  // The selection is set explicitly rather than left to panel 2's fallback. The fallback picks the
+  // same row, but it picks it WITHOUT setting `sel` — so the row is not highlighted, and the
+  // hydration watcher below (which fires on a change to `sel`) never sees the initiative that is
+  // actually on screen. A restored selection from the PM's last session always wins.
+  const sel = state.sel || (p ? firstSlugOf(p.name) : null);
+  setState({
+    wsId: p ? p.ws : null,
+    connectors: [],          // no connector is configured — panel 3's approvals stay inert
+    product: state.product && products.has(state.product) ? state.product : first,
+    sel,
+  });
+  if (sel) hydrate(sel);
+  schedulePoll();
+  pollSessions();
+  return productOrder.map((name) => {
+    const prod = products.get(name);
+    return {
+      name,
+      kind: prod && prod.kind === 'github' ? 'github' : 'local',
+      count: prod && prod.count !== null ? prod.count : null,
+    };
+  });
+}
+
+/**
+ * panel-repos.js — `firstSlugOf(id)`, synchronous. The initiative selected when a repository is
+ * picked. A repository whose board is loaded and genuinely empty returns null, and panel 3 says so.
+ */
+export function firstSlugOf(id) {
+  const p = products.get(id);
+  if (!p || !p.board) return null;
+  for (const g of p.board) if (g.slugs && g.slugs.length) return g.slugs[0];
+  return null;
+}
+
+/**
+ * panel-repos.js — `loadInitiatives(id)`. The board for one repository, loaded if it is not
+ * already. Returns `{groups}` because that is the shape the caller's `firstSlugIn` reads.
+ */
+export async function loadInitiatives(id) {
+  if (FIXTURE) return { groups: [] };
+  let p = products.get(id);
+  if (!p) {
+    await loadRepos();
+    p = products.get(id);
+    if (!p) return { ok: false, error: 'no repository named ' + id + ' is registered', groups: [] };
+  }
+  if (!p.board) await loadBoard(p);
+  publishBoards();
+  if (p.error) return { ok: false, error: p.error, groups: [] };
+  return { ok: true, groups: p.board, records: p.records };
+}
+
+/**
+ * panel-repos.js — `addRepo({source, kind})`. Registering a local folder is a one-call write.
+ *
+ * A GitHub repository goes through the server's repo INGEST instead: the server clones it off the
+ * request path (the one sanctioned egress in this process, git's and not the browser's), scans it
+ * and proposes anchors that a human confirms one at a time. This function starts that and reports
+ * where it got to; it does NOT add a board row, because a row for a repository whose anchors have
+ * not been confirmed would be a board claiming work PMOS has not accepted.
+ */
+export async function addRepo({ source, kind }) {
+  if (FIXTURE) return { log: [] };
+  if (kind === 'local') {
+    const res = await postJson('/api/workspaces', { root: source, focus: false });
+    if (!res || res.ok === false) {
+      return { log: [{ t: 'refused — ' + ((res && res.error) || 'the folder could not be registered'), c: 'var(--destructive)' }] };
+    }
+    const w = res.workspace || {};
+    const rows = foldWorkspaces([{ ...w, repo_key: w.root, repo_name: w.name }]);
+    const p = rows[0];
+    products.set(p.name, Object.assign(products.get(p.name) || {}, p));
+    if (!productOrder.includes(p.name)) productOrder.push(p.name);
+    await loadBoard(products.get(p.name));
+    publishBoards();
+    const prod = products.get(p.name);
+    return {
+      repo: { name: p.name, kind: 'local', count: prod.count },
+      log: [
+        { t: 'registered ' + w.root, c: 'var(--muted-foreground)' },
+        prod.error
+          ? { t: 'the initiative spine could not be read — ' + prod.error, c: 'var(--destructive)' }
+          : { t: 'read planning/ … ' + (prod.count || 0) + ' initiative record(s)', c: 'var(--muted-foreground)' },
+        { t: 'done — ' + p.name + ' added', c: 'var(--success)' },
+      ],
+    };
+  }
+  const res = await postJson('/api/ingest', { source: 'github', ref: source });
+  if (!res || res.ok === false) {
+    return { log: [{ t: 'refused — ' + ((res && res.error) || 'the ingest could not be started'), c: 'var(--destructive)' }] };
+  }
+  return {
+    log: [
+      { t: 'ingest ' + res.id + ' started — clone and scan run off the request path', c: 'var(--muted-foreground)' },
+      { t: 'anchors are PROPOSED by the scan and confirmed one at a time — nothing is on the board yet', c: 'var(--warning)' },
+    ],
+  };
+}
+
+/**
+ * panel-tabs.js — `startSession(slug, sess)`. Deliberately NOT a spawn.
+ *
+ * panel 4's terminal module owns session creation: it holds the WebSocket, and it spawns a PTY for
+ * exactly the sessions that were started in this window. Spawning one here as well would start two
+ * agents for one click and give the PM a tab attached to whichever won. What this hook does is
+ * refresh the session list soon enough that the new PTY appears in `state.sessions` — the join the
+ * board and the status bar read.
+ */
+export function startSession(slug, sess) {
+  if (FIXTURE) return;
+  void slug; void sess;
+  setTimeout(pollSessions, 800);
+}
+
+/** tab-doc.js — `readDoc(path)`. The raw document body, or a rejected promise carrying the reason. */
+export async function readDoc(path) {
+  if (FIXTURE) return '';
+  const p = products.get(currentProductName());
+  const url = '/api/doc?' + q({ ws: state.wsId || (p ? p.ws : ''), path });
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(res.status === 404 ? 'not a readable text document in this workspace' : 'HTTP ' + res.status);
+  return res.text();
+}
+
+/**
+ * tab-doc.js — `saveDoc({ws, path, base, text})`. Refuse-on-stale: the server compares `base`
+ * against the file on disk and REFUSES rather than overwriting a file that changed underneath.
+ * The refusal is returned as `{ok:false,error}` and the caller keeps the buffer.
+ */
+export async function saveDoc({ ws, path, base, text }) {
+  if (FIXTURE) return { ok: true };
+  const p = products.get(currentProductName());
+  return postJson('/api/doc/save', { ws: ws || state.wsId || (p ? p.ws : ''), path, base, text, pm: true });
+}
+
+/**
+ * panel-detail.js — `recordArtifactLink({artifact_path, slug, kind, target})`.
+ * Appends ONE declaration to `artifact-links.jsonl`. It contacts nothing: PMOS holds no credential,
+ * so this records what the PM says the mapping is and says nothing about the destination.
+ */
+export async function recordArtifactLink({ artifact_path, slug, kind, target }) {
+  if (FIXTURE) return { ok: true };
+  const p = products.get(currentProductName());
+  const out = await postJson('/api/initiative/link', {
+    store: 'artifact', ws: state.wsId || (p ? p.ws : ''),
+    initiative_id: slug, artifact_path,
+    // The surface labels a Google destination `google doc`; the store's vocabulary is `google`.
+    kind: String(kind || '').startsWith('google') ? 'google' : kind,
+    target,
+  });
+  if (out && out.ok === false) console.warn('[pm] the artifact link was NOT recorded: ' + out.error);
+  return out;
+}
+
+/** panel-detail.js — `recordInitiativeLink({slug, kind, label, path, st})` → `initiative-links.jsonl`. */
+export async function recordInitiativeLink({ slug, kind, label, path }) {
+  if (FIXTURE) return { ok: true };
+  const p = products.get(currentProductName());
+  const out = await postJson('/api/initiative/link', {
+    store: 'initiative', ws: state.wsId || (p ? p.ws : ''),
+    initiative_id: slug, kind, label, target: path,
+  });
+  if (out && out.ok === false) console.warn('[pm] the reference link was NOT recorded: ' + out.error);
+  return out;
+}
+
+/**
+ * app.js — `runningCount(state)`. The status bar's number: live PTYs the server reports as working
+ * or needing the PM, plus any started in this window the server has not listed yet.
+ */
+export function runningCount(s) {
+  // DECLINE in fixture mode rather than answering 0. Returning a number here is an answer, and
+  // app.js quite correctly takes the first answer it gets — so `0` shadowed the fixture's own
+  // count and the status bar read "0 sessions running" against a seed board with three. It cost a
+  // parity failure on a bar that is otherwise pixel-identical. Null means "not mine to answer".
+  if (FIXTURE) return null;
+  return liveCount((s && s.sessions) || state.sessions || []);
+}
+
+/* ── keeping the selection hydrated ──────────────────────────────────────────────────────────
+ * The PM selects an initiative in panel 2 and panel 3 must show its ladder. Rather than making
+ * every panel call this module, the selection is watched here: one subscription, one fetch per
+ * newly selected initiative, and a repaint when it lands.
+ */
+if (!FIXTURE) {
+  let lastSel = null, lastProduct = null;
+  subscribe(() => {
+    if (state.product !== lastProduct) {
+      lastProduct = state.product;
+      const p = products.get(state.product);
+      if (p && p.ws && state.wsId !== p.ws) setState({ wsId: p.ws });
+      if (p && !p.board) loadInitiatives(state.product);
+    }
+    const sel = state.sel;
+    if (sel && sel !== lastSel) {
+      lastSel = sel;
+      if (!hydrated[sel]) hydrate(sel);
+    }
+  });
+}