mindsystem-cc 4.3.1 → 4.4.1

package/commands/ms/config.md

@@ -1,6 +1,6 @@
 ---
 name: ms:config
-description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, gitignore, git remote, task tracker
+description: Configure Mindsystem preferences — code reviewers, mockups, browser verification, plan mode, 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, browser verification, .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, plan mode, .gitignore patterns for `.planning/` artifacts, git remote setup, and task tracker integration. Run anytime to reconfigure — idempotent.
 
 </objective>
 
@@ -42,7 +42,7 @@ git remote -v 2>/dev/null || echo "NO_REMOTE"
 
 <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`.
+**Setup mode:** Proceed through all setting steps sequentially (git_remote → code_reviewers → gitignore_patterns → mockup_preferences → browser_verification → multi_plan → task_tracker). Then go to `validation_summary`.
 
 **Edit mode:** Display all current settings with values from config.json, git remote, and .gitignore:
 
@@ -53,8 +53,9 @@ git remote -v 2>/dev/null || echo "NO_REMOTE"
 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"}
+5. **Browser verification** — {enabled / disabled}, web project: {yes / no / auto-detect}
+6. **Plan mode** — {single plan (default) / multi-plan}
+7. **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."
@@ -197,7 +198,56 @@ Map selection:
 Update config.json:
 
 ```bash
-ms-tools config-set browser_verification --json '{"enabled": true}'   # or false
+ms-tools config-set browser_verification.enabled --json 'true'   # or false
+```
+
+**If enabled**, detect and confirm web project status:
+
+```bash
+ms-tools detect-web
+```
+
+Present the auto-detection result via AskUserQuestion:
+- header: "Web project detection"
+- question: "Is this a web project with a browser-renderable UI? Auto-detection returned: {detected result}"
+- options:
+  - "Yes — this is a web project" (recommended if detected)
+  - "No — this is not a web project"
+  - "Auto-detect (don't persist)" — remove any existing override
+
+Map selection:
+- "Yes" → `ms-tools config-set browser_verification.web_project --json 'true'`
+- "No" → `ms-tools config-set browser_verification.web_project --json 'false'`
+- "Auto-detect" → `ms-tools config-delete browser_verification.web_project`
+
+**If disabled**, skip the web_project question.
+
+</step>
+
+<step name="multi_plan">
+
+Read current value:
+
+```bash
+CURRENT=$(ms-tools config-get multi_plan --default "false")
+echo "Current multi_plan: $CURRENT"
+```
+
+Use AskUserQuestion:
+- header: "Plan mode"
+- question: "How should plan-phase group tasks into plans?"
+- options:
+  - "Single plan (Recommended)" — All tasks in one plan. Optimal for 1M context windows where phases already scope work tightly
+  - "Multi-plan" — Split into multiple plans with wave-based parallel execution. Use when phases have genuinely independent work streams
+
+Map selection:
+- "Single plan" → `false`
+- "Multi-plan" → `true`
+
+Update config.json:
+
+```bash
+ms-tools config-set multi_plan $VALUE   # true or false (unquoted — boolean)
 ```
 
 </step>
@@ -254,6 +304,7 @@ Configuration updated:
 - Code reviewers: [adhoc / phase / milestone values]
 - Mockup open: [auto / ask / off]
 - Browser verification: [enabled / disabled]
+- Plan mode: [single plan / multi-plan]
 - Gitignore: [patterns added, or "no changes"]
 - Git remote: [remote URL, or "none configured"]
 - Task tracker: [type + cli path, or "none"]

package/commands/ms/doctor.md

@@ -145,7 +145,7 @@ If "Review each" → use AskUserQuestion for each failed check with its details
 
 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.
+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. Research API Keys check provides platform-aware setup guidance (shell export on macOS/Linux, settings.json on Windows) and checks both environment variables and `~/.claude/settings.json` env section as fallback.
 </step>
 
 <step name="apply_fixes">

package/commands/ms/help.md

@@ -108,7 +108,7 @@ Initialize new project with brief and configuration.
 Usage: `/ms:new-project`
 
 **`/ms:config`**
-Configure Mindsystem preferences — code reviewers, mockup preferences, gitignore patterns, git remote.
+Configure Mindsystem preferences — code reviewers, mockup preferences, browser verification, plan mode, gitignore patterns, git remote, task tracker.
 
 - Use when: you want to set up code review agents, mockup open behavior, manage which .planning/ artifacts are git-ignored, or push your repo to GitHub.
 - Edits `.planning/config.json` and `.gitignore`
@@ -205,12 +205,12 @@ Create detailed execution plan for a specific phase.
 - Generates `.planning/phases/XX-phase-name/XX-YY-PLAN.md`
 - Breaks phase into concrete, actionable tasks
 - Includes verification criteria and success measures
-- Multiple plans per phase supported (XX-01, XX-02, etc.)
+- Single plan per phase by default. Enable `multi_plan` in config for multiple plans (XX-01, XX-02, etc.)
 - After planning: calculates risk score (0-100) and offers optional plan verification
   - Skip tier (0-39): Low complexity, verification optional
   - Optional tier (40-69): Moderate complexity, verification recommended
   - Verify tier (70-100): Higher complexity, verification strongly recommended
-- Risk factors: task count, plan count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains
+- Risk factors: task count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains
 
 Usage: `/ms:plan-phase 1`
 Usage: `/ms:plan-phase` (auto-detect next unplanned phase)
@@ -254,22 +254,22 @@ Usage: `/ms:audit-milestone`
 ### Roadmap Management
 
 **`/ms:add-phase <description>`**
-Add new phase to end of current milestone.
+Add new phase to end of current milestone with full specification.
 
 - Use when: you discovered additional work that belongs after the currently planned phases (not an urgent insertion).
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
+- Derives goal, success criteria, and requirements (with REQ-IDs) from description
+- Updates ROADMAP.md, REQUIREMENTS.md (with traceability), and STATE.md
+- Phase is set up identically to roadmapper-created phases — full pipeline support
 
 Usage: `/ms:add-phase "Add admin dashboard"`
 
 **`/ms:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
