…ate parse path

The single --compare=old:new flag forced custom colon-splitting and could
not represent file paths containing colons (e.g. ISO timestamps). Replace
it with paired --compare-old / --compare-new flags that mirror the
--include / --exclude shape, drop the strings.Cut parser entirely, and
fold resolveComparePaths into validateCompareFlag so the flag has a
single parse + validate site. Absolute paths now stash on opts at parse
time and run() consumes them directly.

Conflict checks still run before stat checks so a misuse error is not
masked by a missing-file error. --description and --description-file
remain orthogonal — compare mode keeps the info-popup prose channel.

Updates README, site/docs.html, and the diff-review skill usage docs in
the same commit so released docs do not ship stale.

…ileLines

Insert -- between flag args and path args in the git diff --no-index
invocation so a path that begins with a dash cannot be parsed as a flag,
even if a future caller bypasses filepath.Abs.

countFileLines now hangs off CompareReader and reads r.oldPath directly
— the standalone form took a path parameter only because it was written
before the constructor settled. The nolint:gosec on os.Open drops with
it (the rule only flagged the parameter form).

…ks, error paths

CompareConflicts now uses real t.TempDir() files so a future stat-first
reordering would not silently green these subtests — the assertion
under test is the conflict, not the file existence.

New CompareReader cases:
- paths_with_colons_in_name pins the OG bug killed by the two-flag form
- binary_files exercises the "Binary files ... differ" stdout path
- no_trailing_newline matrix (4 subcases) covers EOF-newline corners
- git_error_surfaces_stderr asserts diffError preserves git's stderr
- symlinks (both-symlink + mixed) confirms Stat-follows-symlink contract
- count_file_lines_large_file_streaming asserts a >5MB read stays under
  a HeapAlloc cap of file_size/4 (32KB buffer) so a future refactor that
  slurps the file would fail loudly

show only what changed between plan revisions instead of re-rendering the
full plan after every rewrite. plan content carries its own diff history
via a first-line html-comment marker pointing at the previous snapshot:

  <!-- previous revision: /tmp/plan-rev-AAA.md -->

on each ExitPlanMode the hook strips the marker, writes the new revision
to a snapshot, and either opens revdiff in --compare against the marker's
target (when present on disk) or falls back to --only mode. on annotations
the hook denies and tells the agent to put the new snapshot path as the
first line of the next plan; on no annotations it cleans up.

launch-plan-review.sh now dispatches on argc: 1 → --only=<plan>,
2 → --compare=<old>:<new>, with PLAN_FILE pointing at the new revision
for the overlay title.

in rolling plan-revision review the user wants to read the new state with
the round's edits highlighted, not pore over the full +/- diff against the
previous revision. --collapsed hides removed lines while preserving inline
highlights on what changed, which matches how human reviewers naturally
read prose revisions.

scoped to compare mode only (2-arg invocation). --only mode shows the file
as context-only with no removed lines, so --collapsed would be a no-op.

Mirror the flag-shape change from compare-flag's refactor commit. The
launcher now builds REVDIFF_ARGS as two pre-shell-quoted tokens in
compare mode (--compare-old=<old> --compare-new=<new>) instead of the
old colon-joined --compare=<old>:<new> form. sq() moved to the top of
the file so the args block can use it; the duplicate definition lower
down is gone.

…olling-review contract

The previous-iteration snapshot was unlinked unconditionally after the
launcher subprocess returned, regardless of whether the launcher actually
ran revdiff against the user. On any launcher non-zero exit (no overlay
terminal available, AppleScript split error, cmux surface lookup failure,
etc.) the user never saw the diff but old_snap was wiped, dangling the
next round's marker and silently dropping the chain to --only.

Gate the unlink on result.returncode == 0 and surface launcher failure
to the user via the hook's ask response instead of pretending the plan
was reviewed clean.

README adds a "Rolling reviews" section covering the marker contract,
the snapshot lifecycle (now correct on the failure path), and an explicit
acknowledgment of the agent-discipline failure mode (forgotten marker →
fallback to --only, self-heals on the next round). Override section
notes the two-args / one-arg dispatch and the failure semantics so
override authors know not to obscure the launcher's exit code.

