mindsystem-cc 4.1.2 → 4.2.0

package/agents/ms-browser-verifier.md

@@ -0,0 +1,102 @@
+---
+name: ms-browser-verifier
+description: Automated functional verification via browser. Tests observable truths, fixes issues inline, reports patterns for knowledge compounding.
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep, Glob
+skills:
+  - agent-browser
+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.
+
+**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.
+</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="extract_testable_truths">
+Read VERIFICATION.md from the phase directory. Extract observable truths and filter for browser-testable ones.
+
+Read plans and summaries to understand pages, routes, and components involved.
+
+**Browser-testable:** UI renders, navigation works, form submission succeeds, data displays correctly, interactions produce expected state changes.
+
+**Not browser-testable:** API internals, database state, background job execution, server-side logging.
+</step>
+
+<step name="verify_each_truth">
+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`
+
+**Critical:** Re-snapshot after every DOM change. Element references go stale after navigation or dynamic updates.
+</step>
+
+<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
+</step>
+
+<step name="close_and_report">
+Close the browser when all truths are verified.
+
+Return a structured report to the orchestrator:
+
+```
+## Browser Verification Report
+
+**Tested:** {count} | **Passed:** {count} | **Fixed:** {count} | **Unresolved:** {count}
+
+### Fixes Applied
+- {what was wrong} → {what was fixed} | Files: {changed files}
+
+### Unresolved Issues
+- {description} | Attempted: {what was tried}
+
+### Patterns for Knowledge
+- {recurring pattern observed across multiple truths}
+```
+</step>
+
+</process>
+
+<rules>
+- 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
+</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/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)$')

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"]
@@ -217,28 +278,17 @@ EOF
 
 </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

@@ -292,6 +292,19 @@ EOF
 ```
 </step>
 
