maestro-flow 0.5.44 → 0.5.45

package/.claude/commands/{maestro-ralph-agent.md → maestro-ralph-v2.md}

@@ -1,6 +1,6 @@
 ---
-name: maestro-ralph-agent
-description: Agent-orchestrated lifecycle — compose, dispatch Agent, evaluate decision, loop
+name: maestro-ralph-v2
+description: Adaptive lifecycle orchestrator — compose, dispatch ralph-executor agent, evaluate decision, loop
 argument-hint: "<intent> [-y] [--amend [change]] [--roadmap] | status | continue"
 allowed-tools:
   - Read
@@ -14,11 +14,9 @@ allowed-tools:
   - Agent
 ---
 <purpose>
-Agent-orchestrated variant of maestro-ralph. Same chain-building logic — but execution via Claude Agent instead of CLI delegation: compose prompt → dispatch Agent(maestro-ralph-agent-execute) → agent runs step loop → returns on decision/complete/fail → evaluate decision inline via Agent → re-dispatch → loop.
+Adaptive lifecycle orchestrator: locate step → resolve args → load context → dispatch Agent(ralph-executor) per step (agent 调 `ralph next` + 执行) → extract signals → drift check → ralph complete → evaluate decision → next step → loop.
 
-Session: `.workflow/.maestro/ralph-agent-{YYYYMMDD-HHmmss}/status.json`
-
-Chain building（A_RESOLVE_PHASE → A_INFER_POSITION → A_BUILD_STEPS）、session schema、decomposition（A_DECOMPOSE_TASKS）逻辑同 ralph。
+Session: `.workflow/.maestro/ralph-v2-{YYYYMMDD-HHmmss}/status.json`
 </purpose>
 
 <deferred_reading>
@@ -40,25 +38,31 @@ Remaining      → intent (amend_mode 时为 change_request)
 
 **State files**:
 - `.workflow/state.json` — artifact registry
-- `.workflow/.maestro/ralph-agent-*/status.json` — session state
+- `.workflow/.maestro/ralph-v2-*/status.json` — session state
 </context>
 
 <invariants>
-All ralph invariants (1-16) apply, with the following overrides:
-
-- **Invariant 1 Agent 语义**: ralph-agent 不直接执行 step 内容；执行由 Agent(maestro-ralph-agent-execute) 完成
-- **Invariant 2 覆盖**: ralph-agent 不调用 `Skill("maestro-ralph-execute")`；invariant 17-24 替代 handoff 机制，ralph-agent 持有完整循环
-
-Additionally:
-
-17. **ralph-agent owns the loop** — dispatch Agent → wait → verify → decide → re-dispatch 全部在本命令内完成；execute Agent 是被委派的执行者
-18. **Dispatch via Agent()** — 使用 `Agent({ name, description, prompt })` 启动执行 Agent，Agent 内部调用 `Skill("maestro-ralph-agent-execute", "--session {session_id}")` 加载执行命令
-19. **Synchronous dispatch** — Agent() 调用是同步的（等待返回），不需要 STOP/callback 模式
-20. **Execute Agent 自治执行** — 执行 Agent 自主循环处理所有 pending 执行 step，遇到 decision 节点时停止并返回；执行 Agent 内部调用 `maestro ralph complete` 上报（agent 上报）
-21. **Decision evaluation inline** — decision 节点不 handoff，通过 `Agent()` 启动分析 Agent 在本循环内评估
-22. **Agent return 解析** — 从 Agent 返回文本中解析执行结果（`---AGENT-STATUS---` 块），替代 `---RESULT---` 解析
-23. **No CLI delegation** — 本命令不使用 `maestro delegate`；执行和评估均通过 Agent() 完成
-24. **No inline skill execution** — 本命令不执行 skill 逻辑；执行由 Agent(maestro-ralph-agent-execute) 完成
+1. **Ralph-v2 owns the full loop** — locate step → resolve args → load context → dispatch agent → extract signals → drift → complete，全部在本命令内完成
+2. **One agent per step** — 每个执行 step 派发一个 executor agent，agent 执行完返回，主流程解析结果后决定下一步
+3. **Agent is a thin wrapper** — executor agent 调 `ralph next` 获取 skill prompt 并执行，返回输出；arg resolution、context loading、signal extraction、drift analysis、ralph complete 均由主流程完成
+4. **Synchronous dispatch** — Agent() 调用是同步的（等待返回），不需要 STOP/callback 模式
+5. **主流程调 `ralph complete`** — 每个 step 完成后由主流程调 `maestro ralph complete`，非 agent 上报
+6. **Decision evaluation inline** — decision 节点不 handoff，通过 `Agent()` 启动分析 Agent 在本循环内评估
+7. **No CLI delegation** — 本命令不使用 `maestro delegate`；执行和评估均通过 Agent() 完成
+8. **Decision delegates read-only** — 评估 Agent 通过 prompt 中的 CONSTRAINTS 约束为只读
+9. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（由 execute Agent 完成）
+10. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
+11. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
+12. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform claude --json --quiet` 预校验
+13. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成
+14. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻
+15. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+16. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop
+17. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作
+18. **Evaluate fallback 必须标记** — 评估 Agent 解析 verdict 失败时 fallback 为 "fix"，MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`
+19. **auto_confirm 单一来源** — `auto_confirm` 仅由用户 `-y` 标志设定
+20. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有
+21. **控制权优先级（范式治理）** — FSM 独占 session 生命周期 + step 排序 + retry/fix/escalate + cross-step decision 节点
 </invariants>
 
 <state_machine>
