spexcode 0.1.0

package/src/supervise.ts

@@ -0,0 +1,158 @@
+// SO_REUSEPORT is ENOTSUP on macOS/Node, so the supervisor owns the public port as a raw-TCP proxy and
+// runs the Hono server as a child on a private port (raw piping carries WS upgrades too).
+import net from 'node:net'
+import http from 'node:http'
+import { spawn, type ChildProcess } from 'node:child_process'
+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 { resolvePublicConfig, startGateway, ensureDashboardBuilt, resolveDistDir } from './gateway.js'
+
+// the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
+// logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
+installProcessGuards()
+
+const here = dirname(fileURLToPath(import.meta.url))
+const tsx = join(here, '..', 'node_modules', '.bin', 'tsx')   // this package's own tsx (no build step)
+const entry = join(here, 'index.ts')                          // the real Hono server
+const publicPort = Number(process.env.PORT || 8787)
+
+// @@@ public mode ([[public-mode]]) - with `spex serve --public`, the supervisor is NOT the internet face:
+// the gateway is. The raw-TCP proxy retreats to a loopback internal port (the trusted boundary local agents
+// reach) and the password-gated TLS gateway takes the public port, proxying /api + WS back to that loopback
+// port. Off → unchanged: the proxy itself owns the public port and SPEXCODE_API_URL points there.
+const publicCfg = resolvePublicConfig(join(here, '..', '..'))
+// the port the raw-TCP proxy actually binds: a private loopback port in public mode, the public port otherwise.
+const proxyPort = publicCfg ? await freePort() : publicPort
+// what launched agents inherit as their `spex` endpoint — ALWAYS the loopback proxy, so local agents never
+// meet the password gate (loopback is the trust boundary). Equals the public port when public mode is off.
+const childApiBase = `http://127.0.0.1:${proxyPort}`
+
+// every package src tree the child imports at runtime; spec-dashboard is absent (its own vite/HMR).
+const repoRoot = join(here, '..', '..')
+const watchRoots = [
+  here,                                  // spec-cli/src — the backend's own source
+  join(repoRoot, 'spec-forge', 'src'),
+  join(repoRoot, 'spec-yatsu', 'src'),
+]
+
+type Backend = { port: number; child: ChildProcess }
+let current: Backend | null = null   // which internal port new proxy connections forward to
+let reloading = false                // single-flight guard for reload()
+let pending = false                  // a code change arrived mid-reload → reload again when done
+
+// grab an ephemeral port by binding :0, then release it for the child to claim (negligible rebind race).
+function freePort(): Promise<number> {
+  return new Promise((res, rej) => {
+    const s = net.createServer()
+    s.once('error', rej)
+    s.listen(0, '127.0.0.1', () => { const p = (s.address() as net.AddressInfo).port; s.close(() => res(p)) })
+  })
+}
+
+// poll GET /health until 200; ~15s budget (150 × 100ms) covers a slow tsx+Hono cold start. False → keep old.
+function waitHealthy(port: number, tries = 150): Promise<boolean> {
+  return new Promise((resolve) => {
+    const retry = (left: number) => { if (left <= 1) resolve(false); else setTimeout(() => attempt(left - 1), 100) }
+    const attempt = (left: number) => {
+      const req = http.get({ host: '127.0.0.1', port, path: '/health', timeout: 1000 }, (r) => {
+        r.resume()
+        if (r.statusCode === 200) resolve(true); else retry(left)
+      })
+      req.on('error', () => retry(left))
+      req.on('timeout', () => { req.destroy(); retry(left) })
+    }
+    attempt(tries)
+  })
+}
+
+// boot a fresh backend child on a free internal port and wait until it's serving.
+async function boot(): Promise<Backend | null> {
+  const port = await freePort()
+  // PORT pins the child's PRIVATE bind port; SPEXCODE_API_URL pins everything the child SPAWNS (launched
+  // sessions + their hooks) at the PUBLIC port, so a launched agent's own `spex` reaches the stable proxy
+  // and never inherits this ephemeral, soon-retired port (apiBase() prefers SPEXCODE_API_URL over PORT).
+  const child = spawn(tsx, [entry], { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: process.env.SPEXCODE_API_URL || childApiBase } })
+  // if the ACTIVE backend dies unexpectedly (crash, OOM), restart it so the public port keeps serving.
+  // Planned retirement sets current to the NEW child first, so the old child's exit fails this identity
+  // check and is ignored. boot()'s ~5s health budget rate-limits any crash loop.
+  child.on('exit', (code, sig) => {
+    if (current?.child === child) { console.error(`[supervisor] active backend exited (${code ?? sig}) — restarting`); current = null; void reload('crash') }
+  })
+  if (await waitHealthy(port)) return { port, child }
+  try { child.kill('SIGKILL') } catch { /* already gone */ }
+  return null
+}
+
+// boot → health-gate → atomic flip → drain old. The flip is a single assignment; the old child is killed
+// only after a drain delay, so a connection mid-flip is never refused.
+async function reload(reason: string): Promise<void> {
+  if (reloading) { pending = true; return }
+  reloading = true
+  try {
+    do {
+      pending = false
+      const next = await boot()
+      if (!next) { console.error(`[supervisor] new backend failed health check (${reason}) — keeping current`); break }
+      const old = current
+      current = next   // atomic flip: new connections now route to `next`
+      console.log(`[supervisor] reloaded (${reason}) → backend :${next.port}`)
+      if (old) setTimeout(() => { try { old.child.kill('SIGTERM') } catch { /* already gone */ } }, 500)
+    } while (pending)
+  } finally { reloading = false }
+}
+
+// the public port: a raw byte pipe to the current backend. Works for HTTP and WS upgrades alike.
+const proxy = net.createServer((client) => {
+  const target = current
+  if (!target) { client.destroy(); return }
+  const up = net.connect(target.port, '127.0.0.1')
+  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.pipe(up); up.pipe(client)
+})
+
+const shutdown = () => { try { current?.child.kill('SIGTERM') } catch { /* */ } process.exit(0) }
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+
+const first = await boot()
+if (!first) { console.error('[supervisor] initial backend failed to start'); process.exit(1) }
+current = first
+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 })
+} else {
+  proxy.listen(publicPort, () => 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
+// packages) into one reload. A root that can't be watched (a package absent in some checkout) is logged
+// and skipped — the supervisor owns the public port and must never die over a missing watch.
+// fs.watch — even recursive — is NOT reliable for a long-lived supervisor: its inotify watches are silently
+// dropped when a watched dir is rewritten (a git merge, a `materialize`) and NEVER re-established, so reloads
+// quietly stop (observed: the watcher fired a few times then went deaf for hours). A cheap mtime poll can't go
+// deaf: every 2s, take the newest .ts/.js/.json mtime across the trees; a jump triggers the debounced reload
+// (a burst of writes still lands as one). Polling a few small src trees is negligible cost.
+let timer: NodeJS.Timeout | undefined
+const newestMtime = (dir: string): number => {
+  let max = 0
+  let entries: Dirent[]
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return 0 }   // a tree absent in some checkout → skip
+  for (const e of entries) {
+    if (e.isDirectory()) { if (e.name !== 'node_modules') max = Math.max(max, newestMtime(join(dir, e.name))) }
+    else if (/\.(ts|js|mjs|json)$/.test(e.name)) { try { max = Math.max(max, statSync(join(dir, e.name)).mtimeMs) } catch { /* raced unlink */ } }
+  }
+  return max
+}
+const scanMtime = (): number => { let m = 0; for (const root of watchRoots) m = Math.max(m, newestMtime(root)); return m }
+let lastMtime = scanMtime()   // baseline at boot — only a LATER change reloads
+setInterval(() => {
+  const m = scanMtime()
+  if (m > lastMtime) { lastMtime = m; clearTimeout(timer); timer = setTimeout(() => void reload('code change'), 150) }
+}, 2000).unref()

package/src/uploads.ts

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join } from 'node:path'
+
+// the backend's tmpdir — same /tmp home as the rendezvous sockets (sessions.ts), shared with the worker.
+const UPLOAD_DIR = join(tmpdir(), 'spexcode-uploads')
+
+// a generous ceiling so a stray huge upload can't quietly fill /tmp — over it we fail loud (the route 413s)
+// rather than write. Real screenshots/attachments sit far under this.
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+
+// strip a client-supplied filename to a safe basename: no directory parts, only [A-Za-z0-9._-], no leading
+// dots — so a crafted name (`../../etc/x`, `.bashrc`) can never escape UPLOAD_DIR. The extension is kept for
+// readability; an empty/exotic name falls back to a generic stem.
+function safeName(name: string): string {
+  const base = basename(name || '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '')
+  return base || 'upload'
+}
+
+let seq = 0
+
+// write one uploaded file into UPLOAD_DIR under a collision-proof `<time>-<seq>-<name>` stem and return its
+// absolute path — the string the dashboard splices into the prompt. Creates the dir on first use.
+export async function saveUpload(file: File): Promise<string> {
+  mkdirSync(UPLOAD_DIR, { recursive: true })
+  const buf = Buffer.from(await file.arrayBuffer())
+  const stamp = `${Date.now().toString(36)}-${(seq++).toString(36)}`
+  const path = join(UPLOAD_DIR, `${stamp}-${safeName(file.name)}`)
+  writeFileSync(path, buf)
+  return path
+}

package/templates/hooks/pre-commit

@@ -0,0 +1,57 @@
+#!/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).
+# Escape hatch for seeding / eager topology: SPEXCODE_ALLOW_MAIN=1 git commit …
+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
+  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).
+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
+      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
+      echo "✗ SpexCode: yatsu check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
+      exit 1
+    fi
+  else
+    # Advisory hook: no CLI found (project hasn't installed @spexcode/spec-cli; monorepo not `npm install`ed).
+    echo "• SpexCode: spec-lint skipped — no \`spex\` CLI found (install @spexcode/spec-cli); CI still enforces." >&2
+  fi
+fi
+exit 0

