spexcode 0.3.0 → 0.4.0

package/spec-cli/src/lint.ts

@@ -1,8 +1,9 @@
 import { readdirSync, readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
-import { repoRoot, stagedFiles, git } from './git.js'
+import { repoRoot, git, driftIndex, historyIndex, rowsFor } from './git.js'
 import { loadSpecs } from './specs.js'
 import { readJsonConfig } from './layout.js'
+import { extractors, extractorFor, extOf, resolveAnchor, windowCommits, anchorHitCommits } from './anchors.js'
 
 export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
 
@@ -13,7 +14,6 @@ export type LintConfig = {
   identifierExtensions: string[]// extensions the altitude bare-filename signal recognises (see IDENT below)
   altitude: { lineBudget: number; charBudget: number; sizeable: number; dense: number; steps: number }
   maxChildren: number        // breadth budget: warn at >= this many direct children
-  driftErrorThreshold: number// commit-local gate HARD-BLOCKS a commit touching a node >= this many commits behind
   maxOwners: number          // warn when a file is governed (code:) by > this many nodes
   scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
 }
@@ -24,7 +24,6 @@ const DEFAULT_CONFIG: LintConfig = {
   identifierExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'md'],
   altitude: { lineBudget: 50, charBudget: 4200, sizeable: 35, dense: 1.3, steps: 3 },
   maxChildren: 8,
-  driftErrorThreshold: 3,
   maxOwners: 3,
   scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
 }
@@ -277,6 +276,59 @@ export async function specLint(): Promise<Finding[]> {
     out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
   }
 
+  // code anchors ([[code-anchor]]): a code: entry may pin one named unit (`path#symbol`). The anchor is
+  // the BLOCKING tier of drift: a window commit (spec's last version..HEAD, non-merge, touching the
+  // governed file) whose --unified=0 hunks intersect the unit's line range — extracted from the file AS
+  // OF that commit, by the extension's ONE designated extractor — is an anchor-drift ERROR unless a
+  // Spec-OK ack covers it. Resolution failures are never silent: a dead or ambiguous anchor, an
+  // unparseable working-tree file, an extension with no designated extractor, and a designated extractor
+  // that can't run here (no host typescript) all ERROR with the repair spelled out.
+  const regs = extractors(root)
+  const [didx, hidx] = await Promise.all([driftIndex(root), historyIndex(root)])
+  const readyWarned = new Set<string>()
+  for (const s of specs) {
+    for (const { path, anchor } of s.anchors) {
+      const x = extractorFor(regs, extOf(path))
+      if (!x) {
+        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${anchor}, but no extractor is designated for '.${extOf(path)}' files — this language has no anchor support yet: add a LangSpec row (anchors.ts) or drop the #${anchor}` })
+        continue
+      }
+      const ready = x.ready()
+      if (ready !== true) {
+        // once per (extractor, reason), even across several anchored nodes — one repair, one message.
+        if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); out.push({ level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` }) }
+        continue
+      }
+      if (!existsSync(join(root, path))) continue // the missing FILE already errored above
+      let units
+      try { units = x.extract(readFileSync(join(root, path), 'utf8'), path) } catch (e: any) {
+        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${anchor} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` })
+        continue
+      }
+      const res = resolveAnchor(units, anchor)
+      if ('dead' in res) {
+        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${anchor} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's code: entry to follow it` })
+        continue
+      }
+      if ('ambiguous' in res) {
+        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${anchor} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` })
+        continue
+      }
+      if (res.ok.typeOnly)
+        out.push({ level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${anchor} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` })
+      const since = rowsFor(hidx, s.path)[0]?.hash || ''
+      const win = windowCommits(didx, since, path)
+      if (!win.length) continue
+      const hits = await anchorHitCommits(root, win, path, anchor, x)
+      const unparseable = hits.filter((h) => h.unparseable)
+      if (hits.length) {
+        const shas = hits.map((h) => h.commit.slice(0, 8)).join(', ')
+        const parseNote = unparseable.length ? ` (${unparseable.length} of these could not be parsed at that commit — counted as hits conservatively)` : ''
+        out.push({ level: 'error', rule: 'anchor-drift', spec: s.id, file: path, msg: `${path}#${anchor} was changed by ${hits.length} commit(s) since spec '${s.id}' v${s.version} [${shas}]${parseNote} — the anchored contract's code moved: update the spec, or 'spex spec ack ${s.id} --reason "…"' if the contract still holds` })
+      }
+    }
+  }
+
   // drift: a governed file has commits NOT yet reflected in its spec. Judged by true git ancestry —
   // loadSpecs computes `driftFiles` via driftFor() over the one cached driftIndex walk (git.ts): a
   // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
