bigpowers 2.83.4 → 2.84.1

package/.windsurf/rules/session-state.md

@@ -0,0 +1,146 @@
+---
+name: session-state
+model: haiku
+description: "Track implementation decisions and progress in specs/state.yaml to prevent context rot. Use at the start of a session to load context, and whenever a significant decision is made or a milestone is reached."
+---
+
+# story: e45s23
+
+# Session State
+> **HARD GATE** — **HARD GATE** — Session state must be synchronized with git state. If state.yaml conflicts with the working tree, halt and ask for clarification. Do NOT assume state is correct.
+
+
+Track the current state of implementation, including decisions made, pending tasks, and open questions, to ensure continuity across session boundaries and prevent "context rot."
+
+Session-state implements the **isolate** strategy from the context-engineering framework (docs/references/context-engineering.md): each agent gets exactly the context it needs — no more — by recording decisions so the next agent can cold-start without replaying history. The four strategies (write, select, compress, isolate) work together: session-state handles isolation, terse-mode handles compression, survey-context handles selection, and CONVENTIONS.md ensures token-efficient writing.
+
+## Goal
+
+Maintain a single source of truth for the *current* session in `specs/state.yaml`. This complements long-term docs in `specs/tech-architecture/` and delivery detail in `specs/epics/` + `specs/release-plan.yaml`.
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT when YAML exists — use `specs/state.yaml` only.
+
+When a story modifies existing behavior, patch only between matching marker pairs in `CLAUDE.md` / `AGENTS.md` `learned-preferences` fence — see e45s21.
+
+## Handoff block (cold start)
+
+When ending a session or before a context-heavy spawn, update `handoff` in `state.yaml`:
+
+```yaml
+handoff:
+  last_step_completed: "e02s01 verify-work passed"
+  open_decisions:
+    - "Use folder mode for e07 (>5 stories)"
+  required_reading:
+    - CONVENTIONS.md
+    - specs/epics/e02-verification/epic.yaml
+  next_skill: develop-tdd
+```
+
+## Strategic compaction
+
+| Trigger | Action |
+|---------|--------|
+| Phase transition (Plan → Build → Verify) | Compact handoff; archive verbose decisions to ADR |
+| Context > 70% estimated | Run terse-mode for status only; move detail to specs/ |
+| Before `dispatch-agents` wave | `state.yaml` only channel between spawns |
+
+## Workflow
+
+### 1. Initialize (Session Start)
+
+If `specs/state.yaml` does not exist, or if starting a new major phase:
+
+- [ ] Read `specs/release-plan.yaml` and `specs/product/SCOPE_LATEST.yaml`.
+- [ ] Get git metadata: `git branch --show-current` and `git rev-parse --short HEAD`.
+- [ ] Create `specs/state.yaml` with active flow, git, handoff, and epic cycle if in build.
+
+### 2. Load (Context Refresh)
+
+When starting a new session or after a significant context flush:
+
+- [ ] Read `specs/state.yaml` to understand where the previous agent left off.
+- [ ] Read `specs/execution-status.yaml` for story progress (do not infer from release-plan).
+- [ ] Verify git matches `state.yaml` `git.branch` / `git.hash`.
+
+### 3. Update (Decision Point/Milestone)
+
+Whenever a significant decision is made or a milestone is reached:
+
+- [ ] Patch via `bash scripts/bp-yaml-set.sh specs/state.yaml git.hash <hash>` (or edit directly).
+- [ ] Patch `handoff` and `learned_preferences` / `workspace_facts` in `CLAUDE.md` fenced block when durable user preferences or repo facts crystallize (e45s23).
+- [ ] Update `handoff.open_decisions` with rationale.
+- [ ] Update `epic_cycle` when advancing `ship-epic` steps.
+- [ ] Record open questions under `handoff.open_decisions` or an ADR.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+## Universal checkpoint pattern
+
+Every multi-step flow (>3 steps) in bigpowers uses a cycle counter in `state.yaml`:
+
+| Flow | Cycle key | Step field | Phases/Steps |
+|------|-----------|------------|-------------|
+| build-epic | `epic_cycle` | `current_step` | 8 (survey → release) |
+| fix-bug | `bug_cycle` | `current_step` | 5 (investigate → release) |
+| orchestrate-project | `project_cycle` | `current_phase` | 6 (discover → release) |
+
+**Checkpoint:** After each step/phase completes, increment the counter in `state.yaml` and update `handoff.next_skill`.
+
+**Resume:** On session start, read the current step/phase from the cycle key — continue from there, not from step 1.
+
+**Completed steps:** Track completed steps in `completed_steps` (comma-separated string) for audit trail.
+
+## Strategic compaction
+
+Print the current session state: `cat specs/state.yaml`, then display `active_flow` and `handoff.next_skill` for quick reference.
+
+### reset-state (absorbed)
+
+Clear ephemeral session state. Set `active_epic_id`, `active_story_id`, and `epic_cycle.current_step` to `null` in `specs/state.yaml`. Use when ending a phase or starting a new project context.
+
+### compact-state (absorbed)
+
+Archive verbose decisions before a context transition. Move all entries from `handoff.open_decisions` to their appropriate location:
+
+- **System-wide decisions** → `specs/adr/NNNN-slug.md` (global Architectural Decision Records)
+- **Epic-scoped decisions** → `specs/epics/<active_epic_id>-<slug>/adr/NNNN-slug.md` (epic-local ADRs, archived with epic)
+
+After archiving, reset `handoff.open_decisions` to an empty list.
+
+## File Format: specs/state.yaml
+
+```yaml
+active_flow: build_epic       # planning | build_epic | fix_bug
+active_epic_id: e02
+active_story_id: e02s01       # required when epic mode: folder
+active_bug_id: null           # BUG-2026-06-01T143022 when fix_bug
+release:
+  target_version: null         # NOT tracked manually — semantic-release decides at merge
+  last_tag: v2.28.0            # mirror of `gh release view`, reference only
+  last_publish: null
+epic_cycle:
+  current_step: develop-tdd
+  next_skill: develop-tdd
+  completed_steps: [kickoff-branch]
+bug_cycle:
+  current_step: null
+  completed_steps: []
+git:
+  branch: feat/e02-verify
+  hash: abc1234
+handoff:
+  last_step_completed: null
+  open_decisions: []
+  next_skill: survey-context
+```
+
+## Anti-Patterns
+
+- **Duplicate Plan**: Don't copy `release-plan.yaml` or epic shards into `state.yaml`.
+- **Stale State**: Forgetting to update `state.yaml` after a major refactor or decision.
+- **Status in release-plan**: Story/epic status lives only in `execution-status.yaml`.
+
+
+<!-- story: e03s03 -->
+<!-- story: e04s01 -->

