maestro-flow-one 0.1.0

package/codex/maestro-flow/commands/quality/retrospective.md

@@ -0,0 +1,292 @@
+---
+name: quality-retrospective
+description: Multi-lens 复盘 (retrospective) for completed phases. Context-Agent Fork loads phase artifacts once; four parallel lens agents (technical, process, quality, decision) analyze independently; synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and lessons.jsonl.
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+<purpose>
+Multi-lens retrospective for completed phases. Context-Agent Fork loads phase artifacts once;
+four parallel lens agents (technical, process, quality, decision) analyze independently;
+synthesizer distills insights; outputs are routed to spec stubs, knowhow tips, issues, and lessons.jsonl.
+
+```
++------------------------------------------------------------------+
+|  quality-retrospective -- Context-Agent Fork + Parallel Fan-out   |
++------------------------------------------------------------------+
+
+  Stage 1-3: Read-only resolution (no writes)
+  +---------------------------------------------+
+  | Parse mode -> Validate artifacts              |
+  | -> [scan] Find unreviewed phases              |
+  +----------------------+-----------------------+
+                         |
+  Stage 4: Context-Agent Fork (Pattern 2.10)
+  +----------------------------------------------------------------+
+  |  spawn ctx (fork_turns: "none")                                 |
+  |  wait ctx                                                       |
+  |  +----------+ +----------+ +----------+ +----------+           |
+  |  |lens-tech | |lens-proc | |lens-qual | |lens-dec  |           |
+  |  |fork=true | |fork=true | |fork=true | |fork=true |           |
+  |  +----------+ +----------+ +----------+ +----------+           |
+  |  wait_agent([lens-tech, lens-proc, lens-qual, lens-dec])        |
+  |  close lenses -> close ctx LAST                                 |
+  +----------------------+-----------------------------------------+
+                         | lens results
+  Stage 5: Synthesizer
+  +------------------------------------------+
+  |  spawn synthesizer (fork_turns: "none") |
+  |  -> wait -> close                        |
+  +----------------------+-------------------+
+                         | distilled_insights
+  Stage 6-8: Route -> Write -> Report
+```
+</purpose>
+
+<context>
+```bash
+$quality-retrospective
+$quality-retrospective "3"
+$quality-retrospective "2..4"
+$quality-retrospective "--all"
+$quality-retrospective "3 --lens technical --no-route"
+$quality-retrospective "3 --compare 2 -y"
+```
+
+**Flags**:
+- No phase argument -> `scan` mode: report unreviewed completed phases, prompt selection
+- `<N>` -> `single` mode: retrospect phase N
+- `<N>..<M>` -> `range` mode: retrospect phases N through M (inclusive)
+- `--all` -> batch mode: re-run for every completed phase
+- `--lens <name>` -- restrict to one lens (repeatable): `technical|process|quality|decision`
+- `--no-route` -- produce retrospective.{md,json} only; skip auto-creation of spec/note/issue
+- `--compare <M>` -- emit a delta section vs phase M's prior retrospective
+- `-y` -- accept all routing recommendations without prompting
+
+When `-y`: Accept all routing recommendations without prompting. Route all insights automatically.
+
+**Storage written**:
+- `{target_dir}/retrospective.md` -- human-readable record (target_dir resolved via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`)
+- `{target_dir}/retrospective.json` -- structured record
+- `.workflow/specs/{category-file}.md` -- `<spec-entry>` entries appended to matching category files (one per spec-routed insight)
+- `.workflow/issues/issues.jsonl` -- appended issue rows (`source: "retrospective"`)
+- `.workflow/knowhow/TIP-*.md` -- knowhow tips (via `manage-knowhow-capture` skill)
+- `.workflow/learning/lessons.jsonl` -- append-only insight log
+- `.workflow/learning/learning-index.json` -- updated searchable index
+
+**Storage read (never modified)** — all resolved via `state.json.artifacts[]`:
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → index.json, plan.json, .task/TASK-*.json, .summaries/TASK-*-summary.md
+- **verify** → verification.json
+- **review** → review.json (findings, verdict, severity distribution)
+- **debug** → understanding.md, evidence.ndjson (root causes, fix directions)
+- **test** → uat.md, .tests/ (UAT results, gaps, coverage)
+- Also reads: `.workflow/issues/issues.jsonl`, `.workflow/state.json`
+
+### Agent Registry
+
+| Agent | task_name | fork_turns | Responsibility |
+|-------|-----------|------------|----------------|
+| Context Agent | `ctx` | "none" | Load all phase artifacts: index.json, plan.json, verification.json, review.json, uat.md, issues.jsonl, task summaries |
+| Technical Lens | `lens-tech` | "all" | Technical debt, architecture decisions, code quality gaps, performance issues |
+| Process Lens | `lens-proc` | "all" | Workflow efficiency, collaboration patterns, planning accuracy, bottlenecks |
+| Quality Lens | `lens-qual` | "all" | Test coverage gaps, verification failures, UAT issues, quality gate outcomes |
+| Decision Lens | `lens-dec` | "all" | Key decisions made, tradeoffs accepted, ADR candidates, reversibility |
+| Synthesizer | `synthesizer` | "none" | Merge lens results, deduplicate insights, classify routing targets |
+
+### Fork Turns Strategy
+
+| Agent | task_name | fork_turns | fork_from | Rationale |
+|-------|-----------|------------|-----------|-----------|
+| Context Agent | `ctx` | "none" | -- | Independent artifact loader; clean start |
+| Technical Lens | `lens-tech` | "all" | `ctx` | Inherits loaded artifacts -- no redundant file reads |
+| Process Lens | `lens-proc` | "all" | `ctx` | Inherits loaded artifacts -- no redundant file reads |
+| Quality Lens | `lens-qual` | "all" | `ctx` | Inherits loaded artifacts -- no redundant file reads |
+| Decision Lens | `lens-dec` | "all" | `ctx` | Inherits loaded artifacts -- no redundant file reads |
+| Synthesizer | `synthesizer` | "none" | -- | Clean context; receives lens results via message |
+
+**Context-Agent Lifecycle**: Spawn `ctx` first -> `wait_agent` -> spawn all lens agents (`fork_turns: "all"`) -> `wait_agent` batch for lenses -> `close_agent` lenses -> `close_agent ctx` LAST.
+
+> **fork_turns semantics**: `fork_turns: "all"` means the spawned agent inherits the *orchestrator's* current conversation context -- not the ctx agent's own context. When `wait_agent` for ctx returns, the ctx agent's completed artifact summaries are visible in the orchestrator's context. Lens agents forked after that point therefore inherit those summaries. Lens agents do **not** fork directly from `ctx`; the `fork_from: ctx` column above is conceptual shorthand for this sequencing.
+</context>
+
+<invariants>
+1. **Read-only until Stage 6**: Stages 1-5 must not write any files -- only read and analyze
+2. **Context-agent spawns first**: `ctx` must complete before any lens agent is spawned
+3. **Parallel lens dispatch**: All active lens agents spawned in a single batch, then `wait_agent` for all together -- never sequentially
+4. **Context-agent closes last**: Close all lens agents before closing `ctx`
+5. **Synthesizer is isolated**: `fork_turns: "none"` -- receives lens results only via message, not full conversation history
+6. **Stable INS-ids**: `INS-{8hex}` from `hash(phase_num + lens + title)` -- re-runs do not create duplicates
+7. **Archive before overwrite**: Move existing retrospective.{md,json} to `.history/` with timestamp before writing new ones
+8. **Spec learnings.md backward-compat**: Append to it only if it already exists -- never create it
+9. **Route confirmation**: Unless `-y`, present routing table and ask per-group before writing spec/issue/knowhow
+10. **Lessons always written**: Append to `lessons.jsonl` regardless of `--no-route` -- routing only controls spec/issue/knowhow creation
+</invariants>
+
+<execution>
+
+### Session Initialization
+
+Update plan: Stages 1-3 → in_progress; Stages 4-8 → pending.
+
+### Stages 1-3: Parse Mode and Validate Artifacts
+
+**Stage 1: Parse mode** from `$ARGUMENTS`:
+
+| First non-flag token | Mode |
+|---------------------|------|
+| (empty) | scan |
+| `<N>` (single digit/number) | single |
+| `<N>..<M>` | range |
+| `--all` flag present | all |
+
+Validate `--lens` values. If `--compare <M>` present, require single mode.
+
+**Stage 2: Validate phase artifacts**. For each target phase:
+- Phase directory must exist (resolved via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`)
+- `index.json` must show `status: "completed"`
+- `.task/` directory must exist with at least one `TASK-*.json`
+- If existing `retrospective.json` found and not `--all`: emit W002, prompt overwrite
+
+**Stage 3: Scan mode** -- list all completed phases without retrospective.json. Prompt user to select.
+
+Update plan: Stages 1-3 → completed; Stage 4 → in_progress.
+
+### Stage 4: Context-Agent Fork + Parallel Lens Analysis
+
+**Archive if overwriting**:
+If existing `retrospective.{md,json}` present, move to `{artifact_dir}/.history/` with timestamp suffix before spawning.
+
+**Step 4a: Spawn context agent**
+```javascript
+spawn_agent({
+  task_name: "ctx",
+  fork_turns: "none",
+  message: `Load and summarize all phase ${targetPhase} artifacts for retrospective.
+    1. Query state.json artifacts[] for phase === ${targetPhase} && milestone === current_milestone
+    2. Load per-artifact outputs (execute→index/plan/tasks/summaries, verify→verification.json, review→review.json, debug→understanding/evidence, test→uat/tests)
+    3. Filter issues.jsonl for this phase; read state.json for project context
+    EXPECTED: Goals vs outcomes, completion rates, verification/review/UAT results, issue counts, key metrics`
+})
+wait_agent({ timeout_ms: 1800000 })
+```
+
+**Step 4b: Fork 4 lens agents** (only active lenses based on `--lens` flag; default: all 4)
+
+All lenses use `fork_turns: "all"` and return the same JSON array schema:
+```json
+[{ "title": "<80 chars>", "summary": "...", "category": "pattern|antipattern|decision|tool|gotcha|technique",
+   "routing": "spec|issue|knowhow|none", "severity": "critical|high|medium|low", "evidence": "<file:line>" }]
+```
+
+| Agent | task_name | Focus |
+|-------|-----------|-------|
+| Technical | `lens-tech` | Tech debt, architecture decisions, code quality, performance, security, dependencies |
+| Process | `lens-proc` | Planning accuracy, collaboration, workflow efficiency, communication, process improvements |
+| Quality | `lens-qual` | Test coverage gaps, quality gates, UAT failures, review blockers, missing scenarios |
+| Decision | `lens-dec` | Key decisions, tradeoffs, ADR candidates, reversibility, retrospective judgment |
+
+```javascript
+// Spawn all 4 lenses in parallel
+["lens-tech", "lens-proc", "lens-qual", "lens-dec"].forEach(name =>
+  spawn_agent({ task_name: name, fork_turns: "all", message: `<lens-specific prompt>` })
+)
+const lensResults = wait_agent({ timeout_ms: 1800000 })
+
+// Close lenses first, then context agent LAST
+["lens-tech", "lens-proc", "lens-qual", "lens-dec"].forEach(n => close_agent({ target: n }))
+close_agent({ target: "ctx" })
+```
+
+If `lensResults.timed_out` for any agent: emit W001, continue with partial coverage.
+
+### Stage 5: Synthesize Insights
+
+```javascript
+spawn_agent({
+  task_name: "synthesizer",
+  fork_turns: "none",
+  message: `Merge and distill insights from 4 lens analyses.
+    Input: ${JSON.stringify(lensResults.status)}
+    1. Merge all insights, deduplicate (same issue across lenses → keep higher severity, combine evidence)
+    2. Generate stable INS-{8hex} id: hash(phase_num + lens + title)
+    3. Classify routing: spec | issue | knowhow | none
+    4. Produce phase-level metrics summary
+    EXPECTED JSON: { insights: [{id,title,summary,category,lens,routing,severity,evidence}],
+      metrics: {tasks_completed,tasks_failed,test_pass_rate,review_issues_count,uat_scenarios_passed},
+      routing_summary: {spec:N, issue:N, knowhow:N, none:N} }`
+})
+const synthResult = wait_agent({ timeout_ms: 1800000 })
+close_agent({ target: "synthesizer" })
+```
+
+Update plan: Stages 1-5 → completed; Stage 6 → in_progress.
+
+### Stage 6: Route Outputs
+
+If `--no-route`: skip this stage.
+
+For each insight in `synthResult.insights`, route based on `routing` field:
+
+**Spec routing** (`routing: "spec"`):
+Map category (pattern/convention → `coding`, architecture → `arch`, quality → `quality`). Append `<spec-entry>` with category, auto-extracted keywords, date, source="retrospective", title, summary, evidence, phase/lens/INS-id.
+
+**Issue routing** (`routing: "issue"`, severity critical/high):
+Append to `.workflow/issues/issues.jsonl` with `ISS-<date>-<seq>` id, source="retrospective", phase/INS-id context, and history entry.
+
+**Memory routing** (`routing: "knowhow"`):
+Invoke `manage-knowhow-capture` skill with tip content and `--tag retrospective,phase-{N}`.
+
+If `!AUTO_YES`: present routing table and ask confirmation before routing each group.
+
+### Stage 7: Write Artifacts
+
+Write two files to `{target_dir}/`:
+- **retrospective.json**: phase, slug, timestamp, lenses_run, metrics, findings_by_lens, distilled_insights, routing_summary
+- **retrospective.md**: Header with phase/slug/timestamp, metrics table (tasks completed, test pass rate, review issues, UAT scenarios), findings by lens, distilled insights, routing summary
+
+Append each insight to `.workflow/learning/lessons.jsonl` and update `learning-index.json`.
+
+If `.workflow/specs/learnings.md` already exists, append each insight as `<spec-entry>` (category=`learning`, auto-extract keywords, date=today, source=`retrospective`). Never create the file -- only append if it exists.
+
+Update plan: Stages 1-7 → completed; Stage 8 → in_progress.
+
+### Stage 8: Report
+
+Display summary: phase, lenses run, insight counts (new vs merged duplicates), routing breakdown (spec/issue/knowhow/lesson counts with target paths), key metrics (task completion, test pass rate, review issues).
+
+Next steps: `$manage-status`, `$manage-issue "list --source retrospective"`, `$manage-learn "list --phase <N>"`, `$manage-wiki health`, `$wiki-digest "<phase-topic>"`.
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized | parse_input |
+| E002 | error | Unknown `--lens` name | parse_input |
+| E003 | error | `--compare` requires single phase mode | parse_input |
+| E004 | error | Phase has no execution artifacts (no .task/) | load_artifacts |
+| E005 | error | Phase directory not found or phase not completed | scan_unreviewed |
+| W001 | warning | One or more lens agents timed out -- partial coverage | multi_lens_analysis |
+| W002 | warning | Existing retrospective.json found -- prompted to overwrite | scan_unreviewed |
+| W003 | warning | `manage-knowhow-capture` did not return parseable TIP id; fell back to direct write | route_outputs |
+| W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly parsed from arguments (scan/single/range/all)
+- [ ] Phase artifacts validated before analysis begins
+- [ ] Context agent loads all artifacts before lens agents spawn
+- [ ] All active lens agents spawned in parallel, waited as batch
+- [ ] Context agent closed last (after all lens agents)
+- [ ] Synthesizer produces deduplicated insights with stable INS-ids
+- [ ] Routing applied per insight (spec/issue/knowhow/none) with confirmation
+- [ ] retrospective.{md,json} written to phase directory
+- [ ] Lessons appended to lessons.jsonl regardless of --no-route flag
+- [ ] Existing retrospective archived before overwrite
+</success_criteria>

