V8 — Right Sidebar: PR Panel + Merge Gate (Linked Issues, CI Checks, Review & Merge)

[Luis85]

Parent epic: #326 · Depends on: F2, F3, F4 · Stories: US-029, US-046, US-047, US-048

Problem

The PR Panel is where review and merge happen — the operational endpoint of the entire MVP loop. The merge gate (reviewStatus === 'approved' AND checks === 'passing') must be enforced inside MergePullRequestUseCase, not only in the template. Hiding the button is a usability hint; the use case is the safety rail.

Solution

PRPanel.vue — right-panel content when right === 'pr'

No header bar — the topbar breadcrumb + sidebar active state already communicate context (per the design brief).

Sections (vertical scroll):

A. Linked Issues (conditional — only if pr.issueIds.length > 0):

• ⊙ icon · Issue number · truncated title · status dot (Open = green)
• Click → useAppStateStore.goToIssue(num) (US-029)

B. CI Checks (collapsible — collapsed by default):

• Header summary: ✓ 4/4 passing (green) / ✕ N failing (red) / ○ N pending (amber)
• › chevron flips to ▾ on expand
• Expanded: row per check (icon + name + status text); click shows status-detail toast

C. Review & Merge (unified — one continuous workflow):

• Review status icon + label (◎ Review required / ✓ Approved / ◐ Draft / ⊛ Merged), color-coded
• Approve button (visible when reviewStatus !== 'approved' and PR is not a draft): click → ApprovePullRequestUseCase; on success: pr.reviewStatus = 'approved', panel re-renders, merge unlocks (US-046)
• Merge button (visible only after approve): full-width purple; enabled only when pr.checks === 'passing'; click → MergePullRequestUseCase (which re-checks the gate internally); 800ms transition; on success: pr.status = 'merged', sidebar pill → purple ✓, panel re-renders (US-047)
• Before approval: dimmed "Approve this PR to unlock merge" message (US-047)
• Draft state: shows ◐ Mark as Ready button instead of Merge; click → MarkDraftReadyUseCase; converts draft to open; re-renders both panels (US-048)
• PR AI input at the bottom: prompt "Ask about PR #N…"; context-button label "PR context ▾"

Use cases (application layer)

• GetPullRequestUseCase (already in V4)
• ApprovePullRequestUseCase
• MergePullRequestUseCase — gate re-check: returns Result.err(MergeBlocked) if reviewStatus !== 'approved' OR checks !== 'passing', regardless of what the UI thinks
• MarkDraftReadyUseCase

Acceptance criteria

• Linked Issues section appears only when pr.issueIds.length > 0; row click navigates to the linked issue (US-029)
• CI Checks section collapsed by default; header summary text matches counts; expand shows per-check rows
• CI row click shows a contextual toast with the check status
• Approve button visible only when not approved + not draft; click dispatches ApprovePullRequestUseCase; on success, panel re-renders and Merge button becomes visible (US-046)
• Merge button enabled only when checks === 'passing'; click dispatches MergePullRequestUseCase; 800ms delay; on success, status = 'merged' and sidebar pill updates (US-047)
• Gate enforcement test: a unit test calls MergePullRequestUseCase directly with reviewStatus === 'review-required' and asserts it returns Result.err(MergeBlocked) — without involving the UI. Same with checks === 'failing'.
• Before approval, the dimmed gate message is shown and the Merge button is hidden (US-047)
• Draft PRs show ◐ Mark as Ready instead of Merge; click converts; re-renders sidebar row + panel (US-048)
• PageObject tests cover: linked-issue navigation, CI expand/collapse, approve flow, merge flow, draft-ready flow, gate-blocked rendering
• Storybook: PR review-required + checks passing, PR review-required + checks failing, PR approved + checks passing, draft PR, merged PR, PR with no linked issues
• npm run typecheck, npm run lint, npm run test, npm run test:storybook pass

Out of scope

• Request-changes flow (post-MVP — ApprovePullRequestUseCase only handles approval)
• PR comment thread (V4 handles activity timeline + comments in the main view)
• Merge methods other than the default — pick one in F1 ADR-08

Affected files

File	Action
src/ui/components/right/PRPanel.vue	New
src/ui/components/right/LinkedIssues.vue	New
src/ui/components/right/CIChecks.vue	New
src/ui/components/right/ReviewAndMerge.vue	New
src/application/pullrequest/ApprovePullRequestUseCase.ts	New
src/application/pullrequest/MergePullRequestUseCase.ts	New (gate-enforcing)
src/application/pullrequest/MarkDraftReadyUseCase.ts	New
src/application/pullrequest/MergeGateError.ts	New
tests/application/pullrequest/MergePullRequestUseCase.test.ts	New (gate behaviour tested here)
tests/ui/components/right/PRPanel.test.ts + .po.ts	New
stories/right/PRPanel.stories.ts	New

References

• inputs/specorator-mvp-design-2026-05/Specorator_Design_Brief.html §"PR Panel" + §"Review & Merge" (gated workflow flow diagram)
• inputs/specorator-mvp-design-2026-05/Specorator_Handoff.html §"PR Merge Workflow (Gated)"
• inputs/specorator-mvp-design-2026-05/SYNTHESIS.md §"PR merge gate enforcement"
• User stories US-029, US-046, US-047, US-048

[Luis85]

Right-sidebar review (V8) — readiness: H — green-light pending one critical clarification on gate semantics

V8 is the safety-critical slice. The plan correctly identifies the gate as an application-layer concern. Below is what the implementation must look like and what tests must exist before this can merge.

Review findings

1. CRITICAL — MergePullRequestUseCase must re-check the gate, not trust the input

The acceptance criterion already calls this out, but the issue body must mandate the specific pattern. The use case is the safety rail; the template is a usability hint. Follow AdvanceFeatureStageUseCase (which re-validates invariants by calling feature.advanceStep() on the freshly fetched aggregate, not on a parameter). Concretely:

// src/application/pullrequest/MergePullRequestUseCase.ts
export class MergePullRequestUseCase {
  constructor(private readonly repo: IPullRequestRepository,
              private readonly github: GitHubPort) {}

  async execute(input: { prId: string }): Promise<Result<PullRequest, MergeGateError | Error>> {
    const pr = await this.repo.findById(input.prId)
    if (!pr) return err(new Error(`PR "${input.prId}" not found`))

    // Re-check from freshly loaded aggregate — never trust caller-supplied state
    if (pr.reviewStatus !== 'approved') {
      return err(new MergeGateError('MERGE_BLOCKED_REVIEW', `PR ${pr.number} is not approved`))
    }
    if (pr.checks !== 'passing') {
      return err(new MergeGateError('MERGE_BLOCKED_CHECKS', `PR ${pr.number} has non-passing checks`))
    }
    if (pr.status === 'merged') {
      return err(new MergeGateError('ALREADY_MERGED', `PR ${pr.number} already merged`))
    }
    if (pr.draft) {
      return err(new MergeGateError('MERGE_BLOCKED_DRAFT', `PR ${pr.number} is a draft`))
    }

    const merged = await this.github.mergePullRequest(pr.number)
    if (!merged.ok) return merged
    return this.repo.save(pr.markMerged())
  }
}

MergeGateError extends Error with a discriminator field (code: 'MERGE_BLOCKED_REVIEW' | 'MERGE_BLOCKED_CHECKS' | 'MERGE_BLOCKED_DRAFT' | 'ALREADY_MERGED') so the UI can surface specific copy without string-matching messages.

Required unit test names (canonical, do not rename):

• 'returns MergeGateError(MERGE_BLOCKED_REVIEW) when reviewStatus is review-required'
• 'returns MergeGateError(MERGE_BLOCKED_REVIEW) when reviewStatus is draft'
• 'returns MergeGateError(MERGE_BLOCKED_CHECKS) when checks is failing'
• 'returns MergeGateError(MERGE_BLOCKED_CHECKS) when checks is pending'
• 'returns MergeGateError(MERGE_BLOCKED_DRAFT) when pr.draft is true'
• 'returns MergeGateError(ALREADY_MERGED) when status is already merged'
• 'calls GitHubPort.mergePullRequest only when all gates pass'
• 'does not call GitHubPort.mergePullRequest when any gate fails' (uses a spy with toHaveBeenCalledTimes(0))
• 're-fetches the PR before checking gates (caller cannot bypass with stale state)'
• 'persists the merged PR via repository.save on success'

The "spy with zero calls" test is the load-bearing one — it proves the gate cannot be tunneled through.

2. ApprovePullRequestUseCase is not gate-free

It must reject when pr.status === 'merged' or pr.draft === true (cannot approve a draft per the Screen v2 source — draft path shows Mark-as-Ready instead). Add ApprovalError with codes ALREADY_APPROVED, CANNOT_APPROVE_MERGED, CANNOT_APPROVE_DRAFT.

3. Approve-then-Merge race

If the user clicks Approve and immediately Merge while CI flips to failing, the local store thinks checks === 'passing' but a fresh repo fetch would say failing. Because the use case re-fetches via repo.findById, this is caught — but the test 'returns MergeGateError(MERGE_BLOCKED_CHECKS) when checks flip between approve and merge' makes the guarantee explicit.

4. 800ms transition belongs in the UI, not the use case

Keep MergePullRequestUseCase synchronous-feeling. The setTimeout(800) is a ReviewAndMerge.vue concern (CSS transition / button "merging…" state). Tests should not need to wait 800ms — UI uses fake timers.

Component test cases (PageObject)

PRPanel.test.ts:

• renders Linked Issues only when pr.issueIds.length > 0
• CI Checks collapsed by default; clicking chevron expands
• review-required + checks-passing → Approve visible, Merge hidden, gate message visible
• approved + checks-passing → Merge enabled
• approved + checks-failing → Merge visible but disabled, helper text "CI must pass"
• approved + checks-pending → Merge disabled, helper text "CI pending"
• draft → Mark-as-Ready button instead of Merge
• merged → "Merged into {base}" line, no buttons
• gate-blocked render shows pr-merge-button-hidden testid (not present in DOM)
• on MergePullRequestUseCase returning MergeGateError, panel re-fetches and updates without crashing (defensive UI)

data-testid hooks (with state variants)

PRPanel: pr-panel-root, pr-panel-linked-issues-section, pr-panel-linked-issues-hidden, pr-panel-ci-section, pr-panel-review-merge-section, pr-panel-ai-input.
LinkedIssues: linked-issue-row (with data-issue-num), linked-issue-status-open, linked-issue-status-closed.
CIChecks: ci-checks-header, ci-checks-summary-passing, ci-checks-summary-failing, ci-checks-summary-pending, ci-checks-chevron-collapsed, ci-checks-chevron-expanded, ci-checks-row, ci-checks-row-icon-pass, ci-checks-row-icon-fail, ci-checks-row-icon-pending.
ReviewAndMerge: review-status-icon, review-status-label, pr-approve-button-visible, pr-approve-button-hidden, pr-merge-button-visible, pr-merge-button-hidden, pr-merge-button-enabled, pr-merge-button-disabled, pr-merge-merging (during 800ms), pr-gate-blocked-message, pr-mark-ready-button, pr-merged-line, pr-merge-helper-passing, pr-merge-helper-failing, pr-merge-helper-pending.

EARS requirements

• REQ-MVP-052: If pr.reviewStatus !== 'approved' OR pr.checks !== 'passing', then MergePullRequestUseCase shall return Result.err(MergeGateError) and shall not invoke GitHubPort.mergePullRequest.
• REQ-MVP-053: When MergePullRequestUseCase is invoked, the system shall re-fetch the PullRequest from the repository before evaluating the gate.
• REQ-MVP-054: When pr.reviewStatus === 'approved' AND pr.checks === 'passing', the system shall render the Merge button enabled.
• REQ-MVP-055: While pr.reviewStatus !== 'approved' AND pr.draft === false, the system shall hide the Merge button and render the "Approve this PR to unlock merge" message.
• REQ-MVP-056: When pr.draft === true, the system shall render the Mark-as-Ready button in place of the Merge button.
• REQ-MVP-057: When ApprovePullRequestUseCase returns Result.ok, the system shall set pr.reviewStatus = 'approved' and re-render the panel so the Merge button becomes visible.
• REQ-MVP-058: While MergePullRequestUseCase is in flight, the system shall disable the Merge button and announce "Merging…" via aria-live.

Storybook story matrix

PRPanel.stories.ts: ReviewRequiredChecksPassing, ReviewRequiredChecksFailing, ReviewRequiredChecksPending, ApprovedChecksPassing, ApprovedChecksFailing, ApprovedChecksPending, Draft, Merged, NoLinkedIssues, ManyLinkedIssues, CIChecksMixedPassFailPending, Merging (mid-800ms).

A11y checklist

• pr-gate-blocked-message rendered inside <div role="status" aria-live="polite"> so SR users hear why the merge is unavailable.
• Approve button has aria-label="Approve PR #{number}"; Merge button has aria-label="Merge PR #{number} into {base}".
• Disabled Merge button uses aria-disabled="true" (so it remains focusable) and an aria-describedby pointing at the helper text ("CI must pass…").
• CI Checks chevron is a <button> with aria-expanded toggled; the expanded list has aria-labelledby on the header.
• During the 800ms transition, the Merge button shows aria-busy="true".
• prefers-reduced-motion: skip the 800ms transition, jump to merged state.

Edge cases

• Draft PR — only Mark-as-Ready; never Approve or Merge.
• PR with no linked issues — Linked Issues section entirely hidden, not "0 linked issues".
• CI all pending — Merge disabled, helper "CI pending" (not "must pass").
• CI mix of pass/fail/pending — pr.checks is the aggregate 'failing'; individual rows still reveal the mix on expand.
• Already-merged PR — show "Merged into {base}" line; no buttons; clicking the (non-existent) merge route is a no-op.
• Race: user approves, CI flips to failing before merge click → use case catches it via re-fetch (REQ-MVP-053).
• Approve then immediately switch panels → optimistic state in store reverts cleanly if the use case fails.
• Network error inside GitHubPort.mergePullRequest — Result.err bubbles; panel does not crash, button re-enables, error notice via NotificationPort.showError.

---

Generated by Claude Code