@@ -321,22 +373,3 @@ Diagnose, then apply the one honest remedy:
                               maps to a node, or file an issue and link it (defer honestly)
 
 Never patch. A reasoned ack or a real fix are recorded and re-judged at review; a blind ack is a lie.`
-
-// commit-local: an empty staged index (CI, audit) → no blockers, drift stays advisory; non-empty → block
-// only when an OWN staged file belongs to a node already >= driftErrorThreshold behind. Sub-threshold drift
-// on a touched node is returned for an advisory nudge; the backlog on untouched nodes never blocks.
-export async function driftGate(): Promise<{ blocked: string[]; touched: { id: string; drift: number }[]; threshold: number }> {
-  const root = repoRoot()
-  const cfg = loadConfig(root)
-  const staged = stagedFiles(root)
-  if (!staged.length) return { blocked: [], touched: [], threshold: cfg.driftErrorThreshold }
-  const specs = await loadSpecs()
-  const owners = new Map<string, string[]>()
-  for (const s of specs) for (const f of s.code) owners.set(f, [...(owners.get(f) ?? []), s.id])
-  const byId = new Map(specs.map((s) => [s.id, s]))
-  const ids = new Set<string>()
-  for (const f of staged) for (const o of owners.get(f) ?? []) ids.add(o)
-  const touched = [...ids].map((id) => byId.get(id)!).filter((s) => s && s.drift > 0)
-    .map((s) => ({ id: s.id, drift: s.drift })).sort((a, b) => b.drift - a.drift)
-  return { blocked: touched.filter((t) => t.drift >= cfg.driftErrorThreshold).map((t) => t.id), touched, threshold: cfg.driftErrorThreshold }
-}

package/spec-cli/src/localIssues.ts

@@ -272,6 +272,25 @@ function writeStoreFile(p: Issue, message: string): boolean {
   return true
 }
 
+// @@@ the shared trunk-data commit — the committing half of the store discipline, exported for OTHER
+// git-tracked data writes that need a durable landing with no worktree ritual behind them (the eval
+// sidecar's human-ok, [[human-ok]]). Same rules as the issue store's own write: only the trunk checkout
+// itself commits (a linked-worktree caller gets 'not-primary' back and leaves its append for its own
+// session's ritual commit — the sidecar, unlike the issue store, legitimately lives per-branch and
+// merges); the commit is `--no-verify` and provably scoped to the one data path; the shared store lock
+// serializes it against every other trunk data write so racing writers never fight over the git index.
+export function commitTrunkData(relPath: string, message: string): 'committed' | 'no-op' | 'not-primary' {
+  if (overrideStoreDir()) return 'not-primary'   // a disposable-store test rig commits nothing, ever
+  if (!isPrimaryCheckout()) return 'not-primary'
+  return withStoreLock(() => {
+    const root = mainCheckout()
+    git(['-C', root, 'add', '--', relPath])
+    if (!git(['-C', root, 'status', '--porcelain', '--', relPath]).trim()) return 'no-op'
+    git(['-C', root, 'commit', '--no-verify', '-m', message, '--', relPath])
+    return 'committed'
+  })
+}
+
 // prepare (a FRESH read-modify or a new thread) + write + commit a single store file, all under the store
 // lock so the read-modify-write is atomic. prepare() runs INSIDE the lock, so a reply/close reads the
 // current thread, never a stale copy. A pre-rename store migrates first (before the lock — ensure takes it).

package/spec-cli/src/migrate-table.ts

@@ -5,13 +5,6 @@
 // else is flagged for review, never rewritten.
 export type MigrateAsset = { rel: string; template: string; oldShas: string[] }
 export const TEMPLATE_ASSETS: MigrateAsset[] = [
-  {
-    "rel": "clarify-before-code/spec.md",
-    "template": "templates/presets/careful/.plugins/clarify-before-code/spec.md",
-    "oldShas": [
-      "a1b9c7e189df9b75a27005d381b43682d717ee6f"
-    ]
-  },
   {
     "rel": "core/idle/idle.sh",
     "template": "templates/spec/project/.plugins/core/idle/idle.sh",
@@ -196,7 +189,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "forge-link/spec.md",
-    "template": "templates/spec/project/.plugins/forge-link/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/forge-link/spec.md",
     "oldShas": [
       "2472c085e6f72364eea004ba1d1b1f8d6b4e13ac",
       "c86439c5a3fe6cb3ece2c40186da0f476d1c52d4"
@@ -204,11 +197,16 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "memory-hygiene/spec.md",
-    "template": "templates/spec/project/.plugins/memory-hygiene/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/memory-hygiene/spec.md",
     "oldShas": [
       "2b5313e770c7d2e857817adcf7bb72aecaeca45f"
     ]
   },
+  {
+    "rel": "prompts/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/spec.md",
+    "oldShas": []
+  },
   {
     "rel": "regroup/spec.md",
     "template": "templates/spec/project/.plugins/regroup/spec.md",
@@ -220,7 +218,7 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
   },
   {
     "rel": "reproduce-before-fix/spec.md",
-    "template": "templates/spec/project/.plugins/reproduce-before-fix/spec.md",
+    "template": "templates/spec/project/.plugins/prompts/reproduce-before-fix/spec.md",
     "oldShas": [
       "28eef30893a83b634900e43dfe729043c8f60ea8",
       "2d056b7344cbc0c4eb0dbeb0ba69ccee0e8b47db",
@@ -286,6 +284,9 @@ export const TEMPLATE_ASSETS: MigrateAsset[] = [
 ]
 // old-world template assets the shipped package no longer carries (recognized → reported, not replaced):
 export const RETIRED_ASSETS: Record<string, string[]> = {
+  "clarify-before-code/spec.md": [
+    "a1b9c7e189df9b75a27005d381b43682d717ee6f"
+  ],
   "core/harness-session-id/harness-session-id.sh": [
     "32b3b963ba6c2c659f0543e82a2a34128c4860bf",
     "626d7f3c56d6430c5dafb7713880a606b4ee8b03"
@@ -296,11 +297,11 @@ export const RETIRED_ASSETS: Record<string, string[]> = {
     "c05f182fc92fcd224f4c7953dc118e59665971aa",
     "c617fc05780f921c55280b68d9f55e60110f74eb"
   ],
-  "core/stop-gate/yatsu.evals.ndjson": [  // dead-words-ok: the migrator names the old vocabulary it migrates from
+  "core/stop-gate/yatsu.evals.ndjson": [
     "268c06c27f3b2dc71da8c0aca4d0507a227829f9",
     "e681fe71b8519577c19bb4f13bc0f310fb92dc31"
   ],
-  "core/stop-gate/yatsu.md": [  // dead-words-ok: the migrator names the old vocabulary it migrates from
+  "core/stop-gate/yatsu.md": [
     "f83f6b2406eb359beb1181bf0145558241806116"
   ],
   "e2e-review/spec.md": [

package/spec-cli/src/search.bench.mjs

@@ -3,7 +3,7 @@
 //
 // Labels are node LEAF names, matched with the same de-collision rule the loader applies (specs.ts reId):
 // a returned id matches a label if it IS the label or ends with `_<label>` — so a bare leaf keeps matching
-// after collision-qualification renames it (e.g. `spec-scout` → `injected-context_spec-scout`). A label may
+// after collision-qualification renames it (e.g. a colliding `probe` leaf → `a_probe`). A label may
 // also be written pre-qualified to pin one collision branch.
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
@@ -26,7 +26,7 @@ const CASES = [
   ['read-before-code', 'the one-shot nudge that makes an agent read its spec before touching code', ['spec-first']],
   ['hot-reload', 'zero-downtime backend reload without dropping connections', ['supervisor']],
   ['many-owners', 'can several specs own the same code file, and what happens if too many do?', ['governed-related']],
-  ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-scout']],
+  ['active-spec-search', 'an injected sub-agent that searches specs for the agent, the spec analog of Explore', ['spec-search']],
   ['declare-done', 'how does a worker declare it is done', ['state']],
 ]
 

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,7 +98,7 @@ 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. `.plugins_spec-scout`) stays a single token everywhere it is resolved.
+// 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.
@@ -174,7 +175,7 @@ function claimMatcher(file: string): (cf: string) => boolean {
 // 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, never eval freshness):
@@ -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
@@ -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)
@@ -302,11 +308,11 @@ 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 plugin is a FLAT direct child of a plugin 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 plugin roots participate: `.plugins` (the instance — DIY dev-flow plugins) and
+// 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).
@@ -354,13 +360,12 @@ function bundleFiles(dir: string): string[] {
   return out.sort()
 }
 // 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 and a
-// grouping parent may itself be a plugin (e.g. `.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). 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.
+// `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/templates/spec/project/.plugins/core/spec.md

