From b6c45067d067bfbbc51a89a39f17a0d9216cd015 Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Tue, 12 May 2026 22:05:35 +0000 Subject: [PATCH 1/3] docs: expand populate_contract error reason codes --- docs/reference/orchestrator-cli.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index f431e1a484..620aed00c2 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -286,7 +286,13 @@ All tools require `task_id` (the pipeline ID). Additional parameters: | `complete_phase` | `unresolved_hitl_decisions` | 409 | Phase has pending HITL decisions; `details.unresolved_decision_ids` lists them. Resolve or pass `force=true` | | `complete_phase` | `invalid_artifacts` | 400 | `artifacts` must be a JSON object with string values | | `complete_phase` | `invalid_force_reason` | 400 | `force_reason` must be a non-empty string | -| `populate_contract` | `populate_contract_failed` | 500 | Internal error during contract population | +| `populate_contract` | `draft_missing` | 404 | Plan draft missing from both local worktree and origin; re-run the plan phase or restore the draft file | +| `populate_contract` | `no_draft_path` | 404 | No draft path configured for this pipeline | +| `populate_contract` | `parse_failed` | 422 | Plan draft found but could not be parsed (malformed `yaml-tasks` section) | +| `populate_contract` | `empty_result` | 422 | Plan draft parsed successfully but produced no tasks | +| `populate_contract` | `contract_load_failed` | 500 | Contract could not be loaded after population | +| `populate_contract` | `egg_contracts_unavailable` | 500 | `egg_contracts` package unavailable in the sandbox | +| `populate_contract` | `unexpected_exception` | 500 | Unexpected internal error during contract population | | `advance_phase`, `start_phase`, `complete_phase`, `fail_phase` | `version_conflict` | 409 | Concurrent modification detected; retry the request | | all | `invalid_pipeline_id` | 400 | Pipeline ID format is invalid | | all | `pipeline_not_found` | 404 | No pipeline with that ID exists | From 906f7a5fdcc62edbbee57d5779d54d9a85e74677 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 22:23:19 +0000 Subject: [PATCH 2/3] docs: correct populate_contract reason-code descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address reviewer feedback on PR #2692: - draft_missing: scope description to the local worktree check that fires in _populate_contract_from_plan (the HTTP endpoint does not use the _safe wrapper, so the origin lookup never runs here). - contract_load_failed: load happens before population, not after. - egg_contracts_unavailable: import runs in the orchestrator process, not the agent sandbox. - parse_failed: broaden to cover empty plan documents and other parser-rejected inputs, not just malformed yaml-tasks. - empty_result: require no slices/tasks AND no PR metadata (changed= False); a draft yielding only a pr_title still comes back POPULATED. - forest_violation: add the row that was missing entirely; flag that the body key is error rather than reason so reason-only clients don't silently miss the case. - populate_contract_failed: keep the residual catch-all row — it is still live in routes/phases.py:1126 and fires for exceptions that escape the populator helper. - Lead-in: note the two cases that break the reason-field convention. --- docs/reference/orchestrator-cli.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/reference/orchestrator-cli.md b/docs/reference/orchestrator-cli.md index 620aed00c2..8c69469540 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -270,7 +270,7 @@ All tools require `task_id` (the pipeline ID). Additional parameters: - `force_reason` (string, optional) — audit note explaining why `force=true` was used. - **`populate_contract`**: No additional parameters. Resolves the pipeline's worktree path, reads the plan document, extracts task structure, and writes tasks and acceptance criteria to the contract. Returns phase and task counts on success. -**Error reason codes** (#1939): All four endpoints include a stable, machine-readable `reason` field in error responses. Switch on `reason` rather than parsing the human-readable `message`. Key codes: +**Error reason codes** (#1939): The four endpoints normally surface a stable, machine-readable `reason` field in error responses — switch on `reason` rather than parsing the human-readable `message`. Two cases break this convention and are noted inline in the table: `populate_contract`'s `forest_violation` 422 ships the structured errors under an `error` key (no `reason`), and the earlier 400-list shape returns a list of structured entries rather than a top-level `reason`. Key codes: | Endpoint | `reason` | HTTP | Meaning / fix | |----------|----------|------|---------------| @@ -286,13 +286,15 @@ All tools require `task_id` (the pipeline ID). Additional parameters: | `complete_phase` | `unresolved_hitl_decisions` | 409 | Phase has pending HITL decisions; `details.unresolved_decision_ids` lists them. Resolve or pass `force=true` | | `complete_phase` | `invalid_artifacts` | 400 | `artifacts` must be a JSON object with string values | | `complete_phase` | `invalid_force_reason` | 400 | `force_reason` must be a non-empty string | -| `populate_contract` | `draft_missing` | 404 | Plan draft missing from both local worktree and origin; re-run the plan phase or restore the draft file | +| `populate_contract` | `draft_missing` | 404 | Plan draft missing from the pipeline's local worktree at the configured draft path; re-run the plan phase or restore the file before retrying. The HTTP endpoint calls `_populate_contract_from_plan` directly, so this is a local-only check — the safe wrapper's extra origin lookup (which raises `PlanDraftMissingOnLocal{,AndOrigin}Error` instead) only applies to internal `source="plan_complete"` callers, not HTTP | | `populate_contract` | `no_draft_path` | 404 | No draft path configured for this pipeline | -| `populate_contract` | `parse_failed` | 422 | Plan draft found but could not be parsed (malformed `yaml-tasks` section) | -| `populate_contract` | `empty_result` | 422 | Plan draft parsed successfully but produced no tasks | -| `populate_contract` | `contract_load_failed` | 500 | Contract could not be loaded after population | -| `populate_contract` | `egg_contracts_unavailable` | 500 | `egg_contracts` package unavailable in the sandbox | -| `populate_contract` | `unexpected_exception` | 500 | Unexpected internal error during contract population | +| `populate_contract` | `parse_failed` | 422 | `parse_plan` returned `success=False` — e.g., empty plan document, missing or malformed `yaml-tasks` appendix, or other parser-rejected input | +| `populate_contract` | `empty_result` | 422 | Parse succeeded but produced no slices/tasks **and** no PR metadata (`changed=False`); a draft yielding only a `pr_title` would still come back as `POPULATED` | +| `populate_contract` | `forest_violation` | 422 | Plan emitted a multi-parent slice DAG (#2137). **Response body shape is `{"error": "forest_violation", "errors": [...]}` — note the key is `error`, not `reason`** (clients switching only on `reason` will miss this case). The structured errors are also stashed on `contract.plan_review_feedback` so the plan reviewer NACKs the planner | +| `populate_contract` | `contract_load_failed` | 500 | Existing contract on disk could not be loaded prior to population (the load happens first; if it fails the populator never runs) | +| `populate_contract` | `egg_contracts_unavailable` | 500 | `egg_contracts` package failed to import in the orchestrator process (the endpoint runs orchestrator-side, not in the agent sandbox) | +| `populate_contract` | `unexpected_exception` | 500 | Unexpected internal error inside the populator helper (`_populate_contract_from_plan`'s catch-all) | +| `populate_contract` | `populate_contract_failed` | 500 | Residual catch-all for exceptions that escape the populator helper itself — e.g., `get_state_store_for_pipeline` / `resolve_worktree_path` raise, or the dynamic `from routes.pipelines import …` fails. Normally pre-empted by one of the specific codes above | | `advance_phase`, `start_phase`, `complete_phase`, `fail_phase` | `version_conflict` | 409 | Concurrent modification detected; retry the request | | all | `invalid_pipeline_id` | 400 | Pipeline ID format is invalid | | all | `pipeline_not_found` | 404 | No pipeline with that ID exists | From 187b4fa4340c30162e65fada64944b6efcbf99c6 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 22:42:25 +0000 Subject: [PATCH 3/3] docs: drop phantom 400-list reference in reason-codes lead-in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The lead-in claimed two convention-breakers (forest_violation's error key and an earlier 400-list shape), but no row documented the 400-list case and no endpoint in orchestrator/routes/ returns one — every 400 goes through make_error_response with the standard {success, message, reason, details} shape. Reword to mention only the real exception (forest_violation). --- 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 8c69469540..9feb1869e2 100644 --- a/docs/reference/orchestrator-cli.md +++ b/docs/reference/orchestrator-cli.md @@ -270,7 +270,7 @@ All tools require `task_id` (the pipeline ID). Additional parameters: - `force_reason` (string, optional) — audit note explaining why `force=true` was used. - **`populate_contract`**: No additional parameters. Resolves the pipeline's worktree path, reads the plan document, extracts task structure, and writes tasks and acceptance criteria to the contract. Returns phase and task counts on success. -**Error reason codes** (#1939): The four endpoints normally surface a stable, machine-readable `reason` field in error responses — switch on `reason` rather than parsing the human-readable `message`. Two cases break this convention and are noted inline in the table: `populate_contract`'s `forest_violation` 422 ships the structured errors under an `error` key (no `reason`), and the earlier 400-list shape returns a list of structured entries rather than a top-level `reason`. Key codes: +**Error reason codes** (#1939): The four endpoints normally surface a stable, machine-readable `reason` field in error responses — switch on `reason` rather than parsing the human-readable `message`. One case breaks this convention and is noted inline in the table: `populate_contract`'s `forest_violation` 422 ships the structured errors under an `error` key (no `reason`). Key codes: | Endpoint | `reason` | HTTP | Meaning / fix | |----------|----------|------|---------------|