spexcode 0.1.0

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

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# @@@ stop-gate - a blocking Stop hook with TWO jobs, each with a HARD loop-break (never blocks more than
+# once on the same cause, never leaks a dishonest stop):
+#   (A) COMMIT GATE — a done/merge proposal (awaiting + merge|nothing) is rejected while the node branch has
+#       uncommitted work or 0 commits ahead of main; the dogfood ritual commits BEFORE proposing. Clean ->
+#       allow; dirty -> block once with the reason, escape on the continuation to `asking` (needs the human).
+#   (B) DECLARE GATE — a session may not stop in an undeclared (`active`) state:
+#         declared (awaiting/parked/error/asking) . allow (the agent reported; nothing to do)
+#         active, first stop  (stop_hook_active false) .. block ONCE — instruct the agent to declare
+#         active, the continuation (stop_hook_active true) auto-declare a safe default (awaiting/nothing if
+#                                          committed, else `asking` — needs the human) and allow. Guaranteed to end.
+# $SPEX is the PATH-independent CLI invocation (abs tsx + cli) injected by settingsArg, so the gate's own
+# auto-default AND the command it shows the agent both work even when `spex` is absent from PATH.
+# @@@ global store + governed gate - state lives in the per-session GLOBAL record session.json (keyed by the
+# harness session_id from the payload, grouped per-project — mirrors spec-cli/src/layout.ts). The gate acts
+# ONLY on a GOVERNED (dashboard-launched) session: a user-self-launched agent has no board to feed, so an
+# undeclared stop is none of our business — we exit 0 SILENTLY (the bug this fixes: the declare-demand
+# misfiring on a self-launched codex/claude). cwd = the session worktree (resolves the project key + the
+# commit-gate's git); state writes go through `$SPEX session … --session <id>` (TS owns the JSON).
+. "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
+S="${SPEX:-spex}"
+input=$(cat 2>/dev/null || true)
+sid=$(hp_session_id "$input"); [ -n "$sid" ] || exit 0
+sdir=$(hp_store_dir "$sid") || exit 0
+rec="$sdir/session.json"
+# non-governed (or no record) → silently let the stop through. THIS is the self-launch fix.
+grep -q '"governed"[[:space:]]*:[[:space:]]*true' "$rec" 2>/dev/null || exit 0
+
+jget() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$rec" 2>/dev/null | head -1; }
+status=$(jget status)
+proposal=$(jget proposal)
+
+# the value of the payload's structured `stop_hook_active` field (true on the hook-forced continuation),
+# read by field name rather than substring-sniffing the JSON blob. ([a-z]* captures true/false portably —
+# BSD sed has no \| alternation.)
+cont=$(printf '%s' "$input" | sed -n 's/.*"stop_hook_active"[[:space:]]*:[[:space:]]*\([a-z]*\).*/\1/p')
+
+# @@@ yatsu advisory - a nudge (never a gate) emitted when a session stops CLEAN-DONE (committed work + a
+# done/awaiting declaration): the agent IS yatsu's evaluator, so a yatsu gap in what it just changed is a
+# blind spot to flag the moment work lands. SCOPED via `spex yatsu scan --changed` to the nodes THIS branch
+# touched — so an agent is never nagged about a score that went stale in a node it never opened (the bug
+# that made three workers ask "is this mine?"). Three gap classes it surfaces: yatsu-drift / yatsu-missing
+# (a node with a yatsu.md whose score is stale / unmeasured) and yatsu-uncovered (a FRONTEND node with no
+# yatsu.md — an obvious UI change carrying no loss signal). Delivered via the Stop hook's additionalContext
+# (NEVER a block decision: a gap is a heads-up, not a wall). FIRES ONCE: the additionalContext itself forces
+# one continuation, so the CALLER guards it on stop_hook_active — re-emitting on the forced re-stop is what
+# looped 31 turns and tripped the Stop-hook block cap. Called only on ALLOW paths, never alongside a block.
+yatsu_advisory() {
+  local out ids n msg esc
+  out=$($S yatsu scan --changed 2>&1)
+  n=$(printf '%s\n' "$out" | grep -cE 'yatsu-(drift|missing|uncovered):')
+  [ "${n:-0}" -gt 0 ] || return 0   # no gap in what you changed (or scan unavailable) -> nothing to nudge
+  ids=$(printf '%s\n' "$out" | sed -n "s/.*yatsu-[a-z]*: '\([^']*\)'.*/\1/p" | awk '!seen[$0]++' | head -6 | paste -sd' ' -)
+  msg="yatsu — the loss signal the optimizer reads — flags ${n} gap(s) in nodes you changed: ${ids}. A node whose score went stale/unmeasured: re-measure it (run the scenario, compare to expected, \`spex yatsu eval <node>\`). A FRONTEND node with no yatsu.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. \`spex yatsu scan --changed\` lists them. (Advisory — fires once, not a gate.)"
+  esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g')
+  printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"%s"}}\n' "$esc"
+}
+
+# @@@ commit gate - a declaration of done/merge (awaiting + proposal merge|nothing) is only honest once the
+# node branch carries the work as COMMITS: the dogfood ritual commits spec+code BEFORE any proposal, yet a
+# dashboard-launched agent kept proposing merge with 0 commits / a dirty tree. So before allowing such a
+# declaration we run the deterministic check (`spex session commit-gate`, which goes through git.ts's git()
+# so the hook's GIT_DIR/GIT_INDEX_FILE can't misdirect repo discovery). Clean -> allow. Dirty/0-ahead ->
+# block ONCE with the specific reason + commit instructions; on the forced continuation (the agent ignored
+# it) escape the loop by downgrading to `asking` (needs the human) with a clear note, so a FALSE "ready to
+# merge" never stands. (A propose-close declaration is exempt — it discards the worktree, so commits are moot.)
+if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$proposal" = nothing ]; }; then
+  if gatemsg=$($S session commit-gate 2>&1); then
+    # nudge ONCE: emit on the natural stop, but STAY SILENT on the forced re-stop the additionalContext
+    # itself causes (stop_hook_active=true). Without this guard the advisory re-fired every clean-done stop
+    # and looped — the bug a prior change DESCRIBED in a comment but never actually implemented at the call.
+    [ "$cont" != true ] && yatsu_advisory
+    exit 0   # work is committed and ahead of main -> the proposal is honest, let it stop.
+  fi
+  if [ "$cont" = true ]; then
+    $S session ask --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
+    exit 0
+  fi
+  esc=$(printf '%s' "$gatemsg" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"Not ready to declare done: %s. The dogfood ritual lands every change as a git commit on your node branch BEFORE you propose. Commit your spec.md + code on this node branch (spec: <id> — <reason>, with a Session: trailer), then re-run %s session done --propose %s."}\n' "$esc" "$S" "$proposal"
+  exit 0
+fi
+
+# any OTHER already-declared state (parked / error / asking / awaiting+close) -> let it stop.
+[ "${status:-active}" != "active" ] && exit 0
+
+if [ "$cont" = true ]; then
+  # the forced continuation also stopped without declaring -> escape the loop, don't block. Keep the commit
+  # gate airtight: default to awaiting/nothing only when the branch is actually committed+ahead; otherwise an
+  # undeclared stop with uncommitted work becomes `asking` (needs the human), never a false awaiting/done.
+  if $S session commit-gate >/dev/null 2>&1; then
+    $S session state awaiting --session "$sid" --propose nothing --note "auto: stopped without declaring" >/dev/null 2>&1 || true
+    # NOTE: no yatsu nudge on the auto-declare path. It only runs on the forced continuation (cont=true),
+    # where a guarded advisory could never fire anyway, and an unguarded one was a second loop vector (a
+    # mark-active tool call could re-enter this branch). The clean-done path above is the single nudge site.
+  else
+    $S session ask --session "$sid" --note "auto: stopped without declaring and with uncommitted work — commit your spec+code on the node branch, then declare" >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
+
+# first stop in an undeclared state -> nudge exactly once with PATH-independent commands. The reason
+# EMPHASIZES that each state is a CLAIM others act on (not a box to tick to end the turn) and gives the
+# precise APPLICATION CONDITION for each — so the agent picks the TRUE one. park is policed hardest because
+# a false park (no real background task) reads on the board as "fine, self-resuming" when the agent actually
+# needs the human, which is the most damaging mislabel.
+printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now, by its condition, then stop. %s session done --propose merge = your spec+code are COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done). %s session done --propose nothing = committed, but you are NOT proposing a merge; paused for the human to look. %s session park --note <what-you-await> = use ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask. park claims leave-me-alone-I-self-resume; do not use it as a default to clear this gate. %s session done --propose close = you propose discarding this worktree. %s session ask --note <your-question> = you need the human: a real question, OR you are simply stopped awaiting their direction; you resume only when they reply. Choose by what is true."}\n' "$S" "$S" "$S" "$S" "$S"
+exit 0

