mindsystem-cc 4.2.1 → 4.3.0

package/README.md

@@ -187,11 +187,13 @@ You approve the plan structure and can adjust granularity.
 
 Runs without intervention. Each plan runs in a fresh subagent with the full context window available. Goal-backward verification checks that the phase achieved its intended outcome, not just that tasks got marked complete.
 
+For web projects, browser verification launches a real browser against your dev server, derives a checklist from execution summaries, and verifies each route visually and programmatically. Clear mismatches get fixed inline; issues beyond visual fixes are reported with screenshot evidence for verify-work.
+
 Configurable code review produces separate commits for review changes. Patch files are generated for manual inspection.
 
 After execution, knowledge consolidation updates subsystem-scoped knowledge files. Future phases touching the same subsystems start with accumulated context: decisions made, patterns established, pitfalls encountered.
 
-**Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, knowledge file updates.
+**Creates:** `SUMMARY.md`, `VERIFICATION.md`, `.patch` files, screenshots, knowledge file updates.
 
 ### 9. Verify work
 
@@ -251,6 +253,10 @@ Orchestration metadata (wave grouping, dependencies) lives in `EXECUTION-ORDER.m
 
 Unnecessary instructions aren't wasted space — they interfere with the ones that matter. Each instruction passes a reliability test: does removing this degrade output in the actual runtime context? Every command, workflow, and agent definition gets audited to cut that interference. Audited agents show 35-39% context reduction with no behavioral regression.
 
+### Browser verification
+
+During execute-phase, web projects get automatic visual QA via [agent-browser](https://github.com/anthropics/agent-browser). A checklist is derived from execution summaries, then each route is verified with screenshots and programmatic diagnostics (console logs, JS errors, network failures). Clear mismatches get fixed inline; anything deeper is reported with screenshot evidence for verify-work. Enabled by default — disable per-project via `/ms:config`.
+
 ### Built-in code review
 
 Configurable per tier: adhoc, phase, or milestone. Runs after execution and produces separate commits for inspection. Ships with structural analysis (`ms-code-reviewer`) and clarity-focused simplification (`ms-code-simplifier`), but you can point any tier at your own custom reviewer agent via `.planning/config.json`.
@@ -296,6 +302,11 @@ Requirements you want but haven't shipped yet are tracked in `PROJECT.md` with o
 - [uv](https://docs.astral.sh/uv/) — Python package runner used by CLI scripts (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
 - Python 3.10+ (used by uv for scripts)
 
+**Optional (for web projects):**
+
+- [agent-browser](https://github.com/anthropics/agent-browser) — enables browser verification during execute-phase (`npm install -g agent-browser`)
+- `cwebp` — optimizes verification screenshots to WebP (`brew install webp`)
+
 ---
 
 ## Quick start
@@ -452,6 +463,13 @@ Mindsystem stores project config in `.planning/config.json`. Run `/ms:config` to
   //   "auto" (default) | "ask" | "off"
   "open_mockups": "auto",
 
+  // Browser verification during execute-phase (web projects only).
+  //   Launches a real browser, derives checklist from summaries,
+  //   screenshots + console/network diagnostics.
+  "browser_verification": {
+    "enabled": true   // default: true for web projects
+  },
+
   // External task tracker integration (Linear only for now).
   //   null → disabled (default)
   "task_tracker": {

package/agents/ms-browser-verifier.md

@@ -34,13 +34,22 @@ Open the app URL headless. If redirected to login, report auth failure and exit
 <step name="environment_preflight">
 Navigate to the app's main route. Screenshot `00-preflight.png`.
 
+Read diagnostics:
+```bash
+agent-browser console
+agent-browser errors
+agent-browser network requests
+```
+
 Evaluate:
-- Does the app load?
-- Visible backend errors? Console errors? Blank page?
+- Does the app load visually?
+- Console errors or uncaught exceptions?
+- Failed network requests (4xx/5xx)?
+- Blank page?
 
-**If systemic issue** (app won't load, white screen, critical error):
+**If systemic issue** (app won't load, white screen, critical error, cascade of failed requests):
 - Screenshot the failure
-- Return `environment_blocked` report to orchestrator with screenshot evidence
+- Return `environment_blocked` report to orchestrator with screenshot and diagnostic output
 - Stop — no point testing individual items
 
 **If app loads with minor warnings:**
@@ -59,16 +68,23 @@ mkdir -p {screenshots_dir}
 For each checklist item:
 
 ```
+agent-browser errors --clear   ← isolate errors per item
+
 Navigate to route → Screenshot → Evaluate
 
 Match expected?
 YES → PASSED, next item
-NO → Environment issue? (API error, 404, empty data, console network errors)
+NO → Read diagnostics:
+     agent-browser errors
+     agent-browser console
+     agent-browser network requests
+
+     Environment issue? (uncaught exception, failed API request, 4xx/5xx, empty data)
      YES → ENVIRONMENT_BLOCKED for this item
            Same error on 2+ consecutive items? → stop, return report
            Otherwise → next item
-     NO → Investigate in project source files
-          → Hit a stop signal? (see Investigation boundaries + Fix discipline) → ISSUE with screenshot evidence, next item
+     NO → Investigate in project source files (diagnostics narrow the search)
+          → Hit a stop signal? (see Investigation boundaries + Fix discipline) → ISSUE with screenshot and diagnostic evidence, next item
           → Root cause found → Fix attempt → re-screenshot
             Fix worked? → FIXED (commit), next item
             Fix failed? → Different root-cause theory available?
@@ -77,9 +93,9 @@ NO → Environment issue? (API error, 404, empty data, console network errors)
 ```
 
 **Per-item screenshots:**
-- `{NN}-{item-slug}.png` — initial state
-- `{NN}-{item-slug}-result.png` — after interaction (if applicable)
-- `{NN}-{item-slug}-fixed.png` — after fix (if applicable)
+- `{NN}-{item-slug}.webp` — initial state (`.png` if cwebp unavailable)
+- `{NN}-{item-slug}-result.webp` — after interaction (if applicable)
+- `{NN}-{item-slug}-fixed.webp` — after fix (if applicable)
 
 **Interactions:** If the checklist item includes an interaction (click, type, submit), perform it and screenshot the result.
 </step>
@@ -105,10 +121,10 @@ Close the browser. Return a structured report to the orchestrator:
 - {what was wrong} → {what was fixed} | Commit: {hash}
 
 ### Issues Found
-- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows}
+- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows} | Diagnostics: {console errors, failed network requests, or "none"}
 
 ### Environment Blockers
-- {description} | Screenshot: {filename}
+- {description} | Screenshot: {filename} | Diagnostics: {error messages, failed requests}
 ```
 </step>
 
@@ -120,11 +136,15 @@ Close the browser. Return a structured report to the orchestrator:
 - Save all screenshots to `{screenshots_dir}` — never to temp or working directory
 - Re-snapshot after every DOM change (element refs go stale)
 - Wait for networkidle before evaluating
+- Convert screenshots to WebP after capture:
+  1. Check once during preflight: `which cwebp`
+  2. If available, after each screenshot: `cwebp -q 80 {file}.png -o {file}.webp && rm {file}.png`
+  3. If unavailable: keep PNGs as-is
 
 ## Investigation boundaries
 - Only read project source files — never node_modules, dist, build output, or generated directories
 - Never read framework/library source to understand why something doesn't work internally
-- Check network responses and console errors before investigating code — if the data source is the problem, it's ENVIRONMENT_BLOCKED
+- Read `agent-browser errors`, `agent-browser console`, and `agent-browser network requests` before investigating source code — if diagnostics show a failed API call or server error, it's ENVIRONMENT_BLOCKED, not a code fix
 - If 2+ consecutive items show the same failure pattern, identify the shared root cause rather than investigating each individually
 
 ## Fix discipline

package/agents/ms-compounder.md

@@ -19,7 +19,7 @@ You are a Mindsystem knowledge compounder spawned by the compound workflow to up
 ## Required Context (provided by compound workflow)
 
 - **Input mode:** `git`, `file`, or `description`
