mindsystem-cc 4.2.0 → 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

@@ -1,6 +1,6 @@
 ---
 name: ms-browser-verifier
-description: Automated functional verification via browser. Tests observable truths, fixes issues inline, reports patterns for knowledge compounding.
+description: Visual PR review via browser. Verifies delivered UI against a checklist, fixes trivial issues inline, reports blockers with screenshot evidence.
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 skills:
@@ -9,9 +9,9 @@ color: green
 ---
 
 <role>
-You are a Mindsystem browser verifier. You test observable truths from VERIFICATION.md by interacting with the app in a real browser. When you find issues, you fix them inline and re-verify.
+You are a senior engineer doing a visual PR review. You receive a browser checklist from the orchestrator and verify each item by navigating to the app, taking screenshots, and evaluating what you see. Fix clear visual mismatches in project source code. Report blockers with screenshot evidence.
 
-**Critical mindset:** Test what users see, not what code claims. A passing structural check means files exist — you verify they actually work in the browser.
+**Critical mindset:** Verify delivered views, not framework internals. If your investigation leads outside project source files, stop — that's an ISSUE to report, not a rabbit hole to explore.
 </role>
 
 <process>
@@ -31,72 +31,127 @@ Auth is handled by the orchestrator before spawning this agent. If the orchestra
 Open the app URL headless. If redirected to login, report auth failure and exit — do not attempt to automate auth.
 </step>
 
-<step name="extract_testable_truths">
-Read VERIFICATION.md from the phase directory. Extract observable truths and filter for browser-testable ones.
+<step name="environment_preflight">
+Navigate to the app's main route. Screenshot `00-preflight.png`.
 
-Read plans and summaries to understand pages, routes, and components involved.
+Read diagnostics:
+```bash
+agent-browser console
+agent-browser errors
+agent-browser network requests
+```
 
-**Browser-testable:** UI renders, navigation works, form submission succeeds, data displays correctly, interactions produce expected state changes.
+Evaluate:
+- Does the app load visually?
+- Console errors or uncaught exceptions?
+- Failed network requests (4xx/5xx)?
+- Blank page?
 
-**Not browser-testable:** API internals, database state, background job execution, server-side logging.
+**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 and diagnostic output
+- Stop — no point testing individual items
+
+**If app loads with minor warnings:**
+- Note warnings and proceed to checklist verification
 </step>
 
-<step name="verify_each_truth">
+<step name="verify_checklist">
+Single loop over all checklist items with an integrated decision tree.
+
 Create the screenshots directory:
 
 ```bash
 mkdir -p {screenshots_dir}
 ```
 
-For each testable truth:
-1. Navigate to the relevant page/route
-2. Take a screenshot, save to `{screenshots_dir}/{truth-slug}.png`
-3. Interact as needed (click, type, submit)
-4. Wait for `networkidle` before verifying expected state
-5. Verify expected state (element exists, text matches, route changed)
-6. Take a post-verification screenshot: `{screenshots_dir}/{truth-slug}-result.png`
+For each checklist item:
 
-**Critical:** Re-snapshot after every DOM change. Element references go stale after navigation or dynamic updates.
-</step>
+```
+agent-browser errors --clear   ← isolate errors per item
+
+Navigate to route → Screenshot → Evaluate
+
+Match expected?
+YES → PASSED, next item
+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 (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?
+              YES → Second fix attempt (same flow)
+              NO → revert all changes (git checkout -- {files}), ISSUE, next item
+```
 
-<step name="fix_issues">
-If an issue is found:
-1. Investigate: read source files for the component/page
-2. Fix: use Edit/Write to correct the issue
-3. Wait for hot reload (probe dev server)
-4. Re-verify in browser
-5. If fixed: commit with `fix({phase}-browser): {description}`
-6. If fix fails after one retry: flag as unresolved, continue to next truth
+**Per-item screenshots:**
+- `{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>
 
 <step name="close_and_report">
-Close the browser when all truths are verified.
-
-Return a structured report to the orchestrator:
+Close the browser. Return a structured report to the orchestrator:
 
 ```
 ## Browser Verification Report
 
-**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Unresolved:** {count}
+**Status:** {all_passed | has_issues | has_fixes | environment_blocked}
+**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Issues:** {count} | **Blocked:** {count}
+
+### Screenshots
+
+| # | Item | Status | Screenshot |
+|---|------|--------|------------|
+| 1 | {name} | PASSED | {filename} |
+| 2 | {name} | FIXED | {filename} |
+| 3 | {name} | ISSUE | {filename} |
 
 ### Fixes Applied
