Sprint

Step 5: Handle Merge Sequencing

Default policy: merge as each pipeline completes. When a pipeline finishes Phase 7 and is marked merge-ready, merge it immediately — don't wait for the batch. Faster feedback, less idle time, and the rebase cost on subsequent pipelines is paid as they reach merge-ready anyway (each one runs its own /wrapup Step 2 rebase-onto-main guard, so main drift is handled automatically).

Ordering enforcement (REQ-483). When /manifest's verdict (Step 2 pre-flight) shows footprint overlaps in the batch, merge the overlapping REQs in its deterministic order (earliest-published first, lower REQ tiebreak — BR-8) instead of as-they-complete, and gate each merge: git -C <worktree> fetch origin <integrationBranch> (refresh the tip), source partials/trial-merge.sh, then adlc_trial_merge "<worktree>" origin/<integrationBranch> before adlc_forge_pr_merge. rc=1 → hold that REQ (blocked, surfaced for rebase); rc=0 → merge; rc=2/3 → failed (setup error, not a conflict). For overlapping single-repo REQs (whose pipeline-runners would otherwise self-merge as they complete), the orchestrator MUST hold the later-ranked one until the earlier merges — do not let both self-merge, or both could pass a stale-tip gate and collide at merge. Non-overlapping REQs still merge as they complete (parallel-by-default). Serializes merges, never implementation; computed in orchestrator code, not delegated (BR-10).

Who actually performs the merge depends on REQ topology (see ~/.claude/agents/pipeline-runner.md Phase 8):

• Single-repo REQ (one touched repo in pipeline-state.repos): the pipeline-runner agent already merged its own PR in its Phase 8 and reports merged. The orchestrator's job here is to verify (per Step 4 verify gate) and move on — do NOT re-merge. If verification shows the PR is still OPEN despite the merged claim, fall through to the cross-repo flow below and merge it yourself.
• Cross-repo REQ (multiple touched repos): the pipeline-runner stops at Phase 7 and reports pr-ready. The orchestrator owns merge sequencing and walks the per-REQ mergeOrder itself.

The sequential flow when the orchestrator is the merge actor (cross-repo, or single-repo fallback after a failed agent merge):

1. Merge the PR: adlc_forge_pr_merge --squash --delete-branch (source partials/forge.sh with the guarded spelling from conventions.md "Bash in skills" in the same fence)
2. Pull main: git checkout main && git pull
3. Move on — other pipelines keep running in the background

Post-merge unblock pass (REQ-485 — self-healing serialization). REQ-483 holds a REQ with a blocked terminal when its pre-merge trial-merge conflicts (rc=1) against an ahead REQ. Today that held REQ is surfaced for a human to rebase + resume. For an unattended /sprint batch, immediately after the orchestrator confirms REQ-A merged (the merge above landed AND repos[A].merged = true was written), run an unblock pass so the batch self-heals — in place of parking the held REQ for a human:

1. Find held REQs (BR-2, BR-11 anchor). Scan every other in-flight REQ's pipeline-state.json for a still-present blockers entry with blockedBy == A. Consider ONLY REQs whose blockers entry exists — a cleared entry means already-resumed-and-merged, so it is never re-processed (the BR-6 idempotency anchor). With nothing newly merged, this scan finds nothing and the pass is a no-op (deterministic + idempotent).
2. Order + serialize (BR-6). If more than one REQ is held on A, order them by REQ-483's deterministic rule (earliest-published PR first, lower REQ tiebreak) and process them one at a time — the held REQs may themselves overlap, so resuming two concurrently would re-introduce the merge race REQ-483 eliminated.
3. Degrade-safe pre-check (BR-7). For each held REQ, read its worktree path from its own pipeline-state.json.repos[<id>].worktree and its currentPhase. If the worktree has been torn down OR currentPhase is unrecorded, skip with a one-line advisory manual resume needed for REQ-x (worktree gone / phase unrecorded) — never an error or a batch crash.
4. Rebase ONLY the held REQ's own worktree (BR-2, BR-5). Fetch and rebase in the held REQ's worktree — mutate nothing else (never REQ-A's branch/PR, never a third REQ's worktree):

   # held=<held REQ id>, hw=<its repos[<id>].worktree>, ib=<integrationBranch>
   git -C "$hw" fetch origin "$ib" >/dev/null 2>&1
   if git -C "$hw" rebase "origin/$ib" >/dev/null 2>&1; then
     echo "rebase-clean: $held"          # → step 5 (auto-resume)
   else
     git -C "$hw" rebase --abort >/dev/null 2>&1 || :   # non-mutating restore
     echo "rebase-conflict: $held"       # → step 6 (re-halt)
   fi

   (Write any list-iteration over held REQs split-free — printf '%s\n' "$held_ids" | while read -r held, every path quoted — so it behaves identically under the executor shell, LESSON-329.)
