maestro-flow 0.3.11 → 0.3.12

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

@@ -1,77 +1,85 @@
----
-name: maestro-merge
-description: Two-phase merge of milestone worktree branch back — git merge first, artifact sync only on success
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Merge a completed milestone worktree branch back into the main branch, sync workflow artifacts for all phases, and reconcile project state. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
-
-Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (patch, don't overwrite).
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- milestone name and optional flags.
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
-- `--force`: Merge even if not all phases are completed
-- `--dry-run`: Show what would be merged without executing
-- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
-- `--continue`: Resume a merge that was paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check (remove stale entries)
-2. Validate phase readiness across all owned phases
-3. Pre-merge rebase (`git merge main` in worktree)
-4. Phase 1: Git merge (source code only)
-5. Phase 2: Artifact sync (only after git merge succeeds)
-6. Atomic state reconciliation
-7. Cleanup (worktree remove + branch delete)
-
-**Conflict handling:**
-If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Next-step routing on completion:**
-- View dashboard → Skill({ skill: "manage-status" })
-- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number provided | Provide `-m <N>` |
-| W001 | warning | Stale registry entries found | Auto-cleaned |
-| W002 | warning | Incomplete phases (without --force) | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed (stale entries cleaned)
-- [ ] Pre-merge rebase successful (worktree has latest main)
-- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
-- [ ] All owned phase artifacts synced to main `.workflow/phases/`
-- [ ] `state.json` reconciled (phases_summary, accumulated_context, transition_history patched)
-- [ ] `roadmap.md` completed phases marked
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated (entry removed)
-</success_criteria>
+---
+name: maestro-merge
+description: Two-phase merge of milestone worktree branch back — git merge first, scratch artifact sync only on success
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a completed milestone worktree branch back into the main branch, sync scratch artifacts, and reconcile the artifact registry. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
+
+Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (merge artifact entries, don't overwrite).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone name and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to registry)
+- `--force`: Merge even if milestone has incomplete artifacts
+- `--dry-run`: Show what would be merged without executing
+- `--no-cleanup`: Keep worktree and branch after merge (for inspection)
+- `--continue`: Resume a merge that was paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check (remove stale worktree entries)
+2. Validate milestone artifact completeness (all EXC artifacts completed)
+3. Pre-merge rebase (`git merge main` in worktree)
+4. Phase 1: Git merge (source code only)
+5. Phase 2: Scratch artifact sync (only after git merge succeeds)
+6. Atomic artifact registry reconciliation
+7. Cleanup (worktree remove + branch delete)
+
+**Phase 2 — Artifact sync detail:**
+- Copy worktree `scratch/*` dirs back to main `.workflow/scratch/`
+- Merge worktree `state.json.artifacts[]` entries into main `state.json.artifacts[]`
+  - Dedup by artifact id; worktree version wins for same id
+- Update milestone status in main `state.json.milestones[]` (remove "forked" flag)
+- Mark `harvested` status from worktree artifacts
+
+**Conflict handling:**
+If git merge fails, the command saves state to `.workflow/.merge-state.json` and exits. User resolves conflicts, then runs `maestro-merge --continue` to resume artifact sync.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next-step routing on completion:**
+- View dashboard → Skill({ skill: "manage-status" })
+- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| W001 | warning | Stale registry entries found | Auto-cleaned |
+| W002 | warning | Incomplete artifacts (without --force) | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed (stale entries cleaned)
+- [ ] Pre-merge rebase successful (worktree has latest main)
+- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
+- [ ] All scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
+- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] `worktrees.json` registry updated (entry removed)
+</success_criteria>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
 description: Explore, clarify, plan, check, and confirm a phase execution plan
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>]"
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [--auto] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - Read
   - Write
@@ -13,7 +13,12 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Create a verified execution plan (plan.json + .task/TASK-*.json) through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+
+Supports three modes:
+- **Create** (default): Build plan from analysis context or phase requirements
+- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
+- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
 
 All plan output goes to `.workflow/scratch/plan-{slug}-{date}/`. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
 </purpose>
@@ -37,6 +42,8 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 - `--auto` -- Skip interactive clarification (P2), use defaults
 - `--gaps` -- Gap closure mode: load verification/issue gaps, skip exploration, plan only gap fixes
 - `--dir <path>` -- Use arbitrary scratch directory as context source (e.g., from analyze session)
+- `--revise [instructions]` -- Revise existing plan. Auto-discovers latest plan for current phase from state.json, or use with `--dir` to target specific plan. If instructions provided, apply directly (e.g. `--revise "add TASK-005 for error handling"`). If omitted, ask user via AskUserQuestion. Skips P1-P3 (exploration/clarification/planning), loads existing plan.json + tasks, applies targeted modifications, re-runs P4 (plan-checker).
+- `--check <plan-dir>` -- Standalone plan verification. Run plan-checker (P4 only) against existing plan without modification. Also checks roadmap consistency and collision detection. Read-only.
 
 **Scope routing:**
 
