maestro-flow 0.3.15 → 0.3.17

package/workflows/integration-test.md

@@ -19,51 +19,11 @@ L0-L3 progressive layers: Static Analysis -> Unit -> Integration -> E2E
 | `--max-iter N` | Set MAX_ITER = N (default 5) |
 | `--layer L2` | Start from L2 layer |
 
-**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"
-```
-
-Check for existing integration test session:
-```bash
-ls ${PHASE_DIR}/.tests/integration/state.json 2>/dev/null
-```
-
-If session exists: offer resume or restart.
-
-**Initialize session:**
-
-Create `.tests/integration/` directory.
+**Resolve phase dir:** from state.json artifact registry (type='execute', matching phase). Error if not found.
 
-Write initial `state.json`:
-```json
-{
-  "phase": "{phase}",
-  "started_at": "{ISO timestamp}",
-  "current_iteration": 0,
-  "max_iterations": 5,
-  "strategy": "conservative",
-  "current_layer": "L0",
-  "pass_rates": [],
-  "convergence_threshold": 95,
-  "status": "running"
-}
-```
+If existing session at `${PHASE_DIR}/.tests/integration/state.json`: offer resume or restart.
 
-Initialize `reflection-log.md`:
-```markdown
-# Integration Test Reflection Log
-Phase: {phase_name}
-Started: {timestamp}
-
-## Iterations
-```
+**Initialize session:** create `.tests/integration/` directory, write initial `state.json` (iteration=0, strategy=conservative, layer=L0, threshold=95, status=running), initialize `reflection-log.md`.
 
 ---
 
@@ -80,20 +40,8 @@ arch_content = maestro spec load --category arch
 
 ### Step 1.5: Load Previously Generated Tests
 
-Check for tests already generated by `quality-test-gen`:
-
-```
-generated_tests = []
-IF file exists "${PHASE_DIR}/.tests/test-gen-report.json":
-  report = read_json("${PHASE_DIR}/.tests/test-gen-report.json")
-  FOR test_entry IN report.generated:
-    IF test_entry.layer is "integration" or "e2e":
-      generated_tests.push(test_entry)
-  IF generated_tests.length > 0:
-    display "Found {generated_tests.length} pre-generated integration/e2e tests from test-gen. Will incorporate into test plan."
-```
-
-These tests are merged into the test plan in Step 3 (Design) — they are executed but not re-generated.
+Load pre-generated integration/e2e tests from `${PHASE_DIR}/.tests/test-gen-report.json` (if exists).
+These are merged into the test plan in Step 3 -- executed but not re-generated.
 
 ---
 
@@ -108,18 +56,8 @@ Discover:
 - External service integrations
 - Event flows and message passing
 
-```bash
-# Find cross-module imports
-grep -r "import.*from.*\.\./" src/ --include="*.ts" --include="*.tsx" -l 2>/dev/null | head -20
-
-# Find API route definitions
-grep -r "router\.\|app\.\(get\|post\|put\|delete\)" src/ --include="*.ts" -l 2>/dev/null | head -20
-
-# Find database calls
-grep -r "prisma\.\|query\|findMany\|findOne\|create\|update\|delete" src/ --include="*.ts" -l 2>/dev/null | head -20
-```
-
-Map integration points: which modules talk to which, through what interfaces.
+Scan for cross-module imports, API route definitions, and database calls.
+Map integration points: which modules communicate through what interfaces.
 
 ---
 
@@ -185,39 +123,12 @@ For integration tests (L2) specifically:
 **Phase 4: Execute tests for current layer.**
 
 Run tests progressively (L0 must pass before L1, etc.):
+- L0: `tsc --noEmit` + `eslint src/`
+- L1: unit tests (`--testPathPattern="unit|__tests__"`)
+- L2: integration tests (`--testPathPattern="integration"`)
+- L3: E2E tests (`--testPathPattern="e2e"`)
 
-```bash
-# L0: Static analysis
-tsc --noEmit 2>&1 | tail -30
-eslint src/ 2>&1 | tail -30
-
-# L1: Unit tests
-{test_command} --testPathPattern="unit|__tests__" 2>&1 | tail -50
-
-# L2: Integration tests
-{test_command} --testPathPattern="integration" 2>&1 | tail -50
-
-# L3: E2E tests
-{test_command} --testPathPattern="e2e" 2>&1 | tail -50
-```
-
-Record results in `test-results-iter-{N}.json`:
-```json
-{
-  "iteration": N,
-  "timestamp": "{ISO timestamp}",
-  "strategy": "{current_strategy}",
-  "layers": {
-    "L0": { "status": "pass|fail", "errors": [...] },
-    "L1": { "total": N, "passed": P, "failed": F, "pass_rate": 95.0 },
-    "L2": { "total": N, "passed": P, "failed": F, "pass_rate": 87.5 },
-    "L3": { "total": N, "passed": P, "failed": F, "pass_rate": 100.0 }
-  },
-  "overall_pass_rate": 92.3
-}
-```
-
-Calculate overall pass rate.
+Record per-layer results (status, total/passed/failed/pass_rate) and overall_pass_rate in `test-results-iter-{N}.json`.
 
 ---
 
@@ -225,32 +136,9 @@ Calculate overall pass rate.
 
 **Phase 5: Reflect on iteration results.**
 
-Analyze what happened:
-- Which tests failed and why?
-- Is pass rate improving, plateauing, or regressing?
-- Are failures clustered in one area or spread out?
-- Is the current strategy working?
-
-Append to `reflection-log.md`:
-```markdown
-## Iteration {N}
-Strategy: {strategy_name}
-Pass rate: {rate}% (previous: {prev_rate}%)
-Delta: {+/-}%
+Analyze: which tests failed, is pass rate improving/plateauing/regressing, are failures clustered, is strategy working.
 
