From eb359048dc2e05a19ed5e2cc06ecd10103f6a096 Mon Sep 17 00:00:00 2001 From: jwbron <8340608+jwbron@users.noreply.github.com> Date: Wed, 13 May 2026 05:55:38 +0000 Subject: [PATCH 1/2] docs: update sdlc-pipeline arch for #2685 context PR and PR phase changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document that the context PR now includes the contract JSON (resolved via the contract loader so integer issue identifiers use the canonical issue-.json path), and that the PR phase suppresses the legacy → main auto-PR in slice-DAG mode where per-slice PRs already exist stacked on the context PR. Authored-by: egg --- docs/architecture/sdlc-pipeline.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/architecture/sdlc-pipeline.md b/docs/architecture/sdlc-pipeline.md index c083d2c589..c2fce99a52 100644 --- a/docs/architecture/sdlc-pipeline.md +++ b/docs/architecture/sdlc-pipeline.md @@ -132,8 +132,10 @@ 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 resolved via the loader so +> integer issue identifiers map to the canonical `issue-.json` +> path) 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 @@ -143,7 +145,10 @@ The contract is a JSON document tracking the complete state of an issue through > (#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.) +> backstop. #2685 added contract JSON to the context PR diff and +> suppressed the legacy ` → main` auto-PR in PR phase +> for slice-DAG pipelines — per-slice PRs already exist stacked on the +> context PR, so the program-level auto-PR is redundant.) ## HITL (Human-in-the-Loop) Mechanism From 8a913aab9ec97fa1b9116340b08682082b49a280 Mon Sep 17 00:00:00 2001 From: "egg-reviewer[bot]" <261018737+egg-reviewer[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 06:15:40 +0000 Subject: [PATCH 2/2] docs: extend #2685 doc sync to sibling architecture pages Reviewer flagged that the original PR only updated sdlc-pipeline.md but the same context-PR artifact list is enumerated in two other docs that #2685 made stale, and the PR-phase auto-PR is described unconditionally in orchestrator.md without mentioning the slice-DAG skip: - docs/architecture/orchestrator.md: add a 'contract JSON resolved via get_contract_path' bullet to the enumerated context-PR artifact list, and a paragraph under 'Special case: PR phase' noting the slice-DAG auto-PR suppression (_should_skip_pr_phase_auto_pr) and the babysit / contract-load fail-safe behaviors. - docs/guides/concurrent-execution.md: same contract JSON bullet on the matching enumerated list under 'Context PR is opened first'. - docs/architecture/sdlc-pipeline.md: split the trailing parenthetical so the #2685 sub-clause is its own paragraph (reviewer nit on the compound parenthetical chaining two #2593 and one #2685 sub-clause inside one set of parens). Simplify the earlier mention of the contract JSON in the artifact line to point at the new paragraph, avoiding duplication of the loader rationale. Authored-by: egg --- docs/architecture/orchestrator.md | 3 +++ docs/architecture/sdlc-pipeline.md | 19 ++++++++++++------- docs/guides/concurrent-execution.md | 8 ++++++++ 3 files changed, 23 insertions(+), 7 deletions(-) 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 c2fce99a52..d885976012 100644 --- a/docs/architecture/sdlc-pipeline.md +++ b/docs/architecture/sdlc-pipeline.md @@ -133,9 +133,8 @@ The contract is a JSON document tracking the complete state of an issue through > 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 resolved via the loader so -> integer issue identifiers map to the canonical `issue-.json` -> path) onto a temp worktree committed to that branch, opens a +> 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 @@ -145,10 +144,16 @@ The contract is a JSON document tracking the complete state of an issue through > (#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. #2685 added contract JSON to the context PR diff and -> suppressed the legacy ` → main` auto-PR in PR phase -> for slice-DAG pipelines — per-slice PRs already exist stacked on the -> context PR, so the program-level auto-PR is redundant.) +> 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`,