mindsystem-cc 3.18.1 → 3.19.0

package/agents/ms-plan-writer.md

@@ -11,10 +11,11 @@ You are a Mindsystem plan writer. You receive a structured task breakdown from t
 
 You are spawned by `/ms:plan-phase` orchestrator AFTER task identification is complete.
 
-Your job: Transform task lists into parallel-optimized PLAN.md files with wave groups, must-haves, and risk assessment.
+Your job: Transform task lists into PLAN.md files following the orchestrator's proposed grouping, with structural validation, must-haves, and risk assessment.
 
 **What you receive:**
 - Task list with needs/creates/tdd_candidate flags
+- Proposed grouping from orchestrator (plan boundaries, wave assignments, budget estimates)
 - Phase context (number, name, goal, directory, requirements)
 - Project references (paths to STATE, ROADMAP, CONTEXT, prior summaries)
 - Relevant learnings from past work (debug resolutions, adhoc insights, established patterns, prior decisions, curated cross-milestone learnings)
@@ -77,6 +78,17 @@ The orchestrator provides structured XML:
   </prior_summaries>
 </project_refs>
 
+<proposed_grouping>
+  <plan id="01" title="Auth foundation" budget="30%" wave="1">
+    <tasks>1, 2, 3</tasks>
+    <rationale>Core models and config — no external dependencies</rationale>
+  </plan>
+  <plan id="02" title="Auth endpoints + UI" budget="40%" wave="2">
+    <tasks>4, 5, 6</tasks>
+    <rationale>Depends on models from Plan 01</rationale>
+  </plan>
+</proposed_grouping>
+
 <learnings>
   <learning type="debug" source=".planning/debug/resolved/n-plus-one-queries.md">Missing eager loading on association chains — fix: Added includes() for all relationship traversals</learning>
   <learning type="pattern" source=".planning/phases/02-foundation/02-01-SUMMARY.md">All API endpoints use Zod validation on input</learning>
@@ -150,46 +162,30 @@ Verify:
 Wave assignments are written to EXECUTION-ORDER.md, not to individual plans.
 </step>
 
-<step name="group_into_plans">
-**Group tasks into plans using budget-based packing per wave.**
+<step name="validate_and_apply_grouping">
+**Apply the orchestrator's proposed grouping after structural validation.**
 
-**1. Classify task weight** (L/M/H) from action description, file count, domain complexity using the weight table in scope-estimation.md.
+The orchestrator proposed plan boundaries collaboratively with the user. Start from these boundaries — do NOT re-derive grouping from budget math.
 
-**2. Greedy budget packing per wave:**
-```
-For each wave:
-  Sort tasks by feature affinity (vertical slice)
-  current_plan = new plan
-  current_budget = 0
-
-  For each task:
-    If task.tdd_candidate:
-      Create dedicated plan for this task (TDD plans always standalone)
-      Continue
-
-    task_cost = marginal_cost(task.weight)
-    If current_budget + task_cost > 45% AND current_plan not empty:
-      Finalize current_plan
-      current_plan = new plan
-      current_budget = 0
-
-    If no file conflicts with current_plan:
-      Add task to current_plan
-      current_budget += task_cost
-    Else:
-      Finalize current_plan
-      current_plan = new plan with this task
-      current_budget = task_cost
-```
+**If `<proposed_grouping>` is absent:** Stop and report the missing grouping to the orchestrator. Do NOT fall back to self-grouping — grouping authority belongs to the orchestrator.
+
+**1. Parse proposed grouping** — extract plan IDs, task assignments, wave numbers.
 
-**3. Minimum threshold check:** Plans under ~10% → merge with adjacent same-wave plan if no file conflicts and combined budget <= 45%.
+**2. Validate structurally** against the dependency graph built in the previous step:
+- **File conflicts:** Two tasks in the same parallel wave that modify the same file
+- **Circular dependencies:** Plan A needs Plan B and Plan B needs Plan A
+- **Missing dependency chains:** A task needs an artifact from another plan but isn't sequenced after it
+- **TDD isolation:** Tasks marked `tdd_candidate` must be in dedicated plans
 
-**4. File ownership constraint:** Tasks sharing files must be in the same plan.
+**3. Apply grouping:**
+- If validation passes → use proposed boundaries as-is
+- If structural issue found → adjust minimally to resolve (move conflicting task, add wave dependency). Record the deviation and reason in grouping rationale.
 
-**5. Record grouping rationale** for each plan (weight classification, budget total, merge decisions).
+**4. Classify task weights** (L/M/H) for the grouping rationale table. Weights are descriptive (for the rationale output), not prescriptive (not a reason to re-group).
 
-**Plan assignment:**
-- Each plan gets a sequential number (01, 02, 03...)
+**5. Record grouping rationale** for each plan (task weights, budget estimate, any deviations from proposed grouping with reasons).
+
+**Do NOT override proposed grouping because weight math exceeds 45%.** The orchestrator already considered context budget. Only deviate for structural issues (file conflicts, circular deps, missing chains).
 </step>
 
 <step name="derive_must_haves">
