mindsystem-cc 4.2.0 → 4.2.1

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,107 @@ 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.
+Evaluate:
+- Does the app load?
+- Visible backend errors? Console errors? Blank page?
 
-**Browser-testable:** UI renders, navigation works, form submission succeeds, data displays correctly, interactions produce expected state changes.
+**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
 
-**Not browser-testable:** API internals, database state, background job execution, server-side logging.
+**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>
+```
+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)
 
-<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
+**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}
 
-### Patterns for Knowledge
-- {recurring pattern observed across multiple truths}
+### 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 (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
+
+## 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/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/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

@@ -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
@@ -293,14 +294,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 +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/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
+```
 
 ---
 

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>

package/commands/ms/new-project.md

@@ -195,9 +195,11 @@ These values are used throughout the system for consistent categorization of sum
 
 <step name="commit">
 
-**First run:**
+**First run — update state and commit:**
 ```bash
+ms-tools set-last-command "ms:new-project"
 git add .planning/PROJECT.md .planning/config.json
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs: initialize [project-name]
 
@@ -208,9 +210,10 @@ EOF
 )"
 ```
 
-**Update mode:**
+**Update mode — update state and commit:**
 ```bash
-git add .planning/PROJECT.md .planning/config.json
+ms-tools set-last-command "ms:new-project"
+git add .planning/PROJECT.md .planning/config.json .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs: update [project-name] project context
 
@@ -268,12 +271,6 @@ Project updated:
 
 </step>
 
-<step name="update_last_command">
-```bash
-ms-tools set-last-command "ms:new-project"
-```
-</step>
-
 </process>
 
 <output>

package/commands/ms/remove-phase.md

@@ -259,14 +259,13 @@ Update any internal references to reflect new numbering.
 </step>
 
 <step name="commit">
-Stage and commit the removal:
+**Update state and commit:**
 
 ```bash
+ms-tools set-last-command "ms:remove-phase $ARGUMENTS"
 git add .planning/
 git commit -m "chore: remove phase {target} ({original-phase-name})"
 ```
-
-The commit message preserves the historical record of what was removed.
 </step>
 
 <step name="completion">
@@ -297,12 +296,6 @@ Would you like to:
 ```
 </step>
 
-<step name="update_last_command">
-```bash
-ms-tools set-last-command "ms:remove-phase $ARGUMENTS"
-```
-</step>
-
 </process>
 
 <anti_patterns>

package/commands/ms/research-milestone.md

@@ -285,10 +285,11 @@ Write Executive Summary (2-3 paragraphs) synthesizing all findings.
 
 Merge overlapping findings. Resolve conflicts by preferring higher-confidence sources.
 
-## 7. Present Results and Commit
+## 7. Update state and commit:
 
 ```bash
-git add .planning/MILESTONE-RESEARCH.md
+ms-tools set-last-command "ms:research-milestone"
+git add .planning/MILESTONE-RESEARCH.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs: complete milestone research
 
@@ -320,12 +321,6 @@ Key findings:
 ---
 ```
 
-## 8. Update Last Command
-
-```bash
-ms-tools set-last-command "ms:research-milestone"
-```
-
 </process>
 
 <success_criteria>

package/commands/ms/research-phase.md

@@ -300,10 +300,11 @@ After all 3 agents return, read their structured outputs. Map findings to RESEAR
 
 Write RESEARCH.md to `.planning/phases/{phase}-{slug}/{phase}-RESEARCH.md` using the standard template structure (semantic XML tags: `<research_summary>`, `<standard_stack>`, `<architecture_patterns>`, `<dont_hand_roll>`, `<common_pitfalls>`, `<code_examples>`, `<sota_updates>`, `<open_questions>`, `<sources>`, `<metadata>`).
 
-## 7. Commit and Present
+## 7. Update state and commit:
 
 ```bash
-git add .planning/phases/${PHASE}-*/*-RESEARCH.md
+ms-tools set-last-command "ms:research-phase $ARGUMENTS"
+git add .planning/phases/${PHASE}-*/*-RESEARCH.md .planning/STATE.md
 git commit -m "docs: complete research for phase ${PHASE}"
 ```
 
@@ -324,12 +325,6 @@ If any section has LOW confidence or significant open questions, flag the weak a
 3. Proceed to planning with caveats noted
 4. Review full research
 
-## 8. Update Last Command
-
-```bash
-ms-tools set-last-command "ms:research-phase $ARGUMENTS"
-```
-
 </process>
 
 <checkpoint_handling>

