mjolnir-qa 0.5.20 → 0.5.24

package/CHANGELOG.md

@@ -9,6 +9,33 @@ Rule behavior changes (new rules, FP-rate changes against the corpus,
 severity changes) are first-class entries here — rule IDs are immutable
 once shipped, so this file is the record of what changed between versions.
 
+## [0.5.24] — 2026-09-08
+
+### Changes since 0.5.23
+
+- L4 ruling: tier-enforcement INCONCLUSIVE without live verdicts (MEASURED_FP = historical artifact only) (#58)
+
+## [0.5.23] — 2026-09-08
+
+### Changes since 0.5.22
+
+- docs(corpus): D14 as amended by owner — re-baseline-per-wave is blocking, PARTIAL repos are tracked debt (never baselines, never a certification gate); zero-PARTIAL is the end state, not the gate
+
+## [0.5.22] — 2026-09-07
+
+### Changes since 0.5.21
+
+- chore: gitignore bench artifacts (machine-local timings + fixture scratch)
+- test(corpus): D14 re-baseline after Wave-1 merges — QA-PW-124 now adapter-gated (configRule metadata), QA-TEST-003/010 surface on repos whose baselines predate the TS project split, corpus regen of partial scans pending quiet-machine rerun
+- chore(qa): eslint-ignore the verbatim QA evidence area (raw probes are committed DATA, certification protocol)
+- chore(qa): commit FINAL-RELEASE certification evidence verbatim (cycle 0, RC 151186b) + lint/format exclusions for raw evidence area (certification plan 1788804968910 protocol)
+
+## [0.5.21] — 2026-09-07
+
+### Changes since 0.5.20
+
+- Integrity layer: category + measurement consistency, measurement census, §27 design pass (Phases 1+4+7) (#56)
+
 ## [0.5.20] — 2026-09-07
 
 ### Changes since 0.5.19

package/README.md

@@ -200,6 +200,7 @@ and you're done. Everything else is optional.
 | `mjolnir badge`                 | shields.io endpoint JSON + snippet                     |
 | `mjolnir rules --md`            | Full rule catalog (JSON or Markdown)                   |
 | `mjolnir doctor`                | Self-audit of Mjölnir's own rule base                  |
+| `mjolnir doctor --json`         | The same self-audit as a machine-readable contract     |
 | `mjolnir create-rule <ID>`      | Scaffold a new rule + fixtures                         |
 | `mjolnir --format mermaid`      | Test-architecture diagram for a PR comment             |
 

package/dist/cli.d.mts

@@ -32,8 +32,17 @@ type EvidenceLevel = (typeof EVIDENCE_ORDER)[number];
  * for the QA engineer's actual job, in their vocabulary.
  */
 type QaImpact = "BLOCKS-RELEASE" | "FLAKY-RISK" | "FALSE-GREEN" | "HYGIENE";
-/** Rule namespaces are frozen public API (§18.4). IDs are never reused. */
-type RuleCategory = "QA-TEST" | "QA-TQUAL" | "QA-PW" | "QA-CI" | "QA-PY" | "QA-ENV" | "QA-JV" | "QA-CS" | "QA-CYP" | "QA-SE" | "QA-WDIO" | "QA-PPTR" | "QA-APM";
+/**
+ * The closed set of rule categories (plan §5.5, certification-audit D6).
+ * Declared FIRST as the single source of truth: the RuleCategory type is
+ * DERIVED from this list (compile-time exhaustiveness — a category added
+ * to the type without the value list, or vice versa, cannot compile).
+ * `--category` values are validated against this list — unknown
+ * categories are a usage error, not a silent no-op. Rule namespaces are
+ * frozen public API (§18.4): IDs are never reused.
+ */
+declare const RULE_CATEGORIES: readonly ["QA-TEST", "QA-TQUAL", "QA-PW", "QA-CI", "QA-PY", "QA-ENV", "QA-JV", "QA-CS", "QA-CYP", "QA-SE", "QA-WDIO", "QA-PPTR", "QA-APM"];
+type RuleCategory = (typeof RULE_CATEGORIES)[number];
 /**
  * Trust levels (Verification Trust Evolution Plan §16): the OVERALL
  * trust a consumer can place in one finding, combining the static
@@ -719,7 +728,7 @@ declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniver
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.20";
+declare const CLI_VERSION = "0.5.24";
 /** A usage-error detail: the offending token, when one exists. */
 interface UsageErrorDetail {
   /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */

package/dist/cli.mjs

@@ -38,16 +38,42 @@ const QA_IMPACT_LABELS = {
 	"FALSE-GREEN": "False-green risk",
 	HYGIENE: "Test hygiene debt"
 };
-/** The closed set of rule categories (plan §5.5). `--category` values
-* are validated against this list — unknown categories are a usage
-* error, not a silent no-op. */
+/**
+* The closed set of rule categories (plan §5.5, certification-audit D6).
+* Declared FIRST as the single source of truth: the RuleCategory type is
+* DERIVED from this list (compile-time exhaustiveness — a category added
+* to the type without the value list, or vice versa, cannot compile).
+* `--category` values are validated against this list — unknown
+* categories are a usage error, not a silent no-op. Rule namespaces are
+* frozen public API (§18.4): IDs are never reused.
+*/
 const RULE_CATEGORIES = [
 	"QA-TEST",
 	"QA-TQUAL",
 	"QA-PW",
-	"QA-CI"
+	"QA-CI",
+	"QA-PY",
+	"QA-ENV",
+	"QA-JV",
+	"QA-CS",
+	"QA-CYP",
+	"QA-SE",
+	"QA-WDIO",
+	"QA-PPTR",
+	"QA-APM"
 ];
 /**
+* Category argument validation shared by every verb accepting
+* `--category` (scan/why/handoff — certification-audit Phase 1.2): the
+* three verbs must never disagree about what a valid category is. A
+* missing value or an unknown value is a usage error (exit 10) at the
+* caller — this helper returns the verdict, the caller renders the
+* rejection.
+*/
+function isValidCategory(value) {
+	return value !== void 0 && RULE_CATEGORIES.includes(value);
+}
+/**
 * Honest default evidence level for a finding (Honesty Core Phase 1).
 * Derivation is deterministic and conservative:
 *   observation → E0 (never proof)
@@ -13264,7 +13290,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.20",
+			version: "0.5.24",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14026,6 +14052,20 @@ async function runWhyCommand(argv, io = {
 	out: (line) => console.log(line),
 	err: (line) => console.error(line)
 }) {
+	const catIdxs = [];
+	argv.forEach((a, i) => {
+		if (a === "--category") catIdxs.push(i + 1);
+	});
+	const categories = [];
+	for (const i of catIdxs) {
+		const value = argv[i];
+		if (!isValidCategory(value)) {
+			io.err(`mjolnir why: unknown --category: ${value === void 0 ? "(missing value)" : value}`);
+			io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+			return 10;
+		}
+		categories.push(value);
+	}
 	const locationToken = argv.find((a) => !a.startsWith("-"));
 	if (!locationToken) {
 		io.err("Usage: mjolnir why <file>:<line> [--json <mjolnir.json>]");
@@ -14038,7 +14078,10 @@ async function runWhyCommand(argv, io = {
 	}
 	const jsonIdx = argv.indexOf("--json");
 	const reportPath = jsonIdx !== -1 ? argv[jsonIdx + 1] : void 0;
-	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && (jsonIdx === -1 || i !== jsonIdx + 1));
+	const valuePositions = /* @__PURE__ */ new Set();
+	if (jsonIdx !== -1) valuePositions.add(jsonIdx + 1);
+	for (const i of catIdxs) valuePositions.add(i);
+	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && !valuePositions.has(i));
 	const target = targetIdx !== -1 ? argv[targetIdx] : ".";
 	let result;
 	if (reportPath !== void 0) {
@@ -14074,11 +14117,6 @@ async function runWhyCommand(argv, io = {
 		}
 	}
 	const match = explainAt(result.findings, location.file, location.line);
-	const catIdxs = [];
-	argv.forEach((a, i) => {
-		if (a === "--category") catIdxs.push(i + 1);
-	});
-	const categories = catIdxs.map((i) => argv[i]).filter((c) => c !== void 0);
 	const filtered = categories.length > 0 ? match.findings.filter((f) => categories.includes(f.category)) : match.findings;
 	io.out(renderWhy({
 		...match,
@@ -14088,6 +14126,28 @@ async function runWhyCommand(argv, io = {
 }
 //#endregion
 //#region src/commands/handoff.ts
+/**
+* `mjolnir handoff [mjolnir.json]` — the deterministic fix-handoff
+* artifact (agent-handoff plan M3).
+*
+* Reads a saved `--json` report (shared loader, report-io.ts) and
+* renders a self-contained Markdown remediation plan an agent (or a
+* human) can execute offline. Every instruction is derived from
+* Mjölnir's own rule metadata — the generator produces INSTRUCTIONS,
+* never executable commands, and no prompt text is fetched or copied
+* from any external source.
+*
+* The artifact embeds the formal verification contract (plan §5.3):
+* what was detected, what should change, what justifies it (evidence
+* boundary per level), what to re-run, what counts as verified
+* (TARGET_RESOLVED / TARGET_REMAINS / NEW_FINDINGS_INTRODUCED /
+* VERIFICATION_NOT_RUN, correlated via the fingerprint rule), and the
+* standing caveat that a clean `--scope changed` run verifies the
+* changed-scope surface only — not that the repository is clean.
+*
+* Exit codes (frozen contract): 0 on success · 10 missing file ·
+* 2 unreadable/invalid JSON.
+*/
 const OCCURRENCE_CAP = 25;
 const EVIDENCE_BOUNDARY = {
 	E2: "The detector's evidence is deterministic for this pattern. Check the location, then apply the prescribed fix — the finding is a deterministic defect at its boundary.",
@@ -14317,6 +14377,11 @@ function runHandoffCommand(argv, io = {
 				}));
 				return 10;
 			}
+			if (a === "--category" && !isValidCategory(val)) {
+				io.err(`mjolnir handoff: unknown --category: ${val}`);
+				io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+				return 10;
+			}
 			i++;
 			continue;
 		}
@@ -17930,6 +17995,25 @@ function checkEvidenceHonesty(rules = RULES) {
 	return check("evidence-honesty", ok ? "pass" : "fail", details);
 }
 /**
+* Measurement census (Phase 4.3): measured = rules with a valid
+* MEASURED_FP entry; unmeasured = the rest; quarantine = measured rules
+* whose effective tier is quarantine. One function, used by the doctor
+* report AND the JSON contract — a single reproducible answer.
+*/
+function measurementBlock(rules = RULES) {
+	const measured = rules.filter((r) => {
+		const m = MEASURED_FP[r.id];
+		return m !== void 0 && m.detectorRevision === declaredDetectorRevision(r);
+	});
+	const quarantine = measured.filter((r) => effectiveTier(r) === "quarantine");
+	return {
+		measured: measured.length,
+		unmeasured: rules.length - measured.length,
+		total: rules.length,
+		quarantine: quarantine.length
+	};
+}
+/**
 * Check 5 (Phase 4 — Tempering Plan, ratcheted per audit H-2):
 * tier enforcement. Core-tier rules must have a measured FP rate
 * (n ≥ 10 classified verdicts in tests/corpus/verdicts/) at a matching
@@ -17941,14 +18025,16 @@ function checkEvidenceHonesty(rules = RULES) {
 */
 function checkTierEnforcement(verdictsDir, rules = RULES) {
 	const details = [];
+	if (!existsSync(verdictsDir)) return check("tier-enforcement", "inconclusive", ["INCONCLUSIVE: live verdicts unavailable (tests/corpus/verdicts missing — installed package) — tier claims cannot be proven without live evidence; MEASURED_FP is a historical artifact and does not substitute (owner ruling 2026-09-08, L4)"]);
 	const classifiedPerRule = /* @__PURE__ */ new Map();
 	const byId = new Map(rules.map((r) => [r.id, r]));
 	for (const [id, m] of Object.entries(MEASURED_FP)) {
 		const rule = byId.get(id);
 		if (rule && m.detectorRevision === declaredDetectorRevision(rule)) classifiedPerRule.set(id, m.n);
 	}
+	let live;
 	try {
-		const live = /* @__PURE__ */ new Map();
+		live = /* @__PURE__ */ new Map();
 		const files = readdirSync(verdictsDir).filter((f) => f.endsWith(".jsonl"));
 		for (const f of files) {
 			const lines = readFileSync(join(verdictsDir, f), "utf8").split("\n").filter((l) => l.trim().length > 0);
@@ -17957,8 +18043,10 @@ function checkTierEnforcement(verdictsDir, rules = RULES) {
 				if (entry.verdict === "TP" || entry.verdict === "FP") live.set(entry.ruleId, (live.get(entry.ruleId) ?? 0) + 1);
 			} catch {}
 		}
-		if (live.size > 0) for (const [id, n] of live) classifiedPerRule.set(id, n);
-	} catch {}
+	} catch (e) {
+		return check("tier-enforcement", "inconclusive", [`INCONCLUSIVE: live verdicts unreadable — ${errorText(e)} (owner ruling 2026-09-08, L4)`]);
+	}
+	if (live.size > 0) for (const [id, n] of live) classifiedPerRule.set(id, n);
 	const coreRules = rules.filter((r) => effectiveTier(r) === "core");
 	for (const r of coreRules) {
 		const n = classifiedPerRule.get(r.id) ?? 0;
@@ -18117,8 +18205,90 @@ function checkRevisionIntegrity(repoRoot, rules = RULES) {
 	details.push(`${rules.length} rules attested: source identity and declared revision match the manifest (check A + check B, G4)`);
 	return check("revision-integrity", "pass", details);
 }
+/**
+* Check 8 (certification-audit Phase 1.4, D6 — HARD-BLOCKING):
+* category-integrity. Every registry rule's category must be a member of
+* the closed RULE_CATEGORIES set (compile-time exhaustive via the D6
+* derivation, so this check is the runtime backstop for values arriving
+* from external rule sources), and no two rules may collide on an id.
+* Registry ids are already unique-checked by registry-sanity; this check
+* owns the category dimension.
+*/
+function checkCategoryIntegrity(rules = RULES) {
+	const details = [];
+	const known = RULE_CATEGORIES;
+	const unknown = rules.filter((r) => !known.includes(r.category));
+	for (const r of unknown) details.push(`${r.id}: category "${r.category}" is not in RULE_CATEGORIES — registries may not invent categories (D6)`);
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const r of rules) byCategory.set(r.category, (byCategory.get(r.category) ?? 0) + 1);
+	return check("category-integrity", unknown.length === 0 ? "pass" : "fail", [`${byCategory.size} categories in use across ${rules.length} rules (closed set: ${RULE_CATEGORIES.length})`, ...details]);
+}
+/**
+* Check 10 (certification-audit Phase 4.1, D7 — HARD-BLOCKING):
+* measurement-consistency. Three invariants over the measurement surface:
+*   (1) every MEASURED_FP entry's `n` equals the LIVE classified verdict
+*       count (TP+FP rows in tests/corpus/verdicts/*.jsonl) — a snapshot
+*       that drifted from the corpus is a lie about evidence;
+*   (2) MEASURED_FP's detectorRevision equals the sidecar's
+*       (tests/corpus/detector-revisions.json) — a measurement taken
+*       against a different detector revision than attested is stale;
+*   (3) every sidecar entry maps to a registered rule.
+* Mismatch → FAIL (certification-critical).
+*/
+function checkMeasurementConsistency(verdictsDir, sidecarPath, rules = RULES, measuredFp = MEASURED_FP) {
+	const details = [];
+	const failures = [];
+	const registered = new Map(rules.map((r) => [r.id, r]));
+	const liveCounts = /* @__PURE__ */ new Map();
+	if (existsSync(verdictsDir)) for (const f of readdirSync(verdictsDir)) {
+		if (!f.endsWith(".jsonl")) continue;
+		const lines = readFileSync(join(verdictsDir, f), "utf8").split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed.length === 0) continue;
+			let row;
+			try {
+				row = JSON.parse(trimmed);
+			} catch {
+				failures.push(`${f}: unparseable verdict row (corpus integrity)`);
+				continue;
+			}
+			if (row.ruleId === void 0) continue;
+			if (row.verdict === "TP" || row.verdict === "FP") liveCounts.set(row.ruleId, (liveCounts.get(row.ruleId) ?? 0) + 1);
+		}
+	}
+	else return check("measurement-consistency", "inconclusive", ["INCONCLUSIVE: verdicts directory missing — measurement consistency cannot be evaluated (certification-critical: never renders as pass)"]);
+	let sidecar = {};
+	if (existsSync(sidecarPath)) try {
+		sidecar = JSON.parse(readFileSync(sidecarPath, "utf8"));
+	} catch (e) {
+		failures.push(`sidecar unreadable/malformed: ${errorText(e)} — regenerate the measurement artifacts`);
+	}
+	else {
+		const needsSidecar = Object.keys(measuredFp).filter((id) => measuredFp[id]?.detectorRevision !== 1);
+		if (needsSidecar.length > 0) return check("measurement-consistency", "inconclusive", [`INCONCLUSIVE: sidecar tests/corpus/detector-revisions.json missing but ${needsSidecar.length} measured rule(s) declare revisions — cannot verify measurement freshness`]);
+	}
+	for (const [id, m] of Object.entries(measuredFp)) {
+		const side = sidecar[id];
+		if (side !== void 0 && side.detectorRevision !== void 0) {
+			if (side.detectorRevision !== m.detectorRevision) failures.push(`${id}: MEASURED_FP revision ${m.detectorRevision} ≠ sidecar ${side.detectorRevision} — the measurement is stale (§07: re-measure or bump)`);
+		}
+		const live = liveCounts.get(id);
+		if (live !== void 0 && live !== m.n) failures.push(`${id}: MEASURED_FP.n=${m.n} but the live corpus has ${live} classified verdict(s) — regenerate (npm run fp-audit:generate)`);
+		if (live === void 0 && m.n > 0) failures.push(`${id}: MEASURED_FP.n=${m.n} but no classified verdicts exist in the live corpus`);
+	}
+	for (const id of Object.keys(sidecar)) if (!registered.has(id)) failures.push(`${id}: sidecar entry for an unregistered rule — remove it from tests/corpus/detector-revisions.json`);
+	if (failures.length > 0) {
+		details.push(...failures);
+		return check("measurement-consistency", "fail", details);
+	}
+	const block = measurementBlock(rules);
+	details.push(`${block.measured} measured / ${block.unmeasured} unmeasured / ${block.total} total (${block.quarantine} quarantine) — MEASURED_FP, live verdicts and sidecar revisions agree`);
+	return check("measurement-consistency", "pass", details);
+}
 function runDoctorSelfAudit(fixturesRoot) {
 	const verdictsDir = join(fixturesRoot, "..", "corpus", "verdicts");
+	const repoRoot = join(fixturesRoot, "..", "..");
 	const checks = [
 		checkFixtureFirewall(fixturesRoot),
 		checkRegistry(),
@@ -18127,12 +18297,15 @@ function runDoctorSelfAudit(fixturesRoot) {
 		checkTierEnforcement(verdictsDir),
 		checkAntiCreep(),
 		checkQuarantineEnforcement(),
+		checkCategoryIntegrity(),
 		checkFixtureIntegrity(fixturesRoot),
-		checkRevisionIntegrity(join(fixturesRoot, "..", ".."))
+		checkRevisionIntegrity(repoRoot),
+		checkMeasurementConsistency(verdictsDir, join(repoRoot, "tests", "corpus", "detector-revisions.json"))
 	];
 	return {
 		checks,
-		healthy: checks.every((c) => c.status === "pass")
+		healthy: checks.every((c) => c.status === "pass"),
+		measurement: measurementBlock()
 	};
 }
 function renderDoctorReport(report) {
@@ -18181,7 +18354,8 @@ function doctorReportJson(report, opts = {}) {
 		schema: DOCTOR_REPORT_SCHEMA,
 		healthy: report.healthy,
 		summary,
-		checks
+		checks,
+		measurement: report.measurement
 	};
 }
 //#endregion
@@ -18449,7 +18623,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.20";
+const CLI_VERSION = "0.5.24";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",

package/dist/mcp/stdio.mjs

@@ -37,16 +37,42 @@ const QA_IMPACT_LABELS = {
 	"FALSE-GREEN": "False-green risk",
 	HYGIENE: "Test hygiene debt"
 };
-/** The closed set of rule categories (plan §5.5). `--category` values
-* are validated against this list — unknown categories are a usage
-* error, not a silent no-op. */
+/**
+* The closed set of rule categories (plan §5.5, certification-audit D6).
+* Declared FIRST as the single source of truth: the RuleCategory type is
+* DERIVED from this list (compile-time exhaustiveness — a category added
+* to the type without the value list, or vice versa, cannot compile).
+* `--category` values are validated against this list — unknown
+* categories are a usage error, not a silent no-op. Rule namespaces are
+* frozen public API (§18.4): IDs are never reused.
+*/
 const RULE_CATEGORIES = [
 	"QA-TEST",
 	"QA-TQUAL",
 	"QA-PW",
-	"QA-CI"
+	"QA-CI",
+	"QA-PY",
+	"QA-ENV",
+	"QA-JV",
+	"QA-CS",
+	"QA-CYP",
+	"QA-SE",
+	"QA-WDIO",
+	"QA-PPTR",
+	"QA-APM"
 ];
 /**
+* Category argument validation shared by every verb accepting
+* `--category` (scan/why/handoff — certification-audit Phase 1.2): the
+* three verbs must never disagree about what a valid category is. A
+* missing value or an unknown value is a usage error (exit 10) at the
+* caller — this helper returns the verdict, the caller renders the
+* rejection.
+*/
+function isValidCategory(value) {
+	return value !== void 0 && RULE_CATEGORIES.includes(value);
+}
+/**
 * Honest default evidence level for a finding (Honesty Core Phase 1).
 * Derivation is deterministic and conservative:
 *   observation → E0 (never proof)
@@ -13263,7 +13289,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.20",
+			version: "0.5.24",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14025,6 +14051,20 @@ async function runWhyCommand(argv, io = {
 	out: (line) => console.log(line),
 	err: (line) => console.error(line)
 }) {
+	const catIdxs = [];
+	argv.forEach((a, i) => {
+		if (a === "--category") catIdxs.push(i + 1);
+	});
+	const categories = [];
+	for (const i of catIdxs) {
+		const value = argv[i];
+		if (!isValidCategory(value)) {
+			io.err(`mjolnir why: unknown --category: ${value === void 0 ? "(missing value)" : value}`);
+			io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+			return 10;
+		}
+		categories.push(value);
+	}
 	const locationToken = argv.find((a) => !a.startsWith("-"));
 	if (!locationToken) {
 		io.err("Usage: mjolnir why <file>:<line> [--json <mjolnir.json>]");
@@ -14037,7 +14077,10 @@ async function runWhyCommand(argv, io = {
 	}
 	const jsonIdx = argv.indexOf("--json");
 	const reportPath = jsonIdx !== -1 ? argv[jsonIdx + 1] : void 0;
-	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && (jsonIdx === -1 || i !== jsonIdx + 1));
+	const valuePositions = /* @__PURE__ */ new Set();
+	if (jsonIdx !== -1) valuePositions.add(jsonIdx + 1);
+	for (const i of catIdxs) valuePositions.add(i);
+	const targetIdx = argv.findIndex((a, i) => !a.startsWith("-") && i !== 0 && !valuePositions.has(i));
 	const target = targetIdx !== -1 ? argv[targetIdx] : ".";
 	let result;
 	if (reportPath !== void 0) {
@@ -14073,11 +14116,6 @@ async function runWhyCommand(argv, io = {
 		}
 	}
 	const match = explainAt(result.findings, location.file, location.line);
-	const catIdxs = [];
-	argv.forEach((a, i) => {
-		if (a === "--category") catIdxs.push(i + 1);
-	});
-	const categories = catIdxs.map((i) => argv[i]).filter((c) => c !== void 0);
 	const filtered = categories.length > 0 ? match.findings.filter((f) => categories.includes(f.category)) : match.findings;
 	io.out(renderWhy({
 		...match,
@@ -14087,6 +14125,28 @@ async function runWhyCommand(argv, io = {
 }
 //#endregion
 //#region src/commands/handoff.ts
+/**
+* `mjolnir handoff [mjolnir.json]` — the deterministic fix-handoff
+* artifact (agent-handoff plan M3).
+*
+* Reads a saved `--json` report (shared loader, report-io.ts) and
+* renders a self-contained Markdown remediation plan an agent (or a
+* human) can execute offline. Every instruction is derived from
+* Mjölnir's own rule metadata — the generator produces INSTRUCTIONS,
+* never executable commands, and no prompt text is fetched or copied
+* from any external source.
+*
+* The artifact embeds the formal verification contract (plan §5.3):
+* what was detected, what should change, what justifies it (evidence
+* boundary per level), what to re-run, what counts as verified
+* (TARGET_RESOLVED / TARGET_REMAINS / NEW_FINDINGS_INTRODUCED /
+* VERIFICATION_NOT_RUN, correlated via the fingerprint rule), and the
+* standing caveat that a clean `--scope changed` run verifies the
+* changed-scope surface only — not that the repository is clean.
+*
+* Exit codes (frozen contract): 0 on success · 10 missing file ·
+* 2 unreadable/invalid JSON.
+*/
 const OCCURRENCE_CAP = 25;
 const EVIDENCE_BOUNDARY = {
 	E2: "The detector's evidence is deterministic for this pattern. Check the location, then apply the prescribed fix — the finding is a deterministic defect at its boundary.",
@@ -14316,6 +14376,11 @@ function runHandoffCommand(argv, io = {
 				}));
 				return 10;
 			}
+			if (a === "--category" && !isValidCategory(val)) {
+				io.err(`mjolnir handoff: unknown --category: ${val}`);
+				io.err(`  Valid categories: ${RULE_CATEGORIES.join(", ")}`);
+				return 10;
+			}
 			i++;
 			continue;
 		}
@@ -17412,6 +17477,25 @@ function checkEvidenceHonesty(rules = RULES) {
 	return check("evidence-honesty", ok ? "pass" : "fail", details);
 }
 /**
+* Measurement census (Phase 4.3): measured = rules with a valid
+* MEASURED_FP entry; unmeasured = the rest; quarantine = measured rules
+* whose effective tier is quarantine. One function, used by the doctor
+* report AND the JSON contract — a single reproducible answer.
+*/
+function measurementBlock(rules = RULES) {
+	const measured = rules.filter((r) => {
+		const m = MEASURED_FP[r.id];
+		return m !== void 0 && m.detectorRevision === declaredDetectorRevision(r);
+	});
+	const quarantine = measured.filter((r) => effectiveTier(r) === "quarantine");
+	return {
+		measured: measured.length,
+		unmeasured: rules.length - measured.length,
+		total: rules.length,
+		quarantine: quarantine.length
+	};
+}
+/**
 * Check 5 (Phase 4 — Tempering Plan, ratcheted per audit H-2):
 * tier enforcement. Core-tier rules must have a measured FP rate
 * (n ≥ 10 classified verdicts in tests/corpus/verdicts/) at a matching
@@ -17423,14 +17507,16 @@ function checkEvidenceHonesty(rules = RULES) {
 */
 function checkTierEnforcement(verdictsDir, rules = RULES) {
 	const details = [];
+	if (!existsSync(verdictsDir)) return check("tier-enforcement", "inconclusive", ["INCONCLUSIVE: live verdicts unavailable (tests/corpus/verdicts missing — installed package) — tier claims cannot be proven without live evidence; MEASURED_FP is a historical artifact and does not substitute (owner ruling 2026-09-08, L4)"]);
 	const classifiedPerRule = /* @__PURE__ */ new Map();
 	const byId = new Map(rules.map((r) => [r.id, r]));
 	for (const [id, m] of Object.entries(MEASURED_FP)) {
 		const rule = byId.get(id);
 		if (rule && m.detectorRevision === declaredDetectorRevision(rule)) classifiedPerRule.set(id, m.n);
 	}
+	let live;
 	try {
-		const live = /* @__PURE__ */ new Map();
+		live = /* @__PURE__ */ new Map();
 		const files = readdirSync(verdictsDir).filter((f) => f.endsWith(".jsonl"));
 		for (const f of files) {
 			const lines = readFileSync(join(verdictsDir, f), "utf8").split("\n").filter((l) => l.trim().length > 0);
@@ -17439,8 +17525,10 @@ function checkTierEnforcement(verdictsDir, rules = RULES) {
 				if (entry.verdict === "TP" || entry.verdict === "FP") live.set(entry.ruleId, (live.get(entry.ruleId) ?? 0) + 1);
 			} catch {}
 		}
-		if (live.size > 0) for (const [id, n] of live) classifiedPerRule.set(id, n);
-	} catch {}
+	} catch (e) {
+		return check("tier-enforcement", "inconclusive", [`INCONCLUSIVE: live verdicts unreadable — ${errorText(e)} (owner ruling 2026-09-08, L4)`]);
+	}
+	if (live.size > 0) for (const [id, n] of live) classifiedPerRule.set(id, n);
 	const coreRules = rules.filter((r) => effectiveTier(r) === "core");
 	for (const r of coreRules) {
 		const n = classifiedPerRule.get(r.id) ?? 0;
@@ -17599,8 +17687,90 @@ function checkRevisionIntegrity(repoRoot, rules = RULES) {
 	details.push(`${rules.length} rules attested: source identity and declared revision match the manifest (check A + check B, G4)`);
 	return check("revision-integrity", "pass", details);
 }
+/**
+* Check 8 (certification-audit Phase 1.4, D6 — HARD-BLOCKING):
+* category-integrity. Every registry rule's category must be a member of
+* the closed RULE_CATEGORIES set (compile-time exhaustive via the D6
+* derivation, so this check is the runtime backstop for values arriving
+* from external rule sources), and no two rules may collide on an id.
+* Registry ids are already unique-checked by registry-sanity; this check
+* owns the category dimension.
+*/
+function checkCategoryIntegrity(rules = RULES) {
+	const details = [];
+	const known = RULE_CATEGORIES;
+	const unknown = rules.filter((r) => !known.includes(r.category));
+	for (const r of unknown) details.push(`${r.id}: category "${r.category}" is not in RULE_CATEGORIES — registries may not invent categories (D6)`);
+	const byCategory = /* @__PURE__ */ new Map();
+	for (const r of rules) byCategory.set(r.category, (byCategory.get(r.category) ?? 0) + 1);
+	return check("category-integrity", unknown.length === 0 ? "pass" : "fail", [`${byCategory.size} categories in use across ${rules.length} rules (closed set: ${RULE_CATEGORIES.length})`, ...details]);
+}
+/**
+* Check 10 (certification-audit Phase 4.1, D7 — HARD-BLOCKING):
+* measurement-consistency. Three invariants over the measurement surface:
+*   (1) every MEASURED_FP entry's `n` equals the LIVE classified verdict
+*       count (TP+FP rows in tests/corpus/verdicts/*.jsonl) — a snapshot
+*       that drifted from the corpus is a lie about evidence;
+*   (2) MEASURED_FP's detectorRevision equals the sidecar's
+*       (tests/corpus/detector-revisions.json) — a measurement taken
+*       against a different detector revision than attested is stale;
+*   (3) every sidecar entry maps to a registered rule.
+* Mismatch → FAIL (certification-critical).
+*/
+function checkMeasurementConsistency(verdictsDir, sidecarPath, rules = RULES, measuredFp = MEASURED_FP) {
+	const details = [];
+	const failures = [];
+	const registered = new Map(rules.map((r) => [r.id, r]));
+	const liveCounts = /* @__PURE__ */ new Map();
+	if (existsSync(verdictsDir)) for (const f of readdirSync(verdictsDir)) {
+		if (!f.endsWith(".jsonl")) continue;
+		const lines = readFileSync(join(verdictsDir, f), "utf8").split("\n");
+		for (const line of lines) {
+			const trimmed = line.trim();
+			if (trimmed.length === 0) continue;
+			let row;
+			try {
+				row = JSON.parse(trimmed);
+			} catch {
+				failures.push(`${f}: unparseable verdict row (corpus integrity)`);
+				continue;
+			}
+			if (row.ruleId === void 0) continue;
+			if (row.verdict === "TP" || row.verdict === "FP") liveCounts.set(row.ruleId, (liveCounts.get(row.ruleId) ?? 0) + 1);
+		}
+	}
+	else return check("measurement-consistency", "inconclusive", ["INCONCLUSIVE: verdicts directory missing — measurement consistency cannot be evaluated (certification-critical: never renders as pass)"]);
+	let sidecar = {};
+	if (existsSync(sidecarPath)) try {
+		sidecar = JSON.parse(readFileSync(sidecarPath, "utf8"));
+	} catch (e) {
+		failures.push(`sidecar unreadable/malformed: ${errorText(e)} — regenerate the measurement artifacts`);
+	}
+	else {
+		const needsSidecar = Object.keys(measuredFp).filter((id) => measuredFp[id]?.detectorRevision !== 1);
+		if (needsSidecar.length > 0) return check("measurement-consistency", "inconclusive", [`INCONCLUSIVE: sidecar tests/corpus/detector-revisions.json missing but ${needsSidecar.length} measured rule(s) declare revisions — cannot verify measurement freshness`]);
+	}
+	for (const [id, m] of Object.entries(measuredFp)) {
+		const side = sidecar[id];
+		if (side !== void 0 && side.detectorRevision !== void 0) {
+			if (side.detectorRevision !== m.detectorRevision) failures.push(`${id}: MEASURED_FP revision ${m.detectorRevision} ≠ sidecar ${side.detectorRevision} — the measurement is stale (§07: re-measure or bump)`);
+		}
+		const live = liveCounts.get(id);
+		if (live !== void 0 && live !== m.n) failures.push(`${id}: MEASURED_FP.n=${m.n} but the live corpus has ${live} classified verdict(s) — regenerate (npm run fp-audit:generate)`);
+		if (live === void 0 && m.n > 0) failures.push(`${id}: MEASURED_FP.n=${m.n} but no classified verdicts exist in the live corpus`);
+	}
+	for (const id of Object.keys(sidecar)) if (!registered.has(id)) failures.push(`${id}: sidecar entry for an unregistered rule — remove it from tests/corpus/detector-revisions.json`);
+	if (failures.length > 0) {
+		details.push(...failures);
+		return check("measurement-consistency", "fail", details);
+	}
+	const block = measurementBlock(rules);
+	details.push(`${block.measured} measured / ${block.unmeasured} unmeasured / ${block.total} total (${block.quarantine} quarantine) — MEASURED_FP, live verdicts and sidecar revisions agree`);
+	return check("measurement-consistency", "pass", details);
+}
 function runDoctorSelfAudit(fixturesRoot) {
 	const verdictsDir = join(fixturesRoot, "..", "corpus", "verdicts");
+	const repoRoot = join(fixturesRoot, "..", "..");
 	const checks = [
 		checkFixtureFirewall(fixturesRoot),
 		checkRegistry(),
@@ -17609,12 +17779,15 @@ function runDoctorSelfAudit(fixturesRoot) {
 		checkTierEnforcement(verdictsDir),
 		checkAntiCreep(),
 		checkQuarantineEnforcement(),
+		checkCategoryIntegrity(),
 		checkFixtureIntegrity(fixturesRoot),
-		checkRevisionIntegrity(join(fixturesRoot, "..", ".."))
+		checkRevisionIntegrity(repoRoot),
+		checkMeasurementConsistency(verdictsDir, join(repoRoot, "tests", "corpus", "detector-revisions.json"))
 	];
 	return {
 		checks,
-		healthy: checks.every((c) => c.status === "pass")
+		healthy: checks.every((c) => c.status === "pass"),
+		measurement: measurementBlock()
 	};
 }
 function renderDoctorReport(report) {
@@ -17663,7 +17836,8 @@ function doctorReportJson(report, opts = {}) {
 		schema: DOCTOR_REPORT_SCHEMA,
 		healthy: report.healthy,
 		summary,
-		checks
+		checks,
+		measurement: report.measurement
 	};
 }
 //#endregion
@@ -18085,7 +18259,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.20";
+const CLI_VERSION = "0.5.24";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",

package/package.json

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