mindsystem-cc 4.2.1 → 4.3.1

package/commands/ms/progress.md

@@ -11,8 +11,6 @@ allowed-tools:
 
 <objective>
 Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
-
-Provides situational awareness before continuing work.
 </objective>
 
 
@@ -77,7 +75,7 @@ Compare versions. Store result for the report step. If npm fails or versions mat
 - Read `.planning/STATE.md` for living memory (position, decisions, issues)
 - Read `.planning/ROADMAP.md` for phase structure and objectives
 - Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
-  </step>
+</step>
 
 <step name="recent">
 **Gather recent work context:**
@@ -85,7 +83,7 @@ Compare versions. Store result for the report step. If npm fails or versions mat
 - Find the 2-3 most recent SUMMARY.md files
 - Extract from each: what was accomplished, key decisions, any issues logged
 - This shows "what we've been working on"
-  </step>
+</step>
 
 <step name="position">
 **Parse current position:**
@@ -97,7 +95,7 @@ Compare versions. Store result for the report step. If npm fails or versions mat
 - Check for DESIGN.md: For UI-heavy phases, check if `{phase}-DESIGN.md` exists in phase directory
 - Count pending todos: `ls .planning/todos/*.md 2>/dev/null | wc -l`
 - Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
-  </step>
+</step>
 
 <step name="report">
 **Present rich status report:**
@@ -205,48 +203,7 @@ Read its `<objective>` section.
 
 **Route B: Phase needs planning**
 
-Check if `{phase}-CONTEXT.md` exists in phase directory.
-
-**If CONTEXT.md exists:**
-
-```
----
-
-## ▶ Next Up
-
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-<sub>✓ Context gathered, ready to plan</sub>
-
-`/ms:plan-phase {phase-number}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-```
-
-**If CONTEXT.md does NOT exist:**
-
-```
----
-
-## ▶ Next Up
-
-**Phase {N}: {Name}** — {Goal from ROADMAP.md}
-
-`/ms:plan-phase {phase}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ms:discuss-phase {phase}` — gather context first
-- `/ms:design-phase {phase}` — create UI/UX specifications
-- `/ms:research-phase {phase}` — investigate unknowns
-- `/ms:discuss-phase {phase}` — gather context and validate assumptions
-
----
-```
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions for the **current** phase (not next phase) to present "Next Up" with pre-work context from ROADMAP.md flags.
 
 ---
 
@@ -299,22 +256,11 @@ A milestone was completed and archived. Read `~/.claude/mindsystem/references/ro
 
 </step>
 
-<step name="edge_cases">
-**Handle edge cases:**
-
-- Phase complete but next phase not planned → offer `/ms:plan-phase [next]`
-- All work complete → offer milestone completion
-- Blockers present → highlight before offering to continue
-  </step>
-
 </process>
 
 <success_criteria>
 
-- [ ] Rich context provided (recent work, decisions, issues)
-- [ ] Current position clear with visual progress
-- [ ] What's next clearly explained
-- [ ] Smart routing: /ms:execute-phase if plan exists, /ms:plan-phase if not
-- [ ] User confirms before any action
-- [ ] Seamless handoff to appropriate mindsystem command
-      </success_criteria>
+- [ ] Report includes recent work, decisions, blockers, and pending counts
+- [ ] Smart routing: /ms:execute-phase if plan exists, ROADMAP pre-work flags consulted if not
+- [ ] Presents copy-paste command — never auto-executes the routed action
+</success_criteria>

package/commands/ms/research-phase.md

@@ -40,7 +40,7 @@ Use `find-phase` output from context. **If phase not found (dir is null):** Erro
 ## 2. Check Existing Research
 
 ```bash
-ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
+ls ${PHASE_DIR}/*RESEARCH.md 2>/dev/null
 ```
 
 **If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
@@ -61,9 +61,9 @@ grep -A20 "Phase ${PHASE}:" .planning/ROADMAP.md
 # Requirements
 cat .planning/REQUIREMENTS.md 2>/dev/null
 
