maestro-flow 0.5.46 → 0.5.48

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

@@ -38,8 +38,18 @@ $ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for aut
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
+
+**Output boundary**: ALL file writes MUST target `.workflow/` (project.md, state.json, config.json, specs/) only. NEVER modify source code or files outside `.workflow/`.
 </context>
 
+<invariants>
+1. **Idempotent init** — re-running init on an already-initialized project MUST detect existing `.workflow/` and warn (E002); NEVER silently overwrite existing state
+2. **Scope guard** — init MUST only make initialization decisions; NEVER prejudge roadmap structure, plan scope, or implementation details
+3. **All artifacts required** — init MUST NOT report completion until project.md, state.json, and config.json all exist; missing artifacts MUST be created before exit
+4. **Template-driven** — deferred templates (project.md, state.json, config.json) MUST be read from `~/.maestro/templates/` and customized; NEVER generate from scratch without template
+5. **Interview writes back** — all interactive decisions MUST be written to project.md/config.json before proceeding to research or completion; NEVER leave decisions unrecorded
+</invariants>
+
 <interview_protocol>
 Follows @~/.maestro/workflows/interview-mechanics.md standard.
 
@@ -52,6 +62,24 @@ Follows @~/.maestro/workflows/interview-mechanics.md standard.
 </interview_protocol>
 
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Pre-flight → Interview**
+- REQUIRED: `.workflow/` existence check completed.
+- REQUIRED: `--from` source validated (if provided).
+- BLOCKED if: E002 (greenfield conflict with existing `.workflow/`) unresolved.
+
+**GATE 2: Interview → Research**
+- REQUIRED: All interview decisions recorded in project.md and config.json.
+- REQUIRED: `.workflow/` directory created with initial structure.
+- BLOCKED if: interview decisions not yet written to files.
+
+**GATE 3: Research → Completion**
+- REQUIRED: All 3 required artifacts exist (project.md, state.json, config.json).
+- REQUIRED: `.workflow/specs/` initialized.
+- BLOCKED if: any artifact missing — write it before reporting completion.
+
 ### Pre-flight
 
 1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
@@ -104,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-overlay.md

@@ -34,8 +34,19 @@ Turn natural-language instructions into command overlays — JSON patch files th
 **Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
 
 **Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/overlays/` (overlay JSON + docs) only. Command file patching is handled by `maestro overlay add` — this skill NEVER modifies `.claude/commands/*.md` directly.
 </context>
 
+<invariants>
+1. **Non-invasive** — overlays MUST use hashed HTML-comment markers for injection; NEVER edit command file content directly outside the overlay system
+2. **Idempotent** — re-running `maestro overlay apply` with the same overlay JSON MUST produce no file changes
+3. **Creation only** — this skill MUST only create overlays; listing and removal are handled by `maestro overlay list` (ink TUI)
+4. **Pristine source preferred** — injection point analysis MUST read from `$PKG_ROOT/.claude/commands/` (untouched originals) first, fall back to `~/.claude/commands/` only if pristine unavailable
+5. **User approval before write** — overlay JSON MUST be shown and approved via AskUserQuestion before writing to disk; NEVER auto-install without confirmation
+6. **Chain skip option mandatory** — if a skill chain is configured, the injected content MUST include a "Skip" option in AskUserQuestion; NEVER force the user into a chain
+</invariants>
+
 <execution>
 ### 1. Parse user intent
 

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-player.md

@@ -67,8 +67,19 @@ $ARGUMENTS — template slug/path, or flags.
   "last_checkpoint": null
 }
 ```
+
+**Output boundary**: ALL file writes MUST target `.workflow/.maestro/player-*/` (session status.json + step outputs) only. Template files (`~/.maestro/templates/workflows/`) are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
+<invariants>
+1. **Resume-safe** — status.json MUST be updated after every step change; an interrupted session MUST be resumable from the last checkpoint via `-c`
+2. **One step at a time** — execution loop MUST process steps sequentially in topological order; parallel steps share a batch index but NEVER run concurrently within the player
+3. **CLI nodes async** — cli-type nodes MUST use `Bash(run_in_background: true)` + STOP pattern; NEVER block the main thread on delegate execution
+4. **Templates read-only** — player MUST NOT modify template JSON files; runtime state belongs in status.json only
+5. **Failure requires user decision** — on step failure without explicit `on_fail`, player MUST prompt via AskUserQuestion (Retry/Skip/Abort); NEVER silently skip or auto-abort
+6. **Reference resolution at runtime** — `{N-xxx.field}` and `{prev_*}` references MUST be resolved at execution time from status.json step results, NEVER pre-resolved during init
+</invariants>
+
 <state_machine>
 
 <states>

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

@@ -39,9 +39,38 @@ Parse for:
    - Browse: `maestro search --category coding`
    - Load task-relevant entries: `maestro load --type knowhow --id <id1> [id2...]`
 3. All are optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/` (task directory, plan.json, summaries) and modified source files as defined in plan.json tasks. State.json scratch entry is implicit workflow tracking.
 </context>
 
