create-pmos 0.10.0 → 0.11.0

package/workspace/public/index.html

@@ -34,6 +34,11 @@
     <div class="lay-menu" id="layMenu" hidden role="dialog" aria-label="Layouts">
       <div class="lay-cap">layouts</div>
       <div id="layList"></div>
+      <!-- R12 — every position the pointer drag can reach is also a button here. Without this,
+           putting the sidebar on the right or docking the reader at the bottom was pointer-only:
+           no stock layout carries either, and the grip's Enter/Space merely opened this menu,
+           which had nothing in it that could move a pane. -->
+      <div class="lay-pos" id="layPos"></div>
       <form class="lay-new miniform" id="layNewForm" hidden>
         <label class="lbl" for="layNewName">name this layout</label>
         <input id="layNewName" type="text" placeholder="e.g. two agents + prd" autocomplete="off" spellcheck="false" maxlength="40" />
@@ -42,7 +47,7 @@
       </form>
       <button class="lay-add" id="layNewBtn">＋ new layout from this arrangement</button>
       <p class="lay-foot">Layouts belong to <b id="layScope">this repo</b>. Drag a pane by its ⠿ grip,
-        or an edge to resize — whatever you change is kept.</p>
+        or an edge to resize — or use the buttons above. Whatever you change is kept.</p>
     </div>
   </header>
 
@@ -52,39 +57,20 @@
        resize handle. DOM order is fixed; only the grid decides where a pane lands. -->
   <div class="body" id="bodyGrid">
 
-    <nav class="side" id="side" aria-label="Workspaces and running agents">
+    <!-- ONE tree (R1): repositories → their working trees, each labelled by the initiative on its
+         branch → that tree's sessions. It replaces the old `workspaces` + `running agents` pair,
+         which split a parent from its children across two panes and made the PM correlate a live
+         count against a separate list. The fold key stays `ws` so an arrangement saved before this
+         change still resolves; `sess` is retired and ignored (R13). -->
+    <nav class="side" id="side" aria-label="Repositories, initiatives and running agents">
       <div class="edge" id="sideEdge" data-edge="side" role="separator" aria-label="Resize the sidebar" tabindex="0"></div>
       <section class="pane" id="paneWs">
         <div class="cap">
           <span class="grip" id="sideGrip" data-pane="side" role="button" tabindex="0"
             aria-label="Move the sidebar" title="Move this column">⠿</span>
-          <button class="fold" id="wsFold" data-fold="ws" aria-expanded="true" title="Hide the workspaces"><span class="chev" aria-hidden="true">▾</span>workspaces</button>
+          <button class="fold" id="wsFold" data-fold="ws" aria-expanded="true" title="Hide the work tree"><span class="chev" aria-hidden="true">▾</span>work</button>
+          <span class="ct" id="needCount"></span>
           <button class="mini" id="addWsBtn" aria-expanded="false" title="Add a repository">＋</button></div>
-        <div class="pane-body">
-          <div id="workspaces"></div>
-          <form class="miniform" id="addWsForm" hidden>
-            <button type="button" class="pick" id="pickFolderBtn">📁 Choose folder…</button>
-            <label class="lbl" for="addWsPath">or type a path</label>
-            <input id="addWsPath" type="text" placeholder="/path/to/another/repo" aria-label="Path to a repository" autocomplete="off" spellcheck="false" />
-            <div class="row">
-              <button type="submit" class="go">add</button>
-              <button type="button" class="quiet" id="addWsCancel">cancel</button>
-            </div>
-            <p class="hint">or just run <code>pmos</code> inside that repo</p>
-          </form>
-          <!-- Worktrees the workspace made are folders the PM has to live with, so the app that
-               creates them is the app that clears them. Hidden entirely until there is one. -->
-          <details class="wtbox" id="wtBox" hidden>
-            <summary id="wtSummary">worktrees</summary>
-            <div id="wtList"></div>
-          </details>
-        </div>
-      </section>
-
-      <section class="pane" id="paneSess">
-        <div class="cap">
-          <button class="fold" id="sessFold" data-fold="sess" aria-expanded="true" title="Hide the running agents"><span class="chev" aria-hidden="true">▾</span>running agents</button>
-          · <span id="sessCount"></span> <span class="ct" id="needCount"></span></div>
         <div class="pane-body">
           <button class="newsess" id="newBtn" aria-expanded="false"><i>＋</i> new session — run an agent here</button>
           <form class="miniform" id="newForm" hidden>
@@ -111,9 +97,27 @@
               <button type="button" class="quiet" id="newCancel">cancel</button>
             </div>
           </form>
