maestro-flow 0.3.8 → 0.3.10

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

@@ -1,130 +1,167 @@
----
-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>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create a verified execution plan (plan.json + .task/TASK-*.json) for a roadmap phase through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Invoked when a phase is ready to be planned after init/brainstorm. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/plan.md
-</required_reading>
-
-<deferred_reading>
-- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
-- [task.json](~/.maestro/templates/task.json) — read when generating task files
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number or slug)
-
-**Flags:**
-- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
-- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
-- `--auto` -- Skip interactive clarification (P2), use defaults
-- `--gaps` -- Gap closure mode: load verification.json gaps, skip exploration, plan only gap fixes
-- `--dir <path>` -- Use arbitrary directory instead of phase resolution (scratch mode, skip roadmap validation)
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/` (or `--dir` path):
-- context.md (user decisions from Skill({ skill: "maestro-analyze" }))
-- index.json (phase metadata)
-- spec-ref from index.json (if set)
-- codebase/doc-index.json (if exists)
-- Wiki prior knowledge via `maestro wiki search` (offline, graceful degradation)
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before starting the plan pipeline, run:
-```
-Bash("maestro team preflight --phase <phase-number>")
-```
-If exit code is 1, the command prints warnings about teammates active on the same phase. Present the warnings to the user and ask whether to proceed. If the user confirms or says "force", continue. If they decline, abort with a clear message.
-
-If exit code is 0, or `maestro team preflight` is unavailable (e.g., team mode not enabled), continue normally.
-
-Follow '~/.maestro/workflows/plan.md' completely.
-
-### Wiki Knowledge Search (P1 addition)
-
-During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
-
-```
-// Extract search keywords from phase goal/title in index.json
-phase_keywords = extract key terms from index.json goal + title (2-5 terms)
-
-// Run wiki search (offline mode, no --live flag)
-wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
-
-IF wiki_result exit code != 0 OR wiki_result is empty OR parse fails:
-  display "W003: Wiki search unavailable, continuing without prior knowledge"
-  wiki_context = ""
-ELSE:
-  entries = JSON.parse(wiki_result).entries (limit to first 10)
-  IF entries.length == 0:
-    wiki_context = "## Wiki Prior Knowledge\nNo related wiki entries found."
-  ELSE:
-    wiki_context = "## Wiki Prior Knowledge\n"
-    FOR each entry in entries:
-      wiki_context += "- [${entry.type}] ${entry.id}: ${entry.title}"
-      IF entry.summary:
-        wiki_context += " — ${entry.summary}"
-      wiki_context += "\n"
-
-// Inject wiki_context into exploration context alongside other P1 outputs
-```
-
-This step uses offline mode by default (no `--live` flag) so it works without the dashboard running. The structured `## Wiki Prior Knowledge` block is passed to downstream planning stages as additional context.
-
-**Report format on completion:**
-
-```
-=== PLAN READY ===
-Phase: {phase_name}
-Tasks: {task_count} tasks in {wave_count} waves
-Check: {checker_status} (iteration {check_count}/{max_checks})
-
-Plan: {phase_dir}/plan.json
-Tasks: {phase_dir}/.task/TASK-*.json
-
-Next steps:
-  Skill({ skill: "maestro-execute", args: "{phase}" })  -- Execute the plan
-  Skill({ skill: "maestro-plan", args: "{phase}" })     -- Re-plan with modifications
-
-Note: If this was a --gaps plan, after execute run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are closed.
-```
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | --gaps requires verification.json to exist | Check arguments format, re-run with correct input |
-| 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 |
-</error_codes>
-
-<success_criteria>
-- [ ] plan.json written to phase directory with summary, approach, task_ids, waves
-- [ ] .task/TASK-*.json files created for each task
-- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
-- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
-- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
-- [ ] Plan-checker passed (or minor issues acknowledged)
-- [ ] User confirmation captured (execute/modify/cancel)
-- [ ] index.json updated with plan status and timestamps
-</success_criteria>
+---
+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>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - 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.
+
+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>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+
+**Flags:**
+- `--collab` -- Multi-planner collaborative mode (spawn N workflow-collab-planner agents with pre-allocated TASK ID ranges)
+- `--spec SPEC-xxx` -- Reference a task-spec for requirements input
+- `--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)
+
+**Scope routing:**
+
+| Invocation | Precondition | Scope | Behavior |
+|-----------|-------------|-------|----------|
+| `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 |
+
+**Upstream context:**
+- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
+- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+
+**Output directory**: `scratch/plan-{slug}-{date}/` (relative to `.workflow/`)
+
+**Output structure:**
+```
+scratch/plan-{slug}-{date}/
+├── plan.json            # summary, task_ids[], waves[] with phase labels
+└── .task/
+    ├── TASK-001.json    # { phase: 1, phase_slug: "auth", ... }
+    ├── TASK-002.json
+    └── ...
+```
+
+**Collision detection**: After plan generation, before user confirmation, check for file overlaps with existing plans in same milestone. Non-blocking warning only.
+
+**Artifact registration**: On completion, register in `state.json.artifacts[]`:
+```jsonc
+{
+  "id": "PLN-{NNN}",
+  "type": "plan",
+  "milestone": "{current_milestone or null}",
+  "phase": "{phase_number or null}",
+  "scope": "{milestone|phase|adhoc|standalone}",
+  "path": "scratch/plan-{slug}-{date}",
+  "status": "completed",
+  "depends_on": "{ANL-NNN or null}",
+  "harvested": false,
+  "created_at": "...",
+  "completed_at": "..."
+}
+```
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Wiki Knowledge Search (P1 addition)
+
+During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
+
+```
+phase_keywords = extract key terms from goal/title (2-5 terms)
+wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+
+IF wiki_result exit code != 0 OR empty:
+  display "W003: Wiki search unavailable, continuing without prior knowledge"
+ELSE:
+  entries = JSON.parse(wiki_result).entries (limit to first 10)
+  wiki_context = structured block for downstream stages
+```
+
+### Issue Linkback (--gaps mode)
+
+After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
+
+```
+For each created TASK-{NNN}.json that has issue_id:
+  Update corresponding issue in .workflow/issues/issues.jsonl:
+    task_refs: append TASK-{NNN} to array
+    task_plan_dir: relative path to .task/ directory
+    status: "planned"
+    updated_at: now()
+  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
+```
+
+This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
+
+**Report format on completion:**
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: {scratch_dir}/plan.json
+Tasks: {scratch_dir}/.task/TASK-*.json
+
+Next steps:
+  /maestro-execute              -- Execute the plan
+  /maestro-execute --dir {dir}  -- Execute specific plan
+  /maestro-plan {phase}         -- Re-plan with modifications
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| 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 |
+| 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 |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel)
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>

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

