mindsystem-cc 4.1.2 → 4.2.1

package/agents/ms-browser-verifier.md

@@ -0,0 +1,137 @@
+---
+name: ms-browser-verifier
+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:
+  - agent-browser
+color: green
+---
+
+<role>
+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:** 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>
+
+<step name="start_dev_server">
+Check if dev server is already running by probing common ports (5173, 3000, 8080, 4200, 3001).
+
+If not running:
+1. Read `package.json` scripts for dev command (`dev`, `start`, `serve`)
+2. Start via `npm run {script}` or `yarn {script}` based on lock file presence
+3. Retry port probe with backoff (1s, 2s, 4s) until ready or timeout (30s)
+</step>
+
+<step name="check_auth_state">
+Auth is handled by the orchestrator before spawning this agent. If the orchestrator provides a storage state file path, load it when launching the browser to restore the authenticated session.
+
+Open the app URL headless. If redirected to login, report auth failure and exit — do not attempt to automate auth.
+</step>
+
+<step name="environment_preflight">
+Navigate to the app's main route. Screenshot `00-preflight.png`.
+
+Evaluate:
+- Does the app load?
+- Visible backend errors? Console errors? Blank page?
+
+**If systemic issue** (app won't load, white screen, critical error):
+- Screenshot the failure
+- Return `environment_blocked` report to orchestrator with screenshot evidence
+- Stop — no point testing individual items
+
+**If app loads with minor warnings:**
+- Note warnings and proceed to checklist verification
+</step>
+
+<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 checklist item:
+
+```
+Navigate to route → Screenshot → Evaluate
+
+Match expected?
+YES → PASSED, next item
+NO → Environment issue? (API error, 404, empty data, console network errors)
+     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
+          → 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
+```
+
+**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)
+
+**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. Return a structured report to the orchestrator:
+
+```
+## Browser Verification Report
+
+**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} | Commit: {hash}
+
+### Issues Found
+- {description} | Screenshot: {filename} | Evidence: {what the screenshot shows}
+
+### Environment Blockers
+- {description} | Screenshot: {filename}
+```
+</step>
+
+</process>
+
+<rules>
+
+## Screenshots
+- 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
+
+## 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
+- 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/bin/install.js

@@ -25,9 +25,8 @@ ${cyan}   ███╗   ███╗██╗███╗   ██╗███
    ╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝   ╚═╝   ╚══════╝   ╚═╝   ╚══════╝╚═╝     ╚═╝${reset}
 
   Mindsystem ${dim}v${pkg.version}${reset}
