@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/cpg/language-parser-worker.js

@@ -0,0 +1,81 @@
+'use strict';
+/* eslint-disable @typescript-eslint/no-var-requires */
+// Runs INSIDE a dedicated worker_thread, used ONLY when running under Jest
+// (see language-parser.ts for why: the tree-sitter native addon corrupts its
+// own parse results if it is ever used a second time inside a Jest-controlled
+// process/vm-context). Production parses inline instead — this file exists
+// purely as a test-infrastructure accommodation.
+//
+// The actual symbol/edge tree-walking logic lives in language-parser-walk.js
+// and is shared with the inline (production) path; this file must not
+// reimplement it.
+const { workerData } = require('worker_threads');
+const { extractSymbolsFromTree, extractEdgesFromTree, extractDataFlowFromTree, parseWithBuffer } = require('./language-parser-walk');
+const Parser = require(workerData.parserModulePath);
+// @implements A-SPEC-121.6
+// Lang -> { modulePath, exportKey } map (see GRAMMAR_MODULE_PATHS in
+// language-parser.ts). Loading is generic over this map, so a new language
+// is one entry on the language-parser.ts side — nothing here changes.
+const grammarModulePaths = workerData.grammarModulePaths;
+// Cache loaded grammar modules by modulePath (typescript and tsx share one
+// module) and Parser instances by lang, for the life of this worker — the
+// same "load each native language binding exactly once per process" rule
+// that motivates this worker's existence in the first place (see the
+// language-parser.ts comment for the full story on tree-sitter + Jest).
+const grammarModules = new Map();
+const parsers = new Map();
+function loadGrammar(lang) {
+    const spec = grammarModulePaths[lang] || grammarModulePaths.typescript;
+    let mod = grammarModules.get(spec.modulePath);
+    if (!mod) {
+        mod = require(spec.modulePath);
+        grammarModules.set(spec.modulePath, mod);
+    }
+    return spec.exportKey ? mod[spec.exportKey] : mod;
+}
+function getParser(lang) {
+    const key = grammarModulePaths[lang] ? lang : 'typescript';
+    let parser = parsers.get(key);
+    if (!parser) {
+        parser = new Parser();
+        parser.setLanguage(loadGrammar(key));
+        parsers.set(key, parser);
+    }
+    return parser;
+}
+function extractSymbolsImpl(code, lang) {
+    // @implements A-SPEC-131 — same bufferSize form as the inline path, so jest and production see the same tree.
+    return extractSymbolsFromTree(parseWithBuffer(getParser(lang), code), lang);
+}
+function extractEdgesImpl(code, lang) {
+    return extractEdgesFromTree(parseWithBuffer(getParser(lang), code), lang);
+}
+// @implements A-SPEC-140.1
+function extractDataFlowImpl(code, lang) {
+    return extractDataFlowFromTree(parseWithBuffer(getParser(lang), code), lang);
+}
+// Explicit dispatch. The previous ternary treated "not extractSymbols" as "edges", which silently
+// made any third method return edges instead of failing — a dispatch table cannot do that.
+const METHODS = {
+    extractSymbols: extractSymbolsImpl,
+    extractEdges: extractEdgesImpl,
+    extractDataFlow: extractDataFlowImpl,
+};
+const { sharedBuffer, port } = workerData;
+const sync = new Int32Array(sharedBuffer);
+port.on('message', (msg) => {
+    let result;
+    let error;
+    try {
+        const impl = METHODS[msg.method];
+        if (!impl)
+            throw new Error(`unknown worker method: ${msg.method}`);
+        result = impl(msg.code, msg.lang);
+    }
+    catch (e) {
+        error = e && e.stack ? String(e.stack) : String(e);
+    }
+    port.postMessage({ id: msg.id, result, error });
+    Atomics.store(sync, 0, 1);
+    Atomics.notify(sync, 0);
+});

package/dist/holmes/cpg/language-parser.js