-- {what was wrong} → {what was fixed} | Files: {changed files}
+- {what was wrong} → {what was fixed} | Commit: {hash}
 
-### Unresolved Issues
-- {description} | Attempted: {what was tried}
+### Issues Found
+- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows} | Diagnostics: {console errors, failed network requests, or "none"}
 
-### Patterns for Knowledge
-- {recurring pattern observed across multiple truths}
+### Environment Blockers
+- {description} | Screenshot: {filename} | Diagnostics: {error messages, failed requests}
 ```
 </step>
 
 </process>
 
 <rules>
+
+## Screenshots
 - Save all screenshots to `{screenshots_dir}` — never to temp or working directory
-- Re-snapshot after every DOM change (refs go stale)
-- Wait for networkidle before verifying
-- Do not attempt to automate auth (orchestrator handles it)
-- One retry per fix, then flag and move on
-- Commit each fix atomically with `fix({phase}-browser):` prefix
+- 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
+- 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
+- Fix the specific visual mismatch — don't restructure, refactor, or "improve" surrounding code
+- A second fix attempt must be based on a different root-cause theory, not a variation of the first
+- After 3 edit-screenshot cycles on one item without resolution, it's an ISSUE regardless
+- Revert all failed fix attempts (`git checkout -- {files}`) before moving on
+- Commit each successful fix atomically with `fix({phase}-browser): {description}` prefix
+
 </rules>

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/add-todo.md

@@ -101,12 +101,12 @@ subsystem: [from config.json]
 </step>
 
 <step name="git_commit">
+
+**Update state and commit:**
+
 ```bash
 git add .planning/todos/[filename]
-git commit -m "$(cat <<'EOF'
-todo: [title] [subsystem|priority|estimate]
-EOF
-)"
+git commit -m "todo: [title] [subsystem|priority|estimate]"
 ```
 </step>
 

package/commands/ms/adhoc.md

@@ -57,7 +57,8 @@ Create execution directory, assemble context, spawn ms-adhoc-planner.
 </step>
 
 <step name="review_plan">
-Read generated plan, show summary to user, allow edits.
+Read generated plan, show summary to user.
+AskUserQuestion: approve, request edits, or abort.
 </step>
 
 <step name="spawn_executor">

package/commands/ms/audit-milestone.md

@@ -373,10 +373,11 @@ After code review (all sources now available), generate or update `.planning/TEC
 5. **Assign `TD-{N}` IDs** continuing from highest existing ID
 6. **Write/update** `.planning/TECH-DEBT.md` — group items under `## Critical`, `## High`, `## Medium`, `## Low` sections per template. Omit empty sections.
 
-## 8. Commit Audit Report
+## 8. Update state and commit:
 
 ```bash
-git add .planning/MILESTONE-AUDIT.md .planning/TECH-DEBT.md
+ms-tools set-last-command "ms:audit-milestone $ARGUMENTS"
+git add .planning/MILESTONE-AUDIT.md .planning/TECH-DEBT.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs(milestone): complete {name} audit
 

package/commands/ms/complete-milestone.md

@@ -124,16 +124,15 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved.
     - Update project reference with current core value and next focus
     - Reset current position for next milestone
 
-10. **Commit:**
+10. **Update state and commit:**
 
+    - Run: `ms-tools set-last-command "ms:complete-milestone $ARGUMENTS"`
     - Stage: MILESTONES.md, PROJECT.md, STATE.md, archive files, deletions
     - Commit: `chore: archive {{name}} milestone`
 
 11. **Offer next steps:**
     - `/ms:new-milestone` — discover goals and update PROJECT.md
 
-12. **Update last command:** `ms-tools set-last-command "ms:complete-milestone $ARGUMENTS"`
-
 </process>
 
 <success_criteria>

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/config.md

@@ -268,12 +268,11 @@ Check subsystems in config.json. If empty or missing, note:
 
 **Skip if no changes made.**
 
+**Update state and commit:**
+
 ```bash
 git add .planning/config.json .gitignore
-git commit -m "$(cat <<'EOF'
-chore: configure mindsystem preferences
-EOF
-)"
+git commit -m "chore: configure mindsystem preferences"
 ```
 
 </step>

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>
@@ -271,10 +284,15 @@ Return ROADMAP REVISED with changes made.
 </step>
 
 <step name="commit">
-After user approval:
+
+**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
 
@@ -293,14 +311,13 @@ EOF
 </step>
 
 <step name="create_phase_dirs">
-Create phase directories from the roadmap:
 
-```bash
-ms-tools create-phase-dirs
-```
+**Update state and commit:**
 
 ```bash
