maestro-flow 0.3.32 → 0.3.34

package/.claude/commands/quality-business-test.md

@@ -1,110 +0,0 @@
----
-name: quality-business-test
-description: PRD-forward business testing with requirement traceability, fixture generation, and multi-layer execution
-argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Validate built features against PRD acceptance criteria through automated multi-layer business testing. Unlike quality-test (interactive UAT from code gaps) and quality-test-gen (generate tests from coverage gaps), this command starts from REQ-*.md acceptance criteria and works forward to verify business rules are satisfied.
-
-Key mechanisms:
-- **PRD-forward extraction**: Parse REQ-*.md acceptance criteria with RFC 2119 priority mapping
-- **Three-tier fixture generation**: Schema-derived (valid/invalid/boundary), criteria-derived (expected outcomes), scenario-derived (multi-entity packs)
-- **Progressive L1-L3 layers**: Interface Contract -> Business Rule -> Business Scenario (fail-fast on critical)
-- **Generator-Critic loop**: Max 3 iterations per layer to distinguish test defects from code defects
-- **Requirement traceability**: Every failure traces back to REQ-NNN:AC-N
-- **Degraded mode**: Falls back to success_criteria + plan.json when no spec package exists
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/business-test.md
-</required_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number)
-
-**Flags:**
-- `--spec SPEC-xxx` -- Explicit spec reference (default: auto-detect from index.json.spec_ref)
-- `--layer L1|L2|L3` -- Run only specific layer (default: progressive L1->L2->L3)
-- `--gen-code` -- Generate framework-specific test classes (JUnit/RestAssured, supertest/vitest, pytest/httpx)
-- `--dry-run` -- Extract scenarios and fixtures only, don't execute
-- `--re-run` -- Re-run only previously failed/blocked scenarios
-- `-y` -- Skip interactive confirmations
-
-**Layer definitions:**
-
-| Layer | Name | Tests | Source |
-|-------|------|-------|--------|
-| L1 | Interface Contract | Single endpoint request/response, input validation, schema compliance | Architecture API endpoints + REQ AC |
-| L2 | Business Rule | Multi-step logic, state transitions, business constraints, edge cases | REQ acceptance criteria + NFR |
-| L3 | Business Scenario | Full user flows, multi-service chains, error propagation | Epic user stories |
-
-**Priority mapping (RFC 2119):**
-
-| Keyword | Priority | Failure = |
-|---------|----------|-----------|
-| MUST / SHALL | critical | blocker |
-| SHOULD / RECOMMENDED | high | major |
-| MAY / OPTIONAL | medium | minor |
-
-Context files:
-- `.workflow/.spec/SPEC-xxx/requirements/REQ-*.md` -- Functional requirements + acceptance criteria
-- `.workflow/.spec/SPEC-xxx/requirements/NFR-*.md` -- Non-functional requirements
-- `.workflow/.spec/SPEC-xxx/architecture/_index.md` -- API endpoints, data model, state machines
-- `.workflow/.spec/SPEC-xxx/epics/EPIC-*.md` -- User stories for E2E scenarios
-- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths):
-  - plan.json -- Task overview (degraded mode)
-  - verification.json -- Cross-reference for must_haves
-  - .tests/business/ -- Previous business test artifacts
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/business-test.md' completely.
-
-**Next-step routing on completion:**
-- All requirements verified → `/maestro-milestone-audit`
-- Failures found → `/quality-debug --from-business-test {phase}`
-- Re-run all pass → `/maestro-verify {phase}`
-- Low coverage → `/quality-test-gen {phase}`
-- Need integration tests → `/quality-integration-test {phase}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json |
-| E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-roadmap --mode full or maestro-plan first |
-| E004 | error | L1 critical failures block L2/L3 progression | Fix blockers first via quality-debug |
-| W001 | warning | Degraded mode (no spec package, using success_criteria) | Consider running maestro-roadmap --mode full for full coverage |
-| W002 | warning | Some requirements have no testable acceptance criteria | Note in report, suggest spec refinement |
-| W003 | warning | Generator-Critic loop exhausted (3 iterations) without full convergence | Accept current state, proceed with known defects |
-| W004 | warning | Mock services not available for L3 scenarios | Skip L3 or run with --gen-code for TestContainers |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and spec package loaded (or degraded mode activated)
-- [ ] Business test scenarios extracted from REQ acceptance criteria
-- [ ] RFC 2119 keywords mapped to test priorities
-- [ ] Test fixtures generated (valid/invalid/boundary per REQ data model)
-- [ ] business-test-plan.json written with layer distribution
-- [ ] User confirmed plan (or -y skipped confirmation)
-- [ ] Test code generated if --gen-code (framework-appropriate)
-- [ ] L1 executed with Generator-Critic loop (max 3 iterations)
-- [ ] L2 executed if no L1 critical failures
-- [ ] L3 executed if no L2 critical failures
-- [ ] Traceability matrix built (every result -> REQ-NNN:AC-N)
-- [ ] business-test-report.json written with requirement_coverage
-- [ ] business-test-summary.md written (human-readable)
-- [ ] index.json updated with business_test section
-- [ ] Issues auto-created for failures (ISS-* in issues.jsonl with req_ref)
-- [ ] Next step routed based on results
-</success_criteria>

package/.claude/commands/quality-integration-test.md

@@ -1,67 +0,0 @@
----
-name: quality-integration-test
-description: Self-iterating integration test cycle with reflection-driven strategy and L0-L3 progressive layers
-argument-hint: "<phase> [--max-iter <N>] [--layer <L0|L1|L2|L3>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Run a self-iterating integration test cycle that combines exploration, test design, test execution, reflection, and adaptive strategy adjustment. Unlike quality-test (UAT with user) or quality-test-gen (generate missing tests), this command runs automated integration tests in a closed loop that self-corrects until convergence. Full 6-phase cycle, adaptive strategy engine, and L0-L3 progressive layers defined in workflow integration-test.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/integration-test.md
-</required_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number)
-
-**Flags:**
-- `--max-iter <N>` -- Maximum iterations (default: 5)
-- `--layer <L0|L1|L2|L3>` -- Start from specific layer (default: auto-detect)
-
-L0-L3 layer definitions, state file formats, and strategy engine rules defined in workflow integration-test.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/integration-test.md' completely.
-
-**Next-step routing on completion:**
-- Converged (pass rate met) → `/maestro-milestone-audit`
-- Max iterations, pass rate close → `/quality-debug {phase}` (investigate remaining failures)
-- Regressions detected → `/quality-debug {phase}`
-- Stuck 3+ iterations → `/maestro-analyze {phase} -q` (reassess approach)
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase number 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 test framework detected | Install test framework or verify project setup |
-| W001 | warning | Max iterations reached without convergence | Review reflection log, consider manual intervention |
-| W002 | warning | Regression detected, switching to Surgical strategy | Review reflection log, consider manual intervention |
-| W003 | warning | Stuck 3+ iterations, switching to Reflective strategy | Review reflection log, consider manual intervention |
-</error_codes>
-
-<success_criteria>
-- [ ] Integration test session initialized with state.json
-- [ ] Codebase explored for integration points
-- [ ] Test plan designed with L0-L3 layers
-- [ ] Tests written following existing patterns
-- [ ] Tests executed with results recorded per iteration
-- [ ] Reflection logged with pattern analysis
-- [ ] Strategy adapted based on results (conservative/aggressive/surgical/reflective)
-- [ ] Iterations continue until convergence or max_iter
-- [ ] summary.json written with final results
-- [ ] reflection-log.md contains full iteration history
-- [ ] index.json updated with integration test status
-- [ ] Next step routed (phase-transition if converged, debug if failures, analyze -q if stuck)
-</success_criteria>

package/.claude/commands/quality-test-gen.md

@@ -1,68 +0,0 @@
----
-name: quality-test-gen
-description: Generate missing tests with TDD/E2E classification and RED-GREEN methodology
-argument-hint: "<phase> [--layer <unit|e2e|all>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Generate missing automated tests for a phase based on gap analysis from maestro-verify (Nyquist audit) and quality-test (UAT coverage gaps). Bridges verification (finds MISSING coverage) and testing (runs UAT) by producing the automated tests that make Nyquist coverage pass. TDD/E2E classification, test discovery, plan approval, and RED-GREEN methodology defined in workflow test-gen.md.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/test-gen.md
-</required_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number)
-
-**Flags:**
-- `--layer <unit|e2e|all>` -- Generate only specific test layer (default: all)
-
-Context files:
-- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths):
-  - verification.json -- Nyquist gaps (MISSING/PARTIAL)
-  - validation.json -- requirement-to-test mapping
-  - .tests/coverage-report.json -- UAT coverage gaps
-  - .summaries/TASK-*.md -- what was built
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/test-gen.md' completely.
-
-**Next-step routing on completion:**
-- All tests pass → `/quality-test {phase}`
-- Bugs discovered (failing tests) → `/quality-debug {phase}`
-- Regressions in existing tests → `/quality-debug {phase}`
-- Coverage still low → `/quality-test-gen {phase} --layer {missing_layer}`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase number required | Check arguments format, re-run with correct input |
-| E002 | error | No verification results found (run maestro-verify first) | Check arguments format, re-run with correct input |
-| E003 | error | No test framework detected | Install test framework or configure test runner |
-| W001 | warning | Some generated tests fail (bugs discovered) | Investigate test failures, fix source code |
-| W002 | warning | Regression in existing tests | Investigate test failures, fix source code |
-</error_codes>
-
-<success_criteria>
-- [ ] Test infrastructure discovered (framework, patterns, conventions)
-- [ ] Gaps identified from verification.json and coverage-report.json
-- [ ] Changed files classified into unit/integration/e2e/skip
-- [ ] Test plan generated and approved by user
-- [ ] Tests written following existing patterns (RED-GREEN methodology)
-- [ ] Tests run and results categorized (passing/failing/regression)
-- [ ] test-gen-report.json written with full results
-- [ ] validation.json updated with new coverage status
-- [ ] Bugs discovered documented (not fixed)
-- [ ] Next step routed (quality-test if pass, quality-debug if bugs discovered)
-</success_criteria>

package/.codex/skills/maestro-ralph-execute/SKILL.md

@@ -1,219 +0,0 @@
----
-name: maestro-ralph-execute
-description: Single-step skill executor — spawned by maestro-ralph via CSV, reads ralph session context, executes one skill command, reports result
-argument-hint: "[-y] <skill_call>"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-<purpose>
-Worker agent spawned by maestro-ralph via `spawn_agents_on_csv`.
-Each invocation executes exactly ONE skill command and reports the result.
-
-Receives `skill_call` (e.g. `$maestro-plan 1`) from the wave CSV.
-Before execution, reads the ralph session status.json to obtain execution context
-(phase, milestone, intent, artifact paths) — uses this to enrich skill args when needed.
-
-Writes back **nothing** to status.json — ralph coordinator reads the result CSV and updates status.json itself.
-Decision nodes never arrive here — ralph processes them directly.
-</purpose>
-
-<context>
-**From CSV row:**
-- `skill_call` — full skill invocation string (e.g. `$maestro-plan 1`, `$quality-review 1`)
-- `topic` — brief description of what this step does
-
-**The skill_call format:** `$<skill-name> <args>`
-
-**Ralph session status.json** — located at `.workflow/.maestro/ralph-*/status.json` (latest running session).
-Read-only for this agent. Provides:
-
-```json
-{
-  "session_id": "ralph-{YYYYMMDD-HHmmss}",
-  "source": "ralph",
-  "intent": "用户原始输入",
-  "status": "running",
-  "phase": 1,
-  "milestone": "MVP",
-  "auto_mode": false,
-  "lifecycle_position": "plan",
-  "context": {
-    "plan_dir": ".workflow/scratch/...",
-    "analysis_dir": ".workflow/scratch/...",
-    "brainstorm_dir": null
-  },
-  "steps": [...],
-  "current_step": 3
-}
-```
-
-**Project state** — `.workflow/state.json` provides artifact registry:
-```json
-{
-  "current_milestone": "MVP",
-  "artifacts": [
-    { "id": "ANL-001", "type": "analyze", "phase": 1,
-      "path": "phases/01-auth-multi-tenant", "status": "completed" }
-  ]
-}
-```
-</context>
-
-<execution>
-
-## Step 1: Parse skill_call
-
-```
-Parse $ARGUMENTS:
-  Contains "-y" or "--yes" → auto = true, remove flag from remaining args
-  Remaining → skill_call
-
-Extract from skill_call:
-  skill_name = text between $ and first space (e.g. "maestro-plan")
-  skill_args = remainder after first space (e.g. "1")
-
-If skill_call is empty or malformed:
-  → report_agent_job_result({ status: "failed", error: "Invalid skill_call" })
-  → End.
-```
-
-Also read `session.auto_mode` from ralph status.json — if `true`, treat as `-y` even if flag not passed.
-
-## Step 2: Load ralph session context
-
-```
-Glob .workflow/.maestro/ralph-*/status.json
-  Filter: status == "running"
-  Sort by created_at DESC, take first
-  → ralph_session
-
-If not found: proceed with skill_args as-is (standalone execution)
-```
-
-Extract from ralph_session:
-- `phase` — current phase number
-- `milestone` — current milestone name
-- `intent` — user's original input text
-- `context.plan_dir` — latest plan artifact directory
-- `context.analysis_dir` — latest analysis artifact directory
-- `context.brainstorm_dir` — brainstorm output directory
-
-Also read `.workflow/state.json` for artifact registry when needed.
-
-## Step 3: Enrich skill args
-
-If skill_args contain unresolved context or are insufficient, enrich based on skill type:
-
-```
-Per-skill enrichment (when args need context from session):
-
-maestro-brainstorm:
-  If args empty → args = '"{intent}"'
-
-maestro-roadmap:
-  If args empty → args = '"{intent}"'
-
-maestro-analyze:
-  If args is just a number → keep as phase number
-  If args empty → args = '{phase}' or '"{intent}"'
-
-maestro-plan:
-  If args is number → keep as phase
-  If needs artifact dir → resolve latest analyze artifact:
-    state.json.artifacts[] → filter(type=="analyze", phase==session.phase) → latest → --dir .workflow/scratch/{path}
-
-maestro-execute:
-  If args is number → keep as phase
-  If needs artifact dir → resolve latest plan artifact:
-    state.json.artifacts[] → filter(type=="plan", phase==session.phase) → latest → --dir .workflow/scratch/{path}
-
-quality-debug:
-  Read previous step's result artifacts for gap/failure context
-  If from verify: append gap summary from verification.json
-  If from test: append --from-uat {phase}
-  If from business-test: append --from-business-test {phase}
-
-quality-* (review, test, test-gen, business-test):
-  If args empty → args = '{phase}'
-
-maestro-verify, maestro-milestone-audit, maestro-milestone-complete:
-  If args empty → args = '{phase}' (or empty for milestone-*)
-```
-
-## Step 4: Execute skill
-
-**`-y` auto flag 传播：** 当 `auto == true` 时，按传播表附加 flag：
-```
-auto_flag_map = {
-  "maestro-init": "-y",
-  "maestro-analyze": "-y",
-  "maestro-brainstorm": "-y",
-  "maestro-roadmap": "-y",
-  "maestro-plan": "-y",
-  "maestro-execute": "-y",
-  "quality-business-test": "-y",
-  "quality-test": "-y --auto-fix",
-  "quality-retrospective": "-y",
-  "maestro-milestone-complete": "-y"
-}
-flag = auto_flag_map[skill_name] || ""
-skill_args = flag ? `${skill_args} ${flag}` : skill_args
-```
-
-```
-Read .codex/skills/{skill_name}/SKILL.md to understand the skill
-Execute the skill with enriched skill_args as $ARGUMENTS
-
-Track:
-  - Artifact paths produced (scratch dirs, plan.json, verification.json, etc.)
-  - Session IDs created (WFS-*, ANL-*, PLN-*, etc.)
-  - Success/failure status
-```
-
-## Step 5: Report result
-
-```
-report_agent_job_result({
-  status: "completed" | "failed",
-  skill_call: "{original_skill_call}",
-  summary: "one-line result description",
-  artifacts: "comma-separated artifact paths or empty string",
-  error: "failure reason or empty string"
-})
-```
-
-**Artifact paths to report** (for ralph's barrier analysis):
-| Skill | Report |
-|-------|--------|
-| maestro-analyze | scratch dir path containing context.md |
-| maestro-plan | scratch dir path containing plan.json |
-| maestro-execute | scratch dir path containing .summaries/ |
-| maestro-brainstorm | .brainstorming/ output dir |
-| maestro-roadmap | roadmap.md path |
-| maestro-verify | verification.json path |
-| quality-review | review.json path |
-| quality-test | uat.md path |
-| quality-business-test | business test output path |
-| Others | empty or relevant output path |
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | skill_call parsing failed | Report failed |
-| E002 | error | Skill SKILL.md not found | Report failed |
-| E003 | error | Skill execution error | Report failed with error details |
-| E004 | error | Ralph session not found (standalone mode) | Execute with args as-is |
-| W001 | warning | Artifact dir not found for enrichment | Use args as-is, warn in summary |
-</error_codes>
-
-<success_criteria>
-- [ ] skill_call correctly parsed into skill_name + skill_args
-- [ ] Ralph session status.json read for context (phase, intent, artifact paths)
-- [ ] Args enriched per-skill when context needed (brainstorm→intent, plan→dir, debug→gaps)
-- [ ] Skill executed via its own SKILL.md
-- [ ] Artifact paths accurately reported for ralph's barrier analysis
-- [ ] status.json NEVER written by this agent
-- [ ] Result reported via report_agent_job_result
-</success_criteria>

package/.codex/skills/quality-business-test/SKILL.md

@@ -1,218 +0,0 @@
----
-name: quality-business-test
-description: PRD-forward business testing with requirement traceability, multi-layer execution (L1 Interface -> L2 Business Rule -> L3 Scenario), fixture generation, and feedback loop.
-argument-hint: "<phase> [--spec SPEC-xxx] [--layer L1|L2|L3] [--gen-code] [--dry-run] [--re-run] [-y]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion
----
-
-<purpose>
-Validate built features against PRD acceptance criteria through automated multi-layer business testing. Unlike quality-test (interactive UAT from code gaps) and quality-test-gen (generate tests from coverage gaps), this starts from REQ-*.md acceptance criteria and works forward.
-
-**Three-track testing** (complementary, not replacements):
-
-| Command | Input Source | Verification Angle |
-|---------|-------------|-------------------|
-| `quality-business-test` | REQ-*.md acceptance criteria | **PRD-forward** -- are business rules satisfied? |
-| `quality-test` | verification.json must_haves | **Code-backward** -- does the code work? |
-| `quality-test-gen` | validation.json gaps | **Coverage-backward** -- is coverage sufficient? |
-
-**Layer definitions:**
-
-| Layer | Name | Tests | Source |
-|-------|------|-------|--------|
-| L1 | Interface Contract | Single endpoint request/response, input validation, schema compliance | Architecture API endpoints + REQ AC |
-| L2 | Business Rule | Multi-step logic, state transitions, business constraints, edge cases | REQ acceptance criteria + NFR |
-| L3 | Business Scenario | Full user flows, multi-service chains, error propagation | Epic user stories |
-</purpose>
-
-<context>
-$ARGUMENTS -- phase number plus optional flags.
-
-**Usage**:
-
-```bash
-$quality-business-test "3"                          # test phase 3 against PRD
-$quality-business-test "3 --layer L1"               # L1 interface tests only
-$quality-business-test "3 --gen-code"               # generate framework-specific test classes
-$quality-business-test "3 --dry-run"                # extract scenarios only, don't execute
-$quality-business-test "3 --re-run"                 # re-run only previously failed scenarios
-$quality-business-test "3 --spec SPEC-auth-2026-04" # explicit spec reference
-$quality-business-test "3 -y"                   # skip plan confirmation
-```
-
-**Flags**:
-- `<phase>`: Phase number (required)
-- `--spec SPEC-xxx`: Explicit spec package reference (default: auto-detect from index.json)
-- `--layer L1|L2|L3`: Run only specific layer
-- `--gen-code`: Generate framework-specific test classes (JUnit/RestAssured, supertest/vitest, pytest/httpx)
-- `--dry-run`: Extract scenarios and fixtures only, don't execute
-- `--re-run`: Re-run only previously failed/blocked scenarios
-- `-y`: Skip interactive confirmations
-
-`-y` skips interactive confirmation of test plan. `--dry-run` extracts scenarios only without execution.
-
-**Output**: `{artifact_dir}/.tests/business/business-test-plan.json` + `business-test-report.json` + `business-test-summary.md`
-</context>
-
-<invariants>
-1. **PRD is source of truth** -- business rules drive test scenarios, not code structure
-2. **RFC 2119 keyword priority** -- MUST = critical, SHOULD = high, MAY = medium
-3. **Fail-fast across layers** -- critical L1 failures block L2/L3
-4. **Generator-Critic loop max 3 iterations** per layer
-5. **Traceability on every result** -- every pass/fail maps to REQ-NNN:AC-N
-6. **Agent calls use `run_in_background: false`** for synchronous execution
-7. **Auto-create issues** in `.workflow/issues/issues.jsonl` for every failure
-8. **Degraded mode** works without spec package (from success_criteria + plan.json)
-9. **Never modify source code** -- this command tests, it doesn't fix
-</invariants>
-
-<execution>
-
-### Step 1: Resolve Target & Load Spec Package
-
-1. Parse `$ARGUMENTS` for phase number and flags
-2. Resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`
-3. **Related session discovery**: Query `state.json.artifacts[]` for all artifacts matching `phase === target_phase && milestone === current_milestone`. Each artifact's type determines its outputs: review → review.json (findings inform which business rules need extra scrutiny), debug → understanding.md (root causes map to specific requirement failures), test → uat.md (prior UAT gaps identify untested business scenarios). Extract conclusions that may affect business test scenario priorities.
-4. Load `index.json` -> find `spec_ref` -> locate `.workflow/.spec/SPEC-xxx/`
-4. **Full mode**: Read `requirements/_index.md` + all `REQ-*.md` + `NFR-*.md` + `architecture/_index.md` + `epics/EPIC-*.md`
-5. **Degraded mode** (no spec package): Read `index.json.success_criteria` + `plan.json` convergence criteria + `.summaries/TASK-*.md`
-6. If `--re-run`: load previous `business-test-report.json`, filter to failed/blocked scenarios
-
-### Step 2: Extract Business Test Scenarios from PRD
-
-For each `REQ-NNN-{slug}.md`:
-
-1. Parse `## Acceptance Criteria` section
-2. Map RFC 2119 keywords to priority:
-
-| Keyword | Priority | Failure = |
-|---------|----------|-----------|
-| MUST / SHALL | critical | blocker |
-| SHOULD / RECOMMENDED | high | major |
-| MAY / OPTIONAL | medium | minor |
-
-3. Classify scenario into layer:
-
-| Source | Layer | Category |
-|--------|-------|----------|
-| Architecture API endpoints + REQ AC about request/response | L1 | api_contract |
-| REQ AC about business logic, validation, state changes | L2 | business_rule |
-| Architecture state machine transitions | L2 | state_transition |
-| Epic user stories (multi-step flows) | L3 | user_flow |
-| NFR performance/security constraints | L2 | non_functional |
-
-4. Generate scenario JSON with `id`, `req_ref` (REQ-NNN:AC-N), `layer`, `priority`, `name`, `category`, `endpoint`, `input`, `expected`, `preconditions`, `postconditions`, `mock_services`
-
-**Degraded mode**: Extract from success_criteria (each -> L2 scenario), plan.json convergence criteria (each -> L1/L2), all default priority: high. No L3 in degraded mode.
-
-### Step 3: Generate Test Data (Fixtures)
-
-Three tiers:
-
-**Tier 1 -- Schema-derived**: From REQ data models, generate valid/invalid/boundary variants per entity:
-- valid: satisfies all constraints
-- invalid: violate each constraint individually (null, empty, overflow, wrong type)
-- boundary: edge values (min, max, min-1, max+1)
-
-**Tier 2 -- Criteria-derived**: From "MUST return X when Y" -> `{ input: Y, expected: X }`. From "MUST validate Z" -> `{ input: invalid_Z, expected: error }`.
-
-**Tier 3 -- Scenario-derived (L3 only)**: From Epic user stories -> scenario packs with coordinated entity IDs across steps.
-
-**Microservice mocks**: From architecture API contract -> request/response pairs for WireMock stubs.
-
-### Step 4: Write Test Plan & Confirm
-
-1. Archive previous `business-test-plan.json` to `.history/` if exists
-2. Write `.tests/business/business-test-plan.json` with scenarios, fixtures, mock_contracts, requirement_coverage_plan
-3. Display plan summary (scenario counts per layer, fixture counts, requirement coverage)
-4. If not `-y`: wait for user confirmation (yes/edit/cancel)
-5. If `--dry-run`: stop here, report plan
-
-### Step 5: Generate Test Code (if --gen-code)
-
-Detect project tech stack from `.workflow/project.md` Tech Stack section or codebase scan.
-
-| Stack | L1 | L2 | L3 |
-|-------|----|----|-----|
-| Java/Spring Boot | RestAssured + MockMvc | JUnit 5 Parameterized + WireMock | TestContainers |
-| TypeScript/Node | supertest + vitest | vitest + nock | playwright/cypress |
-| Python | httpx + pytest | pytest + responses | pytest + selenium |
-
-Each test method includes REQ-NNN:AC-N reference in display name. Test files placed in `.tests/business/{layer}/`.
-
-If no `--gen-code`: scenarios stay as structured JSON for AI agent execution.
-
-### Step 6: Execute Tests (Progressive L1 -> L2 -> L3)
-
-**Fail-fast**: L1 critical failures -> STOP (don't run L2). L2 critical failures -> STOP (don't run L3).
-
-**Generator-Critic loop per layer (max 3 iterations):**
-
-| Iteration | Action |
-|-----------|--------|
-| 1 | Run all scenarios. Critic: classify failures as test_defect / code_defect / env_issue |
-| 2 | Auto-fix test_defects, re-run ALL scenarios |
-| 3 | Final confirmation. Remaining failures = confirmed code_defects |
-
-**Execution modes:**
-- `--gen-code`: run via test framework (`mvn test`, `npx vitest`, etc.)
-- default: AI agent executes scenarios against running application
-
-Record results in `.tests/business/test-results-iter-{N}.json`.
-
-### Step 7: Build Traceability Matrix
-
-Map each result to `REQ-NNN:AC-N`. Per AC: `passed` (all scenarios pass), `failed` (any fail), `blocked` (any blocked, none failed), `untested` (no scenarios). Per REQ verdict: `verified` (all MUST+SHOULD AC passed), `partial` (some failed), `unverified` (all failed/untested).
-
-### Step 8: Generate Reports
-
-1. Archive previous report/summary to `.history/`
-2. Write `.tests/business/business-test-report.json` with:
-   - `layers`: per-layer stats (total, passed, failed, blocked, pass_rate)
-   - `requirement_coverage`: per-REQ criteria results with failure details
-   - `failures`: each with req_ref, severity, expected/actual, fix_suggestion
-   - `summary`: total_requirements, fully_verified, partially_verified, unverified, coverage_pct
-3. Write `.tests/business/business-test-summary.md` (human-readable tables)
-4. Update `index.json` with `business_test` section
-
-### Step 9: Feedback Loop
-
-1. Auto-create issues from failures in `.workflow/issues/issues.jsonl` (each with `req_ref`, `source: "business-test"`)
-2. Report results
-3. **Register artifact**: Append to `state.json.artifacts[]` with `type: "test"`, `id: TST-NNN`, `path: "scratch/{YYYYMMDD}-business-test-P{N}-{slug}"`, `depends_on: exec_art.id`.
-4. Route next step:
-
-| Result | Suggestion |
-|--------|------------|
-| All requirements verified | Skill({ skill: "maestro-milestone-audit" }) |
-| Failures found | Skill({ skill: "quality-debug", args: "--from-business-test {phase}" }) |
-| `--re-run` all pass | Skill({ skill: "maestro-verify", args: "{phase}" }) |
-| Low coverage (< 60%) | Skill({ skill: "quality-test-gen", args: "{phase}" }) |
-
-**Closure criteria**: Requirement marked "verified" ONLY when ALL MUST+SHOULD acceptance criteria pass.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase directory not found | Resolve via state.json artifact registry |
-| E003 | error | No spec package AND no success_criteria | Run maestro-roadmap --mode full or maestro-plan first |
-| E004 | error | L1 critical failures block L2/L3 | Fix blockers via quality-debug |
-| W001 | warning | Degraded mode (no spec package) | Consider running maestro-roadmap --mode full |
-| W002 | warning | Some REQs have no testable AC | Note in report |
-| W003 | warning | Generator-Critic loop exhausted | Accept current state |
-| W004 | warning | Mock services unavailable for L3 | Skip L3 or use --gen-code |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and spec package loaded (or degraded mode activated)
-- [ ] Business test scenarios extracted from PRD acceptance criteria
-- [ ] Fixtures generated for all layers
-- [ ] Test plan written and confirmed (or -y/--dry-run)
-- [ ] Tests executed progressively L1 -> L2 -> L3 with fail-fast
-- [ ] Traceability matrix maps every result to REQ-NNN:AC-N
-- [ ] Reports generated (JSON + summary markdown)
-- [ ] Issues auto-created for all failures
-- [ ] Next step suggested based on results
-</success_criteria>