spexcode 0.4.1 → 0.4.3

package/spec-cli/templates/spec/project/.plugins/core/spec-of-file/spec.md

@@ -10,6 +10,6 @@ block: false
 ---
 A non-blocking per-edit annotation. The first time a session edits a given file, it names the spec node(s) that GOVERN that file — and, when a file is over-owned, flags that it is doing too much and points at the split — so the contract is in view at the very moment of the edit, not only later at commit or drift time.
 
-It never renders a verdict: it only adds context, so it can inform without interrupting. It is deduplicated once per file via a session ledger, so a fifty-edit refactor annotates each file once rather than on every write — the discipline that keeps a pervasive signal from decaying into the noise it is meant to cure. It speaks only when there is something to say: a sanely-owned file draws silence, an over-owned or uncovered one draws the pointer.
+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.

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

@@ -6,7 +6,7 @@ hue: 200
 desc: A config plugin — the minimal spec-discipline contract folded into every launched agent.
 code:
 ---
-The CLI speaks ONE grammar: `spex <noun> <verb> [object] [flags]`. Six nouns — `spec` (the governance graph), `session` (the worktree state machine), `eval` (the measurement system), `issue` (concern threads), `remark` (resolvable pins), `evidence` (content-addressed bytes) — plus a few bare project verbs (`graph` · `init` · `materialize` · `doctor` · `serve` · `uninstall`) whose object is always this project. The verb is always the token right after its noun; a bare noun prints its drawer's help; a `--help` probe is always safe (it prints and exits before the verb runs). `SEL` = session id | unique id-prefix | node id | branch; `.` as a node argument = the node this worktree works on. When unsure of a spelling, ask the tool — `spex help`, `spex help <command>` — never guess from memory: removed spellings only report their replacement and exit.
+The CLI speaks ONE grammar: `spex <noun> <verb> [object] [flags]`. Six nouns — `spec` (the governance graph), `session` (the worktree state machine), `eval` (the measurement system), `issue` (concern threads), `remark` (resolvable pins), `evidence` (content-addressed bytes) — plus a few bare project verbs (`graph` · `init` · `materialize` · `doctor` · `serve` · `uninstall`) whose object is always this project. The verb is always the token right after its noun; a bare noun prints its drawer's help; a `--help` probe is always safe (it prints and exits before the verb runs). `SEL` = session id | unique id-prefix | node id | branch; inside a session worktree, `.` as a session selector = that worktree's own session, while `.` as a node argument = the node this worktree works on. When unsure of a spelling, ask the tool — `spex help`, `spex help <command>` — never guess from memory: removed spellings only report their replacement and exit.
 
 Four disciplines, non-negotiable:
 
@@ -16,6 +16,6 @@ Four disciplines, non-negotiable:
 
 3. THE BODY IS A LIVING CURRENT-STATE DOCUMENT. It states the node's PRESENT intent and is rewritten in place. Never accrete a "## vN" changelog heading, and never add current-state or verdict sections — version history is git's job, not the body's.
 
-4. KEEP THE LOSS SIGNAL HONEST for what you changed — eval readings are the signal the optimizer reads, so a gap is a blind spot. Changed a node that carries a `eval.md`? Re-measure it: run its scenario, compare to the expected, and file the result with `spex eval add <node>`. Made an obvious frontend change to a node with NO `eval.md`? Give it one — a scenario (description + expected) — so its loss can be measured. A frontend scenario is measured through the **actual running product** — drive a real browser, read the real DOM and capture a screenshot (or video), never reason about the code — and that real observation is filed as the reading, not left as an ad-hoc check you ran but never recorded. `spex eval lint --changed` shows the gaps in exactly the nodes you touched.
+4. KEEP THE LOSS SIGNAL HONEST for what you changed — eval readings are the signal the optimizer reads, so a gap is a blind spot. Changed a node that carries a `eval.md`? Re-measure it: run its scenario, compare to the expected, and file the result with `spex eval add <node>`. Match the evidence to the behaviour: a DYNAMIC scenario — anything that moves or is timed (terminal scroll/redraw, an animation or transition, media playback, a multi-step interaction flow) — records a video of the run and files it with `--video`; a STATIC end state screenshots with `--image`; a backend/CLI scenario files its transcript with `--result`. A still of a moving thing proves the wrong thing. File the reading only AFTER the change it measures is committed — a reading's `codeSha` anchors to HEAD at filing time, so verify on the working tree, commit the verified tree, then file; a dirty-tree filing names a commit that lacks your change. Made an obvious frontend change to a node with NO `eval.md`? Give it one — a scenario (description + expected) — so its loss can be measured. `spex eval lint --changed` shows the gaps in exactly the nodes you touched.
 
 Don't reverse-engineer the file formats: `spex guide spec` and `spex guide eval` print the full spec.md and scenario schema on demand. This prompt is the clue; that manual carries the detail.

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