package/templates/hooks/prepare-commit-msg

@@ -0,0 +1,14 @@
+#!/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).
+set -euo pipefail
+msg_file="$1"
+sid="${CLAUDE_CODE_SESSION_ID:-}"
+[ -z "$sid" ] && exit 0
+grep -qiE '^Session:[[:space:]]' "$msg_file" && exit 0
+printf '\nSession: %s\n' "$sid" >> "$msg_file"
+exit 0

package/templates/spec/project/.config/core/idle/idle.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# On an idle_prompt notification, mark the session idle (the active-only guard in `session idle` keeps a
+# deliberate awaiting/asking/parked/error declaration from being clobbered). GATED on `governed`: only a
+# dashboard-launched session has board state to mark — a self-launched agent's idle is none of our business.
+# State lives in the per-session GLOBAL record session.json (keyed by the harness session_id, grouped per-
+# project — see hp_store_dir); the id is passed to the cli via `--session` so it writes the right record
+# without depending on the worktree (which no longer holds any session file). NOTE the Notification event is
+# Claude-only ([[harness-adapter]]: Codex fires no Notification), so this never runs under Codex.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+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"
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+[ "$(hp_notification_type "$payload")" = idle_prompt ] && exec ${SPEX:-spex} session idle --session "$sid"

package/templates/spec/project/.config/core/idle/spec.md

