Findings contract: a structured review result the workflow can act on #266
Notifications
Due Date
No due date set.
Blocks
Depends on
Reference: sam/archie#266
Reference in new issue
Block a user
The reviewer's output must be data the workflow can branch on, not prose a human has to read to find out whether the PR is safe to open. Prose is what makes a review advisory; structure is what lets a finding block.
Define the finding type in the workflow domain (the domain declares the contract it needs; it never names who implements it). At minimum a finding carries: file and line, a one-sentence defect, a concrete failure scenario (inputs/state -> wrong output), a verdict distinguishing CONFIRMED from PLAUSIBLE, and a disposition once acted on (fixed / skipped / no_change_needed).
The CONFIRMED/PLAUSIBLE split is load-bearing and must not be collapsed into a single boolean: only confirmed findings may block, or the feature degrades into crying wolf and the operator learns to skim past it.
Acceptance criteria
A finding type exists in internal/domain/workflow with file, line, summary, failure scenario, verdict and disposition; it is serialisable across the agent-execution data boundary; a review result with zero findings is representable and distinct from a review that did not run.
Close reason
Implemented: workflow.ReviewFinding + ReviewReport in internal/domain/workflow/review_findings.go, merged 53bb841. The domain owns the type; gate.Finding was used as a shape precedent only, not reused, so the review contract is not coupled to the Yaegi gate's evolution. Blocking requires Verdict==confirmed AND Level==error, so a PLAUSIBLE finding never blocks however severe it claims to be. ReviewStatus makes 'ran and found nothing' structurally distinct from 'never ran' -- Passed() is false for a zero-value report, and the distinction does not rest on nil-vs-empty-slice. JSON round-trip covered; Line 0 is preserved (no omitempty) for whole-file findings. Review found and fixed a duplicate package doc comment and a redundant ReviewBlocking/BlockingReviewFindings alias pair. task check green. Fresh adversarial review clean across 8 dimensions; I independently mutation-tested the blocking rule: dropping the verdict check fails 5 tests (incl. plausible_error_MUST_NOT_block) and dropping the level check fails 5 more, so the tests genuinely pin both halves.
Imported from beads
archie-core-h019.2· GitHub #551 · type feature · priority P1 · created 2026-08-21 · closed 2026-08-24