-### What worked
-- {observation}
-
-### What failed
-- {test}: {reason}
-
-### Pattern detected
-- {pattern, e.g., "all failures in auth module"}
-
-### Strategy assessment
-- Current strategy: {effective|ineffective|partially_effective}
-- Recommendation: {keep|switch_to_X}
-```
+Append to `reflection-log.md`: iteration strategy, pass rate delta, what worked/failed, detected patterns, strategy assessment (effective/ineffective + recommendation).
 
 ---
 
@@ -267,82 +155,25 @@ Delta: {+/-}%
 | New regressions appeared | Surgical | Revert last changes, fix regression only |
 | Stuck 3+ iterations (rate not improving) | Reflective | Step back, re-analyze root cause pattern |
 
-**Strategy transitions:**
-```
-Conservative -> (pass rate >80%) -> Aggressive
-Aggressive -> (regression) -> Surgical
-Surgical -> (regression fixed) -> Aggressive
-Any -> (stuck 3+ iters) -> Reflective
-Reflective -> (new insight) -> Conservative (restart approach)
-```
-
-Update state.json with new strategy and iteration count.
+**Strategy transitions:** Conservative --(>80%)--> Aggressive --(regression)--> Surgical --(fixed)--> Aggressive. Any --(stuck 3+ iters)--> Reflective --(insight)--> Conservative.
 
-**Convergence check:**
-- If overall_pass_rate >= convergence_threshold (95%): CONVERGED -> go to Step 8
-- If iteration >= max_iterations: MAX_ITER_REACHED -> go to Step 8
-- Otherwise: go back to Step 4 (next iteration)
+Update state.json. **Convergence:** pass_rate >= 95% -> Step 8. max_iterations reached -> Step 8. Otherwise -> Step 4.
 
 ---
 
 ### Step 8: Complete
 
-**Complete integration test cycle.**
-
-Update state.json: status -> "complete" or "max_iter_reached".
-
-Write `.tests/integration/summary.json`:
-```json
-{
-  "phase": "{phase}",
-  "completed_at": "{ISO timestamp}",
-  "iterations": N,
-  "final_pass_rate": 97.5,
-  "converged": true,
-  "strategy_history": ["conservative", "conservative", "aggressive"],
-  "layers": {
-    "L0": { "status": "pass" },
-    "L1": { "pass_rate": 100.0 },
-    "L2": { "pass_rate": 95.0 },
-    "L3": { "pass_rate": 100.0 }
-  },
-  "bugs_discovered": [...],
-  "regressions_fixed": [...]
-}
-```
-
+Update state.json status to "complete" or "max_iter_reached".
+Write `.tests/integration/summary.json`: iterations, final_pass_rate, converged flag, strategy_history, per-layer results, bugs_discovered, regressions_fixed.
 Update index.json with integration test results.
 
 ---
 
 ### Step 9: Report
 
-```
-=== INTEGRATION TEST CYCLE ===
-Phase:       {phase_name}
-Iterations:  {N}/{max_iter}
-Converged:   {yes/no} (threshold: {threshold}%)
-
-Layer Results:
-  L0 Static:      {pass/fail}
-  L1 Unit:        {pass_rate}% ({passed}/{total})
-  L2 Integration: {pass_rate}% ({passed}/{total})
-  L3 E2E:         {pass_rate}% ({passed}/{total})
-
-Overall:     {final_pass_rate}%
-Strategy:    {final_strategy} (transitioned {N} times)
-
-Bugs Found:  {bug_count}
-Regressions: {regression_count} found, {fixed_count} fixed
-
-Files:
-  {target_dir}/.tests/integration/state.json
-  {target_dir}/.tests/integration/reflection-log.md
-  {target_dir}/.tests/integration/summary.json
-
-Next steps:
-  {suggested_next_command}
-```
+Display summary: iterations, convergence status, per-layer pass rates, overall rate, strategy transitions, bugs/regressions found.
+
+List output files: state.json, reflection-log.md, summary.json.
 
 **Next step routing:**
 

package/workflows/issue-analyze.md

@@ -16,19 +16,8 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 1: Parse Arguments
 
 ```
