diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index fa9a67705d..67c0b4f99b 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -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 ` → 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 `` 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. @@ -184,6 +186,7 @@ After the plan phase completes and the plan_gate is approved, the orchestrator o - `.egg-state/brc-history/-refine.{md,json}` (refine BRC consensus record) - `.egg-state/brc-history/-plan.{md,json}` (plan BRC consensus record) - `.egg-state/agent-outputs/-refine-*.{md,json}` and `-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-.json` shape (with the legacy bare `.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//context` (rather than `egg//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. diff --git a/docs/architecture/sdlc-pipeline.md b/docs/architecture/sdlc-pipeline.md index c083d2c589..d885976012 100644 --- a/docs/architecture/sdlc-pipeline.md +++ b/docs/architecture/sdlc-pipeline.md @@ -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//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 @@ -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-.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. ## HITL (Human-in-the-Loop) Mechanism diff --git a/docs/guides/concurrent-execution.md b/docs/guides/concurrent-execution.md index fa0bc895fa..72339d841f 100644 --- a/docs/guides/concurrent-execution.md +++ b/docs/guides/concurrent-execution.md @@ -970,6 +970,14 @@ Mechanics: - `.egg-state/agent-outputs/-refine-*.{md,json}` and `-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-.json` shape (with the legacy + bare `.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`,