spexcode 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spexcode",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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,300 @@
+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, anchor: null }
+  return { path: raw.slice(0, i), anchor: raw.slice(i + 1).trim() || null }
+}
+
+// ---- 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 the anchored unit: the commit's --unified=0 hunks intersect the 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). A version whose content the extractor cannot parse is a
+// CONSERVATIVE hit (`unparseable` set) — over-warn, never silently skip.
+export type AnchorHit = { commit: string; unparseable?: string }
+export async function anchorHitCommits(root: string, win: string[], path: string, symbol: 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, unparseable: at.unparseable }); continue }
+    const ranges = at.units.filter((u) => u.name === symbol)
+    if (!ranges.length) continue // unit didn't exist under this name at that commit
+    const hunks = await hunksAt(root, c, path)
+    if (hunks.some(([a, b]) => ranges.some((u) => a <= u.end && u.start <= b))) hits.push({ commit: c })
+  }
+  return hits
+}

package/spec-cli/src/cli.ts

@@ -425,20 +425,16 @@ if (cmd === 'serve') {
       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}`)
     }
   } 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 +447,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 +523,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/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/guide.ts

@@ -62,6 +62,10 @@ FRONTMATTER (YAML between the opening and closing --- lines; every field optiona
            Drives drift + eval freshness. Many nodes MAY govern the same file (ordinary
            composition); a file governed by > maxOwners nodes warns (the \`owners\` rule — split it). Omit
            for a pure-prose node: a cross-cutting contract no file owns.
+           The entry may pin ONE named unit — an ANCHOR: \`path#symbol\` (\`#Class.method\` for a class
+           method; top-level functions, arrow/const declarations, classes, enums anchor cleanly; a
+           type/interface anchor warns). An anchor upgrades drift on THAT unit to a blocking error
+           (\`anchor-drift\`); without one, drift stays advisory forever. Anchors are optional.
   related: files this node REFERENCES but does not own — a YAML list, same path forms. Carries coverage
            (never drift, never eval freshness, nothing to ack); it is the many-to-many net that claims the files
            govern doesn't. Every listed path must exist (lint integrity error otherwise).
@@ -84,7 +88,15 @@ Bodies without those headings are read whole. Link sibling nodes with [[node-id]
 a REAL node (lint's mention rule; backtick a placeholder like \`[[node]]\` so it reads as sample text).
 
 WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
-  integrity  (error)  every code:/related: path exists.
+  integrity  (error)  every code:/related: path exists — and every anchor RESOLVES: a dead anchor (unit
+                      deleted/renamed), an ambiguous one (two same-named units in one file), a file that
+                      no longer parses, a language with no designated extractor, or an extractor that
+                      can't run here (e.g. no host typescript — 'npm i -D typescript' or drop the anchor)
+                      all error, never silently pass.
+  anchor-drift (error) a commit since the node's version intersected the ANCHORED unit's lines (judged
+                      from the file as it existed AT each commit) and no Spec-OK ack covers it — the
+                      blocking tier of drift. Remedy: update the spec, or \`spex spec ack\` with a real
+                      reason (recorded in the ack commit body).
   one-govern (error)  a node governs (code:) at most ONE file — keep the true subject, move the rest
                       to related:.
   living     (error)  no "## vN" changelog headings — the body is current-state.
@@ -98,8 +110,12 @@ WHAT lint CHECKS (spex spec lint; the pre-commit hook gates on errors):
                       twin; is an intermediate grouping layer missing?
   coverage   (warn)   every source file is claimed by ≥1 node — via code: OR related: (related is the net).
   drift      (warn)   a governed file has commits newer than the node's spec version — it may be stale.
-                      Remedy: edit the spec to the new intent (re-versions the node), OR \`spex spec ack <node>
-                      --reason "…"\` when only mechanics changed and the contract still holds.
+                      ALWAYS advisory: unanchored drift never blocks a commit (the blocking tier is
+                      anchor-drift above). Remedy: edit the spec to the new intent (re-versions the
+                      node), OR \`spex spec ack <node> --reason "…"\` when only mechanics changed and the
+                      contract still holds.
+  anchor     (warn)   an anchor pins a type/interface — types reshape with every refactor; anchor the
+                      behaviour-bearing unit instead.
   related-drift (warn) a related: file moved ahead of the node — a soft nudge, one summary line, never blocks.
   owners     (warn)   a file governed by > maxOwners nodes (default 3) does too much — SPLIT it so each
                       governor owns its own module (or merge the nodes, or give it one foundation owner).
@@ -338,9 +354,10 @@ the guard (the flag is the declaration of intent). Reads point anywhere.
   lint.altitude            body budgets: { lineBudget, charBudget, sizeable, dense, steps }
                            (defaults 50 / 4200 / 35 / 1.3 / 3).
   lint.maxChildren         breadth budget: warn at >= this many direct children (default 8).
-  lint.driftErrorThreshold commit-local gate HARD-BLOCKS a commit touching a node >= this many commits
-                           behind (default 3).
   lint.maxOwners           warn when a file is governed by > this many nodes (default 3).
+                           (lint.driftErrorThreshold is RETIRED: the count-based commit gate is replaced
+                           by code anchors — \`code: path#symbol\` — whose hits error unconditionally; a
+                           leftover key is ignored.)
   lint.scenarioTags        the closed vocabulary an eval scenario's tags: must draw from (default
                            ["frontend-e2e","backend-api","cli","desktop","mobile"]); extend to mint a tag.
 Example — govern your own source dir and loosen the altitude budget:

package/spec-cli/src/help.ts

@@ -45,7 +45,7 @@ derived status, title, and attention badges (drift:N · stale:N · issues:N · g
   },
   init: {
     line: 'init [dir]            adopt SpexCode on a repo: seed .spec + hooks + materialize  [--preset name]',
-    body: `Usage: spex init [dir=cwd] [--preset default|careful]
+    body: `Usage: spex init [dir=cwd] [--preset default]
 
 Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plugins plugins), plants
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
@@ -121,16 +121,20 @@ owner — the reverse edge: a file's GOVERNORS (code: — drives drift + eval fr
 — coverage only), with the verdict spelled out (uncovered / related-only / sanely governed /
 over-owned → split the file). --actionable prints NOTHING unless action is needed (hook use).
 
-lint — checks the whole spec↔code graph and exits non-zero on errors (or a blocked commit-local
-drift gate). Errors: integrity (a code:/related: file does not exist) · one-govern (a node governs >1
-file) · living (a "## vN" changelog heading) · id-format (an id char outside the whitelist — ascii
-[a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a leaf id
-reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift ·
-related-drift · owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
+lint — checks the whole spec↔code graph and exits non-zero on errors. Errors: integrity (a
+code:/related: file does not exist; a dead/ambiguous/unverifiable \`path#symbol\` anchor; an anchor
+whose language has no designated extractor or whose extractor can't run here) · anchor-drift (a
+commit since the spec's version touched the ANCHORED unit's lines, unacked — the blocking tier of
+drift) · one-govern (a node governs >1 file) · living (a "## vN" changelog heading) · id-format (an
+id char outside the whitelist — ascii [a-z0-9-] or a non-ascii unicode letter/number, CJK ok — or a
+leaf id reused) · mention (a [[id]] naming no node). Warns: altitude · breadth · coverage · drift
+(UNANCHORED drift — always advisory, never blocks) · anchor (anchoring a type) · related-drift ·
+owners · confusable-id (two leaf ids one edit apart). spec lint's errors BLOCK commits (the pre-commit shim; bypass SPEXCODE_SKIP_LINT=1);
 contrast \`spex eval lint\`, which is pure advisory and never blocks anyone.
 
 ack — stamp Spec-OK on HEAD (an empty stamp commit): the drift remedy when only MECHANICS changed
-and the spec's contract still holds. --reason is required but NOT stored. If the intent DID change,
+and the spec's contract still holds. --reason is required and recorded in the ack commit's body
+(quieting an anchor hit is a strong claim — the why must be durable). If the intent DID change,
 edit the spec instead — same commit as the code.`,
     see: 'spex guide spec (the file format + every lint rule) · spex graph (browse the whole tree)',
   },
