From 7bcdfc3cb66bc330f280997123ea7030a01b03d7 Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Thu, 23 Apr 2026 22:39:22 +0000 Subject: [PATCH 1/2] docs: document advance_phase auto-populate on plan exit Authored-by: egg --- docs/guides/sdlc-pipeline.md | 2 +- docs/reference/orchestrator-cli.md | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 6220089d70..63717b2f44 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -851,7 +851,7 @@ The orchestrator's pipeline routes (`orchestrator/routes/pipelines.py`): 4. Validates the contract against the JSON schema 5. Commits the updated contract to the feature branch -This happens in the plan phase itself (before human approval) to provide early validation of the plan format. The implement phase also runs task population as a fallback in case the plan phase step failed or was skipped. +This happens in the plan phase itself (before human approval) to provide early validation of the plan format. The implement phase also runs task population as a fallback in case the plan phase step failed or was skipped. For manual recovery via `advance_phase`, the populate step is also run automatically when transitioning out of the plan phase, so `contract.pr` is populated even when a force-advance bypasses the normal phase completion path. The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to auto-create the PR when the implement phase completes. The orchestrator builds the PR body from the contract's `pr` metadata, the git commit log, diff stats, and a Pipeline Context section (pipeline ID and issue number). The gateway injects a machine-parseable `` HTML comment and applies `egg` and `agent:orchestrator` labels to the PR — no agent is spawned for PR creation. diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index 91bd5fe2e6..c3afb5e91a 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -227,7 +227,7 @@ Four MCP tools expose phase management operations for pipeline recovery and manu | MCP Tool | REST Endpoint | Description | |----------|---------------|-------------| -| `advance_phase` | `POST /pipelines/{id}/phase` | Advance pipeline to a target phase. With `force=true`, stops running containers first to prevent SIGTERM cascading | +| `advance_phase` | `POST /pipelines/{id}/phase` | Advance pipeline to a target phase. With `force=true`, stops running containers first to prevent SIGTERM cascading. When leaving the plan phase, automatically populates the contract from the plan draft | | `start_phase` | `POST /pipelines/{id}/phase/start` | Start the current phase (spawns agents). Use when a phase is in state but no containers are running | | `complete_phase` | `POST /pipelines/{id}/phase/complete` | Mark a phase as complete. Use when automatic transition is stuck. Returns 409 if the phase has unresolved HITL decisions; pass `force=true` to abandon them | | `populate_contract` | `POST /pipelines/{id}/phase/populate-contract` | Populate contract from plan artifacts. Parses yaml-tasks from the plan draft into contract phases/tasks | @@ -236,7 +236,7 @@ Four MCP tools expose phase management operations for pipeline recovery and manu All tools require `task_id` (the pipeline ID). Additional parameters: -- **`advance_phase`**: `target_phase` (string, required) — the phase to advance to (e.g., `"plan"`, `"implement"`, `"pr"`). `force` (boolean, optional, default `false`) — skip validation and stop running containers before advancing. **Important:** When `force=true`, containers from the current phase are stopped before the transition to prevent their SIGTERM signals from being misinterpreted as failures in the new phase. +- **`advance_phase`**: `target_phase` (string, required) — the phase to advance to (e.g., `"plan"`, `"implement"`, `"pr"`). `force` (boolean, optional, default `false`) — skip validation and stop running containers before advancing. **Important:** When `force=true`, containers from the current phase are stopped before the transition to prevent their SIGTERM signals from being misinterpreted as failures in the new phase. When the current phase is `plan`, `advance_phase` automatically runs the contract populate step (parsing the plan's `yaml-tasks` appendix into `contract.pr`), so a separate `populate_contract` call is not needed for plan→implement transitions. - **`start_phase`**: No additional parameters. - **`complete_phase`**: `artifacts` (object, optional) — phase completion artifacts to store (e.g., commit SHAs, PR URLs). - Returns 409 when the current phase has unresolved HITL decisions (both orchestrator-side and contract-side decisions scoped to the phase are checked). @@ -256,7 +256,8 @@ curl -X POST http://egg-orchestrator:9849/api/v1/pipelines//phase \ -H "Content-Type: application/json" \ -d '{"target_phase": "implement", "force": true}' -# 3. Populate contract if it's empty after manual phase setup +# 3. Populate contract if it's still empty (automatic when advancing from plan; +# needed for other phase transitions where the plan was set up externally) # Via MCP tool: populate_contract(task_id="") # Via REST: curl -X POST http://egg-orchestrator:9849/api/v1/pipelines//phase/populate-contract From 7cb9651a9a0a38a4c17f383fc8aa949ab2922a68 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Thu, 23 Apr 2026 22:50:01 +0000 Subject: [PATCH 2/2] docs: clarify populate step writes phases/tasks and contract.pr --- docs/reference/orchestrator-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index c3afb5e91a..e8960cb0da 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -236,7 +236,7 @@ Four MCP tools expose phase management operations for pipeline recovery and manu All tools require `task_id` (the pipeline ID). Additional parameters: -- **`advance_phase`**: `target_phase` (string, required) — the phase to advance to (e.g., `"plan"`, `"implement"`, `"pr"`). `force` (boolean, optional, default `false`) — skip validation and stop running containers before advancing. **Important:** When `force=true`, containers from the current phase are stopped before the transition to prevent their SIGTERM signals from being misinterpreted as failures in the new phase. When the current phase is `plan`, `advance_phase` automatically runs the contract populate step (parsing the plan's `yaml-tasks` appendix into `contract.pr`), so a separate `populate_contract` call is not needed for plan→implement transitions. +- **`advance_phase`**: `target_phase` (string, required) — the phase to advance to (e.g., `"plan"`, `"implement"`, `"pr"`). `force` (boolean, optional, default `false`) — skip validation and stop running containers before advancing. **Important:** When `force=true`, containers from the current phase are stopped before the transition to prevent their SIGTERM signals from being misinterpreted as failures in the new phase. When the current phase is `plan`, `advance_phase` automatically runs the contract populate step (parsing the plan's `yaml-tasks` appendix into the contract (phases, tasks, and `contract.pr` metadata)), so a separate `populate_contract` call is not needed for plan→implement transitions. - **`start_phase`**: No additional parameters. - **`complete_phase`**: `artifacts` (object, optional) — phase completion artifacts to store (e.g., commit SHAs, PR URLs). - Returns 409 when the current phase has unresolved HITL decisions (both orchestrator-side and contract-side decisions scoped to the phase are checked).