maestro-flow 0.4.26 → 0.5.0

package/.claude/commands/maestro-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/.claude/commands/maestro-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/.claude/commands/maestro-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/.claude/commands/maestro-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

package/.claude/commands/maestro-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/.claude/commands/maestro-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/.claude/commands/maestro-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 |

package/.claude/commands/maestro-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/.claude/commands/maestro-ralph-beta.md

@@ -177,7 +177,7 @@ S_TICK_EXEC: Entry: A_EXEC_STEP
   → S_HANDLE_FAIL   WHEN: ralph complete with NEEDS_RETRY|BLOCKED
 
 S_TICK_DECISION: (gate 名取自 `step.decision`)
-  → S_TICK_APPLY    WHEN: quality-gate (post-verify, post-business-test, post-review, post-test)
+  → S_TICK_APPLY    WHEN: quality-gate (post-execute, post-business-test, post-review, post-test)
                      DO: A_DELEGATE_EVALUATE
   → S_TICK_APPLY    WHEN: goal-gate (post-goal-audit)
                      DO: A_GOAL_AUDIT_EVALUATE
@@ -414,8 +414,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 | roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | — | all |
 | analyze | `maestro-analyze {phase}` | `maestro-analyze` | — | all |
 | plan | `maestro-plan {phase}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | — | all |
-| execute | `maestro-execute {phase}` | `maestro-execute` | — | all |
-| verify | `maestro-verify {phase}` | `maestro-verify` | `post-verify` | all |
+| execute | `maestro-execute {phase}` | `maestro-execute` | `post-execute` | all |
 | business-test | `quality-auto-test {phase}` | `quality-auto-test` | `post-business-test` | full only |
 | review | `quality-review {phase}` | `quality-review` | `post-review` | all (quick: append `--tier quick`) |
 | test-gen | `quality-auto-test {phase}` | `quality-auto-test` | — | full / standard if coverage<80% |
@@ -544,7 +543,7 @@ Write enriched args back to status.json.
 3. Map result files:
    | Decision | Files |
    |----------|-------|
-   | post-verify | verification.json |
+   | post-execute | verification.json |
    | post-business-test | .tests/auto-test/report.json |
    | post-review | review.json |
    | post-test | uat.md, .tests/test-results.json |
@@ -717,8 +716,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
      [✓] 0.   maestro-plan 1            [global]
      [✓] 1.   maestro-execute 1         [project]
-     [✓] 2.   maestro-verify 1          [global]
-     [✓] 3. ◆ post-verify               [decision]
+     [✓] 2. ◆ post-execute               [decision]
      ...
    ============================================================
    ```
@@ -793,13 +791,12 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
 插入的执行 step 按 A_BUILD_STEPS 规则 9 解析 `command_path` + `command_scope`；`decision:*` 条目为 decision 节点。
 
-**post-verify:**
+**post-execute:**
 ```
 quality-debug "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry+1}
+decision:post-execute {retry+1}
 ```
 
 **post-business-test:**
@@ -807,8 +804,7 @@ decision:post-verify {retry+1}
 quality-debug --from-business-test "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry+1}
 ```
@@ -827,8 +823,7 @@ decision:post-review {retry+1}
 quality-debug --from-uat "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry: 0}
 quality-review {phase}
@@ -843,7 +838,6 @@ decision:post-test {retry+1}
 # for each unmet sub-goal G{n}, scoped to target_phase:
 maestro-plan --gaps {target_phase} "G{n}: {gap}"     [goal_ref: G{n}]
 maestro-execute {target_phase}                       [goal_ref: G{n}]
-maestro-verify {target_phase}                        [goal_ref: G{n}]
 # after all unmet groups inserted:
 decision:post-goal-audit {retry+1}
 ```

package/.claude/commands/maestro-ralph-execute.md

@@ -201,8 +201,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 
      [✓] 0.   maestro-plan 1            [global]
      [✓] 1.   maestro-execute 1         [project]
