orchestrate: implementer branches fork from a stale worktree base, so merge-mode ff-only integration parks verified work en masse

[TBarregren]

Context — field experience (kntnt-wp-skills, 2026-07-19, orchestrate 0.13.0)

A 14-issue merge-mode run (two slices, serial single-issue waves) hit a systematic integration failure: in slice 1, 5 of 8 independently-verified-green branches failed git merge --ff-only, and 3 of them were parked despite being fully verified, because the rebase hit content conflicts the integrate agent is forbidden to resolve. Slice 2 repeated the pattern (1 of 5 needed a rebase; one issue parked). All parked branches were later landed by a manual recovery loop (rebase agent → targeted re-verify of the conflict resolution → ff-only land) — every single one was sound.

Root cause

Three compounding gaps in skills/orchestrate/orchestrate.workflow.js:

1. The implementer's branch base is stale by construction. The implement prompt says "Work on a fresh branch off the current integration base" but never says how. The agent lands in a Workflow worktree whose HEAD is the harness's scaffolding branch worktree-<runId>-<n>, pinned at run start — observed: every scaffolding branch in both runs sat at the run-start commit even while main advanced issue by issue. So "the current base", resolved from inside the worktree, is the run-start commit, and every issue after the first forks from a base missing its predecessors.
2. The integrate prompt's premise is then false. It asserts "In the serial integrate-immediately design nothing landed between the build and now, so it is already a fast-forward" — untrue once (1) applies; the ff-only refusal it calls "the rare case" becomes the normal case from issue 2 onward.
3. A genuine rebase conflict parks verified work with no reconcile path. The integrate agent is (rightly) forbidden to resolve content conflicts, but the engine's only response is to park — even though the branch passed independent verification. For a batch of tickets that touch the same shared files (SKILL.md/spec/manpages — common in doc-heavy plugins), conflicts are the norm, so merge mode degrades into a park generator.

Telling detail: the engine already contains the correct pattern — integrationHotfix creates its branch with git checkout -B <branch> <current-default-tip> precisely so it "can never build on an old base". The same instruction is missing from implement (and fix).

Proposed fix

