maestro-flow 0.3.10 → 0.3.12

package/.claude/commands/maestro-roadmap.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-roadmap
 description: Interactive roadmap creation with iterative refinement — lightweight alternative to spec-generate
-argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID]"
+argument-hint: "<requirement> [-y] [-c] [-m progressive|direct|auto] [--from-brainstorm SESSION-ID] [--revise [instructions]] [--review]"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +13,12 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Create a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
+Create or revise a project roadmap through interactive requirement decomposition and iterative refinement. This is the lightweight path for structured decomposition — directly from requirements to roadmap without full specification documents. For the heavy path with formal specs, use maestro-spec-generate instead.
+
+Supports three modes:
+- **Create** (default): Build roadmap from requirements
+- **Revise** (`--revise`): Modify existing roadmap while preserving completed phase progress
+- **Review** (`--review`): Health assessment of current roadmap — actual vs planned, drift detection, adjustment recommendations (read-only)
 
 Produces `.workflow/roadmap.md` with milestone/phase structure ready for maestro-plan.
 </purpose>
@@ -31,11 +36,14 @@ $ARGUMENTS -- requirement text, @file reference, or brainstorm session reference
 - `-c` / `--continue`: Resume from last checkpoint
 - `-m progressive|direct|auto`: Decomposition strategy (default: auto)
 - `--from-brainstorm SESSION-ID`: Import guidance-specification.md from a brainstorm session as seed
+- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly (e.g. `--revise "add phase 4 for perf optimization"` or `--revise "split phase 2 into 2a and 2b"`). If omitted, ask user for revision instructions via AskUserQuestion. Preserves completed phase progress.
+- `--review`: Roadmap health assessment — compare actual vs planned progress, detect drift, assess remaining phases (read-only, produces review report)
 
 **Input types:**
 - Direct text: `"Implement user authentication system with OAuth and 2FA"`
 - File reference: `@requirements.md`
 - Brainstorm import: `--from-brainstorm WFS-xxx`