@@ -33,10 +33,10 @@ Parse for:
 Follow '~/.maestro/workflows/quick.md' completely.
 
 **Next-step routing on completion:**
-- Task done, --full verification passed → Skill({ skill: "manage-status" })
-- Task done, verification found gaps → Skill({ skill: "quality-debug", args: "{issue}" })
-- Task done, want to sync docs → Skill({ skill: "quality-sync" })
-- Need a full phase workflow instead → Skill({ skill: "maestro-plan", args: "{phase}" })
+- Task done, --full verification passed → /manage-status
+- Task done, verification found gaps → /quality-debug {issue}
+- Task done, want to sync docs → /quality-sync
+- Need a full phase workflow instead → /maestro-plan {phase}
 </execution>
 
 <error_codes>

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

@@ -66,10 +66,10 @@ Auto-selection: ≥3 high uncertainty factors → Progressive, ≥3 low → Dire
 Follow '~/.maestro/workflows/roadmap.md' completely.
 
 **Next-step routing on completion:**
-- Roadmap approved → Skill({ skill: "maestro-analyze", args: "1" })
-- Simple project, skip analysis → Skill({ skill: "maestro-plan", args: "1" })
-- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
-- View project dashboard → Skill({ skill: "manage-status" })
+- Roadmap approved → /maestro-analyze 1
+- Simple project, skip analysis → /maestro-plan 1
+- Need UI design first → /maestro-ui-design 1
+- View project dashboard → /manage-status
 </execution>
 
 <error_codes>
