Phase 1 · SAO design decision — post-success merge strategy (cherry-pick vs. merge --no-ff)

[Luis85]

Meta

type: DesignDecision
stage: draft
maturity: L1
created: 2026-05-10
inputs:
  - "Luis85/specorator specs/specorator-agent-orchestrator/design.md — open question #2"
related: ["#43", "#47"]

Purpose. Choose between cherry-pick and git merge --no-ff as the post-success worktree integration strategy.

---

Context

Open question #2 from the SAO design doc. After an agent run succeeds (all sensors pass), the worktree changes must be integrated into the main branch. The strategy affects conflict probability, history legibility, and concurrent-run safety.

---

Options

Option A — git merge --no-ff

Merge the full worktree branch into main. All commits from the agent run are preserved.

• Pro: clean, merge-commit history; all agent reasoning commits retained; conceptually simple
• Pro: safest when worktrees are branched from HEAD at creation time and runs complete quickly
• Con: if another feature's run merged while this one was in progress, drift increases conflict probability

Option B — git cherry-pick

Cherry-pick only the specific commit(s) produced by the agent run.

• Pro: surgical; only the relevant change is integrated
• Con: cherry-pick conflicts are harder to resolve than merge conflicts; loses merge-commit lineage
• Con: the agent may produce multiple commits; determining which to cherry-pick adds complexity

Option C — git merge --squash + single commit

Squash all worktree commits into a single commit with a structured message.

• Pro: clean linear history; easy to bisect
• Con: loses intermediate agent reasoning commits; harder to audit what the agent did step-by-step

---

Factors specific to SAO

1. Concurrent runs: multiple features may be running simultaneously. The higher the concurrency, the higher the drift probability, favouring cherry-pick.
2. Worktree creation strategy: worktrees are created from HEAD at claim time. If a run takes 10–30 minutes, HEAD may have advanced.
3. Conflict resolution: who resolves conflicts — the SAO (automated), or a human? Automated conflict resolution is a significant scope increase.
4. History auditability: preserving agent commits aids post-hoc review; squash discards them.

---

Recommendation

Option A (--no-ff) for V1, with a worktree-refresh step before merge:

1. Before merging, fetch and rebase the worktree onto latest HEAD (or fail fast with a conflict signal)
2. Merge with --no-ff
3. On conflict: transition to released with MERGE_CONFLICT reason; surface for human resolution

This avoids the complexity of cherry-pick while maintaining conflict safety.

---

Acceptance

• Decision recorded with rationale
• Conflict handling strategy specified (automated retry vs. human escalation)
• WorktreePort after_run hook updated to reflect merge step
• MERGE_CONFLICT reason code added to released state taxonomy if applicable
• Integration with human-in-the-loop review gates (→ Phase 1 · SAO human-in-the-loop review gates — approval workflow and intervention design #52) specified for conflict escalation