mjolnir-qa 1.0.1 → 1.0.2

package/dist/cli.mjs

@@ -119,12 +119,13 @@ const DEDUCTIONS = {
 */
 const EVIDENCE_CORE_VERSION = "evidence-core@1";
 /** Deterministic canonical order: file → line (absent last) → title → source. */
-function compareRecords(a, b) {
+function compareEvidenceRecords(a, b) {
 	if (a.file !== b.file) return a.file < b.file ? -1 : 1;
 	const la = a.line ?? Number.POSITIVE_INFINITY;
 	const lb = b.line ?? Number.POSITIVE_INFINITY;
 	if (la !== lb) return la - lb;
 	if (a.title !== b.title) return a.title < b.title ? -1 : 1;
+	if (a.source !== b.source) return a.source < b.source ? -1 : 1;
 	return 0;
 }
 function normalizeOne(report, artifact, v) {
@@ -159,7 +160,7 @@ function normalizeOne(report, artifact, v) {
 * record list — report verdict order never leaks into the output.
 */
 function buildEvidenceRecords(report, artifact) {
-	return report.verdicts.map((v) => normalizeOne(report, artifact, v)).sort(compareRecords);
+	return report.verdicts.map((v) => normalizeOne(report, artifact, v)).sort(compareEvidenceRecords);
 }
 /**
 * The test whose declaration span contains `line` — the exact matching
@@ -179,8 +180,8 @@ function findTestAt(records, file, line) {
 	for (const r of inFile) if (r.line === void 0) return void 0;
 	let match;
 	for (const r of inFile) {
-		const rLine = r.line;
-		if (rLine <= line && (match === void 0 || match.line <= rLine)) match = r;
+		const l = r.line;
+		if (l <= line && (match === void 0 || match.line <= l)) match = r;
 	}
 	return match;
 }
@@ -3321,6 +3322,10 @@ const focusedTestCommitted = defineRule({
 	falsePositiveRisk: "low",
 	autofix: true,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: ".only/focus is runner skip-scheduling state; the detector matches the runner's own member-call tokens (.only/.fit/fdescribe) on the code-only text — lexical precision equals the AST call-shape here, and the §13.2 fallback keeps parity"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	suiteInvalidating: true,
@@ -3381,6 +3386,10 @@ const skippedTest = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "skip/xfail/ignore are runner skip-state annotations whose forms are runner API tokens (it.skip, xit, t.skip, @unittest.skip); the detector matches those exact tokens on the code-only text"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -3498,6 +3507,10 @@ const noAssertions = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "assertion-less test bodies are runner-outcome semantics (the runner reports a pass that proves nothing); the detector matches the test-def plus body shapes on the code-only text"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -3572,6 +3585,10 @@ const hardSleep = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "hard-sleep is behavioral wait-shape matching (the wait call plus its interaction context), not a single node; the detector's pattern+wait-shape oracle is the recorded design (§12.1), and the hard-sleep family's structural path carries the depth where available"
+	},
 	detectionNotes: "regex pattern + behavioral wait-shape matching",
 	introduced: "0.1.0",
 	tier: "extended",
@@ -3637,6 +3654,10 @@ const retryAbuse = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "retry abuse is the runner's retry contract (jest.retries, vitest retry, playwright retries); the detector matches the runner's retry API tokens across runners — each an exact key"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -3698,6 +3719,10 @@ const emptyTestBody = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "empty test bodies are runner-outcome semantics; the detector matches the test-def plus empty-body shapes on the code-only text — the AST body-shape is the same predicate"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	overlapWith: ["QA-TEST-003"],
@@ -3749,6 +3774,10 @@ const tautologicalAssertion = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "tautological assertions (x === x, expect(true)) are assertion-semantics on the code-only text; the detector matches the tautology shapes after comment stripping — the AST call-shape is the same predicate"
+	},
 	detectionNotes: "AST-stripped text pattern",
 	introduced: "0.1.0",
 	tier: "quarantine",
@@ -3828,6 +3857,10 @@ const unawaitedPromiseAssertion = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "un-awaited promise assertions are runner async semantics; the detector matches the assertion-call shapes inside promise chains on the code-only text — the async contract is runner behavior"
+	},
 	introduced: "0.2.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -3927,6 +3960,10 @@ const commentedOutTest = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "lexical-artifact",
+		detail: "commented-out assertions are lexical artifacts — the comment-wrapped assertion text is the finding itself; the detector matches the shapes on the raw text"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.2.0",
 	tier: "extended",
@@ -4172,6 +4209,10 @@ const committedDebugArtifacts = defineRule({
 	falsePositiveRisk: "low",
 	autofix: true,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "page.pause() and test.only() are exact Playwright runner tokens; the detector matches the member-call identifiers on the code-only text — closed token set, unique to the defect"
+	},
 	introduced: "0.1.0",
 	tier: "core",
 	run(ctx) {
@@ -4224,6 +4265,10 @@ const brittleSelectors = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "string-content-defect",
+		detail: "brittle selectors ARE string arguments (css=/xpath=/nth-child shapes) — the code-text masking that protects other rules deliberately excludes string content here; the detector reads the string shapes directly (inside-string oracle)"
+	},
 	detectionNotes: "regex pattern + inside-string oracle",
 	introduced: "0.1.0",
 	tier: "quarantine",
@@ -4521,6 +4566,10 @@ const swallowedExitCode = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "shell-string-in-config",
+		detail: "exit-code swallowing lives inside workflow run: strings (shell scripts embedded in YAML); the YAML statement IS a string literal — a shell syntax tree of a YAML value adds parsing without adding classification power"
+	},
 	introduced: "0.1.0",
 	tier: "extended",
 	detectorRevision: 2,
@@ -4573,6 +4622,10 @@ const retryMasking = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "retry masking is defined by the runner's retry semantics, which no language syntax tree represents; the detector matches the runner's own retry keys in workflow YAML where statements are shell strings"
+	},
 	introduced: "0.1.0",
 	tier: "extended",
 	detectorRevision: 2,
@@ -4756,6 +4809,10 @@ const reportNeverGenerated = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "report generation is a runner side effect of the workflow step sequence, not a syntax tree property; the detector reads the workflow step graph, whose statements are already literal text"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	detectorRevision: 2,
@@ -4856,6 +4913,10 @@ const alwaysSuccessStep = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "always()-success is a workflow-step outcome contract, not a code construct; the detector matches the step's run/if keys, which are string fields of the YAML config surface"
+	},
 	introduced: "0.1.0",
 	tier: "quarantine",
 	detectorRevision: 2,
@@ -5102,6 +5163,10 @@ const pyNoAssertions = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "assertion-less pytest bodies are runner-outcome semantics (the runner reports a pass that proves nothing); the detector matches the test-def plus body shapes on the code-only text — pytest's pass contract is runner behavior"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	detectorRevision: 3,
@@ -5185,6 +5250,10 @@ const pyHardSleep = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "time.sleep(n) is an exact stdlib token with a numeric argument; the detector matches the call identifier on the code-only text — closed token, unique to the defect"
+	},
 	introduced: "0.3.0",
 	tier: "extended",
 	overlapWith: ["QA-PY-102"],
@@ -5230,6 +5299,10 @@ const pySkippedTest = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "pytest.mark.skip/xfail are runner marker decorators — exact runner tokens; a syntax tree re-derives the same call shape with no added classification power"
+	},
 	introduced: "0.3.0",
 	run(ctx) {
 		const text = ctx.codeText ?? ctx.text;
@@ -5286,6 +5359,10 @@ const pyTautological = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "tautological assertions in Python (assert x == x) are assertion-semantics on the code-only text; the detector matches the tautology shapes — the AST re-derives the same comparison"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -5340,6 +5417,10 @@ const pyFocusedTest = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "pytest.skip/xfail/parametrize marks are runner decorators and module-level calls; the detector matches those exact tokens on the code-only text — the semantics are runner skip state"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	suiteInvalidating: true,
@@ -5392,6 +5473,10 @@ const pyRaisesWithoutMatch = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "pytest.raises without match is a runner exception-contract semantic; the detector matches the raises-call plus its argumentless form — the runner's exception contract, not a syntax property"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	detectorRevision: 3,
@@ -5471,6 +5556,10 @@ const pyCommentedOutTest = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "lexical-artifact",
+		detail: "commented-out test code is a lexical artifact by definition — the text IS the finding (comment-wrapped test bodies); the detector matches the commented shapes on the raw text, which is where the artifact lives"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.0",
 	tier: "core",
@@ -5516,6 +5605,10 @@ const pyBareTruthinessAssert = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "bare truthiness asserts (assert obj) are assertion-semantics on the code-only text; the detector matches the bare-assert shapes — the AST re-derives the same call"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	detectorRevision: 3,
@@ -5584,6 +5677,10 @@ const pyMutableFixture = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "pytest fixture mutation is fixture-lifecycle semantics (autouse/scope keys plus mutation calls); the detector matches the runner's fixture decorator tokens plus the mutation shapes"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	run(ctx) {
@@ -5632,6 +5729,10 @@ const pwWaitForTimeout = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "family-fallback-lockstep",
+		detail: "the hard-sleep family's §13.2 structural path (AST hook) carries the depth where a tree is available; this lexical path is the mandatory deterministic fallback kept in lockstep — the family's depth is real, the regex is its degraded mode"
+	},
 	introduced: "0.3.0",
 	overlapWith: ["QA-TEST-004"],
 	run(ctx) {
@@ -5675,6 +5776,10 @@ const pwWaitForLoadEvent = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "waitForLoadState('load') is an exact Playwright token plus a closed argument enum; the detector matches the call plus its argument — the AST re-derives the same call shape"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	detectorRevision: 2,
@@ -5727,6 +5832,10 @@ const pwDeepFrameLocator = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "frameLocator chaining depth is an exact Playwright token sequence; the detector matches the frameLocator call chains — the token sequence is closed and unique to the defect"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	run(ctx) {
@@ -5774,6 +5883,10 @@ const pwSerialNoJustification = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "fullyParallel/serial are runner scheduling keys on the config and describe blocks; the detector matches the runner's exact API tokens — the semantics are scheduling, not syntax"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	run(ctx) {
@@ -5827,6 +5940,10 @@ const pwConfigRetryAbuse = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "retries in playwright.config.* is a runner top-level option, not a syntax node; the detector reads the config surface whose statements are object-literal keys — exact-key precision"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.0",
 	tier: "core",
@@ -5888,6 +6005,10 @@ const pwNoTraceOnRetry = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "trace/reporter capture is runner lifecycle state set in the config file; the detector reads the config surface's keys and enum values, which are exact matches — a syntax tree adds no semantic the config text lacks"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.0",
 	tier: "extended",
@@ -5941,6 +6062,10 @@ const pwNoProjectSplit = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "project split is a runner config concept (projects array arrangement); the detector reads playwright.config.* keys (adapter-gated), whose object-literal shape is exact-match text"
+	},
 	detectionNotes: "regex heuristic over playwright.config.* (adapter-gated)",
 	introduced: "0.3.0",
 	detectorRevision: 2,
@@ -5991,6 +6116,10 @@ const pwTrialMisuse = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "the trial-click shape is an exact Playwright API token pair; the detector matches the call identifier on the code-only text — the token is closed and unique to the defect"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	run(ctx) {
@@ -6035,6 +6164,10 @@ const pwStorageStateNoExpiry = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "storageState is an exact Playwright config/use option token; the detector matches the option key and its value shapes — closed config surface"
+	},
 	introduced: "0.3.0",
 	run(ctx) {
 		const text = ctx.text;
@@ -6079,6 +6212,10 @@ const pwGlobalSetupSharedState = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "globalSetup/globalTeardown are runner lifecycle hooks declared in the config file; the detector matches those exact keys — the defect is the runner's execution order, not a code shape"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.0",
 	run(ctx) {
@@ -6131,6 +6268,10 @@ const pwSharedPage = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "page reuse across tests is runner fixture-lifecycle semantics; the detector matches the page-consumption shapes against the test boundaries — the lifecycle is runner behavior"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -6178,6 +6319,10 @@ const qaPw140 = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "the detector matches a closed, exact runner API token on the code-only text; the token identifies the defect uniquely"
+	},
 	introduced: "0.3.0",
 	tier: "core",
 	run(ctx) {
@@ -6245,6 +6390,10 @@ const hardcodedBaseUrl = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "string-content-defect",
+		detail: "hardcoded environment URLs are string literals (http(s):// shapes); the detector reads the string-content shapes the code-text mask preserves for exactly this defect class"
+	},
 	introduced: "0.3.0",
 	tier: "quarantine",
 	run(ctx) {
@@ -6295,6 +6444,10 @@ const envCoupling = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "absence-aggregate",
+		detail: "environment-guard absence over the suite is an aggregate property; the detector aggregates the suite's guard shapes — the defect is what the suite lacks, not a node it has"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.2.0",
 	tier: "quarantine",
@@ -6369,6 +6522,10 @@ const pwRetryMaskingNoForensics = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "retry triage is the runner's retry loop interacting with the reporter config; the detector reads both config keys and the triage call shape — the semantics live in runner behavior"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	tier: "extended",
@@ -6421,6 +6578,10 @@ const pwBlanketRouteMock = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "absence-aggregate",
+		detail: "blanket route interception is an aggregate of route calls across the suite; the detector aggregates the route-call shapes — the finding is the pattern's breadth, not one call"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	tier: "extended",
@@ -6474,6 +6635,10 @@ const pwNoFailureArtifacts = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "absence-aggregate",
+		detail: "artifact-capture absence (no trace/video/screenshot anywhere in the suite) is a directory-level aggregate; the detector aggregates over the suite's shapes — absence, not presence"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	tier: "extended",
@@ -6524,6 +6689,10 @@ const pwSingleBrowserMatrix = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "absence-aggregate",
+		detail: "single-browser coverage absence is a config/projects aggregate property; the detector reads the projects arrangement across the config — no single node constitutes the finding"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	tier: "extended",
@@ -6607,6 +6776,10 @@ const pwLocatorNormalize = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "string-content-defect",
+		detail: "CSS/XPath string selectors are string-argument shapes (css=/xpath= engines, bare id/class/attr CSS, nth-child); the detector classifies the string shapes directly"
+	},
 	detectionNotes: "string-selector shapes (css=/xpath= engines, bare id/class/attr CSS, nth-child) inside .locator()/waitForSelector()/page.$ APIs, on the RAW text view (the selector text lives inside string literals, which the code-only view blanks)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -6666,6 +6839,10 @@ const pwCodegenArtifact = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "lexical-artifact",
+		detail: "the codegen recorder's default title ('test', 'test 1', …) committed is a recording artifact — the default-title string is the finding; the detector matches the recorder's exact title shapes"
+	},
 	detectionNotes: "the codegen recorder's default test title ('test', 'test 1', 'test 2', …) committed verbatim, on the RAW text view (the title is a string literal)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -6712,6 +6889,10 @@ const pyPwSyncAsyncMix = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "family-fallback-lockstep",
+		detail: "the hard-sleep family's Python sync/async variant: the family's structural path carries the depth; this variant's lexical path is the lockstep fallback (async-mix shapes across the sync/async boundary)"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	run(ctx) {
@@ -6757,6 +6938,10 @@ const pyPwWaitForTimeout = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "page.waitForTimeout is an exact Playwright token in Python tests; the detector matches the call identifier — closed token, same predicate the AST would encode"
+	},
 	introduced: "0.3.8",
 	tier: "core",
 	run(ctx) {
@@ -6802,6 +6987,10 @@ const pyPwNoAssertions = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "Playwright test bodies without assertions are runner-outcome semantics; the detector matches the test-def plus body shapes on the code-only text"
+	},
 	detectionNotes: "regex heuristic",
 	introduced: "0.3.8",
 	tier: "quarantine",
@@ -6878,6 +7067,10 @@ const jvDisabledTest = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "@Disabled/@Ignore are exact JUnit/TestNG annotation tokens; the detector matches the annotation identifier — annotation shapes are closed token sets where lexical and structural match coincide"
+	},
 	introduced: "0.3.8",
 	tier: "core",
 	run(ctx) {
@@ -7937,6 +8130,10 @@ const csSkippedTest = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "[Ignore]/[Fact(Skip=…)] are exact xUnit/NUnit/MSTest attribute tokens; the detector matches the attribute identifiers — closed token sets where lexical precision equals structural"
+	},
 	introduced: "0.3.8",
 	run(ctx) {
 		const text = ctx.codeText ?? ctx.text;
@@ -8290,6 +8487,10 @@ const cypCyWait = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "cy.wait(numeric) is a Cypress runner wait contract; the detector matches the member-call token with a numeric-literal argument on the code-only text — alias waits (cy.wait('@…')) are structurally distinct and excluded by the argument shape"
+	},
 	detectionNotes: "cy.wait with a numeric-literal argument only — alias waits (cy.wait('@…')) are the legitimate routed-request form and never fire",
 	introduced: "0.6.0",
 	tier: "extended",
@@ -8362,6 +8563,10 @@ const cypFocusedTest = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "Cypress .only is the runner's focus token; the detector matches the it/describe/context .only member-call shape on the code-only text — exact-key precision"
+	},
 	detectionNotes: "it/describe/context .only member-call shape on the code-only text view",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -8428,6 +8633,10 @@ const cypConfigSecurity = defineRule({
 	falsePositiveRisk: "low",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "exact-key-match",
+		detail: "chromeWebSecurity:false is an exact config key/value pair inside cypress.config.*; the detector matches the key and value literally — the config surface's statements are the finding"
+	},
 	detectionNotes: "positive match on chromeWebSecurity:false inside cypress.config.* (the config is the artifact — no heuristic)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -8535,6 +8744,10 @@ const seJavaSleepLookup = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the Selenium family's variants (QA-SE-001/002/003): the defect is the SEQUENCE sleep-then-interact — runner timing semantics, not a single node; the detector matches the sleep token followed by a lookup within the recorded window"
+	},
 	detectionNotes: "sequence shape: Thread.sleep followed by a findElement/interaction call within 3 lines (code-only view)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -8560,6 +8773,10 @@ const seCSharpSleepLookup = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the Selenium family's variants (QA-SE-001/002/003): the defect is the SEQUENCE sleep-then-interact — runner timing semantics, not a single node; the detector matches the sleep token followed by a lookup within the recorded window"
+	},
 	detectionNotes: "sequence shape: Thread.Sleep/Task.Delay followed by a FindElement/interaction call within 3 lines (code-only view)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -8585,6 +8802,10 @@ const sePythonSleepLookup = defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the Selenium family's variants (QA-SE-001/002/003): the defect is the SEQUENCE sleep-then-interact — runner timing semantics, not a single node; the detector matches the sleep token followed by a lookup within the recorded window"
+	},
 	detectionNotes: "sequence shape: time.sleep followed by a find_element/interaction call within 3 lines (code-only view)",
 	introduced: "0.6.0",
 	tier: "quarantine",
@@ -8623,6 +8844,7 @@ function definePatternFamily(opts) {
 		falsePositiveRisk: v.falsePositiveRisk ?? opts.falsePositiveRisk,
 		autofix: opts.autofix ?? false,
 		detectionStrategy: v.detectionStrategy ?? opts.detectionStrategy ?? "LEXICAL",
+		...v.strategyJustification ?? opts.strategyJustification ? { strategyJustification: v.strategyJustification ?? opts.strategyJustification } : {},
 		...v.detectionNotes !== void 0 ? { detectionNotes: v.detectionNotes } : { ...opts.detectionNotes !== void 0 ? { detectionNotes: opts.detectionNotes } : {} },
 		...opts.introduced ? { introduced: opts.introduced } : {},
 		...v.tier !== void 0 ? { tier: v.tier } : { ...opts.tier !== void 0 ? { tier: opts.tier } : {} },
@@ -8775,6 +8997,10 @@ const hardSleepFamily = definePatternFamily({
 	why: WHY,
 	falsePositiveRisk: "low",
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "family-fallback-lockstep",
+		detail: "the hard-sleep family's Java variant (QA-JV-102): the family's structural path carries the depth where a tree is available; this lexical path is the mandatory deterministic fallback kept in lockstep (§13.2)"
+	},
 	introduced: "0.3.8",
 	tier: "extended",
 	useCodeText: true,
@@ -8824,6 +9050,10 @@ const networkIdleFamily = definePatternFamily({
 	why: "Analytics, websockets, and polling make network idle never fire or fire randomly — a documented source of Playwright flakes.",
 	falsePositiveRisk: "low",
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the network-idle family's variants (QA-JV-107/QA-CS-107/QA-PY-107): networkidle waits are runner timing semantics; the detector matches the runner's wait tokens — exact keys"
+	},
 	introduced: "0.4.0",
 	useCodeText: false,
 	variants: [
@@ -8899,6 +9129,10 @@ const hardcodedUrlFamily = definePatternFamily({
 	why: "Absolute URLs break when environments change and can hit production by accident from a CI runner.",
 	falsePositiveRisk: "low",
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "string-content-defect",
+		detail: "the hardcoded-url family's variants (QA-JV-108/QA-CS-108/QA-PY-108): hardcoded URLs are string literals; the detector matches the http(s):// string shapes — the URL lives in the string, not the syntax tree"
+	},
 	introduced: "0.4.0",
 	useCodeText: false,
 	variants: [{
@@ -8929,6 +9163,10 @@ const sharedPageFamily = definePatternFamily({
 	why: "A shared Page/Browser leaks cookies, localStorage, and navigation state between tests — failures become order-dependent and impossible to reproduce in isolation.",
 	falsePositiveRisk: "medium",
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the shared-page family's variants (QA-JV-104/QA-CS-104/QA-PY-106): page/fixture reuse across tests is runner fixture-lifecycle semantics; the detector matches the consumption shapes against test boundaries"
+	},
 	introduced: "0.4.0",
 	useCodeText: true,
 	variants: [
@@ -9004,6 +9242,10 @@ function makeBrittleSelectors(id, appliesTo, ext, languages, frameworks, pattern
 		falsePositiveRisk: "medium",
 		autofix: false,
 		detectionStrategy: "LEXICAL",
+		strategyJustification: {
+			reasonCode: "string-content-defect",
+			detail: "the brittle-selector family's variants (QA-JV-106/QA-CS-106/QA-PY-104): selector defects are string-argument shapes (xpath=/nth-child/absolute-path); the detector classifies the string shapes the code-text mask preserves for this class"
+		},
 		introduced: "0.4.0",
 		tier: "quarantine",
 		detectorRevision: 2,
@@ -9100,6 +9342,10 @@ const retryMaskingFamily = [defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the retry-masking family's variants (QA-JV-109/QA-CS-109): retry masking is the runner's retry contract; the detector matches the runner's retry tokens on the code-only text"
+	},
 	introduced: "0.4.0",
 	tier: "core",
 	run(ctx) {
@@ -9153,6 +9399,10 @@ const retryMaskingFamily = [defineRule({
 	falsePositiveRisk: "medium",
 	autofix: false,
 	detectionStrategy: "LEXICAL",
+	strategyJustification: {
+		reasonCode: "runner-semantic",
+		detail: "the retry-masking family's variants (QA-JV-109/QA-CS-109): retry masking is the runner's retry contract; the detector matches the runner's retry tokens on the code-only text"
+	},
 	introduced: "0.4.0",
 	tier: "extended",
 	run(ctx) {
@@ -12753,7 +13003,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "1.0.1",
+			version: "1.0.2",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -18417,6 +18667,19 @@ function loadManifest(path) {
 *
 * Exit codes reuse the frozen set: 0 healthy · 1 violations · 20 crash.
 */
+/** The closed reason-code set (master plan P8) — mirrored from
+* src/rules/rule.ts's StrategyReasonCode union via a runtime set so the
+* doctor check validates membership without an extra export cycle. */
+const VALID_REASON_CODES = /* @__PURE__ */ new Set([
+	"shell-string-in-config",
+	"exact-key-match",
+	"lexical-artifact",
+	"runner-semantic",
+	"string-content-defect",
+	"absence-aggregate",
+	"family-fallback-lockstep",
+	"migration-deferred-next-measurement"
+]);
 /** Uniform error rendering for doctor details (Error or thrown-as-string). */
 function errorText(e) {
 	return e instanceof Error ? e.message : String(e);
@@ -18455,7 +18718,8 @@ function checkFixtureFirewall(fixturesRoot) {
 	}
 	return check("fixture-firewall", ok ? "pass" : "fail", details);
 }
-/** Check 2: registry sanity — IDs unique, well-formed, titles distinct. */
+/** Check 2: registry sanity — IDs unique, well-formed, titles distinct,
+* and (P8) every LEXICAL rule carries a valid depth-adjudication record. */
 function checkRegistry(rules = RULES) {
 	const details = [];
 	const ids = /* @__PURE__ */ new Set();
@@ -18470,6 +18734,19 @@ function checkRegistry(rules = RULES) {
 			details.push(`${r.id}: duplicate registration`);
 		}
 		ids.add(r.id);
+		if (r.detectionStrategy === "LEXICAL") {
+			const j = r.strategyJustification;
+			if (!j) {
+				ok = false;
+				details.push(`${r.id}: LEXICAL strategy without strategyJustification — declare the reason the lexical form ships (docs/DEPTH-ADJUDICATION.md)`);
+			} else if (!VALID_REASON_CODES.has(j.reasonCode)) {
+				ok = false;
+				details.push(`${r.id}: strategyJustification.reasonCode "${String(j.reasonCode)}" is outside the closed set (${[...VALID_REASON_CODES].join(", ")})`);
+			} else if (j.detail.trim().length < 20) {
+				ok = false;
+				details.push(`${r.id}: strategyJustification.detail is boilerplate — cite the detector's actual shape`);
+			}
+		}
 		const family = r.id.split("-")[1];
 		for (const other of rules) if (other.id !== r.id && other.title === r.title && other.id.split("-")[1] === family) {
 			ok = false;
@@ -19157,7 +19434,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 = "1.0.1";
+const CLI_VERSION = "1.0.2";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -19493,8 +19770,9 @@ async function runExplainCommand(argv, io = {
 			return 10;
 		}
 		try {
-			io.out(renderVerdictExplain(explainVerdict(resolve(jsonPath))));
-			return explainVerdict(resolve(jsonPath)).ok ? 0 : 10;
+			const r = explainVerdict(resolve(jsonPath));
+			io.out(renderVerdictExplain(r));
+			return r.ok ? 0 : 10;
 		} catch (err) {
 			internalErrorMessage(err, io.err, argv.includes("--debug"));
 			return 20;