mandrel-platform 0.17.2 → 0.19.0

package/scripts/platform-sync.test.mjs

@@ -12,6 +12,12 @@
  *      overrides preserved),
  *   4. idempotency + `--dry-run` non-mutation.
  *
+ * Also exercises the two GitHub-side drift-check modes, which short-circuit
+ * the local-checkout sync above and operate over the GitHub API instead:
+ *   5. `--check-settings` / `--apply-settings` (Story #171, repo settings).
+ *   6. `--check-ruleset` (Story #178, branch rulesets — report-only, no
+ *      `--apply-ruleset`).
+ *
  * Run: node scripts/platform-sync.test.mjs   (or `node --test scripts/`)
  */
 
@@ -76,6 +82,7 @@ test("--dry-run does not mutate any file", () => {
   const after = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
   assert.equal(after, before, "ci.yml must be untouched in dry-run");
   assert.ok(!existsSync(join(consumer, "docs", "runbooks", "observability.md")));
+  assert.ok(!existsSync(join(consumer, ".github", "workflows", "deploy-staging.yml")));
 });
 
 test("apply pins first-party SHAs, leaves external actions untouched", () => {
@@ -87,6 +94,38 @@ test("apply pins first-party SHAs, leaves external actions untouched", () => {
   assert.ok(ci.includes(`actions/checkout@${"2".repeat(40)} # external`), "external action untouched");
 });
 
+test("ciNaming: flags a non-canonical job id (seeded fixture uses job id 'q', not 'ci')", () => {
+  const out = JSON.parse(run([]));
+  assert.equal(out.ciNaming.status, "non-canonical");
+  assert.match(out.ciNaming.message, /no "ci" job id/);
+});
+
+test("ciNaming: reports 'no-canonical-file' when no ci.yml exists", () => {
+  rmSync(join(consumer, ".github", "workflows", "ci.yml"));
+  const out = JSON.parse(run([]));
+  assert.equal(out.ciNaming.status, "no-canonical-file");
+});
+
+test("ciNaming: reports 'canonical' when ci.yml matches the triplet (display name CI + job id ci)", () => {
+  writeFileSync(
+    join(consumer, ".github", "workflows", "ci.yml"),
+    ["name: CI", "jobs:", "  ci:", "    steps:", "      - run: echo hi", ""].join("\n")
+  );
+  const out = JSON.parse(run([]));
+  assert.equal(out.ciNaming.status, "canonical");
+  assert.equal(out.ciNaming.message, null);
+});
+
+test("ciNaming never mutates ci.yml — it is advisory only", () => {
+  const before = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
+  run([]);
+  const after = readFileSync(join(consumer, ".github", "workflows", "ci.yml"), "utf8");
+  // Only the pin rewrite (already covered above) may change bytes; re-read the
+  // *naming* fields specifically — name:/job id text must be byte-identical.
+  assert.equal(before.match(/^name:.*$/m)?.[0], after.match(/^name:.*$/m)?.[0]);
+  assert.equal(before.includes("  q:"), after.includes("  q:"));
+});
+
 test("apply materializes runbook reference stubs (link, don't copy)", () => {
   run([]);
   const stub = join(consumer, "docs", "runbooks", "deploy-promotion.md");
@@ -138,3 +177,441 @@ test("an existing reference stub is skipped idempotently", () => {
   assert.ok(out.runbooks.skipped.length >= 8, "already-present stubs are skipped, not re-created");
   assert.equal(out.runbooks.created.length, 0);
 });
+
+// ---------------------------------------------------------------------------
+// --check-settings / --apply-settings (Story #171)
+//
+// platform-sync.mjs shells out to the real `gh` CLI for the GitHub-side
+// settings mode (no dependency-injection seam like check-pin-drift.mjs), so
+// these tests stub `gh` as a fake executable on PATH and drive the CLI
+// end-to-end. The pure diff/classification logic itself is unit-tested in
+// check-repo-settings.test.mjs; this suite exercises platform-sync's own
+// argument wiring, PATCH-call shape, and non-blocking exit-code contract.
+// ---------------------------------------------------------------------------
+
+let settingsDir;
+let fakeGhDir;
+let fakeGhLogPath;
+
+/**
+ * Write a fake `gh` shell script onto a scratch PATH dir that:
+ *   - responds to `gh api repos/<repo>` and `gh api repos/<repo>/actions/permissions/workflow`
+ *     with the JSON bodies given in `responses` (keyed by the API path),
+ *   - logs every invocation's args (one JSON line per call) to `fakeGhLogPath`
+ *     so PATCH calls can be asserted on,
+ *   - exits 0 for any recognized `gh api ...` / `gh api -X PATCH ...` call.
+ */
+function writeFakeGh(responses) {
+  const script = `#!/usr/bin/env node
+const fs = require("node:fs");
+const args = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(fakeGhLogPath)}, JSON.stringify(args) + "\\n");
+const responses = ${JSON.stringify(responses)};
+if (args[0] === "api") {
+  const isPatch = args[1] === "-X" && args[2] === "PATCH";
+  const path = isPatch ? args[3] : args[1];
+  if (isPatch) {
+    process.exit(0);
+  }
+  if (Object.prototype.hasOwnProperty.call(responses, path)) {
+    process.stdout.write(JSON.stringify(responses[path]));
+    process.exit(0);
+  }
+  process.stderr.write("no stub for " + path + "\\n");
+  process.exit(1);
+}
+process.exit(1);
+`;
+  const ghPath = join(fakeGhDir, "gh");
+  writeFileSync(ghPath, script, { mode: 0o755 });
+}
+
+function runSettings(extraArgs) {
+  return execFileSync("node", [CLI, ...extraArgs], {
+    encoding: "utf8",
+    env: { ...process.env, PATH: `${fakeGhDir}:${process.env.PATH}` },
+  });
+}
+
+const BASELINE_SETTINGS = {
+  allowSquashMerge: true,
+  allowMergeCommit: false,
+  allowRebaseMerge: false,
+  squashMergeCommitTitle: "PR_TITLE",
+  squashMergeCommitMessage: "PR_BODY",
+  deleteBranchOnMerge: true,
+  allowAutoMerge: true,
+  actionsDefaultWorkflowPermissions: "read",
+  actionsCanApprovePullRequestReviews: false,
+};
+
+beforeEach(() => {
+  settingsDir = mkdtempSync(join(tmpdir(), "platform-sync-settings-test-"));
+  fakeGhDir = mkdtempSync(join(tmpdir(), "platform-sync-fakegh-"));
+  fakeGhLogPath = join(settingsDir, "gh-calls.log");
+  writeFileSync(fakeGhLogPath, "");
+  writeFileSync(join(settingsDir, "baseline.json"), JSON.stringify(BASELINE_SETTINGS));
+});
+
+afterEach(() => {
+  rmSync(settingsDir, { recursive: true, force: true });
+  rmSync(fakeGhDir, { recursive: true, force: true });
+});
+
+test("--check-settings reports no drift when live settings match the baseline", () => {
+  writeFakeGh({
+    "repos/dsj1984/swarm-os": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/swarm-os/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+  const out = JSON.parse(
+    runSettings([
+      "--check-settings",
+      "--consumer-repo",
+      "dsj1984/swarm-os",
+      "--baseline",
+      join(settingsDir, "baseline.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.mode, "check-settings");
+  assert.equal(out.drift, false);
+  assert.deepEqual(out.mismatches, []);
+});
+
+test("--check-settings reports drift (domio-shaped: write token perms) without mutating anything", () => {
+  writeFakeGh({
+    "repos/dsj1984/domio": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/domio/actions/permissions/workflow": {
+      default_workflow_permissions: "write",
+      can_approve_pull_request_reviews: false,
+    },
+  });
+  const out = JSON.parse(
+    runSettings([
+      "--check-settings",
+      "--consumer-repo",
+      "dsj1984/domio",
+      "--baseline",
+      join(settingsDir, "baseline.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.drift, true);
+  assert.deepEqual(out.mismatches, [
+    { field: "actionsDefaultWorkflowPermissions", expected: "read", actual: "write" },
+  ]);
+  assert.equal(out.applied, false, "--check-settings never applies");
+  const calls = readFileSync(fakeGhLogPath, "utf8").trim().split("\n").filter(Boolean);
+  assert.ok(
+    calls.every((line) => !JSON.parse(line).includes("PATCH")),
+    "no PATCH call issued by --check-settings"
+  );
+});
+
+test("--check-settings never fails the exit code on drift (non-blocking, standing decision #10)", () => {
+  writeFakeGh({
+    "repos/dsj1984/athportal": {
+      allow_squash_merge: true,
+      allow_merge_commit: true,
+      allow_rebase_merge: true,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "COMMIT_MESSAGES",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/athportal/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: true,
+    },
+  });
+  // execFileSync throws on non-zero exit; a clean return proves exit 0.
+  assert.doesNotThrow(() => {
+    runSettings([
+      "--check-settings",
+      "--consumer-repo",
+      "dsj1984/athportal",
+      "--baseline",
+      join(settingsDir, "baseline.json"),
+      "--json",
+    ]);
+  });
+});
+
+test("--apply-settings PATCHes only the drifted fields, across both endpoints", () => {
+  writeFakeGh({
+    "repos/dsj1984/athportal": {
+      allow_squash_merge: true,
+      allow_merge_commit: true, // drift
+      allow_rebase_merge: true, // drift
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/athportal/actions/permissions/workflow": {
+      default_workflow_permissions: "read",
+      can_approve_pull_request_reviews: true, // drift
+    },
+  });
+  const out = JSON.parse(
+    runSettings([
+      "--apply-settings",
+      "--consumer-repo",
+      "dsj1984/athportal",
+      "--baseline",
+      join(settingsDir, "baseline.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.applied, true);
+  assert.equal(out.mismatches.length, 3);
+
+  const calls = readFileSync(fakeGhLogPath, "utf8")
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l));
+  const patchCalls = calls.filter((c) => c[1] === "-X" && c[2] === "PATCH");
+  assert.equal(patchCalls.length, 2, "one PATCH for the repo endpoint, one for the Actions endpoint");
+  const repoPatch = patchCalls.find((c) => c[3] === "repos/dsj1984/athportal");
+  const actionsPatch = patchCalls.find((c) => c[3] === "repos/dsj1984/athportal/actions/permissions/workflow");
+  assert.ok(repoPatch, "repo-settings PATCH issued");
+  assert.ok(actionsPatch, "Actions-permissions PATCH issued");
+});
+
+test("--apply-settings --dry-run reports the plan without issuing any PATCH", () => {
+  writeFakeGh({
+    "repos/dsj1984/domio": {
+      allow_squash_merge: true,
+      allow_merge_commit: false,
+      allow_rebase_merge: false,
+      squash_merge_commit_title: "PR_TITLE",
+      squash_merge_commit_message: "PR_BODY",
+      delete_branch_on_merge: true,
+      allow_auto_merge: true,
+    },
+    "repos/dsj1984/domio/actions/permissions/workflow": {
+      default_workflow_permissions: "write", // drift
+      can_approve_pull_request_reviews: false,
+    },
+  });
+  const out = JSON.parse(
+    runSettings([
+      "--apply-settings",
+      "--dry-run",
+      "--consumer-repo",
+      "dsj1984/domio",
+      "--baseline",
+      join(settingsDir, "baseline.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.dryRun, true);
+  assert.equal(out.applied, false, "dry-run never applies");
+  const calls = readFileSync(fakeGhLogPath, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+  assert.ok(
+    calls.every((c) => !(c[1] === "-X" && c[2] === "PATCH")),
+    "no PATCH issued under --dry-run"
+  );
+});
+
+test("--check-settings requires --consumer-repo", () => {
+  assert.throws(() => {
+    execFileSync("node", [CLI, "--check-settings"], { encoding: "utf8" });
+  }, /consumer-repo/);
+});
+
+// ---------------------------------------------------------------------------
+// --check-ruleset (Story #178) — report-only branch-ruleset drift check.
+//
+// Same fake-`gh`-on-PATH harness as --check-settings above. The pure
+// diff/classification logic is unit-tested in check-ruleset.test.mjs; this
+// suite exercises platform-sync's own argument wiring and the (deliberate)
+// absence of any mutating call — there is no --apply-ruleset.
+// ---------------------------------------------------------------------------
+
+const MAIN_PROTECTION_CONTRACT = {
+  branch: "main",
+  requiredStatusChecks: ["ci-required"],
+  requireLinearHistory: false,
+  allowForcePushes: false,
+  allowDeletions: false,
+};
+
+function compliantRulesetPayload() {
+  return {
+    id: 1,
+    enforcement: "active",
+    conditions: { ref_name: { include: ["refs/heads/main"] } },
+    bypass_actors: [],
+    rules: [
+      { type: "pull_request" },
+      {
+        type: "required_status_checks",
+        parameters: {
+          required_status_checks: [{ context: "ci-required" }],
+          strict_required_status_checks_policy: true,
+        },
+      },
+      { type: "non_fast_forward" },
+      { type: "deletion" },
+    ],
+  };
+}
+
+test("--check-ruleset reports no drift when the live ruleset matches the contract", () => {
+  writeFakeGh({
+    "repos/Beestera/swarm-os/rulesets": [{ id: 1 }],
+    "repos/Beestera/swarm-os/rulesets/1": compliantRulesetPayload(),
+  });
+  writeFileSync(join(settingsDir, "contract.json"), JSON.stringify(MAIN_PROTECTION_CONTRACT));
+  const out = JSON.parse(
+    runSettings([
+      "--check-ruleset",
+      "--consumer-repo",
+      "Beestera/swarm-os",
+      "--contract",
+      join(settingsDir, "contract.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.mode, "check-ruleset");
+  assert.equal(out.drift, false);
+  assert.deepEqual(out.mismatches, []);
+});
+
+test("--check-ruleset reports drift (bypass actor added) and issues no mutating call", () => {
+  writeFakeGh({
+    "repos/dsj1984/domio/rulesets": [{ id: 7 }],
+    "repos/dsj1984/domio/rulesets/7": { ...compliantRulesetPayload(), bypass_actors: [{ actor_id: 1 }] },
+  });
+  writeFileSync(join(settingsDir, "contract.json"), JSON.stringify(MAIN_PROTECTION_CONTRACT));
+  const out = JSON.parse(
+    runSettings([
+      "--check-ruleset",
+      "--consumer-repo",
+      "dsj1984/domio",
+      "--contract",
+      join(settingsDir, "contract.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.drift, true);
+  assert.deepEqual(out.mismatches, [{ field: "bypassActorsEmpty", expected: true, actual: false }]);
+  const calls = readFileSync(fakeGhLogPath, "utf8").trim().split("\n").filter(Boolean);
+  assert.ok(
+    calls.every((line) => !JSON.parse(line).includes("PATCH")),
+    "--check-ruleset never issues a PATCH — report-only, no --apply-ruleset exists"
+  );
+});
+
+test("--check-ruleset never fails the exit code on drift (non-blocking, standing decision #10)", () => {
+  writeFakeGh({
+    "repos/dsj1984/athportal/rulesets": [{ id: 1 }],
+    "repos/dsj1984/athportal/rulesets/1": {
+      ...compliantRulesetPayload(),
+      rules: compliantRulesetPayload().rules.filter((r) => r.type !== "non_fast_forward"),
+    },
+  });
+  writeFileSync(join(settingsDir, "contract.json"), JSON.stringify(MAIN_PROTECTION_CONTRACT));
+  assert.doesNotThrow(() => {
+    runSettings([
+      "--check-ruleset",
+      "--consumer-repo",
+      "dsj1984/athportal",
+      "--contract",
+      join(settingsDir, "contract.json"),
+      "--json",
+    ]);
+  });
+});
+
+test("--check-ruleset reports 'missing' when no active ruleset targets the branch", () => {
+  writeFakeGh({
+    "repos/owner/no-ruleset/rulesets": [],
+  });
+  writeFileSync(join(settingsDir, "contract.json"), JSON.stringify(MAIN_PROTECTION_CONTRACT));
+  const out = JSON.parse(
+    runSettings([
+      "--check-ruleset",
+      "--consumer-repo",
+      "owner/no-ruleset",
+      "--contract",
+      join(settingsDir, "contract.json"),
+      "--json",
+    ])
+  );
+  assert.equal(out.status, "missing");
+  assert.equal(out.drift, true);
+});
+
+test("--check-ruleset requires --consumer-repo", () => {
+  assert.throws(() => {
+    execFileSync("node", [CLI, "--check-ruleset"], { encoding: "utf8" });
+  }, /consumer-repo/);
+});
+
+test("apply materializes the canonical deploy-staging.yml workflow caller template", () => {
+  const out = JSON.parse(run([]));
+  const stub = join(consumer, ".github", "workflows", "deploy-staging.yml");
+  assert.ok(existsSync(stub));
+  assert.ok(
+    out.workflowStubs.created.some((f) => f.endsWith("deploy-staging.yml")),
+    "deploy-staging.yml reported as created"
+  );
+  const body = readFileSync(stub, "utf8");
+  assert.ok(
+    body.includes("Canonical staging-deploy caller template"),
+    "materialized workflow carries the template marker"
+  );
+  assert.ok(
+    body.includes("dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml"),
+    "template calls the shared deploy-cloudflare.yml reusable workflow"
+  );
+});
+
+test("workflow caller template materialization is idempotent", () => {
+  run([]); // materialize
+  const out = JSON.parse(run([])); // second pass
+  assert.ok(
+    out.workflowStubs.skipped.some((f) => f.endsWith("deploy-staging.yml")),
+    "already-materialized template is skipped, not re-created"
+  );
+  assert.equal(out.workflowStubs.created.length, 0);
+});
+
+test("a hand-authored deploy-staging.yml is flagged, not overwritten", () => {
+  const destDir = join(consumer, ".github", "workflows");
+  mkdirSync(destDir, { recursive: true });
+  const handAuthored = "name: deploy-staging\n# fully custom, no template marker\njobs: {}\n";
+  writeFileSync(join(destDir, "deploy-staging.yml"), handAuthored);
+  const out = JSON.parse(run([]));
+  assert.ok(
+    out.workflowStubs.localCopies.some((f) => f.endsWith("deploy-staging.yml")),
+    "hand-authored caller surfaced as a warning"
+  );
+  assert.equal(
+    readFileSync(join(destDir, "deploy-staging.yml"), "utf8"),
+    handAuthored,
+    "operator's hand-authored caller is never clobbered"
+  );
+});

package/scripts/update-semgrep-rules.mjs

@@ -50,16 +50,18 @@
  *   node scripts/update-semgrep-rules.mjs --semgrep-pin semgrep==1.97.0
  *   node scripts/update-semgrep-rules.mjs --out .semgrep/rules.json --dry-run
  *
- * Requires network egress to PyPI (to install the pinned `semgrep` package)
- * and to the Semgrep registry (to resolve `p/default`) — this script is run
- * by a human/agent deliberately bumping the ruleset, NOT by CI on every PR.
+ * Requires network egress to PyPI (to install the pinned `semgrep` package,
+ * whose artifact is verified against the recorded SHA-256 hashes via pip's
+ * `--require-hashes`) and to the Semgrep registry (to resolve `p/default`) —
+ * this script is run by a human/agent deliberately bumping the ruleset, NOT
+ * by CI on every PR.
  *
  * Exit codes:
  *   0 — rules file written (or, with --dry-run, would-write reported).
  *   1 — semgrep install or rule resolution failed.
  */
 
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -75,6 +77,26 @@ const REPO_ROOT = resolve(__dirname, "..");
 // generate the file is a (harmless but inconsistent) version skew.
 const DEFAULT_SEMGREP_PIN = "semgrep==1.97.0";
 
+// SHA-256 hashes for every `DEFAULT_SEMGREP_PIN` distribution published on
+// PyPI (the four platform wheels + the sdist). pip's `--require-hashes` mode
+// verifies the downloaded `semgrep` artifact against this set before it is
+// installed, so a compromised or swapped PyPI artifact for this exact version
+// is rejected at install time — the same "pin the supply-chain input" posture
+// the action-pin ratchet (SHA-pinned Actions) and the OSV advisory pin apply
+// to their inputs. When bumping `DEFAULT_SEMGREP_PIN`, refresh this map from
+// `https://pypi.org/pypi/semgrep/<version>/json` (the `urls[].digests.sha256`
+// values) — a version with no hash entry here fails fast rather than
+// installing unverified.
+const SEMGREP_HASHES = {
+  "1.97.0": [
+    "sha256:0ddaa25ee45e669e1fef87e88dcef73b2aee0874b507e09f618862c42452a205",
+    "sha256:9184500bf8c49ad19d0fb2d84923abb4aa53058b0ece7008b57a3b0b5e6ce3ee",
+    "sha256:f7d21d6499d4e6fafb4c0b04b1750e9f4b704a26bd78f0aff19f1c73d44843b4",
+    "sha256:996fe0b2bfac3a4d4511e470fdf5f3bca96b1f794f398e0336c8388802c218de",
+    "sha256:c585164358e03cd7868e1f0d38fbcb422c88dbe08795b83caeb5e36cf18874aa",
+  ],
+};
+
 const DEFAULT_OUT = join(REPO_ROOT, ".semgrep", "rules.json");
 
 // Languages this platform's reusable workflows + consumer trees actually
@@ -143,19 +165,67 @@ function resolveRegistryRules(semgrepPin) {
   const venvDir = join(mkdtempSync(join(tmpdir(), "semgrep-vendor-")), "venv");
   const targetDir = mkdtempSync(join(tmpdir(), "semgrep-vendor-target-"));
   const semgrepHome = mkdtempSync(join(tmpdir(), "semgrep-vendor-home-"));
+  const reqsFile = join(mkdtempSync(join(tmpdir(), "semgrep-vendor-reqs-")), "semgrep.txt");
 
   try {
     spawnSync("python3", ["-m", "venv", venvDir], { stdio: "inherit" });
     const pip = join(venvDir, "bin", "pip");
     const semgrep = join(venvDir, "bin", "semgrep");
 
+    // Resolve the exact version from the pin (`semgrep==<version>`) so we can
+    // look up its published artifact hashes. Only the `==` form is hashable;
+    // an unpinned or range pin cannot be verified.
+    const versionMatch = /^semgrep==(.+)$/.exec(semgrepPin.trim());
+    if (!versionMatch) {
+      throw new Error(
+        `cannot hash-pin ${semgrepPin}: only an exact 'semgrep==<version>' pin is supported`
+      );
+    }
+    const version = versionMatch[1];
+    const hashes = SEMGREP_HASHES[version];
+    if (!hashes || hashes.length === 0) {
+      throw new Error(
+        `no published artifact hashes recorded for ${semgrepPin} in SEMGREP_HASHES — ` +
+          `refresh from https://pypi.org/pypi/semgrep/${version}/json before pinning`
+      );
+    }
+
+    // Hash-pinned install: write a requirements file that pins `semgrep` to
+    // the exact version with every published artifact hash, then install it
+    // with `--require-hashes --no-deps`. pip verifies the downloaded semgrep
+    // artifact against this set before installing — a swapped/compromised
+    // artifact for this version is rejected. Dependencies are resolved in a
+    // separate, non-hashed step (semgrep is already satisfied), keeping the
+    // supply-chain-critical `semgrep` binary itself hash-verified.
+    const hashFlags = hashes.map((h) => `    --hash=${h}`).join(" \\\n");
+    writeFileSync(reqsFile, `semgrep==${version} \\\n${hashFlags}\n`, "utf8");
+
+    const installSemgrep = spawnSync(
+      pip,
+      [
+        "install",
+        "--quiet",
+        "--disable-pip-version-check",
+        "--require-hashes",
+        "--no-deps",
+        "-r",
+        reqsFile,
+      ],
+      { stdio: "inherit" }
+    );
+    if (installSemgrep.status !== 0) {
+      throw new Error(
+        `hash-pinned pip install ${semgrepPin} failed (exit ${installSemgrep.status})`
+      );
+    }
+
     const install = spawnSync(
       pip,
       ["install", "--quiet", "--disable-pip-version-check", "setuptools", semgrepPin],
       { stdio: "inherit" }
     );
     if (install.status !== 0) {
-      throw new Error(`pip install ${semgrepPin} failed (exit ${install.status})`);
+      throw new Error(`pip install ${semgrepPin} (dependencies) failed (exit ${install.status})`);
     }
 
     // A throwaway target file gives semgrep something to "scan" so it
@@ -196,6 +266,7 @@ function resolveRegistryRules(semgrepPin) {
     rmSync(venvDir, { recursive: true, force: true });
     rmSync(targetDir, { recursive: true, force: true });
     rmSync(semgrepHome, { recursive: true, force: true });
+    rmSync(dirname(reqsFile), { recursive: true, force: true });
   }
 }
 

package/templates/runbooks/README.md

@@ -1,10 +1,14 @@
 # Runbook Templates (copyable thin stubs)
 
-These are **copyable thin-stub templates** — one per canonical mandrel-platform
-runbook in [`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks).
-They implement the MP-9 adoption model (§7.7 / F1): *replace each duplicated
-process runbook with a thin local doc that holds project-specific values plus a
-link to the canonical runbook.*
+These are **copyable thin-stub templates** for the eight most commonly-adopted
+canonical mandrel-platform runbooks in
+[`docs/runbooks/`](https://github.com/dsj1984/mandrel-platform/tree/main/docs/runbooks)
+(listed in the table below). It is **not** a stub-per-canonical-runbook set —
+several canonical runbooks (`rollback.md`, `slo.md`, `secret-rotation.md`,
+`pin-drift-dashboard.md`) are platform-process docs a consumer reads directly
+and ships no local stub for. They implement the MP-9 adoption model
+(§7.7 / F1): *replace each duplicated process runbook with a thin local doc
+that holds project-specific values plus a link to the canonical runbook.*
 
 Each stub:
 

package/templates/runbooks/branch-protection-setup.md

@@ -21,9 +21,15 @@
 ## Apply & Verify
 
 ```bash
-# Preview / apply
-node scripts/apply-branch-protection.mjs --dry-run
-node scripts/apply-branch-protection.mjs --apply
+# Apply — PUT the protection with the aggregator as the only required context.
+# (There is no apply-branch-protection script; use gh api directly — see the
+# canonical runbook § 3.)
+gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \
+  --method PUT \
+  --raw-field required_status_checks='{"strict":false,"contexts":["<AGGREGATOR_CHECK>"]}' \
+  --field enforce_admins=false \
+  --raw-field required_pull_request_reviews=null \
+  --raw-field restrictions=null
 
 # Verify
 gh api repos/<OWNER>/<REPO>/branches/<PROTECTED_BRANCH>/protection \