hl-valdemar/vamp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs: establish pre-alpha clean-cutover policy

Browse Source
This commit is contained in:
Valdemar Lorenzen
2026-10-16 15:12:14 +02:00
parent 5b8f8c3f07
commit 0c7abc17fe
2 changed files with 9 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+5
View File
@@ -0,0 +1,5 @@
# Compatibility
Vamp is a single-user, pre-alpha tool. Prefer clean cutovers to the simplest current design across code, configuration, interfaces, and persisted formats. Update callers and remove obsolete paths together; add backwards compatibility or migrations only when explicitly requested.
Report incompatible persisted data clearly and preserve it unless the user explicitly requests a reset or deletion.
TODO.md
+4 -4
View File
@@ -6,14 +6,12 @@
- save and reopen reviews using local files that coding agents can read; no server or client/server protocol. - save and reopen reviews using local files that coding agents can read; no server or client/server protocol.
- anchor comments to immutable revision IDs, paths, sides, and source line ranges, never screen coordinates or mutable file indices. - anchor comments to immutable revision IDs, paths, sides, and source line ranges, never screen coordinates or mutable file indices.
- preserve original anchors and mark comments stale when the reviewed snapshot no longer matches; defer automatic reanchoring. - preserve original anchors and mark comments stale when the reviewed snapshot no longer matches; defer automatic reanchoring.
- [ ] add an option for three pane lef/base/right view for conflict resolution.
- alternative pane layout as left/right with base underneath (configurable)
- [x] diff view: attach local review comments to arbitrary contiguous text ranges, not only containing lines. - [x] diff view: attach local review comments to arbitrary contiguous text ranges, not only containing lines.
- preserve exact start/end source positions in grapheme coordinates with an exclusive end, including partial-line and multiline selections on either diff side. - preserve exact start/end source positions in grapheme coordinates with an exclusive end, including partial-line and multiline selections on either diff side.
- characterwise Visual (`v`) anchors the exact selected text; Visual Line (`V`) anchors whole selected lines; no selection retains current-line behavior. - characterwise Visual (`v`) anchors the exact selected text; Visual Line (`V`) anchors whole selected lines; no selection retains current-line behavior.
- retain gutter markers for discovery and highlight the exact anchored text when its comment is selected. - retain gutter markers for discovery and highlight the exact anchored text when its comment is selected.
- preserve immutable snapshot identity and existing stale detection; never silently reanchor comments after source changes. - preserve immutable snapshot identity and existing stale detection; never silently reanchor comments after source changes.
- persist precise ranges in version 2 JSON import/export; no backwards compatibility with old review formats. SQLite storage follows in the next item. - persist precise ranges in version 2 JSON import/export. SQLite storage follows in the next item.
- future GitHub publishing may map precise local anchors to supported line ranges without reducing precision in the local review. - future GitHub publishing may map precise local anchors to supported line ranges without reducing precision in the local review.
- [ ] persist local reviews automatically in a local SQLite database using rusqlite; no server, hosted storage, or synchronization. - [ ] persist local reviews automatically in a local SQLite database using rusqlite; no server, hosted storage, or synchronization.
- keep one database under $XDG_DATA_HOME/vamp/reviews/, falling back to ~/.local/share/vamp/reviews/; allow a configurable review_directory. - keep one database under $XDG_DATA_HOME/vamp/reviews/, falling back to ~/.local/share/vamp/reviews/; allow a configurable review_directory.
@@ -21,9 +19,11 @@
- autosave committed comment edits and summaries when dismissing or switching review editors; save verdicts and deletions immediately, using transactions rather than per-keystroke writes. - autosave committed comment edits and summaries when dismissing or switching review editors; save verdicts and deletions immediately, using transactions rather than per-keystroke writes.
- automatically reopen the repository's sole review; offer a selector when several exist. - automatically reopen the repository's sole review; offer a selector when several exist.
- retain explicit JSON export/import for sharing with coding agents; export must not redirect subsequent autosaves away from the database. - retain explicit JSON export/import for sharing with coding agents; export must not redirect subsequent autosaves away from the database.
- version the database schema and migrate it safely; use review-version checks to reject conflicting edits from multiple editor instances. - version the database schema; use review-version checks to reject conflicting edits from multiple editor instances.
- surface write failures and conflicts without discarding drafts or marking unsuccessful saves as persisted. - surface write failures and conflicts without discarding drafts or marking unsuccessful saves as persisted.
- persist the precise start/end grapheme anchors without reducing them to line ranges. - persist the precise start/end grapheme anchors without reducing them to line ranges.
- [ ] add an option for three pane lef/base/right view for conflict resolution.
- alternative pane layout as left/right with base underneath (configurable)
- [ ] diff view: GitHub code review integration after the local review UX is usable. - [ ] diff view: GitHub code review integration after the local review UX is usable.
- publish local reviews explicitly: general PR comments, inline line/range comments, review summaries, approval, and requests for changes. - publish local reviews explicitly: general PR comments, inline line/range comments, review summaries, approval, and requests for changes.
- preserve explicit PR identity and reviewed commit IDs; validate anchors against GitHub's PR diff and recheck the PR head before submission. - preserve explicit PR identity and reviewed commit IDs; validate anchors against GitHub's PR diff and recheck the PR head before submission.