Pull request overview

Adds a new CLI entry point for seeding revdiff’s in-TUI annotation workflow from an existing markdown annotations file, using the same bidirectional format already produced by Store.FormatOutput().

Changes:

• Introduces --annotations=PATH flag and startup preload pipeline that parses -o-style markdown and populates the annotation store while dropping orphaned records with warnings.
• Adds a strict markdown parser (annotation.Parse) that round-trips with Store.FormatOutput, including file-level, line-level, and range headers plus escaped ## body lines.
• Updates documentation and agent skill references to describe round-trip preload workflows; adds tests for parsing and preload/orphan handling.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tests / lint / race green. parser tests are well shaped: table-driven, round-trip property test, path-with-colon edge case all covered. before merge a few things worth addressing:

block:

1. sanitize comment text on parse. Annotation.Comment flows verbatim from file into Store.Add, then through Renderer.AnnotationInline which wraps raw bytes in ANSI italic. The PR's headline use case is LLM-generated review.md, and the new skill flow in SKILL.md ("Opening an In-Session Review") makes Claude itself the agent producing the file from arbitrary conversation context. That context can plausibly contain raw \x1b[...] sequences, CR-overwrite tricks, or stray escapes (terminal output pasted into chat, error messages with color codes, code samples that discuss ANSI rendering). Without sanitization those bytes reach the TUI render unchanged. The codebase already has diff.sanitizeCommitText for exactly this threat model (commit author/subject/body); route every parsed Comment through it before store.Add. About 5 lines. If #155 lands first, just import the now-exported diff.SanitizeCommitText. If this lands first, export the symbol here or duplicate the strip table.

2. harden file read to match #155. app/annotations_load.go:26 is naked os.Open(path) with nolint:gosec. Mirror app/main.go:resolveDescription from #155: os.Stat first, reject non-regular files via IsRegular() (otherwise opening a FIFO blocks the process before bubbletea initializes), then os.Open, then io.LimitReader(f, max+1) for an upper bound. 1 MiB cap is reasonable here since annotation files aggregate many records. Less critical for the skill-driven temp-file path since the file is skill-controlled, but matters for curl'd review files and edited history files.

should fix:

3. extract a preloader struct, fix params and standalones in one move. the wide-signature problem and the standalone-helpers problem are the same problem.

   • preloadAnnotations (8 params), lookupLineSet (8 params), resolveKnownFiles (5 params), buildLineSet. Project rule is 4+ → option struct.
   • all four are called only from each other (single caller for each helper). Project rule is "functions called only from methods MUST be methods, prefer methods over standalone helpers."
   • one refactor closes both: type preloader struct { renderer, ref, staged, untrackedFn, workDir, warnOut, lineCache }, then (p *preloader) load, (p *preloader) resolveKnownFiles, (p *preloader) lookupLineSet, (p *preloader) buildLineSet. tests collapse from "", false, nil, "", &bytes.Buffer{} repetition to a single preloader{...} literal.

   parseHeader in app/annotation/parse.go:99 is the same shape (standalone, single caller Parse). If Parse becomes Store.Load per #4, parseHeader naturally becomes a method on whatever parser type that introduces, or stays as an unexported helper local to Load.

discuss:

4. Parse → Store.Load / Store.Merge. Right now Parse returns []Annotation and preloadAnnotations re-feeds each through store.Add. A method on Store would close the round-trip loop with Store.FormatOutput symmetrically on the API surface, not just on the format level, and remove the for-loop in the loader.

5. skill instruction underdocs the body-escape rule. SKILL.md tells Claude to write the temp file "using the format documented in references/usage.md (Output Format section)". That section has the ## → ## body-escape rule (line 245), but it's tucked into a paragraph about output. When Claude generates fresh content for --annotations, it can easily emit a body line starting with ## without escaping, which the strict parser rejects (or worse, silently splits the record). Either add an explicit "escape ## in body lines" callout next to the skill instruction, or relax the parser to tolerate unescaped ## in non-header positions. A regression test covering "body line starts with unescaped ## " would also help.

6. renamed-file silent drop. If a file was renamed since --annotations was generated, records key on the old path and get orphan-dropped. Known limit of the format keyed on path. A one-line note in resolveKnownFiles doc-comment saves the next reader from chasing it as a bug.

7. --stdin --annotations is undefined. Preload runs after stdin payload setup so file-level records keyed on the synthetic stdin name probably work; line-scoped records orphan-drop. Either add to the stdin mutual-exclusion list in parseArgs or document as supported.

nits:

• app/annotations_load.go:48,57,85,99,142, five occurrences of _, _ = fmt.Fprintf(warnOut, ...). Once the option-struct refactor lands, a (p *preloader) warnf(...) helper collapses those.
• app/annotations_load.go:81-93, doc-comment says "matches ui.loadFiles" but loadFiles only folds untracked when showUntracked is on; preload always folds. Clarify the divergence.

all addressed cleanly: sanitization wired through diff.SanitizeCommitText, file-read hardened with Stat→IsRegular→LimitReader and 1 MiB cap, preloader struct holds the state, Store.Load closes the round-trip, parser tolerates unescaped ## after the first header (with regression test), --stdin --annotations rejected, doc-comments updated.

verified locally with the built binary against rejection paths (FIFO, dir, oversize, malformed, --stdin mutex), orphan-drop warning, and the unescaped ## tolerance. tests / lint / race green.

LGTM.