msd-core/gsd-core/workflows/pr-branch.md

Create a clean branch for pull requests by filtering out transient .planning/ commits. The PR branch contains only code changes and structural planning state — reviewers don't see GSD transient artifacts (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, etc.) but milestone archives, STATE.md, ROADMAP.md, and PROJECT.md changes are preserved.

Uses git cherry-pick with path filtering to rebuild a clean history.

Parse `$ARGUMENTS` for target branch (default: `main`).

CURRENT_BRANCH=$(git branch --show-current)
TARGET=${1:-main}

Check preconditions:

• Must be on a feature branch (not main/master)
• Must have commits ahead of target

AHEAD=$(git rev-list --count "$TARGET".."$CURRENT_BRANCH" 2>/dev/null)
if [ "$AHEAD" = "0" ]; then
  echo "No commits ahead of $TARGET — nothing to filter."
  exit 0
fi

Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► PR BRANCH
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Branch: {CURRENT_BRANCH}
Target: {TARGET}
Commits: {AHEAD} ahead

Classify commits:

# Get all commits ahead of target
git log --oneline "$TARGET".."$CURRENT_BRANCH" --no-merges

Structural planning files — always preserved (repository planning state):

• .planning/STATE.md
• .planning/ROADMAP.md
• .planning/MILESTONES.md
• .planning/PROJECT.md
• .planning/REQUIREMENTS.md
• .planning/milestones/**

Transient planning files — excluded from PR branch (reviewer noise):

• .planning/phases/** (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, etc.)
• .planning/quick/**
• .planning/research/**
• .planning/threads/**
• .planning/todos/**
• .planning/debug/**
• .planning/seeds/**
• .planning/codebase/**
• .planning/ui-reviews/**

For each commit, check what it touches:

# For each commit hash
FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
NON_PLANNING=$(echo "$FILES" | grep -v "^\.planning/" | wc -l)
STRUCTURAL=$(echo "$FILES" | grep -E "^\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\.md|^\.planning/milestones/" | wc -l)
TRANSIENT_ONLY=$(echo "$FILES" | grep "^\.planning/" | grep -vE "^\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\.md|^\.planning/milestones/" | wc -l)

Classify:

• Code commits: Touch at least one non-.planning/ file → INCLUDE
• Structural planning commits: Touch only structural .planning/ files (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md, REQUIREMENTS.md, milestones/**) → INCLUDE
• Transient planning commits: Touch only transient .planning/ files (phases/, quick/, research/, etc.) → EXCLUDE
• Mixed commits: Touch code + any planning files → INCLUDE (transient planning changes come along; acceptable in mixed context)

Display analysis:

Commits to include: {N} (code changes + structural planning)
Commits to exclude: {N} (transient planning-only)
Mixed commits: {N} (code + planning — included)
Structural planning commits: {N} (STATE/ROADMAP/milestone updates — included)

```bash PR_BRANCH="${CURRENT_BRANCH}-pr"

Create PR branch from target

git checkout -b "$PR_BRANCH" "$TARGET"

Cherry-pick code commits and structural planning commits (in order):

```bash
for HASH in $CODE_AND_STRUCTURAL_COMMITS; do
  git cherry-pick "$HASH" --no-commit
  # Remove only transient .planning/ subdirectories that came along in mixed commits.
  # DO NOT remove structural files (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md,
  # REQUIREMENTS.md, milestones/) — these must survive into the PR branch.
  for dir in phases quick research threads todos debug seeds codebase ui-reviews; do
    git rm -r --cached ".planning/$dir/" 2>/dev/null || true
  done
  git commit -C "$HASH"
done

Return to original branch:

git checkout "$CURRENT_BRANCH"

```bash # Verify no .planning/ files in PR branch PLANNING_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | grep "^\.planning/" | wc -l) TOTAL_FILES=$(git diff --name-only "$TARGET".."$PR_BRANCH" | wc -l) PR_COMMITS=$(git rev-list --count "$TARGET".."$PR_BRANCH") ```

Display results:

✅ PR branch created: {PR_BRANCH}

Original: {AHEAD} commits, {ORIGINAL_FILES} files
PR branch: {PR_COMMITS} commits, {TOTAL_FILES} files
Planning files: {PLANNING_FILES} (should be 0)

Next steps:
  git push origin {PR_BRANCH}
  gh pr create --base {TARGET} --head {PR_BRANCH}

Or use /gsd:ship to create the PR automatically.

<success_criteria>

• PR branch created from target
• Planning-only commits excluded
• No .planning/ files in PR branch diff
• Commit messages preserved from original
• User shown next steps </success_criteria>