spexcode 0.1.5 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
 <img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
 
-> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
-> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
-> a tuxedo of stale ceremony.
+> Spec-driven development fails two ways: the spec drifts out of sync with the code, or it
+> bloats into stale ceremony. SpexCode keeps each spec short and current — rewritten in place,
+> versioned by git, never an accumulating changelog.
 
 **SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
 *spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
@@ -10,49 +10,109 @@ database**: a node's version is its count of content commits, and "drift" is gov
 ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
 separate store.
 
-There are two ways to meet SpexCode, and they are kept separate on purpose:
-
-- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
-- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
+- **[Using SpexCode](#using-spexcode)** — adopt the `spex` CLI and drive it through your coding agent to govern *your own* project.
+- **[Contributing to SpexCode](#contributing-to-spexcode)** — hack on the tool itself, in this repo.
+- **[Working with agents →](https://spexcode.net/working-with-agents/)** — the deeper narrative on the docs site, behind this landing.
 
 ---
 
 ## Using SpexCode
 
-You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
+You set SpexCode up once — `npm i -g spexcode` then `spex init` in your repo — and after that the primary
+way you use it is **by talking to your coding agent**. You describe what you want in plain language —
+*"add a spec node for the auth flow", "extract specs for this package", "dispatch a worker to implement
+Y"* — and the agent runs the `spex` CLI for you while you supervise on the board. The manual CLI below is
+the substrate; your agent is the daily interface.
+
+That works because a freshly-launched agent **already knows SpexCode**. `spex init` materializes the whole
+contract — the spec-node ritual, the commit-before-declare gate, the merge style — into a
+`<!-- spexcode -->` managed block in your repo's `CLAUDE.md`/`AGENTS.md`, which
+**[Claude Code](https://www.anthropic.com/claude-code)** and **Codex** **auto-discover** as always-on
+context (no `--append-system-prompt`, nothing to wire). From there the agent self-serves detail on demand
+from the built-in manual — `spex guide` (the workflow), `spex guide spec` / `spex guide yatsu` (the file
+formats), and `spex guide config` (every `spexcode.json` setting). You can literally say *"run `spex guide
+config` and set me up a launcher"* and it will.
+
+For the full narrative — the three pillars of driving SpexCode by talking to your agent (agent
+self-learning via the materialized block + `spex guide`, config, and the init artifacts) — see
+**[working with agents](https://spexcode.net/working-with-agents/)** on the docs site;
+**[getting started](https://spexcode.net/getting-started/)** walks the setup end to end. This README is
+the concise landing; the site goes deep.
+
+> **It's also just plain tooling.** Strip the agent away and the core is still useful on its own: **spec
+> files versioned by git**, checked by `spex lint` and shown on a read-only dashboard — no AI, and nothing
+> to run but Node and git. The vibe-coding path sits *on top* of that; it doesn't replace it.
+
+> **Requirements.** Core: **Node ≥ 22** and **git**. Driving SpexCode through an agent (or dispatching
+> workers onto your nodes) also needs **tmux** and an authenticated **Claude Code or Codex** on your PATH
+> — and those agents run commands on your machine, so read [`SECURITY.md`](./docs/SECURITY.md) before
+> exposing the backend.
+
+### Set it up
+
+Install the published CLI once, then adopt it in any project:
 
 ```sh
 npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
+cd ~/my-app
+spex init              # additive — never restructures your code
 ```
 
-Adopt it in your project — `spex init` is **additive**, it never restructures your code:
+`spex init` is additive: it seeds a starter **`.spec/`** tree (a root `project` node plus the `.config`
+plugins that define the dev flow), a starter **`spexcode.json`**, and the per-clone **git hooks** (a
+`pre-commit` hook that runs **spec-lint** — blocking on broken spec↔code links — and **main-guard**,
+which blocks direct commits to `main`, plus a `prepare-commit-msg` hook that stamps each commit's
+session attribution). It also **materializes** the harness artifacts that make the agent path
+work: the `<!-- spexcode -->` contract block in `CLAUDE.md`/`AGENTS.md`, and the `.claude/` / `.codex/`
+shims (the `settings.json` hooks) a self-launched agent discovers. Those artifacts are generated and
+gitignored — regenerated on each machine, never committed.
+
+Then make it yours — either ask your agent to, or do it by hand: edit `.spec/project/spec.md` to describe
+the project, point `spexcode.json`'s `lint.governedRoots` at your real source dir(s), and check the graph:
 
 ```sh
-cd ~/my-app
-spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
-# 1. edit .spec/project/spec.md to describe your project
-# 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
 spex lint              # the "coverage" warnings are your adoption TODO list
 ```
 
-Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
-side by side on one host (the cwd picks which project is served):
+### Configure it
+
+Two optional JSON files at the repo root hold every setting, split by portability — pick the right one and
+that's the whole discipline:
+
+- **`spexcode.json`** — *committed, portable*: layout, dashboard identity (`title` + `icon`), lint budgets,
+  and launcher **names**. Facts that are true for the project.
+- **`spexcode.local.json`** — *gitignored, host-specific*: absolute launcher command paths, cert/secret
+  paths, and the private-overlay switch (`private: true`, which makes `spex materialize` leave zero trace
+  in the tracked tree — ignores go to the local git exclude, not the committed `.gitignore` — so you can
+  run SpexCode on a repo you share but don't own). Facts that are true for one machine.
+
+There is no `spex config set` — you (or your agent) edit the files directly. **`spex guide config`** is the
+authoritative manual for every field and which of the two files it belongs in.
+
+### Run it
+
+Start the backend and the dashboard, then open the board:
 
 ```sh
-spex serve --port 8788                       # the backend (API + sessions) for THIS repo
-spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+spex serve          # the backend (API + sessions), on :8787
+spex dashboard      # the board UI on :5173, proxying /api to the backend
 ```
 
-Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
-to `:5173`.
+Open <http://localhost:5173>.
 
-Day to day:
+Both ports are flags (`spex serve --port 8788`, `spex dashboard --port 5174 --api-port 8788`), so you can
+run several projects' boards side by side — the working directory picks which project each serves. Give
+each tab its own identity in that project's `spexcode.json`: `dashboard.title` names it and
+`dashboard.icon` sets the favicon — an emoji (`"🔭"`), an Iconify name (`"mdi:rocket-launch"`), or a URL,
+nothing to download.
+
+Day to day (the commands your agent runs for you — and that you can run yourself):
 
 | command | what it does |
 | --- | --- |
 | `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
 | `spex watch` | stream session / board transitions as they happen |
-| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
+| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` / `config` manuals |
 | `spex board` | dump the current board state as JSON |
 
 The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
@@ -80,7 +140,8 @@ npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
 npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
 ```
 
-The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
-`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
-merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
-out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.
+---
+
+## License
+
+[MIT](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",
@@ -24,12 +24,11 @@
     "node": ">=22"
   },
   "scripts": {
-    "api": "npm --prefix spec-cli run serve",
-    "web": "npm --prefix spec-dashboard run dev",
-    "lint": "npm --prefix spec-cli run -s lint",
-    "seed": "bash scripts/seed-spec-history.sh",
+    "api": "cd spec-cli && npm run serve",
+    "web": "cd spec-dashboard && npm run dev",
+    "lint": "cd spec-cli && npm run -s lint",
     "hooks": "bash scripts/install-hooks.sh",
-    "prepublishOnly": "node scripts/prepublish.mjs",
+    "prepack": "node scripts/prepack.mjs",
     "postinstall": "node -e \"try{require('fs').readdirSync('node_modules/node-pty/prebuilds').forEach(d=>{try{require('fs').chmodSync('node_modules/node-pty/prebuilds/'+d+'/spawn-helper',0o755)}catch{}})}catch{}\""
   },
   "dependencies": {

package/spec-cli/README.md

@@ -0,0 +1,86 @@
+<img src="docs/sdd-tuxedo-pooh.png" alt="Writing code vs. authoring a living, executable specification artifact" width="420">
+
+> Spec-driven development gets wrecked by spec drift and spec bloat. SpexCode's bet
+> is to keep the spec the cheap, honest twin of the code — rewritten in place, never
+> a tuxedo of stale ceremony.
+
+**SpexCode** is a spec-driven, self-developing dev tool. Every part of a project becomes a versioned
+*spec node* — a `.spec/**/spec.md` whose body states the part's *present* intent — and **git is the
+database**: a node's version is its count of content commits, and "drift" is governed code that moved
+ahead of its spec. A `spex` CLI plus a live dashboard read all of it straight from git; there is no
+separate store.
+
+There are two ways to meet SpexCode, and they are kept separate on purpose:
+
+- **[Using SpexCode](#using-spexcode)** — install the `spex` CLI from npm and govern *your own* project.
+- **[Contributing to SpexCode](#contributing-to-spexcode)** — develop the tool itself, in this repo.
+
+---
+
+## Using SpexCode
+
+You don't clone this repo to *use* SpexCode. Install the published CLI once, then point it at any project.
+
+```sh
+npm i -g spexcode      # installs the `spex` command (needs Node ≥ 22)
+```
+
+Adopt it in your project — `spex init` is **additive**, it never restructures your code:
+
+```sh
+cd ~/my-app
+spex init              # seed .spec/, a starter spexcode.json, and git hooks — nothing destructive
+# 1. edit .spec/project/spec.md to describe your project
+# 2. point spexcode.json's  lint.governedRoots  at your real source dir(s)
+spex lint              # the "coverage" warnings are your adoption TODO list
+```
+
+Run it. The backend and the dashboard are **two commands on two ports**, so several projects can run
+side by side on one host (the cwd picks which project is served):
+
+```sh
+spex serve --port 8788                       # the backend (API + sessions) for THIS repo
+spex dashboard --port 5174 --api-port 8788   # the board UI, pointed at that backend
+```
+
+Then open <http://localhost:5174>. With no flags, `spex serve` defaults to `:8787` and `spex dashboard`
+to `:5173`.
+
+Day to day:
+
+| command | what it does |
+| --- | --- |
+| `spex lint` | check the spec↔code graph — coverage, drift, and the living-body rules |
+| `spex watch` | stream session / board transitions as they happen |
+| `spex guide` | print the full workflow, plus the `spec.md` / `yatsu.md` file-format manuals |
+| `spex board` | dump the current board state as JSON |
+
+The spec tree is ground truth and git is its database: every change is a `spec.md` node, **rewritten in
+place** (never a `## vN` changelog) and versioned by its commits.
+
+---
+
+## Contributing to SpexCode
+
+This repository *is* the SpexCode source, and it **dogfoods itself**: every change to the tool lands as a
+spec node merged into `main`. Set up a checkout:
+
+```sh
+git clone https://github.com/shuxueshuxue/spexcode && cd spexcode
+npm --prefix spec-cli install
+npm --prefix spec-dashboard install
+npm run hooks          # install the per-clone git hooks (main-guard + the session-stamp hook)
+```
+
+The development loop runs from source, with hot-reload — this is what `npm run web` is for, as opposed
+to an installed user's `spex dashboard`:
+
+```sh
+npm run api            # backend on :8787, hot-reloads on spec-cli/src changes
+npm run web            # the dashboard via Vite (HMR), proxying /api → :8787
+```
+
+The contribution ritual in one breath: branch `node/<id>` off `main`, make the code change **and** its
+`spec.md` *together*, commit, then `spex session done --propose merge` — a human performs the `--no-ff`
+merge. That ritual, the spec-node model, the lint rules, and the reflexive config system are all spelled
+out in **[`CLAUDE.md`](./CLAUDE.md)** — read it before your first change.

package/spec-cli/bin/spex.mjs

@@ -3,6 +3,7 @@
 // run the TypeScript CLI directly. After `npm link` (or a global install) `spex lint` works anywhere.
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 
@@ -11,9 +12,20 @@ import { dirname, join } from 'node:path'
 // `spex` work from any cwd (agents, git hooks) against this package's code, operating on the cwd.
 const pkg = join(dirname(fileURLToPath(import.meta.url)), '..') // spec-cli/
 const cli = join(pkg, 'src', 'cli.ts')
-// tsx lives in spec-cli/node_modules in the dev monorepo, but at the PUBLISHED package root's
-// node_modules (one level up: spec-cli is a subdir of the `spexcode` tarball) when installed. Try both.
+// tsx lives in spec-cli/node_modules in the dev monorepo, but npm may hoist it above the installed
+// `spexcode` package in a real consumer project. Try local candidates first, then let Node resolve upward
+// from spec-cli so project-local and global installs work the same way.
 const tsxCandidates = [join(pkg, 'node_modules', '.bin', 'tsx'), join(pkg, '..', 'node_modules', '.bin', 'tsx')]
-const tsx = tsxCandidates.find(existsSync) ?? tsxCandidates[0]
+function resolveTsx() {
+  const local = tsxCandidates.find(existsSync)
+  if (local) return local
+  try {
+    const req = createRequire(join(pkg, 'package.json'))
+    return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
+  } catch {
+    return tsxCandidates[0]
+  }
+}
+const tsx = resolveTsx()
 spawn(tsx, [cli, ...process.argv.slice(2)], { stdio: 'inherit' })
   .on('exit', (code) => process.exit(code ?? 0))

package/spec-cli/hooks/dispatch.sh

@@ -17,10 +17,12 @@
 #       the harness propagates. Pure bash, no node boot on the hot path (node runs only inside the gate, only
 #       on actual change). cwd = the project/worktree. $SPEX (abs tsx+cli) is inherited from the shim env.
 set -u
-# args: `<harness> <Event>`. A harness id as $1 (claude|codex) is consumed; otherwise we keep $1 as the event
-# and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# args: `<harness> <Event>`. A harness id as $1 (claude|codex|plugin) is consumed; otherwise we keep $1 as the
+# event and default the harness to claude — so a stale shim still rendered as `dispatch.sh <Event>` keeps working.
+# `plugin` is the bundle form ([[plugin-harness]]): it parses payloads as the claude family in harness.sh (z-code/
+# Claude share Claude's tool names + file_path), so it joins the claude branch there via the default case.
 harness=claude
-case "${1:-}" in claude|codex) harness="$1"; shift ;; esac
+case "${1:-}" in claude|codex|plugin) harness="$1"; shift ;; esac
 event="${1:?usage: dispatch.sh <harness> <Event>}"
 export SPEXCODE_HARNESS="$harness"
 # the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we
@@ -38,11 +40,21 @@ rt="$(cd "$proj" 2>/dev/null && hp_runtime_dir)" || rt=""
 cur="$( (cd "$proj" 2>/dev/null && hp_config_hash) )"
 if [ -n "$rt" ] && [ -n "$cur" ] && [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then
   mkdir -p "$rt" 2>/dev/null
-  ( flock 9
-    if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
-      ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
-    fi
-  ) 9>"$rt/.materialize.lock"
+  # POSIX-portable mutex: mkdir is atomic on every POSIX fs, so it serializes the render with NO dependency on
+  # util-linux `flock` (absent on macOS — where it silently no-op'd, letting concurrent sessions race the write).
+  # Spin on `mkdir` with a bounded wait; after ~10s (200 * 0.05s, well above the ~0.85s materialize) treat the
+  # dir as orphaned by a dead entrant and clear it, so a stale lock can never deadlock a launch. Held only across
+  # the re-check + render, released right after.
+  lockd="$rt/.materialize.lock.d"
+  _lk=0
+  until mkdir "$lockd" 2>/dev/null; do
+    _lk=$((_lk+1)); [ "$_lk" -ge 200 ] && { rm -rf "$lockd" 2>/dev/null; _lk=0; }
+    sleep 0.05
+  done
+  if [ "$cur" != "$(cat "$rt/content-hash" 2>/dev/null || true)" ]; then   # re-check: a sibling dispatch may have just rendered
+    ( cd "$proj" && ${SPEX:-spex} materialize >/dev/null 2>&1 )
+  fi
+  rmdir "$lockd" 2>/dev/null
 fi
 
 # --- (2) dispatch ---------------------------------------------------------------------------------------

package/spec-cli/hooks/harness.sh

@@ -6,6 +6,9 @@
 # HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
 # shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
 # lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
+# SPEXCODE_HARNESS is claude|codex|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its host (z-code/
+# Claude) shares Claude's payload shape, so every `case "$SPEXCODE_HARNESS"` below routes it through the claude
+# branch via the default case — there is no separate `plugin)` arm to maintain.
 
 # the string value of a top-level JSON string field (first match). Harness-agnostic — both harnesses' payloads
 # carry session_id / tool_name as plain string fields. $1 = payload, $2 = field name. The value is scanned as a
@@ -54,13 +57,16 @@ hp_field() {
 }
 
 # the session id from a payload (both harnesses use session_id).
-# the GOVERNED record id the launcher baked into the session env (SPEXCODE_SESSION_ID) wins over the harness's
-# own payload session_id. This is what lets a dashboard-launched CODEX session feed its governed record: codex
-# mints its OWN thread id (un-pinnable), so the record can't be keyed by it — instead the launcher keys the
-# record by a SpexCode id and exports it into the launch, and every hook resolves THAT. Claude's payload id is
-# already the record id, so the env (= same value) is a harmless no-op there. A self-launched agent sets no
-# env → falls back to the payload session_id (its own non-governed record). One resolver, both harnesses.
-hp_session_id() { printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}"; }
+# Codex hooks run inside ONE shared per-project app-server. That process can inherit the FIRST launched
+# session's SPEXCODE_SESSION_ID, so on codex the payload session_id (the acting thread id) must win and then
+# hp_store_dir aliases it to the governed record. Claude's payload id already equals its governed record id,
+# so preferring SPEXCODE_SESSION_ID there preserves the launcher's pinned id path.
+hp_session_id() {
+  case "$SPEXCODE_HARNESS" in
+    codex) hp_field "$1" session_id ;;
+    *)     printf '%s' "${SPEXCODE_SESSION_ID:-$(hp_field "$1" session_id)}" ;;
+  esac
+}
 
 # the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
@@ -75,10 +81,11 @@ hp_runtime_dir() {
 
 # the per-session GLOBAL store dir for a session id — <runtime>/sessions/<id> (sibling of the per-project
 # runtime above). Echoes the dir; returns non-zero (echoing nothing) when git can't resolve.
-# ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env carries NO
-# SPEXCODE_SESSION_ID, so hp_session_id falls back to the payload session_id = the codex THREAD id — NOT the
-# SpexCode record id the dir is keyed by. So when no record sits at <id> directly, find the one record that
-# captured this id as `harness_session_id` (the backend stored it at thread/start, before the first tool turn).
+# ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env may carry a
+# stale SPEXCODE_SESSION_ID from the first launched codex session. hp_session_id therefore returns the acting
+# payload session_id on codex: the codex THREAD id, NOT the SpexCode record id the dir is keyed by. So when no
+# record sits at <id> directly, find the one record that captured this id as `harness_session_id` (the backend
+# stored it at thread/start, before the first tool turn).
 # A grep over the few session.json files — no jq on the hot path; the trailing quote anchors the value so a
 # thread id can't match a longer one as a prefix. Direct hit wins; a miss with no alias echoes the direct path
 # unchanged, so the caller's `[ -e "$rec" ]` still no-ops gracefully. Mirrors layout.ts `readAliasedRawRecord`.

package/spec-cli/src/board.ts

@@ -3,8 +3,10 @@ import { loadSpecs, deriveStatus } from './specs.js'
 import { resolveLayout, readConfig } from './layout.js'
 import { listSessions } from './sessions.js'
 import { repoRoot, driftIndex, historyIndex } from './git.js'
-import { residentForgeView } from '../../spec-forge/src/resident.js'
+import { residentForgeState } from '../../spec-forge/src/resident.js'
+import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-yatsu/src/evaltab.js'
+import { yatsuNodesAsync } from '../../spec-yatsu/src/yatsu.js'
 
 // a ghost (added) node's parent: the existing node whose directory is the longest prefix of the new one.
 function resolveParent(path: string, byDir: Record<string, string>): string | null {
@@ -17,6 +19,22 @@ function resolveParent(path: string, byDir: Record<string, string>): string | nu
   return null
 }
 
+// the board's eval summary ([[board-lean]]): the LATEST reading per scenario, each kept as the VERBATIM
+// reading object — a filter, never a projection. Consumers hang optional fields off a reading (the
+// annotator's timelineBlob rides only video readings), so dropping a field here is a SILENT downstream
+// degradation no error would surface; the field-preservation unit test pins this contract.
+export function latestPerScenario<T extends { scenario: string }>(readings: T[]): T[] {
+  const seen = new Set<string>()
+  return readings.filter((r) => !seen.has(r.scenario) && (seen.add(r.scenario), true))
+}
+
+// the board's scenario fold ([[board-lean]]): the declared set rides SLIM — {name, tags} is everything an
+// overview surface joins state onto (badge, stats, focus rows, search rows); the prose (description/
+// expected) and per-scenario code stay off the hot poll, carried by `/api/specs/lite` and `/api/specs/:id/evals`.
+export function slimScenarios(scenarios: { name: string; tags?: string[] }[]): { name: string; tags?: string[] }[] {
+  return scenarios.map((s) => ({ name: s.name, ...(s.tags?.length ? { tags: s.tags } : {}) }))
+}
+
 export async function buildBoard() {
   // all three sources are warm-cheap and independent, so the board inherits their speed for free: loadSpecs
   // REUSES the HEAD-keyed spec-history cache (the git-derived node data — see specs.ts/git.ts), resolveLayout
@@ -77,35 +95,46 @@ export async function buildBoard() {
   const nodes = [
     ...specs.map((n: any) => {
       const overlays = overlaysByNode[n.id] || []
-      return { ...n, overlays, status: deriveStatus({ version: n.version, drift: n.drift, hasOverlay: overlays.length > 0, hasCode: (n.code?.length ?? 0) > 0, fmStatus: n.fmStatus ?? undefined }) }
+      // `body` and its derivation `parts` are DROPPED from the board payload ([[board-lean]]): together ~56% of
+      // the bytes, and detail the graph overview never renders. The detail view fetches them per node from
+      // `/api/specs/:id/content` on open, and the search palette fetches the body corpus from `/api/specs/lite`
+      // once on open — both off this hot poll. `undefined` makes JSON.stringify omit the keys.
+      return { ...n, body: undefined, parts: undefined, overlays, status: deriveStatus({ version: n.version, drift: n.drift, hasOverlay: overlays.length > 0, hasCode: (n.code?.length ?? 0) > 0, fmStatus: n.fmStatus ?? undefined }) }
     }),
     ...Object.values(ghostById),
   ]
-  // fold spec-forge issues onto each node (full set → issues, open subset → openIssues, attached only when
-  // non-empty), non-blocking: residentForgeView never waits on `gh` and returns [] absent a forge, so a
-  // forge-less board is unchanged. Sorted open-first, newest number first.
-  const isOpen = (i: any) => (i.state || '').toLowerCase() === 'open'
-  const issuesByNode: Record<string, any[]> = {}
-  for (const link of residentForgeView(nodes.map((n) => n.id))) {
-    issuesByNode[link.node] = link.issues
-      .map((i) => ({ number: i.number, state: i.state, title: i.title, url: i.url }))
-      .sort((a, b) => Number(isOpen(b)) - Number(isOpen(a)) || b.number - a.number)
-  }
+  // fold each node's issues onto it through the unified Issue port ([[issues]]): the resident forge slice
+  // AND the local store's threads, one merged store-tagged list (full set → issues, open subset →
+  // openIssues, attached only when non-empty). Non-blocking: residentForgeState never waits on `gh` and is
+  // empty absent a forge, so the fold then carries the local slice alone. Sorted open-first, newest first.
+  const isOpen = (i: { status: string }) => i.status === 'open'
+  const issuesByNode: Record<string, ReturnType<typeof mergedIssues>> = {}
+  for (const issue of mergedIssues({ host: 'github', state: residentForgeState() }, nodes.map((n) => n.id)))
+    for (const nid of issue.nodes) (issuesByNode[nid] ??= []).push(issue)
   for (const n of nodes) {
     const issues = issuesByNode[n.id]
     if (!issues || !issues.length) continue
     n.issues = issues
-    const open = issues.filter(isOpen)
+      .sort((a, b) => Number(isOpen(b)) - Number(isOpen(a)) || b.created.localeCompare(a.created))
+      .map((i) => ({ id: i.id, store: i.store, status: i.status, concern: i.concern, url: i.url }))
+    const open = n.issues.filter(isOpen)
     if (open.length) n.openIssues = open
   }
 
-  // fold each yatsu node's eval timeline onto it, riding this one board poll: `evals` (readings, newest-first)
-  // and `scenarios` (the declared set) attached only when the node declares scenarios. evalContext reuses the
-  // specs + driftIndex above; evalTimeline short-circuits non-yatsu nodes so the poll stays fast.
-  const ectx = evalContext(root, specs, idx, hidx)
+  // fold each yatsu node's eval state onto it — as the LEAN summary ([[board-lean]]): `evals` carries only
+  // the LATEST reading per scenario (newest-first), which is all any overview surface consumes (the score
+  // badge, stats, search all reduce to latest-per-scenario anyway); the full timeline stays off the board
+  // and is lazy-loaded by the eval tab from `/api/specs/:id/evals`. `scenarios` (the declared set) rides
+  // SLIM — {name, tags} only, the fields every overview surface joins state onto — with its prose
+  // (description/expected) and per-scenario code off the hot poll: they ride the `/api/specs/lite` corpus
+  // (search palette, focus-panel preview) and the `/api/specs/:id/evals` timeline (eval tab).
+  // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-yatsu nodes. The
+  // yatsu walk rides fs/promises ([[board-cache]]) so it yields the event loop instead of stalling /health.
+  const ynodes = await yatsuNodesAsync(root)
+  const ectx = await evalContext(root, specs, idx, hidx, undefined, ynodes)
   await Promise.all(nodes.map(async (n) => {
     const tl = await evalTimeline(n.id, ectx)
-    if (tl.hasYatsu) { n.evals = tl.readings; n.scenarios = tl.scenarios }
+    if (tl.hasYatsu) { n.evals = latestPerScenario(tl.readings); n.scenarios = slimScenarios(tl.scenarios) }
   }))
 
   const opsByPath: Record<string, any[]> = {}

package/spec-cli/src/boardCache.ts

@@ -0,0 +1,70 @@
+import { buildBoard } from './board.js'
+
+// @@@ board-cache — single-flight + cache for the hot /api/board build ([[board-lean]]). Assembling the
+// board is expensive (two full-history git-log walks cold, a full `.spec` fs walk every build), so the
+// route MUST NOT rebuild per request: index.ts once ran `buildBoard()` inline on EVERY poll, so a normal
+// dashboard's overlapping polls (+ SSE-triggered refetches) multiplied into N simultaneous builds and
+// starved the event loop — one real user could wedge the backend. Here ONE build is shared by all
+// concurrent callers (a promise memo — this IS the max-concurrent-builds cap: at most one runs) and its
+// result is cached until a REAL change invalidates it. The cache is invalidated by the SAME freshness
+// signals [[board-stream]] already watches (session-store writes, git-ref moves, the cold tick), via
+// invalidateBoard(). So a poll storm costs ONE build, a quiet stretch costs ZERO, and the SSE rebuild and
+// the route share the very same in-flight build.
+
+export type Board = Awaited<ReturnType<typeof buildBoard>>
+
+// a build slower than this is LOGGED, never silently tolerated — the fail-loud regression alarm. Sized
+// above a warm build (~sub-second once the fs walks yield) but below the cold two-walk first build, so a
+// genuinely-degraded hot path shouts while an ordinary cold start stays quiet-ish.
+const BUDGET_MS = Number(process.env.SPEXCODE_BOARD_BUDGET_MS || 1500)
+
+let cached: Board | null = null   // last completed build; served while `valid`
+let cachedJson: string | null = null   // JSON.stringify(cached), serialized ONCE per build (see getBoardJson)
+let valid = false
+let inflight: Promise<Board> | null = null
+let gen = 0                       // bumped on every invalidation — detects a change that landed MID-build
+
+// mark the cache stale. Called by every board-stream freshness source (see boardStream.fireChanged), so a
+// real change forces the next getBoard() to rebuild while a quiet poll storm keeps hitting the cache.
+export function invalidateBoard(): void {
+  gen++
+  valid = false
+}
+
+// the coalesced board read the route and the SSE rebuild both go through. A concurrent caller during a
+// build shares the in-flight promise; a caller after a completed build gets the cached value until the
+// next invalidation. A change that lands WHILE a build runs (gen moved) leaves the cache invalid so the
+// NEXT read rebuilds — the just-finished build still returns to its waiters (freshest available when they
+// asked), never cached as current. Mirrors [[board-stream]]'s building/dirty loop.
+export function getBoard(): Promise<Board> {
+  if (inflight) return inflight
+  if (valid && cached) return Promise.resolve(cached)
+  const startGen = gen
+  const p = (async () => {
+    const t0 = Date.now()
+    try {
+      const board = await buildBoard()
+      cached = board
+      cachedJson = null   // invalidate the memoized serialization; re-serialized lazily on first read
+      valid = gen === startGen
+      return board
+    } finally {
+      const ms = Date.now() - t0
+      if (ms > BUDGET_MS) console.warn(`spec-cli: /api/board build took ${ms}ms (budget ${BUDGET_MS}ms) — hot path is slow`)
+      inflight = null
+    }
+  })()
+  inflight = p
+  return p
+}
+
+// the SERIALIZED board for the /api/board route — JSON.stringify runs ONCE per build, not once per poll,
+// so a poll storm of cache hits costs zero serialization CPU (only the etag hash for the 304 path). The SSE
+// path still takes the object (getBoard) because it decomposes it into delta units ([[board-delta]]).
+export async function getBoardJson(): Promise<string> {
+  const board = await getBoard()
+  if (board === cached && cachedJson !== null) return cachedJson
+  const json = JSON.stringify(board)
+  if (board === cached) cachedJson = json   // memoize only the CURRENT build's serialization
+  return json
+}