spexcode 0.4.0 → 0.4.3

package/spec-cli/src/guide.ts

@@ -5,35 +5,35 @@ the rest, you don't hand-author the spec tree or wire the dashboard yourself.
 
 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.
+   Project-scoped commands operate on the repo of your current directory; the dashboard is host-scoped.
    (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 legacy link of the
-   inner package uninstalls as \`@spexcode/spec-cli\`). A source link ships no
-   prebuilt dashboard dist — \`spex serve ui\` builds it once on first run (needs spec-dashboard's
-   npm deps installed), or use the dev server.)
+   inner package uninstalls as \`@spexcode/spec-cli\`). Contributors run \`npm run api\` and
+   \`npm run web\` from the source root for backend reloads and Vite/HMR; those are not installed-user
+   startup commands.)
 
 2. Adopt a repo
-     cd <your-repo> && spex init                 # seeds .spec/ + git hooks (additive, never overwrites)
+     cd <your-repo> && spex init --harness claude,codex,opencode,pi   # seeds .spec/ + git hooks (additive, never overwrites)
+   --harness is required and has no default — the explicit choice of which harness(es) materialize
+   delivers into. The example lists every built-in; drop the ones you don't use (any one id or
+   comma-separated subset is valid).
    Works on any git repo. Edit .spec/project/spec.md to describe it, then grow child nodes
    (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
+3. Run this repo's backend — it reads .spec + git from cwd and registers in this user's host registry
      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 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 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).
-   (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.)
+   Run one \`spex serve\` from every project you want online. Give each additional backend a free
+   --port; the port only binds that backend and is never paired with a dashboard process.
+
+4. Open the shared host dashboard — run this ONCE for the current user, from any directory
+     spex dashboard                             # host gateway + UI on http://localhost:5173
+   It discovers backends already running and any that start later. \`/projects\` is the global project
+   switcher and management surface; each project's dashboard lives under \`/p/:id/\`. The gateway is
+   loopback-only by default; \`--host\` widens its bind as described by \`spex dashboard --help\`.
 
 5. Govern your layout (optional)
-     spexcode.json sets lint's governedRoots/sourceExtensions and any non-default worktree layout.
+     spexcode.json sets lint's governedRoots/include/exclude/test source policy and any non-default layout.
      \`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:
@@ -62,13 +62,27 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            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.
-           The entry may pin ONE named unit — an ANCHOR: \`path#symbol\` (\`#Class.method\` for a class
-           method; top-level functions, arrow/const declarations, classes, enums anchor cleanly; a
-           type/interface anchor warns). An anchor upgrades drift on THAT unit to a blocking error
-           (\`anchor-drift\`); without one, drift stays advisory forever. Anchors are optional.
+           The entry may pin named units — ANCHORS: one or more \`path#symbol\` rows, ALL on the same
+           base file (\`#Class.method\` for a class method; top-level functions, arrow/const declarations,
+           classes, enums anchor cleanly; a type/interface anchor warns). One-govern counts DISTINCT
+           base paths, so selectors never widen govern past one file. Several selectors are OR: a
+           commit hitting ANY upgrades drift to the blocking \`anchor-drift\` error (one error per
+           entry, naming the hit selectors — a commit counts once). Without an anchor, drift stays
+           advisory forever. A base path is either whole-file (bare) or selector-scoped, never both;
+           duplicates, globs/directories with a selector, and dead/ambiguous units all error loud. A
+           selector-scoped governor claims units, not the file, so it stays out of the \`owners\` bound
+           (spex spec owner still displays it, marked "(scoped)"). Anchors are optional.
+           Python \`.py\`/\`.pyi\` anchors recognize structural \`def\`, \`async def\`, and \`class\`
+           declarations. Methods and nested declarations use lexical qualified names such as
+           \`Class.method\`, \`outer.inner\`, or \`Outer.Inner.method\`; attached decorators belong to
+           the declaration's range. Runtime-created/assigned callables, imported aliases, and generated
+           names are outside this declaration extractor and therefore resolve as dead anchors.
   related: files this node REFERENCES but does not own — a YAML list, same path forms. Carries coverage
            (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).
+           govern doesn't. Every listed path must exist (lint integrity error otherwise). A related row
+           may also pin \`path#symbol\`: the node then hears about a commit ONLY when it moves that
+           unit — a hit is a soft \`related-drift\` warn naming the selector, a miss is SILENT (a scoped
+           related file's ordinary file-level nudge is off). Still never blocks, no ack, no eval freshness.
   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
@@ -92,11 +106,14 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
                       deleted/renamed), an ambiguous one (two same-named units in one file), a file that
                       no longer parses, a language with no designated extractor, or an extractor that
                       can't run here (e.g. no host typescript — 'npm i -D typescript' or drop the anchor)
-                      all error, never silently pass.
-  anchor-drift (error) a commit since the node's version intersected the ANCHORED unit's lines (judged
+                      all error, never silently pass. So do a relation's STRUCTURAL defects: a duplicate
+                      entry, a base path both bare and selector-scoped, or a selector on a
+                      glob/directory.
+  anchor-drift (error) a commit since the node's version intersected an ANCHORED unit's lines (judged
                       from the file as it existed AT each commit) and no Spec-OK ack covers it — the
-                      blocking tier of drift. Remedy: update the spec, or \`spex spec ack\` with a real
-                      reason (recorded in the ack commit body).
+                      blocking tier of drift. Selectors on one file are OR'd: one error per entry, the
+                      hit selectors named, each commit counted once. Remedy: update the spec, or
+                      \`spex spec ack\` with a real reason (recorded in the ack commit body).
   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.
@@ -104,31 +121,36 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
                       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.
                       ALWAYS advisory: unanchored drift never blocks a commit (the blocking tier is
-                      anchor-drift above). 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.
+                      anchor-drift above). On a selector-SCOPED code file whose window has NO hit (a
+                      miss), this advisory stays by default; the committed \`lint.scopedCodeMiss:
+                      "ignore"\` silences ONLY it (hit blocks, bare drift, integrity, acks, related,
+                      eval freshness all untouched). 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.
   anchor     (warn)   an anchor pins a type/interface — types reshape with every refactor; anchor the
                       behaviour-bearing unit instead.
-  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).
+  related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never
+                      blocks. A selector-scoped related row instead warns per HIT (selector named);
+                      its file-level misses are silent.
+  owners     (warn)   a file governed WHOLE-FILE 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). Selector-scoped governors don't count toward the bound.
   confusable-id (warn) two leaf ids one edit apart read as the same word — rename one to read apart.
 
+Heuristic spec health is deliberately outside this production gate. Bare \`spex doctor\` reports opt-in
+altitude and breadth findings; the tidy workflow consumes that report and adds semantic judgment.
+
 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 eval.md is
+behaviour and the spec. It is optional, but a node that governs a file admitted by lint's shared tracked-text
+include-minus-exclude/test policy 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.
 
@@ -141,8 +163,13 @@ FRONTMATTER: a \`scenarios:\` list (a YAML block sequence of mappings). Each sce
                \`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 — eval never executes it.
+  test         optional. Either a repo-path scalar (the backward-compatible shorthand) or a strict object:
+                 test:
+                   path: tests/auth.spec.ts
+                   name: rejects an expired session
+               Both forms normalize in JSON to \`{ "path": "..." }\` with optional \`"name"\`. The object
+               requires exactly \`path\` + \`name\`; its case name is opaque text preserved for the measuring
+               hand. The path must exist. SpexCode does not parse WDIO/Playwright or execute anything.
   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
@@ -187,7 +214,12 @@ PICK THE EVIDENCE KIND BY WHAT THE BEHAVIOUR DOES OVER TIME:
                       CLI harness stamping line numbers — take a baseline and at EACH real step push
                       \`{ at: <position>, step: "…" }\`; dump that array as \`--timeline\`. Its \`axis\` MUST match the
                       evidence it rides (a \`line\` map needs a \`--result\` transcript, a \`time\` map a \`--video\`);
-                      skip it for a short single-step artefact. (Legacy \`{ "v": 1, "events": [{ "tMs" }] }\` — the
+                      skip it for a short single-step artefact. A step name is a SHORT human label for its
+                      moment ("open graph") — never a metadata channel: the run's identity, its verdict, and
+                      the evidence's extent already have canonical homes (the scenario's \`test:\` field, the
+                      measurement's --pass/--fail, the artefact itself), so a step like
+                      "runner start: path/to/spec.ts :: <full case title>" smuggles data the measurement already
+                      carries and turns the step ruler into noise. (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 tool's
@@ -222,23 +254,26 @@ code file or the scenario (the eval.md) moves since it was filed.
 
 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
+SpexCode reads PROJECT runtime settings from TWO optional JSON files at the repo root. There is no imperative
 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
-                        identity, lint budgets, launcher NAMES. "Git is the database": tracked so the
+                        identity, lint policy, doctor health 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. Layered OVER spexcode.json (see MERGE
                         below); a targeted env override (SPEXCODE_CODEX_SERVER_CMD, …) still wins 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
+icon, lint policy, doctor health budgets, and 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 session new\` or the dashboard without an explicit launcher choice.
 
+The host-wide gateway has one separate per-user setting, \`gateway.icon\` in
+\`$SPEXCODE_HOME/config.json\`. It is documented below and never belongs to either project file.
+
 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)
@@ -254,13 +289,23 @@ 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.icon    the project's icon identity. The Projects UI writes one shared preset id:
+                    spexcode | gateway | mdi:rocket-launch | compass | terminal | package | database | spark.
+                    Existing emoji ("🔭"), arbitrary Iconify names ("lucide:radar"), and full URLs remain
+                    supported; picking a preset migrates that one existing field, never creates another.
   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" } }
 
+── HOST GATEWAY ($SPEXCODE_HOME/config.json — per-user host identity, never a project file) ──
+  gateway.icon      the global /projects icon, using the same preset ids above. Default: "gateway".
+                    The admin-only Projects picker writes this field atomically. It is the gateway's ONE
+                    authored icon setting and is never copied into spexcode.json or spexcode.local.json.
+Example:
+  { "gateway": { "icon": "database" } }
+
 ── SESSIONS / WORKERS ──
   sessions.maxActive        concurrency cap — max agents AUTONOMOUSLY PROGRESSING at once (default 8;
                             precedence: spexcode.json → SPEXCODE_MAX_ACTIVE env → default; read live, so
@@ -268,8 +313,8 @@ Example:
                             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.launchers        the NAMED launcher profiles (see LAUNCHERS). \`spex init\` seeds "claude" and
-                            "codex" here as ordinary entries; edit/add more like any other.
+  sessions.launchers        the NAMED launcher profiles (see LAUNCHERS). \`spex init\` seeds one entry per
+                            SELECTED harness (--harness); edit/add more like any other.
   sessions.defaultLauncher  the launcher name a create with no explicit --launcher/dropdown pick uses
                             (required for no-choice creates). A portable NAME → committed.
 A launcher \`cmd\` that is a HOST-SPECIFIC ABSOLUTE PATH belongs in spexcode.local.json — the committed file
@@ -278,18 +323,24 @@ 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 with --launcher/the dashboard dropdown, and the chosen name is persisted on the record so a resume
-reuses the same auth. There are NO magic built-ins: \`spex init\` SEEDS "claude" and "codex" as ordinary
-named launchers,
-  "claude" → { "harness": "claude", "cmd": "claude --dangerously-skip-permissions" }
-  "codex"  → { "harness": "codex",  "cmd": "codex --yolo" }
-after which they are edited (or removed) exactly like any launcher you add. To run workers under an auth
+reuses the same auth. There are NO magic built-ins: \`spex init\` SEEDS an ordinary named launcher for each
+harness the adopter SELECTED (--harness), from the template pool
+  "claude"   → { "harness": "claude",   "cmd": "claude" }
+  "codex"    → { "harness": "codex",    "cmd": "codex" }
+  "opencode" → { "harness": "opencode", "cmd": "opencode" }
+  "pi"       → { "harness": "pi",       "cmd": "pi" }
+These plain commands preserve each harness's normal permission model. Automatic-permission commands such as
+\`claude --dangerously-skip-permissions\`, \`codex --yolo\`, or \`opencode --auto\` are NEVER clean-init
+defaults: define and select one explicitly only when that access is intended. To run workers under an auth
 wrapper (e.g. reclaude), point a launcher's \`cmd\` at it in spexcode.local.json — there is no environment
-override that rewrites a launcher's command. Add more profiles when a project needs named auth/config-dir
-variants. 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:
+override that rewrites a launcher's command. Add more profiles when a project needs named auth/config-dir or
+permission variants. Shape:
+  "launchers": { "<name>": { "harness": "claude" | "codex" | "opencode" | "pi",
+                             "cmd": "<launch command>" } }
+\`harness\` defaults to "claude"; \`cmd\` is required and embedded whole. A portable plain command may live
+in committed spexcode.json (as the init seeds do). A host-specific command — an absolute wrapper path,
+credential route, or personal permission choice — belongs in gitignored spexcode.local.json, while its
+portable defaultLauncher NAME may stay in committed spexcode.json; the merge keeps both:
 
   spexcode.json  (committed — the portable name reference)
   { "sessions": { "defaultLauncher": "gpt5" } }
@@ -321,9 +372,11 @@ resolves its backend per this ladder, flag first:
                              sugar for --api http://127.0.0.1:<n>).
   2a. worker (SPEXCODE_SESSION_ID set): env SPEXCODE_API_URL — the backend-injected lifeline; cwd
                              discovery never steals it.
-  2b. human (no session id): the cwd project's RECORDED live backend — \`spex serve\` records {url,pid}
-                             in ~/.spexcode/projects/<enc>/backend.json at bind time; the reader
-                             health-probes before trusting (a dead record is ignored).
+  2b. human (no session id): the cwd project's RECORDED live backend — \`spex serve\` publishes
+                             {url,pid,instanceId,root} atomically to ~/.spexcode/projects/<enc>/backend.json
+                             at bind time; the reader health-probes before trusting (a dead record is
+                             ignored). The same record is what \`spex dashboard\` reconciles its
+                             host-wide project list from.
   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/resume/stop) refuses
@@ -348,26 +401,52 @@ the guard (the flag is the declaration of intent). Reads point anywhere.
   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.maxOwners           warn when a file is governed by > this many nodes (default 3).
+  lint.sourceIncludeGlobs  optional repo-relative includes. Omit = ALL tracked current regular text under
+                           governedRoots; [] = intentionally none. Slash-less globs match at any depth.
+  lint.sourceExcludeGlobs  repo-relative paths subtracted from the includes (default []). Nothing about
+                           docs/vendor/build/config is guessed: exclude it here when that is project policy.
+  lint.sourceExtensions    compatibility shorthand compiled into include globs (".py" → "**/*.py") and
+                           unioned with sourceIncludeGlobs; it has no separate matching path.
+  lint.testGlobs           globs EXCLUDED from coverage. Defaults cover .test/.spec names, test/tests/
+                           directories, and test_* / *_test conventions; [] governs tests too.
+  lint.maxOwners           warn when a file is governed WHOLE-FILE by > this many nodes (default 3).
+                           Selector-scoped governors (code: path#symbol) don't count toward the bound.
                            (lint.driftErrorThreshold is RETIRED: the count-based commit gate is replaced
                            by code anchors — \`code: path#symbol\` — whose hits error unconditionally; a
                            leftover key is ignored.)
+  lint.scopedCodeMiss      "warn" (default) | "ignore" — the file-level drift ADVISORY on a selector-
+                           scoped code: file whose window commits hit no selector (a miss). "ignore"
+                           silences ONLY that advisory; it never touches hit blocks (anchor-drift),
+                           bare-path drift, integrity, Spec-OK acks, related semantics, or eval
+                           freshness. A project policy → committed spexcode.json.
   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 } } }
+Example — govern your own source dir:
+  { "lint": { "governedRoots": ["src"] } }
+Example — declare project-specific exclusions (nothing is guessed from these names):
+  { "lint": { "governedRoots": ["."], "sourceExcludeGlobs": ["vendor/**", "dist/**", "docs/**"] } }
+Migration: \`lint.maxChildren\` is RETIRED and no longer read; move its value to
+  \`doctor.breadth.maxChildren\`. Bare \`spex doctor\` flags a stale key.
+
+── DOCTOR HEALTH (spexcode.json — portable advisory-diagnosis budgets) ──
+  doctor.altitude         the one altitude proxy config consumed by bare \`spex doctor\`:
+                          { lineBudget, charBudget, sizeable, dense, steps, identifierExtensions }
+                          Defaults: 50 / 4200 / 35 / 1.3 / 3 / []. Exact filename signals derive from
+                          lint's tracked source candidates; identifierExtensions adds compatibility wildcard
+                          rows (".legacy" → "*.legacy") to that same matcher.
+  doctor.breadth          the one tree-breadth hypothesis consumed by bare \`spex doctor\`:
+                          { maxChildren }. Default: 8. Reports each affected node's direct child count and
+                          points to the regroup workflow; genuine flat peers may remain flat.
+Example — tune opt-in health diagnosis without changing the lint gate:
+  { "doctor": { "altitude": { "lineBudget": 70 }, "breadth": { "maxChildren": 10 } } }
 
 ── OTHER (spexcode.json unless noted) ──
   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
+  harnesses   which harness targets \`spex materialize\` delivers into — native ids
+              ("claude"|"codex"|"opencode"|"pi") or a
+              { "plugin": "<folder>" } bundle. REQUIRED — there is no default set: \`spex init --harness\`
+              stamps the explicit choice, and a missing field fails materialize loud. PERSISTENT and
               git-transactional: the edit takes effect at the next git-native materialize anchor (the commit
               that carries it, a checkout/merge that receives it, or a manual \`spex materialize\`) — a
               deselected harness's artifacts are pruned by that pass.`
@@ -376,9 +455,11 @@ 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,
-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
+stitches the two ends into a closed loop. Materialize is the base operation of harness ADAPTATION:
+one pass renders the spec tree into whatever artifacts the selected harness auto-discovers, so that
+is how SpexCode reaches an agent — never a launch-time flag. The footprint follows: the head+tail
+(.spec, spexcode.json, 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) ──

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

@@ -13,19 +13,33 @@ 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)
+// the native vocabulary (for messages and init's flag parsing). There is NO default set: the delivery
+// targets are an explicit adopter choice, stamped by `spex init --harness` and read back from config forever.
+export const NATIVE_HARNESS_IDS: readonly HarnessId[] = HARNESSES.map((h) => h.id)
 const KNOWN: readonly string[] = HARNESSES.map((h) => h.id)
 