-          <div id="sessions"></div>
+          <div id="tree"></div>
+          <div id="workspaces" hidden></div>
+          <form class="miniform" id="addWsForm" hidden>
+            <button type="button" class="pick" id="pickFolderBtn">📁 Choose folder…</button>
+            <label class="lbl" for="addWsPath">or type a path</label>
+            <input id="addWsPath" type="text" placeholder="/path/to/another/repo" aria-label="Path to a repository" autocomplete="off" spellcheck="false" />
+            <div class="row">
+              <button type="submit" class="go">add</button>
+              <button type="button" class="quiet" id="addWsCancel">cancel</button>
+            </div>
+            <p class="hint">or just run <code>pmos</code> inside that repo</p>
+          </form>
+          <!-- Worktrees the workspace made are folders the PM has to live with, so the app that
+               creates them is the app that clears them. Hidden entirely until there is one. -->
+          <details class="wtbox" id="wtBox" hidden>
+            <summary id="wtSummary">worktrees</summary>
+            <div id="wtList"></div>
+          </details>
         </div>
       </section>
+
     </nav>
 
     <main class="term-col" aria-label="Sessions and terminal">
@@ -187,12 +191,12 @@
           <span class="grip" id="readGrip" data-pane="reader" role="button" tabindex="0"
             aria-label="Move the reader" title="Move this pane">⠿</span>
           <button class="fold" id="libFold" aria-expanded="true" title="Hide the library"><span class="chev" aria-hidden="true">▾</span>library</button>
-          <span class="lens" role="tablist" aria-label="Library view">
-            <button role="tab" data-lens="initiatives" aria-selected="true">initiatives</button>
-            <button role="tab" data-lens="folders" aria-selected="false">folders</button>
-            <button role="tab" data-lens="scheduled" aria-selected="false">scheduled</button>
-            <button role="tab" data-lens="history" aria-selected="false">history</button>
-          </span>
+          <!-- R7 — the four standing lenses are gone. What the rail shows follows the SELECTION:
+               a repository group gives repo detail (the folder map, its schedules, its history), a
+               tree row gives that initiative's dossier. The views below are the sub-views of
+               whichever of those two is current, rendered by renderLensTabs(). -->
+          <span class="lens" role="tablist" aria-label="Detail view" id="lensTabs"></span>
+          <span class="reading" id="libWho" title="the repository these documents come from"></span>
           <button class="mini librefresh" id="libRefresh" title="Rescan the repository for new files & folders" aria-label="Refresh the library">↻</button>
         </div>
         <div class="pane-body">

package/workspace/public/styles.css

@@ -258,8 +258,10 @@ button{font:inherit;color:inherit;background:none;border:0;cursor:pointer}
 .cap .fold .chev{font-size:var(--text-2xs);transition:transform var(--duration-fast) var(--ease-emphasized)}
 .pane[data-fold="off"] .cap .fold .chev{transform:rotate(-90deg)}
 @media (prefers-reduced-motion:reduce){.cap .fold .chev{transition:none}}
-/* the move affordance every relocatable pane carries. Keyboard reaches every position it
-   offers through the layout menu, so this is an accelerator and never the only path (R12). */
+/* the move affordance every relocatable pane carries. Keyboard reaches every position it offers
+   through the layout menu's position controls (`.lay-pos`), so this is an accelerator and never
+   the only path (R12). That was asserted here before it was true — the menu had no position
+   controls at all, and `side:right` / `reader:bottom` were pointer-only. Review-Gate finding. */
 .cap .grip{width:22px;min-height:26px;display:grid;place-items:center;border-radius:var(--radius-sm);flex:none;
   color:var(--muted-foreground);cursor:grab;letter-spacing:-2px;margin-left:-4px;touch-action:none}
 .cap .grip:hover{background:var(--accent);color:var(--brand)}
@@ -316,6 +318,22 @@ button{font:inherit;color:inherit;background:none;border:0;cursor:pointer}
   border-radius:var(--radius-sm);color:var(--muted-foreground);font-size:var(--text-xs);flex:none}
 .lay-act:hover{background:var(--secondary);color:var(--brand)}
 .lay-act.del:hover{color:var(--destructive)}
+
+/* R12 — the position controls. Every value the pointer drag can produce is a focusable button
+   here, which is what makes "the layout control can always bring a pane back" a fact about the
+   DOM rather than an argument about the grid template. */
+.lay-pos{margin-top:6px;padding-top:6px;border-top:1px solid var(--border);display:grid;gap:4px}
+.pos-row{display:flex;align-items:center;gap:3px}
+.pos-lbl{font-size:var(--text-2xs);color:var(--muted-foreground);width:52px;flex:none}
+.pos-btn{flex:1;min-height:34px;display:flex;flex-direction:column;align-items:center;justify-content:center;
+  gap:1px;border-radius:var(--radius-sm);border:1px solid transparent;color:var(--muted-foreground);
+  font-size:var(--text-2xs);line-height:1}
+.pos-btn i{font-style:normal;font-size:var(--text-sm)}
+.pos-btn:hover{background:var(--accent);color:var(--accent-foreground)}
+.pos-btn:focus-visible{outline:2px solid var(--ring);outline-offset:1px}
+.pos-btn[aria-pressed="true"]{background:var(--accent);color:var(--brand);border-color:var(--ring);font-weight:500}
+/* a coarse pointer gets the 44px target R12 asks for; a mouse does not need the extra height */
+@media (pointer:coarse){.pos-btn{min-height:44px}.lay-act{min-width:44px;min-height:44px}.lay-row{padding:11px 8px}}
 .lay-add{display:block;width:100%;margin-top:4px;padding:9px;border:1px dashed var(--border);
   border-radius:var(--radius-md);font-size:var(--text-sm);color:var(--muted-foreground);
   transition:color var(--duration-fast) var(--ease-emphasized),
@@ -1313,3 +1331,104 @@ line-height:1.35;cursor:pointer}
   border-top:1px solid var(--border);border-bottom:1px solid var(--border);padding:6px 0}
 .al-err{margin-top:9px;padding:8px 11px;border-radius:var(--radius-md);border:1px solid var(--destructive);
   background:rgba(242,101,95,.08);font-size:var(--text-sm);line-height:1.5;color:var(--foreground)}
