feat(linear): re-integrate dependent child PRs when a predecessor changes (#247 A6)

[isadeks]

Component

API or orchestration, Agent runtime

Describe the feature

For #247 stacked child PRs (A4): when a lower child PR merges, its dependent PRs must be rebased onto the new base and force-pushed so the stack stays correct. Automate this so the human never hand-rebases.

The subtlety this issue exists to handle: GitHub auto-retargets a dependent PR's base pointer when the merged head branch is deleted, but it does not rewrite the dependent branch's commits. So an explicit restack is still required even though the base flips on its own.

Background — why a restack is needed (not just GitHub's auto-retarget)

With a stack A ← B ← C (B's branch cut from A's, C's from B's):

• GitHub retargets on branch delete, not on merge. Per GitHub's documented behavior: "If you delete a branch that has open pull requests based on it, GitHub automatically updates any such pull requests, changing their base branch to the merged pull request's base branch." — https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/deleting-and-restoring-branches-in-a-repository
  So merging A → main and deleting feat/A flips B's base from feat/A to main automatically.
• But the base flip alone leaves B's commits stale. B's branch still physically contains A's old commits; until B is rebased onto the new base, its diff double-counts A's changes (and can conflict). As the stacked-diffs literature puts it, "later diffs cannot be landed to the main branch while they don't contain changes from the updated Diff 1" — resolved by rebasing up the stack. — https://newsletter.pragmaticengineer.com/p/stacked-diffs
• Prior art for the automated restack: Meta's ghstack (https://github.com/ezyang/ghstack) lands one PR and rewrites the rest of the stack's bases so it stays correct; Graphite automates the same restack-on-merge. This issue is the ABCA-native equivalent driven off a webhook instead of a developer CLI.

Net: the correct merge model is bottom-up, one PR at a time, delete the head branch to trigger retarget, then restack the dependents' commits. This issue automates the restack step.

Proposed solution

A restack reconciler triggered on a child PR closed+merged GitHub webhook:

1. Find dependent child branches in the orchestration whose base was the merged branch.
2. git rebase --onto <new-base> <old-base> <dependent-branch> + force-push.
3. Conflict-free → fully automatic (the common case when the lower PR merged unchanged).
4. Conflict case → spawn an AGENT task to resolve it (ABCA-native; do NOT escalate to the human). The agent rebases, resolves conflicts preserving both intents, and pushes. The PR's normal human review remains the safety net for a mis-resolved semantic conflict — so the resolution is automated, the result is still reviewed before merge.

Acceptance criteria

• On a child PR merge, conflict-free dependents are rebased + force-pushed automatically (no human action).
• A conflicting rebase spawns an agent task that resolves + pushes; the dependent PR ends in a reviewable state.
• Idempotent / safe under webhook redelivery.
• Bounded by max_sub_issues stack depth.

Depends on

• feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 A4 (stacked base-branch targeting — creates the stacks this restacks)

Out of scope

• Auto-MERGE of the stack (separate follow-up — gated on approvals + CI via merge queue).

[isadeks]

Rescoped after A4 (#247) landed

A4 (stacked base-branch targeting) now handles the initial predecessor integration:

• linear child → branches off its predecessor's branch (sees its code)
• diamond child → branches off main and merges all predecessor branches in at setup time

So "give a child its predecessors' code" is already done. What remains for this issue is narrower: re-integration when a predecessor changes AFTER the dependent was already released.

Remaining scope

When a lower PR is edited in review (or merged) after its dependent child already started/opened a PR, the dependent is now on stale predecessor code. Handle it:

1. On a predecessor PR synchronize/closed(merged) webhook, find dependent children whose base/merged-in branch changed.
2. Rebase/re-merge the dependent branch onto the updated predecessor + force-push.
3. Conflict → spawn an agent task to resolve (ABCA-native; not escalated to human — PR review is the safety net). Clean re-merge → automatic.
4. Idempotent + bounded by max_sub_issues.

No longer in scope (done in A4)

• Initial branch-from-predecessor / merge-predecessors-in at release time → A4.

Depends on

• feat(linear): parent/sub-issue orchestration with dependency-aware child tasks #247 A4 (creates the stacks/merges this maintains)
• fix(linear): orchestration reconciler loses terminal events during outages (no stranded-orchestration backstop) #303 stranded-orchestration sweep (liveness backstop for a stuck re-merge)

Out of scope

• Auto-MERGE of the stack (separate follow-up; gated on approvals + CI via merge queue).

Related

• docs/research/a4-stacked-base-branch-design.md ("Open risk: re-merge churn")
• docs/research/stacked-pr-merge-practices.md