diff --git a/README.md b/README.md index a649aee5e7..84a44fe1f8 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ The pipeline creates a draft PR automatically when entering the implement phase. ### Human-in-the-Loop Checkpoints -At each phase boundary, the pipeline pauses for human approval before proceeding. Humans interact through checkbox-based UI in GitHub comments (issue mode) or terminal prompts (local mode): +At each phase boundary (refine and plan), the pipeline pauses for human approval before proceeding. Interaction happens through checkbox-based UI in GitHub comments (issue mode) or terminal prompts (local mode). In local mode, the orchestrator also supports requesting changes to re-run a phase with feedback (limited by `max_review_cycles`, default 3). - **Guidance**: Provide additional context, adjust acceptance criteria, break into subtasks - **Override**: Mark complete, skip tasks, cancel pipeline diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index ae6ca34b99..b30328088c 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -40,7 +40,7 @@ Code reviews are performed by the existing PR review workflow (`reusable-review. ### 4. Human-in-the-Loop at Critical Points -The pipeline pauses for human approval at phase transitions. Decisions use checkbox-based UI with 30-second debounce to prevent accidental clicks. +The pipeline pauses for human approval at phase transitions (refine and plan). In issue mode, the `sdlc-hitl.yml` workflow's `handle-approval` job processes checkbox-based approval. In local mode, the orchestrator's decision queue also supports requesting changes, with a circuit breaker (`max_review_cycles`, default 3) to prevent unbounded revision loops. ## Pipeline Architecture diff --git a/docs/hitl-decisions.md b/docs/hitl-decisions.md index 9666125e2e..f9fd970cc5 100644 --- a/docs/hitl-decisions.md +++ b/docs/hitl-decisions.md @@ -13,6 +13,8 @@ Three mechanisms exist for gathering human input: 2. **Feedback comments** — Open-ended questions in an editable comment 3. **Phase approval** — Single checkbox to approve and advance to the next phase +In local mode, the orchestrator's decision queue also supports a "request changes" option at phase gates, with a circuit breaker (`max_review_cycles`, default 3) to prevent unbounded revision loops. + ## Formal HITL Decisions Use formal decisions when you need the human to choose between predefined options. @@ -127,7 +129,7 @@ When you're done, check the box below to submit. ## Phase Approval -Phase approval is a simpler mechanism for advancing the pipeline. +Phase approval is a simpler mechanism for advancing the pipeline at HITL gates. ### Format @@ -144,12 +146,14 @@ Phase approval is a simpler mechanism for advancing the pipeline. ### How It Works -1. The agent includes this at the end of phase completion comments +1. The agent includes this at the end of phase completion comments (refine and plan phases) 2. The `` marker identifies the approval section 3. When the human checks the `[x] Approve` checkbox, GitHub triggers an edit event 4. The `sdlc-hitl.yml` workflow's `handle-approval` job detects this 5. The workflow updates the contract phase and triggers the next pipeline run +In **local mode**, the orchestrator handles phase approval via its decision queue, which also supports a "request changes" option with a circuit breaker (`max_review_cycles`, default 3) to prevent unbounded revision loops. + ### Key Differences from Decisions | Aspect | Formal Decisions | Phase Approval |