-  A meta-prompting, context engineering and spec-driven
-  development system for Claude Code by Roland Tolnay.
-  Based on GSD by TÂCHES.
+  The engineer's meta-prompting system for Claude Code.
+  Amplify your workflow. Compound your knowledge.
 `;
 
 // Parse args

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

@@ -202,7 +202,7 @@ Skip code review step (proceed to next steps).
 ```bash
 # Find first commit in milestone (first phase commit)
 FIRST_PHASE=$(ls -d .planning/phases/*/ | sort -V | head -1 | xargs basename | cut -d- -f1)
-FIRST_COMMIT=$(git log --oneline --grep="(${FIRST_PHASE}-" --format="%H" | tail -1)
+FIRST_COMMIT=$(ms-tools find-phase-commits ${FIRST_PHASE} | tail -1)
 
 # Get all implementation files changed since first commit
 CHANGED_FILES=$(git diff --name-only ${FIRST_COMMIT}^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
@@ -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/config.md

@@ -1,6 +1,6 @@
 ---
 name: ms:config
-description: Configure Mindsystem preferences — code reviewers, mockups, gitignore, git remote, task tracker
+description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, gitignore, git remote, task tracker
 allowed-tools:
   - Read
   - Write
@@ -12,7 +12,7 @@ allowed-tools:
 
 Configure Mindsystem preferences for the current project.
 
-Manages code reviewer agents, mockup preferences, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
+Manages code reviewer agents, mockup preferences, browser verification, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
 
 </objective>
 
@@ -33,6 +33,36 @@ Manages code reviewer agents, mockup preferences, .gitignore patterns for `.plan
 git remote -v 2>/dev/null || echo "NO_REMOTE"
 ```
 
+**Determine mode** from `code_review` values in config.json:
+
+- **Setup mode** — all `code_review` values are null (or no config file): first-time configuration.
+- **Edit mode** — any `code_review` value is non-null: reconfiguration.
+
+</step>
+
+<step name="route">
+
+**Setup mode:** Proceed through all setting steps sequentially (git_remote → code_reviewers → gitignore_patterns → mockup_preferences → browser_verification → task_tracker). Then go to `validation_summary`.
+
+**Edit mode:** Display all current settings with values from config.json, git remote, and .gitignore:
+
+```
+## Current Settings
+
+1. **Git remote** — {remote URL or "none configured"}
+2. **Code reviewers** — adhoc: {value or "not set"}, phase: {value or "not set"}, milestone: {value or "not set"}
+3. **Gitignore** — {current .planning/ patterns or "no .planning/ patterns"}
+4. **Mockups** — open: {auto / ask / off}
+5. **Browser verification** — {enabled / disabled}
+6. **Task tracker** — {type + cli path, or "none"}
+```
+
+Ask: "Which settings would you like to change? Enter the numbers (e.g. 1, 3, 5), 'all' to reconfigure everything, or 'done' if everything looks good."
+
+- **"done"** → skip to `validation_summary` (no changes)
+- **"all"** → proceed through all setting steps sequentially
+- **Specific numbers** → proceed through only the corresponding setting steps, skip the rest
+
 </step>
 
 <step name="git_remote">
@@ -100,12 +130,14 @@ Use AskUserQuestion (multiSelect):
 - options:
   - "Phase patch files (`.planning/phases/**/*.patch`)" — Large binary diffs, regeneratable
   - "Design mockups (`.planning/phases/**/*.html`)" — Generated HTML mockups from design-phase
+  - "Browser screenshots (`.planning/phases/**/screenshots/`)" — Browser verification screenshots
 
 Apply selected patterns to `.gitignore`. Create the file if needed:
 
 ```bash
-echo '.planning/phases/**/*.patch' >> .gitignore  # if selected
-echo '.planning/phases/**/*.html' >> .gitignore   # if selected
+echo '.planning/phases/**/*.patch' >> .gitignore       # if selected
+echo '.planning/phases/**/*.html' >> .gitignore        # if selected
+echo '.planning/phases/**/screenshots/' >> .gitignore  # if selected
 ```
 
 If no selections: skip gitignore changes.
@@ -142,6 +174,34 @@ ms-tools config-set open_mockups "$VALUE"
 
 </step>
 
+<step name="browser_verification">
+
+Read current value:
+
+```bash
+CURRENT=$(ms-tools config-get browser_verification.enabled --default "true")
+echo "Current browser_verification.enabled: $CURRENT"
+```
+
+Use AskUserQuestion:
+- header: "Browser verification"
+- question: "Enable automated browser verification during execute-phase? (Tests your web UI after code changes)"
+- options:
+  - "Enabled (Recommended)" — Automatically test web UI after phase execution
+  - "Disabled" — Skip browser verification
+
+Map selection:
+- "Enabled" → `true`
+- "Disabled" → `false`
+
+Update config.json:
+
+```bash
+ms-tools config-set browser_verification --json '{"enabled": true}'   # or false
+```
+
+</step>
+
 <step name="task_tracker">
 
 Read current value:
@@ -193,6 +253,7 @@ Configuration updated:
 
 - Code reviewers: [adhoc / phase / milestone values]
 - Mockup open: [auto / ask / off]
+- Browser verification: [enabled / disabled]
 - Gitignore: [patterns added, or "no changes"]
 - Git remote: [remote URL, or "none configured"]
 - Task tracker: [type + cli path, or "none"]
@@ -207,38 +268,26 @@ 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>
 
-<step name="done">
-
-Present next steps using the "Next Up" format:
-
-- **If PROJECT.md exists:** recommend `/ms:new-milestone` — Discover what to build next, create requirements and roadmap
-- **If no PROJECT.md:** recommend `/ms:new-project` — Initialize project with business context and vision
-
-Also list: `/ms:doctor` — Verify subsystems and artifact health
-
-</step>
-
 </process>
 
 <success_criteria>
 
+- [ ] Setup mode triggered when all code_review values null; edit mode otherwise
+- [ ] Edit mode displays numbered settings with current values
+- [ ] Only user-selected settings modified in edit mode
 - [ ] Changes committed (if any)
-- [ ] User routed to next step
 - [ ] Gitignore patterns applied (if selected)
 - [ ] Git remote offered (if missing)
 - [ ] Validation summary displayed
-- [ ] Config.json code_review values set (or preserved if skipped)
-- [ ] Config.json open_mockups value set (or preserved if skipped)
-- [ ] Config.json task_tracker value set (or preserved if skipped)
+- [ ] Terminates after commit/summary — no Next Up routing
 
 </success_criteria>

package/commands/ms/create-roadmap.md

@@ -271,7 +271,8 @@ Return ROADMAP REVISED with changes made.
 </step>
 
 <step name="commit">
-After user approval:
+
+**Update state and commit:**
 
 ```bash
 git add .planning/REQUIREMENTS.md .planning/ROADMAP.md .planning/STATE.md
@@ -292,6 +293,18 @@ EOF
 ```
 </step>
 
+<step name="create_phase_dirs">
+
+**Update state and commit:**
+
+```bash
+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>
+
 <step name="done">
 ```
 Requirements and roadmap created:
@@ -305,12 +318,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

@@ -373,10 +373,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 .planning/phases/${PHASE}-*/*-DESIGN.md .planning/STATE.md
 git commit -m "docs: create design for phase ${PHASE}"
 ```
 
@@ -431,12 +432,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/doctor.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 
 <objective>
-Run health checks on project configuration. Detect and fix structural drift across 10 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, and Mindsystem version.
+Run health checks on project configuration. Detect and fix structural drift across 12 categories: subsystem vocabulary, milestone directory structure, milestone naming convention, phase archival, knowledge files, phase summaries, PLAN cleanup, CLI wrappers and environment diagnostics, research API keys, phase directory naming, browser verification prerequisites, and Mindsystem version.
 
 Idempotent.
 </objective>
@@ -119,6 +119,8 @@ Display results as a markdown table:
 | PLAN cleanup             | FAIL   | 9 leftover PLAN.md files         |
 | CLI wrappers             | FAIL   | Not resolvable; bin dir not in PATH |
 | Research API Keys        | WARN   | PERPLEXITY_API_KEY not set        |
+| Phase directory naming   | FAIL   | 1 non-canonical directory         |
+| Browser Verification     | WARN   | Web project, missing agent-browser CLI |
 | Mindsystem version       | WARN   | v3.21.0 → v3.22.1 available       |
 ```
 
@@ -141,7 +143,7 @@ If "Skip" → go to `report`.
 
 If "Review each" → use AskUserQuestion for each failed check with its details and options: "Fix" / "Skip". Only run fixes for accepted checks.
 
-Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_knowledge. Skip any fix whose check passed or was skipped by user.
+Apply fixes in dependency order: fix_subsystems → fix_milestone_dirs → fix_milestone_naming → fix_phase_archival → fix_plan_cleanup → fix_phase_dirs → fix_knowledge. Skip any fix whose check passed or was skipped by user.
 
 Phase summaries are resolved by fix_phase_archival. CLI wrapper failures have specific fixes: bin dir not in PATH → restart Claude Code session; missing wrappers or bin dir → re-run `npx mindsystem-cc`; uv not found → `curl -LsSf https://astral.sh/uv/install.sh | sh`. WARN checks (Research API Keys, missing uv) are informational — no automated fix, only displayed in the report.
 </step>
@@ -179,6 +181,8 @@ Final summary table:
 | PLAN cleanup             | PASS   | ...                              |
 | CLI wrappers             | PASS   | ...                              |
 | Research API Keys        | PASS   | ...                              |
+| Phase directory naming   | PASS   | ...                              |
+| Browser Verification     | PASS   | ...                              |
 | Mindsystem version       | PASS   | ...                              |
 
 All checks passed.
@@ -195,6 +199,6 @@ Include counts: checks total, passed, warned, fixed during this run.
 - [ ] Re-scan verifies all checks pass after fixes
 - [ ] Each fix group committed atomically
 - [ ] Fixes applied in dependency order: subsystems → dirs → milestone naming → archival → cleanup → knowledge
-- [ ] All 10 categories reported with PASS/FAIL/WARN/SKIP
+- [ ] All 12 categories reported with PASS/FAIL/WARN/SKIP
 - [ ] Clean project reports all PASS with no fix prompts
 </success_criteria>

package/commands/ms/execute-phase.md

@@ -77,29 +77,35 @@ ms-tools find-phase "$ARGUMENTS"
      - `passed` → continue to step 7
      - `gaps_found` → present gaps, route via gap-closure-routing.md triage
 
-7. **Code review (optional)**
+7. **Browser verification (web projects)**
+   - Run `ms-tools browser-check` for prerequisites
+   - If ready: handle auth, spawn `ms-browser-verifier` for functional testing
+   - Verifier tests observable truths in browser, fixes issues inline
+   - If skipped: not a web project or browser verification disabled
+
+8. **Code review (optional)**
    - Read `code_review.phase` from config.json (default: `ms-code-simplifier`)
-   - If `"skip"`: proceed to step 8
+   - If `"skip"`: proceed to step 9
    - Spawn code review agent with phase file scope
    - If changes made: commit as `refactor({phase}): code review improvements`
 
-8. **Generate phase patch**
+9. **Generate phase patch**
    - Run: `ms-tools generate-phase-patch ${PHASE_NUMBER}`
    - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
    - Verify: patch file exists OR skip message logged
    - Note: Patch captures all changes including simplifications
 
-9. **Consolidate knowledge**
-   - Spawn `ms-consolidator` with phase directory and number
-   - Consolidator reads phase artifacts and existing knowledge files
-   - Produces updated `.planning/knowledge/{subsystem}.md` files
-   - Deletes PLAN.md files (execution instructions consumed)
-   - Verify: knowledge files written to `.planning/knowledge/`
+10. **Consolidate knowledge**
+    - Spawn `ms-consolidator` with phase directory and number
+    - Consolidator reads phase artifacts and existing knowledge files
+    - Produces updated `.planning/knowledge/{subsystem}.md` files
+    - Deletes PLAN.md files (execution instructions consumed)
+    - Verify: knowledge files written to `.planning/knowledge/`
 
-10. **Update roadmap and state**
+11. **Update roadmap and state**
     - Update ROADMAP.md, STATE.md
 
-11. **Update requirements**
+12. **Update requirements**
     Mark phase requirements as Complete:
     - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
     - Read REQUIREMENTS.md traceability table
@@ -107,18 +113,16 @@ ms-tools find-phase "$ARGUMENTS"
     - Write updated REQUIREMENTS.md
     - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
 
-12. **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`
     - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
     - Commit: `docs({phase}): complete {phase-name} phase`
 
-13. **Offer next steps**
+14. **Offer next steps**
     - Route to next action (see `<offer_next>`)
-
-14. **Update last command:** `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
 </process>
 
 <offer_next>
@@ -141,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.
 
 ---
 
@@ -155,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
+```
 
 ---
 
@@ -247,6 +274,7 @@ After all plans in phase complete:
 - [ ] All incomplete plans in phase executed
 - [ ] Code review completed (or skipped if config says "skip")
 - [ ] Phase goal verified (Must-Haves checked against codebase)
+- [ ] Browser verification completed or skipped (non-web/disabled)
 - [ ] VERIFICATION.md created in phase directory
 - [ ] Patch file generated OR explicitly skipped with message
 - [ ] Knowledge files written to .planning/knowledge/ (consolidation complete)

package/commands/ms/map-codebase.md

@@ -58,9 +58,8 @@ Check for .planning/STATE.md - loads context if project already initialized
    - Agent 4: concerns focus → writes CONCERNS.md
 4. Wait for agents to complete, collect confirmations (NOT document contents)
 5. Verify all 7 documents exist with line counts
-6. Commit codebase map
+6. Update last command and commit codebase map (together with STATE.md)
 7. Offer next steps (adapts: /ms:new-project if no PROJECT.md, /ms:doctor if PROJECT.md exists)
-8. **Update last command:** `ms-tools set-last-command "ms:map-codebase $ARGUMENTS"`
 </process>
 
 <success_criteria>

package/commands/ms/new-milestone.md

@@ -254,14 +254,12 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
     Keep Accumulated Context (decisions, blockers) from previous milestone.
 
-17. **Git commit:**
+17. **Update state and commit:**
 
     ```bash
+    ms-tools set-last-command "ms:new-milestone $ARGUMENTS"
     git add .planning/PROJECT.md .planning/STATE.md .planning/MILESTONE-CONTEXT.md
-    git commit -m "$(cat <<'EOF'
-    docs: start milestone [Name]
-    EOF
-    )"
+    git commit -m "docs: start milestone [Name]"
     ```
 
 18. **Calculate next phase number:**
@@ -302,8 +300,6 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
     ---
     ```
 
-20. **Update last command:** `ms-tools set-last-command "ms:new-milestone $ARGUMENTS"`
-
 </process>
 
 <success_criteria>