maestro-flow 0.3.11 → 0.3.13

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

@@ -0,0 +1,176 @@
+---
+name: maestro-update
+description: Interactive workflow migration — detect version, preview changes, apply upgrades
+argument-hint: "[--dry-run] [--force]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Detect the current `.workflow/` schema version, show available migrations, and interactively apply them step-by-step. Uses a migration registry that supports incremental version upgrades (e.g., 1.0 → 2.0 → 3.0).
+
+Each migration step is previewed before execution. The user confirms each step in a loop.
+</purpose>
+
+<context>
+$ARGUMENTS — optional flags.
+
+**Flags:**
+- `--dry-run` -- Preview migration plan without executing
+- `--force` -- Skip confirmation prompts (apply all pending migrations)
+
+**Migration registry:** `src/migrations/`
+- Each migration is a standalone file (e.g., `v1-to-v2.ts`) exporting a `MigrationDef`
+- All migrations are registered via `src/migrations/index.ts`
+- Registry auto-chains: detects current version → walks chain → applies in order
+- To add a new migration: create `src/migrations/v{N}-to-v{N+1}.ts`, register in `index.ts`
+
+**CLI runner:** `src/migrations/run.ts`
+- Executable entrypoint: `npx tsx src/migrations/run.ts [root] [--dry-run] [--force] [--json]`
+- Outputs JSON (with `--json`) or human-readable text
+
+**State version source:** `.workflow/state.json` → `version` field
+</context>
+
+<execution>
+
+### Step 1: Detect Current State
+
+```
+1. Read .workflow/state.json
+2. Extract version field (default "1.0" if missing)
+3. Display:
+
+   === Maestro Workflow Update ===
+   Project:  {project_name}
+   Version:  {version}
+   Location: {.workflow/ path}
+```
+
+### Step 2: Dry-Run Preview
+
+Run the migration CLI in dry-run + JSON mode to get the full plan:
+
+```bash
+npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+```
+
+Parse the JSON output. If status is `up-to-date`:
+```
+Already up to date (v{version})
+```
+→ EXIT
+
+Otherwise display the migration plan:
+```
+Pending Migrations ({N} step(s)):
+
+  1. [v{from} → v{to}] {name}
+     {description}
+
+  2. [v{from} → v{to}] {name}
+     {description}
+```
+
+If `--dry-run` flag was passed by user → display plan and EXIT.
+
+### Step 3: Interactive Confirmation Loop
+
+For each migration step (unless `--force`):
+
+```
+LOOP for step_index = 1 to N:
+
+  Display:
+    --- Step {step_index}/{N}: {name} ---
+    Version: v{from} → v{to}
+
+    Changes:
+      {description, indented}
+
+  IF NOT --force:
+    AskUserQuestion: "Apply this migration?"
+    Options: [yes / skip / abort]
+
+    - "yes"   → proceed to Step 4 (execute)
+    - "skip"  → WARN "Skipping may break the migration chain"
+                 continue to next step
+    - "abort" → display summary of what was applied so far → EXIT
+
+  IF --force:
+    → proceed to Step 4 (execute)
+```
+
+### Step 4: Execute Single Migration
+
+```
+1. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{from}-{timestamp}
+
+2. Run migration:
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   
+   NOTE: The runner executes ALL pending migrations. For step-by-step control,
+   read state.json, call the migration function directly, or use the runner
+   which stops on first failure.
+
+3. Parse result JSON and display:
+
+   {status_icon} Step {N} completed: {name}
+   Summary: {summary}
+   Changes:
+     - {change_1}
+     - {change_2}
+     - ...
+
+4. If failed:
+   Display: "Migration failed: {summary}"
+   Display: "Backup available at: {backup_path}"
+   Display: "Restore with: cp {backup_path} .workflow/state.json"
+   → EXIT
+
+5. Continue loop to next step
+```
+
+### Step 5: Summary
+
+After all steps completed (or user aborted):
+
+```
+=== Migration Complete ===
+Applied: {applied_count} / {total_count} migration(s)
+Skipped: {skipped_count}
+Version: v{original} → v{final}
+Backup:  .workflow/state.json.backup-v{original}-{timestamp}
+
+Next steps:
+  /manage-status  -- Verify project state
+  /maestro        -- Continue workflow
+```
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | .workflow/state.json not found | Run /maestro-init first |
+| E002 | error | state.json parse error | Check file for corruption |
+| E003 | error | Migration function failed | Restore from backup |
+| W001 | warning | Skipped migration may break version chain | Re-run /maestro-update later |
+| W002 | warning | tsx not available | Install tsx: npm i -D tsx |
+</error_codes>
+
+<success_criteria>
+- [ ] Current version detected from state.json
+- [ ] Dry-run preview shows full migration plan without execution
+- [ ] Each step confirmed interactively (unless --force)
+- [ ] Backup created before each migration
+- [ ] Migration executed and result displayed with change list
+- [ ] Abort stops cleanly with partial summary
+- [ ] Summary shows applied/skipped counts and version change
+</success_criteria>

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

