mindsystem-cc 3.12.0 → 3.13.1

package/mindsystem/references/scope-estimation.md

@@ -32,10 +32,10 @@ Why 50% not 80%?
 | Task Complexity | Tasks/Plan | Context/Task | Total |
 |-----------------|------------|--------------|-------|
 | Simple (CRUD, config) | 3 | ~10-15% | ~30-45% |
-| Complex (auth, payments) | 2 | ~20-30% | ~40-50% |
+| Complex (auth, payments) | 2-3 | ~15-25% | ~40-50% |
 | Very complex (migrations, refactors) | 1-2 | ~30-40% | ~30-50% |
 
-**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+**Default to 3 tasks for simple-medium work, 2 for complex.** Executor overhead reduction creates headroom for the third task.
 </task_rule>
 
 <tdd_plans>
@@ -108,24 +108,23 @@ Plan 03: Visualization components
 </splitting_strategies>
 
 <dependency_awareness>
-**Plans declare dependencies explicitly via frontmatter.**
+**Dependencies centralized in EXECUTION-ORDER.md.**
 
-```yaml
-# Independent plan (Wave 1 candidate)
-depends_on: []
-files_modified: [src/features/user/model.ts, src/features/user/api.ts]
-
-
-# Dependent plan (later wave)
-depends_on: ["03-01"]
-files_modified: [src/integration/stripe.ts]
+```markdown
+## Wave 1 (parallel)
+- 03-01-PLAN.md — User feature
+- 03-02-PLAN.md — Product feature
 
+## Wave 2
+- 03-03-PLAN.md — Integration (after: 01, 02)
 ```
 
+Plans declare files in `**Files:**` lines within `## Changes` subsections. EXECUTION-ORDER.md tracks wave groups and dependencies.
+
 **Wave assignment rules:**
-- `depends_on: []` + no file conflicts → Wave 1 (parallel)
-- `depends_on: ["XX"]` → runs after plan XX completes
-- Shared `files_modified` with sibling → sequential (by plan number)
+- No dependencies + no file conflicts with other Wave 1 plans → Wave 1 (parallel)
+- Depends on earlier plan → later wave (runs after dependency completes)
+- Shared files with sibling plan → sequential (by plan number)
 
 **SUMMARY references:**
 - Only reference prior SUMMARY if genuinely needed (imported types, decisions affecting this plan)
@@ -134,17 +133,21 @@ files_modified: [src/integration/stripe.ts]
 </dependency_awareness>
 
 <file_ownership>
-**Exclusive file ownership prevents conflicts:**
+**Exclusive file ownership prevents conflicts.**
 
-```yaml
-# Plan 01 frontmatter
-files_modified: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]
+File ownership is determined from `**Files:**` lines in each plan's `## Changes` section and validated in EXECUTION-ORDER.md wave assignments.
 
-# Plan 02 frontmatter
-files_modified: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]
+```markdown
+# Plan 01 Changes
+### 1. Create User model
+**Files:** `src/models/user.ts`, `src/api/users.ts`, `src/components/UserList.tsx`
+
+# Plan 02 Changes
+### 1. Create Product model
+**Files:** `src/models/product.ts`, `src/api/products.ts`, `src/components/ProductList.tsx`
 ```
 
-No overlap → can run parallel.
+No overlap → can run parallel (same wave in EXECUTION-ORDER.md).
 
 **If file appears in multiple plans:** Later plan depends on earlier (by plan number).
 **If file cannot be split:** Plans must be sequential for that file.
@@ -202,6 +205,8 @@ Waves: [01, 02, 03] (all parallel)
 
 **2 tasks:** Simple ~30%, Medium ~50%, Complex ~80% (split)
 **3 tasks:** Simple ~45%, Medium ~75% (risky), Complex 120% (impossible)
+
+**Executor overhead:** ~2,400 tokens (down from ~6,900 in previous versions), freeing ~4,500 tokens per plan for code quality.
 </estimating_context>
 
 <summary>
@@ -215,9 +220,9 @@ Waves: [01, 02, 03] (all parallel)
 **The rules:**
 - If in doubt, split. Quality over consolidation.
 - Vertical slices over horizontal layers.
-- Explicit dependencies via `depends_on` frontmatter.
+- Dependencies centralized in EXECUTION-ORDER.md.
 - Autonomous plans get parallel execution.
 
-**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit).
+**Commit rule:** Each plan produces 3-4 commits total (2-3 change commits + 1 docs commit).
 </summary>
 </scope_estimation>

package/mindsystem/references/tdd-execution.md

