@biffo/cli 0.212.1 → 0.214.0

package/_skeletons/plugin-template/scripts/pg-test-db.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env sh
+#
+# Give the Postgres-dependent test lane a database with a CURRENT schema, and
+# print its DSN.
+#
+# ## Why this exists
+#
+# `scripts/verify.sh` grew a `pg-test` check (#1089) because on 2026-08-02 nine
+# of thirteen locally-catchable failing CI steps across the estate were one
+# repo's real-Postgres lane -- a required check with no local counterpart at all.
+# But a gate can only run that lane against a database, and no repo documented
+# how to get one: no compose file, no script, no DSN written down. The container
+# that existed on the workstation had been created ad hoc in some earlier session
+# and held a scatter of scratch databases. That undocumented setup WAS the
+# fail-open, because a gate nobody can run is not a gate.
+#
+# ## Why freshness, not rebuild-every-time
+#
+# The expensive failure is not a slow rebuild, it is a STALE one. Measured on
+# tabsii-platform while writing this: a database built about an hour earlier,
+# before two PRs merged, produced **23 failures** in a module that had nothing to
+# do with the change in hand. Rebuilt from the same tree it passed 336/336, and
+# passed 336 again on an immediate re-run -- so the lane was genuinely
+# re-runnable and every one of those failures was the old schema.
+#
+# That is the worst shape a local gate can have. Twenty-three red tests that are
+# not your fault teach people the gate is unreliable, and an unreliable gate gets
+# bypassed -- which H4 pre-registered as the condition refuting the whole
+# local-gate programme. So the schema inputs are fingerprinted and a rebuild
+# happens only when they actually changed: reuse ~0.3s, rebuild ~4s.
+#
+# ## Why it is generic
+#
+# It adapts to the repo rather than being told about it, for the same reason
+# `verify.sh` does: forks drift, and a per-instance copy of this would drift from
+# the DDL layout it is meant to build. Everything instance-specific is DERIVED --
+# the schema directories from `db/imports/*/`, the engine image from whether the
+# DDL asks for PostGIS, and the did-it-build threshold from the number of
+# policies the DDL itself declares. Nothing here names a product.
+#
+# ## Usage
+#
+#   eval "$(sh scripts/pg-test-db.sh --export)"   # export BIFFO_TEST_PG_DSN
+#   sh scripts/pg-test-db.sh                      # print the DSN on stdout
+#   sh scripts/pg-test-db.sh --recreate           # force a rebuild
+#
+# Only the DSN reaches stdout, so it is safe to capture; progress goes to stderr.
+#
+# Overridable: BIFFO_PG_HOST, BIFFO_PG_PORT, BIFFO_PG_USER, BIFFO_PG_PASSWORD,
+# BIFFO_PG_DB, BIFFO_PG_CONTAINER, BIFFO_PG_IMAGE.
+
+set -eu
+
+HOST="${BIFFO_PG_HOST:-localhost}"
+PORT="${BIFFO_PG_PORT:-55432}"
+USER_="${BIFFO_PG_USER:-postgres}"
+PASS="${BIFFO_PG_PASSWORD:-postgres}"
+DB="${BIFFO_PG_DB:-biffo_test}"
+CONTAINER="${BIFFO_PG_CONTAINER:-biffo-pg-test}"
+
+RECREATE=0
+EXPORT=0
+for arg in "$@"; do
+  case "$arg" in
+    --recreate) RECREATE=1 ;;
+    --export) EXPORT=1 ;;
+    -h | --help)
+      sed -n '2,48p' "$0" | sed 's/^#\{1,2\} \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+say() { echo "pg-test-db: $*" >&2; }
+
+REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd)
+cd "$REPO_ROOT"
+
+# --- what this repo's schema is made of --------------------------------------
+#
+# `db/imports/<name>/*.sql` is the Biffo DDL-import convention that the API's own
+# `ddl_import.list_sql_files` reads at startup, so deriving from it means this
+# script and the running app agree by construction rather than by someone
+# remembering to update both.
+DDL_FILES=$(find db/imports -mindepth 2 -maxdepth 2 -name '*.sql' 2>/dev/null | LC_ALL=C sort || true)
+ALEMBIC_DIR=""
+for _d in services/api .; do
+  [ -f "$_d/alembic.ini" ] && ALEMBIC_DIR="$_d" && break
+done
+
+if [ -z "$DDL_FILES" ] && [ -z "$ALEMBIC_DIR" ]; then
+  say "no db/imports/*/ DDL and no alembic.ini - this repo has no schema to build"
+  exit 1
+fi
+
+# PostGIS or plain, decided by what the DDL asks for. A plain `postgres` image
+# fails on the first `CREATE EXTENSION postgis`, and picking the heavier image
+# unconditionally would slow every repo that does not need it.
+if [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs grep -liE 'EXTENSION[[:space:]]+(IF[[:space:]]+NOT[[:space:]]+EXISTS[[:space:]]+)?postgis' >/dev/null 2>&1; then
+  IMAGE="${BIFFO_PG_IMAGE:-postgis/postgis:16-3.4}"
+else
+  IMAGE="${BIFFO_PG_IMAGE:-postgres:16}"
+fi
+
+export PGPASSWORD="$PASS"
+psql_admin() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d postgres "$@"; }
+psql_db() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" "$@"; }
+
+# --- 1. a reachable server ---------------------------------------------------
+#
+# Started here rather than assumed, because "docker run one yourself" is exactly
+# the tribal knowledge this script replaces. An already-running server is reused.
+if ! psql_admin -c 'SELECT 1' >/dev/null 2>&1; then
+  if ! command -v docker >/dev/null 2>&1; then
+    say "no Postgres at $HOST:$PORT and docker is not installed."
+    say "Start one and re-run, or set BIFFO_PG_HOST / BIFFO_PG_PORT."
+    exit 1
+  fi
+  if docker ps -a --format '{{.Names}}' | grep -qx "$CONTAINER"; then
+    say "starting existing container $CONTAINER"
+    docker start "$CONTAINER" >/dev/null
+  else
+    say "creating container $CONTAINER ($IMAGE) on port $PORT"
+    docker run -d --name "$CONTAINER" \
+      -e POSTGRES_PASSWORD="$PASS" -p "$PORT:5432" "$IMAGE" >/dev/null
+  fi
+  # Polled, not slept: a cold image pull and a warm restart differ by an order of
+  # magnitude, and one fixed sleep is wrong for both.
+  _waited=0
+  until psql_admin -c 'SELECT 1' >/dev/null 2>&1; do
+    _waited=$((_waited + 1))
+    if [ "$_waited" -gt 90 ]; then
+      say "Postgres did not become ready in 90s"
+      exit 1
+    fi
+    sleep 1
+  done
+  say "Postgres ready after ${_waited}s"
+fi
+
+DSN="postgresql+asyncpg://$USER_:$PASS@$HOST:$PORT/$DB"
+emit() {
+  if [ "$EXPORT" -eq 1 ]; then
+    echo "export BIFFO_TEST_PG_DSN='$DSN'"
+  else
+    echo "$DSN"
+  fi
+}
+
+# --- 2. is the existing schema current? --------------------------------------
+#
+# By CONTENT, not mtime: a branch switch changes content and leaves mtime
+# anywhere. Stored inside the database, so it cannot outlive a drop or describe
+# some other database.
+fingerprint() {
+  {
+    [ -n "$ALEMBIC_DIR" ] && find "$ALEMBIC_DIR" -name '*.py' -path '*alembic*' -type f 2>/dev/null |
+      LC_ALL=C sort | xargs cat 2>/dev/null
+    [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs cat 2>/dev/null
+  } | sha256sum | cut -d' ' -f1
+}
+
+WANT=$(fingerprint)
+HAVE=""
+if [ "$RECREATE" -eq 0 ] &&
+  psql_admin -tAc "SELECT 1 FROM pg_database WHERE datname='$DB'" 2>/dev/null | grep -q 1; then
+  HAVE=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+    -c "SELECT value FROM biffo_pg_test_fingerprint LIMIT 1" 2>/dev/null || true)
+fi
+
+if [ -n "$HAVE" ] && [ "$HAVE" = "$WANT" ]; then
+  say "schema is current, reusing $DB"
+  emit
+  exit 0
+fi
+
+[ -n "$HAVE" ] && say "schema inputs changed - rebuilding rather than serving a stale schema"
+
+# --- 3. rebuild the way the app and CI do ------------------------------------
+say "rebuilding $DB"
+psql_admin -c "DROP DATABASE IF EXISTS $DB WITH (FORCE)" >/dev/null
+psql_admin -c "CREATE DATABASE $DB" >/dev/null
+
+if [ -n "$ALEMBIC_DIR" ]; then
+  BIFFO_DATABASE_URL="$DSN" uv run --directory "$ALEMBIC_DIR" alembic upgrade head >/dev/null
+  say "alembic upgrade head"
+fi
+
+if [ -n "$DDL_FILES" ]; then
+  # ONE psql session, sorted by filename, mirroring the API's own DDL import.
+  # Session state an early module sets -- typically `SET search_path` in the
+  # first file -- has to survive into later ones, so a per-file connection would
+  # silently change the meaning of every unqualified name after it. LC_ALL=C
+  # keeps the shell's sort byte-ordered to match Python's.
+  # shellcheck disable=SC2046
+  psql -q -v ON_ERROR_STOP=1 -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+    --single-transaction $(echo "$DDL_FILES" | sed 's/^/-f /' | tr '\n' ' ') >/dev/null
+  say "$(echo "$DDL_FILES" | wc -l | tr -d ' ') DDL modules applied"
+fi
+
+# --- 4. refuse to bless a half-built schema ----------------------------------
+#
+# The threshold is derived, not guessed: count the policies the DDL declares and
+# require the database to hold at least half. Recording a fingerprint against a
+# partial schema is worse than failing, because the NEXT run would trust it and
+# every failure after that would look like the developer's own change.
+if [ -n "$DDL_FILES" ]; then
+  _declared=$(echo "$DDL_FILES" | xargs grep -ciE '^[[:space:]]*CREATE[[:space:]]+POLICY' 2>/dev/null |
+    awk -F: '{s+=$NF} END {print s+0}')
+  if [ "${_declared:-0}" -gt 0 ]; then
+    _actual=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+      -c "SELECT count(*) FROM pg_policies" 2>/dev/null || echo 0)
+    if [ "${_actual:-0}" -lt $((_declared / 2)) ]; then
+      say "only ${_actual:-0} policies present against $_declared declared - the schema did not build."
+      say "Not recording a fingerprint; fix the DDL and re-run."
+      exit 1
+    fi
+    say "$_actual RLS policies ($_declared declared)"
+  fi
+fi
+
+psql_db \
+  -c "CREATE TABLE IF NOT EXISTS biffo_pg_test_fingerprint (value text primary key)" \
+  -c "TRUNCATE biffo_pg_test_fingerprint" \
+  -c "INSERT INTO biffo_pg_test_fingerprint (value) VALUES ('$WANT')" >/dev/null
+
+say "ready"
+emit

