kata-complete-milestone

name	kata-complete-milestone
description	Archive a completed milestone, preparing for the next version, marking a milestone complete, shipping a version, or wrapping up milestone work. Triggers include "complete milestone", "finish milestone", "archive milestone", "ship version", "mark milestone done", "milestone complete", "release version", "create release", and "ship milestone". Use when this capability is needed.
metadata	{"author":"gannonh"}

Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.

Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone. Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.

<execution_context> Load these files NOW (before proceeding):

• @./references/milestone-complete.md (main workflow)
• @./references/milestone-archive-template.md (archive template)
• @./references/version-detector.md (version detection functions)
• @./references/changelog-generator.md (changelog generation functions) </execution_context>

**Project files:** - `.planning/ROADMAP.md` - `.planning/REQUIREMENTS.md` - `.planning/STATE.md` - `.planning/PROJECT.md`

User input:

• Version: {{version}} (e.g., "1.0", "1.1", "2.0")

Follow milestone-complete.md workflow:

0. CRITICAL: Branch setup (if pr_workflow=true)

   Check pr_workflow config FIRST before any other work:

   PR_WORKFLOW=$(node scripts/kata-lib.cjs read-config "pr_workflow" "false")
   CURRENT_BRANCH=$(git branch --show-current)
   WORKTREE_ENABLED=$(node scripts/kata-lib.cjs read-config "worktree.enabled" "false")
   

   If PR_WORKFLOW=true AND on main:

   You MUST create a release branch BEFORE proceeding. All milestone completion work goes on that branch.

   # Determine version from user input or detect from project files
   # (version-detector.md handles detection across project types)
   VERSION="X.Y.Z"  # Set from user input or detection
   

   Release branches always use the main/ working directory. Do NOT create a separate worktree for release work. Milestone completion is sequential admin work with no parallelism — a separate worktree adds complexity with no benefit.

   Create the release branch in the current working directory. In bare repo layout, CWD is already main/. In normal repos, CWD is the project root. Both cases use the same command:

   RELEASE_BRANCH="release/v$VERSION"
   git checkout -b "$RELEASE_BRANCH"
   

   Display:

   ⚠ pr_workflow is enabled — creating release branch.
   
   Branch: $RELEASE_BRANCH
   
   All milestone completion commits will go to this branch.
   After completion, a PR will be created to merge to main.
   

   If PR_WORKFLOW=false OR already on a non-main branch:

   Proceed with current branch (commits go to main or current branch).

   GATE: Do NOT proceed until branch is correct:

   • If pr_workflow=true, you must be on release/vX.Y.Z branch
   • If pr_workflow=false, main branch is OK

   All subsequent steps work in the current working directory. Do NOT cd to any other directory.

0.1. Pre-flight: Check roadmap format (auto-migration)

Read workflow-specific overrides for milestone completion. Also check and auto-migrate roadmap format if needed:

if [ -f .planning/ROADMAP.md ]; then
  node scripts/kata-lib.cjs check-roadmap 2>/dev/null
  FORMAT_EXIT=$?
  
  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi

If exit code 1 (old format):

Invoke kata-doctor in auto mode:

Skill("kata-doctor", "--auto")

Continue after migration completes.

If exit code 0 or 2: Continue silently.

# Validate config and template overrides
node scripts/kata-lib.cjs check-config 2>/dev/null || true
node scripts/kata-lib.cjs check-template-drift 2>/dev/null || true

0.2. Read workflow config:

Read workflow-specific overrides for milestone completion:

VERSION_FILES_JSON=$(node scripts/kata-lib.cjs read-pref "workflows.complete-milestone.version_files" "[]")
PRE_RELEASE_CMDS_JSON=$(node scripts/kata-lib.cjs read-pref "workflows.complete-milestone.pre_release_commands" "[]")

• version_files: overrides version-detector.md auto-detection when non-empty
• pre_release_commands: run after version bump, before archive (failures blocking)

Store for use in release workflow steps. See milestone-complete.md read_workflow_config step.

0.2. Generate release artifacts:

Proactively generate changelog and version bump. Use the functions defined in version-detector.md and changelog-generator.md. Run these steps using the exact function definitions from those references:

