Review notes docs

AGENTS.md

@@ -33,4 +33,5 @@ reactive programming (AFRP). Haskell, built with cabal.
 
 ## Reviewing
 
-See [[REVIEW.md]]
+Reviews are recorded in git notes under `refs/notes/review`; read the latest
+note before reviewing. See [[REVIEW.md]].

REVIEW.md

@@ -15,3 +15,28 @@
 - If there's comments for a function, they must only be about the contract and use instructions
 - If there's comments for implementation, they should only be for exceptional cases, cases where the reader would question why something is implemented like that
 - Comment style should follow minimalistic writing style
+
+## Recording reviews
+
+Reviews are stored as git notes under `refs/notes/review`, one note per
+reviewed commit. The note header carries `branch`, `round`, `verdict`
+(`approve` or `request-changes`), `previous` (sha of the last reviewed tip),
+and a findings list with stable IDs (`F1`, `F2`, ...) whose `status` is
+`open`, `resolved`, or `wontfix`. The body is free markdown prose.
+
+Protocol:
+
+1. Fetch prior results:
+   `git fetch origin "refs/notes/review:refs/notes/review"`
+2. Read the latest verdict and open findings for the branch:
+   `scripts/review-note latest <branch>`
+3. Review the branch tip per this document.
+4. Write the note (header + markdown) to a file and attach it to the tip:
+   `scripts/review-note write <file>`. Use `--force` only to replace a note
+   on the same commit deliberately.
+5. Publish: `scripts/review-note push` (plain `git push` does not push
+   notes).
+
+On a re-review after fixes: new tip, new note, `round`+1, `previous` set to
+the last reviewed sha, open findings carried forward by ID, resolved ones
+marked `resolved`.