From 0c7abc17feb2b03e45b46c577c6cec945502c59b Mon Sep 17 00:00:00 2001 From: Valdemar Lorenzen Date: Fri, 16 Oct 2026 15:12:14 +0200 Subject: [PATCH] docs: establish pre-alpha clean-cutover policy --- AGENTS.md | 5 +++++ TODO.md | 8 ++++---- 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6c81cd9 --- /dev/null +++ b/AGENTS.md @@ -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. diff --git a/TODO.md b/TODO.md index 1f44841..a971f2d 100644 --- a/TODO.md +++ b/TODO.md @@ -6,14 +6,12 @@ - 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. - 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. - 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. - 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. - - 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. - [ ] 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. @@ -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. - 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. - - 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. - 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. - 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.