mandrel-platform 1.5.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^2.35.0"
+    "mandrel": "^2.38.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-runner-runs-on.test.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * check-runner-runs-on.test.mjs — regression guard for the `runner` input's
+ * two documented shapes (Story #421).
+ *
+ * The bug this pins: every `runs-on:` site consumed the input raw as
+ * `${{ inputs.runner }}`. GitHub does not parse a JSON-array *string* in that
+ * position — it takes the entire text as ONE label name. A caller passing the
+ * documented `'["self-hosted","my-runner"]'` therefore targeted a label no
+ * runner carries, and every tier sat `queued` until the 24-hour timeout.
+ *
+ * It was silent. Nothing went red, no job started, so there were no logs, and
+ * `gh pr checks` reported `pending 0` — indistinguishable from a busy fleet.
+ * The tell was that caller-owned jobs went green while every reusable-workflow
+ * tier reported `pending 0`.
+ *
+ * Why this is not a grep. A `grep` cannot tell a resolvable `runs-on`
+ * expression from an unresolvable one — that is precisely how this shipped,
+ * past static checks that all passed. Asserting the expression's spelling
+ * would pin the wording and not the behaviour. So this EXTRACTS each real
+ * expression from the workflow and EVALUATES it under Actions semantics, the
+ * same read-then-execute approach as check-toolchain-cache-default.test.mjs.
+ *
+ * Run: node --test scripts/check-runner-runs-on.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, readdirSync } from "node:fs";
+import { evaluate } from "./lib/actions-expression.mjs";
+
+const WORKFLOW_DIR = ".github/workflows";
+
+/** Every workflow that declares a `runner` workflow_call input. */
+function runnerWorkflows() {
+  return readdirSync(WORKFLOW_DIR)
+    .filter((f) => f.endsWith(".yml"))
+    .map((f) => ({ file: `${WORKFLOW_DIR}/${f}`, text: readFileSync(`${WORKFLOW_DIR}/${f}`, "utf8") }))
+    .filter(({ text }) => /^\s{6}runner:$/m.test(text));
+}
+
+/**
+ * The `${{ … }}` bodies of every `runs-on:` value that reads `inputs.runner`.
+ * Scans lines rather than building a regex around the file — the block
+ * boundary is a single line, and a dynamically-constructed regex is a SAST
+ * finding that buys nothing here.
+ */
+function runsOnExpressions(text) {
+  const out = [];
+  for (const [idx, line] of text.split("\n").entries()) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("runs-on:")) continue;
+    if (!trimmed.includes("inputs.runner")) continue;
+    const m = trimmed.match(/^runs-on:\s*\$\{\{(.+)\}\}\s*$/);
+    assert.ok(m, `line ${idx + 1}: runs-on reads inputs.runner but is not a single expression: ${trimmed}`);
+    out.push({ line: idx + 1, expr: m[1].trim() });
+  }
+  return out;
+}
+
+const WORKFLOWS = runnerWorkflows();
+
+test("every workflow taking a `runner` input is covered by this guard", () => {
+  // A new reusable workflow with a `runner` input must not slip past unseen.
+  const names = WORKFLOWS.map(({ file }) => file.split("/").pop()).sort();
+  assert.deepEqual(names, [
+    "advisory-scan.yml",
+    "deploy-cloudflare.yml",
+    "pr-quality.yml",
+    "release-automation.yml",
+    "secret-scan-push.yml",
+    "uptime-apply.yml",
+  ]);
+});
+
+test("no `runs-on:` consumes `inputs.runner` raw", () => {
+  // The exact shape that shipped the bug. Kept as a cheap, legible tripwire
+  // alongside the behavioural assertions below.
+  for (const { file, text } of WORKFLOWS) {
+    for (const { line, expr } of runsOnExpressions(text)) {
+      assert.notEqual(
+        expr,
+        "inputs.runner",
+        `${file}:${line}: \`runs-on\` consumes the input raw — a JSON-array ` +
+          `string resolves to one unmatchable label name and the job queues forever`,
+      );
+    }
+  }
+});
+
+for (const { file, text } of WORKFLOWS) {
+  const sites = runsOnExpressions(text);
+
+  test(`${file}: has at least one runner-driven runs-on site`, () => {
+    assert.ok(sites.length > 0, "expected this workflow to drive runs-on from inputs.runner");
+  });
+
+  test(`${file}: a bare label resolves to that same string`, () => {
+    for (const { line, expr } of sites) {
+      assert.equal(evaluate(expr, { runner: "ubuntu-latest" }), "ubuntu-latest", `${file}:${line}`);
+      assert.equal(evaluate(expr, { runner: "beestera-runner" }), "beestera-runner", `${file}:${line}`);
+    }
+  });
+
+  test(`${file}: the documented JSON-array string resolves to a label ARRAY`, () => {
+    for (const { line, expr } of sites) {
+      assert.deepEqual(
+        evaluate(expr, { runner: '["self-hosted","beestera-runner"]' }),
+        ["self-hosted", "beestera-runner"],
+        `${file}:${line}: the documented array form must yield real labels, ` +
+          `not one label named after the whole JSON text`,
+      );
+    }
+  });
+
+  test(`${file}: a malformed array-shaped value fails loudly, not into the label branch`, () => {
+    // A silent fallback to the raw string would rebuild the original failure
+    // mode — an unmatchable label, queued until the 24-hour timeout — behind a
+    // fix that claims to have removed it.
+    for (const { line, expr } of sites) {
+      assert.throws(
+        () => evaluate(expr, { runner: '["unterminated' }),
+        /could not parse/,
+        `${file}:${line}: a '['-leading value that is not valid JSON must be a hard error`,
+      );
+    }
+  });
+
+  test(`${file}: every runs-on site resolves identically`, () => {
+    // One workflow must not drift into two dialects of the same decision.
+    const rendered = sites.map(({ expr }) =>
+      JSON.stringify(evaluate(expr, { runner: '["self-hosted","x"]' })),
+    );
+    assert.equal(new Set(rendered).size, 1, `${file}: runs-on sites disagree: ${rendered.join(" | ")}`);
+  });
+}
+
+test("the documented array form resolves AND derives toolchain-cache 'false'", () => {
+  // The coupling the gap report found: before this fix the only `runner` value
+  // that derived the correct cache posture was the one that never reached a
+  // runner, and the only value that reached a runner derived the wrong posture.
+  // A self-hosted caller could not get both right from the documented
+  // interface. Assert the pairing is now reachable in a single value.
+  const quality = readFileSync(`${WORKFLOW_DIR}/pr-quality.yml`, "utf8");
+  const runner = '["self-hosted","beestera-runner"]';
+
+  const [runsOn] = runsOnExpressions(quality);
+  assert.deepEqual(evaluate(runsOn.expr, { runner }), ["self-hosted", "beestera-runner"]);
+
+  const cache = quality.match(/^\s*cache:\s*\$\{\{(.+)\}\}\s*$/m);
+  assert.ok(cache, "no `cache: ${{ … }}` value found at the setup-toolchain call site");
+  assert.equal(evaluate(cache[1].trim(), { runner, "toolchain-cache": "auto" }), "false");
+});