+// the one-line repair every missing-selection error carries — the field is REQUIRED, never defaulted,
+// because with many harnesses a silent "deliver everywhere" would litter the adopter's tree with artifacts
+// for tools they never installed.
+const MISSING = `spexcode.json has no "harnesses" field — the delivery targets are an EXPLICIT choice, never a default. Declare it, e.g. "harnesses": ["claude"] — members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}. Fresh adoption: \`spex init --harness <ids>\` stamps it.`
+
+// parse `spex init --harness <spec>` into the raw JSON members the `harnesses` field carries: a comma-
+// separated list where `plugin:<folder>` means a plugin target and anything else is a native id. Pure
+// spelling translation — legality (unknown ids, plugin exclusivity) stays with resolveHarnessTargets.
+export function parseHarnessFlag(spec: string): unknown[] {
+  return spec.split(',').map((s) => s.trim()).filter(Boolean)
+    .map((s) => (s.startsWith('plugin:') ? { plugin: s.slice('plugin:'.length) } : s))
+}
+
 // 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.
+// JSON value as written; a MISSING field is itself illegal (the choice must exist, stamped by init).
 export function resolveHarnessTargets(raw: unknown): HarnessTarget[] {
-  if (raw === undefined || raw === null) return DEFAULT_HARNESS_IDS.map((id) => ({ kind: 'native', id }))
+  if (raw === undefined || raw === null) throw new Error(MISSING)
   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(', ')}].`)
+    throw new Error(`spexcode.json "harnesses" must be an ARRAY of targets (got ${typeof raw}). Members are native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`)
   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(', ')}].`)
+    throw new Error(`spexcode.json "harnesses" is EMPTY — list at least one target: native ids (${KNOWN.join(', ')}) or {"plugin":"<folder>"}.`)
   const targets: HarnessTarget[] = []
   for (const m of raw) {
     if (typeof m === 'string') {