spexcode 0.1.5 → 0.2.0

package/spec-cli/src/git.ts

@@ -113,41 +113,6 @@ export function worktreeSpecSig(wtPath: string): string {
 export type Version = { hash: string; date: string; reason: string; session: string | null }
 export type DiffStat = { additions: number; deletions: number; files: number }
 
-// per-commit numstat for one file, rename-followed; a pure rename is 0/0 so callers tell "moved" from
-// "changed". The per-file path for files outside `.spec` (`.spec` goes through the bulk index below).
-function fileStatsFollow(root: string, relPath: string): Map<string, DiffStat> {
-  const m = new Map<string, DiffStat>()
-  let out = ''
-  try {
-    out = git(['-C', root, 'log', '--follow', '--format=%H', '--numstat', '--', relPath])
-  } catch {
-    return m
-  }
-  let cur = ''
-  for (const line of out.split('\n')) {
-    const t = line.trim()
-    if (/^[0-9a-f]{7,40}$/.test(t)) { cur = t; if (!m.has(cur)) m.set(cur, { additions: 0, deletions: 0, files: 0 }); continue }
-    const n = line.match(/^(\d+|-)\t(\d+|-)\t/)
-    if (n && cur) { const s = m.get(cur)!; s.files++; s.additions += n[1] === '-' ? 0 : +n[1]; s.deletions += n[2] === '-' ? 0 : +n[2] }
-  }
-  return m
-}
-
-function historyFollow(root: string, relPath: string): Version[] {
-  let out = ''
-  try {
-    out = git(['-C', root, 'log', `--format=%H${US}%aI${US}%s${US}%b${RS}`, '--follow', '--', relPath])
-  } catch {
-    return []
-  }
-  const stats = fileStatsFollow(root, relPath)
-  return out.split(RS).map((r) => r.trim()).filter(Boolean).map((rec) => {
-    const [hash, date, reason, body = ''] = rec.split(US)
-    const m = body.match(/Session:\s*(\S+)/)
-    return { hash, date, reason, session: m ? m[1] : null }
-  }).filter((v) => { const s = stats.get(v.hash); return s != null && s.additions + s.deletions > 0 })
-}
-
 // ---- bulk spec history index ----
 
 export type HistoryIndex = {
@@ -174,14 +139,35 @@ function parseStatPath(token: string): { from: string; to: string } {
   return { from: token, to: token }
 }
 
-let indexCache: { head: string; idx: HistoryIndex } | null = null
+// Both bulk indices are pure functions of a checkout's HEAD, and they are read for SEVERAL roots at
+// once — the backend checkout (board, loadSpecs) plus every session worktree ([[review-proof]]'s eval
+// tab roots its readings at the session's branch). A single-slot cache thrashes between those roots:
+// each eval-tab request evicts the board's entry and vice versa, so every request re-runs a full-history
+// `git log` and re-parses it on the event loop — which is what starves every other request (the board,
+// remark posts) under load. So the cache is a small LRU keyed by HEAD (same head ⇒ same index, whatever
+// the root), holding the in-flight PROMISE so concurrent requests for one head share a single build.
+const INDEX_SLOTS = 16
+function lruGet<V>(m: Map<string, V>, k: string): V | undefined {
+  const v = m.get(k)
+  if (v !== undefined) { m.delete(k); m.set(k, v) }   // refresh recency
+  return v
+}
+function lruPut<V>(m: Map<string, V>, k: string, v: V): void {
+  m.set(k, v)
+  while (m.size > INDEX_SLOTS) m.delete(m.keys().next().value!)
+}
+
+const indexCache = new Map<string, Promise<HistoryIndex>>()
 
-export async function historyIndex(root: string): Promise<HistoryIndex> {
+export function historyIndex(root: string): Promise<HistoryIndex> {
   const head = headOrEmpty(root)
-  if (indexCache && head && indexCache.head === head) return indexCache.idx
-  const idx = await buildIndex(root)
-  if (head) indexCache = { head, idx }
-  return idx
+  if (!head) return buildIndex(root)
+  const hit = lruGet(indexCache, head)
+  if (hit) return hit
+  const p = buildIndex(root)
+  p.catch(() => { indexCache.delete(head) })   // don't pin a failed build
+  lruPut(indexCache, head, p)
+  return p
 }
 
 // resolve HEAD for cache-keying, '' if unreadable (fails the cache test → recompute); warns once.
@@ -232,9 +218,6 @@ async function buildIndex(root: string): Promise<HistoryIndex> {
   return { versions, stats }
 }
 
-// reset the cache when a process knows HEAD will have moved out from under it (tests, hooks).
-export function resetHistoryCache(): void { indexCache = null }
-
 // pure lookups over a prebuilt index (no git). rowsFor drops pure-rename rows (0/0) so a move isn't a version.
 export function rowsFor(idx: HistoryIndex, relPath: string): Version[] {
   const rows = idx.versions.get(relPath) ?? []
@@ -266,18 +249,6 @@ export async function pathsStats(root: string, paths: string[]): Promise<Map<str
   return m
 }
 
-// a file's version timeline: `.spec` from the bulk index, anything else (governed code) via per-file --follow.
-export async function history(root: string, relPath: string): Promise<Version[]> {
-  if (relPath.startsWith('.spec/')) return rowsFor(await historyIndex(root), relPath)
-  return historyFollow(root, relPath)
-}
-
-// per-commit stat for this node's spec.md (rename-followed), summed with governed-code stats by specHistory.
-export async function specStats(root: string, relPath: string): Promise<Map<string, DiffStat>> {
-  if (relPath.startsWith('.spec/')) return statsFor(await historyIndex(root), relPath)
-  return fileStatsFollow(root, relPath)
-}
-
 // the patch a spec.md got in one commit (vs parent); resolve its path AT that commit (reparents move it)
 // via the stable leaf dir `…/<id>/spec.md`, then `git show` that path. `-M` keeps a rename+edit's body. '' on error.
 export async function fileDiffAt(root: string, relPath: string, hash: string): Promise<string> {
@@ -288,35 +259,44 @@ export async function fileDiffAt(root: string, relPath: string, hash: string): P
   return gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '-M', '--format=', hash, '--', at])
 }
 
-// ONE cached `git log` over HEAD (mirrors historyIndex): each commit's position (0 = newest) + per
-// file the commits that touched it; driftFor() is then a pure lookup. `acks`/`specNodes` carry the
-// Spec-OK convention (see driftFor): acks[hash] = node ids declared still-valid via `Spec-OK:` trailers;
-// specNodes[hash] = node ids whose spec.md it touched.
+// A cached `git log` over HEAD (HEAD-keyed like historyIndex), enriched with parent edges so "newer than
+// the spec" is answered by true DAG reachability, never by a log-position/date compare (a linear
+// order can't encode a branching history's partial order and silently under-reports — back-dated
+// branches, adoption). driftFor()/ancestorsOf() are then pure in-memory lookups. `acks`/`specNodes`
+// carry the Spec-OK convention (see driftFor): acks[hash] = node ids declared still-valid via
+// `Spec-OK:` trailers; specNodes[hash] = node ids whose spec.md it touched.
 export type DriftIndex = {
-  pos: Map<string, number>
+  ord: Map<string, number>            // hash -> dense id from the walk: a bitset slot, NEVER an order to compare
+  parents: Map<string, string[]>      // hash -> parent hashes (the DAG edges, from the same walk)
   fileCommits: Map<string, string[]>
   acks: Map<string, Set<string>>      // commit hash -> node ids acknowledged via `Spec-OK:` trailers
   specNodes: Map<string, Set<string>> // commit hash -> node ids whose spec.md it touched (its versions)
+  anc: Map<string, Uint8Array>        // memoized reachability bitsets, lazily built per queried sha
 }
-let driftIdxCache: { head: string; idx: DriftIndex } | null = null
+const driftIdxCache = new Map<string, Promise<DriftIndex>>()   // HEAD-keyed LRU, same shape as indexCache above
 
 async function buildDriftIndex(root: string): Promise<DriftIndex> {
-  const pos = new Map<string, number>(), fileCommits = new Map<string, string[]>()
+  const ord = new Map<string, number>(), parents = new Map<string, string[]>()
+  const fileCommits = new Map<string, string[]>()
   const acks = new Map<string, Set<string>>(), specNodes = new Map<string, Set<string>>()
-  // RS-delimited records: `<hash>US<comma-joined Spec-OK values>` on line 1, then the --name-only file
-  // list. `valueonly,separator` collapses the trailer block to one line so it never collides with the
-  // file names below it (a raw `%b` body would interleave with them and be unparseable).
+  const idx: DriftIndex = { ord, parents, fileCommits, acks, specNodes, anc: new Map() }
+  // RS-delimited records: `<hash>US<parents>US<comma-joined Spec-OK values>` on line 1, then the
+  // --name-only file list. `valueonly,separator` collapses the trailer block to one line so it never
+  // collides with the file names below it (a raw `%b` body would interleave and be unparseable).
   const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'log', '--name-only',
-    `--format=${RS}%H${US}%(trailers:key=Spec-OK,valueonly,separator=%x2C)`, 'HEAD'])
-  if (!out) return { pos, fileCommits, acks, specNodes }
+    `--format=${RS}%H${US}%P${US}%(trailers:key=Spec-OK,valueonly,separator=%x2C)`, 'HEAD'])
+  if (!out) return idx
   let i = 0
   for (const rec of out.split(RS)) {
     const r = rec.replace(/^\n/, '')
     if (!r) continue
     const lines = r.split('\n')
-    const [hash, ackStr = ''] = lines[0].split(US)
+    const [hash, parentStr = '', ackStr = ''] = lines[0].split(US)
     if (!hash) continue
-    if (!pos.has(hash)) pos.set(hash, i++)
+    if (!ord.has(hash)) {
+      ord.set(hash, i++)
+      parents.set(hash, parentStr.split(' ').filter(Boolean))
+    }
     const ackSet = new Set(ackStr.split(',').map((s) => s.trim()).filter(Boolean))
     if (ackSet.size) acks.set(hash, ackSet)
     for (const line of lines.slice(1)) {
@@ -329,42 +309,75 @@ async function buildDriftIndex(root: string): Promise<DriftIndex> {
       }
     }
   }