@@ -20,7 +20,7 @@ Verify execution results through three complementary methods:
 
 Supports dual-level verification:
 - **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
-- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/verify-{milestone}-{date}/milestone-verification.json`
+- **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.
 </purpose>
@@ -51,7 +51,7 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 | `verify --dir scratch/plan-xxx` | Single plan: verify specific plan directory |
 
 **Single plan output**: `verification.json` appended to plan's scratch dir
-**Milestone output**: `scratch/verify-{milestone-slug}-{date}/milestone-verification.json`
+**Milestone output**: `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 **Artifact registration**: On completion, register VRF artifact:
 ```jsonc
@@ -61,7 +61,7 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
   "milestone": "{current_milestone or null}",
   "phase": null,
   "scope": "milestone",
-  "path": "scratch/verify-{milestone-slug}-{date}",
+  "path": "scratch/{YYYYMMDD}-verify-M{N}-{slug}",  // M{N} = milestone number
   "status": "completed",
   "depends_on": ["EXC-001", "EXC-002", ...],
   "harvested": false,
@@ -74,6 +74,21 @@ $ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
 <execution>
 Follow '~/.maestro/workflows/verify.md' completely.
 
+### Post-verify Knowledge Inquiry
+
+After verification completes, evaluate inquiry triggers:
+
+1. **Anti-pattern detection**: If anti-pattern scan found blockers (TODO/FIXME, stubs, empty returns):
+   → Ask: "Verification found {N} anti-patterns. Should `quality-rules.md` be updated to enforce these checks? (`/spec-add quality`)"
+
+2. **Constraint violation**: If Goal-Backward check found constraint_violations or missing wiring:
+   → Ask: "Verification found architecture constraint violations. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+3. **Test coverage gaps**: If Nyquist gaps found with recurring pattern (same module/type across tasks):
+   → Ask: "Persistent test coverage gap detected in {module}. Should it be added to `test-conventions.md` as a required test area? (`/spec-add test`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
 **Next-step routing on completion:**
 - All checks pass, no gaps → /quality-review
 - Gaps found (must-have failures or anti-pattern blockers) → /maestro-plan --gaps

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-codebase-rebuild.md

@@ -70,7 +70,6 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] doc-index.json generated and valid
 - [ ] All documentation files regenerated
 - [ ] state.json updated with rebuild timestamp
-- [ ] project-tech.json refreshed with detected tech stack
 - [ ] project.md Tech Stack section updated if changes detected
 - [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
 </success_criteria>

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

@@ -76,7 +76,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
 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>`
+   - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id> --created-by manage-harvest --source-ref HRV-<fragment_id> --category <fragment_category>`
    - 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.

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

@@ -49,7 +49,7 @@ Arguments: $ARGUMENTS
 
 **Storage:**
 - `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with `quality-retrospective` output)
-- `.workflow/learning/learning-index.json` — searchable index (mirrors `memory-index.json` schema)
+- `.workflow/learning/learning-index.json` — searchable index
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 </context>
@@ -58,8 +58,8 @@ Arguments: $ARGUMENTS
 Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 
 1. **No agent or CLI calls** — this is a pure file operation: parse → infer → append → confirm. Category inference is keyword-based, not LLM-based.
-2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and resolve the matching directory slug. `--phase 0` forces no link.
-3. **Match memory-index pattern** — `learning-index.json` schema mirrors `memory-index.json` from `workflows/memory.md` (entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, phase, phase_slug, confidence, routed_to, routed_id).
+2. **Auto-link phase** — read `.workflow/state.json` for `current_phase` and derive phase context from artifact registry (`state.json.artifacts[]`). `--phase 0` forces no link.
+3. **Index schema** — `learning-index.json` entries[] with id, type, timestamp, file, summary, tags, plus learn-specific fields: lens, category, confidence, routed_to, routed_id.
 4. **Stable INS ids** — `INS-{8 lowercase hex}` from `hash(insight_text + category + phase)`. Deterministic: same content in same context always produces the same ID.
 5. **Append-only lessons.jsonl** — never rewrite existing rows; duplicate detection is the user's job at search time.
 6. **Bootstrap on demand** — create `.workflow/learning/`, `lessons.jsonl`, `learning-index.json` on first use; do not require them to exist upfront.
