spexcode 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "SpexCode — a spec-driven, self-developing dev tool. The `spex` CLI + spec server reads the .spec tree and its git history, and serves the dashboard.",
   "license": "MIT",

package/spec-cli/src/anchors.ts

@@ -0,0 +1,341 @@
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+import { gitA, type DriftIndex, ancestorsOf, inAncestors, ackCoverFor } from './git.js'
+
+// ---- the anchor vocabulary ([[code-anchor]]) ----
+// A spec's `code:` entry may pin ONE named unit: `path#symbol` (`#Class.method` for a class method).
+// Everything below the entry parse splits into two layers:
+//   - the LANGUAGE SEAM: pure extractors (content, filename) -> Unit[] — no git, no cache, no fs.
+//     Each extension maps to exactly ONE designated extractor; there is NO cross-tier fallback.
+//   - the LANGUAGE-AGNOSTIC ENGINE: blob-oid memo, anchor resolution (dead/ambiguous), diff-hunk ∩
+//     unit-range intersection over the drift window. It never knows which language it is measuring.
+
+export type Unit = { name: string; kind: string; start: number; end: number; typeOnly?: boolean }
+
+export type Extractor = {
+  id: string
+  claims(ext: string): boolean
+  // true = usable here. A string is WHY it cannot run — lint turns that into an ERROR with the repair
+  // entrypoint (never a silent or degraded pass): the designated extractor either runs or the anchor
+  // is unverifiable.
+  ready(): true | string
+  // PURE function of its arguments (importable by an external benchmark/scorer as-is). Throws when the
+  // content cannot be parsed — the caller maps that to a conservative verdict, never a silent skip.
+  extract(content: string, filename: string): Unit[]
+}
+
+export type CodeEntry = { path: string; anchor: string | null }
+export function parseCodeEntry(raw: string): CodeEntry {
+  const i = raw.indexOf('#')
+  if (i < 0) return { path: raw.trim(), anchor: null }
+  return { path: raw.slice(0, i).trim(), anchor: raw.slice(i + 1).trim() || null }
+}
+
+// ---- relation parsing: ONE structured path+selector grammar for code: AND related: ----
+// A relation's raw rows group per base path: a row is bare (`path`, whole-file — today's semantics,
+// unchanged) or scoped (`path#symbol`), and any number of scoped rows on the SAME base file fold into
+// one entry whose selectors are OR'd (a commit hitting any counts once; no selector-count cap — the
+// benchmark roster's 1–3 was an annotation rubric, never product syntax). STRUCTURAL verdicts live
+// here, pure and loud: an exact duplicate row, mixing bare with selectors on one base path, and a
+// selector on a glob are all `problems` the caller turns into integrity errors. Filesystem/git
+// verdicts (existence, directories, dead/ambiguous units, extractor readiness) stay the caller's —
+// this parser never touches fs.
+export type RelationEntry = { path: string; selectors: string[] }
+export type RelationParse = { entries: RelationEntry[]; problems: string[] }
+export function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse {
+  const order: string[] = []
+  const byPath = new Map<string, { bare: boolean; selectors: string[] }>()
+  const problems: string[] = []
+  for (const raw of raws) {
+    const { path, anchor } = parseCodeEntry(raw)
+    let e = byPath.get(path)
+    if (!e) { e = { bare: false, selectors: [] }; byPath.set(path, e); order.push(path) }
+    if (anchor === null) {
+      if (e.bare) problems.push(`${relation}: lists '${path}' twice — drop the duplicate entry`)
+      e.bare = true
+    } else if (e.selectors.includes(anchor)) {
+      problems.push(`${relation}: lists selector '${path}#${anchor}' twice — drop the duplicate`)
+    } else e.selectors.push(anchor)
+  }
+  for (const path of order) {
+    const e = byPath.get(path)!
+    if (e.bare && e.selectors.length)
+      problems.push(`${relation}: mixes bare '${path}' with '${path}#…' selectors — one base path is either whole-file or selector-scoped, never both; drop one form`)
+    if (e.selectors.length && path.includes('*'))
+      problems.push(`${relation}: '${path}#${e.selectors[0]}' puts a selector on a glob — a selector scopes ONE real file`)
+  }
+  return { entries: order.map((p) => ({ path: p, selectors: byPath.get(p)!.selectors })), problems }
+}
+
+// ---- extractor: ts-ast (the designated extractor for the JS family) ----
+// Parse-only via the HOST project's own typescript (resolved from the repo root, walking up like any
+// require) — never a bundled copy, so the parse matches what the project itself compiles with. Not
+// resolvable => ready() returns the repair entrypoint and lint ERRORS (no regex fallback for JS).
+const JS_EXTS = new Set(['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs', 'mts', 'cts'])
+
+export function tsAstExtractor(root: string): Extractor {
+  let ts: any | null | undefined // undefined = unprobed; null = unresolvable
+  let readiness: true | string | undefined
+  const probe = () => {
+    if (ts !== undefined) return
+    try { ts = createRequire(join(root, 'package.json'))('typescript') } catch { ts = null }
+  }
+  return {
+    id: 'ts-ast',
+    claims: (ext) => JS_EXTS.has(ext),
+    ready() {
+      if (readiness !== undefined) return readiness
+      probe()
+      if (!ts) return (readiness = `typescript is not resolvable from ${root} — anchors on JS-family files need the host project's typescript: run 'npm i -D typescript', or remove the #anchor`)
+      // resolvability is not usability: typescript@7 (the Go rewrite) may resolve yet not expose the JS
+      // compiler API this extractor drives. Probe the ACTUAL surface with a tiny parse — an incompatible
+      // host typescript is a loud error, never a silent pass or downgrade.
+      try {
+        const sf = ts.createSourceFile('probe.ts', 'const x = 1', ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+        if (!sf?.statements?.length || sf.parseDiagnostics?.length) throw new Error('probe parse failed')
+        readiness = true
+      } catch {
+        readiness = `host typescript (v${ts?.version ?? 'unknown'}) resolves but its createSourceFile API is unusable (a TS7/Go build?) — pin 'npm i -D typescript@5', or remove the #anchor`
+      }
+      return readiness
+    },
+    extract(content, filename) {
+      probe()
+      if (!ts) throw new Error('ts-ast extractor is not ready (typescript unresolvable)')
+      const kind = /\.(tsx)$/.test(filename) ? ts.ScriptKind.TSX
+        : /\.(jsx)$/.test(filename) ? ts.ScriptKind.JSX
+        : /\.(ts|mts|cts)$/.test(filename) ? ts.ScriptKind.TS
+        : ts.ScriptKind.JS
+      const sf = ts.createSourceFile(filename, content, ts.ScriptTarget.Latest, true, kind)
+      // parse-only gate: a file that does not parse yields GARBAGE units (a shell script's `x=$(...)`
+      // parses as a const) — throw so the caller renders an honest "cannot parse" verdict instead.
+      if (sf.parseDiagnostics?.length) throw new Error(`${filename} does not parse as ${ts.ScriptKind[kind]} (${sf.parseDiagnostics.length} syntax error(s))`)
+      const line = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1
+      const units: Unit[] = []
+      const push = (name: string, ukind: string, node: any, typeOnly = false) =>
+        units.push({ name, kind: ukind, start: line(node.getStart(sf)), end: line(node.end), ...(typeOnly ? { typeOnly } : {}) })
+      for (const st of sf.statements) {
+        if (ts.isFunctionDeclaration(st)) push(st.name ? st.name.text : '(default)', 'function', st)
+        else if (ts.isClassDeclaration(st)) {
+          const cname = st.name ? st.name.text : '(default)'
+          push(cname, 'class', st)
+          for (const m of st.members) {
+            if ((ts.isMethodDeclaration(m) || ts.isConstructorDeclaration(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) && m.body) {
+              const mname = ts.isConstructorDeclaration(m) ? 'constructor' : (m.name && ts.isIdentifier(m.name) ? m.name.text : '(computed)')
+              push(`${cname}.${mname}`, 'method', m)
+            }
+          }
+        } else if (ts.isVariableStatement(st)) {
+          for (const d of st.declarationList.declarations) {
+            if (!ts.isIdentifier(d.name)) continue // destructuring — not anchorable by one name
+            const fn = d.initializer && (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))
+            // range = the whole statement (multi-declarator lines co-move; each name shares the range)
+            units.push({ name: d.name.text, kind: fn ? 'const-fn' : 'const-data', start: line(st.getStart(sf)), end: line(st.end) })
+          }
+        } else if (ts.isEnumDeclaration(st)) push(st.name.text, 'enum', st)
+        else if (ts.isInterfaceDeclaration(st)) push(st.name.text, 'interface', st, true)
+        else if (ts.isTypeAliasDeclaration(st)) push(st.name.text, 'type', st, true)
+      }
+      return units
+    },
+  }
+}
+
+// ---- extractor: heuristic(langSpec) — a generic regex engine fed LANGUAGE DATA, not language branches ----
+// The designated extractor for languages described by a LangSpec row; adding a language = adding a data
+// row + a registry entry (never a new engine). The JS family is deliberately NOT routed here (its
+// designated extractor is ts-ast above); JS_LANG_R5B below exists as the validated reference row for the
+// engine's shape and for the external benchmark to score.
+export type LangSpec = {
+  id: string
+  extensions: string[]
+  // column-0 declaration patterns; capture group 1 = the unit name (or the declarator list when declList)
+  decls: { re: RegExp; kind: string; typeOnly?: boolean; classOpener?: boolean; declList?: boolean }[]
+  // class-member pattern, active while inside a classOpener's balanced-bracket body (name -> Class.name)
+  member?: { re: RegExp; blacklist?: RegExp }
+  // a column-0 line matching this ENDS the previous unit (comment-aware so trailing comment blocks
+  // attach to the NEXT unit, not the previous one)
+  boundary: RegExp
+}
+
+const balance = (s: string) => { let n = 0; for (const ch of s) { if ('([{'.includes(ch)) n++; else if (')]}'.includes(ch)) n-- } return n }
+// split a declarator-list head on top-level commas: `COLS = 220, ROWS = 50` -> [COLS, ROWS]
+function declNames(head: string): string[] {
+  let d = 0, seg = ''
+  const segs: string[] = []
+  for (const ch of head) {
+    if ('([{<'.includes(ch)) d++
+    else if (')]}>'.includes(ch)) d--
+    if (ch === ',' && d === 0) { segs.push(seg); seg = '' } else seg += ch
+  }
+  segs.push(seg)
+  return segs.map((s) => s.match(/^\s*([A-Za-z_$][\w$]*)\s*(?::|=|$)/)?.[1]).filter((x): x is string => !!x)
+}
+
+export function heuristicExtractor(spec: LangSpec): Extractor {
+  return {
+    id: spec.id,
+    claims: (ext) => spec.extensions.includes(ext),
+    ready: () => true,
+    extract(content) {
+      const lines = content.split('\n')
+      const units: Unit[] = []
+      let cls: string | null = null, depth = 0
+      for (let i = 0; i < lines.length; i++) {
+        const l = lines[i]
+        if (cls) {
+          const m = spec.member && l.match(spec.member.re)
+          if (m && !spec.member!.blacklist?.test(m[1])) units.push({ name: `${cls}.${m[1]}`, kind: 'method', start: i + 1, end: i + 1 })
+          depth += balance(l)
+          if (depth <= 0) cls = null
+          continue
+        }
+        for (const d of spec.decls) {
+          const m = l.match(d.re)
+          if (!m) continue
+          for (const name of d.declList ? declNames(m[1]) : [m[1]])
+            units.push({ name, kind: d.kind, start: i + 1, end: i + 1, ...(d.typeOnly ? { typeOnly: true } : {}) })
+          if (d.classOpener) { cls = m[1]; depth = balance(l) }
+          break
+        }
+      }
+      // R5b ranges: a unit ends before the next column-0 boundary line; a method is also capped by the
+      // next unit's start (methods sit inside their class's indentation, below boundary's radar).
+      const bset: number[] = []
+      for (let i = 0; i < lines.length; i++) if (spec.boundary.test(lines[i])) bset.push(i + 1)
+      const starts = units.map((u) => u.start).sort((a, b) => a - b)
+      for (const u of units) {
+        const nb = bset.find((b) => b > u.start)
+        let end = nb ?? lines.length + 1
+        if (u.kind === 'method') { const ns = starts.find((x) => x > u.start); if (ns && ns < end) end = ns }
+        u.end = Math.max(u.start, end - 1)
+      }
+      return units
+    },
+  }
+}
+
+// The validated JS-family reference row (R5b: name precision 99.7% / recall 100% / range 98.9% on the
+// 41-file oracle) — NOT registered for JS (ts-ast is designated); kept as the engine's reference shape
+// and the benchmark's scoring subject.
+export const JS_LANG_R5B: LangSpec = {
+  id: 'heuristic-js',
+  extensions: [...JS_EXTS],
+  decls: [
+    { re: /^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\*?\s+([A-Za-z_$][\w$]*)/, kind: 'function' },
+    { re: /^(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/, kind: 'class', classOpener: true },
+    { re: /^(?:export\s+)?(?:declare\s+)?enum\s+([A-Za-z_$][\w$]*)/, kind: 'enum' },
+    { re: /^(?:export\s+)?(?:declare\s+)?interface\s+([A-Za-z_$][\w$]*)/, kind: 'interface', typeOnly: true },
+    { re: /^(?:export\s+)?(?:declare\s+)?type\s+([A-Za-z_$][\w$]*)/, kind: 'type', typeOnly: true },
+    { re: /^(?:export\s+)?(?:const|let|var)\s+(.+)$/, kind: 'const', declList: true },
+  ],
+  member: {
+    re: /^\s+(?:(?:public|private|protected|static|readonly|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(/,
+    blacklist: /^(if|for|while|switch|return|catch|new|await|typeof|throw|else|do)$/,
+  },
+  boundary: /^(?:[A-Za-z_$]|\/\/|\/\*)/,
+}
+
+// ---- registry: extension -> its ONE designated extractor ----
+// The registry's shape is the Extractor INTERFACE, not any engine: a future language row may be a
+// heuristicExtractor(LangSpec) or a web-tree-sitter extractor carrying its own wasm-grammar/query
+// config — whatever the implementation needs rides inside its own factory, never in the registry.
+export function extractors(root: string): Extractor[] {
+  return [tsAstExtractor(root)]
+}
+// first claiming extractor IS the designation (the registry order defines it); null = no anchor support
+// for this language yet (lint ERRORS — the remedy is a LangSpec data row, or dropping the anchor).
+export function extractorFor(regs: Extractor[], ext: string): Extractor | null {
+  return regs.find((x) => x.claims(ext)) ?? null
+}
+export const extOf = (path: string): string => {
+  const base = path.slice(path.lastIndexOf('/') + 1)
+  const dot = base.lastIndexOf('.')
+  return dot > 0 ? base.slice(dot + 1) : ''
+}
+
+// ---- anchor resolution (language-agnostic) ----
+export type AnchorResolution = { ok: Unit } | { dead: true } | { ambiguous: number }
+export function resolveAnchor(units: Unit[], symbol: string): AnchorResolution {
+  const hits = units.filter((u) => u.name === symbol)
+  if (!hits.length) return { dead: true }
+  if (hits.length > 1) return { ambiguous: hits.length }
+  return { ok: hits[0] }
+}
+
+// ---- the historical hit engine (language-agnostic; batch short-lived git, no resident process) ----
+
+// units of a file AS OF a commit, memoized by (blob oid, extractor id) — a blob is immutable, so the
+// memo never invalidates; distinct file versions in a window are few. 'absent' = no blob at that commit;
+// 'unparseable' = the extractor rejected that version's content (the caller treats it conservatively).
+type BlobUnits = { units: Unit[] } | { absent: true } | { unparseable: string }
+const unitMemo = new Map<string, BlobUnits>()
+const MEMO_MAX = 4096
+async function unitsAt(root: string, commit: string, path: string, x: Extractor): Promise<BlobUnits> {
+  const oid = (await gitA(['-C', root, 'rev-parse', `${commit}:${path}`])).trim()
+  if (!oid) return { absent: true }
+  const key = `${oid}\0${x.id}`
+  const hit = unitMemo.get(key)
+  if (hit) return hit
+  const text = await gitA(['-C', root, 'cat-file', 'blob', oid])
+  let v: BlobUnits
+  try { v = { units: x.extract(text, path) } } catch (e: any) { v = { unparseable: e?.message ?? String(e) } }
+  if (unitMemo.size >= MEMO_MAX) unitMemo.clear()
+  unitMemo.set(key, v)
+  return v
+}
+
+// post-image line ranges of one commit's diff to one file (`@@ -a,b +c,d @@`, --unified=0). d>0 → lines
+// c..c+d-1 changed; d==0 (pure deletion) → the point line after which content vanished. Immutable per
+// (commit, file), memoized.
+const hunkMemo = new Map<string, [number, number][]>()
+async function hunksAt(root: string, commit: string, path: string): Promise<[number, number][]> {
+  const key = `${commit}\0${path}`
+  const hit = hunkMemo.get(key)
+  if (hit) return hit
+  const out = await gitA(['-C', root, '-c', 'core.quotePath=false', 'show', '--unified=0', '--format=', commit, '--', path])
+  const ranges: [number, number][] = []
+  for (const m of out.matchAll(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/gm)) {
+    const c = +m[1], d = m[2] === undefined ? 1 : +m[2]
+    ranges.push(d > 0 ? [c, c + d - 1] : [Math.max(1, c), Math.max(1, c)])
+  }
+  if (hunkMemo.size >= MEMO_MAX) hunkMemo.clear()
+  hunkMemo.set(key, ranges)
+  return ranges
+}
+
+// the drift window of an anchored file: every commit to `path` not reachable from the spec's version
+// and not covered by a valid Spec-OK ack — the SAME set driftFor counts, exposed as commits so the
+// anchor engine can probe each one. (fileCommits comes from a --name-only walk, which lists no files
+// for merge commits — the window is non-merge by construction.)
+export function windowCommits(idx: DriftIndex, sinceHash: string, path: string): string[] {
+  if (!sinceHash) return []
+  const base = ancestorsOf(idx, sinceHash)
+  if (!base) return []
+  const cover = ackCoverFor(idx, sinceHash)
+  return (idx.fileCommits.get(path) ?? []).filter((h) => !inAncestors(idx, base, h) && !cover.some((a) => inAncestors(idx, a, h)))
+}
+
+// which window commits TOUCHED any of the anchored units: the commit's --unified=0 hunks intersect a
+// unit's line range extracted from the file AS IT EXISTED AT THAT COMMIT (never from HEAD — units later
+// renamed or moved still attribute correctly). Several selectors are OR — a commit appears ONCE, with
+// `selectors` naming exactly which units its hunks intersected (so diagnostics can attribute the hit).
+// A version whose content the extractor cannot parse is a CONSERVATIVE hit for every selector
+// (`unparseable` set) — over-warn, never silently skip.
+export type AnchorHit = { commit: string; selectors: string[]; unparseable?: string }
+export async function anchorHitCommits(root: string, win: string[], path: string, symbols: string[], x: Extractor): Promise<AnchorHit[]> {
+  const hits: AnchorHit[] = []
+  for (const c of win) {
+    const at = await unitsAt(root, c, path, x)
+    if ('absent' in at) continue // file not in that commit's tree — nothing of the anchor to touch
+    if ('unparseable' in at) { hits.push({ commit: c, selectors: [...symbols], unparseable: at.unparseable }); continue }
+    const bySym = symbols
+      .map((sym) => ({ sym, ranges: at.units.filter((u) => u.name === sym) }))
+      .filter((s) => s.ranges.length) // a unit absent under this name at that commit can't be touched
+    if (!bySym.length) continue
+    const hunks = await hunksAt(root, c, path)
+    const touched = bySym.filter((s) => hunks.some(([a, b]) => s.ranges.some((u) => a <= u.end && u.start <= b))).map((s) => s.sym)
+    if (touched.length) hits.push({ commit: c, selectors: touched })
+  }
+  return hits
+}

package/spec-cli/src/cli.ts

@@ -404,7 +404,11 @@ if (cmd === 'serve') {
     const owners = specOwners(p)
     const related = specRelated(p)
     const maxOwners = loadConfig(process.cwd()).maxOwners
-    const names = (xs: { id: string }[]) => xs.map((o) => `'${o.id}'`).join(', ')
+    // a selector-SCOPED governor (every claiming code: entry carries `#symbol` — [[code-anchor]]) still
+    // DISPLAYS, marked, but does not count toward the too-many-owners bound: it claims named units, not
+    // the whole file.
+    const whole = owners.filter((o) => !o.scoped)
+    const names = (xs: { id: string; scoped?: boolean }[]) => xs.map((o) => `'${o.id}'${o.scoped ? ' (scoped)' : ''}`).join(', ')
     const relLine = related.length ? `\n  also referenced by ${names(related)} (related: coverage only — no drift, no eval freshness)` : ''
     if (owners.length === 0 && related.length === 0) {
       console.log(`${rel} — no spec claims this yet (uncovered). If your change is substantive, give it a home before it drifts.`)
@@ -413,32 +417,28 @@ if (cmd === 'serve') {
       // but a human asking gets the honest nuance: nothing tracks this file's drift.
       if (has('actionable')) process.exit(0)
       console.log(`${rel} — not governed (no code: claim), but referenced by ${names(related)} (related: coverage only). Nothing tracks its drift; if your change is substantive, consider giving it a governing home.`)
-    } else if (owners.length <= maxOwners) {
+    } else if (whole.length <= maxOwners) {
       // a sanely-owned file is NOT actionable: --actionable callers (the per-edit spec-of-file hook) stay
       // silent here, so the annotation fires only on an OVER-owned or uncovered file — rare and worth acting on.
       if (has('actionable')) process.exit(0)
-      const named = owners.map((o) => `'${o.id}'`).join(', ')
+      const named = names(owners)
       const lead = owners.length === 1 ? `${rel} is governed by ${named} — ${owners[0].desc}` : `${rel} is governed by ${named} (shared, fine).`
       console.log(`${lead} Read/honor the spec; if your change shifts the intent, update the spec in the SAME commit.${relLine}`)
     } else {
-      const ids = owners.map((o) => o.id).join(', ')
-      console.log(`${rel} is governed by ${owners.length} specs (${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
+      const ids = names(owners)
+      console.log(`${rel} is governed whole-file by ${whole.length} specs (all claims: ${ids}) — more than one file should hold. This file does TOO MUCH: SPLIT it so each governor owns its own module (or merge the nodes if they're one concern, or give it a single foundation owner + relate the rest).${relLine}`)
     }
   } else if (sub === 'lint') {
-    const { specLint, driftGate, DRIFT_GUIDANCE } = await import('./lint.js')
+    const { specLint, DRIFT_GUIDANCE } = await import('./lint.js')
     const findings = await specLint()
     const errors = findings.filter((f) => f.level === 'error')
     for (const f of findings) console.error(`  ${f.level === 'error' ? '✗' : '•'} ${f.rule}: ${f.msg}`)
     console.error(`spex spec lint: ${errors.length} error(s), ${findings.length - errors.length} warning(s)`)
-    // drift teaches + gates from the ONE `spex spec lint` (no flag): print the remediation guidance wherever
-    // drift exists, then apply the commit-local gate — which reads the staged index itself, so it only
-    // blocks an in-flight commit that touches an already heavily-drifted node. CI/manual (nothing staged)
-    // stays advisory, per the ci-gate contract.
-    const { blocked, touched, threshold } = await driftGate()
-    if (findings.some((f) => f.rule === 'drift') || touched.length) console.error(`\n${DRIFT_GUIDANCE}`)
-    for (const t of touched) console.error(`  ${t.drift >= threshold ? '✗' : '•'} drift-gate: '${t.id}' is ${t.drift} behind${t.drift >= threshold ? ' — BLOCKS this commit' : ' (advisory)'}`)
-    if (blocked.length) console.error(`\n✗ SpexCode: ${blocked.join(', ')} ${blocked.length === 1 ? 'is' : 'are'} ≥ ${threshold} commit(s) behind. Reconcile (above) or bypass with SPEXCODE_SKIP_LINT=1.`)
-    process.exit(errors.length || blocked.length ? 1 : 0)
+    // drift teaches from the ONE `spex spec lint` (no flag). Unanchored drift stays advisory forever; the
+    // blocking tier is anchor-drift ([[code-anchor]]) — an ERROR like any other, so the pre-commit shim
+    // (and CI) gates on it with no separate staged-index machinery.
+    if (findings.some((f) => f.rule === 'drift' || f.rule === 'anchor-drift')) console.error(`\n${DRIFT_GUIDANCE}`)
+    process.exit(errors.length ? 1 : 0)
   } else if (sub === 'ack') {
     // An EMPTY stamp commit on top of HEAD, never an amend: driftFor (git.ts) quiets every drift commit
     // REACHABLE from an ack, so a child stamp covers exactly what amending HEAD would — and it works where
@@ -451,13 +451,13 @@ if (cmd === 'serve') {
     const reason = (flag('reason') ?? '').trim()
     if (!nodes.length || !reason) {
       console.error('usage: spex spec ack <node-id>… --reason "<why this change keeps each spec valid>"')
-      console.error('  --reason is required (it forces you to check before acking) and is NOT stored — git keeps only the Spec-OK trailer.')
+      console.error('  --reason is required (it forces you to check before acking) and is recorded in the ack commit\'s message body — an ack that quiets an anchor hit is a strong claim, so its why must be durable.')
       process.exit(2)
     }
     try {
-      git(['commit', '--only', '--allow-empty', '-m', `ack: Spec-OK ${nodes.join(', ')}`,
+      git(['commit', '--only', '--allow-empty', '-m', `ack: Spec-OK ${nodes.join(', ')}`, '-m', reason,
         ...nodes.flatMap((n) => ['--trailer', `Spec-OK: ${n}`])])
-      console.log(`Spec-OK: ${nodes.join(', ')} → ${git(['rev-parse', '--short', 'HEAD']).trim()}  (empty stamp commit; reason required, not stored)`)
+      console.log(`Spec-OK: ${nodes.join(', ')} → ${git(['rev-parse', '--short', 'HEAD']).trim()}  (empty stamp commit; reason recorded in the commit body)`)
     } catch (e: any) {
       console.error(`ack failed: ${e?.message ?? e}`); process.exit(1)
     }
@@ -527,12 +527,12 @@ if (cmd === 'serve') {
       if (!n.hasEvalFile && !n.uncoveredFrontend) console.log('      (no eval.md — nothing declared to measure)')
       else if (n.hasEvalFile && !n.scenarios.length) console.log('      (eval.md declares no scenarios)')
     }
-  } else if (['add', 'ls', 'scenario', 'lint', 'retract', 'clean'].includes(sub)) {
+  } else if (['add', 'ls', 'scenario', 'lint', 'ok', 'retract', 'clean'].includes(sub)) {
     // node-scoped verbs — thin route; the logic lives in spec-eval.
     const { runEval } = await import('../../spec-eval/src/cli.js')
     await flushExit(await runEval(process.argv.slice(3)))
   } else {
-    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | lint | retract | clean  (spex help eval)`)
+    console.error(`spex eval: unknown verb '${sub}' — add | ls | scenario ls | lint | ok | retract | clean  (spex help eval)`)
     if (!sub.startsWith('--')) console.error(`  (the old \`spex eval <SEL>\` session read is now \`spex eval ls --session <SEL>\` [--export])`) // dead-words-ok: signpost — one-version tombstone teaching the renamed spelling (0.4.0 removes it)
     process.exit(2)
   }

package/spec-cli/src/gateway.ts

@@ -243,7 +243,14 @@ function serveStatic(req: http.IncomingMessage, res: http.ServerResponse, distDi
   const rel = normalize(decodeURIComponent(urlPath)).replace(/^(\.\.[/\\])+/, '')
   let file = join(distDir, rel)
   if (!file.startsWith(distDir)) file = join(distDir, 'index.html')
-  if (urlPath === '/' || !existsSync(file)) file = join(distDir, 'index.html')
+  if (urlPath === '/' || !existsSync(file)) {
+    // @@@ missing-asset 404 - only extensionless SPA routes fall back to index.html. A missing FILE
+    // request (it has an extension) is a stale hashed chunk from a pre-rebuild page still open in some
+    // browser: answering it with HTML trips the strict module-MIME check and hides the miss from the
+    // client — 404 instead, so the shell's vite:preloadError recovery can see it and reload.
+    if (urlPath !== '/' && extname(file)) { res.writeHead(404, { 'Content-Type': 'text/plain' }); return res.end('not found') }
+    file = join(distDir, 'index.html')
+  }
   if (!existsSync(file)) { res.writeHead(503); return res.end('dashboard build missing') }
   const type = MIME[extname(file)] || 'application/octet-stream'
   const raw = readFileSync(file)

package/spec-cli/src/git.ts

@@ -366,28 +366,36 @@ export function inAncestors(idx: DriftIndex, bits: Uint8Array, sha: string): boo
   return o !== undefined && (bits[o >> 3] & (1 << (o & 7))) !== 0
 }
 
-// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
-// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
-//
-// `sinceHash` is the node's OWN latest version commit, so the node(s) it's a version of
-// (specNodes[sinceHash]) name the node being measured; an ack counts only if its `Spec-OK:` set names
-// one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that is itself an ancestor of the
-// version can't speak for it (a re-version invalidates older acks); a valid ack quiets exactly the
-// commits reachable from it. An off-history `sinceHash` → 0: no basis on HEAD to measure from.
-export function driftFor(idx: DriftIndex, sinceHash: string, path: string): number {
-  if (!sinceHash) return 0
+// the valid Spec-OK coverage for a node's version commit: `sinceHash` is the node's OWN latest version,
+// so the node(s) it's a version of (specNodes[sinceHash]) name the node being measured; an ack counts
+// only if its `Spec-OK:` set names one of those — `Spec-OK: A` quiets A's drift, never B's. An ack that
+// is itself an ancestor of the version can't speak for it (a re-version invalidates older acks); a valid
+// ack quiets exactly the commits reachable from it. Shared by driftFor (the count) and the anchor
+// engine's windowCommits (the commit set) so both read ONE ack rule.
+export function ackCoverFor(idx: DriftIndex, sinceHash: string): Uint8Array[] {
   const base = ancestorsOf(idx, sinceHash)
-  if (!base) return 0
+  if (!base) return []
   const targets = idx.specNodes.get(sinceHash)
-  const ackCover: Uint8Array[] = []
+  const cover: Uint8Array[] = []
   if (targets) {
     for (const [h, ackSet] of idx.acks) {
       if (inAncestors(idx, base, h)) continue
       if (![...targets].some((t) => ackSet.has(t))) continue
       const a = ancestorsOf(idx, h)
-      if (a) ackCover.push(a)
+      if (a) cover.push(a)
     }
   }
+  return cover
+}
+
+// pure lookup, no git: a commit to `path` is drift iff it is NOT an ancestor of `sinceHash` — it lies
+// in `sinceHash..HEAD` by true DAG reachability, wherever a date-ordered log happens to place it.
+// An off-history `sinceHash` → 0: no basis on HEAD to measure from.
+export function driftFor(idx: DriftIndex, sinceHash: string, path: string): number {
+  if (!sinceHash) return 0
+  const base = ancestorsOf(idx, sinceHash)
+  if (!base) return 0
+  const ackCover = ackCoverFor(idx, sinceHash)
   let n = 0
   for (const h of idx.fileCommits.get(path) ?? []) {
     if (inAncestors(idx, base, h)) continue           // reachable from the version → not drift

package/spec-cli/src/graph.ts

@@ -7,7 +7,7 @@ import { residentForgeState } from '../../spec-forge/src/resident.js'
 import { resolveForgeHost } from '../../spec-forge/src/drivers.js'
 import { mergedIssues } from './issues.js'
 import { evalContext, evalTimeline } from '../../spec-eval/src/evaltab.js'
-import { evalNodesAsync } from '../../spec-eval/src/scenarios.js'
+import { evalNodesAsync, type ScenarioTestReference } from '../../spec-eval/src/scenarios.js'
 
 // a ghost (added) node's parent: the existing node whose directory is the longest prefix of the new one.
 function resolveParent(path: string, byDir: Record<string, string>): string | null {
@@ -29,11 +29,17 @@ export function latestPerScenario<T extends { scenario: string }>(readings: T[])
   return readings.filter((r) => !seen.has(r.scenario) && (seen.add(r.scenario), true))
 }
 
-// the board's scenario fold ([[graph-lean]]): the declared set rides SLIM — {name, tags} is everything an
-// overview surface joins state onto (badge, stats, focus rows, search rows); the prose (description/
-// expected) and per-scenario code stay off the hot poll, carried by `/api/specs/lite` and `/api/specs/:id/evals`.
-export function slimScenarios(scenarios: { name: string; tags?: string[] }[]): { name: string; tags?: string[] }[] {
-  return scenarios.map((s) => ({ name: s.name, ...(s.tags?.length ? { tags: s.tags } : {}) }))
+// the board's scenario fold ([[graph-lean]]): the declared set rides SLIM — name/tags plus the normalized
+// test reference a measuring hand can follow. Prose and per-scenario code stay off the hot poll, carried by
+// `/api/specs/lite` and `/api/specs/:id/evals`; the opaque test case name is metadata, not an executor seam.
+export function slimScenarios(
+  scenarios: { name: string; tags?: string[]; test?: ScenarioTestReference }[],
+): { name: string; tags?: string[]; test?: ScenarioTestReference }[] {
+  return scenarios.map((s) => ({
+    name: s.name,
+    ...(s.tags?.length ? { tags: s.tags } : {}),
+    ...(s.test ? { test: s.test } : {}),
+  }))
 }
 
 export async function buildBoard() {
@@ -139,7 +145,7 @@ export async function buildBoard() {
   // the LATEST reading per scenario (newest-first), which is all any overview surface consumes (the score
   // badge, stats, search all reduce to latest-per-scenario anyway); the full timeline stays off the board
   // and is lazy-loaded by the eval tab from `/api/specs/:id/evals`. `scenarios` (the declared set) rides
-  // SLIM — {name, tags} only, the fields every overview surface joins state onto — with its prose
+  // SLIM — name/tags/test only, the fields every overview surface or measuring hand needs — with its prose
   // (description/expected) and per-scenario code off the hot poll: they ride the `/api/specs/lite` corpus
   // (search palette, focus-panel preview) and the `/api/specs/:id/evals` timeline (eval tab).
   // evalContext reuses the specs + driftIndex above; evalTimeline short-circuits non-measurable nodes. The