@@ -10,7 +10,7 @@ The CLI speaks ONE grammar: `spex <noun> <verb> [object] [flags]`. Six nouns —
 
 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 (for a find-by-story question a keyword can't reach, dispatch the `spec-scout` agent). 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.
+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).
 

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

@@ -45,7 +45,7 @@ Then grow nodes under that spine:
 `.svelte`/`.css`, or the dashboard) is a blind spot until it carries a `eval.md` — so write one as you
 extract it: a **real user-path** scenario — a goal and the steps to reach it through the running app (never a
 bare render-check), covering a failure/empty/edge state — with a **description** of those steps and the
-**expected** zero-loss result. Frontend scenarios are measured by looking (YATU) — a screenshot filed with
+**expected** zero-loss result. Frontend scenarios are measured by looking — through the running product, as a real user would — a screenshot filed with
 `spex eval add <node> --image <png> --pass`. Backend nodes don't need one yet; run `spex eval lint` to
 list the frontend nodes still uncovered.
 

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

@@ -0,0 +1,20 @@
+---
+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.
+---
+# 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.
+
+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.
+
+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.

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

@@ -6,8 +6,11 @@ desc: The instance home — this repo's DIY dev-flow plugins live here as skill-
 ---
 `.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) — living as a flat child of `.plugins/` and carrying a `surface: command|system` field
-that names where it plugs in.
+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/`, while `core` — the contract subsystem whose
+children are the `surface: hook` gates — and invocable presets (command/skill/agent) are flat
+children here.
 
 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`

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

@@ -5,4 +5,4 @@ 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 worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex session review <id>` or `spex session ls` — both return immediately); never block on `spex session watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: 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:
+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 the project's agent notes (`<root>/CLAUDE.md` / `AGENTS.md`, including the materialized `<!-- spexcode -->` contract block)** for project-specific rules; the loop below (dispatch → monitor → review → merge → close, parallelizing independent tasks) is your playbook. Then drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` — give each ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), monitor with `spex session watch`, review proposals with `spex session review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex session review <id>` or `spex session ls` — both return immediately); never block on `spex session watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: 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/spec-cli/templates/spec/project/spec.md

@@ -12,7 +12,7 @@ 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 flat child nodes, each tagged
+`.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