spexcode 0.4.0 → 0.4.3

package/spec-cli/src/cli.ts

@@ -1,6 +1,6 @@
 export {} // make this a module so top-level await is allowed
 // static import is fine here: mentions.ts is dependency-free at module level, and stripRefSigil is needed
-// by several verbs (spec owner, session new, graph) — a CLI reference arg tolerates an optional @/[[ ]]
+// by several verbs (spec owner, graph, issue/eval node args) — a CLI reference arg tolerates an optional @/[[ ]]
 // sigil ([[mentions]]).
 import { stripRefSigil } from './mentions.js'
 
@@ -60,6 +60,19 @@ function positionals(from: number): string[] {
   return out
 }
 
+function rejectUnknownFlags(command: string, from: number, allowed: readonly string[]): void {
+  const known = new Set(allowed.map((name) => `--${name}`))
+  for (let i = from; i < process.argv.length; i++) {
+    const token = process.argv[i]
+    if (!token.startsWith('--')) continue
+    if (!known.has(token)) {
+      console.error(`${command}: unknown flag ${token}`)
+      process.exit(2)
+    }
+    if (VALUE_FLAGS.has(token)) i++
+  }
+}
+
 // @@@ signposts (one version only — delete in 0.4.0) - every spelling v0.3.0 removed maps to its new home.
 // A signpost REPORTS and exits 2; it never executes (not an alias): a stale hook or a human's muscle memory
 // gets a readable failure that names the migration, and nothing old keeps silently working.
