spexcode 0.2.8 → 0.3.0

package/spec-cli/src/guide.ts

@@ -10,7 +10,8 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    the \`spexcode\` package itself, never the internal @spexcode/spec-cli. Both paths own the same
    \`spex\` bin, so uninstall one before switching (\`npm rm -g spexcode\`; a legacy link of the
    inner package uninstalls as \`@spexcode/spec-cli\`). A source link ships no
-   prebuilt dashboard dist — \`spex dashboard\` needs a manual dashboard build, or use the dev server.)
+   prebuilt dashboard dist — \`spex serve ui\` builds it once on first run (needs spec-dashboard's
+   npm deps installed), or use the dev server.)
 
 2. Adopt a repo
      cd <your-repo> && spex init                 # seeds .spec/ + git hooks (additive, never overwrites)
@@ -18,13 +19,13 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    (each a dir with a spec.md + a \`code:\` list of the files it governs).
 
 3. Run the backend — it reads .spec + git from the cwd repo
-     spex serve                                  # http://localhost:8787  (PORT=<n> for another endpoint)
-   Serve a different repo by running it from there; two repos at once = two \`spex serve\` on two PORTs.
+     spex serve                                  # http://localhost:8787  (--port <n> for another endpoint)
+   Serve a different repo by running it from there; two repos at once = two \`spex serve\` on two ports.
 
-4. Open the dashboard — the SAME board for every project, pointed per project
-     spex dashboard                              # serves the bundled board on :5173, proxying /api
+4. Open the dashboard — the SAME dashboard for every project, pointed per project
+     spex serve ui                              # serves the bundled dashboard on :5173, proxying /api
    Point it at another backend with --api-port (pairs with \`spex serve --port\`); one dashboard per
-   project. The board is a viewer — which backend it proxies is the only "which project" knob.
+   project. The dashboard is a viewer — which backend it proxies is the only "which project" knob.
    Loopback-only by default: viewing from another machine needs \`--host 0.0.0.0\` (or a specific
    interface) — still plain HTTP with no gate, so bind wide only on a LAN/tailnet you trust (for
    the internet, use \`spex serve --public\` instead).
@@ -33,12 +34,12 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
 
 5. Govern your layout (optional)
      spexcode.json sets lint's governedRoots/sourceExtensions and any non-default worktree layout.
-     \`spex lint\` must report 0 errors; coverage warnings are your adoption TODO (files no node claims yet).
+     \`spex spec lint\` must report 0 errors; coverage warnings are your adoption TODO (files no node claims yet).
 
 Look these up on demand — the formats an agent authors, and the settings it configures:
   spex guide spec       the spec.md format (frontmatter + body + the rules lint enforces)
-  spex guide yatsu      the yatsu.md format (scenario schema + how loss is measured and filed)
-  spex guide config     the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, lint
+  spex guide eval       the eval.md format (scenario schema + how loss is measured and filed)
+  spex guide settings   the spexcode.json / spexcode.local.json settings (launchers, dashboard icon, lint
                         budgets, layout) — every field, and which of the two files it belongs in
   spex guide footprint  the footprint model — what SpexCode plants in a repo, and who sees it
                         (committed | ignored | hidden), and every migration recipe`
