The adversarial self-review system was removed in 625ead95, but four pages
describing it survived: the architecture page, its design-decision PRD, and the
two superseded calibration/operator PRDs. The architecture page carried a
hand-written "removed, not shipped" banner and was kept only because live PRDs
linked to it, so every reader paid for a system the tree no longer has.
Delete all four and repoint the live referrers at the authority that replaced
them (docs/prds/pr-review-agent.md): inline-review.md's Builds-on line,
pr-review-remediation.md's isolation-contract citation, pr-review-agent.md's
supersede clause, CLAUDE.md's contributor rule, and three Go comments that cited
the deleted paths. Regenerate docs/data/generated/dev-docs.json.
History stays in git; the tree stops describing a system it does not have.
"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##Lifecycleeffect\n\n`StageReview`runsintheimplementworkflowafterthedeterministicgatesand\nbefore`StageOpenPR`,gatedby`repo.review_enabled`(opt-in,defaultoff).A\nsurvivingblockingfinding—orareviewthatfailedtorun—parksthetask\n(`StatusParked`,not`waiting_human`)withthefindingsrenderedintothepark\nreason;`StageOpenPR`neverruns.Warn/plausiblefindingsandthezero-finding\ncaseleavetheoutcomeunset,sothePRopenswithafindingssectionrendered\nontoitsbody.`StagePostReviewComments`thenrunsafter`StageOpenPR`andposts\nthe**line-anchored**findingsasinlinereviewcomments,carryingaone-click\nsuggestiononaconfirmedfindingthereviewercouldstateafixfor.Thatstage\nisbest-effort—acommentthatfailstopostislogged,neverapark—because\nthebodysectionalreadylistseveryfinding,anditistherecordawhole-file\nfinding(nolinetoanchorto)onlyeverappearsin.\n\n##Modelandbudget\n\nThereviewermodelis`models.reviewer`,fallingbackto`models.builder`.\nEffortistheper-stage`MaxSteps`budget,mappedonto`Subagent.MaxSteps`\n(default10).\n\n##OperatorLine truncated
},
{
"url":"/dev/architecture/agent-system/",
"title":"Agent System",
@@ -174,12 +168,6 @@
"section":"PRDs",
"body":"# Running action playbooks\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** `docs/prds/multi-action-playbooks.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.31`\n\n## Why this exists\n\nAn action playbook loads and type-checks but never runs: `Store.Dispatch`\nskips it and the daemon logs a warning at boot (`multi-action-playbooks.md`,\nD1). This document defines when it runs, what each action does, and how the\n`playbook_dispatches` ledger gates it.\n\n## When a playbook runs\n\nThe daemon runs action playbooks at the point it pins a task's workflow\ndefinition (`Daemon.resolveWorkflowID`), using the same `DispatchInput` the\nworkflow playbooks use. The definition is pinned once per task, so the run\nhappens once per task.\n\n- Every action playbook whose trigger matches runs, in load order. A workflow\n playbook stops at the first match because it chooses one workflow; action\n playbooks choose nothing, so no match suppresses another.\n- A run never changes routing. The task is pinned by the workflow playbooks\n and bindings exactly as when no action playbook exists.\n- An action or playbook failure never parks or fails the task. It is logged\n at warning level with the playbook, the action and the task.\n- A task that already names a workflow (the approval requeue) is skipped, as\n it is for workflow playbooks.\n- Actions run synchronously in the pin path, bounded by the daemon's context.\n The only Module kind, `log`, returns immediately. A slow kind must bring its\n own timeout.\n\n## What one action does\n\nActions run in order against one evaluation context whose `actions` map\nstarts empty.\n\n1. Evaluate `when`. False or an evaluation error skips the action (J3). A\n skipped action records nothing and produces no result.\n2. Evaluate every `args` value. An evaluation error stops the playbook.\n3. Call `playbook.InvokeOnce` with the Module invoke as its function. The\n ledger row is written first. A duplicate row skips the invoke.\n4. An invoke error stops the playbook. The row stays, so the action is not\n retried: the ledger promises at most once, not at least once.\n5. On success, `ModuleRegistry.DecodeResult` converts the result, and it is\n stored as `actions.\u003cid\u003e.result` when the action declares an id.\n\nThe event id in the ledger key is `DispatchInput.TaskID`, the issue's\nidempotency key (`owner/repo/number`). An action therefore runs at most once\nper issue for each playbook version. Editing a playbook changes its version\nand lets it run again for issues it already handled.\n\nA skipped duplicate has no result. A later action that reads it sees a\nmissing field: its `when` evaluates false, or its args fail and the playbook\nstops. This only happens when the same issue is pinned twice under one\nplaybook version.\n\n## Wiring\n\n- `storecontract.PlaybookDispatcher` is lifted onto the daemon from the State\n Store client in `internal/app/archied/bootstrap.go`, the same way\n `BindingDispatcher` is.\n- The daemon's `Playbooks` dependency gains the run method. The Module\n registry is passed to the playbook store at load, so the daemon needs no\n new dependency for it.\n- With no `PlaybookDispatcher` wired, action playbooks do not run, and the\n boot warning names each one. They never run without the ledger.\n- The boot warning that action playbooks do not execute is removed when the\n ledger is wired.\n\n## Verification\n\n- A matching two-action `log` playbook runs both actions in order, and the\n second reads the first's result.\n- Pinning the same task twice under one playbook version invokes each action\n once.\n- A `when` that evaluates false skips that action and the run continues.\n- An invoke error stops the playbook. The task is still pinned to the same\n workflow it would get with no action playbook.\n- A non-matching trigger runs nothing.\n- With no ledger wired, nothing runs and the warning names the playbook.\n"
"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\nalreadycapturedsurviveanerrorreturn,so**thestagereadsthecaptured\nsliceevenwhen`Run`returnsanerror**.Areviewerthatloggedthreedefects\nandthenhititssteplimitstillyieldsthosethree.\n\n##2.Whatit'sgiven,andwhatitmustneverbegiven\n\n**Given:**thecleanfile-contentsnapshot(sothereviewercanreadwhole\nfiles--followanimport,checkinterfacesatisfaction,seeacallsite--\nnotjustdiffhunks,whichthemanual-readchecklistinCLAUDE.mdrLine truncated
},
{
"url":"/dev/prds/agent2agent-protocol/",
"title":"Agent2Agent as archie's agent-to-agent protocol — decision",
@@ -346,7 +334,7 @@
"url":"/dev/prds/inline-review/",
"title":"Inline review -- decision",
"section":"PRDs",
"body":"# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\")hasnolinetoattachtoandstaysin\nthePR-bodylist.Thebodysectionkeepslistingeverything,soitremainsthe\ncompleterecordandthefallback.\n\nFindingsthatblockneverreachthispath:asurvivingblockingfindingparks\nthetaskbefore`StageOpenPR`,sothereisnoPRtocommenton.Inlinecomments\narethenon-blocking,line-anchoredsubset—whichisexactlythesetthatwould\notherwisebeabody-onlylisttheauthorhastomapbacktolinesbyhand.\n\n###4.Abest-effortstageafter`StageOpenPR`\n\nNew`StagePostReviewComments`,after`StageOpenPR`:\n\n1.Readthereportstashedby`StageReview`(`tc.ReviewReport`,h019.6).\n2Line truncated
"body":"# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review)\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\")hasnolinetoattachtoandstaysin\nthePR-bodylist.Thebodysectionkeepslistingeverything,soitremainsthe\ncompleterecordandthefallback.\n\nFindingsthatblockneverreachthispath:asurvivingblockingfindingparks\nthetaskbefore`StageOpenPR`,sothereisnoPRtocommenton.Inlinecomments\narethenon-blocking,line-anchoredsubset—whichisexactlythesetthatwould\notherwisebeabody-onlylisttheauthorhastomapbacktolinesbyhand.\n\n###4.Abest-effortstageafter`StageOpenPR`\n\nNew`StagePostReviewComments`,after`StageOpenPR`:\n\n1.Readthereportstashedby`StageReview`(`tc.ReviewReport`,h019.6).\n2.Posteachline-anchoredfindingasaninlLine truncated
},
{
"url":"/dev/prds/mcp-tool-completion/",
@@ -384,12 +372,6 @@
"section":"PRDs",
"body":"# Public news and per-version release notes\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Beads issue:** `archie-core-2ncm.2`\n**Superseded in part:** `docs/prds/release-stream-and-commit-rules.md` defines the\nsingle release stream. `CHANGELOG.md` carries every release and one `vX.Y.Z` tag\nnames each release.\n\nThe Astro website renders public news and per-version release notes from the\nartifacts generated here. Both derive from `CHANGELOG.md`, so publishing a\nrelease adds no writing.\n\n## Source of truth\n\nRelease notes come from the frozen sections in `CHANGELOG.md`:\n`tools/release.sh --prepare` writes a section, and `--tag` refuses to tag a\nversion without it. The generated artifact has one entry per release version.\n\nTags and raw commits are not the source. The changelog is the edited release\nrecord, and its `## [\u003cversion\u003e] - \u003cdate\u003e` headings provide the version and date.\n\n## Release data\n\nThe generator skips `## [Unreleased]`. Any other `## [` heading that is not\n`[version] - date` stops generation. A relative Markdown link in a changelog\nbody also stops generation because the Astro site must be able to render the\ncontent without depending on repository-relative paths.\n\n`archied` and `archie-agent` version independently. Each\n`docs/news/releases.json` entry carries the tag prefix (`archied`, `archie`),\nproduct name (`archied`, `archie-agent`), version, date, and changelog body.\n`docs/news/redirects.json` maps retired per-component news URLs to each unified\nrelease route. The Astro site must apply this table so previously published\nrelease URLs continue to resolve.\n\nBoth JSON files are committed generated artifacts. `task news` regenerates\nthem, `task news:check` detects drift, and `tools/release.sh --tag` regenerates\nand stages them with the release commit. The Astro site renders from these\nartifacts rather than re-parsing `CHANGELOG.md`.\n\n## Site ownership\n\nThe Astro website is maintained outside this repository and serves the\ndocumentation at `offloaded.dev/docs/`. This repository generates and validates\nthe news and documentation data artifacts; it does not build, preview, or\ndeploy the Astro site.\n\n## Not in scope\n\n- Generated summaries, categories, or section headings; the changelog has no\n structured summary field to derive one from.\n- Per-release download or install links; where to get the artifacts is\n documented once, not restated for every release.\n- Hand-written news items.\n- Changes to `infra/ansible` or to the external Astro website repository.\n\n## Verification\n\n- `go test ./tools/newsgen/...` covers parsing, ordering, artifact generation,\n heading and link refusals, and check-mode drift.\n- `task news:check` passes inside `task check`.\n- `task docs:artifact:check` verifies the generated documentation data against\n its Markdown sources.\n"
},
{
"url":"/dev/prds/operator-pr-review/",
"title":"Operator-triggered PR review",
"section":"PRDs",
"body":"# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an _existing_ PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\nBaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\nbaseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorisation.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
"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,oran\ninlinecommentonaline,isinvisiblework.\n\n##Decisions\n\n###1.Readsurface:anarrow`PullRequestReviewReader`,type-asserted\n\nAnewforgeinterface,implementedbyGitHubandGitea,notfoldedintothe\nfat`Forge`interface(theh019.8`PullRequestReader`precedent—thenoop\nforgecannothonestlyprovideit):\n\n```go\ntypeReviewCommentstruct{IDint64;Author,Body,Pathstring;Lineint;InReplyToint64;CreatedAttime.Time}\ntypeReviewstruct{IDint64;Author,Statestring/*requested_changes|approved|commented|dismissed*/;SubmittedAttime.Time}\n\ntypePullRequestReviewReaderinterface{\nListReviews(ctx,owner,repostring,number,sinceIDint64)([]Review,error)\nListReviewComments(ctx,owner,repostring,number,sinceIDint64)([]ReviewComment,error)\n//ReplyToReviewpostsareplytoarevieworcommentthread.\nReplyToReview(ctx,owner,repostring,number,inReplyToint64,bodystring)error\n}\n```\n\nGitHub:`pulls/{n}/reviews`+`pulls/{n}/comments`;replyvia\n`pulls/{n}/comments/{id}/replies`.Gitea:`pulls/{n}/reviews`+\n`pulls/{n}/comments`;replyvia`pulls/{n}/comments/{id}`.`sinceID`isthe\ncursorforbothpollandwebhookdedup.\n\n###2.Eventsource:webhookfirst,pollastheuniversalbackstop\n\n-**Webhook(GitHub,lowlatency):**extend`receiver.go`toalsodecode\n`pull_request_review`and`pull_request_review_comment`events,behindthe\nexistingHMACverification,producingthesamereactionasthepoller.The\nreceiverstaysaforge-intakesurface—notthegenericchatwebhook,nota\nnewgenericreceiver(7d5udecision4).\n-**Poll(bothforges,nowebhookdependency):**aperiodicscanof`pr_open`\ntaskscalls`ListReviews`/`ListReviewComments`withapersisted`sinceID`\ncursorpertask.ThisistheGiteapathandthedeployment-without-webhook\npath;itmuststayfirst-class,notalegacyfallback(therepo'sown\nwebhook-intakerule).Itis**onesharedscanoverall`pr_open`tasks**,\nnotascaninsideeachidentity'spollloop,anditcallstheforgeclient\nthescannedtask'sownidentityowns.Thisis`reconcilePRs`'sshape\nexactly(`internal/daemon/daemon.go`:`Store.OpenPRs`then`forgeFor(\u0026t)`).\nAper-identityscanwouldcalloneidentity'sforgeclientagainstanother\nidentity'sPR.\n\nBothpathsemitthe**same**typedreaction,so`PublishUnique`dedupsthem\nforfree—the`TaskEnvelope.IdempotencyKey`pattern(7d5udecision4)applied\ntoreviews.\n\n###3.Reactioncontract:producer-only,resolvestoanexistingtask\n\nAnew`workintake.ReviewCommentEnvelope{Owner,Repo,PRNumber,Kind,CommentID,\nReviewID,Author,State,Body,Path,Line}`.Idempotencykeyis\n`owner/repo/pr-number/kind/id`—source-independent,soawebhookdelivery\nandapollofthesamecommentcollapse.\n\n`Kind`(`review`or`comment`)ispartofthekeybecauseareviewIDanda\nreview-commentIDcomefromindependentforgesequences.Keyingonthebareid\nletsareviewandaninlinecommentonthesamePRcollide,silentlydropping\noneofthetwo.Thisisaproducer-onlyreaction\n(7d5udecision3):itnevervetoesormutatesin-flightwork;thetargettask\nisidle(`pr_open`).\n\nThedaemonresolves`PRNumber`→thetaskthatownsit.AnunmatchedPR(not\nanarchietask)isdroppedwithacounter—apublicwebhookmustnotbeable\ntostartanagentagainstanarbitraryrepository.APRwhosetaskismerged,\nclosedorarchivedisdroppedthroughthesamecounter:thereactionisonly\neverworkagainstaPRarchieitselfopened_andstillowns_.\n\nThatlookupdoesnotexist.`pr_number`iswrittenby\n`internal/infrastructure/postgres/store.go`andneverreadina`WHERE`clause,sothisneedsa\n`TaskStore`methodkeyLine truncated
"body":"# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the review pipeline's\nisolation contract (`docs/prds/pr-review-agent.md`, \"Isolation\") and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\"review,oran\ninlinecommentonaline,isinvisiblework.\n\n##Decisions\n\n###1.Readsurface:anarrow`PullRequestReviewReader`,type-asserted\n\nAnewforgeinterface,implementedbyGitHubandGitea,notfoldedintothe\nfat`Forge`interface(theh019.8`PullRequestReader`precedent—thenoop\nforgecannothonestlyprovideit):\n\n```go\ntypeReviewCommentstruct{IDint64;Author,Body,Pathstring;Lineint;InReplyToint64;CreatedAttime.Time}\ntypeReviewstruct{IDint64;Author,Statestring/*requested_changes|approved|commented|dismissed*/;SubmittedAttime.Time}\n\ntypePullRequestReviewReaderinterface{\nListReviews(ctx,owner,repostring,number,sinceIDint64)([]Review,error)\nListReviewComments(ctx,owner,repostring,number,sinceIDint64)([]ReviewComment,error)\n//ReplyToReviewpostsareplytoarevieworcommentthread.\nReplyToReview(ctx,owner,repostring,number,inReplyToint64,bodystring)error\n}\n```\n\nGitHub:`pulls/{n}/reviews`+`pulls/{n}/comments`;replyvia\n`pulls/{n}/comments/{id}/replies`.Gitea:`pulls/{n}/reviews`+\n`pulls/{n}/comments`;replyvia`pulls/{n}/comments/{id}`.`sinceID`isthe\ncursorforbothpollandwebhookdedup.\n\n###2.Eventsource:webhookfirst,pollastheuniversalbackstop\n\n-**Webhook(GitHub,lowlatency):**extend`receiver.go`toalsodecode\n`pull_request_review`and`pull_request_review_comment`events,behindthe\nexistingHMACverification,producingthesamereactionasthepoller.The\nreceiverstaysaforge-intakesurface—notthegenericchatwebhook,nota\nnewgenericreceiver(7d5udecision4).\n-**Poll(bothforges,nowebhookdependency):**aperiodicscanof`pr_open`\ntaskscalls`ListReviews`/`ListReviewComments`withapersisted`sinceID`\ncursorpertask.ThisistheGiteapathandthedeployment-without-webhook\npath;itmuststayfirst-class,notalegacyfallback(therepo'sown\nwebhook-intakerule).Itis**onesharedscanoverall`pr_open`tasks**,\nnotascaninsideeachidentity'spollloop,anditcallstheforgeclient\nthescannedtask'sownidentityowns.Thisis`reconcilePRs`'sshape\nexactly(`internal/daemon/daemon.go`:`Store.OpenPRs`then`forgeFor(\u0026t)`).\nAper-identityscanwouldcalloneidentity'sforgeclientagainstanother\nidentity'sPR.\n\nBothpathsemitthe**same**typedreaction,so`PublishUnique`dedupsthem\nforfree—the`TaskEnvelope.IdempotencyKey`pattern(7d5udecision4)applied\ntoreviews.\n\n###3.Reactioncontract:producer-only,resolvestoanexistingtask\n\nAnew`workintake.ReviewCommentEnvelope{Owner,Repo,PRNumber,Kind,CommentID,\nReviewID,Author,State,Body,Path,Line}`.Idempotencykeyis\n`owner/repo/pr-number/kind/id`—source-independent,soawebhookdelivery\nandapollofthesamecommentcollapse.\n\n`Kind`(`review`or`comment`)ispartofthekeybecauseareviewIDanda\nreview-commentIDcomefromindependentforgesequences.Keyingonthebareid\nletsareviewandaninlinecommentonthesamePRcollide,silentlydropping\noneofthetwo.Thisisaproducer-onlyreaction\n(7d5udecision3):itnevervetoesormutatesin-flightwork;thetargettask\nisidle(`pr_open`).\n\nThedaemonresolves`PRNumber`→thetaskthatownsit.AnunmatchedPR(not\nanarchietask)isdroppedwithacounter—apublicwebhookmustnotbeable\ntostartanagentagainstanarbitraryrepository.APRwhosetaskismerged,\nclosedorarchivedisdroppedthroughthesamecounter:thereactionisonly\neverworkagainstaPRarchieitselfopened_andstillowns_.\n\nThatlookupdoesnotexist.`pr_number`iswrittenby\n`internal/infrastructure/postgres/store.go`andneverreadina`WHERE`clause,sothisneedsa\n`TaskStore`methodkeyeLine truncated
},
{
"url":"/dev/prds/progressive-tool-disclosure/",
@@ -450,12 +432,6 @@
"section":"PRDs",
"body":"# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\"the\nunifiedchangelogbyrewritingtagstomatchit.\n\n##Onereleasepageperversion\n\n`docs/news/\u003cversion\u003e.md`replaces`docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`,carryingthe\nrelease'sper-componentsectionsinsideit.\n\n**EveryreleaseURLalreadypublishedkeepsworking.**`/news/archied/\u003cversion\u003e`and\n`/news/archie/\u003cversion\u003e`routetotheunifiedpageforthatversion.Thegenerator\nemitstheredirecttablebesidethepagessoitcannotdriftfromthem;ifthe\nrendererneedsthetableinitsownrepository,thatisachangeinthatrepository\nratherthanahand-maintainedlisthere.\n\n##Thereviewerrunsbetweenprepareandtag\n\nReleasenotesareprose,andthereviewagentexiststoreviewprose.**`release:tag`\nrefusestotagwhenthereviewhasnotbeenrunforthatversion,orwhenitreports\natthelevel.**\n\nTheinvocationisverifiedratherthanassumed.`tlrules--lint`reports`corpusok`\nandexits0.`tlreview\u003cpath\u003e--deadline\u003cms\u003e--max-turns\u003cn\u003e`reports\n`0findings(0high,0medium)·1/1filesreviewed·clean`andexits0on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on`mustbepassedexplicitly.**Itdefaultsto`never`,soaninvocation\nwithoutitcannotrefuseanythingandthestepwouldbedecorative.`--fail-onhigh`\nisthelevel:amediumfindinginareleasenoteisworthactingon,anditshouldnot\nstopareleaseonitsown.\n\n**Theruleisstatedonce.**Itbelongsinthereviewer'sownruleset,which\n`tlrules--from-doc`candraftfrLine truncated
},
{
"url":"/dev/prds/review-calibration/",
"title":"Review calibration -- decision",
"section":"PRDs",
"body":"# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report _nothing_\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.