@holmes-lab/holmes-kit 0.7.1 → 0.9.0

package/dist/holmes/hooks/stop.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
+exports.changedAnchoredAspecs = changedAnchoredAspecs;
 exports.unanchoredChangedSources = unanchoredChangedSources;
 exports.unrecordedApprovals = unrecordedApprovals;
 exports.rolledBackLedgers = rolledBackLedgers;
@@ -56,10 +57,50 @@ const test_scope_1 = require("../rtm/test-scope");
 const constitution_1 = require("../governance/constitution");
 const provenance_chain_1 = require("../governance/provenance-chain");
 const test_evidence_1 = require("../review/test-evidence");
+const test_outcomes_1 = require("../review/test-outcomes");
+const config_1 = require("../config/config");
 const pre_tool_use_1 = require("./pre-tool-use");
 const governance_history_1 = require("../guardrail/governance-history");
 const constitution_debt_1 = require("../governance/constitution-debt");
 const root_1 = require("../project/root");
+/**
+ * @implements A-SPEC-534.4
+ * ART-8 evidence (I/O half): the A-SPECs whose DIRTY source files carry an @implements anchor. git is
+ * a refinement — no repository means `undefined` (no signal), never a false clean.
+ */
+function changedAnchoredAspecs(root) {
+    const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs|py|go|rs|java|kt|cs|rb|php|swift)$/;
+    const VENDORED = /^(?:reference|node_modules|dist|build|vendor|third_party)\//;
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-uall'], {
+            cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)(),
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const ids = new Set();
+    for (const line of raw.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        let rel = line.slice(3).trim().replace(/^"|"$/g, '');
+        if (rel.includes(' -> '))
+            rel = rel.split(' -> ')[1]; // renames name the destination
+        if (!SOURCE.test(rel) || VENDORED.test(rel))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            continue;
+        } // deleted/unreadable
+        for (const m of text.matchAll(/@implements\s+(A-SPEC-\d+(?:\.\d+)?)/g))
+            ids.add(m[1]);
+    }
+    return [...ids].sort();
+}
 /**
  * @implements A-SPEC-452
  * ART-1 evidence: which changed source files claim nothing.
@@ -248,7 +289,21 @@ function evaluateStop(specs, evidence) {
     // L1: the Stop gate IS the constitution's re-verification point — every turn boundary re-runs the
     // inviolable articles (ART-2 RTM, ART-3 validity incl. 4-quadrant GWT, ART-4 coverage evidence).
     // The articles live in ONE place (governance/constitution.ts); this gate merely executes them.
-    const violations = (0, constitution_1.verifyConstitution)({ specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings });
+    // @implements A-SPEC-534.4 — ART-8 evidence rides through to the constitution, which emits a
+    // BLOCKING ART-8 violation only in `strict` mode. `track`/`off` produce none here.
+    const violations = (0, constitution_1.verifyConstitution)({
+        specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
+        redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
+    });
+    // @implements A-SPEC-534.4 — `track` records ART-8 findings without blocking the turn. Computed
+    // separately (the constitution stays silent on ART-8 outside strict) and returned in `tracked` for
+    // the CLI to record; it never enters `problems`/the block decision.
+    let tracked;
+    if (evidence?.redFirstMode === 'track' && evidence.changedAspecs && evidence.outcomesByAspec) {
+        const t = (0, constitution_1.redFirstViolations)(evidence.changedAspecs, evidence.outcomesByAspec);
+        if (t.length)
+            tracked = t;
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -287,7 +342,7 @@ function evaluateStop(specs, evidence) {
         structured.push({ article: 'ART-2', detail });
     }
     if (problems.length === 0)
-        return { block: false };
+        return { block: false, ...(tracked ? { tracked } : {}) };
     const shown = problems.slice(0, 20);
     const more = problems.length > shown.length ? `\n…and ${problems.length - shown.length} more` : '';
     // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
@@ -301,6 +356,7 @@ function evaluateStop(specs, evidence) {
         block: true,
         articles,
         violations: structured,
+        ...(tracked ? { tracked } : {}),
         reason: `[Holmes-Kit] constitution gate: ${problems.length} article violation(s) must be ` +
             `fixed before finishing:\n${shown.join('\n')}${more}`,
     };
@@ -656,6 +712,25 @@ if (require.main === module) {
             catch {
                 executedByAspec = undefined;
             }
+            // @implements A-SPEC-534.4 — ART-8 RED-first evidence (I/O half). Outcomes recorded at the
+            // current baseline HEAD (where the dirty work's red+green ran); changed anchored A-SPECs from
+            // the working tree; the posture from config. Fail-open: any error leaves ART-8 inert this turn.
+            let redFirstMode;
+            let changedAspecs;
+            let outcomesByAspec;
+            try {
+                redFirstMode = (0, config_1.loadConfig)(stopProjectRoot()).guardrail.redFirstEvidence;
+                if (redFirstMode !== 'off') {
+                    const head = (0, node_child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], { cwd: stopProjectRoot(), stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() }).toString().trim();
+                    changedAspecs = changedAnchoredAspecs(stopProjectRoot());
+                    outcomesByAspec = (0, test_outcomes_1.groupOutcomesByAspec)((0, test_outcomes_1.readOutcomes)(stopProjectRoot()), head);
+                }
+            }
+            catch {
+                redFirstMode = undefined;
+                changedAspecs = undefined;
+                outcomesByAspec = undefined;
+            }
             // Provenance-chain verification (fail-open: a verify error skips the check, never crashes).
             let provenance;
             // @implements A-SPEC-148
@@ -690,7 +765,12 @@ if (require.main === module) {
             const unrecorded = unrecordedApprovals(stopProjectRoot());
             // @implements A-SPEC-455
             const rolledBack = rolledBackLedgers(stopProjectRoot());
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack });
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec });
+            // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
+            // the operator observes RED-first gaps before an owner promotes the posture to strict.
+            if (out.tracked && out.tracked.length > 0) {
+                process.stderr.write(`[Holmes-Kit] ART-8 RED-first (track): ${out.tracked.map((t) => t.detail).join(' | ')}\n`);
+            }
             // @implements A-SPEC-247 — before deciding to re-block, ask whether every unresolved debt is
             // already queued for the owner. If so, tell the user ONCE and let the turn finish; a single
             // non-waiting violation and we block exactly as before.

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

@@ -347,7 +347,25 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         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[];
+        };
+    } | {
         baselineRecorded?: string | undefined;
         scopeFallback?: "full" | undefined;
         tier: import("../rtm/test-scope").RegressionTier;
@@ -359,6 +377,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         tail: string;
         unresolvedFiles: string[];
         changeSource: ChangeSourceInfo;
+        mutate?: undefined;
     }>;
     issue_localize(a: {
         root: string;

package/dist/holmes/mcp/handlers.js

@@ -68,7 +68,10 @@ const rtm_check_1 = require("../rtm/rtm-check");
 const test_scope_1 = require("../rtm/test-scope");
 const gap_analyzer_1 = require("../rtm/gap-analyzer");
 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 localize_1 = require("../rtm/localize");
 const maintenance_analyze_1 = require("./maintenance-analyze");
 const maintenance_evidence_1 = require("./maintenance-evidence");
@@ -90,6 +93,53 @@ const root_1 = require("../project/root");
 // under that tree stopped at the minted marker. This is the harm §8 closed for `review_record`,
 // left open on the scan path. When the store is bound, the cache is the bound project's; otherwise
 // only an anchored answer may be written to, and an unanchored one falls back to a temp cache.
+// @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;
+}
 const cacheDirFor = (root) => {
     const r = (0, root_2.resolveProjectRoot)(root);
     if (r.marker !== 'given')
@@ -130,6 +180,7 @@ const package_1 = require("../review/package");
 const risk_classifier_1 = require("../guardrail/risk-classifier");
 const risk_gate_1 = require("../guardrail/risk-gate");
 const elicit_approval_1 = require("./elicit-approval");
+const autonomy_1 = require("../governance/autonomy");
 const anchor_comment_1 = require("../rtm/anchor-comment");
 const consistency_lints_1 = require("../cpg/consistency-lints");
 const approval_queue_1 = require("../governance/approval-queue");
@@ -669,6 +720,15 @@ function makeRawHandlers(store, opts) {
         token: crypto.randomUUID(),
         rationale: reason ?? 'elicitation grant',
     });
+    // @implements A-SPEC-532.2 — the autonomous channel: the SAME synthesized-Approval shape that
+    // rides the existing seal path, but its actor names `autonomous:<client>` so an audit can tell a
+    // self-approved seal from a human-approved (elicitation) or operator (env/grant) one. Single-use
+    // by construction — it exists only inside this call, persisted nowhere.
+    const autonomousApproval = () => ({
+        actor: `autonomous:${opts?.clientName?.() ?? 'unknown'}`,
+        token: crypto.randomUUID(),
+        rationale: `autonomous grant (${'HOLMES_AUTONOMOUS_APPROVAL'} enabled, spec grade auto)`,
+    });
     /**
      * Where the audit record for a governance act belongs — resolved BEFORE the act writes anything.
      *
@@ -1134,26 +1194,38 @@ function makeRawHandlers(store, opts) {
             if (approveResolved === undefined) {
                 const target = await store.read(a.id).catch(() => null);
                 if (target) {
-                    const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
-                    // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
-                    // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
-                    // more consequential act) as a first approval. The cap cuts the title, never the marker.
-                    const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
-                    if (out.kind === 'answered' && out.decision.granted) {
-                        approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
+                    // @implements A-SPEC-532.2 — the autonomous gate sits BEFORE the human ask: when the
+                    // out-of-band autonomy switch is on AND the spec is low/mid-risk (never gate-behavior, an
+                    // architecture/taint file, or an upstream REQ/H/C — those stay human), the agent seals it
+                    // itself. The switch is env-only and an agent cannot set it (pre-tool-use blocks that,
+                    // A-SPEC-532.2). Off, or a hitl-classed spec, falls straight through to the elicitor
+                    // unchanged — the autonomous-OFF path is byte-identical to before.
+                    if ((0, autonomy_1.autonomousApprovalEnabled)(process.env)
+                        && (0, autonomy_1.specApprovalAutonomy)(target.spec, resolver([target.spec])) === 'auto') {
+                        approveResolved = { approval: autonomousApproval(), source: 'autonomous' };
                     }
-                    else if (out.kind === 'answered') {
-                        // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
-                        // entry is filed — a decided request is not a pending one (REQ-246 visibility).
-                        return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
-                    }
-                    else if (out.kind === 'expired') {
-                        // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
-                        // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
-                        // message learned to say what happened.
-                        elicitExpiredMs = out.waitedMs;
+                    else {
+                        const resealing = typeof target.spec.frontmatter.approved_digest === 'string';
+                        // The MODEL text is capped BEFORE the server markers are appended (round-2): a ~185+ char
+                        // title pushed '(재봉인)' past the dialog's 200-char summary cap, dressing a re-seal (the
+                        // more consequential act) as a first approval. The cap cuts the title, never the marker.
+                        const out = await tryElicit('spec-approve', a.id, `${a.id} — ${target.spec.title.slice(0, 120)}${resealing ? ' (재봉인)' : ''}`);
+                        if (out.kind === 'answered' && out.decision.granted) {
+                            approveResolved = { approval: elicitApproval(out.decision.reason), source: 'elicitation' };
+                        }
+                        else if (out.kind === 'answered') {
+                            // The human ANSWERED (deny/question/decline): the answer is the message, and no queue
+                            // entry is filed — a decided request is not a pending one (REQ-246 visibility).
+                            return { ok: false, reason: `spec_approve: 세션에서 거부됨 — ${out.decision.reason ?? '(사유 없음)'}. 사유를 해소한 뒤 다시 시도하십시오.` };
+                        }
+                        else if (out.kind === 'expired') {
+                            // @implements A-SPEC-497.1 — only the expiry earns a name: the notice LEADS the same
+                            // fail-closed refusal + queue path, so the semantics stay refusal+queue and only the
+                            // message learned to say what happened.
+                            elicitExpiredMs = out.waitedMs;
+                        }
+                        // silent: the channel gave no answer — fall through to the byte-identical refusal.
                     }
-                    // silent: the channel gave no answer — fall through to the byte-identical refusal.
                 }
             }
             if (approveResolved === undefined) {
@@ -1237,8 +1309,15 @@ function makeRawHandlers(store, opts) {
             // element instead leaves a window in which an external edit is silently destroyed and the
             // STALE content gets sealed (measured: 17 of 40 concurrent edits lost, 35-55ms window).
             const cur = await store.read(a.id);
-            if (!cur)
-                return { ok: false, reason: `spec ${a.id} not found` };
+            // @implements A-SPEC-536.1 — BUG-1: a spec whose YAML is broken is dropped by read()/list(),
+            // so a bare "not found" hid that the file EXISTS but cannot be parsed. Surface the skipped
+            // files when there are any; byte-identical to the legacy message when there are none. The
+            // store's specsRoot is read through the same cast the reachability checks use (A-SPEC-169).
+            if (!cur) {
+                const dir = store.specsRoot;
+                const unreadable = typeof dir === 'string' ? (0, spec_store_1.unreadableSpecFiles)(dir) : [];
+                return { ok: false, reason: (0, spec_store_1.notFoundReason)(a.id, unreadable) };
+            }
             const spec = cur.spec;
             // @implements A-SPEC-188 — duplicates make the id ambiguous, for the SPEC and for its
             // PARENTS alike. Round-3 probed the parent half: with a stray duplicate of the parent
@@ -1807,6 +1886,26 @@ function makeRawHandlers(store, opts) {
             // 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 deriveChangedContext(store, 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 {
@@ -1847,6 +1946,12 @@ function makeRawHandlers(store, opts) {
             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
@@ -3038,7 +3143,7 @@ id: ${aspecId}
 type: A-SPEC
 title: ${(0, yaml_scalar_1.yamlScalar)(`Architecture Specification for ${a.title}`)}
 status: draft
-slice: ${a.sliceName}
+slice: ${(0, yaml_scalar_1.yamlScalar)(a.sliceName)}
 priority: P1
 independent_test: true
 depends_on:

package/dist/holmes/mcp/server-instructions.d.ts

@@ -0,0 +1,8 @@
+import { InstallMode } from '../update/update-notice';
+export interface ServerInstructionsInput {
+    version: string;
+    home: string;
+    mode: InstallMode;
+    readFile: (p: string) => string;
+}
+export declare function buildServerInstructions(input: ServerInstructionsInput): string;

package/dist/holmes/mcp/server-instructions.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServerInstructions = buildServerInstructions;
+// @implements A-SPEC-531.2
+// The MCP server's `instructions` banner. A harness with no SessionStart hook (codex, antigravity)
+// still gets the intro (+ optional update notice) delivered to the agent through the server's
+// initialize response. PURE and fail-soft — a cache read failure yields the intro only, and never
+// throws, so server construction is never blocked by the banner.
+const update_notice_1 = require("../update/update-notice");
+function buildServerInstructions(input) {
+    const cached = (0, update_notice_1.readCache)(input.home, input.readFile); // readCache already swallows a throw → null
+    return (0, update_notice_1.composeBanner)({ current: input.version, cached, mode: input.mode, npmUrl: update_notice_1.NPM_URL });
+}

package/dist/holmes/mcp/server.js

@@ -54,7 +54,27 @@ const PKG_VERSION = (() => {
         return '0.0.0';
     }
 })();
-const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} } });
+// @implements A-SPEC-531.2 — the banner rides `instructions` so a harness without a SessionStart
+// hook still delivers the intro (+ update notice) to the agent. Fail-soft: any failure omits it and
+// the server starts normally.
+const SERVER_INSTRUCTIONS = (() => {
+    try {
+        const { buildServerInstructions } = require('./server-instructions');
+        const { detectInstallMode } = require('../hooks/session-start');
+        const os = require('node:os');
+        const fs = require('node:fs');
+        return buildServerInstructions({
+            version: PKG_VERSION,
+            home: os.homedir(),
+            mode: detectInstallMode(require('node:path').resolve(__dirname, '..', '..', '..')),
+            readFile: (p) => fs.readFileSync(p, 'utf8'),
+        });
+    }
+    catch {
+        return undefined;
+    }
+})();
+const server = new index_js_1.Server({ name: 'holmes-kit', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS });
 const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
 // Register each handler as a tool with its real typed inputSchema so MCP
 // clients can marshal complex (array/object) arguments; fall back to a

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

@@ -203,6 +203,7 @@ exports.TOOL_SCHEMAS = {
                 head: str('Head rev (e.g. HEAD). Optional — omit to compare against a baseline.'),
                 since: str('Baseline label to compare against when no git range is given (default `last-green`, recorded by a passing test_run). Works with or without version control.'),
                 mark: str('Baseline label to record when the run passes (default `last-green`). Nothing is recorded for a red or skipped run.'),
+                mutate: str('T-SPEC id (e.g. T-SPEC-129.1). When set, runs that spec’s declared `kills` mutations against the A-SPEC’s source and reports which SURVIVED — a discriminating-power gap. Selective, opt-in; the ordinary run is skipped.'),
             },
             required: ['root'],
         },

package/dist/holmes/review/mutate.d.ts

@@ -0,0 +1,17 @@
+import { Mutation } from '../spec/kills';
+import { TestOutcome } from './test-runner';
+/**
+ * Did the mutation KILL the covering tests? A kill is a `red-assertion` in at least one covering
+ * file — the mutation broke behaviour and a test caught it. A green (or absent, or red-error) result
+ * is `survived`: the tests did not catch the change, which is a discriminating-power gap. Pure.
+ */
+export declare function mutationVerdict(outcomeByFile: Record<string, TestOutcome>, coveringFiles: string[]): 'killed' | 'survived';
+/**
+ * Apply one mutation to a source file, run the covering tests through the injected runner, judge the
+ * verdict, and ALWAYS restore the original source. `applied:false` when `where` is absent (the file
+ * is never touched).
+ */
+export declare function runKillsOnFile(sourceFile: string, mutation: Mutation, coveringFiles: string[], run: (files: string[]) => Record<string, TestOutcome>): {
+    applied: boolean;
+    verdict?: 'killed' | 'survived';
+};

