maestro-flow 0.4.26 → 0.5.0

package/.agents/skills/learn-follow/SKILL.md

@@ -25,7 +25,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/.agents/skills/learn-investigate/SKILL.md

@@ -32,7 +32,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>
@@ -85,7 +85,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/.agents/skills/learn-second-opinion/SKILL.md

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

package/.agents/skills/maestro/SKILL.md

@@ -51,12 +51,14 @@ $ARGUMENTS — user intent text, or special keywords.
 3. **Auto flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args
 4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
-6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）；decision 节点不走 CLI，走 `invoke_skill("maestro-ralph")` handoff
+6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform agent --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `invoke_skill("maestro-ralph")` handoff
 7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
 8. **Grill is interactive-only** — `-y` auto mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
 11. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
+12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
+13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
 </invariants>
 
 <state_machine>
@@ -137,13 +139,14 @@ S_FALLBACK:
 3. Select chain from chainMap，遵循拓扑约束：
    - 压力测试/拷问/验证假设/grill/stress-test → `grill`（**-y 模式跳过 grill，直接走 brainstorm**）
    - 头脑风暴/探索 → `brainstorm`
+   - 学习/阅读代码/跟读/follow → `invoke_skill("learn-follow")`；调查/为什么/investigate → `invoke_skill("learn-investigate")`；分解/模式/decompose → `invoke_skill("learn-decompose")`；评审/挑战/second-opinion → `invoke_skill("learn-second-opinion")`；回顾/retro → `invoke_skill("quality-retrospective")`
    - 正式规格/spec-generate/7-phase → `blueprint`
    - 项目初始化 → `init`
    - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
    - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
    - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
    - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
