create-pmos 0.10.0 → 0.11.0

package/README.md

@@ -333,6 +333,66 @@ 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.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.**
+
+- **Upgrades will keep reaching you.** The launcher decides whether to reinstall the workspace by
+  comparing the app version it bundles against the one you have. 0.10.0 shipped the *kit* at 0.10.0
+  but the bundled app still labelled **0.9.1** — so the next release would have compared equal,
+  decided you were current, and **silently skipped the upgrade**. Which is precisely the failure
+  0.9.1 existed to fix. The two versions are now checked against each other by the test suite, so it
+  cannot drift again unnoticed.
+- **Alignment no longer offers to edit its own notes.** The change-context digest quotes every change
+  you make, so it matched the "quotes text this change altered" rule on the very first save in any
+  repository — and topped the list of documents to realign. A generated file proposing to realign
+  itself. Machine-written state is now excluded from alignment entirely.
+
+If you installed 0.10.0, run `npx create-pmos@latest workspace` once. Nothing was damaged by either
+bug; the first would have cost you a future upgrade, and the second a confusing first suggestion.
+
 ## What's new in 0.10.0
 
 **Editing a document now does something for the rest of them.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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@1771814
-assembled: 2026-07-28
+kernel-source: pmos@cb9565d
+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;
@@ -140,6 +141,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,6 +183,7 @@ 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,
     },
   };

package/workspace/lib/layout.js

@@ -31,15 +31,17 @@
 
   const SIDE_MIN = 160, SIDE_MAX = 520;
   const READ_MIN = 280, READ_MAX = 1000;
+  const LIB_MIN = 15, LIB_MAX = 80;                       // the library/document divider, percent
   const BOTTOM_H = 300;                                   // the reader's height when docked bottom
