Cursor rule

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