guardian-framework 0.1.147 → 0.1.148

package/templates/pi/scripts/validate-coverage-floors.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-coverage-floors.sh — a coverage floor may not be lowered (ADR-010)
+# ============================================================================
+# `.pi/coverage-floors.tsv` is a ratchet: raise a floor when a layer improves,
+# never lower one to make a build pass. A rule that only lives in prose is not
+# a control, so this script makes it executable.
+#
+# Two failure modes, both named:
+#
+#   1. a floor DECREASED relative to the base ref — the ratchet moved backwards
+#      and the layer's real coverage is now unguarded below where it had reached;
+#   2. a layer DISAPPEARED — a removed row stops gating, and a missing row reads
+#      as "no floor" rather than "this layer lost its floor".
+#
+# Table (tab-separated): layer<TAB>floor<TAB>measured<TAB>target<TAB>note
+#   floor     the value that gates (ratchet; never decreases)
+#   measured  last measured line/region coverage (informational)
+#   target    the criterion from the roadmap (gap printed when unmet)
+#
+# Usage:
+#   bash .pi/scripts/validate-coverage-floors.sh              # vs the base ref
+#   bash .pi/scripts/validate-coverage-floors.sh --base main
+#   bash .pi/scripts/validate-coverage-floors.sh --self-test
+# ============================================================================
+set -uo pipefail
+
+# Resolve the project root: the nearest ancestor of this script that looks like
+# a project (has .git or package.json). Works whether the script is invoked from
+# the canonical tree (templates/pi/scripts) or the shipped copy (.pi/scripts).
+resolve_root() {
+	local d
+	d="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	while [ "$d" != "/" ]; do
+		if [ -e "$d/.git" ] || [ -e "$d/package.json" ]; then
+			echo "$d"
+			return
+		fi
+		d="$(dirname "$d")"
+	done
+	echo "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+}
+ROOT="$(resolve_root)"
+TABLE_REL=".pi/coverage-floors.tsv"
+TABLE="$ROOT/$TABLE_REL"
+BASE=""
+MODE="check"
+
+while [ $# -gt 0 ]; do
+	case "$1" in
+	--base) BASE="${2:-}"; shift 2 ;;
+	--self-test) MODE="self-test"; shift ;;
+	--base-file) MODE="base-file"; BASE="${2:-}"; shift 2 ;;
+	--new-file) NEWFILE="${2:-}"; shift 2 ;;
+	*) shift ;;
+	esac
+done
+
+compare() {
+	# $1 = base table file, $2 = new table file
+	python3 - "$1" "$2" <<'PY'
+import sys
+
+def parse(path):
+    rows = {}
+    for lineno, line in enumerate(open(path, encoding="utf-8"), 1):
+        if line.startswith("#") or not line.strip():
+            continue
+        parts = line.rstrip("\n").split("\t")
+        if len(parts) < 2:
+            print(f"{path}:{lineno}: malformed row (need layer<TAB>floor...)", file=sys.stderr)
+            sys.exit(2)
+        layer, floor = parts[0], parts[1]
+        # An uncommented header row is the column name, not a floor.
+        if layer.strip().lower() == "layer":
+            continue
+        try:
+            rows[layer] = float(floor)
+        except ValueError:
+            print(f"{path}:{lineno}: floor is not a number: {floor!r}", file=sys.stderr)
+            sys.exit(2)
+    return rows
+
+base = parse(sys.argv[1])
+new = parse(sys.argv[2])
+problems = []
+
+for layer, b in sorted(base.items()):
+    if layer not in new:
+        problems.append(f"layer '{layer}' disappeared — its floor ({b:g}) no longer gates")
+    elif new[layer] < b - 1e-9:
+        problems.append(f"layer '{layer}' floor decreased {b:g} -> {new[layer]:g} "
+                        f"(a floor is a ratchet; never lower it)")
+
+if problems:
+    print("coverage floors regressed:", file=sys.stderr)
+    for p in problems:
+        print(f"  {p}", file=sys.stderr)
+    sys.exit(1)
+
+raised = [f"{l} {base[l]:g}->{new[l]:g}" for l in base if l in new and new[l] > base[l] + 1e-9]
+print(f"coverage floors OK — {len(new)} layer(s), no floor lowered"
+      + (f"; raised: {', '.join(raised)}" if raised else ""))
+PY
+}
+
+if [ "$MODE" = "--self-test" ] || [ "$MODE" = "self-test" ]; then
+	TD="$(mktemp -d "${TMPDIR:-/tmp}/floors-selftest.XXXXXX")"
+	ok=0
+	fail=0
+	bump() { if [ "$1" -eq 0 ]; then ok=$((ok + 1)); else fail=$((fail + 1)); fi; }
+
+	tbl() { printf 'layer\tfloor\tmeasured\ttarget\n%s\n' "$2" >"$TD/$1.tsv"; }
+
+	# 1. unchanged -> pass
+	tbl base 'domain	90	92	95'
+	tbl same 'domain	90	92	95'
+	compare "$TD/base.tsv" "$TD/same.tsv" >/dev/null 2>&1
+	bump $?
+
+	# 2. raised -> pass
+	tbl raised 'domain	95	96	95'
+	compare "$TD/base.tsv" "$TD/raised.tsv" >/dev/null 2>&1
+	bump $?
+
+	# 3. lowered -> fail
+	tbl lowered 'domain	80	92	95'
+	compare "$TD/base.tsv" "$TD/lowered.tsv" >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $?
+
+	# 4. layer removed -> fail
+	tbl removed 'application	90	91	90'
+	compare "$TD/base.tsv" "$TD/removed.tsv" >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $?
+
+	echo "self-test: $ok ok, $fail failed"
+	[ "$fail" -eq 0 ]
+	exit $?
+fi
+
+if [ "$MODE" != "--self-test" ] && [ "$MODE" != "self-test" ] && [ ! -f "$TABLE" ]; then
+	echo "no coverage floors table ($TABLE_REL) — nothing to ratchet (OK)"
+	exit 0
+fi
+
+if [ -n "$BASE" ]; then
+	git rev-parse --verify --quiet "$BASE" >/dev/null || {
+		echo "unknown base ref: $BASE" >&2
+		exit 2
+	}
+	BASE_COPY="$(mktemp "${TMPDIR:-/tmp}/floors-base.XXXXXX")"
+	if ! git show "$BASE:$TABLE_REL" >"$BASE_COPY" 2>/dev/null; then
+		echo "no $TABLE_REL at $BASE — first ratchet commit (OK)"
+		exit 0
+	fi
+	compare "$BASE_COPY" "$TABLE"
+else
+	# Default: compare against the merge base with the default branch when known.
+	DEFAULT_BRANCH="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+	[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+	MB="$(git merge-base HEAD "origin/$DEFAULT_BRANCH" 2>/dev/null || git merge-base HEAD "$DEFAULT_BRANCH" 2>/dev/null || true)"
+	if [ -z "$MB" ]; then
+		echo "no base commit available — floors unchanged in this checkout (OK)"
+		exit 0
+	fi
+	BASE_COPY="$(mktemp "${TMPDIR:-/tmp}/floors-base.XXXXXX")"
+	if ! git show "$MB:$TABLE_REL" >"$BASE_COPY" 2>/dev/null; then
+		echo "no $TABLE_REL at merge base — first ratchet commit (OK)"
+		exit 0
+	fi
+	compare "$BASE_COPY" "$TABLE"
+fi

package/templates/pi/scripts/validate-guards.sh

@@ -0,0 +1,171 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-guards.sh — make gating vs advisory explicit (ADR-010)
+# ============================================================================
+# A validator that cannot fail is documentation, not a control. This is the one
+# place that answers "which checks can stop a merge?".
+#
+#   * every root .pi/scripts/validate-*.sh MUST be registered in .pi/guards.tsv
+#   * every row must be well-formed and point at a file that exists
+#   * a duplicate or phantom registration is rejected
+#
+# Usage:
+#   bash .pi/scripts/validate-guards.sh              # registry integrity (advisory)
+#   bash .pi/scripts/validate-guards.sh --list       # print the classified table
+#   bash .pi/scripts/validate-guards.sh --run        # run the gating set (run_here=yes)
+#   bash .pi/scripts/validate-guards.sh --self-test  # prove the check bites
+# ============================================================================
+set -uo pipefail
+
+# Resolve the project root: the nearest ancestor of this script that looks like
+# a project (has .git or package.json). Works whether the script is invoked from
+# the canonical tree (templates/pi/scripts) or the shipped copy (.pi/scripts).
+resolve_root() {
+	local d
+	d="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	while [ "$d" != "/" ]; do
+		if [ -e "$d/.git" ] || [ -e "$d/package.json" ]; then
+			echo "$d"
+			return
+		fi
+		d="$(dirname "$d")"
+	done
+	echo "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+}
+ROOT="$(resolve_root)"
+REG="$ROOT/.pi/guards.tsv"
+
+MODE="${1:-check}"
+
+# --self-test must work in any checkout (it builds its own throwaway roots), so
+# the registry requirement applies to the real check only.
+if [ "$MODE" != "--self-test" ] && [ ! -f "$REG" ]; then
+	echo "guard registry missing: .pi/guards.tsv" >&2
+	echo "  run: guardian update --force  (recreates project-owned template files)" >&2
+	exit 2
+fi
+
+registry_check() {
+	# $1 = registry path, $2 = root, $3 = mode (check|list)
+	python3 - "$1" "$2" "$3" <<'PY'
+import os, re, sys
+
+reg, root, mode = sys.argv[1:4]
+rows, seen, errors = [], set(), []
+
+for lineno, line in enumerate(open(reg, encoding="utf-8"), 1):
+    if line.startswith("#") or not line.strip():
+        continue
+    parts = line.rstrip("\n").split("\t")
+    if len(parts) < 6:
+        errors.append(f"{lineno}: malformed row (need 6 tab-separated fields)")
+        continue
+    guard, cls, tier, run_here, owner, notes = parts[:6]
+    if tier not in ("gating", "advisory"):
+        errors.append(f"{lineno}: bad tier {tier!r} (want gating|advisory)")
+    if run_here not in ("yes", "no"):
+        errors.append(f"{lineno}: bad run_here {run_here!r} (want yes|no)")
+    if not os.path.exists(os.path.join(root, guard)):
+        errors.append(f"{lineno}: registered guard does not exist: {guard}")
+    if guard in seen:
+        errors.append(f"{lineno}: duplicate registration: {guard}")
+    seen.add(guard)
+    rows.append((guard, cls, tier, run_here, owner, notes))
+
+scripts_dir = os.path.join(root, ".pi/scripts")
+on_disk = sorted(
+    f".pi/scripts/{n}"
+    for n in (os.listdir(scripts_dir) if os.path.isdir(scripts_dir) else [])
+    if re.fullmatch(r"validate-.*\.sh", n)
+)
+unregistered = [p for p in on_disk if p not in seen]
+
+if errors:
+    print("guard registry invalid — .pi/guards.tsv:", file=sys.stderr)
+    for e in errors:
+        print(f"    {e}", file=sys.stderr)
+    sys.exit(2)
+
+if unregistered:
+    print("unclassified guard(s) — add them to .pi/guards.tsv:", file=sys.stderr)
+    for p in unregistered:
+        print(f"    {p}", file=sys.stderr)
+    print("  every guard declares gating|advisory, run_here and an owner.", file=sys.stderr)
+    sys.exit(2)
+
+if mode == "list":
+    gating = [r for r in rows if r[2] == "gating"]
+    advisory = [r for r in rows if r[2] == "advisory"]
+    print("GATING (a non-zero exit fails a mandatory path):")
+    for g, c, _t, run_here, o, _n in gating:
+        where = "run here" if run_here == "yes" else "gates elsewhere"
+        print(f"  {c:<18} {g:<48} [{where}]  owner={o}")
+    print("\nADVISORY (informational; does not stop a merge):")
+    for g, c, _t, _r, o, _n in advisory:
+        print(f"  {c:<18} {g:<48}  owner={o}")
+    print(f"\n{len(on_disk)} validator script(s) on disk, all classified "
+          f"({len(gating)} gating, {len(advisory)} advisory).")
+    sys.exit(0)
+
+print(f"guard registry OK — {len(on_disk)} validator(s), all classified "
+      f"({sum(1 for r in rows if r[2]=='gating')} gating).")
+PY
+}
+
+case "$MODE" in
+--self-test)
+	# Prove the checks bite, in throwaway roots under a temp dir.
+	TD="$(mktemp -d "${TMPDIR:-/tmp}/guards-selftest.XXXXXX")"
+	ok=0
+	fail=0
+	bump() { if [ "$1" -eq 0 ]; then ok=$((ok + 1)); else fail=$((fail + 1)); fi; }
+
+	# 1. a guard on disk that is not registered must be rejected
+	mkdir -p "$TD/case1/.pi/scripts"
+	printf '#!/usr/bin/env bash\nexit 0\n' >"$TD/case1/.pi/scripts/validate-planted.sh"
+	{ echo "# g\tclass\ttier\trun_here\towner\tnotes"; } >"$TD/case1/.pi/guards.tsv"
+	registry_check "$TD/case1/.pi/guards.tsv" "$TD/case1" check >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $?
+
+	# 2. a bad tier must be rejected
+	mkdir -p "$TD/case2/.pi/scripts"
+	printf '#!/usr/bin/env bash\nexit 0\n' >"$TD/case2/.pi/scripts/validate-x.sh"
+	printf '.pi/scripts/validate-x.sh\tclass\twrong-tier\tno\towner\tnote\n' >"$TD/case2/.pi/guards.tsv"
+	out2="$(registry_check "$TD/case2/.pi/guards.tsv" "$TD/case2" check 2>&1)"
+	case "$out2" in *"bad tier"*) bump 0 ;; *) bump 1 ;; esac
+
+	# 3. a fully classified registry must pass
+	mkdir -p "$TD/case3/.pi/scripts"
+	printf '#!/usr/bin/env bash\nexit 0\n' >"$TD/case3/.pi/scripts/validate-y.sh"
+	printf '.pi/scripts/validate-y.sh\tclass\tgating\tyes\towner\tnote\n' >"$TD/case3/.pi/guards.tsv"
+	registry_check "$TD/case3/.pi/guards.tsv" "$TD/case3" check >/dev/null 2>&1
+	bump $?
+
+	echo "self-test: $ok ok, $fail failed"
+	[ "$fail" -eq 0 ]
+	;;
+--run)
+	registry_check "$REG" "$ROOT" check || exit 1
+	echo "── gating guards ──"
+	rc=0
+	while IFS=$'\t' read -r guard _cls tier run_here _owner _notes; do
+		case "$guard" in \#* | "") continue ;; esac
+		if [ "$tier" = "gating" ] && [ "$run_here" = "yes" ]; then
+			echo "▶ $guard"
+			if ! bash "$ROOT/$guard"; then
+				rc=1
+				echo "✗ $guard FAILED"
+			fi
+		fi
+	done <"$REG"
+	[ "$rc" -eq 0 ] && echo "✅ all gating guards passed"
+	exit "$rc"
+	;;
+--list)
+	registry_check "$REG" "$ROOT" list
+	;;
+*)
+	registry_check "$REG" "$ROOT" check
+	;;
+esac

package/templates/pi/scripts/validate-script-drift.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-script-drift.sh — one source of truth for mirrored .pi/ trees (ADR-010)
+# ============================================================================
+# `.pi/` is copied into sub-projects / crates, so the same command name can end
+# up as a *different program* depending on which tree invoked it. This guard
+# fails when a file mirrored across trees differs AND is not a recorded,
+# reviewed difference.
+#
+# Trees are the immediate subdirectories that carry a `.pi` directory, plus the
+# repo root. Differences are recorded in `.pi/script-drift-allow.tsv`:
+#
+#   pattern<TAB>trees<TAB>reason
+#
+# A pattern present below means the difference is known; the reason says whether
+# it is by design, inert, or drift deliberately not reconciled.
+#
+# Usage:
+#   bash .pi/scripts/validate-script-drift.sh            # check (gating)
+#   bash .pi/scripts/validate-script-drift.sh --list     # show recorded + drifted
+#   bash .pi/scripts/validate-script-drift.sh --self-test
+# ============================================================================
+set -uo pipefail
+
+# Resolve the project root: the nearest ancestor of this script that looks like
+# a project (has .git or package.json). Works whether the script is invoked from
+# the canonical tree (templates/pi/scripts) or the shipped copy (.pi/scripts).
+resolve_root() {
+	local d
+	d="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	while [ "$d" != "/" ]; do
+		if [ -e "$d/.git" ] || [ -e "$d/package.json" ]; then
+			echo "$d"
+			return
+		fi
+		d="$(dirname "$d")"
+	done
+	echo "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+}
+ROOT="$(resolve_root)"
+ALLOW="$ROOT/.pi/script-drift-allow.tsv"
+MODE="${1:-check}"
+
+drift_check() {
+	# $1 = root, $2 = allowlist path, $3 = mode, $4... = subtrees ("." is root)
+	python3 - "$@" <<'PY'
+import fnmatch, hashlib, os, sys
+
+root, allow_path, mode = sys.argv[1:4]
+# Each remaining argument is "label=dir"; `dir` contains a scripts/ subtree.
+pairs = []
+for a in sys.argv[4:]:
+    label, _, d = a.partition("=")
+    if d:
+        pairs.append((label, d))
+if not pairs:
+    pairs = [(".", os.path.join(root, ".pi"))]
+
+records = []
+if os.path.exists(allow_path):
+    for lineno, line in enumerate(open(allow_path, encoding="utf-8"), 1):
+        line = line.rstrip("\n")
+        if not line.strip() or line.startswith("#"):
+            continue
+        parts = line.split("\t")
+        if len(parts) < 3:
+            print(f"{allow_path}:{lineno}: malformed row "
+                  f"(need pattern<TAB>trees<TAB>reason)", file=sys.stderr)
+            sys.exit(2)
+        records.append((parts[0], parts[1], "\t".join(parts[2:])))
+
+def recorded(rel):
+    for pat, _trees, reason in records:
+        if fnmatch.fnmatch(rel, pat):
+            return reason
+    return None
+
+contents = {}
+for label, d in pairs:
+    d = os.path.normpath(os.path.join(d, "scripts"))
+    if not os.path.isdir(d):
+        continue
+    for dirpath, _dirnames, files in os.walk(d):
+        for f in files:
+            p = os.path.join(dirpath, f)
+            rel = os.path.relpath(p, d)
+            h = hashlib.sha256(open(p, "rb").read()).hexdigest()
+            contents.setdefault(rel, {})[label] = h
+
+mirrored = {r: d for r, d in contents.items() if len(d) >= 2}
+drifted = {r: d for r, d in mirrored.items() if len(set(d.values())) > 1}
+allowed = {r: d for r, d in drifted.items() if recorded(r) is not None}
+bad = {r: d for r, d in drifted.items() if recorded(r) is None}
+
+if mode == "list":
+    print(f"mirrored files checked: {len(mirrored)}")
+    print(f"recorded differences (allowed): {len(allowed)}")
+    for r in sorted(allowed):
+        print(f"  {r}")
+        print(f"      trees: {','.join(sorted(allowed[r]))}")
+        print(f"      why:   {recorded(r)}")
+    print(f"unrecorded differences: {len(bad)}")
+    for r in sorted(bad):
+        print(f"  {r}")
+        for t in sorted(bad[r]):
+            print(f"      {t:<10} {bad[r][t][:16]}")
+    sys.exit(0)
+
+if not mirrored:
+    print("script drift: nothing mirrored — no trees to compare (OK)")
+    sys.exit(0)
+
+print(f"script drift: {len(mirrored)} mirrored files, "
+      f"{len(allowed)} recorded difference(s), {len(bad)} unrecorded")
+
+if bad:
+    print("", file=sys.stderr)
+    print("Unintentional drift — mirrored files differ and are not recorded in "
+          ".pi/script-drift-allow.tsv:", file=sys.stderr)
+    for r in sorted(bad):
+        print(f"  {r}", file=sys.stderr)
+        for t in sorted(bad[r]):
+            print(f"      {t:<10} {bad[r][t][:16]}", file=sys.stderr)
+        print("      -> reconcile to one implementation, or record the "
+              "difference with a reason", file=sys.stderr)
+    sys.exit(1)
+
+print("OK — every unrecorded mirrored file is byte-identical across trees.")
+PY
+}
+
+# Trees compared by default:
+#   1. the repo root;
+#   2. every immediate subdirectory that carries .pi/scripts (crate layout);
+#   3. any mirror pair declared in .pi/mirrors.tsv (e.g. templates/pi -> .pi).
+# Declaring a mirror is how a framework repo compares its canonical tree with
+# the copy it ships in.
+# Directories compared. Each entry is a directory that CONTAINS a `scripts/`
+# subtree; files are compared by path relative to that `scripts/` dir.
+#   * the repo root (.pi/scripts is the root .pi/ -> its scripts dir)
+#   * every immediate subdirectory carrying .pi/scripts (crate layout)
+#   * any extra tree declared in .pi/mirrors.tsv (one path per line, e.g.
+#     templates/pi — how a framework compares its canonical tree with the copy
+#     it ships inside the repo).
+tree_dirs() {
+	echo "$ROOT/.pi"
+	for d in "$ROOT"/*/; do
+		[ -d "$d.pi/scripts" ] && echo "${d%/}/.pi"
+	done
+	local mirrors="$ROOT/.pi/mirrors.tsv"
+	if [ -f "$mirrors" ]; then
+		while IFS= read -r line; do
+			case "$line" in \#*|"") continue ;; esac
+			line="$(echo "$line" | tr -d '[:space:]')"
+			[ -n "$line" ] && [ -d "$ROOT/$line/scripts" ] && echo "$ROOT/$line"
+		done <"$mirrors"
+	fi
+}
+
+# label=dir arguments for the real comparison; label is the display name.
+tree_args() {
+	local out=""
+	for d in $(tree_dirs); do
+		local rel="${d#"$ROOT"/}"
+		out="$out ${rel}=$d"
+	done
+	echo "$out"
+}
+
+case "$MODE" in
+--self-test)
+	TD="$(mktemp -d "${TMPDIR:-/tmp}/drift-selftest.XXXXXX")"
+	ok=0
+	fail=0
+	bump() {
+		if [ "$1" -eq 0 ]; then ok=$((ok + 1)); else fail=$((fail + 1)); echo "  x case $2" >&2; fi
+	}
+
+	# 1. identical copies -> pass
+	mkdir -p "$TD/case1/pi/scripts" "$TD/case1/crate/pi/scripts"
+	printf 'echo a\n' >"$TD/case1/pi/scripts/tool.sh"
+	cp "$TD/case1/pi/scripts/tool.sh" "$TD/case1/crate/pi/scripts/tool.sh"
+	: >"$TD/case1/allow.tsv"
+	drift_check "$TD/case1" "$TD/case1/allow.tsv" check "pi=$TD/case1/pi" "crate=$TD/case1/crate/pi" >/dev/null 2>&1
+	bump $? 1
+
+	# 2. divergent copies, unrecorded -> fail
+	mkdir -p "$TD/case2/pi/scripts" "$TD/case2/crate/pi/scripts"
+	printf 'echo a\n' >"$TD/case2/pi/scripts/tool.sh"
+	printf 'echo b\n' >"$TD/case2/crate/pi/scripts/tool.sh"
+	: >"$TD/case2/allow.tsv"
+	drift_check "$TD/case2" "$TD/case2/allow.tsv" check "pi=$TD/case2/pi" "crate=$TD/case2/crate/pi" >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $? 2
+
+	# 3. divergent copies, recorded -> pass
+	printf 'tool.sh\tpi,crate\tby design\n' >"$TD/case2/allow.tsv"
+	drift_check "$TD/case2" "$TD/case2/allow.tsv" check "pi=$TD/case2/pi" "crate=$TD/case2/crate/pi" >/dev/null 2>&1
+	bump $? 3
+
+	echo "self-test: $ok ok, $fail failed"
+	[ "$fail" -eq 0 ]
+	;;
+--list | list)
+	# shellcheck disable=SC2046
+	drift_check "$ROOT" "$ALLOW" list $(tree_args)
+	;;
+*)
+	[ -f "$ALLOW" ] || printf '' >"$ALLOW"
+	# shellcheck disable=SC2046
+	drift_check "$ROOT" "$ALLOW" check $(tree_args)
+	;;
+esac

package/templates/pi/scripts/validate-shell-exit-status.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# ============================================================================
+# validate-shell-exit-status.sh — a passing path must not exit non-zero
+# ============================================================================
+# The bug class: an arithmetic command used as a *statement*.
+#
+#   set -e; x=0; x=$((x + 1)); echo survived
+#     bash 3.2 (macOS) → exit 0, prints "survived"
+#     bash 4.4 / 5.x   → exit 1, prints nothing
+#
+# Two shapes are caught:
+#   1. a standalone arithmetic command in a script that enables errexit
+#   2. the same command as the tail of a one-line function body — there the
+#      *function* returns 1, which errexit treats as a failed command on every
+#      shell: `log_pass() { echo ok; PASS=$((PASS + 1)); }` ends the script on macOS too.
+#
+# The fix is the assignment form, `X=$((X + 1))`, which always returns 0 and
+# does not swallow a real failure (unlike `x=$((x + 1)) || true`).
+#
+# Usage: bash .pi/scripts/validate-shell-exit-status.sh [root] [--self-test]
+# ============================================================================
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# Resolve the project root: the nearest ancestor of this script that looks like
+# a project (has .git or package.json). Works whether the script is invoked from
+# the canonical tree (templates/pi/scripts) or the shipped copy (.pi/scripts).
+resolve_root() {
+	local d
+	d="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+	while [ "$d" != "/" ]; do
+		if [ -e "$d/.git" ] || [ -e "$d/package.json" ]; then
+			echo "$d"
+			return
+		fi
+		d="$(dirname "$d")"
+	done
+	echo "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+}
+RESOLVED_ROOT="$(resolve_root)"
+ROOT="${1:-$RESOLVED_ROOT}"
+
+[ "$ROOT" = "--self-test" ] && ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+SELFTEST=0
+for a in "$@"; do [ "$a" = "--self-test" ] && SELFTEST=1; done
+
+ARITH='\(\([[:space:]]*[A-Za-z_][A-Za-z0-9_]*[[:space:]]*(\+\+|--)[[:space:]]*\)\)'
+STANDALONE_RE="^[[:space:]]*${ARITH}[[:space:]]*;?[[:space:]]*(#.*)?$"
+FUNC_TAIL_RE="^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*[[:space:]]*\(\)[[:space:]]*\{.*;[[:space:]]*${ARITH}[[:space:]]*;[[:space:]]*\}[[:space:]]*(#.*)?$"
+ERREXIT_RE='^[[:space:]]*set[[:space:]]+-[a-zA-Z]*e|set[[:space:]]+-o[[:space:]]+errexit'
+
+scan() {
+	# $1 = root to scan
+	local root="$1"
+	local offenders=0
+	while IFS= read -r f; do
+		case "$f" in */node_modules/* | */target/* | */.git/*) continue ;; esac
+		# Only files that enable errexit are in scope.
+		grep -qE "$ERREXIT_RE" "$f" 2>/dev/null || continue
+		local n=0
+		while IFS= read -r line; do
+			n=$((n + 1))
+			if [[ "$line" =~ $STANDALONE_RE ]] || [[ "$line" =~ $FUNC_TAIL_RE ]]; then
+				if [ "$offenders" -eq 0 ]; then
+					echo "Arithmetic command used as a statement (returns 1 when the value is 0):" >&2
+				fi
+				offenders=$((offenders + 1))
+				echo "  ${f#"$root"/}:$n: $(echo "$line" | sed 's/^[[:space:]]*//')" >&2
+			fi
+		done <"$f"
+	done < <(find "$root" -name '*.sh' -not -path '*/node_modules/*' -not -path '*/target/*' -not -path '*/.git/*' 2>/dev/null)
+
+	if [ "$offenders" -gt 0 ]; then
+		echo "" >&2
+		echo "  Use the assignment form, which always returns 0:" >&2
+		echo "    X=\$((X + 1))     (not  ((X++))  and not  ((X++)) || true)" >&2
+		return 1
+	fi
+	return 0
+}
+
+if [ "$SELFTEST" -eq 1 ]; then
+	TD="$(mktemp -d "${TMPDIR:-/tmp}/exits-selftest.XXXXXX")"
+	ok=0
+	fail=0
+	bump() { if [ "$1" -eq 0 ]; then ok=$((ok + 1)); else fail=$((fail + 1)); fi; }
+
+	# 1. standalone arithmetic command -> fail
+	mkdir -p "$TD/case1"
+	printf '#!/usr/bin/env bash\nset -e\nx=0\n((x++))\necho survived\n' >"$TD/case1/bad.sh"
+	scan "$TD/case1" >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $?
+
+	# 2. function tail -> fail
+	mkdir -p "$TD/case2"
+	printf '#!/usr/bin/env bash\nset -euo pipefail\nPASS=0\nlog_pass() { echo ok; ((PASS++)); }\n' >"$TD/case2/bad.sh"
+	scan "$TD/case2" >/dev/null 2>&1
+	[ $? -ne 0 ]
+	bump $?
+
+	# 3. assignment form -> pass
+	mkdir -p "$TD/case3"
+	printf '#!/usr/bin/env bash\nset -e\nx=0\nx=$((x + 1))\necho survived\n' >"$TD/case3/good.sh"
+	scan "$TD/case3" >/dev/null 2>&1
+	bump $?
+
+	# 4. no errexit -> out of scope, pass
+	mkdir -p "$TD/case4"
+	printf '#!/usr/bin/env bash\nx=0\n((x++))\necho ok\n' >"$TD/case4/loose.sh"
+	scan "$TD/case4" >/dev/null 2>&1
+	bump $?
+
+	echo "self-test: $ok ok, $fail failed"
+	[ "$fail" -eq 0 ]
+	exit $?
+fi
+
+echo "── shell exit-status scan: $ROOT ──"
+scan "$ROOT" && echo "✅ no arithmetic-statement exit hazards"