@@ -47,26 +48,30 @@ const SPEC = `spex guide spec — the spec.md file format
 
 A spec node is a DIRECTORY under .spec/<project>/…/<id>/ holding a spec.md. The node's id is its leaf dir
 name when that is globally unique, else the shortest parent-qualified path-suffix that disambiguates (so ids
-are unique by construction) — the same id \`spex board\`, \`ack\`, and a node/<id> branch use. A spec states a node's PRESENT
+are unique by construction) — the same id \`spex graph\`, \`spec ack\`, and a node/<id> branch use. A spec states a node's PRESENT
 intent at CONTRACT altitude — what it guarantees and why — and is rewritten in place as intent changes;
 version history is git's job, never a changelog in the body.
 
 FRONTMATTER (YAML between the opening and closing --- lines; every field optional, sensible defaults):
   title    display name. Defaults to the dir id.
-  desc     one-line summary shown on the board.
-  hue      board colour, 0–360. Default 210.
+  desc     one-line summary shown on the graph.
+  hue      node colour on the graph, 0–360. Default 210.
   status   pending | active | merged | drift. Usually DERIVED from git state — rarely hand-set.
-  code:    files this node GOVERNS (is source of truth for) — ideally ONE, a YAML list of repo-relative
-           paths/dirs/*-globs. Drives drift + yatsu. Many nodes MAY govern the same file (ordinary
+  code:    the file this node GOVERNS (is source of truth for) — a YAML list, but AT MOST ONE entry
+           (the \`one-govern\` lint error otherwise: keep the true subject, move the rest to related:).
+           Drives drift + eval freshness. Many nodes MAY govern the same file (ordinary
            composition); a file governed by > maxOwners nodes warns (the \`owners\` rule — split it). Omit
            for a pure-prose node: a cross-cutting contract no file owns.
   related: files this node REFERENCES but does not own — a YAML list, same path forms. Carries coverage
-           (never drift, never yatsu, nothing to ack); it is the many-to-many net that claims the files
+           (never drift, never eval freshness, nothing to ack); it is the many-to-many net that claims the files
            govern doesn't. Every listed path must exist (lint integrity error otherwise).
-  surface  config/.config nodes only: system (folded into every agent's prompt) | command (a /command) |
-           hook (a lifecycle hook handler — a co-located script the dispatcher runs on the harness events
-           in events:, ordered by order:, blocking when block: true). hook nodes may nest under a grouping
-           plugin (e.g. .config/core/<id>); surface is a field, discovered recursively.
+  surface  plugin-system/.plugins nodes only: one or MORE of system (folded into every agent's prompt) |
+           command (a /command) | skill (an on-demand SKILL.md the harness loads when a task matches the
+           node's desc) | agent (a spawnable sub-agent definition; its \`tools:\` list is the spawned
+           agent's tool allowlist) | hook (a lifecycle hook handler — a co-located script the dispatcher
+           runs on the harness events in events:, ordered by order:, blocking when block: true).
+           Comma-list several to plug into each. hook nodes may nest under a grouping
+           plugin (e.g. .plugins/core/<id>); surface is a field, discovered recursively.
   events   hook surface only: harness lifecycle events this node binds (YAML list — PreToolUse, Stop, …).
   order    hook surface only: integer; the dispatcher runs same-event hooks low to high.
   block    hook surface only: true if the hook may block its event (honored only on block-capable events).
@@ -75,31 +80,41 @@ BODY (Markdown after the frontmatter): the contract — intent, invariants, outw
 code does it. Two optional level-2 headings split ground truth from detail:
   ## raw source      human-authored, rarely-changed intent — the loss function's target.
   ## expanded spec   agent-authored detail that must keep serving the raw source.
-Bodies without those headings are read whole. Link sibling nodes with [[node-id]] (a dangling link is
-fine — it marks a node worth writing).
-
-WHAT lint CHECKS (spex lint; the pre-commit hook gates on errors):
-  integrity (error)  every code: path exists.
-  living    (error)  no "## vN" changelog headings — the body is current-state.
-  altitude  (warn)   the body stays high-altitude: line/char budgets (~50 lines / 4200 chars), low
-                     code-identifier density, no step-by-step phrasing. Over budget = rewrite higher.
-  coverage  (warn)   every source file is claimed by ≥1 node — via code: OR related: (related is the net).
-  drift     (warn)   a governed file has commits newer than the node's spec version — it may be stale.
-                     Remedy: edit the spec to the new intent (re-versions the node), OR \`spex ack <node>
-                     --reason "…"\` when only mechanics changed and the contract still holds.
-  owners    (warn)   a file governed by > maxOwners nodes (default 3) does too much — SPLIT it so each
-                     governor owns its own module (or merge the nodes, or give it one foundation owner).
-
-LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex lint\` must reach 0 errors
-before merge. \`spex init\` seeds the first tree; \`spex guide yatsu\` covers the sibling loss-signal file.`
-
-const YATSU = `spex guide yatsu — the yatsu.md file format
-
-A yatsu.md sits BESIDE a node's spec.md and says how to MEASURE the node's loss — the gap between live
+Bodies without those headings are read whole. Link sibling nodes with [[node-id]] — every link must name
+a REAL node (lint's mention rule; backtick a placeholder like \`[[node]]\` so it reads as sample text).
+
+WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
+  integrity  (error)  every code:/related: path exists.
+  one-govern (error)  a node governs (code:) at most ONE file — keep the true subject, move the rest
+                      to related:.
+  living     (error)  no "## vN" changelog headings — the body is current-state.
+  id-format  (error)  each id char is ascii [a-z0-9-] or a non-ascii unicode letter/number (CJK ok; one
+                      optional leading dot; no space / '/' / '_' / uppercase Latin), and its leaf dir name
+                      is unique tree-wide.
+  mention    (error)  every [[node-id]] in prose names a real node (fenced/backticked samples exempt).
+  altitude   (warn)   the body stays high-altitude: line/char budgets (~50 lines / 4200 chars), low
+                      code-identifier density, no step-by-step phrasing. Over budget = rewrite higher.
+  breadth    (warn)   a node with >= maxChildren direct children (default 8) — altitude's structural
+                      twin; is an intermediate grouping layer missing?
+  coverage   (warn)   every source file is claimed by ≥1 node — via code: OR related: (related is the net).
+  drift      (warn)   a governed file has commits newer than the node's spec version — it may be stale.
+                      Remedy: edit the spec to the new intent (re-versions the node), OR \`spex spec ack <node>
+                      --reason "…"\` when only mechanics changed and the contract still holds.
+  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never blocks.
+  owners     (warn)   a file governed by > maxOwners nodes (default 3) does too much — SPLIT it so each
+                      governor owns its own module (or merge the nodes, or give it one foundation owner).
+  confusable-id (warn) two leaf ids one edit apart read as the same word — rename one to read apart.
+
+LIFECYCLE: author each node on a node/<id> branch, one node per commit; \`spex spec lint\` must reach 0 errors
+before merge. \`spex init\` seeds the first tree; \`spex guide eval\` covers the sibling eval.md, the measurement file.`
+
+const EVAL = `spex guide eval — the eval.md file format
+
+An eval.md sits BESIDE a node's spec.md and says how to MEASURE the node's loss — the gap between live
 behaviour and the spec. It is optional, but a node that governs SOURCE code (its code: includes a file whose extension is in
-\`lint.sourceExtensions\` — default .ts/.tsx/.js/.jsx, set it for a Rust/Go/Python tree) with no yatsu.md is
-a blind spot: \`spex yatsu scan\` flags it \`yatsu-uncovered\`. yatsu defines no DSL and RUNS NOTHING — the
-agent measures; yatsu keeps score.
+\`lint.sourceExtensions\` — default .ts/.tsx/.js/.jsx, set it for a Rust/Go/Python tree) with no eval.md is
+a blind spot: \`spex eval lint\` flags it \`eval-coverage\`. The eval system defines no DSL and RUNS
+NOTHING — the agent measures; eval keeps score.
 
 FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each scenario:
   name         REQUIRED. Unique within the file — it keys the sidecar and \`--scenario <name>\`.
@@ -111,28 +126,29 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
                use an existing one, or add it to the library to mint it. Tags classify a scenario (surface,
                device) so it can be filtered and, later, routed to the right driver.
   test         optional. A repo path to a co-located runnable file (a playwright.spec.ts, a script)
-               the agent MAY run by hand. Not a driver — yatsu never executes it.
+               the agent MAY run by hand. Not a driver — eval never executes it.
   code         optional. The file THIS scenario GOVERNS, ideally one (a comma list / flow list \`[a, b]\` is
                allowed) — its own slice of the code freshness axis, so scenarios on one node go stale
                independently. Absent → it inherits the node's \`code:\` list. A file governed by > maxOwners
-               scenarios warns \`yatsu-owners\` (split it). Each path must exist (a ghost → \`yatsu-schema\`).
+               scenarios warns \`eval-owners\` (split it). Each path must exist (a ghost → \`eval-schema\`).
   related      optional. Files this scenario REFERENCES but does not govern — same path forms. They do NOT
                stale it (the freshness mirror of a spec node's govern/related). Each path must exist.
 Multi-line prose uses YAML block scalars: \`|\` keeps newlines, \`>\` folds wrapped lines to spaces.
-A yatsu.md OWNS nothing — only its scenarios govern and relate (see governed-related).
+An eval.md OWNS nothing — only its scenarios govern and relate (see governed-related).
 
 THE SCHEMA IS ENFORCED (closed field set, four required fields, unique names, tags within the library). A
 missing required field, an unknown key (a typo like \`descripton:\`), a duplicate name, an out-of-library
-tag, or no scenarios at all is rejected LOUD: \`spex yatsu scan\` reports it as \`yatsu-schema\`, and the
-pre-commit \`yatsu check-staged\` BLOCKS the commit.
+tag, or no scenarios at all is rejected LOUD: \`spex eval lint\` reports it as \`eval-schema\`, and the
+pre-commit \`internal check-staged\` BLOCKS the commit.
 
 BODY (after the frontmatter): prose naming the measurement method — YATU ("You As The User"): the agent
-looks at / calls the real product surface, not an internal helper chosen to make the proof easy.
+looks at / calls the real product surface, not an internal helper chosen to make the evidence easy.
 
 MEASURING AND FILING: the agent runs the scenario however it likes (a browser run, an API
 transcript, a by-hand pass), compares the result to \`expected\`, and files it:
-  spex yatsu eval <node> --scenario <name> (--pass | --fail) [--note <text>]
-                 [--image <png> …repeatable] [--result <txt>|-] [--video <webm|mp4> [--timeline <json>]]
+  spex eval add <node> [--scenario <name>] (--pass | --fail) [--note <text>]
+                 [--image <png> …repeatable] [--result <txt>|-] [--video <webm|mp4>] [--timeline <json>]
+(--scenario may be omitted only when the node declares exactly one scenario.)
 The verdict is \`--pass\` or \`--fail\` (a measurement must commit to one — an unmeasured scenario is \`missing\`,
 not a hedged fail). \`--note <text>\` is an OPTIONAL one-line annotation on either (why it failed, how far a
 pass sits from ideal); it does NOT replace evidence — the image/video/transcript is the captured actual behaviour.
@@ -145,10 +161,11 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       — never a value the agent eyeballs off the finished artefact afterwards (that's
                       misaligned and dishonest, worse than none). \`--timeline <json>\` carries one; its \`axis\`
                       is the evidence's: a video is \`time\` (ms), a transcript \`line\`, a still SEQUENCE \`frame\`,
-                      an action trace \`index\` (the set is OPEN — an unknown axis just renders as a bare number).
+                      a structured data export \`index\` (record ordinals; the format's axis set is open — an
+                      unknown axis just renders as a bare number).
                       \`at\` = the position on that axis, \`step\` = a short name for that moment; copy this shape:
                         { "v": 2, "axis": "time",
-                          "events": [ { "at": 0, "step": "open board" },
+                          "events": [ { "at": 0, "step": "open graph" },
                                       { "at": 1200, "step": "type query" } ] }
                       The run exports it: in whatever drives the evidence — Playwright, a computer-use hand, a
                       CLI harness stamping line numbers — take a baseline and at EACH real step push
@@ -157,36 +174,40 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       skip it for a short single-step artefact. (Legacy \`{ "v": 1, "events": [{ "tMs" }] }\` — the
                       time axis with \`tMs\` — is still accepted, read as \`axis: "time"\`.)
   STATIC end state  → \`--image <png>\` (repeatable — N stills). Layout, an icon, copy, one rendered frame.
-  backend / CLI     → \`--result <txt>\` (a transcript; \`-\` reads stdin). A STRUCTURED export (a JSON
-                      \`--export-json\`, an API payload, a metrics dump) is recognized BY CONTENT and kept as
+  backend / CLI     → \`--result <txt>\` (a transcript; \`-\` reads stdin). A STRUCTURED export (a tool's
+                      \`--export-json\` dump, an API payload, a metrics dump) is recognized BY CONTENT and kept as
                       \`data\` — rendered as a validatable data block, not flattened into scrolling transcript
                       text; free-form output stays a transcript. You pick the flag; the KIND follows the bytes.
 The flags combine in ONE filing — several stills can ride beside the clip of the same run.
-ANCHOR DISCIPLINE: a reading's \`codeSha\` is HEAD at filing time, and a git sha names only a COMMIT — an
+ANCHOR DISCIPLINE: an eval's \`codeSha\` is HEAD at filing time, and a git sha names only a COMMIT — an
 uncommitted change has none. So measure the tree you are about to commit, COMMIT it, then file; confidence
 is earned on the working tree, but the anchor can only land after the commit. Filing from a dirty tree
-mis-anchors the reading (its sha lacks the change it measured) and it goes stale the moment you commit.
+mis-anchors the eval (its sha lacks the change it measured) and it goes stale the moment you commit.
 
 A botched filing (a junk e2e/smoke run, a wrong verdict) is undone through the SAME surface:
-  spex yatsu retract <node> [--scenario <name>] [--last | --ts <iso>] [--note <why>]
+  spex eval retract <node> [--scenario <name>] [--last | --ts <iso>] [--note <why>]
 retract APPENDS a retraction event to the sidecar (never deletes a line — the trace stays, git records
-who/when/why); the scoreboard then drops the retracted reading everywhere: the previous reading becomes
+who/when/why); the scoreboard then drops the retracted eval everywhere: the previous eval becomes
 the latest again, or the scenario honestly returns to \`missing\`. Default target is the scenario's latest
-reading (\`--last\` makes that explicit; repeat to peel junk back one filing at a time); \`--ts\` pins one.
-
-THE SCOREBOARD: readings live in yatsu.evals.ndjson beside the yatsu.md — one JSON line per measurement
-(a second git-as-database axis). Freshness is derived live from git: a reading goes STALE when a governed
-code file or the scenario (the yatsu.md) moves since it was filed.
-  spex yatsu scan [--changed]   blind spots: yatsu-schema (malformed) · yatsu-drift (stale) ·
-                                yatsu-missing (never measured) · yatsu-uncovered (governed source, no yatsu.md) ·
-                                yatsu-owners (a file governed by > maxOwners scenarios — split it)
-  spex yatsu show <node>        the reading timeline (verdict · freshness · evidence), newest first
-  spex yatsu clean              GC the content-addressed evidence cache`
-
-const CONFIG = `spex guide config — SpexCode's runtime settings (spexcode.json / spexcode.local.json)
+eval (\`--last\` makes that explicit; repeat to peel junk back one filing at a time); \`--ts\` pins one.
+
+THE SCOREBOARD: evals live in evals.ndjson beside the eval.md — one JSON line per measurement
+(a second git-as-database axis). Freshness is derived live from git: an eval goes STALE when a governed
+code file or the scenario (the eval.md) moves since it was filed.
+  spex eval lint [--changed]     the measurement layer's findings — PURE ADVISORY, always exit 0 (spec
+                                 lint's errors block commits; a measurement gap never blocks anyone):
+                                 eval-schema (malformed) · eval-drift (stale) · eval-missing (never
+                                 measured) · eval-dangling (orphaned remark track) · eval-coverage
+                                 (governed source, no eval.md — spec lint's coverage, one rule per layer) ·
+                                 eval-owners (a file governed by > maxOwners scenarios — split it)
+  spex eval ls <node>            the eval timeline (verdict · freshness · evidence), newest first
+  spex eval scenario ls [<node>] the declared contracts; --unmeasured = the blind-spot worklist
+  spex eval clean                GC the content-addressed evidence cache`
+
+const SETTINGS = `spex guide settings — SpexCode's runtime settings (spexcode.json / spexcode.local.json)
 
 SpexCode reads its runtime settings from TWO optional JSON files at the repo root. There is no imperative
-\`spex config set\` — an agent CONFIGURES SpexCode by EDITING these files directly. The two split by
+settings verb — an agent CONFIGURES SpexCode by EDITING these files directly. The two split by
 PORTABILITY, and picking the right one is the whole discipline:
 
   spexcode.json         COMMITTED — portable, shared by everyone on the repo. Layout, policy, dashboard
@@ -200,7 +221,7 @@ Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A
 icon, a lint budget, a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
 PATH of a launcher wrapper or a TLS cert path are machine facts → gitignored spexcode.local.json.
 Both files are optional; omit any field to take its default, except \`sessions.defaultLauncher\` when using
-\`spex new\` or the dashboard without an explicit launcher choice.
+\`spex session new\` or the dashboard without an explicit launcher choice.
 
 MERGE: spexcode.local.json is layered over spexcode.json ONE LEVEL DEEP — per top-level section (dashboard,
 sessions, …), the two objects are shallow-merged with LOCAL WINNING per key; sections only one file names
@@ -218,14 +239,16 @@ Example — a repo whose trunk is \`staging\`, not \`main\`:
 ── DASHBOARD (spexcode.json — portable project identity) ──
   dashboard.title   browser-tab name. Default: the repo-root basename.
   dashboard.icon    browser-tab favicon: an emoji ("🔭") OR an Iconify name ("mdi:rocket-launch").
-  dashboard.apiUrl  the per-project backend the board proxies to (read frontend-side). For a SHARED
-                    install prefer the API_URL env var; apiUrl here is the default only when the board
+  dashboard.apiUrl  the per-project backend the dashboard proxies to (read frontend-side). For a SHARED
+                    install prefer the API_URL env var; apiUrl here is the default only when the dashboard
                     lives inside the project.
 Example:
   { "dashboard": { "title": "MyApp specs", "icon": "mdi:rocket-launch" } }
 
 ── SESSIONS / WORKERS ──
-  sessions.maxActive        concurrency cap — max agents AUTONOMOUSLY PROGRESSING at once (default 8).
+  sessions.maxActive        concurrency cap — max agents AUTONOMOUSLY PROGRESSING at once (default 8;
+                            precedence: spexcode.json → SPEXCODE_MAX_ACTIVE env → default; read live, so
+                            an edit applies without a restart).
                             Counts compute slots, not total sessions: idle/asking/review/done do not
                             occupy one. A policy number → committed spexcode.json; omit it to use the
                             default, or tune higher/lower for the project's usual host.
@@ -265,12 +288,13 @@ in the committed spexcode.json — the merge keeps both:
     }
   }
 
-── SERVE (spexcode.json — public-exposure for \`spex serve --public\`) ──
+── SERVE (spexcode.json ONLY — public-exposure for \`spex serve --public\`; this section is read straight
+   from spexcode.json, the local overlay is NOT consulted here) ──
   serve.public.enabled   turn public mode on without the --public flag.
   serve.public.http      drop TLS (the --http escape hatch) — the password then travels in cleartext.
   serve.public.tls       { "cert": "<path>", "key": "<path>" } — PATHS to your own cert/key; omit for a
-                         cached self-signed default. If the paths are host-specific, put them in
-                         spexcode.local.json.
+                         cached self-signed default. Host-specific paths can instead ride the
+                         --tls-cert/--tls-key flags or SPEXCODE_TLS_CERT/SPEXCODE_TLS_KEY env (which win).
 The gateway password is NEVER read from these files (flag/env only), so serve.public stays committable.
 
 ── BACKEND ROUTING (not a config field — how a \`spex\` command picks its backend) ──
@@ -286,20 +310,23 @@ resolves its backend per this ladder, flag first:
                              health-probes before trusting (a dead record is ignored).
   3.  the other side as fallback (human with no live record → env; worker with no env → record).
   4.  default http://127.0.0.1:$PORT||8787.
-WRITES are project-bound: every mutating verb (new/merge/send/close/rename/rawkey/reopen/exit) refuses
+WRITES are project-bound: every mutating verb (new/merge/send/close/rename/resume/stop) refuses
 loudly when the resolved backend serves a DIFFERENT same-host project — an explicit --api/--port skips
-the guard (the flag is the proof of intent). Reads point anywhere.
+the guard (the flag is the declaration of intent). Reads point anywhere.
 
 ── ISSUES (spexcode.json — portable policy) ──
   issues.enabled      the issues-workflow on/off switch (default ON). OFF silences the post-merge nudge and
-                      hides the dashboard view; the CLI toggle is \`spex issues on|off\`.
+                      hides the dashboard view. Flip it by editing the JSON — there is no CLI toggle verb;
+                      \`spex doctor\` reports the current state (and flags a legacy \`proposals.enabled\` key,
+                      which is no longer read).
 
 ── FORGE (spexcode.json — which forge this repo's remote is; a project fact, so committed) ──
   forge.host          explicit forge host id ('github' | 'gitlab' | …) overriding the automatic derivation.
                       Normally OMIT it: spec-forge resolves the host from the origin remote's hostname —
-                      github.com → github, a gitlab/self-hosted remote → gitlab — and only an ambiguous
-                      self-hosted domain the heuristic misreads needs the override. A resolved host with no
-                      registered driver degrades to an EMPTY forge slice (local issues still work, no error).
+                      github.com → github, bitbucket → bitbucket, any other remote → gitlab (the common
+                      self-hosted shape) — and only a domain the heuristic misreads needs the override.
+                      A resolved host with no registered driver degrades to an EMPTY forge slice (local
+                      issues still work, no error).
 
 ── LINT (spexcode.json — a top-level "lint" key; budgets are portable, so committed only) ──
   lint.governedRoots       dirs whose source files must each be governed by a spec (coverage).
@@ -314,13 +341,13 @@ the guard (the flag is the proof of intent). Reads point anywhere.
   lint.driftErrorThreshold commit-local gate HARD-BLOCKS a commit touching a node >= this many commits
                            behind (default 3).
   lint.maxOwners           warn when a file is governed by > this many nodes (default 3).
-  lint.scenarioTags        the closed vocabulary a yatsu scenario's tags: must draw from (default
+  lint.scenarioTags        the closed vocabulary an eval scenario's tags: must draw from (default
                            ["frontend-e2e","backend-api","cli","desktop","mobile"]); extend to mint a tag.
 Example — govern your own source dir and loosen the altitude budget:
   { "lint": { "governedRoots": ["src"], "altitude": { "lineBudget": 70 } } }
 
 ── OTHER (spexcode.json unless noted) ──
-  preset      the SELECTED init preset — which cumulative .config tier \`spex init\` seeds (default
+  preset      the SELECTED init preset — which cumulative .plugins tier \`spex init\` seeds (default
               'default'; seed-time only, read by init.ts).
   harnesses   which harness targets \`spex materialize\` delivers into — native ids ("claude"|"codex") or a
               { "plugin": "<folder>" } bundle. Default (omitted): all native harnesses. PERSISTENT and
@@ -333,18 +360,18 @@ const FOOTPRINT = `spex guide footprint — what SpexCode plants in a repo, and
 SpexCode claims software engineering's HEAD (the recording of intent) and TAIL (the storage of
 measurement) and leaves the MIDDLE — construction — to the harness/agent/test framework; freshness
 stitches the two ends into a closed loop. The footprint follows: the head+tail (.spec, spexcode.json,
-readings) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
+evals) is the ASSET and lives in git like source; everything else is derived wiring or a machine fact.
 Materialized artifacts carry no facts, so they are NEVER tracked — there is exactly one residence
 behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 
 ── THE FOUR KINDS (all fixed) ──
