maestro-flow-one 0.2.30 → 0.2.32

package/maestro-flow/commands/lifecycle/quick.md

@@ -33,7 +33,7 @@ Parse for:
 1. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions and discoverable tools. Apply to implementation.
 2. **UI specs (conditional)**: If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro spec load --category ui`.
 3. **Role Knowledge**:
-   - Browse: `maestro wiki list --category coding`
+   - Browse: `maestro search --category coding`
    - Load task-relevant entries: `maestro wiki load <id1> [id2...]`
 3. All are optional — proceed without if unavailable.
 </context>
@@ -41,6 +41,18 @@ Parse for:
 <execution>
 Follow '~/.maestro/workflows/quick.md' completely.
 
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "plan.json",                              // Task definitions
+  ".summaries/TASK-*-summary.md" (per task)  // Execution results
+]
+```
+If any artifact is missing: DO NOT report completion. Complete the missing step first.
+
+Task summaries MUST include concrete evidence of completion (files changed, tests run, commands executed) — not just "task completed successfully."
+
 **Next-step routing on completion:**
 - Task done, --full verification passed → /manage-status
 - Task done, verification found gaps → /quality-debug {issue}

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -61,13 +61,13 @@ maestro-analyze    ─┘ context-package.json
         ↓
 maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
         ↓
-maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
+maestro-analyze {phase} → maestro-plan → maestro-execute
 ```
 
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
-2. **Wiki search**: `maestro wiki search "{requirement keywords}" --json` → prior knowledge
+2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge
 3. All optional — proceed without if unavailable
 </context>
 
@@ -92,6 +92,32 @@ Sub-modes:
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
+### Phase Gates (MANDATORY, BLOCKING — Create mode)
+
+**GATE 1: Input → Decomposition**
+- REQUIRED: Requirement parsed with goal, constraints, stakeholders.
+- REQUIRED: Upstream context loaded via --from (if specified).
+
+**GATE 2: Decomposition → Refinement**
+- REQUIRED: Milestones defined with deliverable targets.
+- REQUIRED: Phases defined within milestones with dependencies.
+- REQUIRED: Every Active requirement from project.md mapped to exactly one phase.
+- REQUIRED: No circular dependencies in phase ordering.
+
+**GATE 3: Refinement → Completion**
+- REQUIRED: User approved roadmap (or auto-approved with -y).
+- REQUIRED: `.workflow/roadmap.md` written with Milestone > Phase hierarchy.
+- REQUIRED: Artifact registered in state.json with milestone entries.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/roadmap.md"    // Milestone > Phase hierarchy with progress table
+]
+```
+If missing: DO NOT report completion.
+
 </execution>
 
 <completion>

package/maestro-flow/commands/lifecycle/swarm-workflow.md

@@ -26,7 +26,7 @@ Scripts: `~/.maestro/workflows/swarm/wf-*.js`
 | `wf-analyze` | maestro-analyze | explore → 6-dim scoring → **skeptic cross-verify** → **3-way advocacy (go/no-go/conditional) + referee** |
 | `wf-brainstorm` | maestro-brainstorm | multi-role analysis → **3-specialist cross-review** → **3-proposal competition** → **arbitrator** |
 | `wf-review` | quality-review | 6-dim scan → **3-vote adversarial verify (prosecutor/defense/judge)** → **3-perspective report + arbitrated verdict** |
-| `wf-verify` | maestro-verify | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
+| `wf-verify` | maestro-execute (verification gate) | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
 | `wf-grill` | maestro-grill | explore → parallel branch stress → **meta-skeptic challenge** → **3-vote verdict (optimist/pessimist/realist)** |
 | `wf-plan` | maestro-plan | parallel context → **3-strategy competing proposals** → **judge panel scoring** → **3-critic adversarial check** |
 | `wf-execute` | maestro-execute | wave-based parallel execution → **adversarial convergence spot-check** → **3-vote status determination** |
@@ -228,7 +228,7 @@ Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-
   "args": "--script wf-analyze {phase}",
   "stage": "analyze",
   "command_scope": "project",
-  "command_path": "<resolved by maestro ralph skills>"
+  "command_path": "<resolved by maestro ralph skills --platform claude>"
 }
 ```
 

package/maestro-flow/commands/lifecycle/tools-register.md

@@ -65,7 +65,7 @@ Parse $ARGUMENTS to determine mode:
 - Analyze improvement points (step splitting, prerequisites, error handling)
 
 **Promote mode** (existing knowhow → tool):
-- Locate document: `maestro wiki list --keyword <name>` or by path in `.workflow/knowhow/`
+- Locate document: `maestro search "<name>" --type knowhow` or by path in `.workflow/knowhow/`
 - Read document, verify it contains actionable steps (numbered list or ## Steps section)
 - If no actionable steps, suggest extract mode instead
 - Determine category (Step 3) and summary ("Use when ...")
@@ -128,7 +128,7 @@ summary: "Use when <timing>. <scope description>"
 **Optionally register spec ref entry** for index discoverability:
 ```bash
 maestro spec add <category> "<title>" "Use when <timing>. <scope summary>" --keywords "<csv>" \
-  --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
+  --description "<one-line summary>" --ref "knowhow/RCP-<slug>.md" --knowhow-type recipe
 ```
 
 ### Step 6: Verify

package/maestro-flow/commands/lifecycle/ui-codify.md

@@ -56,6 +56,26 @@ If specs not initialized, continue without — the workflow still produces valid
 Route to `~/.maestro/workflows/ui-codify.md` and follow completely.
 
 The workflow orchestrates 4 phases with deferred loading of phase-specific workflow files. Each phase reads its workflow file only when execution reaches that phase.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE Phase 1 → Phase 2**: Source path validated, file discovery completed. design-tokens.json generated.
+**GATE Phase 2 → Phase 3**: layout-templates.json generated with component patterns.
+**GATE Phase 3 → Phase 4**: preview.html + preview.css generated as interactive showcase.
+**GATE Phase 4 → Completion**: knowhow-manifest.json created. codify-to-knowhow called and completed.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "design-tokens.json",      // Phase 1
+  "layout-templates.json",   // Phase 2
+  "preview.html",            // Phase 3
+  "preview.css",             // Phase 3
+  "knowhow-manifest.json"    // Phase 4
+]
+```
+If any artifact is missing: DO NOT report completion.
 </execution>
 
 <error_codes>

package/maestro-flow/commands/lifecycle/update.md

@@ -1,7 +1,7 @@
 ---
 name: maestro-update
 description: Detect version, preview changes, apply workflow upgrades
-argument-hint: "[--dry-run] [--force]"
+argument-hint: "[--dry-run] [--force] [--setup-only]"
 allowed-tools:
   - Read
   - Write
@@ -12,9 +12,13 @@ allowed-tools:
   - 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).
+Version router — detect current version, run schema migration to latest, then follow the version-specific smart upgrade workflow.
 
-Each migration step is previewed before execution. The user confirms each step in a loop.
+Migration scripts live in two layers:
+- **Schema** (`src/migrations/`): code-level state.json transforms, auto-chained by registry
+- **Workflow** (`~/.maestro/workflows/updates/`): version-specific upgrade guides with environment setup
+
+Schema migrations handle the mechanical version bump. Workflow docs handle the smart part — what the user needs to know, configure, or verify for that version. The router runs schema first, then loads the matching workflow doc.
 </purpose>
 
 <context>
@@ -22,131 +26,80 @@ $ARGUMENTS — optional flags.
 
 **Flags:**
 - `--dry-run` -- Preview migration plan without executing
-- `--force` -- Skip confirmation prompts (apply all pending migrations)
+- `--force` -- Skip confirmation prompts
+- `--setup-only` -- Skip schema migration, run only the setup for current version
 
