@thierrynakoa/fire-flow 10.0.0

package/references/testing-enforcement.md

@@ -0,0 +1,192 @@
+# Dominion Flow Testing Enforcement Reference
+
+> **Origin:** NEW for Dominion Flow v2.0 - Mandatory testing requirements.
+
+## Overview
+
+Dominion Flow enforces testing as a first-class requirement, not an afterthought. Every plan that creates or modifies application code must include test verification. This reference defines what testing is required, when, and how it integrates with the execution pipeline.
+
+---
+
+## Testing Requirements by Plan Type
+
+| Plan Type | Unit Tests | Integration Tests | E2E Tests | Build Check |
+|-----------|-----------|------------------|-----------|-------------|
+| API endpoint | Required | Required | Optional | Required |
+| UI component | Required | Optional | Recommended | Required |
+| Database schema | Optional | Required | Optional | Required |
+| Utility/helper | Required | Optional | Optional | Required |
+| Configuration | Optional | Optional | Optional | Required |
+| Documentation | Not needed | Not needed | Not needed | Not needed |
+
+---
+
+## Test Enforcement Points
+
+### 1. During Planning (`/fire-2-plan`)
+
+Every plan's `<verification>` section MUST include:
+
+```xml
+<verification>
+### Test Requirements
+- [ ] [Specific test command] (e.g., npm test -- --testPathPattern=auth)
+- [ ] Build passes: npm run build
+- [ ] No new lint warnings: npm run lint
+
+### WARRIOR Quality Gates
+- [ ] Code builds without errors
+- [ ] Tests pass (existing + new)
+- [ ] No regressions in existing tests
+</verification>
+```
+
+Plans without test requirements are flagged during plan review.
+
+### 2. During Execution (`/fire-execute-plan`)
+
+After each segment completes:
+
+```bash
+# Auto-detect and run test suite
+npm test 2>/dev/null || yarn test 2>/dev/null || pytest 2>/dev/null || go test ./... 2>/dev/null
+```
+
+**If tests pass:** Continue to next segment.
+
+**If tests fail:**
+- Attempt auto-fix (deviation Rule 1)
+- If still failing after 2 attempts, create P1 blocker
+- Present options: Fix / Skip (tracked) / Stop
+
+### 3. During Verification (`/fire-4-verify`)
+
+Verification agent checks:
+- [ ] All planned tests exist and pass
+- [ ] No test files are stubs or placeholders
+- [ ] Test assertions are meaningful (not `expect(true).toBe(true)`)
+- [ ] Critical flows have test coverage
+- [ ] No skipped tests without justification
+
+### 4. During Phase Transition (`/fire-transition`)
+
+Phase metrics include:
+- Tests added this phase
+- Test coverage delta
+- Test pass rate
+- Regression count
+
+---
+
+## Test Quality Standards
+
+### Meaningful Assertions
+
+```javascript
+// BAD - Tests nothing
+expect(true).toBe(true);
+expect(1).toBe(1);
+
+// BAD - Only checks existence
+expect(result).toBeDefined();
+
+// GOOD - Tests behavior
+expect(result.status).toBe(201);
+expect(result.body.user.email).toBe('test@example.com');
+expect(result.body.token).toMatch(/^eyJ/);
+
+// GOOD - Tests error handling
+await expect(login({ email: '' })).rejects.toThrow('Email required');
+```
+
+### Test Structure
+
+```javascript
+describe('POST /api/auth/register', () => {
+  it('creates user with valid credentials', async () => {
+    // Happy path - REQUIRED
+  });
+
+  it('rejects duplicate email', async () => {
+    // Error path - REQUIRED for critical flows
+  });
+
+  it('rejects weak password', async () => {
+    // Validation - REQUIRED for user input
+  });
+});
+```
+
+### Coverage Expectations
+
+| Flow Type | Minimum Coverage |
+|-----------|-----------------|
+| Authentication | Happy + 2 error paths |
+| Payment | Happy + all error paths |
+| Data mutation | Happy + validation + auth check |
+| Read-only API | Happy + not-found + auth check |
+| UI component | Renders + key interactions |
+
+---
+
+## TDD Integration
+
+When `plan.type === "tdd"` in frontmatter:
+
+1. **RED:** Write failing test first, commit: `test({phase}-{plan}): add failing test for [feature]`
+2. **GREEN:** Implement to pass, commit: `feat({phase}-{plan}): implement [feature]`
+3. **REFACTOR:** Clean up if needed, commit: `refactor({phase}-{plan}): clean up [feature]`
+
+TDD plans produce 2-3 atomic commits per feature. See `references/tdd.md` for full TDD reference.
+
+---
+
+## Framework Setup
+
+When no test framework exists in the project:
+
+| Stack | Framework | Setup Command |
+|-------|-----------|---------------|
+| 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 |
+| E2E | Playwright | `npm install -D @playwright/test` |
+
+Framework setup is included in the first plan's execution as an auto task.
+
+---
+
+## Anti-Patterns
+
+- **No tests:** Plan creates code without any test verification
+- **Stub tests:** Tests exist but assert nothing meaningful
+- **Only happy path:** Missing error/edge case coverage
+- **Test after:** Writing all code first, then adding tests as afterthought
+- **Skipping without reason:** Using `.skip()` without documented justification
+- **Testing implementation:** Mocking internals instead of testing behavior
+- **Ignoring failures:** Marking failing tests as "known issue" without blocker
+
+---
+
+## Enforcement Levels
+
+Configurable in `.planning/config.json`:
+
+```json
+{
+  "testing": {
+    "enforcement": "strict",
+    "min_assertions_per_test": 1,
+    "require_error_paths": true,
+    "allow_skip_with_reason": true,
+    "auto_detect_framework": true
+  }
+}
+```
+
+| Level | Behavior |
+|-------|----------|
+| `strict` | Tests required for all code changes, block on failure |
+| `standard` | Tests required for API/logic, warn on missing UI tests |
+| `relaxed` | Tests recommended, never block |

