mandrel-platform 0.28.0 → 0.29.1

package/package.json

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

package/scripts/check-affected-mode.test.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * check-affected-mode.test.mjs — YAML-level regression guard for the
+ * affected-mode wiring in `.github/workflows/pr-quality.yml` (Story #319,
+ * follow-up to #314/#315).
+ *
+ * `scripts/resolve-diff-range.sh` has solid unit coverage
+ * (`resolve-diff-range.test.mjs`), but the affected-mode *wiring* inside the
+ * reusable workflow was only covered indirectly by anchor-expansion checks.
+ * This suite pins the three invariants that keep the affected-mode design
+ * correct, modelled on the sibling `check-ci-required-aggregator.test.mjs`
+ * (read the real workflow, extract blocks by indentation, assert):
+ *
+ *   1. GATING — the coverage-gate steps (`Checkout gate scripts`, `Coverage
+ *      threshold gate`) carry `inputs.coverage-threshold != 0 && !inputs.affected`,
+ *      and the bypass `::notice::` step carries the *complementary*
+ *      `inputs.coverage-threshold != 0 && inputs.affected`. A drift that drops
+ *      `!inputs.affected` (which would false-fail the whole-repo floor on an
+ *      affected subset) fails this suite.
+ *   2. NO EXPORT ON mode=none — executing the resolve-affected `run:` script
+ *      with an unresolved (`mode=none`) range leaves `TURBO_SCM_*` unset, so
+ *      turbo falls back to its own default rather than a bogus range.
+ *   3. INJECTION-SAFE EXPORT (Story #319 hardening) — a newline-bearing
+ *      `affected-base` override is rejected before the `$GITHUB_ENV` write, so
+ *      it can never inject a second env line; a single-line override exports
+ *      exactly `TURBO_SCM_BASE` / `TURBO_SCM_HEAD` and nothing else.
+ *
+ * The `run:` script is executed against real bash with a stubbed
+ * `resolve-diff-range.sh` (the sourced derivation), so no git repo is needed;
+ * skipped when bash is unavailable locally (CI's ubuntu runner always has it).
+ *
+ * Run: node --test scripts/check-affected-mode.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+const content = readFileSync(join(repoRoot, WORKFLOW), "utf8");
+
+// ---------------------------------------------------------------------------
+// Minimal indentation-based extraction (dependency-free, mirrors
+// check-ci-required-aggregator.test.mjs). A step spans from its `- ` bullet to
+// the next sibling bullet at the same indent (or a dedent below it).
+// ---------------------------------------------------------------------------
+
+function stepByName(text, name) {
+  const lines = text.split("\n");
+  const nameIdx = lines.findIndex((l) => /^\s+(- )?name:\s/.test(l) && l.includes(name));
+  assert.notEqual(nameIdx, -1, `step "${name}" not found`);
+  let start = -1;
+  for (let i = nameIdx; i >= 0; i--) {
+    if (/^\s*-\s/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  assert.notEqual(start, -1, `opening bullet for step "${name}" not found`);
+  const bulletIndent = lines[start].match(/^(\s*)/)[1].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent < bulletIndent) {
+      end = i;
+      break;
+    }
+    if (indent === bulletIndent && /^\s*-\s/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The (first) `if:` expression on a step block, trimmed. */
+function ifCondition(stepBlock) {
+  const m = stepBlock.match(/^\s+if:\s*(.+?)\s*$/m);
+  assert.ok(m, "step has no `if:` condition");
+  return m[1].trim();
+}
+
+/** The dedented body of the step's `run: |` block scalar. */
+function runScript(stepBlock) {
+  const lines = stepBlock.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// 1. GATING — coverage-gate steps gated OUT of affected mode; bypass step gated IN
+// ---------------------------------------------------------------------------
+
+test("resolve-affected step runs only in affected mode", () => {
+  const cond = ifCondition(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+  assert.match(cond, /inputs\.affected/, "the resolve step must be gated on `inputs.affected`");
+  assert.doesNotMatch(cond, /!\s*inputs\.affected/, "the resolve step must not be negated");
+});
+
+for (const step of ["Checkout gate scripts (mandrel-platform@resolved-sha)", "Coverage threshold gate"]) {
+  test(`coverage-gate step "${step}" is gated OUT of affected mode`, () => {
+    const cond = ifCondition(stepByName(content, step));
+    assert.match(
+      cond,
+      /inputs\.coverage-threshold != 0/,
+      "must still require a non-zero coverage-threshold"
+    );
+    assert.match(
+      cond,
+      /!\s*inputs\.affected/,
+      "must carry `!inputs.affected` — dropping it false-fails the whole-repo floor on an affected subset"
+    );
+  });
+}
+
+test("bypass `::notice::` step carries the complementary affected-mode gating", () => {
+  const step = stepByName(content, "Coverage floor bypassed (affected mode)");
+  const cond = ifCondition(step);
+  assert.match(cond, /inputs\.coverage-threshold != 0/, "must require a non-zero coverage-threshold");
+  assert.match(cond, /&&\s*inputs\.affected/, "must fire only in affected mode");
+  assert.doesNotMatch(
+    cond,
+    /!\s*inputs\.affected/,
+    "the bypass notice must be the complement of the gate — never negated"
+  );
+  assert.match(step, /::notice title=/, "the bypass must emit a visible ::notice::, never a silent skip");
+});
+
+// ---------------------------------------------------------------------------
+// 2 & 3. Execute the resolve-affected run script against real bash.
+// ---------------------------------------------------------------------------
+
+function bashAvailable() {
+  try {
+    execFileSync("bash", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const RESOLVE_SCRIPT = runScript(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+
+/**
+ * Run the extracted resolve-affected `run:` body with a stubbed
+ * resolve-diff-range.sh that sets RESOLVED_* from STUB_* env, capturing the
+ * lines the step wrote to $GITHUB_ENV.
+ */
+function runResolve({ mode = "", base = "", head = "", override } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "affected-mode-"));
+  try {
+    const workspace = join(dir, "ws");
+    mkdirSync(join(workspace, "_mandrel-platform-range", "scripts"), { recursive: true });
+    // Stub the sourced derivation: RESOLVED_* come from STUB_* env.
+    writeFileSync(
+      join(workspace, "_mandrel-platform-range", "scripts", "resolve-diff-range.sh"),
+      ['RESOLVED_EVENT_MODE="${STUB_MODE-}"', 'RESOLVED_BASE_SHA="${STUB_BASE-}"', 'RESOLVED_HEAD_SHA="${STUB_HEAD-}"', ""].join("\n")
+    );
+    const scriptFile = join(dir, "resolve.sh");
+    writeFileSync(scriptFile, RESOLVE_SCRIPT);
+    const envFile = join(dir, "github_env");
+    writeFileSync(envFile, "");
+
+    const env = {
+      ...process.env,
+      GITHUB_WORKSPACE: workspace,
+      GITHUB_ENV: envFile,
+      STUB_MODE: mode,
+      STUB_BASE: base,
+      STUB_HEAD: head,
+    };
+    if (override !== undefined) env.AFFECTED_BASE_OVERRIDE = override;
+
+    const r = spawnSync("bash", [scriptFile], { encoding: "utf8", env });
+    return { status: r.status, stderr: r.stderr, envLines: readFileSync(envFile, "utf8") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const exec = { skip: bashAvailable() ? false : "bash not available on this host" };
+
+test("mode=none: no ranged base resolvable → TURBO_SCM_* left unset", exec, () => {
+  const r = runResolve({ mode: "", base: "", head: "" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "mode=none must not export a base");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_HEAD/, "mode=none must not export a head");
+});
+
+test("newline-bearing affected-base override is rejected before the export (injection guard)", exec, () => {
+  const r = runResolve({ override: "deadbeef\nMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0, "a multiline override must fail the step, not export");
+  assert.doesNotMatch(r.envLines, /MALICIOUS/, "the injected env line must never reach $GITHUB_ENV");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "no partial export on a rejected override");
+});
+
+test("carriage-return-bearing affected-base override is rejected too", exec, () => {
+  const r = runResolve({ override: "deadbeef\rMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0);
+  assert.doesNotMatch(r.envLines, /MALICIOUS/);
+});
+
+test("single-line affected-base override exports exactly TURBO_SCM_BASE and TURBO_SCM_HEAD", exec, () => {
+  const r = runResolve({ override: "origin/main", head: "cafebabe" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.envLines, /^TURBO_SCM_BASE=origin\/main$/m);
+  assert.match(r.envLines, /^TURBO_SCM_HEAD=cafebabe$/m);
+  const nonEmpty = r.envLines.split("\n").filter((l) => l.trim() !== "");
+  assert.equal(nonEmpty.length, 2, `expected exactly two env lines, got: ${JSON.stringify(nonEmpty)}`);
+});

package/scripts/resolve-diff-range.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# resolve-diff-range.sh — the SINGLE, event-agnostic base/head SHA derivation
+# shared by every diff-scoped tier of pr-quality.yml (Story #314).
+#
+# WHY THIS EXISTS
+# ---------------
+# The diff-scoped security tiers (gitleaks secret scan + Semgrep SAST) must
+# scope their scan to the commits the triggering event INTRODUCED, so a
+# pre-existing finding never blocks. Each event exposes that base/head pair
+# under a different context path:
+#
+#   pull_request → github.event.pull_request.base.sha / .head.sha
+#   merge_group  → github.event.merge_group.base_sha  / .head_sha
+#   push         → github.event.before                / github.sha
+#
+# Under a `merge_group` (merge-queue) event `github.event.pull_request.*` is
+# empty, so without this derivation the tiers degrade to a FULL-TREE scan and
+# surface pre-existing findings unrelated to the queued commits — bouncing the
+# whole queue batch. Deriving base/head from the merge_group context instead
+# keeps the queue diff-scoped. This file is the one place that classification
+# lives, so gitleaks and SAST cannot drift apart.
+#
+# CONTRACT
+# --------
+# SOURCE this file (do NOT exec it) from a `shell: bash` step, after the repo
+# has been checked out with `fetch-depth: 0`. It reads the env vars below (all
+# optional; an absent context evaluates to the empty string in a GitHub
+# expression, so nothing here can `startup_failure` on a missing context) and
+# sets three variables in the CALLER's shell:
+#
+#   Inputs (wire each to the matching context in the step's `env:` block):
+#     PR_BASE_SHA          = github.event.pull_request.base.sha
+#     PR_HEAD_SHA          = github.event.pull_request.head.sha
+#     MERGE_GROUP_BASE_SHA = github.event.merge_group.base_sha
+#     MERGE_GROUP_HEAD_SHA = github.event.merge_group.head_sha
+#     EVENT_NAME           = github.event_name
+#     PUSH_BEFORE_SHA      = github.event.before
+#     PUSH_HEAD_SHA        = github.sha
+#
+#   Outputs (set on the caller's shell):
+#     RESOLVED_EVENT_MODE = pull_request | merge_group | push | none
+#     RESOLVED_BASE_SHA   = <base commit>   (empty when mode = none)
+#     RESOLVED_HEAD_SHA   = <head commit>   (empty when mode = none)
+#
+# Each consumer applies its own shaping to the raw pair: gitleaks builds a
+# `base..head` git-log range (`..` already excludes base-branch drift, so no
+# explicit merge-base is needed); SAST needs a single `--baseline-commit`, and
+# for pull_request derives the merge base of base..head (M8: base.sha is the
+# live base-branch tip and drifts past the fork point once main advances),
+# while for merge_group / push the base is already the exact fork point.
+#
+# `mode = none` means "no ranged base is resolvable" → the consumer falls back
+# to a full-tree scan. This is reached by an absent context (queue no-op, or a
+# branch-creation push whose `before` is the zero SHA / an unreachable commit).
+
+resolve_diff_range() {
+  local zero_sha="0000000000000000000000000000000000000000"
+  RESOLVED_EVENT_MODE="none"
+  RESOLVED_BASE_SHA=""
+  RESOLVED_HEAD_SHA=""
+
+  if [ -n "${PR_BASE_SHA:-}" ] && [ -n "${PR_HEAD_SHA:-}" ]; then
+    # pull_request — the base-branch tip / PR head. Highest precedence so a
+    # caller that (unusually) exposes both PR and push context stays PR-scoped.
+    RESOLVED_EVENT_MODE="pull_request"
+    RESOLVED_BASE_SHA="${PR_BASE_SHA}"
+    RESOLVED_HEAD_SHA="${PR_HEAD_SHA}"
+  elif [ -n "${MERGE_GROUP_BASE_SHA:-}" ] && [ -n "${MERGE_GROUP_HEAD_SHA:-}" ]; then
+    # merge_group — the merge queue built base_sha..head_sha; head_sha is the
+    # temporary merge commit of the queued PR(s) on top of base_sha (the exact
+    # fork point, so no drift to correct for).
+    RESOLVED_EVENT_MODE="merge_group"
+    RESOLVED_BASE_SHA="${MERGE_GROUP_BASE_SHA}"
+    RESOLVED_HEAD_SHA="${MERGE_GROUP_HEAD_SHA}"
+  elif [ "${EVENT_NAME:-}" = "push" ] && [ -n "${PUSH_BEFORE_SHA:-}" ] && \
+       [ "${PUSH_BEFORE_SHA}" != "${zero_sha}" ] && \
+       git cat-file -e "${PUSH_BEFORE_SHA}^{commit}" 2>/dev/null; then
+    # push — the commits this push added (before..sha). `before` is the zero
+    # SHA on a branch-creation push, and may be unreachable after a
+    # force-push / shallow fetch; either case falls through to `none`.
+    RESOLVED_EVENT_MODE="push"
+    RESOLVED_BASE_SHA="${PUSH_BEFORE_SHA}"
+    RESOLVED_HEAD_SHA="${PUSH_HEAD_SHA}"
+  fi
+}
+
+resolve_diff_range
+
+# When EXECUTED directly (not sourced) — e.g. by the unit test — echo the
+# resolution as `KEY=value` lines so the truth table is assertable without a
+# GitHub runner. `BASH_SOURCE[0] == $0` iff the file was run, not sourced.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  printf 'RESOLVED_EVENT_MODE=%s\n' "${RESOLVED_EVENT_MODE}"
+  printf 'RESOLVED_BASE_SHA=%s\n' "${RESOLVED_BASE_SHA}"
+  printf 'RESOLVED_HEAD_SHA=%s\n' "${RESOLVED_HEAD_SHA}"
+fi

package/scripts/resolve-diff-range.test.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * resolve-diff-range.test.mjs — node:test suite for the single, event-agnostic
+ * base/head SHA derivation shared by every diff-scoped tier of pr-quality.yml
+ * (Story #314).
+ *
+ * The workflow's gitleaks and SAST resolvers both `source` this shell script,
+ * so its truth table IS the derived range each tier scans. This suite executes
+ * the script directly (it echoes `RESOLVED_*=…` lines when run rather than
+ * sourced) with per-event env fixtures and asserts the derived base/head for
+ * each of the three events plus the full-tree fallbacks — the "self-test
+ * showing the derived range for each event" half of the Story's Verify.
+ *
+ * Run: node scripts/resolve-diff-range.test.mjs  (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, "resolve-diff-range.sh");
+// The repo root is a git repo, so the push-mode reachability guard
+// (`git cat-file -e <before>`) can resolve a real ancestor commit.
+const REPO_ROOT = join(HERE, "..");
+
+// A real, reachable commit for exercising the push reachability guard, and its
+// parent (also reachable) to stand in as the "before" SHA.
+const HEAD_SHA = execFileSync("git", ["rev-parse", "HEAD"], {
+  cwd: REPO_ROOT,
+  encoding: "utf8",
+}).trim();
+const PARENT_SHA = execFileSync("git", ["rev-parse", "HEAD~1"], {
+  cwd: REPO_ROOT,
+  encoding: "utf8",
+}).trim();
+
+const ZERO_SHA = "0000000000000000000000000000000000000000";
+// A syntactically-valid 40-hex SHA that is not an object in this repo.
+const UNREACHABLE_SHA = "dead0000dead0000dead0000dead0000dead0000";
+
+// Run the derivation with the given env and parse its `KEY=value` output.
+function resolve(env) {
+  const out = execFileSync("bash", [SCRIPT], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+    // Start from a clean slate so the ambient CI env (which may itself set
+    // GITHUB_* / EVENT_NAME) cannot leak into the fixture.
+    env: { PATH: process.env.PATH, ...env },
+  });
+  const parsed = {};
+  for (const line of out.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq === -1) continue;
+    parsed[line.slice(0, eq)] = line.slice(eq + 1);
+  }
+  return parsed;
+}
+
+test("pull_request: derives base.sha/head.sha directly", () => {
+  const r = resolve({
+    PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    EVENT_NAME: "pull_request",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
+  assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+  assert.equal(r.RESOLVED_HEAD_SHA, "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
+});
+
+test("merge_group: derives merge_group.base_sha/head_sha", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+    EVENT_NAME: "merge_group",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
+  assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
+  assert.equal(r.RESOLVED_HEAD_SHA, "dddddddddddddddddddddddddddddddddddddddd");
+});
+
+test("pull_request takes precedence over a co-present merge_group context", () => {
+  const r = resolve({
+    PR_BASE_SHA: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    PR_HEAD_SHA: "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "pull_request");
+  assert.equal(r.RESOLVED_BASE_SHA, "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa");
+});
+
+test("merge_group takes precedence over a co-present push context", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    MERGE_GROUP_HEAD_SHA: "dddddddddddddddddddddddddddddddddddddddd",
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: PARENT_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "merge_group");
+  assert.equal(r.RESOLVED_BASE_SHA, "cccccccccccccccccccccccccccccccccccccccc");
+});
+
+test("push: derives event.before/sha when before is a reachable commit", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: PARENT_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "push");
+  assert.equal(r.RESOLVED_BASE_SHA, PARENT_SHA);
+  assert.equal(r.RESOLVED_HEAD_SHA, HEAD_SHA);
+});
+
+test("push with zero before (branch creation) → none/full-tree", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: ZERO_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+  assert.equal(r.RESOLVED_BASE_SHA, "");
+  assert.equal(r.RESOLVED_HEAD_SHA, "");
+});
+
+test("push with an unreachable before (force-push/shallow) → none/full-tree", () => {
+  const r = resolve({
+    EVENT_NAME: "push",
+    PUSH_BEFORE_SHA: UNREACHABLE_SHA,
+    PUSH_HEAD_SHA: HEAD_SHA,
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+});
+
+test("no event context at all → none/full-tree (never a startup_failure)", () => {
+  const r = resolve({});
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+  assert.equal(r.RESOLVED_BASE_SHA, "");
+  assert.equal(r.RESOLVED_HEAD_SHA, "");
+});
+
+test("merge_group with only base_sha (partial context) → none", () => {
+  const r = resolve({
+    MERGE_GROUP_BASE_SHA: "cccccccccccccccccccccccccccccccccccccccc",
+    EVENT_NAME: "merge_group",
+  });
+  assert.equal(r.RESOLVED_EVENT_MODE, "none");
+});

package/scripts/runner-fleet-consumers.json

@@ -1,5 +1,6 @@
 {
-  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. All nine runners (including Beestera/swarm-os's three) are co-resident on one operator Mac (2026-07-03 runner audit, repo-ops matrix §1a); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it.",
+  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. The co-resident operator Mac now carries 7 domio + 5 athportal monitored runners (plus 17 beestera/swarm-os installs that are deliberately NOT listed — see `$comment_swarm_os`); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it. Keep these counts in lockstep with the live fleets: the maintenance contract lives in templates/runbooks/runner-provisioning.md.",
+  "$comment_expectedCount": "Semantics: warn-below (over-provisioning is fine). The checker computes shortfall = max(0, expectedCount - matchingOnline) and only alarms when fewer online runners match the labels than expected — adding runners above expectedCount never trips the alarm, so a deliberate scale-up needs no immediate roster edit (though you should still bump the count to keep the shortfall floor meaningful). Removing runners on purpose (scale-down) DOES require lowering expectedCount here, otherwise the monitor will correctly flag the missing runners as a shortfall.",
   "$comment_swarm_os": "Beestera/swarm-os is deliberately NOT listed: no dsj1984-owned PAT can read another org's runner API (fine-grained PATs are bound to one resource owner; the Beestera org rejects classic PATs), so its row would permanently false-positive as 0/3 degraded. Host-level coverage is retained regardless — its runners share the Mac with the rows below, so a wedged host still trips domio/athportal. What is NOT covered: swarm-os's individual launchd services dying while the host stays healthy, and its stale-queue check. Re-add the entry if a Beestera-owned credential (fine-grained PAT or GitHub App) plus per-repo token support ever lands.",
   "$comment_staleQueuedMinutes": "A queued/waiting workflow run older than this many minutes with no online runner matching its labels is flagged as a queue-staleness signal (optional per-repo override via `staleQueuedMinutes`).",
   "defaultStaleQueuedMinutes": 20,
@@ -7,13 +8,13 @@
     {
       "name": "domio",
       "repo": "dsj1984/domio",
-      "expectedCount": 3,
+      "expectedCount": 7,
       "labels": ["self-hosted", "macOS", "ARM64", "domio-runner"]
     },
     {
       "name": "athportal",
       "repo": "dsj1984/athportal",
-      "expectedCount": 3,
+      "expectedCount": 5,
       "labels": ["self-hosted", "macOS", "ARM64", "athportal-runner"]
     }
   ]

package/templates/runbooks/runner-provisioning.md

@@ -66,6 +66,28 @@ shasum -a 256 actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 tar xzf actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 ```
 
+## ⚠️ Read second: keep the health-monitor roster in lockstep
+
+Any change to a fleet's size — **adding or removing a runner** — **MUST** be
+accompanied by an update to that repo's `expectedCount` in
+[`scripts/runner-fleet-consumers.json`](../../scripts/runner-fleet-consumers.json).
+That file is the roster the scheduled `runner-fleet-health.yml` monitor
+(`scripts/check-runner-health.mjs`) compares the live fleet against.
+
+- **Scale up (add a runner):** bump `expectedCount` so the shortfall floor
+  keeps pace. Over-provisioning does not trip the alarm on its own (the
+  monitor is **warn-below**: `shortfall = max(0, expectedCount - matchingOnline)`),
+  but leaving the count stale hides a later drop back down to the old value.
+- **Scale down (remove a runner):** lower `expectedCount` in the same change,
+  otherwise the monitor will correctly flag the now-missing runner(s) as a
+  shortfall and page the operator for a deliberate downsizing.
+
+If the roster and the live fleet drift apart, the monitor either false-alarms
+(count too high) or goes silent on real outages above the stale threshold
+(count too low) — the exact mis-calibration this contract exists to prevent.
+See also [`runner-fleet-health.md`](runner-fleet-health.md) for the operator
+response when the monitor does fire.
+
 ## 2. Register with `config.sh` (repo-level)
 
 Registration is **repo-level** (the fleet's standing model), not org-level.
@@ -179,7 +201,10 @@ The runner loads `.env` at service start — after any `.env` change, restart:
   (§5). Mint the removal token via
   `gh api -X POST repos/<OWNER>/<REPO>/actions/runners/remove-token --jq .token`.
 - **Decommission.** Same removal sequence, then delete `<RUNNER_DIR>`.
-  Confirm the runner disappeared from *Settings → Actions → Runners*.
+  Confirm the runner disappeared from *Settings → Actions → Runners*, **and**
+  lower the repo's `expectedCount` in `scripts/runner-fleet-consumers.json`
+  (see the roster-lockstep callout above) so the health monitor does not flag
+  the intentional removal as a shortfall.
 
 ## Project-Specific Notes