@spexcode/spec-core 0.6.2

package/src/specs.ts

@@ -0,0 +1,498 @@
+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, historyStats, pathsStats, driftIndex, driftFor, fileDiffAt,
+  sourceIndexes, treeTextFiles, primeAncestorClosures, ancestorsOf, inAncestors, type HistoryIndex, type DriftIndex } from './git.js'
+import { parseCodeEntry, parseRelation, relationClaimsPath } 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()
+const SPEC_DIR = join(ROOT, '.spec')
+
+type FmValue = string | string[]
+type Raw = { id: string; parent: string | null; relPath: string; fm: Record<string, FmValue>; body: string }
+
+// line-based frontmatter: scalars are `key: value`; an empty key followed by `- item` lines is a list (e.g. `code:`).
+export function parseFrontmatter(src: string) {
+  const fm: Record<string, FmValue> = {}
+  let body = src
+  const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/)
+  if (m) {
+    let key: string | null = null
+    for (const line of m[1].split('\n')) {
+      const item = line.match(/^\s*-\s+(.*)$/)
+      if (item && key) {
+        if (!Array.isArray(fm[key])) fm[key] = fm[key] ? [fm[key] as string] : []
+        ;(fm[key] as string[]).push(item[1].trim())
+        continue
+      }
+      const i = line.indexOf(':')
+      if (i > 0) { key = line.slice(0, i).trim(); fm[key] = line.slice(i + 1).trim() }
+    }
+    body = m[2]
+  }
+  return { fm, body }
+}
+
+const str = (v: FmValue | undefined, d = '') => (Array.isArray(v) ? v.join(', ') : v ?? d)
+const list = (v: FmValue | undefined): string[] => (Array.isArray(v) ? v : v ? [v] : [])
+
+export type SpecParts = {
+  rawSource: string
+  expandedSpec: string
+}
+const PART_ALIASES: Record<string, 'rawSource' | 'expandedSpec'> = {
+  'raw source': 'rawSource',
+  'expanded spec': 'expandedSpec',
+}
+function parseParts(body: string): SpecParts | null {
+  const acc = { rawSource: [] as string[], expandedSpec: [] as string[] }
+  let cur: 'rawSource' | 'expandedSpec' | null = null
+  let inFence = false
+  let any = false
+  for (const line of body.split('\n')) {
+    const fence = /^\s*```/.test(line)
+    if (!inFence && !fence) {
+      const h2 = line.match(/^##\s+(.+?)\s*$/)   // exactly two hashes — `###` won't match
+      if (h2) {
+        const key = PART_ALIASES[h2[1].trim().toLowerCase()]
+        if (key) { cur = key; any = true; continue }
+        // an unrecognized `## …` heading is just content of the current part — fall through.
+      }
+    }
+    if (fence) inFence = !inFence
+    if (cur === 'rawSource') acc.rawSource.push(line)
+    else if (cur === 'expandedSpec') acc.expandedSpec.push(line)
+  }
+  if (!any) return null
+  const t = (a: string[]) => a.join('\n').trim()
+  return { rawSource: t(acc.rawSource), expandedSpec: t(acc.expandedSpec) }
+}
+
+export type DerivedStatus = 'pending' | 'active' | 'merged' | 'drift'
+
+export function deriveStatus(d: { version: number; drift: number; hasOverlay?: boolean; hasCode?: boolean; fmStatus?: string }): DerivedStatus {
+  if (d.fmStatus === 'pending' && !d.hasCode && d.drift === 0) return 'pending'
+  if (d.hasOverlay) return 'active'
+  if (d.drift > 0) return 'drift'
+  if (d.version > 0) return 'merged'
+  const fb = d.fmStatus
+  if (fb === 'active' || fb === 'merged' || fb === 'drift') return fb
+  return 'pending'
+}
+
+function walk(dir: string, parent: string | null, acc: Raw[]) {
+  let myId = parent
+  if (existsSync(join(dir, 'spec.md'))) {
+    myId = basename(dir)
+    const relPath = relative(ROOT, join(dir, 'spec.md'))
+    const { fm, body } = parseFrontmatter(readFileSync(join(dir, 'spec.md'), 'utf8'))
+    acc.push({ id: myId, parent, relPath, fm, body })
+  }
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) walk(join(dir, e.name), myId, acc)
+  }
+}
+
+// the id MINT ([[id-url-safe]]): key each node — given its path segments under .spec — to its leaf dir
+// name, or on a leaf collision the shortest globally-unique trailing path-suffix. A node id is a URL-safe
+// 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_<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[] {
+  // NFC pins one canonical byte form for a non-ASCII dir name (macOS hands out NFD basenames), so a typed
+  // `[[中文节点]]` (NFC, what an IME emits) string-matches the minted id on every platform.
+  const suffix = (s: string[], k: number) => s.slice(s.length - k).join('_').normalize('NFC')
+  return segs.map((s, i) => {
+    let k = 1
+    while (k < s.length && segs.some((o, j) => j !== i && o.length >= k && suffix(o, k) === suffix(s, k))) k++
+    return suffix(s, k)
+  })
+}
+
+// re-key each node via the mint (overrides walk's placeholder basename id/parent); the second loop
+// recomputes parent by path-ancestry.
+function reId(acc: Raw[]): void {
+  const segs = acc.map((r) => r.relPath.split(/[/\\]/).slice(1, -1))   // path under .spec, minus 'spec.md'
+  const ids = mintIds(segs)
+  for (let i = 0; i < acc.length; i++) acc[i].id = ids[i]
+  for (let i = 0; i < acc.length; i++) {
+    let best = -1
+    for (let j = 0; j < acc.length; j++) {
+      const o = segs[j], s = segs[i]
+      if (j !== i && o.length < s.length && o.every((seg, x) => seg === s[x]) && (best < 0 || o.length > segs[best].length)) best = j
+    }
+    acc[i].parent = best >= 0 ? acc[best].id : null
+  }
+}
+
+function raws(): Raw[] {
+  const acc: Raw[] = []
+  if (existsSync(SPEC_DIR)) walk(SPEC_DIR, null, acc)
+  reId(acc)
+  return acc
+}
+
+// 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
+// loadSpecs (already async, on the hot path) uses it, the light one-shot callers keep the sync raws().
+async function walkAsync(dir: string, parent: string | null, acc: Raw[], root: string): Promise<void> {
+  let myId = parent
+  if (existsSync(join(dir, 'spec.md'))) {
+    myId = basename(dir)
+    const relPath = relative(root, join(dir, 'spec.md'))
+    const { fm, body } = parseFrontmatter(await readFile(join(dir, 'spec.md'), 'utf8'))
+    acc.push({ id: myId, parent, relPath, fm, body })
+  }
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) await walkAsync(join(dir, e.name), myId, acc, root)
+  }
+}
+export type SpecTreeSnapshot = { tip: string; files: ReadonlyMap<string, string> }
+
+async function rawsAsync(root: string, tip = 'HEAD', snapshot?: SpecTreeSnapshot): Promise<Raw[]> {
+  if (snapshot || tip !== 'HEAD') {
+    const acc: Raw[] = []
+    const files = snapshot?.files ?? treeTextFiles(root, tip, '.spec')
+    for (const [relPath, source] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
+      if (!relPath.endsWith('/spec.md')) continue
+      const segs = relPath.split('/')
+      const { fm, body } = parseFrontmatter(source)
+      acc.push({ id: segs[segs.length - 2], parent: null, relPath, fm, body })
+    }
+    reId(acc)
+    return acc
+  }
+  const acc: Raw[] = []
+  const specDir = join(root, '.spec')
+  if (existsSync(specDir)) await walkAsync(specDir, null, acc, root)
+  reId(acc)
+  return acc
+}
+
+// the claim rule shared by both relations (exact path, dir-prefix, or *-glob). See [[governed-related]].
+function claimMatcher(file: string): (cf: string) => boolean {
+  const rel = file.startsWith('/') ? relative(ROOT, file) : file
+  return (claim) => relationClaimsPath(claim, rel)
+}
+
+// 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. `scoped` = every claiming entry carries a
+// `#selector` — such a governor still displays, but does not count toward the owners bound ([[code-anchor]]).
+export function specOwners(file: string): { id: string; desc: string; scoped: boolean }[] {
+  const claims = claimMatcher(file)
+  return raws().flatMap((r) => {
+    const entries = list(r.fm.code).map(parseCodeEntry).filter((e) => claims(e.path))
+    return entries.length ? [{ id: r.id, desc: str(r.fm.desc), scoped: entries.every((e) => e.anchor !== null) }] : []
+  })
+}
+
+// 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)
+  return raws().filter((r) => list(r.fm.related).some((e) => claims(parseCodeEntry(e).path))).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
+}
+
+// memo fileDiffAt by (version sha + spec.md path) — a commit's patch is immutable. Keyed by path too: one
+// commit can patch several nodes' spec.md. `{hash:'',patch:''}` for an unversioned node (no git call).
+const diffCache = new Map<string, { hash: string; patch: string }>()
+async function latestDiff(relPath: string, hash: string): Promise<{ hash: string; patch: string }> {
+  if (!hash) return { hash: '', patch: '' }
+  const key = `${hash}\0${relPath}`
+  const hit = diffCache.get(key)
+  if (hit) return hit
+  const val = { hash, patch: await fileDiffAt(ROOT, relPath, hash) }
+  diffCache.set(key, val)
+  return val
+}
+
+// filesystem-only slice of a node (id/title/path/desc/body, no git) for hot lexical reads like
+// [[spec-search]]; same fields loadSpecs reports, without the git history/drift walk.
+export type SpecLite = { id: string; title: string; path: string; desc: string; body: string }
+export function loadSpecsLite(): SpecLite[] {
+  return raws().map((r) => ({
+    id: r.id,
+    title: str(r.fm.title, r.id),
+    path: r.relPath,
+    desc: str(r.fm.desc),
+    body: r.body.trim(),
+  }))
+}
+
+// one node's body + parsed parts, filesystem-only (no git). The board omits both to stay lean
+// ([[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
+}
+
+// `root` defaults to the backend's own checkout — the canonical tree. A session worktree may be passed
+// instead ([[source-of-truth]]'s several-checkouts principle at the loader level): its .spec is the
+// branch's pending proposal, so eval surfaces rooted at a session must load the spec tree from the SAME
+// root as their readings/indexes, or a branch-NEW node simply does not exist for them.
+export type LoadSpecsOptions = {
+  tip?: string
+  history?: HistoryIndex | null
+  drift?: DriftIndex | null
+  snapshot?: SpecTreeSnapshot
+}
+export async function loadSpecs(root: string = ROOT, options: LoadSpecsOptions = {}) {
+  // The default pair shares one immutable-event snapshot; explicit sides let callers skip or supply either
+  // projection. Every node below is then a pure in-memory lookup.
+  const tip = options.tip ?? 'HEAD'
+  if (options.snapshot && options.snapshot.tip !== tip) {
+    throw new Error(`loadSpecs snapshot tip '${options.snapshot.tip}' does not match requested tip '${tip}'`)
+  }
+  const indexes = options.history === undefined && options.drift === undefined
+    ? sourceIndexes(root, tip)
+    : Promise.all([
+      options.history === null ? Promise.resolve(null) : options.history ?? historyIndex(root, tip),
+      options.drift === null ? Promise.resolve(null) : options.drift ?? driftIndex(root, tip),
+    ])
+  const [[idx, didx], allRaws] = await Promise.all([indexes, rawsAsync(root, tip, options.snapshot)])
+  const prepared = allRaws.map((r) => ({
+    r,
+    h: idx ? rowsFor(idx, r.relPath) : [],
+    codeRel: parseRelation(list(r.fm.code), 'code'),
+    relatedRel: parseRelation(list(r.fm.related), 'related'),
+  }))
+  if (didx) {
+    const queries: { hash: string; node: string }[] = []
+    for (const { r, h, codeRel, relatedRel } of prepared) {
+      if (!h[0]?.hash || (!codeRel.entries.length && !relatedRel.entries.some((entry) => !entry.selectors.length))) continue
+      queries.push({ hash: h[0].hash, node: r.id })
+    }
+    primeAncestorClosures(didx, queries.map(({ hash }) => hash))
+    // Only an ack named for this node and outside its version's ancestry becomes a cover. Discover that
+    // exact roster from the now-primed bases instead of retaining closures for older, non-covering acks.
+    const covers: string[] = []
+    for (const [hash, nodes] of didx.acks) if (queries.some(({ hash: baseHash, node }) => {
+      const base = ancestorsOf(didx, baseHash)
+      return !!base && nodes.has(node) && !inAncestors(didx, base, hash)
+    })) covers.push(hash)
+    primeAncestorClosures(didx, covers)
+  }
+  const loaded = []
+  for (const { r, h, codeRel, relatedRel } of prepared) {
+    // 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)
+    // a code:/related: row may pin symbols (`path#fn` — [[code-anchor]]): parseRelation groups each
+    // relation per BASE path, so `code`/`related` carry the distinct PATHS (what every path consumer —
+    // drift, claims, eval attribution — expects, file-level as before), the scoped entries (path +
+    // selectors) ride separately for lint's anchor engine, and structural problems (duplicates,
+    // bare/scoped mixing, glob selectors, the code cap) surface as lint integrity errors.
+    const codeEntries = codeRel.entries
+    const code = codeEntries.map((e) => e.path)
+    const codeScoped = codeEntries.filter((e) => e.selectors.length > 0)
+    const relatedEntries = relatedRel.entries
+    const related = relatedEntries.map((e) => e.path)
+    const relatedScoped = relatedEntries.filter((e) => e.selectors.length > 0)
+    const relationProblems = [...codeRel.problems, ...relatedRel.problems]
+    const S = h[0]?.hash || ''
+    const driftFiles = []
+    for (const f of code) {
+      const d = didx ? { file: f, behind: driftFor(didx, S, f, r.id) } : { file: f, behind: 0 }
+      if (d.behind > 0) driftFiles.push(d)
+    }
+    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 eval freshness. It surfaces only as a lint warn nudge.
+    // A SCOPED related entry is excluded here: its file-level movement is silent by design — only a
+    // selector HIT warns, and that verdict needs the anchor engine, so lint derives it, not the loader.
+    const relatedDriftFiles = []
+    for (const e of relatedEntries) {
+      if (e.selectors.length) continue
+      const d = didx ? { file: e.path, behind: driftFor(didx, S, e.path, r.id) } : { file: e.path, behind: 0 }
+      if (d.behind > 0) relatedDriftFiles.push(d)
+    }
+    const fmStatus = str(r.fm.status, '') || null
+    loaded.push({
+      id: r.id,
+      parent: r.parent,
+      path: r.relPath,
+      title: str(r.fm.title, r.id),
+      status: deriveStatus({ version: h.length, drift, hasCode: code.length > 0, fmStatus: fmStatus ?? undefined }),
+      fmStatus,
+      session,
+      hue: Number(str(r.fm.hue, '210')),
+      desc: str(r.fm.desc),
+      code,
+      codeEntries,
+      codeScoped,
+      related,
+      relatedEntries,
+      relatedScoped,
+      relationProblems,
+      version: h.length,
+      reason: h[0]?.reason || '',
+      // ISO date of the node's latest version commit (h is newest-first), or null if unversioned.
+      lastEdited: h[0]?.date || null,
+      drift,
+      driftFiles,
+      relatedDriftFiles,
+      // the latest version's spec.md patch is NOT precomputed here (it cost 2 git show forks per node on
+      // cold load); the history tab fetches it lazily via specDiffAt. See [[work-pane]].
+      body: r.body.trim(),
+      parts: parseParts(r.body),
+    })
+  }
+  return loaded
+}
+
+// per-node version timeline; each row sums the node's spec.md stat (rename-followed, read on demand) and its
+// governed-code stat (pathsStats) — separate because spec.md needs rename-following a plain `git log -- path` can't do.
+export async function specHistory(id: string) {
+  const node = raws().find((r) => r.id === id)
+  if (!node) return []
+  const codePaths = [...new Set(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 = await historyStats(ROOT, idx, node.relPath)
+  return rowsFor(idx, node.relPath).map((v) => {
+    const s = sStats.get(v.hash) ?? { additions: 0, deletions: 0, files: 0 }
+    const c = cStats.get(v.hash) ?? { additions: 0, deletions: 0, files: 0 }
+    return { ...v, additions: s.additions + c.additions, deletions: s.deletions + c.deletions, files: s.files + c.files }
+  })
+}
+
+// the line-diff a specific version introduced to a node's spec.md, by hash; fetched lazily when a history
+// item expands. fileDiffAt resolves the spec.md path AT that commit (reparents). `{hash:'',patch:''}` for
+// an empty hash, null for an unknown id.
+export async function specDiffAt(id: string, hash: string) {
+  const node = raws().find((r) => r.id === id)
+  if (!node) return null
+  if (!hash) return { hash: '', patch: '' }
+  return latestDiff(node.relPath, hash)
+}
+
+// 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`
+// (repo-relative) and its `files` (co-located paths, spec.md excluded) alongside name/title/desc/kind/body.
+// `kind` ∈ mutating|report tells the launcher whether the preset edits the graph or only reports on it.
+// `events`/`order`/`block` are populated only for the `hook` surface (empty/0/false otherwise): which
+// 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 spec node at ANY depth under a plugin root that carries a
+// `surface: system|command|hook|skill|agent|review` 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 (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 .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 {
+  if (!existsSync(SPEC_DIR)) return null
+  for (const e of readdirSync(SPEC_DIR, { withFileTypes: true })) {
+    if (e.isDirectory() && existsSync(join(SPEC_DIR, e.name, 'spec.md'))) return e.name
+  }
+  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 []
+  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[] {
+  const out: string[] = []
+  const walk = (d: string) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name !== 'spec.md') out.push(relative(ROOT, p))
+    }
+  }
+  walk(dir)
+  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: 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' | 'review'): ConfigPreset[] {
+  const out: ConfigPreset[] = []
+  const visit = (nodeDir: string, name: string) => {
+    if (existsSync(join(nodeDir, 'spec.md'))) {
+      const { fm, body } = parseFrontmatter(readFileSync(join(nodeDir, 'spec.md'), 'utf8'))
+      // @@@ skip pending - a `status: pending` plugin is DECLARED INTENT, not yet active. It renders on the
+      // board (via loadSpecs) but must NOT gather: neither a command preset, nor folded into a system prompt,
+      // nor a live hook. Only built/active plugins surface here, so pending stubs stay inert.
+      // the surface field may name SEVERAL surfaces (comma-separated or a YAML list) — the node plugs
+      // into every one it lists, so the match is membership, not equality.
+      const surfaces = list(fm.surface).flatMap((v) => String(v).split(',')).map((v) => v.trim()).filter(Boolean)
+      if (surfaces.includes(surface) && str(fm.status) !== 'pending') {
+        out.push({
+          name,
+          title: str(fm.title, name),
+          desc: str(fm.desc),
+          kind: str(fm.kind, 'mutating'),
+          dir: relative(ROOT, nodeDir),
+          files: bundleFiles(nodeDir),
+          body: body.trim(),
+          events: list(fm.events),
+          order: Number(str(fm.order, '0')) || 0,
+          block: str(fm.block) === 'true',
+          tools: list(fm.tools),
+        })
+      }
+    }
+    for (const e of readdirSync(nodeDir, { withFileTypes: true })) {
+      if (e.isDirectory()) visit(join(nodeDir, e.name), e.name)
+    }
+  }
+  for (const root of configRoots()) {
+    if (!existsSync(root)) continue
+    for (const e of readdirSync(root, { withFileTypes: true })) {
+      if (e.isDirectory()) visit(join(root, e.name), e.name)
+    }
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name))
+}
+export function loadConfig(): ConfigPreset[] { return loadSurface('command') }
+export function loadSystemConfig(): ConfigPreset[] { return loadSurface('system') }
+// the hook handlers (compiled into the per-session hook manifest the dispatcher reads). Each carries its
+// `events`/`order`/`block` binding + co-located script `files`.
+export function loadHookConfig(): ConfigPreset[] { return loadSurface('hook') }
+// the skill bundles (materialized into each harness's auto-discovered SKILL.md dir). Each node's `desc` is the
+// load-trigger and its `body` is the on-demand instructions; loadSurface passes the folder basename as `name`.
+export function loadSkillConfig(): ConfigPreset[] { return loadSurface('skill') }
+// the sub-agent definitions (materialized into each harness's auto-discovered agent dir, e.g. claude's
+// .claude/agents/<name>.md). Like a skill, the node's `desc` is the on-demand load-trigger and its `body` is the
+// agent's system prompt; additionally its `tools` field is the harness tool allowlist for the spawned agent.
+export function loadAgentConfig(): ConfigPreset[] { return loadSurface('agent') }
+// the review-track prose presets ([[review-commands]]): offered in the eval detail's remark-composer `/`
+// dropdown; picking one PREFILLS the composer with the node's `body` ({node}/{scenario}/{expected}
+// placeholders filled at insert time). Display+prefill only — the send stays the ordinary remark write.
+export function loadReviewConfig(): ConfigPreset[] { return loadSurface('review') }

