mindsystem-cc 3.17.1 → 3.18.0

package/mindsystem/workflows/complete-milestone.md

@@ -1,8 +1,6 @@
 <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. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, archives ROADMAP.md and REQUIREMENTS.md, and tags the release in git.
 
 </purpose>
 
@@ -22,25 +20,14 @@ This is the ritual that separates "development" from "shipped."
 
 When a milestone completes, this workflow:
 
-1. Cleans up raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER deleted)
-2. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
-3. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
-4. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
-5. Archives milestone context to `.planning/milestones/v[X.Y]/CONTEXT.md`
-6. Archives research files to `.planning/milestones/v[X.Y]/research/` (if exists)
-7. Updates ROADMAP.md to replace milestone details with one-line summary
-8. Deletes REQUIREMENTS.md (fresh one created for next milestone)
-9. Performs full PROJECT.md evolution review
-10. Routes to `/ms:new-milestone` for next milestone
-
-Knowledge files in `.planning/knowledge/` persist across milestones (maintained by phase-level consolidation in execute-phase).
-
-**Context Efficiency:**
-
-- 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. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
+2. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
+3. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+4. Archives milestone files via script (audit, context, research — whichever exist)
+5. Consolidates phase summaries, deletes artifacts, moves phase dirs via script
+6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+7. Performs full PROJECT.md evolution review
+8. Routes to `/ms:new-milestone` for next milestone
 
 **Archive Format:**
 
@@ -49,6 +36,10 @@ Knowledge files in `.planning/knowledge/` persist across milestones (maintained
 - Full phase details from roadmap
 - Milestone summary (decisions, issues, technical debt)
 
+**PHASE-SUMMARIES** consolidates all `*-SUMMARY.md` files from phase directories, organized by phase and plan, before artifacts are deleted.
+
+**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`) moved from `.planning/phases/`.
+
 **REQUIREMENTS archive** contains:
 - All v1 requirements marked complete with outcomes
 - Traceability table with final status
@@ -60,32 +51,10 @@ Knowledge files in `.planning/knowledge/` persist across milestones (maintained
 
 <step name="verify_readiness">
 
-Check if milestone is truly complete:
+Read roadmap to determine milestone phase range (`PHASE_START`, `PHASE_END`) for the stats script:
 
 ```bash
 cat .planning/ROADMAP.md
-ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
-```
-
-**Questions to ask:**
-
-- 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?
-
-Present:
-
-```
-Milestone: [Name from user, e.g., "v1.0 MVP"]
-
-Appears to include:
-- 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
 ```
 
 <config-check>
@@ -96,74 +65,30 @@ cat .planning/config.json 2>/dev/null
 
 </config-check>
 
-```
-⚡ Auto-approved: Milestone scope verification
-
-[Show breakdown summary without prompting]
-
-Proceeding to stats gathering...
-```
-
-Proceed directly to cleanup_artifacts step.
-
-</step>
-
-<step name="cleanup_artifacts">
-
-Delete remaining raw artifacts from phase directories. Knowledge files are already current from phase-level consolidation in execute-phase — no consolidation or learnings extraction needed.
+Run the stats script to get readiness status and git statistics:
 
 ```bash
-~/.claude/mindsystem/scripts/cleanup-phase-artifacts.sh $PHASE_START $PHASE_END
+~/.claude/mindsystem/scripts/gather-milestone-stats.sh $PHASE_START $PHASE_END
 ```
 
-Knowledge files in `.planning/knowledge/` persist (they ARE the milestone's knowledge output).
-
-**Present cleanup summary:**
-
-```
-Raw artifacts cleaned from phase directories
-Knowledge files persist in .planning/knowledge/
-```
-
-Continue to gather_stats step.
-
-</step>
+The script outputs:
+- **Readiness:** Phase/plan counts, completeness, list of incomplete plans
+- **Git Stats:** Commit range, timeline, diff stats
 
-<step name="gather_stats">
+If status is NOT READY, stop and report which plans are incomplete.
 
-Calculate milestone statistics:
+If status is READY, present the combined output:
 
-```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
 ```
+⚡ Auto-approved: Milestone scope verification
 
-Present summary:
-
-```
-Milestone Stats:
-- Phases: [X-Y]
-- Plans: [Z] total
-- Tasks: [N] total (estimated from phase summaries)
-- Files modified: [M]
-- Lines of code: [LOC] [language]
-- Timeline: [Days] days ([Start] → [End])
-- Git range: feat(XX-XX) → feat(YY-YY)
+Milestone: [Name from ROADMAP.md]
+[Script readiness output — phases, plans, completeness]
+[Script git stats — range, timeline, changes]
 ```
 
+Proceed directly to extract_accomplishments step.
+
 </step>
 
 <step name="extract_accomplishments">
@@ -378,52 +303,6 @@ Initial user testing showed demand for shape tools.
 
 </step>
 
-<step name="reorganize_roadmap">
-
-Update `.planning/ROADMAP.md` to group completed milestone phases.
-
-Add milestone headers and collapse completed work:
-
-```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">
 
 Extract completed milestone details and create archive file.
@@ -478,7 +357,7 @@ Extract completed milestone details and create archive file.
    ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
-**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.).
+**Note:** Phase directories are moved to `milestones/v[X.Y]/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
 
 </step>
 
@@ -545,55 +424,43 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 </step>
 
-<step name="archive_audit">
+<step name="archive_milestone_files">
 
-Move the milestone audit file to the archive (if it exists):
+Archive optional milestone files (audit, context, research) to the milestone directory:
 
 ```bash
