mandrel-platform 0.20.0 → 0.21.0

package/scripts/deploy-worker-secrets.test.mjs

@@ -0,0 +1,136 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  parseCsv,
+  parseSecretNames,
+  resolveSecretValue,
+  provisionWorkerSecrets,
+} from "./deploy-worker-secrets.mjs";
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+test("parseCsv trims entries and drops empties", () => {
+  assert.deepEqual(parseCsv(" api , worker-cron ,, "), ["api", "worker-cron"]);
+  assert.deepEqual(parseCsv(undefined), []);
+});
+
+test("parseSecretNames trims, skips blanks, and skips '#' comment lines", () => {
+  const raw = ["# deploy-critical only", "TURSO_AUTH_TOKEN", "", "  UPSTREAM_API_KEY  ", "   # trailing note"].join("\n");
+  assert.deepEqual(parseSecretNames(raw), ["TURSO_AUTH_TOKEN", "UPSTREAM_API_KEY"]);
+  assert.deepEqual(parseSecretNames(""), []);
+});
+
+test("resolveSecretValue returns the value only for present, non-empty string entries", () => {
+  const ctx = { A: "value", B: "", C: 42 };
+  assert.equal(resolveSecretValue(ctx, "A"), "value");
+  assert.equal(resolveSecretValue(ctx, "B"), null);
+  assert.equal(resolveSecretValue(ctx, "C"), null);
+  assert.equal(resolveSecretValue(ctx, "MISSING"), null);
+  assert.equal(resolveSecretValue(null, "A"), null);
+});
+
+// ---------------------------------------------------------------------------
+// provisionWorkerSecrets — orchestration with an injected wrangler runner
+// ---------------------------------------------------------------------------
+
+function collect() {
+  const lines = [];
+  const calls = [];
+  return {
+    lines,
+    calls,
+    log: (line) => lines.push(line),
+    runWrangler: (args, stdinValue) => {
+      calls.push({ args, stdinValue });
+      return 0;
+    },
+  };
+}
+
+const BASE_ENV = {
+  DEPLOY_ENV: "production",
+  DEPLOYED_WORKERS: "api,worker-cron",
+  WORKER_SECRETS: "TURSO_AUTH_TOKEN",
+  SECRETS_CONTEXT: JSON.stringify({ TURSO_AUTH_TOKEN: "s3cret" }),
+};
+
+test("provisions each name onto each worker via versions secret put, then promotes with versions deploy -y", () => {
+  const { log, runWrangler, calls } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, { log, runWrangler });
+  assert.equal(code, 0);
+
+  assert.deepEqual(
+    calls.map((c) => c.args.slice(0, 3).join(" ")),
+    [
+      "versions secret put", // api
+      "versions deploy --name", // api promote
+      "versions secret put", // worker-cron
+      "versions deploy --name", // worker-cron promote
+    ]
+  );
+
+  // put: value travels over stdin, never in argv.
+  const put = calls[0];
+  assert.deepEqual(put.args, ["versions", "secret", "put", "TURSO_AUTH_TOKEN", "--name", "api", "--env", "production"]);
+  assert.equal(put.stdinValue, "s3cret");
+
+  // promote: non-interactive -y, message names the Story.
+  const promote = calls[1];
+  assert.ok(promote.args.includes("-y"));
+  assert.ok(promote.args.includes("--message"));
+  assert.equal(promote.stdinValue, undefined);
+});
+
+test("secret values never appear in log output", () => {
+  const { log, runWrangler, lines } = collect();
+  provisionWorkerSecrets(BASE_ENV, { log, runWrangler });
+  assert.ok(lines.every((l) => !l.includes("s3cret")));
+});
+
+test("zero resolved names is a notice + exit 0 (nothing to provision)", () => {
+  const { log, runWrangler, calls, lines } = collect();
+  const code = provisionWorkerSecrets(
+    { ...BASE_ENV, WORKER_SECRETS: "\n# only comments\n\n" },
+    { log, runWrangler }
+  );
+  assert.equal(code, 0);
+  assert.equal(calls.length, 0);
+  assert.ok(lines.some((l) => l.includes("resolved to zero names")));
+});
+
+test("a listed name absent (or empty) in the inherited context is a hard error", () => {
+  const { log, runWrangler, lines } = collect();
+  const code = provisionWorkerSecrets(
+    { ...BASE_ENV, WORKER_SECRETS: "MISSING_SECRET" },
+    { log, runWrangler }
+  );
+  assert.equal(code, 1);
+  assert.ok(lines.some((l) => l.includes("'MISSING_SECRET' is not present (or empty)")));
+});
+
+test("malformed SECRETS_CONTEXT JSON is a hard error", () => {
+  const { log, runWrangler } = collect();
+  const code = provisionWorkerSecrets({ ...BASE_ENV, SECRETS_CONTEXT: "{not json" }, { log, runWrangler });
+  assert.equal(code, 1);
+});
+
+test("a failing wrangler versions secret put aborts with exit 1", () => {
+  const { log } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, {
+    log,
+    runWrangler: (args) => (args[1] === "secret" ? 1 : 0),
+  });
+  assert.equal(code, 1);
+});
+
+test("a failing wrangler versions deploy aborts with exit 1", () => {
+  const { log } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, {
+    log,
+    runWrangler: (args) => (args[0] === "versions" && args[1] === "deploy" ? 1 : 0),
+  });
+  assert.equal(code, 1);
+});

