create-pmos 0.10.1 → 0.11.1

package/README.md

@@ -333,6 +333,70 @@ Refreshes the skills, concepts, and scripts only. Your records — `state/`, `pl
 `okf/product/` — are yours, and an update never touches them. `pmos/KIT-VERSION` always says
 exactly what you're running.
 
+## What's new in 0.11.1
+
+**Fixes: the ladder never actually worked.** If you installed 0.11.0 and every row in the new
+sidebar read `ladder unreadable` in red — that was us, not your repository.
+
+The engine that derives an initiative's stage, next step and blockers was **not included in any
+published package**. It lives at `scripts/workflow-state.js` in the PMOS repo, and the workspace
+looked for it two directories above itself — a path that exists in a development checkout and in no
+install. The surface 0.11.0 was released for could not run for anyone who installed it.
+
+0.11.1 bundles the engine with the app, and adds the check that would have caught this: publishing
+now **derives a ladder from the packed tarball** and fails if it cannot, rather than only confirming
+that files are present.
+
+So rows now show what 0.11.0 described: lane, derived stage, and the next step or the blocker —
+each one naming the branch it was derived from.
+
+A repository with no `planning/initiatives/` records is no longer an error; it simply has no
+initiatives, and reads calmly. Some of the wording around that is still terser than it should be
+(a folder that is not a git repository currently reports an unreadable branch rather than saying it
+is not a repository) — that is being fixed separately and is a label, not a failure.
+
+## What's new in 0.11.0
+
+**The workspace navigates by initiative instead of by folder.** If you upgrade and the left column
+looks unfamiliar, this is why.
+
+- **One tree instead of two panes.** The sidebar was a list of working trees named after
+  directories, plus a separate list of running agents. It is now a single tree: your repository,
+  the working trees under it, and each tree's sessions beneath that. A branch called
+  `initiative/<id>` is labelled with the initiative, not the folder — and the folder name stays on
+  the row, because switching a branch moves every session in that tree and a row that renamed
+  itself would look like a row that vanished.
+
+- **Each row says where the work is and what is next** — its lane, its derived stage, and either
+  the next step or what is blocking it. Nothing here is a status anyone types; it is derived from
+  your records and git, by the same engine the gate runs.
+
+- **Every stage names the branch it was derived from.** This one matters more than it sounds.
+  Stage is computed over `merge-base(main, HEAD)..HEAD` — *this branch's* commits — so an
+  initiative you shipped months ago legitimately reads "spec" on a branch that did not build it.
+  The surface now says which branch produced the answer instead of implying it is absolute.
+
+- **The rail follows your selection.** The four lenses (initiatives · folders · scheduled ·
+  history) are replaced by one detail: pick a repository and you get its folder map, schedules and
+  history; pick an initiative and you get its dossier — where it is, what it still owes, and every
+  artifact it owns, grouped by what the *lane* asks for. A chore is not shown as a feature missing
+  a PRD. Opening a dossier is a read: it never switches your working tree.
+
+- **The workflow panel no longer freezes the app.** Deriving the board shells `git` once per
+  initiative — around 30 seconds on a large repo — and it used to run on the request path, locking
+  the server and every terminal session with it. It now runs in a separate process and every answer
+  is stamped with when it was derived. On a big repository the first read says "deriving" rather
+  than showing nothing.
+
+- **Prototypes, user stories and copywriting are visible to the library.** Specimens in
+  `prototype/<id>/` were outside the scanned tree, so a D60 prototype never appeared on the
+  initiative that produced it. They do now, and `-user-stories`, `-copy-brief` and `-copy` are
+  recognised artifact roles.
+
+Honest note on what this release did *not* get: the 30-second derivation is **cached, not fixed** —
+the underlying per-file git lookups are still unbatched. And the Review Gate for this work was never
+scored; it was accepted on green CI and PM judgement, without an independent adversarial pass.
+
 ## What's new in 0.10.1
 
 **Two fixes found by installing 0.10.0 and using it, rather than by reading the code.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@84f5b38
-assembled: 2026-07-28
+kernel-source: pmos@cae81d8
+assembled: 2026-07-29
 mode: vendor

package/workspace/lib/board-cache.js

@@ -0,0 +1,116 @@
+'use strict';
+/*
+ * board-cache.js — the workflow board, cached and derived OFF the event loop.
+ *
+ * WHY THIS EXISTS. `console-state.workflow()` runs `scripts/workflow-state.js` over every
+ * initiative record, and the engine resolves each artifact's FIRST APPEARANCE by shelling `git`.
+ * Measured on the PMOS repo, 2026-07-29: ~260 ms per initiative × 109 records = **~30 seconds**, and
+ * every millisecond of it is SYNCHRONOUS. Today that cost is paid only when the PM opens the
+ * `workflow` lens, where it freezes the server — and with it every PTY WebSocket — for half a minute.
+ *
+ * PRD R4 puts the same board behind EVERY sidebar row, so an uncached in-process derivation would
+ * turn a 30-second freeze into a freeze on every render. Two rules follow, and they are the whole
+ * design:
+ *
+ *   1. NEVER derive on the request path. A miss spawns a CHILD PROCESS and returns immediately.
+ *      The event loop is never blocked, however cold the cache is.
+ *   2. NEVER serve a stale board as if it were fresh. Every hit carries `as_of` and `stale`, and a
+ *      cold cache returns `pending: true` rather than an empty board. A surface that cannot say how
+ *      old its answer is has no business showing a stage — that is R5's rule applied to time
+ *      instead of to branch.
+ *
+ * The signature is HEAD + the initiative records' own mtimes, so editing a record refreshes the
+ * board without a commit, and switching branch refreshes it without an edit.
+ */
+const fs = require('fs');
+const path = require('path');
+const { spawnSync, spawn } = require('child_process');
+
+const MAX_AGE_MS = 10 * 60 * 1000;   // a board older than this is refreshed even if the signature holds
+const REFRESH_TIMEOUT_MS = 120000;   // a derivation that cannot finish in 2 minutes is reported, not awaited
+
+const cache = new Map();             // root -> { sig, at, value, error }
+const inflight = new Map();          // root -> true
+
+function headSha(root) {
+  const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 });
+  return r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+}
+
+// The records' own state, so an UNCOMMITTED edit still invalidates. Cheap: one readdir + one stat
+// per record, no git, no file contents.
+function recordsSig(root) {
+  const dir = path.join(root, 'planning', 'initiatives');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md')).sort(); } catch { return 'none'; }
+  let newest = 0;
+  for (const n of names) {
+    try { const st = fs.statSync(path.join(dir, n)); if (st.mtimeMs > newest) newest = st.mtimeMs; }
+    catch { /* a record that vanished mid-scan just does not raise the watermark */ }
+  }
+  return `${names.length}:${Math.round(newest)}`;
+}
+
+function signature(root) { return `${headSha(root)}|${recordsSig(root)}`; }
+
+// The child runs the SAME reader the lens uses — no second implementation of the board to drift.
+function refresh(root, sig) {
+  if (inflight.get(root)) return;
+  inflight.set(root, true);
+  const script = `
+    const cs = require(${JSON.stringify(path.join(__dirname, 'console-state.js'))});
+    process.stdout.write(JSON.stringify(cs.workflow({ root: ${JSON.stringify(root)} })));
+  `;
+  let out = '';
+  let child;
+  try { child = spawn(process.execPath, ['-e', script], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] }); }
+  catch (e) {
+    inflight.delete(root);
+    cache.set(root, { sig, at: Date.now(), value: null, error: 'could not start the board derivation: ' + (e.code || e.message) });
+    return;
+  }
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, REFRESH_TIMEOUT_MS);
+  if (timer.unref) timer.unref();
+  child.stdout.on('data', (c) => { out += c; });
+  child.on('error', (e) => {
+    clearTimeout(timer); inflight.delete(root);
+    cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation failed to run: ' + (e.code || e.message) });
+  });
+  child.on('close', (code, signal) => {
+    clearTimeout(timer); inflight.delete(root);
+    if (signal === 'SIGKILL') {
+      cache.set(root, { sig, at: Date.now(), value: null, error: `the board took longer than ${Math.round(REFRESH_TIMEOUT_MS / 1000)}s to derive and was stopped` });
+      return;
+    }
+    if (code !== 0 || !out) {
+      cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation exited without a result' });
+      return;
+    }
+    try { cache.set(root, { sig, at: Date.now(), value: JSON.parse(out), error: null }); }
+    catch { cache.set(root, { sig, at: Date.now(), value: null, error: 'the board derivation returned unreadable output' }); }
+  });
+}
+
+/*
+ * The read the request path uses. Always returns immediately.
+ *   { pending: true }                       nothing cached yet; a derivation was started
+ *   { ok:false, error, as_of, stale }       the derivation failed — render RED, never a calm empty
+ *   { ...workflowPayload, as_of, stale }    a board; `stale` means a refresh is running behind it
+ */
+function board(root, { refreshNow = false } = {}) {
+  if (!root) return { ok: false, error: 'no workspace root resolved for the workflow board', as_of: null, stale: false };
+  let sig;
+  try { sig = signature(root); } catch { sig = 'unreadable'; }
+  const hit = cache.get(root);
+  const fresh = hit && hit.sig === sig && (Date.now() - hit.at) < MAX_AGE_MS;
+  if (!fresh || refreshNow) refresh(root, sig);
+  if (!hit) return { pending: true, refreshing: true, as_of: null, stale: false };
+  const envelope = { as_of: new Date(hit.at).toISOString(), stale: !fresh, refreshing: !!inflight.get(root) };
+  if (hit.error) return { ok: false, error: hit.error, ...envelope };
+  return { ...hit.value, ...envelope };
+}
+
+// Test/maintenance seam: drop everything, or one root.
+function invalidate(root) { if (root) { cache.delete(root); inflight.delete(root); } else { cache.clear(); inflight.clear(); } }
+
+module.exports = { board, invalidate, signature, MAX_AGE_MS, REFRESH_TIMEOUT_MS };

package/workspace/lib/console-state.js

@@ -18,6 +18,7 @@
 const fs = require('fs');
 const path = require('path');
 const reviewGate = require('./review-gate');
+const gitInfo = require('./git-info');       // R5: the ladder is branch-scoped — name the branch it came from
 
 function loadJson(file) {
   let text;
@@ -125,14 +126,45 @@ function radar({ stateDir, snapshotDir }) {
  * option. It is deliberately not `require`d out of the opened directory: the engine only reads
  * files and runs `git -C <root> log`, so no code from a workspace the PM merely opened is ever
  * executed. An install that does not carry the engine gets an honest error, never a blank panel.
+ *
+ * WHERE THE ENGINE ACTUALLY LIVES — the defect this list exists to close (incident
+ * kit-workflow-engine-missing). "Bundled with the workspace" was the INTENT above; packaging never
+ * implemented it. `npm-pkg/package.json` ships only bin/ payload/ workspace/, so in a published
+ * install there is no repo two levels up and `../../scripts/workflow-state.js` resolves to nothing.
+ * Every adopter row read "ladder unreadable" from 0.11.0 back to whenever this surface shipped —
+ * the ladder had never once run outside a PMOS checkout. Two locations, tried in order:
+ *
+ *   1. `../../scripts/workflow-state.js` — a repo checkout (PMOS-self, any dev clone). Preferred on
+ *      purpose: it is the very file `.github/scripts/initiative-gate.sh` executes, so a developer's
+ *      panel can never disagree with what CI is about to print on their PR.
+ *   2. `lib/engine/workflow-state.js` — the copy the publish step vendors into the bundle. This is
+ *      what an adopter runs, and the only reason the ladder derives at all outside this repo.
+ *
+ * ABSENT and BROKEN are answered differently, because they are different facts (R10). A path that
+ * does not exist means "try the next one"; a path that exists and throws is a real fault in an
+ * engine that IS installed, and reporting that as "not present" would send the PM looking for a
+ * packaging bug they do not have.
  */
+const ENGINE_PATHS = [
+  path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js'),
+  path.join(__dirname, 'engine', 'workflow-state.js'),
+];
+function loadEngine() {
+  const tried = [];
+  for (const p of ENGINE_PATHS) {
+    if (!fs.existsSync(p)) { tried.push(p); continue; }
+    try { return { ok: true, engine: require(p), from: p }; }
+    catch (e) {
+      return { ok: false, error: `the workflow engine at ${p} is installed but failed to load — ${String((e && e.message) || e).slice(0, 160)}` };
+    }
+  }
+  return { ok: false, error: `the workflow engine is not present in this install — the ladder cannot be derived here (looked in: ${tried.join(', ')})` };
+}
 function workflow({ root }) {
   if (!root) return { ok: false, error: 'no workspace root resolved for the workflow surface' };
-  let engine;
-  try { engine = require(path.join(__dirname, '..', '..', 'scripts', 'workflow-state.js')); }
-  catch {
-    return { ok: false, error: 'the workflow engine (scripts/workflow-state.js) is not present in this install — the ladder cannot be derived here' };
-  }
+  const loaded = loadEngine();
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const engine = loaded.engine;
   let ids;
   try { ids = engine.listInitiatives(root); }
   catch (e) { return { ok: false, error: 'could not list initiative records: ' + String((e && e.message) || 'error').slice(0, 120) }; }
@@ -140,6 +172,24 @@ function workflow({ root }) {
 
   // One commit range for the whole board — resolving it per initiative would re-shell git for each.
   const range = engine.commitRange(root);
+  // WHERE the ladder was derived from. `commitRange` resolves merge-base(origin/main, HEAD)..HEAD —
+  // this BRANCH's commits, and an EMPTY range on main. So `build`/`quality`, and the stage that
+  // follows from them, are branch-scoped facts. A consumer that prints a stage without saying which
+  // branch produced it states something the data does not support: pmos-terminal-workspace, shipped
+  // under D62, derives to `spec` with "no implementation commits in this range" on every branch that
+  // did not build it. Two worktrees of one repo legitimately print two different ladders.
+  // This block is what lets a caller say so; it is not decoration (PRD R5, rubric dimension 1).
+  const bi = gitInfo.branchInfo(root);
+  const scope = {
+    branch: bi.ok ? (bi.current || 'a detached HEAD') : null,
+    branch_error: bi.ok ? null : (bi.error || 'branch could not be read'),
+    commits: range.ok ? range.shas.length : null,
+    whole_history: range.ok ? !!range.wholeHistory : null,
+    // The empty range is the trap: range.ok is TRUE with zero commits (you are on main, or level
+    // with it), so nothing is "degraded" — every build step legitimately reads `pending` and a naive
+    // reader calls that "never built". Named separately because it needs different words.
+    empty_range: range.ok ? range.shas.length === 0 : null,
+  };
   const rows = ids.map((id) => {
     try { return engine.computeWorkflow(id, { root, range }); }
     catch (e) { return { ok: false, id, error: String((e && e.message) || 'derivation failed').slice(0, 160) }; }
@@ -164,9 +214,12 @@ function workflow({ root }) {
       unreadable: rows.filter((r) => !r.ok).map(shape),
       blocked: shown.filter((r) => r.ok && r.blockers.length).length,
       degraded: range.ok ? null : range.reason,
+      scope,                        // R5 — the branch this ladder was derived from; never omit it
       enforced_from: engine.ENFORCED_FROM,
     },
   };
 }
 
-module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl };
+// ENGINE_PATHS/loadEngine are exported for the packaging guard in workspace/test.js: the incident
+// that made them a list was invisible to every unit test precisely because resolution was inline.
+module.exports = { metrics, radar, workflow, computeMetricsFromRuns, loadJson, loadJsonl, ENGINE_PATHS, loadEngine };

package/workspace/lib/engine/anchor-resolve.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * PMOS anchor resolution — the one place a `parent_kr` string becomes a structured answer.
+ *
+ *   const A = require('./anchor-resolve');
+ *   const index = A.parseOkrIndex(root);          // what the OKR documents actually declare
+ *   const r     = A.resolveAnchor(raw, index);    // { kind, objective, kr, status, ... }
+ *   A.canonical(r)                                // the one normative written form
+ *
+ * WHY THIS EXISTS. Before this module, `parent_kr` was a string that nothing dereferenced. The
+ * ladder's R1 passed any non-empty value that did not contain `health:` as `done` without ever
+ * opening the OKR documents — so `parent_kr: banana` passed, and so did an anchor naming a KR that
+ * existed in no file (`q3-2026:integrity:kr-a` and `:kr-b` did exactly that for two days). The
+ * workspace's OKR surface, meanwhile, never read `parent_kr` at all. One field, several readers,
+ * none of them agreeing what it meant. See
+ * planning/explainers/okr-anchor-resolution-surface-explainer.md.
+ *
+ * THREE RULES, all load-bearing (planning/prd/anchor-normalization-spec.md R-2/R-3/R-4):
+ *
+ *   1. PERMANENTLY BACKWARD-COMPATIBLE (R-2). Every syntax present in the corpus at authoring time
+ *      is accepted, and keeps being accepted — not behind a migration window. The kit ships to
+ *      adopters as `create-pmos` (D55), so records written in the legacy forms exist in repos no
+ *      rewrite here can reach. ACCEPTED_FORMS below is that enumeration, and it is a promise.
+ *
+ *   2. HEALTH IS A FORM TEST, NEVER A SUBSTRING SEARCH (R-3). The corpus contains
+ *      `okrs-q3-2026 → O1.KR1    # or health:<id> from planning/okrs/health-budgets.md` — an OKR
+ *      anchor whose *commentary* mentions health. A substring search classifies it as a health
+ *      anchor and then rejects it as an undeclared budget: recognised, then refused, for a reason
+ *      that is not the reader's fault. Classification therefore tests the START of the value.
+ *
+ *   3. THE OBJECTIVE AND KR PATTERNS WIDEN TOGETHER (R-4). Widening the objective pattern alone
+ *      would let a previously-unmatched KR attach to the *previous matched* objective rather than
+ *      stay unmatched — a silent mis-filing, which is worse than the omission it replaces.
+ *
+ * HONESTY BY CONSTRUCTION. `status` is one of `resolved` · `unresolvable` · `empty` · `unknown`.
+ * `unknown` means the OKR documents could not be read and never collapses into either a pass or a
+ * failure — a resolver that cannot see its inputs says so rather than guessing. Nothing in this
+ * module blocks anything: per the spec's assumption A1 the gates keep accepting any non-empty
+ * anchor, and the RED belongs to the surface. This module reports; callers decide.
+ *
+ * Zero dependencies, stock Node. Runs in CI, in the ladder, and inside the workspace server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/*
+ * The census, from the explainer, as executable documentation. Each entry is a real form found in
+ * planning/initiatives/ at authoring time (2026-07-28). Adding a form here without a matching
+ * pattern below, or vice versa, is the drift this list exists to make visible — the test suite
+ * asserts every example resolves.
+ */
+const ACCEPTED_FORMS = [
+  { example: 'health:tech',                    note: 'D59 registry form, bare' },
+  { example: 'health:tech (D59 — commentary)', note: 'registry form with trailing commentary' },
+  { example: 'q3-2026:o1:kr1',                 note: 'CANONICAL — colon triple' },
+  { example: 'q3-2026:integrity:kr-a',         note: 'canonical, non-numeric objective + KR ids' },
+  { example: 'Q3-2026:O1:KR2',                 note: 'canonical, upper-case variant' },
+  { example: 'okrs-q3-2026 → O1.KR1',          note: 'legacy arrow form, filename-prefixed' },
+  { example: 'okrs-q3-2026 → O1',              note: 'legacy arrow, objective only (no KR)' },
+  { example: 'q3-2026 → O1.KR2',               note: 'legacy arrow, period-prefixed' },
+  { example: 'O1.KR3',                         note: 'legacy bare objective.KR' },
+  { example: '**O1**',                         note: 'legacy bare objective, markdown-bolded' },
+  { example: "okrs-q3-2026 → O2.KR2 / B4 (Cohen's kappa)", note: 'trailing commentary after a slash' },
+  { example: 'okrs-q3-2026 → O1.KR1    # or health:<id> from planning/okrs/health-budgets.md',
+    note: 'R-3 trap: OKR anchor whose COMMENTARY mentions health — must classify as okr' },
+];
+
+/*
+ * Objective and KR tokens are deliberately NOT `O\w+` / `KR\w+`. The OKR document's own H1 is
+ * `# OKRs — Q3 2026`, and a loose objective pattern matches `OKRs` there, inventing an objective
+ * called `okrs` that every subsequent KR would then attach to. The shape is therefore pinned:
+ * an objective is `O` + digits, or `O-` + a word; a KR is `KR` + digits, or `KR-` + a word.
+ */
+const OBJ_TOKEN = '(O\\d+|O-[A-Za-z][A-Za-z0-9-]*)';
+const KR_TOKEN = '(KR\\d+|KR-[A-Za-z][A-Za-z0-9-]*)';
+const PERIOD = '((?:q|Q)[1-4]-\\d{4})';
+
+const RE_OBJ_HEADING = new RegExp('^#{1,3}\\s+' + OBJ_TOKEN + '\\s*(?:[—–:-]\\s*(.*))?$');
+const RE_KR_BULLET = new RegExp('^\\s*[-*]\\s*\\*\\*\\s*' + KR_TOKEN + '\\s*[—–:-]?\\s*(.+?)\\*\\*');
+
+// Anchor forms. Order matters only in that the colon forms are tried before the looser ones.
+const RE_HEALTH = /^health:([a-z0-9_-]+)/i;                       // START-anchored — rule 2
+const RE_COLON_KR = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*):(kr-?[a-z0-9-]+)$', 'i');
+const RE_COLON_OBJ = new RegExp('^(?:okrs-)?' + PERIOD + ':([a-z0-9][a-z0-9-]*)$', 'i');
+const RE_ARROW = new RegExp('^(?:okrs-)?' + PERIOD + '\\s*(?:→|->)\\s*' + OBJ_TOKEN + '(?:\\.' + KR_TOKEN + ')?$', 'i');
+const RE_BARE = new RegExp('^' + OBJ_TOKEN + '(?:\\.' + KR_TOKEN + ')?$', 'i');
+
+/** Strip markdown emphasis and trailing commentary. `(`, `#` and `/` never appear inside an id. */
+function stripCommentary(raw) {
+  let s = String(raw == null ? '' : raw).replace(/\*\*/g, '').trim();
+  const cut = s.search(/[(#/]/);
+  if (cut >= 0) s = s.slice(0, cut);
+  return s.trim();
+}
+
+/** `O-INTEGRITY` → `integrity`; `O1` → `o1`. The anchors write `integrity`, the heading writes
+ *  `O-INTEGRITY`; the explainer flagged that a widened parser must pick one. This picks: the id is
+ *  the heading token minus a leading `O-`, lower-cased. */
+function objectiveId(token) {
+  const t = String(token || '').trim();
+  const m = /^O-(.+)$/i.exec(t);
+  return (m ? m[1] : t).toLowerCase();
+}
+
+/** `KR1` → `kr1`; `KR-C` → `kr-c`. Case only. */
+function krId(token) {
+  return String(token || '').trim().toLowerCase();
+}
+
+function listOkrFiles(root) {
+  const out = [];
+  const seen = new Set();
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.name.startsWith('.') || e.name === 'node_modules') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === 'okrs') {
+          let files;
+          try { files = fs.readdirSync(full); } catch { continue; }
+          for (const f of files) {
+            if (!f.endsWith('.md')) continue;
+            const p = path.join(full, f);
+            if (!seen.has(p)) { seen.add(p); out.push(p); }
+          }
+        } else walk(full, depth + 1);
+      }
+    }
+  };
+  walk(root, 0);
+  return out.sort();
+}
+
+/**
+ * Read every OKR document under `root` and return what they declare.
+ * → { ok, objectives: [{id, token, name, krs:[{id, token, name}], file}], files, error }
+ * `ok:false` is a genuine read failure and must render as an error, never as "no objectives".
+ */
+function parseOkrIndex(root) {
+  const files = listOkrFiles(root);
+  if (!files.length) {
+    return { ok: false, objectives: [], files: [], error: 'no OKR documents found under ' + root };
+  }
+  const objectives = [];
+  const byId = new Map();
+  let period = null;
+  for (const file of files) {
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); }
+    catch (e) {
+      return { ok: false, objectives: [], files, error: `could not read ${file}: ${String((e && e.message) || e).slice(0, 120)}` };
+    }
+    let cur = null;
+    for (const line of text.split('\n')) {
+      if (!period) {
+        const p = /^\s*[-*]?\s*period\s*:\s*(\d{4})-(Q[1-4])\s*$/i.exec(line);
+        if (p) period = `${p[2].toLowerCase()}-${p[1]}`;
+      }
+      const o = RE_OBJ_HEADING.exec(line);
+      if (o) {
+        const id = objectiveId(o[1]);
+        cur = byId.get(id);
+        if (!cur) {
+          cur = { id, token: o[1], name: (o[2] || '').replace(/\*\*/g, '').trim(), krs: [], file: path.relative(root, file) };
+          byId.set(id, cur);
+          objectives.push(cur);
+        }
+        continue;
+      }
+      const k = RE_KR_BULLET.exec(line);
+      // A KR with no open objective stays UNATTACHED (rule 3) — never inherited from a previous one.
+      if (k && cur && !cur.krs.some((x) => x.id === krId(k[1]))) {
+        cur.krs.push({ id: krId(k[1]), token: k[1], name: (k[2] || '').trim() });
+      }
+    }
+  }
+  return { ok: true, objectives, files: files.map((f) => path.relative(root, f)), period: period || null, error: null };
+}
+
+function readBudgets(root) {
+  const p = path.join(root, 'planning', 'okrs', 'health-budgets.md');
+  try { return { ok: true, text: fs.readFileSync(p, 'utf8'), path: path.relative(root, p) }; }
+  catch { return { ok: false, text: '', path: path.relative(root, p) }; }
+}
+
+/**
+ * Resolve one raw `parent_kr` value.
+ * → { raw, kind, status, objective, kr, budget, period, form, reason }
+ *   kind   : 'health' | 'okr' | 'empty'
+ *   status : 'resolved' | 'unresolvable' | 'empty' | 'unknown'
+ * `index` comes from parseOkrIndex; `budgets` from readBudgets (optional — omit to skip the
+ * registry check, which callers that only need the FORM can do).
+ */
+function resolveAnchor(raw, index, budgets) {
+  const original = String(raw == null ? '' : raw).trim();
+  const base = { raw: original, kind: 'empty', status: 'empty', objective: null, kr: null, budget: null, period: null, form: null, reason: null };
+  if (!original) return Object.assign(base, { reason: 'parent_kr is empty — unanchored work is rejected (D59)' });
+
+  // Rule 2: the FORM decides, not a substring. Commentary is stripped only for the OKR branch,
+  // because a health anchor's id must sit at the very start of the raw value.
+  const h = RE_HEALTH.exec(original);
+  if (h) {
+    const id = h[1].toLowerCase();
+    const out = Object.assign({}, base, { kind: 'health', budget: id, form: 'health:<id>' });
+    if (!budgets) return Object.assign(out, { status: 'unknown', reason: 'health budget registry not supplied to the resolver' });
+    if (!budgets.ok) return Object.assign(out, { status: 'unknown', reason: `health-budget registry unreadable at ${budgets.path}` });
+    // Same case handling as the classifier (R-3): recognised case-insensitively, looked up the same way.
+    const declared = new RegExp('health:' + id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\b', 'i').test(budgets.text);
+    return declared
+      ? Object.assign(out, { status: 'resolved', reason: `declared in ${budgets.path}` })
+      : Object.assign(out, { status: 'unresolvable', reason: `health:${id} is not a declared budget in ${budgets.path}` });
+  }
+
+  const s = stripCommentary(original);
+  if (!s) {
+    return Object.assign(base, { kind: 'okr', status: 'unresolvable', reason: 'no anchor left after commentary was stripped' });
+  }
+
+  let period = null, objTok = null, krTok = null, form = null;
+  let m;
+  if ((m = RE_COLON_KR.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; krTok = m[3]; form = 'q3-2026:<objective>:<kr>'; }
+  else if ((m = RE_COLON_OBJ.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; form = 'q3-2026:<objective>'; }
+  else if ((m = RE_ARROW.exec(s))) { period = m[1].toLowerCase(); objTok = m[2]; krTok = m[3] || null; form = 'legacy arrow'; }
+  else if ((m = RE_BARE.exec(s))) { objTok = m[1]; krTok = m[2] || null; form = 'legacy bare'; }
+  else {
+    return Object.assign(base, { kind: 'okr', status: 'unresolvable', form: 'unrecognised', reason: `'${s}' matches no accepted anchor form` });
+  }
+
+  const out = Object.assign({}, base, {
+    kind: 'okr', form, period,
+    objective: objectiveId(objTok),
+    kr: krTok ? krId(krTok) : null,
+  });
+
+  if (!index) return Object.assign(out, { status: 'unknown', reason: 'OKR index not supplied to the resolver' });
+  if (!index.ok) return Object.assign(out, { status: 'unknown', reason: index.error || 'OKR documents unreadable' });
+
+  const obj = index.objectives.find((o) => o.id === out.objective);
+  if (!obj) {
+    return Object.assign(out, { status: 'unresolvable', reason: `objective '${out.objective}' is not declared in ${index.files.join(', ')}` });
+  }
+  if (!out.kr) {
+    // Assumption A2: objective-only anchoring is a legitimate resolvable kind, not debt.
+    return Object.assign(out, { status: 'resolved', reason: `objective '${obj.id}' — no KR written (objective-level anchor)` });
+  }
+  const kr = obj.krs.find((k) => k.id === out.kr);
+  if (!kr) {
+    return Object.assign(out, { status: 'unresolvable', reason: `objective '${obj.id}' declares no KR '${out.kr}' (has: ${obj.krs.map((k) => k.id).join(', ') || 'none'})` });
+  }
+  return Object.assign(out, { status: 'resolved', reason: `${obj.id}/${kr.id} — ${kr.name}`.slice(0, 160) });
+}
+
+/**
+ * The one normative written form (R-1, as amended 2026-07-28 by PM decision).
+ * Returns null when the input does not resolve to something writable — callers must not invent one.
+ */
+function canonical(resolved, fallbackPeriod) {
+  if (!resolved) return null;
+  if (resolved.kind === 'health') return resolved.budget ? `health:${resolved.budget}` : null;
+  if (resolved.kind !== 'okr' || !resolved.objective) return null;
+  const period = resolved.period || fallbackPeriod || null;
+  if (!period) return null;
+  return resolved.kr ? `${period}:${resolved.objective}:${resolved.kr}` : `${period}:${resolved.objective}`;
+}
+
+module.exports = {
+  parseOkrIndex, readBudgets, resolveAnchor, canonical,
+  objectiveId, krId, stripCommentary, listOkrFiles,
+  ACCEPTED_FORMS,
+  // exported for the tests that assert the widening happened together (R-4)
+  RE_OBJ_HEADING, RE_KR_BULLET,
+};