@undeemed/get-shit-done-codex 1.6.12 → 1.20.3

package/get-shit-done/workflows/complete-milestone.md

@@ -1,15 +1,11 @@
 <purpose>
 
-Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
-
-This is the ritual that separates "development" from "shipped."
+Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
 
 </purpose>
 
 <required_reading>
 
-**Read these files NOW:**
-
 1. templates/milestone.md
 2. templates/milestone-archive.md
 3. `.planning/ROADMAP.md`
@@ -20,33 +16,20 @@ This is the ritual that separates "development" from "shipped."
 
 <archival_behavior>
 
-When a milestone completes, this workflow:
-
-1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
-2. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
-3. Updates ROADMAP.md to replace milestone details with one-line summary
-4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
-5. Performs full PROJECT.md evolution review
-6. Offers to create next milestone inline
-
-**Context Efficiency:**
+When a milestone completes:
 
-- Completed milestones: One line each (~50 tokens)
-- Full details: In archive files (loaded only when needed)
-- Result: ROADMAP.md stays constant size forever
-- Result: REQUIREMENTS.md is always milestone-scoped (not cumulative)
+1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
+2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+3. Update ROADMAP.md — replace milestone details with one-line summary
+4. Delete REQUIREMENTS.md (fresh one for next milestone)
+5. Perform full PROJECT.md evolution review
+6. Offer to create next milestone inline
 
-**Archive Format:**
+**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
 
-**ROADMAP archive** uses `templates/milestone-archive.md` template with:
-- Milestone header (status, phases, date)
-- Full phase details from roadmap
-- Milestone summary (decisions, issues, technical debt)
+**ROADMAP archive** uses `templates/milestone-archive.md` — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).
 
-**REQUIREMENTS archive** contains:
-- All v1 requirements marked complete with outcomes
-- Traceability table with final status
-- Notes on any requirements that changed during milestone
+**REQUIREMENTS archive** contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
 
 </archival_behavior>
 
@@ -54,32 +37,29 @@ When a milestone completes, this workflow:
 
 <step name="verify_readiness">
 
-Check if milestone is truly complete:
+**Use `roadmap analyze` for comprehensive readiness check:**
 
 ```bash
-cat .planning/ROADMAP.md
-ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
+ROADMAP=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs roadmap analyze)
 ```
 
-**Questions to ask:**
-
+This returns all phases with plan/summary counts and disk status. Use this to verify:
 - Which phases belong to this milestone?
-- Are all those phases complete (all plans have summaries)?
-- Has the work been tested/validated?
-- Is this ready to ship/tag?
+- All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
+- `progress_percent` should be 100%.
 
 Present:
 
 ```
-Milestone: [Name from user, e.g., "v1.0 MVP"]
+Milestone: [Name, e.g., "v1.0 MVP"]
 
-Appears to include:
+Includes:
 - Phase 1: Foundation (2/2 plans complete)
 - Phase 2: Authentication (2/2 plans complete)
 - Phase 3: Core Features (3/3 plans complete)
 - Phase 4: Polish (1/1 plan complete)
 
-Total: 4 phases, 8 plans, all complete
+Total: {phase_count} phases, {total_plans} plans, all complete
 ```
 
 <config-check>
@@ -94,13 +74,11 @@ cat .planning/config.json 2>/dev/null
 
 ```
 ⚡ Auto-approved: Milestone scope verification
-
 [Show breakdown summary without prompting]
-
 Proceeding to stats gathering...
 ```
 
-Proceed directly to gather_stats step.
+Proceed to gather_stats.
 
 </if>
 
@@ -112,9 +90,8 @@ Ready to mark this milestone as shipped?
 ```
 
 Wait for confirmation.
-
-If "adjust scope": Ask which phases should be included.
-If "wait": Stop, user will return when ready.
+- "adjust scope": Ask which phases to include.
+- "wait": Stop, user returns when ready.
 
 </if>
 
@@ -125,30 +102,20 @@ If "wait": Stop, user will return when ready.
 Calculate milestone statistics:
 
 ```bash
-# Count phases and plans in milestone
-# (user specified or detected from roadmap)
-
-# Find git range
 git log --oneline --grep="feat(" | head -20
-
-# Count files modified in range
 git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
-
-# Count LOC (adapt to language)
 find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
-
-# Calculate timeline
-git log --format="%ai" FIRST_COMMIT | tail -1  # Start date
-git log --format="%ai" LAST_COMMIT | head -1   # End date
+git log --format="%ai" FIRST_COMMIT | tail -1
+git log --format="%ai" LAST_COMMIT | head -1
 ```
 
-Present summary:
+Present:
 
 ```
 Milestone Stats:
 - Phases: [X-Y]
 - Plans: [Z] total
-- Tasks: [N] total (estimated from phase summaries)
+- Tasks: [N] total (from phase summaries)
 - Files modified: [M]
 - Lines of code: [LOC] [language]
 - Timeline: [Days] days ([Start] → [End])
@@ -159,17 +126,16 @@ Milestone Stats:
 
 <step name="extract_accomplishments">
 
-Read all phase SUMMARY.md files in milestone range:
+Extract one-liners from SUMMARY.md files using summary-extract:
 
 ```bash
-cat .planning/phases/01-*/01-*-SUMMARY.md
-cat .planning/phases/02-*/02-*-SUMMARY.md
-# ... for each phase in milestone
+# For each phase in milestone, extract one-liner
+for summary in .planning/phases/*-*/*-SUMMARY.md; do
+  node ~/.codex/get-shit-done/bin/gsd-tools.cjs summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
+done
 ```
 
-From summaries, extract 4-6 key accomplishments.
-
-Present:
+Extract 4-6 key accomplishments. Present:
 
 ```
 Key accomplishments for this milestone:
@@ -184,52 +150,17 @@ Key accomplishments for this milestone:
 
 <step name="create_milestone_entry">
 
-Create or update `.planning/MILESTONES.md`.
-
-If file doesn't exist:
-
-```markdown
-# Project Milestones: [Project Name from PROJECT.md]
-
-[New entry]
-```
-
-If exists, prepend new entry (reverse chronological order).
-
-Use template from `templates/milestone.md`:
-
-```markdown
-## v[Version] [Name] (Shipped: YYYY-MM-DD)
-
-**Delivered:** [One sentence from user]
-
-**Phases completed:** [X-Y] ([Z] plans total)
-
-**Key accomplishments:**
-
-- [List from previous step]
+**Note:** MILESTONES.md entry is now created automatically by `gsd-tools milestone complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
 
-**Stats:**
-
-- [Files] files created/modified
-- [LOC] lines of [language]
-- [Phases] phases, [Plans] plans, [Tasks] tasks
-- [Days] days from [start milestone or start project] to ship
-
-**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
-
-**What's next:** [Ask user: what's the next goal?]
-
----
-```
+If additional details are needed (e.g., user-provided "Delivered" summary, git range, LOC stats), add them manually after the CLI creates the base entry.
 
 </step>
 
 <step name="evolve_project_full_review">
 
-Perform full PROJECT.md evolution review at milestone completion.
+Full PROJECT.md evolution review at milestone completion.
 
-**Read all phase summaries in this milestone:**
+Read all phase summaries:
 
 ```bash
 cat .planning/phases/*-*/*-SUMMARY.md
@@ -238,48 +169,43 @@ cat .planning/phases/*-*/*-SUMMARY.md
 **Full review checklist:**
 
 1. **"What This Is" accuracy:**
-   - Read current description
-   - Compare to what was actually built
-   - Update if the product has meaningfully changed
+   - Compare current description to what was built
+   - Update if product has meaningfully changed
 
 2. **Core Value check:**
-   - Is the stated core value still the right priority?
-   - Did shipping reveal a different core value?
+   - Still the right priority? Did shipping reveal a different core value?
    - Update if the ONE thing has shifted
 
 3. **Requirements audit:**
 
    **Validated section:**
-   - All Active requirements shipped in this milestone → Move to Validated
+   - All Active requirements shipped this milestone → Move to Validated
    - Format: `- ✓ [Requirement] — v[X.Y]`
 
    **Active section:**
-   - Remove requirements that moved to Validated
-   - Add any new requirements for next milestone
-   - Keep requirements that weren't addressed yet
+   - Remove requirements moved to Validated
+   - Add new requirements for next milestone
+   - Keep unaddressed requirements
 
    **Out of Scope audit:**
-   - Review each item — is the reasoning still valid?
-   - Remove items that are no longer relevant
-   - Add any requirements invalidated during this milestone
+   - Review each item — reasoning still valid?
+   - Remove irrelevant items
+   - Add requirements invalidated during milestone
 
 4. **Context update:**
    - Current codebase state (LOC, tech stack)
    - User feedback themes (if any)
-   - Known issues or technical debt to address
+   - Known issues or technical debt
 
 5. **Key Decisions audit:**
    - Extract all decisions from milestone phase summaries
-   - Add to Key Decisions table with outcomes where known
-   - Mark ✓ Good, ⚠️ Revisit, or — Pending for each
+   - Add to Key Decisions table with outcomes
+   - Mark ✓ Good, ⚠️ Revisit, or — Pending
 
 6. **Constraints check:**
-   - Any constraints that changed during development?
-   - Update as needed
-
-**Update PROJECT.md:**
+   - Any constraints changed during development? Update as needed
 
-Make all edits inline. Update "Last updated" footer:
+Update PROJECT.md inline. Update "Last updated" footer:
 
 ```markdown
 ---
