@holmes-lab/holmes-kit 0.2.1 → 0.3.1

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

@@ -0,0 +1,140 @@
+import type { MaintenanceAnalysis } from './maintenance-analyze';
+/**
+ * Persisted maintenance evidence — the durable half of the graph-first protocol.
+ *
+ * An analysis on its own is a prediction that evaporates when the call returns. Calibration is only
+ * possible if the prediction is kept AND the eventual outcome is written next to it, so this module
+ * owns both the artifact format and the arithmetic that scores it. Every number it reports is
+ * derived from recorded outcomes; where nothing was recorded it reports `insufficient-data` rather
+ * than a confident-looking zero.
+ */
+export declare const EVIDENCE_ARTIFACT_SCHEMA = "maintenance-evidence/1.4";
+/** Default directory, relative to the project root. */
+export declare const EVIDENCE_DIR: string;
+export interface EvidenceOutcome {
+    recordedAt: string;
+    actualFiles: string[];
+    actualSymbols: string[];
+    actualTests: string[];
+    /** Absent when nobody has judged the classification: unscored, NOT scored as wrong. */
+    actualClassification?: string;
+}
+export interface EvidenceArtifact {
+    artifactSchema: string;
+    digest: string;
+    recordedAt: string;
+    analysisSchema: string;
+    extractorVersion: string;
+    classification: string;
+    confidence: number;
+    graphBasis: MaintenanceAnalysis['graphBasis'];
+    predicted: {
+        files: string[];
+        primaryFiles: string[];
+        symbols: string[];
+        tests: string[];
+        /**
+         * @implements A-SPEC-277
+         * sha256 of each predicted file AS ANALYSED. HEAD alone cannot see an uncommitted edit to the
+         * very file under analysis, which would leave the evidence looking current while describing
+         * content that no longer exists. Computed by the caller (reading files is I/O; this module is
+         * pure), keyed by the same repo-relative path as `files`.
+         */
+        fileDigests: Record<string, string>;
+    };
+    /**
+     * @implements A-SPEC-276
+     * What the analysis did NOT establish. A pre-edit gate that reads only the prediction would treat
+     * "we saw no impact" and "we could not look" as the same sentence; they are opposite claims. The
+     * artifact is the durable evidence, so the uncertainty travels with it.
+     */
+    uncertainty: {
+        unknowns: string[];
+        coverage: {
+            scannedFiles: number;
+            skippedFiles: string[];
+            unsupportedLanguages: string[];
+        };
+        /** The caller walk stopped at a bound: the transitive set is a lower bound, not a complete one. */
+        impactTruncated: boolean;
+        testScopeTier: string;
+        /** Files reachable only through a call edge — affected, but never analysed as edit candidates. */
+        impactedFiles: string[];
+        /**
+         * @implements A-SPEC-279
+         * Whether each constraint axis was EXAMINED. False means the input was missing, never that the
+         * axis came back clean — the distinction the gate acts on.
+         */
+        securityAssessed: boolean;
+        compatibilityAssessed: boolean;
+    };
+    outcome?: EvidenceOutcome;
+}
+/**
+ * A digest reaches the filesystem as a filename, and it arrives from an MCP caller. Refuse anything
+ * that is not a bare lowercase sha256 hex BEFORE joining it onto a path — an accepted `../` would
+ * turn "record an outcome" into an arbitrary-path write.
+ */
+export declare function digestFilename(digest: string): string;
+/** Project an analysis into the durable prediction record. Pure: the caller supplies the clock. */
+export declare function artifactFrom(analysis: MaintenanceAnalysis, recordedAt: string, fileDigests?: Record<string, string>): EvidenceArtifact;
+/**
+ * Persist an artifact, addressed by its digest. Re-running the same analysis is a re-run, not a
+ * reason to forget what actually happened, so an outcome already recorded at this digest survives.
+ */
+export declare function writeArtifact(dir: string, artifact: EvidenceArtifact): string;
+export interface ArtifactRead {
+    artifacts: EvidenceArtifact[];
+    /** Filenames that could not be parsed — surfaced, never silently dropped from the denominator. */
+    unreadable: string[];
+    /** Artifacts written by a different artifact schema, excluded from any arithmetic. */
+    skippedSchema: number;
+}
+export declare function readArtifacts(dir: string): ArtifactRead;
+export interface OutcomeInput {
+    actualFiles?: string[];
+    actualSymbols?: string[];
+    actualTests?: string[];
+    actualClassification?: string;
+}
+/**
+ * Attach what actually happened to a prediction that was actually made. An unknown digest is
+ * refused: inventing the prediction alongside the outcome would let the record score itself.
+ */
+export declare function recordOutcome(dir: string, digest: string, outcome: OutcomeInput, recordedAt: string): EvidenceArtifact;
+export interface CalibrationBin {
+    lower: number;
+    upper: number;
+    n: number;
+    meanConfidence: number | null;
+    observedAccuracy: number | null;
+    status: 'measured' | 'insufficient-data';
+}
+export interface Calibration {
+    schema: string;
+    /** Predictions that carry a judged classification — the only ones that can be scored. */
+    n: number;
+    /**
+     * @implements A-SPEC-434
+     * Artifacts with no JUDGED CLASSIFICATION — which is not the same as no outcome, and used to be
+     * called `withoutOutcome`. Recording `actualFiles` for a correct prediction reported
+     * `n: 0, withoutOutcome: 1, falsePositives: 0, falseNegatives: 0`: the outcome was there, the file
+     * scores were computed from it, and the name said otherwise. Only a classification can be scored
+     * for confidence, so this counts what cannot enter the bins — nothing more.
+     */
+    withoutClassification: number;
+    bins: CalibrationBin[];
+    brierScore: number | null;
+    falsePositives: number;
+    falseNegatives: number;
+    minSamples: number;
+    status: 'measured' | 'insufficient-data';
+}
+/**
+ * Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports
+ * `insufficient-data` and a null accuracy, because one sample in a bin yields a 0 or a 1 that looks
+ * like a measurement and is really just noise.
+ */
+export declare function computeCalibration(artifacts: readonly EvidenceArtifact[], opts?: {
+    minSamples?: number;
+}): Calibration;

package/dist/holmes/mcp/maintenance-evidence.js

@@ -0,0 +1,253 @@
+"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.EVIDENCE_DIR = exports.EVIDENCE_ARTIFACT_SCHEMA = void 0;
+exports.digestFilename = digestFilename;
+exports.artifactFrom = artifactFrom;
+exports.writeArtifact = writeArtifact;
+exports.readArtifacts = readArtifacts;
+exports.recordOutcome = recordOutcome;
+exports.computeCalibration = computeCalibration;
+// @implements A-SPEC-271
+// @implements A-SPEC-268
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * Persisted maintenance evidence — the durable half of the graph-first protocol.
+ *
+ * An analysis on its own is a prediction that evaporates when the call returns. Calibration is only
+ * possible if the prediction is kept AND the eventual outcome is written next to it, so this module
+ * owns both the artifact format and the arithmetic that scores it. Every number it reports is
+ * derived from recorded outcomes; where nothing was recorded it reports `insufficient-data` rather
+ * than a confident-looking zero.
+ */
+// @implements A-SPEC-434 — the calibration output renamed a field, so a consumer can detect it.
+exports.EVIDENCE_ARTIFACT_SCHEMA = 'maintenance-evidence/1.4';
+/** Default directory, relative to the project root. */
+exports.EVIDENCE_DIR = path.join('.ax', 'evidence', 'maintenance');
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+/**
+ * A digest reaches the filesystem as a filename, and it arrives from an MCP caller. Refuse anything
+ * that is not a bare lowercase sha256 hex BEFORE joining it onto a path — an accepted `../` would
+ * turn "record an outcome" into an arbitrary-path write.
+ */
+function digestFilename(digest) {
+    const bare = digest.startsWith('sha256:') ? digest.slice(7) : digest;
+    if (!DIGEST_PATTERN.test(bare)) {
+        throw new Error(`Refusing an evidence digest that is not a bare sha256 hex: ${JSON.stringify(digest)}`);
+    }
+    return `${bare}.json`;
+}
+function sortedUnique(values) {
+    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
+}
+/** Project an analysis into the durable prediction record. Pure: the caller supplies the clock. */
+function artifactFrom(analysis, recordedAt, fileDigests = {}) {
+    return {
+        artifactSchema: exports.EVIDENCE_ARTIFACT_SCHEMA,
+        digest: analysis.evidenceDigest,
+        recordedAt,
+        analysisSchema: analysis.schemaVersion,
+        extractorVersion: analysis.extractorVersion,
+        classification: analysis.classification,
+        confidence: analysis.confidence,
+        graphBasis: analysis.graphBasis,
+        predicted: {
+            files: sortedUnique(analysis.impacts.files),
+            // @implements A-SPEC-271 — kept so a later slice can score per-tier precision over history.
+            primaryFiles: [...analysis.impacts.tiers.primary],
+            symbols: sortedUnique([...analysis.impacts.direct, ...analysis.impacts.transitive]),
+            tests: sortedUnique(analysis.relevantTests),
+            fileDigests: { ...fileDigests },
+        },
+        uncertainty: {
+            unknowns: [...analysis.unknowns],
+            coverage: {
+                scannedFiles: analysis.coverage.scannedFiles,
+                skippedFiles: [...analysis.coverage.skippedFiles],
+                unsupportedLanguages: [...analysis.coverage.unsupportedLanguages],
+            },
+            impactTruncated: analysis.impactBounds.stoppedAt.length > 0,
+            testScopeTier: analysis.testScope.tier,
+            impactedFiles: [...analysis.impacts.impactedFiles],
+            securityAssessed: analysis.constraints.security.assessed,
+            compatibilityAssessed: analysis.constraints.compatibility.assessed,
+        },
+    };
+}
+function writeAtomic(file, body) {
+    // Same-directory temp + rename: a reader either sees the previous artifact or the new one, never
+    // a half-written object. The temp name carries the pid so concurrent writers cannot collide.
+    const temp = `${file}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temp, body, { encoding: 'utf8' });
+        fs.renameSync(temp, file);
+    }
+    finally {
+        if (fs.existsSync(temp))
+            fs.rmSync(temp, { force: true });
+    }
+}
+/**
+ * Persist an artifact, addressed by its digest. Re-running the same analysis is a re-run, not a
+ * reason to forget what actually happened, so an outcome already recorded at this digest survives.
+ */
+function writeArtifact(dir, artifact) {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, digestFilename(artifact.digest));
+    let merged = artifact;
+    if (fs.existsSync(file)) {
+        try {
+            const existing = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (existing.outcome && !artifact.outcome)
+                merged = { ...artifact, outcome: existing.outcome };
+        }
+        catch {
+            // An unreadable predecessor is replaced by a valid record; `readArtifacts` is what reports
+            // corruption, and refusing to write here would strand the directory in its broken state.
+        }
+    }
+    writeAtomic(file, `${JSON.stringify(merged, null, 2)}\n`);
+    return file;
+}
+function readArtifacts(dir) {
+    if (!fs.existsSync(dir))
+        return { artifacts: [], unreadable: [], skippedSchema: 0 };
+    const artifacts = [];
+    const unreadable = [];
+    let skippedSchema = 0;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+        }
+        catch {
+            unreadable.push(name);
+            continue;
+        }
+        if (parsed?.artifactSchema !== exports.EVIDENCE_ARTIFACT_SCHEMA) {
+            skippedSchema++;
+            continue;
+        }
+        artifacts.push(parsed);
+    }
+    return { artifacts, unreadable, skippedSchema };
+}
+/**
+ * Attach what actually happened to a prediction that was actually made. An unknown digest is
+ * refused: inventing the prediction alongside the outcome would let the record score itself.
+ */
+function recordOutcome(dir, digest, outcome, recordedAt) {
+    const file = path.join(dir, digestFilename(digest));
+    if (!fs.existsSync(file)) {
+        throw new Error(`Refusing to record an outcome for an unknown analysis digest: ${digest}`);
+    }
+    const artifact = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const updated = {
+        ...artifact,
+        outcome: {
+            recordedAt,
+            actualFiles: sortedUnique(outcome.actualFiles ?? []),
+            actualSymbols: sortedUnique(outcome.actualSymbols ?? []),
+            actualTests: sortedUnique(outcome.actualTests ?? []),
+            ...(outcome.actualClassification ? { actualClassification: outcome.actualClassification } : {}),
+        },
+    };
+    writeAtomic(file, `${JSON.stringify(updated, null, 2)}\n`);
+    return updated;
+}
+const BIN_EDGES = [0, 0.2, 0.4, 0.6, 0.8, 1];
+/**
+ * Reliability bins plus a Brier score. `minSamples` is the honesty knob: below it a bin reports
+ * `insufficient-data` and a null accuracy, because one sample in a bin yields a 0 or a 1 that looks
+ * like a measurement and is really just noise.
+ */
+function computeCalibration(artifacts, opts = {}) {
+    const minSamples = Math.max(1, Math.floor(opts.minSamples ?? 5));
+    const scored = artifacts.filter((a) => a.outcome?.actualClassification !== undefined);
+    const withoutClassification = artifacts.length - scored.length; // @implements A-SPEC-434
+    let falsePositives = 0;
+    let falseNegatives = 0;
+    for (const artifact of artifacts) {
+        // File-level FP/FN need only a recorded file set, so they are counted over every artifact whose
+        // outcome names one — independent of whether the classification was judged.
+        if (!artifact.outcome)
+            continue;
+        const actual = new Set(artifact.outcome.actualFiles);
+        const predicted = new Set(artifact.predicted.files);
+        for (const file of predicted)
+            if (!actual.has(file))
+                falsePositives++;
+        for (const file of actual)
+            if (!predicted.has(file))
+                falseNegatives++;
+    }
+    const correctness = scored.map((a) => ({
+        confidence: a.confidence,
+        correct: a.outcome.actualClassification === a.classification,
+    }));
+    const bins = [];
+    for (let i = 0; i < BIN_EDGES.length - 1; i++) {
+        const lower = BIN_EDGES[i];
+        const upper = BIN_EDGES[i + 1];
+        const isLast = i === BIN_EDGES.length - 2;
+        const members = correctness.filter((c) => c.confidence >= lower && (isLast ? c.confidence <= upper : c.confidence < upper));
+        const enough = members.length >= minSamples;
+        bins.push({
+            lower,
+            upper,
+            n: members.length,
+            meanConfidence: enough ? members.reduce((sum, c) => sum + c.confidence, 0) / members.length : null,
+            observedAccuracy: enough ? members.filter((c) => c.correct).length / members.length : null,
+            status: enough ? 'measured' : 'insufficient-data',
+        });
+    }
+    const brierScore = correctness.length === 0
+        ? null
+        : correctness.reduce((sum, c) => sum + (c.confidence - (c.correct ? 1 : 0)) ** 2, 0) / correctness.length;
+    return {
+        schema: exports.EVIDENCE_ARTIFACT_SCHEMA,
+        n: correctness.length,
+        withoutClassification,
+        bins,
+        brierScore,
+        falsePositives,
+        falseNegatives,
+        minSamples,
+        status: correctness.length >= minSamples ? 'measured' : 'insufficient-data',
+    };
+}

package/dist/holmes/mcp/server.js

@@ -12,20 +12,23 @@ const validate_args_1 = require("./validate-args");
 // @implements A-SPEC-100.2
 const store = new spec_store_1.LocalMarkdownRepository(process.env.HOLMES_SPECS ?? '.ax/specs');
 // @implements A-SPEC-263.1 — the elicitation approval channel's wiring. The capability arrives at
-// initialize, AFTER this factory runs, so it is consulted lazily at CALL time: no capability (or
-// any transport error/timeout) folds to null, which the handlers treat as "the channel gave no
-// answer" — the refusal that follows is byte-identical to the pre-elicitation one. Diagnostics, if
-// ever needed, go to stderr only (stdout is the protocol channel).
-const { buildElicitRequest, interpretElicitResult } = require('./elicit-approval');
+// initialize, AFTER this factory runs, so it is consulted lazily at CALL time.
+// @implements A-SPEC-497.1 — the three fates, told apart at THIS seam (the only place the SDK error
+// is visible): a RequestTimeout rejection is `expired` and earns a name in the refusal; every other
+// failure — no capability, transport error, malformed answer — folds to `silent`, whose refusal
+// stays byte-identical to the pre-elicitation one. Diagnostics, if ever needed, go to stderr only
+// (stdout is the protocol channel).
+const { ELICIT_TIMEOUT_MS, buildElicitRequest, classifyElicitError, interpretElicitResult } = require('./elicit-approval');
 const elicit = async (req) => {
     try {
         if (!server.getClientCapabilities()?.elicitation)
-            return null;
-        const r = await server.elicitInput(buildElicitRequest(req), { timeout: 120_000 });
-        return interpretElicitResult(r);
+            return { kind: 'silent' };
+        const r = await server.elicitInput(buildElicitRequest(req), { timeout: ELICIT_TIMEOUT_MS });
+        const d = interpretElicitResult(r);
+        return d === null ? { kind: 'silent' } : { kind: 'answered', decision: d };
     }
-    catch {
-        return null;
+    catch (e) {
+        return classifyElicitError(e);
     }
 };
 const handlers = (0, handlers_1.makeHandlers)(store, {

package/dist/holmes/mcp/tool-schemas.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
+// @implements A-SPEC-277
+// @implements A-SPEC-269
+// @implements A-SPEC-267
 const spec_types_1 = require("../spec/spec-types");
 const phase_1 = require("../guardrail/phase");
 const str = (description) => ({ type: 'string', description });
 const num = (description) => ({ type: 'number', description });
+const bool = (description) => ({ type: 'boolean', description });
 const strArray = (description) => ({ type: 'array', items: { type: 'string' }, description });
 // @implements A-SPEC-189 §10 (round 11) — this said "must equal `git rev-parse --show-toplevel`",
 // and A-SPEC-128 had already replaced `assertRepoTopLevel` with `resolveProjectRoot`: measured,
@@ -208,6 +212,73 @@ exports.TOOL_SCHEMAS = {
             required: ['root', 'issue'],
         },
     },
+    maintenance_analyze: {
+        // @implements A-SPEC-360 — the disclaimer is measured, not hedged: eight computed signals were
+        // correlated against delivered accuracy on two corpora and none agreed even in sign.
+        // @implements A-SPEC-437 — and the numbers in it are kept current. They were -0.062/-0.016 when
+        // first written; re-measuring on the shipped path gave -0.309/-0.212, which is a different claim
+        // (no signal versus an inverted one) and the caller reads this string, not the source.
+        description: 'Graph-first maintenance analysis: classify a request as an existing change, new requirement, or ambiguous; rank code/spec targets; compute call/contract/test impact; attach bounded git rationale, coverage gaps, build basis, and a reproducible evidence digest. The returned `confidence` summarizes WHICH KINDS of evidence were present (direct symbols, relevant tests, history), and is NOT A PROBABILITY and not an estimate of accuracy: re-measured 2026-08-29 on the 30-case clean slice of each corpus it is ANTI-PREDICTIVE — the correlation with delivered localization accuracy is -0.309 here and -0.212 on a second corpus, and the HIGHEST band is the worst on both (on the second corpus the two cases scored 0.85 found nothing at all). An earlier run put it at -0.062/-0.016; the sign has been stable and the magnitude has grown. Do not weight answers by it. Read the candidates, unknowns and coverage instead; the bands and their sample sizes are in review/confidence-calibration.ts. With the opt-in cloud semantic tier active, also read: `sem-verify(…)` evidence lines (display-only calibration — never a hard filter), `semCos` on rankedImpact rows, and `semanticAlternates`: the top-3 semantic matches the lexical emission missed — on lexically-poor requests the true target is often there (measured ×1.25–×2.25 reach gain), so weigh them as candidates too.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                request: str('Issue, change request, or new requirement to analyze against the CPG, RTM, tests, and history.'),
+                historyLimit: num('Maximum matching git history records to include (default 20, clamped to 0..100).'),
+                contextBudget: num('Token budget for the top graph seed context bundle (default 2000, clamped to 100..10000).'),
+                changedFiles: { type: 'array', items: { type: 'string' }, description: 'Optional changed-file basis (e.g. a base..head diff). Required to assess the architecture axis (.ax/decisions and C-SPEC documents), which the code scanner never sees. Omit it and that axis is reported as NOT assessed rather than as empty.' },
+                persist: bool('Write the analysis to .ax/evidence/maintenance as a versioned artifact addressed by its evidence digest. Default false: the tool is read-only unless persistence is explicitly requested.'),
+                groundTruth: {
+                    type: 'object',
+                    description: 'Optional replay ground truth (e.g. the files/symbols/tests a historical commit actually changed). Supplying it scores the graph-off / current / enhanced ablation arms; omitting it reports those metrics as null rather than as zero.',
+                    properties: {
+                        files: { type: 'array', items: { type: 'string' }, description: 'Source files the change actually touched.' },
+                        symbols: { type: 'array', items: { type: 'string' }, description: 'Qualified symbol names the change actually touched.' },
+                        tests: { type: 'array', items: { type: 'string' }, description: 'Test files the change actually touched.' },
+                    },
+                },
+            },
+            required: ['root', 'request'],
+        },
+    },
+    maintenance_outcome: {
+        description: 'Record what a change actually touched against a previously persisted maintenance analysis, so the prediction can later be scored. The digest must name an analysis this project already stored.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                digest: str('The evidenceDigest of the persisted analysis being scored (sha256:<64 hex>).'),
+                actualFiles: { type: 'array', items: { type: 'string' }, description: 'Source files the change actually touched.' },
+                actualSymbols: { type: 'array', items: { type: 'string' }, description: 'Qualified symbol names the change actually touched.' },
+                actualTests: { type: 'array', items: { type: 'string' }, description: 'Test files the change actually touched.' },
+                actualClassification: str('The judged classification (existing-requirement-change | new-requirement | ambiguous). Omit it to record files without scoring the confidence — an unjudged record counts as unscored, never as wrong.'),
+            },
+            required: ['root', 'digest'],
+        },
+    },
+    maintenance_calibration: {
+        description: 'Measure confidence calibration over persisted maintenance analyses that have a recorded outcome: per-confidence-bin observed accuracy, Brier score, and file-level false positives/negatives. Bins below minSamples report insufficient-data rather than a noisy score.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                minSamples: num('Minimum samples before a bin (or the whole record) is reported as measured (default 5).'),
+            },
+            required: ['root'],
+        },
+    },
+    impact_gate_check: {
+        description: 'Pre-edit impact evidence verdict: given an edit target and (optionally) the digest of a persisted analysis, return allow | widen | refuse with every reason that applied and a remediation. Read-only and advisory — it reports a judgement, it does not block anything.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: ROOT_ANY,
+                target: str('Repo-relative path the session intends to edit.'),
+                digest: str('evidenceDigest of the persisted maintenance analysis backing this edit (sha256:<64 hex>). Omit it to ask whether ANY evidence exists — the answer is then a refusal naming what to run.'),
+            },
+            required: ['root', 'target'],
+        },
+    },
     rtm_impact: {
         description: 'Given changed symbol qualified-names, return the impacted SPEC node ids reachable through @implements/depends_on edges ({ impacted }).',
         inputSchema: {

package/dist/holmes/project/root.js

@@ -46,7 +46,9 @@ const node_child_process_1 = require("node:child_process");
 // @implements A-SPEC-205
 function cleanSubprocessEnv(env = process.env) {
     const cleaned = { ...env };
-    const SCRUB_KEYS = new Set(['HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_ROLE', 'HOLMES_ENV_CHANNEL']);
+    // @implements A-SPEC-477 — the semantic key is egress consent; a child process that inherits
+    // it could exfiltrate without the gate ever seeing a command mention the name.
+    const SCRUB_KEYS = new Set(['HOLMES_APPROVAL', 'HOLMES_LEDGER_KEY', 'HOLMES_ROLE', 'HOLMES_ENV_CHANNEL', 'HOLMES_SEMANTIC_API_KEY', 'GEMINI_API_KEY', 'GOOGLE_API_KEY']);
     for (const k of Object.keys(cleaned)) {
         if (SCRUB_KEYS.has(k.toUpperCase())) {
             delete cleaned[k];

package/dist/holmes/review/baseline-arm.d.ts

@@ -0,0 +1,37 @@
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/**
+ * What the same question looks like with no knowledge graph at all.
+ *
+ * Goal Phase B calls this the only path that turns "better than a human" from a claim into a
+ * measurement, and operating principle 10 requires the comparison before the phrase may be used.
+ * Every number in this work so far compares Holmes to *earlier Holmes*; none of them says whether
+ * any of the machinery beats plain word matching.
+ *
+ * So this arm is deliberately impoverished, and each omission is the point rather than an oversight:
+ * no spec-anchor bonus, no citation recovery, no graph expansion, no corpus IDF. Term hits against
+ * symbol names and the path, and nothing else — a stand-in for grepping the tree for the words in
+ * the ticket, which is the floor a developer without tooling actually works from.
+ *
+ * It is a floor, not a model of an expert. A skilled engineer who knows the codebase would do better
+ * than this, and beating it is necessary rather than sufficient for the claim Phase B is about.
+ */
+export interface BaselineHit {
+    file: string;
+    score: number;
+}
+export declare function rankBaseline(issueText: string, scanned: readonly ScannedFile[], topN: number): BaselineHit[];
+/**
+ * @implements A-SPEC-368
+ * The request as an outsider would have written it: with any spec citation removed.
+ *
+ * The replay feeds commit subjects in as the "issue", and 88.3% of this repository's subjects name a
+ * spec outright (`fix(S-266): …`) against 0% of the second corpus's (A-SPEC-367). Citation is the
+ * strongest signal the scorer has — a +20 bonus against a lexical hit worth 3 — so a large share of
+ * the measured advantage may rest on a commit-message convention that no incoming bug report will
+ * follow.
+ *
+ * Removing it is the direct test. Both readings get reported: a maintainer working inside a
+ * Holmes-governed project really does cite specs, and an outside reporter really does not, so the
+ * cited and uncited numbers bound what a user should expect rather than one replacing the other.
+ */
+export declare function stripCitations(text: string): string;

package/dist/holmes/review/baseline-arm.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankBaseline = rankBaseline;
+exports.stripCitations = stripCitations;
+const localize_1 = require("../rtm/localize");
+const tokensOf = (s) => new Set((0, localize_1.significantTerms)(s));
+function rankBaseline(issueText, scanned, topN) {
+    const terms = new Set((0, localize_1.significantTerms)(issueText));
+    if (terms.size === 0)
+        return [];
+    const hits = [];
+    for (const f of scanned) {
+        let score = 0;
+        for (const sym of f.symbols) {
+            const st = tokensOf(sym.qualifiedName);
+            for (const t of terms)
+                if (st.has(t))
+                    score += 3;
+        }
+        const pt = tokensOf(f.sourcePath);
+        for (const t of terms)
+            if (pt.has(t))
+                score += 1;
+        if (score > 0)
+            hits.push({ file: f.sourcePath, score });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, topN);
+}
+/**
+ * @implements A-SPEC-368
+ * The request as an outsider would have written it: with any spec citation removed.
+ *
+ * The replay feeds commit subjects in as the "issue", and 88.3% of this repository's subjects name a
+ * spec outright (`fix(S-266): …`) against 0% of the second corpus's (A-SPEC-367). Citation is the
+ * strongest signal the scorer has — a +20 bonus against a lexical hit worth 3 — so a large share of
+ * the measured advantage may rest on a commit-message convention that no incoming bug report will
+ * follow.
+ *
+ * Removing it is the direct test. Both readings get reported: a maintainer working inside a
+ * Holmes-governed project really does cite specs, and an outside reporter really does not, so the
+ * cited and uncited numbers bound what a user should expect rather than one replacing the other.
+ */
+function stripCitations(text) {
+    // Every spelling the citation extractor recognises — A-SPEC-12, S-262.1, REQ-9, T-SPEC-3 — plus
+    // the conventional `fix(S-266):` wrapper, whose parentheses would otherwise leave `()` behind.
+    return text
+        .replace(/\(\s*(?:[AHT]-SPEC|REQ|S)-\d+(?:\.\d+)?\s*\)/gi, '')
+        .replace(/\b(?:[AHT]-SPEC|REQ|S)-\d+(?:\.\d+)?\b/gi, '')
+        .replace(/\s{2,}/g, ' ')
+        .trim();
+}

package/dist/holmes/review/captured-stdin-guard.d.ts

@@ -0,0 +1,8 @@
+export interface CapturedStdinViolation {
+    file: string;
+    /** The variable holding the captured output. */
+    variable: string;
+    /** 1-indexed line of the `input:` that receives it. */
+    line: number;
+}
+export declare function capturedStdinViolations(source: string, file: string): CapturedStdinViolation[];