1. Primary (cheap, prompt-only): the implement prompt mandates, before any work: git checkout -B <feature-branch> <default-branch> pointing at the current default tip — mirroring integrationHotfix's wording and rationale. In the serial integrate-immediately design this restores the ff-only invariant for real; the fix prompt keeps working in the same branch/worktree as today.
2. Secondary (engine stage): when ff-only is refused AND the rebase hits a genuine content conflict, do not park a verified branch outright — add a bounded reconcile stage: one implementer-grade agent rebases and resolves minimally (keep both sides' concerns), then one targeted re-verify of the conflict resolution only (not the whole panel), then land; park only if the re-verify blocks or a second conflict round hits. This mirrors the manual recovery that landed 5/5 parked branches in the field run.
3. Docs: correct the integrate prompt's "nothing landed between the build and now" claim (or make it true via fix 1) so the agent's mental model matches reality.

Acceptance criteria

• In a serial merge-mode run where issue N's landing edits files issue N+1 also touches, issue N+1's branch forks from the post-N default tip and lands with a plain --ff-only (no rebase) — engine-helpers unit-testable via the prompt text (the checkout -B instruction present in implement), plus a workflow-level assertion if feasible.
• A genuine rebase conflict on a verified branch triggers the reconcile stage and lands after a clear targeted re-verify; parking happens only when the re-verify blocks or the bounded rounds are exhausted.
• The integrate prompt no longer asserts the false invariant.

---

🤖 Generated with Claude Code

[TBarregren]

This was generated by AI during triage.

Agent Brief

Category: bug
Summary: In merge mode, implementer branches fork from a stale worktree base, so --ff-only integration fails routinely and genuine rebase conflicts park independently-verified work with no reconcile path.

Current behavior:
The orchestrate engine's implement prompt tells the agent to "work on a fresh branch off the current integration base" but never says how to establish that base. The implementer runs in an isolated harness worktree whose HEAD is a scaffolding branch pinned before the run's first landing, so "the current base" resolved from inside the worktree is the run-start commit — every issue after the first forks from a base missing its predecessors. The integrate prompt then asserts that "nothing landed between the build and now, so it is already a fast-forward" and treats ff-only refusal as "the rare case"; once the base is stale that premise is false and refusal is the normal case from issue 2 onward. When the resulting rebase hits a genuine content conflict, the integrate agent is (correctly) forbidden to resolve it, and the engine's only response is to park the issue — even though the branch passed independent verification. Field run (kntnt-wp-skills, 2026-07-19, 14 issues, orchestrate 0.13.0): 5 of 8 verified-green branches in slice 1 failed ff-only, 3 parked; all parked branches were later landed manually and every one was sound.

The engine already contains the correct base-establishment pattern: the integration-hotfix prompt instructs git checkout -B <branch> <current-default-tip> precisely so the hotfix "can never build on an old base". The same instruction is absent from the implement prompt (the fix-round prompt correctly continues in the existing branch/worktree and needs no change).

Desired behavior:

1. Fresh base by instruction (primary, prompt-only): before any work, the implement prompt mandates creating the feature branch with git checkout -B <feature-branch> <default-branch> pointing at the current default-branch tip, mirroring the integration-hotfix prompt's wording and rationale. In the serial integrate-immediately design this restores the ff-only invariant for real.
2. Bounded reconcile instead of park (engine stage): when ff-only is refused AND the rebase hits a genuine content conflict on a branch that passed verification, the engine does not park outright. It runs one implementer-grade agent (worktree-isolated, code-touching) that rebases and resolves the conflict minimally — keeping both sides' concerns — then one targeted re-verify scoped to the conflict resolution only (not the full verifier panel), then lands via the same linear fast-forward step. Parking happens only when the targeted re-verify blocks or a second conflict round hits (bounded, like fix rounds).
3. Truthful integrate prompt: the integrate prompt no longer asserts the false "nothing landed between the build and now" invariant — either the claim is removed/corrected or made true by (1); either way the agent's stated mental model must match reality.

Key interfaces:

• The implement prompt text in the orchestrate workflow script — gains the checkout -B base-establishment instruction; unit-testable by asserting the instruction's presence in the prompt text (the existing structural test approach for the workflow script).
• The integrate prompt text — loses the false fast-forward invariant claim.
• The integrate/park path in the workflow engine — gains the bounded reconcile stage between ff-only refusal-with-conflict and status: 'parked'; the reconcile agent must carry worktree isolation like every code-touching agent, per the engine's stated worktree-isolation rule.
• ADR-0001 (orchestrate control model): the reconcile stage adds an engine stage to the control model — check whether the ADR (and SKILL.md's flow description) needs a corresponding update, and make it.

Acceptance criteria:

• The implement prompt contains the git checkout -B <feature-branch> <default-branch> instruction with the current-tip rationale, structurally asserted by a test.
• In a serial merge-mode run where issue N's landing edits files issue N+1 also touches, issue N+1's branch forks from the post-N default tip and lands with a plain --ff-only (no rebase) — workflow-level assertion if feasible, otherwise the prompt-text test stands in.
• A genuine rebase conflict on a verified branch triggers the reconcile stage (rebase-resolve → targeted re-verify → ff-only land); the issue is parked only when the re-verify blocks or the bounded conflict rounds are exhausted.
• The integrate prompt no longer asserts that nothing landed between build and integration.
• SKILL.md and ADR-0001 describe the reconcile stage (or record why the control model is unchanged).

Out of scope:

• PR mode behavior (open-a-PR path) — unchanged.
• The fix-round prompt's branch handling — it correctly continues in the existing branch and worktree.
• Resolving content conflicts inside the integrate agent — that prohibition stays; resolution belongs to the reconcile stage's implementer-grade agent only.
• Any change to the harness's worktree scaffolding itself — the fix works at the prompt/engine level regardless of what HEAD the harness pins.

[TBarregren]

Fixed in 591bbce (tests d92a994, red-before-green).

• Fix 1 — the implement prompt now creates the feature branch fresh off the up-to-date default tip with git checkout -B (mirroring integrationHotfix), so in the serial integrate-immediately design each issue forks from a base already containing its landed predecessors and --ff-only holds.
• Fix 3 — the integrate prompt no longer asserts the false "nothing landed between the build and now" invariant; it ties the fast-forward to the branch having been cut off the then-current tip.
• Fix 2 — a genuine rebase content conflict on a verified branch is no longer parked outright: a bounded reconcile stage (reconcile → targeted reverifyReconcile → land) repairs it, merge mode only, bounded by maxFixRounds. New drift-guarded isReconcilableConflict helper + INTEGRATE_SCHEMA.conflict flag.

Gates green: audit.py 0 findings, 337 tests pass.