package/templates/spec/project/.config/extract/spec.md

@@ -0,0 +1,60 @@
+---
+title: extract
+surface: slash
+status: active
+hue: 30
+desc: Reverse-engineer a faithful spec tree out of existing code — responsibility nodes at contract altitude, intent never fabricated.
+kind: mutating
+---
+Reverse-engineer a spec tree for the target source area(s) below — code that has no specs yet. Aim for a
+tree where every governed file is claimed and `spex lint` is clean, with 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 (e.g. model-config + selection + auth +
+  provider-compat → a *model* domain), and recurse until every level reads as a handful of siblings, not a
+  flat wall. Fold cross-cutting substrate (design system, dialogs, i18n, utilities, platform glue) under one
+  *foundation* node. A sub-domain node claims the cluster's barrel/wiring files (so it isn't pure-prose);
+  equally, 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 `yatsu.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 and the
+**expected** zero-loss result. Frontend scenarios are measured by looking (YATU) — a screenshot filed with
+`spex yatsu eval <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex yatsu scan` to
+list the frontend nodes still uncovered.
+
+**Extract incrementally — don't plan the whole tree before writing.** For a large area (hundreds of files),
+don't enumerate the whole partition up front or script a generator to emit it at once — that 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 holding 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>`) with a `Session:` trailer, and
+run `spex lint` after each: it must reach 0 errors, 0 coverage warnings, 0 altitude warnings.