@@ -371,9 +297,7 @@ Initial user testing showed demand for shape tools.
 
 <step name="reorganize_roadmap">
 
-Update `.planning/ROADMAP.md` to group completed milestone phases.
-
-Add milestone headers and collapse completed work:
+Update `.planning/ROADMAP.md` — group completed milestone phases:
 
 ```markdown
 # Roadmap: [Project Name]
@@ -417,180 +341,230 @@ Add milestone headers and collapse completed work:
 
 <step name="archive_milestone">
 
-Extract completed milestone details and create archive file.
-
-**Process:**
+**Delegate archival to gsd-tools:**
 
-1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
+```bash
+ARCHIVE=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs milestone complete "v[X.Y]" --name "[Milestone Name]")
+```
 
-2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template
+The CLI handles:
+- Creating `.planning/milestones/` directory
+- Archiving ROADMAP.md to `milestones/v[X.Y]-ROADMAP.md`
+- Archiving REQUIREMENTS.md to `milestones/v[X.Y]-REQUIREMENTS.md` with archive header
+- Moving audit file to milestones if it exists
+- Creating/appending MILESTONES.md entry with accomplishments from SUMMARY.md files
+- Updating STATE.md (status, last activity)
 
-3. Extract data from current ROADMAP.md:
-   - All phases belonging to this milestone (by phase number range)
-   - Full phase details (goals, plans, dependencies, status)
-   - Phase plan lists with completion checkmarks
+Extract from result: `version`, `date`, `phases`, `plans`, `tasks`, `accomplishments`, `archived`.
 
-4. Extract data from PROJECT.md:
-   - Key decisions made during this milestone
-   - Requirements that were validated
+Verify: `✅ Milestone archived to .planning/milestones/`
 
-5. Fill template {{PLACEHOLDERS}}:
-   - {{VERSION}} — Milestone version (e.g., "1.0")
-   - {{MILESTONE_NAME}} — From ROADMAP.md milestone header
-   - {{DATE}} — Today's date
-   - {{PHASE_START}} — First phase number in milestone
-   - {{PHASE_END}} — Last phase number in milestone
-   - {{TOTAL_PLANS}} — Count of all plans in milestone
-   - {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview
-   - {{PHASES_SECTION}} — Full phase details extracted
-   - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
-   - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
+**Phase archival (optional):** After archival completes, ask the user:
 
-6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
+AskUserQuestion(header="Archive Phases", question="Archive phase directories to milestones/?", options: "Yes — move to milestones/v[X.Y]-phases/" | "Skip — keep phases in place")
 
-7. Delete ROADMAP.md (fresh one created for next milestone):
-   ```bash
-   rm .planning/ROADMAP.md
-   ```
+If "Yes": move phase directories to the milestone archive:
+```bash
+mkdir -p .planning/milestones/v[X.Y]-phases
+# For each phase directory in .planning/phases/:
+mv .planning/phases/{phase-dir} .planning/milestones/v[X.Y]-phases/
+```
+Verify: `✅ Phase directories archived to .planning/milestones/v[X.Y]-phases/`
 
-8. Verify archive exists:
-   ```bash
-   ls .planning/milestones/v[X.Y]-ROADMAP.md
-   ```
+If "Skip": Phase directories remain in `.planning/phases/` as raw execution history. Use `/gsd:cleanup` later to archive retroactively.
 
-9. Confirm roadmap archive complete:
+After archival, the AI still handles:
+- Reorganizing ROADMAP.md with milestone grouping (requires judgment)
+- Full PROJECT.md evolution review (requires understanding)
+- Deleting original ROADMAP.md and REQUIREMENTS.md
+- These are NOT fully delegated because they require AI interpretation of content
 
-   ```
-   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
-   ✅ ROADMAP.md deleted (fresh one for next milestone)
-   ```
+</step>
 
-**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+<step name="reorganize_roadmap_and_delete_originals">
 
-</step>
+After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then delete originals:
 
-<step name="archive_requirements">
+**Reorganize ROADMAP.md** — group completed milestone phases:
 
-Archive requirements and prepare for fresh requirements in next milestone.
+```markdown
+# Roadmap: [Project Name]
 