5. Clean rebase → auto-resume (BR-3). Re-dispatch a fresh pipeline-runner for the held REQ exactly as in Step 3, using its existing worktree (its pipeline-state.json already records currentPhase, so the runner resumes from there). The runner re-runs the now-passing Phase-8 trial-merge gate and proceeds to merge; on that merge it sets repos[<id>].merged = true AND clears its blockers entry (BR-11). Treat this re-dispatched runner like any other Step 3 pipeline (verify its terminal claim per Step 4). Legacy-engine degrade (OQ-1 default / BR-7): the common halt is the Phase-8 pre-merge gate, and a fresh runner from currentPhase resumes it cleanly — so the common case auto-resolves. If a held REQ halted mid-phase in a way the legacy engine cannot cleanly re-dispatch from, degrade to the surface-to-human advisory rather than forcing a resume.
6. Conflicting rebase → re-halt, never auto-resolve (BR-4, BR-10). The rebase --abort already restored the worktree. Increment the held REQ's blockers.rebaseAttempts. If it is below the retry bound (default 1, overridable via .adlc/config.yml key auto_rebase_max_attempts; missing → 1), re-halt with holdState: "held" carrying the NOW-materialized conflict files and surface a human-resolution prompt. If it is at/above the bound, mark holdState: "needs-manual-rebase", set resolvedBlocker: A, switch blockedBy to a manual/self sentinel (so this scan never re-picks it up — REQ-485 OQ-6), and surface for manual handling. Never auto-resolve, -X force, or "merge anyway" (ethos #6). BR-10 counts attempts per blocker-merged event. When a human resolves the materialized conflict and the REQ resumes, the resume path appends a conflictsResolved entry to that REQ's pipeline-state.json (resolvedBy: "user", schema in agents/pipeline-runner.md — BUG-212); this pass itself appends nothing, because it never resolves.

Blocker-failed release (REQ-485 OQ-5 / ADR-8). A blocker can also end failed/abandoned within the run — its PR will never merge, so no merge event fires the pass above and a REQ held solely on it would sit blocked to batch-end. When a REQ-A terminal is failed, for every held REQ whose ONLY live blockedBy is A (no other live blocker), treat the dead blocker as cleared and run the SAME rebase+resume path (steps 3–6 above) — its ordering constraint has dissolved. A REQ with other live blockers stays held. This is the in-run analogue of REQ-483's stale-PR safety. (Place this check where Step 4.6 / the merge loop observes a REQ's terminal state.)

Batch mode (only when N ≥ 3): when the sprint has 3 or more pipelines AND the orchestrator has strong prior knowledge that their diffs overlap (same files, same modules), switch to batching:

1. Wait for all pipelines to reach merge-ready state (Phase 7 complete, blocked, or stopped)
2. Sort merge-ready pipelines by:
   • Independent changes first (no overlapping files), then
   • Lower REQ numbers first (tie-breaker)
3. Merge sequentially from the sorted list:
   • Merge the first PR
   • Pull main
   • For each subsequent pipeline, its /wrapup Step 2 will re-fetch and rebase onto the new main before merging
   • If any rebase hits conflicts, skip that pipeline and surface to the user — continue with the rest

Batch mode is the exception, not the rule. If you're uncertain whether diffs overlap, default to merging as each completes.

Step 6: Sprint Summary

After all pipelines complete (or are stopped), produce a sprint summary:

## Sprint Summary — [date]

### Completed
| REQ | Title | PR | Duration | Tasks | Lessons |
|-----|-------|----|----------|-------|---------|
| REQ-091 | Feature A | #42 | 25m | 4/4 | 2 |
| REQ-093 | Feature C | #44 | 18m | 3/3 | 1 |

### Blocked / Stopped
| REQ | Title | Phase | Blocker |
|-----|-------|-------|---------|
| REQ-092 | Feature B | 5/9 | Test failure in auth middleware |