@@ -0,0 +1,13 @@
+---
+title: idle
+surface: hook
+status: active
+hue: 200
+events:
+- Notification
+order: 10
+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.

package/templates/spec/project/.config/core/mark-active/mark-active.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE freshness hook, wired to BOTH UserPromptSubmit and PreToolUse. It branches
+# on ONE structured signal read straight from the hook payload (stdin JSON), so the state is HARD — never
+# text-sniffed from the TUI:
+#   the agent is pausing to ask the HUMAN (hp_is_ask) → status: asking, with the question text as the note
+#                                  (the deterministic capture of a question).
+#   any other tool, or a prompt submit → the agent is working → status: active (drop a now-stale proposal/note).
+# WHAT counts as "asking" is the [[harness-adapter]]'s call (Claude: the AskUserQuestion tool; Codex: the
+# request_user_input tool) — read via hp_is_ask, so this hook never names a harness tool.
+# Fires BEFORE the tool runs, so a `spex session done` declaration (itself a tool) lands AFTER this and wins;
+# the next real tool flips back to active, forcing a fresh Stop-gate declaration. Pure shell (no node/tsx) so
+# it stays cheap on every tool call — it value-replaces status/proposal/note in session.json with sed, never jq.
+# @@@ global store - state lives NOT in the worktree but in the per-session GLOBAL record session.json, keyed
+# by the harness session_id, grouped per-project (see hp_store_dir). GATED on `governed`: a user-self-launched
+# (non-governed) session has no board to feed, so this no-ops on it. cwd = the session worktree.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+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"
+# board-lifecycle gate: only a GOVERNED (dashboard-launched) session has a board state to maintain.
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  status=asking
+  note=$(hp_ask_note "$payload")   # first question's text → the note (best-effort)
+else
+  status=active
+  note=
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case).
+[ "$status" = active ] && [ "$(jget status)" = active ] && [ -z "$(jget proposal)" ] && [ -z "$(jget note)" ] && exit 0
+
+# value-replace status + clear proposal + (re)set note, in place. The record is written one-field-per-line
+# with these keys ALWAYS present (sessions.ts writeRecord), so each is a single value substitution — no key
+# add/remove, no JSON parser. Escape \ / & in the note for the sed REPLACEMENT (the note never contains ").
+note_esc=$(printf '%s' "$note" | sed 's/[\\/&]/\\&/g')
+tmp=$(mktemp) || exit 0
+sed -e "s/\(\"status\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$status\"/" \
+    -e "s/\(\"proposal\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"\"/" \
+    -e "s/\(\"note\"[[:space:]]*:[[:space:]]*\)\"[^\"]*\"/\1\"$note_esc\"/" \
+    "$rec" > "$tmp" && mv "$tmp" "$rec"
+exit 0