-**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`
+**Version source:** `.workflow/state.json` → `version` field
 
-**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
+**Workflow docs:** `~/.maestro/workflows/updates/`
+- `update-v{TO}-setup.md` — post-migration setup for version {TO}
 
-**State version source:** `.workflow/state.json` → `version` field
+**Schema registry:** `src/migrations/` — handles all intermediate version bumps automatically
 </context>
 
 <execution>
 
-### Step 1: Detect Current State
+### Step 1: Detect Version
 
 ```
-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}
+1. Read .workflow/state.json → extract version (default "1.0" if missing)
+2. Display:
+   === Maestro Update ===
+   Current version: v{version}
 ```
 
-### Step 2: Dry-Run Preview
-
-Run the migration CLI in dry-run + JSON mode to get the full plan:
+IF `--setup-only`:
+  → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+  → IF exists: follow that document completely, then EXIT
+  → IF not exists: display "No setup script for v{version}" → EXIT
 
-```bash
-npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
-```
+### Step 2: Check for Updates
 
-Parse the JSON output. If status is `up-to-date`:
 ```
-Already up to date (v{version})
-```
-→ EXIT
-
-Otherwise display the migration plan:
+1. Run: npx tsx src/migrations/run.ts "$(pwd)" --dry-run --json
+2. Parse JSON output
+3. IF status = "up-to-date":
+     Display "Already up to date (v{version})"
+     → Glob: ~/.maestro/workflows/updates/update-v{version}-setup.md
+     → IF exists: AskUserQuestion "Run setup for v{version}?" → load and follow
+     → EXIT
+
+4. Display target:
+   Update available: v{current} → v{target}
+   Schema migrations: {N} step(s) (handled automatically)
 ```
-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
+IF `--dry-run` → display info and EXIT.
 
-For each migration step (unless `--force`):
+### Step 3: Execute
 
 ```
-LOOP for step_index = 1 to N:
+1. Confirm (unless --force):
+   AskUserQuestion: "Upgrade v{current} → v{target}?"
+   Options: [执行 / 取消]
 
-  Display:
-    --- Step {step_index}/{N}: {name} ---
-    Version: v{from} → v{to}
+2. Create backup:
+   Bash: cp .workflow/state.json .workflow/state.json.backup-v{current}-{timestamp}
 
-    Changes:
-      {description, indented}
+3. Run schema migration (handles all intermediate steps automatically):
+   Bash: npx tsx src/migrations/run.ts "$(pwd)" --json
+   Parse result, display changes.
 
-  IF NOT --force:
-    AskUserQuestion: "Apply this migration?"
-    Options: [yes / skip / abort]
+4. IF failed → display backup restore command → EXIT
 
-    - "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
+5. Load version-specific setup:
+   Read: ~/.maestro/workflows/updates/update-v{target}-setup.md
+   IF exists → follow completely (hooks, deps, knowledge system config)
 
-  IF --force:
-    → proceed to Step 4 (execute)
+6. Display: "v{current} → v{target}: done"
 ```
 
-### Step 4: Execute Single Migration
+### Step 4: Summary
 
 ```
-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}
+=== Update Complete ===
+Version: v{current} → v{target}
+Backup:  .workflow/state.json.backup-v{current}-{timestamp}
 
 Next steps:
   /manage-status  -- Verify project state
@@ -155,22 +108,12 @@ Next steps:
 
 </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
+- [ ] Schema migrations run automatically (no manual intermediate steps)
+- [ ] Backup created before migration
+- [ ] Version-specific setup doc loaded and followed (if exists)
+- [ ] --setup-only runs only setup for current version
+- [ ] --dry-run previews without executing
+- [ ] Summary shows version change and backup path
 </success_criteria>

package/maestro-flow/commands/manage/codebase-rebuild.md

@@ -53,9 +53,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 
 **Next-step routing on completion:**
 - View updated project state → `/manage-status`
-- Incremental updates later → `/manage-codebase-refresh`
+- Incremental updates later → `/quality-sync`
 - Verify KG stats → `maestro kg stats`
-- Verify wiki integration → `maestro wiki list --keyword kg`
+- Verify wiki integration → `maestro search "kg" --type knowhow`
 - Future change impact → `maestro kg diff-wiki`
 </execution>
 
@@ -80,6 +80,6 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] KG pipeline executed (`maestro kg index`)
 - [ ] knowledge-graph.json generated in .workflow/codebase/
 - [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
-- [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
+- [ ] Next step routing: `/manage-status` or `/quality-sync` for incremental updates later
 - [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
 </success_criteria>

package/maestro-flow/commands/manage/harvest.md

@@ -53,7 +53,7 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 
 **Next-step routing on completion:**
 - Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `/wiki-connect --fix`
+- Connect wiki graph → `/manage-wiki connect --fix`
 - Triage issues → `/manage-issue list --source harvest`
 - View specs → `/spec-load --role implement`
 - Full retrospective → `/quality-retrospective`

package/maestro-flow/commands/manage/knowhow-capture.md

@@ -13,7 +13,7 @@ allowed-tools:
 ---
 <purpose>
 Capture reusable knowledge into `.workflow/knowhow/` with type-specific structured fields.
-Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro knowhow search`.
+Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro search --type knowhow`.
 </purpose>
 
 <required_reading>
@@ -23,7 +23,7 @@ Auto-indexed by WikiIndexer (type=knowhow), searchable via `maestro knowhow sear
 <context>
 $ARGUMENTS — type token + description + optional flags.
 
-**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
+**Flags**: `--lang <lang>`, `--source <url>`, `--tag tag1,tag2`, `--title <title>`, `--description <desc>`, `--asset-type <type>`, `--code-paths <paths>`, `--category <cat>`
 
 **Type routing** (first token match):
 
@@ -38,15 +38,18 @@ $ARGUMENTS — type token + description + optional flags.
 | `asset`/`ast`/`资产`/`契约` | asset | AST- | assetType, codePaths, category |
 | `blueprint`/`blp`/`蓝图` | blueprint | BLP- | codePaths, category |
 | `document`/`doc`/`文档` | document | DOC- | (general fallback) |
+| `insight`/`ins`/`洞察`/`经验` | insight | INS- | content, tags, phase (replaces former manage-learn) |
 | Short text + `--tag` | tip | TIP- | — |
-| No args | — | — | AskUserQuestion (9 options) |
+| No args | — | — | AskUserQuestion (10 options) |
 
-**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{HHMM}.md` with YAML frontmatter (title, type, category, created, tags, source, lang, status)
+**Output**: `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter (title, description, type, category, created, tags, source, lang, status)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/knowhow.md' completely.
 
+**Description rule**: Every entry MUST have a `description` field in frontmatter — a one-line summary (under 120 chars) for search results. WikiIndexer uses priority chain: `description > content[:240]`. Use `--description` flag value if provided; otherwise auto-generate from content.
+
 **Tags language rule**: Tags must match content language. Chinese content → Chinese tags (如 `认证,令牌,刷新`). English content → English tags. Mixed → bilingual.
 
 **Type-specific content rules**:

package/maestro-flow/commands/manage/knowhow.md

@@ -13,9 +13,11 @@ allowed-tools:
 ---
 <purpose>
 Unified memory management across two stores:
-1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts and tips with JSON index, created by `manage-knowhow-capture`
+1. **Workflow knowhow** (`.workflow/knowhow/`) — Session compacts, tips, insights, and all reusable knowledge, created by `manage-knowhow-capture`
 2. **System memory** (`~/.claude/projects/{project}/memory/`) — Claude Code auto-memory (MEMORY.md + topic files), persists across conversations
 
+Also scans `.workflow/specs/learnings.md` for legacy insight entries (backward compat with former `manage-learn`).
+
 Provides list/search/view/edit/delete/prune operations. Default store is `all` (show both).
 </purpose>
 

package/maestro-flow/commands/manage/wiki.md

@@ -1,7 +1,7 @@
 ---
 name: manage-wiki
 description: Manage wiki graph — health, cleanup, search, stats
-argument-hint: "<subcommand: health|search|cleanup|stats> [query] [--fix] [--dry-run]"
+argument-hint: "<subcommand: health|search|cleanup|stats|connect|digest> [query] [--fix] [--dry-run]"
 allowed-tools:
   - Read
   - Write
