mindsystem-cc 3.0.0

package/mindsystem/references/goal-backward.md

@@ -0,0 +1,286 @@
+# Goal-Backward Planning
+
+How to derive requirements by working backwards from the goal, not forwards from tasks.
+
+<core_principle>
+**Forward planning asks:** "What should we build?"
+**Goal-backward planning asks:** "What must be TRUE for the goal to be achieved?"
+
+Forward planning produces tasks. Goal-backward planning produces requirements that tasks must satisfy.
+</core_principle>
+
+<why_this_matters>
+Forward planning fails silently. A task like "create chat component" can be marked complete when the component is a placeholder. The task was done—a component was created—but the goal "working chat interface" was not achieved.
+
+Goal-backward planning starts from "user can chat" and works backwards:
+- What must be TRUE for a user to chat?
+- What must EXIST for those truths to hold?
+- What must be WIRED for those artifacts to function?
+
+This produces must-haves that are verifiable. Either a user CAN chat, or they can't. No ambiguity.
+</why_this_matters>
+
+<the_process>
+
+## Step 1: State the Goal
+
+Take the phase goal from ROADMAP.md. This is the outcome, not the work.
+
+**Examples:**
+- "Working chat interface" (not "build chat components")
+- "Users can authenticate" (not "implement auth system")
+- "Products display with prices" (not "create product pages")
+
+If the roadmap goal is task-shaped ("implement X"), reframe it as outcome-shaped ("X works").
+
+## Step 2: Derive Observable Truths
+
+Ask: **"What must be TRUE for this goal to be achieved?"**
+
+List 3-7 truths from the USER's perspective. These are observable behaviors, not implementation details.
+
+**For "working chat interface":**
+- User can see existing messages
+- User can type a new message
+- User can send the message
+- Sent message appears in the list
+- Messages persist across page refresh
+
+**For "users can authenticate":**
+- User can reach login page
+- User can enter credentials
+- Valid credentials grant access
+- Invalid credentials show error
+- Session persists across refresh
+- User can log out
+
+**Test:** Each truth should be verifiable by a human using the application. If you can't test it by clicking around, it's not observable.
+
+## Step 3: Derive Required Artifacts
+
+For each truth, ask: **"What must EXIST for this to be true?"**
+
+Map truths to concrete artifacts (files, routes, schemas, components).
+
+**"User can see existing messages" requires:**
+- Message list component (renders Message[])
+- Messages state (loaded from somewhere)
+- API route or data source (provides messages)
+- Message type definition (shapes the data)
+
+**"Valid credentials grant access" requires:**
+- Login form component (captures credentials)
+- Auth API route (validates credentials)
+- Session/token mechanism (persists auth state)
+- User record in database (to validate against)
+
+**Test:** Each artifact should be a specific file or database object. If you can't point to where it lives, it's too abstract.
+
+## Step 4: Derive Required Wiring
+
+For each artifact, ask: **"What must be CONNECTED for this artifact to function?"**
+
+Wiring is where most failures hide. The pieces exist but don't talk to each other.
+
+**Message list component wiring:**
+- Imports Message type (not using `any`)
+- Receives messages prop or fetches from API
+- Maps over messages to render (not hardcoded)
+- Handles empty state (not just crashes)
+
+**Auth API route wiring:**
+- Imports database client
+- Queries users table (not placeholder)
+- Compares password hash (not plaintext)
+- Returns session token (not empty response)
+
+**Test:** Wiring is verified by tracing data flow. Does A actually call B? Does B actually return to A? Does A actually use what B returned?
+
+## Step 5: Identify Key Links
+
+Ask: **"Where is this most likely to break?"**
+
+Key links are the critical connections that, if missing, cause cascading failures.
+
+**For chat interface:**
+- Input onSubmit → API call (if broken: typing works but sending doesn't)
+- API save → database (if broken: appears to send but doesn't persist)
+- Component → real data (if broken: shows placeholder, not messages)
+
+**For authentication:**
+- Form submit → API (if broken: form works but auth doesn't)
+- API → database query (if broken: accepts any password)
+- Session → protected routes (if broken: logged in but can't access anything)
+
+Key links get extra verification attention. These are where stubs and placeholders hide.
+
+</the_process>
+
+<output_format>
+The derive_must_haves step produces a structured list for PLAN.md frontmatter:
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+    - "Messages persist across refresh"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+    - path: "src/app/api/chat/route.ts"
+      provides: "Message CRUD operations"
+    - path: "prisma/schema.prisma"
+      provides: "Message model"
+  key_links:
+    - from: "Chat.tsx"
+      to: "api/chat"
+      via: "fetch in useEffect"
+    - from: "api/chat POST"
+      to: "database"
+      via: "prisma.message.create"
+```
+
+This structure is machine-readable for verification after execution.
+</output_format>
+
+<examples>
+
+## Example 1: E-commerce Product Page
+
+**Goal:** "Products display with prices and add-to-cart"
+
+**Truths:**
+- User can see product image
+- User can see product name and description
+- User can see product price
+- User can click "Add to Cart"
+- Cart updates when product added
+
+**Artifacts:**
+- `src/components/ProductCard.tsx` - displays product info
+- `src/components/AddToCart.tsx` - button with cart logic
+- `src/app/products/[id]/page.tsx` - product detail page
+- `src/hooks/useCart.ts` - cart state management
+- `prisma/schema.prisma` - Product model with price field
+
+**Key Links:**
+- ProductCard receives product data (not hardcoded)
+- AddToCart calls cart hook (not just console.log)
+- useCart persists to localStorage or API (not just memory)
+- Price displays from product.price (not placeholder "$XX.XX")
+
+---
+
+## Example 2: User Settings Page
+
+**Goal:** "Users can update their profile settings"
+
+**Truths:**
+- User can see current settings values
+- User can edit each setting field
+- User can save changes
+- Saved changes persist
+- User sees confirmation of save
+
+**Artifacts:**
+- `src/app/settings/page.tsx` - settings page
+- `src/components/SettingsForm.tsx` - form with fields
+- `src/app/api/settings/route.ts` - GET and PUT endpoints
+- `prisma/schema.prisma` - User model with settings fields
+
+**Key Links:**
+- Form loads current values on mount (not empty defaults)
+- Submit calls API with form data (not console.log)
+- API updates database (not just returns success)
+- Success triggers UI feedback (not silent)
+
+---
+
+## Example 3: Real-time Notifications
+
+**Goal:** "Users receive notifications in real-time"
+
+**Truths:**
+- User sees notification badge/indicator
+- New notifications appear without refresh
+- User can view notification list
+- User can mark notifications as read
+- Read state persists
+
+**Artifacts:**
+- `src/components/NotificationBell.tsx` - badge/indicator
+- `src/components/NotificationList.tsx` - dropdown/panel
+- `src/app/api/notifications/route.ts` - CRUD endpoints
+- `src/hooks/useNotifications.ts` - real-time subscription
+- `prisma/schema.prisma` - Notification model
+
+**Key Links:**
+- useNotifications connects to WebSocket/SSE (not polling placeholder)
+- NotificationBell shows actual unread count (not hardcoded)
+- Mark-as-read calls API (not just local state)
+- API broadcasts to other clients (if multi-device)
+
+</examples>
+
+<common_failures>
+
+## Failure: Truths Too Vague
+
+**Bad:** "User can use chat"
+**Good:** "User can see messages", "User can send message", "Messages persist"
+
+Vague truths can't be verified. Break them into specific, observable behaviors.
+
+## Failure: Artifacts Too Abstract
+
+**Bad:** "Chat system", "Auth module"
+**Good:** "src/components/Chat.tsx", "src/app/api/auth/login/route.ts"
+
+Abstract artifacts can't be checked. Point to specific files.
+
+## Failure: Missing Wiring
+
+**Bad:** Listing components without how they connect
+**Good:** "Chat.tsx fetches from /api/chat via useEffect on mount"
+
+Artifacts existing isn't enough. The connections between them are where stubs hide.
+
+## Failure: Skipping Key Links
+
+**Bad:** Assuming "if files exist, it works"
+**Good:** Identifying the 2-3 critical connections that make-or-break the goal
+
+Key links are verification priorities. Without them, you check everything equally (inefficient) or check nothing deeply (ineffective).
+
+</common_failures>
+
+<integration_with_gsd>
+
+## In plan-phase.md
+
+The `derive_must_haves` step runs after gathering context, before breaking into tasks.
+
+Output: `must_haves` structure written to PLAN.md frontmatter.
+
+Tasks are then designed to CREATE the artifacts and ESTABLISH the wiring.
+
+## In execute-phase.md
+
+The `verify_phase_goal` step runs after all plans execute, before updating roadmap.
+
+Input: `must_haves` from PLAN.md frontmatter (or derived from goal if missing).
+
+Process: Check each truth against codebase, verify artifacts exist and aren't stubs, trace key links.
+
+Output: VERIFICATION.md with pass/fail per item, fix recommendations if gaps found.
+
+## The Loop
+
+```
+derive_must_haves → tasks → execute → verify → [gaps?] → fix plans → execute → verify → pass
+```
+
+Must-haves are derived once, verified as many times as needed until all pass.
+
+</integration_with_gsd>

package/mindsystem/references/mock-patterns.md

@@ -0,0 +1,294 @@
+<overview>
+Mock patterns for manual UAT testing. Mocks are temporary scaffolding to reach testable UI states. They exist only as uncommitted changes — never in commit history.
+</overview>
+
+<philosophy>
+**Mocks enable testing states you can't easily reach.**
+
+Without mocks, testing "error message display" requires actually triggering server errors. Testing "premium user badge" requires a premium account. Testing "empty list placeholder" requires deleting all data.
+
+**With mocks:** Set a flag, hot reload, test the UI state.
+
+**Core principles:**
+1. **Temporary** — Mocks are stashed/discarded, never committed
+2. **Minimal** — One override file, minimal production hooks
+3. **Explicit** — Clear flags, clear toggle instructions
+4. **Removable** — Delete file + remove imports = clean
+</philosophy>
+
+<git_stash_lifecycle>
+
+**Why stash?**
+
+Fixes must be clean commits (no mock code). But after fixing, we need mocks back to re-test. Git stash enables this:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 1: Setup                                              │
+├─────────────────────────────────────────────────────────────┤
+│ 1. git stash push -m "pre-verify-work" (if dirty)          │
+│ 2. Mock Generator creates mock code (uncommitted)           │
+│ 3. User confirms mocks look correct                         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 2: Test-Fix Loop (per issue)                          │
+├─────────────────────────────────────────────────────────────┤
+│ 4. User tests on device with mocks active                   │
+│ 5. User reports issue                                       │
+│ 6. git stash push -m "mocks-batch-N"  ← Stash mocks        │
+│ 7. Fixer investigates and commits fix  ← Clean commit      │
+│ 8. git stash pop                       ← Restore mocks     │
+│ 9. User re-tests specific item                             │
+│ 10. Repeat until fixed or skip                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 3: Cleanup                                            │
+├─────────────────────────────────────────────────────────────┤
+│ 11. git stash drop                     ← Discard mocks     │
+│ 12. Generate UAT fixes patch                                │
+│ 13. git stash pop (if pre-existing)    ← Restore user work │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Stash naming convention:**
+- `pre-verify-work` — User's original uncommitted work
+- `mocks-batch-N` — Current mock state for batch N
+
+</git_stash_lifecycle>
+
+<conflict_resolution>
+
+**When git stash pop conflicts:**
+
+This happens when a fix modified the same file as a mock. Resolution:
+
+```bash
+# Conflict means fix touched mock code — take the fix version
+git checkout --theirs <conflicted-file>
+git add <conflicted-file>
+```
+
+**Why take fix version?**
+- The fix is committed, intentional work
+- The mock for that file is likely no longer needed (fix replaced relevant code)
+- Regenerating mock for that specific file is easy if still needed
+
+**This is rare.** Mocks typically live in data layer, fixes often in UI layer.
+
+</conflict_resolution>
+
+<flutter_example>
+
+**Override file: `lib/test_overrides.dart`**
+
+```dart
+// Test Overrides - DELETE THIS FILE BEFORE COMMITTING
+// Used for manual UAT testing only
+
+class TestOverrides {
+  // === STATE FLAGS ===
+  static bool forcePremiumUser = false;
+  static bool forceErrorState = false;
+  static bool forceEmptyResponse = false;
+  static bool forceLoadingState = false;
+
+  // === MOCK DATA ===
+  static String mockErrorMessage = 'Simulated error for testing';
+  static Duration mockLoadingDelay = const Duration(seconds: 3);
+
+  static Map<String, dynamic> mockPremiumUser = {
+    'id': 'test-user-001',
+    'name': 'Test Premium User',
+    'isPremium': true,
+    'subscriptionTier': 'gold',
+  };
+
+  // === RESET ===
+  static void reset() {
+    forcePremiumUser = false;
+    forceErrorState = false;
+    forceEmptyResponse = false;
+    forceLoadingState = false;
+  }
+}
+```
+
+**Production hook: `lib/services/user_service.dart`**
+
+```dart
+import '../test_overrides.dart';
+
+class UserService {
+  Future<User> getCurrentUser() async {
+    // TEST OVERRIDE - Remove before commit
+    if (TestOverrides.forcePremiumUser) {
+      return User.fromJson(TestOverrides.mockPremiumUser);
+    }
+
+    // Real implementation
+    final response = await _api.get('/user/me');
+    return User.fromJson(response.data);
+  }
+
+  Future<List<Item>> getItems() async {
+    // TEST OVERRIDE - Remove before commit
+    if (TestOverrides.forceEmptyResponse) {
+      return [];
+    }
+    if (TestOverrides.forceErrorState) {
+      throw Exception(TestOverrides.mockErrorMessage);
+    }
+
+    // Real implementation
+    final response = await _api.get('/items');
+    return (response.data as List).map((j) => Item.fromJson(j)).toList();
+  }
+}
+```
+
+**Toggle instructions:**
+
+```
+To enable Premium User state:
+1. Open lib/test_overrides.dart
+2. Set TestOverrides.forcePremiumUser = true
+3. Hot reload (r in terminal)
+4. Verify: User profile shows "Premium" badge
+
+To enable Error State:
+1. Open lib/test_overrides.dart
+2. Set TestOverrides.forceErrorState = true
+3. Hot reload (r in terminal)
+4. Verify: Error message appears on relevant screens
+```
+
+</flutter_example>
+
+<react_example>
+
+**Override file: `src/testOverrides.ts`**
+
+```typescript
+// Test Overrides - DELETE THIS FILE BEFORE COMMITTING
+// Used for manual UAT testing only
+
+export const testOverrides = {
+  // === STATE FLAGS ===
+  forcePremiumUser: false,
+  forceErrorState: false,
+  forceEmptyResponse: false,
+  forceLoadingState: false,
+
+  // === MOCK DATA ===
+  mockErrorMessage: 'Simulated error for testing',
+  mockLoadingDelayMs: 3000,
+
+  mockPremiumUser: {
+    id: 'test-user-001',
+    name: 'Test Premium User',
+    isPremium: true,
+    subscriptionTier: 'gold',
+  },
+
+  // === RESET ===
+  reset() {
+    this.forcePremiumUser = false;
+    this.forceErrorState = false;
+    this.forceEmptyResponse = false;
+    this.forceLoadingState = false;
+  },
+};
+```
+
+**Production hook: `src/services/userService.ts`**
+
+```typescript
+import { testOverrides } from '../testOverrides';
+
+export async function getCurrentUser(): Promise<User> {
+  // TEST OVERRIDE - Remove before commit
+  if (testOverrides.forcePremiumUser) {
+    return testOverrides.mockPremiumUser as User;
+  }
+
+  // Real implementation
+  const response = await fetch('/api/user/me');
+  return response.json();
+}
+
+export async function getItems(): Promise<Item[]> {
+  // TEST OVERRIDE - Remove before commit
+  if (testOverrides.forceEmptyResponse) {
+    return [];
+  }
+  if (testOverrides.forceErrorState) {
+    throw new Error(testOverrides.mockErrorMessage);
+  }
+
+  // Real implementation
+  const response = await fetch('/api/items');
+  return response.json();
+}
+```
+
+**Toggle instructions:**
+
+```
+To enable Premium User state:
+1. Open src/testOverrides.ts
+2. Set forcePremiumUser: true
+3. Save file (auto hot reload in dev mode)
+4. Verify: User profile shows "Premium" badge
+
+To enable Error State:
+1. Open src/testOverrides.ts
+2. Set forceErrorState: true
+3. Save file (auto hot reload)
+4. Verify: Error message appears on relevant screens
+```
+
+</react_example>
+
+<best_practices>
+
+**Do:**
+- Keep all flags in one file
+- Use descriptive flag names (`forcePremiumUser` not `flag1`)
+- Add comments marking test-only code
+- Provide reset function
+- Document toggle instructions clearly
+
+**Don't:**
+- Create complex mock infrastructure
+- Add mocks in UI components (use service layer)
+- Commit mock code (ever)
+- Create multiple override files
+- Add conditional compilation / build flags
+
+**Signs you're over-engineering:**
+- More than one override file
+- Mock code in more than 3 production files
+- Complex mock data generators
+- Mocking at multiple layers simultaneously
+
+</best_practices>
+
+<cleanup>
+
+**After UAT complete:**
+
+1. `git stash drop` — Removes mock stash permanently
+2. Delete override file if still present
+3. Remove any imports/hooks still in production code
+
+**Verification:**
+```bash
+git status  # Should show no mock-related files
+grep -r "testOverrides" src/  # Should find nothing (or only the override file itself)
+```
+
+</cleanup>