-1. Extract ISS-ID from first positional token in $ARGUMENTS
-   If empty → error E_NO_ISSUE_ID:
-     "Usage: /manage-issue-analyze <ISS-ID> [--tool gemini|qwen] [--depth standard|deep]"
-     "Example: /manage-issue-analyze ISS-20260318-001 --tool gemini --depth deep"
-
-2. Parse optional flags:
-   --tool VALUE    → TOOL (default: gemini)
-   --depth VALUE   → DEPTH (default: standard)
-
-3. Validate:
-   - ISS-ID matches pattern ISS-\d{8}-\d{3}
-   - TOOL is one of: gemini, qwen
-   - DEPTH is one of: standard, deep
+Extract ISS-ID (required, pattern ISS-\d{8}-\d{3}).
+Flags: --tool gemini|qwen (default: gemini), --depth standard|deep (default: standard)
 ```
 
 ---
@@ -36,21 +25,8 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 2: Load Issue and Validate
 
 ```
-1. Check .workflow/issues/issues.jsonl exists
-   If not → fatal: "No issues file. Run /manage-issue create first."
-
-2. Read .workflow/issues/issues.jsonl line by line
-3. Parse each line as JSON, find record where id == ISS-ID
-   If not found → error E_ISSUE_NOT_FOUND:
-     "Issue {ISS-ID} not found. Run /manage-issue list to see available issues."
-
-4. Check issue status:
-   - If status is 'open' or 'registered' → proceed
-   - Otherwise → warning E_INVALID_STATUS:
-     "Issue {ISS-ID} has status '{status}'. Analysis typically runs on open issues."
-     Proceed anyway (analysis is non-destructive metadata enrichment).
-
-5. Store issue record as ISSUE for subsequent steps
+Load ISS-ID from .workflow/issues/issues.jsonl → fatal if file missing or ID not found.
+Status check: open/registered → proceed; other → warn but continue (non-destructive).
 ```
 
 ---
@@ -58,30 +34,14 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 3: Gather Codebase Context
 
 ```
