@spexcode/spec-cli 0.6.5

package/hooks/harness.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# @@@ harness.sh - the SHELL face of the [[harness-adapter]] (spec-cli/src/harness.ts). The hook scripts run
+# as pure shell, so they cannot import the TS adapter; this sourced library is its mirror. dispatch.sh sources
+# it and exports SPEXCODE_HARNESS (claude|codex|opencode|zcode) — baked into the shim by each adapter, so a hook learns its
+# harness deterministically, never by sniffing the payload shape. EVERY harness-divergent payload-parse lives
+# HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
+# shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
+# lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
+# SPEXCODE_HARNESS is claude|codex|opencode|pi|zcode|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
+# host (adopter-a/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]),
+# `pi`'s generated extension ([[pi-harness]]), and z-code's native hook payload all share that Claude shape — so every
+# `case "$SPEXCODE_HARNESS"` below routes all four through the claude branch via the default case; only codex
+# keeps parse arms of its own.
+
+
+# the string value of a top-level JSON string field (first match). Harness-agnostic — both harnesses' payloads
+# carry session_id / tool_name as plain string fields. $1 = payload, $2 = field name. The value is scanned as a
+# real JSON string: the closing quote is the first UNESCAPED `"`, so a value containing `\"` (a quoted literal
+# inside a codex Bash/apply_patch command — extremely common) is captured WHOLE, not truncated at the inner
+# quote. The standard escapes are decoded (`\"` `\\` `\/` `\n` `\t` `\r` `\b` `\f`), so a patch envelope's `\n`
+# arrives as a real newline here (the downstream codex decode then no-ops). Pure awk, no jq on the hot path.
+hp_field() {
+  printf '%s' "$1" | awk -v field="$2" '
+    BEGIN { s = ""; while ((getline line) > 0) s = s (s == "" ? "" : "\n") line }
+    END {
+      key = "\"" field "\""
+      n = length(s); i = 1
+      while (i <= n) {
+        p = index(substr(s, i), key)
+        if (p == 0) exit
+        i += p + length(key) - 1
+        # skip whitespace, require a colon, skip whitespace, require an opening quote
+        while (i <= n && substr(s, i, 1) ~ /[ \t\n]/) i++
+        if (substr(s, i, 1) != ":") continue
+        i++
+        while (i <= n && substr(s, i, 1) ~ /[ \t\n]/) i++
+        if (substr(s, i, 1) != "\"") continue
+        i++
+        out = ""
+        while (i <= n) {
+          c = substr(s, i, 1)
+          if (c == "\\") {
+            e = substr(s, i + 1, 1)
+            if      (e == "n") out = out "\n"
+            else if (e == "t") out = out "\t"
+            else if (e == "r") out = out "\r"
+            else if (e == "b") out = out "\b"
+            else if (e == "f") out = out "\f"
+            else               out = out e   # \" \\ \/ and any other → the literal char
+            i += 2
+          } else if (c == "\"") {
+            print out; exit
+          } else {
+            out = out c; i++
+          }
+        }
+        exit
+      }
+    }'
+}
+
+# the session id from a payload (both harnesses use session_id).
+# Codex hooks run inside ONE shared per-project app-server. That process can inherit the FIRST launched
+# session's SPEXCODE_SESSION_ID, so on codex the payload session_id (the acting thread id) must win and then
+# hp_store_dir aliases it to the governed record. Claude's payload id equals its governed record id, so the
+# PAYLOAD is the acting identity; the inherited env is only a fallback for payload-less events. Env-first was
+# a live bug: a nested subagent (Task tool) inherits the parent's SPEXCODE_SESSION_ID, so with env winning,
+# every child tool call fired mark-active against the PARENT's record — the parent read `working` forever and
+# every park/done declaration was clobbered within seconds (measured). Same staleness class the codex branch
+# already guards against (payload-first below); claude now follows the same rule.
+# The claude preference is RESOLUTION-AWARE, not blind. "Claude's payload id equals its governed record id"
+# holds only while the launched conversation lives: a compaction/continuation MINTS A NEW conversation id
+# while the record keeps the launched one, and a blindly-preferred payload id then resolves to no record at
+# all — hp_store_dir echoes a path nothing sits at, so every record-dependent hook (stop-gate, mark-active,
+# idle, session-fail) silently no-ops and the session reads `working` forever (measured: a live session froze
+# at `active` while its terminal still answered). So the payload wins only when a record actually answers to
+# it, and an unresolvable payload falls back to the launched SPEXCODE_SESSION_ID. This cannot reopen the
+# subagent bug above: a Task subagent's payload carries the PARENT's session_id, which DOES resolve, so the
+# preference is unchanged there — the divergent branch is reached only when the two ids differ AND the
+# payload names nothing. The common path costs one string compare (the ids are equal), never a store read.
+hp_session_id() {
+  local pid
+  case "$SPEXCODE_HARNESS" in
+    codex) hp_field "$1" session_id ;;
+    *)     pid=$(hp_field "$1" session_id)
+           if [ -n "$pid" ] && [ -n "$SPEXCODE_SESSION_ID" ] && [ "$pid" != "$SPEXCODE_SESSION_ID" ] \
+              && [ ! -e "$(hp_store_dir "$pid")/session.json" ] \
+              && [ -e "$(hp_store_dir "$SPEXCODE_SESSION_ID")/session.json" ]; then
+             printf '%s' "$SPEXCODE_SESSION_ID"
+           else
+             printf '%s' "${pid:-$SPEXCODE_SESSION_ID}"
+           fi ;;
+  esac
+}
+
+# is THIS payload a tool call executed by an IN-PROCESS SUBAGENT (Claude's Task tool — a sub-conversation
+# inside the SAME harness process) rather than the session's own top-level agent? The subagent's payload
+# carries the PARENT's session_id/transcript_path (measured live, claude 2.1.207), so hp_session_id cannot
+# tell them apart — but the harness stamps every subagent-executed call with a top-level `agent_id`
+# (+ `agent_type`) field that a top-level call NEVER carries. The check is structural, never a heuristic:
+# scan ONLY the payload prefix before the first `"tool_input"` (every harness-stamped top-level field
+# precedes tool_input), and require the key shape `"agent_id":`. Inside a JSON string value every quote is
+# escaped (\"), so a bare-quoted `"agent_id"` followed by a colon in that prefix can only be the harness's
+# own stamp — a tool parameter literally NAMED agent_id (an MCP tool) sits inside tool_input, past the
+# truncation, and file/prompt content can never fake an unescaped quote. Codex payloads carry no such field
+# (its verified field set) so this never matches there. Echoes "1" when yes, else nothing.
+hp_is_subagent() {
+  printf '%s' "${1%%\"tool_input\"*}" | grep -q '"agent_id"[[:space:]]*:' && printf 1
+}
+
+# the per-PROJECT GLOBAL runtime dir (mirrors packages/spec-core/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
+# keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
+# worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
+# Echoes the dir; returns non-zero (echoing nothing) when git can't resolve, so a caller can `|| exit 0`.
+hp_runtime_dir() {
+  local gcd
+  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)
+  [ -n "$gcd" ] || return 1
+  printf '%s/projects/%s' "${SPEXCODE_HOME:-$HOME/.spexcode}" "$(printf '%s' "$(dirname "$gcd")" | sed 's#[/.]#-#g')"
+}
+
+# the per-WORKTREE materialize slot (mirrors layout.ts `treeSlotDir`): <runtime>/trees/<enc(worktree-toplevel)> —
+# where THIS tree's materialized hook manifest + content-hash marker live. Keyed by the cwd's own
+# `rev-parse --show-toplevel` through the same enc transform, so a dispatch can only ever read the manifest
+# of the tree it fires in ([[hook-dispatch]] — the old single global file let the last-materialized tree's
+# hook set reach every other tree's sessions). Echoes the dir; returns non-zero when git can't resolve.
+hp_tree_dir() {
+  local rd top
+  rd=$(hp_runtime_dir) || return 1
+  top=$(git rev-parse --show-toplevel 2>/dev/null)
+  [ -n "$top" ] || return 1
+  printf '%s/trees/%s' "$rd" "$(printf '%s' "$top" | sed 's#[/.]#-#g')"
+}
+
+# the per-session GLOBAL store dir for a session id — <runtime>/sessions/<id> (sibling of the per-project
+# runtime above). Echoes the dir; returns non-zero (echoing nothing) when git can't resolve.
+# ALIAS resolution: a codex hook fires from the shared per-PROJECT app-server process, whose env may carry a
+# stale SPEXCODE_SESSION_ID from the first launched codex session. hp_session_id therefore returns the acting
+# payload session_id on codex: the codex THREAD id, NOT the SpexCode record id the dir is keyed by. So when no
+# record sits at <id> directly, find the one record that captured this id as `harness_session_id` (the backend
+# stored it at thread/start, before the first tool turn).
+# A grep over the few session.json files — no jq on the hot path; the trailing quote anchors the value so a
+# thread id can't match a longer one as a prefix. Direct hit wins; a miss with no alias echoes the direct path
+# unchanged, so the caller's `[ -e "$rec" ]` still no-ops gracefully. Mirrors layout.ts `readAliasedRawRecord`.
+hp_store_dir() {
+  local rd; rd=$(hp_runtime_dir) || return 1
+  local direct="$rd/sessions/$1"
+  if [ -e "$direct/session.json" ]; then printf '%s' "$direct"; return 0; fi
+  # same two-halves-of-absence rule as layout.ts's readAliasedRecordEntry: an id owning a store dir is already
+  # one of ours, so its emptiness is settled and the alias grep is the wrong question (and a whole-store scan).
+  if [ -d "$direct" ]; then printf '%s' "$direct"; return 0; fi
+  local hit
+  hit=$(grep -lF "\"harness_session_id\": \"$1\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
+  [ -n "$hit" ] && { printf '%s' "${hit%/session.json}"; return 0; }
+  printf '%s' "$direct"
+}
+
+# the TOOLCHAIN's own version fingerprint — the toolchain side of the content key. The materialized artifacts
+# are a function of (config content, toolchain), so a TOOLCHAIN update must move the key too, or an updated
+# deploy never self-heals its stale contract/shims/manifest until someone happens to edit .plugins (the field
+# lesson: a toolchain update does NOT self-heal). A source checkout answers with the git TREE hash of the
+# package dir (moves exactly when the toolchain's content moves, not on every repo commit); an npm install
+# (no .git) answers with the package.json hash (npm bumps the version). env-stripped git — a git hook's
+# exported GIT_DIR must not misdirect repo discovery (same rule as git.ts's git()).
+SPEXCODE_HP_PKG="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd)"
+hp_toolchain_version() {
+  ( cd "$SPEXCODE_HP_PKG" 2>/dev/null && env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse 'HEAD:./' 2>/dev/null ) \
+    || sha256sum "$SPEXCODE_HP_PKG/package.json" 2>/dev/null | cut -d' ' -f1 \
+    || echo unversioned
+}
+
+# the deterministic content fingerprint of EVERYTHING the materialize is a function of: the EDITABLE config
+# roots (.plugins + plugin-system md/sh), the PERSISTED POLICY files (the MAIN checkout's spexcode.json +
+# spexcode.local.json — the `harnesses` set materialize reads via readConfig(mainCheckout)), and the
+# toolchain version above. Since the dispatch-gate retired ([[commit-surgery]] — materialize anchors on
+# git-native events only), this is a FRESHNESS STAMP materialize records after each pass, a diagnostic
+# (is the last materialize current?) rather than a trigger. Run with cwd = the project. ONE definition:
+# materialize.ts shells to it. env-stripped git, same rule as hp_toolchain_version.
+hp_config_hash() {
+  local gcd
+  gcd=$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) \
+    || gcd=$(realpath "$(env -u GIT_DIR -u GIT_INDEX_FILE git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null)
+  { hp_toolchain_version
+    find .spec/*/.plugins .spec/*/plugin-system \( -name '*.md' -o -name '*.sh' \) -type f -print0 2>/dev/null \
+      | sort -z | xargs -0 cat 2>/dev/null
+    [ -n "$gcd" ] && cat "$(dirname "$gcd")/spexcode.json" "$(dirname "$gcd")/spexcode.local.json" 2>/dev/null
+  } | sha256sum | cut -d' ' -f1
+}
+
+# the tool a payload is about to run / just ran (harness-agnostic field name).
+hp_tool() { hp_field "$1" tool_name; }
+
+# is THIS payload the agent pausing to ask the HUMAN a question? Claude: the AskUserQuestion tool. Codex: the
+# experimental request_user_input tool (its only structured ask path). Echoes "1" when yes, else nothing.
+hp_is_ask() {
+  case "$SPEXCODE_HARNESS" in
+    codex) [ "$(hp_tool "$1")" = request_user_input ] && printf 1 ;;
+    *)     [ "$(hp_tool "$1")" = AskUserQuestion ] && printf 1 ;;
+  esac
+}
+
+# the question text of an ask payload (best-effort; for the board note). Both harnesses carry it under a
+# "question" field of the tool input — so it is just the first such JSON string value: collapse onto hp_field,
+# which (unlike the old grep `[^"]*`) handles an embedded `\"` and decodes escapes instead of truncating.
+hp_ask_note() { hp_field "$1" question; }
+
+# the CODE file(s) a payload touches, mapped to the trigger the spec hooks key on. $2 = mode:
+#   read    → the file being READ         ([[spec-first]] gates the first GOVERNED read)
+#   mutate  → the file being EDITED       ([[spec-of-file]] fires only on a mutation)
+#   access  → either operation
+# Echoes the path(s), ONE PER LINE — a codex multi-file apply_patch (several `*** Update File:` markers)
+# touches several files in one tool call, so every consuming hook iterates the lines. Echoes nothing when the
+# payload is not a code touch of that mode. The harness divergence:
+#   Claude — Read/Edit/Write/NotebookEdit + tool_input.file_path|notebook_path.
+#   Codex  — NO file_path. An EDIT is its own first-class tool `tool_name:"apply_patch"` whose tool_input.command
+#            is the bare patch envelope (`*** Update File: <path>`); a READ/shell is `tool_name:"Bash"` +
+#            tool_input.command. Both carry the touched file inside `command`, so we parse that one field.
+hp_code_path() {
+  local payload="$1" mode="$2" tool
+  tool=$(hp_tool "$payload")
+  case "$SPEXCODE_HARNESS" in
+    codex)
+      case "$mode:$tool" in
+        read:Bash|mutate:apply_patch|mutate:Bash|access:apply_patch|access:Bash) ;;
+        *) return 0 ;;
+      esac
+      _hp_codex_cmd_path "$(hp_field "$payload" command)" "$mode"
+      ;;
+    *)
+      case "$mode" in
+        read)   case "$tool" in Read) ;; *) return 0 ;; esac ;;
+        mutate) case "$tool" in Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+        access) case "$tool" in Read|Edit|Write|NotebookEdit) ;; *) return 0 ;; esac ;;
+        *) return 0 ;;
+      esac
+      local p; p=$(hp_field "$payload" file_path); [ -n "$p" ] || p=$(hp_field "$payload" notebook_path)
+      printf '%s' "$p"
+      ;;
+  esac
+}
+
+# @@@ codex command → path - the apply_patch / sed / cat path-extractor. Codex never sends a file_path; the
+# touched file lives inside `command`. Two shapes: a PATCH envelope carries `*** (Add|Update|Delete) File:
+# <path>` lines (always a MUTATION) — this is what the apply_patch tool sends, the bare envelope with NO literal
+# `apply_patch` token, so we detect it by the File: markers themselves (the legacy `apply_patch` token is kept
+# too, for a shell-wrapped invocation); a plain command (sed/cat/head/rg/…) carries the path as a token.
+# A MUTATION is a patch envelope or a write shape (a redirect, tee, `sed -i`, dd of=); in `mutate` mode a pure
+# read yields nothing. A patch envelope can carry SEVERAL `*** Update File:` markers (a multi-file edit) — ALL
+# of them are emitted, one per line, so the consuming hook acts on every touched file (a single-file patch
+# emits one line; a plain command emits its one token). The plain-command path is the last path-like token
+# (has a / or a .ext), ignoring flags — matches the verified-facts example `sed -n 1p f.ts` → `f.ts`.
+# Best-effort: an exotic command may not resolve, which only means a missed nudge, never a wrong block.
+_hp_codex_cmd_path() {
+  local mode="$2" cmd
+  # the command arrives as a JSON STRING value; hp_field already decodes JSON escapes (so a patch File: line
+  # already ends at a real newline). This gsub is a no-op safety net for any caller that bypassed hp_field.
+  cmd=$(printf '%s' "$1" | awk '{gsub(/\\n/,"\n"); gsub(/\\t/,"\t")}1')
+  case "$cmd" in
+    *apply_patch*|*applypatch*|*'*** Add File:'*|*'*** Update File:'*|*'*** Delete File:'*)
+      [ "$mode" = read ] && return 0
+      printf '%s\n' "$cmd" | sed -n 's/^\*\*\* \(Add\|Update\|Delete\) File: \(.*\)$/\2/p' | sed 's/[[:space:]]*$//'
+      return 0 ;;
+  esac
+  local is_mutate=0
+  case "$cmd" in *' >> '*|*' > '*|*' >>'*|*' >'*|*' tee '*|*'sed -i'*|*' dd '*) is_mutate=1 ;; esac
+  [ "$mode" = mutate ] && [ "$is_mutate" = 0 ] && return 0
+  [ "$mode" = read ] && [ "$is_mutate" = 1 ] && return 0
+  printf '%s\n' "$cmd" | tr ' \t' '\n\n' | grep -E '^[^-].*[/.][A-Za-z0-9_]+' | grep -vE '^(apply_patch|applypatch)$' | tail -1
+}
+
+# the notification type of a Notification payload (Claude only — Codex fires no Notification event).
+hp_notification_type() { hp_field "$1" notification_type; }

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@spexcode/spec-cli",
+  "version": "0.6.5",
+  "type": "module",
+  "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
+  "bin": {
+    "spex": "bin/spex.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./bin/spex.mjs": "./bin/spex.mjs",
+    "./ranker": "./dist/ranker.js",
+    "./eval-host": "./dist/eval-host.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "hooks"
+  ],
+  "bundledDependencies": [
+    "@spexcode/spec-core",
+    "@spexcode/spec-eval",
+    "@spexcode/spec-forge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../scripts/release-publish.mjs --from-package-publish",
+    "serve": "npm run build && node bin/spex.mjs serve",
+    "lint": "npm run build && node bin/spex.mjs spec lint",
+    "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/spec-core": "0.6.5",
+    "@spexcode/spec-eval": "0.6.5",
+    "@spexcode/spec-forge": "0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/templates/hooks/commit-msg

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# Candidate lint is driven solely by reference-transaction. This hook intentionally carries no marker,
+# message hash, tree binding, or TTL; Git's immutable commit object is the only candidate identity.
+# Git does not apply scissors cleanup to every no-editor/-F path, so normalize the final message here,
+# after every editor, using scissors only when the repository explicitly selected that cleanup mode.
+if [ "$(git config --get commit.cleanup 2>/dev/null || true)" = scissors ]; then
+  msg_file="$1"
+  tmp="${msg_file}.spexcode-scissors.$$"
+  awk '/^# ------------------------ >8 ------------------------$/ { exit } { print }' "$msg_file" \
+    | git stripspace --strip-comments > "$tmp"
+  mv "$tmp" "$msg_file"
+fi
+exit 0

package/templates/hooks/post-checkout

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ footprint refresh (post-checkout) ([[commit-surgery]]) - a branch checkout is one of the three git
+# transitions that can move the materialize's inputs: .spec/.plugins content changes across branches, and a
+# contract file's TRACKEDNESS can flip (switching to a branch that tracks CLAUDE.md checks out the pristine
+# index prose — the re-materialize here writes the block back into the working file, binds the clean/smudge
+# filter, and withdraws the exclude entry; the kind-transition heals itself). Git-native anchors only —
+# never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor (pre-commit's
+# unconditional materialize is the correctness backstop).
+#
+# args: <prev-HEAD> <new-HEAD> <flag>; flag=1 is a branch checkout, flag=0 a file checkout (git checkout --
+# <path> restores files and moves nothing the materialize depends on — skip those).
+[ "${3:-0}" = "1" ] || exit 0
+# Session creation owns the one post-seed materialize in its transaction.
+[ "${SPEXCODE_DEFER_FOOTPRINT_REFRESH:-}" = "session-create" ] && exit 0
+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 internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$repo_root/node_modules/.bin/spex" ]; then
+  "$repo_root/node_modules/.bin/spex" internal refresh-footprint >/dev/null 2>&1 || true
+elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then
+  "$main_root/spec-cli/bin/spex.mjs" internal refresh-footprint >/dev/null 2>&1 || true
+fi
+exit 0

package/templates/hooks/post-merge

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ 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 internal 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).
+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_run() {
+  if command -v spex >/dev/null 2>&1; then spex "$@"
+  elif [ -x "$repo_root/node_modules/.bin/spex" ]; then "$repo_root/node_modules/.bin/spex" "$@"
+  elif [ -x "$main_root/spec-cli/bin/spex.mjs" ]; then "$main_root/spec-cli/bin/spex.mjs" "$@"
+  else return 127; fi
+}
+
+# @@@ footprint refresh ([[commit-surgery]]) - a merge is one of the three git transitions that can move the
+# materialize's inputs (.spec/.plugins content, contract-file trackedness), so re-materialize here — git-native
+# anchors only, never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor.
+spex_run internal refresh-footprint >/dev/null 2>&1 || true
+
+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')
+spex_run internal nudge "$node"
+exit 0

