mindsystem-cc 3.13.1 → 3.16.0

package/mindsystem/templates/UAT.md

@@ -127,277 +127,3 @@ mock_type: empty_response
   reason: "[user-provided reason when skipping batch]"
 ```
 
----
-
-<section_rules>
-
-**Frontmatter:**
-- `status`: OVERWRITE - "testing", "fixing", or "complete"
-- `phase`: IMMUTABLE - set on creation
-- `source`: IMMUTABLE - SUMMARY files being tested
-- `started`: IMMUTABLE - set on creation
-- `updated`: OVERWRITE - update on every change
-- `current_batch`: OVERWRITE - current batch number
-- `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:**
-- OVERWRITE after each test result or fix
-- Tracks: total, tested, passed, issues, fixing, pending, skipped
-
-**Current Batch:**
-- OVERWRITE entirely on batch transitions
-- Shows which batch is active
-
-**Tests:**
-- Each test: OVERWRITE result/fix fields when status changes
-- `result` values: [pending], pass, issue, blocked, skipped
-- If issue: add `reported` (verbatim), `severity` (inferred), `fix_status`, `fix_commit`, `retry_count`
-- If blocked: no additional fields (will be re-tested)
-- If skipped: add `reason`
-
-**Fixes Applied:**
-- APPEND only when fix committed
-- Records commit hash, test number, description, files
-
-**Batches:**
-- Each batch: OVERWRITE status and counts as batch progresses
-- Tracks: tests, status, mock_type, passed, issues
-
-**Assumptions:**
-- APPEND when test is skipped
-- Records test number, name, expected behavior, reason
-
-</section_rules>
-
-<fix_lifecycle>
-
-**When issue reported:**
-1. result → "issue"
-2. Add `reported`, `severity`
-3. Add `fix_status: investigating`, `retry_count: 0`
-
-**When fix committed:**
-4. `fix_status: applied`
-5. `fix_commit: {hash}`
-6. Append to "Fixes Applied" section
-
-**When re-test passes:**
-7. result → "pass"
-8. `fix_status: verified`
-
-**When re-test fails:**
-9. Increment `retry_count`
-10. If `retry_count >= 2`: offer skip/escalate options
-11. If user chooses skip: result → "skipped", add reason
-
-</fix_lifecycle>
-
-<mock_lifecycle>
-
-**When batch needs mocks:**
-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" -- <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. Revert old mocks: `git checkout -- <mocked_files>`
-2. Clear `mocked_files`, apply new inline mocks
-
-**On session complete:**
-1. Revert all mocks: `git checkout -- <mocked_files>`
-2. Restore pre_work_stash if exists
-
-</mock_lifecycle>
-
-<resume_behavior>
-
-On `/ms:verify-work` with existing UAT.md:
-
-1. Check `status`:
-   - "complete" → offer to re-run or view results
-   - "testing" or "fixing" → resume
-
-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
-
-4. Check for tests with `fix_status: investigating` or `fix_status: applied`:
-   - Resume fix/re-test flow for those
-
-5. Present remaining tests in current batch
-
-</resume_behavior>
-
-<severity_guide>
-
-Severity is INFERRED from user's natural language, never asked.
-
-| User describes | Infer |
-|----------------|-------|
-| Crash, error, exception, fails completely, unusable | blocker |
-| Doesn't work, nothing happens, wrong behavior, missing | major |
-| Works but..., slow, weird, off, minor, small | minor |
-| Color, font, spacing, alignment, looks off | cosmetic |
-
-Default: **major** (safe default, user can clarify if wrong)
-
-</severity_guide>
-
-<good_example>
-```markdown
----
-status: fixing
-phase: 04-comments
-source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
-started: 2025-01-15T10:30:00Z
-updated: 2025-01-15T11:15:00Z
-current_batch: 2
-mocked_files: [src/services/auth_service.dart, src/services/api_service.dart]
-pre_work_stash: null
----
-
-## Progress
-
-total: 12
-tested: 7
-passed: 5
-issues: 1
-fixing: 1
-pending: 5
-skipped: 0
-
-## Current Batch
-
-batch: 2 of 4
-name: "Error States"
-mock_type: error_state
-tests: [4, 5, 6, 7]
-status: testing
-
-## Tests
-
-### 1. View Comments on Post
-expected: Comments section expands, shows count and comment list
-mock_required: false
-mock_type: null
-result: pass
-
-### 2. Create Top-Level Comment
-expected: Submit comment via rich text editor, appears in list with author info
-mock_required: false
-mock_type: null
-result: pass
-
-### 3. Reply to a Comment
-expected: Click Reply, inline composer appears, submit shows nested reply
-mock_required: false
-mock_type: null
-result: pass
-
-### 4. Login Error Message
-expected: Invalid credentials show "Invalid email or password" message
-mock_required: true
-mock_type: error_state
-result: issue
-reported: "Shows 'Something went wrong' instead of specific error"
-severity: major
-fix_status: applied
-fix_commit: abc123f
-retry_count: 0
-
-### 5. Network Error Handling
-expected: No connection shows "Check your internet connection" with retry button
-mock_required: true
-mock_type: error_state
-result: [pending]
-
-### 6. Server Error Display
-expected: 500 error shows "Try again later" message
-mock_required: true
-mock_type: error_state
-result: [pending]
-
-### 7. Rate Limit Message
-expected: Too many requests shows "Too many attempts" with countdown
-mock_required: true
-mock_type: error_state
-result: [pending]
-
-### 8. Premium Badge Display
-expected: Premium users show gold badge on profile
-mock_required: true
-mock_type: premium_user
-result: [pending]
-
-### 9. Premium Feature Access
-expected: Premium features accessible, non-premium shows upgrade prompt
-mock_required: true
-mock_type: premium_user
-result: [pending]
-
-### 10. Subscription Status
-expected: Account page shows current subscription tier and expiry
-mock_required: true
-mock_type: premium_user
-result: [pending]
-
-### 11. Empty Comments List
-expected: Post with no comments shows "No comments yet" placeholder
-mock_required: true
-mock_type: empty_response
-result: [pending]
-
-### 12. Empty Search Results
-expected: Search with no matches shows "No results found" with suggestions
-mock_required: true
-mock_type: empty_response
-result: [pending]
-
-## Fixes Applied
-
-- commit: abc123f
-  test: 4
-  description: "Display actual error message from API response"
-  files: [src/components/ErrorBanner.tsx]
-
-## Batches
-
-### Batch 1: No Mocks Required
-tests: [1, 2, 3]
-status: complete
-mock_type: null
-passed: 3
-issues: 0
-
-### Batch 2: Error States
-tests: [4, 5, 6, 7]
-status: in_progress
-mock_type: error_state
-passed: 0
-issues: 1
-
-### Batch 3: Premium Features
-tests: [8, 9, 10]
-status: pending
-mock_type: premium_user
-
-### Batch 4: Empty States
-tests: [11, 12]
-status: pending
-mock_type: empty_response
-
-## Assumptions
-
-[none yet]
-```
-</good_example>