+<step name="create_phase_dirs">
+Create phase directories from the roadmap:
+
+```bash
+ms-tools create-phase-dirs
+```
+
+```bash
+git add .planning/phases/
+git commit -m "chore: create phase directories from roadmap"
+```
+</step>
+
 <step name="done">
 ```
 Requirements and roadmap created:

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,7 +113,7 @@ 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**
+13. **Commit phase completion**
     Bundle all phase metadata updates in one commit:
     - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
     - Stage knowledge files: `git add .planning/knowledge/*.md`
@@ -115,10 +121,10 @@ ms-tools find-phase "$ARGUMENTS"
     - 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"`
+15. **Update last command:** `ms-tools set-last-command "ms:execute-phase $ARGUMENTS"`
 </process>
 
 <offer_next>
@@ -247,6 +253,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/mindsystem/references/browser-verification.md

@@ -0,0 +1,76 @@
+<browser_verification>
+
+# Browser Verification Reference
+
+Lazily loaded by execute-phase when `ms-tools browser-check` returns READY (exit 0).
+
+## Auth Flow
+
+Handle browser authentication before spawning the verifier agent.
+
+**Step 1: Check for existing auth state**
+
+```bash
+AUTH_STATE=".agent-browser-state.json"
+[ -f "$AUTH_STATE" ] && echo "HAS_STATE" || echo "NO_STATE"
+```
+
+**Step 2: Detect dev server URL**
+
+Probe common ports to find the running dev server:
+
+```bash
+for PORT in 5173 3000 8080 4200 3001; do
+  curl -s -o /dev/null -w "%{http_code}" "http://localhost:$PORT" 2>/dev/null | grep -q "200\|301\|302" && echo "http://localhost:$PORT" && break
+done
+```
+
+Store the result as `{dev_url}`.
+
+**Step 3: Validate or establish auth**
+
+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
+
+If `NO_STATE` or auth expired:
+1. Close headless browser
+2. Open `{dev_url}` in **headed** mode (visible browser)
+3. Use AskUserQuestion:
+   - header: "Browser authentication"
+   - question: "Please log in to the app in the browser window. Select 'Done' when you've logged in."
+   - options: ["Done — I'm logged in", "Skip browser verification"]
+4. If user logged in: save browser state to `.agent-browser-state.json`, close headed browser, ensure gitignored:
+   ```bash
+   grep -q "\.agent-browser-state\.json" .gitignore 2>/dev/null || echo '.agent-browser-state.json' >> .gitignore
+   ```
+5. If user skips: proceed to code_review, skip browser verification
+
+## Spawn
+
+Spawn the browser verifier agent after auth is established:
+
+```
+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.",
+  subagent_type="ms-browser-verifier"
+)
+```
+
+**After verifier returns:**
+
+If fixes were made, include the report summary in the consolidator prompt (step `consolidate_knowledge`) so browser-discovered patterns are captured in knowledge files.
+
+</browser_verification>

package/mindsystem/templates/config.json

@@ -5,5 +5,8 @@
     "phase": null,
     "milestone": null
   },
-  "open_mockups": "auto"
+  "open_mockups": "auto",
+  "browser_verification": {
+    "enabled": true
+  }
 }

package/mindsystem/workflows/complete-milestone.md

@@ -38,7 +38,7 @@ When a milestone completes, this workflow:
 
 **PHASE-SUMMARIES** consolidates all `*-SUMMARY.md` files from phase directories, organized by phase and plan, before artifacts are deleted.
 
-**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`) moved from `.planning/phases/`.
+**phases/** contains the phase directories themselves (with remaining files like `.patch`, `mockups/`, `screenshots/`) moved from `.planning/phases/`.
 
 **REQUIREMENTS archive** contains:
 - All v1 requirements marked complete with outcomes

package/mindsystem/workflows/doctor-fixes.md

@@ -80,7 +80,7 @@ For each flat file like `milestones/v0.1-ROADMAP.md`:
 3. `git mv` the file, stripping the version prefix from the filename:
    `git mv .planning/milestones/v0.1-ROADMAP.md .planning/milestones/v0.1/ROADMAP.md`
 
-**Note:** New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
+New milestones use slug-based directories (e.g., `milestones/mvp/`, `milestones/push-notifications/`). Old v-prefixed directories from previous format are valid and handled.
 
 Commit:
 
@@ -106,7 +106,7 @@ EOF
 2. **Resolve slugs** — For each versioned dir, match to MILESTONES.md name mapping:
    - Standard dirs: version matches directly (v0.1 → "MVP" → slug "mvp")
    - Nested dirs: match sub-directory name to the milestone name in MILESTONES.md (v2.0.0/quests → "Quests Feature" → slug "quests-feature")
-   - Derive short slugs from names (Claude proposes, user confirms)
+   - Derive slugs from names: lowercase, hyphenated (e.g., "Demo Release" → "demo-release"). Claude proposes, user confirms
 
 3. **Present mapping** to user with AskUserQuestion:
 
@@ -236,6 +236,35 @@ EOF
 ```
 </step>
 
+<step name="fix_phase_dirs">
+**Only if Phase Directory Naming failed or warned.**
+
+1. Create any missing phase directories:
+
+```bash
+ms-tools create-phase-dirs
+```
+
+2. For non-canonical directories (reported as FAIL), rename using `git mv`:
+
+Parse each non-canonical suggestion from the doctor check output (format: `{old} → git mv .planning/phases/{old} .planning/phases/{canonical}`) and execute the `git mv`.
+
+Commit:
+
+```bash
+git add .planning/phases/
+```
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(doctor): fix phase directory naming
+
+Created missing and renamed non-canonical phase directories.
+EOF
+)"
+```
+</step>
+
 <step name="fix_knowledge">
 **Only if Knowledge Files failed.**
 
@@ -253,7 +282,7 @@ If `SUMMARIES > 0`: **artifact mode**. If `SUMMARIES == 0`: **source code mode**
 
 ### 2. Spawn subagent
 
-Spawn a `general-purpose` subagent (Task tool) with the following structured prompt. Inject detected mode, subsystem list from config.json, and environment flags into the prompt.
+Spawn a `general-purpose` subagent (Task tool) with the following structured prompt. Inject detected mode, subsystem list from config.json, and detection results (SUMMARIES, HAS_CODEBASE_DOCS, HAS_PROJECT) into the prompt.
 
 ---
 

package/mindsystem/workflows/execute-phase.md

@@ -291,6 +291,38 @@ If the verifier's return includes "Items Not Verified Programmatically" (uncerta
 Read `~/.claude/mindsystem/references/routing/gap-closure-routing.md` and follow its triage instructions to present gap summary and route to the appropriate primitive based on scope analysis.
 </step>
 
+<step name="browser_verification">
+Run browser verification prerequisites check:
+
+```bash
+ms-tools browser-check
+```
+
+**If exit 0 (READY):**
+
+Read `~/.claude/mindsystem/references/browser-verification.md` and follow its Auth Flow and Spawn sections.
+
+After verifier returns, if fixes were made:
+- Report: "Browser verification: {N} issues found and fixed"
+- Include report summary in consolidator prompt (step `consolidate_knowledge`)
+
+**If exit 1 (MISSING_DEPS):**
+
+Parse output for missing items. Use AskUserQuestion:
+- header: "Browser verification"
+- question: "Browser verification prerequisites are missing. How to proceed?"
+- options:
+  - "Install missing dependencies" — follow install instructions from output
+  - "Skip browser verification" — proceed to code_review
+
+If user installs: re-run `ms-tools browser-check`.
+If user skips: proceed to code_review.
+
+**If exit 2 (SKIP):**
+
+Proceed silently to code_review.
+</step>
+
 <step name="code_review">
 Read code review agent name from config:
 
@@ -311,7 +343,7 @@ Use CODE_REVIEW value directly as agent name.
 1. **Gather changed files:**
    ```bash
    # Get all files changed in this phase's commits
-   PHASE_COMMITS=$(git log --oneline --grep="(${PHASE_NUMBER}-" --format="%H")
+   PHASE_COMMITS=$(ms-tools find-phase-commits ${PHASE_NUMBER})
    CHANGED_FILES=$(git diff --name-only $(echo "$PHASE_COMMITS" | tail -1)^..HEAD | grep -E '\.(dart|ts|tsx|js|jsx|swift|kt|py|go|rs)$')
    ```
 
@@ -447,7 +479,7 @@ Check what changed during this phase:
 
 ```bash
 # Get all source changes from this phase's commits
-PHASE_COMMITS=$(git log --oneline --grep="({phase_number}-" --format="%H" | head -20)
+PHASE_COMMITS=$(ms-tools find-phase-commits {phase_number})
 if [ -n "$PHASE_COMMITS" ]; then
   FIRST=$(echo "$PHASE_COMMITS" | tail -1)
   git diff --name-only ${FIRST}^..HEAD 2>/dev/null | grep -v "^\.planning/"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mindsystem-cc",
-  "version": "4.1.2",
-  "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
+  "version": "4.2.0",
+  "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"
   },

package/scripts/ms-tools.py

@@ -109,13 +109,63 @@ def normalize_phase(phase_str: str) -> str:
 
 
 def find_phase_dir(planning: Path, phase: str) -> Path | None:
-    """Find the phase directory matching a normalized phase number."""
+    """Find the phase directory matching a normalized phase number.
+
+    Tries three patterns in priority order:
+    1. Canonical padded: {phase}-* (e.g., 05-*)
+    2. Unpadded variant: {raw}-* (e.g., 5-*) — only when raw != phase
+    3. Bare directory: {phase}/ or {raw}/ — only directories
+    """
     phases_dir = planning / "phases"
     if not phases_dir.is_dir():
         return None
+
+    # Derive raw (unpadded) form: "05" -> "5", "02.1" -> "2.1"
+    raw_match = re.match(r"^0*(\d.*)", phase)
+    raw = raw_match.group(1) if raw_match else phase
+
+    # Tier 1: canonical padded glob
     matches = sorted(phases_dir.glob(f"{phase}-*"))
     dirs = [m for m in matches if m.is_dir()]
-    return dirs[0] if dirs else None
+    if dirs:
+        return dirs[0]
+
+    # Tier 2: unpadded variant glob (skip when raw == phase)
+    if raw != phase:
+        matches = sorted(phases_dir.glob(f"{raw}-*"))
+        dirs = [m for m in matches if m.is_dir()]
+        if dirs:
+            return dirs[0]
+
+    # Tier 3: bare directory
+    bare_padded = phases_dir / phase
+    if bare_padded.is_dir():
+        return bare_padded
+    if raw != phase:
+        bare_raw = phases_dir / raw
+        if bare_raw.is_dir():
+            return bare_raw
+
+    return None
+
+
+def parse_roadmap_phases(roadmap_path: Path) -> list[tuple[str, str]]:
+    """Parse phase headers from ROADMAP.md.
+
+    Returns list of (phase_number, phase_name) tuples.
+    Strips markers like (INSERTED), (Generated) from names.
+    """
+    if not roadmap_path.is_file():
+        return []
+    text = roadmap_path.read_text(encoding="utf-8")
+    results: list[tuple[str, str]] = []
+    for line in text.splitlines():
+        m = re.match(r"^###\s+Phase\s+(\d+(?:\.\d+)?)\s*:\s*(.+)$", line)
+        if m:
+            num = m.group(1)
+            name = re.sub(r"\s*\([A-Z][A-Za-z]*\)\s*$", "", m.group(2)).strip()
+            results.append((num, name))
+    return results
 
 
 def run_git(*args: str) -> str:
@@ -297,6 +347,80 @@ def build_exclude_pathspecs() -> list[str]:
     return [f":!{p}" for p in PATCH_EXCLUSIONS]
 
 
+# -------------------------------------------------------------------
+# Helper: find_phase_commit_hashes
+# -------------------------------------------------------------------
+
+
+def find_phase_commit_hashes(phase_input: str, suffix: str = "") -> list[str]:
+    """Find commit hashes matching a phase's commit convention.
+
+    Contract:
+        Args: phase_input (str), suffix (str, optional)
+        Output: list of commit hash strings (newest first)
+        Side effects: none (reads git log only)
+    """
+    padded_phase = normalize_phase(phase_input)
+    # Strip leading zeros from integer part, preserve decimal: "02.1" -> "2.1"
+    m = re.match(r"^(\d+)(.*)", padded_phase)
+    raw_phase = str(int(m.group(1))) + m.group(2) if m else padded_phase
+
+    # Build alternation pattern matching both padded and raw forms
+    if padded_phase == raw_phase:
+        phase_alt = re.escape(raw_phase)
+    else:
+        phase_alt = f"(?:0*{re.escape(raw_phase)})"
+
+    # Build commit pattern based on suffix
+    if suffix:
+        if suffix == "uat-fixes":
+            commit_pattern = f"\\({phase_alt}-uat\\):"
+        else:
+            commit_pattern = f"\\({phase_alt}-{re.escape(suffix)}\\):"
+    else:
+        commit_pattern = f"\\({phase_alt}-"
+
+    # Find matching commits
+    try:
+        log_output = run_git("log", "--oneline")
+    except subprocess.CalledProcessError:
+        raise
+
+    hashes = []
+    for line in log_output.splitlines():
+        if re.search(commit_pattern, line):
+            hashes.append(line.split()[0])
+    return hashes
+
+
+# -------------------------------------------------------------------
+# Subcommand: find-phase-commits
+# -------------------------------------------------------------------
+
+
+def cmd_find_phase_commits(args: argparse.Namespace) -> None:
+    """Print commit hashes matching a phase's commit convention.
+
+    Contract:
+        Args: phase (str), --suffix (str, optional)
+        Output: text — one commit hash per line (newest first), empty if no matches
+        Exit codes: 0 = success (including zero matches), 1 = git error
+        Side effects: none
+    """
+    git_root = find_git_root()
+    import os
+    os.chdir(git_root)
+
+    try:
+        hashes = find_phase_commit_hashes(args.phase, args.suffix)
+    except subprocess.CalledProcessError:
+        print("Error: Failed to read git log", file=sys.stderr)
+        sys.exit(1)
+
+    for h in hashes:
+        print(h)
+
+
 # ===================================================================
 # Subcommand: update-state
 # ===================================================================
@@ -475,6 +599,166 @@ def cmd_validate_execution_order(args: argparse.Namespace) -> None:
     print(f"PASS: {len(disk_plans)} plans across {wave_count} waves")
 
 
+# ===================================================================
+# Subcommand: browser-check
+# ===================================================================
+
+
+def _get_claude_config_dir() -> Path:
+    """Cross-platform Claude Code config directory."""
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "Claude"
+        return Path.home() / "AppData" / "Roaming" / "Claude"
+    return Path.home() / ".claude"
+
+
+WEB_FRAMEWORK_DEPS = {
+    "react", "react-dom", "vue", "next", "nuxt", "@angular/core",
+    "svelte", "@sveltejs/kit", "solid-js", "astro", "@remix-run/react",
+    "gatsby", "preact",
+}
+
+WEB_CONFIG_FILES = [
+    "next.config.*", "nuxt.config.*", "vite.config.*", "angular.json",
+    "svelte.config.*", "astro.config.*", "remix.config.*",
+]
+
+
+def _detect_web_project(git_root: Path) -> tuple[bool, str]:
+    """Detect if project is a web project. Returns (is_web, signal_description)."""
+    # Signal 1: package.json deps
+    pkg = git_root / "package.json"
+    if pkg.is_file():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+            all_deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+            found = WEB_FRAMEWORK_DEPS & set(all_deps.keys())
+            if found:
+                return True, f"{', '.join(sorted(found))} in package.json"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Signal 2: Framework config files (glob at root)
+    for pattern in WEB_CONFIG_FILES:
+        if list(git_root.glob(pattern)):
+            return True, f"{pattern} found"
+
+    # Signal 3: One level deep package.json (monorepo)
+    for child_pkg in git_root.glob("*/package.json"):
+        if "node_modules" in str(child_pkg):
+            continue
+        try:
+            data = json.loads(child_pkg.read_text(encoding="utf-8"))
+            all_deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+            found = WEB_FRAMEWORK_DEPS & set(all_deps.keys())
+            if found:
+                return True, f"{', '.join(sorted(found))} in {child_pkg.relative_to(git_root)}"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Signal 4: PROJECT.md tech stack mentions
+    project_md = git_root / ".planning" / "PROJECT.md"
+    if project_md.is_file():
+        try:
+            content = project_md.read_text(encoding="utf-8").lower()
+            web_keywords = ["react", "vue", "next.js", "nextjs", "nuxt", "angular", "svelte", "sveltekit", "astro", "remix"]
+            for kw in web_keywords:
+                if kw in content:
+                    return True, f"'{kw}' mentioned in PROJECT.md"
+        except OSError:
+            pass
+
+    return False, "no web framework in package.json, no framework config files, no web stack in PROJECT.md"
+
+
+def _check_skill_installed(skill_name: str) -> tuple[bool, str]:
+    """Check if a Claude Code skill is installed. Cross-platform."""
+    config_dir = _get_claude_config_dir()
+    locations = [
+        ("user", config_dir / "skills" / skill_name / "SKILL.md"),
+        ("project", Path.cwd() / ".claude" / "skills" / skill_name / "SKILL.md"),
+    ]
+    for label, path in locations:
+        if path.is_file():
+            return True, f"{label}: {path}"
+    return False, "not found in ~/.claude/skills/ or .claude/skills/"
+
+
+def cmd_browser_check(args: argparse.Namespace) -> None:
+    """Check browser verification prerequisites.
+
+    Contract:
+        Output: text — section-based status report
+        Exit codes: 0 = READY, 1 = MISSING_DEPS, 2 = SKIP
+        Side effects: read-only
+    """
+    git_root = find_git_root()
+    planning = git_root / ".planning"
+
+    # 1. Config check
+    print("=== Browser Verification Config ===")
+    enabled = True  # default
+    config_path = planning / "config.json" if planning.is_dir() else None
+    if config_path and config_path.is_file():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+            bv = config.get("browser_verification", {})
+            if isinstance(bv, dict):
+                enabled = bv.get("enabled", True)
+            # else: malformed, default to enabled
+        except (json.JSONDecodeError, OSError):
+            pass  # malformed config, default to enabled
+    print(f"Status: {'enabled' if enabled else 'disabled'}")
+
+    if not enabled:
+        print("\nResult: SKIP (disabled in config)")
+        sys.exit(2)
+
+    # 2. Web project check
+    print("\n=== Web Project Detection ===")
+    is_web, signal = _detect_web_project(git_root)
+    print(f"Web project: {is_web}")
+    print(f"Signal: {signal}")
+
+    if not is_web:
+        print("\nResult: SKIP (not a web project)")
+        sys.exit(2)
+
+    # 3. CLI check
+    print("\n=== Browser CLI ===")
+    cli_path = shutil.which("agent-browser")
+    if cli_path:
+        print(f"agent-browser: {cli_path}")
+    else:
+        print("agent-browser: not found")
+        print("Install: npm install -g agent-browser")
+
+    # 4. Skill check
+    print("\n=== Browser Skill ===")
+    skill_ok, skill_detail = _check_skill_installed("agent-browser")
+    if skill_ok:
+        print(f"agent-browser skill: {skill_detail}")
+    else:
+        print(f"agent-browser skill: {skill_detail}")
+        print("Install: add agent-browser skill to ~/.claude/skills/")
+
+    # Result
+    missing: list[str] = []
+    if not cli_path:
+        missing.append("agent-browser CLI")
+    if not skill_ok:
+        missing.append("agent-browser skill")
+
+    if missing:
+        print(f"\nResult: MISSING_DEPS ({', '.join(missing)})")
+        sys.exit(1)
+
+    print("\nResult: READY")
+    sys.exit(0)
+
+
 # ===================================================================
 # Subcommand: doctor-scan
 # ===================================================================