@@ -45,6 +52,9 @@ $ARGUMENTS — phase number, or no args for milestone-wide planning, with option
 | `plan` (no args) | init + roadmap | milestone | Plan all phases in current milestone |
 | `plan 1` | init + roadmap | phase | Plan phase 1 only |
 | `plan --dir scratch/analyze-xxx` | none | inherited | Plan against specified analyze session |
+| `plan --revise "instructions"` | existing plan | revise | Modify existing plan with instructions |
+| `plan --revise` | existing plan | revise | Modify existing plan, ask user for instructions |
+| `plan --check scratch/plan-xxx` | existing plan | check | Verify existing plan (read-only) |
 
 **Upstream context:**
 - Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
@@ -141,6 +151,80 @@ Next steps:
   /maestro-execute --dir {dir}  -- Execute specific plan
   /maestro-plan {phase}         -- Re-plan with modifications
 ```
+
+### Mode: Revise (`--revise [instructions]`)
+
+Incrementally modify an existing plan without rebuilding from scratch.
+
+**Plan discovery:**
+- With `--dir`: use specified plan directory
+- Without `--dir`: auto-discover latest completed plan for current phase from `state.json.artifacts[]` (type=plan, status=completed, matching phase)
+
+**Execution flow:**
+
+1. **Load existing plan**
+   - Read `plan.json` + all `.task/TASK-*.json` from discovered directory
+   - Show current plan summary: task count, waves, status per task
+
+2. **Obtain revision instructions**
+   - If `--revise "instructions"` provided → parse as change directive
+   - If `--revise` without instructions → AskUserQuestion for what to change:
+     - Add/remove tasks
+     - Modify task scope, action, implementation
+     - Reorder waves or adjust dependencies
+     - Update convergence criteria
+   - Parse instructions into concrete changes
+
+3. **Apply targeted changes**
+   - Modify affected TASK files in-place
+   - If tasks added/removed: re-sequence task IDs, regenerate wave assignments
+   - Update plan.json summary (task count, wave structure)
+   - Preserve unmodified tasks completely
+
+4. **Re-run plan-checker (P4)**
+   - Validate modified plan with same checker as create mode
+   - Re-run collision detection against same-milestone plans
+   - Present check results for confirmation
+
+5. **Update artifact**
+   - Overwrite plan files in existing scratch directory
+   - Update artifact timestamp in state.json (no new artifact created)
+
+### Mode: Check (`--check <plan-dir>`)
+
+Read-only plan verification without modification.
+
+**Execution flow:**
+
+1. **Load plan**
+   - Read `plan.json` + `.task/TASK-*.json` from specified directory
+   - Read `.workflow/roadmap.md` for consistency comparison
+
+2. **Run checks**
+   - Plan-checker (P4 pipeline stage) — task quality, convergence criteria
+   - Roadmap consistency — plan tasks align with phase scope and requirements
+   - Collision detection — file overlaps with other plans in same milestone
+   - Dependency integrity — no broken cross-task dependencies
+
+3. **Produce check report**
+   ```
+   === PLAN CHECK ===
+   Plan: {plan_dir}/plan.json
+   Tasks: {total} ({completed} done, {pending} pending)
+
+   Checker: {PASS|WARN|FAIL} ({issues} issues)
+   Roadmap: {aligned|drift detected}
+   Collision: {clear|{N} overlaps}
+
+   Issues:
+     1. [{severity}] {description}
+
+   Suggested actions:
+     /maestro-plan --revise "fix instructions"  -- Apply fixes
+     /maestro-execute --dir {plan_dir}          -- Execute as-is
+   ```
+
+**No file modifications.** Pure verification + report.
 </execution>
 
 <error_codes>
@@ -148,6 +232,8 @@ Next steps:
 |------|----------|-----------|----------|
 | E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
 | E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
 | W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
 | W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
 | W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |

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/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>

package/.codex/skills/maestro-brainstorm/SKILL.md

@@ -196,7 +196,7 @@ Bash(`mkdir -p ${sessionFolder}/.brainstorming`)
 
 **Decomposition Rules**:
 
-1. **Mode detection**: Number = phase mode (resolve `.workflow/phases/{NN}-{slug}/`), text = scratch mode
+1. **Mode detection**: Number = phase mode (resolve via state.json artifact registry to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`), text = scratch mode
 2. **Project specs loading**: Read `.workflow/specs/` for architecture-aware analysis context
 3. **Role selection**: