Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/architecture/orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,8 @@ The PR phase no longer spawns an agent. Instead, the orchestrator auto-creates t
4. Creates the PR via the gateway using a temporary session with `phase="pr"` permissions and the pipeline's resolved network mode; in `private` mode the PR is created as a draft
5. Applies `egg` and `agent:orchestrator` labels to the newly created PR

In slice-DAG mode (`len(contract.slices) > 1`) the auto-PR is **suppressed** — per-slice PRs already exist stacked on the [Context PR](#context-pr-slice-aware-mode-2548), so a program-level `<pipeline_branch> → main` PR would be redundant and confusing to reviewers. The skip gate is `_should_skip_pr_phase_auto_pr` in `orchestrator/routes/pipelines.py`; babysit-pr mode short-circuits the same gate because the PR already exists. Contract-load failures fail safe to running the legacy path (#2685).

The gateway also injects an `<!-- egg-pipeline-context ... -->` HTML comment into the PR body containing machine-parseable pipeline metadata (`pipeline_id`, `agent_role`, `issue`). Labels are applied best-effort — failures are logged but non-fatal.

This eliminates the need for agent interaction during PR creation and ensures consistent PR formatting across all pipelines.
Expand Down Expand Up @@ -184,6 +186,7 @@ After the plan phase completes and the plan_gate is approved, the orchestrator o
- `.egg-state/brc-history/<id>-refine.{md,json}` (refine BRC consensus record)
- `.egg-state/brc-history/<id>-plan.{md,json}` (plan BRC consensus record)
- `.egg-state/agent-outputs/<id>-refine-*.{md,json}` and `<id>-plan-*.{md,json}` (per-phase agent transcripts — included for transparency, HITL Q3)
- The contract JSON, resolved dynamically via `get_contract_path` so integer issue identifiers map to the canonical `.egg-state/contracts/issue-<N>.json` shape (with the legacy bare `<N>.json` as a fallback). Static glob omission is intentional — see `_STATIC_CONTEXT_PR_FILE_GLOBS` and `_gather_context_pr_files` in `orchestrator/routes/pipelines.py` (#2685).
3. It opens the PR against the configured base branch using `contract.pr.context_title` and `contract.pr.context_description` (distinct from `pr.title` / `pr.description`, which are per-slice).
4. The PR is **doc-only auto-open** (HITL decision-3): the orchestrator opens it, humans review on the PR, and the pipeline does **not** block on its merge before slicing begins.
5. Slice-1's `parent_branch` resolves to `egg/<id>/context` (rather than `egg/<id>/work`); slice-N>1 stacks on its predecessor as before. The [stacked-PR rebase reconciler](slice-dag.md#stacked-pr-rebase-reconciler) prefers the context branch over `pipeline_branch` as a last-resort fallback when retargeting orphaned children.
Expand Down
14 changes: 12 additions & 2 deletions docs/architecture/sdlc-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,8 +132,9 @@ The contract is a JSON document tracking the complete state of an issue through
> **The context-PR mechanism is fully wired as of #2593 (gap from #2548 closed).** After
> plan-gate approval the orchestrator creates `egg/<pipeline_id>/context`
> from the pipeline's base branch, copies the refine + plan artifacts
> (analysis.md, plan.md, BRC history JSON/MD, and per-role agent
> transcripts) onto a temp worktree committed to that branch, opens a
> (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
Expand All @@ -144,6 +145,15 @@ The contract is a JSON document tracking the complete state of an issue through
> path to all plan→implement transition paths: `advance_phase` REST/MCP,
> HITL-approval recovery in `start_pipeline`, and the implement-entry
> backstop.)
>
> **#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-<N>.json` path
> rather than a bare `{identifier}.json` glob), and the legacy
> `<pipeline_branch> → 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.

## HITL (Human-in-the-Loop) Mechanism

Expand Down
8 changes: 8 additions & 0 deletions docs/guides/concurrent-execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -970,6 +970,14 @@ Mechanics:
- `.egg-state/agent-outputs/<id>-refine-*.{md,json}` and
`<id>-plan-*.{md,json}` (per-phase agent transcripts — included
for maximum transparency)
- The contract JSON, resolved dynamically via `get_contract_path`
so integer issue identifiers map to the canonical
`.egg-state/contracts/issue-<N>.json` shape (with the legacy
bare `<N>.json` as a fallback). The contract is intentionally
omitted from the static glob list — see
`_STATIC_CONTEXT_PR_FILE_GLOBS` and
`_gather_context_pr_files` in `orchestrator/routes/pipelines.py`
(#2685).
3. It opens the PR against the pipeline base branch using
`contract.pr.context_title` and `contract.pr.context_description`.
These are distinct from `contract.pr.title` / `pr.description`,
Expand Down
Loading