@@ -79,8 +83,12 @@ S_BUILD_CHAIN   — 构建步骤链（build rules 0-14）
 S_CREATE_SESSION — 写 status.json                                       PERSIST: session (全量)
 S_CONFIRM       — 用户确认
 
-S_AGENT_DISPATCH  — 启动执行 Agent                      PERSIST: session.active_agent_name
-S_AGENT_RECEIVE   — 接收 Agent 返回、解析状态              PERSIST: —
+S_STEP_LOCATE     — 找下一个 pending step                    PERSIST: —
+S_STEP_RESOLVE    — 解析占位符 + 丰富参数                    PERSIST: step.args (enriched)
+S_STEP_DISPATCH   — 组装上下文 + 派发 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_*
 S_DECISION_EVAL   — 启动分析 Agent 评估质量门              PERSIST: —
 S_APPLY_VERDICT   — 应用裁决                              PERSIST: session.steps[]
 S_SESSION_DONE    — 所有 step 完成                        PERSIST: session.status
@@ -104,31 +112,48 @@ S_STATUS:
   → END             DO: A_SHOW_STATUS
 
 S_CONTINUE:
-  → S_AGENT_DISPATCH WHEN: running session found
+  → S_STEP_LOCATE    WHEN: running session found
   → S_FALLBACK       WHEN: no running session
 
 S_AMEND_GOAL:
-  → S_AGENT_DISPATCH WHEN: change applied + user confirmed    DO: A_AMEND_GOAL
+  → S_STEP_LOCATE    WHEN: change applied + user confirmed    DO: A_AMEND_GOAL
   → END              WHEN: user cancels
   GUARD: RISK_LEVEL=high → auto_confirm 无效
 
 S_CREATE_SESSION:
-  → S_CONFIRM         WHEN: not auto_confirm
-  → S_AGENT_DISPATCH  WHEN: auto_confirm
+  → S_CONFIRM        WHEN: not auto_confirm
+  → S_STEP_LOCATE    WHEN: auto_confirm
 
 S_CONFIRM:
-  → S_AGENT_DISPATCH  WHEN: user confirms
-  → S_BUILD_CHAIN     WHEN: user edits
-  → END               WHEN: user cancels
+  → S_STEP_LOCATE    WHEN: user confirms
+  → S_BUILD_CHAIN    WHEN: user edits
+  → END              WHEN: user cancels
+
+S_STEP_LOCATE:
+  → S_STEP_RESOLVE   WHEN: pending execution step found (step.decision == null)
+  → S_DECISION_EVAL  WHEN: pending decision step found (step.decision != null)
+  → S_SESSION_DONE   WHEN: no pending steps (all completed/skipped)
+  → S_HANDLE_FAIL    WHEN: has failed step and no pending
+  → S_FALLBACK       WHEN: no running session
+
+S_STEP_RESOLVE:
+  → S_STEP_DISPATCH  DO: A_STEP_RESOLVE_ARGS
 
-S_AGENT_DISPATCH:
-  → S_AGENT_RECEIVE   DO: A_DISPATCH_EXECUTE_AGENT
+S_STEP_DISPATCH:
+  → S_STEP_ANALYZE   WHEN: agent returned output               DO: A_STEP_DISPATCH
+  → S_HANDLE_FAIL    WHEN: agent returned error/null            DO: A_STEP_DISPATCH
 
-S_AGENT_RECEIVE:
-  → S_DECISION_EVAL   WHEN: Agent returned "decision_pending"   DO: A_PARSE_AGENT_RETURN
-  → S_SESSION_DONE    WHEN: Agent returned "session_complete"    DO: A_PARSE_AGENT_RETURN
-  → S_HANDLE_FAIL     WHEN: Agent returned "step_failed"        DO: A_PARSE_AGENT_RETURN
-  → S_HANDLE_FAIL     WHEN: Agent returned null (agent error)   DO: A_PARSE_AGENT_RETURN
+S_STEP_ANALYZE:
+  → S_STEP_DRIFT     WHEN: STATUS == DONE|DONE_WITH_CONCERNS    DO: A_STEP_EXTRACT
+  → S_HANDLE_FAIL    WHEN: STATUS == NEEDS_RETRY|BLOCKED         DO: A_STEP_EXTRACT
+
+S_STEP_DRIFT:
+  → S_STEP_COMPLETE  WHEN: ALIGNED|MINOR_DRIFT                   DO: A_STEP_DRIFT_ANALYZE
+  → S_STEP_DISPATCH      WHEN: MAJOR_DRIFT + not retried             DO: A_STEP_DRIFT_ANALYZE (ralph retry + re-execute)
+  → S_STEP_COMPLETE  WHEN: MAJOR_DRIFT + retried                 DO: A_STEP_DRIFT_ANALYZE (DONE_WITH_CONCERNS)
+
+S_STEP_COMPLETE:
+  → S_STEP_LOCATE    DO: A_STEP_COMPLETE (loop to next step)
 
 S_DECISION_EVAL: (decision 节点 == `step.decision` 非空)
   → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test, post-frontend-verify)
@@ -143,20 +168,20 @@ S_DECISION_EVAL: (decision 节点 == `step.decision` 非空)
                      DO: A_STRUCTURAL_EVALUATE
 
 S_APPLY_VERDICT:
-  → S_AGENT_DISPATCH WHEN: verdict == "proceed"              DO: A_APPLY_PROCEED
-  → S_AGENT_DISPATCH WHEN: post-goal-audit + has_unmet       DO: A_APPLY_GOAL_FIX
-  → S_AGENT_DISPATCH WHEN: post-goal-audit + all_met + INTENT_ALIGNED=true  DO: A_APPLY_GOAL_DONE
+  → S_STEP_LOCATE WHEN: verdict == "proceed"              DO: A_APPLY_PROCEED
+  → S_STEP_LOCATE WHEN: post-goal-audit + has_unmet       DO: A_APPLY_GOAL_FIX
+  → S_STEP_LOCATE WHEN: post-goal-audit + all_met + INTENT_ALIGNED=true  DO: A_APPLY_GOAL_DONE
   → END              WHEN: post-goal-audit + all_met + INTENT_ALIGNED=false  DO: A_REGROUND_HALT
-  → S_AGENT_DISPATCH WHEN: post-analyze-scope                DO: A_APPLY_SCOPE_VERDICT
-  → S_AGENT_DISPATCH WHEN: verdict == "fix"                  DO: A_APPLY_FIX
-  → S_AGENT_DISPATCH WHEN: verdict == "escalate"             DO: A_APPLY_ESCALATE
-  → S_AGENT_DISPATCH WHEN: post-milestone + standard + next milestone   DO: A_ADVANCE_MILESTONE
+  → S_STEP_LOCATE WHEN: post-analyze-scope                DO: A_APPLY_SCOPE_VERDICT
+  → S_STEP_LOCATE WHEN: verdict == "fix"                  DO: A_APPLY_FIX
+  → S_STEP_LOCATE WHEN: verdict == "escalate"             DO: A_APPLY_ESCALATE
+  → S_STEP_LOCATE WHEN: post-milestone + standard + next milestone   DO: A_ADVANCE_MILESTONE
   → END              WHEN: post-milestone + standard + no next milestone
   → END              WHEN: post-milestone + adhoc                       DO: mark completed (set current_milestone = null)
   → END              WHEN: post-debug-escalate                DO: A_PAUSE_ESCALATE
   → END              WHEN: post-reground + drifted + confidence >= 60  DO: A_REGROUND_HALT
-  → S_AGENT_DISPATCH WHEN: post-reground + aligned           DO: A_APPLY_PROCEED
-  → S_AGENT_DISPATCH WHEN: post-reground + drifted + confidence < 60  DO: A_APPLY_PROCEED (标 LOW CONFIDENCE)
+  → S_STEP_LOCATE WHEN: post-reground + aligned           DO: A_APPLY_PROCEED
+  → S_STEP_LOCATE WHEN: post-reground + drifted + confidence < 60  DO: A_APPLY_PROCEED (标 LOW CONFIDENCE)
   GUARD: retry_count >= max_retries → force escalate
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
@@ -165,10 +190,10 @@ S_APPLY_VERDICT:
   GUARD: post-reground + drifted + confidence >= 60 → A_REGROUND_HALT（auto_confirm 不跳过）
 
 S_HANDLE_FAIL:
-  → S_AGENT_DISPATCH WHEN: auto + not retried              DO: A_RETRY
+  → S_STEP_LOCATE WHEN: auto + not retried              DO: A_RETRY
   → END              WHEN: auto + retried                   DO: A_PAUSE_SESSION
-  → S_AGENT_DISPATCH WHEN: interactive + retry
-  → S_AGENT_DISPATCH WHEN: interactive + skip
+  → S_STEP_LOCATE WHEN: interactive + retry
+  → S_STEP_LOCATE WHEN: interactive + skip
   → END              WHEN: interactive + abort
 
 S_SESSION_DONE:
@@ -179,19 +204,109 @@ S_SESSION_DONE:
 <actions>
 
 ### A_CREATE_SESSION
-1. `session_id` format: `ralph-agent-{YYYYMMDD-HHmmss}`
+1. `session_id` format: `ralph-v2-{YYYYMMDD-HHmmss}`
 2. Additional fields: `execution_mode: "agent"`，无 `cli_tool` 字段
-3. Each step: `agent_exec_name: null`（替代 `delegate_exec_id`）
+3. Each step: `agent_exec_name: null`（执行 Agent 名称标识）
 4. Step mode/role/rule assigned per stage (see Stage Mapping table)
 
-### A_DISPATCH_EXECUTE_AGENT
+### A_STEP_RESOLVE_ARGS
+
+解析占位符 + 丰富参数。在 `ralph next` 之前执行。
+
+**1. Placeholder substitution:**
 
-启动执行 Agent 处理 pending 执行 step。Agent 自主循环直到遇到 decision/完成/失败。
+| 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 |
 
-1. Read status.json → 确认有 pending step
-2. Resolve agent name: `{stage_prefix}-{session_id_short}-{HHmmss}`
+**2. Per-skill enrichment** (when args empty or minimal):
 