package/scripts/check-toolchain-cache-default.test.mjs

@@ -31,6 +31,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { readFileSync } from "node:fs";
+import { evaluate } from "./lib/actions-expression.mjs";
 
 const QUALITY = ".github/workflows/pr-quality.yml";
 const ADVISORY = ".github/workflows/advisory-scan.yml";
@@ -68,146 +69,13 @@ function inputDefault(text, name, file) {
 }
 
 // ---------------------------------------------------------------------------
-// A minimal GitHub Actions expression evaluator
-//
-// Only the surface this expression uses: string literals, `inputs.<name>` /
-// `inputs['<name>']` context reads, `==`/`!=`, `&&`/`||`, parentheses, and
-// `contains()`. The semantics that matter and that a hand-read gets wrong:
-//
-//   - `a && b` yields `b` when `a` is truthy, else `a`.
-//   - `a || b` yields `a` when `a` is truthy, else `b`.
-//   - EVERY non-empty string is truthy — including the string `'false'`.
-//   - String comparison is case-insensitive.
+// The Actions expression evaluator now lives in scripts/lib/actions-expression.mjs
+// (extracted by Story #421, when check-runner-runs-on.test.mjs needed the same
+// read-then-execute approach). Its own semantics are covered by
+// scripts/lib/actions-expression.test.mjs, so this file asserts only the
+// toolchain-cache contract.
 // ---------------------------------------------------------------------------
 
