spexcode 0.4.0 → 0.4.1

package/spec-cli/src/specs.ts

@@ -2,7 +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'
+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()
@@ -172,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((e) => claims(parseCodeEntry(e).path))).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
@@ -227,12 +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)
-    // 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)
+    // 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) }))
@@ -240,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 {
@@ -255,8 +267,10 @@ export async function loadSpecs() {
       hue: Number(str(r.fm.hue, '210')),
       desc: str(r.fm.desc),
       code,
-      anchors,
+      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.
@@ -277,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).map((e) => parseCodeEntry(e).path)
+  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)
@@ -309,7 +323,7 @@ export async function specDiffAt(id: string, hash: string) {
 // 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` frontmatter field naming where it plugs in. There are no
+// `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
@@ -366,7 +380,7 @@ function bundleFiles(dir: string): string[] {
 // 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[] {
+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'))) {
@@ -417,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/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/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

@@ -8,9 +8,9 @@ desc: The instance home — this repo's DIY dev-flow plugins live here as skill-
 working in it. Each plugin is a skill-shaped node — its folder *is* the unit (a `spec.md` plus any
 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.
+`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`