@@ -530,12 +814,6 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         else:
             skip_count += 1
 
-    def format_phase_prefix(phase: str) -> str:
-        if "." in phase:
-            int_part, dec_part = phase.split(".", 1)
-            return f"{int(int_part):02d}.{dec_part}"
-        return f"{int(phase):02d}"
-
     def parse_phase_numbers(line: str) -> list[str]:
         """Parse phase numbers from a 'Phases completed' line."""
         range_match = re.search(r"(\d+)-(\d+)", line)
@@ -629,7 +907,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
             orphans: list[str] = []
             for line in phase_lines:
                 for phase_num in parse_phase_numbers(line):
-                    prefix = format_phase_prefix(phase_num)
+                    prefix = normalize_phase(phase_num)
                     if phases_dir.is_dir():
                         for d in phases_dir.glob(f"{prefix}-*/"):
                             if d.is_dir():
@@ -728,7 +1006,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
             leftovers: list[str] = []
             for line in phase_lines:
                 for phase_num in parse_phase_numbers(line):
-                    prefix = format_phase_prefix(phase_num)
+                    prefix = normalize_phase(phase_num)
                     if phases_dir.is_dir():
                         for d in phases_dir.glob(f"{prefix}-*/"):
                             if d.is_dir():
@@ -877,6 +1155,84 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         record("WARN", "Research API Keys")
     print()
 