@@ -73,7 +73,7 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
 | E004 | error | Insight id not found in lessons.jsonl | show |
-| W001 | warning | Auto-phase detection found a current_phase but no matching directory; phase set to null | capture |
+| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 | W002 | warning | learning-index.json out of sync with lessons.jsonl (different row count); offer to rebuild | list/search |
 </error_codes>
 
@@ -81,7 +81,7 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 - [ ] Mode correctly routed (capture / list / search / show)
 - [ ] Capture: `lessons.jsonl` row appended with valid JSON and all required fields
 - [ ] Capture: `learning-index.json` updated with matching entry
-- [ ] Capture: phase auto-link resolves correctly when `state.json` has `current_phase`
+- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match

package/.claude/commands/manage-memory-capture.md

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Capture session working memory into `.workflow/memory/` for cross-session recovery. Compact mode only: full session compression for recovery. Maintains a `memory-index.json` for search and retrieval. Invoked when saving session state before context loss.
+Capture session working memory into `.workflow/memory/` for cross-session recovery. Compact mode only: full session compression for recovery. Entries are created via `maestro wiki create --type memory` and automatically indexed in `.workflow/wiki-index.json`. Invoked when saving session state before context loss.
 
 **Note:** Quick tips/notes have been moved to `manage-learn tip <text>`. Use that command for atomic knowledge capture.
 </purpose>
@@ -29,8 +29,8 @@ Arguments: $ARGUMENTS
 - No arguments — Defaults to compact mode
 
 **Storage:**
-- `.workflow/memory/` — Memory entries directory
-- `.workflow/memory/memory-index.json` — Searchable index of all entries
+- `.workflow/memory/` — Memory entries directory (via `maestro wiki create --type memory`)
+- `.workflow/wiki-index.json` — Unified wiki index (auto-updated on create)
 </context>
 
 <execution>
@@ -49,7 +49,7 @@ Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
 <success_criteria>
 - [ ] Compact mode executed
 - [ ] Entry markdown file written to `.workflow/memory/`
-- [ ] `memory-index.json` updated with new entry metadata
+- [ ] `wiki-index.json` auto-updated via wiki create
 - [ ] All session fields populated (objective, files, decisions, plan)
 - [ ] Execution plan preserved VERBATIM (not summarized)
 - [ ] All file paths are ABSOLUTE

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

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 
 | Store | Path | Format | Index |
 |-------|------|--------|-------|
-| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `memory-index.json` |
+| `workflow` | `.workflow/memory/` | `MEM-*.md`, `TIP-*.md` (legacy only — new tips go to `manage-learn tip`) | `.workflow/wiki-index.json` (unified) |
 | `system` | `~/.claude/projects/{project}/memory/` | `MEMORY.md` + topic `.md` files | None (flat files) |
 
 **System memory path detection:**

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

@@ -0,0 +1,62 @@
+---
+name: manage-wiki
+description: Wiki knowledge graph management — health dashboard, orphan cleanup, entry search, and graph statistics
+argument-hint: "[health|search|cleanup|stats] [options]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, and graph statistics — the day-to-day operations that keep the knowledge graph healthy.
+
+Complements `/wiki-connect` (link discovery) and `/wiki-digest` (synthesis) with operational tooling.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| No args | Same as `health` |
+
+**Flags:**
+- `--type <type>` — Filter by wiki type: spec, memory, note, lesson, issue
+- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--json` — Output in JSON format
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/wiki-manage.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] Next-step suggestions provided
+</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):
+  - 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 |
 | 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

@@ -39,22 +39,69 @@ User's issue: $ARGUMENTS
 - `--from-uat <phase>` -- Read gaps from phase's uat.md as pre-filled symptoms
 - `--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
-- `.workflow/scratch/debug-*/` -- Standalone debug sessions
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/ (source of code changes)
+- **review** → review.json (findings guide hypothesis formation)
+- **debug** → understanding.md, evidence.ndjson (prior investigations, avoid re-investigation)
+- **test** → uat.md (--from-uat gap source), .tests/
+
+Extract conclusions from related artifacts that may affect this debug session — review findings guide investigation direction, prior debug avoids redundant work.
+
+**Output**: `DEBUG_DIR = .workflow/scratch/{YYYYMMDD}-debug-P{N}-{slug}/` (P{N} = phase number when phase-scoped; omit for standalone)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/debug.md' completely.
 
