mindsystem-cc 4.2.0 → 4.3.0

package/mindsystem/workflows/discuss-phase.md

@@ -80,8 +80,9 @@ cat .planning/knowledge/{subsystem}.md 2>/dev/null
 Check if CONTEXT.md already exists for this phase:
 
 ```bash
-ls .planning/phases/${PHASE}-*/CONTEXT.md 2>/dev/null
-ls .planning/phases/${PHASE}-*/${PHASE}-CONTEXT.md 2>/dev/null
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field, PHASE from `phase` field (normalized, e.g. "02")
+ls ${PHASE_DIR}/*CONTEXT.md 2>/dev/null
 ```
 
 **If exists:**
@@ -242,10 +243,10 @@ Create CONTEXT.md capturing the user's vision and decisions.
 
 Use template from ~/.claude/mindsystem/templates/context.md
 
-**File location:** `.planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md`
+**File location:** `${PHASE_DIR}/${PHASE}-CONTEXT.md`
 
 **If phase directory doesn't exist yet:**
-Create it: `.planning/phases/${PHASE}-${SLUG}/`
+Create it using normalized `${PHASE}` from find-phase output: `.planning/phases/${PHASE}-${SLUG}/`
 
 Use roadmap phase name for slug (lowercase, hyphens).
 
@@ -271,7 +272,7 @@ Write file.
 Present CONTEXT.md summary:
 
 ```
-Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
+Created: ${PHASE_DIR}/${PHASE}-CONTEXT.md
 
 ## Vision
 [How they imagine it working]
@@ -279,32 +280,18 @@ Created: .planning/phases/${PHASE}-${SLUG}/${PHASE}-CONTEXT.md
 ## Essential
 [What must be nailed]
 
----
-
-## ▶ Next Up
-
-**Phase ${PHASE}: [Name]** — [Goal from ROADMAP.md]
-
-`/ms:plan-phase ${PHASE}`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- `/ms:research-phase ${PHASE}` — investigate unknowns
-- Review/edit CONTEXT.md before continuing
-
 ---
 ```
 
 </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 ${PHASE_DIR}/${PHASE}-CONTEXT.md .planning/STATE.md
 git commit -m "$(cat <<'EOF'
 docs(${PHASE}): capture phase context
 
