mandrel-platform 1.2.0 → 1.4.0

package/scripts/check-first-party-pin-freshness.test.mjs

@@ -36,8 +36,11 @@ import {
   collectPinnedRefs,
   resolveManifest,
   manifestsMatch,
+  diffSubpathAtSha,
+  companionsFor,
   runCheck,
   runCli,
+  COMPANION_SUBPATHS,
 } from "./check-first-party-pin-freshness.mjs";
 
 const OWNER = "test-owner/test-repo";
@@ -255,6 +258,299 @@ test("clean: two call sites pinning the same fresh SHA both pass", () => {
   assert.equal(result.scanned, 2);
 });
 
+// ---------------------------------------------------------------------------
+// Story #379 — the comparison is the whole action DIRECTORY, not the manifest
+//
+// A composite action whose behaviour lives in a sibling script is the majority
+// of this repo's action surface (`osv-scan`, `osv-track-issue`), and a
+// manifest-only comparison is structurally unable to see a change there. That
+// blind spot shipped live: Story #365 rewrote `osv-scan/osv-report-gate.mjs`
+// (+189/-12) without touching `action.yml`, so both call sites read as fresh
+// while executing the old gate.
+// ---------------------------------------------------------------------------
+
+const SIBLING_MANIFEST = [
+  "name: demo",
+  "description: fixture composite action whose behaviour lives in a sibling script",
+  "runs:",
+  "  using: composite",
+  "  steps:",
+  "    - shell: bash",
+  "      run: node ./gate.mjs",
+  "",
+].join("\n");
+
+/**
+ * Create a repo whose action manifest NEVER changes — only the sibling
+ * `gate.mjs` does. The `before` commit therefore carries a byte-identical
+ * `action.yml` alongside a stale `gate.mjs`.
+ */
+function makeSiblingScriptRepo(label) {
+  const root = mkdtempSync(join(tmpdir(), `pinfresh-${label}-`));
+  git(root, "init", "-b", "main");
+  git(root, "config", "user.email", "fixture@example.invalid");
+  git(root, "config", "user.name", "Pin Freshness Fixture");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "config", "core.hooksPath", join(root, ".no-hooks"));
+
+  put(root, `${SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${SUBPATH}/gate.mjs`, "process.exit(0);\n");
+  git(root, "add", "-A");
+  git(root, "commit", "-m", "initial action");
+  const before = git(root, "rev-parse", "HEAD");
+
+  // Behaviour change, manifest untouched.
+  put(root, `${SUBPATH}/gate.mjs`, "process.exit(process.env.FAIL ? 1 : 0);\n");
+  git(root, "add", "-A");
+  git(root, "commit", "-m", "harden the gate");
+  const after = git(root, "rev-parse", "HEAD");
+
+  return { root, before, after };
+}
+
+/** `git show <sha>:<path>` without the trimming the `git` helper applies. */
+function showRaw(root, sha, relPath) {
+  return execFileSync("git", ["show", `${sha}:${relPath}`], { cwd: root, encoding: "utf8" });
+}
+
+test("stale: a sibling script that differs at the pinned SHA is stale even when action.yml is byte-identical", () => {
+  const { root, before } = makeSiblingScriptRepo("sibling-stale");
+  track(root);
+  put(root, ".github/workflows/fixture.yml", workflow(before));
+
+  // The premise, asserted rather than assumed: a manifest-only comparison
+  // would have called this pin fresh.
+  assert.equal(
+    showRaw(root, before, `${SUBPATH}/action.yml`),
+    readFileSync(join(root, SUBPATH, "action.yml"), "utf8"),
+    "premise: action.yml is byte-identical at the pinned SHA"
+  );
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.stale.length, 1);
+  assert.equal(result.unreachable.length, 0);
+  assert.match(result.stale[0].reason, /gate\.mjs/, "the report names the drifting sibling");
+
+  const { code, stderr } = capture(["--cwd", root, "--first-party-owner", OWNER]);
+  assert.equal(code, 1);
+  assert.match(stderr, /gate\.mjs/);
+});
+
+test("clean: a pin carrying the current sibling script exits 0", () => {
+  const { root, after } = makeSiblingScriptRepo("sibling-clean");
+  track(root);
+  put(root, ".github/workflows/fixture.yml", workflow(after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER });
+  assert.equal(result.ok, true);
+});
+
+test("stale: a file added to the action directory since the pinned SHA is stale", () => {
+  const { root, after } = makeSiblingScriptRepo("sibling-added");
+  track(root);
+  put(root, `${SUBPATH}/helper.mjs`, "export const help = () => 1;\n");
+  git(root, "add", "-A");
+  put(root, ".github/workflows/fixture.yml", workflow(after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER });
+
+  assert.equal(result.ok, false);
+  assert.match(result.stale[0].reason, /helper\.mjs/);
+});
+
+test("stale: a file removed from the action directory since the pinned SHA is stale", () => {
+  const { root, after } = makeSiblingScriptRepo("sibling-removed");
+  track(root);
+  git(root, "rm", "-q", `${SUBPATH}/gate.mjs`);
+  put(root, ".github/workflows/fixture.yml", workflow(after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER });
+
+  assert.equal(result.ok, false);
+  assert.match(result.stale[0].reason, /gate\.mjs/);
+});
+
+test("diffSubpathAtSha: a tracked file missing from disk is drift, not a silent skip", () => {
+  const path = `${SUBPATH}/gone.mjs`;
+  const fake = { lsTree: () => [path], lsFiles: () => [path], show: () => "body\n" };
+
+  const drift = diffSubpathAtSha(fake, "/no-such-root", "0".repeat(40), SUBPATH);
+
+  assert.deepEqual(drift, [{ path, kind: "unreadable" }]);
+});
+
+test("diffSubpathAtSha: a blob git cannot resolve at the pinned SHA is drift, not a pass", () => {
+  const { root } = makeSiblingScriptRepo("sibling-unresolvable");
+  track(root);
+  const path = `${SUBPATH}/gate.mjs`;
+  const fake = { lsTree: () => [path], lsFiles: () => [path], show: () => null };
+
+  const drift = diffSubpathAtSha(fake, root, "0".repeat(40), SUBPATH);
+
+  assert.deepEqual(drift, [{ path, kind: "differs" }]);
+});
+
+// ---------------------------------------------------------------------------
+// Story #389 — a subpath's COMPANIONS are compared alongside it
+//
+// The subpaths this checker knows are exactly the ones named on `uses:` lines,
+// so the moment an action's behaviour moves into a sibling DIRECTORY the
+// Story #379 blind spot reopens one level up. `osv-track-issue` is now a thin
+// preset that executes `../track-issue/track-issue.mjs`, and nothing `uses:`
+// the generic action — so without a companion map, a rewrite of that shared
+// core leaves every preset call site reading fresh while the pinned SHA runs
+// the old state machine.
+// ---------------------------------------------------------------------------
+
+const PRESET_SUBPATH = ".github/actions/osv-track-issue";
+const CORE_SUBPATH = ".github/actions/track-issue";
+const PRESET_COMPANIONS = { [PRESET_SUBPATH]: [CORE_SUBPATH] };
+
+/** A workflow pinning `subpath@sha`, one step per call site. */
+function workflowFor(subpath, sha) {
+  return [
+    "name: fixture",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  demo:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${OWNER}/${subpath}@${sha}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * A repo shaped like the post-#389 split: a preset directory whose manifest
+ * runs a script in a sibling core directory that no `uses:` line names. Both
+ * are committed; the caller then edits the CORE in the working tree only.
+ */
+function makePresetRepo(label) {
+  const root = mkdtempSync(join(tmpdir(), `pinfresh-${label}-`));
+  git(root, "init", "-b", "main");
+  git(root, "config", "user.email", "fixture@example.invalid");
+  git(root, "config", "user.name", "Pin Freshness Fixture");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "config", "core.hooksPath", join(root, ".no-hooks"));
+
+  put(root, `${CORE_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'noop';\n");
+  put(root, `${PRESET_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "import '../track-issue/track-issue.mjs';\n");
+  git(root, "add", "-A");
+  git(root, "commit", "-m", "split the tracker into a core and a preset");
+  const after = git(root, "rev-parse", "HEAD");
+
+  return { root, after };
+}
+
+test("stale: an edit confined to the shared core marks every preset call site stale", () => {
+  const { root, after } = makePresetRepo("companion-stale");
+  track(root);
+  // Two call sites, both pinning the preset — neither names the core.
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, ".github/workflows/two.yml", workflowFor(PRESET_SUBPATH, after));
+
+  // The edit is confined to the core, and nothing under the preset changes.
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'create';\n");
+
+  // The premise, asserted rather than assumed: without the companion map this
+  // fixture reads perfectly fresh — which is the blind spot, not a pass.
+  const blind = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: {} });
+  assert.equal(blind.ok, true, "premise: a preset-only comparison sees no drift");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.scanned, 2);
+  assert.equal(result.stale.length, 2, "every call site of the preset is stale, not just one");
+  assert.equal(result.unreachable.length, 0);
+  for (const f of result.stale) {
+    assert.equal(f.subpath, PRESET_SUBPATH);
+    assert.match(f.reason, /track-issue\.mjs/, "the report names the drifting shared file");
+    assert.match(f.reason, /shared code it executes/, "and explains why a sibling tree is in scope");
+  }
+});
+
+test("stale: a file added to the shared core since the pinned SHA is drift", () => {
+  const { root, after } = makePresetRepo("companion-added");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, `${CORE_SUBPATH}/helper.mjs`, "export const help = () => 1;\n");
+  git(root, "add", "-A");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.match(result.stale[0].reason, /helper\.mjs/);
+});
+
+test("clean: a pin carrying the current core AND preset exits 0", () => {
+  const { root, after } = makePresetRepo("companion-clean");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true);
+});
+
+test("a subpath with no companions is compared exactly as before", () => {
+  const { root, after } = makePresetRepo("companion-unmapped");
+  track(root);
+  // Pin the CORE directly — it has no companions of its own, so a preset edit
+  // must not leak into its comparison.
+  put(root, ".github/workflows/one.yml", workflowFor(CORE_SUBPATH, after));
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "// rewritten preset\n");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true, "companions are directional, not symmetric");
+});
+
+test("diffSubpathAtSha: companions are unioned into both sides of the comparison", () => {
+  const presetPath = `${PRESET_SUBPATH}/action.yml`;
+  const corePath = `${CORE_SUBPATH}/action.yml`;
+  const presetBody = readFileSync(join(REPO_ROOT, presetPath), "utf8");
+  // The pinned side knows only the preset; the working side also has the core.
+  const fake = {
+    lsTree: (_sha, root) => (root === PRESET_SUBPATH ? [presetPath] : []),
+    lsFiles: (root) => (root === PRESET_SUBPATH ? [presetPath] : [corePath]),
+    show: () => presetBody,
+  };
+
+  const without = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH);
+  assert.deepEqual(without, [], "the preset tree alone is identical at both ends");
+
+  const withCore = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH, [CORE_SUBPATH]);
+  assert.deepEqual(withCore, [{ path: corePath, kind: "added" }]);
+});
+
+test("companionsFor: unmapped subpaths stand alone, and trailing slashes resolve", () => {
+  assert.deepEqual(companionsFor(".github/actions/setup-toolchain"), []);
+  assert.deepEqual(companionsFor(PRESET_SUBPATH, PRESET_COMPANIONS), [CORE_SUBPATH]);
+  assert.deepEqual(companionsFor(`${PRESET_SUBPATH}/`, PRESET_COMPANIONS), [CORE_SUBPATH]);
+});
+
+test("COMPANION_SUBPATHS: every mapped subpath and companion exists in this repo", () => {
+  // A map entry pointing at a path that no longer exists is a silently-dead
+  // guard — the pin would read fresh again with nothing flagging it.
+  for (const [subpath, companions] of Object.entries(COMPANION_SUBPATHS)) {
+    assert.ok(
+      resolveManifest(REPO_ROOT, subpath),
+      `${subpath} is mapped but resolves to no manifest`
+    );
+    for (const companion of companions) {
+      assert.ok(
+        resolveManifest(REPO_ROOT, companion),
+        `${subpath} names companion ${companion}, which resolves to no manifest`
+      );
+    }
+  }
+});
+
 // ---------------------------------------------------------------------------
 // AC-7 — third-party / local / docker references are never classified
 // ---------------------------------------------------------------------------