-# Move audit to milestone folder (if exists)
-[ -f .planning/v[X.Y]-MILESTONE-AUDIT.md ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/v[X.Y]/MILESTONE-AUDIT.md
+~/.claude/mindsystem/scripts/archive-milestone-files.sh v[X.Y]
 ```
 
-Confirm:
-```
-✅ Audit archived to milestones/v[X.Y]/MILESTONE-AUDIT.md
-```
-
-(Skip silently if no audit file exists — audit is optional)
+The script moves whichever files exist and reports what was archived. Files that don't exist are skipped silently.
 
 </step>
 
-<step name="archive_context">
+<step name="archive_and_cleanup_phases">
 
-Archive the milestone context file (if it exists):
+Consolidate phase summaries, delete raw artifacts, and move phase directories to the milestone archive. This runs after all steps that read summaries (extract_accomplishments, evolve_project_full_review) and after archive_milestone creates the milestone directory.
 
 ```bash
-[ -f .planning/MILESTONE-CONTEXT.md ] && mv .planning/MILESTONE-CONTEXT.md .planning/milestones/v[X.Y]/CONTEXT.md
-```
-
-If archived:
-```
-✅ Context archived to milestones/v[X.Y]/CONTEXT.md
+~/.claude/mindsystem/scripts/archive-milestone-phases.sh $PHASE_START $PHASE_END v[X.Y]
 ```
 
-(Skip silently if no context file exists)
-
-</step>
-
-<step name="archive_research">
-
-Archive research files to milestone (if research directory exists):
+Verify archive:
 
 ```bash
-[ -d .planning/research ] && mv .planning/research .planning/milestones/v[X.Y]/research
+ls .planning/milestones/v[X.Y]/PHASE-SUMMARIES.md
+ls .planning/milestones/v[X.Y]/phases/
 ```
 
-If archived:
+Present:
+
 ```
-✅ Research archived to milestones/v[X.Y]/research/
+✅ Phase summaries consolidated to milestones/v[X.Y]/PHASE-SUMMARIES.md
+✅ Raw artifacts deleted from phase directories
+✅ Phase directories moved to milestones/v[X.Y]/phases/
+✅ .planning/phases/ clean for next milestone
 ```
 
-(Skip silently if no research directory exists)
+Knowledge files in `.planning/knowledge/` persist (they ARE the milestone's knowledge output).
 
 </step>
 
@@ -686,12 +553,15 @@ chore: complete v[X.Y] milestone
 Archived to milestones/v[X.Y]/:
 - ROADMAP.md
 - REQUIREMENTS.md
+- PHASE-SUMMARIES.md (consolidated from phase directories)
+- phases/ (phase directories moved from .planning/phases/)
 - MILESTONE-AUDIT.md (if audit was run)
 - CONTEXT.md (if milestone context existed)
 - research/ (if research existed)
 
 Cleaned:
-- Raw phase artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- Raw phase artifacts deleted (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
+- Phase directories moved to milestone archive
 - Knowledge files persist in .planning/knowledge/
 
 Deleted (fresh for next milestone):
@@ -752,62 +622,17 @@ Tag: v[X.Y]
 
 </process>
 
-<milestone_naming>
-
-**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
-
-Keep names short (1-2 words describing the focus).
-
-</milestone_naming>
-
-<what_qualifies>
-
-**Create milestones for:**
-- Initial release (v1.0)
-- 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)
-
-If uncertain, ask: "Is this deployed/usable/shipped in some form?"
-If yes → milestone. If no → keep working.
-
-</what_qualifies>
-
 <success_criteria>
 
-Milestone completion is successful when:
+Milestone completion is successful when (ordered by skip risk):
 
-- [ ] Raw artifacts cleaned from phase directories (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION, EXECUTION-ORDER)
-- [ ] Knowledge files persist in .planning/knowledge/
-- [ ] MILESTONES.md entry created with stats and accomplishments
-- [ ] PROJECT.md full evolution review completed
+- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, Requirements, Key Decisions, Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
-- [ ] ROADMAP.md reorganized with milestone grouping
-- [ ] Milestone directory created (milestones/v[X.Y]/)
+- [ ] MILESTONES.md entry created with stats and accomplishments
 - [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
 - [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
-- [ ] Research archived to milestone (milestones/v[X.Y]/research/) if .planning/research/ existed
 - [ ] 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)
-- [ ] Context archive created if MILESTONE-CONTEXT.md existed
-- [ ] User knows next steps (starting with /ms:new-milestone)
 
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.17.1",
+  "version": "3.18.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/archive-milestone-files.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+#
+# archive-milestone-files.sh
+# Moves optional milestone files (audit, context, research) to the
+# milestone archive directory. Skips silently if files don't exist.
+#
+# Usage: ./scripts/archive-milestone-files.sh <version>
+# Example: ./scripts/archive-milestone-files.sh v1.0
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ]; then
+  echo "Error: Version argument required"
+  echo "Usage: $0 <version>"
+  exit 1
+fi
+
+VERSION="$1"
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+PLANNING_DIR="$GIT_ROOT/.planning"
+MILESTONE_DIR="$PLANNING_DIR/milestones/$VERSION"
+
+if [ ! -d "$MILESTONE_DIR" ]; then
+  echo "Error: Milestone directory not found at $MILESTONE_DIR"
+  echo "Run archive_milestone step first to create it"
+  exit 1
+fi
+
+# --- Move files ---
+ARCHIVED=0
+
+# Milestone audit
+if [ -f "$PLANNING_DIR/${VERSION}-MILESTONE-AUDIT.md" ]; then
+  mv "$PLANNING_DIR/${VERSION}-MILESTONE-AUDIT.md" "$MILESTONE_DIR/MILESTONE-AUDIT.md"
+  echo "Archived: ${VERSION}-MILESTONE-AUDIT.md → MILESTONE-AUDIT.md"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+# Milestone context
+if [ -f "$PLANNING_DIR/MILESTONE-CONTEXT.md" ]; then
+  mv "$PLANNING_DIR/MILESTONE-CONTEXT.md" "$MILESTONE_DIR/CONTEXT.md"
+  echo "Archived: MILESTONE-CONTEXT.md → CONTEXT.md"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+# Research directory
+if [ -d "$PLANNING_DIR/research" ]; then
+  mv "$PLANNING_DIR/research" "$MILESTONE_DIR/research"
+  echo "Archived: research/ → research/"
+  ARCHIVED=$((ARCHIVED + 1))
+fi
+
+if [ "$ARCHIVED" -eq 0 ]; then
+  echo "No optional files to archive (audit, context, research all absent)"
+else
+  echo ""
+  echo "Archived $ARCHIVED item(s) to milestones/$VERSION/"
+fi
+
+exit 0

package/scripts/archive-milestone-phases.sh

@@ -0,0 +1,138 @@
+#!/bin/bash
+#
+# archive-milestone-phases.sh
+# Consolidates phase summaries, deletes raw artifacts, and moves phase
+# directories to the milestone archive.
+#
+# Usage: ./scripts/archive-milestone-phases.sh <start_phase> <end_phase> <version>
+# Example: ./scripts/archive-milestone-phases.sh 1 6 v1.0
+
+set -e
+
+# --- Validation ---
+if [ -z "$1" ] || [ -z "$2" ] || [ -z "$3" ]; then
+  echo "Error: Three arguments required"
+  echo "Usage: $0 <start_phase> <end_phase> <version>"
+  exit 1
+fi
+
+START="$1"
+END="$2"
+VERSION="$3"
+
+if ! [[ "$START" =~ ^[0-9]+$ ]] || ! [[ "$END" =~ ^[0-9]+$ ]]; then
+  echo "Error: start_phase and end_phase must be numeric"
+  echo "Usage: $0 <start_phase> <end_phase> <version>"
+  exit 1
+fi
+
+if [ "$START" -gt "$END" ]; then
+  echo "Error: Start phase ($START) cannot exceed end phase ($END)"
+  exit 1
+fi
+
+# --- Find .planning from git root ---
+GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$GIT_ROOT" ]; then
+  echo "Error: Not in a git repository"
+  exit 1
+fi
+
+PHASES_DIR="$GIT_ROOT/.planning/phases"
+if [ ! -d "$PHASES_DIR" ]; then
+  echo "Error: Phases directory not found at $PHASES_DIR"
+  exit 1
+fi
+
+MILESTONE_DIR="$GIT_ROOT/.planning/milestones/$VERSION"
+if [ ! -d "$MILESTONE_DIR" ]; then
+  echo "Error: Milestone directory not found at $MILESTONE_DIR"
+  echo "Run archive_milestone step first to create it"
+  exit 1
+fi
+
+# --- Helper: check if phase number is in range (supports decimals like 02.1) ---
+in_range() {
+  local phase_num="$1"
+  echo "$phase_num" | awk -v s="$START" -v e="$END" '{
+    # Strip leading zeros for comparison
+    val = $1 + 0
+    if (val >= s && val <= e + 0.999) exit 0
+    else exit 1
+  }'
+}
+
+# --- Stage 1: Consolidate summaries ---
+SUMMARIES_FILE="$MILESTONE_DIR/PHASE-SUMMARIES.md"
+SUMMARY_COUNT=0
+
+echo "# Phase Summaries: $VERSION" > "$SUMMARIES_FILE"
+echo "" >> "$SUMMARIES_FILE"
+
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+  phase_name="${dirname#*-}"
+
+  if in_range "$phase_num"; then
+    has_summaries=false
+    for f in "$dir"/*-SUMMARY.md; do
+      [ -f "$f" ] || continue
+      if [ "$has_summaries" = false ]; then
+        echo "## Phase $phase_num: $phase_name" >> "$SUMMARIES_FILE"
+        echo "" >> "$SUMMARIES_FILE"
+        has_summaries=true
+      fi
+      plan_file=$(basename "$f")
+      plan_id="${plan_file%-SUMMARY.md}"
+      echo "### $plan_id" >> "$SUMMARIES_FILE"
+      echo "" >> "$SUMMARIES_FILE"
+      cat "$f" >> "$SUMMARIES_FILE"
+      echo "" >> "$SUMMARIES_FILE"
+      SUMMARY_COUNT=$((SUMMARY_COUNT + 1))
+    done
+  fi
+done
+
+echo "Stage 1: Consolidated $SUMMARY_COUNT summaries to PHASE-SUMMARIES.md"
+
+# --- Stage 2: Delete artifacts ---
+DELETED=0
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+
+  if in_range "$phase_num"; then
+    for f in "$dir"/*-CONTEXT.md "$dir"/*-DESIGN.md "$dir"/*-RESEARCH.md \
+             "$dir"/*-SUMMARY.md "$dir"/*-UAT.md "$dir"/*-VERIFICATION.md \
+             "$dir"/*-EXECUTION-ORDER.md; do
+      if [ -f "$f" ]; then
+        rm -f "$f"
+        DELETED=$((DELETED + 1))
+      fi
+    done
+  fi
+done
+
+echo "Stage 2: Deleted $DELETED artifact files"
+
+# --- Stage 3: Move phase directories ---
+mkdir -p "$MILESTONE_DIR/phases"
+MOVED=0
+for dir in "$PHASES_DIR"/*/; do
+  [ -d "$dir" ] || continue
+  dirname=$(basename "$dir")
+  phase_num="${dirname%%-*}"
+
+  if in_range "$phase_num"; then
+    mv "$dir" "$MILESTONE_DIR/phases/$dirname"
+    MOVED=$((MOVED + 1))
+  fi
+done
+
+echo "Stage 3: Moved $MOVED phase directories to milestones/$VERSION/phases/"
+echo ""
+echo "Archive complete: $SUMMARY_COUNT summaries, $DELETED artifacts deleted, $MOVED dirs moved"
+exit 0