maestro-ralph-beta

<purpose>
Self-running closed-loop: routes by session state, executes one tick, self-invokes until done or paused.
Single skill handles build + execute + decision evaluation. Session: `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`.
</purpose>

<context>
$ARGUMENTS — intent text, flags, or keywords.

**Parse:**
```
-y flag       → auto_confirm = true
.md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
"status"      → status mode
"continue"    → resume mode
Remaining     → intent (new session)
```

**State files:**
- `.workflow/state.json` — artifact registry, milestones, phases
- `.workflow/roadmap.md` — milestone/phase structure
- `.workflow/.maestro/ralph-*/status.json` — ralph session state
</context>

<invariants>
1. **Self-invocation = `Skill("maestro-ralph-beta")`** — 每次 tick 末尾强制自调用；除非 router 命中终止条件
2. **status.json 是唯一真源；写入权限分层**：
   - **Step 级字段**（`step.completion_*`, `step.status` 执行 step running↔completed, `step.load.*`, `step.retried`，以及执行 step 的 `active_step_index` 占用/释放）→ 由 `maestro ralph next/complete/retry` CLI 写入
   - **会话级结构**（`session.status`, `passed_gates`, `steps[]` 增删/reindex, `task_decomposition[*]`, `boundary_contract`, `context.*`, `scope_verdict`, `consec_exit2_count`, decision step 的 `status`/`retry_count`/`active_step_index` 占用与释放）→ 由 maestro-ralph-beta 写入
3. **执行 step 通过 `maestro ralph next` 加载** — CLI 解析 frontmatter + `<required_reading>` + `<deferred_reading>`、读 required 全文、拼 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`
4. **decision step 内联评估** — 不 handoff、不调 ralph next；按 `step.decision` 分派 A_DECISION_*
5. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入；STATUS 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`
6. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，只扫描 `.claude/commands/`）；未命中标 `command_scope = "missing"`
7. **required reading 由 CLI 加载** — 缺失 → 退出码 1（E007）→ pause session；ralph build 阶段不读 .md 内容
8. **active_step_index 一致性由 CLI 维护** — 同一 session 同时最多一个 step 持有；E008/E009 直接退出
9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 由用户输入
10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段累加，既有字段不删不改
12. **禁止以上下文消耗为由中断自调用链** — harness 自动处理 context compression（消息摘要），模型无需判断上下文剩余空间。自调用的唯一合法终止条件是：router 命中终止条件（S_COMPLETE / S_FALLBACK / END）、session paused、或 decision 末尾的 A_PAUSE_ESCALATE。以"上下文不足"、"已连续完成 N 个 step"、"避免 context overflow"等理由中断属于 invariant violation
</invariants>

<router>

每次进入 skill 先执行 router，按顺序匹配，先命中先用。术语：
- **active session** = `.workflow/.maestro/ralph-*/status.json` 中 `status ∈ {running, paused}` 的最新会话
- **live session** = active session 且 `status == "running"`
- **active_step** = `session.steps[session.active_step_index]`

```
1. intent == "status"                                          → S_STATUS                  → END
2. intent == "continue" AND active session exists              → A_RESUME_SESSION → S_TICK_LOCATE
3. intent non-empty AND intent ∉ {"continue","status"} AND active session exists
                                                               → S_FALLBACK                → END
   display "已有 active session {id}；先 /maestro-ralph-beta continue 续跑或显式 abandon"
4. live session AND active_step.status == "running" AND active_step.decision != null
                                                               → S_TICK_LOCATE → S_TICK_DECISION
5. live session AND has pending step                            → S_TICK_LOCATE
6. live session AND all completion_confirmed                   → S_COMPLETE                → END
7. active session AND session.status == "paused" AND no intent → S_FALLBACK                → END
   display "Session {id} paused；输入 /maestro-ralph-beta continue 显式恢复"
8. no active session AND intent non-empty                      → S_BUILD_PHASE
9. no active session AND no intent                             → S_FALLBACK                → END
```

</router>

<state_machine>

<states>
# Build phase (one-time per session)
S_RESOLVE_PHASE   — 解析 phase + phase_is_new + D-007 milestone   PERSIST: session.phase, session.phase_is_new, session.milestone
S_INFER           — 推断 lifecycle_position                       PERSIST: session.lifecycle_position
S_RESOLVE_SCOPE   — 读 macro analyze conclusions.scope_verdict    PERSIST: session.scope_verdict, session.analyze_macro_id
S_QUALITY_MODE    — 决定质量管线模式                              PERSIST: session.quality_mode
S_PLANNING_MODE   — 决定统一/独立规划模式                         PERSIST: session.planning_mode
S_DECOMPOSE       — 边界澄清、写执行准则+子目标清单                PERSIST: session.boundary_contract, .execution_criteria, .task_decomposition
S_BUILD_CHAIN     — 构建步骤链                                    PERSIST: session.steps[]
S_CREATE_SESSION  — 写 status.json                                PERSIST: session (全量)
S_CONFIRM         — 用户确认                                      PERSIST: —

# Tick phase (per step)
S_TICK_LOCATE     — 定位 session + 找 active step                 PERSIST: —
S_TICK            — 分派执行 step 或 decision step                 PERSIST: step.status, active_step_index
S_TICK_EXEC       — 执行 step：ralph next → inline → ralph complete PERSIST: via CLI
S_TICK_DECISION   — decision step：内联评估 + 应用裁决             PERSIST: session.steps[], passed_gates, decisions.ndjson
S_HANDLE_FAIL     — 处理执行失败                                  PERSIST: step.status, session.status

# Terminal
S_STATUS          — 显示 session 进度                             PERSIST: —
S_COMPLETE        — 收尾                                          PERSIST: session.status = "completed"
S_FALLBACK        — 引导用户输入或退出                            PERSIST: —
</states>

<transitions>

# === Build phase ===

S_BUILD_PHASE (entry):
  → S_RESOLVE_PHASE