package/mindsystem/references/browser-verification.md

@@ -32,7 +32,7 @@ Store the result as `{dev_url}`.
 If `HAS_STATE`:
 1. Open app headless at `{dev_url}`
 2. Check current URL — if redirected to a login/auth path, auth has expired
-3. If still on app pages: auth valid, proceed to Spawn
+3. If still on app pages: auth valid, proceed to Derive Browser Checklist
 
 If `NO_STATE` or auth expired:
 1. Close headless browser
@@ -47,30 +47,97 @@ If `NO_STATE` or auth expired:
    ```
 5. If user skips: proceed to code_review, skip browser verification
 
+## Derive Browser Checklist
+
+Transform SUMMARY.md accomplishments into a structured checklist for the browser verifier.
+
+**Step 1: Read summaries**
+
+Read all `*-SUMMARY.md` files from the phase directory.
+
+**Step 2: Extract per-summary**
+
+For each SUMMARY, extract:
+- **Accomplishments** section
+- **mock_hints** frontmatter (if present) — specifically `external_data` entries
+- **key-files** frontmatter (if present) — for route inference
+
+**Step 3: Derive checklist items**
+
+For each user-observable accomplishment, derive:
+- `name`: brief description of what to verify
+- `route`: URL path (infer from key-files paths, routing config, or component names)
+- `expected`: what should be visible on screen (be specific — "table with columns X, Y, Z", not "data displays")
+- `interaction`: optional action + expected result (e.g., "click Add button → modal opens with form fields A, B, C")
+- `needs_backend_data`: true/false (from mock_hints `external_data` entries)
+
+**Step 4: Filter**
+
+Include: UI renders, navigation, forms, data display, visual states, user interactions.
+Exclude: refactors, type changes, API internals, test files, build config, non-visual changes.
+
+**Step 5: Group and format**
+
+Group items by route for efficient navigation. Format as a numbered list:
+
+```
+1. **{name}**
+   Route: {route}
+   Expected: {expected}
+   Interaction: {interaction or "none"}
+   Needs backend data: {yes/no}
+
+2. **{name}**
+   ...
+```
+
 ## Spawn
 
-Spawn the browser verifier agent after auth is established:
+Spawn the browser verifier agent after auth is established and checklist is derived:
 
 ```
 Task(
   prompt="Run browser verification for phase {phase_number}.
 
 Phase directory: {phase_dir}
-Phase goal: {phase_goal}
-VERIFICATION.md: {verification_path}
 Dev URL: {dev_url}
 Auth state: .agent-browser-state.json
 Screenshots directory: {phase_dir}/screenshots
 
-Read VERIFICATION.md for observable truths. Test browser-testable ones.
-Save all screenshots to {phase_dir}/screenshots/.
-Fix issues inline. Return structured report.",
+## Browser Checklist
+
+{derived_checklist}
+
+## Backend Context
+
+{summary of which items need real backend data — from mock_hints external_data entries.
+Items needing backend data may show empty states or errors — mark as ENVIRONMENT_BLOCKED, not ISSUE.}
+
+Verify each checklist item. Save all screenshots to {phase_dir}/screenshots/.
+Fix trivial issues inline. Return structured report.",
   subagent_type="ms-browser-verifier"
 )
 ```
 
-**After verifier returns:**
+## Post-Verifier Handling
+
+Route based on the report's **Status** field:
+
+**`environment_blocked`:**
+Surface the blocker description and screenshot evidence to the user. Use AskUserQuestion:
+- header: "Browser verification blocked"
+- question: "The browser verifier hit an environment issue: {blocker description}. How to proceed?"
+- options: ["Re-run after fixing environment", "Skip browser verification"]
+
+**`has_fixes`:**
+Report: "Browser verification: {N} fixes applied, {M} issues found"
+Include the Fixes Applied section in the consolidator prompt (step `consolidate_knowledge`) so browser-discovered patterns are captured in knowledge files.
+
+**`has_issues`:**
+Report: "Browser verification: {N} issues found (see screenshots in {phase_dir}/screenshots/)"
+Note issues for verify-work — these are candidates for manual UAT.
 
-If fixes were made, include the report summary in the consolidator prompt (step `consolidate_knowledge`) so browser-discovered patterns are captured in knowledge files.
+**`all_passed`:**
+Report: "Browser verification: all {N} items passed"
 
 </browser_verification>

package/mindsystem/workflows/adhoc.md

@@ -132,7 +132,12 @@ Present a summary to the user:
 - Key files affected
 - Must-Haves checklist
 
-Allow the user to approve, request edits, or abort. If edits requested, apply them directly to the plan file.
+**AskUserQuestion** with options:
+- Approve and execute
+- Request edits (let me describe)
+- Abort
+
+If edits requested, apply them directly to the plan file, then re-present and ask again. If aborted, clean up `${exec_dir}` and stop.
 </step>
 
 <step name="spawn_executor">
@@ -202,8 +207,14 @@ The consolidator reads `adhoc-01-SUMMARY.md`, extracts knowledge (key-decisions,
 
 **Finalize todo (when detected):** Follow the **Finalization**, **Commit Message Suffix**, and **Report Additions** sections from the loaded todo reference.
 
-**Commit knowledge updates:**
+**Update STATE.md** "Recent Adhoc Work" section:
+- Find or create "### Recent Adhoc Work" under "## Accumulated Context"
+- Add entry at top: `- [YYYY-MM-DD]: [description] ({exec_dir}/adhoc-01-SUMMARY.md)`
+- Keep last 5 entries (remove older ones from list)
+
+**Update state and commit:**
 ```bash