+<invariants>
+1. **Atomic commits** — each task execution MUST produce a commit with only the files modified by that task; NEVER stage unrelated files
+2. **Evidence-based summaries** — task summaries MUST include concrete evidence (files changed, tests run, commands executed); NEVER accept "task completed successfully" as a summary
+3. **Plan before execute** — plan.json MUST be written before any task execution begins; NEVER skip planning even for single-task workflows
+4. **Scratch isolation** — all workflow artifacts MUST live under `.workflow/scratch/{task-dir}/`; NEVER write workflow metadata outside this directory
+5. **Commit confirmation** — staged files and commit message MUST be shown via AskUserQuestion before committing (unless `-y`); NEVER auto-commit without user awareness
+</invariants>
+
 <execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Planning**
+- REQUIRED: Task description parsed and scratch directory created.
+- REQUIRED: Coding specs loaded (optional but attempted).
+- BLOCKED if: no task description (E001) or scratch directory creation failed (E002).
+
+**GATE 2: Planning → Execution**
+- REQUIRED: plan.json written with task definitions.
+- REQUIRED: --discuss decisions extracted and recorded (if flag set).
+- BLOCKED if: plan.json missing or empty.
+
+**GATE 3: Execution → Completion**
+- REQUIRED: All tasks executed with `.summaries/TASK-*-summary.md` written per task.
+- REQUIRED: Each summary contains concrete evidence of completion.
+- REQUIRED: --full verification passed (if flag set).
+- BLOCKED if: any task summary missing or lacking evidence.
+
 Follow '~/.maestro/workflows/quick.md' completely.
 
 ### Artifact Verification (before completion)

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/maestro-swarm-workflow.md

@@ -43,6 +43,8 @@ Remaining        → intent
 | `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
 | `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
 | `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+
+**Output boundary**: ALL file writes MUST target `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/` (results, ralph-compatible artifacts). When inside a ralph session, writes target the corresponding step's scratch directory. NEVER modify source code, workflow scripts (`~/.maestro/workflows/swarm/`), or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -196,6 +198,29 @@ Workflow 返回 JSON 后：
 6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Route**
+- REQUIRED: Intent text or `--script` flag parsed successfully.
+- BLOCKED if: no intent and no `--script` (E001).
+
+**GATE 2: Route → Context Assembly**
+- REQUIRED: Target script resolved unambiguously (single match or user-selected from candidates).
+- BLOCKED if: ambiguous routing without user resolution (E002).
+
+**GATE 3: Context → Dispatch**
+- REQUIRED: Args payload assembled with all required fields for target script.
+- REQUIRED: Script file exists at `~/.maestro/workflows/swarm/{script}.js`.
+- BLOCKED if: script file not found (E003) or required args missing.
+
+**GATE 4: Dispatch → Ingest**
+- REQUIRED: Workflow execution completed (success or partial results available).
+- BLOCKED if: Workflow execution failed entirely (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 与 Ralph 集成

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

@@ -35,8 +35,37 @@ $ARGUMENTS — Tool name, keyword, or --category filter
 Empty arguments enters interactive mode: list all tools for user selection.
 </context>
 
+<invariants>
+1. **Confirmation before execution** — MUST AskUserQuestion before executing tool steps; NEVER auto-execute without user consent
+2. **Sequential step execution** — steps MUST be executed in defined order; NEVER skip or reorder steps unless user explicitly requests skip
+3. **Blocker escalation** — step failure MUST be reported to user with retry/skip/abort options; NEVER silently skip failed steps
+4. **Read-only tool definition** — tool execution MUST NOT modify the tool's knowhow document or spec entry; only the target codebase is modified per tool steps
+5. **Progress feedback** — each completed step MUST report `[Step N/M] done — <step_name>`; NEVER execute silently
+6. **Output boundary** — file writes are governed by the individual tool's step definitions. This command itself writes NO files beyond what the loaded tool prescribes
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load**
+- REQUIRED: Tool name, keyword, or --category parsed from arguments (or empty for interactive mode).
+- BLOCKED if: invalid category value.
+
+**GATE 2: Load → Confirm**
+- REQUIRED: Exactly one tool resolved (direct match or user selection from candidates).
+- REQUIRED: Tool document loaded and steps extracted (ref entries expanded via `maestro load --type knowhow`).
+- BLOCKED if: E001 (no match found), E002 unresolved (multiple matches without user selection).
+
+**GATE 3: Confirm → Execute**
+- REQUIRED: User confirmed execution mode via AskUserQuestion (execute as-is / adjust / view only).
+- BLOCKED if: user selects "View only" — display steps and END without execution.
+
+**GATE 4: Execute → Report**
+- REQUIRED: All steps attempted (completed, skipped with user approval, or aborted by user).
+- REQUIRED: Results collected for each step (success/skip/fail).
+- BLOCKED if: user chose abort mid-execution — report partial results and END.
+
 ### Step 1: Load Tool
 
 **By name**:

package/.claude/commands/maestro-tools-register.md

@@ -35,8 +35,37 @@ $ARGUMENTS — Intent description
 ```
 </context>
 