+Insert urgent work as decimal phase between existing phases with full specification.
 
 - Use when: you discovered work that must happen before the next integer phase, but you don’t want to renumber the roadmap.
 - Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
+- Derives goal, success criteria, and requirements (with REQ-IDs) from description
+- Updates ROADMAP.md, REQUIREMENTS.md (with traceability), and STATE.md
 
 Usage: `/ms:insert-phase 7 "Fix critical auth bug"`
 Result: Creates Phase 7.1
@@ -366,11 +366,13 @@ Execute discovered work with knowledge-aware planning and execution.
 - Use when: you discover work mid-session that can be completed in a single context window without multi-phase orchestration.
 - Bridges the gap between `/ms:add-todo` (capture for later) and `/ms:insert-phase` (multi-plan coordination)
 - Knowledge-aware: loads relevant knowledge files before planning, consolidates learnings after execution
+- Accepts Linear ticket IDs when task tracker is configured via `/ms:config` — auto-fetches context, tags commits, and finalizes the ticket on completion
 - Spawns Explore agents for codebase understanding, ms-adhoc-planner for plan creation, ms-executor for execution
 - Creates per-execution artifacts in `.planning/adhoc/{timestamp}-{slug}/`
 - Updates knowledge files via ms-consolidator after execution
 
 Usage: `/ms:adhoc Fix auth token not refreshing on 401`
+Usage: `/ms:adhoc MIN-123` (Linear ticket — auto-fetches context, finalizes on completion)
 Usage: `/ms:adhoc Refactor API error handling to use consistent format`
 
 ### Utility Commands
