spexcode 0.6.7 → 0.6.8

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-fail/fail.sh

@@ -1,12 +1,13 @@
 #!/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.
+# Mark the session errored when a turn ends on an API failure (StopFailure). The canonical lifecycle writer owns
+# the governed-session boundary and active-only compare-and-set; this hook only decodes the native event and
+# passes its acting session id.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 payload=$(cat 2>/dev/null)
+# an IN-PROCESS SUBAGENT's failed turn (Claude's Task tool) fires the parent's hooks with the PARENT's
+# session_id, so without this the parent's own record would be flipped to `error` by a helper it spawned —
+# the same defect already fixed for mark-active, and the same discriminator fixes it: the payload's own
+# top-level agent_id stamp. A subagent's turn dying is not THIS session's turn dying.
+[ -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"
-grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
 exec ${SPEX:-spex} internal session-fail --session "$sid"

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-fail/spec.md

@@ -12,4 +12,6 @@ code:
 ---
 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.
+**A SUBAGENT'S FAILED TURN IS NOT THIS SESSION'S FAILED TURN.** An in-process subagent (Claude's Task tool) fires the parent's hooks carrying the PARENT's `session_id`, so a helper the session spawned could flip the session that spawned it to `error` — a supervising parent marked dead by a delegate it is still supervising. The discriminator is the payload's own top-level `agent_id` stamp, the deterministic one [[mark-active]] already uses for the same reason; it is not a timing window. This is one defect class, so it gets one answer at both hooks rather than a second idea of what "this session acted" means.
+
+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 passes the payload's acting `session_id` to `spex internal session-fail --session <id>`; the canonical writer, not shell parsing of `runtime.json`, resolves the governed record and owns the live-active compare-and-set. 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/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-listen/session-listen.sh

@@ -0,0 +1,133 @@
+#!/usr/bin/env bash
+set -u
+
+# A self-launch project opts in only by configuring the adopter database. No configured database means no listener.
+if [ -z "${SPEX_SESSION_DATABASE_PATH+x}" ] && [ -z "${SPEX_SESSION_CONFIG+x}" ]; then
+  exit 0
+fi
+
+# The explicit command is one executable path; an invalid explicit value must not silently fall through to PATH.
+cli="${SPEX_SESSION_CLI:-}"
+if [ -z "$cli" ]; then
+  cli=$(command -v spex-session 2>/dev/null || true)
+fi
+if [ -z "$cli" ] || [ ! -x "$cli" ]; then
+  printf '%s\n' 'session-listen: spex-session CLI not found; install @spexcode/session-selflaunch (npm install) or set SPEX_SESSION_CLI to its executable path' >&2
+  exit 2
+fi
+
+for tool in awk base64 iconv od grep tail sed mktemp cat tr rm; do
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    printf "session-listen: required delivery tool '%s' is missing; install it or repair PATH before retrying\n" "$tool" >&2
+    exit 2
+  fi
+done
+
+capability_error() {
+  printf "session-listen: required delivery capability '%s' is unavailable; install compatible tooling or repair PATH before retrying\n" "$1" >&2
+  exit 2
+}
+
+escape_awk='
+  BEGIN { ORS = "" }
+  NR > 1 { printf "\\n" }
+  {
+    for (i = 1; i <= length($0); i++) {
+      c = substr($0, i, 1)
+      if (c == "\\") printf "\\\\"
+      else if (c == "\"") printf "\\\""
+      else if (c == "\t") printf "\\t"
+      else if (c == "\r") printf "\\r"
+      else if (c == "\b") printf "\\b"
+      else if (c == "\f") printf "\\f"
+      else printf "%s", c
+    }
+  }
+'
+control_pattern='(^|[[:space:]])(00|01|02|03|04|05|06|07|08|0b|0c|0e|0f|1[0-9a-f])([[:space:]]|$)'
+body64_sed='s/.*"bodyBase64":"\([^"]*\)".*/\1/p'
+
+# Existence is not capability. These fixed vectors prove every non-default operation before at-most-once dequeue.
+[ "$(printf ' A ' | tr -d '[:space:]')" = A ] || capability_error 'tr -d character classes'
+[ "$(printf A | od -An -v -tx1 | tr -d '[:space:]')" = 41 ] || capability_error 'od hexadecimal bytes'
+[ "$(printf QQ== | base64 -d 2>/dev/null | od -An -v -tx1 | tr -d '[:space:]')" = 41 ] \
+  || capability_error 'base64 -d exact decoding'
+[ "$(printf '\303\251' | iconv -f UTF-8 -t UTF-8 2>/dev/null | od -An -v -tx1 | tr -d '[:space:]')" = c3a9 ] \
+  || capability_error 'iconv UTF-8 validation'
+printf ' 00 ' | grep -Eq "$control_pattern" || capability_error 'grep extended quiet match'
+if printf ' 0a ' | grep -Eq "$control_pattern"; then capability_error 'grep extended quiet exclusion'; fi
+[ "$(printf AB | tail -c 1)" = B ] || capability_error 'tail byte selection'
+[ "$(printf '%s' '{"bodyBase64":"QQ=="}' | sed -n "$body64_sed")" = QQ== ] \
+  || capability_error 'sed JSON field extraction'
+[ "$(printf 'A\nB\n' | awk "$escape_awk")" = 'A\nB' ] || capability_error 'awk JSON text escaping'
+[ "$(printf A | cat)" = A ] || capability_error 'cat byte emission'
+
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+payload=$(cat 2>/dev/null || true)
+sid=$(hp_field "$payload" session_id)
+[ -n "$sid" ] || exit 0
+event=$(hp_field "$payload" hook_event_name)
+
+case "$event" in
+  SessionStart)
+    "$cli" initialize --session-id "$sid" >/dev/null || exit 2
+    ;;
+  UserPromptSubmit)
+    decoded=$(mktemp "${TMPDIR:-/tmp}/spex-session-listen.XXXXXX") || {
+      printf '%s\n' 'session-listen: could not allocate a temporary body file; repair TMPDIR and retry' >&2
+      exit 2
+    }
+    escaped_file="$decoded.escaped"
+    output_file="$decoded.output"
+    if ! : >"$escaped_file" || ! : >"$output_file"; then
+      rm -f "$decoded"
+      rm -f "$escaped_file" "$output_file"
+      printf '%s\n' 'session-listen: could not prepare temporary delivery files; repair TMPDIR and retry' >&2
+      exit 2
+    fi
+    cleanup() { rm -f "$decoded" "$escaped_file" "$output_file"; }
+    trap cleanup EXIT
+    raw=$("$cli" dequeue --session-id "$sid") || exit 2
+    [ "$raw" = 'null' ] && exit 0
+    body64=$(printf '%s' "$raw" | sed -n "$body64_sed")
+    message_id=$(printf '%s' "$raw" | sed -n 's/.*"messageId":"\([^"]*\)".*/\1/p')
+    [ -n "$body64" ] || {
+      printf '%s\n' 'session-listen: spex-session dequeue returned invalid JSON (missing bodyBase64)' >&2
+      exit 2
+    }
+    if ! printf '%s' "$body64" | base64 -d >"$decoded" 2>/dev/null; then
+      printf '%s\n' 'session-listen: spex-session dequeue returned invalid bodyBase64' >&2
+      exit 2
+    fi
+    if ! iconv -f UTF-8 -t UTF-8 "$decoded" >/dev/null 2>/dev/null; then
+      printf 'session-listen: refusing non-UTF-8 body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if od -An -v -tx1 "$decoded" | grep -Eq "$control_pattern"; then
+      printf 'session-listen: refusing control-byte body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if ! awk "$escape_awk" "$decoded" >"$escaped_file"; then
+      printf 'session-listen: could not encode body for harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if [ -s "$decoded" ] && [ ! -s "$escaped_file" ]; then
+      printf 'session-listen: non-empty body encoded to empty additionalContext; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    last_byte=$(tail -c 1 "$decoded" | od -An -tx1 | tr -d '[:space:]')
+    if ! {
+      printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"'
+      cat "$escaped_file"
+      [ "$last_byte" = 0a ] && printf '\\n'
+      printf '"}}\n'
+    } >"$output_file"; then
+      printf 'session-listen: could not assemble harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    if ! cat "$output_file"; then
+      printf 'session-listen: could not emit harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
+      exit 2
+    fi
+    ;;
+esac

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/session-listen/spec.md