package/dist/holmes/review/mutate.js

@@ -0,0 +1,66 @@
+"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.mutationVerdict = mutationVerdict;
+exports.runKillsOnFile = runKillsOnFile;
+// @implements A-SPEC-534.8
+const fs = __importStar(require("node:fs"));
+const kills_1 = require("../spec/kills");
+/**
+ * Did the mutation KILL the covering tests? A kill is a `red-assertion` in at least one covering
+ * file — the mutation broke behaviour and a test caught it. A green (or absent, or red-error) result
+ * is `survived`: the tests did not catch the change, which is a discriminating-power gap. Pure.
+ */
+function mutationVerdict(outcomeByFile, coveringFiles) {
+    return coveringFiles.some((f) => outcomeByFile[f] === 'red-assertion') ? 'killed' : 'survived';
+}
+/**
+ * Apply one mutation to a source file, run the covering tests through the injected runner, judge the
+ * verdict, and ALWAYS restore the original source. `applied:false` when `where` is absent (the file
+ * is never touched).
+ */
+function runKillsOnFile(sourceFile, mutation, coveringFiles, run) {
+    const original = fs.readFileSync(sourceFile, 'utf8');
+    const mutated = (0, kills_1.applyMutation)(original, mutation);
+    if (mutated === null)
+        return { applied: false }; // where absent: never touch the file
+    fs.writeFileSync(sourceFile, mutated);
+    try {
+        return { applied: true, verdict: mutationVerdict(run(coveringFiles), coveringFiles) };
+    }
+    finally {
+        fs.writeFileSync(sourceFile, original); // ALWAYS restore, even if run() threw
+    }
+}

package/dist/holmes/review/test-outcomes.d.ts

@@ -0,0 +1,35 @@
+import { TestOutcome } from './test-runner';
+export declare const OUTCOMES_FILE: string;
+/**
+ * A durable, append-only record of a per-A-SPEC test outcome (REQ-534 RED-first evidence). Unlike
+ * `test-evidence.json` (overwritten each run), the SEQUENCE matters here — a red-assertion followed
+ * by a green is what ART-8 reads — so outcomes accumulate. `head` stamps the baseline commit the
+ * run sat on; the red (before code) and green (after code) of one slice share it while the tree is
+ * still dirty, which is exactly when the Stop gate reads them.
+ */
+export interface OutcomeRecord {
+    aspec: string;
+    outcome: TestOutcome;
+    ts: string;
+    head: string;
+    testFileDigest?: string;
+}
+/** Append outcome records as JSONL lines. Fail-open (recording must never break a run). */
+export declare function appendOutcomes(root: string, records: OutcomeRecord[]): boolean;
+/** Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers). */
+export declare function readOutcomes(root: string): OutcomeRecord[];
+/**
+ * @implements A-SPEC-534.5
+ * Expand per-file outcomes into per-A-SPEC records via the anchor map, stamping each with the run's
+ * head and ts. A file with no anchor (or an empty anchor list) contributes nothing — an outcome that
+ * cannot be attributed to an A-SPEC is not evidence about one. Pure.
+ */
+export declare function buildOutcomeRecords(outcomeByFile: Record<string, TestOutcome>, anchors: Record<string, string[]>, head: string, ts: string): OutcomeRecord[];
+/**
+ * Group outcomes by A-SPEC, keeping only records stamped with the given baseline `head` — a stale
+ * record from another commit cannot vouch for the current work (the isFresh discipline). Pure.
+ */
+export declare function groupOutcomesByAspec(records: OutcomeRecord[], head: string): Record<string, Array<{
+    outcome: TestOutcome;
+    ts: string;
+}>>;