maestro-flow 0.3.14 → 0.3.16

package/workflows/review.md

@@ -16,15 +16,9 @@ Tiered multi-dimensional code review with parallel agents, severity classificati
 ```
 Input: <phase> argument (number or slug)
 
-Read .workflow/state.json → state
-artifacts = state.artifacts ?? []
-
-IF number: art = artifacts.find(a => a.type === 'execute' && a.phase === number)
-IF slug:   art = artifacts.find(a => a.type === 'execute' && a.slug?.includes(slug))
-IF art:    PHASE_DIR = ".workflow/" + art.path
-ELSE:      ERROR "Phase not found in artifact registry"
-
-Validate execution has occurred (tasks_completed > 0 or .task/ exists)
+Resolve phase from .workflow/state.json artifacts (type=execute, match by phase number or slug)
+→ PHASE_DIR = ".workflow/" + artifact.path
+→ Error if not found or no completed tasks
 ```
 
 ---
@@ -61,25 +55,16 @@ Three tiers that scale with task depth:
 ### 1a: Extract from task summaries
 
 ```
-changed_files = []
-FOR each .summaries/TASK-{NNN}-summary.md in PHASE_DIR:
-  Parse summary for file paths mentioned (created, modified, deleted)
-  Add to changed_files[]
-
-FOR each .task/TASK-{NNN}.json in PHASE_DIR:
-  Extract files[].path where action is "create" or "modify"
-  Add to changed_files[]
-
-Deduplicate changed_files
+Collect changed_files from PHASE_DIR:
+  - .summaries/TASK-{NNN}-summary.md → extract referenced file paths (created/modified/deleted)
+  - .task/TASK-{NNN}.json → extract files[].path where action is create|modify
+Deduplicate result
 ```
 
 ### 1b: Validate files exist
 
 ```
-review_files = []
-FOR each file in changed_files:
-  IF file exists on disk AND is not in excluded patterns:
-    review_files.push(file)
+review_files = changed_files filtered to: exists on disk AND not in excluded patterns
 
 Excluded patterns:
   - node_modules/**, vendor/**, dist/**, build/**
@@ -90,8 +75,7 @@ Excluded patterns:
 ### 1c: Error if empty
 
 ```
-IF review_files.length == 0:
-  Abort with E004: "No changed files detected in phase"
+Abort E004 if review_files is empty
 ```
 
 ---
@@ -99,18 +83,8 @@ IF review_files.length == 0:
 ## Step 2: Determine Review Level
 
 ```
-IF --level flag provided:
-  level = flag value (quick | standard | deep)
-ELSE:
-  is_critical_phase = index.json.priority == "critical" || index.json.tags?.includes("critical")
-  file_count = review_files.length
-
-  IF file_count <= 3:
-    level = "quick"
-  ELSE IF file_count >= 20 OR is_critical_phase:
-    level = "deep"
-  ELSE:
-    level = "standard"
+level = --level flag value, or auto-detect:
+  ≤3 files → quick | ≥20 files or critical phase → deep | otherwise → standard
 
 Log: "Review level: {level} ({file_count} files)"
 ```
@@ -118,12 +92,9 @@ Log: "Review level: {level} ({file_count} files)"
 ### Determine dimensions
 
 ```
-IF --dimensions flag provided:
-  dimensions = parse comma-separated list, validate each
-ELSE IF level == "quick":
-  dimensions = ["correctness", "security"]
-ELSE:
-  dimensions = ["correctness", "security", "performance", "architecture", "maintainability", "best-practices"]
+dimensions = --dimensions flag (comma-separated), or level defaults:
+  quick → [correctness, security]
+  standard|deep → [correctness, security, performance, architecture, maintainability, best-practices]
 ```
 
 ---
@@ -150,13 +121,8 @@ review_context = {
   success_criteria: index.json.success_criteria,
   tech_stack: detect from package.json / pyproject.toml / go.mod / Cargo.toml,
   specs: specs_content (from Step 3),
-  verification_gaps: [] // from verification.json if exists
+  verification_gaps: load from ${PHASE_DIR}/verification.json .gaps if exists, else []
 }
-
-IF file exists "${PHASE_DIR}/verification.json":
-  Load verification.json
-  review_context.verification_gaps = verification.json.gaps
-  (Reviewers use this to focus on areas with known issues)
 ```
 
 ---
