maestro-flow 0.5.3 → 0.5.31

package/.claude/commands/quality-review.md

@@ -1,128 +1,155 @@
----
-name: quality-review
-description: Use after execution to evaluate code quality across correctness, security, performance, and architecture
-argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<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>
+---
+name: quality-review
+description: Use after execution to evaluate code quality across correctness, security, performance, and architecture
+argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<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>

package/.claude/commands/quality-sync.md

@@ -1,52 +1,88 @@
----
-name: quality-sync
-description: Sync codebase docs by tracing git diff impact
-argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Synchronize project state after manual code changes or to refresh codebase documentation. Detects changes via git diff, traces impact through doc-index.json (file -> component -> feature -> requirement), updates state.json and index.json, and refreshes affected `.workflow/codebase/` documentation. Use --full flag for a complete resync of all tracked files regardless of git diff.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/sync.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags:
-- `--full` -- Complete resync of all tracked files (ignores git diff, rebuilds all docs)
-- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
-- `--dry-run` -- Show what would be updated without writing changes
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/sync.md' completely.
-
-**Next-step routing on completion:**
-- Docs refreshed → `/manage-status`
-- Major structural changes detected → `/manage-codebase-rebuild` (full rebuild recommended)
-- Incremental refresh (replaces former `/manage-codebase-refresh`) → use `--since` flag
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Suggest running `/maestro-init` first|
-| W001 | warning | No changes detected since last sync | Report clean state, skip updates |
-</error_codes>
-
-<success_criteria>
-- [ ] state.json updated with current sync timestamp
-- [ ] Codebase docs refreshed for all affected components
-- [ ] doc-index.json reflects current file state
-- [ ] Changes tracked and logged
-- [ ] project.md Tech Stack section refreshed if dependency manifests changed
-</success_criteria>
+---
+name: quality-sync
+description: Sync codebase docs by tracing git diff impact
+argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Sync codebase docs after code changes: git diff → trace impact via doc-index.json → refresh `.workflow/codebase/` docs.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/sync.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- optional flags:
+- `--full` -- Complete resync of all tracked files (ignores git diff, rebuilds all docs)
+- `--since <commit|HEAD~N>` -- Diff since specific commit (default: last sync timestamp)
+- `--dry-run` -- Show what would be updated without writing changes
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/sync.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Diff → Impact Trace**
+- REQUIRED: Git diff computed (or --full flag set for all files).
+- BLOCKED if no diff and no --full: nothing to sync (W001).
+
+**GATE 2: Impact Trace → Refresh**
+- REQUIRED: Affected components traced via doc-index.json.
+- BLOCKED if trace fails: cannot refresh docs without impact mapping.
+
+**GATE 3: Refresh → Completion**
+- REQUIRED: `.workflow/codebase/` docs refreshed for affected components.
+- REQUIRED: state.json updated with sync timestamp.
+- BLOCKED if missing: do not report completion without updated docs.
+</execution>
+
+<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 |
+|-----------|-----------|
+| Docs refreshed | `/manage-status` |
+| Major structural changes | `/manage-codebase-rebuild` |
+| Incremental refresh | Use `--since` flag |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/ not initialized | Suggest running `/maestro-init` first|
+| W001 | warning | No changes detected since last sync | Report clean state, skip updates |
+</error_codes>
+
+<success_criteria>
+- [ ] state.json updated with current sync timestamp
+- [ ] Codebase docs refreshed for all affected components
+- [ ] doc-index.json reflects current file state
+- [ ] Changes tracked and logged
+- [ ] project.md Tech Stack section refreshed if dependency manifests changed
+</success_criteria>