From 1d27b74a2bbabd8b2f0a4261a93cbaa8ac277792 Mon Sep 17 00:00:00 2001 From: BenStullsBets Date: Sun, 28 Jun 2026 07:23:02 -0700 Subject: [PATCH] spec(0062): rename pin command to 'Mark Changes as Reviewed' Replaces the jargon 'Pin Review Baseline to Now' (snapshot-mode reset) with the user-intent label 'Mark Changes as Reviewed', which fits the review framing of the product. Label-only; semantics unchanged (snapshot-mode only). Co-Authored-By: Claude Opus 4.8 (1M context) --- specs/coauthoring-native-surfaces.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specs/coauthoring-native-surfaces.md b/specs/coauthoring-native-surfaces.md index 1f64247..0db301d 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 "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 + 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 ``` ```gherkin @@ -438,8 +438,8 @@ coauthoring **displaced** state surfaced in the thread / proposed-change listing file's uncommitted work, git-native and storage-free. **Where there is no commit to 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). **"Pin Review Baseline to Now" exists only in + **"Mark Changes as Reviewed,"** stored in extension global storage keyed by URI + hash (in-memory for untitled). **"Mark Changes as Reviewed" 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 @@ -574,7 +574,7 @@ state (INV-7), not durable coauthoring metadata. Git extension API; auto-advances on commit, watched via `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 + `enterCoediting` (reason `entered`) and on **"Mark Changes as Reviewed"** (reason `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 @@ -629,7 +629,7 @@ sequenceDiagram participant C as SCM/QuickDiff ctrl participant B as Baseline provider participant V as Native diff editor - U->>C: Pin baseline + U->>C: Mark Changes as Reviewed C->>B: BaselineStore.pin(docUri, text) U->>U: edits document (or the machine proposes) C-->>U: gutter dirty-diff bars (provideOriginalResource) @@ -793,7 +793,7 @@ sequenceDiagram `diffToBlockHunks`), the `turnProgress` reducer, and the `renderAnnotations` markdown-it transform (token-in → annotated-token-out). - **Integration / E2E (`@vscode/test-electron`):** drive the controllers in the - Extension Development Host — pin baseline → assert QuickDiff original; ask-to-edit + Extension Development Host — mark-reviewed → assert checkpoint reset; ask-to-edit → assert pending proposals + multi-diff opened; Keep/Undo → assert document mutation only on Keep + authorship recorded; toggle annotations → assert preview HTML marks; thread create → re-anchor → displaced. Where the harness cannot drive @@ -965,13 +965,13 @@ a bug reaches us as a tracker issue. | 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 (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 | +| 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 | ## 14. Glossary & References - **Baseline (checkpoint)** — the last settled version, used as the diff *original*. Its source follows the file's home: git `HEAD` for tracked files (resets on - commit), else a snapshot set on entry and reset by "Pin Review Baseline to Now." + commit), else a snapshot set on entry and reset by "Mark Changes as Reviewed." Disposable; never committed by us (INV-7). - **QuickDiffProvider** — the VS Code API that supplies gutter dirty-diff bars from a virtual *original* document.