-4. 执行 step：`shell("maestro ralph skills --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
+4. 执行 step：`shell("maestro ralph skills --platform agent --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
 
@@ -230,7 +233,7 @@ S_FALLBACK:
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
 - [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识
-- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）
+- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --platform agent --json --quiet` 预校验（project 覆盖 global）
 - [ ] Session schema 含 `ralph_protocol_version: "1"` + `active_step_index: null` + step.load 占位
 - [ ] 用户传入 `-y` 时透传到 skill args
 - [ ] All chains dispatched via maestro-ralph-execute

package/.agents/skills/maestro-analyze/SKILL.md

@@ -73,11 +73,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>
@@ -95,6 +95,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/.agents/skills/maestro-blueprint/SKILL.md

@@ -66,7 +66,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>
 
@@ -92,6 +92,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/.agents/skills/maestro-brainstorm/SKILL.md

@@ -59,7 +59,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...]`
@@ -79,6 +79,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/.agents/skills/maestro-collab/SKILL.md

@@ -27,7 +27,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/.agents/skills/maestro-companion/SKILL.md

@@ -116,7 +116,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.
@@ -129,7 +129,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
 
@@ -343,7 +343,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>"
 ```
 
 ---
@@ -472,7 +472,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/.agents/skills/maestro-composer/SKILL.md

@@ -128,7 +128,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/.agents/skills/maestro-execute/SKILL.md

@@ -19,7 +19,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>
@@ -58,13 +58,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>
@@ -78,6 +78,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:
@@ -88,7 +111,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 → `invoke_skill("spec-add", "<category> <content>")`.
+On confirm → `invoke_skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+Include `--description` with a one-line summary for search result display.
 
 ### Issue Status Sync
 
@@ -136,8 +160,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/.agents/skills/maestro-fork/SKILL.md

@@ -44,6 +44,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/.agents/skills/maestro-grill/SKILL.md

@@ -52,7 +52,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>
 
@@ -73,6 +73,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/.agents/skills/maestro-help/SKILL.md

@@ -197,7 +197,6 @@ $ARGUMENTS → Parse:
 | `/maestro-analyze` | 双层分析 — 宏观(文本参数)探索影响面 / 微观(数字参数)Phase 级深入 |
 | `/maestro-plan` | 任务规划 — 支持 `--from analyze:ANL-xxx` 直达 |
 | `/maestro-execute` | 任务执行 |
-| `/maestro-verify` | 验证确认 |
 
 ### 质量管线 (quality)
 
@@ -247,17 +246,17 @@ Roadmap > Milestone > Phase > Task
   roadmap — 消费上游 context，纯 Milestone > Phase 分解
 
 执行层
-  plan → execute → verify
+  plan → execute
 ```
 
 ### 合法路径
 
 | 路径 | 场景 | 命令序列 |
 |------|------|---------|
-| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
-| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` → `verify` |
-| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` → `verify` |
-| Path D | 小改动 | `plan "fix auth bug"` → `execute` → `verify` |
+| Path A | 完整新项目 | `brainstorm` → `blueprint`(可选) → `analyze "topic"` → `roadmap` → `analyze 1` → `plan 1` → `execute` |
+| Path B | 旧项目大功能 | `analyze "feature X"` → `roadmap` → `analyze 1` → `plan 1` → `execute` |
+| Path C | 中等功能 | `analyze "feature X"` → `plan --from analyze:ANL-xxx` → `execute` |
+| Path D | 小改动 | `plan "fix auth bug"` → `execute` |
 | Path E | 纯规格文档 | `blueprint "project idea"` → (供人阅读) |
 | Path F | 纯探索 | `brainstorm "idea"` → (供人决策) |
 | 快速修复 | 已知简单问题 | `/maestro-quick "修复描述"` |

package/.agents/skills/maestro-help/index/catalog.json

@@ -13,7 +13,6 @@
     {"name": "maestro-analyze", "command": "/maestro-analyze", "category": "pipeline", "description": "双层分析 — 宏观(文本参数)探索影响面+scope_verdict / 微观(数字参数)Phase 级深入", "source": "../../commands/maestro-analyze.md"},
     {"name": "maestro-plan", "command": "/maestro-plan", "category": "pipeline", "description": "任务规划 — 支持 --from analyze:ANL-xxx 直达、碰撞检测、gap 修复计划", "source": "../../commands/maestro-plan.md"},
     {"name": "maestro-execute", "command": "/maestro-execute", "category": "pipeline", "description": "任务执行 — wave 并行执行、delegate 编排、自动提交", "source": "../../commands/maestro-execute.md"},
-    {"name": "maestro-verify", "command": "/maestro-verify", "category": "pipeline", "description": "验证确认 — 成果检查、gap 发现、下一阶段建议", "source": "../../commands/maestro-verify.md"},
     {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
     {"name": "maestro-overlay", "command": "/maestro-overlay", "category": "core", "description": "Overlay 管理 — 创建、查看、删除命令补丁", "source": "../../commands/maestro-overlay.md"},
     {"name": "maestro-amend", "command": "/maestro-amend", "category": "core", "description": "修正补丁 — 从工作流信号自动生成 overlay", "source": "../../commands/maestro-amend.md"},
@@ -156,7 +155,6 @@
     "/maestro-roadmap",
     "/maestro-plan",
     "/maestro-execute",
-    "/maestro-verify",
     "/maestro-quick"
   ],
   "workflows": {
@@ -166,27 +164,27 @@
         "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
         "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
         "orchestration": "roadmap (可选，消费上游 context)",
-        "execution": ["plan", "execute", "verify"]
+        "execution": ["plan", "execute"]
       }
     },
     "paths": {
-      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
-      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute → verify",
-      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute → verify",
-      "D_small_fix": "plan → execute → verify",
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute",
+      "D_small_fix": "plan → execute",
       "E_spec_only": "blueprint → (供人阅读)",
       "F_explore_only": "brainstorm → (供人决策)"
     },
     "main_pipeline": {
       "name": "主干管线",
-      "phases": ["analyze", "plan", "execute", "verify"],
+      "phases": ["analyze", "plan", "execute"],
       "quality": ["quality-auto-test", "quality-review", "quality-test"],
       "close": ["maestro-milestone-audit", "maestro-milestone-complete"]
     },
     "quick": {
       "name": "快速渠道",
       "entry": "/maestro-quick",
-      "modes": ["default (analyze+execute)", "--full (analyze+plan+execute+verify)", "--discuss (multi-cli讨论)"]
+      "modes": ["default (analyze+execute)", "--full (analyze+plan+execute)", "--discuss (multi-cli讨论)"]
     },
     "issue_loop": {
       "name": "Issue 闭环",

package/.agents/skills/maestro-help/phases/02-search-present.md

@@ -69,7 +69,7 @@
 
 | 命令 | Guide 文档 |
 |------|-----------|
-| maestro-analyze/plan/execute/verify | `guide/command-usage-guide.md` (主干管线) |
+| maestro-analyze/plan/execute | `guide/command-usage-guide.md` (主干管线) |
 | maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` |
 | maestro-ralph | `guide/maestro-ralph-guide.md` |
 | maestro (协调器) | `guide/maestro-coordinator-guide.md` |
@@ -97,9 +97,7 @@
 | roadmap 完成，phase=pending | `/maestro-analyze 1` | 微观分析：Phase 级深入探索 |
 | analyze (微观) 完成 | `/maestro-plan 1` | Phase 级规划 |
 | plan 完成 | `/maestro-execute` | 规划完成，开始执行 |
-| execute 完成 | `/maestro-verify` | 执行完成，验证成果 |
-| verify 有 gaps | `/maestro-analyze --gaps` | 发现差距，重新分析 |
-| verify 通过 | `/quality-review` | 进入质量管线 |
+| execute 完成 | `/quality-review` | 执行完成，进入质量管线 |
 | quality 全通过 | `/maestro-milestone-audit` | 准备里程碑审计 |
 | 所有 Phase 完成 | `/maestro-milestone-complete` | 里程碑可以关闭 |