package/codex/maestro-flow/commands/quality/review.md

@@ -0,0 +1,364 @@
+---
+name: quality-review
+description: Tiered code review via CSV wave pipeline. Decomposes into 6 dimension agents running in parallel, with optional deep-dive aggregation wave. Replaces quality-review command.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--level quick|standard|deep] [--dimensions list]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Wave-based multi-dimensional code review using `spawn_agents_on_csv`. Decomposes review into independent dimension agents (Wave 1), then aggregates findings into a unified report with verdict (Wave 2).
+
+**Core workflow**: Collect Files -> Decompose Dimensions -> Parallel Review -> Aggregate + Verdict
+
+```
++---------------------------------------------------------------------------+
+|                    CODE REVIEW CSV WAVE WORKFLOW                           |
++---------------------------------------------------------------------------+
+|                                                                           |
+|  Phase 1: Phase Resolution -> CSV                                         |
+|     +-- Resolve phase directory from arguments                            |
+|     +-- Collect changed files from task summaries                         |
+|     +-- Auto-detect review level (quick/standard/deep)                    |
+|     +-- Determine active dimensions                                       |
+|     +-- Generate tasks.csv with one row per dimension                     |
+|     +-- User validates dimension breakdown (skip if -y)                   |
+|                                                                           |
+|  Phase 2: Wave Execution Engine                                           |
+|     +-- Wave 1: Dimension Review (parallel)                               |
+|     |   +-- Each dimension agent reviews all changed files                |
+|     |   +-- Agent classifies findings by severity                         |
+|     |   +-- Discoveries shared via board (patterns, conventions)          |
+|     |   +-- Results: severity_counts + top_issues per dimension           |
+|     +-- Wave 2: Aggregation + Deep-Dive (if needed)                       |
+|     |   +-- Aggregate all dimension findings                              |
+|     |   +-- If criticals > 0 (standard) or always (deep): deep-dive      |
+|     |   +-- Cross-dimension impact analysis                               |
+|     |   +-- Generate verdict: PASS / WARN / BLOCK                        |
+|     +-- discoveries.ndjson shared across all waves (append-only)          |
+|                                                                           |
+|  Phase 3: Results Aggregation                                             |
+|     +-- Export results.csv + review.json                                  |
+|     +-- Generate context.md with all findings                             |
+|     +-- Auto-create issues for qualifying findings                        |
+|     +-- Update phase index.json with review status                        |
+|     +-- Display summary with verdict + next steps                         |
+|                                                                           |
++---------------------------------------------------------------------------+
+```
+</purpose>
+
+<context>
+```bash
+$quality-review "3"
+$quality-review -c 6 "3 --level deep"
+$quality-review -y "3 --dimensions security,performance"
+$quality-review --continue "20260318-review-P3-auth"
+```
+
+**Flags**:
+- `-y, --yes`: Skip all confirmations (auto mode)
+- `-c, --concurrency N`: Max concurrent agents within each wave (default: 6)
+- `--continue`: Resume existing session
+
+When `--yes` or `-y`: Auto-confirm dimension selection, skip interactive validation, use defaults for level detection.
+
+**Output Directory**: `.workflow/.csv-wave/{session-id}/`
+**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report) + `review.json` (structured review output)
+</context>
+
+<csv_schema>
+
+### tasks.csv (Master State)
+
+```csv
+id,title,description,dimension,changed_files,project_specs,review_level,deps,context_from,wave,status,findings,severity_counts,top_issues,error
+"1","Correctness Review","Review all changed files for correctness: logic errors, missing edge cases, incorrect return values, null/undefined handling, off-by-one errors. Classify each finding as critical/high/medium/low with file:line references.","correctness","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Existing patterns use Result type for error handling","standard","","","1","","","","",""
+"2","Security Review","Review all changed files for security vulnerabilities: injection flaws, XSS, CSRF, auth bypass, sensitive data exposure, insecure crypto. Reference OWASP Top 10. Classify each finding.","security","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","Auth uses bcrypt + JWT","standard","","","1","","","","",""
+"3","Performance Review","Review all changed files for performance issues: N+1 queries, unnecessary re-renders, memory leaks, blocking operations, unoptimized algorithms.","performance","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"4","Architecture Review","Review all changed files for architecture issues: layer violations, circular dependencies, inappropriate coupling, missing abstractions, SRP violations.","architecture","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","ESM modules, strict TypeScript","standard","","","1","","","","",""
+"5","Maintainability Review","Review all changed files for maintainability: code duplication, overly complex functions, poor naming, missing types, unclear control flow.","maintainability","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"6","Best Practices Review","Review all changed files for best-practice violations: error handling gaps, missing validation, hardcoded values, deprecated API usage, inconsistent patterns.","best-practices","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","","","1","","","","",""
+"7","Aggregate + Deep-Dive","Aggregate all dimension findings. Calculate severity distribution. Determine verdict (PASS/WARN/BLOCK). If critical findings exist, perform deep-dive with cross-file impact analysis.","aggregation","src/auth/login.ts;src/auth/register.ts;src/utils/validation.ts","","standard","1;2;3;4;5;6","1;2;3;4;5;6","2","","","","",""
+```
+
+**Columns**:
+
+| Column | Phase | Description |
+|--------|-------|-------------|
+| `id` | Input | Unique task identifier (string) |
+| `title` | Input | Short task title |
+| `description` | Input | Detailed review instructions for this dimension |
+| `dimension` | Input | Review dimension: correctness/security/performance/architecture/maintainability/best-practices/aggregation |
+| `changed_files` | Input | Semicolon-separated file paths to review |
+| `project_specs` | Input | Relevant project specs/conventions context |
+| `review_level` | Input | quick/standard/deep -- controls depth |
+| `deps` | Input | Semicolon-separated dependency task IDs |
+| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
+| `wave` | Computed | Wave number (1 = dimension review, 2 = aggregation) |
+| `status` | Output | `pending` -> `completed` / `failed` / `skipped` |
+| `findings` | Output | Key review findings summary (max 500 chars) |
+| `severity_counts` | Output | JSON: `{"critical":N,"high":N,"medium":N,"low":N}` |
+| `top_issues` | Output | Top 5 issues with `[severity] description (file:line)` format |
+| `error` | Output | Error message if failed |
+
+### Per-Wave CSV (Temporary)
+
+Each wave generates `wave-{N}.csv` with extra `prev_context` column.
+
+### Output Artifacts
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `tasks.csv` | Master state -- all tasks with status/findings | Updated after each wave |
+| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
+| `results.csv` | Final export of all task results | Created in Phase 3 |
+| `discoveries.ndjson` | Shared exploration board | Append-only, carries across waves |
+| `context.md` | Human-readable review report | Created in Phase 3 |
+| `review.json` | Structured review output for downstream | Created in Phase 3 |
+
+### Session Structure
+
+```
+.workflow/.csv-wave/{YYYYMMDD}-review-P{N}-{slug}/
++-- tasks.csv
++-- results.csv
++-- discoveries.ndjson
++-- context.md
++-- review.json
++-- wave-{N}.csv (temporary)
+```
+</csv_schema>
+
+<invariants>
+1. **Start Immediately**: First action is session initialization, then Phase 1
+2. **Wave Order is Sacred**: Never execute wave 2 before wave 1 completes and results are merged
+3. **CSV is Source of Truth**: Master tasks.csv holds all state
+4. **Context Propagation**: prev_context built from master CSV, not from memory
+5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
+6. **Skip on Failure**: If all dimension agents failed, skip aggregation
+7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
+8. **DO NOT STOP**: Continuous execution until all waves complete
+</invariants>
+
+<execution>
+
+### Session Initialization
+
+Parse `$ARGUMENTS` to extract:
+- `AUTO_YES` from `--yes` / `-y`
+- `continueMode` from `--continue`
+- `maxConcurrency` from `--concurrency N` / `-c N` (default: 6)
+- `levelMatch` from `--level quick|standard|deep`
+- `dimsMatch` from `--dimensions <list>`
+- `phaseArg` = remaining text after stripping all flags
+
+Session ID: `{YYYYMMDD}-review-P{phaseArg}-{phaseSlug}` (phaseSlug from index.json or roadmap)
+Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
+
+### Phase 1: Phase Resolution -> CSV
+
+**Objective**: Resolve phase, collect changed files, determine review level, generate tasks.csv.
+
+**Decomposition Rules**:
+
+1. **Phase resolution**: Resolve `{phaseArg}` via `state.json` artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
+2. **Related session discovery**: Query `state.json.artifacts[]` for matching phase + milestone. Extract prior quality context (verdicts, root causes, UAT gaps) from artifact outputs by type (execute → .summaries/.task/, review → review.json, debug → understanding.md, test → uat.md)
+3. **File collection**: Read `.task/TASK-*.json` → collect `files[].path` where action != "read"
+4. **Level detection**:
+
+| Condition | Level |
+|-----------|-------|
+| `--level` flag provided | Use explicit level |
+| <=3 changed files | quick |
+| 4-19 changed files | standard |
+| >=20 files OR phase marked critical | deep |
+
+5. **Dimension selection**:
+
+| Level | Dimensions |
+|-------|------------|
+| quick | correctness, security |
+| standard | correctness, security, performance, architecture, maintainability, best-practices |
+| deep | all 6 + forced deep-dive in aggregation |
+
+If `--dimensions` flag provided, override with explicit list.
+
+6. **Specs loading**: Read `.workflow/specs/` for project conventions (unless `--skip-specs`)
+7. **CSV generation**: One row per dimension + one aggregation row
+
+**Wave computation**: Simple 2-wave -- all dimension tasks = wave 1, aggregation = wave 2.
+
+**User validation**: Display task breakdown (skip if AUTO_YES).
+
+### Phase 2: Wave Execution Engine
+
+**Objective**: Execute dimension reviews wave-by-wave via spawn_agents_on_csv.
+
+#### Wave 1: Dimension Reviews (Parallel)
+
+Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-1.csv` (no prev_context needed).
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,
+  id_column: "id",
+  instruction: buildReviewInstruction(sessionFolder),
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: {
+    type: "object",
+    properties: {
+      id: { type: "string" },
+      status: { type: "string", enum: ["completed", "failed"] },
+      findings: { type: "string" },
+      severity_counts: { type: "string" },
+      top_issues: { type: "string" },
+      error: { type: "string" }
+    },
+    required: ["id", "status", "findings"]
+  }
+})
+```
+
+Merge `wave-1-results.csv` into master `tasks.csv`, delete `wave-1.csv`.
+
+#### Wave 2: Aggregation + Deep-Dive
+
+Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation.
+
+Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
+Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results → delete `wave-2.csv`.
+
+### Phase 3: Results Aggregation
+
+**Objective**: Generate final results and human-readable report.
+
+Export master `tasks.csv` as `results.csv`. Build `review.json`:
+
+```json
+{
+  "phase": "<phase>",
+  "level": "<level>",
+  "verdict": "PASS|WARN|BLOCK",
+  "severity_distribution": { "critical": 0, "high": 0, "medium": 0, "low": 0 },
+  "dimensions": [
+    { "dimension": "correctness", "status": "completed", "severity_counts": {...}, "top_issues": [...] }
+  ],
+  "deep_dive": { "performed": true/false, "iterations": N, "impact_analysis": "..." },
+  "issues_created": [],
+  "timestamp": "<ISO>"
+}
+```
+
+Generate `context.md`:
+
+```markdown
+# Code Review Report -- Phase {phase}
+
+## Summary
+- Level: {level}
+- Files reviewed: {file_count}
+- Dimensions: {dimension_count}
+- Verdict: **{verdict}**
+
+## Severity Distribution
+| Severity | Count |
+|----------|-------|
+| Critical | {N} |
+| High     | {N} |
+| Medium   | {N} |
+| Low      | {N} |
+
+## Dimension Results
+### {dimension_name}
+{findings}
+
+**Top Issues:**
+{top_issues}
+
+## Deep-Dive Analysis
+{if performed: impact analysis results}
+
+## Issues Created
+{list of created issue IDs}
+```
+
+**Verdict determination**:
+
+| Condition | Verdict |
+|-----------|---------|
+| Any critical findings | BLOCK |
+| High findings > 3 | BLOCK |
+| Any high findings | WARN |
+| Medium findings > 5 | WARN |
+| Otherwise | PASS |
+
+**Issue creation** by level threshold:
+
+| Level | Create Issues For |
+|-------|------------------|
+| quick | critical only |
+| standard | critical + high |
+| deep | critical + high + medium |
+
+**Phase index update**: Update `{artifact_dir}/index.json` with review status.
+
+**Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
+
+Display summary.
+
+### Shared Discovery Board Protocol
+
+#### Standard Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `code_pattern` | `data.name` | `{name, file, description}` | Reusable code pattern found |
+| `integration_point` | `data.file` | `{file, description, exports[]}` | Module connection point |
+| `convention` | singleton | `{naming, imports, formatting}` | Project code conventions |
+| `blocker` | `data.issue` | `{issue, severity, impact}` | Blocking issue found |
+| `tech_stack` | singleton | `{framework, language, tools[]}` | Technology stack info |
+
+#### Domain Discovery Types
+
+| Type | Dedup Key | Data Schema | Description |
+|------|-----------|-------------|-------------|
+| `vulnerability` | `data.location` | `{location, type, severity, cwe}` | Security vulnerability |
+| `code_smell` | `data.location` | `{location, type, severity, description}` | Code quality issue |
+| `performance_hotspot` | `data.location` | `{location, type, impact}` | Performance issue |
+| `architecture_violation` | `data.location` | `{location, rule, description}` | Architecture rule violation |
+
+#### Protocol
+
+Read `{session_folder}/discoveries.ndjson` before own review. Deduplicate by type + dedup key before writing. Append-only — never modify or delete.
+
+```bash
+echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"src/auth/login.ts:42","type":"sql_injection","severity":"critical","cwe":"CWE-89"}}' >> {session_folder}/discoveries.ndjson
+```
+</execution>
+
+<error_codes>
+
+| Error | Resolution |
+|-------|------------|
+| Phase directory not found | Abort with error: "Phase {N} not found" |
+| No task summaries found | Abort with error: "No execution results -- run execute first" |
+| No changed files | Abort with error: "No changed files detected" |
+| Dimension agent timeout | Mark as failed, skip dependent aggregation if all failed |
+| Aggregation agent failed | Use wave 1 results directly, verdict based on raw counts |
+| CSV parse error | Validate format, show line number |
+| discoveries.ndjson corrupt | Ignore malformed lines |
+| Continue mode: no session found | List available sessions |
+</error_codes>
+
+<success_criteria>
+- [ ] Session folder created with valid tasks.csv
+- [ ] All dimension reviews executed in parallel (wave 1)
+- [ ] Aggregation + deep-dive executed (wave 2)
+- [ ] review.json produced with verdict and severity distribution
+- [ ] context.md produced with full review report
+- [ ] Issues auto-created for qualifying severity findings
+- [ ] Phase index.json updated with review status
+- [ ] discoveries.ndjson append-only throughout
+</success_criteria>