@@ -0,0 +1,234 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeSitterTsParser = exports.TreeSitterInfraError = void 0;
+exports.hasDataFlowWalk = hasDataFlowWalk;
+/* eslint-disable @typescript-eslint/no-var-requires */
+const path = __importStar(require("path"));
+const worker_threads_1 = require("worker_threads");
+/**
+ * Thrown for RPC/infrastructure failures on the jest worker_thread path
+ * (timeout, dead worker, desynchronized response) — as opposed to a genuine
+ * per-file parse exception. Callers such as CpgScanner use this to avoid
+ * silently treating a systemic worker failure as "just this file is
+ * unparseable".
+ */
+class TreeSitterInfraError extends Error {
+}
+exports.TreeSitterInfraError = TreeSitterInfraError;
+// Single source of truth for the symbol/edge tree-walking logic, shared by
+// both the inline (production) path below and the jest-only worker_thread
+// path (language-parser-worker.js) — guarantees the two paths produce
+// byte-identical results.
+const walk = require('./language-parser-walk');
+/**
+ * Whether a language has a data-flow walk at all.
+ *
+ * @implements A-SPEC-140.1
+ * Read straight from the walk's own table so the two can never drift: a caller that guessed the
+ * list would eventually claim "analysed, nothing found" for a language nothing ever looked at.
+ */
+function hasDataFlowWalk(lang) {
+    return walk.DATAFLOW_LANGS.has(lang);
+}
+/**
+ * WHY the jest-only worker_thread path exists: the tree-sitter native addon
+ * (node-tree-sitter + tree-sitter-typescript) silently corrupts its own
+ * parse results — nodes with undefined children, empty symbol lists — the
+ * SECOND time it is used inside the same OS process by a fresh Jest
+ * per-test-file sandbox/vm context (confirmed empirically: whichever test
+ * file's tree-sitter usage runs first in a process succeeds, every
+ * subsequent one in that same process fails, consistently and
+ * reproducibly). This is a JEST-only phenomenon: the identical
+ * repeated-require-and-parse pattern is harmless in a plain Node process or
+ * a hand-rolled `vm.Context` outside Jest's control (verified directly).
+ *
+ * So production parses INLINE, in-process, the simple way — no worker, no
+ * IPC, no Atomics on the hot path. Only when running under Jest
+ * (`JEST_WORKER_ID` set) do we route through a persistent worker_thread,
+ * whose V8 isolate is a plain Node realm Jest never creates, resets, or
+ * tears down, so tree-sitter only ever sees "one real load" for the life of
+ * that worker regardless of how many Jest test files share the process.
+ */
+const IN_JEST = !!process.env.JEST_WORKER_ID;
+// @implements A-SPEC-121.6
+// Lang -> grammar-loader map. Adding a new language (C#/Java/Go/Rust/C++,
+// later slices) is exactly one new entry here — no branching logic to touch.
+// Any lang not present falls back to the typescript loader, preserving the
+// pre-refactor default (the old ensure() treated every non-python lang as
+// TypeScript/TSX).
+const GRAMMAR_LOADERS = {
+    typescript: () => require('tree-sitter-typescript').typescript,
+    tsx: () => require('tree-sitter-typescript').tsx,
+    python: () => require('tree-sitter-python'),
+    csharp: () => require('tree-sitter-c-sharp'),
+    java: () => require('tree-sitter-java'),
+    go: () => require('tree-sitter-go'),
+    rust: () => require('tree-sitter-rust'),
+    cpp: () => require('tree-sitter-cpp'),
+};
+class InlineTreeSitterParser {
+    parsers = new Map();
+    ensure(lang) {
+        let parser = this.parsers.get(lang);
+        if (!parser) {
+            const Parser = require('tree-sitter');
+            parser = new Parser();
+            const loadGrammar = GRAMMAR_LOADERS[lang] ?? GRAMMAR_LOADERS.typescript;
+            parser.setLanguage(loadGrammar());
+            this.parsers.set(lang, parser);
+        }
+        return parser;
+    }
+    extractSymbols(code, lang = 'typescript') {
+        // @implements A-SPEC-131 — bufferSize form: parse(string) throws above 32,767 chars.
+        return walk.extractSymbolsFromTree(walk.parseWithBuffer(this.ensure(lang), code), lang);
+    }
+    extractEdges(code, lang = 'typescript') {
+        return walk.extractEdgesFromTree(walk.parseWithBuffer(this.ensure(lang), code), lang);
+    }
+    // @implements A-SPEC-140.1
+    extractDataFlow(code, lang = 'typescript') {
+        return walk.extractDataFlowFromTree(walk.parseWithBuffer(this.ensure(lang), code), lang);
+    }
+}
+const GRAMMAR_MODULE_PATHS = {
+    typescript: { modulePath: require.resolve('tree-sitter-typescript'), exportKey: 'typescript' },
+    tsx: { modulePath: require.resolve('tree-sitter-typescript'), exportKey: 'tsx' },
+    python: { modulePath: require.resolve('tree-sitter-python') },
+    csharp: { modulePath: require.resolve('tree-sitter-c-sharp') },
+    java: { modulePath: require.resolve('tree-sitter-java') },
+    go: { modulePath: require.resolve('tree-sitter-go') },
+    rust: { modulePath: require.resolve('tree-sitter-rust') },
+    cpp: { modulePath: require.resolve('tree-sitter-cpp') },
+};
+class TreeSitterWorkerClient {
+    worker;
+    port;
+    sync;
+    nextId = 0;
+    ensureWorker() {
+        if (this.worker)
+            return;
+        const { port1, port2 } = new worker_threads_1.MessageChannel();
+        const sharedBuffer = new SharedArrayBuffer(4);
+        this.sync = new Int32Array(sharedBuffer);
+        this.port = port1;
+        const worker = new worker_threads_1.Worker(path.join(__dirname, 'language-parser-worker.js'), {
+            workerData: {
+                sharedBuffer,
+                port: port2,
+                parserModulePath: require.resolve('tree-sitter'),
+                grammarModulePaths: GRAMMAR_MODULE_PATHS,
+            },
+            transferList: [port2],
+        });
+        // A worker crash must not surface as an uncaught exception on the main
+        // thread, and must not permanently degrade parsing: drop the dead
+        // worker's references so the next call transparently respawns one.
+        worker.on('error', () => this.resetWorker());
+        worker.on('exit', () => this.resetWorker());
+        // Don't let this background worker keep the host process alive on its own.
+        worker.unref();
+        this.worker = worker;
+    }
+    resetWorker() {
+        try {
+            this.worker?.terminate();
+        }
+        catch { /* best-effort; worker may already be gone */ }
+        this.worker = undefined;
+        this.port = undefined;
+        this.sync = undefined;
+    }
+    call(method, code, lang = 'typescript') {
+        this.ensureWorker();
+        const id = ++this.nextId;
+        Atomics.store(this.sync, 0, 0);
+        this.port.postMessage({ id, method, code, lang });
+        const status = Atomics.wait(this.sync, 0, 0, 10000);
+        if (status === 'timed-out') {
+            this.resetWorker();
+            throw new TreeSitterInfraError(`TreeSitterTsParser: worker did not respond within timeout (method=${method}); worker has been reset`);
+        }
+        const received = (0, worker_threads_1.receiveMessageOnPort)(this.port);
+        if (!received) {
+            this.resetWorker();
+            throw new TreeSitterInfraError(`TreeSitterTsParser: no message received from worker (method=${method}); worker has been reset`);
+        }
+        const msg = received.message;
+        if (msg.id !== id) {
+            // A response belonging to a different (e.g. previously timed-out)
+            // request arrived on the channel. Never hand back data the caller
+            // didn't ask for: reset the worker so no further stale messages can
+            // surface, and fail loudly for this call.
+            this.resetWorker();
+            throw new TreeSitterInfraError(`TreeSitterTsParser: stale worker response (expected id=${id}, got id=${msg.id}); worker has been reset`);
+        }
+        if (msg.error) {
+            // A genuine exception from inside the worker's own parse/walk logic —
+            // equivalent to what would be thrown by the inline path — not an
+            // infrastructure failure.
+            throw new Error(msg.error);
+        }
+        return msg.result;
+    }
+}
+const inlineParser = new InlineTreeSitterParser();
+// One worker per process, lazily started and reused by every TreeSitterTsParser
+// instance — mirrors the fact that tree-sitter's native parser has no
+// meaningful per-instance state of its own. Only ever constructed/used under
+// Jest; production never touches this.
+const sharedWorkerClient = new TreeSitterWorkerClient();
+// @implements A-SPEC-121.1
+class TreeSitterTsParser {
+    extractSymbols(code, lang = 'typescript') {
+        return IN_JEST
+            ? sharedWorkerClient.call('extractSymbols', code, lang)
+            : inlineParser.extractSymbols(code, lang);
+    }
+    extractEdges(code, lang = 'typescript') {
+        return IN_JEST
+            ? sharedWorkerClient.call('extractEdges', code, lang)
+            : inlineParser.extractEdges(code, lang);
+    }
+    // @implements A-SPEC-140.1
+    extractDataFlow(code, lang = 'typescript') {
+        return IN_JEST
+            ? sharedWorkerClient.call('extractDataFlow', code, lang)
+            : inlineParser.extractDataFlow(code, lang);
+    }
+}
+exports.TreeSitterTsParser = TreeSitterTsParser;

package/dist/holmes/cpg/scan-cache.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScanFileCache = exports.SCAN_CACHE_VERSION = void 0;
+// @implements A-SPEC-113.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+// Bump on ANY change to symbol extraction, grammar versions, or the ScannedFile schema (review D3:
+// without a version stamp, cached entries kept serving OLD-parser symbols indefinitely after an
+// upgrade — content hashes match, so nothing else invalidates them). A mismatch drops the whole
+// cache (one cold scan), which is exactly the correct cost of a parser upgrade.
+exports.SCAN_CACHE_VERSION = 3;
+class ScanFileCache {
+    dir;
+    file;
+    entries;
+    seen = new Set();
+    dirty = false;
+    hits = 0;
+    misses = 0;
+    constructor(dir) {
+        this.dir = dir;
+        this.file = path.join(dir, 'scan-cache.json');
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+            this.entries = raw && raw.v === exports.SCAN_CACHE_VERSION && raw.entries && typeof raw.entries === 'object'
+                ? raw.entries
+                : {}; // version/schema mismatch (incl. the old un-versioned flat format) -> cold scan
+        }
+        catch {
+            this.entries = {};
+        }
+    }
+    static hashOf(content) {
+        return (0, node_crypto_1.createHash)('sha256').update(content, 'utf8').digest('hex');
+    }
+    /** Cached scan result iff the stored hash matches this content. Marks the path as seen. */
+    get(sourcePath, contentHash) {
+        this.seen.add(sourcePath);
+        const e = this.entries[sourcePath];
+        if (e && e.hash === contentHash) {
+            this.hits++;
+            // Default array fields so an entry from a slightly older writer can never yield `undefined`
+            // where a fresh scan yields [] (review D3b — downstream iterates these).
+            return { ...e.file, symbols: e.file.symbols ?? [], implementsSpecs: e.file.implementsSpecs ?? [], unanchoredImplements: e.file.unanchoredImplements ?? [] };
+        }
+        this.misses++;
+        return undefined;
+    }
+    put(sourcePath, contentHash, file) {
+        this.seen.add(sourcePath);
+        this.entries[sourcePath] = { hash: contentHash, file };
+        this.dirty = true;
+    }
+    /**
+     * Persist once per scan. Mark-and-sweep: entries whose path was NOT seen this scan belong to
+     * deleted/renamed files — pruned so the cache cannot grow unboundedly. No-op when nothing changed.
+     */
+    save() {
+        const stale = Object.keys(this.entries).filter((p) => !this.seen.has(p));
+        for (const p of stale) {
+            delete this.entries[p];
+            this.dirty = true;
+        }
+        if (!this.dirty)
+            return;
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            fs.writeFileSync(this.file, JSON.stringify({ v: exports.SCAN_CACHE_VERSION, entries: this.entries }), 'utf8');
+            this.dirty = false;
+        }
+        catch { /* cache persistence is best-effort — next scan just runs colder */ }
+    }
+}
+exports.ScanFileCache = ScanFileCache;

package/dist/holmes/cpg/source-path.js

@@ -0,0 +1,44 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toSourcePath = toSourcePath;
+const path = __importStar(require("node:path"));
+/** Repo-root-relative, POSIX-normalized path used as the provenance key for graph rows. */
+// @implements A-SPEC-121.1
+function toSourcePath(repoRoot, absOrRelPath) {
+    const abs = path.isAbsolute(absOrRelPath) ? absOrRelPath : path.resolve(repoRoot, absOrRelPath);
+    const rel = path.relative(repoRoot, abs);
+    return rel.split(path.sep).join('/').replace(/^\.\//, '');
+}

package/dist/holmes/cpg/test-files.js

@@ -0,0 +1,84 @@
+"use strict";
+// @implements A-SPEC-121.1
+/**
+ * What counts as a TEST file, per ecosystem — the single table both the scanner and the phase gate
+ * read.
+ *
+ * It lives in its own module, apart from the scanner, because two very different consumers need it
+ * and only one of them can afford the scanner's dependencies. `CpgScanner` uses it to keep test
+ * symbols out of the production graph; `classifyAction` (the PreToolUse phase gate, which runs on
+ * every Write/Edit and is measured in tens of milliseconds) uses it to tell WRITE_TEST from
+ * WRITE_CODE. When the two disagree about what a test is, the harness contradicts itself: measured on
+ * a real Python target, `tests/test_briefing.py` was excluded from the graph as a test AND gated as
+ * production code, so editing it demanded a stricter chain than the code it tests.
+ *
+ * Nothing here imports anything, and that is deliberate — it is the property that lets the hook use
+ * it without pulling tree-sitter into a latency-critical path.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_FILE_PATTERNS = void 0;
+exports.isTestFile = isTestFile;
+/**
+ * Test-file conventions, one entry per ecosystem, matched against the path RELATIVE to the project
+ * root (POSIX-separated).
+ *
+ * Test code must never enter the production graph: its symbols would be counted as production, which
+ * corrupts change-impact, clustering, and any reverse-engineered spec drafted from a scan. The
+ * previous rules covered TS/JS, Python and Go only, so — measured — `AppTest.java`, `AppTests.cs`,
+ * `app_test.rs`, `tests/mod.rs` and `app_test.cpp` all leaked through.
+ *
+ * Kept as one exported table rather than scattered constants so the per-language coverage is
+ * auditable at a glance and testable as a unit; `isTestFile` is the only entry point.
+ */
+exports.TEST_FILE_PATTERNS = [
+    // TS/JS and the generic `.test.`/`.spec.` infix, which several ecosystems also use.
+    ['infix', /\.(test|spec)\.(ts|mts|cts|tsx|jsx|js|mjs|cjs|py|cs|java|go|rs|cpp|cc|cxx|hpp|hh|h)$/],
+    // pytest / unittest. `tests.py` is Django's per-app convention and `conftest.py` is pytest's
+    // fixture/config module — neither carries a `test_`/`_test` affix, so both need naming by hand.
+    ['python', /(^|\/)(test_[^/]*|[^/]*_test|tests?|conftest)\.py$/],
+    // `go test`
+    ['go', /(^|\/)[^/]*_test\.go$/],
+    // JUnit / xUnit / NUnit / MSTest. Case-sensitive on the `Test` suffix, so `Manifest.java` and
+    // `Attest.cs` are not misread as tests.
+    ['jvm-dotnet', /(^|\/)[^/]*(Test|Tests|TestCase|TestCases)\.(java|cs)$/],
+    // Cargo unit-test files and googletest. `_unittest` is gtest's other common suffix.
+    ['rust-cpp', /(^|\/)([^/]*_(tests?|unittest)|test_[^/]*)\.(rs|cpp|cc|cxx)$/],
+    // @implements A-SPEC-164
+    // googletest's other common shape. `jvm-dotnet` already does this for .java/.cs, so `ATest.java`
+    // was a test while `ATest.cpp` was not. CASE-SENSITIVE on `Test`, which is what keeps `Attest.cpp`
+    // and `Fastest.cpp` out — over-recognition is the dangerous direction here, since a source file
+    // read as a test can be written with no approved A-SPEC.
+    ['cpp-suffix', /(^|\/)[^/]*(Test|Tests)\.(cpp|cc|cxx)$/],
+    // Directory conventions, each SCOPED TO ITS LANGUAGE'S EXTENSION. These are load-bearing where
+    // the filename carries no signal at all — a Rust integration test is just `tests/foo.rs`, and a
+    // Maven/Gradle test is just `src/test/java/Foo.java`.
+    //
+    // They are language-scoped because a blanket directory rule over-excludes: an earlier version
+    // matched any `spec/` segment and silently dropped this project's own `src/holmes/spec/**`
+    // production files from the graph — the exact "silently dropping real source is the worse
+    // failure" hazard that the vendor-skip set was written to avoid. Tying each directory rule to the
+    // extensions of the ecosystem that uses that convention keeps the signal and removes the hazard.
+    ['python-dir', /(^|\/)tests?\/.*\.py$/],
+    // Any depth: a cargo integration test may pull in helper modules (`tests/common/mod.rs`), and a
+    // one-level rule would let those helpers through as production code.
+    ['rust-dir', /(^|\/)tests\/.*\.rs$/],
+    ['cpp-dir', /(^|\/)tests?\/.*\.(cpp|cc|cxx|hpp|hh|h)$/],
+    ['jvm-dir', /(^|\/)src\/test\/.*\.(java|kt|cs)$/], // Maven/Gradle standard layout
+    ['js-dir', /(^|\/)__tests__\/.*\.(ts|mts|cts|tsx|jsx|js|mjs|cjs)$/],
+    // @implements A-SPEC-164
+    // mocha's and `node:test`'s default directory. Measured before adding it: `test/a.ts` was gated as
+    // production while `test/a.cpp` was already a test — the same convention answered differently by
+    // language, which blocks test-first work in TypeScript. Scoped to the extensions like every other
+    // directory rule, because an unscoped one is exactly what once swallowed `src/holmes/spec/**`.
+    ['js-test-dir', /(^|\/)tests?\/.*\.(ts|mts|cts|tsx|jsx|js|mjs|cjs)$/],
+];
+/**
+ * True when a PROJECT-ROOT-RELATIVE POSIX path is a test file by any ecosystem's convention.
+ *
+ * The path must be relative to the project, not absolute: several rules key on a directory segment,
+ * so a repository that merely lives under some `/…/test/` directory on disk would otherwise read as
+ * one big test tree.
+ */
+function isTestFile(relPosixPath) {
+    return exports.TEST_FILE_PATTERNS.some(([, re]) => re.test(relPosixPath));
+}

package/dist/holmes/governance/constitution-debt.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeDebt = writeDebt;
+exports.readDebt = readDebt;
+exports.clearDebt = clearDebt;
+// @implements A-SPEC-134
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * The constitution-debt state (REQ-134 P3): when the Stop gate exhausts its consecutive-block cap it
+ * no longer yields silently — it records the unresolved articles here and ends the turn. While debt
+ * is outstanding the PreToolUse gate denies WRITE_CODE, so new code cannot be layered on an
+ * unverified constitution. A clean Stop clears it. The state is a small JSON file under .ax/state;
+ * every read fails safe (a corrupt/absent file is "no debt readable" → null, never a throw — a
+ * crash here would be a DoS on the very gate the debt is meant to keep honest).
+ */
+const debtFile = (root) => path.join(root, '.ax', 'state', 'constitution-debt.json');
+function writeDebt(root, articles) {
+    const f = debtFile(root);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, `${JSON.stringify({ articles, recordedAt: new Date().toISOString() }, null, 2)}\n`);
+}
+function readDebt(root) {
+    try {
+        const text = fs.readFileSync(debtFile(root), 'utf8');
+        const parsed = JSON.parse(text);
+        if (!Array.isArray(parsed.articles) || parsed.articles.length === 0)
+            return null;
+        return parsed.articles.filter((a) => typeof a === 'string');
+    }
+    catch {
+        return null; // absent or corrupt → no readable debt
+    }
+}
+function clearDebt(root) {
+    try {
+        fs.rmSync(debtFile(root), { force: true });
+    }
+    catch { /* idempotent: nothing to clear */ }
+}

package/dist/holmes/governance/constitution-report.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LISTED = void 0;
+exports.describeViolations = describeViolations;
+/**
+ * Cap on listed violations. A corpus-wide regression across 300+ specs would otherwise bury the
+ * terminal in hundreds of lines, which reads as noise and gets skipped — the same outcome as
+ * printing nothing.
+ */
+exports.MAX_LISTED = 20;
+function describeViolations(violations) {
+    if (violations.length === 0)
+        return '';
+    const lines = violations.slice(0, exports.MAX_LISTED).map((v) => {
+        // `detail` already embeds the spec id (`spec REQ-154: citation-bad-kind — ...`), so it is passed
+        // through whole. Parsing it apart and reassembling would silently yield an empty field the day
+        // the detail format changes — and that day is precisely when someone is reading this output.
+        const article = v.article ?? '(article 미상)';
+        return v.detail ? `  - ${article}: ${v.detail}` : `  - ${article}: (detail 없음)`;
+    });
+    const rest = violations.length - exports.MAX_LISTED;
+    if (rest > 0)
+        lines.push(`  ... 외 ${rest}건`);
+    return lines.join('\n');
+}