@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/review-evidence.js

@@ -0,0 +1,370 @@
+"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.createReviewEvidenceHandlers = createReviewEvidenceHandlers;
+// @implements A-SPEC-617, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-133, A-SPEC-135, A-SPEC-141, A-SPEC-157, A-SPEC-160, A-SPEC-189, A-SPEC-191, A-SPEC-244, A-SPEC-245, A-SPEC-263.1, A-SPEC-497.1
+const path = __importStar(require("node:path"));
+const findings_1 = require("../../review/findings");
+const review_targets_1 = require("../../review/review-targets");
+const elicit_approval_1 = require("../elicit-approval");
+const basis_1 = require("../basis");
+const ledger_store_1 = require("../../governance/ledger-store");
+const ledger_lock_1 = require("../../governance/ledger-lock");
+const approval_grants_1 = require("../../governance/approval-grants");
+const provenance_chain_1 = require("../../governance/provenance-chain");
+function createReviewEvidenceHandlers(context) {
+    return {
+        async review_record(a) {
+            // @implements A-SPEC-189 §8 (round 11) — §15 shut the door the merge gate READS through and
+            // left the one it is WRITTEN through wide open. Measured: `review_record` joined the caller's
+            // `root` straight into a path and created `.ax/ledger/findings.jsonl` in any directory on the
+            // machine, answering `{recorded: N}` — while `review_status`, bound to this server's project,
+            // could never see those findings. An open critical filed at the wrong root is worse than none:
+            // it reads as recorded and gates nothing. The two doors now ask the same question.
+            const foreignWrite = context.foreignRootReason(a.root);
+            if (foreignWrite !== null)
+                throw context.refusal(`review_record: ${foreignWrite}`);
+            // MCP input is unvalidated JSON: an out-of-enum severity or status
+            // (e.g. a typo like "blocker") would land in the ledger as a stray
+            // value that review_status's counts never match, so it counts toward
+            // neither its own bucket nor `blocked` — a mislabeled critical could
+            // silently pass the gate. Validate up front so the gate's counts stay
+            // trustworthy.
+            const validSeverities = new Set(['critical', 'important', 'minor']);
+            const validStatuses = new Set(['open', 'resolved']);
+            for (const f of a.findings) {
+                if (!validSeverities.has(f.severity)) {
+                    throw context.refusal(`review_record: finding ${f.id} has invalid severity ${JSON.stringify(f.severity)} (must be one of critical|important|minor)`);
+                }
+                if (!validStatuses.has(f.status)) {
+                    throw context.refusal(`review_record: finding ${f.id} has invalid status ${JSON.stringify(f.status)} (must be one of open|resolved)`);
+                }
+            }
+            // @implements A-SPEC-191 (§4e) — the ledger's meaning is guarded at RECORD time, where the
+            // collision actually happens. Measured: conventional ids (C1…) recur across review rounds, so
+            // one round's resolve of "C1" silently lifted the gate over ANOTHER round's unfixed critical;
+            // and a severity-downgrade re-open cleared ART-7 with no resolution at all. Both die at one
+            // door: an id whose latest state is open cannot be opened again — resolve first, then
+            // re-record. Lifting an open CRITICAL requires the out-of-band approval channel (ART-5's
+            // principle): the blocked party must not be able to pull its own teeth in-band. A resolved
+            // record for an id never opened lifts nothing and stays approval-free (found-and-fixed audit
+            // records keep working).
+            // The guard and the append hold ONE lock (round-6: the read→judge→append section was a
+            // cross-process TOCTOU — two sessions both recorded open under the same id, silencing an
+            // open critical at both readers; consumeNonceExclusively already earned this discipline).
+            const findingsFile = context.boundFindingsLedger(a.root);
+            // @implements A-SPEC-263.1 — elicitation happens BEFORE the lock: the human may take up to
+            // the wiring's timeout to answer, and holding the findings ledger lock for that long starves
+            // every other writer (the lock callback is synchronous by design). This is a best-effort
+            // PRE-SCAN over an unlocked snapshot: for each finding that LOOKS like an open-critical lift
+            // not covered by env/grant, ask now and carry the grant into the lock as data. TOCTOU folds
+            // fail-closed — state moved so the lift is no longer needed → the grant is simply unused;
+            // state moved so a lift IS needed that the snapshot missed → no grant → the standard refusal.
+            const elicitGrants = new Map();
+            // A DENY at pre-scan is carried as data too (round-1): throwing here judged a stale snapshot —
+            // a finding concurrently resolved by someone else no longer needs a lift inside the lock, and
+            // the human's "no" must not abort a batch that never needed the question. The deny bites only
+            // at the in-lock site, and only if the lift is ACTUALLY needed there.
+            const elicitDenials = new Map();
+            // @implements A-SPEC-497.1 — an expiry is carried as data like a denial: it bites only at the
+            // in-lock refusal site, where it prefixes the standard message so the agent can tell the user
+            // a session dialog died (instead of the anonymous "no approval" the old null-fold produced).
+            const elicitExpiries = new Map();
+            if (context.hasElicitor()) {
+                try {
+                    const snapshot = new Map();
+                    for (const f of new findings_1.FindingsLedger(findingsFile).list())
+                        snapshot.set(f.id, f);
+                    for (const f of a.findings) {
+                        const last = snapshot.get(f.id);
+                        if (!(f.status === 'resolved' && last?.status === 'open' && last.severity === 'critical'))
+                            continue;
+                        const raw0 = process.env.HOLMES_APPROVAL;
+                        let env0;
+                        try {
+                            env0 = raw0 ? JSON.parse(raw0) : undefined;
+                        }
+                        catch {
+                            env0 = undefined;
+                        }
+                        if (context.resolveHandlerApproval(a.root, env0, { kind: 'review-resolve', target: f.id }, new Date().toISOString()) !== undefined)
+                            continue; // an open door never summons a human
+                        const out = await context.tryElicit('review-resolve', f.id, `열린 치명 발견 ${f.id} 의 해소 기록`);
+                        if (out.kind === 'answered' && out.decision.granted)
+                            elicitGrants.set(f.id, context.elicitApproval(out.decision.reason));
+                        else if (out.kind === 'answered')
+                            elicitDenials.set(f.id, out.decision.reason ?? '(사유 없음)');
+                        else if (out.kind === 'expired')
+                            elicitExpiries.set(f.id, out.waitedMs);
+                    }
+                }
+                catch {
+                    // A pre-scan failure is never worse than no channel: fall through with no grants.
+                }
+            }
+            (0, ledger_lock_1.withLedgerLock)(findingsFile, () => {
+                const ledger = new findings_1.FindingsLedger(findingsFile);
+                const latest = new Map();
+                const liftedCriticals = [];
+                const envLiftedCriticals = []; // lifts the ENV approval authorized (round-1: nonce charges only these)
+                const grantConsumptions = []; // spent AFTER the batch validates (round-2)
+                const elicitationLifts = []; // ledgered per lift (round-5: the promised audit trace)
+                for (const f of ledger.list())
+                    latest.set(f.id, f);
+                for (const f of a.findings) {
+                    if (!f.id || !f.id.trim()) {
+                        throw context.refusal('review_record: finding id 가 비어 있습니다 — 모든 발견은 원장에서 유일하게 식별될 id 가 필요합니다');
+                    }
+                    // Round-5: pre-round-4 ads declared `message`, but the ledger whitelist persists only
+                    // `summary` — clients following the OLD ad lost their text with zero signal. A pointed
+                    // refusal turns that silent loss into the one-line fix it needs.
+                    // Round-9: `=== undefined` let `summary: null` through, so the ledger dropped the text
+                    // and the caller saw success — the very silence this guard exists to end. Absence is
+                    // null OR undefined here, as everywhere else in this validator's vocabulary.
+                    if ('message' in f && (f.summary === undefined || f.summary === null)) {
+                        throw context.refusal(`review_record: finding ${f.id} 의 message 는 폐지된 광고 키입니다 — 원장은 summary 만 보존합니다. 같은 내용을 summary 로 보내십시오`);
+                    }
+                    const last = latest.get(f.id);
+                    if (f.status === 'open' && last?.status === 'open') {
+                        throw context.refusal(`review_record: id ${f.id} 는 이미 미해소(open) 상태입니다 — 다른 발견이면 새 id 를 쓰고, 같은 발견의 갱신이면 먼저 resolved 를 기록한 뒤 재기록하십시오 (id 충돌이 남의 critical 을 침묵시키는 것을 막는 문입니다)`);
+                    }
+                    if (f.status === 'resolved' && last?.status === 'open' && last.severity === 'critical') {
+                        // @implements A-SPEC-191 §11 — checked BEFORE any approval is resolved or consumed
+                        // (round-2): with the guard after resolution, a single-use elicitation grant (or grant
+                        // file) was spent on the FIRST lift, so the second occurrence saw "no approval" and
+                        // surfaced a bogus set-HOLMES_APPROVAL message plus a queue entry for an act a human
+                        // already decided. The double-lift is named honestly on EVERY channel, and nothing
+                        // single-use is touched by a batch that dies here.
+                        if (liftedCriticals.includes(f.id)) {
+                            throw context.refusal(`review_record: 한 배치에서 같은 발견(${f.id})의 치명 해소를 두 번 들 수 없습니다 — 승인은 행위마다 필요합니다`);
+                        }
+                        const raw = process.env.HOLMES_APPROVAL;
+                        let approval;
+                        try {
+                            approval = raw ? JSON.parse(raw) : undefined;
+                        }
+                        catch {
+                            approval = undefined;
+                        }
+                        // covers, not merely well-formed (round-2): A-SPEC-133 built the seam so one token is
+                        // not a master key — an EXPIRED or elsewhere-scoped approval must not lift a critical.
+                        // An unscoped {actor,token,rationale} stays the operator's session key (unchanged).
+                        const nowTs = new Date().toISOString();
+                        let rrResolved = context.resolveHandlerApproval(a.root, approval, { kind: 'review-resolve', target: f.id }, nowTs);
+                        // @implements A-SPEC-263.1 — the second (and last) elicitable kind. The HUMAN was asked
+                        // BEFORE the lock (pre-scan above — a lock must not wait on a person); in here the grant
+                        // is plain data, consumed synchronously and at most once per id.
+                        if (rrResolved === undefined) {
+                            const g = elicitGrants.get(f.id);
+                            if (g) {
+                                elicitGrants.delete(f.id);
+                                rrResolved = { approval: g, source: 'elicitation' };
+                                elicitationLifts.push({ id: f.id, approval: g });
+                            }
+                        }
+                        if (rrResolved === undefined) {
+                            // A pre-scan DENY surfaces HERE — only when the lift is genuinely needed at lock time
+                            // (round-1). The human decided, so the answer is the message and nothing is queued.
+                            const denied = elicitDenials.get(f.id);
+                            if (denied !== undefined) {
+                                throw context.refusal(`review_record: 세션에서 거부됨 — ${denied}. 사유를 해소한 뒤 다시 기록하십시오.`);
+                            }
+                            // @implements A-SPEC-497.1 — an expired dialog leads the refusal by name; silence
+                            // keeps the pre-elicitation face.
+                            const expiredMs = elicitExpiries.get(f.id);
+                            throw context.refusal((expiredMs !== undefined ? (0, elicit_approval_1.expiredNotice)(expiredMs) : '')
+                                + `review_record: id ${f.id} 의 열린 치명 발견을 해소하는 기록은 이 행위를 덮는 유효한 대역외 승인이 필요합니다 — 차단당한 쪽이 스스로 이빨을 뽑을 수 없어야 하고, 만료·다른 범위의 승인은 덮지 않습니다. HOLMES_APPROVAL='{"actor":"<you>","token":"<any>","rationale":"<why fixed>"}' (범위를 쓰면 kind "review-resolve") 를 서버 환경에 설정하고 다시 기록하십시오`
+                                + context.refusalQueueHint(a.root, { kind: 'review-resolve', target: f.id, why: '열린 치명 발견의 해소 기록' }));
+                        }
+                        // Grant-file consumption is DEFERRED past the loop (round-2): consuming here burned the
+                        // single-use file when a LATER finding in the batch failed validation — nothing was
+                        // recorded, yet the operator's legitimate grant was gone and the retry refused. Same
+                        // harm class the env nonce fixed in its round-4; collected now, spent only once the
+                        // whole batch has validated (directly before the append, like the nonce block).
+                        if (rrResolved.source === 'grant' && rrResolved.root && rrResolved.approval.nonce) {
+                            grantConsumptions.push({ root: rrResolved.root, nonce: rrResolved.approval.nonce });
+                        }
+                        liftedCriticals.push(f.id);
+                        // The nonce block below enforces single-use on the ENV approval — so it must key on the
+                        // lifts the ENV approval actually authorized (round-1): before elicitation existed,
+                        // reaching it implied env/grant coverage, but an elicitation-authorized lift flows past
+                        // it with a possibly unrelated env token in the environment. Charging THAT token burned
+                        // an innocent nonce, misattributed the ledger line, and a stale env nonce made a
+                        // human-approved lift permanently refusable.
+                        if (rrResolved.source === 'env')
+                            envLiftedCriticals.push(f.id);
+                    }
+                    latest.set(f.id, f); // 한 배치 안의 순서도 기록 순서다
+                }
+                // A-SPEC-133 promises nonce = single-use "consumed on the ledger, a replay is denied".
+                // Consumed AFTER the whole batch validates and ONCE per call (round-4: consuming inside
+                // the loop burned the grant when a LATER row failed validation — the audit trail asserted
+                // an act that never happened, the retry was refused, and two resolves in one batch would
+                // have double-spent). Consumption directly precedes the append; the only failure between
+                // them is the append itself, which throws loudly.
+                // ONE NONCE, ONE ACT — on the grant channel too (round-4): the round-2 deferral removed the
+                // arity the in-loop spend had accidentally enforced, so a wide-scoped single-use grant
+                // backed N lifts in one batch while the same lifts split across calls refused after the
+                // first (the §13 batch-shape dependence). Checked BEFORE anything is spent (round-3 order
+                // doctrine: every throwable validation precedes every single-use spend).
+                {
+                    const liftsPerNonce = new Map();
+                    for (const g of grantConsumptions)
+                        liftsPerNonce.set(g.nonce, (liftsPerNonce.get(g.nonce) ?? 0) + 1);
+                    for (const [, n] of liftsPerNonce) {
+                        if (n > 1) {
+                            throw context.refusal(`review_record: 단일 사용 승인(grant)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 한 grant 로 ${n}건을 듭니다. 한 건씩 보내십시오`);
+                        }
+                    }
+                }
+                // The elicitation channel's AUDIT TRACE (round-5, repositioned round-6): the trust model
+                // admits review-resolve at a boundary closer than env/grant BECAUSE every grant is ledgered
+                // under an `elicitation:<client>` actor. This append is throwable I/O (chain lock
+                // contention, disk faults), so it stands BEFORE every single-use spend — round-5 placed it
+                // between the env-nonce spend and the findings append, and a lock-contended mixed batch
+                // burned the operator's env nonce with nothing recorded (the §7 doctrine regression). A
+                // failure HERE burns nothing; an orphaned event left when a LATER step throws stays honest,
+                // because it records the AUTHORIZATION, which already happened at pre-scan.
+                if (elicitationLifts.length > 0) {
+                    const chain = new ledger_store_1.FileLedgerStore(path.join(context.projectRootOf(a.root), '.ax', 'ledger'));
+                    for (const lift of elicitationLifts) {
+                        chain.append({
+                            ts: new Date().toISOString(), actor: lift.approval.actor, kind: 'review-resolve-authorized',
+                            summary: `elicitation grant authorized lifting open critical ${lift.id}`.slice(0, 200),
+                            inputs: [lift.id], rationale: lift.approval.rationale,
+                            authorization: (0, provenance_chain_1.authorizationRef)(lift.approval.actor, lift.approval.token),
+                        });
+                    }
+                }
+                // Keyed on the lifts the ENV approval AUTHORIZED, not on the ambient env var (round-1):
+                // an elicitation- or grant-authorized lift must not charge — or be blocked by — an env
+                // token that never covered the act. When env authorized nothing, its nonce is untouched.
+                if (envLiftedCriticals.length > 0) {
+                    const raw = process.env.HOLMES_APPROVAL;
+                    let approval;
+                    try {
+                        approval = raw ? JSON.parse(raw) : undefined;
+                    }
+                    catch {
+                        approval = undefined;
+                    }
+                    if ((0, provenance_chain_1.blankNonce)(approval?.nonce)) {
+                        throw context.refusal('review_record: 승인이 단일 사용(nonce)을 선언했으나 값이 비어 있습니다 — 1회성을 집행할 수 없어 거부합니다');
+                    }
+                    // @implements A-SPEC-191 §13 — 1회용 승인은 한 번의 행위를 authorize 한다. 9라운드
+                    // 실측: 서로 다른 id 의 치명 해소 N 건이 한 배치에서 nonce 한 장으로 통과했고,
+                    // 같은 세 건을 세 호출로 나누면 두 번째부터 거부됐다 — 판정이 묶음 방식에 의존했다.
+                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce) && envLiftedCriticals.length > 1) {
+                        throw context.refusal(`review_record: 단일 사용 승인(nonce)은 한 건의 치명 해소만 authorize 합니다 — 이 배치는 ${envLiftedCriticals.length}건(${envLiftedCriticals.join(', ')})을 듭니다. 한 건씩 보내십시오`);
+                    }
+                    if ((0, provenance_chain_1.nonceDeclared)(approval?.nonce)) {
+                        // @implements A-SPEC-191 §10 — the same bound anchor as risk_check: two consumers must
+                        // spend into ONE ledger, or a nonce spent here reopens the gate there (and back).
+                        const ledgerFile = context.boundNonceLedger();
+                        if (ledgerFile === null) {
+                            throw context.refusal('review_record: 단일 사용 승인(nonce)을 기록할 프로젝트 원장을 확정할 수 없습니다 — 1회성을 보장할 수 없어 거부합니다');
+                        }
+                        const won = (0, provenance_chain_1.consumeNonceExclusively)(String(approval.nonce), ledgerFile, {
+                            ts: new Date().toISOString(), actor: approval.actor, kind: 'nonce-consumed',
+                            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_1.nonceConsumedIn)(ledgerFile) });
+                        if (!won) {
+                            throw context.refusal(`review_record: 단일 사용 승인(nonce)이 이미 소비되었습니다 — 재사용은 거부됩니다. 새 승인을 발급받으십시오`);
+                        }
+                    }
+                }
+                // Deferred single-use spends — LAST, after every throwable validation including the
+                // env-nonce block above (round-3: placed before it, a mixed batch's env-nonce refusal
+                // burned the grant with nothing recorded — the exact harm the round-2 deferral was written
+                // to fix, reintroduced through the env throw path). Only the append itself follows, and it
+                // fails loudly.
+                for (const g of grantConsumptions)
+                    (0, approval_grants_1.consumeGrantFile)(g.root, g.nonce);
+                // @implements A-SPEC-157 — the server's OWN observation, not anything the caller sent.
+                // @implements A-SPEC-160 — the ONLY caller that reads the on-disk build, so the divergence
+                // marker can be sealed. Append INSIDE the same lock as the guard (round-6 TOCTOU).
+                ledger.record(a.findings, (0, basis_1.basisDigest)(context.basisFor(a.root, true)));
+            });
+            return { recorded: a.findings.length };
+        },
+        async review_status(a) {
+            // @implements A-SPEC-191 §15 — the merge gate must not answer about a project it did not read.
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign !== null)
+                throw context.refusal(`review_status: ${foreign}`);
+            // @implements A-SPEC-191 (§4f) — counted on the LATEST record per id, the same folding the
+            // constitution's ART-7 uses. Line-based counting could never decrease on an append-only
+            // ledger, so the canonical exit (a resolved line) left `blocked: true` forever while the Stop
+            // gate passed — two official verdicts about one ledger, disagreeing permanently (measured).
+            const all = new findings_1.FindingsLedger(context.boundFindingsLedger(a.root)).list();
+            const latest = new Map();
+            // Severity of the LATEST open row per id — a forever-sticky "ever critical" set resurrected
+            // a properly-closed critical when a later minor re-finding got a diverged resolve (r6).
+            const lastOpenCritical = new Map();
+            for (const f of all) {
+                latest.set(f.id, f);
+                if (f.status === 'open')
+                    lastOpenCritical.set(f.id, f.severity === 'critical');
+            }
+            // SAME ledger meaning as ART-7 (round-3: the two official readers disagreed): a resolution
+            // sealed on a diverged build does not close a critical here either. What it keeps open is
+            // the CRITICAL it failed to close — bucketing by the resolved line's own severity let a
+            // severity-downgraded diverged resolve report blocked:false while the Stop gate blocked
+            // (round-4 HIGH), and a severity-less row minted an "undefined" bucket.
+            const counts = { critical: 0, important: 0, minor: 0 };
+            for (const f of latest.values()) {
+                if (f.status === 'open') {
+                    if (Object.prototype.hasOwnProperty.call(counts, f.severity))
+                        counts[f.severity]++; // in-체크는 프로토타입 키(toString)로 새었다(r6)
+                    continue;
+                }
+                if (f.status === 'resolved' && lastOpenCritical.get(f.id) === true && (0, basis_1.basisDiverged)(f.basis))
+                    counts.critical++;
+            }
+            // @implements A-SPEC-135
+            // Surface outstanding P4 routing signals: specs whose approved content moved, with the anchored
+            // files awaiting targeted review. This is a backlog to route human attention, NOT a hard block —
+            // the review layer decides severity — so it does not touch `blocked`.
+            // @implements A-SPEC-189 §12 (round 12) — the findings moved onto the bound project in §8 and
+            // this line stayed on the caller's raw root, so the SAME project answered with or without a
+            // P4 routing backlog depending on how its root was spelled (a subdirectory passes the
+            // project-level foreign check). One question, one tree.
+            const reviewNeeded = (0, review_targets_1.readReviewNeeded)(path.join(path.dirname(context.boundFindingsLedger(a.root)), 'provenance.jsonl'));
+            return { blocked: counts.critical > 0 || counts.important > 0, open: counts, reviewNeeded };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/review-queries.d.ts

@@ -0,0 +1,68 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { ChangeSourceInfo } from '../../project/change-source';
+import { ContentSource } from '../../context/bundler';
+export interface ReviewQueryContext {
+    listSpecs(): Promise<Spec[]>;
+    assertStoreReachable(tool: string, root: unknown): void;
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot: string): ScannedFile[];
+    buildContentSource(specs: Spec[], scanned: ScannedFile[]): ContentSource;
+    deriveChangedContext(root: string, args: {
+        base?: string;
+        head?: string;
+        since?: string;
+    }, tool: string): Promise<{
+        root: string;
+        specs: Spec[];
+        scanned: ScannedFile[];
+        changedFiles: string[];
+        changedSymbols: string[];
+        changeSource: ChangeSourceInfo;
+        scopeFallback?: 'full';
+        anchorImpactedSpecs: string[];
+        changedTestFiles: string[];
+        unresolvedFiles: string[];
+    }>;
+}
+export declare function createReviewQueryHandlers(context: ReviewQueryContext): {
+    context_bundle(a: {
+        root: string;
+        seedId: string;
+        budget: number;
+    }): Promise<import("../../context/bundler").ContextBundle>;
+    review_scope(a: {
+        root: string;
+        base?: string;
+        head?: string;
+        since?: string;
+    }): Promise<{
+        scopeFallback?: "full" | undefined;
+        unscannedChangedFiles: string[];
+        testScope: import("../../rtm/test-scope").TestScope;
+        changeSource: ChangeSourceInfo;
+        changedSymbols: string[];
+        impactedSpecs: string[];
+        acceptanceCriteria: Array<{
+            specId: string;
+            criteria: string;
+        }>;
+        unrequestedSymbols: string[];
+        coverageGaps: string[];
+        obligationGaps: string[];
+    }>;
+    review_prepare(a: {
+        root: string;
+        base?: string;
+        head?: string;
+        since?: string;
+        budget?: number;
+    }): Promise<{
+        scopeFallback?: "full" | undefined;
+        package: import("../../review/package").ReviewPackage;
+        unscannedChangedFiles: string[];
+        changeSource: ChangeSourceInfo;
+    }>;
+};

package/dist/holmes/mcp/handlers/review-queries.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReviewQueryHandlers = createReviewQueryHandlers;
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const test_scope_1 = require("../../rtm/test-scope");
+const bundler_1 = require("../../context/bundler");
+const scope_1 = require("../../review/scope");
+const package_1 = require("../../review/package");
+const coverage_1 = require("../../review/coverage");
+function createReviewQueryHandlers(context) {
+    return {
+        async context_bundle(a) {
+            context.assertStoreReachable('context_bundle', a.root); // @implements A-SPEC-433
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            const specs = await context.listSpecs();
+            const scanned = context.cachedScan(root, root);
+            const content = context.buildContentSource(specs, scanned);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                return new bundler_1.ContextBundler(g, content).getContextBundle(a.seedId, a.budget);
+            }
+            finally {
+                g.close(); // release native SQLite handle even if bundling throws
+            }
+        },
+        async review_scope(a) {
+            context.assertStoreReachable('review_scope', a.root); // @implements A-SPEC-419
+            // Guard+diff+scan+changedFiles/changedSymbols prologue: see
+            // deriveChangedContext (shared with review_prepare/rtm_reindex).
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await context.deriveChangedContext(a.root, a, 'review_scope');
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const scope = (0, scope_1.computeReviewScope)(g, specs, changedSymbols);
+                // Intelligent regression test-scope (target-arch §5). Test files are scanned SEPARATELY for
+                // their @implements anchors (the CPG scan excludes tests), coverage gaps feed the safety
+                // fallback, and impactedSpecs are the graph's SPEC:-prefixed ids (stripped inside).
+                // @implements A-SPEC-130 — the same widened set as test_run, so review packaging and test
+                // scoping cannot disagree about what a change touches.
+                const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
+                const testScope = (0, test_scope_1.computeTestScope)(widenedImpacted, (0, test_scope_1.scanTestAnchors)(root), specs, scope.coverageGaps, undefined, { changedTestFiles, unresolvedFiles, architectureTouched: (0, test_scope_1.architectureGoverningFiles)(changedFiles), obligationGaps: scope.obligationGaps });
+                // Honest signal (REQ-124 gate 2a): which changed files the CpgScanner
+                // did NOT ingest (e.g. non-.ts files), computed from the same
+                // changedFiles/scanned already derived above — no new git/scan calls.
+                const { unscanned: unscannedChangedFiles } = (0, coverage_1.partitionChangedFiles)(changedFiles, scanned.map((f) => f.sourcePath));
+                return { ...scope, unscannedChangedFiles, testScope, changeSource, ...(scopeFallback ? { scopeFallback } : {}) };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if scope computation throws
+            }
+        },
+        async review_prepare(a) {
+            context.assertStoreReachable('review_prepare', a.root); // @implements A-SPEC-419
+            // Guard+diff+scan+changedFiles/changedSymbols prologue: see
+            // deriveChangedContext (shared with review_scope/rtm_reindex).
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback } = await context.deriveChangedContext(a.root, a, 'review_prepare');
+            // ContentSource factory shared with context_bundle: see buildContentSource.
+            const content = context.buildContentSource(specs, scanned);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const pkg = (0, package_1.assembleReviewPackage)(g, specs, changedSymbols, content, a.budget ?? 4000);
+                // Honest signal (REQ-124 gate 2a): which changed files the CpgScanner
+                // did NOT ingest, computed from the same changedFiles/scanned already
+                // derived above — no new git/scan calls.
+                const { unscanned: unscannedChangedFiles } = (0, coverage_1.partitionChangedFiles)(changedFiles, scanned.map((f) => f.sourcePath));
+                return { package: pkg, unscannedChangedFiles, changeSource, ...(scopeFallback ? { scopeFallback } : {}) };
+            }
+            finally {
+                g.close(); // release native SQLite handle even if assembly throws
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/risk-assessment.d.ts

@@ -0,0 +1,25 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { Approval, Enforcement } from '../../guardrail/risk-gate';
+import { RiskAction } from '../../guardrail/risk-types';
+export interface RiskAssessmentContext {
+    listSpecs(): Promise<Spec[]>;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot?: string): ScannedFile[];
+    boundNonceLedger(): string | null;
+}
+export declare function createRiskAssessmentHandlers(context: RiskAssessmentContext): {
+    risk_check(a: {
+        root?: string;
+        action: RiskAction;
+        approval?: Approval;
+        changedSymbols?: string[];
+        enforcement?: Enforcement;
+        ts: string;
+        actor?: string;
+        rationale?: string;
+    }): Promise<{
+        assessment: import("../../guardrail/risk-types").RiskAssessment;
+        gate: import("../../guardrail/risk-gate").GateResult;
+    }>;
+};