mindsystem-cc 3.10.1 → 3.11.0

package/mindsystem/references/mock-patterns.md

@@ -16,6 +16,47 @@ Without mocks, testing "error message display" requires actually triggering serv
 4. **Removable** — Delete file + remove imports = clean
 </philosophy>
 
+<classification_framework>
+
+**Two-question framework for mock classification:**
+
+For each test, ask two questions in order:
+
+1. **Is the observable state transient?**
+   - Does it appear briefly during async operations? (loading skeleton, spinner, transition animation)
+   - Does it require precise timing to observe? (appears for <1s before real data loads)
+   - If YES → `mock_type: "transient_state"` — needs delay/force mock strategy
+
+2. **Does the test depend on external data?**
+   - Does the feature fetch from an API, database, or external service?
+   - Would the test fail without specific data existing locally?
+   - If YES → `mock_type: "external_data"` — confirm data availability with user first
+
+**Two-tier classification priority:**
+
+| Priority | Source | When used |
+|----------|--------|-----------|
+| 1 | SUMMARY.md `mock_hints` | Executor captured hints at build time (including `none` for explicit no-mock) |
+| 2 | Inline classification + keyword heuristics | No `mock_hints` key (legacy summaries) — classify in main context using two-question framework + keywords |
+
+**Why keyword matching alone fails:**
+
+Domain terms don't map reliably to mock types. "View recipe list" needs external_data mocks but contains no keywords. "Loading skeleton" is transient_state but keyword matching might miss the underlying async dependency. The two-question framework traces UI elements to their data sources instead of pattern-matching descriptions.
+
+**Category examples:**
+
+| Test | Classification | Reasoning |
+|------|---------------|-----------|
+| "Recipe list loading skeleton" | transient_state | Brief UI state during async fetch — resolves in <1s |
+| "View recipe list" | external_data | Fetches from /api/recipes — data may not exist locally |
+| "Login error message" | error_state | Error response from auth endpoint |
+| "Empty favorites placeholder" | empty_response | Requires zero items in collection |
+| "Premium badge display" | premium_user | Requires premium subscription state |
+| "Offline sync indicator" | offline_state | Requires network disconnection |
+| "Tap login button" | no mock needed | Happy path with available test credentials |
+
+</classification_framework>
+
 <git_stash_lifecycle>
 
 **Why stash?**
