mjolnir-qa 0.5.18 → 0.5.20

package/dist/cli.mjs

@@ -13264,7 +13264,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.18",
+			version: "0.5.20",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -13707,7 +13707,7 @@ function renderPrComment(result, options = {}) {
 * from here.
 */
 /** Human message for any thrown value — never "undefined"/"[object Object]". */
-function errorText(err) {
+function errorText$1(err) {
 	if (err instanceof Error) return err.message;
 	if (typeof err === "string") return err;
 	if (typeof err === "object" && err !== null) return JSON.stringify(err);
@@ -13723,7 +13723,7 @@ function validateReportJson(text) {
 	try {
 		parsed = JSON.parse(text);
 	} catch (err) {
-		throw new Error(`not valid JSON (${errorText(err)})`, { cause: err });
+		throw new Error(`not valid JSON (${errorText$1(err)})`, { cause: err });
 	}
 	if (typeof parsed !== "object" || parsed === null) throw new Error("the file is a JSON value but not an object");
 	const doc = parsed;
@@ -13900,7 +13900,7 @@ function runSummaryCommand(argv, io = {
 	try {
 		result = loadSavedReport(reportPath);
 	} catch (err) {
-		io.err(`mjolnir summary: cannot read ${reportPath}: ${errorText(err)}`);
+		io.err(`mjolnir summary: cannot read ${reportPath}: ${errorText$1(err)}`);
 		return 2;
 	}
 	const env = process.env;
@@ -13919,7 +13919,7 @@ function runSummaryCommand(argv, io = {
 	if (stepSummaryPath) try {
 		appendFileSync(stepSummaryPath, `${summary}\n`);
 	} catch (err) {
-		io.err(`mjolnir summary: could not write $GITHUB_STEP_SUMMARY (${errorText(err)}); printing to stdout instead.`);
+		io.err(`mjolnir summary: could not write $GITHUB_STEP_SUMMARY (${errorText$1(err)}); printing to stdout instead.`);
 		io.out(summary);
 	}
 	else io.out(summary);
@@ -14050,7 +14050,7 @@ async function runWhyCommand(argv, io = {
 		try {
 			result = loadSavedReport(reportPath);
 		} catch (err) {
-			io.err(`mjolnir why: cannot read ${reportPath}: ${errorText(err)}`);
+			io.err(`mjolnir why: cannot read ${reportPath}: ${errorText$1(err)}`);
 			return 2;
 		}
 	} else {
@@ -14069,7 +14069,7 @@ async function runWhyCommand(argv, io = {
 				strict: argv.includes("--strict")
 			});
 		} catch (err) {
-			io.err(`mjolnir why: scan failed: ${errorText(err)}`);
+			io.err(`mjolnir why: scan failed: ${errorText$1(err)}`);
 			return 20;
 		}
 	}
@@ -14351,7 +14351,7 @@ function runHandoffCommand(argv, io = {
 	try {
 		result = loadSavedReport(reportPath);
 	} catch (err) {
-		io.err(`mjolnir handoff: cannot read ${reportPath}: ${errorText(err)}`);
+		io.err(`mjolnir handoff: cannot read ${reportPath}: ${errorText$1(err)}`);
 		return 2;
 	}
 	io.out(renderHandoff(result, {
@@ -17630,6 +17630,204 @@ 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/engine/detector-hash.ts
+/**
+* Detector revision integrity engine (certification-audit Phase 3,
+* G4/D8v2/D17).
+*
+* The manifest records, per rule, a `logicHash` = source-identity hash
+* over the rule's DECLARED METADATA (the gating/participation surface)
+* plus the FULL TOKEN STREAM of its defining module (the detection
+* surface). It is deliberately NOT a behavior-equivalence hash (D17):
+* behavior-neutral edits that touch source tokens (renames, unrelated
+* imports) DO churn it — that errs in the safe direction. What it
+* mechanically guarantees: no source-token change can pass without
+* either a declared revision bump or an explicit, review-visible
+* manifest regeneration.
+*
+* Token-stream contract (G4): every non-trivia token of the module with
+* regex/string/template-literal token texts preserved EXACTLY (whitespace
+* inside a literal is semantic); comments and inter-token whitespace
+* excluded (a prettier reformat or comment edit cannot churn the hash).
+* Module-scope detection constants, control-flow edits, and metadata
+* edits all change the token stream → detected. `String(rule.run)` is
+* proven insufficient for exactly this (module-scope constants live in
+* ≥7 rule files).
+*
+* Implementation note: tokenization goes through ts-morph's bundled
+* TypeScript compiler (ts-morph is a runtime dependency — the doctor
+* computes current hashes at runtime; `typescript` itself is dev-only
+* and must not leak into the runtime surface).
+*/
+/** The record separator between the metadata JSON and the token stream. */
+const SECTION_SEP = "␞";
+/** The unit separator between consecutive tokens (length-agnostic, unambiguous). */
+const TOKEN_SEP = "␟";
+/**
+* A context-aware, trivia-free token walk over `moduleText`. Yields
+* {kind, text} for every non-trivia token with regex/template resolution
+* identical to the compiler:
+*   - A SlashToken is re-scanned as RegularExpressionLiteral exactly when
+*     the previous token cannot end an expression (the lexer's own
+*     context rule); a division operator stays SlashToken.
+*   - A CloseBraceToken inside a template continuation is re-scanned via
+*     reScanTemplateToken (TemplateHead opens; TemplateMiddle/Tail close
+*     a level). A brace outside a template is plain punctuation —
+*     re-scanning it would swallow the rest of the file (proven).
+* Regex/string/template bodies keep their exact internal text; comments
+* and whitespace are trivia and never yielded.
+*/
+function* walkTokens(moduleText) {
+	const scanner = ts.createScanner(ts.ScriptTarget.ES2022, true, ts.LanguageVariant.Standard, moduleText);
+	let templateDepth = 0;
+	let prevKind;
+	const endsExpression = (kind) => {
+		if (kind === void 0) return false;
+		return kind === ts.SyntaxKind.Identifier || kind === ts.SyntaxKind.StringLiteral || kind === ts.SyntaxKind.NumericLiteral || kind === ts.SyntaxKind.RegularExpressionLiteral || kind === ts.SyntaxKind.NoSubstitutionTemplateLiteral || kind === ts.SyntaxKind.LastTemplateToken || kind === ts.SyntaxKind.CloseParenToken || kind === ts.SyntaxKind.CloseBracketToken || kind === ts.SyntaxKind.CloseBraceToken || kind === ts.SyntaxKind.PlusPlusToken || kind === ts.SyntaxKind.MinusMinusToken || kind === ts.SyntaxKind.ThisKeyword || kind === ts.SyntaxKind.SuperKeyword || kind === ts.SyntaxKind.TrueKeyword || kind === ts.SyntaxKind.FalseKeyword || kind === ts.SyntaxKind.NullKeyword;
+	};
+	let tok = scanner.scan();
+	while (tok !== ts.SyntaxKind.EndOfFileToken) {
+		if (tok === ts.SyntaxKind.SlashToken && !endsExpression(prevKind)) tok = scanner.reScanSlashToken();
+		else if (tok === ts.SyntaxKind.CloseBraceToken && templateDepth > 0) tok = scanner.reScanTemplateToken(false);
+		const text = scanner.getTokenText();
+		yield {
+			kind: tok,
+			text
+		};
+		if (tok === ts.SyntaxKind.TemplateHead) templateDepth++;
+		else if (tok === ts.SyntaxKind.LastTemplateToken) templateDepth = Math.max(0, templateDepth - 1);
+		prevKind = tok;
+		tok = scanner.scan();
+	}
+}
+/**
+* The deterministic token stream consumed by the logic hash: token texts
+* joined with the unit separator.
+*/
+function moduleTokenStream(moduleText) {
+	const parts = [];
+	for (const { text } of walkTokens(moduleText)) parts.push(text);
+	return parts.join(TOKEN_SEP);
+}
+/** The canonical logic hash for one rule: metadata JSON ‖ module token stream. */
+function computeRuleLogicHash(metadata, moduleText) {
+	return createHash("sha256").update(JSON.stringify(metadata)).update(SECTION_SEP).update(moduleTokenStream(moduleText)).digest("hex");
+}
+/**
+* The metadata surface a hash covers, extracted from a live rule object.
+* Field order must stay in sync with RuleHashMetadata (the object literal
+* order defines the JSON serialization).
+*/
+function metadataForRule(rule) {
+	return {
+		appliesTo: rule.appliesTo,
+		configRule: rule.configRule,
+		configFiles: rule.configFiles,
+		frameworks: rule.frameworks,
+		tier: rule.tier,
+		severity: rule.severity,
+		confidence: rule.confidence,
+		findingType: rule.findingType,
+		evidenceLevel: rule.evidenceLevel,
+		overlapWith: rule.overlapWith
+	};
+}
+function declaredRevision(rule) {
+	return rule.detectorRevision ?? 1;
+}
+/**
+* Walks the rule source tree and maps every rule to its defining module —
+* STATICALLY. A module claims a rule when its tokens contain the property
+* sequence `id` `:` `<QA-rule-id string literal>` (defineRule options and
+* family variants both have exactly this shape). No dynamic import: the
+* doctor computes current hashes at runtime (also from dist, where .ts
+* imports are neither available nor needed — only file text is hashed),
+* so a runtime import of rule sources would break the installed case and
+* tie the integrity check to the module loader.
+*
+* Each rule id must be claimed exactly once — a double claim means the
+* module layout drifted and the manifest would be ambiguous.
+*/
+function collectRuleModules(rulesDir) {
+	const claimed = /* @__PURE__ */ new Map();
+	const files = listRuleModules(rulesDir).sort();
+	const RULE_ID_LIT = /^QA-[A-Z]{1,6}-\d{3}$/;
+	for (const file of files) {
+		const moduleText = readFileSync(file, "utf8");
+		let pendingIdKey = false;
+		let prevTok;
+		for (const { kind: tok, text: raw } of walkTokens(moduleText)) {
+			const isStringLit = tok === ts.SyntaxKind.StringLiteral;
+			const literalValue = isStringLit && raw.length >= 2 ? raw.slice(1, -1) : raw;
+			if (isStringLit && RULE_ID_LIT.exec(literalValue) !== null && (prevTok === ts.SyntaxKind.ColonToken && pendingIdKey || prevTok === ts.SyntaxKind.OpenParenToken)) {
+				const prev = claimed.get(literalValue);
+				if (prev && prev !== file) throw new Error(`rule ${literalValue} is claimed by both ${prev} and ${file} — the manifest needs exactly one defining module per rule`);
+				claimed.set(literalValue, file);
+				pendingIdKey = false;
+			} else if (tok === ts.SyntaxKind.Identifier && raw === "id") pendingIdKey = true;
+			else if (tok !== ts.SyntaxKind.ColonToken) pendingIdKey = false;
+			prevTok = tok;
+		}
+	}
+	return [...claimed.entries()].map(([ruleId, modulePath]) => ({
+		ruleId,
+		modulePath
+	}));
+}
+function listRuleModules(rulesDir) {
+	const out = [];
+	const visit = (dir) => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) visit(full);
+			else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".d.ts")) {
+				if (entry.name === "index.ts" || entry.name.endsWith(".generated.ts")) continue;
+				out.push(full);
+			}
+		}
+	};
+	visit(rulesDir);
+	return out;
+}
+/**
+* Computes the full manifest from the live source tree. `rules` supplies
+* the registry (for detectorRevision + metadata of every registered rule);
+* `rulesDir` supplies the defining modules. Rules present in one but not
+* the other fail loudly — the manifest must cover exactly the registry.
+*/
+function computeDetectorHashes(rules, rulesDir) {
+	const modules = collectRuleModules(rulesDir);
+	const byId = new Map(modules.map((m) => [m.ruleId, m]));
+	const registryIds = new Set(rules.map((r) => r.id));
+	const manifest = {};
+	for (const rule of rules) {
+		const module = byId.get(rule.id);
+		if (!module) throw new Error(`rule ${rule.id} is registered but has no defining module under ${rulesDir}`);
+		const moduleText = readFileSync(module.modulePath, "utf8");
+		manifest[rule.id] = {
+			logicHash: computeRuleLogicHash(metadataForRule(rule), moduleText),
+			detectorRevision: declaredRevision(rule)
+		};
+	}
+	for (const id of byId.keys()) if (!registryIds.has(id)) throw new Error(`rule ${id} defines a module under ${rulesDir} but is not in the registry — the manifest must cover exactly the registry`);
+	return manifest;
+}
+function loadManifest(path) {
+	return JSON.parse(readFileSync(path, "utf8"));
+}
+//#endregion
 //#region src/commands/doctor.ts
 /**
 * `mjolnir doctor` — self-audit of Mjolnir's own rule base.
@@ -17646,7 +17844,20 @@ function renderFixReport(results, dryRun) {
 *
 * Exit codes reuse the frozen set: 0 healthy · 1 violations · 20 crash.
 */
+/** Uniform error rendering for doctor details (Error or thrown-as-string). */
+function errorText(e) {
+	return e instanceof Error ? e.message : String(e);
+}
 const ui$1 = 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 [];
@@ -17669,11 +17880,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) {
@@ -17696,20 +17903,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
@@ -17728,11 +17927,7 @@ function checkEvidenceHonesty(rules = RULES) {
 			details.push(`${r.id}: declares ${r.evidenceLevel} but findingType=${r.findingType}/confidence=${r.confidence} supports at most ${derived}`);
 		}
 	}
-	return {
-		name: "evidence-honesty",
-		ok,
-		details
-	};
+	return check("evidence-honesty", ok ? "pass" : "fail", details);
 }
 /**
 * Check 5 (Phase 4 — Tempering Plan, ratcheted per audit H-2):
@@ -17773,11 +17968,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.
@@ -17796,11 +17987,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
@@ -17820,11 +18007,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):
@@ -17877,11 +18060,62 @@ 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):
+* revision-integrity. The manifest tests/corpus/detector-hashes.json
+* attests each rule's source identity (logicHash = sha256 of the rule's
+* metadata ‖ its defining module's token stream) against the declared
+* detectorRevision:
+*   check A — current logicHash ≠ manifest logicHash → FAIL ("bump +
+*             re-measure + regen, or regen with stated behavior-neutrality");
+*   check B — declared revision ≠ manifest revision → FAIL (stale manifest);
+*   manifest missing/unreadable, or the source tree unavailable (the
+*             installed-package case) → the check CANNOT be evaluated
+*             honestly → reported as INCONCLUSIVE and ok=false — a
+*             certification-critical INCONCLUSIVE never renders as pass
+*             (G2); Phase 5's status migration carries the same rule.
+*
+* Where the check runs: the doctor self-audits THIS repo, so `repoRoot`
+* must be the Mjölnir checkout (src/ present). On an installed package
+* the src tree does not exist → honest INCONCLUSIVE, same as above.
+*/
+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 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 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 check("revision-integrity", "inconclusive", [`INCONCLUSIVE: detector hash computation failed — ${errorText(e)}`]);
+	}
+	const failures = [];
+	for (const rule of rules) {
+		const attested = manifest[rule.id];
+		if (!attested) {
+			failures.push(`${rule.id}: not attested in the manifest (stale manifest — regenerate)`);
+			continue;
+		}
+		if (attested.logicHash !== current[rule.id]?.logicHash) failures.push(`${rule.id}: source identity changed since manifest attestation — bump detectorRevision + re-measure + regen, or regen with stated behavior-neutrality (G4)`);
+		if (attested.detectorRevision !== declaredDetectorRevision(rule)) failures.push(`${rule.id}: manifest revision ${attested.detectorRevision} ≠ declared ${declaredDetectorRevision(rule)} (stale manifest — regenerate)`);
+	}
+	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 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 check("revision-integrity", "pass", details);
 }
 function runDoctorSelfAudit(fixturesRoot) {
 	const verdictsDir = join(fixturesRoot, "..", "corpus", "verdicts");
@@ -17893,11 +18127,12 @@ function runDoctorSelfAudit(fixturesRoot) {
 		checkTierEnforcement(verdictsDir),
 		checkAntiCreep(),
 		checkQuarantineEnforcement(),
-		checkFixtureIntegrity(fixturesRoot)
+		checkFixtureIntegrity(fixturesRoot),
+		checkRevisionIntegrity(join(fixturesRoot, "..", ".."))
 	];
 	return {
 		checks,
-		healthy: checks.every((c) => c.ok)
+		healthy: checks.every((c) => c.status === "pass")
 	};
 }
 function renderDoctorReport(report) {
@@ -17907,7 +18142,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`);
@@ -17916,6 +18151,88 @@ 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
+	};
+}
+//#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
 /**
@@ -18132,7 +18449,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.18";
+const CLI_VERSION = "0.5.20";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -18297,8 +18614,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,
@@ -18420,30 +18735,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,
@@ -19079,22 +19370,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;