mjolnir-qa 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -9,6 +9,71 @@ 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.4] — 2026-09-06
+
+### Agent Handoff + Minimized Reporting (plan 1788599400000)
+
+### Added
+
+- **`mjolnir why <file>:<line>`** — occurrence-level evidence query
+  (informational, NOT a gate): exact file+line match, severity icon,
+  message/why/fix, evidence level, trust level, measured FP rate
+  (or the honest "ships on assumption"), runtime corroboration when
+  present, and the suppression contract (reason required, 90-day
+  expiry). Saved-report mode (`--json <mjolnir.json>`) is
+  authoritative; live scan runs otherwise. Exit 0 match / 1 no match.
+- **`mjolnir handoff [mjolnir.json]`** — the deterministic fix-handoff
+  artifact: per-rule remediation sections (what is wrong / why
+  Mjölnir believes it / evidence boundary by level / occurrences
+  capped at 25 / fix / constraints / occurrences list), a per-rule
+  fenced copy block and a one-shot handoff prompt, and the formal
+  verification contract (TARGET_RESOLVED / TARGET_REMAINS /
+  NEW_FINDINGS_INTRODUCED / VERIFICATION_NOT_RUN, correlated by the
+  fingerprint ruleId+file+message; the standing caveat that a clean
+  `--scope changed` run verifies the changed surface only). Generated
+  solely from Mjölnir's own rule metadata — offline, deterministic,
+  escapeMarkdown'd. Zero findings → exit 0, non-actionable clean
+  artifact with no prompt. `--category`/`--rules` are presentation
+  filters.
+- **`mjolnir install`** — installs the agent instruction surfaces
+  (`.claude/commands/mjolnir.md`, `.kilo/command/mjolnir.md`,
+  `.cursor/rules/mjolnir.mdc`, marker-appended `AGENTS.md`): the
+  version-pinned trust loop brief (scan `--scope changed` before
+  finishing, never suppress to green, report files changed and checks
+  not run). `--staged-hook` adds a NON-BLOCKING pre-commit hook
+  (`mjolnir --staged --blocking warning`, reusing `.husky`/
+  `core.hooksPath` when present). Marker-based idempotency;
+  `--dry-run` writes nothing; refusal (exit 10) before overwriting
+  any non-Mjölnir file; `--force` overwrites only Mjölnir-marked
+  files; never @latest.
+- **`--score`** — prints only the numeric score (`unknown` when no
+  tests exist — never a fake 0); pure rendering flag, exit code
+  unchanged; stderr note when --json was also requested.
+- **`--category <cat>`** (repeatable) — presentation filter on the
+  terminal findings display (and handoff/why): NEVER filters the
+  scan, the JSON/SARIF output, or the score; the terminal prints
+  `filtered view: N of M findings shown; score reflects the full
+scan`. Unknown categories are a usage error (exit 10).
+- **`--staged`** — scan-surface restriction: intersects discovered
+  test files with the git staged list; score reflects the staged
+  surface and is labeled as such (`staged surface: N file(s)`); not a
+  git repo → honest degraded fallback; empty staged set → exit 0.
+- **`--blocking error|warning|none`** — exit-status override only:
+  maps onto the existing gate model (none→advisory, error→errors
+  block, warning→errors+warnings block). Detection and rendering are
+  identical under all three values; E0 findings never block; partial
+  scans stay exit 2.
+- **`fixGroupId`** (additive JSON field): the stable semantic identity
+  of a remediation group — intentionally distinct from `ruleId`
+  (which identifies the detector). Current strategy: one rule = one
+  group, so fixGroupId equals ruleId today; consumers must not rely
+  on that permanently.
+
+### Changed
+
+- help registry gained `why`, `handoff`, `install` and the new flags;
+  site/reference/cli.md documents the handoff trust model.
+
 ## [0.5.3] — 2026-09-05
 
 ### Terminal + CI UX Overhaul (plan 1788579907109)

package/dist/cli.d.mts

@@ -128,6 +128,21 @@ interface Finding {
   /** How to fix — concrete action. */
   fix: string;
   docsUrl?: string;
+  /**
+   * Stable semantic identity of a remediation group: findings that can
+   * be reasoned about and potentially remediated as one root-cause unit
+   * (agent-handoff plan §5.1). This is intentionally a DIFFERENT
+   * concept from `ruleId` (which identifies the detector/rule).
+   *
+   * Current implementation strategy: fixGroupId = ruleId, because each
+   * rule currently represents one remediation group. Future rules may
+   * emit multiple findings belonging to one fix group, or multiple
+   * remediation groups. Consumers MUST NOT rely on
+   * fixGroupId === ruleId permanently.
+   *
+   * Additive within schemaVersion 1.
+   */
+  fixGroupId?: string;
 }
 interface DimensionScore {
   category: RuleCategory;
@@ -147,6 +162,16 @@ interface ScanResult {
   /** Present when --scope changed was requested. */
   scope?: "all" | "changed";
   scopeDegraded?: string;
+  /**
+   * Present when --staged was requested (agent-handoff plan §5.7):
+   * the scan surface was restricted to git staged files, and `files`
+   * is how many survived the intersection. The score reflects THAT
+   * surface — never present it as a full-repo score. Additive within
+   * schemaVersion 1.
+   */
+  staged?: {
+    files: number;
+  };
   /** Detected test frameworks (0.2). Empty + unknown=true when undetectable. */
   frameworks: string[];
   frameworkDetectionUnknown: boolean;
@@ -491,7 +516,7 @@ interface UniversalRule {
  * `scripts/sync-sarif-version.cjs` on release and guarded by
  * `tests/version-consistency.spec.ts` locally.
  */
-declare const CLI_VERSION = "0.5.3";
+declare const CLI_VERSION = "0.5.4";
 declare function buildUniversalRules(root: string, strict?: boolean): Promise<{
   rules: UniversalRule[];
   pluginErrors: string[];
@@ -536,6 +561,33 @@ interface CliArgs {
    * and auto-disabled in CI/machine formats; this flag is the manual off.
    */
   noProgress?: boolean;
+  /**
+   * --category <cat> (repeatable): presentation filter — narrows the
+   * TERMINAL findings display (and handoff/why output) to the given
+   * rule categories. NEVER filters the scan, the JSON/SARIF output,
+   * or the score (agent-handoff plan §5.5).
+   */
+  categories?: RuleCategory[];
+  /**
+   * --score: print only the numeric score (or `unknown` when the repo
+   * has no tests) instead of the full report. Pure rendering flag:
+   * scan semantics and exit codes are unchanged (plan §5.6).
+   */
+  scoreOnly?: boolean;
+  /**
+   * --staged: scan-surface restriction (plan §5.7) — intersect the
+   * discovered test files with the git staged file list. Does NOT
+   * change rule semantics; score implications come only from the
+   * narrowed surface (labeled as such in the report).
+   */
+  staged?: boolean;
+  /**
+   * --blocking error|warning|none (plan §5.8): invocation-level gate
+   * override. Controls PROCESS EXIT BEHAVIOR ONLY via the existing
+   * exitForFindings mechanism — detection, rendering, JSON and score
+   * are identical under all three values. Overrides config.gate.
+   */
+  blocking?: "error" | "warning" | "none";
 }
 /** A usage-error detail: the offending token, when one exists. */
 interface UsageErrorDetail {

package/dist/cli.mjs

@@ -25,6 +25,15 @@ 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. */
+const RULE_CATEGORIES = [
+	"QA-TEST",
+	"QA-TQUAL",
+	"QA-PW",
+	"QA-CI"
+];
 /**
 * Honest default evidence level for a finding (Honesty Core Phase 1).
 * Derivation is deterministic and conservative:
@@ -9501,10 +9510,24 @@ function renderTerminal(result, opts) {
 		score: result.score
 	}, p, width, ascii);
 	appendFrameworks(lines, result, ui);
+	if (result.staged !== void 0) {
+		lines.push(ui.p.dim(`  staged surface: ${result.staged.files} file(s) scanned; score reflects that surface`));
+		lines.push("");
+	}
 	appendDimensions(lines, result, ui);
 	appendDeductions(lines, result, counts, ui);
-	appendFixThisFirst(lines, result, ui);
-	appendFindings(lines, result, counts, opts.verbose === true, ui, opts.tone);
+	const filtered = opts.visibleFindings;
+	const filtering = filtered !== void 0 && filtered.length < result.findings.length;
+	const display = filtering ? {
+		...result,
+		findings: filtered
+	} : result;
+	appendFixThisFirst(lines, display, ui);
+	if (filtering) {
+		lines.push(ui.p.dim(`  filtered view: ${filtered?.length} of ${result.findings.length} findings shown; score reflects the full scan`));
+		lines.push("");
+	}
+	appendFindings(lines, display, counts, opts.verbose === true, ui, opts.tone);
 	if (counts.total === 0 && result.score === 100) appendForgedBlock(lines, p, ascii);
 	appendFooter(lines, result, ui);
 	return lines.join("\n");
@@ -9710,6 +9733,11 @@ function pushCard(lines, card, ui) {
 function appendFindings(lines, result, counts, verbose, ui, tone) {
 	const { p } = ui;
 	if (counts.total === 0) return;
+	if (result.findings.length === 0) {
+		lines.push(ui.p.dim("  filtered view: no findings in the selected category"));
+		lines.push("");
+		return;
+	}
 	const byRule = /* @__PURE__ */ new Map();
 	for (const f of result.findings) {
 		const list = byRule.get(f.ruleId) ?? [];
@@ -9887,7 +9915,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.3",
+			version: "0.5.4",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -10308,6 +10336,52 @@ function renderPrComment(result, options = {}) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/commands/report-io.ts
+/**
+* Shared saved-report loading (agent-handoff plan §9.0).
+*
+* `summary`, `handoff` and `why` all consume a saved `--json` report.
+* One loader, one validation, one error shape — previously
+* validateReportJson was private to summary.ts; extracting it keeps
+* the three commands byte-identical in their loading behavior without
+* duplication. The exit-code mapping stays in the callers (they own
+* their io), but the error MESSAGES are identical because they come
+* from here.
+*/
+/** Human message for any thrown value — never "undefined"/"[object Object]". */
+function errorText(err) {
+	if (err instanceof Error) return err.message;
+	if (typeof err === "string") return err;
+	if (typeof err === "object" && err !== null) return JSON.stringify(err);
+	return String(err);
+}
+/**
+* Parse-and-validate a saved report. Throws Error with a
+* human-explanatory message on: invalid JSON, non-object document,
+* wrong schemaVersion, missing findings array.
+*/
+function validateReportJson(text) {
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (err) {
+		throw new Error(`not valid JSON (${errorText(err)})`, { cause: err });
+	}
+	if (typeof parsed !== "object" || parsed === null) throw new Error("the file is a JSON value but not an object");
+	const doc = parsed;
+	if (doc.schemaVersion !== 1) throw new Error(`unsupported schemaVersion ${JSON.stringify(doc.schemaVersion)} — expected 1`);
+	if (!Array.isArray(doc.findings)) throw new Error("missing a \"findings\" array — is this a Mjölnir --json report?");
+	return parsed;
+}
+/** Load + validate a saved report from disk. Throws on any problem. */
+function loadSavedReport(reportPath) {
+	return validateReportJson(readFileSync(reportPath, "utf8"));
+}
+/** True when the report file exists (callers own the not-found message). */
+function reportExists(reportPath) {
+	return existsSync(reportPath);
+}
+//#endregion
 //#region src/commands/summary.ts
 /**
 * `mjolnir summary [report.json]` — CI annotations + step summary
@@ -10332,29 +10406,7 @@ function renderPrComment(result, options = {}) {
 * `--path-prefix <dir>` re-scopes for subdirectory scans.
 */
 const DETAILS_PER_SEVERITY_CAP = 25;
-/** Human message for any thrown value — never "undefined"/"[object Object]". */
-function errorText(err) {
-	if (err instanceof Error) return err.message;
-	if (typeof err === "string") return err;
-	if (typeof err === "object" && err !== null) return JSON.stringify(err);
-	return String(err);
-}
-/** Parse-and-validate a saved report. Module-private: the command is
-* the only consumer; tests exercise it through runSummaryCommand. */
-function validateReportJson(text) {
-	let parsed;
-	try {
-		parsed = JSON.parse(text);
-	} catch (err) {
-		throw new Error(`not valid JSON (${errorText(err)})`, { cause: err });
-	}
-	if (typeof parsed !== "object" || parsed === null) throw new Error("the file is a JSON value but not an object");
-	const doc = parsed;
-	if (doc.schemaVersion !== 1) throw new Error(`unsupported schemaVersion ${JSON.stringify(doc.schemaVersion)} — expected 1`);
-	if (!Array.isArray(doc.findings)) throw new Error("missing a \"findings\" array — is this a Mjölnir --json report?");
-	return parsed;
-}
-function scoreBar(score, width = 20) {
+function scoreBar$1(score, width = 20) {
 	const filled = Math.round(score / 100 * width);
 	return `${"█".repeat(filled)}${"░".repeat(Math.max(0, width - filled))}`;
 }
@@ -10373,7 +10425,7 @@ function renderStepSummary(result, options = {}) {
 		lines.push(`Score: **${result.score}/100** · ${verdict} (${state.band}) · ${headlineFor(state, result.findings.length)}`);
 		lines.push("");
 		lines.push("```text");
-		lines.push(`${scoreBar(result.score)}  ${result.score}/100`);
+		lines.push(`${scoreBar$1(result.score)}  ${result.score}/100`);
 		lines.push("```");
 	}
 	lines.push("");
@@ -10488,7 +10540,7 @@ function runSummaryCommand(argv, io = {
 	}
 	let result;
 	try {
-		result = validateReportJson(readFileSync(reportPath, "utf8"));
+		result = loadSavedReport(reportPath);
 	} catch (err) {
 		io.err(`mjolnir summary: cannot read ${reportPath}: ${errorText(err)}`);
 		return 2;
@@ -10516,6 +10568,766 @@ function runSummaryCommand(argv, io = {
 	return 0;
 }
 //#endregion
+//#region src/commands/why.ts
+/**
+* `mjolnir why <file>:<line>` — occurrence-level evidence/explanation
+* query (agent-handoff plan M2).
+*
+* Role: an INFORMATIONAL query, not a gate. It works regardless of
+* verdict or tier, shows evidence tags, measured FP rates, runtime
+* corroboration, why/fix, and suppression guidance. Matching is exact
+* file + exact line — the occurrence location as reported, not a
+* durable identity (the fingerprint contract, baseline.ts, governs
+* before/after correlation instead).
+*
+* Two modes:
+* - `--json <mjolnir.json>`: the saved report is AUTHORITATIVE — the
+*   query runs against exactly what the saved scan found (deterministic,
+*   offline).
+* - live (default): runs a fresh scan of the target.
+*
+* Exit codes: 0 match · 1 no finding at that location · 10 usage ·
+* 2 invalid saved report · 20 crash.
+*/
+/** Exact file + exact line match over a finding list. Pure. */
+function explainAt(findings, file, line) {
+	const normalized = file.replace(/\\/g, "/");
+	return {
+		findings: findings.filter((f) => f.file === normalized && f.line === line),
+		file: normalized,
+		line
+	};
+}
+/** Parse the `<file>:<line>` positional (split at the LAST colon). */
+function parseFileLine(token) {
+	const idx = token.lastIndexOf(":");
+	if (idx === -1) return null;
+	const file = token.slice(0, idx);
+	const line = Number(token.slice(idx + 1));
+	if (!file || !Number.isInteger(line) || line < 1) return null;
+	return {
+		file,
+		line
+	};
+}
+function evidenceLines(f, ui) {
+	const lines = [];
+	if (f.evidenceLevel !== void 0 || f.trustLevel !== void 0) {
+		const parts = [];
+		if (f.evidenceLevel !== void 0) parts.push(`evidence ${f.evidenceLevel}`);
+		if (f.trustLevel !== void 0) parts.push(`trust ${f.trustLevel}`);
+		lines.push(`  Evidence: ${parts.join(" · ")}`);
+	}
+	if (f.measuredFpRate !== void 0) {
+		const pct = Math.round(f.measuredFpRate * 100);
+		const n = f.measuredFpN !== void 0 ? ` over ${f.measuredFpN} classified verdicts` : "";
+		lines.push(`  Measured FP rate: ${pct}%${n}`);
+	} else lines.push("  Measured FP rate: none — this rule ships on assumption.");
+	if (f.runtimeCorroboration !== void 0) {
+		const c = f.runtimeCorroboration;
+		const label = c.level === "defect" ? "defect corroborated by the run report" : c.level === "test" ? "the containing test executed in the run report" : "the containing file executed in the run report";
+		lines.push(`  Runtime corroboration: ${label} (${c.source})`);
+	}
+	return lines;
+}
+const SUPPRESSION_HINT = "Suppression (only with cause): an `ignore` entry in mjolnir.config.json — reason REQUIRED, expires after 90 days. Prefer fixing the root cause.";
+/** Render the why answer. Pure over (match, ui). */
+function renderWhy(match, ui = plainContext()) {
+	const { p } = ui;
+	if (match.findings.length === 0) return [
+		sectionHeader(`WHY — ${match.file}:${match.line}`, ui),
+		"",
+		`  No finding at ${match.file}:${match.line} in this report.`,
+		"",
+		p.dim("  Locations are exact (file + line as reported). If the code"),
+		p.dim("  moved since the scan, re-run mjolnir to refresh locations."),
+		""
+	].join("\n");
+	const lines = [
+		sectionHeader(`WHY — ${match.file}:${match.line}`, ui),
+		"",
+		`${match.findings.length} finding${match.findings.length === 1 ? "" : "s"} at this location:`,
+		""
+	];
+	for (const f of match.findings) {
+		lines.push(`  ${severityIcon(f.severity, ui)} ${p.bold(escapeMarkdown(f.ruleId))} — ${escapeMarkdown(f.message)}`);
+		lines.push(`  Why it matters: ${escapeMarkdown(f.why)}`);
+		lines.push(`  Fix: ${escapeMarkdown(f.fix)}`);
+		for (const line of evidenceLines(f, ui)) lines.push(line);
+		lines.push(SUPPRESSION_HINT);
+		lines.push("");
+	}
+	lines.push(nextStep("mjolnir explain <RULE-ID>", ui) + " — full rule context.");
+	return lines.join("\n");
+}
+/**
+* Testable why command core. Returns the process exit code.
+* Live mode awaits the real scan; saved-report mode is synchronous.
+*/
+async function runWhyCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}) {
+	const locationToken = argv.find((a) => !a.startsWith("-"));
+	if (!locationToken) {
+		io.err("Usage: mjolnir why <file>:<line> [--json <mjolnir.json>]");
+		return 10;
+	}
+	const location = parseFileLine(locationToken);
+	if (!location) {
+		io.err(`mjolnir why: cannot parse location "${locationToken}" — expected <file>:<line>`);
+		return 10;
+	}
+	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 target = targetIdx !== -1 ? argv[targetIdx] : ".";
+	let result;
+	if (reportPath !== void 0) {
+		if (!reportExists(reportPath)) {
+			io.err(`mjolnir why: report file not found: ${reportPath}`);
+			io.err("  Run the scan with --json first: mjolnir --json > mjolnir.json");
+			return 10;
+		}
+		try {
+			result = loadSavedReport(reportPath);
+		} catch (err) {
+			io.err(`mjolnir why: cannot read ${reportPath}: ${errorText(err)}`);
+			return 2;
+		}
+	} else {
+		if (!existsSync(target)) {
+			io.err(`mjolnir why: scan target does not exist: ${target}`);
+			return 10;
+		}
+		try {
+			result = await runScan({
+				target,
+				json: false,
+				verbose: false,
+				maxDurationMs: Number.POSITIVE_INFINITY,
+				scopeChanged: false,
+				format: "terminal",
+				strict: argv.includes("--strict")
+			});
+		} catch (err) {
+			io.err(`mjolnir why: scan failed: ${errorText(err)}`);
+			return 20;
+		}
+	}
+	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,
+		findings: filtered
+	}));
+	return filtered.length > 0 ? 0 : 1;
+}
+//#endregion
+//#region src/commands/handoff.ts
+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.",
+	E1: "REQUIRES CONFIRMATION before editing. This is a heuristic finding — the detector's observation alone does not prove the defect. Establish the runtime/product context first, and treat the fix as a hypothesis to validate.",
+	E0: "Observation only — informational by definition. This finding can never deduct points or gate CI. Decide whether it matters in context; do NOT 'fix' it blindly."
+};
+function evidenceBoundary(f) {
+	const level = f.evidenceLevel ?? "E1";
+	const base = EVIDENCE_BOUNDARY[level];
+	if (f.runtimeCorroboration !== void 0) return `${base}\n${f.runtimeCorroboration.level === "defect" ? "Runtime corroboration: the run report directly corroborates this defect." : f.runtimeCorroboration.level === "test" ? "Runtime corroboration: the containing test executed in the run report." : "Runtime corroboration: the containing file executed in the run report."}`;
+	return base;
+}
+function fpLine(f) {
+	if (f.measuredFpRate === void 0) return "Measured FP rate: none — this rule ships on assumption (no measured false-positive rate).";
+	return `Measured FP rate: ${Math.round(f.measuredFpRate * 100)}%${f.measuredFpN !== void 0 ? ` over ${f.measuredFpN} classified verdicts` : ""}.`;
+}
+function scoreBar(score, width = 20) {
+	const filled = Math.round(score / 100 * width);
+	return `${"█".repeat(filled)}${"░".repeat(Math.max(0, width - filled))}`;
+}
+function scopeNote(options) {
+	const parts = [];
+	if (options.categories && options.categories.length > 0) parts.push(`categories: ${options.categories.join(", ")}`);
+	if (options.rules && options.rules.length > 0) parts.push(`rules: ${options.rules.join(", ")}`);
+	return parts.length > 0 ? ` (filtered — ${parts.join("; ")})` : "";
+}
+/**
+* The verification procedure block — the Trust contract rendered into
+* every artifact (plan §5.3). `version` is pinned at render time.
+*/
+function verificationBlock(version) {
+	return [
+		"## Verification procedure",
+		"",
+		"1. Before editing (recommended): `mjolnir baseline` captures the pre-fix report.",
+		"2. After the fixes: `npx mjolnir-qa@" + version + " . --scope changed` re-verifies the targeted surface.",
+		"3. Correlate before/after by finding fingerprint (ruleId + file + message — line numbers are occurrence locations, not identity; edits may move lines).",
+		"",
+		"Outcomes:",
+		"",
+		"- **TARGET_RESOLVED** — every fingerprint in this document is absent from the post-fix scan.",
+		"- **TARGET_REMAINS** — at least one target fingerprint is still present. Report it honestly; do not suppress to clear the report.",
+		"- **NEW_FINDINGS_INTRODUCED** — the post-fix scan contains fingerprints absent from the pre-fix report. Report them; do not silently accept them.",
+		"- **VERIFICATION_NOT_RUN** — no post-fix scan, or a partial scan. Never claim a fix is verified without it.",
+		"",
+		"> ⚠ A clean `--scope changed` run re-verifies the targeted changed-scope remediation. It is NOT a statement that the entire repository is clean — run a full scan for that.",
+		"",
+		"Report files changed. Report checks not run. Report unresolved findings honestly."
+	];
+}
+/** The per-rule remediation copy block (fenced, self-contained). */
+function ruleCopyBlock(group, version) {
+	const f = group.findings[0];
+	const occurrences = group.findings.slice(0, OCCURRENCE_CAP).map((x) => `- \`${escapeMarkdown(x.file)}:${x.line}\``).join("\n");
+	const overflow = group.findings.length > OCCURRENCE_CAP ? `\n- … and ${group.findings.length - OCCURRENCE_CAP} more — see the JSON report.` : "";
+	return [
+		"```text",
+		`Remediation task: ${escapeMarkdown(group.ruleId)} (fix group: ${escapeMarkdown(group.fixGroupId ?? group.ruleId)})`,
+		"",
+		`What was detected: ${escapeMarkdown(f.message)}`,
+		"",
+		`Evidence boundary: ${evidenceBoundary(f).replace(/\n/g, " ")}`,
+		escapeMarkdown(fpLine(f)),
+		"",
+		`What should change: ${escapeMarkdown(f.fix)}`,
+		"",
+		"Constraints:",
+		"- Make the smallest behavior-preserving change that fixes the root cause.",
+		"- Preserve public interfaces, failure semantics, and repository conventions.",
+		"- Adapt identifiers and framework details instead of copying blindly.",
+		"- Do NOT disable the rule or suppress matching code merely to obtain a green scan.",
+		"",
+		"Occurrences (validate each):",
+		occurrences,
+		overflow,
+		"",
+		"Verification:",
+		`  npx mjolnir-qa@${version} . --scope changed`,
+		"",
+		"Expected verification behavior: the fingerprint (ruleId + file + message) of every occurrence above disappears from the post-fix scan, and no NEW fingerprint appears.",
+		"",
+		"Report files changed. Report checks not run. Report unresolved findings honestly.",
+		"```"
+	].join("\n");
+}
+/** The full deterministic handoff artifact. Pure over (result, options). */
+function renderHandoff(result, options = {}, version = CLI_VERSION) {
+	const lines = [];
+	lines.push("### 🔨 Mjölnir — Fix Handoff");
+	lines.push("");
+	if (result.score !== null) {
+		const state = deriveScoreState(result.score);
+		const verdict = verdictFor(result.score);
+		lines.push(`Score: **${result.score}/100** · ${verdict} (${state.band}) · ${headlineFor(state, result.findings.length)}`);
+		lines.push("");
+		lines.push("```text");
+		lines.push(`${scoreBar(result.score)}  ${result.score}/100`);
+		lines.push("```");
+	} else lines.push("Score: **not measurable** — no test files found (`reason: no-tests-found`).");
+	lines.push("");
+	if (result.partial) {
+		lines.push("> ⚠ Partial scan: the budget expired or files were skipped — the finding list may be incomplete. Treat VERIFICATION claims accordingly.");
+		lines.push("");
+	}
+	if (result.findings.length === 0) {
+		lines.push("Zero findings — nothing to fix.");
+		lines.push("");
+		lines.push("No remediation prompt is included. Do not modify the repository on the basis of this document.");
+		lines.push("");
+		if (result.partial) {
+			lines.push("> The scan was partial — the absence of findings is only as trustworthy as the scan's coverage.");
+			lines.push("");
+		}
+		return lines.join("\n");
+	}
+	lines.push(`This document turns ${result.findings.length} finding${result.findings.length === 1 ? "" : "s"} into a remediation plan. Work top-down (errors before warnings); validate each occurrence according to its evidence level before editing.`);
+	lines.push("");
+	const groups = /* @__PURE__ */ new Map();
+	for (const f of result.findings) {
+		const gid = f.fixGroupId ?? f.ruleId;
+		const g = groups.get(gid);
+		if (g) g.findings.push(f);
+		else groups.set(gid, {
+			ruleId: f.ruleId,
+			fixGroupId: gid,
+			findings: [f]
+		});
+	}
+	const ruleFilter = options.rules && options.rules.length > 0 ? new Set(options.rules) : void 0;
+	const catFilter = options.categories && options.categories.length > 0 ? new Set(options.categories) : void 0;
+	const selected = [...groups.values()].filter((g) => !ruleFilter || ruleFilter.has(g.ruleId)).map((g) => ({
+		...g,
+		findings: catFilter ? g.findings.filter((f) => catFilter.has(f.category)) : g.findings
+	})).filter((g) => g.findings.length > 0);
+	if (selected.length === 0) {
+		lines.push("No findings match the requested filters — no remediation prompt is included.");
+		lines.push("");
+		return lines.join("\n");
+	}
+	const sevOrder = {
+		error: 0,
+		warning: 1,
+		info: 2
+	};
+	const sortable = selected;
+	sortable.sort((a, b) => {
+		const sa = sevOrder[a.findings[0].severity];
+		const sb = sevOrder[b.findings[0].severity];
+		if (sa !== sb) return sa - sb;
+		if (b.findings.length !== a.findings.length) return b.findings.length - a.findings.length;
+		return a.ruleId < b.ruleId ? -1 : 1;
+	});
+	lines.push("## How to use this document");
+	lines.push("");
+	lines.push("- Validate each occurrence according to its evidence level before editing.", "- Apply the smallest behavior-preserving fix.", "- Re-run the verification procedure below; correlate by fingerprint.", "- Never suppress a finding merely to obtain a green scan (suppressions live in `mjolnir.config.json`, require a reason, and expire after 90 days).");
+	lines.push("");
+	lines.push(scopeNote(options) ? scopeNote(options).trim() : "");
+	if (!scopeNote(options)) lines.pop();
+	lines.push("");
+	for (const g of sortable) {
+		const first = g.findings[0];
+		lines.push(`### ${escapeMarkdown(g.ruleId)} — ${first.severity} × ${g.findings.length} (fix group: ${escapeMarkdown(g.fixGroupId)})`);
+		lines.push("");
+		lines.push(`**What is wrong:** ${escapeMarkdown(first.message)}`);
+		lines.push("");
+		lines.push(`**Why Mjölnir believes it:** ${escapeMarkdown(first.why)}`);
+		lines.push("");
+		lines.push(`**How trustworthy (evidence boundary):**`);
+		lines.push("");
+		lines.push(evidenceBoundary(first));
+		lines.push("");
+		lines.push(escapeMarkdown(fpLine(first)));
+		lines.push("");
+		lines.push(`**What should change:** ${escapeMarkdown(first.fix)}`);
+		lines.push("");
+		lines.push("**What must NOT change:** behavior unrelated to this finding — public interfaces, failure semantics, accessibility, and repository conventions stay intact.");
+		lines.push("");
+		lines.push(`**Occurrences (${g.findings.length}):**`);
+		lines.push("");
+		for (const f of g.findings.slice(0, OCCURRENCE_CAP)) lines.push(`- \`${escapeMarkdown(f.file)}:${f.line}\` — ${escapeMarkdown(f.message)}`);
+		if (g.findings.length > OCCURRENCE_CAP) lines.push(`- … and ${g.findings.length - OCCURRENCE_CAP} more — see the JSON report.`);
+		lines.push("");
+		lines.push(ruleCopyBlock(g, version));
+		lines.push("");
+	}
+	lines.push("## One-shot handoff prompt");
+	lines.push("");
+	lines.push("```text");
+	lines.push(`Work through the ${selected.length} remediation group(s) above IN ORDER. For each:`);
+	lines.push("- Validate the occurrences according to that group's evidence boundary (E2 = deterministic, act after a location check; E1/E0 = confirm in context first, never assume the observation alone proves the defect).");
+	lines.push("- Apply the smallest behavior-preserving fix from the group's instruction.");
+	lines.push("- Do NOT suppress findings merely to make the scan green.");
+	lines.push(`- Re-run: npx mjolnir-qa@${version} . --scope changed`);
+	lines.push("- Correlate before/after by fingerprint (ruleId + file + message).");
+	lines.push("- Report: files changed, checks not run, and any findings that remain (TARGET_REMAINS) or newly appeared (NEW_FINDINGS_INTRODUCED).");
+	lines.push("- Stop and ask the user when an evidence boundary cannot be resolved.");
+	lines.push("```");
+	lines.push("");
+	lines.push(...verificationBlock(version));
+	lines.push("");
+	lines.push(`_Generated by [Mjölnir](https://github.com/Sergey-Bar/Mjolnir) — evidence and verification; the agent remains responsible for every change._`);
+	return lines.join("\n");
+}
+const KNOWN_FLAGS = /* @__PURE__ */ new Set([
+	"--category",
+	"--rules",
+	"--help",
+	"-h"
+]);
+/**
+* Testable handoff command core. Returns the process exit code.
+* `mjolnir handoff [mjolnir.json] [--category <cat>]... [--rules <ids>]`
+*/
+function runHandoffCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}) {
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (!a.startsWith("-")) continue;
+		if (a === "--category" || a === "--rules") {
+			const val = argv[i + 1];
+			if (val === void 0 || val.startsWith("-")) {
+				io.err(usageErrorMessage({
+					flag: a,
+					token: val
+				}));
+				return 10;
+			}
+			i++;
+			continue;
+		}
+		if (KNOWN_FLAGS.has(a)) continue;
+		io.err(usageErrorMessage({ token: a }));
+		return 10;
+	}
+	const positional = [];
+	const categories = [];
+	let rules;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--category") {
+			categories.push(argv[i + 1]);
+			i++;
+			continue;
+		}
+		if (a === "--rules") {
+			rules = argv[i + 1].split(",").map((r) => r.trim()).filter((r) => r.length > 0);
+			i++;
+			continue;
+		}
+		if (!a.startsWith("-")) positional.push(a);
+	}
+	const reportPath = positional[0] ?? "mjolnir.json";
+	if (!reportExists(reportPath)) {
+		io.err(`mjolnir handoff: report file not found: ${reportPath}`);
+		io.err("  Run the scan with --json first: mjolnir --json > mjolnir.json");
+		return 10;
+	}
+	let result;
+	try {
+		result = loadSavedReport(reportPath);
+	} catch (err) {
+		io.err(`mjolnir handoff: cannot read ${reportPath}: ${errorText(err)}`);
+		return 2;
+	}
+	io.out(renderHandoff(result, {
+		categories,
+		...rules ? { rules } : {}
+	}));
+	return 0;
+}
+//#endregion
+//#region src/commands/install-agents.ts
+/**
+* `mjolnir install` — instruction-surface installer (agent-handoff
+* plan M4).
+*
+* Directory probes detect INSTRUCTION SURFACES, not agents: the probe
+* is a deterministic, offline existence check. All detected surfaces
+* are written; none take precedence over another.
+*
+* Safety contract (plan §17):
+* - Writes are planned by a pure `planInstall()` and executed by
+*   `executeInstall()`; `--dry-run` never executes.
+* - A target file that exists WITHOUT a Mjölnir marker is user-owned →
+*   refusal (exit 10). `--force` overwrites ONLY marker-identified
+*   Mjölnir-owned files.
+* - Re-running rewrites Mjölnir-owned regions idempotently; identical
+*   content → no write at all.
+* - Content is deterministic (no timestamps) and version-pinned to the
+*   running CLI_VERSION — never @latest.
+*
+* Exit codes: 0 installed/updated/nothing-detected (honest message) ·
+* 10 refusal/usage · 20 crash.
+*/
+const MARKER_OPEN = "<!-- mjolnir:managed";
+const MARKER_CLOSE = "<!-- /mjolnir:managed -->";
+function agentBrief(surface, cwdNote) {
+	return [
+		`# Mjölnir — verification trust loop (${surface})`,
+		"",
+		`${MARKER_OPEN} v${CLI_VERSION} -->`,
+		"",
+		`Run \`${cwdNote}npx mjolnir-qa@${CLI_VERSION} . --scope changed\` before finishing any task that touched test code.`,
+		"",
+		"- Exit 0 = clean. Exit 1 = new findings on changed lines: fix them (smallest behavior-preserving change) or justify them to the user.",
+		`- npx mjolnir-qa@${CLI_VERSION} why <file>:<line> explains any finding (evidence level, measured FP rate, fix).`,
+		`- npx mjolnir-qa@${CLI_VERSION} handoff renders a full remediation plan from a saved --json report.`,
+		"- NEVER suppress a finding merely to obtain a green scan (suppressions live in mjolnir.config.json, require a reason, and expire after 90 days).",
+		"- After fixing: re-run the scan, report files changed, report checks not run, report unresolved findings honestly.",
+		"",
+		`<!-- /mjolnir:managed -->`,
+		""
+	].join("\n");
+}
+/** Enumerate every detected surface with its planned content. Pure. */
+function detectSurfaces(cwd) {
+	const surfaces = [];
+	if (existsSync(join(cwd, ".claude"))) surfaces.push({
+		name: "Claude Code command surface",
+		dir: join(cwd, ".claude", "commands"),
+		file: join(cwd, ".claude", "commands", "mjolnir.md"),
+		content: agentBrief("Claude Code command", "/"),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, ".kilo"))) surfaces.push({
+		name: "Kilo command surface",
+		dir: join(cwd, ".kilo", "command"),
+		file: join(cwd, ".kilo", "command", "mjolnir.md"),
+		content: agentBrief("Kilo command", ""),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, ".cursor"))) surfaces.push({
+		name: "Cursor rule surface",
+		dir: join(cwd, ".cursor", "rules"),
+		file: join(cwd, ".cursor", "rules", "mjolnir.mdc"),
+		content: agentBrief("Cursor rule", ""),
+		mode: "whole-file"
+	});
+	if (existsSync(join(cwd, "AGENTS.md"))) surfaces.push({
+		name: "AGENTS.md instruction surface",
+		dir: cwd,
+		file: join(cwd, "AGENTS.md"),
+		content: agentBrief("AGENTS.md", ""),
+		mode: "append-block"
+	});
+	return surfaces;
+}
+function hasMjolnirMarker(content) {
+	return content.includes("<!-- mjolnir:managed") && content.includes("<!-- /mjolnir:managed -->");
+}
+function mergedBlock(existing, content) {
+	const openIdx = existing.indexOf(MARKER_OPEN);
+	const closeIdx = existing.indexOf(MARKER_CLOSE);
+	if (openIdx !== -1 && closeIdx !== -1 && closeIdx > openIdx) {
+		const body = content.slice(content.indexOf(MARKER_OPEN), content.indexOf(MARKER_CLOSE) + 25);
+		return existing.slice(0, openIdx) + body + existing.slice(closeIdx + 25);
+	}
+	return `${existing}${existing.endsWith("\n") ? "" : "\n"}\n${content}`;
+}
+/** Pure plan: what install WOULD do. Zero I/O. */
+function planInstall(cwd, options = {}) {
+	const surfaces = detectSurfaces(cwd);
+	const entries = [];
+	for (const s of surfaces) {
+		if (s.mode === "append-block") {
+			const existing = readFileSync(s.file, "utf8");
+			if (hasMjolnirMarker(existing)) {
+				const merged = mergedBlock(existing, s.content);
+				entries.push(merged === existing ? {
+					action: "no-op",
+					surface: s.name,
+					file: s.file,
+					content: existing
+				} : {
+					action: "update-in-place",
+					surface: s.name,
+					file: s.file,
+					content: merged
+				});
+				continue;
+			}
+			entries.push({
+				action: "create",
+				surface: s.name,
+				file: s.file,
+				content: mergedBlock(existing, s.content)
+			});
+			continue;
+		}
+		if (existsSync(s.file)) {
+			const existing = readFileSync(s.file, "utf8");
+			if (existing === s.content) {
+				entries.push({
+					action: "no-op",
+					surface: s.name,
+					file: s.file,
+					content: existing
+				});
+				continue;
+			}
+			if (!hasMjolnirMarker(existing)) {
+				entries.push({
+					action: "refuse",
+					surface: s.name,
+					file: s.file,
+					reason: "existing file is not Mjölnir-managed (no marker) — pass --force ONLY after reviewing it"
+				});
+				continue;
+			}
+			if (options.force !== true) {
+				entries.push({
+					action: "refuse",
+					surface: s.name,
+					file: s.file,
+					reason: "Mjölnir-managed file has local edits — pass --force to overwrite"
+				});
+				continue;
+			}
+			entries.push({
+				action: "update-in-place",
+				surface: s.name,
+				file: s.file,
+				content: s.content
+			});
+			continue;
+		}
+		entries.push({
+			action: "create",
+			surface: s.name,
+			file: s.file,
+			content: s.content
+		});
+	}
+	return {
+		entries,
+		detected: surfaces.length
+	};
+}
+/** Execute a plan. Returns the number of files written. */
+function executeInstall(entries) {
+	let written = 0;
+	for (const e of entries) {
+		if (e.action === "refuse" || e.action === "no-op") continue;
+		const dir = join(e.file, "..");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(e.file, e.content);
+		written++;
+	}
+	return written;
+}
+/**
+* Testable install command core. Returns the process exit code.
+* `mjolnir install [--dry-run] [--force]` — probes the given cwd
+* (production default: process.cwd()).
+*/
+function runInstallCommand(argv, io = {
+	out: (line) => console.log(line),
+	err: (line) => console.error(line)
+}, cwd = process.cwd()) {
+	const dryRun = argv.includes("--dry-run");
+	const force = argv.includes("--force");
+	const stagedHook = argv.includes("--staged-hook");
+	for (const a of argv) {
+		if (a === "--dry-run" || a === "--force" || a === "--staged-hook") continue;
+		if (a === "--help" || a === "-h") continue;
+		io.err(usageMessageFor(a));
+		return 10;
+	}
+	const { entries, detected } = planInstall(cwd, { force });
+	if (detected === 0 && !stagedHook) {
+		io.out("No instruction surfaces detected — nothing to install. Surfaces probed: .claude/ (Claude Code), .kilo/ (Kilo), .cursor/ (Cursor), AGENTS.md.");
+		return 0;
+	}
+	if (dryRun) {
+		io.out("Install plan (dry run — nothing written):");
+		for (const e of entries) if (e.action === "refuse") io.err(`  REFUSE ${e.file}: ${e.reason}`);
+		else io.out(`  ${e.action} ${e.file}`);
+		if (stagedHook) {
+			const hook = planHookInstall(cwd);
+			io.out(`  ${hook.action} ${hook.file} (non-blocking pre-commit hook)`);
+		}
+		return 0;
+	}
+	let refused = false;
+	for (const e of entries) {
+		if (e.action === "refuse") {
+			io.err(`mjolnir install: refusing ${e.file} — ${e.reason}`);
+			refused = true;
+			continue;
+		}
+		if (e.action === "no-op") continue;
+	}
+	const written = executeInstall(entries);
+	for (const e of entries) if (e.action !== "refuse" && e.action !== "no-op") io.out(`  ${e.action}: ${e.surface} → ${e.file} (mjolnir-qa@${CLI_VERSION})`);
+	if (stagedHook) {
+		const hook = planHookInstall(cwd);
+		executeHookInstall(hook);
+		io.out(`  ${hook.action}: non-blocking pre-commit hook → ${hook.file} (mjolnir-qa@${CLI_VERSION} --staged --blocking warning)`);
+	}
+	for (const e of entries) if (e.action !== "refuse" && e.action !== "no-op") io.out(`  ${e.action}: ${e.surface} → ${e.file} (mjolnir-qa@${CLI_VERSION})`);
+	if (refused) {
+		io.err("Some surfaces were skipped — see refusals above. Nothing was overwritten.");
+		return 10;
+	}
+	io.out(`Installed on ${detected} instruction surface(s); ${written} file(s) written.`);
+	return 0;
+}
+function usageMessageFor(token) {
+	return `mjolnir install: unknown argument "${token}" — supported: --dry-run, --force`;
+}
+const HOOK_MARKER_OPEN = "# mjolnir:managed pre-commit (non-blocking)";
+const HOOK_MARKER_CLOSE = "# /mjolnir:managed pre-commit";
+function hookBlock(version) {
+	return [
+		`${HOOK_MARKER_OPEN} v${version}`,
+		`# Advisory: surfaces staged-file findings without blocking the commit.`,
+		`mjolnir --staged --blocking warning || true`,
+		HOOK_MARKER_CLOSE
+	].join("\n");
+}
+/** The hook file an existing hook manager (husky / core.hooksPath) owns. */
+function resolveHookTarget(cwd) {
+	const huskyDir = join(cwd, ".husky");
+	if (existsSync(huskyDir)) return join(huskyDir, "pre-commit");
+	try {
+		const hooksPath = execFileSync("git", [
+			"-C",
+			cwd,
+			"config",
+			"core.hooksPath"
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		] }).toString().trim();
+		return join(cwd, hooksPath, "pre-commit");
+	} catch {}
+	return join(cwd, ".git", "hooks", "pre-commit");
+}
+/**
+* Pure plan for `--staged-hook` (plan M5). Reuses husky/core.hooksPath
+* when present; otherwise the default .git/hooks path. Marker-based:
+* an existing hook WITHOUT the marker is user-owned → refuse.
+*/
+function planHookInstall(cwd) {
+	const file = resolveHookTarget(cwd);
+	if (!existsSync(file)) return {
+		action: "create",
+		file
+	};
+	let existing;
+	try {
+		existing = readFileSync(file, "utf8");
+	} catch {
+		return {
+			action: "refuse",
+			file,
+			reason: "existing hook is unreadable"
+		};
+	}
+	if (existing.includes(HOOK_MARKER_OPEN)) return {
+		action: "update",
+		file
+	};
+	return {
+		action: "append",
+		file
+	};
+}
+function executeHookInstall(entry) {
+	switch (entry.action) {
+		case "create":
+			mkdirSync(join(entry.file, ".."), { recursive: true });
+			writeFileSync(entry.file, `#!/bin/sh\n${hookBlock(CLI_VERSION)}\n`);
+			return true;
+		case "append": {
+			const existing = readFileSync(entry.file, "utf8");
+			const sep = existing.endsWith("\n") ? "" : "\n";
+			writeFileSync(entry.file, `${existing}${sep}\n${hookBlock(CLI_VERSION)}\n`);
+			return true;
+		}
+		case "update": {
+			const existing = readFileSync(entry.file, "utf8");
+			const openIdx = existing.indexOf(HOOK_MARKER_OPEN);
+			const closeIdx = existing.indexOf(HOOK_MARKER_CLOSE);
+			if (openIdx !== -1 && closeIdx !== -1) writeFileSync(entry.file, existing.slice(0, openIdx) + hookBlock(CLI_VERSION) + existing.slice(closeIdx + 29));
+			else {
+				const sep = existing.endsWith("\n") ? "" : "\n";
+				writeFileSync(entry.file, `${existing}${sep}\n${hookBlock(CLI_VERSION)}\n`);
+			}
+			return true;
+		}
+		default: return false;
+	}
+}
+//#endregion
 //#region src/scope/changed.ts
 /**
 * Changed-scope engine (Sprint-Plan W6, Product-MVP §9 `--scope changed`).
@@ -10724,6 +11536,23 @@ function filterToChanged(findings, diff) {
 		return false;
 	});
 }
+/**
+* --staged (agent-handoff plan §5.7): the staged file names, as a
+* *scan-surface restriction*. Returns null when git data is
+* unavailable (degraded — callers fall back to the full surface with
+* an honest stderr note). Empty list = genuinely nothing staged.
+*/
+function computeStagedFiles(root) {
+	if (!existsSync(join(root, ".git"))) return null;
+	const raw = git$1(root, [
+		"diff",
+		"--cached",
+		"--name-only",
+		"-z"
+	]);
+	if (raw === null) return null;
+	return raw.split("\0").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 //#endregion
 //#region src/engine/rule-runner.ts
 /**
@@ -11915,6 +12744,18 @@ const HELP_ENTRIES = [
 		usage: "mjolnir init [--interactive]",
 		examples: ["mjolnir init"]
 	},
+	{
+		verb: "why",
+		summary: "why did Mjölnir flag <file>:<line>? evidence + fix (not a gate)",
+		usage: "mjolnir why <file>:<line> [path] [--json <mjolnir.json>]",
+		examples: ["mjolnir why e2e/a.spec.ts:3", "mjolnir why e2e/a.spec.ts:3 --json mjolnir.json"]
+	},
+	{
+		verb: "handoff",
+		summary: "deterministic fix-handoff artifact from a saved --json report",
+		usage: "mjolnir handoff [mjolnir.json] [--category <cat>] [--rules <ids>]",
+		examples: ["mjolnir --json > mjolnir.json && mjolnir handoff mjolnir.json", "mjolnir handoff mjolnir.json --category QA-PW"]
+	},
 	{
 		verb: "explain",
 		summary: "what/why/fix + measured FP rate for one rule",
@@ -11944,6 +12785,12 @@ const HELP_ENTRIES = [
 		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. */
@@ -11999,6 +12846,22 @@ const HELP_FLAGS = [
 	{
 		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"
 	}
 ];
 const EXIT_CODE_TABLE = [
@@ -12083,7 +12946,13 @@ const GROUPS = [
 	},
 	{
 		title: "Meta",
-		verbs: ["rules", "explain"]
+		verbs: [
+			"rules",
+			"explain",
+			"why",
+			"handoff",
+			"install"
+		]
 	}
 ];
 const SCAN_SUMMARY_LINES = ["mjolnir [path]                 full-repo scan + WORTHINESS score"];
@@ -12742,6 +13611,15 @@ function renderImpact(report) {
 */
 const ui$8 = plainContext();
 const DEFAULT_BASELINE_PATH = join(".mjolnir", "baseline.json");
+/**
+* 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}`;
 }
@@ -14618,7 +15496,7 @@ function computeSelectorHealth(root, ignoreMatcher = DEFAULT_IGNORE_MATCHER) {
 * `scripts/sync-sarif-version.cjs` on release and guarded by
 * `tests/version-consistency.spec.ts` locally.
 */
-const CLI_VERSION = "0.5.3";
+const CLI_VERSION = "0.5.4";
 const UNIVERSAL_RULES = RULES.map(asUniversal);
 /** Registered rule IDs — used to warn on unknown severityOverrides keys (M4). */
 const KNOWN_RULE_IDS = new Set(RULES.map((r) => r.id));
@@ -14736,7 +15614,23 @@ function parseArgs(argv, onError) {
 		else if (a === "--record-milestones") args.recordMilestones = true;
 		else if (a === "--cache") args.cache = true;
 		else if (a === "--no-progress") args.noProgress = true;
-		else if (a === "--help" || a === "-h") return null;
+		else if (a === "--category") {
+			const cat = argv[++i];
+			if (cat === void 0 || !RULE_CATEGORIES.includes(cat)) return reject({
+				flag: "--category",
+				token: cat
+			});
+			args.categories = [...args.categories ?? [], cat];
+		} else if (a === "--score") args.scoreOnly = true;
+		else if (a === "--staged") args.staged = true;
+		else if (a === "--blocking") {
+			const level = argv[++i];
+			if (level === "error" || level === "warning" || level === "none") args.blocking = level;
+			else return reject({
+				flag: "--blocking",
+				token: level
+			});
+		} else if (a === "--help" || a === "-h") return null;
 		else if (!a.startsWith("-")) args.target = a;
 		else return reject({ token: a });
 	}
@@ -14916,6 +15810,17 @@ async function runScan(args, hooks = {}) {
 		testFiles: wfBucket
 	});
 	ctx.testFiles.push(...wfBucket);
+	let stagedSurface = false;
+	if (args.staged) {
+		const staged = computeStagedFiles(scanRoot.root);
+		if (staged === null) hooks.onConfigWarning?.("mjolnir: --staged ignored — not a git repository (scanning the full surface).");
+		else {
+			const stagedSet = new Set(staged.map((s) => s.replace(/\\/g, "/")));
+			ctx.testFiles = ctx.testFiles.filter((f) => stagedSet.has(relative(scanRoot.root, f).replace(/\\/g, "/")));
+			stagedSurface = true;
+			if (ctx.testFiles.length === 0) hooks.onConfigWarning?.("mjolnir: --staged — no staged files match the scan surface.");
+		}
+	}
 	hooks.onProgress?.({
 		phase: "discover",
 		done: ctx.testFiles.length,
@@ -15067,8 +15972,10 @@ async function runScan(args, hooks = {}) {
 	});
 	const elapsed = Date.now() - started;
 	const hasTests = testFileCount > 0;
+	for (const f of findings) f.fixGroupId = f.ruleId;
 	const result = {
 		schemaVersion: 1,
+		...stagedSurface ? { staged: { files: testFileCount } } : {},
 		partial: discoveryTruncated || rulesPartial || skippedFiles > 0,
 		score: hasTests ? total : null,
 		...hasTests ? {} : { reason: "no-tests-found" },
@@ -15370,13 +16277,22 @@ async function runScanCommand(argv, io = {
 			for (const line of crashLog.slice(0, 50)) io.err(`  ${line}`);
 			if (crashLog.length > 50) io.err(`  … and ${crashLog.length - 50} more`);
 		}
+		if (args.scoreOnly) {
+			if (args.json) io.err("--score overrides --json; stdout is the bare score.");
+			const { config: scoreConfig } = loadConfig(target, { knownRuleIds: KNOWN_RULE_IDS });
+			io.out(result.score === null ? "unknown" : String(result.score));
+			return exitForFindings(result.findings, args.blocking === "none" ? "advisory" : args.blocking ?? scoreConfig.gate ?? "error");
+		}
 		if (args.format === "sarif") io.out(renderSarif(result));
 		else if (args.format === "mermaid") io.out(renderMermaid(result));
 		else if (args.json) io.out(JSON.stringify(result, null, 2));
 		else {
+			const categories = args.categories;
+			const visible = categories && categories.length > 0 ? result.findings.filter((f) => categories.includes(f.category)) : result.findings;
 			io.out(renderTerminal(result, {
 				isTTY: process$1.stdout.isTTY ?? false,
 				verbose: args.verbose,
+				...categories && categories.length > 0 ? { visibleFindings: visible } : {},
 				...args.width !== void 0 ? { width: args.width } : {},
 				...args.ascii !== void 0 ? { ascii: args.ascii } : {},
 				...args.tone !== void 0 ? { tone: args.tone } : {}
@@ -15394,7 +16310,7 @@ async function runScanCommand(argv, io = {
 		if (result.partial) return 2;
 		const { config, warnings } = loadConfig(target, { knownRuleIds: KNOWN_RULE_IDS });
 		for (const w of warnings) io.err(w);
-		return exitForFindings(result.findings, config.gate ?? "error");
+		return exitForFindings(result.findings, args.blocking === "none" ? "advisory" : args.blocking ?? config.gate ?? "error");
 	} catch (err) {
 		if (err instanceof ConfigValidationError) {
 			io.err(err.message);
@@ -15789,8 +16705,11 @@ async function main(argv = process$1.argv.slice(2), io = {
 	if (argv[0] === "rules") return runRulesCommand(argv.slice(1));
 	if (argv[0] === "explain") return runExplainCommand(argv.slice(1));
 	if (argv[0] === "doctor:playwright") return runDoctorPlaywright(argv);
+	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] === "help") return runHelpCommand(argv.slice(1), io);
-	return runScanCommand(argv);
+	return runScanCommand(argv, io);
 }
 /**
 * `mjolnir help` / `mjolnir help <verb>` (plan M2). `--help`/`-h` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mjolnir-qa",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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": {