Define full merge train semantics

[cbusillo]

Objective

Define Launchplane's full merge train semantics as batch candidate validation followed by PR-native sequential landing. This issue resolves the naming/product ambiguity: the current deployed system is an ordered merge queue; the full train target validates a combined candidate containing multiple queued PRs, then lands the original PRs in order when the candidate passes.

Finish Line

The merge-train contract, docs, and plan define the batch train model: collect eligible queued PRs, build one combined candidate from base + PRs in order, run CI on that candidate, merge original PRs in order after the candidate passes, and split/fallback when the candidate fails.

Current Status

State: Done via PR #608, merged to main at 4aca673 and deployed. Docs and contracts now define Level 1 ordered queue vs full batch merge train semantics, including batch candidates and PR-native landing plans.
Next action: Use #604/#605 for implementation wiring; no remaining action on this semantics issue unless review finds a terminology gap.
Blocked by: None.
Last verified: Main CI, Security, CodeQL, and Deploy Launchplane succeeded for 4aca673 on May 14, 2026.

Scope

• In: terminology, product contract, invariants, state diagrams, policy semantics, and docs updates.
• Out: implementation of queue records, GitHub refs, scheduler, or UI beyond documentation needed for alignment.

Acceptance Criteria

• Docs name the current system as the sequential/ordered merge queue baseline.
• Docs define the full train as batch candidate validation plus PR-native sequential landing.
• Invariants define what must be true before merging each original PR after batch CI passes.
• Candidate ref strategy is selected and documented.
• Failure strategy is selected: binary split, one-at-a-time fallback, or both.
• Policy terms define pause, reflow, split, dequeue, cancellation, and stale candidate behavior.
• Per-position speculative validation is explicitly deferred or scoped as a later enhancement.

Relationships

• Blocks the implementation sub-issues in the full merge train plan.
• Related to Build Launchplane sequential merge train #410.

Validation

• Docs review against current code behavior.
• At least one example two-PR train scenario is described end-to-end.

Decisions

• No production hardcoded repositories or fallback policy examples.
• Full batch train semantics remain flat: train candidates target the protected base branch, are combined into a batch candidate, and are landed through normal PR-native merge paths.
• Stacked PR support is a pre-admission normalization workflow, not a change to the core batch train landing contract.
• A collapsed stack contributes one train entry: the root PR targeting the base branch after it contains the child stack changes and has fresh required checks.

Open Questions

• Should batch candidates use temporary branches, hidden refs, or draft PR branches?
• Should blocker isolation start with binary split or one-at-a-time fallback?
• Should Launchplane merge original PRs using GitHub's PR merge API only, or can it ever merge a validated candidate branch directly?
• How should Launchplane prove each original PR still corresponds to the tested batch candidate before PR-native landing?