-**Process:**
+## Milestones
 
-1. Read current REQUIREMENTS.md:
-   ```bash
-   cat .planning/REQUIREMENTS.md
-   ```
+- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
 
-2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+## Phases
 
-3. Transform requirements for archive:
-   - Mark all v1 requirements as `[x]` complete
-   - Add outcome notes where relevant (validated, adjusted, dropped)
-   - Update traceability table status to "Complete" for all shipped requirements
-   - Add "Milestone Summary" section with:
-     - Total requirements shipped
-     - Any requirements that changed scope during milestone
-     - Any requirements dropped and why
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
 
-4. Write archive file with header:
-   ```markdown
-   # Requirements Archive: v[X.Y] [Milestone Name]
+- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
+- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
 
-   **Archived:** [DATE]
-   **Status:** ✅ SHIPPED
+</details>
+```
 
-   This is the archived requirements specification for v[X.Y].
-   For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
+**Then delete originals:**
 
-   ---
+```bash
+rm .planning/ROADMAP.md
+rm .planning/REQUIREMENTS.md
+```
 
-   [Full REQUIREMENTS.md content with checkboxes marked complete]
+</step>
 
-   ---
+<step name="update_state">
 
-   ## Milestone Summary
+Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields:
 
-   **Shipped:** [X] of [Y] v1 requirements
-   **Adjusted:** [list any requirements that changed during implementation]
-   **Dropped:** [list any requirements removed and why]
+**Project Reference:**
 
-   ---
-   *Archived: [DATE] as part of v[X.Y] milestone completion*
-   ```
+```markdown
+## Project Reference
 
-5. Delete original REQUIREMENTS.md:
-   ```bash
-   rm .planning/REQUIREMENTS.md
-   ```
+See: .planning/PROJECT.md (updated [today])
 
-6. Confirm:
-   ```
-   ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
-   ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
-   ```
+**Core value:** [Current core value from PROJECT.md]
+**Current focus:** [Next milestone or "Planning next milestone"]
+```
 
-**Important:** The next milestone workflow starts with `/gsd:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries the cumulative record across milestones.
+**Accumulated Context:**
+- Clear decisions summary (full log in PROJECT.md)
+- Clear resolved blockers
+- Keep open blockers for next milestone
 
 </step>
 
-<step name="archive_audit">
+<step name="handle_branches">
 
-Move the milestone audit file to the archive (if it exists):
+Check branching strategy and offer merge options.
+
+Use `init milestone-op` for context, or load config directly:
 
 ```bash
-# Move audit to milestones folder (if exists)
-[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
+INIT=$(node ~/.codex/get-shit-done/bin/gsd-tools.cjs init execute-phase "1")
 ```
 
-Confirm:
+Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template`, and `commit_docs` from init JSON.
+
+**If "none":** Skip to git_tag.
+
+**For "phase" strategy:**
+
+```bash
+BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
+PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
 ```
-✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md
+
+**For "milestone" strategy:**
+
+```bash
+BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
+MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
 ```
 
-(Skip silently if no audit file exists — audit is optional)
+**If no branches found:** Skip to git_tag.
 
-</step>
+**If branches exist:**
 
-<step name="update_state">
+```
+## Git Branches Detected
 
-Update STATE.md to reflect milestone completion.
+Branching strategy: {phase/milestone}
+Branches: {list}
 
-**Project Reference:**
+Options:
+1. **Merge to main** — Merge branch(es) to main
+2. **Delete without merging** — Already merged or not needed
+3. **Keep branches** — Leave for manual handling
+```
 
-```markdown
-## Project Reference
+AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
 
-See: .planning/PROJECT.md (updated [today])
+**Squash merge:**
 
-**Core value:** [Current core value from PROJECT.md]
-**Current focus:** [Next milestone or "Planning next milestone"]
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git checkout main
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    git merge --squash "$branch"
+    # Strip .planning/ from staging if commit_docs is false
+    if [ "$COMMIT_DOCS" = "false" ]; then
+      git reset HEAD .planning/ 2>/dev/null || true
+    fi
+    git commit -m "feat: $branch for v[X.Y]"
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  git merge --squash "$MILESTONE_BRANCH"
+  # Strip .planning/ from staging if commit_docs is false
+  if [ "$COMMIT_DOCS" = "false" ]; then
+    git reset HEAD .planning/ 2>/dev/null || true
+  fi
+  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
+fi
+
+git checkout "$CURRENT_BRANCH"
 ```
 
-**Current Position:**
-
-```markdown
-Phase: [Next phase] of [Total] ([Phase name])
-Plan: Not started
-Status: Ready to plan
-Last activity: [today] — v[X.Y] milestone complete
+**Merge with history:**
 
