From dd3abd2c95f168666beb57abe34f96efd8124068 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sat, 3 Oct 2026 00:01:42 +1000 Subject: [PATCH] docs: delete the superseded adversarial review document family The adversarial self-review system was removed in 7299b923, 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. --- CLAUDE.md | 4 +- docs/architecture/adversarial-review.md | 100 ---------- docs/data/generated/dev-docs.json | 46 +---- docs/prds/adversarial-self-review.md | 233 ------------------------ docs/prds/inline-review.md | 2 +- docs/prds/operator-pr-review.md | 87 --------- docs/prds/pr-review-agent.md | 6 +- docs/prds/pr-review-remediation.md | 4 +- docs/prds/review-calibration.md | 78 -------- internal/domain/workflow/implement.go | 3 +- internal/domain/workflow/workflow.go | 4 +- internal/worktree/worktree.go | 4 +- 12 files changed, 15 insertions(+), 556 deletions(-) delete mode 100644 docs/architecture/adversarial-review.md delete mode 100644 docs/prds/adversarial-self-review.md delete mode 100644 docs/prds/operator-pr-review.md delete mode 100644 docs/prds/review-calibration.md diff --git a/CLAUDE.md b/CLAUDE.md index be5ba9870..5fbfd930b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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:** diff --git a/docs/architecture/adversarial-review.md b/docs/architecture/adversarial-review.md deleted file mode 100644 index ccedbf596..000000000 --- a/docs/architecture/adversarial-review.md +++ /dev/null @@ -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. diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 80e245b35..0bd472043 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -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## Operator-triggered review\n\nThe same reviewer runs against an _existing_ PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorisation is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n" - }, { "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 requires),\n`diff.patch`, and `issue.md`.\n\n**Never mounted or passed, by construction:** the implementer's\n`agentexec.Result` (summary, captures, stop reason), any prior turn's tool-call\ntranscript, commit messages/git history/branch name (excluded by stripping\n`.git`, not by instruction), daemon internal state, and any other task's data.\nThis is the environmental-enforcement principle applied literally: the\nreviewer is never told \"ignore the implementer's reasoning,\" because there is\nno code path that hands it any.\n\n## 3. Findings contract: `workflow.ReviewFinding`, workflow domain owns it\n\nNot a reuse of `internal/gate.Finding` (`gate.go`), despite the similar\nshape. That type belongs to the Yaegi gate contract (`.archie/gate.go`,\nrepo-owner-authored checks); coupling the review stage's blocking contract to\ngate's evolution would violate \"a domain declares the interface it needs, it\nnever names who implements it.\" `h019.2` implements, in\n`internal/domain/workflow`:\n\n```go\ntype ReviewFinding struct {\n Level string // \"error\" (blocks) | \"warn\" (advisory)\n Category string // dead-code | unchecked-error | hardcoded-value |\n // interface-satisfaction | nil-risk | goroutine-leak |\n // race | other -- CLAUDE.md's own checklist categories\n File string\n Line int\n Message string\n}\n\nfunc ReviewBlocking(findings []ReviewFinding) bool // mirrors gate.Blocking\n```\n\nThe domain owns the type and the pure blocking decision; turning the\nreviewer agent's raw output into `[]ReviewFinding` is app/infrastructure code\n(`h019.3`/`h019.4`), not domain code -- same direction as gate's Yaegi\nevaluator producing `[]gate.Finding` for the domain to consume.\n\n**Findings are reported through a structured capture tool**, the same\n`agentexec.CaptureTool` pattern `feasibility.go`'s `decideCaptureTools`\nalready uses, not free text the caller regexes out of a final message. This\nis the findings contract's own application of environmental enforcement:\nthe reviewer cannot end its turn without calling a typed tool, rather than\nbeing asked to format its answer as JSON and trusted to comply.\n\n## 4. Lifecycle effect of a surviving finding: `StatusParked`, not `WaitingHuman`\n\nThe epic's acceptance criteria say a surviving finding \"parks the task as\n`waiting_human`,\" which names two different states in the actual machine\n(`internal/taskstate/taskstate.go`). This decides between them:\n**`store.StatusParked`**, following `StageDiffCap`'s existing precedent\n(`steps.go`) exactly -- a stage-computed policy stop with a `Detail`\nexplaining why, before PR open. `Parked`'s available actions, retry and\nabandon, are the right shape here: fix the flagged code and retry, or\nabandon/override if a finding is a false positive. `WaitingHuman`'s\napprove/reject actions have no obvious referent -- there is no PR yet to\napprove or reject.\n\nA `Level == \"error\"` finding that survives sets\n`tc.Outcome = Outcome{Status: store.StatusParked, Detail: \u003crendered findings\u003e}`\nand the stage returns `nil`; `StageOpenPR` never runs. `Level == \"warn\"`\nfindings, and the zero-findings case, leave `tc.Outcome` unset and the stage\nreturns `nil`, so `StageOpenPR` runs next. Attaching warn-level findings to\nthe task record for PR-body/dashboard display is `h019.6`'s job, not decided\nhere.\n\n**A review that fails to run is fail-closed.** The\nblocking rule is `Verdict == confirmed \u0026\u0026 Level == error`, so only a confirmed\nfinding blocks -- but that governs findings, not the reviewer's own failure. A\nsub-agent that errors, is truncated, or produces no conclusion yields\n`ReviewStatusNotRun`, for which `ReviewReport.Passed()` is false and\n`Blocking()` is also false; the contract deliberately refuses to guess. This\nstage resolves that as **park, do not open the PR**. The reasoning is that\n`Repo.ReviewEnabled` is opt-in: an operator who turned the gate on wants the\ngate, and a provider outage silently degrading into \"PR opened unreviewed\" is\nthe failure they were buying protection against. The cost is accepted -- a\ntransient model error parks a task, and `Parked`'s retry action is the\nremedy. `Detail` must say the review did not run, never that it passed.\n\nNote this is why `h019.2` models \"ran and found nothing\" separately from \"did\nnot run\": collapsing them to an empty slice would make an outage\nindistinguishable from a clean review, and fail-closed unimplementable.\n\n## 5. Model, effort, and whether a repo even runs this yet\n\n**Model:** a new `\"reviewer\"` key in the existing `Config.Models` map (already\na generic `map[string]string`, no schema change) with the same single-level\nfallback precedent `agent.go` already uses for planner-\u003ebuilder:\n`Models[\"reviewer\"]`, falling back to `Models[\"builder\"]` if unset. Operators\nwho want a genuinely independent second opinion configure a distinct model;\nnothing forces one, because CLAUDE.md's project scope is \"smallest change\nthat works,\" not a mandated model-diversity policy.\n\n**Effort/budget:** reuse the per-stage budget override `AgentStage` already\nsupports (`agent.go`), not a new config surface -- a repo wanting a\ncheaper or more thorough reviewer sets `MaxSteps` the same way\nthe plan stage already can. Map that budget onto `Subagent.MaxSteps` and\n`Subagent.MaxTokens` deliberately: **`MaxTokens` is a per-call ceiling, not a\ncumulative budget**, so an N-step reviewer can emit up to N x `MaxTokens`.\nSetting it as though it bounded the whole run is a costing error, not a\nsafety one. `Subagent.MaxSteps` defaults to 10 when unset.\n\n**Observability:** the nested run is synchronous and non-streaming -- nothing\nis emitted between the parent's call and its result, so a long review reads as\na stalled stage. Emit task events around the call so the dashboard shows the\nreviewer working rather than a gap.\n\n**Opt-in, not automatic:** `h019.5` (calibration -- confirm findings\nadversarially before they surface) is a separate, lower-priority bead than\n`h019.4` (wiring). Shipping the stage unconditionally the moment `h019.4`\nlands would gate every existing repo's PR flow on an uncalibrated reviewer\nbefore calibration exists, which is exactly the \"reviewer that cries wolf\"\nrisk the epic names as the thing that kills this feature. `h019.4` adds\n`Repo.ReviewEnabled bool` (default `false`) to `internal/config`; an operator\nopts a repo in once they trust it, the same shape as any other per-repo gate\nsetting.\n\n## Packages this touches\n\n- `internal/domain/workflow` (`h019.2`, `h019.4`): `ReviewFinding`,\n `ReviewReport`, `ReviewBlocking` -- shipped -- and a `ReviewStage` inserted\n between `StageDiffCap` and `StageOpenPR` in `implement.go`. The domain owns\n the contract and the pure blocking decision, and declares the reviewer\n interface it needs; it never names `agent.Subagent`.\n- `internal/worktree` or a sibling package (`h019.3`): the clean-snapshot\n export (`git archive`, no `.git`) building the reviewer's isolated\n workspace. Still required -- `Subagent` isolates conversation, not\n filesystem.\n- `internal/app/agentworker` (`h019.3`): constructs the `agent.Subagent` from\n the worker's own resolved provider (`agentexec.NewRuntime`), with a\n read-only toolset rooted at the snapshot and the findings capture tool. This\n is app-layer wiring: the domain gets an implementation of its reviewer\n interface, not an SDK type.\n- `internal/config` (`h019.4`): `Models[\"reviewer\"]` (no type change) and\n `Repo.ReviewEnabled bool`.\n- `internal/store`/`internal/taskstate`: unchanged; reuses `StatusParked`.\n- Surfacing findings on the PR body and dashboard is `h019.6`, out of scope\n here.\n\n## What this does not decide\n\nThe exact review checklist prompt content, how many findings can survive\nbefore `MaxSteps` is exhausted, and the adversarial-confirmation mechanism\nthat keeps a finding from surfacing on a single reviewer's say-so are\n`h019.5`. The PR-body/dashboard rendering of findings is `h019.6`. This\ndocument decides isolation, inputs, the findings contract's owner and shape,\nthe lifecycle effect, and model/effort/opt-in configuration only.\n" - }, { "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).\n2. Post each line-anchored finding as an inline comment, with a suggestion block\n when `Verdict == confirmed \u0026\u0026 Suggestion != \"\"`. The head SHA the comments are\n anchored to is resolved by the forge implementation, not here; there is no\n `PullRequestReader` on this side of the agent boundary. The stage passes\n `tc.ReviewedHeadSHA` alongside them.\n\nNothing in the run pushes between `StageReview` and this stage, so at that\nmoment the pull request's head _is_ the revision the review read. That was an\nassumption, and a collaborator can falsify it by pushing to the branch between\nthe review and the posting. A line number is not validated against a revision:\nboth forges anchor it to whatever now occupies that line, so a stale anchor\nmislabels rather than failing. The revision is therefore carried with the\ncomments and the set is refused when the head has moved off it\n(`reviewHeadDrift`) — a refusal lands in the failure path below, leaving the PR\nbody as the record. With no measured revision (a `Trees` that cannot report one)\nthe comments post unverified rather than being dropped.\n\n**Failures log and never fail the task.** The PR is already open; a comment that\nfailed to post must not park a task whose actual work succeeded, and the body\nsection already carries every finding. This mirrors `OpenPR`'s existing\nbest-effort `LinkBranch` call.\n\n### 5. No separate opt-in flag\n\nInline comments are posted whenever a review ran and produced line-anchored\nfindings — the same `repo.review_enabled` gate already covers it. A second flag\nis a knob to add if it proves noisy in practice; adding it speculatively is the\nsmallest-change principle's opposite.\n\n## Out of scope\n\n- Commenting on the blocking/parked case (no PR exists).\n- Resolving/dismissing threads, or reacting to replies (that is the\n `archie-core-8li9` remediation direction).\n- Multi-line suggestions.\n- Gitea's \"suggested change\" rendering: Gitea has no one-click apply, so the\n `Suggestion` there is informational text in the comment body.\n\n## Packages this touches\n\n- `internal/domain/workflow` — `ReviewFinding.Suggestion`; `StagePostReviewComments`;\n the `Forger` subset gains the writer (or `TaskContext` gains the writer seam).\n- `internal/forge` — `ReviewCommentWriter`, GitHub + Gitea implementations.\n- `internal/app/agentworker` — the reviewer prompt asks for a `Suggestion` on\n confirmed, mechanically-fixable findings; `record_finding` accepts it.\n" + "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 inline comment, with a suggestion block\n when `Verdict == confirmed \u0026\u0026 Suggestion != \"\"`. The head SHA the comments are\n anchored to is resolved by the forge implementation, not here; there is no\n `PullRequestReader` on this side of the agent boundary. The stage passes\n `tc.ReviewedHeadSHA` alongside them.\n\nNothing in the run pushes between `StageReview` and this stage, so at that\nmoment the pull request's head _is_ the revision the review read. That was an\nassumption, and a collaborator can falsify it by pushing to the branch between\nthe review and the posting. A line number is not validated against a revision:\nboth forges anchor it to whatever now occupies that line, so a stale anchor\nmislabels rather than failing. The revision is therefore carried with the\ncomments and the set is refused when the head has moved off it\n(`reviewHeadDrift`) — a refusal lands in the failure path below, leaving the PR\nbody as the record. With no measured revision (a `Trees` that cannot report one)\nthe comments post unverified rather than being dropped.\n\n**Failures log and never fail the task.** The PR is already open; a comment that\nfailed to post must not park a task whose actual work succeeded, and the body\nsection already carries every finding. This mirrors `OpenPR`'s existing\nbest-effort `LinkBranch` call.\n\n### 5. No separate opt-in flag\n\nInline comments are posted whenever a review ran and produced line-anchored\nfindings — the same `repo.review_enabled` gate already covers it. A second flag\nis a knob to add if it proves noisy in practice; adding it speculatively is the\nsmallest-change principle's opposite.\n\n## Out of scope\n\n- Commenting on the blocking/parked case (no PR exists).\n- Resolving/dismissing threads, or reacting to replies (that is the\n `archie-core-8li9` remediation direction).\n- Multi-line suggestions.\n- Gitea's \"suggested change\" rendering: Gitea has no one-click apply, so the\n `Suggestion` there is informational text in the comment body.\n\n## Packages this touches\n\n- `internal/domain/workflow` — `ReviewFinding.Suggestion`; `StagePostReviewComments`;\n the `Forger` subset gains the writer (or `TaskContext` gains the writer seam).\n- `internal/forge` — `ReviewCommentWriter`, GitHub + Gitea implementations.\n- `internal/app/agentworker` — the reviewer prompt asks for a `Suggestion` on\n confirmed, mechanically-fixable findings; `record_finding` accepts it.\n" }, { "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 ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, running in a\n bounded pool at most 8 at a time (matching phase 4), keeping the original\n on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait. The gate\nbelongs to the standalone `pr-review` workflow only; archie's own-PR stage list\ndrops it, because a park there would end an implement run before its PR\nexists (`docs/prds/pr-review-operator-response.md`,\n\"The gate is not reachable from archie's own PRs\").\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Organisations\n\nThe reviewer is a workflow, so `docs/prds/orgs-and-access.md` applies to it\nunchanged: it runs as the workflow's identity under the run credential, reads\nonly repositories that identity may read, and posts through the forge RPC\nunder that credential. A watched repository belongs to a workspace, and its\nPR events start reviews through that workspace's bindings. Findings,\nStepExecutions and the posted review carry the run's org and workspace.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" + "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) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n near-duplicates through a small classification call that keeps both\n when unsure;\n - map lines to the diff's coordinates, sort by score, cap at 25 inline\n comments.\n8. **Merge gate.** One classification call per finding decides blocking or\n advisory: blocking only for broken builds, security, data loss, contract\n breaks and regressions. A failed call means advisory.\n9. **Output.** One call per comment tightens its wording, running in a\n bounded pool at most 8 at a time (matching phase 4), keeping the original\n on failure. The review is posted as one forge review with inline\n comments. Any blocking finding requests changes; otherwise the review is a\n comment. Archie never posts an approval.\n\n## Precision dial\n\nWith `review.precision_gate = true`, a post-worthiness pass runs after phase 4\nand before the verification layer. It keeps every concrete, evidenced defect\nand drops nitpicks, style and unverifiable claims, keeping a finding when\nunsure. It trades recall for precision and cuts verification cost by\nfiltering early.\n\n## Operator approval\n\nWith `review.approve_before_post = true`, synthesis ends in\n`waiting_human`. The operator chooses which findings to post, rejects the\nreview, or asks for a re-review with instructions. A re-review reruns phases\n3 to 8 with the instructions added to the lens and reviewer prompts, at most\n2 times. A review with no findings posts nothing and does not wait. The gate\nbelongs to the standalone `pr-review` workflow only; archie's own-PR stage list\ndrops it, because a park there would end an implement run before its PR\nexists (`docs/prds/pr-review-operator-response.md`,\n\"The gate is not reachable from archie's own PRs\").\n\n## Isolation\n\nEvery agent in the pipeline reads a `.git`-free snapshot of the PR head, with\nread-only tools rooted at it, and never the implementer's worktree or\ntranscript. No pipeline agent holds a forge credential; posting is code.\n\n## Budget\n\nA run has a cost cap and a wall-clock cap, split into per-phase shares. A\nphase whose share is spent is skipped and recorded on its StepExecution. The\nposted review names every skipped phase, so an exhausted run never reads as a\nclean one. A run whose review stage fails posts nothing and\nfails.\n\n## Triggers\n\n- **Watched repositories:** a PR opened or updated on a repository with\n `review.enabled` starts a run. An update cancels the in-flight run for the\n same PR.\n- **Operator:** a PR URL from the dashboard or chat starts a run on any\n repository the identity can read.\n- **Archie's own PRs:** the implement workflow runs the pipeline before\n opening its PR. A blocking finding the adversary did not challenge parks\n the task with the findings. A pipeline that fails parks the task. Advisory\n findings are posted after the PR opens.\n\n## Organisations\n\nThe reviewer is a workflow, so `docs/prds/orgs-and-access.md` applies to it\nunchanged: it runs as the workflow's identity under the run credential, reads\nonly repositories that identity may read, and posts through the forge RPC\nunder that credential. A watched repository belongs to a workspace, and its\nPR events start reviews through that workspace's bindings. Findings,\nStepExecutions and the posted review carry the run's org and workspace.\n\n## Models\n\nEach agent phase names a model role. Lens, reviewer, verification,\nadversary, compound and consistency agents use the review role. Intake,\ncoverage, dedup, merge gate and polish calls use the classification role.\nEither role may run on the built-in runner or a harness.\n\n## Out of scope\n\n- SARIF and standalone report formats. The findings are StepExecution outputs\n and the forge review.\n- Reviewing a diff without a forge PR.\n- Self-consistency reruns.\n\n## Plan\n\n1. Deterministic core: diff parsing, clustering, blast radius, evidence\n extraction, scoring, dedup, line mapping, review event. Table-driven tests.\n2. The benchmark harness (Verification), run against the deterministic core\n with fixture findings.\n3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,\n output, with the execution tree recording each call.\n4. Verification layer, coverage loop and consistency verification.\n5. Merge gate, polish, budget shares and skipped-phase reporting.\n6. Benchmark acceptance run.\n7. Triggers: operator, watched repositories, archie's own PRs replacing the\n single-reviewer stage.\n8. Precision dial and operator approval.\n\n## Verification\n\n- **Benchmark acceptance.** On the 38 runnable PRs of the Martian\n Code-Review-Bench offline set, one blind run per PR at `deep` with the\n review and classification roles on GLM-5.2, and an independent judge\n (`anthropic/claude-sonnet-4.6`) matching posted comments to golden\n comments: golden micro-recall is at least 0.70. Golden-only precision is\n reported alongside it. The run is reproducible from a script in the\n repository.\n- Scoring, thresholds, dedup and line mapping give identical output for\n identical findings.\n- A run whose phase share is exhausted posts a review naming the skipped\n phase.\n- An update to a PR under review cancels the running review and its child\n steps.\n- No pipeline agent can write to the snapshot, and none can reach a forge\n credential.\n- Archie's own PR with an unchallenged blocking finding is parked, not\n opened.\n- Archie never submits an approving review.\n" }, { "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 keyed on `(owner, repo, pr_number)`, a matching\n`StateStoreService` RPC (a Go interface method on a store facade without one\nis forbidden, `CLAUDE.md`), and an index on those three columns. It is the\nauthorisation boundary, so it is sequenced as its own step below rather than\ncarried along with the envelope.\n\n**Identity is derived from the resolved task, never carried in the reaction.**\nThe task row already stores `identity` (`internal/infrastructure/postgres/store.go`), and it is\nthe resolved task's identity that selects the forge client, worktree manager,\nrepo config and `bot_user` for the remediation run and the `ReplyToReview`\nreply, through the existing `forgeFor`/`treesFor`/`repoFor` helpers. That is\nwhat decision 5's \"the identity that owns the task\" means, and it is the only\nplace identity enters this path.\n\nIdentity is deliberately **not** added to the envelope, the idempotency key or\nthe index:\n\n- A PR number is unique within an `owner/repo`, and the tasks table is keyed\n `UNIQUE(owner, repo, issue_number)` with no host or identity column, so\n archie already treats `owner/repo` as globally unique across identities. A\n `(owner, repo, pr_number)` lookup cannot return a task other than the one\n that owns that PR; there is no cross-identity resolution to guard against.\n- The webhook producer has no identity to carry: webhook intake refuses to\n start when `[[identities]]` is configured (`setupForgeWebhook`,\n `internal/app/archied/bootstrap.go`).\n- Keying on a field only one of the two producers can populate is precisely\n the delivery-source-specific key `CLAUDE.md` forbids, and it would break the\n webhook/poll dedup the key exists for. An index column that never appears in\n the `WHERE` clause is dead weight.\n\n### 4. Remediation: a `remediate` workflow on the existing branch\n\nA new workflow that runs when a reaction resolves to an archie-owned PR. It is\nnot a new branch/PR — it reuses the task's prepared worktree, refreshes it\nonto the PR branch (the `worktree.Manager.refresh` idempotency), and:\n\n1. Runs a builder agent whose mission is the review's actionable comments\n (each with body, path, line): \"Address these review comments with the\n smallest change; run the gate.\" One agent run per review, per decision 5. The toolset is the normal builder toolset — edit + gate + (never\n git; the orchestrator commits/pushes) — not the reviewer's read-only set.\n2. Runs the repo gate (`[[repos.gate]]`) and `diff_cap_lines` — the same\n enforcement as any other work (webhook-intake-security point 4; no\n relaxation for review-triggered edits).\n3. Commits and pushes to the **same** PR branch.\n4. Replies to the review/comment via `ReplyToReview`, summarising what\n changed.\n\nThe comment is injected through the task record (e.g. `Task.Notes` or a\ndedicated review field), not through a prompt-only path, so the reaction is\nrecoverable and auditable.\n\n### 5. Routing and lifecycle\n\nA **review** is the unit of remediation, never an individual comment.\n\n- `requested_changes` review → one remediation run addressing every actionable\n comment in that review.\n- `commented` review with actionable inline comments → one remediation run\n addressing every actionable comment in that review.\n- `approved` review → no remediation. Record the review state on the task;\n do **not** auto-merge — merging stays an operator action (the dashboard/chat\n `/approve` precedent). Auto-merge is a separate decision if ever wanted.\n\nOne run per review, strictly. A review carrying eight inline comments arrives\nas one `pull_request_review` event plus eight `pull_request_review_comment`\nevents; remediating each separately means eight builder runs, eight gate runs\nand eight pushes to answer one review. The comment events are collected\nagainst their parent `ReviewID` and remediated together. A standalone comment\nwith no parent review is its own unit of one.\n\nRemediation runs for a single task are **serialised**, whatever\n`[[repos]].allow_concurrent` says. Two runs against one PR branch would race\non the shared worktree and on the push; `allow_concurrent` is about unrelated\ntasks in a repo, not about one task reacting to itself.\n\n#### Whose comments count\n\nOnly archie's **own** comments are excluded, matched on the forge identity\nthat owns the task (`bot_user`, or the identity's `bot_user` under\n`[[identities]]`), so its `ReplyToReview` replies do not retrigger it.\n\nEvery other author is actionable, including other bots. The external review\nbot on this repository is the main source of findings on an archie-opened PR,\nand discarding comments because their author is a bot would discard the review\nthis feature exists to act on. There is no \"is a bot\" test anywhere in this\npath.\n\n(The original draft justified a broader exclusion by citing a `RepliesAfter`\n`exclude` precedent. No such mechanism exists in the tree; the citation is\nwithdrawn.)\n\n#### Bounding the exchange\n\nBecause bot comments are actionable, the exchange can run away without a human\never touching it: archie pushes a remediation, the review bot re-reviews the\nnew commit, comments, archie remediates again. Nothing in the reaction path\nterminates that on its own.\n\nA task therefore carries a remediation round count, bounded by the repo's\nexisting `max_retries`. On the cap, archie stops remediating, posts one\ncomment saying it has stopped and why, and parks the task for an operator.\nThis is a hard stop, not a backoff: the failure it guards against is\nunbounded spend, so slowing it down does not address it.\n\n### 6. Security posture\n\nThe webhook reaction is not a public no-code binding, so it does not pass\nthrough the `draft → pending_approval → armed` gate (webhook-intake-security\npoint 2) — but every other constraint holds: HMAC (already in the receiver),\nper-source rate limiting (add when the receiver gains a second event family),\nand blast radius bounded by the existing gate/sandbox/worktree enforcement,\n**plus** the new archie-owned-task check (decision 3), which is the actual\nauthorisation boundary: a review event only ever causes work against a PR\narchie itself opened and still owns.\n\nAccepting other bots' comments (decision 5) does not widen that boundary: an\nauthor is never a reason to act, only the owned-task check is. It does widen\nthe _spend_ surface, which the round cap bounds.\n\n### 7. Sequencing\n\n1. **The reaction stream.** `ARCHIE_REACTIONS`, under the fan-out\n `jetstream.LimitsPolicy` the parent decision requires\n (`event-sources-and-reactions.md` §2). `Config.Retention` is\n parameterised for exactly this (`archie-core-7d5u.2`), but no reaction\n stream exists and `ARCHIE_TASKS` carries `archie.task.\u003e` only, so every\n publish to `archie.reaction.*` fails against no matching\n stream. This step is first because nothing after it can be exercised\n without it.\n2. `PullRequestReviewReader` + GitHub/Gitea implementations + `ReplyToReview`.\n _(Landed.)_\n3. `ReviewCommentEnvelope` + the kinded idempotency key.\n4. **The owned-task guard**: `(owner, repo, pr_number)` lookup, its\n `StateStoreService` RPC, its index, and the drop-with-counter path for an\n unmatched, merged, closed or archived PR. Nothing may consume a reaction\n before this exists.\n5. `remediate` workflow: worktree refresh, one run per review, builder, gate,\n push, reply, round cap.\n6. Webhook receiver extension (`pull_request_review` / `_comment` events).\n7. Poll backstop with the persisted `sinceID` cursor.\n8. Tests + `task check`.\n\nSteps 6 and 7 are the producers and come last on purpose. Building a producer\nbefore its consumer and its authorisation guard yields a path that publishes\ninto nothing, and becomes an unguarded intake the moment a stream appears.\n\n## Out of scope\n\n- Auto-merge on approval (separate decision).\n- Reacting to comments on PRs archie did not open.\n- The calibration epic's confirm-before-surfacing (h019.5) — orthogonal.\n" + "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 keyed on `(owner, repo, pr_number)`, a matching\n`StateStoreService` RPC (a Go interface method on a store facade without one\nis forbidden, `CLAUDE.md`), and an index on those three columns. It is the\nauthorisation boundary, so it is sequenced as its own step below rather than\ncarried along with the envelope.\n\n**Identity is derived from the resolved task, never carried in the reaction.**\nThe task row already stores `identity` (`internal/infrastructure/postgres/store.go`), and it is\nthe resolved task's identity that selects the forge client, worktree manager,\nrepo config and `bot_user` for the remediation run and the `ReplyToReview`\nreply, through the existing `forgeFor`/`treesFor`/`repoFor` helpers. That is\nwhat decision 5's \"the identity that owns the task\" means, and it is the only\nplace identity enters this path.\n\nIdentity is deliberately **not** added to the envelope, the idempotency key or\nthe index:\n\n- A PR number is unique within an `owner/repo`, and the tasks table is keyed\n `UNIQUE(owner, repo, issue_number)` with no host or identity column, so\n archie already treats `owner/repo` as globally unique across identities. A\n `(owner, repo, pr_number)` lookup cannot return a task other than the one\n that owns that PR; there is no cross-identity resolution to guard against.\n- The webhook producer has no identity to carry: webhook intake refuses to\n start when `[[identities]]` is configured (`setupForgeWebhook`,\n `internal/app/archied/bootstrap.go`).\n- Keying on a field only one of the two producers can populate is precisely\n the delivery-source-specific key `CLAUDE.md` forbids, and it would break the\n webhook/poll dedup the key exists for. An index column that never appears in\n the `WHERE` clause is dead weight.\n\n### 4. Remediation: a `remediate` workflow on the existing branch\n\nA new workflow that runs when a reaction resolves to an archie-owned PR. It is\nnot a new branch/PR — it reuses the task's prepared worktree, refreshes it\nonto the PR branch (the `worktree.Manager.refresh` idempotency), and:\n\n1. Runs a builder agent whose mission is the review's actionable comments\n (each with body, path, line): \"Address these review comments with the\n smallest change; run the gate.\" One agent run per review, per decision 5. The toolset is the normal builder toolset — edit + gate + (never\n git; the orchestrator commits/pushes) — not the reviewer's read-only set.\n2. Runs the repo gate (`[[repos.gate]]`) and `diff_cap_lines` — the same\n enforcement as any other work (webhook-intake-security point 4; no\n relaxation for review-triggered edits).\n3. Commits and pushes to the **same** PR branch.\n4. Replies to the review/comment via `ReplyToReview`, summarising what\n changed.\n\nThe comment is injected through the task record (e.g. `Task.Notes` or a\ndedicated review field), not through a prompt-only path, so the reaction is\nrecoverable and auditable.\n\n### 5. Routing and lifecycle\n\nA **review** is the unit of remediation, never an individual comment.\n\n- `requested_changes` review → one remediation run addressing every actionable\n comment in that review.\n- `commented` review with actionable inline comments → one remediation run\n addressing every actionable comment in that review.\n- `approved` review → no remediation. Record the review state on the task;\n do **not** auto-merge — merging stays an operator action (the dashboard/chat\n `/approve` precedent). Auto-merge is a separate decision if ever wanted.\n\nOne run per review, strictly. A review carrying eight inline comments arrives\nas one `pull_request_review` event plus eight `pull_request_review_comment`\nevents; remediating each separately means eight builder runs, eight gate runs\nand eight pushes to answer one review. The comment events are collected\nagainst their parent `ReviewID` and remediated together. A standalone comment\nwith no parent review is its own unit of one.\n\nRemediation runs for a single task are **serialised**, whatever\n`[[repos]].allow_concurrent` says. Two runs against one PR branch would race\non the shared worktree and on the push; `allow_concurrent` is about unrelated\ntasks in a repo, not about one task reacting to itself.\n\n#### Whose comments count\n\nOnly archie's **own** comments are excluded, matched on the forge identity\nthat owns the task (`bot_user`, or the identity's `bot_user` under\n`[[identities]]`), so its `ReplyToReview` replies do not retrigger it.\n\nEvery other author is actionable, including other bots. The external review\nbot on this repository is the main source of findings on an archie-opened PR,\nand discarding comments because their author is a bot would discard the review\nthis feature exists to act on. There is no \"is a bot\" test anywhere in this\npath.\n\n(The original draft justified a broader exclusion by citing a `RepliesAfter`\n`exclude` precedent. No such mechanism exists in the tree; the citation is\nwithdrawn.)\n\n#### Bounding the exchange\n\nBecause bot comments are actionable, the exchange can run away without a human\never touching it: archie pushes a remediation, the review bot re-reviews the\nnew commit, comments, archie remediates again. Nothing in the reaction path\nterminates that on its own.\n\nA task therefore carries a remediation round count, bounded by the repo's\nexisting `max_retries`. On the cap, archie stops remediating, posts one\ncomment saying it has stopped and why, and parks the task for an operator.\nThis is a hard stop, not a backoff: the failure it guards against is\nunbounded spend, so slowing it down does not address it.\n\n### 6. Security posture\n\nThe webhook reaction is not a public no-code binding, so it does not pass\nthrough the `draft → pending_approval → armed` gate (webhook-intake-security\npoint 2) — but every other constraint holds: HMAC (already in the receiver),\nper-source rate limiting (add when the receiver gains a second event family),\nand blast radius bounded by the existing gate/sandbox/worktree enforcement,\n**plus** the new archie-owned-task check (decision 3), which is the actual\nauthorisation boundary: a review event only ever causes work against a PR\narchie itself opened and still owns.\n\nAccepting other bots' comments (decision 5) does not widen that boundary: an\nauthor is never a reason to act, only the owned-task check is. It does widen\nthe _spend_ surface, which the round cap bounds.\n\n### 7. Sequencing\n\n1. **The reaction stream.** `ARCHIE_REACTIONS`, under the fan-out\n `jetstream.LimitsPolicy` the parent decision requires\n (`event-sources-and-reactions.md` §2). `Config.Retention` is\n parameterised for exactly this (`archie-core-7d5u.2`), but no reaction\n stream exists and `ARCHIE_TASKS` carries `archie.task.\u003e` only, so every\n publish to `archie.reaction.*` fails against no matching\n stream. This step is first because nothing after it can be exercised\n without it.\n2. `PullRequestReviewReader` + GitHub/Gitea implementations + `ReplyToReview`.\n _(Landed.)_\n3. `ReviewCommentEnvelope` + the kinded idempotency key.\n4. **The owned-task guard**: `(owner, repo, pr_number)` lookup, its\n `StateStoreService` RPC, its index, and the drop-with-counter path for an\n unmatched, merged, closed or archived PR. Nothing may consume a reaction\n before this exists.\n5. `remediate` workflow: worktree refresh, one run per review, builder, gate,\n push, reply, round cap.\n6. Webhook receiver extension (`pull_request_review` / `_comment` events).\n7. Poll backstop with the persisted `sinceID` cursor.\n8. Tests + `task check`.\n\nSteps 6 and 7 are the producers and come last on purpose. Building a producer\nbefore its consumer and its authorisation guard yields a path that publishes\ninto nothing, and becomes an unguarded intake the moment a stream appears.\n\n## Out of scope\n\n- Auto-merge on approval (separate decision).\n- Reacting to comments on PRs archie did not open.\n- The calibration epic's confirm-before-surfacing (h019.5) — orthogonal.\n" }, { "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 from this document; `RELEASING.md` points at that\nrule beside the step it governs rather than restating it, because two statements of\none rule drift.\n\n## Commit rules and their enforcement\n\n- **Conventional commits**, with the scope taken from the package map.\n- **One logical change per commit.** A commit that does two things is two commits.\n- **The subject is imperative and short**; the body says why the change is right\n rather than restating the diff.\n- **A commit depends on the gate's exit status.** The gate and the commit run as one\n conditional chain, never as separate statements on one command line, where nothing\n reads the gate's status but the operator who typed it.\n- **Enforcement is a `commit-msg` hook** installed by one documented target, plus a\n check in CI over the pushed range, so the rule holds for a person who never\n installed the hook.\n- **Scopes are derived, not invented**, and an unknown scope fails loudly rather than\n being accepted.\n\n## The release pipeline\n\n**A Woodpecker workflow performs the release**: gate, generate the release page, run\nthe reviewer over it, commit the changelog and the generated pages, tag, push,\npublish images, and trigger the site's artifact sync. No step in that list is an\noperator's.\n\n**It triggers on a push to main**, not on a manual run. A pipeline a human must start\nis a pipeline that can be forgotten, which is the property this change removes. The\ntrigger is also not dependent on repairing manual triggering: in this estate a manual\nrun fails with zero steps while the same configuration runs on a push, and the\nestate's own Woodpecker configurations trigger on push with cron, manual or\npull-request events _added_ to it rather than instead of it.\n\n**Prerequisite: Woodpecker must watch this repository.** Adding the workflow to the\nrepository and enabling the repository in Woodpecker are two steps, and the second is\na configuration action rather than a file. A release pipeline that is correct and\nnever runs is invisible until someone asks why no release happened, so the repository\nbeing enabled is a prerequisite of this design rather than an assumption behind it.\n\n**One tag, and the duplicate-build problem shrinks as a consequence.** Concurrency\nkeyed on a commit identifier treats an annotated tag as a ref distinct from its\ncommit, which starts three builds for one release. One version and one tag removes\ntwo of those refs. Nothing in the pipeline may depend on a tag object's\nidentity, and this is a consequence of one version stream rather than a separate fix.\n\n### The version is computed, not typed\n\nThe version is derived from the conventional commits since the last release, which is\nwhat the commit rules above exist for.\n\n- `feat` bumps the minor version; `fix`, `perf` and `refactor` bump the patch.\n- **A breaking change bumps the major version.** Its form is `!` after the type or\n scope, as in `feat(api)!:`, and a `BREAKING CHANGE:` trailer — either marks it.\n- `chore`, `docs`, `test`, `style` and `build` bump nothing alone.\n- **The scope decides whether a commit is the product's.** A commit whose scope is\n the repository's own machinery -- `release`, `ci`, `docs`, `build`, `test` -- does\n not bump the version even when its type is `feat` or `fix`, because it changes how\n the project is delivered rather than what it does. Without this filter the first\n improvement anyone makes to the release process inflates the product's version.\n- **No release is a legitimate outcome.** A commit set that justifies no version\n produces no version, and the pipeline reports that rather than inventing one.\n\n### `tools/release.sh` is designed for the pipeline\n\n- **It never prompts.** Every input arrives as an argument or in the environment, so\n it runs with no terminal.\n- **Its version is a result as well as an argument.** It may be given one or asked to\n derive one, and it reports the version it used in a form a pipeline can read.\n- **\"Nothing to release\" has its own exit code**, distinct from failure, so the\n pipeline finishes green without tagging.\n- **It commits and tags nothing.** The pipeline owns the commit, the tag and the push;\n the script writes the notes and reports what it did. A script that pushes cannot be\n run twice safely, and this one runs on every push to main.\n\n### Which CI is authoritative\n\nThree surfaces exist: GitHub Actions, the Gitea workflow files, and Woodpecker.\n\n- **Woodpecker owns releases**, which is the production path this repository's deploy\n workflow already names.\n- **GitHub Actions keeps the checks a pull request needs.**\n- **The Gitea workflow files are retired in favour of Woodpecker** once Woodpecker\n runs the same checks, and are not edited in the meantime: two copies of a pipeline\n diverge.\n- No check lives in two places with neither authoritative. Where a check must run in\n both, the second runs the same file rather than a copy of it.\n\n## Verification\n\n- One changelog file exists, the two component changelogs do not, and the generated\n pages match it.\n- A release prepared with `VERSION` alone writes its notes and tags, with no\n `GATEWAY` or `RUNTIME` input.\n- Every release URL published before this change resolves.\n- `release:tag` refuses after a review that reported at the level, and refuses when\n no review ran.\n- The `commit-msg` hook and the CI range check each refuse a non-conforming subject\n and an unknown scope, with the hook absent and present.\n- A push to main carrying releasable commits produces a version, a release page, a\n tag and a published image with no operator step.\n- A push whose commits justify no release ends green and tags nothing.\n- `tools/release.sh` runs to completion with stdin closed, and exits with its\n distinct code when there is nothing to release.\n- The release workflow reads no tag object's identity, so one release starts one\n build.\n" }, - { - "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/" diff --git a/docs/prds/adversarial-self-review.md b/docs/prds/adversarial-self-review.md deleted file mode 100644 index e15ccb0ec..000000000 --- a/docs/prds/adversarial-self-review.md +++ /dev/null @@ -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 | 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: }` -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. diff --git a/docs/prds/inline-review.md b/docs/prds/inline-review.md index 1083adb35..7345f2151 100644 --- a/docs/prds/inline-review.md +++ b/docs/prds/inline-review.md @@ -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 diff --git a/docs/prds/operator-pr-review.md b/docs/prds/operator-pr-review.md deleted file mode 100644 index e2287e575..000000000 --- a/docs/prds/operator-pr-review.md +++ /dev/null @@ -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/`. - `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged: - `Diff` resolves `origin/` 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. diff --git a/docs/prds/pr-review-agent.md b/docs/prds/pr-review-agent.md index 48ed54723..c0f644e33 100644 --- a/docs/prds/pr-review-agent.md +++ b/docs/prds/pr-review-agent.md @@ -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), diff --git a/docs/prds/pr-review-remediation.md b/docs/prds/pr-review-remediation.md index 5d2b2c3ae..2cfded647 100644 --- a/docs/prds/pr-review-remediation.md +++ b/docs/prds/pr-review-remediation.md @@ -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 diff --git a/docs/prds/review-calibration.md b/docs/prds/review-calibration.md deleted file mode 100644 index 2445aae4e..000000000 --- a/docs/prds/review-calibration.md +++ /dev/null @@ -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. diff --git a/internal/domain/workflow/implement.go b/internal/domain/workflow/implement.go index 7fd717fc9..6f73b01dd 100644 --- a/internal/domain/workflow/implement.go +++ b/internal/domain/workflow/implement.go @@ -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 diff --git a/internal/domain/workflow/workflow.go b/internal/domain/workflow/workflow.go index efdaeccef..ec7097cf2 100644 --- a/internal/domain/workflow/workflow.go +++ b/internal/domain/workflow/workflow.go @@ -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 } diff --git a/internal/worktree/worktree.go b/internal/worktree/worktree.go index a75b69f01..83550ead5 100644 --- a/internal/worktree/worktree.go +++ b/internal/worktree/worktree.go @@ -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 {