spexcode 0.2.8 → 0.4.0

package/spec-cli/src/specs.ts

@@ -2,6 +2,7 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, basename } from 'node:path'
 import { repoRoot, historyIndex, rowsFor, statsFor, pathsStats, driftIndex, driftFor, fileDiffAt } from './git.js'
+import { parseCodeEntry } from './anchors.js'
 
 // a node is any directory under .spec holding a spec.md; its parent is the nearest ancestor that also holds one.
 const ROOT = repoRoot()
@@ -97,8 +98,8 @@ function walk(dir: string, parent: string | null, acc: Raw[]) {
 // single token — never a '/'-joined path, which would break every `:id` route and fetch that treats an id
 // as one path segment. So the disambiguation separator is '_': like '/' it never occurs inside a dir
 // basename (so the join stays unambiguous), but unlike '/' it is a URL/wikilink/DOM-safe unreserved char,
-// so a collision-qualified id (e.g. `.config_spec-scout`) stays a single token everywhere it is resolved.
-// Exported as the ONE mint every id producer shares: spec-yatsu mints its node ids through this same
+// so a collision-qualified id (e.g. `.plugins_<id>`) stays a single token everywhere it is resolved.
+// Exported as the ONE mint every id producer shares: spec-eval mints its node ids through this same
 // function over this same universe (every spec node), so a colliding leaf carries one canonical id
 // system-wide instead of a second, diverging bare-leaf scheme.
 export function mintIds(segs: string[][]): string[] {
@@ -135,7 +136,7 @@ function raws(): Raw[] {
   return acc
 }
 
-// async twin of walk/raws for the HOT board build ([[board-cache]]): reading each spec.md through
+// async twin of walk/raws for the HOT board build ([[graph-cache]]): reading each spec.md through
 // fs/promises YIELDS the event loop between files, so a build never stalls a `/health` liveness probe the
 // way the sync walk (one ~450ms uninterrupted stretch) did. Same output as raws() — identical push order
 // (pre-order DFS, dir before children) and the same reId — so every caller reads the same nodes; only
@@ -170,14 +171,14 @@ function claimMatcher(file: string): (cf: string) => boolean {
   }
 }
 
-// spec node(s) that GOVERN a file (frontmatter `code:` — source of truth, drives drift/yatsu); reads only
+// spec node(s) that GOVERN a file (frontmatter `code:` — source of truth, drives drift + eval freshness); reads only
 // frontmatter (cheap, no git) so a per-edit hook can call it.
 export function specOwners(file: string): { id: string; desc: string }[] {
   const claims = claimMatcher(file)
-  return raws().filter((r) => list(r.fm.code).some(claims)).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
+  return raws().filter((r) => list(r.fm.code).some((e) => claims(parseCodeEntry(e).path))).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
 }
 
-// spec node(s) that REFERENCE a file (frontmatter `related:` — carries coverage, never drift/yatsu):
+// spec node(s) that REFERENCE a file (frontmatter `related:` — carries coverage, never drift, never eval freshness):
 // [[governed-related]]'s other half, same claim rule, same cheap frontmatter-only read.
 export function specRelated(file: string): { id: string; desc: string }[] {
   const claims = claimMatcher(file)
@@ -211,7 +212,7 @@ export function loadSpecsLite(): SpecLite[] {
 }
 
 // one node's body + parsed parts, filesystem-only (no git). The board omits both to stay lean
-// ([[board-lean]]); the detail view fetches them here when a node opens. null when the id isn't a node.
+// ([[graph-lean]]); the detail view fetches them here when a node opens. null when the id isn't a node.
 export function specContent(id: string): { body: string; parts: ReturnType<typeof parseParts> } | null {
   const r = raws().find((x) => x.id === id)
   return r ? { body: r.body.trim(), parts: parseParts(r.body) } : null
@@ -226,7 +227,11 @@ export async function loadSpecs() {
     // session = the Session: trailer of the node's latest version; frontmatter `session:` is the fallback.
     const fmSession = str(r.fm.session)
     const session = h[0]?.session || (fmSession && fmSession !== 'null' ? fmSession : null)
-    const code = list(r.fm.code)
+    // a code: entry may pin a symbol (`path#fn` — [[code-anchor]]): `code` carries the PATHS (what every
+    // path consumer — drift, claims, eval attribution — expects); the anchors ride separately for lint.
+    const codeEntries = list(r.fm.code).map(parseCodeEntry)
+    const code = codeEntries.map((e) => e.path)
+    const anchors = codeEntries.filter((e): e is { path: string; anchor: string } => e.anchor !== null)
     const related = list(r.fm.related)
     const S = h[0]?.hash || ''
     const driftFiles = code
@@ -234,7 +239,7 @@ export async function loadSpecs() {
       .filter((d) => d.behind > 0)
     const drift = driftFiles.reduce((a, d) => a + d.behind, 0)
     // related drift is the SOFT tier ([[governed-related]]): same ancestry basis, but it stays OUT of
-    // `drift` — it never feeds status, the commit gate, or yatsu. It surfaces only as a lint warn nudge.
+    // `drift` — it never feeds status, the commit gate, or eval freshness. It surfaces only as a lint warn nudge.
     const relatedDriftFiles = related
       .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
       .filter((d) => d.behind > 0)
@@ -250,6 +255,7 @@ export async function loadSpecs() {
       hue: Number(str(r.fm.hue, '210')),
       desc: str(r.fm.desc),
       code,
+      anchors,
       related,
       version: h.length,
       reason: h[0]?.reason || '',
@@ -271,7 +277,7 @@ export async function loadSpecs() {
 export async function specHistory(id: string) {
   const node = raws().find((r) => r.id === id)
   if (!node) return []
-  const codePaths = list(node.fm.code)
+  const codePaths = list(node.fm.code).map((e) => parseCodeEntry(e).path)
   // index (cached) and the code-path walk are independent — run them in parallel, both async git.
   const [idx, cStats] = await Promise.all([historyIndex(ROOT), pathsStats(ROOT, codePaths)])
   const sStats = statsFor(idx, node.relPath)
@@ -292,7 +298,7 @@ export async function specDiffAt(id: string, hash: string) {
   return latestDiff(node.relPath, hash)
 }
 
-// config presets - REFLEXIVE, SKILL-SHAPED preset nodes whose folder IS a skill bundle: `spec.md`'s
+// plugin presets - REFLEXIVE, SKILL-SHAPED preset nodes whose folder IS a skill bundle: `spec.md`'s
 // body is the agent prompt/contract (with a {{targets}} placeholder the launcher fills with the
 // @-referenced nodes), and the SAME folder may co-locate auxiliary files — scripts, assets — that the
 // preset ships for the agent to run deterministically. So each preset reports its folder `dir`
@@ -302,19 +308,19 @@ export async function specDiffAt(id: string, hash: string) {
 // harness lifecycle events the node binds, its deterministic intra-event order, and whether it intends to
 // block (honored only on block-capable events). See loadHookConfig + the hook compiler/dispatcher.
 export type ConfigPreset = { name: string; title: string; desc: string; kind: string; dir: string; files: string[]; body: string; events: string[]; order: number; block: boolean; tools: string[] }
-// field-driven surface - a config plugin is a FLAT direct child of a config root (`<root>/<name>/spec.md`)
-// that carries a `surface: system|command|hook|skill|agent` frontmatter field naming where it plugs in. There are no
+// field-driven surface - a plugin is a spec node at ANY depth under a plugin root that carries a
+// `surface: system|command|hook|skill|agent` frontmatter field naming where it plugs in. There are no
 // `command/`/`system/`/`hook/`/`skill/`/`agent/` bucket dirs (those were graph-invisible grouping dirs with no spec.md, so
 // the spec graph skipped them — path != graph); the surface is a FIELD on the node, so the plugin is a real
-// graph child of its root. BOTH config roots participate: `.config` (the instance — DIY dev-flow plugins) and
-// `config` (the project system spec). loadConfig gathers the `command` surface, loadSystemConfig the `system`
+// graph child (a grouping parent like `.plugins/prompts` is itself a spec node, never a bare dir). BOTH plugin roots participate: `.plugins` (the instance — DIY dev-flow plugins) and
+// `plugin-system` (the project system spec). loadConfig gathers the `command` surface, loadSystemConfig the `system`
 // surface, loadHookConfig the `hook` surface, loadSkillConfig the `skill` surface, loadAgentConfig the `agent`
 // surface (sub-agent definitions); each scans the children under every root and filters by the field. The plugins also show on the board as ordinary spec nodes (via loadSpecs).
 // root node - the spec tree's single top-level node: the one directory directly under .spec/ that
 // holds a spec.md. The dogfood repo names it 'spexcode'; a repo scaffolded by `spex init` names it
 // 'project' (or whatever the adopter renames it to). Detected DYNAMICALLY so the config loaders resolve
 // the ACTUAL root's config dirs — never a hardcoded 'spexcode', which silently returned [] in an adopter
-// repo, so their .config/core contract never loaded and their launched agents got no system prompt.
+// repo, so their .plugins/core contract never loaded and their launched agents got no system prompt.
 // Returns null when .spec holds no such directory. (resolveLayout's `main` is a checkout PATH, not the
 // root node NAME, so it can't serve this — a tiny filesystem probe is the right seam.)
 function rootNode(): string | null {
@@ -325,10 +331,20 @@ function rootNode(): string | null {
   return null
 }
 // resolved at call time (not module-eval) so it tracks the live tree.
+// @@@ legacy-tree refusal - v0.3.0 renamed the plugin instance root `.config` → `.plugins`. A pre-0.3.0
+// tree would otherwise load an EMPTY plugin surface — no contract block, no hooks, no commands — and the
+// launched agents would silently run ungoverned. So refuse loudly: existence-only probe (never a dual
+// read of legacy content), pointing at the one-shot migrator. Delete this check in 0.4.0.
 function configRoots(): string[] {
   const root = rootNode()
   if (!root) return []
-  return ['.config', 'config'].map((r) => join(SPEC_DIR, root, r))
+  if (existsSync(join(SPEC_DIR, root, '.config')) && !existsSync(join(SPEC_DIR, root, '.plugins'))) {
+    throw new Error(
+      `.spec/${root}/.config exists but .spec/${root}/.plugins does not — this spec tree predates the v0.3.0 ` +
+      `plugin rename (.config → .plugins). Refusing to load an empty plugin surface (agents would launch ` +
+      `ungoverned). Run \`spex doctor --migrate\` to migrate the tree.`)
+  }
+  return ['.plugins', 'plugin-system'].map((r) => join(SPEC_DIR, root, r))
 }
 // co-located bundle files = everything under the node folder except its spec.md, repo-relative, recursive.
 function bundleFiles(dir: string): string[] {
@@ -343,14 +359,13 @@ function bundleFiles(dir: string): string[] {
   walk(dir)
   return out.sort()
 }
-// gather the preset nodes under a config root that declare `surface: <surface>`. The scan is RECURSIVE —
-// `surface` is a FIELD, not a path (the design's core tenet), so a plugin may live at ANY depth and a
-// grouping parent may itself be a plugin (e.g. `.config/core` is a `surface: system` contract whose CHILDREN
-// are `surface: hook` nodes). The field filter keeps it safe: a node only gathers if it declares THIS
-// surface, so descending past a matched node never double-counts (children carry a different surface). For
-// `system`/`command` the result is identical to the old one-level scan on the current tree — every existing
-// such node is a flat direct child and no nested node declares those surfaces — so the gather set (hence
-// the appended system prompt and the command dropdown) is byte-for-byte unchanged.
+// gather the preset nodes under a plugin root that declare `surface: <surface>`. The scan is RECURSIVE —
+// `surface` is a FIELD, not a path (the design's core tenet), so a plugin may live at ANY depth: under a
+// surface-less grouping shelf (the auxiliary `surface: system` contracts live under `.plugins/prompts/`),
+// or under a plugin that is itself a grouping parent (`.plugins/core` is a `surface: system` contract whose
+// CHILDREN are `surface: hook` nodes). The field filter keeps it safe: a node only gathers if it declares THIS
+// surface, so descending past a matched node never double-counts (children carry a different surface),
+// and the gather set is path-independent — regrouping a plugin never changes what materializes.
 function loadSurface(surface: 'command' | 'system' | 'hook' | 'skill' | 'agent'): ConfigPreset[] {
   const out: ConfigPreset[] = []
   const visit = (nodeDir: string, name: string) => {

package/spec-cli/src/supervise.ts

@@ -37,7 +37,7 @@ const repoRoot = join(here, '..', '..')
 const watchRoots = [
   here,                                  // spec-cli/src — the backend's own source
   join(repoRoot, 'spec-forge', 'src'),
-  join(repoRoot, 'spec-yatsu', 'src'),
+  join(repoRoot, 'spec-eval', 'src'),
 ]
 
 type Backend = { port: number; child: ChildProcess }
@@ -128,7 +128,7 @@ const proxy = net.createServer((client) => {
   client.once('close', () => up.destroy())   // client abandoned → reap its upstream (THE leak that wedged :8787); nothing left to flush to a gone client
   // upstream gone → drop the client half, but ONLY force it when the close was ABNORMAL: on a normal FIN,
   // `up.pipe(client)` has already called `client.end()` (writableEnded), so let the client flush the last of a
-  // large response (e.g. /api/board) rather than truncate it with a destroy; a crash/half-open close (no prior
+  // large response (e.g. /api/graph) rather than truncate it with a destroy; a crash/half-open close (no prior
   // end) still gets reaped.
   up.once('close', () => { if (!client.writableEnded) client.destroy() })
   client.pipe(up); up.pipe(client)

package/spec-cli/src/tree.ts

@@ -1,7 +1,7 @@
-// @@@ spex tree - the CLI's human-readable graph view: the same assembled board the dashboard's
+// @@@ spex graph - the CLI's human-readable graph view: the same assembled board the dashboard's
 // tidy-tree renders, as an indented terminal tree. Pure presentation over buildBoard()'s nodes —
 // no read path of its own; status colours and badge semantics mirror the dashboard (drift /
-// stale-yatsu / open-issues counts). Governed by the spex-tree spec node.
+// stale-eval / open-issues counts). Governed by the spex-tree spec node.
 
 // the subset of a board node this view consumes (buildBoard attaches more; we read only these).
 export type TreeNode = {
@@ -23,7 +23,7 @@ export type TreeOpts = { node?: string; depth?: number; color?: boolean }
 // from the warning yellow), drift=yellow (the dashboard's warning colour), pending=muted grey.
 const STATUS_ANSI: Record<string, string> = { merged: '32', active: '36', drift: '33', pending: '90' }
 
-// stale-yatsu count: declared scenarios whose LATEST reading exists but is no longer fresh.
+// stale-eval count: declared scenarios whose LATEST reading exists but is no longer fresh.
 // board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
 // axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
 function staleYatsu(n: TreeNode): number {
@@ -48,7 +48,7 @@ function childrenIndex(nodes: TreeNode[]): Map<string | null, TreeNode[]> {
 function roots(nodes: TreeNode[], nodeId?: string): TreeNode[] {
   if (nodeId) {
     const hit = nodes.find((n) => n.id === nodeId)
-    if (!hit) throw new Error(`no spec node "${nodeId}" — spex tree lists every id; spex search <topic> finds one by intent`)
+    if (!hit) throw new Error(`no spec node "${nodeId}" — spex graph lists every id; spex spec search <topic> finds one by intent`)
     return [hit]
   }
   const ids = new Set(nodes.map((n) => n.id))
@@ -100,7 +100,7 @@ export function renderTree(nodes: TreeNode[], opts: TreeOpts = {}): string {
 }
 
 // the machine exit: the same filtered subtree as NESTED objects, badge counts precomputed — a
-// shaped view, not a replacement for `spex board` (which stays the full flat payload). Pruned
+// shaped view, not a replacement for `spex graph --json` (which stays the full flat payload). Pruned
 // children degrade to their ids, so --depth still tells the machine what exists below the cut.
 export function treeJson(nodes: TreeNode[], opts: TreeOpts = {}): object[] {
   const byParent = childrenIndex(nodes)

package/spec-cli/src/uninstall.ts

@@ -13,7 +13,7 @@ import { dematerialize } from './materialize.js'
 // and the optional git hooks. EVERY removal is gated on a SpexCode IDENTITY STAMP (the managed-block
 // sentinels, the shim's own dispatch.sh command line, the trust sentinels, the generated mark / name-scoped
 // on-demand paths, the plugin name stamp), so it can only ever delete what SpexCode itself generated. The one
-// inviolable rule: the user's spec ASSET (.spec/.config) is NEVER touched — uninstall removes only generated
+// inviolable rule: the user's spec ASSET (.spec/.plugins) is NEVER touched — uninstall removes only generated
 // WIRING, not the spec graph that wiring served.
 
 // the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
@@ -85,7 +85,7 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
   const proj = resolve(targetArg ?? process.cwd())
   console.log(`spex uninstall → ${proj}`)
 
-  // cwd = the project so the .config loaders read THIS tree's surface nodes (the live skill/agent names tell
+  // cwd = the project so the .plugins loaders read THIS tree's surface nodes (the live skill/agent names tell
   // each adapter's clean() exactly which name-scoped on-demand files were its to remove).
   const prevCwd = process.cwd()
   let arts: HarnessArtifacts = { skills: [], agents: [] }
@@ -93,7 +93,7 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
     process.chdir(proj)
     arts = { skills: loadSkillConfig().map((s) => s.name), agents: loadAgentConfig().map((a) => a.name) }
   } catch {
-    // no readable .config (already partly torn down, or never adopted) — clean still strips the harness wiring.
+    // no readable .plugins (already partly torn down, or never adopted) — clean still strips the harness wiring.
   } finally {
     process.chdir(prevCwd)
   }
@@ -140,6 +140,6 @@ export function uninstall(targetArg: string | undefined, opts: { hooks?: boolean
 
   console.log(`
 SpexCode wiring removed. Your spec data is untouched:
-  • .spec/ and .config/ remain — your spec graph is YOURS, never deleted by uninstall.
+  • .spec/ and .plugins/ remain — your spec graph is YOURS, never deleted by uninstall.
   • To re-adopt later: \`spex init\` regenerates the shims, contract, trust, and global store.`)
 }

package/spec-cli/templates/hooks/post-checkout

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 # @@@ footprint refresh (post-checkout) ([[commit-surgery]]) - a branch checkout is one of the three git
-# transitions that can move the materialize's inputs: .spec/.config content changes across branches, and a
+# transitions that can move the materialize's inputs: .spec/.plugins content changes across branches, and a
 # contract file's TRACKEDNESS can flip (switching to a branch that tracks CLAUDE.md checks out the pristine
 # index prose — the re-materialize here writes the block back into the working file, binds the clean/smudge
 # filter, and withdraws the exclude entry; the kind-transition heals itself). Git-native anchors only —

package/spec-cli/templates/hooks/post-merge

@@ -5,7 +5,7 @@
 # command's own output — a git-native nudge that costs no harness block-cap and reaches a self-launched agent
 # too. GUARDED to the `merge node/<id>:` commit, so an ordinary `git pull`/unrelated merge never nags.
 #
-# The nudge TEXT and the on/off toggle both live in the CLI (`spex issues nudge <node>` prints nothing when
+# The nudge TEXT and the on/off toggle both live in the CLI (`spex internal nudge <node>` prints nothing when
 # the feature is OFF in spexcode.json), so this hook is a THIN resolver + caller: resolve `spex` the same
 # three ways the pre-commit hook does, pass the merged node, echo whatever it prints. No CLI resolvable → no
 # nudge (safe degradation, same as the lint shim's advisory mode).
@@ -19,7 +19,7 @@ spex_run() {
 }
 
 # @@@ footprint refresh ([[commit-surgery]]) - a merge is one of the three git transitions that can move the
-# materialize's inputs (.spec/.config content, contract-file trackedness), so re-materialize here — git-native
+# materialize's inputs (.spec/.plugins content, contract-file trackedness), so re-materialize here — git-native
 # anchors only, never a harness event. Quiet, best-effort: a failed refresh self-heals at the next anchor.
 spex_run internal refresh-footprint >/dev/null 2>&1 || true
 
@@ -29,5 +29,5 @@ case "$subj" in
   *) exit 0 ;;
 esac
 node=$(printf '%s' "$subj" | sed -n 's#^merge \(node/[^:]*\):.*#\1#p')
-spex_run issues nudge "$node"
+spex_run internal nudge "$node"
 exit 0

package/spec-cli/templates/hooks/pre-commit

@@ -30,7 +30,7 @@ spex_cli() {
 # @@@ tree-unchanged stamp - a commit whose tree EQUALS HEAD's tree (`git write-tree` over the commit's own
 # index — the hook's GIT_INDEX_FILE, a temp HEAD-tree index for `commit --only --allow-empty`) adds NO
 # content: it cannot smuggle code past the main-guard below and cannot introduce spec↔code drift, so the
-# whole hook passes it. This is `spex ack`'s empty Spec-OK stamp — the reason ack works on a trunk merge
+# whole hook passes it. This is `spex spec ack`'s empty Spec-OK stamp — the reason ack works on a trunk merge
 # commit (amending it would re-author the merge after MERGE_HEAD is gone and read as direct authoring) and
 # with a DIRTY real index (the lint shim below reads the real index via git.ts's env-strip, which would
 # otherwise block the stamp on the very drift it acknowledges). Deliberately a one-line tree compare, not an
@@ -60,7 +60,7 @@ trunk=$(spex_cli internal trunk 2>/dev/null | head -1)
 if [ "$branch" = "$trunk" ] && [ ! -f "$git_dir/MERGE_HEAD" ] && [ -z "${SPEXCODE_ALLOW_MAIN:-}" ]; then
   echo "✗ SpexCode: direct commits on $trunk (the trunk) are blocked." >&2
   echo "  Work in a worktree (.worktrees/<node>, branch node/<id>) and merge back." >&2
-  echo "  Merges and tree-unchanged stamps (spex ack) pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
+  echo "  Merges and tree-unchanged stamps (spex spec ack) pass automatically; for seeding/topology: SPEXCODE_ALLOW_MAIN=1 git commit …" >&2
   exit 1
 fi
 
@@ -74,13 +74,13 @@ if [ -n "$spex_kind" ]; then
   spex_cli internal commit-surgery || echo "• SpexCode: footprint surgery skipped (error above) — a generated artifact may be staged; CI still enforces." >&2
 fi
 
-# @@@ spec-lint - the hook is just a thin shim over `spex lint`. It blocks on errors only (broken
+# @@@ spec-lint - the hook is just a thin shim over `spex spec lint`. It blocks on errors only (broken
 # spec↔code links); coverage/drift are warnings. Bypass with SPEXCODE_SKIP_LINT=1. It shims through the
 # shared spex_cli() resolved above (repoRoot() discovers the cwd's toplevel via git.ts, which strips the
 # hook's GIT_DIR, so lint validates THIS worktree's `.spec`).
 if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
   if [ -n "$spex_kind" ]; then
-    spex_cli lint >&2
+    spex_cli spec lint >&2
     lint_rc=$?
     # exit 75 = the launcher's mid-merge guard (spex's own source holds conflict markers — transient).
     # Degrade to advisory rather than walling every commit behind a merge someone else is resolving.
@@ -90,11 +90,11 @@ if [ -z "${SPEXCODE_SKIP_LINT:-}" ]; then
       echo "✗ SpexCode: spec-lint failed — fix the spec↔code links or bypass with SPEXCODE_SKIP_LINT=1." >&2
       exit 1
     else
-      # @@@ yatsu backstop - reject a staged yatsu offender: a stray pixel blob copied into the tree (blobs
-      # belong in the shared git common dir, never committed) OR a malformed yatsu.md (a scenario schema
-      # violation). Logic lives in spec-yatsu; this is the lint-shim's twin. (this node's contract)
-      if ! spex_cli yatsu check-staged >&2; then
-        echo "✗ SpexCode: yatsu check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
+      # @@@ eval backstop - reject a staged eval offender: a stray evidence blob copied into the tree (blobs
+      # belong in the shared git common dir, never committed) OR a malformed eval.md (a scenario schema
+      # violation). Logic lives in spec-eval; this is the lint-shim's twin. (this node's contract)
+      if ! spex_cli internal check-staged >&2; then
+        echo "✗ SpexCode: internal check-staged failed (see above) — fix it or bypass with SPEXCODE_SKIP_LINT=1." >&2
         exit 1
       fi
     fi

package/spec-cli/templates/hooks/prepare-commit-msg

@@ -34,7 +34,7 @@ fi
 
 [ -z "$sid" ] && exit 0
 # Stamp via interpret-trailers (git's own sample-hook mechanism), NOT a raw printf append: appending after a
-# message that already carries a trailer block (e.g. `spex ack`'s Spec-OK) opens a new paragraph, and git then
+# message that already carries a trailer block (e.g. `spex spec ack`'s Spec-OK) opens a new paragraph, and git then
 # parses ONLY the last paragraph as trailers — the earlier trailers silently become body prose. interpret-trailers
 # appends into the existing block, keeping ONE parseable block. It needs the file newline-terminated first:
 # on an unterminated message (git merge -m writes MERGE_MSG without one) it folds the trailer into the subject

package/spec-cli/templates/spec/project/{.config → .plugins}/core/idle/idle.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# On an idle_prompt notification, mark the session idle (the active-only guard in `session idle` keeps a
+# 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-
@@ -12,4 +12,4 @@ 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} session idle --session "$sid"
+[ "$(hp_notification_type "$payload")" = idle_prompt ] && exec ${SPEX:-spex} internal session-idle --session "$sid"

package/spec-cli/templates/spec/project/{.config → .plugins}/core/mark-active/mark-active.sh

@@ -15,6 +15,13 @@
 # (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"

package/spec-cli/templates/spec/project/{.config → .plugins}/core/mark-active/spec.md

@@ -13,4 +13,6 @@ The single freshness signal for a session. Any work a session does — a new pro
 
 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.
+
 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/spec-cli/templates/spec/project/{.config → .plugins}/core/session-fail/fail.sh

@@ -9,4 +9,4 @@ 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} session fail --session "$sid"
+exec ${SPEX:-spex} internal session-fail --session "$sid"

package/spec-cli/templates/spec/project/{.config → .plugins}/core/spec-first/spec-first.sh

@@ -48,7 +48,7 @@ if [ -n "$node" ]; then
   sp=$(find .spec -path "*/$node/spec.md" 2>/dev/null | head -1)
   where="your node's spec (${sp:-.spec/.../$node/spec.md})"
 else
-  where="the spec node that governs this area (run: spex search <topic>)"
+  where="the spec node that governs this area (run: spex spec search <topic>)"
 fi
 printf '{"decision":"block","reason":"Before working in this code, read %s FIRST — it is the current contract — and read its NEIGHBORS too (the parent that scopes it, the siblings it borders, the children that refine it), since its intent is only fully legible against the surrounding tree. Then act deliberately: changing the intent? edit the spec first so spec and code land together. implementing existing intent? make the code honor the spec. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at your first code read or edit.)"}\n' "$where"
 exit 0

package/spec-cli/templates/spec/project/{.config → .plugins}/core/spec-of-file/spec-of-file.sh

@@ -4,7 +4,7 @@
 # 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 owner`); cwd = the session worktree.
+# 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.
@@ -52,7 +52,7 @@ while IFS= read -r path; do
   path=$(hp_actionable_repo_path "$path") || continue
   [ -f "$led" ] && grep -qxF -- "$path" "$led" && continue
   mkdir -p "$sdir"; echo "$path" >> "$led"
-  m=$(cd "$repo" && $S owner "$path" --actionable 2>/dev/null)   # --actionable: silent on a sanely-owned file; speaks only for an OVER-owned / uncovered file
+  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"

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

@@ -0,0 +1,21 @@
+---
+title: core
+surface: system
+status: active
+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.
+
+Four disciplines, non-negotiable:
+
+1. SPEC FIRST. Before you touch code — and merely READING it counts, not only editing — read the governing spec's BODY: its actual prose, not the title, not the one-line desc, not your memory of it. The body is the current contract; code and its comments tell you what the code DOES, only the spec tells you what it is SUPPOSED to do. Don't know which node governs the area? `spex spec search <topic>` — not grep: grep finds code by architectural centrality, search finds intent by user-story. Read the NEIGHBORS' bodies too — the parent that scopes it, the siblings it borders, the children that refine it — a node's intent is only legible against the tree around it. If your task changes the intent, edit the spec first so spec and code land together; if it implements existing intent, make the code honor the spec. The one forbidden move is code that silently diverges from its spec.
+
+2. COMMIT BEFORE YOU DECLARE. Commit your spec node and the code it justifies BEFORE you declare done or propose merge — the commit comes first, never as an afterthought to a declaration. An independently-scoped feature gets its OWN sibling spec node, not a ride-along in your assigned node's commit (cosmetic polish riding along is the smell).
+
+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.
+
+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/{.config → .plugins}/core/stop-gate/stop-gate.sh

@@ -35,33 +35,33 @@ proposal=$(jget proposal)
 # 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
+# @@@ eval advisory - a nudge (never a gate) emitted when a session stops CLEAN-DONE (committed work + a
+# done/awaiting declaration): the agent IS the measuring hand, so an eval gap in what it just changed is a
+# blind spot to flag the moment work lands. SCOPED via `spex eval lint --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
+# that made three workers ask "is this mine?"). Three gap classes it surfaces: eval-drift / eval-missing
+# (a node with an eval.md whose score is stale / unmeasured) and eval-coverage (a FRONTEND node with no
+# eval.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.
 #
 # SURFACE-NEUTRAL: a stale/unmeasured score is refreshed only by PRODUCING the measurement on the scenario's
 # OWN surface — a real run, never a desk check and never deferring to review a recording after the fact. The
-# nudge privileges NO surface: `scan --changed` carries each drift/missing scenario's tag on its finding line
-# ([[yatsu-core]]'s lint.scenarioTags — frontend-e2e / backend-api / cli / desktop / mobile), so the agent
+# nudge privileges NO surface: `eval lint --changed` carries each drift/missing scenario's tag on its finding line
+# ([[eval-core]]'s lint.scenarioTags — frontend-e2e / backend-api / cli / desktop / mobile), so the agent
 # reads there WHICH surface to run. One line covers all five surfaces; there is no per-surface branch.
-yatsu_advisory() {
+eval_advisory() {
   local out ids n msg esc
   # Codex Stop hooks reject the Claude-family `hookSpecificOutput.additionalContext` shape on allow paths.
   # Keep Codex Stop stdout empty unless it is a real block decision; the dispatcher still bridges block
   # reasons to Codex stderr.
   [ "${SPEXCODE_HARNESS:-claude}" = codex ] && return 0
-  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 — PRODUCE the measurement YOURSELF with a real run of the scenario's actual surface (its tag on the \`spex yatsu scan --changed\` line tells you WHICH surface to run), compare to expected, and file it with \`spex yatsu eval <node>\`; don't desk-check it, and don't defer to reviewing a recording after the fact. 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.)"
+  out=$($S eval lint --changed 2>&1)
+  n=$(printf '%s\n' "$out" | grep -cE 'eval-(drift|missing|coverage):')
+  [ "${n:-0}" -gt 0 ] || return 0   # no gap in what you changed (or eval lint unavailable) -> nothing to nudge
+  ids=$(printf '%s\n' "$out" | sed -n "s/.*eval-[a-z]*: '\([^']*\)'.*/\1/p" | awk '!seen[$0]++' | head -6 | paste -sd' ' -)
+  msg="eval — 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 — PRODUCE the measurement YOURSELF with a real run of the scenario's actual surface (its tag on the \`spex eval lint --changed\` line tells you WHICH surface to run), compare to expected, and file it with \`spex eval add <node>\`; don't desk-check it, and don't defer to reviewing a recording after the fact. A FRONTEND node with no eval.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. \`spex eval lint --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"
 }
@@ -69,17 +69,17 @@ yatsu_advisory() {
 # @@@ 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()
+# declaration we run the deterministic check (`spex internal 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
+  if gatemsg=$($S internal 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
+    [ "$cont" != true ] && eval_advisory
     exit 0   # work is committed and ahead of main -> the proposal is honest, let it stop.
   fi
   if [ "$cont" = true ]; then
@@ -98,9 +98,9 @@ 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),
+  if $S internal commit-gate >/dev/null 2>&1; then
+    $S internal session-state awaiting --session "$sid" --propose nothing --note "auto: stopped without declaring" >/dev/null 2>&1 || true
+    # NOTE: no eval 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
@@ -134,5 +134,5 @@ touch "$taught" 2>/dev/null || true
 # tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
 # this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
 # kills the park->block->re-park loop at its source lives here.
-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 and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — 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; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
+printf '{"decision":"block","reason":"Your session state is a CLAIM the graph, 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 and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex session 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; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, arm your background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
 exit 0

package/spec-cli/templates/spec/project/{.config → .plugins}/distill/spec.md

@@ -19,14 +19,14 @@ Input: a session id — SpexCode's, a bare harness id (claude / codex thread), o
 - **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 prompt <id>`. For a claude-harness session the transcript id IS the SpexCode session id;
+  `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.
 
 ## 2 · digest the transcript — mechanical first, model second
 
-`node .spec/<root>/.config/distill/digest.mjs <id-or-path>` locates the transcript (claude:
+`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