diff --git a/specs/coauthoring-native-surfaces.md b/specs/coauthoring-native-surfaces.md index a6bc3fe..1f64247 100644 --- a/specs/coauthoring-native-surfaces.md +++ b/specs/coauthoring-native-surfaces.md @@ -284,7 +284,7 @@ Scenario: PUC-1 — see the diff against the baseline checkpoint (realizes BUC-1 Then the source-control gutter shows change bars for what changed since the checkpoint 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 running "Pin Review Baseline to Now" resets the checkpoint to the current content (works anywhere, incl. ~/Downloads and untitled) + And "Pin Review Baseline to Now" 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 ``` ```gherkin @@ -337,6 +337,7 @@ Scenario: PUC-7 — enter (and leave) coediting mode (realizes INV-10) When I run "Coedit this Document with Claude" (command, editor title, or context menu) Then this document gains the Cowriting source-control entry, the annotation toggle, and machine-edit/comment-response behavior And the baseline is established — the last commit if the file is in git, otherwise a snapshot of the current content + And any uncommitted changes already in a git-tracked file appear as my (human) changes since the baseline And my other markdown documents are unaffected And running "Stop editing with Claude" (context menu) removes those surfaces (the saved sidecar is kept for next time) ``` @@ -438,15 +439,22 @@ coauthoring **displaced** state surfaced in the thread / proposed-change listing anchor to** (outside any repo, untracked/ignored, brand-new, or untitled), the baseline is a **snapshot** defaulted to the current content on entry and reset by **"Pin Review Baseline to Now,"** stored in extension global storage keyed by URI - hash (in-memory for untitled). A manual pin is available in **both** homes as a - finer checkpoint (in a git file it sits ahead of `HEAD` until the next commit - supersedes it); a new in-repo file flips from snapshot to `HEAD`-tracking on its - first commit. A coedited document therefore *always* has a baseline — there is + hash (in-memory for untitled). **"Pin Review Baseline to Now" exists only in + snapshot mode** (files with no committed `HEAD` to anchor to) — for git-tracked + files there is no manual pin; the writer **commits** and the baseline follows + `HEAD`. A new in-repo file is in snapshot mode until its first commit, then flips to + `HEAD`-tracking (and the pin command disappears). A coedited document therefore *always* has a baseline — there is **no "missing baseline" state**; the only empty state is a genuinely empty document. The baseline is disposable review state, never committed by us. - **INV-8 — provenance carries on-behalf-of identity:** every authored span / message records `provenance` (the human's git identity, or the machine acting `onBehalfOf` a human), reused across attributions, proposed changes, and threads. + Changes **already present when a coediting session starts** (uncommitted work vs. + `HEAD`, *including* edits made outside this experience — by hand or by a machine + elsewhere) carry no prior provenance record, so they are **attributed to the writer + (human)**: the session cannot know their origin and treats them as the writer's + existing work. (In snapshot mode the baseline is the content at entry, so there is + nothing pre-existing to attribute.) - **INV-9 — machine turns are observable and cancellable:** a turn streams progress and honors an `AbortSignal`; the progress reducer is pure. - **INV-10 — coediting is opt-in per document:** every coauthoring surface (the @@ -567,10 +575,10 @@ state (INV-7), not durable coauthoring metadata. `repository.state.onDidChange`); **otherwise → a stored snapshot** (`BaselineStore.snapshot(docUri, text, reason)` / `get(docUri)`), set on `enterCoediting` (reason `entered`) and on **"Pin Review Baseline to Now"** (reason - `pinned`). A pin in a git-tracked file records a snapshot that takes precedence over - `HEAD` until the next commit supersedes it (baseline = most-recent settle). This - mirrors the in-repo/out-of-repo `SidecarRouter` (§6.2). A coedited document always - resolves a baseline; non-coedited documents resolve none. + `pinned`). The **pin command is gated to snapshot mode** — hidden/disabled for + `HEAD`-anchored files (`when: cowriting.baselineMode == snapshot`), where committing + is the reset. This mirrors the in-repo/out-of-repo `SidecarRouter` (§6.2). A coedited + document always resolves a baseline; non-coedited documents resolve none. - **QuickDiffProvider** — `provideOriginalResource(docUri) → cowriting-baseline:` URI (drives gutter bars). Registered on the "Cowriting" `SourceControl`. - **Machine-edit seam** — the single boundary where machine text enters the model: @@ -956,7 +964,8 @@ a bug reaches us as a tracker issue. | D10 | Comment trigger | While a document is in coediting mode, **every** new comment summons the machine (no per-comment gate); coediting mode is the control, "Stop editing with Claude" the off switch | 2026-06-27 | | D11 | Authorship surface (Q5) | Option 1 — the annotated preview is the authorship view; native diff stays author-blind; in-editor decorations (opt 2) and an owned track-changes diff (opt 3) are out of scope | 2026-06-27 | | D12 | Editable proposals | The review's proposed side is writable; the writer tweaks before Keep; machine words vs. writer tweaks are attributed at Keep (INV-12); live doc untouched until Keep (INV-5) | 2026-06-27 | -| 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 + re-pinnable (global storage / in-memory). A manual pin works in both; a coedited doc always has a baseline; the only empty state is a genuinely empty document (INV-7) | 2026-06-27 | +| 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) | "Pin Review Baseline to Now" 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 | ## 14. Glossary & References