package/templates/spec/project/.config/core/mark-active/spec.md

@@ -0,0 +1,16 @@
+---
+title: mark-active
+surface: hook
+status: active
+hue: 200
+events:
+- UserPromptSubmit
+- PreToolUse
+order: 10
+block: false
+---
+The single freshness signal for a session. Any work a session does — a new prompt, or any tool about to run — flips its declared state to `active`, which also drops a now-stale proposal or note: once the agent is moving again, an old "ready to merge" claim no longer stands. The one exception is asking the human: when the tool is AskUserQuestion the state becomes `asking`, carrying the question itself as the note, so a pause for the human is captured deterministically without the agent having to also declare it.
+
+The state is read from ONE structured field in the hook payload, never sniffed from the terminal UI, so the signal is hard rather than guessed. Because it fires before the tool runs, a deliberate [[stop-gate]] declaration (itself made via a tool) lands after this and wins; the next real tool flips back to `active`, forcing a fresh declaration at the following stop. It is pure shell so it stays cheap firing on every tool call.
+
+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/templates/spec/project/.config/core/session-fail/fail.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Mark the session errored when a turn ends on an API failure (StopFailure). GATED on `governed`: only a
+# dashboard-launched session has board state to mark. State lives in the per-session GLOBAL record (keyed by
+# the harness session_id, grouped per-project — see hp_store_dir); the id is passed to the cli via `--session`
+# so it writes the right record without depending on the worktree.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+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"
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+exec ${SPEX:-spex} session fail --session "$sid"

package/templates/spec/project/.config/core/session-fail/spec.md

@@ -0,0 +1,13 @@
+---
+title: session-fail
+surface: hook
+status: active
+hue: 200
+events:
+- StopFailure
+order: 10
+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.

package/templates/spec/project/.config/core/spec-first/spec-first.sh

