bigpowers 2.86.5 → 2.86.7

package/scripts/golden-g13-script-orphans.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# story: e37s05
+# golden-g13-script-orphans.sh — every scripts/*.sh must be wired into a gate,
+# invoked by another script/skill/doc/workflow, or explicitly tagged as a
+# manual utility.
+#
+# Originally scoped to scripts/test-*.sh only (33 of 35 test scripts were
+# reachable from nothing). Broadened after a catalog-wide review found 9 more
+# orphans among non-test scripts, one of which (sync-version-mirrors.sh) was a
+# false positive of the SCANNER, not the script: it is called from
+# .releaserc.json's semantic-release prepareCmd, a reference location the
+# original scan never searched. The file is also renamed from
+# golden-g13-test-orphans.sh to match what it now checks — a check whose name
+# doesn't match its mechanism is the exact defect class G25 fixes elsewhere in
+# this series.
+#
+# Usage: bash scripts/golden-g13-script-orphans.sh [--self-test]
+# Exit 0: every script is referenced, or explicitly tagged bp-manual-utility
+# Exit 1: at least one orphan (or, under --self-test, the gate failed to
+#         notice a deliberately unlisted, untagged script)
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+GATES_FILE="scripts/lib/golden-suite-gates.sh"
+
+# Reference locations a script can legitimately be called from. Archived
+# epics are frozen history (per BUG-2026-07-26: an archived reference is not a
+# live caller), so they're excluded even though they match the glob.
+REF_GLOBS=(
+  "scripts/**/*.sh"
+  "skills/**/SKILL.md"
+  "skills/**/REFERENCE.md"
+  "CLAUDE.md"
+  "CONVENTIONS.md"
+  "docs/**/*.md"
+  "bin/**/*.js"
+  "package.json"
+  ".releaserc.json"
+  ".github/workflows/*.yml"
+  "specs/epics/**/*.yaml"
+  "specs/epics/**/*.md"
+)
+
+is_manual_utility() { # $1 = script path
+  head -10 "$1" 2>/dev/null | grep -q '^# bp-manual-utility:'
+}
+
+is_referenced() { # $1 = script basename, $2... = candidate file globs already expanded
+  local name="$1"; shift
+  local f
+  for f in "$@"; do
+    [[ "$f" == *"/$name" || "$(basename "$f")" == "$name" ]] && continue # self
+    grep -q "$name" "$f" 2>/dev/null && return 0
+  done
+  return 1
+}
+
+collect_ref_files() {
+  shopt -s globstar nullglob
+  local pattern expanded=()
+  for pattern in "${REF_GLOBS[@]}"; do
+    for f in $pattern; do
+      [[ "$f" == specs/epics/archive/* ]] && continue
+      expanded+=("$f")
+    done
+  done
+  shopt -u globstar nullglob
+  printf '%s\n' "${expanded[@]}"
+}
+
+find_orphans() { # $1 = scripts root dir, $2 = extra untagged basename to inject (self-test only)
+  local root="$1" extra="${2:-}"
+  local orphans="" f b
+  mapfile -t ref_files < <(collect_ref_files)
+  for f in "$root"/*.sh; do
+    [[ -e "$f" ]] || continue
+    b="$(basename "$f")"
+    is_manual_utility "$f" && continue
+    is_referenced "$b" "${ref_files[@]}" || orphans+="  $b"$'\n'
+  done
+  if [[ -n "$extra" ]]; then
+    is_referenced "$extra" "${ref_files[@]}" || orphans+="  $extra"$'\n'
+  fi
+  printf '%s' "$orphans"
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  echo "=== G-13 self-test: prove the gate can fail, and that its exemptions work ==="
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+
+  # (a) An unlisted, untagged script must still be reported. Built by
+  # concatenation, not a literal string: this script's own source lives under
+  # scripts/, which REF_GLOBS also scans, so a literal fixture name written
+  # here would make the checker match its own self-test line.
+  fake_name="fixture-not-wired-$$.sh"
+  ok=1
+  if [[ -z "$(find_orphans "scripts" "$fake_name")" ]]; then
+    echo -e "${RED}FAIL${NC} (a) unlisted script was not reported — vacuous gate"
+    ok=0
+  else
+    echo -e "${GREEN}PASS${NC} (a) unlisted, untagged script is reported"
+  fi
+
+  # (b) A bp-manual-utility-tagged, unwired script must be excluded.
+  cat > "$TMP/tagged-orphan.sh" <<'EOF'
+#!/usr/bin/env bash
+# bp-manual-utility: fixture for G-13 self-test — deliberately unreferenced
+echo "never called by anything"
+EOF
+  if [[ -n "$(find_orphans "$TMP")" ]]; then
+    echo -e "${RED}FAIL${NC} (b) bp-manual-utility-tagged script was still flagged"
+    ok=0
+  else
+    echo -e "${GREEN}PASS${NC} (b) bp-manual-utility-tagged script is excluded"
+  fi
+
+  # (c) A script referenced only from .releaserc.json-shaped content must be
+  # excluded — regression guard for the exact scope gap fixed here
+  # (sync-version-mirrors.sh, called only from .releaserc.json's prepareCmd).
+  mkdir -p "$TMP/scope-fixture"
+  cat > "$TMP/scope-fixture/releaserc-lookalike.json" <<'EOF'
+{"prepareCmd": "bash scripts/only-in-releaserc.sh 1.0.0"}
+EOF
+  cat > "$TMP/scope-fixture/only-in-releaserc.sh" <<'EOF'
+#!/usr/bin/env bash
+echo "referenced only from a releaserc-shaped file"
+EOF
+  refs=("$TMP/scope-fixture/releaserc-lookalike.json")
+  if is_referenced "only-in-releaserc.sh" "${refs[@]}"; then
+    echo -e "${GREEN}PASS${NC} (c) a releaserc-shaped reference is detected by is_referenced"
+  else
+    echo -e "${RED}FAIL${NC} (c) is_referenced did not find the releaserc-shaped reference"
+    ok=0
+  fi
+
+  if [[ "$ok" -eq 1 ]]; then
+    echo "G-13 self-test: PASS"
+    exit 0
+  fi
+  echo "G-13 self-test: FAIL"
+  exit 1
+fi
+
+echo "=== G-13: script orphan check ==="
+ORPHANS="$(find_orphans "scripts")"
+TOTAL=$(ls scripts/*.sh 2>/dev/null | wc -l | tr -d ' ')
+
+if [[ -z "$ORPHANS" ]]; then
+  echo "  ok  : all $TOTAL script(s) in scripts/ are referenced or tagged bp-manual-utility"
+  echo -e "${GREEN}PASS${NC}"
+  echo "G-13: PASS"
+  exit 0
+fi
+
+echo "  orphaned scripts (present but reachable from no gate, doc, or workflow):"
+printf '%s' "$ORPHANS"
+echo -e "${RED}FAIL${NC} wire them into a gate, reference them from a skill/doc, tag them '# bp-manual-utility: <reason>', or delete them"
+echo "G-13: FAIL"
+exit 1

package/scripts/golden-g14-adapter-dispatch.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# story: e37s05
+# golden-g14-adapter-dispatch.sh — an adapter that can render must be dispatched.
+#
+# scripts/lib/srp-engine.py builds its dispatch list from targets.yaml entries
+# carrying a skill.adapter. An adapter that defines render_skill() but is
+# declared `skill: null` therefore never runs during sync, while its install
+# function still reads a rendered directory that is never produced — the target
+# reports success and installs nothing
+# (BUG-2026-07-26-null-skill-adapters-install-nothing).
+#
+# Context-only bridges (aider, goose, ...) are exempt by construction: they
+# define no render_skill, so there is nothing to dispatch.
+#
+# Usage: bash scripts/golden-g14-adapter-dispatch.sh [--self-test]
+# Exit 0: every rendering adapter is dispatched
+# Exit 1: at least one rendering adapter is undispatched (or, under
+#         --self-test, the gate failed to notice an injected one)
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+check() { # $1 = targets.yaml path
+  $PYTHON - "$1" <<'PY'
+import sys, os, re
+import yaml
+
+targets_path = sys.argv[1]
+data = yaml.safe_load(open(targets_path, encoding="utf-8")) or {}
+
+dispatched = set()
+for t in data.get("targets") or []:
+    skill = t.get("skill")
+    if isinstance(skill, dict) and skill.get("adapter"):
+        dispatched.add(skill["adapter"])
+
+problems = []
+adapter_dir = os.path.join("scripts", "adapters")
+for fn in sorted(os.listdir(adapter_dir)):
+    if not fn.endswith(".sh"):
+        continue
+    aid = fn[:-3]
+    src = open(os.path.join(adapter_dir, fn), encoding="utf-8").read()
+    if not re.search(r"^render_skill\(\)", src, re.M):
+        continue  # context-only bridge — nothing to dispatch
+    if aid not in dispatched:
+        problems.append(
+            f"{aid}: defines render_skill() but targets.yaml does not dispatch it "
+            f"(skill.adapter missing or null) — sync renders nothing for it"
+        )
+
+if problems:
+    for p in problems:
+        print(f"  UNDISPATCHED {p}")
+    print(f"\n{len(problems)} rendering adapter(s) never run during sync")
+    sys.exit(1)
+
+print(f"  ok  : all rendering adapters are dispatched ({len(dispatched)} in registry)")
+sys.exit(0)
+PY
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  echo "=== G-14 self-test: prove the gate can fail ==="
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+  $PYTHON - "$TMP/targets.yaml" <<'PY'
+import sys, yaml
+d = yaml.safe_load(open("scripts/targets.yaml", encoding="utf-8"))
+# Null out the first dispatched adapter — the gate must notice.
+for t in d.get("targets") or []:
+    s = t.get("skill")
+    if isinstance(s, dict) and s.get("adapter"):
+        print(f"injected: {t['id']} skill -> null")
+        t["skill"] = None
+        break
+yaml.dump(d, open(sys.argv[1], "w", encoding="utf-8"), default_flow_style=False, sort_keys=False)
+PY
+  set +e
+  check "$TMP/targets.yaml" >/dev/null 2>&1
+  rc=$?
+  set -e
+  if [[ $rc -ne 0 ]]; then
+    echo -e "${GREEN}PASS${NC} G-14 detected an injected undispatched adapter"
+    echo "G-14 self-test: PASS"
+    exit 0
+  fi
+  echo -e "${RED}FAIL${NC} G-14 passed on an injected null adapter — vacuous gate"
+  echo "G-14 self-test: FAIL"
+  exit 1
+fi
+
+echo "=== G-14: adapter dispatch coverage ==="
+set +e
+out=$(check "scripts/targets.yaml" 2>&1)
+rc=$?
+set -e
+echo "$out"
+if [[ $rc -eq 0 ]]; then
+  echo -e "${GREEN}PASS${NC}"
+  echo "G-14: PASS"
+  exit 0
+fi
+echo -e "${RED}FAIL${NC} see BUG-2026-07-26-null-skill-adapters-install-nothing"
+echo "G-14: FAIL"
+exit 1

package/scripts/golden-g15-compliance-runner-selftest.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# story: e45s02
+# golden-g15-compliance-runner-selftest.sh — audit-compliance-runner.sh must
+# correctly execute a Background step, a step on a file's last line with no
+# trailing newline, and must still report a genuinely failing step as FAIL
+# rather than silently dropping it.
+#
+# audit-compliance-runner.sh had two bugs that dropped steps entirely rather
+# than failing them: no Background: handling at all (akita.feature's
+# Background Given was silently skipped), and `done < "$FEATURE_FILE"` losing
+# a final line with no trailing newline (karpathy.feature's last step never
+# appeared in [STEP] output). Both are fixed; this gate is the regression
+# guard so a future change to the runner can't reintroduce either silently —
+# and, just as important, can't "fix" step-dropping by making every line
+# execute unconditionally, which would hide a genuinely failing step as a
+# false PASS.
+#
+# Usage: bash scripts/golden-g15-compliance-runner-selftest.sh [--self-test]
+# Exit 0: Background executes, the no-newline last step executes, and a
+#         failing step is reported FAIL (or, under --self-test, a loose
+#         Given line outside any Background/Scenario is correctly NOT
+#         executed)
+# Exit 1: any of the above does not hold
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+# Builds a fixture project at $1 with the step scripts a fixture .feature
+# needs, then runs audit_run_file against $2 (a path relative to $1) and
+# echoes the captured [STEP]/Result output.
+run_fixture() { # $1 = fixture root, $2 = feature file path relative to root
+  local root="$1" feature="$2"
+  (
+    cd "$root"
+    # shellcheck source=lib/audit-compliance-runner.sh
+    source "$REPO_ROOT/scripts/lib/audit-compliance-runner.sh"
+    DRY_RUN=false SCENARIO_FILTER="" JUDGE="binary"
+    TOTAL_GLOBAL_PASS=0 TOTAL_GLOBAL_FAIL=0 TOTAL_GLOBAL_WAIVED=0 TOTAL_GLOBAL_EXPIRED=0
+    audit_run_file "$feature" 2>&1
+  )
+}
+
+build_step() { # $1 = fixture root, $2 = sanitized step filename (no .sh), $3 = exit code
+  cat > "$1/specs/verifications/steps/$2.sh" <<EOF
+#!/usr/bin/env bash
+exit $3
+EOF
+}
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  echo "=== G-15 self-test: a loose Given outside Background/Scenario must not execute ==="
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+  mkdir -p "$TMP/specs/verifications/steps" "$TMP/specs/verifications/reports"
+
+  build_step "$TMP" "given-a-loose-step-outside-any-block" 0
+  # No "Background:" keyword and no "Scenario:" before this line — structurally
+  # mimics what the pre-fix runner treated every top-level Given/Then/And as
+  # (no scenario context tracked at all), which is the over-broad failure mode
+  # a bad fix could reintroduce: executing steps regardless of context.
+  printf 'Feature: G-15 self-test fixture\nGiven a loose step outside any block\n' \
+    > "$TMP/specs/features_fixture.feature"
+
+  OUTPUT=$(run_fixture "$TMP" "specs/features_fixture.feature")
+  if grep -q '\[STEP\] Given a loose step outside any block' <<<"$OUTPUT"; then
+    echo -e "${RED}FAIL${NC} a loose Given outside any Background/Scenario executed — the runner no longer tracks scenario context"
+    echo "G-15 self-test: FAIL"
+    exit 1
+  fi
+  echo -e "${GREEN}PASS${NC} the loose Given correctly did not execute"
+  echo "G-15 self-test: PASS"
+  exit 0
+fi
+
+echo "=== G-15: compliance runner Background/EOF/failure handling ==="
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/specs/verifications/steps" "$TMP/specs/verifications/reports"
+
+build_step "$TMP" "given-a-background-step" 0
+build_step "$TMP" "then-a-normal-step" 0
+build_step "$TMP" "and-a-step-that-should-fail" 1
+build_step "$TMP" "and-a-step-with-no-trailing-newline" 0
+
+# Written without a trailing newline after the last line — printf, not a
+# heredoc, so the file ends exactly where karpathy.feature's bug lived.
+printf 'Feature: G-15 fixture\n  Background:\n    Given a background step\n\n  Scenario: Fixture\n    Then a normal step\n    And a step that should fail\n    And a step with no trailing newline' \
+  > "$TMP/specs/features_fixture.feature"
+
+OUTPUT=$(run_fixture "$TMP" "specs/features_fixture.feature")
+
+FAILS=0
+
+if grep -q '\[STEP\] Given a background step' <<<"$OUTPUT"; then
+  echo -e "${GREEN}PASS${NC} Background step executed"
+else
+  echo -e "${RED}FAIL${NC} Background step did not execute"
+  FAILS=$((FAILS + 1))
+fi
+
+if grep -q '\[STEP\] And a step with no trailing newline' <<<"$OUTPUT"; then
+  echo -e "${GREEN}PASS${NC} the no-trailing-newline last step executed"
+else
+  echo -e "${RED}FAIL${NC} the no-trailing-newline last step did not execute"
+  FAILS=$((FAILS + 1))
+fi
+
+if grep -A2 '\[STEP\] And a step that should fail' <<<"$OUTPUT" | grep -q 'Result: FAIL'; then
+  echo -e "${GREEN}PASS${NC} the genuinely failing step is reported FAIL, not silently dropped"
+else
+  echo -e "${RED}FAIL${NC} the genuinely failing step was not reported FAIL"
+  FAILS=$((FAILS + 1))
+fi
+
+if [[ "$FAILS" -eq 0 ]]; then
+  echo "G-15: PASS"
+  exit 0
+fi
+echo "G-15: FAIL ($FAILS assertion(s) failed)"
+exit 1

package/scripts/golden-g16-spec-version-gap.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# story: e44s02
+# golden-g16-spec-version-gap.sh — bigpowers' own repo must never show a spec
+# version gap against itself.
+#
+# check-spec-version-gap.sh is a fully-formed SoT-drift detector for consuming
+# projects (installed package.json version vs the spec-format version stamped
+# or fingerprinted in their specs/), the same class of check as G-12, but it
+# had no gate of its own and was reachable from nothing (G-13). Running it
+# against this repo's own specs/ is the natural self-test the tool already
+# supports via --project: bigpowers' own package.json version and its own
+# specs/state.yaml bigpowers_version stamp must always agree.
+#
+# Usage: bash scripts/golden-g16-spec-version-gap.sh [--self-test]
+# Exit 0: no gap (or, under --self-test, a deliberately injected gap was
+#         correctly detected)
+# Exit 1: a real gap exists, or --self-test failed to detect an injected one
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+resolve_repo_root
+cd "$REPO_ROOT"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+if [[ "${1:-}" == "--self-test" ]]; then
+  echo "=== G-16 self-test: prove the gap detector can fail ==="
+  TMP=$(mktemp -d)
+  trap 'rm -rf "$TMP"' EXIT
+  mkdir -p "$TMP/specs"
+  cp package.json "$TMP/package.json"
+  # A stamped version far behind package.json's must be reported as a gap.
+  # set +e around the call: under set -e, `out=$(cmd)` itself aborts the
+  # script when cmd exits non-zero — exactly the outcome under test here — so
+  # rc=$? would never be reached.
+  printf 'bigpowers_version: 0.0.1\nactive_flow: null\n' > "$TMP/specs/state.yaml"
+  set +e
+  out=$(bash scripts/check-spec-version-gap.sh --project "$TMP" --skip-block --json 2>&1)
+  rc=$?
+  set -e
+  # check-spec-version-gap.sh's stamp path emits json.dumps-formatted JSON
+  # ("gap": true, with a space); its fingerprint path emits hand-concatenated
+  # JSON ("gap":true, no space) — tolerate both rather than assuming one.
+  if [[ $rc -eq 1 ]] && grep -qE '"gap":[[:space:]]*true' <<<"$out"; then
+    echo -e "${GREEN}PASS${NC} injected version gap detected (exit $rc): $out"
+    echo "G-16 self-test: PASS"
+    exit 0
+  fi
+  echo -e "${RED}FAIL${NC} injected gap was not detected (exit $rc): $out"
+  echo "G-16 self-test: FAIL"
+  exit 1
+fi
+
+echo "=== G-16: spec version gap (self-check) ==="
+# Same set -e hazard as the self-test above: a real gap exits non-zero, and
+# without set +e this assignment would abort before the FAIL branch prints.
+set +e
+OUT=$(bash scripts/check-spec-version-gap.sh --project . --skip-block --json 2>&1)
+RC=$?
+set -e
+echo "  $OUT"
+
+if [[ $RC -eq 0 ]]; then
+  echo -e "${GREEN}PASS${NC} no spec version gap"
+  echo "G-16: PASS"
+  exit 0
+fi
+echo -e "${RED}FAIL${NC} bigpowers' own specs/ disagree with its own package.json version (exit $RC)"
+echo "G-16: FAIL"
+exit 1

package/scripts/lib/adapter-guard.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# story: e37s05
+# adapter-guard.sh — shared skill-name validation for every render adapter.
+#
+# Adapters interpolate the SkillIR `name` straight into a filesystem path
+# (mkdir -p "$dir/$IR_NAME"). A name containing "/" or ".." therefore writes
+# outside the destination directory.
+#
+# Ten adapters carried a private copy of this check (qwen_is_unsafe_skill_name
+# and friends) and nine had none at all — and the nine unguarded ones were
+# exactly the nine that never got a per-target test. One guard, sourced by every
+# adapter, replaces both the duplication and the gap.
+
+# Returns 0 (true) when the name must not be used as a path component.
+bp_is_unsafe_skill_name() {
+  local name="${1-}"
+  [[ -z "$name" || "$name" == "null" || "$name" == *"/"* || "$name" == *".."* || "$name" == .* ]]
+}
+
+# Echoes the name when safe; otherwise reports on stderr and returns 1.
+# Usage inside render_skill:  name="$(bp_assert_safe_skill_name "$IR_NAME" adaptername)" || return 1
+bp_assert_safe_skill_name() {
+  local name="${1-}"
+  local adapter="${2:-adapter}"
+  if bp_is_unsafe_skill_name "$name"; then
+    echo "${adapter}: refusing unsafe skill name: ${name:-<empty>}" >&2
+    return 1
+  fi
+  printf '%s' "$name"
+}

package/scripts/lib/audit-compliance-report.sh

@@ -5,6 +5,23 @@
 if [ -n "${AUDIT_COMPLIANCE_REPORT_LOADED:-}" ]; then return 0; fi
 AUDIT_COMPLIANCE_REPORT_LOADED=1
 
+# A score sitting exactly on the 94% threshold has zero margin: one more
+# failing scenario (the suite grows over time) blocks all forward work under
+# this repo's own Always-Green doctrine — it already happened once mid-session.
+# pass-warn surfaces a thinning margin before it goes red; it still exits 0,
+# it does not block, it only makes the OKF report and terminal output loud
+# about a score close enough to the threshold to be worth attention.
+audit_gate_status() {
+  local score="$1"
+  if [[ "$score" -lt 94 ]]; then
+    echo "fail"
+  elif [[ "$score" -lt 97 ]]; then
+    echo "pass-warn"
+  else
+    echo "pass"
+  fi
+}
+
 audit_write_okf_report() {
   local OKF_DIR OKF_FILE TIMESTAMP GIT_COMMIT GATE TOTAL_GLOBAL_ALL
 
@@ -20,7 +37,7 @@ audit_write_okf_report() {
   OKF_FILE="$OKF_DIR/audit-$(date +%Y-%m-%d).okf.md"
   TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
   GIT_COMMIT=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
-  GATE=$(if [[ $SCORE -ge 94 ]]; then echo "pass"; else echo "fail"; fi)
+  GATE=$(audit_gate_status "$SCORE")
 
   cat > "$OKF_FILE" << OKF_EOF
 ---
@@ -67,10 +84,18 @@ audit_print_summary_and_exit() {
     echo "  SCORE: ${SCORE}% (threshold 94%)"
   fi
 
-  if [[ $SCORE -ge 94 ]]; then
-    echo "  GATE: PASS"
-    exit 0
-  fi
-  echo "  GATE: FAIL (below 94%)"
-  exit 1
+  case "$(audit_gate_status "$SCORE")" in
+    pass)
+      echo "  GATE: PASS"
+      exit 0
+      ;;
+    pass-warn)
+      echo "  GATE: PASS (WARNING: ${SCORE}% is within 3 points of the 94% threshold — margin is thin)"
+      exit 0
+      ;;
+    *)
+      echo "  GATE: FAIL (below 94%)"
+      exit 1
+      ;;
+  esac
 }

package/scripts/lib/audit-compliance-runner.sh

@@ -84,13 +84,26 @@ audit_run_file() {
   TOTAL_PASS=0
   TOTAL_FAIL=0
 
-  while IFS= read -r line; do
+  # `|| [[ -n "$line" ]]` is required: read returns non-zero on a final line
+  # with no trailing newline, so without this a feature file not ending in \n
+  # silently drops its last step — confirmed on karpathy.feature, whose last
+  # line ("And I should push back on unnecessary complexity") never appeared
+  # in [STEP] output at all.
+  while IFS= read -r line || [[ -n "$line" ]]; do
     line=$(echo "$line" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
 
     if [[ "$line" =~ ^Feature: ]]; then
       CURRENT_FEATURE="${line#Feature: }"
       echo "FEATURE: $CURRENT_FEATURE"
       echo "## Feature: $CURRENT_FEATURE" >> "$REPORT_FILE"
+    elif [[ "$line" =~ ^Background: ]]; then
+      # A Background's Given/And lines must execute the same as a Scenario's —
+      # without this branch IN_SCENARIO never goes true here, so every step
+      # under Background is silently skipped (not FAILed, not counted at all).
+      # Runs once per file, matching how every other line here executes once
+      # as encountered — not true per-scenario Gherkin re-execution semantics.
+      IN_SCENARIO=true
+      CURRENT_SCENARIO="Background"
     elif [[ "$line" =~ ^Scenario: ]]; then
       CURRENT_SCENARIO="${line#Scenario: }"
       if [[ -n "$SCENARIO_FILTER" && "$CURRENT_SCENARIO" != "$SCENARIO_FILTER" ]]; then

package/scripts/lib/golden-suite-gates.sh

@@ -19,10 +19,50 @@ GOLDEN_GATES=(
   # first so a vacuous gate is caught before its verdict is trusted.
   "g12-status-selftest:bash scripts/golden-g12-status-consistency.sh --self-test:false"
   "g12-status-consistency:bash scripts/golden-g12-status-consistency.sh:false"
-  # Anti-vacuity for the target-contract seam: every contract declared in
-  # targets.yaml must have a real assertion, and an unknown contract must FAIL
-  # rather than SKIP+exit 0 (seven contracts were fail-open before this).
+  # audit-compliance-runner.sh silently dropped a Background: step and a
+  # feature file's last line when it had no trailing newline — a step exists,
+  # is correct, and never runs is exactly this session's recurring defect
+  # class. Fixture-based regression guard for both, plus a check that a fix
+  # to "make steps execute" doesn't also make a genuinely failing step report
+  # as PASS.
+  "g15-compliance-runner-selftest:bash scripts/golden-g15-compliance-runner-selftest.sh --self-test:false"
+  "g15-compliance-runner:bash scripts/golden-g15-compliance-runner-selftest.sh:false"
+  # Writing a script must be enough to make it run: G-13 fails if any
+  # scripts/*.sh is absent, unreferenced, and untagged bp-manual-utility.
+  # Broadened from scripts/test-*.sh only after a catalog-wide review found 9
+  # more orphans among non-test scripts; renamed to match (golden-g13-test-
+  # orphans.sh -> golden-g13-script-orphans.sh).
+  "g13-script-orphans-selftest:bash scripts/golden-g13-script-orphans.sh --self-test:false"
+  "g13-script-orphans:bash scripts/golden-g13-script-orphans.sh:false"
+  # An adapter that defines render_skill() must be dispatched by targets.yaml,
+  # or sync renders nothing for it while its install still claims success.
+  # docs/WORKFLOWS.md is generated from specs/workflows/*.yaml; a diagram nothing
+  # regenerates is a diagram that lies (see specs/archive/assets/README.md).
+  "workflow-diagrams-fresh:bash scripts/generate-workflow-diagrams.sh --check:false"
+  # REFERENCE.md nav tables are line-number indexes; hand-maintained they drift
+  # the moment a section grows (all 10 were stale when this gate was added).
+  "reference-nav-fresh:bash scripts/generate-reference-nav.sh --check:false"
+  "g14-adapter-dispatch-selftest:bash scripts/golden-g14-adapter-dispatch.sh --self-test:false"
+  "g14-adapter-dispatch:bash scripts/golden-g14-adapter-dispatch.sh:false"
+  # check-spec-version-gap.sh is a fully-formed SoT-drift detector for
+  # consuming projects but had no gate of its own (G-13 orphan). Self-checking
+  # bigpowers' own repo against its own package.json is the natural gate.
+  "g16-spec-version-gap-selftest:bash scripts/golden-g16-spec-version-gap.sh --self-test:false"
+  "g16-spec-version-gap:bash scripts/golden-g16-spec-version-gap.sh:false"
   "target-contracts:bash scripts/test-target-contracts.sh:false"
+  # Registry-driven replacements for the 25 hand-written per-target scripts.
+  "install-hub:bash scripts/test-install-hub.sh:false"
+  "adapter-render:bash scripts/test-adapter-render.sh:false"
+  "adapters:bash scripts/test-adapters.sh:false"
+  # Previously orphaned: present in scripts/ but reachable from no gate.
+  "tombstone-mechanism:bash scripts/test-tombstone-mechanism.sh:false"
+  "trace-strict:bash scripts/test-trace-strict.sh:false"
+  "trace-matrix-size:bash scripts/test-trace-matrix-size.sh:false"
+  "setup-no-pyyaml:bash scripts/test-setup-no-pyyaml.sh:false"
+  "install-distribute-only:bash scripts/test-install-distribute-only.sh:false"
+  "completeness-critic-scope:bash scripts/test-completeness-critic-scope.sh:false"
+  "epics-wiki-zero-stories:bash scripts/test-generate-epics-wiki-zero-stories.sh:false"
+  "golden-g11-worktree-venv:bash scripts/test-golden-g11-worktree-venv.sh:false"
   "install-helpers:bash scripts/test-install-helpers.sh:false"
   "import-boundaries:bash scripts/check-import-boundaries.sh:false"
   "skill-catalog:bash scripts/validate-skill-catalog.sh:false"