maestro-flow 0.3.7 → 0.3.9

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

@@ -1,6 +1,6 @@
 ---
 name: maestro-learn
-description: Learning coordinator - analyze intent → route to optimal learn command chain → execute via Skill()
+description: Learning coordinator — route intent to learn commands, execute single or multi-step chains
 argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
 allowed-tools:
   - Read
@@ -12,23 +12,18 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Orchestrate all learn-* commands based on user intent. Routes natural language learning requests to the optimal learn command or multi-step chain.
+Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
 
-Two routing modes:
-1. **Intent-based**: User describes a learning goal → classify → select command/chain → confirm → execute
-2. **Direct**: User specifies a known chain name via `--chain`
-
-Produces session directory at `.workflow/learning/.maestro-learn/{session_id}/` with status.json tracking chain progress.
-Executes commands sequentially via Skill() with artifact propagation between steps.
+Executes commands sequentially via Skill() with session tracking.
 </purpose>
 
 <context>
 $ARGUMENTS — user learning intent text, or flags.
 
 **Flags:**
-- `-y` / `--yes` — Auto mode: skip clarification, skip confirmation
+- `-y` / `--yes` — Auto mode: skip confirmation
 - `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection). Valid: `follow`, `investigate`, `decompose`, `second-opinion`, `retro-git`, `retro-decision`, `deep-understand`, `pattern-catalog`, `full-retro`
+- `--chain <name>` — Force a specific chain (bypass intent detection)
 
 **Available learn commands:**
 | Command | Purpose |
@@ -37,8 +32,18 @@ $ARGUMENTS — user learning intent text, or flags.
 | `learn-investigate` | Hypothesis-driven question investigation |
 | `learn-decompose` | 4-dimension parallel pattern extraction |
 | `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro-git` | Git activity retrospective with metrics |
-| `learn-retro-decision` | Decision trace and lifecycle evaluation |
+| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
+
+**Available chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer a "how/why" question |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
 
 **Storage:**
 - `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
@@ -47,318 +52,89 @@ $ARGUMENTS — user learning intent text, or flags.
 
 <execution>
 
