From 230aa0104184e83c8d30f0c998025058d0aef5d2 Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Sun, 8 Feb 2026 08:40:46 +0000 Subject: [PATCH] docs: Update SDLC pipeline docs with HITL workflow references Update docs/guides/sdlc-pipeline.md: - Add reference to hitl-decisions.md documentation - Add --format markdown option to add-decision CLI example - Add Phase Completion Comments section referencing the template Update docs/adr/implemented/ADR-SDLC-Pipeline.md: - Add reference to hitl-decisions.md documentation - Add Phase Approval section explaining the mechanism - Update Files and Locations table with new files Authored-by: egg --- docs/adr/implemented/ADR-SDLC-Pipeline.md | 14 +++++++++++- docs/architecture/README.md | 2 +- docs/development/STRUCTURE.md | 12 ++++++++++ docs/guides/sdlc-pipeline.md | 27 +++++++++++++++-------- docs/index.md | 7 ++++++ 5 files changed, 51 insertions(+), 11 deletions(-) diff --git a/docs/adr/implemented/ADR-SDLC-Pipeline.md b/docs/adr/implemented/ADR-SDLC-Pipeline.md index 1928af97c5..f6131182d7 100644 --- a/docs/adr/implemented/ADR-SDLC-Pipeline.md +++ b/docs/adr/implemented/ADR-SDLC-Pipeline.md @@ -205,6 +205,8 @@ This functionality has been replaced by the PR-based review workflow, which prov ## HITL (Human-in-the-Loop) Mechanism +For detailed HITL workflow documentation, see [HITL Decisions](../../hitl-decisions.md). + When escalation occurs, the system generates a decision block with checkboxes for human input. ### Checkbox Categories @@ -220,6 +222,14 @@ A 30-second debounce prevents accidental clicks: - Decision is processed only after debounce expires - Comment is updated with countdown status +### Phase Approval + +In addition to formal HITL decisions, a simpler phase approval mechanism exists for advancing between phases: +- Uses `` markers in comments +- Single checkbox: `- [ ] Approve and advance to next phase` +- Detected by the `handle-approval` job in `sdlc-hitl.yml` +- See [Phase Completion Template](../../templates/phase-completion.md) for the comment format + --- ## Gateway Integration @@ -338,7 +348,9 @@ Long-running jobs checkpoint state before timeout: | CLI tools | `sandbox/egg_lib/contract_cli.py` | | PR review workflow | `.github/workflows/reusable-review.yml` | | Workflow files | `.github/workflows/sdlc-*.yml` | -| Templates | `docs/templates/analysis.md`, `docs/templates/plan.md` | +| Templates | `docs/templates/analysis.md`, `docs/templates/plan.md`, `docs/templates/phase-completion.md` | +| HITL documentation | `docs/hitl-decisions.md` | +| HITL integration tests | `tests/workflows/test_hitl_integration.py` | --- diff --git a/docs/architecture/README.md b/docs/architecture/README.md index d28eaa7aaf..e5e03546a0 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -68,7 +68,7 @@ Agents interact with contract state via the `egg-contract` CLI (`sandbox/egg_lib | `egg-contract update-notes --task --notes ` | Add implementation notes | | `egg-contract mark-task --task --status ` | Mark task status (deprecated as of PR #285) | | `egg-contract mark-phase --phase --passed ` | Mark phase status (deprecated as of PR #285) | -| `egg-contract add-decision --question [--options ...]` | Create HITL decision point, optionally with predefined choices | +| `egg-contract add-decision --question [--options ...] [--format {json,markdown}]` | Create HITL decision point with optional predefined choices and markdown output format for GitHub comments | ### Plan Parser diff --git a/docs/development/STRUCTURE.md b/docs/development/STRUCTURE.md index cf3fff40a2..b6223fef64 100644 --- a/docs/development/STRUCTURE.md +++ b/docs/development/STRUCTURE.md @@ -122,6 +122,18 @@ integration_tests/ └── test_role_enforcement.py # Role-based mutation enforcement ``` +## Unit Tests Structure + +``` +tests/ +├── sandbox/ # Sandbox component tests +│ ├── test_contract_cli.py # Contract CLI tests +│ └── ... +└── workflows/ # Workflow integration tests + ├── __init__.py + └── test_hitl_integration.py # HITL decision format verification +``` + ## Action Directory ``` diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 1fbdc82b56..522fb177f1 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -205,24 +205,26 @@ This functionality has been replaced by the PR-based review workflow, which prov ## Human-in-the-Loop Decisions +For detailed documentation on HITL workflows, see [HITL Decisions](../hitl-decisions.md). + ### Checkbox-Based Interface -HITL decisions render as checkboxes in bot comments: +HITL decisions render as checkboxes in bot comments. The `` marker identifies each decision: ```markdown ## Human Decision Required -### Option 1: Provide Guidance - -- [ ] I will provide additional context or requirements below -- [ ] The acceptance criteria should be adjusted -- [ ] Break this task into smaller sub-tasks + -### Option 2: Override - +**How should we proceed with this task?** + +- [ ] Provide additional context or requirements below +- [ ] Adjust the acceptance criteria +- [ ] Break this task into smaller sub-tasks - [ ] Mark current tasks as complete (override review) - [ ] Skip remaining tasks in this phase - [ ] Cancel the pipeline for this issue +- [ ] Other (explain in reply) ``` ### Debounce Mechanism @@ -304,6 +306,10 @@ Template sections: - [TASK-1-2] Add role validation — Acceptance: Unauthorized mutations rejected ``` +### Phase Completion Comments + +When a phase is complete and ready for human approval, agents post a comment using the [Phase Completion Template](../templates/phase-completion.md). This format includes the `` marker which the HITL workflow uses to detect approval checkbox changes. + ### Task Population Tasks are automatically extracted from the plan document and populated into the contract during the plan phase, after the plan document is validated. @@ -363,8 +369,11 @@ egg-contract add-commit --task task-1-1 --commit abc1234 # Add implementation notes (implementer) egg-contract update-notes --task task-1-1 --notes "Completed validation" -# Create HITL decision point +# Create HITL decision point (plain text) egg-contract add-decision --question "Should we proceed with approach X?" + +# Create HITL decision point with markdown checkbox format (for GitHub comments) +egg-contract add-decision --question "Which approach?" --options "A" "B" --format markdown ``` **Note:** `mark-task` and `mark-phase` commands (previously used by the dedicated reviewer agent) are deprecated as of PR #285. Task validation now happens via PR-based code review. diff --git a/docs/index.md b/docs/index.md index 428cdc2b5a..9b1ef24b84 100644 --- a/docs/index.md +++ b/docs/index.md @@ -55,6 +55,13 @@ This index helps both humans and LLMs navigate the documentation efficiently. |----------|-------------| | [Analysis Template](templates/analysis.md) | Problem analysis template for the refine phase | | [Plan Template](templates/plan.md) | Implementation plan template with task ID format for the plan phase | +| [Phase Completion Template](templates/phase-completion.md) | Phase completion comment format with approval checkbox | + +### SDLC Workflow Documentation + +| Document | Description | +|----------|-------------| +| [HITL Decisions](hitl-decisions.md) | Human-in-the-loop decision workflow with formal decisions and phase approvals | ## Component Documentation