package/mindsystem/templates/context.md

@@ -161,17 +161,7 @@ Priority is clarity over features. Better to show less and make it obvious than
 1. **Vision sections** (`<vision>`, `<essential>`, `<specifics>`, `<notes>`) — for human understanding
 2. **Decision sections** (`<decisions>`, `<deferred>`) — for downstream agent parsing
 
-The user is the visionary. They know:
-- How they imagine it working
-- What it should feel like
-- What's essential vs nice-to-have
-- References to things they like
-
-The user does NOT know (and shouldn't be asked):
-- Codebase patterns (Claude reads the code)
-- Technical risks (Claude identifies during research)
-- Implementation constraints (Claude figures out)
-- Success metrics (Claude infers from the work)
+Vision sections capture the user's own words — how they imagine it, what they reference, what excites them. Do not inject technical analysis, risk assessment, or implementation constraints into vision sections.
 
 **Vision content should read like:**
 - A founder describing their product vision

package/mindsystem/templates/discovery.md

@@ -119,11 +119,10 @@ Create `.planning/phases/XX-name/DISCOVERY.md`:
 </output_structure>
 
 <success_criteria>
-- All scope questions answered with authoritative sources
+- Low-confidence findings marked with validation checkpoints
 - Quality checklist items completed
+- All scope questions answered with authoritative sources
 - Clear primary recommendation
-- Low-confidence findings marked with validation checkpoints
-- Ready to inform PLAN.md creation
 </success_criteria>
 
 <guidelines>

package/mindsystem/templates/knowledge.md

@@ -0,0 +1,99 @@
+# Knowledge Template
+
+Template for `.planning/knowledge/{subsystem}.md` — per-subsystem knowledge files that persist across phases and milestones.
+
+**Purpose:** Curated reference per domain area. Bridges phase-scoped execution artifacts to topic-scoped knowledge. Each file contains decisions, architecture, design, pitfalls, and key files for one subsystem.
+
+**Created by:** `ms-consolidator` agent during `execute-phase`
+
+**Referenced by:** All pre-planning phases (discuss-phase, design-phase, research-phase, plan-phase)
+
+---
+
+<template>
+
+```markdown
+# {subsystem}
+
+> {One-line summary of what this subsystem does and the current approach.}
+
+## Decisions
+
+| Decision | Rationale | Source |
+|----------|-----------|--------|
+| {choice in 5-10 words} | {reason in 5-10 words} | {vX.Y phase N} |
+
+## Architecture
+
+- {Structural pattern or flow description}
+- {How components connect and interact}
+
+## Design
+
+- {Visual/UX spec, interaction pattern, or design token}
+- {Component state, layout choice, or color value}
+
+## Pitfalls
+
+- **{Brief title}**: {What to watch out for and why}
+- **{Brief title}**: {Operational pattern or known trap}
+
+## Key Files
+
+- `{path/to/file}` — {What it does}
+- `{path/to/file}` — {What it does}
+```
+
+</template>
+
+<guidelines>
+
+## Section Purposes
+
+| Section | Captures | Source Artifacts |
+|---------|----------|-----------------|
+| **Decisions** | Choices with rationale (the "because" part) | CONTEXT.md locked decisions, RESEARCH.md recommendations, PLAN.md approach rationale, SUMMARY.md key-decisions |
+| **Architecture** | How the subsystem works, structural patterns | RESEARCH.md architecture patterns, PLAN.md implementation details, SUMMARY.md accomplishments |
+| **Design** | Visual/UX specs, interaction patterns, design tokens | DESIGN.md component specs, UX flows, color/spacing values |
+| **Pitfalls** | What to watch out for, operational patterns | RESEARCH.md common pitfalls, SUMMARY.md issues/deviations, debug resolutions, adhoc learnings |
+| **Key Files** | Important file paths for this subsystem | SUMMARY.md key-files, PLAN.md file targets |
+
+## Format Rules
+
+- **Omit empty sections.** A subsystem with no design work has no Design section.
+- **No frontmatter.** Filename is the address (`knowledge/auth.md` = auth subsystem). The one-line summary under the heading provides orientation.
+- **Decisions table is concise.** 5-10 words per cell. Extract the "because" — not a description of what was done.
+- **Architecture and Design use prose bullets.** Describe how things work, not tables.
+- **Pitfalls use bold titles** for scannability.
+- **Key Files is a flat list.** No nesting, no grouping.
+- **Rewrite semantics, not append.** Each consolidation produces the current state. Superseded decisions get updated. Outdated patterns get removed. The file is always current.
+
+## Cross-Reference Pattern
+
+When a subsystem's knowledge references another subsystem, add a parenthetical cross-reference:
+
+```markdown
+- JWT tokens validated by API middleware on all protected routes (see api subsystem)
+```
+
+The cross-reference is navigational, not essential. Each file is self-contained for its consumer.
+
+## Good vs Bad Entries
+
+**Good decision entries:**
+- `jose over jsonwebtoken | Better TypeScript support, actively maintained | v1.0 phase 2`
+- `httpOnly cookies over localStorage | XSS prevention | v1.0 phase 2`
+
+**Bad decision entries:**
+- `Use React | — | 1` (no rationale)
+- `Implemented authentication | Users can log in | 2` (not a decision, just work done)
+
+**Good pitfall entries:**
+- **bcrypt cost factor**: Use 12, not 10. Cost factor 10 is brute-forceable on modern GPUs
+- **JWT payload size**: Keep under 4KB — cookie size limits vary by browser
+
+**Bad pitfall entries:**
+- Fixed a bug in auth (description, not a reusable pattern)
+- Missing import in login.ts (trivial, not worth persisting)
+
+</guidelines>

package/mindsystem/templates/requirements.md

@@ -110,23 +110,7 @@ Which phases cover which requirements. Updated by create-roadmap.
 </guidelines>
 
 <evolution>
-
-**After each phase completes:**
-1. Mark covered requirements as Complete
-2. Update traceability status
-3. Note any requirements that changed scope
-
-**After roadmap updates:**
-1. Verify all v1 requirements still mapped
-2. Add new requirements if scope expanded
-3. Move requirements to v2/out of scope if descoped
-
-**Requirement completion criteria:**
-- Requirement is "Complete" when:
-  - Feature is implemented
-  - Feature is verified (tests pass, manual check done)
-  - Feature is committed
-
+Update requirements after phase completion: mark requirements Complete, update traceability status. After roadmap changes: verify all v1 requirements still mapped, add/move requirements as scope changes. A requirement is "Complete" when implemented, verified, and committed.
 </evolution>
 
 <example>
@@ -143,31 +127,13 @@ Which phases cover which requirements. Updated by create-roadmap.
 
 - [ ] **AUTH-01**: User can sign up with email and password
 - [ ] **AUTH-02**: User receives email verification after signup
-- [ ] **AUTH-03**: User can reset password via email link
-- [ ] **AUTH-04**: User session persists across browser refresh
 
 ### Profiles
 
 - [ ] **PROF-01**: User can create profile with display name
 - [ ] **PROF-02**: User can upload avatar image
-- [ ] **PROF-03**: User can write bio (max 500 chars)
-- [ ] **PROF-04**: User can view other users' profiles
-
-### Content
 
-- [ ] **CONT-01**: User can create text post
-- [ ] **CONT-02**: User can upload image with post
-- [ ] **CONT-03**: User can edit own posts
-- [ ] **CONT-04**: User can delete own posts
-- [ ] **CONT-05**: User can view feed of posts
-
-### Social
-
-- [ ] **SOCL-01**: User can follow other users
-- [ ] **SOCL-02**: User can unfollow users
-- [ ] **SOCL-03**: User can like posts
-- [ ] **SOCL-04**: User can comment on posts
-- [ ] **SOCL-05**: User can view activity feed (followed users' posts)
+[... additional categories ...]
 
 ## v2 Requirements
 
@@ -175,16 +141,7 @@ Which phases cover which requirements. Updated by create-roadmap.
 
 - **NOTF-01**: User receives in-app notifications
 - **NOTF-02**: User receives email for new followers
-- **NOTF-03**: User receives email for comments on own posts
-- **NOTF-04**: User can configure notification preferences
-
-### Moderation
-
-- **MODR-01**: User can report content
-- **MODR-02**: User can block other users
-- **MODR-03**: Admin can view reported content
-- **MODR-04**: Admin can remove content
-- **MODR-05**: Admin can ban users
+- **NOTF-03**: User can configure notification preferences
 
 ## Out of Scope
 
@@ -193,7 +150,6 @@ Which phases cover which requirements. Updated by create-roadmap.
 | Real-time chat | High complexity, not core to community value |
 | Video posts | Storage/bandwidth costs, defer to v2+ |
 | OAuth login | Email/password sufficient for v1 |
-| Mobile app | Web-first, mobile later |
 
 ## Traceability
 
@@ -201,22 +157,8 @@ Which phases cover which requirements. Updated by create-roadmap.
 |-------------|-------|--------|
 | AUTH-01 | Phase 1 | Pending |
 | AUTH-02 | Phase 1 | Pending |
-| AUTH-03 | Phase 1 | Pending |
-| AUTH-04 | Phase 1 | Pending |
 | PROF-01 | Phase 2 | Pending |
 | PROF-02 | Phase 2 | Pending |
-| PROF-03 | Phase 2 | Pending |
-| PROF-04 | Phase 2 | Pending |
-| CONT-01 | Phase 3 | Pending |
-| CONT-02 | Phase 3 | Pending |
-| CONT-03 | Phase 3 | Pending |
-| CONT-04 | Phase 3 | Pending |
-| CONT-05 | Phase 3 | Pending |
-| SOCL-01 | Phase 4 | Pending |
-| SOCL-02 | Phase 4 | Pending |
-| SOCL-03 | Phase 4 | Pending |
-| SOCL-04 | Phase 4 | Pending |
-| SOCL-05 | Phase 4 | Pending |
 
 **Coverage:**
 - v1 requirements: 18 total

package/mindsystem/templates/research-comparison-output.md

@@ -0,0 +1,50 @@
+# Comparison Output Template
+
+Template for comparison research — side-by-side evaluation of alternatives.
+
+**Purpose:** Provide a structured comparison matrix with clear recommendation for technology/approach decisions.
+
+**Created by:** `ms-researcher` agent during comparison research mode
+
+---
+
+## File Template
+
+```markdown
+# Comparison: [Option A] vs [Option B] vs [Option C]
+
+**Context:** [what we're deciding]
+**Recommendation:** [option] because [one-liner reason]
+
+## Quick Comparison
+
+| Criterion | [A] | [B] | [C] |
+|-----------|-----|-----|-----|
+| [criterion 1] | [rating/value] | [rating/value] | [rating/value] |
+| [criterion 2] | [rating/value] | [rating/value] | [rating/value] |
+
+## Detailed Analysis
+
+### [Option A]
+**Strengths:**
+- [strength 1]
+- [strength 2]
+
+**Weaknesses:**
+- [weakness 1]
+
+**Best for:** [use cases]
+
+### [Option B]
+...
+
+## Recommendation
+
+[1-2 paragraphs explaining the recommendation]
+
+**Choose [A] when:** [conditions]
+**Choose [B] when:** [conditions]
+
+## Sources
+[URLs with confidence levels]
+```

package/mindsystem/templates/research-feasibility-output.md

@@ -0,0 +1,43 @@
+# Feasibility Assessment Output Template
+
+Template for feasibility research — can we actually do this?
+
+**Purpose:** Provide a clear yes/no/maybe verdict with evidence for technical feasibility decisions.
+
+**Created by:** `ms-researcher` agent during feasibility research mode
+
+---
+
+## File Template
+
+```markdown
+# Feasibility Assessment: [Goal]
+
+**Verdict:** [YES / NO / MAYBE with conditions]
+**Confidence:** [HIGH/MEDIUM/LOW]
+
+## Summary
+
+[2-3 paragraph assessment]
+
+## Requirements
+
+What's needed to achieve this:
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| [req 1] | [available/partial/missing] | [details] |
+
+## Blockers
+
+| Blocker | Severity | Mitigation |
+|---------|----------|------------|
+| [blocker] | [high/medium/low] | [how to address] |
+
+## Recommendation
+
+[What to do based on findings]
+
+## Sources
+[URLs with confidence levels]
+```

package/mindsystem/templates/research-project-output.md

@@ -0,0 +1,81 @@
+# Project Research Output Template
+
+Template for `.planning/research/` files — research before creating roadmap.
+
+**Purpose:** Document ecosystem-level findings for a whole project, informing phase structure and technology choices.
+
+**Created by:** `ms-researcher` agent during `/ms:research-project`
+
+---
+
+## Output Files
+
+### SUMMARY.md
+
+Executive summary synthesizing all research with roadmap implications.
+
+```markdown
+# Research Summary: [Project Name]
+
+**Domain:** [type of product]
+**Researched:** [date]
+**Overall confidence:** [HIGH/MEDIUM/LOW]
+
+## Executive Summary
+
+[3-4 paragraphs synthesizing all findings]
+
+## Key Findings
+
+**Stack:** [one-liner from STACK.md]
+**Architecture:** [one-liner from ARCHITECTURE.md]
+**Critical pitfall:** [most important from PITFALLS.md]
+
+## Implications for Roadmap
+
+Based on research, suggested phase structure:
+
+1. **[Phase name]** - [rationale]
+   - Addresses: [features from FEATURES.md]
+   - Avoids: [pitfall from PITFALLS.md]
+
+2. **[Phase name]** - [rationale]
+   ...
+
+**Phase ordering rationale:**
+- [Why this order based on dependencies]
+
+**Research flags for phases:**
+- Phase [X]: Likely needs deeper research (reason)
+- Phase [Y]: Standard patterns, unlikely to need research
+
+## Confidence Assessment
+
+| Area | Confidence | Notes |
+|------|------------|-------|
+| Stack | [level] | [reason] |
+| Features | [level] | [reason] |
+| Architecture | [level] | [reason] |
+| Pitfalls | [level] | [reason] |
+
+## Gaps to Address
+
+- [Areas where research was inconclusive]
+- [Topics needing phase-specific research later]
+```
+
+### STACK.md
+
+Recommended technologies with versions and rationale.
+
+### FEATURES.md
+
+Feature landscape - table stakes, differentiators, anti-features.
+
+### ARCHITECTURE.md
+
+System structure patterns with component boundaries.
+
+### PITFALLS.md
+
+Common mistakes with prevention strategies.