spexcode 0.3.0 → 0.4.1

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, parseRelation } 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.
@@ -171,17 +172,21 @@ function claimMatcher(file: string): (cf: string) => boolean {
 }
 
 // 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 }[] {
+// 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().filter((r) => list(r.fm.code).some(claims)).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
+  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(claims)).map((r) => ({ id: r.id, desc: str(r.fm.desc) }))
+  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
@@ -226,8 +231,18 @@ 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)
-    const related = list(r.fm.related)
+    // 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 codeRel = parseRelation(list(r.fm.code), 'code')
+    const relatedRel = parseRelation(list(r.fm.related), 'related')
+    const code = codeRel.entries.map((e) => e.path)
+    const codeScoped = codeRel.entries.filter((e) => e.selectors.length > 0)
+    const related = relatedRel.entries.map((e) => e.path)
+    const relatedScoped = relatedRel.entries.filter((e) => e.selectors.length > 0)
+    const relationProblems = [...codeRel.problems, ...relatedRel.problems]
     const S = h[0]?.hash || ''
     const driftFiles = code
       .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
@@ -235,8 +250,10 @@ export async function loadSpecs() {
     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.
-    const relatedDriftFiles = related
-      .map((f) => ({ file: f, behind: driftFor(didx, S, f) }))
+    // 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 = relatedRel.entries.filter((e) => !e.selectors.length)
+      .map((e) => ({ file: e.path, behind: driftFor(didx, S, e.path) }))
       .filter((d) => d.behind > 0)
     const fmStatus = str(r.fm.status, '') || null
     return {
@@ -250,7 +267,10 @@ export async function loadSpecs() {
       hue: Number(str(r.fm.hue, '210')),
       desc: str(r.fm.desc),
       code,
+      codeScoped,
       related,
+      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.
@@ -271,7 +291,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 = [...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 = statsFor(idx, node.relPath)
@@ -302,11 +322,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|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 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,14 +374,13 @@ 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.
-function loadSurface(surface: 'command' | 'system' | 'hook' | 'skill' | 'agent'): ConfigPreset[] {
+// `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'))) {
@@ -412,3 +431,7 @@ export function loadSkillConfig(): ConfigPreset[] { return loadSurface('skill')
 // .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/spec-cli/templates/hooks/prepare-commit-msg

@@ -26,7 +26,12 @@ if [ -z "$sid" ] && [ -n "${CODEX_THREAD_ID:-}" ]; then # codex: alias the threa
     if [ -e "$rd/sessions/$CODEX_THREAD_ID/session.json" ]; then
       sid="$CODEX_THREAD_ID"                             # a governed record keyed by the thread id (rare/direct)
     else                                                 # else the record that captured it as harness_session_id
-      hit=$(grep -lF "\"harness_session_id\": \"$CODEX_THREAD_ID\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
+      # @@@ unmatched-is-noop - grep's no-match (exit 1) and an absent sessions glob (exit 2) are the
+      # NOT-GOVERNED case, not an error: any repo inherits a foreign CODEX_THREAD_ID from a codex session's
+      # shell, and under `set -euo pipefail` a bare grep|head assignment would abort the hook — and the
+      # commit — before the intended `[ -z "$sid" ] && exit 0` no-op. Genuine errors past this lookup
+      # (interpret-trailers etc.) still fail loud via set -e.
+      hit=$(grep -lF "\"harness_session_id\": \"$CODEX_THREAD_ID\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1) || hit=""
       [ -n "$hit" ] && sid=$(basename "$(dirname "$hit")")
     fi
   fi

package/spec-cli/templates/spec/project/.plugins/{extract → commands/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/commands/spec.md

@@ -0,0 +1,16 @@
+---
+title: commands
+status: active
+hue: 40
+desc: Grouping shelf for the `surface: command` plugins — the `/`-dropdown launch presets a new session can pick. A shelf, not a surface — routing stays field-driven.
+---
+# commands
+
+The invocable **command** plugins live here: leaf plugins whose body is a launch preset a new session
+picks from the `/` dropdown, each carrying `surface: command`. Grouping them keeps `.plugins/` legible at
+a glance — the command presets on this shelf, the skill plugins on `skills/`, the auxiliary system
+contracts on `prompts/`, with `core` a flat child beside them.
+
+This node is a **shelf, not a surface**: it declares no `surface` field and gathers nothing itself.
+Discovery is recursive and field-driven, so a resident plugs in exactly as it would at the root — a
+plugin that serves both surfaces shelves once by its primary identity, never duplicated.

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

@@ -0,0 +1,8 @@
+---
+title: supervisor
+surface: command
+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 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/.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/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/skills/spec.md

@@ -0,0 +1,17 @@
+---
+title: skills
+status: active
+hue: 280
+desc: Grouping shelf for the `surface: skill` plugins — the harness skills an agent invokes on demand. A shelf, not a surface — routing stays field-driven.
+---
+# skills
+
+The invocable **skill** plugins live here: leaf plugins that materialize into the harness's skill dir,
+where an agent invokes them on demand, each carrying `surface: skill`. Grouping them keeps `.plugins/`
+legible at a glance — the skill plugins on this shelf, the command presets on `commands/`, the auxiliary
+system contracts on `prompts/`, with `core` a flat child beside them.
+
+This node is a **shelf, not a surface**: it declares no `surface` field and gathers nothing itself.
+Discovery is recursive and field-driven, so a resident plugs in exactly as it would at the root. A plugin
+that serves both surfaces shelves here by its primary (skill) identity and still gathers as a command
+through its field.

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/`, the `surface: command` presets under
+`commands/`, the `surface: skill` plugins under `skills/`, while `core` — the contract subsystem whose
+children are the `surface: hook` gates — sits as a flat child here.
 
 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/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