maestro-flow 0.5.2 → 0.5.31

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

@@ -1,247 +1,247 @@
----
-name: maestro-ralph-execute
-description: Execute next pending step in ralph session
-argument-hint: "[-y] [session-id]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Skill
----
-<purpose>
-Single-step executor for ralph (adaptive) and maestro (static) sessions.
-Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
-
-Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
-Session: `.workflow/.maestro/*/status.json`
-</purpose>
-
-<context>
-$ARGUMENTS — optional `-y` flag + optional session ID.
-
-**Parse:**
-```
--y / --yes → auto = true
-Remaining  → session_id (if matches maestro-* or ralph-*)
-```
-Also read `session.auto_mode` from status.json — if true, treat as `-y`.
-
-**Step kinds:**
-
-| Kind | Identifier | Execution | Flow after |
-|------|-----------|-----------|------------|
-| decision step | `step.decision` 非空 | `Skill("maestro-ralph")` | Execution ends here |
-| 执行 step | `step.decision == null` | `Bash("maestro ralph next")` → 内联按其 stdout 执行 → `Bash("maestro ralph complete N --status ...")` | Self-invoke next |
-
-HARD RULES:
-- 执行 step：**统一通过 `maestro ralph next` CLI 加载**。CLI 负责读 command_path、解析 `<required_reading>` + `<deferred_reading>`、拼接 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`。不要再在会话里手动 Read + 解析 required_reading
-- decision step：A_EXEC_DECISION 通过 `Skill({ skill: "maestro-ralph" })` handoff 给 ralph 评估（不走 CLI）
-- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（缺失 → ralph next 返回 E006/E007 并拒绝执行）
-- 每个 step 结束必须调用 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`。STATUS 仅 4 个合法值：`DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`（**`NEEDS_CONTEXT` 已废除**，context 容量由 harness 自动压缩处理）
-</context>
-
-<invariants>
-1. **执行 = `ralph next` + inline + `ralph complete`** — 调 `maestro ralph next` 拿到 skill 内容，按 stdout 内联执行
-2. **Required reading 由 CLI 负责** — `ralph next` 自动展开 + 加载 `<required_reading>` 引用的所有文件，缺失 → 退出码 1（E007），不写 active_step_index，不进入执行
-3. **Deferred reading recorded only** — `<deferred_reading>` 路径由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
-4. **一致性取代锁** — 同一 session 同时最多一个 step 持 `active_step_index`；CLI 校验失败直接退出码 3，不静默推进
-5. **Completion 通过 CLI 调用** — 每个 step 末尾调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`，由 CLI 写 `completion_*` + 清 `active_step_index`
-6. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
-8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
-9. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 包含完整 skill prompt，必须全量捕获。**严禁** `| head`、`| tail`、`2>&1 | head -N` 等任何截断管道。Bash timeout 可加长但不可截断输出
-</invariants>
-
-<state_machine>
-
-<states>
-S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
-S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
-S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
-S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
-S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
-S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
-S_FALLBACK      — 无 session 可执行                      PERSIST: —
-</states>
-
-<transitions>
-
-S_LOCATE:
-  → S_RESOLVE_ARGS  WHEN: pending step found                DO: A_LOCATE_SESSION
-  → S_COMPLETE      WHEN: no pending steps
-  → S_FALLBACK      WHEN: no running session
-
-S_RESOLVE_ARGS:
-  → S_EXECUTE       DO: A_RESOLVE_ARGS
-
-S_EXECUTE:
-  → END             WHEN: step.decision != null              DO: A_EXEC_DECISION
-  → S_POST_EXEC     WHEN: step.decision == null + ralph complete invoked with DONE|DONE_WITH_CONCERNS  DO: A_EXEC_STEP
-  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit≠0 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
-
-S_POST_EXEC:
-  → S_LOCATE        DO: Bash("maestro ralph complete ...") + Skill("maestro-ralph-execute")
-                     NOTE: CLI 已写完 completion_*, status, active_step_index；无需额外写盘
-
-S_HANDLE_FAIL:
-  → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
-  → END             WHEN: auto + retried                    DO: A_PAUSE_SESSION
-  → S_LOCATE        WHEN: interactive + user selects retry  DO: A_RETRY
-  → S_LOCATE        WHEN: interactive + user selects skip   DO: A_SKIP_STEP
-  → END             WHEN: interactive + user selects abort  DO: A_PAUSE_SESSION
-
-S_COMPLETE:
-  → END             DO: A_COMPLETE_SESSION
-
-S_FALLBACK:
-  → END             DO: display "无运行中的会话。使用 /maestro 或 /maestro-ralph 创建。"
-
-</transitions>
-
-<actions>
-
-### A_LOCATE_SESSION
-
-1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
-2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
-3. Extract: session_id, source, steps[], phase, milestone, intent, auto_mode, context, cli_tool, active_step_index
-4. **不在此处选 pending step**——pending 选择由 `maestro ralph next` CLI 内部完成；A_LOCATE_SESSION 只确认 session 存在且 running，由 A_EXEC_STEP 调 CLI 推进
-
-### A_RESOLVE_ARGS
-
-**Placeholder substitution:**
-
-| Placeholder | Source |
-|-------------|--------|
-| `{phase}` | session.phase |
-| `{milestone}` | session.milestone |
-| `{intent}` | session.intent |
-| `{description}` | session.intent (alias) |
-| `{scratch_dir}` | session.context.scratch_dir or latest artifact path |
-| `{plan_dir}` | session.context.plan_dir |
-| `{analysis_dir}` | session.context.analysis_dir |
-| `{issue_id}` | session.context.issue_id |
-| `{milestone_num}` | session.context.milestone_num |
-
-**Per-skill enrichment** (when args empty or minimal):
-
-| Skill | Required context | Source |
-|-------|-----------------|--------|
-| maestro-brainstorm | topic | `"{intent}"` |
-| maestro-roadmap | description | `"{intent}"` |
-| maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| quality-debug | gap context | Read previous step's error/gap |
-| quality-* | phase | `{phase}` |
-
-**Artifact dir resolution for --dir:**
-```
-Read state.json → filter artifacts by milestone + phase
-plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
-execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
-```
-
-Write enriched args back to status.json.
-
-### A_EXEC_DECISION
-
-1. Mark step running, write status.json
-2. Display: `[{index}/{total}] ◆ {step.decision} Retry: {retry}/{max}`
-3. `Skill({ skill: "maestro-ralph" })` — ralph 评估 + handoff
-4. 执行在此结束
-
-### A_EXEC_STEP
-
-1. **Load** — `Bash("maestro ralph next --session <session_id>")` — **必须全量捕获 stdout，严禁 `| head`/`| tail` 等截断管道**（stdout 含完整 skill prompt，截断会导致执行内容不完整）
-   - 退出码 0 → 按 stdout 内联执行
-   - 退出码 2 → 交给 S_LOCATE
-   - 退出码 3 → active_step_index 已被占用
-   - 退出码 1 → pause session
-2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-3. **Complete**:
-   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
-   - `Bash("maestro ralph retry N")`
-   - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
-4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
-
-完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
-
-### A_RETRY
-
-1. `Bash("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`
-2. Display: `[{index}/{total}] ↻ {step.skill} retry`
-
-### A_SKIP_STEP
-
-跳过执行 step — 手动编辑 `status.json`：将该 step `status` 设为 `"skipped"`，`completion_confirmed` 设为 `false`，并清 `active_step_index`（若指向此 step）。
-（不提供 CLI 子命令；跳过是非常规操作，避免自动化误用。）
-
-### A_PAUSE_SESSION
-
-通常由 `ralph complete N --status BLOCKED --reason "..."` 触发，CLI 已写 `session.status = "paused"`。手动 pause 场景下直接编辑 status.json。
-Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
-
-### A_COMPLETE_SESSION
-
-1. 校验：所有 step `completion_confirmed == true`（除 skipped）；task_decomposition 存在时校验 `task_decomposition_all_done == true`
-2. 任一校验失败 → 不标 completed，回 S_LOCATE 或 pause
-3. `session.status = "completed"`, write status.json
-4. Display completion report:
-   ```
-   ============================================================
-     SESSION COMPLETE
-   ============================================================
-     Session:  {session_id} [{source}]
-     Steps:    {completed}/{total}   confirmed: {confirmed}/{completed}
-
-     [✓] 0.   maestro-plan 1            [global]
-     [✓] 1.   maestro-execute 1         [project]
-     [✓] 2. ◆ post-execute               [decision]
-     ...
-   ============================================================
-   ```
-   Icons: `✓` confirmed, `—` skipped, `✗` failed, `◆` decision
-
-</actions>
-
-</state_machine>
-
-<appendix>
-
-### Error Codes
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
-| E006 | error | command_path missing/unreachable for 执行 step | `ralph next` 拒绝；编辑 status.json 或重 build |
-| E007 | error | required_reading 引用文件缺失 | `ralph next` 拒绝；CLI stderr 列出缺失路径 |
-| E008 | error | `ralph complete` idx ≠ active_step_index | 编辑 status.json 修正一致性 |
-| E009 | error | `ralph complete` step.status ≠ running | 重复 complete 或非法跳跃；编辑 status.json |
-| E010 | error | status.json schema 损坏 | `ralph check` 显示具体损坏字段 |
-| W001 | warning | Step completed with concerns | Log and continue |
-| W005 | warning | active_step_index 指向已 completed step | `ralph next` 自动清理后继续 |
-| W007 | warning | step.skill ≠ command .md frontmatter.name | 提示但不阻塞 |
-
-### Success Criteria
-
-- [ ] Session discovery covers maestro-* and ralph-*
-- [ ] `-y` parsed from args 或 session.auto_mode；auto=true 时透传 `-y` 到 skill args
-- [ ] Placeholders resolved；per-skill enrichment 正确
-- [ ] Decision 节点（`step.decision != null`）走 Skill("maestro-ralph") handoff（**不调 ralph next CLI**）
-- [ ] 执行 step 通过 `Bash("maestro ralph next")` 加载；CLI 返回拼好的 prompt + completion 协议
-- [ ] required_reading 由 CLI 自动加载并拼入 prompt；缺失 → CLI 退出码 1，pause session
-- [ ] `<deferred_reading>` 由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
-- [ ] 每个 step 末尾必须调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`
-- [ ] STATUS 枚举仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；CLI 拒绝 `NEEDS_CONTEXT`
-- [ ] active_step_index 一致性由 CLI 维护；E008/E009 直接退出，不静默推进
-- [ ] step.completion_evidence 通过 `--evidence` 传入并记录
-- [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
-- [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
-- [ ] 自调用持续到全部 completion_confirmed 或 paused
-
-</appendix>
+---
+name: maestro-ralph-execute
+description: Execute next pending step in ralph session
+argument-hint: "[-y] [session-id]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+---
+<purpose>
+Single-step executor for ralph (adaptive) and maestro (static) sessions.
+Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
+
+Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
+Session: `.workflow/.maestro/*/status.json`
+</purpose>
+
+<context>
+$ARGUMENTS — optional `-y` flag + optional session ID.
+
+**Parse:**
+```
+-y / --yes → auto = true
+Remaining  → session_id (if matches maestro-* or ralph-*)
+```
+Also read `session.auto_mode` from status.json — if true, treat as `-y`.
+
+**Step kinds:**
+
+| Kind | Identifier | Execution | Flow after |
+|------|-----------|-----------|------------|
+| decision step | `step.decision` 非空 | `Skill("maestro-ralph")` | Execution ends here |
+| 执行 step | `step.decision == null` | `Bash("maestro ralph next")` → 内联按其 stdout 执行 → `Bash("maestro ralph complete N --status ...")` | Self-invoke next |
+
+HARD RULES:
+- 执行 step：**统一通过 `maestro ralph next` CLI 加载**。CLI 负责读 command_path、解析 `<required_reading>` + `<deferred_reading>`、拼接 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`。不要再在会话里手动 Read + 解析 required_reading
+- decision step：A_EXEC_DECISION 通过 `Skill({ skill: "maestro-ralph" })` handoff 给 ralph 评估（不走 CLI）
+- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（缺失 → ralph next 返回 E006/E007 并拒绝执行）
+- 每个 step 结束必须调用 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`。STATUS 仅 4 个合法值：`DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`（**`NEEDS_CONTEXT` 已废除**，context 容量由 harness 自动压缩处理）
+</context>
+
+<invariants>
+1. **执行 = `ralph next` + inline + `ralph complete`** — 调 `maestro ralph next` 拿到 skill 内容，按 stdout 内联执行
+2. **Required reading 由 CLI 负责** — `ralph next` 自动展开 + 加载 `<required_reading>` 引用的所有文件，缺失 → 退出码 1（E007），不写 active_step_index，不进入执行
+3. **Deferred reading recorded only** — `<deferred_reading>` 路径由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
+4. **一致性取代锁** — 同一 session 同时最多一个 step 持 `active_step_index`；CLI 校验失败直接退出码 3，不静默推进
+5. **Completion 通过 CLI 调用** — 每个 step 末尾调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`，由 CLI 写 `completion_*` + 清 `active_step_index`
+6. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
+8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
+9. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 包含完整 skill prompt，必须全量捕获。**严禁** `| head`、`| tail`、`2>&1 | head -N` 等任何截断管道。Bash timeout 可加长但不可截断输出
+</invariants>
+
+<state_machine>
+
+<states>
+S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
+S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
+S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
+S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
+S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
+S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
+S_FALLBACK      — 无 session 可执行                      PERSIST: —
+</states>
+
+<transitions>
+
+S_LOCATE:
+  → S_RESOLVE_ARGS  WHEN: pending step found                DO: A_LOCATE_SESSION
+  → S_COMPLETE      WHEN: no pending steps
+  → S_FALLBACK      WHEN: no running session
+
+S_RESOLVE_ARGS:
+  → S_EXECUTE       DO: A_RESOLVE_ARGS
+
+S_EXECUTE:
+  → END             WHEN: step.decision != null              DO: A_EXEC_DECISION
+  → S_POST_EXEC     WHEN: step.decision == null + ralph complete invoked with DONE|DONE_WITH_CONCERNS  DO: A_EXEC_STEP
+  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit≠0 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
+
+S_POST_EXEC:
+  → S_LOCATE        DO: Bash("maestro ralph complete ...") + Skill("maestro-ralph-execute")
+                     NOTE: CLI 已写完 completion_*, status, active_step_index；无需额外写盘
+
+S_HANDLE_FAIL:
+  → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
+  → END             WHEN: auto + retried                    DO: A_PAUSE_SESSION
+  → S_LOCATE        WHEN: interactive + user selects retry  DO: A_RETRY
+  → S_LOCATE        WHEN: interactive + user selects skip   DO: A_SKIP_STEP
+  → END             WHEN: interactive + user selects abort  DO: A_PAUSE_SESSION
+
+S_COMPLETE:
+  → END             DO: A_COMPLETE_SESSION
+
+S_FALLBACK:
+  → END             DO: display "无运行中的会话。使用 /maestro 或 /maestro-ralph 创建。"
+
+</transitions>
+
+<actions>
+
+### A_LOCATE_SESSION
+
+1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
+2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
+3. Extract: session_id, source, steps[], phase, milestone, intent, auto_mode, context, cli_tool, active_step_index
+4. **不在此处选 pending step**——pending 选择由 `maestro ralph next` CLI 内部完成；A_LOCATE_SESSION 只确认 session 存在且 running，由 A_EXEC_STEP 调 CLI 推进
+
+### A_RESOLVE_ARGS
+
+**Placeholder substitution:**
+
+| Placeholder | Source |
+|-------------|--------|
+| `{phase}` | session.phase |
+| `{milestone}` | session.milestone |
+| `{intent}` | session.intent |
+| `{description}` | session.intent (alias) |
+| `{scratch_dir}` | session.context.scratch_dir or latest artifact path |
+| `{plan_dir}` | session.context.plan_dir |
+| `{analysis_dir}` | session.context.analysis_dir |
+| `{issue_id}` | session.context.issue_id |
+| `{milestone_num}` | session.context.milestone_num |
+
+**Per-skill enrichment** (when args empty or minimal):
+
+| Skill | Required context | Source |
+|-------|-----------------|--------|
+| maestro-brainstorm | topic | `"{intent}"` |
+| maestro-roadmap | description | `"{intent}"` |
+| maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
+| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| quality-debug | gap context | Read previous step's error/gap |
+| quality-* | phase | `{phase}` |
+
+**Artifact dir resolution for --dir:**
+```
+Read state.json → filter artifacts by milestone + phase
+plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
+execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+```
+
+Write enriched args back to status.json.
+
+### A_EXEC_DECISION
+
+1. Mark step running, write status.json
+2. Display: `[{index}/{total}] ◆ {step.decision} Retry: {retry}/{max}`
+3. `Skill({ skill: "maestro-ralph" })` — ralph 评估 + handoff
+4. 执行在此结束
+
+### A_EXEC_STEP
+
+1. **Load** — `Bash("maestro ralph next --session <session_id>")` — **必须全量捕获 stdout，严禁 `| head`/`| tail` 等截断管道**（stdout 含完整 skill prompt，截断会导致执行内容不完整）
+   - 退出码 0 → 按 stdout 内联执行
+   - 退出码 2 → 交给 S_LOCATE
+   - 退出码 3 → active_step_index 已被占用
+   - 退出码 1 → pause session
+2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
+3. **Complete**:
+   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
+   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `Bash("maestro ralph retry N")`
+   - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+
+完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
+
+### A_RETRY
+
+1. `Bash("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`
+2. Display: `[{index}/{total}] ↻ {step.skill} retry`
+
+### A_SKIP_STEP
+
+跳过执行 step — 手动编辑 `status.json`：将该 step `status` 设为 `"skipped"`，`completion_confirmed` 设为 `false`，并清 `active_step_index`（若指向此 step）。
+（不提供 CLI 子命令；跳过是非常规操作，避免自动化误用。）
+
+### A_PAUSE_SESSION
+
+通常由 `ralph complete N --status BLOCKED --reason "..."` 触发，CLI 已写 `session.status = "paused"`。手动 pause 场景下直接编辑 status.json。
+Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+
+### A_COMPLETE_SESSION
+
+1. 校验：所有 step `completion_confirmed == true`（除 skipped）；task_decomposition 存在时校验 `task_decomposition_all_done == true`
+2. 任一校验失败 → 不标 completed，回 S_LOCATE 或 pause
+3. `session.status = "completed"`, write status.json
+4. Display completion report:
+   ```
+   ============================================================
+     SESSION COMPLETE
+   ============================================================
+     Session:  {session_id} [{source}]
+     Steps:    {completed}/{total}   confirmed: {confirmed}/{completed}
+
+     [✓] 0.   maestro-plan 1            [global]
+     [✓] 1.   maestro-execute 1         [project]
+     [✓] 2. ◆ post-execute               [decision]
+     ...
+   ============================================================
+   ```
+   Icons: `✓` confirmed, `—` skipped, `✗` failed, `◆` decision
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Error Codes
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
+| E006 | error | command_path missing/unreachable for 执行 step | `ralph next` 拒绝；编辑 status.json 或重 build |
+| E007 | error | required_reading 引用文件缺失 | `ralph next` 拒绝；CLI stderr 列出缺失路径 |
+| E008 | error | `ralph complete` idx ≠ active_step_index | 编辑 status.json 修正一致性 |
+| E009 | error | `ralph complete` step.status ≠ running | 重复 complete 或非法跳跃；编辑 status.json |
+| E010 | error | status.json schema 损坏 | `ralph check` 显示具体损坏字段 |
+| W001 | warning | Step completed with concerns | Log and continue |
+| W005 | warning | active_step_index 指向已 completed step | `ralph next` 自动清理后继续 |
+| W007 | warning | step.skill ≠ command .md frontmatter.name | 提示但不阻塞 |
+
+### Success Criteria
+
+- [ ] Session discovery covers maestro-* and ralph-*
+- [ ] `-y` parsed from args 或 session.auto_mode；auto=true 时透传 `-y` 到 skill args
+- [ ] Placeholders resolved；per-skill enrichment 正确
+- [ ] Decision 节点（`step.decision != null`）走 Skill("maestro-ralph") handoff（**不调 ralph next CLI**）
+- [ ] 执行 step 通过 `Bash("maestro ralph next")` 加载；CLI 返回拼好的 prompt + completion 协议
+- [ ] required_reading 由 CLI 自动加载并拼入 prompt；缺失 → CLI 退出码 1，pause session
+- [ ] `<deferred_reading>` 由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
+- [ ] 每个 step 末尾必须调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`
+- [ ] STATUS 枚举仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；CLI 拒绝 `NEEDS_CONTEXT`
+- [ ] active_step_index 一致性由 CLI 维护；E008/E009 直接退出，不静默推进
+- [ ] step.completion_evidence 通过 `--evidence` 传入并记录
+- [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
+- [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
+- [ ] 自调用持续到全部 completion_confirmed 或 paused
+
+</appendix>

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

@@ -13,42 +13,8 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Closed-loop decision engine for the maestro workflow lifecycle.
-Reads project state → infers position → builds adaptive chain → delegates execution.
-
-Entry points:
-- **`/maestro-ralph "intent"`** — New session: infer → decompose → build → emit /goal prompt（如有 decomposition）→ dispatch ralph-execute
-- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
-- **`/maestro-ralph status`** — Display session progress
-
-> 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `Skill("maestro-ralph")` handoff，无需用户手动切换。
-
-Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
-
-Step kinds:
-- **执行 step**: ralph-execute 调 `Bash("maestro ralph next")` 加载 command .md + required_reading 全文，按 stdout 内联执行
-- **decision step**: `step.decision` 字段非空；回 ralph 评估（CLI 只读分析）
-
-Key difference from maestro coordinator:
-- maestro: static chain → one-time selection → runs all steps
-- ralph: living chain → decision nodes re-evaluate → chain grows/shrinks dynamically
-
-Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`
-Mutual invocation with `/maestro-ralph-execute` forms a self-perpetuating work loop.
-
-### Execution Flow
-
-```
- /maestro-ralph "intent" ─▶ ralph        infer → decompose → build chain
-                              │           resolves command_path per step
-                              │           writes status.json
-                              │           emits /goal prompt
-                              ▼
-                       ralph-execute  ◀─┐ 执行 step → `maestro ralph next` + inline + `ralph complete`
-                              │         │ decision step → Skill("maestro-ralph")
-                              └─────────┘ CLI writes step.completion_confirmed
-                       loop until all completion_confirmed | paused
-```
+Closed-loop decision engine: read project state → infer position → build adaptive chain → delegate execution.
+Ralph builds/evaluates; ralph-execute runs steps. Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`.
 </purpose>
 
 <context>
@@ -269,8 +235,7 @@ resolve_milestone(phase_number):
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
-| phase 已存在 + 最新 artifact = execute | `verify` |
-| phase 已存在 + 最新 artifact = verify | → refine from result files |
+| phase 已存在 + 最新 artifact = execute | → refine from post-execute results |
 
 **关键不变量**：artifact 过滤按 `session.phase`，不读 `state.json.current_phase`。`phase_is_new` → 直接 `analyze`。
 
@@ -289,11 +254,13 @@ resolve_milestone(phase_number):
 | `medium` / `small` | analyze-macro → plan --from analyze:{ANL_ID} → execute → ...（跳过 roadmap + analyze-phase） |
 | `unknown` | 默认走 large 路径，post-analyze-scope 决策节点再纠正 |
 
-**Refine from verify results:**
+**Refine from post-execute results:**
+
+在 execute artifact 的 scratch dir 中检查结果文件（verification.json 由 execute 内置 gate 产出）：
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] | `verify-failed` |
+| 无 verification.json 或 passed==false 或 gaps[] | `execute` (触发 post-execute fix loop) |
 | passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
@@ -304,7 +271,7 @@ resolve_milestone(phase_number):
 
 决定下游质量管线长度。读 `session.quality_mode_override`（CLI 标志 `--quality`），无则按规则推断：
 
-| Condition | Mode | Pipeline (verify 之后) |
+| Condition | Mode | Pipeline (execute 之后) |
 |-----------|------|-------------------------|
 | Has `specs/REQ-*.md` + 当前 phase 业务范围明确 | `full` | business-test → review → test-gen → test |
 | Default | `standard` | review → test-gen (当 coverage<80%) → test |
@@ -335,7 +302,7 @@ options:
   - label: "统一规划 (Recommended)"
     description: "一次性分析+规划整个里程碑所有 phase，analyze/plan 走里程碑级，适合 phase 间关联紧密"
   - label: "独立规划"
-    description: "逐个 phase 走完整生命周期（analyze→plan→execute→verify→...），适合 phase 间独立性高"
+    description: "逐个 phase 走完整生命周期（analyze→plan→execute→...），适合 phase 间独立性高"
 ```
 
 写入 `session.planning_mode`（`"unified"` 或 `"independent"`）。`A_BUILD_STEPS` 据此决定 skill args 是否携带 `{phase}` 占位符。
@@ -369,7 +336,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 { "id": "G1", "goal": "<deliverable>", "boundary": "<in/out note>",
   "done_when": "<objectively checkable condition>",
   "evidence": "verification.json|review.json|uat.md|<test path>",
-  "lifecycle": ["analyze","execute","verify"], "status": "pending" }
+  "lifecycle": ["analyze","execute"], "status": "pending" }
 ```
 `done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。
 
@@ -410,7 +377,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
 3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
-5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
+5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
@@ -558,7 +525,7 @@ Runs only when `task_decomposition` present.
 3. 路径 B（`medium` / `small`）：
    - 删除 `goal-audit` 之前所有未完成的 `roadmap` + `analyze` (phase) step
    - 把下一个未完成的 `plan` step 改为 `maestro-plan --from analyze:{analyze_macro_id}`，去掉 `{phase}`，`source_artifact_ref = analyze:{analyze_macro_id}`
-   - 后续 `execute` / `verify` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
+   - 后续 `execute` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
 4. 路径 C（`unknown`）：
    - 非 auto_confirm → AskUserQuestion 二选一（large / medium-small）；auto_confirm → 默认 large
 5. Reindex steps，标 decision completed，write status.json
@@ -619,7 +586,7 @@ Runs only when `task_decomposition` present.
     "index": 0,
     "skill": "",                  // 执行 step 有值；decision 节点为空字符串/null
     "args": "",
-    "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
+    "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|...
     "scope": null,                // "phase"|"standalone"|"milestone"|null（plan 等需要）
     "decision": null,             // 非 null → decision 节点（值为 gate 名，如 "post-execute"）；null → 执行 step
     "retry_count": 0,             // decision 节点专用