@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/taint-screening.js

@@ -0,0 +1,183 @@
+"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.createTaintScreeningHandlers = createTaintScreeningHandlers;
+// @implements A-SPEC-611, A-SPEC-100.2, A-SPEC-128, A-SPEC-138, A-SPEC-140.2, A-SPEC-189, A-SPEC-461, A-SPEC-512.2, A-SPEC-513.1, A-SPEC-524.1
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const taint_1 = require("../../rtm/taint");
+function createTaintScreeningHandlers(context) {
+    return {
+        /**
+         * @implements A-SPEC-138
+         * Call-graph taint REACHABILITY screen: source-named functions that reach sink-named functions
+         * through call edges. A SCREENING signal that routes a security review, NOT a data-flow proof —
+         * the result always carries the honesty envelope (kind + limits) and phrases pairs as "reaches",
+         * never "vulnerable".
+         */
+        async taint_scan(a) {
+            // @implements A-SPEC-461 — same §15 defence as rtm_check: refuse a root that is not this
+            // server's project rather than scanning it against the bound store's specs.
+            {
+                const foreign = context.foreignRootReason(a.root);
+                if (foreign)
+                    return { ok: false, reason: foreign };
+            }
+            const root = context.projectRootOf(a.root);
+            const scanned = context.cachedScan(root, root);
+            const g = new rtm_graph_1.RtmGraph();
+            try {
+                (0, rtm_builder_1.buildRtm)(await context.listSpecs(), scanned, g);
+                const cfg = taint_1.DEFAULT_TAINT_CONFIG;
+                const { pairs, truncated } = (0, taint_1.taintReachability)(g, cfg);
+                const base = { kind: 'call-reachability', limits: [...taint_1.TAINT_LIMITS], maxPaths: cfg.maxPaths, truncated, pairs };
+                if (a.dataFlow !== true)
+                    return base;
+                // @implements A-SPEC-512.2
+                // OPT-IN def-use lane. Measured 2026-09-02: extracting data-flow facts over this
+                // repository costs 7.6s on top of the scan, which is why this follows the `cpg_scan
+                // lints:true` precedent instead of running by default. Before this slice the engine
+                // (A-SPEC-140.1, with its own 13-case benchmark) had NO caller at all — capability
+                // present, unreachable. Findings are filtered by reaching definitions: inter-procedural
+                // arrival is preserved, and only what the DDG positively refutes is dropped.
+                const { TreeSitterTsParser } = require('../../cpg/language-parser');
+                const { taintDataFlow, DATAFLOW_LIMITS } = require('../../rtm/dataflow-taint');
+                const { filterFindingsForFile } = require('../../rtm/reaching-def-filter');
+                // @implements A-SPEC-513.1 — vocabulary is SELECTED per file language, never unioned:
+                // Python's `input(` must not taint a TypeScript `input`, and `req.body` means nothing in
+                // Python. Measured on jarvis: the shipped (JS) list missed `subprocess.run`, `os.environ`
+                // and `input(` entirely, so a Python repository could only ever report zero.
+                const { vocabularyFor } = require('../../rtm/taint-vocabulary');
+                const parser = new TreeSitterTsParser();
+                const factSet = [];
+                // @implements A-SPEC-524.1 — every non-TS language with a CFG takes the flow-sensitive
+                // lane, each judged with ITS OWN vocabulary. The TS family keeps the facts+reaching-defs
+                // lane (its interprocedural propagation lives there).
+                const FLOW_EXT = [
+                    [/\.py$/i, 'python'], [/\.go$/i, 'go'], [/\.rs$/i, 'rust'],
+                    [/\.java$/i, 'java'], [/\.cs$/i, 'csharp'], [/\.(cpp|cc|cxx|hpp|h)$/i, 'cpp'],
+                ];
+                const flowLangFiles = new Map();
+                for (const f of scanned) {
+                    const vocab = vocabularyFor(f.sourcePath);
+                    if (!vocab)
+                        continue;
+                    const flowLang = FLOW_EXT.find(([re]) => re.test(f.sourcePath))?.[1];
+                    if (flowLang !== undefined) {
+                        flowLangFiles.set(flowLang, [...(flowLangFiles.get(flowLang) ?? []), f.sourcePath]);
+                        continue;
+                    }
+                    let src;
+                    try {
+                        src = fs.readFileSync(path.join(root, f.sourcePath), 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    const facts = parser.extractDataFlow(src, f.sourcePath.endsWith('x') ? 'tsx' : 'typescript');
+                    if (facts)
+                        factSet.push({ file: f.sourcePath, facts });
+                }
+                const tsVocab = vocabularyFor('x.ts');
+                const raw = taintDataFlow(factSet, tsVocab);
+                const byFile = new Map();
+                for (const fnd of raw.findings)
+                    byFile.set(fnd.file, [...(byFile.get(fnd.file) ?? []), fnd]);
+                const kept = [];
+                let refuted = 0;
+                for (const [rel, fs2] of byFile) {
+                    const out = await filterFindingsForFile(root, rel, fs2, tsVocab);
+                    kept.push(...out.kept.map((f) => ({ ...f, lane: 'facts+reaching-defs' })));
+                    refuted += out.removed.length;
+                }
+                // @implements A-SPEC-513.1 / A-SPEC-524.1 — the flow-sensitive lane, generalized from
+                // Python-only to every language whose CFG/DDG landed in P2. The judgement engine is
+                // language-agnostic; only the vocabulary is selected per language.
+                const flowLangsAnalysed = [];
+                if (flowLangFiles.size > 0) {
+                    const { parseAst } = require('../../cpg/foundation/ast-store');
+                    const { cfgOf, functionsIn } = require('../../cpg/foundation/cfg');
+                    const { ddgOf } = require('../../cpg/foundation/ddg');
+                    const { flowSensitiveTaint } = require('../../rtm/flow-sensitive-taint');
+                    for (const [flowLang, files] of flowLangFiles) {
+                        flowLangsAnalysed.push(flowLang);
+                        for (const rel of files) {
+                            let src;
+                            try {
+                                src = fs.readFileSync(path.join(root, rel), 'utf8');
+                            }
+                            catch {
+                                continue;
+                            }
+                            const vocab = vocabularyFor(rel);
+                            const ast = await parseAst(src, rel);
+                            if (!ast || ast.errorCount > 0)
+                                continue;
+                            for (const fn of functionsIn(ast)) {
+                                const fcfg = cfgOf(ast, fn, src);
+                                if ('unsupported' in fcfg)
+                                    continue;
+                                const fddg = ddgOf(ast, fcfg, fn, src);
+                                if ('unsupported' in fddg)
+                                    continue;
+                                const r = flowSensitiveTaint({ ast, cfg: fcfg, ddg: fddg, source: src, fnName: rel, config: vocab });
+                                for (const f of r.findings)
+                                    kept.push({ ...f, file: rel, lane: 'flow-sensitive' });
+                            }
+                        }
+                    }
+                }
+                return {
+                    ...base,
+                    dataFlow: {
+                        findings: kept,
+                        /** Findings the reaching-definition evidence positively refuted (dead or fully sanitized). */
+                        refutedByReachingDefs: refuted,
+                        limits: [...DATAFLOW_LIMITS],
+                        converged: raw.converged,
+                        truncated: raw.truncated,
+                        /** Which languages this run could actually judge, so a zero is readable. */
+                        languagesAnalysed: [...new Set([factSet.length > 0 ? 'typescript' : null, ...flowLangsAnalysed].filter(Boolean))],
+                    },
+                };
+            }
+            finally {
+                g.close();
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/test-execution.d.ts

@@ -0,0 +1,63 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { ChangeSourceInfo } from '../../project/change-source';
+export interface TestExecutionContext {
+    defaultBaseline: string;
+    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 createTestExecutionHandlers(context: TestExecutionContext): {
+    test_run(a: {
+        root: string;
+        base?: string;
+        head?: string;
+        since?: string;
+        mark?: string;
+        mutate?: string;
+    }): Promise<{
+        mutate: {
+            tspec: string;
+            aspec: string | undefined;
+            coveringFiles: string[];
+            results: ({
+                mutation: import("../../spec/kills").Mutation;
+                applied: boolean;
+                reason: string;
+            } | {
+                applied: boolean;
+                verdict?: "killed" | "survived";
+                mutation: import("../../spec/kills").Mutation;
+                reason?: undefined;
+            })[];
+            survivors: import("../../spec/kills").Mutation[];
+        };
+    } | {
+        calibrationClosed?: string[] | undefined;
+        baselineRecorded?: string | undefined;
+        scopeFallback?: "full" | undefined;
+        tier: import("../../rtm/test-scope").RegressionTier;
+        mode: "full" | "noop" | "scoped";
+        passed: boolean;
+        skipped: boolean;
+        ranFiles: string[];
+        executedByAspec: Record<string, number>;
+        tail: string;
+        unresolvedFiles: string[];
+        changeSource: ChangeSourceInfo;
+        mutate?: undefined;
+    }>;
+};

package/dist/holmes/mcp/handlers/test-execution.js

@@ -0,0 +1,210 @@
+"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.createTestExecutionHandlers = createTestExecutionHandlers;
+// @implements A-SPEC-616, A-SPEC-100.2, A-SPEC-102.1, A-SPEC-121.2, A-SPEC-121.3, A-SPEC-128, A-SPEC-130, A-SPEC-189, A-SPEC-233, A-SPEC-419, A-SPEC-433, A-SPEC-534.5, A-SPEC-534.8, A-SPEC-578.4, A-SPEC-614
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const change_source_1 = require("../../project/change-source");
+const root_1 = require("../../project/root");
+const ignore_1 = require("../../project/ignore");
+const baseline_1 = require("../../project/baseline");
+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 scope_1 = require("../../review/scope");
+const test_runner_1 = require("../../review/test-runner");
+const kills_1 = require("../../spec/kills");
+const mutate_1 = require("../../review/mutate");
+const test_evidence_1 = require("../../review/test-evidence");
+const test_outcomes_1 = require("../../review/test-outcomes");
+const maintenance_evidence_1 = require("../maintenance-evidence");
+// @implements A-SPEC-534.8
+// The governed source file a `kills` mutation targets: one that @implements the A-SPEC AND contains
+// the `where` literal. Bounded walk, skips vendored/test/hidden dirs. null when none qualifies.
+function sourceFileWithMutation(root, aspecId, where) {
+    if (!where)
+        return null;
+    const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift)$/;
+    let found = null;
+    const walk = (d) => {
+        if (found)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (found)
+                return;
+            if (e.name === 'node_modules' || e.name === 'dist' || e.name === 'reference'
+                || e.name === 'vendor' || e.name === 'third_party' || e.name.startsWith('.'))
+                continue;
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+                continue;
+            }
+            if (!SOURCE.test(e.name) || /\.test\./.test(e.name))
+                continue;
+            let text;
+            try {
+                text = fs.readFileSync(p, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (text.includes(`@implements ${aspecId}`) && text.includes(where)) {
+                found = p;
+                return;
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+function createTestExecutionHandlers(context) {
+    return {
+        async test_run(a) {
+            // Closes the decision->execution loop: scope -> run -> durable per-A-SPEC EXECUTION evidence
+            // (what the constitution's ART-4 prefers over the syntactic count).
+            const { root, specs, scanned, changedFiles, changedSymbols, changeSource, scopeFallback, anchorImpactedSpecs, changedTestFiles, unresolvedFiles } = await context.deriveChangedContext(a.root, a, 'test_run');
+            // @implements A-SPEC-534.8 — `mutate`: run a T-SPEC's declared `kills` mutations against the
+            // A-SPEC's source and report which SURVIVED (a discriminating-power gap). Selective, opt-in via
+            // the argument; absent → the ordinary run below is untouched.
+            if (a.mutate) {
+                const tspec = specs.find((s) => s.id === a.mutate && s.type === 'T-SPEC');
+                const kills = tspec ? (0, kills_1.parseKills)(tspec.frontmatter) : [];
+                const aspecId = tspec?.dependsOn[0];
+                const anchors = (0, test_scope_1.scanTestAnchors)(root);
+                const coveringFiles = aspecId
+                    ? Object.entries(anchors).filter(([, ids]) => ids.includes(aspecId)).map(([f]) => f) : [];
+                const results = kills.map((m) => {
+                    const src = aspecId ? sourceFileWithMutation(root, aspecId, m.where) : null;
+                    if (!src)
+                        return { mutation: m, applied: false, reason: 'no governed source anchors this A-SPEC and contains `where`' };
+                    const r = (0, mutate_1.runKillsOnFile)(src, m, coveringFiles, (files) => (0, test_runner_1.runJestOutcomes)(files, root));
+                    return { mutation: m, ...r };
+                });
+                const survivors = results.filter((r) => r.verdict === 'survived').map((r) => r.mutation);
+                return { mutate: { tspec: a.mutate, aspec: aspecId, coveringFiles, results, survivors } };
+            }
+            const g = new rtm_graph_1.RtmGraph();
+            let testScope;
+            try {
+                (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                const scope = (0, scope_1.computeReviewScope)(g, specs, changedSymbols);
+                // @implements A-SPEC-130
+                // Lane 2 widens the impacted set with file-anchor edges the symbol walk cannot see; lanes 3
+                // and the unresolved remainder ride in through extras. A nonempty change set can end in a
+                // scoped run or a full run — never in "nothing to do".
+                const widenedImpacted = [...new Set([...scope.impactedSpecs, ...anchorImpactedSpecs])];
+                // @implements A-SPEC-233 — the architecture axis of `assessRisk` already calls these changes
+                // `hard-hitl`; until now nothing on the test side consumed that verdict, so the most
+                // dangerous change could receive the narrowest run (measured 2026-08-22: tier `unit`, one
+                // test file, against `hard-hitl`).
+                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 });
+                // @implements A-SPEC-128
+                // No change set means no basis for narrowing. Widening is the same fail-safe direction
+                // computeTestScope already takes when no anchored test resolves — never a silently narrow run.
+                if (scopeFallback === 'full') {
+                    testScope = { ...testScope, tier: 'full', reason: `${changeSource.reason ?? 'no change set'} — cannot narrow safely, full regression` };
+                }
+            }
+            finally {
+                g.close();
+            }
+            const result = (0, test_runner_1.runTestScope)(testScope, root);
+            const anchors = (0, test_scope_1.scanTestAnchors)(root);
+            const executedByAspec = (0, test_evidence_1.computeExecutedByAspec)(result.executedByFile ?? {}, anchors);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            // 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 });
+            }
+            // @implements A-SPEC-534.5 — RED-first outcome evidence for ART-8. Recorded UNCONDITIONALLY,
+            // unlike the green-only baseline above: a red-assertion recorded before the code is exactly what
+            // the red→green sequence needs. Append-only, one record per (A-SPEC, outcome) at this HEAD.
+            if (result.outcomeByFile) {
+                (0, test_outcomes_1.appendOutcomes)(root, (0, test_outcomes_1.buildOutcomeRecords)(result.outcomeByFile, anchors, head, new Date().toISOString()));
+            }
+            // @implements A-SPEC-128
+            // The baseline is written under EXACTLY the condition that already gates evidence: a run that
+            // 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 ?? context.defaultBaseline;
+                // A-SPEC-256.2 round-4 — surfaced to the report below
+                const ig = (0, ignore_1.loadIgnore)(root); // parse .gitignore ONCE, not per file (round-10)
+                (0, baseline_1.writeBaseline)(root, baseline, (0, change_source_1.hashTree)(root, { isIgnored: (p) => ig.isIgnored(p) }));
+            }
+            return { tier: testScope.tier, mode: result.mode, passed: result.passed, skipped: result.skipped,
+                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 } : {}),
+                ...(calibrationClosed ? { calibrationClosed } : {}) };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/workspace-identity.d.ts

@@ -0,0 +1,30 @@
+import { IdentityOperation } from '../../project/workspace-identity';
+export declare function createWorkspaceIdentityHandlers(context: {
+    foreignRootReason(root?: string): string | null;
+    storeRoot?: string;
+}): {
+    workspace_identity(a: {
+        root: string;
+        operation?: IdentityOperation;
+    }): Promise<{
+        ok: true;
+        state: "legacy";
+    } | {
+        ok: true;
+        state: "initialized";
+        workspaceId: string;
+    } | {
+        ok: true;
+        state: "registered";
+        workspaceId: string;
+        replicaId: string;
+    } | {
+        ok: boolean;
+        reason: string;
+        code?: undefined;
+    } | {
+        ok: boolean;
+        code: string;
+        reason: string;
+    }>;
+};

package/dist/holmes/mcp/handlers/workspace-identity.js

@@ -0,0 +1,68 @@
+"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.createWorkspaceIdentityHandlers = createWorkspaceIdentityHandlers;
+// @implements A-SPEC-623, A-SPEC-189
+const workspace_identity_1 = require("../../project/workspace-identity");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const root_1 = require("../../project/root");
+function createWorkspaceIdentityHandlers(context) {
+    return {
+        async workspace_identity(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                return { ok: false, reason: foreign };
+            // A new/custom store directory may not exist yet. Resolve its existing ancestor rather than
+            // treating failure to resolve that directory as permission to initialize any supplied root.
+            if (context.storeRoot !== undefined) {
+                let ancestor = path.resolve(context.storeRoot);
+                while (!fs.existsSync(ancestor) && path.dirname(ancestor) !== ancestor)
+                    ancestor = path.dirname(ancestor);
+                const bound = (0, root_1.resolveProjectRoot)(ancestor), asked = (0, root_1.resolveProjectRoot)(a.root);
+                if (bound.marker !== '.ax' || bound.root !== asked.root)
+                    return { ok: false, code: 'foreign-workspace', reason: 'The configured spec store must belong to the requested Holmes workspace before identity operations.' };
+            }
+            try {
+                return (0, workspace_identity_1.workspaceIdentity)(a.root, a.operation);
+            }
+            catch (e) {
+                if (e instanceof workspace_identity_1.WorkspaceIdentityError)
+                    return { ok: false, code: e.code, reason: e.message };
+                throw e;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,77 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+export interface WorkspaceQueryContext {
+    listSpecs(): Promise<Spec[]>;
+    foreignRootReason(root?: string): string | null;
+    projectRootOf(root: string): string;
+    cachedScan(root: string, repoRoot?: string): ScannedFile[];
+    cachedScanWithReport(root: string, repoRoot?: string): {
+        scanned: ScannedFile[];
+        skipped: Array<{
+            file: string;
+            reason: string;
+        }>;
+    };
+    assertStoreReachable(tool: string, root: unknown): void;
+}
+export declare function createWorkspaceQueryHandlers(context: WorkspaceQueryContext): {
+    rtm_check(a?: {
+        root?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        issues?: undefined;
+        gaps?: undefined;
+        breakingChangeDistribution?: undefined;
+    } | {
+        issues: import("../../rtm/rtm-check").RtmIssue[];
+        gaps: import("../../rtm/gap-analyzer").ConvergenceGaps;
+        breakingChangeDistribution: Record<string, number>;
+        ok?: undefined;
+        reason?: undefined;
+    } | {
+        issues: import("../../rtm/rtm-check").RtmIssue[];
+        breakingChangeDistribution: Record<string, number>;
+        ok?: undefined;
+        reason?: undefined;
+        gaps?: undefined;
+    }>;
+    cpg_scan(a: {
+        root: string;
+        lints?: boolean;
+    }): Promise<{
+        files: number;
+        symbols: number;
+        skipped: {
+            file: string;
+            reason: string;
+        }[];
+        skippedCount: number;
+    } | {
+        lints: {
+            dynamicRef: {
+                file: string;
+                name: string;
+                line: number;
+            }[];
+            asyncBlocking: {
+                file: string;
+                pattern: string;
+                line: number;
+            }[];
+            limits: string[];
+        };
+        files: number;
+        symbols: number;
+        skipped: {
+            file: string;
+            reason: string;
+        }[];
+        skippedCount: number;
+    }>;
+    issue_localize(a: {
+        root: string;
+        issue: string;
+        topN?: number;
+    }): Promise<import("../../rtm/localize").LocalizationReport>;
+};