spexcode 0.1.6 → 0.2.0

package/spec-cli/src/specs.ts

@@ -1,4 +1,5 @@
 import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 import { repoRoot, historyIndex, rowsFor, statsFor, pathsStats, driftIndex, driftFor, fileDiffAt } from './git.js'
 
@@ -93,9 +94,14 @@ function walk(dir: string, parent: string | null, acc: Raw[]) {
 
 // re-key each node to the shortest globally-unique trailing path-suffix (overrides walk's placeholder
 // basename id/parent); the second loop recomputes parent by path-ancestry.
+// A node id is a URL-safe single token ([[id-url-safe]]) — never a '/'-joined path, which would break
+// every `:id` route and fetch that treats an id as one path segment. So the disambiguation separator is
+// '_': like '/' it never occurs inside a dir basename (so the join stays unambiguous), but unlike '/' it
+// is a URL/wikilink/DOM-safe unreserved char, so a collision-qualified id (e.g. `.config_spec-scout`)
+// stays a single token everywhere it is resolved.
 function reId(acc: Raw[]): void {
   const segs = acc.map((r) => r.relPath.split(/[/\\]/).slice(1, -1))   // path under .spec, minus 'spec.md'
-  const suffix = (s: string[], k: number) => s.slice(s.length - k).join('/')
+  const suffix = (s: string[], k: number) => s.slice(s.length - k).join('_')
   for (let i = 0; i < acc.length; i++) {
     const s = segs[i]
     let k = 1
@@ -119,6 +125,30 @@ function raws(): Raw[] {
   return acc
 }
 
+// async twin of walk/raws for the HOT board build ([[board-cache]]): reading each spec.md through
+// fs/promises YIELDS the event loop between files, so a build never stalls a `/health` liveness probe the
+// way the sync walk (one ~450ms uninterrupted stretch) did. Same output as raws() — identical push order
+// (pre-order DFS, dir before children) and the same reId — so every caller reads the same nodes; only
+// loadSpecs (already async, on the hot path) uses it, the light one-shot callers keep the sync raws().
+async function walkAsync(dir: string, parent: string | null, acc: Raw[]): Promise<void> {
+  let myId = parent
+  if (existsSync(join(dir, 'spec.md'))) {
+    myId = basename(dir)
+    const relPath = relative(ROOT, join(dir, 'spec.md'))
+    const { fm, body } = parseFrontmatter(await readFile(join(dir, 'spec.md'), 'utf8'))
+    acc.push({ id: myId, parent, relPath, fm, body })
+  }
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) await walkAsync(join(dir, e.name), myId, acc)
+  }
+}
+async function rawsAsync(): Promise<Raw[]> {
+  const acc: Raw[] = []
+  if (existsSync(SPEC_DIR)) await walkAsync(SPEC_DIR, null, acc)
+  reId(acc)
+  return acc
+}
+
 // spec node(s) that GOVERN a file by the claim rule (exact path, dir-prefix, or *-glob); reads only
 // frontmatter `code:` (cheap, no git) so a per-edit hook can call it. See [[governed-related]].
 export function specOwners(file: string): { id: string; desc: string }[] {
@@ -158,11 +188,17 @@ export function loadSpecsLite(): SpecLite[] {
   }))
 }
 