+<invariants>
+1. **Schema validation** — tool knowhow document MUST include `tool: true`, `category`, `keywords`, and `summary` in YAML frontmatter; missing fields → reject write
+2. **No duplicate names** — tool title MUST be unique within its category; duplicate detection → E002 warning with overwrite/optimize confirmation
+3. **Category required** — every tool MUST declare exactly one category from: coding, test, review, arch, debug; empty category → E003
+4. **Confirmation gate** — MUST AskUserQuestion before writing knowhow document and spec ref entry; NEVER persist without user confirmation
+5. **Promote is in-place** — promote mode MUST update existing knowhow frontmatter via `maestro wiki update`; NEVER recreate the document
+6. **Output boundary** — ALL file writes MUST target .workflow/knowhow/ (tool documents) and .workflow/specs/ (ref entries via maestro spec add) only. NEVER modify source code or files outside these paths
+7. **Description format** — first line after `### Title` MUST state "Use when ..." (usage timing); this is critical for ref entry summary visibility in spec-load
+</invariants>
+
 <execution>
 
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Gather**
+- REQUIRED: Mode determined (extract/generate/optimize/promote) from argument parsing.
+- REQUIRED: For optimize/promote modes, target tool/document exists and is loadable.
+- BLOCKED if: empty args without user response to AskUserQuestion.
+
+**GATE 2: Gather → Write**
+- REQUIRED: Tool name, category, and usage timing confirmed.
+- REQUIRED: Steps extracted or generated (extract: ≥1 step, generate: user-confirmed scope).
+- REQUIRED: Inline vs ref mode decided based on step count.
+- REQUIRED: User confirmed via AskUserQuestion (title, category, keywords, summary, step count).
+- BLOCKED if: E001 (.workflow/specs/ not initialized), E003 (no category), user cancels.
+
+**GATE 3: Write → Verify**
+- REQUIRED: Knowhow document written with `tool: true` frontmatter (or updated in-place for promote).
+- REQUIRED: Spec ref entry registered (if user confirmed).
+- BLOCKED if: write failed or spec add returned error.
+
 ### Step 1: Intent Detection
 
 Parse $ARGUMENTS to determine mode:

package/.claude/commands/maestro-ui-codify.md

@@ -33,8 +33,19 @@ Flags:
 - `--package-name <name>`: Package name for reference output (default: auto-generated from source directory)
 - `--output-dir <path>`: Output directory for reference package (default: `.workflow/reference_style`)
 - `--overwrite`: Allow overwriting existing package directory
+
+**Output boundary**: ALL file writes MUST target the `--output-dir` path (default: `.workflow/reference_style/`) for reference packages, and `.workflow/knowhow/` for knowledge assets (via `codify-to-knowhow`). NEVER modify the source directory being analyzed.
 </context>
 
