bigpowers 2.87.4 → 2.87.5

package/.cursor/rules/smoke-test.mdc

@@ -0,0 +1,260 @@
+---
+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."
+alwaysApply: false
+---
+
+# 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 HTTP checks against live URLs. Each check asserts HTTP status, optional body signal (regex), and optional response-time threshold.
+
+## Configuration
+
+Smoke checks live in `smoke-checks.yaml` at the project root:
+
+```yaml
+base_url: "https://example.com"
+checks:
+  - name: "Homepage"
+    path: "/"
+    expected_status: 200
+    content_signal: "welcome|ok"
+    max_response_time_ms: 3000
+```
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Human-readable check name |
+| `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 in response body |
+| `max_response_time_ms` | No | — | Fail if slower than threshold (ms) |
+
+Ad-hoc single-URL mode: `DEPLOY_URL=https://host bash scripts/run-smoke.sh`
+
+## Process
+
+### 1. Load checks
+
+```bash
+SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+BASE_URL="${DEPLOY_URL:-$BASE_URL}"
+test -f "$SMOKE_CHECKS_FILE" || test -n "$BASE_URL" || { echo "ERROR: no checks file or URL"; exit 1; }
+```
+
+### 2. Run each check
+
+```bash
+bash scripts/run-smoke.sh "${DEPLOY_URL:-}" "${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
+```
+
+The runner performs curl requests per check, records pass/fail per assertion, and prints a summary.
+
+### 3. Assert results
+
+- Any HTTP status mismatch → FAIL
+- Missing `content_signal` when configured → FAIL
+- Response time over `max_response_time_ms` → FAIL
+- Exit code non-zero → deployment not healthy
+
+### 4. Generate report
+
+Capture stdout from `run-smoke.sh` as evidence. Persist to `specs/verifications/smoke-<date>.log` for release-branch.
+
+## Integration with deploy skill
+
+```bash
+DEPLOY_URL="$DEPLOY_URL" bash scripts/run-smoke.sh
+```
+
+## Verify arc
+
+Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
+
+## Verify
+
+→ verify: `test -x scripts/run-smoke.sh && grep -q 'run-smoke.sh' skills/smoke-test/SKILL.md && ! grep -q 'See \[REFERENCE.md\](REFERENCE.md)$' skills/smoke-test/SKILL.md && echo OK`
+
+---
+
+# Smoke Test — Reference
+
+## Navigation
+
+| Lines | Section |
+|-------|---------|
+| 1 | Title |
+| 3–17 | Navigation |
+| 18–34 | Runner script |
+| 35–46 | Configuration reference |
+| 47–55 | Verification |
+| 56–89 | Reference block 1 |
+| 90–107 | Reference block 2 |
+| 108–122 | Reference block 3 |
+| 123–159 | Reference block 4 |
+| 160–177 | Reference block 5 |
+
+## Runner script
+
+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/.cursor/rules/spike-prototype.mdc

@@ -0,0 +1,94 @@
+---
+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\"."
+alwaysApply: false
+---
+
+# 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/.cursor/rules/stocktake-skills.mdc

@@ -0,0 +1,73 @@
+---
+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."
+alwaysApply: false
+---
+
+# story: e09s01
+<!-- story: e45s12 -->
+<!-- story: e79s04 -->
+
+
+# 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).
+0b. **Agentic STE audit (e79s04)** — run `bash scripts/validate-agentic-ste.sh --audit skills/`. Flag hedge words and sentences over 20 words per [AGENTIC-STE.md](../../docs/AGENTIC-STE.md). Record WARN lines in the stocktake report as **STE debt** — do NOT rewrite the full catalog in one pass. Route critical repeat offenders to `evolve-skill`.
+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: `compgen -G 'specs/STOCKTAKE-*.md' >/dev/null && bash scripts/validate-skill-catalog.sh`
+
+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)

package/.cursor/rules/survey-context.mdc