package/_skeletons/plugin-template/scripts/verify.sh

@@ -478,6 +478,23 @@ pg_test_run() {
 }
 
 _pg_modules=$(pg_test_modules)
+
+# Provision the database rather than requiring the operator to remember.
+#
+# A gate that only runs when you exported the right variable is a gate that runs
+# on the days you did not need it. `scripts/pg-test-db.sh` is idempotent and
+# cheap when the schema is unchanged (~0.3s; ~4s when it genuinely has to
+# rebuild), so calling it is better than warning about it. Failure is silent
+# BECAUSE the WARN below is the honest report of it -- no Docker, no server, no
+# schema all end in the same place: the lane did not run, and the gate says so.
+if [ -z "$PG_TEST_DSN" ] && [ -n "$_pg_modules" ] && [ -z "$LIST" ] && [ -f scripts/pg-test-db.sh ]; then
+  PG_TEST_DSN=$(sh scripts/pg-test-db.sh 2>/dev/null | tail -1) || PG_TEST_DSN=""
+  case "$PG_TEST_DSN" in
+    postgres*) ;;
+    *) PG_TEST_DSN="" ;;
+  esac
+fi
+
 # Order matters, and getting it wrong made these very tests machine-dependent:
 # with `uv not installed` checked FIRST, a runner without uv skipped quietly and
 # the gap warning never printed -- green on a workstation, red on CI, for a
@@ -550,6 +567,7 @@ fi
 if [ -f scripts/biffo.sh ]; then
   run_check plugin-tf sh scripts/biffo.sh check plugin-terraform
   run_check plugin-names sh scripts/biffo.sh check plugin-collisions
+  run_check adr-numbering sh scripts/biffo.sh check adr-numbering
 else
   skip biffo-guards "no scripts/biffo.sh in this repo"
 fi

package/_skeletons/sibling-template/scripts/pg-test-db.sh

@@ -0,0 +1,232 @@
+#!/usr/bin/env sh
+#
+# Give the Postgres-dependent test lane a database with a CURRENT schema, and
+# print its DSN.
+#
+# ## Why this exists
+#
+# `scripts/verify.sh` grew a `pg-test` check (#1089) because on 2026-08-02 nine
+# of thirteen locally-catchable failing CI steps across the estate were one
+# repo's real-Postgres lane -- a required check with no local counterpart at all.
+# But a gate can only run that lane against a database, and no repo documented
+# how to get one: no compose file, no script, no DSN written down. The container
+# that existed on the workstation had been created ad hoc in some earlier session
+# and held a scatter of scratch databases. That undocumented setup WAS the
+# fail-open, because a gate nobody can run is not a gate.
+#
+# ## Why freshness, not rebuild-every-time
+#
+# The expensive failure is not a slow rebuild, it is a STALE one. Measured on
+# tabsii-platform while writing this: a database built about an hour earlier,
+# before two PRs merged, produced **23 failures** in a module that had nothing to
+# do with the change in hand. Rebuilt from the same tree it passed 336/336, and
+# passed 336 again on an immediate re-run -- so the lane was genuinely
+# re-runnable and every one of those failures was the old schema.
+#
+# That is the worst shape a local gate can have. Twenty-three red tests that are
+# not your fault teach people the gate is unreliable, and an unreliable gate gets
+# bypassed -- which H4 pre-registered as the condition refuting the whole
+# local-gate programme. So the schema inputs are fingerprinted and a rebuild
+# happens only when they actually changed: reuse ~0.3s, rebuild ~4s.
+#
+# ## Why it is generic
+#
+# It adapts to the repo rather than being told about it, for the same reason
+# `verify.sh` does: forks drift, and a per-instance copy of this would drift from
+# the DDL layout it is meant to build. Everything instance-specific is DERIVED --
+# the schema directories from `db/imports/*/`, the engine image from whether the
+# DDL asks for PostGIS, and the did-it-build threshold from the number of
+# policies the DDL itself declares. Nothing here names a product.
+#
+# ## Usage
+#
+#   eval "$(sh scripts/pg-test-db.sh --export)"   # export BIFFO_TEST_PG_DSN
+#   sh scripts/pg-test-db.sh                      # print the DSN on stdout
+#   sh scripts/pg-test-db.sh --recreate           # force a rebuild
+#
+# Only the DSN reaches stdout, so it is safe to capture; progress goes to stderr.
+#
+# Overridable: BIFFO_PG_HOST, BIFFO_PG_PORT, BIFFO_PG_USER, BIFFO_PG_PASSWORD,
+# BIFFO_PG_DB, BIFFO_PG_CONTAINER, BIFFO_PG_IMAGE.
+
+set -eu
+
+HOST="${BIFFO_PG_HOST:-localhost}"
+PORT="${BIFFO_PG_PORT:-55432}"
+USER_="${BIFFO_PG_USER:-postgres}"
+PASS="${BIFFO_PG_PASSWORD:-postgres}"
+DB="${BIFFO_PG_DB:-biffo_test}"
+CONTAINER="${BIFFO_PG_CONTAINER:-biffo-pg-test}"
+
+RECREATE=0
+EXPORT=0
+for arg in "$@"; do
+  case "$arg" in
+    --recreate) RECREATE=1 ;;
+    --export) EXPORT=1 ;;
+    -h | --help)
+      sed -n '2,48p' "$0" | sed 's/^#\{1,2\} \{0,1\}//'
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $arg" >&2
+      exit 2
+      ;;
+  esac
+done
+
+say() { echo "pg-test-db: $*" >&2; }
+
+REPO_ROOT=$(cd "$(dirname "$0")/.." && pwd)
+cd "$REPO_ROOT"
+
+# --- what this repo's schema is made of --------------------------------------
+#
+# `db/imports/<name>/*.sql` is the Biffo DDL-import convention that the API's own
+# `ddl_import.list_sql_files` reads at startup, so deriving from it means this
+# script and the running app agree by construction rather than by someone
+# remembering to update both.
+DDL_FILES=$(find db/imports -mindepth 2 -maxdepth 2 -name '*.sql' 2>/dev/null | LC_ALL=C sort || true)
+ALEMBIC_DIR=""
+for _d in services/api .; do
+  [ -f "$_d/alembic.ini" ] && ALEMBIC_DIR="$_d" && break
+done
+
+if [ -z "$DDL_FILES" ] && [ -z "$ALEMBIC_DIR" ]; then
+  say "no db/imports/*/ DDL and no alembic.ini - this repo has no schema to build"
+  exit 1
+fi
+
+# PostGIS or plain, decided by what the DDL asks for. A plain `postgres` image
+# fails on the first `CREATE EXTENSION postgis`, and picking the heavier image
+# unconditionally would slow every repo that does not need it.
+if [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs grep -liE 'EXTENSION[[:space:]]+(IF[[:space:]]+NOT[[:space:]]+EXISTS[[:space:]]+)?postgis' >/dev/null 2>&1; then
+  IMAGE="${BIFFO_PG_IMAGE:-postgis/postgis:16-3.4}"
+else
+  IMAGE="${BIFFO_PG_IMAGE:-postgres:16}"
+fi
+
+export PGPASSWORD="$PASS"
+psql_admin() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d postgres "$@"; }
+psql_db() { psql -q -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" "$@"; }
+
+# --- 1. a reachable server ---------------------------------------------------
+#
+# Started here rather than assumed, because "docker run one yourself" is exactly
+# the tribal knowledge this script replaces. An already-running server is reused.
+if ! psql_admin -c 'SELECT 1' >/dev/null 2>&1; then
+  if ! command -v docker >/dev/null 2>&1; then
+    say "no Postgres at $HOST:$PORT and docker is not installed."
+    say "Start one and re-run, or set BIFFO_PG_HOST / BIFFO_PG_PORT."
+    exit 1
+  fi
+  if docker ps -a --format '{{.Names}}' | grep -qx "$CONTAINER"; then
+    say "starting existing container $CONTAINER"
+    docker start "$CONTAINER" >/dev/null
+  else
+    say "creating container $CONTAINER ($IMAGE) on port $PORT"
+    docker run -d --name "$CONTAINER" \
+      -e POSTGRES_PASSWORD="$PASS" -p "$PORT:5432" "$IMAGE" >/dev/null
+  fi
+  # Polled, not slept: a cold image pull and a warm restart differ by an order of
+  # magnitude, and one fixed sleep is wrong for both.
+  _waited=0
+  until psql_admin -c 'SELECT 1' >/dev/null 2>&1; do
+    _waited=$((_waited + 1))
+    if [ "$_waited" -gt 90 ]; then
+      say "Postgres did not become ready in 90s"
+      exit 1
+    fi
+    sleep 1
+  done
+  say "Postgres ready after ${_waited}s"
+fi
+
+DSN="postgresql+asyncpg://$USER_:$PASS@$HOST:$PORT/$DB"
+emit() {
+  if [ "$EXPORT" -eq 1 ]; then
+    echo "export BIFFO_TEST_PG_DSN='$DSN'"
+  else
+    echo "$DSN"
+  fi
+}
+
+# --- 2. is the existing schema current? --------------------------------------
+#
+# By CONTENT, not mtime: a branch switch changes content and leaves mtime
+# anywhere. Stored inside the database, so it cannot outlive a drop or describe
+# some other database.
+fingerprint() {
+  {
+    [ -n "$ALEMBIC_DIR" ] && find "$ALEMBIC_DIR" -name '*.py' -path '*alembic*' -type f 2>/dev/null |
+      LC_ALL=C sort | xargs cat 2>/dev/null
+    [ -n "$DDL_FILES" ] && echo "$DDL_FILES" | xargs cat 2>/dev/null
+  } | sha256sum | cut -d' ' -f1
+}
+
+WANT=$(fingerprint)
+HAVE=""
+if [ "$RECREATE" -eq 0 ] &&
+  psql_admin -tAc "SELECT 1 FROM pg_database WHERE datname='$DB'" 2>/dev/null | grep -q 1; then
+  HAVE=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+    -c "SELECT value FROM biffo_pg_test_fingerprint LIMIT 1" 2>/dev/null || true)
+fi
+
+if [ -n "$HAVE" ] && [ "$HAVE" = "$WANT" ]; then
+  say "schema is current, reusing $DB"
+  emit
+  exit 0
+fi
+
+[ -n "$HAVE" ] && say "schema inputs changed - rebuilding rather than serving a stale schema"
+
+# --- 3. rebuild the way the app and CI do ------------------------------------
+say "rebuilding $DB"
+psql_admin -c "DROP DATABASE IF EXISTS $DB WITH (FORCE)" >/dev/null
+psql_admin -c "CREATE DATABASE $DB" >/dev/null
+
+if [ -n "$ALEMBIC_DIR" ]; then
+  BIFFO_DATABASE_URL="$DSN" uv run --directory "$ALEMBIC_DIR" alembic upgrade head >/dev/null
+  say "alembic upgrade head"
+fi
+
+if [ -n "$DDL_FILES" ]; then
+  # ONE psql session, sorted by filename, mirroring the API's own DDL import.
+  # Session state an early module sets -- typically `SET search_path` in the
+  # first file -- has to survive into later ones, so a per-file connection would
+  # silently change the meaning of every unqualified name after it. LC_ALL=C
+  # keeps the shell's sort byte-ordered to match Python's.
+  # shellcheck disable=SC2046
+  psql -q -v ON_ERROR_STOP=1 -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+    --single-transaction $(echo "$DDL_FILES" | sed 's/^/-f /' | tr '\n' ' ') >/dev/null
+  say "$(echo "$DDL_FILES" | wc -l | tr -d ' ') DDL modules applied"
+fi
+
+# --- 4. refuse to bless a half-built schema ----------------------------------
+#
+# The threshold is derived, not guessed: count the policies the DDL declares and
+# require the database to hold at least half. Recording a fingerprint against a
+# partial schema is worse than failing, because the NEXT run would trust it and
+# every failure after that would look like the developer's own change.
+if [ -n "$DDL_FILES" ]; then
+  _declared=$(echo "$DDL_FILES" | xargs grep -ciE '^[[:space:]]*CREATE[[:space:]]+POLICY' 2>/dev/null |
+    awk -F: '{s+=$NF} END {print s+0}')
+  if [ "${_declared:-0}" -gt 0 ]; then
+    _actual=$(psql -tAq -h "$HOST" -p "$PORT" -U "$USER_" -d "$DB" \
+      -c "SELECT count(*) FROM pg_policies" 2>/dev/null || echo 0)
+    if [ "${_actual:-0}" -lt $((_declared / 2)) ]; then
+      say "only ${_actual:-0} policies present against $_declared declared - the schema did not build."
+      say "Not recording a fingerprint; fix the DDL and re-run."
+      exit 1
+    fi
+    say "$_actual RLS policies ($_declared declared)"
+  fi
+fi
+
+psql_db \
+  -c "CREATE TABLE IF NOT EXISTS biffo_pg_test_fingerprint (value text primary key)" \
+  -c "TRUNCATE biffo_pg_test_fingerprint" \
+  -c "INSERT INTO biffo_pg_test_fingerprint (value) VALUES ('$WANT')" >/dev/null
+
+say "ready"
+emit

package/_skeletons/sibling-template/scripts/verify.sh

@@ -478,6 +478,23 @@ pg_test_run() {
 }
 
 _pg_modules=$(pg_test_modules)
+
+# Provision the database rather than requiring the operator to remember.
+#
+# A gate that only runs when you exported the right variable is a gate that runs
+# on the days you did not need it. `scripts/pg-test-db.sh` is idempotent and
+# cheap when the schema is unchanged (~0.3s; ~4s when it genuinely has to
+# rebuild), so calling it is better than warning about it. Failure is silent
+# BECAUSE the WARN below is the honest report of it -- no Docker, no server, no
+# schema all end in the same place: the lane did not run, and the gate says so.
+if [ -z "$PG_TEST_DSN" ] && [ -n "$_pg_modules" ] && [ -z "$LIST" ] && [ -f scripts/pg-test-db.sh ]; then
+  PG_TEST_DSN=$(sh scripts/pg-test-db.sh 2>/dev/null | tail -1) || PG_TEST_DSN=""
+  case "$PG_TEST_DSN" in
+    postgres*) ;;
+    *) PG_TEST_DSN="" ;;
+  esac
+fi
+
 # Order matters, and getting it wrong made these very tests machine-dependent:
 # with `uv not installed` checked FIRST, a runner without uv skipped quietly and
 # the gap warning never printed -- green on a workstation, red on CI, for a
@@ -550,6 +567,7 @@ fi
 if [ -f scripts/biffo.sh ]; then
   run_check plugin-tf sh scripts/biffo.sh check plugin-terraform
   run_check plugin-names sh scripts/biffo.sh check plugin-collisions
+  run_check adr-numbering sh scripts/biffo.sh check adr-numbering
 else
   skip biffo-guards "no scripts/biffo.sh in this repo"
 fi

package/dist/index.js

@@ -9124,9 +9124,61 @@ siblingCommand.addCommand(siblingCheckIdentityCommand);
 // src/commands/check.ts
 import { Command as Command23 } from "commander";
 
+// src/scripts/check-adr-numbering.ts
+import { existsSync as existsSync32 } from "fs";
+import { join as join31 } from "path";
+import { execa as execa5 } from "execa";
+
+// src/lib/adr-numbering-guard.ts
+import { existsSync as existsSync31, readdirSync as readdirSync13 } from "fs";
+var ADR_FILENAME = /^(\d{4})-.+\.md$/;
+function adrNumbersIn(adrDir) {
+  const claims = /* @__PURE__ */ new Map();
+  if (!existsSync31(adrDir)) return claims;
+  for (const entry of readdirSync13(adrDir).sort()) {
+    const match = ADR_FILENAME.exec(entry);
+    if (!match) continue;
+    const number = match[1];
+    claims.set(number, [...claims.get(number) ?? [], entry]);
+  }
+  return claims;
+}
+function findAdrNumberCollisions(adrDir) {
+  const collisions = [];
+  for (const [number, files] of [...adrNumbersIn(adrDir).entries()].sort()) {
+    if (files.length > 1) collisions.push({ number, files: [...files].sort() });
+  }
+  return collisions;
+}
+function formatAdrNumberCollisions(collisions) {
+  return collisions.map(
+    (c) => `  ADR-${c.number} is claimed by: ${c.files.join(", ")}
+    Pick a different number for the newer one \u2014 citing "ADR-${c.number}" is
+    ambiguous while both exist.`
+  ).join("\n");
+}
+
+// src/scripts/check-adr-numbering.ts
+async function runAdrNumberingCheck() {
+  const root = (await execa5("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const adrDir = join31(root, "docs", "ADR");
+  if (!existsSync32(adrDir)) {
+    console.log("\u2713 ADR numbering guard: no docs/ADR/ directory \u2014 nothing to compare");
+    return;
+  }
+  const collisions = findAdrNumberCollisions(adrDir);
+  if (collisions.length > 0) {
+    console.error("\u2717 ADR numbering guard: two ADRs in docs/ADR/ share a number\n");
+    console.error(formatAdrNumberCollisions(collisions));
+    console.error("\nSee tabsii-platform#449 for how this class of collision happens.");
+    process.exit(1);
+  }
+  console.log("\u2713 ADR numbering guard: OK");
+}
+
 // src/scripts/check-branch-protection.ts
 import { Octokit as Octokit2 } from "@octokit/rest";
-import { execa as execa5 } from "execa";
+import { execa as execa6 } from "execa";
 
 // src/lib/branch-protection-apply.ts
 var CONTEXT_CONSISTENCY_THRESHOLD = 2 / 3;
@@ -9253,7 +9305,7 @@ async function resolveRepo(explicit) {
     }
     return { owner, repo };
   }
-  const { stdout } = await execa5("git", ["remote", "get-url", "origin"]);
+  const { stdout } = await execa6("git", ["remote", "get-url", "origin"]);
   const m = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/.exec(stdout.trim());
   if (!m?.[1] || !m[2]) {
     console.error(
@@ -9385,7 +9437,7 @@ async function runBranchProtectionCheck(explicitRepo, options = {}) {
 }
 
 // src/scripts/check-core-ownership.ts
-import { execa as execa6 } from "execa";
+import { execa as execa7 } from "execa";
 var BOLD = "\x1B[1m";
 var DIM = "\x1B[2m";
 var RED = "\x1B[31m";
@@ -9396,7 +9448,7 @@ async function runOwnershipCheck(argv) {
   const stagedFlag = args.indexOf("--staged");
   const staged = stagedFlag !== -1;
   const messageFile = staged ? args[stagedFlag + 1] : void 0;
-  const root = (await execa6("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const root = (await execa7("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   if (!isInstanceRepo(root)) {
     console.log("\u2713 core ownership guard: skipped \u2014 this is the template, which owns these paths.");
     return;
@@ -9405,11 +9457,11 @@ async function runOwnershipCheck(argv) {
   let deletedFiles = [];
   let commitMessage = "";
   if (staged) {
-    const { stdout } = await execa6("git", ["diff", "--cached", "--name-status"], { cwd: root });
+    const { stdout } = await execa7("git", ["diff", "--cached", "--name-status"], { cwd: root });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
     if (messageFile) {
-      const { readFileSync: readFileSync26, existsSync: existsSync35 } = await import("fs");
-      if (existsSync35(messageFile)) commitMessage = readFileSync26(messageFile, "utf8");
+      const { readFileSync: readFileSync26, existsSync: existsSync37 } = await import("fs");
+      if (existsSync37(messageFile)) commitMessage = readFileSync26(messageFile, "utf8");
     }
   } else {
     const base = process.env["GITHUB_BASE_REF"] ?? args[0];
@@ -9417,18 +9469,18 @@ async function runOwnershipCheck(argv) {
       console.error("No base ref: set GITHUB_BASE_REF or pass a base branch as the first argument.");
       process.exit(2);
     }
-    await execa6("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
-    const { stdout } = await execa6("git", ["diff", "--name-status", `origin/${base}...HEAD`], {
+    await execa7("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
+    const { stdout } = await execa7("git", ["diff", "--name-status", `origin/${base}...HEAD`], {
       cwd: root
     });
     ({ changed: changedFiles, deleted: deletedFiles } = parseNameStatus(stdout));
-    const { stdout: log2 } = await execa6("git", ["log", "--format=%B", `origin/${base}..HEAD`], {
+    const { stdout: log2 } = await execa7("git", ["log", "--format=%B", `origin/${base}..HEAD`], {
       cwd: root,
       reject: false
     });
     commitMessage = log2;
   }
-  const { stdout: gitBranch } = await execa6("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+  const { stdout: gitBranch } = await execa7("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
     cwd: root,
     reject: false
   });
@@ -9510,34 +9562,34 @@ ${BOLD}If the divergence is deliberate${OFF}
 }
 
 // src/scripts/check-plugin-collisions.ts
-import { existsSync as existsSync32 } from "fs";
-import { join as join32 } from "path";
-import { execa as execa7 } from "execa";
+import { existsSync as existsSync34 } from "fs";
+import { join as join33 } from "path";
+import { execa as execa8 } from "execa";
 
 // src/lib/plugin-collision-guard.ts
-import { existsSync as existsSync31, readdirSync as readdirSync13, statSync as statSync7 } from "fs";
-import { join as join31 } from "path";
+import { existsSync as existsSync33, readdirSync as readdirSync14, statSync as statSync7 } from "fs";
+import { join as join32 } from "path";
 var PYTEST_SPECIAL = /* @__PURE__ */ new Set(["conftest.py"]);
 var IGNORED_DIRS = /* @__PURE__ */ new Set([".venv", "node_modules", "__pycache__", ".git", "dist", "build"]);
 function subdirectories(dir) {
-  if (!existsSync31(dir)) return [];
-  return readdirSync13(dir).filter((entry) => {
+  if (!existsSync33(dir)) return [];
+  return readdirSync14(dir).filter((entry) => {
     if (IGNORED_DIRS.has(entry) || entry.startsWith(".")) return false;
     try {
-      return statSync7(join31(dir, entry)).isDirectory();
+      return statSync7(join32(dir, entry)).isDirectory();
     } catch {
       return false;
     }
   });
 }
 function regularPackagesOf(pluginDir2) {
-  return subdirectories(pluginDir2).filter((name) => existsSync31(join31(pluginDir2, name, "__init__.py"))).sort();
+  return subdirectories(pluginDir2).filter((name) => existsSync33(join32(pluginDir2, name, "__init__.py"))).sort();
 }
 function bareTestModulesOf(pluginDir2) {
-  const testsDir = join31(pluginDir2, "tests");
-  if (!existsSync31(testsDir)) return [];
-  if (existsSync31(join31(testsDir, "__init__.py"))) return [];
-  return readdirSync13(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
+  const testsDir = join32(pluginDir2, "tests");
+  if (!existsSync33(testsDir)) return [];
+  if (existsSync33(join32(testsDir, "__init__.py"))) return [];
+  return readdirSync14(testsDir).filter((f) => f.endsWith(".py") && !PYTEST_SPECIAL.has(f)).sort();
 }
 function findCollisions(servicesDir, pluginDirs) {
   const plugins = (pluginDirs ?? subdirectories(servicesDir)).filter((name) => !name.startsWith("_")).filter((name) => name !== "api").sort();
@@ -9545,7 +9597,7 @@ function findCollisions(servicesDir, pluginDirs) {
   const gather = (kind, namesOf) => {
     const claims = /* @__PURE__ */ new Map();
     for (const plugin of plugins) {
-      for (const name of namesOf(join31(servicesDir, plugin))) {
+      for (const name of namesOf(join32(servicesDir, plugin))) {
         claims.set(name, [...claims.get(name) ?? [], plugin]);
       }
     }
@@ -9582,9 +9634,9 @@ function formatCollisions(collisions) {
 
 // src/scripts/check-plugin-collisions.ts
 async function runPluginCollisionCheck() {
-  const root = (await execa7("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  const servicesDir = join32(root, "services");
-  if (!existsSync32(servicesDir)) {
+  const root = (await execa8("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const servicesDir = join33(root, "services");
+  if (!existsSync34(servicesDir)) {
     console.log("\u2713 plugin collision guard: no services/ directory \u2014 nothing to compare");
     return;
   }
@@ -9601,11 +9653,11 @@ async function runPluginCollisionCheck() {
 }
 
 // src/scripts/check-plugin-terraform.ts
-import { execa as execa8 } from "execa";
+import { execa as execa9 } from "execa";
 
 // src/lib/plugin-terraform-guard.ts
-import { existsSync as existsSync33, readFileSync as readFileSync24, readdirSync as readdirSync14 } from "fs";
-import { dirname as dirname9, join as join33, relative as relative6, sep as sep3 } from "path";
+import { existsSync as existsSync35, readFileSync as readFileSync24, readdirSync as readdirSync15 } from "fs";
+import { dirname as dirname9, join as join34, relative as relative6, sep as sep3 } from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".worktrees", "dist", ".venv", "__pycache__"]);
 var PLUGIN_MANIFEST_FILE2 = "biffo.plugin.json";
 function findPluginManifests(root) {
@@ -9613,16 +9665,16 @@ function findPluginManifests(root) {
   const walk = (dir) => {
     let entries;
     try {
-      entries = readdirSync14(dir, { withFileTypes: true });
+      entries = readdirSync15(dir, { withFileTypes: true });
     } catch {
       return;
     }
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
-        walk(join33(dir, entry.name));
+        walk(join34(dir, entry.name));
       } else if (entry.isFile() && entry.name === PLUGIN_MANIFEST_FILE2) {
-        found.push(relative6(root, join33(dir, entry.name)).split(sep3).join("/"));
+        found.push(relative6(root, join34(dir, entry.name)).split(sep3).join("/"));
       }
     }
   };
@@ -9647,14 +9699,14 @@ function readSubscriptions(absManifestPath) {
 }
 function checkPluginTerraform(root) {
   const violations = [];
-  const coreManifest = existsSync33(join33(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
+  const coreManifest = existsSync35(join34(root, CORE_MANIFEST_FILE)) ? readCoreManifest(root) : null;
   for (const manifest of findPluginManifests(root)) {
     if (coreManifest && !isTemplateOwned(manifest, coreManifest)) continue;
-    const absManifest = join33(root, manifest);
+    const absManifest = join34(root, manifest);
     const subscriptions = readSubscriptions(absManifest);
     if (subscriptions === null) continue;
     const pluginDir2 = dirname9(absManifest);
-    if (existsSync33(join33(pluginDir2, "terraform"))) continue;
+    if (existsSync35(join34(pluginDir2, "terraform"))) continue;
     const relPluginDir = relative6(root, pluginDir2).split(sep3).join("/");
     violations.push({
       manifest,
@@ -9674,7 +9726,7 @@ function formatViolations(violations) {
 
 // src/scripts/check-plugin-terraform.ts
 async function runPluginTerraformCheck() {
-  const root = (await execa8("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  const root = (await execa9("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
   const violations = checkPluginTerraform(root);
   if (violations.length > 0) {
     console.error("\u2717 plugin Terraform guard: event subscriptions with no infrastructure\n");
@@ -9685,7 +9737,7 @@ async function runPluginTerraformCheck() {
 }
 
 // src/scripts/check-release-subject.ts
-import { execa as execa9 } from "execa";
+import { execa as execa10 } from "execa";
 
 // src/lib/release-version.ts
 var MINOR_TYPES = /* @__PURE__ */ new Set(["feat"]);
@@ -9723,13 +9775,13 @@ async function runReleaseSubjectCheck(argv) {
     console.error("No base ref: set GITHUB_BASE_REF or pass a base branch as the first argument.");
     process.exit(2);
   }
-  const root = (await execa9("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
-  await execa9("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
-  const { stdout } = await execa9("git", ["diff", "--name-only", `origin/${base}...HEAD`], {
+  const root = (await execa10("git", ["rev-parse", "--show-toplevel"])).stdout.trim();
+  await execa10("git", ["fetch", "--quiet", "origin", base], { cwd: root, reject: false });
+  const { stdout } = await execa10("git", ["diff", "--name-only", `origin/${base}...HEAD`], {
     cwd: root
   });
   const changedFiles = stdout.split("\n").map((s) => s.trim()).filter(Boolean);
-  const subject = process.env["PR_TITLE"]?.trim() || (await execa9("git", ["log", "-1", "--format=%s"], { cwd: root })).stdout.trim();
+  const subject = process.env["PR_TITLE"]?.trim() || (await execa10("git", ["log", "-1", "--format=%s"], { cwd: root })).stdout.trim();
   const manifest = readCoreManifest(root);
   const { unparseable, bump, templateOwnedChanges, skippedAsInstance } = checkReleaseSubject(
     changedFiles,
@@ -9788,6 +9840,11 @@ checkCommand.command("plugin-collisions").description("Refuse two vendored plugi
 checkCommand.command("plugin-terraform").description("Verify every template-owned plugin declaring infra ships a Terraform module").action(async () => {
   await runPluginTerraformCheck();
 });
+checkCommand.command("adr-numbering").description(
+  "Refuse two ADRs in this repo's own docs/ADR/ claiming the same number (tabsii-platform#449)"
+).action(async () => {
+  await runAdrNumberingCheck();
+});
 checkCommand.command("branch-protection").description(
   "Verify dev/staging/main are actually protected \u2014 scaffolding skips this on a 403 (#715)"
 ).option("--repo <owner/name>", "Repo to audit; defaults to this checkout's origin remote").option(
@@ -9802,8 +9859,8 @@ function rawArgsAfter(subcommand) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync34, readFileSync as readFileSync25 } from "fs";
-import { join as join34, resolve as resolve18 } from "path";
+import { existsSync as existsSync36, readFileSync as readFileSync25 } from "fs";
+import { join as join35, resolve as resolve18 } from "path";
 import chalk21 from "chalk";
 import { Command as Command24 } from "commander";
 
@@ -9978,8 +10035,8 @@ async function runDoctor(options, deps = { git: new GitAdapter() }) {
   return runDoctorChecks(facts);
 }
 function readLocalCoreVersion(cwd) {
-  const path = join34(cwd, INSTANCE_CORE_FILE);
-  if (!existsSync34(path)) return null;
+  const path = join35(cwd, INSTANCE_CORE_FILE);
+  if (!existsSync36(path)) return null;
   try {
     return parseCoreRecord(readFileSync25(path, "utf8"));
   } catch {
@@ -9996,8 +10053,8 @@ function parseCoreRecord(contents) {
   }
 }
 function readFossil(cwd) {
-  const path = join34(cwd, CORE_VERSION_FILE);
-  if (!existsSync34(path)) return null;
+  const path = join35(cwd, CORE_VERSION_FILE);
+  if (!existsSync36(path)) return null;
   try {
     const value = readFileSync25(path, "utf8").trim();
     return value === "" ? null : value;

package/package.json

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