Improve autonomous review convergence

.agents/skills/recipe-add-integration-tests/SKILL.md

@@ -8,7 +8,8 @@ description: "Add integration/E2E tests to existing codebase using Design Docs."
 1. [LOAD IF NOT ACTIVE] `testing` — test strategy and quality gates
 2. [LOAD IF NOT ACTIVE] `integration-e2e-testing` — integration and E2E test patterns
 3. [LOAD IF NOT ACTIVE] `documentation-criteria` — document creation rules and templates
-4. [LOAD IF NOT ACTIVE] `llm-friendly-context` — clear prompts, handoffs, and generated artifacts
+4. [LOAD IF NOT ACTIVE] `subagents-orchestration-guide` — review revision convergence and agent coordination
+5. [LOAD IF NOT ACTIVE] `llm-friendly-context` — clear prompts, handoffs, and generated artifacts
 
 **Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context.
 
@@ -147,7 +148,7 @@ Keep `testsAdded` as reporting metadata only.
 
 Check Step 5 result:
 - `status: approved` -> Mark complete, proceed to Step 7
-- `status: needs_revision` -> Spawn the layer-appropriate executor with: "Fix the following issues in test files: [requiredFixes from Step 5]." Then return to Step 5. Maximum 2 revision cycles per task file; if still `needs_revision`, escalate to the user.
+- `status: needs_revision` -> Apply Review Revision Convergence (`author`: layer-appropriate executor; `artifact`: changed test files); on `progression`, proceed to Step 7.
 
 ### Step 7: Quality Check
 

.agents/skills/recipe-build/SKILL.md

@@ -78,8 +78,7 @@ Spawn document-reviewer agent: "Review the work plan before task decomposition.
 
 Branch on `verdict.decision`:
 - `approved` -> spawn work-planner in update mode once to record `Status: approved` and `Conditions: none` in WorkPlan Review, then continue to user confirmation
-- `approved_with_conditions` -> stop before task decomposition and report that the work plan needs update via recipe-plan
-- `needs_revision` -> stop before task decomposition and report that the work plan needs update via recipe-plan
+- `approved_with_conditions` or `needs_revision` -> apply Review Revision Convergence (`author`: work-planner; `artifact`: work plan); on `progression`, follow the `approved` branch
 - `rejected` -> stop before task decomposition and present the blocking findings to the user
 
 When task files don't exist and the WorkPlan Review section records `Status: approved` and `Conditions: none`, skip Work Plan Review and continue to user confirmation.
@@ -118,7 +117,7 @@ For EACH task, YOU MUST:
 3. **CHECK task-executor response**:
    - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user
    - `requiresTestReview` is `true` -> Spawn integration-test-reviewer agent with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile: [task-file-path]`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`
-     - `needs_revision` -> Return to step 2 with `requiredFixes`
+     - `needs_revision` -> Apply Review Revision Convergence (`author`: task-executor; `artifact`: changed test files); on `progression`, proceed to step 4
      - `approved` -> Proceed to step 4
      - `blocked` or unrecognized status -> STOP and escalate to user
    - `readyForQualityCheck: true` -> Proceed to step 4

.agents/skills/recipe-front-build/SKILL.md

@@ -78,8 +78,7 @@ Spawn document-reviewer agent: "Review the frontend work plan before task decomp
 
 Branch on `verdict.decision`:
 - `approved` -> spawn work-planner in update mode once to record `Status: approved` and `Conditions: none` in WorkPlan Review, then continue to user confirmation
-- `approved_with_conditions` -> stop before task decomposition and report that the work plan needs update via recipe-front-plan
-- `needs_revision` -> stop before task decomposition and report that the work plan needs update via recipe-front-plan
+- `approved_with_conditions` or `needs_revision` -> apply Review Revision Convergence (`author`: work-planner; `artifact`: work plan); on `progression`, follow the `approved` branch
 - `rejected` -> stop before task decomposition and present the blocking findings to the user
 
 When task files don't exist and the WorkPlan Review section records `Status: approved` and `Conditions: none`, skip Work Plan Review and continue to user confirmation.