@@ -315,20 +302,12 @@ Phase ${PHASE}: ${PHASE_NAME}
 EOF
 )"
 ```
-
-Confirm: "Committed: docs(${PHASE}): capture phase context"
 </step>
 
 <step name="show_prework_status">
 Read `~/.claude/mindsystem/references/prework-status.md` and present what's done vs still needed for this phase.
 </step>
 
-<step name="update_state">
-```bash
-ms-tools set-last-command "ms:discuss-phase ${PHASE}"
-```
-</step>
-
 </process>
 
 <success_criteria>

package/mindsystem/workflows/execute-phase.md

@@ -39,11 +39,9 @@ Options:
 Confirm phase exists and has plans:
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
-if [ -z "$PHASE_DIR" ]; then
-  echo "ERROR: No phase directory matching '${PHASE_ARG}'"
-  exit 1
-fi
+ms-tools find-phase "${PHASE_ARG}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
+# If dir is null, error: "No phase directory matching '${PHASE_ARG}'"
 
 PLAN_COUNT=$(ls -1 "$PHASE_DIR"/*-PLAN.md 2>/dev/null | wc -l | tr -d ' ')
 if [ "$PLAN_COUNT" -eq 0 ]; then
@@ -300,11 +298,13 @@ ms-tools browser-check
 
 **If exit 0 (READY):**
 
-Read `~/.claude/mindsystem/references/browser-verification.md` and follow its Auth Flow and Spawn sections.
+Ensure `$PHASE_DIR/*-SUMMARY.md` files are available (needed for checklist derivation — may already be in context from wave reports).
 
-After verifier returns, if fixes were made:
-- Report: "Browser verification: {N} issues found and fixed"
-- Include report summary in consolidator prompt (step `consolidate_knowledge`)
+Read `~/.claude/mindsystem/references/browser-verification.md` and follow its sections in order:
+1. **Auth Flow** — establish browser authentication
+2. **Derive Browser Checklist** — transform SUMMARYs into visual checklist items
+3. **Spawn** — launch verifier with derived checklist
+4. **Post-Verifier Handling** — route by report status
 
 **If exit 1 (MISSING_DEPS):**
 
@@ -509,23 +509,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/execute-plan.md

@@ -260,7 +260,9 @@ completed: YYYY-MM-DD
 ---
 ```
 
-**Subsystem:** Use inline `**Subsystem:**` metadata from plan header if present. Otherwise select from `ms-tools config-get subsystems`. If novel, append to config.json and log in decisions.
+**Subsystem:** Use inline `**Subsystem:**` metadata from plan header if present. Otherwise select the best match from `ms-tools config-get subsystems`.
+
+**Novel subsystem (safety net):** If the plan's work genuinely doesn't fit any existing subsystem, append: `ms-tools config-set subsystems --append "{name}"`. Use in SUMMARY frontmatter and log the addition in Decisions Made. This is a fallback — `create-roadmap` handles most subsystem additions proactively.
 
 **Mock hints:** Reflect on what you built. If UI with transient states (loading, animations, async transitions) or external data dependencies, populate accordingly. If purely backend or no async UI, write `mock_hints: none  # reason`. Always populate.
 

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/mockup-generation.md

@@ -79,8 +79,9 @@ Extract the HTML scaffold from the `<template>` block.
 
 <step name="spawn_agents">
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
-# Assumes single match. If empty, phase directory is missing — stop and report.
+ms-tools find-phase "${PHASE}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
+# If dir is null, phase directory is missing — stop and report.
 mkdir -p "${PHASE_DIR}/mockups"
 ```
 

package/mindsystem/workflows/verify-work.md

@@ -6,6 +6,7 @@ Complete verify-and-fix session: by session end, everything verified, issues fix
 
 <execution_context>
 <!-- mock-patterns.md loaded on demand for transient_state mocks (see generate_mocks step) -->
+<!-- knowledge files loaded on first fix attempt (see investigate_issue step) -->
 </execution_context>
 
 <process>
@@ -74,7 +75,8 @@ Provide a phase number to start testing (e.g., /ms:verify-work 4)
 **Find SUMMARY.md files for the phase:**
 
 ```bash
-PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1)
+ms-tools find-phase "${PHASE_ARG}"
+# Extract PHASE_DIR from the `dir` field of the JSON output
 ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
 ```
 
@@ -341,6 +343,19 @@ Progress auto-recalculates on every `uat-update` call. No manual progress recalc
 <step name="investigate_issue">
 **Investigate reported issue:**
 
+**0. Load knowledge (first issue only):**
+
+If this is the first issue requiring investigation in this session, load knowledge files now. On subsequent issues, knowledge is already in context — skip to step 1.
+
+```bash
+ms-tools config-get subsystems
+grep "^subsystem:" "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null
+```
+
+Match SUMMARY.md subsystem values against config subsystems. Read matching `.planning/knowledge/{subsystem}.md` files (1-3 most relevant).
+
+This knowledge informs investigation (where to look, known pitfalls) and any subsequent fixes.
+
 **1. Lightweight investigation (2-3 tool calls):**
 
 ```
@@ -440,6 +455,10 @@ You are a Mindsystem verify-fixer. Investigate this issue, find the root cause,
 
 {lightweight_investigation_results}
 
+## Knowledge Context
+
+{loaded_knowledge_content or "No knowledge files loaded for this session."}
+
 ## Your task
 
 1. Investigate to find root cause
@@ -590,7 +609,7 @@ PRE_WORK_STASH=$(git stash list | grep "pre-verify-work" | head -1 | cut -d: -f1
 [ -n "$PRE_WORK_STASH" ] && git stash pop "$PRE_WORK_STASH"
 ```
 
-**4. Update UAT.md and commit together with STATE.md:**
+**4. Update state and commit:**
 ```bash
 ms-tools uat-update $PHASE_NUMBER --session status=complete current_batch= mocked_files=
 ms-tools set-last-command "ms:verify-work $ARGUMENTS"

package/package.json

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

package/scripts/ms-tools.py

@@ -1198,6 +1198,7 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
 
     # ---- CHECK 11: Browser Verification ----
     print("=== Browser Verification ===")
+    is_web, web_signal = False, "not checked"
     bv_enabled = True
     bv_config = config.get("browser_verification", {})
     if isinstance(bv_config, dict):
@@ -1233,6 +1234,28 @@ def cmd_doctor_scan(args: argparse.Namespace) -> None:
                 record("PASS", "Browser Verification")
     print()
 
+    # ---- CHECK 12: Screenshot Optimization ----
+    print("=== Screenshot Optimization ===")
+    if not bv_enabled:
+        print("Status: SKIP")
+        print("Browser verification disabled")
+        record("SKIP", "Screenshot Optimization")
+    elif not is_web:
+        print("Status: SKIP")
+        print(f"Not a web project ({web_signal})")
+        record("SKIP", "Screenshot Optimization")
+    else:
+        if shutil.which("cwebp"):
+            print("Status: PASS")
+            print("cwebp available — screenshots will be converted to WebP")
+            record("PASS", "Screenshot Optimization")
+        else:
+            print("Status: WARN")
+            print("cwebp not found — browser screenshots will remain as PNG (larger files)")
+            print("Install: brew install webp | apt install webp | choco install webp")
+            record("WARN", "Screenshot Optimization")
+    print()
+
     # ---- SUMMARY ----
     total = pass_count + warn_count + fail_count + skip_count
     print("=== Summary ===")
@@ -3126,7 +3149,7 @@ def _load_uat(args_phase: str) -> tuple[Path, "UATFile"]:
     if phase_dir is None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)
@@ -3166,7 +3189,7 @@ def cmd_uat_init(args: argparse.Namespace) -> None:
     phase_name = phase_dir.name
     uat = UATFile.from_init_json(data, phase_name)
 
-    out_path = phase_dir / f"{phase_name}-UAT.md"
+    out_path = phase_dir / f"{phase}-UAT.md"
     out_path.write_text(uat.serialize(), encoding="utf-8")
 
     n_tests = len(uat.tests)
@@ -3196,7 +3219,7 @@ def cmd_uat_update(args: argparse.Namespace) -> None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
 
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)
@@ -3264,7 +3287,7 @@ def cmd_uat_status(args: argparse.Namespace) -> None:
         print(f"Error: Phase directory not found for {phase}", file=sys.stderr)
         sys.exit(1)
 
-    uat_path = phase_dir / f"{phase_dir.name}-UAT.md"
+    uat_path = phase_dir / f"{phase}-UAT.md"
     if not uat_path.is_file():
         print(f"Error: UAT file not found: {uat_path}", file=sys.stderr)
         sys.exit(1)