@@ -170,30 +136,15 @@ IF file exists "${PHASE_DIR}/verification.json":
 No agents spawned. The orchestrator performs the review directly.
 
 ```
-all_findings = []
-
-FOR each dimension in dimensions:  // correctness, security
-  FOR each file in review_files:
-    Read file content
-    Apply dimension-specific checks:
-
-    IF dimension == "correctness":
-      - Scan for: unhandled null/undefined, missing error propagation, type mismatches
-      - Scan for: off-by-one patterns, missing boundary checks
-      - Scan for: unreachable code, logic contradictions
+Scan each review_file against each dimension, collecting findings:
 
-    IF dimension == "security":
-      - Scan for: SQL/command injection (string interpolation in queries)
-      - Scan for: hardcoded secrets, API keys, passwords
-      - Scan for: missing input validation on external inputs
-      - Scan for: XSS vectors (unsanitized user content in output)
+  correctness: unhandled null/undefined, missing error propagation, type mismatches,
+               off-by-one, missing boundary checks, unreachable code, logic contradictions
+  security:    SQL/command injection, hardcoded secrets/keys/passwords,
+               missing input validation, XSS vectors
 
-    FOR each issue found:
-      all_findings.push({
-        id: "{PREFIX}-{NNN}",
-        dimension, severity, title, file, line, snippet,
-        description, impact, suggestion
-      })
+Each finding: { id: "{PREFIX}-{NNN}", dimension, severity, title, file, line, snippet,
+               description, impact, suggestion }
 ```
 
 **After inline scan, skip to Step 6 (Aggregate).**
@@ -203,91 +154,32 @@ FOR each dimension in dimensions:  // correctness, security
 Spawn one workflow-reviewer agent per dimension, all in parallel:
 
 ```
-Agent({
-  subagent_type: "workflow-reviewer",
-  run_in_background: false,
-  description: "Review: {dimension}",
-  prompt: `
-    ## Assignment
-    Dimension: {dimension}
-    Phase: {phase_name} — {phase_goal}
-
-    ## Files to Review
-    {review_files joined by newline}
-
-    ## Phase Context
-    Success criteria: {success_criteria}
-    Tech stack: {tech_stack}
-
-    ## Project Specs
-    {specs_content or "No specs loaded"}
-
-    ## Known Issues (from verification)
-    {verification_gaps or "No prior verification gaps"}
-
-    ## Instructions
-    1. Read each file listed above
-    2. Analyze for {dimension}-specific issues only
-    3. Classify each finding: critical / high / medium / low
-    4. Return findings as JSON array with: id, dimension, severity, title, file, line, snippet, description, impact, suggestion, spec_violation (if applicable)
-    5. Limit to top 20 findings, prioritized by severity
-    6. Every finding MUST have file:line evidence
-  `
-})
+Per dimension → spawn workflow-reviewer agent (all parallel):
+  Context: dimension, phase_name, phase_goal, review_files, success_criteria,
+           tech_stack, specs_content, verification_gaps
+  Instructions:
+    - Read each file, analyze for {dimension}-specific issues only
+    - Classify: critical / high / medium / low
+    - Return JSON array: id, dimension, severity, title, file, line, snippet,
+      description, impact, suggestion, spec_violation (if applicable)
+    - Top 20 findings by severity, each with file:line evidence
 ```
 
 **Launch ALL dimension agents in a single message** (parallel execution).
 
