add spec ./specs/coauthoring-document-edit-flow.md (status: graduated)

2026-06-13 07:05:14 -07:00
parent 62706371a2
commit 9d016e8f39
1 changed files with 592 additions and 0 deletions
@@ -0,0 +1,592 @@
+---
+status: graduated
+---
+# Solution Design: The Ask-Claude Document-Edit Flow (#42 · #47 · #46)
+
+| | |
+| --- | --- |
+| **Author(s)** | Ben Stull (with Claude) |
+| **Reviewers / approvers** | Ben Stull |
+| **Status** | `draft` |
+| **Version** | v0.1.0 |
+| **Source artifacts** | Features `benstull/vscode-cowriting-plugin#42` (Ask Claude to Edit Document, `type/feature`, `priority/P2`) · `#47` (block-granularity proposals, `type/feature`, `priority/P1`) · `#46` (accept-all, `type/feature`, `priority/P2`) · Epic `#1` (closed) · Capture sessions `vscode-cowriting-plugin-0035` (#42), `0040` (#47), `0039` (#46) · Brainstorming session `vscode-cowriting-plugin-0041` · Builds on (all shipped): F4 `#12` (propose/accept seam), F10 `#29` (interactive review preview), F11 `#43` (preview toolbar + `editDocument`/`runEditAndPropose`) · Parent specs (graduated): `coauthoring-propose-accept.md`, `coauthoring-attribution.md`, `coauthoring-interactive-review.md`, `coauthoring-rendered-preview.md` · F11 design currently lives in code + issue draft `issues/preview-toolbar-interaction-surface.md` (un-graduated — see §9) · Lineage: `ben.stull/rfc-app#48` |
+
+**Change log**
+
+| Date | Version | Change | By |
+| --- | --- | --- | --- |
+| 2026-06-12 | v0.1.0 | Initial draft — brainstorming session 0041. One combined design for the document-edit cluster, sequencing #42 → #47 → #46. Two forks locked with the operator: per-block proposals **preserve unchanged-span attribution** (block = decision unit, word = attribution unit); the cluster ships as **one** Solution Design. | Ben Stull + Claude |
+
+---
+
+## 1. Business Context
+
+### 1.1 Executive Summary
+
+The plugin can already ask Claude to edit a whole document (F11 shipped
+`cowriting.editDocument` → `runEditAndPropose({kind:"document"})`), but the flow
+around that capability is rough on three sides, each captured as its own feature:
+
+- **You can't easily reach it** (#42). "Ask Claude to Edit" only appears in the
+  editor body **when text is selected**. Right-clicking the body with *no*
+  selection, or right-clicking the editor **tab**, offers nothing — two natural
+  "do something with this document" gestures hit a dead end.
+- **What comes back is unreviewable** (#47, **P1**). A whole-document rewrite is
+  diffed at **word** granularity (`diffToHunks`, INV-37): a light copy-edit pass
+  explodes into dozens of tiny blue ✓/✗ blocks, forcing the reviewer to
+  adjudicate word-fragments out of the sentence they live in.
+- **Taking the result is tedious** (#46). Accepting Claude's edits is **one
+  proposal at a time**; a document a writer wants wholesale still demands a click
+  per proposal.
+
+This design treats the three as **one flow** — **reach → review → accept** — and
+ships them in that order. **#42** makes the document edit reachable from the
+obvious gestures; **#47** cuts the rewrite into **one proposal per changed block**
+(paragraph / header / bullet / fence) so the reviewer decides in the unit they
+think in; **#46** adds a single **Accept all** gesture. The whole flow is built on
+the existing F4 propose/accept seam and the F10/F11 preview — **no new edit path,
+no new accept mechanism, no new persisted model.**
+
+### 1.2 Background
+
+The inner loop shipped F2–F5 (threads · attribution · propose/accept ·
+cross-rung). F10 (`#29`) collapsed the review surfaces into one: a **clean
+editor** + the **rendered markdown preview** as the single annotated review
+surface, with ✓/✗ acting only on pending F4 proposals (INV-32..34). F11 (`#43`)
+made the preview's **toolbar the primary interaction surface** — a **Pin
+baseline** button and an **adaptive Ask-Claude** button — and, as part of that,
+added the host-side **`cowriting.editDocument`** command and the
+**`runEditAndPropose`** path that diffs a whole-document rewrite into per-hunk F4
+proposals (INV-35 sealed-webview intent, INV-36 `data-src` block→source mapping,
+INV-37 word-level per-hunk granularity).
+
+So the *capability* exists; this cluster is about the **experience around it**.
+Three captures landed it:
+
+- **0035 → #42**: "Add 'Ask Claude to Edit Document' on right-click with no
+  selection; same Edit-Selection/Edit-Document on the tab."
+- **0040 → #47**: "A single change should be a paragraph (or header, or
+  bulletpoint), not individual words. It's too much to review."
+- **0039 → #46**: "We need a way to accept all of Claude's edits."
+
+The captures themselves flagged that these "form an edit-flow cluster — brainstorm
+/ sequence together," which this session does.
+
+### 1.3 Business Actors / Roles
+
+- **Coauthor (human)** — the writer/engineer; the sole user of every gesture
+  here (right-click to ask, ✓/✗ to adjudicate, Accept-all to commit).
+- **Coauthor (machine)** — Claude via `@cline/sdk`; produces the document
+  rewrite that becomes block-level proposals; its accepted blocks land
+  Claude-attributed (word-precise — §6, INV-40).
+
+### 1.4 Problem Statement
+
+How do we make "ask Claude to revise this whole document, look at what it did,
+and take the parts I want" a **fluid, reviewable, low-friction** loop — when today
+it is **hard to invoke, exploded into word-fragments, and accepted one click at a
+time** — **without** forking a second edit path, a second accept mechanism, or a
+new persisted artifact?
+
+### 1.5 Pain Points
+
+| # | Pain | Felt by | Today |
+| --- | --- | --- | --- |
+| P-1 | No whole-document ask from the body (no selection) or the tab | Mouse-first / tab-oriented writers | Dead-end gestures |
+| P-2 | A document edit fans out into many word-level proposals | Anyone reviewing a document edit (worse the lighter the edit) | "Too much to review" (#47, P1) |
+| P-3 | Accepting many proposals is one click each | Writers who want Claude's whole pass | Manual sweep of ✓ |
+| P-4 | Block-level accept could lose attribution fidelity inside a block | The product's F3 attribution value | (a design risk this spec resolves — INV-40) |
+
+### 1.6 Targeted Business Outcomes
+
+- A **consistent "Ask Claude to Edit"** entry point — selection-scoped with a
+  selection, whole-document without — from both the body and the tab.
+- A document edit produces a **small number of in-context, block-sized**
+  decisions instead of a flood of word-fragments.
+- **"Take Claude's whole pass"** is a **single gesture**.
+- Attribution stays **word-precise** even though the decision unit is the block.
+
+### 1.7 Scope (business)
+
+**In scope:** the three features as one sequenced flow — entry-point wiring
+(#42); document-edit proposal granularity word→block (#47); bulk-accept over the
+current document (#46). Each remains its own implementation increment / PR.
+
+**Out of scope / non-goals:**
+
+- **Selection edits are unchanged** — a selection edit is already a single
+  proposal; #47 touches only the document path, #42 leaves selection behavior
+  intact, #46 reuses the same seam.
+- **No Explorer context-menu entry** for Ask-Claude (#42 is tab + body only, per
+  the capture; the review-panel Explorer entry shipped separately as #41).
+- **No "reject all"** (#46 is accept-only; a sibling ask if wanted).
+- **No cross-document / workspace-wide accept-all** — current document only.
+- **No new proposal-granularity *setting*** — block is the chosen unit, not a
+  toggle.
+- **No change to the inline word-level `<ins>`/`<del>` rendering** inside a block
+  — the reviewer still sees exactly what changed; only the *decision unit* and the
+  *attribution reconciliation* change.
+
+### 1.8 Assumptions · Constraints · Dependencies
+
+- **F11 already shipped the document-edit path** (`editDocument`,
+  `askClaude`, `runEditAndPropose`, `diffToHunks`). This is the strongest
+  constraint: #42 is mostly **menu wiring** (the command exists); #47 **replaces
+  the diff inside `runEditAndPropose`'s document branch**; #46 **loops the existing
+  `acceptById`**. The cluster adds almost no new surface.
+- **The block model already exists** — `splitBlocks` / `splitBlocksWithRanges` /
+  `diffBlocks` (`BlockOp`: unchanged / added / removed / changed+atomic; fences
+  atomic per INV-23). #47 **reuses this**, not a second notion of "block."
+- **The F4 accept seam is the only mutation path** —
+  `ProposalController.accept` → `AttributionController.applyAgentEdit`
+  (`WorkspaceEdit`); the sealed webview posts **intent** only (INV-8/21/35).
+- **No new persisted artifact** (INV-20) — proposals live in the F4 sidecar; this
+  cluster adds at most one transient field on the proposal (granularity marker —
+  §6.3) and transient webview messages.
+- VS Code context menus render a command's own `title`; the tab menu picks one of
+  two commands by a `when` clause on selection state (no per-menu relabel of one
+  command).
+
+### 1.9 Business Use Cases
+
+- **BUC-1 (reach)** — A writer right-clicks the document (body, no selection) or
+  the tab and asks Claude to edit the whole document.
+- **BUC-2 (review)** — The writer reads Claude's pass as block-sized proposals
+  and accepts/rejects each.
+- **BUC-3 (accept)** — The writer, happy with the pass, accepts all pending
+  proposals in one gesture.
+
+---
+
+## 2. Solution Proposal
+
+**One flow, three increments, all on existing seams.**
+
+```mermaid
+flowchart LR
+  subgraph reach["#42 — REACH"]
+    body["right-click body / tab\n(selection-aware)"] --> cmd["editSelection /\neditDocument"]
+  end
+  subgraph review["#47 — REVIEW"]
+    cmd --> rep["runEditAndPropose\n(document branch)"]
+    rep -- "diffToBlockHunks\n(per changed block)" --> props["F4 proposals\n(one per block)"]
+  end
+  subgraph accept["#46 — ACCEPT"]
+    props --> one["✓/✗ per block"]
+    props --> all["Accept all\n(toolbar intent)"]
+  end
+  one --> seam["F4 acceptById →\napplyAgentEdit"]
+  all --> seam
+  seam -- "block proposals: word-precise\nintra-block attribution (INV-40)" --> doc[(document)]
+```
+
+The defining idea of the cluster is in **#47's accept**: a document edit's
+proposals are cut at **block** granularity (the unit a human reviews), but each
+accept reconciles attribution at **word** granularity (the unit F3 records). The
+block is the **decision** unit; the word is the **attribution** unit. This is what
+lets us coarsen the review without coarsening the attribution — and it reuses the
+*exact* word-level machinery (`diffToHunks`) that INV-37 used, now repurposed as
+the intra-block sub-diff at accept time rather than the proposal cut.
+
+---
+
+## 3. Product Personas
+
+- **PP-1 (the coauthoring writer)** — edits a markdown document with Claude;
+  wants to invoke a whole-document pass quickly, review it at paragraph altitude,
+  and take it wholesale or selectively.
+
+---
+
+## 4. Product Use Cases
+
+| PUC | As PP-1 I… | Feature | Acceptance |
+| --- | --- | --- | --- |
+| PUC-1 | right-click the body with **no selection** → **Ask Claude to Edit Document** | #42 | whole-document edit → block proposals in the preview |
+| PUC-2 | right-click the body **with a selection** → **Ask Claude to Edit Selection** (unchanged) | #42 | one proposal over the selection (existing behavior) |
+| PUC-3 | right-click the **tab** → Edit Selection (if selection) / Edit Document (if not) | #42 | same behavior as the body equivalents, against that doc |
+| PUC-4 | see Claude's document edit as **one proposal per changed block** | #47 | M changed blocks → M proposals; unchanged blocks → none; fences atomic |
+| PUC-5 | accept a block proposal and have **only Claude's actual changes** attributed to Claude | #47 | unchanged words inside the accepted block keep their prior author (INV-40) |
+| PUC-6 | press **Accept all** to take every pending proposal at once | #46 | all anchored proposals applied; orphans skipped + reported |
+
+---
+
+## 5. UX Layout
+
+- **#42 entry points.** Two existing commands, surfaced in two more menus:
+  - **Editor body** (`editor/context`): **Ask Claude to Edit Selection** when
+    `editorHasSelection`, **Ask Claude to Edit Document** when not.
+  - **Editor tab** (`editor/title/context`): the same pair, gated the same way,
+    targeting the tab's document.
+  - Both entries appear **only for markdown / authorable** docs (mirroring
+    `editSelection`'s `when`: `resourceScheme == file || untitled` +
+    `editorLangId == markdown`).
+- **#47 review.** The preview is unchanged in *look* — the reviewer still sees
+  word-level `<ins>`/`<del>` inside each block. What changes: each **changed
+  block** is **one `cw-proposal` block** carrying one `data-proposal-id` and one
+  ✓/✗ pair, instead of several. A changed code/mermaid fence is one atomic
+  proposal (INV-23).
+- **#46 accept-all.** An **Accept all** button in the F11 preview **toolbar**,
+  shown when the document has **≥ 2 pending proposals**. Pressing it posts the
+  `acceptAll` intent; on completion the host reports applied-vs-skipped (status
+  message / toast). No confirmation dialog — VS Code undo restores (consistent
+  with single accept).
+
+```
+┌─ Review: my-doc.md ──────────────────────────────┐
+│ [ Pin baseline ]  [ Ask Claude ▾ ]  [ Accept all ]│  ← Accept all visible only when ≥2 pending
+├───────────────────────────────────────────────────┤
+│  ## Heading                                         │
+│  ┌───────────────────────────── proposal ───────┐  │
+│  │ The ~~quick brown~~ swift fox …          ✓ ✗ │  │  ← one block, word-level ins/del inside
+│  └───────────────────────────────────────────────┘  │
+└───────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Technical Design
+
+### 6.1 Invariants
+
+Parent invariants **INV-1..INV-37 carry over except where #47 supersedes
+INV-37**. This cluster adds:
+
+- **INV-38 (consistent, selection-aware Ask-Claude entry points)** — "Ask Claude
+  to Edit" is reachable from the editor **body** and the editor **tab**,
+  **selection-scoped when there is a selection** (`cowriting.editSelection`),
+  **whole-document when there is not** (`cowriting.editDocument`). Both menus are
+  gated to **markdown / authorable** docs. Both scopes route through the **single**
+  `runEditAndPropose` path — no divergent edit code (#42).
+- **INV-39 (document edits propose per changed block — supersedes INV-37)** — a
+  whole-document rewrite is cut into **one F4 proposal per changed block**, where a
+  block is the unit `splitBlocks` already recognizes (prose paragraph / header /
+  bullet; code & mermaid fences **atomic**, INV-23). **Unchanged blocks produce no
+  proposal.** A block proposal's anchor spans the **whole** source block and its
+  replacement is Claude's **whole** version of that block. This **replaces**
+  INV-37's per-hunk word-level granularity **for document edits** (selection edits
+  are unaffected) (#47).
+- **INV-40 (block decision, word-precise attribution)** — accepting a block
+  proposal applies Claude's whole block but attributes **only the runs Claude
+  actually changed** to Claude; **unchanged spans within the block keep their
+  prior authorship**. Mechanism: an intra-block **word** sub-diff at accept time
+  (reusing `diffToHunks`) drives one `applyAgentEdit` per changed run. The **block
+  is the decision unit; the word is the attribution unit** (#47).
+- **INV-41 (block-insertion anchoring)** — a newly **inserted** block (one Claude
+  added) is anchored to an adjacent block boundary so its proposal **resolves and
+  is acceptable** — the block-level analogue of `anchorInsertion`; **no
+  unresolvable zero-width block proposal** (#47).
+- **INV-42 (accept-all = batched F4 seam; current doc; orphan-skip)** —
+  `cowriting.acceptAllProposals` applies **every pending proposal on the current
+  document** through the existing `acceptById` seam, in a **re-anchor-safe order**,
+  **skipping (never force-applying)** proposals that can't anchor, and **reports
+  applied-vs-skipped**. It is a **batched application of the existing accept path**,
+  not a new mechanism; the webview button posts **intent** (INV-35). Per-proposal
+  ✓/✗ is unchanged (#46).
+
+**Supersession (explicit):** **INV-39 reverses INV-37** (document rewrite → per
+*hunk*/word) in favour of per *block*. INV-37's word-level engine (`diffToHunks`)
+is **not removed** — it is **repurposed** as the intra-block sub-diff that
+realizes INV-40's word-precise attribution. The F11 spec carrying INV-37 is
+un-graduated (§9); this spec is the canonical home of the superseding decision.
+
+### 6.2 High-level architecture
+
+All three increments are localized to four already-existing files; no new module
+is required (one new pure function + one new command + menu JSON).
+
+```mermaid
+flowchart TD
+  pkg["package.json\n(menus: editor/context + editor/title/context)"] -. "#42 wiring" .-> cmds
+  cmds["editSelection / editDocument\n(existing commands)"] --> rep["runEditAndPropose\n(trackChangesPreview.ts)"]
+  rep -- "selection branch (unchanged)" --> single["one single-range proposal"]
+  rep -- "document branch (#47)" --> dbh["diffToBlockHunks\n(trackChangesModel.ts — NEW, pure)"]
+  dbh --> blockprops["one proposal per changed block\n(granularity: 'block')"]
+  single & blockprops --> pc["ProposalController\n(proposalController.ts)"]
+  pc -- "accept (block) → intra-block sub-diff (#47, INV-40)" --> attr["AttributionController.applyAgentEdit\n(per changed run)"]
+  pc -- "acceptAll (#46, INV-42)" --> pc
+  tb["preview toolbar\nAccept all button"] -- "{type:'acceptAll'} intent (INV-35)" --> pc
+```
+
+- **`package.json`** (#42) — add `editSelection` + `editDocument` to
+  `editor/context` and `editor/title/context`, each with a selection-state `when`
+  clause; titles "Ask Claude to Edit Selection" / "Ask Claude to Edit Document".
+- **`trackChangesModel.ts`** (#47, pure / vscode-free) — add
+  **`diffToBlockHunks(currentText, rewrittenText): EditHunk[]`**: split both sides
+  into the existing block units, diff blocks (reusing `diffBlocks`/`diffArrays`
+  keying), and emit **one `EditHunk` per changed-or-added block** spanning the
+  whole block's source range → its rewrite text; fences atomic; inserted blocks
+  anchored (INV-41). Returns the same `EditHunk[]` shape `diffToHunks` does, so the
+  proposal-minting loop is unchanged. **`diffToHunks` stays** as the intra-block
+  sub-diff helper for INV-40.
+- **`trackChangesPreview.ts`** (#42/#47) — `runEditAndPropose`'s **document
+  branch** calls `diffToBlockHunks` instead of `diffToHunks`, and tags each minted
+  proposal `granularity: "block"`; `editDocument` resolves the **tab's** document
+  (URI arg) when invoked from `editor/title/context`, not only `activeTextEditor`.
+  Adds the `acceptAll` inbound-message case (#46) → `proposals.acceptAllProposals`.
+- **`proposalController.ts`** (#47/#46):
+  - `accept` (#47): when `proposal.granularity === "block"`, instead of one
+    whole-block `applyAgentEdit`, compute the intra-block word sub-diff
+    (`diffToHunks(resolvedBlockText, proposal.replacement)`) and apply **one
+    `applyAgentEdit` per changed run** (Claude-attributed), unchanged runs left in
+    place — one undo-grouped edit. Non-block proposals keep the existing single
+    `applyAgentEdit`.
+  - `acceptAllProposals(document)` (#46): gather pending proposals, apply via
+    `acceptById` in **descending document order** (last anchor first, so earlier
+    anchors' offsets stay valid), skip orphans (suppressing per-item warnings),
+    and return `{ applied, skipped }` for the controller to report.
+
+### 6.3 Data model & ownership
+
+**No new persisted artifact** (INV-20). The only model change is **one optional
+field** on the F4 `Proposal`:
+
+```ts
+// F4 sidecar Proposal — additive, optional, defaulted (back-compat):
+interface Proposal {
+  // …existing fields…
+  granularity?: "block" | "single";   // "block" ⇒ accept reconciles attribution per word (INV-40)
+}
+```
+
+- A document-edit proposal is minted with `granularity: "block"`; selection
+  proposals are `"single"` (or absent → treated as single). A missing field on an
+  older sidecar reads as `"single"` — existing proposals accept exactly as before.
+- New transient webview message (host ⇄ webview), extending the F11 toolbar
+  intents:
+
+```ts
+// webview → host (intent only — INV-35)
+type ToolbarMsg =
+  | /* …existing: setMode | accept | reject | pinBaseline | askClaude… */
+  | { type: "acceptAll" };
+```
+
+Baseline owned by F6; proposals by F4 (sidecar); attribution by F3. This cluster
+adds no new ownership.
+
+### 6.4 Interfaces & contracts
+
+- **`trackChangesModel`** (vscode-free): `diffToBlockHunks(currentText: string,
+  rewrittenText: string): EditHunk[]` — deterministic; one hunk per changed/added
+  block over the existing block units; fences atomic; inserted blocks anchored
+  (INV-41). Same `EditHunk` shape as `diffToHunks`. `diffToHunks` is **retained**
+  (intra-block sub-diff for INV-40).
+- **`ProposalController`**: `acceptAllProposals(document): Promise<{ applied:
+  number; skipped: number }>` — batched accept over the document's pending set via
+  the existing `acceptById` seam, re-anchor-safe order, orphan-skip (INV-42). The
+  private `accept` gains the block-aware attribution branch (INV-40) keyed off
+  `proposal.granularity`.
+- **Commands**: `cowriting.editDocument` (existing — extended to resolve a tab
+  URI arg); new `cowriting.acceptAllProposals` (active doc; reachable outside the
+  webview).
+
+### 6.5 Per–Product-Use-Case design
+
+- **PUC-1/2/3 (#42)** — pure `package.json` menu wiring + the `editDocument` tab
+  URI resolution. `runEditAndPropose` is reached unchanged; the only code touch is
+  resolving the right document for the tab gesture (mirroring #41's clicked-doc
+  resolution).
+- **PUC-4 (#47 cut)** — `diffToBlockHunks` replaces `diffToHunks` in the document
+  branch. For each `BlockOp` that is `changed` or `added`, emit one `EditHunk`:
+  `changed` → `[block.start, block.end) → after-block text`; `added` → a zero-width
+  range anchored to the adjacent block boundary (INV-41) with the new block text +
+  a separating newline as needed; `removed` → a hunk that deletes the block;
+  `unchanged` → nothing. Fences (`atomic`) emit one whole-fence hunk (never
+  word-refined).
+- **PUC-5 (#47 attribution, INV-40)** — at accept of a `block` proposal: re-resolve
+  the anchor → the current block text; `diffToHunks(currentBlockText,
+  replacement)` → the word-level changed runs *within* the block; apply each run's
+  replacement via `applyAgentEdit` (Claude-attributed) in one undo-grouped
+  `WorkspaceEdit`, leaving unchanged runs untouched so their prior attribution
+  stands. Net buffer text equals the whole-block replacement; net attribution is
+  word-precise.
+- **PUC-6 (#46)** — `acceptAllProposals`: snapshot the pending list, sort
+  descending by resolved anchor start, `acceptById` each (block proposals take the
+  INV-40 path automatically), tally applied vs. skipped-orphan, report once.
+
+### 6.6 Non-functional requirements & cross-cutting concerns
+
+- **Determinism / testability** — `diffToBlockHunks` is pure and vscode-free
+  (unit-tested like `diffToHunks`/`diffBlocks`). The INV-40 attribution
+  reconciliation is exercised through the controller with a fake document.
+- **Security** — unchanged: the webview stays sealed; **Accept all** posts intent;
+  the host validates and performs every mutation (INV-8/21/35). No LLM/secret
+  surface enters the sandbox.
+- **Performance** — block diffing is cheaper than the prior word fan-out (fewer
+  proposals minted/rendered). Accept-all is O(pending) seam calls; large documents
+  bounded by proposal count, not document size.
+- **Reversibility** — accept-all is one undo-restorable step-set; block accept is
+  one undo-grouped edit. No destructive irreversibility.
+
+### 6.7 Key decisions & alternatives considered
+
+| Decision | Chosen | Alternative (rejected) |
+| --- | --- | --- |
+| Cluster artifact | **One combined Solution Design**, three increments sequenced #42→#47→#46 (§3.3 — one design absorbs the roadmap) | Three separate specs — more duplication of the shared F11 edit path + F4 seam |
+| #47 block model | **Reuse `splitBlocks`/`diffBlocks`** | Invent a second "block" notion — divergence risk (capture warned against it) |
+| #47 attribution of unchanged words in an accepted block | **Preserve unchanged spans** — block decision, word-precise attribution (INV-40), via intra-block `diffToHunks` sub-diff at accept | **Whole block → Claude** — simpler (one seam call) but loses F3 fidelity inside the block; operator chose fidelity |
+| #47 vs INV-37 | **Supersede** INV-37 for document edits; **repurpose** `diffToHunks` as the intra-block engine | Keep word-level proposals + a separate "group view" — two models, more surface |
+| #46 apply-order | **Descending document order** through `acceptById` (each accept re-resolves the fingerprint, INV-11) | Re-resolve-then-rescan after every accept — more work for the same result |
+| #46 confirmation | **None** (undo restores) | A confirm dialog — friction the single-accept path doesn't have |
+| #46 scope | **Current document only** | Workspace-wide — capture non-goal |
+| #42 surfaces | **Body + tab only**, selection-aware | Add Explorer entry — capture non-goal (#41 covers Explorer for the review panel) |
+
+### 6.8 Testing strategy
+
+- **Unit (vitest, pure)** — `diffToBlockHunks`: N words across M blocks → **M**
+  hunks (one per changed block, spanning the block); unchanged block → none;
+  changed fence → **one atomic** hunk; inserted block → an anchored, resolvable
+  hunk (INV-41); each hunk's `[start,end)` lands on real block boundaries in
+  `currentText`.
+- **Unit (controller)** — INV-40: accepting a block proposal whose replacement
+  changes 2 of 6 words attributes **only those 2 runs** to Claude (the other 4
+  keep prior author); orphaned block proposal is flagged, not force-applied.
+- **Host E2E (Playwright)** —
+  - #42: body no-selection shows **Edit Document**; body selection shows **Edit
+    Selection**; tab shows the right one per selection state; each produces
+    proposal(s).
+  - #47: a document edit changing words across M blocks yields **M proposals**,
+    each spanning its block; unchanged block → none; changed fence → one atomic
+    proposal; an inserted block accepts cleanly.
+  - #46: with N pending proposals, **Accept all** applies all N (text replaced,
+    Claude-attributed, proposals cleared); an orphaned proposal in the set is
+    skipped and **reported**, not mangled; the button is hidden with < 2 pending.
+- **Manual smoke** — extend `docs/MANUAL-SMOKE-F11.md` (or a new
+  `MANUAL-SMOKE-F12.md`) covering the three gestures end-to-end.
+
+### 6.9 Failure modes, rollback & flags
+
+- **Orphaned proposal** (target text changed / missing) — single accept already
+  warns + flags (never applied by guess); accept-all **skips** it and includes it
+  in the applied-vs-skipped report (INV-42). Reject-or-undo remains the recovery.
+- **Inserted block fails to anchor** — INV-41's adjacent-boundary anchoring makes
+  this resolvable; if the boundary block itself later changes, the proposal orphans
+  and is handled as above (never silently dropped).
+- **Back-compat** — the additive `granularity` field defaults to `"single"`;
+  pre-existing sidecars/proposals accept unchanged. No migration.
+- **No feature flags** — each increment ships green through the pipeline; this is
+  a VS Code extension (no flotilla deploy stage).
+
+---
+
+## 7. Delivery Plan
+
+### 7.1 Approach / strategy
+
+Ship the flow **reach → review → accept** as three independent
+planning-and-executing increments, each its own PR, in sequence. They are
+**code-independent** (different files / functions), so the order is chosen for
+**user-visible value compounding**, not technical dependency — each increment is
+usable on its own.
+
+> **WSJF note (transparent):** **#47 carries the P1 value** ("too much to review"
+> is the sharpest pain); #42 and #46 are P2. The operator set the goal "starting
+> with #42," and #42 is the smallest, lowest-risk increment (the command already
+> exists — it's menu wiring), so leading with it completes the entry-point story
+> first. Because the three are code-independent, **#47 and #42 could swap** with no
+> rework if the P1 review pain should land first — a one-line resequencing.
+
+### 7.2 Slicing plan
+
+- **SLICE-1 — #42 (reach).** `package.json` menus (`editor/context` +
+  `editor/title/context`, selection-aware, markdown-gated); `editDocument`
+  resolves the tab's document; titles. **+ E2E** (body/tab × selection state →
+  right item → proposal). Smallest; no model change. (INV-38.)
+- **SLICE-2 — #47 (review).** `diffToBlockHunks` (pure, + unit tests); document
+  branch of `runEditAndPropose` switches to it and tags `granularity:"block"`;
+  block-aware accept in `ProposalController` (intra-block sub-diff, INV-40);
+  block-insertion anchoring (INV-41). **Supersede INV-37 → INV-39** in the spec/
+  invariant set. **+ unit + E2E.** The substantive increment. (INV-39/40/41.)
+- **SLICE-3 — #46 (accept).** `acceptAllProposals` (controller, re-anchor-safe
+  order, orphan-skip + report); `cowriting.acceptAllProposals` command; preview
+  toolbar **Accept all** button + `{type:"acceptAll"}` intent (shown ≥2 pending).
+  **+ E2E.** (INV-42.)
+
+### 7.3 Rollout / launch plan
+
+No deploy pipeline (VS Code extension — no flotilla / PPE / prod stages; the §9
+pipeline's deploy stages don't apply). Each slice merges to `main` green
+(unit + host E2E). "Done" = merged with tests green; there is no prod-promotion
+gate for an extension increment.
+
+### 7.4 Risks & mitigations
+
+| Risk | Mitigation |
+| --- | --- |
+| INV-40 intra-block multi-edit accept skews offsets mid-apply | Apply changed runs **last-position-first** within the block, one undo-grouped `WorkspaceEdit`; unit-test the 2-of-6-words case |
+| Block taxonomy edge cases (lists w/o blank lines, tables, blockquotes, nested) | **Reuse `splitBlocks` exactly** — whatever it already treats as one block *is* one proposal; document the taxonomy = the splitter's, no second notion |
+| Inserted-block anchor collides / can't resolve | INV-41 anchors to an adjacent **unchanged** block boundary; orphan-handling is the backstop (never force-applied) |
+| Accept-all on a large pending set partially applies then an orphan appears | Each `acceptById` is independent + re-resolves (INV-11); skipped orphans reported; undo restores the whole step-set |
+| F11 spec un-graduated → INV-35/36/37 only in code | This spec restates the load-bearing F11 invariants it depends on; §9 logs the graduation gap as a follow-up |
+
+---
+
+## 8. Traceability matrix
+
+| Requirement | PUC | Invariant / §6 | Slice | Feature |
+| --- | --- | --- | --- | --- |
+| Ask-Claude reachable body (no-sel) + tab, selection-aware | PUC-1/2/3 | INV-38, §6.5 | SLICE-1 | #42 |
+| Selection edit unchanged | PUC-2 | INV-38 (single path) | SLICE-1 | #42 |
+| Document edit → one proposal per changed block | PUC-4 | INV-39, §6.5 (`diffToBlockHunks`) | SLICE-2 | #47 |
+| Unchanged block → no proposal; fence atomic | PUC-4 | INV-39, INV-23 | SLICE-2 | #47 |
+| Accepted block attributes only changed words to Claude | PUC-5 | INV-40, §6.5 | SLICE-2 | #47 |
+| Inserted block anchors + accepts | PUC-4 | INV-41 | SLICE-2 | #47 |
+| Accept-all over current doc, orphan-skip + report | PUC-6 | INV-42, §6.5 | SLICE-3 | #46 |
+| All mutation via the F4 seam; webview intent-only | PUC-4/5/6 | INV-35, §6.6 | SLICE-2/3 | #47/#46 |
+
+---
+
+## 9. Open Questions & Decisions log
+
+**Decided this session (operator):**
+
+- **D-1** — #47 accepts **preserve unchanged-span attribution** (block = decision
+  unit, word = attribution unit; INV-40). *Not* whole-block→Claude.
+- **D-2** — the cluster ships as **one** combined Solution Design (this doc),
+  three sequenced increments.
+- **D-3 (driver call, low-confidence — for finalize review)** — sequence **#42 →
+  #47 → #46** per the goal's "starting with #42," despite #47 carrying the P1
+  value. The three are code-independent so the order is reversible (§7.1).
+- **D-4 (driver call)** — block taxonomy = **exactly `splitBlocks`'s** units (no
+  second notion of "block"); list/table/blockquote/nested behavior is whatever the
+  splitter already does.
+- **D-5 (driver call)** — accept-all needs **no confirmation** (undo restores);
+  button shown at **≥ 2** pending.
+
+**Open / deferred:**
+
+- **OQ-1** — Should **selection** edits *also* preserve-unchanged-span
+  attribution for consistency with INV-40? Out of #47's captured scope (selection
+  edits explicitly unchanged); a future consistency pass could unify them. **Not
+  in this cluster.**
+- **OQ-2 (spec-hygiene, not blocking)** — the **F11 (#43) Solution Design is
+  un-graduated** — INV-35/36/37 live only in code comments + the issue draft
+  `issues/preview-toolbar-interaction-surface.md`, not in `specs/`. This spec
+  restates the F11 invariants it depends on and supersedes INV-37 here, but the
+  F11 design should be graduated to `specs/` for a clean invariant ledger.
+  Captured for finalize as a follow-up.
+- **OQ-3** — Very large blocks: no special fallback is specified (block proposals
+  are bounded by the block, and accept reconciles per word). Revisit only if a
+  pathological single-giant-block document surfaces.
+
+---
+
+## 10. Glossary & References
+
+- **Block** — the unit `splitBlocks` recognizes: a prose paragraph, header, or
+  bullet/list item; a code or mermaid fence (atomic, INV-23). The #47 decision
+  unit.
+- **Block proposal** — an F4 proposal whose anchor spans a whole block and whose
+  replacement is Claude's whole version of that block (`granularity: "block"`).
+- **Intra-block sub-diff** — the word-level `diffToHunks` run *inside* an accepted
+  block to realize word-precise attribution (INV-40).
+- **`diffToHunks` / `diffToBlockHunks`** — word-level (legacy INV-37; now the
+  intra-block engine) / block-level (INV-39, new) document-rewrite differs, both
+  emitting `EditHunk[]`.
+- **References** — `coauthoring-propose-accept.md` (F4 seam, INV-9..13),
+  `coauthoring-interactive-review.md` (F10 preview, INV-32..34),
+  `coauthoring-attribution.md` (F3, `applyAgentEdit`/`spansFor`),
+  `issues/preview-toolbar-interaction-surface.md` (F11, INV-35..37 — un-graduated),
+  features `#42` / `#47` / `#46`, capture sessions `0035` / `0040` / `0039`,
+  brainstorming session `0041`. Lineage `ben.stull/rfc-app#48`.