mindsystem-cc 3.18.1 → 3.20.0

package/commands/ms/doctor.md

@@ -8,19 +8,19 @@ allowed-tools:
   - Bash
   - Glob
   - Grep
+  - Task
   - AskUserQuestion
 ---
 
 <objective>
-Run health checks on project configuration. Detect and fix configuration issues.
-
-V1 check: subsystem vocabulary setup and validation. Ensures `.planning/config.json` has a canonical `subsystems` array and all artifacts use values from it.
+Run comprehensive health checks on project configuration. Detect and fix structural drift across 6 categories: subsystem vocabulary, milestone directory structure, phase archival, knowledge files, phase summaries, and PLAN cleanup.
 
 Idempotent — safe to run repeatedly.
 </objective>
 
 <context>
 @.planning/config.json
+@.planning/MILESTONES.md
 </context>
 
 <process>
@@ -64,55 +64,98 @@ Write to `.planning/config.json`. Log: "Created config.json with empty subsystem
 Proceed to next step.
 </step>
 
-<step name="read_current_subsystems">
+<step name="run_scan">
+Run the diagnostic scan:
+
 ```bash
-jq -r '.subsystems // [] | length' .planning/config.json
+~/.claude/mindsystem/scripts/doctor-scan.sh
 ```
 
-- If 0 → **State A**: no subsystems configured. Go to `audit_existing_usage`.
-- If >0 → **State B**: subsystems exist. Go to `validate_vocabulary`.
+Capture the full output. Parse each check's Status (PASS/FAIL/SKIP) and detail lines.
+</step>
+
+<step name="present_results">
+Display results as a markdown table:
+
+```
+## Doctor Report
+
+| Check                    | Result | Details                          |
+|--------------------------|--------|----------------------------------|
+| Subsystem vocabulary     | PASS   | 9 subsystems, all artifacts OK   |
+| Milestone directories    | FAIL   | 2 flat files need restructuring  |
+| Phase archival           | FAIL   | 8 orphaned phase directories     |
+| Knowledge files          | FAIL   | Directory missing                |
+| Phase summaries          | FAIL   | 2 milestones missing summaries   |
+| PLAN cleanup             | FAIL   | 9 leftover PLAN.md files         |
+```
+
+Populate Result and Details from scan output. Use concise detail summaries.
+
+If all PASS → go to `report`.
+If any FAIL → go to `confirm_action`.
 </step>
 
-<step name="audit_existing_usage">
-**State A only.** Scan all artifact types for existing free-form `subsystem:` values.
+<step name="confirm_action">
+Use AskUserQuestion:
+- header: "Fix issues"
+- question: "How would you like to handle the failed checks?"
+- options:
+  - "Fix all" — apply all fixes in dependency order
+  - "Review each" — present each failed check individually for decision
+  - "Skip" — leave as-is, report only
+
+If "Skip" → go to `report`.
+
+If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
+
+Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
+</step>
+
+<step name="fix_subsystems">
+**Only if Subsystem Vocabulary failed.**
+
+If subsystems array is empty (State A):
+
+1. Scan all artifacts for existing values:
 
 ```bash
 ~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh --values-only
 ```
 
-Collect all unique values found. Note count of artifacts scanned and values found.
-</step>
+2. Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
 
-<step name="derive_and_confirm">
-**State A only.** 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
 
-Derive 5-12 canonical subsystem identifiers from:
+   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)
 
-1. Unique values found in `audit_existing_usage`
-2. Project domain from PROJECT.md
-3. Phase structure from ROADMAP.md
+4. Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
 
-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)
+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
 
-Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
+6. After confirmation: update `config.json` (subsystems as first field), standardize existing artifact `subsystem:` fields using Edit tool.
 
-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
+If subsystems exist but artifacts have mismatches (State B):
 
-After confirmation:
+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.
 
-1. Update `config.json` — set `subsystems` array as first field
-2. If existing artifacts had free-form values, standardize each `subsystem:` field to the canonical value using the Edit tool (only modify the `subsystem:` line, never body content)
-3. Commit all changes:
+Commit:
 
 ```bash
 git add .planning/config.json
@@ -126,99 +169,184 @@ git add .planning/todos/done/*.md 2>/dev/null
 
 ```bash
 git commit -m "$(cat <<'EOF'
-chore: initialize subsystem vocabulary
+chore(doctor): fix subsystem vocabulary
 
-Added subsystems array to config.json and standardized existing artifact values.
+Standardized subsystem configuration and artifact values.
 EOF
 )"
 ```
 </step>
 
-<step name="validate_vocabulary">
-**State B only.** Read canonical list from config.json:
+<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 versioned 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`
+
+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_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/{version}`
+3. Run the archive script:
+
+```bash
+~/.claude/mindsystem/scripts/archive-milestone-phases.sh <start> <end> <version>
+```
+
+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
-jq -r '.subsystems[]' .planning/config.json
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
 ```
 
