From 5ee22e6256d726e93d07e8247f6ccfef7f499c16 Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Fri, 30 Jan 2026 17:24:32 -0600
Subject: [PATCH] feat(git): add squash merge option for branching strategies

- Add "Squash merge" as recommended option at complete-milestone
- Keep "Merge with history" (--no-ff) as alternative
- Document merge options in planning-config reference

Improves on #298 based on community feedback from @oojacoboo.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 get-shit-done/references/planning-config.md   | 11 ++++++
 get-shit-done/workflows/complete-milestone.md | 34 +++++++++++++++++--
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/get-shit-done/references/planning-config.md b/get-shit-done/references/planning-config.md
index b0c65de88..f9b4a7aae 100644
--- a/get-shit-done/references/planning-config.md
+++ b/get-shit-done/references/planning-config.md
@@ -165,6 +165,17 @@ if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
 fi
 ```
 
+**Merge options at complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
 **Use cases:**
 
 | Strategy | Best for |
diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md
index 5f2d1a035..8ae1e551f 100644
--- a/get-shit-done/workflows/complete-milestone.md
+++ b/get-shit-done/workflows/complete-milestone.md
@@ -643,7 +643,8 @@ AskUserQuestion([
     header: "Branches",
     multiSelect: false,
     options: [
-      { label: "Merge to main", description: "Merge all branches to main sequentially" },
+      { label: "Squash merge (Recommended)", description: "Squash all commits into one clean commit on main" },
+      { label: "Merge with history", description: "Preserve all individual commits (--no-ff)" },
       { label: "Delete without merging", description: "Branches already merged or not needed" },
       { label: "Keep branches", description: "Leave branches for manual handling later" }
     ]
@@ -651,7 +652,34 @@ AskUserQuestion([
 ])
 ```
 
-**If "Merge to main":**
+**If "Squash merge":**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git checkout main
+
+# For phase strategy - squash merge each phase branch
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    echo "Squash merging $branch..."
+    git merge --squash "$branch"
+    git commit -m "feat: $branch for v[X.Y]"
+  done
+fi
+
+# For milestone strategy - squash merge milestone branch
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  echo "Squash merging $MILESTONE_BRANCH..."
+  git merge --squash "$MILESTONE_BRANCH"
+  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
+fi
+
+git checkout "$CURRENT_BRANCH"
+```
+
+Report: "Squash merged branches to main"
+
+**If "Merge with history":**
 
 ```bash
 CURRENT_BRANCH=$(git branch --show-current)
@@ -674,7 +702,7 @@ fi
 git checkout "$CURRENT_BRANCH"
 ```
 
-Report: "Merged branches to main"
+Report: "Merged branches to main with full history"
 
 **If "Delete without merging":**