mindsystem-cc 3.10.1 → 3.12.0

package/mindsystem/workflows/execute-plan.md

@@ -77,12 +77,6 @@ SUMMARY naming follows same pattern:
 
 Confirm with user if ambiguous.
 
-<config-check>
-```bash
-cat .planning/config.json 2>/dev/null
-```
-</config-check>
-
 ```
 ⚡ Auto-approved: Execute {phase}-{plan}-PLAN.md
 [Plan X of Y for Phase Z]
@@ -90,7 +84,7 @@ cat .planning/config.json 2>/dev/null
 Starting execution...
 ```
 
-Proceed directly to parse_segments step.
+Proceed directly to execution.
 </step>
 
 <step name="record_start_time">
@@ -104,166 +98,6 @@ PLAN_START_EPOCH=$(date +%s)
 Store in shell variables for duration calculation at completion.
 </step>
 
-<step name="parse_segments">
-**Intelligent segmentation: Parse plan into execution segments.**
-
-Plans are divided into segments by checkpoints. Each segment is routed to optimal execution context (subagent or main).
-
-**1. Check for checkpoints:**
-
-```bash
-# Find all checkpoints and their types
-grep -n "type=\"checkpoint" .planning/phases/XX-name/{phase}-{plan}-PLAN.md
-```
-
-**2. Analyze execution strategy:**
-
-**If NO checkpoints found:**
-
-- **Fully autonomous plan** - spawn single subagent for entire plan
-- Subagent gets fresh 200k context, executes all tasks, creates SUMMARY, commits
-- Main context: Just orchestration (~5% usage)
-
-**If checkpoints found, parse into segments:**
-
-Segment = tasks between checkpoints (or start→first checkpoint, or last checkpoint→end)
-
-**For each segment, determine routing:**
-
-```
-Segment routing rules:
-
-IF segment has no prior checkpoint:
-  → SUBAGENT (first segment, nothing to depend on)
-
-IF segment follows checkpoint:human-verify:
-  → SUBAGENT (verification is just confirmation, doesn't affect next work)
-
-IF segment follows checkpoint:decision OR checkpoint:human-action:
-  → MAIN CONTEXT (next tasks need the decision/result)
-```
-
-**3. Execution pattern:**
-
-**Pattern A: Fully autonomous (no checkpoints)**
-
-```
-Spawn subagent → execute all tasks → SUMMARY → commit → report back
-```
-
-**Pattern B: Segmented with verify-only checkpoints**
-
-```
-Segment 1 (tasks 1-3): Spawn subagent → execute → report back
-Checkpoint 4 (human-verify): Main context → you verify → continue
-Segment 2 (tasks 5-6): Spawn NEW subagent → execute → report back
-Checkpoint 7 (human-verify): Main context → you verify → continue
-Aggregate results → SUMMARY → commit
-```
-
-**Pattern C: Decision-dependent (must stay in main)**
-
-```
-Checkpoint 1 (decision): Main context → you decide → continue in main
-Tasks 2-5: Main context (need decision from checkpoint 1)
-No segmentation benefit - execute entirely in main
-```
-
-**4. Why this works:**
-
-**Segmentation benefits:**
-
-- Fresh context for each autonomous segment (0% start every time)
-- Main context only for checkpoints (~10-20% total)
-- Can handle 10+ task plans if properly segmented
-- Quality impossible to degrade in autonomous segments
-
-**When segmentation provides no benefit:**
-
-- Checkpoint is decision/human-action and following tasks depend on outcome
-- Better to execute sequentially in main than break flow
-
-**5. Implementation:**
-
-**For fully autonomous plans:**
-
-```
-1. Run init_agent_tracking step first (see step below)
-
-2. Use Task tool with subagent_type="ms-executor":
-
-   Prompt: "Execute plan at .planning/phases/{phase}-{plan}-PLAN.md
-
-   This is an autonomous plan (no checkpoints). Execute all tasks, create SUMMARY.md in phase directory, commit with message following plan's commit guidance.
-
-   Follow all deviation rules and authentication gate protocols from the plan.
-
-   When complete, report: plan name, tasks completed, SUMMARY path, commit hash."
-
-3. After Task tool returns with agent_id:
-
-   a. Write agent_id to current-agent-id.txt:
-      echo "[agent_id]" > .planning/current-agent-id.txt
-
-   b. Append spawn entry to agent-history.json:
-      {
-        "agent_id": "[agent_id from Task response]",
-        "task_description": "Execute full plan {phase}-{plan} (autonomous)",
-        "phase": "{phase}",
-        "plan": "{plan}",
-        "segment": null,
-        "timestamp": "[ISO timestamp]",
-        "status": "spawned",
-        "completion_timestamp": null
-      }
-
-4. Wait for subagent to complete
-
-5. After subagent completes successfully:
-
-   a. Update agent-history.json entry:
-      - Find entry with matching agent_id
-      - Set status: "completed"
-      - Set completion_timestamp: "[ISO timestamp]"
-
-   b. Clear current-agent-id.txt:
-      rm .planning/current-agent-id.txt
-
-6. Report completion to user
-```
-
-**For segmented plans (has verify-only checkpoints):**
-
-```
-Execute segment-by-segment:
-
-For each autonomous segment:
-  Spawn subagent with prompt: "Execute tasks [X-Y] from plan at .planning/phases/{phase}-{plan}-PLAN.md. Read the plan for full context and deviation rules. Do NOT create SUMMARY or commit - just execute these tasks and report results."
-
-  Wait for subagent completion
-
-For each checkpoint:
-  Execute in main context
-  Wait for user interaction
-  Continue to next segment
-
-After all segments complete:
-  Aggregate all results
-  Create SUMMARY.md
-  Commit with all changes
-```
-
-**For decision-dependent plans:**
-
-```
-Execute in main context (standard flow below)
-No subagent routing
-Quality maintained through small scope (2-3 tasks per plan)
-```
-
-See step name="segment_execution" for detailed segment execution loop.
-</step>
-
 <step name="init_agent_tracking">
 **Initialize agent tracking for subagent resume capability.**
 