@@ -501,7 +503,7 @@ Optional: `/ms:config` — configure code reviewers, gitignore, and other prefer
 **Plan → execute loop (with optional quality gates):**
 
 ```
-/ms:plan-phase 5                 # Create one or more PLAN.md files
+/ms:plan-phase 5                 # Create PLAN.md file(s)
 /ms:execute-phase 5              # Execute; produces SUMMARY + VERIFICATION
 # If gaps found during verification, follow triage recommendation:
 # Small gaps:    /ms:adhoc "Close phase 5 gaps: ..."

package/commands/ms/insert-phase.md

@@ -6,19 +6,21 @@ allowed-tools:
   - Read
   - Write
   - Bash
+  - AskUserQuestion
 ---
 
 <objective>
-Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases, fully specified with goal, success criteria, and requirements.
 
-Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions. The phase is set up identically to phases created by the roadmapper — downstream commands work without degradation.
 
-Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap, with full pipeline support.
 </objective>
 
 <execution_context>
 @.planning/ROADMAP.md
 @.planning/STATE.md
+@.planning/REQUIREMENTS.md
 </execution_context>
 
 <process>
@@ -59,8 +61,8 @@ fi
 
 </step>
 
-<step name="load_roadmap">
-Load the roadmap file:
+<step name="load_context">
+Load project context:
 
 ```bash
 if [ -f .planning/ROADMAP.md ]; then
@@ -69,9 +71,33 @@ else
   echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
   exit 1
 fi
+
+if [ ! -f .planning/REQUIREMENTS.md ]; then
+  echo "ERROR: No REQUIREMENTS.md found"
+  exit 1
+fi
+```
+
+If REQUIREMENTS.md is missing, display:
+
+```
+Phase insertion requires an active milestone with requirements tracking.
+No .planning/REQUIREMENTS.md found.
+
+Instead, consider:
+- `/ms:new-milestone` — start a new milestone with requirements
+- `/ms:create-roadmap` — if milestone context exists but roadmap wasn't created yet
+- `/ms:adhoc "<description>"` — for work that doesn't need milestone tracking
 ```
 
-Read roadmap content for parsing.
+Exit command.
+
+Read ROADMAP.md and REQUIREMENTS.md.
+
+From REQUIREMENTS.md, extract:
+- Existing REQ-ID categories and their prefixes (e.g., AUTH, SUB, CONTENT)
+- Highest REQ-ID number per category (e.g., AUTH-04 → next is AUTH-05)
+- Traceability table structure
 </step>
 
 <step name="verify_target_phase">
@@ -88,7 +114,7 @@ Verify that the target phase exists in the roadmap:
    Exit.
 
 3. Verify phase is in current milestone (not completed/archived)
-   </step>
+</step>
 
 <step name="find_existing_decimals">
 Find existing decimal phases after the target phase:
@@ -107,6 +133,14 @@ Examples:
 Store as: `decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"`
 </step>
 
+<step name="derive_phase_specification">
+Read `~/.claude/mindsystem/references/derive-phase-specification.md` and follow its algorithm.
+
+Variables: `{PHASE_ID}` = `{decimal_phase}`, `{PHASE_MARKER}` = `(INSERTED)`.
+
+Input: user's description + project context (PROJECT.md, ROADMAP.md phases, REQUIREMENTS.md categories).
+</step>
+
 <step name="generate_slug">
 Convert the phase description to a kebab-case slug:
 
@@ -129,46 +163,44 @@ mkdir -p "$phase_dir"
 Confirm: "Created directory: $phase_dir"
 </step>
 
-<step name="update_roadmap">
-Insert the new phase entry into the roadmap:
-
-1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
+<step name="update_requirements">
+Follow the requirements update procedure in `~/.claude/mindsystem/references/derive-phase-specification.md`.
 
-2. Before writing the phase entry, analyze the description to determine pre-work flags:
+Use Phase `{decimal_phase}` for traceability table references and footer dating.
+</step>
 
-   **Discuss**: Default Likely — enumerate 2-4 assumptions or open questions specific
-   to the phase. Unlikely only for fully mechanical zero-decision work (version bump,
-   rename-only refactor, config-only change, pure deletion/cleanup).
+<step name="update_roadmap">
+Insert the new phase entry into the roadmap:
 
