Support stacked PR collapse before merge-train admission

[cbusillo]

Objective

Add stacked pull request handling as a pre-train normalization step for the
full Launchplane merge train. A same-repository linear stack should be detected,
collapsed from leaf to root by merging child PR branches into parent PR
branches, then the root PR targeting the protected base branch should be
required to go green before normal batch-train admission.

This keeps the batch merge train DRY and focused on flat PRs targeting the base
branch, while giving agents a safe path to land stacked work without teaching
the train to natively land arbitrary PR graph topology.

Finish Line

Launchplane collapses same-repo linear stacked PRs into the root PR, waits for fresh root checks, and admits only that root into the flat batch merge train.

Current Status

State: Live pilot completed successfully. Launchplane collapsed the real codex-skills stack (#61 -> #60 -> #59), waited for the root PR to go green, built and observed a flat batch candidate, and landed root PR #59 through the service-backed GitHub Actions/OIDC merge-train workflow. Child PRs #60 and #61 were resolved as merged during collapse, and codex-skills main now points at merge commit c704e4d7a8e3975eef38fdce5e0446103b5ce335.
Next action: Update the codex-skills Launchplane skill so agents know the root ready-to-merge label drives stack collapse, root train admission, and child PR resolution after root landing.
Blocked by: Not blocked for stack-collapse behavior. Remaining work is documentation/agent guidance and then broader flat-train scheduler/controller automation in #605/#601.
Last verified: 2026-05-14. Evidence: stack-collapse execute record merge-train-stack-collapse-plan-20260514T222707Z-d13946c496d3388e; batch candidate observed as passed in merge-train-batch-candidate-20260514T223411Z-5b8899e860ef704c; landing record merge-train-batch-landing-plan-20260514T223626Z-d4b60cf568a75c7e; Launchplane workflow run 25889612288; codex-skills CodeQL-on-main run 25889619001; Launchplane health ok with Postgres backend.

Scope

• In: stack discovery, same-repo linear-stack validation, DB-backed collapse
  plan/run records, expected-SHA guards, branch mutation safety, root PR
  required-check gating, child PR comments/labels/closure policy, codex-skills
  pilot validation, and docs/operator feedback.
• Out: native arbitrary DAG landing inside the batch train, forked PR stack
  mutation, hardcoded repository defaults, file-backed train policy, bypassing
  required checks, and merging stack children directly into the protected base
  branch.

Acceptance Criteria

• GitHub snapshot/read model can see relevant open PRs beyond only the base
  branch and records head_ref, base_ref, head repo, base repo, head SHA,
  and base SHA.
• Stack discovery accepts only a single same-repository linear chain rooted
  at a PR targeting the train base branch.
• Ambiguous stacks, forked stacks, missing write permission, sibling
  children, cycles, conflict states, or unsupported branch protection states
  fail closed with operator-visible reasons.
• Collapse plans are DB-backed records containing root PR, child order,
  expected SHAs, intended branch mutations, policy digest, and idempotency
  key.
• Collapse execution mutates feature branches only after explicit stored
  operator/agent intent and compare-and-swap style SHA checks.
• Collapse proceeds leaf-to-root, rechecking each parent/child SHA before
  mutation and recording any conflict at the exact child/parent boundary.
• After collapse, Launchplane waits for the root PR's current head SHA to
  satisfy required checks against the protected base branch before queue
  admission.
• Only the root PR enters the existing batch merge train; child PRs do not
  appear as independent train entries after collapse.
• Child PR lifecycle is explicit after root landing: comment/link the root
  landing, apply a clear label/status, and close or otherwise resolve them
  according to stored policy.
• Existing flat batch merge-train behavior remains unchanged for ordinary
  PRs targeting the base branch.
• The first live pilot uses codex-skills with a synthetic linear stack and
  proves stale-head, ambiguous-stack, conflict, and success paths.
• When this lands, update the codex-skills Launchplane skill so agents know
  to use stack collapse before requesting train admission.

Relationships

• Part of Build full Launchplane merge train #601.
• Builds on the batch candidate and PR-native landing primitives already merged
  for the full merge train.
• Related to Automate full merge train scheduler #605, but not blocked by scheduler automation; stack collapse is a
  pre-admission workflow.
• related: Automate full merge train scheduler #605 - Automate full merge train scheduler #605

Validation

• Unit tests for stack graph discovery, linearity checks, unsupported cases,
  stale SHA guards, and child PR disposition decisions.
• GitHub adapter tests for fetching all relevant PRs and reading head/base repo
  and ref fields.
• Contract/storage tests for collapse plan and collapse run records.
• Workflow tests showing collapsed root admission reuses existing batch train
  code paths.
• Live codex-skills pilot with a synthetic stack rooted at main.

Decisions

• Stack handling is pre-train normalization, not native stacked landing inside
  the batch train.
• The batch train remains flat: candidates admitted to the train must target the
  protected base branch.
• Collapse mutates feature branches, so it requires explicit stored intent and
  fresh SHA guards.
• Synthetic rollup PRs remain a fallback option if branch mutation proves too
  risky for a repository.
• No production code may hardcode codex-skills or any other real repository;
  codex-skills is only the first operator-selected live test bed.

Open Questions

• What exact stored intent grants Launchplane permission to mutate stack feature
  branches: label on every PR, root-only label plus policy, or explicit operator
  API action?
• Should child PRs be closed automatically after the root lands, or left open
  with a resolved-by-root label and comment for operator review?
• Which branch protection combinations are supported for the first pilot, and
  which should be reported as unsupported?
• Should collapse be implemented before Automate full merge train scheduler #605 scheduler automation, or after the
  scheduler can run multi-phase workflows without manual record IDs?

[cbusillo]

Production deploy fixed by #619. Follow-up: verify whether failed deploy created launchplane_merge_train_stack_collapse_plans before crashing; if so, add missing indexes with CREATE INDEX IF NOT EXISTS launchplane_merge_train_stack_collapse_repository_base_idx ON launchplane_merge_train_stack_collapse_plans (repository, base_branch, updated_at DESC) and CREATE INDEX IF NOT EXISTS launchplane_merge_train_stack_collapse_plans_status_idx ON launchplane_merge_train_stack_collapse_plans (status, updated_at DESC). This is performance/operability, not correctness.

[cbusillo]

State: Live pilot completed successfully. Launchplane collapsed the real codex-skills stack (#61 -> #60 -> #59), waited for the root PR to go green, built and observed a flat batch candidate, and landed root PR #59 through the service-backed GitHub Actions/OIDC merge-train workflow. Child PRs #60 and #61 were resolved as merged during collapse, and codex-skills main now points at merge commit c704e4d7a8e3975eef38fdce5e0446103b5ce335.
Next action: Update the codex-skills Launchplane skill so agents know the root ready-to-merge label drives stack collapse, root train admission, and child PR resolution after root landing.
Blocked by: Not blocked for stack-collapse behavior. Remaining work is documentation/agent guidance and then broader flat-train scheduler/controller automation in #605/#601.
Last verified: 2026-05-14. Evidence: stack-collapse execute record merge-train-stack-collapse-plan-20260514T222707Z-d13946c496d3388e; batch candidate observed as passed in merge-train-batch-candidate-20260514T223411Z-5b8899e860ef704c; landing record merge-train-batch-landing-plan-20260514T223626Z-d4b60cf568a75c7e; Launchplane workflow run 25889612288; codex-skills CodeQL-on-main run 25889619001; Launchplane health ok with Postgres backend.