Findings contract: a structured review result the workflow can act on #266

Closed
opened 2026-10-27 13:35:37 +00:00 by sam · 0 comments
Owner

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

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_
sam added the highfeature labels 2026-10-27 13:35:37 +00:00
sam self-assigned this 2026-10-27 13:35:37 +00:00
sam closed this issue 2026-10-27 13:35:37 +00:00
sam added a new dependency 2026-10-27 13:41:51 +00:00
sam added a new dependency 2026-10-27 13:41:51 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#266