package/templates/hooks/pre-commit

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ 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 launcher by path       - dogfood: bin/spex.mjs (owns tsx resolution + the mid-merge guard).
+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/bin/spex.mjs" ]; then
+  spex_kind=pkg
+fi
+spex_cli() {
+  case "$spex_kind" in
+    path)  spex "$@" ;;
+    local) "$repo_root/node_modules/.bin/spex" "$@" ;;
+    pkg)   "$main_root/spec-cli/bin/spex.mjs" "$@" ;;
+    *)     return 127 ;;
+  esac
+}
+
+# A commit containing only issue storage cannot change governed code or an anchor range. Keep this as a
+# path-property check at the hook boundary so the common dashboard write does not pay materialize/eval
+# backstops; any mixed commit continues through the full hook chain and the reference transaction gate.
+staged_issue_only=1
+staged_any=0
+while IFS= read -r -d '' staged_path; do
+  staged_any=1
+  case "$staged_path" in .spec/.issues/*) ;; *) staged_issue_only=0 ;; esac
+done < <(git diff --cached --name-only -z 2>/dev/null)
+if [ "$staged_any" -eq 1 ] && [ "$staged_issue_only" -eq 1 ]; then
+  exit 0
+fi
+
+# @@@ tree-unchanged stamp - a commit whose tree EQUALS HEAD's tree (`git write-tree` over the commit's own
+# index — the hook's GIT_INDEX_FILE, a temp HEAD-tree index for `commit --only --allow-empty`) adds NO
+# content: it cannot smuggle code past the main-guard below and cannot introduce spec↔code drift, so the
+# whole hook passes it. This is `spex spec ack`'s empty Spec-OK stamp — the reason ack works on a trunk merge
+# commit (amending it would re-author the merge after MERGE_HEAD is gone and read as direct authoring) and
+# with a DIRTY real index (the lint shim below reads the real index via git.ts's env-strip, which would
+# otherwise block the stamp on the very drift it acknowledges). Deliberately a one-line tree compare, not an
+# "is this an amend?" heuristic (undecidable at pre-commit time).
+if [ "$(git write-tree 2>/dev/null)" = "$(git rev-parse 'HEAD^{tree}' 2>/dev/null || echo none)" ]; then
+  exit 0
+fi
+
+# @@@ 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), and a tree-unchanged
+# stamp already passed above. 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() (the stable mainBranch project fact stamped at adoption; conventional default 'main') — so
+# the guard protects whatever the repo's trunk is actually named. When the CLI isn't resolvable (advisory
+# mode), only the convention is available: shell does not guess identity from a mutable checkout.
+branch=$(git symbolic-ref --short HEAD 2>/dev/null || echo)
+git_dir=$(git rev-parse --git-dir 2>/dev/null)
+trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
+[ -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 and tree-unchanged stamps (spex spec ack) pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
+  exit 1
+fi
+
+# @@@ footprint surgery ([[commit-surgery]]) - the history anchor: an UNCONDITIONAL materialize (masks fresh
+# at the one moment history is written) + staged-index repair — strip the spexcode sentinel block from any
+# staged blob (source = the staged blob, so `git add -p` partial staging survives), unstage HEAD-untracked
+# generated artifacts. REPAIRS AND PROCEEDS, never rejects; one note per repair on stderr. Runs INSIDE the
+# hook env on purpose: the surgery honors GIT_INDEX_FILE so a pathspec/`-a` commit's TEMPORARY index is the
+# one repaired. Advisory when spex is unresolvable or errors (CI lint enforces); never blocks the commit.
+if [ -n "$spex_kind" ]; then
+  spex_cli internal commit-surgery || echo "• SpexCode: footprint surgery skipped (error above) — a generated artifact may be staged; CI still enforces." >&2
+fi
+
+# @@@ spec-lint - reference-transaction owns the candidate gate. When the installed consumer is the
+# SpexCode unmarked predicate, running full HEAD lint here would restore the history-scaled cost this gate
+# removes. A missing/custom consumer keeps the old full lint fallback, so a hook collision never reduces
+# local coverage. Static identity matters: never execute a user-owned hook with made-up probe arguments.
+# Bypass with SPEXCODE_SKIP_LINT=1. It shims through shared spex_cli() resolved above.
+if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
+  if [ -n "$spex_kind" ]; then
+    consume_hook=$(git rev-parse --git-path hooks/reference-transaction 2>/dev/null)
+    if [ -x "$consume_hook" ] && grep -q 'one unmarked predicate at Git' "$consume_hook" 2>/dev/null; then
+      lint_rc=0
+    else
+      spex_cli spec lint >&2
+      lint_rc=$?
+    fi
+    # exit 75 = the launcher's mid-merge guard (spex's own source holds conflict markers — transient).
+    # Degrade to advisory rather than walling every commit behind a merge someone else is resolving.
+    if [ "$lint_rc" -eq 75 ]; then
+      echo "• SpexCode: spec-lint skipped — spex is paused mid-merge (exit 75); CI still enforces." >&2
+    elif [ "$lint_rc" -ne 0 ]; then
+      echo "✗ SpexCode: spec-lint failed — fix the spec↔code links or bypass with SPEXCODE_SKIP_LINT=1." >&2
+      exit 1
+    else
+      # @@@ eval backstop - reject a staged eval offender: a stray evidence blob copied into the tree (blobs
+      # belong in the shared git common dir, never committed) OR a malformed eval.md (a scenario schema
+      # violation). Logic lives in spec-eval; this is the lint-shim's twin. (this node's contract)
+      if ! spex_cli internal check-staged >&2; then
+        echo "✗ SpexCode: internal check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
+        exit 1
+      fi
+    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,35 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ 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.
+#
+# The id is simply READ here, because it was established where it is KNOWN: whoever creates an agent's
+# execution context injects that context's own record id, and nothing else may carry one.
+#   - a session launch bakes `SPEXCODE_SESSION_ID=<record id>` into the agent's process — and STRIPS every
+#     session-identity variable it inherited first, so the pane's ancestry (a tmux server started long ago by
+#     someone else) cannot smuggle one in;
+#   - a codex thread gets the same variable injected into every command it spawns, at `thread/start`, via
+#     codex's own `shell_environment_policy.set` — the tool shell is a child of the SHARED app-server and must
+#     therefore inherit nothing, so the backend hands it its identity per thread instead;
+#   - that shared app-server, and any other process we own that belongs to no single session, is spawned with
+#     those variables stripped. A process that outlived its session handing its id to strangers is exactly how
+#     this trailer once named a session that no longer existed (github#76).
+# So there is nothing to resolve, alias, or verify at commit time: the variable is present only in processes
+# that genuinely belong to that session, and it already IS the record id. No store lookup, no per-harness
+# tiers, and nothing derived from the current directory — where a process stands says nothing about who it is.
+# No id → no trailer. An existing Session: trailer is left alone, so the ritual / a human can set one by hand.
+set -euo pipefail
+msg_file="$1"
+grep -qiE '^Session:[[:space:]]' "$msg_file" && exit 0
+[ -n "${SPEXCODE_SESSION_ID:-}" ] || exit 0
+
+# Stamp via interpret-trailers (git's own sample-hook mechanism), NOT a raw printf append: appending after a
+# message that already carries a trailer block (e.g. `spex spec ack`'s Spec-OK) opens a new paragraph, and git then
+# parses ONLY the last paragraph as trailers — the earlier trailers silently become body prose. interpret-trailers
+# appends into the existing block, keeping ONE parseable block. It needs the file newline-terminated first:
+# on an unterminated message (git merge -m writes MERGE_MSG without one) it folds the trailer into the subject
+# paragraph, where git's trailer parser never looks — the reason merge commits' Session: never parsed.
+[ -n "$(tail -c1 "$msg_file")" ] && echo >> "$msg_file"
+git interpret-trailers --in-place --trailer "Session: $SPEXCODE_SESSION_ID" "$msg_file"
+exit 0