@@ -91,5 +91,5 @@ Follow '~/.maestro/workflows/roadmap.md' completely.
 - [ ] No circular dependencies in phase ordering
 - [ ] User approved roadmap (or auto-approved with -y)
 - [ ] `.workflow/roadmap.md` written with phase details, scope decisions, and progress table
-- [ ] Phase directories created under `.workflow/phases/`
+- [ ] No phase directories created (phases are labels in roadmap, not directories)
 </success_criteria>

package/.claude/commands/maestro-spec-generate.md

@@ -38,7 +38,7 @@ $ARGUMENTS -- idea text, @file reference to requirements document, or brainstorm
 **Input types:**
 - Direct text: `"Build a real-time collaboration platform"`
 - File reference: `@requirements.md` or `@design-brief.txt`
-- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/` or `.workflow/phases/*/`)
+- Brainstorm import: `--from-brainstorm WFS-xxx` (reads `.workflow/scratch/brainstorm-*/`)
 
 **Output location:** `.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/`
 
@@ -62,10 +62,10 @@ maestro-init → maestro-roadmap → roadmap.md directly
 Follow '~/.maestro/workflows/spec-generate.md' completely.
 
 **Next-step routing on completion:**
-- Roadmap generated, ready to plan → Skill({ skill: "maestro-plan", args: "1" })
-- Need UI design first → Skill({ skill: "maestro-ui-design", args: "1" })
-- Need analysis before planning → Skill({ skill: "maestro-analyze", args: "1" })
-- View project dashboard → Skill({ skill: "manage-status" })
+- Roadmap generated, ready to plan → /maestro-plan 1
+- Need UI design first → /maestro-ui-design 1
+- Need analysis before planning → /maestro-analyze 1
+- View project dashboard → /manage-status
 </execution>
 
 <error_codes>

package/.claude/commands/maestro-ui-design.md

@@ -109,9 +109,9 @@ Design System:
   Compare:          {phase_dir}/design-ref/prototypes/compare.html
 
 Next steps:
-  Skill({ skill: "maestro-plan", args: "{phase}" })              -- Plan with design reference
-  Skill({ skill: "maestro-ui-design", args: "{phase} --refine" }) -- Refine selected design
-  Skill({ skill: "maestro-analyze", args: "{phase}" })           -- Analyze before planning
+  /maestro-plan {phase}              -- Plan with design reference
+  /maestro-ui-design {phase} --refine -- Refine selected design
+  /maestro-analyze {phase}           -- Analyze before planning
 ```
 </execution>
 

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

