Repository navigation
Standard 1.5.1: Add actionable review correction protocol #18
Description
Problem or opportunity
Agent Handoff 1.5 defines when a finding may block acceptance, but it does not define what a reviewer must provide when handing a blocking finding back to an implementation agent. A bare defect statement can therefore trigger avoidable clarification and re-review loops, or cause an agent to weaken invariants, expand scope, or follow an implementation suggestion as if it were a hidden acceptance criterion.
Proposed change
Publish Agent Handoff Standard 1.5.1 with a compact ai/REVIEW_PROTOCOL.md and synchronized workflow, reporting, validation, and release documentation.
A blocking finding must provide a sufficient correction contract: stable ID, evidence or reproduction, violated contract, required outcome, preserved invariants, scope guard, applicable verification, and observable acceptance criteria. Cause confidence must be explicit (confirmed | likely | unknown). Implementation guidance may recommend a solution, but equivalent alternatives remain valid when they satisfy the required outcome and invariants.
Non-blocking findings and questions remain lightweight. Finding state is distinct from PR state: open → addressed → verified; an agent may report a finding as addressed, but only reviewer verification resolves it.
Primary outcome
A reviewer can hand a blocking defect to a coding agent as a self-contained, verifiable correction task without prescribing one implementation unnecessarily.
Smallest acceptance proof
The repository checker passes and confirms the new review protocol, correction-report fields, PR checklist item, active version metadata, and matching 1.5.1 release notes.
Execution envelope
Authorized: focused English documentation, templates, structural validation, version/release metadata, one handoff, branch/PR publication, squash merge after green checks, tag v1.5.1, and a published GitHub Release. No product code, container layout, security baseline, existing tag, repository settings, or unrelated protocol changes.
Acceptance criteria
ai/REVIEW_PROTOCOL.mddefines blocking, non-blocking, and question findings proportionately.- Blocking findings contain enough evidence, contract, outcome, invariants, scope, verification, and acceptance information for another agent to act without chat history.
- Root-cause certainty is explicit and hypotheses are not represented as facts.
- Recommended implementation is guidance, not a hidden acceptance criterion; safe equivalent alternatives are allowed.
- Positive, negative, security, and race tests are required only when applicable.
- Agent correction reports map stable finding IDs to changes and evidence.
addresseddoes not meanverifiedor automatically resolved.- The workflow, standard, task reports, PR checklist, checker, public documentation, changelog, citation metadata, project state, decision record, and release notes agree on Standard 1.5.1.
- Repository checks and GitHub Actions pass.
- Release
v1.5.1is published from the verified merge commit.
Non-goals
- Automated semantic scoring of review quality.
- A mandatory long template for nits, optional suggestions, or questions.
- Requiring every category of test for every finding.
- Allowing a review finding to widen agent authority or the original Issue scope.
- Replacing GitHub review threads with repository memory files.
Activity
artyomboyko commentedon Jul 27, 2026
Agent Handoff Work Claim
Agent: Review Lynx
Agent ID: review-lynx-5a1c
Run ID: 20260727-issue-18-5a1c
Coordinator: Artyom Boyko
Supervision: human-supervised
Started: 2026-07-27 12:18 UTC
Issue: #18
Branch: actionable-review-protocol
Draft PR: TBD
Scope: Add a proportionate reviewer-to-agent correction contract and publish Standard 1.5.1.
Primary outcome: A blocking review can be handed to a coding agent as a self-contained, verifiable correction task without unnecessarily prescribing one implementation.
Smallest acceptance proof:
python3 scripts/check_agent_handoff.pypasses and validates the protocol, correction report, PR checklist, active 1.5.1 metadata, and release notes; GitHub Actions is green before merge.Execution envelope: Focused English protocol, standard, workflow, reporting, template, validation, public docs, release metadata, one decision record, one handoff, branch/PR publication, squash merge after green checks, tag
v1.5.1, and published GitHub Release. No product code, container layout, security baseline, existing tag, repository settings, or unrelated protocol changes.Status: in-progress
Next update: Draft PR after the synchronized change passes local validation.
artyomboyko commentedon Jul 27, 2026
Agent Handoff Final Result
Agent ID: review-lynx-5a1c
Run ID: 20260727-issue-18-5a1c
Status: completed
Primary outcome: A blocking review can be handed to a coding agent as a self-contained, verifiable correction task without unnecessarily prescribing one implementation.
Outcome progress: completed
Acceptance proof: The locally validated tree matches all 24 changed files on PR head
99f6b90644c1fdc53466906be353c6be0aa68b18; repository checker passes; GitHub Actions run30266060075passed.Supporting work: Synchronized standard metadata, public docs, templates, structural validation, decision record, release notes, and one handoff.
Verified blocker: none
Summary:
ai/REVIEW_PROTOCOL.mdand synchronized Agent Handoff Standard 1.5.1.addressedremains distinct from reviewer-confirmedverified.Changed:
Not changed:
Tests:
python3 scripts/check_agent_handoff.py— passed.scripts/check_agent_handoff.py— passed.ai/REVIEW_PROTOCOL.md— failed as expected with the required-path error.git diff --check— passed.30266060075— success.Docs:
docs/releases/v1.5.1.md; synchronized README, GitHub Pages, FAQ, changelog, citation metadata, promotion checklists, project state, and decision record.Commits:
99f6b90644c1fdc53466906be353c6be0aa68b18Risks:
Next direct outcome step:
v1.5.1from the verified merge commit.