-  return { pos, fileCommits, acks, specNodes }
+  return idx
 }
-export async function driftIndex(root: string): Promise<DriftIndex> {
+export function driftIndex(root: string): Promise<DriftIndex> {
   const head = headOrEmpty(root) // filesystem HEAD, no subprocess — see historyIndex
-  if (driftIdxCache && head && driftIdxCache.head === head) return driftIdxCache.idx
-  const idx = await buildDriftIndex(root)
-  if (head) driftIdxCache = { head, idx }
-  return idx
+  if (!head) return buildDriftIndex(root)
+  const hit = lruGet(driftIdxCache, head)
+  if (hit) return hit
+  const p = buildDriftIndex(root)
+  p.catch(() => { driftIdxCache.delete(head) })
+  lruPut(driftIdxCache, head, p)
+  return p
+}
+// the reachability set of `sha` — itself plus every ancestor — as a bitset over the walk's dense ids.
+// Built once per queried sha by following parent edges in memory (no git fork), memoized on the index;
+// a bitset costs history-length BITS, so hundreds of cached shas stay cheap on the board hot path.
+// undefined when `sha` is not reachable from HEAD (rebased away, an unmerged branch, or never on any
+// ref) — callers apply their own conservative rule to that "can't prove" case.
+export function ancestorsOf(idx: DriftIndex, sha: string): Uint8Array | undefined {
+  const hit = idx.anc.get(sha)
+  if (hit) return hit
+  const start = idx.ord.get(sha)
+  if (start === undefined) return undefined
+  const bits = new Uint8Array((idx.ord.size + 7) >> 3)
+  bits[start >> 3] |= 1 << (start & 7)
+  const stack = [sha]
+  while (stack.length) {
+    for (const p of idx.parents.get(stack.pop()!) ?? []) {
+      const o = idx.ord.get(p)
+      if (o === undefined) continue // shallow-clone boundary: an unwalked parent ends the chain
+      const m = 1 << (o & 7)
+      if (bits[o >> 3] & m) continue
+      bits[o >> 3] |= m
+      stack.push(p)
+    }
+  }
+  idx.anc.set(sha, bits)
+  return bits
 }
-// pure lookup: how many commits to `path` are newer than `sinceHash` (the spec's last version) and not
-// yet acknowledged. No git calls.
+export function inAncestors(idx: DriftIndex, bits: Uint8Array, sha: string): boolean {
+  const o = idx.ord.get(sha)
+  return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0
+}
+
+// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
+// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
 //
 // `sinceHash` is the node's OWN latest version commit, so the node(s) it's a version of
-// (specNodes[sinceHash]) name the node being measured; an ack counts only if its `Spec-OK:` set names one
-// of those — `Spec-OK: A` quiets A's drift, never B's.
+// (specNodes[sinceHash]) name the node being measured; an ack counts only if its `Spec-OK:` set names
+// one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that is itself an ancestor of the
+// version can't speak for it (a re-version invalidates older acks); a valid ack quiets exactly the
+// commits reachable from it. An off-history `sinceHash` → 0: no basis on HEAD to measure from.
 export function driftFor(idx: DriftIndex, sinceHash: string, path: string): number {
   if (!sinceHash) return 0
-  const sp = idx.pos.get(sinceHash)
-  if (sp === undefined) return 0
+  const base = ancestorsOf(idx, sinceHash)
+  if (!base) return 0
   const targets = idx.specNodes.get(sinceHash)
-  // the newest commit that acks a target (smallest pos = closest to HEAD) is the floor at/below which all
-  // drift is acknowledged. No target / no matching ack → Infinity, so nothing is quieted. An ack at or
-  // before the version (p >= sp) can't speak for it — a re-version invalidates older acks.
-  let ackPos = Infinity
+  const ackCover: Uint8Array[] = []
   if (targets) {
     for (const [h, ackSet] of idx.acks) {
-      const p = idx.pos.get(h)
-      if (p === undefined || p >= sp) continue
-      if ([...targets].some((t) => ackSet.has(t))) ackPos = Math.min(ackPos, p)
+      if (inAncestors(idx, base, h)) continue
+      if (![...targets].some((t) => ackSet.has(t))) continue
+      const a = ancestorsOf(idx, h)
+      if (a) ackCover.push(a)
     }
   }
   let n = 0
   for (const h of idx.fileCommits.get(path) ?? []) {
-    const p = idx.pos.get(h)
-    if (p === undefined || p >= sp) continue   // older than / at the version → not drift
-    if (p >= ackPos) continue                  // at or below the newest covering ack → acknowledged
+    if (inAncestors(idx, base, h)) continue           // reachable from the version → not drift
+    if (ackCover.some((a) => inAncestors(idx, a, h))) continue // covered by an ack → acknowledged
     n++
   }
   return n

package/spec-cli/src/guide.ts

@@ -27,9 +27,11 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
      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).
 
-The file formats an agent authors — run these for the full schema:
+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 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
+                      budgets, layout) — every field, and which of the two files it belongs in`
 
 const SPEC = `spex guide spec — the spec.md file format
 