-Collect results:
-```
-dimension_results = {}
-FOR each completed agent:
-  Parse JSON findings array from agent output
-  dimension_results[dimension] = findings[]
-  IF agent failed:
-    Log warning W001, continue with partial results
-```
+Collect dimension_results from each agent (JSON findings array). Log W001 on agent failure, continue with partial results.
 
 ### Deep Level — Enhanced Agent Review
 
 Same parallel agent spawning as standard, but with enhanced prompt:
 
 ```
-Agent({
-  subagent_type: "workflow-reviewer",
-  run_in_background: false,
-  description: "Review: {dimension}",
-  prompt: `
-    ## Assignment
-    Dimension: {dimension}
-    Phase: {phase_name} — {phase_goal}
-    Review Level: DEEP — thorough analysis required
-
-    ## Files to Review
-    {review_files joined by newline}
-
-    ## Phase Context
-    Success criteria: {success_criteria}
-    Tech stack: {tech_stack}
-
-    ## Project Specs
-    {specs_content or "No specs loaded"}
-
-    ## Known Issues (from verification)
-    {verification_gaps or "No prior verification gaps"}
-
-    ## Instructions (Deep Mode)
-    1. Read each file listed above completely
-    2. For each file, also read its direct imports to understand context
-    3. Analyze for {dimension}-specific issues
-    4. Classify each finding: critical / high / medium / low
-    5. For critical/high findings: trace callers and dependents
-    6. Cross-reference patterns across files (duplication, inconsistency)
-    7. Return findings as JSON array with: id, dimension, severity, title, file, line, snippet, description, impact, suggestion, spec_violation, related_files[]
-    8. Limit to top 30 findings, prioritized by severity
-    9. Every finding MUST have file:line evidence
-  `
-})
+Same parallel agent spawning as standard, with deep-mode enhancements:
+  - Also read direct imports for context
+  - Trace callers/dependents for critical/high findings
+  - Cross-reference patterns across files (duplication, inconsistency)
+  - Return includes additional field: related_files[]
+  - Top 30 findings (vs 20 for standard)
 ```
 
 Collect results same as standard.
@@ -299,50 +191,30 @@ Collect results same as standard.
 ### 6a: Merge all findings
 
 ```
-all_findings = []
-FOR each dimension in dimension_results (or inline results for quick):
-  all_findings.push(...findings)
-
-Sort all_findings by severity (critical > high > medium > low), then by dimension
+all_findings = merge all dimension results, sorted by severity (critical > high > medium > low), then dimension
 ```
 
 ### 6b: Severity distribution
 
 ```
-severity_dist = {
-  critical: all_findings.filter(f => f.severity == "critical").length,
-  high: all_findings.filter(f => f.severity == "high").length,
-  medium: all_findings.filter(f => f.severity == "medium").length,
-  low: all_findings.filter(f => f.severity == "low").length
-}
+severity_dist = count all_findings by severity {critical, high, medium, low}
 ```
 
 ### 6c: Identify critical files (standard + deep only)
 
 ```
 IF level != "quick":
-  file_dimension_map = {}
-  FOR each finding in all_findings:
-    IF finding.severity in ["critical", "high"]:
-      file_dimension_map[finding.file] = file_dimension_map[finding.file] || new Set()
-      file_dimension_map[finding.file].add(finding.dimension)
-
-  critical_files = Object.entries(file_dimension_map)
-    .filter(([file, dims]) => dims.size >= 3)
-    .map(([file, dims]) => ({ file, dimensions: [...dims] }))
+  critical_files = files with critical/high findings across 3+ distinct dimensions
+  → [{ file, dimensions[] }]
 ```
 
 ### 6d: Determine verdict
 
 ```
-IF severity_dist.critical > 0:
-  verdict = "BLOCK"    // Must fix before proceeding
-ELSE IF severity_dist.high > 5:
-  verdict = "BLOCK"    // Too many high-severity issues
-ELSE IF severity_dist.high > 0:
-  verdict = "WARN"     // Should fix, can proceed with acknowledgment
-ELSE:
-  verdict = "PASS"     // Good to proceed
+verdict:
+  BLOCK → any critical, or >5 high
+  WARN  → any high (≤5)
+  PASS  → no critical or high
 ```
 
 ---
