mindforge-cc 2.1.0 → 2.1.2

package/docs/Templates/Project/RETROSPECTIVE.md

@@ -0,0 +1,54 @@
+# Project Retrospective
+
+*A living document updated after each milestone. Lessons feed forward into future planning.*
+
+## Milestone: v{version} — {name}
+
+**Shipped:** {date}
+**Phases:** {count} | **Plans:** {count} | **Sessions:** {count}
+
+### What Was Built
+- {Key deliverable 1}
+- {Key deliverable 2}
+- {Key deliverable 3}
+
+### What Worked
+- {Efficiency win or successful pattern}
+- {What went smoothly}
+
+### What Was Inefficient
+- {Missed opportunity}
+- {What took longer than expected}
+
+### Patterns Established
+- {New pattern or convention that should persist}
+
+### Key Lessons
+1. {Specific, actionable lesson}
+2. {Another lesson}
+
+### Cost Observations
+- Model mix: {X}% opus, {Y}% sonnet, {Z}% haiku
+- Sessions: {count}
+- Notable: {efficiency observation}
+
+---
+
+## Cross-Milestone Trends
+
+### Process Evolution
+
+| Milestone | Sessions | Phases | Key Change |
+|-----------|----------|--------|------------|
+| v{X} | {N} | {M} | {What changed in process} |
+
+### Cumulative Quality
+
+| Milestone | Tests | Coverage | Zero-Dep Additions |
+|-----------|-------|----------|-------------------|
+| v{X} | {N} | {Y}% | {count} |
+
+### Top Lessons (Verified Across Milestones)
+
+1. {Lesson verified by multiple milestones}
+2. {Another cross-validated lesson}

package/docs/Templates/Project/ROADMAP.md

