mjolnir-qa 0.5.32 → 0.5.34

package/CHANGELOG.md

@@ -9,6 +9,18 @@ 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.34] — 2026-09-08
+
+### Changes since 0
+
+- p2: structural anti-dilution — deduction-mass ceilings close the padding vector (plan 1788853205786 P2, decision 4) (#64)
+
+## [0.5.33] — 2026-09-08
+
+### Changes since 0.5.32
+
+- P1: distribution — root action, moving v1 tag, action-based ci install (#63)
+
 ## [0.5.32] — 2026-09-08
 
 ### Changes since 0.5.31

package/README.md

@@ -188,14 +188,16 @@ not drown a first PR:
 npx mjolnir-qa@latest --scope changed
 ```
 
-`mjolnir ci install` writes that as a GitHub Actions workflow — advisory by
-default, never blocking until you say so.
+`mjolnir ci install` writes that as a GitHub Actions workflow — the
+[action](https://github.com/Sergey-Bar/Mjolnir#readme) (Marketplace-grade,
+pinned to the `v1` major tag) by default, or plain `npx` with
+`--no-action`. Advisory by default, never blocking until you say so.
 
 | Command                             | What it does                                     |
 | ----------------------------------- | ------------------------------------------------ |
 | `mjolnir`                           | Full-repo scan + worthiness score                |
 | `mjolnir --scope changed`           | Only what your branch introduced — the CI form   |
-| `mjolnir ci install`                | Generate the advisory PR workflow                |
+| `mjolnir ci install`                | Generate the advisory PR workflow (action-based) |
 | `mjolnir explain QA-CI-001`         | What / why / fix + measured FP rate for one rule |
 | `mjolnir why src/a.spec.ts:42`      | Why this exact line was flagged — never a gate   |
 | `mjolnir forensics ./test-results/` | Runtime evidence from a real run                 |
@@ -236,6 +238,9 @@ of them.
 
 Requires **Node.js ≥ 22.18**. Runs on Windows, macOS and Linux. Install
 globally with `npm i -g mjolnir-qa` if you prefer it over `npx`.
+(Why ≥ 22.18? The build toolchain sets the floor — tsdown targets it and
+the release pipeline smoke-tests against it; the runtime dependencies
+have no such requirement.)
 
 ---
 
@@ -538,6 +543,19 @@ One command generates the PR workflow — advisory by default:
 mjolnir ci install
 ```
 
+Prefer the Marketplace action over a generated workflow? It is one line:
+
+```yaml
+- uses: Sergey-Bar/Mjolnir@v1
+  with:
+    scope: changed
+    fail-on: error
+```
+
+Pin `@v1` to follow the major line or an exact tag (`@v0.5.32`) for a
+reproducible gate — [docs/DISTRIBUTION-KIT.md](docs/DISTRIBUTION-KIT.md)
+covers Marketplace, Smithery and the MCP registries.
+
 Or wire it into GitHub Code Scanning natively via SARIF:
 
 ```yaml

package/dist/cli.d.mts

@@ -201,6 +201,15 @@ interface ScanResult {
   testDeclarationCount?: number;
   /** Raw deduction total before normalization (Phase 5 — transparency). */
   rawDeductions?: number;
+  /**
+   * The evidence-discounted deduction mass the P2 anti-dilution ceiling
+   * caps against (equals rawDeductions today — E0 charges 0, E1 halves;
+   * the ceiling input is deliberately the full discount surface).
+   * Additive within schemaVersion 1; present so consumers recompute the
+   * ceiling from docs/SCORING.md formula v2 without re-deriving
+   * evidence levels.
+   */
+  effectiveDeductions?: number;
   /** Number of findings suppressed by active config entries (suppression transparency). */
   suppressionCount?: number;
   /**
@@ -728,7 +737,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.32";
+declare const CLI_VERSION = "0.5.34";
 /** 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

@@ -10074,6 +10074,58 @@ function computeDimensions(findings) {
 	for (const dim of byCategory.values()) dim.score = Math.max(0, 100 - deductions.get(dim.category));
 	return [...byCategory.values()].sort((a, b) => a.category.localeCompare(b.category));
 }
+/**
+* Deduction-mass ceilings (product-gap-remediation master plan P2,
+* plan 1788853205786 — structural anti-dilution, decision 4).
+*
+* The Goodhart vector the density formula permits: fixed deduction mass
+* ÷ padded denominator → score → 99. A repo with 80 warning-points of
+* real findings and 10,000 test declarations reads 99+ ("one minor
+* issue") because the RATE is tiny — the padding is free. Density stays
+* as the legitimate differentiator for small masses (a lone warning in
+* a 10k suite must still read ≥ 95), but it can no longer dilute a
+* large mass: each absolute deduction-mass band caps the score. Padding
+* cannot move a ceiling — the vector is structurally closed. 80
+* warning-pts read ≤ 75 in ANY suite size.
+*
+* The error-severity floor (95) is the ≥ 8 band seen from the other
+* side: 1 error ≥ 8 pts, so it is subsumed and left standing as a named
+* special case for prose continuity. The > 0 band is the honesty guard
+* (clampWithFindings) — subsumed as well.
+*
+* Calibration (P2.4): these boundaries were chosen to hold the three
+* known data points (self 100, golden 49 via suiteVoided, demo 67) and
+* are then FROZEN with a changelog entry. Never tune them to flatter a
+* repo (docs/SCORING.md Correction section is the precedent).
+*/
+const DEDUCTION_MASS_CEILINGS = [
+	{
+		minMass: 160,
+		ceiling: 65
+	},
+	{
+		minMass: 80,
+		ceiling: 75
+	},
+	{
+		minMass: 40,
+		ceiling: 85
+	},
+	{
+		minMass: 8,
+		ceiling: 95
+	}
+];
+/**
+* The score ceiling for a given evidence-discounted deduction mass.
+* 0 → no ceiling (the 100 honesty guard lives in clampWithFindings);
+* below the smallest band → no ceiling beyond the named guards.
+* Exported for the JSON contract (effectiveDeductions) and the tests.
+*/
+function massCeiling(totalDeduction) {
+	for (const band of DEDUCTION_MASS_CEILINGS) if (totalDeduction >= band.minMass) return band.ceiling;
+	return null;
+}
 function computeTotal(dimensions, findings, exposure) {
 	if (findings.length === 0) return 100;
 	let totalDeduction = 0;
@@ -10086,6 +10138,8 @@ function computeTotal(dimensions, findings, exposure) {
 		const rate = totalDeduction / (declarations + 1);
 		score = clampWithFindings(100 - Math.min(100, rate * 5), totalDeduction);
 	} else score = clampWithFindings(100 - totalDeduction, totalDeduction);
+	const ceiling = massCeiling(totalDeduction);
+	if (ceiling !== null && score > ceiling) score = ceiling;
 	if (findings.some((f) => f.severity === "error" && deductionFor(f) > 0) && score > 95) score = 95;
 	return suiteVoided ? Math.min(score, 49) : score;
 }
@@ -12322,6 +12376,7 @@ async function runScan$1(args, hooks = {}) {
 	});
 	const dimensions = computeDimensions(findings);
 	const rawDeductions = findings.reduce((sum, f) => sum + deductionFor(f), 0);
+	const effectiveDeductions = rawDeductions;
 	const total = computeTotal(dimensions, findings, {
 		testDeclarations: testDeclarationCount,
 		testFileCount,
@@ -12346,6 +12401,7 @@ async function runScan$1(args, hooks = {}) {
 		testFileCount,
 		testDeclarationCount,
 		rawDeductions,
+		effectiveDeductions,
 		suppressionCount,
 		...pluginsLoaded.length > 0 ? { plugins: pluginsLoaded } : {},
 		agenticProfile: computeAgenticProfile(fileProvenance, findings),
@@ -12900,6 +12956,10 @@ function appendScoreSection(lines, result, p, width, ascii) {
 	lines.push(`  ${scoreGauge(result.score, p, gaugeWidth, ascii)}`);
 	lines.push(`  ${p.dim(headlineFor(state, result.findings.length))}`);
 	if (result.rawDeductions !== void 0 && result.testDeclarationCount) lines.push(`  ${p.dim(`(${result.rawDeductions} raw pts / ${result.testDeclarationCount} test declarations — normalized)`)}`);
+	if (result.effectiveDeductions !== void 0 && result.score !== null) {
+		const ceiling = massCeiling(result.effectiveDeductions);
+		if (ceiling !== null && result.score <= ceiling && result.rawDeductions !== void 0) lines.push(`  ${p.dim(`(capped: deduction mass ${result.effectiveDeductions} pts — absolute ceiling ${ceiling})`)}`);
+	}
 	if (result.suppressionCount && result.suppressionCount > 0) lines.push(`  ${p.dim(`(${result.suppressionCount} finding(s) suppressed by config)`)}`);
 	lines.push("");
 }
@@ -13290,7 +13350,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.32",
+			version: "0.5.34",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -15741,7 +15801,7 @@ const SUMMARY_SCRIPT_V1 = [
 * the script via indentBlock(…, 10) inside the `run: |` scalar, so the
 * raw unindented substring never appears in a real v1 file. */
 function isKnownTemplate(content) {
-	return GATES.some((g) => content === TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
+	return GATES.some((g) => content === TEMPLATE(g)) || GATES.some((g) => content === ACTION_TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
 }
 /** Indents an embedded script so it sits inside a YAML `run: |` block scalar. */
 function indentBlock(text, spaces) {
@@ -15854,6 +15914,127 @@ const GATES = [
 	"error",
 	"warning"
 ];
+/**
+* The action-ref the action-based template pins (P1: distribution).
+* `v1` is the major moving tag release.yml's action-tags job maintains on
+* every stable release — Marketplace convention. The generated workflow
+* pins the major, never @latest: a new release must not change gate
+* semantics without a commit of the consumer's.
+*/
+const ACTION_REF = "Sergey-Bar/Mjolnir@v1";
+/**
+* The action-based workflow for one gate level (P1.3): the root
+* action.yml does checkout-independent scanning — setup-node, the scan
+* itself (writing mjolnir.json for the reporting steps), and the gate
+* via the action's `fail-on` input. The action owns the gate: with
+* fail-on error/warning its step exits 1 on findings at the gate, so the
+* workflow needs no separate gate step; partial scans never block (the
+* action downgrades exit 2 to a loud warning, per the frozen exit-code
+* contract). Reporting steps run `if: always()` exactly like the npx
+* template. Advisory mode adds an explicit advisory note as the last
+* step so the job summary says "never blocking" in plain words.
+*/
+const ACTION_TEMPLATE = (gate) => `name: Mjölnir
+
+on:
+  pull_request:
+
+concurrency:
+  group: mjolnir-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    # A hung scan must not sit for the 6-hour default.
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0   # needed for --scope changed merge-base
+      # The action scans with the published mjolnir-qa package, pinned to
+      # the EXACT version that generated this workflow — never a floating
+      # tag: a new release must not change your gate semantics with no
+      # commit of yours (same rule as the npx template). The fail-on
+      # input is the gate: it fails the job on findings at the gate and
+      # never on a partial scan (exit 2 downgrades to a warning — the
+      # frozen exit-code contract). Advisory mode reports, never blocks.
+      - name: Mjölnir verification trust scan
+        id: mjolnir
+        if: always()
+        continue-on-error: ${gate === "advisory" ? "true" : "false"}
+        uses: ${ACTION_REF}
+        with:
+          scope: changed
+          format: json
+          fail-on: ${gate === "advisory" ? "none" : gate}
+          version: ${CLI_VERSION}
+      # Reporting, not gating: runs even when the scan/gate failed, from
+      # the same mjolnir.json the action wrote.
+      - name: Annotations + Job Summary
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} summary mjolnir.json
+      - name: Render PR comment
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} pr-comment . > mjolnir-comment.md
+      # Best-effort: on a pull_request event from a fork the GITHUB_TOKEN is
+      # read-only and this step will 403 for every external contributor. The
+      # Job Summary above is the fallback that always renders.
+      # (pull_request_target would fix the token but is a code-execution
+      # risk — deliberately NOT used.)
+      - name: Post or update PR comment
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('fs');
+            let body = '';
+            try { body = fs.readFileSync('mjolnir-comment.md', 'utf8'); } catch (e) {}
+            if (!body.trim()) {
+              console.log('mjolnir-comment.md is empty or missing — nothing to post.');
+              return;
+            }
+            const marker = '<!-- mjolnir-pr-comment -->';
+            const listed = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = listed.data.find((c) => c.body?.startsWith(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+${gate === "advisory" ? `      # Advisory mode: findings are reported in the Job Summary,
+      # never blocking — the action ran with fail-on: none and
+      # continue-on-error, so even a crashed scan cannot fail this job.
+      - name: Gate (advisory)
+        if: always()
+        run: echo "Advisory mode — findings reported, never blocking."` : `      # Gate enforcement: the action step above IS the gate — fail-on
+      # ${gate} exits 1 on findings at the gate and the step is
+      # continue-on-error: false, so its failure fails the job. A partial
+      # scan never blocks (the action downgrades exit 2 to a warning per
+      # the frozen exit-code contract). The reporting steps above ran
+      # first (if: always()), so a red gate never suppresses the report.`}
+`;
 /** Multiset line diff — counts only, for the refusal message. */
 function summarizeContentDiff(existing, incoming) {
 	const remaining = /* @__PURE__ */ new Map();
@@ -15873,16 +16054,17 @@ function ciInstall(root, gate = "advisory", options = {}) {
 	const target = join(wfDir, "mjolnir.yml");
 	if (!existsSync(wfDir)) mkdirSync(wfDir, { recursive: true });
 	const existed = existsSync(target);
+	const template = options.action === false ? TEMPLATE(gate) : ACTION_TEMPLATE(gate);
 	if (existed) {
 		const current = readFileSync(target, "utf8");
 		if (!isKnownTemplate(current) && !(options.force ?? false)) return {
 			written: target,
 			existed,
 			refused: true,
-			diffSummary: summarizeContentDiff(current, TEMPLATE(gate))
+			diffSummary: summarizeContentDiff(current, template)
 		};
 	}
-	writeFileSync(target, TEMPLATE(gate));
+	writeFileSync(target, template);
 	return {
 		written: target,
 		existed,
@@ -16037,9 +16219,13 @@ function writeBadge(result, options) {
 const HELP_ENTRIES = [
 	{
 		verb: "ci install",
-		summary: "generate the PR workflow (scan + annotations + gate)",
-		usage: "mjolnir ci install [--gate advisory|error|warning] [--force]",
-		examples: ["mjolnir ci install", "mjolnir ci install --gate error --force"],
+		summary: "generate the PR workflow (action-based by default; scan + annotations + gate)",
+		usage: "mjolnir ci install [--gate advisory|error|warning] [--no-action] [--force]",
+		examples: [
+			"mjolnir ci install",
+			"mjolnir ci install --gate error",
+			"mjolnir ci install --no-action --gate error --force"
+		],
 		next: "mjolnir --scope changed"
 	},
 	{
@@ -18662,7 +18848,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.32";
+const CLI_VERSION = "0.5.34";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -18835,9 +19021,11 @@ function runCiInstall(argv, io = {
 	let gateArg;
 	let gateSeen = false;
 	let force = false;
+	let noAction = false;
 	const unknown = [];
 	for (const arg of argv) if (arg === "--gate") gateSeen = true;
 	else if (arg === "--force") force = true;
+	else if (arg === "--no-action") noAction = true;
 	else if (gateSeen && gateArg === void 0 && !arg.startsWith("--")) gateArg = arg;
 	else unknown.push(arg);
 	if (gateSeen && gateArg === void 0) {
@@ -18856,7 +19044,10 @@ function runCiInstall(argv, io = {
 		io.err("Unknown gate level. Use: advisory | error | warning");
 		return 10;
 	}
-	const result = ciInstall(resolve("."), gateArg ?? "advisory", { force });
+	const result = ciInstall(resolve("."), gateArg ?? "advisory", {
+		force,
+		action: !noAction
+	});
 	if (result.refused) {
 		io.err(`Refusing to overwrite the customized workflow at ${result.written}.`);
 		io.err("The file differs from the template Mjölnir would write:");
@@ -18865,8 +19056,9 @@ function runCiInstall(argv, io = {
 		return 10;
 	}
 	io.out(`${result.existed ? "Updated" : "Created"} ${result.written}`);
-	io.out("Default mode: advisory — findings reported, never blocking.");
+	io.out(noAction ? "Plain-npx template (—no-action). Default mode: advisory — findings reported, never blocking." : "Action-based template: uses Sergey-Bar/Mjolnir@v1 (major moving tag).");
 	io.out("Change with: mjolnir ci install --gate error|warning|advisory");
+	if (!noAction) io.out("Prefer the plain-npx workflow? Re-run with --no-action.");
 	return 0;
 }
 /** Testable `suppressions` handler. */

package/dist/mcp/stdio.mjs

@@ -10073,6 +10073,58 @@ function computeDimensions(findings) {
 	for (const dim of byCategory.values()) dim.score = Math.max(0, 100 - deductions.get(dim.category));
 	return [...byCategory.values()].sort((a, b) => a.category.localeCompare(b.category));
 }
+/**
+* Deduction-mass ceilings (product-gap-remediation master plan P2,
+* plan 1788853205786 — structural anti-dilution, decision 4).
+*
+* The Goodhart vector the density formula permits: fixed deduction mass
+* ÷ padded denominator → score → 99. A repo with 80 warning-points of
+* real findings and 10,000 test declarations reads 99+ ("one minor
+* issue") because the RATE is tiny — the padding is free. Density stays
+* as the legitimate differentiator for small masses (a lone warning in
+* a 10k suite must still read ≥ 95), but it can no longer dilute a
+* large mass: each absolute deduction-mass band caps the score. Padding
+* cannot move a ceiling — the vector is structurally closed. 80
+* warning-pts read ≤ 75 in ANY suite size.
+*
+* The error-severity floor (95) is the ≥ 8 band seen from the other
+* side: 1 error ≥ 8 pts, so it is subsumed and left standing as a named
+* special case for prose continuity. The > 0 band is the honesty guard
+* (clampWithFindings) — subsumed as well.
+*
+* Calibration (P2.4): these boundaries were chosen to hold the three
+* known data points (self 100, golden 49 via suiteVoided, demo 67) and
+* are then FROZEN with a changelog entry. Never tune them to flatter a
+* repo (docs/SCORING.md Correction section is the precedent).
+*/
+const DEDUCTION_MASS_CEILINGS = [
+	{
+		minMass: 160,
+		ceiling: 65
+	},
+	{
+		minMass: 80,
+		ceiling: 75
+	},
+	{
+		minMass: 40,
+		ceiling: 85
+	},
+	{
+		minMass: 8,
+		ceiling: 95
+	}
+];
+/**
+* The score ceiling for a given evidence-discounted deduction mass.
+* 0 → no ceiling (the 100 honesty guard lives in clampWithFindings);
+* below the smallest band → no ceiling beyond the named guards.
+* Exported for the JSON contract (effectiveDeductions) and the tests.
+*/
+function massCeiling(totalDeduction) {
+	for (const band of DEDUCTION_MASS_CEILINGS) if (totalDeduction >= band.minMass) return band.ceiling;
+	return null;
+}
 function computeTotal(dimensions, findings, exposure) {
 	if (findings.length === 0) return 100;
 	let totalDeduction = 0;
@@ -10085,6 +10137,8 @@ function computeTotal(dimensions, findings, exposure) {
 		const rate = totalDeduction / (declarations + 1);
 		score = clampWithFindings(100 - Math.min(100, rate * 5), totalDeduction);
 	} else score = clampWithFindings(100 - totalDeduction, totalDeduction);
+	const ceiling = massCeiling(totalDeduction);
+	if (ceiling !== null && score > ceiling) score = ceiling;
 	if (findings.some((f) => f.severity === "error" && deductionFor(f) > 0) && score > 95) score = 95;
 	return suiteVoided ? Math.min(score, 49) : score;
 }
@@ -12321,6 +12375,7 @@ async function runScan$1(args, hooks = {}) {
 	});
 	const dimensions = computeDimensions(findings);
 	const rawDeductions = findings.reduce((sum, f) => sum + deductionFor(f), 0);
+	const effectiveDeductions = rawDeductions;
 	const total = computeTotal(dimensions, findings, {
 		testDeclarations: testDeclarationCount,
 		testFileCount,
@@ -12345,6 +12400,7 @@ async function runScan$1(args, hooks = {}) {
 		testFileCount,
 		testDeclarationCount,
 		rawDeductions,
+		effectiveDeductions,
 		suppressionCount,
 		...pluginsLoaded.length > 0 ? { plugins: pluginsLoaded } : {},
 		agenticProfile: computeAgenticProfile(fileProvenance, findings),
@@ -12899,6 +12955,10 @@ function appendScoreSection(lines, result, p, width, ascii) {
 	lines.push(`  ${scoreGauge(result.score, p, gaugeWidth, ascii)}`);
 	lines.push(`  ${p.dim(headlineFor(state, result.findings.length))}`);
 	if (result.rawDeductions !== void 0 && result.testDeclarationCount) lines.push(`  ${p.dim(`(${result.rawDeductions} raw pts / ${result.testDeclarationCount} test declarations — normalized)`)}`);
+	if (result.effectiveDeductions !== void 0 && result.score !== null) {
+		const ceiling = massCeiling(result.effectiveDeductions);
+		if (ceiling !== null && result.score <= ceiling && result.rawDeductions !== void 0) lines.push(`  ${p.dim(`(capped: deduction mass ${result.effectiveDeductions} pts — absolute ceiling ${ceiling})`)}`);
+	}
 	if (result.suppressionCount && result.suppressionCount > 0) lines.push(`  ${p.dim(`(${result.suppressionCount} finding(s) suppressed by config)`)}`);
 	lines.push("");
 }
@@ -13289,7 +13349,7 @@ function renderSarif(result, repoRootUri) {
 		tool: { driver: {
 			name: "Mjölnir",
 			informationUri: "https://github.com/Sergey-Bar/Mjolnir",
-			version: "0.5.32",
+			version: "0.5.34",
 			rules: [...rules.values()].map((r) => {
 				const meta = RULES.find((x) => x.id === r.id);
 				return {
@@ -14838,7 +14898,7 @@ const SUMMARY_SCRIPT_V1 = [
 * the script via indentBlock(…, 10) inside the `run: |` scalar, so the
 * raw unindented substring never appears in a real v1 file. */
 function isKnownTemplate(content) {
-	return GATES.some((g) => content === TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
+	return GATES.some((g) => content === TEMPLATE(g)) || GATES.some((g) => content === ACTION_TEMPLATE(g)) || content.includes(indentBlock(SUMMARY_SCRIPT_V1, 10));
 }
 /** Indents an embedded script so it sits inside a YAML `run: |` block scalar. */
 function indentBlock(text, spaces) {
@@ -14951,6 +15011,127 @@ const GATES = [
 	"error",
 	"warning"
 ];
+/**
+* The action-ref the action-based template pins (P1: distribution).
+* `v1` is the major moving tag release.yml's action-tags job maintains on
+* every stable release — Marketplace convention. The generated workflow
+* pins the major, never @latest: a new release must not change gate
+* semantics without a commit of the consumer's.
+*/
+const ACTION_REF = "Sergey-Bar/Mjolnir@v1";
+/**
+* The action-based workflow for one gate level (P1.3): the root
+* action.yml does checkout-independent scanning — setup-node, the scan
+* itself (writing mjolnir.json for the reporting steps), and the gate
+* via the action's `fail-on` input. The action owns the gate: with
+* fail-on error/warning its step exits 1 on findings at the gate, so the
+* workflow needs no separate gate step; partial scans never block (the
+* action downgrades exit 2 to a loud warning, per the frozen exit-code
+* contract). Reporting steps run `if: always()` exactly like the npx
+* template. Advisory mode adds an explicit advisory note as the last
+* step so the job summary says "never blocking" in plain words.
+*/
+const ACTION_TEMPLATE = (gate) => `name: Mjölnir
+
+on:
+  pull_request:
+
+concurrency:
+  group: mjolnir-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    # A hung scan must not sit for the 6-hour default.
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0   # needed for --scope changed merge-base
+      # The action scans with the published mjolnir-qa package, pinned to
+      # the EXACT version that generated this workflow — never a floating
+      # tag: a new release must not change your gate semantics with no
+      # commit of yours (same rule as the npx template). The fail-on
+      # input is the gate: it fails the job on findings at the gate and
+      # never on a partial scan (exit 2 downgrades to a warning — the
+      # frozen exit-code contract). Advisory mode reports, never blocks.
+      - name: Mjölnir verification trust scan
+        id: mjolnir
+        if: always()
+        continue-on-error: ${gate === "advisory" ? "true" : "false"}
+        uses: ${ACTION_REF}
+        with:
+          scope: changed
+          format: json
+          fail-on: ${gate === "advisory" ? "none" : gate}
+          version: ${CLI_VERSION}
+      # Reporting, not gating: runs even when the scan/gate failed, from
+      # the same mjolnir.json the action wrote.
+      - name: Annotations + Job Summary
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} summary mjolnir.json
+      - name: Render PR comment
+        if: always()
+        continue-on-error: true
+        run: npx --yes mjolnir-qa@${CLI_VERSION} pr-comment . > mjolnir-comment.md
+      # Best-effort: on a pull_request event from a fork the GITHUB_TOKEN is
+      # read-only and this step will 403 for every external contributor. The
+      # Job Summary above is the fallback that always renders.
+      # (pull_request_target would fix the token but is a code-execution
+      # risk — deliberately NOT used.)
+      - name: Post or update PR comment
+        if: always()
+        continue-on-error: true
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const fs = require('fs');
+            let body = '';
+            try { body = fs.readFileSync('mjolnir-comment.md', 'utf8'); } catch (e) {}
+            if (!body.trim()) {
+              console.log('mjolnir-comment.md is empty or missing — nothing to post.');
+              return;
+            }
+            const marker = '<!-- mjolnir-pr-comment -->';
+            const listed = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = listed.data.find((c) => c.body?.startsWith(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }
+${gate === "advisory" ? `      # Advisory mode: findings are reported in the Job Summary,
+      # never blocking — the action ran with fail-on: none and
+      # continue-on-error, so even a crashed scan cannot fail this job.
+      - name: Gate (advisory)
+        if: always()
+        run: echo "Advisory mode — findings reported, never blocking."` : `      # Gate enforcement: the action step above IS the gate — fail-on
+      # ${gate} exits 1 on findings at the gate and the step is
+      # continue-on-error: false, so its failure fails the job. A partial
+      # scan never blocks (the action downgrades exit 2 to a warning per
+      # the frozen exit-code contract). The reporting steps above ran
+      # first (if: always()), so a red gate never suppresses the report.`}
+`;
 /** Multiset line diff — counts only, for the refusal message. */
 function summarizeContentDiff(existing, incoming) {
 	const remaining = /* @__PURE__ */ new Map();
@@ -14970,16 +15151,17 @@ function ciInstall(root, gate = "advisory", options = {}) {
 	const target = join(wfDir, "mjolnir.yml");
 	if (!existsSync(wfDir)) mkdirSync(wfDir, { recursive: true });
 	const existed = existsSync(target);
+	const template = options.action === false ? TEMPLATE(gate) : ACTION_TEMPLATE(gate);
 	if (existed) {
 		const current = readFileSync(target, "utf8");
 		if (!isKnownTemplate(current) && !(options.force ?? false)) return {
 			written: target,
 			existed,
 			refused: true,
-			diffSummary: summarizeContentDiff(current, TEMPLATE(gate))
+			diffSummary: summarizeContentDiff(current, template)
 		};
 	}
-	writeFileSync(target, TEMPLATE(gate));
+	writeFileSync(target, template);
 	return {
 		written: target,
 		existed,
@@ -15228,9 +15410,13 @@ function writeBadge(result, options) {
 const HELP_ENTRIES = [
 	{
 		verb: "ci install",
-		summary: "generate the PR workflow (scan + annotations + gate)",
-		usage: "mjolnir ci install [--gate advisory|error|warning] [--force]",
-		examples: ["mjolnir ci install", "mjolnir ci install --gate error --force"],
+		summary: "generate the PR workflow (action-based by default; scan + annotations + gate)",
+		usage: "mjolnir ci install [--gate advisory|error|warning] [--no-action] [--force]",
+		examples: [
+			"mjolnir ci install",
+			"mjolnir ci install --gate error",
+			"mjolnir ci install --no-action --gate error --force"
+		],
 		next: "mjolnir --scope changed"
 	},
 	{
@@ -18298,7 +18484,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.32";
+const CLI_VERSION = "0.5.34";
 function parseArgs(argv, onError) {
 	const args = {
 		target: ".",
@@ -18471,9 +18657,11 @@ function runCiInstall(argv, io = {
 	let gateArg;
 	let gateSeen = false;
 	let force = false;
+	let noAction = false;
 	const unknown = [];
 	for (const arg of argv) if (arg === "--gate") gateSeen = true;
 	else if (arg === "--force") force = true;
+	else if (arg === "--no-action") noAction = true;
 	else if (gateSeen && gateArg === void 0 && !arg.startsWith("--")) gateArg = arg;
 	else unknown.push(arg);
 	if (gateSeen && gateArg === void 0) {
@@ -18492,7 +18680,10 @@ function runCiInstall(argv, io = {
 		io.err("Unknown gate level. Use: advisory | error | warning");
 		return 10;
 	}
-	const result = ciInstall(resolve("."), gateArg ?? "advisory", { force });
+	const result = ciInstall(resolve("."), gateArg ?? "advisory", {
+		force,
+		action: !noAction
+	});
 	if (result.refused) {
 		io.err(`Refusing to overwrite the customized workflow at ${result.written}.`);
 		io.err("The file differs from the template Mjölnir would write:");
@@ -18501,8 +18692,9 @@ function runCiInstall(argv, io = {
 		return 10;
 	}
 	io.out(`${result.existed ? "Updated" : "Created"} ${result.written}`);
-	io.out("Default mode: advisory — findings reported, never blocking.");
+	io.out(noAction ? "Plain-npx template (—no-action). Default mode: advisory — findings reported, never blocking." : "Action-based template: uses Sergey-Bar/Mjolnir@v1 (major moving tag).");
 	io.out("Change with: mjolnir ci install --gate error|warning|advisory");
+	if (!noAction) io.out("Prefer the plain-npx workflow? Re-run with --no-action.");
 	return 0;
 }
 /** Testable `suppressions` handler. */

package/package.json

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