mjolnir-qa 0.5.19 → 0.5.23

package/dist/mcp/stdio.mjs

@@ -37,16 +37,42 @@ const QA_IMPACT_LABELS = {
 	"FALSE-GREEN": "False-green risk",
 	HYGIENE: "Test hygiene debt"
 };
-/** The closed set of rule categories (plan §5.5). `--category` values
-* are validated against this list — unknown categories are a usage
-* error, not a silent no-op. */
+/**
+* The closed set of rule categories (plan §5.5, certification-audit D6).
+* Declared FIRST as the single source of truth: the RuleCategory type is
+* DERIVED from this list (compile-time exhaustiveness — a category added
+* to the type without the value list, or vice versa, cannot compile).
+* `--category` values are validated against this list — unknown
+* categories are a usage error, not a silent no-op. Rule namespaces are
+* frozen public API (§18.4): IDs are never reused.
+*/
 const RULE_CATEGORIES = [
 	"QA-TEST",
 	"QA-TQUAL",
 	"QA-PW",
-	"QA-CI"
+	"QA-CI",
+	"QA-PY",
+	"QA-ENV",
+	"QA-JV",
+	"QA-CS",
+	"QA-CYP",
+	"QA-SE",
+	"QA-WDIO",
+	"QA-PPTR",
+	"QA-APM"
 ];
 /**
+* Category argument validation shared by every verb accepting
+* `--category` (scan/why/handoff — certification-audit Phase 1.2): the
+* three verbs must never disagree about what a valid category is. A
+* missing value or an unknown value is a usage error (exit 10) at the
+* caller — this helper returns the verdict, the caller renders the
+* rejection.
+*/
+function isValidCategory(value) {
+	return value !== void 0 && RULE_CATEGORIES.includes(value);
+}
+/**
 * Honest default evidence level for a finding (Honesty Core Phase 1).
 * Derivation is deterministic and conservative:
 *   observation → E0 (never proof)
@@ -13263,7 +13289,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.19",
+			version: "0.5.23",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14025,6 +14051,20 @@ async function runWhyCommand(argv, io = {
 	out: (line) => console.log(line),
 	err: (line) => console.error(line)
 }) {
+	const catIdxs = [];
+	argv.forEach((a, i) => {
+		if (a === "--category") catIdxs.push(i + 1);
+	});
+	const categories = [];
+	for (const i of catIdxs) {
+		const value = argv[i];
+		if (!isValidCategory(value)) {
+			io.err(`mjolnir why: unknown --category: ${value === void 0 ? "(missing value)" : value}`);
+			io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+			return 10;
+		}
+		categories.push(value);
+	}
 	const locationToken = argv.find((a) => !a.startsWith("-"));
 	if (!locationToken) {
 		io.err("Usage: mjolnir why <file>:<line> [--json <mjolnir.json>]");
@@ -14037,7 +14077,10 @@ async function runWhyCommand(argv, io = {
 	}
 	const jsonIdx = argv.indexOf("--json");
 	const reportPath = jsonIdx !== -1 ? argv[jsonIdx + 1] : void 0;
-	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && (jsonIdx === -1 || i !== jsonIdx + 1));
+	const valuePositions = /* @__PURE__ */ new Set();
+	if (jsonIdx !== -1) valuePositions.add(jsonIdx + 1);
+	for (const i of catIdxs) valuePositions.add(i);
+	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && !valuePositions.has(i));
 	const target = targetIdx !== -1 ? argv[targetIdx] : ".";
 	let result;
 	if (reportPath !== void 0) {
@@ -14073,11 +14116,6 @@ async function runWhyCommand(argv, io = {
 		}
 	}
 	const match = explainAt(result.findings, location.file, location.line);
-	const catIdxs = [];
-	argv.forEach((a, i) => {
-		if (a === "--category") catIdxs.push(i + 1);
-	});
-	const categories = catIdxs.map((i) => argv[i]).filter((c) => c !== void 0);
 	const filtered = categories.length > 0 ? match.findings.filter((f) => categories.includes(f.category)) : match.findings;
 	io.out(renderWhy({
 		...match,
@@ -14087,6 +14125,28 @@ async function runWhyCommand(argv, io = {
 }
 //#endregion
 //#region src/commands/handoff.ts
+/**
+* `mjolnir handoff [mjolnir.json]` — the deterministic fix-handoff
+* artifact (agent-handoff plan M3).
+*
+* Reads a saved `--json` report (shared loader, report-io.ts) and
+* renders a self-contained Markdown remediation plan an agent (or a
+* human) can execute offline. Every instruction is derived from
+* Mjölnir's own rule metadata — the generator produces INSTRUCTIONS,
+* never executable commands, and no prompt text is fetched or copied
+* from any external source.
+*
+* The artifact embeds the formal verification contract (plan §5.3):
+* what was detected, what should change, what justifies it (evidence
+* boundary per level), what to re-run, what counts as verified
+* (TARGET_RESOLVED / TARGET_REMAINS / NEW_FINDINGS_INTRODUCED /
+* VERIFICATION_NOT_RUN, correlated via the fingerprint rule), and the
+* standing caveat that a clean `--scope changed` run verifies the
+* changed-scope surface only — not that the repository is clean.
+*
+* Exit codes (frozen contract): 0 on success · 10 missing file ·
+* 2 unreadable/invalid JSON.
+*/
 const OCCURRENCE_CAP = 25;
 const EVIDENCE_BOUNDARY = {
 	E2: "The detector's evidence is deterministic for this pattern. Check the location, then apply the prescribed fix — the finding is a deterministic defect at its boundary.",
@@ -14316,6 +14376,11 @@ function runHandoffCommand(argv, io = {
 				}));
 				return 10;
 			}
+			if (a === "--category" && !isValidCategory(val)) {
+				io.err(`mjolnir handoff: unknown --category: ${val}`);
+				io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+				return 10;
+			}
 			i++;
 			continue;
 		}
@@ -17084,6 +17149,18 @@ function renderFixReport(results, dryRun) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/cli-io.ts
+const out = (...parts) => console.log(parts.map(String).join(" "));
+const err = (...parts) => console.error(parts.map(String).join(" "));
+function internalErrorMessage(err, emit, debug) {
+	const message = err instanceof Error ? err.message : String(err);
+	emit("mjolnir internal error — this is a bug in Mjölnir, not your repo:");
+	emit(`  ${message}`);
+	if (debug && err instanceof Error && err.stack) emit(err.stack);
+	emit("Rerun with --debug for the stack trace. Please report this:");
+	emit("  https://github.com/Sergey-Bar/Mjolnir/issues");
+}
+//#endregion
 //#region src/rules/measurement.ts
 /** The rule's declared detector implementation revision (§07). */
 function declaredDetectorRevision(rule) {
@@ -17319,6 +17396,15 @@ function errorText(e) {
 	return e instanceof Error ? e.message : String(e);
 }
 const ui$2 = plainContext();
+/** Builds the check record: `ok` is always the pass-mirror of `status`. */
+function check(name, status, details) {
+	return {
+		name,
+		status,
+		ok: status === "pass",
+		details
+	};
+}
 const VALID_ID = RULE_ID_RE;
 function nonHiddenFiles(dir) {
 	if (!existsSync(dir)) return [];
@@ -17341,11 +17427,7 @@ function checkFixtureFirewall(fixturesRoot) {
 			details.push(`${rule.id}: missing must-not-fire fixture`);
 		}
 	}
-	return {
-		name: "fixture-firewall",
-		ok,
-		details
-	};
+	return check("fixture-firewall", ok ? "pass" : "fail", details);
 }
 /** Check 2: registry sanity — IDs unique, well-formed, titles distinct. */
 function checkRegistry(rules = RULES) {
@@ -17368,20 +17450,12 @@ function checkRegistry(rules = RULES) {
 			details.push(`"${r.title}": duplicate title in family (${r.id})`);
 		}
 	}
-	return {
-		name: "registry-sanity",
-		ok,
-		details
-	};
+	return check("registry-sanity", ok ? "pass" : "fail", details);
 }
 /** Check 3: Trust Metadata presence (informational until full coverage). */
 function checkTrustMetadata(rules = RULES) {
 	const missing = rules.filter((r) => !r.languages?.length || !r.frameworks?.length || r.falsePositiveRisk === void 0);
-	return {
-		name: "trust-metadata",
-		ok: missing.length === 0,
-		details: missing.map((r) => `${r.id}: missing trust metadata`)
-	};
+	return check("trust-metadata", missing.length === 0 ? "pass" : "fail", missing.map((r) => `${r.id}: missing trust metadata`));
 }
 /**
 * Check 4 (Honesty Core): evidence-level honesty. A rule that claims a
@@ -17400,10 +17474,25 @@ function checkEvidenceHonesty(rules = RULES) {
 			details.push(`${r.id}: declares ${r.evidenceLevel} but findingType=${r.findingType}/confidence=${r.confidence} supports at most ${derived}`);
 		}
 	}
+	return check("evidence-honesty", ok ? "pass" : "fail", details);
+}
+/**
+* Measurement census (Phase 4.3): measured = rules with a valid
+* MEASURED_FP entry; unmeasured = the rest; quarantine = measured rules
+* whose effective tier is quarantine. One function, used by the doctor
+* report AND the JSON contract — a single reproducible answer.
+*/
+function measurementBlock(rules = RULES) {
+	const measured = rules.filter((r) => {
+		const m = MEASURED_FP[r.id];
+		return m !== void 0 && m.detectorRevision === declaredDetectorRevision(r);
+	});
+	const quarantine = measured.filter((r) => effectiveTier(r) === "quarantine");
 	return {
-		name: "evidence-honesty",
-		ok,
-		details
+		measured: measured.length,
+		unmeasured: rules.length - measured.length,
+		total: rules.length,
+		quarantine: quarantine.length
 	};
 }
 /**
@@ -17445,11 +17534,7 @@ function checkTierEnforcement(verdictsDir, rules = RULES) {
 	const total = coreRules.length;
 	const ok = unmeasured <= 0;
 	details.unshift(ok ? `Ratchet (Law #3): ${unmeasured}/${total} core rules lack a measured FP rate — cap is 0 (Phase 1 closed the unmeasured-core hole)` : `BLOCKING: ${unmeasured}/${total} core rules unmeasured — exceeds the Law #3 ratchet cap of 0`);
-	return {
-		name: "tier-enforcement",
-		ok,
-		details
-	};
+	return check("tier-enforcement", ok ? "pass" : "fail", details);
 }
 /**
 * Check 6 (Phase 7 — Tempering Plan): anti-creep law enforcement.
@@ -17468,11 +17553,7 @@ function checkAntiCreep(rules = RULES) {
 		for (const r of overflow.slice(0, 5)) details.push(`  overflow: ${r.id} — ${r.title}`);
 		if (overflow.length > 5) details.push(`  … and ${overflow.length - 5} more`);
 	} else details.push(`Core tier: ${count}/65 rules (${65 - count} slots available)`);
-	return {
-		name: "anti-creep",
-		ok,
-		details
-	};
+	return check("anti-creep", ok ? "pass" : "fail", details);
 }
 /**
 * Check 7 (audit H-1): quarantine enforcement. The tier policy must cap
@@ -17492,11 +17573,7 @@ function checkQuarantineEnforcement(rules = RULES) {
 		}
 	}
 	details.unshift(`${quarantine.length} quarantine rules capped to severity=info, evidence=E0 — no quarantine rule may emit error`);
-	return {
-		name: "quarantine-enforcement",
-		ok,
-		details
-	};
+	return check("quarantine-enforcement", ok ? "pass" : "fail", details);
 }
 /**
 * Check 8 (certification-audit Phase 2.5, plan G3 Layer A support):
@@ -17549,11 +17626,7 @@ function checkFixtureIntegrity(fixturesRoot, rules = RULES) {
 		details.push("typecheck-allowlist.json is unreadable/malformed");
 	}
 	details.unshift(`fixture trees: ${fixtureDirs} rule dirs, ${fixtureFiles} fixture files — orphaned dirs and empty dirs are blocking`);
-	return {
-		name: "fixture-integrity",
-		ok,
-		details
-	};
+	return check("fixture-integrity", ok ? "pass" : "fail", details);
 }
 /**
 * Check 9 (certification-audit Phase 3.3, G4/D8v2 — HARD-BLOCKING):
@@ -17578,35 +17651,19 @@ function checkRevisionIntegrity(repoRoot, rules = RULES) {
 	const details = [];
 	const manifestPath = join(repoRoot, "tests", "corpus", "detector-hashes.json");
 	const rulesDir = join(repoRoot, "src", "rules");
-	if (!existsSync(manifestPath)) return {
-		name: "revision-integrity",
-		ok: false,
-		details: ["INCONCLUSIVE: tests/corpus/detector-hashes.json is missing — run `npm run detector-hashes:update` (certification-critical: an unevaluable check never renders as pass)"]
-	};
-	if (!existsSync(rulesDir)) return {
-		name: "revision-integrity",
-		ok: false,
-		details: ["INCONCLUSIVE: src/rules is not present (installed package) — detector source identity cannot be verified here"]
-	};
+	if (!existsSync(manifestPath)) return check("revision-integrity", "inconclusive", ["INCONCLUSIVE: tests/corpus/detector-hashes.json is missing — run `npm run detector-hashes:update` (certification-critical: an unevaluable check never renders as pass)"]);
+	if (!existsSync(rulesDir)) return check("revision-integrity", "inconclusive", ["INCONCLUSIVE: src/rules is not present (installed package) — detector source identity cannot be verified here"]);
 	let manifest;
 	try {
 		manifest = loadManifest(manifestPath);
 	} catch {
-		return {
-			name: "revision-integrity",
-			ok: false,
-			details: ["INCONCLUSIVE: tests/corpus/detector-hashes.json is unreadable/malformed — regenerate with `npm run detector-hashes:update`"]
-		};
+		return check("revision-integrity", "inconclusive", ["INCONCLUSIVE: tests/corpus/detector-hashes.json is unreadable/malformed — regenerate with `npm run detector-hashes:update`"]);
 	}
 	let current;
 	try {
 		current = computeDetectorHashes(rules, rulesDir);
 	} catch (e) {
-		return {
-			name: "revision-integrity",
-			ok: false,
-			details: [`INCONCLUSIVE: detector hash computation failed — ${errorText(e)}`]
-		};
+		return check("revision-integrity", "inconclusive", [`INCONCLUSIVE: detector hash computation failed — ${errorText(e)}`]);
 	}
 	const failures = [];
 	for (const rule of rules) {
@@ -17621,21 +17678,95 @@ function checkRevisionIntegrity(repoRoot, rules = RULES) {
 	for (const id of Object.keys(manifest)) if (!rules.some((r) => r.id === id)) failures.push(`${id}: attested in the manifest but not in the registry`);
 	if (failures.length > 0) {
 		details.push(...failures);
-		return {
-			name: "revision-integrity",
-			ok: false,
-			details
-		};
+		return check("revision-integrity", "fail", details);
 	}
 	details.push(`${rules.length} rules attested: source identity and declared revision match the manifest (check A + check B, G4)`);
-	return {
-		name: "revision-integrity",
-		ok: true,
-		details
-	};
+	return check("revision-integrity", "pass", details);
+}
+/**
+* Check 8 (certification-audit Phase 1.4, D6 — HARD-BLOCKING):
+* category-integrity. Every registry rule's category must be a member of
+* the closed RULE_CATEGORIES set (compile-time exhaustive via the D6
+* derivation, so this check is the runtime backstop for values arriving
+* from external rule sources), and no two rules may collide on an id.
+* Registry ids are already unique-checked by registry-sanity; this check
+* owns the category dimension.
+*/
+function checkCategoryIntegrity(rules = RULES) {
+	const details = [];
+	const known = RULE_CATEGORIES;
+	const unknown = rules.filter((r) => !known.includes(r.category));
+	for (const r of unknown) details.push(`${r.id}: category "${r.category}" is not in RULE_CATEGORIES — registries may not invent categories (D6)`);
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const r of rules) byCategory.set(r.category, (byCategory.get(r.category) ?? 0) + 1);
+	return check("category-integrity", unknown.length === 0 ? "pass" : "fail", [`${byCategory.size} categories in use across ${rules.length} rules (closed set: ${RULE_CATEGORIES.length})`, ...details]);
+}
+/**
+* Check 10 (certification-audit Phase 4.1, D7 — HARD-BLOCKING):
+* measurement-consistency. Three invariants over the measurement surface:
+*   (1) every MEASURED_FP entry's `n` equals the LIVE classified verdict
+*       count (TP+FP rows in tests/corpus/verdicts/*.jsonl) — a snapshot
+*       that drifted from the corpus is a lie about evidence;
+*   (2) MEASURED_FP's detectorRevision equals the sidecar's
+*       (tests/corpus/detector-revisions.json) — a measurement taken
+*       against a different detector revision than attested is stale;
+*   (3) every sidecar entry maps to a registered rule.
+* Mismatch → FAIL (certification-critical).
+*/
+function checkMeasurementConsistency(verdictsDir, sidecarPath, rules = RULES, measuredFp = MEASURED_FP) {
+	const details = [];
+	const failures = [];
+	const registered = new Map(rules.map((r) => [r.id, r]));
+	const liveCounts = /* @__PURE__ */ new Map();
+	if (existsSync(verdictsDir)) for (const f of readdirSync(verdictsDir)) {
+		if (!f.endsWith(".jsonl")) continue;
+		const lines = readFileSync(join(verdictsDir, f), "utf8").split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed.length === 0) continue;
+			let row;
+			try {
+				row = JSON.parse(trimmed);
+			} catch {
+				failures.push(`${f}: unparseable verdict row (corpus integrity)`);
+				continue;
+			}
+			if (row.ruleId === void 0) continue;
+			if (row.verdict === "TP" || row.verdict === "FP") liveCounts.set(row.ruleId, (liveCounts.get(row.ruleId) ?? 0) + 1);
+		}
+	}
+	else return check("measurement-consistency", "inconclusive", ["INCONCLUSIVE: verdicts directory missing — measurement consistency cannot be evaluated (certification-critical: never renders as pass)"]);
+	let sidecar = {};
+	if (existsSync(sidecarPath)) try {
+		sidecar = JSON.parse(readFileSync(sidecarPath, "utf8"));
+	} catch (e) {
+		failures.push(`sidecar unreadable/malformed: ${errorText(e)} — regenerate the measurement artifacts`);
+	}
+	else {
+		const needsSidecar = Object.keys(measuredFp).filter((id) => measuredFp[id]?.detectorRevision !== 1);
+		if (needsSidecar.length > 0) return check("measurement-consistency", "inconclusive", [`INCONCLUSIVE: sidecar tests/corpus/detector-revisions.json missing but ${needsSidecar.length} measured rule(s) declare revisions — cannot verify measurement freshness`]);
+	}
+	for (const [id, m] of Object.entries(measuredFp)) {
+		const side = sidecar[id];
+		if (side !== void 0 && side.detectorRevision !== void 0) {
+			if (side.detectorRevision !== m.detectorRevision) failures.push(`${id}: MEASURED_FP revision ${m.detectorRevision} ≠ sidecar ${side.detectorRevision} — the measurement is stale (§07: re-measure or bump)`);
+		}
+		const live = liveCounts.get(id);
+		if (live !== void 0 && live !== m.n) failures.push(`${id}: MEASURED_FP.n=${m.n} but the live corpus has ${live} classified verdict(s) — regenerate (npm run fp-audit:generate)`);
+		if (live === void 0 && m.n > 0) failures.push(`${id}: MEASURED_FP.n=${m.n} but no classified verdicts exist in the live corpus`);
+	}
+	for (const id of Object.keys(sidecar)) if (!registered.has(id)) failures.push(`${id}: sidecar entry for an unregistered rule — remove it from tests/corpus/detector-revisions.json`);
+	if (failures.length > 0) {
+		details.push(...failures);
+		return check("measurement-consistency", "fail", details);
+	}
+	const block = measurementBlock(rules);
+	details.push(`${block.measured} measured / ${block.unmeasured} unmeasured / ${block.total} total (${block.quarantine} quarantine) — MEASURED_FP, live verdicts and sidecar revisions agree`);
+	return check("measurement-consistency", "pass", details);
 }
 function runDoctorSelfAudit(fixturesRoot) {
 	const verdictsDir = join(fixturesRoot, "..", "corpus", "verdicts");
+	const repoRoot = join(fixturesRoot, "..", "..");
 	const checks = [
 		checkFixtureFirewall(fixturesRoot),
 		checkRegistry(),
@@ -17644,12 +17775,15 @@ function runDoctorSelfAudit(fixturesRoot) {
 		checkTierEnforcement(verdictsDir),
 		checkAntiCreep(),
 		checkQuarantineEnforcement(),
+		checkCategoryIntegrity(),
 		checkFixtureIntegrity(fixturesRoot),
-		checkRevisionIntegrity(join(fixturesRoot, "..", ".."))
+		checkRevisionIntegrity(repoRoot),
+		checkMeasurementConsistency(verdictsDir, join(repoRoot, "tests", "corpus", "detector-revisions.json"))
 	];
 	return {
 		checks,
-		healthy: checks.every((c) => c.ok)
+		healthy: checks.every((c) => c.status === "pass"),
+		measurement: measurementBlock()
 	};
 }
 function renderDoctorReport(report) {
@@ -17659,7 +17793,7 @@ function renderDoctorReport(report) {
 		""
 	];
 	for (const c of report.checks) {
-		const mark = c.ok ? "✓" : "✗";
+		const mark = c.status === "pass" ? "✓" : c.status === "fail" ? "✗" : "? INCONCLUSIVE";
 		lines.push(`${mark} ${c.name}`);
 		for (const d of c.details.slice(0, 20)) lines.push(`    ${d}`);
 		if (c.details.length > 20) lines.push(`    … and ${c.details.length - 20} more`);
@@ -17668,6 +17802,89 @@ function renderDoctorReport(report) {
 	lines.push(report.healthy ? "Mjölnir self-audit: WORTHY" : "Mjölnir self-audit: VIOLATIONS FOUND");
 	return lines.join("\n");
 }
+/** Versioned JSON schema name for `doctor --json` (G5). */
+const DOCTOR_REPORT_SCHEMA = "mjolnir.doctor-report@1";
+/**
+* Serializes the doctor report to the machine-readable contract (Phase 5,
+* G5): versioned `schema` field, stable key order (constructed once, here),
+* details limited exactly like the text render, paths already POSIX-relative
+* (the checks build them that way), and byte-identical across two runs on
+* the same tree — the CI certification job re-runs the command twice and
+* diffs, so any nondeterminism fails there.
+*/
+function doctorReportJson(report, opts = {}) {
+	const maxDetails = opts.maxDetails ?? 20;
+	const summary = {
+		pass: 0,
+		fail: 0,
+		inconclusive: 0
+	};
+	const checks = report.checks.map((c) => {
+		summary[c.status]++;
+		return {
+			name: c.name,
+			status: c.status,
+			ok: c.ok,
+			details: c.details.length > maxDetails ? [...c.details.slice(0, maxDetails), `… and ${c.details.length - maxDetails} more`] : c.details
+		};
+	});
+	return {
+		schema: DOCTOR_REPORT_SCHEMA,
+		healthy: report.healthy,
+		summary,
+		checks,
+		measurement: report.measurement
+	};
+}
+//#endregion
+//#region src/commands/doctor-run.ts
+/**
+* Doctor CLI entry (certification-audit Phase 5, G6): the command handler
+* lives beside the check implementations instead of in cli.ts — the CLI
+* file is a dispatch table, not a business-logic home.
+*
+* Exit-code contract (stable, e2e-locked):
+*   0  — WORTHY (every check pass)
+*   1  — VIOLATIONS FOUND (any fail OR inconclusive — G2: an
+*        INCONCLUSIVE check never renders as pass, in text or JSON, and
+*        never exits 0)
+*   2  — no fixtures directory at the target (not an mjolnir checkout)
+*   10 — usage error (unknown flag / flag-shaped positional)
+*   20 — internal error (crash; --debug prints the stack)
+*
+* `--json`: prints the versioned machine contract (doctorReportJson)
+* instead of the text render. stdout carries EXACTLY the JSON document —
+* no banners, no progress lines — so `doctor . --json > report.json` is
+* a clean file. The exit code is the gate; the JSON is the evidence.
+*/
+function runDoctorCommand(argv, io = {
+	out,
+	err
+}) {
+	const json = argv.includes("--json");
+	if (argv.filter((a) => a.startsWith("-") && a !== "--json").length > 0) {
+		io.err("Usage: mjolnir doctor [--json] [repo-root]");
+		return 10;
+	}
+	const targetArg = argv.find((a) => !a.startsWith("-")) ?? process.cwd();
+	try {
+		const fixturesRoot = resolve(join(targetArg, "tests", "fixtures"));
+		if (!existsSync(fixturesRoot)) {
+			io.err(`No fixtures directory at ${fixturesRoot}. Run from the mjolnir repo root.`);
+			return 2;
+		}
+		const report = runDoctorSelfAudit(fixturesRoot);
+		if (json) {
+			io.out(JSON.stringify(doctorReportJson(report), null, 2));
+			return report.healthy ? 0 : 1;
+		}
+		io.out(renderDoctorReport(report));
+		return report.healthy ? 0 : 1;
+	} catch (err) {
+		internalErrorMessage(err, io.err, process.argv.includes("--debug"));
+		return 20;
+	}
+}
 //#endregion
 //#region src/commands/rules-catalog.ts
 /**
@@ -18038,7 +18255,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.19";
+const CLI_VERSION = "0.5.23";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -18203,8 +18420,6 @@ function parseArgsOrUsage(argv, io) {
 	if (!args && !reported) printUsage(io.out);
 	return args;
 }
-const out = (...parts) => console.log(parts.map(String).join(" "));
-const err = (...parts) => console.error(parts.map(String).join(" "));
 /** Testable `ci install` handler. Returns the process exit code. */
 function runCiInstall(argv, io = {
 	out,
@@ -18326,30 +18541,6 @@ async function runDoctorPlaywright(argv, io = { out }) {
 		return 20;
 	}
 }
-/** Testable `doctor` handler — self-audit of Mjölnir's own rule base. */
-function runDoctorCommand(argv, io = {
-	out,
-	err
-}) {
-	if (argv.some((a) => a.startsWith("-"))) {
-		io.err("Usage: mjolnir doctor [repo-root]");
-		return 10;
-	}
-	const targetArg = argv[0] ?? process$1.cwd();
-	try {
-		const fixturesRoot = resolve(join(targetArg, "tests", "fixtures"));
-		if (!existsSync(fixturesRoot)) {
-			io.err(`No fixtures directory at ${fixturesRoot}. Run from the mjolnir repo root.`);
-			return 2;
-		}
-		const report = runDoctorSelfAudit(fixturesRoot);
-		io.out(renderDoctorReport(report));
-		return report.healthy ? 0 : 1;
-	} catch (err) {
-		internalErrorMessage(err, io.err, process$1.argv.includes("--debug"));
-		return 20;
-	}
-}
 /** Testable `rules` handler — rule catalog with Trust Metadata. */
 async function runRulesCommand(argv, io = {
 	out,
@@ -18985,22 +19176,6 @@ function runHelpCommand(argv, io = {
 function printUsage(print) {
 	print(renderRootHelp());
 }
-/**
-* Friendly exit-20 path (plan M2): the crash says it's Mjölnir's bug,
-* not the user's repo, carries the underlying message for a report, and
-* prints the stack ONLY when `debug` is set (uniform across
-* subcommands — they don't parse scan flags). Tests pin
-* /internal error/i. Exported so the --debug stack arm is directly
-* spec-coverable (spawning a real crash under --debug would be flaky).
-*/
-function internalErrorMessage(err, emit, debug) {
-	const message = err instanceof Error ? err.message : String(err);
-	emit("mjolnir internal error — this is a bug in Mjölnir, not your repo:");
-	emit(`  ${message}`);
-	if (debug && err instanceof Error && err.stack) emit(err.stack);
-	emit("Rerun with --debug for the stack trace. Please report this:");
-	emit("  https://github.com/Sergey-Bar/Mjolnir/issues");
-}
 function isEntryPoint() {
 	const argv1 = process$1.argv[1];
 	if (!argv1) return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mjolnir-qa",
-  "version": "0.5.19",
+  "version": "0.5.23",
   "description": "Mjölnir — the Verification Trust Engine for QA. Audits test suites and CI pipelines, reports a worthiness score and prioritized findings.",
   "type": "module",
   "engines": {