Standard 1.5.1: Add actionable review correction protocol

.github/pull_request_template.md

@@ -30,6 +30,7 @@ Closes #
 - [ ] Required stage or final result comment exists.
 - [ ] Smoke tests were run or reason is documented.
 - [ ] Primary outcome, smallest acceptance proof, and execution envelope are recorded; supporting work did not become an independent stage, handoff, completion target, or approval gate without crossing an explicit boundary.
+- [ ] Blocking review findings, when present, contain sufficient correction contracts; agent-reported addressed findings map to changes and evidence, and reviewer verification remains separate.
 - [ ] Security and evidence work did not block acceptance or expand scope without a verified High/Critical current-scope risk or an exactly cited mandatory requirement; other items remain non-blocking.
 - [ ] Mandatory containerization decision was confirmed when relevant, or not applicable.
 - [ ] Changed Compose configuration was rendered and checked, or reason and risk are documented.

AGENTS.md

@@ -20,6 +20,8 @@ Use GitHub Issues and Pull Requests as the primary workflow system.
 
 Report each meaningful Issue with a required stage or final result comment.
 
+For Pull Request review or `changes-requested` work, read `ai/REVIEW_PROTOCOL.md`. A blocking finding must provide a sufficient correction contract, while implementation guidance remains non-binding unless an exact mandatory requirement is cited. An agent-reported `addressed` finding still requires reviewer verification.
+
 Prioritize the stated primary outcome and its smallest acceptance proof. Record the execution envelope before implementation. Keep supporting work subordinate: fix localized, reversible supporting-work failures and perform bounded post-fix verification within the same work item and authorization. Create a stage, handoff, or completion target only when the outcome materially advanced, the acceptance proof completed, a verified blocker is outside the execution envelope, or work is genuinely interrupted or transferred. A supporting-tool failure alone does not require new owner approval; request a decision only when an explicit approval boundary is crossed. After two consecutive supporting-only updates without outcome progress, mark the work `progress-stalled` and replan the shortest path.
 
 Security and evidence work MUST NOT block acceptance or expand scope without a verified High or Critical current-scope risk supported by reproducible evidence or a directly applicable authoritative source. A suspected High or Critical risk permits only a short, time-boxed investigation until confirmed. Keep Low, Medium, unrated, and unverified risks non-blocking; preserve the existing security baseline and prioritize the smallest useful end-to-end scenario. An exact acceptance criterion or verified mandatory requirement is an independent blocker only when cited.

AGENT_HANDOFF_STANDARD.md

@@ -1,8 +1,8 @@
 ---
 standard: Agent Handoff
-version: "1.5"
+version: "1.5.1"
 status: active
-updated: 2026-07-26
+updated: 2026-07-27
 ---
 
 # Agent Handoff Standard
@@ -35,6 +35,7 @@ ai/HANDOFF_PROTOCOL.md
 ai/AGENT_IDENTITY.md
 ai/WORK_CLAIM_PROTOCOL.md
 ai/TASK_REPORT_PROTOCOL.md
+ai/REVIEW_PROTOCOL.md
 ai/REFACTORING.md
 ai/handoffs/INDEX.md
 .github/ISSUE_TEMPLATE/
@@ -56,11 +57,12 @@ Before meaningful work, read:
 6. `ai/AGENT_IDENTITY.md`
 7. `ai/WORK_CLAIM_PROTOCOL.md`
 8. `ai/TASK_REPORT_PROTOCOL.md`
-9. `ai/PROJECT_STATE.md`
-10. `ai/DECISIONS.md`
-11. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, or being discussed
-12. related GitHub Issue or Pull Request
-13. relevant handoffs through `ai/handoffs/INDEX.md`
+9. `ai/REVIEW_PROTOCOL.md` when reviewing a Pull Request, responding to `changes-requested`, or resuming work with open blocking findings
+10. `ai/PROJECT_STATE.md`
+11. `ai/DECISIONS.md`
+12. `ai/CONTAINERIZATION.md` when Docker or Compose is used, planned, or being discussed
+13. related GitHub Issue or Pull Request
+14. relevant handoffs through `ai/handoffs/INDEX.md`
 
 ## Task result reports
 
@@ -72,6 +74,8 @@ Small single-stage Issues must have one final result comment before the work is
 
 Use `ai/TASK_REPORT_PROTOCOL.md` for the required comment templates.
 
+When blocking review findings are addressed, use the correction report in `ai/TASK_REPORT_PROTOCOL.md`.
+
 ## Workflow
 
 1. Select or create a GitHub Issue.
@@ -234,6 +238,33 @@ A 10–15% share of stage work for security and evidence may be used as a non-bi
 
 Reviews, task reports, and handoffs must distinguish verified blocking High or Critical risks, time-boxed investigations of suspected High or Critical risks, follow-up hardening, and owner-accepted risks.
 
+## Actionable review handoff
+
+A blocking review MUST hand off more than the fact that a defect exists. It must provide a sufficient correction contract so another agent can act without private chat history.
+
+Each blocking finding must have:
+
+- a stable finding ID;
+- evidence and reproduction, or an exactly cited acceptance criterion or verified mandatory requirement when runtime reproduction is not applicable;
+- the violated behavioral, architectural, compatibility, security, or acceptance contract;
+- a cause marked `confirmed`, `likely`, or `unknown`;
+- the required observable outcome;
+- invariants and a scope guard;
+- minimum applicable verification and expected evidence;
+- observable acceptance criteria.
+
+Implementation guidance is optional and MUST NOT become a hidden acceptance criterion. An equivalent correction is valid when it achieves the required outcome, preserves the stated invariants, remains inside the execution envelope, and supplies the required evidence. A reviewer must not reject it solely because it differs from the recommended implementation.
+
+Positive, negative, security, and race tests are selected by applicability, not required mechanically for every finding. Race tests are required only when concurrency, lifecycle ordering, cancellation, retries, cleanup, or shared state is material.
+
+The full correction contract is mandatory only for findings classified `blocking`. Non-blocking findings and questions may remain concise but must be classified clearly. A security or evidence finding remains subject to the proportionality rule above; this review protocol does not make an otherwise ineligible finding blocking.
+
+An agent reports each blocking finding as `addressed`, `disputed`, `blocked`, or `not-addressed` and maps it to the change and evidence. `Addressed` is not `verified`: only the reviewer or another authorized maintainer verifies the correction. Finding state normally follows `open -> addressed -> verified`; failed verification reopens it.
+
+A review finding does not widen the agent's authority or Issue scope. If every safe correction crosses an approval boundary, the agent must state the minimum required expansion and request the applicable owner decision.
+
+Use `ai/REVIEW_PROTOCOL.md` for the complete templates and lifecycle.
+
 ## Definition of Done
 
 - related Issue or PR is linked;
@@ -247,6 +278,7 @@ Reviews, task reports, and handoffs must distinguish verified blocking High or C
 - changes are committed;
 - smoke tests were run or reason is documented;
 - PR description is updated;
+- blocking review findings have sufficient correction contracts and are verified or otherwise validly dispositioned before merge;
 - verified blocking High or Critical risks, time-boxed investigations, follow-up hardening, and owner-accepted risks are distinguished;
 - security and evidence work did not block acceptance or expand scope without a verified High or Critical current-scope risk or an exactly cited mandatory requirement;
 - handoff exists for meaningful work;

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Agent Handoff are documented here.
 