-  spec data       .spec/ (incl .config/) + spexcode.json — ALWAYS tracked. Git is the database; there is
+  spec data       .spec/ (incl .plugins/) + spexcode.json — ALWAYS tracked. Git is the database; there is
                   deliberately NO way to say "untrack the spec" in this schema.
   machine facts   spexcode.local.json, the hook shims (.claude/settings.json, .codex/hooks.json), plugin
                   bundles — NEVER tracked; always in the per-clone exclude.
   artifacts       the CLAUDE.md/AGENTS.md contract blocks + materialized skills/agents — derived, NEVER
                   tracked; hidden via .git/info/exclude. The host's tracked .gitignore is never touched.
-  run residue     .worktrees/, the global store (~/.spexcode), .git/spexcode blobs — never tracked;
+  run residue     .worktrees/, the global store (~/.spexcode), .git/spexcode evidence — never tracked;
                   out-of-tree, or exclude-ruled where in-tree.
 
 ── A CONTRACT FILE'S RESIDENCE IS A LIVE CONTENT FACT (re-judged at every materialize) ──
@@ -360,10 +387,10 @@ behavior, decided per KIND (and, for a contract file, by its live CONTENT).
 ── THE GIT-NATIVE ANCHORS (no harness event ever triggers a materialize) ──
   spex init / spex materialize / session-worktree creation — the explicit passes;
   pre-commit    the correctness anchor: an UNCONDITIONAL materialize (masks provably fresh at the only
-                moment history is written) + staged-index surgery — a staged blob carrying the sentinel
-                block is cleaned IN PLACE (partial staging survives; source is the staged blob), a
+                moment history is written) + staged-index surgery — a staged file carrying the sentinel
+                block is cleaned IN PLACE (partial staging survives; source is the staged content), a
                 HEAD-untracked generated artifact is unstaged. Repairs and proceeds, never rejects.