package/scripts/check-gitleaks-allowlist.test.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * check-gitleaks-allowlist.test.mjs — the secret-scan tier's escape hatch
+ * (Story #365).
+ *
+ * The failure this closes: the secret scan exposed no seam for suppressing a
+ * known false positive, so ordinary prose matching the generic-secret
+ * heuristic blocked a docs-only pull request with no option but rewording the
+ * source or turning the tier off. A required check needs an escape that is not
+ * disabling it.
+ *
+ * Reading the YAML is not enough: what decides the outcome is a shell branch,
+ * and the failure mode is silent — a caller-supplied config that quietly
+ * REPLACES the default ruleset would turn one suppression into a tier-wide
+ * opt-out that still reports green. So this extracts the real `run:` body and
+ * executes it against a stub gitleaks that echoes its argv, the same
+ * read-then-execute approach as check-setup-toolchain-store.test.mjs.
+ *
+ * Run: node --test scripts/check-gitleaks-allowlist.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { execFileSync } from "node:child_process";
+import { readFileSync, mkdtempSync, writeFileSync, chmodSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { stepByName, runScript } from "./lib/yaml-step.mjs";
+
+const ACTION = ".github/actions/gitleaks-scan/action.yml";
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+
+const actionText = readFileSync(ACTION, "utf8");
+const workflowText = readFileSync(WORKFLOW, "utf8");
+const scanScript = runScript(stepByName(actionText, "Run gitleaks scan"));
+
+/**
+ * The definition block of a single `workflow_call` input, keyed by name: every
+ * line indented under the `      <name>:` key. Asserts rather than returning a
+ * sentinel, so a renamed input fails at the point of extraction instead of
+ * silently passing an empty block to every downstream matcher.
+ */
+function workflowInput(name) {
+  const lines = workflowText.split("\n");
+  const start = lines.indexOf(`      ${name}:`);
+  assert.notEqual(start, -1, `workflow_call input "${name}" is not declared`);
+  const body = [];
+  for (let i = start + 1; i < lines.length && /^ {8,}\S/.test(lines[i]); i++) {
+    body.push(lines[i]);
+  }
+  return body.join("\n");
+}
+
+/**
+ * Run the extracted scan body against a stub gitleaks that echoes its argv and
+ * exits `leakExit` (non-zero = a finding). Returns `{ status, output }` rather
+ * than throwing, because a non-zero exit IS the assertion in the blocking
+ * cases.
+ */
+function runScan({ files = {}, leakExit = 0, ...env } = {}) {
+  const dir = mkdtempSync(path.join(tmpdir(), "gitleaks-allowlist-"));
+  try {
+    for (const [name, contents] of Object.entries(files)) {
+      writeFileSync(path.join(dir, name), contents);
+    }
+    const stub = path.join(dir, "gitleaks-stub");
+    writeFileSync(stub, `#!/bin/sh\necho "GITLEAKS_ARGV: $*"\nexit ${leakExit}\n`);
+    chmodSync(stub, 0o755);
+    const script = path.join(dir, "scan.sh");
+    writeFileSync(script, scanScript);
+
+    try {
+      const output = execFileSync("bash", [script], {
+        cwd: dir,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+          PATH: process.env.PATH,
+          GITLEAKS_BIN: stub,
+          SCAN_MODE: "dir",
+          LOG_OPTS: "",
+          REDACT: "100",
+          VERBOSE: "false",
+          REPORT_FORMAT: "",
+          REPORT_PATH: "",
+          NON_BLOCKING: "false",
+          CONFIG_PATH: "",
+          ALLOW_RULE_REPLACEMENT: "false",
+          ...env,
+        },
+      });
+      return { status: 0, output };
+    } catch (err) {
+      return {
+        status: err.status ?? 1,
+        output: `${err.stdout ?? ""}${err.stderr ?? ""}`,
+      };
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const EXTENDING_CONFIG = ['[extend]', 'useDefault = true', '', '[[rules]]', 'id = "x"'].join("\n");
+
+test("no config-path leaves the scan byte-for-byte as it was", () => {
+  const { status, output } = runScan();
+  assert.equal(status, 0);
+  assert.doesNotMatch(output, /--config/);
+  assert.match(output, /--redact=100/);
+});
+
+test("AC-7: a caller-supplied allowlist config is passed to gitleaks as --config", () => {
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": EXTENDING_CONFIG },
+    CONFIG_PATH: ".gitleaks.toml",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+  // The tier is still on: redaction and the scan itself are unchanged.
+  assert.match(output, /--redact=100/);
+});
+
+test("AC-7: the suppression seam works without disabling the tier or rewording the source", () => {
+  // The docs-only PR case: a config that allowlists the one false positive,
+  // scanned in the same blocking mode, with the source untouched.
+  const { status, output } = runScan({
+    files: {
+      ".gitleaks.toml": [
+        "[extend]",
+        "useDefault = true",
+        "",
+        "[[allowlists]]",
+        'description = "prose in docs/reusable-workflows.md"',
+        'paths = ["docs/reusable-workflows\\\\.md"]',
+      ].join("\n"),
+    },
+    CONFIG_PATH: ".gitleaks.toml",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+  assert.doesNotMatch(output, /non-blocking/);
+});
+
+test("AC-8: with a config in place, any other finding still fails the step", () => {
+  // The load-bearing half. An allowlist narrows one rule; it must not turn the
+  // gate into a reporter. A leak (stub exit 1) fails the step exactly as it
+  // does with no config at all.
+  const withConfig = runScan({
+    files: { ".gitleaks.toml": EXTENDING_CONFIG },
+    CONFIG_PATH: ".gitleaks.toml",
+    leakExit: 1,
+  });
+  assert.notEqual(withConfig.status, 0, "a finding must still fail the step");
+
+  const withoutConfig = runScan({ leakExit: 1 });
+  assert.equal(withConfig.status, withoutConfig.status);
+});
+
+test("AC-8: a config that replaces the default ruleset is rejected", () => {
+  // Without this guard, `--config` is a supported way to delete every rule and
+  // still report green — a tier-wide opt-out wearing an allowlist's clothes.
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": '[[rules]]\nid = "only-mine"\n' },
+    CONFIG_PATH: ".gitleaks.toml",
+  });
+  assert.equal(status, 1);
+  assert.match(output, /must extend the default ruleset/);
+  assert.match(output, /useDefault = true/);
+  assert.doesNotMatch(output, /GITLEAKS_ARGV/, "gitleaks must not run on a rejected config");
+});
+
+test("AC-8: useDefault must sit in [extend], not merely appear in the file", () => {
+  // The guard's one remaining bypass if it were a bare grep: gitleaks reads
+  // useDefault only from the [extend] table, so the same line under [[rules]]
+  // is inert — a rule-replacing config that reads as if it extended.
+  const { status, output } = runScan({
+    files: {
+      ".gitleaks.toml": ["[[rules]]", 'id = "only-mine"', "useDefault = true"].join("\n"),
+    },
+    CONFIG_PATH: ".gitleaks.toml",
+  });
+  assert.equal(status, 1);
+  assert.match(output, /must extend the default ruleset/);
+  assert.doesNotMatch(output, /GITLEAKS_ARGV/, "gitleaks must not run on a rejected config");
+});
+
+test("AC-7: [extend] is still honoured when other tables follow it", () => {
+  const { status, output } = runScan({
+    files: {
+      ".gitleaks.toml": [
+        "[extend]",
+        "useDefault = true",
+        "",
+        "[[allowlists]]",
+        'description = "prose"',
+      ].join("\n"),
+    },
+    CONFIG_PATH: ".gitleaks.toml",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+});
+
+test("a deliberate full rule-set replacement is possible, but only explicitly", () => {
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": '[[rules]]\nid = "only-mine"\n' },
+    CONFIG_PATH: ".gitleaks.toml",
+    ALLOW_RULE_REPLACEMENT: "true",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+});
+
+test("a config-path that does not exist is a hard error, not a silently-skipped flag", () => {
+  const { status, output } = runScan({ CONFIG_PATH: "nope.toml" });
+  assert.equal(status, 1);
+  assert.match(output, /does not exist in the checkout/);
+  assert.doesNotMatch(output, /GITLEAKS_ARGV/);
+});
+
+test("AC-3: a repo-root .gitleaks.toml is validated instead of silently auto-discovered", () => {
+  // gitleaks reads a repo-root .gitleaks.toml on its own whenever --config is
+  // absent. Left alone, that is a second, UNVALIDATED way into the scan — the
+  // useDefault guard never runs. The file is adopted as config-path instead.
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": EXTENDING_CONFIG },
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+});
+
+test("AC-3: a rule-replacing repo-root .gitleaks.toml is rejected, naming config-path", () => {
+  // The bypass this closes. Auto-discovery would have applied this config —
+  // which deletes every default rule — and reported green.
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": '[[rules]]\nid = "only-mine"\n' },
+  });
+  assert.equal(status, 1);
+  assert.match(output, /must extend the default ruleset/);
+  assert.match(output, /config-path/);
+  assert.doesNotMatch(output, /GITLEAKS_ARGV/, "gitleaks must not run on a rejected config");
+});
+
+// Not AC-3 evidence: this passes with the discovery branch reverted, because
+// nothing ever routed a root file when config-path was set. It is a regression
+// guard for one plausible mis-write of that branch — omitting its `[ -z
+// "$CONFIG_PATH" ]` condition — and should not be read as proving AC-3.
+test("an explicit config-path still wins over a repo-root .gitleaks.toml", () => {
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": EXTENDING_CONFIG, "custom.toml": EXTENDING_CONFIG },
+    CONFIG_PATH: "custom.toml",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config custom\.toml/);
+  assert.doesNotMatch(output, /--config \.gitleaks\.toml/);
+});
+
+test("AC-3: a deliberate rule-replacing root config still opts in explicitly", () => {
+  const { status, output } = runScan({
+    files: { ".gitleaks.toml": '[[rules]]\nid = "only-mine"\n' },
+    ALLOW_RULE_REPLACEMENT: "true",
+  });
+  assert.equal(status, 0);
+  assert.match(output, /--config \.gitleaks\.toml/);
+});
+
+test("AC-1: pr-quality.yml declares both allowlist inputs with unchanged-behaviour defaults", () => {
+  // pr-quality.yml is compile-time resolved for every consumer, so a caller
+  // that passes neither input must get byte-identical behaviour: '' and
+  // 'false' are exactly the composite's own defaults.
+  const configPath = workflowInput("secret-scan-config-path");
+  assert.match(configPath, /^ {8}type: string$/m);
+  assert.match(configPath, /^ {8}default: ''$/m);
+
+  const allowReplacement = workflowInput("secret-scan-allow-default-rule-replacement");
+  assert.match(allowReplacement, /^ {8}type: string$/m);
+  assert.match(allowReplacement, /^ {8}default: 'false'$/m);
+
+  // Cross-repo portability contract (scripts/check-workflow-portability.mjs):
+  // no `${{ }}` in a workflow_call input description or default — GitHub
+  // resolves those during interface validation, before any context exists.
+  assert.doesNotMatch(configPath, /\$\{\{/);
+  assert.doesNotMatch(allowReplacement, /\$\{\{/);
+});
+
+test("AC-2: both caller inputs reach the gitleaks composite's own inputs", () => {
+  // The whole point of the Story: an input a consumer can set has to arrive at
+  // the composite, or the documented escape from a false positive is
+  // unreachable and `enable-security: false` stays the only exit.
+  const step = stepByName(workflowText, "Secret scan (pinned gitleaks, blocking)");
+  assert.match(step, /^\s+config-path: \$\{\{ inputs\.secret-scan-config-path \}\}$/m);
+  assert.match(
+    step,
+    /^\s+allow-default-rule-replacement: \$\{\{ inputs\.secret-scan-allow-default-rule-replacement \}\}$/m,
+  );
+});
+
+test("the action declares both inputs with the non-breaking empty/false defaults", () => {
+  // A consumer that passes neither input must be unaffected — the whole reason
+  // the defaults are '' and 'false'.
+  assert.match(actionText, /^ {2}config-path:$/m);
+  assert.match(actionText, /^ {2}allow-default-rule-replacement:$/m);
+  // Cross-repo portability contract: no `${{ }}` in input descriptions or
+  // defaults (scripts/check-workflow-portability.mjs).
+  const inputsBlock = actionText.slice(
+    actionText.indexOf("\ninputs:"),
+    actionText.indexOf("\nruns:"),
+  );
+  assert.doesNotMatch(inputsBlock, /\$\{\{/);
+});