@@ -0,0 +1,202 @@
+# Roadmap Template
+
+Template for `.planning/ROADMAP.md`.
+
+## Initial Roadmap (v1.0 Greenfield)
+
+```markdown
+# Roadmap: [Project Name]
+
+## Overview
+
+[One paragraph describing the journey from start to finish]
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: [Name]** - [One-line description]
+- [ ] **Phase 2: [Name]** - [One-line description]
+- [ ] **Phase 3: [Name]** - [One-line description]
+- [ ] **Phase 4: [Name]** - [One-line description]
+
+## Phase Details
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Nothing (first phase)
+**Requirements**: [REQ-01, REQ-02, REQ-03]  <!-- brackets optional, parser handles both formats -->
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans, e.g., "3 plans" or "TBD"]
+
+Plans:
+- [ ] 01-01: [Brief description of first plan]
+- [ ] 01-02: [Brief description of second plan]
+- [ ] 01-03: [Brief description of third plan]
+
+### Phase 2: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 1
+**Requirements**: [REQ-04, REQ-05]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 02-01: [Brief description]
+- [ ] 02-02: [Brief description]
+
+### Phase 2.1: Critical Fix (INSERTED)
+**Goal**: [Urgent work inserted between phases]
+**Depends on**: Phase 2
+**Success Criteria** (what must be TRUE):
+  1. [What the fix achieves]
+**Plans**: 1 plan
+
+Plans:
+- [ ] 02.1-01: [Description]
+
+### Phase 3: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 2
+**Requirements**: [REQ-06, REQ-07, REQ-08]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+  3. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 03-01: [Brief description]
+- [ ] 03-02: [Brief description]
+
+### Phase 4: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 3
+**Requirements**: [REQ-09, REQ-10]
+**Success Criteria** (what must be TRUE):
+  1. [Observable behavior from user perspective]
+  2. [Observable behavior from user perspective]
+**Plans**: [Number of plans]
+
+Plans:
+- [ ] 04-01: [Brief description]
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. [Name] | 0/3 | Not started | - |
+| 2. [Name] | 0/2 | Not started | - |
+| 3. [Name] | 0/2 | Not started | - |
+| 4. [Name] | 0/1 | Not started | - |
+```
+
+<guidelines>
+**Initial planning (v1.0):**
+- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12)
+- Each phase delivers something coherent
+- Phases can have 1+ plans (split if >3 tasks or multiple subsystems)
+- Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md)
+- No time estimates (this isn't enterprise PM)
+- Progress table updated by execute workflow
+- Plan count can be "TBD" initially, refined during planning
+
+**Success criteria:**
+- 2-5 observable behaviors per phase (from user's perspective)
+- Cross-checked against requirements during roadmap creation
+- Flow downstream to `must_haves` in plan-phase
+- Verified by verify-phase after execution
+- Format: "User can [action]" or "[Thing] works/exists"
+
+**After milestones ship:**
+- Collapse completed milestones in `<details>` tags
+- Add new milestone sections for upcoming work
+- Keep continuous phase numbering (never restart at 01)
+</guidelines>
+
+<status_values>
+- `Not started` - Haven't begun
+- `In progress` - Currently working
+- `Complete` - Done (add completion date)
+- `Deferred` - Pushed to later (with reason)
+</status_values>
+
+## Milestone-Grouped Roadmap (After v1.0 Ships)
+
+After completing first milestone, reorganize with milestone groupings:
+
+```markdown
+# Roadmap: [Project Name]
+
+## Milestones
+
+- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
+- 🚧 **v1.1 [Name]** - Phases 5-6 (in progress)
+- 📋 **v2.0 [Name]** - Phases 7-10 (planned)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
+
+### Phase 1: [Name]
+**Goal**: [What this phase delivers]
+**Plans**: 3 plans
+
+Plans:
+- [x] 01-01: [Brief description]
+- [x] 01-02: [Brief description]
+- [x] 01-03: [Brief description]
+
+[... remaining v1.0 phases ...]
+
+</details>
+
+### 🚧 v1.1 [Name] (In Progress)
+
+**Milestone Goal:** [What v1.1 delivers]
+
+#### Phase 5: [Name]
+**Goal**: [What this phase delivers]
+**Depends on**: Phase 4
+**Plans**: 2 plans
+
+Plans:
+- [ ] 05-01: [Brief description]
+- [ ] 05-02: [Brief description]
+
+[... remaining v1.1 phases ...]
+
+### 📋 v2.0 [Name] (Planned)
+
+**Milestone Goal:** [What v2.0 delivers]
+
+[... v2.0 phases ...]
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Foundation | v1.0 | 3/3 | Complete | YYYY-MM-DD |
+| 2. Features | v1.0 | 2/2 | Complete | YYYY-MM-DD |
+| 5. Security | v1.1 | 0/2 | Not started | - |
+```
+
+**Notes:**
+- Milestone emoji: ✅ shipped, 🚧 in progress, 📋 planned
+- Completed milestones collapsed in `<details>` for readability
+- Current/future milestones expanded
+- Continuous phase numbering (01-99)
+- Progress table includes milestone column

package/docs/Templates/Quality/DEBUG.md

@@ -0,0 +1,164 @@
+# Debug Template
+
+Template for `.planning/debug/[slug].md` — active debug session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | awaiting_human_verify | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - always reflects NOW -->
+
+hypothesis: [current theory being tested]
+test: [how testing it]
+expecting: [what result means if true/false]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then immutable -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages if any]
+reproduction: [how to trigger]
+started: [when it broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating after /clear -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered during investigation -->
+
+- timestamp: [when found]
+  checked: [what was examined]
+  found: [what was observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: OVERWRITE - reflects current phase
+- `trigger`: IMMUTABLE - verbatim user input, never changes
+- `created`: IMMUTABLE - set once
+- `updated`: OVERWRITE - update on every change
+
+**Current Focus:**
+- OVERWRITE entirely on each update
+- Always reflects what the agent is doing RIGHT NOW
+- If the agent reads this after /clear, it knows exactly where to resume
+- Fields: hypothesis, test, expecting, next_action
+
+**Symptoms:**
+- Written during initial gathering phase
+- IMMUTABLE after gathering complete
+- Reference point for what we're trying to fix
+- Fields: expected, actual, errors, reproduction, started
+
+**Eliminated:**
+- APPEND only - never remove entries
+- Prevents re-investigating dead ends after context reset
+- Each entry: hypothesis, evidence that disproved it, timestamp
+- Critical for efficiency across /clear boundaries
+
+**Evidence:**
+- APPEND only - never remove entries
+- Facts discovered during investigation
+- Each entry: timestamp, what checked, what found, implication
+- Builds the case for root cause
+
+**Resolution:**
+- OVERWRITE as understanding evolves
+- May update multiple times as fixes are tried
+- Final state shows confirmed root cause and verified fix
+- Fields: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**Creation:** Immediately when /mindforge-debug is called
+- Create file with trigger from user input
+- Set status to "gathering"
+- Current Focus: next_action = "gather symptoms"
+- Symptoms: empty, to be filled
+
+**During symptom gathering:**
+- Update Symptoms section as user answers questions
+- Update Current Focus with each question
+- When complete: status → "investigating"
+
+**During investigation:**
+- OVERWRITE Current Focus with each hypothesis
+- APPEND to Evidence with each finding
+- APPEND to Eliminated when hypothesis disproved
+- Update timestamp in frontmatter
+
+**During fixing:**
+- status → "fixing"
+- Update Resolution.root_cause when confirmed
+- Update Resolution.fix when applied
+- Update Resolution.files_changed
+
+**During verification:**
+- status → "verifying"
+- Update Resolution.verification with results
+- If verification fails: status → "investigating", try again
+
+**After self-verification passes:**
+- status -> "awaiting_human_verify"
+- Request explicit user confirmation in a checkpoint
+- Do NOT move file to resolved yet
+
+**On resolution:**
+- status → "resolved"
+- Move file to .planning/debug/resolved/ (only after user confirms fix)
+
+</lifecycle>
+
+<resume_behavior>
+
+When the agent reads this file after /clear:
+
+1. Parse frontmatter → know status
+2. Read Current Focus → know exactly what was happening
+3. Read Eliminated → know what NOT to retry
+4. Read Evidence → know what's been learned
+5. Continue from next_action
+
+The file IS the debugging brain. the agent should be able to resume perfectly from any interruption point.
+
+</resume_behavior>
+
+<size_constraint>
+
+Keep debug files focused:
+- Evidence entries: 1-2 lines each, just the facts
+- Eliminated: brief - hypothesis + why it failed
+- No narrative prose - structured data only
+
+If evidence grows very large (10+ entries), consider whether you're going in circles. Check Eliminated to ensure you're not re-treading.
+
+</size_constraint>

package/docs/Templates/Quality/UAT.md

@@ -0,0 +1,280 @@
+# UAT Template
+
+Template for `.planning/phases/XX-name/{phase_num}-UAT.md` — persistent UAT session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: testing | partial | complete | diagnosed
+phase: XX-name
+source: [list of SUMMARY.md files tested]
+started: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Environment Matrix
+<!-- Where this testing was performed -->
+
+| Device/OS    | Browser  | Status    | Notes |
+| :----------- | :------- | :-------- | :---- |
+| [e.g. macOS] | [Chrome] | [Pending] | []    |
+| [e.g. iOS]   | [Safari] | [Pending] | []    |
+
+## Compliance & Security Check
+<!-- Enterprise-level verification -->
+
+- [ ] [ ] **Accessibility (WCAG 2.1)**: [Status: Pass/Fail/NA]
+- [ ] [ ] **Data Privacy (GDPR/CCPA)**: [Status: Pass/Fail/NA]
+- [ ] [ ] **Security (OWASP Top 10)**: [Status: Pass/Fail/NA]
+
+## Current Test
+<!-- OVERWRITE each test - shows where we are -->
+
+number: [N]
+name: [test name]
+expected: |
+  [what user should observe]
+awaiting: user response
+
+## Tests
+
+### 1. [Test Name]
+expected: [observable behavior - what user should see]
+result: [pending]
+
+### 2. [Test Name]
+expected: [observable behavior]
+result: pass
+
+### 3. [Test Name]
+expected: [observable behavior]
+result: issue
+reported: "[verbatim user response]"
+severity: major
+
+### 4. [Test Name]
+expected: [observable behavior]
+result: skipped
+reason: [why skipped]
+
+### 5. [Test Name]
+expected: [observable behavior]
+result: blocked
+blocked_by: server | physical-device | release-build | third-party | prior-phase
+reason: [why blocked]
+
+...
+
+## Summary
+
+total: [N]
+passed: [N]
+issues: [N]
+pending: [N]
+skipped: [N]
+blocked: [N]
+
+## Gaps
+
+<!-- YAML format for plan-phase --gaps consumption -->
+- truth: "[expected behavior from test]"
+  status: failed
+  reason: "User reported: [verbatim response]"
+  severity: blocker | major | minor | cosmetic
+  test: [N]
+  root_cause: ""     # Filled by diagnosis
+  artifacts: []      # Filled by diagnosis
+  missing: []        # Filled by diagnosis
+  debug_session: ""  # Filled by diagnosis
+```
+
+---
+
+<section_rules>
+
+**Frontmatter:**
+- `status`: OVERWRITE - "testing", "partial", 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 Test:**
+- OVERWRITE entirely on each test transition
+- Shows which test is active and what's awaited
+- On completion: "[testing complete]"
+
+**Tests:**
+- Each test: OVERWRITE result field when user responds
+- `result` values: [pending], pass, issue, skipped, blocked
+- If issue: add `reported` (verbatim) and `severity` (inferred)
+- If skipped: add `reason` if provided
+- If blocked: add `blocked_by` (tag) and `reason` (if provided)
+
+**Summary:**
+- OVERWRITE counts after each response
+- Tracks: total, passed, issues, pending, skipped
+
+**Gaps:**
+- APPEND only when issue found (YAML format)
+- After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
+- This section feeds directly into /mindforge-plan-phase --gaps
+
+</section_rules>
+
+<diagnosis_lifecycle>
+
+**After testing complete (status: complete), if gaps exist:**
+
+1. User runs diagnosis (from verify-work offer or manually)
+2. diagnose-issues workflow spawns parallel debug agents
+3. Each agent investigates one gap, returns root cause
+4. UAT.md Gaps section updated with diagnosis:
+   - Each gap gets `root_cause`, `artifacts`, `missing`, `debug_session` filled
+5. status → "diagnosed"
+6. Ready for /mindforge-plan-phase --gaps with root causes
+
+**After diagnosis:**
+```yaml
+## Gaps
+
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+
+</diagnosis_lifecycle>
+
+<lifecycle>
+
+**Creation:** When /mindforge-verify-work starts new session
+- Extract tests from SUMMARY.md files
+- Set status to "testing"
+- Current Test points to test 1
+- All tests have result: [pending]
+
+**During testing:**
+- Present test from Current Test section
+- User responds with pass confirmation or issue description
+- Update test result (pass/issue/skipped)
+- Update Summary counts
+- If issue: append to Gaps section (YAML format), infer severity
+- Move Current Test to next pending test
+
+**On completion:**
+- status → "complete"
+- Current Test → "[testing complete]"
+- Commit file
+- Present summary with next steps
+
+**Partial completion:**
+- status → "partial" (if pending, blocked, or unresolved skipped tests remain)
+- Current Test → "[testing paused — {N} items outstanding]"
+- Commit file
+- Present summary with outstanding items highlighted
+
+**Resuming partial session:**
+- `/mindforge-verify-work {phase}` picks up from first pending/blocked test
+- When all items resolved, status advances to "complete"
+
+**Resume after /clear:**
+1. Read frontmatter → know phase and status
+2. Read Current Test → know where we are
+3. Find first [pending] result → continue from there
+4. Summary shows progress so far
+
+</lifecycle>
+
+<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, minor, small issue   | minor     |
+| Color, font, spacing, alignment, visual, looks off | cosmetic  |
+
+Default: **major** (safe default, user can clarify if wrong)
+
+</severity_guide>
+
+<good_example>
+```markdown
+---
+status: diagnosed
+phase: 04-comments
+source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
+started: 2025-01-15T10:30:00Z
+updated: 2025-01-15T10:45:00Z
+---
+
+## Current Test
+
+[testing complete]
+
+## Tests
+
+### 1. View Comments on Post
+expected: Comments section expands, shows count and comment list
+result: pass
+
+### 2. Create Top-Level Comment
+expected: Submit comment via rich text editor, appears in list with author info
+result: issue
+reported: "works but doesn't show until I refresh the page"
+severity: major
+
+### 3. Reply to a Comment
+expected: Click Reply, inline composer appears, submit shows nested reply
+result: pass
+
+### 4. Visual Nesting
+expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
+result: pass
+
+### 5. Delete Own Comment
+expected: Click delete on own comment, removed or shows [deleted] if has replies
+result: pass
+
+### 6. Comment Count
+expected: Post shows accurate count, increments when adding comment
+result: pass
+
+## Summary
+
+total: 6
+passed: 5
+issues: 1
+pending: 0
+skipped: 0
+
+## Gaps
+
+- truth: "Comment appears immediately after submission in list"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+  debug_session: ".planning/debug/comment-not-refreshing.md"
+```
+</good_example>