@spexcode/spec-cli 0.6.5

package/templates/hooks/reference-transaction

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# spexcode-managed-hook-v1
+# @@@ candidate lint ([[code-anchor]]) - one unmarked predicate at Git's prepared ref boundary:
+# a refs/heads update that introduces a commit object which is not already reachable from refs/reflogs.
+# Structural ref plumbing is inert; no commit-msg arm, marker, TTL, tree, parent, or message identity exists.
+set -u
+state="${1:-}"
+payload=$(cat)
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || printf 'spexcode-gate: reference state=%s action=%s payload=%s\n' "$state" "${GIT_REFLOG_ACTION:-}" "$(printf '%s' "$payload" | tr '\n' ';')" >&2
+[ "$state" = prepared ] || exit 0
+[ -z "${SPEXCODE_SKIP_LINT:-}" ] || exit 0
+
+candidate=
+candidate_old=
+operation_git_dir=$(git rev-parse --git-dir 2>/dev/null || printf .git)
+while read -r old new ref; do
+  [ -n "${new:-}" ] || continue
+  case "$ref" in HEAD|refs/heads/*) ;; *) continue ;; esac
+  case "$new" in *[!0-9a-f]*) continue ;; esac
+  [ "$(git cat-file -t "$new" 2>/dev/null || true)" = commit ] || continue
+  # Git exposes no operation name at this boundary. Do not infer one from old=0 or from ancestor process
+  # command lines: an unreachable ref creation is the same observable candidate as any other new ref object.
+  case "$old" in '' ) continue ;; esac
+  candidate="$new"
+  candidate_old="$old"
+  break
+done <<< "$payload"
+[ -n "$candidate" ] || exit 0
+
+# Rebase/cherry-pick/revert/am author new content even when a detached rewrite left the object in a reflog.
+# Ordinary reset/branch/checkout targets are already reachable and therefore remain inert.
+force_operation=0
+if [ -d "$operation_git_dir/rebase-merge" ] || [ -d "$operation_git_dir/rebase-apply" ] \
+  || [ -d "$operation_git_dir/sequencer" ] || [ -f "$operation_git_dir/CHERRY_PICK_HEAD" ] \
+  || [ -f "$operation_git_dir/REVERT_HEAD" ]; then
+  force_operation=1
+fi
+if [ "$force_operation" -eq 0 ]; then
+  if [ -n "$(git for-each-ref --contains "$candidate" --format='%(refname)' 2>/dev/null)" ] \
+    || git reflog --all --format=%H 2>/dev/null | grep -Fqx "$candidate"; then
+    [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: reachable candidate=$candidate skipped" >&2
+    exit 0
+  fi
+fi
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: candidate=$candidate force=$force_operation" >&2
+
+# Local issue/remark commits change only non-topology data. With no code path and no node spec.md in the
+# candidate diff, an anchored unit cannot have moved and no governing claim can have changed. Prove that
+# narrow shape directly at the ref boundary so dashboard writes do not launch a full CLI merely to rediscover
+# the same fact. This is candidate classification, not a writer-set bypass: every other shape still lints.
+issue_only=1
+parent_count=$(git rev-list --parents -n1 "$candidate" 2>/dev/null | awk '{print NF-1}')
+[ "${parent_count:-0}" -gt 1 ] && issue_only=0
+changed_paths=$(git -c core.quotePath=false diff-tree --no-commit-id --name-only -r -m "$candidate_old" "$candidate" 2>/dev/null || true)
+[ -n "$changed_paths" ] || issue_only=0
+while IFS= read -r path; do
+  [ -n "$path" ] || continue
+  case "$path" in .spec/.issues/*) ;; *) issue_only=0; break ;; esac
+done <<< "$changed_paths"
+if [ "$issue_only" -eq 1 ]; then
+  [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: issue-only candidate=$candidate skipped before lint" >&2
+  exit 0
+fi
+
+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
+}
+if [ -z "$spex_kind" ]; then
+  echo "• SpexCode: candidate spec-lint skipped — no \`spex\` CLI found; CI still enforces." >&2
+  exit 0
+fi
+SPEXCODE_GATE_SCOPE_ONLY=1 spex_cli spec lint --pending "$candidate" >&2
+lint_rc=$?
+if [ "$lint_rc" -eq 76 ]; then
+  [ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: non-governed candidate=$candidate skipped before full lint" >&2
+  exit 0
+fi
+[ -z "${SPEXCODE_GATE_TRACE:-}" ] || echo "spexcode-gate: lint_rc=$lint_rc candidate=$candidate" >&2
+if [ "$lint_rc" -eq 75 ]; then
+  echo "• SpexCode: candidate spec-lint skipped — spex is paused mid-merge (exit 75); CI still enforces." >&2
+  exit 0
+fi
+if [ "$lint_rc" -ne 0 ]; then
+  echo "✗ SpexCode: candidate spec-lint failed; the ref is unchanged and staged/sequencer state is intact." >&2
+  echo "  Explicit bypass: SPEXCODE_SKIP_LINT=1 git commit …" >&2
+  echo "  Continue after staging a repair: git merge --continue | git cherry-pick --continue | git rebase --continue" >&2
+  echo "  Abort the active operation:       git merge --abort    | git cherry-pick --abort    | git rebase --abort" >&2
+  exit 1
+fi
+exit 0

package/templates/spec/project/.plugins/commands/extract/spec.md

@@ -0,0 +1,66 @@
+---
+title: extract
+surface: command
+status: active
+hue: 30
+desc: Reverse-engineer — or re-run to reconcile — a faithful spec tree out of existing code: responsibility nodes at contract altitude, intent never fabricated, every frontend node carrying a loss signal.
+kind: mutating
+---
+Reverse-engineer a spec tree for the target source area(s) below — or **re-run to reconcile** an
+already-extracted area, the same pass that closes the gaps code growth opens (an unclaimed governed file, a
+frontend node missing its loss signal, a thin scenario). Extraction is not a one-shot. Aim for a tree where
+every governed file is claimed and `spex spec lint` is clean, bodies at contract altitude and in the codebase's
+own primary language (a predominantly-Chinese repo → Chinese specs).
+
+{{targets}}
+
+**Find the spine the code already declares first** — a barrel of exports, a README or design doc, the
+dependency direction between modules — and adopt it as the top-level shape, refined where the code reveals
+finer responsibilities. Only when the code declares no architecture is the top-level cut a judgment call
+worth raising with the human.
+
+Then grow nodes under that spine:
+
+- **Decompose by responsibility, not by file.** A node is one job the code does. A fat file split across
+  several jobs becomes several nodes that each claim it; one job spanning several files becomes one node
+  claiming them all. Every governed file is claimed by at least one node; nest into subtrees where warranted.
+- **Group wide layers; don't mirror the file tree — at every level, the root included.** One-node-per-folder
+  is a smell. If a node would have more than ~7 direct children you're under-grouping: add intermediate
+  **sub-domain** nodes that cluster siblings serving one concern (model-config + selection + auth → a *model*
+  domain), and recurse until every level reads as a handful of siblings, not a flat wall. Fold cross-cutting
+  substrate (design system, i18n, platform glue) under one *foundation* node that claims the cluster's
+  barrel/wiring files (so it isn't pure-prose); split a fat folder holding several distinct jobs. Group by
+  responsibility, never to hit a number.
+- **Stay at contract altitude.** State each node's intent, invariants, and outward behavior — what it
+  guarantees and why — not how the code does it.
+- **Never fabricate intent.** Code shows *what it does*, rarely *why*. Read any README/design docs for real
+  intent; where you can still only see behavior, state the behavior and mark the intent as inferred rather
+  than inventing a rationale.
+- **Reserve pure-prose nodes** (no `code:`) for a genuine cross-cutting contract no single file owns. Use
+  sparingly.
+- **Mind the scope boundary.** A file that looks like a thin wrapper may be the foot of a feature defined
+  outside the target area — flag it instead of mis-homing it, and prefer extracting the whole repo so
+  cross-cutting features stay visible. If nothing reaches a file, say it's likely dead rather than
+  dignifying it with a confident spec.
+
+**Give every frontend node a loss signal.** A node that governs UI or visual code (`.tsx`/`.jsx`/`.vue`/
+`.svelte`/`.css`, or the dashboard) is a blind spot until it carries a `eval.md` — so write one as you
+extract it: a **real user-path** scenario — a goal and the steps to reach it through the running app (never a
+bare render-check), covering a failure/empty/edge state — with a **description** of those steps, the
+**expected** zero-loss result, and **≥1 `tags`** classifying it (a surface like `frontend-e2e`/`backend-api`/
+`cli`, a device like `desktop`/`mobile`) drawn from the configured library (`lint.scenarioTags`); a tag
+outside the library fails `scan`, so use an existing one or extend the library. Frontend scenarios are measured by looking (YATU) — a screenshot filed with
+`spex eval add <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex eval lint` to
+list the frontend nodes still uncovered. On a **re-run** this is also where you sharpen — give an uncovered
+node its first scenario, tighten a thin one (a bare render-check, or a stale `expected`); `spex guide eval`
+has the schema.
+
+**Extract incrementally — don't plan the whole tree before writing.** For a large area (hundreds of files),
+enumerating the whole partition up front or scripting a generator to emit it at once burns context before a
+node lands and loses everything to one interruption. Fix the top-level cut and commit it, then take ONE
+subtree at a time (write the leaf, list its files, lint, COMMIT) before the next — never more than one
+subtree uncommitted, so progress survives context limits.
+
+Confirm `spexcode.json`'s `governedRoots` points at the real source dirs first — lint reads silently empty
+otherwise. Commit one node per commit (`spec: <id> — extract from <area>`) and run `spex spec lint` after each:
+0 errors, 0 coverage/altitude warnings.

package/templates/spec/project/.plugins/commands/regroup/spec.md

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

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

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

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

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

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

@@ -0,0 +1,8 @@
+---
+title: supervisor
+surface: command
+status: active
+hue: 280
+desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
+---
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. This preset IS your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize) — the CLI's own `spex help session` is the reference for every verb's exact semantics. Drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` creates the parent-child relation and automatically installs your managed `parent` watch; inspect that existing relation/source with `spex session watch list`, so do NOT add a manual watch for this child — give it ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), review proposals with `spex session review <id>`, dispatch the merge of good ones back to their own session (`spex session merge <id>`; the doer syncs the base into its own worktree first, so what reaches `<root>` is a trivial merge) and confirm it landed, then close. `<root>` is the fleet's ONE landing door — it takes one landing at a time, so a worker whose merge finds it mid-merge waits rather than racing, and you never fix up another lane's half-merged index yourself. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); for a local next-lifecycle-edge read when no managed delivery exists, background `spex session wait <id>` — it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path; `spex session watch stream` is human-only and STREAMS forever, so never block on it. **Stay parked while your fleet runs:** `spex session new`'s managed watch delivery is a real wake-up, so park while it exists. A manual `spex session watch <id>` is deliberate ongoing supervision of an existing session, not a one-off wait: it adds your `manual` source, and every future AUTHORED state transition is queued as a message to the watcher until `spex session watch cancel <id>` removes that source. That creates continuing traffic/noise, so use manual watch only when you want that consequence; `watch list` inspects the relation/source and `watch cancel` removes only the manual source. An `@<session>` explanation request is point-to-point: use `spex session send <id> "<question>"`; the reply hint returns over send, never watch/wait. Only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. Two footguns that bite a fresh supervisor. First: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Second: `<id>` always names a WORKER YOU DISPATCHED, spelled out — never `.` and never your own id. `.` means the session running the command, so `close .` deletes your own worktree, branch and record mid-turn and takes your fleet's manager down with it; your own ending is a declaration (`done --propose close`), never a close you run on yourself. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows:

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

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

package/templates/spec/project/.plugins/core/comment-altitude/spec.md

@@ -0,0 +1,9 @@
+---
+title: comment-altitude
+surface: system
+status: active
+hue: 200
+desc: A config plugin — code comments navigate non-obvious local reasoning; specs own product intent and contract.
+---
+Specs own intent, invariants, policy, and observable contracts. Comments only navigate non-obvious local decisions.
+`spex guide spec` has the comment-altitude details.

package/templates/spec/project/.plugins/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 `internal 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} internal session-idle --session "$sid"

package/templates/spec/project/.plugins/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. As a board-lifecycle hook it also acts only on a GOVERNED session — it resolves the record in the global store from the payload's `session_id` and no-ops unless `governed: true` — then marks idle via `spex internal session-idle --session <id>`. It is guarded so it never clobbers a deliberate declaration: marking idle applies only to a session still in the undeclared `active` state, leaving any considered `awaiting`, `asking`, `parked`, or `error` claim untouched. Together with [[stop-gate]] and [[session-fail]] it closes the last gap where a session could stop without its true state reaching the board.

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

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# @@@ mark-active - the SINGLE turn-boundary hook, wired to BOTH UserPromptSubmit and PreToolUse. It has ONE
+# job, keyed off the session's global record dir: keep the declared FRESHNESS state honest. It carries no
+# conversation — a message reaches this agent as an ordinary prompt through the harness adapter
+# ([[delivery-queue]]), which is the only way anything enters a turn. A hook that also injected mail handed
+# every message over twice and made the agent's context depend on which of two paths won a race.
+# Freshness 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.
+# @@@ read cheap, write through the ONE writer - this hook is on the hot path (every tool call), so it does
+# its own READ in pure shell: three exact-line greps answer "already active, nothing stale to clear?", which
+# is the overwhelmingly common case, and that path exits without spawning anything. When there IS a change to
+# make it hands the write to `spex internal session-state`, the same structured writer the CLI declarations
+# use. It never edits session.json itself: an asking note is arbitrary human/agent prose, and a writer that
+# substitutes prose into existing JSON meets a quote, a backslash, or a newline and leaves a record nothing
+# can parse — which is how a live session came to report "no session record" ([[sessions-core]]).
+# @@@ 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)
+# an IN-PROCESS SUBAGENT's tool call (Claude's Task tool) fires the parent's hooks with the PARENT's
+# session_id — flipping here let a supervising parent's own subagents erase its declared park/ask within
+# seconds and race the stop-gate into "undeclared stop" (issue #60). A subagent working is not the parent
+# agent ACTING, so its calls never touch the record; the parent's own next tool call still flips. The
+# discriminator is the payload's own top-level agent_id stamp (hp_is_subagent) — deterministic, never a
+# timing window.
+[ -n "$(hp_is_subagent "$payload")" ] && exit 0
+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 '^[[:space:]]*"governed"[[:space:]]*:[[:space:]]*true,\?$' "$rec" 2>/dev/null || exit 0
+
+# does FIELD's line hold exactly VALUE? The record is written one-field-per-line by the single writer
+# (sessions.ts writeRecord), so a whole-line match is exact — and, unlike a value regex, it cannot be fooled
+# by an escaped quote inside a neighbouring note.
+jline_is() { grep -q "^[[:space:]]*\"$1\"[[:space:]]*:[[:space:]]*\"$2\",\?$" "$rec" 2>/dev/null; }
+
+# The writer's own stdout is a human confirmation, not hook output — swallow it so a PreToolUse handler never
+# emits a decision-shaped line; its stderr (a refusal — a corrupt or retired record) still surfaces. We always
+# exit 0: this hook observes freshness, it is not a gate on the tool that triggered it.
+if [ -n "$(hp_is_ask "$payload")" ]; then
+  # first question's text → the note (best-effort). It is passed as ONE argv word to the writer, so quotes,
+  # backslashes, newlines, and non-ASCII reach the record intact — no shell ever composes the JSON.
+  ${SPEX:-spex} internal session-state asking --session "$sid" --note "$(hp_ask_note "$payload")" >/dev/null
+  exit 0
+fi
+
+# cheap path: already active with nothing stale to clear → no-op (the common every-tool case), no spawn.
+jline_is status active && jline_is proposal '' && jline_is note '' && exit 0
+${SPEX:-spex} internal session-state active --session "$sid" >/dev/null
+exit 0

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

@@ -0,0 +1,22 @@
+---
+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.
+
+The one activity that does NOT count as the session acting is an IN-PROCESS SUBAGENT's tool call (the harness's Task tool — a sub-conversation inside the same process). Such a call fires the parent's hooks carrying the parent's `session_id`, so without a discriminator a supervising parent could never hold a declared state: its own subagents erased every park/ask within seconds and raced the stop-gate into "undeclared stop". The harness stamps subagent-executed calls with a top-level `agent_id` field the parent's own calls never carry; `hp_is_subagent` reads that stamp deterministically (scanning only the pre-`tool_input` payload prefix, where a tool parameter or file content can never fake an unescaped key), and this hook skips the flip entirely. A subagent working is its parent supervising, not the parent moving on — the parent's own next tool call still flips as before.
+
+It is a board-lifecycle hook, so it acts only on a GOVERNED (dashboard-launched) session — it resolves that session's record in the global per-session store from the payload's `session_id` and no-ops unless `governed: true`. The state it writes lives in that record's `session.json` (state), but it never edits that file itself: it READS it in pure shell (whole-line matches, the hot path stays jq-free) and hands every write to `spex internal session-state`, the one structured writer the CLI declarations use — an asking note is arbitrary prose, and a shell that substitutes prose into existing JSON eventually writes a record nothing can parse.
+
+This hook carries no conversation. A message addressed to the session reaches its agent as an ordinary prompt through the harness adapter (delivery-queue), which is the only way anything enters a turn, so an inter-agent message is indistinguishable from a human one at the point of arrival. A hook that also injected mail delivered every message a second time and made the agent's context depend on which of two paths won a race; a freshness signal reports a fact about the session and hands nothing over.
+
+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/.plugins/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} internal session-fail --session "$sid"

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

@@ -0,0 +1,15 @@
+---
+title: session-fail
+surface: hook
+status: active
+hue: 200
+events:
+- StopFailure
+order: 10
+block: false
+code:
+- .spec/project/.plugins/core/session-fail/fail.sh
+---
+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 on the failure event: the failure already happened, so the only job is to report it truthfully. As a board-lifecycle hook it acts only on a GOVERNED session — resolved in the global store from the payload's `session_id` — and writes via `spex internal session-fail --session <id>`. That machine entry reaches the same live-active compare-and-set as Codex's native failed completion and a headless turn's non-zero exit (harness-adapter): only an undeclared, non-stopped `active` record becomes `error`. A declaration, explicit stop, or archive that landed first remains authoritative; a late native failure never rewrites it. This one writer keeps the [[stop-gate]] family's invariant intact for every harness while each adapter retains only its native failure signal.

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

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# @@@ spec-first - a one-shot governed READ gate. It advances only when the adapter resolves a read path AND
+# the spec graph resolves a real `code:` governor for that path. Irrelevant tools, unresolvable reads, and
+# uncovered/related-only files leave the sentinel absent, so any number of ungoverned reads cannot mute the
+# first later governed read. That read spends the gate and blocks once with its actual governor; retries pass.
+# @@@ event vs matcher - materialized shims bind PreToolUse event-wide on every harness. hp_code_path ... read
+# is the ONE adapter matcher that reduces Claude/Codex payload differences to a path. This handler owns the
+# harness-agnostic state transition and governor lookup; it has no tool-name, harness, or filename branches.
+# @@@ all sessions, global sentinel - file governance is independent of a record's `governed` bit, so the
+# same gate serves dashboard and self-launched agents. The sentinel lives in the per-session global store dir
+# (see hp_store_dir) and is created only by the first governed read. cwd = the worktree.
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+S="${SPEX:-spex}"
+payload=$(cat 2>/dev/null)
+sid=$(hp_session_id "$payload"); [ -n "$sid" ] || exit 0
+sdir=$(hp_store_dir "$sid") || exit 0
+sent="$sdir/spec-checked"
+[ -f "$sent" ] && exit 0
+
+paths=$(hp_code_path "$payload" read)
+[ -n "$paths" ] || exit 0
+repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+
+# The internal projection uses the authoritative code: edge resolver and emits stable id<TAB>spec-path rows;
+# empty output means uncovered or related-only, deliberately a non-transition.
+path=""; owner=""
+while IFS= read -r candidate; do
+  [ -n "$candidate" ] || continue
+  governors=$(cd "$repo" && $S internal spec-governors "$candidate" 2>/dev/null)
+  [ -n "$governors" ] || continue
+  path="$candidate"
+  owner=$(printf '%s\n' "$governors" | awk -F '\t' 'BEGIN{sep=""} {printf "%s%s [%s]",sep,$2,$1; sep=", "}')
+  break
+done <<EOF
+$paths
+EOF
+[ -n "$owner" ] || exit 0
+
+mkdir -p "$sdir"; : > "$sent"
+reason=$($S internal hook-prompt spec-first --path "$path" --owner "$owner") || 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/core/spec-first/spec.md

@@ -0,0 +1,17 @@
+---
+title: spec-first
+surface: hook
+status: active
+hue: 200
+events:
+- PreToolUse
+order: 20
+block: true
+---
+A one-shot, governed-aware READ gate. Its state advances only when the agent is about to read code that has a real governor (`code:` ownership). The first such read creates the session sentinel and blocks once, naming the resolved governing spec and directing the agent through the relevant parent, sibling, and child contracts before retrying. Once that contract-read path has been demanded, later code reads pass.
+
+The state machine has no transition for an irrelevant tool, an unresolvable path, or an uncovered/related-only file. In particular, any number of ungoverned reads remain allowed without consuming or muting the gate; a later governed read must still block. This is file governance, distinct from a session record's `governed` field: spec-awareness still serves dashboard-launched and user-self-launched agents alike, with the sentinel created on demand in the session's global store directory.
+
+Event delivery and semantic matching have separate responsibilities. The hook subscribes to the shared `PreToolUse` lifecycle event because Claude and Codex shims deliver that event broadly. The harness adapter's single `read` matcher decides whether the payload represents a file read and extracts its path; the hook then asks the spec graph whether that path has a governor. Harness payload differences stay inside the adapter, while the gate and its state transitions stay one mechanism.
+
+This enforces the read-the-contract-first rule of [[core]] only where a contract actually exists, at the moment before understanding hardens around governed code.

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

@@ -0,0 +1,66 @@
+#!/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 spec 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
+repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+repo=$(cd "$repo" 2>/dev/null && pwd -P) || exit 0
+
+hp_actionable_repo_path() {
+  local raw="$1" target dir base abs rel
+  case "$raw" in
+    /*) target="$raw" ;;
+    *)  target="$PWD/$raw" ;;
+  esac
+  dir=${target%/*}; base=${target##*/}
+  [ "$dir" = "$target" ] && dir=.
+  abs=$(cd "$dir" 2>/dev/null && printf '%s/%s' "$(pwd -P)" "$base") || return 1
+  case "$abs" in
+    "$repo"/*) rel=${abs#"$repo"/} ;;
+    *) return 1 ;;
+  esac
+  [ -n "$rel" ] || return 1
+  # editing the spec itself is not a governed-code edit -> nothing to annotate.
+  case "$rel" in .spec/*|*/.spec/*|*/spec.md|spec.md|.git/*) return 1 ;; esac
+  # Speak only for files Git would care about: tracked files, or untracked files that are not ignored.
+  git -C "$repo" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1 && { printf '%s' "$rel"; return 0; }
+  git -C "$repo" check-ignore -q -- "$rel" && return 1
+  printf '%s' "$rel"
+}
+
+# the code file(s) just MUTATED (empty when this tool didn't mutate a file, e.g. a pure read). A codex
+# multi-file apply_patch yields several paths (one per line) — annotate EACH governed code file, once.
+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
+  path=$(hp_actionable_repo_path "$path") || continue
+  [ -f "$led" ] && grep -qxF -- "$path" "$led" && continue
+  mkdir -p "$sdir"; echo "$path" >> "$led"
+  m=$(cd "$repo" && $S spec 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
+msg=$($S internal hook-prompt spec-of-file --details "$msg") || exit 1
+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/.plugins/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. Like [[spec-first]], spec-awareness is universal — it is NOT gated on `governed` and runs for any agent. It is deduplicated once per normalized repo-relative file via a ledger that lives as a sibling file in the session's global store dir (keyed by the payload's `session_id`), 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. It only speaks for Git-relevant files inside the current repo: tracked files, plus new untracked files that are not ignored. Paths outside the repo, `.spec`, `.git`, and ignored artifacts stay silent.
+
+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.