-   **Agent Name Prefix (by stage):**
+| Skill | Required context | Source |
+|-------|-----------------|--------|
+| maestro-brainstorm | topic | `"{intent}"` |
+| maestro-roadmap | description | `"{intent}"` |
+| maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
+| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-execute | phase or --dir | see --from auto-injection below |
+| quality-debug | gap context | Read previous step's error/gap |
+| quality-* | phase | `{phase}` |
+
+**3. --from auto-injection (phase-level artifact chaining):**
+
+```
+Read state.json.artifacts（含 milestone_history 内归档 artifacts）
+→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+
+plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+  2. 命中 → args 追加 --from analyze:{id}
+  3. 写 step.source_artifact_ref = "analyze:{id}"
+
+execute step（含 {phase} 占位符，args 无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="plan" artifact → id = PLN-xxx, path = scratch/...
+  2. 命中 → args 追加 --dir .workflow/scratch/{path}
+  3. 写 step.source_artifact_ref = "plan:{id}"
+```
+
+兜底：查询无结果 → 不注入，由命令自身 discovery 逻辑处理。已有 `--from` 或 `--dir` 的 step 不覆盖。
+
+**4. Goal context injection:**
+
+当 `step.goal_ref` 非空且 `session.task_decomposition` 存在时：
+```
+goal = session.task_decomposition.find(g => g.id == step.goal_ref)
+if goal:
+  goal_snippet = { id: goal.id, goal: goal.goal, done_when: goal.done_when,
+                   boundary: goal.boundary, evidence: goal.evidence }
+  → 传递给 A_STEP_DISPATCH 注入 agent prompt
+```
+
+**5. Write** enriched args + source_artifact_ref back to status.json.
+
+### A_STEP_DISPATCH
+
+加载前序产出 + 组装上下文 + 派发 executor agent 执行单步。Agent 内部调 `maestro ralph next` 获取 skill prompt 并执行。
+
+**1. Load previous step context:**
+
+- 读前一 completed step 的 `completion_summary` + `completion_caveats` + `completion_decisions` + `completion_deferred`
+- 按 `session.context` 中的路径逐个 Read，提取与当前 step 相关的内容：
+
+   | 当前 stage | 加载什么 | Source |
+   |-----------|---------|--------|
+   | plan | analysis conclusions + scope_verdict | `{context.analysis_dir}/conclusions.json` |
+   | execute | task list + wave assignments | `{context.plan_dir}/TASK-*.json` |
+   | review | changed files + verification results | `{context.scratch_dir}/verification.json` |
+   | test | review findings | `review.json` |
+   | debug | error traces + failing test details | 前一 step 的 `completion_evidence` |
+   | brainstorm | grill report | `{context.grill_id}` report |
+
+- Explore if needed — 产物指向代码位置但缺少上下文 → `maestro explore` 补充（仅 execute/debug/test 且有文件路径引用时）
+- Accumulated signals — 遍历 ALL completed steps → 聚合 caveats + deferred
+
+**2. Goal context pre-injection:**
+
+- GUARD: `ralph_protocol_version >= "2"` → skip（session_anchor 已含 goal context）
+- WHEN `ralph_protocol_version < "2"` 或缺失 AND `step.goal_ref` 非空 → 组装 `<goal_context>` 块注入 prompt：
+```
+<goal_context>
+Sub-goal: {goal.id} — {goal.goal}
+Done when: {goal.done_when}
+Boundary: {goal.boundary}
+Evidence target: {goal.evidence}
+Execution criteria: {session.execution_criteria joined by '; '}
+</goal_context>
+```
+
+**3. Resolve agent name:** `{stage_prefix}-{session_id_short}-{HHmmss}`
 
    | Stage | Prefix |
    |-------|--------|
@@ -206,97 +321,160 @@ S_SESSION_DONE:
    | debug | `dbg` |
    | Other | `run` |
 
-3. Compose `<execution_context>` block:
-
-```xml
-<execution_context>
-  <intent>{session.intent}</intent>
-  <phase>{session.phase}</phase>
-  <milestone>{session.milestone}</milestone>
-  <boundary_contract>
-    <in_scope>{boundary_contract.in_scope}</in_scope>
-    <out_of_scope>{boundary_contract.out_of_scope}</out_of_scope>
-    <definition_of_done>{boundary_contract.definition_of_done}</definition_of_done>
-  </boundary_contract>
-  <execution_criteria>{session.execution_criteria}</execution_criteria>
-  <active_goals>{task_decomposition WHERE status != "superseded"; superseded 目标仅一行标注}</active_goals>
-  <prior_step_context>
-    {最近 5 个已完成 step 的 completion_summary + completion_caveats}
-  </prior_step_context>
-  <accumulated_signals>
-    {聚合所有已完成 step 的 caveats + deferred}
-  </accumulated_signals>
-  <stage_context>
-    {按下一个 pending step 的目标 skill 类型选择性注入，见下表；仅在有实际内容时加入}
-  </stage_context>
-</execution_context>
+**4. Dispatch:**
+
 ```