@@ -126,7 +125,7 @@ For EACH task, YOU MUST:
 3. **CHECK task-executor-frontend response**:
    - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user
    - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`
-     - `needs_revision` -> Return to step 2 with `requiredFixes`
+     - `needs_revision` -> Apply Review Revision Convergence (`author`: task-executor-frontend; `artifact`: changed test files); on `progression`, proceed to step 4
      - `approved` -> Proceed to step 4
      - `blocked` or unrecognized status -> STOP and escalate to user
    - `readyForQualityCheck: true` -> Proceed to step 4

.agents/skills/recipe-front-plan/SKILL.md

@@ -60,7 +60,7 @@ Spawn document-reviewer agent: "Review the frontend work plan. doc_type: WorkPla
 
 Branch on `verdict.decision`:
 - `approved` -> spawn work-planner in update mode once to record `Status: approved` and `Conditions: none` in WorkPlan Review, then proceed to Step 5
-- `approved_with_conditions` or `needs_revision` -> spawn work-planner in update mode with the findings or conditions, then repeat Step 4. Use max 2 revision iterations as defined by the `needs_revision` row in subagents-orchestration-guide Approval Status Vocabulary.
+- `approved_with_conditions` or `needs_revision` -> apply Review Revision Convergence (`author`: work-planner; `artifact`: work plan); on `progression`, follow the `approved` branch
 - `rejected` -> stop and present the blocking findings to the user.
 
 ### Step 5: Plan Approval

.agents/skills/recipe-fullstack-build/SKILL.md

@@ -88,8 +88,7 @@ Spawn document-reviewer agent: "Review the fullstack work plan before task decom
 
 Branch on `verdict.decision`:
 - `approved` -> spawn work-planner in update mode once to record `Status: approved` and `Conditions: none` in WorkPlan Review, then continue to user confirmation
-- `approved_with_conditions` -> stop before task decomposition and report that the work plan needs update via recipe-plan or the fullstack planning flow
-- `needs_revision` -> stop before task decomposition and report that the work plan needs update via recipe-plan or the fullstack planning flow
+- `approved_with_conditions` or `needs_revision` -> apply Review Revision Convergence (`author`: work-planner; `artifact`: work plan); on `progression`, follow the `approved` branch
 - `rejected` -> stop before task decomposition and present the blocking findings to the user
 
 When task files don't exist and the WorkPlan Review section records `Status: approved` and `Conditions: none`, skip Work Plan Review and continue to user confirmation.
@@ -136,7 +135,7 @@ For EACH task, YOU MUST:
 3. **CHECK executor response**:
    - `status: "escalation_needed"` or `"blocked"` -> STOP and escalate to user
    - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with `changedTestFiles: [integration/E2E paths from filesModified]`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`
-     - `needs_revision` -> Return to step 2 with `requiredFixes`
+     - `needs_revision` -> Apply Review Revision Convergence (`author`: layer-appropriate executor; `artifact`: changed test files); on `progression`, proceed to step 4
      - `approved` -> Proceed to step 4
      - `blocked` or unrecognized status -> STOP and escalate to user
    - `readyForQualityCheck: true` -> Proceed to step 4

.agents/skills/recipe-implement/SKILL.md

@@ -114,7 +114,7 @@ Before the first task, call `update_plan` once with first "Map active rules to t
 2. Check task-executor response:
    - `status: escalation_needed` or `blocked` -> Escalate to user
    - `requiresTestReview` is `true` -> Spawn integration-test-reviewer with changed integration/E2E paths from `filesModified`, `diffBase`, and `taskFile`; when matching integration/E2E skeleton paths are available from acceptance-test-generator output or task/work-plan references, pass only those paths as `skeletonFiles`
