docs: delete the superseded adversarial review document family

The adversarial self-review system was removed in 625ead95, but four pages
describing it survived: the architecture page, its design-decision PRD, and the
two superseded calibration/operator PRDs. The architecture page carried a
hand-written "removed, not shipped" banner and was kept only because live PRDs
linked to it, so every reader paid for a system the tree no longer has.

Delete all four and repoint the live referrers at the authority that replaced
them (docs/prds/pr-review-agent.md): inline-review.md's Builds-on line,
pr-review-remediation.md's isolation-contract citation, pr-review-agent.md's
supersede clause, CLAUDE.md's contributor rule, and three Go comments that cited
the deleted paths. Regenerate docs/data/generated/dev-docs.json.

History stays in git; the tree stops describing a system it does not have.
This commit is contained in:
sam committed 2026-10-03 00:01:42 +10:00
1 parent 0adc165c4c
commit aacec67c24
12 files changed
+15 -556

No files matched your search

+2 -2
View File
@@ -346,8 +346,8 @@ StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
agent _contributor_. Separately, archied runs its own PR review pipeline
(`docs/prds/pr-review-agent.md`) before it opens a PR of its own — see that
PRD's Triggers section ("archie's own PRs"). It supersedes the older
single-reviewer stage `docs/architecture/adversarial-review.md` described
(`repo.review_enabled` no longer exists). The two paths are distinct: you
single-reviewer stage and the `repo.review_enabled` setting, both since
removed. The two paths are distinct: you
run a manual pass when asked; archied runs its own before it opens a PR.
6. **Linter Guard:**
-100
View File
@@ -1,100 +0,0 @@
# Adversarial self-review
> **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system
> that no longer exists in the tree.**
>
> `d73e0748` ("remove the superseded adversarial-self-review system") deleted the
> stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`
> and `StageReview` are gone from `internal/domain/workflow`, so everything under
> "Contract" below describes types that cannot be found.
>
> The authority is `docs/prds/pr-review-agent.md`, which says so itself: it
> "supersedes the reviewer executor and blocking rule in
> `docs/architecture/adversarial-review.md`". archied now runs its PR review
> pipeline before it opens a pull request; there is no separate adversarial
> self-review pass and no `repo.review_enabled` setting.
>
> The page is kept rather than deleted because PRDs link to it
> (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,
> `docs/prds/pr-review-agent.md`). Read it as history.
>
> One section is stale in a second, older way: "Operator-triggered review" below
> describes the synchronous `review_pr` (fetch the head, snapshot it, run the
> reviewer, return findings), which `archie-core-afbk.14` replaced with a queued
> pr-review task.
Archie ran a fresh adversarial review of the diff before it opened 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. `StagePostReviewComments` then runs after `StageOpenPR` and posts
the **line-anchored** findings as inline review comments, carrying a one-click
suggestion on a confirmed finding the reviewer could state a fix for. That stage
is best-effort — a comment that fails to post is logged, never a park — because
the body section already lists every finding, and it is the record a whole-file
finding (no line to anchor to) only ever appears in.
## 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. Authorisation is identity-scoped
to the operator's configured repositories; duplicate or concurrent reviews of
the same PR are deduplicated.
+3 -43
View File
@@ -6,12 +6,6 @@
"section": "Architecture",
"body": "# Architecture\n\nArchie is a personal agent platform built around six domain boundaries:\n\n- Identity tracks users and other actors responsible for actions.\n- Agent owns persistent assistants, specialisation, and continuity.\n- Messaging owns conversations, messages, branches, and channel correlation.\n- Workflow owns reusable, versioned behaviour definitions and their executions.\n- Work Intake admits optional durable work without constraining ordinary agent\n conversation or direct capability use.\n- Plugin owns generic extension discovery and lifecycle; each capability family\n owns its typed plugin contract.\n\nThe detailed architecture and migration decisions are maintained under\n`docs/architecture/` in the repository while this generated site is being\nassembled.\n"
},
{
"url": "/dev/architecture/adversarial-review/",
"title": "Adversarial self-review",
"section": "Architecture",
"body": "# Adversarial self-review\n\n\u003e **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system\n\u003e that no longer exists in the tree.**\n\u003e\n\u003e `d73e0748` (\"remove the superseded adversarial-self-review system\") deleted the\n\u003e stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`\n\u003e and `StageReview` are gone from `internal/domain/workflow`, so everything under\n\u003e \"Contract\" below describes types that cannot be found.\n\u003e\n\u003e The authority is `docs/prds/pr-review-agent.md`, which says so itself: it\n\u003e \"supersedes the reviewer executor and blocking rule in\n\u003e `docs/architecture/adversarial-review.md`\". archied now runs its PR review\n\u003e pipeline before it opens a pull request; there is no separate adversarial\n\u003e self-review pass and no `repo.review_enabled` setting.\n\u003e\n\u003e The page is kept rather than deleted because PRDs link to it\n\u003e (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,\n\u003e `docs/prds/pr-review-agent.md`). Read it as history.\n\u003e\n\u003e One section is stale in a second, older way: \"Operator-triggered review\" below\n\u003e describes the synchronous `review_pr` (fetch the head, snapshot it, run the\n\u003e reviewer, return findings), which `archie-core-afbk.14` replaced with a queued\n\u003e pr-review task.\n\nArchie ran a fresh adversarial review of the diff before it opened a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## OperatorLine truncated
},
{
"url": "/dev/architecture/agent-system/",
"title": "Agent System",
@@ -174,12 +168,6 @@
"section": "PRDs",
"body": "# Running action playbooks\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.31`\n\n## Why this exists\n\nAn action playbook loads and type-checks but never runs: `Store.Dispatch`\nskips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,\nD1). This document defines when it runs, what each action does, and how the\n`playbook_dispatches` ledger gates it.\n\n## When a playbook runs\n\nThe daemon runs action playbooks at the point it pins a task's workflow\ndefinition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the\nworkflow playbooks use. The definition is pinned once per task, so the run\nhappens once per task.\n\n- Every action playbook whose trigger matches runs, in load order. A workflow\n playbook stops at the first match because it chooses one workflow; action\n playbooks choose nothing, so no match suppresses another.\n- A run never changes routing. The task is pinned by the workflow playbooks\n and bindings exactly as when no action playbook exists.\n- An action or playbook failure never parks or fails the task. It is logged\n at warning level with the playbook, the action and the task.\n- A task that already names a workflow (the approval requeue) is skipped, as\n it is for workflow playbooks.\n- Actions run synchronously in the pin path, bounded by the daemon's context.\n The only Module kind, `log`, returns immediately. A slow kind must bring its\n own timeout.\n\n## What one action does\n\nActions run in order against one evaluation context whose `actions` map\nstarts empty.\n\n1. Evaluate `when`. False or an evaluation error skips the action (J3). A\n skipped action records nothing and produces no result.\n2. Evaluate every `args` value. An evaluation error stops the playbook.\n3. Call `playbook.InvokeOnce` with the Module invoke as its function. The\n ledger row is written first. A duplicate row skips the invoke.\n4. An invoke error stops the playbook. The row stays, so the action is not\n retried: the ledger promises at most once, not at least once.\n5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is\n stored as `actions.\u003cid\u003e.result` when the action declares an id.\n\nThe event id in the ledger key is `DispatchInput.TaskID`, the issue's\nidempotency key (`owner/repo/number`). An action therefore runs at most once\nper issue for each playbook version. Editing a playbook changes its version\nand lets it run again for issues it already handled.\n\nA skipped duplicate has no result. A later action that reads it sees a\nmissing field: its `when` evaluates false, or its args fail and the playbook\nstops. This only happens when the same issue is pinned twice under one\nplaybook version.\n\n## Wiring\n\n- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State\n Store client in `internal/app/archied/bootstrap.go`, the same way\n `BindingDispatcher` is.\n- The daemon's `Playbooks` dependency gains the run method. The Module\n registry is passed to the playbook store at load, so the daemon needs no\n new dependency for it.\n- With no `PlaybookDispatcher` wired, action playbooks do not run, and the\n boot warning names each one. They never run without the ledger.\n- The boot warning that action playbooks do not execute is removed when the\n ledger is wired.\n\n## Verification\n\n- A matching two-action `log` playbook runs both actions in order, and the\n second reads the first's result.\n- Pinning the same task twice under one playbook version invokes each action\n once.\n- A `when` that evaluates false skips that action and the run continues.\n- An invoke error stops the playbook. The task is still pinned to the same\n workflow it would get with no action playbook.\n- A non-matching trigger runs nothing.\n- With no ledger wired, nothing runs and the warning names the playbook.\n"
},
{
"url": "/dev/prds/adversarial-self-review/",
"title": "Adversarial self-review stage -- decision",
"section": "PRDs",
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n_Conversation isolation is structural, and free._ `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n_Workspace isolation is still ours to build._ A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe _implementer's_ model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
},
{
"url": "/dev/prds/agent2agent-protocol/",
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
@@ -346,7 +334,7 @@
"url": "/dev/prds/inline-review/",
"title": "Inline review -- decision",
"section": "PRDs",
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\n2Line truncated
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review)\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\n2. Post each line-anchored finding as an inlLine truncated
},
{
"url": "/dev/prds/mcp-tool-completion/",
@@ -384,12 +372,6 @@
"section": "PRDs",
"body": "# Public news and per-version release notes\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` defines the\nsingle release stream. `CHANGELOG.md` carries every release and one `vX.Y.Z` tag\nnames each release.\n\nThe Astro website renders public news and per-version release notes from the\nartifacts generated here. Both derive from `CHANGELOG.md`, so publishing a\nrelease adds no writing.\n\n## Source of truth\n\nRelease notes come from the frozen sections in `CHANGELOG.md`:\n`tools/release.sh --prepare` writes a section, and `--tag` refuses to tag a\nversion without it. The generated artifact has one entry per release version.\n\nTags and raw commits are not the source. The changelog is the edited release\nrecord, and its `## [\u003cversion\u003e] - \u003cdate\u003e` headings provide the version and date.\n\n## Release data\n\nThe generator skips `## [Unreleased]`. Any other `## [` heading that is not\n`[version] - date` stops generation. A relative Markdown link in a changelog\nbody also stops generation because the Astro site must be able to render the\ncontent without depending on repository-relative paths.\n\n`archied` and `archie-agent` version independently. Each\n`docs/news/releases.json` entry carries the tag prefix (`archied`, `archie`),\nproduct name (`archied`, `archie-agent`), version, date, and changelog body.\n`docs/news/redirects.json` maps retired per-component news URLs to each unified\nrelease route. The Astro site must apply this table so previously published\nrelease URLs continue to resolve.\n\nBoth JSON files are committed generated artifacts. `task news` regenerates\nthem, `task news:check` detects drift, and `tools/release.sh --tag` regenerates\nand stages them with the release commit. The Astro site renders from these\nartifacts rather than re-parsing `CHANGELOG.md`.\n\n## Site ownership\n\nThe Astro website is maintained outside this repository and serves the\ndocumentation at `offloaded.dev/docs/`. This repository generates and validates\nthe news and documentation data artifacts; it does not build, preview, or\ndeploy the Astro site.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every release.\n- Hand-written news items.\n- Changes to `infra/ansible` or to the external Astro website repository.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, artifact generation,\n heading and link refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\n- `task docs:artifact:check` verifies the generated documentation data against\n its Markdown sources.\n"
},
{
"url": "/dev/prds/operator-pr-review/",
"title": "Operator-triggered PR review",
"section": "PRDs",
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an _existing_ PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\nBaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\nbaseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorisation.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
},
{
"url": "/dev/prds/orgs-and-access/",
"title": "Orgs, workspaces and access control",
@@ -418,7 +400,7 @@
"url": "/dev/prds/pr-review-agent/",
"title": "PR review agent",
"section": "PRDs",
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake\n (including its machine-written score), anatomy and diff, each able to read\n the repository. A PR that intake scores as likely machine-written adds a\n hallucination-check dimension: claims, citations and behaviour the diff\n does not actually implement.\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags. A reviewer\n that exhausts its turn cap or deadline before its terminal tool call\n records a distinct StepExecution status from a reviewer that completed\n and found nothing; synthesis and the posted review treat the two\n differently (the former is unreviewed, the latter is reviewed-clean).\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both endLine truncated
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the earlier\nreviewer executor and blocking rule.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake\n (including its machine-written score), anatomy and diff, each able to read\n the repository. A PR that intake scores as likely machine-written adds a\n hallucination-check dimension: claims, citations and behaviour the diff\n does not actually implement.\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags. A reviewer\n that exhausts its turn cap or deadline before its terminal tool call\n records a distinct StepExecution status from a reviewer that completed\n and found nothing; synthesis and the posted review treat the two\n differently (the former is unreviewed, the latter is reviewed-clean).\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) ×Line truncated
},
{
"url": "/dev/prds/pr-review-operator-response/",
@@ -430,7 +412,7 @@
"url": "/dev/prds/pr-review-remediation/",
"title": "PR review comment remediation -- decision",
"section": "PRDs",
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened _and still owns_.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyLine truncated
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the review pipeline's\nisolation contract (`docs/prds/pr-review-agent.md`, \"Isolation\") and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened _and still owns_.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyeLine truncated
},
{
"url": "/dev/prds/progressive-tool-disclosure/",
@@ -450,12 +432,6 @@
"section": "PRDs",
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
},
{
"url": "/dev/prds/review-calibration/",
"title": "Review calibration -- decision",
"section": "PRDs",
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report _nothing_\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
},
{
"url": "/dev/prds/review-settings-resource/",
"title": "Review settings resource",
@@ -582,10 +558,6 @@
"title": "Architecture",
"url": "/dev/architecture/",
"items": [
{
"title": "Adversarial self-review",
"url": "/dev/architecture/adversarial-review/"
},
{
"title": "Agent System",
"url": "/dev/architecture/agent-system/"
@@ -701,10 +673,6 @@
"title": "Running action playbooks",
"url": "/dev/prds/action-playbook-run/"
},
{
"title": "Adversarial self-review stage -- decision",
"url": "/dev/prds/adversarial-self-review/"
},
{
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
"url": "/dev/prds/agent2agent-protocol/"
@@ -841,10 +809,6 @@
"title": "Public news and per-version release notes",
"url": "/dev/prds/news-and-releases/"
},
{
"title": "Operator-triggered PR review",
"url": "/dev/prds/operator-pr-review/"
},
{
"title": "Orgs, workspaces and access control",
"url": "/dev/prds/orgs-and-access/"
@@ -885,10 +849,6 @@
"title": "One release stream, one page per version, and commit rules — decision",
"url": "/dev/prds/release-stream-and-commit-rules/"
},
{
"title": "Review calibration -- decision",
"url": "/dev/prds/review-calibration/"
},
{
"title": "Review settings resource",
"url": "/dev/prds/review-settings-resource/"
-233
View File
@@ -1,233 +0,0 @@
# Adversarial self-review stage -- decision
**Status:** Finalised
**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.
**Date:** 2026-08-22
**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`
> **Section 1 is superseded by the decision below.**
> The original execution mechanism assumed daemon-owned in-process execution
> and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both
> call sites, leaving one open question: how a fresh reviewer receives an
> isolated snapshot from inside the task-scoped worker, without a host
> executor or a nested container lifecycle. Section 1 below now answers it
> with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;
> section 3's contract shipped as `archie-core-h019.2`.
Answers the five questions in `h019.1`'s description against the actual
implement workflow, not designed from scratch: the gate pattern, the
container pool, and the workflow engine's `Outcome` mechanism already answer
most of this.
## 1. Where it runs: `agent.Subagent`, inside the task worker
The implement workflow's stage list
(`internal/domain/workflow/implement.go`) already has the right slot:
after `StageDiffCap()`, before `StageOpenPR()` -- gates
have passed, the diff is final, and nothing has told the forge about this
change yet.
**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk
`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,
synchronous `core.GenerateText` call in the same process, with its own model,
system prompt, toolset and step budget. That is what makes this feature
buildable at all after `q15y` -- the reviewer runs inside the task-scoped
`archie-agent` worker that is already executing the workflow, so there is no
host executor, no second `Pool.Acquire`, and no nested container lifecycle.
**Two isolations are needed, and Subagent only provides one of them.**
_Conversation isolation is structural, and free._ `Subagent.Run`
(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and
`Messages` never populated. The implementer's history has no code path into
the nested run; only the prompt string crosses, and only text comes back.
This is the literal form of "environmental enforcement over prompt rules":
the reviewer is not told to ignore the implementer's reasoning, because
nothing hands it any. `h019.3`'s required test asserts this as a construction
fact.
_Workspace isolation is still ours to build._ A sub-agent shares the parent's
process, working directory and credentials. So the `.git`-free snapshot from
the original decision survives unchanged and is load-bearing: export the
reviewed commit (`git archive <commit> | tar -x`) into a fresh scratch
directory beside, not inside, the task worktree, and write `diff.patch` (the
diff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`
(the originating issue's title and body, nothing else) alongside it. Stripping
`.git` is what makes commit messages, branch name and reflog -- the actual
channel a multi-commit implementer's reasoning leaks through -- structurally
unreachable rather than merely undisclosed.
`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the
snapshot**. Never the worker's own toolset: it carries the `worktreerpc`
publication grant, so a reviewer holding it could push the branch it exists to
block.
**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool
the _implementer's_ model may choose to invoke -- self-certification by the
implementer, which is the exact failure this feature exists to prevent. The
stage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s
documented footguns: the parent's two-step minimum and the recursion risk of
passing a toolset back to itself.
**Findings return through a closure, not the return value.** `Run` yields only
final text, so section 3's structured contract cannot ride the return. Because
the sub-agent is in-process, the capture tool's Go implementation appends
directly to a `[]workflow.ReviewFinding` the stage owns. This preserves the
"cannot end its turn without calling a typed tool" property, and it defeats
`Subagent`'s documented "no partial results on failure" limitation: findings
already captured survive an error return, so **the stage reads the captured
slice even when `Run` returns an error**. A reviewer that logged three defects
and then hit its step limit still yields those three.
## 2. What it's given, and what it must never be given
**Given:** the clean file-content snapshot (so the reviewer can read whole
files -- follow an import, check interface satisfaction, see a call site --
not just diff hunks, which the manual-read checklist in CLAUDE.md requires),
`diff.patch`, and `issue.md`.
**Never mounted or passed, by construction:** the implementer's
`agentexec.Result` (summary, captures, stop reason), any prior turn's tool-call
transcript, commit messages/git history/branch name (excluded by stripping
`.git`, not by instruction), daemon internal state, and any other task's data.
This is the environmental-enforcement principle applied literally: the
reviewer is never told "ignore the implementer's reasoning," because there is
no code path that hands it any.
## 3. Findings contract: `workflow.ReviewFinding`, workflow domain owns it
Not a reuse of `internal/gate.Finding` (`gate.go`), despite the similar
shape. That type belongs to the Yaegi gate contract (`.archie/gate.go`,
repo-owner-authored checks); coupling the review stage's blocking contract to
gate's evolution would violate "a domain declares the interface it needs, it
never names who implements it." `h019.2` implements, in
`internal/domain/workflow`:
```go
type ReviewFinding struct {
Level string // "error" (blocks) | "warn" (advisory)
Category string // dead-code | unchecked-error | hardcoded-value |
// interface-satisfaction | nil-risk | goroutine-leak |
// race | other -- CLAUDE.md's own checklist categories
File string
Line int
Message string
}
func ReviewBlocking(findings []ReviewFinding) bool // mirrors gate.Blocking
```
The domain owns the type and the pure blocking decision; turning the
reviewer agent's raw output into `[]ReviewFinding` is app/infrastructure code
(`h019.3`/`h019.4`), not domain code -- same direction as gate's Yaegi
evaluator producing `[]gate.Finding` for the domain to consume.
**Findings are reported through a structured capture tool**, the same
`agentexec.CaptureTool` pattern `feasibility.go`'s `decideCaptureTools`
already uses, not free text the caller regexes out of a final message. This
is the findings contract's own application of environmental enforcement:
the reviewer cannot end its turn without calling a typed tool, rather than
being asked to format its answer as JSON and trusted to comply.
## 4. Lifecycle effect of a surviving finding: `StatusParked`, not `WaitingHuman`
The epic's acceptance criteria say a surviving finding "parks the task as
`waiting_human`," which names two different states in the actual machine
(`internal/taskstate/taskstate.go`). This decides between them:
**`store.StatusParked`**, following `StageDiffCap`'s existing precedent
(`steps.go`) exactly -- a stage-computed policy stop with a `Detail`
explaining why, before PR open. `Parked`'s available actions, retry and
abandon, are the right shape here: fix the flagged code and retry, or
abandon/override if a finding is a false positive. `WaitingHuman`'s
approve/reject actions have no obvious referent -- there is no PR yet to
approve or reject.
A `Level == "error"` finding that survives sets
`tc.Outcome = Outcome{Status: store.StatusParked, Detail: <rendered findings>}`
and the stage returns `nil`; `StageOpenPR` never runs. `Level == "warn"`
findings, and the zero-findings case, leave `tc.Outcome` unset and the stage
returns `nil`, so `StageOpenPR` runs next. Attaching warn-level findings to
the task record for PR-body/dashboard display is `h019.6`'s job, not decided
here.
**A review that fails to run is fail-closed.** The
blocking rule is `Verdict == confirmed && Level == error`, so only a confirmed
finding blocks -- but that governs findings, not the reviewer's own failure. A
sub-agent that errors, is truncated, or produces no conclusion yields
`ReviewStatusNotRun`, for which `ReviewReport.Passed()` is false and
`Blocking()` is also false; the contract deliberately refuses to guess. This
stage resolves that as **park, do not open the PR**. The reasoning is that
`Repo.ReviewEnabled` is opt-in: an operator who turned the gate on wants the
gate, and a provider outage silently degrading into "PR opened unreviewed" is
the failure they were buying protection against. The cost is accepted -- a
transient model error parks a task, and `Parked`'s retry action is the
remedy. `Detail` must say the review did not run, never that it passed.
Note this is why `h019.2` models "ran and found nothing" separately from "did
not run": collapsing them to an empty slice would make an outage
indistinguishable from a clean review, and fail-closed unimplementable.
## 5. Model, effort, and whether a repo even runs this yet
**Model:** a new `"reviewer"` key in the existing `Config.Models` map (already
a generic `map[string]string`, no schema change) with the same single-level
fallback precedent `agent.go` already uses for planner->builder:
`Models["reviewer"]`, falling back to `Models["builder"]` if unset. Operators
who want a genuinely independent second opinion configure a distinct model;
nothing forces one, because CLAUDE.md's project scope is "smallest change
that works," not a mandated model-diversity policy.
**Effort/budget:** reuse the per-stage budget override `AgentStage` already
supports (`agent.go`), not a new config surface -- a repo wanting a
cheaper or more thorough reviewer sets `MaxSteps` the same way
the plan stage already can. Map that budget onto `Subagent.MaxSteps` and
`Subagent.MaxTokens` deliberately: **`MaxTokens` is a per-call ceiling, not a
cumulative budget**, so an N-step reviewer can emit up to N x `MaxTokens`.
Setting it as though it bounded the whole run is a costing error, not a
safety one. `Subagent.MaxSteps` defaults to 10 when unset.
**Observability:** the nested run is synchronous and non-streaming -- nothing
is emitted between the parent's call and its result, so a long review reads as
a stalled stage. Emit task events around the call so the dashboard shows the
reviewer working rather than a gap.
**Opt-in, not automatic:** `h019.5` (calibration -- confirm findings
adversarially before they surface) is a separate, lower-priority bead than
`h019.4` (wiring). Shipping the stage unconditionally the moment `h019.4`
lands would gate every existing repo's PR flow on an uncalibrated reviewer
before calibration exists, which is exactly the "reviewer that cries wolf"
risk the epic names as the thing that kills this feature. `h019.4` adds
`Repo.ReviewEnabled bool` (default `false`) to `internal/config`; an operator
opts a repo in once they trust it, the same shape as any other per-repo gate
setting.
## Packages this touches
- `internal/domain/workflow` (`h019.2`, `h019.4`): `ReviewFinding`,
`ReviewReport`, `ReviewBlocking` -- shipped -- and a `ReviewStage` inserted
between `StageDiffCap` and `StageOpenPR` in `implement.go`. The domain owns
the contract and the pure blocking decision, and declares the reviewer
interface it needs; it never names `agent.Subagent`.
- `internal/worktree` or a sibling package (`h019.3`): the clean-snapshot
export (`git archive`, no `.git`) building the reviewer's isolated
workspace. Still required -- `Subagent` isolates conversation, not
filesystem.
- `internal/app/agentworker` (`h019.3`): constructs the `agent.Subagent` from
the worker's own resolved provider (`agentexec.NewRuntime`), with a
read-only toolset rooted at the snapshot and the findings capture tool. This
is app-layer wiring: the domain gets an implementation of its reviewer
interface, not an SDK type.
- `internal/config` (`h019.4`): `Models["reviewer"]` (no type change) and
`Repo.ReviewEnabled bool`.
- `internal/store`/`internal/taskstate`: unchanged; reuses `StatusParked`.
- Surfacing findings on the PR body and dashboard is `h019.6`, out of scope
here.
## What this does not decide
The exact review checklist prompt content, how many findings can survive
before `MaxSteps` is exhausted, and the adversarial-confirmation mechanism
that keeps a finding from surfacing on a single reviewer's say-so are
`h019.5`. The PR-body/dashboard rendering of findings is `h019.6`. This
document decides isolation, inputs, the findings contract's owner and shape,
the lifecycle effect, and model/effort/opt-in configuration only.
+1 -1
View File
@@ -2,7 +2,7 @@
**Status:** Finalised
**Beads issue:** `archie-core-q9au`
**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`
**Builds on:** `archie-core-h019` (adversarial self-review)
## Problem
-87
View File
@@ -1,87 +0,0 @@
# Operator-triggered PR review
**Status:** Draft
**Beads issue:** `archie-core-h019.8`
> Superseded by `docs/prds/pr-review-agent.md`.
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. **Authorisation.** 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.
+2 -4
View File
@@ -1,10 +1,8 @@
# PR review agent
**Status:** Approved
**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer
executor and blocking rule in `docs/architecture/adversarial-review.md`, and
the designs in `docs/prds/operator-pr-review.md` and
`docs/prds/review-calibration.md`.
**Authority:** `docs/architecture/agent-system.md`; supersedes the earlier
reviewer executor and blocking rule.
**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent
call is a StepExecution), `docs/prds/external-agent-harness.md` (any agent
step may run on a harness), `docs/prds/inline-review.md` (posting),
+2 -2
View File
@@ -5,8 +5,8 @@
**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)
Answers: how archie reacts to review comments on a PR it opened, from a human
or from another review bot, and remediates them. Built on two settled decisions — the adversarial review
epic's isolation contract (`docs/prds/adversarial-self-review.md`) and the
or from another review bot, and remediates them. Built on two settled decisions — the review pipeline's
isolation contract (`docs/prds/pr-review-agent.md`, "Isolation") and the
event-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the
webhook intake security contract (`docs/prds/webhook-intake-security.md`).
Nothing here re-decides those; it names the one concrete reaction each one's
-78
View File
@@ -1,78 +0,0 @@
# Review calibration -- decision
**Status:** Draft
**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)
> Superseded by `docs/prds/pr-review-agent.md`.
Decides the half of calibration `docs/prds/adversarial-self-review.md` left
open: "the adversarial-confirmation mechanism that keeps a finding from
surfacing on a single reviewer's say-so."
## The problem, precisely
The shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)
already makes only a **confirmed** error-level finding block
(`Blocking() == Verdict == confirmed && Level == error`), and a zero-finding
review is already distinguishable from one that never ran (`ReviewStatus`).
What is missing is the other half: a reviewer can report _nothing_
and say only "I found nothing" in free text. The operator cannot tell "I
checked the five things that matter and they are clean" from "I did not look."
That is the failure the epic names -- a findings surface that consumes attention
without earning trust.
## Decisions
### 1. "Checked and cleared" becomes structured, not prose
`ReviewReport` gains `Checked []ReviewCheck`:
```go
type ReviewCheck struct {
Property string // what was verified clean, e.g. "nil-safety of Foo callers"
Evidence string // how it was verified, e.g. "read all 4 callers; each nil-checks"
}
```
`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:
a check without evidence is an assertion, and the whole point is to separate a
verified property from an unexamined one. A zero-finding review is credible
only when it lists what it checked.
### 2. Report checks through a typed tool, like findings
The reviewer calls a new capture tool `record_checked` (mirroring
`record_finding`) once per property it verified clean. The same environmental
argument as findings applies: the reviewer cannot end its turn having silently
skipped the checklist. `ReviewReport.Summary` stays as the human overview.
### 3. Style nits are out of contract
A finding must describe wrong behaviour or a crash. Style, formatting, naming,
and preference nits are explicitly out of contract -- they are the padding that
trains the operator to skim. Stated in the reviewer prompt and in the
`ReviewFinding` type's own documentation. Not machine-enforced: deciding "is
this a style nit" from free text is unreliable, and a wrong rejection is worse
than a tolerated one. The category enum already has no style bucket; the rule
closes the gap that would otherwise let one hide under `other`.
### 4. Surfacing
The PR-body findings section lists the cleared properties alongside findings,
so "ran and found nothing" arrives with its evidence. (Park reasons keep
rendering only blocking findings -- what a human needs to act on, not the full
checklist.)
## What this does not decide
- Adding a second, independent reviewer pass. The verdict distinction plus the
recorded checks is the confirmation mechanism; a second model pass is a
separate, heavier decision and nothing in `h019.5` requires it.
- How many findings can survive before `MaxSteps` is exhausted (a budget
question, already satisfied by the per-stage budget).
## Packages this touches
- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.
- `internal/app/agentworker` -- `record_checked` tool, prompt rules.
- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.
+1 -2
View File
@@ -225,8 +225,7 @@ func Implement() Workflow {
// not full price.
//
// This used to also append the adversarial self-review's findings section
// (docs/prds/adversarial-self-review.md, now superseded by
// docs/prds/pr-review-agent.md per that PRD's own header). archie-core-afbk.7
// (now superseded by docs/prds/pr-review-agent.md). archie-core-afbk.7
// removed the old review stage; hooking the new pr-review pipeline in as
// this workflow's "archie's own PRs" trigger is tracked separately (see the
// bead's continuation comment) rather than guessed at here, since it needs
+2 -2
View File
@@ -91,8 +91,8 @@ type Trees interface {
ChangedLines(ctx context.Context, dir, base string) (int, error)
// Snapshot exports HEAD's tracked files into destDir with no .git
// directory -- no commit history, branch name, or reflog. Used to
// build the adversarial reviewer's isolated workspace (see
// docs/prds/adversarial-self-review.md).
// build the reviewer's isolated workspace (see the isolation contract
// in docs/prds/pr-review-agent.md).
Snapshot(ctx context.Context, dir, destDir string) error
}
+2 -2
View File
@@ -866,8 +866,8 @@ func fileChange(fp fdiff.FilePatch) task.FileChange {
// Snapshot exports HEAD's tracked files into a fresh, empty destDir with no
// .git directory: file contents only, no commit history, branch name, or
// reflog. Used to build the adversarial reviewer's isolated workspace
// (docs/prds/adversarial-self-review.md section 1) -- stripping .git is
// reflog. Used to build the reviewer's isolated workspace (the isolation
// contract in docs/prds/pr-review-agent.md) -- stripping .git is
// what makes the implementer's reasoning (commit messages, branch name,
// history) structurally unreachable rather than merely undisclosed.
func (m *Manager) Snapshot(ctx context.Context, dir, destDir string) error {