@@ -0,0 +1,36 @@
+---
+title: session-listen
+surface: hook
+status: active
+hue: 280
+events:
+- SessionStart
+- UserPromptSubmit
+order: 20
+block: true
+---
+The backend-free self-launch message loop. On `SessionStart`, it initializes the harness's native session id in the
+adopter protocol database; initialization is idempotent and creates no governed lifecycle record. On each
+`UserPromptSubmit`, it performs exactly one at-most-once `spex-session dequeue` for that same native id. A message
+body is decoded and emitted as the harness's `hookSpecificOutput.additionalContext` JSON, so the harness input seam
+receives it without a resident process or wake-hint dependency. An empty queue is a successful no-op and emits no
+stdout. The hook never derives a database path: the adopter CLI owns path resolution and locality checks.
+
+Every external delivery tool and each non-default operation it supplies is proven with a fixed result vector before
+`dequeue`, so a binary that exists but lacks or misimplements the required flag cannot consume a message. In
+particular, `base64 -d` must decode `QQ==` to exactly the one byte `0x41`; checking only its exit status would admit a
+shim that merely copies input. `-d` is used because GNU base64 on Linux and base64 on both fleet Macs running macOS
+15.6.1 were measured to decode that vector correctly; this is an observed common capability, not a platform legend.
+The opaque body
+is decoded to a temporary file, validated as UTF-8, and rejected loudly (with its `messageId` and original
+`bodyBase64`) when it contains NUL or other JSON-hostile control bytes. Clean text is escaped with the existing awk
+toolchain without command substitution, preserving embedded and trailing newlines; a non-empty body can never become
+an empty additionalContext success.
+
+The CLI is resolved at runtime through one explicit seam: a non-empty `SPEX_SESSION_CLI` wins, otherwise PATH is
+searched for `spex-session`. If either protocol database environment variable is configured and no CLI can be
+resolved, the hook fails loudly with an installation or `SPEX_SESSION_CLI` repair entrypoint. With neither database
+variable configured, the project has not adopted this capability, so the hook exits silently without trying another
+delivery path. Only these two events are bound: startup establishes the address, and prompt submission is the natural
+harness input seam; a configured-but-broken adopter is a blocking hook failure so dispatch cannot hide it. There is no
+daemon, polling, retry loop, observer, governed record, or compatibility path.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/spec.md