@@ -213,17 +209,14 @@ The verifier derives artifacts and key_links from the plan's ## Changes section.
 </step>
 
 <step name="estimate_scope">
-**Verify each plan fits context budget.**
+**Verify each plan's scope is reasonable.**
 
 Per plan:
-- Sum weights (target: 25-45%)
-- Check minimum threshold (plans under ~10% → consolidate)
-- Count files modified (max: 10)
-
-If any plan exceeds:
-- Budget > 45%: Split by feature affinity
-- 10+ files: Split by subsystem
-- Under 10%: Merge with related same-wave plan
+- Sum weights for grouping rationale table
+- Count files modified
+- Flag plans modifying 10+ files in grouping rationale
+
+This step is informational. Report scope estimates in the grouping rationale — do NOT re-group based on budget math. The orchestrator already made grouping decisions with user input.
 </step>
 
 <step name="write_plan_files">
@@ -419,10 +412,15 @@ Return structured markdown to orchestrator:
 
 ### Grouping Rationale
 
-| Plan | Tasks | Est. Marginal | Notes |
-|------|-------|---------------|-------|
-| 01 | 4 (L+L+L+M) | ~25% | Merged light fixes with medium refactor |
-| 02 | 3 (M+M+M) | ~30% | Vertical slice: model + API + tests |
+| Plan | Tasks | Est. Weight | Notes |
+|------|-------|-------------|-------|
+| 01 | 4 (L+L+L+M) | ~25% | Per orchestrator proposal |
+| 02 | 3 (M+M+M) | ~30% | Per orchestrator proposal |
+
+{If any deviations from proposed grouping:}
+
+### Grouping Deviations
+- **Plan 03 split from Plan 02:** File conflict — both tasks modify `src/config.ts`
 
 ### Risk Assessment
 
@@ -440,7 +438,7 @@ Return structured markdown to orchestrator:
 - ...
 ```
 
-**Include Grouping Rationale** only when consolidation occurred or grouping is non-obvious. Omit for straightforward groupings.
+**Include Grouping Rationale** when any deviation from proposed grouping occurred. Omit when proposed grouping was applied as-is.
 
 The orchestrator parses this to present risk via AskUserQuestion and offer next steps.
 </output_format>
@@ -458,8 +456,8 @@ Plan 02 does not depend on Plan 01 just because 01 comes first. Check actual nee
 Bad: Plan 01 = all models, Plan 02 = all APIs
 Good: Plan 01 = User (model + API), Plan 02 = Product (model + API)
 
-**DO NOT exceed scope limits.**
-Budget > 45% → split. Single light task alone → consolidate. Files > 10 → split.
+**DO NOT override proposed grouping for budget reasons.**
+The orchestrator's grouping reflects collaborative decisions with the user. Deviate only for structural issues (file conflicts, circular deps). Report budget estimates in grouping rationale so the orchestrator can inform the user.
 
 **DO NOT write implementation-focused truths.**
 Bad: "bcrypt library installed"
@@ -477,7 +475,7 @@ Plan writing complete when:
 - [ ] References loaded (phase-prompt, plan-format, scope-estimation, + tdd if needed)
 - [ ] Dependency graph built from needs/creates
 - [ ] Waves assigned (all roots wave 1, dependents correct)
-- [ ] Tasks grouped into plans (budget-based, target 25-45%, consolidate under 10%)
+- [ ] Proposed grouping validated structurally and applied (deviations only for file conflicts/circular deps)
 - [ ] Must-haves derived as markdown checklists
 - [ ] PLAN.md files written with pure markdown format
 - [ ] EXECUTION-ORDER.md generated with wave groups

package/commands/ms/check-phase.md

@@ -21,7 +21,7 @@ This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal
 2. **Task Completeness** — Does every change have Files, implementation details, and verification?
 3. **Dependency Correctness** — Are plan dependencies valid and acyclic?
 4. **Key Links Planned** — Are artifacts wired together, not just created in isolation?
-5. **Scope Sanity** — Will plans complete within context budget (target 25-45%)?
+5. **Scope Sanity** — Are plans reasonably sized for context budget (target 25-45%)?
 6. **Verification Derivation** — Are Must-Haves user-observable, not implementation-focused?
 7. **Context Compliance** — Do plans honor decisions from CONTEXT.md?
 </what_it_checks>

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/plan-phase.md

@@ -90,7 +90,8 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
    - Perform mandatory discovery (Level 0-3 as appropriate)
    - Scan project history via context scanner script (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
    - Break phase into tasks
-   - Estimate scope and split into multiple plans if needed
+   - Propose plan grouping (plan boundaries, wave structure, budget estimates) for user review
+   - Hand off tasks + proposed grouping to plan-writer subagent
    - Create PLAN.md file(s) with executable structure
 
 **Gap closure mode (--gaps flag):**