@@ -12,9 +12,7 @@ allowed-tools:
   - 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.
+Unified wiki graph management command. Provides interactive access to wiki health monitoring, entry search, orphan cleanup, graph statistics, link discovery, and knowledge synthesis — the single entry point for all wiki graph operations.
 </purpose>
 
 <required_reading>
@@ -31,16 +29,26 @@ $ARGUMENTS — subcommand and optional flags.
 | `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 |
+| `connect` | Find and link hidden connections — orphan rescue, missing links, transitive gaps |
+| `digest [topic]` | Generate knowledge digest with theme clustering and gap analysis |
 | No args | Same as `health` |
 
 **Flags:**
 - `--type <type>` — Filter by wiki type: spec, knowhow, note, issue
-- `--fix` — Auto-fix issues found during cleanup (remove broken links, suggest connections)
+- `--fix` — Auto-fix issues found during cleanup/connect (remove broken links, apply connections)
 - `--json` — Output in JSON format
+- `--min-similarity N` — (connect) Minimum similarity threshold for link candidates
+- `--max N` — (connect) Maximum number of suggestions
+- `--format brief|full` — (digest) Output format
+- `--recent N` — (digest) Scope to N most recent entries
+- `--create-issues` — (digest) Create issues for identified knowledge gaps
 </context>
 
 <execution>
-Follow '~/.maestro/workflows/wiki-manage.md' completely.
+**Subcommand routing:**
+- `health|search|cleanup|stats` → Follow `~/.maestro/workflows/wiki-manage.md` completely.
+- `connect` → Follow `~/.maestro/workflows/wiki-connect.md` completely (Stages 1-6).
+- `digest` → Follow `~/.maestro/workflows/wiki-digest.md` completely (Stages 1-8).
 </execution>
 
 <error_codes>
@@ -54,9 +62,10 @@ Follow '~/.maestro/workflows/wiki-manage.md' completely.
 </error_codes>
 
 <success_criteria>
-- [ ] Subcommand parsed (health/search/cleanup/stats)
+- [ ] Subcommand parsed (health/search/cleanup/stats/connect/digest)
 - [ ] Wiki data loaded via `maestro wiki` CLI
 - [ ] Results displayed in formatted output
-- [ ] If cleanup --fix: issues resolved and delta reported
+- [ ] If cleanup/connect --fix: issues resolved and delta reported
+- [ ] If digest: themes clustered, gaps identified, coverage heatmap generated
 - [ ] Next-step suggestions provided
 </success_criteria>

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

@@ -22,7 +22,7 @@ Audit milestone completion using the artifact registry. Checks:
 Data source: `state.json.artifacts[]` filtered by current milestone.
 Produces audit report at `.workflow/milestones/{milestone}/audit-report.md`.
 
-Pipeline position: downstream of maestro-verify (all phases verified), upstream of maestro-milestone-complete.
+Pipeline position: downstream of maestro-execute (which includes verification), upstream of maestro-milestone-complete.
 </purpose>
 
 <required_reading>
@@ -49,7 +49,7 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 
 ### Role Knowledge
 
-1. Browse: `maestro wiki list --category review`
+1. Browse: `maestro search --category review`
 2. Select entries relevant to milestone integration audit
 3. Load: `maestro wiki load <id1> [id2...]`
 </context>
@@ -58,6 +58,38 @@ Milestone: $ARGUMENTS (optional -- defaults to current_milestone from state.json
 Follow '~/.maestro/workflows/milestone-audit.md' completely.
 
 Audit checklist steps (phase coverage, ad-hoc completeness, execution completeness, cross-artifact integration) are defined in workflow `milestone-audit.md`.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Load → Phase Coverage Check**
+- REQUIRED: state.json loaded with artifacts[] filtered by target milestone.
+- REQUIRED: Milestone phases identified from roadmap (standard) or milestone_obj.phases (adhoc).
+- BLOCKED if no execute artifacts found: error E003.
+
+**GATE 2: Phase Coverage → Integration Check**
+- REQUIRED: Every phase checked for artifact chain completeness (ANL→PLN→EXC for standard, PLN→EXC for adhoc).
+- REQUIRED: Execution completeness verified — all tasks in executed plans checked for status.
+- Do NOT skip incomplete chains — each gap MUST be logged in audit report.
+
+**GATE 3: Integration Check → Report**
+- REQUIRED: Cross-artifact integration check completed (shared interfaces, data contracts, configuration consistency).
+- REQUIRED: Clear PASS/FAIL verdict determined with evidence for each check.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/milestones/{milestone}/audit-report.md"  // Clear PASS/FAIL verdict
+]
+```
+If missing: DO NOT report completion. Write the audit report first.
+
+### Evidence Requirement
+
+Every audit check result MUST cite what was examined and what was found:
+- PASS: "Phase 1 chain complete: ANL-001 → PLN-001 → EXC-001, all tasks completed"
+- FAIL: "Phase 2 missing EXC artifact — PLN-002 exists but no execution found"
+- Do NOT mark checks as PASS without verifying the actual artifact exists and contains expected content.
 </execution>
 
 <completion>