… docs

Security
- planning hook restricts the agent-supplied "previous revision" marker
  to a trusted snapshot under \$TMPDIR with the plan-rev-* prefix. without
  this guard the agent could point --compare-old at any readable file
  (~/.ssh/id_rsa, /etc/passwd, …) and surface its contents through the
  diff overlay and subsequent annotations.
- marker regex now tolerates leading whitespace before <!-- so common
  LLM drift (blank line, indented fence) does not silently collapse
  the rolling-review chain to --only mode.

Hook resilience
- subprocess.run is now wrapped in try/except for TimeoutExpired and OSError;
  both branches preserve old_snap and clean up the orphan new_snap so
  the rolling chain survives a hung or failed-to-start launcher.

Test rigor
- drop three tautological "compare mode" rows in renderer_setup_test.go
  (TestCommitsApplicable, TestReloadApplicable) that passed for reasons
  unrelated to compare logic; rename the TestCompactApplicable case to
  honestly reflect what it pins (CompareReader != FileReader).
- TestCompareReader_FileDiff_GitErrorSurfacesStderr no longer accepts
  the bare "exit" fallback substring; requires an actual stderr token.
- TestCompareReader_FileDiff_BinaryFiles now asserts the exact
  one-placeholder contract instead of vacuously iterating an empty slice.
- TestCompareReader_FileDiff_Symlinks asserts non-zero add+remove counts
  matching git's actual symlink-object semantics (not the original
  NotEmpty-only check).

Cleanup
- collapse the eight repeated conflict checks in validateCompareFlag
  into a slice-driven loop; reads better, mirrors --include/--exclude
  shape on the data side.

Docs
- CLAUDE.md: replace 3 stale --compare=old:new references with --compare-old/--compare-new.
- CHANGELOG.md: new "Unreleased" section covering --compare-old/--compare-new and the rolling planning-hook review.
- site/index.html: extend All-files-mode card to mention --compare-old/--compare-new.

…on, etc.

Security
- close TOCTOU on the planning hook's marker path. trusted_snapshot now
  returns the canonical resolved Path (or None) and the caller uses it as
  old_snap; previously the hook validated the resolved target but handed
  the unresolved candidate (potentially a symlink) to git/revdiff,
  letting the symlink be re-pointed between validation and use.

Hook resilience
- propagate revdiff's exit code through every async launcher branch
  (zellij, kitty, wezterm, cmux, ghostty, iTerm2, emacs vterm) by
  writing the rc to the sentinel atomically (printf + mv -f) and exiting
  the outer launcher with that rc instead of an unconditional exit 0.
  without this, revdiff failures inside an overlay terminal silently
  surfaced as "plan reviewed, no annotations" — bypassing the new
  returncode-gating logic and the rolling-review chain. tmux already
  propagates exit code natively via display-popup -E.

Quality
- countFileLines now treats non-EOF read errors as "unknown" (returns 0)
  rather than returning a partial count; a partial count would mislabel
  the trailing-divider "⋯ N lines ⋯" footer.

Docs
- add --annotations to the compare-mode mutual-exclusion list in
  README.md, CLAUDE.md, site/docs.html, and the diff-review skill
  usage.md so the documented contract matches the validator.

mv -f atomically renames SENTINEL.tmp to SENTINEL on the success path, so
the temp file does not normally outlive the script — but if the launcher
or overlay terminal is killed mid-write, .tmp leaks in TMPDIR. add it to
each async branch's trap list so the cleanup is robust under signals.

both branches inline the inner script via sh -c instead of writing a
LAUNCH_SCRIPT, so the existing async-branch traps did not cover them.
add a per-branch trap so SENTINEL and SENTINEL.tmp clean up on signal.

Adds the --compare-old/--compare-new inline example and the full
"Two-File Diff" section that landed in the claude-plugin reference
when --compare flags shipped. The codex skills are a content-mirror
of the claude-plugin skills (copies, not symlinks); usage.md drifted
because earlier compare-flag updates only touched the claude-plugin
side.