feat(review): surface reviewed-file edits deterministically — Tier A (nudge + version)

[adnaan]

The problem

Every review-loop failure in the driving use case (muster's plan reviews) was the same shape: "the agent didn't run a command." A comment left QUEUED (no done); no "working" pill (no status). Nagging the LLM harder via the skill is non-deterministic — it can always forget.

The fix: observe ground truth, not the agent's narration

prereview now watches the reviewed files. The moment the agent edits one, the reviewer sees it — with no command from the agent. Every piece already existed; only the trigger was missing.

Trigger — reviewedFilesFingerprint (mtime+size over versionScope), a sibling of the existing sidecar fingerprint, joins the existing 750ms WatchLLMStatus poll. A reviewed-file change is now first-class alongside the agent's sidecar signals.

A1 — the nudge. On a change the watcher bumps a per-tab reviewedGen; LLMStatusChanged nudges the existing PendingRefresh affordance when a tab lags — the same non-intrusive, frozen-view refresh working→done already uses (scroll/drafts survive; refresh rebuilds + re-anchors). No new UI, no mid-read view mutation.

A2 — the version + diff. The same change checkpoints a version, so the reviewer gets the diff of what changed even with no done message. It's ordered after the llm-done checkpoint and suppressed while working, so an agent that does use status keeps its richer changelog (the file-edit checkpoint becomes a SHA no-op); a bare edit gets its own changelog-less version.

Skill update (ships with the behavior)

SKILL.md reframes status working/done from a required progress signal to optional enrichment: the reviewer already sees the edit + its version via the file-watch, so skipping status no longer hides anything — it just adds a message and a changelog.

Tests

• Unit: fingerprint fires iff a scoped file changes; the handler nudges on a gen bump with no agent status; the watcher checkpoints a file-edit version, dedups a no-op touch by SHA, and defers to working→done so the agent's changelog is never lost.
• Browser e2e (deterministic): a raw os.WriteFile edit — zero prereview commands — surfaces the nudge and checkpoints a file-edit version; asserts no llm-status.json was written.
• Existing internal/review + e2e suites stay green.

Notes

• Fingerprint cost: a stat per scoped file per tick. Single-file/NoGit (how muster reviews a plan) is one stat; git-mode runs git name-status per tick — fine for a local tool, flagged in a comment as the sole thing to revisit for a huge repo.
• This is Tier A. Tier B — a first-class "this comment's region was edited → likely addressed" state that reduces reliance on prereview done — is planned separately.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FG91be8B49Jq7sNMJskM8c