From fdf73243a01c4483f5854a4bbcc40d3a3c7e9ca7 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 10 Sep 2026 01:31:50 +1000 Subject: [PATCH] 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. --- ARCHITECTURE.md | 7 +++ CLAUDE.md | 12 +++-- docs/architecture/adversarial-review.md | 72 +++++++++++++++++++++++++ docs/prds/adversarial-self-review.md | 2 +- 4 files changed, 88 insertions(+), 5 deletions(-) create mode 100644 docs/architecture/adversarial-review.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 591d3f51b..53900f969 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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. diff --git a/CLAUDE.md b/CLAUDE.md index a2f6a27a9..8c579bf2e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/docs/architecture/adversarial-review.md b/docs/architecture/adversarial-review.md new file mode 100644 index 000000000..61d980f2d --- /dev/null +++ b/docs/architecture/adversarial-review.md @@ -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. diff --git a/docs/prds/adversarial-self-review.md b/docs/prds/adversarial-self-review.md index 58f36111f..ea56d983b 100644 --- a/docs/prds/adversarial-self-review.md +++ b/docs/prds/adversarial-self-review.md @@ -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`