+// one node's body + parsed parts, filesystem-only (no git). The board omits both to stay lean
+// ([[board-lean]]); the detail view fetches them here when a node opens. null when the id isn't a node.
+export function specContent(id: string): { body: string; parts: ReturnType<typeof parseParts> } | null {
+  const r = raws().find((x) => x.id === id)
+  return r ? { body: r.body.trim(), parts: parseParts(r.body) } : null
+}
+
 export async function loadSpecs() {
   // both indexes are one cached git walk each and independent — fetch them in parallel (async git, off
   // the event loop). Every node below is then a pure lookup.
-  const [idx, didx] = await Promise.all([historyIndex(ROOT), driftIndex(ROOT)])
-  const allRaws = raws()
+  const [idx, didx, allRaws] = await Promise.all([historyIndex(ROOT), driftIndex(ROOT), rawsAsync()])
   return Promise.all(allRaws.map(async (r) => {
     const h = rowsFor(idx, r.relPath)
     // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.
@@ -236,15 +272,15 @@ export async function specDiffAt(id: string, hash: string) {
 // `events`/`order`/`block` are populated only for the `hook` surface (empty/0/false otherwise): which
 // harness lifecycle events the node binds, its deterministic intra-event order, and whether it intends to
 // block (honored only on block-capable events). See loadHookConfig + the hook compiler/dispatcher.
-export type ConfigPreset = { name: string; title: string; desc: string; kind: string; dir: string; files: string[]; body: string; events: string[]; order: number; block: boolean }
+export type ConfigPreset = { name: string; title: string; desc: string; kind: string; dir: string; files: string[]; body: string; events: string[]; order: number; block: boolean; tools: string[] }
 // field-driven surface - a config plugin is a FLAT direct child of a config root (`<root>/<name>/spec.md`)
-// that carries a `surface: system|slash|hook|skill` frontmatter field naming where it plugs in. There are no
-// `slash/`/`system/`/`hook/`/`skill/` bucket dirs (those were graph-invisible grouping dirs with no spec.md, so
+// that carries a `surface: system|command|hook|skill|agent` frontmatter field naming where it plugs in. There are no
+// `command/`/`system/`/`hook/`/`skill/`/`agent/` bucket dirs (those were graph-invisible grouping dirs with no spec.md, so
 // the spec graph skipped them — path != graph); the surface is a FIELD on the node, so the plugin is a real
 // graph child of its root. BOTH config roots participate: `.config` (the instance — DIY dev-flow plugins) and
-// `config` (the project system spec). loadConfig gathers the `slash` surface, loadSystemConfig the `system`
-// surface, loadHookConfig the `hook` surface, loadSkillConfig the `skill` surface; each scans the children under
-// every root and filters by the field. The plugins also show on the board as ordinary spec nodes (via loadSpecs).
+// `config` (the project system spec). loadConfig gathers the `command` surface, loadSystemConfig the `system`
+// surface, loadHookConfig the `hook` surface, loadSkillConfig the `skill` surface, loadAgentConfig the `agent`
+// surface (sub-agent definitions); each scans the children under every root and filters by the field. The plugins also show on the board as ordinary spec nodes (via loadSpecs).
 // root node - the spec tree's single top-level node: the one directory directly under .spec/ that
 // holds a spec.md. The dogfood repo names it 'spexcode'; a repo scaffolded by `spex init` names it
 // 'project' (or whatever the adopter renames it to). Detected DYNAMICALLY so the config loaders resolve
@@ -283,16 +319,16 @@ function bundleFiles(dir: string): string[] {
 // grouping parent may itself be a plugin (e.g. `.config/core` is a `surface: system` contract whose CHILDREN
 // are `surface: hook` nodes). The field filter keeps it safe: a node only gathers if it declares THIS
 // surface, so descending past a matched node never double-counts (children carry a different surface). For
-// `system`/`slash` the result is identical to the old one-level scan on the current tree — every existing
+// `system`/`command` the result is identical to the old one-level scan on the current tree — every existing
 // such node is a flat direct child and no nested node declares those surfaces — so the gather set (hence
-// the appended system prompt and the slash dropdown) is byte-for-byte unchanged.
-function loadSurface(surface: 'slash' | 'system' | 'hook' | 'skill'): ConfigPreset[] {
+// the appended system prompt and the command dropdown) is byte-for-byte unchanged.
+function loadSurface(surface: 'command' | 'system' | 'hook' | 'skill' | 'agent'): ConfigPreset[] {
   const out: ConfigPreset[] = []
   const visit = (nodeDir: string, name: string) => {
     if (existsSync(join(nodeDir, 'spec.md'))) {
       const { fm, body } = parseFrontmatter(readFileSync(join(nodeDir, 'spec.md'), 'utf8'))
       // @@@ skip pending - a `status: pending` plugin is DECLARED INTENT, not yet active. It renders on the
-      // board (via loadSpecs) but must NOT gather: neither a slash preset, nor folded into a system prompt,
+      // board (via loadSpecs) but must NOT gather: neither a command preset, nor folded into a system prompt,
       // nor a live hook. Only built/active plugins surface here, so pending stubs stay inert.
       if (str(fm.surface) === surface && str(fm.status) !== 'pending') {
         out.push({
@@ -306,6 +342,7 @@ function loadSurface(surface: 'slash' | 'system' | 'hook' | 'skill'): ConfigPres
           events: list(fm.events),
           order: Number(str(fm.order, '0')) || 0,
           block: str(fm.block) === 'true',
+          tools: list(fm.tools),
         })
       }
     }
@@ -321,7 +358,7 @@ function loadSurface(surface: 'slash' | 'system' | 'hook' | 'skill'): ConfigPres
   }
   return out.sort((a, b) => a.name.localeCompare(b.name))
 }
-export function loadConfig(): ConfigPreset[] { return loadSurface('slash') }
+export function loadConfig(): ConfigPreset[] { return loadSurface('command') }
 export function loadSystemConfig(): ConfigPreset[] { return loadSurface('system') }
 // the hook handlers (compiled into the per-session hook manifest the dispatcher reads). Each carries its
 // `events`/`order`/`block` binding + co-located script `files`.
@@ -329,3 +366,7 @@ export function loadHookConfig(): ConfigPreset[] { return loadSurface('hook') }
 // the skill bundles (rendered into each harness's auto-discovered SKILL.md dir). Each node's `desc` is the
 // load-trigger and its `body` is the on-demand instructions; loadSurface passes the folder basename as `name`.
 export function loadSkillConfig(): ConfigPreset[] { return loadSurface('skill') }
+// the sub-agent definitions (rendered into each harness's auto-discovered agent dir, e.g. claude's
+// .claude/agents/<name>.md). Like a skill, the node's `desc` is the on-demand load-trigger and its `body` is the
+// agent's system prompt; additionally its `tools` field is the harness tool allowlist for the spawned agent.
+export function loadAgentConfig(): ConfigPreset[] { return loadSurface('agent') }

package/spec-cli/src/supervise.ts

@@ -7,6 +7,7 @@ import { statSync, readdirSync, type Dirent } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { installProcessGuards } from './resilience.js'
+import { listenOrExit } from './listen.js'
 import { resolvePublicConfig, startGateway, ensureDashboardBuilt, resolveDistDir } from './gateway.js'
 import { tsxBin } from './tsx-bin.js'
 
@@ -105,6 +106,14 @@ async function reload(reason: string): Promise<void> {
 }
 
 // the public port: a raw byte pipe to the current backend. Works for HTTP and WS upgrades alike.
+// @@@ connection reaping ([[spec-cli]]) - a raw TCP proxy must tear down the PAIR when EITHER end goes, or it
+// leaks the still-open half. The wedge that started the mass-restore incident was exactly this: every
+// client-side timeout-kill left the client's UPSTREAM socket half-open to the child (the old handler bailed
+// only on `error`, so a clean FIN / a silent drop never reaped the upstream) — 135 leaked conns piled on the
+// child and it looked dead. So a close on either side destroys BOTH (idempotent). The abandoned-but-silent
+// case (no FIN/RST ever arrives) is reaped from the CHILD instead — its HTTP keepAliveTimeout/requestTimeout
+// close an idle/stalled socket, whose close then propagates here — so an active WS/SSE (not idle keep-alive)
+// is never mistaken for abandoned and cut.
 const proxy = net.createServer((client) => {
   const target = current
   if (!target) { client.destroy(); return }
@@ -112,6 +121,12 @@ const proxy = net.createServer((client) => {
   client.setNoDelay(true); up.setNoDelay(true)   // proxy a request promptly — don't let Nagle add latency
   const bail = () => { client.destroy(); up.destroy() }
   client.on('error', bail); up.on('error', bail)
+  client.once('close', () => up.destroy())   // client abandoned → reap its upstream (THE leak that wedged :8787); nothing left to flush to a gone client
+  // upstream gone → drop the client half, but ONLY force it when the close was ABNORMAL: on a normal FIN,
+  // `up.pipe(client)` has already called `client.end()` (writableEnded), so let the client flush the last of a
+  // large response (e.g. /api/board) rather than truncate it with a destroy; a crash/half-open close (no prior
+  // end) still gets reaped.
+  up.once('close', () => { if (!client.writableEnded) client.destroy() })
   client.pipe(up); up.pipe(client)
 })
 
@@ -122,14 +137,19 @@ process.on('SIGTERM', shutdown)
 const first = await boot()
 if (!first) { console.error('[supervisor] initial backend failed to start'); process.exit(1) }
 current = first
+// reap the booted child if a port bind fails, so a "can't own my port → exit" never leaves a zombie child.
+// SIGTERM (not SIGKILL): the child is a `tsx` wrapper around the real node server — SIGKILL kills the wrapper
+// instantly and ORPHANS the server still bound to its port, whereas tsx FORWARDS SIGTERM to it (the same
+// signal the reload drain uses). Sent synchronously here, before the process.exit that follows.
+const reapChild = () => { try { current?.child.kill('SIGTERM') } catch { /* already gone */ } }
 if (publicCfg) {
   // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
   const distDir = resolveDistDir() // bundled <pkg>/dashboard-dist when installed, else monorepo spec-dashboard/dist
   ensureDashboardBuilt(repoRoot, distDir)
-  proxy.listen(proxyPort, '127.0.0.1', () => console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`))
-  startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir })
+  listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`) })
+  startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild })
 } else {
-  proxy.listen(publicPort, () => console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`))
+  listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`) })
 }
 
 // watch every imported source tree; debounce a burst of writes (a merge touching several files across

package/spec-cli/src/tsx-bin.ts

@@ -1,11 +1,20 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
 
 // @@@ tsxBin - where the tsx executable lives, dev-or-published. In the dev monorepo it sits in
-// spec-cli/node_modules; in the PUBLISHED `spexcode` tarball spec-cli is a SUBDIR of the package, so tsx
-// installs one level up at the package ROOT's node_modules. Resolve against both so the supervisor's child
-// spawn and the baked launch/hook SPEX commands work in either layout. `pkgDir` is the spec-cli directory.
+// spec-cli/node_modules; in an installed `spexcode` package npm may hoist it to the consumer's node_modules
+// instead of nesting it under the package. Resolve explicit local candidates first, then let Node's own
+// package resolver walk upward from spec-cli so dev, global, and project-local installs share one mechanism.
+// `pkgDir` is the spec-cli directory.
 export function tsxBin(pkgDir: string): string {
   const candidates = [join(pkgDir, 'node_modules', '.bin', 'tsx'), join(pkgDir, '..', 'node_modules', '.bin', 'tsx')]
-  return candidates.find(existsSync) ?? candidates[0]
+  const local = candidates.find(existsSync)
+  if (local) return local
+  try {
+    const req = createRequire(join(pkgDir, 'package.json'))
+    return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs')
+  } catch {
+    return candidates[0]
+  }
 }

package/spec-cli/src/uninstall.ts

@@ -0,0 +1,146 @@
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { join, resolve, relative } from 'node:path'
+import { execFileSync } from 'node:child_process'
+import { HARNESSES, removeManagedBlock, type HarnessArtifacts } from './harness.js'
+import { runtimeRoot, readConfig, mainCheckout } from './layout.js'
+import { resolveHarnessTargets } from './harness-select.js'
+import { loadSkillConfig, loadAgentConfig } from './specs.js'
+
+// @@@ spex-uninstall - the surgical inverse of spex-init/materialize. init + harness-delivery WRITE the
+// SpexCode footprint into a repo; this REMOVES it, so a project can fully back out. 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 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/.config) is NEVER touched — uninstall
+// removes only generated WIRING, not the spec graph that wiring 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
+
+// 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
+  const manifest = join(dir, '.claude-plugin', 'plugin.json')
+  if (!existsSync(manifest)) return false
+  try {
+    return (JSON.parse(readFileSync(manifest, 'utf8')) as { name?: unknown }).name === 'spexcode'
+  } catch {
+    return false
+  }
+}
+
+// sweep any spexcode-stamped plugin bundle (`<host>/plugins/spexcode`, or a `.claude-plugin/plugin.json` named
+// spexcode) under the project's plugin-host folders. The bundle EMITTER is a later node, so a native-only install
+// has nothing here today; the sweep keeps uninstall a true inverse once it lands (and cleans a hand-dropped one).
+function sweepPluginBundles(proj: string, hosts: readonly string[]): string[] {
+  const removed: string[] = []
+  for (const host of new Set(hosts)) {
+    const pluginsDir = join(proj, host, 'plugins')
+    if (!existsSync(pluginsDir)) continue
+    for (const e of readdirSync(pluginsDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue
+      const dir = join(pluginsDir, e.name)
+      if (isSpexcodeBundle(dir)) {
+        rmSync(dir, { recursive: true, force: true })
+        removed.push(relative(proj, dir))
+      }
+    }
+  }
+  return removed
+}
+
+// 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 {
+    const common = execFileSync('git', ['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+    return join(common, 'hooks')
+  } catch {
+    return 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`.
+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)
+    }
+  }
+  return removed
+}
+
+export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean } = {}): void {
+  const proj = resolve(targetArg ?? process.cwd())
+  console.log(`spex uninstall → ${proj}`)
+
+  // cwd = the project so the .config loaders read THIS tree's surface nodes (the live skill/agent names tell
+  // each adapter's clean() exactly which name-scoped on-demand files were its to remove).
+  const prevCwd = process.cwd()
+  let arts: HarnessArtifacts = { skills: [], agents: [] }
+  try {
+    process.chdir(proj)
+    arts = { skills: loadSkillConfig().map((s) => s.name), agents: loadAgentConfig().map((a) => a.name) }
+  } catch {
+    // no readable .config (already partly torn down, or never adopted) — clean still strips the harness wiring.
+  } finally {
+    process.chdir(prevCwd)
+  }
+
+  // 1. every harness's own artifacts — clean() is the adapter's surgical inverse (managed contract block w/
+  //    deleteIfEmpty, generated shim, trust block, named skill/agent files). materialize cleans only UNSELECTED
+  //    harnesses; uninstall cleans EVERY one. clean() already calls removeTrust, so it is the full inverse.
+  for (const h of HARNESSES) h.clean(proj, arts)
+
+  // 2. the shared .gitignore block — the one in-tree artifact no adapter owns (materialize writes it directly),
+  //    so strip it directly too: the managed `#` block, deleteIfEmpty so a wholly-ours .gitignore is removed.
+  removeManagedBlock(join(proj, '.gitignore'), ['# ', ''], true)
+
+  // 3. the global per-project store — manifest + content-hash marker + gate lock + session records. This is the
+  //    runtime tier, not the user's spec asset, so the whole dir is ours.
+  let store: string | null = null
+  try {
+    store = runtimeRoot(proj)
+    rmSync(store, { recursive: true, force: true })
+  } catch {
+    store = null
+  }
+
+  // 4. any spexcode-stamped plugin bundle, under the configured + standard plugin-host folders.
+  let pluginHosts: string[] = [...DEFAULT_PLUGIN_HOSTS]
+  try {
+    const targets = resolveHarnessTargets(readConfig(mainCheckout(proj)).harnesses)
+    pluginHosts = [...pluginHosts, ...targets.filter((t) => t.kind === 'plugin').map((t) => (t as { folder: string }).folder)]
+  } catch {
+    // an illegal harnesses set doesn't block backout — fall through to the standard hosts.
+  }
+  const bundles = sweepPluginBundles(proj, pluginHosts)
+
+  console.log(`✓ pruned harness artifacts (CLAUDE.md/AGENTS.md block, shims, Codex trust, skills, sub-agents) for ${HARNESSES.map((h) => h.id).join(', ')}`)
+  console.log('✓ stripped the .gitignore spexcode block')
+  if (store) console.log(`✓ removed the global per-project store (${store})`)
+  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).
+  if (opts.hooks) {
+    const removed = removeHooks(proj)
+    if (removed.length) console.log(`✓ removed git hooks (${removed.join(', ')})`)
+    else console.log('• no spexcode git hooks to remove')
+  } else {
+    console.log('• left git hooks in place (per-clone; pass --hooks to remove the spexcode ones)')
+  }
+
+  console.log(`
+SpexCode wiring removed. Your spec data is untouched:
+  • .spec/ and .config/ remain — your spec graph is YOURS, never deleted by uninstall.
+  • To re-adopt later: \`spex init\` regenerates the shims, contract, trust, and global store.`)
+}

package/spec-cli/templates/hooks/post-merge

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# @@@ issue nudge (post-merge) - the taste store ([[local-issues]]) fires AFTER the work lands, not while the
+# agent is finishing it: the agent's own task comes first. Merge is dispatched to the session's OWN agent
+# (see [[dispatch]]), so this hook runs in that live merge turn and its stdout reaches the agent as the merge
+# command's own output — a git-native nudge that costs no harness block-cap and reaches a self-launched agent
+# too. GUARDED to the `merge node/<id>:` commit, so an ordinary `git pull`/unrelated merge never nags.
+#
+# The nudge TEXT and the on/off toggle both live in the CLI (`spex issues nudge <node>` prints nothing when
+# the feature is OFF in spexcode.json), so this hook is a THIN resolver + caller: resolve `spex` the same
+# three ways the pre-commit hook does, pass the merged node, echo whatever it prints. No CLI resolvable → no
+# nudge (safe degradation, same as the lint shim's advisory mode).
+subj=$(git log -1 --format=%s 2>/dev/null)
+case "$subj" in
+  "merge node/"*) ;;
+  *) exit 0 ;;
+esac
+node=$(printf '%s' "$subj" | sed -n 's#^merge \(node/[^:]*\):.*#\1#p')
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+if command -v spex >/dev/null 2>&1; then
+  spex issues nudge "$node"
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  "$repo_root/node_modules/.bin/spex" issues nudge "$node"
+elif [ -x "$main_root/spec-cli/node_modules/.bin/tsx" ] && [ -f "$main_root/spec-cli/src/cli.ts" ]; then
+  "$main_root/spec-cli/node_modules/.bin/tsx" "$main_root/spec-cli/src/cli.ts" issues nudge "$node"
+fi
+exit 0

package/spec-cli/templates/hooks/pre-commit

@@ -1,51 +1,71 @@
 #!/usr/bin/env bash
-# @@@ main-guard - the worktree model: never author directly on main; main only RECEIVES merges.
-# Reject a direct commit while HEAD is main. Merges pass (MERGE_HEAD present).
+# @@@ shared spex runner - resolve the `spex` CLI ONCE, into spex_cli(), so BOTH the main-guard trunk
+# lookup and the spec-lint shim shim through the same mechanism (no duplicated, drift-prone resolution).
+# This must work for BOTH ways this hook ships: a real project that installed @spexcode/spec-cli, and the
+# SpexCode monorepo dogfooding itself from source. cwd stays the committing worktree either way. main_root
+# is the parent of the shared git *common* dir (= layout.ts mainCheckout()); a fresh session worktree has
+# no node_modules of its own, so the dogfood tsx path reaches the main checkout's. First that exists wins:
+#   1. `spex` on PATH                  - installed globally / on the shell PATH.
+#   2. <repo>/node_modules/.bin/spex   - a project that did `npm i @spexcode/spec-cli` (the dep's bin).
+#   3. monorepo tsx + cli.ts by path   - dogfood: run the CLI from source.
+main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+spex_kind=
+if command -v spex >/dev/null 2>&1; then
+  spex_kind=path
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  spex_kind=local
+elif [ -x "$main_root/spec-cli/node_modules/.bin/tsx" ] && [ -f "$main_root/spec-cli/src/cli.ts" ]; then
+  spex_kind=tsx
+fi
+spex_cli() {
+  case "$spex_kind" in
+    path)  spex "$@" ;;
+    local) "$repo_root/node_modules/.bin/spex" "$@" ;;
+    tsx)   "$main_root/spec-cli/node_modules/.bin/tsx" "$main_root/spec-cli/src/cli.ts" "$@" ;;
+    *)     return 127 ;;
+  esac
+}
+
+# @@@ main-guard - the worktree model: never author directly on the trunk; the trunk only RECEIVES merges.
+# Reject a direct commit while HEAD is the trunk. Merges pass (MERGE_HEAD present).
 # Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
