mindsystem-cc 3.14.0 → 3.16.0

package/commands/ms/discuss-phase.md

@@ -13,9 +13,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase
 </objective>
 
 <execution_context>
-@~/.claude/mindsystem/references/principles.md
 @~/.claude/mindsystem/workflows/discuss-phase.md
-@~/.claude/mindsystem/templates/context.md
 </execution_context>
 
 <context>
@@ -38,6 +36,7 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
 1. Validate phase number argument (error if missing or invalid)
 2. Check if phase exists in roadmap
 3. Check if CONTEXT.md already exists (offer to update if yes)
+3.5. **Load prior knowledge** — determine relevant subsystem(s) by matching ROADMAP.md phase description against subsystem names in config.json. Load matching `.planning/knowledge/{subsystem}.md` files. If knowledge exists, present brief "What we know so far" summary before questioning.
 4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
    - Present phase from roadmap
    - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
@@ -50,13 +49,6 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Format: `Last Command: ms:discuss-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
 
 **CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
-
-User is the visionary, you are the builder:
-- Ask about vision, feel, essential outcomes
-- DON'T ask about technical risks (you figure those out)
-- DON'T ask about codebase patterns (you read the code)
-- DON'T ask about success metrics (too corporate)
-- DON'T interrogate about constraints they didn't mention
 </process>
 
 <success_criteria>

package/commands/ms/doctor.md

@@ -0,0 +1,224 @@
+---
+name: ms:doctor
+description: Health check and fix project configuration
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - 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.
+
+Idempotent — safe to run repeatedly.
+</objective>
+
+<context>
+@.planning/config.json
+</context>
+
+<process>
+
+<step name="check_planning_dir">
+```bash
+[ -d .planning ] && echo "EXISTS" || echo "MISSING"
+```
+
+If MISSING:
+
+```
+No .planning/ directory found.
+
+Run `/ms:new-project` to initialize this project.
+```
+
+Exit.
+</step>
+
+<step name="ensure_config">
+```bash
+[ -f .planning/config.json ] && echo "EXISTS" || echo "MISSING"
+```
+
+If MISSING, create from template structure:
+
+```json
+{
+  "subsystems": [],
+  "code_review": {
+    "adhoc": null,
+    "phase": null,
+    "milestone": null
+  }
+}
+```
+
+Write to `.planning/config.json`. Log: "Created config.json with empty subsystems."
+
+Proceed to next step.
+</step>
+
+<step name="read_current_subsystems">
+```bash
+jq -r '.subsystems // [] | length' .planning/config.json
+```
+
+- If 0 → **State A**: no subsystems configured. Go to `audit_existing_usage`.
+- If >0 → **State B**: subsystems exist. Go to `validate_vocabulary`.
+</step>
+
+<step name="audit_existing_usage">
+**State A only.** Scan all artifact types for existing free-form `subsystem:` 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>
+
+<step name="derive_and_confirm">
+**State A only.** Read `.planning/PROJECT.md` and `.planning/ROADMAP.md`.
+
+Derive 5-12 canonical subsystem identifiers from:
+
+1. Unique values found in `audit_existing_usage`
+2. Project domain from PROJECT.md
+3. 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)
+
+Present the proposed list with merge mappings (e.g., "authentication" -> "auth").
+
+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
+
+After confirmation:
+
+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:
+
+```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: initialize subsystem vocabulary
+
+Added subsystems array to config.json and standardized existing artifact values.
+EOF
+)"
+```
+</step>
+
+<step name="validate_vocabulary">
+**State B only.** Read canonical list from config.json:
+
+```bash
+jq -r '.subsystems[]' .planning/config.json
+```
+
+Scan all artifacts for `subsystem:` values. Extract from YAML frontmatter:
+
+```bash
+~/.claude/mindsystem/scripts/scan-artifact-subsystems.sh
+```
+
+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
+
+Display results grouped by status. If all OK:
+
+```
+## Subsystem Vocabulary
+
+PASS — all N artifacts use canonical subsystem values.
+```
+
+Go to `report`.
+
+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
+
+For fixes:
+- MISMATCH: propose closest canonical value (fuzzy match on prefix/synonym)
+- MISSING: propose based on artifact content/path context
+
+Apply fixes using Edit tool. Commit:
+
+```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
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore: fix subsystem vocabulary mismatches
+
+Standardized artifact subsystem values to canonical vocabulary.
+EOF
+)"
+```
+</step>
+
+<step name="report">
+Final summary:
+
+```
+## Doctor Report
+
+| Check                  | Result      | Details                    |
+|------------------------|-------------|----------------------------|
+| Subsystem vocabulary   | PASS / INIT | N artifacts, M subsystems  |
+
+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
+</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
+</success_criteria>