-  post-checkout/post-merge   freshness anchors: .spec/.config edits are git-transactional — they take
+  post-checkout/post-merge   freshness anchors: .spec/.plugins edits are git-transactional — they take
                 effect at the commit/checkout/merge that carries them, like any other source change.
 An environment with no spex-planted hooks (CI, a cloud agent's fresh clone, a teammate who hasn't
 installed) simply runs \`spex materialize\` in its setup step — there is no committed-artifact mode.
@@ -373,7 +400,7 @@ TRACK ≠ PUSH: none of this ever touches remotes; where commits GO is branch/re
 materialize(P₂) ∘ materialize(P₁) = materialize(P₂): every materialize first ERASES all landing points by
 SpexCode's own identity stamps, then re-asserts — legacy states (a .gitignore managed block, a committed
 artifact) are forgotten by the same pass. \`spex uninstall\` is the empty
-materialize plus the global store: a total backout that never touches your .spec/.config or prose. Fresh
+materialize plus the global store: a total backout that never touches your .spec/.plugins or prose. Fresh
 clones and session worktrees are self-sufficient: data by checkout, materialized artifacts by
 re-materialize, the machine snapshot (spexcode.local.json) by copy.
 
@@ -393,7 +420,7 @@ remote, give it a different git HOME instead of untracking it. The manual recipe
      (e.g. .git/spexcode/<name>.git) — the dir then holds only a one-line .git pointer file, so the
      spec loader never walks an object store;
   4. commit the node's changes through that inner repo.
-The effect, honestly: filesystem-derived surfaces see the node (board, search, lint); git-derived
+The effect, honestly: filesystem-derived surfaces see the node (graph, search, lint); git-derived
 views are blind to it (version count, the history tab, drift), and a dispatched worker's worktree
 checkout does not contain it. Those gaps are what the pending spec-local design (a first-class
 private overlay root) closes — not built yet. Cautions: \`git clean -fdx\` in the outer repo deletes
@@ -407,7 +434,7 @@ not a flag flip.
                             elsewhere cannot be recalled.
   back out entirely         \`spex uninstall\` (add --hooks to also remove the spexcode git hooks).`
 
-const TOPICS: Record<string, string> = { spec: SPEC, yatsu: YATSU, config: CONFIG, footprint: FOOTPRINT }
+const TOPICS: Record<string, string> = { spec: SPEC, eval: EVAL, settings: SETTINGS, footprint: FOOTPRINT }
 
 // every guide page ends by naming the OTHER help layer, so a reader never dead-ends here: guide is
 // the skill layer (workflows · formats · settings); command usage lives in help.ts's two layers.

package/spec-cli/src/harness-select.ts

@@ -30,14 +30,14 @@ export function resolveHarnessTargets(raw: unknown): HarnessTarget[] {
   for (const m of raw) {
     if (typeof m === 'string') {
       if (m === 'plugin')
-        throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".zcode"}), not the bare string "plugin", because each host agent scans a different plugins dir.`)
+        throw new Error(`spexcode.json "harnesses": a plugin target needs an EXPLICIT landing folder — write {"plugin":"<folder>"} (e.g. {"plugin":".zcode"}), not the bare string "plugin", because each host agent reads a different plugins dir.`)
       if (!KNOWN.includes(m))
         throw new Error(`spexcode.json "harnesses": unknown harness id "${m}" — known native ids are ${KNOWN.join(', ')}, or use {"plugin":"<folder>"}.`)
       targets.push({ kind: 'native', id: m as HarnessId })
     } else if (m && typeof m === 'object' && !Array.isArray(m) && 'plugin' in m) {
       const folder = (m as { plugin?: unknown }).plugin
       if (typeof folder !== 'string' || !folder.trim())
-        throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".zcode"}) — each host agent scans a different plugins dir, so the folder must be explicit.`)
+        throw new Error(`spexcode.json "harnesses": a {"plugin":…} target needs a NON-EMPTY folder string (e.g. {"plugin":".zcode"}) — each host agent reads a different plugins dir, so the folder must be explicit.`)
       targets.push({ kind: 'plugin', folder: folder.trim() })
     } else {
       throw new Error(`spexcode.json "harnesses": each member must be a native id string (${KNOWN.join(', ')}) or a {"plugin":"<folder>"} object — got ${JSON.stringify(m)}.`)

package/spec-cli/src/harness.ts

@@ -25,10 +25,17 @@ import { git } from './git.js'
 export type HarnessId = 'claude' | 'codex'
 export type HarnessLivenessRecord = { session: string; harnessSessionId?: string | null }
 // the per-pane runtime probe the caller snapshots ONCE for the whole session list and hands liveness():
-// the pane's root pid (tmux `#{pane_pid}`) plus one whole-box pid→(ppid, comm) table (a single `ps` spawn).
-// The adapter that cares (codex) walks the pane pid's descendants in that table; claude ignores it.
+// the pane's root pid (tmux `#{pane_pid}`), the hot-tier `pidAlive` verdict, and — ONLY on the legacy path —
+// one whole-box pid→(ppid, comm) table (a single `ps` spawn).
+//   `pidAlive` = the hot registry's verdict for THIS session's launch-registered `agent.pid`: true = the pid
+//     answers kill-0 (alive), false = proven dead (ESRCH, permanently latched per pid-reuse guard), undefined =
+//     NO agent.pid file (a pre-registration/old session). codex reads this as its liveness truth when present
+//     and falls back to `procs` (the whole-box tree walk) only when it is undefined; claude ignores it (its
+//     truth is the rendezvous socket).
+//   `procs` is gathered (the single `ps` spawn) ONLY when a pid-less codex session still needs the legacy
+//     tree-walk, so a box with no codex — or all pid-registered launches — never pays for it.
 export type ProcTable = Map<number, { ppid: number; comm: string }>
-export type PaneProbe = { panePid?: number; procs?: ProcTable }
+export type PaneProbe = { panePid?: number; procs?: ProcTable; pidAlive?: boolean }
 
 export interface Harness {
   readonly id: HarnessId
@@ -116,11 +123,13 @@ export interface Harness {
   // live listener (the caller probes all windowed sessions once per snapshot). The adapter adds only its own
   // channel check. claude: online iff the window is up AND its reclaude rendezvous socket has a live LISTENER
   // (`socketLive` — a connect that a live claude accepts and a stale socket FILE refuses; claude IGNORES the
-  // pane probe). codex: online iff the window is up AND a codex-ish process (`codex` by any
-  // name, or the `node` its CLI runs under) is live in the pane pid's DESCENDANT tree — NOT the pane's
-  // foreground command name (that is `bash`, the launch wrapper, even while the TUI renders — field-confirmed),
-  // and NOT the SHARED per-project app-server socket (it stays bound after a failed `--remote resume` dropped
-  // the pane back to the shell). A missing probe (tmux/ps couldn't report) is not-live. The 'starting' boot
+  // pane probe). codex: online iff the window is up AND the launch-registered `agent.pid` is alive
+  // (`pane.pidAlive`, the hot-tier kill-0 verdict — zero ps scan); a pre-registration session with no agent.pid
+  // (`pidAlive` undefined) falls back to the LEGACY whole-box tree walk — a codex-ish process (`codex` by any
+  // name, or the `node` its CLI runs under) live in the pane pid's DESCENDANT tree, NOT the pane's foreground
+  // command name (that is `bash`, the launch wrapper, even while the TUI renders — field-confirmed), and NOT the
+  // SHARED per-project app-server socket (it stays bound after a failed `--remote resume` dropped the pane back
+  // to the shell). A missing probe (tmux/ps couldn't report) is not-live. The 'starting' boot
   // grace lives in the caller (sessions.ts liveness), so a still-booting pane reads starting, not offline.
   liveness(rec: HarnessLivenessRecord, tmuxAlive: boolean, runtimeDir?: string, pane?: PaneProbe, socketLive?: boolean): 'online' | 'offline'
   // deliver a follow-up prompt to a LIVE session and report whether it landed. claude: through the rendezvous
@@ -1042,11 +1051,18 @@ export const codexHarness: Harness = {
   removeTrust: (proj) => removeCodexTrust(mainCheckout(proj)),
   clean(proj, arts) { cleanHarness(this, proj, arts) },
   slashCommands: codexSlashCommands,
-  // online iff the tmux window is up AND a codex-ish process is live in the pane pid's DESCENDANT tree — see
-  // paneTreeRunsCodex. NOT the pane's foreground command (that is `bash`, the launch wrapper, even while the
-  // TUI renders — the field-confirmed false-OFFLINE) and NOT the app-server socket (SHARED per-project, it
-  // survives a failed `--remote resume` — the earlier false-ONLINE).
-  liveness: (_rec, tmuxAlive, _runtimeDir, pane) => (tmuxAlive && paneTreeRunsCodex(pane) ? 'online' : 'offline'),
+  // online iff the tmux window is up AND the agent is live. PRIMARY: the launch-registered `agent.pid` hot-tier
+  // verdict (`pidAlive`) — a 100ms syscall (kill-0), no ps scan. LEGACY: a pre-registration session has no
+  // agent.pid (`pidAlive` undefined) → fall back to the whole-box ps DESCENDANT-tree walk (paneTreeRunsCodex):
+  // a codex-ish process live below the pane pid, NOT the pane's foreground command (that is `bash`, the launch
+  // wrapper, even while the TUI renders — the field-confirmed false-OFFLINE) and NOT the app-server socket
+  // (SHARED per-project, it survives a failed `--remote resume` — the earlier false-ONLINE). The legacy path
+  // self-extinguishes as pre-registration sessions close.
+  liveness: (_rec, tmuxAlive, _runtimeDir, pane) => {
+    if (!tmuxAlive) return 'offline'
+    if (pane?.pidAlive !== undefined) return pane.pidAlive ? 'online' : 'offline'
+    return paneTreeRunsCodex(pane) ? 'online' : 'offline'
+  },
   deliver: (rec, text) => deliverViaCodexAppServer(rec, text),
   // owned thread id → `--resume <id>` MARKER the codex launch script reads to resume that thread DIRECTLY (NOT
   // a tail handed to a bare `codex` — the script's final `codex … resume "$tid"` performs codex's own resume on
@@ -1088,7 +1104,7 @@ export function launcherList(root = mainCheckout()): Launcher[] {
 export const MISSING_DEFAULT_LAUNCHER_ERROR =
   'sessions.defaultLauncher is required for a launch without --launcher; set it in spexcode.json or spexcode.local.json (for example {"sessions":{"defaultLauncher":"claude"}})'
 
-// the configured default launcher NAME ([[launcher-select]]) — the profile `spex new`/a dropdown pick with no
+// the configured default launcher NAME ([[launcher-select]]) — the profile `spex session new`/a dropdown pick with no
 // explicit choice resolves. Missing config is a fail-loud setup error, never an implicit fallthrough to a
 // `claude` launcher (which `spex init` seeds by name, so a default can point at it explicitly).
 export function defaultLauncher(root = mainCheckout()): string {