-### Step 1: Parse Arguments & Detect Mode
-
-```javascript
-const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)
-const dryRun = /\b--dry-run\b/.test($ARGUMENTS)
-const forcedChain = $ARGUMENTS.match(/--chain\s+(\S+)/)?.[1] || null
-const intent = $ARGUMENTS
-  .replace(/\b(-y|--yes|--dry-run)\b/g, '')
-  .replace(/--chain\s+\S+/g, '')
-  .trim()
-```
-
-**Display banner:**
-```
-============================================================
-  MAESTRO LEARN COORDINATOR
-============================================================
-  Mode:  {intent-based | forced-chain}
-  Auto:  {yes | no}
-  Input: {intent}
-```
-
----
-
-### Step 2: Analyze Intent
-
-**If `$FORCED_CHAIN` is set:**
-- Validate against known chains: `follow`, `investigate`, `decompose`, `second-opinion`, `retro-git`, `retro-decision`, `deep-understand`, `pattern-catalog`, `full-retro`
-- If valid: skip intent analysis, jump to **Step 4**
-- If invalid: **Error E005** — display valid chains
-
-**Extract structured intent:**
-
-```json
-{
-  "action":  "<from enum>",
-  "target":  "<file path | module | topic | wiki-id | null>",
-  "mode":    "<review | challenge | consult | null>",
-  "scope":   "<path filter | null>",
-  "flags":   "<--depth, --days, --save-wiki, etc.>"
-}
-```
-
-**Action enum:**
-
-| action | Triggered by (semantic) |
-|--------|------------------------|
-| `read` | Read code, follow along, walk through, understand file, 阅读, 跟读 |
-| `question` | Why does X, how does Y work, what happens if, investigate, 为什么, 怎么 |
-| `patterns` | Find patterns, decompose, catalog, extract conventions, 分解, 模式 |
-| `opinion` | Second opinion, review, challenge, critique, consult, 评审, 挑战 |
-| `retro-git` | Git activity, commit history, retro, work sessions, 提交回顾 |
-| `retro-decision` | Decision review, architecture decisions, decision quality, 决策回顾 |
-| `learn` | Generic learn, capture insight, remember — route to best fit |
-
-**Target resolution:**
-- Contains `/` or `\` or file extension → file path
-- Matches `<type>-<slug>` → wiki ID
-- Matches `--days`, `--author` → retro-git flags
-- Matches `--phase`, `--tag`, `--id` → retro-decision flags
-- Otherwise → topic string (passed as quoted argument)
-
----
-
-### Step 3: Route via action → command
-
-```javascript
-const routeMap = {
-  'read':           'follow',
-  'question':       'investigate',
-  'patterns':       'decompose',
-  'opinion':        'second-opinion',
-  'retro-git':      'retro-git',
-  'retro-decision': 'retro-decision',
-  'learn':          null,  // needs disambiguation
-};
-
-function routeLearnIntent(action, target, intent) {
-  // Direct mapping
-  if (routeMap[action]) return routeMap[action];
-
-  // Disambiguate generic 'learn' based on target and context
-  if (target && isFilePath(target))  return 'follow';
-  if (target && isWikiId(target))    return 'follow';
-  if (/retro|commit|git|session/i.test(intent))  return 'retro-git';
-  if (/decision|architect/i.test(intent))         return 'retro-decision';
-  if (/pattern|decompose|catalog/i.test(intent))  return 'decompose';
-  if (/opinion|review|challenge/i.test(intent))   return 'second-opinion';
-  if (/why|how|what if/i.test(intent))            return 'investigate';
-
-  // Fallback: ask user
-  return null;
-}
-```
-
-**Compute clarity score:**
-- 3: `action` recognized + `target` present + specific flags
-- 2: `action` recognized + `target` present
-- 1: `action` recognized but no `target`
-- 0: Cannot determine action
-
-**If clarity < 2 and not autoYes:**
-
-```
-AskUserQuestion:
-  header: "What would you like to learn?"
-  question: |
-    I need a bit more detail. What are you trying to do?
-  options:
-    - "Read through code/docs" → follow
-    - "Investigate a question" → investigate
-    - "Find patterns in code" → decompose
-    - "Get a second opinion" → second-opinion
-    - "Review git activity" → retro-git
-    - "Evaluate decisions" → retro-decision
-    - "Let me rephrase" → re-parse
-```
-
-Max 2 clarification rounds. If still unclear: **Error E002**.
+### Step 1: Parse & Route
 
----
+Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
 
-### Step 4: Select Chain & Confirm
+**If `--chain` specified:** validate against known chains, jump to Step 2.
 
-#### 4a: Map resolved command → chain
+**Intent routing table** (match first token or keywords):
 
-```javascript
-const chainMap = {
-  // Single-step chains
-  'follow':          [{ cmd: 'learn-follow', args: '{target} {flags}' }],
-  'investigate':     [{ cmd: 'learn-investigate', args: '"{target}" {flags}' }],
-  'decompose':       [{ cmd: 'learn-decompose', args: '{target} {flags}' }],
-  'second-opinion':  [{ cmd: 'learn-second-opinion', args: '{target} {flags}' }],
-  'retro-git':       [{ cmd: 'learn-retro-git', args: '{flags}' }],
-  'retro-decision':  [{ cmd: 'learn-retro-decision', args: '{flags}' }],
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| Wiki ID (`type-slug` pattern) | `follow` |
+| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
+| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
+| pattern, decompose, catalog, 分解, 模式 | `decompose` |
+| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
+| retro, git, commit, decision, 回顾 | `retro` |
+| thorough, deep, 全面, 深入 | `deep-understand` |
 
-  // Multi-step chains
-  'deep-understand': [
-    { cmd: 'learn-follow', args: '{target} --depth deep' },
-    { cmd: 'learn-decompose', args: '{target} --save-spec' },
-    { cmd: 'learn-second-opinion', args: '{target} --mode challenge' }
-  ],
-  'pattern-catalog': [
-    { cmd: 'learn-decompose', args: '{target} --save-spec --save-wiki' },
-    { cmd: 'learn-second-opinion', args: '{target} --mode review' }
-  ],
-  'full-retro': [
-    { cmd: 'learn-retro-git', args: '{flags}' },
-    { cmd: 'learn-retro-decision', args: '{flags}' }
-  ]
-};
+**If no match:** present menu via AskUserQuestion:
 ```
-
-**Chain upgrade heuristic** — single commands may upgrade to multi-step chains when context warrants it:
-- `follow` on a large module (>500 LOC) → suggest `deep-understand`
-- `decompose` with `--save-spec --save-wiki` → already a full catalog, no upgrade
-- User explicitly mentions "thorough" or "deep" or "全面" → upgrade to multi-step
-
-#### 4b: Assemble arguments
-
-- Replace `{target}` with resolved target path/topic/wiki-id
-- Replace `{flags}` with extracted flags (--depth, --days, --mode, --scope, etc.)
-- Clean empty placeholders
-
-#### 4c: Confirm (skip if autoYes)
-
-**If `$DRY_RUN`:**
+What would you like to do?
+1. Read through code/docs → follow
+2. Investigate a question → investigate
+3. Find patterns in code → decompose
+4. Get a second opinion → second-opinion
+5. Retrospective → retro
 ```
