spexcode 0.1.6 → 0.2.1

package/spec-cli/src/guide.ts

@@ -3,9 +3,13 @@ const SETUP = `spex guide — run SpexCode on your own repo
 The product model: install SpexCode ONCE, then use it across all your projects — an agent drives
 the rest, you don't hand-author the spec tree or wire the dashboard yourself.
 
-1. Install the CLI (one-time, global — this ONE checkout serves every project)
-     cd spec-cli && npm install && npm link      # \`spex\` now runs from ANY directory
+1. Install the CLI (one-time, global — ONE install serves every project)
+     npm i -g spexcode                           # ONE command lands on PATH: \`spex\` (Node ≥ 22)
    It always operates on the repo of your current directory — that cwd is the only "which repo" knob.
+   (Dogfooding an unpublished HEAD from a source checkout? \`npm link\` at the repo ROOT — that links
+   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 source link ships no
+   prebuilt dashboard dist — \`spex dashboard\` needs a manual dashboard build, or use the dev server.)
 
 2. Adopt a repo
      cd <your-repo> && spex init                 # seeds .spec/ + git hooks (additive, never overwrites)
@@ -17,19 +21,21 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
    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
-     cd spec-dashboard && npm install                        # once
-     API_URL=http://localhost:<port> npm run dev             # point this board at step 3's backend
-   The board is a viewer: API_URL is how the shared install points at each project (one dev-server
-   per project). "dashboard": { "apiUrl": "..." } in spexcode.json is the default ONLY when the board
-   lives inside the project (the dogfood layout) — for a shared install, use API_URL.
+     spex dashboard                              # serves the bundled board 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.
+   (Dogfood/source alternative: API_URL=http://localhost:<port> npm run dev in spec-dashboard —
+   the dev server; "dashboard": { "apiUrl": "..." } in spexcode.json applies only to that layout.)
 
 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).
 
-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 +57,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 +98,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 +114,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 +146,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 })),
+  }
+}