review: pr-af's code review, built into codeaf as its third program

[ZeroPoint95]

Renamed from /pr to /review on the owner's call: the chat command, the shell verb, via, the manual page, the guide, the report files and the endings. internal/praf keeps its name, after the project it was copied from, as internal/secaf does.

Retargeted to dev after #1781 merged. dev (with #1781 squash-merged as 741f1b9ee) is merged into this branch with a plain merge, so the diff against dev is only this program. Squash-merge it.

What changed

pr-af, AgentField's pull-request reviewer, is built into codeaf as its third carried program: /review in the chat, codeaf review at a shell, via: "review" from a proposal. It follows the same approach as sec in #1781. pr-af's Go port is copied in once, at pr-af's tag codeaf-absorb (b70667e), as internal/praf and frozen there. It runs on the shared agent loop (internal/agentsession), and every model call goes through the run's model API, priced and held to the run's ceiling. Its reviewers read the pull request's checkout with the four read-only tools. It lands text: an account in the conversation, and review-report.md / .json in the task's record folder. The chat then offers to post the review or to hand the blocking findings to senior-dev, and starts neither until the person says yes.

• Scope: /review <pull request> [focus] takes a URL, owner/repo#N or #N. A bare /review reviews the current branch's open pull request, found with gh pr view or, failing that, the upstream remote and the GitHub API. Focus words become pr-af's review hints.
• The chat hears it by its command and its work, not the word "review" (Delegate.Asked, new and optional). "review" is a word people use for much else, so the bare word names nothing ("review this function" stays in the conversation). /review always asks for it, and so does a message that points at a pull request (PR, pull request, its link, owner/repo#N) and asks for it to be looked over ("review PR 123", "take a look at my PR"), which keeps the feel PR had when the program was called pr. The turn-back for a proposal without via then says which work was heard. senior-dev and sec set no Asked and are heard exactly as before.
• Posting is its own run, on a per-run yes. A review posts nothing. /review post <review-report.json> posts the saved review on the commit that was reviewed, and the chat proposes it only after the person agrees. GitHub refuses a request for changes on the author's own pull request, so that case is posted as a comment and the ending says so.
• GitHub auth: GH_TOKEN, then GITHUB_TOKEN, then gh auth token; with none, public repositories are read anonymously. git gets the token through an extraheader, never in a URL. The checkout lives in a temporary folder of its own that is removed when the run ends, and checkouts left by killed runs are swept after a day.
• Every limit is review's own (internal/praf/limits.go): each agent's turns and time (10–30 turns, 5–15 minutes), plus concurrency, retries and the session policy. Since sec: sec-af's security audit, built into codeaf as its second program #1781 the shared loop has no defaults, and a praf test proves the config review hands it is complete. --max-turns, --session-wall, --sessions, --model and --light override for one run. The sessions are told their work is "a code review".
• Ceilings: $5 and two hours (Delegate.Unattended). A review cut by its time ceiling still reports and says where it was cut, and it keeps three minutes back to write the review.
• One failed session fails one reviewer, not the review. The account says how many agent sessions and single calls failed, and a review where every session failed ends as a failure.
• Changes to pr-af's own code on the way:
  • The JSON context files the reviewers read are written one value to a line. codeaf cuts a line at 2,000 characters, so pr-af's single-line JSON was unreadable past that, and reviewers spent their turns re-reading it.
  • The review is a single pass.
  • The HITL loop, GitHub App auth, the SDK harness and every PR_AF_* variable are gone.
• Manual: a new review page (internal/manual/chat/review.md, its probes keyed review), plus updates to commands, delegates, tasks, models-and-cost and running-from-the-terminal, with nine probes.
• Budgets: SIZE-BUDGET rises by exactly what linking internal/praf measured (+1,032,784 bytes on darwin/amd64 with furrow staged), and the prefix waivers by review's guide (+203 bytes in both arms, over sec's as re-measured on dev baa2d7f0f); both are in PERF.md.

Design notes: docs/design/pr-review/ABSORB.md (what was copied, what changed, and why), and docs/design/pr-review/PR-AF-GO-README.md (pr-af's own README, kept for reference).

How it was checked

• BASE=origin/dev make pr-ready passed on this branch's tree as merged with dev 741f1b9ee (16e937b82): the light gate, the law tests, the touched packages and the whole internal/session suite (8 shards), every selected test on its first run. On this Mac, scripts/one-suite_test.sh (needs flock) and cmd/codeaf's TestRunSurfaceWiresTheDeferredLaunchCheckAndInstallerThroughRealInit fail the same on a clean dev; neither is this branch's.
• GitHub CI runs on this PR now that its base is dev.
• An independent review from another session (build on darwin and windows, vet, laws, and the touched packages) found four issues, all fixed on this branch: a bare /review post started a review; the manual promised a progress count the page never drew; --sessions 0 ended with agentsession's sentence instead of review's; and one manual quote did not match its message.
• A final-pass review from the same session, on the tip before dev was merged in, found nothing blocking: builds on darwin and windows, vet, laws, size, and every touched package.
• make test-laws passed.
• GOOS=windows go build ./... passes; GOARCH=amd64 make size on 16e937b82: 72,234,096 bytes, under the 72,395,784 budget.
• internal/praf:
  • a stub-model end-to-end review (checkout, sessions, pipeline, account, both report files, nothing posted);
  • brief reading (URL, owner/repo#N, #N, bare, focus, post <path>);
  • posting, including the own-pull-request fallback;
  • the account's wording, the time-ceiling cut and the all-sessions-failed ending;
  • the per-agent limits and overrides;
  • that the sessions' config passes agentsession.New;
  • what asks for a review (asksForReview): a pull request pointed at and asked to be looked over, never either alone.
• internal/session: TestAProgramNamedByAnEverydayWordIsHeardByItsCommandAndItsWork, covering the bare word, the command, the work, the name after an ask word, the work's turn-back, and senior-dev unchanged beside it.
• Live, at a shell (as codeaf pr, before the rename) on Make GH_TOKEN optional in the Go node manifest pr-af#73, on deepseek/deepseek-v4-flash-0731. The whole review ran in 55m14s: 575 calls, $0.34, 6 findings (0 blocking, 3 important, 3 suggestions), and nothing was posted. Each finding had a location and a fix. Earlier live runs found the bugs fixed in this branch:
  • sessions were told they were part of a security audit;
  • one reply with no choices ended the whole review;
  • endings repeated their prefix;
  • the single-line JSON context files above, which drove every session to its turn cap.

Not yet checked: a review started from the chat, watching the turn it wakes; and /review post against a real pull request, which is covered only by tests. The per-agent limits are a choice of depth, not a measurement, and a small pull request still takes close to an hour, so tuning them is the next step.

Checklist

• A change entry: docs/changes/unreleased/1784-review.md
• The manual knows about it: review.md is new, the commands/delegates/tasks/models-and-cost/terminal pages are updated, and there are probes
• No new line in .github/known-red.txt
• Only my own paths are staged, no git add -A

Not in this PR: pr-af's codeaf-absorb tag and the commit it points at exist only in a local pr-af checkout and are not pushed.

🤖 Generated with Claude Code