From 183ee97463d7ef50b58288911e45469fc0710157 Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Sat, 30 May 2026 21:45:07 +0000 Subject: [PATCH 1/6] docs: update pipeline docs for PR-phase removal (#2777) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove all references to the deprecated PR phase from README.md, docs/architecture/sdlc-pipeline.md, and docs/guides/sdlc-pipeline.md. IMPLEMENT is now the terminal phase. The context PR opens automatically at the plan→implement boundary via _open_context_pr_at_implement_start. Schema bumped to 1.2 (removes context_branch/context_title/context_description from PRMetadata; context_pr_number survives). Authored-by: egg --- README.md | 21 ++---- docs/architecture/sdlc-pipeline.md | 73 +++++++-------------- docs/guides/sdlc-pipeline.md | 101 ++++++++++++++--------------- 3 files changed, 81 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 4dd4c5ee94..9e6eef39be 100644 --- a/README.md +++ b/README.md @@ -93,17 +93,17 @@ The overseer is phase-scoped: it is spawned at the start of each pipeline phase egg structures work into phases with mandatory human gates: ``` -┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────┐ -│ REFINE │─────▶│ PLAN │─────▶│ IMPLEMENT │─────▶│ PR │ -└────┬─────┘ └────┬─────┘ └──────────────┘ └────┬─────┘ - │ │ │ -Human gate Human gate Human merge +┌──────────┐ ┌──────────┐ ┌─────────────────────────────────────┐ +│ REFINE │─────▶│ PLAN │─────▶│ IMPLEMENT │ +└────┬─────┘ └────┬─────┘ └─────────────────────────────────────┘ + │ │ │ │ +Human gate Human gate Context PR opened Human merges + at phase start slice PRs ``` 1. **Refine**: Agents analyze the task, research the codebase, produce requirements. Reviewers validate. Human approves before planning. 2. **Plan**: Architect recommends approach, task planner breaks it into discrete tasks with acceptance criteria, risk analyst flags concerns. Human approves before any code is written. -3. **Implement**: The plan's tasks are split into a **DAG of independent slices** — each slice runs as its own agent team on its own integration branch with its own BRC consensus and stacked PR. Slices whose dependencies are satisfied run concurrently (up to `EGG_ORCH_MAX_PARALLEL_SLICES`, default 2 per pipeline; a separate `EGG_ORCH_GLOBAL_MAX_PARALLEL_SLICES` cap, default 4, bounds the total across all running pipelines); slices with unmet dependencies wait in subsequent waves. Within each slice, the coder writes code, the tester writes regression tests and adversarially probes the coder's implementation for bugs (NACKing with failing tests as bug reports), and the documenter updates docs. Code and contract reviewers provide line-level feedback; security and concurrency lens reviewers add targeted cross-file analysis and block consensus on a NACK. Cycles continue until all checks pass and BRC consensus is reached for that slice. See [Slice-DAG Implement Phase](docs/architecture/slice-dag.md) for the full model. -4. **PR**: Orchestrator auto-creates the PR from plan metadata. Only a human can merge via GitHub UI. +3. **Implement**: The plan's tasks are split into a **DAG of independent slices** — each slice runs as its own agent team on its own integration branch with its own BRC consensus and stacked PR. Slices whose dependencies are satisfied run concurrently (up to `EGG_ORCH_MAX_PARALLEL_SLICES`, default 2 per pipeline; a separate `EGG_ORCH_GLOBAL_MAX_PARALLEL_SLICES` cap, default 4, bounds the total across all running pipelines); slices with unmet dependencies wait in subsequent waves. Within each slice, the coder writes code, the tester writes regression tests and adversarially probes the coder's implementation for bugs (NACKing with failing tests as bug reports), and the documenter updates docs. Code and contract reviewers provide line-level feedback; security and concurrency lens reviewers add targeted cross-file analysis and block consensus on a NACK. Cycles continue until all checks pass and BRC consensus is reached for that slice. See [Slice-DAG Implement Phase](docs/architecture/slice-dag.md) for the full model. A context PR (`egg//work → main`) is opened automatically at the plan→implement boundary; slice PRs stack on it. Only a human can merge via GitHub UI. For **Jira epic-mode pipelines** (when `jira_ticket` resolves to a Jira Epic), an **Apply** phase is inserted between Plan and Implement: the `applier` role drives Jira mutations (epic Description writes, child ticket creates/edits, link creates, Won't-Do handoffs) on operator approval, before code implementation begins. Pass `mode='fresh'` (no existing children) or `mode='reassess'` (existing children to classify) to `submit_task`; `mode='auto'` (default) detects which to use at submit time. @@ -139,13 +139,6 @@ Within each phase, specialized agents run concurrently via BRC (enabled by defau │ ✓ reviewer_security ✓ reviewer_concurrency │ │ [1h11m] │ ╚═══════════════════════════════════════════════╝ - │ - ▼ -╔════════════╗ -│ ✓ PR │ -│ complete │ -│ [2s] │ -╚════════════╝ ``` ## Architecture diff --git a/docs/architecture/sdlc-pipeline.md b/docs/architecture/sdlc-pipeline.md index e712d44522..30ba0da419 100644 --- a/docs/architecture/sdlc-pipeline.md +++ b/docs/architecture/sdlc-pipeline.md @@ -9,7 +9,7 @@ For operational details, CLI commands, and triggering instructions, see the [SDL **The core guarantee**: An agent cannot bypass verification gates or self-approve its own work. All state transitions are enforced structurally through role-based mutations and gateway policy enforcement. **Key properties:** -- **Phased execution**: Work progresses through defined phases (refine → plan → implement → pr) +- **Phased execution**: Work progresses through defined phases (refine → plan → implement); implement is terminal — the context PR opens at the plan→implement boundary - **Role-based control**: Implementer, Reviewer, and Human roles have distinct permissions - **Human-in-the-loop**: Critical transitions pause for human approval - **Audit trail**: All mutations are logged for accountability @@ -39,10 +39,11 @@ This architecture implements **structural enforcement**: the agent physically ca ┌─────────────────────────────────────────────────────────────────────────┐ │ SDLC Pipeline │ │ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │ -│ │ Refine │───▶│ Plan │───▶│ Implement │───▶│ PR │ │ -│ │ (Human) │ │ (Human) │ │ (Reviewer) │ │ (Human) │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ └──────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │ +│ │ Refine │───▶│ Plan │───▶│ Implement │ │ +│ │ (Human) │ │ (Human) │ │ (Reviewer; context PR │ │ +│ └─────────────┘ └─────────────┘ │ opened at phase start) │ │ +│ └─────────────────────────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ @@ -65,8 +66,7 @@ This architecture implements **structural enforcement**: the agent physically ca |-------|---------|---------------| | **refine** | Problem analysis and requirements gathering | Human approval | | **plan** | Implementation planning with task breakdown | Human approval | -| **implement** | Task execution and code changes | All checks pass (CI + PR review) | -| **pr** | Pull request creation and merge | Human merge | +| **implement** | Task execution and code changes; context PR opened automatically at phase start | All checks pass + human merge (terminal phase) | ### Role Permissions @@ -83,7 +83,7 @@ The contract is a JSON document tracking the complete state of an issue through ```json { - "schemaVersion": "1.1", + "schemaVersion": "1.2", "issue": { "number": 133, "title": "...", "url": "..." }, "current_phase": "implement", "slices": [{ @@ -116,48 +116,23 @@ The contract is a JSON document tracking the complete state of an issue through > existing imports. See [Slice-DAG Implement Phase](slice-dag.md) for > the full design. -> **Schema 1.1 (#2548)**: `schemaVersion` was bumped from `1.0` to `1.1` -> to track the addition of four optional `pr.context_*` fields on +> **Schema 1.1 (#2548)** added four optional `pr.context_*` fields on > `PRMetadata` (`context_title`, `context_description`, `context_branch`, -> `context_pr_number`) used by the dedicated context-PR mechanism. The -> bump is purely additive — pre-1.1 contracts load transparently via a -> Pydantic `model_validator(mode="after")` migration that stamps -> `schemaVersion = "1.1"` on every load when the on-disk value is exactly -> `"1.0"`; the migration is silent (no audit-log entry) and idempotent. -> `context_title` / `context_description` are planner-emitted optional -> framing for the strategic-plan PR; `context_branch` / -> `context_pr_number` are populated by the orchestrator after the context -> branch is created and the context PR is opened. +> `context_pr_number`) for a dedicated `egg//context` branch +> mechanism. > -> **The context-PR mechanism is fully wired as of #2593 (gap from #2548 closed).** After -> plan-gate approval the orchestrator creates `egg//context` -> from the pipeline's base branch, copies the refine + plan artifacts -> (analysis.md, plan.md, BRC history JSON/MD, per-role agent -> transcripts, and the contract JSON — see the #2685 paragraph below) -> onto a temp worktree committed to that branch, opens a -> doc-only PR via `gh pr create`, and persists `context_branch` / -> `context_pr_number` into the contract. Slice-1 stacks on the context -> branch rather than the pipeline work branch, so the strategic narrative -> is reachable through the slice PR diff. The stacked-PR reconciler -> prefers the context branch over the pipeline branch when retargeting -> orphaned child PRs whose entire ancestor chain has been deleted. -> (#2593 extended the hook from the inline `_run_pipeline` auto-advance -> path to all plan→implement transition paths: `advance_phase` REST/MCP, -> HITL-approval recovery in `start_pipeline`, and the implement-entry -> backstop. #2744 added a fifth safety net at slice-loop entry in -> `_run_implement_phase_slices` — called before any slice is provisioned -> so slice-1's context-branch resolution finds a populated -> `context_branch`; the wrapper's inner `context_pr_number` short-circuit -> makes this call cheap when an earlier path already opened the PR.) -> -> **#2685 added two follow-on behaviors:** the contract JSON is now -> included in the context PR diff (resolved via the contract loader so -> integer issue identifiers map to the canonical `issue-.json` path -> rather than a bare `{identifier}.json` glob), and the legacy -> ` → main` auto-PR in the PR phase is suppressed for -> slice-DAG pipelines (`len(contract.slices) > 1`) — per-slice PRs -> already exist stacked on the context PR, so the program-level -> auto-PR would be redundant and confusing to reviewers. +> **Schema 1.2 (#2777)**: `schemaVersion` was bumped to `"1.2"` when the +> three split fields (`context_branch`, `context_title`, +> `context_description`) were hard-removed. Under the new topology, the +> context PR opens on the work branch (`egg//work → main`) +> directly at the plan→implement boundary via +> `_open_context_pr_at_implement_start`, so separate branch/title/description +> fields are no longer needed. `context_pr_number` survives as the single +> surviving field that tracks the opened PR's number. Pre-1.2 contracts on +> disk load transparently: a `model_validator(mode="wrap")` migration strips +> the three removed keys before Pydantic constructs `PRMetadata` and bumps +> `schemaVersion` to `"1.2"`. The PR phase enum row (`PipelinePhase.PR`) was +> also hard-removed in #2777 — `IMPLEMENT` is now the terminal phase. ## HITL (Human-in-the-Loop) Mechanism @@ -221,7 +196,7 @@ The local distributed orchestrator (`orchestrator/` package) manages the full li | Contract schema | `.egg/schemas/contract.schema.json` | | Contract instances | `.egg-state/contracts/{identifier}.json` | | Phase drafts | `.egg-state/drafts/{identifier}-{analysis\|plan}.md` (preserved on PR branch as pipeline artifacts) | -| BRC consensus history | `.egg-state/brc-history/{identifier}-{phase}.md` and `.json` (re-written in PR phase as safety net; `.md` is human-readable with YAML metadata blocks, `.json` is machine-readable) | +| BRC consensus history | `.egg-state/brc-history/{identifier}-{phase}.md` and `.json` (written at each phase boundary; `.md` is human-readable with YAML metadata blocks, `.json` is machine-readable) | | Review verdicts | `.egg-state/reviews/{identifier}-{phase}-{reviewer}.json` | | Contract library | `shared/egg_contracts/` | | Gateway endpoints | `gateway/contract_api.py` (proxy), `gateway/phase_api.py` | diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index fa1478cd3a..c904f3c75d 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -62,22 +62,22 @@ The pipeline pauses for human approval at phase transitions (refine and plan). T │ SDLC PIPELINE │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │ -│ │ REFINE │───▶│ PLAN │───▶│ IMPLEMENT │───▶│ CREATE │ │ -│ │ (cycles) │ │ (cycles) │ │ (cycles) │ │ PR │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ └──────────┘ │ -│ │ ╎ │ │ │ │ -│ ▼ ╎ ▼ ▼ ▼ │ -│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ REVIEW │ ╎ │ REVIEW │ │ REVIEW │ │ HUMAN │ │ -│ │ (auto) │ ╎ │ (auto) │ │ (auto) │ │ MERGE │ │ -│ └────┬────┘ ╎ └────┬────┘ └─────────┘ └─────────┘ │ -│ │ ╎ │ │ -│ ▼ ╎ ▼ │ -│ ┌─────────┐ ╎ ┌─────────┐ │ -│ │ HITL │ ╎ │ HITL │ │ -│ │ Approve │ ╎ │ Approve │ │ -│ └─────────┘ ╎ └─────────┘ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │ +│ │ REFINE │───▶│ PLAN │───▶│ IMPLEMENT │ │ +│ │ (cycles) │ │ (cycles) │ │ (cycles; context PR opened │ │ +│ └─────────────┘ └─────────────┘ │ at phase start) │ │ +│ │ ╎ │ └─────────────────────────────┘ │ +│ ▼ ╎ ▼ │ │ +│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ +│ │ REVIEW │ ╎ │ REVIEW │ │ REVIEW │ │ +│ │ (auto) │ ╎ │ (auto) │ │ (auto) │ │ +│ └────┬────┘ ╎ └────┬────┘ └─────────┘ │ +│ │ ╎ │ │ │ +│ ▼ ╎ ▼ ▼ │ +│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ +│ │ HITL │ ╎ │ HITL │ │ HUMAN │ │ +│ │ Approve │ ╎ │ Approve │ │ MERGE │ │ +│ └─────────┘ ╎ └─────────┘ └─────────┘ │ │ ╎ │ │ │ │ │ @@ -122,14 +122,14 @@ Returns the current pipeline status for polling-based monitoring. } ``` -Once a pull request is created during the PR phase, two additional fields appear in `data`: +Once the context PR is opened at the plan→implement boundary, two additional fields appear in `data`: -- `pr_url` — full GitHub URL of the created PR (e.g. `"https://github.com/owner/repo/pull/42"`) +- `pr_url` — full GitHub URL of the context PR (e.g. `"https://github.com/owner/repo/pull/42"`) - `pr_number` — integer PR number parsed from the URL (e.g. `42`); omitted if the URL has an unexpected shape This avoids a separate `gh pr list` call by monitoring clients. -> **Pipeline record fields (issue #1911).** The auto-PR path also writes `pipeline.pr_number` and (best-effort) `pipeline.pr_head_sha` onto the pipeline record itself, not only the `pr_url` phase artifact. Consumers that load the pipeline via `get_pipeline_snapshot` / the pipeline JSON can rely on `pipeline.pr_number` directly — the overseer's `post-consensus-push-stall` detector uses this as one of the three signals that the post-consensus transition succeeded. `pipeline.pr_head_sha` is populated when `gh pr view` returns a valid hex SHA; if the `gh` call fails or propagation is still in flight, the field is left `None` and the PR phase still succeeds. +> **Pipeline record fields (issue #1911).** The context-PR open path also writes `pipeline.pr_number` and (best-effort) `pipeline.pr_head_sha` onto the pipeline record itself. Consumers that load the pipeline via `get_pipeline_snapshot` / the pipeline JSON can rely on `pipeline.pr_number` directly — the overseer's `post-consensus-push-stall` detector uses this as one of the three signals that the post-consensus transition succeeded. `pipeline.pr_head_sha` is populated when `gh pr view` returns a valid hex SHA; if the `gh` call fails or propagation is still in flight, the field is left `None`. When `pending_decisions > 0`, the `data` object includes an additional `pending_decision` field with the first pending decision's details, so consumers don't need a second round-trip to fetch it: @@ -205,14 +205,13 @@ Returns a Server-Sent Events (SSE) stream for real-time updates across all activ "current_phase": "implement", "visualization": { "dag": ">>> ╔══════════════════════╗\n │ ▶ Implement │\n │ running (2 cycles completed) │\n │ ✓ coder ▶ reviewer│\n │ [last cycle: 5m0s | total: 15m0s]│\n ╚══════════════════════╝", - "compact": "✓Refine → ✓Plan → [▶Implement] → ○PR", + "compact": "✓Refine → ✓Plan → [▶Implement]", "progress": "[███████████░░░░░░░░░] 60%" }, "phases": { "refine": {"status": "complete", "review_cycles": 2, "containers": 1, "agents": [{"role": "coder", "status": "complete"}]}, "plan": {"status": "complete", "review_cycles": 1, "containers": 1, "agents": [{"role": "coder", "status": "complete"}]}, - "implement": {"status": "running", "review_cycles": 2, "containers": 2, "agents": [{"role": "coder", "status": "complete"}, {"role": "reviewer", "status": "running"}]}, - "pr": {"status": "pending", "review_cycles": 0, "containers": 0, "agents": []} + "implement": {"status": "running", "review_cycles": 2, "containers": 2, "agents": [{"role": "coder", "status": "complete"}, {"role": "reviewer", "status": "running"}]} }, "pending_decisions": 0, "updated_at": "2026-02-12T10:30:00Z" @@ -250,8 +249,7 @@ Timing starts when actual work begins (`work_started_at`), excluding setup and H |-------|---------|-------------------|---------------| | **Refine** | Analyze issue, produce analysis document | `git push`, `egg-contract add-decision` | Auto-review pass + Human approval | | **Plan** | Create implementation plan with tasks | `git push`, `egg-contract add-decision` | Auto-review pass + Human approval | -| **Implement** | Execute tasks on draft PR with CI and review feedback | `git push`, `egg-contract complete-task/complete-phase` | All checks pass (CI + PR review) | -| **PR** | Finalize PR for human review and merge | `gh pr edit`, `git push` | Human merge (closes issue automatically) | +| **Implement** | Execute tasks with CI and review feedback; context PR opened automatically at phase start | `git push`, `egg-contract complete-task/complete-phase` | All checks pass + human merge (terminal phase) | ### Multi-Reviewer Architecture @@ -418,8 +416,7 @@ Each phase has a defined set of permitted operations. The gateway blocks all oth **Phase restrictions:** - **Refine/Plan phases**: `git push` restricted to `.egg-state/` files; cannot `gh pr create`—prevents source code changes before plan approval -- **Implement phase**: Can `git push` to the branch; draft PR is created automatically by the pipeline (not by agent) -- **PR phase**: PR is auto-created by the orchestrator from contract metadata and git log (no agent spawned). Human must merge. +- **Implement phase**: Can `git push` to the branch; the context PR and slice PRs are created automatically by the orchestrator (not by the agent). The implement phase is terminal — no separate PR phase follows. This structural enforcement prevents incidents where agents push code during planning or manually create PRs before implementation is complete. @@ -433,7 +430,7 @@ This structural enforcement prevents incidents where agents push code during pla | `.egg/phase-permissions.json` | Phase operation restrictions | `main` | | `.egg-state/contracts/` | Per-issue contract instances | Feature branches only | | `.egg-state/drafts/` | Draft analysis and plan documents (preserved on PR branch for review) | Feature branches only | -| `.egg-state/brc-history/` | Per-phase BRC consensus message logs — `.md` (human-readable with YAML metadata) and `.json` (machine-readable) per phase (re-written in PR phase as safety net) | Feature branches only | +| `.egg-state/brc-history/` | Per-phase BRC consensus message logs — `.md` (human-readable with YAML metadata) and `.json` (machine-readable) per phase (written at each phase boundary) | Feature branches only | | `.egg-state/reviews/` | Internal review verdicts (JSON) | Feature branches only | ### Conflict-Resistant Contract Updates @@ -444,7 +441,7 @@ The local orchestrator handles concurrent contract updates through `orchestrator ```json { - "schemaVersion": "1.1", + "schemaVersion": "1.2", "issue": { "number": 123, "title": "Add feature X", @@ -483,12 +480,15 @@ The local orchestrator handles concurrent contract updates through `orchestrator } ``` -> **Schema 1.1 (#2548)**: The default `schemaVersion` is now `"1.1"`, which -> additively introduces four optional `pr.context_*` fields -> (`context_title`, `context_description`, `context_branch`, -> `context_pr_number`). Pre-1.1 contract JSON loads cleanly — a Pydantic -> `model_validator` silently promotes `"1.0"` to `"1.1"` on load and the -> bumped value is persisted on the next save. +> **Schema 1.2 (#2777)**: The default `schemaVersion` is now `"1.2"`. +> Schema 1.1 (#2548) added four optional `pr.context_*` fields; schema 1.2 +> hard-removed three of them (`context_branch`, `context_title`, +> `context_description`) — the context PR now opens on the work branch +> directly and reuses `title`/`description`. The surviving field is +> `context_pr_number`. Pre-1.2 contracts on disk load cleanly — a Pydantic +> `model_validator(mode="wrap")` strips the three removed keys before +> constructing `PRMetadata` and bumps `schemaVersion` to `"1.2"`; the new +> value is persisted on the next save. ### Role-Based Field Ownership @@ -544,14 +544,13 @@ This ensures agents always work with the latest codebase and conflicts are resol The implement phase uses PR-based automated code review: -1. **Main branch merge** — Before starting work, merges latest main into the issue branch (see above) -2. **Implementer executes tasks** — The implementer agent runs, commits changes, and pushes to the branch -3. **Draft PR created** — After implementation succeeds, a draft PR is created automatically with commit messages in the description +1. **Context PR opened** — At phase start, the orchestrator opens the context PR (`egg//work → main`) with the plan metadata; no agent is spawned for this step +2. **Main branch merge** — Before starting work, merges latest main into the issue branch (see above) +3. **Implementer executes tasks** — The implementer agent runs, commits changes, and pushes to the branch 4. **CI and review checks** — The pipeline waits for all GitHub check runs (linting, tests, and PR review) to complete 5. **Review feedback** — The `reusable-review.yml` workflow provides line-level code review comments on the draft PR 6. **Re-implementation cycles** — If checks fail or review requests changes, the implementer is re-invoked with feedback -7. **PR finalization** — Once all checks pass and review approves, the draft PR is marked ready for human merge -8. **Issue closure** — When the PR is merged, the original issue is automatically closed (the PR body includes `Closes #`) +7. **Issue closure** — When the PR is merged, the original issue is automatically closed (the PR body includes `Closes #`) This approach provides: - Line-level code review comments visible to humans @@ -751,7 +750,7 @@ The orchestrator pushes worktree state (including `.egg-state/` files) to the re 1. **After contract initialization** — Pushes initial contract and analysis/plan drafts so the first agents in the next phase see them 2. **After phase completion** — Pushes statefiles (drafts, reviews, BRC history, check results, contract updates) so the next phase's agents don't have unpushed `.egg-state/` files in their diff -3. **Before PR creation** — Pushes BRC history re-writes and any pending statefiles. This is a safety net for cases where post-phase pushes (point 2) failed silently. Push outcomes are logged at INFO level with the number of local commits ahead of remote (see [PR-Phase State File Troubleshooting](#pr-phase-state-file-troubleshooting)) +3. **Before context PR creation** — Pushes BRC history and any pending statefiles. This is a safety net for cases where post-phase pushes (point 2) failed silently. Push outcomes are logged at INFO level with the number of local commits ahead of remote. 4. **On pipeline failure** — Best-effort failsafe push to preserve in-progress work All pushes use `GatewayClient.push_worktree_branch()`, which authenticates directly with the launcher secret (orchestrator-trusted) rather than registering a temporary session token. This bypasses the agent-targeted pipeline-push enforcement so the orchestrator's programmatic pushes are never blocked by #2028-style pipeline-session guards. On non-fast-forward rejection, it automatically performs a `git fetch` + `git rebase` in the worktree and retries the push once before giving up. The call returns a `PushResult` dataclass (truthy on success) whose `category` and `detail` fields describe the underlying git error — so contract-init failures surface an operator-actionable message like `"non_fast_forward: ! [rejected] ... (fetch first)"` instead of the historical opaque `"push_worktree_branch returned False"`. @@ -864,7 +863,7 @@ The orchestrator's pipeline routes (`orchestrator/routes/pipelines.py`): 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. If neither the contract nor the plan draft on disk contains a `pr.title`, the PR falls through to a stub (issue title or pipeline ID) and is opened as a **draft** with a warning banner listing parse failures so reviewers can diagnose and repair before merging. +The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. If neither the contract nor the plan draft on disk contains a `pr.title`, the PR falls through to a stub (issue title or pipeline ID) and is opened as a **draft** with a warning banner listing parse failures so reviewers can diagnose and repair before merging. ## Phase Checks @@ -956,14 +955,12 @@ Default checks for each phase are defined in `shared/egg_contracts/phase_default - Test check (required) - Auto-fixer (optional) -**PR phase:** -- No checks -- PR is auto-created by the orchestrator (no agent spawned). The PR title and description are sourced from the contract's `pr` field (populated by the plan agent), with commit log and diff stats appended automatically. When BRC consensus was active, a one-line pointer to the committed per-phase BRC history transcripts is included in the PR body (linked from `.egg-state/brc-history/`). See [Concurrent Execution — BRC History Link in PR Body](concurrent-execution.md#brc-history-link-in-pr-body) for details. -- **Agent-outputs cleanup**: At PR-phase entry, the orchestrator removes `.egg-state/agent-outputs/` from the branch via `_cleanup_agent_outputs_for_pr()`. These files are ephemeral coder→tester handoff artifacts (e.g., `coder-test-changes.patch`) that the tester has already consumed. Leaving them causes merge conflicts in concurrent pipelines and pollutes the PR diff. Cleanup is best-effort — failures are logged but do not block PR creation. -- **BRC history safety net**: Before PR creation, the orchestrator re-writes BRC history files for all completed phases via `_write_brc_history()`. This is a safety net — BRC history is normally written at each phase boundary, but per-phase pushes can fail silently. Re-writing in the PR phase ensures BRC history files are always present in the PR diff. All functions in this chain emit INFO-level diagnostic logs at entry, exit, and each early-return path (see [PR-Phase State File Troubleshooting](#pr-phase-state-file-troubleshooting)). -- **Pre-PR-open rebase** (#2224): Immediately before calling `gh pr create`, the orchestrator rebases the pipeline branch against the current `origin/` via `_refresh_pipeline_branch_against_current_base()`. Phase-start rebases (`_rebase_pipeline_branch_onto_base`) only run once per phase iteration; if `base_branch` advances *during* the PR phase, the pipeline branch ends up behind. This step closes that gap so the PR opens with a clean linear diff. The operation is best-effort — on any failure (rebase conflict, push rejection, transient gateway error) the PR still opens against the un-rebased tip and the divergence is visible to the human reviewer. Only the pipeline branch is ever written to; `base_branch` is read-only here. -- **Draft preservation**: Pipeline-specific draft files (`.egg-state/drafts/{id}-analysis.md`, `.egg-state/drafts/{id}-plan.md`) are **preserved** on the PR branch as artifacts of the pipeline's reasoning. Reviewers can compare the planned approach against the shipped code, and post-hoc debugging has the analysis and plan available as a baseline (see #1713). The PR phase used to remove these files to keep diffs focused; that behavior was reverted because the audit value outweighs the diff noise. -- If PR creation returns no URL, the pipeline is marked **FAILED** immediately. The overseer also runs a safety-net check at pipeline completion: if `current_phase=pr` but no `pr_url` is in the phase artifacts, it creates a HITL decision and Slack notification to prevent stranded branch work from going unnoticed. +**Context PR (opened at implement-phase start, #2777):** +- The PR phase was hard-removed in #2777; `IMPLEMENT` is now terminal. The context PR (`egg//work → main`) is opened by the orchestrator at the plan→implement boundary via `_open_context_pr_at_implement_start` — no separate phase or agent is spawned for this. +- The PR title and description are sourced from the contract's `pr` field (populated by the plan agent). When BRC consensus was active, a one-line pointer to the committed per-phase BRC history transcripts is included in the PR body (linked from `.egg-state/brc-history/`). See [Concurrent Execution — BRC History Link in PR Body](concurrent-execution.md#brc-history-link-in-pr-body) for details. +- **Agent-outputs cleanup**: At implement-phase start the orchestrator removes `.egg-state/agent-outputs/` from the branch via `_cleanup_agent_outputs_for_pr()`. These files are ephemeral coder→tester handoff artifacts that the tester has already consumed. Cleanup is best-effort — failures are logged but do not block PR creation. +- **Draft preservation**: Pipeline-specific draft files (`.egg-state/drafts/{id}-analysis.md`, `.egg-state/drafts/{id}-plan.md`) are preserved on the branch as artifacts of the pipeline's reasoning (#1713). +- If context PR creation returns no URL, the pipeline is marked **FAILED** immediately (the context PR is hard-required — there is no soft-fail path). ### Customizing Phase Checks @@ -1606,9 +1603,11 @@ Note: `update-notes` writes to a task's `notes` field, not `contract.decisions`, For pre-plan phase gates (refine→plan), there are no contract tasks yet to attach notes to. In that case, prepend the resolution context directly to the next phase's draft once it materialises (e.g., `.egg-state/drafts/-plan.md`) so the planner picks it up. -### PR-Phase State File Troubleshooting +### Context PR State File Troubleshooting -The PR phase runs three operations before creating the PR: agent-outputs cleanup, BRC history re-write, and a final push. Each operation has diagnostic INFO-level logging to help identify failures. +Before opening the context PR at the plan→implement boundary, the orchestrator runs several operations: agent-outputs cleanup, BRC history writing, and a final push. Each operation has diagnostic INFO-level logging to help identify failures. + +> **Note**: Prior to #2777 this section described a dedicated "PR phase". That phase was removed; the operations described below now occur at implement-phase start. **BRC history files missing from PR** (`.egg-state/brc-history/` absent): From 6855d38f0f03eadb43a488e5bcd27462e8cfe9dd Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Sat, 30 May 2026 23:23:39 +0000 Subject: [PATCH 2/6] docs: address review feedback on PR-phase removal cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/guides/sdlc-pipeline.md:50 — Replace stale "draft PRs created during the implement phase" with accurate description (context PR opened by orchestrator at plan→implement boundary). - docs/guides/sdlc-pipeline.md:547 — Drop dangling "not at PR finalization time" reference to a now-deleted phase. - docs/guides/sdlc-pipeline.md:557 — Step 5 now says "context PR" instead of "draft PR" (the context PR is opened with draft=False). - docs/guides/sdlc-pipeline.md:70-82 — Restore consistent 75-char width across diagram rows and add missing ▼ arrowhead on the IMPLEMENT→REVIEW column (matching the Refine/Plan columns). - docs/architecture/sdlc-pipeline.md:45 — Pad the third inner row of the Implement box to 75 chars (was 74; right edge drifted). - docs/architecture/sdlc-pipeline.md:47-48 — Drop the 4th down-arrow that previously fed from the now-removed PR box; the wide Implement box no longer reads as having two outputs. - README.md:100-101 — Clarify the human-merge label as "context + slice PRs" to reflect that both surfaces require human merge. Authored-by: egg --- README.md | 2 +- docs/architecture/sdlc-pipeline.md | 6 +++--- docs/guides/sdlc-pipeline.md | 30 +++++++++++++++--------------- 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9e6eef39be..bf8c4b7ded 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ egg structures work into phases with mandatory human gates: └────┬─────┘ └────┬─────┘ └─────────────────────────────────────┘ │ │ │ │ Human gate Human gate Context PR opened Human merges - at phase start slice PRs + at phase start context + slice PRs ``` 1. **Refine**: Agents analyze the task, research the codebase, produce requirements. Reviewers validate. Human approves before planning. diff --git a/docs/architecture/sdlc-pipeline.md b/docs/architecture/sdlc-pipeline.md index 7f09e19918..1b66d58d8d 100644 --- a/docs/architecture/sdlc-pipeline.md +++ b/docs/architecture/sdlc-pipeline.md @@ -42,10 +42,10 @@ This architecture implements **structural enforcement**: the agent physically ca │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────────┐ │ │ │ Refine │───▶│ Plan │───▶│ Implement │ │ │ │ (Human) │ │ (Human) │ │ (Reviewer; context PR │ │ -│ └─────────────┘ └─────────────┘ │ opened at phase start) │ │ +│ └─────────────┘ └─────────────┘ │ opened at phase start) │ │ │ └─────────────────────────────┘ │ -│ │ │ │ │ │ -│ ▼ ▼ ▼ ▼ │ +│ │ │ │ │ +│ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ Contract State │ │ │ │ .egg-state/contracts/{identifier}.json │ │ diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index b4bddea087..7c2e1bdcc3 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -47,7 +47,7 @@ The pipeline enforces role-based field ownership in contracts: | **Reviewer** | `status`, `review_feedback`, `current_phase` | `commit`, task definitions | | **Human** | All fields | — | -Code reviews are performed by the existing PR review workflow (`reusable-review.yml`), which provides line-level feedback on draft PRs created during the implement phase. +Code reviews are performed by the existing PR review workflow (`reusable-review.yml`), which provides line-level feedback on the context PR opened by the orchestrator at the plan→implement boundary. ### 4. Human-in-the-Loop at Critical Points @@ -67,19 +67,19 @@ The pipeline pauses for human approval at phase transitions (refine and plan). T │ │ (cycles) │ │ (cycles) │ │ (cycles; context PR opened │ │ │ └─────────────┘ └─────────────┘ │ at phase start) │ │ │ │ ╎ │ └─────────────────────────────┘ │ -│ ▼ ╎ ▼ │ │ -│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ -│ │ REVIEW │ ╎ │ REVIEW │ │ REVIEW │ │ -│ │ (auto) │ ╎ │ (auto) │ │ (auto) │ │ -│ └────┬────┘ ╎ └────┬────┘ └─────────┘ │ -│ │ ╎ │ │ │ -│ ▼ ╎ ▼ ▼ │ -│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ -│ │ HITL │ ╎ │ HITL │ │ HUMAN │ │ -│ │ Approve │ ╎ │ Approve │ │ MERGE │ │ -│ └─────────┘ ╎ └─────────┘ └─────────┘ │ +│ ▼ ╎ ▼ ▼ │ +│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ +│ │ REVIEW │ ╎ │ REVIEW │ │ REVIEW │ │ +│ │ (auto) │ ╎ │ (auto) │ │ (auto) │ │ +│ └────┬────┘ ╎ └────┬────┘ └─────────┘ │ +│ │ ╎ │ │ │ +│ ▼ ╎ ▼ ▼ │ +│ ┌─────────┐ ╎ ┌─────────┐ ┌─────────┐ │ +│ │ HITL │ ╎ │ HITL │ │ HUMAN │ │ +│ │ Approve │ ╎ │ Approve │ │ MERGE │ │ +│ └─────────┘ ╎ └─────────┘ └─────────┘ │ │ ╎ │ -│ │ +│ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` @@ -544,7 +544,7 @@ The SDLC pipeline automatically merges the latest main branch into the issue bra - Pulls the resolved changes and continues - Fails if no PR exists (required for `workflow_dispatch` targeting) or conflict resolution fails -This ensures agents always work with the latest codebase and conflicts are resolved before work begins, not at PR finalization time. +This ensures agents always work with the latest codebase and conflicts are resolved before work begins. ### Implement and PR-Based Review @@ -554,7 +554,7 @@ The implement phase uses PR-based automated code review: 2. **Main branch merge** — Before starting work, merges latest main into the issue branch (see above) 3. **Implementer executes tasks** — The implementer agent runs, commits changes, and pushes to the branch 4. **CI and review checks** — The pipeline waits for all GitHub check runs (linting, tests, and PR review) to complete -5. **Review feedback** — The `reusable-review.yml` workflow provides line-level code review comments on the draft PR +5. **Review feedback** — The `reusable-review.yml` workflow provides line-level code review comments on the context PR 6. **Re-implementation cycles** — If checks fail or review requests changes, the implementer is re-invoked with feedback 7. **Issue closure** — When the PR is merged, the original issue is automatically closed (the PR body includes `Closes #`) From 17584491845517c6b05e743581628efa7af8faa6 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Sat, 30 May 2026 23:55:32 +0000 Subject: [PATCH 3/6] =?UTF-8?q?docs:=20drop=20agent-outputs=20cleanup=20cl?= =?UTF-8?q?aim=20=E2=80=94=20function=20has=20no=20production=20callers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewer flagged that two passages introduced by this PR describe `_cleanup_agent_outputs_for_pr()` running at implement-phase start, but the function has zero production call sites since #2891 deleted the PR-phase entry that used to call it. Removing the bullet at line 968 and the 'agent-outputs cleanup' clause at line 1617 so the docs no longer assert behavior that does not happen. The orphaned function itself is tracked for code cleanup in #2899. --- docs/guides/sdlc-pipeline.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 7c2e1bdcc3..b981b5d38d 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -965,7 +965,6 @@ Default checks for each phase are defined in `shared/egg_contracts/phase_default **Context PR (opened at implement-phase start, #2777):** - The terminal "PR phase" was **deleted** as a separate pipeline stage; `IMPLEMENT` is now terminal. The context PR (`egg//work → main`) is opened by the orchestrator at the plan→implement boundary via `_open_context_pr_at_implement_start` — no separate phase or agent is spawned for this. The open is hard-required and idempotent (`GatewayClient.list_open_prs` pre-flight with client-side head+base filter). Per-slice PRs are opened inline by `create_slice_pr`, which uses `GatewayClient._lookup_open_pr` (server-side `gh pr list --head … --base … --limit 1` pre-flight; #2777 cq-8). - The PR title and description are sourced from the contract's `pr` field (populated by the plan agent), with commit log and diff stats appended automatically. When BRC consensus was active, a one-line pointer to the committed per-phase BRC history transcripts is included in the PR body (linked from `.egg-state/brc-history/`). See [Concurrent Execution — BRC History Link in PR Body](concurrent-execution.md#brc-history-link-in-pr-body) for details. -- **Agent-outputs cleanup**: At implement-phase start the orchestrator removes `.egg-state/agent-outputs/` from the branch via `_cleanup_agent_outputs_for_pr()`. These files are ephemeral coder→tester handoff artifacts that the tester has already consumed. Cleanup is best-effort — failures are logged but do not block PR creation. - **Draft preservation**: Pipeline-specific draft files (`.egg-state/drafts/{id}-analysis.md`, `.egg-state/drafts/{id}-plan.md`) are **preserved** on the PR branch as artifacts of the pipeline's reasoning. Reviewers can compare the planned approach against the shipped code, and post-hoc debugging has the analysis and plan available as a baseline (#1713). - If the up-front context-PR open fails (after the idempotent pre-flight returns no existing PR and `gh pr create` itself fails), the pipeline is marked **FAILED** immediately — there is no terminal back-stop because the open is hard-required up-front. @@ -1614,7 +1613,7 @@ For pre-plan phase gates (refine→plan), there are no contract tasks yet to att The PR phase as a separate pipeline stage was **deleted** in [#2777](https://github.com/jwbron/egg/issues/2777). BRC history, drafts and other `.egg-state/` artifacts now reach the context PR (`egg//work → main`) through the post-phase push points described in [Worktree State Synchronization](#worktree-state-synchronization) — one push at the end of each completed phase. There is no longer a separate "before PR creation" rewrite/push step. The per-phase write path itself (`_write_brc_history` → `_commit_statefiles_to_worktree` → `push_worktree_branch`) is unchanged; only the PR-phase wrapper that used to re-invoke it as a safety net is gone. -Before opening the context PR at the plan→implement boundary, the orchestrator runs several operations: agent-outputs cleanup, BRC history writing, and a final push. Each operation has diagnostic INFO-level logging to help identify failures. +Before opening the context PR at the plan→implement boundary, the orchestrator runs BRC history writing and a final push. Each operation has diagnostic INFO-level logging to help identify failures. **BRC history files missing from PR** (`.egg-state/brc-history/` absent): From 97645c9605d68c64f0d82ecd1d0fbf7dda6d22d9 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Sun, 31 May 2026 00:39:11 +0000 Subject: [PATCH 4/6] Drop stale stub-tier fall-through claim from context-PR doc The final sentence of the PR-metadata paragraph in docs/guides/sdlc-pipeline.md described a stub-title fall-through that opens the PR as a draft with a warning banner. That path belonged to the deleted _finalize_pr_phase and does not exist in _open_context_pr_at_implement_start (which raises ContextPrCreationError(reason="missing_pr_metadata") instead). Replaced with an accurate description of the actual failure path, referencing the pre-flight validator as the structural gate. --- docs/guides/sdlc-pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 84ed76ba4a..1238e2e3ec 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -872,7 +872,7 @@ This happens in the plan phase itself (before human approval) to provide early v **Plan pre-flight validation at plan→implement** (#2777): when `advance_phase` transitions from plan to implement (without `force=true`), the orchestrator runs a structural pre-flight check on the plan draft *before* the populate step. The check verifies that the plan contains a parseable `yaml-tasks` block, non-empty `pr.title` / `pr.description` / `pr.test_plan` fields, and a present `pr.manual_steps` key (an empty string is allowed — the contract default — but the key must exist in the YAML). If any field is missing the call returns **422** with `reason: preflight_invalid_plan` and a `missing_fields` list naming each absent field — so the operator sees the full set of issues in one response rather than discovering them one at a time. Passing `force=true` bypasses the pre-flight validator (useful when a plan draft is unrecoverable and the operator needs to unstick the pipeline manually). Infra failures (dependency import errors, worktree probe / draft-read `OSError`s) surface as **500** with `reason: preflight_unavailable` so the operator retries rather than mistaking infra trouble for a passing check; if the draft path is undeclared or the draft file is absent on disk, the validator skips silently and lets the populate step handle the gap. -The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. If neither the contract nor the plan draft on disk contains a `pr.title`, the PR falls through to a stub (issue title or pipeline ID) and is opened as a **draft** with a warning banner listing parse failures so reviewers can diagnose and repair before merging. +The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. The pre-flight validator above is the structural gate that ensures `contract.pr.title` is populated on the normal path; if the opener is reached with a missing or empty title (only possible via `force=true` plan→implement with a malformed draft), it raises `ContextPrCreationError(reason="missing_pr_metadata")` and the pipeline is marked **FAILED** — there is no stub-title fall-through. ## Phase Checks From 6a1433a9179d42dc83125e57f0ca0dcc28fb44c8 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Sun, 31 May 2026 01:02:36 +0000 Subject: [PATCH 5/6] Correct context-PR opener failure-mode description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The prior sentence claimed the pipeline is marked FAILED and that the missing-title case is only reachable via force=true. Both are wrong: - On the canonical advance_phase path the handler returns 422 with reason context_pr_open_failed and the pipeline stays in its prior phase (PLAN) — see orchestrator/routes/phases.py:632-637. - The case is also reachable on the non-force path when the validator silently skips (no plan draft on disk) and the populate step fails to write contract.pr — phases.py:444-465 + 552-557 log-and-continue. - The runner-side force=true backstops (pipelines.py:16004-16013, 21845-21861, plus two more) log-and-continue rather than marking the pipeline FAILED. --- docs/guides/sdlc-pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 1238e2e3ec..1a5f3f7659 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -872,7 +872,7 @@ This happens in the plan phase itself (before human approval) to provide early v **Plan pre-flight validation at plan→implement** (#2777): when `advance_phase` transitions from plan to implement (without `force=true`), the orchestrator runs a structural pre-flight check on the plan draft *before* the populate step. The check verifies that the plan contains a parseable `yaml-tasks` block, non-empty `pr.title` / `pr.description` / `pr.test_plan` fields, and a present `pr.manual_steps` key (an empty string is allowed — the contract default — but the key must exist in the YAML). If any field is missing the call returns **422** with `reason: preflight_invalid_plan` and a `missing_fields` list naming each absent field — so the operator sees the full set of issues in one response rather than discovering them one at a time. Passing `force=true` bypasses the pre-flight validator (useful when a plan draft is unrecoverable and the operator needs to unstick the pipeline manually). Infra failures (dependency import errors, worktree probe / draft-read `OSError`s) surface as **500** with `reason: preflight_unavailable` so the operator retries rather than mistaking infra trouble for a passing check; if the draft path is undeclared or the draft file is absent on disk, the validator skips silently and lets the populate step handle the gap. -The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. The pre-flight validator above is the structural gate that ensures `contract.pr.title` is populated on the normal path; if the opener is reached with a missing or empty title (only possible via `force=true` plan→implement with a malformed draft), it raises `ContextPrCreationError(reason="missing_pr_metadata")` and the pipeline is marked **FAILED** — there is no stub-title fall-through. +The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. The pre-flight validator above is the structural gate that ensures `contract.pr.title` is populated on the normal path. If the opener is reached with a missing or empty title — reachable when the validator silently skips (no plan draft on disk) *and* the plan-exit populate step fails to write `contract.pr`, or via `force=true` which bypasses both the validator and the canonical opener call — it raises `ContextPrCreationError(reason="missing_pr_metadata")`. On the canonical `advance_phase` path the orchestrator returns **HTTP 422** with `reason: context_pr_open_failed` and the pipeline remains in its prior phase (`PLAN`); on the runner-side `force=true` backstops the raise is logged and execution continues without a context PR, leaving slice PRs without a base to cascade onto. There is no stub-title fall-through on any path. ## Phase Checks From 62c0ef8284a221cf6bfa5dff8374040df7bd3a37 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Sun, 31 May 2026 01:23:50 +0000 Subject: [PATCH 6/6] Tighten wording on context-PR opener failure-mode sentence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address two non-blocking wording imprecisions flagged on docs/guides/sdlc-pipeline.md:875: 1. 'on the runner-side `force=true` backstops' overstated the scope — the four backstops (slice-loop entry, implement-entry, auto-advance, HITL-resume) cover non-force soft-fail paths too. Replaced with 'runner-side soft-fail backstops' to match the code's own framing. 2. 'leaving slice PRs without a base to cascade onto' diverged from the code's vocabulary — slice PRs do have a base (`pipeline_branch` resolved by `_resolve_slice_base_branch`); the operator-facing failure is that the slice stack is stranded on `egg//work` with no integrating context PR. Replaced with the stranded-stack framing consistent with the inline comments at pipelines.py:21841, 23199-23200, 24217-24218. --- docs/guides/sdlc-pipeline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 1a5f3f7659..48675a217d 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -872,7 +872,7 @@ This happens in the plan phase itself (before human approval) to provide early v **Plan pre-flight validation at plan→implement** (#2777): when `advance_phase` transitions from plan to implement (without `force=true`), the orchestrator runs a structural pre-flight check on the plan draft *before* the populate step. The check verifies that the plan contains a parseable `yaml-tasks` block, non-empty `pr.title` / `pr.description` / `pr.test_plan` fields, and a present `pr.manual_steps` key (an empty string is allowed — the contract default — but the key must exist in the YAML). If any field is missing the call returns **422** with `reason: preflight_invalid_plan` and a `missing_fields` list naming each absent field — so the operator sees the full set of issues in one response rather than discovering them one at a time. Passing `force=true` bypasses the pre-flight validator (useful when a plan draft is unrecoverable and the operator needs to unstick the pipeline manually). Infra failures (dependency import errors, worktree probe / draft-read `OSError`s) surface as **500** with `reason: preflight_unavailable` so the operator retries rather than mistaking infra trouble for a passing check; if the draft path is undeclared or the draft file is absent on disk, the validator skips silently and lets the populate step handle the gap. -The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. The pre-flight validator above is the structural gate that ensures `contract.pr.title` is populated on the normal path. If the opener is reached with a missing or empty title — reachable when the validator silently skips (no plan draft on disk) *and* the plan-exit populate step fails to write `contract.pr`, or via `force=true` which bypasses both the validator and the canonical opener call — it raises `ContextPrCreationError(reason="missing_pr_metadata")`. On the canonical `advance_phase` path the orchestrator returns **HTTP 422** with `reason: context_pr_open_failed` and the pipeline remains in its prior phase (`PLAN`); on the runner-side `force=true` backstops the raise is logged and execution continues without a context PR, leaving slice PRs without a base to cascade onto. There is no stub-title fall-through on any path. +The PR metadata (title and description) from the plan is stored in the contract's `pr` field and used by the orchestrator to open the context PR at the plan→implement boundary. 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. The pre-flight validator above is the structural gate that ensures `contract.pr.title` is populated on the normal path. If the opener is reached with a missing or empty title — reachable when the validator silently skips (no plan draft on disk) *and* the plan-exit populate step fails to write `contract.pr`, or via `force=true` which bypasses both the validator and the canonical opener call — it raises `ContextPrCreationError(reason="missing_pr_metadata")`. On the canonical `advance_phase` path the orchestrator returns **HTTP 422** with `reason: context_pr_open_failed` and the pipeline remains in its prior phase (`PLAN`); on the runner-side soft-fail backstops the raise is logged and execution continues without a context PR, leaving the slice stack stranded on `egg//work` with no integrating context PR. There is no stub-title fall-through on any path. ## Phase Checks