-1. Extract keywords from ISSUE.title and ISSUE.description
-   - Split into significant words (>3 chars, skip stop words)
-   - Include ISSUE.context.location if present
-   - Include ISSUE.affected_components[] if present
-
-2. If DEPTH == "standard":
-   - Use Grep to search for each keyword in source files:
-     rg "{keyword}" --type-add "src:*.{ts,tsx,js,jsx,py,java,go}" --type src -l
-   - Collect up to 20 matching file paths
-   - For top 5 files by match count, read relevant sections (10 lines around match)
-
-3. If DEPTH == "deep":
-   - Run standard keyword grep (above)
-   - Additionally, launch Agent for semantic search:
-     Search for code related to: "{ISSUE.title} - {ISSUE.description}"
-     Focus on: error handling, data flow, dependencies
-   - Merge results from both approaches
-
-4. Build CONTEXT_SUMMARY:
-   - List of related files with brief relevance notes
-   - Key code snippets (max 50 lines total)
-   - Dependency chain if identifiable
-
-5. Store as CODEBASE_CONTEXT for CLI prompt
+Extract keywords from issue title, description, location, affected_components.
+
+Standard depth: grep keywords in source files → top 20 paths, read 10 lines around
+  top 5 matches.
+Deep depth: standard grep + semantic Agent search (error handling, data flow, deps),
+  merge results.
+
+Build CODEBASE_CONTEXT: related files, key snippets (max 50 lines), dependency chain.
 ```
 
 ---
@@ -89,47 +49,18 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 4: Run CLI Analysis
 
 ```