package/.windsurf/rules/setup-environment.md

@@ -0,0 +1,39 @@
+---
+name: setup-environment
+model: haiku
+description: "Pre-install dependencies and configure tools before development work begins. Use at session start on a fresh clone, before kickoff-branch, or when user says setup environment or install deps."
+---
+
+# Setup Environment
+> **HARD GATE** — **HARD GATE** — Environment setup must be idempotent and reproducible. If setup fails, provide clear error messages and remediation steps. Do NOT assume prior state.
+
+
+Idempotent prep so BUILD phase commands succeed on first run.
+
+## Checklist
+
+1. Read `CLAUDE.md` / `CONVENTIONS.md` for required runtimes and commands.
+2. Verify runtime versions (`node -v`, `swift --version`, etc.).
+3. Install dependencies (`npm ci`, `bundle install`, etc.) — prefer lockfile installs.
+4. Copy `.env.example` → `.env` if documented; never commit secrets.
+5. Run smoke: lint + one fast test or `--version` on key tools.
+6. Record versions in `specs/state.yaml` under Environment.
+
+## BCP Plus Counter (optional)
+
+The `big-counter` tool is an optional dependency for BCP Plus 13-dimension story sizing:
+
+```bash
+# Install from PyPI (recommended)
+pip install big-counter
+
+# Or from npm
+npm install -g big-counter
+```
+
+Verify the install: `big-counter --version`
+Skip if BCP Plus sizing is not needed for this project.
+
+## Verify
+
+→ verify: `test -f CLAUDE.md && grep -q 'Test' CLAUDE.md && echo "OK: CLAUDE.md has test table" || echo "MISSING: test commands"`

package/.windsurf/rules/simulate-agents.md

@@ -0,0 +1,26 @@
+---
+name: simulate-agents
+model: sonnet
+description: "Run Mock User and Auditor agents against a feature in fresh contexts before human review. Use after verify-work, before request-review, when user wants pre-review simulation."
+---
+
+# Simulate Agents
+> **HARD GATE** — **HARD GATE** — Simulations are hypothetical. Do NOT use sim results to make production decisions without validation on real agents. Sims help discover gaps, not replace testing.
+
+
+Two roles, **isolated contexts** (no shared state with BUILD agent):
+
+1. **Mock User** — follows Verification Script; reports UX gaps in plain language.
+2. **Auditor** — checks CONVENTIONS.md, security checklist, test coverage; structured pass/fail.
+
+## Process
+
+1. Read story Verification Script + changed files diff.
+2. Spawn Mock User: step through UAT script; log failures.
+3. Spawn Auditor: run `audit-code` checklist cold.
+4. Write `specs/SIMULATION-<feature>.md` with both reports.
+5. Failed items → `respond-review` or `plan-work` gaps — do not skip human review.
+
+## Verify
+
+→ verify: `ls specs/SIMULATION-*.md 2>/dev/null | head -1 | grep -q . && grep -c "Mock User\|Auditor" specs/SIMULATION-*.md | awk '{if($1>=2) print "OK"}' || echo "MISSING: no simulation files"`

package/.windsurf/rules/slice-tasks.md

@@ -0,0 +1,68 @@
+---
+name: slice-tasks
+model: sonnet
+description: "PLANNING SPINE STEP 2 of 3 — Slice the work: break a scoped PRD into vertical-slice stories in specs/epics/. Use after scope-work (step 1), before plan-work (step 3). Not a substitute for scope-work or plan-work."
+---
+
+# story: e45s29
+
+# Slice Tasks
+
+> **Spine position:** Step 2 — scope-work → slice-tasks → plan-work.
+
+Produce **epic capsule story tasks** in `specs/epics/eNN-slug/` — vertical slices, each independently deliverable and testable. Output: decoupled `eNNsYY-tasks.yaml` files with runnable verify commands. Legacy `specs/epics/ (see slice-tasks)` is deprecated; use capsule dirs + `execution-status.yaml`.
+
+## Pre-flight
+
+- [ ] Does `specs/product/SCOPE_LATEST.yaml` exist? If not, run `scope-work` first — you can't slice what you haven't bounded.
+- [ ] Is the `release-plan.yaml` populated with the epics you're slicing? Epic IDs (e01, e02…) should exist before you create stories.
+- [ ] Do you understand the difference between a horizontal layer and a vertical slice? (See anti-patterns below.)
+
+## Process
+
+0. **Read planning-context.yaml** — If `specs/planning-context.yaml` exists, read it first:
+   ```bash
+   test -f specs/planning-context.yaml && echo "Context found" || echo "No context — starting fresh"
+   ```
+   Use `feature_name`, `constraints`, and `out_of_scope` to inform slice boundaries. `key_decisions` in the file may constrain how stories are cut (e.g., "no external deps" constrains slice 2). If absent, proceed normally.
+
+1. **Read context** — Read `specs/product/SCOPE_LATEST.yaml` and/or `specs/release-plan.yaml`. Understand what the epic delivers end-to-end.
+
+2. **Cut tracer-bullet slices** — Identify the thinnest possible vertical path through the stack that delivers user value. Start with this slice; it will catch integration issues first. For example:
+   - A search feature: first slice is "user types query → API returns results" (no filters, no pagination, no ranking — just the plumbing working end-to-end).
+   - A checkout flow: first slice is "user clicks buy → order created" (no payment, no inventory, no email).
+
+3. **Assign BCPs** — For each story, estimate Business Complexity Points (1–13). A 1-BCP story is a trivial change (one file, one concept). A 13-BCP story is a major feature across multiple modules. If a story exceeds 8 BCPs, consider splitting it.
+
+4. **Each story** writes:
+   - `eNNsYY-tasks.yaml` with `story_id`, `title`, `status`, `bcps`, `tasks[]` (each with `id`, `description`, `verify`, `status`)
+   - Story spec `.md` files are written by `plan-work` and follow countable-story-format.md
+   - The epic capsule manifest (`epic.yaml`) is updated to list the story ID and BCPs
+   - **Requirement deltas (e45s29):** Stories that alter existing behavior MUST carry `delta:` in `epic.yaml` (`ADDED` | `MODIFIED` | `REMOVED` | `RENAMED`). `plan-work` expands deltas into full before/after requirement text.
+
+5. **Order by WSJF** in `release-plan.yaml` epic list — highest WSJF first. Weight-shortest-job-first ensures the highest value arrives earliest.
+
+6. **Validate slices** — Every slice must answer: "If this story ships, does a user get new value?" If the answer is "no, they need a later story too", the slice is too horizontal — cut vertically deeper.
+
+> **HARD GATE** — No horizontal-only slices ("add all models") without a vertical path that proves integration. Every story must be independently demonstrable, even if it only handles the happy path.
+
+> **HARD GATE** — Each task's `verify:` field must contain a runnable command (not "manually check" or "review visually"). If verification requires manual steps, prefix with `verify-script:` and write the steps in the story file.
+
+## Anti-Patterns
+
+- **Layer cakes** — "Week 1: all models. Week 2: all controllers. Week 3: all views." This hides integration risk until the end. Every story must cut through all layers.
+- **Too-small slices** — If a slice takes < 30 minutes to implement, it's probably noise. Combine with adjacent slices.
+- **Too-large slices** — If a slice takes > 3 days, it's an epic, not a story. Split further.
+
+## Output
+
+- `specs/epics/eNN-slug/eNNsYY-tasks.yaml` — per-story task breakdown with verify commands
+- `specs/epics/eNN-slug/epic.yaml` — updated with story list and BCPs
+- `specs/release-plan.yaml` — updated WSJF ordering (if needed)
+
+## Verify
+
+→ verify: `find specs/epics -name "*-tasks.yaml" | wc -l | awk '{if($1>0) print "OK: "$1" task files"; else print "MISSING"}'`
+
+
+<!-- story: e03s01 -->

package/.windsurf/rules/smoke-test.md

@@ -0,0 +1,242 @@
+---
+name: smoke-test
+model: sonnet
+description: "Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill."
+---
+
+# Smoke Test
+
+> **HARD GATE** — Do NOT run smoke-test against a URL that hasn't been deployed yet. Always run `deploy` first, then `smoke-test`.
+>
+> **HARD GATE** — A failed smoke test means the deployment is broken. Do NOT mark a deploy as successful until all smoke checks pass.
+
+Validate a deployed application is healthy by running a configurable set of HTTP checks against live URLs. Each check asserts:
+- HTTP status code (e.g., 200 for success, 404 for expected-not-found)
+- Response body content signal (regex or jq expression)
+- Response time threshold (optional)
+
+Can be run standalone for quick health checks or chained as the final step of the `deploy` skill.
+
+## Configuration
+
+Smoke checks are defined in `smoke-checks.yaml` at the project root:
+
+See [REFERENCE.md](REFERENCE.md)
+
+Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use.
+
+### Check Schema
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Human-readable check name (used in report) |
+| `path` | Yes | `/` | URL path relative to base_url |
+| `method` | No | `GET` | HTTP method |
+| `expected_status` | No | `200` | Expected HTTP status code |
+| `content_signal` | No | — | Regex or string to find in response body |
+| `max_response_time_ms` | No | — | Fail if response slower than this threshold (ms) |
+
+## Process
+
+### 1. Load smoke checks
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 2. Run each check
+
+For each check in the configuration, perform an HTTP request:
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 3. Assert results
+
+See [REFERENCE.md](REFERENCE.md)
+
+### 4. Generate report
+
+See [REFERENCE.md](REFERENCE.md)
+
+## Integration with deploy skill
+
+The `deploy` skill references `smoke-test` as its final verification step:
+
+```bash
+# In deploy workflow — after successful deploy
+DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
+```
+
+---
+
+# Smoke Test — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–12 | Navigation |
+| 14–31 | Runner script |
+| 33–42 | Configuration reference |
+| 44–53 | Verification |
+| 55–160 | Reference blocks 1–5 |
+
+## Runner script
+
+A ready-to-use runner is provided for standalone operation:
+
+```bash
+bash scripts/run-smoke.sh [url] [smoke-checks-file]
+```
+
+The runner:
+1. Uses `$DEPLOY_URL`, `$SMOKE_CHECKS_FILE`, or CLI arguments
+2. Runs all defined checks
+3. Prints a pass/fail summary
+4. Exits 0 on all pass, non-zero on any failure
+
+
+---
+
+## Configuration reference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SMOKE_CHECKS_FILE` | `smoke-checks.yaml` | Path to smoke checks YAML |
+| `DEPLOY_URL` / `BASE_URL` | *(required)* | Base URL for all checks |
+| `SMOKE_TIMEOUT` | `30` | Per-check timeout (seconds) |
+| `SMOKE_RETRIES` | `0` | Number of retries on failure |
+
+
+---
+
+## Verification
+
+→ verify: `test -f smoke-test/SKILL.md && grep -q 'name: smoke-test' smoke-test/SKILL.md && echo OK`
+→ verify: `grep -qi 'smoke.checks.yaml\|checklist\|expected_status\|content_signal' smoke-test/SKILL.md && echo OK`
+→ verify: `grep -ci 'pass\|fail\|summary\|report' smoke-test/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
+→ verify: `grep -q 'smoke-test' SKILL-INDEX.md && echo OK`
+
+---
+
+## Reference block 1
+
+```yaml
+# smoke-checks.yaml — auto-loaded if present at project root
+base_url: "https://example.com"
+checks:
+  - name: "Homepage"
+    path: "/"
+    method: GET
+    expected_status: 200
+    content_signal: "bigpowers"
+    max_response_time_ms: 3000
+
+  - name: "API Health"
+    path: "/api/health"
+    method: GET
+    expected_status: 200
+    content_signal: "ok|healthy"
+
+  - name: "API Jogos"
+    path: "/api/jogos"
+    method: GET
+    expected_status: 200
+    content_signal: "jogos|games"
+
+  - name: "Not Found handling"
+    path: "/nonexistent"
+    method: GET
+    expected_status: 404
+    content_signal: "not found|404"
+```
+
+---
+
+## Reference block 2
+
+```bash
+SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+BASE_URL="${DEPLOY_URL:-$BASE_URL}"
+
+if [ -f "$SMOKE_CHECKS_FILE" ]; then
+  echo "Loaded smoke checks from $SMOKE_CHECKS_FILE"
+elif [ -n "$BASE_URL" ]; then
+  echo "No smoke-checks.yaml found. Using single URL check against $BASE_URL"
+else
+  echo "ERROR: No smoke-checks.yaml found and no DEPLOY_URL/BASE_URL set."
+  exit 1
+fi
+```
+
+---
+
+## Reference block 3
+
+```bash
+url="${BASE_URL}${path}"
+start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
+
+# Perform the HTTP request
+response=$(curl -s -o /tmp/smoke_body.txt -w "%{http_code}" "$url")
+response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
+status=$response
+body=$(cat /tmp/smoke_body.txt)
+```
+
+---
+
+## Reference block 4
+
+```bash
+checks_passed=0
+checks_failed=0
+failures=""
+
+# Assert status code
+if [ "$status" -ne "${expected_status:-200}" ]; then
+  echo "  FAIL: expected status ${expected_status} but got $status"
+  checks_failed=$((checks_failed + 1))
+  failures="${failures}  - $name: HTTP $status (expected ${expected_status})\n"
+else
+  echo "  PASS: HTTP $status"
+fi
+
+# Assert content signal
+if [ -n "$content_signal" ]; then
+  if echo "$body" | grep -qiE "$content_signal"; then
+    echo "  PASS: body contains \"$content_signal\""
+  else
+    echo "  FAIL: body does not contain \"$content_signal\""
+    checks_failed=$((checks_failed + 1))
+    failures="${failures}  - $name: missing content signal \"$content_signal\"\n"
+  fi
+fi
+
+# Assert response time
+if [ -n "$max_response_time_ms" ] && [ "$response_time" -gt "$max_response_time_ms" ]; then
+  echo "  FAIL: response time ${response_time}ms exceeds ${max_response_time_ms}ms"
+  checks_failed=$((checks_failed + 1))
+  failures="${failures}  - $name: response time ${response_time}ms (max ${max_response_time_ms}ms)\n"
+fi
+```
+
+---
+
+## Reference block 5
+
+```bash
+total=$((checks_passed + checks_failed))
+echo ""
+echo "=== Smoke Test Summary ==="
+echo "Total: $total | Passed: $checks_passed | Failed: $checks_failed"
+
+if [ "$checks_failed" -gt 0 ]; then
+  echo ""
+  echo "Failures:"
+  echo -e "$failures"
+  exit 1
+else
+  echo "All checks passed."
+  exit 0
+fi
+```

package/.windsurf/rules/spike-prototype.md

@@ -0,0 +1,95 @@
+---
+name: spike-prototype
+model: sonnet
+description: "Throw-away prototype for unknown problem spaces. Output is learning notes in specs/archive/spikes/SPIKE-<name>.md, not production code. Use when the domain or technology is unexplored, when estimates are impossible without experimentation, or when user says \"spike\", \"prototype\", or \"proof of concept\"."
+---
+
+# Spike Prototype
+> **HARD GATE** — **HARD GATE** — Spikes are time-boxed experiments, not shipping code. Results must be throwaway or clearly isolated. Do NOT merge a spike without a plan to integrate it or replace it with a proper implementation.
+
+
+A spike is a time-boxed experiment to answer a specific question. The code is thrown away. The learning is kept in `specs/archive/spikes/SPIKE-<name>.md`.
+
+**The spike produces learning, not code to ship.** If you find yourself cleaning up spike code for production, stop — run `plan-work` and `develop-tdd` instead with the insights you gained.
+
+## When to spike
+
+- The technology is unfamiliar (new library, API, infrastructure)
+- The approach is uncertain (multiple solutions exist; none has been tried)
+- Estimates are impossible without seeing how the thing actually behaves
+- A key assumption needs to be validated before committing to a design
+
+## Process
+
+### 1. Define the question
+
+Before writing a single line, state the question the spike must answer:
+
+> "Can we [specific thing] using [specific approach] within [constraint]?"
+
+Examples:
+- "Can we stream large files from S3 to the client without buffering in memory?"
+- "Does the Stripe webhook SDK handle signature verification correctly in our edge runtime?"
+- "Can we achieve < 100ms p99 response time for the search endpoint with a naive Postgres full-text search?"
+
+A spike with no question is just unplanned coding. Refuse to start if the question isn't clear.
+
+### 2. Set a timebox
+
+Agree on a timebox with the user: 30 minutes, 1 hour, 2 hours. When time is up, stop — even if the question isn't fully answered. Partial learning is still learning.
+
+### 3. Experiment
+
+Write the simplest code that could answer the question. Ignore:
+- Error handling
+- Test coverage
+- Code quality
+- Production concerns
+
+Focus entirely on answering the question.
+
+### 4. Write specs/archive/spikes/SPIKE-<name>.md
+
+Save the learning to `specs/archive/spikes/SPIKE-<name>.md`. Create the `specs/` directory if it doesn't exist.
+
+<spike-template>
+
+# Spike: [name]
+
+## Question
+
+[The specific question this spike was answering]
+
+## Result
+
+[Answered / Partially answered / Not answered]
+
+## Findings
+
+[What you learned — concrete observations, not opinions]
+
+## Evidence
+
+[Code snippet, benchmark result, API response, or screenshot that proves the finding]
+
+## Implications for the plan
+
+[How this changes the approach, the design, or the estimate]
+
+## What was NOT explored
+
+[Known gaps — things the spike didn't validate]
+
+## Recommendation
+
+[Should we proceed with this approach? If yes, what does plan-work need to account for?]
+
+</spike-template>
+
+### 5. Delete the spike code
+
+After writing the findings, delete or discard the spike code. It is not meant to ship.
+
+### 6. Feed back into plan-work
+
+The spike findings are the input to `plan-work`. Call `plan-work` next, informed by `specs/archive/spikes/SPIKE-<name>.md`.

package/.windsurf/rules/stocktake-skills.md

@@ -0,0 +1,72 @@
+---
+name: stocktake-skills
+model: sonnet
+description: "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected."
+---
+
+# story: e09s01
+<!-- story: e45s12 -->
+
+
+# Stocktake Skills
+> **HARD GATE** — **HARD GATE** — Skill inventory must be current. Missing HARD GATEs, stale descriptions, or broken verify commands are defects, not cosmetic. Fix them in `evolve-skill`.
+
+
+Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX mismatches.
+
+## Modes
+
+| Mode | Scope |
+|------|-------|
+| **Quick Scan** | Skills changed since last tag or in current diff |
+| **Full** | All skills per SKILL-INDEX.md + catalog audit |
+| **--verify** | Run `bash scripts/run-skill-verify.sh` and append health results to the stocktake report |
+
+## Process
+
+0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
+1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
+2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
+3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).
+4. **Effectiveness report (--full mode only):** Read `specs/state.yaml` `metrics.skill_timings` and report:
+   - Top 5 most-used skills (by calls, total_seconds)
+   - Skills with zero calls (potential dead weight)
+   - Skills with high average time (candidates for `evolve-skill`)
+5. Critical findings → `plan-work` story; cosmetic → `evolve-skill` candidate.
+6. **--verify mode:** Run `bash scripts/run-skill-verify.sh` and append a `## Verify Health` section to the stocktake report: `"N/68 PASS, M FAIL, K SKIP"`. FAIL skills are critical findings and go straight to `plan-work`.
+
+### Skill timing data (`metrics.skill_timings`)
+
+In `--full` mode, read `specs/state.yaml` `metrics.skill_timings` for per-skill usage stats:
+
+```yaml
+metrics:
+  skill_timings:
+    survey-context:
+      calls: 12
+      total_seconds: 180
+      avg_seconds: 15.0
+    develop-tdd:
+      calls: 30
+      total_seconds: 5400
+      avg_seconds: 180.0
+```
+
+Timing data is populated by `scripts/bp-timing.sh start|end <skill>` calls within critical-path skills.
+
+## Verify
+
+→ verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING`
+
+See [REFERENCE.md](REFERENCE.md) for checklist.
+
+---
+
+# Stocktake checklist
+
+- [ ] SKILL.md exists at repo root `&lt;name&gt;/SKILL.md`
+- [ ] Listed in SKILL-INDEX.md with correct phase
+- [ ] `description` includes "Use when..."
+- [ ] At least one HARD GATE callout
+- [ ] specs/ output documented if applicable
+- [ ] No edit to `.cursor/rules/` or `.gemini/` (generated only)