maestro-flow-one 0.2.29 → 0.2.31

package/maestro-flow/commands/learn/follow.md

@@ -23,7 +23,7 @@ $ARGUMENTS — target and optional flags.
 |-------|-----------|
 | File path (contains `/` or `\`) | Read source file |
 | Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
-| Topic string | `maestro wiki search "<topic>"` → top result; fallback: Grep src/ |
+| Topic string | `maestro search "<topic>"` → top result; fallback: Grep src/ |
 
 **Flags**:
 - `--depth shallow` (default): key patterns and structure only

package/maestro-flow/commands/learn/investigate.md

@@ -30,7 +30,7 @@ $ARGUMENTS — question text and optional flags.
 - `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
 - `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks
 
-**Storage read**: source files in scope + `maestro wiki search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+**Storage read**: source files in scope + `maestro search` + `.workflow/specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
 </context>
 
 <state_machine>
@@ -83,7 +83,7 @@ S_REPORT:
 ### A_FRAME_QUESTION
 
 1. Parse question, generate slug, create KNW-investigate-{slug}/
-2. Search prior knowledge: `maestro wiki search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
+2. Search prior knowledge: `maestro search "<question>"` + search .workflow/specs/learnings.md + read debug-notes.md
 3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
 
 ### A_COLLECT_EVIDENCE

package/maestro-flow/commands/learn/second-opinion.md

@@ -33,7 +33,7 @@ $ARGUMENTS — target and optional mode flag.
 
 **Flags**: `--mode review|challenge|consult` (default: review)
 
-**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro wiki search "<target topic>"` for related entries.
+**Pre-load** (optional): `Skill("spec-load")` for conventions + `maestro search "<target topic>"` for related entries.
 
 **Output**: `.workflow/knowhow/KNW-opinion-{slug}-{YYYY-MM-DD}.md`
 </context>

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

@@ -71,11 +71,11 @@ Output directory format, artifact registration schema, and output artifact listi
 
 1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
 2. **Specs**: `maestro spec load --category arch` — load architecture constraints
-3. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
 4. All optional — proceed without if unavailable (log warning)
 
 ### Role Knowledge
-`maestro wiki list --category debug` → select relevant → `maestro wiki load`
+`maestro search --category debug` → select relevant → `maestro wiki load`
 </context>
 
 <interview_protocol>
@@ -93,6 +93,57 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 <execution>
 Follow '~/.maestro/workflows/analyze.md' completely.
 
+### Core Principle: Evidence-Backed Decisions
+
+Every decision produced by this command MUST be traceable to independently gathered evidence. Manual file reading (Read/Grep by the orchestrator) is preparation, NOT evidence. Evidence comes from:
+- cli-explore-agent output (code anchors, call chains, data flows)
+- maestro delegate CLI analysis output (multi-perspective findings)
+- User-provided input (domain knowledge, constraints, corrections)
+
+A decision without at least one CLI/agent-sourced evidence item is LOW CONFIDENCE and MUST be flagged as such.
+
+### Standard Mode Phase Gates (when `-q` and `--gaps` are BOTH absent)
+
+These gates are MANDATORY and BLOCKING. Do NOT advance past a gate until ALL conditions are met. Do NOT substitute manual Read/Grep for agent/CLI exploration.
+
+**GATE 1: Step 4 → Step 5** (Exploration → Discussion)
+- REQUIRED: cli-explore-agent spawned and completed (Step 4.1). Output written to `exploration-codebase.json` with ≥1 code anchor.
+- REQUIRED: At least one maestro delegate CLI call completed (Step 4.2). Output aggregated into `explorations.json` or `perspectives.json`.
+- REQUIRED: Baseline confidence scoring recorded in discussion.md (Step 4.6).
+- BLOCKED if any missing: complete Step 4 before proceeding.
+
+**GATE 2: Step 5 → Step 6** (Discussion → Scoring)
+- REQUIRED: discussion.md contains ≥1 interactive round with user feedback (Step 5.3).
+- REQUIRED: Confidence re-scored ≥1 time with delta shown (Step 5.8).
+- REQUIRED: Pressure pass completed ≥1 time (Step 5.9).
+- BLOCKED if any missing: continue discussion rounds.
+
+**GATE 3: Step 6 → Step 7** (Scoring → Synthesis)
+- REQUIRED: analysis.md written with all 6 dimensions scored.
+- REQUIRED: Each dimension score cites evidence from exploration-codebase.json or explorations.json — NOT from orchestrator's manual file reading.
+- BLOCKED if any missing: complete scoring first.
+
+**GATE 4: Step 7 → Step 8** (Synthesis → Decision Extraction)
+- REQUIRED: conclusions.json written with recommendations and decision trail.
+- REQUIRED: Intent Coverage Matrix shows no unresolved ❌ items (or user-confirmed deferrals).
+- BLOCKED if any missing: complete synthesis first.
+
+### Artifact Verification
+
+Before writing the completion report (Step 9), verify ALL expected artifacts exist in OUTPUT_DIR:
+```
+FULL_MODE_REQUIRED = [
+  "discussion.md",           // Step 3+5
+  "exploration-codebase.json", // Step 4.1
+  "explorations.json" OR "perspectives.json", // Step 4.3
+  "analysis.md",             // Step 6
+  "conclusions.json",        // Step 7
+  "context.md",              // Step 8
+  "context-package.json"     // Step 8.6
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
+
 ### --gaps Mode (Issue Root Cause Analysis)
 
 When `--gaps` flag is present, follow `~/.maestro/workflows/issue-gaps-analyze.md` instead of the standard analyze pipeline:

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

@@ -64,7 +64,7 @@ maestro-analyze → maestro-roadmap → maestro-plan
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints for Phase 4 decisions
-2. **Wiki search**: `maestro wiki search "{topic keywords}" --json` → prior knowledge context
+2. **Wiki search**: `maestro search "{topic keywords}" --json` → prior knowledge context
 3. All optional — proceed without if unavailable
 </context>
 
@@ -90,6 +90,41 @@ P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief
 
 P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+Each phase produces artifacts that are prerequisites for the next. Do NOT advance past a gate without verifying the prior phase's output exists.
+
+**GATE P0 → P1**: `blueprint-config.json` created with session metadata.
+**GATE P1 → P1.5**: Discovery context gathered (codebase patterns, upstream context loaded).
+**GATE P1.5 → P2**: Requirements expanded from discovery findings.
+**GATE P2 → P3**: `product-brief.md` written with vision, goals, scope, multi-perspective synthesis.
+**GATE P3 → P4**: `requirements/` directory with `_index.md` + individual `REQ-*.md` + `NFR-*.md` files. All requirements have RFC 2119 keywords and acceptance criteria.
+**GATE P4 → P5**: `architecture/` directory with `_index.md` + individual `ADR-*.md` files.
+**GATE P5 → P6**: `epics/` directory with `_index.md` + individual `EPIC-*.md` files. Cross-Epic dependency map present.
+**GATE P6**: Readiness score computed. Pass (≥80%) or Review (≥60%) required for handoff.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "blueprint-config.json",        // P0
+  "product-brief.md",             // P2
+  "glossary.json",                // P2 (≥5 terms)
+  "requirements/_index.md",       // P3
+  "architecture/_index.md",       // P4
+  "epics/_index.md",              // P5
+  "readiness-report.md",          // P6
+  "blueprint-summary.md",         // P6
+  "context-package.json"          // P6
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce it.
+
+### Evidence Requirement
+
+Architecture Decision Records (ADR-*.md) MUST cite evidence for each decision:
+- Valid: code analysis, requirement traceability (REQ-xxx), upstream context, CLI analysis output
+- INVALID: generic rationale without reference to project-specific constraints
 </execution>
 
 <completion>

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

@@ -57,7 +57,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 ### Role Knowledge
 1. Browse accumulated knowledge for this role:
-   `maestro wiki list --category arch`
+   `maestro search --category arch`
 2. Analyze the index, identify entries relevant to the current task
 3. Load selected documents:
    `maestro wiki load <id1> [id2] [id3...]`
@@ -77,6 +77,45 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 <execution>
 Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+These gates apply to Auto mode (full pipeline). Do NOT advance past a gate until ALL conditions are met.
+
+**GATE 1: Framework → Role Analysis** (Step 1 → Step 3)
+- REQUIRED: `guidance-specification.md` written with §10 feature decomposition and RFC 2119 keywords.
+- REQUIRED: Role selection completed (interactive or auto-default).
+- BLOCKED if missing: complete framework generation before spawning role agents.
+
+**GATE 2: Role Analysis → Cross-Role Review** (Step 3 → Step 4.5)
+- REQUIRED: Every selected role has `{role}/analysis.md` with §2 Decision Digest (4 tables).
+- REQUIRED: Per-feature files `{role}/analysis-F-*.md` written for each feature in §10.
+- BLOCKED if missing: complete all role analyses before spawning cross-role-reviewer.
+
+**GATE 3: Cross-Role Review → Completion** (Step 4.5 → Report)
+- REQUIRED: Cross-role-reviewer output received with `patch_targets[]`.
+- REQUIRED: If findings > 0, resolutions applied via Edit AND logged in `guidance-specification.md` §12.
+- REQUIRED: If findings == 0, final report explicitly states "No cross-role issues detected".
+- BLOCKED if missing: complete review synthesis before reporting.
+
+### Artifact Verification (before completion report)
+
+```
+AUTO_MODE_REQUIRED = [
+  "guidance-specification.md",            // Step 1
+  "{role}/analysis.md" (per selected role), // Step 3
+  "{role}/analysis-F-*.md" (per feature),   // Step 3
+]
+```
+If any artifact is missing: DO NOT report completion. Go back and produce the missing artifact.
+
+### Evidence Requirement
+
+Role analysis findings in `{role}/analysis.md` §2 Decision Digest MUST cite concrete evidence:
+- Code references (file:line), API endpoints, data models from the codebase
+- User-provided constraints from interview
+- Cross-role references to other role analyses
+Decisions without evidence are flagged LOW CONFIDENCE.
 </execution>
 
 <completion>

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

@@ -25,7 +25,7 @@ $ARGUMENTS — requirement text and optional flags.
 - `--rule <template>`: Shared rule template for all delegates
 - `-y`: Skip plan confirmation
 
-**Pre-load** (optional): `maestro spec load --category arch` + `maestro wiki list --category arch` → include in delegate prompts.
+**Pre-load** (optional): `maestro spec load --category arch` + `maestro search --category arch` → include in delegate prompts.
 
 **Output**: `.workflow/scratch/{YYYYMMDD}-collab-{slug}/`
 - `collab-report.md` — merged findings with consensus/conflict/unique tags

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

@@ -114,7 +114,7 @@ Display loaded rules summary (entry count + key rule names).
 maestro knowhow list --store workflow
 
 # With --task: search relevant entries
-maestro knowhow search "<task_keyword>"
+maestro search --type knowhow "<task_keyword>"
 ```
 
 Display available knowhow entries (ID + title). Hint: `maestro wiki load <id>` for details.
@@ -127,7 +127,7 @@ ls .workflow/codebase/doc-index.json
 
 - Exists → display "Codebase docs ready, last updated: {timestamp}"
 - Missing → suggest `/manage-codebase-rebuild`
-- Stale (>7 days) → suggest `/manage-codebase-refresh`
+- Stale (>7 days) → suggest `/quality-sync`
 
 ### 4. Create companion document
 
@@ -341,7 +341,7 @@ Mid-task commands:
   /maestro-companion note "finding or decision"
   /maestro-companion note --file src/auth.ts "changed token validation"
   /spec-load --keyword <keyword>
-  maestro wiki search "<query>"
+  maestro search "<query>"
 ```
 
 ---
@@ -470,7 +470,7 @@ Clear `.workflow/.scratchpad/.companion-active`.
 
 ```
 Knowledge accumulation reminders:
-  Reusable pattern found?        /spec-add <category> "title" "content"
+  Reusable pattern found?        /spec-add <category> "title" "content" --description "summary"
   Solved a complex problem?      /manage-knowhow-capture recipe "description"
   Made an architecture decision? /manage-knowhow-capture decision "description"
   Discovered a useful trick?     /manage-knowhow-capture tip "content"

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

@@ -126,7 +126,7 @@ Read deferred `node-catalog.md` (fallback to built-in mapping):
 | review | `quality-review` |
 | brainstorm | `maestro-brainstorm` |
 | analysis | `maestro delegate --role analyze` |
-| verify | `maestro-verify` |
+| verify | `maestro-execute` |
 | refactor | `quality-refactor` |
 | debug | `quality-debug` |
 

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

@@ -17,7 +17,7 @@ Execute all tasks in a plan using wave-based parallel execution with dependency-
 
 Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
 
-Pipeline position: upstream from maestro-plan (consumes confirmed plan), downstream to maestro-verify.
+Pipeline position: upstream from maestro-plan (consumes confirmed plan). Verification is built-in (E2.7).
 </purpose>
 
 <required_reading>
@@ -56,13 +56,13 @@ Full resolution logic, output directory format, artifact registration schema, an
 ### Pre-load context (before task execution)
 
 1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
-2. **Wiki knowledge**: Run `maestro wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+2. **Wiki knowledge**: Run `maestro search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
 3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
 4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
 5. All are optional — proceed without if unavailable (log warning).
 
 ### Role Knowledge
-`maestro wiki list --category coding` → select relevant → `maestro wiki load`
+`maestro search --category coding` → select relevant → `maestro wiki load`
 </context>
 
 <execution>
@@ -76,6 +76,29 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/execute.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Plan Load → Task Execution**
+- REQUIRED: plan.json found and parsed with valid task definitions.
+- REQUIRED: `.task/TASK-*.json` files exist for all tasks in plan.
+- BLOCKED if no pending tasks: error E004.
+
+**GATE 2: Per-Task Execution → Summary**
+- REQUIRED: Each completed task has `.summaries/TASK-{NNN}-summary.md` written with concrete evidence (files changed, tests run, verification results).
+- REQUIRED: `.task/TASK-{NNN}.json` status updated to completed|blocked.
+- Do NOT silently skip failed tasks — mark as blocked with reason.
+
+**GATE 3: All Tasks → Completion**
+- REQUIRED: All waves executed in dependency order.
+- REQUIRED: EXC artifact registered in state.json.
+
+### Evidence Requirement
+
+Task summaries MUST include:
+- Files actually modified (not just planned targets)
+- Convergence criteria verification results (pass/fail with evidence)
+- Any deviations from the plan with rationale
+
 ### Post-task Knowledge Inquiry
 
 After each task completion, check triggers:
@@ -86,7 +109,8 @@ After each task completion, check triggers:
 | retry_count >= 2 | "Document fix pattern?" | spec-add debug |
 | Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
 
-On confirm → `Skill("spec-add", "<category> <content>")`.
+On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+Include `--description` with a one-line summary for search result display.
 
 ### Issue Status Sync
 
@@ -134,8 +158,7 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| All tasks completed successfully | `/maestro-verify` |
-| Specific plan needs verification | `/maestro-verify --dir {dir}` |
+| All tasks completed successfully | `/quality-review` |
 | Failed tasks exist | `/quality-debug` |
 | View project dashboard | `/manage-status` |
 </completion>

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

@@ -42,6 +42,30 @@ Follow '~/.maestro/workflows/fork.md' completely.
 
 Fork and sync algorithm steps are defined in workflow `fork.md`.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**Fork mode:**
+
+**GATE 1: Validation → Worktree Creation**
+- REQUIRED: Milestone resolved from state.json.milestones[].
+- REQUIRED: No existing active worktree for this milestone (E008).
+- REQUIRED: Not running inside a worktree (E003).
+
+**GATE 2: Worktree Creation → Artifact Copy**
+- REQUIRED: Git worktree created with branch (`milestone/{slug}`).
+- REQUIRED: Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/).
+
+**GATE 3: Artifact Copy → Completion**
+- REQUIRED: `worktree-scope.json` written with milestone scope.
+- REQUIRED: Scoped `state.json` written (only this milestone's artifacts).
+- REQUIRED: `worktrees.json` registry updated in main worktree.
+
+**Sync mode:**
+
+**GATE: Sync → Completion**
+- REQUIRED: Git merge main into worktree branch completed.
+- REQUIRED: Shared artifacts re-copied.
+
 **Next-step routing on completion:**
 
 Fork mode:

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

@@ -50,7 +50,7 @@ $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstrea
 ### Pre-load
 
 1. **Specs**: `maestro spec load --category arch` — load architecture constraints
-2. **Wiki search**: `maestro wiki search "{topic keywords}"` → load relevant entries before grilling
+2. **Wiki search**: `maestro search "{topic keywords}"` → load relevant entries before grilling
 3. All optional — proceed without if unavailable
 </context>
 
@@ -71,6 +71,43 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 <execution>
 Follow '~/.maestro/workflows/grill.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Branch Walking** (Step 1 → Step 2)
+- REQUIRED: Topic parsed and output directory created.
+- REQUIRED: Initial codebase scan completed — at least one code reference identified for grounding.
+- BLOCKED if missing: cannot grill without code reality baseline.
+
+**GATE 2: Branch Walking → Synthesis** (Step 2 → Step 3)
+- REQUIRED: All depth-selected branches walked (shallow=3, standard=5, deep=8).
+- REQUIRED: Each branch has ≥2 Q&A pairs with evidence (code reference or explicit user input).
+- REQUIRED: Every locked decision has evidence — NOT just orchestrator inference.
+- BLOCKED if branches incomplete: continue walking before synthesizing.
+
+**GATE 3: Synthesis → Completion** (Step 3 → Report)
+- REQUIRED: `grill-report.md` written with Branch Log table + all Q&A entries + synthesis section.
+- REQUIRED: `terminology.md` written with ≥5 terms.
+- REQUIRED: `context-package.json` generated.
+- BLOCKED if any artifact missing: produce it before reporting completion.
+
+### Evidence Requirement
+
+Grill questions MUST reference specific code when challenging the user's proposal:
+- Valid: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+- INVALID: Generic questions without code grounding (e.g., "How would you handle errors?")
+- If codebase scan failed (W001): flag ALL subsequent locked decisions as LOW CONFIDENCE.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "grill-report.md",        // Branch Log + Q&A + synthesis
+  "terminology.md",         // ≥5 terms with code refs
+  "context-package.json"    // Schema "context-package/1.0"
+]
+```
+If any missing: DO NOT report completion. Go back and produce the missing artifact.
 </execution>
 
 <completion>

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

@@ -253,3 +253,16 @@ When findings lack explicit suggested command:
 | Personality, memorability | delight |
 
 Never auto-select: teach, shape, craft, live, document, extract, overdrive, critique, audit.
+
+## Chain Phase Gates (MANDATORY for chain mode)
+
+**GATE: Quality Gate Step → Next Step**
+- REQUIRED: Score parsed from critique/audit output (not assumed or estimated).
+- REQUIRED: P0 count extracted from findings — P0 == 0 required for pass.
+- REQUIRED: If gate fails, refine commands executed and re-gate attempted.
+- Do NOT skip quality gate steps or mark as "passed" without parsing actual score.
+
+**GATE: Chain → Completion**
+- REQUIRED: All non-skipped steps executed (TodoWrite all completed).
+- REQUIRED: status.json updated with `status: "completed"` and final scores.
+- REQUIRED: If any step failed: documented in status.json with reason.

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

@@ -59,6 +59,17 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 2. Validate `--from` source is accessible if provided
 
 Follow '~/.maestro/workflows/init.md' completely.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  ".workflow/project.md",    // Core Value, Requirements, Key Decisions
+  ".workflow/state.json",    // artifacts[], initialized to idle state
+  ".workflow/config.json"    // Workflow configuration
+]
+```
+If any artifact is missing: DO NOT report completion. Write the missing file first.
 </execution>
 
 <completion>

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

@@ -31,8 +31,24 @@ Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequen
 <execution>
 Follow '~/.maestro/workflows/merge.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Pre-merge → Git Merge**
+- REQUIRED: Registry health check completed (stale entries cleaned or flagged).
+- REQUIRED: Pre-merge rebase successful (worktree has latest main).
+- BLOCKED if rebase has conflicts: resolve in worktree first (W003).
+
+**GATE 2: Git Merge → Artifact Sync**
+- REQUIRED: Git merge completed without conflicts (or conflicts resolved via --continue).
+- Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
+
+**GATE 3: Artifact Sync → Completion**
+- REQUIRED: All scratch artifacts synced to main `.workflow/scratch/`.
+- REQUIRED: `state.json.artifacts[]` reconciled (worktree entries merged into main).
+- REQUIRED: Worktree cleaned up (unless --no-cleanup).
+
 **Knowledge inquiry on completion:**
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2>")`.
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `Skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
 
 **Next-step routing on completion:**
 - View dashboard → Skill({ skill: "manage-status" })

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

@@ -112,8 +112,7 @@ ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
 | 有 roadmap，未启动 phase | analyze | `maestro-analyze {phase}` |
 | 最新 artifact = analyze | plan | `maestro-plan {phase}` |
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
-| 最新 artifact = execute | verify | `maestro-verify {phase}` |
-| verify passed | review | `quality-review {phase}` |
+| 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |
 | 测试全绿 | milestone-audit | `maestro-milestone-audit` |
 | 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
@@ -122,7 +121,7 @@ ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
 **Maestro Lifecycle 主线：**
 ```
 brainstorm → blueprint → init → analyze-macro → roadmap
-   → [per phase] analyze → plan → execute → verify
+   → [per phase] analyze → plan → execute (includes verification)
    → [quality gate] review → auto-test → test
    → milestone-audit → milestone-complete → milestone-release
 ```
@@ -157,19 +156,19 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | 分析 / analyze / 多维度调研 | `maestro-analyze` |
 | 规划 / plan / 任务分解 | `maestro-plan` |
 | 实现 / 执行 / execute | `maestro-execute` |
-| 验证 / verify / 验收 | `maestro-verify` |
+| 验证 / verify / 验收 | `maestro-execute` |
 | 调试 / debug / 排查 / bug | `quality-debug` |
 | 审查 / review / 代码审查 | `quality-review` |
 | 测试 / test / UAT | `quality-test` / `quality-auto-test` |
 | 重构 / refactor / 技术债 | `quality-refactor` |
 | 同步文档 / sync docs | `quality-sync` |
-| 回顾 / retro | `quality-retrospective` / `learn-retro` |
+| 回顾 / retro | `quality-retrospective` |
 | issue / 缺陷管理 | `manage-issue` / `manage-issue-discover` |
-| wiki / 知识图谱 | `manage-wiki` / `wiki-connect` / `wiki-digest` |
+| wiki / 知识图谱 | `manage-wiki` (含 connect/digest 子命令) |
 | spec / 规则 / 约束 | `spec-load` / `spec-add` / `spec-setup` |
 | 项目初始化 / init | `maestro-init` |
 | 状态 / status / 仪表盘 | `manage-status` |
-| 文档重建 / codebase 文档 | `manage-codebase-rebuild` / `manage-codebase-refresh` |
+| 文档重建 / codebase 文档 | `manage-codebase-rebuild` / `quality-sync` |
 | 安全 / security / OWASP | `security-audit` |
 | 跟读 / 学习 / 阅读源码 | `learn-follow` / `learn-investigate` |
 | 第二意见 / challenge / consult | `learn-second-opinion` |
@@ -185,9 +184,9 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 |----|------|---------|
 | Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
 | Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
-| Wiki | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
+| Wiki | 知识图谱整理 | `manage-wiki health` → `manage-wiki connect` → `manage-wiki digest` |
 | Issue | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
-| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
+| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-rebuild` (if major) |
 | 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
 | 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
 | 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |

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

@@ -73,7 +73,7 @@ After confirming the injection point, ask whether this overlay should chain to a
 
 Use AskUserQuestion:
 - **"No chain"** — standard overlay, no skill handoff
-- **"Chain to skill"** → ask for the target skill name (e.g., `quality-review`, `maestro-verify`, `quality-test`)
+- **"Chain to skill"** → ask for the target skill name (e.g., `quality-review`, `maestro-execute`, `quality-test`)
 - **"Chain with alternatives"** → ask for primary skill + 1-2 alternative skills
 
 If chain is selected, record the skill name(s) for use in Step 3.
@@ -115,11 +115,11 @@ Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestr
 After the above step completes, use AskUserQuestion:
 - "Proceed to /quality-review" — Hand off to quality review
 - "Skip" — Continue with current command flow
-- "Alternative: /maestro-verify" — Run verification instead
+- "Alternative: /maestro-execute" — Run execution with built-in verification instead
 
 On user selection:
 - Proceed → Skill({ skill: "quality-review", args: "{phase}" })
-- Alternative → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Alternative → Skill({ skill: "maestro-execute", args: "{phase}" })
 - Skip → continue normally
 ```
 

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

@@ -59,7 +59,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 **Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
 
 ### Role Knowledge
-`maestro wiki list --category arch` → select relevant → `maestro wiki load`
+`maestro search --category arch` → select relevant → `maestro wiki load`
 </context>
 
 <execution>
@@ -73,6 +73,24 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### Phase Gates (MANDATORY, BLOCKING — Create mode only)
+
+**GATE P1 → P2**: Context collection completed — context files loaded, codebase docs read (if available), wiki searched.
+**GATE P2 → P3**: Clarification completed — ambiguous requirements resolved via AskUserQuestion (≤3 rounds).
+**GATE P3 → P4**: Plan generated by planner agent — `plan.json` + `.task/TASK-*.json` files written. Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
+**GATE P4 → P5**: Plan-checker passed (or minor issues acknowledged). Confidence scored. Pressure pass completed on highest-complexity task.
+**GATE P5 → Completion**: User confirmation captured (execute/modify/cancel). PLN artifact registered in state.json.
+
+### Artifact Verification (before completion)
+
+```
+REQUIRED_ARTIFACTS = [
+  "plan.json",                    // Task definitions, waves, summary
+  ".task/TASK-*.json" (per task)   // Individual task files with convergence criteria
+]
+```
+Every task MUST have `convergence.criteria[]` with grep-verifiable conditions. If any task lacks verifiable criteria: DO NOT report completion — fix the criteria first.
+
 ### P3 Agent Constraint (MANDATORY)
 
 Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.
@@ -95,7 +113,7 @@ During P1 Context Collection, after loading context files and before parallel ex
 
 ```
 phase_keywords = extract key terms from goal/title (2-5 terms)
-wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+wiki_result = Bash("maestro search ${phase_keywords} --json 2>/dev/null")
 
 IF wiki_result exit code != 0 OR empty:
   display "W003: Wiki search unavailable, continuing without prior knowledge"
@@ -167,7 +185,7 @@ Status verdicts:
 | 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 |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-execute first (verification is built-in) |
 | E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
 | E005 | error | Plan directory not found (--check) | Check path, use --dir |
 | W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |