docs(architecture): promote the shipped review stage, reconcile CLAUDE.md

Closes archie-core-h019.7. Three parts:

- Promote docs/prds/adversarial-self-review.md into
  docs/architecture/adversarial-review.md, describing the stage as shipped
  (subagent executor, .git-free snapshot, ReviewReport contract, fail-closed
  park, models.reviewer budget, operator-triggered review_pr) and mark the PRD
  as promoted.
- Add the review stage to ARCHITECTURE.md's task lifecycle.
- Reconcile CLAUDE.md's Development Protocol: distinguish the contributor's
  opt-in manual pass from archied's automatic pre-PR review.

Note: the h019.7 text said the review diverts to waiting_human, but the
shipped stage (h019.1/h019.4) parks to StatusParked, not waiting_human. This
change documents the shipped behaviour (parked), not the stale wording.
This commit is contained in:
sam committed 2026-09-10 01:31:50 +10:00
1 parent 851c46d8ed
commit fdf73243a0
4 files changed
+88 -5

No files matched your search

+7
View File
@@ -65,6 +65,13 @@ recorded on the task as `park_reason` (cleared on requeue) and surfaced by the
dashboard and `/api/tasks`. Retries are an explicit operator action capped by
`max_retries`, not a label a human removes.
**Adversarial review:** the implement workflow runs a fresh adversarial review
after the deterministic gates and before `pr_open` (see
`docs/architecture/adversarial-review.md`). A surviving blocking finding — or a
review that failed to run — parks the task with the findings as its
`park_reason`; otherwise the PR opens with a findings section on its body.
Opt-in per repo via `repo.review_enabled`.
**PR reconciliation:** the daemon polls open PRs, checks GitHub state
(`merged`/`closed`), transitions the task, and cleans up worktrees.
+8 -4
View File
@@ -262,10 +262,14 @@ structures found in legacy packages.
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
`task fmt` (`gofumpt` + `go fix`) verbatim. Never revert or fight canonical
linter/formatter diffs.
5. **No standing adversarial-review pass:** Do not spawn a separate
fresh-context reviewer pass on every change as a matter of course. Red-green
TDD plus `task check` is the gate. Adversarial review is opt-in per
request, not a default step in this loop -- ask before running one.
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
opt-in per request — ask before running one. This is the rule for a human or
agent *contributor*. Separately, archied runs the same adversarial review
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
you run one when asked; archied runs one before it opens a PR.
6. **Linter Guard:**
- When using `errorlint` fixes, ensure boolean predicates (e.g.
+72
View File
@@ -0,0 +1,72 @@
# Adversarial self-review
Archie runs a fresh adversarial review of the diff before it opens a pull
request, so a PR arrives with a findings record rather than an unreviewed
claim. The reviewer provably cannot see the implementer's context: it reviews a
`.git`-free snapshot of the committed tree, not the worktree, the commit
history, or the implementer's transcript.
Promoted from `docs/prds/adversarial-self-review.md` (the design decision;
`archie-core-h019`). Describes the stage as shipped.
## Contract (`internal/domain/workflow`)
The workflow domain owns the contract and the blocking decision; it never names
the executor.
- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the
workflow stage consumes.
- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free
export of the reviewed commit), `Diff` (base...head), `IssueText` (the
originating issue title/body), and `MaxSteps`.
- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing
rule is `Blocking() == (Verdict == confirmed && Level == error)`: only a
confirmed error-level finding blocks; a plausible finding never blocks
however severe it claims to be.
`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero
findings) structurally, so "ran and found nothing" is not the same as "never
ran" — collapsing them would make an outage indistinguishable from a clean
review.
## Execution (`internal/app/agentworker`)
The executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in
the same worker process, with its own model, system prompt, toolset and step
budget.
- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt
string, never the implementer's message history.
- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is
read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the
worker's own toolset, which carries the `worktreerpc` publication grant.
- **Findings return through a typed capture tool** (`record_finding`), validated
on the way in, so the reviewer reports through the contract rather than free
text the caller regexes.
- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion
yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent
"PR opened unreviewed".
## Lifecycle effect
`StageReview` runs in the implement workflow after the deterministic gates and
before `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A
surviving blocking finding — or a review that failed to run — parks the task
(`StatusParked`, not `waiting_human`) with the findings rendered into the park
reason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding
case leave the outcome unset, so the PR opens with a findings section rendered
onto its body.
## Model and budget
The reviewer model is `models.reviewer`, falling back to `models.builder`.
Effort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`
(default 10).
## Operator-triggered review
The same reviewer runs against an *existing* PR via the channel-neutral
`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated
reviewer, and return the structured findings. Authorization is identity-scoped
to the operator's configured repositories; duplicate or concurrent reviews of
the same PR are deduplicated.
+1 -1
View File
@@ -1,6 +1,6 @@
# Adversarial self-review stage -- decision
**Status:** Active
**Status:** Promoted to `docs/architecture/adversarial-review.md` (h019.7) — that document describes the stage as shipped and is authoritative. This PRD remains as the design-decision record.
**Date:** 2026-08-22, section 1 replaced 2026-08-25
**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`