+ms-tools set-last-command "ms:adhoc ${slug}"
 git add .planning/knowledge/*.md "${exec_dir}/adhoc-01-SUMMARY.md" .planning/STATE.md
 # Only include patch if it was generated
 [ -f "${exec_dir}/adhoc-01-changes.patch" ] && git add "${exec_dir}/adhoc-01-changes.patch"
@@ -215,16 +226,6 @@ EOF
 )"
 ```
 
-**Update STATE.md** "Recent Adhoc Work" section:
-- Find or create "### Recent Adhoc Work" under "## Accumulated Context"
-- Add entry at top: `- [YYYY-MM-DD]: [description] ({exec_dir}/adhoc-01-SUMMARY.md)`
-- Keep last 5 entries (remove older ones from list)
-
-**Set last command:**
-```bash
-ms-tools set-last-command "ms:adhoc $ARGUMENTS"
-```
-
 **Report completion:**
 ```
 Adhoc work complete: [description]
@@ -242,9 +243,7 @@ Artifacts:
 ```
 ---
 
-Continue with current work or check project status:
-- `/ms:progress` — see project status
-- `/ms:execute-phase` — continue phase execution
+Check `/ms:progress` to see project status and next steps.
 ```
 </step>
 

package/mindsystem/workflows/compound.md

@@ -97,20 +97,13 @@ Agent reads changes, reads affected knowledge files, writes updates, returns rep
 ms-tools config-set subsystems --append "new-subsystem"
 ```
 
-**Commit changes:**
+**Update state and commit:**
 ```bash
-git add .planning/knowledge/*.md
+ms-tools set-last-command "ms:compound $ARGUMENTS"
+git add .planning/knowledge/*.md .planning/STATE.md
 # Only add config.json if modified
 git add .planning/config.json 2>/dev/null
-git commit -m "$(cat <<'EOF'
-docs: compound knowledge from <description>
-EOF
-)"
-```
-
-**Set last command:**
-```bash
-ms-tools set-last-command "ms:compound $ARGUMENTS"
+git commit -m "docs: compound knowledge from <description>"
 ```
 
 **Report:** Subsystems updated, entries added/changed/removed, new subsystems created (if any).

package/mindsystem/workflows/define-requirements.md

@@ -258,7 +258,8 @@ If "adjust": Return to scope_categories or identify_gaps as appropriate.
 </step>
 
 <step name="git_commit">
-Commit requirements:
+
+**Update state and commit:**
 
 ```bash
 git add .planning/REQUIREMENTS.md

package/mindsystem/workflows/discuss-phase.md

@@ -300,11 +300,13 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 
 </step>
 
-<step name="git_commit">
-Commit phase context:
+<step name="commit">
+
+**Update state and commit:**
 
 ```bash
-git add .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
+ms-tools set-last-command "ms:discuss-phase ${PHASE}"
+git add .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs(${PHASE}): capture phase context
 
@@ -315,20 +317,12 @@ Phase ${PHASE}: ${PHASE_NAME}
 EOF
 )"
 ```
-
-Confirm: "Committed: docs(${PHASE}): capture phase context"
 </step>
 
 <step name="show_prework_status">
 Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
 </step>
 
-<step name="update_state">
-```bash
-ms-tools set-last-command "ms:discuss-phase ${PHASE}"
-```
-</step>
-
 </process>
 
 <success_criteria>

package/mindsystem/workflows/execute-phase.md

@@ -300,11 +300,13 @@ ms-tools browser-check
 
 **If exit 0 (READY):**
 
-Read `~/.claude/mindsystem/references/browser-verification.md` and follow its Auth Flow and Spawn sections.
+Ensure `$PHASE_DIR/*-SUMMARY.md` files are available (needed for checklist derivation — may already be in context from wave reports).
 
-After verifier returns, if fixes were made:
-- Report: "Browser verification: {N} issues found and fixed"
-- Include report summary in consolidator prompt (step `consolidate_knowledge`)
+Read `~/.claude/mindsystem/references/browser-verification.md` and follow its sections in order:
+1. **Auth Flow** — establish browser authentication
+2. **Derive Browser Checklist** — transform SUMMARYs into visual checklist items
+3. **Spawn** — launch verifier with derived checklist
+4. **Post-Verifier Handling** — route by report status
 
 **If exit 1 (MISSING_DEPS):**
 
@@ -509,23 +511,67 @@ git commit -m "docs: update codebase map after phase {X}"
 <step name="offer_next">
 Present next steps based on milestone status.
 
+**Thoroughness by default:** Verification is the natural next step after execution. The user can skip, but the system always suggests it first.
+
 **First, surface user actions:**
 
 Read `## User Actions Required` from all `*-SUMMARY.md` files in the phase directory. If any non-empty actions exist, present as `## ⚠ Action Required` block before route-specific content. Skip if all "None".
 
+**Then, assess skip context** from SUMMARYs and VERIFICATION.md already in context:
+- If all Must-Haves verified programmatically (uncertain = 0) AND phase involved only internal/structural changes (no user-facing UI, behavior, or API changes): include a brief skip note.
+- Otherwise: present verify-work without qualification — human verification adds clear value.
+
+**Present verify-work as Next Up:**
+
+```markdown
+## ✓ Phase {Z}: {Name} Complete
+
+All {Y} plans finished. Phase goal verified.
+
+---
+
+## ▶ Next Up
+
+`/ms:verify-work {Z}` — validate {phase name} through manual acceptance testing
+
+<sub>`/clear` first → fresh context window</sub>
+
+{If skip context applies: "Phase involved only {description} with no user-facing changes — skip if structural verification is sufficient."}
+```
+
+**Then present "Also available" based on milestone status:**
+
 **If more phases remain:**
 
-Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions to present "Next Up" with pre-work context for the next phase.
+Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` to determine the most appropriate command for the next phase (discuss/design/research/plan based on pre-work flags). Present concisely under "Also available":
 
-After the "Next Up" section, add:
 ```markdown
+---
+
+**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 from routing}
+- `/ms:plan-phase {Z+1}` — skip pre-work, plan directly
+
+---
 ```
 
+Include the pre-work recommendations table from the routing reference if any pre-work is flagged as "Likely".
+
 **If milestone complete:**
 
-Read `~/.claude/mindsystem/references/routing/milestone-complete-routing.md` and follow its instructions to present the milestone complete section.
+```markdown
+---
+
+**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
+
+---
+```
 </step>
 
 </process>

package/mindsystem/workflows/map-codebase.md

@@ -217,10 +217,13 @@ Continue to commit_codebase_map.
 </step>
 
 <step name="commit_codebase_map">
-Commit the codebase map:
+
+**Update state and commit:**
 
 ```bash
+ms-tools set-last-command "ms:map-codebase $ARGUMENTS"
 git add .planning/codebase/*.md
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs: map existing codebase
 

package/mindsystem/workflows/verify-work.md

@@ -590,7 +590,7 @@ PRE_WORK_STASH=$(git stash list | grep "pre-verify-work" | head -1 | cut -d: -f1
 [ -n "$PRE_WORK_STASH" ] && git stash pop "$PRE_WORK_STASH"
 ```
 
-**4. Update UAT.md and commit together with STATE.md:**
+**4. Update state and commit:**
 ```bash
 ms-tools uat-update $PHASE_NUMBER --session status=complete current_batch= mocked_files=
 ms-tools set-last-command "ms:verify-work $ARGUMENTS"

package/package.json

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