create-pmos 0.21.0 → 0.23.0

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.21.0",
+      "version": "0.23.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pmos-workspace",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "private": true,
-  "description": "PMOS Terminal Workspace \u2014 local companion hosting real PTYs beside the library and gates (D62)",
+  "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
   "bin": {
     "pmos": "bin/pmos.js"
@@ -29,7 +29,7 @@
     "playwright-core": "^1.61.1",
     "ws": "^8.18.0"
   },
-  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs \u2014 it just stops measuring pixels, and says so.",
+  "//devDependencies": "design-parity's pixel axis only. Kept OUT of dependencies deliberately: `create-pmos workspace` installs this package with `npm install -g`, which takes dependencies and not devDependencies, so an adopter installing a local PM tool does not also install a screenshot differ. design-parity.js requires both optionally and degrades to text+style+geometry when they are absent, so the parity check still runs — it just stops measuring pixels, and says so.",
   "devDependencies": {
     "pixelmatch": "^7.1.0",
     "pngjs": "^7.0.0"

package/workspace/public/pm/data.js

@@ -766,6 +766,11 @@ export async function loadRepos() {
       name,
       kind: prod && prod.kind === 'github' ? 'github' : 'local',
       count: prod && prod.count !== null ? prod.count : null,
+      // The board's OTHER population, published beside the count rather than folded into it — see
+      // `prod.unrecorded` in loadBoard and the sub-line in panel-repos.js#toTuple. A row that
+      // reports only the spine's number is accurate about itself and silent about the rest of the
+      // panel; the two together are what make panel 1 and panel 2 unable to disagree.
+      unrecorded: prod && typeof prod.unrecorded === 'number' ? prod.unrecorded : 0,
     };
   });
 }
@@ -824,12 +829,17 @@ export async function addRepo({ source, kind }) {
     publishBoards();
     const prod = products.get(p.name);
     return {
-      repo: { name: p.name, kind: 'local', count: prod.count },
+      repo: { name: p.name, kind: 'local', count: prod.count, unrecorded: prod.unrecorded || 0 },
       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)' },
+          // The log says WHERE the records were read from, because "0 initiative record(s)" against
+          // a repo that has them is the defect this initiative exists to close — a line naming
+          // `planning/` on a kit repo that keeps them in `pmos/state/` would have described a
+          // directory the server never opened.
+          : { t: 'read ' + (prod.count === 1 ? '1 initiative record' : (prod.count || 0) + ' initiative records')
+              + (prod.unrecorded ? ' · ' + prod.unrecorded + ' artifact group(s) with no record' : ''), c: 'var(--muted-foreground)' },
         { t: 'done — ' + p.name + ' added', c: 'var(--success)' },
       ],
     };

package/workspace/public/pm/panel-repos.js