@@ -12,6 +12,12 @@ The blocking stop gate, with two jobs, each holding a hard loop-break so it neve
 
 The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand.
 
-The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop blocks once to make the agent pick the true state; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end. The full block text (choices, each with its application condition, plus the discipline of declaring as the turn's LAST call — any later tool call re-flips the record to active) prints once per session, marked by a sentinel file beside the session record; later undeclared stops get a one-line reminder that stays self-explanatory — menu, declare-last, and the `spex help session` entry that recovers the full conditions.
+The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop emits `{"decision":"block"}` and the dispatcher exits 2 so the harness actually interrupts the stop and shows the reason; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end.
+
+The block text is where the declaration ritual is taught, so it is written to be read at two depths. The FULL teaching text prints once per session: it names the PATH-independent CLI once as a shared prefix, lists the five choices as a compact menu each with its application condition (park policed hardest — a false park is the most damaging mislabel), and ends with the ordering discipline: declare LAST, then stop — a declaration followed by more tool calls honestly re-flips the record to active ([[mark-active]], by design), so making the declaration the turn's final call is what eliminates the park→block→re-park loop at its source. Every later undeclared stop in the same session gets a ONE-LINE version instead (a heavy session hits the gate 15-20 times a night; re-printing the full menu is token noise). The once-sentinel is a plain file beside the session record in the global store — the same per-session-sentinel mechanism as the CLI's note-truncation notice, never a second scheme. The terse line stays self-explanatory: it carries the command menu, the declare-LAST reminder, and the `spex help session` recovery entry, so an agent that never saw the full text (a compacted context) recovers every choice's condition from the entry rather than from memory — the whole full-to-terse information gap is closable from the line itself.
+
+The clean-done eval nudge is advisory only and must never corrupt the Stop hook protocol. Claude-family hooks can receive it as `hookSpecificOutput.additionalContext`; Codex Stop allows are silent because Codex treats unsupported non-block stdout as invalid hook JSON. Blocking decisions stay shared across harnesses through `{"decision":"block"}` plus the dispatcher’s Codex stderr bridge.
+
+Both gates act ONLY on a GOVERNED (dashboard-launched) session: the gate resolves the session's record in the global store from the payload's `session_id`, and on a non-governed (user-self-launched) record — or none — it exits 0 SILENTLY. A self-launched agent has no board to feed, so the declare-demand must never misfire on it. Its own state writes go through `spex session … --session <id>`, passing the id explicitly since there is no worktree file to read it from.
 
 It is the enforcement edge of [[core]]: nothing leaves a session except as committed work under a truthful declaration. The freshness it reads is set by [[mark-active]].

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

@@ -3,7 +3,7 @@ title: forge-link
 surface: system
 status: active
 hue: 280
-desc: A config plugin — agents link an issue they open to the spec node it serves via a `Spec: <id>` body line.
+desc: A config plugin — agents link an issue or change request opened through the resolved forge to the spec node it serves via one `Spec: <id>` body line.
 code:
 ---
-When you open a GitHub issue, link it to the spec node(s) it serves by adding a line to the issue **body**: `Spec: <node-id>` (comma-separate several). The id is the node's **leaf** name — the folder under `.spec/…/<id>/spec.md`, e.g. `sessions`, never the slash-path. An unrecognized id silently links nothing, so use a real node id (`spex graph --json` lists them). A pull request needs no marker: opening it from your `node/<id>` branch links it for free.
+When you open an issue or change request through the repository's resolved forge, link it to the spec node(s) it serves by adding one line to its **body**: `Spec: <node-id>` (comma-separate several). The id is the node's **leaf** name — the folder under `.spec/…/<id>/spec.md`, e.g. `sessions`, never the slash-path. An unrecognized id silently links nothing, so use a real node id (`spex graph --json` lists them). This is the one linking marker on every forge.

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

@@ -3,16 +3,16 @@ title: reproduce-before-fix
 surface: system
 status: active
 hue: 140
-desc: A config plugin — a bug fix must first REPRODUCE the failure as a failing eval, then fix, then file the passing eval. The fail→pass pair on one scenario is the fix's proof (the A/B).
+desc: A config plugin — a bug fix must first REPRODUCE the failure as a failing eval, then fix, verify, commit, and file the passing eval. The fail→pass pair on one scenario is the fix's proof (the A/B).
 code:
 ---
 ## Reproduce before you fix — the fix's proof is a fail→pass pair
 
 If your task is to FIX A BUG, reproduce it *first*, as a measurement — before you touch the fix. A claim that something is broken is worth nothing until the loss signal shows it broken; a claim that you fixed it is worth nothing until the same signal shows it passing. So a bug fix is bracketed by two readings of ONE scenario:
 
-- **A — reproduce (fail).** Find the eval scenario whose expected the bug violates (if none fits, ADD one to the node's `eval.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex eval add <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
-- **B — fix, then re-measure (pass).** Make the code honor the spec, run the SAME scenario again, and file the passing reading with evidence of the corrected behaviour: `spex eval add <node> --scenario <s> --pass`.
+- **A — reproduce (fail).** Find the eval-core scenario whose expected the bug violates (if none fits, ADD one to the node's `eval.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex eval add <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
+- **B — fix, verify, commit, then file (pass).** Four moves, in order: make the code honor the spec; run the SAME scenario against your **working tree** until it actually passes — confidence is earned here, before any commit; **commit** the verified tree; only then file the passing reading, `spex eval add <node> --scenario <s> --pass`, so its `codeSha` names the very commit you measured (the sidecar append lands last, on top of it). Confidence and anchoring are two different acts: you test the uncommitted tree, but the reading's sha anchor can only land after the commit — this is NOT "commit first, then test" (blind commits with routine rollbacks are bad git). A git sha names only a commit and an uncommitted change has none, so a reading filed from a dirty tree is born mis-anchored — its `codeSha` is a HEAD that does not contain the change it claims to measure — and freshness later marking it stale is the mis-anchor being correctly exposed, not an engine bug. (A needs no such care: it measures the bug on the old, already-committed HEAD, so its anchor is honest as-is.)
 
-The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. eval keeps per-scenario reading history, so the pair is durable and navigable end to end.
+The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. eval already keeps per-scenario reading history, so the pair is durable and navigable end to end: the dashboard annotator flips between A (fail) and B (pass), and a trunk delivery (deliver-port) carries that pair as the evidence the fix is real. Don't skip A because the fix looks obvious — an obvious fix with no reproduced failure leaves the loss signal blind to exactly the regression you just closed.
 
-Don't skip A because the fix looks obvious — an obvious fix with no reproduced failure leaves the loss signal blind to exactly the regression you just closed. This does not apply to building new intent (there is no prior failure to reproduce) — it is the discipline for **repair**: keep the loss signal honest across a bug's whole lifecycle, not just at the end.
+This does not apply to building new intent (there is no prior failure to reproduce) — it is the discipline for **repair**: keep the loss signal honest across a bug's whole lifecycle, not just at the end.

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

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

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

@@ -3,72 +3,60 @@ title: distill
 surface: skill, command
 status: active
 hue: 210
-desc: Use when the human wants to inherit a past or dead session's knowledge and work — "distill session X / 继承那个 session 的经验 / 接手它的工作 / 把之前 session 的东西捞回来 / harvest, salvage a finished session". Given a session id, read its transcript from disk (NEVER resume or re-prompt it — its cache is cold and a re-prime is expensive), distill goal · decisions · traps · next steps into the current session, and if its worktree/branch never merged, carry the work over and retire the resources.
+desc: Use when the user wants to inherit a finished, dead, or abandoned session — "distill session X / 继承那个 session 的经验 / 接手它的工作 / harvest or salvage a session". Given a SpexCode session id, harness thread id, or transcript path, read it without resuming, extract decisions, traps, and next actions, salvage unmerged work, retire only resources proven safe to remove, then rename the inheriting session to mark the handoff.
 ---
 
 # distill
 
-Inherit a finished (or dead) session's **mind and desk** without waking it — mind = its transcript on disk,
-desk = its worktree/branch. The one iron rule: **never resume, reopen, send to, or otherwise re-prompt the
-old session** (cold cache: any turn pays a full re-prime). Everything below is read-only files and plain git.
+Inherit a finished session's **mind and desk** without waking it: mind is its transcript; desk is its
+worktree and branch. **Never resume, reopen, send to, or otherwise re-prompt the old session.** Read files
+and git state only until its work has landed.
 
-## 1 · resolve the session
+## Resolve and digest
 
-Input: a session id — SpexCode's, a bare harness id (claude / codex thread), or a transcript `.jsonl` path.
+Accept a SpexCode session id, a Claude/Codex thread id, or a transcript `.jsonl` path.
 
-- **SpexCode session** (first choice — the join is first-class): its record is
-  `~/.spexcode/projects/*/sessions/<id>/session.json` — glob for the id, prefix ok. Take `worktree_path`,
-  `branch`, `harness`, `harness_session_id`, `status`, `title`; the originating goal is
-  `spex session show <id>` (the record's prompt). For a claude-harness session the transcript id IS the SpexCode session id;
-  for codex it is `harness_session_id`.
-- **Any other session**: treat the arg as the harness's own id. The transcript carries `cwd` (and, unless
-  the worktree was detached, a branch) — the digest header surfaces them; that is your join to its desk.
+- For a SpexCode id, find `~/.spexcode/projects/*/sessions/<id>/session.json` (a unique prefix is enough).
+  Keep its prompt, `worktree_path`, `branch`, `harness`, and `harness_session_id`; Claude uses the session
+  id as its transcript id, while Codex uses `harness_session_id`.
+- Otherwise pass the harness id or transcript path directly. The digest header supplies its `cwd` and branch
+  when recorded; those locate the desk even when it belongs to another repository.
 
-## 2 · digest the transcript — mechanical first, model second
+From the repository root run the plugin's co-located digest:
 
-`node .spec/<root>/.plugins/distill/digest.mjs <id-or-path>` locates the transcript (claude:
-`$CLAUDE_CONFIG_DIR` and every `~/.claude*` config dir → `projects/*/<id>.jsonl`; codex: `$CODEX_HOME` or
-`~/.codex` → `sessions/**/rollout-*<id>.jsonl`) and prints a compact digest: the human's prompts in full,
-the agent's own text, tool calls as one-liners, error results, and a footer with the files it edited and
-the raw transcript path. It exits loud when nothing is found — do not fall back to resuming the session.
+`node .spec/*/.plugins/skills/distill/digest.mjs <id-or-path>`
 
-Read the digest yourself when small; big (>~100 KB) → a subagent returns only the distillation below, so
-the inheritance never floods your own context. Its ⚠ error lines and footer are step 3's trap material.
+It searches the harness's normal local transcript stores and prints human prompts, agent text, concise tool
+calls, errors, metadata, edited files, and the raw path. A miss fails loudly; never recover by waking the old
+session. For output above about 100 KB, have a subagent return only the distillation below.
 
-## 3 · distill — forward-looking, not narrative
+## Distill forward
 
-Completed work is git's job to remember; do not re-narrate it — and never paste raw transcript. State in
-your reply, and work from, what the transcript knows that git does not:
+Do not paste the transcript or retell changes git already records. Preserve what git does not:
 
-- **Goal & landing** — what it set out to do, and where it actually stopped (merged? proposal pending?
-  abandoned mid-flight?).
-- **Decisions & why** — the direction that was settled, including options weighed and rejected.
-- **Traps** — failures, dead ends, gotchas, and every correction the human made. These are the
-  highest-value lines in the whole transcript.
-- **Unfinished / next actions** — what it would have done next.
-- **Pointers** — files edited, spec nodes touched, and the raw transcript path itself, so later questions
-  drill into the source instead of inheriting everything up front.
+- goal, actual stopping point, and whether anything landed;
+- decisions and rejected alternatives, with reasons;
+- failures, dead ends, and user corrections;
+- unfinished work and next actions;
+- edited files, relevant spec nodes, and the raw transcript path.
 
-## 4 · salvage the desk
+## Salvage, then retire
 
-The SpexCode record names the worktree/branch; otherwise the digest's `cwd` may be a linked worktree
-(`git -C <cwd> rev-parse --git-common-dir`). Salvage inside that repo — it need not be the one you sit in.
-Cross-check the digest's files-edited footer against that worktree: a manager-style session's edits often
-live OUTSIDE it (main-checkout config, other repos) — those need a by-hand look, not the recipe below.
+Use the record or digest to inspect the old repository's worktree, branch, merge base, commits, dirty files,
+and untracked files. Cross-check the digest's edited-file list because some work may live outside that
+worktree. Distinguish an already-merged branch from a branch equal to its merge base, which never committed.
 
-- **Already merged** (`git merge-base --is-ancestor <branch> <trunk>`) → nothing to salvage; note it and
-  go to cleanup. A tip that EQUALS the merge-base carried no commits — say "never committed", not "merged".
-- **Unmerged commits** → carry them onto your current branch: `git cherry-pick <base>..<branch>` (keeps
-  authorship and `Session:` trailers); fall back to applying `git diff <base> <branch>` when the history
-  is too messy to replay.
-- **Uncommitted changes** in the old worktree → `git -C <wt> status --porcelain`; apply its diff to your
-  tree and copy untracked files over. Commit the salvage in your own tree, naming the origin session in
-  the message.
+Carry unmerged commits onto the current branch with `git cherry-pick <base>..<branch>`; if replay is
+unsuitable, apply the branch diff. Apply dirty changes and copy needed untracked files, then commit them
+with the source session named. Keep authorship and `Session:` trailers where possible.
 
-## 5 · clean up — only after the salvage LANDED
+Only after verifying the salvage is present (or the branch truly merged), retire a SpexCode session with
+`spex session close <id>`, or remove a bare worktree and then its branch. If proof is incomplete, keep the
+resources and report why.
 
-Cleanup discards state — verify the salvaged commits are in your tree (or the branch genuinely merged) first.
+## Rename yourself
 
-- SpexCode session: `spex session close <id>` retires the session and its worktree in one verb.
-- Bare worktree: `git worktree remove <wt>`, + `git branch -D <branch>` once confirmed carried or merged.
-- In doubt, keep the resources and say so — a kept worktree costs disk; a wrong cleanup costs the work.
+Last step: mark the inheritance on the board. If you run as a SpexCode session (inside a session
+worktree), `spex session rename . "<name>"` — `.` selects this worktree's own session. Name what this
+session now carries — the inherited goal going forward, not the old session's id and no `distill:`
+prefix. Outside a SpexCode session there is nothing to rename; skip this step.

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

@@ -2,16 +2,18 @@
 title: skills
 status: active
 hue: 280
-desc: Grouping shelf for the `surface: skill` plugins — the harness skills an agent invokes on demand. A shelf, not a surface — routing stays field-driven.
+desc: Grouping shelf for the `surface: skill` plugins — the harness skills an agent invokes on demand. A shelf, not a surface — routing stays field-driven per surface.
 ---
 # skills
 
 The invocable **skill** plugins live here: leaf plugins that materialize into the harness's skill dir,
 where an agent invokes them on demand, each carrying `surface: skill`. Grouping them keeps `.plugins/`
-legible at a glance — the skill plugins on this shelf, the command presets on `commands/`, the auxiliary
-system contracts on `prompts/`, with `core` a flat child beside them.
+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**: it declares no `surface` field and gathers nothing itself.
-Discovery is recursive and field-driven, so a resident plugs in exactly as it would at the root. A plugin
-that serves both surfaces shelves here by its primary (skill) identity and still gathers as a command
-through its field.
+This node is a **shelf, not a surface** (the [[prompts]] shape): it declares no `surface` field and
+gathers nothing itself. Discovery is recursive and field-driven (surface), so a resident plugs in
+exactly as it would at the root. A plugin that serves BOTH surfaces — [[distill]] is skill and command —
+shelves here by its primary (skill) identity and still gathers as a command through its field. The init
+templates mirror this layout. The shelf stays pure presentation: moving a resident beneath it changes
+neither that plugin's identity nor the surfaces gathered from its frontmatter.

package/spec-cli/templates/spec/project/.plugins/spec.md

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

package/spec-cli/templates/spec/project/spec.md

@@ -12,8 +12,9 @@ made it. This node is the founding spec everything else hangs from — **rewrite
 your own project**, then grow child package/feature nodes beneath it (each its own directory with a
 `spec.md`).
 
-`.plugins/` holds the dev-flow plugins this instance ships — skill-shaped child nodes, each tagged
-with a `surface` field: a `surface: system` node folds into every launched agent's system prompt as
-always-on contract (the seed ships `core`), and a `surface: command` node is a prompt preset the
-new-session dropdown composes over target nodes (the seed ships `tidy`). Add, edit, or
-remove plugins by editing those spec nodes.
+`.plugins/` holds the dev-flow plugins this instance ships — spec-shaped child nodes whose `surface`
+field says how they enter the product. The initialized set includes always-on `system` contracts,
+lifecycle `hook` handlers, new-session `command` presets, and an on-demand `skill`; one plugin may serve
+more than one surface. Grouping shelves carry no surface themselves, and discovery is recursive, so the
+folder layout stays readable without deciding behavior. Add, edit, or remove plugins by editing those
+spec nodes.

package/spec-cli/templates/spexcode.json

@@ -4,8 +4,10 @@
   },
   "sessions": {
     "launchers": {
-      "claude": { "harness": "claude", "cmd": "claude --dangerously-skip-permissions" },
-      "codex": { "harness": "codex", "cmd": "codex --yolo" }
+      "claude": { "harness": "claude", "cmd": "claude" },
+      "codex": { "harness": "codex", "cmd": "codex" },
+      "opencode": { "harness": "opencode", "cmd": "opencode" },
+      "pi": { "harness": "pi", "cmd": "pi" }
     },
     "defaultLauncher": "claude"
   }