-# Phase-specific context and design
-cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
-cat .planning/phases/${PHASE}-*/${PHASE}-DESIGN.md 2>/dev/null
+# Phase-specific context and design (PHASE_DIR from find-phase in <context>)
+cat ${PHASE_DIR}/*-CONTEXT.md 2>/dev/null
+cat ${PHASE_DIR}/*-DESIGN.md 2>/dev/null
 
 # Locked decisions
 grep -A30 "### Decisions Made" .planning/STATE.md 2>/dev/null
@@ -304,27 +304,32 @@ Write RESEARCH.md to `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md` using
 
 ```bash
 ms-tools set-last-command "ms:research-phase $ARGUMENTS"
-git add .planning/phases/${PHASE}-*/*-RESEARCH.md .planning/STATE.md
+git add ${PHASE_DIR}/*-RESEARCH.md .planning/STATE.md
 git commit -m "docs: complete research for phase ${PHASE}"
 ```
 
-Display research summary. Read `~/.claude/mindsystem/references/prework-status.md` to show what's done vs still needed for this phase.
+Display research summary.
 
 **Post-synthesis routing:**
 
 Scan the synthesized RESEARCH.md for LOW confidence sections and significant open questions.
 
-If all sections HIGH/MEDIUM confidence with no major gaps, use AskUserQuestion:
-1. Proceed to planning
-2. Dig deeper into specific area
-3. Review full research
+If all sections HIGH/MEDIUM confidence with no major gaps:
+
+Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+
+Also offer:
+- **Dig deeper** — into specific area
+- **Review full research** — display RESEARCH.md
 
 If any section has LOW confidence or significant open questions, flag the weak areas explicitly, then use AskUserQuestion:
 1. Dig deeper into [specific LOW area] — re-run targeted agent
 2. Try different research mode (e.g., ecosystem -> implementation)
-3. Proceed to planning with caveats noted
+3. Proceed with caveats noted
 4. Review full research
 
+When user selects "Proceed with caveats noted", read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+
 </process>
 
 <checkpoint_handling>

package/commands/ms/verify-work.md

@@ -31,6 +31,11 @@ Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 
+Resolve phase directory:
+```bash
+ms-tools find-phase "$ARGUMENTS"
+```
+
 @.planning/STATE.md
 @.planning/ROADMAP.md
 @.planning/PROJECT.md
@@ -49,9 +54,10 @@ Phase: $ARGUMENTS (optional)
    - Present tests via AskUserQuestion (Pass / Can't test / Skip / Other)
    - Process results — UAT.md updates happen via `ms-tools uat-update` (auto-recalculates progress)
    - **For each issue found:**
-     - Lightweight investigation (2-3 tool calls)
+     - On first issue: load knowledge files (match phase subsystem against `.planning/knowledge/*.md`)
+     - Lightweight investigation (2-3 tool calls, informed by knowledge)
      - If simple: Fix inline, commit (amend previous fix commit on retry when HEAD matches fix_commit), ask for re-test
-     - If complex: Spawn ms-verify-fixer subagent
+     - If complex: Spawn ms-verify-fixer subagent (with knowledge context in prompt)
      - 2 retries on failed re-test, then offer options
 8. **On batch transition:**
    - If new mock_type: Revert old mocks (`git checkout -- <mocked_files>`), apply new ones

package/mindsystem/references/prework-status.md

@@ -22,7 +22,8 @@ Extract:
 Check what context files already exist:
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
 [ -f "$PHASE_DIR"/*-CONTEXT.md ] && echo "CONTEXT_EXISTS"
 [ -f "$PHASE_DIR"/*-DESIGN.md ] && echo "DESIGN_EXISTS"
 [ -f "$PHASE_DIR"/*-RESEARCH.md ] && echo "RESEARCH_EXISTS"

package/mindsystem/references/routing/next-phase-routing.md

@@ -1,17 +1,17 @@
 # Next Phase Routing
 
-Reference for presenting "Next Up" guidance when moving to the next phase. Used by execute-phase and verify-work.
+Reference for presenting "Next Up" guidance for a phase. Used by progress (current phase) and verify-work (next phase).
 
 ## Purpose
 
-Help user decide between Discuss/Research/Design/Plan for the NEXT phase without referencing external files.
+Help user decide between Discuss/Research/Design/Plan for a target phase using ROADMAP.md pre-work flags.
 
 ## Information to Extract
 
-From ROADMAP.md, get the next phase details:
+From ROADMAP.md, get the target phase details:
 
 ```bash
-grep -A 25 "### Phase ${NEXT_PHASE}:" .planning/ROADMAP.md
+grep -A 25 "### Phase ${TARGET_PHASE}:" .planning/ROADMAP.md
 ```
 
 Extract:
@@ -26,7 +26,8 @@ Extract:
 Check for existing context files:
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${NEXT_PHASE}-* 2>/dev/null | head -1)
+ms-tools find-phase "${TARGET_PHASE}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
 [ -f "$PHASE_DIR"/*-CONTEXT.md ] && echo "CONTEXT_EXISTS"
 [ -f "$PHASE_DIR"/*-DESIGN.md ] && echo "DESIGN_EXISTS"
 [ -f "$PHASE_DIR"/*-RESEARCH.md ] && echo "RESEARCH_EXISTS"

package/mindsystem/templates/knowledge.md

@@ -66,7 +66,7 @@ Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge fi
 - **Architecture and Design use prose bullets.** Describe how things work, not tables.
 - **Pitfalls use bold titles** for scannability.
 - **Key Files is a flat list.** No nesting, no grouping.
-- **Rewrite semantics, not append.** Each consolidation produces the current state. Superseded decisions get updated. Outdated patterns get removed. The file is always current.
+- **Edit to reflect current state.** Each update produces the current state through targeted edits — update superseded decisions, remove outdated patterns, append new entries. Use `Edit` for existing files, `Write` only for new files. Never replace an entire knowledge file via `Write`.
 
 ## Cross-Reference Pattern
 

package/mindsystem/templates/milestone-archive.md

@@ -10,8 +10,6 @@ This template is used by the complete-milestone workflow to create archive files
 
 **Status:** ✅ SHIPPED {{DATE}}
 **Phases:** {{PHASE_START}}-{{PHASE_END}}
-**Total Plans:** {{TOTAL_PLANS}}
-
 ## Overview
 
 {{MILESTONE_DESCRIPTION}}
@@ -26,13 +24,6 @@ This template is used by the complete-milestone workflow to create archive files
 
 **Goal**: {{PHASE_GOAL}}
 **Depends on**: {{DEPENDS_ON}}
-**Plans**: {{PLAN_COUNT}} plans
-
-Plans:
-
-- [x] {{PHASE}}-01: {{PLAN_DESCRIPTION}}
-- [x] {{PHASE}}-02: {{PLAN_DESCRIPTION}}
-      [... all plans ...]
 
 **Details:**
 {{PHASE_DETAILS_FROM_ROADMAP}}
@@ -43,11 +34,6 @@ Plans:
 
 **Goal**: Fix authentication bypass vulnerability
 **Depends on**: Phase 2
-**Plans**: 1 plan
-
-Plans:
-
-- [x] 02.1-01: Patch auth vulnerability
 
 **Details:**
 {{PHASE_DETAILS_FROM_ROADMAP}}

package/mindsystem/templates/roadmap-milestone.md

@@ -18,12 +18,6 @@ Template for reorganizing `ROADMAP.md` after first milestone ships. Collapse com
 
 ### Phase 1: [Name]
 **Goal**: [What this phase delivers]
-**Plans**: 3 plans
-
-Plans:
-- [x] 01-01: [Brief description]
-- [x] 01-02: [Brief description]
-- [x] 01-03: [Brief description]
 
 [... remaining phases ...]
 
@@ -36,11 +30,6 @@ Plans:
 #### Phase 5: [Name]
 **Goal**: [What this phase delivers]
 **Depends on**: Phase 4
-**Plans**: 2 plans
-
-Plans:
-- [ ] 05-01: [Brief description]
-- [ ] 05-02: [Brief description]
 
 [... remaining phases ...]
 
@@ -52,11 +41,11 @@ Plans:
 
 ## Progress
 
-| Phase | Milestone | Plans Complete | Status | Completed |
-|-------|-----------|----------------|--------|-----------|
-| 1. Foundation | MVP | 3/3 | Complete | YYYY-MM-DD |
-| 2. Features | MVP | 2/2 | Complete | YYYY-MM-DD |
-| 5. Security | Security & Polish | 0/2 | Not started | - |
+| Phase | Milestone | Status | Completed |
+|-------|-----------|--------|-----------|
+| 1. Foundation | MVP | Complete | YYYY-MM-DD |
+| 2. Features | MVP | Complete | YYYY-MM-DD |
+| 5. Security | Security & Polish | Not started | - |
 ```
 
 **Notes:**

package/mindsystem/templates/roadmap.md

@@ -52,12 +52,6 @@ Decimal phases appear between their surrounding integers in numeric order.
 **Discuss**: Unlikely (mechanical setup, zero design decisions)
 **Design**: Unlikely (backend only)
 **Research**: Unlikely (established patterns)
-**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
-
-Plans:
-- [ ] 01-01: [Brief description of first plan]
-- [ ] 01-02: [Brief description of second plan]
-- [ ] 01-03: [Brief description of third plan]
 
 ### Phase 2: [Name]
 **Goal**: [What this phase delivers]
@@ -72,21 +66,12 @@ Plans:
 **Design focus**: [What to design]
 **Research**: Likely (new integration)
 **Research topics**: [What needs investigating]
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 02-01: [Brief description]
-- [ ] 02-02: [Brief description]
 
 ### Phase 2.1: Critical Fix (INSERTED)
 **Goal**: [Urgent work inserted between phases]
 **Depends on**: Phase 2
 **Success Criteria** (what must be TRUE):
   1. [What the fix achieves]
-**Plans**: 1 plan
-
-Plans:
-- [ ] 02.1-01: [Description]
 
 ### Phase 3: [Name]
 **Goal**: [What this phase delivers]
@@ -101,11 +86,6 @@ Plans:
 **Design**: Unlikely (API only)
 **Research**: Likely (external API)
 **Research topics**: [What needs investigating]
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 03-01: [Brief description]
-- [ ] 03-02: [Brief description]
 
 ### Phase 4: [Name]
 **Goal**: [What this phase delivers]
@@ -118,22 +98,18 @@ Plans:
 **Discuss topics**: [Priority rules, batch vs individual, error recovery]
 **Design**: Unlikely (backend only)
 **Research**: Unlikely (internal patterns)
-**Plans**: [Number of plans]
-
-Plans:
-- [ ] 04-01: [Brief description]
 
 ## Progress
 
 **Execution Order:**
 Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 
-| Phase | Plans Complete | Status | Completed |
-|-------|----------------|--------|-----------|
-| 1. [Name] | 0/3 | Not started | - |
-| 2. [Name] | 0/2 | Not started | - |
-| 3. [Name] | 0/2 | Not started | - |
-| 4. [Name] | 0/1 | Not started | - |
+| Phase | Status | Completed |
+|-------|--------|-----------|
+| 1. [Name] | Not started | - |
+| 2. [Name] | Not started | - |
+| 3. [Name] | Not started | - |
+| 4. [Name] | Not started | - |
 ```
 
 <guidelines>
@@ -145,11 +121,9 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 **Initial planning:**
 - Phase count derived from actual work (not a target number)
 - Each phase delivers something coherent
-- Phases can have 1+ plans (split by orchestrator judgment — multiple subsystems, context budget, vertical slices)
 - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
 - No time estimates (this isn't enterprise PM)
 - Progress table updated by execute workflow
-- Plan count can be "TBD" initially, refined during planning
 
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)

package/mindsystem/workflows/complete-milestone.md

@@ -345,7 +345,6 @@ Extract completed milestone details and create archive file.
    - {{DATE}} — Today's date
    - {{PHASE_START}} — First phase number in milestone
    - {{PHASE_END}} — Last phase number in milestone
-   - {{TOTAL_PLANS}} — Count of all plans in milestone
    - {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview
    - {{PHASES_SECTION}} — Full phase details extracted
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md

package/mindsystem/workflows/compound.md

@@ -19,7 +19,7 @@ fi
 ```
 
 **Mode detection:**
-- If `$ARGUMENTS` empty: **description mode** — deduce from conversation context. Summarize what was discussed/changed in the current session.
+- If `$ARGUMENTS` empty: **conversation mode** — reflect on current conversation to build change summary. No Explore agents needed.
 - If matches git SHA pattern (7-40 hex chars), contains `..`, or starts with `HEAD`: **git mode**
 - If matches existing file path (`test -e "$ARGUMENTS"`): **file mode**
 - Otherwise: **description mode** — treat `$ARGUMENTS` as free-text description
@@ -42,7 +42,25 @@ git log --oneline -5 -- <path>
 ```
 Capture file path for passing to compounder.
 
-**Description mode (including no-args):**
+**Conversation mode (no args):**
+Build change summary from conversation context and git data.
+
+1. **Reflect on conversation:** Summarize what was discussed, changed, and decided
+   in the current session. Include rationale and key decisions.
+2. **Supplement with git data:**
+   ```bash
+   git diff --stat          # uncommitted changes
+   git log --stat -5        # recent commits with file lists
+   ```
+3. **Thin-context guard:** If conversation reflection produces little substance
+   (e.g., fresh context, unrelated discussion), use AskUserQuestion:
+   - "Describe what changed" — enter free-text, then proceed as description mode (spawn Explore agents)
+   - "Compound recent commits" — use git log output as change context
+   - "Cancel" — abort
+4. **Combine into change summary:** Merge conversation insights with git file paths
+   into a concise summary covering: what changed, why, which files, key decisions.
+
+**Description mode (free-text argument provided):**
 Spawn 1 Explore agent to find relevant code changes. If changes span multiple unrelated areas, spawn a second agent for the additional area. They return:
 - Which files changed or are relevant
 - Which subsystems are likely affected
@@ -60,7 +78,7 @@ ms-tools config-get subsystems
 
 **Git/file mode:** Match file paths from diff stats against subsystem names via keyword matching.
 
-**Description mode:** Use Explore agent findings for subsystem matching.
+**Description/conversation mode:** Use Explore agent findings or conversation summary for subsystem matching.
 
 **Detect potential new subsystems:** Changes in file areas that don't match any existing subsystem.
 
@@ -82,8 +100,8 @@ AskUserQuestion: "Compound knowledge for these subsystems?" with options:
 
 <step name="spawn_compounder">
 Spawn ms-compounder via Task tool with:
-- Input mode (`git`, `file`, or `description`)
-- Change reference (git ref/range, file path, or description + exploration findings)
+- Input mode (`git`, `file`, or `description` — conversation mode passes as `description`)
+- Change reference (git ref/range, file path, description + exploration findings, or conversation summary)
 - Confirmed affected subsystems list
 - Config.json subsystem vocabulary
 
@@ -91,7 +109,7 @@ Agent reads changes, reads affected knowledge files, writes updates, returns rep
 </step>
 
 <step name="finalize">
-**Update config.json** (if new subsystems were confirmed in step 4):
+**Update config.json** (if new subsystems were confirmed in confirm_with_user step):
 ```bash
 # Add new subsystem to config.json
 ms-tools config-set subsystems --append "new-subsystem"

package/mindsystem/workflows/discuss-phase.md

@@ -80,8 +80,9 @@ cat .planning/knowledge/{subsystem}.md 2>/dev/null
 Check if CONTEXT.md already exists for this phase:
 
 ```bash
-ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null
-ls .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field, PHASE from `phase` field (normalized, e.g. "02")
+ls ${PHASE_DIR}/*CONTEXT.md 2>/dev/null
 ```
 
 **If exists:**
@@ -242,10 +243,10 @@ Create CONTEXT.md capturing the user's vision and decisions.
 
 Use template from ~/.claude/mindsystem/templates/context.md
 
-**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md`
+**File location:** `${PHASE_DIR}/${PHASE}-CONTEXT.md`
 
 **If phase directory doesn't exist yet:**
-Create it: `.planning/phases/${PHASE}-${SLUG}/`
+Create it using normalized `${PHASE}` from find-phase output: `.planning/phases/${PHASE}-${SLUG}/`
 
 Use roadmap phase name for slug (lowercase, hyphens).
 
@@ -271,7 +272,7 @@ Write file.
 Present CONTEXT.md summary:
 
 ```
-Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
+Created: ${PHASE_DIR}/${PHASE}-CONTEXT.md
 
 ## Vision
 [How they imagine it working]
@@ -279,22 +280,6 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 ## Essential
 [What must be nailed]
 
----
-
-## ▶ Next Up
-
-**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
-
-`/ms:plan-phase ${PHASE}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ms:research-phase ${PHASE}` — investigate unknowns
-- Review/edit CONTEXT.md before continuing
-
 ---
 ```
 
@@ -306,7 +291,7 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 
 ```bash
 ms-tools set-last-command "ms:discuss-phase ${PHASE}"
-git add .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md .planning/STATE.md
+git add ${PHASE_DIR}/${PHASE}-CONTEXT.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs(${PHASE}): capture phase context
 

package/mindsystem/workflows/doctor-fixes.md

@@ -315,7 +315,7 @@ Spawn a `general-purpose` subagent (Task tool) with the following structured pro
 > - Preserve rationale when visible in code comments or config. Do not fabricate reasons.
 > - Do not fabricate specific numbers (limits, thresholds, counts) — read from source or omit.
 > - Omit empty sections. No Design section if subsystem has no UI.
-> - Rewrite semantics — if existing knowledge files exist, merge by producing current state.
+> - Edit to reflect current state — use `Edit` for existing knowledge files (targeted changes), `Write` only for new files.
 > - Cross-reference between subsystems where relevant: "(see api subsystem)".
 > - Decisions table: 5-10 words per cell. Source column: `"existing"` for source code mode, artifact reference for artifact mode.
 > - Key files must reference actual paths verified to exist.

package/mindsystem/workflows/execute-phase.md

@@ -39,11 +39,9 @@ Options:
 Confirm phase exists and has plans:
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
-if [ -z "$PHASE_DIR" ]; then
-  echo "ERROR: No phase directory matching '${PHASE_ARG}'"
-  exit 1
-fi
+ms-tools find-phase "${PHASE_ARG}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
+# If dir is null, error: "No phase directory matching '${PHASE_ARG}'"
 
 PLAN_COUNT=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
 if [ "$PLAN_COUNT" -eq 0 ]; then
@@ -541,24 +539,24 @@ All {Y} plans finished. Phase goal verified.
 
 **Then present "Also available" based on milestone status:**
 
-**If more phases remain:**
+**If more phases remain AND skip context applies:**
 
-Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` to determine the most appropriate command for the next phase (discuss/design/research/plan based on pre-work flags). Present concisely under "Also available":
+Determine the next phase's primary suggestion inline — do NOT read next-phase-routing.md:
+- From ROADMAP.md (already in context), get Phase {Z+1} pre-work flags
+- Check: CONTEXT.md exists? DESIGN.md? RESEARCH.md? in next phase dir
+- Priority: discuss (if Likely + no CONTEXT.md) > design (if Likely + no DESIGN.md) > research (if Likely + no RESEARCH.md) > plan-phase
+- Present ONE "Also available" entry:
 
 ```markdown
 ---
-
-**Phase {Z+1}: {Name}** — {Goal}
-{If pre-work flagged: brief note about recommendations}
-
 **Also available:**
-- `/ms:{suggested} {Z+1}` — {reason from routing}
-- `/ms:plan-phase {Z+1}` — skip pre-work, plan directly
-
+- `/ms:{suggested} {Z+1}` — skip verify, start Phase {Z+1}: {Name}
 ---
 ```
 
-Include the pre-work recommendations table from the routing reference if any pre-work is flagged as "Likely".
+**If more phases remain but skip context does NOT apply:** No "Also available" — verify-work is the sole suggestion.
+
+Do NOT present pre-work recommendation tables or multiple cross-phase alternatives. Cross-phase routing belongs to verify-work and progress.
 
 **If milestone complete:**
 

package/mindsystem/workflows/execute-plan.md

@@ -260,7 +260,9 @@ completed: YYYY-MM-DD
 ---
 ```
 
-**Subsystem:** Use inline `**Subsystem:**` metadata from plan header if present. Otherwise select from `ms-tools config-get subsystems`. If novel, append to config.json and log in decisions.
+**Subsystem:** Use inline `**Subsystem:**` metadata from plan header if present. Otherwise select the best match from `ms-tools config-get subsystems`.
+
+**Novel subsystem (safety net):** If the plan's work genuinely doesn't fit any existing subsystem, append: `ms-tools config-set subsystems --append "{name}"`. Use in SUMMARY frontmatter and log the addition in Decisions Made. This is a fallback — `create-roadmap` handles most subsystem additions proactively.
 
 **Mock hints:** Reflect on what you built. If UI with transient states (loading, animations, async transitions) or external data dependencies, populate accordingly. If purely backend or no async UI, write `mock_hints: none  # reason`. Always populate.
 

package/mindsystem/workflows/mockup-generation.md

@@ -79,8 +79,9 @@ Extract the HTML scaffold from the `<template>` block.
 
 <step name="spawn_agents">
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
-# Assumes single match. If empty, phase directory is missing — stop and report.
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
+# If dir is null, phase directory is missing — stop and report.
 mkdir -p "${PHASE_DIR}/mockups"
 ```