mindsystem-cc 4.1.2 → 4.2.1

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

@@ -0,0 +1,143 @@
+<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 Derive Browser Checklist
+
+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
+
+## 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 and checklist is derived:
+
+```
+Task(
+  prompt="Run browser verification for phase {phase_number}.
+
+Phase directory: {phase_dir}
+Dev URL: {dev_url}
+Auth state: .agent-browser-state.json
+Screenshots directory: {phase_dir}/screenshots
+
+## 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"
+)
+```
+
+## 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.
+
+**`all_passed`:**
+Report: "Browser verification: all {N} items passed"
+
+</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/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/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/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/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,40 @@ 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):**
+
+Ensure `$PHASE_DIR/*-SUMMARY.md` files are available (needed for checklist derivation — may already be in context from wave reports).
+
+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):**
+
+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 +345,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 +481,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/"
@@ -477,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,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.1",
+  "description": "The engineer's meta-prompting system for Claude Code.",
   "bin": {
     "mindsystem-cc": "bin/install.js"
   },