@biffo/cli 0.170.0 → 0.172.0

package/_skeletons/plugin-template/.githooks/commit-msg

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# Conventional Commits, and the core-ownership boundary.
+# See docs/practices/standards/local-gates.md
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+
+# commitlint only where it is configured. The release derives its version bump
+# from the squash-merge subject (ADR-0006), so this matters most in repos that
+# cut releases -- but a repo without the config must not be blocked by it.
+if [ -f commitlint.config.js ] || [ -f commitlint.config.mjs ] || [ -f .commitlintrc.json ]; then
+  pnpm exec commitlint --edit "$1" || exit 1
+else
+  echo "commit-msg: no commitlint config — subject not checked (see local-gates.md)" >&2
+fi
+
+# Refuse commits that edit template-owned paths (#370). Inert in the template
+# and absent in sibling/plugin repos, which own all of their own paths.
+# CI runs the same check, which --no-verify cannot skip.
+if [ -f scripts/biffo.sh ]; then
+  sh scripts/biffo.sh check ownership --staged "$1" || exit 1
+fi

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# Per-file, auto-fixing, sub-second. See docs/practices/standards/local-gates.md
+#
+# Defensive by design: these three hooks are dropped verbatim into every repo in
+# the estate, and they differ in what they have. A hook that fails because the
+# repo has no lint-staged config would block all work there, which is how a
+# safety measure gets ripped out. Absent tooling is reported, never fatal;
+# tooling that IS present and fails is fatal.
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+
+if [ ! -f package.json ]; then
+  echo "pre-commit: no package.json — nothing staged-file-level to run" >&2
+  exit 0
+fi
+if ! node -e "const p=require('./package.json');process.exit(p['lint-staged']||p.config?.['lint-staged']?0:1)" 2>/dev/null \
+   && [ ! -f .lintstagedrc ] && [ ! -f .lintstagedrc.json ] && [ ! -f lint-staged.config.js ]; then
+  echo "pre-commit: no lint-staged config — skipping (see local-gates.md)" >&2
+  exit 0
+fi
+exec pnpm exec lint-staged

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

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+# Run the checks CI runs, before paying for the round trip that would find them.
+#
+# Over the 30 days to 2026-07-29 the estate had 373 failed CI runs, 211 of 342
+# failing steps locally catchable. scripts/verify.sh documents the breakdown and
+# what it deliberately leaves out.
+#
+# Skip in CI. This is a *local* guard; CI runs each check in its own job with its
+# own reporting. CI jobs that push (notably the core-v* tag workflow) have no
+# `uv` on PATH, so firing here made tag pushes fail with `uv: not found` (code
+# 127) and blocked releases. GitHub Actions and every mainstream CI set $CI.
+[ -n "${CI:-}" ] && exit 0
+
+# Escape hatch, deliberately explicit rather than a flag on git. `--no-verify`
+# would skip this too, but it also skips every other hook silently; this leaves a
+# decision in the shell history. Its usage rate is an H4 counter-metric.
+if [ -n "${BIFFO_SKIP_VERIFY:-}" ]; then
+  echo "pre-push: verify skipped (BIFFO_SKIP_VERIFY set) — CI will run it anyway." >&2
+  exit 0
+fi
+
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+if [ ! -f scripts/verify.sh ]; then
+  echo "pre-push: no scripts/verify.sh — NO checks ran (see local-gates.md)" >&2
+  exit 0
+fi
+exec sh scripts/verify.sh

package/_skeletons/plugin-template/scripts/hook-audit.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+#
+# Is a git hook actually going to execute here?
+#
+# ## Why this exists
+#
+# A configured hook that does not run is worse than no hook, because it is
+# assumed to be protecting you. On 2026-07-29 the estate was in exactly that
+# state: `core.hooksPath` pointed at `.husky/_`, a **gitignored** directory
+# created only by `prepare: husky` on `pnpm install` — and git resolves that
+# relative path against *each worktree's* root. Every fresh worktree therefore
+# had no hooks, and git said nothing: no warning, no error, no output.
+#
+# AGENTS.md §1 mandates a fresh worktree per unit of work, so the required
+# workflow disarmed its own gates. 6 of 32 working trees were armed. The pre-push
+# pyright, the pre-commit lint-staged and commitlint had all been silently
+# skipped in the other 26 for as long as anyone had been using worktrees.
+#
+# Nothing detected it because nothing looked. This is the thing that looks.
+#
+# ## Verdicts
+#
+#   ARMED     git will execute a hook here.
+#   DEAD      core.hooksPath is set and its target is missing or carries no
+#             hooks. Git skips silently. **This is the state that lies to you**,
+#             and the only one that makes this script exit non-zero.
+#   NO-HOOKS  no hooks configured at all. Honest, and visible in this report.
+#
+# Usage:
+#   sh scripts/hook-audit.sh                 # this repo and its worktrees
+#   sh scripts/hook-audit.sh --estate ~/code # every repo under a directory
+#   sh scripts/hook-audit.sh --quiet         # verdict counts only
+
+set -uo pipefail
+
+ESTATE=""
+QUIET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --estate) ESTATE="$2"; shift 2 ;;
+    --quiet) QUIET=1; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+armed=0
+dead=0
+nohooks=0
+dead_list=""
+
+# The three hooks this standard cares about. A hooksPath directory containing
+# none of them is not armed for our purposes even if it holds something else.
+WANTED='^(pre-commit|pre-push|commit-msg)$'
+
+report() {
+  tree="$1"
+  label="$2"
+  hp=$(git -C "$tree" config core.hooksPath 2>/dev/null)
+
+  if [ -z "$hp" ]; then
+    # The default hooks directory is in the **common** git dir, which linked
+    # worktrees share. Reading "$tree/.git/hooks" is wrong for exactly the trees
+    # this audit exists to check: in a linked worktree `.git` is a *file*
+    # containing a gitdir pointer, so that path does not exist and every armed
+    # worktree was about to be reported NO-HOOKS. Ask git where it actually is.
+    #
+    # Git ships .sample files there that never execute, so counting the
+    # directory as armed merely for being non-empty would be exactly the false
+    # comfort this script exists to remove.
+    common=$(git -C "$tree" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+    real=$(ls "${common:-$tree/.git}/hooks" 2>/dev/null | grep -vc '\.sample$' || true)
+    if [ "${real:-0}" -gt 0 ]; then
+      armed=$((armed + 1))
+      [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "(default)" "$real hook(s) in .git/hooks"
+    else
+      nohooks=$((nohooks + 1))
+      [ -n "$QUIET" ] || printf '%-56s %-14s \033[33mNO-HOOKS\033[0m %s\n' "$label" "(default)" "no hooks configured"
+    fi
+    return
+  fi
+
+  # Relative hooksPath resolves against the working tree root — the whole bug.
+  case "$hp" in
+    /*) dir="$hp" ;;
+    *) dir="$tree/$hp" ;;
+  esac
+
+  present=$(ls "$dir" 2>/dev/null | grep -E "$WANTED" | tr '\n' ',' || true)
+  if [ -z "$present" ]; then
+    dead=$((dead + 1))
+    dead_list="$dead_list  $label ($hp)
+"
+    [ -n "$QUIET" ] || printf '%-56s %-14s \033[31mDEAD\033[0m     %s\n' "$label" "$hp" "$hp missing or holds no hooks — git skips ALL hooks silently"
+  else
+    armed=$((armed + 1))
+    [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "$hp" "${present%,}"
+  fi
+}
+
+walk_repo() {
+  root="${1%/}"
+  name="$2"
+  # Every working tree, not just the primary — the primary is usually the one
+  # that IS armed, which is how this went unnoticed for so long.
+  git -C "$root" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2}' | while read -r t; do
+    [ -d "$t" ] || continue
+    if [ "$t" = "$root" ]; then echo "$t|$name"; else echo "$t|$name${t#$root}"; fi
+  done
+}
+
+[ -n "$QUIET" ] || printf '%-56s %-14s %-8s %s\n' "WORKING TREE" "hooksPath" "VERDICT" "detail"
+
+if [ -n "$ESTATE" ]; then
+  targets=$(for d in "$ESTATE"/*/; do
+    [ -e "$d/.git" ] || continue
+    walk_repo "$d" "$(basename "${d%/}")"
+  done)
+else
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "not a git repo" >&2; exit 2; }
+  # From inside a worktree, --show-toplevel gives the worktree; walk from the
+  # common repo so sibling worktrees are audited too.
+  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+  root=$(dirname "$common")
+  targets=$(walk_repo "$root" "$(basename "$root")")
+fi
+
+while IFS='|' read -r tree label; do
+  [ -n "$tree" ] || continue
+  report "$tree" "$label"
+done <<EOF
+$targets
+EOF
+
+total=$((armed + dead + nohooks))
+printf '\n%s working trees — \033[32m%s armed\033[0m, \033[31m%s dead\033[0m, %s without hooks' "$total" "$armed" "$dead" "$nohooks"
+[ "$total" -gt 0 ] && printf ' (%s%% armed)' "$((100 * armed / total))"
+printf '\n'
+
+if [ "$dead" -gt 0 ]; then
+  printf '\n\033[31mDEAD working trees — hooks are configured here and are NOT running:\033[0m\n%s' "$dead_list"
+  printf 'Every commit and push made in these is unguarded, and nothing says so.\n'
+  printf 'Fix: run `pnpm install` there, or move the repo to tracked .githooks/.\n'
+  exit 1
+fi
+exit 0

package/_skeletons/plugin-template/scripts/install-hooks.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env sh
+#
+# Install hook dispatchers into the repository's **shared** hooks directory, so
+# every worktree is guarded — including ones that already exist.
+#
+# ## Why not core.hooksPath
+#
+# #838 moved the hooks into a tracked `.githooks/` and pointed
+# `core.hooksPath` there. That fixed the original bug (a gitignored runner
+# directory that only `pnpm install` created), but it leaves a gap that matters
+# for reaching full coverage:
+#
+# `core.hooksPath` is a **relative** path resolved against each worktree's root,
+# and it lives in the shared config. So the moment it is set, every worktree
+# checked out on a branch that predates `.githooks/` has the config but not the
+# directory — and git is back to skipping silently. AGENTS.md forbids modifying
+# a worktree you did not create, so those cannot simply be rebased.
+#
+# Git's own default is better than the override. With `core.hooksPath` **unset**,
+# a linked worktree runs the hooks in the **common** `.git/hooks` directory —
+# verified 2026-07-29: a dispatcher installed once in the main checkout fired in
+# a pre-existing linked worktree and in one created afterwards, blocking the
+# commit in both, with the hook's `pwd` set to the worktree.
+#
+# So the shared directory is the delivery mechanism and `.githooks/` stays the
+# source of truth for the logic. One install per clone arms every worktree that
+# clone will ever have.
+#
+# ## What a dispatcher does when there is nothing to dispatch to
+#
+# It warns and exits 0. A branch without `.githooks/` has no repo-defined hooks,
+# which is the state it was already in — blocking every commit there would be
+# inventing a gate that branch never had, and would break other agents
+# mid-flight. But it says so, every time, because "no checks ran" being
+# invisible is the whole defect (#838, #839).
+#
+# Run by `prepare`, so `pnpm install` is still what arms a fresh clone. There is
+# no way to ship an armed hook in a repository — that is git's design, not an
+# oversight — so the goal is to need it once per clone rather than once per
+# worktree.
+
+set -eu
+
+HOOKS_DIR="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/hooks"
+mkdir -p "$HOOKS_DIR"
+
+# An inherited core.hooksPath would make every dispatcher below unreachable, and
+# the failure would be silent. Clearing it is the entire point of the exercise.
+if [ -n "$(git config --local core.hooksPath 2>/dev/null || true)" ]; then
+  git config --local --unset core.hooksPath
+fi
+
+for hook in pre-commit pre-push commit-msg; do
+  cat > "$HOOKS_DIR/$hook" <<EOF
+#!/usr/bin/env sh
+# Generated by scripts/install-hooks.sh — do not edit.
+# The logic lives in the tracked .githooks/ of whichever worktree is running.
+root=\$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+if [ -x "\$root/.githooks/$hook" ]; then
+  exec "\$root/.githooks/$hook" "\$@"
+fi
+if [ -f "\$root/.githooks/$hook" ]; then
+  exec sh "\$root/.githooks/$hook" "\$@"
+fi
+# Nothing to run. Say so — an unguarded commit that looks guarded is the defect
+# this whole mechanism exists to remove (#839).
+echo "warning: no .githooks/$hook in \$root — this tree predates the local-gate" >&2
+echo "         standard, so NO checks ran. See docs/practices/standards/local-gates.md" >&2
+exit 0
+EOF
+  chmod +x "$HOOKS_DIR/$hook"
+done
+
+echo "hooks armed: $HOOKS_DIR (shared — every worktree of this clone, now and later)"

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env sh
+#
+# Run the checks CI runs, here, before the push that would have found them.
+#
+# ## Why this exists
+#
+# Until 2026-07-29 the only local gate was a whole-project `pyright` in a
+# pre-push hook -- in the three repos that had hooks at all. Everything else
+# (eslint, prettier, tsc, vitest, ruff, terraform fmt, the plugin guards) ran for
+# the first time on a GitHub runner, after a push, after a PR, after the merge
+# race.
+#
+# Over the 30 days to 2026-07-29, across the twelve repos in the estate that run
+# CI: 373 failed runs, and 211 of 342 failing steps (62%) were locally
+# catchable -- deterministic, offline, no credentials. By kind: tests 49,
+# format 53, typecheck 20, lint 16, terraform fmt 12, and the core ownership
+# guard 11 -- a check already wired as a commit hook, being discovered in the
+# pipeline because the hook was not running.
+#
+# The same file failed the same check across consecutive runs -- e.g.
+# services/api/src/api/routing/crud_handlers.py failing `ruff format --check` on
+# four separate runs. That is the signature of a round trip being used as the
+# check: push, wait for CI, read the failure, fix, push again.
+#
+# ## Why it adapts instead of being tailored
+#
+# This one file runs in the template, in instances, in sibling apps and in
+# plugin repos, whose CI check sets differ. It could have been forked per repo;
+# forks drift, and a gate that has drifted from CI reports a green CI will not
+# honour.
+#
+# So every check is conditional on the repo actually having it, and an
+# inapplicable check prints `n/a` rather than being silently absent. Absence and
+# inapplicability look identical in a summary that omits both, and telling them
+# apart is the entire point (docs/practices/standards/local-gates.md).
+#
+# ## What is deliberately excluded
+#
+#   - pytest -- 56s in the template, more than the rest of the gate combined,
+#     and it failed once there in 30 days. Opt in per repo with
+#     BIFFO_VERIFY_PYTEST=1 where the suite is fast.
+#   - app/portal build -- a full Next build.
+#   - dependency audits, pip-audit, pnpm audit -- network.
+#   - gitleaks -- scans history, not the working tree.
+#
+# cli/src/lib/verify-parity.test.ts fails if the template's CI grows a check
+# that is neither here nor in that written exclusion list.
+#
+# Usage:
+#   sh scripts/verify.sh          # everything applicable to this repo
+#   pnpm run verify               # same
+#   BIFFO_SKIP_VERIFY=1 git push  # escape hatch, for when you mean it
+
+set -u
+
+FAILED=""
+PASSED=""
+SKIPPED=""
+
+PYTEST="${BIFFO_VERIFY_PYTEST:-}"
+
+have_script() {
+  [ -f package.json ] || return 1
+  node -e "process.exit(JSON.parse(require('fs').readFileSync('package.json','utf8')).scripts?.['$1']?0:1)" 2>/dev/null
+}
+
+run_check() {
+  name="$1"
+  shift
+  start=$(date +%s)
+  if "$@" >"/tmp/biffo-verify.$$" 2>&1; then
+    PASSED="$PASSED $name"
+    printf '  \033[32mOK\033[0m   %-16s %ss\n' "$name" "$(($(date +%s) - start))"
+  else
+    FAILED="$FAILED $name"
+    printf '  \033[31mFAIL\033[0m %-16s %ss\n' "$name" "$(($(date +%s) - start))"
+    sed 's/^/      /' "/tmp/biffo-verify.$$" | tail -25
+  fi
+  rm -f "/tmp/biffo-verify.$$"
+}
+
+skip() {
+  SKIPPED="$SKIPPED $1"
+  printf '  \033[90m--   %-16s n/a - %s\033[0m\n' "$1" "$2"
+}
+
+printf '\nverify - the checks CI runs, before the push\n\n'
+
+# Python first: ruff is near-instant, so the cheapest feedback on the largest
+# single class of failure comes back immediately.
+if [ -f pyproject.toml ]; then
+  if command -v uv >/dev/null 2>&1; then
+    run_check ruff-check uv run ruff check .
+    run_check ruff-format uv run ruff format --check .
+    run_check pyright uv run pyright
+    if [ -n "$PYTEST" ]; then
+      run_check pytest uv run pytest -q
+    else
+      skip pytest "excluded - set BIFFO_VERIFY_PYTEST=1 where the suite is fast"
+    fi
+  else
+    skip python "uv not installed"
+  fi
+else
+  skip python "no pyproject.toml in this repo"
+fi
+
+# Terraform, wherever this repo keeps it: modules/ in the template and
+# instances, infra/ and modules/ in siblings.
+if command -v terraform >/dev/null 2>&1; then
+  # Scope must match this repo's CI, not exceed it. The template and instances
+  # deliberately fmt-check modules/ ONLY: infra/environments/ is user-owned, and
+  # a template-shipped check asserting over paths the template does not own is
+  # the #325 trap -- it reds an instance on content it neither wrote nor can
+  # repair. Siblings own their whole infra/ and their CI checks it, so they get
+  # both. biffo.sibling.json is what tells them apart.
+  tf_dirs=""
+  [ -d modules ] && tf_dirs="$tf_dirs modules/"
+  [ -f biffo.sibling.json ] && [ -d infra ] && tf_dirs="$tf_dirs infra/"
+  if [ -n "$tf_dirs" ]; then
+    # shellcheck disable=SC2086
+    run_check terraform-fmt terraform fmt -check -recursive $tf_dirs
+  else
+    skip terraform-fmt "no terraform in this repo"
+  fi
+else
+  skip terraform-fmt "terraform not installed"
+fi
+
+# The Biffo guards, where the dispatcher exists. Cheap, and two of them
+# (ownership, plugin-terraform) were being caught in CI.
+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
+else
+  skip biffo-guards "no scripts/biffo.sh in this repo"
+fi
+
+# JS, cheapest first; `test` last because it is slowest and the most likely to
+# be interrupted by an impatient reader.
+if [ -f package.json ]; then
+  skip build "excluded - a full app build is too slow for a push gate"
+  for s in lint typecheck format:check test; do
+    label=$(printf '%s' "$s" | tr -d ':')
+    if have_script "$s"; then
+      run_check "$label" pnpm run "$s"
+    else
+      skip "$label" "no \"$s\" script in package.json"
+    fi
+  done
+else
+  skip javascript "no package.json in this repo"
+fi
+
+printf '\n'
+if [ -n "$FAILED" ]; then
+  printf '\033[31mverify failed:\033[0m%s\n' "$FAILED"
+  printf 'Fix these here - CI will find them anyway, three minutes and a merge race later.\n'
+  printf 'Most format failures are one command: pnpm run format\n\n'
+  exit 1
+fi
+printf '\033[32mverify passed\033[0m -%s\n' "$PASSED"
+[ -n "$SKIPPED" ] && printf '\033[90mnot applicable here:%s\033[0m\n' "$SKIPPED"
+printf '\n'

package/_skeletons/sibling-template/.githooks/commit-msg

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# Conventional Commits, and the core-ownership boundary.
+# See docs/practices/standards/local-gates.md
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+
+# commitlint only where it is configured. The release derives its version bump
+# from the squash-merge subject (ADR-0006), so this matters most in repos that
+# cut releases -- but a repo without the config must not be blocked by it.
+if [ -f commitlint.config.js ] || [ -f commitlint.config.mjs ] || [ -f .commitlintrc.json ]; then
+  pnpm exec commitlint --edit "$1" || exit 1
+else
+  echo "commit-msg: no commitlint config — subject not checked (see local-gates.md)" >&2
+fi
+
+# Refuse commits that edit template-owned paths (#370). Inert in the template
+# and absent in sibling/plugin repos, which own all of their own paths.
+# CI runs the same check, which --no-verify cannot skip.
+if [ -f scripts/biffo.sh ]; then
+  sh scripts/biffo.sh check ownership --staged "$1" || exit 1
+fi

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

@@ -0,0 +1,21 @@
+#!/usr/bin/env sh
+# Per-file, auto-fixing, sub-second. See docs/practices/standards/local-gates.md
+#
+# Defensive by design: these three hooks are dropped verbatim into every repo in
+# the estate, and they differ in what they have. A hook that fails because the
+# repo has no lint-staged config would block all work there, which is how a
+# safety measure gets ripped out. Absent tooling is reported, never fatal;
+# tooling that IS present and fails is fatal.
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+
+if [ ! -f package.json ]; then
+  echo "pre-commit: no package.json — nothing staged-file-level to run" >&2
+  exit 0
+fi
+if ! node -e "const p=require('./package.json');process.exit(p['lint-staged']||p.config?.['lint-staged']?0:1)" 2>/dev/null \
+   && [ ! -f .lintstagedrc ] && [ ! -f .lintstagedrc.json ] && [ ! -f lint-staged.config.js ]; then
+  echo "pre-commit: no lint-staged config — skipping (see local-gates.md)" >&2
+  exit 0
+fi
+exec pnpm exec lint-staged

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

@@ -0,0 +1,28 @@
+#!/usr/bin/env sh
+# Run the checks CI runs, before paying for the round trip that would find them.
+#
+# Over the 30 days to 2026-07-29 the estate had 373 failed CI runs, 211 of 342
+# failing steps locally catchable. scripts/verify.sh documents the breakdown and
+# what it deliberately leaves out.
+#
+# Skip in CI. This is a *local* guard; CI runs each check in its own job with its
+# own reporting. CI jobs that push (notably the core-v* tag workflow) have no
+# `uv` on PATH, so firing here made tag pushes fail with `uv: not found` (code
+# 127) and blocked releases. GitHub Actions and every mainstream CI set $CI.
+[ -n "${CI:-}" ] && exit 0
+
+# Escape hatch, deliberately explicit rather than a flag on git. `--no-verify`
+# would skip this too, but it also skips every other hook silently; this leaves a
+# decision in the shell history. Its usage rate is an H4 counter-metric.
+if [ -n "${BIFFO_SKIP_VERIFY:-}" ]; then
+  echo "pre-push: verify skipped (BIFFO_SKIP_VERIFY set) — CI will run it anyway." >&2
+  exit 0
+fi
+
+root=$(git rev-parse --show-toplevel) || exit 0
+cd "$root" || exit 0
+if [ ! -f scripts/verify.sh ]; then
+  echo "pre-push: no scripts/verify.sh — NO checks ran (see local-gates.md)" >&2
+  exit 0
+fi
+exec sh scripts/verify.sh

package/_skeletons/sibling-template/scripts/hook-audit.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+#
+# Is a git hook actually going to execute here?
+#
+# ## Why this exists
+#
+# A configured hook that does not run is worse than no hook, because it is
+# assumed to be protecting you. On 2026-07-29 the estate was in exactly that
+# state: `core.hooksPath` pointed at `.husky/_`, a **gitignored** directory
+# created only by `prepare: husky` on `pnpm install` — and git resolves that
+# relative path against *each worktree's* root. Every fresh worktree therefore
+# had no hooks, and git said nothing: no warning, no error, no output.
+#
+# AGENTS.md §1 mandates a fresh worktree per unit of work, so the required
+# workflow disarmed its own gates. 6 of 32 working trees were armed. The pre-push
+# pyright, the pre-commit lint-staged and commitlint had all been silently
+# skipped in the other 26 for as long as anyone had been using worktrees.
+#
+# Nothing detected it because nothing looked. This is the thing that looks.
+#
+# ## Verdicts
+#
+#   ARMED     git will execute a hook here.
+#   DEAD      core.hooksPath is set and its target is missing or carries no
+#             hooks. Git skips silently. **This is the state that lies to you**,
+#             and the only one that makes this script exit non-zero.
+#   NO-HOOKS  no hooks configured at all. Honest, and visible in this report.
+#
+# Usage:
+#   sh scripts/hook-audit.sh                 # this repo and its worktrees
+#   sh scripts/hook-audit.sh --estate ~/code # every repo under a directory
+#   sh scripts/hook-audit.sh --quiet         # verdict counts only
+
+set -uo pipefail
+
+ESTATE=""
+QUIET=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --estate) ESTATE="$2"; shift 2 ;;
+    --quiet) QUIET=1; shift ;;
+    *) echo "unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+armed=0
+dead=0
+nohooks=0
+dead_list=""
+
+# The three hooks this standard cares about. A hooksPath directory containing
+# none of them is not armed for our purposes even if it holds something else.
+WANTED='^(pre-commit|pre-push|commit-msg)$'
+
+report() {
+  tree="$1"
+  label="$2"
+  hp=$(git -C "$tree" config core.hooksPath 2>/dev/null)
+
+  if [ -z "$hp" ]; then
+    # The default hooks directory is in the **common** git dir, which linked
+    # worktrees share. Reading "$tree/.git/hooks" is wrong for exactly the trees
+    # this audit exists to check: in a linked worktree `.git` is a *file*
+    # containing a gitdir pointer, so that path does not exist and every armed
+    # worktree was about to be reported NO-HOOKS. Ask git where it actually is.
+    #
+    # Git ships .sample files there that never execute, so counting the
+    # directory as armed merely for being non-empty would be exactly the false
+    # comfort this script exists to remove.
+    common=$(git -C "$tree" rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+    real=$(ls "${common:-$tree/.git}/hooks" 2>/dev/null | grep -vc '\.sample$' || true)
+    if [ "${real:-0}" -gt 0 ]; then
+      armed=$((armed + 1))
+      [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "(default)" "$real hook(s) in .git/hooks"
+    else
+      nohooks=$((nohooks + 1))
+      [ -n "$QUIET" ] || printf '%-56s %-14s \033[33mNO-HOOKS\033[0m %s\n' "$label" "(default)" "no hooks configured"
+    fi
+    return
+  fi
+
+  # Relative hooksPath resolves against the working tree root — the whole bug.
+  case "$hp" in
+    /*) dir="$hp" ;;
+    *) dir="$tree/$hp" ;;
+  esac
+
+  present=$(ls "$dir" 2>/dev/null | grep -E "$WANTED" | tr '\n' ',' || true)
+  if [ -z "$present" ]; then
+    dead=$((dead + 1))
+    dead_list="$dead_list  $label ($hp)
+"
+    [ -n "$QUIET" ] || printf '%-56s %-14s \033[31mDEAD\033[0m     %s\n' "$label" "$hp" "$hp missing or holds no hooks — git skips ALL hooks silently"
+  else
+    armed=$((armed + 1))
+    [ -n "$QUIET" ] || printf '%-56s %-14s \033[32mARMED\033[0m    %s\n' "$label" "$hp" "${present%,}"
+  fi
+}
+
+walk_repo() {
+  root="${1%/}"
+  name="$2"
+  # Every working tree, not just the primary — the primary is usually the one
+  # that IS armed, which is how this went unnoticed for so long.
+  git -C "$root" worktree list --porcelain 2>/dev/null | awk '/^worktree /{print $2}' | while read -r t; do
+    [ -d "$t" ] || continue
+    if [ "$t" = "$root" ]; then echo "$t|$name"; else echo "$t|$name${t#$root}"; fi
+  done
+}
+
+[ -n "$QUIET" ] || printf '%-56s %-14s %-8s %s\n' "WORKING TREE" "hooksPath" "VERDICT" "detail"
+
+if [ -n "$ESTATE" ]; then
+  targets=$(for d in "$ESTATE"/*/; do
+    [ -e "$d/.git" ] || continue
+    walk_repo "$d" "$(basename "${d%/}")"
+  done)
+else
+  root=$(git rev-parse --show-toplevel 2>/dev/null) || { echo "not a git repo" >&2; exit 2; }
+  # From inside a worktree, --show-toplevel gives the worktree; walk from the
+  # common repo so sibling worktrees are audited too.
+  common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)
+  root=$(dirname "$common")
+  targets=$(walk_repo "$root" "$(basename "$root")")
+fi
+
+while IFS='|' read -r tree label; do
+  [ -n "$tree" ] || continue
+  report "$tree" "$label"
+done <<EOF
+$targets
+EOF
+
+total=$((armed + dead + nohooks))
+printf '\n%s working trees — \033[32m%s armed\033[0m, \033[31m%s dead\033[0m, %s without hooks' "$total" "$armed" "$dead" "$nohooks"
+[ "$total" -gt 0 ] && printf ' (%s%% armed)' "$((100 * armed / total))"
+printf '\n'
+
+if [ "$dead" -gt 0 ]; then
+  printf '\n\033[31mDEAD working trees — hooks are configured here and are NOT running:\033[0m\n%s' "$dead_list"
+  printf 'Every commit and push made in these is unguarded, and nothing says so.\n'
+  printf 'Fix: run `pnpm install` there, or move the repo to tracked .githooks/.\n'
+  exit 1
+fi
+exit 0

package/_skeletons/sibling-template/scripts/install-hooks.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env sh
+#
+# Install hook dispatchers into the repository's **shared** hooks directory, so
+# every worktree is guarded — including ones that already exist.
+#
+# ## Why not core.hooksPath
+#
+# #838 moved the hooks into a tracked `.githooks/` and pointed
+# `core.hooksPath` there. That fixed the original bug (a gitignored runner
+# directory that only `pnpm install` created), but it leaves a gap that matters
+# for reaching full coverage:
+#
+# `core.hooksPath` is a **relative** path resolved against each worktree's root,
+# and it lives in the shared config. So the moment it is set, every worktree
+# checked out on a branch that predates `.githooks/` has the config but not the
+# directory — and git is back to skipping silently. AGENTS.md forbids modifying
+# a worktree you did not create, so those cannot simply be rebased.
+#
+# Git's own default is better than the override. With `core.hooksPath` **unset**,
+# a linked worktree runs the hooks in the **common** `.git/hooks` directory —
+# verified 2026-07-29: a dispatcher installed once in the main checkout fired in
+# a pre-existing linked worktree and in one created afterwards, blocking the
+# commit in both, with the hook's `pwd` set to the worktree.
+#
+# So the shared directory is the delivery mechanism and `.githooks/` stays the
+# source of truth for the logic. One install per clone arms every worktree that
+# clone will ever have.
+#
+# ## What a dispatcher does when there is nothing to dispatch to
+#
+# It warns and exits 0. A branch without `.githooks/` has no repo-defined hooks,
+# which is the state it was already in — blocking every commit there would be
+# inventing a gate that branch never had, and would break other agents
+# mid-flight. But it says so, every time, because "no checks ran" being
+# invisible is the whole defect (#838, #839).
+#
+# Run by `prepare`, so `pnpm install` is still what arms a fresh clone. There is
+# no way to ship an armed hook in a repository — that is git's design, not an
+# oversight — so the goal is to need it once per clone rather than once per
+# worktree.
+
+set -eu
+
+HOOKS_DIR="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)/hooks"
+mkdir -p "$HOOKS_DIR"
+
+# An inherited core.hooksPath would make every dispatcher below unreachable, and
+# the failure would be silent. Clearing it is the entire point of the exercise.
+if [ -n "$(git config --local core.hooksPath 2>/dev/null || true)" ]; then
+  git config --local --unset core.hooksPath
+fi
+
+for hook in pre-commit pre-push commit-msg; do
+  cat > "$HOOKS_DIR/$hook" <<EOF
+#!/usr/bin/env sh
+# Generated by scripts/install-hooks.sh — do not edit.
+# The logic lives in the tracked .githooks/ of whichever worktree is running.
+root=\$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+if [ -x "\$root/.githooks/$hook" ]; then
+  exec "\$root/.githooks/$hook" "\$@"
+fi
+if [ -f "\$root/.githooks/$hook" ]; then
+  exec sh "\$root/.githooks/$hook" "\$@"
+fi
+# Nothing to run. Say so — an unguarded commit that looks guarded is the defect
+# this whole mechanism exists to remove (#839).
+echo "warning: no .githooks/$hook in \$root — this tree predates the local-gate" >&2
+echo "         standard, so NO checks ran. See docs/practices/standards/local-gates.md" >&2
+exit 0
+EOF
+  chmod +x "$HOOKS_DIR/$hook"
+done
+
+echo "hooks armed: $HOOKS_DIR (shared — every worktree of this clone, now and later)"

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env sh
+#
+# Run the checks CI runs, here, before the push that would have found them.
+#
+# ## Why this exists
+#
+# Until 2026-07-29 the only local gate was a whole-project `pyright` in a
+# pre-push hook -- in the three repos that had hooks at all. Everything else
+# (eslint, prettier, tsc, vitest, ruff, terraform fmt, the plugin guards) ran for
+# the first time on a GitHub runner, after a push, after a PR, after the merge
+# race.
+#
+# Over the 30 days to 2026-07-29, across the twelve repos in the estate that run
+# CI: 373 failed runs, and 211 of 342 failing steps (62%) were locally
+# catchable -- deterministic, offline, no credentials. By kind: tests 49,
+# format 53, typecheck 20, lint 16, terraform fmt 12, and the core ownership
+# guard 11 -- a check already wired as a commit hook, being discovered in the
+# pipeline because the hook was not running.
+#
+# The same file failed the same check across consecutive runs -- e.g.
+# services/api/src/api/routing/crud_handlers.py failing `ruff format --check` on
+# four separate runs. That is the signature of a round trip being used as the
+# check: push, wait for CI, read the failure, fix, push again.
+#
+# ## Why it adapts instead of being tailored
+#
+# This one file runs in the template, in instances, in sibling apps and in
+# plugin repos, whose CI check sets differ. It could have been forked per repo;
+# forks drift, and a gate that has drifted from CI reports a green CI will not
+# honour.
+#
+# So every check is conditional on the repo actually having it, and an
+# inapplicable check prints `n/a` rather than being silently absent. Absence and
+# inapplicability look identical in a summary that omits both, and telling them
+# apart is the entire point (docs/practices/standards/local-gates.md).
+#
+# ## What is deliberately excluded
+#
+#   - pytest -- 56s in the template, more than the rest of the gate combined,
+#     and it failed once there in 30 days. Opt in per repo with
+#     BIFFO_VERIFY_PYTEST=1 where the suite is fast.
+#   - app/portal build -- a full Next build.
+#   - dependency audits, pip-audit, pnpm audit -- network.
+#   - gitleaks -- scans history, not the working tree.
+#
+# cli/src/lib/verify-parity.test.ts fails if the template's CI grows a check
+# that is neither here nor in that written exclusion list.
+#
+# Usage:
+#   sh scripts/verify.sh          # everything applicable to this repo
+#   pnpm run verify               # same
+#   BIFFO_SKIP_VERIFY=1 git push  # escape hatch, for when you mean it
+
+set -u
+
+FAILED=""
+PASSED=""
+SKIPPED=""
+
+PYTEST="${BIFFO_VERIFY_PYTEST:-}"
+
+have_script() {
+  [ -f package.json ] || return 1
+  node -e "process.exit(JSON.parse(require('fs').readFileSync('package.json','utf8')).scripts?.['$1']?0:1)" 2>/dev/null
+}
+
+run_check() {
+  name="$1"
+  shift
+  start=$(date +%s)
+  if "$@" >"/tmp/biffo-verify.$$" 2>&1; then
+    PASSED="$PASSED $name"
+    printf '  \033[32mOK\033[0m   %-16s %ss\n' "$name" "$(($(date +%s) - start))"
+  else
+    FAILED="$FAILED $name"
+    printf '  \033[31mFAIL\033[0m %-16s %ss\n' "$name" "$(($(date +%s) - start))"
+    sed 's/^/      /' "/tmp/biffo-verify.$$" | tail -25
+  fi
+  rm -f "/tmp/biffo-verify.$$"
+}
+
+skip() {
+  SKIPPED="$SKIPPED $1"
+  printf '  \033[90m--   %-16s n/a - %s\033[0m\n' "$1" "$2"
+}
+
+printf '\nverify - the checks CI runs, before the push\n\n'
+
+# Python first: ruff is near-instant, so the cheapest feedback on the largest
+# single class of failure comes back immediately.
+if [ -f pyproject.toml ]; then
+  if command -v uv >/dev/null 2>&1; then
+    run_check ruff-check uv run ruff check .
+    run_check ruff-format uv run ruff format --check .
+    run_check pyright uv run pyright
+    if [ -n "$PYTEST" ]; then
+      run_check pytest uv run pytest -q
+    else
+      skip pytest "excluded - set BIFFO_VERIFY_PYTEST=1 where the suite is fast"
+    fi
+  else
+    skip python "uv not installed"
+  fi
+else
+  skip python "no pyproject.toml in this repo"
+fi
+
+# Terraform, wherever this repo keeps it: modules/ in the template and
+# instances, infra/ and modules/ in siblings.
+if command -v terraform >/dev/null 2>&1; then
+  # Scope must match this repo's CI, not exceed it. The template and instances
+  # deliberately fmt-check modules/ ONLY: infra/environments/ is user-owned, and
+  # a template-shipped check asserting over paths the template does not own is
+  # the #325 trap -- it reds an instance on content it neither wrote nor can
+  # repair. Siblings own their whole infra/ and their CI checks it, so they get
+  # both. biffo.sibling.json is what tells them apart.
+  tf_dirs=""
+  [ -d modules ] && tf_dirs="$tf_dirs modules/"
+  [ -f biffo.sibling.json ] && [ -d infra ] && tf_dirs="$tf_dirs infra/"
+  if [ -n "$tf_dirs" ]; then
+    # shellcheck disable=SC2086
+    run_check terraform-fmt terraform fmt -check -recursive $tf_dirs
+  else
+    skip terraform-fmt "no terraform in this repo"
+  fi
+else
+  skip terraform-fmt "terraform not installed"
+fi
+
+# The Biffo guards, where the dispatcher exists. Cheap, and two of them
+# (ownership, plugin-terraform) were being caught in CI.
+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
+else
+  skip biffo-guards "no scripts/biffo.sh in this repo"
+fi
+
+# JS, cheapest first; `test` last because it is slowest and the most likely to
+# be interrupted by an impatient reader.
+if [ -f package.json ]; then
+  skip build "excluded - a full app build is too slow for a push gate"
+  for s in lint typecheck format:check test; do
+    label=$(printf '%s' "$s" | tr -d ':')
+    if have_script "$s"; then
+      run_check "$label" pnpm run "$s"
+    else
+      skip "$label" "no \"$s\" script in package.json"
+    fi
+  done
+else
+  skip javascript "no package.json in this repo"
+fi
+
+printf '\n'
+if [ -n "$FAILED" ]; then
+  printf '\033[31mverify failed:\033[0m%s\n' "$FAILED"
+  printf 'Fix these here - CI will find them anyway, three minutes and a merge race later.\n'
+  printf 'Most format failures are one command: pnpm run format\n\n'
+  exit 1
+fi
+printf '\033[32mverify passed\033[0m -%s\n' "$PASSED"
+[ -n "$SKIPPED" ] && printf '\033[90mnot applicable here:%s\033[0m\n' "$SKIPPED"
+printf '\n'

package/package.json

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