-     [✓] 2.   maestro-verify 1          [global]
-     [✓] 3. ◆ post-verify               [decision]
+     [✓] 2. ◆ post-execute               [decision]
      ...
    ============================================================
    ```

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

@@ -74,11 +74,13 @@ Remaining     → intent
 4. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（详见 invariant 8）
 5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
 6. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
-7. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global），命中即写绝对路径到 status.json；未命中标 `command_scope = "missing"`
-8. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成：解析 frontmatter + `<required_reading>` + `<deferred_reading>`，自动读取 required 文件全文并拼入 prompt；缺失 required → 退出码 1（E007），pause session。ralph build 阶段只通过 `maestro ralph skills` 校验路径存在性，不读 .md 内容
+7. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，限定 `.claude/commands/` + `.claude/skills/`），命中即写绝对路径到 status.json；未命中标 `command_scope = "missing"`
+8. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成：解析 frontmatter + `<required_reading>` + `<deferred_reading>`，自动读取 required 文件全文并拼入 prompt；缺失 required → 退出码 1（E007），pause session。ralph build 阶段只通过 `maestro ralph skills --platform claude` 校验路径存在性，不读 .md 内容
 9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 输出提示词后继续 handoff，用户可在执行过程中随时输入 `/goal`
 10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
+12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作。不得以 "效率" 或 "意图明确" 为由绕过。特别是 invariant 1（ralph 不执行 step）和 invariant 6（completion_confirmed 由 CLI 写入）不可隐性违反。
+13. **Delegate fallback 必须标记** — A_DELEGATE_EVALUATE 解析 verdict 失败时 fallback 为 "fix"，但 MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`，后续 step 继承 LOW CONFIDENCE 标记。
 </invariants>
 
 <state_machine>
@@ -160,7 +162,7 @@ S_DISPATCH:
   → END             DO: Skill({ skill: "maestro-ralph-execute" })
 
 S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取自该字段)
-  → S_APPLY_VERDICT WHEN: quality-gate (post-verify, post-business-test, post-review, post-test)
+  → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test)
                      DO: A_DELEGATE_EVALUATE
   → S_APPLY_VERDICT WHEN: goal-gate (post-goal-audit)
                      DO: A_GOAL_AUDIT_EVALUATE
@@ -389,8 +391,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 | roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | — | all |
 | analyze | `maestro-analyze {phase}` | `maestro-analyze` | — | all |
 | plan | `maestro-plan {phase}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | — | all |
-| execute | `maestro-execute {phase}` | `maestro-execute` | — | all |
-| verify | `maestro-verify {phase}` | `maestro-verify` | `post-verify` | all |
+| execute | `maestro-execute {phase}` | `maestro-execute` | `post-execute` | all |
 | business-test | `quality-auto-test {phase}` | `quality-auto-test` | `post-business-test` | full only |
 | review | `quality-review {phase}` | `quality-review` | `post-review` | all (quick: append `--tier quick`) |
 | test-gen | `quality-auto-test {phase}` | `quality-auto-test` | — | full / standard if coverage<80% |
@@ -415,7 +416,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
    - 取 skill 名（args 前的第一个 token）
-   - **预校验通过 `Bash("maestro ralph skills --json --quiet")`** 一次性拉取所有可用 commands + skills（global + project，project 覆盖 global），匹配 skill 名得到：
+   - **预校验通过 `Bash("maestro ralph skills --platform claude --json --quiet")`** 一次性拉取 claude 平台可用 commands + skills（global + project，project 覆盖 global），匹配 skill 名得到：
      - 命中 commands → `command_scope = "global" | "project"`，`command_path = <绝对路径>`
      - 命中 skills → 同上（type=skill）
      - 未命中 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
@@ -447,7 +448,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 3. Map result files:
    | Decision | Files |
    |----------|-------|
-   | post-verify | verification.json |
+   | post-execute | verification.json |
    | post-business-test | .tests/auto-test/report.json |
    | post-review | review.json |
    | post-test | uat.md, .tests/test-results.json |
@@ -460,13 +461,14 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    CONSTRAINTS: 只评估 | 置信度<60% 倾向 fix | retry {n}/{max} 达上限必须 escalate"
    --role analyze --mode analysis
    ```