@@ -51,7 +53,7 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
   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
            govern doesn't. Every listed path must exist (lint integrity error otherwise).
-  surface  config/.config nodes only: system (folded into every agent's prompt) | slash (a /command) |
+  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.
@@ -92,6 +94,11 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
   name         REQUIRED. Unique within the file — it keys the sidecar and \`--scenario <name>\`.
   description  REQUIRED. What to check / how to measure it through the running product.
   expected     REQUIRED. What ZERO loss looks like — the target the measurement is compared against.
+  tags         REQUIRED. ≥1 classification tag (a comma list / flow list \`[a, b]\`), each drawn from the
+               configured library (\`lint.scenarioTags\` in spexcode.json; ships
+               \`frontend-e2e, backend-api, cli, desktop, mobile\`). A tag outside the library is rejected —
+               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.
   code         optional. The file THIS scenario GOVERNS, ideally one (a comma list / flow list \`[a, b]\` is
@@ -103,18 +110,29 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
 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).
 
-THE SCHEMA IS ENFORCED (closed field set, three required fields, unique names). A missing required field,
-an unknown key (a typo like \`descripton:\`), a duplicate name, 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.
+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.
 
 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.
 
 MEASURING AND FILING: the agent runs the scenario however it likes (a browser screenshot, 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> | --result <txt>|-]
+  spex yatsu eval <node> --scenario <name> (--pass | --fail) [--note <text>] [--image <png> | --result <txt>|-]
+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/transcript is the captured actual behaviour.
 Frontend → \`--image <png>\` (visual evidence); backend → \`--result <txt>\` (a transcript; \`-\` reads stdin).
 
+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>]
+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
+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, the scenario (the yatsu.md), or the evaluator moves since it was filed.
@@ -124,11 +142,156 @@ code file, the scenario (the yatsu.md), or the evaluator moves since it was file
   spex yatsu show <node>        the reading timeline (verdict · freshness · evidence), newest first
   spex yatsu clean              GC the content-addressed evidence cache`
 
-const TOPICS: Record<string, string> = { spec: SPEC, yatsu: YATSU }
+const CONFIG = `spex guide config — 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
+PORTABILITY, and picking the right one is the whole discipline:
+
+  spexcode.json         COMMITTED — portable, shared by everyone on the repo. Layout, policy, dashboard
+                        identity, lint budgets, launcher NAMES. "Git is the database": tracked so the
+                        team shares ONE configuration.
+  spexcode.local.json   GITIGNORED — host-specific, never committed. Absolute launcher paths, cert/secret
+                        paths, private-overlay mode. Layered OVER spexcode.json (see MERGE below); an env
+                        var (SPEXCODE_CLAUDE_CMD, …) still overrides both at its read site.
+
+Rule of thumb — is the value TRUE FOR THE PROJECT or TRUE FOR THIS MACHINE? A branch name, a dashboard
+icon, a lint budget, a launcher's name+harness are project facts → committed spexcode.json. The ABSOLUTE
+PATH of a launcher wrapper, a TLS cert path, private mode are machine facts → gitignored spexcode.local.json.
+Both files are optional; omit any field to take its default.
+
+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
+pass through untouched. This is exactly what lets a launcher's portable NAME reference (defaultLauncher)
+sit in the committed file while its host-specific DEFINITION (with the abs cmd) sits in the local file —
+see LAUNCHERS.
+
+── LAYOUT (spexcode.json — portable; set only for a NON-DEFAULT repo layout) ──
+  main          path to the source-of-truth checkout. Default: the \`main\` worktree.
+  mainBranch    the source-of-truth BRANCH worktrees fork from. Default: auto-detected.
+  branchPrefix  how a node branch is named. Default "node/".
+Example — a repo whose trunk is \`staging\`, not \`main\`:
+  { "mainBranch": "staging" }
+
+── 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
+                    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).
+                            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.
+  sessions.claudeCmd        the UNNAMED default worker launcher for Claude (default
+                            'claude --dangerously-skip-permissions'); env SPEXCODE_CLAUDE_CMD overrides.
+  sessions.codexCmd         the UNNAMED default worker launcher for Codex (default 'codex --yolo'); env
+                            SPEXCODE_CODEX_CMD overrides.
+  sessions.launchers        NAMED launcher profiles (see LAUNCHERS).
+  sessions.defaultLauncher  the launcher name a create with no explicit --launcher/dropdown pick uses
+                            (else the unnamed claudeCmd/codexCmd path). A portable NAME → committed.
+A claudeCmd/codexCmd or a launcher \`cmd\` that is a HOST-SPECIFIC ABSOLUTE PATH belongs in
+spexcode.local.json — the committed file must stay free of machine paths.
+
+── LAUNCHERS (the profile block, split across the two files) ──
+A named launcher profile fixes BOTH a session's harness AND its exact launch command; a create picks one
+by name, and the chosen name is persisted on the record so a resume reuses the same auth. Shape:
+  "launchers": { "<name>": { "harness": "claude" | "codex", "cmd": "<launch command>" } }
+\`harness\` defaults to "claude"; \`cmd\` is required. Because \`cmd\` is a machine fact (an abs wrapper path),
+the DEFINITION lives in the gitignored spexcode.local.json, while the portable defaultLauncher NAME sits
+in the committed spexcode.json — the merge keeps both:
+
+  spexcode.json  (committed — the portable name reference)
+  { "sessions": { "defaultLauncher": "gpt5" } }
+
+  spexcode.local.json  (gitignored — the host-specific definitions)
+  {
+    "sessions": {
+      "launchers": {
+        "gpt5":       { "harness": "codex",  "cmd": "/Users/me/bin/reclaude-codex --yolo" },
+        "claude-prod": { "harness": "claude", "cmd": "/Users/me/bin/reclaude --dangerously-skip-permissions" }
+      }
+    }
+  }
+
+── SERVE (spexcode.json — public-exposure for \`spex serve --public\`) ──
+  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.
+The gateway password is NEVER read from these files (flag/env only), so serve.public stays committable.
+
+── 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\`.
+
+── 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).
+                           '.' = the whole project (only git-TRACKED files). Default
+                           ["spec-dashboard/src", "spec-cli/src"].
+  lint.sourceExtensions    extensions coverage treats as source. Default ["ts","tsx","js","jsx"].
+  lint.testGlobs           globs EXCLUDED from coverage (default ["**/*.test.*"]; [] to govern tests too).
+  lint.identifierExtensions extensions the altitude bare-filename signal recognises.
+  lint.altitude            body budgets: { lineBudget, charBudget, sizeable, dense, steps }
+                           (defaults 50 / 4200 / 35 / 1.3 / 3).
+  lint.maxChildren         breadth budget: warn at >= this many direct children (default 8).
+  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
+                           ["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
+              '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.
+  private     (spexcode.local.json ONLY) private-overlay mode — when true, \`spex materialize\` leaves ZERO
+              trace in the host's TRACKED files: managed ignore entries go to .git/info/exclude and any
+              tracked contract file is marked skip-worktree. Trades away git-derived spec version history.
+              A HOST decision → never the committed file. See PRIVATE MODE below.
+
+── PRIVATE MODE (default ⇄ private — the two delivery modes) ──
+DEFAULT mode (private absent/false): materialize commits .spec + spexcode.json and writes its ignore list as
+a managed block in the TRACKED .gitignore — transparent, but every collaborator sees it. PRIVATE mode
+(spexcode.local.json { "private": true }): the SAME contract reaches the agent, but the ignore list goes to
+the per-clone .git/info/exclude and any host-tracked CLAUDE.md/AGENTS.md is skip-worktree'd — so \`git status\`
+stays clean and nothing enters shared history.
+
+  Switch:   edit spexcode.local.json  ({ "private": true } on / false or remove = off), then \`spex materialize\`
+            (the hook gate also re-runs it on the next agent turn).
+  Reversible + idempotent: the two modes fully CANCEL OUT. default→private→default (or private→default→private)
+            converges to the SAME on-disk state as running that mode once — each mode re-asserts the inverse of
+            the other (exclude block ⇄ .gitignore block, skip-worktree set ⇄ cleared). Switch order never
+            matters; running a mode twice changes nothing.
+
+MANUAL STEP (the only one materialize can't do for you — it also PRINTS this when needed):
+  .git/info/exclude hides UNTRACKED paths only. If you adopted DEFAULT mode first, .spec + spexcode.json are
+  already committed, so private mode can't hide them until you un-track them ONCE:
+      git rm -r --cached .spec spexcode.json     # keeps the files on disk, stops tracking them
+  (then commit that on your branch). A private-from-the-start adoption never needs this.
+
+FOOTGUN (skip-worktree): a host-tracked CLAUDE.md/AGENTS.md is skip-worktree'd in private mode, so a later
+  \`git pull\` that touches it can complain. Fix: flip back to DEFAULT mode (or \`git update-index
+  --no-skip-worktree CLAUDE.md AGENTS.md\`), pull, then re-materialize.`
+
+const TOPICS: Record<string, string> = { spec: SPEC, yatsu: YATSU, config: CONFIG }
+
+// 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.
+const FOOTER = `\n\n(This is the skill layer. Command usage: \`spex help\` for the map, \`spex help <command>\` for one command.)`
 
-export function guideText(topic?: string): string {
-  if (!topic) return SETUP
+// null = unknown topic: the caller fails loud (exit non-zero) while still naming the layers to go
+// back to — an unknown topic must never read as a successful page ([[cli-surface]]'s dead-end rule).
+export function guideText(topic?: string): string | null {
+  if (!topic) return SETUP + FOOTER
   const t = TOPICS[topic]
-  if (t) return t
-  return `spex guide: no topic '${topic}'. Topics: spec, yatsu. Run \`spex guide\` (no topic) for the setup workflow.`
+  return t ? t + FOOTER : null
 }

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

@@ -0,0 +1,63 @@
+import { HARNESSES, type Harness, type HarnessId } from './harness.js'
+
+// @@@ harness-select - the DECLARATIVE choice of WHICH harness targets `spex materialize` delivers the
+// SpexCode system into. The selection is persistent config (spexcode.json's `harnesses`), NOT a one-shot
+// flag, because materialize is driven by a content-hash gate (re-run on every .config edit), so the intent
+// must live where every re-materialize can read it. This module owns ONLY the vocabulary + validation; the
+// per-harness write/clean mechanics live on the [[harness-adapter]], the render loop on [[harness-delivery]].
+
+// a resolved DELIVERY TARGET. Either a NATIVE harness (claude/codex — its adapter writes shims/contract/trust
+// directly), or a PLUGIN bundle dropped into a host-agent-scanned folder. The plugin EMITTER is a later node;
+// here a plugin target is only validated, it produces no artifact yet.
+export type HarnessTarget =
+  | { kind: 'native'; id: HarnessId }
+  | { kind: 'plugin'; folder: string }
+
+// the zero-config default: deliver to EVERY native harness, no plugin.
+export const DEFAULT_HARNESS_IDS: readonly HarnessId[] = HARNESSES.map((h) => h.id)
+const KNOWN: readonly string[] = HARNESSES.map((h) => h.id)
+
+// parse + validate the spexcode.json `harnesses` field into resolved targets. FAIL LOUD on an illegal set —
+// materialize and init both gate on this so a bad config never silently delivers the wrong thing. `raw` is the
+// JSON value as written; undefined/null → the default native set.
+export function resolveHarnessTargets(raw: unknown): HarnessTarget[] {
+  if (raw === undefined || raw === null) return DEFAULT_HARNESS_IDS.map((id) => ({ kind: 'native', id }))
+  if (!Array.isArray(raw))
+    throw new Error(`spexcode.json "harnesses" must be an ARRAY of targets (got ${typeof raw}). Members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}; omit the field to default to [${DEFAULT_HARNESS_IDS.join(', ')}].`)
+  if (raw.length === 0)
+    throw new Error(`spexcode.json "harnesses" is EMPTY — list at least one target, or remove the field to default to [${DEFAULT_HARNESS_IDS.join(', ')}].`)
+  const targets: 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.`)
+      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.`)
+      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)}.`)
+    }
+  }
+  // PLUGIN EXCLUSIVITY: a plugin bundle is a SUPERSET delivery to its host agent, so pairing it with any
+  // native harness double-delivers. So a set with a plugin may carry NO native harness.
+  const natives = targets.filter((t): t is { kind: 'native'; id: HarnessId } => t.kind === 'native')
+  if (targets.some((t) => t.kind === 'plugin') && natives.length)
+    throw new Error(`spexcode.json "harnesses": a plugin target is EXCLUSIVE — it cannot coexist with native harnesses (${natives.map((t) => t.id).join(', ')}). A plugin bundle already delivers the whole system to its host agent, so pairing it with a native harness double-delivers. Choose EITHER native harnesses OR plugin target(s).`)
+  return targets
+}
+
+// split the live HARNESSES adapters by whether the resolved targets SELECT them: selected get write()n,
+// unselected get clean()ed (pruned). `plugins` carries the plugin targets (no emitter yet — a later node).
+export function partitionHarnesses(targets: HarnessTarget[]): { selected: Harness[]; unselected: Harness[]; plugins: { folder: string }[] } {
+  const selectedIds = new Set(targets.filter((t) => t.kind === 'native').map((t) => (t as { id: HarnessId }).id))
+  return {
+    selected: HARNESSES.filter((h) => selectedIds.has(h.id)),
+    unselected: HARNESSES.filter((h) => !selectedIds.has(h.id)),
+    plugins: targets.filter((t) => t.kind === 'plugin').map((t) => ({ folder: (t as { folder: string }).folder })),
+  }
+}