@biffo/cli 0.292.0 → 0.294.0

package/_skeletons/plugin-template/.github/workflows/ci.yml

@@ -85,6 +85,21 @@ jobs:
       # measure.
       - name: Error-branch coverage
         run: uv run python scripts/error_branch_coverage.py --check --coverage coverage.json
+      - name: Core-revision preflight — self-test
+        if: ${{ !cancelled() }}
+        # scripts/core-revision-preflight.sh (biffo-template#1604) is
+        # distributed here too, verbatim, via shared-files.json's `files` —
+        # but a plugin repo has no deploy.yml and nothing that mounts an
+        # independently-deployed service ahead of core, so it is never
+        # invoked for a REAL preflight in this repo the way the sibling
+        # skeleton's deploy.yml invokes it. This is the caller that keeps it
+        # off the #1413 zero-caller list anyway: it proves the script itself
+        # still blocks a stale core, passes a current one, and fails CLOSED
+        # when the digest is missing, against a stubbed curl — the same
+        # governance-plumbing reasoning js-dependency-audit.sh/
+        # py-dependency-audit.sh already carry as inert-but-verified copies
+        # in a Python-only or JS-only sibling.
+        run: sh scripts/core-revision-preflight.test.sh
       - uses: codecov/codecov-action@v5
         if: always()
         with:

package/_skeletons/plugin-template/scripts/core-revision-preflight.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env sh
+#
+# Core-revision preflight (#1604).
+#
+# ## Why this exists
+#
+# A sibling's deploy is structurally incapable of seeing core's deploy state:
+# `resolve-environment -> deploy-infra -> deploy-app` runs with no step that
+# reads anything about core, and its only post-deploy proof is its OWN Lambda
+# health and its OWN CDN route. Merge ordering does not fix this either — in
+# the recorded incident the core PR had already merged and the core deploy
+# simply sat in the runner queue while the sibling went live first, serving
+# requests against routes core had not shipped yet.
+#
+# The owner's decision (#1604): core publishes a DIGEST of its route table to
+# the existing public `.well-known/` channel — a monotonic revision counter
+# paired with a content hash, never the route surface itself (`/openapi.json`
+# stays 401-gated). This script is the consumer half: it asks "is core at
+# least at the revision I need", using ONLY that published digest, run
+# BEFORE `deploy-app` so a sibling that would go live ahead of core never
+# gets that far.
+#
+# ## Why "revision", not the hash
+#
+# The hash proves the route table is DIFFERENT from some prior observation;
+# it cannot prove "at or past", because "different" has no direction. The
+# published `revision` is core's `git rev-list --count HEAD` at deploy time
+# (scripts/route-table-digest.py) — the number of commits reachable from the
+# deployed commit, not a counter that increments once per deploy. That
+# distinction is the whole point: a deploy counter goes up on every run
+# regardless of what shipped, so a ROLLBACK (a new deploy of an OLDER
+# commit) would report a revision higher than the one that actually had the
+# routes a sibling needs — a false "yes, at or past" fired exactly when the
+# true answer is "no". A commit count is tied to the code's real position in
+# history: redeploying the same commit reports the same revision (correctly
+# "at least as new" — an equality, not a regression); rolling back to an
+# older commit reports a LOWER revision, because that commit genuinely has
+# fewer ancestors. This script only ever compares that one integer.
+#
+# ## This script's monotonicity guarantee is borrowed, not owned
+#
+# `git rev-list --count HEAD` is only monotonic/collision-free along one
+# continuous, non-rewritten history. If core's `dev`/`staging`/`main` ever
+# allowed force pushes or a non-linear history, a rewritten branch could
+# report a LOWER commit count for a commit that is, in reality, later —
+# silently undermining the one property this whole mechanism depends on,
+# with no signal anywhere in this script or its caller. Checked directly
+# against the live `keiranholloway/biffo-platform` repo during #1635's
+# prosecution: `allow_force_pushes: false`, `required_linear_history: true`
+# and `enforce_admins: true` are all set on every one of those branches
+# today, so the guarantee currently holds — but nothing in this script (or
+# in scripts/route-table-digest.py, which computes the number on the
+# publishing side) asserts that, or would notice if it changed. Deliberately
+# NOT asserted with a live GitHub API call here: this script runs in every
+# sibling's deploy job, on every deploy, and a branch-protection check would
+# add a second network dependency and a second way to fail closed for a
+# property that is core's to guarantee, not each sibling's to re-verify on
+# every run. If this ever needs enforcing rather than documenting, it
+# belongs as a periodic check against the CORE repo (once, not once per
+# sibling deploy) — not bolted onto this script.
+#
+# ## Fail-closed (the #1363 class)
+#
+# A sibling that declares no minimum has nothing to check — that is a
+# legitimate "I depend on nothing new from core" state, and it passes with a
+# notice. But once a minimum IS declared, absence of the digest — an older
+# core, a failed publish, a CDN cache miss — must never read as "satisfied".
+# It fails, and says WHICH: "missing/unreachable" and "present but behind"
+# are different facts, and a caller reading only the exit code must not be
+# able to mistake one for the other from the log.
+#
+# Exit codes:
+#   0 = no minimum declared (nothing to check), or core is at/past it.
+#   1 = core is behind the declared minimum, the digest is missing or
+#       unreachable, or the digest could not be parsed. Every one of these
+#       is "not verified as safe" and none may be treated as a pass.
+#
+# ## Usage
+#
+#   CORE_MIN_ROUTE_REVISION=42 \
+#   CORE_ROUTE_REVISION_URL=https://dev.example.com/.well-known/route-revision.json \
+#     sh scripts/core-revision-preflight.sh
+#
+# CORE_MIN_ROUTE_REVISION — the minimum core revision this sibling's code
+#                            needs. Set as a per-environment repo variable
+#                            (vars.CORE_MIN_ROUTE_REVISION), the same way a
+#                            version pin is set by hand: after merging the
+#                            core PR your sibling code depends on, read the
+#                            `revision` core published for that deploy and
+#                            record it here. Unset/empty means "no new
+#                            dependency" and the check is skipped.
+# CORE_ROUTE_REVISION_URL  — where to fetch the digest, typically
+#                            "${CORE_PORTAL_URL}/.well-known/route-revision.json".
+#                            Required whenever a minimum is declared.
+# PREFLIGHT_CURL           — override the curl binary/wrapper (tests use
+#                            this to point at a stub).
+#
+# Run this file's own tests: sh scripts/core-revision-preflight.test.sh
+
+set -u
+
+CURL=${PREFLIGHT_CURL:-curl}
+
+MIN=${CORE_MIN_ROUTE_REVISION:-}
+if [ -z "$MIN" ]; then
+  # Loud on purpose (#1635 prosecution finding 2). A green "Preflight — core
+  # route revision" step looks identical whether it actually checked
+  # something or checked nothing — the whole point of #1604 is to stop a
+  # sibling deploying blind, so its own "nothing to check" state must never
+  # read like "checked and fine". Same treatment this repo already gives the
+  # structurally identical deliberately-off case
+  # (SIBLING_DEPLOY_ENABLED=false in _skeletons/sibling-template's own
+  # deploy.yml): a GitHub Actions ::notice:: annotation, not a bare echo that
+  # only shows up if someone opens the step log.
+  MSG="core-revision-preflight: preflight did NOT run — CORE_MIN_ROUTE_REVISION is not set, so this sibling has declared no core-route dependency. This is 'nothing was checked', not 'core was checked and is ready'; set CORE_MIN_ROUTE_REVISION once this sibling depends on a specific core revision."
+  echo "::notice::${MSG}"
+  if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    echo "${MSG}" >> "$GITHUB_STEP_SUMMARY"
+  fi
+  exit 0
+fi
+
+case "$MIN" in
+  ''|*[!0-9]*)
+    echo "::error::core-revision-preflight: CORE_MIN_ROUTE_REVISION='$MIN' is not a non-negative integer." >&2
+    exit 1
+    ;;
+esac
+
+URL=${CORE_ROUTE_REVISION_URL:-}
+if [ -z "$URL" ]; then
+  echo "::error::core-revision-preflight: CORE_MIN_ROUTE_REVISION=$MIN is declared but CORE_ROUTE_REVISION_URL is not set — cannot fetch the digest to check it against. Refusing to proceed rather than assuming core is ready." >&2
+  exit 1
+fi
+
+BODY_FILE=/tmp/core-revision-preflight-body.$$
+ERR_FILE=/tmp/core-revision-preflight-err.$$
+trap 'rm -f "$BODY_FILE" "$ERR_FILE"' EXIT
+
+HTTP_CODE=$("$CURL" -sS --max-time 15 --retry 2 --retry-delay 2 \
+  -o "$BODY_FILE" -w '%{http_code}' "$URL" 2>"$ERR_FILE")
+RC=$?
+ERR=$(cat "$ERR_FILE" 2>/dev/null)
+
+if [ "$RC" -ne 0 ] || [ "$HTTP_CODE" != "200" ]; then
+  echo "::error::core-revision-preflight: no route-revision digest available at $URL (curl exit $RC, http ${HTTP_CODE:-none}${ERR:+, $ERR}). An absent or unreachable digest is treated as NOT satisfied — this is expected on an older core, a failed publish, or a CDN cache miss, and is a DIFFERENT fact from 'core is behind revision $MIN'. Refusing to deploy rather than assuming core is ready." >&2
+  exit 1
+fi
+
+ACTUAL=$(command -v jq >/dev/null 2>&1 && jq -r 'if (.revision | type) == "number" then (.revision | floor) else empty end' "$BODY_FILE" 2>/dev/null)
+
+case "${ACTUAL:-}" in
+  ''|*[!0-9]*)
+    echo "::error::core-revision-preflight: digest at $URL did not contain a valid integer 'revision' field. Treating a malformed digest the same as a missing one — refusing to deploy." >&2
+    exit 1
+    ;;
+esac
+
+if [ "$ACTUAL" -ge "$MIN" ]; then
+  echo "core-revision-preflight: OK — core is at revision $ACTUAL, this sibling needs at least $MIN."
+  exit 0
+fi
+
+echo "::error::core-revision-preflight: core is at revision $ACTUAL, but this sibling needs at least $MIN. Core has not deployed the routes this sibling depends on yet — refusing to deploy ahead of it." >&2
+exit 1

package/_skeletons/plugin-template/scripts/core-revision-preflight.test.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env sh
+#
+# Proves core-revision-preflight.sh (#1604) actually blocks a sibling that
+# would go live ahead of the core routes it depends on, passes it once core
+# has caught up, and fails CLOSED — never open — when the digest is missing.
+#
+# Stubs `curl` on PATH so this needs no network and no live deployment.
+#
+# Run: sh scripts/core-revision-preflight.test.sh
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+TARGET="$SCRIPT_DIR/core-revision-preflight.sh"
+STUB_DIR=$(mktemp -d)
+OUT_FILE=/tmp/core-revision-preflight-test-out.$$
+trap 'rm -rf "$STUB_DIR"; rm -f "$OUT_FILE"' EXIT
+
+FAILURES=0
+URL="https://dev.example.com/.well-known/route-revision.json"
+
+# _run <env assignments...> -- runs the target with PREFLIGHT_CURL pointed at
+# the stub, capturing combined output to $OUT_FILE and the exit code into
+# $LAST_RC. NOT run inside a subshell/command-substitution, so a caller that
+# wants to assert on both the exit code AND FAILURES afterward gets both —
+# an earlier version of this test ran the assertion inside `out=$(...)`,
+# which put the whole check in a subshell: FAILURES++ there never reached
+# the parent shell, so a real regression could not fail this test.
+_run() {
+  env "$@" sh -c "PREFLIGHT_CURL='$STUB_DIR/curl' sh '$TARGET'" >"$OUT_FILE" 2>&1
+  LAST_RC=$?
+}
+
+_assert_exit() {
+  # _assert_exit <scenario-name> <expected-exit>
+  name=$1
+  expected=$2
+  if [ "$LAST_RC" -eq "$expected" ]; then
+    echo "PASS: $name (exit $LAST_RC)"
+  else
+    echo "FAIL: $name — expected exit $expected, got $LAST_RC"
+    echo "--- output ---"
+    cat "$OUT_FILE"
+    echo "--------------"
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
+_assert_output_contains() {
+  # _assert_output_contains <scenario-name> <needle>
+  name=$1
+  needle=$2
+  if grep -qF "$needle" "$OUT_FILE"; then
+    echo "PASS: $name mentions '$needle'"
+  else
+    echo "FAIL: $name — expected output to mention '$needle'"
+    echo "--- output ---"
+    cat "$OUT_FILE"
+    echo "--------------"
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
+# --- Stub curl factory --------------------------------------------------
+# Writes a stub that returns a fixed http status + body for the one URL this
+# script ever fetches, or simulates a transport failure.
+_write_stub_ok() {
+  revision=$1
+  cat > "$STUB_DIR/curl" <<STUB
+#!/usr/bin/env sh
+outfile=""
+prev=""
+for a in "\$@"; do
+  case "\$prev" in
+    -o) outfile="\$a" ;;
+  esac
+  prev="\$a"
+done
+printf '{"revision": $revision, "hash": "deadbeef", "routeCount": 70, "generatedAt": "2026-08-17T00:00:00Z"}' > "\$outfile"
+printf '200'
+exit 0
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_unreachable() {
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+echo "curl: (6) Could not resolve host: dev.example.com" >&2
+exit 6
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_404() {
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+outfile=""
+prev=""
+for a in "$@"; do
+  case "$prev" in
+    -o) outfile="$a" ;;
+  esac
+  prev="$a"
+done
+printf 'Not Found' > "$outfile"
+printf '404'
+exit 0
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_never_called() {
+  # A curl invocation in this scenario is itself the bug — the script must
+  # short-circuit before ever fetching.
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+echo "curl invoked when it should not have been" >&2
+exit 99
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+# 1. No CORE_MIN_ROUTE_REVISION declared at all — this sibling depends on
+#    nothing new from core. Must pass WITHOUT even invoking curl, and must
+#    say so LOUDLY: a GitHub Actions ::notice:: annotation (not a bare echo
+#    a reader would have to open the step log to find), and never wording
+#    that could be mistaken for "checked and fine" (#1635 prosecution
+#    finding 2 — the same treatment this repo already gives
+#    SIBLING_DEPLOY_ENABLED=false).
+_write_stub_never_called
+_run -u CORE_MIN_ROUTE_REVISION -u CORE_ROUTE_REVISION_URL --
+_assert_exit "no minimum declared" 0
+_assert_output_contains "no minimum declared — is a ::notice:: annotation" "::notice::"
+_assert_output_contains "no minimum declared — says preflight did not run" "did NOT run"
+
+# 1b. Same scenario, but with GITHUB_STEP_SUMMARY set as it is in a real
+#     GitHub Actions run — the skip must ALSO land in the job summary, not
+#     only the step log, matching how this repo's own deploy-app.yml surfaces
+#     a deploy-time skip/failure to a reader who never opens raw logs.
+SUMMARY_FILE=/tmp/core-revision-preflight-test-summary.$$
+: > "$SUMMARY_FILE"
+_write_stub_never_called
+_run -u CORE_MIN_ROUTE_REVISION -u CORE_ROUTE_REVISION_URL -- GITHUB_STEP_SUMMARY="$SUMMARY_FILE"
+_assert_exit "no minimum declared, with GITHUB_STEP_SUMMARY set" 0
+if grep -qF "did NOT run" "$SUMMARY_FILE" 2>/dev/null; then
+  echo "PASS: no minimum declared — writes to \$GITHUB_STEP_SUMMARY"
+else
+  echo "FAIL: no minimum declared — expected \$GITHUB_STEP_SUMMARY ($SUMMARY_FILE) to mention 'did NOT run'"
+  echo "--- summary file ---"
+  cat "$SUMMARY_FILE" 2>/dev/null
+  echo "--------------------"
+  FAILURES=$((FAILURES + 1))
+fi
+rm -f "$SUMMARY_FILE"
+
+# 2. Sibling requires a revision core HAS reached (core is AHEAD) — passes.
+_write_stub_ok 50
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core ahead of required revision (42 <= 50)" 0
+_assert_output_contains "core ahead — names actual" "revision 50"
+
+# 2b. Exact match — core is AT the required revision — passes.
+_write_stub_ok 42
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core exactly at required revision" 0
+
+# 3. Sibling requires a revision core has NOT reached — fails, naming both
+#    the required and actual revisions.
+_write_stub_ok 10
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core behind required revision" 1
+_assert_output_contains "core behind — names actual" "revision 10"
+_assert_output_contains "core behind — names required" "at least 42"
+
+# 4. No digest published at all (transport failure) — fails CLOSED, and says
+#    the digest was missing rather than that the check passed.
+_write_stub_unreachable
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "digest unreachable" 1
+_assert_output_contains "digest unreachable — says missing, not behind" "no route-revision digest available"
+
+# 5. Digest endpoint 404s (older core / never published) — fails CLOSED, same
+#    "missing" message as scenario 4, never "core is behind".
+_write_stub_404
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "digest 404" 1
+_assert_output_contains "digest 404 — says missing" "no route-revision digest available"
+
+# 6. A minimum is declared but CORE_ROUTE_REVISION_URL is not set — must fail
+#    without invoking curl (misconfiguration, not "core is ready").
+_write_stub_never_called
+_run -u CORE_ROUTE_REVISION_URL -- CORE_MIN_ROUTE_REVISION=42
+_assert_exit "minimum declared but URL unset" 1
+
+echo
+if [ "$FAILURES" -eq 0 ]; then
+  echo "core-revision-preflight.test.sh: all checks passed."
+  exit 0
+else
+  echo "core-revision-preflight.test.sh: $FAILURES check(s) failed."
+  exit 1
+fi

package/_skeletons/sibling-template/.github/workflows/ci.yml

@@ -248,6 +248,17 @@ jobs:
         # failures against a stubbed curl. A verification script with no
         # caller is the class tracked in #1413; this is that caller.
         run: sh ../../scripts/routing-smoke-test.test.sh
+      - name: Core-revision preflight — self-test
+        if: ${{ !cancelled() }}
+        # Same shape as the routing smoke test above: not exercising a real
+        # core deployment (CI has none to reach), proves
+        # scripts/core-revision-preflight.sh — the deploy.yml
+        # preflight-core-revision job (#1604) that blocks this sibling from
+        # going live ahead of the core routes it depends on — still blocks a
+        # stale core, passes a current one, and fails CLOSED when the digest
+        # is missing, against a stubbed curl. Without this caller the script
+        # is the #1413 zero-caller class the instant it lands.
+        run: sh ../../scripts/core-revision-preflight.test.sh
 
   security-secrets:
     name: Secret Scan

package/_skeletons/sibling-template/.github/workflows/deploy.yml

@@ -141,9 +141,58 @@ jobs:
             --body "$(terraform output -raw lambda_function_name)" \
             --env "${{ needs.resolve-environment.outputs.environment }}"
 
+  # A sibling's deploy is structurally incapable of seeing core's deploy
+  # state: this workflow runs resolve-environment -> deploy-infra ->
+  # deploy-app with no step that reads anything about core, and its only
+  # post-deploy proof is its OWN Lambda health and its OWN CDN route. Merge
+  # ordering does not fix it either — in the recorded incident the core PR
+  # had already merged and the core deploy simply sat in the runner queue
+  # while the sibling went live first, serving requests against routes core
+  # had not shipped yet (#1604).
+  #
+  # Core publishes a DIGEST of its route table — never the surface itself,
+  # /openapi.json stays 401-gated — to the existing public .well-known/
+  # channel (scripts/route-table-digest.py in the core repo). This job asks
+  # that digest "is core at or past the revision this sibling needs" BEFORE
+  # deploy-app runs, and fails the whole workflow if it cannot say yes.
+  #
+  # Runs in parallel with deploy-infra (both depend only on
+  # resolve-environment) so it costs no extra wall-clock on a deploy that
+  # passes; deploy-app then needs both, so it never starts until this job
+  # has actually cleared.
+  preflight-core-revision:
+    name: Preflight — core route revision
+    needs: resolve-environment
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    environment: ${{ needs.resolve-environment.outputs.environment }}
+    if: vars.SIBLING_DEPLOY_ENABLED == 'true'
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - name: Core-revision preflight
+        # scripts/core-revision-preflight.sh does the actual check; see its
+        # own header for the full reasoning (why a monotonic revision rather
+        # than the hash, why absence fails closed rather than being treated
+        # as satisfied — the #1363 fail-open class, on the deploy path,
+        # would fire during exactly the incident this exists to prevent).
+        #
+        # CORE_MIN_ROUTE_REVISION is how THIS sibling declares which core
+        # revision its code depends on — set by hand as a per-environment
+        # repo variable, the same way a version pin is set: after merging
+        # the core PR your code needs, read the `revision` core published
+        # for that deploy from /.well-known/route-revision.json and record
+        # it here. Unset means "this sibling depends on nothing new from
+        # core" and the check is skipped — that is the correct default for
+        # a sibling that has never declared a dependency, not a fail-open:
+        # nothing here is being checked FOR IT to pass, there is simply
+        # nothing to check yet.
+        env:
+          CORE_MIN_ROUTE_REVISION: ${{ vars.CORE_MIN_ROUTE_REVISION }}
+          CORE_ROUTE_REVISION_URL: ${{ vars.CORE_PORTAL_URL }}/.well-known/route-revision.json
+        run: sh scripts/core-revision-preflight.sh
+
   deploy-app:
     name: Deploy app
-    needs: [resolve-environment, deploy-infra]
+    needs: [resolve-environment, deploy-infra, preflight-core-revision]
     runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
     environment: ${{ needs.resolve-environment.outputs.environment }}
     steps:
@@ -345,7 +394,7 @@ jobs:
   # and "never configured" are different facts and only one of them is a defect:
   deploy-status:
     name: Deploy status
-    needs: [resolve-environment, deploy-infra, deploy-app]
+    needs: [resolve-environment, deploy-infra, preflight-core-revision, deploy-app]
     if: always()
     runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
     steps:
@@ -353,9 +402,10 @@ jobs:
         env:
           ENABLED: ${{ vars.SIBLING_DEPLOY_ENABLED }}
           INFRA: ${{ needs.deploy-infra.result }}
+          PREFLIGHT: ${{ needs.preflight-core-revision.result }}
           APP: ${{ needs.deploy-app.result }}
         run: |
-          echo "SIBLING_DEPLOY_ENABLED='${ENABLED}'  deploy-infra=${INFRA}  deploy-app=${APP}"
+          echo "SIBLING_DEPLOY_ENABLED='${ENABLED}'  deploy-infra=${INFRA}  preflight-core-revision=${PREFLIGHT}  deploy-app=${APP}"
 
           if [ "${ENABLED}" = "false" ]; then
             echo "::notice::Deploys are deliberately disabled for this repo (SIBLING_DEPLOY_ENABLED=false). Nothing was deployed, by choice."
@@ -368,10 +418,14 @@ jobs:
           fi
 
           # A real failure already makes the run red for the right reason, and
-          # `deploy-app` needs `deploy-infra` — so a failed infra job SKIPS the
-          # app job. Reporting that skip as "deployed nothing" would bury the
-          # actual cause under a second, wrong error. Defer to the real one.
-          case "${INFRA}:${APP}" in
+          # `deploy-app` needs `deploy-infra` AND `preflight-core-revision` —
+          # so a failed infra job or a preflight that blocked a stale sibling
+          # SKIPS the app job. Reporting that skip as "deployed nothing" would
+          # bury the actual cause (visible on the failed job itself, e.g.
+          # core-revision-preflight.sh's own ::error:: naming the required
+          # and actual revisions, #1604) under a second, vaguer error. Defer
+          # to the real one.
+          case "${INFRA}:${PREFLIGHT}:${APP}" in
             *failure*|*cancelled*)
               echo "A deploy job failed or was cancelled; that failure is the run's result. Not adding a second error."
               exit 0
@@ -380,7 +434,7 @@ jobs:
 
           # Enabled — the jobs were meant to run. 'skipped' here means a gate
           # upstream of them suppressed the work while the run still went green.
-          for pair in "deploy-infra:${INFRA}" "deploy-app:${APP}"; do
+          for pair in "deploy-infra:${INFRA}" "preflight-core-revision:${PREFLIGHT}" "deploy-app:${APP}"; do
             job="${pair%%:*}"
             result="${pair#*:}"
             if [ "${result}" = "skipped" ]; then
@@ -389,4 +443,4 @@ jobs:
             fi
           done
 
-          echo "Deploy jobs ran (infra=${INFRA}, app=${APP})."
+          echo "Deploy jobs ran (infra=${INFRA}, preflight=${PREFLIGHT}, app=${APP})."

package/_skeletons/sibling-template/scripts/core-revision-preflight.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env sh
+#
+# Core-revision preflight (#1604).
+#
+# ## Why this exists
+#
+# A sibling's deploy is structurally incapable of seeing core's deploy state:
+# `resolve-environment -> deploy-infra -> deploy-app` runs with no step that
+# reads anything about core, and its only post-deploy proof is its OWN Lambda
+# health and its OWN CDN route. Merge ordering does not fix this either — in
+# the recorded incident the core PR had already merged and the core deploy
+# simply sat in the runner queue while the sibling went live first, serving
+# requests against routes core had not shipped yet.
+#
+# The owner's decision (#1604): core publishes a DIGEST of its route table to
+# the existing public `.well-known/` channel — a monotonic revision counter
+# paired with a content hash, never the route surface itself (`/openapi.json`
+# stays 401-gated). This script is the consumer half: it asks "is core at
+# least at the revision I need", using ONLY that published digest, run
+# BEFORE `deploy-app` so a sibling that would go live ahead of core never
+# gets that far.
+#
+# ## Why "revision", not the hash
+#
+# The hash proves the route table is DIFFERENT from some prior observation;
+# it cannot prove "at or past", because "different" has no direction. The
+# published `revision` is core's `git rev-list --count HEAD` at deploy time
+# (scripts/route-table-digest.py) — the number of commits reachable from the
+# deployed commit, not a counter that increments once per deploy. That
+# distinction is the whole point: a deploy counter goes up on every run
+# regardless of what shipped, so a ROLLBACK (a new deploy of an OLDER
+# commit) would report a revision higher than the one that actually had the
+# routes a sibling needs — a false "yes, at or past" fired exactly when the
+# true answer is "no". A commit count is tied to the code's real position in
+# history: redeploying the same commit reports the same revision (correctly
+# "at least as new" — an equality, not a regression); rolling back to an
+# older commit reports a LOWER revision, because that commit genuinely has
+# fewer ancestors. This script only ever compares that one integer.
+#
+# ## This script's monotonicity guarantee is borrowed, not owned
+#
+# `git rev-list --count HEAD` is only monotonic/collision-free along one
+# continuous, non-rewritten history. If core's `dev`/`staging`/`main` ever
+# allowed force pushes or a non-linear history, a rewritten branch could
+# report a LOWER commit count for a commit that is, in reality, later —
+# silently undermining the one property this whole mechanism depends on,
+# with no signal anywhere in this script or its caller. Checked directly
+# against the live `keiranholloway/biffo-platform` repo during #1635's
+# prosecution: `allow_force_pushes: false`, `required_linear_history: true`
+# and `enforce_admins: true` are all set on every one of those branches
+# today, so the guarantee currently holds — but nothing in this script (or
+# in scripts/route-table-digest.py, which computes the number on the
+# publishing side) asserts that, or would notice if it changed. Deliberately
+# NOT asserted with a live GitHub API call here: this script runs in every
+# sibling's deploy job, on every deploy, and a branch-protection check would
+# add a second network dependency and a second way to fail closed for a
+# property that is core's to guarantee, not each sibling's to re-verify on
+# every run. If this ever needs enforcing rather than documenting, it
+# belongs as a periodic check against the CORE repo (once, not once per
+# sibling deploy) — not bolted onto this script.
+#
+# ## Fail-closed (the #1363 class)
+#
+# A sibling that declares no minimum has nothing to check — that is a
+# legitimate "I depend on nothing new from core" state, and it passes with a
+# notice. But once a minimum IS declared, absence of the digest — an older
+# core, a failed publish, a CDN cache miss — must never read as "satisfied".
+# It fails, and says WHICH: "missing/unreachable" and "present but behind"
+# are different facts, and a caller reading only the exit code must not be
+# able to mistake one for the other from the log.
+#
+# Exit codes:
+#   0 = no minimum declared (nothing to check), or core is at/past it.
+#   1 = core is behind the declared minimum, the digest is missing or
+#       unreachable, or the digest could not be parsed. Every one of these
+#       is "not verified as safe" and none may be treated as a pass.
+#
+# ## Usage
+#
+#   CORE_MIN_ROUTE_REVISION=42 \
+#   CORE_ROUTE_REVISION_URL=https://dev.example.com/.well-known/route-revision.json \
+#     sh scripts/core-revision-preflight.sh
+#
+# CORE_MIN_ROUTE_REVISION — the minimum core revision this sibling's code
+#                            needs. Set as a per-environment repo variable
+#                            (vars.CORE_MIN_ROUTE_REVISION), the same way a
+#                            version pin is set by hand: after merging the
+#                            core PR your sibling code depends on, read the
+#                            `revision` core published for that deploy and
+#                            record it here. Unset/empty means "no new
+#                            dependency" and the check is skipped.
+# CORE_ROUTE_REVISION_URL  — where to fetch the digest, typically
+#                            "${CORE_PORTAL_URL}/.well-known/route-revision.json".
+#                            Required whenever a minimum is declared.
+# PREFLIGHT_CURL           — override the curl binary/wrapper (tests use
+#                            this to point at a stub).
+#
+# Run this file's own tests: sh scripts/core-revision-preflight.test.sh
+
+set -u
+
+CURL=${PREFLIGHT_CURL:-curl}
+
+MIN=${CORE_MIN_ROUTE_REVISION:-}
+if [ -z "$MIN" ]; then
+  # Loud on purpose (#1635 prosecution finding 2). A green "Preflight — core
+  # route revision" step looks identical whether it actually checked
+  # something or checked nothing — the whole point of #1604 is to stop a
+  # sibling deploying blind, so its own "nothing to check" state must never
+  # read like "checked and fine". Same treatment this repo already gives the
+  # structurally identical deliberately-off case
+  # (SIBLING_DEPLOY_ENABLED=false in _skeletons/sibling-template's own
+  # deploy.yml): a GitHub Actions ::notice:: annotation, not a bare echo that
+  # only shows up if someone opens the step log.
+  MSG="core-revision-preflight: preflight did NOT run — CORE_MIN_ROUTE_REVISION is not set, so this sibling has declared no core-route dependency. This is 'nothing was checked', not 'core was checked and is ready'; set CORE_MIN_ROUTE_REVISION once this sibling depends on a specific core revision."
+  echo "::notice::${MSG}"
+  if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    echo "${MSG}" >> "$GITHUB_STEP_SUMMARY"
+  fi
+  exit 0
+fi
+
+case "$MIN" in
+  ''|*[!0-9]*)
+    echo "::error::core-revision-preflight: CORE_MIN_ROUTE_REVISION='$MIN' is not a non-negative integer." >&2
+    exit 1
+    ;;
+esac
+
+URL=${CORE_ROUTE_REVISION_URL:-}
+if [ -z "$URL" ]; then
+  echo "::error::core-revision-preflight: CORE_MIN_ROUTE_REVISION=$MIN is declared but CORE_ROUTE_REVISION_URL is not set — cannot fetch the digest to check it against. Refusing to proceed rather than assuming core is ready." >&2
+  exit 1
+fi
+
+BODY_FILE=/tmp/core-revision-preflight-body.$$
+ERR_FILE=/tmp/core-revision-preflight-err.$$
+trap 'rm -f "$BODY_FILE" "$ERR_FILE"' EXIT
+
+HTTP_CODE=$("$CURL" -sS --max-time 15 --retry 2 --retry-delay 2 \
+  -o "$BODY_FILE" -w '%{http_code}' "$URL" 2>"$ERR_FILE")
+RC=$?
+ERR=$(cat "$ERR_FILE" 2>/dev/null)
+
+if [ "$RC" -ne 0 ] || [ "$HTTP_CODE" != "200" ]; then
+  echo "::error::core-revision-preflight: no route-revision digest available at $URL (curl exit $RC, http ${HTTP_CODE:-none}${ERR:+, $ERR}). An absent or unreachable digest is treated as NOT satisfied — this is expected on an older core, a failed publish, or a CDN cache miss, and is a DIFFERENT fact from 'core is behind revision $MIN'. Refusing to deploy rather than assuming core is ready." >&2
+  exit 1
+fi
+
+ACTUAL=$(command -v jq >/dev/null 2>&1 && jq -r 'if (.revision | type) == "number" then (.revision | floor) else empty end' "$BODY_FILE" 2>/dev/null)
+
+case "${ACTUAL:-}" in
+  ''|*[!0-9]*)
+    echo "::error::core-revision-preflight: digest at $URL did not contain a valid integer 'revision' field. Treating a malformed digest the same as a missing one — refusing to deploy." >&2
+    exit 1
+    ;;
+esac
+
+if [ "$ACTUAL" -ge "$MIN" ]; then
+  echo "core-revision-preflight: OK — core is at revision $ACTUAL, this sibling needs at least $MIN."
+  exit 0
+fi
+
+echo "::error::core-revision-preflight: core is at revision $ACTUAL, but this sibling needs at least $MIN. Core has not deployed the routes this sibling depends on yet — refusing to deploy ahead of it." >&2
+exit 1

package/_skeletons/sibling-template/scripts/core-revision-preflight.test.sh

@@ -0,0 +1,203 @@
+#!/usr/bin/env sh
+#
+# Proves core-revision-preflight.sh (#1604) actually blocks a sibling that
+# would go live ahead of the core routes it depends on, passes it once core
+# has caught up, and fails CLOSED — never open — when the digest is missing.
+#
+# Stubs `curl` on PATH so this needs no network and no live deployment.
+#
+# Run: sh scripts/core-revision-preflight.test.sh
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+TARGET="$SCRIPT_DIR/core-revision-preflight.sh"
+STUB_DIR=$(mktemp -d)
+OUT_FILE=/tmp/core-revision-preflight-test-out.$$
+trap 'rm -rf "$STUB_DIR"; rm -f "$OUT_FILE"' EXIT
+
+FAILURES=0
+URL="https://dev.example.com/.well-known/route-revision.json"
+
+# _run <env assignments...> -- runs the target with PREFLIGHT_CURL pointed at
+# the stub, capturing combined output to $OUT_FILE and the exit code into
+# $LAST_RC. NOT run inside a subshell/command-substitution, so a caller that
+# wants to assert on both the exit code AND FAILURES afterward gets both —
+# an earlier version of this test ran the assertion inside `out=$(...)`,
+# which put the whole check in a subshell: FAILURES++ there never reached
+# the parent shell, so a real regression could not fail this test.
+_run() {
+  env "$@" sh -c "PREFLIGHT_CURL='$STUB_DIR/curl' sh '$TARGET'" >"$OUT_FILE" 2>&1
+  LAST_RC=$?
+}
+
+_assert_exit() {
+  # _assert_exit <scenario-name> <expected-exit>
+  name=$1
+  expected=$2
+  if [ "$LAST_RC" -eq "$expected" ]; then
+    echo "PASS: $name (exit $LAST_RC)"
+  else
+    echo "FAIL: $name — expected exit $expected, got $LAST_RC"
+    echo "--- output ---"
+    cat "$OUT_FILE"
+    echo "--------------"
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
+_assert_output_contains() {
+  # _assert_output_contains <scenario-name> <needle>
+  name=$1
+  needle=$2
+  if grep -qF "$needle" "$OUT_FILE"; then
+    echo "PASS: $name mentions '$needle'"
+  else
+    echo "FAIL: $name — expected output to mention '$needle'"
+    echo "--- output ---"
+    cat "$OUT_FILE"
+    echo "--------------"
+    FAILURES=$((FAILURES + 1))
+  fi
+}
+
+# --- Stub curl factory --------------------------------------------------
+# Writes a stub that returns a fixed http status + body for the one URL this
+# script ever fetches, or simulates a transport failure.
+_write_stub_ok() {
+  revision=$1
+  cat > "$STUB_DIR/curl" <<STUB
+#!/usr/bin/env sh
+outfile=""
+prev=""
+for a in "\$@"; do
+  case "\$prev" in
+    -o) outfile="\$a" ;;
+  esac
+  prev="\$a"
+done
+printf '{"revision": $revision, "hash": "deadbeef", "routeCount": 70, "generatedAt": "2026-08-17T00:00:00Z"}' > "\$outfile"
+printf '200'
+exit 0
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_unreachable() {
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+echo "curl: (6) Could not resolve host: dev.example.com" >&2
+exit 6
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_404() {
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+outfile=""
+prev=""
+for a in "$@"; do
+  case "$prev" in
+    -o) outfile="$a" ;;
+  esac
+  prev="$a"
+done
+printf 'Not Found' > "$outfile"
+printf '404'
+exit 0
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+_write_stub_never_called() {
+  # A curl invocation in this scenario is itself the bug — the script must
+  # short-circuit before ever fetching.
+  cat > "$STUB_DIR/curl" <<'STUB'
+#!/usr/bin/env sh
+echo "curl invoked when it should not have been" >&2
+exit 99
+STUB
+  chmod +x "$STUB_DIR/curl"
+}
+
+# 1. No CORE_MIN_ROUTE_REVISION declared at all — this sibling depends on
+#    nothing new from core. Must pass WITHOUT even invoking curl, and must
+#    say so LOUDLY: a GitHub Actions ::notice:: annotation (not a bare echo
+#    a reader would have to open the step log to find), and never wording
+#    that could be mistaken for "checked and fine" (#1635 prosecution
+#    finding 2 — the same treatment this repo already gives
+#    SIBLING_DEPLOY_ENABLED=false).
+_write_stub_never_called
+_run -u CORE_MIN_ROUTE_REVISION -u CORE_ROUTE_REVISION_URL --
+_assert_exit "no minimum declared" 0
+_assert_output_contains "no minimum declared — is a ::notice:: annotation" "::notice::"
+_assert_output_contains "no minimum declared — says preflight did not run" "did NOT run"
+
+# 1b. Same scenario, but with GITHUB_STEP_SUMMARY set as it is in a real
+#     GitHub Actions run — the skip must ALSO land in the job summary, not
+#     only the step log, matching how this repo's own deploy-app.yml surfaces
+#     a deploy-time skip/failure to a reader who never opens raw logs.
+SUMMARY_FILE=/tmp/core-revision-preflight-test-summary.$$
+: > "$SUMMARY_FILE"
+_write_stub_never_called
+_run -u CORE_MIN_ROUTE_REVISION -u CORE_ROUTE_REVISION_URL -- GITHUB_STEP_SUMMARY="$SUMMARY_FILE"
+_assert_exit "no minimum declared, with GITHUB_STEP_SUMMARY set" 0
+if grep -qF "did NOT run" "$SUMMARY_FILE" 2>/dev/null; then
+  echo "PASS: no minimum declared — writes to \$GITHUB_STEP_SUMMARY"
+else
+  echo "FAIL: no minimum declared — expected \$GITHUB_STEP_SUMMARY ($SUMMARY_FILE) to mention 'did NOT run'"
+  echo "--- summary file ---"
+  cat "$SUMMARY_FILE" 2>/dev/null
+  echo "--------------------"
+  FAILURES=$((FAILURES + 1))
+fi
+rm -f "$SUMMARY_FILE"
+
+# 2. Sibling requires a revision core HAS reached (core is AHEAD) — passes.
+_write_stub_ok 50
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core ahead of required revision (42 <= 50)" 0
+_assert_output_contains "core ahead — names actual" "revision 50"
+
+# 2b. Exact match — core is AT the required revision — passes.
+_write_stub_ok 42
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core exactly at required revision" 0
+
+# 3. Sibling requires a revision core has NOT reached — fails, naming both
+#    the required and actual revisions.
+_write_stub_ok 10
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "core behind required revision" 1
+_assert_output_contains "core behind — names actual" "revision 10"
+_assert_output_contains "core behind — names required" "at least 42"
+
+# 4. No digest published at all (transport failure) — fails CLOSED, and says
+#    the digest was missing rather than that the check passed.
+_write_stub_unreachable
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "digest unreachable" 1
+_assert_output_contains "digest unreachable — says missing, not behind" "no route-revision digest available"
+
+# 5. Digest endpoint 404s (older core / never published) — fails CLOSED, same
+#    "missing" message as scenario 4, never "core is behind".
+_write_stub_404
+_run CORE_MIN_ROUTE_REVISION=42 CORE_ROUTE_REVISION_URL="$URL"
+_assert_exit "digest 404" 1
+_assert_output_contains "digest 404 — says missing" "no route-revision digest available"
+
+# 6. A minimum is declared but CORE_ROUTE_REVISION_URL is not set — must fail
+#    without invoking curl (misconfiguration, not "core is ready").
+_write_stub_never_called
+_run -u CORE_ROUTE_REVISION_URL -- CORE_MIN_ROUTE_REVISION=42
+_assert_exit "minimum declared but URL unset" 1
+
+echo
+if [ "$FAILURES" -eq 0 ]; then
+  echo "core-revision-preflight.test.sh: all checks passed."
+  exit 0
+else
+  echo "core-revision-preflight.test.sh: $FAILURES check(s) failed."
+  exit 1
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.292.0",
+  "version": "0.294.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",