-6. On callback: parse verdict; if parse fails → fallback STATUS="fix"
+6. On callback: parse verdict; if parse fails → fallback STATUS="fix", BUT MUST set `parse_failed: true` and `confidence_score: 0` in decision log (invariant 13). Subsequent steps inherit LOW CONFIDENCE flag.
 7. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
 8. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
    ```json
    { "id": "DEC-{timestamp}", "timestamp": "{ISO}", "source": "ralph",
      "node_id": "{step.decision}", "type": "quality-gate",
      "verdict": "{adjusted_verdict}", "confidence_score": {N},
+     "parse_failed": false,
      "close_call": {N>=50 && N<=70}, "summary": "{REASON}" }
    ```
 
@@ -619,11 +621,11 @@ Runs only when `task_decomposition` present.
     "args": "",
     "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
     "scope": null,                // "phase"|"standalone"|"milestone"|null（plan 等需要）
-    "decision": null,             // 非 null → decision 节点（值为 gate 名，如 "post-verify"）；null → 执行 step
+    "decision": null,             // 非 null → decision 节点（值为 gate 名，如 "post-execute"）；null → 执行 step
     "retry_count": 0,             // decision 节点专用
     "max_retries": 2,             // decision 节点专用
     "command_scope": "global|project|missing|null",  // 执行 step；decision 节点固定 null
-    "command_path": "<absolute path resolved by `maestro ralph skills --json --quiet`> | null",
+    "command_path": "<absolute path resolved by `maestro ralph skills --platform claude --json --quiet`> | null",
     "milestone_id": null,         // D-007 反查注入；仅含 {phase} 占位符的 step 有
     "source_artifact_ref": null,  // "analyze:ANL-xxx" | "blueprint:BLP-xxx" | null
     "status": "pending|running|completed|skipped|failed",
@@ -657,13 +659,12 @@ Runs only when `task_decomposition` present.
 
 所有插入的执行 step 按 A_BUILD_STEPS 规则 9 解析 `command_path` + `command_scope`；`decision:*` 条目为 decision 节点（`step.decision` 字段）。
 
-**post-verify:**
+**post-execute:**
 ```
 quality-debug "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry+1}
+decision:post-execute {retry+1}
 ```
 
 **post-business-test:**
@@ -671,8 +672,7 @@ decision:post-verify {retry+1}
 quality-debug --from-business-test "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry+1}
 ```
@@ -691,8 +691,7 @@ decision:post-review {retry+1}
 quality-debug --from-uat "{gap_summary}"
 maestro-plan --gaps {phase}
 maestro-execute {phase}
-maestro-verify {phase}
-decision:post-verify {retry: 0}
+decision:post-execute {retry: 0}
 quality-auto-test {phase}
 decision:post-business-test {retry: 0}
 quality-review {phase}
@@ -707,7 +706,6 @@ decision:post-test {retry+1}
 # for each unmet sub-goal G{n}, scoped to target_phase:
 maestro-plan --gaps {target_phase} "G{n}: {gap}"     [goal_ref: G{n}]
 maestro-execute {target_phase}                       [goal_ref: G{n}]
-maestro-verify {target_phase}                        [goal_ref: G{n}]
 # after all unmet groups inserted:
 decision:post-goal-audit {retry+1}
 ```
@@ -755,8 +753,8 @@ decision:post-goal-audit {retry+1}
 - [ ] quality_mode 由 A_DETERMINE_QUALITY_MODE 决定，过滤 build steps
 - [ ] Decomposition: broad intent ≤3 question clarify；narrow auto-derive
 - [ ] status.json 唯一真源：boundary_contract + execution_criteria + task_decomposition；无外部清单
-- [ ] 执行 step 含 `command_scope` + `command_path`（通过 `maestro ralph skills --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
-- [ ] Ralph build 阶段只通过 `ralph skills` 校验路径存在性，不读 .md 内容；`<required_reading>` 加载由 `maestro ralph next` CLI 完成
+- [ ] 执行 step 含 `command_scope` + `command_path`（通过 `maestro ralph skills --platform claude --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
+- [ ] Ralph build 阶段只通过 `ralph skills --platform claude` 校验路径存在性，不读 .md 内容；`<required_reading>` 加载由 `maestro ralph next` CLI 完成
 - [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 false/null/[]）
 - [ ] 每个 sub-goal 含 `completion_confirmed`（初始 false）
 - [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前

package/.claude/commands/maestro-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/.claude/commands/maestro-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/.claude/commands/maestro-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