Files
archie/docs/prds/operator-pr-review.md
T
sam ca433865b0 fix(archied): build the Gateway's worktree manager so it serves review_pr
boot.prReviewer returns nil without a worktree manager, and a nil reviewer
omits review_pr from every channel's tool set. RunGateway never called
buildTreesAndIdentities, so the Gateway resolved a nil reviewer and no
channel could review a PR.

Extract the manager's construction into boot.buildWorktreeManager, called
by buildTreesAndIdentities (daemon, unchanged field-for-field) and by
startGatewayRuntime before setupGatewayChat. The Gateway does not call
buildTreesAndIdentities: that also registers daemon identity runners the
Gateway must not own, and PR review only needs a clone of the PR head,
which worktree.Manager.CheckoutPR does from the forge.

Pin the ordering by source position in composition_order_test.go, alongside
the memory-engine ordering the same function already carries, and pin both
compositions behaviourally in worktree_manager_composition_test.go: the
Gateway's step must yield a reviewer that advertises review_pr, and the
daemon must still build its root manager plus one runner per identity with
a distinct WorkDir.

Correct docs/prds/operator-pr-review.md, which still asserted the daemon
supplies ChatPRReviewer and holds the review in-flight set.
2026-09-22 03:44:45 +10:00

86 lines
4.2 KiB
Markdown

# Operator-triggered PR review
**Status:** Draft
**Beads issue:** `archie-core-h019.8`
This PRD reuses the adversarial-self-review contract
(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /
`workflow.ReviewReport` types from `internal/domain/workflow`. It decides
only what is new: how an operator asks for a review of an *existing* PR, and
how that PR's content reaches the reviewer.
## Problem
The adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`
and reviews the task's own worktree HEAD. There is no way to review a PR that
already exists: one archie opened, a human opened, or one whose findings the
operator wants re-checked after a push.
## Shape
One channel-neutral command — `review_pr` — accepts a repository and PR number
and returns the structured `ReviewReport`. The Web UI chat and Telegram invoke
the same command; neither duplicates review behaviour. The reviewer model is
`models.reviewer` (falling back to `models.builder`), already the rule the
workflow stage uses, so an operator configures it independently of
planner/builder.
## Decisions
1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a
forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,
BaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,
implemented by GitHub and Gitea; the noop forge does not implement it, so
the composition root type-asserts and refuses review with "forge does not support PR
review". Adding to the fat `Forge` interface would churn every test fake for
a capability the noop forge cannot honestly provide.
2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,
baseRef)` clones the repository fully and checks out `origin/<headRef>`.
`Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:
`Diff` resolves `origin/<baseRef>` via the existing `resolveBase`, and
`Snapshot` strips `.git` exactly as the workflow stage does. The head must
already be pushed to the same repository — archie's own PRs always are; a
cross-repo or deleted head is refused with that reason, not half-reviewed.
3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`
builds the same `subagentReviewer` the stage uses, from daemon-level config
rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`
gate (the operator asked explicitly) and the task-run scaffolding.
4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the
channel's identity at construction — the model never names an identity,
matching `task_spawn`/`task_action`. The Gateway process serves it: it
composes the worktree manager it needs to materialise the PR head, and the
composition root supplies `ChatPRReviewer`, a narrow gateway interface
whose adapter maps `workflow.ReviewReport` into a gateway-owned result
shape (gateway states what it needs, the composition root adapts — the
`ChatTaskActor` pattern).
5. **Authorization.** Identity-scoped repository allow-list, the
`task_spawn` rule: a chat identity may only review a repo in its
`TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard
operator who may review any configured repository.
6. **Determinism.** One review per (owner, repo, number) at a time: the
Gateway holds an in-flight set; a concurrent request for the same PR returns
"review already in progress" rather than launching a second reviewer and
racing on the snapshot.
## Files
- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,
`PullRequestReader`, `GetPullRequest`.
- `internal/worktree/worktree.go` — `CheckoutPR`.
- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.
- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.
- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.
- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.
- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.
## Not in scope
- Surfacing findings on the PR body or the dashboard (h019.6).
- Reviewer model per-invocation override: configuration via `models.reviewer`
is the selection surface; a per-call override is a later knob.