@@ -312,194 +146,6 @@ If agent-history.json has more than `max_entries`:
 - Pattern C (main context): Skip - no subagents spawned
 </step>
 
-<step name="segment_execution">
-**Detailed segment execution loop for segmented plans.**
-
-**This step applies ONLY to segmented plans (Pattern B: has checkpoints, but they're verify-only).**
-
-For Pattern A (fully autonomous) and Pattern C (decision-dependent), skip this step.
-
-**Execution flow:**
-
-````
-1. Parse plan to identify segments:
-   - Read plan file
-   - Find checkpoint locations: grep -n "type=\"checkpoint" PLAN.md
-   - Identify checkpoint types: grep "type=\"checkpoint" PLAN.md | grep -o 'checkpoint:[^"]*'
-   - Build segment map:
-     * Segment 1: Start → first checkpoint (tasks 1-X)
-     * Checkpoint 1: Type and location
-     * Segment 2: After checkpoint 1 → next checkpoint (tasks X+1 to Y)
-     * Checkpoint 2: Type and location
-     * ... continue for all segments
-
-2. For each segment in order:
-
-   A. Determine routing (apply rules from parse_segments):
-      - No prior checkpoint? → Subagent
-      - Prior checkpoint was human-verify? → Subagent
-      - Prior checkpoint was decision/human-action? → Main context
-
-   B. If routing = Subagent:
-      ```
-      Spawn Task tool with subagent_type="ms-executor":
-
-      Prompt: "Execute tasks [task numbers/names] from plan at [plan path].
-
-      **Context:**
-      - Read the full plan for objective, context files, and deviation rules
-      - You are executing a SEGMENT of this plan (not the full plan)
-      - Other segments will be executed separately
-
-      **Your responsibilities:**
-      - Execute only the tasks assigned to you
-      - Follow all deviation rules and authentication gate protocols
-      - Track deviations for later Summary
-      - DO NOT create SUMMARY.md (will be created after all segments complete)
-      - DO NOT commit (will be done after all segments complete)
-
-      **Report back:**
-      - Tasks completed
-      - Files created/modified
-      - Deviations encountered
-      - Any issues or blockers"
-
-      **After Task tool returns with agent_id:**
-
-      1. Write agent_id to current-agent-id.txt:
-         echo "[agent_id]" > .planning/current-agent-id.txt
-
-      2. Append spawn entry to agent-history.json:
-         {
-           "agent_id": "[agent_id from Task response]",
-           "task_description": "Execute tasks [X-Y] from plan {phase}-{plan}",
-           "phase": "{phase}",
-           "plan": "{plan}",
-           "segment": [segment_number],
-           "timestamp": "[ISO timestamp]",
-           "status": "spawned",
-           "completion_timestamp": null
-         }
-
-      Wait for subagent to complete
-      Capture results (files changed, deviations, etc.)
-
-      **After subagent completes successfully:**
-
-      1. Update agent-history.json entry:
-         - Find entry with matching agent_id
-         - Set status: "completed"
-         - Set completion_timestamp: "[ISO timestamp]"
-
-      2. Clear current-agent-id.txt:
-         rm .planning/current-agent-id.txt
-
-      ```
-
-   C. If routing = Main context:
-      Execute tasks in main using standard execution flow (step name="execute")
-      Track results locally
-
-   D. After segment completes (whether subagent or main):
-      Continue to next checkpoint/segment
-
-3. After ALL segments complete:
-
-   A. Aggregate results from all segments:
-      - Collect files created/modified from all segments
-      - Collect deviations from all segments
-      - Collect decisions from all checkpoints
-      - Merge into complete picture
-
-   B. Create SUMMARY.md:
-      - Use aggregated results
-      - Document all work from all segments
-      - Include deviations from all segments
-      - Note which segments were subagented
-
-   C. Commit:
-      - Stage all files from all segments
-      - Stage SUMMARY.md
-      - Commit with message following plan guidance
-      - Include note about segmented execution if relevant
-
-   D. Report completion
-
-**Example execution trace:**
-
-````
-
-Plan: 01-02-PLAN.md (8 tasks, 2 verify checkpoints)
-
-Parsing segments...
-
-- Segment 1: Tasks 1-3 (autonomous)
-- Checkpoint 4: human-verify
-- Segment 2: Tasks 5-6 (autonomous)
-- Checkpoint 7: human-verify
-- Segment 3: Task 8 (autonomous)
-
-Routing analysis:
-
-- Segment 1: No prior checkpoint → SUBAGENT ✓
-- Checkpoint 4: Verify only → MAIN (required)
-- Segment 2: After verify → SUBAGENT ✓
-- Checkpoint 7: Verify only → MAIN (required)
-- Segment 3: After verify → SUBAGENT ✓
-
-Execution:
-[1] Spawning subagent for tasks 1-3...
-→ Subagent completes: 3 files modified, 0 deviations
-[2] Executing checkpoint 4 (human-verify)...
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: Verification Required                    ║
-╚═══════════════════════════════════════════════════════╝
-
-Progress: 3/8 tasks complete
-Task: Verify database schema
-
-Built: User and Session tables with relations
-
-How to verify:
-  1. Check src/db/schema.ts for correct types
-
-────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "approved" or describe issues
-────────────────────────────────────────────────────────
-User: "approved"
-[3] Spawning subagent for tasks 5-6...
-→ Subagent completes: 2 files modified, 1 deviation (added error handling)
-[4] Executing checkpoint 7 (human-verify)...
-User: "approved"
-[5] Spawning subagent for task 8...
-→ Subagent completes: 1 file modified, 0 deviations
-
-Aggregating results...
-
-- Total files: 6 modified
-- Total deviations: 1
-- Segmented execution: 3 subagents, 2 checkpoints
-
-Creating SUMMARY.md...
-Committing...
-✓ Complete
-
-````
-
-**Benefits of this pattern:**
-- Main context usage: ~20% (just orchestration + checkpoints)
-- Subagent 1: Fresh 0-30% (tasks 1-3)
-- Subagent 2: Fresh 0-30% (tasks 5-6)
-- Subagent 3: Fresh 0-20% (task 8)
-- All autonomous work: Peak quality
-- Can handle large plans with many tasks if properly segmented
-
-**When NOT to use segmentation:**
-- Plan has decision/human-action checkpoints that affect following tasks
-- Following tasks depend on checkpoint outcome
-- Better to execute in main sequentially in those cases
-</step>
-
 <step name="load_prompt">
 Read the plan prompt:
 ```bash
@@ -555,14 +201,6 @@ Execute each task in the prompt. **Deviations are normal** - handle them automat
    - Track task completion and commit hash for Summary documentation
    - Continue to next task
 
-   **If `type="checkpoint:*"`:**
-
-   - STOP immediately (do not continue to next task)
-   - Execute checkpoint_protocol (see below)
-   - Wait for user response
-   - Verify if possible (check files, env vars, etc.)
-   - Only after user confirmation: continue to next task
-
 3. Run overall verification checks from `<verification>` section
 4. Confirm all success criteria from `<success_criteria>` section met
 5. Document all deviations in Summary (automatic - see deviation_documentation below)
@@ -586,7 +224,7 @@ This is NOT a failure. Authentication gates are expected and normal. Handle them
 
 1. **Recognize it's an auth gate** - Not a bug, just needs credentials
 2. **STOP current task execution** - Don't retry repeatedly
-3. **Create dynamic checkpoint:human-action** - Present it to user immediately
+3. **Use AskUserQuestion** - Present it to user immediately
 4. **Provide exact authentication steps** - CLI commands, where to get keys
 5. **Wait for user to authenticate** - Let them complete auth flow
 6. **Verify authentication works** - Test that credentials are valid
@@ -601,7 +239,7 @@ Running: vercel --yes
 
 Error: Not authenticated. Please run 'vercel login'
 
-[Create checkpoint dynamically]
+[Present via AskUserQuestion]
 
 ╔═══════════════════════════════════════════════════════╗
 ║  CHECKPOINT: Action Required                          ║
@@ -765,7 +403,7 @@ Apply these rules automatically. Track all deviations for Summary documentation.
 
 **Trigger:** Fix/addition requires significant structural modification
 
-**Action:** STOP, present to user, wait for decision
+**Action:** STOP, report via AskUserQuestion, wait for decision
 
 **Examples:**
 
@@ -807,9 +445,9 @@ Proceed with proposed change? (yes / different approach / defer)
 
 **RULE PRIORITY (when multiple could apply):**
 
-1. **If Rule 4 applies** → STOP and ask (architectural decision)
+1. **If Rule 4 applies** → STOP and report to user (architectural decision)
 2. **If Rules 1-3 apply** → Fix automatically, track for Summary
-3. **If genuinely unsure which rule** → Apply Rule 4 (ask user)
+3. **If genuinely unsure which rule** → Apply Rule 4 (stop and report)
 
 **Edge case guidance:**
 
@@ -1030,160 +668,6 @@ TASK_COMMITS+=("Task ${TASK_NUM}: ${TASK_COMMIT}")
 
 </task_commit>
 
-<step name="checkpoint_protocol">
-When encountering `type="checkpoint:*"`:
-
-**Critical: Claude automates everything with CLI/API before checkpoints.** Checkpoints are for verification and decisions, not manual work.
-
-**Display checkpoint clearly:**
-
-```
-╔═══════════════════════════════════════════════════════╗
-║  CHECKPOINT: [Type]                                   ║
-╚═══════════════════════════════════════════════════════╝
-
-Progress: {X}/{Y} tasks complete
-Task: [task name]
-
-[Display task-specific content based on type]
-
-────────────────────────────────────────────────────────
-→ YOUR ACTION: [Resume signal instruction]
-────────────────────────────────────────────────────────
-```
-
-**For checkpoint:human-verify (90% of checkpoints):**
-
-```
-Built: [what was automated - deployed, built, configured]
-
-How to verify:
-  1. [Step 1 - exact command/URL]
-  2. [Step 2 - what to check]
-  3. [Step 3 - expected behavior]
-
-────────────────────────────────────────────────────────
-→ YOUR ACTION: Type "approved" or describe issues
-────────────────────────────────────────────────────────
-```
-
-**For checkpoint:decision (9% of checkpoints):**
-
-```
-Decision needed: [decision]
-
-Context: [why this matters]
-
-Options:
-1. [option-id]: [name]
-   Pros: [pros]
-   Cons: [cons]
-
-2. [option-id]: [name]
-   Pros: [pros]
-   Cons: [cons]
-
-[Resume signal - e.g., "Select: option-id"]
-```
-
-**For checkpoint:human-action (1% - rare, only for truly unavoidable manual steps):**
-
-```
-I automated: [what Claude already did via CLI/API]
-
-Need your help with: [the ONE thing with no CLI/API - email link, 2FA code]
-
-Instructions:
-[Single unavoidable step]
-
-I'll verify after: [verification]
-
-[Resume signal - e.g., "Type 'done' when complete"]
-```
-
-**After displaying:** WAIT for user response. Do NOT hallucinate completion. Do NOT continue to next task.
-
-**After user responds:**
-
-- Run verification if specified (file exists, env var set, tests pass, etc.)
-- If verification passes or N/A: continue to next task
-- If verification fails: inform user, wait for resolution
-
-See ~/.claude/mindsystem/references/checkpoints.md for complete checkpoint guidance.
-</step>
-
-<step name="checkpoint_return_for_orchestrator">
-**When spawned by an orchestrator (execute-phase or execute-plan command):**
-
-If you were spawned via Task tool and hit a checkpoint, you cannot directly interact with the user. Instead, RETURN to the orchestrator with structured checkpoint state so it can present to the user and spawn a fresh continuation agent.
-
-**Return format for checkpoints:**
-
-**Required in your return:**
-
-1. **Completed Tasks table** - Tasks done so far with commit hashes and files created
-2. **Current Task** - Which task you're on and what's blocking it
-3. **Checkpoint Details** - User-facing content (verification steps, decision options, or action instructions)
-4. **Awaiting** - What you need from the user
-
-**Example return:**
-
-```
-## CHECKPOINT REACHED
-
-**Type:** human-action
-**Plan:** 01-01
-**Progress:** 1/3 tasks complete
-
-### Completed Tasks
-
-| Task | Name | Commit | Files |
-|------|------|--------|-------|
-| 1 | Initialize Next.js 15 project | d6fe73f | package.json, tsconfig.json, app/ |
-
-### Current Task
-
-**Task 2:** Initialize Convex backend
-**Status:** blocked
-**Blocked by:** Convex CLI authentication required
-
-### Checkpoint Details
-
-**Automation attempted:**
-Ran `npx convex dev` to initialize Convex backend
-
-**Error encountered:**
-"Error: Not authenticated. Run `npx convex login` first."
-
-**What you need to do:**
-1. Run: `npx convex login`
-2. Complete browser authentication
-3. Run: `npx convex dev`
-4. Create project when prompted
-
-**I'll verify after:**
-`cat .env.local | grep CONVEX` returns the Convex URL
-
-### Awaiting
-
-Type "done" when Convex is authenticated and project created.
-```
-
-**After you return:**
-
-The orchestrator will:
-1. Parse your structured return
-2. Present checkpoint details to the user
-3. Collect user's response
-4. Spawn a FRESH continuation agent with your completed tasks state
-
-You will NOT be resumed. A new agent continues from where you stopped, using your Completed Tasks table to know what's done.
-
-**How to know if you were spawned:**
-
-If you're reading this workflow because an orchestrator spawned you, the orchestrator's prompt will include checkpoint return instructions. Follow those instructions when you hit a checkpoint.
-</step>
-
 <step name="verification_failure_gate">
 If any task verification fails:
 
@@ -1330,7 +814,12 @@ Before writing summary content, populate frontmatter fields from execution conte
 5. **Decisions:**
    - key-decisions: Extract from "Decisions Made" section
 
-6. **Metrics:**
+6. **Verification hints (required):**
+   - mock_hints.transient_states: Reflect on what you built. Any UI with async loading, animations, or transitions that produce brief intermediate states? List each with component file and trigger.
+   - mock_hints.external_data: Any feature that fetches from an API? List the source, data type, and rendering components.
+   - If no UI work, no async operations, no external data: write `mock_hints: none` with a brief reason comment (e.g., `mock_hints: none  # no transient states or external data dependencies`). Always populate — `none` tells verify-work to skip mock analysis.
+
+7. **Metrics:**
    - duration: From $DURATION variable
    - completed: From $PLAN_END_TIME (date only, format YYYY-MM-DD)
 

package/mindsystem/workflows/generate-mocks.md

@@ -112,9 +112,83 @@ Common mock types and what they enable:
 | `empty_response` | Empty states, placeholder UI, "no results" | `forceEmpty` |
 | `loading_state` | Loading spinners, skeleton screens | `forceLoading`, `mockLoadingDelay` |
 | `offline` | Offline UI, cached data, sync indicators | `forceOffline` |
+| `transient_state` | Brief async states (loading skeletons, transitions) | `forceTransient`, `mockTransientDelay` |
+| `external_data` | Features depending on API data that may not exist locally | `forceMockData`, `mockDataSet` |
 
 </mock_types>
 
+<transient_state_patterns>
+
+**Transient states are UI states that appear briefly during async operations.** Loading skeletons, shimmer effects, transition animations — they resolve too fast to observe and test manually.
+
+**Two mock strategies:**
+
+**1. Extended delay strategy (default):**
+
+Add a configurable delay before the real data returns. The transient state stays visible long enough to test.
+
+```dart
+// Flutter — Completer-based delay
+Future<List<Recipe>> getRecipes() async {
+  // TEST OVERRIDE - Extend loading state for testing
+  if (TestOverrides.forceTransientState) {
+    await Future.delayed(TestOverrides.mockTransientDelay); // default 5s
+  }
+  // Real implementation continues...
+  final response = await _api.get('/recipes');
+  return response.data.map((j) => Recipe.fromJson(j)).toList();
+}
+```
+
+```typescript
+// React/Next.js — Promise delay
+async function getRecipes(): Promise<Recipe[]> {
+  // TEST OVERRIDE - Extend loading state for testing
+  if (testOverrides.forceTransientState) {
+    await new Promise(resolve => setTimeout(resolve, testOverrides.mockTransientDelayMs));
+  }
+  // Real implementation continues...
+  const response = await fetch('/api/recipes');
+  return response.json();
+}
+```
+
+**When to use:** Testing that the loading UI (skeleton, spinner) displays correctly while waiting.
+
+**2. Never-resolve strategy:**
+
+The async call never completes. The transient state stays permanently visible.
+
+```dart
+// Flutter — Completer that never completes
+Future<List<Recipe>> getRecipes() async {
+  // TEST OVERRIDE - Never resolve, keep loading state visible
+  if (TestOverrides.forceTransientState && TestOverrides.mockTransientDelay == Duration.zero) {
+    await Completer<void>().future; // Never completes
+  }
+  // Real implementation continues...
+}
+```
+
+```typescript
+// JS — Promise that never resolves
+async function getRecipes(): Promise<Recipe[]> {
+  // TEST OVERRIDE - Never resolve, keep loading state visible
+  if (testOverrides.forceTransientState && testOverrides.mockTransientDelayMs === 0) {
+    await new Promise(() => {}); // Never resolves
+  }
+  // Real implementation continues...
+}
+```
+
+**When to use:** Testing that the loading UI itself is correct (layout, styling, animation) without it disappearing.
+
+**Choosing between strategies:**
+- Testing the transition (loading → loaded): Use extended delay (5s default)
+- Testing the loading UI appearance: Use never-resolve (set delay to 0)
+
+</transient_state_patterns>
+
 <toggle_instructions_template>
 
 **Format for each mock state:**