Windsurf rules

1---
2name: release-branch
3model: haiku
4description: "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\"."
5---
6 
7<!-- story: e38s07 -->
8<!-- story: e45s15 -->
9<!-- story: e45s32 -->
10<!-- story: e45s39 -->
11<!-- story: e20s02 -->
12 
13 
14# Release Branch
15 
16> **HARD GATE** — Do NOT merge or release if tests fail or if coverage gates are not met. If the branch is red, return to `develop-tdd` to fix regressions or add missing tests before proceeding.
17 
18Finalize a completed feature branch: verify coverage gates, integrate onto `main`, and clean up the worktree.
19 
20## Additional modes
21- `--hotfix`: Cherry-pick to main + tag. Skip PR in solo.
22- `--squash-state`: Squash `chore(state):` commits before merge.
23 
24## Integrate mode
25 
26Read `specs/state.yaml` key `workflow_mode` (`team-pr` | `solo-git`). Fall back to `profiles/solo-git.md`.
27 
28| Mode | When | Ship path |
29|------|------|-----------|
30| **solo-local** | `workflow_mode: solo-git` | Auto: `scripts/land-branch.sh` if present, else fallback (Step 5) |
31| **team-pr** | `workflow_mode: team-pr` (default) | `gh pr create` → `gh pr merge --squash` |
32 
33If unsure, prefer **solo-local**.
34 
35## Process
36 
37> **Timing:** `bash scripts/bp-timing.sh start release-branch` at invocation; `bash scripts/bp-timing.sh end release-branch` before handoff.
38 
39### 1. Final verification
40 
41```bash
42&lt;full test command&gt; && &lt;typecheck command&gt; && &lt;lint command&gt;
43git log main...HEAD --oneline | grep -vE &quot;^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$&quot; && echo &quot;❌ Non-conventional commits found&quot; || echo &quot;✅ Commits verified&quot;
44# Block AI agent attribution (P1)
45git log main...HEAD --format=&quot;%B&quot; | grep -qiE 'co[- ]authored[- ]by' && echo &quot;❌ Co-authored-by footer found — blocked&quot; || echo &quot;✅ No AI attribution&quot;
46```
47 
48- [ ] All tests pass, no type errors, no lint violations, all commits follow Conventional Commits
49- [ ] **NO `Co-authored-by` or `Co-Authored-By`** in any commit body — P1 rule (CONVENTIONS.md § Git Attribution). `land-branch.sh` blocks the merge if found.
50 
51### 2. Coverage check
52 
53- [ ] Overall coverage ≥ 80%; business logic coverage ≥ 95%
54 
55### 2a. Security gate
56 
57- [ ] `specs/security/REVIEW.md` exists and is fresh (matches current branch diff)
58- [ ] No unresolved HIGH findings with confidence ≥ 8 (or all documented in `specs/security/EXCEPTIONS.md` with sign-off rationale)
59 
60If REVIEW.md is missing or stale → run `security-review` inline. Findings block the merge unless documented in EXCEPTIONS.md.
61 
62### 2b. Traceability gate
63 
64Run `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.
65 
66> **Adversarial refute framing (e45s32):** The final pre-merge check is **refute, not rubber-stamp**. Before declaring ready, actively try to disprove traceability completeness — missing story tags, absent verify evidence, stale security review. Only proceed when refutation fails.
67 
68### 3. Diff review
69 
70- [ ] All commits intentional, no secrets, CONVENTIONS.md compliance
71 
72### 4. Decision
73 
74Options: **Release (solo-local)** / **Open PR** / **Keep branch** / **Discard**
75 
76### 5. Solo-local integrate
77 
78Run `commit-message` for the squash subject, then land:
79 
80```bash
81# Path A (preferred):
82bash scripts/land-branch.sh &lt;task-slug&gt; &quot;feat(scope): description&quot;
83# Path B (fallback if land-branch.sh missing): see REFERENCE.md
84```
85 
86### 6. Create PR (team-pr only)
87 
88Create the pull request with a **literal provenance marker** in the body so agent-generated PRs are identifiable and do not rot silently:
89 
90```markdown
91<!-- bigpowers-provenance: agent-generated -->
92```
93 
94Place the marker on its own line immediately after the `## Summary` heading. Then merge via `gh`:
95 
96```bash
97gh pr create --title &quot;...&quot; --body &quot;$(cat &lt;&lt;'EOF'
98## Summary
99&lt;!-- bigpowers-provenance: agent-generated --&gt;
100 
101- ...
102 
103## Test plan
104- [ ] ...
105 
106EOF
107)&quot;
108gh pr merge --squash --delete-branch
109```
110 
111`semantic-release` auto-detects the commit, bumps SemVer, tags the repo, generates release notes.
112 
113### 7a. Archive completed epic capsule
114 
115> **HARD GATE** — When all epic stories are done (all `done` in `execution-status.yaml`), archive the capsule:
116 
117```bash
118mv specs/epics/eNN-slug specs/epics/archive/
119```
120 
121### 7b. CI verification & agent lock release (e39s02)
122 
123> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release).
124 
125```bash
126bash scripts/wait-for-ci.sh --timeout 600 --interval 30
127```
128 
129- [ ] CI passes; `release.ci_verified: true` in state.yaml
130- On failure: `handoff.next_skill = fix-bug`
131 
132### 8. Clean up & return
133 
134Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time).
135 
136Report: "Branch released."
137 
138## Verify
139 
140→ verify: `command -v gh >/dev/null 2>&1 && test -f specs/state.yaml && test -d skills/verify-work`
141 
142---
143 
144# Release Branch — Reference
145 
146## Navigation
147 
148| Lines | Section |
149|-------|---------|
150| 1 | Title |
151| 3–22 | Navigation |
152| 23–31 | PR body template (team-pr mode) |
153| 32–35 | Summary |
154| 36–41 | Verify |
155| 42–47 | specs/ artifacts |
156| 48–58 | Worktree cleanup details |
157| 59–81 | Cycle-time recording |
158| 82–100 | Why not story_start minus story_end? |
159| 101–121 | CI verification |
160| 122–127 | Solo-local fallback detail |
161| 128–134 | Handoff |
162| 135–159 | Reference block 1 |
163 
164# Release Branch — Reference
165 
166## PR body template (team-pr mode)
167 
168```bash
169PR_TITLE=&quot;&lt;type&gt;(&lt;scope&gt;): &lt;description&gt;&quot;
170echo &quot;$PR_TITLE&quot; | grep -vE &quot;^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?: .+$&quot; && echo &quot;❌ ERROR: PR Title must follow Conventional Commits&quot;
171
172gh pr create \
173  --title &quot;$PR_TITLE&quot; \
174  --body &quot;$(cat &lt;&lt;'EOF'
175## Summary
176- [What this PR does]
177- [Key decisions made]
178 
179## Verify
180- [ ] All tests pass
181- [ ] Coverage gates met (≥80% overall, ≥95% business logic)
182- [ ] CONVENTIONS.md compliance verified
183- [ ] PR Title follows Conventional Commits (for automated release)
184 
185## specs/ artifacts
186- [List any specs/ files produced or updated]
187EOF
188)&quot;
189```
190 
191## Worktree cleanup details
192 
193```bash
194# From the main repo root
195git worktree prune
196git worktree remove ../&lt;branch-name&gt; 2&gt;/dev/null || true
197git branch -d &lt;branch-name&gt;
198```
199 
200If `git worktree remove` fails due to uncommitted changes, ask: "There are uncommitted changes in the worktree. Force remove? (y/n)". If yes: `git worktree remove -f ../<branch-name>`.
201 
202## Cycle-time recording
203 
204After landing the branch, record delivery metrics using the git-derived,
205additive script (replaces hand-arithmetic):
206 
207```bash
208bash scripts/record-cycle-time.sh append \
209  --story &lt;story_id&gt; --bcps &lt;bcps&gt; \
210  --range &quot;$(git merge-base main HEAD)..HEAD&quot; \
211  --file specs/metrics/cycle-times.yaml
212```
213 
214This appends a row to the cycle-times ledger with two separated metrics:
215 
216- **effort_hours** — ADDITIVE. Idle-stripped estimated effort from git commit
217  history (git-hours model: 120-min session threshold, 120-min first-commit pad).
218  Sums exactly to whole-repo effort. NO hand-arithmetic, NO wall-clock includes.
219- **lead_time_minutes** — calendar latency from first commit to merge.
220  Median-aggregated across stories; NEVER summed.
221 
222The script also runs an additivity self-check: Σ(story effort) == whole-repo effort
223within rounding tolerance.
224 
225### Why not story_start minus story_end?
226 
227The previous hand-arithmetic approach (survey-context writes `story_start`,
228release-branch writes `story_end`, agent hand-computes `cycle_minutes`) was
229retired because:
230 
2311. It was **agent-self-reported** — trivially fabricated or mis-subtracted.
2322. Wall-clock included **overnight/weekend/UAT gaps** — calendar latency,
233   not coding effort.
2343. The `bcp_per_hour` metric was **computationally meaningless** (velocity
235   derived from a latency measurement).
236 
237The new approach derives effort from commit history (objective, reproducible)
238and lead time from first commit → merge (honest calendar latency). See
239`docs/references/bcp.md` for BCP sizing context and
240`scripts/record-cycle-time.sh` for the full algorithm.
241 
242---
243 
244## CI verification
245 
246The CI polling logic has been extracted to `scripts/wait-for-ci.sh`.
247See the script's `--help` for usage. Step 7b of the main SKILL.md invokes it directly:
248 
249```bash
250bash scripts/wait-for-ci.sh --timeout 600 --interval 30
251```
252 
253**Exit codes:**
254- **0** — all workflows green. Set `release.ci_verified: true` in state.yaml.
255- **1** — at least one workflow failed. Prints failure URLs. Set `handoff.next_skill = fix-bug`.
256- **2** — timeout. CI did not complete. Retry or investigate.
257- **0 with warning** — `gh` CLI not available, git-only fallback confirmed push landed but CI status unverified.
258 
259The script handles: auto-discovery of all workflows for the current
260branch/commit, polling until completion, success/failure/timeout exit codes,
261and git-only fallback when `gh` CLI is unavailable.
262 
263---
264 
265## Solo-local fallback detail
266 
267The fallback sequence (Path B above) handles the "remote has moved" case with `git pull --rebase`. Use when `scripts/land-branch.sh` is absent.
268 
269**Acceptance:** When fallback runs, main is updated, feature branch is deleted locally, and output states `"used fallback merge (land-branch.sh not found)"`.
270 
271## Handoff
272 
273Gate: READY -> next: survey-context
274Writes: state.yaml handoff.next_skill = survey-context
275 
276---
277 
278## Reference block 1
279 
280```bash
281# Fallback: manual squash-merge when land-branch.sh is absent
282FEATURE_BRANCH=&lt;task-slug&gt;
283DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2&gt;/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
284 
285# Ensure we're on the feature branch
286if [ &quot;$(git branch --show-current)&quot; != &quot;$FEATURE_BRANCH&quot; ]; then
287  git checkout &quot;$FEATURE_BRANCH&quot;
288fi
289 
290# Checkout default branch and update
291git checkout &quot;$DEFAULT_BRANCH&quot;
292git pull --rebase origin &quot;$DEFAULT_BRANCH&quot; 2&gt;/dev/null || git pull origin &quot;$DEFAULT_BRANCH&quot;
293 
294# Squash-merge the feature branch
295git merge --no-ff &quot;$FEATURE_BRANCH&quot; -m &quot;&lt;conventional-commit-message&gt;&quot;
296 
297# Push
298git push origin &quot;$DEFAULT_BRANCH&quot;
299 
300# Clean up local feature branch
301git branch -d &quot;$FEATURE_BRANCH&quot;
302```
303