[Phase 4A] PR Status: PROOF9-gated merge button

[frankbria]

Goal

Add a PROOF9-gated [Merge] button to the PR Status panel so the merge action enforces proof obligations before it becomes available.

Background

Follows the PR Status panel (#570). "Merge is gated on PROOF9 pass" is a core vision statement. Without a merge gate in the UI, this guarantee only exists in the CLI. The [Merge] button should be the last action in the SHIP phase.

Scope

[Merge] button (added to the PR Status panel from #570):

• Calls POST /api/v2/pr/merge with the PR number
• Active only when both conditions are met:
  1. All CI checks have passed
  2. PROOF9 GET /api/v2/proof/status returns no open (non-waived) requirements for the current workspace
• Blocked state (either condition unmet): button is disabled with a tooltip explaining what's blocking
• PROOF9 blocking message: if open requirements are blocking, show an inline list of the blocking REQ titles with a link to the PROOF9 page
• CI blocking message: if CI is still running or failing, show "Waiting for CI checks" / "CI checks failing"
• On merge success: show confirmation banner, stop polling

Acceptance criteria

• [Merge] button disabled when CI failing or open PROOF9 requirements exist
• Blocking reason shown inline with PROOF9 link when applicable
• Merge calls correct API endpoint and shows success state
• npm test pass

[coderabbitai]

🔗 Related PRs

#461 - feat(web-ui): PROOF9 requirements list, detail, and dashboard widget (#458) [merged]
#491 - feat(web-ui): surface PROOF9 gate link in execution completion banner (#469) [merged]
#492 - feat(web-ui): PROOF9 terminology tooltips and glossary on Proof page (#470) [merged]
#496 - feat(web-ui): link failed tasks to PROOF9 gate failure for root cause (#474) [merged]
#526 - feat(web-ui): sort and filter controls for Proof requirements table [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The web-ui is a Next.js 16 + React 19 app using swr for data fetching, axios for API calls, @radix-ui for UI primitives (including Tooltip), and @hugeicons/react for icons. The backend merge endpoint already exists at POST /api/v2/pr/{pr_number}/merge in file:codeframe/ui/routers/pr_v2.py. The proofApi.getStatus method and ProofStatusResponse type are already defined in file:web-ui/src/lib/api.ts and file:web-ui/src/types/index.ts. Issue #570's PR Status panel is the parent component this work extends — it does not yet exist in the codebase and must be created as part of this ticket.

Approach

Create a PRStatusPanel component that wraps the existing PR status display (from #570) and adds a PROOF9-gated Merge button. The component fetches proof status via proofApi.getStatus (already in api.ts) and calls a new prApi.merge method. The button's enabled/disabled state is derived from both CI status and open PROOF9 requirements. Tests follow the Jest + React Testing Library pattern established in file:web-ui/__tests__/app/proof/page.test.tsx.

---

Implementation Steps

1. Add prApi.merge to the API client

In file:web-ui/src/lib/api.ts, extend the existing prApi object with a merge method that calls POST /api/v2/pr/{pr_number}/merge. The response shape matches MergeResponse from file:codeframe/ui/routers/pr_v2.py ({ sha, merged, message }).

Add a corresponding MergeResponse interface to file:web-ui/src/types/index.ts:

Field	Type	Description
sha	string | null	Merge commit SHA
merged	boolean	Whether merge succeeded
message	string	Status message

Also add a MergePRRequest interface with a single optional method field ('squash' \| 'merge' \| 'rebase', defaulting to 'squash').

---

2. Create PRStatusPanel component

Create file:web-ui/src/components/review/PRStatusPanel.tsx as a 'use client' component. It receives workspacePath: string and prNumber: number as props.

Internal state:

• isMerging: boolean — tracks in-flight merge call
• merged: boolean — true after successful merge (stops polling, shows banner)
• mergeError: string | null

Data fetching (via useSWR):

• Proof status: proofApi.getStatus(workspacePath) with refreshInterval: 15000, paused when merged === true
• CI status: prApi.get(workspacePath, prNumber) (calls GET /api/v2/pr/{pr_number}) with refreshInterval: 15000, paused when merged === true

Gate logic (derived, not stored in state):

openRequirements = proofStatus.requirements.filter(r => r.status === 'open')
ciPassing        = pr.state === 'open' && ciChecksPass   // derive from PR state
canMerge         = openRequirements.length === 0 && ciPassing

Since PRResponse from pr_v2.py does not include a ci_status field, derive CI readiness from pr.state === 'open' and the absence of a merged_at. If the backend later exposes CI check data, this can be enriched.

Blocking message logic:

• If openRequirements.length > 0: render an inline list of requirement titles, each linking to /proof/{req.id}, plus a link to /proof
• If CI is not passing: render "Waiting for CI checks" or "CI checks failing"
• Both conditions can be true simultaneously; show both messages

Merge button:

• Wrapped in TooltipProvider + Tooltip (already used in file:web-ui/src/app/proof/page.tsx)
• disabled when !canMerge || isMerging || merged
• TooltipContent summarises the blocking reason when disabled
• On click: call prApi.merge(workspacePath, prNumber, { method: 'squash' }), set merged = true on success, set mergeError on failure

Success state:

• Replace the merge button area with a green confirmation banner ("PR #N merged successfully") and stop polling by passing isPaused: () => true to both SWR hooks

Component structure (wireframe):

┌─────────────────────────────────────────────────────┐
│  PR Status                              [PR #N link] │
├─────────────────────────────────────────────────────┤
│  CI Checks:   ● passing / ⏳ pending / ✗ failing    │
│  PROOF9:      ✓ All clear / ✗ 2 open requirements   │
│               • REQ-001: Title A  →/proof/REQ-001   │
│               • REQ-002: Title B  →/proof/REQ-002   │
│               View all →/proof                       │
├─────────────────────────────────────────────────────┤
│  [error banner if mergeError]                        │
│  [success banner if merged]                          │
│                                    [Merge ▼] button  │
└─────────────────────────────────────────────────────┘

Use Card, Button, Badge, Tooltip/TooltipProvider/TooltipTrigger/TooltipContent from the existing component library. Use Loading03Icon, CheckmarkCircle01Icon, Cancel01Icon from @hugeicons/react (already used in file:web-ui/src/components/review/ReviewHeader.tsx).

---

3. Integrate PRStatusPanel into the Review page

In file:web-ui/src/app/review/page.tsx, after a PR is successfully created (i.e., prNumber > 0), render <PRStatusPanel workspacePath={workspacePath} prNumber={prNumber} /> below the existing CommitPanel. Pass prNumber from the existing prNumber state variable.

---

4. Add prApi.get to the API client

In file:web-ui/src/lib/api.ts, add a get method to prApi that calls GET /api/v2/pr/{pr_number} and returns PRResponse. This is needed by PRStatusPanel to poll PR state.

---

5. Write Jest tests

Create file:web-ui/__tests__/components/review/PRStatusPanel.test.tsx following the pattern in file:web-ui/__tests__/app/proof/page.test.tsx:

• Mock @/lib/api (prApi.get, prApi.merge, proofApi.getStatus)
• Mock swr with jest.fn()
• Mock @/lib/workspace-storage

Test cases:

Scenario	Expected
Open PROOF9 requirements exist	Merge button is disabled
Open PROOF9 requirements exist	Blocking REQ titles rendered inline
Open PROOF9 requirements exist	Link to /proof page rendered
All requirements satisfied/waived	Merge button is enabled
Merge button clicked → success	Success banner shown, button gone
Merge button clicked → API error	Error message shown, button re-enabled
isMerging in-flight	Button shows loading state and is disabled
Both CI and PROOF9 blocking	Both messages shown

Import In IDE

🤖 Prompt for AI Agents

## Observations

The `web-ui` is a Next.js 16 + React 19 app using `swr` for data fetching, `axios` for API calls, `@radix-ui` for UI primitives (including `Tooltip`), and `@hugeicons/react` for icons. The backend merge endpoint already exists at `POST /api/v2/pr/{pr_number}/merge` in `file:codeframe/ui/routers/pr_v2.py`. The `proofApi.getStatus` method and `ProofStatusResponse` type are already defined in `file:web-ui/src/lib/api.ts` and `file:web-ui/src/types/index.ts`. Issue #570's PR Status panel is the parent component this work extends — it does not yet exist in the codebase and must be created as part of this ticket.

## Approach

Create a `PRStatusPanel` component that wraps the existing PR status display (from #570) and adds a PROOF9-gated Merge button. The component fetches proof status via `proofApi.getStatus` (already in `api.ts`) and calls a new `prApi.merge` method. The button's enabled/disabled state is derived from both CI status and open PROOF9 requirements. Tests follow the Jest + React Testing Library pattern established in `file:web-ui/__tests__/app/proof/page.test.tsx`.

---

## Implementation Steps

### 1. Add `prApi.merge` to the API client

In `file:web-ui/src/lib/api.ts`, extend the existing `prApi` object with a `merge` method that calls `POST /api/v2/pr/{pr_number}/merge`. The response shape matches `MergeResponse` from `file:codeframe/ui/routers/pr_v2.py` (`{ sha, merged, message }`).

Add a corresponding `MergeResponse` interface to `file:web-ui/src/types/index.ts`:

| Field | Type | Description |
|---|---|---|
| `sha` | `string \| null` | Merge commit SHA |
| `merged` | `boolean` | Whether merge succeeded |
| `message` | `string` | Status message |

Also add a `MergePRRequest` interface with a single optional `method` field (`'squash' \| 'merge' \| 'rebase'`, defaulting to `'squash'`).

---

### 2. Create `PRStatusPanel` component

Create `file:web-ui/src/components/review/PRStatusPanel.tsx` as a `'use client'` component. It receives `workspacePath: string` and `prNumber: number` as props.

**Internal state:**
- `isMerging: boolean` — tracks in-flight merge call
- `merged: boolean` — true after successful merge (stops polling, shows banner)
- `mergeError: string | null`

**Data fetching (via `useSWR`):**
- Proof status: `proofApi.getStatus(workspacePath)` with `refreshInterval: 15000`, paused when `merged === true`
- CI status: `prApi.get(workspacePath, prNumber)` (calls `GET /api/v2/pr/{pr_number}`) with `refreshInterval: 15000`, paused when `merged === true`

**Gate logic (derived, not stored in state):**

```
openRequirements = proofStatus.requirements.filter(r => r.status === 'open')
ciPassing        = pr.state === 'open' && ciChecksPass   // derive from PR state
canMerge         = openRequirements.length === 0 && ciPassing
```

Since `PRResponse` from `pr_v2.py` does not include a `ci_status` field, derive CI readiness from `pr.state === 'open'` and the absence of a `merged_at`. If the backend later exposes CI check data, this can be enriched.

**Blocking message logic:**
- If `openRequirements.length > 0`: render an inline list of requirement titles, each linking to `/proof/{req.id}`, plus a link to `/proof`
- If CI is not passing: render "Waiting for CI checks" or "CI checks failing"
- Both conditions can be true simultaneously; show both messages

**Merge button:**
- Wrapped in `TooltipProvider` + `Tooltip` (already used in `file:web-ui/src/app/proof/page.tsx`)
- `disabled` when `!canMerge || isMerging || merged`
- `TooltipContent` summarises the blocking reason when disabled
- On click: call `prApi.merge(workspacePath, prNumber, { method: 'squash' })`, set `merged = true` on success, set `mergeError` on failure

**Success state:**
- Replace the merge button area with a green confirmation banner ("PR #N merged successfully") and stop polling by passing `isPaused: () => true` to both SWR hooks

**Component structure (wireframe):**

```
┌─────────────────────────────────────────────────────┐
│  PR Status                              [PR #N link] │
├─────────────────────────────────────────────────────┤
│  CI Checks:   ● passing / ⏳ pending / ✗ failing    │
│  PROOF9:      ✓ All clear / ✗ 2 open requirements   │
│               • REQ-001: Title A  →/proof/REQ-001   │
│               • REQ-002: Title B  →/proof/REQ-002   │
│               View all →/proof                       │
├─────────────────────────────────────────────────────┤
│  [error banner if mergeError]                        │
│  [success banner if merged]                          │
│                                    [Merge ▼] button  │
└─────────────────────────────────────────────────────┘
```

Use `Card`, `Button`, `Badge`, `Tooltip`/`TooltipProvider`/`TooltipTrigger`/`TooltipContent` from the existing component library. Use `Loading03Icon`, `CheckmarkCircle01Icon`, `Cancel01Icon` from `@hugeicons/react` (already used in `file:web-ui/src/components/review/ReviewHeader.tsx`).

---

### 3. Integrate `PRStatusPanel` into the Review page

In `file:web-ui/src/app/review/page.tsx`, after a PR is successfully created (i.e., `prNumber > 0`), render `<PRStatusPanel workspacePath={workspacePath} prNumber={prNumber} />` below the existing `CommitPanel`. Pass `prNumber` from the existing `prNumber` state variable.

---

### 4. Add `prApi.get` to the API client

In `file:web-ui/src/lib/api.ts`, add a `get` method to `prApi` that calls `GET /api/v2/pr/{pr_number}` and returns `PRResponse`. This is needed by `PRStatusPanel` to poll PR state.

---

### 5. Write Jest tests

Create `file:web-ui/__tests__/components/review/PRStatusPanel.test.tsx` following the pattern in `file:web-ui/__tests__/app/proof/page.test.tsx`:

- Mock `@/lib/api` (`prApi.get`, `prApi.merge`, `proofApi.getStatus`)
- Mock `swr` with `jest.fn()`
- Mock `@/lib/workspace-storage`

**Test cases:**

| Scenario | Expected |
|---|---|
| Open PROOF9 requirements exist | Merge button is `disabled` |
| Open PROOF9 requirements exist | Blocking REQ titles rendered inline |
| Open PROOF9 requirements exist | Link to `/proof` page rendered |
| All requirements satisfied/waived | Merge button is enabled |
| Merge button clicked → success | Success banner shown, button gone |
| Merge button clicked → API error | Error message shown, button re-enabled |
| `isMerging` in-flight | Button shows loading state and is disabled |
| Both CI and PROOF9 blocking | Both messages shown |

---

Execution Information

Branch: main
Commit: ea0de0a

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.