@@ -57,7 +57,16 @@ function toTuple(r) {
    * read (a folder with no `planning/`, a tree that errored) rendered "local · " — a sub-line that
    * trails off mid-sentence and reads as a bug in the row rather than as "PMOS has not counted
    * this". The dash is the design's own vocabulary for a value that is not there. */
-  const sub = r.sub || (n === null ? '—' : n + (n === 1 ? ' initiative' : ' initiatives'));
+  /* …AND THE ROW MAY NOT STATE A NUMBER THE BOARD CONTRADICTS. The headline count is the SPINE's —
+   * that ruling stands, it is what keeps `176 initiatives` off a repository holding 138 records and
+   * 38 orphans. What it did not cover is the other side of the same coin: with no records found and
+   * artifacts grouped anyway, the row printed a confident `0 initiatives` over a board the PM could
+   * see was not empty, and on this repo it silently dropped 20 groups from a headline of 177. The
+   * second clause names that population in the board's own vocabulary ("artifacts with no
+   * initiative record"), counted separately and never added in. Absent when there are none. */
+  const un = typeof r.unrecorded === 'number' && r.unrecorded > 0 ? r.unrecorded : 0;
+  const sub = r.sub || (n === null ? '—'
+    : n + (n === 1 ? ' initiative' : ' initiatives') + (un ? ' · ' + un + ' unrecorded' : ''));
   const kind = (r.kind || r.source) === 'local' ? 'local' : (r.kind || r.source) === 'github' ? 'github'
     : (r.remote || r.origin) ? 'github' : 'local';
   return [String(id), sub, kind];

package/workspace/server.js

@@ -495,11 +495,97 @@ function findDirsNamed(root, name, maxDepth) {
   return found;
 }
 function planningRoots(root) { return findDirsNamed(root, 'planning', BUNDLE_MAX_DEPTH); }
-// A repo with a planning/ bundle (at any shallow depth) or a DECISIONS.md gets the initiative lens
-// + curated knowledge; anything else is a plain document tree. Detection is nested-aware so a repo
-// that vendors a PMOS bundle under a sub-folder still shows its initiatives (the reported defect).
+
+/*
+ * ── WHERE A REPOSITORY KEEPS ITS INITIATIVE RECORDS ──────────────────────────────────────────
+ *
+ * THE ONE ANSWER. `surfaceSpine` and `surfaceOkr` both used `findDirsNamed(root,'initiatives',2)`
+ * directly, and that search reaches `planning/initiatives/` at the repo root and nothing deeper —
+ * one level above where the scaffolder THIS PROJECT PUBLISHES puts records:
+ *
+ *     planning/initiatives/            depth 2   pmos-self                       … found before
+ *     pmos/planning/initiatives/       depth 3   a bundle vendored under pmos/   … MISSED
+ *     pmos/state/initiatives/          depth 3   every create-pmos kit           … MISSED
+ *
+ * So a kit adopter's repository reported `ok:true, empty:true` — a SUCCESSFUL read of nothing —
+ * and panel 1 printed a confident `0 initiatives` over a repo full of records. `planningRoots`
+ * finds `pmos/planning` (that name IS at depth 2), so the library lens saw the same repo's
+ * documents while the spine saw no records at all: two panels, one repository, contradictory.
+ *
+ * The fact was already in this process twice. `stateDirFor` resolves — and will create —
+ * `pmos/state/`, and `scripts/workflow-state.js#layout`, the engine every ladder derives through,
+ * branches on `pmos/state/initiatives` by name. Only the READ path had never been told.
+ *
+ * DERIVED FROM BUNDLE ROOTS, NOT FROM A DEEPER WALK. Raising BUNDLE_MAX_DEPTH would have found
+ * these directories and also widened `prototype`, `okf`, `skills` and `build-skills` discovery,
+ * for which this change has no finding. Instead each bundle root — the repo root, plus the parent
+ * of every discovered `planning/` and `state/` directory — is asked for the two layouts PMOS
+ * ships. That is a fixed pair of existence checks per bundle root over walks already performed,
+ * and it cannot start proposing records out of a directory nobody vendored.
+ */
+function isDirSafe(p) { try { return fs.statSync(p).isDirectory(); } catch { return false; } }
+
+function bundleRoots(root) {
+  const out = [root];
+  const seen = new Set([path.resolve(root)]);
+  const add = (d) => { const r = path.resolve(d); if (!seen.has(r)) { seen.add(r); out.push(d); } };
+  for (const p of planningRoots(root)) add(path.dirname(p));
+  for (const d of findDirsNamed(root, 'state', BUNDLE_MAX_DEPTH)) add(path.dirname(d));
+  return out;
+}
+
+/** Every directory this repository keeps initiative RECORDS in. Existence-checked, de-duplicated. */
+function initiativeDirs(root) {
+  const out = [];
+  const seen = new Set();
+  const add = (d) => {
+    const r = path.resolve(d);
+    if (seen.has(r) || !isDirSafe(d)) return;
+    seen.add(r); out.push(d);
+  };
+  // The original search first, so no layout that worked before can stop working.
+  for (const d of findDirsNamed(root, 'initiatives', BUNDLE_MAX_DEPTH)) add(d);
+  for (const b of bundleRoots(root)) {
+    add(path.join(b, 'planning', 'initiatives'));       // pmos-self, at the root or in a bundle
+    add(path.join(b, 'state', 'initiatives'));          // the create-pmos kit (kit/build-kit.sh)
+  }
+  return out;
+}
+
+/*
+ * The health-budget registry, read from the bundle root that HAS one.
+ *
+ * `anchors.readBudgets(root)` is a fixed `<root>/planning/okrs/health-budgets.md`. A kit vendors it
+ * to `pmos/planning/okrs/health-budgets.md` (build-kit.sh writes it on every fresh vendor), so in
+ * a kit repo it was never read — and every `parent_kr: health:<id>` resolved against an empty
+ * registry into `unanchored`, with a reason that blamed the record. Finding the records without
+ * this would have replaced an invisible initiative with a misfiled one.
+ *
+ * A repo with no registry ANYWHERE still gets the root-relative `{ok:false}` — absence is reported,
+ * never faked, and `budgets_readable` stays false so the surface can say so.
+ */
+function budgetsFor(A, root) {
+  const first = A.readBudgets(root);
+  if (first && first.ok) return first;
+  for (const b of bundleRoots(root)) {
+    if (path.resolve(b) === path.resolve(root)) continue;
+    const r = A.readBudgets(b);
+    if (r && r.ok) return { ...r, path: path.relative(root, path.join(b, 'planning', 'okrs', 'health-budgets.md')) };
+    // The engine's kit path for the same registry (workflow-state.js#layout).
+    const kit = path.join(b, 'state', 'health-budgets.md');
+    try { return { ok: true, text: fs.readFileSync(kit, 'utf8'), path: path.relative(root, kit) }; }
+    catch { /* not here either — keep looking, then fall back to the root's own answer */ }
+  }
+  return first;
+}
+
+// A repo with a planning/ bundle (at any shallow depth), initiative records in a layout PMOS ships,
+// or a DECISIONS.md gets the initiative lens + curated knowledge; anything else is a plain document
+// tree. Detection is nested-aware so a repo that vendors a PMOS bundle under a sub-folder still
+// shows its initiatives (the reported defect) — including a kit whose records are its whole bundle.
 function wsShape(root) {
-  return planningRoots(root).length || fs.existsSync(path.join(root, 'DECISIONS.md')) ? 'pmos' : 'plain';
+  return planningRoots(root).length || initiativeDirs(root).length
+    || fs.existsSync(path.join(root, 'DECISIONS.md')) ? 'pmos' : 'plain';
 }
 
 // ── Library: the file tree the sidebar browses. ───────────────────────────────────────
@@ -739,12 +825,37 @@ function walkMd(dir, acc) {
   }
   return acc;
 }