package/references/ui-brand.md

@@ -0,0 +1,383 @@
+# Dominion Flow UI Brand Guide
+
+> Visual patterns for consistent, recognizable user-facing output
+
+---
+
+## Stage Banners
+
+Use stage banners to mark major workflow phases. Always use the Dominion Flow prefix for brand recognition.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+                         DOMINION FLOW > DISCOVERY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Standard Stage Names
+
+| Stage | Usage |
+|-------|-------|
+| `DOMINION FLOW > DISCOVERY` | Gathering requirements, exploring codebase |
+| `DOMINION FLOW > PLANNING` | Creating execution plans |
+| `DOMINION FLOW > EXECUTION` | Implementing changes |
+| `DOMINION FLOW > VERIFICATION` | Testing and validation |
+| `DOMINION FLOW > CHECKPOINT` | Mid-execution review points |
+| `DOMINION FLOW > COMPLETE` | Task finished successfully |
+
+### Compact Banner (for sub-stages)
+
+```
+━━━ DOMINION FLOW > BREATH 1 EXECUTION ━━━
+```
+
+---
+
+## Checkpoint Boxes
+
+Use checkpoint boxes for critical decision points and status summaries.
+
+### Standard Checkpoint
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                              CHECKPOINT                                       ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  ✓ Database schema created                                                   ║
+║  ✓ API routes implemented                                                    ║
+║  ○ Frontend components pending                                               ║
+║  ○ Tests not started                                                         ║
+║                                                                              ║
+║  Progress: ████████░░░░░░░░ 50%                                             ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+### Decision Checkpoint
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                         DECISION REQUIRED                                     ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  Issue: API response format inconsistent with frontend expectations          ║
+║                                                                              ║
+║  Options:                                                                    ║
+║    A) Modify API to match frontend schema                                   ║
+║    B) Update frontend to handle current API format                          ║
+║    C) Create adapter layer                                                   ║
+║                                                                              ║
+║  Recommendation: Option A (lower complexity, single change point)           ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Status Symbols
+
+### Primary Symbols
+
+| Symbol | Meaning | Usage |
+|--------|---------|-------|
+| `✓` | Complete/Success | Task finished, test passed |
+| `✗` | Failed/Error | Task failed, test failed |
+| `◆` | In Progress | Currently executing |
+| `○` | Pending | Not yet started |
+| `⚡` | Active/Running | Live process, spawned agent |
+| `⚠` | Warning | Non-blocking issue |
+| `🎉` | Celebration | Major milestone achieved |
+
+### Secondary Symbols
+
+| Symbol | Meaning | Usage |
+|--------|---------|-------|
+| `→` | Flow/Next | Indicates next step |
+| `↳` | Sub-item | Nested task or detail |
+| `│` | Vertical line | Tree structure |
+| `├` | Branch | Tree branching |
+| `└` | Last branch | Final item in tree |
+
+### Usage Examples
+
+```
+✓ Build successful
+✗ Test failed: authentication.spec.ts
+◆ Running database migrations...
+○ Deploy to staging (pending)
+⚡ Agent spawned: code-review
+⚠ Warning: No tests for new endpoint
+🎉 Phase 3 Complete!
+```
+
+---
+
+## Progress Display
+
+### Standard Progress Bar
+
+```
+Progress: ████████████░░░░░░░░ 60%
+```
+
+### Detailed Progress
+
+```
+Overall: ████████████████░░░░ 80%
+├─ Backend:   ████████████████████ 100%
+├─ Frontend:  ████████████░░░░░░░░ 60%
+└─ Tests:     ████████░░░░░░░░░░░░ 40%
+```
+
+### Progress with Context
+
+```
+Breath 2 of 4: ██████████░░░░░░░░░░ 50%
+  Tasks: 3/6 complete
+  Time: ~15 min remaining
+```
+
+---
+
+## Spawning Indicators
+
+Use when launching parallel agents or sub-processes.
+
+### Agent Spawn
+
+```
+◆ Spawning agents for Breath 2...
+  ⚡ Agent 1: Backend API implementation
+  ⚡ Agent 2: Database schema updates
+  ⚡ Agent 3: Test scaffolding
+```
+
+### Single Spawn
+
+```
+◆ Spawning code-review agent...
+```
+
+### Spawn Complete
+
+```
+✓ All agents spawned (3 active)
+  ├─ ⚡ Agent 1: Running (backend)
+  ├─ ⚡ Agent 2: Running (database)
+  └─ ⚡ Agent 3: Running (tests)
+```
+
+---
+
+## Next Up Blocks
+
+Use to show upcoming work and maintain momentum.
+
+### Simple Next Up
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ NEXT UP                                                                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  → Implement user authentication endpoint                                   │
+│  → Add input validation middleware                                          │
+│  → Create integration tests                                                 │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Detailed Next Up
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ NEXT UP: Breath 3                                                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  Priority Tasks:                                                            │
+│    1. [HIGH] Fix authentication token refresh                               │
+│    2. [MED]  Add error boundary to dashboard                                │
+│    3. [LOW]  Update loading spinners                                        │
+│                                                                             │
+│  Blocked:                                                                   │
+│    - Payment integration (waiting on API keys)                              │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Error Boxes
+
+Use for critical errors that need immediate attention.
+
+### Standard Error
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ ✗ ERROR                                                                      ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  Build failed: TypeScript compilation error                                  ║
+║                                                                              ║
+║  Location: src/services/auth.service.ts:47                                  ║
+║  Message: Property 'token' does not exist on type 'User'                    ║
+║                                                                              ║
+║  Action: Fix type definition before proceeding                              ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+### Warning Box
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ ⚠ WARNING                                                                   │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  No tests found for: src/components/Dashboard.tsx                           │
+│                                                                             │
+│  Recommendation: Add unit tests before merge                                │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Success/Completion Boxes
+
+### Phase Complete
+
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ 🎉 PHASE COMPLETE                                                            ║
+╠══════════════════════════════════════════════════════════════════════════════╣
+║                                                                              ║
+║  Phase 2: Backend API Implementation                                         ║
+║                                                                              ║
+║  Achievements:                                                               ║
+║    ✓ 12 API endpoints created                                               ║
+║    ✓ Authentication middleware added                                         ║
+║    ✓ 94% test coverage                                                       ║
+║    ✓ Documentation generated                                                 ║
+║                                                                              ║
+║  Time: 2h 15m | Breaths: 4 | Agents Used: 8                                   ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Anti-Patterns (Avoid These)
+
+### DON'T: Inconsistent symbols
+
+```
+❌ Bad:
+[x] Task complete
+[DONE] Another task
+* Third task done
+```
+
+```
+✓ Good:
+✓ Task complete
+✓ Another task
+✓ Third task done
+```
+
+### DON'T: Missing Dominion Flow branding
+
+```
+❌ Bad:
+=== STARTING PHASE 2 ===
+```
+
+```
+✓ Good:
+━━━ DOMINION FLOW > PHASE 2 EXECUTION ━━━
+```
+
+### DON'T: Plain text errors
+
+```
+❌ Bad:
+Error: Build failed
+```
+
+```
+✓ Good:
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ ✗ ERROR: Build failed                                                        ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+### DON'T: Unclear progress
+
+```
+❌ Bad:
+Working on it...
+Almost done...
+```
+
+```
+✓ Good:
+Progress: ████████████░░░░░░░░ 60%
+  ├─ ✓ Schema created
+  ├─ ◆ Migrations running
+  └─ ○ Seeding pending
+```
+
+### DON'T: Emoji overload
+
+```
+❌ Bad:
+🚀 Starting! 💪 Let's go! 🎯 Targeting API! 🔥 Hot fixes!
+```
+
+```
+✓ Good:
+━━━ DOMINION FLOW > EXECUTION ━━━
+◆ Implementing API endpoints...
+```
+
+### DON'T: Inconsistent box styles
+
+```
+❌ Bad:
++------------------+
+| Some content     |
++------------------+
+
+[Another Box]
+| Different style |
+```
+
+```
+✓ Good:
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ Standard content box                                                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+╔══════════════════════════════════════════════════════════════════════════════╗
+║ Important/checkpoint box                                                     ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Quick Reference
+
+| Element | Character Set |
+|---------|--------------|
+| Stage banners | `━` (heavy horizontal) |
+| Checkpoint boxes | `╔ ╗ ╚ ╝ ║ ═ ╠ ╣` (double line) |
+| Standard boxes | `┌ ┐ └ ┘ │ ─ ├ ┤` (single line) |
+| Progress fill | `█` (full block) |
+| Progress empty | `░` (light shade) |
+| Tree structure | `│ ├ └ ─` |
+
+---
+
+*Consistent branding builds trust and recognition. Every Dominion Flow output should be immediately identifiable.*