@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/complete-milestone.md

@@ -0,0 +1,1298 @@
+<purpose>
+
+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>
+
+<context_tier>verification</context_tier>
+
+<required_reading>
+
+1. templates/milestone.md
+2. templates/milestone-archive.md
+3. references/conflict-resolution.md
+
+NOTE: Items below use variables resolved by `init milestone-op` in the initialize step.
+Read these AFTER running the initialize step, not before.
+
+4. `${roadmap_path}` (from init milestone-op)
+5. `${requirements_path}` (from init milestone-op)
+6. `${project_path}` (from init milestone-op)
+
+</required_reading>
+
+<archival_behavior>
+
+When a milestone completes:
+
+1. Extract full milestone details to `${project_root}/milestones/v[X.Y]-ROADMAP.md`
+2. Archive requirements to `${project_root}/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
+
+**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
+
+**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 requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
+
+</archival_behavior>
+
+<process>
+
+<step name="initialize" priority="first">
+
+Load project context and resolve paths:
+
+```bash
+INIT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" init milestone-op)
+```
+
+Parse JSON for: `commit_docs`, `state_path`, `roadmap_path`, `project_path`, `requirements_path`, `phases_dir`, `archive_dir`, `project_root`, `phase_count`, `completed_phases`, `all_phases_complete`.
+
+**Load verification tier context:**
+
+```bash
+LAST_PHASE=$(echo "$completed_phases" | tail -1)
+TIER_FILES=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" context load-tier verification --phase "${LAST_PHASE}" --raw 2>/dev/null)
+```
+
+This provides all execution-tier files plus VERIFICATION.md and UAT*.md for the last phase. Keep the operational reads of ROADMAP, REQUIREMENTS (used for archival, not just context).
+
+Detect `JOB_MODE`:
+- Check if `<job-mode>silent</job-mode>` is present in the invoking context
+- Store as `JOB_MODE = true/false`
+
+</step>
+
+<step name="verify_readiness">
+
+**Use `roadmap analyze` for comprehensive readiness check:**
+
+```bash
+ROADMAP=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" roadmap analyze)
+```
+
+This returns all phases with plan/summary counts and disk status. Use this to verify:
+- Which phases belong to this milestone?
+- All phases complete (all plans have summaries)? Check `disk_status === 'complete'` for each.
+- `progress_percent` should be 100%.
+
+**Requirements completion check (REQUIRED before presenting):**
+
+Parse REQUIREMENTS.md traceability table:
+- Count total v1 requirements vs checked-off (`[x]`) requirements
+- Identify any non-Complete rows in the traceability table
+
+Present:
+
+```
+Milestone: [Name, e.g., "v1.0 MVP"]
+
+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: {phase_count} phases, {total_plans} plans, all complete
+Requirements: {N}/{M} v1 requirements checked off
+```
+
+**If requirements incomplete** (N < M):
+
+```
+⚠ Unchecked Requirements:
+
+- [ ] {REQ-ID}: {description} (Phase {X})
+- [ ] {REQ-ID}: {description} (Phase {Y})
+```
+
+**If `JOB_MODE` is true:**
+- Log: `[AUTO-RESOLVE] {N}/{M} requirements checked -- proceeding with known gaps`
+- Note incomplete requirements in MILESTONES.md under `### Known Gaps`
+- Skip to gather_stats (do not prompt)
+
+**If `JOB_MODE` is false (default):**
+
+MUST present 3 options:
+1. **Proceed anyway** — mark milestone complete with known gaps
+2. **Run audit first** — `/dgs:audit-milestone` to assess gap severity
+3. **Abort** — return to development
+
+If user selects "Proceed anyway": note incomplete requirements in MILESTONES.md under `### Known Gaps` with REQ-IDs and descriptions.
+
+<config-check>
+
+```bash
+cat ${config_path} 2>/dev/null
+```
+
+</config-check>
+
+<if mode="yolo">
+
+```
+⚡ Auto-approved: Milestone scope verification
+[Show breakdown summary without prompting]
+Proceeding to stats gathering...
+```
+
+Proceed to gather_stats.
+
+</if>
+
+<if mode="job-mode">
+
+```
+[AUTO-RESOLVE] Milestone scope verified in job mode
+```
+
+Proceed to gather_stats.
+
+</if>
+
+<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">
+
+```
+Ready to mark this milestone as shipped?
+(yes / wait / adjust scope)
+```
+
+Wait for confirmation.
+- "adjust scope": Ask which phases to include.
+- "wait": Stop, user returns when ready.
+
+</if>
+
+</step>
+
+<step name="gather_stats">
+
+Calculate milestone statistics:
+
+```bash
+git log --oneline --grep="feat(" | head -20
+git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
+find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
+git log --format="%ai" FIRST_COMMIT | tail -1
+git log --format="%ai" LAST_COMMIT | head -1
+```
+
+Present:
+
+```
+Milestone Stats:
+- Phases: [X-Y]
+- Plans: [Z] total
+- Tasks: [N] total (from phase summaries)
+- Files modified: [M]
+- Lines of code: [LOC] [language]
+- Timeline: [Days] days ([Start] → [End])
+- Git range: feat(XX-XX) → feat(YY-YY)
+```
+
+</step>
+
+<step name="extract_accomplishments">
+
+Extract one-liners from SUMMARY.md files using summary-extract:
+
+```bash
+# For each phase in milestone, extract one-liner
+for summary in ${project_root}/phases/*-*/*-SUMMARY.md; do
+  node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" summary-extract "$summary" --fields one_liner | jq -r '.one_liner'
+done
+```
+
+Extract 4-6 key accomplishments. Present:
+
+```
+Key accomplishments for this milestone:
+1. [Achievement from phase 1]
+2. [Achievement from phase 2]
+3. [Achievement from phase 3]
+4. [Achievement from phase 4]
+5. [Achievement from phase 5]
+```
+
+</step>
+
+<step name="create_milestone_entry">
+
+**Note:** MILESTONES.md entry is now created automatically by `dgs-tools milestone complete` in the archive_milestone step. The entry includes version, date, phase/plan/task counts, and accomplishments extracted from SUMMARY.md files.
+
+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">
+
+Full PROJECT.md evolution review at milestone completion.
+
+Read all phase summaries:
+
+```bash
+cat ${project_root}/phases/*-*/*-SUMMARY.md
+```
+
+**Full review checklist:**
+
+1. **"What This Is" accuracy:**
+   - Compare current description to what was built
+   - Update if product has meaningfully changed
+
+2. **Core Value check:**
+   - 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 this milestone → Move to Validated
+   - Format: `- ✓ [Requirement] — v[X.Y]`
+
+   **Active section:**
+   - Remove requirements moved to Validated
+   - Add new requirements for next milestone
+   - Keep unaddressed requirements
+
+   **Out of Scope audit:**
+   - 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
+
+5. **Key Decisions audit:**
+   - Extract all decisions from milestone phase summaries
+   - Add to Key Decisions table with outcomes
+   - Mark ✓ Good, ⚠️ Revisit, or — Pending
+
+6. **Constraints check:**
+   - Any constraints changed during development? Update as needed
+
+Update PROJECT.md inline. Update "Last updated" footer:
+
+```markdown
+---
+*Last updated: [date] after v[X.Y] milestone*
+```
+
+**Example full evolution (v1.0 → v1.1 prep):**
+
+Before:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Canvas drawing tools
+- [ ] Real-time sync < 500ms
+- [ ] User authentication
+- [ ] Export to PNG
+
+### Out of Scope
+
+- Mobile app — web-first approach
+- Video chat — use external tools
+```
+
+After v1.0:
+
+```markdown
+## What This Is
+
+A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
+
+## Core Value
+
+Real-time sync that feels instant.
+
+## Requirements
+
+### Validated
+
+- ✓ Canvas drawing tools — v1.0
+- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
+- ✓ User authentication — v1.0
+
+### Active
+
+- [ ] Export to PNG
+- [ ] Undo/redo history
+- [ ] Shape tools (rectangles, circles)
+
+### Out of Scope
+
+- Mobile app — web-first approach, PWA works well
+- Video chat — use external tools
+- Offline mode — real-time is core value
+
+## Context
+
+Shipped v1.0 with 2,400 LOC TypeScript.
+Tech stack: Next.js, Supabase, Canvas API.
+Initial user testing showed demand for shape tools.
+```
+
+**Step complete when:**
+
+- [ ] "What This Is" reviewed and updated if needed
+- [ ] Core Value verified as still correct
+- [ ] All shipped requirements moved to Validated
+- [ ] New requirements added to Active for next milestone
+- [ ] Out of Scope reasoning audited
+- [ ] Context updated with current state
+- [ ] All milestone decisions added to Key Decisions
+- [ ] "Last updated" footer reflects milestone completion
+
+</step>
+
+<step name="reorganize_roadmap">
+
+Update `${roadmap_path}` — group completed milestone phases:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
+- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
+
+- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
+- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
+- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
+- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
+
+</details>
+
+### 🚧 v[Next] [Name] (In Progress / Planned)
+
+- [ ] Phase 5: [Name] ([N] plans)
+- [ ] Phase 6: [Name] ([N] plans)
+
+## Progress
+
+| Phase             | Milestone | Plans Complete | Status      | Completed  |
+| ----------------- | --------- | -------------- | ----------- | ---------- |
+| 1. Foundation     | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
+| 2. Authentication | v1.0      | 2/2            | Complete    | YYYY-MM-DD |
+| 3. Core Features  | v1.0      | 3/3            | Complete    | YYYY-MM-DD |
+| 4. Polish         | v1.0      | 1/1            | Complete    | YYYY-MM-DD |
+| 5. Security Audit | v1.1      | 0/1            | Not started | -          |
+| 6. Hardening      | v1.1      | 0/2            | Not started | -          |
+```
+
+</step>
+
+<step name="archive_milestone">
+
+**Delegate archival to dgs-tools:**
+
+```bash
+ARCHIVE=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" milestone complete "v[X.Y]" --name "[Milestone Name]")
+```
+
+The CLI handles:
+- Creating `${project_root}/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)
+
+Extract from result: `version`, `date`, `phases`, `plans`, `tasks`, `accomplishments`, `archived`.
+
+Verify: `✅ Milestone archived to ${project_root}/milestones/`
+
+**If `JOB_MODE` is true:**
+- Log: `[AUTO-RESOLVE] Skipping phase archival in job mode`
+- Keep phases in place (select "Skip" path automatically)
+- Skip the AskUserQuestion below
+
+**If `JOB_MODE` is false (default):**
+
+**Phase archival (optional):** After archival completes, ask the user:
+
+AskUserQuestion(header="Archive Phases", question="Archive phase directories to milestones/?", options: "Yes — move to milestones/v[X.Y]-phases/" | "Skip — keep phases in place")
+
+If "Yes": move phase directories to the milestone archive:
+```bash
+mkdir -p ${project_root}/milestones/v[X.Y]-phases
+# For each phase directory in ${phases_dir}/:
+mv ${phases_dir}/{phase-dir} ${project_root}/milestones/v[X.Y]-phases/
+```
+Verify: `✅ Phase directories archived to ${project_root}/milestones/v[X.Y]-phases/`
+
+If "Skip": Phase directories remain in `${phases_dir}/` as raw execution history. Use `/dgs:cleanup` later to archive retroactively.
+
+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
+
+</step>
+
+<step name="reorganize_roadmap_and_delete_originals">
+
+After `milestone complete` has archived, reorganize ROADMAP.md with milestone groupings, then delete originals:
+
+**Reorganize ROADMAP.md** — group completed milestone phases:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
+
+- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
+- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
+
+</details>
+```
+
+**Then delete originals:**
+
+```bash
+rm ${roadmap_path}
+rm ${project_root}/REQUIREMENTS.md
+```
+
+</step>
+
+<step name="write_retrospective">
+
+**Append to living retrospective:**
+
+Check for existing retrospective:
+```bash
+ls .planning/RETROSPECTIVE.md 2>/dev/null
+```
+
+**If exists:** Read the file, append new milestone section before the "## Cross-Milestone Trends" section.
+
+**If doesn't exist:** Create from template at `~/.claude/deliver-great-systems/templates/retrospective.md`.
+
+**Gather retrospective data:**
+
+1. From SUMMARY.md files: Extract key deliverables, one-liners, tech decisions
+2. From VERIFICATION.md files: Extract verification scores, gaps found
+3. From UAT.md files: Extract test results, issues found
+4. From git log: Count commits, calculate timeline
+5. From the milestone work: Reflect on what worked and what didn't
+
+**Write the milestone section:**
+
+```markdown
+## Milestone: v{version} — {name}
+
+**Shipped:** {date}
+**Phases:** {phase_count} | **Plans:** {plan_count}
+
+### What Was Built
+{Extract from SUMMARY.md one-liners}
+
+### What Worked
+{Patterns that led to smooth execution}
+
+### What Was Inefficient
+{Missed opportunities, rework, bottlenecks}
+
+### Patterns Established
+{New conventions discovered during this milestone}
+
+### Key Lessons
+{Specific, actionable takeaways}
+
+### Cost Observations
+- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Sessions: {count}
+- Notable: {efficiency observation}
+```
+
+**Update cross-milestone trends:**
+
+If the "## Cross-Milestone Trends" section exists, update the tables with new data from this milestone.
+
+**Commit:**
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: update retrospective for v${VERSION}" --files .planning/RETROSPECTIVE.md
+```
+
+</step>
+
+<step name="update_state">
+
+Most STATE.md updates were handled by `milestone complete`, but verify and update remaining fields:
+
+**Project Reference:**
+
+```markdown
+## Project Reference
+
+See: ${project_path} (updated [today])
+
+**Core value:** [Current core value from PROJECT.md]
+**Current focus:** [Next milestone or "Planning next milestone"]
+```
+
+**Accumulated Context:**
+- Clear decisions summary (full log in PROJECT.md)
+- Clear resolved blockers
+- Keep open blockers for next milestone
+
+</step>
+
+<step name="handle_branches">
+
+Check branching strategy and offer merge options.
+
+Use the INIT from the initialize step (already loaded). Extract `branching_strategy`, `phase_branch_template`, `milestone_branch_template`, `commit_docs`, and `current_project` from init JSON.
+
+If branching config is not in milestone-op init, load from config:
+```bash
+cat ${config_path} 2>/dev/null
+```
+
+Extract `base_branch` from init JSON (defaults to `"main"` if not set). This is the integration target for all merge operations on code repos.
+
+Extract `current_project` from init JSON. This is the project slug used for scoped branch discovery.
+
+```bash
+PROJECT_SLUG="${current_project}"  # from init JSON
+```
+
+**If "none":** Skip to git_tag.
+
+**For "phase" strategy:**
+
+```bash
+if [ -n "$PROJECT_SLUG" ]; then
+  # Project-scoped: only find branches for this project
+  PHASE_BRANCHES=$(git branch --list "dgs/${PROJECT_SLUG}/*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
+else
+  # Legacy: use template prefix
+  BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
+  PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
+fi
+echo "Branch discovery: project=$PROJECT_SLUG, found=$(echo "$PHASE_BRANCHES" | wc -w | tr -d ' ') branches"
+echo "Matched branches: $PHASE_BRANCHES"
+```
+
+**For "milestone" strategy:**
+
+```bash
+if [ -n "$PROJECT_SLUG" ]; then
+  # Project-scoped: only find branches for this project
+  MILESTONE_BRANCH=$(git branch --list "dgs/${PROJECT_SLUG}/*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
+else
+  # Legacy: use template prefix
+  BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
+  MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
+fi
+echo "Branch discovery: project=$PROJECT_SLUG, found=$(echo "$MILESTONE_BRANCH" | wc -w | tr -d ' ') branches"
+echo "Matched branches: $MILESTONE_BRANCH"
+```
+
+**If no branches found:** Skip to git_tag.
+
+**If `JOB_MODE` is true:**
+- Log: `[AUTO-RESOLVE] Keeping branches for manual handling in job mode`
+- Skip all branch operations (select "Keep branches" path automatically)
+- Skip to git_tag
+
+**If `JOB_MODE` is false (default):**
+
+**If branches exist:**
+
+**Pre-check: verify base branch exists in all code repos before starting merge:**
+
+```bash
+BASE_BRANCH="${base_branch}"  # from init JSON, defaults to "main"
+
+# If REPOS.md exists, verify base branch in all code repos
+if [ -f "$REPOS_PATH" ]; then
+  for repo in $REPO_PATHS; do
+    git -C "$repo" fetch origin "$BASE_BRANCH" 2>/dev/null || true
+    if ! git -C "$repo" rev-parse --verify "$BASE_BRANCH" >/dev/null 2>&1 && \
+       ! git -C "$repo" rev-parse --verify "origin/$BASE_BRANCH" >/dev/null 2>&1; then
+      echo "Error: Base branch '$BASE_BRANCH' does not exist in repo at $repo"
+      echo "Configure git.base_branch in ${config_path} or create the branch first."
+      exit 1
+    fi
+  done
+fi
+```
+
+```
+## Git Branches Detected
+
+Branching strategy: {phase/milestone}
+Base branch: {BASE_BRANCH}
+Branches: {list}
+
+Options:
+1. **Merge to {BASE_BRANCH}** — Merge branch(es) to {BASE_BRANCH}
+2. **Delete without merging** — Already merged or not needed
+3. **Keep branches** — Leave for manual handling
+```
+
+AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
+
+**Squash merge:**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git fetch origin "$BASE_BRANCH" 2>/dev/null || true
+git checkout "$BASE_BRANCH"
+
+# Initialize cascading context for sequential phase merges
+LEARNINGS_FILE=$(mktemp)
+echo '{}' > "$LEARNINGS_FILE"
+ALL_SEMANTIC_WARNINGS=()
+TOTAL_RESOLVED=0
+TOTAL_ESCALATED=0
+BRANCHES_MERGED=0
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    if ! git merge --squash "$branch"; then
+      # Merge has conflicts -- run conflict resolution agent
+      # Extract phase number from branch name
+      PHASE_NUM=$(echo "$branch" | sed -n 's/.*phase-\([0-9][0-9]*\).*/\1/p')
+      PHASE_DIR=""
+      if [ -n "$PHASE_NUM" ]; then
+        PHASE_DIR=$(ls -d ${phases_dir}/${PHASE_NUM}-* 2>/dev/null | head -1)
+      fi
+
+      RESOLVE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent run --phase-dir "$PHASE_DIR" --learnings "$LEARNINGS_FILE")
+
+      # Parse JSON result
+      RESOLVED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.resolved_count // 0')
+      ESCALATED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.escalated_count // 0')
+      VERIFIED=$(echo "$RESOLVE_RESULT" | jq -r '.verified // false')
+      SEMANTIC_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.semantic_warnings // 0')
+      REPORT_PATH=$(echo "$RESOLVE_RESULT" | jq -r '.report_path // ""')
+
+      TOTAL_RESOLVED=$((TOTAL_RESOLVED + RESOLVED_COUNT))
+
+      if [ "$ESCALATED_COUNT" -gt 0 ]; then
+        # Run escalation protocol per references/conflict-resolution.md
+        STILL_CONFLICTED=$(git diff --name-only --diff-filter=U)
+
+        for FILE in $STILL_CONFLICTED; do
+          RETRY_COUNT=0
+          FILE_RESOLVED=false
+
+          while [ "$RETRY_COUNT" -lt 2 ] && [ "$FILE_RESOLVED" = "false" ]; do
+            CONTEXT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" merge-conflicts context "$FILE" --phase-dir "$PHASE_DIR")
+
+            # Present escalated conflict to user
+            echo "## Escalated Conflict: $FILE"
+            echo ""
+            echo "**Reason:** $(echo "$CONTEXT" | jq -r '.hunks[0].reasoning // "Divergent changes requiring manual review"')"
+            echo "**Type:** $(echo "$CONTEXT" | jq -r '.hunks[0].type // "UNKNOWN"') | **Confidence:** $(echo "$CONTEXT" | jq -r '.hunks[0].confidence // "LOW"')"
+            echo ""
+            echo "### Ours (current branch):"
+            echo "$(echo "$CONTEXT" | jq -r '.hunks[0].ours // "No ours content"')"
+            echo ""
+            echo "### Theirs (merging branch):"
+            echo "$(echo "$CONTEXT" | jq -r '.hunks[0].theirs // "No theirs content"')"
+            echo ""
+            echo "### Plan Context:"
+            echo "$(echo "$CONTEXT" | jq -r '(.plan_context // []) | map(.task_name + " (" + .plan + ")") | join(", ") // "No plan context available"')"
+            echo ""
+            echo "### All Hunk Reasoning:"
+            echo "$(echo "$CONTEXT" | jq -r '(.hunks // []) | map(.type + " [" + .confidence + "]: " + .reasoning) | join("\n") // "No hunk analysis available"')"
+            echo ""
+            echo "Options:"
+            echo "1. **Accept** proposed resolution"
+            echo "2. **Reject with hint** -- provide guidance for retry"
+            echo "3. **Abort this file** -- skip, leave unresolved"
+
+            # AskUserQuestion: Accept / Reject with hint / Abort
+            # On Accept: apply proposed resolution
+            # On Reject with hint: capture hint, retry
+            # On Abort: take theirs or abort merge for this branch
+
+            case "$USER_CHOICE" in
+              accept)
+                RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR")
+                git add "$FILE"
+                FILE_RESOLVED=true
+                TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+                ;;
+              reject)
+                RETRY_COUNT=$((RETRY_COUNT + 1))
+                RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR" --hint "$USER_HINT")
+                # Check if resolved
+                if ! grep -q '^<\{7\}' "$FILE" 2>/dev/null; then
+                  git add "$FILE"
+                  FILE_RESOLVED=true
+                  TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+                fi
+                ;;
+              abort)
+                TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+                git checkout --theirs "$FILE" && git add "$FILE"
+                FILE_RESOLVED=true
+                ;;
+            esac
+          done
+
+          # Max retries exhausted -- abort this file
+          if [ "$FILE_RESOLVED" = "false" ]; then
+            TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+            git merge --abort
+            echo "Aborted merge for branch $branch after 2 failed retries on $FILE"
+            continue 2  # Skip to next branch
+          fi
+        done
+      fi
+
+      if [ "$VERIFIED" = "false" ]; then
+        # Post-resolution verification failed
+        echo "## Post-Resolution Verification Failed"
+        echo ""
+        echo "$(echo "$RESOLVE_RESULT" | jq -r '.verification_errors // [] | join("\n")')"
+        echo ""
+        echo "Options:"
+        echo "1. **Proceed anyway** -- commit despite test failures"
+        echo "2. **Abort merge** -- git merge --abort, skip this branch"
+
+        # AskUserQuestion: Proceed / Abort
+        # On Abort: git merge --abort; continue
+      fi
+    fi
+
+    # Strip planning root from staging if commit_docs is false
+    if [ "$COMMIT_DOCS" = "false" ]; then
+      git reset HEAD ${project_root}/ 2>/dev/null || true
+    fi
+    git commit -m "feat: $branch for v[X.Y]"
+
+    # Extract and accumulate learnings for cascading context
+    if [ -n "$RESOLVE_RESULT" ]; then
+      NEW_LEARNINGS=$(echo "$RESOLVE_RESULT" | jq -r '.learnings // {}')
+      if [ "$NEW_LEARNINGS" != "{}" ] && [ "$NEW_LEARNINGS" != "null" ]; then
+        EXISTING_LEARNINGS=$(cat "$LEARNINGS_FILE")
+        # Merge: accumulate files_resolved, strategies_used, domain_changes, increment phase_merges_completed
+        MERGED=$(echo "$EXISTING_LEARNINGS" "$NEW_LEARNINGS" | jq -s '
+          if (.[0] | type) == "object" and (.[0] | has("files_resolved")) then
+            {
+              files_resolved: ((.[0].files_resolved // []) + (.[1].files_resolved // [])),
+              strategies_used: ((.[0].strategies_used // []) + (.[1].strategies_used // [])),
+              domain_changes: ((.[0].domain_changes // {}) * (.[1].domain_changes // {})),
+              phase_merges_completed: ((.[0].phase_merges_completed // 0) + (.[1].phase_merges_completed // 0))
+            }
+          else
+            .[1]
+          end
+        ')
+        echo "$MERGED" > "$LEARNINGS_FILE"
+      fi
+    fi
+
+    BRANCHES_MERGED=$((BRANCHES_MERGED + 1))
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  if ! git merge --squash "$MILESTONE_BRANCH"; then
+    # Merge has conflicts -- run conflict resolution agent
+    PHASE_DIR=$(ls -d ${phases_dir}/*/ 2>/dev/null | tail -1)
+
+    RESOLVE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent run --phase-dir "$PHASE_DIR")
+    RESOLVED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.resolved_count // 0')
+    ESCALATED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.escalated_count // 0')
+    VERIFIED=$(echo "$RESOLVE_RESULT" | jq -r '.verified // false')
+
+    TOTAL_RESOLVED=$((TOTAL_RESOLVED + RESOLVED_COUNT))
+
+    if [ "$ESCALATED_COUNT" -gt 0 ]; then
+      # Run escalation protocol (same as phase strategy above)
+      STILL_CONFLICTED=$(git diff --name-only --diff-filter=U)
+      for FILE in $STILL_CONFLICTED; do
+        RETRY_COUNT=0
+        FILE_RESOLVED=false
+
+        while [ "$RETRY_COUNT" -lt 2 ] && [ "$FILE_RESOLVED" = "false" ]; do
+          CONTEXT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" merge-conflicts context "$FILE" --phase-dir "$PHASE_DIR")
+          echo "## Escalated Conflict: $FILE"
+          echo "**Reason:** $(echo "$CONTEXT" | jq -r '.hunks[0].reasoning // "Divergent changes requiring manual review"')"
+          echo "**Type:** $(echo "$CONTEXT" | jq -r '.hunks[0].type // "UNKNOWN"') | **Confidence:** $(echo "$CONTEXT" | jq -r '.hunks[0].confidence // "LOW"')"
+          echo "Options: 1. Accept  2. Reject with hint  3. Abort this file"
+
+          case "$USER_CHOICE" in
+            accept)
+              RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR")
+              git add "$FILE"
+              FILE_RESOLVED=true
+              TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+              ;;
+            reject)
+              RETRY_COUNT=$((RETRY_COUNT + 1))
+              RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR" --hint "$USER_HINT")
+              if ! grep -q '^<\{7\}' "$FILE" 2>/dev/null; then
+                git add "$FILE"
+                FILE_RESOLVED=true
+                TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+              fi
+              ;;
+            abort)
+              TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+              git checkout --theirs "$FILE" && git add "$FILE"
+              FILE_RESOLVED=true
+              ;;
+          esac
+        done
+
+        if [ "$FILE_RESOLVED" = "false" ]; then
+          TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+          git merge --abort
+          echo "Aborted merge for $MILESTONE_BRANCH after 2 failed retries on $FILE"
+          break
+        fi
+      done
+    fi
+
+    if [ "$VERIFIED" = "false" ]; then
+      echo "## Post-Resolution Verification Failed"
+      echo "Options: 1. Proceed anyway  2. Abort merge"
+    fi
+  fi
+
+  # Strip planning root from staging if commit_docs is false
+  if [ "$COMMIT_DOCS" = "false" ]; then
+    git reset HEAD ${project_root}/ 2>/dev/null || true
+  fi
+  git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
+  BRANCHES_MERGED=$((BRANCHES_MERGED + 1))
+fi
+
+# Display semantic conflict warnings after all branch merges
+if [ "$SEMANTIC_COUNT" -gt 0 ] || [ ${#ALL_SEMANTIC_WARNINGS[@]} -gt 0 ]; then
+  echo ""
+  echo "## Semantic Conflict Warnings"
+  echo ""
+  echo "The following files were modified by multiple branches and may have semantic conflicts"
+  echo "even though they merged cleanly. Consider integration testing these areas:"
+  echo ""
+  # List files with domain descriptions from resolution reports
+fi
+
+# Display final conflict resolution summary
+echo ""
+echo "Conflict Resolution Complete:"
+echo "- $BRANCHES_MERGED branches merged"
+echo "- $TOTAL_RESOLVED total conflicts resolved"
+echo "- $TOTAL_ESCALATED conflicts escalated to user"
+echo "- $SEMANTIC_COUNT semantic warnings emitted"
+if [ -n "$REPORT_PATH" ]; then
+  echo "- Report: $REPORT_PATH"
+fi
+
+# Clean up
+rm -f "$LEARNINGS_FILE"
+
+git checkout "$CURRENT_BRANCH"
+```
+
+**Merge with history:**
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+git fetch origin "$BASE_BRANCH" 2>/dev/null || true
+git checkout "$BASE_BRANCH"
+
+# Initialize cascading context for sequential phase merges
+LEARNINGS_FILE=$(mktemp)
+echo '{}' > "$LEARNINGS_FILE"
+ALL_SEMANTIC_WARNINGS=()
+TOTAL_RESOLVED=0
+TOTAL_ESCALATED=0
+BRANCHES_MERGED=0
+
+if [ "$BRANCHING_STRATEGY" = "phase" ]; then
+  for branch in $PHASE_BRANCHES; do
+    if ! git merge --no-ff --no-commit "$branch"; then
+      # Merge has conflicts -- run conflict resolution agent
+      PHASE_NUM=$(echo "$branch" | sed -n 's/.*phase-\([0-9][0-9]*\).*/\1/p')
+      PHASE_DIR=""
+      if [ -n "$PHASE_NUM" ]; then
+        PHASE_DIR=$(ls -d ${phases_dir}/${PHASE_NUM}-* 2>/dev/null | head -1)
+      fi
+
+      RESOLVE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent run --phase-dir "$PHASE_DIR" --learnings "$LEARNINGS_FILE")
+
+      RESOLVED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.resolved_count // 0')
+      ESCALATED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.escalated_count // 0')
+      VERIFIED=$(echo "$RESOLVE_RESULT" | jq -r '.verified // false')
+      SEMANTIC_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.semantic_warnings // 0')
+      REPORT_PATH=$(echo "$RESOLVE_RESULT" | jq -r '.report_path // ""')
+
+      TOTAL_RESOLVED=$((TOTAL_RESOLVED + RESOLVED_COUNT))
+
+      if [ "$ESCALATED_COUNT" -gt 0 ]; then
+        # Run escalation protocol per references/conflict-resolution.md
+        STILL_CONFLICTED=$(git diff --name-only --diff-filter=U)
+
+        for FILE in $STILL_CONFLICTED; do
+          RETRY_COUNT=0
+          FILE_RESOLVED=false
+
+          while [ "$RETRY_COUNT" -lt 2 ] && [ "$FILE_RESOLVED" = "false" ]; do
+            CONTEXT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" merge-conflicts context "$FILE" --phase-dir "$PHASE_DIR")
+
+            echo "## Escalated Conflict: $FILE"
+            echo "**Reason:** $(echo "$CONTEXT" | jq -r '.hunks[0].reasoning // "Divergent changes requiring manual review"')"
+            echo "**Type:** $(echo "$CONTEXT" | jq -r '.hunks[0].type // "UNKNOWN"') | **Confidence:** $(echo "$CONTEXT" | jq -r '.hunks[0].confidence // "LOW"')"
+            echo "Options: 1. Accept  2. Reject with hint  3. Abort this file"
+
+            case "$USER_CHOICE" in
+              accept)
+                RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR")
+                git add "$FILE"
+                FILE_RESOLVED=true
+                TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+                ;;
+              reject)
+                RETRY_COUNT=$((RETRY_COUNT + 1))
+                RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR" --hint "$USER_HINT")
+                if ! grep -q '^<\{7\}' "$FILE" 2>/dev/null; then
+                  git add "$FILE"
+                  FILE_RESOLVED=true
+                  TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+                fi
+                ;;
+              abort)
+                TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+                git checkout --theirs "$FILE" && git add "$FILE"
+                FILE_RESOLVED=true
+                ;;
+            esac
+          done
+
+          if [ "$FILE_RESOLVED" = "false" ]; then
+            TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+            git merge --abort
+            echo "Aborted merge for branch $branch after 2 failed retries on $FILE"
+            continue 2
+          fi
+        done
+      fi
+
+      if [ "$VERIFIED" = "false" ]; then
+        echo "## Post-Resolution Verification Failed"
+        echo "Options: 1. Proceed anyway  2. Abort merge"
+      fi
+    fi
+
+    # Strip planning root from staging if commit_docs is false
+    if [ "$COMMIT_DOCS" = "false" ]; then
+      git reset HEAD ${project_root}/ 2>/dev/null || true
+    fi
+    git commit -m "Merge branch '$branch' for v[X.Y]"
+
+    # Extract and accumulate learnings for cascading context
+    if [ -n "$RESOLVE_RESULT" ]; then
+      NEW_LEARNINGS=$(echo "$RESOLVE_RESULT" | jq -r '.learnings // {}')
+      if [ "$NEW_LEARNINGS" != "{}" ] && [ "$NEW_LEARNINGS" != "null" ]; then
+        EXISTING_LEARNINGS=$(cat "$LEARNINGS_FILE")
+        # Merge: accumulate files_resolved, strategies_used, domain_changes, increment phase_merges_completed
+        MERGED=$(echo "$EXISTING_LEARNINGS" "$NEW_LEARNINGS" | jq -s '
+          if (.[0] | type) == "object" and (.[0] | has("files_resolved")) then
+            {
+              files_resolved: ((.[0].files_resolved // []) + (.[1].files_resolved // [])),
+              strategies_used: ((.[0].strategies_used // []) + (.[1].strategies_used // [])),
+              domain_changes: ((.[0].domain_changes // {}) * (.[1].domain_changes // {})),
+              phase_merges_completed: ((.[0].phase_merges_completed // 0) + (.[1].phase_merges_completed // 0))
+            }
+          else
+            .[1]
+          end
+        ')
+        echo "$MERGED" > "$LEARNINGS_FILE"
+      fi
+    fi
+
+    BRANCHES_MERGED=$((BRANCHES_MERGED + 1))
+  done
+fi
+
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  if ! git merge --no-ff --no-commit "$MILESTONE_BRANCH"; then
+    # Merge has conflicts -- run conflict resolution agent
+    PHASE_DIR=$(ls -d ${phases_dir}/*/ 2>/dev/null | tail -1)
+
+    RESOLVE_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent run --phase-dir "$PHASE_DIR")
+    RESOLVED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.resolved_count // 0')
+    ESCALATED_COUNT=$(echo "$RESOLVE_RESULT" | jq -r '.escalated_count // 0')
+    VERIFIED=$(echo "$RESOLVE_RESULT" | jq -r '.verified // false')
+
+    TOTAL_RESOLVED=$((TOTAL_RESOLVED + RESOLVED_COUNT))
+
+    if [ "$ESCALATED_COUNT" -gt 0 ]; then
+      STILL_CONFLICTED=$(git diff --name-only --diff-filter=U)
+      for FILE in $STILL_CONFLICTED; do
+        RETRY_COUNT=0
+        FILE_RESOLVED=false
+
+        while [ "$RETRY_COUNT" -lt 2 ] && [ "$FILE_RESOLVED" = "false" ]; do
+          CONTEXT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" merge-conflicts context "$FILE" --phase-dir "$PHASE_DIR")
+          echo "## Escalated Conflict: $FILE"
+          echo "**Reason:** $(echo "$CONTEXT" | jq -r '.hunks[0].reasoning // "Divergent changes requiring manual review"')"
+          echo "**Type:** $(echo "$CONTEXT" | jq -r '.hunks[0].type // "UNKNOWN"') | **Confidence:** $(echo "$CONTEXT" | jq -r '.hunks[0].confidence // "LOW"')"
+          echo "Options: 1. Accept  2. Reject with hint  3. Abort this file"
+
+          case "$USER_CHOICE" in
+            accept)
+              RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR")
+              git add "$FILE"
+              FILE_RESOLVED=true
+              TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+              ;;
+            reject)
+              RETRY_COUNT=$((RETRY_COUNT + 1))
+              RETRY_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" conflict-agent resolve-file "$FILE" --phase-dir "$PHASE_DIR" --hint "$USER_HINT")
+              if ! grep -q '^<\{7\}' "$FILE" 2>/dev/null; then
+                git add "$FILE"
+                FILE_RESOLVED=true
+                TOTAL_RESOLVED=$((TOTAL_RESOLVED + 1))
+              fi
+              ;;
+            abort)
+              TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+              git checkout --theirs "$FILE" && git add "$FILE"
+              FILE_RESOLVED=true
+              ;;
+          esac
+        done
+
+        if [ "$FILE_RESOLVED" = "false" ]; then
+          TOTAL_ESCALATED=$((TOTAL_ESCALATED + 1))
+          git merge --abort
+          echo "Aborted merge for $MILESTONE_BRANCH after 2 failed retries on $FILE"
+          break
+        fi
+      done
+    fi
+
+    if [ "$VERIFIED" = "false" ]; then
+      echo "## Post-Resolution Verification Failed"
+      echo "Options: 1. Proceed anyway  2. Abort merge"
+    fi
+  fi
+
+  # Strip planning root from staging if commit_docs is false
+  if [ "$COMMIT_DOCS" = "false" ]; then
+    git reset HEAD ${project_root}/ 2>/dev/null || true
+  fi
+  git commit -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
+  BRANCHES_MERGED=$((BRANCHES_MERGED + 1))
+fi
+
+# Display semantic conflict warnings after all branch merges
+if [ "$SEMANTIC_COUNT" -gt 0 ] || [ ${#ALL_SEMANTIC_WARNINGS[@]} -gt 0 ]; then
+  echo ""
+  echo "## Semantic Conflict Warnings"
+  echo ""
+  echo "The following files were modified by multiple branches and may have semantic conflicts"
+  echo "even though they merged cleanly. Consider integration testing these areas:"
+  echo ""
+fi
+
+# Display final conflict resolution summary
+echo ""
+echo "Conflict Resolution Complete:"
+echo "- $BRANCHES_MERGED branches merged"
+echo "- $TOTAL_RESOLVED total conflicts resolved"
+echo "- $TOTAL_ESCALATED conflicts escalated to user"
+echo "- $SEMANTIC_COUNT semantic warnings emitted"
+if [ -n "$REPORT_PATH" ]; then
+  echo "- Report: $REPORT_PATH"
+fi
+
+# Clean up
+rm -f "$LEARNINGS_FILE"
+
+git checkout "$CURRENT_BRANCH"
+```
+
+**Delete without merging:**
+
+```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:
+
+```bash
+git tag -a v[X.Y] -m "v[X.Y] [Name]
+
+Delivered: [One sentence]
+
+Key accomplishments:
+- [Item 1]
+- [Item 2]
+- [Item 3]
+
+See ${project_root}/MILESTONES.md for full details."
+```
+
+Confirm: "Tagged: v[X.Y]"
+
+**If `JOB_MODE` is true:**
+- Log: `[AUTO-RESOLVE] Skipping tag push in job mode`
+- Do not push tag
+- Skip to git_commit_milestone
+
+**If `JOB_MODE` is false (default):**
+
+Ask: "Push tag to remote? (y/n)"
+
+If yes:
+```bash
+git push origin v[X.Y]
+```
+
+</step>
+
+<step name="git_commit_milestone">
+
+Commit milestone completion.
+
+```bash
+node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "chore: complete v[X.Y] milestone" --files ${project_root}/milestones/v[X.Y]-ROADMAP.md ${project_root}/milestones/v[X.Y]-REQUIREMENTS.md ${project_root}/v[X.Y]-MILESTONE-AUDIT.md ${project_root}/MILESTONES.md ${project_path} ${state_path}
+```
+```
+
+Confirm: "Committed: chore: complete v[X.Y] milestone"
+
+</step>
+
+<step name="offer_next">
+
+```
+✅ Milestone v[X.Y] [Name] complete
+
+Shipped:
+- [N] phases ([M] plans, [P] tasks)
+- [One sentence of what shipped]
+
+Archived:
+- milestones/v[X.Y]-ROADMAP.md
+- milestones/v[X.Y]-REQUIREMENTS.md
+
+Summary: ${project_root}/MILESTONES.md
+Tag: v[X.Y]
+
+---
+
+## ▶ Next Up
+
+**Start Next Milestone** — questioning → research → requirements → roadmap
+
+`/dgs:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+</step>
+
+</process>
+
+<milestone_naming>
+
+**Version conventions:**
+- **v1.0** — Initial MVP
+- **v1.1, v1.2** — Minor updates, new features, fixes
+- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
+
+**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, public releases, major feature sets shipped, before archiving planning.
+
+**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
+
+Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
+
+</what_qualifies>
+
+<success_criteria>
+
+Milestone completion is successful when:
+
+- [ ] MILESTONES.md entry created with stats and accomplishments
+- [ ] PROJECT.md full evolution review completed
+- [ ] All shipped requirements moved to Validated in PROJECT.md
+- [ ] Key Decisions updated with outcomes
+- [ ] ROADMAP.md reorganized with milestone grouping
+- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
+- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
+- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
+- [ ] STATE.md updated with fresh project reference
+- [ ] Git tag created (v[X.Y])
+- [ ] Milestone commit made (includes archive files and deletion)
+- [ ] Requirements completion checked against REQUIREMENTS.md traceability table
+- [ ] Incomplete requirements surfaced with proceed/audit/abort options
+- [ ] Known gaps recorded in MILESTONES.md if user proceeded with incomplete requirements
+- [ ] RETROSPECTIVE.md updated with milestone section
+- [ ] Cross-milestone trends updated
+- [ ] User knows next step (/dgs:new-milestone)
+
+</success_criteria>