-Progress: [updated progress bar]
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git checkout main
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    git merge --no-ff --no-commit "$branch"
+    # Strip .planning/ from staging if commit_docs is false
+    if [ "$COMMIT_DOCS" = "false" ]; then
+      git reset HEAD .planning/ 2>/dev/null || true
+    fi
+    git commit -m "Merge branch '$branch' for v[X.Y]"
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  git merge --no-ff --no-commit "$MILESTONE_BRANCH"
+  # Strip .planning/ from staging if commit_docs is false
+  if [ "$COMMIT_DOCS" = "false" ]; then
+    git reset HEAD .planning/ 2>/dev/null || true
+  fi
+  git commit -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
+fi
+
+git checkout "$CURRENT_BRANCH"
 ```
 
-**Accumulated Context:**
+**Delete without merging:**
 
-- Clear decisions summary (full log in PROJECT.md)
-- Clear resolved blockers
-- Keep open blockers for next milestone
+```bash
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
+fi
+```
+
+**Keep branches:** Report "Branches preserved for manual handling"
 
 </step>
 
 <step name="git_tag">
 
-Create git tag for milestone:
+Create git tag:
 
 ```bash
-git tag -a v[X.Y] -m "$(cat <<'EOF'
-v[X.Y] [Name]
+git tag -a v[X.Y] -m "v[X.Y] [Name]
 
 Delivered: [One sentence]
 
@@ -599,9 +573,7 @@ Key accomplishments:
 - [Item 2]
 - [Item 3]
 
-See .planning/MILESTONES.md for full details.
-EOF
-)"
+See .planning/MILESTONES.md for full details."
 ```
 
 Confirm: "Tagged: v[X.Y]"
@@ -609,7 +581,6 @@ Confirm: "Tagged: v[X.Y]"
 Ask: "Push tag to remote? (y/n)"
 
 If yes:
-
 ```bash
 git push origin v[X.Y]
 ```
@@ -618,43 +589,11 @@ git push origin v[X.Y]
 
 <step name="git_commit_milestone">
 
-Commit milestone completion including archive files and deletions.
+Commit milestone completion.
 
 ```bash
-# Stage archive files (new)
-git add .planning/milestones/v[X.Y]-ROADMAP.md
-git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
-git add .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md 2>/dev/null || true
-
-# Stage updated files
-git add .planning/MILESTONES.md
-git add .planning/PROJECT.md
-git add .planning/STATE.md
-
-# Stage deletions
-git add -u .planning/
-
-# Commit with descriptive message
-git commit -m "$(cat <<'EOF'
-chore: complete v[X.Y] milestone
-
-Archived:
-- milestones/v[X.Y]-ROADMAP.md
-- milestones/v[X.Y]-REQUIREMENTS.md
-- milestones/v[X.Y]-MILESTONE-AUDIT.md (if audit was run)
-
-Deleted (fresh for next milestone):
-- ROADMAP.md
-- REQUIREMENTS.md
-
-Updated:
-- MILESTONES.md (new entry)
-- PROJECT.md (requirements → Validated)
-- STATE.md (reset for next milestone)
-
-Tagged: v[X.Y]
-EOF
-)"
+node ~/.codex/get-shit-done/bin/gsd-tools.cjs commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md
+```
 ```
 
 Confirm: "Committed: chore: complete v[X.Y] milestone"
@@ -698,35 +637,20 @@ Tag: v[X.Y]
 
 **Version conventions:**
 - **v1.0** — Initial MVP
-- **v1.1, v1.2, v1.3** — Minor updates, new features, fixes
-- **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction
-
-**Name conventions:**
-- v1.0 MVP
-- v1.1 Security
-- v1.2 Performance
-- v2.0 Redesign
-- v2.0 iOS Launch
+- **v1.1, v1.2** — Minor updates, new features, fixes
+- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
 
-Keep names short (1-2 words describing the focus).
+**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).
 
 </milestone_naming>
 
 <what_qualifies>
 
-**Create milestones for:**
-- Initial release (v1.0)
-- Public releases
-- Major feature sets shipped
-- Before archiving planning
+**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.
 
-**Don't create milestones for:**
-- Every phase completion (too granular)
-- Work in progress (wait until shipped)
-- Internal dev iterations (unless truly shipped internally)
+**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
 
-If uncertain, ask: "Is this deployed/usable/shipped in some form?"
-If yes → milestone. If no → keep working.
+Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
 
 </what_qualifies>