pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/tdd.md

@@ -0,0 +1,255 @@
+# TDD Workflow
+
+---
+
+## Iron Law
+
+**NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.**
+
+Write code before the test? Delete it. Start over.
+- Don't keep it as "reference"
+- Don't "adapt" it while writing tests
+- Delete means delete
+
+---
+
+## Red-Green-Refactor Cycle
+
+Every feature/behavior follows this mandatory sequence:
+
+```
+RED: Write failing test → verify it fails correctly
+GREEN: Write minimal code to pass → verify ALL tests pass
+REFACTOR: Clean up → verify tests still pass
+```
+
+Each cycle produces exactly 3 tasks in the plan. No steps may be skipped or merged.
+
+---
+
+## Red Flags — These Thoughts Mean STOP
+
+- "This is too simple to need TDD"
+- "I'll write tests after to verify"
+- "Let me explore the implementation first, then add tests"
+- "I'll keep the code as reference and write tests first"
+- "TDD will slow me down"
+- "I already manually tested this"
+- "Tests after achieve the same goals"
+
+All of these mean: **follow the cycle anyway**.
+
+---
+
+## Rationalization Table
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing — you never saw them catch the bug. |
+| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
+| "Already manually tested" | Ad-hoc != systematic. No record, can't re-run. |
+| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Need to explore first" | Fine. Throw away exploration, start fresh with TDD. |
+| "Test hard = design unclear" | Listen to the test. Hard to test = hard to use. Simplify the interface. |
+| "TDD will slow me down" | TDD is faster than debugging in production. |
+
+---
+
+## Task Chain Generation
+
+When `maestro-plan --tdd` is active, each behavior/feature decomposes into a TDD triplet:
+
+### Structure
+
+For each behavior B (derived from requirements or convergence criteria):
+
+```
+TASK-{N}a: RED — Write failing test for B
+TASK-{N}b: GREEN — Implement minimal code to pass B
+TASK-{N}c: REFACTOR — Clean up B implementation (optional, skip if nothing to clean)
+```
+
+### TASK-{N}a: RED — Write Failing Test
+
+```json
+{
+  "id": "TASK-{N}a",
+  "title": "RED: Write failing test for {behavior}",
+  "type": "test",
+  "action": "Write test that describes expected behavior. Test MUST fail before implementation exists.",
+  "implementation": [
+    "Identify the behavior to test from requirement",
+    "Write one minimal test — one behavior per test, clear name",
+    "Use real code, not mocks (unless external dependency)",
+    "Run test: verify it FAILS (not errors) with expected failure message",
+    "If test passes: wrong test — testing existing behavior, fix test",
+    "If test errors: fix error, re-run until it fails correctly"
+  ],
+  "convergence": {
+    "criteria": [
+      "Test file exists at {test_path}",
+      "Test run exits non-zero (test fails, not errors)",
+      "Failure message matches expected behavior gap"
+    ],
+    "verification": "Run test command, confirm RED status (failure, not error)"
+  },
+  "meta": {
+    "tdd_phase": "red",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+### TASK-{N}b: GREEN — Write Minimal Code
+
+```json
+{
+  "id": "TASK-{N}b",
+  "title": "GREEN: Implement minimal code for {behavior}",
+  "type": "feature",
+  "depends_on": ["TASK-{N}a"],
+  "action": "Write the simplest code that makes the failing test pass. No features beyond what the test requires.",
+  "implementation": [
+    "Read the failing test to understand exactly what is needed",
+    "Write minimal production code — just enough to pass",
+    "Do NOT add features, refactor other code, or improve beyond the test",
+    "Do NOT add options, configurability, or flexibility not required by test",
+    "Run test: verify it PASSES",
+    "Run full test suite: verify no regressions (all other tests still pass)",
+    "If test fails: fix code, NOT test",
+    "If other tests fail: fix now"
+  ],
+  "convergence": {
+    "criteria": [
+      "Test from TASK-{N}a passes (exit 0)",
+      "Full test suite passes (no regressions)",
+      "No warnings or errors in test output"
+    ],
+    "verification": "Run test command, confirm GREEN status (all pass, clean output)"
+  },
+  "meta": {
+    "tdd_phase": "green",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+### TASK-{N}c: REFACTOR — Clean Up
+
+```json
+{
+  "id": "TASK-{N}c",
+  "title": "REFACTOR: Clean up {behavior} implementation",
+  "type": "refactor",
+  "depends_on": ["TASK-{N}b"],
+  "action": "Remove duplication, improve names, extract helpers. Keep tests green. Do NOT add behavior.",
+  "implementation": [
+    "Review code from TASK-{N}b for duplication, naming, structure",
+    "Apply refactoring while keeping ALL tests green",
+    "Remove duplication across the new and existing code",
+    "Improve variable and function names for clarity",
+    "Extract helpers only if reuse is immediate (not speculative)",
+    "Run full test suite after each refactoring step",
+    "If any test fails during refactoring: undo last change, re-run"
+  ],
+  "convergence": {
+    "criteria": [
+      "Full test suite passes (same as GREEN, no regressions)",
+      "No new behavior added beyond what tests cover"
+    ],
+    "verification": "Run full test suite, confirm still GREEN"
+  },
+  "meta": {
+    "tdd_phase": "refactor",
+    "tdd_group": "{N}"
+  }
+}
+```
+
+---
+
+## Wave Assignment
+
+TDD triplets are sequential within each group but groups can parallelize if independent:
+
+```
+Wave 1: TASK-1a (RED for feature A),  TASK-2a (RED for feature B)    — parallel if independent
+Wave 2: TASK-1b (GREEN for feature A), TASK-2b (GREEN for feature B)  — parallel
+Wave 3: TASK-1c (REFACTOR for A),     TASK-2c (REFACTOR for B)       — parallel
+```
+
+Within a group, the dependency chain is always: `{N}a → {N}b → {N}c`.
+
+---
+
+## Integration with plan.json
+
+When `--tdd` is active, the plan.json output includes:
+
+```json
+{
+  "tdd_mode": true,
+  "tdd_groups": [
+    {
+      "group": 1,
+      "behavior": "User can login with email and password",
+      "tasks": ["TASK-1a", "TASK-1b", "TASK-1c"]
+    }
+  ]
+}
+```
+
+The standard `plan.json.waves[]` and `.task/TASK-*.json` structure is preserved — `maestro-execute` consumes it without modification.
+
+---
+
+## Execution Enforcement
+
+When `maestro-execute` processes a TDD plan (detected by `plan.json.tdd_mode == true`):
+
+### RED task verification
+- After TASK-{N}a completes, verify test exists AND fails
+- If test passes: mark task BLOCKED with reason "Test passes before implementation — wrong test"
+
+### GREEN task verification
+- After TASK-{N}b completes, verify ALL tests pass
+- If the RED test still fails: mark task BLOCKED, provide failure output
+- If other tests regress: mark task BLOCKED, list regressed tests
+
+### REFACTOR task verification
+- After TASK-{N}c completes, verify ALL tests still pass
+- If any test fails: undo changes, mark as needing re-attempt
+
+---
+
+## Good Tests
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | One thing per test. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
+| **Clear** | Name describes behavior | `test('test1')`, `test('it works')` |
+| **Shows intent** | Demonstrates desired API | Obscures what code should do |
+| **Real code** | Uses actual implementations | Mocks everything, tests mock behavior |
+
+---
+
+## When to Skip REFACTOR
+
+TASK-{N}c (REFACTOR) may be omitted from the plan when:
+- GREEN code is already clean (no duplication, good names)
+- The change is truly trivial (single-line fix)
+
+When skipped, mark in plan.json: `"refactor_skipped": true, "reason": "GREEN code already clean"`
+
+---
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No test framework detected | Abort: "No test infrastructure found. Set up testing first." |
+| RED test passes immediately | BLOCKED: "Test passes before implementation — rewrite test" |
+| GREEN test still fails after implementation | Retry once with more context, then BLOCKED |
+| REFACTOR breaks tests | Undo refactoring, mark as BLOCKED |
+| Cannot write meaningful test | AskUserQuestion: "Behavior '{B}' is hard to test. Should we: (1) simplify the interface, (2) skip TDD for this behavior, (3) use integration test instead?" |

package/workflows/test-gen.md

@@ -0,0 +1,226 @@
+# Test Generation Workflow
+
+Generate missing automated tests for a phase based on gap analysis from maestro-execute verification gate (Nyquist audit) and quality-test (UAT coverage gaps). Classifies changed files into unit/E2E/skip, discovers test infrastructure, generates a test plan for user approval, then writes tests using RED-GREEN methodology.
+
+Tests expose bugs -- fixing is for quality-debug or maestro-execute.
+
+---
+
+### Step 0: Load Project Specs
+
+```
+specs_content = maestro spec load --category test
+```
+
+Apply project test conventions (from Step 0 specs) when generating the plan (Step 4) and writing tests (Step 5); REQUIRED: tests conform to loaded spec conventions.
+
+---
+
+### Step 1: Discover Test Infrastructure
+
+Detect existing test framework and patterns by scanning for:
+- **Config files**: `jest.config.*`, `vitest.config.*`, `pytest.ini`, `pyproject.toml`, `.mocharc.*`
+- **Existing tests**: `*.test.*`, `*.spec.*`, `test_*` (exclude node_modules, .git)
+- **Utilities**: `test-utils.*`, `testHelper*`, `conftest.py`, `setup.*`
+
+Extract: framework, directory structure, naming convention, test utilities, run command.
+
+Read 2-3 existing test files to learn: import style, describe/it nesting, assertion library, mock patterns, setup/teardown.
+
+If no test framework detected: Error E003.
+
+---
+
+### Step 2: Identify Gaps
+
+Sources: validation.json (`gaps[]` MISSING/PARTIAL), coverage-report.json (`requirements_uncovered[]`), task summaries (modified files).
+
+Priority: MISSING or uncovered requirement → HIGH; PARTIAL → MEDIUM.
+
+---
+
+### Step 3: Classify Files
+
+Classify each changed file into test categories:
+
+| File Type | Category | Rationale |
+|-----------|----------|-----------|
+| Pure function / utility | unit | Isolated, no side effects |
+| React component | unit + e2e | Unit for logic, E2E for rendering |
+| API route / handler | integration | Needs request context |
+| Database model / query | integration | Needs DB connection |
+| CLI command | e2e | Needs process execution |
+| Config / types / constants / CSS / test files | skip | No testable behavior |
+
+Output: `{ "unit": [...], "integration": [...], "e2e": [...], "skip": [...] }`
+
+Apply --layer filter if set.
+
+---
+
+### Step 3.5: CLI Supplementary Test Analysis (optional)
+
+**Purpose:** Use external CLI tool to analyze source code and suggest edge cases and boundary conditions that manual classification may miss.
+
+**Skip if** no enabled CLI tools or classified files are all "skip".
+
+```
+IF no CLI tools enabled OR all files classified as "skip": skip to Step 4
+
+# Build file list for analysis
+target_files = unit + integration + e2e files, map to paths
+
+Bash({
+  command: 'maestro delegate "PURPOSE: Analyze source files to identify test-worthy edge cases and boundary conditions
+TASK: For each file, identify: error handling paths | boundary conditions | state transitions | external dependency interactions
+MODE: analysis
+CONTEXT: @${target_files as glob}
+EXPECTED: JSON array of { file, edge_cases: [{ description, type: boundary|error|state|integration, priority: high|medium }] }
+CONSTRAINTS: Only report non-obvious cases | Max 5 edge cases per file | Focus on untested paths
+" --role analyze --mode analysis',
+  run_in_background: true
+})
+```
+
+**On callback:** Parse result, merge edge_cases into Step 4 test_cases for matching files. Mark CLI-suggested cases with `source: "cli-analysis"`.
+
+---
+
+### Step 4: Generate Test Plan
+
+For each gap + classified file, create a test entry:
+
+```json
+{
+  "tests": [
+    {
+      "id": "TG-001",
+      "target_file": "src/utils/validate.ts",
+      "test_file": "src/utils/__tests__/validate.test.ts",
+      "layer": "unit",
+      "requirement_ref": "SC-002",
+      "description": "Validate email format accepts valid emails, rejects invalid",
+      "test_cases": [
+        "accepts standard email format",
+        "rejects missing @ symbol",
+        "rejects empty string",
+        "handles unicode characters"
+      ],
+      "priority": "high"
+    }
+  ]
+}
+```
+
+Present plan to user:
+
+```
+=== TEST GENERATION PLAN ===
+Phase: {phase_name}
+
+| # | Target | Layer | Test Cases | Priority |
+|---|--------|-------|------------|----------|
+| TG-001 | validate.ts | unit | 4 cases | HIGH |
+| TG-002 | ChatWindow.tsx | e2e | 3 cases | HIGH |
+| TG-003 | comments.ts | integration | 5 cases | MEDIUM |
+
+Total: {N} test files, {M} test cases
+
+Proceed? (yes/modify/cancel)
+```
+
+Wait for user approval via AskUserQuestion.
+- "yes" / "y" -> proceed to Step 5
+- "modify" -> ask what to change, update plan
+- "cancel" -> abort
+
+---
+
+### Step 5: Generate Tests (RED-GREEN)
+
+For each approved test entry:
+
+1. **RED** -- Write test following existing patterns; tests must fail if behavior is broken (not trivially pass)
+2. **Verify RED** -- Run `{test_run_command} {test_file}`:
+   - Passes → may be trivial, strengthen it
+   - Fails expected → good, targets real behavior
+   - Fails unexpected → fix test setup, not source code
+3. **GREEN assessment** -- Passes = gap was missing test; Fails = bug discovery (do NOT fix source)
+
+**Important**: This command generates tests only. Failing tests document missing behavior -- fixing is for quality-debug.
+
+Write each test file to the discovered test directory structure.
+
+---
+
+### Step 6: Run Full Test Suite
+
+Verify no regressions.
+
+```bash
+{test_run_command} 2>&1 | tail -50
+```
+
+Categorize results:
+- New tests passing: coverage gap filled
+- New tests failing: bug discovered (document, don't fix)
+- Existing tests broken: regression introduced (investigate)
+
+If regressions found, flag as blocker. (W002)
+
+---
+
+### Step 7: Write Artifacts
+
+Archive existing `.tests/test-gen-report.json` → `.history/test-gen-report-{timestamp}.json` if present.
+
+Write `.tests/test-gen-report.json`:
+```json
+{
+  "phase": "{phase}",
+  "generated_at": "{ISO timestamp}",
+  "infrastructure": {
+    "framework": "vitest",
+    "test_dir": "__tests__/",
+    "run_command": "npm test"
+  },
+  "classification": { "unit": [...], "integration": [...], "e2e": [...], "skip": [...] },
+  "generated": [
+    {
+      "id": "TG-001",
+      "test_file": "src/utils/__tests__/validate.test.ts",
+      "layer": "unit",
+      "test_cases": 4,
+      "status": "passing|failing|mixed",
+      "bugs_discovered": []
+    }
+  ],
+  "summary": {
+    "files_generated": N,
+    "test_cases_total": M,
+    "passing": P,
+    "failing": F,
+    "bugs_discovered": B
+  }
+}
+```
+
+Update validation.json gaps: change MISSING -> COVERED for gaps that now have tests.
+
+---
+
+### Step 8: Report
+
+```
+Display: phase, framework, files/cases generated, passing/failing counts,
+  bugs found (with descriptions), coverage delta, report path, next step suggestion
+```
+
+**Next step routing:**
+
+| Result | Suggestion |
+|--------|------------|
+| All tests passing | Skill({ skill: "quality-review", args: "{phase}" }) to update Nyquist coverage |
+| Bugs discovered (failing tests) | Skill({ skill: "quality-debug", args: "--from-uat {phase}" }) to investigate |
+| Regressions found | Skill({ skill: "quality-debug" }) immediately |
+| Coverage still low | Run again with `--layer` for uncovered layers |