@@ -192,7 +196,7 @@ ${MENTION_NOTE}`,
     see: 'spex eval ls --session <SEL> (the session’s measured loss) · spex help eval',
   },
   eval: {
-    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · retract · clean',
+    line: 'eval <verb>           the measurement system: add · ls · scenario ls · lint · ok · retract · clean',
     body: `Usage: spex eval add [<node>|.] [--scenario <name>] (--pass|--fail) [--note <text>]
                     [--image <png> …repeatable] [--result <path|->] [--video <webm|mp4>] [--timeline <json>]
        spex eval ls [<node>|.] [--json]                a node's eval timeline, newest first
@@ -200,6 +204,7 @@ ${MENTION_NOTE}`,
        spex eval ls --session <SEL> --export [--open | --out <path>]
        spex eval scenario ls [<node>|.] [--unmeasured] [--json]   declared scenarios; bare = every node
        spex eval lint [--changed]                      measurement-layer findings (advisory, always exit 0)
+       spex eval ok <node> [--scenario <name>]         the HUMAN sign-off on the scenario's latest reading
        spex eval retract [<node>|.] [--scenario <name>] [--last | --ts <iso>] [--note <why>]
        spex eval clean [--keep-latest | --all]         GC the content-addressed evidence cache
 
@@ -222,6 +227,11 @@ stale (eval-drift) · orphaned remark tracks (eval-dangling) · governed source
 files (eval-owners). --changed scopes to the nodes THIS branch touched. spec lint's errors block
 commits; eval lint is PURE ADVISORY, always exit 0 — a measurement gap never blocks anyone.
 
+ok — the human's reviewed-and-agreed mark on the scenario's LATEST reading: an appended, monotonic
+sign-off bound to that one immutable reading (a newer reading or staleness releases it on its own —
+no un-ok exists). The evals feed default-hides a fresh, ok'd scenario; a governed session is refused
+(an agent's judgment on a reading is a remark, never a self-blessing).
+
 retract — the sanctioned undo for a botched filing: APPENDS a retraction event (traceable, never
 deletes a line); the previous eval becomes latest again, or the scenario honestly returns to
 unmeasured.

package/spec-cli/src/index.ts

@@ -21,6 +21,7 @@ import { evalTimeline, readBlobByHash } from '../../spec-eval/src/evaltab.js'
 import { putBlob } from '../../spec-eval/src/cache.js'
 import { evalNodes } from '../../spec-eval/src/scenarios.js'
 import { fileHumanReading } from '../../spec-eval/src/filing.js'
+import { fileHumanOk } from '../../spec-eval/src/humanok.js'
 import { buildExportModel, renderExportHtml, buildSessionEvals } from '../../spec-eval/src/sessioneval.js'
 import { saveUpload, MAX_UPLOAD_BYTES } from './uploads.js'
 import { attachViewer, detachViewer, resizeBridge, forwardWheel, superviseBridges, type Viewer } from './pty-bridge.js'
@@ -113,6 +114,19 @@ app.post('/api/specs/:id/evals', async (c) => {
   const r = fileHumanReading(c.req.param('id'), b)
   return r.ok ? c.json({ ok: true, reading: r.reading }) : c.json({ error: r.error }, 400)
 })
+// the HUMAN SIGN-OFF write ([[human-ok]]) — the dashboard's ok affordance and `spex eval ok` share this ONE
+// write (LAW L: no dashboard-only path). Identity is SERVER-DERIVED 'human', never the request body (the
+// same rule as /api/remarks). The write appends a monotonic human-ok event bound to the scenario's latest
+// reading and — on the trunk checkout — commits it straight to trunk; the board cache is invalidated
+// atomically with persistence so the writer's own refetch never races a stale cache.
+app.post('/api/specs/:id/evals/ok', async (c) => {
+  const b = await c.req.json().catch(() => null)
+  if (!b || typeof b.scenario !== 'string') return c.json({ error: 'body needs { scenario }' }, 400)
+  const r = fileHumanOk(c.req.param('id'), b.scenario, 'human')
+  if (!r.ok) return c.json({ error: r.error }, 400)
+  notifyBoardChanged('full')
+  return c.json({ ok: true, already: r.already, humanOk: r.humanOk })
+})
 // serve a reading's evidence blob by content hash (bytes never enter git): bad hash → 400, missing → 404,
 // else the bytes with a sniffed MIME and an immutable cache header (the name IS the content hash).
 // HTTP Range is honored — a <video> can only SEEK when the server answers byte ranges (a browser clamps

package/spec-cli/src/init.ts

@@ -11,11 +11,12 @@ const pkgRoot = fileURLToPath(new URL('..', import.meta.url))
 const TEMPLATES = join(pkgRoot, 'templates')
 
 // the cumulative preset chain, lean → cautious (see [[init-preset]]). `default` is the live `.plugins`
-// instance set (planted from templates/spec); every higher tier is a SEPARATE package under
-// templates/presets/<tier>/ that seeding stacks ON TOP — a superset, so selecting `careful` seeds the
-// default set PLUS the careful package. Selection matters ONLY here at seed time; the running repo just
+// instance set (planted from templates/spec); a higher tier would be a SEPARATE package under
+// templates/presets/<tier>/ that seeding stacks ON TOP — a superset. No non-default tier ships today
+// (the `careful` package was retired); the chain mechanism stays for when one earns its keep.
+// Selection matters ONLY here at seed time; the running repo just
 // walks whatever `.plugins` ended up planted, so there is no launcher-side preset gate.
-const PRESET_TIERS = ['default', 'careful'] as const
+const PRESET_TIERS = ['default'] as const
 const presetRank = (name: string): number => (PRESET_TIERS as readonly string[]).indexOf(name)
 
 // recursively copy srcDir -> destDir, NEVER overwriting an existing file. Returns the repo-relative