+<invariants>
+1. **Source read-only** — the source path being analyzed MUST NOT be modified; extraction is purely read-only
+2. **Phase-sequential loading** — workflow files (ui-codify-extract, ui-codify-package, ui-codify-knowhow) MUST be read only when their phase starts; NEVER load all phases eagerly
+3. **User confirmation before knowhow** — Phase 3→4 gate MUST present AskUserQuestion before generating knowledge assets; NEVER auto-proceed to knowhow generation
+4. **Overwrite protection** — existing package directory MUST NOT be overwritten without `--overwrite` flag (E003)
+5. **Artifact completeness** — all 5 required artifacts MUST exist before reporting completion; NEVER skip artifact verification
+6. **Token-first extraction** — design-tokens.json MUST be generated before layout-templates.json; layout extraction depends on token foundation
+</invariants>
+
 <execution>
 ## 1. Load UI Specs
 

package/.claude/commands/maestro-universal-workflow.md

@@ -33,6 +33,8 @@ Remaining         → intent
 **Library locations:**
 - Fixed scripts: `~/.maestro/workflows/swarm/wf-*.js`
 - Dynamic scripts: `~/.maestro/workflows/dynamic/uwf-*.js`
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/workflows/dynamic/` (generated scripts) and `.workflow/scratch/{YYYYMMDD}-uwf-*/` (execution results). Fixed scripts at `~/.maestro/workflows/swarm/` are read-only. NEVER modify source code or `.claude/commands/` files.
 </context>
 
 <state_machine>
@@ -509,6 +511,36 @@ Findings: ${digest}
 12. **无反斜杠路径** — 字符串中路径用正斜杠（`\u`、`\a` 等会被解析为转义序列）
 </invariants>
 
+<execution>
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Scan**
+- REQUIRED: Intent text or `--from`/`--resume` flag parsed.
+- BLOCKED if: no intent and no flags (E001).
+
+**GATE 2: Scan → Design/Execute**
+- REQUIRED: Library scan completed (both `swarm/` and `dynamic/` directories).
+- REQUIRED: User decision if matches found (reuse existing vs generate new).
+- BLOCKED if: scan fails to read script directories.
+
+**GATE 3: Design → Generate**
+- REQUIRED: Task decomposition completed with work_items, decision_points, data_flow.
+- REQUIRED: Phase orchestration and adversarial pattern selection determined by depth.
+- BLOCKED if: task cannot be decomposed (E002).
+
+**GATE 4: Generate → Execute**
+- REQUIRED: Script written to `~/.maestro/workflows/dynamic/uwf-{slug}.js`.
+- REQUIRED: `node --check` syntax validation passed.
+- REQUIRED: User confirmation via AskUserQuestion (unless resuming).
+- BLOCKED if: syntax validation fails after 2 retries (E003).
+
+**GATE 5: Execute → Persist**
+- REQUIRED: Workflow execution completed via `scriptPath` invocation.
+- BLOCKED if: Workflow execution failed (E004) — offer `--resume`.
+
+</execution>
+
 <appendix>
 
 ### 使用示例
@@ -569,3 +601,30 @@ universal-workflow 扫描时会同时检查 swarm/ 和 dynamic/ 目录，
 | E005 | 持久化失败 | 展示脚本内容，让用户手动保存 |
 
 </appendix>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent and no --from/--resume flag | Prompt user for intent text |
+| E002 | error | Task decomposition failed — cannot identify work_items | Require more specific intent description |
+| E003 | error | Generated script syntax error after 2 retries | Show script content + error for manual fix |
+| E004 | error | Workflow execution failed | Show error, offer --resume with runId |
+| E005 | error | Script persistence failed (filesystem write error) | Show script content for manual save |
+| W001 | warning | No matching scripts found in library scan | Proceed directly to S_DESIGN |
+| W002 | warning | Adversarial gate confidence < 50% | Flag low-confidence decision, suggest --depth deep |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and flags extracted (--name, --depth, --dry-run, --from, --resume)
+- [ ] Library scan completed across both swarm/ and dynamic/ directories
+- [ ] User decision captured if matching scripts found (reuse vs generate)
+- [ ] Task decomposition produced: work_items, decision_points, data_flow
+- [ ] Adversarial pattern selected per decision_point according to depth level
+- [ ] Blueprint presented to user with estimated agent count
+- [ ] Script generated as pure JavaScript with all 12 generation rules enforced
+- [ ] `node --check` syntax validation passed
+- [ ] User confirmation obtained before execution (unless --resume)
+- [ ] Workflow executed via scriptPath (not inline script string)
+- [ ] Script persisted to `~/.maestro/workflows/dynamic/uwf-{slug}.js`
+- [ ] Completion summary displayed with reuse/resume commands
+</success_criteria>