maestro-flow 0.5.47 → 0.5.48

package/.claude/agents/ralph-executor.md

@@ -1,6 +1,6 @@
 ---
 name: ralph-executor
-description: Single-step executor — ralph next + inline skill execution, multi-agent orchestration via SendMessage
+description: Single-step executor — ralph next + inline skill execution, unnamed nesting for multi-agent orchestration
 allowed-tools:
   - Read
   - Write
@@ -10,48 +10,42 @@ allowed-tools:
   - Grep
   - Skill
   - Agent
-  - SendMessage
 ---
 
 # Ralph Executor
 
 ## Role
 
-Single-step skill executor with multi-agent orchestration capability. Call `maestro ralph next` to load the skill prompt, execute it inline, return execution output via SendMessage. You are a sandboxed executor — arg resolution, context assembly, signal extraction, drift analysis, and session management are handled by the orchestrator.
+Single-step skill executor with multi-agent orchestration capability. Call `maestro ralph next` to load the skill prompt, execute it inline, return execution output as final text. You are a sandboxed executor — arg resolution, context assembly, signal extraction, drift analysis, and session management are handled by the orchestrator.
 
 ## Process
 
-**立即自启动**：你是 named mailbox teammate。收到含 `session_id` 和 `agent_name` 的 dispatch prompt 后，MUST 立即从 step 1 开始执行——禁止等待 mailbox 后续指令，禁止发送 idle notification。
+**立即自启动**：收到含 `session_id` 的 dispatch prompt 后，MUST 立即从 step 1 开始执行。
 
 1. Call `Bash("maestro ralph next --session {session_id}")` — **全量捕获 stdout，严禁截断管道**
    - Exit 0 → skill_prompt = stdout，继续执行
-   - Exit 1 → SendMessage 错误信息给 main，结束
-   - Exit 2 → SendMessage "所有 step 已完成" 给 main，结束
-   - Exit 3 → SendMessage "并发冲突" 给 main，结束
+   - Exit 1 → 返回错误信息，结束
+   - Exit 2 → 返回 "所有 step 已完成"，结束
+   - Exit 3 → 返回 "并发冲突"，结束
 2. Execute the skill prompt inline — follow all instructions faithfully
 3. Handle `<deferred_reading>` paths: Read files on demand during execution, do not batch-load upfront
-4. SendMessage({to: "main"}) 返回执行产物路径 + 摘要
+4. 返回执行产物路径 + 摘要作为最终输出文本（主流程通过 task-notification `<result>` 接收）
 
 ## Multi-Agent Orchestration
 
 当 skill prompt 需要多 agent 编排时（如 `maestro-execute` 的 wave 并行派发）：
 
-1. **派发 named worker**：调用 `Agent({name})` 派发 worker 为 named teammate，确保长时间任务存活：
-   ```
-   worker name 格式: {agent_name}-w{index}（如 exe-v2-001-w1, exe-v2-001-w2）
-   ```
-   > **必须传 name**：匿名 agent 执行完当前任务会 came to rest（死亡），后台任务完成通知无法唤醒。Named teammate 只会 idle，可被后台任务通知或 SendMessage 唤醒。
-2. **等待结果**：worker 通过 SendMessage 回传结果到 executor 的 mailbox
-3. **收集汇总**：接收所有 worker 的 SendMessage，汇总执行结果
-4. **回报主流程**：通过 `SendMessage({to: "main"})` 返回最终执行输出
+1. **派发 unnamed worker**：调用 `Agent()` 不传 name，子结果自动回流给本 executor（嵌套套娃模型）
+2. **等待结果**：子 Agent 的 task-notification 会自动回流到本 executor，可直接使用返回的 `<result>`
+3. **收集汇总**：汇总所有子 Agent 的执行结果
+4. **返回**：将最终执行输出作为文本返回（主流程通过 task-notification 接收）
 
 ### Worker Dispatch Template
 
 ```
 Agent({
-  name: "{agent_name}-w{index}",
   description: "执行子任务: {task_description}",
-  prompt: "你是 worker agent。执行以下任务：\n{task_content}\n\n完成后必须调用 SendMessage({to: \"{agent_name}\", summary: \"worker完成\", message: \"WORKER_RESULT: [执行结果摘要 + 产物路径]\"})。"
+  prompt: "执行以下任务：\n{task_content}\n\n返回执行结果摘要 + 产物路径。"
 })
 ```
 