package/maestro-flow/commands/milestone/complete.md

@@ -46,6 +46,24 @@ Follow '~/.maestro/workflows/milestone-complete.md' completely.
 
 Archive flow steps (validation, directory archival, artifact history, knowhow extraction, state advancement, cleanup) are defined in workflow `milestone-complete.md`.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Validation → Archival**
+- REQUIRED: Audit report verified as PASS (E002 if not).
+- REQUIRED: No incomplete artifacts remain (E003 if any).
+
+**GATE 2: Archival → Knowhow Extraction**
+- REQUIRED: Scratch artifacts moved to `milestones/{M}/artifacts/`.
+- REQUIRED: Artifact entries archived to milestone_history in state.json.
+
+**GATE 3: Knowhow Extraction → State Advancement**
+- REQUIRED: Knowhow extraction attempted (may produce 0 entries — W001).
+- REQUIRED: `project.md` Context updated with milestone summary.
+
+**GATE 4: State Advancement → Completion**
+- REQUIRED: state.json updated — next milestone as current (standard) or current_milestone=null (adhoc).
+- REQUIRED: Roadmap snapshot saved (standard only).
+
 ### Knowledge Promotion Inquiry
 
 After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
@@ -56,7 +74,7 @@ After knowhow extraction (step 4), scan `learnings.md` for promotion candidates:
 2. **Convention drift detection**: Compare executed task summaries against `coding-conventions.md` and `architecture-constraints.md`:
    → Ask: "Were any established conventions bypassed during this milestone? Should conventions be updated?"
 
-3. **Wiki island check**: Auto-trigger `wiki-connect --fix` to link newly extracted knowledge.
+3. **Wiki island check**: Auto-trigger `manage-wiki connect --fix` to link newly extracted knowledge.
 
 If user confirms promotion, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
 

package/maestro-flow/commands/milestone/release.md

@@ -58,6 +58,24 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 <execution>
 Follow '~/.maestro/workflows/milestone-release.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Validation → Version Bump**
+- REQUIRED: Current milestone completed (audit PASS + milestone-complete run). E001 if not.
+- REQUIRED: Working tree clean (no uncommitted changes). E003 if dirty.
+
+**GATE 2: Version Bump → Changelog**
+- REQUIRED: Target version computed and greater than previous (E005 if not).
+- REQUIRED: Version manifest file(s) identified and accessible.
+
+**GATE 3: Changelog → Tag/Push**
+- REQUIRED: CHANGELOG.md entry written with milestone summary + grouped changes.
+- REQUIRED: Release commit created with conventional message.
+
+**GATE 4: Tag → Completion**
+- REQUIRED: Annotated git tag created (unless --no-tag).
+- REQUIRED: state.json updated with last_release_version + last_release_at.
+
 **High-level flow:**
 1. Validate preconditions (milestone completed, clean tree, audit PASS)
 2. Resolve target version from `<version>` or `--bump` against current manifest