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:
1 parent
851c46d8ed
commit
fdf73243a0
4 files changed
+88
-5
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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,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`
|
||||
|
||||
|
||||
Reference in new issue
Block a user