@holmes-lab/holmes-kit 0.1.0

package/dist/holmes/reverse/surface.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAME_MAX = exports.SURFACE_BUDGET = void 0;
+exports.surfaceOf = surfaceOf;
+exports.renderSurface = renderSurface;
+exports.renderTestPoints = renderTestPoints;
+exports.renderDoneWhen = renderDoneWhen;
+/**
+ * Total characters the rendered symbol list may occupy.
+ *
+ * Chosen from measurement, not taste. On the calibration target the 15 clusters hold 164, 132, 68,
+ * 53, 11 and ten single-symbol surfaces; listing EVERY one whole costs 11,460 characters (~2.9K
+ * tokens) for the entire adoption of a 203-file repository. So the bound exists to stop a
+ * pathological monorepo cluster, NOT to trim ordinary ones: at 4,000 every cluster on the target
+ * fits whole except the largest, which loses ~15% and says so.
+ *
+ * A tighter bound was tried first (1,200) and dropped 119 of 164 names — 73% of the largest slice —
+ * to save ~2K tokens across a whole adoption. That trade sends the human back to the scan report,
+ * which is the toil this REQ exists to remove.
+ */
+exports.SURFACE_BUDGET = 4000;
+/**
+ * Longest name that may be quoted. A longer one is dropped rather than truncated: a partially
+ * printed identifier cannot be searched for, so it is worse than an honest omission count.
+ */
+exports.NAME_MAX = 80;
+/** Byte-stable comparator. `localeCompare` is locale-dependent and would break determinism. */
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * The top-level, non-underscore symbols of the given files — the PUBLIC SURFACE CANDIDATES.
+ *
+ * Two mechanical filters, no natural-language judgement:
+ *
+ * 1. NESTED, decided by line range WITHIN THE SAME FILE: a symbol `s` is nested when some other
+ *    symbol `o` of that same file satisfies `o.startLine < s.startLine && o.endLine >= s.endLine`.
+ *    `>=` (not `>`) because a nested definition may end on the same line as its enclosing one.
+ *    `<` (not `<=`) on the start because two symbols reported at the same start line cannot be
+ *    ordered by containment — refusing to decide keeps both rather than deleting a real symbol.
+ *    The comparison is per-file: a wide range in one file must not swallow a narrow one in another.
+ * 2. PRIVATE, decided by a leading underscore. `build_briefing` keeps its inner underscores; only
+ *    the first character is consulted.
+ *
+ * Sorted by file then start line so the same scan always renders byte-identically.
+ */
+function surfaceOf(files) {
+    const out = [];
+    for (const f of files) {
+        for (const s of f.symbols) {
+            if (s.name.startsWith('_'))
+                continue;
+            // `o !== s` is REDUNDANT under the strict `<` — `s.startLine < s.startLine` is false, so a
+            // symbol can never contain itself. Measured on 1,101 symbols across three trees: removing it
+            // changes zero verdicts. It is kept as the guard that makes the strictness safe to revisit:
+            // relaxing the start-line comparison to `<=` without it would make every symbol its own
+            // container and empty the surface, which reads as "the scanner found nothing", not as a bug.
+            const nested = f.symbols.some((o) => o !== s && o.startLine < s.startLine && o.endLine >= s.endLine);
+            if (nested)
+                continue;
+            out.push({ file: f.sourcePath, name: s.name, kind: s.kind, startLine: s.startLine });
+        }
+    }
+    out.sort((a, b) => cmp(a.file, b.file) || a.startLine - b.startLine || cmp(a.name, b.name));
+    return out.map(({ file, name, kind }) => ({ file, name, kind }));
+}
+const EMPTY_SURFACE = '스캐너가 이 슬라이스에서 최상위 심볼을 하나도 찾지 못했다. 이 언어에 심볼 추출이 없거나, ' +
+    '이 슬라이스의 코드가 모듈 수준 문장으로만 이루어져 있다는 뜻이다 — 계약이 없다는 뜻은 아니다.';
+const header = (file) => `- \`${file}\`: `;
+/**
+ * The surface as a per-file list, bounded.
+ *
+ * Four rules, the same ones A-SPEC-183 arrived at for the gate's denial text:
+ * (1) a name is printed WHOLE or not at all; (2) if nothing fits, report a COUNT instead of a list;
+ * (3) the bound is on the TOTAL, not per item; (4) no item passes unconditionally — the first entry
+ * is budget-checked like every other, so one absurd path cannot blow the bound.
+ */
+function renderSurface(surface) {
+    if (surface.length === 0)
+        return EMPTY_SURFACE;
+    // Grouped through a Map rather than "is this the same file as the previous entry", which would
+    // silently fragment a file into several bullets if a caller ever passed an unsorted array.
+    // `surfaceOf` sorts, so today the two agree — this keeps them agreeing without the precondition.
+    const groups = new Map();
+    let used = 0;
+    let omitted = 0;
+    for (const s of surface) {
+        if (s.name.length > exports.NAME_MAX) {
+            omitted++;
+            continue;
+        }
+        const existing = groups.get(s.file);
+        // A file's header is paid once, by its first accepted name.
+        const cost = existing ? s.name.length + 2 : header(s.file).length + s.name.length + 1;
+        // Rule (4) — the first entry is budget-checked like every other. `continue`, never `break`: a
+        // later short name still fits after a long one is skipped, and `break` would discard it along
+        // with everything behind it.
+        if (used + cost > exports.SURFACE_BUDGET) {
+            omitted++;
+            continue;
+        }
+        used += cost;
+        if (existing)
+            existing.push(s.name);
+        else
+            groups.set(s.file, [s.name]);
+    }
+    const lead = `스캐너가 찾은 최상위 심볼 ${surface.length}개. 이것은 표면 **후보**이지 이 슬라이스가 약속하는 계약이 아니다.`;
+    // Rule (2): not one name fit, so say how many there are rather than printing an empty list that
+    // reads as "there is nothing here".
+    if (groups.size === 0) {
+        return `${lead}\n\n이름이 너무 길거나 경로가 너무 깊어 ${omitted}개 모두 여기에 싣지 못했다. 스캔 보고서에서 확인하라.`;
+    }
+    const body = [...groups].map(([file, names]) => `${header(file)}${names.join(', ')}`).join('\n');
+    const tail = omitted > 0 ? `\n\n(그 밖에 ${omitted}개는 길이 상한으로 생략)` : '';
+    return `${lead}\n\n${body}${tail}`;
+}
+/**
+ * The tests already attached to this slice, and — always — how many the repository could not attach
+ * to any slice at all.
+ *
+ * The unmatched count is not decoration. Measured on the calibration target the matcher attaches 46
+ * of 86 test files (53%), and the 40 it refuses are mostly its own rule's limit, not unrelated
+ * tests. A list printed without that number reads as "these are the tests for this slice".
+ */
+function renderTestPoints(ev) {
+    const head = ev.testFiles.length
+        ? `이름 증거로 이 슬라이스에 붙은 기존 테스트 ${ev.testFiles.length}개:\n\n` +
+            ev.testFiles.map((f) => `- \`${f}\``).join('\n')
+        : '이름 증거로 이 슬라이스에 붙은 기존 테스트가 없다. 테스트가 없거나, 그 이름이 대상을 밝히지 않는다는 뜻이다.';
+    const gap = ev.testsUnmatched > 0
+        ? `\n\n저장소 전체에서 어느 슬라이스에도 붙지 못한 테스트 파일이 ${ev.testsUnmatched}개 있다. ` +
+            '위 목록은 이 슬라이스를 덮는 테스트의 전부가 아닐 수 있다 — 매칭은 파일 이름의 정확한 일치만 인정한다.'
+        : '';
+    return `${head}${gap}`;
+}
+/**
+ * A completion criterion that is checkable as written, which is why this section — alone among the
+ * three A-SPEC-181 fills — does not keep a TODO and therefore does not block approval.
+ *
+ * Clause 3 is NEVER dropped when the slice has no attached test. Dropping it would leave 1 and 2
+ * standing alone and read as "done"; the absence of a regression control is this slice's largest
+ * risk and belongs in the completion criterion, not in silence. Measured on the calibration target:
+ * 11 of 15 clusters are in exactly that state.
+ */
+function renderDoneWhen(files, testFiles) {
+    const third = testFiles.length
+        ? `3. 이 슬라이스에 붙은 기존 테스트 ${testFiles.length}개가 여전히 통과한다.`
+        : '3. 이 슬라이스를 덮는 기존 테스트가 없다 — 회귀 대조군이 없다는 사실 자체가 이 슬라이스의 ' +
+            '가장 큰 위험이며, 그것을 메우는 T-SPEC이 생기기 전까지 이 항은 충족될 수 없다.';
+    return [
+        `1. 아래 ${files.length}개 파일 밖의 파일이 바뀌지 않는다 — 바뀐다면 슬라이스 경계가 틀린 것이므로 A-SPEC을 다시 자른다.`,
+        '2. 이 A-SPEC을 `depends_on`에 담은 승인된 T-SPEC의 시나리오가 모두 통과한다.',
+        third,
+    ].join('\n');
+}

package/dist/holmes/reverse/test-map.js

@@ -0,0 +1,263 @@
+"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.SEGMENT_SEPARATOR = exports.MAX_TRAILING_DROP = void 0;
+exports.subjectStems = subjectStems;
+exports.qualifierSegments = qualifierSegments;
+exports.mapTestsToClusters = mapTestsToClusters;
+// @implements A-SPEC-126
+const path = __importStar(require("node:path"));
+const draft_1 = require("./draft");
+/**
+ * Attach a brownfield project's EXISTING tests to the slices they cover.
+ *
+ * Why this exists: per-A-SPEC test evidence (`scanTestAnchors` → `computeTestScope` →
+ * `writeTestEvidence`) is read from `@implements` anchors inside TEST files, but the scanner
+ * deliberately keeps test files out of the production graph — so reverse engineering clustered the
+ * production code and left every test unanchored, and the evidence link had to be wired by hand.
+ * Measured on a real pytest target, that was 76 files of manual work standing between adoption and
+ * any per-slice test evidence at all.
+ *
+ * The mapping is by NAME EVIDENCE ONLY, and unmatched is a first-class outcome. A test whose subject
+ * cannot be identified, or whose subject lives in two different slices, is REPORTED rather than
+ * attached: an anchor is an authorship claim, and attaching one on directory proximity would be the
+ * guessing this whole slice refuses to do everywhere else.
+ */
+/**
+ * Candidate subjects a test file's name could be naming, STRONGEST FIRST.
+ *
+ * The first element is the whole name with its test convention stripped. The rest drop leading
+ * `_`-separated segments one at a time, because a test name routinely carries a suite qualifier
+ * ahead of its subject — measured on a real Python target, 62 of 74 tests were
+ * `tests/golden/test_golden_<subject>.py`, where `golden_` names the suite. A fixed vocabulary of
+ * qualifiers ("golden", "unit", "integration", …) would be a guess about someone else's conventions;
+ * offering weaker candidates and demanding a UNIQUE production match lets the target's own file names
+ * decide which reading is right. An empty list means the name identifies no subject at all.
+ */
+function subjectStems(testPath, qualifiers) {
+    const base = path.posix.basename(testPath.replace(/\\/g, '/'));
+    const name = base.replace(/\.[^.]+$/, ''); // drop the extension
+    let stem = null;
+    // `x.test.ts` / `x.spec.ts`
+    const infix = /^(.+)\.(test|spec)$/i.exec(name);
+    if (infix)
+        stem = infix[1];
+    // `test_x` / `x_test` / `x_tests` / `x_unittest`
+    if (!stem) {
+        const m = /^test_(.+)$/i.exec(name);
+        if (m)
+            stem = m[1];
+    }
+    if (!stem) {
+        const m = /^(.+)_(tests?|unittest)$/i.exec(name);
+        if (m)
+            stem = m[1];
+    }
+    // `AppTest` / `AppTests` / `AppTestCase` — JVM/.NET. Requires something before the suffix, so a
+    // file named exactly `Test.java` names no subject.
+    if (!stem) {
+        const m = /^(.+?)(Test|Tests|TestCase|TestCases)$/.exec(name);
+        if (m)
+            stem = m[1];
+    }
+    // `conftest.py`, `tests.py`, `mod.rs`, `integration.rs` — real test files that name no subject.
+    if (!stem)
+        return [];
+    const segments = stem.toLowerCase().split('_').filter(Boolean);
+    // Drop leading segments ONLY while they are corpus-attested suite qualifiers. Dropping any leading
+    // segment instead attached `test_golden_capabilities_tool.py` to `src/core/tool.py` — a generic
+    // trailing word that happened to be unique, which is an anchor placed on no real evidence.
+    const out = [];
+    for (let i = 0; i < segments.length; i++) {
+        out.push(segments.slice(i).join('_'));
+        if (!qualifiers.has(segments[i]))
+            break;
+    }
+    return out;
+}
+/**
+ * Leading name segments that the corpus itself shows to be SUITE QUALIFIERS rather than subjects.
+ *
+ * A qualifier is a word many of a project's tests start with (`golden_`, `unit_`, `integration_`),
+ * which is a property of the corpus and therefore measurable — as opposed to a vocabulary guessed in
+ * advance, which would encode one project's conventions as everyone's. The thresholds keep a
+ * coincidence from qualifying: at least three files AND at least a tenth of the suite.
+ */
+function qualifierSegments(testFiles) {
+    const counts = new Map();
+    for (const f of testFiles) {
+        const [first] = subjectStems(f, new Set()).flatMap((s) => s.split('_'));
+        if (first)
+            counts.set(first, (counts.get(first) ?? 0) + 1);
+    }
+    const min = Math.max(3, Math.ceil(testFiles.length * 0.1));
+    return new Set([...counts].filter(([, n]) => n >= min).map(([seg]) => seg));
+}
+/**
+ * How many trailing segments the `shortened` reading may drop.
+ *
+ * ONE, and the value is measured rather than chosen. At two, the calibration target gains four more
+ * matches and two of them are the false anchor this file already warns about above:
+ * `test_golden_tool_dispatch_e2e.py` lands on `src/core/tool.py`. The more segments a reading
+ * discards, the more generic the remainder becomes — and a generic word is the kind that happens to
+ * be unique by accident.
+ */
+exports.MAX_TRAILING_DROP = 1;
+/**
+ * Segment separators recognised WHEN WEAKENING a subject — `_` for python-style names, `-` for
+ * JS/TS-style ones.
+ *
+ * Deliberately not shared with `subjectStems`/`qualifierSegments`: widening the split there would
+ * change which leading segments count as suite qualifiers, and that could move matches that already
+ * exist. The weakening steps only ever run where the exact reading found nothing, so they can be
+ * broader without disturbing anything.
+ */
+exports.SEGMENT_SEPARATOR = /[_-]/;
+const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const READINGS = [
+    // Indexed, like the original rule — a full scan here would turn the whole pass quadratic for the
+    // reading that answers most of the corpus.
+    { via: 'exact', owners: (s, prod) => prod.byStem.get(s) ?? [] },
+    {
+        via: 'prefix',
+        // The only reading that must scan: a prefix is not a hash key. It runs solely for test files no
+        // stronger reading could place, so the scan is over the small tail rather than the corpus.
+        //
+        // The boundary check is the safeguard. Without it `place` attaches to `places.py` — an overlap
+        // of spelling, not of name. `p.stem.length > s.length` keeps this from restating `exact`.
+        owners: (s, prod) => prod.all.filter((p) => p.stem.length > s.length && p.stem.startsWith(s) && exports.SEGMENT_SEPARATOR.test(p.stem[s.length])),
+    },
+    {
+        via: 'shortened',
+        owners: (s, prod) => {
+            const segs = s.split(exports.SEGMENT_SEPARATOR).filter(Boolean);
+            // A single-segment subject yields nothing: dropping its only segment leaves the empty string,
+            // which would match on emptiness rather than on evidence.
+            if (segs.length <= exports.MAX_TRAILING_DROP)
+                return [];
+            const sep = s.includes('-') && !s.includes('_') ? '-' : '_';
+            // The shortened form is still an EXACT name, so it is indexed too.
+            return prod.byStem.get(segs.slice(0, segs.length - exports.MAX_TRAILING_DROP).join(sep)) ?? [];
+        },
+    },
+];
+function mapTestsToClusters(testFiles, clusters) {
+    // stem -> the production files that carry it, with the cluster each belongs to.
+    const byStem = new Map();
+    const prod = [];
+    for (const c of clusters) {
+        const key = (0, draft_1.clusterKeyOf)(c);
+        for (const f of c.files) {
+            const stem = path.posix.basename(f).replace(/\.[^.]+$/, '').toLowerCase();
+            if (!byStem.has(stem))
+                byStem.set(stem, []);
+            const owner = { file: f, clusterKey: key, stem };
+            byStem.get(stem).push(owner);
+            prod.push(owner);
+        }
+    }
+    const matched = [];
+    const unmatched = [];
+    const qualifiers = qualifierSegments(testFiles);
+    const index = { byStem, all: prod };
+    // @implements A-SPEC-185
+    // Does THIS project keep its tests beside the code they cover?
+    //
+    // Read from the LAYOUT, not from any match: how many test files sit in a directory that also
+    // holds production code. That makes the answer available even when nothing matched exactly —
+    // which is precisely the project where the weakened readings matter most, and where deciding
+    // from matches would have no evidence to decide on.
+    //
+    // Measured: the calibration target has 0 of 86 test files inside a production directory (a
+    // separate `tests/` tree); this repository has 113 of 129 (88%). The signal is 0% against 88%,
+    // not a judgement call.
+    const productionDirs = new Set(clusters.flatMap((c) => c.files).map((f) => path.posix.dirname(f)));
+    const inside = testFiles.filter((f) => productionDirs.has(path.posix.dirname(f))).length;
+    const testsSitBesideSources = inside * 2 >= testFiles.length;
+    for (const file of [...testFiles].sort(cmp)) {
+        const stems = subjectStems(file, qualifiers);
+        if (stems.length === 0) {
+            unmatched.push({ file, reason: 'the file name states no subject to map it to' });
+            continue;
+        }
+        // The STRONGEST stem that matches anything decides. A weaker one is only consulted while nothing
+        // has matched at all — once a stem finds owners, an ambiguity among them is a real ambiguity, and
+        // falling through to a less specific name would paper over it with a worse guess.
+        //
+        // @implements A-SPEC-185
+        // The same rule now governs the READINGS as well: a whole reading is tried across every stem
+        // before the next, weaker one begins, and the first reading to find any owner ends the search.
+        // Both loops stop on the first hit, so a test that already matched exactly cannot be re-decided
+        // by a weaker rule — which is why this change cannot move an existing match.
+        let hit = null;
+        for (const reading of READINGS) {
+            for (const stem of stems) {
+                // @implements A-SPEC-185
+                // A weakened name searches the WHOLE production set, so it can land in an unrelated
+                // directory. Measured, that produced two false anchors on this very repository:
+                // `mcp/surface-conformance.test.ts` (which tests stdio-client) attached to
+                // `reverse/surface.ts`, and `cpg/scan-completeness.test.ts` attached to `reverse/scan.ts`.
+                //
+                // The constraint is NOT "attach by proximity" — proximity never creates a match here. It
+                // refuses a weakened match that contradicts the project's OWN observed layout, and whether
+                // the project has that layout is measured from its already-settled exact matches rather
+                // than assumed. `exact` is exempt: a whole-name match is evidence enough, and leaving it
+                // alone is what keeps this change from moving any existing attachment.
+                const owners = reading.owners(stem, index).filter((o) => reading.via === 'exact' || !testsSitBesideSources || path.posix.dirname(o.file) === path.posix.dirname(file));
+                if (owners.length > 0) {
+                    hit = { stem, owners, via: reading.via };
+                    break;
+                }
+            }
+            if (hit)
+                break;
+        }
+        if (!hit) {
+            unmatched.push({ file, reason: `no candidate file named "${stems[0]}"` });
+            continue;
+        }
+        const keys = [...new Set(hit.owners.map((o) => o.clusterKey))].sort(cmp);
+        if (keys.length > 1) {
+            // Two slices define the same name; picking one would be a coin flip that mis-credits evidence.
+            // Reached from ANY reading, and it never falls through to a weaker one: a less specific name
+            // that happens to be unique is the false anchor this file was already burned by.
+            unmatched.push({ file, reason: `subject "${hit.stem}" is defined in ${keys.length} clusters` });
+            continue;
+        }
+        const subject = hit.owners.map((o) => o.file).sort(cmp)[0];
+        matched.push({ file, clusterKey: keys[0], subject, via: hit.via });
+    }
+    return { matched, unmatched };
+}

package/dist/holmes/review/coverage.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCANNABLE_NOTE = void 0;
+exports.partitionChangedFiles = partitionChangedFiles;
+// @implements A-SPEC-102.1
+/**
+ * Partitions changed files into two sets: those the CpgScanner ingested
+ * (scanned) and those it skipped (unscanned).
+ *
+ * A changed file is considered "scanned" iff its repo-relative POSIX path
+ * is present in the scannedSourcePaths set. This provides an honest signal
+ * about what the review actually analyzed vs what it did not (REQ-124 gate 2a).
+ *
+ * @param changedFiles - List of repo-relative POSIX paths that changed
+ * @param scannedSourcePaths - Set of repo-relative POSIX paths the scanner ingested
+ * @returns Object with sorted, deduplicated scanned and unscanned arrays
+ */
+function partitionChangedFiles(changedFiles, scannedSourcePaths) {
+    const scannedSet = new Set(scannedSourcePaths);
+    const uniqueChanged = [...new Set(changedFiles)];
+    const scanned = uniqueChanged
+        .filter((f) => scannedSet.has(f))
+        .sort();
+    const unscanned = uniqueChanged
+        .filter((f) => !scannedSet.has(f))
+        .sort();
+    return { scanned, unscanned };
+}
+/**
+ * Human-readable description of what the CpgScanner ingests.
+ * Used to make the "unscanned" signal self-documenting in review output.
+ */
+exports.SCANNABLE_NOTE = 'CpgScanner analyzes the TS/JS family (.ts/.mts/.cts/.tsx/.jsx/.js/.mjs/.cjs, incl. JSX), Python (.py), C# (.cs), Java (.java), Go (.go), Rust (.rs), and C++ (.cpp/.cc/.cxx/.hpp/.hh/.h) — the Aider-Polyglot + C# language set — extracting function/class/method symbols and @implements anchors. Excludes *.test.*/*.spec.*, Python (test_*.py/*_test.py) and Go (*_test.go) test files; skips node_modules/dist/.git. Call/import EDGES are extracted for TS/JS only (other languages: symbols + anchors, edges deferred). Other languages (e.g. Kotlin/Swift/Ruby/PHP) appear as unscanned.';

package/dist/holmes/review/findings.js

@@ -0,0 +1,123 @@
+"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.FindingsLedger = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// @implements A-SPEC-102.1
+/**
+ * Append-only, spec/code-linked audit trail of review findings. Each call to
+ * `record` appends one JSON line per finding to a `.jsonl` file — never
+ * truncated, never rewritten — so the file itself is the durable evidence
+ * trail (Decision-Event style) that a diff-only review lacks.
+ *
+ * Ids and timestamps are caller-supplied: this ledger has no clock and no id
+ * generator, so recording is fully deterministic given its inputs.
+ */
+class FindingsLedger {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /**
+     * @implements A-SPEC-157
+     * `basis` is a SEPARATE argument, not a field on the findings, so the caller cannot choose it.
+     * Optional because making it required would break every existing call site without declaring it
+     * (ADR-013 tier ③); when it is absent, no basis is written and that absence is observable.
+     */
+    record(findings, basis) {
+        if (findings.length === 0)
+            return;
+        const lines = findings.map((f) => FindingsLedger.serialize(f, basis)).join('');
+        fs.mkdirSync(path.dirname(this.path), { recursive: true });
+        fs.appendFileSync(this.path, lines, 'utf8');
+    }
+    list(filter) {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.path, 'utf8');
+        }
+        catch (err) {
+            // Missing file: no findings recorded yet, not an error. Any other
+            // failure (EACCES, a directory at this path, etc.) must NOT be
+            // swallowed: silently returning [] here would make review_status
+            // report blocked:false despite recorded open critical/important
+            // findings — a silent gate pass.
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        const findings = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                // `null`/scalars/`[]` ARE valid JSON, so parse alone let them through — and a null row
+                // crashed every consumer that dereferenced `.status` (measured: verifyConstitution threw,
+                // the Stop hook's outer catch exited 0, and the gate failed OPEN over an open critical).
+                // A row without a string id is the same corrupt-line class as unparseable JSON.
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+                    || typeof parsed.id !== 'string')
+                    continue;
+                findings.push(parsed);
+            }
+            catch {
+                // Corrupt line: skip it rather than throwing away the whole ledger.
+                continue;
+            }
+        }
+        return findings.filter((f) => (filter?.status === undefined || f.status === filter.status) &&
+            (filter?.severity === undefined || f.severity === filter.severity));
+    }
+    /** Ordered-object serialization so identical findings always produce identical bytes. */
+    static serialize(f, basis) {
+        // Rebuilding from a whitelist is what makes the caller's own `basis` unable to survive: it is
+        // never copied from `f`, so there is no path — not even "observe nothing and let theirs
+        // through" — by which a supplied value reaches the ledger.
+        const ordered = {
+            id: f.id,
+            severity: f.severity,
+            category: f.category,
+            file: f.file,
+            specRef: f.specRef,
+            summary: f.summary,
+            status: f.status,
+            ...(basis !== undefined ? { basis } : {}),
+        };
+        return JSON.stringify(ordered) + '\n';
+    }
+}
+exports.FindingsLedger = FindingsLedger;

package/dist/holmes/review/package.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleReviewPackage = assembleReviewPackage;
+const scope_1 = require("./scope");
+const bundler_1 = require("../context/bundler");
+const DEFAULT_MAX_SEEDS = 8;
+/**
+ * Assembles a review package: the review scope (impacted specs, acceptance
+ * criteria, coverage gaps, etc.) plus a graph-scoped context bundle seeded at
+ * each impacted spec AND at each changed code symbol, so a reviewer sees the
+ * impacted specs, the changed code itself, and their neighborhoods — the
+ * surpass point over a diff-only review.
+ *
+ * Pure/deterministic given the injected content source: no Date, randomness,
+ * or LLM calls. Same inputs always yield a deep-equal ReviewPackage.
+ */
+// @implements A-SPEC-102.1
+function assembleReviewPackage(graph, specs, changedSymbols, content, budget, opts) {
+    const scope = (0, scope_1.computeReviewScope)(graph, specs, changedSymbols);
+    const maxSeeds = opts?.maxSeeds ?? DEFAULT_MAX_SEEDS;
+    const perSeedBudget = opts?.perSeedBudget ?? budget;
+    // Seed universe = impacted specs (SPEC:*) ∪ changed code symbols (CODE:*),
+    // deduped and sorted into a single deterministic total order.
+    // @implements A-SPEC-121.4
+    // Resolve each changed qn to its REAL (source_path-qualified) node id(s) via
+    // graph.codeNodeIds — a bare `CODE:<qn>` id matches no node in the graph
+    // post-A-SPEC-121.3, so BFS from it would silently yield an empty
+    // (content-less) bundle instead of the actual changed-symbol content. A qn
+    // with no matching node contributes no seed at all (empty array, not a
+    // crash); a qn shared across files contributes one seed per file.
+    const codeSeeds = scope.changedSymbols.flatMap((qn) => graph.codeNodeIds(qn));
+    const seedUniverse = [...new Set([...scope.impactedSpecs, ...codeSeeds])].sort();
+    const seeds = seedUniverse.slice(0, maxSeeds);
+    const droppedSeeds = seedUniverse.slice(maxSeeds).sort();
+    const bundles = seeds.map((seedId) => ({
+        seedId,
+        bundle: new bundler_1.ContextBundler(graph, content).getContextBundle(seedId, perSeedBudget),
+    }));
+    return { scope, bundles, droppedSeeds };
+}