+    # ---- CHECK 10: Phase Directory Naming ----
+    print("=== Phase Directory Naming ===")
+    roadmap_path = planning / "ROADMAP.md"
+    roadmap_phases = parse_roadmap_phases(roadmap_path)
+    if not roadmap_phases:
+        print("Status: SKIP")
+        print("No ROADMAP.md or no phases found")
+        record("SKIP", "Phase Directory Naming")
+    else:
+        non_canonical: list[str] = []
+        missing_dirs: list[str] = []
+        for num, name in roadmap_phases:
+            padded = normalize_phase(num)
+            slug = slugify(name)
+            canonical = f"{padded}-{slug}"
+            canonical_path = phases_dir / canonical if phases_dir.is_dir() else None
+            if canonical_path and canonical_path.is_dir():
+                continue
+            found = find_phase_dir(planning, padded)
+            if found is not None:
+                non_canonical.append(f"  {found.name} → git mv .planning/phases/{found.name} .planning/phases/{canonical}")
+            else:
+                missing_dirs.append(f"  {canonical} (missing, run: ms-tools create-phase-dirs)")
+        if non_canonical:
+            print("Status: FAIL")
+            print(f"Found {len(non_canonical)} non-canonical phase directory name(s):")
+            for line in non_canonical:
+                print(line)
+            record("FAIL", "Phase Directory Naming")
+        elif missing_dirs:
+            print("Status: WARN")
+            print(f"Found {len(missing_dirs)} missing phase directory(ies):")
+            for line in missing_dirs:
+                print(line)
+            record("WARN", "Phase Directory Naming")
+        else:
+            print("Status: PASS")
+            print("All phase directories use canonical naming")
+            record("PASS", "Phase Directory Naming")
+    print()
+
+    # ---- CHECK 11: Browser Verification ----
+    print("=== Browser Verification ===")
+    bv_enabled = True
+    bv_config = config.get("browser_verification", {})
+    if isinstance(bv_config, dict):
+        bv_enabled = bv_config.get("enabled", True)
+
+    if not bv_enabled:
+        print("Status: SKIP")
+        print("Disabled in config.json")
+        record("SKIP", "Browser Verification")
+    else:
+        is_web, web_signal = _detect_web_project(git_root)
+        if not is_web:
+            print("Status: SKIP")
+            print(f"Not a web project ({web_signal})")
+            record("SKIP", "Browser Verification")
+        else:
+            bv_missing: list[str] = []
+            cli_path = shutil.which("agent-browser")
+            if not cli_path:
+                bv_missing.append("agent-browser CLI (npm install -g agent-browser)")
+            skill_ok, _ = _check_skill_installed("agent-browser")
+            if not skill_ok:
+                bv_missing.append("agent-browser skill")
+            if bv_missing:
+                print("Status: WARN")
+                print(f"Web project detected ({web_signal}) but missing:")
+                for m in bv_missing:
+                    print(f"  {m}")
+                record("WARN", "Browser Verification")
+            else:
+                print("Status: PASS")
+                print(f"Web project ({web_signal}), CLI and skill installed")
+                record("PASS", "Browser Verification")
+    print()
+
     # ---- SUMMARY ----
     total = pass_count + warn_count + fail_count + skip_count
     print("=== Summary ===")
@@ -890,6 +1246,44 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
         print("All checks passed")
 
 
+# ===================================================================
+# Subcommand: create-phase-dirs
+# ===================================================================
+
+
+def cmd_create_phase_dirs(args: argparse.Namespace) -> None:
+    """Create phase directories from ROADMAP.md headers.
+
+    Reads ### Phase N: Name headers, creates .planning/phases/{padded}-{slug}/
+    for each. Skips phases that already have a directory (found via resilient
+    find_phase_dir).
+    """
+    planning = find_planning_dir()
+    roadmap_path = planning / "ROADMAP.md"
+    phases = parse_roadmap_phases(roadmap_path)
+    if not phases:
+        print("Error: No phases found in ROADMAP.md (or file missing)", file=sys.stderr)
+        sys.exit(1)
+
+    phases_dir = planning / "phases"
+    phases_dir.mkdir(parents=True, exist_ok=True)
+
+    created = 0
+    skipped = 0
+    for num, name in phases:
+        padded = normalize_phase(num)
+        if find_phase_dir(planning, padded) is not None:
+            skipped += 1
+            continue
+        slug = slugify(name)
+        dir_name = f"{padded}-{slug}"
+        (phases_dir / dir_name).mkdir(parents=True, exist_ok=True)
+        print(f"Created: {dir_name}")
+        created += 1
+
+    print(f"\n{created} created, {skipped} skipped (already exist)")
+
+
 # ===================================================================
 # Subcommand: gather-milestone-stats
 # ===================================================================
@@ -982,28 +1376,32 @@ def cmd_gather_milestone_stats(args: argparse.Namespace) -> None:
 
     all_commits: list[str] = []
 
-    # Integer phases
+    # Integer phases — try both padded and raw formats
     for i in range(start, end + 1):
-        phase = f"{i:02d}"
-        try:
-            out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({phase}-")
-            if out:
-                all_commits.extend(out.splitlines())
-        except subprocess.CalledProcessError:
-            pass
+        padded = normalize_phase(str(i))
+        raw = str(i)
+        for p in ([padded, raw] if padded != raw else [padded]):
+            try:
+                out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({p}-")
+                if out:
+                    all_commits.extend(out.splitlines())
+            except subprocess.CalledProcessError:
+                pass
 
-    # Decimal phases
+    # Decimal phases — try both directory-derived and padded forms
     for d in sorted(phases_dir.iterdir()):
         if not d.is_dir():
             continue
         phase_num = d.name.split("-", 1)[0]
         if "." in phase_num and in_range(phase_num, start, end):
-            try:
-                out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({phase_num}-")
-                if out:
-                    all_commits.extend(out.splitlines())
-            except subprocess.CalledProcessError:
-                pass
+            padded = normalize_phase(phase_num)
+            for p in ([padded, phase_num] if padded != phase_num else [padded]):
+                try:
+                    out = run_git("log", "--all", "--format=%H %ai %s", f"--grep=({p}-")
+                    if out:
+                        all_commits.extend(out.splitlines())
+                except subprocess.CalledProcessError:
+                    pass
 
     # Deduplicate and sort by date
     seen: set[str] = set()
@@ -1071,38 +1469,24 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
     import os
     os.chdir(git_root)
 
-    # Normalize phase number
-    if re.match(r"^\d$", phase_input):
-        phase_number = f"{int(phase_input):02d}"
-    else:
-        phase_number = phase_input
+    padded_phase = normalize_phase(phase_input)
 
-    # Determine commit pattern
     if suffix:
         if suffix == "uat-fixes":
-            commit_pattern = f"\\({phase_number}-uat\\):"
-            print(f"Generating UAT fixes patch for phase {phase_number}...")
+            print(f"Generating UAT fixes patch for phase {padded_phase}...")
         else:
-            commit_pattern = f"\\({phase_number}-{suffix}\\):"
-            print(f"Generating {suffix} patch for phase {phase_number}...")
+            print(f"Generating {suffix} patch for phase {padded_phase}...")
     else:
-        commit_pattern = f"\\({phase_number}-"
-        print(f"Generating patch for phase {phase_number}...")
+        print(f"Generating patch for phase {padded_phase}...")
 
-    # Find matching commits
     try:
-        log_output = run_git("log", "--oneline")
+        phase_commits = find_phase_commit_hashes(phase_input, suffix)
     except subprocess.CalledProcessError:
         print("Error: Failed to read git log", file=sys.stderr)
         sys.exit(1)
 
-    phase_commits = []
-    for line in log_output.splitlines():
-        if re.search(commit_pattern, line):
-            phase_commits.append(line.split()[0])
-
     if not phase_commits:
-        print(f"No commits found matching pattern: {commit_pattern}")
+        print("No commits found matching phase convention")
         print("Patch skipped")
         return
 
@@ -1120,7 +1504,7 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
 
     # Find output directory
     phases_dir = Path(".planning/phases")
-    phase_dir_matches = sorted(phases_dir.glob(f"{phase_number}-*")) if phases_dir.is_dir() else []
+    phase_dir_matches = sorted(phases_dir.glob(f"{padded_phase}-*")) if phases_dir.is_dir() else []
     phase_dir = str(phase_dir_matches[0]) if phase_dir_matches else str(phases_dir)
 
     Path(phase_dir).mkdir(parents=True, exist_ok=True)
@@ -1128,9 +1512,9 @@ def cmd_generate_phase_patch(args: argparse.Namespace) -> None:
 
     # Determine output filename
     if suffix:
-        patch_file = f"{phase_dir}/{phase_number}-{suffix}.patch"
+        patch_file = f"{phase_dir}/{padded_phase}-{suffix}.patch"
     else:
-        patch_file = f"{phase_dir}/{phase_number}-changes.patch"
+        patch_file = f"{phase_dir}/{padded_phase}-changes.patch"
 
     # Generate diff
     exclude_args = build_exclude_pathspecs()
@@ -2776,10 +3160,8 @@ def cmd_uat_init(args: argparse.Namespace) -> None:
 
     phase_dir = find_phase_dir(planning, phase)
     if phase_dir is None:
-        phases_dir = planning / "phases"
-        phases_dir.mkdir(parents=True, exist_ok=True)
-        phase_dir = phases_dir / phase
-        phase_dir.mkdir(parents=True, exist_ok=True)
+        print(f"Error: Phase directory not found for {phase}. Run: ms-tools create-phase-dirs", file=sys.stderr)
+        sys.exit(1)
 
     phase_name = phase_dir.name
     uat = UATFile.from_init_json(data, phase_name)
@@ -3234,10 +3616,18 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("phase_dir", help="Phase directory path")
     p.set_defaults(func=cmd_validate_execution_order)
 
+    # --- browser-check ---
+    p = subparsers.add_parser("browser-check", help="Check browser verification prerequisites")
+    p.set_defaults(func=cmd_browser_check)
+
     # --- doctor-scan ---
     p = subparsers.add_parser("doctor-scan", help="Diagnostic scan of .planning/ tree")
     p.set_defaults(func=cmd_doctor_scan)
 
+    # --- create-phase-dirs ---
+    p = subparsers.add_parser("create-phase-dirs", help="Create phase directories from ROADMAP.md")
+    p.set_defaults(func=cmd_create_phase_dirs)
+
     # --- gather-milestone-stats ---
     p = subparsers.add_parser("gather-milestone-stats", help="Gather milestone readiness and git statistics")
     p.add_argument("start_phase", type=int, help="Start phase number")
@@ -3250,6 +3640,12 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--suffix", default="", help="Filter commits and customize output filename")
     p.set_defaults(func=cmd_generate_phase_patch)
 
+    # --- find-phase-commits ---
+    p = subparsers.add_parser("find-phase-commits", help="Find commit hashes matching phase convention")
+    p.add_argument("phase", help="Phase number (e.g., 04 or 4)")
+    p.add_argument("--suffix", default="", help="Filter by suffix (e.g., uat)")
+    p.set_defaults(func=cmd_find_phase_commits)
+
     # --- generate-adhoc-patch ---
     p = subparsers.add_parser("generate-adhoc-patch", help="Generate patch from an adhoc commit or range")
     p.add_argument("commit", help="Start commit hash")