mindsystem-cc 3.12.0 → 3.13.1

package/mindsystem/templates/summary.md

@@ -1,293 +0,0 @@
-# Summary Template
-
-Template for `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md` - phase completion documentation.
-
----
-
-## File Template
-
-```markdown
----
-phase: XX-name
-plan: YY
-subsystem: [from .planning/config.json subsystems list]
-tags: [searchable tech: jwt, stripe, react, postgres, prisma]
-
-# Dependency graph
-requires:
-  - phase: [prior phase this depends on]
-    provides: [what that phase built that this uses]
-provides:
-  - [bullet list of what this phase built/delivered]
-affects: [list of phase names or keywords that will need this context]
-
-# Tech tracking
-tech-stack:
-  added: [libraries/tools added in this phase]
-  patterns: [architectural/code patterns established]
-
-key-files:
-  created: [important files created]
-  modified: [important files modified]
-
-key-decisions:
-  - "Decision 1"
-  - "Decision 2"
-
-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
----
-
-# Phase [X]: [Name] Summary
-
-**[Substantive one-liner describing outcome - NOT "phase complete" or "implementation finished"]**
-
-## Performance
-
-- **Duration:** [time] (e.g., 23 min, 1h 15m)
-- **Started:** [ISO timestamp]
-- **Completed:** [ISO timestamp]
-- **Tasks:** [count completed]
-- **Files modified:** [count]
-
-## Accomplishments
-- [Most important outcome]
-- [Second key accomplishment]
-- [Third if applicable]
-
-## Task Commits
-
-Each task was committed atomically:
-
-1. **Task 1: [task name]** - `abc123f` (feat/fix/test/refactor)
-2. **Task 2: [task name]** - `def456g` (feat/fix/test/refactor)
-3. **Task 3: [task name]** - `hij789k` (feat/fix/test/refactor)
-
-**Plan metadata:** `lmn012o` (docs: complete plan)
-
-_Note: TDD tasks may have multiple commits (test → feat → refactor)_
-
-## Files Created/Modified
-- `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"]
-
-## Deviations from Plan
-
-[If no deviations: "None - plan executed exactly as written"]
-
-[If deviations occurred:]
-
-### Auto-fixed Issues
-
-**1. [Rule X - Category] Brief description**
-- **Found during:** Task [N] ([task name])
-- **Issue:** [What was wrong]
-- **Fix:** [What was done]
-- **Files modified:** [file paths]
-- **Verification:** [How it was verified]
-- **Committed in:** [hash] (part of task commit)
-
-[... repeat for each auto-fix ...]
-
----
-
-**Total deviations:** [N] auto-fixed ([breakdown by rule])
-**Impact on plan:** [Brief assessment - e.g., "All auto-fixes necessary for correctness/security. No scope creep."]
-
-## Issues Encountered
-[Problems and how they were resolved, or "None"]
-
-[Note: "Deviations from Plan" documents unplanned work that was handled automatically via deviation rules. "Issues Encountered" documents problems during planned work that required problem-solving.]
-
-## User Setup Required
-
-[If USER-SETUP.md was generated:]
-**External services require manual configuration.** See [{phase}-USER-SETUP.md](./{phase}-USER-SETUP.md) for:
-- Environment variables to add
-- Dashboard configuration steps
-- Verification commands
-
-[If no USER-SETUP.md:]
-None - no external service configuration required.
-
-## Next Phase Readiness
-[What's ready for next phase]
-[Any blockers or concerns]
-
----
-*Phase: XX-name*
-*Completed: [date]*
-```
-
-<frontmatter_guidance>
-**Purpose:** Enable automatic context assembly via dependency graph. Frontmatter makes summary metadata machine-readable so plan-phase can scan all summaries quickly and select relevant ones based on dependencies.
-
-**Fast scanning:** Frontmatter is first ~25 lines, cheap to scan across all summaries without reading full content.
-
-**Dependency graph:** `requires`/`provides`/`affects` create explicit links between phases, enabling transitive closure for context selection.
-
-**Subsystem:** Primary categorization from `.planning/config.json` subsystems list. If work doesn't fit any existing subsystem, add a new value to config.json and use it.
-
-**Tags:** Searchable technical keywords (libraries, frameworks, tools) for tech stack awareness.
-
-**Key-files:** Important files for @context references in PLAN.md.
-
-**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>
-The one-liner MUST be substantive:
-
-**Good:**
-- "JWT auth with refresh rotation using jose library"
-- "Prisma schema with User, Session, and Product models"
-- "Dashboard with real-time metrics via Server-Sent Events"
-
-**Bad:**
-- "Phase complete"
-- "Authentication implemented"
-- "Foundation finished"
-- "All tasks done"
-
-The one-liner should tell someone what actually shipped.
-</one_liner_rules>
-
-<example>
-```markdown
-# Phase 1: Foundation Summary
-
-**JWT auth with refresh rotation using jose library, Prisma User model, and protected API middleware**
-
-## Performance
-
-- **Duration:** 28 min
-- **Started:** 2025-01-15T14:22:10Z
-- **Completed:** 2025-01-15T14:50:33Z
-- **Tasks:** 5
-- **Files modified:** 8
-
-## Accomplishments
-- User model with email/password auth
-- Login/logout endpoints with httpOnly JWT cookies
-- Protected route middleware checking token validity
-- Refresh token rotation on each request
-
-## Files Created/Modified
-- `prisma/schema.prisma` - User and Session models
-- `src/app/api/auth/login/route.ts` - Login endpoint
-- `src/app/api/auth/logout/route.ts` - Logout endpoint
-- `src/middleware.ts` - Protected route checks
-- `src/lib/auth.ts` - JWT helpers using jose
-
-## Decisions Made
-- Used jose instead of jsonwebtoken (ESM-native, Edge-compatible)
-- 15-min access tokens with 7-day refresh tokens
-- Storing refresh tokens in database for revocation capability
-
-## Deviations from Plan
-
-### Auto-fixed Issues
-
-**1. [Rule 2 - Missing Critical] Added password hashing with bcrypt**
-- **Found during:** Task 2 (Login endpoint implementation)
-- **Issue:** Plan didn't specify password hashing - storing plaintext would be critical security flaw
-- **Fix:** Added bcrypt hashing on registration, comparison on login with salt rounds 10
-- **Files modified:** src/app/api/auth/login/route.ts, src/lib/auth.ts
-- **Verification:** Password hash test passes, plaintext never stored
-- **Committed in:** abc123f (Task 2 commit)
-
-**2. [Rule 3 - Blocking] Installed missing jose dependency**
-- **Found during:** Task 4 (JWT token generation)
-- **Issue:** jose package not in package.json, import failing
-- **Fix:** Ran `npm install jose`
-- **Files modified:** package.json, package-lock.json
-- **Verification:** Import succeeds, build passes
-- **Committed in:** def456g (Task 4 commit)
-
----
-
-**Total deviations:** 2 auto-fixed (1 missing critical, 1 blocking)
-**Impact on plan:** Both auto-fixes essential for security and functionality. No scope creep.
-
-## Issues Encountered
-- jsonwebtoken CommonJS import failed in Edge runtime - switched to jose (planned library change, worked as expected)
-
-## Next Phase Readiness
-- Auth foundation complete, ready for feature development
-- User registration endpoint needed before public launch
-
----
-*Phase: 01-foundation*
-*Completed: 2025-01-15*
-```
-</example>
-
-<guidelines>
-**When to create:**
-- After completing each phase plan
-- Required output from execute-plan workflow
-- Documents what actually happened vs what was planned
-
-**Frontmatter completion:**
-- MANDATORY: Complete all frontmatter fields during summary creation
-- See <frontmatter_guidance> for field purposes
-- Frontmatter enables automatic context assembly for future planning
-
-**One-liner requirements:**
-- Must be substantive (describe what shipped, not "phase complete")
-- Should tell someone what was accomplished
-- Examples: "JWT auth with refresh rotation using jose library" not "Authentication implemented"
-
-**Performance tracking:**
-- Include duration, start/end timestamps
-- Used for velocity metrics in STATE.md
-
-**Deviations section:**
-- Documents unplanned work handled via deviation rules
-- Separate from "Issues Encountered" (which is planned work problems)
-- Auto-fixed issues: What was wrong, how fixed, verification
-
-**Decisions section:**
-- Key decisions made during execution
-- Include rationale (why this choice)
-- Extracted to STATE.md accumulated context
-- Use "None - followed plan as specified" if no deviations
-
-**After creation:**
-- STATE.md updated with position, decisions, issues
-- Next plan can reference decisions made
-</guidelines>

package/mindsystem/workflows/generate-mocks.md

@@ -1,261 +0,0 @@
-<purpose>
-Generate framework-specific mock code for manual UAT testing. Creates override files with toggle flags and minimal production hooks.
-
-Called by verify-work workflow when a test batch requires mock state.
-</purpose>
-
-<philosophy>
-**Mocks are temporary scaffolding.**
-
-They exist only as uncommitted changes during testing. They enable reaching UI states that require specific backend conditions (premium user, error states, empty lists, loading states).
-
-**Principles:**
-- Minimal footprint: One override file + minimal hooks
-- Easy removal: Delete file, remove imports, done
-- Framework-appropriate: Match project conventions
-- User-controlled: Clear toggle instructions
-</philosophy>
-
-<framework_detection>
-
-**Step 1: Read PROJECT.md**
-```bash
-cat .planning/PROJECT.md 2>/dev/null | head -50
-```
-
-**Step 2: Verify with config files**
-
-| Check | Indicates |
-|-------|-----------|
-| `pubspec.yaml` exists | Flutter |
-| `package.json` has `"react"` or `"next"` | React/Next.js |
-| `package.json` has `"react-native"` | React Native |
-| `package.json` has `"vue"` | Vue |
-
-**Step 3: Determine file locations**
-
-| Framework | Override File | Import Pattern |
-|-----------|---------------|----------------|
-| Flutter | `lib/test_overrides.dart` | `import 'package:{app}/test_overrides.dart';` |
-| React/Next.js | `src/testOverrides.ts` | `import { testOverrides } from '@/testOverrides';` |
-| React Native | `src/testOverrides.ts` | `import { testOverrides } from '../testOverrides';` |
-| Vue | `src/testOverrides.ts` | `import { testOverrides } from '@/testOverrides';` |
-
-</framework_detection>
-
-<override_file_pattern>
-
-**Structure:**
-
-```
-// Test Overrides - DELETE THIS FILE BEFORE COMMITTING
-// Used for manual UAT testing only
-
-// === STATE FLAGS ===
-// Set to true to enable mock state
-
-{flag declarations based on mock_type}
-
-// === MOCK DATA ===
-// Returned when flags are true
-
-{mock data structures}
-
-// === RESET ===
-// Call to disable all overrides
-
-{reset function}
-```
-
-**Flag naming convention:**
-- `force{State}` for boolean flags (e.g., `forcePremiumUser`, `forceErrorState`)
-- `mock{DataType}` for mock data (e.g., `mockUserData`, `mockErrorMessage`)
-
-</override_file_pattern>
-
-<production_hook_pattern>
-
-**Minimal hooks at service/repository layer:**
-
-```
-// Check override BEFORE real implementation
-if (testOverrides.force{State}) {
-  return testOverrides.mock{Data};
-}
-
-// Real implementation continues here...
-```
-
-**Placement:**
-- In services/repositories, not UI components
-- At the data fetch point, not the render point
-- Single if-check, no complex branching
-
-**Marking:**
-```
-// TEST OVERRIDE - Remove before commit
-if (testOverrides.forceError) {
-  throw testOverrides.mockError;
-}
-```
-
-</production_hook_pattern>
-
-<mock_types>
-
-Common mock types and what they enable:
-
-| Mock Type | Enables Testing | Typical Flags |
-|-----------|-----------------|---------------|
-| `error_state` | Error messages, retry UI, fallback displays | `forceError`, `mockErrorMessage` |
-| `premium_user` | Premium badges, gated features, upgrade prompts | `forcePremium`, `mockPremiumData` |
-| `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:**
-
-```markdown
-**To enable {state_name}:**
-1. Open `{override_file_path}`
-2. Set `{flag_name} = true`
-3. {Hot reload command or restart instruction}
-4. Verify: {What user should see to confirm mock is active}
-
-**To disable:**
-1. Set `{flag_name} = false`
-2. {Hot reload / restart}
-```
-
-**Framework-specific apply instructions:**
-
-| Framework | Apply Changes |
-|-----------|---------------|
-| Flutter | Hot reload (r in terminal) or hot restart (R) |
-| React/Next.js (dev) | Auto hot reload on save |
-| React Native | Shake device → Reload, or `r` in Metro |
-| Vue (dev) | Auto hot reload on save |
-
-</toggle_instructions_template>
-
-<spawn_mock_generator>
-
-When verify-work needs mocks:
-
-```
-Task(
-  prompt="""
-You are generating test mocks for manual UI verification.
-
-## Context
-
-Project type: {detected_framework}
-Phase: {phase_name}
-Mock type needed: {mock_type}
-
-## Tests requiring this mock
-
-{test_list_with_expected_behavior}
-
-## Requirements
-
-1. Create override file at standard location for this framework
-2. Add minimal hooks to relevant services (if needed)
-3. Provide clear toggle instructions
-4. Write all files to disk
-
-Follow the patterns from @~/.claude/mindsystem/workflows/generate-mocks.md
-""",
-  subagent_type="ms-mock-generator",
-  description="Generate {mock_type} mocks"
-)
-```
-
-</spawn_mock_generator>
-
-<success_criteria>
-- [ ] Framework correctly detected
-- [ ] Override file created at standard location
-- [ ] Minimal hooks added (only if needed)
-- [ ] Toggle instructions clear and complete
-- [ ] Files written to disk (uncommitted)
-- [ ] Easy to remove (clear cleanup path)
-</success_criteria>