@@ -10,6 +10,8 @@ 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.
+Put raw file evidence in a persistent directory outside the product repository by default, then run
+`spex session files ls` before review and repair or retract every `INVALID` handoff.
 
 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.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/stop-gate/spec.md

@@ -18,6 +18,6 @@ The block text is where the declaration ritual is taught, so it is written to be
 
 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.
+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. The forced-continuation fallback writes `asking` through `spex internal session-state --session <id>` — the canonical writer, with no delivery or build side effects — passing the id explicitly since there is no worktree file to read it from. Porcelain declarations remain agent-facing; the hook never invokes them to repair its own stop.
 
 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/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -11,28 +11,20 @@
 #                                          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).
+# @@@ governed gate - the session id comes from the payload. 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. Lifecycle status/proposal come from the canonical session application through one
+# CLI read; this shell never treats runtime.json as a second lifecycle database.
 . "${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)
+# non-governed (or no record) → silently let the stop through. THIS is the self-launch fix. The CLI response
+# is governed<TAB>status<TAB>proposal; status/proposal are canonical, while governed is identity metadata.
+hook_state=$($S internal session-hook-state --session "$sid" 2>/dev/null) || exit 0
+IFS=$'\t' read -r governed status proposal <<< "$hook_state"
+[ "$governed" = 1 ] || exit 0
 
 # 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 —
@@ -91,7 +83,10 @@ if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$propos
     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
+    # The hook is a thin boundary.  Do not call the porcelain declaration here: it may trigger
+    # delivery/build work and can remain running after the harness has already accepted the stop.
+    # The internal writer is the same canonical lifecycle path, with no dispatch side effects.
+    $S internal session-state asking --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
@@ -106,13 +101,15 @@ fi
 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
+  # Keep this fallback inside the hook/CLI boundary.  The porcelain `session ask` command can wait on
+  # delivery and workspace builds; a stop hook must settle the canonical state independently of those paths.
+  $S internal session-state asking --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
+# full menu each time is pure token noise). The once-sentinel is a plain file beside runtime.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

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/skills/merge/spec.md