-============================================================
-  MAESTRO LEARN: {chain_name} (dry run)
-============================================================
-  Intent: {original_intent}
-  Target: {resolved_target}
 
-  Pipeline:
-    1. [{command}] args: {assembled_args}
-    ...
+Max 1 clarification round. If still unclear: error.
 
-  (Use without --dry-run to execute)
-============================================================
-```
-Exit after display.
+### Step 2: Resolve Target & Build Args
 
-**If not autoYes:**
-```
-AskUserQuestion:
-  header: "Confirm: {chain_name}"
-  question: |
-    Execute this learning chain?
-
-    Pipeline:
-      1. {command} — {description}
-      ...
+- File path → pass directly
+- Wiki ID → pass directly
+- Topic string → pass as quoted argument
+- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
 
-  options:
-    - "Execute" → proceed
-    - "Cancel" → exit
+**Chain → command mapping:**
 ```
-
----
-
-### Step 5: Setup Tracking
-
-```bash
-SESSION_ID="learn-$(date +%Y%m%d-%H%M%S)"
-SESSION_DIR=".workflow/learning/.maestro-learn/${SESSION_ID}"
-mkdir -p "${SESSION_DIR}"
+follow          → Skill("learn-follow", "{target} {flags}")
+investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → Skill("learn-decompose", "{target} {flags}")
+second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
+retro           → Skill("learn-retro", "{flags}")
+deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
+pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
 ```
 
-Write `${SESSION_DIR}/status.json`:
-```json
-{
-  "session_id": "{SESSION_ID}",
-  "created_at": "{ISO timestamp}",
-  "intent": "{original_intent}",
-  "chain": "{chain_name}",
-  "steps": [
-    { "index": 0, "cmd": "{command}", "args": "{args}", "status": "pending" }
-  ],
-  "current_step": 0,
-  "auto_mode": false
-}
-```
+### Step 3: Confirm & Execute
 
----
-
-### Step 6: Execute Chain
-
-For each step in the chain (starting from `$STEP_INDEX` or 0):
-
-1. Update `status.json`: set step status to `"running"`
-2. Display step header:
-   ```
-   ── Step {N}/{total}: {command} ──────────────────────────
-   ```
-3. Execute: `Skill({ skill: "{command}", args: "{assembled_args}" })`
-4. On success:
-   - Update step status to `"completed"`
-   - Record duration
-   - Continue to next step
-5. On failure:
-   - Update step status to `"failed"`, record error
-   - **If autoYes**: skip and continue (log warning)
-   - **If interactive**:
-     ```
-     AskUserQuestion:
-       header: "Step {N} failed"
-       question: "{error summary}"
-       options:
-         - "Retry" → re-execute same step
-         - "Skip" → continue to next step
-         - "Abort" → exit chain
-     ```
-
----
-
-### Step 7: Session Summary
-
-After all steps complete (or chain aborted):
-
-```
-=== MAESTRO LEARN SESSION COMPLETE ===
-Session: {session_id}
-Chain:   {chain_name} ({steps_completed}/{steps_total} steps)
-Mode:    {auto | interactive}
-
-Steps:
-  [{status_icon}] {N}. {command_name} — {duration}
-
-Artifacts:
-  - {list of files written to .workflow/learning/}
-
-Next:
-  {suggested_next_action based on chain type}
-```
+**If `--dry-run`:** display chain plan and exit.
 
-**Next-step routing by chain type:**
+**If not `-y`:** show plan, ask for confirmation.
 
-| Chain | Suggested next |
-|-------|---------------|
-| `follow` | "Decompose patterns? → `/maestro-learn --chain decompose`" |
-| `investigate` | "Follow-along on discovered code? → `/maestro-learn follow <path>`" |
-| `decompose` | "Get second opinion? → `/maestro-learn --chain second-opinion`" |
-| `second-opinion` | "Create issue for findings? → `/manage-issue create`" |
-| `retro-git` | "Deep dive on hotspot? → `/maestro-learn follow <path>`" |
-| `retro-decision` | "Investigate stale decision? → `/maestro-learn investigate <question>`" |
-| `deep-understand` | "Browse insights → `/manage-learn list`" |
-| `pattern-catalog` | "Load specs → `/spec-load`" |
-| `full-retro` | "Browse all insights → `/manage-learn list --tag retro`" |
+**Execute:**
+1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+2. Write `status.json` with chain steps
+3. Execute each step via `Skill()`:
+   - On success: mark completed, continue
+   - On failure (interactive): ask retry/skip/abort
+   - On failure (auto): skip and continue
+4. Display session summary with artifact list and next-step suggestion
 
 </execution>
 
 <error_codes>
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
-| E001 | error | No intent provided and no learning context | Provide a learning goal or target |
-| E002 | error | Clarity too low after 2 clarification rounds | Show parsed intent, ask user to rephrase |
-| E003 | error | Chain step failed + user chose abort | Record partial progress in status.json |
-| E005 | error | Invalid chain name provided with --chain | Show valid chain names: follow, investigate, decompose, second-opinion, retro-git, retro-decision, deep-understand, pattern-catalog, full-retro |
-| W001 | warning | Intent ambiguous between two commands | Present options, let user choose |
+| E001 | error | No intent provided | Provide a learning goal or use --chain |
+| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
+| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous between commands | Present options |
 | W002 | warning | Chain step completed with warnings | Log and continue |
-| W003 | warning | `.workflow/learning/` not found | Auto-create and proceed |
 </error_codes>
 
 <success_criteria>
-- [ ] Intent classified with action, target, clarity_score
-- [ ] Command/chain selected and confirmed (or auto-confirmed with -y)
-- [ ] Session directory created at `.workflow/learning/.maestro-learn/{session_id}/`
-- [ ] status.json tracks per-step progress
-- [ ] All chain steps executed via Skill() with proper argument propagation
-- [ ] Target resolved (file path, wiki-id, topic) and passed to downstream commands
-- [ ] Error handling: retry/skip/abort per step (auto-skip in -y mode)
-- [ ] Session summary displayed on completion with next-step routing
+- [ ] Intent routed to correct chain (or --chain validated)
+- [ ] Target resolved and arguments assembled
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed via Skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
 - [ ] No files modified outside `.workflow/learning/`
 </success_criteria>

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

@@ -0,0 +1,77 @@
+---
+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>

package/.claude/commands/maestro-milestone-audit.md

@@ -1,60 +1,72 @@
----
-name: maestro-milestone-audit
-description: Audit current milestone for cross-phase integration gaps
-argument-hint: "[<milestone>]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-
-<purpose>
-Audit milestone completion with cross-phase integration checks. Identifies which phases belong to the milestone, spawns a workflow-integration-checker agent to validate that all phases work together correctly (shared interfaces, data contracts, dependency chains), and produces an audit report with gap analysis and fix suggestions.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-audit.md
-</required_reading>
-
-<context>
-Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
-
-**Requires:** All phases in the milestone should be completed or verifying.
-
-**State files:**
-- `.workflow/state.json` -- current_milestone, phases_completed
-- `.workflow/roadmap.md` -- milestone-to-phase mapping
-- `.workflow/phases/{NN}-{slug}/index.json` -- phase metadata per phase
-- `.workflow/phases/{NN}-{slug}/verification.json` -- phase verification results
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-audit.md' completely.
-
-**Next-step routing on completion:**
-- Verdict PASS → Skill({ skill: "maestro-milestone-complete", args: "{milestone}" })
-- Verdict FAIL, integration gaps → Skill({ skill: "maestro-plan", args: "{affected_phase} --gaps" })
-- Verdict FAIL, incomplete phases → Skill({ skill: "maestro-execute", args: "{incomplete_phase}" })
-- Gaps fixed, need re-audit → Skill({ skill: "maestro-milestone-audit", args: "{milestone}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone identifier required | Check arguments format, re-run with correct input |
-| E002 | error | Milestone not found in roadmap | Check arguments format, re-run with correct input |
-| E003 | error | Phases incomplete for this milestone | Complete remaining phases before audit |
-| W001 | warning | Phase lacks completed_at — may not have been formally transitioned | Run phase-transition for the phase first |
-</error_codes>
-
-<success_criteria>
-- [ ] All phases in milestone identified and status checked
-- [ ] Integration check completed via workflow-integration-checker agent
-- [ ] Audit report written with gap analysis and fix suggestions
-- [ ] Cross-phase integration issues identified and categorized
-- [ ] Clear verdict (PASS/FAIL) with next-step routing
-</success_criteria>
+---
+name: maestro-milestone-audit
+description: Audit current milestone for cross-phase integration gaps
+argument-hint: "[<milestone>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+
+<purpose>
+Audit milestone completion using the artifact registry. Checks:
+1. Phase coverage — every phase in roadmap has plan + execute artifacts (completed)
+2. Ad-hoc completeness — all adhoc artifacts are completed (or explicitly skipped)
+3. Execution completeness — all tasks in executed plans are completed
+4. Cross-artifact integration — interfaces, data contracts, configuration consistency
+
+Data source: `state.json.artifacts[]` filtered by current milestone.
+Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-audit.md
+</required_reading>
+
+<context>
+Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json).
+
+**Requires:** All phases in the milestone should have completed execute artifacts.
+
+**Data source:**
+- `.workflow/state.json` — artifacts[], current_milestone, milestones[]
+- `.workflow/roadmap.md` — milestone-to-phase mapping
+- Plan scratch dirs — for task status verification
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-audit.md' completely.
+
+**Audit checklist (from architecture):**
+1. Phase coverage: each phase in roadmap has analyze → plan → execute chain
+2. Ad-hoc completeness: all adhoc artifacts completed or skipped
+3. Execution completeness: all tasks in executed plans completed
+4. Cross-artifact integration: interface compatibility, data contracts, config consistency
+
+**Next-step routing on completion:**
+- Verdict PASS → `/maestro-milestone-complete {milestone}`
+- Verdict FAIL, integration gaps → `/maestro-plan --gaps`
+- Verdict FAIL, incomplete execution → `/maestro-execute`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone identifier required | Check arguments format |
+| E002 | error | Milestone not found in state.json | Check milestone ID |
+| E003 | error | No execute artifacts found for milestone | Run maestro-execute first |
+| W001 | warning | Some phases lack complete artifact chains | Review incomplete phases |
+</error_codes>
+
+<success_criteria>
+- [ ] All phases in milestone identified from roadmap
+- [ ] Artifact chains verified (ANL→PLN→EXC) per phase
+- [ ] Ad-hoc artifacts checked for completion
+- [ ] Integration check completed (shared interfaces, data contracts)
+- [ ] Audit report written with clear PASS/FAIL verdict
+- [ ] Next-step routing provided
+</success_criteria>