-Scan all artifacts for `subsystem:` values. Extract from YAML frontmatter:
+Commit:
 
 ```bash
-~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh
+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>
 
-Classify each artifact's `subsystem:` value:
-- **OK** — value is in canonical list
-- **MISMATCH** — value exists but not in canonical list
-- **MISSING** — no `subsystem:` field found
+<step name="fix_plan_cleanup">
+**Only if PLAN Cleanup failed AND fix_phase_archival did not already handle it.**
 
-Display results grouped by status. If all OK:
+Delete leftover PLAN files in completed phase directories:
 
+```bash
+find .planning/milestones/*/phases/ -name "*-PLAN.md" -delete 2>/dev/null
 ```
-## Subsystem Vocabulary
 
-PASS — all N artifacts use canonical subsystem values.
+For any leftover PLANs in `phases/` belonging to completed milestones (identified by the scan), delete those too.
+
+Commit:
+
+```bash
+git add .planning/
 ```
 
-Go to `report`.
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): clean up leftover PLAN files
 
-If MISMATCH or MISSING found, use AskUserQuestion:
-- header: "Fix issues"
-- question: "Found N issues (X mismatches, Y missing). How to proceed?"
-- options:
-  - "Fix all" — apply best-match canonical values to all issues
-  - "Review each" — present each issue individually for decision
-  - "Skip" — leave as-is
+Removed PLAN files from completed phase directories.
+EOF
+)"
+```
+</step>
 
-For fixes:
-- MISMATCH: propose closest canonical value (fuzzy match on prefix/synonym)
-- MISSING: propose based on artifact content/path context
+<step name="fix_knowledge">
+**Only if Knowledge Files failed.**
 
-Apply fixes using Edit tool. Commit:
+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
-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
+ls .planning/knowledge/*.md
+```
+
+Commit:
+
+```bash
+git add .planning/knowledge/
 ```
 
 ```bash
 git commit -m "$(cat <<'EOF'
-chore: fix subsystem vocabulary mismatches
+chore(doctor): generate knowledge files
 
-Standardized artifact subsystem values to canonical vocabulary.
+Created per-subsystem knowledge files from phase summaries.
 EOF
 )"
 ```
 </step>
 
+<step name="verify">
+Re-run the diagnostic scan:
+
+```bash
+~/.claude/mindsystem/scripts/doctor-scan.sh
+```
+
+All checks should now PASS. If any still fail, report which checks remain and why.
+</step>
+
 <step name="report">
-Final summary:
+Final summary table:
 
 ```
 ## Doctor Report
 
-| Check                  | Result      | Details                    |
-|------------------------|-------------|----------------------------|
-| Subsystem vocabulary   | PASS / INIT | N artifacts, M subsystems  |
+| Check                    | Result | Details                          |
+|--------------------------|--------|----------------------------------|
+| Subsystem vocabulary     | PASS   | ...                              |
+| Milestone directories    | PASS   | ...                              |
+| Phase archival           | PASS   | ...                              |
+| Knowledge files          | PASS   | ...                              |
+| Phase summaries          | PASS   | ...                              |
+| PLAN cleanup             | PASS   | ...                              |
 
 All checks passed.
 ```
 
-- **PASS**: subsystems were already configured and all artifacts validated
-- **INIT**: subsystems were initialized during this run
-- Include artifact count (how many scanned) and subsystem count
+Include counts: checks total, passed, fixed during this run.
 </step>
 
 </process>
 
 <success_criteria>
-- [ ] State A: config.json updated, existing artifacts standardized to canonical values, changes committed
-- [ ] State B issues: offers fix/review/skip, applies fixes, commits
-- [ ] Final report displayed with check name, result, and artifact/subsystem counts
-- [ ] State A: derives canonical list from audit + project context, confirms with user before applying
-- [ ] State B: all artifacts scanned and classified; reports PASS if all OK
+- [ ] Each fix group committed atomically
+- [ ] Re-scan verifies all checks pass after fixes
+- [ ] User confirms fix strategy before changes (Fix all / Review each / Skip)
+- [ ] Fixes applied in dependency order: subsystems → dirs → archival → cleanup → knowledge
+- [ ] Results displayed as markdown table before any action
+- [ ] All 6 categories reported with PASS/FAIL/SKIP
+- [ ] Clean project reports all PASS with no fix prompts
 </success_criteria>

package/commands/ms/execute-phase.md

@@ -69,21 +69,21 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Collect summaries from all plans
    - Report phase completion status
 
-6. **Code review (optional)**
-   - Read `code_review.phase` from config.json (default: `ms-code-simplifier`)
-   - If `"skip"`: proceed to step 7
-   - Spawn code review agent with phase file scope
-   - If changes made: commit as `refactor({phase}): code review improvements`
-
-7. **Verify phase goal**
+6. **Verify phase goal**
    - Spawn `ms-verifier` subagent with phase directory and goal
    - Verifier checks Must-Haves against actual codebase (not SUMMARY claims)
    - Creates VERIFICATION.md with detailed report
    - Route by status:
-     - `passed` → continue to step 8
+     - `passed` → continue to step 7
      - `human_needed` → present items, get approval or feedback
      - `gaps_found` → present gaps, offer `/ms:plan-phase {X} --gaps`
 
+7. **Code review (optional)**
+   - Read `code_review.phase` from config.json (default: `ms-code-simplifier`)
+   - If `"skip"`: proceed to step 8
+   - Spawn code review agent with phase file scope
+   - If changes made: commit as `refactor({phase}): code review improvements`
+
 8. **Generate phase patch**
    - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`

package/commands/ms/help.md

@@ -377,12 +377,12 @@ Usage: `/ms:adhoc Fix auth token not refreshing on 401`
 ### Utility Commands
 
 **`/ms:doctor`**
-Health check and fix project configuration.
+Health check and fix project configuration — subsystems, milestone structure, knowledge files.
 
-- Use when: subsystems are missing, artifacts have inconsistent vocabulary, or periodic health check
-- V1: subsystem vocabulary setup and validation
-- If subsystems missing: derives from project context and guides through setup
-- If subsystems present: validates all artifacts use canonical values
+- Use when: project has structural drift, missing config, or periodic health check
+- Runs 6 checks: subsystem vocabulary, milestone directories, phase archival, knowledge files, phase summaries, PLAN cleanup
+- Presents results table, then offers to fix all issues in dependency order
+- Each fix group gets its own atomic commit
 - Idempotent — safe to run repeatedly
 
 Usage: `/ms:doctor`

package/commands/ms/insert-phase.md

@@ -133,13 +133,36 @@ Confirm: "Created directory: $phase_dir"
 Insert the new phase entry into the roadmap:
 
 1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
-2. Insert new phase heading with (INSERTED) marker:
+
+2. Before writing the phase entry, analyze the description to determine pre-work flags:
+
+   **Discuss**: Likely when description mentions user-facing features, UX decisions,
+   experiential qualities, or novel features. Unlikely for backend/infra, bug fixes,
+   technical debt, or clear-cut work.
+
+   **Design**: Likely when description involves UI work, visual elements, forms,
+   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
+   or established UI patterns.
+
+   **Research**: Likely when description mentions external APIs/services, new
+   libraries/frameworks, or unclear technical approach. Unlikely for established
+   internal patterns or well-documented conventions.
+
+   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+
+3. Insert new phase heading with (INSERTED) marker and pre-work flags:
 
    ```
    ### Phase {decimal_phase}: {Description} (INSERTED)
 
    **Goal:** [Urgent work - to be planned]
    **Depends on:** Phase {after_phase}
+   **Discuss**: {Likely (reason) | Unlikely (reason)}
+   **Discuss topics**: {topics} ← only if Likely
+   **Design**: {Likely (reason) | Unlikely (reason)}
+   **Design focus**: {focus} ← only if Likely
+   **Research**: {Likely (reason) | Unlikely (reason)}
+   **Research topics**: {topics} ← only if Likely
    **Plans:** 0 plans
 
    Plans:
@@ -149,7 +172,7 @@ Insert the new phase entry into the roadmap:
    [To be added during planning]
    ```
 
-3. Write updated roadmap back to file
+4. Write updated roadmap back to file
 
 The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
 
@@ -183,24 +206,13 @@ Phase {decimal_phase} inserted after Phase {after_phase}:
 Roadmap updated: {roadmap-path}
 Project state updated: .planning/STATE.md
 
----
-
-## ▶ Next Up
-
-**Phase {decimal_phase}: {description}** — urgent insertion
-
-`/ms:plan-phase {decimal_phase}`
-
-<sub>`/clear` first → fresh context window</sub>
+```
 
----
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
+to present "Next Up" with pre-work context for Phase {decimal_phase}.
 
-**Also available:**
+After the "Next Up" section, add:
 - Review insertion impact: Check if Phase {next_integer} dependencies still make sense
-- Review roadmap
-
----
-```
 </step>
 
 <step name="update_last_command">

package/commands/ms/new-milestone.md

@@ -88,7 +88,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
    - Settled decisions and patterns from knowledge files
    - Untested assumptions from previous audit
    - Unaddressed requirements from previous milestones
-   - Strategic features inferred from PROJECT.md's problem/audience/USP
+   - Strategic features inferred from PROJECT.md: Who It's For, Core Problem, How It's Different
    - Pending todos from STATE.md
 
    If no meaningful artifacts exist (first milestone after v1.0), base suggestions purely on PROJECT.md.
@@ -199,8 +199,8 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
     - [Feature 3]
     ```
 
-    Update Active requirements section with new goals.
     Update "Last updated" footer.
+    Note: Milestone-specific goals live in MILESTONE-CONTEXT.md (step 15), not in PROJECT.md.
 
 15. **Write MILESTONE-CONTEXT.md:**
 
@@ -285,7 +285,6 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 <success_criteria>
 - PROJECT.md updated with Current Milestone section
-- Active requirements reflect new milestone goals
 - MILESTONE-CONTEXT.md created with vision, features, scope, priorities
 - STATE.md reset for new milestone
 - Git commit made