-1. Build analysis prompt:
-
-   maestro delegate "PURPOSE: Root cause analysis for issue {ISS-ID}: {ISSUE.title}
-   Identify the root cause, assess impact, and suggest an approach.
-
-   ISSUE DETAILS:
-   - Title: {ISSUE.title}
-   - Description: {ISSUE.description}
-   - Severity: {ISSUE.severity}
-   - Location: {ISSUE.context.location or 'unknown'}
-   - Fix Direction: {ISSUE.fix_direction or 'none provided'}
-
-   CODEBASE CONTEXT:
-   {CODEBASE_CONTEXT}
-
-   TASK:
-   - Identify the root cause with file:line references
-   - Assess impact scope (which components/features affected)
-   - List all related files that need attention
-   - Rate confidence in the analysis (high/medium/low)
-   - Suggest a fix approach (brief, actionable)
-
-   MODE: analysis
-   CONTEXT: @**/*
-   EXPECTED: JSON object with fields:
-     root_cause: string (clear explanation),
-     impact: string (scope of impact),
-     related_files: string[] (file paths),
-     confidence: 'high'|'medium'|'low',
-     suggested_approach: string (actionable fix direction)
-   CONSTRAINTS: Only cite evidence found in codebase, no speculation
-   " --to {TOOL} --mode analysis
-
-2. Parse CLI output:
-   - Extract JSON object from response
-   - Validate required fields: root_cause, impact, related_files, confidence, suggested_approach
-   - If parsing fails → error E_ANALYSIS_FAILED:
-     "Analysis did not return valid JSON. Raw output saved for review."
-     Store raw output in ISSUE feedback for manual review.
-
-3. Store parsed result as ANALYSIS_RESULT
+Delegate root cause analysis with issue details + CODEBASE_CONTEXT:
+
+  maestro delegate "Root cause analysis for {ISS-ID}: {ISSUE.title}
+  ISSUE: title, description, severity, location, fix_direction
+  CODEBASE CONTEXT: {CODEBASE_CONTEXT}
+  TASK: Identify root cause (file:line) → assess impact → list related files → rate confidence → suggest fix
+  EXPECTED: JSON { root_cause, impact, related_files[], confidence, suggested_approach }
+  CONSTRAINTS: Evidence-only, no speculation
+  " --to {TOOL} --mode analysis
+
+Validate response: all required fields present.
+Parse failure → save raw output to issue feedback for review.
 ```
 
 ---
@@ -137,18 +68,8 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 5: Build Analysis Record
 
 ```
-1. Construct IssueAnalysis record:
-   {
-     "root_cause": "{ANALYSIS_RESULT.root_cause}",
-     "impact": "{ANALYSIS_RESULT.impact}",
-     "related_files": {ANALYSIS_RESULT.related_files},
-     "confidence": "{ANALYSIS_RESULT.confidence}",
-     "suggested_approach": "{ANALYSIS_RESULT.suggested_approach}",
-     "analyzed_at": "{NOW_ISO}",
-     "analyzed_by": "{TOOL}"
-   }
-
-2. Store as ANALYSIS record for next step
+Construct IssueAnalysis:
+  { root_cause, impact, related_files, confidence, suggested_approach, analyzed_at: NOW_ISO, analyzed_by: TOOL }
 ```
 
 ---
@@ -156,27 +77,11 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 6: Update Issue in JSONL
 
 ```
-1. Read all lines from .workflow/issues/issues.jsonl
-2. Find the line matching ISS-ID
-3. Update the issue record:
-   - Set issue.analysis = ANALYSIS
-   - Set issue.updated_at = NOW_ISO
-   - Add issue_history entry:
-     {
-       "timestamp": "{NOW_ISO}",
-       "from_status": "{ISSUE.status}",
-       "to_status": "{ISSUE.status}",
-       "actor": "analysis-agent",
-       "note": "Root cause analysis completed (confidence: {ANALYSIS.confidence})"
-     }
-   - Status stays unchanged (analysis is metadata enrichment, not a status transition)
-
-4. Rewrite .workflow/issues/issues.jsonl:
-   - Replace the matching line with updated record (single JSON line)
-   - Write all lines back to file
-
-5. Verify file integrity:
-   - Re-read file, confirm ISS-ID record has analysis field
+Read-modify-write issues.jsonl:
+  Set issue.analysis = ANALYSIS, updated_at = NOW_ISO
+  Append issue_history: actor "analysis-agent", note "confidence: {confidence}"
+  Status unchanged (analysis is metadata enrichment).
+Verify: re-read file, confirm analysis field present.
 ```
 
 ---
@@ -184,34 +89,11 @@ Root cause analysis for a specific issue using CLI exploration and codebase cont
 ### Step 7: Display Summary and Next Steps
 
 ```
-Display analysis summary:
-
-====================================================
-  ANALYSIS COMPLETE: {ISS-ID}
-  Tool: {TOOL}    Depth: {DEPTH}
-====================================================
-
-ROOT CAUSE:
-  {ANALYSIS.root_cause}
-
-IMPACT:
-  {ANALYSIS.impact}
-
-CONFIDENCE: {ANALYSIS.confidence}
-
-RELATED FILES:
-  {for each file in ANALYSIS.related_files}
-  - {file}
-  {/for}
-
-SUGGESTED APPROACH:
-  {ANALYSIS.suggested_approach}
-====================================================
+Display: root cause, impact, confidence, related files, suggested approach.
 
-Suggest next steps:
-  - Skill({ skill: "manage-issue-plan", args: "{ISS-ID}" }) -- Generate solution plan
-  - Skill({ skill: "manage-issue-plan", args: "{ISS-ID} --tool {TOOL}" }) -- Plan with same tool
-  - Skill({ skill: "manage-issue", args: "status {ISS-ID}" }) -- View full issue details
+Next steps:
+  - manage-issue-plan {ISS-ID} (generate solution | --tool {TOOL})
+  - manage-issue status {ISS-ID}
 ```
 
 ---