+
+/* ── The sidebar tree (workspace-initiative-nav-build, R1–R6) ─────────────────────────────────
+   Repository → its working trees, each labelled by the initiative on its branch → sessions.
+   Replaces the old `workspaces` + `running agents` pair. Session-row styles are reused verbatim
+   from that pane — only the nesting is new. Colours go through the D38 semantic tokens: a hex
+   fallback here would be a second source of truth for a value the token layer owns, which is the
+   drift `token-hygiene` exists to catch. */
+.repo-group{margin-bottom:6px}
+.repo-head{display:flex;align-items:center;gap:6px;width:100%;padding:4px 8px;background:none;
+  border:0;color:var(--foreground);font:inherit;font-weight:600;font-size:var(--text-xs);
+  cursor:default;text-align:left}
+.repo-head .cue{color:var(--muted-foreground);font-size:var(--text-2xs)}
+.repo-head small{margin-left:auto;color:var(--muted-foreground);font-family:var(--mono);font-size:var(--text-2xs)}
+
+.treerow{border-left:2px solid transparent}
+.treerow[data-open="true"]{border-left-color:var(--border)}
+.tr-head{display:flex;align-items:flex-start}
+.tr-toggle{background:none;border:0;color:var(--muted-foreground);cursor:pointer;
+  padding:6px 2px 6px 8px;font:inherit;line-height:1.2}
+.tr-toggle .cue{font-size:var(--text-2xs)}
+.tr{flex:1;min-width:0;display:block;text-align:left;background:none;border:0;color:inherit;
+  font:inherit;padding:5px 6px 6px 0;cursor:pointer}
+.tr:hover,.tr-head:hover .tr{background:var(--accent)}
+.tr[aria-current="true"]{background:var(--accent);font-weight:500}
+.tr .r1{display:flex;align-items:baseline;gap:6px}
+.tr .r1 .g{font-size:var(--text-2xs);width:9px;flex:none}
+.treerow[data-st="working"] .r1 .g{color:var(--success)}
+.treerow[data-st="quiet"] .r1 .g,
+.treerow[data-st="idle"] .r1 .g,
+.treerow[data-st="exited"] .r1 .g{color:var(--muted-foreground)}
+.treerow[data-st="blocked"] .r1 .g{color:var(--destructive)}
+.tr .r1 .nm{font-size:var(--text-xs);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.tr .r1 .dir{margin-left:auto;flex:none;font-family:var(--mono);font-size:var(--text-2xs);
+  color:var(--muted-foreground)}
+.tr .r2{display:flex;flex-wrap:wrap;gap:6px;align-items:baseline;padding-left:15px;margin-top:2px;
+  font-family:var(--mono);font-size:var(--text-2xs);color:var(--muted-foreground)}
+.tr .wf{display:inline-flex;gap:6px;align-items:baseline}
+.tr .wf .lane{color:var(--muted-foreground)}
+.tr .wf .stg{color:var(--brand)}
+.tr .wf .nx{color:var(--muted-foreground)}
+.tr .wf .bl,.tr .r2 .bl{color:var(--destructive)}
+.tr .wf .drv{color:var(--muted-foreground);font-style:italic}
+.tr .needs-n{color:var(--warning)}
+.tr .rollup{color:var(--muted-foreground)}
+/* R5 — the branch a ladder was derived from, and when. Never optional when a stage is shown. */
+.tr .attrib{display:block;padding-left:15px;margin-top:2px;font-family:var(--mono);
+  font-size:var(--text-2xs);color:var(--muted-foreground)}
+.tr .attrib b{color:var(--foreground);font-weight:500}
+.tr-sessions{padding-left:14px}
+.tree-new{display:block;width:calc(100% - 8px);margin:2px 0 6px 4px;padding:4px 8px;background:none;
+  border:1px dashed var(--border);border-radius:var(--radius-sm);color:var(--muted-foreground);
+  font:inherit;font-size:var(--text-2xs);cursor:pointer;text-align:left}
+.tree-new:hover{color:var(--foreground);border-color:var(--input)}
+.cap .ct[data-bad="1"]{color:var(--destructive)}
+
+/* ── The rail's initiative dossier (R7·R8·R9) ────────────────────────────────────────────────── */
+.reading{font-family:var(--mono);font-size:var(--text-2xs);color:var(--muted-foreground);
+  overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:12ch}
+.reading[data-away="1"]{color:var(--warning);max-width:none}
+.dz-head{padding:10px 12px 8px;border-bottom:1px solid var(--border)}
+.dz-id{font-size:var(--text-sm);font-weight:600;letter-spacing:-.01em}
+.dz-t{font-size:var(--text-xs);color:var(--muted-foreground);margin-top:2px;line-height:1.4}
+.dz-meta{display:flex;gap:5px;flex-wrap:wrap;margin-top:7px}
+.dz-meta .pill{font-family:var(--mono);font-size:var(--text-2xs);padding:2px 5px;
+  border-radius:var(--radius-sm);background:var(--secondary);color:var(--muted-foreground);
+  border:1px solid var(--border)}
+.dz-meta .pill.lane{color:var(--purple)}
+/* R5 — the branch a ladder came from, never optional beside a stage */
+.dz-attrib{margin-top:7px;font-family:var(--mono);font-size:var(--text-2xs);
+  color:var(--muted-foreground);line-height:1.5}
+.dz-attrib b{color:var(--foreground);font-weight:500}
+.dz-attrib .sub{display:block;opacity:.85}
+.dz-next{margin:9px 12px;padding:8px 10px;border-radius:var(--radius-md);background:var(--success-wash);
+  border:1px solid var(--border);font-size:var(--text-xs);color:var(--foreground);line-height:1.5}
+.dz-next b{display:block;font-family:var(--mono);font-size:var(--text-2xs);letter-spacing:.12em;
+  text-transform:uppercase;color:var(--success);margin-bottom:3px;font-weight:500}
+/* accepted AND owing, together — a green badge alone is the watermelon */
+.dz-next.owed{background:var(--warning-wash)}
+.dz-next.owed b{color:var(--warning)}
+.dz-next.done b{color:var(--muted-foreground)}
+.dz-wait{margin:9px 12px;font-size:var(--text-xs);color:var(--muted-foreground);line-height:1.5}
+.dz-wait .sub{display:block;font-size:var(--text-2xs);margin-top:3px;opacity:.85}
+.dz-none{margin:9px 12px;font-size:var(--text-xs);color:var(--muted-foreground);line-height:1.55}
+.dz-arts{padding:0 12px 14px}
+.dz-sec{padding-top:10px}
+.dz-sec+.dz-sec{border-top:1px solid var(--border);margin-top:8px}
+.dz-sec h5{display:flex;gap:7px;align-items:baseline;font-family:var(--mono);
+  font-size:var(--text-2xs);letter-spacing:.13em;text-transform:uppercase;
+  color:var(--muted-foreground);font-weight:500;margin-bottom:5px}
+.dz-sec h5 .c{opacity:.8;letter-spacing:0}
+.dz-art{display:flex;gap:7px;align-items:baseline;width:100%;text-align:left;padding:4px 7px;
+  margin-bottom:3px;border-radius:var(--radius-sm);background:var(--card);border:1px solid var(--border);
+  color:inherit;font:inherit;cursor:pointer}
+.dz-art:hover{border-color:var(--input);background:var(--accent)}
+.dz-art .role{font-family:var(--mono);font-size:var(--text-2xs);letter-spacing:.1em;
+  text-transform:uppercase;color:var(--info);width:74px;flex:none}
+.dz-art .pth{font-family:var(--mono);font-size:var(--text-2xs);color:var(--muted-foreground);
+  overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+/* `n/a for this lane` must never look like `missing` — that difference is the whole of R8 */
+.dz-na{font-size:var(--text-2xs);color:var(--muted-foreground);font-style:italic;line-height:1.5;
+  padding:2px 0 4px}

package/workspace/server.js

@@ -68,6 +68,7 @@ const skillStore = require('./lib/skill-store');
 const remoteAccess = require('./lib/remote-access');   // tailnet bind + token guard (D62) + origin/host allowlist (D64)
 const rateLimit = require('./lib/rate-limit');         // per-connection token bucket for spawn/input (D64 A3)
 const consoleState = require('./lib/console-state');   // read-only console surfaces over file-mode state (D64 B)
+const boardCache = require('./lib/board-cache');   // the workflow board, cached + derived off the event loop (R4)
 const fmParse = require('./lib/file-mode-parse');      // canonical file-mode parsers, shared with metrics.py (D64 D)
 const gitInfo = require('./lib/git-info');             // read-mostly branch awareness + select/create at session start
 const tmuxControl = require('./lib/tmux-control');     // tmux -CC protocol: the pane's raw stream, so xterm.js keeps its scrollback
@@ -217,14 +218,47 @@ function homeWorkspace() {
   return HOME_ENABLED ? workspaces.get(wsId(SELF_ROOT)) : [...workspaces.values()][0];
 }
 function getWs(id) { return (id && workspaces.get(id)) || homeWorkspace(); }
+// R2/R3 — what the sidebar tree needs and cannot derive for itself: which REPOSITORY a registered
+// working tree belongs to, and which branch it is on. `git worktree list` names the main worktree
+// first from any of a repo's trees (git-info.worktreesAt), so index 0 is the group key: it is what
+// turns `pmos` and `pmos ⑂ initiative/foo` from two peer rows into a parent and its child.
+// Both shell git, so both are memoised — wsList() runs on every workspace push.
+const REPO_KEY_TTL_MS = 15000;
+const repoKeyCache = new Map();   // root -> { at, key, name, branch }
+function repoIdentity(root) {
+  const hit = repoKeyCache.get(root);
+  const now = Date.now();
+  if (hit && now - hit.at < REPO_KEY_TTL_MS) return hit;
+  let key = root, name = path.basename(root), branch = null, branchError = null;
+  try {
+    const trees = gitInfo.worktrees(root);
+    if (trees.length && trees[0].dir) { key = path.resolve(trees[0].dir); name = path.basename(key); }
+  } catch { /* not a repo, or git absent — the tree is its own group, which is the truth */ }
+  try {
+    const bi = gitInfo.branchInfo(root);
+    if (bi.ok) branch = bi.detached ? null : bi.current;
+    else branchError = bi.error || 'branch could not be read';
+  } catch { branchError = 'branch could not be read'; }
+  const val = { at: now, key, name, branch, branchError };
+  repoKeyCache.set(root, val);
+  return val;
+}
 function wsList() {
-  return [...workspaces.values()].map((w) => ({
-    id: w.id, name: w.name, root: w.root, home: HOME_ENABLED && w.root === SELF_ROOT,
-    shape: wsShape(w.root), addedAt: w.addedAt,
-    sessions: [...sessions.values()].filter((s) => s.ws === w.id).length,
-  }));
+  return [...workspaces.values()].map((w) => {
+    const rid = repoIdentity(w.root);
+    return {
+      id: w.id, name: w.name, root: w.root, home: HOME_ENABLED && w.root === SELF_ROOT,
+      shape: wsShape(w.root), addedAt: w.addedAt,
+      sessions: [...sessions.values()].filter((s) => s.ws === w.id).length,
+      // the repository this working tree belongs to, and the branch it is on
+      repo_key: rid.key, repo_name: rid.name, branch: rid.branch, branch_error: rid.branchError,
+    };
+  });
 }
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'vendor', 'target', 'coverage', '.git', 'tmp', 'out']);
+// The directories stateDirFor() resolves to. Their contents are machine-written runtime and curated
+// records — never documents alignment should offer to edit.
+const STATE_DIR_NAMES = new Set(['state', '.pmos']);
 const PLAIN_MAX_DEPTH = 3;      // the curated (knowledge) view stays shallow
 const TREE_MAX_DEPTH = 6;       // the folder lens is a real explorer, but bounded on huge/slow repos
 const TREE_MAX_NODES = 4000;    // …and node-budgeted so a giant repo (or Google Drive) never hangs