+/*
+ * Initiative RECORDS that live outside every planning root — `pmos/state/initiatives/` in a
+ * create-pmos kit. `walkMd` over the planning roots cannot reach them, so in a kit repo the one
+ * document that carries the lane and the anchor was absent from its own initiative's artifact list
+ * even once the spine could see it. They are read through the SAME `docMeta` as every other
+ * document (ROLE_BY_DIR maps an `initiatives/` parent to role `record`, wherever it sits), so the
+ * join, the role and the id come from one implementation rather than a second opinion.
+ */
+function looseRecordMetas(root, proots) {
+  const under = (d) => proots.some((p) => insideRoot(path.resolve(p), path.resolve(d)));
+  const out = [];
+  for (const dir of initiativeDirs(root)) {
+    if (under(dir)) continue;                  // already covered by the planning walk
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of ents) {
+      if (!e.isFile() || !e.name.endsWith('.md') || e.name.startsWith('.')) continue;
+      const m = docMeta(root, path.join(dir, e.name));
+      if (m) out.push(m);
+    }
+  }
+  return out;
+}
+
 function initiativeIndex(root) {
   const proots = planningRoots(root);          // planning/ at the root OR nested (e.g. IDPF/pmos/planning)
   const specimens = specimenMetas(root);       // prototype/<id>/ — outside planning/, grouped by dir
-  if (!proots.length && !specimens.length) return { initiatives: [], ungrouped: [] };
+  const records = looseRecordMetas(root, proots);   // pmos/state/initiatives/ — outside planning/ too
+  if (!proots.length && !specimens.length && !records.length) return { initiatives: [], ungrouped: [] };
   const metas = proots.flatMap((p) => walkMd(p, [])).map((f) => docMeta(root, f))
-    .filter(Boolean).concat(specimens);
+    .filter(Boolean).concat(specimens).concat(records);
   // Pass 1: every id an artifact explicitly declares. Only these are real initiatives —
   // a filename stem is promoted to a group only when it matches a declared id or when
   // several artifacts share it, so a lone research note never invents an initiative.
@@ -811,71 +922,58 @@ function library(root) {
 // ("— not tracked"), never invented (D14/D40 honesty).
 const PHASE_OF = { planning: 'plan', building: 'deliver', blocked: 'deliver', delivered: 'report', accepted: 'report', unknown: 'plan' };
 
-// ── Delivery evidence (board-delivery-truth R-2/R-3). ──────────────────────────────────────────
+// ── Delivery evidence (board-delivery-truth R-2/R-3; shared reader, workflow-status-sweep R-1). ──
 // "Has this shipped?" answered from the trunk's own history rather than from anything anyone typed.
 //
-// ONE `git log` per trunk head, memoised on that sha — ~0.3s and ~800 KB on this repo's 1,214
-// commits, paid once and reused by every surface until the trunk moves. Local only: git reads the
-// object store on disk, so the suite's "no network" guarantee (K. Surfaces) is untouched.
+// THIS DERIVATION NO LONGER LIVES HERE. It was module-private to this file, which meant the GUI's
+// initiative board answered the question with attribution while the engine's ladder
+// (`scripts/workflow-state.js`) answered it without any — `buildCommits` counted every build commit
+// in a range with no idea which initiative it was answering about, and over the trunk reported the
+// same 488 commits as evidence for all 177 initiatives. Two readers, one repository, different
+// answers to "did this ship". `scripts/delivery-index.js` is now the single reader, in the same
+// shape and for the same reason as `scripts/anchor-resolve.js`; its header carries the two-signal
+// rationale that used to be written here.
 //
-// TWO signals, because one is not enough. The branch convention (`initiative/<id>`) is precise but
-// incomplete: 31% of this repo's merged PRs shipped on `claude/*` branches, which match no id. So a
-// commit that MENTIONS the id and TOUCHES a build path counts too. The build-path requirement is
-// what keeps the mention signal honest — `feat(planning): add <id> PRD` mentions the id while
-// delivering nothing, and without the path test every specified initiative would read as shipped.
-const BUILD_EXCLUDE = /^(planning|okf|prototype)\//;
-function isDeliveryPath(f) {
-  if (!f) return false;
-  if (BUILD_EXCLUDE.test(f)) return false;
-  return !/^[^/]+\.md$/.test(f);      // root governance prose (DECISIONS.md, CLAUDE.md…) is not a build
-}
-const deliveryCache = new Map();      // root -> { head, index }
-function trunkRef(root) {
-  for (const c of ['origin/main', 'main', 'origin/master', 'master']) {
-    const r = gitCap(root, ['rev-parse', '--verify', '--quiet', c]);
-    if (r.ok && r.out.trim()) return { ref: c, head: r.out.trim() };
+// Resolution follows the ANCHOR_LIB_PATHS pattern below: a repo checkout first (so a dev surface and
+// CI cannot disagree), then the copy `scripts/vendor-workspace-engine.js` vendors into the bundle.
+// The engine requires this module, so it is already inside the vendored closure — an adopter's
+// install carries it without a second packaging step to remember.
+const DELIVERY_LIB_PATHS = [
+  path.join(__dirname, '..', 'scripts', 'delivery-index.js'),
+  path.join(__dirname, 'lib', 'engine', 'delivery-index.js'),
+];
+function deliveryLib() {
+  for (const p of DELIVERY_LIB_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return require(p); } catch { return null; }
   }
   return null;
 }
-function gitCap(root, args) {
-  try {
-    const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-    if (r.error || r.status !== 0) return { ok: false, out: '', err: (r.stderr || (r.error && r.error.message) || '').trim() };
-    return { ok: true, out: r.stdout || '' };
-  } catch (e) { return { ok: false, out: '', err: String((e && e.message) || e) }; }
+function isDeliveryPath(f) {
+  const D = deliveryLib();
+  // Absent library → no path can be CONFIRMED as a delivery path. Returning `true` here would let
+  // every commit count as delivery evidence in exactly the install where the evidence cannot be
+  // read, which is the false-green direction. `deliveryIndex` below reports the absence out loud.
+  return D ? D.isDeliveryPath(f) : false;
 }
 /**
  * → { ok, reason?, byBranch:Set<id>, byMention:Set<id> }
  * `ok:false` is a REAL answer and never degrades into "nothing was delivered" — the caller renders
  * it red and marks every initiative's delivery `unknown` (R-3). A board that cannot read the
  * history must say so; silently reporting `planning` for 110 shipped initiatives is the failure
- * this whole initiative exists to remove.
+ * this whole initiative exists to remove. A missing library is the same class of answer as an
+ * unreadable history and takes the same `ok:false` path.
  */
 function deliveryIndex(root, ids) {
-  const t = trunkRef(root);
-  if (!t) return { ok: false, reason: 'no trunk branch (main/master) is reachable from this repository — delivery cannot be derived', byBranch: new Set(), byMention: new Set() };
-  const hit = deliveryCache.get(root);
-  if (hit && hit.head === t.head) return hit.index;
-
-  // %x1e separates commits, %x1f separates the message from --name-only's file list.
-  const r = gitCap(root, ['log', '--format=%x1e%s %b%x1f', '--name-only', t.head]);
-  if (!r.ok) {
-    return { ok: false, reason: `git could not read the history at ${t.ref}${r.err ? ` — ${r.err}` : ''}`, byBranch: new Set(), byMention: new Set() };
-  }
-  const byBranch = new Set(), byMention = new Set();
-  const known = Array.isArray(ids) ? ids : [...ids];
-  for (const chunk of r.out.split('\x1e')) {
-    if (!chunk.trim()) continue;
-    const cut = chunk.indexOf('\x1f');
-    const msg = cut < 0 ? chunk : chunk.slice(0, cut);
-    const files = cut < 0 ? [] : chunk.slice(cut + 1).split('\n').map((s) => s.trim()).filter(Boolean);
-    for (const m of msg.matchAll(/initiative\/([A-Za-z0-9][\w.-]*)/g)) byBranch.add(m[1]);
-    if (!files.some(isDeliveryPath)) continue;
-    for (const id of known) if (id.length > 3 && msg.includes(id)) byMention.add(id);
-  }
-  const index = { ok: true, byBranch, byMention };
-  deliveryCache.set(root, { head: t.head, index });
-  return index;
+  const D = deliveryLib();
+  if (!D) {
+    return {
+      ok: false,
+      reason: 'the delivery reader (scripts/delivery-index.js) is not present in this install — delivery cannot be derived here',
+      byBranch: new Set(), byMention: new Set(),
+    };
+  }
+  return D.deliveryIndex(root, ids);
 }
 /**
  * The five states, in precedence order. Every one of them names the artifact it was read from, so
@@ -1075,10 +1173,10 @@ function surfaceOkr(root) {
   // Anchor health, NOT the initiative↔KR join — the join is an explicit non-goal of this spec. What
   // is reported is only whether each anchor names something these documents declare, because an
   // anchor pointing at nothing is precisely what went unseen for two days.
-  const budgets = A.readBudgets(root);
+  const budgets = budgetsFor(A, root);
   const unresolvable = [];
   let checked = 0, empty = 0;
-  for (const dir of findDirsNamed(root, 'initiatives', BUNDLE_MAX_DEPTH)) {
+  for (const dir of initiativeDirs(root)) {
     let files = [];
     try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')); } catch { continue; }
     for (const f of files) {
@@ -1124,7 +1222,7 @@ function surfaceSpine(root) {
   if (!index.ok) {
     return { objectives: [], budgets: [], unanchored: [], unreadable: index.error || 'the OKR documents could not be read' };
   }
-  const budgetsDoc = A.readBudgets(root);
+  const budgetsDoc = budgetsFor(A, root);
 
   // the empty spine, keyed for O(1) attachment below
   const objectives = index.objectives.map((o) => ({
@@ -1138,7 +1236,7 @@ function surfaceSpine(root) {
   const budgets = new Map();       // health:<id> groups — peers of objectives (D59), not a footnote
   const unanchored = [];           // R6 — never dropped to make the tree tidy
 
-  for (const dir of findDirsNamed(root, 'initiatives', BUNDLE_MAX_DEPTH)) {
+  for (const dir of initiativeDirs(root)) {
     let files = [];
     try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort(); } catch { continue; }
     for (const f of files) {