@biffo/cli 0.243.2 → 0.244.1

package/_skeletons/plugin-template/.githooks/pre-push

@@ -53,6 +53,47 @@ cd "$root" || exit 0
 # cannot run, that is a reason to stop, not to wave the push through.
 sh scripts/biffo.sh rewrite-scope-check || exit 1
 
+# --- Claim guard (#1231 instance 2) -------------------------------------------
+#
+# `scripts/claim.sh` (packaged inside `@biffo/cli`, run through the bridge
+# above) has asked the estate's four-signal question about "is this issue
+# taken?" since #1209 -- but nothing ever RAN it. It shipped advisory-only, so
+# the fix for the collisions it exists to catch was itself subject to the same
+# failure: a collision happens precisely when someone does not think to check.
+#
+# `--guard <branch>` is the enforced form. It derives the issue number from the
+# branch name (`<type>/<number>-slug>`) and, when the branch names one, checks
+# for another remote branch or another OPEN PR naming the same issue -- NEVER
+# the `in-progress` label (three of four real collisions were "work exists,
+# label does not") and NEVER identity (a claim on #1109 was recorded as
+# `github-actions[bot]` because of a repo-local `user.email` override). It
+# excludes the branch being pushed and any PR whose head IS that branch, so
+# pushing your own branch a second time cannot block you on your own work.
+#
+# A branch that names no issue returns before any network call -- most
+# branches are fine, and noise kills a gate. Measured on a branch that DOES
+# name one: the added latency is the cost of two `gh` lookups, similar in
+# order of magnitude to `rewrite-scope-check` above.
+branch=$(git symbolic-ref --quiet --short HEAD) || branch=""
+
+if [ -n "$branch" ]; then
+  sh scripts/biffo.sh claim --guard "$branch"
+  claim_status=$?
+
+  if [ "$claim_status" -eq 1 ]; then
+    exit 1
+  fi
+
+  # $claim_status -eq 2 is "cannot tell" -- no network, gh unauthenticated, an
+  # API error -- and claim.sh has already printed a warning. Deliberately NOT
+  # blocked here: unlike every other gate in this file, this is a COORDINATION
+  # gate, not a correctness one. A false block costs the ability to push at
+  # all; a miss costs a recoverable collision caught early (every collision in
+  # #1209's own incident was caught before duplicate work merged). Set
+  # BIFFO_CLAIM_STRICT=1 to make claim.sh itself collapse cannot-tell into
+  # exit 1 instead, if you would rather block than guess.
+fi
+
 # Through the version-pinned CLI since #1109, so a repo cannot run a gate two
 # versions old -- eight of them did, and tabsii-crm checked ONE thing in eight
 # on a 700-line change and printed `verify passed` (#855). There is one copy of

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

@@ -2,9 +2,15 @@ name: CI
 
 # Scaled down from biffo-template's own root .github/workflows/ci.yml for a
 # single Python package: a plugin repo (per ADR-0003) extends the SDK and
-# has no JS/TS and no Terraform of its own — Terraform, if a plugin ships
-# any, is provisioned by the *consuming* project's infra, not this repo's
-# CI (see README's "What this repo does not build" section).
+# has no JS/TS of its own.
+#
+# It DOES have Terraform. This comment used to claim the opposite — "no
+# Terraform of its own; Terraform, if a plugin ships any, is provisioned by the
+# consuming project's infra, not this repo's CI" — while the skeleton beside it
+# shipped a whole `terraform/` module, and that untrue sentence is exactly why
+# nothing checked it (#1244). What the consuming project provisions is the
+# module's *instantiation*; the module's own source lives here, is edited here,
+# and is only ever checked here. See the `terraform` job below.
 
 on:
   push:
@@ -108,6 +114,48 @@ jobs:
         run: |
           uv run python -m jsonschema -i biffo.plugin.json registry-schema.json
 
+  terraform:
+    name: Terraform (fmt)
+    runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+    timeout-minutes: 20
+    # This repo's `terraform/` module is checked by nothing else (#1244). The
+    # skeleton shipped the module and no terraform step at all, so every plugin
+    # repo was scaffolded with Terraform that nothing looked at — confirmed live
+    # in biffo-plugin-idea-scout: three .tf files, zero terraform references
+    # across three workflows.
+    #
+    # `scripts/verify.sh` cannot substitute for this job, and deliberately does
+    # not try: its terraform check is guarded by `ci_has "terraform fmt"` so a
+    # template-shipped gate never asserts over more than the repo's own CI does
+    # (the #325 trap). A repo whose CI checks nothing therefore, correctly, gets
+    # nothing locally either. This job is what switches the local gate on.
+    #
+    # ## Why there is no `terraform validate` here
+    #
+    # Not an oversight, and do not "fix" it by adding one. `terraform/main.tf`
+    # sets `source = "../../cloud/aws/compute"`, a path relative to the module's
+    # INSTALL location (`modules/plugins/<name>/` in the consuming monorepo),
+    # not to this repo. `terraform init` in `terraform/` therefore fails with
+    #
+    #   Error: Unreadable module directory
+    #   Unable to evaluate directory symlink: lstat ../../cloud: no such file
+    #
+    # before `validate` is ever reached — verified against this skeleton. The
+    # module is validated where its paths resolve: by the consuming project's
+    # own `infra-validate` job, after `biffo plugin install` has copied it into
+    # place. See `terraform/README.md`, which has said so all along.
+    #
+    # fmt alone is not cosmetic. `terraform fmt -check` parses the HCL, so it
+    # exits 2 on an unparseable file and 3 on a merely unformatted one — the
+    # "a malformed .tf merges green" hole is closed by this step by itself.
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: hashicorp/setup-terraform@v4
+        with:
+          terraform_version: '~> 1.9'
+      - name: Terraform fmt check
+        run: terraform fmt -check -recursive terraform/
+
   security-secrets:
     name: Secret Scan
     runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}

package/_skeletons/sibling-template/.githooks/pre-push

@@ -53,6 +53,47 @@ cd "$root" || exit 0
 # cannot run, that is a reason to stop, not to wave the push through.
 sh scripts/biffo.sh rewrite-scope-check || exit 1
 
+# --- Claim guard (#1231 instance 2) -------------------------------------------
+#
+# `scripts/claim.sh` (packaged inside `@biffo/cli`, run through the bridge
+# above) has asked the estate's four-signal question about "is this issue
+# taken?" since #1209 -- but nothing ever RAN it. It shipped advisory-only, so
+# the fix for the collisions it exists to catch was itself subject to the same
+# failure: a collision happens precisely when someone does not think to check.
+#
+# `--guard <branch>` is the enforced form. It derives the issue number from the
+# branch name (`<type>/<number>-slug>`) and, when the branch names one, checks
+# for another remote branch or another OPEN PR naming the same issue -- NEVER
+# the `in-progress` label (three of four real collisions were "work exists,
+# label does not") and NEVER identity (a claim on #1109 was recorded as
+# `github-actions[bot]` because of a repo-local `user.email` override). It
+# excludes the branch being pushed and any PR whose head IS that branch, so
+# pushing your own branch a second time cannot block you on your own work.
+#
+# A branch that names no issue returns before any network call -- most
+# branches are fine, and noise kills a gate. Measured on a branch that DOES
+# name one: the added latency is the cost of two `gh` lookups, similar in
+# order of magnitude to `rewrite-scope-check` above.
+branch=$(git symbolic-ref --quiet --short HEAD) || branch=""
+
+if [ -n "$branch" ]; then
+  sh scripts/biffo.sh claim --guard "$branch"
+  claim_status=$?
+
+  if [ "$claim_status" -eq 1 ]; then
+    exit 1
+  fi
+
+  # $claim_status -eq 2 is "cannot tell" -- no network, gh unauthenticated, an
+  # API error -- and claim.sh has already printed a warning. Deliberately NOT
+  # blocked here: unlike every other gate in this file, this is a COORDINATION
+  # gate, not a correctness one. A false block costs the ability to push at
+  # all; a miss costs a recoverable collision caught early (every collision in
+  # #1209's own incident was caught before duplicate work merged). Set
+  # BIFFO_CLAIM_STRICT=1 to make claim.sh itself collapse cannot-tell into
+  # exit 1 instead, if you would rather block than guess.
+fi
+
 # Through the version-pinned CLI since #1109, so a repo cannot run a gate two
 # versions old -- eight of them did, and tabsii-crm checked ONE thing in eight
 # on a 700-line change and printed `verify passed` (#855). There is one copy of

package/package.json

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

package/scripts/claim.sh

@@ -42,6 +42,7 @@
 #   sh scripts/claim.sh 1234                 # check, and claim if free
 #   sh scripts/claim.sh 1234 --check         # report only, change nothing
 #   sh scripts/claim.sh 1234 -R owner/repo
+#   sh scripts/claim.sh --guard <branch>     # pre-push gate — see below
 #
 #   0  free — and claimed, unless --check
 #   1  taken, or already closed — the reason is printed
@@ -51,15 +52,50 @@
 # A check that cannot see its input must not report "free".
 #
 # Requires `gh`, authenticated. Uses gh's embedded jq, so no jq binary needed.
+#
+# ## `--guard <branch>` — the pre-push gate (#1231 instance 2)
+#
+# The four-signal check above is advisory: nothing ever runs it for you, so a
+# collision happens precisely when someone does not think to check. `--guard`
+# is the enforced half, called from `.githooks/pre-push` on every push.
+#
+# It answers a narrower question than the plain form above, on purpose:
+#
+#   - **Derives the issue from the branch name.** Pattern `<type>/<number>-…`,
+#     e.g. `feat/1234-thing`. A branch that does not name an issue (most of
+#     them) is skipped SILENTLY, before any network call — most branches are
+#     fine and noise kills a gate.
+#   - **Never checks the `in-progress` label.** Of four real collisions in one
+#     morning, three were "work exists, label does not" — so a gate keyed on
+#     the label would have caught one of four. This checks only what git and
+#     GitHub cannot help but know: an open PR, a remote branch.
+#   - **Never compares identity.** A claim on #1109 was recorded as
+#     `github-actions[bot]` because of a repo-local `user.email` override —
+#     usernames are not a trustworthy signal here.
+#   - **Excludes the branch being pushed, and any PR whose head IS that
+#     branch**, from counting as a conflict. Without this, pushing your own
+#     branch a second time blocks you on your own work.
+#   - **A real conflict — another branch or another open PR naming the same
+#     issue — exits 1**, naming what was found. AGENTS.md permits stealing a
+#     claim that is over an hour stale, with a comment; the message points
+#     there rather than being a dead end.
+#   - **"Cannot tell" (no network, `gh` unauthenticated, an API error) warns
+#     and exits 2 — never 1.** By default the caller should treat 2 as a pass:
+#     this is a COORDINATION gate, not a correctness one, and a false block
+#     costs the ability to push at all while a miss costs a recoverable
+#     collision caught early (see "What it cannot do" above). Set
+#     `BIFFO_CLAIM_STRICT=1` to make this script itself collapse cannot-tell
+#     into exit 1 instead, for anyone who would rather block than guess.
 
 set -u
 
 ISSUE=""
 REPO=""
 CHECK_ONLY=""
+GUARD_BRANCH=""
 
 usage() {
-  sed -n '2,58p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '2,84p' "$0" | sed 's/^# \{0,1\}//'
   exit 2
 }
 
@@ -70,6 +106,10 @@ while [ $# -gt 0 ]; do
       shift 2
       ;;
     --check) CHECK_ONLY=1; shift ;;
+    --guard)
+      GUARD_BRANCH="${2:-}"
+      shift 2
+      ;;
     -h | --help) usage ;;
     *)
       ISSUE="$1"
@@ -78,13 +118,6 @@ while [ $# -gt 0 ]; do
   esac
 done
 
-case "$ISSUE" in
-  '' | *[!0-9]*)
-    echo "claim: give an issue number, e.g. sh scripts/claim.sh 1234" >&2
-    exit 2
-    ;;
-esac
-
 RED=$(printf '\033[31m')
 GREEN=$(printf '\033[32m')
 YELLOW=$(printf '\033[33m')
@@ -94,12 +127,117 @@ OFF=$(printf '\033[0m')
 gh_issue() { if [ -n "$REPO" ]; then gh issue "$@" --repo "$REPO"; else gh issue "$@"; fi; }
 gh_pr() { if [ -n "$REPO" ]; then gh pr "$@" --repo "$REPO"; else gh pr "$@"; fi; }
 
+# `git ls-remote --heads ""` fails outright ("fatal: bad repository ''") rather
+# than falling back to the default remote — `${REPO:+url}` expands to an empty
+# STRING ARGUMENT when $REPO is unset, not to no argument at all. That silently
+# broke signal 3 below for every caller that does not pass -R, which is nearly
+# all of them: the branch check never fired, and nothing noticed because the
+# label and open-PR signals usually catch a collision first. Found while
+# building `--guard`, which depends on this signal actually working.
+remote_branches() {
+  if [ -n "$REPO" ]; then
+    git ls-remote --heads "https://github.com/$REPO.git"
+  else
+    git ls-remote --heads
+  fi
+}
+
 LABEL=in-progress
 TAKEN=0
 REASONS=""
 
 note() { REASONS="${REASONS}  $1\n"; TAKEN=1; }
 
+# --- --guard <branch>: the enforced pre-push gate -----------------------------
+#
+# Deliberately short-circuits before any of the four-signal machinery below —
+# it asks two of those four questions, not all four, and answers a different
+# question ("would this push collide with someone else's live work?" rather
+# than "is this issue free to claim?").
+if [ -n "$GUARD_BRANCH" ]; then
+  guard_issue=$(printf '%s' "$GUARD_BRANCH" | sed -n 's#^[^/]*/\([0-9][0-9]*\)-.*#\1#p')
+
+  # No issue named by the branch — most branches, e.g.
+  # `security/brace-expansion-5-0-9`. Skip silently, and — this is the point —
+  # before touching the network at all.
+  if [ -z "$guard_issue" ]; then
+    exit 0
+  fi
+
+  cannot_tell=0
+  conflict=0
+  findings=""
+  cannot_tell_reasons=""
+
+  # --- an open PR referencing the issue, excluding our own branch's PR --------
+  pr_err=$(mktemp)
+  open_prs=$(gh_pr list --state open --limit 100 --json number,title,body,headRefName \
+    --jq "[.[] | select(((.title + \" \" + .body) | test(\"(^|[^0-9])#$guard_issue([^0-9]|\$)\")) or (.headRefName | test(\"(^|[^0-9])$guard_issue([^0-9]|\$)\")))] | .[] | select(.headRefName != \"$GUARD_BRANCH\") | \"#\(.number) \(.headRefName)\"" \
+    2>"$pr_err")
+  pr_status=$?
+  pr_err_text=$(cat "$pr_err")
+  rm -f "$pr_err"
+
+  if [ "$pr_status" -ne 0 ]; then
+    cannot_tell=1
+    cannot_tell_reasons="${cannot_tell_reasons}${pr_err_text} "
+  elif [ -n "$open_prs" ]; then
+    conflict=1
+    findings="${findings}  ${RED}open PR${OFF}    $(printf '%s' "$open_prs" | head -1)\n"
+  fi
+
+  # --- a remote branch naming the issue, excluding our own branch -------------
+  branch_err=$(mktemp)
+  raw_branches=$(remote_branches 2>"$branch_err")
+  branch_status=$?
+  branch_err_text=$(cat "$branch_err")
+  rm -f "$branch_err"
+
+  if [ "$branch_status" -ne 0 ]; then
+    cannot_tell=1
+    cannot_tell_reasons="${cannot_tell_reasons}${branch_err_text} "
+  else
+    other_branch=$(printf '%s\n' "$raw_branches" |
+      sed 's|.*refs/heads/||' |
+      grep -E "(^|[^0-9])$guard_issue([^0-9]|$)" |
+      grep -v -x "$GUARD_BRANCH" | head -1)
+    if [ -n "$other_branch" ]; then
+      conflict=1
+      findings="${findings}  ${RED}branch${OFF}     $other_branch\n"
+    fi
+  fi
+
+  if [ "$conflict" -eq 1 ]; then
+    printf '%b' "${RED}claim --guard: issue #$guard_issue looks claimed by someone else.${OFF}\n$findings"
+    echo
+    echo "${DIM}If you believe it is abandoned (no activity for over an hour), AGENTS.md${OFF}"
+    echo "${DIM}permits stealing it deliberately — say so in a comment on the issue first,${OFF}"
+    echo "${DIM}then push. Never steal a fresh claim.${OFF}"
+    exit 1
+  fi
+
+  if [ "$cannot_tell" -eq 1 ]; then
+    if [ -n "${BIFFO_CLAIM_STRICT:-}" ]; then
+      echo "${RED}claim --guard: cannot tell whether #$guard_issue is claimed elsewhere${OFF} — ${DIM}$cannot_tell_reasons${OFF}" >&2
+      echo "${DIM}BIFFO_CLAIM_STRICT=1 is set, so cannot-tell blocks the push.${OFF}" >&2
+      exit 1
+    fi
+    echo "${YELLOW}claim --guard: cannot tell whether #$guard_issue is claimed elsewhere${OFF} — ${DIM}$cannot_tell_reasons${OFF}" >&2
+    echo "${DIM}Warning and letting the push through: this is a coordination gate, not a${OFF}" >&2
+    echo "${DIM}correctness one. Set BIFFO_CLAIM_STRICT=1 to block instead of guessing.${OFF}" >&2
+    exit 2
+  fi
+
+  exit 0
+fi
+
+case "$ISSUE" in
+  '' | *[!0-9]*)
+    echo "claim: give an issue number, e.g. sh scripts/claim.sh 1234" >&2
+    exit 2
+    ;;
+esac
+
 # --- 0. Does the issue exist, and is it still open? --------------------------
 
 meta=$(gh_issue view "$ISSUE" --json state,title,labels \
@@ -150,7 +288,7 @@ fi
 #
 # Catches work that has been pushed but has no PR yet. Whole-number match again.
 
-branches=$(git ls-remote --heads "${REPO:+https://github.com/$REPO.git}" 2>/dev/null |
+branches=$(remote_branches 2>/dev/null |
   sed 's|.*refs/heads/||' |
   grep -E "(^|[^0-9])$ISSUE([^0-9]|$)" 2>/dev/null)