# 1. Get current version (version-detector.md: get_current_version)
CURRENT_VERSION=$(node -p "require('./package.json').version" 2>/dev/null || git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "0.0.0")

# 2. Get commits since last tag (version-detector.md: commit_parsing)
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -n "$LAST_TAG" ]; then
  COMMITS=$(git log --oneline --format="%s" "$LAST_TAG"..HEAD)
else
  COMMITS=$(git log --oneline --format="%s")
fi

# 3. Categorize commits
BREAKING=$(echo "$COMMITS" | grep -E "^[a-z]+(\(.+\))?!:|BREAKING CHANGE:" || true)
FEATURES=$(echo "$COMMITS" | grep -E "^feat(\(.+\))?:" || true)
FIXES=$(echo "$COMMITS" | grep -E "^fix(\(.+\))?:" || true)

# 4. Determine bump type
if [ -n "$BREAKING" ]; then BUMP_TYPE="major"
elif [ -n "$FEATURES" ]; then BUMP_TYPE="minor"
elif [ -n  ];  BUMP_TYPE=
 BUMP_TYPE=


 
 
 

Calculate next version using calculate_next_version from version-detector.md. Generate changelog entry using changelog-generator.md format. Update version in project files using update_versions from version-detector.md (if version changed).

Present all proposed changes for review:

## Release Preview

**Current version:** $CURRENT_VERSION
**Bump type:** $BUMP_TYPE
**Next version:** $NEXT_VERSION

**Changelog entry:**
## [$NEXT_VERSION] - $DATE

### Added
[feat commits formatted]

### Fixed
[fix commits formatted]

### Changed
[docs/refactor/perf commits formatted]

**Files updated:**
[list each version file detected and updated]
- CHANGELOG.md → new entry prepended

Use AskUserQuestion:

• header: "Release Changes"
• question: "Review the release changes above. Approve?"
• options:
  • "Approve" — Keep changes and proceed to verify readiness
  • "Edit changelog first" — Pause for user edits, then confirm
  • "Revert and skip release" — Undo release file changes, proceed to verify readiness without release artifacts

1. Check for audit:

   • Look for .planning/v{{version}}-MILESTONE-AUDIT.md
   • If missing or stale: recommend /kata-audit-milestone first
   • If audit status is gaps_found: recommend /kata-plan-milestone-gaps first
   • If audit status is passed: proceed to step 1

   ## Pre-flight Check
   
   {If no v{{version}}-MILESTONE-AUDIT.md:}
   ⚠ No milestone audit found. Run `/kata-audit-milestone` first to verify
   requirements coverage, cross-phase integration, and E2E flows.
   
   {If audit has gaps:}
   ⚠ Milestone audit found gaps. Run `/kata-plan-milestone-gaps` to create
   phases that close the gaps, or proceed anyway to accept as tech debt.
   
   {If audit passed:}
   ✓ Milestone audit passed. Proceeding with completion.
   

2. Verify readiness:

   • Check all phases in milestone have completed plans (SUMMARY.md exists)
   • Present milestone scope and stats
   • Wait for confirmation

3. Gather stats:

   • Count phases, plans, tasks
   • Calculate git range, file changes, LOC
   • Extract timeline from git log
   • Present summary, confirm

4. Extract accomplishments:

   • Read all phase SUMMARY.md files in milestone range
   • Extract 4-6 key accomplishments
   • Present for approval

5. Archive milestone:

   • Create .planning/milestones/v{{version}}-ROADMAP.md
   • Extract full phase details from ROADMAP.md
   • Fill milestone-archive.md template
   • Update ROADMAP.md to one-line summary with link

6. Archive requirements:

   • Create .planning/milestones/v{{version}}-REQUIREMENTS.md
   • Mark all v1 requirements as complete (checkboxes checked)
   • Note requirement outcomes (validated, adjusted, dropped)
   • Delete .planning/REQUIREMENTS.md (fresh one created for next milestone)

7. Update PROJECT.md:

   • Add "Current State" section with shipped version

6.5. Review Documentation (Non-blocking):

Before committing, offer final README review:

Use AskUserQuestion:

• header: "Final README Review"
• question: "Revise README before completing milestone v{{version}}?"
• options:
  • "Yes, draft an update for my review" — Revise README and present to the user for approval
  • "No, I'll make the edits myself" — Pause for user review, wait for "continue"
  • "Skip for now" — Proceed directly to commit

If "Yes, I'll review now":

Review README.md for the complete v{{version}} milestone.
Ensure all shipped features are documented.
Say "continue" when ready to proceed.

If "Show README": Display README.md, then use AskUserQuestion:

• header: "README Accuracy"
• question: "Does this look accurate for v{{version}}?"
• options:
  • "Yes, looks good" — Proceed to Step 7
  • "Needs updates" — Pause for user edits, wait for "continue"

If "Skip" or review complete: Proceed to Step 7.

Non-blocking: milestone completion continues regardless of choice.

6.7. Close GitHub Milestone:

If github.enabled, close the GitHub Milestone for this version. See milestone-complete.md close_github_milestone step for details.

7. Commit and finalize:

   • Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
   • Commit: chore: complete v{{version}} milestone

   PR workflow handling (branch was created in step 0):

   PR_WORKFLOW=$(node scripts/kata-lib.cjs read-config "pr_workflow" "false")
   CURRENT_BRANCH=$(git branch --show-current)
   

   If PR_WORKFLOW=true (on release/vX.Y.Z branch):

   Push branch and create PR:

   # Push branch (use --head for bare repo layout where gh can't auto-detect)
   git push -u origin "$CURRENT_BRANCH"
   
   # Collect all phase issues for this milestone
   GITHUB_ENABLED=$(node scripts/kata-lib.cjs read-config "github.enabled" "false")
   ISSUE_MODE=$(node scripts/kata-lib.cjs read-config "github.issue_mode" "never")
   
   CLOSES_LINES=""
   if [ "$GITHUB_ENABLED" = "true" ] && [ "$ISSUE_MODE" != "never" ]; then
     # Get all phase issue numbers for this milestone
     # --state all includes already-closed issues (GitHub ignores redundant Closes #X,
     # but including them ensures PR body reflects all related work)
     # gh issue list --milestone only searches open milestones; use API to include closed
     REPO_SLUG=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
     MS_NUM=$(gh api "repos/${REPO_SLUG}/milestones?state=all" --jq ".[] | select(.title==\"v{{version}}\") | .number" 2>/dev/null)
     PHASE_ISSUES=""
     if [ -n "$MS_NUM" ]; 
       PHASE_ISSUES=$(gh api  \
         --jq  2>/dev/null)
     
   
      [ -z  ]; 
        
     
   
     
      num  ; 
       CLOSES_LINES=
     
   
   
   
   gh  create \
     --  \
     --base main \
     --title  \
     --body 
   

<success_criteria>

• Milestone archived to .planning/milestones/v{{version}}-ROADMAP.md
• Requirements archived to .planning/milestones/v{{version}}-REQUIREMENTS.md
• .planning/REQUIREMENTS.md deleted (fresh for next milestone)
• ROADMAP.md collapsed to one-line entry
• PROJECT.md updated with current state
• Git tag v{{version}} created (if pr_workflow=false) OR PR created/instructions given (if pr_workflow=true)
• GitHub Milestone v{{version}} closed (if github.enabled)
• Commit successful
• User knows next steps (including need for fresh requirements)

If release workflow was run:

• CHANGELOG.md updated with v{{version}} entry (reviewed and approved)
• Version bumped in all detected project version files
• GitHub Release created (if pr_workflow=false) OR instructions provided (if pr_workflow=true) </success_criteria>

<critical_rules>

• Load workflow first: Read milestone-complete.md before executing
• Verify completion: All phases must have SUMMARY.md files
• User confirmation: Wait for approval at verification gates
• Archive before deleting: Always create archive files before updating/deleting originals
• One-line summary: Collapsed milestone in ROADMAP.md should be single line with link
• Context efficiency: Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
• Fresh requirements: Next milestone starts with /kata-add-milestone which includes requirements definition </critical_rules>

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.