-     - `needs_revision` -> Return to step 1 with `requiredFixes`
+     - `needs_revision` -> Apply Review Revision Convergence (`author`: layer-appropriate executor; `artifact`: changed test files); on `progression`, proceed to step 3
      - `approved` -> Proceed to step 3
      - `blocked` or unrecognized status -> Escalate to user
    - Otherwise -> Proceed to step 3

.agents/skills/recipe-plan/SKILL.md

@@ -63,7 +63,7 @@ Spawn document-reviewer agent: "Review the work plan. doc_type: WorkPlan. target
 
 Branch on `verdict.decision`:
 - `approved` -> spawn work-planner in update mode once to record `Status: approved` and `Conditions: none` in WorkPlan Review, then proceed to Step 5
-- `approved_with_conditions` or `needs_revision` -> spawn work-planner in update mode with the findings or conditions, then repeat Step 4. Use max 2 revision iterations as defined by the `needs_revision` row in subagents-orchestration-guide Approval Status Vocabulary.
+- `approved_with_conditions` or `needs_revision` -> apply Review Revision Convergence (`author`: work-planner; `artifact`: work plan); on `progression`, follow the `approved` branch
 - `rejected` -> stop and present the blocking findings to the user.
 
 ### Step 5: Plan Approval

.agents/skills/recipe-reverse-engineer/SKILL.md

@@ -108,21 +108,17 @@ Spawn document-reviewer agent: "Review the following PRD considering code verifi
 
 **Store output as**: `$STEP_4_OUTPUT`
 
-#### Step 5: Revision (conditional)
-
-**Trigger Conditions** (any one of the following):
-- Review status is "Needs Revision" or "Rejected"
-- Critical discrepancies exist in `$STEP_3_OUTPUT`
-- consistencyScore < 70
+If `verdict.decision` is `rejected`, halt the current unit and escalate the blocking findings to the user.
 
-Spawn prd-creator agent: "Update PRD based on review feedback and code verification results. Operation Mode: update. Existing PRD: $STEP_2_OUTPUT. Review Feedback: $STEP_4_OUTPUT. Code Verification Results: $STEP_3_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale."
+#### Step 5: Revision (conditional)
 
-**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status.
-ENFORCEMENT: Exceeding 2 revision cycles without flagging produces unreviewed output.
+- If `verdict.decision` is `needs_revision`, apply Review Revision Convergence (`author`: prd-creator; `artifact`: `$STEP_2_OUTPUT`); on `progression`, retain its final review as the current review and evaluate the next bullet.
+- If the current review permits progression and critical discrepancies exist in `$STEP_3_OUTPUT` or consistencyScore < 70, spawn prd-creator once: "Update PRD based on code verification results. Operation Mode: update. Existing PRD: $STEP_2_OUTPUT. Code Verification Results: $STEP_3_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale." Then re-run Step 4 and route the new verdict only; this verification-triggered correction runs once per unit.
+- After the applicable revision bullets complete, continue to Unit Completion.
 
 #### Unit Completion
 
-- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] `verdict.decision` is `approved` or `approved_with_conditions`
 - [ ] Human review passed (if enabled in Step 0)
 
 **Next**: Proceed to next unit. After all units -> Phase 2.
@@ -215,20 +211,17 @@ Spawn document-reviewer agent: "Review the following Design Doc considering code
 
 **Store output as**: `$STEP_9_OUTPUT`
 
-#### Step 10: Revision (conditional)
-
-**Trigger Conditions** (same as Step 5):
-- Review status is "Needs Revision" or "Rejected"
-- Critical discrepancies exist in `$STEP_8_OUTPUT`
-- consistencyScore < 70
+If `verdict.decision` is `rejected`, halt the current unit and escalate the blocking findings to the user.
 
-Spawn technical-designer agent: "Update Design Doc based on review feedback and code verification results. Operation Mode: update. Existing Design Doc: $STEP_7_OUTPUT. Review Feedback: $STEP_9_OUTPUT. Code Verification Results: $STEP_8_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale."
+#### Step 10: Revision (conditional)
 