+- No args + `--revise` / `--review`: Operate on existing `.workflow/roadmap.md`
 
 **Relationship to pipeline:**
 ```
@@ -63,6 +71,9 @@ Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Dire
 </context>
 
 <execution>
+
+### Mode: Create (default)
+
 Follow '~/.maestro/workflows/roadmap.md' completely.
 
 **Next-step routing on completion:**
@@ -70,6 +81,104 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 - Simple project, skip analysis → /maestro-plan 1
 - Need UI design first → /maestro-ui-design 1
 - View project dashboard → /manage-status
+
+### Mode: Revise (`--revise [instructions]`)
+
+Revise an existing roadmap while preserving completed phase progress.
+
+**Pre-conditions:**
+- `.workflow/roadmap.md` exists
+- `.workflow/state.json` exists (for progress tracking)
+
+**Execution flow:**
+
+1. **Load current state**
+   - Read `.workflow/roadmap.md` — parse milestones, phases, dependencies, progress markers
+   - Read `.workflow/state.json` — get artifact registry, current milestone
+   - Identify completed vs in-progress vs pending phases
+
+2. **Obtain revision instructions**
+   - If `--revise "instructions text"` provided → use directly as change directive
+   - If `--revise` without instructions → use AskUserQuestion to ask user what to change
+     - Show current roadmap summary with phase statuses
+     - Present options: add/remove/reorder phases, modify scope/criteria/deps, move between milestones
+     - Capture change instructions from response
+
+3. **Impact analysis**
+   - For each proposed change, assess impact on:
+     - Phase dependency chain (re-validate no circular deps)
+     - Requirement coverage (every Active requirement still mapped)
+     - Completed phases (warn if change invalidates completed work)
+     - Existing plan artifacts (warn if plan exists for affected phase)
+   - Present impact summary for confirmation
+
+4. **Apply revisions**
+   - Update `.workflow/roadmap.md` preserving:
+     - Completed phase progress markers (✓, completion dates)
+     - Phase numbering for completed phases (renumber only pending phases)
+     - Cross-references from state.json artifacts
+   - Update `state.json` if milestone structure changed
+   - Add revision log entry to roadmap.md metadata section
+
+5. **Post-revision validation**
+   - Re-check dependency integrity (no circular deps)
+   - Re-check requirement coverage (every Active req mapped)
+   - Verify completed phases unaffected
+
+**Next-step routing on completion:**
+- Phases changed, need re-analysis → `/maestro-analyze {phase}`
+- Phases changed, ready to plan → `/maestro-plan {phase}`
+- Only pending phases adjusted → `/maestro-plan` (continue from where left off)
+
+### Mode: Review (`--review`)
+
+Read-only health assessment of the current roadmap.
+
+**Pre-conditions:**
+- `.workflow/roadmap.md` exists
+
+**Execution flow:**
+
+1. **Load roadmap + execution history**
+   - Read `.workflow/roadmap.md` — full structure
+   - Read `.workflow/state.json` — artifact registry, milestone progress
+   - Cross-reference: for each phase, check ANL/PLN/EXC/VRF artifact status
+
+2. **Assessment dimensions**
+   - **Progress tracking**: Actual vs planned per phase, milestone velocity
+   - **Drift detection**: Completed phases deviating from original scope (via verify/audit findings)
+   - **Relevance check**: Pending phases still aligned with current project goals (from project.md)
+   - **Dependency health**: Pending phase dependencies still valid given completed work
+   - **Risk assessment**: Identify phases at risk (blocked, scope creep, dependency failures)
+
+3. **Produce review report**
+   - Write to `.workflow/scratch/roadmap-review-{date}.md`
+   - Format:
+     ```
+     === ROADMAP REVIEW ===
+     Date: {date}
+     Milestone: {current}
+
+     Progress: {completed}/{total} phases ({percentage}%)
+     Drift: {none|minor|significant}
+     Risk: {low|medium|high}
+
+     Phase Assessment:
+       [✓] Phase 1: {name} — completed, on-scope
+       [~] Phase 2: {name} — in-progress, {status notes}
+       [ ] Phase 3: {name} — pending, {risk/notes}
+
+     Recommendations:
+       1. {actionable recommendation}
+       2. ...
+
+     Suggested actions:
+       /maestro-roadmap --revise   — Apply recommended changes
+       /maestro-plan {phase}       — Plan next phase
+       /manage-status              — View full dashboard
+     ```
+
+**No state modifications.** Pure assessment + recommendations.
 </execution>
 
 <error_codes>
@@ -78,6 +187,8 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 | E001 | error | Requirement text or @file required | Prompt user for input |
 | E002 | error | Brainstorm session not found (--from-brainstorm) | Show available sessions |
 | E003 | error | Circular dependency detected in phases | Prompt user to re-decompose |
+| E004 | error | roadmap.md not found (--revise/--review) | Run maestro-roadmap first |
+| E005 | error | Revision invalidates completed phase work | Warn user, ask to confirm or adjust |
 | W001 | warning | CLI analysis failed, using fallback | Continue with available data |
 | W002 | warning | Max refinement rounds (5) reached | Force proceed with current roadmap |
 | W005 | warning | External research agent failed | Continue without apiResearchContext |

package/.claude/commands/maestro.md

@@ -55,6 +55,7 @@ When `-y` is active, maestro propagates auto flags to downstream commands. Only
 |---------|-----------|--------|
 | maestro-analyze | `-y` | Skip interactive scoping, auto-deepen |
 | maestro-brainstorm | `-y` | Skip interactive questions, use defaults |
+| maestro-roadmap | `-y` | Skip interactive questions, use defaults (create/revise/review) |
 | maestro-ui-design | `-y` | Skip interactive selection, pick top variant |
 | maestro-plan | `--auto` | Skip interactive clarification |
 | maestro-spec-generate | `-y` | Skip interactive questions, use defaults |

package/.claude/commands/manage-harvest.md

@@ -1,131 +1,131 @@
----
-name: manage-harvest
-description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
-argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
-
-Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
-
-**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/harvest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
-- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected):**
-- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
-- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
-- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
-
-**Flags:**
-- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
-- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
-- `--recent N` — Only artifacts updated within last N days (default: 30)
-- `--dry-run` — Preview extraction and routing without writing
-- `-y` / `--yes` — Skip confirmation prompts
-- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
-
-**Source registry (scan paths):**
-| Source Type | Scan Path | Key Files |
-|-------------|-----------|-----------|
-| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
-| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
-| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
-| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
-| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
-| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
-| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
-
-**Storage written:**
-- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
-- `.workflow/harvest/harvest-report-{date}.md` — per-run report
-- Wiki entries via `maestro wiki create`
-- Spec entries via `Skill({ skill: "spec-add" })`
-- Issue entries appended to `.workflow/issues/issues.jsonl`
-
-**Storage read (never modified):**
-- All artifact source files (read-only until routing stage)
-- `.workflow/harvest/harvest-log.jsonl` (dedup check)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
-
-1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
-2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
-3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
-4. **Reuse existing routing infrastructure**:
-   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-   - Spec: `Skill({ skill: "spec-add", args: "<type> <content>" })`
-   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
-5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
-6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
-7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
-
-**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
-
-**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
-
-**Next-step routing on completion:**
-- Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
-- Triage issues → `/manage-issue list --source harvest`
-- View specs → `/spec-load --category general`
-- Full retrospective → `/quality-retrospective`
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
-| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
-| E003 | error | Invalid `--source` type | Display valid source types from registry |
-| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
-| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
-| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
-| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
-| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
-| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
-| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly resolved (scan / session / path)
-- [ ] Source artifacts discovered and listed with metadata
-- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
-- [ ] All files in selected artifacts loaded and parsed
-- [ ] Knowledge fragments extracted with category, confidence, tags
-- [ ] Fragments filtered by `--min-confidence`
-- [ ] Routing classification applied (auto or forced by `--to`)
-- [ ] Dedup check passed against harvest-log.jsonl and existing stores
-- [ ] If `--dry-run`: preview displayed, no files written
-- [ ] If not dry-run: all routed items written to target stores
-- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
-- [ ] Spec entries added via `spec-add` mechanism
-- [ ] Issue entries appended to `issues.jsonl` with canonical schema
-- [ ] `harvest-log.jsonl` updated with provenance for each routed item
-- [ ] `harvest-report-{date}.md` written with full summary
-- [ ] No source artifacts modified
-- [ ] Summary displayed with counts and next-step routing
-</success_criteria>
+---
+name: manage-harvest
+description: Extract knowledge from workflow artifacts and route to wiki / spec / issue stores
+argument-hint: "[<session-id|path>] [--to wiki|spec|issue|auto] [--source <type>] [--recent N] [--dry-run] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Extract knowledge fragments from workflow artifacts (analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, completed sessions) and route them into the project's three knowledge stores: wiki entries, spec conventions, and trackable issues.
+
+Complements `quality-retrospective` (which is phase-scoped) by harvesting from **any** workflow artifact. Prevents knowledge loss from completed analysis and planning sessions that would otherwise only exist as stale files.
+
+**Closed-loop**: harvest extracts → wiki/spec/issue stores → downstream commands consume (wiki-digest, spec-load, maestro-plan --gaps).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/harvest.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl schema for issue routing — read when creating issues in Stage 6c)
+- @~/.maestro/workflows/specs-add.md (spec entry format — read when routing to spec in Stage 6b)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Modes (auto-detected):**
+- No arguments → `scan` mode: discover all harvestable artifacts, interactive selection
+- `<session-id>` (e.g., `ANL-auth-20260410`, `WFS-xxx`) → `session` mode: harvest specific session
+- `<path>` (e.g., `.workflow/.analysis/ANL-auth-20260410/`) → `path` mode: harvest from explicit directory
+
+**Flags:**
+- `--to <target>` — Force routing: `wiki`, `spec`, `issue`, `auto` (default: `auto`)
+- `--source <type>` — Filter source type: `analysis`, `brainstorm`, `debug`, `lite-plan`, `lite-fix`, `scratchpad`, `session`, `learning`, `all` (default: `all`)
+- `--recent N` — Only artifacts updated within last N days (default: 30)
+- `--dry-run` — Preview extraction and routing without writing
+- `-y` / `--yes` — Skip confirmation prompts
+- `--min-confidence N` — Minimum extraction confidence 0.0-1.0 (default: 0.5)
+
+**Source registry (scan paths):**
+| Source Type | Scan Path | Key Files |
+|-------------|-----------|-----------|
+| `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` |
+| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md` |
+| `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` |
+| `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` |
+| `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` |
+| `scratchpad` | `.workflow/.scratchpad/` | `*.md`, `*.json` |
+| `session` | `.workflow/active/WFS-*/` | `workflow-session.json` |
+| `learning` | `.workflow/learning/` | `lessons.jsonl`, `digest-*.md` |
+
+**Storage written:**
+- `.workflow/harvest/harvest-log.jsonl` — provenance log (prevents duplicate harvesting)
+- `.workflow/harvest/harvest-report-{date}.md` — per-run report
+- Wiki entries via `maestro wiki create`
+- Spec entries via `Skill({ skill: "spec-add" })`
+- Issue entries appended to `.workflow/issues/issues.jsonl`
+
+**Storage read (never modified):**
+- All artifact source files (read-only until routing stage)
+- `.workflow/harvest/harvest-log.jsonl` (dedup check)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
+
+1. **Read-only until Stage 6** — Stages 1–5 must not write anything. All extraction and classification happens in-memory.
+2. **Dedup before write** — Stage 7 (dedup_check) runs BEFORE each write in Stage 6. Check harvest-log.jsonl, wiki search, issues.jsonl, and learnings.md for existing matches.
+3. **Stable fragment IDs** — `HRV-{8 hex}` from `hash(source_id + content_hash)` so re-runs on same artifacts do not create duplicates.
+4. **Reuse existing routing infrastructure**:
+   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
+   - Spec: `Skill({ skill: "spec-add", args: "<category> <content>" })`
+   - Issue: append to `issues.jsonl` matching canonical schema from `workflows/issue.md`
+5. **Never modify source artifacts** — harvest is purely extractive. Source files remain untouched.
+6. **Confidence filtering** — fragments below `--min-confidence` are logged but not routed.
+7. **Provenance tracking** — every routed item logged to `harvest-log.jsonl` with fragment_id, source reference, and target reference.
+
+**Fragment extraction uses source-specific parsing** (see harvest.md Stage 3b for per-source patterns). The agent should read each artifact file and identify discrete knowledge items: findings, decisions, patterns, bugs, risks, tasks, lessons, recommendations.
+
+**Classification uses category-to-target mapping** (see harvest.md Stage 4). Override with `--to` flag if user wants all items in one store.
+
+**Next-step routing on completion:**
+- Review wiki entries → `maestro wiki list --type note`
+- Connect wiki graph → `/wiki-connect --fix`
+- Triage issues → `/manage-issue list --source harvest`
+- View specs → `/spec-load --category learning`
+- Full retrospective → `/quality-retrospective`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
+| E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
+| E003 | error | Invalid `--source` type | Display valid source types from registry |
+| E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |
+| E005 | error | Path does not exist or contains no parseable artifacts | Verify path and file structure |
+| W001 | warning | No harvestable artifacts found within `--recent` window | Widen time window or check `.workflow/` contents |
+| W002 | warning | `maestro wiki create` failed — wiki entries saved to `.workflow/harvest/wiki-pending-*.md` | Apply pending entries manually or retry |
+| W003 | warning | Some fragments below confidence threshold — logged but not routed | Lower `--min-confidence` to include |
+| W004 | warning | Duplicate fragments skipped | Review harvest-log.jsonl for prior routing |
+| W005 | warning | `.workflow/issues/` directory missing | Auto-create directory and empty issues.jsonl |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly resolved (scan / session / path)
+- [ ] Source artifacts discovered and listed with metadata
+- [ ] User selected artifact(s) to harvest (or auto-selected via session/path mode)
+- [ ] All files in selected artifacts loaded and parsed
+- [ ] Knowledge fragments extracted with category, confidence, tags
+- [ ] Fragments filtered by `--min-confidence`
+- [ ] Routing classification applied (auto or forced by `--to`)
+- [ ] Dedup check passed against harvest-log.jsonl and existing stores
+- [ ] If `--dry-run`: preview displayed, no files written
+- [ ] If not dry-run: all routed items written to target stores
+- [ ] Wiki entries created via `maestro wiki create` (or fallback to pending files)
+- [ ] Spec entries added via `spec-add` mechanism
+- [ ] Issue entries appended to `issues.jsonl` with canonical schema
+- [ ] `harvest-log.jsonl` updated with provenance for each routed item
+- [ ] `harvest-report-{date}.md` written with full summary
+- [ ] No source artifacts modified
+- [ ] Summary displayed with counts and next-step routing
+</success_criteria>