@@ -360,73 +232,34 @@ ELSE:
 ### 7a: Select deep-dive targets
 
 ```
-IF level == "deep":
-  deep_dive_targets = all_findings
-    .filter(f => f.severity in ["critical", "high"])
-    .slice(0, 15)  // More targets for deep level
-ELSE:
-  deep_dive_targets = all_findings
-    .filter(f => f.severity == "critical")
-    .slice(0, 10)
+deep_dive_targets:
+  deep  → critical + high findings, top 15
+  standard → critical findings only, top 10
 ```
 
 ### 7b: Deep-dive iteration
 
 ```
-max_iterations = level == "deep" ? 3 : 1
-deep_dive_results = []
-
-FOR iteration = 1 TO max_iterations:
-  unresolved = deep_dive_targets.filter(t => !t.deep_dive_complete)
-  IF unresolved.length == 0: break
-
-  FOR each target in unresolved:
-    Agent({
-      subagent_type: "workflow-reviewer",
-      run_in_background: false,
-      description: "Deep-dive: {target.id}",
-      prompt: `
-        ## Deep-Dive Analysis (Iteration {iteration})
-        Original finding: {target as JSON}
-        {IF iteration > 1: "Previous analysis: {previous_result}"}
-
-        ## Extended Context
-        1. Read the affected file completely: {target.file}
-        2. Find all imports/callers of the affected code:
-           grep -r "{identifier}" src/ --include="*.ts" --include="*.tsx" --include="*.py"
-        3. Check related test files for coverage
-
-        ## Analyze
-        - Root cause: Why does this issue exist?
-        - Impact radius: What other code is affected?
-        - Remediation: Specific fix with code example
-        - Risk: What could go wrong if unfixed?
-
-        ## Output
-        Return JSON:
-        {
-          "finding_id": "{target.id}",
-          "root_cause": "...",
-          "impact_radius": ["file1.ts", "file2.ts"],
-          "remediation": { "approach": "...", "code_example": "..." },
-          "risk_if_unfixed": "...",
-          "reassessed_severity": "critical|high|medium|low",
-          "confidence": 0.0-1.0
-        }
-      `
-    })
-
-  Merge results:
-  FOR each result:
-    Find original finding by finding_id
-    Enrich with root_cause, impact_radius, remediation, risk_if_unfixed
-    IF result.confidence >= 0.8:
-      target.deep_dive_complete = true
-    Update severity if reassessed differently (with justification)
-    deep_dive_results.push(result)
-
-  IF level == "deep" AND iteration < max_iterations:
-    Log: "Deep-dive iteration {iteration} complete. {unresolved remaining} findings need further analysis."
+Iterate up to max_iterations (deep=3, standard=1) over unresolved targets:
+
+  Per target → spawn workflow-reviewer agent:
+    Context: original finding JSON, previous analysis (if iteration > 1)
+    Tasks: read affected file, find callers/imports, check test coverage
+    Analyze: root cause, impact radius, remediation (with code example), risk if unfixed
+
+    Return JSON:
+    {
+      "finding_id": "{target.id}",
+      "root_cause": "...",
+      "impact_radius": ["file1.ts", "file2.ts"],
+      "remediation": { "approach": "...", "code_example": "..." },
+      "risk_if_unfixed": "...",
+      "reassessed_severity": "critical|high|medium|low",
+      "confidence": 0.0-1.0
+    }
+
+  Merge: enrich original finding, mark complete if confidence >= 0.8,
+         update severity if reassessed. Stop early if all resolved.
 ```
 
 ---
