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`.