maestro-flow 0.5.36 → 0.5.37

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

@@ -13,143 +13,143 @@ allowed-tools:
 ---
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
-<purpose>
-Unified automated testing via CSV layer pipeline. Auto-selects scenario source from project state (specs / coverage gaps / code exploration), then: discover → plan → build CSV → write tests (parallel) → execute → diagnose failures (parallel) → iterate → report.
-
-Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-iter 1` = single-pass; default = full iterative cycle.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/auto-test.md
-</required_reading>
-
-<context>
-Phase or task: $ARGUMENTS (required — phase number)
-
-**Flags:**
-- `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
-- `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
-- `--dry-run` — Generate test plan only, do not execute
-- `--re-run` — Re-run only previously failed/blocked scenarios
-
-**Intelligent routing** (auto-detected from project state):
-
-| Priority | Condition | Route | Reference skill |
-|----------|-----------|-------|-----------------|
-| 1 | Active session exists (state.json status=running) | Resume | — |
-| 2 | --re-run flag + previous failures | Re-run | — |
-| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
-| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
-| 5 | Default | code | quality-integration-test (separate skill) |
-
-Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
-
-### Pre-load context (before test generation)
-
-1. **Test specs + tools**: Run `maestro spec load --category test` to load test conventions (framework, patterns, naming). Apply to all generated tests.
-2. **Coding specs**: Run `maestro spec load --category coding` to understand coding patterns for accurate test targeting.
-3. **Role Knowledge**:
-   - Browse: `maestro search --category test`
-   - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
-4. All are optional — proceed without if unavailable.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/auto-test.md' completely.
-
-### Phase Gates (MANDATORY, BLOCKING)
-
-**GATE 1: Setup → Plan** (Route Selection → CSV Generation)
-- REQUIRED: Phase resolved from artifact registry. E001/E002 if missing.
-- REQUIRED: Route auto-selected (spec/gap/code) from project state.
-- REQUIRED: Test infrastructure discovered (framework, patterns, conventions).
-- BLOCKED if missing: cannot generate test plan without route and framework.
-
-**GATE 2: Plan → Write** (CSV → Test Generation)
-- REQUIRED: test-plan.json generated with layer distribution (L0→L3).
-- REQUIRED: User confirmed plan (unless `--dry-run` stops here).
-- BLOCKED if plan missing or rejected: do not write tests.
-
-**GATE 3: Write → Execute** (Test Generation → Execution)
-- REQUIRED: All planned test files written following existing patterns.
-- REQUIRED: Tests follow RED-GREEN methodology.
-- BLOCKED if tests incomplete: finish writing before execution.
-
-**GATE 4: Execute → Report** (Iteration → Completion)
-- REQUIRED: Progressive execution completed (L0→L3, fail-fast on critical).
-- REQUIRED: Iteration engine ran (inner: test_defect fix, outer: strategy adjust).
-- REQUIRED: Confidence scored with 5-dimension factor model (>= 60%).
-- REQUIRED: Pressure pass completed on highest-pass-rate layer.
-- BLOCKED if iteration incomplete: continue iterating before reporting.
-
-**Command-specific extensions (not in workflow):**
-
-**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, suggest quality-debug
-
-**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}-auto-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:**
-- Converged (>=95%) → `/quality-review {phase}`
-- All requirements verified (spec source) → `/maestro-milestone-audit`
-- Bugs discovered → `/quality-debug --from-uat {phase}`
-- Max iter, >80% → `/quality-test {phase}` for manual UAT
-- Max iter, <80% → `/quality-debug {phase}`
-- Coverage still low → `/quality-auto-test {phase} --layer {missing}`
-- Re-run all pass → `/quality-review {phase}`
-- Single pass, all pass → `/quality-test {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required (no active sessions) | Prompt user for phase number |
-| E002 | error | Phase not found in artifact registry | Check state.json artifacts |
-| E003 | error | No test framework detected | Install test framework or configure test runner |
-| W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
-| W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
-| W003 | warning | Degraded spec mode (no full spec package) | Consider running maestro-roadmap --mode full |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved from artifact registry
-- [ ] Route auto-selected from project state (spec/gap/code)
-- [ ] Active sessions checked, resume offered if applicable
-- [ ] Scenarios extracted and normalized to unified format
-- [ ] Test infrastructure discovered (framework, patterns, conventions)
-- [ ] test-plan.json generated with layer distribution
-- [ ] User confirmed plan (or --dry-run stopped here)
-- [ ] Tests written following RED-GREEN methodology and existing patterns
-- [ ] Tests executed progressively (L0→L3) with fail-fast on critical
-- [ ] Iteration engine ran (inner: test_defect fix, outer: strategy adjust)
-- [ ] state.json, report.json, reflection-log.md written
-- [ ] Test confidence scored per iteration (Step 7.5) with 5-dimension factor model
-- [ ] Convergence check includes confidence >= 60% alongside pass_rate threshold
-- [ ] Pressure pass completed on highest-pass-rate layer before completion
-- [ ] report.json includes confidence section
-- [ ] index.json updated with auto_test section
-- [ ] If spec source: traceability matrix built, traceability.md written
-- [ ] If failures: issues auto-created in issues.jsonl
-- [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
-- [ ] Next step routed based on convergence status
-</success_criteria>
+<purpose>
+Unified automated testing via CSV layer pipeline. Auto-selects scenario source from project state (specs / coverage gaps / code exploration), then: discover → plan → build CSV → write tests (parallel) → execute → diagnose failures (parallel) → iterate → report.
+
+Layers L0→L3 sequential (fail-fast), scenarios within layer parallel. `--max-iter 1` = single-pass; default = full iterative cycle.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/auto-test.md
+</required_reading>
+
+<context>
+Phase or task: $ARGUMENTS (required — phase number)
+
+**Flags:**
+- `--max-iter N` — Maximum outer iterations (default: 5). Set to 1 for single-pass generation only.
+- `--layer L` — Start from or restrict to specific layer (L0|L1|L2|L3)
+- `--dry-run` — Generate test plan only, do not execute
+- `--re-run` — Re-run only previously failed/blocked scenarios
+
+**Intelligent routing** (auto-detected from project state):
+
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
+| 1 | Active session exists (state.json status=running) | Resume | — |
+| 2 | --re-run flag + previous failures | Re-run | — |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
+
+Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
+
+### Pre-load context (before test generation)
+
+1. **Test specs + tools**: Run `maestro load --type spec --category test` to load test conventions (framework, patterns, naming). Apply to all generated tests.
+2. **Coding specs**: Run `maestro load --type spec --category coding` to understand coding patterns for accurate test targeting.
+3. **Role Knowledge**:
+   - Browse: `maestro search --category test`
+   - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
+4. All are optional — proceed without if unavailable.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/auto-test.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Plan** (Route Selection → CSV Generation)
+- REQUIRED: Phase resolved from artifact registry. E001/E002 if missing.
+- REQUIRED: Route auto-selected (spec/gap/code) from project state.
+- REQUIRED: Test infrastructure discovered (framework, patterns, conventions).
+- BLOCKED if missing: cannot generate test plan without route and framework.
+
+**GATE 2: Plan → Write** (CSV → Test Generation)
+- REQUIRED: test-plan.json generated with layer distribution (L0→L3).
+- REQUIRED: User confirmed plan (unless `--dry-run` stops here).
+- BLOCKED if plan missing or rejected: do not write tests.
+
+**GATE 3: Write → Execute** (Test Generation → Execution)
+- REQUIRED: All planned test files written following existing patterns.
+- REQUIRED: Tests follow RED-GREEN methodology.
+- BLOCKED if tests incomplete: finish writing before execution.
+
+**GATE 4: Execute → Report** (Iteration → Completion)
+- REQUIRED: Progressive execution completed (L0→L3, fail-fast on critical).
+- REQUIRED: Iteration engine ran (inner: test_defect fix, outer: strategy adjust).
+- REQUIRED: Confidence scored with 5-dimension factor model (>= 60%).
+- REQUIRED: Pressure pass completed on highest-pass-rate layer.
+- BLOCKED if iteration incomplete: continue iterating before reporting.
+
+**Command-specific extensions (not in workflow):**
+
+**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, suggest quality-debug
+
+**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}-auto-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:**
+- Converged (>=95%) → `/quality-review {phase}`
+- All requirements verified (spec source) → `/maestro-milestone-audit`
+- Bugs discovered → `/quality-debug --from-uat {phase}`
+- Max iter, >80% → `/quality-test {phase}` for manual UAT
+- Max iter, <80% → `/quality-debug {phase}`
+- Coverage still low → `/quality-auto-test {phase} --layer {missing}`
+- Re-run all pass → `/quality-review {phase}`
+- Single pass, all pass → `/quality-test {phase}`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required (no active sessions) | Prompt user for phase number |
+| E002 | error | Phase not found in artifact registry | Check state.json artifacts |
+| E003 | error | No test framework detected | Install test framework or configure test runner |
+| W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
+| W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
+| W003 | warning | Degraded spec mode (no full spec package) | Consider running maestro-roadmap --mode full |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved from artifact registry
+- [ ] Route auto-selected from project state (spec/gap/code)
+- [ ] Active sessions checked, resume offered if applicable
+- [ ] Scenarios extracted and normalized to unified format
+- [ ] Test infrastructure discovered (framework, patterns, conventions)
+- [ ] test-plan.json generated with layer distribution
+- [ ] User confirmed plan (or --dry-run stopped here)
+- [ ] Tests written following RED-GREEN methodology and existing patterns
+- [ ] Tests executed progressively (L0→L3) with fail-fast on critical
+- [ ] Iteration engine ran (inner: test_defect fix, outer: strategy adjust)
+- [ ] state.json, report.json, reflection-log.md written
+- [ ] Test confidence scored per iteration (Step 7.5) with 5-dimension factor model
+- [ ] Convergence check includes confidence >= 60% alongside pass_rate threshold
+- [ ] Pressure pass completed on highest-pass-rate layer before completion
+- [ ] report.json includes confidence section
+- [ ] index.json updated with auto_test section
+- [ ] If spec source: traceability matrix built, traceability.md written
+- [ ] If failures: issues auto-created in issues.jsonl
+- [ ] If gap source: validation.json gaps updated (MISSING→COVERED)
+- [ ] Next step routed based on convergence status
+</success_criteria>

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

@@ -14,148 +14,148 @@ allowed-tools:
 ---
 <!-- 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/
-
-### Pre-load (optional, proceed without)
-- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
-- Wiki: `maestro search "<symptom keywords>" --json` → prior investigations
-- Specs: `maestro spec load --category debug --keyword "<symptom>"` → known issues/workarounds
-- Role knowledge: `maestro search --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.
-
-### Phase Gates (MANDATORY, BLOCKING)
-
-**GATE 1: Input → Investigation**
-- REQUIRED: Symptoms gathered (interactive) or loaded from UAT (--from-uat).
-- REQUIRED: Debug output directory created.
-- BLOCKED if missing: cannot investigate without symptom baseline.
-
-**GATE 2: Investigation → Diagnosis**
-- REQUIRED: Debug agent(s) spawned with full symptom context.
-- REQUIRED: evidence.ndjson written with structured entries.
-- REQUIRED: understanding.md tracks evolving understanding.
-- BLOCKED if incomplete: continue investigation before declaring root cause.
-
-**GATE 3: Diagnosis → Completion**
-- REQUIRED: Root causes collected with fix_direction and affected_files.
-- REQUIRED: Multi-factor confidence scored per gap.
-- REQUIRED: Readiness gate checked and pressure pass completed.
-- BLOCKED if inconclusive: resume session or escalate.
-
-**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> --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 |
-|-----------|-----------|
-| 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) |
-| Standalone fix already applied | `/maestro-execute {phase}` |
-</completion>
-
-<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>
+<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/
+
+### Pre-load (optional, proceed without)
+- Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → module boundaries
+- Wiki: `maestro search "<symptom keywords>" --json` → prior investigations
+- Specs: `maestro load --type spec --category debug --keyword "<symptom>"` → known issues/workarounds
+- Role knowledge: `maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
+
+**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.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Input → Investigation**
+- REQUIRED: Symptoms gathered (interactive) or loaded from UAT (--from-uat).
+- REQUIRED: Debug output directory created.
+- BLOCKED if missing: cannot investigate without symptom baseline.
+
+**GATE 2: Investigation → Diagnosis**
+- REQUIRED: Debug agent(s) spawned with full symptom context.
+- REQUIRED: evidence.ndjson written with structured entries.
+- REQUIRED: understanding.md tracks evolving understanding.
+- BLOCKED if incomplete: continue investigation before declaring root cause.
+
+**GATE 3: Diagnosis → Completion**
+- REQUIRED: Root causes collected with fix_direction and affected_files.
+- REQUIRED: Multi-factor confidence scored per gap.
+- REQUIRED: Readiness gate checked and pressure pass completed.
+- BLOCKED if inconclusive: resume session or escalate.
+
+**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> --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 |
+|-----------|-----------|
+| 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) |
+| Standalone fix already applied | `/maestro-execute {phase}` |
+</completion>
+
+<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>