mjolnir-qa 0.5.12 → 0.5.14

package/dist/cli.mjs

@@ -10,6 +10,7 @@ import { Project, SyntaxKind, ts } from "ts-morph";
 import { Language, Parser } from "web-tree-sitter";
 import { parse } from "yaml";
 import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
 import { tmpdir } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
@@ -11597,7 +11598,7 @@ const ALLOWED_QA_IMPACTS = /* @__PURE__ */ new Set([
 	"HYGIENE"
 ]);
 /** Consistent error message extraction (v8 branch-friendly form). */
-function errorMessage(err) {
+function errorMessage$1(err) {
 	if (err instanceof Error) return err.message;
 	return String(err);
 }
@@ -11618,7 +11619,7 @@ async function loadLocalRules(root, gateOpen = false) {
 	try {
 		entries = readdirSync(dir);
 	} catch (err) {
-		result.errors.push(`external rules directory "${LOCAL_RULES_DIR}/" could not be read: ${errorMessage(err)}`);
+		result.errors.push(`external rules directory "${LOCAL_RULES_DIR}/" could not be read: ${errorMessage$1(err)}`);
 		return result;
 	}
 	for (const entry of entries.sort()) {
@@ -11640,7 +11641,7 @@ function loadJsonRule(path, result) {
 	try {
 		raw = JSON.parse(readFileSync(path, "utf8"));
 	} catch (err) {
-		result.errors.push(`external rule "${name}" is not valid JSON: ${errorMessage(err)}`);
+		result.errors.push(`external rule "${name}" is not valid JSON: ${errorMessage$1(err)}`);
 		return;
 	}
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
@@ -11676,7 +11677,7 @@ function loadJsonRule(path, result) {
 	try {
 		regexes = patterns.map((p) => new RegExp(p, "g"));
 	} catch (err) {
-		result.errors.push(`external rule ${id} declares an invalid regex: ${errorMessage(err)}`);
+		result.errors.push(`external rule ${id} declares an invalid regex: ${errorMessage$1(err)}`);
 		return;
 	}
 	const severity = decl["severity"];
@@ -11771,7 +11772,7 @@ async function loadModuleRules(path, result) {
 	try {
 		mod = await import(pathToFileURL(path).href);
 	} catch (err) {
-		result.errors.push(`external rule module "${name}" failed to load: ${errorMessage(err)}`);
+		result.errors.push(`external rule module "${name}" failed to load: ${errorMessage$1(err)}`);
 		return;
 	}
 	const rules = mod?.rules;
@@ -12480,26 +12481,26 @@ function topFixes(findings, n = 3) {
 }
 //#endregion
 //#region src/reporter/art.ts
-/** Block-character logo. Keep ≤ 62 cols wide. */
+/**
+* The report's wordmark. A LOCKUP, not a picture of a hammer.
+*
+* This used to be eight rows of box-drawing that spelled out a hammer —
+* directly above the score instrument, which is also a hammer. Two
+* hammers, ten lines apart, and the smaller static one came first, so
+* appendScoreSection's own claim that "the hammer is the instrument: the
+* first thing the eye lands on" was false in every report the tool has
+* ever printed.
+*
+* There is one hammer now, and it is the one that means something: the
+* state-resolved instrument in HAMMER_STATES. The wordmark stays out of
+* its way.
+*/
 const LOGO = `
- ╔═══════════╗
- ║           ║
- ╠═══════════╣    M J Ö L N I R
- ║     ║     ║
- ╚═════╩═════╝    VERIFICATION TRUST ENGINE
-       ║
-       ║
+  M J Ö L N I R  ·  VERIFICATION TRUST ENGINE
 `;
-/** Plain-ASCII fallback logo for cmd.exe/legacy consoles where the
-* block-drawing LOGO above renders as mangled "?" glyphs. */
+/** Plain-ASCII fallback for cmd.exe/legacy consoles. */
 const LOGO_ASCII = `
- +-----------+
- |           |
- +-----------+    M J O L N I R
- |     |     |
- +-----+-----+    VERIFICATION TRUST ENGINE
-       |
-       |
+  M J O L N I R  -  VERIFICATION TRUST ENGINE
 `;
 const TROPHY = String.raw`
         ___________
@@ -13000,7 +13001,12 @@ const CARD_GUTTER = "    ";
 function pushCard(lines, card, ui) {
 	const { p, width } = ui;
 	const contentWidth = Math.max(20, width - 2 - 4 - CARD_LABEL_PAD);
-	lines.push(`  ${severityIcon(card.severity, ui)} ${p.bold(card.loc)}  ${p.dim(card.evidence)}`);
+	const header = `  ${severityIcon(card.severity, ui)} ${p.bold(card.loc)}`;
+	if (measure(`${header}  ${card.evidence}`) <= width) lines.push(`${header}  ${p.dim(card.evidence)}`);
+	else {
+		lines.push(header);
+		lines.push(`${CARD_GUTTER}${p.dim(card.evidence)}`);
+	}
 	const fields = [
 		{
 			label: "Finding",
@@ -13040,7 +13046,7 @@ function pushCard(lines, card, ui) {
 * overflow line; --verbose shows everything.
 */
 function appendFindings(lines, result, counts, verbose, ui, tone) {
-	const { p } = ui;
+	const { p, width } = ui;
 	if (counts.total === 0) return;
 	if (result.findings.length === 0) {
 		lines.push(ui.p.dim("  filtered view: no findings in the selected category"));
@@ -13089,9 +13095,21 @@ function appendFindings(lines, result, counts, verbose, ui, tone) {
 				hiddenRules.add(unit.ruleId);
 				continue;
 			}
-			lines.push(`  ${severityIcon(maxSeverity(unit.findings), ui)} ${p.bold(sanitizeData(unit.ruleId))} ${p.dim(`× ${n} — same fix applies`)} ${p.dim(evidenceTag$1(first))}`);
-			lines.push(`${CARD_GUTTER}${p.accent("Fix".padEnd(CARD_LABEL_PAD))}${p.dim(sanitizeData(first.fix))}`);
-			for (const f of unit.findings) lines.push(`${CARD_GUTTER}${" ".repeat(CARD_LABEL_PAD)}${p.dim(`· ${sanitizeData(f.file)}:${f.line} — ${sanitizeData(f.message)}`)}`);
+			const groupHead = `  ${severityIcon(maxSeverity(unit.findings), ui)} ${p.bold(sanitizeData(unit.ruleId))} ${p.dim(`× ${n} — same fix applies`)}`;
+			const groupEvidence = evidenceTag$1(first);
+			if (measure(`${groupHead} ${groupEvidence}`) <= width) lines.push(`${groupHead} ${p.dim(groupEvidence)}`);
+			else {
+				lines.push(groupHead);
+				lines.push(`${CARD_GUTTER}${p.dim(groupEvidence)}`);
+			}
+			const groupContentWidth = Math.max(20, width - 2 - 4 - CARD_LABEL_PAD);
+			wrapLines(sanitizeData(first.fix), groupContentWidth).forEach((seg, i) => {
+				const label = i === 0 ? p.accent("Fix".padEnd(CARD_LABEL_PAD)) : " ".repeat(CARD_LABEL_PAD);
+				lines.push(`${CARD_GUTTER}${label}${p.dim(seg)}`);
+			});
+			for (const f of unit.findings) wrapLines(`· ${sanitizeData(f.file)}:${f.line} — ${sanitizeData(f.message)}`, groupContentWidth).forEach((seg, i) => {
+				lines.push(`${CARD_GUTTER}${" ".repeat(CARD_LABEL_PAD)}${p.dim(i === 0 ? seg : `  ${seg}`)}`);
+			});
 			lines.push("");
 			shown++;
 			continue;
@@ -13129,22 +13147,34 @@ function appendForgedBlock(lines, p, ascii) {
 	lines.push(p.forged(TROPHY));
 	lines.push("");
 }
+/**
+* Pushes dimmed prose that respects the terminal width.
+*
+* The honesty footer used to be pushed as single unbroken strings — the
+* rule-coverage line alone is ~147 columns, so it overflowed every
+* default 80- or 100-column terminal and ignored `--width` entirely.
+* `wrapText` is the same helper the finding cards already use.
+*/
+function pushWrapped(lines, p, text, width) {
+	const indent = "  ";
+	for (const line of wrapText(text, Math.max(20, width - 2))) lines.push(p.dim(`${indent}${line}`));
+}
 function appendFooter(lines, result, ui) {
-	const { p } = ui;
+	const { p, width } = ui;
 	lines.push(...buildFooter({
 		ui,
 		complete: result.analysisStatus.discovery !== "partial",
 		durationMs: result.analysisStatus.durationMs
 	}));
 	const advisory = result.findings.filter((f) => (f.evidenceLevel ?? deriveEvidenceLevel(f.findingType, f.confidence)) === "E0").length;
-	if (advisory > 0) lines.push(p.dim(`  ${advisory} advisory finding${advisory === 1 ? "" : "s"} (E0 — observation only, no score impact)`));
+	if (advisory > 0) pushWrapped(lines, p, `${advisory} advisory finding${advisory === 1 ? "" : "s"} (E0 — observation only, no score impact)`, width);
 	if (result.findings.length > 0) {
 		const firedRuleIds = new Set(result.findings.map((f) => f.ruleId));
 		const measuredHere = [...firedRuleIds].filter((id) => MEASURED_FP[id] !== void 0).length;
-		lines.push(p.dim(`  Rule coverage: ${measuredHere}/${firedRuleIds.size} rules that fired here have a measured false-positive rate; the rest are heuristics. \`mjolnir rules --unmeasured\` lists them.`));
+		pushWrapped(lines, p, `Rule coverage: ${measuredHere}/${firedRuleIds.size} rules that fired here have a measured false-positive rate; the rest are heuristics. \`mjolnir rules --unmeasured\` lists them.`, width);
 		const verified = result.findings.filter((f) => f.runtimeCorroboration !== void 0).length;
-		if (verified > 0) lines.push(p.dim(`  Runtime evidence: ${verified}/${result.findings.length} findings corroborated by a real run report (trust L3–L5); the rest are static-only.`));
-		else lines.push(p.dim(`  Runtime evidence: not available — no run report (mjolnir.report.json / test-results) next to the scan target; all findings are static-only (L0–L2).`));
+		if (verified > 0) pushWrapped(lines, p, `Runtime evidence: ${verified}/${result.findings.length} findings corroborated by a real run report (trust L3–L5); the rest are static-only.`, width);
+		else pushWrapped(lines, p, `Runtime evidence: not available — no run report (mjolnir.report.json / test-results) next to the scan target; all findings are static-only (L0–L2).`, width);
 	}
 	const profile = result.agenticProfile;
 	if (profile && (profile.generatedMarkedFiles > 0 || profile.codegenLikeFiles > 0)) {
@@ -13224,7 +13254,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.12",
+			version: "0.5.14",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14646,307 +14676,185 @@ function executeHookInstall(entry) {
 	}
 }
 //#endregion
-//#region src/integrations/ci-install.ts
+//#region src/rules/measurement.ts
+/** The rule's declared detector implementation revision (§07). */
+function declaredDetectorRevision(rule) {
+	return rule.detectorRevision ?? 1;
+}
 /**
-* CI integration (Sprint-Plan W7): generates .github/workflows/mjolnir.yml
-* from internal templates ONLY — no user-input interpolation (R3 supply-chain).
-* Default gate: advisory (report, never block).
-*
-* Bug-audit hardening (H2): the previous template shipped the same
-* `github.rest.checks` no-op this repo's own audit removed from mjolnir.yml,
-* failed the job before the annotate/summary steps could run whenever the
-* scan step exited non-zero, recommended floating `mjolnir-qa@latest`, and
-* `ciInstall` silently overwrote hand-customized workflows. The template now
-* mirrors the dogfooded `.github/workflows/mjolnir.yml` (pinned action SHAs,
-* `if: always()` on reporting steps, a real gate step that reads
-* `mjolnir.json`, partial scans never block) and `ciInstall` refuses to
-* replace a customized workflow without an explicit `--force`.
+* A measurement exists AND was taken against the detector revision the
+* rule declares now. A revision mismatch (stale) does NOT count — §07:
+* stale → provisional → re-measure.
 */
+function hasValidMeasurement(rule) {
+	const m = MEASURED_FP[rule.id];
+	return m !== void 0 && m.detectorRevision === declaredDetectorRevision(rule);
+}
 /**
-* The gate-check script embedded in generated workflows (and executed
-* directly by tests against fixture JSONs). Semantics, kept in sync with
-* the tool's own exit-code contract:
-*  - missing/unreadable `mjolnir.json` → fail (the scan step crashed; a
-*    silent pass here would turn a broken pipeline into a green one);
-*  - `partial: true` → never block (truncated results can neither prove
-*    nor disprove the gate — the "PARTIAL" banner in the summary is the
-*    honest signal);
-*  - `error` gate → block on any error-severity finding;
-*  - `warning` gate → block on warnings and errors.
+* The tier a rule effectively ships as: its declared tier, or — for the
+* omitted-tier case — the measurement-dependent default (§11.2 Step 2).
 */
-function gateScript(gate) {
-	return [
-		"const fs = require(\"fs\");",
-		"let r;",
-		"try {",
-		"  r = JSON.parse(fs.readFileSync(\"mjolnir.json\", \"utf8\"));",
-		"} catch (e) {",
-		"  process.stderr.write(\"mjolnir.json is missing or unreadable - the scan step crashed before the gate could run. Failing instead of passing silently.\\n\");",
-		"  process.exit(1);",
-		"}",
-		"if (r.partial === true) {",
-		"  process.stdout.write(\"Scan was PARTIAL - some files were not analyzed; gate not enforced.\\n\");",
-		"  process.exit(0);",
-		"}",
-		"const findings = Array.isArray(r.findings) ? r.findings : [];",
-		"const errors = findings.filter(function (f) { return f && f.severity === \"error\"; }).length;",
-		"const warnings = findings.filter(function (f) { return f && f.severity === \"warning\"; }).length;",
-		"process.stdout.write(\"Mjolnir gate: \" + errors + \" error(s), \" + warnings + \" warning(s).\\n\");",
-		`if (${gate === "error" ? "errors > 0" : "errors > 0 || warnings > 0"}) { process.exit(1); }`,
-		"process.exit(0);"
-	].join("\n");
+function effectiveTier(rule) {
+	if (rule.tier !== void 0) return rule.tier;
+	if (hasValidMeasurement(rule)) return "core";
+	return "extended";
+}
+/** The §11.2 Step 2 PROVISIONAL display predicate. */
+function isProvisional(rule) {
+	return effectiveTier(rule) === "extended" && !hasValidMeasurement(rule);
 }
+//#endregion
+//#region src/commands/fixture-example.ts
 /**
-* Template v2 (Terminal + CI UX Overhaul plan, M4): the summary step
-* calls `mjolnir summary mjolnir.json` — annotations + step summary via
-* ONE emitter — instead of the v1 inline SUMMARY_SCRIPT. The gate
-* script is unchanged (reads `partial`, `findings[].severity`).
+* Shared example-fixture selection for `mjolnir explain` (explain.ts)
+* and the generated rule docs (rule-docs.ts) — one chooser so both
+* surfaces always show the same example for the same rule. Extracted
+* after the same bug-audit L9 fix had to be applied to both verbatim
+* copies: duplicated fixture selection drifts, and a drift means
+* `mjolnir explain <ID>` contradicts docs/rules/<ID>.md.
 */
-/** Renders findings into `$GITHUB_STEP_SUMMARY`; tolerates a missing scan result.
-* v1 inline script, retained ONLY for overwrite-refusal recognition of
-* workflows generated by older versions (they are treated as ours, so
-* a frictionless `ci install` upgrade stays possible). Exported for the
-* recognition test that reconstructs the embedded form. */
-const SUMMARY_SCRIPT_V1 = [
-	"const fs = require(\"fs\");",
-	"let r = {};",
-	"try { r = JSON.parse(fs.readFileSync(\"mjolnir.json\", \"utf8\")); } catch (e) {}",
-	"const findings = Array.isArray(r.findings) ? r.findings : [];",
-	"const lines = findings.map(function (f) {",
-	"  return \"- **\" + f.ruleId + \"** (\" + f.severity + \") \" + f.file + \":\" + f.line + \" - \" + f.message;",
-	"});",
-	"const head = r.partial === true",
-	"  ? \"Mjolnir scan was PARTIAL - some files may not have been analyzed.\"",
-	"  : \"Mjolnir scan finished.\";",
-	"const body = [\"## Mjolnir findings\", head, \"\"].concat(lines).join(\"\\n\");",
-	"if (process.env.GITHUB_STEP_SUMMARY && lines.length > 0) {",
-	"  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, body + \"\\n\");",
-	"}",
-	"process.stdout.write(lines.length + \" finding(s)\\n\");"
-].join("\n");
-/** True when a workflow was generated by any Mjölnir template (v1 or v2).
-* The v1 needle is matched in its INDENTED form: the v1 template embedded
-* the script via indentBlock(…, 10) inside the `run: |` scalar, so the
-* raw unindented substring never appears in a real v1 file. */
-function isKnownTemplate(content) {
-	return GATES.some((g) => content === TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
+/**
+* First (byte-stable) fixture file in a must-fire / must-not-fire
+* directory, or null when the directory is absent or empty.
+*/
+function firstFixtureFile(dir) {
+	if (!existsSync(dir)) return null;
+	const entries = readdirSync(dir).filter((f) => !f.startsWith(".")).sort();
+	return entries.length > 0 ? join(dir, entries[0]) : null;
 }
-/** Indents an embedded script so it sits inside a YAML `run: |` block scalar. */
-function indentBlock(text, spaces) {
-	const pad = " ".repeat(spaces);
-	return text.split("\n").map((l) => l.length > 0 ? pad + l : l).join("\n");
+//#endregion
+//#region src/commands/explain.ts
+/**
+* `mjolnir explain <RULE-ID>` — implements Plan.md Sprint 1.3
+* (Master-Stabilization-Plan Sprint 5, Task 19).
+*
+* For any registered rule, renders what is wrong, why it matters, the
+* evidence level and confidence behind the verdict, the prescription,
+* and how to verify the fix. This is a presentation layer only — no new
+* detection logic. Every field it prints already exists on RuleMeta or
+* comes from actually running the rule against its own committed
+* must-fire fixture, so the example shown is real detector output, not
+* hand-written prose that can drift from what the rule actually does.
+*/
+const ui$12 = plainContext();
+/**
+* Runs the rule against its own must-fire fixture to get one real,
+* concrete example finding. `fixturesRoot` defaults to this repo's own
+* `tests/fixtures` — explain only has real examples to show when run
+* from (or pointed at) a Mjolnir checkout; degrades honestly
+* (exampleFinding left undefined) otherwise, same as `doctor`.
+*/
+function explainRule(ruleId, fixturesRoot) {
+	const rule = getRule(ruleId);
+	if (!rule) return {
+		ok: false,
+		error: `Unknown rule ID "${ruleId}". Run \`mjolnir rules\` for the full catalog.`
+	};
+	const fixturePath = firstFixtureFile(join(fixturesRoot, ruleId, "must-fire"));
+	if (!fixturePath) return {
+		ok: true,
+		rule
+	};
+	let text;
+	try {
+		text = readFileSync(fixturePath, "utf8").replace(/\r\n/g, "\n");
+	} catch {
+		return {
+			ok: true,
+			rule
+		};
+	}
+	const normalizedPath = fixturePath.replaceAll("\\", "/");
+	let ast;
+	if (rule.appliesTo === "ci-workflows") try {
+		ast = parseWorkflow(text);
+	} catch {
+		return {
+			ok: true,
+			rule
+		};
+	}
+	let findings;
+	try {
+		const parsed = {
+			path: normalizedPath,
+			text,
+			ast
+		};
+		const codeText = computeCodeText(parsed, normalizedPath.endsWith(".py") ? "python" : normalizedPath.endsWith(".java") ? "java" : normalizedPath.endsWith(".cs") ? "csharp" : "typescript");
+		findings = rule.run({
+			...parsed,
+			codeText
+		});
+	} catch {
+		return {
+			ok: true,
+			rule
+		};
+	}
+	const example = findings[0];
+	if (!example) return {
+		ok: true,
+		rule
+	};
+	return {
+		ok: true,
+		rule,
+		exampleFinding: example,
+		exampleFixturePath: fixturePath,
+		exampleFixtureRelPath: relative(fixturesRoot, fixturePath).replaceAll("\\", "/")
+	};
 }
-/** The generated workflow for one gate level. Exported for template tests. */
-const TEMPLATE = (gate) => `name: Mjölnir
-
-on:
-  pull_request:
-
-concurrency:
-  group: mjolnir-\${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    # A hung scan must not sit for the 6-hour default.
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          fetch-depth: 0   # needed for --scope changed merge-base
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
-        with:
-          node-version: 22
-      # Scan with the PINNED version that generated this workflow — never
-      # a floating tag: a new release must not change your gate semantics
-      # with no commit of yours. To review PRs with the exact tool your
-      # repo develops against, add mjolnir-qa to devDependencies and drop
-      # the @version suffix so npx resolves the local install.
-      - name: Scan changed code (exit 1/2 is data — the gate step decides)
-        continue-on-error: true
-        run: npx --yes mjolnir-qa@${CLI_VERSION} . --scope changed --json > mjolnir.json
-      # Reporting, not gating: a crashed scan leaves mjolnir.json empty/missing
-      # and the summary step exits 2/10 — continue-on-error keeps the advisory
-      # job green, exactly like the v1 inline script did (the gate step decides).
-      - name: Annotations + Job Summary
-        if: always()
-        continue-on-error: true
-        run: npx --yes mjolnir-qa@${CLI_VERSION} summary mjolnir.json
-      - name: Render PR comment
-        if: always()
-        continue-on-error: true
-        run: npx --yes mjolnir-qa@${CLI_VERSION} pr-comment . > mjolnir-comment.md
-      # Best-effort: on a pull_request event from a fork the GITHUB_TOKEN is
-      # read-only and this step will 403 for every external contributor. The
-      # Job Summary above is the fallback that always renders.
-      # (pull_request_target would fix the token but is a code-execution
-      # risk — deliberately NOT used.)
-      - name: Post or update PR comment
-        if: always()
-        continue-on-error: true
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        with:
-          script: |
-            const fs = require('fs');
-            let body = '';
-            try { body = fs.readFileSync('mjolnir-comment.md', 'utf8'); } catch (e) {}
-            if (!body.trim()) {
-              console.log('mjolnir-comment.md is empty or missing — nothing to post.');
-              return;
-            }
-            const marker = '<!-- mjolnir-pr-comment -->';
-            const { data: comments } = await github.rest.issues.listComments({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              issue_number: context.issue.number,
-            });
-            const existing = comments.find((c) => c.body?.startsWith(marker));
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existing.id,
-                body,
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: context.issue.number,
-                body,
-              });
-            }
-${gate === "advisory" ? `      # Advisory mode: findings are reported in the Job Summary and the
-      # PR comment, never blocking. The scan step's exit code is visible
-      # as the step outcome, but continue-on-error keeps the job green.
-      - name: Gate (advisory)
-        if: always()
-        run: echo "Advisory mode — findings reported, never blocking."` : `      # Gate enforcement: the scan step's own exit code is deliberately
-      # neutralized (continue-on-error) so reporting steps always run; THIS
-      # step is what fails the job. A partial scan never blocks.
-      - name: Gate (${gate})
-        if: always()
-        run: |
-          node -e '
-${indentBlock(gateScript(gate), 10)}
-          '`}
-`;
-/** Every gate variant, used to tell "our template" from "hand-customized". */
-const GATES = [
-	"advisory",
-	"error",
-	"warning"
-];
-/** Multiset line diff — counts only, for the refusal message. */
-function summarizeContentDiff(existing, incoming) {
-	const remaining = /* @__PURE__ */ new Map();
-	for (const line of existing.split(/\r?\n/)) remaining.set(line, (remaining.get(line) ?? 0) + 1);
-	let added = 0;
-	for (const line of incoming.split(/\r?\n/)) {
-		const count = remaining.get(line) ?? 0;
-		if (count > 0) remaining.set(line, count - 1);
-		else added += 1;
-	}
-	let removed = 0;
-	for (const count of remaining.values()) removed += count;
-	return [`  - ${removed} line(s) of your file are not in the template and would be removed`, `  - ${added} template line(s) are not in your file and would be added`];
-}
-function ciInstall(root, gate = "advisory", options = {}) {
-	const wfDir = join(root, ".github", "workflows");
-	const target = join(wfDir, "mjolnir.yml");
-	if (!existsSync(wfDir)) mkdirSync(wfDir, { recursive: true });
-	const existed = existsSync(target);
-	if (existed) {
-		const current = readFileSync(target, "utf8");
-		if (!isKnownTemplate(current) && !(options.force ?? false)) return {
-			written: target,
-			existed,
-			refused: true,
-			diffSummary: summarizeContentDiff(current, TEMPLATE(gate))
-		};
-	}
-	writeFileSync(target, TEMPLATE(gate));
-	return {
-		written: target,
-		existed,
-		refused: false,
-		diffSummary: []
-	};
-}
-//#endregion
-//#region src/forensics/triage.ts
-const ui$12 = plainContext();
-const QUARANTINE_MIN_ATTEMPTS = 2;
-/** Deterministic triage table rows, worst first. */
-function triageRows(report) {
-	return report.verdicts.filter((v) => v.everFailed || v.passedOnRetry).sort((a, b) => {
-		if (a.passedOnRetry !== b.passedOnRetry) return a.passedOnRetry ? -1 : 1;
-		if (a.attempts !== b.attempts) return b.attempts - a.attempts;
-		return b.totalDurationMs - a.totalDurationMs;
-	}).map((v) => ({
-		file: v.file,
-		title: v.title,
-		attempts: v.attempts,
-		passedOnRetry: v.passedOnRetry,
-		finalStatus: v.finalStatus,
-		totalDurationMs: v.totalDurationMs,
-		suggestedAction: suggestAction(v),
-		proposedQuarantine: v.attempts >= QUARANTINE_MIN_ATTEMPTS && v.everFailed
-	}));
-}
-function suggestAction(v) {
-	if (v.passedOnRetry && v.attempts >= QUARANTINE_MIN_ATTEMPTS) return "quarantine + ticket";
-	if (v.passedOnRetry) return "fix nondeterminism";
-	if (v.finalStatus === "failed" || v.finalStatus === "timedOut") return "fix now — failing";
-	return "investigate";
-}
-/** Terminal rendering of the triage proposal. */
-function renderTriage(report) {
-	const rows = triageRows(report);
-	const lines = [];
-	lines.push(sectionHeader("FLAKY TRIAGE — auto-generated, do not edit", ui$12));
-	lines.push("");
-	if (rows.length === 0) {
-		lines.push("Nothing to triage — no failures or retries in this run.");
-		return lines.join("\n");
-	}
-	const quarantineCount = rows.filter((r) => r.proposedQuarantine).length;
-	for (const r of rows) {
-		const flag = r.passedOnRetry ? "TRUE-FLAKE" : "FAILING";
-		lines.push(`• [${flag}] ${r.title} (${r.file}) — ${r.attempts} attempt${r.attempts === 1 ? "" : "s"} → ${r.suggestedAction}`);
-	}
-	lines.push("");
-	lines.push(`Auto-quarantine proposal: ${quarantineCount} test${quarantineCount === 1 ? "" : "s"} (retried ≥${QUARANTINE_MIN_ATTEMPTS} and failed at least once).`);
-	lines.push("Quarantined tests should run nightly, not per-PR — quarantine is not deletion.");
-	return lines.join("\n");
-}
-/** TRIAGE.md — the meeting artifact. */
-function renderTriageMd(report) {
-	const rows = triageRows(report);
+/**
+* Default column budget when no width is supplied.
+*
+* `explain`'s prose used to be pushed as unbroken strings — the
+* "HOW TO VERIFY THE FIX" paragraph alone is 150 columns — so every
+* explanation overflowed a default terminal. Renderers here take a width
+* rather than reading process.stdout, so output stays a pure function of
+* its arguments (same rule the reporter's palette follows).
+*/
+const DEFAULT_EXPLAIN_WIDTH = 80;
+function renderExplain(result, width = DEFAULT_EXPLAIN_WIDTH) {
+	if (!result.ok || !result.rule) return `explain failed: ${result.error ?? "unknown error"}`;
+	const r = result.rule;
+	const evidenceLevel = r.evidenceLevel ?? deriveEvidenceLevel(r.findingType, r.confidence);
 	const lines = [];
-	lines.push("# TRIAGE.md");
+	/** Pushes prose indented two columns, wrapped to the budget. */
+	const pushBody = (text) => {
+		for (const seg of wrapText(text, Math.max(20, width - 2))) lines.push(`  ${seg}`);
+	};
+	lines.push(sectionHeader(`${r.id} — ${r.title}`, ui$12));
 	lines.push("");
-	lines.push("> Auto-generated by `mjolnir triage` from real run data. Do not edit by hand.");
+	lines.push(`Severity:    ${r.severity}`);
+	lines.push(`Confidence:  ${r.confidence}`);
+	lines.push(`Tier:        ${effectiveTier(r)}${isProvisional(r) ? " (PROVISIONAL)" : ""}`);
+	lines.push(`Evidence:    ${evidenceLevel}`);
+	lines.push(`QA impact:   ${QA_IMPACT_LABELS[r.qaImpact]} (${r.qaImpact})`);
+	const measured = MEASURED_FP[r.id];
+	lines.push(measured ? `Measured FP: ${Math.round(measured.fpRate * 100)}% (${measured.n} hand-classified corpus verdicts)` : `Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)`);
+	if (r.falsePositiveRisk) lines.push(`FP risk:     ${r.falsePositiveRisk} (author estimate)`);
+	if (r.languages?.length) lines.push(`Languages:   ${r.languages.join(", ")}`);
+	if (r.frameworks?.length) lines.push(`Frameworks:  ${r.frameworks.join(", ")}`);
 	lines.push("");
-	if (rows.length === 0) {
-		lines.push("_No flaky or failing tests this run — nothing to triage._ 🎉");
-		return lines.join("\n");
-	}
-	lines.push("| Status | Test | File | Attempts | Duration | Suggested action | Quarantine? |");
-	lines.push("|--------|------|------|----------|----------|------------------|-------------|");
-	for (const r of rows) {
-		const status = r.passedOnRetry ? `${FLAKE_GLYPH} TRUE-FLAKE` : "❌ FAILING";
-		lines.push(`| ${status} | \`${r.title}\` | \`${r.file}\` | ${r.attempts} | ${(r.totalDurationMs / 1e3).toFixed(1)}s | ${r.suggestedAction} | ${r.proposedQuarantine ? "✅ propose" : "—"} |`);
-	}
-	const q = rows.filter((r) => r.proposedQuarantine).length;
+	if (result.exampleFinding) {
+		const f = result.exampleFinding;
+		lines.push("WHAT WAS FOUND (real detector output, not a mockup)");
+		pushBody(f.message);
+		lines.push("");
+		lines.push("WHY IT MATTERS");
+		pushBody(f.why);
+		lines.push("");
+		lines.push("HOW TO FIX");
+		pushBody(f.fix);
+		lines.push("");
+		pushBody(`Example from this rule's own must-fire fixture: ${result.exampleFixtureRelPath ?? result.exampleFixturePath ?? "(unknown path)"}`);
+	} else for (const seg of wrapText("No example available — run this command from a mjolnir checkout (or pass --fixtures-root) so the fixture that proves this rule works can be shown as a real example.", width)) lines.push(seg);
 	lines.push("");
-	lines.push(`**Auto-quarantine proposal: ${q}** — move them to the nightly suite and open tracked tickets.`);
+	lines.push("HOW TO VERIFY THE FIX");
+	pushBody("Re-run `mjolnir` on the changed file(s) — this finding should no longer appear. `mjolnir --scope changed` scopes the check to just what you touched.");
 	lines.push("");
+	lines.push(`Docs: mjolnir rules --md   (full catalog, this rule included)`);
 	return lines.join("\n");
 }
 //#endregion
@@ -15044,68 +14952,998 @@ function sweepStaleTempFiles(dir) {
 	return swept;
 }
 //#endregion
-//#region src/commands/badge.ts
-/**
-* `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
-*
-* Static JSON, no server. The badge makes falsifiable claims:
-* score + date + commit. Anyone can click through and verify.
-*/
-/**
-* Badge colors follow the SAME ScoreState bands as the terminal
-* (≥80 trusted / ≥50 warning / <50 critical / 100 forged) — this
-* retarget fixes the historical threshold drift (the badge used
-* ≥90/≥75/≥50 with four bands while the reporter used ≥80/≥50).
-*
-* Shields.io has no cyan or white-gold, so the mapping is documented
-* here: trusted → `important` (blue-family, closest to aurora-cyan),
-* forged → `success` (the strongest positive signal shields offers).
-* The badge is a peripheral surface; ScoreState remains the truth.
-*/
-function colorFor(score) {
-	const band = deriveScoreState(score).band;
-	if (band === "unmeasured") return "lightgrey";
-	if (band === "forged") return "success";
-	if (band === "trusted") return "important";
-	return band === "warning" ? "yellow" : "red";
-}
-/** Build the shields.io endpoint payload from a scan result. */
-function buildBadge(result, commit) {
-	const errors = result.findings.filter((f) => f.severity === "error").length;
-	const score = result.score;
-	return {
-		schemaVersion: 1,
-		label: "MJÖLNIR",
-		message: score === null ? "no tests found" : score === 100 && errors === 0 ? "100/100 · forged" : `${score}/100 · ${errors} error${errors === 1 ? "" : "s"}`,
-		color: colorFor(score),
-		namedLogo: "vitest",
-		...commit !== void 0 ? { commit } : {}
-	};
+//#region src/engine/resolution.ts
+/** Correlation identity (v1-compatible): ruleId\0file\0message. */
+function fingerprint$2(entry) {
+	return `${entry.ruleId}\u0000${entry.file}\u0000${entry.message}`;
 }
 /**
-* Full README-ready markdown snippet with commit-bound verification line
-* (the falsifiable claim: "verified at commit X on date Y").
+* The §15 ordered algorithm. Pure; first match wins.
 */
-function renderBadgeSnippet(result, repoUrl = "https://github.com/Sergey-Bar/Mjolnir") {
-	let commit = "unknown";
-	try {
-		commit = execSync("git rev-parse --short HEAD", {
-			cwd: process.cwd(),
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			]
-		}).trim();
-	} catch {}
-	const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-	const errors = result.findings.filter((f) => f.severity === "error").length;
-	return [
-		"```markdown",
-		"[![MJÖLNIR](https://img.shields.io/endpoint?url=<your-badge-json-url>)](" + repoUrl + ")",
-		"<!-- Mjölnir verified at commit " + commit + " on " + date + ": " + (result.score === null ? "no tests found" : result.score + "/100") + ", " + errors + " blocking error(s) -->",
-		"```"
+function resolve$1(input) {
+	const { entry, baseline, current } = input;
+	const fp = fingerprint$2(entry);
+	const comparedAgainst = input.baselineCommit ?? baseline.commit ?? "unknown baseline";
+	if (current.partial || current.analysisStatus.rules !== "complete") return {
+		status: "INCONCLUSIVE",
+		cause: "partial",
+		comparedAgainst
+	};
+	if (input.crashedRuleIds?.has(entry.ruleId)) return {
+		status: "INCONCLUSIVE",
+		cause: "crash",
+		comparedAgainst
+	};
+	if (input.skippedFiles?.has(entry.file)) return {
+		status: "INCONCLUSIVE",
+		cause: "skipped",
+		comparedAgainst
+	};
+	if (input.suppressed?.has(`${entry.ruleId}\u0000${entry.file}`)) return {
+		status: "SUPPRESSED",
+		comparedAgainst
+	};
+	if (input.excludedFiles?.has(entry.file)) return {
+		status: "DISAPPEARED-NON-FIX",
+		cause: "excluded",
+		comparedAgainst
+	};
+	const entryRev = entry.detectorRevision;
+	if (entryRev === void 0) return {
+		status: "INCONCLUSIVE",
+		cause: "legacy-baseline",
+		comparedAgainst
+	};
+	const registryRev = input.registryRevisions.get(entry.ruleId);
+	if (registryRev === void 0) return {
+		status: "DISAPPEARED-NON-FIX",
+		cause: "retired",
+		comparedAgainst
+	};
+	if (registryRev !== entryRev) return {
+		status: "INCONCLUSIVE",
+		cause: "revision-changed",
+		comparedAgainst
+	};
+	if (current.findings.some((f) => fingerprint$2(f) === fp)) return {
+		status: "STILL-PRESENT",
+		comparedAgainst
+	};
+	return {
+		status: "VERIFIED-RESOLVED",
+		comparedAgainst
+	};
+}
+/** The §15 rendering law: "FIXED" only for VERIFIED-RESOLVED. */
+function renderResolution(r) {
+	switch (r.status) {
+		case "VERIFIED-RESOLVED": return "FIXED SINCE BASELINE (verified by a complete same-revision scan)";
+		case "STILL-PRESENT": return "STILL PRESENT";
+		case "SUPPRESSED": return "SUPPRESSED (active ignore entry)";
+		case "INCONCLUSIVE": return `INCONCLUSIVE (${r.cause})`;
+		case "DISAPPEARED-NON-FIX": return `DISAPPEARED — NOT A FIX (${r.cause})`;
+	}
+}
+//#endregion
+//#region src/commands/baseline.ts
+/**
+* `mjolnir baseline` / `mjolnir diff` — Sprint 6 Task 24
+* (Master-Stabilization-Plan.md).
+*
+* Implements Plan.md Phase 10 / §24's key insight: existing debt should
+* not block every PR — only NEW or WORSENED debt should. `baseline`
+* snapshots the current finding set to disk; `diff` compares the current
+* scan against that snapshot and reports only what changed.
+*
+* Findings are matched across scans by a stable fingerprint (ruleId +
+* file + message), not by line number — line numbers shift constantly as
+* a file is edited, so matching on them would report unrelated churn as
+* "new" debt and miss genuinely new findings that happen to land on a
+* previously-flagged line.
+*
+* Storage: .mjolnir/baseline.json (local; not gitignored — only
+* .mjolnir/logs/ is, see .gitignore). A team CAN commit this
+* file if they want a shared baseline; that's a deliberate choice this
+* command does not make for them.
+*/
+const ui$11 = plainContext();
+const DEFAULT_BASELINE_PATH = join(".mjolnir", "baseline.json");
+/**
+* Registry-declared detector revisions (§17): a baseline entry whose
+* revision differs from today's registry is INCONCLUSIVE(revision-
+* changed), never resolved. Omitted declarations mean revision 1 (the
+* documented RuleMeta default for first-generation detectors); a
+* ruleId ABSENT from this map means the rule is retired.
+*/
+const REGISTRY_REVISIONS = new Map(RULES.map((r) => [r.id, r.detectorRevision ?? 1]));
+/**
+* Correlation identity for before/after comparison (agent-handoff plan
+* §5.2): ruleId + file + message, deliberately EXCLUDING `line` — a
+* source edit that shifts a finding still correlates. file:line is an
+* occurrence location, not a durable identity; message rewording,
+* file renames and rule-id changes correlate as resolved+new
+* (documented limitation). Exported for the handoff verification
+* contract — do not duplicate this algorithm.
+*/
+function fingerprint$1(f) {
+	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
+}
+function buildBaseline(result, commit) {
+	return {
+		schemaVersion: 1,
+		capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		commit,
+		...result.score !== null ? { score: result.score } : {},
+		findings: result.findings.map((f) => ({
+			ruleId: f.ruleId,
+			file: f.file,
+			message: f.message,
+			severity: f.severity,
+			...f.detectorRevision !== void 0 ? { detectorRevision: f.detectorRevision } : {}
+		}))
+	};
+}
+/**
+* Bug-audit L7 / decision D3: overwriting an existing baseline used to
+* happen silently — a stale re-capture on a dirty tree made `diff`
+* report all old debt as new with no way to see what was lost. The
+* previous baseline is now backed up to `<path>.bak` and the caller
+* prints the notice.
+*/
+function saveBaseline(result, commit, outPath) {
+	mkdirSync(dirname(outPath), { recursive: true });
+	const existed = existsSync(outPath);
+	let backupPath;
+	if (existed) {
+		backupPath = `${outPath}.bak`;
+		copyFileSync(outPath, backupPath);
+	}
+	writeFileAtomic(outPath, JSON.stringify(buildBaseline(result, commit), null, 2) + "\n");
+	return {
+		path: outPath,
+		replaced: existed,
+		...backupPath !== void 0 ? { backupPath } : {}
+	};
+}
+function loadBaseline(path, onWarning) {
+	if (!existsSync(path)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		if (typeof parsed === "object" && parsed !== null && "findings" in parsed && Array.isArray(parsed.findings)) {
+			const file = parsed;
+			const version = parsed.schemaVersion;
+			if (version === void 0) onWarning?.("baseline file has no schemaVersion (pre-versioning format) — treated as v1.");
+			else if (version !== 1) {
+				onWarning?.(`baseline file declares schemaVersion ${JSON.stringify(version)}; this Mjölnir understands v1 — baseline ignored (upgrade Mjölnir to diff it).`);
+				return null;
+			}
+			const rawScore = parsed.score;
+			const score = typeof rawScore === "number" && Number.isFinite(rawScore) ? rawScore : void 0;
+			file.findings = file.findings.filter((f) => typeof f === "object" && f !== null && typeof f.ruleId === "string" && typeof f.file === "string" && typeof f.message === "string");
+			return score === void 0 ? file : {
+				...file,
+				score
+			};
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+function diffAgainstBaseline(result, baseline) {
+	if (!baseline) return {
+		hasBaseline: false,
+		newFindings: [],
+		resolvedFindings: [],
+		unchangedCount: 0
+	};
+	const baseSet = /* @__PURE__ */ new Map();
+	for (const f of baseline.findings) baseSet.set(fingerprint$1(f), f);
+	const headKeys = /* @__PURE__ */ new Set();
+	const newFindings = [];
+	let unchangedCount = 0;
+	for (const f of result.findings) {
+		const key = fingerprint$1(f);
+		headKeys.add(key);
+		if (baseSet.has(key)) unchangedCount++;
+		else newFindings.push(f);
+	}
+	const resolvedFindings = [];
+	for (const [key, f] of baseSet) if (!headKeys.has(key)) {
+		const resolution = resolve$1({
+			entry: f,
+			baseline,
+			current: result,
+			registryRevisions: REGISTRY_REVISIONS
+		});
+		resolvedFindings.push({
+			...f,
+			resolution
+		});
+	}
+	return {
+		hasBaseline: true,
+		baselineCapturedAt: baseline.capturedAt,
+		baselineCommit: baseline.commit,
+		...baseline.score !== void 0 ? { baselineScore: baseline.score } : {},
+		newFindings,
+		resolvedFindings,
+		unchangedCount
+	};
+}
+function renderBaselineSaved(path, count, replaced) {
+	const lines = [
+		sectionHeader("BASELINE SAVED", ui$11),
+		"",
+		`Captured ${count} finding${count === 1 ? "" : "s"} to ${path}.`
+	];
+	if (replaced?.backupPath !== void 0) lines.push(`Replaced an existing baseline — the previous one was saved to ${replaced.backupPath}.`);
+	lines.push(nextStep("mjolnir diff", ui$11) + " — see only what's new.");
+	return lines.join("\n");
+}
+function renderBaselineDiff(diff) {
+	const lines = [];
+	lines.push(sectionHeader("DIFF AGAINST BASELINE", ui$11));
+	lines.push("");
+	if (!diff.hasBaseline) {
+		lines.push("UNKNOWN — no baseline found.");
+		lines.push(nextStep("mjolnir baseline", ui$11) + " to capture a comparison point.");
+		return lines.join("\n");
+	}
+	lines.push(`Baseline captured ${diff.baselineCapturedAt ?? "unknown time"} at commit ${diff.baselineCommit ?? "unknown"}.`);
+	lines.push(`${diff.unchangedCount} pre-existing finding${diff.unchangedCount === 1 ? "" : "s"} carried over — not reported as new.`);
+	lines.push("");
+	if (diff.newFindings.length === 0) lines.push("NEW OR WORSENED DEBT: none. This change introduced nothing new.");
+	else {
+		lines.push(`NEW OR WORSENED DEBT (${diff.newFindings.length}) — this is what should block this PR:`);
+		for (const f of diff.newFindings) lines.push(`  + ${f.ruleId} (${f.severity}) · ${f.file}:${f.line} — ${f.message}`);
+	}
+	lines.push("");
+	if (diff.resolvedFindings.length > 0) {
+		const verified = diff.resolvedFindings.filter((f) => f.resolution.status === "VERIFIED-RESOLVED");
+		const unresolved = diff.resolvedFindings.filter((f) => f.resolution.status !== "VERIFIED-RESOLVED");
+		if (verified.length > 0) {
+			lines.push(`FIXED SINCE BASELINE (${verified.length}):`);
+			for (const f of verified) lines.push(`  ✓ ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
+			lines.push("");
+		}
+		if (unresolved.length > 0) {
+			lines.push(`DISAPPEARED — NOT CLASSIFIED AS FIXED (${unresolved.length}):`);
+			for (const f of unresolved) lines.push(`  ${renderResolution(f.resolution)} · ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
+		}
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region src/mcp/server.ts
+/** Hard caps (§21 threat model: parameter size + resource bounds). */
+const MAX_PARAM_BYTES = 65536;
+const PROTOCOL_VERSION = "2025-06-18";
+/** JSON-RPC error codes (subset used here). */
+const MCP_ERRORS = {
+	PARSE: -32700,
+	INVALID_REQUEST: -32600,
+	METHOD_NOT_FOUND: -32601,
+	INVALID_PARAMS: -32602,
+	INTERNAL: -32603
+};
+/** The tool catalog — 1:1 mappings to canonical verbs, nothing else. */
+const MCP_TOOLS = [
+	{
+		name: "scan",
+		description: "Run the Mjölnir verification scan on a directory and return the canonical machine contract (findings with ruleId/detectorRevision/evidence/trust, completeness fields, deterministic digest). One scan in flight; zero network; plugin gate applies unchanged.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Absolute or repo-relative directory to scan. Must exist."
+				},
+				maxDurationMs: {
+					type: "number",
+					description: "Optional analysis budget in ms (pipeline budget)."
+				}
+			},
+			required: ["path"]
+		}
+	},
+	{
+		name: "explain",
+		description: "Explain one rule: what it detects, why it matters, how to fix it, plus its measured FP rate and trust metadata. Read-only; never runs a scan.",
+		inputSchema: {
+			type: "object",
+			properties: { ruleId: {
+				type: "string",
+				description: "e.g. QA-PW-101"
+			} },
+			required: ["ruleId"]
+		}
+	},
+	{
+		name: "diff",
+		description: "Compare a completed scan result against the target's committed baseline (.mjolnir/baseline.json) using the §15 lifecycle resolution. Returns new findings and per-disappearance resolutions (VERIFIED-RESOLVED / INCONCLUSIVE(cause) / SUPPRESSED / DISAPPEARED-NON-FIX). Read-only.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Scanned directory."
+				},
+				scanResult: {
+					type: "object",
+					description: "The canonical ScanResult JSON previously returned by the scan tool."
+				}
+			},
+			required: ["path", "scanResult"]
+		}
+	}
+];
+/** Strict param validation — unknown/missing/mistyped ⇒ INVALID_PARAMS. */
+function validateParams(name, args) {
+	if (JSON.stringify(args).length > MAX_PARAM_BYTES) return `parameters exceed ${MAX_PARAM_BYTES} bytes (threat model §21)`;
+	if (name === "scan") {
+		if (typeof args["path"] !== "string" || args["path"].length === 0) return "scan requires a non-empty string `path`";
+		if (args["maxDurationMs"] !== void 0 && typeof args["maxDurationMs"] !== "number") return "`maxDurationMs` must be a number";
+	}
+	if (name === "explain") {
+		if (typeof args["ruleId"] !== "string" || !/^QA-[A-Z]+-\d{3}$/.test(args["ruleId"])) return "explain requires `ruleId` matching /^QA-[A-Z]+-\\d{3}$/";
+	}
+	if (name === "diff") {
+		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";
+	}
+	return null;
+}
+/**
+* Serialized queue for tool work (§21: ONE scan in flight). The queue
+* tail swallows each settled result so the chain never accumulates
+* rejections — the caller's own `next` still propagates errors to the
+* awaiting tool call (the `work, work` pair passes the rejection
+* through to `next` too, so `handleToolCall`'s catch converts it into
+* a structured INTERNAL response).
+*/
+let scanInFlight = Promise.resolve();
+function serializeScan(work) {
+	const next = scanInFlight.then(work, work);
+	scanInFlight = next.then(() => void 0, () => void 0);
+	return next;
+}
+/**
+* Dispatch a tool call. Every tool maps 1:1 to canonical semantics —
+* the transport adds SHAPE, never MEANING.
+*/
+async function handleToolCall(call) {
+	const paramError = validateParams(call.name, call.args);
+	if (paramError !== null) return {
+		jsonrpc: "2.0",
+		id: call.id,
+		error: {
+			code: MCP_ERRORS.INVALID_PARAMS,
+			message: paramError
+		}
+	};
+	try {
+		if (call.name === "scan") {
+			const target = resolve(call.args["path"]);
+			if (!existsSync(target)) return {
+				jsonrpc: "2.0",
+				id: call.id,
+				error: {
+					code: MCP_ERRORS.INVALID_PARAMS,
+					message: `scan target does not exist: ${target}`
+				}
+			};
+			const maxDurationMs = typeof call.args["maxDurationMs"] === "number" ? call.args["maxDurationMs"] : Number.POSITIVE_INFINITY;
+			const result = await serializeScan(() => runScan({
+				target,
+				json: true,
+				verbose: false,
+				maxDurationMs,
+				scopeChanged: false,
+				format: "json"
+			}));
+			return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: {
+					...result,
+					contract: buildMachineContract(result)
+				}
+			};
+		}
+		if (call.name === "explain") {
+			const ruleId = call.args["ruleId"];
+			const explanation = explainRule(ruleId, process.cwd());
+			if (!explanation.ok) return {
+				jsonrpc: "2.0",
+				id: call.id,
+				error: {
+					code: MCP_ERRORS.INVALID_PARAMS,
+					message: explanation.error
+				}
+			};
+			return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: explanation
+			};
+		}
+		if (call.name === "diff") {
+			const target = resolve(call.args["path"]);
+			const scanResult = call.args["scanResult"];
+			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 — nothing to resolve against"
+				}
+			};
+			const baseline = loadBaseline(baselinePath);
+			if (baseline === null) return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: {
+					hasBaseline: false,
+					note: "baseline failed to parse"
+				}
+			};
+			const diff = diffAgainstBaseline(scanResult, baseline);
+			return {
+				jsonrpc: "2.0",
+				id: call.id,
+				result: {
+					hasBaseline: true,
+					baselineCapturedAt: diff.baselineCapturedAt,
+					baselineCommit: diff.baselineCommit,
+					newFindings: diff.newFindings,
+					resolutions: diff.resolvedFindings.map((f) => ({
+						ruleId: f.ruleId,
+						file: f.file,
+						message: f.message,
+						resolution: f.resolution
+					})),
+					unchangedCount: diff.unchangedCount
+				}
+			};
+		}
+		return {
+			jsonrpc: "2.0",
+			id: call.id,
+			error: {
+				code: MCP_ERRORS.METHOD_NOT_FOUND,
+				message: `unknown tool: ${call.name}`
+			}
+		};
+	} catch (err) {
+		return {
+			jsonrpc: "2.0",
+			id: call.id,
+			error: {
+				code: MCP_ERRORS.INTERNAL,
+				message: errorMessage(err)
+			}
+		};
+	}
+}
+/** Normalize any thrown value to a string (unit-tested both arms). */
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/** JSON-RPC request shape validation (strict — §21). */
+function validateRequest(msg) {
+	if (typeof msg !== "object" || msg === null) return {
+		ok: false,
+		errorCode: MCP_ERRORS.PARSE
+	};
+	const o = msg;
+	if (o["jsonrpc"] !== "2.0") return {
+		ok: false,
+		errorCode: MCP_ERRORS.INVALID_REQUEST
+	};
+	if (typeof o["method"] !== "string") return {
+		ok: false,
+		errorCode: MCP_ERRORS.INVALID_REQUEST
+	};
+	if (o["id"] === void 0) return {
+		ok: false,
+		errorCode: MCP_ERRORS.INVALID_REQUEST
+	};
+	return {
+		ok: true,
+		id: o["id"],
+		method: o["method"],
+		params: o["params"]
+	};
+}
+/**
+* Handle one JSON-RPC message (initialize / tools/list / tools/call).
+* Returns the response object, or null for notifications.
+*/
+async function handleMcpMessage(msg) {
+	const req = validateRequest(msg);
+	if (!req.ok) return {
+		jsonrpc: "2.0",
+		id: null,
+		error: {
+			code: req.errorCode,
+			message: "malformed JSON-RPC request"
+		}
+	};
+	if (req.method === "initialize") return {
+		jsonrpc: "2.0",
+		id: req.id,
+		result: {
+			protocolVersion: PROTOCOL_VERSION,
+			capabilities: { tools: {} },
+			serverInfo: {
+				name: "mjolnir-qa",
+				version: CLI_VERSION
+			}
+		}
+	};
+	if (req.method === "tools/list") return {
+		jsonrpc: "2.0",
+		id: req.id,
+		result: { tools: MCP_TOOLS }
+	};
+	if (req.method === "tools/call") {
+		const params = req.params ?? {};
+		const name = params["name"];
+		if (typeof name !== "string") return {
+			jsonrpc: "2.0",
+			id: req.id,
+			error: {
+				code: MCP_ERRORS.INVALID_PARAMS,
+				message: "tools/call requires a string `name`"
+			}
+		};
+		const args = typeof params["arguments"] === "object" && params["arguments"] !== null ? params["arguments"] : {};
+		const response = await handleToolCall({
+			id: req.id,
+			name,
+			args
+		});
+		if (response.error !== void 0) return {
+			jsonrpc: "2.0",
+			id: req.id,
+			error: response.error
+		};
+		const payload = response.result;
+		return {
+			jsonrpc: "2.0",
+			id: req.id,
+			result: {
+				content: [{
+					type: "text",
+					text: JSON.stringify(payload, null, 2)
+				}],
+				structuredContent: payload
+			}
+		};
+	}
+	return {
+		jsonrpc: "2.0",
+		id: req.id,
+		error: {
+			code: MCP_ERRORS.METHOD_NOT_FOUND,
+			message: `unknown method: ${req.method}`
+		}
+	};
+}
+//#endregion
+//#region src/mcp/transport.ts
+/**
+* MCP stdio transport loop (blueprint §21 — the framing around the
+* pure-transport server).
+*
+* Reads newline-delimited JSON-RPC 2.0 frames from `input`, writes one
+* response frame per request to `output`. Malformed input produces a
+* structured error response and the loop CONTINUES — the transport
+* stays alive by contract (§21). EOF resolves; the binary entrypoint
+* (stdio.ts) exits 0 after it.
+*/
+/**
+* Drive the transport over arbitrary streams (real stdio in the binary,
+* PassThrough in tests). Resolves on input EOF.
+*/
+async function runStdioTransport(input, output) {
+	const rl = createInterface({ input });
+	for await (const line of rl) await handleStdioLine(line, (s) => output.write(s));
+}
+/**
+* Process one newline-delimited JSON-RPC frame; write the response to
+* `write`. Never throws — malformed frames become structured errors and
+* the transport stays alive (§21).
+*/
+async function handleStdioLine(line, write) {
+	const trimmed = line.trim();
+	if (trimmed.length === 0) return;
+	let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		write(`${JSON.stringify({
+			jsonrpc: "2.0",
+			id: null,
+			error: {
+				code: -32700,
+				message: "parse error — input was not valid JSON"
+			}
+		})}\n`);
+		return;
+	}
+	const response = await handleMcpMessage(parsed);
+	write(`${JSON.stringify(response)}\n`);
+}
+//#endregion
+//#region src/integrations/ci-install.ts
+/**
+* CI integration (Sprint-Plan W7): generates .github/workflows/mjolnir.yml
+* from internal templates ONLY — no user-input interpolation (R3 supply-chain).
+* Default gate: advisory (report, never block).
+*
+* Bug-audit hardening (H2): the previous template shipped the same
+* `github.rest.checks` no-op this repo's own audit removed from mjolnir.yml,
+* failed the job before the annotate/summary steps could run whenever the
+* scan step exited non-zero, recommended floating `mjolnir-qa@latest`, and
+* `ciInstall` silently overwrote hand-customized workflows. The template now
+* mirrors the dogfooded `.github/workflows/mjolnir.yml` (pinned action SHAs,
+* `if: always()` on reporting steps, a real gate step that reads
+* `mjolnir.json`, partial scans never block) and `ciInstall` refuses to
+* replace a customized workflow without an explicit `--force`.
+*/
+/**
+* The gate-check script embedded in generated workflows (and executed
+* directly by tests against fixture JSONs). Semantics, kept in sync with
+* the tool's own exit-code contract:
+*  - missing/unreadable `mjolnir.json` → fail (the scan step crashed; a
+*    silent pass here would turn a broken pipeline into a green one);
+*  - `partial: true` → never block (truncated results can neither prove
+*    nor disprove the gate — the "PARTIAL" banner in the summary is the
+*    honest signal);
+*  - `error` gate → block on any error-severity finding;
+*  - `warning` gate → block on warnings and errors.
+*/
+function gateScript(gate) {
+	return [
+		"const fs = require(\"fs\");",
+		"let r;",
+		"try {",
+		"  r = JSON.parse(fs.readFileSync(\"mjolnir.json\", \"utf8\"));",
+		"} catch (e) {",
+		"  process.stderr.write(\"mjolnir.json is missing or unreadable - the scan step crashed before the gate could run. Failing instead of passing silently.\\n\");",
+		"  process.exit(1);",
+		"}",
+		"if (r.partial === true) {",
+		"  process.stdout.write(\"Scan was PARTIAL - some files were not analyzed; gate not enforced.\\n\");",
+		"  process.exit(0);",
+		"}",
+		"const findings = Array.isArray(r.findings) ? r.findings : [];",
+		"const errors = findings.filter(function (f) { return f && f.severity === \"error\"; }).length;",
+		"const warnings = findings.filter(function (f) { return f && f.severity === \"warning\"; }).length;",
+		"process.stdout.write(\"Mjolnir gate: \" + errors + \" error(s), \" + warnings + \" warning(s).\\n\");",
+		`if (${gate === "error" ? "errors > 0" : "errors > 0 || warnings > 0"}) { process.exit(1); }`,
+		"process.exit(0);"
+	].join("\n");
+}
+/**
+* Template v2 (Terminal + CI UX Overhaul plan, M4): the summary step
+* calls `mjolnir summary mjolnir.json` — annotations + step summary via
+* ONE emitter — instead of the v1 inline SUMMARY_SCRIPT. The gate
+* script is unchanged (reads `partial`, `findings[].severity`).
+*/
+/** Renders findings into `$GITHUB_STEP_SUMMARY`; tolerates a missing scan result.
+* v1 inline script, retained ONLY for overwrite-refusal recognition of
+* workflows generated by older versions (they are treated as ours, so
+* a frictionless `ci install` upgrade stays possible). Exported for the
+* recognition test that reconstructs the embedded form. */
+const SUMMARY_SCRIPT_V1 = [
+	"const fs = require(\"fs\");",
+	"let r = {};",
+	"try { r = JSON.parse(fs.readFileSync(\"mjolnir.json\", \"utf8\")); } catch (e) {}",
+	"const findings = Array.isArray(r.findings) ? r.findings : [];",
+	"const lines = findings.map(function (f) {",
+	"  return \"- **\" + f.ruleId + \"** (\" + f.severity + \") \" + f.file + \":\" + f.line + \" - \" + f.message;",
+	"});",
+	"const head = r.partial === true",
+	"  ? \"Mjolnir scan was PARTIAL - some files may not have been analyzed.\"",
+	"  : \"Mjolnir scan finished.\";",
+	"const body = [\"## Mjolnir findings\", head, \"\"].concat(lines).join(\"\\n\");",
+	"if (process.env.GITHUB_STEP_SUMMARY && lines.length > 0) {",
+	"  fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, body + \"\\n\");",
+	"}",
+	"process.stdout.write(lines.length + \" finding(s)\\n\");"
+].join("\n");
+/** True when a workflow was generated by any Mjölnir template (v1 or v2).
+* The v1 needle is matched in its INDENTED form: the v1 template embedded
+* the script via indentBlock(…, 10) inside the `run: |` scalar, so the
+* raw unindented substring never appears in a real v1 file. */
+function isKnownTemplate(content) {
+	return GATES.some((g) => content === TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
+}
+/** Indents an embedded script so it sits inside a YAML `run: |` block scalar. */
+function indentBlock(text, spaces) {
+	const pad = " ".repeat(spaces);
+	return text.split("\n").map((l) => l.length > 0 ? pad + l : l).join("\n");
+}
+/** The generated workflow for one gate level. Exported for template tests. */
+const TEMPLATE = (gate) => `name: Mjölnir
+
+on:
+  pull_request:
+
+concurrency:
+  group: mjolnir-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    # A hung scan must not sit for the 6-hour default.
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0   # needed for --scope changed merge-base
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+      # Scan with the PINNED version that generated this workflow — never
+      # a floating tag: a new release must not change your gate semantics
+      # with no commit of yours. To review PRs with the exact tool your
+      # repo develops against, add mjolnir-qa to devDependencies and drop
+      # the @version suffix so npx resolves the local install.
+      - name: Scan changed code (exit 1/2 is data — the gate step decides)
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} . --scope changed --json > mjolnir.json
+      # Reporting, not gating: a crashed scan leaves mjolnir.json empty/missing
+      # and the summary step exits 2/10 — continue-on-error keeps the advisory
+      # job green, exactly like the v1 inline script did (the gate step decides).
+      - name: Annotations + Job Summary
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} summary mjolnir.json
+      - name: Render PR comment
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} pr-comment . > mjolnir-comment.md
+      # Best-effort: on a pull_request event from a fork the GITHUB_TOKEN is
+      # read-only and this step will 403 for every external contributor. The
+      # Job Summary above is the fallback that always renders.
+      # (pull_request_target would fix the token but is a code-execution
+      # risk — deliberately NOT used.)
+      - name: Post or update PR comment
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('fs');
+            let body = '';
+            try { body = fs.readFileSync('mjolnir-comment.md', 'utf8'); } catch (e) {}
+            if (!body.trim()) {
+              console.log('mjolnir-comment.md is empty or missing — nothing to post.');
+              return;
+            }
+            const marker = '<!-- mjolnir-pr-comment -->';
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.find((c) => c.body?.startsWith(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+${gate === "advisory" ? `      # Advisory mode: findings are reported in the Job Summary and the
+      # PR comment, never blocking. The scan step's exit code is visible
+      # as the step outcome, but continue-on-error keeps the job green.
+      - name: Gate (advisory)
+        if: always()
+        run: echo "Advisory mode — findings reported, never blocking."` : `      # Gate enforcement: the scan step's own exit code is deliberately
+      # neutralized (continue-on-error) so reporting steps always run; THIS
+      # step is what fails the job. A partial scan never blocks.
+      - name: Gate (${gate})
+        if: always()
+        run: |
+          node -e '
+${indentBlock(gateScript(gate), 10)}
+          '`}
+`;
+/** Every gate variant, used to tell "our template" from "hand-customized". */
+const GATES = [
+	"advisory",
+	"error",
+	"warning"
+];
+/** Multiset line diff — counts only, for the refusal message. */
+function summarizeContentDiff(existing, incoming) {
+	const remaining = /* @__PURE__ */ new Map();
+	for (const line of existing.split(/\r?\n/)) remaining.set(line, (remaining.get(line) ?? 0) + 1);
+	let added = 0;
+	for (const line of incoming.split(/\r?\n/)) {
+		const count = remaining.get(line) ?? 0;
+		if (count > 0) remaining.set(line, count - 1);
+		else added += 1;
+	}
+	let removed = 0;
+	for (const count of remaining.values()) removed += count;
+	return [`  - ${removed} line(s) of your file are not in the template and would be removed`, `  - ${added} template line(s) are not in your file and would be added`];
+}
+function ciInstall(root, gate = "advisory", options = {}) {
+	const wfDir = join(root, ".github", "workflows");
+	const target = join(wfDir, "mjolnir.yml");
+	if (!existsSync(wfDir)) mkdirSync(wfDir, { recursive: true });
+	const existed = existsSync(target);
+	if (existed) {
+		const current = readFileSync(target, "utf8");
+		if (!isKnownTemplate(current) && !(options.force ?? false)) return {
+			written: target,
+			existed,
+			refused: true,
+			diffSummary: summarizeContentDiff(current, TEMPLATE(gate))
+		};
+	}
+	writeFileSync(target, TEMPLATE(gate));
+	return {
+		written: target,
+		existed,
+		refused: false,
+		diffSummary: []
+	};
+}
+//#endregion
+//#region src/forensics/triage.ts
+const ui$10 = plainContext();
+const QUARANTINE_MIN_ATTEMPTS = 2;
+/** Deterministic triage table rows, worst first. */
+function triageRows(report) {
+	return report.verdicts.filter((v) => v.everFailed || v.passedOnRetry).sort((a, b) => {
+		if (a.passedOnRetry !== b.passedOnRetry) return a.passedOnRetry ? -1 : 1;
+		if (a.attempts !== b.attempts) return b.attempts - a.attempts;
+		return b.totalDurationMs - a.totalDurationMs;
+	}).map((v) => ({
+		file: v.file,
+		title: v.title,
+		attempts: v.attempts,
+		passedOnRetry: v.passedOnRetry,
+		finalStatus: v.finalStatus,
+		totalDurationMs: v.totalDurationMs,
+		suggestedAction: suggestAction(v),
+		proposedQuarantine: v.attempts >= QUARANTINE_MIN_ATTEMPTS && v.everFailed
+	}));
+}
+function suggestAction(v) {
+	if (v.passedOnRetry && v.attempts >= QUARANTINE_MIN_ATTEMPTS) return "quarantine + ticket";
+	if (v.passedOnRetry) return "fix nondeterminism";
+	if (v.finalStatus === "failed" || v.finalStatus === "timedOut") return "fix now — failing";
+	return "investigate";
+}
+/** Terminal rendering of the triage proposal. */
+function renderTriage(report) {
+	const rows = triageRows(report);
+	const lines = [];
+	lines.push(sectionHeader("FLAKY TRIAGE — auto-generated, do not edit", ui$10));
+	lines.push("");
+	if (rows.length === 0) {
+		lines.push("Nothing to triage — no failures or retries in this run.");
+		return lines.join("\n");
+	}
+	const quarantineCount = rows.filter((r) => r.proposedQuarantine).length;
+	for (const r of rows) {
+		const flag = r.passedOnRetry ? "TRUE-FLAKE" : "FAILING";
+		lines.push(`• [${flag}] ${r.title} (${r.file}) — ${r.attempts} attempt${r.attempts === 1 ? "" : "s"} → ${r.suggestedAction}`);
+	}
+	lines.push("");
+	lines.push(`Auto-quarantine proposal: ${quarantineCount} test${quarantineCount === 1 ? "" : "s"} (retried ≥${QUARANTINE_MIN_ATTEMPTS} and failed at least once).`);
+	lines.push("Quarantined tests should run nightly, not per-PR — quarantine is not deletion.");
+	return lines.join("\n");
+}
+/** TRIAGE.md — the meeting artifact. */
+function renderTriageMd(report) {
+	const rows = triageRows(report);
+	const lines = [];
+	lines.push("# TRIAGE.md");
+	lines.push("");
+	lines.push("> Auto-generated by `mjolnir triage` from real run data. Do not edit by hand.");
+	lines.push("");
+	if (rows.length === 0) {
+		lines.push("_No flaky or failing tests this run — nothing to triage._ 🎉");
+		return lines.join("\n");
+	}
+	lines.push("| Status | Test | File | Attempts | Duration | Suggested action | Quarantine? |");
+	lines.push("|--------|------|------|----------|----------|------------------|-------------|");
+	for (const r of rows) {
+		const status = r.passedOnRetry ? `${FLAKE_GLYPH} TRUE-FLAKE` : "❌ FAILING";
+		lines.push(`| ${status} | \`${r.title}\` | \`${r.file}\` | ${r.attempts} | ${(r.totalDurationMs / 1e3).toFixed(1)}s | ${r.suggestedAction} | ${r.proposedQuarantine ? "✅ propose" : "—"} |`);
+	}
+	const q = rows.filter((r) => r.proposedQuarantine).length;
+	lines.push("");
+	lines.push(`**Auto-quarantine proposal: ${q}** — move them to the nightly suite and open tracked tickets.`);
+	lines.push("");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/badge.ts
+/**
+* `mjolnir badge` — evidentiary shields.io endpoint JSON (Tier 1 #5).
+*
+* Static JSON, no server. The badge makes falsifiable claims:
+* score + date + commit. Anyone can click through and verify.
+*/
+/**
+* Badge colors follow the SAME ScoreState bands as the terminal
+* (≥80 trusted / ≥50 warning / <50 critical / 100 forged) — this
+* retarget fixes the historical threshold drift (the badge used
+* ≥90/≥75/≥50 with four bands while the reporter used ≥80/≥50).
+*
+* Shields.io has no cyan or white-gold, so the mapping is documented
+* here: trusted → `important` (blue-family, closest to aurora-cyan),
+* forged → `success` (the strongest positive signal shields offers).
+* The badge is a peripheral surface; ScoreState remains the truth.
+*/
+function colorFor(score) {
+	const band = deriveScoreState(score).band;
+	if (band === "unmeasured") return "lightgrey";
+	if (band === "forged") return "success";
+	if (band === "trusted") return "important";
+	return band === "warning" ? "yellow" : "red";
+}
+/** Build the shields.io endpoint payload from a scan result. */
+function buildBadge(result, commit) {
+	const errors = result.findings.filter((f) => f.severity === "error").length;
+	const score = result.score;
+	return {
+		schemaVersion: 1,
+		label: "MJÖLNIR",
+		message: score === null ? "no tests found" : score === 100 && errors === 0 ? "100/100 · forged" : `${score}/100 · ${errors} error${errors === 1 ? "" : "s"}`,
+		color: colorFor(score),
+		namedLogo: "vitest",
+		...commit !== void 0 ? { commit } : {}
+	};
+}
+/**
+* Full README-ready markdown snippet with commit-bound verification line
+* (the falsifiable claim: "verified at commit X on date Y").
+*/
+function renderBadgeSnippet(result, repoUrl = "https://github.com/Sergey-Bar/Mjolnir") {
+	let commit = "unknown";
+	try {
+		commit = execSync("git rev-parse --short HEAD", {
+			cwd: process.cwd(),
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		}).trim();
+	} catch {}
+	const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+	const errors = result.findings.filter((f) => f.severity === "error").length;
+	return [
+		"```markdown",
+		"[![MJÖLNIR](https://img.shields.io/endpoint?url=<your-badge-json-url>)](" + repoUrl + ")",
+		"<!-- Mjölnir verified at commit " + commit + " on " + date + ": " + (result.score === null ? "no tests found" : result.score + "/100") + ", " + errors + " blocking error(s) -->",
+		"```"
 	].join("\n");
 }
 function writeBadge(result, options) {
@@ -15236,1142 +16074,886 @@ const HELP_ENTRIES = [
 	{
 		verb: "rules",
 		summary: "rule catalog with trust metadata (md/json/unmeasured)",
-		usage: "mjolnir rules [--md] [--unmeasured|--measured] [--external]",
-		examples: ["mjolnir rules --md --unmeasured"]
-	},
-	{
-		verb: "suppressions",
-		summary: "list suppressed findings (governance transparency)",
-		usage: "mjolnir suppressions",
-		examples: ["mjolnir suppressions"]
-	},
-	{
-		verb: "create-rule",
-		summary: "scaffold a new rule + fixtures (must-fire, must-not-fire)",
-		usage: "mjolnir create-rule <QA-XXX-nnn> --title \"Rule title\"",
-		examples: ["mjolnir create-rule QA-PW-131 --title \"No request waits\""]
-	},
-	{
-		verb: "doctor",
-		summary: "self-audit of the rule base (fixture firewall, tiers, caps)",
-		usage: "mjolnir doctor [repo-root]",
-		examples: ["mjolnir doctor"]
-	},
-	{
-		verb: "install",
-		summary: "install the agent instruction surfaces + optional staged hook",
-		usage: "mjolnir install [--staged-hook] [--dry-run] [--force]",
-		examples: ["mjolnir install --dry-run", "mjolnir install --staged-hook"]
-	}
-];
-/** Scan-flag entries documented per-flag via the overview. */
-const HELP_FLAGS = [
-	{
-		flag: "--json",
-		summary: "machine-readable output"
-	},
-	{
-		flag: "--format sarif",
-		summary: "SARIF 2.1 for GitHub Code Scanning"
-	},
-	{
-		flag: "--format mermaid",
-		summary: "test-architecture diagram"
-	},
-	{
-		flag: "--tone blunt",
-		summary: "blunter, pattern-mocking messages"
-	},
-	{
-		flag: "--verbose",
-		summary: "show all findings"
-	},
-	{
-		flag: "--scope changed",
-		summary: "only new/changed lines vs merge-base"
-	},
-	{
-		flag: "--max-duration <sec>",
-		summary: "analysis time budget"
-	},
-	{
-		flag: "--width <cols>",
-		summary: "override terminal width"
-	},
-	{
-		flag: "--ascii / --no-ascii",
-		summary: "force glyph mode"
-	},
-	{
-		flag: "--strict",
-		summary: "include quarantine-tier rules"
-	},
-	{
-		flag: "--debug",
-		summary: "print swallowed rule crashes"
-	},
-	{
-		flag: "--cache",
-		summary: "reuse local per-file verdicts"
-	},
-	{
-		flag: "--no-progress",
-		summary: "no live scan-progress line on stderr"
-	},
-	{
-		flag: "--score",
-		summary: "print only the numeric score (or `unknown`)"
-	},
-	{
-		flag: "--category <cat>",
-		summary: "presentation filter (repeatable)"
-	},
-	{
-		flag: "--staged",
-		summary: "scan only git staged files"
-	},
-	{
-		flag: "--blocking <level>",
-		summary: "exit-status override: error|warning|none"
-	},
-	{
-		flag: "--enable-plugins",
-		summary: "allow npm/JS-module rules (default OFF)"
-	}
-];
-const EXIT_CODE_TABLE = [
-	["0", "clean — no findings or the requested artifact was produced"],
-	["1", "errors found (or the diff/impact verdict says the PR should not merge)"],
-	["2", "partial — the scan ran but was truncated, or input was unreadable"],
-	["10", "usage — bad flags or arguments; help is printed"],
-	["20", "crash — internal error; rerun with --debug for the stack trace"]
-];
-function findEntry(verb) {
-	return HELP_ENTRIES.find((e) => e.verb === verb);
-}
-/** True when `mjolnir help <verb>` has a detailed page. */
-function hasVerbHelp(verb) {
-	return findEntry(verb) !== void 0;
-}
-/** One per-verb help page: summary, usage, examples, next step. */
-function renderVerbHelp(verb) {
-	const e = findEntry(verb);
-	if (!e) return [
-		`  No detailed help for "${verb}".`,
-		"",
-		"  $ mjolnir --help",
-		""
-	].join("\n");
-	const lines = [];
-	lines.push(`  ${e.verb} — ${e.summary}`);
-	lines.push("");
-	lines.push(`  Usage:`);
-	lines.push(`    ${e.usage}`);
-	lines.push("");
-	lines.push(`  Examples:`);
-	for (const ex of e.examples) lines.push(`    $ ${ex}`);
-	if (e.next) {
-		lines.push("");
-		lines.push(`  Next step:`);
-		lines.push(`    $ ${e.next}`);
-	}
-	lines.push("");
-	return lines.join("\n");
-}
-const DOCS_URL = "https://github.com/Sergey-Bar/Mjolnir#readme";
-/** The overview's grouped one-line sections, in display order. */
-const GROUPS = [
+		usage: "mjolnir rules [--md] [--unmeasured|--measured] [--external]",
+		examples: ["mjolnir rules --md --unmeasured"]
+	},
 	{
-		title: "Scan",
-		verbs: []
+		verb: "suppressions",
+		summary: "list suppressed findings (governance transparency)",
+		usage: "mjolnir suppressions",
+		examples: ["mjolnir suppressions"]
 	},
 	{
-		title: "CI & PRs",
-		verbs: [
-			"ci install",
-			"summary",
-			"pr-comment",
-			"badge",
-			"impact",
-			"baseline",
-			"diff"
-		]
+		verb: "create-rule",
+		summary: "scaffold a new rule + fixtures (must-fire, must-not-fire)",
+		usage: "mjolnir create-rule <QA-XXX-nnn> --title \"Rule title\"",
+		examples: ["mjolnir create-rule QA-PW-131 --title \"No request waits\""]
 	},
 	{
-		title: "Forensics",
-		verbs: [
-			"forensics",
-			"triage",
-			"pw-report",
-			"doctor:playwright"
-		]
+		verb: "doctor",
+		summary: "self-audit of the rule base (fixture firewall, tiers, caps)",
+		usage: "mjolnir doctor [repo-root]",
+		examples: ["mjolnir doctor"]
 	},
 	{
-		title: "Maintenance",
-		verbs: [
-			"fix",
-			"debt",
-			"stats",
-			"suppressions",
-			"handover",
-			"init",
-			"doctor",
-			"create-rule"
-		]
+		verb: "install",
+		summary: "install the agent instruction surfaces + optional staged hook",
+		usage: "mjolnir install [--staged-hook] [--dry-run] [--force]",
+		examples: ["mjolnir install --dry-run", "mjolnir install --staged-hook"]
 	},
 	{
-		title: "Meta",
-		verbs: [
-			"rules",
-			"explain",
-			"why",
-			"handoff",
-			"install"
-		]
+		verb: "mcp",
+		summary: "run as an MCP server over stdio (scan / explain / diff tools)",
+		usage: "mjolnir mcp",
+		examples: ["mjolnir mcp"]
 	}
 ];
-const SCAN_SUMMARY_LINES = ["mjolnir [path]                 full-repo scan + WORTHINESS score"];
-/**
-* The redesigned root help (plan M2): grouped sections, one-line
-* descriptions, copy-pasteable examples, the frozen exit-code table and
-* the docs link. Content is identical whether colored or piped — the
-* caller decides (runHelpCommand passes a resolved palette; printUsage
-* stays plain).
-*/
-function renderRootHelp(schemaVersion = 1) {
-	const byVerb = new Map(HELP_ENTRIES.map((e) => [e.verb, e]));
-	const lines = [];
-	lines.push("🔨 mjölnir — verification trust engine for test suites and CI pipelines");
-	lines.push("");
-	lines.push("Usage: mjolnir [path] [options] · mjolnir <subcommand> [args] · mjolnir help <verb>");
-	lines.push("");
-	lines.push("The product is one command in CI:");
-	lines.push("");
-	lines.push("  mjolnir --scope changed        scan only what the branch touched; exit 1 on");
-	lines.push("                                 new findings. `mjolnir ci install` writes the");
-	lines.push("                                 workflow for you.");
-	lines.push("");
-	lines.push("Everything else is optional.");
-	lines.push("");
-	lines.push("  " + SCAN_SUMMARY_LINES[0]);
-	lines.push("  mjolnir explain <RULE-ID>      what/why/fix + measured FP rate for one rule");
-	lines.push("  mjolnir rules --unmeasured     the rules running on assumption, not measurement");
-	lines.push("");
-	lines.push("Options:");
-	for (const f of HELP_FLAGS) {
-		const pad = f.flag.padEnd(22);
-		lines.push(`  ${pad}${f.summary}`);
-	}
-	lines.push("  -v, --version         print the installed version and exit");
-	lines.push("  -h, --help            show this help");
-	lines.push("");
-	for (const g of GROUPS) {
-		lines.push(`Subcommands — ${g.title}:`);
-		for (const verb of g.verbs) {
-			const e = byVerb.get(verb);
-			if (!e) continue;
-			const usage = e.usage.replace(/^mjolnir /, "").padEnd(46);
-			lines.push(`  ${usage}${e.summary}`);
-		}
-		lines.push("");
-	}
-	lines.push("Copy-paste starts:");
-	lines.push("  $ mjolnir                         score this repo's test suite");
-	lines.push("  $ mjolnir --scope changed         CI gate: only what the branch touched");
-	lines.push("  $ mjolnir ci install              write the PR workflow");
-	lines.push("  $ mjolnir forensics test-results  where the flakes hide");
-	lines.push("");
-	lines.push("Per-command help: mjolnir help <verb>   (e.g. mjolnir help fix)");
-	lines.push("");
-	lines.push(`Exit codes: ${EXIT_CODE_TABLE.map(([c]) => c).join(" · ")}`);
-	for (const [code, meaning] of EXIT_CODE_TABLE) lines.push(`  ${code.padEnd(3)} ${meaning}`);
-	lines.push("");
-	lines.push(`Docs: ${DOCS_URL}   (JSON schemaVersion ${schemaVersion}, additive-only)`);
-	return lines.join("\n");
-}
-//#endregion
-//#region src/commands/debt.ts
-const ui$11 = plainContext();
-/** Cost model (documented, conservative): hours/quarter per occurrence. */
-const COST_MODEL = {
-	"QA-TEST-004": {
-		label: "Hard sleeps",
-		hoursPerOccurrence: .4
-	},
-	"QA-PY-005": {
-		label: "Hard sleeps",
-		hoursPerOccurrence: .4
-	},
-	"QA-PW-118": {
-		label: "Network-idle waits",
-		hoursPerOccurrence: .3
-	},
-	"QA-TEST-002": {
-		label: "Skipped tests",
-		hoursPerOccurrence: .2
-	},
-	"QA-PY-002": {
-		label: "Skipped tests",
-		hoursPerOccurrence: .2
-	},
-	"QA-TEST-003": {
-		label: "No-assertion tests",
-		hoursPerOccurrence: .25
-	},
-	"QA-PY-003": {
-		label: "No-assertion tests",
-		hoursPerOccurrence: .25
+/** Scan-flag entries documented per-flag via the overview. */
+const HELP_FLAGS = [
+	{
+		flag: "--json",
+		summary: "machine-readable output"
 	},
-	"QA-TEST-010": {
-		label: "Empty test bodies",
-		hoursPerOccurrence: .15
+	{
+		flag: "--format sarif",
+		summary: "SARIF 2.1 for GitHub Code Scanning"
 	},
-	"QA-PY-006": {
-		label: "Empty test bodies",
-		hoursPerOccurrence: .15
+	{
+		flag: "--format mermaid",
+		summary: "test-architecture diagram"
 	},
-	"QA-TQUAL-001": {
-		label: "Mock-only verification",
-		hoursPerOccurrence: .3
+	{
+		flag: "--tone blunt",
+		summary: "blunter, pattern-mocking messages"
 	},
-	"QA-PW-004": {
-		label: "Brittle selectors",
-		hoursPerOccurrence: .35
+	{
+		flag: "--verbose",
+		summary: "show all findings"
 	},
-	"QA-ENV-001": {
-		label: "Environment coupling",
-		hoursPerOccurrence: .5
-	}
-};
-function computeDebt(result) {
-	const byLabel = /* @__PURE__ */ new Map();
-	for (const f of result.findings) {
-		const entry = COST_MODEL[f.ruleId];
-		if (!entry) continue;
-		const cur = byLabel.get(entry.label) ?? {
-			count: 0,
-			hours: 0,
-			ruleIds: /* @__PURE__ */ new Set()
-		};
-		cur.count += 1;
-		cur.hours += entry.hoursPerOccurrence;
-		cur.ruleIds.add(f.ruleId);
-		byLabel.set(entry.label, cur);
-	}
-	const classes = [...byLabel.entries()].map(([label, v]) => ({
-		label,
-		count: v.count,
-		estHoursPerQuarter: Math.round(v.hours * 10) / 10,
-		ruleIds: [...v.ruleIds].sort((a, b) => a.localeCompare(b))
-	})).sort((a, b) => b.estHoursPerQuarter - a.estHoursPerQuarter);
-	return {
-		classes,
-		totalHours: Math.round(classes.reduce((s, c) => s + c.estHoursPerQuarter, 0) * 10) / 10
-	};
-}
-function renderDebt(result) {
-	const { classes, totalHours } = computeDebt(result);
-	const lines = [];
-	lines.push(sectionHeader("TEST DEBT REGISTER", ui$11));
-	lines.push("");
-	if (classes.length === 0) {
-		lines.push("No tracked debt classes found — the suite is clean.");
-		return lines.join("\n");
-	}
-	const rows = ["DEBT CLASS", ""];
-	rows[0] = `DEBT CLASS                  COUNT   EST. HOURS/QUARTER`;
-	for (const c of classes) rows.push(`${c.label.padEnd(26)} ${String(c.count).padStart(5)}   ${c.estHoursPerQuarter.toFixed(1).padStart(8)}`);
-	rows.push(`TOTAL ESTIMATED DRAG:       ~${totalHours.toFixed(1)} engineer-hours/qtr`);
-	for (const row of panel(rows, ui$11)) lines.push(row);
-	lines.push("");
-	lines.push("Cost model is conservative and documented in src/commands/debt.ts.");
-	return lines.join("\n");
-}
-//#endregion
-//#region src/commands/rule-families.ts
-const RULE_FAMILIES = [
 	{
-		token: "TEST",
-		dir: "test",
-		category: "QA-TEST",
-		appliesTo: "test-files"
+		flag: "--scope changed",
+		summary: "only new/changed lines vs merge-base"
 	},
 	{
-		token: "TQUAL",
-		dir: "quality",
-		category: "QA-TQUAL",
-		appliesTo: "test-files"
+		flag: "--max-duration <sec>",
+		summary: "analysis time budget"
 	},
 	{
-		token: "PW",
-		dir: "playwright",
-		category: "QA-PW",
-		appliesTo: "test-files"
+		flag: "--width <cols>",
+		summary: "override terminal width"
 	},
 	{
-		token: "CI",
-		dir: "ci",
-		category: "QA-CI",
-		appliesTo: "ci-workflows"
+		flag: "--ascii / --no-ascii",
+		summary: "force glyph mode"
 	},
 	{
-		token: "PY",
-		dir: "python",
-		category: "QA-PY",
-		appliesTo: "python"
+		flag: "--strict",
+		summary: "include quarantine-tier rules"
 	},
 	{
-		token: "ENV",
-		dir: "quality",
-		category: "QA-ENV",
-		appliesTo: "test-files"
+		flag: "--debug",
+		summary: "print swallowed rule crashes"
 	},
 	{
-		token: "JV",
-		dir: "java",
-		category: "QA-JV",
-		appliesTo: "java"
+		flag: "--cache",
+		summary: "reuse local per-file verdicts"
 	},
 	{
-		token: "CS",
-		dir: "csharp",
-		category: "QA-CS",
-		appliesTo: "csharp"
+		flag: "--no-progress",
+		summary: "no live scan-progress line on stderr"
 	},
 	{
-		token: "CYP",
-		dir: "cypress",
-		category: "QA-CYP",
-		appliesTo: "test-files"
+		flag: "--score",
+		summary: "print only the numeric score (or `unknown`)"
 	},
 	{
-		token: "SE",
-		dir: "selenium",
-		category: "QA-SE",
-		appliesTo: "test-files"
+		flag: "--category <cat>",
+		summary: "presentation filter (repeatable)"
 	},
 	{
-		token: "WDIO",
-		dir: "webdriverio",
-		category: "QA-WDIO",
-		appliesTo: "test-files"
+		flag: "--staged",
+		summary: "scan only git staged files"
 	},
 	{
-		token: "PPTR",
-		dir: "puppeteer",
-		category: "QA-PPTR",
-		appliesTo: "test-files"
+		flag: "--blocking <level>",
+		summary: "exit-status override: error|warning|none"
 	},
 	{
-		token: "APM",
-		dir: "apm",
-		category: "QA-APM",
-		appliesTo: "test-files"
+		flag: "--enable-plugins",
+		summary: "allow npm/JS-module rules (default OFF)"
 	}
 ];
-/** The full ID regex — derived from the table, so doctor and create-rule
-* can never disagree about which families exist. */
-const RULE_ID_RE = new RegExp(`^QA-(?:${RULE_FAMILIES.map((f) => f.token).join("|")})-\\d{3}$`);
-function familyByToken(token) {
-	const upper = token.toUpperCase();
-	return RULE_FAMILIES.find((f) => f.token === upper);
-}
-//#endregion
-//#region src/commands/create-rule.ts
-/**
-* `mjolnir create-rule <ID> --title "..."` — rule scaffold generator
-* (Tier 6 #34, Contribution Surface Engineering).
-*
-* Generates the four files every rule MUST ship with (anti-creep law):
-*   src/rules/<family>/qa-<id-lower>.ts     — the rule
-*   tests/fixtures/<ID>/must-fire/          — at least one must-fire fixture
-*   tests/fixtures/<ID>/must-not-fire/      — at least one must-not fixture
-* and prints the exact registry edit to make.
-*
-* The generated rule intentionally FAILS its fixtures until the author
-* implements it — you cannot ship a stub.
-*/
-const ui$10 = plainContext();
-function parseId(id) {
-	if (!RULE_ID_RE.exec(id)) return null;
-	const family = familyByToken(id.slice(3, id.length - 4));
-	return {
-		family: family.dir,
-		dir: family.dir,
-		category: family.category,
-		appliesTo: family.appliesTo,
-		num: id.slice(-3),
-		lower: id.toLowerCase()
-	};
-}
-function createRuleScaffold(input, rootDir) {
-	const parsed = parseId(input.id);
-	if (!parsed) return {
-		ok: false,
-		error: "Invalid rule ID. Expected QA-<FAMILY>-NNN with one of the registered families (TEST, TQUAL, PW, CI, PY, ENV, JV, CS, CYP, SE, WDIO, PPTR, APM).",
-		files: [],
-		registryEdit: ""
-	};
-	if (!input.title || input.title.trim().length === 0) return {
-		ok: false,
-		error: "A --title is required.",
-		files: [],
-		registryEdit: ""
-	};
-	const dirRel = join("src", "rules", parsed.dir);
-	const ruleRel = join(dirRel, `${parsed.lower}.ts`);
-	const absRule = join(rootDir, ruleRel);
-	if (existsSync(absRule)) return {
-		ok: false,
-		error: `Rule file already exists: ${ruleRel}`,
-		files: [],
-		registryEdit: ""
-	};
-	mkdirSync(join(rootDir, "src", "rules", parsed.dir), { recursive: true });
-	const files = [];
-	writeFileAtomic(absRule, `/**
- * ${input.id} — ${input.title}.
- *
- * TODO(implement): replace the placeholder below. The rule currently
- * returns no findings on purpose so the fixture harness FAILS until
- * real detection logic lands (anti-creep law §18.1).
- */
-
-import { defineRule } from "../rule.js";
-import type { Finding } from "../../types.js";
-
-export const ${camel(parsed.lower)} = defineRule({
-  id: "${input.id}",
-  category: "${parsed.category}",
-  title: ${JSON.stringify(input.title)},
-  severity: "warning",
-  confidence: "medium",
-  findingType: "heuristic-risk",
-  qaImpact: "HYGIENE",
-  appliesTo: ${JSON.stringify(parsed.appliesTo)},
-  run(ctx) {
-    const findings: Omit<Finding, "ruleId" | "category">[] = [];
-    void ctx; // TODO: implement detection over ctx.path / ctx.text
-    return findings;
-  },
-});
-`);
-	files.push(ruleRel);
-	for (const direction of ["must-fire", "must-not-fire"]) {
-		const dirRel = join("tests", "fixtures", input.id, direction);
-		const absDir = join(rootDir, dirRel);
-		mkdirSync(absDir, { recursive: true });
-		const isPy = parsed.family === "python";
-		const name = isPy ? `example.${direction}.py` : `example.${direction}.ts`;
-		const content = isPy ? `# ${input.id} ${direction} fixture — replace with a real case.\n` : `// ${input.id} ${direction} fixture — replace with a real case.\n`;
-		writeFileAtomic(join(absDir, name), content);
-		files.push(join(dirRel, name));
-	}
-	const exportName = camel(parsed.lower);
-	return {
-		ok: true,
-		files,
-		registryEdit: [
-			`// 1. Add import to src/rules/index.ts:`,
-			`import { ${exportName} } from "./${parsed.dir}/${parsed.lower}.js";`,
-			`// 2. Add to the RULES array:`,
-			`  ${exportName},`
-		].join("\n")
-	};
-}
-function camel(idLower) {
-	return idLower.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
-}
-function renderScaffoldReport(result) {
-	if (!result.ok) return `create-rule failed: ${result.error}`;
-	const lines = [];
-	lines.push(sectionHeader("RULE SCAFFOLD CREATED", ui$10));
-	lines.push("");
-	for (const f of result.files) lines.push(`  + ${f}`);
-	lines.push("");
-	lines.push(result.registryEdit);
-	lines.push("");
-	lines.push("Next steps:", "  1. Implement detection logic in the rule's run()", "  2. Replace both fixture skeletons with real cases", "  3. Run: npm test — must-fire AND must-not-fire must pass", "  4. A rule whose fixtures fail CANNOT ship (anti-creep law)");
-	lines.push("");
-	lines.push("Note: running the test suite right now will show the new fixtures FAILING. This is intentional, not a bug in the scaffold — the rule above returns zero findings on purpose, so its must-fire fixture cannot pass until you implement real detection logic. A rule that ships as a silent no-op stub would violate the fixture-firewall law without anyone noticing.");
-	return lines.join("\n");
-}
-//#endregion
-//#region src/commands/handover.ts
-const ui$9 = plainContext();
-const FAKE_GREEN_RULES = /* @__PURE__ */ new Set([
-	"QA-TEST-003",
-	"QA-PY-003",
-	"QA-TEST-010",
-	"QA-PY-006",
-	"QA-TQUAL-002",
-	"QA-PY-012"
-]);
-const FLAKY_RULES = /* @__PURE__ */ new Set([
-	"QA-TEST-004",
-	"QA-PY-005",
-	"QA-PW-118",
-	"QA-PW-114",
-	"QA-TEST-006",
-	"QA-ENV-001"
-]);
-const CI_TRUST_RULES = /* @__PURE__ */ new Set([
-	"QA-CI-001",
-	"QA-CI-002",
-	"QA-CI-005",
-	"QA-CI-007",
-	"QA-CI-008"
-]);
-/** Group findings by directory to name "solid" areas. */
-function dirOf(file) {
-	const idx = file.lastIndexOf("/");
-	return idx === -1 ? file : file.slice(0, idx);
+const EXIT_CODE_TABLE = [
+	["0", "clean — no findings or the requested artifact was produced"],
+	["1", "errors found (or the diff/impact verdict says the PR should not merge)"],
+	["2", "partial — the scan ran but was truncated, or input was unreadable"],
+	["10", "usage — bad flags or arguments; help is printed"],
+	["20", "crash — internal error; rerun with --debug for the stack trace"]
+];
+function findEntry(verb) {
+	return HELP_ENTRIES.find((e) => e.verb === verb);
 }
-function buildHandover(scan, forensics) {
-	const fakeGreen = [];
-	const flaky = [];
-	const ciTrust = [];
-	const touchedDirs = /* @__PURE__ */ new Map();
-	for (const f of scan.findings) {
-		if (FAKE_GREEN_RULES.has(f.ruleId)) fakeGreen.push(f);
-		else if (FLAKY_RULES.has(f.ruleId)) flaky.push(f);
-		else if (CI_TRUST_RULES.has(f.ruleId)) ciTrust.push(f);
-		const d = dirOf(f.file);
-		touchedDirs.set(d, (touchedDirs.get(d) ?? 0) + 1);
-	}
-	const sections = [];
-	const flakyFromRuns = forensics?.verdicts.filter((v) => v.passedOnRetry || v.everFailed) ?? [];
-	const flakyItems = [];
-	for (const v of flakyFromRuns.slice(0, 5)) flakyItems.push(`${v.title} (${v.file}) — ${v.attempts} attempt${v.attempts === 1 ? "" : "s"}${v.passedOnRetry ? ", TRUE-FLAKE" : ""} → see FLAKY.md`);
-	for (const f of flaky.slice(0, 3)) flakyItems.push(`${f.file}:${f.line} — ${f.message}`);
-	if (flakyItems.length > 0) sections.push({
-		heading: "🔴 Known flaky / timing-sensitive",
-		items: flakyItems
-	});
-	if (fakeGreen.length > 0) sections.push({
-		heading: "🟡 Fake-green suspects (tests that can't fail)",
-		items: fakeGreen.slice(0, 5).map((f) => `${f.file}:${f.line} — ${f.message}`)
-	});
-	if (ciTrust.length > 0) sections.push({
-		heading: "⚠ CI trust warnings (green ≠ verified)",
-		items: ciTrust.slice(0, 4).map((f) => `${f.file}:${f.line} — ${f.message}`)
-	});
-	if (new Set(scan.findings.map((f) => f.file)).size === 0 && scan.score !== null && scan.score >= 90 || scan.findings.length === 0) sections.push({
-		heading: "🟢 Solid foundation",
-		items: ["No tracked anti-patterns found in scanned specs — good place to start contributing."]
-	});
-	const totalIssues = fakeGreen.length + flaky.length + ciTrust.length + (forensics?.flakyTests ?? 0);
-	return {
-		sections,
-		summaryLine: totalIssues === 0 ? "Welcome aboard — the suite is in good shape." : `${totalIssues} thing${totalIssues === 1 ? "" : "s"} to know about before your first release sign-off.`
-	};
+/** True when `mjolnir help <verb>` has a detailed page. */
+function hasVerbHelp(verb) {
+	return findEntry(verb) !== void 0;
 }
-function renderHandover(map) {
+/** One per-verb help page: summary, usage, examples, next step. */
+function renderVerbHelp(verb) {
+	const e = findEntry(verb);
+	if (!e) return [
+		`  No detailed help for "${verb}".`,
+		"",
+		"  $ mjolnir --help",
+		""
+	].join("\n");
 	const lines = [];
-	lines.push(sectionHeader("WELCOME TO THE TEST SUITE — WHAT YOU NEED TO KNOW", ui$9));
+	lines.push(`  ${e.verb} — ${e.summary}`);
 	lines.push("");
-	lines.push(map.summaryLine);
-	for (const s of map.sections) {
+	lines.push(`  Usage:`);
+	lines.push(`    ${e.usage}`);
+	lines.push("");
+	lines.push(`  Examples:`);
+	for (const ex of e.examples) lines.push(`    $ ${ex}`);
+	if (e.next) {
 		lines.push("");
-		lines.push(s.heading);
-		for (const item of s.items) lines.push(`  • ${item}`);
+		lines.push(`  Next step:`);
+		lines.push(`    $ ${e.next}`);
 	}
 	lines.push("");
-	lines.push("Generated by mjolnir handover — re-run after big refactors.");
 	return lines.join("\n");
 }
-//#endregion
-//#region src/commands/impact.ts
+const DOCS_URL = "https://github.com/Sergey-Bar/Mjolnir#readme";
+/** The overview's grouped one-line sections, in display order. */
+const GROUPS = [
+	{
+		title: "Scan",
+		verbs: []
+	},
+	{
+		title: "CI & PRs",
+		verbs: [
+			"ci install",
+			"summary",
+			"pr-comment",
+			"badge",
+			"impact",
+			"baseline",
+			"diff"
+		]
+	},
+	{
+		title: "Forensics",
+		verbs: [
+			"forensics",
+			"triage",
+			"pw-report",
+			"doctor:playwright"
+		]
+	},
+	{
+		title: "Maintenance",
+		verbs: [
+			"fix",
+			"debt",
+			"stats",
+			"suppressions",
+			"handover",
+			"init",
+			"doctor",
+			"create-rule"
+		]
+	},
+	{
+		title: "Meta",
+		verbs: [
+			"rules",
+			"explain",
+			"why",
+			"handoff",
+			"install",
+			"mcp"
+		]
+	}
+];
+const SCAN_SUMMARY_LINES = ["mjolnir [path]                 full-repo scan + WORTHINESS score"];
 /**
-* `mjolnir impact` — Sprint 6 Task 23 (Master-Stabilization-Plan.md).
-*
-* Answers "what would have burned you": compares the current scan against
-* an earlier point in this repo's own git history and reports anti-patterns
-* that were actually removed (evidence: findings present at the base ref,
-* absent now, backed by a real file+message match) plus new debt introduced
-* since then. That is the entire honesty-safe surface this command can
-* stand behind with real evidence.
-*
-* HARD CONSTRAINT (Honesty Core, non-negotiable per the plan): every number
-* here is evidence-backed from data actually present on disk, or the field
-* is UNKNOWN. This command never estimates or extrapolates "hours saved" or
-* "CI minutes saved" — inventing such a number would be worse than useless,
-* it would be the exact kind of fake-precision this product exists to
-* catch in *other* tools. Local-only, zero network (verified by
-* tests/privacy-network-isolation.spec.ts, which scans this file too).
+* The redesigned root help (plan M2): grouped sections, one-line
+* descriptions, copy-pasteable examples, the frozen exit-code table and
+* the docs link. Content is identical whether colored or piped — the
+* caller decides (runHelpCommand passes a resolved palette; printUsage
+* stays plain).
 */
-const ui$8 = plainContext();
-/** The S1-resolved absolute git binary, or the bare name to fail on. */
-function gitExe() {
-	return resolveGitPath() ?? "git";
-}
-function git(root, args) {
-	try {
-		return execFileSync(gitExe(), [
-			"-C",
-			root,
-			...args
-		], {
-			encoding: "utf8",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			],
-			timeout: 3e4
-		});
-	} catch {
-		return null;
-	}
-}
-/** Like git(), but returns the raw bytes — no utf8 decode round-trip. */
-function gitBuffer(root, args) {
-	try {
-		return execFileSync(gitExe(), [
-			"-C",
-			root,
-			...args
-		], {
-			encoding: "buffer",
-			stdio: [
-				"ignore",
-				"pipe",
-				"ignore"
-			],
-			timeout: 3e4
-		});
-	} catch {
-		return null;
-	}
-}
-/** Fingerprint a finding for cross-commit matching (line numbers shift). */
-function fingerprint$2(f) {
-	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
-}
-async function computeImpact(root, options) {
-	const unknownFacts = ["CI minutes or engineer-hours saved: not computed — this repo does not store historical CI run duration locally, and this command never estimates a number it cannot prove."];
-	if (!existsSync(join(root, ".git"))) return {
-		hasComparison: false,
-		unknownReason: "not-a-git-repo",
-		resolved: [],
-		introduced: [],
-		unknownFacts
-	};
-	let baseRef = options.since;
-	if (!baseRef) baseRef = git(root, ["rev-parse", "HEAD~1"])?.trim() ?? git(root, [
-		"merge-base",
-		"HEAD",
-		options.baseBranch ?? "main"
-	])?.trim() ?? void 0;
-	else baseRef = git(root, ["rev-parse", baseRef])?.trim() ?? baseRef;
-	if (!baseRef) return {
-		hasComparison: false,
-		unknownReason: "no-prior-commit",
-		resolved: [],
-		introduced: [],
-		unknownFacts
-	};
-	const headRef = git(root, ["rev-parse", "HEAD"])?.trim() ?? "HEAD";
-	if (baseRef === headRef) return {
-		hasComparison: false,
-		unknownReason: options.since ? "base-equals-head" : "no-prior-commit",
-		baseRef,
-		headRef,
-		resolved: [],
-		introduced: [],
-		unknownFacts
-	};
-	let tmpDir;
-	try {
-		tmpDir = mkdtempSync(join(tmpdir(), "mjolnir-impact-"));
-	} catch {
-		return {
-			hasComparison: false,
-			unknownReason: "tree-materialize-failed",
-			baseRef,
-			headRef,
-			resolved: [],
-			introduced: [],
-			unknownFacts
-		};
+function renderRootHelp(schemaVersion = 1) {
+	const byVerb = new Map(HELP_ENTRIES.map((e) => [e.verb, e]));
+	const lines = [];
+	lines.push("🔨 mjölnir — verification trust engine for test suites and CI pipelines");
+	lines.push("");
+	lines.push("Usage: mjolnir [path] [options] · mjolnir <subcommand> [args] · mjolnir help <verb>");
+	lines.push("");
+	lines.push("The product is one command in CI:");
+	lines.push("");
+	lines.push("  mjolnir --scope changed        scan only what the branch touched; exit 1 on");
+	lines.push("                                 new findings. `mjolnir ci install` writes the");
+	lines.push("                                 workflow for you.");
+	lines.push("");
+	lines.push("Everything else is optional.");
+	lines.push("");
+	lines.push("  " + SCAN_SUMMARY_LINES[0]);
+	lines.push("  mjolnir explain <RULE-ID>      what/why/fix + measured FP rate for one rule");
+	lines.push("  mjolnir rules --unmeasured     the rules running on assumption, not measurement");
+	lines.push("");
+	lines.push("Options:");
+	for (const f of HELP_FLAGS) {
+		const pad = f.flag.padEnd(22);
+		lines.push(`  ${pad}${f.summary}`);
 	}
-	let baseResult;
-	let baseTreeTruncated;
-	try {
-		const treeListing = git(root, [
-			"ls-tree",
-			"-r",
-			"--name-only",
-			"-z",
-			baseRef
-		]);
-		if (treeListing === null) return {
-			hasComparison: false,
-			unknownReason: "tree-listing-failed",
-			baseRef,
-			headRef,
-			resolved: [],
-			introduced: [],
-			unknownFacts
-		};
-		const paths = treeListing.split("\0").filter(Boolean);
-		const MAX_FILES = 2e4;
-		const truncated = paths.length > MAX_FILES;
-		for (const relPath of paths.slice(0, MAX_FILES)) {
-			const blob = gitBuffer(root, ["show", `${baseRef}:${relPath}`]);
-			if (blob === null) continue;
-			const dest = join(tmpDir, relPath);
-			mkdirSync(dirname(dest), { recursive: true });
-			writeFileSync(dest, blob);
-		}
-		if (truncated) {
-			baseTreeTruncated = {
-				scanned: Math.min(paths.length, MAX_FILES),
-				total: paths.length
-			};
-			unknownFacts.push(`Base tree materialization truncated at ${MAX_FILES} of ${paths.length} paths — files beyond the cap were never scanned at base, so findings that exist only there are misreported here as new debt.`);
+	lines.push("  -v, --version         print the installed version and exit");
+	lines.push("  -h, --help            show this help");
+	lines.push("");
+	for (const g of GROUPS) {
+		lines.push(`Subcommands — ${g.title}:`);
+		for (const verb of g.verbs) {
+			const e = byVerb.get(verb);
+			if (!e) continue;
+			const usage = e.usage.replace(/^mjolnir /, "").padEnd(46);
+			lines.push(`  ${usage}${e.summary}`);
 		}
-		baseResult = await options.runScan(tmpDir);
-	} catch {
-		return {
-			hasComparison: false,
-			unknownReason: "tree-materialize-failed",
-			baseRef,
-			headRef,
-			resolved: [],
-			introduced: [],
-			unknownFacts
+		lines.push("");
+	}
+	lines.push("Copy-paste starts:");
+	lines.push("  $ mjolnir                         score this repo's test suite");
+	lines.push("  $ mjolnir --scope changed         CI gate: only what the branch touched");
+	lines.push("  $ mjolnir ci install              write the PR workflow");
+	lines.push("  $ mjolnir forensics test-results  where the flakes hide");
+	lines.push("");
+	lines.push("Per-command help: mjolnir help <verb>   (e.g. mjolnir help fix)");
+	lines.push("");
+	lines.push(`Exit codes: ${EXIT_CODE_TABLE.map(([c]) => c).join(" · ")}`);
+	for (const [code, meaning] of EXIT_CODE_TABLE) lines.push(`  ${code.padEnd(3)} ${meaning}`);
+	lines.push("");
+	lines.push(`Docs: ${DOCS_URL}   (JSON schemaVersion ${schemaVersion}, additive-only)`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/debt.ts
+const ui$9 = plainContext();
+/** Cost model (documented, conservative): hours/quarter per occurrence. */
+const COST_MODEL = {
+	"QA-TEST-004": {
+		label: "Hard sleeps",
+		hoursPerOccurrence: .4
+	},
+	"QA-PY-005": {
+		label: "Hard sleeps",
+		hoursPerOccurrence: .4
+	},
+	"QA-PW-118": {
+		label: "Network-idle waits",
+		hoursPerOccurrence: .3
+	},
+	"QA-TEST-002": {
+		label: "Skipped tests",
+		hoursPerOccurrence: .2
+	},
+	"QA-PY-002": {
+		label: "Skipped tests",
+		hoursPerOccurrence: .2
+	},
+	"QA-TEST-003": {
+		label: "No-assertion tests",
+		hoursPerOccurrence: .25
+	},
+	"QA-PY-003": {
+		label: "No-assertion tests",
+		hoursPerOccurrence: .25
+	},
+	"QA-TEST-010": {
+		label: "Empty test bodies",
+		hoursPerOccurrence: .15
+	},
+	"QA-PY-006": {
+		label: "Empty test bodies",
+		hoursPerOccurrence: .15
+	},
+	"QA-TQUAL-001": {
+		label: "Mock-only verification",
+		hoursPerOccurrence: .3
+	},
+	"QA-PW-004": {
+		label: "Brittle selectors",
+		hoursPerOccurrence: .35
+	},
+	"QA-ENV-001": {
+		label: "Environment coupling",
+		hoursPerOccurrence: .5
+	}
+};
+function computeDebt(result) {
+	const byLabel = /* @__PURE__ */ new Map();
+	for (const f of result.findings) {
+		const entry = COST_MODEL[f.ruleId];
+		if (!entry) continue;
+		const cur = byLabel.get(entry.label) ?? {
+			count: 0,
+			hours: 0,
+			ruleIds: /* @__PURE__ */ new Set()
 		};
-	} finally {
-		try {
-			rmSync(tmpDir, {
-				recursive: true,
-				force: true
-			});
-		} catch {}
+		cur.count += 1;
+		cur.hours += entry.hoursPerOccurrence;
+		cur.ruleIds.add(f.ruleId);
+		byLabel.set(entry.label, cur);
 	}
-	const headResult = await options.runScan(root);
-	const baseSet = /* @__PURE__ */ new Map();
-	for (const f of baseResult.findings) baseSet.set(fingerprint$2(f), f);
-	const headSet = /* @__PURE__ */ new Map();
-	for (const f of headResult.findings) headSet.set(fingerprint$2(f), f);
-	const resolved = [];
-	for (const [key, f] of baseSet) if (!headSet.has(key)) resolved.push({
-		ruleId: f.ruleId,
-		file: f.file,
-		message: f.message
-	});
-	const introduced = [];
-	for (const [key, f] of headSet) if (!baseSet.has(key)) introduced.push({
-		ruleId: f.ruleId,
-		file: f.file,
-		message: f.message
-	});
+	const classes = [...byLabel.entries()].map(([label, v]) => ({
+		label,
+		count: v.count,
+		estHoursPerQuarter: Math.round(v.hours * 10) / 10,
+		ruleIds: [...v.ruleIds].sort((a, b) => a.localeCompare(b))
+	})).sort((a, b) => b.estHoursPerQuarter - a.estHoursPerQuarter);
 	return {
-		hasComparison: true,
-		baseRef,
-		headRef,
-		...baseTreeTruncated ? { baseTreeTruncated } : {},
-		resolved: resolved.sort((a, b) => a.file.localeCompare(b.file)),
-		introduced: introduced.sort((a, b) => a.file.localeCompare(b.file)),
-		unknownFacts
+		classes,
+		totalHours: Math.round(classes.reduce((s, c) => s + c.estHoursPerQuarter, 0) * 10) / 10
 	};
 }
-function renderImpact(report) {
+function renderDebt(result) {
+	const { classes, totalHours } = computeDebt(result);
 	const lines = [];
-	lines.push(sectionHeader("IMPACT REPORT", ui$8));
+	lines.push(sectionHeader("TEST DEBT REGISTER", ui$9));
 	lines.push("");
-	if (!report.hasComparison) {
-		lines.push(`UNKNOWN — no comparison could be made (${report.unknownReason ?? "unknown reason"}).`);
-		lines.push("This is reported as UNKNOWN rather than a fabricated zero: mjolnir");
-		lines.push("never invents a number it cannot prove.");
-		lines.push("");
-		for (const fact of report.unknownFacts) lines.push(`UNKNOWN: ${fact}`);
+	if (classes.length === 0) {
+		lines.push("No tracked debt classes found — the suite is clean.");
 		return lines.join("\n");
 	}
-	lines.push(`Comparing ${report.baseRef?.slice(0, 12)} → ${report.headRef?.slice(0, 12)}`);
-	lines.push("");
-	if (report.baseTreeTruncated) {
-		lines.push(`UNKNOWN: base tree truncated — scanned ${report.baseTreeTruncated.scanned} of ${report.baseTreeTruncated.total} paths.`);
-		lines.push("Files beyond the cap were never scanned at base; their findings are misreported as new debt.");
-		lines.push("");
-	}
-	if (report.resolved.length === 0) lines.push("FIXED SINCE BASE: none found.");
-	else {
-		lines.push(`FIXED SINCE BASE (${report.resolved.length}) — real, evidence-backed:`);
-		for (const f of report.resolved) lines.push(`  ✓ ${f.ruleId} · ${f.file} — ${f.message}`);
-	}
-	lines.push("");
-	if (report.introduced.length === 0) lines.push("NEW DEBT SINCE BASE: none found.");
-	else {
-		lines.push(`NEW DEBT SINCE BASE (${report.introduced.length}):`);
-		for (const f of report.introduced) lines.push(`  + ${f.ruleId} · ${f.file} — ${f.message}`);
-	}
+	const rows = ["DEBT CLASS", ""];
+	rows[0] = `DEBT CLASS                  COUNT   EST. HOURS/QUARTER`;
+	for (const c of classes) rows.push(`${c.label.padEnd(26)} ${String(c.count).padStart(5)}   ${c.estHoursPerQuarter.toFixed(1).padStart(8)}`);
+	rows.push(`TOTAL ESTIMATED DRAG:       ~${totalHours.toFixed(1)} engineer-hours/qtr`);
+	for (const row of panel(rows, ui$9)) lines.push(row);
 	lines.push("");
-	for (const fact of report.unknownFacts) lines.push(`UNKNOWN: ${fact}`);
+	lines.push("Cost model is conservative and documented in src/commands/debt.ts.");
 	return lines.join("\n");
 }
 //#endregion
-//#region src/engine/resolution.ts
-/** Correlation identity (v1-compatible): ruleId\0file\0message. */
-function fingerprint$1(entry) {
-	return `${entry.ruleId}\u0000${entry.file}\u0000${entry.message}`;
-}
+//#region src/commands/rule-families.ts
+const RULE_FAMILIES = [
+	{
+		token: "TEST",
+		dir: "test",
+		category: "QA-TEST",
+		appliesTo: "test-files"
+	},
+	{
+		token: "TQUAL",
+		dir: "quality",
+		category: "QA-TQUAL",
+		appliesTo: "test-files"
+	},
+	{
+		token: "PW",
+		dir: "playwright",
+		category: "QA-PW",
+		appliesTo: "test-files"
+	},
+	{
+		token: "CI",
+		dir: "ci",
+		category: "QA-CI",
+		appliesTo: "ci-workflows"
+	},
+	{
+		token: "PY",
+		dir: "python",
+		category: "QA-PY",
+		appliesTo: "python"
+	},
+	{
+		token: "ENV",
+		dir: "quality",
+		category: "QA-ENV",
+		appliesTo: "test-files"
+	},
+	{
+		token: "JV",
+		dir: "java",
+		category: "QA-JV",
+		appliesTo: "java"
+	},
+	{
+		token: "CS",
+		dir: "csharp",
+		category: "QA-CS",
+		appliesTo: "csharp"
+	},
+	{
+		token: "CYP",
+		dir: "cypress",
+		category: "QA-CYP",
+		appliesTo: "test-files"
+	},
+	{
+		token: "SE",
+		dir: "selenium",
+		category: "QA-SE",
+		appliesTo: "test-files"
+	},
+	{
+		token: "WDIO",
+		dir: "webdriverio",
+		category: "QA-WDIO",
+		appliesTo: "test-files"
+	},
+	{
+		token: "PPTR",
+		dir: "puppeteer",
+		category: "QA-PPTR",
+		appliesTo: "test-files"
+	},
+	{
+		token: "APM",
+		dir: "apm",
+		category: "QA-APM",
+		appliesTo: "test-files"
+	}
+];
+/** The full ID regex — derived from the table, so doctor and create-rule
+* can never disagree about which families exist. */
+const RULE_ID_RE = new RegExp(`^QA-(?:${RULE_FAMILIES.map((f) => f.token).join("|")})-\\d{3}$`);
+function familyByToken(token) {
+	const upper = token.toUpperCase();
+	return RULE_FAMILIES.find((f) => f.token === upper);
+}
+//#endregion
+//#region src/commands/create-rule.ts
 /**
-* The §15 ordered algorithm. Pure; first match wins.
+* `mjolnir create-rule <ID> --title "..."` — rule scaffold generator
+* (Tier 6 #34, Contribution Surface Engineering).
+*
+* Generates the four files every rule MUST ship with (anti-creep law):
+*   src/rules/<family>/qa-<id-lower>.ts     — the rule
+*   tests/fixtures/<ID>/must-fire/          — at least one must-fire fixture
+*   tests/fixtures/<ID>/must-not-fire/      — at least one must-not fixture
+* and prints the exact registry edit to make.
+*
+* The generated rule intentionally FAILS its fixtures until the author
+* implements it — you cannot ship a stub.
 */
-function resolve$1(input) {
-	const { entry, baseline, current } = input;
-	const fp = fingerprint$1(entry);
-	const comparedAgainst = input.baselineCommit ?? baseline.commit ?? "unknown baseline";
-	if (current.partial || current.analysisStatus.rules !== "complete") return {
-		status: "INCONCLUSIVE",
-		cause: "partial",
-		comparedAgainst
-	};
-	if (input.crashedRuleIds?.has(entry.ruleId)) return {
-		status: "INCONCLUSIVE",
-		cause: "crash",
-		comparedAgainst
-	};
-	if (input.skippedFiles?.has(entry.file)) return {
-		status: "INCONCLUSIVE",
-		cause: "skipped",
-		comparedAgainst
-	};
-	if (input.suppressed?.has(`${entry.ruleId}\u0000${entry.file}`)) return {
-		status: "SUPPRESSED",
-		comparedAgainst
-	};
-	if (input.excludedFiles?.has(entry.file)) return {
-		status: "DISAPPEARED-NON-FIX",
-		cause: "excluded",
-		comparedAgainst
-	};
-	const entryRev = entry.detectorRevision;
-	if (entryRev === void 0) return {
-		status: "INCONCLUSIVE",
-		cause: "legacy-baseline",
-		comparedAgainst
+const ui$8 = plainContext();
+function parseId(id) {
+	if (!RULE_ID_RE.exec(id)) return null;
+	const family = familyByToken(id.slice(3, id.length - 4));
+	return {
+		family: family.dir,
+		dir: family.dir,
+		category: family.category,
+		appliesTo: family.appliesTo,
+		num: id.slice(-3),
+		lower: id.toLowerCase()
 	};
-	const registryRev = input.registryRevisions.get(entry.ruleId);
-	if (registryRev === void 0) return {
-		status: "DISAPPEARED-NON-FIX",
-		cause: "retired",
-		comparedAgainst
+}
+function createRuleScaffold(input, rootDir) {
+	const parsed = parseId(input.id);
+	if (!parsed) return {
+		ok: false,
+		error: "Invalid rule ID. Expected QA-<FAMILY>-NNN with one of the registered families (TEST, TQUAL, PW, CI, PY, ENV, JV, CS, CYP, SE, WDIO, PPTR, APM).",
+		files: [],
+		registryEdit: ""
 	};
-	if (registryRev !== entryRev) return {
-		status: "INCONCLUSIVE",
-		cause: "revision-changed",
-		comparedAgainst
+	if (!input.title || input.title.trim().length === 0) return {
+		ok: false,
+		error: "A --title is required.",
+		files: [],
+		registryEdit: ""
 	};
-	if (current.findings.some((f) => fingerprint$1(f) === fp)) return {
-		status: "STILL-PRESENT",
-		comparedAgainst
+	const dirRel = join("src", "rules", parsed.dir);
+	const ruleRel = join(dirRel, `${parsed.lower}.ts`);
+	const absRule = join(rootDir, ruleRel);
+	if (existsSync(absRule)) return {
+		ok: false,
+		error: `Rule file already exists: ${ruleRel}`,
+		files: [],
+		registryEdit: ""
 	};
+	mkdirSync(join(rootDir, "src", "rules", parsed.dir), { recursive: true });
+	const files = [];
+	writeFileAtomic(absRule, `/**
+ * ${input.id} — ${input.title}.
+ *
+ * TODO(implement): replace the placeholder below. The rule currently
+ * returns no findings on purpose so the fixture harness FAILS until
+ * real detection logic lands (anti-creep law §18.1).
+ */
+
+import { defineRule } from "../rule.js";
+import type { Finding } from "../../types.js";
+
+export const ${camel(parsed.lower)} = defineRule({
+  id: "${input.id}",
+  category: "${parsed.category}",
+  title: ${JSON.stringify(input.title)},
+  severity: "warning",
+  confidence: "medium",
+  findingType: "heuristic-risk",
+  qaImpact: "HYGIENE",
+  appliesTo: ${JSON.stringify(parsed.appliesTo)},
+  run(ctx) {
+    const findings: Omit<Finding, "ruleId" | "category">[] = [];
+    void ctx; // TODO: implement detection over ctx.path / ctx.text
+    return findings;
+  },
+});
+`);
+	files.push(ruleRel);
+	for (const direction of ["must-fire", "must-not-fire"]) {
+		const dirRel = join("tests", "fixtures", input.id, direction);
+		const absDir = join(rootDir, dirRel);
+		mkdirSync(absDir, { recursive: true });
+		const isPy = parsed.family === "python";
+		const name = isPy ? `example.${direction}.py` : `example.${direction}.ts`;
+		const content = isPy ? `# ${input.id} ${direction} fixture — replace with a real case.\n` : `// ${input.id} ${direction} fixture — replace with a real case.\n`;
+		writeFileAtomic(join(absDir, name), content);
+		files.push(join(dirRel, name));
+	}
+	const exportName = camel(parsed.lower);
 	return {
-		status: "VERIFIED-RESOLVED",
-		comparedAgainst
+		ok: true,
+		files,
+		registryEdit: [
+			`// 1. Add import to src/rules/index.ts:`,
+			`import { ${exportName} } from "./${parsed.dir}/${parsed.lower}.js";`,
+			`// 2. Add to the RULES array:`,
+			`  ${exportName},`
+		].join("\n")
 	};
 }
-/** The §15 rendering law: "FIXED" only for VERIFIED-RESOLVED. */
-function renderResolution(r) {
-	switch (r.status) {
-		case "VERIFIED-RESOLVED": return "FIXED SINCE BASELINE (verified by a complete same-revision scan)";
-		case "STILL-PRESENT": return "STILL PRESENT";
-		case "SUPPRESSED": return "SUPPRESSED (active ignore entry)";
-		case "INCONCLUSIVE": return `INCONCLUSIVE (${r.cause})`;
-		case "DISAPPEARED-NON-FIX": return `DISAPPEARED — NOT A FIX (${r.cause})`;
-	}
+function camel(idLower) {
+	return idLower.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function renderScaffoldReport(result) {
+	if (!result.ok) return `create-rule failed: ${result.error}`;
+	const lines = [];
+	lines.push(sectionHeader("RULE SCAFFOLD CREATED", ui$8));
+	lines.push("");
+	for (const f of result.files) lines.push(`  + ${f}`);
+	lines.push("");
+	lines.push(result.registryEdit);
+	lines.push("");
+	lines.push("Next steps:", "  1. Implement detection logic in the rule's run()", "  2. Replace both fixture skeletons with real cases", "  3. Run: npm test — must-fire AND must-not-fire must pass", "  4. A rule whose fixtures fail CANNOT ship (anti-creep law)");
+	lines.push("");
+	lines.push("Note: running the test suite right now will show the new fixtures FAILING. This is intentional, not a bug in the scaffold — the rule above returns zero findings on purpose, so its must-fire fixture cannot pass until you implement real detection logic. A rule that ships as a silent no-op stub would violate the fixture-firewall law without anyone noticing.");
+	return lines.join("\n");
 }
 //#endregion
-//#region src/commands/baseline.ts
-/**
-* `mjolnir baseline` / `mjolnir diff` — Sprint 6 Task 24
-* (Master-Stabilization-Plan.md).
-*
-* Implements Plan.md Phase 10 / §24's key insight: existing debt should
-* not block every PR — only NEW or WORSENED debt should. `baseline`
-* snapshots the current finding set to disk; `diff` compares the current
-* scan against that snapshot and reports only what changed.
-*
-* Findings are matched across scans by a stable fingerprint (ruleId +
-* file + message), not by line number — line numbers shift constantly as
-* a file is edited, so matching on them would report unrelated churn as
-* "new" debt and miss genuinely new findings that happen to land on a
-* previously-flagged line.
-*
-* Storage: .mjolnir/baseline.json (local; not gitignored — only
-* .mjolnir/logs/ is, see .gitignore). A team CAN commit this
-* file if they want a shared baseline; that's a deliberate choice this
-* command does not make for them.
-*/
+//#region src/commands/handover.ts
 const ui$7 = plainContext();
-const DEFAULT_BASELINE_PATH = join(".mjolnir", "baseline.json");
-/**
-* Registry-declared detector revisions (§17): a baseline entry whose
-* revision differs from today's registry is INCONCLUSIVE(revision-
-* changed), never resolved. Omitted declarations mean revision 1 (the
-* documented RuleMeta default for first-generation detectors); a
-* ruleId ABSENT from this map means the rule is retired.
-*/
-const REGISTRY_REVISIONS = new Map(RULES.map((r) => [r.id, r.detectorRevision ?? 1]));
-/**
-* Correlation identity for before/after comparison (agent-handoff plan
-* §5.2): ruleId + file + message, deliberately EXCLUDING `line` — a
-* source edit that shifts a finding still correlates. file:line is an
-* occurrence location, not a durable identity; message rewording,
-* file renames and rule-id changes correlate as resolved+new
-* (documented limitation). Exported for the handoff verification
-* contract — do not duplicate this algorithm.
-*/
-function fingerprint(f) {
-	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
+const FAKE_GREEN_RULES = /* @__PURE__ */ new Set([
+	"QA-TEST-003",
+	"QA-PY-003",
+	"QA-TEST-010",
+	"QA-PY-006",
+	"QA-TQUAL-002",
+	"QA-PY-012"
+]);
+const FLAKY_RULES = /* @__PURE__ */ new Set([
+	"QA-TEST-004",
+	"QA-PY-005",
+	"QA-PW-118",
+	"QA-PW-114",
+	"QA-TEST-006",
+	"QA-ENV-001"
+]);
+const CI_TRUST_RULES = /* @__PURE__ */ new Set([
+	"QA-CI-001",
+	"QA-CI-002",
+	"QA-CI-005",
+	"QA-CI-007",
+	"QA-CI-008"
+]);
+/** Group findings by directory to name "solid" areas. */
+function dirOf(file) {
+	const idx = file.lastIndexOf("/");
+	return idx === -1 ? file : file.slice(0, idx);
 }
-function buildBaseline(result, commit) {
+function buildHandover(scan, forensics) {
+	const fakeGreen = [];
+	const flaky = [];
+	const ciTrust = [];
+	const touchedDirs = /* @__PURE__ */ new Map();
+	for (const f of scan.findings) {
+		if (FAKE_GREEN_RULES.has(f.ruleId)) fakeGreen.push(f);
+		else if (FLAKY_RULES.has(f.ruleId)) flaky.push(f);
+		else if (CI_TRUST_RULES.has(f.ruleId)) ciTrust.push(f);
+		const d = dirOf(f.file);
+		touchedDirs.set(d, (touchedDirs.get(d) ?? 0) + 1);
+	}
+	const sections = [];
+	const flakyFromRuns = forensics?.verdicts.filter((v) => v.passedOnRetry || v.everFailed) ?? [];
+	const flakyItems = [];
+	for (const v of flakyFromRuns.slice(0, 5)) flakyItems.push(`${v.title} (${v.file}) — ${v.attempts} attempt${v.attempts === 1 ? "" : "s"}${v.passedOnRetry ? ", TRUE-FLAKE" : ""} → see FLAKY.md`);
+	for (const f of flaky.slice(0, 3)) flakyItems.push(`${f.file}:${f.line} — ${f.message}`);
+	if (flakyItems.length > 0) sections.push({
+		heading: "🔴 Known flaky / timing-sensitive",
+		items: flakyItems
+	});
+	if (fakeGreen.length > 0) sections.push({
+		heading: "🟡 Fake-green suspects (tests that can't fail)",
+		items: fakeGreen.slice(0, 5).map((f) => `${f.file}:${f.line} — ${f.message}`)
+	});
+	if (ciTrust.length > 0) sections.push({
+		heading: "⚠ CI trust warnings (green ≠ verified)",
+		items: ciTrust.slice(0, 4).map((f) => `${f.file}:${f.line} — ${f.message}`)
+	});
+	if (new Set(scan.findings.map((f) => f.file)).size === 0 && scan.score !== null && scan.score >= 90 || scan.findings.length === 0) sections.push({
+		heading: "🟢 Solid foundation",
+		items: ["No tracked anti-patterns found in scanned specs — good place to start contributing."]
+	});
+	const totalIssues = fakeGreen.length + flaky.length + ciTrust.length + (forensics?.flakyTests ?? 0);
 	return {
-		schemaVersion: 1,
-		capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-		commit,
-		...result.score !== null ? { score: result.score } : {},
-		findings: result.findings.map((f) => ({
-			ruleId: f.ruleId,
-			file: f.file,
-			message: f.message,
-			severity: f.severity,
-			...f.detectorRevision !== void 0 ? { detectorRevision: f.detectorRevision } : {}
-		}))
+		sections,
+		summaryLine: totalIssues === 0 ? "Welcome aboard — the suite is in good shape." : `${totalIssues} thing${totalIssues === 1 ? "" : "s"} to know about before your first release sign-off.`
 	};
 }
+function renderHandover(map) {
+	const lines = [];
+	lines.push(sectionHeader("WELCOME TO THE TEST SUITE — WHAT YOU NEED TO KNOW", ui$7));
+	lines.push("");
+	lines.push(map.summaryLine);
+	for (const s of map.sections) {
+		lines.push("");
+		lines.push(s.heading);
+		for (const item of s.items) lines.push(`  • ${item}`);
+	}
+	lines.push("");
+	lines.push("Generated by mjolnir handover — re-run after big refactors.");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/impact.ts
 /**
-* Bug-audit L7 / decision D3: overwriting an existing baseline used to
-* happen silently — a stale re-capture on a dirty tree made `diff`
-* report all old debt as new with no way to see what was lost. The
-* previous baseline is now backed up to `<path>.bak` and the caller
-* prints the notice.
+* `mjolnir impact` — Sprint 6 Task 23 (Master-Stabilization-Plan.md).
+*
+* Answers "what would have burned you": compares the current scan against
+* an earlier point in this repo's own git history and reports anti-patterns
+* that were actually removed (evidence: findings present at the base ref,
+* absent now, backed by a real file+message match) plus new debt introduced
+* since then. That is the entire honesty-safe surface this command can
+* stand behind with real evidence.
+*
+* HARD CONSTRAINT (Honesty Core, non-negotiable per the plan): every number
+* here is evidence-backed from data actually present on disk, or the field
+* is UNKNOWN. This command never estimates or extrapolates "hours saved" or
+* "CI minutes saved" — inventing such a number would be worse than useless,
+* it would be the exact kind of fake-precision this product exists to
+* catch in *other* tools. Local-only, zero network (verified by
+* tests/privacy-network-isolation.spec.ts, which scans this file too).
 */
-function saveBaseline(result, commit, outPath) {
-	mkdirSync(dirname(outPath), { recursive: true });
-	const existed = existsSync(outPath);
-	let backupPath;
-	if (existed) {
-		backupPath = `${outPath}.bak`;
-		copyFileSync(outPath, backupPath);
-	}
-	writeFileAtomic(outPath, JSON.stringify(buildBaseline(result, commit), null, 2) + "\n");
-	return {
-		path: outPath,
-		replaced: existed,
-		...backupPath !== void 0 ? { backupPath } : {}
-	};
+const ui$6 = plainContext();
+/** The S1-resolved absolute git binary, or the bare name to fail on. */
+function gitExe() {
+	return resolveGitPath() ?? "git";
 }
-function loadBaseline(path, onWarning) {
-	if (!existsSync(path)) return null;
+function git(root, args) {
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8"));
-		if (typeof parsed === "object" && parsed !== null && "findings" in parsed && Array.isArray(parsed.findings)) {
-			const file = parsed;
-			const version = parsed.schemaVersion;
-			if (version === void 0) onWarning?.("baseline file has no schemaVersion (pre-versioning format) — treated as v1.");
-			else if (version !== 1) {
-				onWarning?.(`baseline file declares schemaVersion ${JSON.stringify(version)}; this Mjölnir understands v1 — baseline ignored (upgrade Mjölnir to diff it).`);
-				return null;
-			}
-			const rawScore = parsed.score;
-			const score = typeof rawScore === "number" && Number.isFinite(rawScore) ? rawScore : void 0;
-			file.findings = file.findings.filter((f) => typeof f === "object" && f !== null && typeof f.ruleId === "string" && typeof f.file === "string" && typeof f.message === "string");
-			return score === void 0 ? file : {
-				...file,
-				score
-			};
-		}
+		return execFileSync(gitExe(), [
+			"-C",
+			root,
+			...args
+		], {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 3e4
+		});
+	} catch {
 		return null;
+	}
+}
+/** Like git(), but returns the raw bytes — no utf8 decode round-trip. */
+function gitBuffer(root, args) {
+	try {
+		return execFileSync(gitExe(), [
+			"-C",
+			root,
+			...args
+		], {
+			encoding: "buffer",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 3e4
+		});
 	} catch {
 		return null;
 	}
 }
-function diffAgainstBaseline(result, baseline) {
-	if (!baseline) return {
-		hasBaseline: false,
-		newFindings: [],
-		resolvedFindings: [],
-		unchangedCount: 0
+/** Fingerprint a finding for cross-commit matching (line numbers shift). */
+function fingerprint(f) {
+	return `${f.ruleId}\u0000${f.file}\u0000${f.message}`;
+}
+async function computeImpact(root, options) {
+	const unknownFacts = ["CI minutes or engineer-hours saved: not computed — this repo does not store historical CI run duration locally, and this command never estimates a number it cannot prove."];
+	if (!existsSync(join(root, ".git"))) return {
+		hasComparison: false,
+		unknownReason: "not-a-git-repo",
+		resolved: [],
+		introduced: [],
+		unknownFacts
 	};
-	const baseSet = /* @__PURE__ */ new Map();
-	for (const f of baseline.findings) baseSet.set(fingerprint(f), f);
-	const headKeys = /* @__PURE__ */ new Set();
-	const newFindings = [];
-	let unchangedCount = 0;
-	for (const f of result.findings) {
-		const key = fingerprint(f);
-		headKeys.add(key);
-		if (baseSet.has(key)) unchangedCount++;
-		else newFindings.push(f);
+	let baseRef = options.since;
+	if (!baseRef) baseRef = git(root, ["rev-parse", "HEAD~1"])?.trim() ?? git(root, [
+		"merge-base",
+		"HEAD",
+		options.baseBranch ?? "main"
+	])?.trim() ?? void 0;
+	else baseRef = git(root, ["rev-parse", baseRef])?.trim() ?? baseRef;
+	if (!baseRef) return {
+		hasComparison: false,
+		unknownReason: "no-prior-commit",
+		resolved: [],
+		introduced: [],
+		unknownFacts
+	};
+	const headRef = git(root, ["rev-parse", "HEAD"])?.trim() ?? "HEAD";
+	if (baseRef === headRef) return {
+		hasComparison: false,
+		unknownReason: options.since ? "base-equals-head" : "no-prior-commit",
+		baseRef,
+		headRef,
+		resolved: [],
+		introduced: [],
+		unknownFacts
+	};
+	let tmpDir;
+	try {
+		tmpDir = mkdtempSync(join(tmpdir(), "mjolnir-impact-"));
+	} catch {
+		return {
+			hasComparison: false,
+			unknownReason: "tree-materialize-failed",
+			baseRef,
+			headRef,
+			resolved: [],
+			introduced: [],
+			unknownFacts
+		};
 	}
-	const resolvedFindings = [];
-	for (const [key, f] of baseSet) if (!headKeys.has(key)) {
-		const resolution = resolve$1({
-			entry: f,
-			baseline,
-			current: result,
-			registryRevisions: REGISTRY_REVISIONS
-		});
-		resolvedFindings.push({
-			...f,
-			resolution
-		});
+	let baseResult;
+	let baseTreeTruncated;
+	try {
+		const treeListing = git(root, [
+			"ls-tree",
+			"-r",
+			"--name-only",
+			"-z",
+			baseRef
+		]);
+		if (treeListing === null) return {
+			hasComparison: false,
+			unknownReason: "tree-listing-failed",
+			baseRef,
+			headRef,
+			resolved: [],
+			introduced: [],
+			unknownFacts
+		};
+		const paths = treeListing.split("\0").filter(Boolean);
+		const MAX_FILES = 2e4;
+		const truncated = paths.length > MAX_FILES;
+		for (const relPath of paths.slice(0, MAX_FILES)) {
+			const blob = gitBuffer(root, ["show", `${baseRef}:${relPath}`]);
+			if (blob === null) continue;
+			const dest = join(tmpDir, relPath);
+			mkdirSync(dirname(dest), { recursive: true });
+			writeFileSync(dest, blob);
+		}
+		if (truncated) {
+			baseTreeTruncated = {
+				scanned: Math.min(paths.length, MAX_FILES),
+				total: paths.length
+			};
+			unknownFacts.push(`Base tree materialization truncated at ${MAX_FILES} of ${paths.length} paths — files beyond the cap were never scanned at base, so findings that exist only there are misreported here as new debt.`);
+		}
+		baseResult = await options.runScan(tmpDir);
+	} catch {
+		return {
+			hasComparison: false,
+			unknownReason: "tree-materialize-failed",
+			baseRef,
+			headRef,
+			resolved: [],
+			introduced: [],
+			unknownFacts
+		};
+	} finally {
+		try {
+			rmSync(tmpDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
 	}
+	const headResult = await options.runScan(root);
+	const baseSet = /* @__PURE__ */ new Map();
+	for (const f of baseResult.findings) baseSet.set(fingerprint(f), f);
+	const headSet = /* @__PURE__ */ new Map();
+	for (const f of headResult.findings) headSet.set(fingerprint(f), f);
+	const resolved = [];
+	for (const [key, f] of baseSet) if (!headSet.has(key)) resolved.push({
+		ruleId: f.ruleId,
+		file: f.file,
+		message: f.message
+	});
+	const introduced = [];
+	for (const [key, f] of headSet) if (!baseSet.has(key)) introduced.push({
+		ruleId: f.ruleId,
+		file: f.file,
+		message: f.message
+	});
 	return {
-		hasBaseline: true,
-		baselineCapturedAt: baseline.capturedAt,
-		baselineCommit: baseline.commit,
-		...baseline.score !== void 0 ? { baselineScore: baseline.score } : {},
-		newFindings,
-		resolvedFindings,
-		unchangedCount
+		hasComparison: true,
+		baseRef,
+		headRef,
+		...baseTreeTruncated ? { baseTreeTruncated } : {},
+		resolved: resolved.sort((a, b) => a.file.localeCompare(b.file)),
+		introduced: introduced.sort((a, b) => a.file.localeCompare(b.file)),
+		unknownFacts
 	};
 }
-function renderBaselineSaved(path, count, replaced) {
-	const lines = [
-		sectionHeader("BASELINE SAVED", ui$7),
-		"",
-		`Captured ${count} finding${count === 1 ? "" : "s"} to ${path}.`
-	];
-	if (replaced?.backupPath !== void 0) lines.push(`Replaced an existing baseline — the previous one was saved to ${replaced.backupPath}.`);
-	lines.push(nextStep("mjolnir diff", ui$7) + " — see only what's new.");
-	return lines.join("\n");
-}
-function renderBaselineDiff(diff) {
+function renderImpact(report) {
 	const lines = [];
-	lines.push(sectionHeader("DIFF AGAINST BASELINE", ui$7));
+	lines.push(sectionHeader("IMPACT REPORT", ui$6));
 	lines.push("");
-	if (!diff.hasBaseline) {
-		lines.push("UNKNOWN — no baseline found.");
-		lines.push(nextStep("mjolnir baseline", ui$7) + " to capture a comparison point.");
+	if (!report.hasComparison) {
+		lines.push(`UNKNOWN — no comparison could be made (${report.unknownReason ?? "unknown reason"}).`);
+		lines.push("This is reported as UNKNOWN rather than a fabricated zero: mjolnir");
+		lines.push("never invents a number it cannot prove.");
+		lines.push("");
+		for (const fact of report.unknownFacts) lines.push(`UNKNOWN: ${fact}`);
 		return lines.join("\n");
 	}
-	lines.push(`Baseline captured ${diff.baselineCapturedAt ?? "unknown time"} at commit ${diff.baselineCommit ?? "unknown"}.`);
-	lines.push(`${diff.unchangedCount} pre-existing finding${diff.unchangedCount === 1 ? "" : "s"} carried over — not reported as new.`);
+	lines.push(`Comparing ${report.baseRef?.slice(0, 12)} → ${report.headRef?.slice(0, 12)}`);
 	lines.push("");
-	if (diff.newFindings.length === 0) lines.push("NEW OR WORSENED DEBT: none. This change introduced nothing new.");
+	if (report.baseTreeTruncated) {
+		lines.push(`UNKNOWN: base tree truncated — scanned ${report.baseTreeTruncated.scanned} of ${report.baseTreeTruncated.total} paths.`);
+		lines.push("Files beyond the cap were never scanned at base; their findings are misreported as new debt.");
+		lines.push("");
+	}
+	if (report.resolved.length === 0) lines.push("FIXED SINCE BASE: none found.");
 	else {
-		lines.push(`NEW OR WORSENED DEBT (${diff.newFindings.length}) — this is what should block this PR:`);
-		for (const f of diff.newFindings) lines.push(`  + ${f.ruleId} (${f.severity}) · ${f.file}:${f.line} — ${f.message}`);
+		lines.push(`FIXED SINCE BASE (${report.resolved.length}) — real, evidence-backed:`);
+		for (const f of report.resolved) lines.push(`  ✓ ${f.ruleId} · ${f.file} — ${f.message}`);
 	}
 	lines.push("");
-	if (diff.resolvedFindings.length > 0) {
-		const verified = diff.resolvedFindings.filter((f) => f.resolution.status === "VERIFIED-RESOLVED");
-		const unresolved = diff.resolvedFindings.filter((f) => f.resolution.status !== "VERIFIED-RESOLVED");
-		if (verified.length > 0) {
-			lines.push(`FIXED SINCE BASELINE (${verified.length}):`);
-			for (const f of verified) lines.push(`  ✓ ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
-			lines.push("");
-		}
-		if (unresolved.length > 0) {
-			lines.push(`DISAPPEARED — NOT CLASSIFIED AS FIXED (${unresolved.length}):`);
-			for (const f of unresolved) lines.push(`  ${renderResolution(f.resolution)} · ${f.ruleId} (${f.severity}) · ${f.file} — ${f.message}`);
-		}
+	if (report.introduced.length === 0) lines.push("NEW DEBT SINCE BASE: none found.");
+	else {
+		lines.push(`NEW DEBT SINCE BASE (${report.introduced.length}):`);
+		for (const f of report.introduced) lines.push(`  + ${f.ruleId} · ${f.file} — ${f.message}`);
 	}
+	lines.push("");
+	for (const fact of report.unknownFacts) lines.push(`UNKNOWN: ${fact}`);
 	return lines.join("\n");
 }
 //#endregion
@@ -16402,7 +16984,7 @@ function renderBaselineDiff(diff) {
 * fix recorded by `diff`), announced once and never repeated. Display-only:
 * it does not change scores, exit codes or the JSON schema.
 */
-const ui$6 = plainContext();
+const ui$5 = plainContext();
 const DEFAULT_STATS_PATH = join(".mjolnir", "stats.json");
 const MILESTONE_MESSAGES = {
 	"first-clean-scan": "MILESTONE: first flawless scan recorded for this repo (score 100, zero findings).",
@@ -16490,13 +17072,13 @@ function saveStats(stats, outPath) {
 }
 function renderStats(stats) {
 	const lines = [];
-	lines.push(sectionHeader("ALL-TIME STATS (this machine, this repo)", ui$6));
+	lines.push(sectionHeader("ALL-TIME STATS (this machine, this repo)", ui$5));
 	lines.push("");
 	if (!stats || stats.recordedFixEvents === 0) {
 		lines.push("No fixes recorded yet.");
 		lines.push("Fixes are counted here only when observed by mjolnir diff —", "capture a baseline first, then diff after making fixes:");
-		lines.push(nextStep("mjolnir baseline", ui$6));
-		lines.push(nextStep("mjolnir diff", ui$6));
+		lines.push(nextStep("mjolnir baseline", ui$5));
+		lines.push(nextStep("mjolnir diff", ui$5));
 		lines.push("");
 		lines.push("UNKNOWN: totals before tracking started. This command only counts");
 		lines.push("what it has personally witnessed via mjolnir diff.");
@@ -16525,7 +17107,7 @@ function renderStats(stats) {
 *
 * Idempotent: existing files are reported, never overwritten.
 */
-const ui$5 = plainContext();
+const ui$4 = plainContext();
 function runInit(rootDir, workspace, options = {}) {
 	const steps = [];
 	const nextCommands = [];
@@ -16575,7 +17157,7 @@ function runInit(rootDir, workspace, options = {}) {
 }
 function renderInit(result) {
 	const lines = [];
-	lines.push(sectionHeader("MJÖLNIR INIT", ui$5));
+	lines.push(sectionHeader("MJÖLNIR INIT", ui$4));
 	lines.push("");
 	for (const s of result.steps) {
 		const icon = s.status === "advice" ? "·" : s.status === "exists" ? "=" : "-";
@@ -16584,7 +17166,7 @@ function renderInit(result) {
 	if (result.nextCommands.length > 0) {
 		lines.push("");
 		lines.push("Next commands:");
-		for (const c of result.nextCommands) lines.push(nextStep(c, ui$5));
+		for (const c of result.nextCommands) lines.push(nextStep(c, ui$4));
 	}
 	lines.push("");
 	lines.push("Existing files are never overwritten — init is safe to re-run.");
@@ -16602,7 +17184,7 @@ function tryReadPackageJson(rootDir) {
 }
 //#endregion
 //#region src/commands/pw-report.ts
-const ui$4 = plainContext();
+const ui$3 = plainContext();
 function summarizePwRun(report) {
 	const slowest = [...report.verdicts].sort((a, b) => b.totalDurationMs - a.totalDurationMs).slice(0, 5).map((v) => ({
 		title: v.title,
@@ -16622,7 +17204,7 @@ function summarizePwRun(report) {
 }
 function renderPwRunSummary(s) {
 	const lines = [];
-	lines.push(sectionHeader("MJÖLNIR — RUN SUMMARY", ui$4));
+	lines.push(sectionHeader("MJÖLNIR — RUN SUMMARY", ui$3));
 	lines.push("");
 	lines.push(`${s.total} tests · ${s.passed} passed · ${s.failed} failed · ${s.skipped} skipped`);
 	if (s.retried > 0 || s.trueFlakes > 0) lines.push(`↻ ${s.retried} retried · ${FLAKE_GLYPH} ${s.trueFlakes} TRUE-FLAKE${s.trueFlakes === 1 ? "" : "S"} (passed only on attempt ≥2)`);
@@ -16653,7 +17235,7 @@ function renderPwRunSummary(s) {
 * Everything else stays suggestion-only. No AST surgery on heuristic
 * findings — false fixes would break the brand promise.
 */
-const ui$3 = plainContext();
+const ui$2 = plainContext();
 const MAX_FILE_BYTES = 524288;
 /**
 * Path-containment guard (adversarial-audit wave; hardened per audit
@@ -17014,7 +17596,7 @@ function fixVerified(edit, fixedText, originalText) {
 }
 function renderFixReport(results, dryRun) {
 	const lines = [];
-	lines.push(sectionHeader(dryRun ? "FIX PLAN (dry-run)" : "FIX REPORT", ui$3));
+	lines.push(sectionHeader(dryRun ? "FIX PLAN (dry-run)" : "FIX REPORT", ui$2));
 	lines.push("");
 	if (results.length === 0) {
 		lines.push("No safe auto-fixes available for these findings.");
@@ -17022,7 +17604,7 @@ function renderFixReport(results, dryRun) {
 		return lines.join("\n");
 	}
 	for (const r of results) {
-		const icon = r.status === "applied" ? okIcon(ui$3) : r.status === "planned" ? "▸" : "✗";
+		const icon = r.status === "applied" ? okIcon(ui$2) : r.status === "planned" ? "▸" : "✗";
 		lines.push(`${icon} [${r.ruleId}] ${r.file}:${r.line} — ${r.description}`);
 	}
 	const applied = results.filter((r) => r.status === "applied").length;
@@ -17038,34 +17620,6 @@ function renderFixReport(results, dryRun) {
 	return lines.join("\n");
 }
 //#endregion
-//#region src/rules/measurement.ts
-/** The rule's declared detector implementation revision (§07). */
-function declaredDetectorRevision(rule) {
-	return rule.detectorRevision ?? 1;
-}
-/**
-* A measurement exists AND was taken against the detector revision the
-* rule declares now. A revision mismatch (stale) does NOT count — §07:
-* stale → provisional → re-measure.
-*/
-function hasValidMeasurement(rule) {
-	const m = MEASURED_FP[rule.id];
-	return m !== void 0 && m.detectorRevision === declaredDetectorRevision(rule);
-}
-/**
-* The tier a rule effectively ships as: its declared tier, or — for the
-* omitted-tier case — the measurement-dependent default (§11.2 Step 2).
-*/
-function effectiveTier(rule) {
-	if (rule.tier !== void 0) return rule.tier;
-	if (hasValidMeasurement(rule)) return "core";
-	return "extended";
-}
-/** The §11.2 Step 2 PROVISIONAL display predicate. */
-function isProvisional(rule) {
-	return effectiveTier(rule) === "extended" && !hasValidMeasurement(rule);
-}
-//#endregion
 //#region src/commands/doctor.ts
 /**
 * `mjolnir doctor` — self-audit of Mjolnir's own rule base.
@@ -17082,7 +17636,7 @@ function isProvisional(rule) {
 *
 * Exit codes reuse the frozen set: 0 healthy · 1 violations · 20 crash.
 */
-const ui$2 = plainContext();
+const ui$1 = plainContext();
 const VALID_ID = RULE_ID_RE;
 function nonHiddenFiles(dir) {
 	if (!existsSync(dir)) return [];
@@ -17281,7 +17835,7 @@ function runDoctorSelfAudit(fixturesRoot) {
 function renderDoctorReport(report) {
 	const lines = [
 		"",
-		sectionHeader("MJÖLNIR — SELF-AUDIT", ui$2),
+		sectionHeader("MJÖLNIR — SELF-AUDIT", ui$1),
 		""
 	];
 	for (const c of report.checks) {
@@ -17359,145 +17913,6 @@ function escapeMdCell(text) {
 	return text.replaceAll("|", "\\|");
 }
 //#endregion
-//#region src/commands/fixture-example.ts
-/**
-* Shared example-fixture selection for `mjolnir explain` (explain.ts)
-* and the generated rule docs (rule-docs.ts) — one chooser so both
-* surfaces always show the same example for the same rule. Extracted
-* after the same bug-audit L9 fix had to be applied to both verbatim
-* copies: duplicated fixture selection drifts, and a drift means
-* `mjolnir explain <ID>` contradicts docs/rules/<ID>.md.
-*/
-/**
-* First (byte-stable) fixture file in a must-fire / must-not-fire
-* directory, or null when the directory is absent or empty.
-*/
-function firstFixtureFile(dir) {
-	if (!existsSync(dir)) return null;
-	const entries = readdirSync(dir).filter((f) => !f.startsWith(".")).sort();
-	return entries.length > 0 ? join(dir, entries[0]) : null;
-}
-//#endregion
-//#region src/commands/explain.ts
-/**
-* `mjolnir explain <RULE-ID>` — implements Plan.md Sprint 1.3
-* (Master-Stabilization-Plan Sprint 5, Task 19).
-*
-* For any registered rule, renders what is wrong, why it matters, the
-* evidence level and confidence behind the verdict, the prescription,
-* and how to verify the fix. This is a presentation layer only — no new
-* detection logic. Every field it prints already exists on RuleMeta or
-* comes from actually running the rule against its own committed
-* must-fire fixture, so the example shown is real detector output, not
-* hand-written prose that can drift from what the rule actually does.
-*/
-const ui$1 = plainContext();
-/**
-* Runs the rule against its own must-fire fixture to get one real,
-* concrete example finding. `fixturesRoot` defaults to this repo's own
-* `tests/fixtures` — explain only has real examples to show when run
-* from (or pointed at) a Mjolnir checkout; degrades honestly
-* (exampleFinding left undefined) otherwise, same as `doctor`.
-*/
-function explainRule(ruleId, fixturesRoot) {
-	const rule = getRule(ruleId);
-	if (!rule) return {
-		ok: false,
-		error: `Unknown rule ID "${ruleId}". Run \`mjolnir rules\` for the full catalog.`
-	};
-	const fixturePath = firstFixtureFile(join(fixturesRoot, ruleId, "must-fire"));
-	if (!fixturePath) return {
-		ok: true,
-		rule
-	};
-	let text;
-	try {
-		text = readFileSync(fixturePath, "utf8").replace(/\r\n/g, "\n");
-	} catch {
-		return {
-			ok: true,
-			rule
-		};
-	}
-	const normalizedPath = fixturePath.replaceAll("\\", "/");
-	let ast;
-	if (rule.appliesTo === "ci-workflows") try {
-		ast = parseWorkflow(text);
-	} catch {
-		return {
-			ok: true,
-			rule
-		};
-	}
-	let findings;
-	try {
-		const parsed = {
-			path: normalizedPath,
-			text,
-			ast
-		};
-		const codeText = computeCodeText(parsed, normalizedPath.endsWith(".py") ? "python" : normalizedPath.endsWith(".java") ? "java" : normalizedPath.endsWith(".cs") ? "csharp" : "typescript");
-		findings = rule.run({
-			...parsed,
-			codeText
-		});
-	} catch {
-		return {
-			ok: true,
-			rule
-		};
-	}
-	const example = findings[0];
-	if (!example) return {
-		ok: true,
-		rule
-	};
-	return {
-		ok: true,
-		rule,
-		exampleFinding: example,
-		exampleFixturePath: fixturePath
-	};
-}
-function renderExplain(result) {
-	if (!result.ok || !result.rule) return `explain failed: ${result.error ?? "unknown error"}`;
-	const r = result.rule;
-	const evidenceLevel = r.evidenceLevel ?? deriveEvidenceLevel(r.findingType, r.confidence);
-	const lines = [];
-	lines.push(sectionHeader(`${r.id} — ${r.title}`, ui$1));
-	lines.push("");
-	lines.push(`Severity:    ${r.severity}`);
-	lines.push(`Confidence:  ${r.confidence}`);
-	lines.push(`Tier:        ${effectiveTier(r)}${isProvisional(r) ? " (PROVISIONAL)" : ""}`);
-	lines.push(`Evidence:    ${evidenceLevel}`);
-	lines.push(`QA impact:   ${QA_IMPACT_LABELS[r.qaImpact]} (${r.qaImpact})`);
-	const measured = MEASURED_FP[r.id];
-	lines.push(measured ? `Measured FP: ${Math.round(measured.fpRate * 100)}% (${measured.n} hand-classified corpus verdicts)` : `Measured FP: not yet measured — this rule ships on assumption (see docs/FP-AUDIT.md)`);
-	if (r.falsePositiveRisk) lines.push(`FP risk:     ${r.falsePositiveRisk} (author estimate)`);
-	if (r.languages?.length) lines.push(`Languages:   ${r.languages.join(", ")}`);
-	if (r.frameworks?.length) lines.push(`Frameworks:  ${r.frameworks.join(", ")}`);
-	lines.push("");
-	if (result.exampleFinding) {
-		const f = result.exampleFinding;
-		lines.push("WHAT WAS FOUND (real detector output, not a mockup)");
-		lines.push(`  ${f.message}`);
-		lines.push("");
-		lines.push("WHY IT MATTERS");
-		lines.push(`  ${f.why}`);
-		lines.push("");
-		lines.push("HOW TO FIX");
-		lines.push(`  ${f.fix}`);
-		lines.push("");
-		lines.push(`Example from this rule's own must-fire fixture: ${result.exampleFixturePath ?? "(unknown path)"}`);
-	} else lines.push("No example available — run this command from a mjolnir checkout (or pass --fixtures-root) so the fixture that proves this rule works can be shown as a real example.");
-	lines.push("");
-	lines.push("HOW TO VERIFY THE FIX");
-	lines.push("  Re-run `mjolnir` on the changed file(s) — this finding should no longer appear. `mjolnir --scope changed` scopes the check to just what you touched.");
-	lines.push("");
-	lines.push(`Docs: mjolnir rules --md   (full catalog, this rule included)`);
-	return lines.join("\n");
-}
-//#endregion
 //#region src/playwright/selector-health-types.ts
 /** Risk weights per locator shape (0 = resilient, higher = brittle). */
 const LOCATOR_RISK = {
@@ -17649,7 +18064,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.12";
+const CLI_VERSION = "0.5.14";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -18513,7 +18928,8 @@ const SUBCOMMANDS = /* @__PURE__ */ new Set([
 	"doctor",
 	"rules",
 	"explain",
-	"doctor:playwright"
+	"doctor:playwright",
+	"mcp"
 ]);
 async function main(argv = process$1.argv.slice(2), io = {
 	out,
@@ -18550,6 +18966,10 @@ async function main(argv = process$1.argv.slice(2), io = {
 	if (argv[0] === "why") return runWhyCommand(argv.slice(1), io);
 	if (argv[0] === "handoff") return runHandoffCommand(argv.slice(1), io);
 	if (argv[0] === "install") return runInstallCommand(argv.slice(1), io);
+	if (argv[0] === "mcp") {
+		await runStdioTransport(process$1.stdin, process$1.stdout);
+		return 0;
+	}
 	if (argv[0] === "help") return runHelpCommand(argv.slice(1), io);
 	if (SUBCOMMANDS.has(argv[0] ?? "")) {
 		err(`mjolnir: incomplete or unknown subcommand "${argv[0]}".`);