mindsystem-cc 3.21.0 → 3.22.1

package/mindsystem/workflows/execute-phase.md

@@ -274,34 +274,18 @@ grep "^status:" "$PHASE_DIR"/*-VERIFICATION.md | cut -d: -f2 | tr -d ' '
 | Status | Action |
 |--------|--------|
 | `passed` | Continue to code_review |
-| `human_needed` | Present items to user, get approval or feedback |
 | `gaps_found` | Present gap summary, offer `/ms:plan-phase {phase} --gaps` |
 
 **If passed:**
 
 Phase goal verified. Proceed to code_review.
 
-**If human_needed:**
+If the verifier's return includes "Items Not Verified Programmatically" (uncertain > 0), surface that section to the user before proceeding:
 
 ```markdown
-## ✓ Phase {X}: {Name} — Human Verification Required
-
-All automated checks passed. {N} items need human testing:
-
-### Human Verification Checklist
-
-{Extract from VERIFICATION.md human_verification section}
-
----
-
-**After testing:**
-- "approved" → continue to code_review
-- Report issues → will route to gap closure planning
+**Note:** {N} items could not be verified by structural checks alone. Consider `/ms:verify-work {phase}` to validate these through UAT.
 ```
 
-If user approves → continue to code_review.
-If user reports issues → treat as gaps_found.
-
 **If gaps_found:**
 
 Present gaps and offer next command:

package/mindsystem/workflows/map-codebase.md

@@ -96,18 +96,12 @@ Write these documents to .planning/codebase/:
 - STACK.md - Languages, runtime, frameworks, dependencies, configuration
 - INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
 
-After writing STACK.md, update config.json code_review fields with the appropriate agent names:
-1. Read STACK.md to detect primary framework
-2. Map framework to code review agent names:
-   - Flutter/Dart:
-     - adhoc: "ms-flutter-code-quality"
-     - phase: "ms-flutter-code-quality"
-     - milestone: "ms-flutter-reviewer"
-   - All others (React, Next.js, Node, Swift, Kotlin, etc.):
-     - adhoc: "ms-code-simplifier"
-     - phase: "ms-code-simplifier"
-     - milestone: (leave as null — runtime defaults to ms-flutter-reviewer)
-3. If .planning/config.json exists: update all three code_review fields
+After writing STACK.md, update config.json code_review fields with the default agent names:
+1. Default for all frameworks:
+   - adhoc: "ms-code-simplifier"
+   - phase: "ms-code-simplifier"
+   - milestone: null
+2. If .planning/config.json exists: update all three code_review fields
    If not: note the recommended code review agents for later config creation
 
 Explore thoroughly. Write documents directly using templates. Return confirmation only.

package/mindsystem/workflows/mockup-generation.md

@@ -6,8 +6,6 @@ Called by design-phase command (step 4b) when user opts into mockup generation.
 
 <required_reading>
 @~/.claude/mindsystem/references/design-directions.md
-@~/.claude/mindsystem/templates/mockup-mobile.md (if mobile)
-@~/.claude/mindsystem/templates/mockup-web.md (if web)
 </required_reading>
 
 <process>
@@ -82,17 +80,18 @@ 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.
 mkdir -p "${PHASE_DIR}/mockups"
 ```
 
 Spawn 3 ms-mockup-designer agents IN PARALLEL, each receiving:
-- `<product_context>` — From PROJECT.md
-- `<phase_context>` — From ROADMAP.md phase entry
-- `<design_direction>` — One of the 3 derived directions (name, philosophy, concrete choices)
-- `<platform>` — `mobile` or `web`
-- `<feature_grounding>` — The screen/feature being mocked
-- `<existing_aesthetic>` — Colors/fonts from project UI skill or codebase (if exists)
-- `<mockup_template>` — The HTML scaffold from the template file
+- `<product_context>` — from PROJECT.md "What This Is" section
+- `<phase_context>` — from ROADMAP.md phase entry
+- `<design_direction>` — one of the 3 directions from `derive_directions` (name, philosophy, concrete choices)
+- `<platform>` — `mobile` or `web` from `determine_platform`
+- `<feature_grounding>` — screen/feature identified in `identify_primary_screen`
+- `<existing_aesthetic>` — from project UI skill (`SKILL.md` with design tokens) if exists, else scan codebase theme/style files for colors and fonts. If greenfield, state "No existing aesthetic."
+- `<mockup_template>` — HTML scaffold from `read_template`
 - Output path: `.planning/phases/{phase}-{slug}/mockups/variant-a.html` (b, c for others)
 
 ```
@@ -107,13 +106,24 @@ After all 3 agents return, run the comparison script to create the comparison pa
 
 ```bash
 ms-compare-mockups "${PHASE_DIR}/mockups"
-open "${PHASE_DIR}/mockups/comparison.html"
 ```
 
-Display summary:
+Read the `open_mockups` config setting:
+
+```bash
+OPEN_MOCKUPS=$(cat .planning/config.json 2>/dev/null | jq -r '.open_mockups // "auto"')
+```
+
+Branch on the value:
+
+- **`"auto"` (default):** Run `open "${PHASE_DIR}/mockups/comparison.html"`. Display summary with "comparison page opened in browser."
+- **`"ask"`:** Display summary with "comparison page ready." Ask "Open mockup comparison in browser?" (Yes/No). If Yes, run `open`.
+- **`"off"`:** Display summary with explicit comparison page path. No open.
+
+**Summary template** (adapt first line per branch above):
 
 ```markdown
-3 mockup variants generated — comparison page opened in browser.
+3 mockup variants generated — {status line from branch}.
 
 Individual variants for reference:
 - **A: {Direction A name}** — `.planning/phases/{phase}-{slug}/mockups/variant-a.html`
@@ -121,7 +131,7 @@ Individual variants for reference:
 - **C: {Direction C name}** — `.planning/phases/{phase}-{slug}/mockups/variant-c.html`
 ```
 
-Use AskUserQuestion:
+**After displaying summary**, use AskUserQuestion:
 > "Which direction works best?"
 > 1. **A: {name}** — Use this direction
 > 2. **B: {name}** — Use this direction
@@ -145,15 +155,29 @@ Handle user response:
 </step>
 
 <step name="extract_specs">
-Read the chosen HTML file. Extract from the inline CSS:
-- Direction name and description (from the derived direction that was selected)
-- Color palette — `background`, `color`, CSS custom properties, repeated accent values
-- Layout structure — container arrangement (sidebar/topnav/stacked, grid/list)
-- Typography — `font-size`, `font-weight`, `line-height` from headings and body
-- Spacing — `padding`, `gap`, `margin` values used consistently
-- User preferences (any specific feedback from selection)
-
-Assemble into a `<mockup_direction>` block for ms-designer. See the `<mockup_direction>` template in `design-phase.md` step 5 for the expected format.
+Read the chosen HTML file. Extract from the inline CSS and assemble into a `<mockup_direction>` block with this exact structure:
+
+```xml
+<mockup_direction>
+Direction: [chosen direction name]
+Philosophy: [direction one-sentence philosophy]
+
+Color palette:
+[Extracted hex values — background, text, accent, secondary from `background`, `color`, CSS custom properties, repeated accent values]
+
+Layout structure:
+[Container arrangement from CSS — sidebar/topnav/stacked, grid/list]
+
+Typography:
+[`font-size`, `font-weight`, `line-height` from headings and body]
+
+Spacing:
+[`padding`, `gap`, `margin` values used consistently]
+
+User preferences:
+[Any specific feedback from mockup selection — "I liked X but want Y changed"]
+</mockup_direction>
+```
 
 Return this block to the design-phase orchestrator.
 </step>

package/mindsystem/workflows/plan-phase.md

@@ -447,9 +447,15 @@ Tasks: {task_ids} — {brief rationale}
 **Waves:** {wave structure}
 ```
 
-The user may adjust, merge, or split plans. Once confirmed (or if the user proceeds without objection), pass the proposed grouping to the plan-writer.
-
 **TDD plans are always standalone** — propose them as dedicated plans regardless of budget.
+
+**Confirm via AskUserQuestion:**
+- header: "Plan Structure"
+- question: "Does this plan structure look good?"
+- Options: "Looks good, proceed", "Adjust grouping"
+
+**"Looks good, proceed":** Continue to discover_skills.
+**"Adjust grouping":** User describes changes in free-text. Apply adjustments, re-present, and confirm again.
 </step>
 
 <step name="discover_skills">
@@ -462,9 +468,10 @@ After the user confirms the plan structure, check if project skills could improv
 - The domain of the tasks identified (UI patterns, API design, state management, etc.)
 - Keywords from RESEARCH.md or CONTEXT.md if they exist
 
-**If matches found:** Present via AskUserQuestion:
-- List each matching skill with its description
-- Always include an escape hatch option for the user to name skills manually or skip entirely
+**If matches found:** Present via AskUserQuestion with `multiSelect: true`:
+- Each matching skill is one option (label: skill name, description: what it provides)
+- Always include a "None — skip skill loading" option
+- User selects which to load, skips, or types a skill name in the free-text field
 
 **If no matches:** Skip silently — no need to ask the user.
 

package/mindsystem/workflows/verify-work.md

@@ -175,21 +175,27 @@ Each batch has: batch number, name, mock_type, and test list.
 </step>
 
 <step name="create_uat_file">
-**Create UAT file:**
+**Create UAT file via ms-tools:**
+
+Construct JSON from classified tests and batch data, pipe to `uat-init`:
 
 ```bash
-mkdir -p "$PHASE_DIR"
+ms-tools uat-init $PHASE_NUMBER <<'EOF'
+{"source":["XX-01-SUMMARY.md"],"tests":[{"name":"...","expected":"...","mock_required":false,"mock_type":null}],"batches":[{"name":"No Mocks","mock_type":null,"tests":[1,2]}]}
+EOF
 ```
 
-Create file at `.planning/phases/XX-name/{phase}-UAT.md` following the template structure in context. Populate with classified tests and batch data from previous steps.
+- `source`: list of SUMMARY.md filenames tested
+- `tests`: array of `{name, expected, mock_required, mock_type}` from classification
+- `batches`: array of `{name, mock_type, tests: [nums]}` from batch grouping
 
-Proceed to `execute_batch`.
+stdout confirms path and counts. Proceed to `execute_batch`.
 </step>
 
 <step name="execute_batch">
 **Execute current batch:**
 
-Read current batch from UAT.md.
+Read current batch from UAT.md (test descriptions needed for presenting to user).
 
 **1. Handle mock generation (if needed):**
 
@@ -198,7 +204,7 @@ If `mock_type` is not null AND different from previous batch:
   ```bash
   git checkout -- <mocked_files>
   ```
-- Clear `mocked_files` in frontmatter
+- Clear mocked_files: `ms-tools uat-update $PHASE_NUMBER --session mocked_files=`
 - Go to `generate_mocks`
 
 If `mock_type` is null or same as previous:
@@ -314,11 +320,24 @@ For each question:
 | color, font, spacing, alignment, visual | cosmetic |
 | Default | major |
 
-**Update UAT.md after processing all responses in batch:**
-- Update each test's result
-- Update Progress counts
-- Update Batches section
-- Update timestamp
+**Update UAT.md via ms-tools after processing each response:**
+
+```bash
+# Pass:
+ms-tools uat-update $PHASE_NUMBER --test N result=pass
+
+# Blocked:
+ms-tools uat-update $PHASE_NUMBER --test N result=blocked
+
+# Skipped:
+ms-tools uat-update $PHASE_NUMBER --test N result=skipped
+echo '{"test":N,"name":"...","expected":"...","reason":"..."}' | ms-tools uat-update $PHASE_NUMBER --append-assumption
+
+# Issue:
+ms-tools uat-update $PHASE_NUMBER --test N result=issue reported="user description" severity=major fix_status=investigating retry_count=0
+```
+
+Progress auto-recalculates on every `uat-update` call. No manual progress recalculation needed.
 
 **For each issue found:** Go to `investigate_issue` before processing next test.
 </step>
@@ -372,21 +391,31 @@ Use `mocked_files` list from UAT.md frontmatter.
 - Edit the file(s)
 - Test that fix compiles/runs
 
-**3. Commit with proper message:**
+**3. Commit (amend on retry when safe):**
 ```bash
 git add [specific files]
-git commit -m "fix({phase}-uat): {description}"
+
+# Check if this is a retry AND HEAD matches the test's previous fix_commit:
+PREV_FIX=$(ms-tools uat-status $PHASE_NUMBER | python3 -c "import sys,json; d=json.load(sys.stdin); t=[x for x in d['fixing_tests'] if x['num']==N]; print(t[0].get('fix_commit','') if t else '')" 2>/dev/null)
+HEAD_SHORT=$(git rev-parse --short HEAD)
+
+if [ "$PREV_FIX" = "$HEAD_SHORT" ] && [ -n "$PREV_FIX" ]; then
+  git commit --amend --no-edit
+else
+  git commit -m "fix({phase}-uat): {description}"
+fi
 ```
 
-**4. Record in UAT.md:**
-- Update test: `fix_status: applied`, `fix_commit: {hash}`
-- Append to Fixes Applied section:
-  ```yaml
-  - commit: {hash}
-    test: {N}
-    description: "{what was fixed}"
-    files: [{changed files}]
-  ```
+Safety: only amend if HEAD matches recorded fix_commit. If HEAD has moved (other fixes in between), create new commit.
+
+**4. Record in UAT.md via ms-tools:**
+```bash
+FIX_HASH=$(git rev-parse --short HEAD)
+ms-tools uat-update $PHASE_NUMBER --test N fix_status=applied fix_commit=$FIX_HASH
+echo '{"commit":"'$FIX_HASH'","test":N,"description":"what was fixed","files":["changed.ts"]}' | ms-tools uat-update $PHASE_NUMBER --append-fix
+```
+
+`append-fix` updates in-place if a fix for the same test already exists (amend support).
 
 **5. Restore mocks:**
 ```bash
@@ -459,7 +488,7 @@ Mocks are stashed — working tree is clean.
 **3. Handle fixer return:**
 
 **If FIX COMPLETE:**
-- Update UAT.md with fix details
+- Record fix via ms-tools (same as `apply_fix` step 4: `uat-update --test N` + `--append-fix`)
 - Restore mocks: `git stash pop`
 - Handle conflicts as in `apply_fix`
 - Request re-test
@@ -484,11 +513,15 @@ Mocks are stashed — working tree is clean.
 AskUserQuestion: Pass / Still broken / New issue.
 
 **If Pass:**
-- Update test: `result: pass`, `fix_status: verified`
+```bash
+ms-tools uat-update $PHASE_NUMBER --test N result=pass fix_status=verified
+```
 - Continue to next issue or next batch
 
 **If Still broken (retry_count < 2):**
-- Increment `retry_count` in UAT.md test entry
+```bash
+ms-tools uat-update $PHASE_NUMBER --test N retry_count=1
+```
 - Go back to `investigate_issue` with new context
 
 **If Still broken (retry_count >= 2):**
@@ -513,7 +546,12 @@ AskUserQuestion: Pass / Still broken / New issue.
 <step name="resume_from_file">
 **Resume testing from UAT file:**
 
-Read full UAT file.
+Use `uat-status` for compact status determination:
+```bash
+ms-tools uat-status $PHASE_NUMBER
+```
+
+Returns JSON with: `status`, `current_batch`, `total_batches`, `progress`, `mocked_files`, `fixing_tests`, `pending_tests`, `blocked_tests`, `pre_work_stash`, `path`.
 
 Check `mocked_files` — if non-empty, verify mocks are still present:
 ```bash
@@ -522,19 +560,17 @@ git diff --name-only
 If mocked files have uncommitted changes, mocks are still active — continue.
 If mocked files are clean, mocks were lost — regenerate for current batch.
 
-Find current position:
-- current_batch
-- Tests with `[pending]` or `blocked` or `fixing` status
+Read full UAT.md only if test descriptions needed (for re-presenting tests to user).
 
 Announce:
 ```
 Resuming: Phase {phase} UAT
-Batch: {current} of {total}
+Batch: {current_batch} of {total_batches}
 Progress: {tested}/{total}
 Issues being fixed: {fixing count}
 ```
 
-If `fix_status: fixing` exists, go to `handle_retest` for that issue.
+If `fixing_tests` is non-empty, go to `handle_retest` for that issue.
 Otherwise, go to `execute_batch`.
 </step>
 
@@ -548,17 +584,15 @@ If blocked tests exist AND no issues remain in `fixing` status:
 - Re-present the blocked tests via `present_tests`
 - Blocked tests were waiting on other issues to be fixed first
 
-**2. Update Batches section (when no blocked tests remain):**
+**2. Update batch and session via ms-tools (when no blocked tests remain):**
 
-```yaml
-### Batch {N}: [Name]
-tests: [...]
-status: complete
-mock_type: [...]
-passed: {count}
-issues: {count}
+```bash
+ms-tools uat-update $PHASE_NUMBER --batch N status=complete passed=X issues=Y
+ms-tools uat-update $PHASE_NUMBER --session current_batch=N+1
 ```
 
+The `--session current_batch=N` call auto-syncs the Current Batch section with the new batch's info.
+
 **If more batches remain:**
 - Increment current_batch
 - Check if next batch needs different mock_type
@@ -591,15 +625,12 @@ 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:**
-- status: complete
-- Clear current_batch, mocked_files
-- Final Progress counts
-
-**5. Commit UAT.md:**
+**4. Update UAT.md and commit together with STATE.md:**
 ```bash
-git add ".planning/phases/XX-name/{phase}-UAT.md"
-git commit -m "test({phase}): complete UAT - {passed} passed, {fixed} fixed, {skipped} assumptions"
+ms-tools uat-update $PHASE_NUMBER --session status=complete current_batch= mocked_files=
+ms-tools set-last-command "ms:verify-work $ARGUMENTS"
+git add "$PHASE_DIR/${PHASE}-UAT.md" .planning/STATE.md
+git commit -m "test(${PHASE}): complete UAT - {passed} passed, {fixed} fixed, {skipped} assumptions"
 ```
 
 **5.5. Update knowledge pitfalls (lightweight):**
@@ -653,28 +684,24 @@ Check if more phases remain in ROADMAP.md:
 **Issue adds:** reported, severity, fix_status (investigating | applied | verified), fix_commit, retry_count
 **Skipped adds:** reason
 
-**Write UAT.md after:**
-- Each batch of responses processed
-- Each fix applied
-- Each re-test completed
-- Session complete
-
-| Section | Rule | When |
-|---------|------|------|
-| Frontmatter.status | OVERWRITE | Phase transitions |
-| Frontmatter.current_batch | OVERWRITE | Batch transitions |
-| Frontmatter.mocked_files | OVERWRITE | Mock generation/cleanup |
-| Frontmatter.pre_work_stash | OVERWRITE | Dirty tree handling |
-| Frontmatter.updated | OVERWRITE | Every write |
-| Progress | OVERWRITE | After each test result |
-| Current Batch | OVERWRITE | Batch transitions |
-| Tests.{N}.result | OVERWRITE | When user responds |
-| Tests.{N}.fix_status | OVERWRITE | During fix flow |
-| Tests.{N}.fix_commit | OVERWRITE | After fix committed |
-| Tests.{N}.retry_count | OVERWRITE | On re-test failure |
-| Fixes Applied | APPEND | After each fix committed |
-| Batches.{N}.status | OVERWRITE | Batch transitions |
-| Assumptions | APPEND | When test skipped |
+**All UAT.md updates use ms-tools commands.** Never Read/Edit UAT.md manually for field updates.
+
+| Trigger | Command |
+|---------|---------|
+| User responds to test | `ms-tools uat-update $PHASE --test N result=pass` |
+| Issue found | `ms-tools uat-update $PHASE --test N result=issue severity=major fix_status=investigating retry_count=0` |
+| Fix applied | `ms-tools uat-update $PHASE --test N fix_status=applied fix_commit=HASH` |
+| Fix verified | `ms-tools uat-update $PHASE --test N result=pass fix_status=verified` |
+| Re-test failed | `ms-tools uat-update $PHASE --test N retry_count=N` |
+| Record fix | `echo '{"commit":"...","test":N,...}' \| ms-tools uat-update $PHASE --append-fix` |
+| Test skipped | `ms-tools uat-update $PHASE --test N result=skipped` + `--append-assumption` |
+| Batch complete | `ms-tools uat-update $PHASE --batch N status=complete passed=X issues=Y` |
+| Batch transition | `ms-tools uat-update $PHASE --session current_batch=N` |
+| Mock files changed | `ms-tools uat-update $PHASE --session mocked_files=a.dart,b.dart` |
+| Session complete | `ms-tools uat-update $PHASE --session status=complete current_batch= mocked_files=` |
+| Resume session | `ms-tools uat-status $PHASE` (read-only JSON) |
+
+Progress auto-recalculates on every `uat-update` call. Timestamp auto-updates on every write.
 </update_rules>
 
 <severity_inference>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.21.0",
+  "version": "3.22.1",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"