package/.claude/commands/manage-issue.md

@@ -67,7 +67,7 @@ Follow '~/.maestro/workflows/issue.md' completely.
 - [ ] Output displayed in appropriate format (table for list, detail for status)
 - [ ] Cross-references maintained (link creates bidirectional references)
 - [ ] Next step routing by subcommand:
-  - create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
-  - list → `/manage-issue-analyze <ISS-ID>` for any open issue
+  - create → `/maestro-analyze --gaps <ISS-ID>` or `/maestro-plan --gaps`
+  - list → `/maestro-analyze --gaps <ISS-ID>` for any open issue
   - close → `/manage-status`
 </success_criteria>

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

@@ -60,10 +60,10 @@ Context files:
 - `.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
-- `.workflow/phases/{NN}-{slug}/index.json` -- Phase metadata, success_criteria
-- `.workflow/phases/{NN}-{slug}/plan.json` -- Task overview (degraded mode)
-- `.workflow/phases/{NN}-{slug}/verification.json` -- Cross-reference for must_haves
-- `.workflow/phases/{NN}-{slug}/.tests/business/` -- Previous business test artifacts
+- Phase artifacts (resolve via `state.json.artifacts[]` → `.workflow/scratch/` paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+  - plan.json -- Task overview (degraded mode)
+  - verification.json -- Cross-reference for must_haves
+  - .tests/business/ -- Previous business test artifacts
 </context>
 
 <execution>
@@ -81,7 +81,7 @@ Follow '~/.maestro/workflows/business-test.md' completely.
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase directory not found | Verify phase exists in .workflow/phases/ |
+| E002 | error | Phase artifacts not found | Verify phase has artifacts in state.json or .workflow/phases/ |
 | E003 | error | No spec package AND no success_criteria (can't extract scenarios) | Run maestro-spec-generate 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-spec-generate for full coverage |

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

@@ -40,8 +40,9 @@ User's issue: $ARGUMENTS
 - `--parallel` -- Spawn parallel debug agents (one per gap cluster)
 
 **State files:**
-- `.workflow/phases/{NN}-{slug}/uat.md` -- UAT gaps (if --from-uat)
-- `.workflow/phases/{NN}-{slug}/.debug/` -- Phase-scoped debug sessions
+- Phase UAT/debug artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+  - uat.md -- UAT gaps (if --from-uat)
+  - .debug/ -- Phase-scoped debug sessions
 - `.workflow/scratch/debug-*/` -- Standalone debug sessions
 </context>
 

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

@@ -43,8 +43,9 @@ Arguments: $ARGUMENTS
 - `--auto-yes` — accept all routing recommendations without prompting
 
 **Storage written:**
-- `.workflow/phases/{NN}-{slug}/retrospective.md` — human-readable record
-- `.workflow/phases/{NN}-{slug}/retrospective.json` — structured record
+- Retrospective output (resolve via `state.json.artifacts[]` → `.workflow/scratch/` path; fallback to `.workflow/phases/{NN}-{slug}/`):
+  - retrospective.md — human-readable record
+  - retrospective.json — structured record
 - `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
 - `.workflow/learning/lessons.jsonl` — tips routed via `manage-learn tip` (formerly manage-memory-capture)