@@ -1,87 +1,106 @@
----
-name: maestro-verify
-description: Goal-Backward verification with 3-layer must-have checks, anti-pattern scan, Nyquist test coverage validation, and gap-fix plan generation
-argument-hint: "<phase> [--skip-tests] [--skip-antipattern]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Verify phase execution results through three complementary methods:
-1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved, not just tasks completed
-2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
-3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification (COVERED/PARTIAL/MISSING)
-
-Core principle: **Task completion ≠ Goal achievement**. A task "create chat component" can be marked complete when the component is a placeholder. This verifier checks that the goal "working chat interface" is actually achieved.
-
-Produces verification.json with must-have checks, gaps, anti-patterns, and fix plans. Optionally produces validation.json with test coverage analysis.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/verify.md
-</required_reading>
-
-<deferred_reading>
-- [verification.json](~/.maestro/templates/verification.json) — read when generating verification output
-- [validation.json](~/.maestro/templates/validation.json) — read when generating validation output
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number or slug)
-
-**Flags:**
-- `--skip-tests` -- Skip Nyquist test coverage validation (V2), only run Goal-Backward verification
-- `--skip-antipattern` -- Skip anti-pattern scan
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/`:
-- index.json (phase metadata, success_criteria, plan, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with convergence.criteria)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/verify.md' completely.
-
-**Next-step routing on completion:**
-- All checks pass, no gaps → Skill({ skill: "quality-review", args: "{phase}" })
-- Gaps found (must-have failures or anti-pattern blockers) → Skill({ skill: "maestro-plan", args: "{phase} --gaps" })
-- Low test coverage (Nyquist gaps) → Skill({ skill: "quality-test-gen", args: "{phase}" })
-
-**Gap-fix closure loop:**
-Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | No execution results found (missing summaries) | Check arguments format, re-run with correct input |
-| W001 | warning | Test coverage below configured threshold | Review coverage gaps, run quality-test-gen |
-| W002 | warning | Anti-pattern blockers found in modified files | Fix anti-pattern blockers before proceeding |
-| W003 | warning | Wiki health below threshold (score < 80) | Review broken links and orphan specs |
-| W004 | warning | Wiki health check unavailable | Skipped — wiki may not be initialized |
-</error_codes>
-
-<success_criteria>
-- [ ] Must-haves established (from success_criteria, convergence.criteria, or derived)
-- [ ] All truths verified with status and evidence (Layer 1)
-- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
-- [ ] Wiki health score reported (Layer 2.5) — warnings emitted if score < 80 or orphan specs found
-- [ ] All key links verified with evidence (Layer 3)
-- [ ] Anti-patterns scanned and categorized (unless skipped)
-- [ ] Nyquist test coverage assessed with gap classification (unless skipped)
-- [ ] Fix plans generated for identified gaps
-- [ ] Human verification items identified
-- [ ] verification.json written with complete results
-- [ ] validation.json written if test audit ran
-- [ ] index.json updated with verification status and timestamps
-</success_criteria>
+---
+name: maestro-verify
+description: Goal-Backward verification with 3-layer must-have checks, anti-pattern scan, Nyquist test coverage validation, and gap-fix plan generation
+argument-hint: "[phase] [--skip-tests] [--skip-antipattern] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Verify execution results through three complementary methods:
+1. **Goal-Backward verification** — 3-layer check (Truths → Artifacts → Wiring) that validates goals are actually achieved
+2. **Anti-pattern scan** — detect stubs, placeholders, TODO/FIXME, empty returns in modified files
+3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
+
+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`
+
+Registers VRF artifact in state.json on completion.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/verify.md
+</required_reading>
+
+<deferred_reading>
+- [verification.json](~/.maestro/templates/verification.json) — read when generating output
+- [validation.json](~/.maestro/templates/validation.json) — read when generating test output
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number or no args for milestone-wide, with optional flags.
+
+**Flags:**
+- `--skip-tests` -- Skip Nyquist test coverage validation, only run Goal-Backward
+- `--skip-antipattern` -- Skip anti-pattern scan
+- `--dir <path>` -- Verify specific plan directory
+
+**Scope routing:**
+
+| Invocation | Behavior |
+|-----------|----------|
+| `verify` (no args) | Milestone-level: verify all executed plans, aggregate results |
+| `verify 1` | Phase-level: verify all executed plans for phase 1 |
+| `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`
+
+**Artifact registration**: On completion, register VRF artifact:
+```jsonc
+{
+  "id": "VRF-{NNN}",
+  "type": "verify",
+  "milestone": "{current_milestone or null}",
+  "phase": null,
+  "scope": "milestone",
+  "path": "scratch/verify-{milestone-slug}-{date}",
+  "status": "completed",
+  "depends_on": ["EXC-001", "EXC-002", ...],
+  "harvested": false,
+  "created_at": "...",
+  "completed_at": "..."
+}
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/verify.md' completely.
+
+**Next-step routing on completion:**
+- All checks pass, no gaps → /quality-review
+- Gaps found (must-have failures or anti-pattern blockers) → /maestro-plan --gaps
+- Low test coverage (Nyquist gaps) → /quality-test-gen
+
+**Gap-fix closure loop:**
+Gaps found → maestro-plan --gaps → maestro-execute → maestro-verify (re-run)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No executed plans found for verification | Run maestro-execute first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | No execution results found (missing summaries) | Run maestro-execute first |
+| W001 | warning | Test coverage below configured threshold | Review coverage gaps |
+| W002 | warning | Anti-pattern blockers found in modified files | Fix blockers before proceeding |
+</error_codes>
+
+<success_criteria>
+- [ ] Must-haves established (from convergence.criteria in tasks)
+- [ ] All truths verified with status and evidence (Layer 1)
+- [ ] All artifacts checked at L1 (exists), L2 (substantive), L3 (wired) (Layer 2)
+- [ ] All key links verified with evidence (Layer 3)
+- [ ] Anti-patterns scanned and categorized (unless skipped)
+- [ ] Nyquist test coverage assessed (unless skipped)
+- [ ] Fix plans generated for identified gaps
+- [ ] verification.json written to plan dir (single plan) or milestone verify dir
+- [ ] VRF artifact registered in state.json
+</success_criteria>

package/.claude/commands/maestro.md

@@ -39,9 +39,9 @@ $ARGUMENTS — user intent text, or special keywords.
 - `--chain <name>` — Force a specific chain (bypass intent detection). Valid: full-lifecycle, spec-driven, brainstorm-driven, execute-verify, quality-loop, milestone-close, quick, review
 
 **State files read:**
-- `.workflow/state.json` — project state machine
+- `.workflow/state.json` — project state machine + artifact registry
 - `.workflow/roadmap.md` — milestone/phase structure
-- `.workflow/phases/*/index.json` — per-phase metadata and progress
+- `.workflow/scratch/*/plan.json` — plan metadata (via artifact registry paths)
 </context>
 
 <execution>
@@ -65,7 +65,7 @@ When `-y` is active, maestro propagates auto flags to downstream commands. Only
 | quality-test-gen | *(none)* | No auto flag — generates tests normally |
 | quality-debug | *(none)* | No auto flag — runs diagnosis normally |
 | quality-retrospective | `--auto-yes` | Accept all routing recommendations (spec/note/issue) without prompting |
-| maestro-phase-transition | *(none)* | No auto flag — validates and transitions |
+| maestro-milestone-audit | *(none)* | No auto flag — validates milestone readiness |
 | manage-learn | *(none)* | No auto flag — pure file operation, no prompts |
 
 Commands not listed (manage-*, spec-*, milestone-*) have no auto flags and execute as-is.
@@ -75,6 +75,12 @@ In auto mode, maestro also:
 - Skips chain confirmation (Step 5d)
 - Auto-skips on step errors (retry once, then skip and continue)
 
+**Context cleanup hint:**
+
+After completing step 3+, proactively suggest `-c` resume:
+- Interactive mode: display `⚡ 已执行 {N} 步，上下文较重。可随时 /maestro -c 在新上下文中恢复。`
+- `-y` mode and step 4+: log one-line warning to status.json, continue.
+
 **Context window reminder:**
 
 Before each Step 7 Skill() call, if context usage is near the window limit:
@@ -87,7 +93,7 @@ Before each Step 7 Skill() call, if context usage is near the window limit:
 === MAESTRO SESSION COMPLETE ===
 Session: {session_id}
 Chain:   {chain_name} ({steps_completed}/{steps_total} steps)
-Phase:   {current_phase} (if applicable)
+Milestone: {current_milestone} (if applicable)
 Mode:    {auto | interactive}
 
 Steps: