@holmes-lab/holmes-kit 0.18.0 → 0.19.2

package/dist/holmes/hooks/stop.js

@@ -42,6 +42,7 @@ exports.escalateReappraisals = escalateReappraisals;
 exports.unrecordedApprovals = unrecordedApprovals;
 exports.rolledBackLedgers = rolledBackLedgers;
 exports.governanceLostPreflight = governanceLostPreflight;
+exports.trackedLines = trackedLines;
 exports.evaluateStop = evaluateStop;
 exports.stopDebtAction = stopDebtAction;
 exports.acknowledgeStop = acknowledgeStop;
@@ -62,6 +63,8 @@ const node_child_process_1 = require("node:child_process");
 const path = __importStar(require("node:path"));
 const test_scope_1 = require("../rtm/test-scope");
 const constitution_1 = require("../governance/constitution");
+// @implements A-SPEC-574.4 — same detector as the design-time advisory and the strict article.
+const cycle_detect_1 = require("../cpg/cycle-detect");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const test_evidence_1 = require("../review/test-evidence");
 const test_outcomes_1 = require("../review/test-outcomes");
@@ -430,6 +433,36 @@ function governanceLostPreflight(specsDir, projectRoot) {
     const root = projectRoot ?? path.resolve(specsDir, '..', '..');
     return (0, governance_history_1.hasGovernanceHistory)(root) ? governance_history_1.GOVERNANCE_LOST_HINT : null;
 }
+// @implements A-SPEC-578.1
+/** What each article's track observations are called on the operator's screen. */
+const TRACK_LABELS = {
+    'ART-8': 'RED-first',
+    'ART-2': 'code-graph cycles',
+};
+/**
+ * One line per ARTICLE, each under its own name.
+ *
+ * This used to be a single line reading `ART-8 RED-first (track)` for everything in `tracked` —
+ * and the cycle ratchet pushes ART-2 findings into that same array, so an import cycle was
+ * reported to the operator as a RED-first violation. Two observers sharing one sentence means the
+ * sentence is wrong for at least one of them.
+ *
+ * An article with no label still speaks, under its bare name: a new observer that says nothing is
+ * worse than one that says something plain.
+ */
+function trackedLines(tracked) {
+    if (!tracked || tracked.length === 0)
+        return [];
+    const byArticle = new Map();
+    for (const t of tracked) {
+        const key = String(t?.article ?? '');
+        byArticle.set(key, [...(byArticle.get(key) ?? []), String(t?.detail ?? '')]);
+    }
+    return [...byArticle.entries()].map(([article, details]) => {
+        const label = TRACK_LABELS[article];
+        return `[Holmes-Kit] ${article}${label ? ` ${label}` : ''} (track): ${details.join(' | ')}`;
+    });
+}
 function evaluateStop(specs, evidence) {
     // L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
     // inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
@@ -439,6 +472,7 @@ function evaluateStop(specs, evidence) {
     const violations = (0, constitution_1.verifyConstitution)({
         specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
         redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
+        cycles: evidence?.cycles,
     });
     // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
     // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
@@ -449,6 +483,17 @@ function evaluateStop(specs, evidence) {
         if (t.length)
             tracked = t;
     }
+    // @implements A-SPEC-574.4 — the cycle ratchet's track posture: recorded, never blocking. Promotion
+    // to `strict` waits on the observation ledger answering the false-positive rate, which is the same
+    // path impactAdvisory and anchorDensity took.
+    if (evidence?.cycles !== undefined && evidence.cycles.mode === 'track') {
+        const scope = evidence.cycles.scope.unavailable.length > 0
+            ? ` (NOT judged: ${evidence.cycles.scope.unavailable.join(', ')})` : '';
+        const t = (0, cycle_detect_1.cycleRatchetViolations)(evidence.cycles.current, evidence.cycles.allowed)
+            .map((x) => ({ article: 'ART-2', detail: `code ${x.detail}${scope}` }));
+        if (t.length)
+            tracked = [...(tracked ?? []), ...t];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -876,6 +921,77 @@ if (require.main === module) {
                 changedAspecs = undefined;
                 outcomesByAspec = undefined;
             }
+            // @implements A-SPEC-574.4 — the code graph's acyclicity, judged where the code exists. The
+            // scan is the same one every other layer uses; the classification reads only the files an
+            // import edge starts from. Fail-open in every direction: any error leaves the article silent,
+            // because "we could not look" must never be reported as "there is nothing there".
+            let cycles;
+            try {
+                const root = stopProjectRoot();
+                const { CpgScanner } = require('../cpg/cpg-scanner');
+                const scanned = new CpgScanner().scan(root, root);
+                const known = new Set(scanned.map((f) => f.sourcePath));
+                const edges = [];
+                const judged = new Set();
+                const sawImports = new Set();
+                for (const f of scanned) {
+                    const ext = f.sourcePath.slice(f.sourcePath.lastIndexOf('.'));
+                    let text = '';
+                    try {
+                        text = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    let sawImport = false;
+                    for (const e of f.edges ?? []) {
+                        if (e.rel !== 'imports' || !e.to)
+                            continue;
+                        sawImport = true;
+                        if (!e.to.startsWith('.'))
+                            continue;
+                        const base = path.posix.normalize(path.posix.join(path.posix.dirname(f.sourcePath), e.to));
+                        const to = ['.ts', '.tsx', '.js', '/index.ts'].map((x) => base + x).find((c) => known.has(c))
+                            ?? (known.has(base) ? base : null);
+                        if (to === null || to === f.sourcePath)
+                            continue;
+                        edges.push({ from: f.sourcePath, to, kind: (0, cycle_detect_1.classifyEdgeByTarget)(text, f.sourcePath, to) });
+                        judged.add(ext);
+                    }
+                    // A file whose imports are all bare specifiers is not evidence that its LANGUAGE is
+                    // unresolvable — subtract the judged set at the end instead of marking per file, or one
+                    // such file makes the whole language read as unjudged (measured: `.ts` and `.js` landed in
+                    // both lists).
+                    if (sawImport)
+                        sawImports.add(ext);
+                }
+                cycles = {
+                    current: (0, cycle_detect_1.detectCycles)(edges).cycles,
+                    allowed: [],
+                    mode: 'track',
+                    // Unjudged = saw imports, resolved none, anywhere. Naming these is the difference between
+                    // "no cycles" and "no cycles in the languages we could follow".
+                    scope: {
+                        judged: [...judged].sort(),
+                        unavailable: [...sawImports].filter((e) => !judged.has(e)).sort(),
+                    },
+                };
+                // @implements A-SPEC-578.1 — record the observation the promotion criterion waits on.
+                // EVERY run, including a clean one: a false-positive rate is violations over chances, and a
+                // ledger that only speaks when something is wrong keeps the numerator and drops the
+                // denominator. Append failure is swallowed by the outer catch below — an observation that
+                // could change a verdict would be a gate wearing another name.
+                // Its OWN try: sharing the outer one would let a fault in the observation discard the
+                // article's evidence, which is the coupling this comment exists to deny.
+                try {
+                    const { appendCycleObservation, buildCycleObservation } = require('../cpg/cycle-observation');
+                    appendCycleObservation(root, buildCycleObservation(cycles, new Date().toISOString()));
+                }
+                catch { /* an observation never touches the verdict */ }
+            }
+            catch {
+                cycles = undefined;
+            }
             // Provenance-chain verification (fail-open: a verify error skips the check, never crashes).
             let provenance;
             // @implements A-SPEC-148
@@ -973,9 +1089,9 @@ if (require.main === module) {
                 }
             }
             catch { /* the reappraisal signal is advisory; a failure never affects the stop verdict */ }
-            if (out.tracked && out.tracked.length > 0) {
-                process.stderr.write(`[Holmes-Kit] ART-8 RED-first (track): ${out.tracked.map((t) => t.detail).join(' | ')}\n`);
-            }
+            // @implements A-SPEC-578.1 — one line per article, each under its own name.
+            for (const line of trackedLines(out.tracked))
+                process.stderr.write(`${line}\n`);
             // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
             // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
             // non-waiting violation and we block exactly as before.

package/dist/holmes/mcp/defuse-bound.d.ts

@@ -0,0 +1 @@
+export declare const DEFUSE_TOP_FILES = 10;

package/dist/holmes/mcp/defuse-bound.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFUSE_TOP_FILES = void 0;
+// @implements A-SPEC-573.4
+// One constant, imported by both consumers, so the product path and the benchmark cannot drift on
+// how much data flow they read. Ten is the emission tier a caller acts on; whole-repository
+// extraction was measured at +88.8% (2572ms -> 4857ms, 2026-09-08) and ten files at roughly 95ms.
+exports.DEFUSE_TOP_FILES = 10;

package/dist/holmes/mcp/handlers.d.ts

@@ -223,6 +223,11 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         graphPreview?: {
             impact?: import("../rtm/impact-advisory").ImpactAdvisory;
             density?: import("../rtm/anchor-density").AnchorDensityFinding[];
+            cycles?: {
+                findings: import("../cpg/cycle-detect").CycleFinding[];
+                note: string;
+            };
+            architecture?: import("../cpg/arch-observe").ArchObservation[];
             graphAsOf?: string;
         } | undefined;
         id: string;
@@ -485,6 +490,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             survivors: import("../spec/kills").Mutation[];
         };
     } | {
+        calibrationClosed?: string[] | undefined;
         baselineRecorded?: string | undefined;
         scopeFallback?: "full" | undefined;
         tier: import("../rtm/test-scope").RegressionTier;
@@ -513,6 +519,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         changedFiles?: string[];
     }): Promise<MaintenanceAnalysis & {
         persistedTo?: string;
+        bounded?: boolean;
     }>;
     maintenance_outcome(a: {
         root: string;

package/dist/holmes/mcp/handlers.js

@@ -45,6 +45,8 @@ exports.collectDecisions = collectDecisions;
 // @implements A-SPEC-277
 // @implements A-SPEC-269
 // @implements A-SPEC-267
+// @implements A-SPEC-573.4 — shared with the benchmark so the two cannot drift.
+const defuse_bound_1 = require("./defuse-bound");
 const fs = __importStar(require("node:fs"));
 const http = __importStar(require("node:http"));
 const assoc_arm_1 = require("../assoc/assoc-arm");
@@ -205,6 +207,8 @@ const ledger_timeline_1 = require("../governance/ledger-timeline");
 const version_conflict_1 = require("../spec/version-conflict");
 const ledger_store_1 = require("../governance/ledger-store");
 const provenance_chain_1 = require("../governance/provenance-chain");
+// @implements A-SPEC-574.3 — the caller owns the store and hands the chain the question.
+const ledger_store_2 = require("../governance/ledger-store");
 const ledger_lock_1 = require("../governance/ledger-lock");
 const decision_ledger_1 = require("../guardrail/decision-ledger");
 const cspec_change_1 = require("../guardrail/cspec-change");
@@ -1375,7 +1379,63 @@ function makeRawHandlers(store, opts) {
                                 return null;
                             } });
                             const density = anchorDensityFindings(ftt, graph.implementsAnchorCounts());
-                            if (impact || density.length > 0) {
+                            // @implements A-SPEC-574.2 — the computation lives in cycle-detect; this file holds
+                            // the wiring only (measured: 85 anchors here against a p90 of 7).
+                            const { cycleAdvisory, classifyEdgeByTarget, CYCLE_ADVISORY_NOTE } = require('../cpg/cycle-detect');
+                            const readCache = new Map();
+                            const readSource = (rel) => {
+                                const hit = readCache.get(rel);
+                                if (hit !== undefined)
+                                    return hit;
+                                // A read failure degrades to the conservative kind rather than losing the finding.
+                                let text = '';
+                                try {
+                                    text = fs.readFileSync(path.join(a.root, rel), 'utf8');
+                                }
+                                catch {
+                                    text = '';
+                                }
+                                readCache.set(rel, text);
+                                return text;
+                            };
+                            const cycleFindings = cycleAdvisory(ftt, graph.importEdges().map((edge) => ({
+                                ...edge,
+                                kind: classifyEdgeByTarget(readSource(edge.from), edge.from, edge.to),
+                            })));
+                            // @implements A-SPEC-574.5 — the same import edges the cycle pass already read, plus
+                            // the parent-time symbol spans the graph already holds. No new scan, no new parse.
+                            const { architectureObservation } = require('../cpg/arch-observe');
+                            const { TreeSitterTsParser } = require('../cpg/language-parser');
+                            const { langForPath } = require('../cpg/cpg-scanner');
+                            // Bounded to the DECLARED files, whose text is read once and used for both numbers.
+                            const archParser = new TreeSitterTsParser();
+                            const archText = new Map();
+                            const readArch = (f) => {
+                                if (!archText.has(f)) {
+                                    try {
+                                        archText.set(f, fs.readFileSync(path.join(a.root, f), 'utf8'));
+                                    }
+                                    catch {
+                                        archText.set(f, null);
+                                    }
+                                }
+                                return archText.get(f) ?? null;
+                            };
+                            const spans = new Map(ftt.map((f) => {
+                                const text = readArch(f);
+                                if (text === null)
+                                    return [f, []];
+                                try {
+                                    return [f, archParser.extractSymbols(text, langForPath(f))
+                                            .filter((sy) => sy.kind !== 'class')
+                                            .map((sy) => ({ startLine: sy.startLine, endLine: sy.endLine }))];
+                                }
+                                catch {
+                                    return [f, []];
+                                }
+                            }));
+                            const arch = architectureObservation(ftt, spans, graph.importEdges(), (f) => { const t = readArch(f); return t === null ? null : t.split('\n').length; });
+                            if (impact || density.length > 0 || cycleFindings.length > 0 || arch.length > 0) {
                                 const graphAsOf = (() => { try {
                                     return fs.statSync(dbPath).mtime.toISOString();
                                 }
@@ -1385,6 +1445,9 @@ function makeRawHandlers(store, opts) {
                                 graphPreview = {
                                     ...(impact ? { impact } : {}),
                                     ...(density.length > 0 ? { density } : {}),
+                                    ...(cycleFindings.length > 0
+                                        ? { cycles: { findings: cycleFindings, note: CYCLE_ADVISORY_NOTE } } : {}),
+                                    ...(arch.length > 0 ? { architecture: arch } : {}),
                                     ...(graphAsOf ? { graphAsOf } : {}),
                                 };
                             }
@@ -2304,6 +2367,9 @@ function makeRawHandlers(store, opts) {
             // Record ONLY an actually-executed, GREEN run (review C4/C7): a red suite must not stand as
             // coverage evidence at the moment the code is broken, and a no-op run must not overwrite a real
             // record with a dishonest `passed: true` over an empty result.
+            // @implements A-SPEC-578.4 — read BEFORE the write below replaces it: the calibration window
+            // is "since the previous evidence run", and this line is the only moment that value exists.
+            const previousEvidenceTs = (0, test_evidence_1.readTestEvidence)(root)?.ts;
             const verified = (0, baseline_1.shouldRecordBaseline)(result);
             if (verified) {
                 (0, test_evidence_1.writeTestEvidence)(root, { ts: new Date().toISOString(), head, tier: testScope.tier, passed: true, executedByAspec });
@@ -2319,6 +2385,19 @@ function makeRawHandlers(store, opts) {
             // actually executed and passed. A red or skipped run must never become the reference point for
             // "since the last verified state" — that would silently narrow every later scope against a
             // state nobody verified.
+            // @implements A-SPEC-578.4 — close the calibration loop on real work.
+            // The window is the PREVIOUS evidence run's timestamp, read before this run overwrote it —
+            // an analysis older than that belonged to a previous slice, and attributing today's changes
+            // to it would be contamination rather than measurement. Its own try: an observation that
+            // could change `passed` would be a gate wearing another name.
+            let calibrationClosed;
+            try {
+                const closed = (0, maintenance_evidence_1.closeOpenArtifacts)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), { files: changedFiles }, new Date().toISOString(), previousEvidenceTs).closed;
+                if (closed.length > 0)
+                    calibrationClosed = closed;
+            }
+            catch { /* the loop is observation; it never touches the verdict */ }
+            // @implements A-SPEC-128
             let baseline;
             if (verified) {
                 baseline = a.mark ?? DEFAULT_BASELINE;
@@ -2330,7 +2409,8 @@ function makeRawHandlers(store, opts) {
                 ranFiles: result.ranFiles, executedByAspec, tail: result.tail,
                 // @implements A-SPEC-130 — the remediation rides in the answer: these are the files to anchor.
                 unresolvedFiles: testScope.unresolvedFiles,
-                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}) };
+                changeSource, ...(scopeFallback ? { scopeFallback } : {}), ...(baseline ? { baselineRecorded: baseline } : {}),
+                ...(calibrationClosed ? { calibrationClosed } : {}) };
         },
         async issue_localize(a) {
             assertSpecStoreReachable('issue_localize', store, a.root); // @implements A-SPEC-419
@@ -2515,7 +2595,7 @@ function makeRawHandlers(store, opts) {
                             commitTextBoost[hit.file] = hit.score / top;
                 }
                 catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
-                const analysis = (0, maintenance_analyze_1.analyzeMaintenance)({
+                const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
                     semantic,
                     ...common,
                     coverage: { ...common.coverage, historyStatus },
@@ -2524,7 +2604,43 @@ function makeRawHandlers(store, opts) {
                     commitTextBoost,
                     contextBundle,
                     groundTruth: a.groundTruth,
+                    defUse,
                 });
+                // @implements A-SPEC-573.4 — def-use for the TOP CANDIDATES ONLY. Extracting it for the whole
+                // repository costs +88.8% (measured 2026-09-08), well past this slice's budget; the first pass
+                // says which handful of files are worth parsing, and the second pass reads their data flow.
+                // Every step is fail-open: a parse failure, an unsupported language or a missing file leaves
+                // the candidate's symbols exactly as the first pass produced them.
+                const firstPass = analyzeWith();
+                const analysis = (() => {
+                    const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((c) => c.file);
+                    if (targets.length === 0)
+                        return firstPass;
+                    const defUse = {};
+                    try {
+                        const { TreeSitterTsParser, hasDataFlowWalk } = require('../cpg/language-parser');
+                        const { langForPath } = require('../cpg/cpg-scanner');
+                        const parser = new TreeSitterTsParser();
+                        for (const file of targets) {
+                            try {
+                                // The LANGUAGE matters: the first wiring omitted it and parsed Python as TypeScript,
+                                // which produced wrong facts and cost the second corpus 0.2376 -> 0.1741 on the
+                                // symbol axis. A language with no walk is skipped rather than guessed at.
+                                const lang = langForPath(file);
+                                if (!hasDataFlowWalk(lang))
+                                    continue;
+                                const facts = parser.extractDataFlow(fs.readFileSync(path.join(root, file), 'utf8'), lang);
+                                if (facts !== undefined)
+                                    defUse[file] = facts;
+                            }
+                            catch { /* one unreadable or unparseable file must not cost the other nine */ }
+                        }
+                    }
+                    catch {
+                        return firstPass;
+                    }
+                    return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
+                })();
                 // @implements A-SPEC-268 — persistence is OPT-IN. The tool is advertised read-only, and a
                 // regression pins that a cold project gains no `.ax/cpg_cache`; writing evidence by default
                 // would break that contract for every caller who only wanted to look.
@@ -2544,9 +2660,19 @@ function makeRawHandlers(store, opts) {
                         if (digest)
                             fileDigests[file] = digest;
                     }
+                    // The artifact takes the WHOLE analysis, never the bounded one below: a file has no
+                    // context window, and the calibration that scores this prediction must score what the
+                    // product actually predicted.
                     result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
                 }
-                return result;
+                // @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
+                // 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
+                // it, which is why AGENTS.md step 3 had never once been obeyed with `persist: true`.
+                // `persistedTo` rides along so the caller knows where the whole thing is.
+                const bounded = (0, maintenance_analyze_1.boundAnalysis)(result);
+                if (JSON.stringify(bounded).length !== JSON.stringify(result).length)
+                    bounded.bounded = true;
+                return bounded;
             }
             finally {
                 graph.close();
@@ -3092,7 +3218,7 @@ function makeRawHandlers(store, opts) {
                             summary: `consumed single-use approval for: review-resolve ${envLiftedCriticals.join(', ')}`.slice(0, 200),
                             inputs: [(0, provenance_chain_1.nonceFingerprint)(String(approval.nonce))], rationale: approval.rationale,
                             authorization: (0, provenance_chain_1.authorizationRef)(approval.actor, approval.token),
-                        });
+                        }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
                         if (!won) {
                             throw new HandlerRefusal(`review_record: 단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 거부됩니다. 새 승인을 발급받으십시오`);
                         }
@@ -3222,7 +3348,7 @@ function makeRawHandlers(store, opts) {
                         summary: `consumed single-use approval for: ${coverTarget.kind} ${(0, provenance_chain_1.redactTarget)('command', coverTarget.target)}`.slice(0, 200),
                         inputs: [(0, provenance_chain_1.nonceFingerprint)(String(a.approval.nonce))], rationale: a.approval.rationale,
                         authorization: (0, provenance_chain_1.authorizationRef)(a.approval.actor, a.approval.token),
-                    });
+                    }, { isNonceConsumed: (0, ledger_store_2.nonceConsumedIn)(ledgerFile) });
                 }
                 catch {
                     won = false;

package/dist/holmes/mcp/history-admission.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrow history-derived candidates to files that could be source at all.
+ *
+ * The predicate is the SCANNER's, not the replay corpus's truth predicate — scoring against a
+ * filter copied from the metric would be gaming it. Deliberately NOT membership in the scanned
+ * set: a file a commit CREATES does not exist in the parent-time scan, and admitting exactly such
+ * files is A-SPEC-388's boundary contract. Every offender measured above is excluded by the
+ * extension test alone (.jsonl / .json / .md), so the stronger predicate would have cost that
+ * contract and bought nothing.
+ *
+ * Order is preserved because the downstream RRF lists are position-indexed.
+ */
+export declare function admitHistoryFiles(historyFiles: readonly string[]): string[];
+/** The lexical path's predicate (localize.ts), restated so both channels demote the same trees. */
+export declare const isVendorPath: (p: string) => boolean;

package/dist/holmes/mcp/history-admission.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVendorPath = void 0;
+exports.admitHistoryFiles = admitHistoryFiles;
+// @implements A-SPEC-573.1
+// The commit-prose channel (A-SPEC-388) lets files the lexical layer never scored ENTER the
+// candidate pool — that is where its measured gain comes from (Top-10 recall 0.393 -> 0.601). But
+// its keys come from git history, so it also admits files that CANNOT be the answer: this
+// repository's ledger JSONL, the last-green baseline, CHANGELOG.md. Measured 2026-09-08 over 12
+// real commit-subject requests: 76 of 120 emitted candidate slots (63.3%) went to such files, and
+// one took the emission head. The channel is not the problem; its POPULATION is.
+const cpg_scanner_1 = require("../cpg/cpg-scanner");
+/**
+ * Narrow history-derived candidates to files that could be source at all.
+ *
+ * The predicate is the SCANNER's, not the replay corpus's truth predicate — scoring against a
+ * filter copied from the metric would be gaming it. Deliberately NOT membership in the scanned
+ * set: a file a commit CREATES does not exist in the parent-time scan, and admitting exactly such
+ * files is A-SPEC-388's boundary contract. Every offender measured above is excluded by the
+ * extension test alone (.jsonl / .json / .md), so the stronger predicate would have cost that
+ * contract and bought nothing.
+ *
+ * Order is preserved because the downstream RRF lists are position-indexed.
+ */
+function admitHistoryFiles(historyFiles) {
+    const admitted = historyFiles.filter((file) => !file.endsWith('.d.ts') && cpg_scanner_1.SCANNABLE_EXTENSIONS.some((ext) => file.endsWith(ext)));
+    // @implements A-SPEC-573.2 — the lexical path halves a vendored file's score AND orders vendored
+    // last (localize.ts). Entering at score 0, this channel bypassed both: measured 2026-09-08, the
+    // only two non-source candidates the extension test let through were vendored files and BOTH held
+    // the emission head. Demote, never drop — vendored code is the answer in some projects, which is
+    // why the lexical path orders rather than filters. Stable within each group: the downstream RRF
+    // lists are position-indexed.
+    return [...admitted.filter((f) => !(0, exports.isVendorPath)(f)), ...admitted.filter(exports.isVendorPath)];
+}
+/** The lexical path's predicate (localize.ts), restated so both channels demote the same trees. */
+const isVendorPath = (p) => /(^|\/)(reference|vendor|vendors|third_party|third-party|external)\//i.test(p);
+exports.isVendorPath = isVendorPath;

package/dist/holmes/mcp/maintenance-analyze.d.ts

@@ -117,6 +117,14 @@ export interface MaintenanceAnalysisInput {
      * that is the whole result.
      */
     commitTextBoost?: Record<string, number>;
+    /**
+     * @implements A-SPEC-573.4
+     * Def-use facts for a BOUNDED set of files — the caller extracts them, because this core does no
+     * I/O. Extracting them for the whole repository costs +88.8% (measured 2026-09-08, 2572ms ->
+     * 4857ms), which is why the callers pass the top candidates only. Absent means "not extracted",
+     * and the symbols then read exactly as they did before this existed.
+     */
+    defUse?: Record<string, import('../cpg/language-parser').DataFlowFacts>;
     contextBundle?: ContextBundle | null;
     /**
      * @implements A-SPEC-290
@@ -436,3 +444,40 @@ export declare function unquoteGitPath(line: string): string;
  * reproduce and compare an analysis from the exact same captured inputs.
  */
 export declare function analyzeMaintenance(input: MaintenanceAnalysisInput): MaintenanceAnalysis;
+/**
+ * Items a response lists before it starts counting instead.
+ *
+ * TEN, because that is the unit this product is measured in: localization emits Top-10 and every
+ * recall figure in this repository is recall@10. Aligning the response cap with the emission unit
+ * is a reason; picking a number that happens to hit a size target is a knob. Measured on the real
+ * 187,174-character response: cap 20 gave 34,811 with `intent` alone at 11,037 (32%), cap 10 fits.
+ */
+export declare const ANALYZE_LIST_CAP = 10;
+/** Characters one listed item keeps. */
+export declare const ANALYZE_TEXT_CAP = 400;
+/**
+ * @implements A-SPEC-578.5
+ * The RESPONSE-EDGE projection. The artifact on disk keeps everything.
+ *
+ * Measured 2026-09-09: one `maintenance_analyze` call returns 187,174 characters (~47k tokens) and
+ * the harness refuses it outright. AGENTS.md step 3 instructs every agent to make that call before
+ * editing source — and across 2,779 spec approvals `persist:true` had never been used once. An
+ * instruction nobody can afford to follow is not an instruction.
+ *
+ * The cap is applied RECURSIVELY, which the first cut got wrong. Capping only the top level took
+ * the response from 187,174 to 142,701 and no further, because the weight is in NESTED DUPLICATES:
+ * `impacts.test` and `testScope.impactedTestFiles` carry the same 158 paths, and `impacts.contract`
+ * and `testScope.impactedSpecs` the same 160 spec ids. A cap that stops at depth one caps the
+ * cheapest arrays in the document.
+ *
+ * NEVER CALLED FROM `analyzeMaintenance`. The design-time advisory named the replay benchmark
+ * (`run-replay.ts`, `replay-corpus.ts`, `commit-text.ts`, `temporal-prior.ts`) as readers of this
+ * type, and among their anchors sits A-SPEC-402 — "the numbers reported are not what the product
+ * does". Bounding inside the analysis would make every pinned benchmark score a truncated
+ * pipeline, which is the most expensive instrument failure this repository has recorded. The
+ * benchmark keeps seeing exactly what it sees today; only the conversation gets the short form.
+ *
+ * What is dropped is COUNTED, at whatever depth it was dropped. A response that quietly shrank
+ * would be a worse lie than a long one.
+ */
+export declare function boundAnalysis(a: MaintenanceAnalysis): MaintenanceAnalysis;