spexcode 0.6.2 → 0.6.5

package/spec-cli/src/lint.ts

@@ -1,488 +0,0 @@
-import { readFileSync, existsSync, statSync } from 'node:fs'
-import { join } from 'node:path'
-import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, withEventLedgerBuild, type DriftPathEvent } from './git.js'
-import { loadSpecs, parseFrontmatter } from './specs.js'
-import { readJsonConfig } from './layout.js'
-import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveAnchor, resolveSelectors, windowEvents, anchorHitQueries } from './anchors.js'
-import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js'
-
-export type Finding = { level: 'error' | 'warn'; rule: string; spec?: string; file?: string; msg: string }
-export const SPEC_LINT_REPORT_PROJECTION = 'spex.spec-lint.report'
-export const SPEC_LINT_REPORT_SCHEMA_VERSION = 1
-export type SpecLintReport = {
-  projection: typeof SPEC_LINT_REPORT_PROJECTION
-  schemaVersion: typeof SPEC_LINT_REPORT_SCHEMA_VERSION
-  sourceFiles: string[]
-  findings: Finding[]
-}
-
-export type LintConfig = {
-  governedRoots: string[]       // dirs whose tracked source files must each be governed by a spec. '.' = whole project.
-  sourceIncludeGlobs: string[] | null // null includes every tracked regular text file; [] intentionally includes none
-  sourceExcludeGlobs: string[]  // explicit source-policy subtraction
-  sourceExtensions: string[] | null // compatibility shorthand compiled into sourceIncludeGlobs
-  testGlobs: string[]           // globs EXCLUDED from coverage; set [] to govern tests too
-  maxOwners: number          // warn when a file is governed (code:) by > this many nodes
-  scenarioTags: string[]     // the closed vocabulary an eval scenario's `tags:` must draw from; extend it to mint a new tag
-  scopedCodeMiss: 'warn' | 'ignore' // the file-level drift ADVISORY on a selector-scoped code: file whose window has no
-                             // selector hit ([[code-anchor]]). 'warn' (default) keeps today's drift warning; 'ignore'
-                             // silences ONLY that advisory — hit blocks, bare code drift, integrity, acks, related
-                             // semantics, and eval freshness are all untouched by this knob.
-}
-const DEFAULT_CONFIG: LintConfig = {
-  governedRoots: ['spec-dashboard/src', 'spec-cli/src'],
-  sourceIncludeGlobs: null,
-  sourceExcludeGlobs: [],
-  sourceExtensions: null,
-  testGlobs: DEFAULT_TEST_GLOBS,
-  maxOwners: 3,
-  scenarioTags: ['frontend-e2e', 'backend-api', 'cli', 'desktop', 'mobile'],
-  scopedCodeMiss: 'warn',
-}
-export function loadConfig(root: string, pendingSource?: string | null): LintConfig {
-  // Absent spexcode.json → tuned defaults; a MALFORMED one throws LOUD (readJsonConfig) rather than
-  // silently reverting the author's budgets to defaults and green-washing the very warnings they tuned.
-  let parsed: any
-  if (pendingSource === undefined) parsed = readJsonConfig(join(root, 'spexcode.json'))
-  else if (pendingSource === null) parsed = {}
-  else {
-    try { parsed = JSON.parse(pendingSource) }
-    catch (e: any) { throw new Error(`invalid JSON in candidate spexcode.json: ${e?.message ?? e}`) }
-  }
-  const c = parsed?.lint ?? {}
-  const merged = { ...DEFAULT_CONFIG, ...c }
-  return normalizeConfig(merged)
-}
-
-// Compile every author-facing source selector into one include-minus-exclude/test policy. In particular,
-// sourceExtensions is compatibility syntax only: it contributes include globs and never reaches discovery.
-export function normalizeConfig(cfg: LintConfig): LintConfig {
-  // a mistyped enum silently reverting to the default would green-wash (or over-warn) exactly the
-  // advisory the author meant to tune — same fail-loud rule as a malformed spexcode.json.
-  if (cfg.scopedCodeMiss !== 'warn' && cfg.scopedCodeMiss !== 'ignore')
-    throw new Error(`spexcode.json lint.scopedCodeMiss must be "warn" or "ignore", got ${JSON.stringify(cfg.scopedCodeMiss)}`)
-  const dedot = (xs: string[]) => xs.map((x) => x.replace(/^\.+/, ''))
-  const anyDepth = (xs: string[]) => xs.map((g) => (g.includes('/') ? g : `**/${g}`))
-  const extensions = cfg.sourceExtensions === null ? null : dedot(cfg.sourceExtensions)
-  const includes = cfg.sourceIncludeGlobs === null && extensions === null
-    ? null
-    : [...new Set([...anyDepth(cfg.sourceIncludeGlobs ?? []), ...(extensions ?? []).map((ext) => `**/*.${ext}`)])]
-  return {
-    ...cfg,
-    sourceIncludeGlobs: includes,
-    sourceExcludeGlobs: anyDepth(cfg.sourceExcludeGlobs),
-    sourceExtensions: extensions,
-    testGlobs: anyDepth(cfg.testGlobs),
-  }
-}
-
-export type SpecLintOptions = { tip?: string }
-type SpecLintRun = { sourceFiles: string[]; findings: Finding[] }
-
-function untrackedAdoptionFiles(root: string): string[] {
-  if (git(['-C', root, 'rev-parse', '--is-inside-work-tree']).trim() !== 'true') return []
-  const status = git([
-    '-C', root,
-    '-c', 'core.quotePath=false',
-    'status', '--porcelain=v1', '-z', '--untracked-files=all',
-    '--', '.spec', 'spexcode.json',
-  ])
-  return status.split('\0')
-    .filter((entry) => entry.startsWith('?? '))
-    .map((entry) => entry.slice(3))
-    .filter(Boolean)
-}
-
-function pendingChangedPaths(root: string, tip: string): string[] {
-  try {
-    git(['-C', root, 'rev-parse', `${tip}^{commit}`])
-    // `-m` compares a merge with every parent. An `ours` merge can leave the result tree
-    // identical to its first parent while still making an unacknowledged side-branch commit
-    // reachable; first-parent-only paths would filter that debt out of the pending anchor window.
-    const fields = git(['-C', root, '-c', 'core.quotePath=false', 'diff-tree', '--no-commit-id', '--name-status', '-z', '-r', '-m', '-M', tip])
-      .split('\0').filter(Boolean)
-    const changed: string[] = []
-    for (let i = 0; i < fields.length;) {
-      const status = fields[i++]
-      if (/^[RC]/.test(status)) {
-        changed.push(fields[i++], fields[i++])
-      } else {
-        changed.push(fields[i++])
-      }
-    }
-    return [...new Set(changed.filter(Boolean))]
-  } catch { return [] }
-}
-// Cheap pending classification for the reference hook. It reads only the candidate tree and claims; it
-// never constructs either history index. A normal lint call deliberately does not use this
-// shortcut so its full findings/oracle contract remains unchanged.
-export async function pendingTouchesGoverned(root: string, tip: string): Promise<boolean> {
-  // A merge can introduce reachable side-branch debt without changing the result tree. The first-parent
-  // diff is insufficient for a scope proof, so all multi-parent candidates stay on the full lint path.
-  const parentCount = git(['-C', root, 'rev-list', '--parents', '-n1', tip]).trim().split(/\s+/).length - 1
-  if (parentCount > 1) return true
-  const changed = pendingChangedPaths(root, tip)
-  if (!changed.length) return true
-  // `governedRoots` is source discovery policy, not the set of actual code claims: a spec may deliberately
-  // govern a path outside those roots. Read only the candidate spec tree (no history/drift indexes) so the
-  // scope proof follows the same code:/related: declarations that lint later enforces.
-  const specs = await loadSpecs(root, { tip, history: null, drift: null })
-  const claims = specs.flatMap((spec) => [...spec.code, ...spec.related])
-  return changed.some((path) => claims.some((claim) => relationClaimsPath(claim, path))
-    || path === 'spexcode.json' || path === 'spexcode.local.json'
-    || (path.startsWith('.spec/') && !path.startsWith('.spec/.issues/'))
-    || path === '.spec')
-}
-
-export async function specLint(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<Finding[]> {
-  return (await specLintRun(root, regs, options)).findings
-}
-
-export async function specLintReport(root = repoRoot(), regs = extractors(root), options: SpecLintOptions = {}): Promise<SpecLintReport> {
-  const run = await specLintRun(root, regs, options)
-  return {
-    projection: SPEC_LINT_REPORT_PROJECTION,
-    schemaVersion: SPEC_LINT_REPORT_SCHEMA_VERSION,
-    sourceFiles: run.sourceFiles,
-    findings: run.findings,
-  }
-}
-
-function specLintRun(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
-  return withEventLedgerBuild(root, () => specLintInLedger(root, regs, options))
-}
-
-async function specLintInLedger(root: string, regs: ReturnType<typeof extractors>, options: SpecLintOptions): Promise<SpecLintRun> {
-  const tip = options.tip ?? 'HEAD'
-  const pending = tip !== 'HEAD'
-  const changed = pending ? pendingChangedPaths(root, tip) : []
-  const files = pending ? treeFilePaths(root, tip) : null
-  const directories = new Set<string>()
-  for (const file of files ?? []) {
-    const parts = file.split('/')
-    for (let i = 1; i < parts.length; i++) directories.add(parts.slice(0, i).join('/'))
-  }
-  const existsAtTip = (path: string) => files ? files.has(path) || directories.has(path.replace(/\/+$/, '')) : existsSync(join(root, path))
-  const isDirectoryAtTip = (path: string) => files
-    ? !files.has(path) && directories.has(path.replace(/\/+$/, ''))
-    : statSync(join(root, path)).isDirectory()
-  const textAtTip = (path: string) => pending ? treeFileText(root, tip, path) : readFileSync(join(root, path), 'utf8')
-  const cfg = loadConfig(root, pending ? treeFileText(root, tip, 'spexcode.json') : undefined)
-  const untracked = untrackedAdoptionFiles(root)
-  if (untracked.length) {
-    const shown = untracked.slice(0, 6)
-    const suffix = untracked.length > shown.length ? ` (+${untracked.length - shown.length} more)` : ''
-    return {
-      sourceFiles: [],
-      findings: [{
-        level: 'error',
-        rule: 'integrity',
-        msg: `project source of truth is untracked: ${shown.join(', ')}${suffix} — add it with \`git add .spec spexcode.json\` and commit it; generated harness files such as .codex/, .claude/, and AGENTS.md are machine-local`,
-      }],
-    }
-  }
-  const governed = trackedSourceFiles(root, cfg.governedRoots, cfg, tip)
-  const [hidx, didx] = await sourceIndexes(root, tip)
-  const specs = await loadSpecs(root, { tip, history: hidx, drift: didx })
-  const out: Finding[] = []
-
-  // integrity + build the file -> owners map. A relation's STRUCTURAL problems (a duplicate entry,
-  // bare/scoped mixing on one base path, a selector on a glob — all from parseRelation,
-  // [[code-anchor]]) are integrity errors: malformed edges block like broken ones.
-  const owners = new Map<string, string[]>()
-  const claimed = new Set<string>()
-  const governedClaims = new Set<string>()
-  for (const s of specs) {
-    for (const p of s.relationProblems)
-      out.push({ level: 'error', rule: 'integrity', spec: s.id, msg: `'${s.id}' ${p}` })
-    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
-    for (const f of s.code) {
-      if (!existsAtTip(f))
-        out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing file: ${f}` })
-      claimed.add(f)
-      governedClaims.add(f)
-      // a selector-SCOPED entry claims named units, not the whole file, so it stays out of the owners
-      // bound below ([[code-anchor]]) — `spex spec owner` still displays it as a (scoped) governor.
-      if (!scopedPaths.has(f)) owners.set(f, [...(owners.get(f) ?? []), s.id])
-    }
-    // one-govern: a node is source of truth for at most ONE file — DISTINCT base paths; several
-    // `path#symbol` selectors on the same file are one subject — so drift/eval/ack have a single
-    // unambiguous subject (see [[governed-related]]). >1 is a defect — pick the true subject, demote the
-    // rest to related. ERROR (the node-side twin of too-many-owners' file-side bound). 0 is fine.
-    if (s.code.length > 1)
-      out.push({ level: 'error', rule: 'one-govern', spec: s.id, msg: `'${s.id}' governs ${s.code.length} files [${s.code.join(', ')}] — a node is source of truth for at most ONE. Keep the true subject in code:, move the rest to related:` })
-  }
-  // a file is COVERED if any node GOVERNS (code:) or merely REFERENCES (related:) it; integrity covers both.
-  // `related:` is the coverage net: govern is a sharp ideally-one-file pointer, so most files are reached by
-  // related, not govern (see [[governed-related]]). It carries coverage but never drift, never eval freshness.
-  for (const s of specs) for (const f of s.related) {
-    if (!existsAtTip(f))
-      out.push({ level: 'error', rule: 'integrity', spec: s.id, file: f, msg: `spec '${s.id}' lists a missing related file: ${f}` })
-    claimed.add(f)
-  }
-
-  // A candidate may retire a node together with the implementation it owned, or transfer that path to a
-  // new node. It may not delete the governor while leaving the governed subject behind: ordinary coverage
-  // is advisory, so without this transition check a candidate could erase the very contract that would
-  // reject its code change. Read only deleted spec blobs from HEAD; no second history index is needed.
-  if (pending) {
-    let deleted: string[] = []
-    try {
-      deleted = git(['-C', root, '-c', 'core.quotePath=false', 'diff', '--diff-filter=D', '--name-only', 'HEAD', tip, '--', '.spec'])
-        .split('\n').map((path) => path.trim()).filter((path) => path.endsWith('/spec.md'))
-    } catch { /* an unreadable comparison is already surfaced by the candidate history reads */ }
-    for (const specPath of deleted) {
-      const oldSource = treeFileText(root, 'HEAD', specPath)
-      if (oldSource === null) continue
-      const value = parseFrontmatter(oldSource).fm.code
-      const rows = Array.isArray(value) ? value : value ? [value] : []
-      for (const row of rows) {
-        const path = parseCodeEntry(row).path
-        if (existsAtTip(path) && !governedClaims.has(path))
-          out.push({ level: 'error', rule: 'integrity', file: path, msg: `candidate deletes governor '${specPath}' but leaves its governed subject '${path}' without a code: owner — delete the retired implementation too, or transfer it to a real node in this commit` })
-      }
-    }
-  }
-
-  // id-format: a node id (its leaf dir basename) passes an EXACT per-character whitelist — an ascii char
-  // must be [a-z0-9-]; a non-ascii char must be a unicode letter/number (judged on NFC, the mint's
-  // canonical form) — and is UNIQUE tree-wide (ERROR). This is THE id vocabulary, defined once (the
-  // spec-lint node's rule table) and referenced by [[mentions]] / [[id-url-safe]]: CJK and every other
-  // letter script is first-class, exactly what the script-agnostic resolve machinery already accepts.
-  // Everything else is forbidden by construction, no heuristics — space, '/', uppercase Latin (lowercase
-  // is the Latin norm), control chars, and '_' (reserved as the mint's parent-qualification join; a '_'
-  // inside a basename would make that join ambiguous). One optional leading dot is allowed — the
-  // reflexive plugin root `.plugins` is dot-prefixed by design. Uniqueness is what keeps the leaf THE id:
-  // on a collision the mint must parent-qualify with `_`, so every surface suddenly speaks a longer id
-  // than the dir name — legal to the machinery, illegible to people.
-  const ID_RE = /^\.?(?:[a-z0-9-]|(?![\x00-\x7F])[\p{L}\p{N}])+$/u
-  const leafOf = (p: string) => { const segs = p.split('/'); return segs[segs.length - 2] }
-  const byLeaf = new Map<string, string[]>()
-  for (const s of specs) {
-    const leaf = leafOf(s.path)
-    byLeaf.set(leaf, [...(byLeaf.get(leaf) ?? []), s.path])
-    if (!ID_RE.test(leaf.normalize('NFC')))
-      out.push({ level: 'error', rule: 'id-format', spec: s.id, msg: `node dir '${leaf}' is not a valid id — each char is ascii [a-z0-9-] or a non-ascii unicode letter/number (one optional leading dot); space, '/', '_', uppercase Latin and control chars are forbidden; rename the directory` })
-  }
-  for (const [leaf, paths] of byLeaf) {
-    if (paths.length > 1)
-      out.push({ level: 'error', rule: 'id-format', msg: `leaf id '${leaf}' names ${paths.length} nodes [${paths.map((p) => p.replace(/\/spec\.md$/, '')).join(', ')}] — a leaf id is unique tree-wide; rename all but one` })
-  }
-
-  // confusable-id: two leaf ids one edit apart read as the same word (WARN — a typo in either reaches a
-  // real, wrong node). Deliberately conservative: distance exactly 1, so hierarchy naming like
-  // graph/graph-delivery (a whole suffix apart) and verb pairs like evidence-put/evidence-get (distance 2)
-  // never warn — better to miss a borderline pair than to nag legitimate siblings. Distance is measured
-  // in CODE POINTS, script-agnostic: a CJK pair one character apart (节点/结点 — a classic homophone
-  // IME slip) warns like an ascii pair, an astral char counts as one edit (not two surrogate units), and
-  // a pure-CJK id can never sit one edit from a pure-ascii one.
-  const lev1 = (a: string, b: string): boolean => {
-    const A = [...a], B = [...b]
-    if (Math.abs(A.length - B.length) > 1 || a === b) return false
-    let i = 0
-    while (i < A.length && i < B.length && A[i] === B[i]) i++
-    const rest = (x: string[], k: number) => x.slice(k).join('')
-    return rest(A, i + 1) === rest(B, i + 1) || rest(A, i + 1) === rest(B, i) || rest(A, i) === rest(B, i + 1)
-  }
-  const leaves = [...byLeaf.keys()]
-  for (let i = 0; i < leaves.length; i++) for (let j = i + 1; j < leaves.length; j++) {
-    if (lev1(leaves[i], leaves[j]))
-      out.push({ level: 'warn', rule: 'confusable-id', msg: `leaf ids '${leaves[i]}' and '${leaves[j]}' are one edit apart — easily confused; if they are distinct concepts, rename one to read apart` })
-  }
-
-  // mention: a `[[id]]` in a body must name a real node (ERROR — a dangling mention is a broken edge in
-  // the very graph the tree exists to keep honest). Checked against the SAME minted ids every other
-  // surface resolves ([[id-url-safe]]). Prose only: a fenced block or inline `code span` is sample text
-  // (`[[node]]`, `[[<id>]]` placeholders live there), not a reference.
-  const idSet = new Set(specs.map((s) => s.id))
-  const MENTION_RE = /\[\[(\.?[\p{L}\p{N}_-]+)\]\]/gu
-  for (const s of specs) {
-    let inFence = false
-    for (const rawLine of s.body.split('\n')) {
-      if (/^\s*```/.test(rawLine)) { inFence = !inFence; continue }
-      if (inFence) continue
-      const line = rawLine.replace(/`[^`]*`/g, '')
-      for (const m of line.matchAll(MENTION_RE)) {
-        if (!idSet.has(m[1]))
-          out.push({ level: 'error', rule: 'mention', spec: s.id, msg: `'${s.id}' mentions [[${m[1]}]] — no such node; retarget or drop it (backtick it if it is sample text)` })
-      }
-    }
-  }
-
-  // living: a spec body describes the node's CURRENT intent — it is not a changelog. Version history
-  // (every content commit, its reason/session/line-diff) is read from git and shown in the dashboard's
-  // recent/history tabs, so a `## vN`-style heading in the body is duplicated, drift-prone state.
-  // Reject it. Fence-aware — a `## v2` inside a ``` block is sample text, not a heading.
-  const VER_HEADING = /^#{1,6}\s+v\d+\b/
-  for (const s of specs) {
-    let inFence = false
-    for (const line of s.body.split('\n')) {
-      if (/^\s*```/.test(line)) { inFence = !inFence; continue }
-      if (!inFence && VER_HEADING.test(line))
-        out.push({ level: 'error', rule: 'living', spec: s.id, msg: `'${s.id}' has a changelog heading "${line.trim()}" — keep the body current-state; version history lives in git (recent/history tabs)` })
-    }
-  }
-
-  // coverage: every governed source file must be claimed by at least one spec.
-  if (governed.length === 0)
-    out.push({ level: 'warn', rule: 'coverage', msg: `governing NOTHING — 0 source candidates under governedRoots [${cfg.governedRoots.join(', ')}]; ${sourcePolicyDescription(cfg)}. Repair these knobs under the "lint" key in spexcode.json (top-level keys are ignored): governedRoots, sourceIncludeGlobs, sourceExcludeGlobs, testGlobs; sourceExtensions remains compatibility shorthand for include globs.` })
-  for (const f of governed)
-    if (!claimed.has(f)) out.push({ level: 'warn', rule: 'coverage', file: f, msg: `no spec governs: ${f}` })
-
-  // too-many-owners: many nodes governing one file is ordinary composition (drift fans to each — correct,
-  // every owner has a stake), so this is NOT flagged. Only an OVER-owned file is a smell — governed by more
-  // than maxOwners nodes, it has accreted more independently-specified functionality than one file should
-  // hold (see [[governed-related]]). ONE summary line (not one per file — its own wall of noise): the count,
-  // the worst offenders, and the remedy, which blames the FILE not the ownership — SPLIT it so each governor
-  // reclaims its own module; or merge the nodes if they're one concern; or give it a single foundation owner.
-  const over = [...owners].filter(([, ids]) => ids.length > cfg.maxOwners).sort((a, b) => b[1].length - a[1].length)
-  if (over.length) {
-    const top = over.slice(0, 5).map(([f, ids]) => `${f.split('/').pop()}(${ids.length})`).join(', ')
-    out.push({ level: 'warn', rule: 'owners', msg: `${over.length} file(s) are governed by > ${cfg.maxOwners} nodes — each holds more separately-specified functionality than one file should. Worst: ${top}. SPLIT the file so each governor owns its own module (or merge the nodes, or give it a single foundation owner + related:).` })
-  }
-
-  // code anchors ([[code-anchor]]): a code:/related: entry may pin named units (`path#symbol` — any
-  // number per base file, OR'd). On code:, the anchor is the BLOCKING tier of drift: a window
-  // commit (spec's last version..tip, ordinary diff or merge-authored combined diff) whose zero-context hunks
-  // intersect any pinned unit's line range — extracted from the file AS OF that commit, by the
-  // extension's ONE designated extractor — is ONE anchor-drift ERROR naming the hit selectors, unless a
-  // Spec-OK ack covers it. On related:, the SAME engine yields only a soft warn on a hit — a scoped
-  // related miss is silent (never blocks, no ack, no eval freshness). Resolution failures are never
-  // silent for either relation: a dead or ambiguous selector, a selector on a directory, and an
-  // unparseable working-tree file ERROR. An extension with no designated extractor, or a designated
-  // extractor that cannot run here, also ERRORS but skips those anchors so the remaining checks continue.
-  type AnchorLintQuery = { id: string; version: number; relation: 'code' | 'related'; path: string; symbols: string[]; win: DriftPathEvent[] }
-  type AnchorLintStep = { finding: Finding } | { query: AnchorLintQuery }
-  const readyWarned = new Set<string>()
-  const anchorSteps: AnchorLintStep[] = []
-  for (const s of specs) {
-    for (const { relation, entries } of [{ relation: 'code' as const, entries: s.codeScoped }, { relation: 'related' as const, entries: s.relatedScoped }]) {
-      for (const { path, selectors } of entries) {
-        if (pending && !changed.some((file) => relationClaimsPath(path, file))) continue
-        const x = extractorFor(regs, extOf(path))
-        if (!x) {
-          anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' anchors ${path}#${selectors.join(', #')} (${relation}:), but no extractor is designated for '.${extOf(path)}' files — anchor validation was skipped and remains unverified; add a LangSpec row (anchors.ts) or drop the selector(s)` } })
-          continue
-        }
-        const ready = x.ready()
-        if (ready !== true) {
-          // once per (extractor, reason), even across several anchored nodes — one repair, one message.
-          if (!readyWarned.has(x.id + ready)) { readyWarned.add(x.id + ready); anchorSteps.push({ finding: { level: 'error', rule: 'integrity', msg: `anchor extractor '${x.id}' cannot run: ${ready}` } }) }
-          continue
-        }
-        if (!existsAtTip(path)) continue // the missing FILE already errored above
-        if (isDirectoryAtTip(path)) {
-          anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `'${s.id}' puts a selector on a directory (${relation}: ${path}#${selectors[0]}) — a selector scopes ONE real file` } })
-          continue
-        }
-        let units
-        try {
-          const source = textAtTip(path)
-          if (source === null) throw new Error(`candidate tree has no file '${path}'`)
-          units = x.extract(source, path)
-        } catch (e: any) {
-          anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `anchor ${path}#${selectors.join(', #')} ('${s.id}') is unverifiable — the current file does not parse: ${e?.message ?? e}` } })
-          continue
-        }
-        // each selector resolves (or errors) on its own; only the live ones feed the window engine.
-        // The dead/ambiguous verdict itself comes from the ONE shared classifier ([[code-anchor]]); only the
-        // wording of the gate's findings lives here.
-        const live: string[] = []
-        for (const res of resolveSelectors(units, selectors)) {
-          const sym = res.selector
-          if ('dead' in res) {
-            anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `dead anchor: ${path}#${sym} ('${s.id}') names no unit on the current tree — the unit was deleted or renamed; update the spec's ${relation}: entry to follow it` } })
-            continue
-          }
-          if ('ambiguous' in res) {
-            anchorSteps.push({ finding: { level: 'error', rule: 'integrity', spec: s.id, file: path, msg: `ambiguous anchor: ${path}#${sym} ('${s.id}') names ${res.ambiguous} same-named units in one file — an anchor must be unique; rename one unit` } })
-            continue
-          }
-          if (res.ok.typeOnly)
-            anchorSteps.push({ finding: { level: 'warn', rule: 'anchor', spec: s.id, file: path, msg: `${path}#${sym} anchors a ${res.ok.kind} — anchoring a type is usually wrong (types reshape with every refactor); anchor the behaviour-bearing unit instead` } })
-          live.push(sym)
-        }
-        if (!live.length) continue
-        const since = rowsFor(hidx, s.path)[0]?.hash || ''
-        const win = windowEvents(didx, since, path, s.id)
-        if (!win.length) continue
-        anchorSteps.push({ query: { id: s.id, version: s.version, relation, path, symbols: live, win } })
-      }
-    }
-  }
-  const anchorHits = await anchorHitQueries(root, anchorSteps.flatMap((step) => 'query' in step ? [{ win: step.query.win, symbols: step.query.symbols }] : []), regs)
-  let hitIndex = 0
-  for (const step of anchorSteps) {
-    if ('finding' in step) { out.push(step.finding); continue }
-    const { id, version, relation, path } = step.query
-    const hits = anchorHits[hitIndex++]
-    if (!hits.length) continue
-    const hitSyms = [...new Set(hits.flatMap((h) => h.selectors))]
-    const shas = hits.map((h) => h.commit.slice(0, 8)).join(', ')
-    const unparseable = hits.filter((h) => h.unparseable)
-    const parseNote = unparseable.length ? ` (${unparseable.length} of these could not be parsed at that commit — counted as hits conservatively)` : ''
-    if (relation === 'code') {
-      const current = pending && hits.some((hit) => hit.commit === tip)
-      const older = pending && hits.some((hit) => hit.commit !== tip)
-      const remedy = !pending
-        ? `update the spec, or 'spex spec ack ${id} --reason "…"' if the contract still holds`
-        : current && older
-          ? `update the spec in this commit; its own hit can be declared by retrying with 'git commit --trailer "Spec-OK: ${id}" …', but the listed older debt must be cleared first (an in-commit declaration never pardons ancestors)`
-          : current
-            ? `update the spec in this commit, or retry with 'git commit --trailer "Spec-OK: ${id}" …'; a later empty ack cannot pre-author this candidate`
-            : `update the spec in this commit, or clear this older debt with 'spex spec ack ${id} --reason "…"' before retrying the candidate`
-      out.push({ level: 'error', rule: 'anchor-drift', spec: id, file: path, msg: `${path}#${hitSyms.join(', #')} was changed by ${hits.length} commit(s) since spec '${id}' v${version} [${shas}]${parseNote} — the anchored contract's code moved: ${remedy}` })
-    } else
-      out.push({ level: 'warn', rule: 'related-drift', spec: id, file: path, msg: `related ${path}#${hitSyms.join(', #')} ('${id}') was changed by ${hits.length} commit(s) since v${version} [${shas}]${parseNote} — a scoped dependency shifted, worth a glance (SOFT: never blocks, no ack, no eval staleness)` })
-  }
-
-  // drift: a governed file has commits NOT yet reflected in its spec. Judged by true git ancestry —
-  // loadSpecs computes `driftFiles` via driftFor() over the one cached driftIndex walk (git.ts): a
-  // commit to the file counts iff it is NOT reachable from the spec's latest version (in-memory
-  // parent-edge reachability, the equivalent of `rev-list <version>..HEAD -- <file>`), never a
-  // log-position or timestamp guess.
-  // A selector-SCOPED code file keeps this file-level advisory by default (a miss still nudges); the
-  // committed `lint.scopedCodeMiss: "ignore"` silences ONLY this advisory for scoped entries — the
-  // anchor engine's verdicts above (hit = block, resolution failures = integrity) are untouched.
-  for (const s of specs) {
-    const scopedPaths = new Set(s.codeScoped.map((e) => e.path))
-    for (const d of s.driftFiles) {
-      if (cfg.scopedCodeMiss === 'ignore' && scopedPaths.has(d.file)) continue
-      out.push({ level: 'warn', rule: 'drift', spec: s.id, file: d.file, msg: `${d.file} is ${d.behind} commit(s) ahead of spec '${s.id}' (v${s.version}) — may be stale` })
-    }
-  }
-
-  // related drift: the SOFT tier ([[governed-related]]). A referenced file moved ahead of the node's
-  // version — a nudge that a dependency shifted. Same ancestry basis as govern drift, but WARN-only,
-  // never reaching the commit gate (driftGate reads govern) or eval freshness. It is COMMON (shared substrate and
-  // faces change often without re-versioning every referrer), so per-file it is a wall; like
-  // too-many-owners it collapses to ONE summary line, with the per-file detail riding the board
-  // (relatedDriftFiles). It stays a soft edge, never a per-file interruption.
-  const rd = specs.flatMap((s) => s.relatedDriftFiles.map((d) => ({ id: s.id, behind: d.behind })))
-  if (rd.length) {
-    const byNode = new Map<string, number>()
-    for (const d of rd) byNode.set(d.id, (byNode.get(d.id) ?? 0) + 1)
-    const worst = [...byNode].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([id, n]) => `${id}(${n})`).join(', ')
-    out.push({ level: 'warn', rule: 'related-drift', msg: `${rd.length} related file(s) across ${byNode.size} node(s) drifted ahead of their spec (SOFT — a dependency shifted, worth a glance; never blocks, no ack, no eval staleness). Most: ${worst}` })
-  }
-
-  return { sourceFiles: governed.slice().sort(), findings: out }
-}
-
-export const DRIFT_GUIDANCE = `DRIFT — a governed file has moved ahead of its spec. A CHECKPOINT, not a chore: find WHERE the truth
-broke along  raw intent → expanded spec → code: link → code structure → implementation, fix THAT layer.
-
-  Inspect:  spex spec lint                                                       which files, against which spec
-            the node's spec.md                                             its raw source + expanded spec
-            git diff $(git log -1 --format=%H -- <spec.md>)..HEAD -- <file>   the code delta since the spec
-
-Diagnose, then apply the one honest remedy:
-  • contract changed        → rewrite the spec body to the new intent, commit it (re-versions the node)
-  • only mechanics changed  → spex spec ack <node>   "checked — spec still valid"   (give a real reason)
-  • implementation is WRONG → the spec is right; fix the CODE back toward it, then ack
-  • wrong code: link        → the node shouldn't own this file (or owns it too broadly); fix frontmatter
-  • expanded spec ≠ raw     → the spec drifted from human intent; fix the expanded spec to serve the raw
-  • structural mismatch     → one file owned by many specs / a feature with no home: refactor so a file
-                              maps to a node, or file an issue and link it (defer honestly)
-
-Never patch. A reasoned ack or a real fix are recorded and re-judged at review; a blind ack is a lie.`