package/templates/spec/project/.config/forge-link/spec.md

@@ -0,0 +1,9 @@
+---
+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.
+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 board` lists them). A pull request needs no marker: opening it from your `node/<id>` branch links it for free.

package/templates/spec/project/.config/memory-hygiene/spec.md

@@ -0,0 +1,15 @@
+---
+title: memory-hygiene
+surface: system
+status: active
+hue: 200
+desc: A config plugin — keep the project-keyed agent memory free of session- and role-specific facts, so N agents in one folder never inherit a confused identity.
+code:
+---
+## Memory hygiene — keep the shared store identity-clean
+
+SpexCode's agent memory is keyed by the **main project**, so every agent running under this project — the main checkout AND every worktree — reads the **same** memory. That makes session- and role-specific facts toxic: one agent's note silently becomes every agent's belief. So, when deciding whether to record a memory:
+
+- **Never record session-specific content** — this task, this worktree's transient state, a one-off decision, who you're talking to right now. Memory is ONLY for durable, cross-session project/user facts.
+- **On a non-main worktree** (you are on a `node/<id>` branch, not the main checkout): do **not** record any memory for this session at all. Its work is transient and will merge or close; a durable lesson is recorded later, from main, once it has actually landed.
+- **Even on main, never record a transient ROLE or IDENTITY** — "I am the supervisor", "I'm the coordinator", "I'm the agent doing X". These are per-launch facts, not durable ones. Recording one makes the next launched agent read *itself* as that role, and several agents in one folder dissolve into mutual-supervision confusion (everyone thinks they're the supervisor, everyone watches everyone).

package/templates/spec/project/.config/regroup/spec.md

@@ -0,0 +1,25 @@
+---
+title: regroup
+surface: slash
+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 for **breadth** has too many direct children: a flat fan-out the eye can't hold. Breadth is altitude's structural twin — the same comprehensibility limit, rotated from a body's depth onto the tree's width. Find the **natural seams** in the fan-out and lift the children onto them, *only where a real group exists*. Getting under the 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 pass altitude lint itself) — 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 `yatsu.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 lint` and confirm breadth is resolved with no new errors. Uncommitted `git mv`s churn the drift count transiently — committing settles it; don't chase it.

package/templates/spec/project/.config/scenario/spec.md

@@ -0,0 +1,32 @@
+---
+title: scenario
+surface: slash
+status: active
+hue: 160
+kind: mutating
+desc: Enter Scenario mode — author, refine, and re-measure a node's yatsu.md loss scenarios as first-class, file-scoped units.
+---
+You are in **Scenario mode** — a focused flow for managing a node's yatsu.md **scenarios** as first-class
+units of loss. A scenario is one declared way to measure a node's loss: a `name`, a `description` of what to
+check, the `expected` result that is zero loss, and optionally a `test` (a co-located runnable file) and
+`code` (the concrete repo files THIS scenario depends on — its own freshness axis). Your job is to **edit,
+create, and manage** these scenarios for the target node(s) — nothing else; do not write feature code.
+
+Work through the real `spex` surface, never by reverse-engineering files:
+
+1. **Read the schema and the node.** Run `spex guide yatsu` for the exact yatsu.md format. Read the target
+   node's `spec.md` (its present intent) and its governed `code:` files, plus its existing `yatsu.md` if any.
+   A scenario must measure what the SPEC promises, through the real product surface (YATU — You As The User),
+   not an internal helper chosen to make the proof easy.
+2. **Author or refine scenarios.** For a node with no yatsu.md, create one with at least one scenario. For an
+   existing one, sharpen weak scenarios and add missing coverage. Give a scenario its own `code:` list when it
+   depends on a specific subset of the node's files, so it goes stale independently of its siblings. Keep
+   names unique and the schema valid — `spex yatsu scan <node>` reports violations (`yatsu-schema`), and the
+   pre-commit gate rejects a malformed file, so fix every finding before committing.
+3. **Re-measure when the change warrants it.** If you changed a scenario or the code it measures, file a fresh
+   reading: measure through the product, then `spex yatsu eval <node> --scenario <name> (--pass|--fail|--note)
+   [--image <png>|--result <txt>]`. Use `spex yatsu show <node>` to read the timeline.
+4. **Commit spec + yatsu.md together** on the node's branch, then report what scenarios now exist and their
+   satisfaction status. Do not bundle unrelated edits.
+
+The node(s) to manage scenarios for: {{targets}}

package/templates/spec/project/.config/spec.md

@@ -0,0 +1,15 @@
+---
+title: .config
+status: active
+hue: 110
+desc: The instance home — this repo's DIY dev-flow plugins live here as skill-shaped config nodes.
+---
+`.config/` is the **instance** of the config 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) — living as a flat child of `.config/` and carrying a `surface: slash|system` field
+that names where it plugs in.
+
+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 `tidy` and `health`
+(`surface: slash` — prompt presets); add your own by creating a sibling node with a `surface` field.

package/templates/spec/project/.config/supervisor/spec.md

@@ -0,0 +1,8 @@
+---
+title: supervisor
+surface: slash
+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. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into spec-node tasks and dispatch one worker per independent task (`spex new "<task>" --node <id>` — give each ONLY its task), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. Two footguns that bite a fresh supervisor: (1) `spex session new --help` is NOT help — it CREATES a stray session; always dispatch with `spex new`. (2) 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. Report progress as you go and when the goal is complete. Your goal follows:

package/templates/spec/project/.config/tidy/spec.md

@@ -0,0 +1,25 @@
+---
+title: tidy
+surface: slash
+status: active
+hue: 140
+desc: Rewrite a node's body to contract altitude — push mechanics into code comments, keep the contract, without going vague.
+kind: mutating
+---
+Tidy each target spec node so its body reads as **contract**, not implementation — and not vague hand-waving either.
+
+{{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.** It leaves the body and becomes an `@@@title - explanation` comment at the code that owns it (operators, call names, data structures, "added a parameter", step-by-step how-to).
+- **No ⇒ it is contract surface.** Keep it — public names, signatures, return types, invariants, edges/errors, the WHEN → outcome a caller observes.
+
+For each target, in its own commit:
+
+- **Preserve the contract** — never drop a requirement; tidying is rephrasing at the right altitude, not deletion of meaning.
+- **Raise, don't hollow out** — the trap while shortening is going *too thin*: a body so vague a refactor couldn't violate it ("validates input appropriately") is as broken as a mechanics dump. Keep every testable specific; cut only the how.
+- **Cut redundancy and narration** — say each thing once, at the altitude a maintainer needs.
+- **Stay a living document** — rewrite in place; never add `## vN` history (git carries versions).
+
+Commit per node (`spec: <id> — tidy to contract altitude`) with a `Session:` trailer. Run `spex lint` after each — it must stay at 0 errors.

package/templates/spec/project/spec.md

@@ -0,0 +1,19 @@
+---
+title: project
+status: active
+hue: 45
+desc: The root spec node — the founding intent this repo's spec tree hangs from. Rewrite it to your own.
+---
+# project
+
+The root of your spec tree. In SpexCode the spec tree IS ground truth and git is its database: every
+node is a `spec.md` stating present intent, and each version change is attributed to the session that
+made it. This node is the founding spec everything else hangs from — **rewrite this body to describe
+your own project**, then grow child package/feature nodes beneath it (each its own directory with a
+`spec.md`).
+
+`.config/` holds the dev-flow plugins this instance ships — skill-shaped flat 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: slash` node is a prompt preset the
+new-session dropdown composes over target nodes (the seed ships `tidy` and `health`). Add, edit, or
+remove plugins by editing those spec nodes.

package/templates/spexcode.json

@@ -0,0 +1,5 @@
+{
+  "lint": {
+    "governedRoots": ["src"]
+  }
+}