mindsystem-cc 3.20.0 → 3.21.0

package/mindsystem/workflows/doctor-fixes.md

@@ -0,0 +1,273 @@
+<purpose>
+Apply fixes for doctor health check failures. Each step targets one check category,
+runs only if that check failed, and commits atomically.
+</purpose>
+
+<process>
+
+<step name="fix_subsystems">
+**Only if Subsystem Vocabulary failed.**
+
+If subsystems array is empty (State A):
+
+1. Scan all artifacts for existing values:
+
+```bash
+ms-tools scan-artifact-subsystems --values-only
+```
+
+2. Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
+
+3. Derive 5-12 canonical subsystem identifiers from:
+   - Unique values found in artifacts
+   - Project domain from PROJECT.md
+   - Phase structure from ROADMAP.md
+
+   Rules:
+   - Lowercase, single-word or hyphenated (e.g., "auth", "real-time", "ui")
+   - Merge synonyms into one canonical value (pick shortest/most common)
+   - Cover all existing usage plus obvious gaps
+   - Include infrastructure-level subsystems if relevant (api, database, infra, testing)
+
+4. Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
+
+5. Use AskUserQuestion:
+   - header: "Subsystems"
+   - question: "These subsystems were derived from your project. Look good?"
+   - options:
+     - "Looks good" — accept and apply
+     - "Add/remove some" — iterate on the list
+     - "Start over" — re-derive from scratch
+
+6. After confirmation: update `config.json` (subsystems as first field), standardize existing artifact `subsystem:` fields using Edit tool.
+
+If subsystems exist but artifacts have mismatches (State B):
+
+1. Classify each artifact as OK/MISMATCH/MISSING.
+2. For MISMATCH: propose closest canonical value.
+3. For MISSING: propose based on artifact content/path.
+4. Apply fixes using Edit tool.
+
+Commit:
+
+```bash
+git add .planning/config.json
+git add .planning/phases/*/*-SUMMARY.md 2>/dev/null
+git add .planning/adhoc/*-SUMMARY.md 2>/dev/null
+git add .planning/debug/*.md 2>/dev/null
+git add .planning/debug/resolved/*.md 2>/dev/null
+git add .planning/todos/pending/*.md 2>/dev/null
+git add .planning/todos/done/*.md 2>/dev/null
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): fix subsystem vocabulary
+
+Standardized subsystem configuration and artifact values.
+EOF
+)"
+```
+</step>
+
+<step name="fix_milestone_dirs">
+**Only if Milestone Directory Structure failed.**
+
+For each flat file like `milestones/v0.1-ROADMAP.md`:
+
+1. Extract version prefix (e.g., `v0.1`).
+2. Create directory if it doesn't exist: `mkdir -p .planning/milestones/v0.1`
+3. `git mv` the file, stripping the version prefix from the filename:
+   `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
+
+**Note:** New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
+
+Commit:
+
+```bash
+git add .planning/milestones/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): restructure milestone directories
+
+Moved flat milestone files into versioned directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_milestone_naming">
+**Only if Milestone Naming Convention failed.**
+
+1. **Build mapping** — run `ms-tools scan-milestone-naming`, parse JSON output.
+
+2. **Resolve slugs** — For each versioned dir, match to MILESTONES.md name mapping:
+   - Standard dirs: version matches directly (v0.1 → "MVP" → slug "mvp")
+   - Nested dirs: match sub-directory name to the milestone name in MILESTONES.md (v2.0.0/quests → "Quests Feature" → slug "quests-feature")
+   - Derive short slugs from names (Claude proposes, user confirms)
+
+3. **Present mapping** to user with AskUserQuestion:
+
+   ```
+   | Current Directory       | Milestone Name       | Proposed Slug    |
+   |-------------------------|----------------------|------------------|
+   | v0.1/                   | MVP                  | mvp              |
+   | v0.2/                   | Infrastructure       | infrastructure   |
+   | (active)                | Demo Release         | demo-release     |
+   ```
+
+   Options: "Looks good" / "Edit slugs" / "Skip"
+
+4. **Rename directories:**
+   - Standard: `git mv .planning/milestones/v0.1 .planning/milestones/mvp`
+   - Nested: `git mv .planning/milestones/v2.0.0/quests .planning/milestones/quests-feature` for each sub-dir, then `rmdir .planning/milestones/v2.0.0` to remove empty parent
+
+5. **Update archived milestone files** (inside each renamed dir):
+   - `PHASE-SUMMARIES.md`: `# Phase Summaries: v0.1` → `# Phase Summaries: MVP`
+   - `ROADMAP.md`: `# Milestone v0.1: Name` → `# Milestone: Name`
+   - `REQUIREMENTS.md`: `# Requirements Archive: v0.1 Name` → `# Requirements Archive: Name`
+   - `MILESTONE-AUDIT.md`: YAML `milestone: v0.1` → `milestone: mvp` (use slug)
+   - `CONTEXT.md`: `# Milestone Context: v0.1 Name` → `# Milestone Context: Name`
+
+6. **Update MILESTONES.md:**
+   - Strip version prefix from headers: `## v0.1 MVP (Shipped:...)` → `## MVP (Shipped:...)`
+   - Preserve all other content (git ranges, stats, accomplishments)
+
+7. **Update active .planning files:**
+   - `PROJECT.md`: Replace `— v0.1` with `— MVP` in validated requirements, strip version from `## Current Milestone:` header, update `Shipped v0.2 with...` → `Shipped Infrastructure with...`
+   - `STATE.md`: Replace version refs with names (`v0.3 Demo Release` → `Demo Release`)
+   - `ROADMAP.md`: Strip version from `**Milestone:** v0.3 Demo Release` → `**Milestone:** Demo Release`
+   - `MILESTONE-CONTEXT.md`: Strip version from header
+   - `REQUIREMENTS.md`: Strip version from `**Milestone:**` line. For deferred sections (`### v0.4 — On-Device Hardening`), use AskUserQuestion to confirm replacement names or keep description-only format (`### On-Device Hardening (deferred)`)
+
+8. **Rules:**
+   - Do NOT modify git range references (`**Git range:** feat(01-01) → ...`)
+   - Do NOT modify git commit messages quoted in MILESTONES.md
+   - Preserve shipped dates, stats, phase ranges
+   - Use Edit tool for targeted replacements (not bulk find-replace)
+
+9. **Commit:**
+
+```bash
+git add .planning/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): migrate milestone naming from versions to slugs
+
+Renamed milestone directories from version-based (v0.1/, v2.0.0/) to
+name-based slugs (mvp/, quests-feature/). Updated all planning file references.
+EOF
+)"
+```
+</step>
+
+<step name="fix_phase_archival">
+**Only if Phase Archival failed.**
+
+Parse MILESTONES.md for completed milestones and their phase ranges (`**Phases completed:** X-Y`).
+
+For each completed milestone with orphaned phases in `.planning/phases/`:
+
+1. Determine the version and phase range from MILESTONES.md.
+2. Ensure the milestone directory exists: `mkdir -p .planning/milestones/{slug}`
+3. Run the archive script:
+
+```bash
+ms-tools archive-milestone-phases <start> <end> <slug>
+```
+
+This simultaneously:
+- Consolidates PHASE-SUMMARIES.md (fixes Phase Summaries check)
+- Deletes raw artifacts (CONTEXT, DESIGN, RESEARCH, SUMMARY, UAT, VERIFICATION)
+- Moves phase directories to milestone archive
+
+**If MILESTONES.md doesn't have parseable phase ranges:** Use AskUserQuestion to ask the user for the phase range for each milestone.
+
+After archive completes, clean up leftover PLAN files in archived phases (fixes PLAN Cleanup check):
+
+```bash
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
+```
+
+Commit:
+
+```bash
+git add .planning/phases/ .planning/milestones/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): archive completed milestone phases
+
+Consolidated summaries, deleted raw artifacts, moved phase directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_plan_cleanup">
+**Only if PLAN Cleanup failed AND fix_phase_archival did not already handle it.**
+
+Delete leftover PLAN files in completed phase directories:
+
+```bash
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
+```
+
+For any leftover PLANs in `phases/` belonging to completed milestones (identified by the scan), delete those too.
+
+Commit:
+
+```bash
+git add .planning/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): clean up leftover PLAN files
+
+Removed PLAN files from completed phase directories.
+EOF
+)"
+```
+</step>
+
+<step name="fix_knowledge">
+**Only if Knowledge Files failed.**
+
+Spawn a `general-purpose` subagent (Task tool) to generate knowledge files retroactively. Provide the subagent with:
+
+- Subsystem vocabulary from config.json
+- Instructions to read all PHASE-SUMMARIES.md from `milestones/*/PHASE-SUMMARIES.md` AND any remaining SUMMARY files in `phases/`
+- The knowledge template at `~/.claude/mindsystem/templates/knowledge.md`
+- Instructions to read any existing knowledge files and merge (rewrite semantics — current state, not append)
+- Instructions to create `.planning/knowledge/` directory if missing
+- Instructions to write `.planning/knowledge/{subsystem}.md` for each missing subsystem
+
+After subagent completes, verify files exist:
+
+```bash
+ls .planning/knowledge/*.md
+```
+
+Commit:
+
+```bash
+git add .planning/knowledge/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): generate knowledge files
+
+Created per-subsystem knowledge files from phase summaries.
+EOF
+)"
+```
+</step>
+
+</process>

package/mindsystem/workflows/execute-phase.md

@@ -81,7 +81,7 @@ Skip completed plans. If all complete, report "Phase already executed" and exit.
 Run validation before launching executors:
 
 ```bash
-~/.claude/mindsystem/scripts/validate-execution-order.sh "$PHASE_DIR"
+ms-tools validate-execution-order "$PHASE_DIR"
 ```
 
 If validation fails (exit 1), stop execution and report the mismatch to user.
@@ -201,7 +201,7 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
 
    After reporting wave completion, update STATE.md with progress:
    ```bash
-   ~/.claude/mindsystem/scripts/update-state.sh {completed_count} {total_count}
+   ms-tools update-state {completed_count} {total_count}
    ```
 
 5. **Handle failures:**
@@ -412,7 +412,7 @@ Generate a patch file with all implementation changes from this phase.
 
 **Run the patch generation script:**
 ```bash
-~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}
+ms-tools generate-phase-patch ${PHASE_NUMBER}
 ```
 
 The script will:
@@ -527,6 +527,10 @@ git commit -m "docs: update codebase map after phase {X}"
 <step name="offer_next">
 Present next steps based on milestone status.
 
+**First, surface user actions:**
+
+Read `## User Actions Required` from all `*-SUMMARY.md` files in the phase directory. If any non-empty actions exist, present as `## ⚠ Action Required` block before route-specific content. Skip if all "None".
+
 **If more phases remain:**
 
 Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for the next phase.

package/mindsystem/workflows/execute-plan.md

@@ -298,6 +298,9 @@ completed: YYYY-MM-DD
 ## Issues Encountered
 [Problems during planned work, or "None"]
 
+## User Actions Required
+[Commands the user must run: migrations, package installs, env vars, server restarts. Or "None — no manual steps needed."]
+
 ## Next Step
 [Ready for next plan, or "Phase complete, ready for transition"]
 ```

package/mindsystem/workflows/map-codebase.md

@@ -100,8 +100,8 @@ After writing STACK.md, update config.json code_review fields with the appropria
 1. Read STACK.md to detect primary framework
 2. Map framework to code review agent names:
    - Flutter/Dart:
-     - adhoc: "ms-flutter-simplifier"
-     - phase: "ms-flutter-simplifier"
+     - adhoc: "ms-flutter-code-quality"
+     - phase: "ms-flutter-code-quality"
      - milestone: "ms-flutter-reviewer"
    - All others (React, Next.js, Node, Swift, Kotlin, etc.):
      - adhoc: "ms-code-simplifier"

package/mindsystem/workflows/mockup-generation.md

@@ -106,7 +106,7 @@ Task(prompt=assembled_context, subagent_type="ms-mockup-designer", description="
 After all 3 agents return, run the comparison script to create the comparison page. Do NOT generate comparison HTML manually — use the script:
 
 ```bash
-uv run ~/.claude/mindsystem/scripts/compare_mockups.py "${PHASE_DIR}/mockups"
+ms-compare-mockups "${PHASE_DIR}/mockups"
 open "${PHASE_DIR}/mockups/comparison.html"
 ```
 

package/mindsystem/workflows/plan-phase.md

@@ -277,7 +277,7 @@ PHASE_NAME=$(grep -A2 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null | head
 **2. Run context scanner:**
 
 ```bash
-uv run ~/.claude/mindsystem/scripts/scan-planning-context.py \
+ms-tools scan-planning-context \
   --phase "${PHASE}" \
   --phase-name "${PHASE_NAME}" \
   ${SUBSYSTEM:+--subsystem="${SUBSYSTEM}"}

package/mindsystem/workflows/transition.md

@@ -400,12 +400,12 @@ Exit skill and invoke SlashCommand("/ms:plan-phase [X+1]")
 ```
 Phase {X} marked complete.
 
-🎉 Milestone {version} is 100% complete — all {N} phases finished!
+🎉 Milestone is 100% complete — all {N} phases finished!
 
 ⚡ Auto-continuing: Complete milestone and archive
 ```
 
-Exit skill and invoke SlashCommand("/ms:complete-milestone {version}")
+Exit skill and invoke SlashCommand("/ms:complete-milestone")
 
 </step>
 

package/mindsystem/workflows/verify-work.md

@@ -580,7 +580,7 @@ Use `mocked_files` list from UAT.md frontmatter. Clear the list after reverting.
 
 **2. Generate UAT fixes patch (if fixes were made):**
 ```bash
-~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER} --suffix=uat-fixes
+ms-tools generate-phase-patch ${PHASE_NUMBER} --suffix=uat-fixes
 ```
 Output: `.planning/phases/{phase_dir}/{phase}-uat-fixes.patch`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.20.0",
+  "version": "3.21.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/fixtures/scan-context/.planning/ROADMAP.md

@@ -0,0 +1,16 @@
+# Roadmap
+
+## Phase 02: Infrastructure
+Database setup and core infrastructure.
+
+## Phase 03: Core Models
+Data models and schemas.
+
+## Phase 04: Setup
+Project configuration and tooling.
+
+## Phase 05: Authentication
+User auth with JWT tokens.
+
+## Phase 06: UI
+Frontend components and screens.

package/scripts/fixtures/scan-context/.planning/adhoc/20260220-fix-token-SUMMARY.md

@@ -0,0 +1,12 @@
+---
+subsystem: auth
+learnings:
+  - Token expiry must account for clock skew
+  - Always validate token signature before checking claims
+related_phase: "05-auth"
+tags: [jwt, tokens]
+---
+
+# Fix Token Validation
+
+Fixed edge case where expired tokens passed validation due to clock skew.

package/scripts/fixtures/scan-context/.planning/config.json

@@ -0,0 +1,3 @@
+{
+  "subsystems": ["auth", "database", "api"]
+}

package/scripts/fixtures/scan-context/.planning/debug/resolved/token-bug.md

@@ -0,0 +1,11 @@
+---
+subsystem: auth
+root_cause: Clock skew between servers caused token validation to fail intermittently
+resolution: Added 30-second leeway to token expiry check
+tags: [jwt, timing]
+phase: "05-auth"
+---
+
+# Token Validation Bug
+
+Intermittent auth failures due to clock skew between API servers.

package/scripts/fixtures/scan-context/.planning/knowledge/auth.md

@@ -0,0 +1,11 @@
+# Auth Subsystem Knowledge
+
+## Authentication Flow
+1. User submits credentials to POST /api/auth/login
+2. Server validates with bcrypt
+3. JWT issued as httpOnly cookie
+4. Middleware validates on subsequent requests
+
+## Key Patterns
+- Token rotation on refresh
+- Clock skew leeway of 30 seconds

package/scripts/fixtures/scan-context/.planning/phases/02-infra/02-1-SUMMARY.md

@@ -0,0 +1,20 @@
+---
+phase: "02-infra"
+subsystem: database
+affects: []
+requires: []
+tags: [postgres, migrations]
+tech-stack:
+  added: [postgres]
+  patterns: []
+patterns-established: []
+key-files:
+  created: [db/schema.sql]
+  modified: []
+key-decisions:
+  - Use PostgreSQL for primary store
+---
+
+# Phase 02 Plan 1 Summary
+
+Set up database infrastructure with migrations.

package/scripts/fixtures/scan-context/.planning/phases/04-setup/04-1-SUMMARY.md

@@ -0,0 +1,21 @@
+---
+phase: "04-setup"
+subsystem: api
+affects: []
+requires: []
+tags: [jwt, config]
+tech-stack:
+  added: [dotenv]
+  patterns: [env-config]
+patterns-established:
+  - Config loading pattern
+key-files:
+  created: [src/config.ts]
+  modified: [package.json]
+key-decisions:
+  - Use dotenv for configuration
+---
+
+# Phase 04 Plan 1 Summary
+
+Project setup and configuration with JWT support.

package/scripts/fixtures/scan-context/.planning/phases/05-auth/05-1-SUMMARY.md

@@ -0,0 +1,28 @@
+---
+phase: "05-auth"
+subsystem: auth
+affects: ["06-ui"]
+requires: ["04-setup"]
+tags: [jwt, auth, tokens]
+tech-stack:
+  added: [jose, bcrypt]
+  patterns: [jwt-auth]
+patterns-established:
+  - JWT token rotation
+  - Password hashing with bcrypt
+key-files:
+  created: [src/auth/login.ts, src/auth/middleware.ts]
+  modified: [src/config.ts]
+key-decisions:
+  - JWT with httpOnly cookies
+  - bcrypt for password hashing
+---
+
+# Phase 05 Plan 1 Summary
+
+Authentication system with JWT and bcrypt.
+
+## Next Phase Readiness
+
+- UI phase needs auth context provider
+- Token refresh endpoint not yet implemented

package/scripts/fixtures/scan-context/.planning/todos/done/setup-db.md

@@ -0,0 +1,10 @@
+---
+title: Set up database migrations
+subsystem: database
+priority: high
+phase_origin: "02-infra"
+---
+
+# Set Up Database Migrations
+
+Configure migration tooling for PostgreSQL.

package/scripts/fixtures/scan-context/.planning/todos/pending/add-logout.md

@@ -0,0 +1,10 @@
+---
+title: Add logout endpoint
+subsystem: auth
+priority: medium
+phase_origin: "05-auth"
+---
+
+# Add Logout Endpoint
+
+Implement POST /api/auth/logout to invalidate tokens.