Handbook
Code review worker
Dual-wiki: operator · system.
Updated
Executive capsule
code_review_worker is the only identity allowed to merge agent pull requests. After the operator replies confirm on a READY FOR TEST thread, a separate Fleet job (code_review_task) clones the PR head and base in a fresh agentic_dev container, re-runs verify[] on the pushed SHA, runs deterministic checks, optionally asks an LLM for advisory findings, emits forge.review_result.v1, and merges only when the rules below allow it.
Who this is for
Operators who confirm agent PRs from Element, forgeadmins who release HELD critical reviews, and maintainers of the Fleet rail.
Problem
The implementing job (agentic_dev_task) and the reviewing job never share a container, a clone, or a credential. The reviewer has no Cursor key — only the node's scoped git token. A PASS from the agent's own verify run is evidence, not a decision; the reviewer's independent run is what counts.
How it works
Deterministic checks:
| Check id | fail (blocks) |
critical (HITL) |
|---|---|---|
head_pinned |
branch tip moved since READY FOR TEST |
— |
path_guard |
change outside allow_paths or inside deny_paths |
— |
secret_scan |
key material / credential patterns in changed files | — |
task_trailer |
missing Forge-Task: <task_id> trailer on the agent commit |
— |
independent_verify |
any verify command non-zero on the reviewer's checkout | — |
lockfile_diff |
— | package-lock.json, poetry.lock, Cargo.lock, go.sum, … changed |
protected_paths |
— | .github/**, deploy/**, Dockerfiles, compose, unit files, env/secret-like files |
conflict_probe |
— | git merge-tree against current origin/<base_ref> reports conflicts |
change_size |
— | more than 1500 changed lines |
Verdict: any fail → fail; else any critical → hold; else pass. The LLM step (use_llm: true) adds llm_findings[] and never changes critical.
Merge rules:
verdict: passandcritical: false→PUT /repos/<repo>/pulls/<n>/mergewithmerge_method=squash,sha=<head_sha>, title<summary> (Forge-Task <id>), trailersForge-Task,Reviewed-By; then delete the branch.verdict: hold→HELDin the thread with the critical check ids and a fresh!approve <task_id>:merge <digest>line; the digest bindsrepo, pr_number, head_sha, critical_check_ids. A forgeadmin receipt makes the broker re-submit the review withmerge_override; the reviewer merges the same head SHA or refuses (head_pinned).verdict: fail→FAILED; amerge_overrideis refused onfail.- GitHub required checks block the API merge →
merge_errorandrequired_checks_blocking[]are surfaced inHELD; the worker never uses admin merge.
How it fits the ecosystem
| Artifact | Where |
|---|---|
| Workcell | forge-workcells/src/forge_workcells/workcells/code_review_worker.py (forge-workcells run --workcell code_review_worker --request …) |
| Container pipeline | forge-fleet/deploy/agentic-dev/run_review.py |
| Fleet route | POST /v1/admin/code-review-task, GET /v1/admin/agentic-dev-task/{id} |
| Result schema | schemas/review_result.v1.schema.json |
| Element events | repo-task-element-protocol |
| Program | Engineering Autonomy |
Evidence
forge-fleet/fleet_server/test_agentic_dev_job.py::ReviewTests and forge-workcells/tests/test_code_review_worker.py cover: path violation, secret pattern, head moved, stale conflict, lockfile change, protected path, oversized change, verify failing on the reviewer side although the agent reported success, merge blocked by required checks, and the refusal of an override on fail. No live merge of an agent PR has been recorded yet (R12 canary pending).
Trust boundary
Humans decide confirm, reject, and the release of a hold. The worker decides nothing outside the table above, never widens allow paths, never force-pushes, never uses admin merge, and never sees the Cursor credential.
How to use
Operators do not invoke the worker directly; confirm in the task thread does. Maintainers can run the same job from a launch pack: forge-workcells run --workcell code_review_worker --request <launch.json> --out-dir <dir> (pack must carry task_id, repo, base_ref, branch, pr_number, head_sha; a credential field is rejected).