maestro-flow 0.5.2 → 0.5.31

package/.agy/skills/quality-refactor/SKILL.md

@@ -14,56 +14,94 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Plan and execute targeted refactoring with safety guarantees through analysis, planning, and reflection-driven iteration. Identifies affected files and dependencies, creates a refactoring plan, confirms with the user before execution, then applies changes with test verification after every modification to ensure zero regressions. Each refactoring round records strategy, outcome, and adjustments in reflection-log.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/refactor.md
-</required_reading>
-
-<context>
-Scope: $ARGUMENTS (required)
-- Module path: "src/auth" - specific directory
-- Feature area: "authentication" - conceptual scope
-- "all" - full codebase scan
-
-If not provided, prompt user for scope.
-
-### Pre-load context (before refactoring)
-
-1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
-2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
-3. **Role Knowledge**:
-   - Browse: `maestro search --category coding`
-   - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
-4. All are optional — proceed without if unavailable.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/refactor.md' completely.
-
-**Knowledge inquiry on completion:**
-After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes, persist via `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
-
-**Next-step routing on completion:**
-- All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
-- No test suite available → `/quality-auto-test {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
-| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
-| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
-</error_codes>
-
-<success_criteria>
-- [ ] Refactoring plan created and confirmed by user
-- [ ] Changes implemented according to plan
-- [ ] All tests pass after refactoring
-- [ ] No regressions introduced
-- [ ] reflection-log.md written with strategy and outcomes
-</success_criteria>
+<purpose>
+Targeted refactoring with safety guarantees: plan → confirm → execute with test verification per change → reflection-log.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/refactor.md
+</required_reading>
+
+<context>
+Scope: $ARGUMENTS (required)
+- Module path: "src/auth" - specific directory
+- Feature area: "authentication" - conceptual scope
+- "all" - full codebase scan
+
+If not provided, prompt user for scope.
+
+### Pre-load context (before refactoring)
+
+1. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Apply conventions to all refactored code.
+2. **Review specs**: Run `maestro spec load --category review` to load review standards. Use as quality gate for refactored code.
+3. **Role Knowledge**:
+   - Browse: `maestro search --category coding`
+   - Identify task-relevant entries, then load: `maestro wiki load <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/refactor.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Analysis → Plan**
+- REQUIRED: Affected files and dependencies identified.
+- REQUIRED: Refactoring plan created with specific changes.
+- BLOCKED if missing: cannot refactor without identified targets.
+
+**GATE 2: Plan → Execution**
+- REQUIRED: User confirmed refactoring plan.
+- BLOCKED if not confirmed: do not apply changes without approval.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All changes applied with test verification per modification.
+- REQUIRED: Zero regressions (all tests pass).
+- REQUIRED: reflection-log.md written with strategy and outcomes.
+- BLOCKED if tests fail: fix regressions before completing.
+
+**Knowledge inquiry on completion:**
+After successful refactoring, ask user once: "Record refactoring pattern as coding convention?" If yes → `Skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tests pass | `/quality-sync` (update codebase docs) |
+| Test failures after refactor | `/quality-debug "test failures after refactor in {scope}"` |
+| No test suite available | `/quality-auto-test {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Refactoring scope/description required | Prompt user for module path, feature area, or "all" |
+| E002 | error | Test suite not available for affected area | Suggest creating tests first, or proceed with manual verification |
+| W001 | warning | Partial test coverage for affected area | Note uncovered areas, proceed with extra caution |
+</error_codes>
+
+<success_criteria>
+- [ ] Refactoring plan created and confirmed by user
+- [ ] Changes implemented according to plan
+- [ ] All tests pass after refactoring
+- [ ] No regressions introduced
+- [ ] reflection-log.md written with strategy and outcomes
+</success_criteria>

package/.agy/skills/quality-retrospective/SKILL.md

@@ -14,66 +14,112 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/retrospective.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
-- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
-- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
-2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
-3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-knowhow-capture tip` for note routing** — do not duplicate the learning pipeline; invoke via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`.
-5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
-6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
-7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
-| E003 | error | `--compare` requires a single phase argument | parse_input |
-| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
-| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
-| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
-| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS 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 resolved (scan / single / range / all)
-- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
-- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
-- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
-- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
-- [ ] Each insight has a stable `INS-{8hex}` id
-- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
-- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
-- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`
-- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
-- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
-- [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-knowhow list` to browse the knowhow library
-</success_criteria>
+<purpose>
+Post-execution retrospective (复盘): four parallel lenses (technical/process/quality/decision) → distill insights → route to spec/knowhow/issue stores.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/retrospective.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
+- @~/.maestro/workflows/learn.md (tip routing via manage-knowhow-capture tip)
+- @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
+- @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+Modes (scan/single/range/all), flags (--lens, --no-route, --compare, -y), and storage paths defined in workflow retrospective.md Argument Shape and Stages 1-7.
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Input → Lens Analysis** (Stages 1-3 → Stage 4)
+- REQUIRED: Mode resolved (scan/single/range/all) and phases validated.
+- REQUIRED: At least one phase selected with status=completed and existing artifacts.
+- REQUIRED: Read-only — no file writes in Stages 1-3.
+- BLOCKED if no valid phases: E004/E005.
+
+**GATE 2: Lens Analysis → Routing** (Stages 4-5 → Stage 6)
+- REQUIRED: All requested lens agents returned valid JSON (or W001 logged for partial).
+- REQUIRED: Insights distilled with stable `INS-{8hex}` IDs.
+- REQUIRED: Archive existing `retrospective.{md,json}` before overwrite.
+- BLOCKED if all lens agents failed: cannot synthesize without results.
+
+**GATE 3: Routing → Completion** (Stage 6 → Stages 7-8)
+- REQUIRED: `retrospective.json` written with metrics, findings, insights, routing.
+- REQUIRED: `retrospective.md` written (human-readable).
+- REQUIRED: Issue rows match canonical `issues.jsonl` schema (status "open", full fields).
+- REQUIRED: Note tips routed via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`.
+- BLOCKED if routing incomplete: finish all write operations before reporting.
+
+### Execution Constraints
+
+- **Parallel lens dispatch**: Stage 4 spawns one Agent per active lens in a single message.
+- **Stable IDs**: `INS-{8 hex}` from `hash(phase_num + lens + title)` — re-runs do not duplicate.
+- **No source modification**: Never modify verification.json, review.json, plan.json.
+- **Backward-compat**: Append to `.workflow/specs/learnings.md` only if file already exists.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
+| E003 | error | `--compare` requires a single phase argument | parse_input |
+| E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
+| E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
+| W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
+| W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
+| W003 | warning | `manage-knowhow-capture tip` did not return parseable INS 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 resolved (scan / single / range / all)
+- [ ] At least one phase selected and validated (status == "completed", artifacts exist)
+- [ ] All requested lens agents returned valid JSON, or W001 logged for partial coverage
+- [ ] `retrospective.json` written with metrics, findings_by_lens, distilled_insights, routing_recommendations
+- [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
+- [ ] Each insight has a stable `INS-{8hex}` id
+- [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
+- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
+- [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
+- [ ] Note tips (if any) created via `view_file(AbsolutePath="<agy-skills-dir>/manage-knowhow-capture/SKILL.md") + execute inline (args: "tip ...")`
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
+- [ ] Confirmation banner displays routing counts and next-step suggestions
+</success_criteria>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Insights routed | `/manage-status` |
+| Issues created | `/manage-issue list --source retrospective` |
+| Knowhow captured | `/manage-knowhow list` |
+| More phases to review | `/quality-retrospective --all` |
+</completion>

package/.agy/skills/quality-review/SKILL.md

@@ -14,117 +14,144 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<purpose>
-Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-execute's built-in verification ("is the goal met?") and quality-test ("does it work for users?"). Three review levels (quick/standard/deep) scale with task depth, auto-detected from file count. Level definitions, dimension lists, deep-dive rules, and issue creation thresholds defined in workflow review.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/review.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required — phase number or slug)
-
-**Flags:**
-- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
-- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
-- `--skip-specs` — Skip loading project specs as review context
-
-**All context 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** → .summaries/, .task/, verification.json, plan.json (source of files to review)
-- **review** → review.json (prior verdict, findings — for delta comparison)
-- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
-- **test** → uat.md, .tests/ (user-observable gaps)
-
-Extract conclusions from related artifacts that may affect this review. Pass as prior quality context to reviewer agents — avoid redundant work, focus on gaps and regressions.
-
-### Pre-load (optional, proceed without)
-- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
-- Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
-- Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
-- Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
-
-**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/review.md' completely.
-
-**Output writes to REVIEW_DIR** (not EXEC_DIR):
-- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
-
-**Register artifact on completion:**
-```
-Append to state.json.artifacts[]:
-{
-  id: nextArtifactId(artifacts, "review"),  // REV-001
-  type: "review",
-  milestone: current_milestone,
-  phase: target_phase,
-  scope: "phase",
-  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
-  status: "completed",
-  depends_on: exec_art.id,                 // or prior debug/review if re-review
-  harvested: false,
-  created_at: start_time,
-  completed_at: now()
-}
-```
-
-Report format and next-step routing by verdict defined in workflow review.md Report Format and Next Step Routing sections.
-
-**Next-step routing summary:**
-- PASS → `/quality-test {phase}`
-- WARN → `/quality-test {phase}` (proceed with caveats)
-- BLOCK → `/maestro-plan {phase} --gaps` (fix critical findings first)
-
-**Completion status:**
-```
---- COMPLETION STATUS ---
-STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
-CONCERNS: {description if applicable}
-NEXT: /quality-refactor
---- END STATUS ---
-```
-
-Status mapping:
-- **DONE** — PASS verdict, no critical findings → NEXT: /quality-refactor
-- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking → NEXT: /quality-test
-- **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | No execution results found (no task summaries) | Verify execution completed with task summaries |
-| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
-| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
-| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and changed files collected from task summaries
-- [ ] Review level determined (explicit flag or auto-detected)
-- [ ] Project specs loaded as review context (unless --skip-specs)
-- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
-- [ ] All dimension results aggregated with severity classification
-- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
-- [ ] review.json written with complete findings, severity distribution, verdict
-- [ ] Issues auto-created based on level thresholds
-- [ ] index.json updated with review status
-- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
-</success_criteria>
+<purpose>
+Multi-dimensional code review on a phase's changed files. Three levels (quick/standard/deep), auto-detected from file count. Level and dimension details in workflow review.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required — phase number or slug)
+
+**Flags:**
+- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
+- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
+- `--skip-specs` — Skip loading project specs as review context
+
+**All context 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** → .summaries/, .task/, verification.json, plan.json (source of files to review)
+- **review** → review.json (prior verdict, findings — for delta comparison)
+- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
+- **test** → uat.md, .tests/ (user-observable gaps)
+
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
+- Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
+- Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
+- Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
+
+**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/review.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Review**
+- REQUIRED: Phase resolved and changed files collected from task summaries. E001/E002 if missing.
+- REQUIRED: Review level determined (explicit flag or auto-detected from file count).
+- BLOCKED if no changed files: E004.
+
+**GATE 2: Review → Aggregation**
+- REQUIRED: All dimension reviews executed (inline for quick, parallel agents for standard/deep).
+- REQUIRED: Deep-dive completed if triggered (standard: auto, deep: forced).
+
+**GATE 3: Aggregation → Completion**
+- REQUIRED: review.json written with findings, severity distribution, and verdict.
+- REQUIRED: Issues auto-created based on level thresholds.
+- REQUIRED: index.json updated with review status.
+
+**Output writes to REVIEW_DIR** (not EXEC_DIR):
+- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // REV-001
+  type: "review",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
+  status: "completed",
+  depends_on: exec_art.id,                 // or prior debug/review if re-review
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+Report format defined in workflow review.md Report Format section.
+</execution>
+
+<completion>
+### Standalone report
+
+```
+--- COMPLETION STATUS ---
+STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY
+CONCERNS: {description if applicable}
+--- END STATUS ---
+```
+
+Status mapping:
+- **DONE** — PASS verdict, no critical findings
+- **DONE_WITH_CONCERNS** — WARN verdict, issues found but non-blocking
+- **NEEDS_RETRY** — BLOCK verdict, critical findings require fix first
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| PASS verdict | `/quality-test {phase}` |
+| WARN verdict (non-blocking issues) | `/quality-test {phase}` (proceed with caveats) |
+| BLOCK verdict (critical findings) | `/maestro-plan {phase} --gaps` (fix first) |
+| Want code cleanup | `/quality-refactor {phase}` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | No execution results found (no task summaries) | Verify execution completed with task summaries |
+| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
+| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
+| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved and changed files collected from task summaries
+- [ ] Review level determined (explicit flag or auto-detected)
+- [ ] Project specs loaded as review context (unless --skip-specs)
+- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
+- [ ] All dimension results aggregated with severity classification
+- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
+- [ ] review.json written with complete findings, severity distribution, verdict
+- [ ] Issues auto-created based on level thresholds
+- [ ] index.json updated with review status
+- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
+</success_criteria>