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) <noreply@anthropic.com>
This commit is contained in:
BenStullsBets
2026-06-28 07:23:02 -07:00
parent 22393f0d63
commit 1d27b74a2b
+8 -8
View File
@@ -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 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 "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 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 ```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 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 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 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 **"Mark Changes as Reviewed,"** stored in extension global storage keyed by URI
hash (in-memory for untitled). **"Pin Review Baseline to Now" exists only in 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 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 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`. 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 Git extension API; auto-advances on commit, watched via
`repository.state.onDidChange`); **otherwise → a stored snapshot** `repository.state.onDidChange`); **otherwise → a stored snapshot**
(`BaselineStore.snapshot(docUri, text, reason)` / `get(docUri)`), set on (`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 `pinned`). The **pin command is gated to snapshot mode** — hidden/disabled for
`HEAD`-anchored files (`when: cowriting.baselineMode == snapshot`), where committing `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 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 C as SCM/QuickDiff ctrl
participant B as Baseline provider participant B as Baseline provider
participant V as Native diff editor participant V as Native diff editor
U->>C: Pin baseline U->>C: Mark Changes as Reviewed
C->>B: BaselineStore.pin(docUri, text) C->>B: BaselineStore.pin(docUri, text)
U->>U: edits document (or the machine proposes) U->>U: edits document (or the machine proposes)
C-->>U: gutter dirty-diff bars (provideOriginalResource) C-->>U: gutter dirty-diff bars (provideOriginalResource)
@@ -793,7 +793,7 @@ sequenceDiagram
`diffToBlockHunks`), the `turnProgress` reducer, and the `renderAnnotations` `diffToBlockHunks`), the `turnProgress` reducer, and the `renderAnnotations`
markdown-it transform (token-in → annotated-token-out). markdown-it transform (token-in → annotated-token-out).
- **Integration / E2E (`@vscode/test-electron`):** drive the controllers in the - **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 → assert pending proposals + multi-diff opened; Keep/Undo → assert document
mutation only on Keep + authorship recorded; toggle annotations → assert preview mutation only on Keep + authorship recorded; toggle annotations → assert preview
HTML marks; thread create → re-anchor → displaced. Where the harness cannot drive 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 | | 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 | | 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 | | 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 ## 14. Glossary & References
- **Baseline (checkpoint)** — the last settled version, used as the diff *original*. - **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 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). Disposable; never committed by us (INV-7).
- **QuickDiffProvider** — the VS Code API that supplies gutter dirty-diff bars from a - **QuickDiffProvider** — the VS Code API that supplies gutter dirty-diff bars from a
virtual *original* document. virtual *original* document.