### Knowledge Captured
- LESSON-048: [title from REQ-091 wrapup]
- LESSON-049: [title from REQ-091 wrapup]
- LESSON-050: [title from REQ-093 wrapup]

### Metrics
- Total duration: 32 minutes
- REQs shipped: 2/3
- Tasks completed: 7
- Lines changed: +420 / -85
- Lessons captured: 3

Self-healing serialization (REQ-485)

REQ-483 made a /sprint batch enforce merge ordering: a REQ whose pre-merge trial-merge conflicts (rc=1) against an ahead REQ is held with a blocked terminal. REQ-485 makes the batch self-heal that hold, so an unattended batch ("launch it and walk away") does not sit idle behind a human nudge. The contract, across both engines:

• The trigger is blocker-merged → rebase-held-REQ → resume (BR-1, BR-2, BR-3). Immediately after the orchestrator merges REQ-A within the run, it runs the post-merge unblock pass (legacy: Step 5; workflow: unblockHeldReqs after the merge barrier) over every REQ held with a still-present blockers entry where blockedBy == A. Each held REQ's OWN worktree is rebased onto the refreshed integration branch; a clean rebase resumes it from its recorded currentPhase (re-running the now-passing trial-merge gate, which proceeds to merge).
• A conflicting rebase is never auto-resolved (BR-4). The rebase is --aborted (worktree restored, non-mutating) and the REQ is re-halted carrying the NOW-materialized conflict files, surfaced for human resolution. Nothing is force-merged or "merged anyway" (ethos #6).
• Only the held REQ's own branch/worktree is mutated (BR-5). The pass never touches the blocker's branch/PR (already merged) or any third REQ's worktree. Ordering is derived from merge events, never asserted by mutation.
• Deterministic, idempotent, serialized (BR-6). With nothing newly merged the pass is a no-op. Multiple REQs held on one blocker unblock in REQ-483's deterministic order (earliest-published PR, lower REQ tiebreak) and are processed one at a time — held REQs may themselves overlap, so concurrent resume would reintroduce the merge race. The pass considers ONLY REQs whose blockers entry is still present (cleared on a successful resume — BR-11), which is the idempotency anchor.
• Degrade-safe (BR-7). A held REQ whose worktree has been torn down or whose currentPhase is unrecorded is skipped with a manual resume needed for REQ-x advisory — never an error or a batch crash. Per OQ-1, the workflow engine is the primary auto-resume path; the legacy engine auto-resumes the common Phase-8-gate halt by re-dispatching a pipeline-runner from currentPhase and degrades to surface-to-human for any halt it cannot cleanly re-dispatch.
• Retry-bounded (BR-10). A persistently-conflicting rebase stops after auto_rebase_max_attempts (default 1, overridable in .adlc/config.yml) and is marked needs-manual-rebase — not auto-re-triggered by future merges. Attempts are counted per blocker-merged event.
• Blocker-failed release (OQ-5). If a blocker ends failed/abandoned within the run (its PR will never merge), a REQ held solely on it is released and re-attempted on the same rebase+resume path — its ordering constraint has dissolved. A REQ with other live blockers stays held.

Scope (v1). Within-/sprint-run only (BR-9): the orchestrator merged the blocker itself, so "blocker-merged" is a known local event — there is no cross-session watch/poll. A blocker merged by a different session stays manual. Solo /proceed (not under /sprint) is unchanged — manual resume, because the human is present (BR-1). Rebase conflicts are always human-resolved by the machinery (BR-4) — this pass only detects and restores, never resolves. BR-4 binds the unblock pass; it was never written about a runner's own Phase 7/8 rebase, and reading it that way left the most common mid-batch case unsettled (BUG-207). That case is now explicit in agents/pipeline-runner.md "Bounded resolution": under /sprint a runner may resolve an append-point collision on its own branch — both sides purely adding self-contained, delimiter-balanced lines, checked by partials/conflict-bound.sh, resolved keep-both, verified, recorded — and halts blocked on anything else. Solo /proceed is unchanged: halt and ask. Every resolution that does happen during a run — by a human on a re-halt, or by a runner in its own Phase 7/8 — is recorded in that REQ's pipeline-state.json.conflictsResolved at the moment it happens (BUG-212), so /status can answer "which runs resolved a conflict, and was it verified?" without reading narrative.

Error Handling

• Agent crash: If a background agent stops unexpectedly, check its last pipeline-state.json state. Report the failure and offer to relaunch from the last completed phase.
• Worktree conflict: If a worktree already exists for a REQ, check if there's an active pipeline. If abandoned (no recent state update), offer to clean up and restart.
• Resource exhaustion: If the system is slow or agents are timing out, reduce concurrency — pause lower-priority pipelines and let active ones finish first.
• Merge conflict during sequencing: Stop the conflicting pipeline, surface the conflict to the user, and continue merging other completed pipelines.

Cross-Repo Sprints

/sprint supports sprints that include cross-repo REQs. Cross-repo handling is delegated entirely to each /proceed pipeline — /sprint itself still originates every pipeline from the same repo (the one it was invoked in), but each /proceed reads .adlc/config.yml and may create worktrees in sibling repos as needed.

Collision avoidance: concurrent cross-repo REQs that share a sibling each create their own worktree at <sibling-path>/.worktrees/REQ-xxx (different REQ numbers → different paths → no collision). If two REQs accidentally try to use the same REQ number, git worktree add fails loudly on the second — surface that in the pre-flight report.

Pre-flight check for cross-repo sprints: for each REQ whose frontmatter or tasks declare sibling repos (via repo: values from .adlc/config.yml), verify in Step 2:

• Every declared sibling is present on disk and is a git repo
• Each touched sibling's main is clean or has no conflicting branch

Sibling-repo worktree collisions are deferred to /proceed Step 0 (per REQ-263 architecture.md "Cross-repo behavior" + OQ-2 default). The /sprint Step 2 collision check (item 4 above) intentionally scans only the primary repo; sibling collisions are caught by /proceed Step 0's per-repo git worktree add validation gate, which runs the same fail-loud halt with the same error format. Do not extend Step 2 to scan siblings without a deliberate decision — it would duplicate the validation logic ADR-1 was designed to keep in one place.

If any check fails, mark the REQ ineligible with a specific issue in the pre-flight table. The user may choose to clean up and retry, or exclude that REQ from the sprint.

Dashboard: the sprint dashboard's per-REQ row should show "primary repo → N touched" when a REQ is cross-repo (e.g., api → 3 touched) so the user sees fleet-wide activity at a glance, not just local work.

Merge sequencing: cross-repo REQs produce multiple PRs, merged in the REQ's own mergeOrder (by its /proceed Phase 8). /sprint still merges REQs "as each pipeline completes" — a completed cross-repo pipeline means all its per-repo PRs have landed. Only the next REQ's pipelines need to re-fetch main.

What This Skill Does NOT Do

• It does not create specs — run /spec first for each REQ
• It does not replace /proceed — it orchestrates multiple /proceed sessions
• It does not originate REQs from different primary repos in a single sprint — every REQ in one /sprint invocation is assumed to originate from the repo the command was run in. Cross-repo REQs whose primary is a sibling must be sprinted from that sibling instead.
• It does not require the workflow engine. Dynamic Workflows is a research-preview, plan-gated capability that can be absent (headless/cron runs, non-qualifying plans), so the workflow engine is never assumed present: /sprint runs the workflow engine only when the Workflow tool is invocable and the run opts in (--workflow, or once it graduates to default), and otherwise runs the legacy background-runner engine — the always-available, behavior-unchanged fallback. A --workflow request with the tool unavailable does not fail the sprint; it falls back to legacy with an explicit notice.
• It does not make the two engines diverge in outcome. The workflow engine only changes how the pipeline is dispatched (restored per-REQ fan-out); it does not add, skip, or reorder pipeline phases relative to the legacy engine, and it does not gate the legacy engine behind the workflow engine.
• It does not auto-resume a REQ blocked by a cross-session merge (REQ-485 BR-9). Self-healing serialization triggers only on a blocker this /sprint run merged itself — a known local event. There is no cross-session watch/poll; a blocker merged by a different session stays manual until a human resumes it.
• It does not auto-resume a solo /proceed (not under /sprint) that hit a trial-merge block (REQ-485 BR-1). The human is present in that path, so the held REQ keeps today's manual rebase-and-resume behavior; only an orchestrated /sprint batch self-heals.
• It does not auto-resolve a rebase conflict (REQ-485 BR-4). A conflicting auto-rebase is --aborted and re-halted for human resolution; the machinery only detects and restores, never resolves, forces, or merges-anyway.