@@ -95,10 +136,12 @@ class TestOverrides {
   static bool forceErrorState = false;
   static bool forceEmptyResponse = false;
   static bool forceLoadingState = false;
+  static bool forceTransientState = false;
 
   // === MOCK DATA ===
   static String mockErrorMessage = 'Simulated error for testing';
   static Duration mockLoadingDelay = const Duration(seconds: 3);
+  static Duration mockTransientDelay = const Duration(seconds: 5);
 
   static Map<String, dynamic> mockPremiumUser = {
     'id': 'test-user-001',
@@ -113,6 +156,7 @@ class TestOverrides {
     forceErrorState = false;
     forceEmptyResponse = false;
     forceLoadingState = false;
+    forceTransientState = false;
   }
 }
 ```
@@ -142,6 +186,10 @@ class UserService {
     if (TestOverrides.forceErrorState) {
       throw Exception(TestOverrides.mockErrorMessage);
     }
+    // TEST OVERRIDE - Extend transient state (loading skeleton stays visible)
+    if (TestOverrides.forceTransientState) {
+      await Future.delayed(TestOverrides.mockTransientDelay);
+    }
 
     // Real implementation
     final response = await _api.get('/items');

package/mindsystem/references/plan-format.md

@@ -21,7 +21,6 @@ type: execute
 wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan time.
 depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"])
 files_modified: []          # Files this plan modifies
-autonomous: true            # false if plan has checkpoints
 ---
 ```
 
@@ -33,12 +32,9 @@ autonomous: true            # false if plan has checkpoints
 | `wave` | Yes | Execution wave number (1, 2, 3...). Pre-computed during planning. |
 | `depends_on` | Yes | Array of plan IDs this plan requires. |
 | `files_modified` | Yes | Files this plan touches. |
-| `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `subsystem_hint` | No | Subsystem from config.json, assigned by planner for executor to use in SUMMARY.md |
 
 **Wave is pre-computed:** `/ms:plan-phase` assigns wave numbers based on `depends_on`. `/ms:execute-phase` reads `wave` directly from frontmatter and groups plans by wave number. No runtime dependency analysis needed.
-
-**Checkpoint handling:** Plans with `autonomous: false` require user interaction. They run in their assigned wave but pause at checkpoints.
 </frontmatter>
 
 <prompt_structure>
@@ -52,7 +48,6 @@ type: execute
 wave: N
 depends_on: []
 files_modified: [path/to/file.ts]
-autonomous: true
 ---
 
 <objective>
@@ -64,8 +59,6 @@ Output: [...]
 <execution_context>
 @~/.claude/mindsystem/workflows/execute-plan.md
 @~/.claude/mindsystem/templates/summary.md
-[If checkpoints exist:]
-@~/.claude/mindsystem/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -86,21 +79,6 @@ Output: [...]
   <done>[criteria]</done>
 </task>
 
-<task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[what Claude automated]</what-built>
-  <how-to-verify>[numbered verification steps]</how-to-verify>
-  <resume-signal>[how to continue - "approved" or describe issues]</resume-signal>
-</task>
-
-<task type="checkpoint:decision" gate="blocking">
-  <decision>[what needs deciding]</decision>
-  <context>[why this matters]</context>
-  <options>
-    <option id="option-a"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
-    <option id="option-b"><name>[Name]</name><pros>[pros]</pros><cons>[cons]</cons></option>
-  </options>
-  <resume-signal>[how to indicate choice]</resume-signal>
-</task>
 </tasks>
 
 <verification>
@@ -186,114 +164,9 @@ Tasks have a `type` attribute that determines how they execute:
 Use for: Everything Claude can do independently (code, tests, builds, file operations).
 </type>
 
-<type name="checkpoint:human-action">
-**RARELY USED** - Only for actions with NO CLI/API. Claude automates everything possible first.
-
-**Structure:**
-
-```xml
-<task type="checkpoint:human-action" gate="blocking">
-  <action>[Unavoidable manual step - email link, 2FA code]</action>
-  <instructions>
-    [What Claude already automated]
-    [The ONE thing requiring human action]
-  </instructions>
-  <verification>[What Claude can check afterward]</verification>
-  <resume-signal>[How to continue]</resume-signal>
-</task>
-```
-
-Use ONLY for: Email verification links, SMS 2FA codes, manual approvals with no API, 3D Secure payment flows.
-
-Do NOT use for: Anything with a CLI (Vercel, Stripe, Upstash, Railway, GitHub), builds, tests, file creation, deployments.
-
-**Execution:** Claude automates everything with CLI/API, stops only for truly unavoidable manual steps.
-</type>
-
-<type name="checkpoint:human-verify">
-**Human must verify Claude's work** - Visual checks, UX testing.
-
-**Structure:**
-
-```xml
-<task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard layout</what-built>
-  <how-to-verify>
-    1. Run: npm run dev
-    2. Visit: http://localhost:3000/dashboard
-    3. Desktop (>1024px): Verify sidebar left, content right
-    4. Tablet (768px): Verify sidebar collapses to hamburger
-    5. Mobile (375px): Verify single column, bottom nav
-    6. Check: No layout shift, no horizontal scroll
-  </how-to-verify>
-  <resume-signal>Type "approved" or describe issues</resume-signal>
-</task>
-```
-
-Use for: UI/UX verification, visual design checks, animation smoothness, accessibility testing.
-
-**Execution:** Claude builds the feature, stops, provides testing instructions, waits for approval/feedback.
-</type>
-
-<type name="checkpoint:decision">
-**Human must make implementation choice** - Direction-setting decisions.
-
-**Structure:**
-
-```xml
-<task type="checkpoint:decision" gate="blocking">
-  <decision>Select authentication provider</decision>
-  <context>We need user authentication. Three approaches with different tradeoffs:</context>
-  <options>
-    <option id="supabase">
-      <name>Supabase Auth</name>
-      <pros>Built-in with Supabase, generous free tier</pros>
-      <cons>Less customizable UI, tied to ecosystem</cons>
-    </option>
-    <option id="clerk">
-      <name>Clerk</name>
-      <pros>Beautiful pre-built UI, best DX</pros>
-      <cons>Paid after 10k MAU</cons>
-    </option>
-    <option id="nextauth">
-      <name>NextAuth.js</name>
-      <pros>Free, self-hosted, maximum control</pros>
-      <cons>More setup, you manage security</cons>
-    </option>
-  </options>
-  <resume-signal>Select: supabase, clerk, or nextauth</resume-signal>
-</task>
-```
-
-Use for: Technology selection, architecture decisions, design choices, feature prioritization.
-
-**Execution:** Claude presents options with balanced pros/cons, waits for decision, proceeds with chosen direction.
-</type>
-
-**When to use checkpoints:**
-
-- Visual/UX verification (after Claude builds) → `checkpoint:human-verify`
-- Implementation direction choice → `checkpoint:decision`
-- Truly unavoidable manual actions (email links, 2FA) → `checkpoint:human-action` (rare)
-
-**When NOT to use checkpoints:**
-
-- Anything with CLI/API (Claude automates it) → `type="auto"`
-- Deployments (Vercel, Railway, Fly) → `type="auto"` with CLI
-- Creating resources (Upstash, Stripe, GitHub) → `type="auto"` with CLI/API
-- File operations, tests, builds → `type="auto"`
-
-**Golden rule:** If Claude CAN automate it, Claude MUST automate it.
-
-**Checkpoint impact on parallelization:**
-- Plans with checkpoints set `autonomous: false` in frontmatter
-- Non-autonomous plans execute after parallel wave or in main context
-- Subagent pauses at checkpoint, returns to orchestrator
-- Orchestrator presents checkpoint to user
-- User responds
-- Orchestrator resumes agent with `resume: agent_id`
+**Golden rule:** If Claude CAN automate it, Claude MUST automate it. All tasks use `type="auto"`.
 
-See `./checkpoints.md` for comprehensive checkpoint guidance.
+**Decisions:** Resolve during planning via AskUserQuestion, not during execution. For purely technical choices, make the decision and document it in the plan's objective.
 </task_types>
 
 <tdd_plans>

package/mindsystem/references/scope-estimation.md

@@ -65,7 +65,7 @@ See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure.
 - **More than 3 tasks** - Even if tasks seem small
 - **Multiple subsystems** - DB + API + UI = separate plans
 - **Any task with >5 file modifications** - Split by file groups
-- **Checkpoint + implementation work** - Checkpoints in one plan, implementation after in separate plan
+- **Discovery + verification in separate plans** - Don't mix exploratory and implementation work
 - **Discovery + implementation** - DISCOVERY.md in one plan, implementation in another
 </always_split>
 
@@ -114,12 +114,12 @@ Plan 03: Visualization components
 # Independent plan (Wave 1 candidate)
 depends_on: []
 files_modified: [src/features/user/model.ts, src/features/user/api.ts]
-autonomous: true
+
 
 # Dependent plan (later wave)
 depends_on: ["03-01"]
 files_modified: [src/integration/stripe.ts]
-autonomous: true
+
 ```
 
 **Wave assignment rules:**

package/mindsystem/templates/config.json

@@ -4,8 +4,6 @@
   "parallelization": {
     "enabled": true,
     "plan_level": true,
-    "task_level": false,
-    "skip_checkpoints": true,
     "max_concurrent_agents": 3,
     "min_plans_for_parallel": 2
   },

package/mindsystem/templates/design.md

@@ -13,7 +13,7 @@ Template for `.planning/phases/XX-name/{phase}-DESIGN.md` - captures visual/UX d
 
 **Designed:** [date]
 **Platform:** [web / mobile / both]
-**Aesthetic source:** [implement-ui skill / codebase analysis / fresh design]
+**Aesthetic source:** [project UI skill / codebase analysis / fresh design]
 
 ## Visual Identity
 

package/mindsystem/templates/phase-prompt.md

@@ -16,7 +16,6 @@ type: execute
 wave: N                     # Execution wave (1, 2, 3...). Pre-computed at plan time.
 depends_on: []              # Plan IDs this plan requires (e.g., ["01-01"]).
 files_modified: []          # Files this plan modifies.
-autonomous: true            # false if plan has checkpoints requiring user interaction
 subsystem_hint: ""          # From planner, for executor SUMMARY.md
 user_setup: []              # Human-required setup Claude cannot automate (see below)
 
@@ -37,8 +36,6 @@ Output: [What artifacts will be created]
 <execution_context>
 @~/.claude/mindsystem/workflows/execute-plan.md
 @~/.claude/mindsystem/templates/summary.md
-[If plan contains checkpoint tasks (type="checkpoint:*"), add:]
-@~/.claude/mindsystem/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -73,35 +70,6 @@ Output: [What artifacts will be created]
   <done>[Acceptance criteria]</done>
 </task>
 
-<task type="checkpoint:decision" gate="blocking">
-  <decision>[What needs deciding]</decision>
-  <context>[Why this decision matters]</context>
-  <options>
-    <option id="option-a">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
-    <option id="option-b">
-      <name>[Option name]</name>
-      <pros>[Benefits and advantages]</pros>
-      <cons>[Tradeoffs and limitations]</cons>
-    </option>
-  </options>
-  <resume-signal>[How to indicate choice - "Select: option-a or option-b"]</resume-signal>
-</task>
-
-<task type="checkpoint:human-verify" gate="blocking">
-  <what-built>[What Claude just built that needs verification]</what-built>
-  <how-to-verify>
-    1. Run: [command to start dev server/app]
-    2. Visit: [URL to check]
-    3. Test: [Specific interactions]
-    4. Confirm: [Expected behaviors]
-  </how-to-verify>
-  <resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
-</task>
-
 </tasks>
 
 <verification>
@@ -136,7 +104,6 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 | `wave` | Yes | Execution wave number (1, 2, 3...). Pre-computed at plan time. |
 | `depends_on` | Yes | Array of plan IDs this plan requires. |
 | `files_modified` | Yes | Files this plan touches. |
-| `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
 | `subsystem_hint` | No | Subsystem from config.json, assigned by planner for executor to use in SUMMARY.md |
 | `user_setup` | No | Array of human-required setup items (external services) |
 | `must_haves` | Yes | Goal-backward verification criteria (see below) |
@@ -158,19 +125,16 @@ After completion, create `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 wave: 1
 depends_on: []
 files_modified: [src/models/user.ts, src/api/users.ts]
-autonomous: true
 
 # Plan 02 - Product feature (no overlap with Plan 01)
 wave: 1
 depends_on: []
 files_modified: [src/models/product.ts, src/api/products.ts]
-autonomous: true
 
 # Plan 03 - Order feature (no overlap)
 wave: 1
 depends_on: []
 files_modified: [src/models/order.ts, src/api/orders.ts]
-autonomous: true
 ```
 
 All three run in parallel (Wave 1) - no dependencies, no file conflicts.
@@ -182,28 +146,15 @@ All three run in parallel (Wave 1) - no dependencies, no file conflicts.
 wave: 1
 depends_on: []
 files_modified: [src/lib/auth.ts, src/middleware/auth.ts]
-autonomous: true
 
 # Plan 02 - Protected features (needs auth)
 wave: 2
 depends_on: ["01"]
 files_modified: [src/features/dashboard.ts]
-autonomous: true
 ```
 
 Plan 02 in Wave 2 waits for Plan 01 in Wave 1 - genuine dependency on auth types/middleware.
 
-**Checkpoint plan:**
-
-```yaml
-# Plan 03 - UI with verification
-wave: 3
-depends_on: ["01", "02"]
-files_modified: [src/components/Dashboard.tsx]
-autonomous: false  # Has checkpoint:human-verify
-```
-
-Wave 3 runs after Waves 1 and 2. Pauses at checkpoint, orchestrator presents to user, resumes on approval.
 
 </parallel_examples>
 
@@ -283,19 +234,12 @@ See `~/.claude/mindsystem/references/tdd.md` for TDD plan structure.
 
 ## Task Types
 
-| Type | Use For | Autonomy |
-|------|---------|----------|
-| `auto` | Everything Claude can do independently | Fully autonomous |
-| `checkpoint:human-verify` | Visual/functional verification | Pauses, returns to orchestrator |
-| `checkpoint:decision` | Implementation choices | Pauses, returns to orchestrator |
-| `checkpoint:human-action` | Truly unavoidable manual steps (rare) | Pauses, returns to orchestrator |
+| Type | Use For |
+|------|---------|
+| `auto` | Everything Claude can do independently (default) |
+| `tdd` | TDD features with RED → GREEN → REFACTOR cycle |
 
-**Checkpoint behavior in parallel execution:**
-- Plan runs until checkpoint
-- Agent returns with checkpoint details + agent_id
-- Orchestrator presents to user
-- User responds
-- Orchestrator resumes agent with `resume: agent_id`
+**Decisions:** Resolve during planning via AskUserQuestion, not during execution. For purely technical choices, make the decision and document it in the plan's objective.
 
 ---
 
@@ -311,7 +255,6 @@ type: execute
 wave: 1
 depends_on: []
 files_modified: [src/features/user/model.ts, src/features/user/api.ts, src/features/user/UserList.tsx]
-autonomous: true
 ---
 
 <objective>
@@ -360,76 +303,6 @@ After completion, create `.planning/phases/03-features/03-01-SUMMARY.md`
 </output>
 ```
 
-**Plan with checkpoint (non-autonomous):**
-
-```markdown
----
-phase: 03-features
-plan: 03
-type: execute
-wave: 2
-depends_on: ["03-01", "03-02"]
-files_modified: [src/components/Dashboard.tsx]
-autonomous: false
----
-
-<objective>
-Build dashboard with visual verification.
-
-Purpose: Integrate user and product features into unified view.
-Output: Working dashboard component.
-</objective>
-
-<execution_context>
-@~/.claude/mindsystem/workflows/execute-plan.md
-@~/.claude/mindsystem/templates/summary.md
-@~/.claude/mindsystem/references/checkpoints.md
-</execution_context>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@.planning/phases/03-features/03-01-SUMMARY.md
-@.planning/phases/03-features/03-02-SUMMARY.md
-</context>
-
-<tasks>
-<task type="auto">
-  <name>Task 1: Build Dashboard layout</name>
-  <files>src/components/Dashboard.tsx</files>
-  <action>Create responsive grid with UserList and ProductList components. Use Tailwind for styling.</action>
-  <verify>npm run build succeeds</verify>
-  <done>Dashboard renders without errors</done>
-</task>
-
-<task type="checkpoint:human-verify" gate="blocking">
-  <what-built>Responsive dashboard with user and product sections</what-built>
-  <how-to-verify>
-    1. Run: npm run dev
-    2. Visit: http://localhost:3000/dashboard
-    3. Desktop: Verify two-column grid
-    4. Mobile: Verify stacked layout
-    5. Check: No layout shift, no scroll issues
-  </how-to-verify>
-  <resume-signal>Type "approved" or describe issues</resume-signal>
-</task>
-</tasks>
-
-<verification>
-- [ ] npm run build succeeds
-- [ ] Visual verification passed
-</verification>
-
-<success_criteria>
-- All tasks completed
-- User approved visual layout
-</success_criteria>
-
-<output>
-After completion, create `.planning/phases/03-features/03-03-SUMMARY.md`
-</output>
-```
-
 ---
 
 ## Anti-Patterns
@@ -446,14 +319,6 @@ Plan 02: All APIs (depends on 01)
 Plan 03: All UIs (depends on 02)
 ```
 
-**Bad: Missing autonomy flag**
-```yaml
-# Has checkpoint but no autonomous: false
-depends_on: []
-files_modified: [...]
-# autonomous: ???  <- Missing!
-```
-
 **Bad: Vague tasks**
 ```xml
 <task type="auto">
@@ -467,10 +332,9 @@ files_modified: [...]
 ## Guidelines
 
 - Always use XML structure for Claude parsing
-- Include `wave`, `depends_on`, `files_modified`, `autonomous` in every plan
+- Include `wave`, `depends_on`, `files_modified` in every plan
 - Prefer vertical slices over horizontal layers
 - Only reference prior SUMMARYs when genuinely needed
-- Group checkpoints with related auto tasks in same plan
 - 2-3 tasks per plan, ~50% context max
 
 ---

package/mindsystem/templates/summary.md

@@ -38,6 +38,17 @@ patterns-established:
   - "Pattern 1: description"
   - "Pattern 2: description"
 
+# Verification hints (required — aids verify-work mock classification, use `none` if not applicable)
+mock_hints:
+  transient_states:
+    - state: "[description of transient UI state]"
+      component: "[file path]"
+      trigger: "[async call | animation | timer]"
+  external_data:
+    - source: "[API endpoint or data source]"
+      data_type: "[what kind of data]"
+      components: ["[file1]", "[file2]"]
+
 # Metrics
 duration: Xmin
 completed: YYYY-MM-DD
@@ -76,6 +87,17 @@ _Note: TDD tasks may have multiple commits (test → feat → refactor)_
 - `path/to/file.ts` - What it does
 - `path/to/another.ts` - What it does
 
+## Verification Hints
+
+[If phase built UI with transient states or external data dependencies, list them.
+If not applicable: "None — no transient states or external data dependencies."]
+
+**Transient states:** [States that appear briefly during async operations]
+- [state description] in `[component]` — triggered by [what]
+
+**External data:** [Features that fetch specific data from APIs]
+- [data type] from [source] — used by `[component1]`, `[component2]`
+
 ## Decisions Made
 [Key decisions with brief rationale, or "None - followed plan as specified"]
 
@@ -143,6 +165,8 @@ None - no external service configuration required.
 **Patterns:** Established conventions future phases should maintain.
 
 **Population:** Frontmatter is populated during summary creation in execute-plan.md. See `<step name="create_summary">` for field-by-field guidance.
+
+**Mock hints (required):** Captures verification-relevant knowledge about transient UI states and external data dependencies. Transient states are UI states that appear briefly (loading skeletons, animations, transitions) — verify-work needs these to generate mocks that force/extend the state. External data entries identify features depending on API data — verify-work uses these to ask the user whether test data exists locally. Populate when the phase builds UI with these characteristics. When a phase has no transient states or external data dependencies, write `mock_hints: none` (with optional comment, e.g., `mock_hints: none  # purely backend, no async UI`). Always populate — `none` is a valid value that tells verify-work to skip mock analysis.
 </frontmatter_guidance>
 
 <one_liner_rules>