spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/lint.js

@@ -0,0 +1,476 @@
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { repoRoot, git, sourceIndexes, rowsFor, treeFilePaths, treeFileText, withEventLedgerBuild } from '@spexcode/spec-core';
+import { loadSpecs, parseFrontmatter } from '@spexcode/spec-core';
+import { readJsonConfig } from '@spexcode/spec-core';
+import { extractors, extractorFor, extOf, parseCodeEntry, relationClaimsPath, resolveSelectors, windowEvents, anchorHitQueries } from '@spexcode/spec-core';
+import { DEFAULT_TEST_GLOBS, sourcePolicyDescription, trackedSourceFiles } from './source-files.js';
+export const SPEC_LINT_REPORT_PROJECTION = 'spex.spec-lint.report';
+export const SPEC_LINT_REPORT_SCHEMA_VERSION = 1;
+const DEFAULT_CONFIG = {
+    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, pendingSource) {
+    // 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;
+    if (pendingSource === undefined)
+        parsed = readJsonConfig(join(root, 'spexcode.json'));
+    else if (pendingSource === null)
+        parsed = {};
+    else {
+        try {
+            parsed = JSON.parse(pendingSource);
+        }
+        catch (e) {
+            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) {
+    // 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) => xs.map((x) => x.replace(/^\.+/, ''));
+    const anyDepth = (xs) => 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),
+    };
+}
+function untrackedAdoptionFiles(root) {
+    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, tip) {
+    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 = [];
+        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, tip) {
+    // 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 = {}) {
+    return (await specLintRun(root, regs, options)).findings;
+}
+export async function specLintReport(root = repoRoot(), regs = extractors(root), options = {}) {
+    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, regs, options) {
+    return withEventLedgerBuild(root, () => specLintInLedger(root, regs, options));
+}
+async function specLintInLedger(root, regs, options) {
+    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();
+    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) => files ? files.has(path) || directories.has(path.replace(/\/+$/, '')) : existsSync(join(root, path));
+    const isDirectoryAtTip = (path) => files
+        ? !files.has(path) && directories.has(path.replace(/\/+$/, ''))
+        : statSync(join(root, path)).isDirectory();
+    const textAtTip = (path) => 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 = [];
+    // 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();
+    const claimed = new Set();
+    const governedClaims = new Set();
+    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 = [];
+        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) => { const segs = p.split('/'); return segs[segs.length - 2]; };
+    const byLeaf = new Map();
+    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, b) => {
+        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, k) => 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:).` });
+    }
+    const readyWarned = new Set();
+    const anchorSteps = [];
+    for (const s of specs) {
+        for (const { relation, entries } of [{ relation: 'code', entries: s.codeScoped }, { relation: 'related', 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) {
+                    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 = [];
+                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();
+        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.`;

package/node_modules/@spexcode/spec-cli/dist/listen.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from 'node:net';
+export declare function listenOrExit(server: Server, port: number, opts: {
+    host?: string;
+    label: string;
+    cleanup?: () => void;
+    onListen: () => void;
+}): void;

package/{spec-cli/src/listen.ts → node_modules/@spexcode/spec-cli/dist/listen.js}

@@ -1,5 +1,3 @@
-import type { Server } from 'node:net'
-
 // @@@ listenOrExit - the shared "I own this port; if I cannot bind it, I have failed" contract for the two
 // public-port listeners: the supervisor's raw-TCP proxy (supervise.ts) and the dashboard/public gateway
 // (gateway.ts). A bind failure is the ONE thing neither may survive — it is the opposite of the keep-serving
@@ -10,19 +8,17 @@ import type { Server } from 'node:net'
 // reap any child booted for this bind so none is orphaned, and exit non-zero.
 //
 // http.Server / https.Server both extend net.Server, so this one signature covers every caller.
-export function listenOrExit(
-  server: Server,
-  port: number,
-  opts: { host?: string; label: string; cleanup?: () => void; onListen: () => void },
-): void {
-  server.once('error', (err: NodeJS.ErrnoException) => {
-    opts.cleanup?.()
-    const why = err.code === 'EADDRINUSE' ? `port ${port} is already in use`
-      : err.code === 'EACCES' ? `permission denied binding port ${port}`
-      : err.code ?? err.message
-    console.error(`spec-cli: ${opts.label} cannot bind — ${why}. Free :${port} (e.g. lsof -i :${port}) or pick another port, then retry.`)
-    process.exit(1)
-  })
-  if (opts.host) server.listen(port, opts.host, opts.onListen)
-  else server.listen(port, opts.onListen)
+export function listenOrExit(server, port, opts) {
+    server.once('error', (err) => {
+        opts.cleanup?.();
+        const why = err.code === 'EADDRINUSE' ? `port ${port} is already in use`
+            : err.code === 'EACCES' ? `permission denied binding port ${port}`
+                : err.code ?? err.message;
+        console.error(`spec-cli: ${opts.label} cannot bind — ${why}. Free :${port} (e.g. lsof -i :${port}) or pick another port, then retry.`);
+        process.exit(1);
+    });
+    if (opts.host)
+        server.listen(port, opts.host, opts.onListen);
+    else
+        server.listen(port, opts.onListen);
 }

package/node_modules/@spexcode/spec-cli/dist/localIssues.d.ts

@@ -0,0 +1,65 @@
+import { type DispatchOutcome } from './mentions.js';
+import type { Issue } from './issues.js';
+export declare const issuesEnabled: () => boolean;
+export declare const currentSession: () => string;
+export declare function loadLocalIssues(): Issue[];
+export declare function loadOne(id: string): Issue;
+export declare function commitTrunkData(relPath: string, message: string): 'committed' | 'no-op' | 'not-primary';
+export declare function openIssue(concern: string, opts?: {
+    nodes?: string[];
+    body?: string;
+    evidence?: string[];
+    author?: string;
+}): Issue;
+export declare function reply(id: string, body: string, author?: string, evidence?: string[], remark?: {
+    targetCodeSha: string;
+}): Issue;
+export declare function replyLocalIssue(id: string, body: string, author: string, evidence?: string[], remark?: {
+    targetCodeSha: string;
+}): Promise<{
+    thread: Issue;
+    outcomes: DispatchOutcome[];
+}>;
+export declare function postLocalIssue(concern: string, opts: {
+    nodes?: string[];
+    body?: string;
+    evidence?: string[];
+    author: string;
+}): Promise<{
+    thread: Issue;
+    outcomes: DispatchOutcome[];
+}>;
+export declare function closeLocalIssue(id: string): {
+    status: 'landed';
+    already: boolean;
+};
+export declare const parseEvalConcern: (concern: string) => {
+    node: string;
+    scenario: string;
+} | null;
+export declare function remarkOnHost(host: {
+    issue?: string;
+    node?: string;
+    scenario?: string;
+}, body: string, opts?: {
+    codeSha?: string;
+    author?: string;
+    evidence?: string[];
+}): Promise<{
+    ref: string;
+    rid: string;
+    codeSha: string;
+    thread: Issue;
+    author: string;
+    outcomes: DispatchOutcome[];
+}>;
+export declare function resolveRemark(ref: string, by: string): {
+    thread: Issue;
+    rid: string;
+};
+export declare function retractRemark(ref: string, by: string): {
+    thread: Issue;
+    rid: string;
+};
+export declare function nudge(node: string): string;
+export declare function closeoutNudge(sessionId: string | null | undefined): string;