Windsurf rules

1---
2name: build-epic
3model: sonnet
4description: "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."
5---
6 
7# story: e20s05
8 
9# Build Epic
10 
11Scope: one story. Called by orchestrate-project Phase 4. Not a replacement for orchestrate-project.
12 
13Orchestrates the **build** flow for a single epic: survey → plan tasks → kickoff → TDD → verify → audit → commit → release.
14 
15> **HARD GATE** — Set `specs/state.yaml` `active_flow: build_epic` and `active_epic: eNN` before starting.
16>
17> **HARD GATE** — Not on `main`/`master` before step 3 (kickoff-branch).
18 
19## Nine steps (`epic_cycle` in state.yaml)
20 
21| Step | Skill / action |
22|------|----------------|
23| 0 | `security-review` — threat-model epic scope → `specs/security/epics/<id>/THREAT_MODEL.md` |
24| 1 | `survey-context` — confirm epic + story |
25| 2 | `plan-work` — flesh out story `tasks[]` in `specs/epics/eNN-slug/epic.yaml` |
26| 3 | `kickoff-branch` — feature branch + clean baseline |
27| 4 | `develop-tdd` — red-green per task |
28| 5 | `verify-work` — UAT + mechanical gates |
29| 6 | `audit-code` — **non-optional gate** (pass/fail; fail → loop back to step 4) |
30| 7 | `commit-message` — Conventional Commits draft |
31| 8 | `release-branch` — PR or solo land (supports `--squash-state`) | |
32 
33## Process
34 
351. Read `specs/state.yaml`, `specs/execution-status.yaml`, `specs/release-plan.yaml`, active `specs/epics/eNN-slug/epic.yaml`.
36   - **On story start (step 1):** Write `started_at` ISO 8601 timestamp to `execution-status.yaml` under the story's key in the `stories:` section. The `bp-timing.sh` script already tracks skill-level timings — this is story-level.
372. **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.
383. **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.
394. **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`.
405. **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.
416. If `epic_cycle.step` missing, set to `1`.
426. Run **only the current step** (resume mode) unless user asked for full auto-run.
437. After step verify passes, increment `epic_cycle.step` in `state.yaml` (or `bash scripts/bp-yaml-set.sh` if available).
448. On story complete, set `execution-status.yaml` story key to `done`; run `bash scripts/sync-status-from-epics.sh`.
45   - **On story complete (step 8):** Write `completed_at` ISO 8601 timestamp to `execution-status.yaml` under the same story key. Format:
46 
47```yaml
48     stories:
49       e01s01:
50         status: done
51         started_at: "2026-07-12T16:00:00-03:00"
52         completed_at: "2026-07-12T18:45:00-03:00"
53```
549. **Traceability refresh:** Before step 8 (release-branch), run `bash scripts/trace-stories.sh` to regenerate `specs/traceability-matrix.json`, `specs/TRACEABILITY_LATEST.md`, and the `specs/codebase-wiki/` OKF bundle. Surface dark/orphan/stale findings for the just-built epic in your verify summary. If `scripts/trace-stories.sh` is missing or fails, note "trace skipped" and continue — trace failure must be visible, not silent (blocking is gate-trace's job, e38s06).
55 
569b. **OKF wiki refresh (e39s08):** Before step 8, run maintain-wiki INGEST to refresh the OKF wiki bundle:
57```bash
58   bash scripts/decompose-conventions.sh
59   bash scripts/generate-agent-guide.sh
60```
61   If any script is missing or fails, note "OKF wiki refresh skipped" and continue.
62   This is non-blocking — stale concepts are caught by LINT in verify-work Phase 3.
63 
64### Step 6 — audit-code gate (non-optional)
65 
66After step 5 (verify-work) completes successfully, step 6 runs `audit-code` automatically in `--gate` mode:
67 
681. **Run audit:** Invoke `audit-code --gate` on the complete diff for this story.
692. **Pass (exit 0):** All checklist sections pass → advance to step 7 (commit-message). Record `epic_cycle.audit_result: pass` in `state.yaml`.
703. **Fail (exit 1):** One or more checklist sections fail → **reset `epic_cycle.current_step` to `4`** (develop-tdd) and add the failing section IDs to `completed_steps` as `"1,2,3,4,5,6(fail: ...)"`. Record `epic_cycle.audit_result: fail` in `state.yaml`. Do NOT advance past step 6 until audit passes.
714. **Audit artifact:** Full audit report saved to `specs/verifications/AUDIT-<epic>-<story>.md` regardless of pass/fail, for reviewer traceability.
725. **Enforce F.I.R.S.T:** After audit-code passes, run `enforce-first --quick` on new/modified tests. Append F.I.R.S.T violations (if any) to the audit report. Failing F.I.R.S.T criteria trigger the same loop-back to step 4.
73 
74## --fast mode
75 
76Coalesces read-and-report steps to reduce token overhead. Activate with `build-epic --fast`.
77 
78| Normal | --fast | Change |
79|--------|--------|--------|
80| Step 1 (survey-context) | 1+2 together | survey + plan in one invocation |
81| Step 2 (plan-work) | (absorbed into 1) | — |
82| Step 3 (kickoff-branch) | Step 2 | unchanged, sequential |
83| Step 4 (develop-tdd) | Step 3 | unchanged, sequential |
84| Step 5 (verify-work) | Step 4 | unchanged, sequential |
85| Step 6 (audit-code) | 5+6 together | audit + commit-message in one invocation |
86| Step 7 (commit-message) | (absorbed into 6) | — |
87| Step 8 (release-branch) | Step 7 | unchanged, sequential |
88 
89**Total invocations:** 8 → 6 per story.
90 
91**Rules:**
92- Steps 3/4/5/8 (kickoff, develop, verify, release) still run sequentially — they require user interaction or branch state.
93- `--fast` does NOT skip any checklist items; it only coalesces steps that are pure read-and-report.
94- Record `epic_cycle.fast_mode: true` in `state.yaml` when this flag is active.
95 
96## Handoff
97 
98Write `handoff.next_skill` and `handoff.context` in `state.yaml` when pausing mid-epic.
99 
100## Verify
101 
102→ verify: `test -f specs/state.yaml && test -f specs/execution-status.yaml && test -f specs/release-plan.yaml && test -d skills/assess-impact && test -d skills/audit-code && test -d skills/security-review`
103 
104 
105<!-- story: e38s02 -->
106