bigpowers 2.55.0 → 2.56.0

package/.pi/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.55.0",
-  "description": "72 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
+  "version": "2.56.0",
+  "description": "73 skills — 72 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"
   ],

package/.pi/prompts/gate-trace.md

@@ -0,0 +1,79 @@
+---
+description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability."# story: e38s06
+---
+
+
+# Gate Trace
+
+Deterministic quality gate that combines traceability coverage and blind-spot data into a single PASS/FAIL/CONCERNS/WAIVED decision before release.
+
+## Decision Rules
+
+| Rule | Condition | Verdict |
+|------|-----------|---------|
+| R1 | Any undone story with 0 code tags | FAIL |
+| R2 | Any story done but no verify evidence | CONCERNS |
+| R3 | P0 story (top WSJF quartile) with 0% coverage | FAIL |
+| R4 | Overall coverage < 60% | CONCERNS |
+| R5 | Overall ≥ 80% + no critical gaps + all verify → PASS | PASS |
+
+## Oracle Confidence Downgrade
+
+TEA-inspired: if trace links rely on heuristics rather than explicit tags, confidence drops.
+
+| Heuristic Ratio | Downgrade |
+|-----------------|-----------|
+| > 50% links from heuristics (file-name or task-reference) | One level (PASS→CONCERNS, CONCERNS→FAIL) |
+| > 80% links from heuristics | Two levels (PASS→FAIL, CONCERNS→FAIL) |
+
+## Process
+
+1. **Pre-flight:** Ensure `scripts/trace-stories.sh --json` has been run (produces `specs/traceability-matrix.json`). If not present, run it.
+2. Ensure `scripts/check-blind-spots.sh` has been run (produces `specs/blind-spots.json`). If not present, run it.
+3. Read `specs/traceability-matrix.json` and `specs/blind-spots.json`.
+4. Apply decision rules R1–R5 in order (first match wins).
+5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`.
+6. Output verdict + rationale to stdout.
+7. Update `specs/execution-status.yaml` with gate-trace result.
+
+## Verdict Semantics
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| PASS | All gates satisfied | Proceed with merge |
+| CONCERNS | Non-critical issues found | Requires explicit human override in `state.yaml` |
+| FAIL | Critical traceability gap | Block merge — fix gap first |
+| WAIVED | Cannot evaluate (missing inputs) | Skip gate — data not available |
+
+## Output Format
+
+```yaml
+gate_trace:
+  verdict: PASS|CONCERNS|FAIL|WAIVED
+  generated_at: "<ISO 8601>"
+  rationale: "<human-readable explanation>"
+  heuristic_ratio: <0.0–1.0>
+  downgrade_applied: <true|false>
+```
+
+## Integration Points
+
+- **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
+- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
+
+## References
+
+- BMAD TEA traceability approach (market survey 2026-07-02).
+- scripts/trace-stories.sh (e38s01) — produces traceability-matrix.json.
+- scripts/check-blind-spots.sh (e38s04) — produces blind-spots.json.
+- specs/execution-status.yaml — output target for gate result.
+
+## Verify
+
+→ verify: `test -f skills/gate-trace/SKILL.md && grep -q 'PASS.*CONCERNS.*FAIL.*WAIVED' skills/gate-trace/SKILL.md && echo "OK: gate-trace skill created" || echo "FAIL"`
+
+## Handoff
+
+Gate: READY → next: release-branch (final step before merge)
+Writes: state.yaml handoff.next_skill = release-branch

package/.pi/prompts/release-branch.md

@@ -11,21 +11,19 @@ Finalize a completed feature branch: verify coverage gates, integrate onto `main
 
 ## Additional modes
 
-- `--hotfix`: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
-- `--squash-state`: Squashes all intermediate `chore(state):` commits on the feature branch into a single clean commit before merging. Use this to reduce noise in the main git repository history.
+- `--hotfix`: Cherry-pick to main + tag. Skip PR in solo.
+- `--squash-state`: Squash `chore(state):` commits before merge.
 
 ## Integrate mode
 
-Read `specs/state.yaml` key `workflow_mode` first (`team-pr` | `solo-git`). Fall back to sniffing `profiles/solo-git.md` only when the key is absent.
+Read `specs/state.yaml` key `workflow_mode` (`team-pr` | `solo-git`). Fall back to `profiles/solo-git.md`.
 
 | Mode | When | Ship path |
 |------|------|-----------|
-| **solo-local** | `workflow_mode: solo-git` (or `profiles/solo-git.md` present as fallback) | Auto-detect: if `scripts/land-branch.sh` exists → use it; else → fallback (see Step 5) |
+| **solo-local** | `workflow_mode: solo-git` | Auto: `scripts/land-branch.sh` if present, else fallback (Step 5) |
 | **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
 
-If unsure and working alone, prefer **solo-local**.
-
-> **Auto-detect note:** The solo-local path first checks if `scripts/land-branch.sh` exists and is executable. If present, the script handles the full squash-merge workflow. If absent, the built-in fallback sequence runs instead.
+If unsure, prefer **solo-local**.
 
 ## Process
 