package/commands/ms/execute-phase.md

@@ -90,10 +90,17 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
    - Verify: patch file exists OR skip message logged
    - Note: Patch captures all changes including simplifications
 
-9. **Update roadmap and state**
-   - Update ROADMAP.md, STATE.md
+9. **Consolidate knowledge**
+   - Spawn `ms-consolidator` with phase directory and number
+   - Consolidator reads phase artifacts and existing knowledge files
+   - Produces updated `.planning/knowledge/{subsystem}.md` files
+   - Deletes PLAN.md files (execution instructions consumed)
+   - Verify: knowledge files written to `.planning/knowledge/`
 
-10. **Update requirements**
+10. **Update roadmap and state**
+    - Update ROADMAP.md, STATE.md
+
+11. **Update requirements**
     Mark phase requirements as Complete:
     - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
     - Read REQUIREMENTS.md traceability table
@@ -101,16 +108,18 @@ PHASE=$(printf "%02d" "$PHASE_ARG" 2>/dev/null || echo "$PHASE_ARG")
     - Write updated REQUIREMENTS.md
     - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-11. **Commit phase completion**
+12. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
+    - Stage knowledge files: `git add .planning/knowledge/*.md`
+    - Stage PLAN.md deletions: `git add -u .planning/phases/{phase_dir}/*-PLAN.md`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-12. **Offer next steps**
+13. **Offer next steps**
     - Route to next action (see `<offer_next>`)
 
-13. **Update last command**
+14. **Update last command**
     - Update `.planning/STATE.md` Last Command field
     - Format: `Last Command: ms:execute-phase $ARGUMENTS | YYYY-MM-DD HH:MM`
 </process>
@@ -213,8 +222,10 @@ After code simplification step:
 
 After all plans in phase complete:
 1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
-2. Commit with format: `docs({phase}): complete {phase-name} phase`
-3. Bundles all phase-level state updates in one commit
+2. Stage knowledge files: `git add .planning/knowledge/*.md`
+3. Stage PLAN.md deletions: `git add -u .planning/phases/{phase_dir}/*-PLAN.md`
+4. Commit with format: `docs({phase}): complete {phase-name} phase`
+5. Bundles all phase-level state updates in one commit
 
 **NEVER use:**
 - `git add .`
@@ -226,13 +237,12 @@ After all plans in phase complete:
 
 <success_criteria>
 - [ ] All incomplete plans in phase executed
-- [ ] Each plan has SUMMARY.md
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] Phase goal verified (Must-Haves checked against codebase)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message
-- [ ] STATE.md reflects phase completion
-- [ ] ROADMAP.md updated
+- [ ] Knowledge files written to .planning/knowledge/ (consolidation complete)
+- [ ] PLAN.md files deleted from phase directory
+- [ ] STATE.md and ROADMAP.md reflect phase completion
 - [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
-- [ ] User informed of next steps
 </success_criteria>

package/commands/ms/help.md

@@ -376,6 +376,17 @@ Usage: `/ms:adhoc Fix auth token not refreshing on 401`
 
 ### Utility Commands
 
+**`/ms:doctor`**
+Health check and fix project configuration.
+
+- 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
+- Idempotent — safe to run repeatedly
+
+Usage: `/ms:doctor`
+
 **`/ms:help`**
 Show this command reference.
 

package/commands/ms/new-milestone.md

@@ -63,10 +63,9 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 3. **Strategic assessment (silent — do not output this step):**
    - Check for previous milestone artifacts using calculated version:
-     - `.planning/milestones/v{VERSION}-DECISIONS.md` (if exists)
+     - `.planning/knowledge/*.md` (subsystem knowledge files — persist across milestones)
      - `.planning/milestones/v{VERSION}-MILESTONE-AUDIT.md` (if exists)
      - `.planning/TECH-DEBT.md` (if exists)
-     - `.planning/LEARNINGS.md` (if exists)
    - Identify: outstanding tech debt, untested assumptions, high-impact gaps, unaddressed requirements
    - This is background analysis — synthesize silently, surface through suggestions in step 4
 
@@ -85,7 +84,8 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
    ```
 
    Sources for suggestions:
-   - High-impact tech debt from TECH-DEBT.md or MILESTONE-AUDIT.md
+   - Tech debt from TECH-DEBT.md, MILESTONE-AUDIT.md, or knowledge file Pitfalls sections
+   - 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

package/commands/ms/plan-phase.md

@@ -84,7 +84,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 5. Follow plan-phase.md workflow:
    - Load project state and accumulated decisions
    - Perform mandatory discovery (Level 0-3 as appropriate)
-   - Read project history (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
+   - 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
    - Create PLAN.md file(s) with executable structure