create-pmos 0.13.0 → 0.15.0

package/workspace/lib/focus.js

@@ -0,0 +1,967 @@
+'use strict';
+/*
+ * focus.js — the Focus queue (workspace-focus R2–R10).
+ *
+ * ONE question, asked across every registered tree: **what does only a human unblock?**
+ *
+ * The workspace already computes everything Focus shows — a board per tree, a needs-you queue per
+ * tree, a spine per tree, one session list for all of them. What it has never done is the join, and
+ * the join is the whole product: the PM currently opens a product, reads a ladder, decides whether
+ * that blocked step is his or an agent's, switches product, repeats. This module is that decision,
+ * written down once so it is checkable instead of re-made by hand every morning.
+ *
+ * ── THE MEMBERSHIP RULE IS THE SPEC (PRD "The membership rule") ─────────────────────────────────
+ * An item enters `queue` ONLY if closing it is an act no agent can perform. Everything else — the
+ * agent that is mid-run, the step a skill can fix by writing a file, the board another team owns —
+ * belongs in `delegated` or `handoffs`.
+ *
+ * The rule is ENUMERATED, not heuristic, and the classifiers below are TOTAL over their domains.
+ * That distinction is the point: a filter list ("exclude route, prototype, understand, …") admits
+ * the thirteenth step key the day someone adds it to the engine, silently, and the queue grows by
+ * one item nobody chose. `classifyStep` answers for every (key, status) pair including the ones
+ * that do not exist yet, and its answer for those is NO with a stated reason.
+ *
+ * The failure that looks like success is a FULL queue. A long list containing every blocked ladder
+ * step and every running session is correct-looking, comprehensive, photographs well, and is
+ * worthless within a week — the one item that was actually the PM's is now item nine of thirty.
+ * The value is entirely in what this refuses.
+ *
+ * ── PURE BY CONSTRUCTION ────────────────────────────────────────────────────────────────────────
+ * `buildFocus` does NO I/O: no filesystem, no git, no clock, no DOM. It takes reads that the caller
+ * already performed and returns a shape. Three consequences, all deliberate:
+ *
+ *   1. It is testable over its whole domain rather than sampled against a live machine.
+ *   2. It cannot accidentally call `consoleState.workflow()` on the request path — the ~30 s
+ *      synchronous derivation that freezes every PTY socket (board-cache.js:5–12, PRD R12). Boards
+ *      arrive here already read, through `boardCache.board()`, or they do not arrive at all.
+ *   3. Anything it cannot be told, it cannot claim. The on-disk skill index (R8) and the health
+ *      budget registry (R10) are INPUTS; when they are not supplied the answer is a stated
+ *      "not read", never a guess and never an offer PMOS could not honour.
+ *
+ * ── HONEST STATES, RESTATED WHERE THIS FILE CAN VIOLATE THEM ────────────────────────────────────
+ *   · a failed read is RED and carries the reader's own string, never a paraphrase;
+ *   · a successful read of nothing is CALM — an empty queue is the good outcome;
+ *   · an ABSENCE is stated in its own words (handoffs, memory), which are not "empty"'s words;
+ *   · DERIVING is a third state — a `pending` board is neither empty nor broken;
+ *   · no verdict recorded is not a pass.
+ *
+ * `count` is `queue.length`, computed at the end of every call. There is no cached total and no
+ * second code path — R5's rule exists because a stored counter is how a badge starts disagreeing
+ * with the list under it. And a BARE NUMBER is forbidden whenever a contributing read failed, is
+ * still deriving, or was never supplied: render `badge.text`, never `count`.
+ */
+
+const sessionState = require('./session-state');
+
+// ── Tiers ───────────────────────────────────────────────────────────────────────────────────────
+// The handoff's four tiers, plus 2b. `order` sorts; `tier` is the label the PM sees, and it keeps
+// the "2b" wording so the surface and the PRD name the same thing.
+//
+// Tier 3 is DECLARED AND ALWAYS EMPTY in this build. Nothing in this repository can read another
+// team's board, so no item can ever be built for it. It is not dropped — `handoffs` renders the
+// absence in words (R9) — because a tier that quietly vanishes reads as "there is nothing of that
+// kind", which is a claim about someone else's work derived from no connection at all.
+const TIERS = [
+  { id: 'integrity', order: 1, tier: '1', label: 'board integrity' },
+  { id: 'gate', order: 2, tier: '2', label: 'contract / gate' },
+  { id: 'session', order: 3, tier: '2b', label: 'a session is waiting on you' },
+  { id: 'handoff', order: 4, tier: '3', label: 'handoff blockers' },
+  { id: 'intake', order: 5, tier: '4', label: 'intake' },
+];
+const TIER = {};
+for (const t of TIERS) TIER[t.id] = t;
+
+// ── The ladder's step vocabulary ────────────────────────────────────────────────────────────────
+// Emission order from `computeWorkflow` (scripts/workflow-state.js). Listed here so a test can walk
+// the domain; NOT used as a filter — see `classifyStep`, which answers for keys absent from this
+// list too.
+const STEP_KEYS = ['route', 'anchor', 'prototype', 'understand', 'spec', 'priors',
+  'contract', 'build', 'quality', 'review', 'explain', 'accept'];
+const STEP_STATUSES = ['done', 'current', 'blocked', 'pending', 'na', 'unknown'];
+
+/*
+ * The three ladder positions the engine itself says are the PM's, quoted from the engine.
+ *
+ * There are exactly three, and each one is a sentence in `scripts/workflow-state.js` naming the PM
+ * as the actor. No fourth position is inferred: the moment this table is extended by judgement
+ * rather than by a quotation, the queue starts holding work an agent could have done.
+ */
+const PM_STEPS = {
+  contract: {
+    blocked: {
+      tier: TIER.gate,
+      why: 'the pre-run contract needs numbered done_criteria + test_method agreed WITH THE PM — runs are logged against this initiative with no PM_approved line',
+      reason: 'workflow-state.js:600 — "agree numbered done_criteria + test_method with the PM"',
+    },
+  },
+  accept: {
+    pending: {
+      tier: TIER.gate,
+      why: 'the PM Acceptance Gate is open and non-delegable (D12) — no agent can close it',
+      reason: 'workflow-state.js:670 — "PM Acceptance Gate open — non-delegable (D12)"',
+    },
+  },
+  anchor: {
+    blocked: {
+      tier: TIER.intake,
+      why: 'this initiative is unanchored or names something the OKR documents do not declare — adding the KR, or a budget, is a PM act',
+      reason: 'workflow-state.js:359/:371 — "add the KR (a PM act)" / "only the PM adds a budget"',
+    },
+  },
+};
+
+// Why each REFUSAL is a refusal. Every one of these is a sentence the engine or the PRD already
+// says; they are carried so a PM auditing an absence gets the reason rather than silence.
+const STEP_REFUSALS = {
+  'accept/blocked': 'the Acceptance Gate does not open over an unfinished ladder (workflow-state.js:669) — admitting these would put every in-flight initiative in the queue and destroy it',
+  'contract/pending': 'no run is logged for this initiative yet — nothing has been built without a contract, so nothing is owed',
+  'build/*': 'build is a fact about commits, not a request to the PM',
+  'quality/*': 'quality is always unknown by design — the engine never claims a test result it did not run (workflow-state.js:620)',
+};
+// Every blocked step outside PM_STEPS whose `next` names an agent act. These are `delegated`'s raw
+// material (R8), never the queue's.
+const AGENT_ACT_STEPS = ['route', 'prototype', 'understand', 'spec', 'priors', 'review', 'explain'];
+
+/**
+ * TOTAL over (step key × status), including keys and statuses that do not exist.
+ *
+ * → { qualifies, tier, why, reason }
+ *   `tier` is a TIERS entry when it qualifies, otherwise null.
+ *   `reason` is always populated — it states why the answer is what it is, for admits AND refusals.
+ *
+ * The default arm is the load-bearing one: an unrecognised key defaults OUT. A step the engine
+ * grows next quarter cannot appear in the PM's queue until someone quotes the engine saying it is
+ * the PM's.
+ */
+function classifyStep(key, status) {
+  const k = key == null ? '' : String(key);
+  const s = status == null ? '' : String(status);
+  const rule = PM_STEPS[k] && PM_STEPS[k][s];
+  if (rule) return { qualifies: true, tier: rule.tier, why: rule.why, reason: rule.reason };
+
+  let reason = STEP_REFUSALS[`${k}/${s}`] || STEP_REFUSALS[`${k}/*`] || null;
+  if (!reason) {
+    if (!STEP_KEYS.includes(k)) {
+      reason = `'${k || '(unnamed)'}' is not one of the engine's step keys — a step key added later defaults OUT of the queue, never in`;
+    } else if (!STEP_STATUSES.includes(s)) {
+      reason = `'${s || '(unnamed)'}' is not one of the engine's step statuses — an unrecognised status defaults OUT of the queue`;
+    } else if (AGENT_ACT_STEPS.includes(k)) {
+      reason = s === 'blocked'
+        ? `the \`next\` for a blocked ${k} names an agent act — it belongs in delegated, not the queue`
+        : `${k} is ${s}; nothing is being asked of the PM`;
+    } else {
+      reason = `${k} is ${s}; the engine asks nothing of the PM here`;
+    }
+  }
+  return { qualifies: false, tier: null, why: null, reason };
+}
+
+/**
+ * TOTAL over the presented session states (lib/session-state's PRESENTED), plus anything else.
+ *
+ * Only `needs` admits, and it admits because `presented()` reaches it ONLY from quiet + turn 'user'
+ * — the turn ended and nothing is moving. That is the most literal instance of "you are the
+ * blocker" this system holds, and it is already derived honestly by a module built for the claim.
+ *
+ * `blocked` is the judgement call and it is refused: session-state.js:57 is explicit that the
+ * evidence cannot separate a permission prompt from a hung tool from a corpse. A queue whose intro
+ * promises "you are the blocker" may not be filled with maybes. It reaches `delegated` instead,
+ * carrying the module's own hedged word verbatim.
+ */
+function classifySession(shown) {
+  const p = shown == null ? '' : String(shown);
+  if (p === 'needs') {
+    return {
+      qualifies: true,
+      tier: TIER.session,
+      why: 'the turn ended and nothing is moving — this session is waiting on you',
+      reason: "session-state.js:100 — `needs` is reachable only from quiet + turn 'user'",
+    };
+  }
+  const refusals = {
+    working: 'an agent is producing bytes — the most common thing on screen and the most tempting thing to count',
+    quiet: 'quiet carries no claim on the PM',
+    exited: 'an exited session carries no claim on the PM',
+    blocked: "the evidence cannot separate a permission prompt from a hung tool from a corpse — it appears in delegated carrying its own 'maybe blocked' hedge",
+  };
+  return {
+    qualifies: false,
+    tier: null,
+    why: null,
+    reason: refusals[p] || `'${p || '(unnamed)'}' is not a presented session state — an unrecognised state defaults OUT of the queue`,
+  };
+}
+
+/**
+ * TOTAL over needs-queue items. Three admit:
+ *   · kind 'accept'  — an eval with no acceptance for its run_id (deriveNeeds, server.js:1855)
+ *   · kind 'outcome' — a declared outcome past its horizon, never disposed (D57)
+ *   · derived !== true — the harness filed it against the PM by name, whatever it called it
+ * Anything else the derivation grows later defaults out.
+ */
+function classifyNeed(kind, derived) {
+  const k = kind == null ? '' : String(kind);
+  if (derived !== true) {
+    return {
+      qualifies: true, tier: TIER.gate,
+      why: 'the harness filed this against you by name — it is not derived, someone asked',
+      reason: 'needs.json entry with derived !== true',
+    };
+  }
+  if (k === 'accept') {
+    return {
+      qualifies: true, tier: TIER.gate,
+      why: 'an eval has been recorded and no acceptance names its run — the Acceptance Gate is open (D12)',
+      reason: 'deriveNeeds (server.js:1855) — evals.jsonl run_id with no row in acceptances.jsonl',
+    };
+  }
+  if (k === 'outcome') {
+    return {
+      qualifies: true, tier: TIER.gate,
+      why: 'a declared outcome is past its horizon and has never been disposed — the D57 check is due',
+      reason: 'deriveNeeds (server.js:1866) — outcome_horizon in the past, no row in outcome_checks.jsonl',
+    };
+  }
+  return {
+    qualifies: false, tier: null, why: null,
+    reason: `a derived need of kind '${k || '(unnamed)'}' is not one of the two enumerated derivations — it defaults OUT of the queue`,
+  };
+}
+
+// ── Normalising the inputs ──────────────────────────────────────────────────────────────────────
+// Every reader this module joins has its own shape and its own failure mode. Each `read*` below
+// turns one of them into a single vocabulary — state ∈ ok | empty | deriving | error | not-read —
+// so the join never has to ask "which of these four shapes is a failure again?".
+//
+// `not-read` is deliberately NOT `error`. A read that FAILED produces a reader's own reason and is
+// the PM's problem; a read that never HAPPENED is a plumbing gap in the caller, and reporting it as
+// a broken repository sends the PM looking for a fault they do not have. Both suppress the bare
+// count, in different words.
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+const str = (v) => (v == null ? '' : String(v));
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * `boardCache.board(root)` → one of:
+ *   { pending:true, refreshing, as_of:null, stale:false }              never derived yet
+ *   { ok:false, error, as_of, stale }                                  the derivation failed
+ *   { ok:true, empty:true, source, as_of, stale }                      a repo with no records
+ *   { ok:true, empty:false, data:{ live, hidden, total, unreadable, … }, as_of, stale, refreshing }
+ */
+function readBoard(board) {
+  const base = { rows: [], unreadable: [], shown: 0, hidden: 0, total: 0, as_of: null, stale: false, refreshing: false, error: null };
+  if (board == null) {
+    return Object.assign(base, { state: 'not-read', error: 'no board read was supplied for this product — nothing about its ladders can be claimed here' });
+  }
+  if (!isObj(board)) {
+    return Object.assign(base, { state: 'error', error: 'the board read returned something that is not an object — the source is broken, not empty' });
+  }
+  const env = { as_of: board.as_of == null ? null : str(board.as_of), stale: !!board.stale, refreshing: !!board.refreshing };
+  if (board.pending === true) return Object.assign(base, env, { state: 'deriving' });
+  if (board.ok === false) {
+    return Object.assign(base, env, { state: 'error', error: str(board.error) || 'the board derivation failed and gave no reason' });
+  }
+  if (board.ok !== true) {
+    return Object.assign(base, env, { state: 'error', error: 'the board read returned neither a result, a failure nor a pending derivation — an unrecognised shape' });
+  }
+  if (board.empty === true || !isObj(board.data)) {
+    // A repo with no initiative records at all is a successful read of nothing — calm, not red.
+    return Object.assign(base, env, { state: 'empty' });
+  }
+  const d = board.data;
+  const rows = arr(d.live).filter(isObj);
+  return Object.assign(base, env, {
+    state: 'ok',
+    rows,
+    unreadable: arr(d.unreadable).filter(isObj),
+    shown: rows.length,
+    hidden: Number.isFinite(d.hidden) ? d.hidden : 0,
+    total: Number.isFinite(d.total) ? d.total : rows.length,
+  });
+}
+
+/**
+ * `needsResult(w)` → { ok:false, error } | { ok:true, empty:true } | { ok:true, empty:false, data:{items} }
+ */
+function readNeeds(needs) {
+  if (needs == null) return { state: 'not-read', items: [], error: 'no needs-you read was supplied for this product' };
+  if (!isObj(needs)) return { state: 'error', items: [], error: 'the needs-you read returned something that is not an object — corrupt state, not empty' };
+  if (needs.ok === false) return { state: 'error', items: [], error: str(needs.error) || 'the needs-you queue could not be read and gave no reason' };
+  if (needs.ok !== true) return { state: 'error', items: [], error: 'the needs-you read returned neither a result nor a failure — an unrecognised shape' };
+  if (needs.empty === true || !isObj(needs.data)) return { state: 'empty', items: [], error: null };
+  return { state: 'ok', items: arr(needs.data.items).filter(isObj), error: null };
+}
+
+/**
+ * `surfaceSpine(root)` → { objectives, budgets, unanchored, unreadable, budgets_readable }
+ * `unreadable` is a STRING when the anchor resolver or the OKR documents could not be read.
+ */
+function readSpine(spine) {
+  const base = { objectives: [], budgets: [], unanchored: [], budgets_readable: null, error: null };
+  if (spine == null) return Object.assign(base, { state: 'not-read', error: 'no spine read was supplied for this product' });
+  if (!isObj(spine)) return Object.assign(base, { state: 'error', error: 'the spine read returned something that is not an object' });
+  if (spine.unreadable) return Object.assign(base, { state: 'error', error: str(spine.unreadable) });
+  if (!Array.isArray(spine.objectives) || !Array.isArray(spine.unanchored)) {
+    return Object.assign(base, { state: 'error', error: 'the spine read returned no objectives/unanchored lists — the source is malformed, not empty' });
+  }
+  return {
+    state: 'ok',
+    objectives: spine.objectives.filter(isObj),
+    budgets: arr(spine.budgets).filter(isObj),
+    unanchored: spine.unanchored.filter(isObj),
+    budgets_readable: spine.budgets_readable == null ? null : !!spine.budgets_readable,
+    error: null,
+  };
+}
+
+/**
+ * Extra per-initiative ladders, from `consoleState.ladder({root,id})`. Accepts an array of rows, an
+ * array of `{ok,row}` envelopes, or a map keyed by id. Anything unrecognised is ignored rather than
+ * guessed at.
+ *
+ * Where an id appears in BOTH the board and here, this wins: the board is served from a cache up to
+ * ten minutes old (board-cache MAX_AGE_MS), while a single-initiative ladder is derived on demand
+ * and therefore never the older of the two.
+ */
+function readLadders(ladders) {
+  const rows = [];
+  const failed = [];
+  const take = (v, keyHint) => {
+    if (!isObj(v)) return;
+    if (v.ok === false) {
+      failed.push({ id: str(v.id || keyHint) || '(unnamed)', error: str(v.error) || 'this ladder could not be derived and gave no reason' });
+      return;
+    }
+    const row = isObj(v.row) ? v.row : v;
+    if (v.empty === true && !isObj(v.row)) return;              // a successful read of "no such record"
+    if (Array.isArray(row.steps)) rows.push(row);
+  };
+  if (Array.isArray(ladders)) for (const v of ladders) take(v, null);
+  else if (isObj(ladders)) for (const k of Object.keys(ladders)) take(ladders[k], k);
+  return { rows, failed };
+}
+
+// ── Products ────────────────────────────────────────────────────────────────────────────────────
+/*
+ * Focus is cross-product by definition, so `products` is the real input and the top-level
+ * `board`/`needs`/`spine`/`ladders` are the ONE-product convenience form.
+ *
+ * The fallback is deliberately refused when more than one product is present. A single top-level
+ * board shared across several trees would attribute one repository's ladders to all of them —
+ * quietly, plausibly, and wrongly. Sessions are the exception and are always partitioned from the
+ * top-level list, because `sessionList()` rows carry `ws` and can therefore be split without a
+ * guess.
+ */
+function normalizeProducts(inp) {
+  const declared = arr(inp.products).filter(isObj);
+  const list = declared.length ? declared : [{}];
+  const single = list.length === 1;
+  const allSessions = arr(inp.sessions).filter(isObj);
+  return list.map((p, i) => {
+    const id = p.id == null ? (declared.length ? null : (inp.product == null ? null : str(inp.product))) : str(p.id);
+    const name = str(p.name || p.label || '') || (id || '');
+    const has = (k) => Object.prototype.hasOwnProperty.call(p, k) && p[k] != null;
+    const sessions = has('sessions')
+      ? arr(p.sessions).filter(isObj)
+      : (id ? allSessions.filter((s) => str(s.ws) === id) : allSessions);
+    return {
+      id,
+      name,
+      // sortKey keeps the order stable between renders (product name, then id, then position), so a
+      // rank number means something across two consecutive looks at the same screen. The separator
+      // is NUL because nothing in a product name or an id can contain it, so two fields can never
+      // run together into a false ordering — but it is written as the ESCAPE `\x00`, never as a
+      // literal byte. A raw NUL makes the file binary to git diff, grep and ripgrep, and ripgrep
+      // then skips it silently: the largest module in this batch was invisible to every source
+      // search anyone ran over it. Same string at runtime, same file readable by the tools.
+      sortKey: `${name.toLowerCase()}\x00${(id || '').toLowerCase()}\x00${String(i).padStart(4, '0')}`,
+      board: readBoard(has('board') ? p.board : (single ? inp.board : null)),
+      needs: readNeeds(has('needs') ? p.needs : (single ? inp.needs : null)),
+      spine: readSpine(has('spine') ? p.spine : (single ? inp.spine : null)),
+      ladders: readLadders(has('ladders') ? p.ladders : (single ? inp.ladders : null)),
+      sessions,
+    };
+  });
+}
+
+// ── `read:` lines ───────────────────────────────────────────────────────────────────────────────
+// R4: every queue row carries one mono line naming WHAT WAS ACTUALLY READ. It is not decoration —
+// it is what lets the PM check the queue instead of trusting it, so it names real files and real
+// fields and never a summary of them. The `read:` label itself belongs to the caller; these strings
+// are the content after it.
+function boardRead(b) {
+  if (b.state === 'not-read') return 'board — not read';
+  if (b.state === 'deriving') return 'boardCache.board() — deriving, never yet returned a result';
+  const at = b.as_of ? `board as_of ${b.as_of}` : 'board (no as_of recorded)';
+  return b.stale ? `${at} (stale, refresh running)` : at;
+}
+function stepRead(b, row, step) {
+  const parts = [boardRead(b)];
+  if (row.record) parts.push(str(row.record));
+  parts.push(`ladder step ${step.key} (${step.status})`);
+  const ev = str(step.evidence).trim();
+  return ev ? `${parts.join(' · ')} — ${ev}` : parts.join(' · ');
+}
+
+// ── The queue ───────────────────────────────────────────────────────────────────────────────────
+function item(product, tier, fields) {
+  return Object.assign({
+    tier: tier.tier, tierId: tier.id, tierOrder: tier.order, tierLabel: tier.label,
+    product: product.id, productName: product.name || product.id || null,
+    title: null, detail: null, action: null,
+    // internal join/sort keys, stripped once the queue is ranked
+    dedup: null, sortKey: product.sortKey,
+  }, fields);
+}
+
+/**
+ * TIER 1 · board integrity — the board itself, or a record under it, could not be read.
+ * Nothing below a failed read can be trusted, so these lead the queue however few they are.
+ */
+function integrityItems(p) {
+  const out = [];
+  if (p.board.state === 'error') {
+    out.push(item(p, TIER.integrity, {
+      kind: 'board-unreadable', id: `board:${p.id || 'workspace'}`, subject: p.id || 'workspace',
+      dedup: `board:${p.id || 'workspace'}`,
+      why: 'the board itself could not be derived — nothing below it can be trusted',
+      detail: p.board.error,
+      read: `${boardRead(p.board)} — ok:false · ${p.board.error}`,
+      target: { kind: 'product', product: p.id, id: null },
+    }));
+  }
+  // Reported over ALL records, not just the capped 12 (console-state.js:214) — so an unparseable
+  // record cannot hide behind the board's in-flight cap.
+  for (const u of p.board.unreadable) {
+    const id = str(u.id) || '(unnamed record)';
+    out.push(item(p, TIER.integrity, {
+      kind: 'record-unreadable', id: `record:${p.id || ''}:${id}`, subject: id, dedup: `record:${id}`,
+      why: 'this initiative record will not parse — only its author\'s intent can fix it',
+      detail: str(u.error) || null,
+      read: `${boardRead(p.board)} · unreadable[] row ${id}${u.error ? ` — ${str(u.error)}` : ''}`,
+      target: { kind: 'initiative', product: p.id, id },
+    }));
+  }
+  for (const f of p.ladders.failed) {
+    out.push(item(p, TIER.integrity, {
+      kind: 'record-unreadable', id: `record:${p.id || ''}:${f.id}`, subject: f.id, dedup: `record:${f.id}`,
+      why: 'this initiative record will not parse — only its author\'s intent can fix it',
+      detail: f.error,
+      read: `consoleState.ladder({id:'${f.id}'}) — ok:false · ${f.error}`,
+      target: { kind: 'initiative', product: p.id, id: f.id },
+    }));
+  }
+  if (p.needs.state === 'error') {
+    out.push(item(p, TIER.integrity, {
+      kind: 'needs-unreadable', id: `needs:${p.id || 'workspace'}`, subject: p.id || 'workspace',
+      dedup: `needs:${p.id || 'workspace'}`,
+      why: 'the needs-you queue is corrupt or unreadable — a broken honesty surface must read red, never zero',
+      detail: p.needs.error,
+      read: `needsResult() over needs.json + evals.jsonl/acceptances.jsonl — ok:false · ${p.needs.error}`,
+      target: { kind: 'product', product: p.id, id: null },
+    }));
+  }
+  if (p.spine.state === 'error') {
+    out.push(item(p, TIER.integrity, {
+      kind: 'spine-unreadable', id: `spine:${p.id || 'workspace'}`, subject: p.id || 'workspace',
+      dedup: `spine:${p.id || 'workspace'}`,
+      why: 'the OKR documents or the anchor resolver could not be read — every anchor below them is unverifiable',
+      detail: p.spine.error,
+      read: `surfaceSpine() — unreadable · ${p.spine.error}`,
+      target: { kind: 'product', product: p.id, id: null },
+    }));
+  }
+  return out;
+}
+
+/** The ladder rows Focus reasons over: the board's in-flight rows, overridden by any on-demand
+ *  ladder for the same id (fresher — see `readLadders`). */
+function ladderRows(p) {
+  const byId = new Map();
+  for (const r of p.board.rows) if (r && r.id != null && Array.isArray(r.steps)) byId.set(str(r.id), r);
+  for (const r of p.ladders.rows) if (r && r.id != null) byId.set(str(r.id), r);
+  return [...byId.values()];
+}
+
+/** TIERS 2 and 4 from the ladder — the three PM steps and nothing else. */
+function ladderItems(p) {
+  const out = [];
+  for (const row of ladderRows(p)) {
+    const id = str(row.id);
+    for (const step of arr(row.steps)) {
+      if (!isObj(step)) continue;
+      const c = classifyStep(step.key, step.status);
+      if (!c.qualifies) continue;
+      out.push(item(p, c.tier, {
+        kind: str(step.key), id: `${c.tier.id}:${p.id || ''}:${id}:${str(step.key)}`, subject: id,
+        dedup: step.key === 'anchor' ? `anchor:${id}` : `${str(step.key)}:${id}`,
+        title: row.title == null ? null : str(row.title),
+        why: c.why,
+        detail: step.evidence == null ? null : str(step.evidence),
+        action: step.next == null ? null : str(step.next),
+        read: stepRead(p.board, row, step),
+        target: { kind: 'initiative', product: p.id, id },
+      }));
+    }
+  }
+  return out;
+}
+
+/** TIER 2 from the needs-you queue. */
+function needsItems(p) {
+  const out = [];
+  for (const n of p.needs.items) {
+    const c = classifyNeed(n.kind, n.derived);
+    if (!c.qualifies) continue;
+    const runId = str(n.run_id) || '(no run_id)';
+    const initId = n.initiative_id == null ? null : str(n.initiative_id);
+    const kind = str(n.kind) || 'question';
+    let read;
+    if (n.derived !== true) read = `needs.json — entry filed by the harness (kind ${kind}, run_id ${runId})`;
+    else if (kind === 'accept') read = `evals.jsonl run_id ${runId} · acceptances.jsonl — no acceptance row for that run_id`;
+    else read = `state initiatives/${initId || '?'}.md outcome_metric + outcome_horizon · outcome_checks.jsonl — no disposal recorded`;
+    out.push(item(p, c.tier, {
+      kind: `need-${kind}`, id: `need:${p.id || ''}:${runId}`, subject: initId || runId,
+      dedup: `need:${runId}`,
+      why: c.why,
+      detail: n.question == null ? null : str(n.question),
+      read,
+      target: { kind: initId ? 'initiative' : 'product', product: p.id, id: initId },
+    }));
+  }
+  return out;
+}
+
+/** TIER 2b · a session whose turn ended with nothing moving. */
+function sessionItems(p) {
+  const out = [];
+  for (const s of p.sessions) {
+    const c = classifySession(s.shown);
+    if (!c.qualifies) continue;
+    const id = str(s.id);
+    out.push(item(p, c.tier, {
+      kind: 'session-needs', id: `session:${id}`, subject: id, dedup: `session:${id}`,
+      title: s.name == null ? null : str(s.name),
+      why: c.why,
+      detail: s.lastWords == null ? null : str(s.lastWords),
+      read: `sessionList() session ${id}${s.agent ? ` (${str(s.agent)})` : ''} · session-state.presented() → shown '${str(s.shown)}'`
+        + (Number.isFinite(s.quietMs) ? ` · quiet ${s.quietMs}ms` : ''),
+      target: { kind: 'session', product: p.id, id },
+    }));
+  }
+  return out;
+}
+
+/**
+ * TIER 4 · intake, from the spine. `surfaceSpine().unanchored[]` is UNCAPPED, which is exactly why
+ * the intake tier reads it: anchor faults escape the board's in-flight cap of 12 through this list.
+ */
+function unanchoredItems(p) {
+  const out = [];
+  for (const u of p.spine.unanchored) {
+    const id = str(u.id) || '(unnamed record)';
+    out.push(item(p, TIER.intake, {
+      kind: 'unanchored', id: `unanchored:${p.id || ''}:${id}`, subject: id, dedup: `anchor:${id}`,
+      title: u.title == null ? null : str(u.title),
+      why: 'this initiative is unanchored or names something the OKR documents do not declare — adding the KR, or a budget, is a PM act',
+      detail: u.reason == null ? null : str(u.reason),
+      read: `surfaceSpine().unanchored[] ${id}${u.file ? ` (${str(u.file)})` : ''} — parent_kr '${str(u.raw)}' · status ${str(u.status) || 'unresolved'}`,
+      target: { kind: 'initiative', product: p.id, id },
+    }));
+  }
+  return out;
+}
+
+/*
+ * The ladder's `anchor` step and the spine's `unanchored[]` row are TWO VIEWS OF ONE FACT, not two
+ * facts. Listing both would inflate the queue with duplicates — the exact way a queue stops being
+ * read. The first-ranked view wins (the ladder's, which carries the engine's `next`), and the
+ * second is folded into its `read:` line so no source is silently dropped.
+ */
+function dedupe(items) {
+  const seen = new Map();
+  const out = [];
+  for (const it of items) {
+    const key = `${it.tierOrder}|${it.product == null ? '' : it.product}|${it.dedup}`;
+    const prior = seen.get(key);
+    if (prior) { prior.read = `${prior.read} · also ${it.read}`; continue; }
+    seen.set(key, it);
+    out.push(it);
+  }
+  return out;
+}
+
+// ── Sections that are not the queue ─────────────────────────────────────────────────────────────
+
+/**
+ * R7 — one row per product, its top objective. Four distinguishable states, because there are four
+ * distinguishable facts:
+ *   objective  a top objective was read
+ *   none       a SUCCESSFUL read of a repo that declares none — calm
+ *   error      the read FAILED — RED, carrying surfaceSpine's own string (and it also files a
+ *              tier-1 queue item; one fact, two views)
+ *   not-read   no spine was supplied to this call — nothing happened, so nothing is claimed
+ */
+function objectiveRows(products) {
+  return products.map((p) => {
+    const base = { product: p.id, productName: p.name || p.id || null };
+    if (p.spine.state === 'error') {
+      return Object.assign(base, { state: 'error', id: null, name: null, error: p.spine.error });
+    }
+    if (p.spine.state === 'not-read') {
+      return Object.assign(base, {
+        state: 'not-read', id: null, name: null,
+        error: 'no spine read was supplied for this product — its objectives were not read, which is not the same as none being declared',
+      });
+    }
+    const top = p.spine.objectives[0];
+    if (!top) {
+      return Object.assign(base, { state: 'none', id: null, name: null, error: null, note: 'this repository declares no objectives' });
+    }
+    return Object.assign(base, {
+      state: 'objective', id: str(top.id) || null, name: str(top.name) || null, error: null,
+    });
+  });
+}
+
+/*
+ * R9 — handoffs. The requirement the prototype most directly contradicts, and the one this build is
+ * most likely to regress by copying it.
+ *
+ * There is no credential, no MCP client and no sync path in this repository, so a story count or a
+ * sync time would be fabricated. The worse failure is the quiet one: a calm "nothing owed by you"
+ * over an absent connection is a claim about another team's board derived from NOTHING, and it
+ * looks identical to a working, connected, all-clear integration. That is the watermelon the
+ * honest-state contract exists to prevent.
+ *
+ * `count` is null, never 0. Zero is an answer; this section does not have one.
+ */
+function handoffsSection() {
+  return {
+    connected: false,
+    state: 'not-connected',
+    heading: 'handoffs · waiting on other teams',
+    body: 'not connected. No external tracker is configured, so PMOS cannot say what another team owes. '
+      + 'Connecting one is a PM decision about credentials and an MCP server.',
+    items: [],
+    count: null,
+    tier: TIER.handoff.tier,
+  };
+}
+
+// A skill path named inside an engine `next` string. `skills/…` and `build-skills/…` are the only
+// two roots that carry them, and the `.skill` suffix is what makes the reference resolvable rather
+// than prose about a skill.
+const SKILL_PATH = /(?:build-)?skills\/[A-Za-z0-9._\-\/]+\.skill/g;
+/** Every skill path a `next` string names, in order, without duplicates. */
+function skillPathsIn(text) {
+  const found = str(text).match(SKILL_PATH);
+  return found ? [...new Set(found)] : [];
+}
+
+/*
+ * R8 — delegated. Two parts, and the second is where an over-eager surface does damage.
+ *
+ * RUNNING is every non-exited session, carrying `session-state`'s own WORD verbatim — including
+ * 'maybe blocked' with its hedge intact. Focus may not upgrade or soften a session state; the
+ * module owns those words and both sides already share it.
+ *
+ * STARTS offers `▶ delegate` ONLY where the engine's own `next` names a skill file that EXISTS ON
+ * DISK. Focus is pure, so it cannot stat anything: the caller supplies the on-disk skill index. No
+ * index supplied ⇒ NO offers at all and a stated reason, because an offer PMOS cannot honour is
+ * worse than no offer. Focus never invents an agent name, a capability claim or a recommendation.
+ */
+function delegatedSection(products, skills) {
+  const index = skills == null ? null
+    : new Set((skills instanceof Set ? [...skills] : arr(skills)).map((s) => str(s)));
+
+  const running = [];
+  for (const p of products) {
+    for (const s of p.sessions) {
+      const shown = str(s.shown);
+      if (shown === 'exited') continue;
+      running.push({
+        id: str(s.id), name: s.name == null ? null : str(s.name),
+        product: p.id, productName: p.name || p.id || null,
+        agent: s.agent == null ? null : str(s.agent),
+        shown,
+        // Verbatim from lib/session-state's WORD table — one source of truth for the word beside a
+        // session, so this surface and the sidebar can never hold different opinions.
+        word: sessionState.WORD[shown] || shown,
+        glyph: sessionState.GLYPH[shown] || null,
+        hedged: shown === 'blocked',
+        quietMs: Number.isFinite(s.quietMs) ? s.quietMs : null,
+        in_queue: classifySession(shown).qualifies,
+      });
+    }
+  }
+  running.sort((a, b) => (a.product || '').localeCompare(b.product || '') || a.id.localeCompare(b.id));
+
+  const starts = [];
+  const seen = new Set();
+  for (const p of products) {
+    for (const row of ladderRows(p)) {
+      const id = str(row.id);
+      for (const step of arr(row.steps)) {
+        if (!isObj(step)) continue;
+        // Belt and braces: a position the PM owns never gets a delegate button, whatever its `next`
+        // happens to contain. The three PM steps name no skill file today; this makes that a rule
+        // rather than a coincidence of the engine's current wording.
+        if (classifyStep(step.key, step.status).qualifies) continue;
+        for (const skill of skillPathsIn(step.next)) {
+          if (index && !index.has(skill)) continue;
+          const key = `${p.id || ''}:${id}:${skill}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          starts.push({
+            initiative: id, title: row.title == null ? null : str(row.title),
+            product: p.id, productName: p.name || p.id || null,
+            step: str(step.key), status: str(step.status),
+            skill,
+            action: str(step.next),
+            initialInput: `Run ${skill} for initiative ${id}. The workflow engine says: ${str(step.next)}`,
+            offered: !!index,
+          });
+        }
+      }
+    }
+  }
+  starts.sort((a, b) => (a.product || '').localeCompare(b.product || '')
+    || a.initiative.localeCompare(b.initiative) || a.skill.localeCompare(b.skill));
+
+  return {
+    running,
+    starts: index ? starts : [],
+    starts_state: index ? 'resolved' : 'not-resolved',
+    starts_note: index
+      ? 'a ▶ delegate action is offered only where the engine\'s own `next` names a skill file present in the supplied on-disk index'
+      : 'no on-disk skill index was supplied to this call, so no ▶ delegate action is offered — an offer PMOS cannot honour is worse than no offer',
+    // What WOULD be offered if the index resolved them. Kept separate so a caller can never render
+    // it as a button, and so the "no index" case is diagnosable rather than mysteriously empty.
+    candidates: starts.map((s) => ({ initiative: s.initiative, product: s.product, step: s.step, skill: s.skill })),
+  };
+}
+
+/*
+ * R10 — upkeep says only what it can read.
+ *
+ * MEMORY is a stated absence, not a count. `memory` mode is `data: 'absent'` by construction; there
+ * is no store, so there are no unpinned entries at compaction risk. The row says the mechanism is
+ * not built.
+ *
+ * HEALTH BUDGETS carry a caveat instead of a verdict. The caps are shares of A QUARTER's
+ * initiatives; no initiative record carries a period and `surfaceSpine` reads none. So the counts
+ * below are over ALL anchored initiatives and are NOT the cap test — and no percentage is printed,
+ * because a percentage implies a test that has not been run.
+ */
+const BUDGET_CAVEAT = 'The caps are shares of a QUARTER\'s initiatives. No initiative record carries a period '
+  + 'and the spine reads none, so the counts here are over ALL anchored initiatives and are NOT the cap test.';
+
+function upkeepSection(products, registry) {
+  const memory = {
+    id: 'memory',
+    state: 'absent',
+    heading: 'memory grooming',
+    body: 'not built. There is no memory store in this workspace, so there are no entries to groom and none at compaction risk. '
+      + 'This row states the absence of the mechanism; it is not a count of zero.',
+    count: null,
+  };
+
+  // The registry (planning/okrs/health-budgets.md) is a FILE, and this function reads nothing. It
+  // is an input; absent, the caps are reported as not read rather than guessed.
+  let caps = null;
+  let capsError = null;
+  if (Array.isArray(registry)) caps = registry.filter(isObj);
+  else if (isObj(registry)) {
+    if (registry.ok === false) capsError = str(registry.error) || 'the health-budget registry could not be read';
+    else if (Array.isArray(registry.budgets)) caps = registry.budgets.filter(isObj);
+    else capsError = 'the health-budget registry read returned no budget list — malformed, not empty';
+  }
+
+  const rows = new Map();
+  const row = (id) => {
+    if (!rows.has(id)) rows.set(id, { id, cap: null, covers: null, cap_state: 'not-read', anchored: [], total: 0 });
+    return rows.get(id);
+  };
+  for (const b of arr(caps)) {
+    const id = str(b.id) || '';
+    if (!id) continue;
+    const r = row(id.startsWith('health:') ? id : `health:${id}`);
+    r.cap = b.cap == null ? null : str(b.cap);
+    r.covers = b.covers == null ? null : str(b.covers);
+    r.cap_state = r.cap ? 'declared' : 'declared-without-cap';
+  }
+  let spineUnread = 0;
+  let budgetsUnreadable = 0;
+  for (const p of products) {
+    if (p.spine.state !== 'ok') { spineUnread++; continue; }
+    if (p.spine.budgets_readable === false) budgetsUnreadable++;
+    for (const b of p.spine.budgets) {
+      const id = str(b.id) || '';
+      if (!id) continue;
+      const r = row(id);
+      const n = arr(b.initiatives).length;
+      r.anchored.push({ product: p.id, productName: p.name || p.id || null, count: n });
+      r.total += n;
+    }
+  }
+
+  return {
+    memory,
+    budgets: {
+      state: capsError ? 'error' : (caps ? 'read' : 'not-read'),
+      error: capsError,
+      note: capsError ? null : (caps
+        ? 'caps as declared in planning/okrs/health-budgets.md'
+        : 'the caps live in planning/okrs/health-budgets.md and were not supplied to this call — no cap is shown for any budget'),
+      caveat: BUDGET_CAVEAT,
+      // Deliberately no percentage, share or ratio field anywhere in this row. Printing one would
+      // imply the cap has been evaluated against a quarter it was never measured over.
+      rows: [...rows.values()].sort((a, b) => a.id.localeCompare(b.id)),
+      spine_not_read: spineUnread,
+      registry_unreadable_in: budgetsUnreadable,
+    },
+  };
+}
+
+/*
+ * R6 — coverage is stated, because it is genuinely partial. BOARD_CAP is 12
+ * (workflow-state.js:787), so the ladder-derived tiers see only the top 12 in-flight initiatives
+ * per product. The cap sorts unreadable first, then blocked, so it is UNLIKELY to hide a qualifying
+ * item — and unlikely is not cannot, which is why this line exists rather than a reassurance.
+ */
+function coverageRows(products) {
+  return products.map((p) => {
+    const b = p.board;
+    const base = {
+      product: p.id, productName: p.name || p.id || null,
+      state: b.state, shown: b.shown, total: b.total, hidden: b.hidden,
+      stale: b.stale, as_of: b.as_of, error: b.error, line: null,
+    };
+    if (b.state === 'error') { base.line = `this board could not be derived — ${b.error}`; return base; }
+    if (b.state === 'deriving') { base.line = 'this board is still deriving — it is neither empty nor broken'; return base; }
+    if (b.state === 'not-read') { base.line = 'no board read was supplied for this product'; return base; }
+    if (b.state === 'empty') { base.line = 'this repository holds no initiative records'; return base; }
+    base.line = b.hidden > 0
+      ? `${b.shown} of ${b.total} scanned · ${b.hidden} outside the board's in-flight cap.`
+      : `${b.shown} of ${b.total} scanned · none outside the board's in-flight cap.`;
+    if (b.stale) base.line += ` This board was derived at ${b.as_of} and a refresh is running.`;
+    return base;
+  });
+}
+
+/*
+ * R5 — the badge. The count is derived from the queue that was just built, in the same call that
+ * renders the list, and a BARE NUMBER IS FORBIDDEN whenever a contributing read failed, is still
+ * deriving, or never happened. The third quiet failure the PRD names is a badge that sums the
+ * readable products and ignores the broken one: right about what it counted, wrong about what it
+ * claimed, with nothing on screen saying which.
+ */
+function badgeFor(n, reads) {
+  const failed = reads.filter((r) => r.state === 'error');
+  const deriving = reads.filter((r) => r.state === 'deriving');
+  const notRead = reads.filter((r) => r.state === 'not-read');
+  const reasons = failed.map((r) => `${r.product || 'this workspace'}: ${r.error}`);
+
+  if (failed.length) {
+    // The shape app.js:795 already uses. No partial sum, because a partial sum is a claim about a
+    // total nobody computed.
+    return { n, text: 'needs unreadable', exact: false, unreadable: true, failed: failed.length, deriving: deriving.length, not_read: notRead.length, reasons };
+  }
+  const notes = [];
+  if (deriving.length) notes.push(`${deriving.length} product${deriving.length === 1 ? '' : 's'} still deriving`);
+  if (notRead.length) notes.push(`${notRead.length} product${notRead.length === 1 ? '' : 's'} not read`);
+  const head = n === 0 && !notes.length ? 'nothing needs you' : `${n} need you`;
+  return {
+    n, text: notes.length ? `${head} · ${notes.join(' · ')}` : head,
+    exact: !notes.length, unreadable: false,
+    failed: 0, deriving: deriving.length, not_read: notRead.length,
+    reasons: notes,
+  };
+}
+
+/** Every contributing read, with its state — the provenance the badge is derived from. */
+function readLog(products) {
+  const out = [];
+  for (const p of products) {
+    const tag = { product: p.id, productName: p.name || p.id || null };
+    out.push(Object.assign({ source: 'board' }, tag, { state: p.board.state, error: p.board.error }));
+    out.push(Object.assign({ source: 'needs' }, tag, { state: p.needs.state, error: p.needs.error }));
+    out.push(Object.assign({ source: 'spine' }, tag, { state: p.spine.state, error: p.spine.error }));
+  }
+  return out;
+}
+
+/**
+ * buildFocus(input) — the whole surface, derived.
+ *
+ * INPUT (every field optional; nothing is read from disk, a clock or the network):
+ *   products []       — [{ id, name, board, needs, spine, sessions, ladders }]. The real input.
+ *   board             — one `boardCache.board(root)` result. Used only when `products` names at
+ *   needs             —   most one product; a top-level read shared across several trees would
+ *   spine             —   attribute one repository's state to all of them.
+ *   ladders           — extra `consoleState.ladder()` results (array, envelope array, or id map).
+ *   sessions []       — one `sessionList()`, partitioned per product by each row's `ws`.
+ *   skills            — array/Set of repo-relative skill paths that EXIST ON DISK (R8). Omit and no
+ *                       ▶ delegate action is offered at all.
+ *   budgetRegistry    — the declared health budgets, parsed from planning/okrs/health-budgets.md
+ *                       (array of {id, cap, covers}, or {ok:false,error}). Omit and no cap is shown.
+ *
+ * RETURNS:
+ *   { objectives[], queue[], handoffs, delegated, upkeep, count, badge, coverage, reads, tiers }
+ *
+ * Render `badge.text`, NEVER `count`. `count` is a true statement about the queue's length; it is
+ * not a true statement about the world whenever `badge.unreadable` is set.
+ */
+function buildFocus(input) {
+  const inp = isObj(input) ? input : {};
+  const products = normalizeProducts(inp);
+
+  const raw = [];
+  for (const p of products) {
+    raw.push(...integrityItems(p), ...ladderItems(p), ...needsItems(p), ...sessionItems(p), ...unanchoredItems(p));
+  }
+
+  // Rank exactly as the PRD states: board-integrity → contract/gate → a session is waiting →
+  // handoff (structurally empty) → intake. Within a tier, product name then id — so the order is
+  // stable between renders and a rank number therefore means something.
+  raw.sort((a, b) => a.tierOrder - b.tierOrder
+    || String(a.sortKey).localeCompare(String(b.sortKey))
+    || String(a.subject).localeCompare(String(b.subject))
+    || String(a.id).localeCompare(String(b.id)));
+
+  const queue = dedupe(raw);
+  for (let i = 0; i < queue.length; i++) {
+    queue[i].rank = i + 1;
+    // internal join/sort keys — not fields the UI owes anything to
+    delete queue[i].dedup;
+    delete queue[i].sortKey;
+  }
+
+  const reads = readLog(products);
+  const count = queue.length;                                 // derived here, every call. Never stored.
+  return {
+    intro: 'This list holds only items where you are the blocker. Everything else is running on an agent or waiting on another team.',
+    objectives: objectiveRows(products),
+    queue,
+    handoffs: handoffsSection(),
+    delegated: delegatedSection(products, inp.skills),
+    upkeep: upkeepSection(products, inp.budgetRegistry),
+    count,
+    badge: badgeFor(count, reads),
+    coverage: coverageRows(products),
+    reads,
+    tiers: TIERS,
+    empty_note: 'nothing is waiting on you',                  // the CALM state — only honest when badge.exact
+  };
+}
+
+module.exports = {
+  buildFocus,
+  // The classifiers are exported so the suite can walk their whole domains rather than sample them
+  // — the property that separates a total classifier from a filter list.
+  classifyStep, classifySession, classifyNeed, skillPathsIn,
+  readBoard, readNeeds, readSpine, readLadders,
+  STEP_KEYS, STEP_STATUSES, AGENT_ACT_STEPS, PM_STEPS, TIERS, BUDGET_CAVEAT,
+};