+## 1.5.1 - 2026-07-27
+
+### Why
+
+- Standard 1.5 defined when work and findings may block progress, but it did not define how a reviewer hands a blocking finding back to an implementation agent. A bare defect statement could cause clarification loops, accidental scope expansion, weakened invariants, or treatment of an implementation suggestion as a hidden acceptance criterion.
+
+### Added
+
+- `ai/REVIEW_PROTOCOL.md` with blocking, non-blocking, and question classifications.
+- A required blocking correction contract with stable finding ID, evidence, violated contract, cause confidence, required outcome, invariants, scope guard, applicable verification, and acceptance criteria.
+- Agent Handoff Review Correction Report mapped by finding ID.
+- Finding lifecycle `open -> addressed -> verified`, distinct from Pull Request labels.
+- Release notes in `docs/releases/v1.5.1.md`.
+
+### Changed
+
+- Implementation guidance is explicitly non-binding when an equivalent safe correction satisfies the required outcome, preserves invariants, remains inside the execution envelope, and provides the required evidence.
+- Root-cause confidence must be marked `confirmed`, `likely`, or `unknown`.
+- Positive, negative, security, and race tests are selected by applicability rather than required mechanically for every finding.
+- Agent-reported `addressed` status no longer implies reviewer verification or automatic review-thread resolution.
+- GitHub workflow, task reporting, handoff rules, Pull Request checklist, public documentation, and structural checks now cover the correction loop.
+
 ## 1.5 - 2026-07-26
 
 ### Why

CITATION.cff

@@ -4,8 +4,8 @@ title: "Agent Handoff: GitHub-native context handoff for AI coding agents"
 authors:
   - family-names: "Boyko"
     given-names: "Artyom"
-version: "1.5"
-date-released: 2026-07-26
+version: "1.5.1"
+date-released: 2026-07-27
 url: "https://github.com/artyomboyko/Agent_Handoff"
 repository-code: "https://github.com/artyomboyko/Agent_Handoff"
 license: "GPL-3.0-only"
@@ -19,6 +19,8 @@ keywords:
   - "handoff-protocol"
   - "outcome-oriented-execution"
   - "bounded-supporting-work"
+  - "actionable-review-handoff"
+  - "review-correction"
   - "proportionate-security"
   - "docker-compose"
   - "containerization"

FAQ.md

@@ -33,3 +33,11 @@ No by default. Use meaningful branch names and link Issues through Work Claim co
 Test harnesses, smoke wrappers, evidence collectors, CI scaffolding, and similar tools usually exist to enable or prove another outcome. Turning every localized failure into a separate stage, handoff, or approval cycle can advance the process without advancing that outcome.
 
 Agent Handoff therefore keeps reversible in-scope repairs and bounded post-fix verification inside the original execution envelope. The envelope records existing authorization and cannot be used by an agent to grant itself broader authority. A new owner decision is still required when the outcome, scope, architecture, accepted baseline, external effects, resource or risk boundary, security baseline, or enforced permission gate changes.
+
+## What makes a blocking review actionable for an agent?
+
+A blocking review gives each finding a stable ID and enough evidence, contract, outcome, invariant, scope, verification, and acceptance information for another agent to correct it without private chat history.
+
+The reviewer may recommend an implementation, but that recommendation is not a hidden acceptance criterion. An equivalent safe correction remains valid when it satisfies the required outcome, preserves invariants, stays inside the execution envelope, and provides the required evidence.
+
+An agent can report a finding as `addressed`; the reviewer or another authorized maintainer still verifies it before merge.

README.md

@@ -1,6 +1,6 @@
 # Agent Handoff
 