-- **Change reference:** Git ref/range (git mode), file path (file mode), or description + exploration summary (description mode)
+- **Change reference:** Git ref/range (git mode), file path (file mode), or description/conversation summary (description mode)
 - **Affected subsystems:** List confirmed by user in main context
 - **Subsystem vocabulary:** From config.json (for alignment validation)
 
@@ -47,7 +47,7 @@ Retrieve the raw changes based on input mode:
 
 - **Git mode:** `git show <ref>` for single commit, `git diff <range>` for ranges. Include `--stat` for file overview.
 - **File mode:** Read the file content. Run `git log --oneline -5 -- <path>` for recent history context.
-- **Description mode:** Use the provided exploration summary as change context. No additional reads needed.
+- **Description mode:** Use the provided summary (from exploration or conversation context) as change context. No additional reads needed.
 
 ## Step 2: Read Existing Knowledge Files
 

package/agents/ms-researcher.md

@@ -483,7 +483,8 @@ Orchestrator provides:
 
 ```bash
 # For phase research, check for CONTEXT.md from discuss-phase
-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
 if [ -n "$PHASE_DIR" ]; then
   cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
 fi

package/agents/ms-roadmapper.md

@@ -534,6 +534,19 @@ Verify 100% requirement mapping:
 
 If gaps found, include in draft for user decision.
 
+## Step 6b: Evaluate Subsystem Coverage
+
+Compare phase domains against config.json `subsystems` array. Phases may introduce domains not in the current subsystem vocabulary.
+
+1. Parse `subsystems` from config.json (provided in planning context)
+2. For each phase, identify its primary domain (e.g., "Payment Processing" maps to `payments`)
+3. Match against existing subsystems — exact or close synonym counts as covered
+4. Collect unmatched domains as proposed additions
+
+Include proposals in the return under `### Subsystem Proposals`. Do not modify config.json — the orchestrator handles confirmation and update.
+
+If all phase domains map to existing subsystems, omit the section.
+
 ## Step 7: Write Files Immediately
 
 **Write files first, then return.** This ensures artifacts persist even if context is lost.
@@ -613,6 +626,16 @@ When files are written and returning to orchestrator:
 
 {For phases with Likely recommendations, include topics/focus}
 
+{If new subsystems proposed:}
+
+### Subsystem Proposals
+
+New domains detected that don't match existing subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}: {phase-name} | {why this needs its own subsystem} |
+
 ### Files Ready for Review
 
 User can review actual files:
@@ -644,6 +667,16 @@ After incorporating user feedback and updating files:
 - .planning/ROADMAP.md
 - .planning/STATE.md (if needed)
 
+{If new subsystems proposed:}
+
+### Subsystem Proposals
+
+New domains detected that don't match existing subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}: {phase-name} | {why this needs its own subsystem} |
+
 ### Updated Summary
 
 | Phase | Goal | Requirements |

package/commands/ms/compound.md

@@ -19,7 +19,7 @@ Input modes:
 - **Git reference:** SHA, range (`HEAD~3..HEAD`), or any git ref
 - **File path:** Path to a changed file
 - **Description:** Free-text description of changes
-- **No args:** Infer from current conversation context
+- **No args:** Reflect on current conversation context + git data
 </objective>
 
 <execution_context>
@@ -34,7 +34,7 @@ Validate active project: check `.planning/config.json` exists.
 </step>
 
 <step name="resolve_change_context">
-Gather lightweight change context. Git mode: diff stats. File mode: recent git log. Description mode: spawn Explore agents to find relevant changes.
+Gather lightweight change context. Git mode: diff stats. File mode: recent git log. No-args mode: reflect on conversation context + git diff/log; if context is thin, ask user for intent. Description mode: spawn Explore agents to find relevant changes.
 </step>
 
 <step name="determine_subsystems">
@@ -50,7 +50,7 @@ Spawn ms-compounder with input mode, change reference, confirmed subsystems, and
 </step>
 
 <step name="finalize">
-Update config.json if new subsystems confirmed. Commit knowledge file changes. Set last command.
+Update config.json if new subsystems confirmed. Commit knowledge file changes. Set last command. Report results.
 </step>
 
 </process>

package/commands/ms/create-roadmap.md