+#
+# The trunk is resolved the SAME way the rest of SpexCode resolves it — `spex internal trunk` = layout.ts
+# mainBranch() (config override → the main checkout's current branch → 'main') — so the guard protects
+# whatever the repo's trunk is actually named, NOT a hardcoded 'main' (which gave a `master`/non-`main`
+# trunk zero protection). When the CLI isn't resolvable (advisory mode), fall back to a pure-git
+# auto-detect of the main checkout's current branch, then 'main' — still protecting a non-`main` trunk.
 branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo)
 git_dir=$(git rev-parse --git-dir 2>/dev/null)
-if [ "$branch" = "main" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
-  echo "✗ SpexCode: direct commits on main are blocked." >&2
+trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
+# Fallback auto-detect: the main checkout's current branch. Strip the hook's exported GIT_DIR/
+# GIT_INDEX_FILE first — otherwise they pin discovery to the COMMITTING worktree and `-C "$main_root"`
+# is ignored, so it would read THIS branch and think every node branch is the trunk. (`spex internal
+# trunk` above is immune: layout.ts mainBranch() resolves through git.ts's env-stripping git().)
+[ -n "$trunk" ] || trunk=$(env -u GIT_DIR -u GIT_INDEX_FILE git -C "$main_root" symbolic-ref --short HEAD 2>/dev/null)
+[ -n "$trunk" ] || trunk=main
+if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
+  echo "✗ SpexCode: direct commits on $trunk (the trunk) are blocked." >&2
   echo "  Work in a worktree (.worktrees/<node>, branch node/<id>) and merge back." >&2
   echo "  Merges pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
   exit 1
 fi
 
 # @@@ spec-lint - the hook is just a thin shim over `spex lint`. It blocks on errors only (broken
-# spec↔code links); coverage/drift are warnings. Bypass with SPEXCODE_SKIP_LINT=1.
-#
-# Resolving the `spex` CLI must work for BOTH ways this hook ships: a real project that installed
-# @spexcode/spec-cli, and the SpexCode monorepo dogfooding itself from source. cwd stays the committing
-# worktree either way, so lint validates THIS worktree's `.spec` (repoRoot() discovers the cwd's toplevel
-# via git.ts, which strips the hook's GIT_DIR). First resolution that exists wins:
-#   1. `spex` on PATH                  - installed globally / on the shell PATH.
-#   2. <repo>/node_modules/.bin/spex   - a project that did `npm i @spexcode/spec-cli` (the dep's bin).
-#   3. monorepo tsx + cli.ts by path   - dogfood: run the CLI from source. main is the parent of the shared
-#      git *common* dir (a fresh session worktree has no node_modules of its own, so we reach the main one).
+# spec↔code links); coverage/drift are warnings. Bypass with SPEXCODE_SKIP_LINT=1. It shims through the
+# shared spex_cli() resolved above (repoRoot() discovers the cwd's toplevel via git.ts, which strips the
+# hook's GIT_DIR, so lint validates THIS worktree's `.spec`).
 if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
-  main_root=$(dirname "$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)")
-  repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
-  # @@@ one resolved runner - resolve `spex` ONCE into spex_run(), so every spec-cli pre-commit check
-  # (lint, the yatsu stray-blob backstop) shims through the same mechanism instead of re-resolving.
-  spex_found=1
-  if command -v spex >/dev/null 2>&1; then
-    spex_run() { spex "$@" >&2; }
-  elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
-    spex_run() { "$repo_root/node_modules/.bin/spex" "$@" >&2; }
-  elif [ -x "$main_root/spec-cli/node_modules/.bin/tsx" ] && [ -f "$main_root/spec-cli/src/cli.ts" ]; then
-    spex_run() { "$main_root/spec-cli/node_modules/.bin/tsx" "$main_root/spec-cli/src/cli.ts" "$@" >&2; }
-  else
-    spex_found=0
-  fi
-  if [ "$spex_found" = 1 ]; then
-    if ! spex_run lint; then
+  if [ -n "$spex_kind" ]; then
+    if ! spex_cli lint >&2; then
       echo "✗ SpexCode: spec-lint failed — fix the spec↔code links or bypass with SPEXCODE_SKIP_LINT=1." >&2
       exit 1
     fi
     # @@@ yatsu backstop - reject a staged yatsu offender: a stray pixel blob copied into the tree (blobs
     # belong in the shared git common dir, never committed) OR a malformed yatsu.md (a scenario schema
     # violation). Logic lives in spec-yatsu; this is the lint-shim's twin. (this node's contract)
-    if ! spex_run yatsu check-staged; then
+    if ! spex_cli yatsu check-staged >&2; then
       echo "✗ SpexCode: yatsu check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
       exit 1
     fi

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

@@ -1,14 +1,37 @@
 #!/usr/bin/env bash
-# @@@ session-stamp - auto-attribute a commit to the Claude Code session that authored it. SpexCode
-# reads the `Session:` trailer as a version's attribution (git is the database). CLAUDE_CODE_SESSION_ID
-# is the live session id Claude Code exports — and it EQUALS the `--session-id` we launch worktree
-# sessions with, so a spec node's version attribution links to the live session in the dashboard's
-# session window for free. No-op outside Claude Code, or if a Session: trailer is already present
-# (so the dogfood ritual / a human can still set it explicitly).
+# @@@ session-stamp - auto-attribute a commit to the SESSION that authored it, ACROSS HARNESSES. SpexCode
+# reads the `Session:` trailer as a version's attribution (git is the database), keyed by the SpexCode record
+# id so the dashboard's session window links to it. Resolving that id is a harness-adapter concern, mirroring
+# `envSessionId` / the shell `hp_store_dir` alias:
+#   - Claude exports CLAUDE_CODE_SESSION_ID, which EQUALS the record id → stamp it directly.
+#   - Codex has no such equality: its per-command CODEX_THREAD_ID is the THREAD id, not the record key, and the
+#     SHARED per-project app-server means SPEXCODE_SESSION_ID is contaminated with the FIRST session's id — so
+#     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.
+# 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"
-sid="${CLAUDE_CODE_SESSION_ID:-}"
-[ -z "$sid" ] && exit 0
 grep -qiE '^Session:[[:space:]]' "$msg_file" && exit 0
+
+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
+  fi
+fi
+
+[ -z "$sid" ] && exit 0
 printf '\nSession: %s\n' "$sid" >> "$msg_file"
 exit 0

package/spec-cli/templates/presets/careful/.config/clarify-before-code/spec.md

@@ -0,0 +1,11 @@
+---
+title: clarify-before-code
+surface: system
+status: active
+hue: 30
+desc: A config plugin (careful preset) — before coding, the worker surfaces ambiguities as explicit assumptions in its proposal, and blocks for a live question only on a load-bearing one.
+code:
+---
+Before you write code, enumerate the ambiguities, contradictions, and technical risks in your task. Most of them are cheap: resolve a cheap one by **stating your assumption explicitly** in the work you propose. SpexCode's manager-merge review is already the hard gate — a misread surfaces there, in the proposal, not in a live interrogation of the human. So clarification shifts **left into the artifact**: the diff and the spec body say what you assumed, and the reviewer catches a wrong assumption at merge.
+
+Block for a live question (the `needs-input` channel) **only on a load-bearing ambiguity** — one where guessing wrong would waste the whole node. A small or clear task proceeds without asking. This is deliberately the opposite of "every agent asks the user": the default is to proceed on a stated assumption, and the human is interrupted only when proceeding blind would burn the work.

package/spec-cli/templates/spec/project/.config/core/spec-of-file/spec-of-file.sh

@@ -16,6 +16,30 @@ S="${SPEX:-spex}"
 payload=$(cat 2>/dev/null)
 sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
 sdir=$(hp_store_dir "$sid") || exit 0
+repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+repo=$(cd "$repo" 2>/dev/null && pwd -P) || exit 0
+
+hp_actionable_repo_path() {
+  local raw="$1" target dir base abs rel
+  case "$raw" in
+    /*) target="$raw" ;;
+    *)  target="$PWD/$raw" ;;
+  esac
+  dir=${target%/*}; base=${target##*/}
+  [ "$dir" = "$target" ] && dir=.
+  abs=$(cd "$dir" 2>/dev/null && printf '%s/%s' "$(pwd -P)" "$base") || return 1
+  case "$abs" in
+    "$repo"/*) rel=${abs#"$repo"/} ;;
+    *) return 1 ;;
+  esac
+  [ -n "$rel" ] || return 1
+  # editing the spec itself is not a governed-code edit -> nothing to annotate.
+  case "$rel" in .spec/*|*/.spec/*|*/spec.md|spec.md|.git/*) return 1 ;; esac
+  # Speak only for files Git would care about: tracked files, or untracked files that are not ignored.
+  git -C "$repo" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1 && { printf '%s' "$rel"; return 0; }
+  git -C "$repo" check-ignore -q -- "$rel" && return 1
+  printf '%s' "$rel"
+}
 
 # the code file(s) just MUTATED (empty when this tool didn't mutate a file, e.g. a pure read). A codex
 # multi-file apply_patch yields several paths (one per line) — annotate EACH governed code file, once.
@@ -25,11 +49,10 @@ led="$sdir/spec-of-file-seen"   # dedupe: once per session per file. Lists alrea
 msg=""
 while IFS= read -r path; do
   [ -n "$path" ] || continue
-  # editing the spec itself is not a governed-code edit → nothing to annotate.
-  case "$path" in */.spec/*|.spec/*|*/spec.md|spec.md) continue ;; esac
+  path=$(hp_actionable_repo_path "$path") || continue
   [ -f "$led" ] && grep -qxF -- "$path" "$led" && continue
   mkdir -p "$sdir"; echo "$path" >> "$led"
