bigpowers 2.86.6 → 2.86.8

package/.zcode/skills/seed-conventions/SKILL.md

@@ -128,16 +128,26 @@ Emit these fences in `AGENTS.md` (and therefore `CLAUDE.md` symlink) from `docs/
 
 | Lines | Section |
 |-------|---------|
-| 1–4 | Title + story tags |
-| 6–22 | Navigation (this table) |
-| 24–35 | AGENTS.md spine |
-| 37–76 | Agent config template |
-| 78–85 | opencode.json template |
-| 87–96 | Aider bridge |
-| 98–108 | Codex CLI wiring |
-| 110–118 | CONVENTIONS.md |
-| 120–122 | Stack profile fragments |
-| 124–153 | Local tool wiring |
+| 1 | Title |
+| 5–29 | Navigation |
+| 30–53 | Fenced markers (e45s21) |
+| 54–65 | AGENTS.md spine (Reach Template — e37s01) |
+| 66–77 | Agent config template (legacy — prefer AGENTS.md spine) |
+| 78–81 | Project |
+| 82–91 | Commands |
+| 92–94 | Architecture |
+| 95–98 | Conventions |
+| 99–104 | Never |
+| 105–114 | Agent Rules |
+| 115–123 | opencode.json template |
+| 124–133 | Aider — `.aider.conf.yml` bridge (e37s03) |
+| 134–146 | Codex CLI — project-local `.codex/config.toml` + AGENTS.md (e37s14) |
+| 147–156 | CONVENTIONS.md |
+| 157–160 | Stack profile fragments |
+| 161–164 | Local tool wiring (optional interview step 8) |
+| 165–173 | Cursor — project-local `.cursor/rules` symlink |
+| 174–187 | OpenCode — project-local `opencode.json` + `AGENTS.md` |
+| 188–190 | When to offer |
 
 ## Fenced markers (e45s21)
 

package/.zcode/skills/smoke-test/SKILL.md

@@ -89,11 +89,15 @@ Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-te
 | Lines | Section |
 |-------|---------|
 | 1 | Title |
-| 3–12 | Navigation |
-| 14–31 | Runner script |
-| 33–42 | Configuration reference |
-| 44–53 | Verification |
-| 55–160 | Reference blocks 1–5 |
+| 3–17 | Navigation |
+| 18–34 | Runner script |
+| 35–46 | Configuration reference |
+| 47–55 | Verification |
+| 56–89 | Reference block 1 |
+| 90–107 | Reference block 2 |
+| 108–122 | Reference block 3 |
+| 123–159 | Reference block 4 |
+| 160–177 | Reference block 5 |
 
 ## Runner script
 

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

@@ -47,7 +47,7 @@ Write the document focusing on "Expert Collaboration":
 
 1. Ask: "Project name? One-sentence description?"
 2. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round.
-3. Fill gaps from `CLAUDE.md` commands if available; use `TODO` markers otherwise.
+3. Fill gaps from `CLAUDE.md` / `AGENTS.md` commands if available (prefer `AGENTS.md`); use `TODO` markers otherwise.
 4. Output and suggest `edit-document` for polish.
 
 → verify: `test -f README.md && [ "$(grep -c '^## ' README.md)" -ge 7 ]`
@@ -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,18 @@
+## [2.86.8](https://github.com/danielvm-git/bigpowers/compare/v2.86.7...v2.86.8) (2026-07-28)
+
+
+### Bug Fixes
+
+* **scripts:** replace hardcoded owner URL in check-skill-links.py ([4cb8b35](https://github.com/danielvm-git/bigpowers/commit/4cb8b351e780a14aa522a7b3156a9e32477b0f4c))
+* **skills:** add AGENTS.md fallback to context-bootstrap skills ([8e44d4d](https://github.com/danielvm-git/bigpowers/commit/8e44d4d6c9810589d06166665a68f11d65311997))
+
+## [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.8",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/check-skill-links.py

@@ -7,7 +7,8 @@
 # Those trees are auto-generated from SKILL.md sources via sync-skills.sh and
 # are not published to npm, so dangling links there are a rendering gap, not a
 # source defect. Enable once the sync pipeline gains link-rewriting support.
-# See: https://github.com/danielvm-git/bigpowers/issues/78
+# Placeholder — replace with the project's own issue tracker URL.
+# See: https://github.com/OWNER/REPO/issues/78
 import glob
 import os
 import sys

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