-[![Standard](https://img.shields.io/badge/standard-1.5-blue)](AGENT_HANDOFF_STANDARD.md)
+[![Standard](https://img.shields.io/badge/standard-1.5.1-blue)](AGENT_HANDOFF_STANDARD.md)
 [![Language](https://img.shields.io/badge/language-English-blue)](docs/en/README.md)
 [![GitHub native](https://img.shields.io/badge/GitHub-native-black)](ai/GITHUB_WORKFLOW.md)
 [![AI agent ready](https://img.shields.io/badge/AI%20agent-ready-purple)](ai/AGENT_IDENTITY.md)
@@ -65,6 +65,11 @@ Keep supporting work minimum sufficient. Fix localized reversible supporting-wor
 Do not create a separate stage, handoff, completion target, or owner approval gate for a supporting-tool failure alone.
 After two consecutive supporting-only updates without outcome progress, mark the work progress-stalled and replan the shortest path.
 
+When requesting changes in a Pull Request, classify findings as blocking, non-blocking, or questions.
+Give each blocking finding a stable ID and a sufficient correction contract: evidence or reproduction, violated contract, cause confidence, required outcome, preserved invariants, scope guard, applicable verification, and acceptance criteria.
+Treat implementation guidance as non-binding when an equivalent safe correction satisfies the outcome and invariants.
+Keep agent-reported addressed status separate from reviewer-verified resolution.
+
 Open a Pull Request and leave a compact handoff.
 ```
 
@@ -77,6 +82,7 @@ Open a Pull Request and leave a compact handoff.
 5. Humans stay in control of structural and migration decisions.
 6. Security and evidence work blocks or expands scope only for verified High or Critical current-scope risk or an exactly cited mandatory requirement.
 7. Supporting work stays subordinate to the primary outcome and its smallest acceptance proof.
+8. Blocking review findings carry sufficient correction contracts without prescribing one implementation unnecessarily.
 
 ## What is included
 
@@ -88,14 +94,15 @@ Open a Pull Request and leave a compact handoff.
 | Memory map | [ai/README.md](ai/README.md) |
 | Work claim | [ai/WORK_CLAIM_PROTOCOL.md](ai/WORK_CLAIM_PROTOCOL.md) |
 | Task reports | [ai/TASK_REPORT_PROTOCOL.md](ai/TASK_REPORT_PROTOCOL.md) |
+| Review corrections | [ai/REVIEW_PROTOCOL.md](ai/REVIEW_PROTOCOL.md) |
 | Agent identity | [ai/AGENT_IDENTITY.md](ai/AGENT_IDENTITY.md) |
 | Refactoring workflow | [ai/REFACTORING.md](ai/REFACTORING.md) |
 | Containerization | [ai/CONTAINERIZATION.md](ai/CONTAINERIZATION.md) |
 | Issue labels | [ISSUE_LABELS.md](ISSUE_LABELS.md) |
 | Issue status | [ISSUE_STATUS.md](ISSUE_STATUS.md) |
 | FAQ | [FAQ.md](FAQ.md) |
 | Examples | [examples/](examples/) |
-| Release notes | [docs/releases/v1.5.md](docs/releases/v1.5.md) |
+| Release notes | [docs/releases/v1.5.1.md](docs/releases/v1.5.1.md) |
 
 ## Comparison
 
@@ -109,15 +116,15 @@ Open a Pull Request and leave a compact handoff.
 
 ## Natural search terms
 
-Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, outcome-oriented execution, bounded supporting work, progress-stalled recovery, proportionate security, evidence scope, vertical slices, containerization decisions, Docker Compose organization, and human-agent collaboration.
+Agent Handoff is related to AI coding agents, Codex-like agents, ChatGPT coding workflows, Cursor, Claude Code, LLM agents, project context, agent memory, GitHub workflow, multi-agent development, handoff protocol, pull request workflow, actionable review handoff, review correction contract, outcome-oriented execution, bounded supporting work, progress-stalled recovery, proportionate security, evidence scope, vertical slices, containerization decisions, Docker Compose organization, and human-agent collaboration.
 
 ## For humans
 
 Use Agent Handoff to see who owns work, what changed, what was tested, what remains risky, and where the next contributor or agent should continue.
 
 ## For agents
 
-Start from `AGENTS.md`, read the required files, claim work in GitHub, record the primary outcome and execution envelope, keep supporting work subordinate, ask for required user decisions, keep security and evidence non-blocking unless a High or Critical current-scope risk is verified, open a Draft PR early, keep `ai/` compact, and leave a handoff only at a legitimate outcome boundary, blocker, interruption, or transfer.
+Start from `AGENTS.md`, read the required files, claim work in GitHub, record the primary outcome and execution envelope, keep supporting work subordinate, ask for required user decisions, keep security and evidence non-blocking unless a High or Critical current-scope risk is verified, use `ai/REVIEW_PROTOCOL.md` for blocking review corrections, open a Draft PR early, keep `ai/` compact, and leave a handoff only at a legitimate outcome boundary, blocker, interruption, or transfer.
 
 ## Repository visibility
 

ai/DECISIONS.md

@@ -2,7 +2,7 @@
 type: architecture_record
 version: 1
 status: active
-updated: 2026-07-26
+updated: 2026-07-27
 project: Agent_Handoff
 ---
 
@@ -95,6 +95,7 @@ Do not allow the agent to infer approval or automatically apply the recommended
 - `AGENT_HANDOFF_STANDARD.md`
 - `ai/CONTAINERIZATION.md`
 - `ai/HANDOFF_PROTOCOL.md`
+
 - `docs/en/README.md`
 
 ## 2026-07-18 — Stable GUI automation over position-dependent tests
@@ -214,3 +215,51 @@ A new owner decision remains required for changes to the outcome or acceptance c
 - `ai/WORK_CLAIM_PROTOCOL.md`
 - `ai/TASK_REPORT_PROTOCOL.md`
 - `ai/HANDOFF_PROTOCOL.md`
+
+## 2026-07-27 — Actionable review handoff without implementation lock-in
+
+Status: accepted in Standard 1.5.1
+
+### Background
+
+Standard 1.5 defined blocking eligibility, outcome progress, execution envelopes, and approval boundaries, but did not define the reviewer-to-agent correction handoff. A blocking comment could identify a defect without enough reproduction, contract, invariant, verification, or acceptance information for another agent to act independently.
+
+Requiring only a reviewer-proposed implementation would close the information gap by creating a different problem: it could turn guidance into an undocumented acceptance criterion and reject equally safe solutions.
+
+### Decision
+
+Require every blocking finding to carry a stable ID and a sufficient correction contract: evidence or reproduction, violated contract, cause confidence, required outcome, invariants and scope guard, minimum applicable verification, and observable acceptance criteria.
+
+Mark cause confidence as `confirmed`, `likely`, or `unknown`. Treat implementation guidance as optional and non-binding unless an exact mandatory requirement makes the choice normative.
+
+Allow equivalent corrections when they satisfy the required outcome, preserve the stated invariants, remain inside the execution envelope, and provide the required evidence.
+
+Keep finding state distinct from Pull Request state. The implementation agent may mark a finding `addressed`, but only the reviewer or another authorized maintainer marks it `verified`.
+
+Apply the complete contract only to blocking findings. Keep non-blocking findings and questions concise and explicitly classified.
+
+### Rejected alternatives
+
+- Require the full template for every nit, optional suggestion, or question.
+- Require every finding to have positive, negative, security, and race tests.
+- Treat a reviewer-recommended implementation as the only acceptable correction.
+- Let `addressed` automatically resolve a review thread.
+- Let a review finding widen the original authorization or Issue scope.
+- Add automated semantic scoring of review quality.
+
+### Consequences
+
+- Coding agents receive self-contained, verifiable correction tasks without private chat history.
+- Root-cause hypotheses are not represented as confirmed facts.
+- Architecture and security invariants remain explicit during correction.
+- Review cycles map finding IDs to changes, evidence, and independent verification.
+- Equivalent safe implementations remain possible.
+- The structural checker validates protocol fields but does not judge review semantics.
+
+### Related
+
+- Issue: #18
+- Pull Request: #19
+- `AGENT_HANDOFF_STANDARD.md`
+- `ai/REVIEW_PROTOCOL.md`
+- `ai/TASK_REPORT_PROTOCOL.md`