-  m=$($S owner "$path" --actionable 2>/dev/null)   # --actionable: silent on a sanely-owned file; speaks only for an OVER-owned / uncovered file
+  m=$(cd "$repo" && $S owner "$path" --actionable 2>/dev/null)   # --actionable: silent on a sanely-owned file; speaks only for an OVER-owned / uncovered file
   [ -n "$m" ] || continue
   msg="${msg:+$msg
 }$m"

package/spec-cli/templates/spec/project/.config/core/spec.md

@@ -11,3 +11,7 @@ Commit your spec node and the code it justifies BEFORE you declare done or propo
 A spec body is a living current-state document: it states the node's PRESENT intent and is rewritten in place. Never accrete a "## vN" changelog heading, and never add current-state or verdict sections — version history is git's job, not the body's.
 
 An independently-scoped feature gets its OWN spec node: if you build something separately scoped while working, create a sibling node for it rather than bundling it into your assigned node's commit (cosmetic polish riding along is the smell).
+
+Keep the loss signal honest for what you changed — yatsu is the signal the optimizer reads, so a gap is a blind spot. Changed a node that carries a `yatsu.md`? Re-measure it: run its scenario, compare to the expected, and file the result with `spex yatsu eval <node>`. Made an obvious frontend change to a node with NO `yatsu.md`? Give it one — a scenario (description + expected) — so its loss can be measured. A frontend scenario is measured through the **actual running product** — drive a real browser, read the real DOM and capture a screenshot (or video), never reason about the code — and that real observation is filed as the reading, not left as an ad-hoc check you ran but never recorded. `spex yatsu scan --changed` shows the gaps in exactly the nodes you touched.
+
+Don't reverse-engineer the file formats: `spex guide spec` and `spex guide yatsu` print the full spec.md and yatsu.md schema on demand. This prompt is the clue; that manual carries the detail. The CLI explains itself the same way: `spex help` is the command map (grouped by the loop each verb serves), `spex help <command>` one command's usage — when unsure of a verb, ask the tool, don't guess.