@@ -52,8 +53,9 @@ Arguments: $ARGUMENTS
 - `.workflow/learning/learning-index.json` — searchable index
 
 **Storage read (never modified):**
-- `.workflow/phases/{NN}-{slug}/index.json`, `plan.json`, `verification.json`, `review.json`, `uat.md`
-- `.workflow/phases/{NN}-{slug}/.task/TASK-*.json`, `.summaries/TASK-*-summary.md`
+- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+  - index.json, plan.json, verification.json, review.json, uat.md
+  - .task/TASK-*.json, .summaries/TASK-*-summary.md
 - `.workflow/issues/issues.jsonl`, `.workflow/issues/issue-history.jsonl`
 - `.workflow/state.json`
 </context>

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

@@ -53,7 +53,7 @@ Phase: $ARGUMENTS (required — phase number or slug)
 - `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
 - `--skip-specs` — Skip loading project specs as review context
 
-Context files resolved from `.workflow/phases/{NN}-{slug}/`:
+Context files resolved via `state.json.artifacts[]` → scratch path (fallback: `.workflow/phases/{NN}-{slug}/`):
 - index.json (phase metadata, execution results)
 - plan.json (task overview)
 - .task/TASK-{NNN}.json (task definitions with file lists)

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

@@ -36,10 +36,11 @@ Phase: $ARGUMENTS (required -- phase number)
 - `--layer <unit|e2e|all>` -- Generate only specific test layer (default: all)
 
 Context files:
-- `.workflow/phases/{NN}-{slug}/verification.json` -- Nyquist gaps (MISSING/PARTIAL)
-- `.workflow/phases/{NN}-{slug}/validation.json` -- requirement-to-test mapping
-- `.workflow/phases/{NN}-{slug}/.tests/coverage-report.json` -- UAT coverage gaps
-- `.workflow/phases/{NN}-{slug}/.summaries/TASK-*.md` -- what was built
+- Phase artifacts (resolve via `state.json.artifacts[]` → scratch paths; fallback to `.workflow/phases/{NN}-{slug}/`):
+  - 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>