maestro-flow 0.4.26 → 0.5.0

package/.agents/skills/maestro-help/phases/03-workflow-guide.md

@@ -45,7 +45,7 @@ const taskPatterns = [
 4. `/maestro-analyze "topic"` — 宏观分析，探索影响面 → scope_verdict
 5. `/maestro-roadmap --from analyze:ANL-xxx` — 纯编排，Milestone > Phase 分解
 6. `/maestro-analyze 1` — 微观分析，Phase 级深入
-7. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+7. `/maestro-plan 1` → `/maestro-execute`
 
 ### 路径 E: 纯规格文档（不进执行链）
 1. `/maestro-blueprint "project idea"` — 供人阅读和决策
@@ -62,7 +62,7 @@ const taskPatterns = [
 1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=large
 2. `/maestro-roadmap --from analyze:ANL-xxx` — Milestone > Phase 分解
 3. `/maestro-analyze 1` — 微观分析
-4. `/maestro-plan 1` → `/maestro-execute` → `/maestro-verify`
+4. `/maestro-plan 1` → `/maestro-execute`
 ```
 
 **中等功能 — Path C** (复杂度: 中，跳过 roadmap):
@@ -72,7 +72,7 @@ const taskPatterns = [
 
 1. `/maestro-analyze "feature X"` — 宏观分析 → scope_verdict=medium
 2. `/maestro-plan --from analyze:ANL-xxx` — 直达规划，跳过 roadmap
-3. `/maestro-execute` → `/maestro-verify`
+3. `/maestro-execute`
 
 ### 快速渠道（简单功能）
 1. `/maestro-quick "功能描述"` — 一键完成
@@ -87,7 +87,7 @@ const taskPatterns = [
 ## 小改动工作流
 
 1. `/maestro-plan "fix auth bug"` — 直接规划
-2. `/maestro-execute` → `/maestro-verify`
+2. `/maestro-execute`
 
 ### 快速修复（已知问题）
 1. `/maestro-quick "修复 Bug 描述"`
@@ -131,7 +131,7 @@ const taskPatterns = [
 上游起源: brainstorm(发散) | blueprint(收敛) → 可选
 理解层:   analyze "topic"(宏观) → scope_verdict 路由
 编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
-执行层:   plan → execute → verify → quality → milestone-audit → milestone-complete
+执行层:   plan → execute → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
 全自动: /maestro -y → (自动路由)
@@ -146,7 +146,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 
 - **Roadmap**: 项目级常驻规划文档，包含多个 Milestone
 - **Milestone**: 可独立交付的版本节点（v0.1.0-rc1），包含多个 Phase
-- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute → verify 生命周期
+- **Phase**: Milestone 内的同步屏障执行阶段，走 analyze → plan → execute 生命周期
 - **Task**: Phase 内的具体代码修改单元（wave DAG 管理并行）
 - **Blueprint**: 正式规格文档化命令（7-phase 收敛），与 brainstorm 并列作为上游起源
 - **Analyze 双层**: 宏观(文本参数)探索影响面产出 scope_verdict；微观(数字参数)Phase 级深入分析
@@ -179,8 +179,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 | 6 | `/maestro-roadmap` | 路线图编排 | scope_verdict=large 时，Milestone > Phase 分解 |
 | 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
 | 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
-| 9 | `/maestro-verify` | 验证 | 执行完成后，检查成果 |
-| 10 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 9 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
 ```
 
 #### Step 5.2: 快速入门路径

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

@@ -255,3 +255,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 (track_tasks all completed).
+- REQUIRED: status.json updated with `status: "completed"` and final scores.
+- REQUIRED: If any step failed: documented in status.json with reason.

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

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

@@ -33,8 +33,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 `invoke_skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2>")`.
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `invoke_skill("spec-add", "learning \"<title>\" \"<insight>\" --keywords <kw1>,<kw2> --description \"<summary>\"")`.
 
 **Next-step routing on completion:**
 - View dashboard → invoke_skill({ skill: "manage-status" })

package/.agents/skills/maestro-milestone-audit/SKILL.md

@@ -24,7 +24,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>
@@ -51,7 +51,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>
@@ -60,6 +60,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/.agents/skills/maestro-milestone-complete/SKILL.md

@@ -48,6 +48,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:
@@ -58,7 +76,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 `invoke_skill({ skill: "spec-add", args: "<category> <content>" })` with promoted content, preserving original date and source traceability.
 

package/.agents/skills/maestro-milestone-release/SKILL.md

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

@@ -114,8 +114,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` |
@@ -124,7 +123,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
 ```
@@ -159,19 +158,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` |
@@ -187,9 +186,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/.agents/skills/maestro-overlay/SKILL.md

@@ -75,7 +75,7 @@ After confirming the injection point, ask whether this overlay should chain to a
 
 Use ask_user:
 - **"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.
@@ -117,11 +117,11 @@ Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestr
 After the above step completes, use ask_user:
 - "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 → invoke_skill({ skill: "quality-review", args: "{phase}" })
-- Alternative → invoke_skill({ skill: "maestro-verify", args: "{phase}" })
+- Alternative → invoke_skill({ skill: "maestro-execute", args: "{phase}" })
 - Skip → continue normally
 ```
 

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

@@ -61,7 +61,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>
@@ -75,6 +75,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 ask_user (≤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.
@@ -97,7 +115,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 = shell("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+wiki_result = shell("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"
@@ -169,7 +187,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/.agents/skills/maestro-quick/SKILL.md

@@ -35,7 +35,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>
@@ -43,6 +43,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/.agents/skills/maestro-ralph/SKILL.md

@@ -76,11 +76,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 agent --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 agent` 校验路径存在性，不读 .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>
@@ -162,7 +164,7 @@ S_DISPATCH:
   → END             DO: invoke_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
@@ -391,8 +393,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% |
@@ -417,7 +418,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
    - 取 skill 名（args 前的第一个 token）
-   - **预校验通过 `shell("maestro ralph skills --json --quiet")`** 一次性拉取所有可用 commands + skills（global + project，project 覆盖 global），匹配 skill 名得到：
+   - **预校验通过 `shell("maestro ralph skills --platform agent --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
@@ -449,7 +450,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 |
@@ -462,13 +463,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}" }
    ```
 
@@ -621,11 +623,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 agent --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",
@@ -659,13 +661,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:**
@@ -673,8 +674,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}
 ```
@@ -693,8 +693,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}
@@ -709,7 +708,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}
 ```
@@ -757,8 +755,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 agent --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
+- [ ] Ralph build 阶段只通过 `ralph skills --platform agent` 校验路径存在性，不读 .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/.agents/skills/maestro-ralph-beta/SKILL.md

@@ -56,7 +56,7 @@ Remaining     → intent (new session)
 3. **执行 step 通过 `maestro ralph next` 加载** — CLI 解析 frontmatter + `<required_reading>` + `<deferred_reading>`、读 required 全文、拼 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`
 4. **decision step 内联评估** — 不 handoff、不调 ralph next；按 `step.decision` 分派 A_DECISION_*
 5. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入；STATUS 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`
-6. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，只扫描 `.claude/commands/`）；未命中标 `command_scope = "missing"`
+6. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform agent --json --quiet` 预校验（project 覆盖 global，只扫描 `.claude/commands/`）；未命中标 `command_scope = "missing"`
 7. **required reading 由 CLI 加载** — 缺失 → 退出码 1（E007）→ pause session；ralph build 阶段不读 .md 内容
 8. **active_step_index 一致性由 CLI 维护** — 同一 session 同时最多一个 step 持有；E008/E009 直接退出
 9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 由用户输入
@@ -179,7 +179,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
@@ -416,8 +416,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% |
@@ -439,7 +438,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（执行 step）：
    - skill 名 = args 前的第一个 token
-   - `shell("maestro ralph skills --platform claude --json --quiet")` 拉取 global + project（project 覆盖 global），匹配 skill 名：
+   - `shell("maestro ralph skills --platform agent --json --quiet")` 拉取 global + project（project 覆盖 global），匹配 skill 名：
      - 命中 → `command_scope = "global" | "project"`，`command_path = <绝对路径>`
      - 未命中 → `command_scope = "missing"`, `command_path = null` → A_CREATE_SESSION raise E006
 10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`, `load: null`
@@ -546,7 +545,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 |
@@ -719,8 +718,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]
      ...
    ============================================================
    ```
@@ -795,13 +793,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:**
@@ -809,8 +806,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}
 ```
@@ -829,8 +825,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}
@@ -845,7 +840,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}
 ```