spexcode 0.4.0 → 0.4.3

package/spec-cli/src/tree.ts

@@ -12,9 +12,10 @@ export type TreeNode = {
   version?: number
   drift?: number
   ghost?: boolean
-  openIssues?: unknown[]
-  scenarios?: { name: string }[]
-  evals?: { scenario: string; fresh?: boolean }[]
+  reviewSummary?: {
+    issues?: { open: number }
+    evals?: { stalePass: number; staleFail: number }
+  }
 }
 
 export type TreeOpts = { node?: string; depth?: number; color?: boolean }
@@ -27,9 +28,8 @@ const STATUS_ANSI: Record<string, string> = { merged: '32', active: '36', drift:
 // board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
 // axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
 function staleYatsu(n: TreeNode): number {
-  if (!n.scenarios?.length || !n.evals?.length) return 0
-  const latest = new Map(n.evals.map((r) => [r.scenario, r]))
-  return n.scenarios.filter((s) => { const r = latest.get(s.name); return r && r.fresh === false }).length
+  const summary = n.reviewSummary?.evals
+  return summary ? summary.stalePass + summary.staleFail : 0
 }
 
 function childrenIndex(nodes: TreeNode[]): Map<string | null, TreeNode[]> {
@@ -67,7 +67,7 @@ export function renderTree(nodes: TreeNode[], opts: TreeOpts = {}): string {
     if (n.drift) parts.push(c('33', `drift:${n.drift}`))
     const stale = staleYatsu(n)
     if (stale) parts.push(c('90', `stale:${stale}`))
-    if (n.openIssues?.length) parts.push(c('31', `issues:${n.openIssues.length}`))
+    if (n.reviewSummary?.issues?.open) parts.push(c('31', `issues:${n.reviewSummary.issues.open}`))
     return parts.length ? '  ' + parts.join(' ') : ''
   }
 
@@ -109,7 +109,7 @@ export function treeJson(nodes: TreeNode[], opts: TreeOpts = {}): object[] {
     const pruned = opts.depth !== undefined && depth >= opts.depth
     return {
       id: n.id, title: n.title, status: n.status, version: n.version ?? 0,
-      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.openIssues?.length ?? 0,
+      drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.reviewSummary?.issues?.open ?? 0,
       ...(n.ghost ? { ghost: true } : {}),
       children: pruned ? kids.map((k) => k.id) : kids.map((k) => shape(k, depth + 1)),
     }

package/spec-cli/src/uninstall.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
-import { join, resolve, relative } from 'node:path'
+import { basename, join, resolve, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { execFileSync } from 'node:child_process'
 import { HARNESSES, type HarnessArtifacts } from './harness.js'
 import { runtimeRoot, readConfig, mainCheckout } from './layout.js'
@@ -13,16 +14,20 @@ import { dematerialize } from './materialize.js'
 // and the optional git hooks. EVERY removal is gated on a SpexCode IDENTITY STAMP (the managed-block
 // sentinels, the shim's own dispatch.sh command line, the trust sentinels, the generated mark / name-scoped
 // on-demand paths, the plugin name stamp), so it can only ever delete what SpexCode itself generated. The one
-// inviolable rule: the user's spec ASSET (.spec/.plugins) is NEVER touched — uninstall removes only generated
-// WIRING, not the spec graph that wiring served.
+// inviolable rule: the user's tracked intent ASSET (.spec/.plugins + spexcode.json) is NEVER touched — uninstall
+// removes only generated WIRING and local runtime state, not the spec graph and adoption config they served.
 
 // the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
-const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex'] as const
+const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex', '.zcode'] as const
+
+// Init and uninstall share one ownership source for generated git hooks: the shipped canonical templates.
+// Exact bytes prove the destination is still our derivative; any user edit withdraws that ownership.
+const HOOK_TEMPLATES = fileURLToPath(new URL('../templates/hooks', import.meta.url))
 
 // is this dir a SpexCode plugin bundle? Either its folder name is the identity stamp, or its
 // `.claude-plugin/plugin.json` declares `name: spexcode`. Read-gated so a user's other plugin is never touched.
 function isSpexcodeBundle(dir: string): boolean {
-  if (dir.split('/').pop() === 'spexcode') return true
+  if (basename(dir) === 'spexcode') return true
   const manifest = join(dir, '.claude-plugin', 'plugin.json')
   if (!existsSync(manifest)) return false
   try {
@@ -52,6 +57,26 @@ function sweepPluginBundles(proj: string, hosts: readonly string[]): string[] {
   return removed
 }
 
+// Arbitrary plugin landing folders are the one materialized path set that cannot be reconstructed from stamps
+// alone, so materialize records them as data. Read every current per-tree ledger plus the legacy project-global
+// ledger before uninstall removes the store; a stale bundle remains removable even after current config stopped
+// naming its former host folder.
+function pluginLedgerHosts(store: string): string[] {
+  const ledgers = [join(store, 'plugin-folders')]
+  const trees = join(store, 'trees')
+  if (existsSync(trees)) {
+    for (const e of readdirSync(trees, { withFileTypes: true })) {
+      if (e.isDirectory()) ledgers.push(join(trees, e.name, 'plugin-folders'))
+    }
+  }
+  const hosts: string[] = []
+  for (const ledger of ledgers) {
+    if (!existsSync(ledger)) continue
+    hosts.push(...readFileSync(ledger, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean))
+  }
+  return hosts
+}
+
 // resolve the repo's shared git hooks dir (the common dir's hooks/), or null when <dir> isn't a git repo.
 function hooksDir(proj: string): string | null {
   try {
@@ -65,18 +90,18 @@ function hooksDir(proj: string): string | null {
   }
 }
 
-// remove the SpexCode git hooks — but ONLY a hook whose content carries a SpexCode identity marker, so a user's
-// own pre-commit is never deleted. Per-clone hooks are preserved by default; this runs only under `--hooks`.
+// Remove only byte-identical products of the canonical hook templates. Enumerating the same template directory
+// init copies keeps every generated hook covered without a second name list; modified and unrelated hooks survive.
 function removeHooks(proj: string): string[] {
   const dir = hooksDir(proj)
   if (!dir) return []
   const removed: string[] = []
-  for (const name of ['pre-commit', 'prepare-commit-msg']) {
-    const f = join(dir, name)
-    if (existsSync(f) && /spexcode/i.test(readFileSync(f, 'utf8'))) {
-      rmSync(f, { force: true })
-      removed.push(name)
-    }
+  for (const e of readdirSync(HOOK_TEMPLATES, { withFileTypes: true })) {
+    if (!e.isFile()) continue
+    const hook = join(dir, e.name)
+    if (!existsSync(hook) || !readFileSync(hook).equals(readFileSync(join(HOOK_TEMPLATES, e.name)))) continue
+    rmSync(hook, { force: true })
+    removed.push(e.name)
   }
   return removed
 }
@@ -103,19 +128,20 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
   //    erase phase every materialize runs, asserted against the empty policy. One inverse, never a parallel one.
   dematerialize(proj, arts)
 
-  // 3. the global per-project store — the per-tree materialize slots (trees/<enc>: manifest + content-hash +
-  //    plugin ledger), any legacy pre-slot manifest, and the session records. This is the runtime tier,
-  //    not the user's spec asset, so the whole dir is ours.
+  // 3. Locate the global per-project store and recover every current/legacy plugin landing folder from its
+  //    ledgers BEFORE deleting it. The store is the runtime tier, not the user's tracked intent asset.
   let store: string | null = null
+  let ledgerHosts: string[] = []
   try {
     store = runtimeRoot(proj)
-    rmSync(store, { recursive: true, force: true })
   } catch {
     store = null
   }
+  if (store) ledgerHosts = pluginLedgerHosts(store)
 
-  // 4. any spexcode-stamped plugin bundle, under the configured + standard plugin-host folders.
-  let pluginHosts: string[] = [...DEFAULT_PLUGIN_HOSTS]
+  // 4. Any spexcode-stamped plugin bundle under configured, standard, or ledger-recovered hosts. The ledger
+  //    input is what closes plugin-folder A -> native/folder B even when the previous materialize never finished.
+  let pluginHosts: string[] = [...DEFAULT_PLUGIN_HOSTS, ...ledgerHosts]
   try {
     const targets = resolveHarnessTargets(readConfig(mainCheckout(proj)).harnesses)
     pluginHosts = [...pluginHosts, ...targets.filter((t) => t.kind === 'plugin').map((t) => (t as { folder: string }).folder)]
@@ -124,12 +150,19 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
   }
   const bundles = sweepPluginBundles(proj, pluginHosts)
 
+  // 5. The whole store: per-tree manifests/hashes/ledgers, legacy project-global products, and sessions.
+  let removedStore: string | null = null
+  if (store && existsSync(store)) {
+    rmSync(store, { recursive: true, force: true })
+    removedStore = store
+  }
+
   console.log(`✓ dematerialized (contract blocks, shims, Codex trust, skills, sub-agents, ignore blocks, content filter) for ${HARNESSES.map((h) => h.id).join(', ')}`)
-  if (store) console.log(`✓ removed the global per-project store (${store})`)
+  if (removedStore) console.log(`✓ removed the global per-project store (${removedStore})`)
   if (bundles.length) console.log(`✓ removed plugin bundle(s): ${bundles.join(', ')}`)
 
-  // git hooks are per-clone and may carry user logic → preserved unless --hooks (and even then only a hook that
-  // carries a SpexCode identity marker).
+  // Git hooks are per-clone and may carry user logic → preserved unless --hooks (and even then only while
+  // byte-identical to a canonical generated template; a user edit withdraws our ownership).
   if (opts.hooks) {
     const removed = removeHooks(proj)
     if (removed.length) console.log(`✓ removed git hooks (${removed.join(', ')})`)
@@ -140,6 +173,6 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
 
   console.log(`
 SpexCode wiring removed. Your spec data is untouched:
-  • .spec/ and .plugins/ remain — your spec graph is YOURS, never deleted by uninstall.
+  • .spec/ (including .plugins/) and spexcode.json remain — your tracked intent is never deleted by uninstall.
   • To re-adopt later: \`spex init\` regenerates the shims, contract, trust, and global store.`)
 }

package/spec-cli/templates/hooks/prepare-commit-msg

@@ -9,26 +9,45 @@
 #     it must NOT be trusted. Resolve the thread id → record via the SAME `harness_session_id` alias the shell
 #     hooks use, AT COMMIT TIME (the record is swept on close, so read-time aliasing would fail), and stamp the
 #     resolved RECORD id.
+#   - Per-session-process harnesses (opencode; pi) export NO harness var to tool subprocesses — their identity
+#     channel IS the launch-injected SPEXCODE_SESSION_ID (each TUI is one process, no shared-server
+#     contamination). Trust it only as the LAST tier, and only when the record it names is verifiably not a
+#     codex record — so a codex shell that somehow lost its CODEX_THREAD_ID can never stamp the first
+#     session's id.
 # No-op outside a governed session, or if a Session: trailer is already present (so the dogfood ritual / a
 # human can still set it explicitly).
 set -euo pipefail
 msg_file="$1"
 grep -qiE '^Session:[[:space:]]' "$msg_file" && exit 0
 
+# the per-project store (mirrors layout.ts runtimeRoot / harness.sh hp_runtime_dir): keyed by the project
+# (dirname of the ABSOLUTE git-common-dir), '/' and '.' → '-'.
+gcd=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
+  || gcd=$(realpath "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null) || gcd=""
+rd=""
+[ -n "$gcd" ] && rd="${SPEXCODE_HOME:-$HOME/.spexcode}/projects/$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
+
 sid="${CLAUDE_CODE_SESSION_ID:-}"                       # claude: the exported id IS the record id
-if [ -z "$sid" ] && [ -n "${CODEX_THREAD_ID:-}" ]; then # codex: alias the thread id → record id
-  gcd=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
-    || gcd=$(realpath "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null) || gcd=""
-  if [ -n "$gcd" ]; then
-    # the per-project store (mirrors layout.ts runtimeRoot / harness.sh hp_runtime_dir): keyed by the project
-    # (dirname of the ABSOLUTE git-common-dir), '/' and '.' → '-'.
-    rd="${SPEXCODE_HOME:-$HOME/.spexcode}/projects/$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
-    if [ -e "$rd/sessions/$CODEX_THREAD_ID/session.json" ]; then
-      sid="$CODEX_THREAD_ID"                             # a governed record keyed by the thread id (rare/direct)
-    else                                                 # else the record that captured it as harness_session_id
-      hit=$(grep -lF "\"harness_session_id\": \"$CODEX_THREAD_ID\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
-      [ -n "$hit" ] && sid=$(basename "$(dirname "$hit")")
-    fi
+if [ -z "$sid" ] && [ -n "${CODEX_THREAD_ID:-}" ] && [ -n "$rd" ]; then # codex: alias the thread id → record id
+  if [ -e "$rd/sessions/$CODEX_THREAD_ID/session.json" ]; then
+    sid="$CODEX_THREAD_ID"                               # a governed record keyed by the thread id (rare/direct)
+  else                                                   # else the record that captured it as harness_session_id
+    # @@@ unmatched-is-noop - grep's no-match (exit 1) and an absent sessions glob (exit 2) are the
+    # NOT-GOVERNED case, not an error: any repo inherits a foreign CODEX_THREAD_ID from a codex session's
+    # shell, and under `set -euo pipefail` a bare grep|head assignment would abort the hook — and the
+    # commit — before the intended `[ -z "$sid" ] && exit 0` no-op. Genuine errors past this lookup
+    # (interpret-trailers etc.) still fail loud via set -e.
+    hit=$(grep -lF "\"harness_session_id\": \"$CODEX_THREAD_ID\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1) || hit=""
+    [ -n "$hit" ] && sid=$(basename "$(dirname "$hit")")
+  fi
+fi
+if [ -z "$sid" ] && [ -n "${SPEXCODE_SESSION_ID:-}" ] && [ -n "$rd" ]; then
+  # last tier of the shared envSessionId precedence rule: no harness var claimed the commit, so the
+  # launch-injected record id is the identity — IF its record exists (governance check; swept on close) and
+  # is not codex's (the one harness whose shared server contaminates this env var).
+  rec="$rd/sessions/$SPEXCODE_SESSION_ID/session.json"
+  if [ -e "$rec" ] && ! grep -q '"harness": "codex"' "$rec"; then
+    sid="$SPEXCODE_SESSION_ID"
   fi
 fi
 

package/spec-cli/templates/spec/project/.plugins/{extract → commands/extract}/spec.md

@@ -3,12 +3,14 @@ title: extract
 surface: command
 status: active
 hue: 30
-desc: Reverse-engineer a faithful spec tree out of existing code — responsibility nodes at contract altitude, intent never fabricated.
+desc: Reverse-engineer — or re-run to reconcile — a faithful spec tree out of existing code: responsibility nodes at contract altitude, intent never fabricated, every frontend node carrying a loss signal.
 kind: mutating
 ---
-Reverse-engineer a spec tree for the target source area(s) below — code that has no specs yet. Aim for a
-tree where every governed file is claimed and `spex spec lint` is clean, with bodies at contract altitude and in
-the codebase's own primary language (a predominantly-Chinese repo → Chinese specs).
+Reverse-engineer a spec tree for the target source area(s) below — or **re-run to reconcile** an
+already-extracted area, the same pass that closes the gaps code growth opens (an unclaimed governed file, a
+frontend node missing its loss signal, a thin scenario). Extraction is not a one-shot. Aim for a tree where
+every governed file is claimed and `spex spec lint` is clean, bodies at contract altitude and in the codebase's
+own primary language (a predominantly-Chinese repo → Chinese specs).
 
 {{targets}}
 
@@ -24,11 +26,11 @@ Then grow nodes under that spine:
   claiming them all. Every governed file is claimed by at least one node; nest into subtrees where warranted.
 - **Group wide layers; don't mirror the file tree — at every level, the root included.** One-node-per-folder
   is a smell. If a node would have more than ~7 direct children you're under-grouping: add intermediate
-  **sub-domain** nodes that cluster siblings serving one concern (e.g. model-config + selection + auth +
-  provider-compat → a *model* domain), and recurse until every level reads as a handful of siblings, not a
-  flat wall. Fold cross-cutting substrate (design system, dialogs, i18n, utilities, platform glue) under one
-  *foundation* node. A sub-domain node claims the cluster's barrel/wiring files (so it isn't pure-prose);
-  equally, split a fat folder holding several distinct jobs. Group by responsibility, never to hit a number.
+  **sub-domain** nodes that cluster siblings serving one concern (model-config + selection + auth → a *model*
+  domain), and recurse until every level reads as a handful of siblings, not a flat wall. Fold cross-cutting
+  substrate (design system, i18n, platform glue) under one *foundation* node that claims the cluster's
+  barrel/wiring files (so it isn't pure-prose); split a fat folder holding several distinct jobs. Group by
+  responsibility, never to hit a number.
 - **Stay at contract altitude.** State each node's intent, invariants, and outward behavior — what it
   guarantees and why — not how the code does it.
 - **Never fabricate intent.** Code shows *what it does*, rarely *why*. Read any README/design docs for real
@@ -44,17 +46,21 @@ Then grow nodes under that spine:
 **Give every frontend node a loss signal.** A node that governs UI or visual code (`.tsx`/`.jsx`/`.vue`/
 `.svelte`/`.css`, or the dashboard) is a blind spot until it carries a `eval.md` — so write one as you
 extract it: a **real user-path** scenario — a goal and the steps to reach it through the running app (never a
-bare render-check), covering a failure/empty/edge state — with a **description** of those steps and the
-**expected** zero-loss result. Frontend scenarios are measured by looking — through the running product, as a real user would — a screenshot filed with
+bare render-check), covering a failure/empty/edge state — with a **description** of those steps, the
+**expected** zero-loss result, and **≥1 `tags`** classifying it (a surface like `frontend-e2e`/`backend-api`/
+`cli`, a device like `desktop`/`mobile`) drawn from the configured library (`lint.scenarioTags`); a tag
+outside the library fails `scan`, so use an existing one or extend the library. Frontend scenarios are measured by looking (YATU) — a screenshot filed with
 `spex eval add <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex eval lint` to
-list the frontend nodes still uncovered.
+list the frontend nodes still uncovered. On a **re-run** this is also where you sharpen — give an uncovered
+node its first scenario, tighten a thin one (a bare render-check, or a stale `expected`); `spex guide eval`
+has the schema.
 
 **Extract incrementally — don't plan the whole tree before writing.** For a large area (hundreds of files),
-don't enumerate the whole partition up front or script a generator to emit it at once — that burns context
-before a node lands and loses everything to one interruption. Fix the top-level cut and commit it, then take
-ONE subtree at a time (write the leaf, list its files, lint, COMMIT) before the next — never holding more than
-one subtree uncommitted, so progress survives context limits.
+enumerating the whole partition up front or scripting a generator to emit it at once burns context before a
+node lands and loses everything to one interruption. Fix the top-level cut and commit it, then take ONE
+subtree at a time (write the leaf, list its files, lint, COMMIT) before the next — never more than one
+subtree uncommitted, so progress survives context limits.
 
 Confirm `spexcode.json`'s `governedRoots` points at the real source dirs first — lint reads silently empty
-otherwise. Commit one node per commit (`spec: <id> — extract from <area>`) with a `Session:` trailer, and
-run `spex spec lint` after each: it must reach 0 errors, 0 coverage warnings, 0 altitude warnings.
+otherwise. Commit one node per commit (`spec: <id> — extract from <area>`) and run `spex spec lint` after each:
+0 errors, 0 coverage/altitude warnings.

package/spec-cli/templates/spec/project/.plugins/{regroup → commands/regroup}/spec.md

@@ -6,14 +6,14 @@ hue: 130
 desc: Resolve a node's breadth — a flat fan-out of too many children — by lifting children onto their true owner or a new grouping layer, only along real seams.
 kind: mutating
 ---
-A node flagged for **breadth** has too many direct children: a flat fan-out the eye can't hold. Breadth is altitude's structural twin — the same comprehensibility limit, rotated from a body's depth onto the tree's width. Find the **natural seams** in the fan-out and lift the children onto them, *only where a real group exists*. Getting under the child budget is the floor, not the goal; never manufacture structure to hit a number.
+A node flagged by `spex doctor` for **breadth** has many direct children: a flat fan-out the eye may not hold. Breadth is an unvalidated health hypothesis, not a lint defect — a flat list of genuine peers can be right. Find the **natural seams** in the fan-out and lift the children onto them, *only where a real group exists*. Getting under the configured child budget is the floor, not the goal; never manufacture structure to hit a number.
 
 {{targets}}
 
 Read before you move: the over-broad node's spec, every child's spec, and the `[[links]]`/`related:` between them. A flat fan-out is rarely one undifferentiated list — some children are **misfiled** under the wrong parent, some **cohere into a surface no node owns yet**, and some are **genuine independent peers**. Sort each child into exactly one disposition:
 
 - **Reparent under an existing sibling.** When a child's own spec says it is *part of* another child — its tab, its row, its input, a sub-surface of it — that sibling is its true owner. `git mv` it under that node. No new parent: the breadth was the symptom of a misparented child, and putting it under its real owner fixes the miscategorization for free. **Try this first** — it is the cheapest, most honest move and adds nothing to the tree. (Second-order case: if a reparent pushes the new host over budget, that host now needs its own seam.)
-- **Group under a new intermediate parent.** When several children genuinely cohere — one surface, one concept, read together to understand one thing — but no existing node owns them. Create one parent along that seam. It must **earn its existence**: a body stating what the group *is* and why these children belong, a contract at altitude (it is a real node and must pass altitude lint itself) — never a hollow container echoing a table of contents. The two-for-one test: a true seam also makes the siblings around it read more clearly.
+- **Group under a new intermediate parent.** When several children genuinely cohere — one surface, one concept, read together to understand one thing — but no existing node owns them. Create one parent along that seam. It must **earn its existence**: a body stating what the group *is* and why these children belong, a contract at altitude (it is a real node and must stay clear in the doctor's altitude diagnosis) — never a hollow container echoing a table of contents. The two-for-one test: a true seam also makes the siblings around it read more clearly.
 - **Leave it flat.** When a child shares no boundary with the rest. A flat list of genuine peers is sometimes right; refusing to force a "misc"/"everything-else" bucket is the correct move, not a failure. A couple of real groups plus a handful of still-flat peers is a good outcome.
 
 Honor these:
@@ -22,4 +22,4 @@ Honor these:
 - **Fewest, deepest-justified parents.** Don't trade one flat layer for six two-child wrappers — that relocates the sprawl instead of resolving it. Between two passing groupings, take the one that adds fewer nodes.
 - Parent ids name the concept (kebab-case); give the parent a `hue` near its children's family.
 
-Work the order: (1) read everything; (2) write each candidate seam with the one-sentence intent that justifies it — kill the unjustifiable, and mark each survivor as reparent-under-existing or new-parent; (3) make the moves, one reviewable commit per group (`spec: <parent> — regroup <children>`, with a `Session:` trailer); (4) run `spex spec lint` and confirm breadth is resolved with no new errors. Uncommitted `git mv`s churn the drift count transiently — committing settles it; don't chase it.
+Work the order: (1) read everything; (2) write each candidate seam with the one-sentence intent that justifies it — kill the unjustifiable, and mark each survivor as reparent-under-existing or new-parent; (3) make the moves, one reviewable commit per group (`spec: <parent> — regroup <children>`, with a `Session:` trailer); (4) run `spex spec lint` and keep it at 0 errors, then run bare `spex doctor` and confirm the breadth finding is resolved. Uncommitted `git mv`s churn the drift count transiently — committing settles it; don't chase it.

package/spec-cli/templates/spec/project/.plugins/commands/rename/spec.md

@@ -0,0 +1,11 @@
+---
+title: rename
+surface: command
+status: active
+hue: 300
+desc: Give this SpexCode session a short, specific name derived from the work it is currently doing.
+kind: mutating
+---
+Review the work this session is currently doing and choose a short, specific name that will distinguish it
+from the other sessions on the SpexCode board. Then run `spex session rename . "<name>"` to set that name.
+Rename the SpexCode session, not the harness conversation, and do not edit project files for this task.

package/spec-cli/templates/spec/project/.plugins/commands/spec.md

@@ -0,0 +1,30 @@
+---
+title: commands
+status: active
+hue: 40
+desc: Grouping shelf for the `surface: command` prompt presets offered wherever a human composes work for an agent. A shelf, not a surface — routing stays field-driven per surface.
+---
+# commands
+
+The invocable **command** plugins live here: leaf plugins whose body is a prompt preset a human can pick
+from the `/` dropdown while launching or driving a session, each carrying `surface: command`. Grouping them keeps `.plugins/` legible at
+a glance — the command presets on this shelf, the skill plugins on [[skills]], the auxiliary system
+contracts on [[prompts]], with [[core]] (the dev-flow contract subsystem) a flat child beside them.
+
+Invocation belongs to the backend prompt boundary, not to whichever client happens to render the picker.
+Every compose surface sends the raw `/<preset> [[node]]… <free text>` prompt; the shared resolver expands the
+live `surface: command` body before either launch starts a worker or dispatch sends text to one. At
+launch, the raw invocation remains the session's originating prompt and identity source, so links inside a
+plugin body can never invent a node target. Dashboard and phone menus are therefore discovery/insertion
+chrome, while dashboard, phone, CLI, API, and in-process fallback all invoke through the same backend
+resolution. A preset with `{{targets}}` always receives the resolved target block; one without that placeholder
+gets a target block only when the invocation actually names a target, so a targetless utility remains a small
+prompt. An unknown leading `/name` stays ordinary prompt text and is never swallowed or guessed.
+
+This node is a **shelf, not a surface** (the [[prompts]] shape): it declares no `surface` field and
+gathers nothing itself. Discovery is recursive and field-driven (surface), so a resident plugs in
+exactly as it would at the root — the gather set is path-independent, so shelving a command changes
+nothing about what `/api/plugins` and the launcher offer. A plugin that serves BOTH surfaces (e.g.
+[[distill]], skill and command) shelves once by its primary identity, never duplicated. The init
+templates mirror this layout. The shelf stays pure presentation: moving a resident beneath it changes
+neither that plugin's identity nor the surfaces gathered from its frontmatter.

package/spec-cli/templates/spec/project/.plugins/commands/supervisor/spec.md

@@ -0,0 +1,8 @@
+---
+title: supervisor
+surface: command
+status: active
+hue: 280
+desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
+---
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** after dispatching, background a `spex session wait <child>` per worker (per the manager loop) so that when you stop with children still working you land in `parked` — self-resuming on the next child transition — NOT `asking`; only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows:

package/spec-cli/templates/spec/project/.plugins/commands/tidy/spec.md

@@ -0,0 +1,43 @@
+---
+title: tidy
+surface: command
+status: active
+hue: 140
+desc: Diagnose or fix a node's body altitude — grade it against the contract-surface test (read-only), or rewrite it to contract altitude — by what the invocation asks for.
+kind: mutating
+---
+Bring each target spec node's body to **contract** altitude — observable behavior, not implementation, and not vague
+hand-waving either. One node, two modes chosen by the invoking prompt: **diagnose** (grade only, change nothing) or
+**fix** (rewrite in place). Default to diagnose when the ask is "how healthy / what's wrong", to fix when it is "tidy /
+clean up".
+
+{{targets}}
+
+The objective rule for every sentence is the contract-surface test: *"could a behavior-preserving refactor delete or
+change this?"*
+
+- **Yes ⇒ it is implementation** (operators, call names, data structures, "added a parameter", step-by-step how-to). In
+  fix mode it leaves the body and becomes an `@@@title - explanation` comment at the code that owns it.
+- **No ⇒ it is contract surface.** Keep it — public names, signatures, return types, invariants, edges/errors, the
+  WHEN → outcome a caller observes.
+
+**Diagnose** (read-only — no edits, no commits). Run bare `spex doctor` once and consume its **Spec health
+diagnosis** for every target; never restate or locally reproduce the altitude proxy thresholds. For each target
+report two layers:
+
+- **Deterministic (git + `spex spec lint`):** *Lint* — errors/warnings naming this node (integrity, living, coverage, drift);
+  *Drift* — whether its governed `code:` files moved ahead of its latest version, by how much; *Link-gap* — does `code:`
+  name every implementing file? an unlinked file is invisible to lint and drift, so the spec silently stops governing it.
+- **Quality grade (judge the body, not the code):** score 1–5 — *declarative*, *refactor-resistant*, *edges*,
+  *testable*, *concise*. Include the doctor's altitude finding (or explicit clear result) as the cheap mechanical
+  signal. Two failure directions remain a semantic judgment: **too low** (a mechanics dump — leaks, code identifiers,
+  how-to) and **too thin** (so vague a refactor couldn't violate it, e.g. "validates input appropriately"; only you catch
+  this). End with a one-line verdict (`healthy` | `needs-tidy` | `too-thin` | `drifting` | `link-gap`) and the single
+  highest-value next action. Change nothing.
+
+**Fix** (mutating — one commit per node). Rewrite the body at the right altitude: **preserve the contract** (never drop a
+requirement; rephrase, don't delete meaning), **raise don't hollow out** (keep every testable specific; cut only the
+how — too-thin is as broken as a mechanics dump), **cut redundancy** (say each thing once), **stay a living document**
+(rewrite in place, never a `## vN` history — git carries versions). Commit per node (`spec: <id> — tidy to contract
+altitude`) with a `Session:` trailer; run `spex spec lint` after each — it must stay at 0 errors.
+Then run bare `spex doctor` and confirm the target no longer carries an altitude finding.

package/spec-cli/templates/spec/project/.plugins/core/idle/spec.md

@@ -10,4 +10,4 @@ block: false
 ---
 Catches the undeclared stop the [[stop-gate]] misses. When the harness signals — via an idle-prompt notification — that the agent is simply sitting idle at its prompt rather than working, this hook marks the session `idle`, so a session that quietly ran out of things to do is not left reading as active on the board.
 
-It acts only on the idle-prompt notification, ignoring every other notification kind. It is guarded so it never clobbers a deliberate declaration: marking idle applies only to a session still in the undeclared `active` state, leaving any considered `awaiting`, `asking`, `parked`, or `error` claim untouched. Together with [[stop-gate]] and [[session-fail]] it closes the last gap where a session could stop without its true state reaching the board.
+It acts only on the idle-prompt notification, ignoring every other notification kind. As a board-lifecycle hook it also acts only on a GOVERNED session — it resolves the record in the global store from the payload's `session_id` and no-ops unless `governed: true` — then marks idle via `spex internal session-idle --session <id>`. It is guarded so it never clobbers a deliberate declaration: marking idle applies only to a session still in the undeclared `active` state, leaving any considered `awaiting`, `asking`, `parked`, or `error` claim untouched. Together with [[stop-gate]] and [[session-fail]] it closes the last gap where a session could stop without its true state reaching the board.

package/spec-cli/templates/spec/project/.plugins/core/mark-active/spec.md

@@ -15,4 +15,6 @@ The state is read from ONE structured field in the hook payload, never sniffed f
 
 The one activity that does NOT count as the session acting is an IN-PROCESS SUBAGENT's tool call (the harness's Task tool — a sub-conversation inside the same process). Such a call fires the parent's hooks carrying the parent's `session_id`, so without a discriminator a supervising parent could never hold a declared state: its own subagents erased every park/ask within seconds and raced the stop-gate into "undeclared stop". The harness stamps subagent-executed calls with a top-level `agent_id` field the parent's own calls never carry; `hp_is_subagent` reads that stamp deterministically (scanning only the pre-`tool_input` payload prefix, where a tool parameter or file content can never fake an unescaped key), and this hook skips the flip entirely. A subagent working is its parent supervising, not the parent moving on — the parent's own next tool call still flips as before.
 
+It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), which it edits directly in shell (the hot path stays jq-free).
+
 This is the freshness half of the [[core]] discipline: it keeps the board honest about whether a session is working, waiting, or asking, so the gates and the dashboard read a true present state rather than a stale one.

package/spec-cli/templates/spec/project/.plugins/core/session-fail/spec.md

@@ -10,4 +10,4 @@ block: false
 ---
 When a turn ends not because the agent declared but because the API itself failed, this hook structurally marks the session `error`. A failed turn is a real outcome the board must show, and without this signal the session would freeze under whatever state it last held — reading as "active" or "awaiting" long after it actually died.
 
-It is non-blocking and unconditional on the failure event: the failure already happened, so the only job is to record it truthfully. By turning an API error into a declared `error` state it keeps the [[stop-gate]] family's invariant intact — a session's displayed state always reflects what is really true of its last turn — for the one stop path the agent cannot narrate itself.
+It is non-blocking and unconditional on the failure event: the failure already happened, so the only job is to record it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. By turning an API error into a declared `error` state it keeps the [[stop-gate]] family's invariant intact — a session's displayed state always reflects what is really true of its last turn — for the one stop path the agent cannot narrate itself.

package/spec-cli/templates/spec/project/.plugins/core/spec-first/spec-first.sh

@@ -1,54 +1,43 @@
 #!/usr/bin/env bash
-# @@@ spec-first - a ONE-SHOT PreToolUse nudge, wired alongside mark-active. The FIRST time a session
-# ACCESSES code — READS or mutates a non-spec file — WITHOUT having touched its spec, it blocks once to
-# remind: read the node's spec AND its neighbors first, then reconcile against it (change the spec, or make
-# the code honor it) — never silently diverge. It once fired only on code-MUTATING tools, which let a pure
-# understanding/analysis session sail past it (the grounding gap): an agent reasoned straight from the code
-# without ever opening the contract. Widening the trigger to any code access (read or edit) closes that. The
-# sentinel makes it fire at most once per session; the re-issued tool call passes. An agent whose first code
-# touch IS its spec — reading or editing it — is blessed silently. Pure shell (no node/tsx).
-# @@@ harness-agnostic - WHICH tool/path counts as a code access is the [[harness-adapter]]'s call, read via
-# hp_code_path (Claude Read/Edit/Write/NotebookEdit + file_path; Codex tool_name:Bash + the parsed command
-# path). So this hook never names Claude's tools — it fires on Claude AND Codex alike.
-# @@@ all sessions, global sentinel - spec-awareness is UNIVERSAL, so this is NOT gated on `governed`: it
-# serves any agent (dashboard or user-self-launched). The once-per-session sentinel lives in the session's
-# GLOBAL store dir (keyed by the harness session_id, grouped per-project — see hp_store_dir), created on
-# demand. The node it points at is read from the global record when the session is bound to one (a dashboard
-# session); a self-launched agent has no record, so it falls back to the generic nudge. cwd = the worktree.
+# @@@ spec-first - a one-shot governed READ gate. It advances only when the adapter resolves a read path AND
+# the spec graph resolves a real `code:` governor for that path. Irrelevant tools, unresolvable reads, and
+# uncovered/related-only files leave the sentinel absent, so any number of ungoverned reads cannot mute the
+# first later governed read. That read spends the gate and blocks once with its actual governor; retries pass.
+# @@@ event vs matcher - materialized shims bind PreToolUse event-wide on every harness. hp_code_path ... read
+# is the ONE adapter matcher that reduces Claude/Codex payload differences to a path. This handler owns the
+# harness-agnostic state transition and governor lookup; it has no tool-name, harness, or filename branches.
+# @@@ all sessions, global sentinel - file governance is independent of a record's `governed` bit, so the
+# same gate serves dashboard and self-launched agents. The sentinel lives in the per-session global store dir
+# (see hp_store_dir) and is created only by the first governed read. cwd = the worktree.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+S="${SPEX:-spex}"
 payload=$(cat 2>/dev/null)
 sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
 sdir=$(hp_store_dir "$sid") || exit 0
-rec="$sdir/session.json"
 sent="$sdir/spec-checked"
-[ -f "$sent" ] && exit 0           # already reminded or blessed this session → silent, every later access passes
+[ -f "$sent" ] && exit 0
 
-# the code file(s) about to be read/edited (empty when this tool is not a code access, or no path resolved) →
-# don't consume the one-shot for a non-code tool. A codex multi-file apply_patch yields several paths (one per
-# line); this tool is a code access if ANY resolved path is a non-spec file.
-paths=$(hp_code_path "$payload" access)
+paths=$(hp_code_path "$payload" read)
 [ -n "$paths" ] || exit 0
+repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
 
-# fires if ANY touched path is code; a touch that is ALL spec files IS spec-first → bless silently (set the
-# sentinel, allow). MUST come first: the nudge tells the agent to read its spec, so a spec-only access can
-# never be the thing we block.
-is_code=0
-while IFS= read -r p; do
-  [ -n "$p" ] || continue
-  case "$p" in */.spec/*|.spec/*|*/spec.md|spec.md) ;; *) is_code=1 ;; esac
+# The internal projection uses the authoritative code: edge resolver and emits stable id<TAB>spec-path rows;
+# empty output means uncovered or related-only, deliberately a non-transition.
+path=""; owner=""
+while IFS= read -r candidate; do
+  [ -n "$candidate" ] || continue
+  governors=$(cd "$repo" && $S internal spec-governors "$candidate" 2>/dev/null)
+  [ -n "$governors" ] || continue
+  path="$candidate"
+  owner=$(printf '%s\n' "$governors" | awk -F '\t' 'BEGIN{sep=""} {printf "%s%s [%s]",sep,$2,$1; sep=", "}')
+  break
 done <<EOF
 $paths
 EOF
-[ "$is_code" = 1 ] || { mkdir -p "$sdir"; : > "$sent"; exit 0; }
+[ -n "$owner" ] || exit 0
 
-# first code access without having touched the spec → set the sentinel (so this fires exactly once), nudge once.
 mkdir -p "$sdir"; : > "$sent"
-node=$(sed -n 's/.*"node"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$rec" 2>/dev/null | head -1)
-if [ -n "$node" ]; then
-  sp=$(find .spec -path "*/$node/spec.md" 2>/dev/null | head -1)
-  where="your node's spec (${sp:-.spec/.../$node/spec.md})"
-else
-  where="the spec node that governs this area (run: spex spec search <topic>)"
-fi
-printf '{"decision":"block","reason":"Before working in this code, read %s FIRST — it is the current contract — and read its NEIGHBORS too (the parent that scopes it, the siblings it borders, the children that refine it), since its intent is only fully legible against the surrounding tree. Then act deliberately: changing the intent? edit the spec first so spec and code land together. implementing existing intent? make the code honor the spec. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at your first code read or edit.)"}\n' "$where"
+reason="Before accessing governed source $path, read its governing spec FIRST: $owner. Read the relevant NEIGHBORS too: the parent that scopes it, the siblings it borders, and the children that refine it. Then reconcile deliberately: change the spec if the intent is changing, or make the code honor it. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at the first governed code read.)"
+esc=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
+printf '{"decision":"block","reason":"%s"}\n' "$esc"
 exit 0

package/spec-cli/templates/spec/project/.plugins/core/spec-first/spec.md

@@ -8,8 +8,10 @@ events:
 order: 20
 block: true
 ---
-A one-shot grounding gate. The first time a session touches code — reads OR mutates any non-spec file — without having opened its spec, it blocks once to demand the right order of work: read the governing node's spec first, since it is the current contract, and read its neighbors too, because a node's intent is only fully legible against the tree around it. Then reconcile deliberately — change the spec if the intent is changing, or make the code honor it — never silently diverge.
+A one-shot, governed-aware READ gate. Its state advances only when the agent is about to read code that has a real governor (`code:` ownership). The first such read creates the session sentinel and blocks once, naming the resolved governing spec and directing the agent through the relevant parent, sibling, and child contracts before retrying. Once that contract-read path has been demanded, later code reads pass.
 
-It blocks at most once per session: a sentinel records the first touch, and every later access passes. Reading is included on purpose, not just editing — a pure analysis session that reasons straight from code without ever opening the contract is exactly the grounding gap this closes. Doing it right earns no nag: an agent whose first code touch IS its spec (reading or editing it) is blessed silently, and the session's own runtime state is ignored without consuming the one-shot.
+The state machine has no transition for an irrelevant tool, an unresolvable path, or an uncovered/related-only file. In particular, any number of ungoverned reads remain allowed without consuming or muting the gate; a later governed read must still block. This is file governance, distinct from a session record's `governed` field: spec-awareness still serves dashboard-launched and user-self-launched agents alike, with the sentinel created on demand in the session's global store directory.
 
-This enforces the read-the-contract-first rule of [[core]] at the moment of first contact, before understanding hardens around ungrounded code.
+Event delivery and semantic matching have separate responsibilities. The hook subscribes to the shared `PreToolUse` lifecycle event because Claude and Codex shims deliver that event broadly. The harness adapter's single `read` matcher decides whether the payload represents a file read and extracts its path; the hook then asks the spec graph whether that path has a governor. Harness payload differences stay inside the adapter, while the gate and its state transitions stay one mechanism.
+
+This enforces the read-the-contract-first rule of [[core]] only where a contract actually exists, at the moment before understanding hardens around governed code.