@@ -442,56 +275,20 @@ FOR iteration = 1 TO max_iterations:
 | Deep | Critical + High + Medium |
 
 ```
-IF level == "quick":
-  issue_findings = all_findings.filter(f => f.severity == "critical")
-ELSE IF level == "standard":
-  issue_findings = all_findings.filter(f => f.severity in ["critical", "high"])
-ELSE:
-  issue_findings = all_findings.filter(f => f.severity in ["critical", "high", "medium"])
-
-IF issue_findings.length > 0:
-  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)
-
-  FOR each finding IN issue_findings:
-    issue_id = "ISS-{today}-{counter padded to 3 digits}"
-    issue = {
-      id: issue_id,
-      title: "[{finding.dimension}] {finding.title}" (truncated to 100 chars),
-      status: "registered",
-      priority: severity_to_priority(finding.severity),
-      severity: finding.severity,
-      source: "review",
-      phase_ref: PHASE_NUM,
-      gap_ref: finding.id,
-      description: finding.description,
-      fix_direction: finding.suggestion,
-      context: {
-        location: "{finding.file}:{finding.line}",
-        suggested_fix: finding.suggestion,
-        notes: finding.impact
-      },
-      tags: ["review", finding.dimension],
-      affected_components: [],
-      feedback: [],
-      issue_history: [],
-      created_at: now(),
-      updated_at: now(),
-      resolved_at: null,
-      resolution: null
-    }
-    Append JSON line to .workflow/issues/issues.jsonl
-    finding.issue_id = issue_id
-    counter++
+Filter findings by level threshold (quick=critical, standard=critical+high, deep=+medium)
+
+For each qualifying finding → append issue to .workflow/issues/issues.jsonl:
+  id: "ISS-{YYYYMMDD}-{NNN}" (auto-increment from existing today's entries)
+  title: "[{dimension}] {title}" (max 100 chars)
+  status: "registered"
+  priority: severity_to_priority (critical→1, high→2, medium→3)
+  severity, source: "review", phase_ref, gap_ref: finding.id
+  description, fix_direction: finding.suggestion
+  context: { location: "{file}:{line}", suggested_fix, notes: impact }
+  tags: ["review", dimension]
+  Timestamps: created_at, updated_at = now()
 
-  Print: "Created {issue_findings.length} issues from review findings"
+Link finding.issue_id back to created issue
 ```
 
 **severity_to_priority mapping**: critical → 1, high → 2, medium → 3
@@ -502,10 +299,7 @@ IF issue_findings.length > 0:
 
 **Archive previous review artifacts** before writing:
 ```
-IF file exists "${PHASE_DIR}/review.json":
-  mkdir -p "${PHASE_DIR}/.history"
-  TIMESTAMP = current timestamp formatted as "YYYY-MM-DDTHH-mm-ss"
-  mv "${PHASE_DIR}/review.json" "${PHASE_DIR}/.history/review-${TIMESTAMP}.json"
+Archive existing review.json → ${PHASE_DIR}/.history/review-{YYYY-MM-DDTHH-mm-ss}.json
 ```
 
 ```
@@ -537,15 +331,9 @@ Write ${PHASE_DIR}/review.json:
 ## Step 10: Update index.json
 
 ```
-index.json.updated_at = now()
-index.json.review = {
-  level: review.json.level,
-  verdict: review.json.verdict,
-  reviewed_at: review.json.reviewed_at,
-  severity_distribution: review.json.severity_distribution,
-  findings_count: review.json.severity_distribution.total,
-  issues_created: review.json.issues_created.length
-}
+Update index.json.updated_at = now()
+Set index.json.review = { level, verdict, reviewed_at, severity_distribution,
+                          findings_count, issues_created count }
 ```
 
 ---
@@ -592,7 +380,7 @@ Next steps:
 
 | Verdict | Suggestion |
 |---------|------------|
-| PASS | Skill({ skill: "quality-test", args: "{phase}" }) for UAT, or Skill({ skill: "maestro-phase-transition", args: "{phase}" }) if UAT already passed |
+| PASS | Skill({ skill: "quality-test", args: "{phase}" }) for UAT, or Skill({ skill: "maestro-milestone-audit" }) if UAT already passed |
 | WARN | Review findings, then Skill({ skill: "quality-test", args: "{phase}" }) — acknowledge warnings before proceeding |
 | BLOCK | Fix critical issues first: Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) -> Skill({ skill: "maestro-execute", args: "{phase}" }) -> re-run Skill({ skill: "quality-review", args: "{phase}" }) |