-   **Design**: Likely when description involves UI work, visual elements, forms,
-   dashboards, or multi-screen flows. Unlikely for backend-only, API, infrastructure,
-   or established UI patterns.
+**1. Find insertion point:** immediately after Phase {after_phase}'s content (and any existing decimals), before next integer phase heading or "---".
 
-   **Research**: Likely when description mentions external APIs/services, new
-   libraries/frameworks, or unclear technical approach. Unlikely for established
-   internal patterns or well-documented conventions.
+**2. Add phase details:**
 
-   Use binary Likely/Unlikely with parenthetical reason. Include topics/focus only when Likely.
+Insert full phase entry matching roadmapper format with (INSERTED) marker:
 
-3. Insert new phase heading with (INSERTED) marker and pre-work flags:
+```
+### Phase {decimal_phase}: {Name} (INSERTED)
+**Goal**: {approved goal}
+**Depends on**: Phase {after_phase}
+**Requirements**: {REQ-IDs comma-separated}
+**Success Criteria** (what must be TRUE):
+  1. {criterion}
+  2. {criterion}
+  3. {criterion}
+**Discuss**: {Likely (reason) | Unlikely (reason)}
+**Discuss topics**: {topics} ← only if Likely
+**Design**: {Likely (reason) | Unlikely (reason)}
+**Design focus**: {focus} ← only if Likely
+**Research**: {Likely (reason) | Unlikely (reason)}
+**Research topics**: {topics} ← only if Likely
+```
 
-   ```
-   ### Phase {decimal_phase}: {Description} (INSERTED)
-
-   **Goal:** [Urgent work - to be planned]
-   **Depends on:** Phase {after_phase}
-   **Discuss**: {Likely (reason) | Unlikely (reason)}
-   **Discuss topics**: {topics} ← only if Likely
-   **Design**: {Likely (reason) | Unlikely (reason)}
-   **Design focus**: {focus} ← only if Likely
-   **Research**: {Likely (reason) | Unlikely (reason)}
-   **Research topics**: {topics} ← only if Likely
-
-   **Details:**
-   [To be added during planning]
-   ```
+**3. Update progress table** — insert row in correct position:
+```
+| {decimal_phase}. {Name} (INSERTED) | Not started | - |
+```
 
-4. Write updated roadmap back to file
+Write updated roadmap back to file.
 
 The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
 
@@ -194,14 +226,17 @@ Present completion summary:
 
 ```
 Phase {decimal_phase} inserted after Phase {after_phase}:
-- Description: {description}
+- Goal: {goal}
+- Requirements: {REQ-IDs}
+- Success criteria: {count}
 - Directory: .planning/phases/{decimal-phase}-{slug}/
 - Status: Not planned yet
 - Marker: (INSERTED) - indicates urgent work
 
-Roadmap updated: {roadmap-path}
-Project state updated: .planning/STATE.md
-
+Files updated:
+- .planning/ROADMAP.md
+- .planning/REQUIREMENTS.md
+- .planning/STATE.md
 ```
 
 Read `~/.claude/mindsystem/references/routing/next-phase-routing.md` and follow its instructions
@@ -227,15 +262,18 @@ ms-tools set-last-command "ms:insert-phase $ARGUMENTS"
 - Don't modify the target phase content
 - Don't create plans yet (that's /ms:plan-phase)
 - Don't commit changes (user decides when to commit)
-  </anti_patterns>
+- Don't write skeletal "[To be planned]" entries — derive a real goal and success criteria
+</anti_patterns>
 
 <success_criteria>
 Phase insertion is complete when:
 
-- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
-- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
-- [ ] Phase inserted in correct position (after target phase, before next integer phase)
+- [ ] Specification derived with outcome-focused goal and 2-5 observable success criteria
+- [ ] Requirements derived with REQ-IDs and REQUIREMENTS.md updated with traceability mapping
+- [ ] Phase directory and roadmap entry created with (INSERTED) marker and correct decimal number
+- [ ] Phase inserted after target phase, before next integer phase
+- [ ] Roadmap entry matches roadmapper format (Goal, Requirements, Success Criteria, pre-work flags)
 - [ ] STATE.md updated with roadmap evolution note
-- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] User approved specification before writing
 - [ ] User informed of next steps and dependency implications
-      </success_criteria>
+</success_criteria>

package/commands/ms/new-milestone.md

@@ -130,7 +130,7 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 6. **Adaptive depth based on response clarity:**
 
-   - **Clear, detailed response** → brief confirmation ("Sounds like you want X, Y, Z — let me confirm a few things"), then move toward Phase 3 quickly
+   - **Clear, detailed response** → brief confirmation ("Sounds like you want X, Y, Z — let me confirm a few things"), then build on what they shared rather than re-asking
    - **Vague response** → probe with AskUserQuestion, explore features, challenge vagueness
    - **External context shared** → integrate it, clarify implications, ask follow-ups
 
@@ -276,7 +276,9 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
 19. **Route to next step:**
 
-    Default to `/ms:research-milestone` — domain research improves roadmap quality for most milestones. Only recommend `/ms:create-roadmap` directly when the domain is clearly familiar, no open questions surfaced, and there are no external APIs, new libraries, or unfamiliar patterns involved.
+    Determine primary suggestion:
+    - Default: `/ms:research-milestone` — domain research improves roadmap quality for most milestones
+    - Only `/ms:create-roadmap` when domain is clearly familiar, no open questions surfaced, and no external APIs, new libraries, or unfamiliar patterns
 
     ```
     Milestone [Name] initialized.
@@ -289,17 +291,20 @@ Milestone name: $ARGUMENTS (optional — will emerge during discovery if not pro
 
     ## ▶ Next Up
 
-    `/ms:[recommended-command]` — [one-line reason from conversation]
+    `/ms:{suggested}` — [one-line reason from conversation]
 
     <sub>`/clear` first → fresh context window</sub>
 
     ---
 
-    **Also available:** `/ms:[alternative-command]` — [brief reason]
+    **Also available:**
+    - `/ms:{alternative}` — [brief reason]
 
     ---
     ```
 
+    `{suggested}` and `{alternative}` are always one of: `research-milestone`, `create-roadmap`.
+
 </process>
 
 <success_criteria>

package/commands/ms/plan-phase.md

@@ -19,7 +19,7 @@ allowed-tools:
 Create executable phase prompt with discovery, context injection, and task breakdown.
 
 Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
-Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
+Output: PLAN.md file(s) in the phase directory (single plan by default; multiple when multi_plan enabled)
 
 </objective>
 
@@ -86,7 +86,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
    - Perform mandatory discovery (Level 0-3 as appropriate)
    - Scan project history via context scanner script (prior decisions, issues, debug resolutions, adhoc learnings, cross-milestone patterns)
    - Break phase into tasks
-   - Propose plan grouping (plan boundaries, wave structure, budget estimates) for user review
+   - Determine plan grouping (single plan by default; multi-plan with user confirmation when enabled)
    - Discover relevant project skills, confirm with user
    - Hand off tasks + proposed grouping + confirmed skills to plan-writer subagent
    - Create PLAN.md file(s) with executable structure
@@ -94,7 +94,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 6. **Update last command:** `ms-tools set-last-command "ms:plan-phase $ARGUMENTS"`
 
 7. **Risk assessment**
-   - Calculate risk score from context already loaded (task count, plan count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains)
+   - Calculate risk score from context already loaded (task count, external services, CONTEXT.md, cross-cutting concerns, new deps, complex domains)
    - Present score + top factors via AskUserQuestion
    - Tier-based recommendation: Skip (0-39), Optional (40-69), Verify (70+)
    - If user chooses verify: spawn ms-plan-checker, surface results
@@ -103,7 +103,7 @@ Check for `.planning/codebase/` and load relevant documents based on phase type.
 
 <success_criteria>
 
-- One or more PLAN.md files created in .planning/phases/XX-name/
+- PLAN.md file(s) created in .planning/phases/XX-name/
 - Each plan has: Context, Changes, Verification, Must-Haves (pure markdown format)
 - Must-Haves derived as markdown checklist of user-observable truths
 - Changes are specific enough for Claude to execute

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 Derive Browser Checklist
+3. If still on app pages: auth valid, proceed to Derive User Journeys
 
 If `NO_STATE` or auth expired:
 1. Close headless browser
@@ -47,9 +47,9 @@ If `NO_STATE` or auth expired:
    ```
 5. If user skips: proceed to code_review, skip browser verification
 
-## Derive Browser Checklist
+## Derive User Journeys
 
-Transform SUMMARY.md accomplishments into a structured checklist for the browser verifier.
+Transform SUMMARY.md accomplishments into user journeys for the browser verifier.
 
 **Step 1: Read summaries**
 
@@ -62,29 +62,38 @@ For each SUMMARY, extract:
 - **mock_hints** frontmatter (if present) — specifically `external_data` entries
 - **key-files** frontmatter (if present) — for route inference
 
-**Step 3: Derive checklist items**
+**Step 3: Derive user journeys**
 
-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")
+For each user-observable accomplishment, derive a journey:
+- `name`: verb-first — what the user is trying to accomplish (e.g., "Create a new project via the Add button")
+- `start`: page reachable via sidebar/nav (NOT a deep URL)
+- `steps`: ordered actions — click, fill, submit, verify state change
+- `success`: what should be true after completing the journey
 - `needs_backend_data`: true/false (from mock_hints `external_data` entries)
 
+**Derivation rules:**
+- New pages/routes: journey starts from parent page, navigates via UI
+- Forms: MUST include fill AND submit
+- Toggles/filters: MUST include activate AND deactivate
+- CRUD: one journey per built operation
+- Modals: open, interact, confirm — not just "modal opens"
+
 **Step 4: Filter**
 
-Include: UI renders, navigation, forms, data display, visual states, user interactions.
+Include: UI renders, navigation, forms, data display, visual states, user interactions — each as a complete journey.
 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:
+Group journeys by starting area for efficient navigation. Format as a numbered list:
 
 ```
 1. **{name}**
-   Route: {route}
-   Expected: {expected}
-   Interaction: {interaction or "none"}
+   Start: {start page/area}
+   Steps:
+   - {action 1}
+   - {action 2}
+   Success: {what should be true after}
    Needs backend data: {yes/no}
 
 2. **{name}**
@@ -93,7 +102,7 @@ Group items by route for efficient navigation. Format as a numbered list:
 
 ## Spawn
 
-Spawn the browser verifier agent after auth is established and checklist is derived:
+Spawn the browser verifier agent after auth is established and journeys are derived:
 
 ```
 Task(
@@ -104,16 +113,16 @@ Dev URL: {dev_url}
 Auth state: .agent-browser-state.json
 Screenshots directory: {phase_dir}/screenshots
 
-## Browser Checklist
+## User Journeys
 
-{derived_checklist}
+{derived_journeys}
 
 ## 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.}
+{summary of which journeys need real backend data — from mock_hints external_data entries.
+Journeys 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/.
+Complete each user journey end-to-end. Save all screenshots to {phase_dir}/screenshots/.
 Fix trivial issues inline. Return structured report.",
   subagent_type="ms-browser-verifier"
 )
@@ -138,6 +147,6 @@ Report: "Browser verification: {N} issues found (see screenshots in {phase_dir}/
 Note issues for verify-work — these are candidates for manual UAT.
 
 **`all_passed`:**
-Report: "Browser verification: all {N} items passed"
+Report: "Browser verification: all {N} journeys passed"
 
 </browser_verification>