bigpowers 2.62.0 → 2.64.0

package/scripts/sync-skills.sh

@@ -1,14 +1,12 @@
 #!/usr/bin/env bash
-# story: e13s03
+# story: e13s03 e28s03
 # sync-skills.sh — generate Cursor, Gemini CLI, and pi artifacts from SKILL.md source files
+# Architecture: Parse→IR→Render. Each target is its own render_<target>() function.
 # Run this after adding or updating any skill. Symlinks carry changes through automatically.
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-# SKILLS_ROOT: use skills/ subdirectory when it exists, fall back to repo root
-# This allows e29s02 to git-mv skill dirs into skills/ without changing this script.
-SKILLS_ROOT="$REPO_ROOT"
-[[ -d "$REPO_ROOT/skills" ]] && SKILLS_ROOT="$REPO_ROOT/skills"
+source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
+
 CURSOR_RULES="$REPO_ROOT/.cursor/rules"
 GEMINI_EXT_DIR="$REPO_ROOT/.gemini/extensions/bigpowers"
 GEMINI_SKILLS="$GEMINI_EXT_DIR/skills"
@@ -26,100 +24,136 @@ rm -rf "${GEMINI_COMMANDS:?}"/*
 rm -rf "${PI_SKILLS:?}"/*
 rm -rf "${PI_PROMPTS:?}"/*
 
-# We'll collect metadata for the manifest if needed, 
-# though skills/commands are auto-discovered.
-# Manifest is still good for extension-level name/version.
-
-skill_count=0
-
-for skill_dir in "$SKILLS_ROOT"/*/; do
-  skill_md="$skill_dir/SKILL.md"
-  [[ -f "$skill_md" ]] || continue
-
-  # Extract name, model, and description from YAML frontmatter
-  name=$(awk '/^---/{f++} f==1 && /^name:/{print; exit}' "$skill_md" | sed 's/^name:[[:space:]]*//')
-  model=$(awk '/^---/{f++} f==1 && /^model:/{print; exit}' "$skill_md" | sed 's/^model:[[:space:]]*//')
-  # Capture description: from "description:" line to next YAML key or closing ---
-  description=$(awk '/^---/{f++; next} f==1 && /^description:/{p=1; sub(/^description:[[:space:]]*/,""); print; next} f==1 && p && /^[a-z]+:/{exit} f==1 && p{print}' "$skill_md" \
-    | tr -d '\n' \
-    | sed -E 's/[[:space:]]+/ /g')
-
-  # Escape double quotes and backslashes for safe double-quoted YAML output
-  description_escaped=$(echo "$description" | sed 's/\\/\\\\/g; s/"/\\"/g')
-
-  [[ -z "$name" ]] && continue
-
-  # Build concatenated content: SKILL.md body + all other *.md files alphabetically
-  # Strip frontmatter from SKILL.md (content between second --- and EOF)
+# ── IR: shared intermediate representation ──────────────────────────
+# These globals are set by the main loop per skill and consumed by render functions.
+IR_NAME=""
+IR_MODEL=""
+IR_DESCRIPTION=""
+IR_DESC_ESCAPED=""
+IR_BODY=""
+
+# ── build_body ──────────────────────────────────────────────────────
+# Builds the concatenated content: SKILL.md body + all other *.md files.
+# Args: $1 = path to SKILL.md, $2 = skill directory
+build_body() {
+  local skill_md="$1"
+  local skill_dir="$2"
+  local body
+
+  # Strip frontmatter from SKILL.md (content after second ---)
   body=$(awk '/^---/{f++; next} f>=2{print}' "$skill_md")
 
+  # Append extra *.md files alphabetically
+  local extra_md
   for extra_md in $(find "$skill_dir" -maxdepth 1 -name "*.md" ! -name "SKILL.md" | LC_ALL=C sort); do
     body="$body"$'\n\n'"---"$'\n\n'"$(cat "$extra_md")"
   done
 
   # Strip disable-model-invocation lines
-  body=$(echo "$body" | grep -v 'disable-model-invocation')
+  echo "$body" | grep -v 'disable-model-invocation'
+}
 
-  # 1. Write .cursor/rules/<name>.mdc
-  cursor_file="$CURSOR_RULES/$name.mdc"
+# ── Render target: Cursor ───────────────────────────────────────────
+# Writes .cursor/rules/<name>.mdc with YAML frontmatter + body.
+render_cursor() {
+  local cursor_file="$CURSOR_RULES/$IR_NAME.mdc"
   {
     echo "---"
-    echo "description: \"$description_escaped\""
+    echo "description: \"$IR_DESC_ESCAPED\""
     echo "alwaysApply: false"
     echo "---"
     echo ""
-    echo "$body"
+    echo "$IR_BODY"
   } > "$cursor_file"
+}
 
-  # 2. Write Gemini Agent Skill: .gemini/extensions/bigpowers/skills/<name>/SKILL.md
-  mkdir -p "$GEMINI_SKILLS/$name"
+# ── Render target: Gemini Agent Skill ───────────────────────────────
+# Writes .gemini/extensions/bigpowers/skills/<name>/SKILL.md
+render_gemini_skill() {
+  mkdir -p "$GEMINI_SKILLS/$IR_NAME"
   {
     echo "---"
-    echo "name: $name"
-    echo "description: \"$description_escaped\""
+    echo "name: $IR_NAME"
+    echo "description: \"$IR_DESC_ESCAPED\""
     echo "---"
     echo ""
-    echo "$body"
-  } > "$GEMINI_SKILLS/$name/SKILL.md"
+    echo "$IR_BODY"
+  } > "$GEMINI_SKILLS/$IR_NAME/SKILL.md"
+}
 
-  # 3. Write Gemini Slash Command: .gemini/extensions/bigpowers/commands/<name>.toml
-  # We use a dedicated prompt file to keep the TOML clean
+# ── Render target: Gemini Slash Command ─────────────────────────────
+# Writes .gemini/extensions/bigpowers/commands/<name>.toml + prompt file
+render_gemini_command() {
   mkdir -p "$GEMINI_COMMANDS/prompts"
-  prompt_file="commands/prompts/$name.md"
-  echo "$body" > "$GEMINI_EXT_DIR/$prompt_file"
-  
+  local prompt_file="commands/prompts/$IR_NAME.md"
+  echo "$IR_BODY" > "$GEMINI_EXT_DIR/$prompt_file"
   {
-    echo "description = \"$description_escaped\""
+    echo "description = \"$IR_DESC_ESCAPED\""
     echo "prompt = \"@{$prompt_file}\""
-  } > "$GEMINI_COMMANDS/$name.toml"
+  } > "$GEMINI_COMMANDS/$IR_NAME.toml"
+}
 
-  # 4. Write pi skill: .pi/skills/<name>/SKILL.md
-  # Pi implements the Agent Skills standard — same YAML frontmatter + body format
-  mkdir -p "$PI_SKILLS/$name"
+# ── Render target: pi Agent Skill ───────────────────────────────────
+# Writes .pi/skills/<name>/SKILL.md
+render_pi_skill() {
+  mkdir -p "$PI_SKILLS/$IR_NAME"
   {
     echo "---"
-    echo "name: $name"
-    echo "description: \"$description_escaped\""
-    [[ -n "$model" ]] && echo "model: $model"
+    echo "name: $IR_NAME"
+    echo "description: \"$IR_DESC_ESCAPED\""
+    [[ -n "$IR_MODEL" ]] && echo "model: $IR_MODEL"
     echo "---"
     echo ""
-    echo "$body"
-  } > "$PI_SKILLS/$name/SKILL.md"
+    echo "$IR_BODY"
+  } > "$PI_SKILLS/$IR_NAME/SKILL.md"
+}
 
-  # 5. Write pi prompt template: .pi/prompts/<name>.md
-  # Slash-command templates expandable via /<name> in pi's editor
+# ── Render target: pi Prompt Template ───────────────────────────────
+# Writes .pi/prompts/<name>.md
+render_pi_prompt() {
   {
     echo "---"
-    echo "description: $description"
+    echo "description: $IR_DESCRIPTION"
     echo "---"
     echo ""
-    echo "$body"
-  } > "$PI_PROMPTS/$name.md"
+    echo "$IR_BODY"
+  } > "$PI_PROMPTS/$IR_NAME.md"
+}
+
+# ── Target registry ─────────────────────────────────────────────────
+# Order matters: render functions are called in this order per skill.
+TARGETS=(render_cursor render_gemini_skill render_gemini_command render_pi_skill render_pi_prompt)
+
+skill_count=0
+
+# ── Main loop: Parse → IR → Render per skill ────────────────────────
+while IFS= read -r skill_dir; do
+  skill_md="$skill_dir/SKILL.md"
+
+  parse_frontmatter "$skill_md" || continue
+
+  IR_NAME="$_PF_NAME"
+  IR_MODEL="$_PF_MODEL"
+  IR_DESCRIPTION="$_PF_DESCRIPTION"
+
+  # Escape double quotes and backslashes for safe double-quoted YAML output
+  IR_DESC_ESCAPED=$(echo "$IR_DESCRIPTION" | sed 's/\\/\\\\/g; s/"/\\"/g')
+
+  [[ -z "$IR_NAME" ]] && continue
+
+  IR_BODY=$(build_body "$skill_md" "$skill_dir")
+
+  # Dispatch to each render target
+  for target_fn in "${TARGETS[@]}"; do
+    "$target_fn"
+  done
 
   skill_count=$((skill_count + 1))
-done
+done < <(iterate_skills)
+
+# ── Post-loop: manifest, opencode, regeneration, guards, README badge ──
 
-# Assemble final gemini-extension.json (top-level fields only — not scripts.version)
+# Assemble final gemini-extension.json
 pkg_version=$(jq -r '.version' "$REPO_ROOT/package.json")
 pkg_desc=$(jq -r '.description' "$REPO_ROOT/package.json")
 
@@ -128,8 +162,7 @@ jq -n --arg name "bigpowers" \
       --arg desc "${skill_count} skills — ${pkg_desc}" \
       '{name: $name, version: $version, description: $desc}' > "$GEMINI_MANIFEST"
 
-# 6. Write pi package config: .pi/package.json
-# Enables pi install (local path, npm, or git) with auto-discovered skills and prompts
+# Write pi package config: .pi/package.json
 jq -n --arg version "$pkg_version" \
       --arg desc "${skill_count} skills — ${pkg_desc}" \
       '{
@@ -143,9 +176,7 @@ jq -n --arg version "$pkg_version" \
         }
       }' > "$PI_PACKAGE_JSON"
 
-# 7. Write OpenCode configuration: opencode.json (minimal project-level config)
-# Skills are loaded on-demand via opencode's native skill tool, not instructions.
-# Full opencode integration lives in the bigpowers-opencode repo.
+# Write OpenCode configuration: opencode.json
 {
   echo "{"
   echo "  \"\$schema\": \"https://opencode.ai/config.json\","
@@ -153,7 +184,7 @@ jq -n --arg version "$pkg_version" \
   echo "}"
 } > "$REPO_ROOT/opencode.json"
 
-# 5. Sync to bigpowers-opencode repo (if --opencode path is provided)
+# Sync to bigpowers-opencode repo (if --opencode path is provided)
 OPN_TARGET=""
 for arg in "$@"; do
   case "$arg" in
@@ -194,8 +225,7 @@ if [[ -x "$REPO_ROOT/scripts/build-skill-index.sh" ]]; then
   bash "$REPO_ROOT/scripts/build-skill-index.sh" || true
 fi
 
-# Prune orphan cursor rules — .mdc files whose skill directory no longer exists.
-# Allowlist: hand-maintained rules that intentionally have no SKILL.md source.
+# Prune orphan cursor rules
 CURSOR_KEEP="context7.mdc"
 for mdc in "$CURSOR_RULES"/*.mdc; do
   [[ -e "$mdc" ]] || continue
@@ -207,8 +237,7 @@ for mdc in "$CURSOR_RULES"/*.mdc; do
   fi
 done
 
-# Stamp the README skill-count badge from the live count — never hardcode it by hand.
-# Portable (BSD/GNU): write to temp file instead of sed -i.
+# Stamp the README skill-count badge
 readme="$REPO_ROOT/README.md"
 if [[ -f "$readme" ]] && grep -q 'badge/skills-' "$readme"; then
   readme_tmp=$(mktemp)
@@ -229,7 +258,7 @@ echo "  → SKILL-INDEX.md (auto-generated skill reference)"
 echo "  → opencode.json (CLAUDE.md + CONVENTIONS.md instructions)"
 [[ -n "$OPN_TARGET" ]] && echo "  → bigpowers-opencode: $opencode_count skills"
 
-# Regression guard (BUG-2026-06-02T164500): BSD sed without -E strips '+' from descriptions
+# Regression guard (BUG-2026-06-02T164500)
 trace_mdc="$REPO_ROOT/.cursor/rules/trace-requirement.mdc"
 if [[ -f "$trace_mdc" ]] && ! grep -q 'release-plan.yaml + epic' "$trace_mdc"; then
   echo "sync-skills: FAIL — '+' missing from trace-requirement; use sed -E for whitespace collapse" >&2
@@ -257,15 +286,13 @@ if [[ -f "$validate_script" ]] && command -v python3 &>/dev/null; then
   fi
 fi
 
-# Regression guard (BUG-2026-07-02T103911): no bash 4+ features in install-chain scripts
-# macOS ships bash 3.2 which lacks declare -A (associative arrays)
+# Regression guard (BUG-2026-07-02T103911): no bash 4+ features
 if grep -rn '^declare -A\|^[[:space:]]*declare -A' scripts/sync-skills.sh scripts/generate-skill-index.sh scripts/regenerate-lockfile.sh scripts/build-skill-index.sh 2>/dev/null; then
   echo "sync-skills: FAIL — bash 4+ features detected in install-chain scripts (not macOS-compatible)" >&2
   exit 1
 fi
 
-# Regenerate derived reference tables from live SKILL.md frontmatter
-# Only in dev context (with .git) — not during consumer npm install where docs/ is excluded
+# Regenerate derived reference tables
 if [[ -d "$REPO_ROOT/.git" ]]; then
   bash "$REPO_ROOT/scripts/generate-reference-tables.sh"
 fi

package/scripts/validate-okf.sh

@@ -194,6 +194,31 @@ for m in d.get('migrations',[]):
   printf "${GREEN}PASS${NC} %s (%s migrations indexed)\n" "$name" "$count"
 }
 
+# ---- Receipts validation (e41s04) ----------------------------------------
+validate_receipts() {
+  local f="$ROOT/specs/receipts.json"
+  if [ ! -f "$f" ]; then printf "${YELLOW}SKIP${NC} receipts.json not found\n"; return; fi
+  python3 -c "
+import json, sys
+d=json.load(open('$f'))
+vs={'measured','estimated','backfilled','absent'}
+ss=('compliance','golden_suite','metrics','traceability')
+errs=0
+for sec in ss:
+    data=d.get(sec)
+    if data is None: continue
+    src=data.get('source','')
+    if not src: print(f'FAIL: receipts.json — {sec}: missing source tag'); errs+=1; continue
+    if src not in vs: print(f'FAIL: receipts.json — {sec}: unknown source \"{src}\"'); errs+=1; continue
+    hv='value' in data
+    if src=='absent' and hv: print(f'FAIL: receipts.json — {sec}: tagged absent but carries value'); errs+=1
+    elif src!='absent' and not hv: print(f'FAIL: receipts.json — {sec}: tagged {src} but missing value'); errs+=1
+if errs==0: print('PASS receipts.json')
+else: print(f'{errs} violation(s) in receipts.json')
+sys.exit(errs)
+" || { EXIT_CODE=1; return; }
+}
+
 # ---- Main validation dispatcher ----------------------------------------
 validate_bundle() {
   local file="$1"
@@ -280,4 +305,7 @@ else
   exit 1
 fi
 
+# e41s04: always validate receipts.json
+validate_receipts
+
 exit "$EXIT_CODE"

package/scripts/verify-install.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# story: e47s04
+# verify-install.sh — manual assertion harness for install + seed wiring
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+PASS=0
+FAIL=0
+TMPDIR=""
+
+cleanup() { [[ -n "$TMPDIR" && -d "$TMPDIR" ]] && rm -rf "$TMPDIR"; }
+trap cleanup EXIT
+
+pass() { echo "  PASS $1"; PASS=$((PASS + 1)); }
+fail() { echo "  FAIL $1"; FAIL=$((FAIL + 1)); }
+
+echo "=== install.sh --dry-run ==="
+DRY_OUT="$("$REPO_ROOT/scripts/install.sh" --dry-run 2>&1)"
+
+echo "$DRY_OUT" | grep -q 'pi →' && pass "install --dry-run includes pi" || fail "install --dry-run missing pi"
+DRY_UNINSTALL="$("$REPO_ROOT/scripts/install.sh" --dry-run --uninstall 2>&1)"
+echo "$DRY_UNINSTALL" | grep -q 'pi →' && pass "uninstall --dry-run includes pi" || fail "uninstall --dry-run missing pi"
+echo "$DRY_OUT" | grep -qi 'opencode' && fail "install references opencode" || pass "install has no opencode reference"
+echo "$DRY_OUT" | grep -q 'Claude Code →' && pass "install includes Claude Code" || fail "install missing Claude Code"
+echo "$DRY_OUT" | grep -q 'Gemini CLI →' && pass "install includes Gemini CLI" || fail "install missing Gemini CLI"
+echo "$DRY_OUT" | grep -q 'Cursor →' && pass "install includes Cursor" || fail "install missing Cursor"
+
+for tool in "Claude Code" "pi"; do
+  # Find the skills count in the tool's section (between this tool header and next section)
+  section=$(echo "$DRY_OUT" | sed -n "/${tool} →/,/^$/p")
+  count=$(echo "$section" | grep -o '[0-9]\+ skills installed' | grep -o '[0-9]\+' || echo "0")
+  [[ "$count" -gt 0 ]] && pass "${tool}: $count skills" || fail "${tool}: 0 skills"
+done
+
+echo ""
+echo "=== seed-conventions local wiring ==="
+grep -qi 'local tool wiring' "$REPO_ROOT/skills/seed-conventions/SKILL.md" && pass "SKILL.md: local tool wiring" || fail "SKILL.md: missing local tool wiring"
+grep -qi 'opencode.json' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: opencode.json" || fail "REFERENCE.md: missing opencode.json"
+grep -qi 'cursor/rules' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" && pass "REFERENCE.md: Cursor symlink" || fail "REFERENCE.md: missing Cursor symlink"
+
+OPENCODE_JSON=$(sed -n '/```json/,/```/p' "$REPO_ROOT/skills/seed-conventions/REFERENCE.md" | grep -v '```' || true)
+if [[ -n "$OPENCODE_JSON" ]]; then
+  TMPDIR=$(mktemp -d)
+  echo "$OPENCODE_JSON" > "$TMPDIR/test-opencode.json"
+  jq empty "$TMPDIR/test-opencode.json" 2>/dev/null && pass "opencode.json valid JSON" || fail "opencode.json NOT valid JSON"
+else
+  fail "opencode.json template not found"
+fi
+
+echo ""
+echo "=== install.sh source ==="
+grep -q 'install_pi()' "$REPO_ROOT/scripts/install.sh" && pass "source: install_pi()" || fail "source: missing install_pi()"
+grep -q 'uninstall_pi()' "$REPO_ROOT/scripts/install.sh" && pass "source: uninstall_pi()" || fail "source: missing uninstall_pi()"
+grep -q 'PI_SKILLS_DIR="$PI_CONFIG_DIR/agent/skills"' "$REPO_ROOT/scripts/install.sh" && pass "source: targets ~/.pi/agent/skills/" || fail "source: wrong pi target"
+! grep -q 'install_opencode\|print_opencode_instructions' "$REPO_ROOT/scripts/install.sh" && pass "source: no opencode functions" || fail "source: opencode functions remain"
+
+echo ""
+echo "──────────────────────────────────────────"
+echo "verify-install: $PASS passed, $FAIL failed"
+[[ "$FAIL" -gt 0 ]] && { echo "Overall: fail"; exit 1; } || echo "Overall: pass"

package/skills/build-epic/SKILL.md

@@ -36,7 +36,8 @@ Orchestrates the **build** flow for a single epic: survey → plan tasks → kic
 2. **Step 0 — Threat Model:** Run `security-review` against the epic's scope (read from the epic capsule). Output `specs/security/epics/<epic-id>/THREAT_MODEL.md` with surface area, vulnerability categories, risk level, and mitigation guidance.
 3. **Assess Impact (Step 2):** Before writing tasks, run `assess-impact --lightweight` on the proposed change. If the risk score exceeds 7, gate — require a `grill-me` session. Write the impact report to `specs/IMPACT-<epic>-<story>.md`. For net-new code with no existing dependents, skip.
 4. **BCP Tracking (Step 2):** After `plan-work` completes, read the `bcps:` count (Business Complexity Points story size) from the epic capsule and carry it into `state.yaml` as `epic_cycle.story_bcps = N`.
-5. If `epic_cycle.step` missing, set to `1`.
+5. **BCP Plus (Step 2, optional):** When the epic capsule carries a `bcp_plus_breakdown` (13-dimension sizing), also carry it into `state.yaml` as `epic_cycle.bcp_plus`. The breakdown maps each of the 13 dimensions to an integer count. NFR dimensions (11–13) that are N/A per the NFR Gate may be set to 0.
+6. If `epic_cycle.step` missing, set to `1`.
 6. Run **only the current step** (resume mode) unless user asked for full auto-run.
 7. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
 8. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.

package/skills/develop-tdd/SKILL.md

@@ -102,3 +102,7 @@ If this cycle modified files in `.github/workflows/`, run the CI dry-run procedu
 
 Gate: READY -> next: verify-work
 Writes: state.yaml handoff.next_skill = verify-work
+
+## BCP Plus Integration
+
+At story completion, if the story was sized with BCP Plus (13-dimension breakdown), log the `bcp_plus.total` alongside the standard `bcps:` count in the story's tasks.yaml. The breakdown is available from the epic capsule's `bcp_plus_breakdown` field. See `docs/references/bcp-plus.md` for the full methodology and NFR Gate pattern.

package/skills/investigate-bug/SKILL.md

@@ -120,3 +120,8 @@ A numbered list of RED-GREEN cycles:
 
 After writing the bug file, print a one-line summary of the root cause and suggest running `kickoff-branch` next to create a fix branch.
 
+## References
+
+- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm
+- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating
+

package/skills/plan-refactor/SKILL.md

@@ -78,5 +78,10 @@ Any further notes about the refactor.
 
 After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next to create a refactor branch.
 
+## References
+
+- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy
+- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change
+
 ## Verify
 

package/skills/run-benchmark/SKILL.md

@@ -1,69 +1,87 @@
 ---
 name: run-benchmark
+# story: e48s01
 model: haiku
 effort: standard
-description: Run skill quality benchmarks from specs/benchmarks/ definitions and write pass@k reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.
+description: Run skill quality benchmarks from specs/benchmarks/ definitions — N-run with/without-skill delta grading, train/validation split, pass@k + benchmark.json reports. Use before and after evolve-skill to prove quality changes are improvements, not regressions.
 ---
 
 # Run Benchmark
 
 > **HARD GATE** — Do NOT use benchmark scores to declare a skill "good" or "bad" in isolation. Benchmarks measure relative quality vs. a baseline — they catch regressions, they do not certify correctness.
 
-Reads benchmark definitions from `specs/benchmarks/`, executes each scenario's grader, and writes a structured `pass@k` report that `evolve-skill` consumes.
+Reads benchmark definitions from `specs/benchmarks/`, executes each scenario's grader with and without the skill loaded, and writes a structured `pass@k` report with delta grading that `evolve-skill` consumes.
 
-## Usage
+## With/Without-Skill Delta Grading
 
-```bash
-# Benchmark a single skill
-run-benchmark <skill-name>
+Every scenario runs N times (default 3) in two modes: **with** the skill loaded and **without** (bare agent with only CLAUDE.md). The delta `Δ = pass@k_with − pass@k_without` isolates the skill's causal contribution. A negative delta is a regression flag.
 
-# Benchmark all skills with definitions
-run-benchmark --all
+## Train/Validation Split
 
-# Pin current results as baseline
-run-benchmark <skill-name> --baseline
-```
+Benchmark definitions partition scenarios into two sets:
 
-## Process
+| Set | Tag | Purpose |
+|-----|-----|---------|
+| **Train** | `split: train` | Development scenarios — used while iterating. Hitting 100% on train is expected. |
+| **Validation** | `split: validation` | Held-out scenarios — the real quality signal. Overfitting train while validation stagnates is a design smell. |
 
-1. **Locate definition** — Read `specs/benchmarks/<skill>.yaml`. If absent, report: `"No benchmark definition found for <skill>. Create specs/benchmarks/<skill>.yaml first."` and stop.
-
-2. **Run each scenario** — For each scenario in `scenarios[]`:
-   - **Code grader:** Run `grader.command` in repo root via `bash -c`. Exit 0 → PASS. Non-zero → FAIL. Timeout: 15 seconds.
-   - **Rubric grader:** Present each criterion to the agent as a yes/no question about the scenario output. ≥ 80% yes → PASS, else FAIL.
-
-3. **Calculate pass@k** — `pass@k = sum(weight of PASS scenarios) / sum(all weights)`. Round to 2 decimal places.
-
-4. **Write report** to `specs/benchmarks/reports/BENCHMARK-<skill>-<YYYY-MM-DD>.yaml`:
-
-```yaml
-skill: survey-context
-run_date: "2026-06-22"
-pass_at_k: 0.83
-total_scenarios: 3
-passed: 2
-failed: 1
-scenarios:
-  - id: s01
-    name: "detects active epic from state.yaml"
-    result: PASS
-    weight: 1.0
-  - id: s02
-    name: "reads release-plan.yaml and reports next epic"
-    result: PASS
-    weight: 1.0
-  - id: s03
-    name: "handles missing state.yaml gracefully"
-    result: FAIL
-    weight: 0.5
-    failure_note: "crashed instead of suggesting state.yaml creation"
-```
+`pass@k` is reported separately for train and validation. Validation score is authoritative; train score is iteration guidance only.
 
-5. **Baseline mode** (`--baseline`) — Copy the report to `specs/benchmarks/reports/BASELINE-<skill>.yaml`. This is the reference point for regression checks in `evolve-skill`.
+## Usage
 
-6. **Compare to baseline** — If a `BASELINE-<skill>.yaml` exists, compare `pass_at_k`. Report:
-   - `IMPROVED: 0.67 → 0.83`
-   - `REGRESSION: 0.83 → 0.67 — do NOT ship this change`
-   - `STABLE: 0.83 = 0.83`
+```bash
+run-benchmark <skill-name>           # benchmark single skill
+run-benchmark --all                  # benchmark all with definitions
+run-benchmark <skill-name> --baseline # pin results as baseline
+```
 
+## Process
 
+1. **Locate definition** — Read `specs/benchmarks/<skill>.yaml`. If absent, stop with message.
+
+2. **Partition scenarios** — Split by `split` field (`train` → iteration, `validation` → authoritative, default: `validation`).
+
+3. **Run each scenario (N-run delta)** — For each scenario, run grader N times (default 3, configurable via `runs:`):
+   - **Without skill:** Agent with only CLAUDE.md/CONVENTIONS.md
+   - **With skill:** Agent with the skill under test active
+   - Code grader: `bash -c <command>`, exit 0 → PASS. Timeout: 15s.
+   - Rubric grader: yes/no per criterion, ≥ 80% yes → PASS.
+   - Record: `{scenario_id: {with: [P/F,...], without: [P/F,...]}}`
+
+4. **Calculate scores** — Per split (train, validation) and mode (with, without):
+   - `pass@k = sum(weight × pass_rate) / sum(weights)` where `pass_rate = passes/runs`
+   - `Δ = pass@k_with − pass@k_without` — causal contribution
+   - Round to 2 decimal places
+
+5. **Write benchmark.json** to `specs/benchmarks/reports/benchmark-<skill>.json`:
+   ```json
+   {"skill":"survey-context","run_date":"2026-06-22","runs_per_scenario":3,"train":{"with_skill":0.92,"without_skill":0.67,"delta":0.25,"scenarios":["s01","s02"]},"validation":{"with_skill":0.83,"without_skill":0.60,"delta":0.23,"scenarios":["s03","s04","s05"]}}
+   ```
+
+6. **Write YAML report** to `specs/benchmarks/reports/BENCHMARK-<skill>-<YYYY-MM-DD>.yaml`:
+   ```yaml
+   skill: survey-context
+   run_date: "2026-06-22"
+   runs_per_scenario: 3
+   train:
+     pass_at_k_with: 0.92
+     pass_at_k_without: 0.67
+     delta: 0.25
+   validation:
+     pass_at_k_with: 0.83
+     pass_at_k_without: 0.60
+     delta: 0.23
+   scenarios:
+     - id: s01
+       split: train
+       with_pass_rate: 1.0
+       without_pass_rate: 0.67
+       delta: 0.33
+       weight: 1.0
+   ```
+
+7. **Baseline** (`--baseline`) — Copy to `BASELINE-<skill>.yaml` + `baseline-<skill>.json`.
+
+8. **Compare to baseline** — `IMPROVED: Δ 0.17 → 0.25` / `REGRESSION: Δ 0.25 → 0.17 — do NOT ship` / `STABLE`.
+
+9. **Delta threshold gate** — Validation Δ < 0.0 blocks release. Δ < 0.05 warns (marginal). Min meaningful threshold: 0.05.

package/skills/security-review/SKILL.md

@@ -30,6 +30,10 @@ description: >
 
 Covered: SQLi, XSS, SSRF, command injection, auth bypass, unsafe deserialization, path traversal, IDOR, crypto flaws, secrets exposure, template injection, NoSQLi
 
+## BCP Plus Integration
+
+This skill maps to **BCP Plus dimension 12 (Security & Compliance)**. When BCP Plus sizing is active, the threat model categories above correspond to sub-elements within dimension 12. The NFR Gate rule applies: standard-expectation items (e.g., "use HTTPS", "hash passwords") score 0 with a one-line rationale; only above-standard security requirements contribute to the dimension 12 count. See `docs/references/bcp-plus.md` for the full 13-dimension framework and NFR Gate pattern.
+
 ## Integration points
 
 | Skill | Touchpoint |

package/skills/seed-conventions/REFERENCE.md

@@ -61,3 +61,34 @@ Use the standard bigpowers CONVENTIONS.md as the base. Fill in the project-speci
 ## Stack profile fragments
 
 If the user selected a stack profile, merge the matching `profiles/<name>.md` fragment into the generated `CONVENTIONS.md` under a `## Stack Conventions` section. Profiles supply language-specific commands, architecture patterns, and never-do additions.
+
+## Local tool wiring (optional interview step 8)
+
+Offered after the standard interview. Covers the two tools that global install (`scripts/install.sh`) structurally cannot reach because they read project-root config, not global paths.
+
+### Cursor — project-local `.cursor/rules` symlink
+
+```bash
+# From the project root:
+ln -sfn <bigpowers-install-path>/.cursor/rules .cursor/rules
+```
+
+Cursor reads `.cursor/rules/` from the project root. This symlink gives every project access to bigpowers skills as Cursor rules without duplicating the files. Run once per project.
+
+### OpenCode — project-local `opencode.json` + `AGENTS.md`
+
+`opencode.json` (project root):
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [".cursor/rules/*.mdc", "AGENTS.md"]
+}
+```
+
+OpenCode reads `opencode.json` from the project root, NOT from a global path. The `instructions` array points to the local `.cursor/rules` symlink (from the Cursor step above) and the project's `AGENTS.md`. Both must exist in the project for OpenCode to see bigpowers skills.
+
+`AGENTS.md` is already generated by the standard interview (step 2 of Generate Files). When local tool wiring is opted in, ensure `AGENTS.md` includes the standard agent-config template header `# [Project Name] — OpenCode`.
+
+### When to offer
+
+Only offer local tool wiring when the user's project will be opened in Cursor or OpenCode. These tools are project-root scoped by design — no global installer can solve them. Global install (`install.sh`) already handles Claude Code, Gemini CLI, and pi globally. Do not offer for tools that read global config.

package/skills/seed-conventions/SKILL.md

@@ -30,6 +30,8 @@ Ask the user these questions (one at a time, wait for each answer):
 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
+8. **Local tool wiring (optional)** — "Wire bigpowers skills for project-local tools that global install can't reach? (Cursor + OpenCode only)" If yes, generate the local wiring artifacts described in [REFERENCE.md](REFERENCE.md) §Local tool wiring. If no, skip — the standard seed output is unchanged.
+8. **Local tool wiring (optional)** — "Wire bigpowers skills for project-local tools that global install can't reach? (Cursor + OpenCode only)" If yes, generate the local wiring artifacts described in [REFERENCE.md](REFERENCE.md) §Local tool wiring. If no, skip — the standard seed output is unchanged.
 
 ## Generate files