Maestro Ralph Cli Execute

---
name: maestro-ralph-cli-execute
description: Skill execution wrapper for delegate — execute skill, return structured result
argument-hint: "--session <id> | <skill-name> [args...]"
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Skill
  - AskUserQuestion
---
<purpose>
Thin execution wrapper for CLI delegation.

Job: receive session ID (or skill name + args) → load via `maestro ralph next` → execute the skill → scan artifacts → output structured `---RESULT---` block.

This command does NOT manage sessions, compose prompts, make decisions, or call `maestro ralph complete`. Completion 由 orchestrator (`/maestro-ralph-cli`) 负责：orchestrator 解析 `---RESULT---` 块后调用 `maestro ralph complete N --status <STATUS> --summary <SUMMARY> [--evidence ...] [--decisions ...] [--caveats ...] [--deferred ...]`，清 `active_step_index`。
</purpose>

<context>
$ARGUMENTS — `--session <id>` (session mode) 或 `<skill-name> [args...]` (direct mode)

**Parse:**

--session → session_id (session mode: skill 由 ralph next 从 status.json 解析，无需传 skill name) First token → skill_name (direct mode only, e.g., maestro-plan, maestro-execute) Remaining → skill_args (direct mode only)

`<execution_context>` 块由 ralph-cli delegation prompt 注入于 `$ARGUMENTS` 之前，含 intent、boundary、goals 等，透传给 skill。
</context>

<invariants>
1. **Execute exactly one skill** — session mode 由 `ralph next` 解析，direct mode 由 skill_name 确定；执行一次即返回
2. **Structured output** — always end with `---RESULT---` / `---END---` block
3. **No session management** — never create/modify sessions, make decisions, or call `maestro ralph complete`（completion 由 orchestrator 负责）
4. **No self-invocation** — execute once and return
5. **Artifact scanning** — after skill execution, scan for produced artifacts
6. **Required reading 由 CLI 负责** — session mode 下 `ralph next` 自动展开 + 加载 `<required_reading>`，缺失 → exit 1（E007），cli-execute 不手动处理
7. **Deferred reading 只记录** — `<deferred_reading>` 路径由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read，不提前批量读取
8. **并发保护** — 同一 session 最多一个 step 持 `active_step_index`；`ralph next` exit 3 表示冲突，不静默推进
9. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
10. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 必须全量捕获，严禁 `| head`/`| tail` 等截断管道
</invariants>

<state_machine>

<states>
S_PARSE     — 解析 skill name + args              PERSIST: —
S_EXECUTE   — 执行 skill                          PERSIST: —
S_SCAN      — 扫描产物 + 提取信号                   PERSIST: —
S_OUTPUT    — 输出结构化结果                        PERSIST: —
</states>

<transitions>
S_PARSE → S_EXECUTE    DO: A_PARSE_ARGS
S_EXECUTE → S_SCAN     DO: A_EXECUTE_SKILL
S_SCAN → S_OUTPUT      DO: A_SCAN_ARTIFACTS
S_OUTPUT → END         DO: A_OUTPUT_RESULT
</transitions>

<actions>

### A_PARSE_ARGS

1. Parse `--session <id>` → `session_id`（session mode）
2. 无 `--session` → extract `skill_name`（first token）and `skill_args`（remaining）为 direct mode
3. Parse `<execution_context>` block from delegation prompt if present:

intent, phase, boundary_contract, active_goals, execution_criteria

### A_EXECUTE_SKILL

1. If `session_id` present → `Bash("maestro ralph next --session {session_id}")` — CLI loads skill + required_reading, returns prompt
- **必须全量捕获 stdout，严禁 `| head`/`| tail` 等任何截断管道**（stdout 含完整 skill prompt，截断会导致执行内容不完整）
- Exit 0 → 按 stdout 内联执行（stdout 含 CLI 拼接好的完整 prompt + session_anchor）
- Exit 1 → required_reading 缺失或 schema 错误 → set `status = "BLOCKED"`, skip to S_OUTPUT, SUMMARY 引用 CLI stderr
- Exit 2 → 无 pending step（已全部完成）→ set `status = "DONE"`, SUMMARY = "所有 step 已完成", skip to S_OUTPUT
- Exit 3 → active_step_index 冲突（另一进程占用）→ set `status = "BLOCKED"`, SUMMARY = "并发冲突", skip to S_OUTPUT
2. If no session → `Skill({ skill: skill_name, args: skill_args })` — direct skill call
3. **Goal context**: `ralph next` CLI 输出的 session_anchor 已含 goal context（`ralph_protocol_version >= "2"`），无需额外注入
4. **Deferred reading**: `ralph next` 将 `<deferred_reading>` 路径记录到 `step.load.deferred_files`，执行阶段按需 Read
5. **Inline execution** — 按 stdout 内容执行 skill 逻辑；执行完成后进入 S_SCAN
6. Track execution: note start time, watch for errors

### A_SCAN_ARTIFACTS

After skill execution, scan for produced artifacts:

| Pattern | Stage 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` |

Use `Glob` to find files created/modified during execution.

Extract signals from output:
- Artifact IDs: `ANL-xxx`, `PLN-xxx`, `BLP-xxx`
- Path signals: `scratch_dir:`, `plan_dir:`
- Phase signals: `PHASE: N`

### A_OUTPUT_RESULT

Output structured result block.

---RESULT--- STATUS: DONE|DONE_WITH_CONCERNS|NEEDS_RETRY|BLOCKED SUMMARY: <动词开头，≤100 字的执行总结> ARTIFACTS: <逗号分隔的产物路径> EVIDENCE: <验证产物路径，如 verification.json、uat.md、e2e-results.json> DECISIONS: <本步做出的关键决策，分号分隔> CAVEATS: <后续步骤需注意的事项；DONE_WITH_CONCERNS 时同时作为 concerns> DEFERRED: <推迟到后续的工作项，分号分隔> SIGNALS: <key=value 对，分号分隔，如 plan_dir=.workflow/scratch/PLN-xxx;phase=2> ---END---

**Rules:**
- STATUS 必填，从执行结果推断（仅 4 个合法值，NEEDS_CONTEXT 已废除）
- SUMMARY 必填（DONE/DONE_WITH_CONCERNS 时为 MUST），动词开头
- ARTIFACTS 列出所有新增/修改的产物文件路径
- EVIDENCE 为 SHOULD，列出验证产物路径
- DECISIONS/CAVEATS/DEFERRED 为 SHOULD，有则填
- SIGNALS 提取 A_SCAN_ARTIFACTS 发现的 key=value 对

**SIGNALS→context 映射：**

| Signal key | 写入 status.json 字段 |
|------------|----------------------|
| `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` |

**Stage-specific SUMMARY 提取指引：**

| Stage | SU