@@ -0,0 +1,134 @@
+---
+description: "Per-task context bootstrap — reads existing specs/ and tech-architecture docs to map the current lifecycle phase and suggest the next skill. Use at the start of any task, when returning after a break, or when unsure what to do next. For deriving a tech-stack doc from scratch, use map-codebase first."
+alwaysApply: false
+---
+
+# Survey Context
+
+Read the project's current state and give a phase map + next-skill recommendation. This is the "where am I?" skill — run it at the start of every task.
+
+> **Use this vs map-codebase:** `survey-context` consumes existing specs and docs (fast; does not re-derive). `map-codebase` builds the tech-stack doc from scratch by scanning the codebase. Run `map-codebase` when `specs/tech-architecture/tech-stack.md` doesn't exist yet; run `survey-context` when it does.
+
+> **HARD GATE** — Read specs/ files before suggesting next steps. If state.yaml is stale or contradicts the codebase, request clarification rather than assuming intent.
+
+Orchestrate-project 6 phases: Phase 1 Discover - Phase 2 Elaborate - Phase 3 Plan - Phase 4 Build - Phase 5 Verify - Phase 6 Release
+
+## Process
+
+> **Timing:** `bash scripts/bp-timing.sh start survey-context` at invocation; `bash scripts/bp-timing.sh end survey-context` before handoff.
+
+### 1. Read CONVENTIONS.md
+
+If `CONVENTIONS.md` exists at the project root, read it first. It contains the rules all agents must follow in this project.
+
+### 2. Read specs/ (YAML-first)
+
+Scan the `specs/` directory if it exists:
+
+```
+specs/
+├── state.yaml                  → session: active_flow, epic, git, handoff
+├── release-plan.yaml           → target version, WSJF epic index
+├── execution-status.yaml       → flat story/epic status
+├── planning-status.yaml        → discover-phase checklist (optional)
+├── requirements/
+│   ├── VISION_LATEST.yaml
+│   ├── SCOPE_LATEST.yaml
+│   └── GLOSSARY_LATEST.yaml
+├── plans/                      → TECH_STACK, TEST_PLAN, etc.
+├── epics/                      → eNN shards (flat yaml or eNN/stories/)
+└── bugs/                       → BUG-*.md + registry.yaml
+```
+
+For each YAML file found, note: exists? keys populated? `handoff.next_skill`?
+
+Legacy markdown (`specs/archive/STATE.md`, `RELEASE-PLAN.md`) is **not** SoT if YAML exists.
+
+→ verify: `bash scripts/validate-specs-yaml.sh`
+
+### 3. Read CLAUDE.md
+
+If `CLAUDE.md` exists at the project root, read it for project context (stack, commands, architecture, conventions).
+
+### 4. Check git state
+
+```bash
+git status --short
+git log --oneline -5
+git branch --show-current
+```
+
+Note: is there a feature branch active? Are there uncommitted changes? Do they match `specs/state.yaml` `git` block?
+
+### 5. Map the lifecycle phase
+
+Based on what you've found, identify which PMBOK phase this project is currently in:
+
+| Phase | Signals |
+|-------|---------|
+| **Discover** | No `requirements/SCOPE_LATEST.yaml` yet, or only rough notes |
+| **Design** | SCOPE exists but no `release-plan.yaml` |
+| **Plan** | `release-plan.yaml` exists; on `main`/`master` branch |
+| **Initiate** | On a feature branch; no code changes yet |
+| **Execute** | `state.yaml` `active_flow: build_epic`; epic capsule in progress |
+| **Verify** | Implementation done; run `verify-work` or `run-evals` |
+| **Bug** | `state.yaml` `active_flow: fix_bug` or open `specs/bugs/BUG-*.md` |
+| **Review** | All code written; no PR yet |
+| **Integrate** | PR open; tests passing |
+| **Sustain** | Ongoing; no active task |
+
+Prefer `specs/state.yaml` `active_flow` and `handoff.next_skill` when present.
+
+### 6. Suggest next skill
+
+Based on the phase and state, recommend the most useful next step:
+
+- **If in Plan/Bug phase and on `main`**: Suggest `kickoff-branch` next.
+- **If in Initiate phase**: Suggest `develop-tdd` or `execute-plan` or `ship-epic`.
+- **If in Execute phase**: Suggest `ship-epic` (resume) or `develop-tdd` for `active_story_id`.
+- **If in Verify phase**: Suggest `verify-work` (UAT) or `run-evals`.
+
+Example:
+```
+Phase: Execute
+Active branch: feat/e02-verify (state.yaml matches)
+release-plan.yaml: v3.0.0, 10 epics
+active_epic_id: e02
+
+Suggested next: ship-epic (resume e02s01 at develop-tdd)
+```
+
+Be specific — name the exact skill and why. If multiple options exist, list them in priority order.
+
+### 7. Surface blockers
+
+If something looks wrong:
+- Broken tests in the baseline
+- Open `specs/bugs/BUG-*.md` with no active fix branch
+- Epic shards missing `verify:` on tasks
+- `validate-specs-yaml.sh` fails
+- Git hash in `state.yaml` stale vs `git rev-parse`
+
+Report blockers first, before recommendations.
+
+### 8. Record story start timestamp
+
+At story start, write `metrics.story_start` with the current ISO 8601 timestamp to `specs/state.yaml` as an **informational progress marker only** — not a measurement input. Cycle-time metrics are now derived from git commit history via `scripts/record-cycle-time.sh` (see `skills/release-branch/REFERENCE.md` §Cycle-time recording).
+
+## Utility outputs
+
+### list-epics (absorbed)
+
+Loop through all `specs/epics/*/epic.yaml` files and print a summary of story counts per epic. Useful for understanding overall project scope and epic distribution.
+
+### check-gates (absorbed)
+
+Print the current `active_flow` from `specs/state.yaml`, run `bash scripts/validate-specs-yaml.sh` to verify YAML integrity, and show `git status` to report uncommitted changes and branch state. Use before handoffs or context transitions.
+
+## Handoff
+
+Gate: READY -> next: plan-work
+Writes: state.yaml handoff.next_skill = plan-work
+
+
+<!-- story: e03s03 -->

package/.cursor/rules/terse-mode.mdc

@@ -0,0 +1,41 @@
+---
+description: "Fallback ultra-compressed communication mode. Cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. Use ONLY when context is critically long and compressing output is necessary to continue. Not a strategy — token discipline comes from code shape (small functions, unique names, headless tests), not terser prompts. Use when user says \"caveman mode\", \"terse mode\", \"less tokens\", \"be brief\", or invokes /terse-mode."
+alwaysApply: false
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+> **HARD GATE** — **HARD GATE** — Terse mode is for reducing token usage in long sessions. Do NOT use terse mode when clarity is critical (complex design decisions, bug investigations). Enable it only on explicit user request.
+
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+## Auto-Clarity Exception
+
+Drop terse temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Terse resume. Verify backup exist first.
+
+
+
+<!-- story: e04s02 -->

package/.cursor/rules/trace-requirement.mdc

@@ -0,0 +1,68 @@
+---
+description: "Link story IDs from specs/release-plan.yaml + epic capsule directories to the implementing code and tests. Produces specs/TRACEABILITY_LATEST.md. Use when you want to verify coverage of a release plan, audit which stories are implemented, or find \"dark\" stories with no code."
+alwaysApply: false
+---
+
+# Trace Requirement
+
+Build a traceability matrix from `specs/release-plan.yaml + epic capsule directories` to implementing code and tests. Surfaces gaps in both directions: stories with no code, and code with no story.
+
+## Pre-flight
+
+> **HARD GATE** — `specs/release-plan.yaml + epic capsule directories` must exist. If it doesn't, run `plan-release` first.
+
+→ verify: `test -f specs/release-plan.yaml && test -d specs/epics`
+
+Read `specs/release-plan.yaml + epic capsule directories` fully before proceeding.
+
+## Process
+
+### 1. Extract story IDs
+
+From release-plan.yaml, collect all story IDs (e.g. `1.1`, `1.2`, `2.1`).
+
+→ verify: `grep -rho 'e[0-9]\+s[0-9]\+' specs/release-plan.yaml specs/epics/*/epic.yaml 2>/dev/null | sort -u | head -1 | grep -q .`
+
+### 2. Search for story tags in code
+
+Look for `// story: X.Y` or `# story: X.Y` comments in source files and tests:
+
+```
+grep -rn "story: " . --include="*.ts" --include="*.js" --include="*.py" --include="*.sh" | grep -v node_modules
+```
+
+→ verify: `[ "$(grep -rl "story: " . --include="*.ts" --include="*.sh" --include="*.py" 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]`
+
+### 3. Build the matrix
+
+For each story ID:
+- **Implemented**: list files that contain `// story: X.Y`
+- **Tested**: list test files that contain `// story: X.Y`
+- **Dark**: story has no tag in any file — flag as unimplemented
+
+For each tagged file with no matching story ID in release-plan.yaml:
+- **Orphan**: code exists but story was removed or never planned — flag for cleanup
+
+### 4. Write specs/TRACEABILITY_LATEST.md
+
+```
+## Story Coverage
+
+| Story | Title              | Files | Tests | Status    |
+|-------|--------------------|-------|-------|-----------|
+| 1.1   | [title]            | 2     | 1     | Covered   |
+| 1.2   | [title]            | 0     | 0     | Dark      |
+
+## Orphan Code (no story tag)
+- [file]: contains untagged implementation
+
+## Gaps (dark stories)
+- Story 1.2: no implementation found → run plan-work
+
+## Coverage summary
+Stories: [X] covered / [Y] dark / [Z] total
+```
+
+→ verify: `grep -c "Covered\|Dark" specs/TRACEABILITY_LATEST.md`
+
+Suggest `plan-work` for each dark story found.