spexcode 0.4.0 → 0.4.3

package/spec-cli/src/help.ts

@@ -14,7 +14,8 @@
 type Entry = { line: string; body: string; see?: string }
 
 const SEL_NOTE = `SEL = session id (or unique id-prefix) | node id | branch — every session read/control verb
-accepts any of the three; on the list verbs (ls/watch), none (or @all) means every session.`
+accepts any of the four; inside a session worktree, . means that worktree's session. On the list verbs (ls/watch),
+none (or @all) means every session.`
 
 const ROUTING_NOTE = `Backend routing: every backend-touching verb accepts --api <url> (--port <n> = localhost sugar) to name
 its backend explicitly — the flag always wins. Bare, it resolves: worker env / the cwd project's live
@@ -24,9 +25,9 @@ const DOT_NOTE = `\`.\` as a node argument means the node THIS worktree works on
 node/<id> branch). One-shot payload reads (graph · spec search · session ls/show/review · eval ls ·
 scenario ls · issue ls/show/links) take --json.`
 
-const MENTION_NOTE = `Mentions: @session · [[node]] · @new work in ANY prompt, issue, or remark body — text passed as a CLI
-arg included. [[node]] names the topic node; @session hands the text to that live agent; @new spawns a
-fresh worker on the thread's node.`
+const MENTION_NOTE = `Mentions: @session · [[node]] · @new / @new:<launcher> work in ANY prompt, issue, or remark body —
+text passed as a CLI arg included. [[node]] names the topic node; @session hands the text to that live agent;
+@new spawns a fresh worker on the thread's node (bare = configured default; :<launcher> = that named profile).`
 
 const ENTRIES: Record<string, Entry> = {
   // ── project verbs (implicit object = this project) ────────────────────────
@@ -44,47 +45,53 @@ derived status, title, and attention badges (drift:N · stale:N · issues:N · g
     see: 'spex spec search (find one node by intent) · spex session ls (just the sessions, as a table)',
   },
   init: {
-    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
-    body: `Usage: spex init [dir=cwd] [--preset default]
+    line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  --harness <ids> [--preset name]',
+    body: `Usage: spex init [dir=cwd] --harness <id[,id]|plugin:<folder>> [--preset default]
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
-shims). Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
+shims). --harness is REQUIRED — the explicit choice of which harnesses materialize delivers into
+(stamped as spexcode.json "harnesses"; only their launchers are seeded); a pre-existing "harnesses"
+field satisfies it. Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
 Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
 a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
     see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
   },
   materialize: {
-    line: 'materialize           re-materialize the harness artifacts (contract block · shims) for cwd’s project',
+    line: 'materialize           the base pass of harness adaptation: render .spec/.plugins into your harness’s artifacts',
     body: `Usage: spex materialize
 
-Materializes the surface:system plugin nodes into the managed <!-- spexcode --> block of
-CLAUDE.md/AGENTS.md plus the .claude/.codex shims, and prints the content hash. The materialize anchors on
-git-native events only (init · this verb · session-worktree creation · the pre-commit/post-checkout/
-post-merge hooks) — run it by hand after a toolchain update, or in the setup step of any clone that
-has no spex-planted hooks yet (CI, a cloud agent): the artifacts are generated and excluded, so they
-never arrive via git.`,
+The base operation of HARNESS ADAPTATION: one pass renders the spec tree's surface nodes into the
+artifacts each selected harness auto-discovers — the managed <!-- spexcode --> block of
+CLAUDE.md/AGENTS.md, the .claude/.codex shims, the skills/agents — and prints the content hash.
+The outputs are derived and never tracked: to change one, edit its source (.plugins, spexcode.json)
+and re-materialize — never the artifact. Not a one-time setup: it anchors on git-native events
+(init · this verb · session-worktree creation · the pre-commit/post-checkout/post-merge hooks) —
+run it by hand after a toolchain update, or in the setup step of any clone that has no spex-planted
+hooks yet (CI, a cloud agent): generated and excluded, the artifacts never arrive via git.`,
     see: 'spex doctor (verify the materialized artifacts actually reach an agent)',
   },
   doctor: {
-    line: 'doctor                diagnose whether the workflow actually reaches this agent  [--contract|--conflicts]',
-    body: `Usage: spex doctor                per-layer coverage report: preconditions · git-hook floor · contract ·
-                                  hooks + handler existence · backend — for every harness materialize delivers to
+    line: 'doctor                diagnose spec health and whether the workflow reaches this agent  [--contract|--conflicts]',
+    body: `Usage: spex doctor                spec-health findings + delivery report: preconditions · git-hook floor ·
+                                  contract · hooks + handler existence · backend · footprint
        spex doctor --contract     print the composed surface:system text any agent here reads
        spex doctor --conflicts    detect double-delivery (loose artifacts beside the managed ones)
 
-Run it when a worker seems to be missing its contract or hooks — it names the broken layer and the
-repair, instead of you diffing materialized files by hand.`,
-    see: 'spex materialize (re-materialize the artifacts doctor checks)',
+Bare doctor is the opt-in, read-only health surface: it reports altitude and breadth findings without
+putting them in the lint gate, then audits workflow delivery. Run it directly or let the tidy workflow
+consume the same visible diagnosis.`,
+    see: 'spex spec lint (deterministic graph/contract gate) · spex materialize (repair delivery artifacts)',
   },
   uninstall: {
-    line: 'uninstall [dir]       surgical inverse of init — removes generated artifacts, keeps your .spec  [--hooks]',
+    line: 'uninstall [dir]       remove all derived artifacts + local state; preserve tracked intent  [--hooks]',
     body: `Usage: spex uninstall [dir=cwd] [--hooks]
 
-Removes every SpexCode-GENERATED artifact (harness shims · contract blocks · trust entries ·
-exclude/ignore blocks · global store · plugin bundle) and never your .spec/.plugins data or your own
-prose. Git hooks are preserved unless --hooks.`,
-    see: 'spex init (re-adopt later — your .spec survives)',
+Removes all SpexCode-derived wiring and project-local state: contract blocks, harness shims,
+generated skills/agents, plugin bundles, trust/filter/exclude entries, and the global per-project
+store. Your tracked intent (.spec including .plugins, plus spexcode.json) and surrounding user prose
+are preserved. Git hooks remain unless --hooks; that flag removes only unmodified canonical copies.`,
+    see: 'spex init (re-adopt later — your tracked intent survives)',
   },
   serve: {
     line: 'serve [api|ui]        api (default) = the backend :8787 · ui = the dashboard :5173 on top of it',
@@ -104,6 +111,30 @@ projects coexist on one host). Loopback-only by default; --host 0.0.0.0 opens it
 still plain HTTP with no gate, so bind wide only on a network you trust.`,
     see: 'GET /health (backend liveness probe)',
   },
+  dashboard: {
+    line: 'dashboard             ONE dashboard for every project you serve — no --api-port pairing  [--port N=5173]',
+    body: `Usage: spex dashboard [--port N=5173] [--host H=127.0.0.1]
+
+The HOST gateway: serves the built dashboard once and routes to EVERY backend the current user runs —
+the multi-project hub engine plus the host registry on top. It continuously reconciles the per-project
+endpoint records each \`spex serve\` publishes (validating each against the live backend's /api/instance
+identity), keeps a durable known-project catalog, and proxies each project's API + SSE + terminal
+socket under /p/<projectId>/* — the project is named in the path, so nothing is "current" and no
+pairing flag exists.
+
+Admin surface (hub-authorized: implicit from loopback until an admin password is set, then cookie
+sessions): GET /projects (the validated list + gating state) · GET /projects/stream (SSE) ·
+GET /projects/browse?path=… (read-only host folder picker) · POST /projects {root, initGit?, init?}
+(explicit setup, then register) · GET|PUT /projects/<id>/config (raw portable
+spexcode.json, revision-guarded) · POST /projects/<id>/init|doctor|serve
+(run the real \`spex init\`/\`spex doctor\`, or start an offline project's backend, detached — a
+backend never depends on this gateway staying up) · PUT|DELETE /projects/admin-password and
+/projects/<id>/password (the gates). A gated project answers /p/<id>/login with the designed page.
+
+Loopback-only by default; --host widens the bind — the admin surface stays locked to loopback until
+an admin password exists, and ungated projects serve open.`,
+    see: 'spex serve (each project\'s backend) · spex serve ui (explicit one-backend pairing)',
+  },
 
   // ── the noun drawers ──────────────────────────────────────────────────────
   spec: {
@@ -122,14 +153,18 @@ owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval fr
 over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).
 
 lint — checks the whole spec↔code graph and exits non-zero on errors. Errors: integrity (a
-code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` anchor; an anchor
-whose language has no designated extractor or whose extractor can't run here) · anchor-drift (a
-commit since the spec's version touched the ANCHORED unit's lines, unacked — the blocking tier of
-drift) · one-govern (a node governs >1 file) · living (a "## vN" changelog heading) · id-format (an
+code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` selector; a selector
+whose language has no designated extractor or whose extractor can't run here; a duplicate entry, a
+base path both bare and scoped, or a selector on a glob/directory) · anchor-drift (a
+commit since the spec's version touched an ANCHORED unit's lines, unacked — the blocking tier of
+drift; same-file selectors OR'd, one error naming the hit selectors) · one-govern (a node
+governs >1 DISTINCT file) · living (a "## vN" changelog heading) · id-format (an
 id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
-leaf id reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift
-(UNANCHORED drift — always advisory, never blocks) · anchor (anchoring a type) · related-drift ·
-owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+leaf id reused) · mention (a [[id]] naming no node). Warns: coverage · drift
+(UNANCHORED drift — always advisory, never blocks; on a scoped file's MISS, \`lint.scopedCodeMiss:
+"ignore"\` may silence it) · anchor (anchoring a type) · related-drift (a scoped related row warns
+per selector HIT, misses silent) · owners (whole-file governors only; scoped don't count) ·
+confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
 contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
@@ -141,10 +176,10 @@ edit the spec instead — same commit as the code.`,
   session: {
     line: 'session <verb>        the worktree state machine: new · ls · watch · wait · review · merge · send · …',
     body: `Manager verbs (dispatch, monitor, land):
-  spex session new "<prompt>" [--prompt-file <path>|-] [--node <id>] [--launcher <name>]
+  spex session new "<prompt>" [--prompt-file <path>|-] [--launcher <name>]
       Launch a worker in its own node worktree. Give it ONLY its task — the dev-flow contract
-      reaches it through the materialized system prompt. --node (or the prompt's first [[id]],
-      same effect) binds the session to that node. --prompt-file <path>|- carries a long prompt
+      reaches it through the materialized system prompt. The prompt's first [[id]] mention binds
+      the session to that node. --prompt-file <path>|- carries a long prompt
       without shell quoting (exclusive with the inline prompt). Then MONITOR it (wait/watch below).
   spex session ls [SEL…] [--status a,b] [--json]        one-shot table of living sessions
   spex session watch [SEL…] [--as NAME] [--idle] [--interval N=5]
@@ -196,15 +231,16 @@ ${MENTION_NOTE}`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · ok · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls · matrix · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
        spex eval ls --session <SEL> [--json]           a session's aggregate: its changed nodes' scores
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
+       spex eval matrix <launcher> [--node <id>] [--rows k1,k2]   the harness live-behavior matrix
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
-       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest reading
+       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest measurement
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
        spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache
 
@@ -218,19 +254,25 @@ ls — node-scoped bare (its per-scenario eval history); session-scoped with an
 ✦-marked ahead of the inherited baseline. --export writes that evaluation as ONE self-contained
 HTML artifact (diff · evidence inlined · gates) for CI/sharing.
 
-scenario ls — the DECLARED contracts (name · tags · latest verdict), no evals: bare lists every
+scenario ls — the DECLARED contracts (name · tags · normalized test reference · latest verdict), no evals: bare lists every
 measurable node's scenarios; --unmeasured keeps only the never-measured — the blind-spot worklist.
 
+matrix — run the eight-row harness live-behavior matrix against a REAL dispatched session of the named
+launcher (the harness-adapter acceptance rule, defined once in spec-eval/src/matrix.ts): it syncs the
+rows into the \`<harness>-harness\` node's eval.md scenarios, drives one worker through undeclared-stop ·
+pretooluse-block · ask-note · deliver-steer · resume · liveness · commit-gate · close-residue, and files
+a per-row measurement with its evidence transcript. A new harness needs only its launcher + spec node.
+
 lint — the measurement layer's findings: malformed eval.md (eval-schema) · unmeasured (eval-missing) ·
 stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source with no eval.md
 (eval-coverage — the same name and shape as spec lint's coverage, one rule per layer) · over-owned
 files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
 commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.
 
-ok — the human's reviewed-and-agreed mark on the scenario's LATEST reading: an appended, monotonic
-sign-off bound to that one immutable reading (a newer reading or staleness releases it on its own —
+ok — the human's reviewed-and-agreed mark on the scenario's LATEST measurement: an appended, monotonic
+sign-off bound to that one immutable measurement (a newer measurement or staleness releases it on its own —
 no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
-(an agent's judgment on a reading is a remark, never a self-blessing).
+(an agent's judgment on a measurement is a remark, never a self-blessing).
 
 retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
 deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
@@ -357,6 +399,7 @@ Project verbs (implicit object = this project)
   ${ENTRIES.doctor.line}
   ${ENTRIES.uninstall.line}
   ${ENTRIES.serve.line}
+  ${ENTRIES.dashboard.line}
 
 Noun drawers
   ${ENTRIES.spec.line}