mjolnir-qa 0.5.36 → 0.5.38

package/dist/cli.mjs

@@ -11178,19 +11178,19 @@ function parseJestJson(json) {
 }
 //#endregion
 //#region src/forensics/parse-junit.ts
-const MAX_INPUT = 20971520;
-function decodeEntities(s) {
+const MAX_INPUT$1 = 20971520;
+function decodeEntities$1(s) {
 	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
 }
 function attr(tag, name) {
 	const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 	const m = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*"([^"]*)"`, "i").exec(tag);
-	if (m?.[1] !== void 0) return decodeEntities(m[1]);
+	if (m?.[1] !== void 0) return decodeEntities$1(m[1]);
 	const m2 = new RegExp(`(?:^|\\s)${escaped}\\s*=\\s*'([^']*)'`, "i").exec(tag);
-	return m2?.[1] !== void 0 ? decodeEntities(m2[1]) : void 0;
+	return m2?.[1] !== void 0 ? decodeEntities$1(m2[1]) : void 0;
 }
 function parseJunitXml(xml) {
-	if (xml.length > MAX_INPUT) return [];
+	if (xml.length > MAX_INPUT$1) return [];
 	const out = [];
 	const startRe = /<testcase\b/gi;
 	const closeRe = /<\/testcase\s*>/gi;
@@ -11345,7 +11345,7 @@ function parseVitestJson(json) {
 *
 * Writes FLAKY.md next to the scan target unless --no-flaky-md.
 */
-const MAX_FILES = 500;
+const MAX_FILES$1 = 500;
 function runForensics(target, options = {}) {
 	const records = [];
 	let source = "playwright-json";
@@ -11369,7 +11369,7 @@ function runForensics(target, options = {}) {
 	else {
 		let count = 0;
 		for (const full of listFiles(target)) {
-			if (++count > MAX_FILES) break;
+			if (++count > MAX_FILES$1) break;
 			try {
 				const parsed = parseFile(full, readFileSync(full, "utf8"));
 				if (parsed.records.length === 0) continue;
@@ -11437,7 +11437,7 @@ function parseFile(path, text) {
 function listFiles(dir) {
 	const out = [];
 	const walk = (d, depth) => {
-		if (depth > 4 || out.length > MAX_FILES) return;
+		if (depth > 4 || out.length > MAX_FILES$1) return;
 		let entries;
 		try {
 			entries = readdirSync(d, { withFileTypes: true });
@@ -13464,7 +13464,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.36",
+			version: "0.5.38",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14697,6 +14697,7 @@ function agentBrief(surface, cwdNote) {
 		"- Exit 0 = clean. Exit 1 = new findings on changed lines: fix them (smallest behavior-preserving change) or justify them to the user.",
 		`- npx mjolnir-qa@${CLI_VERSION} why <file>:<line> explains any finding (evidence level, measured FP rate, fix).`,
 		`- npx mjolnir-qa@${CLI_VERSION} handoff renders a full remediation plan from a saved --json report.`,
+		`- Agent loop: establish the before-state once with npx mjolnir-qa@${CLI_VERSION} baseline (commits .mjolnir/baseline.json); after fixing, npx mjolnir-qa@${CLI_VERSION} verify prints the before/after digest — resolved (per §15 lifecycle) / new / unchanged by ruleId+location, and the score delta. Exit 0 clean, 1 new errors, 2 partial or no baseline.`,
 		"- NEVER suppress a finding merely to obtain a green scan (suppressions live in mjolnir.config.json, require a reason, and expire after 90 days).",
 		"- After fixing: re-run the scan, report files changed, report checks not run, report unresolved findings honestly.",
 		"",
@@ -15525,6 +15526,113 @@ function renderBaselineDiff(diff) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/commands/verify.ts
+/**
+* `mjolnir verify` — the agent-loop digest (product-gap-remediation
+* master plan P7, plan 1788853205786 — flag agent, decision 6).
+*
+* An agent fixes findings, then runs `mjolnir verify` against the
+* committed baseline (established once with `mjolnir baseline`). The
+* digest answers exactly the loop's questions, derived from the SAME
+* §15 comparison machinery as `mjolnir diff` (no second truth):
+*
+*   - RESOLVED — baseline findings no longer present, each with its
+*     lifecycle resolution (only VERIFIED-RESOLVED is a fix claim);
+*   - NEW — findings the fix introduced;
+*   - UNCHANGED — pre-existing debt, grouped by ruleId + location
+*     (the agent-loop key: an agent works by location, not message);
+*   - SCORE DELTA — before (baseline) → after (this scan).
+*
+* Exit semantics are the frozen contract: 0 clean · 1 new error
+* findings · 2 partial scan or no baseline (nothing to verify against
+* — the agent must first establish the before-state).
+*/
+function buildVerifyDigest(result, baseline) {
+	const diff = diffAgainstBaseline(result, baseline);
+	const digest = {
+		hasBaseline: diff.hasBaseline,
+		...diff.baselineCapturedAt !== void 0 ? { baselineCapturedAt: diff.baselineCapturedAt } : {},
+		...diff.baselineCommit !== void 0 ? { baselineCommit: diff.baselineCommit } : {},
+		resolved: diff.resolvedFindings.map((f) => ({
+			ruleId: f.ruleId,
+			file: f.file,
+			resolution: f.resolution.status
+		})),
+		new: diff.newFindings.map((f) => ({
+			ruleId: f.ruleId,
+			file: f.file,
+			line: f.line,
+			severity: f.severity
+		})),
+		unchanged: [],
+		unchangedCount: diff.unchangedCount,
+		scoreBefore: diff.baselineScore ?? null,
+		scoreAfter: result.score ?? null,
+		scoreDelta: diff.baselineScore !== void 0 && result.score !== null ? result.score - diff.baselineScore : null
+	};
+	if (diff.hasBaseline && baseline) {
+		const byRule = /* @__PURE__ */ new Map();
+		const headByFingerprint = /* @__PURE__ */ new Map();
+		for (const f of result.findings) headByFingerprint.set(`${f.ruleId}\u0000${f.file}\u0000${f.message}`, f);
+		for (const b of baseline.findings) {
+			const head = headByFingerprint.get(`${b.ruleId}\u0000${b.file}\u0000${b.message}`);
+			if (!head) continue;
+			let group = byRule.get(b.ruleId);
+			if (!group) {
+				group = {
+					ruleId: b.ruleId,
+					locations: []
+				};
+				byRule.set(b.ruleId, group);
+			}
+			group.locations.push(`${head.file}:${head.line}`);
+		}
+		digest.unchanged = [...byRule.values()].map((g) => ({
+			ruleId: g.ruleId,
+			locations: g.locations.sort()
+		}));
+	}
+	return digest;
+}
+function renderVerifyDigest(digest) {
+	if (!digest.hasBaseline) return [
+		"VERIFY — no baseline",
+		"",
+		"No committed baseline at .mjolnir/baseline.json — nothing to verify",
+		"against. Establish the before-state once with `mjolnir baseline`,",
+		"then re-run `mjolnir verify` after the fix."
+	].join("\n");
+	const lines = [];
+	lines.push("VERIFY — before/after digest");
+	lines.push("");
+	if (digest.scoreDelta !== null) {
+		const dir = digest.scoreDelta > 0 ? "improved" : digest.scoreDelta < 0 ? "worse" : "unchanged";
+		lines.push(`score: ${digest.scoreBefore} → ${digest.scoreAfter} (${dir}, Δ${digest.scoreDelta >= 0 ? "+" : ""}${digest.scoreDelta})`);
+	}
+	lines.push(`${digest.resolved.length} resolved · ${digest.new.length} new · ${digest.unchangedCount} unchanged`);
+	lines.push("");
+	if (digest.resolved.length > 0) {
+		lines.push("RESOLVED (per §15 lifecycle — only VERIFIED-RESOLVED is a fix claim):");
+		for (const r of digest.resolved) lines.push(`  ${r.ruleId} ${r.file} — ${r.resolution}`);
+		lines.push("");
+	}
+	if (digest.new.length > 0) {
+		lines.push("NEW (introduced by the change under verification):");
+		for (const n of digest.new) lines.push(`  ${n.ruleId} ${n.file}:${n.line} (${n.severity})`);
+		lines.push("");
+	}
+	if (digest.unchanged.length > 0) {
+		lines.push("UNCHANGED (pre-existing debt — out of this fix's scope):");
+		for (const g of digest.unchanged) {
+			lines.push(`  ${g.ruleId} × ${g.locations.length}`);
+			for (const loc of g.locations.slice(0, 5)) lines.push(`    ${loc}`);
+			if (g.locations.length > 5) lines.push(`    … and ${g.locations.length - 5} more`);
+		}
+		lines.push("");
+	}
+	return lines.join("\n").trimEnd();
+}
+//#endregion
 //#region src/mcp/server.ts
 /** Hard caps (§21 threat model: parameter size + resource bounds). */
 const MAX_PARAM_BYTES = 65536;
@@ -15586,6 +15694,18 @@ const MCP_TOOLS = [
 			},
 			required: ["path", "scanResult"]
 		}
+	},
+	{
+		name: "verify",
+		description: "Agent-loop digest (1:1 with `mjolnir verify`): scan the target and diff against the committed baseline. Returns resolved (per §15 lifecycle), new, unchanged (grouped by ruleId + location), and the score delta. Read-only; the same transport guardrails as every other tool.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Directory to scan and verify."
+			} },
+			required: ["path"]
+		}
 	}
 ];
 /** Strict param validation — unknown/missing/mistyped ⇒ INVALID_PARAMS. */
@@ -15602,6 +15722,9 @@ function validateParams(name, args) {
 		if (typeof args["path"] !== "string" || args["path"].length === 0) return "diff requires a non-empty string `path`";
 		if (typeof args["scanResult"] !== "object" || args["scanResult"] === null) return "diff requires the `scanResult` object from a previous scan tool call";
 	}
+	if (name === "verify") {
+		if (typeof args["path"] !== "string" || args["path"].length === 0) return "verify requires a non-empty string `path`";
+	}
 	return null;
 }
 /**
@@ -15718,6 +15841,52 @@ async function handleToolCall(call) {
 				}
 			};
 		}
+		if (call.name === "verify") {
+			const target = resolve(call.args["path"]);
+			if (!existsSync(target)) return {
+				jsonrpc: "2.0",
+				id: call.id,
+				error: {
+					code: MCP_ERRORS.INVALID_PARAMS,
+					message: `verify target does not exist: ${target}`
+				}
+			};
+			const baselinePath = join(target, DEFAULT_BASELINE_PATH);
+			if (!existsSync(baselinePath)) return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: {
+					hasBaseline: false,
+					note: "no committed baseline at .mjolnir/baseline.json — establish the before-state with `mjolnir baseline` first"
+				}
+			};
+			const result = await serializeScan(() => runScan({
+				target,
+				json: true,
+				verbose: false,
+				maxDurationMs: Number.POSITIVE_INFINITY,
+				scopeChanged: false,
+				format: "json"
+			}));
+			const digest = buildVerifyDigest(result, loadBaseline(baselinePath));
+			return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: {
+					hasBaseline: digest.hasBaseline,
+					baselineCapturedAt: digest.baselineCapturedAt,
+					baselineCommit: digest.baselineCommit,
+					resolved: digest.resolved,
+					new: digest.new,
+					unchanged: digest.unchanged,
+					unchangedCount: digest.unchangedCount,
+					scoreBefore: digest.scoreBefore,
+					scoreAfter: digest.scoreAfter,
+					scoreDelta: digest.scoreDelta,
+					partial: result.partial
+				}
+			};
+		}
 		return {
 			jsonrpc: "2.0",
 			id: call.id,
@@ -16314,6 +16483,220 @@ function renderTriageMd(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/mutation/parse-stryker.ts
+const MAX_FILES = 5e3;
+const MAX_MUTANTS_PER_FILE = 2e4;
+/** Sniff: does this parsed JSON look like a Stryker mutation report? */
+function looksLikeStrykerJson(json) {
+	if (!json || typeof json !== "object") return false;
+	return typeof json.files === "object" && json.files !== null;
+}
+function parseStrykerJson(json) {
+	if (!json || typeof json !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const files = json.files;
+	if (!files || typeof files !== "object") return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const entries = Object.entries(files).slice(0, MAX_FILES);
+	for (const [rawPath, file] of entries) {
+		if (!file || typeof file !== "object") continue;
+		const mutants = Array.isArray(file.mutants) ? file.mutants : [];
+		const path = rawPath.replaceAll("\\", "/");
+		for (const m of mutants.slice(0, MAX_MUTANTS_PER_FILE)) {
+			if (!m || typeof m !== "object") continue;
+			if (m.status === "Survived") {
+				const startLine = toOneBased(m.location?.start?.line);
+				const endLine = toOneBased(m.location?.end?.line);
+				if (startLine === void 0) continue;
+				survived.push({
+					file: path,
+					mutator: typeof m.mutatorName === "string" ? m.mutatorName : "unknown",
+					startLine,
+					endLine: endLine !== void 0 ? Math.max(startLine, endLine) : startLine
+				});
+			} else if (m.status === "NoCoverage") noCoverage++;
+			else if (m.status === "Killed" || m.status === "Timeout") killed++;
+		}
+	}
+	return {
+		tool: "stryker",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+function toOneBased(line) {
+	return typeof line === "number" && line >= 0 ? line + 1 : void 0;
+}
+//#endregion
+//#region src/mutation/parse-mutmut.ts
+const MAX_INPUT = 20971520;
+/** Sniff: does this XML look like mutmut's junit output? */
+function looksLikeMutmutXml(xml) {
+	return xml.length <= MAX_INPUT && /mutmut/i.test(xml.slice(0, 4e3));
+}
+function decodeEntities(s) {
+	return s.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", "\"").replaceAll("&apos;", "'").replaceAll("&#39;", "'").replaceAll("&amp;", "&");
+}
+/**
+* The file for a testcase: mutmut 2.x writes
+* `classname="tests.test_auth-mutmut0::x_mutmut_1"`-style classes whose
+* FIRST dot-separated segment before `-mutmut` is the module path;
+* mutmut 3.x writes the path directly in `classname`. Both are
+* normalized here to a repo-relative path with `.py` intact.
+*/
+function fileFromClassname(classname) {
+	const decoded = decodeEntities(classname);
+	const cut = decoded.indexOf("-mutmut");
+	const candidate = (cut !== -1 ? decoded.slice(0, cut) : decoded).trim();
+	if (candidate.length === 0) return null;
+	return candidate.replaceAll(".", "/") + ".py";
+}
+function parseMutmutXml(xml) {
+	if (xml.length > MAX_INPUT) return {
+		tool: "mutmut",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+	const survived = [];
+	let noCoverage = 0;
+	let killed = 0;
+	const startRe = /<testcase\b/gi;
+	const closeRe = /<\/testcase\s*>/gi;
+	let start;
+	while ((start = startRe.exec(xml)) !== null) {
+		const gt = xml.indexOf(">", start.index);
+		if (gt === -1) break;
+		const attrs = xml.slice(start.index + 9, gt);
+		let inner;
+		if (attrs.endsWith("/")) {
+			inner = "";
+			startRe.lastIndex = gt + 1;
+		} else {
+			closeRe.lastIndex = gt + 1;
+			const close = closeRe.exec(xml);
+			if (close === null) break;
+			inner = xml.slice(gt + 1, close.index);
+			startRe.lastIndex = close.index + close[0].length;
+		}
+		const classname = /(?:^|\s)classname\s*=\s*"([^"]*)"/i.exec(attrs)?.[1] ?? "";
+		if (/<skipped\b/i.test(inner)) {
+			noCoverage++;
+			continue;
+		}
+		const killedMutant = /<(?:failure|error)\b/i.test(inner);
+		const verdict = {
+			file: fileFromClassname(classname),
+			survived: !killedMutant
+		};
+		if (killedMutant) killed++;
+		else if (verdict.file !== null) survived.push({
+			file: verdict.file,
+			mutator: "mutmut",
+			startLine: 1,
+			endLine: Number.MAX_SAFE_INTEGER
+		});
+		else noCoverage++;
+	}
+	return {
+		tool: "mutmut",
+		survived,
+		noCoverage,
+		killed
+	};
+}
+//#endregion
+//#region src/mutation/derive.ts
+/**
+* Stamp mutation evidence onto findings (mutates in place, the same
+* contract as stampEvidenceLevels). Returns the stamp stats.
+*/
+function stampMutationEvidence(findings, report) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	let stamped = 0;
+	let derived = 0;
+	for (const f of findings) {
+		const mutants = byFile.get(f.file);
+		if (!mutants || mutants.length === 0) continue;
+		let matched = mutants.filter((m) => f.line >= m.startLine && f.line <= m.endLine);
+		let granularity = "line";
+		if (matched.length === 0) {
+			matched = mutants;
+			granularity = "file";
+		}
+		f.mutationEvidence = {
+			source: report.tool,
+			matchedMutants: matched.length,
+			mutators: [...new Set(matched.map((m) => m.mutator))].sort(),
+			granularity
+		};
+		stamped++;
+		if (f.evidenceLevel === "E1") {
+			f.evidenceLevel = "E2";
+			derived++;
+		}
+	}
+	return {
+		stamped,
+		derived
+	};
+}
+/**
+* Survived-mutant leaderboard: most-mutated files first. The summary's
+* honesty headline: files here are code the suite demonstrably does not
+* constrain — regardless of what any static tool found.
+*/
+function survivedLeaderboard(report, top = 25) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const m of report.survived) {
+		const list = byFile.get(m.file) ?? [];
+		list.push(m);
+		byFile.set(m.file, list);
+	}
+	return [...byFile.entries()].map(([file, mutants]) => ({
+		file,
+		survived: mutants.length,
+		mutators: [...new Set(mutants.map((m) => m.mutator))].sort()
+	})).sort((a, b) => b.survived - a.survived).slice(0, top);
+}
+function renderMutationSummary(report) {
+	const lines = [];
+	lines.push(`MUTATION EVIDENCE — ${report.tool}`);
+	lines.push("");
+	lines.push(`${report.survived.length} survived · ${report.killed} killed · ${report.noCoverage} no-coverage`);
+	lines.push("");
+	const top = survivedLeaderboard(report);
+	if (top.length === 0) {
+		lines.push("No survived mutants — every executed mutant was killed.");
+		lines.push("");
+		lines.push("Interpretation: the suite constrains the code the mutation run reached. This is evidence about THOSE mutants only — untested surfaces are the no-coverage column, and no-coverage is not survived.");
+		return lines.join("\n");
+	}
+	lines.push("Files the suite does not constrain (most survived first):");
+	lines.push("");
+	for (const row of top) lines.push(`  ${row.survived}× ${row.file} [${row.mutators.join(", ")}]`);
+	lines.push("");
+	lines.push("A survived mutant is not a bug — it is code the suite would not notice changing. Findings near these lines were consolidated E1→E2 by derivation (see docs/RULE-LIFECYCLE.md).");
+	return lines.join("\n");
+}
+//#endregion
 //#region src/commands/badge.ts
 /**
 * `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
@@ -16422,6 +16805,12 @@ const HELP_ENTRIES = [
 		usage: "mjolnir triage <test-results-dir-or-report-file> [--no-md]",
 		examples: ["mjolnir triage test-results --no-md"]
 	},
+	{
+		verb: "mutation",
+		summary: "mutation-evidence reader: survived-mutant leaderboard + E1→E2 derivation",
+		usage: "mjolnir mutation <mutation-report> [--scan .]",
+		examples: ["mjolnir mutation reports/mutation-report.json", "mjolnir mutation reports/… --scan ."]
+	},
 	{
 		verb: "pw-report",
 		summary: "Playwright run summary (counts, true flakes, slowest tests)",
@@ -16449,10 +16838,16 @@ const HELP_ENTRIES = [
 	},
 	{
 		verb: "diff",
-		summary: "compare a fresh scan against the baseline — new/worsened only",
-		usage: "mjolnir diff [path]",
+		summary: "lifecycle diff vs the committed baseline",
+		usage: "mjolnir diff [path] [--json] [scan flags]",
 		examples: ["mjolnir diff"]
 	},
+	{
+		verb: "verify",
+		summary: "agent-loop digest: resolved/new/unchanged vs baseline + score delta",
+		usage: "mjolnir verify [path] [--json] [scan flags]",
+		examples: ["mjolnir verify"]
+	},
 	{
 		verb: "impact",
 		summary: "what a commit introduced vs resolved, since a prior commit",
@@ -16539,7 +16934,7 @@ const HELP_ENTRIES = [
 	},
 	{
 		verb: "mcp",
-		summary: "run as an MCP server over stdio (scan / explain / diff tools)",
+		summary: "run as an MCP server over stdio (scan / explain / diff / verify tools)",
 		usage: "mjolnir mcp",
 		examples: ["mjolnir mcp"]
 	}
@@ -16692,7 +17087,8 @@ const GROUPS = [
 			"badge",
 			"impact",
 			"baseline",
-			"diff"
+			"diff",
+			"verify"
 		]
 	},
 	{
@@ -16704,6 +17100,10 @@ const GROUPS = [
 			"doctor:playwright"
 		]
 	},
+	{
+		title: "Mutation evidence",
+		verbs: ["mutation"]
+	},
 	{
 		title: "Maintenance",
 		verbs: [
@@ -19022,7 +19422,7 @@ const { runScan, buildUniversalRules, fallbackWorkspace, pathMatchesGlob, isVali
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.36";
+const CLI_VERSION = "0.5.38";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -19508,6 +19908,97 @@ function runTriageCommand(argv, io = {
 		return 20;
 	}
 }
+/**
+* Sniff + parse a mutation report: Stryker JSON, mutmut junitxml, else
+* an empty report (the caller renders the honest "nothing recognized").
+*/
+function ingestMutationReport(text) {
+	const trimmed = text.trimStart();
+	if (trimmed.startsWith("<?xml") || trimmed.startsWith("<testsuite")) return parseMutmutXml(text);
+	try {
+		const json = JSON.parse(text);
+		if (looksLikeStrykerJson(json)) return parseStrykerJson(json);
+	} catch {}
+	if (looksLikeMutmutXml(text)) return parseMutmutXml(text);
+	return {
+		tool: "stryker",
+		survived: [],
+		noCoverage: 0,
+		killed: 0
+	};
+}
+/** Testable `mutation` handler (master plan P5, plan 1788853205786).
+* Reads a mutation report (Stryker JSON / mutmut junitxml), renders the
+* survived-mutant leaderboard, and — with `--scan <path>` — re-scans the
+* target, stamps matching findings with `mutationEvidence` (E1→E2 by
+* derivation) and renders the stamped findings. NEVER spawns mutation
+* tools: it reads reports the user already produced. Exit 2 when
+* nothing in the report is recognized — honest no-evidence, not an
+* error. Exit 0 in every other case: the reader is report-only, never a
+* gate. */
+async function runMutationCommand(argv, io = {
+	out,
+	err
+}) {
+	const targetArg = argv.find((a) => !a.startsWith("-"));
+	if (!targetArg) {
+		io.err("Usage: mjolnir mutation <mutation-report> [--scan <path>]");
+		return 10;
+	}
+	const scanIdx = argv.indexOf("--scan");
+	const scanArg = scanIdx !== -1 ? argv[scanIdx + 1] : void 0;
+	if (scanIdx !== -1 && (!scanArg || scanArg.startsWith("-"))) {
+		io.err("--scan requires a path argument");
+		return 10;
+	}
+	let report;
+	try {
+		const path = resolve(targetArg);
+		if (!existsSync(path)) {
+			io.err(`No such file: ${path}`);
+			return 2;
+		}
+		report = ingestMutationReport(readFileSync(path, "utf8"));
+		if (report.survived.length === 0 && report.killed === 0 && report.noCoverage === 0) {
+			io.err("No mutants recognized. Expected a Stryker JSON report (mutation-report.json) or a mutmut junitxml report.");
+			return 2;
+		}
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+	io.out(renderMutationSummary(report));
+	if (scanArg === void 0) return 0;
+	try {
+		const scanPath = resolve(scanArg);
+		const invalid = validateScanTarget(scanPath, io.err);
+		if (invalid !== null) return invalid;
+		const result = await runScan({
+			target: scanPath,
+			json: true,
+			verbose: true,
+			maxDurationMs: 12e4,
+			scopeChanged: false,
+			format: "json"
+		});
+		const stats = stampMutationEvidence(result.findings, report);
+		io.out("");
+		if (stats.stamped === 0) io.out("No findings intersect the survived-mutant surface — nothing to derive.");
+		else {
+			io.out(`${stats.stamped} finding(s) carry mutationEvidence (${stats.derived} consolidated E1→E2 by derivation — docs/RULE-LIFECYCLE.md):`);
+			for (const f of result.findings) {
+				if (!f.mutationEvidence) continue;
+				io.out(`  ${f.ruleId} ${f.file}:${f.line} — ${f.evidenceLevel} · ${f.mutationEvidence.matchedMutants} mutant(s) @ ${f.mutationEvidence.granularity} granularity`);
+			}
+			io.out("");
+			io.out("Machine form: re-run with --json — mutationEvidence rides the findings additively.");
+		}
+		return 0;
+	} catch (err) {
+		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
+		return 20;
+	}
+}
 /** Testable `badge` handler (Tier 1 #5). */
 async function runBadgeCommand(argv, io = {
 	out,
@@ -19689,6 +20180,36 @@ async function runBaselineCommand(argv, io = {
 	}
 }
 /** Testable `diff` handler (Sprint 6 Task 24) — new/worsened debt only. */
+/** Testable `verify` handler — the agent-loop verb (master plan P7,
+* plan 1788853205786). Scans the target and diffs against the committed
+* baseline, rendering the before/after digest the agent loop consumes
+* (resolved per §15 · new · unchanged by ruleId+location · score delta).
+* Exit semantics are the frozen contract: 0 clean · 1 new error
+* findings · 2 partial scan or no baseline · 20 internal. */
+async function runVerifyCommand(argv, io = {
+	out,
+	err
+}) {
+	const args = parseArgsOrUsage(argv, io);
+	if (!args) return 10;
+	try {
+		const target = resolve(args.target);
+		const invalid = validateScanTarget(target, io.err);
+		if (invalid !== null) return invalid;
+		const result = await runScan({
+			...args,
+			target
+		});
+		const digest = buildVerifyDigest(result, loadBaseline(join(target, DEFAULT_BASELINE_PATH), (w) => io.err(w)));
+		io.out(renderVerifyDigest(digest));
+		if (result.partial) return 2;
+		if (!digest.hasBaseline) return 2;
+		return digest.new.some((f) => f.severity === "error") ? 1 : 0;
+	} catch (err) {
+		internalErrorMessage(err, io.err, args?.debug === true);
+		return 20;
+	}
+}
 async function runDiffCommand(argv, io = {
 	out,
 	err
@@ -19886,11 +20407,13 @@ async function main(argv = process$1.argv.slice(2), io = {
 	if (argv[0] === "suppressions") return runSuppressions();
 	if (argv[0] === "forensics") return runForensicsCommand(argv.slice(1));
 	if (argv[0] === "triage") return runTriageCommand(argv.slice(1));
+	if (argv[0] === "mutation") return runMutationCommand(argv.slice(1), io);
 	if (argv[0] === "badge") return runBadgeCommand(argv.slice(1));
 	if (argv[0] === "debt") return runDebtCommand(argv.slice(1));
 	if (argv[0] === "impact") return runImpactCommand(argv.slice(1));
 	if (argv[0] === "baseline") return runBaselineCommand(argv.slice(1));
 	if (argv[0] === "diff") return runDiffCommand(argv.slice(1));
+	if (argv[0] === "verify") return runVerifyCommand(argv.slice(1), io);
 	if (argv[0] === "pr-comment") return runPrCommentCommand(argv.slice(1));
 	if (argv[0] === "summary") return runSummaryCommand(argv.slice(1), io);
 	if (argv[0] === "stats") return runStatsCommand(argv.slice(1));
@@ -19962,4 +20485,4 @@ function isEntryPoint() {
 }
 if (isEntryPoint()) process$1.exitCode = await main();
 //#endregion
-export { CLI_VERSION, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, SUITE_INVALIDATING_RULE_IDS, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, usageErrorMessage };
+export { CLI_VERSION, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, SUITE_INVALIDATING_RULE_IDS, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runMutationCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, runVerifyCommand, usageErrorMessage };