kata-complete-milestone

What this skill does

<objective>
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.
</objective>

<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>

<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")
  </context>

<process>

**Follow milestone-complete.md workflow:**

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

   **Check pr_workflow config FIRST before any other work:**

   ```bash
   PR_WORKFLOW=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" read-config "pr_workflow" "false")
   CURRENT_BRANCH=$(git branch --show-current)
   WORKTREE_ENABLED=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/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.

   ```bash
   # 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:

   ```bash
   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:

```bash
if [ -f .planning/ROADMAP.md ]; then
  node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/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.

```bash
# Validate config and template overrides
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" check-config 2>/dev/null || true
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" check-template-drift 2>/dev/null || true
```

0.2. **Read workflow config:**

Read workflow-specific overrides for milestone completion:

```bash
VERSION_FILES_JSON=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/scripts/kata-lib.cjs" read-pref "workflows.complete-milestone.version_files" "[]")
PRE_RELEASE_CMDS_JSON=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-complete-milestone/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:

```bash
# 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 "$FIXES" ]; then BUMP_TYPE="patch"
else BUMP_TYPE="none"
fi

echo "CURRENT=$CURRENT_VERSION BUMP=$BUMP_TYPE"
echo "FEATURES: $FEATURES"
echo "FIXES: $FIXES"
```

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

   ```markdown
   ## 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.
   ```

1. **Verify readiness:**
   - Check all phases in milestone have completed plans (SUMMARY.md exists)
   - Present milestone scope and stats
   - Wait for confirmation

1. **Gather stats:**
   - Count phases, plans, tasks
   - Calculate git range, file changes, LOC
   - Extract timeline from git log
   - Present summary, conf