maestro-flow 0.3.14 → 0.3.16

package/workflows/test-gen.md

@@ -18,32 +18,14 @@ Follow project test conventions in Step 4 (Generate Test Plan) and Step 5 (Write
 
 ### Step 1: Discover Test Infrastructure
 
-Detect existing test framework and patterns.
+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.*`
 
-```bash
-# Find test config files
-find . -name "jest.config.*" -o -name "vitest.config.*" -o -name "pytest.ini" -o -name "pyproject.toml" -o -name ".mocharc.*" 2>/dev/null | head -10
-
-# Find existing test files
-find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -40
-
-# Find test utilities and helpers
-find . \( -name "test-utils.*" -o -name "testHelper*" -o -name "conftest.py" -o -name "setup.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -10
-```
-
-Extract:
-- **Framework**: Jest, Vitest, pytest, Mocha, etc.
-- **Test directory structure**: `__tests__/`, `tests/`, co-located, etc.
-- **Naming convention**: `*.test.ts`, `*.spec.ts`, `test_*.py`
-- **Test utilities**: shared helpers, fixtures, factories
-- **Run command**: `npm test`, `pytest`, etc.
+Extract: framework, directory structure, naming convention, test utilities, run command.
 
-Read 2-3 existing test files to learn patterns:
-- Import style
-- Describe/it nesting
-- Assertion library
-- Mock/stub patterns
-- Setup/teardown conventions
+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.
 
@@ -51,52 +33,26 @@ If no test framework detected: Error E003.
 
 ### Step 2: Identify Gaps
 
-Identify what needs tests from verification artifacts:
-
-1. **From validation.json** (Nyquist audit):
-   - `gaps[]` where status = "MISSING" or "PARTIAL"
-   - Each gap has requirement_ref and description
+Sources: validation.json (`gaps[]` MISSING/PARTIAL), coverage-report.json (`requirements_uncovered[]`), task summaries (modified files).
 
-2. **From coverage-report.json** (UAT):
-   - `requirements_uncovered[]` -- requirements without test evidence
-
-3. **From task summaries**:
-   - Files modified/created in this phase
-   - Functionality added
-
-Build gap list with priority:
-- MISSING (no test at all) -> HIGH priority
-- Uncovered requirement -> HIGH priority
-- PARTIAL (test exists but incomplete) -> MEDIUM priority
+Priority: MISSING or uncovered requirement → HIGH; PARTIAL → MEDIUM.
 
 ---
 
 ### Step 3: Classify Files
 
-Classify changed files into test categories.
-
-For each file modified in this phase:
+Classify each changed file into test categories:
 
-| File Type | Test Category | Rationale |
-|-----------|---------------|-----------|
+| 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 | skip | No behavior to test |
-| CSS / styles | skip | Visual, not testable with code |
-| Test files themselves | skip | Don't test tests |
+| Config / types / constants / CSS / test files | skip | No testable behavior |
 
-Output classification:
-```json
-{
-  "unit": ["src/utils/validate.ts", "src/hooks/useChat.ts"],
-  "integration": ["src/api/comments.ts", "src/db/queries.ts"],
-  "e2e": ["src/components/ChatWindow.tsx"],
-  "skip": ["src/types/index.ts", "src/styles/theme.css"]
-}
-```
+Output: `{ "unit": [...], "integration": [...], "e2e": [...], "skip": [...] }`
 
 Apply --layer filter if set.
 
@@ -156,25 +112,14 @@ Wait for user approval via AskUserQuestion.
 
 For each approved test entry:
 
-1. **RED phase** -- Write the test first:
-   - Follow existing test patterns (imports, describe/it, assertions)
-   - Write test cases that verify the expected behavior
-   - Tests should FAIL if the behavior is broken (not trivially pass)
-
-2. **Verify RED** -- Run the test:
-   ```bash
-   {test_run_command} {test_file} 2>&1 | tail -20
-   ```
-   - If test passes: the test may be trivial, review and strengthen
-   - If test fails with expected error: good, test targets real behavior
-   - If test fails with unexpected error: fix test setup, not source code
+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)
 
-3. **GREEN assessment** -- Check if source already satisfies:
-   - If tests pass: coverage gap was about missing tests, not missing code
-   - If tests fail: record as bug discovery (NOT fix -- that's for quality-debug)
-
-**Important**: This command generates tests, it does NOT fix source code.
-Failing tests are valuable -- they document missing behavior.
+**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.
 
@@ -199,13 +144,7 @@ If regressions found, flag as blocker. (W002)
 
 ### Step 7: Write Artifacts
 
-**Archive previous test-gen artifacts** before writing:
-```
-IF file exists "$OUTPUT_DIR/.tests/test-gen-report.json":
-  mkdir -p "$OUTPUT_DIR/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  mv "$OUTPUT_DIR/.tests/test-gen-report.json" "$OUTPUT_DIR/.history/test-gen-report-${TIMESTAMP}.json"
-```
+Archive existing `.tests/test-gen-report.json` → `.history/test-gen-report-{timestamp}.json` if present.
 
 Write `.tests/test-gen-report.json`:
 ```json
@@ -245,24 +184,8 @@ Update validation.json gaps: change MISSING -> COVERED for gaps that now have te
 ### Step 8: Report
 
 ```
-=== TEST GENERATION RESULTS ===
-Phase:       {phase_name}
-Framework:   {framework}
-
-Generated:   {files_generated} test files, {test_cases_total} test cases
-  Passing:   {passing} (coverage gaps filled)
-  Failing:   {failing} (bugs discovered)
-
-Bugs Found:  {bugs_discovered}
-  {list of failing tests with brief description}
-
-Coverage:    {old_pct}% -> {new_pct}% (if measurable)
-
-Files:
-  {target_dir}/.tests/test-gen-report.json
-
-Next steps:
-  {suggested_next_command}
+Display: phase, framework, files/cases generated, passing/failing counts,
+  bugs found (with descriptions), coverage delta, report path, next step suggestion
 ```
 
 **Next step routing:**

package/workflows/test.md

@@ -22,16 +22,7 @@ Determine test target from $ARGUMENTS:
 
 **If phase number provided** (e.g., "3"):
 - Set `$TARGET_TYPE = "phase"`
-- Resolve phase dir:
-  ```
-  Read .workflow/state.json → state
-  artifacts = state.artifacts ?? []
-  art = artifacts.find(a => a.type === 'execute' && a.phase === phaseNum)
-  IF art:
-    PHASE_DIR = ".workflow/" + art.path
-  ELSE:
-    ERROR "Phase {phaseNum} not found in artifact registry"
-  ```
+- Resolve phase dir: look up `phaseNum` in `.workflow/state.json` artifacts (type=execute), derive `PHASE_DIR = ".workflow/" + art.path`. Error if not found.
 - Load `$PHASE_DIR/index.json` for context
 
 **If scratch task ID provided:**
@@ -157,14 +148,7 @@ Skip internal/non-observable items (refactors, type changes).
 
 ### Step 6: Create UAT File
 
-**Archive previous UAT artifacts** before writing:
-```
-ARCHIVE_TARGETS = ["uat.md"]
-IF file exists "$OUTPUT_DIR/uat.md":
-  mkdir -p "$OUTPUT_DIR/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  mv "$OUTPUT_DIR/uat.md" "$OUTPUT_DIR/.history/uat-${TIMESTAMP}.md"
-```
+**Archive previous UAT artifacts** before writing: if `$OUTPUT_DIR/uat.md` exists, move it to `$OUTPUT_DIR/.history/uat-{YYYY-MM-DDTHH-mm-ss}.md`.
 
 Build test list from test-plan.json. Create file at `$OUTPUT_DIR/uat.md`:
 
@@ -275,43 +259,11 @@ Append to Gaps section:
 ```
 
 **Auto-create Issue from UAT Gap:**
-```
-IF result == "issue":
-  mkdir -p ".workflow/issues"
-  existing_ids = []
-  IF file exists ".workflow/issues/issues.jsonl":
-    Read .workflow/issues/issues.jsonl
-    Extract all id fields matching today's date prefix ISS-YYYYMMDD-*
-    existing_ids = collected IDs
-
-  today = format(now(), "YYYYMMDD")
-  counter = max sequence number from existing_ids for today + 1 (start at 1 if none)
-
-  issue_id = "ISS-{today}-{counter padded to 3 digits}"
-  issue = {
-    id: issue_id,
-    title: "UAT: " + test.name + " - " + user_response (truncated to 100 chars),
-    status: "registered",
-    priority: severity_to_priority(inferred_severity),
-    severity: inferred_severity,
-    source: "uat",
-    phase_ref: TARGET_TYPE == "phase" ? PHASE_NUM : null,
-    gap_ref: test.id,
-    description: "UAT test failed: " + test.name + ". Expected: " + test.expected + ". Reported: " + user_response,
-    fix_direction: "",
-    context: { location: "", suggested_fix: "", notes: "requirement_ref: " + test.requirement_ref },
-    tags: ["uat"],
-    affected_components: [],
-    feedback: [],
-    issue_history: [],
-    created_at: now(),
-    updated_at: now(),
-    resolved_at: null,
-    resolution: null
-  }
-  Append JSON line to .workflow/issues/issues.jsonl
-  gap.issue_id = issue_id   // back-reference in gap YAML entry
-```
+
+When result is "issue", create an issue in `.workflow/issues/issues.jsonl`:
+- **ID**: `ISS-{YYYYMMDD}-{NNN}` (auto-increment per day from existing entries)
+- **Fields**: `id`, `title` ("UAT: {test.name} - {response}" truncated 100 chars), `status: "registered"`, `priority` (from severity), `severity`, `source: "uat"`, `phase_ref` (if phase-scoped), `gap_ref: test.id`, `description` (expected vs reported), `fix_direction: ""`, `context` (with requirement_ref), `tags: ["uat"]`, `affected_components: []`, `feedback: []`, `issue_history: []`, timestamps, `resolved_at: null`, `resolution: null`
+- Back-reference: set `gap.issue_id = issue_id` in the gap YAML entry
 
 **Batched writes for efficiency:**
 Keep results in memory. Write to file only when:
@@ -339,22 +291,7 @@ Proceed to Step 7.
 
 Update uat.md frontmatter: status -> "complete", updated timestamp.
 
-**Archive previous test result artifacts** before writing:
-```
-RESULT_TARGETS = ["test-results.json", "coverage-report.json"]
-has_existing = false
-FOR artifact IN RESULT_TARGETS:
-  IF file exists "$OUTPUT_DIR/.tests/${artifact}":
-    has_existing = true
-    break
-
-IF has_existing:
-  mkdir -p "$OUTPUT_DIR/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  FOR artifact IN RESULT_TARGETS:
-    IF file exists "$OUTPUT_DIR/.tests/${artifact}":
-      mv "$OUTPUT_DIR/.tests/${artifact}" "$OUTPUT_DIR/.history/${name}-${TIMESTAMP}.${ext}"
-```
+**Archive previous test result artifacts** before writing: if `test-results.json` or `coverage-report.json` exist in `$OUTPUT_DIR/.tests/`, move them to `$OUTPUT_DIR/.history/{name}-{YYYY-MM-DDTHH-mm-ss}.{ext}`.
 
 Write `.tests/test-results.json`:
 ```json
@@ -407,45 +344,11 @@ If issues > 0 -> go to Step 11.
 
 2. **Spawn one debug agent per cluster** (parallel):
 
-For each cluster, spawn workflow-debugger agent with pre-filled symptoms:
-```
-Agent({
-  subagent_type: "general-purpose",
-  description: "Diagnose UAT gap cluster: {cluster_name}",
-  prompt: "
-    Investigate UAT failures for {target}.
-
-    Gaps in this cluster:
-    {gap list with test ID, expected, reported, severity}
-
-    Mode: symptoms_prefilled (no user questions needed)
-    Goal: find root cause for each gap
-
-    Search relevant source files, trace the behavior,
-    identify why expected != actual.
-
-    Return for each gap:
-    - root_cause: what's wrong
-    - fix_direction: how to fix
-    - affected_files: which files need changes
-    - evidence: file:line references
-  ",
-  run_in_background: false
-})
-```
+For each cluster, spawn a general-purpose agent with pre-filled symptoms (test ID, expected, reported, severity). Agent investigates source files and returns per gap: `root_cause`, `fix_direction`, `affected_files`, `evidence` (file:line refs). Mode: `symptoms_prefilled`, goal: `find_root_cause`. `run_in_background: false`.
 
 3. **Collect results** from all agents.
 
-**Pass issue_ids to debug context:**
-```
-FOR each cluster:
-  cluster.issue_ids = []
-  FOR each gap IN cluster.gaps:
-    IF gap.issue_id exists:
-      cluster.issue_ids.push(gap.issue_id)
-  // Include issue_ids in the agent prompt context so debug agents
-  // can reference and update the corresponding issues
-```
+**Pass issue_ids to debug context:** gather `issue_id` from each gap in the cluster and include in agent prompt so debug agents can reference/update corresponding issues.
 
 4. **Update uat.md** gaps with diagnosis:
 ```yaml
@@ -505,22 +408,9 @@ If re-verify passes: update uat.md gaps as resolved, report success.
 If re-verify still has gaps: report remaining gaps, suggest manual intervention.
 
 **Issue lifecycle updates during gap-fix loop:**
-```
-// Before fix execution: transition issues to planning/executing
-FOR each gap IN diagnosed_gaps:
-  IF gap.issue_id exists:
-    Update issue in .workflow/issues/issues.jsonl:
-      status: "registered" -> "planning" (before plan --gaps)
-      status: "planning" -> "executing" (before execute)
-
-// After re-verify: update based on result
-FOR each gap IN diagnosed_gaps:
-  IF gap.issue_id exists:
-    IF gap resolved by re-verify:
-      Update issue: status -> "completed", resolved_at -> now(), resolution -> "auto-fixed via gap-fix loop"
-    ELSE:
-      Update issue: status -> "failed", updated_at -> now()
-```
+- Before plan --gaps: transition issues `registered` -> `planning`
+- Before execute: transition `planning` -> `executing`
+- After re-verify: resolved gaps -> `completed` (with resolution "auto-fixed via gap-fix loop"), unresolved -> `failed`
 
 **Loop limit**: Maximum 2 iterations to prevent infinite loops.
 
@@ -554,8 +444,8 @@ Next steps:
 
 | Result | Suggestion |
 |--------|------------|
-| All passed, no gaps | Skill({ skill: "maestro-phase-transition" }) |
-| Gaps auto-fixed | Skill({ skill: "maestro-phase-transition" }) |
+| All passed, no gaps | Skill({ skill: "maestro-milestone-audit" }) |
+| Gaps auto-fixed | Skill({ skill: "maestro-milestone-audit" }) |
 | Gaps remain, diagnosed | Skill({ skill: "quality-debug" }) or Skill({ skill: "maestro-plan", args: "--gaps" }) |
 | Low coverage | Skill({ skill: "quality-test-gen", args: "{phase}" }) to generate missing tests |