@@ -136,8 +136,9 @@ Task(
 5. Map every v1 requirement to exactly one phase
 6. Derive 2-5 success criteria per phase (observable user behaviors)
 7. Validate 100% coverage
-8. Write files immediately (REQUIREMENTS.md, ROADMAP.md, STATE.md)
-9. Return ROADMAP CREATED with combined requirements + roadmap summary
+8. Evaluate subsystem coverage — compare phase domains against config.json subsystems, propose additions for unmatched domains
+9. Write files immediately (REQUIREMENTS.md, ROADMAP.md, STATE.md)
+10. Return ROADMAP CREATED with combined requirements + roadmap summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
@@ -200,6 +201,18 @@ Pre-work: Research [Likely/Unlikely] | Discuss [Likely/Unlikely] | Design [Likel
 
 [... continue for all phases ...]
 
+{If roadmapper returned Subsystem Proposals:}
+
+### New Subsystems
+
+The roadmap introduces domains not covered by current subsystems:
+
+| Proposed | Source Phase | Rationale |
+|----------|-------------|-----------|
+| {name}   | Phase {N}   | {reason}  |
+
+These will be added to config.json upon approval.
+
 ---
 ```
 </step>
@@ -275,7 +288,11 @@ Return ROADMAP REVISED with changes made.
 **Update state and commit:**
 
 ```bash
+# For each subsystem proposal the user approved (skip any rejected during revision):
+ms-tools config-set subsystems --append "{subsystem-name}"
+
 git add .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
+git diff --quiet .planning/config.json 2>/dev/null || git add .planning/config.json
 git commit -m "$(cat <<'EOF'
 docs: define requirements and create roadmap
 

package/commands/ms/design-phase.md

@@ -30,9 +30,14 @@ Create design specifications for a phase. Spawns ms-designer agent with phase co
 <context>
 Phase number: $ARGUMENTS (required)
 
+Resolve phase directory:
+```bash
+ms-tools find-phase "$ARGUMENTS"
+```
+
 Check for existing design:
 ```bash
-ls .planning/phases/${PHASE}-*/*DESIGN.md 2>/dev/null
+ls ${PHASE_DIR}/*DESIGN.md 2>/dev/null
 ```
 </context>
 
@@ -52,8 +57,7 @@ ms-tools find-phase "$ARGUMENTS"
 ## 2. Check Existing Design
 
 ```bash
-# Check for existing DESIGN.md
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+# PHASE_DIR already resolved from find-phase in <context>
 ls "${PHASE_DIR}"/*-DESIGN.md 2>/dev/null
 ```
 
@@ -119,7 +123,7 @@ Extract from ROADMAP.md:
 **4b. Optional context - CONTEXT.md (from discuss-phase):**
 
 ```bash
-cat .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
+cat ${PHASE_DIR}/*-CONTEXT.md 2>/dev/null
 ```
 
 If exists, extract:
@@ -377,7 +381,7 @@ Task(
 
 ```bash
 ms-tools set-last-command "ms:design-phase $ARGUMENTS"
-git add .planning/phases/${PHASE}-*/*-DESIGN.md .planning/STATE.md
+git add ${PHASE_DIR}/*-DESIGN.md .planning/STATE.md
 git commit -m "docs: create design for phase ${PHASE}"
 ```
 
@@ -387,12 +391,12 @@ Display summary from agent response:
 - Screens designed
 - Key design decisions
 
-Then present pre-work status: Read `~/.claude/mindsystem/references/prework-status.md` and show what's done vs still needed for this phase.
-
 Also offer:
 - **Refine design** — Discuss changes conversationally
 - **View full design** — Display DESIGN.md
 
+Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
+
 **`## DESIGN NEEDS CLARIFICATION`:**
 
 Present the question to user. Get response. Spawn continuation with the clarification.

package/commands/ms/help.md

@@ -136,6 +136,7 @@ Define requirements and create roadmap with phases.
 - Creates `.planning/ROADMAP.md` (phase breakdown)
 - Creates `.planning/STATE.md` (project memory)
 - Creates `.planning/phases/` directories
+- Evaluates subsystem coverage — proposes new subsystems if phases introduce unmatched domains
 
 Usage: `/ms:create-roadmap`
 

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), execute-phase (next 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/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/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

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"
 ```
 

package/mindsystem/workflows/verify-work.md

@@ -6,6 +6,7 @@ Complete verify-and-fix session: by session end, everything verified, issues fix
 
 <execution_context>
 <!-- mock-patterns.md loaded on demand for transient_state mocks (see generate_mocks step) -->
+<!-- knowledge files loaded on first fix attempt (see investigate_issue step) -->
 </execution_context>
 
 <process>
@@ -74,7 +75,8 @@ Provide a phase number to start testing (e.g., /ms:verify-work 4)
 **Find SUMMARY.md files for the phase:**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
+ms-tools find-phase "${PHASE_ARG}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
 ```
 
@@ -341,6 +343,19 @@ Progress auto-recalculates on every `uat-update` call. No manual progress recalc
 <step name="investigate_issue">
 **Investigate reported issue:**
 
+**0. Load knowledge (first issue only):**
+
+If this is the first issue requiring investigation in this session, load knowledge files now. On subsequent issues, knowledge is already in context — skip to step 1.
+
+```bash
+ms-tools config-get subsystems
+grep "^subsystem:" "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+Match SUMMARY.md subsystem values against config subsystems. Read matching `.planning/knowledge/{subsystem}.md` files (1-3 most relevant).
+
+This knowledge informs investigation (where to look, known pitfalls) and any subsequent fixes.
+
 **1. Lightweight investigation (2-3 tool calls):**
 
 ```
@@ -440,6 +455,10 @@ You are a Mindsystem verify-fixer. Investigate this issue, find the root cause,
 
 {lightweight_investigation_results}
 
+## Knowledge Context
+
+{loaded_knowledge_content or "No knowledge files loaded for this session."}
+
 ## Your task
 
 1. Investigate to find root cause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.2.1",
+  "version": "4.3.0",
   "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/scripts/ms-tools.py

@@ -1198,6 +1198,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
 
     # ---- CHECK 11: Browser Verification ----
     print("=== Browser Verification ===")
+    is_web, web_signal = False, "not checked"
     bv_enabled = True
     bv_config = config.get("browser_verification", {})
     if isinstance(bv_config, dict):
@@ -1233,6 +1234,28 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
                 record("PASS", "Browser Verification")
     print()
 
+    # ---- CHECK 12: Screenshot Optimization ----
+    print("=== Screenshot Optimization ===")
+    if not bv_enabled:
+        print("Status: SKIP")
+        print("Browser verification disabled")
+        record("SKIP", "Screenshot Optimization")
+    elif not is_web:
+        print("Status: SKIP")
+        print(f"Not a web project ({web_signal})")
+        record("SKIP", "Screenshot Optimization")
+    else:
+        if shutil.which("cwebp"):
+            print("Status: PASS")
+            print("cwebp available — screenshots will be converted to WebP")
+            record("PASS", "Screenshot Optimization")
+        else:
+            print("Status: WARN")
+            print("cwebp not found — browser screenshots will remain as PNG (larger files)")
+            print("Install: brew install webp | apt install webp | choco install webp")
+            record("WARN", "Screenshot Optimization")
+    print()
+
     # ---- SUMMARY ----
     total = pass_count + warn_count + fail_count + skip_count
     print("=== Summary ===")
@@ -3126,7 +3149,7 @@ def _load_uat(args_phase: str) -> tuple[Path, "UATFile"]:
     if phase_dir is None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)
@@ -3166,7 +3189,7 @@ def cmd_uat_init(args: argparse.Namespace) -> None:
     phase_name = phase_dir.name
     uat = UATFile.from_init_json(data, phase_name)
 
-    out_path = phase_dir / f"{phase_name}-UAT.md"
+    out_path = phase_dir / f"{phase}-UAT.md"
     out_path.write_text(uat.serialize(), encoding="utf-8")
 
     n_tests = len(uat.tests)
@@ -3196,7 +3219,7 @@ def cmd_uat_update(args: argparse.Namespace) -> None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
 
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)
@@ -3264,7 +3287,7 @@ def cmd_uat_status(args: argparse.Namespace) -> None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
 
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)