[issue-3393][slice-5/7] Cross-repo merge-sequencing hold (cq-1...

[james-in-a-box]

Implement the operator-resolved (HITL cq-1) two-tier merge-sequencing hold. Tier A (automated): a cross-repo dependent slice is developed in parallel, its PR opens as draft, and the orchestrator polls the upstream slice's PR merge state and auto-marks the dependent PR ready once the upstream merges — no HITL for plain merge ordering. Tier B (HITL): a distinct hold type for beyond-merge-state conditions (release/publish of the upstream repo, a version-pin choice, or a genuine cannot-continue development block) is held and released by a HITL decision, never programmatic detection. Dependencies gate merge-readiness, not development.

Base PR: #3418

What's in this PR

Commits (5):

• Persist BRC history for slice-5 (Slice PRs are missing analysis/plan docs and all BRC history; need a 'context' PR for refine+plan phases plus per-slice BRC in each slice PR #2548)
• Slice-5 (Feature: multi-repo pipelines — coordinated PRs across repositories in one pipeline #3393): honour the human's selected hold option (reviewer_code_holistic v1 NACK)
• Slice-5 (Feature: multi-repo pipelines — coordinated PRs across repositories in one pipeline #3393): converge with tester seams (task-5-1/5-2)
• Slice-5 (Feature: multi-repo pipelines — coordinated PRs across repositories in one pipeline #3393): cross-repo merge-sequencing hold (cq-1 two-tier) (task-5-1, task-5-2)
• test(Feature: multi-repo pipelines — coordinated PRs across repositories in one pipeline #3393): slice-5 cross-repo merge-sequencing hold tests (task-5-3)

.egg-state/brc-history/3393-implement-slice-5.json | 2290 +++++++++++++++++++++++++++++++++++++
 .egg-state/brc-history/3393-implement-slice-5.md   | 2465 ++++++++++++++++++++++++++++++++++++++++
 gateway/gateway.py                                 |  170 +++
 orchestrator/cross_repo_merge_gate.py              |  423 +++++++
 orchestrator/env_config.py                         |   13 +
 orchestrator/gateway_client/__init__.py            |    2 +
 orchestrator/gateway_client/_pr.py                 |   98 ++
 orchestrator/routes/pipelines.py                   |  320 ++++++
 orchestrator/tests/test_pipelines.py               |  431 +++++++
 9 files changed, 6212 insertions(+)

This slice

Cross-repo merge-sequencing hold (cq-1 two-tier)

Files affected:

• orchestrator/routes/pipelines.py
• orchestrator/stacked_pr_reconciler.py
• orchestrator/gateway_client/_pr.py
• gateway/gateway.py
• gateway/github_client.py
• orchestrator/tests/test_pipelines.py

Tasks (3) + acceptance criteria

• task-5-1: Implement Tier A (automated merge-ordering hold) with FULLY PINNED failure semantics (reviewer_plan R3 / architect aeb3528 layer_6). A dependency edge B→A is cross-repo iff resolve_slice_repo(A) != resolve_slice_repo(B). For such an edge: open B's PR as a DRAFT (already supported) while upstream A's PR is unmerged, and register an upstream-merge poll on the EXISTING reconcile cadence (extend orchestrator/stacked_pr_reconciler.py, or add a small cross_repo_merge_gate.py invoked from it — do not invent a new scheduler subsystem). PIN THREE SEMANTICS: (a) MERGE DETECTION uses the PR merged boolean / mergedAt (gh pr view --json state,mergedAt via a small gateway read verb), NOT head-SHA equality — a squash/rebase merge yields a merge-commit SHA ≠ the PR head, so SHA-equality would misfire. On merged⇒ call a NEW gateway verb mark_pr_ready(repo, pr_number) (wraps the existing gh pr ready, gateway/github_client.py:124) exposed via gateway/gateway.py + orchestrator/gateway_client/_pr.py, transitioning B draft→ready. (b) CLOSED-UNMERGED TERMINAL: if upstream A's PR reaches state=CLOSED with no mergedAt (closed, not merged), do NOT auto-ready B — escalate to a HITL hold (reuse the Tier-B hold mechanism / decision queue) and surface it on status. This is distinct from Tier B's beyond-merge-state conditions; it is the Tier-A failure terminal. (c) BOUND / TIMEOUT: bound the poll (a max wait / attempt budget); a never-merging upstream that exceeds the bound escalates to the same HITL hold rather than leaving B draft indefinitely. "If the auto path cannot resolve, fall through to the HITL hold rather than hanging" (architect layer_6). Development is NOT serialized — B is worked in parallel; only B's PR ready-state waits. Do NOT implement release/publish or version detection here (cq-1 forbids automating those signals).
  • Acceptance criteria: - A cross-repo dependent slice's PR opens draft and is auto-marked ready (via mark_pr_ready) only when the upstream PR's merged boolean / mergedAt is set — detection uses merged-state, NOT head-SHA equality. - Upstream PR CLOSED-not-merged does NOT auto-ready B; it escalates to a HITL hold and is surfaced on status. - The poll is bounded; exceeding the bound (never-merging upstream) escalates to the HITL hold, not an indefinite draft. - A new mark_pr_ready(repo, pr_number) gateway verb (wrapping gh pr ready) exists and is used for the transition. - Development is not serialized by the dependency; no release/publish/version auto-detection is added; same-repo dependencies and N=1 pipelines are unaffected.
• task-5-2: Implement Tier B (HITL beyond-merge-state hold). Add a distinct hold type that, for a dependency the plan marks as a beyond-merge-state condition (release/publish of the upstream repo, version-pin choice, or a genuine cannot-continue development block), holds the dependent slice's PR and releases it only via a HITL decision — never programmatic detection. Reuse the existing HITL decision mechanism (register_open_question / contract decision gate); default a cross-repo dependency to the Tier-A merge-state hold and escalate to Tier B only where the plan identifies such a condition. Wire it in orchestrator/routes/pipelines.py alongside Tier A.
  • Acceptance criteria: - A beyond-merge-state hold routes to a HITL decision and is released by human resolution, not auto-detection. - The default for a plain cross-repo dependency is the Tier-A merge-state hold; Tier B is opt-in per the plan. - The two hold kinds have two distinct release paths.
• task-5-3: Add tests in orchestrator/tests covering Tier A's happy path AND both failure terminals (reviewer_plan R3), plus Tier B. Mock the gateway PR-state read (state, mergedAt) and mark_pr_ready; do not hit the network. Cases: (a) upstream PR mergedAt set ⇒ dependent PR draft→ready via mark_pr_ready; assert detection keys off merged-state, NOT head-SHA (include a squash-merge case where the merge commit SHA ≠ PR head and the transition still fires). (b) CLOSED-UNMERGED: upstream state=CLOSED, mergedAt=null ⇒ NO auto-ready; a HITL hold is registered and surfaced on status. (c) NEVER-MERGING: poll exceeds the bound/timeout ⇒ HITL hold, dependent PR not left draft indefinitely. (d) development is not blocked while the hold is active. (e) Tier-B beyond-merge-state edge routes to a HITL decision and stays held until resolved (no auto-release). (f) same-repo dependency and N=1 pipeline take neither hold.
  • Acceptance criteria: - Tests assert Tier-A auto draft→ready on merged-state (incl. a squash-merge SHA≠head case), the CLOSED-unmerged⇒HITL terminal, and the never-merging⇒HITL bound/timeout terminal. - Tests assert non-blocking development, Tier-B HITL routing (no auto-release), and the same-repo / N=1 no-hold paths. - make test (narrowed) and make test-all green.

Stack

• Position: slice 5 of 7 in pipeline issue-3393
• Base PR: Multi-repo pipelines: coordinated PRs across repositories (#3393) #3418
• Stacked on top of egg/issue-3393/slice-4