-**Loop Control**: Maximum 2 revision cycles. After 2 cycles, flag for human review regardless of status.
+- If `verdict.decision` is `needs_revision`, apply Review Revision Convergence (`author`: technical-designer; `artifact`: `$STEP_7_OUTPUT`); on `progression`, retain its final review as the current review and evaluate the next bullet.
+- If the current review permits progression and critical discrepancies exist in `$STEP_8_OUTPUT` or consistencyScore < 70, spawn technical-designer once: "Update Design Doc based on code verification results. Operation Mode: update. Existing Design Doc: $STEP_7_OUTPUT. Code Verification Results: $STEP_8_OUTPUT. Address discrepancies by severity. Critical and major items require correction. Minor items: correct if straightforward, otherwise leave as-is with rationale." Then re-run Step 9 and route the new verdict only; this verification-triggered correction runs once per unit.
+- After the applicable revision bullets complete, continue to Unit Completion.
 
 #### Unit Completion
 
-- [ ] Review status is "Approved" or "Approved with Conditions"
+- [ ] `verdict.decision` is `approved` or `approved_with_conditions`
 - [ ] Human review passed (if enabled in Step 0)
 
 **Next**: Proceed to next unit. After all units -> Final Report.
@@ -247,7 +240,7 @@ Output summary including:
 | Discovery finds nothing | Ask user for project structure hints |
 | Generation fails | Log failure, continue with other units, report in summary |
 | consistencyScore < 50 | **[STOP — BLOCKING]** Flag for mandatory human review. **CANNOT proceed until user explicitly confirms.** |
-| Review rejects after 2 revisions | Stop loop, flag for human intervention |
+| Review Revision Convergence returns `non_convergent` | Stop the unit loop, present the exact unresolved findings and attempted corrections, then wait |
 
 ## Completion Criteria
 

.agents/skills/recipe-update-doc/SKILL.md

@@ -124,16 +124,11 @@ Spawn document-reviewer agent: "Review the following updated document. doc_type:
 
 **Store output as**: `$STEP_5_OUTPUT`
 
-**[STOP — BLOCKING]** Present review results to user for approval.
-**CANNOT proceed until user explicitly confirms.**
-
 **On review result**:
-- Approved -> Proceed to Step 6
-- Needs revision -> Return to Step 4 with review feedback (max 2 iterations):
-  Spawn [Update Agent from Step 2] agent: "Operation Mode: update. Existing Document: [path from Step 1]. Review Feedback to Address: $STEP_5_OUTPUT. Address each issue raised in the review feedback."
-- **After 2 rejections** -> Flag for human review, present accumulated feedback to user and end
-
-Present review result to user for approval.
+- `approved` -> **[STOP — BLOCKING]** Present review results to the user and proceed to Step 6 only after explicit approval
+- `approved_with_conditions` -> Apply the Approval Status Vocabulary conditions handling, then **[STOP — BLOCKING]** present the result and proceed to Step 6 only after explicit approval
+- `needs_revision` -> Apply Review Revision Convergence (`author`: [Update Agent from Step 2]; `artifact`: target document); on `progression`, follow the matching approved branch
+- `rejected` -> **[STOP — BLOCKING]** Present the exact blocking findings and required user decision, then wait
 
 ### Step 6: Consistency Verification (Design Doc only) [Stop]
 
@@ -156,7 +151,7 @@ For Design Doc, spawn design-sync agent: "Verify consistency of the updated Desi
 |-------|--------|
 | Target document not found | Report and end (suggest $recipe-design instead) |
 | Sub-agent update fails | Log failure, present error to user, retry once |
-| Review rejects after 2 revisions | Stop loop, flag for human intervention |
+| Review Revision Convergence returns `non_convergent` | Stop the loop, present the exact unresolved findings and attempted corrections, then wait |
 | design-sync detects conflicts | Present to user for resolution decision |
 
 ## Completion Criteria