package/templates/runbooks/README.md

@@ -54,3 +54,16 @@ node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref mandrel-platf
 
 > Placeholder convention: `<UPPER_SNAKE>` between angle brackets. Search for
 > `<` after copying to find everything that still needs a value.
+
+## Self-contained runbooks (not stubs)
+
+One template in this directory is a **full runbook**, not a thin stub — it
+has no canonical `docs/runbooks/` counterpart to link and carries the entire
+process inline (placeholders included):
+
+| Runbook | Scope |
+|---------|-------|
+| `runner-provisioning.md` | provision a persistent self-hosted runner with the [`templates/runner/`](../runner/) hygiene kit (job-start cleanup hook + runner-scoped `.env`) |
+
+Adopt it the same way as a stub (copy into `docs/runbooks/`, fill the
+placeholders); `platform-sync.mjs` materializes it alongside the stubs.

package/templates/runbooks/runner-provisioning.md

@@ -0,0 +1,187 @@
+# Self-Hosted Runner Provisioning — <PROJECT_NAME>
+
+> **Self-contained runbook** (not a thin stub). Unlike the other templates in
+> this directory, there is no canonical `docs/runbooks/` counterpart to link —
+> this file IS the process. It provisions a **persistent** (non-ephemeral)
+> GitHub Actions runner on a macOS host using the mandrel-platform runner kit
+> (`templates/runner/`), which ships the job-start hygiene hook
+> (`job-cleanup.sh`) and the per-runner `.env` (`.env.example`).
+>
+> Placeholder convention: `<UPPER_SNAKE>` between angle brackets — search for
+> `<` after copying to find everything that still needs a value.
+
+---
+
+## ⚠️ Read first: the shared-`$HOME` concurrency hazard
+
+Every runner on a host typically runs as the **same OS user**, so anything
+resolved against `$HOME` is **shared across all co-resident runners** — it is
+*not* scoped to "this runner", no matter what a comment claims. The two
+hazards this kit exists to close:
+
+1. **`~/setup-pnpm` is shared.** `pnpm/action-setup`'s `dest` input defaults
+   to `~/setup-pnpm`. With N runners on one host, N concurrent jobs race on
+   one pnpm shim install. Worse, a cleanup hook that `pkill`s processes
+   matching `~/setup-pnpm` or `rm -rf`s it at job start will **destroy a pnpm
+   install a concurrent runner is mid-flight on**. The fix is ordering:
+   **first** make the pnpm shim location per-runner (workflow-side, see
+   [pnpm scoping](#3-pnpm-scoping-workflow-side-prerequisite) below), and only
+   **then** is a reap/delete hook safe — and even then it must target only the
+   runner-scoped path. The kit's `job-cleanup.sh` never touches
+   `~/setup-pnpm`.
+2. **The default tool cache is shared.** Without a runner-scoped
+   `RUNNER_TOOL_CACHE`, toolchain actions extract into a host-shared cache
+   and co-resident runners race on it. The kit's `.env` scopes it to the
+   runner's own `_work/_tool`.
+
+Do not roll the hook out to a host until every workflow that job's runner
+serves installs pnpm to a runner-scoped `dest`. Rolling out the hook without
+the pnpm-scoping prerequisite reintroduces the exact corruption it guards
+against.
+
+## Host Values
+
+| Value | Setting |
+|-------|---------|
+| Runner host | `<RUNNER_HOST>` |
+| Runner OS user | `<RUNNER_USER>` |
+| Runner root dir | `<RUNNER_DIR>` (e.g. `~/Development/github-runners/<REPO>`) |
+| Repository | `<OWNER>/<REPO>` |
+| Runner name | `<REPO>-runner` (or `<REPO>-runner-<N>` for a pool) |
+| Labels | `self-hosted, macOS, ARM64, <REPO>-runner` |
+| Runner version | `<RUNNER_VERSION>` (latest from [actions/runner releases](https://github.com/actions/runner/releases)) |
+
+## 1. Download and unpack the runner
+
+One directory per runner — never share a runner root between registrations.
+
+```bash
+mkdir -p <RUNNER_DIR> && cd <RUNNER_DIR>
+curl -o actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz -L \
+  https://github.com/actions/runner/releases/download/v<RUNNER_VERSION>/actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+# Verify the SHA-256 against the checksum published on the release page
+# before unpacking — same download-and-verify posture as the platform's
+# pinned gitleaks/actionlint installs.
+shasum -a 256 actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+tar xzf actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+```
+
+## 2. Register with `config.sh` (repo-level)
+
+Registration is **repo-level** (the fleet's standing model), not org-level.
+Mint a short-lived registration token via the repo UI
+(*Settings → Actions → Runners → New self-hosted runner*) or:
+
+```bash
+gh api -X POST repos/<OWNER>/<REPO>/actions/runners/registration-token --jq .token
+```
+
+Then configure:
+
+```bash
+cd <RUNNER_DIR>
+./config.sh \
+  --url https://github.com/<OWNER>/<REPO> \
+  --token <REGISTRATION_TOKEN> \
+  --name <REPO>-runner \
+  --labels self-hosted,macOS,ARM64,<REPO>-runner \
+  --work _work \
+  --unattended
+```
+
+- `--labels` — the four-label contract the fleet's workflows target
+  (`self-hosted, macOS, ARM64, <REPO>-runner`). The `<REPO>-runner` label is
+  the routing key; keep it unique per repo.
+- `--work _work` — keeps the work tree inside `<RUNNER_DIR>`, which is what
+  makes every path in the hygiene kit runner-scoped.
+- Registration tokens expire after ~1 hour; mint a fresh one per runner.
+
+## 3. pnpm scoping (workflow-side prerequisite)
+
+Before installing the hook, confirm every workflow this runner serves
+installs the pnpm shim to a **runner-scoped** destination:
+
+- Workflows using the platform's `setup-toolchain` composite action (all
+  `pr-quality.yml` tiers) are already safe: it defaults `pnpm/action-setup`'s
+  `dest` to `${{ runner.temp }}/pnpm`, i.e. `<RUNNER_DIR>/_work/_temp/pnpm`,
+  unique per runner. `pr-quality.yml` also exposes a `pnpm-dest` input for
+  explicit overrides.
+- Workflows calling `pnpm/action-setup` directly MUST pass
+  `dest: ${{ runner.temp }}/pnpm`. The action's default (`~/setup-pnpm`) is
+  host-shared and unsafe under runner concurrency (see the hazard header).
+
+There is **no runner-side override** for the pnpm `dest` — it is a workflow
+input — which is why this step is a rollout gate, not an `.env` line.
+
+## 4. Install the hygiene kit (hook + `.env`)
+
+Copy the kit from the platform payload into the runner root:
+
+```bash
+cp node_modules/mandrel-platform/templates/runner/job-cleanup.sh <RUNNER_DIR>/job-cleanup.sh
+chmod +x <RUNNER_DIR>/job-cleanup.sh
+cp node_modules/mandrel-platform/templates/runner/.env.example <RUNNER_DIR>/.env
+```
+
+Then edit `<RUNNER_DIR>/.env` and replace every `<RUNNER_DIR>` placeholder
+with the runner root's absolute path. The resulting file wires:
+
+- `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh` — the
+  job-start hook. It reaps orphaned pnpm/node processes parented to **this**
+  runner's work tree, clears stale runner-scoped pnpm installs, and
+  age-gate-sweeps shared-`$TMPDIR` gitleaks leftovers. It never fails a job
+  (always exits 0) and never touches another runner's state.
+- `RUNNER_TOOL_CACHE=<RUNNER_DIR>/_work/_tool` and
+  `AGENT_TOOLSDIRECTORY=<RUNNER_DIR>/_work/_tool` — runner-scoped tool cache
+  (two env names, one dir; some actions read the legacy name).
+- `LANG=en_US.UTF-8`.
+
+The hook needs no per-runner editing: it derives `RUNNER_DIR` from its own
+location, so the same file works verbatim on every runner.
+
+## 5. Install as a launchd service (`svc.sh`)
+
+```bash
+cd <RUNNER_DIR>
+./svc.sh install   # generates the launchd plist for the current user
+./svc.sh start
+./svc.sh status    # expect: Started · running
+```
+
+Verify end-to-end: push a trivial workflow run targeting
+`runs-on: [self-hosted, macOS, ARM64, <REPO>-runner]` and confirm (a) the job
+is picked up and (b) the job log shows the `Set up runner` hook phase running
+`job-cleanup.sh` before the first step.
+
+The runner loads `.env` at service start — after any `.env` change, restart:
+
+```bash
+./svc.sh stop && ./svc.sh start
+```
+
+## 6. Update / rotation guidance
+
+- **Runner version updates.** Persistent runners self-update by default when
+  GitHub releases a new runner version; no action needed. If a runner is
+  pinned or the self-update wedges, stop the service, download/unpack the new
+  tarball over `<RUNNER_DIR>` (config and `.env` survive), and restart via
+  `svc.sh`.
+- **Kit updates.** The hook and `.env.example` are versioned in
+  mandrel-platform. On a platform release that touches `templates/runner/`,
+  re-copy `job-cleanup.sh` (verbatim — it is parameterized) and diff
+  `.env.example` against the live `.env`, then `./svc.sh stop && ./svc.sh
+  start`. There is no `mandrel sync` equivalent for a runner host's
+  filesystem — this is an operator-applied step.
+- **Token/registration rotation.** Registration tokens are one-shot at
+  config time; nothing persists to rotate. To move a runner between repos or
+  rename it: `./svc.sh stop && ./svc.sh uninstall && ./config.sh remove
+  --token <REMOVAL_TOKEN>`, then re-register (§2) and reinstall the service
+  (§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*.
+
+## Project-Specific Notes
+
+<!-- Record host quirks: co-resident runner inventory for this host, Xcode /
+     toolchain versions the workloads assume, monitoring hooks, etc. -->

package/templates/runner/.env.example

@@ -0,0 +1,45 @@
+# .env — per-runner environment for a PERSISTENT self-hosted runner
+# (mandrel-platform runner kit).
+#
+# Copy this file to `<RUNNER_DIR>/.env` (the runner root, next to config.sh)
+# and replace every `<RUNNER_DIR>` placeholder with the runner's ABSOLUTE
+# root path (e.g. /Users/ci/Development/github-runners/myrepo). The runner
+# loads this file at service start and injects the variables into every job.
+#
+# Placeholder convention: `<UPPER_SNAKE>` between angle brackets — search for
+# `<` after copying to find everything that still needs a value.
+#
+# See templates/runbooks/runner-provisioning.md for the full provisioning
+# procedure, including WHY every value here must be runner-scoped (multiple
+# runners on one host share an OS user, so anything resolved against $HOME is
+# a cross-runner concurrency hazard).
+
+# Locale — pnpm/git/node emit UTF-8; a C locale garbles their output.
+LANG=en_US.UTF-8
+
+# Job-start hygiene hook. Runs templates/runner/job-cleanup.sh (installed
+# into the runner root) before every job: reaps orphaned pnpm/node processes
+# from THIS runner's work tree and clears stale install/temp artifacts.
+# The hook is runner-scoped and never fails the job (always exits 0).
+ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh
+
+# Runner-scoped tool cache. Without this, actions/setup-node & friends
+# default the tool cache to a host-shared location and co-resident runners
+# race on extraction. `_work/_tool` is inside this runner's own work tree,
+# so each runner gets an isolated cache.
+RUNNER_TOOL_CACHE=<RUNNER_DIR>/_work/_tool
+
+# Same value, second consumer: some toolchain actions read
+# AGENT_TOOLSDIRECTORY (the Azure Pipelines-era name) instead of
+# RUNNER_TOOL_CACHE. Keep both pointing at the same runner-scoped dir.
+AGENT_TOOLSDIRECTORY=<RUNNER_DIR>/_work/_tool
+
+# ── pnpm scoping (read this before enabling the hook) ──────────────────────
+# The pnpm shim install location is a WORKFLOW-side setting, not a runner-side
+# one: pnpm/action-setup's `dest` input defaults to `~/setup-pnpm`, which is
+# SHARED across every runner on the host. The platform's setup-toolchain
+# composite action already re-defaults `dest` to `${{ runner.temp }}/pnpm`
+# (runner-scoped); workflows that call pnpm/action-setup directly MUST pass
+# `dest: ${{ runner.temp }}/pnpm` (or the pr-quality.yml `pnpm-dest` input).
+# The job-cleanup.sh hook only reaps the runner-scoped locations — it
+# deliberately never touches `~/setup-pnpm`.

package/templates/runner/job-cleanup.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# ACTIONS_RUNNER_HOOK_JOB_STARTED hook — generalized, runner-scoped hygiene
+# for PERSISTENT self-hosted runners (mandrel-platform runner kit).
+#
+# A persistent runner (launchd/systemd service) leaks state from a prior job
+# into the next one: the runner does not always reap the job's child process
+# tree, and some actions leave files in shared locations. Observed breakage
+# classes this hook guards against:
+#
+#   - an orphaned `pnpm`/`node` process (e.g. a hung install or lint) still
+#     mutating the pnpm shim install, corrupting the pnpm CLI for the next job;
+#   - leftover `gitleaks.tmp` / `gitleaks-*` artifacts in the shared $TMPDIR
+#     blocking the next gitleaks download.
+#
+# Running this before every job gives each job a clean slate ("fresh per job"
+# without the cost of re-registering an ephemeral runner).
+#
+# ── CONCURRENCY SAFETY (the load-bearing design constraint) ─────────────────
+#
+# Multiple runners on one host typically run as the SAME OS user, so anything
+# under $HOME (notably `~/setup-pnpm`, the pnpm/action-setup DEFAULT install
+# destination) is SHARED across all co-resident runners. A hook that reaps
+# processes matching `~/setup-pnpm` or `rm -rf`s it will destroy a pnpm
+# install a CONCURRENT runner is mid-flight on. This hook therefore:
+#
+#   1. NEVER touches `~/setup-pnpm` or any other $HOME-shared pnpm path.
+#      The pnpm shim MUST instead be runner-scoped at install time: the
+#      platform's `setup-toolchain` composite action already defaults
+#      pnpm/action-setup's `dest` to `${{ runner.temp }}/pnpm` (i.e.
+#      `<RUNNER_DIR>/_work/_temp/pnpm`, unique per runner), and
+#      `pr-quality.yml` exposes a `pnpm-dest` input for explicit overrides.
+#      See templates/runbooks/runner-provisioning.md § "pnpm scoping".
+#   2. Reaps ONLY processes whose command line resolves inside THIS runner's
+#      own work tree (`<RUNNER_DIR>/_work/...`). Every path below derives
+#      from RUNNER_DIR, which is unique per runner, so a co-resident
+#      runner's processes and files are never matched.
+#   3. Age-gates cleanup of the genuinely shared $TMPDIR gitleaks artifacts,
+#      so a fresh (in-flight) download owned by a concurrent job is never
+#      deleted — only stale leftovers are.
+#
+# ── PARAMETERIZATION ────────────────────────────────────────────────────────
+#
+# No hardcoded usernames, repo names, or runner names. All paths derive from:
+#
+#   RUNNER_DIR   — the runner's root directory. Defaults to the directory
+#                  containing this script (the kit installs the hook into the
+#                  runner root, next to config.sh / run.sh). Override via env
+#                  only if you install the hook elsewhere.
+#   RUNNER_TMP   — the runner's per-runner job temp (`runner.temp`), always
+#                  `${RUNNER_DIR}/_work/_temp`.
+#   JOB_CLEANUP_STALE_MINUTES
+#                — age threshold (minutes) for the shared-$TMPDIR gitleaks
+#                  sweep. Default 60. Artifacts younger than this are assumed
+#                  in-flight and left alone.
+#
+# Configured via `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh`
+# in the runner's `.env` (see .env.example in this directory).
+#
+# NEVER fails the job — best-effort cleanup, always exits 0.
+
+set +e
+
+RUNNER_DIR="${RUNNER_DIR:-$(cd "$(dirname "$0")" && pwd)}"
+RUNNER_WORK="${RUNNER_DIR}/_work"
+RUNNER_TMP="${RUNNER_WORK}/_temp"
+TMP="${TMPDIR:-/tmp}"
+STALE_MINUTES="${JOB_CLEANUP_STALE_MINUTES:-60}"
+
+# 1) Reap orphaned pnpm/node processes from prior jobs — scoped to THIS
+#    runner's work tree only. The patterns target executable paths INSIDE the
+#    runner-scoped install locations (`.../node_modules`), so they match the
+#    actual pnpm/node binaries that ran from these dirs — not a shell that
+#    merely references the path. RUNNER_TMP and RUNNER_WORK are unique per
+#    runner, so co-resident runners and unrelated user processes are never
+#    hit. The shared `~/setup-pnpm` is deliberately NOT a reap target (see
+#    the concurrency-safety header).
+pkill -9 -f "${RUNNER_TMP}/pnpm/node_modules"       2>/dev/null
+pkill -9 -f "${RUNNER_TMP}/setup-pnpm/node_modules" 2>/dev/null
+pkill -9 -f "${RUNNER_WORK}/_tool/[^ ]*node_modules" 2>/dev/null
+
+# 2) Remove stale runner-scoped pnpm shim installs so the next job's
+#    pnpm/action-setup starts from a clean slate. Only paths under THIS
+#    runner's `_work/_temp` are deleted — never `~/setup-pnpm`.
+rm -rf "${RUNNER_TMP}/pnpm"       2>/dev/null
+rm -rf "${RUNNER_TMP}/setup-pnpm" 2>/dev/null
+
+# 3) Sweep stale gitleaks artifacts from the SHARED $TMPDIR. Because this
+#    location is shared by every runner on the host, deletion is age-gated:
+#    only artifacts older than STALE_MINUTES are removed, so a concurrent
+#    runner's in-flight download is never deleted mid-job.
+find "${TMP}" -maxdepth 1 -name 'gitleaks.tmp' -mmin "+${STALE_MINUTES}" \
+  -exec rm -f  {} + 2>/dev/null
+find "${TMP}" -maxdepth 1 -name 'gitleaks-*'   -mmin "+${STALE_MINUTES}" \
+  -exec rm -rf {} + 2>/dev/null
+
+exit 0

package/templates/workflows/deploy-staging.yml

@@ -3,7 +3,7 @@ name: deploy-staging
 # Canonical staging-deploy caller template (Story #175).
 #
 # > **Thin local caller.** The defence-in-depth deploy core (secret-isolation
-# > audit -> CF env gate -> pre-migration snapshot -> migrate -> deploy ->
+# > audit -> CF env gate -> migration (snapshot + apply) -> deploy ->
 # > boot-smoke + auto-rollback) AND the CI-green guard both live in the shared
 # > `dsj1984/mandrel-platform` `deploy-cloudflare.yml` reusable workflow — see
 # > https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml.
@@ -16,11 +16,13 @@ name: deploy-staging
 # `conclusion == 'success'`. `workflow_run` fires on BOTH a successful AND a
 # failed upstream run, so a caller-side guard against a red run used to be
 # REQUIRED here — every consumer hand-copied the same `preflight` job (see
-# mandrel-platform Story #175 context). That guard is now a `require-ci-green`
-# job INSIDE `deploy-cloudflare.yml` itself (`github.event` inside a reusable
-# workflow is the CALLER's event, so the shared workflow can see and gate on
-# the `workflow_run` conclusion even though it cannot own this file's `on:`
-# block). This template needs NO caller-side preflight guard as a result —
+# mandrel-platform Story #175 context). That guard now lives INSIDE
+# `deploy-cloudflare.yml` itself as a job-level `if:` on its entry jobs
+# (`github.event` inside a reusable workflow is the CALLER's event, so the
+# shared workflow can see and gate on the `workflow_run` conclusion even
+# though it cannot own this file's `on:` block); a red upstream run skips
+# the whole chain with zero runner spin-ups (mandrel-platform Story #237).
+# This template needs NO caller-side preflight guard as a result —
 # copy it as-is and fill in the placeholders below.
 #
 # Replace every <PLACEHOLDER> with your project's real values:
@@ -46,8 +48,9 @@ name: deploy-staging
 
 on:
   # CI-green gate: fires when <CI_WORKFLOW_NAME> finishes on main. The shared
-  # deploy-cloudflare.yml's require-ci-green job skips-with-notice unless the
-  # upstream conclusion was 'success' — no caller-side guard needed.
+  # deploy-cloudflare.yml's job-level CI-green gate skips the entire job
+  # chain (zero runners) unless the upstream conclusion was 'success' — no
+  # caller-side guard needed.
   workflow_run:
     workflows: [<CI_WORKFLOW_NAME>]
     branches: [main]