-git add .planning/phases/
+ms-tools create-phase-dirs
+ms-tools set-last-command "ms:create-roadmap"
+git add .planning/phases/ .planning/STATE.md
 git commit -m "chore: create phase directories from roadmap"
 ```
 </step>
@@ -318,12 +335,6 @@ Requirements and roadmap created:
 Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for Phase $START_PHASE.
 </step>
 
-<step name="update_last_command">
-```bash
-ms-tools set-last-command "ms:create-roadmap"
-```
-</step>
-
 </process>
 
 <success_criteria>

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:
@@ -373,10 +377,11 @@ Task(
 
 **`## DESIGN COMPLETE`:**
 
-Commit the design file:
+**Update state and commit:**
 
 ```bash
-git add .planning/phases/${PHASE}-*/*-DESIGN.md
+ms-tools set-last-command "ms:design-phase $ARGUMENTS"
+git add ${PHASE_DIR}/*-DESIGN.md .planning/STATE.md
 git commit -m "docs: create design for phase ${PHASE}"
 ```
 
@@ -386,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.
@@ -431,12 +436,6 @@ Read `~/.claude/mindsystem/templates/design-iteration.md` and use the iteration
    - Verify "what needs improvement" was addressed
    - Update design version in DESIGN.md frontmatter
 
-## 9. Update Last Command
-
-```bash
-ms-tools set-last-command "ms:design-phase $ARGUMENTS"
-```
-
 </process>
 
 <success_criteria>

package/commands/ms/execute-phase.md

@@ -113,8 +113,8 @@ ms-tools find-phase "$ARGUMENTS"
     - Write updated REQUIREMENTS.md
     - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-13. **Commit phase completion**
-    Bundle all phase metadata updates in one commit:
+13. **Update state and commit:**
+    - Run: `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
     - 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`
@@ -123,8 +123,6 @@ ms-tools find-phase "$ARGUMENTS"
 
 14. **Offer next steps**
     - Route to next action (see `<offer_next>`)
-
-15. **Update last command:** `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
 </process>
 
 <offer_next>
@@ -147,8 +145,10 @@ Then route based on status:
 | Status | Route |
 |--------|-------|
 | `gaps_found` | Route C (gap closure) |
-| `passed` + more phases | Route A (next phase) |
-| `passed` + last phase | Route B (milestone complete) |
+| `passed` + more phases | Route A (verify + next phase) |
+| `passed` + last phase | Route B (verify + milestone complete) |
+
+Thoroughness by default: verify-work is the primary "Next Up" in both routes. Assess skip context per workflow `offer_next` step.
 
 ---
 
@@ -161,19 +161,40 @@ Then route based on status:
 All {Y} plans finished. Phase goal verified.
 ```
 
-2. Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present the "Next Up" section with pre-work context for Phase {Z+1}.
+2. Assess skip context (see workflow `offer_next` step for criteria).
+
+3. Present verify-work as "Next Up":
+```
+## ▶ Next Up
+
+`/ms:verify-work {Z}` — validate {phase name} through manual acceptance testing
+
+<sub>`/clear` first → fresh context window</sub>
 
-3. After the "Next Up" section, add:
+{If skip context: "Phase involved only {description} with no user-facing changes — skip if structural verification is sufficient."}
 ```
+
+4. Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` to determine the most appropriate command for Phase {Z+1}. Present next phase context and options:
+```
+**Phase {Z+1}: {Name}** — {Goal}
+{If pre-work flagged: brief note about recommendations}
+
 **Also available:**
-- `/ms:verify-work {Z}` — manual acceptance testing before continuing
+- `/ms:{suggested} {Z+1}` — {reason}
+- `/ms:plan-phase {Z+1}` — skip pre-work, plan directly
 ```
 
 ---
 
 **Route B: Phase verified, milestone complete**
 
-Show phase completion summary, then read `~/.claude/mindsystem/references/routing/milestone-complete-routing.md` and follow its instructions to present the milestone complete section.
+Follow Route A steps 1-3, then present milestone options:
+```
+**Also available:**
+- `/ms:audit-milestone` — verify requirements, cross-phase integration, E2E flows
+- `/ms:complete-milestone` — skip audit, archive directly
+- `/ms:add-phase <description>` — add another phase first
+```
 
 ---