mandrel-platform 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-workflow-lint-tier.test.mjs

@@ -0,0 +1,324 @@
+// Structural guards for the workflow-lint tier (Story #425).
+//
+// These assertions are deliberately STRUCTURAL rather than textual: each one
+// resolves the actual `workflow-lint` job block and inspects the keys inside
+// it. A repo-wide grep cannot do this job — `pr-quality.yml` legitimately
+// carries job-level `permissions:` on three OTHER jobs, so "does the file
+// contain `permissions:`" answers a question nobody asked.
+//
+// The invariant that matters most here is the ABSENCE of a job-level
+// `permissions:` on the new tier. GitHub validates a called reusable
+// workflow's declared job permissions against the caller's grant at COMPILE
+// time, regardless of the job's `if:` gate — so adding a scope to this job
+// fails the ENTIRE call with `startup_failure` (zero jobs) for every consumer
+// that has not granted it, including consumers who turned the tier off. Story
+// #292 is the precedent: `pull-requests: read` on migration-guard broke
+// ci.yml and the cross-repo smoke consumer, and stranded a release
+// unpublished. That break is invisible until a consumer's next pin bump,
+// which is exactly the kind of regression a unit test should hold.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const read = (rel) => readFileSync(join(repoRoot, rel), "utf8");
+
+const PR_QUALITY = read(".github/workflows/pr-quality.yml");
+const CI = read(".github/workflows/ci.yml");
+const ACTION = read(".github/actions/workflow-lint/action.yml");
+const DOCS = read("docs/reusable-workflows.md");
+
+/**
+ * Return the lines belonging to one top-level job — from `  <name>:` until the
+ * next key at the same indentation. This is the "parse" the permissions
+ * assertion needs: it scopes the search to ONE job rather than the file.
+ *
+ * @param {string} text  Workflow file contents.
+ * @param {string} job   Job id, e.g. "workflow-lint".
+ * @returns {string[]}
+ */
+export function jobBlock(text, job) {
+  const lines = text.split(/\r?\n/);
+  // A plain line comparison, not a built regex: Semgrep's
+  // detect-non-literal-regexp rejects a RegExp built from a non-literal,
+  // and a job header is an exact line anyway.
+  const start = lines.findIndex((l) => l.trimEnd() === `  ${job}:`);
+  assert.notEqual(start, -1, `job '${job}' not found`);
+  const block = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    // A new key at the job's own indent (2 spaces) ends this block. Blank
+    // lines and comments belong to whatever follows, so they never terminate.
+    if (/^ {2}\S/.test(line)) break;
+    block.push(line);
+  }
+  return block;
+}
+
+/** Keys declared directly on a job (indent 4), ignoring nested mappings. */
+export function jobKeys(block) {
+  return block
+    .filter((l) => /^ {4}[A-Za-z_-]+:/.test(l))
+    .map((l) => l.trim().split(":")[0]);
+}
+
+/**
+ * The block declaring one composite-action input. Anchored to a line start
+ * because the action's header carries USAGE COMMENTS that contain the same
+ * `  <input>:` text — an unanchored indexOf reads the comment instead.
+ *
+ * @param {string} text @param {string} name
+ */
+export function actionInput(text, name) {
+  const lines = text.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trimEnd() === `  ${name}:`);
+  assert.ok(start !== -1, `input '${name}' not declared`);
+  const block = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    // The next input header (indent 2, bare key) ends this block.
+    if (/^ {2}[A-Za-z_-]+:\s*$/.test(lines[i])) break;
+    block.push(lines[i]);
+  }
+  return block.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// The compile-time consumer break (AC-3)
+// ---------------------------------------------------------------------------
+
+test("the workflow-lint job declares NO job-level permissions", () => {
+  const keys = jobKeys(jobBlock(PR_QUALITY, "workflow-lint"));
+  assert.ok(
+    !keys.includes("permissions"),
+    "adding a job-level `permissions:` scope here fails the ENTIRE reusable-workflow " +
+      "call with startup_failure for every consumer lacking that grant, regardless " +
+      "of the job's `if:` gate (Story #292). Use the workflow-level grant instead.",
+  );
+});
+
+test("the scoping is real: other pr-quality jobs DO declare permissions", () => {
+  // If this ever fails, `jobBlock` has stopped scoping and the assertion above
+  // has quietly become vacuous.
+  const withPermissions = ["migration-guard", "security", "osv-scan"].filter((job) =>
+    jobKeys(jobBlock(PR_QUALITY, job)).includes("permissions"),
+  );
+  assert.ok(
+    withPermissions.length > 0,
+    "expected at least one job to declare permissions, else the guard above proves nothing",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Inputs and defaults (AC-3, AC-8)
+// ---------------------------------------------------------------------------
+
+test("enable-workflow-lint is a boolean defaulting to true", () => {
+  const block = PR_QUALITY.slice(PR_QUALITY.indexOf("      enable-workflow-lint:"));
+  assert.match(block.slice(0, 300), /type: boolean/);
+  assert.match(block.slice(0, 300), /default: true/);
+});
+
+test("workflow-lint-enforce is a boolean defaulting to false — advisory on arrival", () => {
+  const block = PR_QUALITY.slice(PR_QUALITY.indexOf("      workflow-lint-enforce:"));
+  assert.match(block.slice(0, 400), /type: boolean/);
+  assert.match(
+    block.slice(0, 400),
+    /default: false/,
+    "the tier must ship advisory: a consumer inheriting it on a pin bump must not " +
+      "have pre-existing workflow debt red their merge",
+  );
+});
+
+test("the tier-timeouts description names the new tier key", () => {
+  const desc = PR_QUALITY.slice(
+    PR_QUALITY.indexOf("      tier-timeouts:"),
+    PR_QUALITY.indexOf("      tier-timeouts:") + 900,
+  );
+  assert.match(desc, /workflow-lint/);
+});
+
+// ---------------------------------------------------------------------------
+// Gate wiring (AC-4)
+// ---------------------------------------------------------------------------
+
+test("workflow-lint is a needs: of ci-required", () => {
+  const block = jobBlock(PR_QUALITY, "ci-required").join("\n");
+  const needs = block.slice(block.indexOf("needs:"), block.indexOf("steps:"));
+  assert.match(
+    needs,
+    /^\s*- workflow-lint$/m,
+    "the aggregator is self-maintaining — adding the job to needs: is the only edit " +
+      "required to make the tier branch-protection load-bearing, with no new required " +
+      "context to register when it later flips to enforcing",
+  );
+});
+
+test("the tier's base timeout is present in TIER_TIMEOUT_BASES", () => {
+  const job = jobBlock(PR_QUALITY, "workflow-lint").join("\n");
+  const m = job.match(/tier-timeouts\)\['workflow-lint'\]\s*\|\|\s*(\d+)/);
+  assert.ok(m, "the tier must read its budget from the tier-timeouts map");
+  const base = m[1];
+  const bases = PR_QUALITY.match(/TIER_TIMEOUT_BASES:\s*'(\[[^\]]*\])'/);
+  assert.ok(bases, "TIER_TIMEOUT_BASES not found");
+  assert.ok(
+    JSON.parse(bases[1]).includes(Number(base)),
+    `base ceiling ${base} must appear in TIER_TIMEOUT_BASES ${bases[1]} — the ` +
+      "cancelled-provenance classifier infers a timed-out cancel by matching a job's " +
+      "wall duration against that set",
+  );
+});
+
+test("the tier honours the runner input like every other tier", () => {
+  const job = jobBlock(PR_QUALITY, "workflow-lint").join("\n");
+  assert.match(job, /runs-on: \$\{\{ fromJSON\(startsWith\(inputs\.runner, '\['\)/);
+});
+
+test("the tier is gated on its enable input", () => {
+  const job = jobBlock(PR_QUALITY, "workflow-lint").join("\n");
+  assert.match(job, /if: \$\{\{ inputs\.enable-workflow-lint \}\}/);
+});
+
+test("pr-quality pins the composite by absolute SHA, as consumers require", () => {
+  const job = jobBlock(PR_QUALITY, "workflow-lint").join("\n");
+  assert.match(
+    job,
+    /uses: dsj1984\/mandrel-platform\/\.github\/actions\/workflow-lint@[0-9a-f]{40}$/m,
+    "a reusable workflow must reference first-party actions by absolute owner/repo " +
+      "path at a full 40-hex SHA — a relative ./ path resolves against the CALLER's " +
+      "checkout, where this action does not exist",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Tool posture (AC-6) and consolidation (AC-7)
+// ---------------------------------------------------------------------------
+
+test("zizmor runs offline at the configured minimum severity", () => {
+  assert.match(ACTION, /--offline/, "online audits red on real ref-version-mismatch " +
+    "findings and would make the gate depend on a live API call");
+  assert.match(ACTION, /--min-severity "\$\{ZIZMOR_MIN_SEVERITY\}"/);
+  assert.match(ACTION, /default: 'medium'/);
+});
+
+test("zizmor's findings never set the exit code — the gate script decides", () => {
+  assert.match(ACTION, /--no-exit-codes/);
+});
+
+test("pyflakes is always disabled and shellcheck is opt-in", () => {
+  assert.match(ACTION, /-pyflakes=/, "pyflakes must be explicitly disabled, not left to PATH");
+  assert.match(ACTION, /inputs\.shellcheck/);
+  assert.match(
+    actionInput(ACTION, "shellcheck"),
+    /default: ''|default: 'false'/,
+    "consumers must not inherit a PATH-dependent gate",
+  );
+});
+
+test("consumers get shellcheck off; this repo's own ci.yml opts in", () => {
+  const job = jobBlock(PR_QUALITY, "workflow-lint").join("\n");
+  assert.match(job, /shellcheck: 'false'/);
+  const ciJob = jobBlock(CI, "actionlint").join("\n");
+  assert.match(
+    ciJob,
+    /shellcheck: 'true'/,
+    "ci.yml relied on ubuntu-latest's PATH shellcheck before this tier existed; " +
+      "consolidating onto the composite must not silently drop that coverage",
+  );
+});
+
+test("ci.yml keeps actionlint blocking while zizmor lands advisory", () => {
+  const ciJob = jobBlock(CI, "actionlint").join("\n");
+  assert.match(ciJob, /enforce-actionlint: 'true'/);
+  assert.match(ciJob, /enforce-zizmor: 'false'/);
+});
+
+test("ci.yml carries no actionlint version or checksum of its own (AC-7)", () => {
+  assert.ok(
+    !/ACTIONLINT_VERSION|ACTIONLINT_SHA256/.test(CI),
+    "the version + checksum map must exist in exactly one place — the composite — " +
+      "or a bump silently updates one copy and leaves the other running an old binary",
+  );
+  assert.match(jobBlock(CI, "actionlint").join("\n"), /uses: \.\/\.github\/actions\/workflow-lint/);
+});
+
+test("the composite pins four checksums per tool across darwin/linux x amd64/arm64", () => {
+  for (const slug of [
+    "1.7.12_darwin_amd64",
+    "1.7.12_darwin_arm64",
+    "1.7.12_linux_amd64",
+    "1.7.12_linux_arm64",
+    "1.30.0_aarch64-apple-darwin",
+    "1.30.0_x86_64-apple-darwin",
+    "1.30.0_aarch64-unknown-linux-gnu",
+    "1.30.0_x86_64-unknown-linux-gnu",
+  ]) {
+    // Plain string scan (no built regex — see jobBlock): find the slug's own
+    // case arm, then assert the 64-hex literal that follows it on that line.
+    const arm = ACTION.split(/\r?\n/).find((l) => l.includes(`"${slug}")`));
+    assert.ok(arm, `missing case arm for ${slug}`);
+    assert.match(arm, /="[0-9a-f]{64}"/, `missing pinned SHA-256 for ${slug}`);
+  }
+});
+
+test("an unmapped platform slug is a hard error, never a silent skip", () => {
+  assert.match(ACTION, /No pinned checksum for actionlint/);
+  assert.match(ACTION, /No pinned checksum for zizmor/);
+  assert.match(ACTION, /actionlint checksum mismatch/);
+  assert.match(ACTION, /zizmor checksum mismatch/);
+});
+
+test("actionlint gets no path arguments — it errors on a directory", () => {
+  // The tools disagree on argument shape; unifying them broke the first cut.
+  assert.match(ACTION, /auto-discovers/);
+  assert.match(ACTION, /\$\{zz_targets\}/, "zizmor takes the resolved directory list");
+  assert.ok(
+    !/actionlint" -no-color -format '\{\{json \.\}\}'[^\n]*\$\{zz_targets\}/.test(ACTION),
+    "actionlint must not be handed directory arguments",
+  );
+});
+
+test("ci.yml's dogfood self-call does not run the natively-covered tier", () => {
+  // The self-call exists to dogfood the SECURITY tier; every tier ci.yml runs
+  // itself is disabled there. workflow-lint is now one of them — and leaving it
+  // on would also make the dogfood depend on the tier's SHA-pinned `uses:`,
+  // which cannot resolve in the PR that first introduces the action.
+  const block = CI.slice(CI.indexOf("uses: ./.github/workflows/pr-quality.yml"));
+  assert.match(block.slice(0, 1500), /enable-workflow-lint: false/);
+});
+
+test("no test or action file builds a RegExp from a non-literal", () => {
+  // Semgrep's detect-non-literal-regexp is diff-baselined and blocks new JS
+  // that does. Pinning it here keeps a future edit from rediscovering it in CI.
+  for (const rel of [
+    "scripts/check-workflow-lint-tier.test.mjs",
+    "scripts/workflow-lint-gate.test.mjs",
+    ".github/actions/workflow-lint/workflow-lint-gate.mjs",
+  ]) {
+    // Assembled so this guard's own needle is not a literal occurrence.
+    const needle = ["new", "RegExp("].join(" ");
+    assert.ok(!read(rel).includes(needle), `${rel} builds a RegExp dynamically`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Documentation (AC-8)
+// ---------------------------------------------------------------------------
+
+test("the docs carry an inputs row and a dedicated tier section", () => {
+  assert.match(DOCS, /\| `enable-workflow-lint`/);
+  assert.match(DOCS, /### Workflow lint tier \(`enable-workflow-lint`\)/);
+});
+
+test("the docs explain the advisory posture, the dial, shellcheck and provenance", () => {
+  const start = DOCS.indexOf("### Workflow lint tier (`enable-workflow-lint`)");
+  assert.notEqual(start, -1);
+  const section = DOCS.slice(start, start + 9000);
+  assert.match(section, /advisory/i);
+  assert.match(section, /workflow-lint-enforce/);
+  assert.match(section, /shellcheck/i);
+  assert.match(section, /checksum/i);
+  assert.match(section, /no checksums file/i, "the zizmor provenance caveat must be recorded");
+});

package/scripts/workflow-lint-gate.test.mjs

@@ -0,0 +1,425 @@
+// Unit coverage for the workflow-lint advisory/enforcing gate (Story #425).
+//
+// The enforcement dial is the load-bearing part of this tier: the gate ships
+// ADVISORY so a consumer inheriting it on a pin bump does not have their
+// pre-existing workflow debt redden the merge, and flips to blocking only when
+// the caller opts in. A grep over pr-quality.yml cannot tell a working dial
+// from a broken one — it pins the spelling, not the behaviour — so the
+// decision lives in a script and is pinned here, mirroring
+// `osv-report-gate.test.mjs` next door.
+//
+// The other invariant these tests hold: a missing or malformed report is a
+// TOOL FAILURE and exits non-zero even in advisory mode. A gate that reports
+// "no findings" because the linter never ran is worse than no gate at all.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+import {
+  normalizeActionlint,
+  normalizeZizmor,
+  classify,
+  countBySeverity,
+  findingsDigest,
+  renderSummary,
+  loadReport,
+  severityRank,
+  resolveEnforcement,
+  WorkflowLintGateError,
+} from "../.github/actions/workflow-lint/workflow-lint-gate.mjs";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const GATE = join(repoRoot, ".github/actions/workflow-lint/workflow-lint-gate.mjs");
+
+// An actionlint `-format '{{json .}}'` row, as the real binary emits it.
+const actionlintRow = (over = {}) => ({
+  message: "got unexpected character '+' while lexing expression",
+  filepath: ".github/workflows/bad.yml",
+  line: 6,
+  column: 29,
+  kind: "expression",
+  snippet: "    timeout-minutes: ${{ 15 + 3 }}",
+  ...over,
+});
+
+// A zizmor `--format json` (v1) finding, as the real binary emits it. Note the
+// ZERO-indexed start_point — the +1 is the thing worth pinning.
+const zizmorRow = (over = {}) => ({
+  ident: "excessive-permissions",
+  desc: "overly broad permissions",
+  url: "https://docs.zizmor.sh/audits/#excessive-permissions",
+  determinations: { confidence: "High", severity: "High", persona: "Regular" },
+  locations: [
+    {
+      symbolic: {
+        key: { Local: { verbatim_path: ".github/workflows/release-please.yml" } },
+        kind: "Primary",
+      },
+      concrete: { location: { start_point: { row: 31, column: 2 } } },
+    },
+  ],
+  ...over,
+});
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+test("normalizeActionlint maps a row and records it at high severity", () => {
+  const [f] = normalizeActionlint([actionlintRow()]);
+  assert.equal(f.tool, "actionlint");
+  assert.equal(f.id, "expression");
+  // actionlint has no severity model — every diagnostic is an error.
+  assert.equal(f.severity, "high");
+  assert.equal(f.file, ".github/workflows/bad.yml");
+  assert.equal(f.line, 6);
+  assert.equal(f.column, 29);
+});
+
+test("normalizeActionlint keeps only the first line of a multi-line message", () => {
+  const [f] = normalizeActionlint([actionlintRow({ message: "first\nsecond" })]);
+  assert.equal(f.message, "first");
+});
+
+test("normalizeZizmor converts zizmor's 0-indexed point to a 1-indexed location", () => {
+  const [f] = normalizeZizmor([zizmorRow()]);
+  assert.equal(f.tool, "zizmor");
+  assert.equal(f.id, "excessive-permissions");
+  assert.equal(f.severity, "high");
+  assert.equal(f.file, ".github/workflows/release-please.yml");
+  // row 31 / column 2 are 0-indexed; zizmor's own plain renderer prints 32:3.
+  assert.equal(f.line, 32);
+  assert.equal(f.column, 3);
+});
+
+test("normalizeZizmor prefers the Primary location over other locations", () => {
+  const row = zizmorRow({
+    locations: [
+      {
+        symbolic: { key: { Local: { verbatim_path: "other.yml" } }, kind: "Related" },
+        concrete: { location: { start_point: { row: 0, column: 0 } } },
+      },
+      {
+        symbolic: { key: { Local: { verbatim_path: "primary.yml" } }, kind: "Primary" },
+        concrete: { location: { start_point: { row: 9, column: 4 } } },
+      },
+    ],
+  });
+  const [f] = normalizeZizmor([row]);
+  assert.equal(f.file, "primary.yml");
+  assert.equal(f.line, 10);
+});
+
+test("normalizeZizmor tolerates a finding with no locations", () => {
+  const [f] = normalizeZizmor([zizmorRow({ locations: [] })]);
+  assert.equal(f.file, "");
+  assert.equal(f.line, 0);
+});
+
+test("a non-array report is a hard error for either tool", () => {
+  assert.throws(() => normalizeActionlint({ nope: true }), WorkflowLintGateError);
+  assert.throws(() => normalizeZizmor("nope"), WorkflowLintGateError);
+});
+
+// ---------------------------------------------------------------------------
+// The enforcement dial — the reason this file exists
+// ---------------------------------------------------------------------------
+
+test("advisory (the default): findings are reported but do NOT fail the tier", () => {
+  const findings = [
+    ...normalizeActionlint([actionlintRow()]),
+    ...normalizeZizmor([zizmorRow()]),
+  ];
+  const verdict = classify(findings);
+  assert.equal(verdict.enforce, false);
+  assert.equal(verdict.findings.length, 2, "every finding is still reported");
+  assert.equal(verdict.blocking.length, 0);
+  assert.equal(verdict.exitCode, 0, "advisory mode must never red the tier");
+});
+
+test("enforcing: the same findings DO fail the tier", () => {
+  const findings = normalizeZizmor([zizmorRow()]);
+  const verdict = classify(findings, { enforce: true });
+  assert.equal(verdict.blocking.length, 1);
+  assert.equal(verdict.exitCode, 1);
+});
+
+test("no findings passes under either setting", () => {
+  assert.equal(classify([]).exitCode, 0);
+  assert.equal(classify([], { enforce: true }).exitCode, 0);
+});
+
+test("findings sort by severity, strongest first", () => {
+  const findings = [
+    { tool: "zizmor", id: "a", severity: "medium", file: "a.yml", line: 1 },
+    { tool: "zizmor", id: "b", severity: "high", file: "b.yml", line: 1 },
+  ];
+  assert.equal(classify(findings).findings[0].severity, "high");
+});
+
+test("severityRank orders the ladder and floors an unknown band", () => {
+  assert.ok(severityRank("high") > severityRank("medium"));
+  assert.ok(severityRank("medium") > severityRank("low"));
+  assert.equal(severityRank("nonsense"), 0);
+});
+
+test("countBySeverity buckets each band and files strays under unknown", () => {
+  const counts = countBySeverity([
+    { severity: "high" },
+    { severity: "medium" },
+    { severity: "medium" },
+    { severity: "bogus" },
+  ]);
+  assert.equal(counts.high, 1);
+  assert.equal(counts.medium, 2);
+  assert.equal(counts.unknown, 1);
+});
+
+// ---------------------------------------------------------------------------
+// Per-tool enforcement — the two linters arrive with different debt
+// ---------------------------------------------------------------------------
+
+test("resolveEnforcement: a per-tool value overrides the tier-wide default", () => {
+  assert.deepEqual(resolveEnforcement({ enforce: "false", actionlint: "true" }), {
+    actionlint: true,
+    zizmor: false,
+  });
+  assert.deepEqual(resolveEnforcement({ enforce: "true", zizmor: "false" }), {
+    actionlint: true,
+    zizmor: false,
+  });
+});
+
+test("resolveEnforcement: an empty per-tool value inherits the tier default", () => {
+  assert.deepEqual(resolveEnforcement({ enforce: "true" }), {
+    actionlint: true,
+    zizmor: true,
+  });
+  assert.deepEqual(resolveEnforcement({}), { actionlint: false, zizmor: false });
+});
+
+test("resolveEnforcement: only the literal 'true' enables a tool", () => {
+  for (const value of ["TRUE", "1", "yes", "on"]) {
+    assert.deepEqual(
+      resolveEnforcement({ actionlint: value, zizmor: value }),
+      { actionlint: false, zizmor: false },
+      `${value} must not enable enforcement`,
+    );
+  }
+});
+
+test("only the enforcing tool's findings block — this repo's ci.yml case", () => {
+  // actionlint blocking (clean), zizmor advisory (pre-existing backlog).
+  const findings = [
+    ...normalizeActionlint([actionlintRow()]),
+    ...normalizeZizmor([zizmorRow()]),
+  ];
+  const verdict = classify(findings, {
+    enforce: { actionlint: true, zizmor: false },
+  });
+  assert.equal(verdict.findings.length, 2, "both are still reported");
+  assert.equal(verdict.blocking.length, 1);
+  assert.equal(verdict.blocking[0].tool, "actionlint");
+  assert.equal(verdict.exitCode, 1);
+});
+
+test("a clean enforcing tool passes even while the advisory tool has findings", () => {
+  const verdict = classify(normalizeZizmor([zizmorRow()]), {
+    enforce: { actionlint: true, zizmor: false },
+  });
+  assert.equal(verdict.findings.length, 1);
+  assert.equal(verdict.blocking.length, 0);
+  assert.equal(verdict.exitCode, 0);
+});
+
+test("the summary labels each row's own gate when the tools differ", () => {
+  const findings = [
+    ...normalizeActionlint([actionlintRow()]),
+    ...normalizeZizmor([zizmorRow()]),
+  ];
+  const md = renderSummary(classify(findings, { enforce: { actionlint: true, zizmor: false } }));
+  assert.match(md, /❌ blocking \| high \| actionlint/);
+  assert.match(md, /⚠️ advisory \| high \| zizmor/);
+  assert.match(md, /1 of 2 finding\(s\)/);
+});
+
+test("the digest counts a mixed verdict rather than calling it all-or-nothing", () => {
+  const findings = [
+    ...normalizeActionlint([actionlintRow()]),
+    ...normalizeZizmor([zizmorRow()]),
+  ];
+  const digest = findingsDigest(
+    classify(findings, { enforce: { actionlint: true, zizmor: false } }),
+  );
+  assert.match(digest, /1 ENFORCING \(failing this tier\), 1 advisory/);
+});
+
+test("CLI: per-tool env vars drive the gate", () => {
+  const both = { actionlint: [actionlintRow()], zizmor: [zizmorRow()] };
+  // actionlint enforcing → red, even though the tier default is advisory.
+  assert.equal(
+    runGate({ WORKFLOW_LINT_ENFORCE_ACTIONLINT: "true" }, both).status,
+    1,
+  );
+  // zizmor advisory override beats an enforcing tier default → its findings
+  // alone cannot red the tier.
+  assert.equal(
+    runGate(
+      { WORKFLOW_LINT_ENFORCE: "true", WORKFLOW_LINT_ENFORCE_ACTIONLINT: "false", WORKFLOW_LINT_ENFORCE_ZIZMOR: "false" },
+      both,
+    ).status,
+    0,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Reporting — an advisory finding nobody can see is the same as no tier
+// ---------------------------------------------------------------------------
+
+test("the digest names the posture so a green log is not mistaken for clean", () => {
+  const findings = normalizeZizmor([zizmorRow()]);
+  assert.match(findingsDigest(classify(findings)), /advisory, so they do NOT fail/);
+  assert.match(findingsDigest(classify(findings, { enforce: true })), /ENFORCING/);
+  assert.match(findingsDigest(classify([])), /no findings/);
+});
+
+test("the summary renders every finding in advisory mode", () => {
+  const md = renderSummary(classify(normalizeZizmor([zizmorRow()])));
+  assert.match(md, /advisory/);
+  assert.match(md, /workflow-lint-enforce: true/);
+  assert.match(md, /release-please\.yml:32:3/);
+  assert.match(md, /excessive-permissions/);
+});
+
+test("the summary says findings fail the build when enforcing", () => {
+  const md = renderSummary(classify(normalizeZizmor([zizmorRow()]), { enforce: true }));
+  assert.match(md, /enforcing/);
+  assert.doesNotMatch(md, /do \*\*not\*\* fail/);
+});
+
+test("backslashes are escaped BEFORE pipes, so a cell cannot be merged", () => {
+  // CodeQL js/incomplete-sanitization: escaping pipes first would let an input
+  // backslash become the escape character for the pipe after it, silently
+  // merging two table cells.
+  const md = renderSummary(
+    classify(normalizeActionlint([actionlintRow({ message: String.raw`a \ b | c` })])),
+  );
+  const row = md.split("\n").find((l) => l.includes("| actionlint |"));
+  assert.ok(row.includes(String.raw`a \\ b \| c`), row);
+});
+
+test("a pipe in a finding message cannot break the summary table", () => {
+  const md = renderSummary(
+    classify(normalizeActionlint([actionlintRow({ message: "a | b" })])),
+  );
+  assert.match(md, /a \\\| b/);
+});
+
+// ---------------------------------------------------------------------------
+// Report loading — a report that did not arrive is never a pass
+// ---------------------------------------------------------------------------
+
+test("an unset report path contributes nothing", () => {
+  assert.deepEqual(loadReport("actionlint", ""), []);
+});
+
+test("a missing report file is fatal, not an empty pass", () => {
+  assert.throws(
+    () => loadReport("zizmor", "/no/such/report.json"),
+    (err) => err instanceof WorkflowLintGateError && /did not run/.test(err.message),
+  );
+});
+
+test("an unparseable report is fatal", () => {
+  const dir = mkdtempSync(join(tmpdir(), "wl-gate-"));
+  try {
+    const p = join(dir, "bad.json");
+    writeFileSync(p, "{not json");
+    assert.throws(() => loadReport("actionlint", p), WorkflowLintGateError);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("an empty report file reads as no findings", () => {
+  const dir = mkdtempSync(join(tmpdir(), "wl-gate-"));
+  try {
+    const p = join(dir, "empty.json");
+    writeFileSync(p, "   ");
+    assert.deepEqual(loadReport("actionlint", p), []);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end through the real CLI entrypoint (AC-5)
+// ---------------------------------------------------------------------------
+
+function runGate(env, { actionlint = [], zizmor = [] } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "wl-gate-e2e-"));
+  try {
+    const alPath = join(dir, "al.json");
+    const zzPath = join(dir, "zz.json");
+    writeFileSync(alPath, JSON.stringify(actionlint));
+    writeFileSync(zzPath, JSON.stringify(zizmor));
+    return spawnSync(process.execPath, [GATE], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        ACTIONLINT_REPORT: alPath,
+        ZIZMOR_REPORT: zzPath,
+        GITHUB_STEP_SUMMARY: "",
+        ...env,
+      },
+    });
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("CLI: a finding exits 0 in advisory mode and still reports itself", () => {
+  const res = runGate({}, { zizmor: [zizmorRow()] });
+  assert.equal(res.status, 0, res.stderr);
+  assert.match(res.stdout, /excessive-permissions/);
+  assert.match(res.stdout, /advisory/);
+  // Advisory findings annotate as warnings, which never red a check run.
+  assert.match(res.stdout, /::warning /);
+});
+
+test("CLI: the same finding exits non-zero when enforcing", () => {
+  const res = runGate({ WORKFLOW_LINT_ENFORCE: "true" }, { zizmor: [zizmorRow()] });
+  assert.equal(res.status, 1);
+  assert.match(res.stdout, /::error /);
+});
+
+test("CLI: a clean report exits 0 either way", () => {
+  assert.equal(runGate({}).status, 0);
+  assert.equal(runGate({ WORKFLOW_LINT_ENFORCE: "true" }).status, 0);
+});
+
+test("CLI: a missing report fails even in advisory mode", () => {
+  const res = spawnSync(process.execPath, [GATE], {
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ACTIONLINT_REPORT: "/no/such/al.json",
+      ZIZMOR_REPORT: "",
+      WORKFLOW_LINT_ENFORCE: "false",
+    },
+  });
+  assert.equal(res.status, 1, "a linter that never ran is not a clean gate");
+  assert.match(res.stderr, /::error::workflow-lint gate/);
+});
+
+test("CLI: only the literal string 'true' enables enforcement", () => {
+  for (const value of ["false", "TRUE", "1", "yes", ""]) {
+    const res = runGate({ WORKFLOW_LINT_ENFORCE: value }, { zizmor: [zizmorRow()] });
+    assert.equal(res.status, 0, `enforce=${JSON.stringify(value)} must stay advisory`);
+  }
+});