maestro-flow 0.4.11 → 0.4.13

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

@@ -33,19 +33,24 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 | Type | Execution | Flow after |
 |------|-----------|------------|
-| decision (ralph-only) | `Skill("maestro-ralph")` — ralph re-evaluates | Execution ends here |
-| internal | `Skill({ skill, args })` — synchronous | Self-invoke next |
-| external | `maestro delegate --to claude --mode write` | STOP → callback → self-invoke |
-
-HARD RULE: External nodes ALWAYS append `-y` to skill args inside the prompt — delegate sessions are non-interactive.
-HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can execute slash-command skills.
+| decision (ralph-only) | `Skill("maestro-ralph")` | Execution ends here |
+| internal (default) | `Read({file_path: step.command_path})` + 内联解释执行 | Self-invoke next |
+| external (opt-in) | `maestro delegate --to claude --mode write` (STOP → callback) | Self-invoke next |
+
+HARD RULES:
+- internal step：优先通过 `Read({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `Skill({skill})` 调用
+- decision 节点例外：A_EXEC_DECISION 必须使用 `Skill({ skill: "maestro-ralph" })` 进行 handoff（这是 decision 节点的唯一允许用法）
+- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
+- external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
+- 每个 step 必须产出 `--- COMPLETION STATUS ---` 块，否则视为 NEEDS_RETRY
 </context>
 
 <invariants>
-1. **Every step via Skill() or delegate** — never simulate or inline a skill's work
-2. **External → claude only** — `session.cli_tool` is for analysis delegates, NOT execution
-3. **Self-invocation chain** — continues until all steps complete or session paused
-4. **Status.json updated after every change** — resume-safe
+1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
+2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+5. **status.json 每步骤后写盘** — resume-safe
 </invariants>
 
 <state_machine>
@@ -54,8 +59,8 @@ HARD RULE: External nodes ALWAYS delegate to `claude` — only Claude Code can e
 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.status, session.context
-S_HANDLE_FAIL   — 处理失败（重试/跳过/中止）              PERSIST: step.status, session.status
+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>
@@ -127,9 +132,9 @@ S_FALLBACK:
 | 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}` if standalone |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` if standalone |
-| quality-debug | gap context | Read previous step's error/gap from artifact dir |
+| 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:**
@@ -139,91 +144,97 @@ 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 (resume-safe).
+Write enriched args back to status.json.
 
 ### A_EXEC_DECISION
 
 1. Mark step running, write status.json
-2. Display: `[{index}/{total}] ◆ {skill} [decision] Retry: {retry}/{max}`
-3. `Skill({ skill: "maestro-ralph" })` — ralph detects running decision → evaluates → handoff
-4. **This execution ends here** — ralph handles the handoff back
+2. Display: `[{index}/{total}] ◆ {decision} Retry: {retry}/{max}`
+3. `Skill({ skill: "maestro-ralph" })` — ralph 评估 + handoff
+4. 执行在此结束
 
 ### A_EXEC_INTERNAL
 
-1. Mark step running, write status.json
-2. Display: `[{index}/{total}] {skill} [internal]`
-3. Resolve auto flag: `auto ? (flag_map[skill] || "") : ""`
-4. `Skill({ skill: next.skill, args: effective_args })`
-5. Return success/failure
+1. Validate `step.command_path != null`；否则 raise E002，pause session
+2. Mark step running, write status.json
+3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
+4. `Read({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
+5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
+6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
+7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate
+8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+9. Return success / failure
 
-**Auto flag map:** all lifecycle skills → `-y`; `quality-test` → `-y --auto-fix`; unlisted internal → no flag
+**Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
 ### A_EXEC_EXTERNAL
 
+仅当 `step.type == "external"` 时使用（默认链路不产生）。
+
 1. Mark step running, write status.json
-2. Display: `[{index}/{total}] ⚡ {skill} [external]`
-3. Always append `-y` to skill args (delegates are non-interactive): `flag = flag_map[skill] || "-y"`
+2. Display: `[{index}/{total}] ⚡ {step.skill} [external]`
+3. 始终在 prompt 内追加 `-y`（delegate session 非交互）：`flag = flag_map[step.skill] || "-y"`
 4. Execute:
    ```
    Bash({
-     command: `maestro delegate "/${skill} ${effective_args}" --to claude --mode write`,
+     command: `maestro delegate "/${step.skill} ${effective_args}" --to claude --mode write`,
      run_in_background: true, timeout: 600000
    })
    STOP — wait for callback.
    ```
-5. On callback: retrieve output → S_POST_EXEC or S_HANDLE_FAIL
+5. On callback: 把回调输出视为 step 的执行结果 → S_POST_EXEC / S_HANDLE_FAIL
 
 ### A_MARK_COMPLETE
 
-1. `step.status = "completed"`, `step.completed_at = now`
-2. Scan output for context signals:
-   - `PHASE: N` → session.phase
-   - `scratch_dir: path` → context.scratch_dir
-   - `SPEC-xxx` → context.spec_session_id
-3. Scan output for `--- COMPLETION STATUS ---` block. If found, parse and map:
-   - `STATUS: DONE` → `step.status = "completed"`
-   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.concerns = CONCERNS value`
-   - `STATUS: NEEDS_RETRY` → trigger retry: set `step.status = "pending"`, `step.retried = true` → S_HANDLE_FAIL
-   - `STATUS: BLOCKED` → `session.status = "paused"`, display blocker reason from CONCERNS
-   - `STATUS: NEEDS_CONTEXT` → `session.status = "paused"`, display context gap from CONCERNS
-   - If no `--- COMPLETION STATUS ---` block found → fall back to existing heuristic (backward compatible)
-4. Write status.json
-5. Display: `[{index}/{total}] ✓ {skill} completed`
+1. 从 step 输出中提取 `--- COMPLETION STATUS ---` 块（required）
+2. 解析并写入：
+   - `STATUS: DONE` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE"`
+   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE_WITH_CONCERNS"`, `step.concerns = <CONCERNS>`
+   - `STATUS: NEEDS_RETRY` → `step.status = "pending"`, `step.retried = true`, `step.completion_confirmed = false`, → S_HANDLE_FAIL
+   - `STATUS: BLOCKED` / `NEEDS_CONTEXT` → `session.status = "paused"`, `step.completion_status` 记录原因, `step.completion_confirmed = false`
+   - 缺失 `--- COMPLETION STATUS ---` 块 → 视为 NEEDS_RETRY（不允许 heuristic fallback）
+3. 写入 `step.completion_evidence`（artifact 路径 / 关键输出节选）
+4. 扫描输出抓取 context 信号：`PHASE: N` → session.phase；`scratch_dir: path` → context.scratch_dir；`BLP-xxx` → context.blueprint_session_id
+5. `step.completed_at = now`，写 status.json
+6. **Sub-goal evidence 校验**（task_decomposition 存在时）：若 `step.goal_ref` 对应子目标的 `lifecycle` 覆盖当前 stage 且 evidence artifact 已生成 → 暂不直接置 done，仍交由 post-goal-audit 决策；仅在 step 显式确认时更新 `task_decomposition[*].completion_confirmed = false` 占位（保持 pending）
+7. Display: `[{index}/{total}] ✓ {step.skill} completed (confirmed)`
 
 ### A_RETRY
 
-1. `step.retried = true`, `step.status = "pending"`, `step.error = null`
+1. `step.retried = true`, `step.status = "pending"`, `step.error = null`, `step.completion_confirmed = false`
 2. Write status.json
 
 ### A_SKIP_STEP
 
-1. `step.status = "skipped"`
+1. `step.status = "skipped"`, `step.completion_confirmed = false`
 2. Write status.json
 
 ### A_PAUSE_SESSION
 
 1. `session.status = "paused"`, write status.json
-2. Display: `[{index}/{total}] ✗ {skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+2. Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
 
 ### A_COMPLETE_SESSION
 
-1. `session.status = "completed"`, write status.json
-2. Display completion report:
+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}
+     Steps:    {completed}/{total}   confirmed: {confirmed}/{completed}
 
-     [✓] 0.   maestro-plan 1            [internal]
-     [✓] 1. ⚡ maestro-execute 1         [external]
-     [✓] 2.   maestro-verify 1          [internal]
+     [✓] 0.   maestro-plan 1            [internal · global]
+     [✓] 1.   maestro-execute 1         [internal · project]
+     [✓] 2.   maestro-verify 1          [internal · global]
      [✓] 3. ◆ post-verify               [decision]
      ...
    ============================================================
    ```
-   Icons: `✓` completed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
+   Icons: `✓` confirmed, `—` skipped, `✗` failed, `◆` decision, `⚡` external
 
 </actions>
 
@@ -236,22 +247,26 @@ Write enriched args back to status.json (resume-safe).
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
 | E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
-| E002 | error | status.json corrupt | Show path, suggest manual check |
-| E003 | error | Delegate failed + user abort | Mark paused, suggest resume |
-| W001 | warning | Step completed with warnings | Log and continue |
+| E002 | error | step.command_path missing for internal step | Pause, ask ralph to rebuild step |
+| E003 | error | status.json corrupt | Show path, manual check |
+| E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
+| E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| W001 | warning | Step completed with concerns | Log and continue |
 
 ### Success Criteria
 
-- [ ] Session discovery covers both maestro-* and ralph-*
-- [ ] `-y` parsed from args OR inherited from session.auto_mode
-- [ ] Placeholders resolved from session context
-- [ ] Per-skill enrichment provides correct args
-- [ ] Decision nodes hand off to maestro-ralph via Skill()
-- [ ] Internal nodes execute via Skill() with auto flag
-- [ ] External nodes delegate to claude with `-y` in prompt args, run_in_background + STOP
-- [ ] Context signals propagate to status.json
-- [ ] Auto mode: retry once then pause
-- [ ] Interactive: AskUserQuestion retry/skip/abort
-- [ ] Self-invocation continues until complete or paused
+- [ ] Session discovery covers maestro-* and ralph-*
+- [ ] `-y` parsed from args 或 session.auto_mode
+- [ ] Placeholders resolved；per-skill enrichment 正确
+- [ ] Decision 节点 Skill("maestro-ralph") handoff
+- [ ] Internal 节点通过 Read({step.command_path}) 内联执行，禁止 Skill()
+- [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
+- [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
+- [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置
+- [ ] step.completion_evidence 记录 artifact path / 输出节选
+- [ ] Context signals 传播 status.json
+- [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
+- [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] A_COMPLETE_SESSION 校验全部 step confirmed + sub-goal all_done
 
 </appendix>