@@ -0,0 +1,70 @@
+<tdd_execution>
+
+## RED-GREEN-REFACTOR Cycle
+
+Lazy-loaded by executor when plan metadata says `**Type:** tdd`.
+
+### RED — Write failing test
+
+1. Create test file following project conventions
+2. Write test describing expected behavior (from plan's behavior specification)
+3. Run test — MUST fail (if passes, feature exists or test is wrong — investigate)
+4. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+### GREEN — Implement to pass
+
+1. Write minimal code to make test pass — no cleverness, no optimization
+2. Run test — MUST pass
+3. Commit: `feat({phase}-{plan}): implement [feature]`
+
+### REFACTOR (if needed)
+
+1. Clean up implementation if obvious improvements exist
+2. Run tests — MUST still pass
+3. Commit only if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+Result: Each TDD plan produces 2-3 atomic commits (test/feat/refactor).
+
+---
+
+## Test Framework Setup
+
+When no test framework is configured, set it up as part of the RED phase:
+
+| Project | Framework | Install |
+|---------|-----------|---------|
+| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
+| Node.js (Vite) | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` |
+| Go | testing | Built-in |
+| Rust | cargo test | Built-in |
+| Flutter/Dart | flutter_test | Built-in |
+
+Detect project type from package.json / requirements.txt / go.mod / pubspec.yaml. Create config if needed. Verify with empty test run.
+
+---
+
+## Commit Pattern
+
+TDD plans use dedicated commit types per phase:
+
+```
+test(08-02): add failing test for email validation
+feat(08-02): implement email validation
+refactor(08-02): extract regex to constant  # optional
+```
+
+Comparison: Standard plans produce 1 commit per task. TDD plans produce 2-3 commits for single feature.
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Test doesn't fail in RED | Feature may exist or test is wrong — investigate before proceeding |
+| Test doesn't pass in GREEN | Debug implementation, keep iterating until green |
+| Tests fail in REFACTOR | Undo refactor — commit was premature, refactor in smaller steps |
+| Unrelated tests break | Stop and investigate — may indicate coupling issue |
+
+</tdd_execution>

package/mindsystem/references/tdd.md

@@ -1,12 +1,13 @@
-<overview>
+# TDD Reference for Plan Writers
+
 TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
 
 **Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
 
-**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
-</overview>
+**Key insight:** TDD work is fundamentally heavier than standard tasks — it requires 2-3 execution cycles (RED -> GREEN -> REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
+
+---
 
-<when_to_use_tdd>
 ## When TDD Improves Quality
 
 **TDD candidates (create a TDD plan):**
@@ -18,7 +19,7 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle
 - State machines and workflows
 - Utility functions with clear specifications
 
-**Skip TDD (use standard plan with `type="auto"` tasks):**
+**Skip TDD (use standard plan):**
 - UI layout, styling, visual components
 - Configuration changes
 - Glue code connecting existing components
@@ -27,92 +28,65 @@ TDD is about design quality, not coverage metrics. The red-green-refactor cycle
 - Exploratory prototyping
 
 **Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
-→ Yes: Create a TDD plan
-→ No: Use standard plan, add tests after if needed
-</when_to_use_tdd>
+- Yes: Create a TDD plan
+- No: Use standard plan, add tests after if needed
+
+---
 
-<tdd_plan_structure>
 ## TDD Plan Structure
 
-Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle. Use the same pure markdown format as all other plans:
 
 ```markdown
----
-phase: XX-name
-plan: NN
-type: tdd
----
+# Plan NN: Feature name
 
-<objective>
-[What feature and why]
-Purpose: [Design benefit of TDD for this feature]
-Output: [Working, tested feature]
-</objective>
-
-<context>
-@.planning/PROJECT.md
-@.planning/ROADMAP.md
-@relevant/source/files.ts
-</context>
-
-<feature>
-  <name>[Feature name]</name>
-  <files>[source file, test file]</files>
-  <behavior>
-    [Expected behavior in testable terms]
-    Cases: input → expected output
-  </behavior>
-  <implementation>[How to implement once tests pass]</implementation>
-</feature>
-
-<verification>
-[Test command that proves feature works]
-</verification>
-
-<success_criteria>
-- Failing test written and committed
-- Implementation passes test
-- Refactor complete (if needed)
-- All 2-3 commits present
-</success_criteria>
-
-<output>
-After completion, create SUMMARY.md with:
-- RED: What test was written, why it failed
-- GREEN: What implementation made it pass
-- REFACTOR: What cleanup was done (if any)
-- Commits: List of commits produced
-</output>
-```
+**Subsystem:** validation | **Type:** tdd
+
+## Context
+Why TDD benefits this feature. Clear inputs/outputs that make test-first
+design valuable. Reference any prior work.
+
+## Changes
+
+### 1. RED — Write failing tests
+**Files:** `src/lib/__tests__/validate-email.test.ts`
+
+Test cases:
+- Valid: `user@example.com`, `name+tag@domain.co.uk` -> returns true
+- Invalid: `@domain.com`, `user@`, empty string -> returns false
+- Edge: very long local part (>64 chars) -> returns false
 
-**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD—use a standard plan and add tests after.
-</tdd_plan_structure>
+Import `validateEmail` from `src/lib/validate-email.ts` (does not exist yet).
+Run tests — all must fail with import/function error.
 
-<execution_flow>
-## Red-Green-Refactor Cycle
+### 2. GREEN — Implement minimal validation
+**Files:** `src/lib/validate-email.ts`
 
-**RED - Write failing test:**
-1. Create test file following project conventions
-2. Write test describing expected behavior (from `<behavior>` element)
-3. Run test - it MUST fail
-4. If test passes: feature exists or test is wrong. Investigate.
-5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+Export `validateEmail(email: string): boolean`. Use regex matching RFC 5322
+simplified pattern. Handle null/undefined input by returning false. No
+optimization — just make tests pass.
 
-**GREEN - Implement to pass:**
-1. Write minimal code to make test pass
-2. No cleverness, no optimization - just make it work
-3. Run test - it MUST pass
-4. Commit: `feat({phase}-{plan}): implement [feature]`
+### 3. REFACTOR — Extract regex constant
+**Files:** `src/lib/validate-email.ts`
 
-**REFACTOR (if needed):**
-1. Clean up implementation if obvious improvements exist
-2. Run tests - MUST still pass
-3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+Extract regex to `EMAIL_REGEX` constant at module level. Add JSDoc with
+examples. Run tests — all must still pass. Only commit if changes improve
+readability.
 
-**Result:** Each TDD plan produces 2-3 atomic commits.
-</execution_flow>
+## Verification
+- `npm test -- --grep "validate-email"` passes all cases
+- Import works from other modules without errors
+
+## Must-Haves
+- [ ] Valid email addresses return true
+- [ ] Invalid email addresses return false
+- [ ] Edge cases (length limits, null input) handled correctly
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD — use a standard plan and add tests after.
+
+---
 
-<test_quality>
 ## Good Tests vs Bad Tests
 
 **Test behavior, not implementation:**
@@ -131,123 +105,9 @@ After completion, create SUMMARY.md with:
 **No implementation details:**
 - Good: Test public API, observable behavior
 - Bad: Mock internals, test private methods, assert on internal state
-</test_quality>
-
-<framework_setup>
-## Test Framework Setup (If None Exists)
-
-When executing a TDD plan but no test framework is configured, set it up as part of the RED phase:
-
-**1. Detect project type:**
-```bash
-# JavaScript/TypeScript
-if [ -f package.json ]; then echo "node"; fi
-
-# Python
-if [ -f requirements.txt ] || [ -f pyproject.toml ]; then echo "python"; fi
-
-# Go
-if [ -f go.mod ]; then echo "go"; fi
-
-# Rust
-if [ -f Cargo.toml ]; then echo "rust"; fi
-```
-
-**2. Install minimal framework:**
-| Project | Framework | Install |
-|---------|-----------|---------|
-| Node.js | Jest | `npm install -D jest @types/jest ts-jest` |
-| Node.js (Vite) | Vitest | `npm install -D vitest` |
-| Python | pytest | `pip install pytest` |
-| Go | testing | Built-in |
-| Rust | cargo test | Built-in |
-
-**3. Create config if needed:**
-- Jest: `jest.config.js` with ts-jest preset
-- Vitest: `vitest.config.ts` with test globals
-- pytest: `pytest.ini` or `pyproject.toml` section
-
-**4. Verify setup:**
-```bash
-# Run empty test suite - should pass with 0 tests
-npm test  # Node
-pytest    # Python
-go test ./...  # Go
-cargo test    # Rust
-```
-
-**5. Create first test file:**
-Follow project conventions for test location:
-- `*.test.ts` / `*.spec.ts` next to source
-- `__tests__/` directory
-- `tests/` directory at root
-
-Framework setup is a one-time cost included in the first TDD plan's RED phase.
-</framework_setup>
-
-<error_handling>
-## Error Handling
-
-**Test doesn't fail in RED phase:**
-- Feature may already exist - investigate
-- Test may be wrong (not testing what you think)
-- Fix before proceeding
-
-**Test doesn't pass in GREEN phase:**
-- Debug implementation
-- Don't skip to refactor
-- Keep iterating until green
-
-**Tests fail in REFACTOR phase:**
-- Undo refactor
-- Commit was premature
-- Refactor in smaller steps
-
-**Unrelated tests break:**
-- Stop and investigate
-- May indicate coupling issue
-- Fix before proceeding
-</error_handling>
-
-<commit_pattern>
-## Commit Pattern for TDD Plans
-
-TDD plans produce 2-3 atomic commits (one per phase):
 
-```
-test(08-02): add failing test for email validation
-
-- Tests valid email formats accepted
-- Tests invalid formats rejected
-- Tests empty input handling
-
-feat(08-02): implement email validation
-
-- Regex pattern matches RFC 5322
-- Returns boolean for validity
-- Handles edge cases (empty, null)
-
-refactor(08-02): extract regex to constant (optional)
-
-- Moved pattern to EMAIL_REGEX constant
-- No behavior changes
-- Tests still pass
-```
-
-**Comparison with standard plans:**
-- Standard plans: 1 commit per task, 2-4 commits per plan
-- TDD plans: 2-3 commits for single feature
-
-Both follow same format: `{type}({phase}-{plan}): {description}`
-
-**Benefits:**
-- Each commit independently revertable
-- Git bisect works at commit level
-- Clear history showing TDD discipline
-- Consistent with overall commit strategy
-</commit_pattern>
+---
 
-<context_budget>
 ## Context Budget
 
 TDD plans target **~40% context usage** (lower than standard plans' ~50%).
@@ -260,4 +120,3 @@ Why lower:
 Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
 
 Single feature focus ensures full quality throughout the cycle.
-</context_budget>

package/mindsystem/templates/UAT.md

@@ -14,7 +14,7 @@ source: [list of SUMMARY.md files tested]
 started: [ISO timestamp]
 updated: [ISO timestamp]
 current_batch: [N]
-mock_stash: [stash name or null]
+mocked_files: []
 pre_work_stash: [stash name or null]
 ---
 
@@ -138,7 +138,7 @@ mock_type: empty_response
 - `started`: IMMUTABLE - set on creation
 - `updated`: OVERWRITE - update on every change
 - `current_batch`: OVERWRITE - current batch number
-- `mock_stash`: OVERWRITE - name of stashed mocks or null
+- `mocked_files`: OVERWRITE - list of files with inline mocks, or empty array
 - `pre_work_stash`: OVERWRITE - user's pre-existing work stash or null
 
 **Progress:**
@@ -196,23 +196,22 @@ mock_type: empty_response
 <mock_lifecycle>
 
 **When batch needs mocks:**
-1. Generate mock files (uncommitted)
-2. User enables mocks
-3. Testing proceeds
+1. Edit service methods inline (hardcoded return values)
+2. Record files in `mocked_files` frontmatter
+3. User hot reloads, testing proceeds
 
 **When fix needed:**
-1. `git stash push -m "mocks-batch-N"`
-2. Update `mock_stash` in frontmatter
-3. Fix applied, committed
-4. `git stash pop` to restore mocks
-5. Clear `mock_stash` if no conflicts
+1. `git stash push -m "mocks-batch-N" -- <mocked_files>`
+2. Fix applied, committed
+3. `git stash pop` to restore mocks
+4. If conflict: take fix version, remove file from `mocked_files`
 
 **On batch transition (different mock_type):**
-1. Discard old mocks: `git stash drop`
-2. Generate new mocks for new batch
+1. Revert old mocks: `git checkout -- <mocked_files>`
+2. Clear `mocked_files`, apply new inline mocks
 
 **On session complete:**
-1. Discard all mocks: `git stash drop`
+1. Revert all mocks: `git checkout -- <mocked_files>`
 2. Restore pre_work_stash if exists
 
 </mock_lifecycle>
@@ -225,8 +224,9 @@ On `/ms:verify-work` with existing UAT.md:
    - "complete" → offer to re-run or view results
    - "testing" or "fixing" → resume
 
-2. Check `mock_stash`:
-   - If exists, offer to restore or discard
+2. Check `mocked_files`:
+   - If non-empty, verify mocks still present via `git diff --name-only`
+   - If mocks lost, regenerate for current batch
 
 3. Check `current_batch`:
    - Resume from that batch
@@ -262,7 +262,7 @@ source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
 started: 2025-01-15T10:30:00Z
 updated: 2025-01-15T11:15:00Z
 current_batch: 2
-mock_stash: mocks-batch-2
+mocked_files: [src/services/auth_service.dart, src/services/api_service.dart]
 pre_work_stash: null
 ---