@@ -51,6 +49,10 @@ git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refact
 
 If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
 
+### 2b. Traceability gate
+
+Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
+
 ### 3. Diff review
 
 - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
@@ -61,20 +63,14 @@ Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
 
 ### 5. Solo-local integrate
 
-Run `commit-message` to produce the squash commit subject. Then auto-detect the integration path:
+Run `commit-message` for the squash subject, then land:
 
-**Path A — `scripts/land-branch.sh` exists (happy path):**
 ```bash
+# Path A (preferred):
 bash scripts/land-branch.sh <task-slug> "feat(scope): description"
+# Path B (fallback if land-branch.sh missing): see REFERENCE.md
 ```
 
-**Path B — `scripts/land-branch.sh` missing (fallback):**
-See [REFERENCE.md](REFERENCE.md)
-
-**Report which path was taken.** Print exactly:
-- `"used land-branch.sh"` if Path A
-- `"used fallback merge (land-branch.sh not found)"` if Path B
-
 ### 6. Create PR (team-pr only)
 
 See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.

package/.pi/prompts/verify-work.md

@@ -34,6 +34,7 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 3. **AGENTS.md preflight** — before running default checks, call `bash scripts/bp-read-agents.sh` to detect project-specific commands. If `BP_PREFLIGHT` is set, run it instead of the default mechanical gates (or in addition to them if the project requires both). Output: `"Using preflight from AGENTS.md: <cmd>"`. Fall back to `CLAUDE.md` commands if AGENTS.md is absent.
 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md).
 5. **Security scan** — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
+5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
 6. **Step-by-step UAT** — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 

package/.pi/skills/gate-trace/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gate-trace
+description: "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"# story: e38s06"
+model: haiku
+---
+
+
+# Gate Trace
+
+Deterministic quality gate that combines traceability coverage and blind-spot data into a single PASS/FAIL/CONCERNS/WAIVED decision before release.
+
+## Decision Rules
+
+| Rule | Condition | Verdict |
+|------|-----------|---------|
+| R1 | Any undone story with 0 code tags | FAIL |
+| R2 | Any story done but no verify evidence | CONCERNS |
+| R3 | P0 story (top WSJF quartile) with 0% coverage | FAIL |
+| R4 | Overall coverage < 60% | CONCERNS |
+| R5 | Overall ≥ 80% + no critical gaps + all verify → PASS | PASS |
+
+## Oracle Confidence Downgrade
+
+TEA-inspired: if trace links rely on heuristics rather than explicit tags, confidence drops.
+
+| Heuristic Ratio | Downgrade |
+|-----------------|-----------|
+| > 50% links from heuristics (file-name or task-reference) | One level (PASS→CONCERNS, CONCERNS→FAIL) |
+| > 80% links from heuristics | Two levels (PASS→FAIL, CONCERNS→FAIL) |
+
+## Process
+
+1. **Pre-flight:** Ensure `scripts/trace-stories.sh --json` has been run (produces `specs/traceability-matrix.json`). If not present, run it.
+2. Ensure `scripts/check-blind-spots.sh` has been run (produces `specs/blind-spots.json`). If not present, run it.
+3. Read `specs/traceability-matrix.json` and `specs/blind-spots.json`.
+4. Apply decision rules R1–R5 in order (first match wins).
+5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`.
+6. Output verdict + rationale to stdout.
+7. Update `specs/execution-status.yaml` with gate-trace result.
+
+## Verdict Semantics
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| PASS | All gates satisfied | Proceed with merge |
+| CONCERNS | Non-critical issues found | Requires explicit human override in `state.yaml` |
+| FAIL | Critical traceability gap | Block merge — fix gap first |
+| WAIVED | Cannot evaluate (missing inputs) | Skip gate — data not available |
+
+## Output Format
+
+```yaml
+gate_trace:
+  verdict: PASS|CONCERNS|FAIL|WAIVED
+  generated_at: "<ISO 8601>"
+  rationale: "<human-readable explanation>"
+  heuristic_ratio: <0.0–1.0>
+  downgrade_applied: <true|false>
+```
+
+## Integration Points
+
+- **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
+- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
+
+## References
+
+- BMAD TEA traceability approach (market survey 2026-07-02).
+- scripts/trace-stories.sh (e38s01) — produces traceability-matrix.json.
+- scripts/check-blind-spots.sh (e38s04) — produces blind-spots.json.
+- specs/execution-status.yaml — output target for gate result.
+
+## Verify
+
+→ verify: `test -f skills/gate-trace/SKILL.md && grep -q 'PASS.*CONCERNS.*FAIL.*WAIVED' skills/gate-trace/SKILL.md && echo "OK: gate-trace skill created" || echo "FAIL"`
+
+## Handoff
+
+Gate: READY → next: release-branch (final step before merge)
+Writes: state.yaml handoff.next_skill = release-branch

package/.pi/skills/release-branch/SKILL.md

@@ -13,21 +13,19 @@ Finalize a completed feature branch: verify coverage gates, integrate onto `main
 
 ## Additional modes
 
-- `--hotfix`: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
-- `--squash-state`: Squashes all intermediate `chore(state):` commits on the feature branch into a single clean commit before merging. Use this to reduce noise in the main git repository history.
+- `--hotfix`: Cherry-pick to main + tag. Skip PR in solo.
+- `--squash-state`: Squash `chore(state):` commits before merge.
 
 ## Integrate mode
 
-Read `specs/state.yaml` key `workflow_mode` first (`team-pr` | `solo-git`). Fall back to sniffing `profiles/solo-git.md` only when the key is absent.
+Read `specs/state.yaml` key `workflow_mode` (`team-pr` | `solo-git`). Fall back to `profiles/solo-git.md`.
 
 | Mode | When | Ship path |
 |------|------|-----------|
-| **solo-local** | `workflow_mode: solo-git` (or `profiles/solo-git.md` present as fallback) | Auto-detect: if `scripts/land-branch.sh` exists → use it; else → fallback (see Step 5) |
+| **solo-local** | `workflow_mode: solo-git` | Auto: `scripts/land-branch.sh` if present, else fallback (Step 5) |
 | **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
 
-If unsure and working alone, prefer **solo-local**.
-
-> **Auto-detect note:** The solo-local path first checks if `scripts/land-branch.sh` exists and is executable. If present, the script handles the full squash-merge workflow. If absent, the built-in fallback sequence runs instead.
+If unsure, prefer **solo-local**.
 
 ## Process
 
@@ -53,6 +51,10 @@ git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refact
 
 If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
 
+### 2b. Traceability gate
+
+Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
+
 ### 3. Diff review
 
 - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
@@ -63,20 +65,14 @@ Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
 
 ### 5. Solo-local integrate
 
-Run `commit-message` to produce the squash commit subject. Then auto-detect the integration path:
+Run `commit-message` for the squash subject, then land:
 
-**Path A — `scripts/land-branch.sh` exists (happy path):**
 ```bash
+# Path A (preferred):
 bash scripts/land-branch.sh <task-slug> "feat(scope): description"
+# Path B (fallback if land-branch.sh missing): see REFERENCE.md
 ```
 
-**Path B — `scripts/land-branch.sh` missing (fallback):**
-See [REFERENCE.md](REFERENCE.md)
-
-**Report which path was taken.** Print exactly:
-- `"used land-branch.sh"` if Path A
-- `"used fallback merge (land-branch.sh not found)"` if Path B
-
 ### 6. Create PR (team-pr only)
 
 See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.

package/.pi/skills/verify-work/SKILL.md

@@ -36,6 +36,7 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 3. **AGENTS.md preflight** — before running default checks, call `bash scripts/bp-read-agents.sh` to detect project-specific commands. If `BP_PREFLIGHT` is set, run it instead of the default mechanical gates (or in addition to them if the project requires both). Output: `"Using preflight from AGENTS.md: <cmd>"`. Fall back to `CLAUDE.md` commands if AGENTS.md is absent.
 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md).
 5. **Security scan** — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
+5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
 6. **Step-by-step UAT** — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [2.56.0](https://github.com/danielvm-git/bigpowers/compare/v2.55.0...v2.56.0) (2026-07-03)
+
+
+### Bug Fixes
+
+* trim release-branch SKILL.md to 146 lines (cap 150) ([6c91813](https://github.com/danielvm-git/bigpowers/commit/6c91813012ce64b3e0fa90f3c11afa5b67559d9c))
+
+
+### Features
+
+* **e38:** spec-to-code traceability gate — matrix, blind-spots, CI/CD integration ([ffeb843](https://github.com/danielvm-git/bigpowers/commit/ffeb8435a91ad2d278a490670bf2f1561df60135))
+
 # [2.55.0](https://github.com/danielvm-git/bigpowers/compare/v2.54.0...v2.55.0) (2026-07-03)
 
 

package/CLAUDE.md

@@ -1,3 +1,5 @@
+# story: e38s08
+
 # bigpowers — Claude Code
 
 Read CONVENTIONS.md before any GitHub or git operation.
@@ -21,6 +23,7 @@ Stack: Markdown / Bash (documentation-based; skills integrate with Claude Code,
 | CI platform | GitHub Actions (`.github/workflows/publish.yml`, `sync-skills.yml`) |
 | Compliance | `npm run compliance` |
 | Golden Suite | `bash scripts/run-golden-suite.sh` |
+| Traceability | `bash scripts/trace-stories.sh --strict` | grep for story tags (traceability check) |
 
 ### Pre-Merge Checklist
 

package/CONVENTIONS.md

@@ -1,3 +1,5 @@
+# story: e38s08
+
 # Conventions
 
 ## Conventional Commits & Semantic Versioning
@@ -51,6 +53,7 @@ You are operating within the `bigpowers` spec-driven development methodology.
   - Use `investigate-bug` for bug reports before writing a fix.
 - **Verification Mandate:** Every story implementation MUST end with a step-by-step manual verification script provided to the user. You must wait for the user to confirm behavioral correctness (UAT) before declaring the story done or moving to the next.
 - **Verification:** You MUST verify every change with tests. Code generation without a corresponding plan in `specs/` is strictly forbidden.
+- **Traceability Mandate:** Every story MUST have at least one `story: eNNsNN` tag in its implementing code or test file. `trace-stories.sh --strict` runs in CI to enforce this. Untagged stories fail the CI traceability gate.
 - **Stream Continuity:** When writing large files or long documents, you MUST output continuously in chunks of ~200 lines. Do not pause between sections. Continue immediately until complete. If you need time to process, emit a placeholder comment or heading rather than going silent to prevent stream idle timeouts.
 
 ## specs/ — All Planning Output Goes Here

package/README.md

@@ -2,7 +2,7 @@
 
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![npm version](https://img.shields.io/npm/v/bigpowers.svg)
-![Skills](https://img.shields.io/badge/skills-72-brightgreen.svg)
+![Skills](https://img.shields.io/badge/skills-73-brightgreen.svg)
 
 **Agent skills synthesizing 17 years of software engineering discipline — from Clean Code to AI-native architecture — into a single, prescriptive methodology for solo developers.**
 

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Skills:** 72
+**Skills:** 73
 
 ---
 

package/package.json

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

package/scripts/check-blind-spots.sh

@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+# story: e38s04
+# check-blind-spots.sh — TEA-inspired heuristic blind-spot detector
+# Reads execution-status.yaml + traceability-matrix.json, runs 6 structural
+# quality checks beyond percentage coverage, and emits specs/blind-spots.json.
+#
+# Checks:
+#   a. verify-gap       — story done but no verification evidence
+#   b. test-gap          — code tagged but no test file references
+#   c. epic-orphan       — capsule task with no story tag anywhere
+#   d. stale-tag         — story done but tag still in code
+#   e. double-tag        — same file tagged with multiple stories
+#   f. bootstrap-testless — new story without test-related tag or files
+#
+# Severities: HIGH / MEDIUM / LOW
+#
+# Usage:
+#   bash scripts/check-blind-spots.sh            # full scan, emit JSON
+#   bash scripts/check-blind-spots.sh --help     # this message
+#
+# Exit codes:
+#   0 — no HIGH-severity findings
+#   1 — one or more HIGH-severity findings (or input files missing)
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BLIND_SPOTS_JSON="$REPO_ROOT/specs/blind-spots.json"
+EXEC_STATUS="$REPO_ROOT/specs/execution-status.yaml"
+MATRIX_JSON="$REPO_ROOT/specs/traceability-matrix.json"
+VERIFICATIONS_DIR="$REPO_ROOT/specs/verifications"
+EPICS_DIR="$REPO_ROOT/specs/epics"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --help|-h)
+      cat <<'USAGE'
+Usage: check-blind-spots.sh [flags]
+
+Run 6 heuristic blind-spot checks on the codebase.
+
+Flags:
+  --help   Print this message and exit.
+
+Checks:
+  verify-gap        Story done, no verify evidence.
+  test-gap          Code tagged, no test file references.
+  epic-orphan       Capsule task with no story tag.
+  stale-tag         Done story, tag still in code.
+  double-tag        File tagged with multiple stories.
+  bootstrap-testless New story without test coverage.
+
+Output: specs/blind-spots.json
+
+Exit codes:
+  0  No HIGH-severity findings.
+  1  One or more HIGH-severity findings (or input files missing).
+USAGE
+      exit 0
+      ;;
+    *)
+      echo "check-blind-spots.sh: unknown flag: $1" >&2
+      echo "Try --help for usage." >&2
+      exit 1
+      ;;
+  esac
+done
+
+# ---------------------------------------------------------------------------
+# Input existence checks
+# ---------------------------------------------------------------------------
+if [[ ! -f "$EXEC_STATUS" ]]; then
+  echo "check-blind-spots.sh: execution-status.yaml: not found at $EXEC_STATUS" >&2
+  exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Detector logic (Python stdlib only)
+# ---------------------------------------------------------------------------
+python3 - "$REPO_ROOT" "$BLIND_SPOTS_JSON" "$EXEC_STATUS" "$MATRIX_JSON" "$VERIFICATIONS_DIR" "$EPICS_DIR" <<'PYEOF'
+import json, os, re, sys
+from pathlib import Path
+from datetime import datetime, timezone
+
+ROOT = Path(sys.argv[1])
+BLIND_SPOTS_JSON = Path(sys.argv[2])
+EXEC_STATUS = Path(sys.argv[3])
+MATRIX_JSON = Path(sys.argv[4])
+VERIFICATIONS_DIR = Path(sys.argv[5])
+EPICS_DIR = Path(sys.argv[6])
+
+findings: list[dict] = []
+
+# -----------------------------------------------------------------------
+# Parse execution-status.yaml → flat dict of story_id → status
+# -----------------------------------------------------------------------
+def parse_exec_status(path: Path) -> dict[str, str]:
+    status: dict[str, str] = {}
+    if not path.exists():
+        return status
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    in_dev_status = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("development_status:"):
+            in_dev_status = True
+            continue
+        if not in_dev_status:
+            # Stop if we hit another top-level key
+            if stripped and not stripped.startswith(" ") and not stripped.startswith("#"):
+                if ":" in stripped:
+                    in_dev_status = False
+            continue
+        if ":" in stripped and not stripped.startswith("#"):
+            # Lines like '  e38s04: "done"'
+            m = re.match(r'\s+(\S+):\s*"([^"]*)"', stripped)
+            if m:
+                status[m.group(1)] = m.group(2)
+    return status
+
+dev_status = parse_exec_status(EXEC_STATUS)
+
+# -----------------------------------------------------------------------
+# Read traceability matrix (if available)
+# -----------------------------------------------------------------------
+matrix_data: dict | None = None
+if MATRIX_JSON.exists():
+    matrix_data = json.loads(MATRIX_JSON.read_text(encoding="utf-8"))
+
+# Build indexes from matrix
+tagged_files: dict[str, list[str]] = {}  # story_id → [files]
+file_story_counts: dict[str, set[str]] = {}  # file → set of story_ids
+if matrix_data:
+    for s in matrix_data.get("stories", []):
+        sid = s["id"]
+        for link in s.get("links", []):
+            f = link["file"]
+            tagged_files.setdefault(sid, []).append(f)
+            file_story_counts.setdefault(f, set()).add(sid)
+
+# Enumerate all tracked code files (skip .git, node_modules, specs/)
+CODE_EXTENSIONS = {".sh", ".py", ".js", ".ts", ".jsx", ".tsx", ".md", ".yaml", ".yml", ".cjs", ".mjs", ".json"}
+SKIP_DIRS = {".git", "node_modules", ".cursor", ".gemini", ".pi", "specs", "dist", "build", "__pycache__", ".bigpowers"}
+
+def is_code_file(p: Path) -> bool:
+    return p.suffix in CODE_EXTENSIONS and not any(s in p.parts for s in SKIP_DIRS)
+
+all_code_files: list[str] = []
+for root, dirs, files in os.walk(str(ROOT)):
+    # Prune skip dirs
+    dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+    rel_root = str(Path(root).relative_to(ROOT))
+    for fname in files:
+        fpath = Path(root) / fname
+        if is_code_file(fpath):
+            all_code_files.append(str(fpath.relative_to(ROOT)))
+
+# -----------------------------------------------------------------------
+# Helper: find test files for a given code file
+# -----------------------------------------------------------------------
+TEST_PATTERNS = [
+    re.compile(r"(^|/)test(s)?/", re.IGNORECASE),
+    re.compile(r"(^|/)__tests__/", re.IGNORECASE),
+    re.compile(r"\.test\.", re.IGNORECASE),
+    re.compile(r"\.spec\.", re.IGNORECASE),
+    re.compile(r"_test\.", re.IGNORECASE),
+    re.compile(r"test_", re.IGNORECASE),
+]
+
+def has_test_files(code_files: list[str]) -> bool:
+    """Check if any file in the repo looks like a test for the given code files."""
+    for cf in code_files:
+        cf_path = Path(cf)
+        cf_dir = cf_path.parent
+        cf_stem = cf_path.stem
+        for tf in all_code_files:
+            tp = Path(tf)
+            # Same directory test file
+            if tp.parent == cf_dir:
+                for pat in TEST_PATTERNS:
+                    if pat.search(tp.name) and cf_stem in tp.name:
+                        return True
+            # Tests dir sibling
+            test_dir_names = ["tests", "test", "__tests__"]
+            for tdn in test_dir_names:
+                test_dir = cf_dir / tdn
+                if str(test_dir) in tf:
+                    if cf_stem in tp.name:
+                        return True
+    return False
+
+# -----------------------------------------------------------------------
+# Check A: verify-gap — story done but no verify evidence
+# -----------------------------------------------------------------------
+for sid, sstatus in dev_status.items():
+    if sstatus == "done":
+        verify_file = VERIFICATIONS_DIR / f"{sid}-verify.yaml"
+        if not verify_file.exists():
+            findings.append({
+                "check": "verify-gap",
+                "story_id": sid,
+                "severity": "HIGH",
+                "description": f"Story {sid} is marked done but no verification evidence exists at specs/verifications/{sid}-verify.yaml",
+                "remediation": f"Run verify-work for {sid} or create the verification evidence file"
+            })
+
+# -----------------------------------------------------------------------
+# Check B: test-gap — code tagged but no test file references
+# -----------------------------------------------------------------------
+for sid, files in tagged_files.items():
+    if dev_status.get(sid) in ("done", "active"):
+        if not has_test_files(files):
+            # Only flag if there are actual code files (not just docs)
+            code_only = [f for f in files if Path(f).suffix in {".sh", ".py", ".js", ".ts", ".jsx", ".tsx"} and "SKILL.md" not in f]
+            if code_only:
+                findings.append({
+                    "check": "test-gap",
+                    "story_id": sid,
+                    "severity": "MEDIUM",
+                    "description": f"Story {sid} has {len(code_only)} tagged code file(s) with no matching test files",
+                    "remediation": f"Add test coverage for the tagged files: {', '.join(code_only[:3])}"
+                })
+
+# -----------------------------------------------------------------------
+# Check C: epic-orphan — capsule task with no story tag in any code file
+# -----------------------------------------------------------------------
+if EPICS_DIR.exists():
+    for epic_dir in sorted(EPICS_DIR.iterdir()):
+        if not epic_dir.is_dir() or epic_dir.name == "archive":
+            continue
+        epic_yaml = epic_dir / "epic.yaml"
+        if not epic_yaml.exists():
+            continue
+        # Extract story IDs from epic capsule task files
+        for task_file in sorted(epic_dir.glob("e*[0-9]-tasks.yaml")):
+            # e.g., e38s04-tasks.yaml → e38s04
+            sid_match = re.match(r"(e\d+s\d+)", task_file.name)
+            if not sid_match:
+                continue
+            sid = sid_match.group(1)
+            # Check if story has any tagged files (explicit or heuristic)
+            sstatus = dev_status.get(sid, "backlog")
+            if sstatus in ("done", "active") and sid not in tagged_files:
+                findings.append({
+                    "check": "epic-orphan",
+                    "story_id": sid,
+                    "severity": "LOW",
+                    "description": f"Story {sid} has capsule tasks but no story tags found in any code file",
+                    "remediation": f"Add `// story: {sid}` tags to implementing files"
+                })
+
+# -----------------------------------------------------------------------
+# Check D: stale-tag — story done but tag still in code
+# -----------------------------------------------------------------------
+stale_from_matrix: set[str] = set()
+if matrix_data:
+    stale_from_matrix = set(matrix_data.get("summary", {}).get("stale_tags", []))
+
+for sid in stale_from_matrix:
+    findings.append({
+        "check": "stale-tag",
+        "story_id": sid,
+        "severity": "LOW",
+        "description": f"Story {sid} is marked done but still has story tags in code",
+        "remediation": f"Remove `// story: {sid}` tags from files or confirm the story should remain done"
+    })
+
+# -----------------------------------------------------------------------
+# Check E: double-tag — same file tagged with multiple stories
+# -----------------------------------------------------------------------
+for fpath, sids in file_story_counts.items():
+    if len(sids) > 1:
+        findings.append({
+            "check": "double-tag",
+            "file": fpath,
+            "severity": "MEDIUM",
+            "description": f"File '{fpath}' is tagged with multiple stories: {', '.join(sorted(sids))}",
+            "remediation": "Review whether this file genuinely implements multiple stories. If it's a shared utility, this is acceptable."
+        })
+
+# -----------------------------------------------------------------------
+# Check F: bootstrap-testless — new story (active/recent) without test evidence
+# -----------------------------------------------------------------------
+recent_threshold = 5  # flag active/done stories in the last 5 stories if no tests
+active_and_recent = []
+for sid in sorted(dev_status.keys()):
+    if dev_status[sid] in ("active",):
+        active_and_recent.append(sid)
+
+for sid in active_and_recent:
+    # Check if story has tagged code AND no test files for those
+    if sid in tagged_files:
+        code_files = tagged_files[sid]
+        code_only = [f for f in code_files if Path(f).suffix in {".sh", ".py", ".js", ".ts", ".jsx", ".tsx"} and "SKILL.md" not in f]
+        if code_only and not has_test_files(code_files):
+            findings.append({
+                "check": "bootstrap-testless",
+                "story_id": sid,
+                "severity": "HIGH",
+                "description": f"Active story {sid} has {len(code_only)} tagged code file(s) but no test files detected",
+                "remediation": f"Add test files for: {', '.join(code_only[:3])}"
+            })
+
+# -----------------------------------------------------------------------
+# De-duplicate findings (same check + story_id)
+# -----------------------------------------------------------------------
+seen: set[tuple] = set()
+deduped: list[dict] = []
+for f in findings:
+    key = (f["check"], f.get("story_id", f.get("file", "")))
+    if key not in seen:
+        seen.add(key)
+        deduped.append(f)
+findings = deduped
+
+# -----------------------------------------------------------------------
+# Emit blind-spots.json
+# -----------------------------------------------------------------------
+high_count = sum(1 for f in findings if f["severity"] == "HIGH")
+medium_count = sum(1 for f in findings if f["severity"] == "MEDIUM")
+low_count = sum(1 for f in findings if f["severity"] == "LOW")
+
+blind_spots = {
+    "generated_at": datetime.now(timezone.utc).isoformat(),
+    "version": "1.0",
+    "summary": {
+        "total_findings": len(findings),
+        "high": high_count,
+        "medium": medium_count,
+        "low": low_count
+    },
+    "findings": findings
+}
+
+BLIND_SPOTS_JSON.parent.mkdir(parents=True, exist_ok=True)
+BLIND_SPOTS_JSON.write_text(json.dumps(blind_spots, indent=2), encoding="utf-8")
+
+# Print summary to stdout
+print(f"check-blind-spots.sh: {len(findings)} findings ({high_count} HIGH, {medium_count} MEDIUM, {low_count} LOW)")
+for f in findings:
+    print(f"  [{f['severity']}] {f['check']}: {f['description'][:100]}")
+
+if high_count > 0:
+    print(f"\n⚠️  {high_count} HIGH-severity finding(s) — review specs/blind-spots.json")
+    sys.exit(1)
+
+sys.exit(0)
+PYEOF

package/scripts/trace-stories.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# story: e38s01
 # trace-stories.sh — deterministic spec-to-code coverage matrix builder
 # Parses specs/release-plan.yaml + specs/execution-status.yaml, greps the
 # codebase for story: eNNsNN tags, cross-references, and emits a coverage matrix.

package/skills/build-epic/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: build-epic
+# story: e38s02
 model: sonnet
 effort: standard
 description: Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.

package/skills/gate-trace/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gate-trace
+description: "Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability."
+# story: e38s06
+model: haiku
+effort: light
+---
+
+# Gate Trace
+
+Deterministic quality gate that combines traceability coverage and blind-spot data into a single PASS/FAIL/CONCERNS/WAIVED decision before release.
+
+## Decision Rules
+
+| Rule | Condition | Verdict |
+|------|-----------|---------|
+| R1 | Any undone story with 0 code tags | FAIL |
+| R2 | Any story done but no verify evidence | CONCERNS |
+| R3 | P0 story (top WSJF quartile) with 0% coverage | FAIL |
+| R4 | Overall coverage < 60% | CONCERNS |
+| R5 | Overall ≥ 80% + no critical gaps + all verify → PASS | PASS |
+
+## Oracle Confidence Downgrade
+
+TEA-inspired: if trace links rely on heuristics rather than explicit tags, confidence drops.
+
+| Heuristic Ratio | Downgrade |
+|-----------------|-----------|
+| > 50% links from heuristics (file-name or task-reference) | One level (PASS→CONCERNS, CONCERNS→FAIL) |
+| > 80% links from heuristics | Two levels (PASS→FAIL, CONCERNS→FAIL) |
+
+## Process
+
+1. **Pre-flight:** Ensure `scripts/trace-stories.sh --json` has been run (produces `specs/traceability-matrix.json`). If not present, run it.
+2. Ensure `scripts/check-blind-spots.sh` has been run (produces `specs/blind-spots.json`). If not present, run it.
+3. Read `specs/traceability-matrix.json` and `specs/blind-spots.json`.
+4. Apply decision rules R1–R5 in order (first match wins).
+5. Apply oracle confidence downgrade based on the heuristic link ratio from the matrix's `oracle_stats`.
+6. Output verdict + rationale to stdout.
+7. Update `specs/execution-status.yaml` with gate-trace result.
+
+## Verdict Semantics
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| PASS | All gates satisfied | Proceed with merge |
+| CONCERNS | Non-critical issues found | Requires explicit human override in `state.yaml` |
+| FAIL | Critical traceability gap | Block merge — fix gap first |
+| WAIVED | Cannot evaluate (missing inputs) | Skip gate — data not available |
+
+## Output Format
+
+```yaml
+gate_trace:
+  verdict: PASS|CONCERNS|FAIL|WAIVED
+  generated_at: "<ISO 8601>"
+  rationale: "<human-readable explanation>"
+  heuristic_ratio: <0.0–1.0>
+  downgrade_applied: <true|false>
+```
+
+## Integration Points
+
+- **release-branch SKILL.md** — pre-PR gate (FAIL blocks merge).
+- **sync-skills.yml** — CI gate (FAIL blocks pipeline).
+- **verify-work SKILL.md** — runs blind-spot checks; gate-trace consumes the result.
+
+## References
+
+- BMAD TEA traceability approach (market survey 2026-07-02).
+- scripts/trace-stories.sh (e38s01) — produces traceability-matrix.json.
+- scripts/check-blind-spots.sh (e38s04) — produces blind-spots.json.
+- specs/execution-status.yaml — output target for gate result.
+
+## Verify
+
+→ verify: `test -f skills/gate-trace/SKILL.md && grep -q 'PASS.*CONCERNS.*FAIL.*WAIVED' skills/gate-trace/SKILL.md && echo "OK: gate-trace skill created" || echo "FAIL"`
+
+## Handoff
+
+Gate: READY → next: release-branch (final step before merge)
+Writes: state.yaml handoff.next_skill = release-branch

package/skills/release-branch/SKILL.md

@@ -1,3 +1,4 @@
+<!-- story: e38s07 -->
 ---
 name: release-branch
 model: haiku
@@ -13,21 +14,19 @@ Finalize a completed feature branch: verify coverage gates, integrate onto `main
 
 ## Additional modes
 
-- `--hotfix`: Emergency fix. Cherry-pick to main plus immediate tag. Skip PR in solo profile.
-- `--squash-state`: Squashes all intermediate `chore(state):` commits on the feature branch into a single clean commit before merging. Use this to reduce noise in the main git repository history.
+- `--hotfix`: Cherry-pick to main + tag. Skip PR in solo.
+- `--squash-state`: Squash `chore(state):` commits before merge.
 
 ## Integrate mode
 
-Read `specs/state.yaml` key `workflow_mode` first (`team-pr` | `solo-git`). Fall back to sniffing `profiles/solo-git.md` only when the key is absent.
+Read `specs/state.yaml` key `workflow_mode` (`team-pr` | `solo-git`). Fall back to `profiles/solo-git.md`.
 
 | Mode | When | Ship path |
 |------|------|-----------|
-| **solo-local** | `workflow_mode: solo-git` (or `profiles/solo-git.md` present as fallback) | Auto-detect: if `scripts/land-branch.sh` exists → use it; else → fallback (see Step 5) |
+| **solo-local** | `workflow_mode: solo-git` | Auto: `scripts/land-branch.sh` if present, else fallback (Step 5) |
 | **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
 
-If unsure and working alone, prefer **solo-local**.
-
-> **Auto-detect note:** The solo-local path first checks if `scripts/land-branch.sh` exists and is executable. If present, the script handles the full squash-merge workflow. If absent, the built-in fallback sequence runs instead.
+If unsure, prefer **solo-local**.
 
 ## Process
 
@@ -53,6 +52,10 @@ git log main...HEAD --oneline | grep -vE "^[a-f0-9]+ (feat|fix|docs|style|refact
 
 If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
 
+### 2b. Traceability gate
+
+Run `gate-trace` before merge. FAIL blocks merge; CONCERNS requires explicit override in `specs/state.yaml` (`traceability_override: CONCERNS accepted, reason: <explanation>`). WAIVED if no matrix available.
+
 ### 3. Diff review
 
 - [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
@@ -63,20 +66,14 @@ Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
 
 ### 5. Solo-local integrate
 
-Run `commit-message` to produce the squash commit subject. Then auto-detect the integration path:
+Run `commit-message` for the squash subject, then land:
 
-**Path A — `scripts/land-branch.sh` exists (happy path):**
 ```bash
+# Path A (preferred):
 bash scripts/land-branch.sh <task-slug> "feat(scope): description"
+# Path B (fallback if land-branch.sh missing): see REFERENCE.md
 ```
 
-**Path B — `scripts/land-branch.sh` missing (fallback):**
-See [REFERENCE.md](REFERENCE.md)
-
-**Report which path was taken.** Print exactly:
-- `"used land-branch.sh"` if Path A
-- `"used fallback merge (land-branch.sh not found)"` if Path B
-
 ### 6. Create PR (team-pr only)
 
 See [REFERENCE.md](REFERENCE.md) for the full PR body template and gh commands.

package/skills/verify-work/SKILL.md

@@ -1,3 +1,4 @@
+<!-- story: e38s05 -->
 ---
 name: verify-work
 description: Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.
@@ -36,6 +37,7 @@ Review answers "is the code good?"; Verify answers "does the built thing do what
 3. **AGENTS.md preflight** — before running default checks, call `bash scripts/bp-read-agents.sh` to detect project-specific commands. If `BP_PREFLIGHT` is set, run it instead of the default mechanical gates (or in addition to them if the project requires both). Output: `"Using preflight from AGENTS.md: <cmd>"`. Fall back to `CLAUDE.md` commands if AGENTS.md is absent.
 4. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md).
 5. **Security scan** — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
+5a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
 6. **Step-by-step UAT** — one user-observable action at a time.
 7. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
 

package/skills-lock.json

@@ -23,7 +23,7 @@
     },
     "build-epic": {
       "description": "Eight-step epic build cycle — reads state.yaml, execution-status.yaml, and one epic capsule; updates status via bp-yaml-set or direct edit. Resume mode runs one step per invocation. Use instead of ad-hoc execute-plan for release work.",
-      "sha256": "3d2337356c24ee55",
+      "sha256": "5abf6858c529996c",
       "path": "skills/build-epic/SKILL.md"
     },
     "change-request": {
@@ -126,6 +126,11 @@
       "sha256": "ce4781244b970a14",
       "path": "skills/fix-bug/SKILL.md"
     },
+    "gate-trace": {
+      "description": "\"Deterministic traceability quality gate — reads coverage matrix + blind-spot data, applies decision rules with oracle confidence downgrade, emits PASS/CONCERNS/FAIL/WAIVED verdict. Use before release-branch to gate merges on traceability.\"# story: e38s06",
+      "sha256": "15ca25acd70b90dd",
+      "path": "skills/gate-trace/SKILL.md"
+    },
     "grill-me": {
       "description": "Interactive assumption-surfacing Q&A that stress-tests a plan through relentless questioning until every decision is resolved. Use when user wants to challenge a plan, validate decisions from conversation/context, or mentions \"grill me\". For doc-grounded variant, use grill-with-docs.",
       "sha256": "8ef90da0f127f2fd",
@@ -213,7 +218,7 @@
     },
     "release-branch": {
       "description": "Make the merge/PR/keep/discard decision for a feature branch, verify coverage gates, create the PR with gh, and clean up the worktree. Use when a feature is done and ready to ship, or when user says \"release\", \"merge\", or \"open a PR\".",
-      "sha256": "170166b534697f55",
+      "sha256": "354267f0f4b593b5",
       "path": "skills/release-branch/SKILL.md"
     },
     "request-review": {
@@ -338,7 +343,7 @@
     },
     "verify-work": {
       "description": "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code.",
-      "sha256": "9176edfb256f07bc",
+      "sha256": "b2828b807467e5c7",
       "path": "skills/verify-work/SKILL.md"
     },
     "visual-dashboard": {