@biffo/cli 0.301.14 → 0.301.16

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

@@ -126,6 +126,18 @@ jobs:
         # 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
+      - name: Core-version preflight — self-test
+        if: ${{ !cancelled() }}
+        # scripts/core-version-preflight.sh (biffo-template#1605) is
+        # distributed here too, verbatim, via shared-files.json's `files` —
+        # same reasoning as the Core-revision preflight self-test above: a
+        # plugin repo has no deploy.yml, so it is never invoked for a REAL
+        # preflight here 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 health
+        # document is missing or reports "unknown", against a stubbed curl.
+        run: sh scripts/core-version-preflight.test.sh
       - name: Guard self-test wiring — this repo's own scripts/*.test.sh
         if: ${{ !cancelled() }}
         # Level-3 self-audit (biffo-template#1710): the template repo's own

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env sh
+#
+# Core-version preflight (#1605).
+#
+# ## Why this exists
+#
+# A sibling can deploy against a core instance whose TEMPLATE version is
+# older than the sibling's code needs — a different failure from #1604's
+# route-ordering race. #1604 asks "has core shipped the specific route my
+# code depends on RIGHT NOW"; this asks "is the instance running at least
+# the core template capability my code was written against". The two are
+# deliberately separate scripts and separate deploy jobs, because they read
+# different signals and fail for different reasons — conflating them would
+# make either failure's message describe the wrong problem. This script does
+# NOT address, and is not a substitute for, #1604's deploy-ordering race.
+#
+# ## The signal
+#
+# `services/api/src/api/routers/health.py` returns `core_version()`, baked
+# in at package time by `scripts/resolve-core-version.sh`, and is publicly
+# reachable with no credential at `/api/v1/health` on every deployed
+# instance (`{"status":"ok","version":"0.287.12"}`). Nothing new is
+# published for this script — it reads a signal that already exists.
+#
+# ## Why NOT biffo.sibling.json's `template_version`
+#
+# The obvious-looking home for a declared floor is the sibling's own
+# `template_version` field. It is the wrong field: ADR-0007 states it is
+# stamped ONCE at scaffold time from `getLatestCoreVersion()`, is
+# "visibility only", and explicitly "nothing reads or compares the field
+# yet" — it is a backward PROVENANCE stamp that only ever falls further
+# behind, not a forward REQUIREMENT that rises as a sibling adopts newer
+# core capability. Measured live across all five real siblings at the time
+# #1605 was picked up: four had no `template_version` at all and the fifth
+# was ~80 minor versions behind the running core — reusing it as a floor
+# would be inert for four siblings and trivially satisfied by the fifth.
+# Mirroring #1604's already-proven shape instead: a per-environment GitHub
+# Actions repo variable the sibling sets by hand, the same way
+# CORE_MIN_ROUTE_REVISION is set — no JSON schema change, no ADR amendment,
+# no new document.
+#
+# ## Fail-closed (the #1363 class)
+#
+# A sibling that declares no minimum has nothing to check — that is a
+# legitimate "I depend on nothing beyond whatever core happens to be
+# running" state, and it passes with a notice. Once a minimum IS declared,
+# absence of a valid version in the health response — an unreachable
+# instance, a non-packaged deployment reporting the literal string
+# "unknown" (health.py's own documented fallback), a malformed body — 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.
+#
+# ## Version comparison
+#
+# Both versions are dotted non-negative-integer strings (e.g. "0.287.12"),
+# the shape every `core-v*` tag and every `biffo.core.json` `.version` takes
+# (see resolve-core-version.sh). Compared segment-by-segment, numerically,
+# left to right, with a missing trailing segment on either side treated as
+# 0 — so "0.287" and "0.287.0" compare equal, and "0.9" is correctly less
+# than "0.10". This is deliberately NOT full semver (no pre-release/build
+# metadata) because nothing in this estate's version strings ever carries
+# either.
+#
+# Exit codes:
+#   0 = no minimum declared (nothing to check), or the instance is at/past it.
+#   1 = the instance is behind the declared minimum, its health endpoint is
+#       unreachable, or its reported version could not be parsed. Every one
+#       of these is "not verified as safe" and none may be treated as a pass.
+#
+# ## Usage
+#
+#   CORE_MIN_TEMPLATE_VERSION=0.250.0 \
+#   CORE_HEALTH_URL=https://dev.example.com/api/v1/health \
+#     sh scripts/core-version-preflight.sh
+#
+# CORE_MIN_TEMPLATE_VERSION — the minimum core template version this
+#                              sibling's code needs. Set as a per-environment
+#                              repo variable (vars.CORE_MIN_TEMPLATE_VERSION),
+#                              the same way CORE_MIN_ROUTE_REVISION is set by
+#                              hand. Unset/empty means "no floor declared"
+#                              and the check is skipped.
+# CORE_HEALTH_URL           — where to fetch the instance's health document,
+#                              typically "${CORE_API_URL}/api/v1/health".
+#                              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-version-preflight.test.sh
+
+set -u
+
+CURL=${PREFLIGHT_CURL:-curl}
+
+MIN=${CORE_MIN_TEMPLATE_VERSION:-}
+if [ -z "$MIN" ]; then
+  # Loud on purpose, matching core-revision-preflight.sh's own reasoning: a
+  # green "Preflight — core template version" step must never look
+  # identical whether it actually checked something or checked nothing.
+  MSG="core-version-preflight: preflight did NOT run — CORE_MIN_TEMPLATE_VERSION is not set, so this sibling has declared no core-template-version dependency. This is 'nothing was checked', not 'core was checked and is ready'; set CORE_MIN_TEMPLATE_VERSION once this sibling depends on a specific core template version."
+  echo "::notice::${MSG}"
+  if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    echo "${MSG}" >> "$GITHUB_STEP_SUMMARY"
+  fi
+  exit 0
+fi
+
+is_version() {
+  printf '%s' "$1" | grep -Eq '^[0-9]+(\.[0-9]+)*$'
+}
+
+if ! is_version "$MIN"; then
+  echo "::error::core-version-preflight: CORE_MIN_TEMPLATE_VERSION='$MIN' is not a dotted non-negative-integer version (e.g. '0.250.0')." >&2
+  exit 1
+fi
+
+URL=${CORE_HEALTH_URL:-}
+if [ -z "$URL" ]; then
+  echo "::error::core-version-preflight: CORE_MIN_TEMPLATE_VERSION=$MIN is declared but CORE_HEALTH_URL is not set — cannot fetch the instance's health document to check it against. Refusing to proceed rather than assuming core is ready." >&2
+  exit 1
+fi
+
+BODY_FILE=/tmp/core-version-preflight-body.$$
+ERR_FILE=/tmp/core-version-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-version-preflight: no health response available at $URL (curl exit $RC, http ${HTTP_CODE:-none}${ERR:+, $ERR}). An absent or unreachable health endpoint is treated as NOT satisfied — this is expected on a down instance, a network issue, or a not-yet-deployed core — and is a DIFFERENT fact from 'core is behind version $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 (.version | type) == "string" then .version else empty end' "$BODY_FILE" 2>/dev/null)
+
+if [ -z "${ACTUAL:-}" ] || ! is_version "$ACTUAL"; then
+  # Deliberately covers health.py's own documented fallback: outside a
+  # packaged deployment it returns the literal string "unknown", which is
+  # not a version and must fail the same way a missing/malformed body does
+  # — never be silently treated as satisfied.
+  echo "::error::core-version-preflight: health document at $URL did not contain a valid dotted version in 'version' (got '${ACTUAL:-<empty>}'). Treating a malformed or unknown version the same as a missing one — refusing to deploy." >&2
+  exit 1
+fi
+
+version_ge() {
+  # Prints "1" if $1 >= $2, "0" otherwise — dotted numeric segments compared
+  # left to right, missing trailing segments on either side treated as 0.
+  awk -v a="$1" -v b="$2" '
+    BEGIN {
+      na = split(a, pa, ".")
+      nb = split(b, pb, ".")
+      n = (na > nb) ? na : nb
+      for (i = 1; i <= n; i++) {
+        x = (i <= na) ? pa[i] + 0 : 0
+        y = (i <= nb) ? pb[i] + 0 : 0
+        if (x > y) { print "1"; exit }
+        if (x < y) { print "0"; exit }
+      }
+      print "1"
+    }
+  '
+}
+
+if [ "$(version_ge "$ACTUAL" "$MIN")" = "1" ]; then
+  echo "core-version-preflight: OK — core is at version $ACTUAL, this sibling needs at least $MIN."
+  exit 0
+fi
+
+echo "::error::core-version-preflight: core is at version $ACTUAL, but this sibling needs at least $MIN. The instance has not upgraded to the core template version this sibling depends on yet — refusing to deploy ahead of it." >&2
+exit 1

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

@@ -0,0 +1,220 @@
+#!/usr/bin/env sh
+#
+# Proves core-version-preflight.sh (#1605) actually blocks a sibling from
+# deploying against an instance whose core template version is too old,
+# passes it once the instance has caught up, and fails CLOSED — never open
+# — when the health document is missing, unreachable, or reports the
+# "unknown" version health.py falls back to outside a packaged deployment.
+#
+# Stubs `curl` on PATH so this needs no network and no live deployment.
+#
+# Run: sh scripts/core-version-preflight.test.sh
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+TARGET="$SCRIPT_DIR/core-version-preflight.sh"
+STUB_DIR=$(mktemp -d)
+OUT_FILE=/tmp/core-version-preflight-test-out.$$
+trap 'rm -rf "$STUB_DIR"; rm -f "$OUT_FILE"' EXIT
+
+FAILURES=0
+URL="https://dev.example.com/api/v1/health"
+
+# _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, matching
+# core-revision-preflight.test.sh's own reasoning: an assertion made inside
+# `out=$(...)` runs FAILURES++ in a subshell that never reaches the parent,
+# so a real regression could not fail the 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() {
+  version=$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 '{"status": "ok", "version": "$version"}' > "\$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_TEMPLATE_VERSION declared at all — this sibling depends on
+#    no specific core template version. 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".
+_write_stub_never_called
+_run -u CORE_MIN_TEMPLATE_VERSION -u CORE_HEALTH_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.
+SUMMARY_FILE=/tmp/core-version-preflight-test-summary.$$
+: > "$SUMMARY_FILE"
+_write_stub_never_called
+_run -u CORE_MIN_TEMPLATE_VERSION -u CORE_HEALTH_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 version core HAS reached (core is AHEAD) — passes.
+_write_stub_ok "0.287.12"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core ahead of required version (0.250.0 <= 0.287.12)" 0
+_assert_output_contains "core ahead — names actual" "version 0.287.12"
+
+# 2b. Exact match — core is AT the required version — passes.
+_write_stub_ok "0.250.0"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core exactly at required version" 0
+
+# 2c. Lexicographic trap: "0.9" must compare LESS than "0.10" numerically,
+#     not greater as a naive string compare would report.
+_write_stub_ok "0.9.0"
+_run CORE_MIN_TEMPLATE_VERSION=0.10.0 CORE_HEALTH_URL="$URL"
+_assert_exit "0.9.0 is numerically behind 0.10.0 (string compare would say ahead)" 1
+
+# 2d. Missing trailing segment treated as 0 — "0.287" == "0.287.0".
+_write_stub_ok "0.287"
+_run CORE_MIN_TEMPLATE_VERSION=0.287.0 CORE_HEALTH_URL="$URL"
+_assert_exit "0.287 satisfies a 0.287.0 floor (missing segment = 0)" 0
+
+# 3. Sibling requires a version core has NOT reached — fails, naming both
+#    the required and actual versions.
+_write_stub_ok "0.208.1"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core behind required version" 1
+_assert_output_contains "core behind — names actual" "version 0.208.1"
+_assert_output_contains "core behind — names required" "at least 0.250.0"
+
+# 4. No health document available at all (transport failure) — fails
+#    CLOSED, and says the health endpoint was missing rather than that core
+#    is behind.
+_write_stub_unreachable
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "health endpoint unreachable" 1
+_assert_output_contains "health endpoint unreachable — says missing, not behind" "no health response available"
+
+# 5. Health endpoint 404s — fails CLOSED, same "missing" message as
+#    scenario 4, never "core is behind".
+_write_stub_404
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "health endpoint 404" 1
+_assert_output_contains "health endpoint 404 — says missing" "no health response available"
+
+# 6. Instance reports the literal "unknown" version — health.py's own
+#    documented fallback outside a packaged deployment. Must fail CLOSED
+#    exactly like a malformed/missing body, never be treated as satisfied.
+_write_stub_ok "unknown"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "instance reports 'unknown' version" 1
+_assert_output_contains "'unknown' version — treated as malformed, not satisfied" "did not contain a valid dotted version"
+
+# 7. A minimum is declared but CORE_HEALTH_URL is not set — must fail
+#    without invoking curl (misconfiguration, not "core is ready").
+_write_stub_never_called
+_run -u CORE_HEALTH_URL -- CORE_MIN_TEMPLATE_VERSION=0.250.0
+_assert_exit "minimum declared but URL unset" 1
+
+echo
+if [ "$FAILURES" -eq 0 ]; then
+  echo "core-version-preflight.test.sh: all checks passed."
+  exit 0
+else
+  echo "core-version-preflight.test.sh: $FAILURES check(s) failed."
+  exit 1
+fi

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

@@ -274,6 +274,18 @@ jobs:
         # 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
+      - name: Core-version preflight — self-test
+        if: ${{ !cancelled() }}
+        # Same shape as the two self-tests above: not exercising a real core
+        # deployment (CI has none to reach), proves
+        # scripts/core-version-preflight.sh — the deploy.yml
+        # preflight-core-version job (#1605) that blocks this sibling from
+        # deploying against an instance whose core TEMPLATE version is too
+        # old — still blocks a stale core, passes a current one, and fails
+        # CLOSED when the health document is missing or reports "unknown",
+        # against a stubbed curl. Without this caller the script is the
+        # #1413 zero-caller class the instant it lands.
+        run: sh ../../scripts/core-version-preflight.test.sh
       - name: Guard self-test wiring — this repo's own scripts/*.test.sh
         if: ${{ !cancelled() }}
         working-directory: .

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

@@ -190,9 +190,52 @@ jobs:
           CORE_ROUTE_REVISION_URL: ${{ vars.CORE_PORTAL_URL }}/.well-known/route-revision.json
         run: sh scripts/core-revision-preflight.sh
 
+  # A DIFFERENT dependency from preflight-core-revision above: that job asks
+  # "has core shipped the specific ROUTE my code depends on right now" (a
+  # deploy-ORDERING race, #1604/#903). This asks "is the instance running at
+  # least the core TEMPLATE version my code was written against" — a much
+  # coarser, cheaper signal that does not require core to have published
+  # anything new. It reuses core's existing, already-public /api/v1/health
+  # endpoint (services/api/src/api/routers/health.py), which reports
+  # core_version() baked in at package time. #1605 split this off #903
+  # deliberately: it does NOT address #903's ordering race, only the
+  # separate case of a sibling deploying against a core template that is
+  # simply too old for what the sibling needs.
+  #
+  # Runs in parallel with deploy-infra and preflight-core-revision (all three
+  # depend only on resolve-environment) so it costs no extra wall-clock on a
+  # deploy that passes; deploy-app then needs all three.
+  preflight-core-version:
+    name: Preflight — core template version
+    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-version preflight
+        # scripts/core-version-preflight.sh does the actual check; see its
+        # own header for the full reasoning (why NOT biffo.sibling.json's
+        # template_version, why absence fails closed rather than being
+        # treated as satisfied — the #1363 fail-open class, same as
+        # preflight-core-revision above).
+        #
+        # CORE_MIN_TEMPLATE_VERSION is how THIS sibling declares which core
+        # template version its code depends on — set by hand as a
+        # per-environment repo variable, the same way CORE_MIN_ROUTE_REVISION
+        # is set: after merging a core PR your code needs, record the
+        # version /api/v1/health reports for that deploy here. Unset means
+        # "this sibling depends on no specific core template version" and
+        # the check is skipped — the correct default for a sibling that has
+        # never declared a dependency, not a fail-open.
+        env:
+          CORE_MIN_TEMPLATE_VERSION: ${{ vars.CORE_MIN_TEMPLATE_VERSION }}
+          CORE_HEALTH_URL: ${{ vars.CORE_API_URL }}/api/v1/health
+        run: sh scripts/core-version-preflight.sh
+
   deploy-app:
     name: Deploy app
-    needs: [resolve-environment, deploy-infra, preflight-core-revision]
+    needs: [resolve-environment, deploy-infra, preflight-core-revision, preflight-core-version]
     runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
     environment: ${{ needs.resolve-environment.outputs.environment }}
     steps:
@@ -394,7 +437,14 @@ 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, preflight-core-revision, deploy-app]
+    needs:
+      [
+        resolve-environment,
+        deploy-infra,
+        preflight-core-revision,
+        preflight-core-version,
+        deploy-app,
+      ]
     if: always()
     runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
     steps:
@@ -403,9 +453,10 @@ jobs:
           ENABLED: ${{ vars.SIBLING_DEPLOY_ENABLED }}
           INFRA: ${{ needs.deploy-infra.result }}
           PREFLIGHT: ${{ needs.preflight-core-revision.result }}
+          VERSION_PREFLIGHT: ${{ needs.preflight-core-version.result }}
           APP: ${{ needs.deploy-app.result }}
         run: |
-          echo "SIBLING_DEPLOY_ENABLED='${ENABLED}'  deploy-infra=${INFRA}  preflight-core-revision=${PREFLIGHT}  deploy-app=${APP}"
+          echo "SIBLING_DEPLOY_ENABLED='${ENABLED}'  deploy-infra=${INFRA}  preflight-core-revision=${PREFLIGHT}  preflight-core-version=${VERSION_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."
@@ -418,14 +469,15 @@ jobs:
           fi
 
           # A real failure already makes the run red for the right reason, and
-          # `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
+          # `deploy-app` needs `deploy-infra`, `preflight-core-revision` AND
+          # `preflight-core-version` — so a failed infra job or either
+          # 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 or core-version-preflight.sh's own
+          # ::error:: naming the required and actual values, #1604/#1605)
+          # under a second, vaguer error. Defer to the real one.
+          case "${INFRA}:${PREFLIGHT}:${VERSION_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
@@ -434,7 +486,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}" "preflight-core-revision:${PREFLIGHT}" "deploy-app:${APP}"; do
+          for pair in "deploy-infra:${INFRA}" "preflight-core-revision:${PREFLIGHT}" "preflight-core-version:${VERSION_PREFLIGHT}" "deploy-app:${APP}"; do
             job="${pair%%:*}"
             result="${pair#*:}"
             if [ "${result}" = "skipped" ]; then
@@ -443,4 +495,4 @@ jobs:
             fi
           done
 
-          echo "Deploy jobs ran (infra=${INFRA}, preflight=${PREFLIGHT}, app=${APP})."
+          echo "Deploy jobs ran (infra=${INFRA}, preflight=${PREFLIGHT}, version-preflight=${VERSION_PREFLIGHT}, app=${APP})."

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env sh
+#
+# Core-version preflight (#1605).
+#
+# ## Why this exists
+#
+# A sibling can deploy against a core instance whose TEMPLATE version is
+# older than the sibling's code needs — a different failure from #1604's
+# route-ordering race. #1604 asks "has core shipped the specific route my
+# code depends on RIGHT NOW"; this asks "is the instance running at least
+# the core template capability my code was written against". The two are
+# deliberately separate scripts and separate deploy jobs, because they read
+# different signals and fail for different reasons — conflating them would
+# make either failure's message describe the wrong problem. This script does
+# NOT address, and is not a substitute for, #1604's deploy-ordering race.
+#
+# ## The signal
+#
+# `services/api/src/api/routers/health.py` returns `core_version()`, baked
+# in at package time by `scripts/resolve-core-version.sh`, and is publicly
+# reachable with no credential at `/api/v1/health` on every deployed
+# instance (`{"status":"ok","version":"0.287.12"}`). Nothing new is
+# published for this script — it reads a signal that already exists.
+#
+# ## Why NOT biffo.sibling.json's `template_version`
+#
+# The obvious-looking home for a declared floor is the sibling's own
+# `template_version` field. It is the wrong field: ADR-0007 states it is
+# stamped ONCE at scaffold time from `getLatestCoreVersion()`, is
+# "visibility only", and explicitly "nothing reads or compares the field
+# yet" — it is a backward PROVENANCE stamp that only ever falls further
+# behind, not a forward REQUIREMENT that rises as a sibling adopts newer
+# core capability. Measured live across all five real siblings at the time
+# #1605 was picked up: four had no `template_version` at all and the fifth
+# was ~80 minor versions behind the running core — reusing it as a floor
+# would be inert for four siblings and trivially satisfied by the fifth.
+# Mirroring #1604's already-proven shape instead: a per-environment GitHub
+# Actions repo variable the sibling sets by hand, the same way
+# CORE_MIN_ROUTE_REVISION is set — no JSON schema change, no ADR amendment,
+# no new document.
+#
+# ## Fail-closed (the #1363 class)
+#
+# A sibling that declares no minimum has nothing to check — that is a
+# legitimate "I depend on nothing beyond whatever core happens to be
+# running" state, and it passes with a notice. Once a minimum IS declared,
+# absence of a valid version in the health response — an unreachable
+# instance, a non-packaged deployment reporting the literal string
+# "unknown" (health.py's own documented fallback), a malformed body — 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.
+#
+# ## Version comparison
+#
+# Both versions are dotted non-negative-integer strings (e.g. "0.287.12"),
+# the shape every `core-v*` tag and every `biffo.core.json` `.version` takes
+# (see resolve-core-version.sh). Compared segment-by-segment, numerically,
+# left to right, with a missing trailing segment on either side treated as
+# 0 — so "0.287" and "0.287.0" compare equal, and "0.9" is correctly less
+# than "0.10". This is deliberately NOT full semver (no pre-release/build
+# metadata) because nothing in this estate's version strings ever carries
+# either.
+#
+# Exit codes:
+#   0 = no minimum declared (nothing to check), or the instance is at/past it.
+#   1 = the instance is behind the declared minimum, its health endpoint is
+#       unreachable, or its reported version could not be parsed. Every one
+#       of these is "not verified as safe" and none may be treated as a pass.
+#
+# ## Usage
+#
+#   CORE_MIN_TEMPLATE_VERSION=0.250.0 \
+#   CORE_HEALTH_URL=https://dev.example.com/api/v1/health \
+#     sh scripts/core-version-preflight.sh
+#
+# CORE_MIN_TEMPLATE_VERSION — the minimum core template version this
+#                              sibling's code needs. Set as a per-environment
+#                              repo variable (vars.CORE_MIN_TEMPLATE_VERSION),
+#                              the same way CORE_MIN_ROUTE_REVISION is set by
+#                              hand. Unset/empty means "no floor declared"
+#                              and the check is skipped.
+# CORE_HEALTH_URL           — where to fetch the instance's health document,
+#                              typically "${CORE_API_URL}/api/v1/health".
+#                              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-version-preflight.test.sh
+
+set -u
+
+CURL=${PREFLIGHT_CURL:-curl}
+
+MIN=${CORE_MIN_TEMPLATE_VERSION:-}
+if [ -z "$MIN" ]; then
+  # Loud on purpose, matching core-revision-preflight.sh's own reasoning: a
+  # green "Preflight — core template version" step must never look
+  # identical whether it actually checked something or checked nothing.
+  MSG="core-version-preflight: preflight did NOT run — CORE_MIN_TEMPLATE_VERSION is not set, so this sibling has declared no core-template-version dependency. This is 'nothing was checked', not 'core was checked and is ready'; set CORE_MIN_TEMPLATE_VERSION once this sibling depends on a specific core template version."
+  echo "::notice::${MSG}"
+  if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    echo "${MSG}" >> "$GITHUB_STEP_SUMMARY"
+  fi
+  exit 0
+fi
+
+is_version() {
+  printf '%s' "$1" | grep -Eq '^[0-9]+(\.[0-9]+)*$'
+}
+
+if ! is_version "$MIN"; then
+  echo "::error::core-version-preflight: CORE_MIN_TEMPLATE_VERSION='$MIN' is not a dotted non-negative-integer version (e.g. '0.250.0')." >&2
+  exit 1
+fi
+
+URL=${CORE_HEALTH_URL:-}
+if [ -z "$URL" ]; then
+  echo "::error::core-version-preflight: CORE_MIN_TEMPLATE_VERSION=$MIN is declared but CORE_HEALTH_URL is not set — cannot fetch the instance's health document to check it against. Refusing to proceed rather than assuming core is ready." >&2
+  exit 1
+fi
+
+BODY_FILE=/tmp/core-version-preflight-body.$$
+ERR_FILE=/tmp/core-version-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-version-preflight: no health response available at $URL (curl exit $RC, http ${HTTP_CODE:-none}${ERR:+, $ERR}). An absent or unreachable health endpoint is treated as NOT satisfied — this is expected on a down instance, a network issue, or a not-yet-deployed core — and is a DIFFERENT fact from 'core is behind version $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 (.version | type) == "string" then .version else empty end' "$BODY_FILE" 2>/dev/null)
+
+if [ -z "${ACTUAL:-}" ] || ! is_version "$ACTUAL"; then
+  # Deliberately covers health.py's own documented fallback: outside a
+  # packaged deployment it returns the literal string "unknown", which is
+  # not a version and must fail the same way a missing/malformed body does
+  # — never be silently treated as satisfied.
+  echo "::error::core-version-preflight: health document at $URL did not contain a valid dotted version in 'version' (got '${ACTUAL:-<empty>}'). Treating a malformed or unknown version the same as a missing one — refusing to deploy." >&2
+  exit 1
+fi
+
+version_ge() {
+  # Prints "1" if $1 >= $2, "0" otherwise — dotted numeric segments compared
+  # left to right, missing trailing segments on either side treated as 0.
+  awk -v a="$1" -v b="$2" '
+    BEGIN {
+      na = split(a, pa, ".")
+      nb = split(b, pb, ".")
+      n = (na > nb) ? na : nb
+      for (i = 1; i <= n; i++) {
+        x = (i <= na) ? pa[i] + 0 : 0
+        y = (i <= nb) ? pb[i] + 0 : 0
+        if (x > y) { print "1"; exit }
+        if (x < y) { print "0"; exit }
+      }
+      print "1"
+    }
+  '
+}
+
+if [ "$(version_ge "$ACTUAL" "$MIN")" = "1" ]; then
+  echo "core-version-preflight: OK — core is at version $ACTUAL, this sibling needs at least $MIN."
+  exit 0
+fi
+
+echo "::error::core-version-preflight: core is at version $ACTUAL, but this sibling needs at least $MIN. The instance has not upgraded to the core template version this sibling depends on yet — refusing to deploy ahead of it." >&2
+exit 1

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

@@ -0,0 +1,220 @@
+#!/usr/bin/env sh
+#
+# Proves core-version-preflight.sh (#1605) actually blocks a sibling from
+# deploying against an instance whose core template version is too old,
+# passes it once the instance has caught up, and fails CLOSED — never open
+# — when the health document is missing, unreachable, or reports the
+# "unknown" version health.py falls back to outside a packaged deployment.
+#
+# Stubs `curl` on PATH so this needs no network and no live deployment.
+#
+# Run: sh scripts/core-version-preflight.test.sh
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
+TARGET="$SCRIPT_DIR/core-version-preflight.sh"
+STUB_DIR=$(mktemp -d)
+OUT_FILE=/tmp/core-version-preflight-test-out.$$
+trap 'rm -rf "$STUB_DIR"; rm -f "$OUT_FILE"' EXIT
+
+FAILURES=0
+URL="https://dev.example.com/api/v1/health"
+
+# _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, matching
+# core-revision-preflight.test.sh's own reasoning: an assertion made inside
+# `out=$(...)` runs FAILURES++ in a subshell that never reaches the parent,
+# so a real regression could not fail the 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() {
+  version=$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 '{"status": "ok", "version": "$version"}' > "\$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_TEMPLATE_VERSION declared at all — this sibling depends on
+#    no specific core template version. 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".
+_write_stub_never_called
+_run -u CORE_MIN_TEMPLATE_VERSION -u CORE_HEALTH_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.
+SUMMARY_FILE=/tmp/core-version-preflight-test-summary.$$
+: > "$SUMMARY_FILE"
+_write_stub_never_called
+_run -u CORE_MIN_TEMPLATE_VERSION -u CORE_HEALTH_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 version core HAS reached (core is AHEAD) — passes.
+_write_stub_ok "0.287.12"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core ahead of required version (0.250.0 <= 0.287.12)" 0
+_assert_output_contains "core ahead — names actual" "version 0.287.12"
+
+# 2b. Exact match — core is AT the required version — passes.
+_write_stub_ok "0.250.0"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core exactly at required version" 0
+
+# 2c. Lexicographic trap: "0.9" must compare LESS than "0.10" numerically,
+#     not greater as a naive string compare would report.
+_write_stub_ok "0.9.0"
+_run CORE_MIN_TEMPLATE_VERSION=0.10.0 CORE_HEALTH_URL="$URL"
+_assert_exit "0.9.0 is numerically behind 0.10.0 (string compare would say ahead)" 1
+
+# 2d. Missing trailing segment treated as 0 — "0.287" == "0.287.0".
+_write_stub_ok "0.287"
+_run CORE_MIN_TEMPLATE_VERSION=0.287.0 CORE_HEALTH_URL="$URL"
+_assert_exit "0.287 satisfies a 0.287.0 floor (missing segment = 0)" 0
+
+# 3. Sibling requires a version core has NOT reached — fails, naming both
+#    the required and actual versions.
+_write_stub_ok "0.208.1"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "core behind required version" 1
+_assert_output_contains "core behind — names actual" "version 0.208.1"
+_assert_output_contains "core behind — names required" "at least 0.250.0"
+
+# 4. No health document available at all (transport failure) — fails
+#    CLOSED, and says the health endpoint was missing rather than that core
+#    is behind.
+_write_stub_unreachable
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "health endpoint unreachable" 1
+_assert_output_contains "health endpoint unreachable — says missing, not behind" "no health response available"
+
+# 5. Health endpoint 404s — fails CLOSED, same "missing" message as
+#    scenario 4, never "core is behind".
+_write_stub_404
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "health endpoint 404" 1
+_assert_output_contains "health endpoint 404 — says missing" "no health response available"
+
+# 6. Instance reports the literal "unknown" version — health.py's own
+#    documented fallback outside a packaged deployment. Must fail CLOSED
+#    exactly like a malformed/missing body, never be treated as satisfied.
+_write_stub_ok "unknown"
+_run CORE_MIN_TEMPLATE_VERSION=0.250.0 CORE_HEALTH_URL="$URL"
+_assert_exit "instance reports 'unknown' version" 1
+_assert_output_contains "'unknown' version — treated as malformed, not satisfied" "did not contain a valid dotted version"
+
+# 7. A minimum is declared but CORE_HEALTH_URL is not set — must fail
+#    without invoking curl (misconfiguration, not "core is ready").
+_write_stub_never_called
+_run -u CORE_HEALTH_URL -- CORE_MIN_TEMPLATE_VERSION=0.250.0
+_assert_exit "minimum declared but URL unset" 1
+
+echo
+if [ "$FAILURES" -eq 0 ]; then
+  echo "core-version-preflight.test.sh: all checks passed."
+  exit 0
+else
+  echo "core-version-preflight.test.sh: $FAILURES check(s) failed."
+  exit 1
+fi

package/package.json

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