docs: document advance_phase auto-populate on plan exit [doc-updater]

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 `<!-- egg-pipeline-context ... -->` HTML comment and applies `egg` and `agent:orchestrator` labels to the PR — no agent is spawned for PR creation.
 

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 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).
@@ -256,7 +256,8 @@ curl -X POST http://egg-orchestrator:9849/api/v1/pipelines/<id>/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="<id>")
 # Via REST:
 curl -X POST http://egg-orchestrator:9849/api/v1/pipelines/<id>/phase/populate-contract