From 7d842a840e7207149c4a50d8dbe52db14305196e Mon Sep 17 00:00:00 2001 From: BenStullsBets Date: Sun, 28 Jun 2026 07:47:51 -0700 Subject: [PATCH] =?UTF-8?q?spec(0062):=20no=20flow=20requires=20the=20Sour?= =?UTF-8?q?ce=20Control=20pane=20=E2=80=94=20title=20bar=20+=20status=20ba?= =?UTF-8?q?r=20are=20primary=20(D16/INV-13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Non-git writers (~/Downloads, untitled) won't know to open Source Control. So: editor title-bar actions (Review Changes / Ask Claude / Toggle Annotations / Mark Changes as Reviewed) + '✦ Coediting · N changes' status-bar item (click -> review) + auto-open review on proposals are the primary entry points; SCM viewlet + gutter become optional git-user extras. Resolves Q3. Updated INV-13, §5 UX, PUC-1/2, decisions; also removed the stale open Q8 (resolved by D14). Co-Authored-By: Claude Opus 4.8 (1M context) --- specs/coauthoring-native-surfaces.md | 50 ++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 11 deletions(-) diff --git a/specs/coauthoring-native-surfaces.md b/specs/coauthoring-native-surfaces.md index 3782a91..0bdcb6e 100644 --- a/specs/coauthoring-native-surfaces.md +++ b/specs/coauthoring-native-surfaces.md @@ -282,6 +282,7 @@ Scenario: PUC-1 — see the diff against the baseline checkpoint (realizes BUC-1 Given I am coediting a document (its baseline is the last commit if it's in git, else a snapshot taken on entry) When I (or the machine) change the document Then the source-control gutter shows change bars for what changed since the checkpoint + And a Review Changes button in the editor title bar and a "✦ Coediting · N changes" status-bar item open the review without visiting the Source Control pane And "Open Changes" opens the native diff editor (baseline ⟷ live), inline or side-by-side at my choice And committing the file (when it's in a git repo) advances the baseline to the new commit (the diff goes clean) And "Mark Changes as Reviewed" is offered only when the file has no commit to anchor to (outside a repo, untitled, or not-yet-committed), and resets the checkpoint there @@ -364,15 +365,23 @@ panel to wireframe. Described in text (source of truth): turns the active document into a coedited document; a **"Stop editing with Claude"** command — in the same command palette **and the editor/explorer context menu** — reverses it. A subtle status-bar item ("✦ Coediting") indicates when the active - document is in coediting mode. Until a document is entered, **none** of the - surfaces below attach to it (INV-10). **Entering also sets the baseline to the - document's current content** — a clean checkpoint to measure future changes - against (INV-7). -- **Source Control gutter & viewlet.** A dedicated source-control entry, - *"Cowriting,"* coexists with Git. Its quick-diff provider draws the familiar - change bars in the editor gutter against the pinned baseline; its resource group - lists the document's pending coauthoring changes; "Open Changes" uses the native - diff editor. + document is in coediting mode **and the change count** (`✦ Coediting · N changes`), + and **clicking it opens the review** — so the writer never needs to find the Source + Control pane (INV-13). Until a document is entered, **none** of the surfaces below + attach to it (INV-10). **Entering also sets the baseline to the document's current + content** — a clean checkpoint to measure future changes against (INV-7). +- **Primary actions — editor title bar + status bar (no navigation, INV-13).** When + the document is coedited, title-bar buttons (**Review Changes**, **Ask Claude**, + **Toggle Annotations**, and in snapshot mode **Mark Changes as Reviewed**) and the + `✦ Coediting · N changes` status-bar item are the everyday entry points — visible + without going anywhere. The review also **auto-opens** on new proposals, and the + live-progress notification carries a *Review* action. +- **Source Control gutter & viewlet (optional, for git users).** A dedicated + source-control entry, *"Cowriting,"* coexists with Git: its quick-diff provider + draws the familiar change bars in the editor gutter against the baseline checkpoint, + its resource group lists the document's pending coauthoring changes, and "Open + Changes" uses the native diff editor. A bonus home for those who use Source Control + — never the required path (INV-13). - **Native diff editor.** The writer's normal diff (`baseline ⟷ live`), with the platform's inline/side-by-side toggle, navigation, and accessibility. - **Multi-diff review editor.** When the machine proposes edits, a multi-diff editor @@ -480,6 +489,13 @@ coauthoring **displaced** state surfaced in the thread / proposed-change listing color scoping — §6.7). Authorship (human vs. machine) is shown on a surface the extension renders: the annotated preview (and optionally a decoration-based track-changes editor), never by recoloring the native diff. +- **INV-13 — no surface requires the Source Control pane:** the primary, + always-visible entry points for a coedited document are the **editor title-bar + actions** and a **status-bar item** (both gated on `cowriting.isCoediting`), and the + review **auto-opens** on new machine proposals. The SCM viewlet entry and the gutter + dirty-diff are additional native affordances, not the required path — a writer + unfamiliar with git / Source Control never has to find them to coedit, review, or + settle a checkpoint. - **INV-12 — proposed changes are editable before they are kept:** the review surface presents the machine's proposal on a **writable** side, so the writer can tweak it in place before keeping it (the common "close, but a few human edits" @@ -690,6 +706,18 @@ sequenceDiagram then shows clean green/blue with no post-hoc untangling. *Open detail (§13-Q7):* how per-change Keep/Undo behaves once the writer has freely edited across hunks. +#### Always-visible entry points (no Source Control navigation) — INV-13 + +- **Implementation:** reviewing changes must **never require finding the Source + Control pane** (writers working outside git — `~/Downloads`, untitled — won't know + it exists). When `cowriting.isCoediting` is set, the actions surface where the + writer already is: **editor title-bar buttons** (Review Changes, Ask Claude, Toggle + Annotations, and in snapshot mode Mark Changes as Reviewed) and a **status-bar + item** (`✦ Coediting · N changes`, click → Review Changes). The multi-diff review + **auto-opens** on new proposals, and the live-progress notification carries a + *Review* action. The SCM viewlet entry and the gutter dirty-diff remain as native + extras for git-literate users, never the required path. + #### PUC-3 — annotated rendered preview ```mermaid @@ -798,6 +826,7 @@ sequenceDiagram | Authorship surface | **Option 1** — the annotated preview is the authorship view (green/blue track-changes incl. deletions); native diff stays author-blind | Option 2 (in-editor decorations); Option 3 (owned author-colored track-changes diff that replaces native diff) | Preview shows author-colored changes for near-zero maintenance; editable proposals (INV-12) keep authorship clean *at creation*, so in-editor / post-hoc authorship rendering is unnecessary. Opts 2/3 deferred | | Editing proposals | the proposed side of the review is **writable**; pre-Keep tweaks are absorbed and attributed (machine vs. writer) at Keep (INV-12) | machine proposal read-only (tweak only after accepting) | Most revisions are "close, but a few human edits"; editing at review time keeps authorship clean at creation and avoids messy post-acceptance untangling | | Coediting activation | opt-in per document via "Coedit this Document with Claude"; every surface gated on the active coediting set (INV-10) | always-on for all markdown; opt-in per workspace/folder | Per-document opt-in is the only grain that avoids hijacking Comments/SCM/preview for the writer's other files while keeping single-file precision | +| Change discovery (resolves Q3) | primary entry = **editor title bar + status-bar item + auto-open review**; the SCM viewlet + gutter are optional extras (INV-13) | rely on the Source Control pane / gutter as the entry point | Writers working outside git won't find (or know) the Source Control pane; always-visible title-bar / status-bar actions need no git familiarity | | Authorship in the diff | the native diff is **author-blind** (what changed); authorship is shown in the preview, optionally a decoration track-changes editor (INV-11) | recolor machine changes inside the native diff editor | **Not possible:** `diffEditor.*` colors are global theme tokens with no per-author scoping; `inlineEdit.*`/chat tokens differentiate accept-state not author; decorations over the diff pane composite over green/red and are unreliable (vanish on tab-switch). Verified against the VS Code API (§13-Q5) | | Comment → machine response | on a coedited doc, a comment fires a turn that replies + offers an edit → pending proposal | comment is inert (human-only threads) | Turns the familiar review-comment gesture into a coediting action without a new surface; the opt-in gate (INV-10) keeps it from firing on other docs | | Comments & the preview | comments are **native** (source gutter + Comments panel); the preview can *initiate* a comment (selection → source range via the `markdown-it` source map) and show a deep-linking 💬 marker, but cannot **host** the thread (it's a webview — verified) | render a bespoke comment widget inside the preview webview | Keeps comments on the native surface (no INV-3 exception, keeps the Comments panel + gutter); the writer can still comment on what they're reading and add whole-document comments (top-anchored) | @@ -961,10 +990,8 @@ a bug reaches us as a tracker issue. | --- | --- | --- | --- | | Q1 | Product packaging & delivery sequence — the decision to act on this north star | Ben | Any implementation plan | | Q2 | Per-change Keep/Undo: how far can the stable API go before falling back to per-hunk CodeLens? | Ben | PUC-2 build (last surface) | -| Q3 | One "Cowriting" SourceControl vs. QuickDiff-only (no full SCM viewlet entry) — how much SCM presence is wanted | Ben | PUC-1 build | | Q4 | Does any need genuinely require a webview the native surfaces can't serve (INV-3 escape hatch)? | Ben | Per-surface build | | Q7 | Once the writer freely edits the proposal across hunks (INV-12), how do per-change Keep/Undo behave — do per-hunk actions survive arbitrary edits, or does free editing collapse the change set to a single Keep/Reject-all? | Ben | PUC-2 build | -| Q8 | In a git-tracked file, may a manual pin checkpoint *ahead* of `HEAD` (finer than commits), or is committing the only reset for git files? (Spec currently: pin allowed everywhere, superseded by the next commit.) | Ben | PUC-1 build | **Resolved** @@ -985,6 +1012,7 @@ a bug reaches us as a tracker issue. | D13 | Baseline semantics & source | Baseline = the last settled version. Its **source follows the file's home**: git `HEAD` where tracked (auto-resets on commit, storage-free), else a snapshot set on entry (global storage / in-memory). A coedited doc always has a baseline; the only empty state is a genuinely empty document (INV-7) | 2026-06-27 | | D14 | Pin is the non-git fallback only (resolves Q8) | "Mark Changes as Reviewed" exists **only in snapshot mode** (no committed `HEAD`); git-tracked files have no manual pin — the writer **commits** and the baseline follows `HEAD`. The pin command is `when`-gated on `cowriting.baselineMode == snapshot` | 2026-06-27 | | D15 | Comments & the preview | Native comment threads can't render in the preview (it's a webview — verified). The preview *initiates* a comment (selection → source range via the `markdown-it` source map) and shows deep-linking 💬 markers; a whole-document comment anchors at the top. Threads stay native (gutter + Comments panel); no bespoke in-webview comment UI | 2026-06-27 | +| D16 | Change discovery (resolves Q3) | No flow requires the Source Control pane (INV-13). Primary entry = editor title-bar actions + `✦ Coediting · N changes` status-bar item + auto-open review; SCM viewlet + gutter kept as optional git-user extras | 2026-06-27 | ## 14. Glossary & References