bigpowers 2.86.6 → 2.86.7

package/.zcode/skills/validate-contracts/SKILL.md

@@ -87,12 +87,21 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–24 | Integration |
-| 26–35 | Configuration |
-| 37–46 | Verification |
-| 48–170 | Reference blocks + Examples 1–6 |
-| 172–190 | Integration (duplicate) + Configuration + Verification |
+| 3–23 | Navigation |
+| 24–32 | Integration |
+| 33–44 | Configuration |
+| 45–54 | Verification |
+| 55–71 | Reference block 1 |
+| 72–92 | Reference block 2 |
+| 93–104 | Example 1 |
+| 105–121 | Example 2 |
+| 122–133 | Example 3 |
+| 134–144 | Example 4 |
+| 145–165 | Example 5 |
+| 166–176 | Example 6 |
+| 177–185 | Integration |
+| 186–197 | Configuration |
+| 198–204 | Verification |
 
 ## Integration
 

package/.zcode/skills/wire-ci/SKILL.md

@@ -118,11 +118,18 @@ See [REFERENCE.md](REFERENCE.md).
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–14 | Navigation |
-| 16–38 | Examples |
-| 40–52 | Options |
-| 54–62 | Integration with build-epic |
-| 64–270 | Reference blocks 1–8 |
+| 3–20 | Navigation |
+| 21–22 | Examples |
+| 23–39 | Create CI for a Go project (TBR + optional deploy) |
+| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
+| 50–57 | Validate existing workflows (no generation) |
+| 58–70 | Options |
+| 71–79 | Integration with build-epic |
+| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
+| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
+| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
+| 233–257 | Reference block 4 — validate script |
+| 258–268 | Reference block 5 — dry-run |
 
 ## Examples
 

package/.zcode/skills/write-document/SKILL.md

@@ -86,10 +86,36 @@ Combined from dbader/readme-template and jehna/readme-best-practices. No TOC.
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 5–16 | Navigation |
-| 18–24 | Sections intro |
-| 26–178 | README section templates (1–15) |
-| 180–183 | Verify |
+| 5–40 | Navigation |
+| 41–42 | Sections |
+| 43–54 | 1. Title + Badges |
+| 55–60 | 2. Tagline |
+| 61–64 | 3. Description |
+| 65–67 | 4. Prerequisites |
+| 68–75 | Prerequisites |
+| 76–78 | 5. Installation |
+| 79–89 | Installation |
+| 90–92 | 6. Usage |
+| 93–102 | Usage |
+| 103–105 | 7. Features |
+| 106–113 | Features |
+| 114–116 | 8. Configuration |
+| 117–125 | Configuration |
+| 126–128 | 9. Development Setup |
+| 129–139 | Development |
+| 140–142 | 10. Running Tests |
+| 143–152 | Tests |
+| 153–155 | 11. Contributing |
+| 156–164 | Contributing |
+| 165–167 | 12. Changelog |
+| 168–172 | Changelog |
+| 173–175 | 13. Links |
+| 176–181 | Links |
+| 182–184 | 14. License |
+| 185–191 | License |
+| 192–194 | 15. Credits (optional) |
+| 195–199 | Credits |
+| 200–202 | Verify |
 
 ## Sections
 

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [2.86.7](https://github.com/danielvm-git/bigpowers/compare/v2.86.6...v2.86.7) (2026-07-28)
+
+
+### Bug Fixes
+
+* **verify:** close the compliance margin and orphan-script risk ([e95c86a](https://github.com/danielvm-git/bigpowers/commit/e95c86aeb5808642c4fb94d280b4fd4777c0d6db))
+
 ## [2.86.6](https://github.com/danielvm-git/bigpowers/compare/v2.86.5...v2.86.6) (2026-07-26)
 
 

package/CONVENTIONS.md

@@ -380,6 +380,8 @@ name must return < 5 results across the repo.
 | `visual-dashboard` | adjective-noun | `view-dashboard` implies read-only; `show-dashboard` collides with `show` verbs |
 | `deploy` | single verb | Well-known DevOps single-word concept; renames like `deploy-app` or `deploy-service` are redundant since deploy always targets an application |
 | `grill-with-docs` | three-word verb-prep-noun | Variant of `grill-me`; the `-with-docs` suffix is the distinguishing feature — collapsing it would hide the doc-grounded contract |
+| `context7-mcp` | noun-noun (product + protocol) | Names the external service and protocol it fronts; a verb-noun rename (`fetch-docs`) would collide with generic doc-fetch skills and hide which provider is used |
+| `generate-allure-report` | three-word verb-noun-noun | `generate-report` is ambiguous across report types; `allure` names the specific output format consumers integrate with |
 
 Any new exception requires an entry in this table before the skill is published.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.86.6",
+  "version": "2.86.7",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/generate-context-bundle.sh

@@ -1,6 +1,12 @@
 #!/usr/bin/env bash
 # story: e37s06
 # scenario: SC-e37s06-P1-01
+# bp-manual-utility: ADR-0007/tech-stack.md document this as the post-seed
+# context-wiring step, but seed-conventions never invokes it — a real
+# "documented, never executed" gap. Not fixed here: wiring it into
+# seed-conventions changes that skill's actual output, which needs its own
+# investigate-bug pass and verification, not a silent bundle into a
+# compliance-margin PR. Run manually: bash scripts/generate-context-bundle.sh
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

package/scripts/generate-reference-nav.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# story: e45s02
+# generate-reference-nav.sh — rebuild the "| Lines | Section |" nav table at the
+# top of each skills/*/REFERENCE.md from the file's actual headings.
+#
+# These tables are a token-economy aid: they let an agent jump to a line range
+# instead of reading the whole file. Hand-maintained, they drift the moment any
+# section grows — at the time this was written, 4 of 10 cited a line number past
+# end-of-file, so the index pointed past the document it indexed.
+#
+# Usage: bash scripts/generate-reference-nav.sh [--check]
+#   --check  fail if any committed nav table is stale (for CI)
+
+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"
+
+MODE="${1:-write}"
+
+$PYTHON - "$MODE" <<'PY'
+import sys, glob, re
+
+mode = sys.argv[1]
+stale, rewritten = [], []
+
+def rebuild(lines):
+    """One pass: replace the nav table with ranges derived from the headings."""
+    hdr = next((i for i, l in enumerate(lines) if l.strip() == "| Lines | Section |"), None)
+    if hdr is None:
+        return None
+    end = hdr + 2
+    while end < len(lines) and lines[end].startswith("|"):
+        end += 1
+
+    # Section boundaries come from ## / ### headings; the title is line 1.
+    heads = [(i + 1, l) for i, l in enumerate(lines) if re.match(r"^#{2,3} ", l)]
+    # "## Navigation" is itself a heading — do not synthesize a second row for it.
+    rows = ["| Lines | Section |", "|-------|---------|", "| 1 | Title |"]
+    # split("\n") on a trailing newline yields one extra empty element; the real
+    # last line is the last non-empty index.
+    last = len(lines)
+    while last > 0 and lines[last - 1] == "":
+        last -= 1
+    for idx, (ln, text) in enumerate(heads):
+        nxt = heads[idx + 1][0] - 1 if idx + 1 < len(heads) else last
+        name = re.sub(r"^#{2,3} ", "", text).strip()
+        rows.append("| %d–%d | %s |" % (ln, nxt, name))
+    return lines[:hdr] + rows + lines[end:]
+
+
+for path in sorted(glob.glob("skills/*/REFERENCE.md")):
+    original = open(path, encoding="utf-8").read().split("\n")
+
+    # Rewriting the table changes the line numbers the table reports, so iterate
+    # to a fixed point rather than assuming one pass converges.
+    lines = original
+    for _ in range(10):
+        nxt = rebuild(lines)
+        if nxt is None or nxt == lines:
+            break
+        lines = nxt
+    if lines is None:
+        continue
+
+    new = lines
+    if new == original:
+        continue
+    lines = original  # keep the staleness comparison against what is committed
+    if mode == "--check":
+        stale.append(path)
+    else:
+        open(path, "w", encoding="utf-8").write("\n".join(new))
+        rewritten.append(path)
+
+if mode == "--check":
+    if stale:
+        print("generate-reference-nav: stale nav table(s):", file=sys.stderr)
+        for s in stale:
+            print("  %s" % s, file=sys.stderr)
+        print("run: bash scripts/generate-reference-nav.sh", file=sys.stderr)
+        sys.exit(1)
+    print("generate-reference-nav: all nav tables current")
+else:
+    for r in rewritten:
+        print("  rebuilt %s" % r)
+    print("generate-reference-nav: %d table(s) rebuilt" % len(rewritten))
+PY

package/scripts/generate-viz-graph.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 # story: e45s04
 # generate-viz-graph.sh — build specs/viz.html from bigpowers-mcp/graph.jsonl
+# bp-manual-utility: on-demand report generator; nothing else depends on
+# viz.html's freshness the way generate-workflow-diagrams.sh/
+# generate-reference-nav.sh are --check-gated. Run manually after graph.jsonl
+# changes: bash scripts/generate-viz-graph.sh
 set -euo pipefail
 source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

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-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/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
 }