vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump

[amrmelsayed]

Problem

Codev specs and plans routinely cross 200–400 lines. When an architect leaves multiple <!-- REVIEW(@<author>): --> markers across a long doc, the only ways to see them all are:

1. Scroll the entire file in the editor and visually scan for the colored decoration from review-decorations.ts
2. Open every comment thread in the Comments panel one at a time

Neither gives a single bird's-eye view answering: "What feedback exists on this doc? Where? By whom? In which sections?" Builders coming back to address feedback face the same problem in reverse — they need a work-list of "what to fix," not a scroll-through.

Proposal

A standalone review summary webview panel (codev.openReviewSummary) that renders one row per REVIEW marker in the current spec/plan/review file, grouped by section heading, with click-to-jump to the source line.

Visual shape

Review Summary — 0042-feature-x.md                              [×]
────────────────────────────────────────────────────────────────────
## Acceptance criteria                                            3
   @architect  L47   tighten this paragraph
   @architect  L52   missing acceptance criterion for X
   @architect  L58   rephrase — unclear what "safe" means here

## Implementation                                                 1
   @architect  L91   this approach won't compose with #793

## Out of scope                                                   0
────────────────────────────────────────────────────────────────────
[ all ] [ unresolved ] [ mine ]                  sort: position ▾

• Section grouping — markers grouped under their nearest preceding heading (H2 by default; H1 if no H2 exists). Empty-section rows shown collapsed by default with a count
• Per-row content — author, line number, comment body (truncated; tooltip shows full)
• Click row → opens the source file at that line in the editor; reveals + highlights the marker briefly
• Empty state — "No review comments in this file" placeholder; the panel still opens (signals "you have nothing to address")

Scope: current file only (v1)

The panel shows markers for whichever spec/plan/review file is active in the editor. Switching files (or opening a new one) refreshes the panel. Future expansion options to "all open spec/plan files" or "all spec/plan files in the workspace" deliberately deferred.

Filters

Three buttons in the panel footer (sticky):

Filter	Behavior
All (default)	Every REVIEW marker
Unresolved	Only markers without a resolved annotation. Today this matches "All" because resolve state doesn't exist (see Composes-with below). Pre-builds the filter so it lights up the day P3.3 lands.
Mine	Only markers by the current git-config user.name. Falls back to no-op if author detection isn't wired (today; #857 wires it)

Sort

Single sort selector: position (default — file order) | author | line. No multi-key sort in v1.

Sync

• Refreshes on workspace.onDidSaveTextDocument for the bound file
• Refreshes on workspace.onDidChangeActiveTextEditor (when active editor changes to a different eligible file)
• Refreshes on workspace.onDidChangeTextDocument debounced ~500ms (so live typing in the source file updates the panel without thrashing)
• No external state; the panel is a derived view of the file content

Implementation sketch

Files

• New: packages/vscode/src/panels/review-summary-panel.ts — webview lifecycle (createOrShow, revive on extension reload)
• New: packages/vscode/src/panels/review-summary/index.tsx (or vanilla JS — webview UI is small enough to skip React)
• New: packages/vscode/src/lib/review-marker-scan.ts — pure function: (text: string) => Array<{ author, line, body, sectionHeading }>. Reuses the same REVIEW_COMMENT_PATTERN regex from plan-review.ts:31. Heading detection is a simple ## scan from each marker walking backward.

Commands

• codev.openReviewSummary — opens the panel for the active editor's file (no-op if not in an eligible path); palette-visible
• Optional v1 surface: a CodeLens at the top of every eligible file: > Open review summary (N markers)

Path eligibility

Match the regex from plan-review.ts:33 (after #857 extends it to reviews/). Same path set as the editor-side gutter +.

Webview communication

• Extension → webview: postMessage with the parsed marker list on load and on each refresh tick
• Webview → extension: postMessage with { type: 'jumpToLine', line: N } on row click; extension calls vscode.window.showTextDocument(uri, { selection: new Range(N, 0, N, 0) })

Acceptance criteria

• codev.openReviewSummary registered; opens a webview panel titled Review Summary — <basename>
• Panel renders one row per REVIEW marker in the active editor's file (if the file is in codev/(plans|specs|reviews)/)
• Markers grouped by nearest preceding heading; sections with 0 markers shown collapsed with count
• Row click → opens source file at the marker's line, scrolls into view, briefly highlights the marker (uses existing review-decorations.ts highlight or a transient overlay)
• Panel refreshes on file save, active-editor change to another eligible file, and (debounced) text changes
• Three filter buttons: All / Unresolved / Mine. Unresolved is a no-op today (no resolve state) but the button is present for forward-compat
• Sort selector: position (default) / author / line
• Empty state: "No review comments in this file"
• Opening the panel against a non-eligible file shows the empty state without erroring
• Panel revives across VS Code reload via WebviewPanel.serialize
• Webview styling uses VS Code theme variables (--vscode-foreground, --vscode-textLink-foreground, etc.) for theme consistency

Out of scope (v1)

• Cross-file aggregation (all open spec/plan files, all in workspace). Future expansion; needs a UI design call (single-file feed is the simpler primitive)
• Reply / thread display. Each REVIEW marker is one row; if Phase 3 lands replies, this expands then
• Resolve state UI (mark resolved from the panel). The Unresolved filter is plumbed but does nothing until P3.3 lands
• Edit / delete from the panel. Click jumps to source; mutation happens in the editor via the existing Comments API path
• Inline preview of the surrounding context (line N-2 ... line N+2). Row body shows the comment text only; click jumps for context
• Sidebar view variant (vs webview panel). Webview panel chosen for layout flexibility; sidebar tree would compress the per-row content awkwardly

Why this is high leverage

For long Codev artifacts — the typical case — this is the single piece of "where's the feedback?" infrastructure. It composes with everything else in the queue:

• vscode: spec/plan review comments — polish pass (placeholders, reviews/ coverage, author identity, panel discoverability) #857 wires author identity → the "Mine" filter becomes accurate
• vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 preview-side add-comment → the marker appears in this summary the moment it's saved
• Future replies / resolve state → "Unresolved" filter lights up; row count becomes a real status
• vscode: viewSpecDiff / viewPlanDiff — side-by-side diff of current vs prior revision for spec/plan files #858 spec/plan diff → reviewer reads the diff, opens the summary, walks through the markers, addresses each

The single-file v1 is a deliberate scope cap to keep the PR small. Cross-file aggregation and richer status visualization are natural follow-ups once the primitive proves itself.

Related

• packages/vscode/src/comments/plan-review.ts — source of REVIEW markers; shares REVIEW_COMMENT_PATTERN regex
• packages/vscode/src/review-decorations.ts — existing in-editor decoration for REVIEW lines; jump-target highlight reuses this
• vscode: spec/plan review comments — polish pass (placeholders, reviews/ coverage, author identity, panel discoverability) #857 — author identity (git config user.name); enables accurate "Mine" filter
• vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 — preview-pane add-comment; new markers from there flow into this summary on save
• vscode: viewSpecDiff / viewPlanDiff — side-by-side diff of current vs prior revision for spec/plan files #858 — viewSpecDiff / viewPlanDiff; complementary review-workflow surface