+Agent({
+  subagent_type: "ralph-executor",
+  name: "{resolved_agent_name}",
+  description: "执行 step {index}: {step.skill}",
+  prompt: `Session: {session_id}
 
-   **Stage-specific `<stage_context>` injection:**
+{goal_context 块，仅 protocol < 2 时}
 
-   | 目标 skill 类型 | 注入重点 |
-   |----------------|---------|
-   | analyze | intent + scope + boundary |
-   | plan | analysis findings + scope_verdict + recommendations |
-   | execute | task list + dependencies + wave + caveats from plan |
-   | review | changed files + verification results + execution decisions |
-   | test | review findings + execution artifacts + coverage data |
-   | debug | error details + failing tests + execution trace |
-   | brainstorm/grill | challenged assumptions + risks + prior findings |
+{loaded_step_context}
+`
+})
+```
 
-4. Dispatch Agent:
+Agent 内部调 `maestro ralph next --session {session_id}` 获取 skill prompt 并执行。
+
+5. Write `step.agent_exec_name` to status.json
+6. Display: `[{index}/{total}] ⟶ {step.skill} → Agent:{name}`
+7. Agent 同步返回 → `agent_output` = 返回文本；返回 null → STATUS=BLOCKED
 
-```
-Agent({
-  name: "{resolved_agent_name}",
-  description: "执行 ralph session steps",
-  prompt: `执行 ralph-agent session {session_id} 的 pending steps。
+### A_STEP_EXTRACT
 
-调用 Skill("maestro-ralph-agent-execute", "--session {session_id}") 执行步骤。
-maestro-ralph-agent-execute 会自动循环执行 pending 执行 step，遇到 decision/完成/失败时返回。
+从 agent 返回的执行输出中提取结构化信号，用于 completion 参数组装。
 
-{execution_context}
+**1. Stage-specific signal extraction:**
 
-执行 Agent 内部调用 maestro ralph complete 上报。你只需确保 Skill 调用完成后输出 ---AGENT-STATUS--- 块。
+| Stage | 提取什么 | 写入字段 |
+|-------|---------|---------|
+| analyze | `conclusions.json` scope_verdict + key_findings | `--summary`, context.analysis_dir |
+| plan | TASK-*.json 数量 + 主要模块 + 波次 | `--summary`, context.plan_dir |
+| execute | 修改文件数 + verification passed/failed | `--summary`, `--evidence`, context.scratch_dir |
+| review | verdict + findings 数量 + severity | `--summary`, `--decisions` |
+| test | pass/fail 统计 | `--summary`, `--evidence` |
+| debug | root cause + 修复内容 | `--summary`, `--decisions` |
+| grill | 核心质疑点数量 | `--summary`, `--caveats`, context.grill_id |
+| brainstorm | 候选方案数 + 推荐方案 | `--summary`, `--decisions`, context.brainstorm_dir |
 
-最后必须输出以下状态块：
+**2. Artifact scanning** — Use Glob 查找执行期间新增/修改的产物:
 
----AGENT-STATUS---
-RESULT: decision_pending|session_complete|step_failed|steps_completed
-LAST_STEP_INDEX: {N}
-DECISION_NODE: {gate name, 仅 decision_pending 时}
-COMPLETED_STEPS: {本次完成的 step 数量}
-FAILURE_REASON: {仅 step_failed 时}
----END---`
-})
-```
+| Pattern | Signal |
+|---------|--------|
+| `conclusions.json` | `analysis_dir` |
+| `TASK-*.json` | `plan_dir` |
+| `verification.json` | `scratch_dir` |
+| `review.json` | review stage |
+| `test-results.json`, `uat.md` | test stage |
+| `grill-report.md` | `grill_id` |
+| `.brainstorming/*` | `brainstorm_dir` |
+
+**3. Output text signal extraction** — 从执行输出文本中提取：
+
+| Signal pattern | 写入 |
+|----------------|------|
+| `ANL-xxx` (artifact ID) | `session.analyze_macro_id` |
+| `PLN-xxx` (artifact ID) | `context.plan_dir` |
+| `BLP-xxx` (artifact ID) | `session.blueprint_id` |
+| `scratch_dir:` 或 `.workflow/scratch/` 路径 | `context.scratch_dir` |
+| `plan_dir:` 路径 | `context.plan_dir` |
+| `PHASE: N` | `session.context.phase` |
+
+**4. STATUS determination:**
 
-5. Write `session.active_agent_name` to status.json
-6. Display: `⟶ Agent:{name} dispatched for session {session_id}`
+| 条件 | STATUS |
+|------|--------|
+| Skill 正常完成 + 有产物 | `DONE` |
+| 完成但有 warnings/concerns | `DONE_WITH_CONCERNS` |
+| 执行出错但可重试（临时错误、网络问题） | `NEEDS_RETRY` |
+| 执行出错且无法重试（schema 错误、command_path 不可达） | `BLOCKED` |
+| Agent 返回 null（崩溃/超时） | `BLOCKED` |
 
-### A_PARSE_AGENT_RETURN
+**5. Compose completion params:**
 
-从 Agent 返回文本中解析 `---AGENT-STATUS---` 块，并验证 session 状态一致性。
+| Param | 规则 | 组装方法 |
+|-------|------|---------|
+| `--summary` | MUST。动词开头，≤100 字 | `"<动词><做了什么>，<量化结果>"` |
+| `--decisions` | SHOULD。每条一个架构/技术决策 | 从执行中做出的非显而易见的选择 |
+| `--caveats` | SHOULD。后续 step 须知 | 发现但不属于本步解决的问题 |
+| `--deferred` | SHOULD。推迟工作项 | 被主动推迟的项 |
+| `--evidence` | SHOULD。验证产物路径 | 指向验证结果文件 |
+| `--concerns` | COND。仅 DONE_WITH_CONCERNS 时 | CAVEATS 内容同时映射为 --concerns |
 
-1. Extract RESULT field → route to next state
-2. Extract metadata: LAST_STEP_INDEX, DECISION_NODE, COMPLETED_STEPS, FAILURE_REASON
-3. If no `---AGENT-STATUS---` block → fallback: re-read status.json 推断状态
-   - 有 pending decision step → `decision_pending`
-   - 全部 completed → `session_complete`
-   - 有 failed step → `step_failed`
-4. **Verify agent reporting** — re-read status.json 验证 agent 上报是否成功写入：
-   - 检查 LAST_STEP_INDEX 对应的 step 是否 `completion_confirmed == true`
-   - 若 Agent 返回 COMPLETED_STEPS > 0 但 status.json 中对应 step 未 completed → 标记 `agent_report_mismatch = true`，RESULT 降级为 `step_failed`，FAILURE_REASON = "agent 上报未写入 status.json"
-   - 检查 `session.status` 是否仍为 "running"（agent 崩溃可能导致 paused）
-5. Display: `[Agent返回] {RESULT} — 完成 {COMPLETED_STEPS} 步`
+### A_STEP_DRIFT_ANALYZE
+
+产物 vs 目标偏离分析。A_STEP_EXTRACT 后、A_STEP_COMPLETE 前执行。
+
+**1. 收集对照基准:**
+
+| 基准来源 | 取值 |
+|---------|------|
+| `step.goal_ref` → goal.done_when | 子目标完成条件 |
+| `session.boundary_contract.definition_of_done` | 全局验收标准 |
+| `session.execution_criteria` | 执行准则 |
+| `session.intent` | 原始意图 |
+
+**2. 对比评分:**
+
+| 维度 | 检查 |
+|------|------|
+| 覆盖度 | 产物是否覆盖 goal.done_when 每个条件 |
+| 方向性 | decisions 是否与 intent/boundary 一致 |
+| 完整性 | 预期产物类型是否齐全 |
+
+**drift_score:**
+- `ALIGNED` — 全部维度通过
+- `MINOR_DRIFT` — 小缺口，不影响后续
+- `MAJOR_DRIFT` — 方向性偏离或关键产物缺失
+
+**3. 修正动作:**
+
+| drift_score | 动作 |
+|-------------|------|
+| ALIGNED | 正常进入 S_STEP_COMPLETE |
+| MINOR_DRIFT | 偏离项追加到 caveats，正常 complete |
+| MAJOR_DRIFT + 未重试 | `Bash("maestro ralph retry {index}")` → 回到 S_STEP_DISPATCH 重执行（drift_correction 作修正上下文注入 prompt） |
+| MAJOR_DRIFT + 已重试 | 以 DONE_WITH_CONCERNS complete |
+
+**4. 写入:** `step.drift_score`, `step.drift_correction`
+
+### A_STEP_COMPLETE
+
+调 `ralph complete` 上报 + 传播上下文信号 + 循环。
+
+1. 使用 A_STEP_EXTRACT 组装的参数调用 `ralph complete`:
+   ```
+   Bash("maestro ralph complete {index} --status DONE --summary \"{SUMMARY}\" [--evidence ...] [--decisions ...] [--caveats ...] [--deferred ...]")
+   ```
+   DONE_WITH_CONCERNS 时 caveats 同时映射 `--concerns`。BLOCKED 时用 `--reason`。
+
+2. **Context signals propagation** — 将关键信号写入 `status.json.context`:
+
+   | Signal | 写入字段 |
+   |--------|---------|
+   | `analysis_dir` | `context.analysis_dir` |
+   | `plan_dir` | `context.plan_dir` |
+   | `scratch_dir` | `context.scratch_dir` |
+   | `grill_id` | `context.grill_id` |
+   | `brainstorm_dir` | `context.brainstorm_dir` |
+   | `blueprint_dir` | `context.blueprint_dir` |
+   | `ANL-xxx` | `session.analyze_macro_id` |
+   | `BLP-xxx` | `session.blueprint_id` |
+   | `phase` | `session.context.phase` |
+
+3. Display: `[{index}/{total}] ✓ {step.skill} → {SUMMARY}`
+4. Loop back to S_STEP_LOCATE
 
 ### A_AGENT_EVALUATE
 
-通过 Agent 在本循环内评估质量门。替代 `maestro delegate --mode analysis`。
+通过 Agent 在本循环内评估质量门。
 
 1. Resolve artifact dir: `.workflow/scratch/{artifact.path}/` with fallback glob
 2. Parse decision metadata: `{ decision, retry_count, max_retries }`
-3. Map result files（同 ralph A_DELEGATE_EVALUATE）:
+3. Map result files:
 
    | Decision | Files |
    |----------|-------|
@@ -327,11 +505,11 @@ FAILURE_REASON: {仅 step_failed 时}
    CONSTRAINTS: 只评估不修改文件 | 置信度<60%倾向 fix | retry {n}/{max} 达上限必须 escalate"
    })
    ```
-5. On return: parse `---VERDICT---` block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; parse failure → fallback STATUS="fix", `parse_failed: true`, `confidence_score: 0` (invariant 13)
+5. On return: parse `---VERDICT---` block — STATUS must match strict enum `PASS|FAIL|PARTIAL|BLOCKED`; parse failure → fallback STATUS="fix", `parse_failed: true`, `confidence_score: 0` (invariant 18)
 6. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
 7. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
    ```json
-   { "id": "DEC-{timestamp}", "timestamp": "{ISO}", "source": "ralph-agent",
+   { "id": "DEC-{timestamp}", "timestamp": "{ISO}", "source": "ralph-v2",
      "node_id": "{step.decision}", "type": "quality-gate",
      "verdict": "{adjusted_verdict}", "confidence_score": {N},
      "parse_failed": false,
@@ -340,7 +518,7 @@ FAILURE_REASON: {仅 step_failed 时}
 
 ### A_AGENT_GOAL_AUDIT
 
-通过 Agent 审计子目标完成情况。替代 `maestro delegate --mode analysis` 的 goal audit。
+通过 Agent 审计子目标完成情况。
 
 1. Read `session.task_decomposition` from status.json
 2. Dispatch audit Agent:
@@ -377,7 +555,7 @@ FAILURE_REASON: {仅 step_failed 时}
 
 ### A_AGENT_REGROUND
 
-通过 Agent 执行意图保真检查。替代 `maestro delegate --mode analysis` 的 reground。
+通过 Agent 执行意图保真检查。
 
 1. Read status.json：intent, boundary_contract, completed steps, done goals
 2. Dispatch reground Agent:
@@ -419,7 +597,7 @@ FAILURE_REASON: {仅 step_failed 时}
 1. 定位刚完成的 macro analyze artifact → `analyze_macro_id`, `conclusions_path`
 2. 读取 `conclusions.scope_verdict`（`large | medium | small`），缺失 → `unknown`
 3. 写入 `session.scope_verdict` + `session.analyze_macro_id`
-4. Append `{session_dir}/decisions.ndjson`：`{ "type": "scope-gate", "source": "ralph-agent", "verdict": "{scope_verdict}", "analyze_macro_id": "{ANL_ID}" }`
+4. Append `{session_dir}/decisions.ndjson`：`{ "type": "scope-gate", "source": "ralph-v2", "verdict": "{scope_verdict}", "analyze_macro_id": "{ANL_ID}" }`
 
 ### A_STRUCTURAL_EVALUATE
 
@@ -432,7 +610,7 @@ FAILURE_REASON: {仅 step_failed 时}
 
 ### A_SHOW_STATUS
 
-1. Find latest `ralph-agent-*` session（by created_at）
+1. Find latest `ralph-v2-*` session（by created_at）
 2. Display: Session, Status, Position, Progress, Current step
 3. List steps: [✓] confirmed, [▸] current, [ ] pending, [◆] decision；执行 step 附 `command_scope` + `command_path`
 4. If `task_decomposition` present → 显示 sub-goals 进度（done/total）
@@ -476,7 +654,7 @@ FAILURE_REASON: {仅 step_failed 时}
 |-------|------|------|
 | 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
 | 2. 解析 | `change_request` 非空 → 直接用；为空 → AskUserQuestion（修改/新增/移除/调整边界） | `change_type` + `change_request` |
-| 3. Mini Grill | Agent 评估影响（替代 maestro delegate） | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 3. Mini Grill | Agent 评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
 | 4. 确认 | AskUserQuestion：应用并继续 / 仅改目标 / 取消 | 用户选择 |
 | 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | re-dispatch |
 
@@ -513,9 +691,9 @@ GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 
 ### A_RETRY / A_PAUSE_SESSION / A_COMPLETE_SESSION
 
-- **A_RETRY**: `Bash("maestro ralph retry {index}")` — 同 ralph
-- **A_PAUSE_SESSION**: `ralph complete N --status BLOCKED --reason "..."` — 同 ralph
-- **A_COMPLETE_SESSION**: 校验所有 step `completion_confirmed == true` + `task_decomposition_all_done == true`，写 `session.status = "completed"` — 同 ralph
+- **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"`
 
 </actions>
 
@@ -523,21 +701,9 @@ GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
 
 <appendix>
 
-### Agent vs CLI-Delegate 对照
-
-| 维度 | ralph-cli (CLI-delegate) | ralph-agent (Agent) |
-|------|-------------------------|---------------------|
-| 执行分发 | `maestro delegate` (Bash bg) | `Agent()` (同步) |
-| 执行包装器 | `maestro-ralph-cli-execute` (delegate 加载) | `maestro-ralph-agent-execute` (Agent 内 Skill 加载) |
-| 结果通信 | `---RESULT---` 文本块 (从 delegate output 解析) | Agent 返回文本 + `---AGENT-STATUS---` 块 |
-| 回调模式 | STOP → re-invocation callback | 同步等待 Agent 返回（无 STOP） |
-| 决策评估 | `maestro delegate --mode analysis` (Bash bg + STOP) | `Agent()` 同步分析（无 STOP） |
-| 完成上报 | 编排器调 `ralph complete`（解析 RESULT 后） | 执行 Agent 内调 `ralph complete`（agent 上报） |
-| session 字段 | `execution_mode: "cli-delegate"`, `cli_tool`, `delegate_exec_id` | `execution_mode: "agent"`, `agent_exec_name` |
-
 ### Stage Mapping
 
-Agent 版无 `delegate_mode`/`delegate_rule` 字段。执行 Agent 始终拥有完整工具集（read + write），由 skill 自身约束行为。Decision 评估 Agent 通过 prompt 中的 CONSTRAINTS 约束为只读。
+执行 Agent 始终拥有完整工具集（read + write），由 skill 自身约束行为。Decision 评估 Agent 通过 prompt 中的 CONSTRAINTS 约束为只读。
 
 | Stage | Skill (independent) | Skill (unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
@@ -566,7 +732,7 @@ Build rules 0-14 全部适用，包括 spec-setup 预检（rule 0.5）、grill a
 
 ```json
 {
-  "session_id": "ralph-agent-{YYYYMMDD-HHmmss}",
+  "session_id": "ralph-v2-{YYYYMMDD-HHmmss}",
   "source": "ralph", "status": "running",
   "execution_mode": "agent",
   "ralph_protocol_version": "2",
@@ -645,7 +811,7 @@ Build rules 0-14 全部适用，包括 spec-setup 预检（rule 0.5）、grill a
 
 ### Fix-Loop Templates
 
-6 套 fix-loop templates（post-execute / post-business-test / post-review / post-test / post-frontend-verify / post-goal-audit），结构同 ralph。插入的 step 通过 Agent dispatch 执行，由 execute Agent 内调 `ralph complete` 上报。
+6 套 fix-loop templates（post-execute / post-business-test / post-review / post-test / post-frontend-verify / post-goal-audit）。插入的 step 通过 A_STEP_DISPATCH 派发 executor agent 逐步执行，由主流程调 `ralph complete` 上报。
 
 ### Error Codes
 
@@ -654,29 +820,30 @@ E001–E006, W001–W004 适用。Agent 新增：
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
 | E014 | error | Agent execution failed (Agent returned null) | Retry once, then BLOCKED |
-| E015 | error | `---AGENT-STATUS---` block not found | Fallback: re-read status.json 推断 |
 | E016 | error | Evaluation Agent verdict parse failed | Fallback fix + parse_failed: true |
 
 ### Success Criteria
 
-- [ ] ralph-agent owns full loop: dispatch Agent → wait → verify → decide → re-dispatch
-- [ ] 执行通过 `Agent()` 分发，Agent 内调 `Skill("maestro-ralph-agent-execute", "--session {id}")` 执行
-- [ ] Agent 返回文本含 `---AGENT-STATUS---` 块（RESULT/LAST_STEP_INDEX/DECISION_NODE/COMPLETED_STEPS/FAILURE_REASON）
+- [ ] ralph-v2 owns full step loop: locate → resolve → dispatch → extract → drift → complete → next
+- [ ] One agent per step — `Agent({ subagent_type: "ralph-executor" })` 每步派发一个
+- [ ] Agent 内调 `maestro ralph next` 获取 skill prompt 并执行，返回执行输出
+- [ ] 主流程调 `maestro ralph complete` 上报（非 agent 上报）
+- [ ] 主流程负责 arg resolution、context loading、signal extraction、drift analysis
+- [ ] Agent 返回执行输出文本，主流程从中提取信号和状态
+- [ ] Agent 崩溃（返回 null）→ STATUS=BLOCKED，转 S_HANDLE_FAIL
 - [ ] 无 STOP/callback 模式 — Agent() 同步等待返回
-- [ ] 执行 Agent 自主循环执行 step，遇 decision 停止返回
-- [ ] 执行 Agent 内部调 `maestro ralph complete` 上报（agent 上报，非编排器上报）
-- [ ] A_PARSE_AGENT_RETURN 验证 status.json：agent 上报写入确认 + session.status 一致性
-- [ ] Decision evaluation 通过 Agent() 同步完成（非 maestro delegate）
+- [ ] Decision evaluation 通过 Agent() 同步完成
 - [ ] Verdict 解析保持 `---VERDICT---` 格式，parse 失败 → fallback fix + parse_failed: true
-- [ ] decisions.ndjson 追加：source 字段为 `"ralph-agent"`
-- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name` 替代 `delegate_exec_id`，含 `artifacts_produced`
-- [ ] Chain building（S_RESOLVE_PHASE through S_BUILD_CHAIN）逻辑同 ralph，本文件自包含执行
-- [ ] execution_context 块含 prior_step_context（滑动窗口 5 step）+ accumulated_signals + stage_context
-- [ ] execution_context 中 boundary_contract 不截断；superseded 目标仅一行标注
+- [ ] decisions.ndjson 追加：source 字段为 `"ralph-v2"`
+- [ ] Session schema: `execution_mode: "agent"`，`agent_exec_name`（执行 Agent 名称标识），含 `artifacts_produced`
+- [ ] Chain building（S_RESOLVE_PHASE through S_BUILD_CHAIN）自包含执行
+- [ ] A_STEP_DISPATCH 含前序产出加载（滑动窗口 5 step + accumulated signals + stage-specific artifacts）
 - [ ] Agent name 含 stage prefix（grl/brn/anm/ana/pln/exe/rev/tst/dbg）
-- [ ] Stage Mapping 表内联适配（无 delegate_mode/delegate_rule，Agent 始终 read+write，评估 Agent prompt 约束只读）
-- [ ] completion_summary 在 DONE/DONE_WITH_CONCERNS 时为 MUST（由 execute Agent 的 ralph complete --summary 写入）
-- [ ] CAVEATS 在 DONE_WITH_CONCERNS 时同时映射 --concerns（execute Agent 负责）
+- [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] CAVEATS 在 DONE_WITH_CONCERNS 时同时映射 --concerns
+- [ ] A_STEP_EXTRACT 从 agent 输出提取 artifact IDs、path signals、phase signals
+- [ ] A_STEP_DRIFT_ANALYZE：ALIGNED/MINOR_DRIFT → complete；MAJOR_DRIFT+未重试 → retry；MAJOR_DRIFT+已重试 → DONE_WITH_CONCERNS
+- [ ] A_STEP_COMPLETE 将 context signals 写入 status.json.context
 - [ ] A_AMEND_GOAL：完整 5 步流程 + deferred_reading ralph-amend-goal.md + Agent mini grill 含完整 prompt
 - [ ] 旧目标标 superseded（superseded_by + superseded_at），新目标 origin: "CHG-xxx"
 - [ ] goal_changelog 含完整 before/after + impact_assessment
@@ -684,12 +851,8 @@ E001–E006, W001–W004 适用。Agent 新增：
 - [ ] spec-setup 预检（build rule 0.5）
 - [ ] post-milestone adhoc 分支：mark completed + set current_milestone = null
 - [ ] post-reground + drifted + confidence < 60 → A_APPLY_PROCEED (LOW CONFIDENCE)
-- [ ] Fix-loop 插入的 step 通过 Agent dispatch 执行，`agent_exec_name` 初始化为 null
+- [ ] Fix-loop 插入的 step 通过 A_STEP_DISPATCH 逐步执行
 - [ ] re-grounding 3-step 插入规则（build rule 5.5）不变
 - [ ] A_REGROUND_HALT 漂移熔断（auto_confirm 不跳过）不变
-- [ ] `---AGENT-STATUS---` 块缺失时 fallback：re-read status.json 推断状态
-- [ ] Agent 超时/崩溃 → A_PARSE_AGENT_RETURN fallback 推断 + S_HANDLE_FAIL 路径
 
 </appendix>
-</output>
-</output>