Rebase PRs on new main, check if CI is healthy

[guettli]

How to handle PRs?

Rebase then on new main.

When the CI of a PR fails, then this should be fixed by an agent.

When CI is ok, merge them.

How to configure that?

Some projects want auto merge, some not.

[guettli]

Posting the plan as the issue comment.

---

Plan: Rebase PRs on new main, check CI is healthy

What already exists

• example/loop/agentloop/prompts/merge.md (added in PR Add loop/merge prompt that merges PRs once CI is green #39) already drives a "merge agent" via the loop/merge label triple. It finds the PR that closes the issue, polls CI, fixes failures on the branch, and merges. Failure → <!-- loop-route: escalate -->.
• code.md declares routes: merge: loop/merge, so the code prompt hands off to merge via the routing mechanism (added in PR Output-label routing: let a prompt pick the next label #34).
• A repo opts in to auto-merge today simply by including merge.md in its prompts/ directory and keeping the routes: merge: line in code.md. Opting out means deleting merge.md and removing that route line — the issue then stops at loop/code-done, where a human takes over.

So the per-project configuration question (auto-merge vs. manual) is already answered by the prompt-set the operator commits. This plan does not add a new config knob for that — it documents the existing one.

What is genuinely missing is the rebase behaviour: when main advances after the PR was opened, the PR can be behind, and the merge agent should bring it forward before merging (and re-run CI). The current merge.md does not say a word about that.

Concrete changes

All changes are prompt + documentation edits. No Go code changes.

1. Extend example/loop/agentloop/prompts/merge.md

Add an explicit "bring the PR up to date with the head branch" step at the top of the workflow, and tighten the loop so a rebase that breaks CI is retried like any other CI failure.

Proposed new step list (replaces lines 16–25):

- Find the open pull request that closes this issue.
- If the PR branch is behind the configured head branch ({{.HeadBranch}}),
  bring it up to date by rebasing onto {{.HeadBranch}} and force-pushing the
  branch. Prefer rebase over a merge commit so history stays linear; fall
  back to "merge main into the branch" only if the project's merge strategy
  requires it (read the PR's checks / repo settings if unsure).
- If the rebase has conflicts you cannot resolve mechanically, escalate.
- Check the pull request's CI status. If checks are still running, wait for
  them to finish (poll periodically) within your timeout budget.
- If CI passes, merge the pull request and you are done.
- If CI fails, check out the branch, read the failing job logs, fix the
  underlying problem, commit the fix on the same branch, push, and wait for
  CI again.
- Do not open a second pull request: keep working on the existing one.
- If main has advanced again while you were fixing CI, repeat the rebase
  step before re-checking CI.

This depends on the {{.HeadBranch}} template variable proposed in pr-plan.md (Decision §2). If that templating is not yet wired up when this is implemented, hardcode main in the prompt and add a TODO — but it's cheap to land both together.

2. Document the opt-in model in README.md

Add a short subsection under "Example: plan, code and merge prompts" (around line 221) that calls out:

• Auto-merge is opt-in per repo by including merge.md. To disable for a repo, omit merge.md and drop routes: merge: loop/merge from code.md — the code prompt will terminate at loop/code-done, and a human merges.
• Variants the operator can fork from merge.md:
  • Strict rebase (default proposed above).
  • Merge-commit style (replace the rebase step with "merge main into the branch").
  • "Use GitHub auto-merge" (call gh pr merge --auto instead of polling). This avoids the agent holding the per-prompt concurrency slot while CI runs, but only works on forges that support server-side auto-merge.
• Concurrency stays at 1 for merge (one merge attempt at a time) — already the example default.

3. Note rebase requires push scope and that the branch is force-pushed

Already implied by the existing credential helper (internal/gitcred) and the README's "token must have push scope for coding prompts" paragraph (line ~398). Add one sentence: "the merge prompt also force-pushes the PR branch when it rebases — the same push scope is sufficient."

Explicitly out of scope

• Adding a Go-side "rebase the clone" step in internal/clone. The merge agent operates inside the same clone primitive coding agents use; the rebase is performed by the agent with its own git tools, consistent with the project's stance ("agentloop drives labels and comments; the agent does the work" — pr-plan.md Decision §1).
• A new config.yaml field for "enable auto-merge". The presence/absence of merge.md is the knob; adding a redundant config field would be two sources of truth.
• Parsing CI status from agentloop. Polling and log-reading stay inside the agent (forge-agnostic, no new code path).
• Auto-rebase of the coding agent's clone mid-run. That remains the user's responsibility (README "Concurrency and merge conflicts").

Implementation steps

1. Edit example/loop/agentloop/prompts/merge.md: insert the rebase step and the "rebase again if main moved" loop (above).
2. Edit README.md: add the "opt-in / variants" subsection and the push-scope sentence.
3. If {{.HeadBranch}} templating from pr-plan.md is not yet implemented, either land that first or hardcode main in step 1.
4. No new tests needed — these are prose changes. Run task check to confirm formatting/lint still pass.
5. Commit on issue-51-rebase-and-merge-config and open a PR referencing Closes #51.

Risk / open questions

• Force-push to the PR branch is destructive to anyone else who pushed there. In the agentloop happy-path the PR was opened by the coding agent and no human has touched it, so this is fine — but worth a one-line warning in the prompt: "if the branch has commits whose author is not the agentloop user, escalate instead of force-pushing".
• Squash vs. rebase merge strategy is repo-specific. The prompt leaves the choice to the agent ("read repo settings if unsure"); operators with a strict policy should fork merge.md and pin the strategy.
• GitHub auto-merge (gh pr merge --auto) is mentioned as a documented variant only; the default prompt does not use it because (a) it is GitHub-only and agentloop is forge-agnostic, and (b) it complicates the "agent fixes CI on failure" loop (the agent would have to come back later to react to a failing auto-merge attempt). Operators who want it can swap it in.

[guettli]

Done. Implemented the plan posted on the issue: no Go code changes, just prompt + documentation edits.

What changed

• example/loop/agentloop/prompts/merge.md (and the matching mergePromptMD() scaffold in init.go): added an explicit step to rebase the PR branch onto the configured head branch (and force-push) before checking CI, plus a "rebase again if main moved while you were fixing CI" loop. Mechanical-conflict rebases and branches with non-agentloop commits escalate via <!-- loop-route: escalate --> instead of producing a destructive force-push.
• README.md: added an "Auto-merge is opt-in per repo" subsection that documents the existing knob (include merge.md to opt in, drop it to opt out) and lists common variants (strict rebase, merge-commit style, forge-side gh pr merge --auto). Also extended the push-scope paragraph to note that the merge prompt's force-push uses the same token scope.

How I verified

• ./run task check → gofmt, go vet, golangci-lint (0 issues), go test ./... all green.
• Pre-commit hook ran the same set on commit and passed.

PR: #53 — closes #51.