@@ -73,7 +86,6 @@ const SIGNPOSTS: Record<string, string> = {
   blob: 'spex evidence put|get',
   issues: 'spex issue — ls (was: bare issues) · show · open · reply · close · promote; on|off|status → the `issues.enabled` key in spexcode.json; `issues nudge` → spex internal nudge',
   forge: 'spex issue links [--pending] [--store <host>]  (--host is now --store)',
-  dashboard: 'spex serve ui',
   new: 'spex session new',
   ls: 'spex session ls',
   watch: 'spex session watch',
@@ -173,7 +185,7 @@ async function withWatchEdge<T>(selectors: string[], intervalMs: number, body: (
 }
 
 async function resolveSelectorOrExit(selector: string): Promise<string> {
-  if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch)'); process.exit(2) }
+  if (!selector) { console.error('spex: missing session selector (id | id-prefix | node | branch | . for self)'); process.exit(2) }
   const { resolveClientSession } = await import('./client.js')
   const { sessionLabel } = await import('./sessions.js')
   const r = await resolveClientSession(selector)
@@ -309,6 +321,19 @@ if (cmd === 'serve') {
     console.error(`spex serve: unknown target '${target}' — spex serve [api] (the backend) | spex serve ui (the dashboard)`)
     process.exit(2)
   }
+} else if (cmd === 'dashboard') {
+  // the HOST-level dashboard ([[host-gateway]]): ONE gateway for every project this user serves. The
+  // engine is [[gateway-hub]] (routing + [[gateway-auth]] authorization: admin scope implicit from
+  // loopback until an admin password is set; per-project gates as configured); the host layer mounts the
+  // instance-validated project registry, its SSE stream, the durable catalog, and the /projects
+  // operations (register · init · doctor · start a backend) as the hub's admin extension. No --api-port
+  // pairing: which backend a request reaches is named in its /p/:projectId path, resolved per request.
+  // `spex serve ui` remains the explicit one-backend pairing; this verb is the zero-config many-project face.
+  const { startHostDashboard } = await import('./host.js')
+  const port = Number(flag('port') ?? process.env.SPEXCODE_DASHBOARD_PORT ?? 5173)
+  const host = flag('host') ?? '127.0.0.1'
+  if (!Number.isInteger(port)) { console.error('spex dashboard: --port must be an integer'); process.exit(2) }
+  startHostDashboard({ port, host })
 } else if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   // `spex help <cmd>` drills into one command; bare help is the map. Both name the next layer down.
   const { commandHelp, overviewHelp } = await import('./help.js')
@@ -404,7 +429,11 @@ if (cmd === 'serve') {
     const owners = specOwners(p)
     const related = specRelated(p)
     const maxOwners = loadConfig(process.cwd()).maxOwners
-    const names = (xs: { id: string }[]) => xs.map((o) => `'${o.id}'`).join(', ')
+    // a selector-SCOPED governor (every claiming code: entry carries `#symbol` — [[code-anchor]]) still
+    // DISPLAYS, marked, but does not count toward the too-many-owners bound: it claims named units, not
+    // the whole file.
+    const whole = owners.filter((o) => !o.scoped)
+    const names = (xs: { id: string; scoped?: boolean }[]) => xs.map((o) => `'${o.id}'${o.scoped ? ' (scoped)' : ''}`).join(', ')
     const relLine = related.length ? `\n  also referenced by ${names(related)} (related: coverage only — no drift, no eval freshness)` : ''
     if (owners.length === 0 && related.length === 0) {
       console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
@@ -413,16 +442,16 @@ if (cmd === 'serve') {
       // but a human asking gets the honest nuance: nothing tracks this file's drift.
       if (has('actionable')) process.exit(0)
       console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). Nothing tracks its drift; if your change is substantive, consider giving it a governing home.`)
-    } else if (owners.length <= maxOwners) {
+    } else if (whole.length <= maxOwners) {
       // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
       // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
       if (has('actionable')) process.exit(0)
-      const named = owners.map((o) => `'${o.id}'`).join(', ')
+      const named = names(owners)
       const lead = owners.length === 1 ? `${rel} is governed by ${named} — ${owners[0].desc}` : `${rel} is governed by ${named} (shared, fine).`
       console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.${relLine}`)
     } else {
-      const ids = owners.map((o) => o.id).join(', ')
-      console.log(`${rel} is governed by ${owners.length} specs (${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
+      const ids = names(owners)
+      console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
     }
   } else if (sub === 'lint') {
     const { specLint, DRIFT_GUIDANCE } = await import('./lint.js')
@@ -463,9 +492,9 @@ if (cmd === 'serve') {
   }
 } else if (cmd === 'init') {
   // scaffold a repo to adopt SpexCode: copy the shipped DATA templates (seed spec tree + git hooks)
-  // into <targetDir> (default cwd). spex init [targetDir] [--preset <tier>]
+  // into <targetDir> (default cwd). spex init [targetDir] --harness <ids> [--preset <tier>]
   const { specInit } = await import('./init.js')
-  await specInit(positionals(3)[0], flag('preset'))
+  await specInit(positionals(3)[0], flag('preset'), flag('harness'))
 } else if (cmd === 'uninstall') {
   // the surgical inverse of init: remove every SpexCode-generated artifact (harness shims/contract/trust, the
   // .gitignore block, the global store, any plugin bundle) — NEVER the user's .spec/.plugins data or their own
@@ -493,42 +522,35 @@ if (cmd === 'serve') {
     if (!r.ok) { console.error(`no evals for ${id} (status ${r.status})`); process.exit(1) }
     if (has('json')) { console.log(JSON.stringify(r.model, null, 2)); await flushExit(0) }
     const m = r.model
-    // mirror the tab's scenarioStates per node: latest reading per DECLARED scenario (evals arrive
-    // newest-first), so a retired scenario's residual reading contributes no row; the ✦ count is over
-    // these rows — the same number the tab's chip shows.
-    const groups = m.nodes.map((n) => {
-      const latest = new Map<string, (typeof n.evals)[number]>()
-      for (const e of n.evals) if (!latest.has(e.scenario)) latest.set(e.scenario, e)
-      const blind = n.scenarios.filter((s) => !latest.has(s.name))
-      const rows = n.scenarios.filter((s) => latest.has(s.name)).map((s) => latest.get(s.name)!)
-        .sort((a, b) => (Number(b.inSession) - Number(a.inSession)) || (a.ts < b.ts ? 1 : -1))
-      return { n, blind, rows }
-    })
-    const own = groups.reduce((a, g) => a + g.rows.filter((e) => e.inSession).length, 0)
-    console.log(`eval ${m.title}  [${m.id}]`)
-    console.log(`  branch : ${m.branch ?? '—'} · ${m.ahead} commit(s) ahead · ${m.dirtyNonRuntime} uncommitted`)
+    const byNode = new Map<string, any[]>()
+    for (const item of m.items) {
+      const rows = byNode.get(item.node) ?? []
+      rows.push(item)
+      byNode.set(item.node, rows)
+    }
+    const groups = [...byNode].map(([node, rows]) => ({ node, rows }))
+    const own = m.items.filter((item) => item.inSession).length
+    console.log(`eval session  [${m.id}]`)
     console.log(`  gates  : ${m.gates.map((g) => `${g.ok ? '✓' : '✗'} ${g.label} — ${g.detail}`).join(' · ')}`)
     if (own) console.log(`  ✦      : ${own} scenario(s) measured by THIS session (unmarked rows = inherited baseline)`)
-    if (!m.nodes.length) console.log('\n  no changed spec nodes — nothing to evaluate yet (empty diff)')
-    for (const { n, blind, rows } of groups) {
-      console.log(`\n${n.title}  [${n.id}]${n.uncoveredFrontend ? '  ⚠ frontend change with NO eval.md — a blind spot: give it a scenario' : ''}`)
-      for (const s of blind) console.log(`      ∅ unmeasured  ${s.name}  — declared, never measured (blind spot)`)
+    if (!m.items.length) console.log('\n  no affected scenarios to evaluate yet')
+    for (const { node, rows } of groups) {
+      console.log(`\n${node}`)
+      for (const item of rows.filter((row) => row.filterKind === 'blind')) console.log(`      ∅ unmeasured  ${item.scenario}  — declared, never measured (blind spot)`)
       let divided = false
-      for (const e of rows) {
-        if (!e.inSession && !divided && rows.some((x) => x.inSession)) { console.log(`      ── inherited baseline (other sessions' latest evals) ──`); divided = true }
+      for (const e of rows.filter((row) => row.filterKind === 'result')) {
+        if (!e.inSession && !divided && rows.some((x) => x.filterKind === 'result' && x.inSession)) { console.log(`      ── inherited baseline (other sessions' latest evals) ──`); divided = true }
         const verdict = e.verdict?.status === 'pass' ? '✓ pass' : e.verdict?.status === 'fail' ? '✗ fail' : '· unscored'
-        const stale = e.fresh ? '' : ` (stale: ${e.staleAxes.join(',')})`
+        const stale = e.fresh ? '' : ` (stale: ${(e.staleAxes || []).join(',')})`
         console.log(`    ${e.inSession ? '✦' : ' '} ${verdict}${stale}  ${e.scenario}  — ${e.ts}${e.evaluator ? ` · ${e.evaluator}` : ''}`)
       }
-      if (!n.hasEvalFile && !n.uncoveredFrontend) console.log('      (no eval.md — nothing declared to measure)')
-      else if (n.hasEvalFile && !n.scenarios.length) console.log('      (eval.md declares no scenarios)')
     }
-  } else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
+  } else if (['add', 'ls', 'scenario', 'matrix', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | lint | ok | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | matrix | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }
@@ -579,7 +601,14 @@ if (cmd === 'serve') {
   // trust, for cwd's project. Anchored on git-native events only ([[commit-surgery]]): this verb, init,
   // session-worktree creation, and the planted pre-commit/post-checkout/post-merge hooks.
   const { materialize } = await import('./materialize.js')
-  console.log(`materialized — content-hash ${materialize()}`)
+  try {
+    console.log(`materialized — content-hash ${materialize().contentHash}`)
+  } catch (e) {
+    // a policy error (e.g. a missing/illegal `harnesses` set) is a user-facing verdict, not a crash — one
+    // line + the repair it already carries, never a stack trace.
+    console.error(`spex materialize: ${(e as Error).message}`)
+    process.exit(1)
+  }
 } else if (cmd === 'doctor') {
   // @@@ doctor - the diagnosis surface ([[doctor]], né `self` — renamed: "self" read as the tool itself /
   // the global install, while the report is about THIS agent's wiring): does the materialized workflow
@@ -595,12 +624,16 @@ if (cmd === 'serve') {
   } else if (SESSION_SIGNPOSTS[sub]) {
     signpost(`spex session ${sub}`, SESSION_SIGNPOSTS[sub])
   } else if (sub === 'new') {
-    // spex session new "<prompt>" [--node X]  (prompt = first positional or --prompt, or --prompt-file
+    // spex session new "<prompt>"  (prompt = first positional or --prompt, or --prompt-file
     // <path>|- so a long multi-paragraph prompt never fights shell quoting — [[prompt-file]]).
     // createSession POSTs to the running backend so the launch runs in the backend's process (auth env + cap);
     // it falls back to an in-process launch only when no backend answers.
+    if (has('node')) {
+      console.error('spex session new: --node was removed — put a [[<id>]] mention in the prompt — the first mention binds')
+      process.exit(2)
+    }
+    rejectUnknownFlags('spex session new', 4, ['prompt', 'prompt-file', 'launcher', 'api', 'port'])
     const { createSession } = await import('./sessions.js')
-    if (has('harness')) { console.error('spex session new: --harness was removed; use --launcher <name> (for example --launcher codex)'); process.exit(2) }
     const promptFile = flag('prompt-file')
     const inline = flag('prompt') ?? positionals(4)[0]
     let prompt = inline ?? ''
@@ -612,8 +645,7 @@ if (cmd === 'serve') {
       catch (e) { console.error(`spex session new: --prompt-file ${promptFile}: ${e instanceof Error ? e.message : e}`); process.exit(2) }
       if (!prompt.trim()) { console.error(`spex session new: --prompt-file ${promptFile === '-' ? 'stdin' : promptFile} is empty — refusing a promptless launch`); process.exit(2) }
     }
-    const nodeArg = flag('node')
-    const created = await createSession(nodeArg ? stripRefSigil(nodeArg) : null, prompt, flag('launcher') ?? undefined)
+    const created = await createSession(prompt, flag('launcher') ?? undefined)
     console.log(JSON.stringify(created, null, 2))
     await launchMonitorReminder(created.id)
   } else if (sub === 'ls') {
@@ -724,7 +756,7 @@ if (cmd === 'serve') {
       // overrides for a genuinely wedged process. A following prompt is what actually re-drives it.
       const full = await resolveSelectorOrExit(id)
       const r = await c.clientResume(full, process.argv.includes('--force'))
-      if (r.ok) console.log(`${full} -> resumed`)
+      if (r.ok) console.log(r.info ? `${full} -> ${r.info}` : `${full} -> resumed`)
       else { console.error(`spex session resume: ${r.error || `no such session ${full}`}`); process.exit(2) }
     } else if (sub === 'done') {
       // sugar for awaiting; --propose merge|nothing|close, optional --note
@@ -851,6 +883,18 @@ if (cmd === 'serve') {
     // line; GET /api/settings exposes the same resolution (`.layout`).
     const { mainBranch } = await import('./layout.js')
     console.log(mainBranch())
+  } else if (sub === 'spec-governors') {
+    // Stable machine projection for spec-aware hooks: one real code: governor per row, with the live spec
+    // path the block reason can point at. Empty stdout means ungoverned (including related-only).
+    const file = process.argv[4]
+    if (!file) { console.error('usage: spex internal spec-governors <path>'); process.exit(2) }
+    const { specOwners, loadSpecsLite } = await import('./specs.js')
+    const paths = new Map(loadSpecsLite().map((node) => [node.id, node.path]))
+    for (const owner of specOwners(file)) {
+      const path = paths.get(owner.id)
+      if (!path) throw new Error(`governor '${owner.id}' has no live spec path`)
+      console.log(`${owner.id}\t${path}`)
+    }
   } else if (sub === 'codex-launch') {
     // BACKEND-owned codex thread. On the shared per-project app-server: thread/start { cwd = this worktree }
     // (codex loads that worktree's config/hooks/AGENTS.md), store the new id on the governed record (keyed by
@@ -864,7 +908,7 @@ if (cmd === 'serve') {
     // On the bypass-trust path (the codex install supports the flag → materialize skipped writeCodexTrust's hash),
     // the thread the BACKEND owns must carry `bypass_hook_trust` in thread/start's config so the app-server fires
     // the worktree's local hooks — mirror materialize's capability decision so the two stay in lockstep.
-    const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(process.env.SPEXCODE_CODEX_CMD || 'codex --yolo'))
+    const bypassHookTrust = codexSupportsBypassHookTrust(codexBinary(process.env.SPEXCODE_CODEX_CMD || 'codex'))
     const r = await codexStartThread(sock, cwd, bypassHookTrust)
     if (!r.ok) { console.error(r.error); process.exit(1) }
     if (prompt) {
@@ -883,6 +927,17 @@ if (cmd === 'serve') {
     const sid = process.env.SPEXCODE_SESSION_ID
     if (sid) markHarnessSessionId(sid, r.threadId)
     console.log(r.threadId)
+  } else if (sub === 'opencode-capture') {
+    // opencode MINTS its own session id (no launch flag pins it), so the generated plugin's FIRST event calls
+    // this to store that id as harness_session_id on the governed record (SPEXCODE_SESSION_ID from the launch
+    // env, inherited by the opencode process → plugin). That is what lets reopen() resume the SAME
+    // conversation (`--session <id>`). A missing record/env is a clean no-op — a plugin loaded outside a
+    // governed launch has nothing to mark.
+    const { markHarnessSessionId } = await import('./sessions.js')
+    const ocid = process.argv[4]
+    if (!ocid) { console.error('usage: spex internal opencode-capture <opencode-session-id>'); process.exit(2) }
+    const sid = process.env.SPEXCODE_SESSION_ID
+    console.log(sid && markHarnessSessionId(sid, ocid) ? `captured ${ocid}` : 'noop (no governed session record)')
   } else if (sub === 'commit-surgery') {
     // the pre-commit footprint anchor ([[commit-surgery]]): unconditional materialize + staged-index repair
     // (strip our sentinel block from staged blobs, unstage HEAD-untracked generated artifacts). Called only

package/spec-cli/src/client.ts

@@ -1,5 +1,4 @@
 import { apiBase, assertProjectMatch, resolveSession, type Session, type Resolved, type DispatchResult, type ReviewPayload } from './sessions.js'
-import type { SessionEvals } from '../../spec-eval/src/sessioneval.js'
 
 export class BackendError extends Error {
   constructor(message: string, readonly status?: number) {
@@ -74,15 +73,38 @@ export async function clientEvalExport(id: string): Promise<ExportResult> {
   return { ok: false, status: r.status }
 }
 
-// GET /api/sessions/:id/evals — the session EVAL model ([[session-eval]]'s interactive face, the same
-// route's default JSON representation): the changed
-// nodes' worktree-rooted reading rows (each carrying `inSession`), no diff enrichment, no inlined evidence
-// bytes — what `spex eval` renders, the dashboard Eval tab's source. 404 → no such session.
-export type EvalsResult = { ok: true; model: SessionEvals } | { ok: false; status: number }
+// The CLI's explicit aggregate walks the same 25-row pages as the dashboard. No server response contains
+// the full session model; aggregation exists only for this one-shot terminal rendering.
+type SessionEvalPage = {
+  items: any[]
+  page: number
+  pageCount: number
+  total: number
+  gates: any[]
+  unknown: number
+  revision: string
+  summary?: any
+  evalRevision?: any
+}
+export type EvalsResult = { ok: true; model: SessionEvalPage & { id: string } } | { ok: false; status: number }
 export async function clientEvals(id: string): Promise<EvalsResult> {
-  const r = await apiFetch(`/api/sessions/${seg(id)}/evals`)
-  if (!r.ok) return { ok: false, status: r.status }
-  return { ok: true, model: await r.json() as SessionEvals }
+  const q = encodeURIComponent(`is:eval scope:${id}`)
+  for (let attempt = 0; attempt < 2; attempt++) {
+    const items: any[] = []
+    let first: SessionEvalPage | null = null
+    let changed = false
+    for (let page = 1;; page++) {
+      const r = await apiFetch(`/api/evals?q=${q}&page=${page}`)
+      if (!r.ok) return { ok: false, status: r.status }
+      const current = await r.json() as SessionEvalPage
+      first ??= current
+      if (current.revision !== first.revision) { changed = true; break }
+      items.push(...current.items)
+      if (page >= current.pageCount) break
+    }
+    if (!changed) return { ok: true, model: { ...first!, id, items } }
+  }
+  throw new BackendError(`session eval pages changed while reading ${id}; retry the command`)
 }
 
 // POST /api/sessions/:id/merge — the cockpit's merge DISPATCH (200 {dispatched:true} / 409 {reason}).
@@ -94,8 +116,9 @@ export async function clientMerge(id: string): Promise<{ dispatched: boolean; re
 
 // POST /api/sessions/:id/resume — bring the agent back (relaunch ONLY if confirmed offline); demotes
 // working→idle, keeps any declaration. The RESUME GUARD REFUSES (409 {refused:true}) on a live/unproven agent;
-// `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404).
-export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean }> {
+// `force` overrides for a wedged-but-alive process. {ok:false} otherwise = no such session (404). `info`
+// carries a non-error advisory.
+export async function clientResume(id: string, force = false): Promise<{ ok: boolean; error?: string; refused?: boolean; info?: string }> {
   await guarded('session resume')
   const r = await apiFetch(`/api/sessions/${seg(id)}/resume`, post({ force }))
   return await r.json().catch(() => ({ ok: false, error: `bad backend response (${r.status})` }))

package/spec-cli/src/doctor.ts

@@ -1,19 +1,17 @@
-// @@@ spex doctor - the DIAGNOSIS surface ([[doctor]]; command renamed from `self`, which misread as the
-// tool itself / the global install). When a user launches their OWN claude/codex with no SpexCode process
-// in the launch, the workflow reaches that agent only through the files materialize() writes (the manifest
-// in the global store; the in-tree contract blocks + hook shims + codex trust). Bare `spex doctor` answers
-// "is this agent actually governed, or silently running free?" — diagnosing that materialized contract per
-// LAYER, looping the same HARNESSES adapter materialize delivers through (so claude AND codex are covered
-// with no hardcoded paths). It catches the SILENT failure: a shim whose handler is missing, a PATH that
-// can't resolve `spex`, a contract that never landed. Read-only today: the bare report, `contract` (print
-// the surface:system text any agent reads), `conflicts`. install/uninstall are STAGED (noteStaged).
+// @@@ spex doctor - the opt-in, read-only project DIAGNOSIS surface ([[doctor]]). Bare doctor composes
+// spec-health findings with the delivery audit: when a user launches their OWN agent with no SpexCode
+// process in the launch, the workflow reaches it only through the files materialize() writes. The audit
+// loops the same HARNESSES adapter materialize uses and catches missing delivery or duplicate discovery.
+// `--contract` and `--conflicts` remain focused representations of that same diagnosis.
 import { existsSync, readFileSync, readdirSync, accessSync, constants } from 'node:fs'
 import { join, dirname, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { homedir } from 'node:os'
-import { loadSystemConfig, loadSkillConfig } from './specs.js'
-import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout } from './layout.js'
+import { loadSystemConfig, loadSkillConfig, loadSpecs } from './specs.js'
+import { runtimeRoot, treeSlotDir, envSessionId, readAliasedRawRecord, mainCheckout, readJsonConfig } from './layout.js'
+import { loadConfig } from './lint.js'
+import { trackedSourceFiles } from './source-files.js'
 
 // this file lives at <pkgRoot>/src/self.ts, so `..` is the package root — the same derivation init.ts/
 // materialize.ts use (never a hardcoded repo path), so the git-hook template lookup survives a relocated install.
@@ -31,6 +29,156 @@ function commonHooksDir(dir: string): string | null {
 }
 const read = (f: string): string => { try { return readFileSync(f, 'utf8') } catch { return '' } }
 
+type AltitudeConfig = {
+  lineBudget: number
+  charBudget: number
+  sizeable: number
+  dense: number
+  steps: number
+  identifierExtensions: string[]
+}
+
+type BreadthConfig = {
+  maxChildren: number
+}
+
+export type HealthFinding = {
+  check: string
+  spec: string
+  summary: string
+  evidence: string[]
+  repair: string
+}
+
+const DEFAULT_ALTITUDE: AltitudeConfig = {
+  lineBudget: 50,
+  charBudget: 4200,
+  sizeable: 35,
+  dense: 1.3,
+  steps: 3,
+  identifierExtensions: [],
+}
+
+const DEFAULT_BREADTH: BreadthConfig = {
+  maxChildren: 8,
+}
+
+function loadAltitudeConfig(root: string): AltitudeConfig {
+  const configured = readJsonConfig(join(root, 'spexcode.json'))?.doctor?.altitude ?? {}
+  const merged = { ...DEFAULT_ALTITUDE, ...configured }
+  return {
+    ...merged,
+    identifierExtensions: (merged.identifierExtensions ?? []).map((ext: string) => ext.replace(/^\.+/, '')),
+  }
+}
+
+function loadBreadthConfig(root: string): BreadthConfig {
+  const configured = readJsonConfig(join(root, 'spexcode.json'))?.doctor?.breadth ?? {}
+  return { ...DEFAULT_BREADTH, ...configured }
+}
+
+// Filename rows are lint coverage's exact tracked candidates. Compatibility extensions lower to wildcard
+// rows before the one identifier matcher is compiled.
+function identifierFilenameCandidates(sourceFiles: string[], compatibilityExtensions: string[]): string[] {
+  return [...new Set([
+    ...sourceFiles.map((path) => basename(path)),
+    ...compatibilityExtensions.map((ext) => `*.${ext}`),
+  ])]
+}
+
+function identRe(filenameCandidates: string[]): RegExp {
+  const escape = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const filenames = filenameCandidates
+    .map((candidate) => candidate.startsWith('*.')
+      ? `[\\w-]+\\.${escape(candidate.slice(2))}`
+      : escape(candidate))
+    .sort((a, b) => b.length - a.length)
+  const signals = [
+    '[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*',
+    '\\b[a-z]+_[a-z0-9_]+\\b',
+    '\\b\\w+\\(',
+    '`[^`]+`',
+    '\\/[\\w./-]+\\.\\w+',
+  ]
+  if (filenames.length) signals.push(`(?<![\\w./-])(?:${filenames.join('|')})(?![\\w.-])`)
+  return new RegExp(signals.join('|'), 'g')
+}
+
+const STEP_LINE = /^\s*(\d+[.)]\s|[-*]\s*(first|then|next|finally)\b)|(^|[,;]\s*)(first|then|next|finally),/i
+
+function altitudeEvidence(body: string, cfg: AltitudeConfig, ident: RegExp): string[] {
+  const lines = body.split('\n')
+  const nonBlank = lines.filter((line) => line.trim()).length
+  let inFence = false
+  let signals = 0
+  let steps = 0
+  for (const line of lines) {
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue }
+    if (inFence || !line.trim()) continue
+    signals += line.match(ident)?.length ?? 0
+    if (STEP_LINE.test(line)) steps++
+  }
+  const density = signals / Math.max(1, nonBlank)
+  const evidence: string[] = []
+  if (nonBlank > cfg.lineBudget || body.length > cfg.charBudget)
+    evidence.push(`${nonBlank} non-blank lines / ${body.length} chars over budget (${cfg.lineBudget}/${cfg.charBudget})`)
+  if (nonBlank > cfg.sizeable && density > cfg.dense)
+    evidence.push(`code-identifier density ${density.toFixed(2)}/line over ${cfg.dense}`)
+  if (nonBlank > cfg.sizeable && steps >= cfg.steps)
+    evidence.push(`${steps} step-by-step how-to lines`)
+  return evidence
+}
+
+export async function specHealthDiagnosis(root: string): Promise<HealthFinding[]> {
+  const lint = loadConfig(root)
+  const altitude = loadAltitudeConfig(root)
+  const breadth = loadBreadthConfig(root)
+  const governed = trackedSourceFiles(root, lint.governedRoots, lint)
+  const ident = identRe(identifierFilenameCandidates(governed, altitude.identifierExtensions))
+  const specs = await loadSpecs(root)
+  const childCount = new Map<string, number>()
+  for (const spec of specs) if (spec.parent) childCount.set(spec.parent, (childCount.get(spec.parent) ?? 0) + 1)
+  const findings: HealthFinding[] = []
+  for (const spec of specs) {
+    const evidence = altitudeEvidence(spec.body, altitude, ident)
+    if (evidence.length) findings.push({
+      check: 'altitude',
+      spec: spec.id,
+      summary: 'body reads like mechanics rather than a contract',
+      evidence,
+      repair: `rewrite '${spec.id}' around observable intent and invariants; the tidy workflow can perform the semantic review`,
+    })
+    const children = childCount.get(spec.id) ?? 0
+    if (children >= breadth.maxChildren) findings.push({
+      check: 'breadth',
+      spec: spec.id,
+      summary: 'tree fan-out may be missing a natural grouping layer',
+      evidence: [`${children} direct child nodes (>= ${breadth.maxChildren})`],
+      repair: `review '${spec.id}' with the regroup workflow; group only along a real seam and leave genuine peers flat`,
+    })
+  }
+  return findings
+}
+
+function healthReport(findings: HealthFinding[], adopted: boolean): string[] {
+  const lines = ['Spec health diagnosis (opt-in advisory; never part of spex spec lint)']
+  if (!adopted) {
+    lines.push('  status          : unavailable — adopt the repository with `spex init`')
+    return lines
+  }
+  const checks = ['altitude', 'breadth', ...new Set(findings.map((finding) => finding.check).filter((check) => check !== 'altitude' && check !== 'breadth'))]
+  for (const check of checks) {
+    const rows = findings.filter((finding) => finding.check === check)
+    lines.push(`  ${check.padEnd(16)}: ${rows.length ? `${rows.length} finding(s)` : 'healthy'}`)
+    for (const finding of rows) {
+      lines.push(`    ${finding.spec.padEnd(16)}: ${finding.summary}`)
+      for (const evidence of finding.evidence) lines.push(`      evidence      : ${evidence}`)
+      lines.push(`      repair        : ${finding.repair}`)
+    }
+  }
+  return lines
+}
+
 // @@@ contractText - the layer-2 payload: the composed `surface:system` bodies, the SAME join materialize()
 // folds into each harness's contract file — so a BYOA agent reads byte-identical guidance.
 function contractText(): { names: string[]; body: string } {
@@ -170,9 +318,9 @@ async function doubleDeliveryReport(base: string): Promise<{ lines: string[]; co
   if (conflict) {
     L.push('Repair — SpexCode is reaching this agent through MORE THAN ONE discovery channel. Keep exactly one:')
     L.push('  • remove the independently-installed plugin bundle (delete its dir, or `claude plugin uninstall spexcode`); or')
-    L.push('  • if you WANT the plugin, stop the native delivery: set spexcode.json "harnesses" to a plugin target')
-    L.push('    (e.g. ["plugin",{"plugin":".claude"}] → {"plugin":".claude"}) so `spex materialize` prunes the loose shim/contract/skills; or')
-    L.push('  • remove the loose copy directly (`spex doctor uninstall` [staged] / `spex uninstall`).')
+    L.push('  • if you WANT the plugin, stop the native delivery: set spexcode.json to')
+    L.push('    `"harnesses": [{"plugin":".claude"}]`, then run `spex materialize` to prune the loose shim/contract/skills; or')
+    L.push('  • remove SpexCode\'s generated delivery with `spex uninstall`.')
   } else {
     L.push('No double-delivery: each harness is reached by at most one spexcode-stamped channel.')
   }
@@ -233,8 +381,14 @@ async function doctor(): Promise<number> {
     })
     line('issues workflow', `${issuesEnabled() ? 'ON' : 'OFF'} (spexcode.json issues.enabled)`)
     if (legacy.length) line('  LEGACY key', `\`proposals\` found in ${legacy.map((f) => join(cfgHome, f)).join(', ')} — no longer read; rename it to "issues": { "enabled": … }`)
+    const projectConfig = readJsonConfig(join(base, 'spexcode.json'))
+    if (Object.prototype.hasOwnProperty.call(projectConfig.lint ?? {}, 'maxChildren'))
+      line('RETIRED key', '`lint.maxChildren` is no longer read — move the value to `doctor.breadth.maxChildren`')
   }
 
+  const health = adopted ? await specHealthDiagnosis(base) : []
+  L.push('\n' + healthReport(health, adopted).join('\n'))
+
   // --- preconditions: nothing downstream fires without these ---
   L.push('\nPreconditions (without these nothing downstream fires)')
   for (const bin of ['spex', 'claude', 'codex']) {
@@ -347,37 +501,23 @@ async function conflicts(): Promise<number> {
   return conflict ? 1 : 0
 }
 
-
-// install/uninstall are STAGED: wiring layer-3 hooks into a standalone repo is only SAFE once the hooks
-// detect a missing managed session and degrade. So the diagnosis ships first; the installer lands behind it.
-function noteStaged(verb: string): number {
-  console.error(`spex doctor ${verb} is not available yet — it is staged behind the hook-degradation prerequisite
-(the live hooks must detect a missing managed session and degrade before they can be safely wired into your
-own agent's config). Meanwhile: \`spex doctor\` reports your coverage, and \`spex doctor --contract\` prints
-the workflow text you can hand any agent.`)
+function migrationRemoved(): number {
+  console.error('spex: `spex doctor --migrate` was removed in v0.4.0 — migrate this tree with a 0.3.x SpexCode release, then reinstall the current release. Nothing was changed.')
   return 2
 }
 
 function usage(): number {
-  console.error(`spex doctor — diagnose how the SpexCode workflow reaches your agent
-  (bare)         per-layer report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
+  console.error(`spex doctor — diagnose spec health and how the SpexCode workflow reaches your agent
+  (bare)         spec-health findings + delivery report: preconditions · git-hook floor · contract · hooks(+handlers) · backend · footprint
   --contract     print the surface:system contract text (hand it to any agent)
-  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)
-  --migrate      one-shot 0.2.x → 0.3.0 vocabulary migration for an adopter repo (renames + hook-asset
-                 upgrade + body rewrites; refuses on a dirty tree / undrained sessions / an already-migrated
-                 tree; stages everything, commits nothing; removed in 0.4.0)
-  install        [staged] wire the materialized contract + hooks into your agent  (--agent claude, --minimal)
-  uninstall      [staged] reverse exactly what install wrote`)
+  --conflicts    detect double-delivery — the same agent reached via loose native delivery AND a plugin bundle (exits non-zero on conflict)`)
   return 0
 }
 
 export async function runDoctor(args: string[]): Promise<number> {
   // contract/conflicts are FLAGS, not subcommands ([[cli-surface]] §4: another representation of the same
   // diagnosis read, not a distinct action). The old positional spellings signpost — report, never run.
-  // --migrate is the one MUTATING flag: the term-limited 0.2.x→0.3.0 adopter migrator ([[migrate]],
-  // ships with 0.3.0, deleted in 0.4.0) — dispatched first so its refusal/summary is never diluted
-  // by the diagnosis report.
-  if (args.includes('--migrate')) return await (await import('./migrate.js')).runMigrate()
+  if (args.includes('--migrate')) return migrationRemoved()
   if (args.includes('--contract')) return contract()
   if (args.includes('--conflicts')) return await conflicts()
   switch (args[0]) {
@@ -385,8 +525,6 @@ export async function runDoctor(args: string[]): Promise<number> {
     case 'contract': case 'conflicts':
       console.error(`spex: \`spex doctor ${args[0]}\` was removed in v0.3.0 — use: spex doctor --${args[0]}`)
       return 2
-    case 'install': return noteStaged('install')
-    case 'uninstall': return noteStaged('uninstall')
     case 'help': case '--help': case '-h': return usage()
     default: console.error(`spex doctor: unknown subcommand "${args[0]}"`); usage(); return 2
   }