ai-core-framework 0.1.0

package/core/skills/review-merge-pr/SKILL.md

@@ -0,0 +1,425 @@
+---
+name: review-merge-pr
+description: Use when the user asks to run /merge-pr, merge an approved pull request, enforce merge prerequisites, delete the branch, or advance the linked ticket to QA.
+command: /merge-pr
+display_name: "Merge Pull Request"
+version: 1.0.0
+owner_agent: tech-lead
+model_preference: sonnet
+args:
+  - name: pr_number
+    required: true
+    type: integer
+    description: "PR number to merge"
+  - name: strategy
+    required: false
+    type: string
+    default: "squash"
+    enum: [squash, merge, rebase]
+    description: "Merge strategy (squash default per RULE GIT-008)"
+preconditions:
+  - pr_exists: true
+  - pr_open: true
+  - pr_approved: true  # ≥1 approval from tech-lead
+  - pr_not_own: true   # Cannot merge own PR (RULE TL-005)
+  - ci_status: green
+  - no_unresolved_comments: true
+  - ticket_status: IN_REVIEW
+  - branch_up_to_date: true  # Merged with develop latest
+postconditions:
+  - pr_merged: true
+  - branch_deleted: true
+  - ticket_status: QA
+  - ci_triggered_on_develop: true
+---
+
+# /merge-pr
+
+> Merge approved PR into develop. Transitions ticket IN_REVIEW → QA.
+> **Final gate before code enters integration branch.**
+
+## 🎯 Purpose
+
+After review is approved, merge the PR with:
+1. Verify all gates still green (CI, approvals, comments resolved)
+2. Execute merge with correct strategy
+3. Delete source branch
+4. Update ticket → QA state
+5. Trigger QA smoke test notification
+
+## 🚦 Trigger
+
+**Manual** (primary):
+```
+/merge-pr 123
+```
+
+**With strategy override**:
+```
+/merge-pr 123 --strategy=merge    # For release PRs (preserve history)
+```
+
+**NOT auto-merge** — human/agent decision every time.
+
+## 📋 Preconditions (STRICT)
+
+### 1. PR exists + open
+```bash
+gh pr view "$PR_NUMBER" --json state | jq -e '.state == "OPEN"' || ABORT
+```
+
+### 2. Not own PR (RULE TL-005)
+```bash
+pr_author=$(gh pr view "$PR_NUMBER" --json author --jq .author.login)
+current_user=$(gh api user --jq .login)
+[ "$pr_author" != "$current_user" ] || ABORT "Cannot merge own PR (RULE TL-005)"
+```
+
+### 3. Approved by tech-lead
+```bash
+approvals=$(gh pr view "$PR_NUMBER" --json reviews --jq '[.reviews[] | select(.state == "APPROVED")] | length')
+[ "$approvals" -ge 1 ] || ABORT "No approval. Need tech-lead review first."
+```
+
+Verify approval is from tech-lead role (not just any developer).
+
+### 4. CI green
+```bash
+ci_state=$(gh pr checks "$PR_NUMBER" --json status --jq '.[].status' | sort -u)
+echo "$ci_state" | grep -q "SUCCESS" && ! echo "$ci_state" | grep -qE "(FAILURE|ERROR|PENDING)" || ABORT
+```
+
+### 5. No unresolved review comments
+```bash
+unresolved=$(gh api "repos/{owner}/{repo}/pulls/$PR_NUMBER/reviews" | jq '[.[] | select(.state == "CHANGES_REQUESTED")] | length')
+[ "$unresolved" -eq 0 ] || ABORT "Unresolved CHANGES_REQUESTED. Resolve first."
+```
+
+### 6. Ticket status = IN_REVIEW
+Read ticket from branch name. Must be IN_REVIEW.
+
+### 7. Branch up-to-date with develop
+```bash
+behind=$(gh pr view "$PR_NUMBER" --json mergeable --jq '.mergeable')
+[ "$behind" = "MERGEABLE" ] || ABORT "Merge conflict or stale. Rebase first."
+```
+
+### 8. No merge commits in feature branch (RULE GIT-012)
+Check commit history doesn't contain merge commits from other feature branches.
+
+## 🔄 Execution Flow
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ STEP 1: Validate preconditions (above)                   │
+├──────────────────────────────────────────────────────────┤
+│ STEP 2: Load context                                     │
+│   - PR metadata                                          │
+│   - Ticket JSON                                          │
+│   - Linked ADRs                                          │
+├──────────────────────────────────────────────────────────┤
+│ STEP 3: Final sanity checks                              │
+│   - Recheck CI status (in case just turned red)          │
+│   - Verify approving reviewer is actually tech-lead role │
+│   - Verify no new unresolved comments since approval     │
+├──────────────────────────────────────────────────────────┤
+│ STEP 4: Prepare merge message                            │
+│   Format (squash):                                       │
+│     <type>(TICKET-XXX): <PR title> (#PR_NUMBER)          │
+│                                                          │
+│     <PR description summary - first paragraph>           │
+│                                                          │
+│     Refs: ADR-XXXX (if any)                              │
+│     Closes: TICKET-XXX                                   │
+│     Reviewed-by: <tech-lead-handle>                      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 5: Execute merge                                    │
+│   gh pr merge $PR_NUMBER \                               │
+│     --<strategy> \                                       │
+│     --subject "<merge subject>" \                        │
+│     --body "<merge body>" \                              │
+│     --delete-branch                                      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 6: Verify merge success                             │
+│   - Check PR status = MERGED                             │
+│   - Check branch deleted                                 │
+│   - Check commit in develop history                      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 7: Update ticket                                    │
+│   - state: IN_REVIEW → QA                                │
+│   - merge_commit_sha: <sha>                              │
+│   - merged_at: <timestamp>                               │
+│   - state_history append                                 │
+├──────────────────────────────────────────────────────────┤
+│ STEP 8: Notify QA                                        │
+│   - Suggest: /smoke-test TICKET-XXX                      │
+│   - (Optional) Slack notification                        │
+├──────────────────────────────────────────────────────────┤
+│ STEP 9: Log metrics                                      │
+├──────────────────────────────────────────────────────────┤
+│ STEP 10: Output summary                                  │
+└──────────────────────────────────────────────────────────┘
+```
+
+## 🔒 Hard Rules
+
+### RULE MP-001: Only tech-lead merges
+`/merge-pr` **MUST** be invoked by tech-lead agent. Developer cannot merge.
+
+### RULE MP-002: No self-merge
+**MUST NOT** merge PR authored by the merger. Per RULE TL-005.
+
+### RULE MP-003: All gates must be green
+**MUST NOT** override:
+- Failing CI (even "flaky" — fix flakiness first)
+- Missing approval
+- Unresolved comments
+- Ticket wrong state
+
+No `--force` flag exists for a reason.
+
+### RULE MP-004: Squash by default
+Default strategy = `squash` (per RULE GIT-008). Keeps develop history clean.
+
+**Exceptions** (use merge commit):
+- Release PRs (develop → main)
+- PRs with valuable commit history (ADR: document decision)
+
+### RULE MP-005: Delete branch after merge
+**MUST** delete source branch. Enforce via `--delete-branch` flag.
+
+### RULE MP-006: Hotfix special flow
+If branch is `hotfix/*`:
+- Base = `main` (not develop)
+- After merge to main → MUST trigger cherry-pick to develop
+- See `commands/release/hotfix.md`
+
+### RULE MP-007: Ticket transition mandatory
+**MUST** update ticket IN_REVIEW → QA. Not PR merged is a BUG state.
+
+### RULE MP-008: Audit trail
+**MUST** log merge event:
+- Who merged
+- When
+- Which PR/ticket
+- Merge commit SHA
+- Strategy used
+
+Store in `project/audit-log.jsonl`.
+
+### RULE MP-009: Rollback plan for risky merges
+If PR flagged as `high-risk` (auth changes, DB migration, payment):
+- Document rollback plan in merge comment
+- Notify scrum-master
+
+### RULE MP-010: No merge Friday afternoon (configurable)
+If project policy: `config.merge_freeze.friday_afternoon: true`:
+- Block merges Friday 15:00+ (unless hotfix)
+- Rationale: avoid weekend fire
+
+Configurable in `project-config.yaml`.
+
+## 📥 Input Examples
+
+```
+/merge-pr 123                          # Standard squash merge
+/merge-pr 123 --strategy=merge         # Preserve history (release PR)
+/merge-pr 123 --force-flaky            # NOT ALLOWED - no such flag
+```
+
+## 📤 Output Format (Success)
+
+```markdown
+## ✅ PR Merged: #123
+
+**PR**: feat(TICKET-042): add password reset via email
+**Branch**: feature/TICKET-042-password-reset → develop
+**Merged by**: tech-lead-agent
+**Strategy**: squash
+**Merge commit**: abc1234def5678 on develop
+
+### Pre-merge Verification
+| Check | Status |
+|-------|--------|
+| CI | ✅ All green (47 checks) |
+| Approvals | ✅ 1 (tech-lead) |
+| Comments | ✅ All resolved |
+| Conflicts | ✅ None (auto-merge clean) |
+| Up-to-date | ✅ Rebased on develop@xyz890 |
+
+### Merge Message
+```
+feat(TICKET-042): add password reset via email (#123)
+
+Implements self-service password reset flow with email verification:
+- New endpoint POST /auth/request-reset
+- Rate limiting 5/hour/email
+- Secure 32-byte tokens, 24h expiration
+- SendGrid email integration
+
+Refs: ADR-0012
+Closes: TICKET-042
+Reviewed-by: tech-lead-agent
+```
+
+### Post-merge Actions
+- ✅ Source branch deleted (remote + suggest local cleanup)
+- ✅ CI triggered on develop (build + integration tests)
+- ✅ Ticket TICKET-042 transitioned IN_REVIEW → QA
+- ✅ Notification sent (Slack #releases)
+
+### Ticket Updated
+```json
+{
+  "id": "TICKET-042",
+  "status": "QA",
+  "merge_info": {
+    "pr_number": 123,
+    "merge_commit_sha": "abc1234",
+    "merged_at": "2026-04-18T16:30:00Z",
+    "merged_by": "tech-lead-agent",
+    "strategy": "squash"
+  }
+}
+```
+
+### Audit Log Entry
+```json
+{
+  "timestamp": "2026-04-18T16:30:00Z",
+  "event": "pr_merged",
+  "pr_number": 123,
+  "ticket_id": "TICKET-042",
+  "merger": "tech-lead-agent",
+  "author": "developer-agent",
+  "strategy": "squash",
+  "lines_changed": 279,
+  "commits_squashed": 7
+}
+```
+
+### Next Steps
+1. **QA**: `/smoke-test TICKET-042` on next deploy to staging
+2. **Developer**: Local cleanup - `git branch -D feature/TICKET-042-password-reset`
+3. **Scrum Master**: Update sprint board if using external tracker
+
+### Deployment
+- **Next deploy window**: Staging daily auto-deploy at 18:00 UTC
+- **Production**: Next release train (Tuesday)
+
+---
+HANDOFF → qa-tester
+Action needed: /smoke-test TICKET-042 after staging deploy
+```
+
+## 📤 Output Format (Failure)
+
+```markdown
+## ❌ Cannot Merge PR #123
+
+**Blockers**:
+1. CI failing (2 checks red)
+2. 1 unresolved review comment
+
+### Details
+
+#### Blocker 1: CI failing
+- `lint` ✅
+- `unit-tests` ✅
+- `integration-tests` ❌ (2 failures)
+- `e2e-tests` ❌ (timeout)
+
+**Action**: Check CI output, fix failures, push again.
+
+#### Blocker 2: Unresolved comment
+- Tech-lead comment on `src/auth/reset.ts:45` marked CHANGES_REQUESTED
+- Not yet resolved
+
+**Action**: Developer address comment, reply "Resolved" or update code.
+
+### State
+- PR: remains OPEN (unchanged)
+- Ticket: remains IN_REVIEW (unchanged)
+
+### Retry
+Once blockers resolved:
+```
+/merge-pr 123
+```
+```
+
+## 📤 Output Format (Self-merge attempt)
+
+```markdown
+## ❌ Cannot Merge Own PR
+
+**Reason**: You are the PR author.
+
+Per RULE TL-005: Tech lead cannot approve/merge own PR.
+
+### Options
+1. **Request review from another tech-lead** (if available)
+2. **Escalate to human** (solo tech-lead scenario)
+3. **Pair with a developer** on next PR (shared ownership)
+
+### State
+Unchanged. PR remains OPEN.
+```
+
+## 🚨 Failure Modes
+
+| Scenario | Action |
+|----------|--------|
+| PR closed | ABORT |
+| PR already merged | Notify, exit gracefully |
+| CI red | ABORT, show which checks |
+| No approval | ABORT, request /techlead-review |
+| Self-merge | ABORT with RULE TL-005 |
+| Conflicts | ABORT, instruct rebase |
+| Ticket wrong state | ABORT, show expected state |
+| Merge API fails | Retry 3x, escalate on persist |
+| Branch deletion fails | Non-fatal, log warning |
+| Ticket update fails | CRITICAL - manually sync |
+
+## 🔗 Related Commands
+
+- **Before**: `/techlead-review` (approval required)
+- **After**: `/smoke-test` (QA's next step)
+- **Alternatives**:
+  - `/hotfix` (for emergency merges to main)
+- **Rollback**: `git revert <merge_sha>` + create new PR
+
+## 📊 Metrics Tracked
+
+```json
+{
+  "timestamp": "2026-04-18T16:30:00Z",
+  "pr_number": 123,
+  "ticket_id": "TICKET-042",
+  "merger": "tech-lead-agent",
+  "duration_from_pr_created_hours": 26.5,
+  "duration_from_approval_hours": 2.3,
+  "review_iterations": 1,
+  "strategy": "squash",
+  "commits_squashed": 7,
+  "lines_added": 234,
+  "lines_removed": 45,
+  "size_category": "M"
+}
+```
+
+## 💡 Best Practices
+
+**For Tech Leads**:
+- Merge within 1 hour of final approval (keep momentum)
+- Don't accumulate PRs waiting to merge (context switch)
+- Communicate if delaying merge (dev waiting)
+
+**For Developers (your PR about to merge)**:
+- Keep terminal open, watch for merge notification
+- Clean local branch after: `git checkout develop && git pull && git branch -D <feature>`
+- Celebrate small wins 🎉
+
+---
+**Last updated**: 2026-04-18
+**Maintainer**: Tech Lead