+  const LIB_DEFAULT = 46;
 
   // `review` is byte-for-byte the arrangement that shipped before this feature (R2): a PM who
   // never opens the layout control must see no change at all.
   const STOCK = [
-    { id: 'focus',   name: 'focus',   key: 1, side: 'off',  reader: 'off',    split: 'off', sideW: 262, readW: 400 },
-    { id: 'read',    name: 'read',    key: 2, side: 'left', reader: 'left',   split: 'off', sideW: 214, readW: 760 },
-    { id: 'compare', name: 'compare', key: 3, side: 'left', reader: 'off',    split: 'on',  sideW: 214, readW: 400 },
-    { id: 'review',  name: 'review',  key: 4, side: 'left', reader: 'right',  split: 'off', sideW: 262, readW: 400 },
+    { id: 'focus',   name: 'focus',   key: 1, side: 'off',  reader: 'off',    split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
+    { id: 'read',    name: 'read',    key: 2, side: 'left', reader: 'left',   split: 'off', sideW: 214, readW: 760, libSplit: LIB_DEFAULT },
+    { id: 'compare', name: 'compare', key: 3, side: 'left', reader: 'off',    split: 'on',  sideW: 214, readW: 400, libSplit: LIB_DEFAULT },
+    { id: 'review',  name: 'review',  key: 4, side: 'left', reader: 'right',  split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
   ];
   const DEFAULT_ID = 'review';
   const STOCK_IDS = STOCK.map((l) => l.id);
@@ -86,6 +88,11 @@
       split: oneOf(r.split, SPLIT, base ? base.split : 'off'),
       sideW: Math.round(clamp(num(r.sideW, base ? base.sideW : 262), SIDE_MIN, SIDE_MAX)),
       readW: Math.round(clamp(num(r.readW, base ? base.readW : 400), READ_MIN, READ_MAX)),
+      // the library/document divider. It lives IN the tuple rather than in localStorage because R8
+      // promises to carry it across the upgrade and dimension 1 counts it as "nothing lost" — a
+      // global client key can satisfy neither: it is not per-workspace, and it goes on being read
+      // from the pre-feature store on every boot, which R8 explicitly forbids.
+      libSplit: Math.round(clamp(num(r.libSplit, base ? base.libSplit : LIB_DEFAULT), LIB_MIN, LIB_MAX) * 10) / 10,
       folds: folds(r.folds),
       lastUsedAt: Math.max(0, Math.round(num(r.lastUsedAt, 0))),
     };
@@ -140,16 +147,26 @@
   }
 
   /* A layout that hides every pane is legal (`focus` is exactly that) — but a layout the PM
-     cannot get OUT of is not. The header control is always rendered, so the only real dead end
-     would be a template with no terminal track; assert it here so a future edit cannot introduce
-     one silently (rubric dimension 1, checklist item 4). */
+     cannot get OUT of is not.
+
+     HONEST SCOPE, and read this before trusting it: every branch of gridFor() unconditionally
+     emits a `term` cell, so this can only fail if someone edits gridFor. It is a change-detector
+     for that one function — NOT evidence for rubric dimension 1's checklist item 4. A Review-Gate
+     evaluator fuzzed 38,416 layouts through it for zero failures and correctly called it vacuous.
+     The property item 4 actually names — the control that un-hides a pane is itself always
+     reachable — is a fact about the DOM (the chip lives in `.bar`, a grid sibling of `#bodyGrid`,
+     and the position controls in `.lay-pos` can always restore a pane), and it is asserted where
+     it can genuinely fail: ui-test.js walks all twelve side × reader states in a real engine. */
   function hasEscape(l) {
     return gridFor(l).areas.indexOf('term') !== -1;
   }
 
   /* R8 — carry the pre-feature client keys into this workspace's `review` so nobody's tuning is
      lost on upgrade. Reads the five localStorage values the shipped app wrote:
-     rail(on|off) railw(<n>px) libsplit(<n>%) fold-lib(on|off) fold-doc(on|off). */
+     rail(on|off) railw(<n>px) libsplit(<n>%) fold-lib(on|off) fold-doc(on|off).
+     It formerly said "five" and read four — `libsplit` was collected by the caller and dropped
+     here, so R8's promise was false for it and the pre-feature key went on being read at every
+     boot. Review-Gate finding: the comment was the spec, and the code disagreed with it. */
   function migrateLegacy(legacy) {
     const g = (k) => (legacy && typeof legacy === 'object' ? legacy[k] : null);
     const review = stockLayout(DEFAULT_ID);
@@ -157,15 +174,33 @@
     if (railOff) review.reader = 'off';
     const w = num(String(g('railw') || '').replace('px', ''), null);
     if (w !== null) review.readW = Math.round(clamp(w, READ_MIN, READ_MAX));
+    const ls = num(String(g('libsplit') || '').replace('%', ''), null);
+    if (ls !== null) review.libSplit = Math.round(clamp(ls, LIB_MIN, LIB_MAX) * 10) / 10;
     if (g('fold-lib') === 'off') review.folds.lib = false;
     if (g('fold-doc') === 'off') review.folds.doc = false;
     const layouts = stockLayouts().map((l) => (l.id === DEFAULT_ID ? review : l));
     return { layouts, currentId: DEFAULT_ID };
   }
 
+  /* What a GET /api/layouts response entitles the client to DO. Split out as a pure function
+     because the original inline condition conflated two very different states — "this workspace
+     has never stored a layout" and "I could not read what it stored" — and answered both by
+     migrating and then WRITING, silently replacing a real stored document whenever a read failed.
+     A read failure must never author a write.
+
+       'migrate' — the server affirmatively says nothing is stored (first run here): R8 applies.
+       'use'     — a stored document came back: adopt it.
+       'keep'    — the answer is unusable (transport error, non-JSON, !ok, or no `stored` flag).
+                   Hold the boot defaults in memory and WRITE NOTHING. */
+  function loadAction(doc) {
+    if (!doc || doc.ok !== true || typeof doc.stored !== 'boolean') return 'keep';
+    return doc.stored ? 'use' : 'migrate';
+  }
+
   return {
     SIDE, READER, SPLIT, FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
-    SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, BOTTOM_H,
+    SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, LIB_MIN, LIB_MAX, LIB_DEFAULT, BOTTOM_H,
     isStock, stockLayout, stockLayouts, layout, sanitize, gridFor, hasEscape, migrateLegacy,
+    loadAction,
   };
 });

package/workspace/package.json

@@ -1,17 +1,21 @@
 {
   "name": "pmos-workspace",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
-  "bin": { "pmos": "bin/pmos.js" },
+  "bin": {
+    "pmos": "bin/pmos.js"
+  },
   "scripts": {
     "start": "node server.js",
     "test": "node test.js",
     "test:ui": "node ui-test.js",
     "doctor": "node doctor.js"
   },
-  "engines": { "node": ">=18" },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/addon-web-links": "^0.12.0",