@@ -0,0 +1,54 @@
+#!/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.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+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
+
+# 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)
+[ -n "$paths" ] || 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
+done <<EOF
+$paths
+EOF
+[ "$is_code" = 1 ] || { mkdir -p "$sdir"; : > "$sent"; 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 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"
+exit 0

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

@@ -0,0 +1,15 @@
+---
+title: spec-first
+surface: hook
+status: active
+hue: 200
+events:
+- PreToolUse
+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.
+
+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.
+
+This enforces the read-the-contract-first rule of [[core]] at the moment of first contact, before understanding hardens around ungrounded code.

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# @@@ spec-of-file - a PostToolUse ANNOTATE hook: the FIRST time a session edits a given file, it tells the
+# agent which spec node(s) GOVERN it — and, when a file is OVER-owned (> maxOwners), flags it as doing too
+# much and points at the split — so the contract is in view AT THE MOMENT OF THE EDIT, not just later at
+# commit (lint/drift). NON-BLOCKING (additionalContext only — never a verdict) and dedup'd PER FILE via a
+# ledger, so a 50-edit refactor annotates each file ONCE. Uses MAIN's tsx+cli ($SPEX) for the file→spec
+# resolve (`spex owner`); cwd = the session worktree.
+# @@@ harness-agnostic - WHICH tool/path counts as a code MUTATION is the [[harness-adapter]]'s call, read via
+# hp_code_path … mutate (Claude Edit/Write/NotebookEdit + file_path; Codex tool_name:Bash + an apply_patch /
+# write-shape command). So this annotates edits on Claude AND Codex.
+# @@@ all sessions, global ledger - like [[spec-first]], spec-awareness is UNIVERSAL so this is NOT gated on
+# `governed`. The once-per-file ledger lives in the session's GLOBAL store dir (keyed by the harness
+# session_id, grouped per-project — see hp_store_dir).
+. "${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
+
+# 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.
+paths=$(hp_code_path "$payload" mutate)
+[ -n "$paths" ] || exit 0
+led="$sdir/spec-of-file-seen"   # dedupe: once per session per file. Lists already-annotated paths.
+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
+  [ -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
+  [ -n "$m" ] || continue
+  msg="${msg:+$msg
+}$m"
+done <<EOF
+$paths
+EOF
+[ -n "$msg" ] || exit 0
+esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
+printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}\n' "$esc"
+exit 0

package/templates/spec/project/.config/core/spec-of-file/spec.md

@@ -0,0 +1,15 @@
+---
+title: spec-of-file
+surface: hook
+status: active
+hue: 200
+events:
+- PostToolUse
+order: 10
+block: false
+---
+A non-blocking per-edit annotation. The first time a session edits a given file, it names the spec node(s) that GOVERN that file — and, when a file is over-owned, flags that it is doing too much and points at the split — so the contract is in view at the very moment of the edit, not only later at commit or drift time.
+
+It never renders a verdict: it only adds context, so it can inform without interrupting. It is deduplicated once per file via a session ledger, so a fifty-edit refactor annotates each file once rather than on every write — the discipline that keeps a pervasive signal from decaying into the noise it is meant to cure. It speaks only when there is something to say: a sanely-owned file draws silence, an over-owned or uncovered one draws the pointer.
+
+This is the at-the-keystroke companion to the read-first gate [[spec-first]] and the commit-time checks: together they keep the [[core]] rule — code must not silently diverge from its spec — visible across the whole edit loop.

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

@@ -0,0 +1,13 @@
+---
+title: core
+surface: system
+status: active
+hue: 200
+desc: A config plugin — the minimal spec-discipline contract folded into every launched agent.
+code:
+---
+Commit your spec node and the code it justifies BEFORE you declare done or propose merge — the commit comes first, never as an afterthought to a declaration.
+
+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).

package/templates/spec/project/.config/core/stop-gate/spec.md

@@ -0,0 +1,17 @@
+---
+title: stop-gate
+surface: hook
+status: active
+hue: 200
+events:
+- Stop
+order: 10
+block: true
+---
+The blocking stop gate, with two jobs, each holding a hard loop-break so it never blocks twice on the same cause and never lets a dishonest stop through.
+
+The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand.
+
+The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end.
+
+It is the enforcement edge of [[core]]: nothing leaves a session except as committed work under a truthful declaration. The freshness it reads is set by [[mark-active]].