@@ -317,6 +351,11 @@ function markdownDocs(root, limit = 800) {
       if (e.name.startsWith('.') || SKIP_DIRS.has(e.name)) continue;
       const full = path.join(dir, e.name);
       const r = rel ? rel + '/' + e.name : e.name;
+      // Machine-written state is not a document the PM maintains, and alignment must never propose
+      // realigning it. change-context.md in particular QUOTES every change, so it matches the
+      // quoted-text rule on the first save in any repository and would top the candidate list —
+      // a generated file suggesting itself, found by installing the published artifact and using it.
+      if (STATE_DIR_NAMES.has(e.name)) continue;
       if (e.isDirectory()) walk(full, r, depth + 1);
       else if (preview.previewKind(e.name) === 'markdown') out.push(r);
     }
@@ -367,8 +406,11 @@ function readTextDoc(root, rel) {
 // filesystem, useless for "show me everything for pmos-jira-sync". This projection joins
 // them on the initiative_id the artifacts already declare in their own identity block,
 // falling back to the filename convention when an artifact declares nothing.
+// Ordered LONGEST-DISCRIMINATOR-FIRST: `-copy-brief` must be tested before `-brief`, and
+// `-eval-rubric` before any `-rubric`, because the first match wins and slices the stem.
 const ROLE_SUFFIXES = [
   ['-eval-rubric', 'rubric'], ['-design-brief', 'design brief'], ['-design-reference', 'design'],
+  ['-copy-brief', 'copy brief'], ['-user-stories', 'user stories'], ['-copy', 'copy'],
   ['-dogfood', 'dogfood'], ['-reconcile', 'reconcile'], ['-findings', 'findings'],
   ['-scoping', 'scoping'], ['-intake', 'intake'], ['-brief', 'brief'], ['-prd', 'PRD'],
 ];
@@ -377,6 +419,43 @@ const ROLE_BY_DIR = {
   okrs: 'OKR', radar: 'radar', gtm: 'gtm', 'out-of-scope': 'rejected', 'harness-refine': 'harness',
   'design-export': 'design', explainers: 'explainer', fixtures: 'fixture',
 };
+// ── D60 specimens: prototype/<id>/, deliberately OUTSIDE planning/ ───────────────────────────
+// The planning walk cannot reach them (planningRoots only finds `planning`), so a prototype leg was
+// invisible on the initiative that produced it — and D60 makes the specimen a PRECONDITION of the
+// PRD, so the missing artifact was the one that gates the rest.
+//
+// Grouping here is by DIRECTORY NAME, not by a parsed declaration: `prototype/<id>/` is the lane's
+// own convention, so attribution comes from where a file lives. That is deliberately STRICTER than
+// the planning path, whose parseHead() matches `initiative_id:` anywhere in the first 4 KB — body
+// text can therefore claim a document there, and widening the scan must not widen that laxity.
+// HTML counts here (it does nowhere else in the index): a lookable specimen is the artifact.
+function specimenRoots(root) { return findDirsNamed(root, 'prototype', BUNDLE_MAX_DEPTH); }
+const SPECIMEN_ROLE = { 'brief.md': 'brief', 'grilling.md': 'grilling', 'readme.md': 'doc' };
+function specimenMetas(root) {
+  const out = [];
+  for (const proot of specimenRoots(root)) {
+    let dirs = [];
+    try { dirs = fs.readdirSync(proot, { withFileTypes: true }); } catch { continue; }
+    for (const d of dirs) {
+      if (!d.isDirectory() || d.name.startsWith('.') || SKIP_DIRS.has(d.name)) continue;
+      let files = [];
+      try { files = fs.readdirSync(path.join(proot, d.name), { withFileTypes: true }); } catch { continue; }
+      for (const f of files) {
+        if (!f.isFile() || f.name.startsWith('.')) continue;
+        const html = /\.html?$/i.test(f.name);
+        if (!html && !f.name.endsWith('.md')) continue;
+        const full = path.join(proot, d.name, f.name);
+        out.push({
+          path: path.relative(root, full), name: f.name,
+          role: SPECIMEN_ROLE[f.name.toLowerCase()] || (html ? 'specimen' : 'doc'),
+          initiative: d.name, stem: d.name, title: null, status: null, stage: null, kr: null,
+        });
+      }
+    }
+  }
+  return out;
+}
+
 /** full path -> {mtimeMs, initiative, role, title} — re-read only what actually changed */
 const metaCache = new Map();
 
@@ -443,8 +522,10 @@ function walkMd(dir, acc) {
 }
 function initiativeIndex(root) {
   const proots = planningRoots(root);          // planning/ at the root OR nested (e.g. IDPF/pmos/planning)
-  if (!proots.length) return { initiatives: [], ungrouped: [] };
-  const metas = proots.flatMap((p) => walkMd(p, [])).map((f) => docMeta(root, f)).filter(Boolean);
+  const specimens = specimenMetas(root);       // prototype/<id>/ — outside planning/, grouped by dir
+  if (!proots.length && !specimens.length) return { initiatives: [], ungrouped: [] };
+  const metas = proots.flatMap((p) => walkMd(p, [])).map((f) => docMeta(root, f))
+    .filter(Boolean).concat(specimens);
   // 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.
@@ -573,22 +654,58 @@ function surfaceRoadmap(root, w) {
     .filter((g) => g.items.length);
   return { groups, note: 'dates are net-new state — grouped by status until a timeline is tracked' };
 }
+// The OKR surface reads through the SAME resolver as the ladder (spec R-6 / contract C-7). It used
+// to carry its own parser, and that parser matched objectives with /^#{1,3}\s+(O\d+)/ and KRs with
+// (KR\d+) — so `## O-INTEGRITY` and `KR-C` were invisible here while the ladder happily accepted
+// anchors naming them. One field with two opinions is the defect this initiative removes; a second
+// parser would have been the same bug wearing a different regex.
+function anchorLib() {
+  try { return require(path.join(__dirname, '..', 'scripts', 'anchor-resolve.js')); }
+  catch { return null; }
+}
 function surfaceOkr(root) {
-  const objectives = [];
-  for (const dir of findDirsNamed(root, 'okrs', BUNDLE_MAX_DEPTH)) {
-    for (const f of walkMd(dir, [])) {
-      let text = '';
-      try { text = fs.readFileSync(f, 'utf8'); } catch { continue; }
-      let cur = null;
-      for (const line of text.split('\n')) {
-        const o = line.match(/^#{1,3}\s+(O\d+)\s*[—–:-]?\s*(.+)$/);
-        if (o) { cur = { id: o[1], name: o[2].replace(/\*\*/g, '').trim().slice(0, 120), krs: [] }; objectives.push(cur); continue; }
-        const k = line.match(/^\s*[-*]\s*\*\*\s*(KR\d+)\s*[—–:-]?\s*(.+?)\*\*/);
-        if (k && cur) cur.krs.push({ id: k[1], name: k[2].trim().slice(0, 140), current: null, target: null, levers: null });
+  const A = anchorLib();
+  if (!A) {
+    return { objectives: [], unreadable: 'the anchor resolver (scripts/anchor-resolve.js) is not present in this install — the OKR surface cannot be derived here', note: null };
+  }
+  const index = A.parseOkrIndex(root);
+  // A read that FAILED is not a read that found nothing. It renders RED (D64 Track B); the calm
+  // empty state is reserved for a successful read of genuinely nothing.
+  if (!index.ok) return { objectives: [], unreadable: index.error || 'the OKR documents could not be read', note: null };
+
+  const objectives = index.objectives.map((o) => ({
+    id: o.token, key: o.id, name: (o.name || '').slice(0, 120), file: o.file,
+    krs: o.krs.map((k) => ({ id: k.token, key: k.id, name: (k.name || '').slice(0, 140), current: null, target: null, levers: null })),
+  }));
+
+  // 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 unresolvable = [];
+  let checked = 0, empty = 0;
+  for (const dir of findDirsNamed(root, 'initiatives', BUNDLE_MAX_DEPTH)) {
+    let files = [];
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')); } catch { continue; }
+    for (const f of files) {
+      let head = '';
+      try { head = fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 4096); } catch { continue; }
+      const m = /^parent_kr:[ \t]*(.*)$/m.exec(head);
+      if (!m) continue;
+      const r = A.resolveAnchor(m[1], index, budgets);
+      if (r.kind === 'empty') { empty++; continue; }
+      checked++;
+      if (r.status === 'unresolvable' || r.status === 'unknown') {
+        unresolvable.push({ initiative: f.replace(/\.md$/, ''), raw: String(m[1]).trim().slice(0, 80), reason: r.reason, status: r.status });
       }
     }
   }
-  return { objectives, note: 'KR current/target and the lever tree are net-new state — shown as "— not tracked"' };
+  return {
+    objectives,
+    unreadable: null,
+    anchor_health: { checked, empty, unresolvable },
+    note: 'KR current/target and the lever tree are net-new state — shown as "— not tracked"',
+  };
 }
 function surfaceReport(root, w) {
   const s = surfaceInitiatives(root, w);
@@ -1510,11 +1627,17 @@ const LAYOUT_MAX = 40_000;
 function layoutPath(w) { return w ? path.join(LAYOUT_DIR, w.id + '.json') : null; }
 // Always returns a usable document: an absent, empty, truncated or hand-mangled file yields the
 // four stock layouts rather than an error, because the alternative is a window the PM cannot use.
+// `stored` is the client's ONLY safe signal that R8's one-time migration should run. sanitize()
+// always yields the four stock layouts, so the response body alone cannot distinguish "this
+// workspace has never stored anything" from "I could not read what it stored" — and the client
+// answers those two cases very differently (one writes, one must not). A file that exists but is
+// corrupt still counts as stored: this workspace has been through the layout system, so replaying
+// the pre-feature localStorage over it would be a second loss, not a recovery.
 function readLayouts(w) {
   const f = layoutPath(w);
   let raw = null;
   if (f) { try { raw = fs.readFileSync(f, 'utf8'); } catch { raw = null; } }
-  return layoutModel.sanitize(raw);
+  return Object.assign(layoutModel.sanitize(raw), { stored: raw !== null });
 }
 function writeLayouts(w, doc) {
   const f = layoutPath(w);
@@ -1694,6 +1817,59 @@ function needsResult(w) {
   if (!items.length) return { ok: true, empty: true };
   return { ok: true, empty: false, data: { items } };
 }
+// R12 — the per-tree aggregate the collapsed sidebar rows need, and R10's honesty rule applied to
+// the count itself. It deliberately routes through needsResult(), the STRICT reader: readNeeds()
+// swallows a corrupt needs.json in a bare `catch {}`, so a broken queue rendered as a calm "nothing
+// pending" on the one chip the PM uses to decide whether to look. A row that cannot read its state
+// says so; it never reports zero. `error` and `count` are mutually exclusive by construction.
+function needsCountFor(w) {
+  // One unreadable tree must never take down the aggregate — a registered workspace whose root has
+  // been moved or deleted is ordinary, and a 500 here would blank the count for every OTHER tree.
+  // Caught defensively rather than trusted: needsResult reaches the filesystem through several
+  // helpers (needsFileFor → stateDirFor → deriveNeeds) and only some of them guard themselves.
+  let r;
+  try { r = needsResult(w); }
+  catch (e) { return { count: null, error: 'needs state unreadable: ' + String((e && e.code) || (e && e.message) || 'error').slice(0, 60) }; }
+  if (!r.ok) return { count: null, error: r.error };
+  return { count: r.empty ? 0 : r.data.items.length, error: null };
+}
+// The aggregate covers EVERY registered tree, and deriveNeeds() re-reads that tree's whole
+// initiative set (110 records on this repo) plus its jsonl state. Computing it per request, per
+// workspace, made /api/needs cost O(trees × records) in filesystem reads — enough to hang the
+// request and reset the connection. It is memoised with a short TTL, and the TTL is the honest
+// bound: this is the glance number on a COLLAPSED row, refreshed on the cadence the sidebar
+// repaints. The SELECTED tree's queue (`needs`) is never cached — the list the PM acts on stays
+// authoritative and is read fresh on every call.
+const NEEDS_AGG_TTL_MS = 4000;
+const needsAgg = new Map();     // ws id -> { at, sig, value }
+// The queue file's identity, so a change to it is never served from cache. A TTL alone was wrong in
+// exactly the case R10 exists for: corrupt the queue and the memo keeps answering with the count it
+// computed a moment earlier — a calm number over broken state, which is the failure this whole
+// requirement is about. `none` and `unreadable` are distinct signatures on purpose; a file that
+// appears, vanishes or becomes unstattable each invalidate.
+function needsSig(w) {
+  const f = needsFileFor(w);
+  if (!f) return 'none';
+  try { const st = fs.statSync(f); return `${st.mtimeMs}:${st.size}`; }
+  catch { return 'unreadable'; }
+}
+function needsCountCached(w) {
+  const hit = needsAgg.get(w.id);
+  const now = Date.now();
+  let sig;
+  try { sig = needsSig(w); } catch { sig = 'unreadable'; }
+  if (hit && hit.sig === sig && now - hit.at < NEEDS_AGG_TTL_MS) return hit.value;
+  const value = needsCountFor(w);
+  needsAgg.set(w.id, { at: now, sig, value });
+  return value;
+}
+function needsByWorkspace() {
+  const out = {};
+  for (const w of workspaces.values()) out[w.id] = needsCountCached(w);
+  return out;
+}
+// Anything that resolves or files a need makes the memo stale; drop it rather than wait out the TTL.
+function invalidateNeedsAgg(id) { if (id) needsAgg.delete(id); else needsAgg.clear(); }
 function buildConsole(name, w, root) {
   const stateDir = stateDirFor(w);
   const snapshotDir = latestSnapshotDir(root);
@@ -1702,7 +1878,12 @@ function buildConsole(name, w, root) {
   if (name === 'radar') return consoleState.radar({ stateDir, snapshotDir });
   // The workflow ladder reads the OPENED workspace's repo (records + git), not the state dir — an
   // initiative's position is a property of the repo it lives in, snapshot or no snapshot.
-  if (name === 'workflow') return consoleState.workflow({ root: w ? w.root : root });
+  // Through the cache, never the raw reader. The derivation shells git once per initiative —
+  // ~30s on this repo — and it is synchronous, so calling it here froze the server and every PTY
+  // socket with it for the whole half minute. boardCache returns immediately and derives in a
+  // child; the payload carries `as_of` / `stale` / `pending` so the client can say how old the
+  // answer is instead of implying it is current.
+  if (name === 'workflow') return boardCache.board(w ? w.root : root);
   return { ok: false, error: 'unknown console surface: ' + name };
 }
 
@@ -2122,7 +2303,7 @@ async function handleRequest(req, res) {
     const w = getWs(url.searchParams.get('ws'));
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
     const doc = readLayouts(w);
-    return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId });
+    return json(res, { ok: true, layouts: doc.layouts, currentId: doc.currentId, stored: doc.stored });
   }
   if (p === '/api/doc') {
     const w = getWs(url.searchParams.get('ws'));
@@ -2153,7 +2334,18 @@ async function handleRequest(req, res) {
       res.end(buf);
     });
   }
-  if (p === '/api/needs') return json(res, { needs: readNeeds(getWs(url.searchParams.get('ws'))) });
+  // `needs` stays the queue the strip renders. `state` is R10: whether that list is trustworthy or
+  // merely quiet — the strip must not draw a calm empty over a corrupt file. `by_ws` is R12: the
+  // per-tree counts a COLLAPSED sidebar row shows, which is the whole reason a row can be collapsed.
+  if (p === '/api/needs') {
+    const w = getWs(url.searchParams.get('ws'));
+    const strict = needsResult(w);
+    return json(res, {
+      needs: readNeeds(w),
+      state: strict.ok ? { ok: true } : { ok: false, error: strict.error },
+      by_ws: needsByWorkspace(),
+    });
+  }
   if (p === '/api/console') {
     // Read-only console surfaces (needs-you · radar · metrics) over file-mode state (D64 Track B).
     // Discriminated result: {ok:true,empty} genuinely nothing · {ok:false,error} a broken read the
@@ -2180,6 +2372,7 @@ async function handleRequest(req, res) {
   if (p === '/api/gate' && req.method === 'POST') {
     // The PMOS Acceptance/Review vocabulary in file mode (R5). NEVER automatic — this is
     // only reached by an explicit PM click, and it just records the decision.
+    invalidateNeedsAgg();     // a recorded decision changes the counts; do not wait out the TTL
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }