PR Lifecycle

PR Lifecycle — All 8 Stages

Stage 1: Issue Creation

• Pillar: MCP / CLI
• GitHub: gh issue create
• Forgejo: mcp__forgejo__create_issue() or mcp__forgejo__create_issue_and_branch()
• Hook: check-issue.sh (PreToolUse) blocks Write/Edit without a valid issue
• Labels: Ava applies type:feature, type:bug, or type:devops at creation

Stage 2: Branch & Development

• Pillar: Hooks enforce
• Hook: block-main-commits.sh (PreToolUse) prevents direct commits to main
• Hook: check-issue.sh (PreToolUse) validates branch name contains issue number
• SOP: worktree-workflow — one worktree per issue
• Labels: Dev agent sets status:in-progress on the Forgejo issue after creating branch

Stage 3: PR Submission

• Pillar: MCP / CLI + Hooks
• GitHub: gh pr create
• Forgejo: mcp__forgejo__submit_pr()
• Hook (Bash): remind-review-loop.sh (PostToolUse) — reminds review-fix loop
• Hook (MCP): remind-mcp-review-loop.sh (PostToolUse on mcp__forgejo__submit_pr) — same reminder
• Template: get_note(slug="template-pr-body")
• Labels: Dev agent sets status:qa on the Forgejo issue, comments on issue with PR URL

Stage 4: Review-Fix Loop

• Pillar: Skills + Agents
• Skill: /review-pr orchestrates the loop
• Forgejo: mcp__forgejo__review_pr() for diff, mcp__forgejo__comment_on_pr() for comments
• GitHub: gh pr diff, gh pr comment
• SOP: pr-review-loop — fresh reviewer each round, repeat until clean
• Labels: QA sets status:approved (clean pass) or status:needs-fix (issues found) on the Forgejo issue. QA comments findings on the issue (not the PR) — one thread per work item.
• Fix iteration: Dev fixes, sets status:qa again. QA re-reviews. Repeat until status:approved.

Stage 5: Sprint Board Sync

• Pillar: Ava (MCP)
• Action: Ava reads labels on the Forgejo issue, updates sprint board column to match
• Action: Ava links PR URL to the sprint item note
• Mapping: status:qa → qa column, status:approved → needs_approval column, status:needs-fix → next_up column
• DORA data: Each label transition generates a timestamp for Lead Time, CFR, and Plan-to-Ship metrics

Stage 6: Present to User

• Pillar: Agent behavior (SOP-enforced)
• SOP: solo-dev-pr-workflow — present link and STOP
• Rule: NEVER merge without explicit user approval

Stage 7: Merge

• Pillar: Hooks guard + MCP/CLI execute
• Hook (Bash): block-pr-merge.sh (PreToolUse) — "ask" permission for gh pr merge
• Hook (MCP): block-mcp-merge.sh (PreToolUse on mcp__forgejo__merge_approved_pr) — "ask" permission
• GitHub: gh pr merge --admin --squash
• Forgejo: mcp__forgejo__merge_approved_pr() — verifies merge succeeded

Stage 8: Post-Merge Documentation Update

• Pillar: Hooks remind + Skill structures + SOP defines
• Hook (Bash): post-merge-rebase.sh (PostToolUse) — fast-forwards local main
• Hook (MCP): post-mcp-merge-rebase.sh (PostToolUse on mcp__forgejo__merge_approved_pr) — same
• Hook: remind-update-docs.sh (PostToolUse) — reminds Ava to run /update-docs
• Hook: remind-sprint-update.sh (PostToolUse) — reminds Ava to update sprint item
• Skill: /update-docs — the executable checklist. See skill-update-docs.
• SOP: sop-post-merge-docs — the full checklist and the rule: merged does not mean done.
• Gate: Sprint item cannot move to done until docs are current. The docs update is the gate, not the merge.
• Checklist (walk up the traceability chain):

What Changed (2026-03-03)

• Label signaling integrated. Stages 2-4 now include Forgejo label steps (status:in-progress, status:qa, status:approved/needs-fix).
• Stage 5 added: Sprint Board Sync — Ava reads labels and syncs board columns.
• Stage 8 expanded: Post-merge now includes the full documentation update checklist with /update-docs skill and sop-post-merge-docs SOP. Docs update is the gate before "done."
• Mermaid diagram updated to show QA agent and Ava as participants.
• QA comments on issues, not PRs. One thread per work item, findings stay with the spec.