-function truthy(v) {
-  if (typeof v === "boolean") return v;
-  if (typeof v === "number") return v !== 0;
-  if (typeof v === "string") return v !== "";
-  return v !== null && v !== undefined;
-}
-
-function looseEqual(a, b) {
-  if (typeof a === "string" && typeof b === "string") {
-    return a.toLowerCase() === b.toLowerCase();
-  }
-  return a === b;
-}
-
-function evaluate(expr, inputs) {
-  let i = 0;
-
-  const ws = () => {
-    while (i < expr.length && /\s/.test(expr[i])) i++;
-  };
-  const eat = (token) => {
-    ws();
-    if (expr.startsWith(token, i)) {
-      i += token.length;
-      return true;
-    }
-    return false;
-  };
-
-  function parseOr() {
-    let left = parseAnd();
-    for (;;) {
-      ws();
-      if (!eat("||")) return left;
-      const right = parseAnd();
-      left = truthy(left) ? left : right;
-    }
-  }
-
-  function parseAnd() {
-    let left = parseCompare();
-    for (;;) {
-      ws();
-      if (!eat("&&")) return left;
-      const right = parseCompare();
-      left = truthy(left) ? right : left;
-    }
-  }
-
-  function parseCompare() {
-    const left = parsePrimary();
-    ws();
-    if (eat("!=")) return !looseEqual(left, parsePrimary());
-    if (eat("==")) return looseEqual(left, parsePrimary());
-    return left;
-  }
-
-  function parsePrimary() {
-    ws();
-    if (eat("(")) {
-      const v = parseOr();
-      ws();
-      assert.ok(eat(")"), `unbalanced parenthesis at ${i} in: ${expr}`);
-      return v;
-    }
-    if (expr[i] === "'") {
-      i++;
-      let out = "";
-      while (i < expr.length) {
-        if (expr[i] === "'" && expr[i + 1] === "'") {
-          out += "'";
-          i += 2;
-          continue;
-        }
-        if (expr[i] === "'") {
-          i++;
-          return out;
-        }
-        out += expr[i++];
-      }
-      assert.fail(`unterminated string literal in: ${expr}`);
-    }
-    if (expr.startsWith("contains(", i)) {
-      i += "contains(".length;
-      const hay = parseOr();
-      ws();
-      assert.ok(eat(","), `contains() expects two arguments in: ${expr}`);
-      const needle = parseOr();
-      ws();
-      assert.ok(eat(")"), `unclosed contains() in: ${expr}`);
-      return String(hay).toLowerCase().includes(String(needle).toLowerCase());
-    }
-    const ident = expr.slice(i).match(/^[A-Za-z_][A-Za-z0-9_.\-]*(\['[^']*'\])?/);
-    assert.ok(ident, `unparseable token at ${i} in: ${expr}`);
-    i += ident[0].length;
-    const raw = ident[0];
-    if (raw === "true") return true;
-    if (raw === "false") return false;
-    const bracket = raw.match(/^inputs\['([^']*)'\]$/);
-    const dotted = raw.match(/^inputs\.(.+)$/);
-    const key = bracket ? bracket[1] : dotted ? dotted[1] : null;
-    assert.ok(key !== null, `unsupported context read \`${raw}\` in: ${expr}`);
-    assert.ok(key in inputs, `expression reads \`inputs.${key}\`, not provided by the test case`);
-    return inputs[key];
-  }
-
-  const value = parseOr();
-  ws();
-  assert.equal(i, expr.length, `trailing tokens at ${i} in: ${expr}`);
-  return value;
-}
-
-// ---------------------------------------------------------------------------
-// The evaluator itself must be trustworthy before it can judge the workflow.
-// ---------------------------------------------------------------------------
-
-test("the expression evaluator models Actions truthiness, not JavaScript's", () => {
-  // The trap the real expression depends on: the STRING 'false' is truthy, so
-  // an explicitly-pinned 'false' survives the first arm of the ternary.
-  assert.equal(evaluate("'false' && 'yes' || 'no'", {}), "yes");
-  // `&&`/`||` yield operands, not booleans.
-  assert.equal(evaluate("true && 'kept'", {}), "kept");
-  assert.equal(evaluate("'' || 'fallback'", {}), "fallback");
-  // Comparison is case-insensitive.
-  assert.equal(evaluate("'AUTO' == 'auto'", {}), true);
-  assert.equal(evaluate("contains('[\"self-hosted\",\"x\"]', 'self-hosted')", {}), true);
-});
-
 // ---------------------------------------------------------------------------
 // The contract
 // ---------------------------------------------------------------------------

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");
+});