@@ -62,12 +56,11 @@ Agent({
 | Field | Required | Description |
 |-------|----------|-------------|
 | `session_id` | Yes | ralph session ID |
-| `agent_name` | Yes | 本 agent 的 name，用于 sub-agent SendMessage 回传 |
 | execution context | No | 编排器注入的上下文（intent、boundary、goals、prior steps 等） |
 
 ## Output
 
-通过 `SendMessage({to: "main"})` 返回，格式：
+返回最终文本（主流程通过 task-notification `<result>` 接收），格式：
 
 ```
 EXECUTOR_OUTPUT:
@@ -78,14 +71,11 @@ EXECUTOR_OUTPUT:
 - error: <错误信息，仅 ERROR 时>
 ```
 
-失败时也必须 SendMessage，禁止静默崩溃。
-
 ## Constraints
 
-- 禁止无故空转——收到 session_id 即开始执行，不等待编排器的后续 mailbox 指令。等待 worker SendMessage 回传期间的 idle 是正常行为（平台自动触发 idle_notification，不可抑制）
+- 收到 session_id 即开始执行
 - Execute exactly one step per invocation
 - Do not call `maestro ralph complete` — completion is handled by the orchestrator
 - Do not read or modify `status.json` — session management is the orchestrator's responsibility
 - Do not skip execution steps or short-circuit — execute the full skill content
 - Do not insert/delete/reorder steps or evaluate decision nodes
-- 所有执行结果必须通过 SendMessage({to: "main"}) 回报，直接文本输出主流程看不到

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[phase|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
+argument-hint: "[milestone|topic] [-y] [-c] [-q] [--gaps [ISS-ID]]"
 allowed-tools:
   - Read
   - Write
@@ -27,17 +27,17 @@ Multi-dimensional analysis of a proposal, decision, or architecture choice via C
 </deferred_reading>
 
 <context>
-$ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no args for milestone-wide.
+$ARGUMENTS -- milestone number for micro mode, topic text for macro/adhoc mode, no args for current milestone.
 
 **Dual-layer mode:**
 - **Macro mode** (text argument): Explore impact surface of a topic/requirement. Produces coarse-grained context with `scope_verdict` to route next step. Use before roadmap or for standalone analysis.
-- **Micro mode** (numeric argument): Phase-level deep analysis within an existing roadmap. Produces fine-grained context for plan consumption. `analyze 1` = Phase 1 of current milestone.
+- **Micro mode** (numeric argument): Milestone-level deep analysis within an existing roadmap. Covers all phases under the milestone. Same analysis depth, broader scope. `analyze 1` = Milestone 1.
 
 **Disambiguation rule (mode selection):**
-- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as phase number)
+- First positional arg matches `^\d+$` (pure digits, e.g. `1`, `42`) → **micro mode** (treat as milestone number)
 - First positional arg is non-numeric text (e.g. `auth-refactor`, `improve search`) → **macro mode** (treat as topic)
-- No positional arg → milestone-wide micro mode (when roadmap present) else macro fallback
-- Mixed input like `"1 phase"` is treated as text → macro mode (only bare numerics trigger micro)
+- No positional arg → current milestone micro mode (when roadmap present) else macro fallback
+- Mixed input like `"1 milestone"` is treated as text → macro mode (only bare numerics trigger micro)
 
 **Flags:**
 
@@ -52,9 +52,9 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 **Scope routing:**
 | Input | Mode | Scope |
 |-------|------|-------|
-| Pure digits (e.g. `1`, `42`) | micro | Phase-level deep analysis |
+| Pure digits (e.g. `1`, `42`) | micro | Milestone-level deep analysis |
 | Non-numeric text (e.g. `auth-refactor`) | macro | Topic impact surface |
-| No positional arg + roadmap | micro | Milestone-wide |
+| No positional arg + roadmap | micro | Current milestone |
 | No positional arg + no roadmap | macro | Fallback |
 | `--gaps [ISS-ID]` | gaps | Issue root cause analysis |
 
@@ -79,7 +79,7 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 **Scope guard**: only analyze decisions; do not prejudge plan/execute concerns
 **Writeback target**: discussion.md (top table) + context.md "Interview Decisions"
 **Additional search sources**: issues.jsonl (--gaps mode), roadmap.md
-**Additional skip conditions**: input is already specific (explicit phase number or unambiguous topic)
+**Additional skip conditions**: input is already specific (explicit milestone number or unambiguous topic)
 **Exit condition**: all decision points settled → finalize session metadata
 </interview_protocol>
 
@@ -122,9 +122,9 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Phase/Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
-| Phase/Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {phase}` |
-| Phase/Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
+| Milestone scope, Go, UI work needed | `/maestro-impeccable build {target}` |
+| Milestone scope, Go, ready to plan | `/maestro-plan` or `/maestro-plan {milestone}` |
+| Milestone scope, No-Go | Revisit requirements or `/maestro-brainstorm {topic}` |
 | Macro/Adhoc, scope_verdict = large | `/maestro-roadmap --from analyze:ANL-xxx` |
 | Macro/Adhoc, scope_verdict = medium/small | `/maestro-plan --from analyze:ANL-xxx` |
 | Need more exploration | `/maestro-analyze {topic} -c` |
@@ -175,7 +175,7 @@ Both modes (full + quick):
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Scope creep redirected to Deferred section
 - [ ] Deferred items auto-created as issues (if any)
-- [ ] Artifact registered in state.json with correct scope/milestone/phase
+- [ ] Artifact registered in state.json with correct scope/milestone
 - [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>

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

@@ -152,7 +152,7 @@ Write `nodes.json`. Display resolved node list.
 |------|-----------|
 | Artifact boundary | Source outputs plan/spec/analysis/review |
 | Execution gate | Target contains `execute` |
-| Long-running | Target is maestro-plan, maestro-roadmap --mode full |
+| Long-running | Target is maestro-plan, maestro-blueprint |
 | Post-testing | Source contains `test` or `auto-test` |
 | User-defined | type_hint == checkpoint |
 

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

@@ -132,7 +132,7 @@ Status verdicts:
 | Condition | Suggestion |
 |-----------|-----------|
 | Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
-| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
+| Full spec package | `/maestro-blueprint <idea>` |
 | Explore ideas first | `/maestro-brainstorm <topic>` |
 | View project dashboard | `/manage-status` |
 | Quick ad-hoc task | `/maestro-quick <task>` |

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

@@ -56,7 +56,7 @@ Audit checklist steps (phase coverage, ad-hoc completeness, execution completene
 
 **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).
+- REQUIRED: Milestone phases identified from the PLN artifact's plan.json (standard) or milestone_obj.phases (adhoc). Phase coverage is verified from the PLN artifact's plan.json, not from roadmap.
 - BLOCKED if no execute artifacts found: error E003.
 
 **GATE 2: Phase Coverage → Integration Check**
@@ -116,7 +116,7 @@ Status verdicts:
 </error_codes>
 
 <success_criteria>
-- [ ] All phases in milestone identified from roadmap (standard) or milestone_obj.phases (adhoc)
+- [ ] All phases in milestone identified from the PLN artifact's plan.json (standard) or milestone_obj.phases (adhoc)
 - [ ] Artifact chains verified: ANL→PLN→EXC per phase (standard) or PLN→EXC exists (adhoc)
 - [ ] Ad-hoc artifacts checked for completion
 - [ ] Integration check completed (shared interfaces, data contracts)

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

@@ -111,7 +111,7 @@ Status verdicts:
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Release successful, starting next milestone | `/maestro-plan {next_phase}` |
+| Release successful, starting next milestone | `/maestro-plan {next_milestone}` |
 | Want to view project dashboard | `/manage-status` |
 </completion>
 

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

@@ -105,8 +105,8 @@ ls -la .workflow/.maestro/ 2>/dev/null | head -5  # 进行中的 session
 | 无 `.workflow/` + 有源码 | init | `maestro-init` |
 | 有 state.json，无 roadmap，无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
 | 有 macro analyze artifact，无 roadmap | roadmap | `maestro-roadmap` |
-| 有 roadmap，未启动 phase | analyze | `maestro-analyze {phase}` |
-| 最新 artifact = analyze | plan | `maestro-plan {phase}` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {milestone}` |
+| 最新 artifact = analyze | plan | `maestro-plan {milestone}` |
 | 最新 artifact = plan | execute | `maestro-execute {phase}` |
 | 最新 artifact = execute | review | `quality-review {phase}` |
 | review verdict=PASS | test-gen | `quality-auto-test {phase}` |

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
-description: Use when creating, revising, or verifying an execution plan for a phase or task
-argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
+description: Use when creating, revising, or verifying an execution plan for a milestone or task
+argument-hint: "[milestone] [--spec SPEC-xxx] [-y] [--gaps] [--tdd] [--dir <path>] [--from <source>] [--revise [instructions]] [--check <plan-dir>]"
 allowed-tools:
   - Read
   - Write
@@ -29,9 +29,9 @@ Produces plan.json + TASK files; registers PLN artifact in state.json.
 </deferred_reading>
 
 <context>
-$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+$ARGUMENTS — milestone number, or no args for current milestone, with optional flags.
 
-Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+Scope routing, base flags (`--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
 
 **Command-level flags** (extensions beyond workflow base):
 - `--from <source>`: Load upstream context directly (bypasses roadmap requirement):
@@ -46,8 +46,8 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 1. `--from analyze:ANL-xxx` → uses analyze conclusions.implementation_scope directly
 2. `--from blueprint:BLP-xxx` → uses blueprint requirements + architecture
 3. `--dir <path>` → explicit context directory (unchanged)
-4. Numeric arg → scope = "phase", resolve from roadmap (unchanged)
-5. No args + roadmap → scope = "milestone" (unchanged)
+4. Numeric arg → scope = "milestone", resolve from roadmap
+5. No args + roadmap → scope = "current_milestone"
 6. No args + no roadmap → search state.json for latest analyze artifact, fallback standalone
 
 **Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
@@ -69,6 +69,28 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### Plan Agent Model
+
+Plan automatically selects agent mode based on milestone scope:
+
+**Single agent mode** (default):
+- Milestone involves ≤3 modules
+- 1 workflow-planner agent, max 8 TASK JSON output
+- Directly produces plan.json
+
+**2+1 agent mode** (auto-triggered):
+- Milestone involves >3 modules
+- 2 parallel workflow-planner agents, each scoped to 2-3 modules
+- Each agent produces max 8 TASK JSON (total max 16)
+- +1 synthesis agent:
+  - Merges TASK JSON from both agents
+  - DAG analysis: dependency correctness, cycle detection, cross-module conflicts
+  - Terminology consistency check
+  - Wave ordering optimization
+  - Produces unified plan.json
+
+Module count is derived from milestone phase definitions and analyze upstream context.
+
 ### Phase Gates (MANDATORY, BLOCKING — Create mode only)
 
 **GATE P1 → P2: Context Collection → Clarification**
@@ -113,7 +135,7 @@ Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These
 
 ```
 === PLAN READY ===
-Phase: {phase_name}
+Milestone: {milestone_name}
 Tasks: {task_count} tasks in {wave_count} waves
 Check: {checker_status} (iteration {check_count}/{max_checks})
 Collision: {collision_status}
@@ -143,13 +165,13 @@ Status verdicts:
 |-----------|-----------|
 | Plan confirmed for execution | `/maestro-execute` |
 | Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
-| Re-plan with modifications | `/maestro-plan {phase}` |
+| Re-plan with modifications | `/maestro-plan {milestone}` |
 </completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide milestone number or topic, or create roadmap |
 | 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 |

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

@@ -43,13 +43,13 @@ Remaining      → intent (amend_mode 时为 change_request)
 </context>
 
 <invariants>
-1. **Ralph-v2 owns the full loop** — locate step → resolve args → load context → dispatch agent → wait for SendMessage → receive → extract signals → drift → complete，全部在本命令内完成
-2. **One agent per step** — 每个执行 step 派发一个 named executor agent，agent 通过 SendMessage 回传结果，主流程解析结果后决定下一步
-3. **Agent is a thin wrapper** — executor agent 调 `ralph next` 获取 skill prompt 并执行，通过 SendMessage 回传输出；arg resolution、context loading、signal extraction、drift analysis、ralph complete 均由主流程完成
-4. **Dual dispatch model** — 执行 Agent 与评估 Agent 使用不同派发模式：
-   - **执行 Agent**（A_STEP_DISPATCH）：`Agent({name: "exe-xxx"})` — named mailbox teammate，支持内部多 agent 编排，通过 `SendMessage({to: "main"})` 回传结果
-   - **评估 Agent**（A_AGENT_EVALUATE / A_AGENT_GOAL_AUDIT / A_AGENT_REGROUND）：`Agent()` 不传 `name` — 同步阻塞，直接返回结果（评估 agent 只读不需要多 agent）
-   - `agent_exec_name` 既用于 display/日志，也作为执行 Agent 的 `name` 参数
+1. **Ralph-v2 owns the full loop** — locate step → resolve args → load context → dispatch agent → wait for task-notification → extract signals → drift → complete，全部在本命令内完成
+2. **One agent per step** — 每个执行 step 派发一个 unnamed executor agent，结果通过 task-notification `<result>` 回传，主流程解析结果后决定下一步
+3. **Agent is a thin wrapper** — executor agent 调 `ralph next` 获取 skill prompt 并执行，返回输出文本；arg resolution、context loading、signal extraction、drift analysis、ralph complete 均由主流程完成
+4. **Unified unnamed dispatch** — 执行 Agent 和评估 Agent 均使用 unnamed Agent()，结果通过 task-notification `<result>` 回传：
+   - **执行 Agent**（A_STEP_DISPATCH）：`Agent()` 不传 name — executor 内部编排也用 unnamed Agent（子结果自动回流 executor，嵌套套娃模型）
+   - **评估 Agent**（A_AGENT_EVALUATE / A_AGENT_GOAL_AUDIT / A_AGENT_REGROUND）：同样 `Agent()` 不传 name
+   - `agent_exec_name` 仅用于 display/日志标识，不作为 Agent name 参数
 5. **主流程调 `ralph complete`** — 每个 step 完成后由主流程调 `maestro ralph complete`，非 agent 上报
 6. **Decision evaluation inline** — decision 节点不 handoff，通过 Agent 或 CLI delegate 在本循环内评估
 7. **CLI delegation for evaluation only** — CLI delegate（`maestro delegate --mode analysis`）仅限评估环节；执行仍通过 executor Agent 完成
@@ -89,8 +89,7 @@ S_CONFIRM       — 用户确认
 
 S_STEP_LOCATE     — 找下一个 pending step                    PERSIST: —
 S_STEP_RESOLVE    — 解析占位符 + 丰富参数                    PERSIST: step.args (enriched)
-S_STEP_DISPATCH   — 组装上下文 + 派发 named executor agent     PERSIST: step.agent_exec_name, step.status = "running"
-S_STEP_WAIT_MSG   — 等待 executor 的 SendMessage 回传          PERSIST: —
+S_STEP_DISPATCH   — 组装上下文 + 派发 unnamed executor agent    PERSIST: step.agent_exec_name, step.status = "running"
 S_STEP_ANALYZE    — 提取信号 + 组装 completion 参数            PERSIST: —
 S_STEP_DRIFT      — 产物 vs 目标偏离分析                      PERSIST: step.drift_score
 S_STEP_COMPLETE   — 调 `ralph complete` 上报                  PERSIST: step.completion_*
@@ -145,12 +144,8 @@ S_STEP_RESOLVE:
   → S_STEP_DISPATCH  DO: A_STEP_RESOLVE_ARGS
 
 S_STEP_DISPATCH:
-  → S_STEP_WAIT_MSG  WHEN: executor dispatched                  DO: A_STEP_DISPATCH
-
-S_STEP_WAIT_MSG:
-  → S_STEP_ANALYZE   WHEN: received agent-message with EXECUTOR_OUTPUT   DO: A_STEP_RECEIVE
-  → S_HANDLE_FAIL    WHEN: received agent-message with status=ERROR      DO: A_STEP_RECEIVE
-  → S_HANDLE_FAIL    WHEN: executor idle without SendMessage（崩溃检测）  DO: mark BLOCKED
+  → S_STEP_ANALYZE   WHEN: task-notification status=completed            DO: A_STEP_DISPATCH
+  → S_HANDLE_FAIL    WHEN: task-notification status=failed               DO: mark BLOCKED
 
 S_STEP_ANALYZE:
   → S_STEP_DRIFT     WHEN: STATUS == DONE|DONE_WITH_CONCERNS    DO: A_STEP_EXTRACT
@@ -330,17 +325,15 @@ Execution criteria: {session.execution_criteria joined by '; '}
    | debug | `dbg` |
    | Other | `run` |
 
-**4. Dispatch（named mailbox executor）:**
+**4. Dispatch（unnamed executor）:**
 
-> 执行 Agent 使用 `name` 参数派发为 named mailbox teammate，支持内部多 agent 编排。executor 通过 `SendMessage({to: "main"})` 回传执行结果。`resolved_agent_name` 同时用于 display 和 Agent `name` 参数。
+> 执行 Agent 不传 name，结果通过 task-notification `<result>` 自动回传主流程。executor 内部编排也用 unnamed Agent（子结果自动回流 executor，嵌套套娃模型）。
 
 ```
 Agent({
-  name: "{resolved_agent_name}",
   subagent_type: "ralph-executor",
-  description: "执行 step {index}: {step.skill}",
+  description: "执行 step {index}: {step.skill} [{resolved_agent_name}]",
   prompt: `Session: {session_id}
-Agent name: {resolved_agent_name}
 
 {goal_context 块，仅 protocol < 2 时}
 
@@ -349,24 +342,11 @@ Agent name: {resolved_agent_name}
 })
 ```
 
-5. Write `step.agent_exec_name` to status.json
+5. Write `step.agent_exec_name` to status.json（仅日志标识）
 6. Display: `[{index}/{total}] ⟶ {step.skill} → {resolved_agent_name}`
-7. Agent() 立即返回（named teammate 异步启动）→ 进入 S_STEP_WAIT_MSG 等待 executor 的 SendMessage
-
-### A_STEP_RECEIVE
-
-从 executor 的 `agent-message` 中提取执行输出。
-
-1. 接收到 `<agent-message from="{resolved_agent_name}">` 后，提取 message 内容
-2. 解析 `EXECUTOR_OUTPUT` 格式：
-   - `status: DONE` → agent_output = message 内容，继续 S_STEP_ANALYZE
-   - `status: DONE_WITH_CONCERNS` → agent_output = message 内容，继续 S_STEP_ANALYZE
-   - `status: ERROR` → STATUS=BLOCKED，转 S_HANDLE_FAIL
-3. idle_notification 处理（区分正常等待与崩溃）：
-   - 首次收到 `idle_notification`：executor 可能在等待 worker 回传，正常现象，继续等待
-   - 连续收到 2 次 `idle_notification` 且中间无 `agent-message`：向 executor 发送 `SendMessage({to: "{resolved_agent_name}", message: "请回报执行状态"})` 询问
-   - 询问后仍只收到 `idle_notification` 无 `agent-message`：STATUS=BLOCKED，转 S_HANDLE_FAIL
-4. `agent_output` = 提取的 message 内容
+7. Agent() 返回 agentId → 等待 task-notification（status=completed 时 `<result>` 含 executor 输出）
+8. task-notification 到达后，`agent_output` = `<result>` 内容 → 进入 S_STEP_ANALYZE
+9. task-notification status=failed → STATUS=BLOCKED，转 S_HANDLE_FAIL
 
 ### A_STEP_EXTRACT
 
@@ -749,10 +729,7 @@ GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 
 - **A_RETRY**: `Bash("maestro ralph retry {index}")` — CLI 设 `step.retried = true`, `step.status = "pending"`, 清 `active_step_index`
 - **A_PAUSE_SESSION**: `ralph complete N --status BLOCKED --reason "..."` — CLI 写 `session.status = "paused"`
-- **A_COMPLETE_SESSION**: 校验所有 step `completion_confirmed == true` + `task_decomposition_all_done == true`（若存在），通过后写 `session.status = "completed"`。完成后向所有 idle executor 发送 shutdown_request 清理：
-  ```
-  遍历 steps[].agent_exec_name → SendMessage({to: name, message: {type: "shutdown_request"}})
-  ```
+- **A_COMPLETE_SESSION**: 校验所有 step `completion_confirmed == true` + `task_decomposition_all_done == true`（若存在），通过后写 `session.status = "completed"`。unnamed executor 执行完自动终止，无需 shutdown 清理
 
 </actions>
 
@@ -884,24 +861,23 @@ E001–E006, W001–W004 适用。Agent 新增：
 
 ### Success Criteria
 
-- [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → wait → receive → extract → drift → complete → next
-- [ ] One agent per step — `Agent({ name, subagent_type: "ralph-executor" })` 每步派发一个 named executor
-- [ ] Executor 内调 `maestro ralph next` 获取 skill prompt 并执行，支持内部多 agent 编排
-- [ ] Executor 通过 `SendMessage({to: "main"})` 回传 `EXECUTOR_OUTPUT` 格式结果
+- [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → wait task-notification → extract → drift → complete → next
+- [ ] One agent per step — `Agent({ subagent_type: "ralph-executor" })` 每步派发一个 unnamed executor
+- [ ] Executor 内调 `maestro ralph next` 获取 skill prompt 并执行，内部编排用 unnamed Agent（子结果回流 executor）
+- [ ] Executor 结果通过 task-notification `<result>` 自动回传主流程
 - [ ] 主流程调 `maestro ralph complete` 上报（非 agent 上报）
 - [ ] 主流程负责 arg resolution、context loading、signal extraction、drift analysis
-- [ ] A_STEP_RECEIVE 从 executor 的 agent-message 中提取执行输出
-- [ ] Executor 崩溃（idle 无 SendMessage）→ 询问 2 次后 STATUS=BLOCKED，转 S_HANDLE_FAIL
-- [ ] Dual dispatch: 执行 Agent 传 `name`（async + SendMessage），评估 Agent 不传 `name`（sync）或 CLI delegate
+- [ ] task-notification status=failed → STATUS=BLOCKED，转 S_HANDLE_FAIL
+- [ ] Unified unnamed dispatch: 执行 Agent 和评估 Agent 均不传 name，结果通过 task-notification 回传。CLI delegate 仅限评估环节
 - [ ] Decision evaluation 支持三种模式：agent（同步）、cli（CLI delegate）、dual（并行交叉验证）
 - [ ] `evaluate_via` 字段控制评估模式，默认 `"agent"`
 - [ ] dual 模式合并策略：一致取共识、分歧保守降级、CLI 未返回用 Agent 结果
 - [ ] Verdict 解析保持 `---VERDICT---` 格式，parse 失败 → fallback fix + parse_failed: true
 - [ ] decisions.ndjson 追加：source 字段为 `"ralph-v2"`
-- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name`（执行 Agent name + display），含 `artifacts_produced`
+- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name`（display 标识），含 `artifacts_produced`
 - [ ] Chain building（S_RESOLVE_PHASE through S_BUILD_CHAIN）自包含执行
 - [ ] A_STEP_DISPATCH 含前序产出加载（滑动窗口 5 step + accumulated signals + stage-specific artifacts）
-- [ ] `agent_exec_name` 含 stage prefix（grl/brn/anm/ana/pln/exe/rev/tst/dbg）——同时用于 Agent name 参数和 display
+- [ ] `agent_exec_name` 含 stage prefix（grl/brn/anm/ana/pln/exe/rev/tst/dbg）——仅用于 display/日志标识
 - [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
 - [ ] CAVEATS 在 DONE_WITH_CONCERNS 时同时映射 --concerns
 - [ ] A_STEP_EXTRACT 从 executor 输出提取 artifact IDs、path signals、phase signals

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

@@ -15,7 +15,7 @@ allowed-tools:
 <purpose>
 Generate milestone/phase roadmap from requirements or upstream context. Three modes: create (default), revise (`--revise`), review (`--review`). For formal spec documents, use `/maestro-blueprint`.
 
-Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {phase} → plan → execute.
+Pipeline: brainstorm/blueprint/analyze → **roadmap** → analyze {milestone} → plan {milestone} → execute.
 </purpose>
 
 <required_reading>
@@ -60,7 +60,7 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
 **Interaction mode**: convergent menu-driven
 **Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
-**Scope guard**: only roadmap shape; do not pre-resolve intra-phase task breakdown (belongs to plan)
+**Scope guard**: only roadmap shape; do not pre-resolve task breakdown or phase decomposition (belongs to plan)
 **Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
 **Additional skip conditions**: --revise, --review (skip to respective mode)
 **Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section

package/.claude/commands/quality-auto-test.md

@@ -148,7 +148,7 @@ Append to state.json.artifacts[]:
 | E003 | error | No test framework detected | Install test framework or configure test runner |
 | W001 | warning | One or more test scenarios failed | Auto-iterate or suggest fix options |
 | W002 | warning | Max iterations reached without convergence | Review reflection-log.md, suggest debug |
-| W003 | warning | Degraded spec mode (no full spec package) | Consider running maestro-roadmap --mode full |
+| W003 | warning | Degraded spec mode (no full spec package) | Consider running /maestro-blueprint |
 </error_codes>
 
 <success_criteria>

package/.claude/skills/maestro-help/SKILL.md

@@ -292,6 +292,8 @@ Odyssey 长周期循环（独立路径）
 | 长周期改进 | Odyssey 深度循环 | `/odyssey-improve "改进目标"` |
 | 需求迭代 | Odyssey 深度循环 | `/odyssey-planex "需求描述"` |
 
+> 注：Path A/B 中 `analyze 1` / `plan 1` 的数字 `1` 指 **milestone 编号**（第 1 个里程碑），下游以 milestone 为入口。
+
 ## Core Rules
 
 1. **Catalog First**: 先查 catalog.json，再按需读 source 文件

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

@@ -9,8 +9,8 @@
     {"name": "maestro-init", "command": "/maestro-init", "category": "core", "description": "项目初始化 — 创建 .workflow/ 目录结构和状态文件", "source": "../../commands/maestro-init.md"},
     {"name": "maestro-brainstorm", "command": "/maestro-brainstorm", "category": "core", "description": "头脑风暴 — 发散探索，多角色创意，上游起源命令", "source": "../../commands/maestro-brainstorm.md"},
     {"name": "maestro-blueprint", "command": "/maestro-blueprint", "category": "core", "description": "正式规格文档化 — 7-phase 收敛规格链，上游起源命令，产出 .workflow/blueprint/", "source": "../../commands/maestro-blueprint.md"},
-    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — 消费上游 context，纯 Milestone > Phase 分解（不做技术探索）", "source": "../../commands/maestro-roadmap.md"},
-    {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过 Phase 管线直接完成，支持 --full/--discuss 模式", "source": "../../commands/maestro-quick.md"},
+    {"name": "maestro-roadmap", "command": "/maestro-roadmap", "category": "core", "description": "路线图编排 — Milestone > Phase 分解，下游以 milestone 为入口", "source": "../../commands/maestro-roadmap.md"},
+    {"name": "maestro-quick", "command": "/maestro-quick", "category": "core", "description": "快速任务 — 跳过管线直接完成，支持 --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"},
     {"name": "maestro-composer", "command": "/maestro-composer", "category": "core", "description": "编排器 — compose + play 工作流组合执行", "source": "../../commands/maestro-composer.md"},
@@ -27,7 +27,7 @@
     {"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-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查 Phase 完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
+    {"name": "maestro-milestone-audit", "command": "/maestro-milestone-audit", "category": "milestone", "description": "里程碑审计 — 检查里程碑完成度和质量", "source": "../../commands/maestro-milestone-audit.md"},
     {"name": "maestro-milestone-complete", "command": "/maestro-milestone-complete", "category": "milestone", "description": "里程碑完成 — 归档里程碑并推进下一个", "source": "../../commands/maestro-milestone-complete.md"},
     {"name": "maestro-milestone-release", "command": "/maestro-milestone-release", "category": "milestone", "description": "里程碑发布 — 生成发布说明和变更日志", "source": "../../commands/maestro-milestone-release.md"},
 
@@ -218,17 +218,17 @@
   ],
   "workflows": {
     "topology": {
-      "hierarchy": "Roadmap > Milestone > Phase > Task",
+      "hierarchy": "Roadmap > Milestone > Phase | Plan > Task > Wave",
       "layers": {
         "upstream_origin": ["brainstorm (发散/轻量)", "blueprint (收敛/重型)"],
-        "understanding": "analyze 双层: 宏观(文本参数) + 微观(数字参数)",
+        "understanding": "analyze 双层: 宏观(文本参数) + 微观(milestone 数字参数)",
         "orchestration": "roadmap (可选，消费上游 context)",
         "execution": ["plan", "execute"]
       }
     },
     "paths": {
-      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze 微观 → plan → execute",
-      "B_large_feature": "analyze 宏观 → roadmap → analyze 微观 → plan → execute",
+      "A_full_project": "brainstorm → blueprint(可选) → analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute",
+      "B_large_feature": "analyze 宏观 → roadmap → analyze {milestone} → plan {milestone} → execute",
       "C_medium_feature": "analyze 宏观 → plan --from analyze:ANL-xxx → execute",
       "D_small_fix": "plan → execute",
       "E_spec_only": "blueprint → (供人阅读)",

package/.codex/skills/maestro/SKILL.md

@@ -349,6 +349,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
    | Placeholder | Source |
    |-------------|--------|
    | `{phase}` | session.phase |
+   | `{milestone}` | session.milestone |
    | `{plan_dir}` | session.context.plan_dir |
    | `{analysis_dir}` | session.context.analysis_dir |
    | `{brainstorm_dir}` | session.context.brainstorm_dir |
@@ -358,7 +359,7 @@ Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechani
    | `{BLP}` | session.blueprint_id |
    | `{intent}` | session.intent |
 
-   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
+   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{milestone}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `Skill(skill_name, resolved_args)` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: mark step `status="done"`. **Structured completion**: `Bash("maestro ralph complete {idx} --status DONE --summary \"...\" [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`（`--summary` MUST，动词开头 ≤100 字）。**Barrier-context update** (when step is a context-producing skill):
@@ -424,9 +425,9 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `init` | `maestro-init` |
 | `blueprint` | `maestro-blueprint "{intent}"` |
 | `analyze_macro` | `maestro-analyze "{intent}"` |
-| `analyze` | `maestro-analyze {phase}` |
+| `analyze` | `maestro-analyze {milestone}` |
 | `ui_design` | `maestro-impeccable build "{phase}"` |
-| `plan` | `maestro-plan {phase}` |
+| `plan` | `maestro-plan {milestone}` |
 | `plan_from_analyze` | `maestro-plan --from analyze:{analyze_macro_id}` |
 | `plan_from_blueprint` | `maestro-plan --from blueprint:{blueprint_id}` |
 | `execute` | `maestro-execute {phase}` |
@@ -482,7 +483,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 | `quality-fix` | [B] maestro-analyze --gaps → [B] maestro-plan --gaps → [B] maestro-execute → quality-review |
 | `deploy` | quality-review → maestro-milestone-release |
 | `blueprint-driven` | maestro-init → [B] maestro-blueprint → [B] maestro-plan --from blueprint:{BLP} → [B] maestro-execute → quality-review → manage-harvest --auto |
-| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {phase} → [B] maestro-plan {phase}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
+| `analyze-macro-driven` | [B] maestro-analyze "{intent}" → ◆ post-analyze-scope → (large: [B] maestro-roadmap --from analyze:{ANL} → [B] maestro-analyze {milestone} → [B] maestro-plan {milestone}) / (medium\|small: [B] maestro-plan --from analyze:{ANL}) → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `grill-brainstorm` | [B] maestro-grill → [B] maestro-brainstorm --from grill:{GRL} → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto (**auto_mode: grill 透传 `-y`，Auto mode 代码代答**) |
 | `brainstorm-driven` | [B] maestro-brainstorm → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
 | `ui-craft-build` | maestro-impeccable build → [B] maestro-plan → [B] maestro-execute → quality-review → manage-harvest --auto |
@@ -542,7 +543,7 @@ S_DECISION_EVAL 入口；镜像 maestro-ralph `A_GOAL_AUDIT_EVALUATE`。Condense
 - [ ] Intent classified and chain resolved
 - [ ] Chain catalog 覆盖 blueprint / analyze_macro / plan_from_analyze / plan_from_blueprint / blueprint-driven / analyze-macro-driven 等新拓扑路径
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查；写入 step
-- [ ] plan step args 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
+- [ ] plan step args 支持 `{milestone}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径，`source_artifact_ref` 写入
 - [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
 - [ ] Goal registered via built-in `create_goal`; status.json decomposition fields additive-only
 - [ ] status.json 唯一真源；无 markdown 清单