@spexcode/spec-cli 0.6.5

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

@@ -0,0 +1,22 @@
+---
+title: core
+surface: system
+status: active
+hue: 200
+desc: A config plugin — the minimal spec-discipline contract folded into every launched agent.
+code:
+---
+Use noun-first CLI commands; `spex help` is the authoritative command map.
+
+Anything a human needs to inspect, whether a file or a local webpage, goes out through `spex session files add` or
+`spex session web add`: never paste an absolute path or `host:port`, and never start a static server yourself.
+
+When this session has a clearly running child session (`active` or `parked`), the parent is supervising rather
+than finished: declare `park`, not `done`/`awaiting`, until the child reports a settled state.
+
+1. **Spec first:** before governed code, read its spec body with `spex spec owner <path>` or `spex spec search`.
+   Update that current-state body with any changed intent.
+2. **Commit before declare:** commit the code and spec it justifies before done or merge; independent intent gets
+   its own node.
+3. **Keep the loss signal honest:** run `spex spec lint` (the blocking correctness gate) and `spex eval lint --changed`. Measure changed scenarios
+   through the real product, commit the verified tree, then file with `spex eval add`; the reading's `codeSha` must name that commit.

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

@@ -0,0 +1,23 @@
+---
+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. `done --propose nothing` is a porcelain trap, not a declaration: it writes no state and names merge, close, ask, and park as the real destinations; legacy `nothing` records remain readable.
+
+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 emits `{"decision":"block"}` and the dispatcher exits 2 so the harness actually interrupts the stop and shows the reason; on the forced continuation it declares `asking`, so the loop is guaranteed to end without inventing a completion state. state owns the choice: a posted file or web artifact, a reported finding/recommendation awaiting a human decision, or any handoff awaiting human direction selects `asking`; `close-pending` requires genuinely settled work with no such outstanding decision or follow-up.
+
+The block text is where the declaration ritual is taught, so it is written to be read at two depths. The FULL teaching text prints once per session: it names the PATH-independent CLI once as a shared prefix, lists the five choices as a compact menu each with its application condition (park policed hardest — a false park is the most damaging mislabel). A real wake source is either a background job or a managed session-follow subscription whose normal send delivery will re-enter the parent; a caller without that address must still arm background `session wait`. It ends with the ordering discipline: declare LAST, then stop — a declaration followed by more tool calls honestly re-flips the record to active ([[mark-active]], by design), so making the declaration the turn's final call is what eliminates the park→block→re-park loop at its source. Every later undeclared stop in the same session gets a ONE-LINE version instead (a heavy session hits the gate 15-20 times a night; re-printing the full menu is token noise). The once-sentinel is a plain file beside the session record in the global store — the same per-session-sentinel mechanism as the CLI's note-truncation notice, never a second scheme. The terse line stays self-explanatory: it carries the command menu, the declare-LAST reminder, and the `spex help session` recovery entry, so an agent that never saw the full text (a compacted context) recovers every choice's condition from the entry rather than from memory — the whole full-to-terse information gap is closable from the line itself.
+
+The clean-done eval nudge is advisory only and must never corrupt the Stop hook protocol. Claude-family hooks can receive it as `hookSpecificOutput.additionalContext`; Codex Stop allows are silent because Codex treats unsupported non-block stdout as invalid hook JSON. Blocking decisions stay shared across harnesses through `{"decision":"block"}` plus the dispatcher’s Codex stderr bridge.
+
+Both gates act ONLY on a GOVERNED (dashboard-launched) session: the gate resolves the session's record in the global store from the payload's `session_id`, and on a non-governed (user-self-launched) record — or none — it exits 0 SILENTLY. A self-launched agent has no board to feed, so the declare-demand must never misfire on it. Its own state writes go through `spex session … --session <id>`, passing the id explicitly since there is no worktree file to read it from.
+
+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]].

package/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# @@@ stop-gate - a blocking Stop hook with TWO jobs, each with a HARD loop-break (never blocks more than
+# once on the same cause, never leaks a dishonest stop):
+#   (A) COMMIT GATE — a done/merge proposal (awaiting + merge; legacy nothing remains readable) is rejected while the node branch has
+#       uncommitted work or 0 commits ahead of main; the dogfood ritual commits BEFORE proposing. Clean ->
+#       allow; dirty -> block once with the reason, escape on the continuation to `asking` (needs the human).
+#   (B) DECLARE GATE — a session may not stop in an undeclared (`active`) state:
+#         declared (awaiting/parked/error/asking) . allow (the agent reported; nothing to do)
+#         active, first stop  (stop_hook_active false) .. block ONCE — instruct the agent to declare
+#         active, the continuation (stop_hook_active true) auto-declare `asking` and allow. Guaranteed to end
+#                                          without inventing a completion state.
+# $SPEX is the PATH-independent CLI invocation (abs tsx + cli) injected by settingsArg, so the gate's own
+# auto-default AND the command it shows the agent both work even when `spex` is absent from PATH.
+# @@@ global store + governed gate - state lives in the per-session GLOBAL record session.json (keyed by the
+# harness session_id from the payload, grouped per-project — mirrors spec-cli/src/layout.ts). The gate acts
+# ONLY on a GOVERNED (dashboard-launched) session: a user-self-launched agent has no board to feed, so an
+# undeclared stop is none of our business — we exit 0 SILENTLY (the bug this fixes: the declare-demand
+# misfiring on a self-launched codex/claude). cwd = the session worktree (resolves the project key + the
+# commit-gate's git); state writes go through `$SPEX session … --session <id>` (TS owns the JSON).
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+S="${SPEX:-spex}"
+input=$(cat 2>/dev/null || true)
+sid=$(hp_session_id "$input"); [ -n "$sid" ] || exit 0
+sdir=$(hp_store_dir "$sid") || exit 0
+rec="$sdir/session.json"
+# non-governed (or no record) → silently let the stop through. THIS is the self-launch fix.
+grep -q '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
+
+# read a CLOSED-VOCABULARY field (status / proposal) off its OWN line. The record is one-field-per-line from
+# the single writer ([[sessions-core]]), so anchoring to the line start is what keeps a neighbouring note's
+# escaped quote from being read as this field's value — the read half of the same rule that stops shell from
+# ever composing the record.
+jget() { sed -n "s/^[[:space:]]*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\",\?$/\1/p" "$rec" 2>/dev/null | head -1; }
+status=$(jget status)
+proposal=$(jget proposal)
+
+# the value of the payload's structured `stop_hook_active` field (true on the hook-forced continuation),
+# read by field name rather than substring-sniffing the JSON blob. ([a-z]* captures true/false portably —
+# BSD sed has no \| alternation.)
+cont=$(printf '%s' "$input" | sed -n 's/.*"stop_hook_active"[[:space:]]*:[[:space:]]*\([a-z]*\).*/\1/p')
+
+# @@@ eval advisory - a nudge (never a gate) emitted when a session stops CLEAN-DONE (committed work + a
+# done/awaiting declaration): the agent IS the measuring hand, so an eval gap in what it just changed is a
+# blind spot to flag the moment work lands. SCOPED via `spex eval lint --changed` to the nodes THIS branch
+# touched — so an agent is never nagged about a score that went stale in a node it never opened (the bug
+# that made three workers ask "is this mine?"). Three gap classes it surfaces: eval-drift / eval-missing
+# (a node with an eval.md whose score is stale / unmeasured) and eval-coverage (a FRONTEND node with no
+# eval.md — an obvious UI change carrying no loss signal). Delivered via the Stop hook's additionalContext
+# (NEVER a block decision: a gap is a heads-up, not a wall). FIRES ONCE: the additionalContext itself forces
+# one continuation, so the CALLER guards it on stop_hook_active — re-emitting on the forced re-stop is what
+# looped 31 turns and tripped the Stop-hook block cap. Called only on ALLOW paths, never alongside a block.
+#
+# SURFACE-NEUTRAL: a stale/unmeasured score is refreshed only by PRODUCING the measurement on the scenario's
+# OWN surface — a real run, never a desk check and never deferring to review a recording after the fact. The
+# nudge privileges NO surface: `eval lint --changed` carries each drift/missing scenario's tag on its finding line
+# ([[eval-core]]'s lint.scenarioTags — frontend-e2e / backend-api / cli / desktop / mobile), so the agent
+# reads there WHICH surface to run. One line covers all five surfaces; there is no per-surface branch.
+eval_advisory() {
+  local out ids n msg esc
+  # Codex Stop hooks reject the Claude-family `hookSpecificOutput.additionalContext` shape on allow paths.
+  # Keep Codex Stop stdout empty unless it is a real block decision; the dispatcher still bridges block
+  # reasons to Codex stderr.
+  [ "${SPEXCODE_HARNESS:-claude}" = codex ] && return 0
+  out=$($S eval lint --changed 2>&1)
+  n=$(printf '%s\n' "$out" | grep -cE 'eval-(drift|missing|coverage):')
+  [ "${n:-0}" -gt 0 ] || return 0   # no gap in what you changed (or eval lint unavailable) -> nothing to nudge
+  ids=$(printf '%s\n' "$out" | sed -n "s/.*eval-[a-z]*: '\([^']*\)'.*/\1/p" | awk '!seen[$0]++' | head -6 | paste -sd' ' -)
+  msg=$($S internal hook-prompt stop-gate --variant eval --count "$n" --ids "$ids") || return 0
+  esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"%s"}}\n' "$esc"
+}
+
+# @@@ commit gate - a declaration of done/merge (awaiting + proposal merge; legacy nothing is accepted only
+# for backward-readable records) is only honest once the
+# node branch carries the work as COMMITS: the dogfood ritual commits spec+code BEFORE any proposal, yet a
+# dashboard-launched agent kept proposing merge with 0 commits / a dirty tree. So before allowing such a
+# declaration we run the deterministic check (`spex internal commit-gate`, which goes through git.ts's git()
+# so the hook's GIT_DIR/GIT_INDEX_FILE can't misdirect repo discovery). Clean -> allow. Dirty/0-ahead ->
+# block ONCE with the specific reason + commit instructions; on the forced continuation (the agent ignored
+# it) escape the loop by downgrading to `asking` (needs the human) with a clear note, so a FALSE "ready to
+# merge" never stands. (A propose-close declaration is exempt — it discards the worktree, so commits are moot.)
+# The PROPOSAL rides into the check: `merge` claims there is committed work to land (so 0-ahead blocks too),
+# New public `done --propose nothing` calls trap before this hook; keep its legacy branch so historic records
+# stop normally instead of becoming corrupt.
+if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$proposal" = nothing ]; }; then
+  if gatemsg=$($S internal commit-gate "$proposal" 2>&1); then
+    # nudge ONCE: emit on the natural stop, but STAY SILENT on the forced re-stop the additionalContext
+    # itself causes (stop_hook_active=true). Without this guard the advisory re-fired every clean-done stop
+    # and looped — the bug a prior change DESCRIBED in a comment but never actually implemented at the call.
+    [ "$cont" != true ] && eval_advisory
+    exit 0   # work is committed and ahead of main -> the proposal is honest, let it stop.
+  fi
+  if [ "$cont" = true ]; then
+    $S session ask --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
+    exit 0
+  fi
+  reason=$($S internal hook-prompt stop-gate --variant commit --reason "$gatemsg" --cli "$S" --propose "$proposal") || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
+  exit 0
+fi
+
+# Any other declared state (parked / error / asking / awaiting+close, plus legacy awaiting+nothing) stops.
+[ "${status:-active}" != "active" ] && exit 0
+
+if [ "$cont" = true ]; then
+  # The forced continuation also stopped without declaring. Escape into asking: no default may invent a
+  # completed lane, and the stopped agent now needs a human prompt to choose merge, close, ask, or park.
+  $S session ask --session "$sid" --note "auto: stopped without declaring — choose merge, close, ask, or park; done --propose nothing records no state" >/dev/null 2>&1 || true
+  exit 0
+fi
+
+# first stop in an undeclared state -> block. The FULL teaching text prints ONCE per session; every later
+# undeclared stop gets a ONE-LINE version (a heavy session hits this gate 15-20x a night — re-printing the
+# full menu each time is pure token noise). The once-sentinel is a plain file beside session.json in the
+# session's global store dir — the same per-session-sentinel mechanism as the CLI's note-echo-taught; $sdir
+# is already alias-resolved here, so a codex thread id lands on the same file, and an unwritable dir just
+# teaches again (never blocks the block). The terse line must stay SELF-EXPLANATORY: an agent whose context
+# was compacted may never have seen the full text, so the line carries the whole command menu, the
+# declare-LAST discipline, and the `help session` entry that re-explains each choice's condition — every bit
+# of the full-to-terse information gap is recoverable from the entry, none of it from memory.
+taught="$sdir/stop-gate-taught"
+if [ -f "$taught" ]; then
+  reason=$($S internal hook-prompt stop-gate --variant terse --cli "$S") || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
+  exit 0
+fi
+touch "$taught" 2>/dev/null || true
+# The full reason names the PATH-independent CLI ($S) ONCE as a shared `<CLI> session <choice>` prefix, then
+# lists the four real states plus the `nothing` trap as a compact newline menu of bare subcommands — so the
+# terminal output stays legible instead of repeating the long abs path per option. It EMPHASIZES that each
+# state is a CLAIM others act on (not a box to tick to end the turn) and gives the precise APPLICATION CONDITION
+# for each — so the agent picks the TRUE one. park is policed hardest because a false park (no real background task) reads on the
+# board as "fine, self-resuming" when the agent actually needs the human, which is the most damaging mislabel.
+# It ends with the ORDERING discipline — declare LAST, then stop — because a declaration followed by more
+# tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
+# this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
+# kills the park->block->re-park loop at its source lives here.
+if [ -s "$sdir/files.json" ] && grep -qE '"[^"]+"' "$sdir/files.json"; then
+  reason=$($S internal hook-prompt stop-gate --variant artifact) || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
+  exit 0
+fi
+reason=$($S internal hook-prompt stop-gate --variant full --cli "$S") || exit 1
+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/templates/spec/project/.plugins/prompts/atomic-landing/spec.md

@@ -0,0 +1,15 @@
+---
+title: atomic-landing
+surface: system
+status: active
+hue: 30
+desc: A config plugin — the trunk checkout is the fleet's one landing door, so a merge must be trivial by the time it reaches it: sync and resolve in YOUR OWN worktree, land only when your branch already contains the trunk, and wait rather than race for a busy door.
+code:
+---
+## Landing is atomic
+
+1. In your worktree, merge `<base>` into the branch, resolve conflicts there, and rerun the proof.
+2. Immediately before landing, require `git merge-base --is-ancestor <base> <branch>`; otherwise sync again.
+3. A clean textual merge is not product proof; the synced branch's verification is required.
+
+`spex guide spec` has the shared-checkout mid-merge rule.

package/templates/spec/project/.plugins/prompts/forge-link/spec.md

@@ -0,0 +1,10 @@
+---
+title: forge-link
+surface: system
+status: active
+hue: 280
+desc: A config plugin — agents link an issue or change request opened through the resolved forge to the spec node it serves via one `Spec: <id>` body line.
+code:
+---
+Every forge issue or change request body includes `Spec: <node-id>` (comma-separate several). Use each node's
+leaf directory name, not its slash path; `spex graph --json` lists valid ids.

package/templates/spec/project/.plugins/prompts/memory-hygiene/spec.md

@@ -0,0 +1,13 @@
+---
+title: memory-hygiene
+surface: system
+status: active
+hue: 200
+desc: A config plugin — keep the project-keyed agent memory free of session- and role-specific facts, so N agents in one folder never inherit a confused identity.
+code:
+---
+## Memory hygiene
+
+Project memory is shared by the main checkout and all worktrees. Store only durable cross-session project/user
+facts. Never store this task, transient worktree state, a one-off decision, role, or identity. On a non-main
+`node/<id>` worktree, record no memory at all; land a durable lesson first, then record it from main.

package/templates/spec/project/.plugins/prompts/reproduce-before-fix/spec.md

@@ -0,0 +1,12 @@
+---
+title: reproduce-before-fix
+surface: system
+status: active
+hue: 140
+desc: A config plugin — a bug fix must first REPRODUCE the failure as a failing eval, then fix, verify, commit, and file the passing eval. The fail→pass pair on one scenario is the fix's proof (the A/B).
+code:
+---
+## Reproduce before you fix
+
+For a bug fix, the fail→pass pair on one scenario is the repair proof. New intent has no prior failure to
+reproduce; `spex guide eval` has the A/B filing sequence.

package/templates/spec/project/.plugins/prompts/spec.md

@@ -0,0 +1,24 @@
+---
+title: prompts
+status: active
+hue: 110
+desc: Grouping shelf for the auxiliary `surface: system` prompt contracts — single-body always-on prose. Core is NOT a resident — the core contract subsystem is a direct `.plugins` child. A shelf, not a surface — routing stays field-driven per surface.
+---
+# prompts
+
+The **auxiliary** `surface: system` prompt contracts live here: leaf plugins whose whole substance is one
+prose body an agent must always carry — materialized (in name order, together with every other system
+body) into the `<!-- spexcode -->` contract block — rather than a verb it invokes. Grouping them keeps
+`.plugins/` legible at a glance: peripheral prompt contracts on this shelf; the command presets on
+[[commands]], the skill plugins on [[skills]], and [[core]] as a flat child beside it.
+
+The shelf boundary is **leafness, not surface**: a single-body prose contract shelves here, while a
+contract that anchors its own subtree outranks the shelf — [[core]], the dev-flow contract subsystem
+whose children are the `surface: hook` gates, is a *peer* of this shelf, never a resident.
+
+This node is a **shelf, not a surface**: it declares no `surface` field and gathers nothing itself.
+Discovery is recursive and field-driven (surface), so residents plug in exactly as they would at the
+root — nothing about materialization order (name order, unchanged names) or gathering changes with the
+path. The init templates mirror this layout — a fresh `spex init` (per init-preset) seeds `core`
+flat and its auxiliary system plugins under the same `prompts/` shelf. The shelf stays pure presentation:
+changing this path changes neither a plugin's identity nor its gathered surface.

package/templates/spec/project/.plugins/skills/distill/digest.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// digest.mjs — locate a dead session's transcript on disk and print a compact markdown digest.
+// Usage: node digest.mjs <session-id | path/to/transcript.jsonl>
+// Read-only: never resumes, prompts, or mutates the session. Exit 1 (loud) when no transcript is found.
+//
+// Harness coverage: claude (projects/<enc-cwd>/<id>.jsonl) and codex (sessions/YYYY/MM/DD/rollout-*<id>.jsonl).
+// The digest keeps the high-signal stream — user prompts in full, assistant text, tool calls as one-liners,
+// error results — and drops the bulk (tool outputs, attachments, sidechains, reasoning).
+
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const arg = process.argv[2]
+if (!arg) { console.error('usage: digest.mjs <session-id | transcript.jsonl>'); process.exit(1) }
+
+const TRUNC = (s, n) => { s = String(s ?? '').trim(); return s.length > n ? s.slice(0, n) + ` …[+${s.length - n} chars]` : s }
+
+// ---- locate -------------------------------------------------------------
+const claudeRoots = () => {
+  const roots = []
+  if (process.env.CLAUDE_CONFIG_DIR) roots.push(process.env.CLAUDE_CONFIG_DIR)
+  for (const e of readdirSync(homedir(), { withFileTypes: true }))
+    if (e.isDirectory() && e.name.startsWith('.claude')) roots.push(join(homedir(), e.name))
+  return roots
+}
+const findClaude = (id) => {
+  for (const root of claudeRoots()) {
+    const proj = join(root, 'projects')
+    if (!existsSync(proj)) continue
+    for (const d of readdirSync(proj)) {
+      const f = join(proj, d, `${id}.jsonl`)
+      if (existsSync(f)) return f
+    }
+  }
+  return null
+}
+const findCodex = (id) => {
+  const root = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'sessions')
+  if (!existsSync(root)) return null
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) stack.push(join(dir, e.name))
+      else if (e.name.startsWith('rollout-') && e.name.includes(id) && e.name.endsWith('.jsonl')) return join(dir, e.name)
+    }
+  }
+  return null
+}
+const file = arg.endsWith('.jsonl') ? arg : (findClaude(arg) || findCodex(arg))
+if (!file || !existsSync(file)) { console.error(`no transcript found for "${arg}" (searched claude projects/ and codex sessions/)`); process.exit(1) }
+
+// ---- parse --------------------------------------------------------------
+const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean)
+const out = []
+const meta = { cwd: null, branch: null, first: null, last: null }
+const filesTouched = new Set()
+let errors = 0
+const seen = new Set()
+
+// harness-injected preamble arrives typed as "user" (system-reminders, AGENTS.md folds, codex permission/skill
+// blocks) — it is noise to a digest, and real human prompts essentially never open with these markers.
+const isInjected = (t) => /^(<|# AGENTS\.md instructions|Caveat: The messages below)/.test(t.trimStart())
+const userBlock = (t) => { t = String(t ?? '').trim(); return t && !isInjected(t) ? `\n## user\n${t}` : null }
+
+const toolLine = (name, input = {}) => {
+  if ((name === 'Edit' || name === 'Write' || name === 'NotebookEdit') && input.file_path) filesTouched.add(input.file_path)
+  const hint = input.description || input.file_path || input.command || input.prompt || input.query || input.pattern || ''
+  return `→ ${name}${hint ? ` · ${TRUNC(hint, 160)}` : ''}`
+}
+
+for (const raw of lines) {
+  let l; try { l = JSON.parse(raw) } catch { continue }
+  const ts = l.timestamp
+  if (ts) { meta.first ||= ts; meta.last = ts }
+  if (l.cwd) meta.cwd ||= l.cwd
+  if (l.gitBranch && l.gitBranch !== 'HEAD') meta.branch ||= l.gitBranch
+
+  // claude shape: {type: user|assistant, message:{content}, isSidechain}
+  if (l.type === 'user' || l.type === 'assistant') {
+    if (l.isSidechain) continue // subagent noise
+    const c = l.message?.content
+    if (typeof c === 'string') { const u = userBlock(c); if (u) out.push(u); continue }
+    for (const item of c || []) {
+      if (item.type === 'text' && item.text?.trim()) {
+        if (l.type === 'user') { const u = userBlock(item.text); if (u) out.push(u) }
+        else out.push(TRUNC(item.text, 2000))
+      }
+      else if (item.type === 'tool_use') out.push(toolLine(item.name, item.input))
+      else if (item.type === 'tool_result' && item.is_error) {
+        errors++
+        const t = Array.isArray(item.content) ? item.content.map((x) => x.text || '').join(' ') : item.content
+        out.push(`⚠ tool error: ${TRUNC(t, 400)}`)
+      }
+    }
+    continue
+  }
+
+  // codex shape: {type: session_meta|response_item|event_msg, payload:{...}}. The same message is logged
+  // BOTH as a response_item and an event_msg (version-dependent which exists) — dedupe on the text.
+  const p = l.payload
+  if (!p) continue
+  if (l.type === 'session_meta') { meta.cwd ||= p.cwd; continue }
+  const pushMsg = (role, text) => {
+    text = String(text ?? '').trim()
+    if (!text || seen.has(text)) return
+    seen.add(text)
+    if (role === 'user') { const u = userBlock(text); if (u) out.push(u) }
+    else if (role === 'assistant') out.push(TRUNC(text, 2000)) // developer/system roles are harness plumbing
+  }
+  if (l.type === 'event_msg' && (p.type === 'user_message' || p.type === 'agent_message'))
+    pushMsg(p.type === 'user_message' ? 'user' : 'assistant', p.message)
+  else if (l.type === 'response_item') {
+    if (p.type === 'message') {
+      pushMsg(p.role, (p.content || []).map((x) => x.text || '').join('\n'))
+    } else if (p.type === 'function_call') {
+      let input = {}; try { input = JSON.parse(p.arguments || '{}') } catch {}
+      out.push(toolLine(p.name, input))
+    } else if (p.type === 'function_call_output' && /error/i.test(String(p.output).slice(0, 200))) {
+      errors++
+      out.push(`⚠ tool error: ${TRUNC(p.output, 400)}`)
+    }
+  }
+}
+
+// ---- emit ---------------------------------------------------------------
+const kb = Math.round(statSync(file).size / 1024)
+console.log(`# transcript digest — ${arg}`)
+console.log(`- file: ${file} (${kb} KB, ${lines.length} lines)`)
+if (meta.first) console.log(`- span: ${meta.first} → ${meta.last}`)
+if (meta.cwd) console.log(`- cwd: ${meta.cwd}`)
+if (meta.branch) console.log(`- branch: ${meta.branch}`)
+console.log(out.join('\n'))
+console.log(`\n---\n- transcript: ${file}\n- tool errors seen: ${errors}`)
+if (filesTouched.size) console.log(`- files edited:\n${[...filesTouched].map((f) => `  - ${f}`).join('\n')}`)

package/templates/spec/project/.plugins/skills/distill/spec.md

@@ -0,0 +1,67 @@
+---
+title: distill
+surface: skill, command
+status: active
+hue: 210
+desc: Use when the user wants to inherit a finished, dead, or abandoned session — "distill session X / 继承那个 session 的经验 / 接手它的工作 / harvest or salvage a session". Given a SpexCode session id, harness thread id, or transcript path, read it without resuming, extract decisions, traps, and next actions, salvage unmerged work, retire only resources proven safe to remove, then rename the inheriting session to mark the handoff.
+---
+
+# distill
+
+Inherit a finished session's **mind and desk** without waking it: mind is its transcript; desk is its
+worktree and branch. **Never resume, reopen, send to, or otherwise re-prompt the old session.** Read files
+and git state only until its work has landed.
+
+## Resolve and digest
+
+Accept a SpexCode session id, a Claude/Codex thread id, or a transcript `.jsonl` path.
+
+- For a SpexCode id, find `~/.spexcode/projects/*/sessions/<id>/session.json` (a unique prefix is enough).
+  Keep its prompt, `worktree_path`, `branch`, `harness`, and `harness_session_id`; Claude uses the session
+  id as its transcript id, while Codex uses `harness_session_id`.
+- Otherwise pass the harness id or transcript path directly. The digest header supplies its `cwd` and branch
+  when recorded; those locate the desk even when it belongs to another repository.
+
+From the repository root run the plugin's co-located digest:
+
+`node .spec/*/.plugins/skills/distill/digest.mjs <id-or-path>`
+
+It searches the harness's normal local transcript stores and prints human prompts, agent text, concise tool
+calls, errors, metadata, edited files, and the raw path. A miss fails loudly; never recover by waking the old
+session. For output above about 100 KB, have a subagent return only the distillation below.
+
+## Distill forward
+
+Do not paste the transcript or retell changes git already records. Preserve what git does not:
+
+- goal, actual stopping point, and whether anything landed;
+- decisions and rejected alternatives, with reasons;
+- failures, dead ends, and user corrections;
+- unfinished work and next actions;
+- edited files, relevant spec nodes, and the raw transcript path.
+
+## Salvage, then retire
+
+Use the record or digest to inspect the old repository's worktree, branch, merge base, commits, dirty files,
+and untracked files. Cross-check the digest's edited-file list because some work may live outside that
+worktree. Distinguish an already-merged branch from a branch equal to its merge base, which never committed.
+
+Carry unmerged commits onto the current branch with `git cherry-pick <base>..<branch>`; if replay is
+unsuitable, apply the branch diff. Apply dirty changes and copy needed untracked files, then commit them
+with the source session named. Keep authorship and `Session:` trailers where possible.
+
+Only after verifying the salvage is present (or the branch truly merged), retire a SpexCode session with
+`spex session close <id>`, or remove a bare worktree and then its branch. If proof is incomplete, keep the
+resources and report why.
+
+`<id>` is the OLD session's id — the one you are inheriting, spelled out. It is never `.` and never your own
+id: `.` means THIS session (the rename step below relies on that), and closing yourself deletes the worktree
+you are running in, mid-turn, along with your branch and record. Retiring the source is the only close this
+skill asks for; your own ending stays a declaration.
+
+## Rename yourself
+
+Last step: mark the inheritance on the board. If you run as a SpexCode session (inside a session
+worktree), `spex session rename . "<name>"` — `.` selects this worktree's own session. Name what this
+session now carries — the inherited goal going forward, not the old session's id and no `distill:`
+prefix. Outside a SpexCode session there is nothing to rename; skip this step.

package/templates/spec/project/.plugins/skills/spec.md

@@ -0,0 +1,19 @@
+---
+title: skills
+status: active
+hue: 280
+desc: Grouping shelf for the `surface: skill` plugins — the harness skills an agent invokes on demand. A shelf, not a surface — routing stays field-driven per surface.
+---
+# skills
+
+The invocable **skill** plugins live here: leaf plugins that materialize into the harness's skill dir,
+where an agent invokes them on demand, each carrying `surface: skill`. Grouping them keeps `.plugins/`
+legible at a glance — the skill plugins on this shelf, the command presets on [[commands]], the auxiliary
+system contracts on [[prompts]], with [[core]] a flat child beside them.
+
+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. A plugin that serves BOTH surfaces — [[distill]] is skill and command —
+shelves here by its primary (skill) identity and still gathers as a command through its field. 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/templates/spec/project/.plugins/spec.md

@@ -0,0 +1,23 @@
+---
+title: .plugins
+status: active
+hue: 110
+desc: The instance home — SpexCode's DIY dev-flow plugins live here as skill-shaped plugin nodes.
+---
+`.plugins/` is the **instance** of the plugin system: the concrete dev-flow plugins SpexCode ships for
+working in this repo. Each plugin is a skill-shaped node — its folder *is* the unit (a `spec.md` plus any
+co-located scripts) — carrying a `surface: command|system|…` field that names where it plugs in, per
+plugin-system's surface field-driven routing. Discovery is recursive, so a plugin may sit under a
+grouping shelf: the auxiliary `surface: system` prompt contracts live under [[prompts]], the `surface:
+command` presets under [[commands]], the `surface: skill` plugins under [[skills]], the `surface: review`
+remark presets under review, while [[core]] — the dev-flow contract subsystem whose children are the
+`surface: hook` gates — sits as a flat child beside them.
+
+`/api/plugins` and the launcher's system gather read from here, not from plugin-system (which holds the
+*spec of the plugin system* itself). Only **built/active** plugins gather — a `pending` node is declared
+intent, not yet an active plugin, so it renders on the board but is neither offered as a command preset nor
+materialized into the agent's contract.
+
+Which plugins `spex init` ships is the init-preset rule. `seed: false` excludes a plugin subtree; shared
+plugins have one body and one helper set — there is no separately authored adopter variant. Dogfood eval
+scenarios/readings remain with the implementation and git history they measure.

package/templates/spec/project/spec.md

@@ -0,0 +1,20 @@
+---
+title: project
+status: active
+hue: 45
+desc: The root spec node — the founding intent this repo's spec tree hangs from. Rewrite it to your own.
+---
+# project
+
+The root of your spec tree. In SpexCode the spec tree IS ground truth and git is its database: every
+node is a `spec.md` stating present intent, and each version change is attributed to the session that
+made it. This node is the founding spec everything else hangs from — **rewrite this body to describe
+your own project**, then grow child package/feature nodes beneath it (each its own directory with a
+`spec.md`).
+
+`.plugins/` holds the dev-flow plugins this instance ships — spec-shaped child nodes whose `surface`
+field says how they enter the product. The initialized set includes always-on `system` contracts,
+lifecycle `hook` handlers, new-session `command` presets, and an on-demand `skill`; one plugin may serve
+more than one surface. Grouping shelves carry no surface themselves, and discovery is recursive, so the
+folder layout stays readable without deciding behavior. Add, edit, or remove plugins by editing those
+spec nodes.