+**Output writes to DEBUG_DIR** (`scratch/{YYYYMMDD}-debug-P{N}-{slug}/`):
+- understanding.md, evidence.ndjson, diagnosis-summary.json
+
+**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}",  // or {YYYYMMDD}-debug-{slug} for standalone
+  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
+
+After root cause is confirmed, evaluate inquiry triggers:
+
+1. **Recurring pattern**: If root cause matches a recurring pattern (similar to prior debug sessions):
+   → Ask: "This root cause pattern has appeared before. Should it be documented in `debug-notes.md` to prevent recurrence? (`/spec-add debug`)"
+
+2. **Non-obvious fix**: If fix involved a non-obvious approach or workaround:
+   → Ask: "This fix used a non-obvious strategy. Should it be recorded as a learning? (`/spec-add learning`)"
+
+3. **Architectural gap**: If root cause traces to architectural boundary violation or missing constraint:
+   → Ask: "Root cause points to an architectural gap. Should `architecture-constraints.md` be updated? (`/spec-add arch`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })`.
+
 **Next-step routing on completion:**
 - Root cause found, fix needed → `/maestro-plan {phase} --gaps`
 - Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
 - Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
 - Standalone fix already applied → `/maestro-verify {phase}`
-
-Note: Debug output (.debug/) is auto-loaded by maestro-plan --gaps.
 </execution>
 
 <error_codes>

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

@@ -43,17 +43,19 @@ 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
-- `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
+- Retrospective output (resolve via `state.json.artifacts[]` → `.workflow/scratch/` path):
+  - retrospective.md — human-readable record
+  - retrospective.json — structured record
+- `.workflow/specs/{category-file}.md` — `<spec-entry>` entries appended to matching category files (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)
 - `.workflow/learning/lessons.jsonl` — append-only insight log
 - `.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):
+  - 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>
@@ -67,7 +69,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
-7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{phase_dir}/.history/` with a timestamp suffix first.
+7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{artifact_dir}/.history/` with a timestamp suffix first.
 </execution>
 
 <error_codes>
@@ -92,7 +94,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] `retrospective.md` written and human-readable (tweetable, metrics table, per-lens findings, insights, routing table)
 - [ ] Each insight has a stable `INS-{8hex}` id
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
-- [ ] Spec stubs (if any) written to `.workflow/specs/SPEC-retro-*.md` with proper frontmatter
+- [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
 - [ ] `lessons.jsonl` appended with one row per insight regardless of routing target

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

@@ -53,17 +53,49 @@ 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}/`:
-- index.json (phase metadata, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with file lists)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-- verification.json (if exists — incorporate verification gaps as review context)
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (source of files to review)
+- **review** → review.json (prior verdict, findings — for delta comparison)
+- **debug** → understanding.md, evidence.ndjson (confirmed root causes)
+- **test** → uat.md, .tests/ (user-observable gaps)
+
+Extract conclusions from related artifacts that may affect this review. Pass as prior quality context to reviewer agents — avoid redundant work, focus on gaps and regressions.
+
+**Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/review.md' completely.
 
+**Output writes to REVIEW_DIR** (not EXEC_DIR):
+- `REVIEW_DIR/review.json` — findings, severity distribution, verdict
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // REV-001
+  type: "review",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-review-P{N}-{slug}",    // relative to .workflow/
+  status: "completed",
+  depends_on: exec_art.id,                 // or prior debug/review if re-review
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+
 **Report format on completion:**
 
 ```
@@ -87,7 +119,7 @@ Verdict: {PASS | WARN | BLOCK}
 Issues Created: {issue_count}
 
 Files:
-  {phase_dir}/review.json
+  {REVIEW_DIR}/review.json
 
 Next steps:
   {verdict_based_routing}

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

@@ -47,5 +47,5 @@ Follow '~/.maestro/workflows/sync.md' completely.
 - [ ] Codebase docs refreshed for all affected components
 - [ ] doc-index.json reflects current file state
 - [ ] Changes tracked and logged
-- [ ] project-tech.json refreshed if dependency manifests changed
+- [ ] project.md Tech Stack section refreshed if dependency manifests changed
 </success_criteria>

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):
+  - 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>