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:

  1. verdict: pass and critical: false → PUT /repos/<repo>/pulls/<n>/merge with merge_method=squash, sha=<head_sha>, title <summary> (Forge-Task <id>), trailers Forge-Task, Reviewed-By; then delete the branch.
  2. verdict: hold → HELD in the thread with the critical check ids and a fresh !approve <task_id>:merge <digest> line; the digest binds repo, pr_number, head_sha, critical_check_ids. A forgeadmin receipt makes the broker re-submit the review with merge_override; the reviewer merges the same head SHA or refuses (head_pinned).
  3. verdict: fail → FAILED; a merge_override is refused on fail.
  4. GitHub required checks block the API merge → merge_error and required_checks_blocking[] are surfaced in HELD; 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).