Comment system v2: durable thread storage + full lifecycle (edit / delete / reply / resolve)

[amrmelsayed]

Problem

The review-comment surfaces shipped across #859 (add from preview), #860 (summary panel), #861 (preview nav), and #863 (inline cards + minimap) are all built on a single flat on-disk marker:

<!-- REVIEW(@<author>): <text> -->

That format carries an author and a body and nothing else. It has no stable identity, no notion of a reply, no resolved flag, no reaction state. Every comment-lifecycle capability a reviewer expects is therefore either missing or half-present:

• Edit an existing comment — not possible anywhere
• Delete — works only from the editor gutter, not from the preview reading surface
• Reply / threads — a marker is a single comment; thread.canReply = false
• Resolve / unresolve — no state to store, so no way to mark feedback addressed or visually distinguish open vs. done
• Reactions / acknowledgement — nowhere to record

These were each deferred (across #859/#860/#863's "out of scope" sections) to "the reply-storage decision." This issue IS that decision plus the lifecycle features it unblocks, scoped as one coherent unit because they share one root cause: the storage format.

The spine: storage format first

The keystone is a richer, durable comment representation that can carry:

• a stable comment ID (so edit/delete/resolve target a specific comment, not a line)
• thread membership (a reply belongs to a parent)
• resolved / unresolved state
• (optional, later) reaction counts

Constraints the format must respect:

• Stays human-readable and diff-friendly in the .md source (markers are committed to git)
• Backward-compatible: existing flat <!-- REVIEW(@a): t --> markers parse as a single-comment, unresolved, no-reply thread
• Round-trips cleanly through the existing parse path (parseReviewMarkers), the editor-side Comments API (plan-review.ts), and the preview canvas (artifact-canvas)
• Path eligibility unchanged: codev/(plans|specs|reviews)/*.md only

Proposed phasing

1. Format v2 + parser/codec — design the on-disk shape, extend the codec, migrate the read/write path. No user-visible feature yet; existing markers keep working.
2. Edit + preview-side delete — the two capabilities that need the least from the format (edit rewrites one comment; delete already exists editor-side). Carved out as independently shippable — could land before phase 1 as a quick slice against the current flat format, or fold in here.
3. Reply threads — multiple comments under one anchor, rendered in both the editor thread and the preview inline card stack.
4. Resolve state — resolve/unresolve action; resolved markers render distinctly (border/dot color) in preview cards and the vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863 minimap; composes with vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860's filter.
5. Reactions (optional / lowest priority).

Scope boundaries

• Edit + preview-delete are independently shippable and must not be held hostage by the larger format design. Mentioned here for completeness; can split out if it accelerates delivery.
• Notifications / @mentions / commit-from-comment ("suggested change") are explicitly out of scope — separate, much larger concerns.
• Filter UI (mine / unresolved) stays vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860's job; this issue only supplies the resolve state it filters on.

Why this is design-heavy (protocol note)

This is SPIR-shaped, not a quick PIR/AIR. The format decision in phase 1 has long-lived blast radius (it's the on-disk contract every comment surface reads) and deserves a real spec and consultation. Bundling is correct because the design must be reasoned about as a whole.

Relationships

• Builds on vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859 (add), vscode: review summary webview — bird's-eye list of all REVIEW markers in spec/plan files with click-to-jump #860 (summary/filter), vscode: markdown preview navigation chrome — floating TOC + quick-jump overlay + per-heading mini-toolbar for long Codev artifacts #861 (preview nav), vscode: markdown preview marker-aware features — inline REVIEW rendering + right-edge marker minimap #863 (inline cards + minimap) — all consume the marker format this issue evolves
• Editor-side: packages/vscode/src/comments/plan-review.ts, packages/vscode/src/review-decorations.ts
• Preview-side: packages/artifact-canvas/src/

Acceptance criteria (sketch — to be firmed in the spec)

• New on-disk format carries stable ID + thread + resolved state; documented
• Existing flat markers parse unchanged (backward compatible)
• Edit a comment from editor and preview
• Delete a comment from the preview reading surface (not just the editor gutter)
• Reply to a comment; replies render as a thread in both surfaces
• Resolve / unresolve; resolved markers render distinctly in cards and minimap
• All gated to codev/(plans|specs|reviews)/*.md; theme variables throughout
• No external runtime dependencies added