@@ -0,0 +1,33 @@
+---
+title: merge
+surface: skill, command
+status: active
+hue: 130
+desc: Land this session's completed branch into the repository's source-of-truth branch as one verified no-ff merge, preserve unrelated dirty work, push it, and settle the session honestly. Use when the user says /merge, asks to merge or land this session, or when a supervisor dispatches a merge.
+kind: mutating
+---
+# merge
+
+Land the current SpexCode session's branch; do not dispatch another merge request back to yourself.
+
+1. Inspect the current session, branch, worktree, source-of-truth checkout, and live Git status. Treat every
+   pre-existing dirty or untracked path as user-owned. Record its exact status and diff fingerprint; never
+   discard it, fold it into your commit, or hide it behind an unverified stash.
+2. Commit this session's intended spec and code first. In this worktree, merge the latest source-of-truth
+   head into the session branch. Resolve conflicts here, then rerun the focused proof, build, `spex spec lint`,
+   and `spex eval lint --changed` required by the changed behavior.
+3. Immediately before landing, verify
+   `git merge-base --is-ancestor <source-head> <session-head>`. If it fails, sync again. A clean textual merge
+   is not product proof.
+4. In the source-of-truth checkout, make one `--no-ff` merge of the already-synced session tip. Do not resolve
+   conflicts there. If unrelated dirty work prevents the merge, preserve it byte-for-byte and report the exact
+   overlap rather than forcing, resetting, or committing it.
+5. Verify the source checkout has no `MERGE_HEAD`, the session tip is its ancestor, unrelated dirty
+   fingerprints are unchanged, and the post-merge gates pass. Push the source-of-truth branch only after
+   those checks.
+6. Stop test-owned processes and publish any evidence a human must inspect. If the work is fully landed and
+   no decision remains, run `spex session done --propose close` as the final action. Never close your own
+   session directly. If a real decision or external wake-up remains, declare the truthful alternative instead.
+
+`spex session merge <SEL>` is the supervisor-facing dispatcher that sends this workflow to another session.
+Inside the target session, execute the workflow above; do not call `spex session merge .` recursively.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/skills/spec.md

@@ -11,9 +11,5 @@ where an agent invokes them on demand, each carrying `surface: skill`. Grouping
 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.
+This node is a **shelf, not a surface**. Its routing and relocation invariant is owned once by
+[[.plugins]]'s shelf invariant; this node only describes skill-specific materialization and invocation.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/spec.md

@@ -21,3 +21,10 @@ 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.
+
+## shelf invariant
+
+Grouping shelves (`[[commands]]`, `[[skills]]`, `[[review]]`, and `[[prompts]]`) are presentation parents, not
+surfaces. Discovery is recursive and field-driven, so moving a resident under a shelf changes neither its
+identity nor the surfaces gathered from its frontmatter. Each shelf therefore states only its surface-specific
+purpose; it must not copy this routing invariant.

package/node_modules/@spexcode/spec-core/dist/anchors.d.ts

@@ -9,8 +9,8 @@ export type Unit = {
 export type Extractor = {
     id: string;
     claims(ext: string): boolean;
-    ready(): true | string;
-    extract(content: string, filename: string): Unit[];
+    ready(): true | string | Promise<true | string>;
+    extract(content: string, filename: string): Unit[] | Promise<Unit[]>;
     memoKey: (filename: string) => string;
 };
 export type CodeEntry = {
@@ -56,6 +56,16 @@ export type LangSpec = {
 export declare function heuristicExtractor(spec: LangSpec): Extractor;
 export declare const JS_LANG_R5B: LangSpec;
 export declare const PYTHON_LANG: LangSpec;
+type TreeSitterNode = any;
+export type TreeSitterLanguageRow = {
+    id: string;
+    extensions: string[];
+    grammar: string;
+    schema: string;
+    units(root: TreeSitterNode): Unit[];
+};
+export declare const TREE_SITTER_ROWS: TreeSitterLanguageRow[];
+export declare function treeSitterExtractor(row: TreeSitterLanguageRow): Extractor;
 export declare function extractors(root: string): Extractor[];
 export declare function extractorFor(regs: Extractor[], ext: string): Extractor | null;
 export declare const extOf: (path: string) => string;
@@ -92,3 +102,4 @@ export type AnchorHitQuery = {
 export declare function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]>;
 export declare function anchorHitExists(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<boolean[]>;
 export declare function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]>;
+export {};