package/templates/spexcode.json

@@ -0,0 +1,33 @@
+{
+  "lint": {
+    "governedRoots": ["."]
+  },
+  "dashboard": {
+    "showHeadlessLaunchers": false
+  },
+  "uploads": {
+    "maxBytes": 2147483648,
+    "chunkBytes": 8388608,
+    "concurrency": 1,
+    "requestTimeoutMs": 120000,
+    "retryLimit": 2,
+    "retryDelayMs": 500,
+    "incompleteTtlMs": 86400000,
+    "cleanupIntervalMs": 3600000,
+    "minFreeBytes": 268435456,
+    "evidenceMaxBytes": 52428800
+  },
+  "sessions": {
+    "launchers": {
+      "claude": { "harness": "claude", "cmd": "claude" },
+      "claude-headless": { "harness": "claude-headless", "cmd": "claude" },
+      "codex": { "harness": "codex", "cmd": "codex" },
+      "codex-headless": { "harness": "codex-headless", "cmd": "codex --yolo" },
+      "opencode": { "harness": "opencode", "cmd": "opencode" },
+      "opencode-headless": { "harness": "opencode-headless", "cmd": "opencode --auto" },
+      "pi": { "harness": "pi", "cmd": "pi" },
+      "pi-headless": { "harness": "pi-headless", "cmd": "pi" }
+    },
+    "defaultLauncher": "claude"
+  }
+}