maestro-flow 0.4.10 → 0.4.12

package/.agents/skills/quality-debug/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: quality-debug
+description: Use when bugs, test failures, or unexpected behavior need systematic root cause investigation
+argument-hint: "[issue description] [--from-uat <phase>] [--parallel]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Debug issues using scientific method with subagent isolation and persistent debug state. Three entry modes (standalone, from-UAT, parallel) and structured root cause collection with UAT feedback loop. Full algorithm defined in workflow debug.md.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/debug.md
+</required_reading>
+
+<context>
+User's issue: $ARGUMENTS
+
+**Flags:**
+- `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
+- `--parallel` -- Spawn parallel debug agents (one per gap cluster)
+
+**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/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
+
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
+- Wiki: `maestro wiki search "<symptom keywords>" --json` → prior investigations
+- Specs: `maestro spec load --category debug --keyword "<symptom>"` → known issues/workarounds
+- Role knowledge: `maestro wiki list --category debug` → select relevant → `maestro wiki load`
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone). Output directory rules defined in workflow debug.md Step 4.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/debug.md' completely.
+
+**Register artifact on completion (phase-scoped only):**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "debug"),  // DBG-001
+  type: "debug",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-debug-P{N}-{slug}",
+  status: all_diagnosed ? "completed" : "failed",
+  depends_on: triggering_review_id || exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+### Post-debug Knowledge Inquiry
+
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Recurring root cause pattern (seen in prior debug) | "Document in debug-notes.md?" | spec-add debug |
+| Non-obvious fix / workaround | "Record as learning?" | spec-add learning |
+| Root cause = architectural boundary violation | "Update architecture-constraints.md?" | spec-add arch |
+
+On confirm → `invoke_skill("spec-add", "<category> <content>")`.
+
+**Next-step routing on completion:**
+- Root cause found, fix needed → `/maestro-plan {phase} --gaps`
+- Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
+- Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
+- Standalone fix already applied → `/maestro-verify {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Issue description required (no arguments, no active sessions) | Check arguments format, re-run with correct input |
+| E002 | error | UAT file not found for --from-uat phase | Verify UAT file exists for specified phase |
+| W001 | warning | Existing debug session found, offer resume | Review existing sessions, choose resume or new |
+| W002 | warning | Checkpoint reached, user input needed | Provide requested input to continue |
+| W003 | warning | Some gaps inconclusive, partial diagnosis | Review partial results, retry inconclusive gaps |
+</error_codes>
+
+<success_criteria>
+- [ ] Input parsed: standalone, --from-uat, or --parallel mode determined
+- [ ] Active sessions checked and resume offered if applicable
+- [ ] Symptoms gathered (interactive) or loaded from UAT (pre-filled)
+- [ ] Debug output directory created (phase .debug/ or scratch/)
+- [ ] Debug agent(s) spawned with full symptom context
+- [ ] If --parallel: one agent per gap cluster, all concurrent
+- [ ] evidence.ndjson written with structured NDJSON entries
+- [ ] understanding.md tracks evolving understanding per cluster
+- [ ] Root causes collected with fix_direction and affected_files
+- [ ] Multi-factor confidence scored per gap (Step 7.0) replacing simple high/medium/low
+- [ ] Readiness gate checked before ROOT CAUSE declaration
+- [ ] Pressure pass completed on confirmed hypothesis
+- [ ] Confidence table appended to understanding.md
+- [ ] If --from-uat: uat.md gaps updated with diagnosis artifacts
+- [ ] Results unified into diagnosis summary with confidence section
+- [ ] Next step routed (plan --gaps + execute if fix needed, verify if fix applied, resume if inconclusive)
+</success_criteria>

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

@@ -0,0 +1,69 @@
+---
+name: quality-refactor
+description: Use when accumulated tech debt needs systematic identification and safe reduction
+argument-hint: "[<scope>]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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 wiki list --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 `invoke_skill("spec-add", "coding \"<title>\" \"<pattern>\" --keywords <kw1>,<kw2>")`.
+
+**Next-step routing on completion:**
+- All tests pass → `/quality-sync` (update codebase docs)
+- Test failures after refactor → `/quality-debug {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>

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

@@ -0,0 +1,79 @@
+---
+name: quality-retrospective
+description: Use after completing a phase to extract lessons, patterns, and improvement opportunities
+argument-hint: "[phase|N..M] [--lens technical|process|quality|decision] [--all] [--no-route] [--compare N] [-y]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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/knowhow/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-learn 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-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `invoke_skill({ skill: "manage-learn", 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-learn 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 `invoke_skill({ skill: "manage-learn", args: "tip ..." })`
+- [ ] `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-learn list` to browse the knowhow library
+</success_criteria>

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

@@ -0,0 +1,130 @@
+---
+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_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" -- complementing maestro-verify ("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 wiki search "architecture constraint" --json` → documented decisions
+- Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
+- Role knowledge: `maestro wiki list --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: /maestro-verify
+- **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>

package/.agents/skills/quality-sync/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: quality-sync
+description: Sync codebase docs by tracing git diff impact
+argument-hint: "[--full] [--since <commit|HEAD~N>] [--dry-run]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<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)
+</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>

package/.agents/skills/quality-test/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: quality-test
+description: Use when implementation needs user acceptance testing with interactive verification and gap closure
+argument-hint: "[phase] [--smoke] [--auto-fix]"
+allowed-tools:
+  - read_file
+  - write_file
+  - edit_file
+  - shell
+  - find_files
+  - search
+  - delegate_subagent
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+<purpose>
+Run UAT-style conversational testing for a completed phase. Designs test scenarios from verification criteria, walks through each scenario interactively one at a time with plain text responses, and records pass/fail results with severity inference.
+
+When issues are found, spawns parallel debug agents (one per gap cluster) to diagnose root causes, then optionally triggers the gap-fix loop (plan --gaps -> execute -> re-verify) to auto-close gaps.
+
+Key mechanisms from GSD verify-work:
+- **Session persistence**: uat.md survives context resets, resume from any point
+- **Severity inference**: Natural language -> blocker/major/minor/cosmetic (never ask)
+- **Cold-start smoke tests**: --smoke flag injects basic sanity tests before UAT
+- **Parallel auto-diagnosis**: Spawn debug agents per gap cluster with pre-filled symptoms
+- **Gap-plan closure loop**: --auto-fix triggers verify -> plan --gaps -> execute -> re-verify
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/test.md
+</required_reading>
+
+<context>
+Phase or task: $ARGUMENTS (optional)
+
+Flags, artifact context resolution, and output directory format defined in workflow test.md.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/test.md' completely.
+
+**Command-specific extensions (not in workflow):**
+
+**Knowledge context loading** (before test design):
+- Wiki search: `maestro wiki search "<phase/feature keywords>" --json` → prior test strategies, recipes, decisions
+- Role knowledge: `maestro wiki list --category test` → select relevant → `maestro wiki load <id>`
+- Specs + tools: `maestro spec load --category test` → test conventions + discoverable knowhow tools
+
+**Test tool discovery** (knowhow tools as scenario source):
+- Load registered test tools: `maestro spec load --category test --keyword <feature>`
+- If tools found, extract their steps as additional test scenarios marked `source: "tool"`
+- Each numbered step in a tool becomes a UAT test with its assertion as `expected` behavior
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
+**Next-step routing on completion:**
+- All tests pass → `/maestro-milestone-audit`
+- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
+- Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
+- Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
+- Coverage below threshold → `/quality-auto-test {phase}`
+- Need integration tests → `/quality-auto-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase or task target required (no active sessions) | Prompt user for phase number |
+| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-verify` first |
+| E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
+| W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
+| W002 | warning | Coverage below threshold | Suggest `/quality-auto-test` |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved (phase or scratch task)
+- [ ] Active sessions checked, resume offered if applicable
+- [ ] Smoke tests run if --smoke flag set
+- [ ] test-plan.json generated with categorized tests mapped to requirements
+- [ ] uat.md created/resumed with all tests
+- [ ] Tests presented one at a time with expected behavior
+- [ ] User responses processed as pass/issue/skip
+- [ ] Severity inferred from natural language (never asked)
+- [ ] Batched writes: on issue, every 5 passes, or completion
+- [ ] test-results.json and coverage-report.json written
+- [ ] UAT confidence scored with 4-dimension factor model
+- [ ] Readiness gate checked before final report
+- [ ] Pressure pass completed if > 80% pass rate
+- [ ] Confidence summary appended to uat.md
+- [ ] index.json uat fields updated
+- [ ] If issues: parallel debug agents spawned per gap cluster
+- [ ] Gaps updated with root_cause, fix_direction, affected_files
+- [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
+- [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)
+</success_criteria>