maestro-flow 0.4.10 → 0.4.12

package/.codex/skills/maestro-ralph/SKILL.md

@@ -1,491 +1,740 @@
----
-name: maestro-ralph
-description: Use when the optimal command sequence is unclear and needs automated state-based determination
-argument-hint: "\"intent\" [-y] | status | continue | execute"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
----
-
-<purpose>
-Closed-loop decision engine for the maestro workflow lifecycle.
-Coordinator infers position -> decomposes intent into a goal-tracked sub-goal checklist ->
-builds chain -> **directly invokes each skill in-context** -> delegates evaluation at
-decision nodes -> dynamically grows the step chain until all sub-goals converge.
-
-Entry: `"intent"` (new session), `execute`/`continue` (resume), `status` (display).
-Node types: **skill** (direct in-context invocation) and **decision** (delegate / structural evaluate).
-Session at `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`.
-
-Codex specifics:
-- **No agent spawning** — skills run directly in coordinator context, sequentially, one step at a time.
-- **Goal created via built-in tool** — `create_goal` binds the decomposed sub-goal checklist as a
-  hard objective; `update_plan` mirrors steps; `update_goal` releases on convergence. Codex
-  registers the goal itself via `create_goal`.
-</purpose>
-
-<context>
-$ARGUMENTS -- intent text, flags, or keywords.
-
-**Parse**: `-y` -> auto_mode. `.md/.txt` path -> input_doc (supplementary, never substitutes lifecycle). Remaining -> intent.
-
-**`-y` downstream propagation**:
-
-| Skill | Flag | Effect |
-|-------|------|--------|
-| maestro-init | `-y` | skip interactive |
-| maestro-analyze | `-y` | skip scoping |
-| maestro-brainstorm | `-y` | skip questions |
-| maestro-roadmap | `-y` | skip choices |
-| maestro-plan | `-y` | skip confirmation |
-| maestro-execute | `-y` | skip confirmation, auto-continue blocked |
-| quality-auto-test | `-y` | skip plan confirmation |
-| quality-test | `-y --auto-fix` | auto gap-fix loop |
-| maestro-verify | `-y` | skip confirmation |
-| quality-review | `-y` | skip confirmation |
-| quality-debug | `-y` | skip confirmation |
-| maestro-milestone-complete | `-y` | skip knowledge promotion |
-| maestro-milestone-audit | `-y` | skip confirmation |
-
-**State files**: `.workflow/state.json`, `.workflow/roadmap.md`, `.workflow/.maestro/ralph-*/status.json`
-</context>
-
-<invariants>
-1. **Skills invoked DIRECTLY in-context** — coordinator runs `$skill {resolved_args}` itself, sequentially. NO spawn_agents_on_csv, NO wave, NO worker CSV.
-2. **Coordinator owns the loop** — infer -> decompose -> build -> for each step: resolve args -> invoke skill -> read result -> persist -> next.
-3. **Decision nodes evaluate, never execute** — quality-gate/goal-gate via `maestro delegate --role analyze`; structural decisions evaluated directly.
-4. **Goal is tool-created, not prompt-emitted** — `A_DECOMPOSE_TASKS` calls `create_goal` with the sub-goal checklist as success criteria. `update_goal` on full convergence; never released while sub-goals unmet.
-5. **task_decomposition drives DYNAMIC step growth** — sub-goals are the convergence spec; `steps[]` is a living array. `post-goal-audit` re-checks the checklist and **inserts scoped skill steps** for every unmet sub-goal (same insert+reindex+retry mechanism as fix-loops). Decomposition feeds adaptive branching, never freezes a plan.
-6. **Status JSON: schema-additive + step-dynamic** — decomposition fields (`boundary_contract`, `execution_criteria`, `task_decomposition`, `goal_checklist_path`) are OPTIONAL; absent = old behavior. `steps[]` grows at runtime via decisions; `goal_ref` traces dynamically-added steps. Never remove/rename existing fields.
-7. **Sequential execution** — one step at a time in index order; no parallelism (no spawning). Each step's result read before the next starts.
-8. **Quality mode governs steps** — full/standard/quick determines quality stages.
-9. **passed_gates skip** — already-passed gates not re-run unless code changed.
-</invariants>
-
-<state_machine>
-
-<states>
-S_PARSE_ROUTE     -- 解析参数、路由入口点                PERSIST: --
-S_STATUS          -- 显示 session 进度后结束             PERSIST: --
-S_INFER           -- 推断生命周期位置                    PERSIST: session.lifecycle_position
-S_RESOLVE_PHASE   -- 解析目标 phase                      PERSIST: session.phase
-S_QUALITY_MODE    -- 确定质量模式 full/standard/quick     PERSIST: session.quality_mode
-S_DECOMPOSE       -- 边界澄清、写执行准则+子目标、建 goal  PERSIST: session.boundary_contract, .execution_criteria, .task_decomposition
-S_BUILD_CHAIN     -- 构建步骤链                          PERSIST: session.steps[]
-S_CREATE_SESSION  -- 写 status.json                      PERSIST: session (full)
-S_CONFIRM         -- 用户确认（auto_mode skip）          PERSIST: --
-S_LOAD_NEXT       -- 找下一个 pending step               PERSIST: --
-S_STEP_EXEC       -- 直接调用 skill 执行该 step           PERSIST: session.steps[], context
-S_DECISION_EVAL   -- 评估质量门 / 目标门                 PERSIST: --
-S_APPLY_VERDICT   -- 应用裁决                            PERSIST: passed_gates[], retry_count
-S_FIX_LOOP        -- 插入修复步骤、重索引                PERSIST: session.steps[] (expanded)
-S_COMPLETE        -- 标记完成                            PERSIST: session.status = "completed"
-S_PAUSED          -- 暂停等待人工                        PERSIST: session.status = "paused"
-S_FALLBACK        -- 请求用户输入                        PERSIST: session.status = "paused"
-</states>
-
-<transitions>
-
-S_PARSE_ROUTE:
-  -> S_STATUS        WHEN: intent == "status"
-  -> S_LOAD_NEXT     WHEN: intent == "execute" | "continue"
-  -> S_DECISION_EVAL WHEN: running session with decision step in "running"
-  -> S_INFER         WHEN: intent non-empty
-  -> S_FALLBACK      WHEN: no intent AND no running session
-
-S_STATUS -> END      DO: A_SHOW_STATUS
-
-S_INFER:
-  -> S_RESOLVE_PHASE WHEN: position resolved    DO: A_INFER_POSITION
-  -> S_FALLBACK      WHEN: cannot infer
-
-S_RESOLVE_PHASE:
-  -> S_QUALITY_MODE  DO: A_RESOLVE_PHASE
-
-S_QUALITY_MODE:
-  -> S_DECOMPOSE     DO: A_DETERMINE_QUALITY_MODE
-
-S_DECOMPOSE:
-  -> S_BUILD_CHAIN   DO: A_DECOMPOSE_TASKS
-                     GUARD: broad intent (重构/全面/重写/迁移/overhaul/migrate/rewrite) -> MUST clarify boundary even if auto_mode
-                     GUARD: narrow intent (single file/function/bug) -> auto-derive, skip questions
-                     GUARD: position in {brainstorm, init} -> skip decomposition (no concrete target yet)
-
-S_BUILD_CHAIN:
-  -> S_CREATE_SESSION DO: A_BUILD_STEPS
-
-S_CREATE_SESSION:
-  -> S_CONFIRM       WHEN: not auto_mode                       DO: A_CREATE_SESSION
-  -> S_LOAD_NEXT     WHEN: auto_mode                           DO: A_CREATE_SESSION
-
-S_CONFIRM:
-  -> S_LOAD_NEXT     WHEN: "Proceed"
-  -> S_BUILD_CHAIN   WHEN: "Edit"
-  -> S_QUALITY_MODE  WHEN: "Change quality mode"
-  -> S_PAUSED        WHEN: "Cancel"
-
-S_LOAD_NEXT:
-  -> S_DECISION_EVAL WHEN: next_step.type == "decision"
-  -> S_STEP_EXEC     WHEN: next_step.type == "skill"
-  -> S_COMPLETE      WHEN: no pending steps
-
-S_STEP_EXEC:
-  -> S_LOAD_NEXT     WHEN: success            DO: A_EXEC_STEP
-  -> S_PAUSED        WHEN: failed             GUARD: auto_mode retry once then pause
-
-S_DECISION_EVAL:
-  -> S_APPLY_VERDICT WHEN: quality-gate        DO: A_DELEGATE_EVALUATE
-  -> S_APPLY_VERDICT WHEN: goal-gate           DO: A_GOAL_AUDIT_EVALUATE
-  -> S_APPLY_VERDICT WHEN: structural          DO: A_STRUCTURAL_EVALUATE
-
-S_APPLY_VERDICT:
-  -> S_LOAD_NEXT     WHEN: proceed             DO: add gate to passed_gates
-  -> S_LOAD_NEXT     WHEN: post-goal-audit + all sub-goals met   DO: A_APPLY_GOAL_DONE
-  -> S_LOAD_NEXT     WHEN: post-goal-audit + unmet sub-goals      DO: A_APPLY_GOAL_FIX
-  -> S_FIX_LOOP      WHEN: fix                 DO: clear passed_gates, increment retry
-  -> S_PAUSED        WHEN: escalate
-  -> S_LOAD_NEXT     WHEN: post-milestone + next milestone    DO: A_ADVANCE_MILESTONE
-  -> S_COMPLETE      WHEN: post-milestone + no next
-  -> S_PAUSED        WHEN: post-debug-escalate (always, even -y)
-  GUARD: retry >= max_retries -> force escalate
-  GUARD: confidence < 60 AND proceed -> override to fix
-  GUARD: confidence > 95 AND fix AND retry > 0 -> suggest proceed
-
-S_FIX_LOOP:
-  -> S_LOAD_NEXT     DO: A_INSERT_FIX_LOOP
-
-S_COMPLETE -> END    DO: A_FINALIZE
-S_PAUSED -> END      DO: A_PAUSE_SESSION
-S_FALLBACK -> S_PARSE_ROUTE WHEN: user input | -> END WHEN: cancel
-
-</transitions>
-
-<actions>
-
-### A_INFER_POSITION
-
-**Intent-based override**: brainstorm pattern -> position = brainstorm.
-
-**Bootstrap detection**:
-
-| Condition | Position |
-|-----------|----------|
-| No .workflow/ + no source | brainstorm |
-| No .workflow/ + has source | init |
-| Has .workflow/ but no state.json | init |
-| Has state.json | artifact-based inference |
-
-**Artifact-based inference:** Filter by current_milestone + target phase:
-
-| Condition | Position |
-|-----------|----------|
-| no milestones defined or no roadmap.md | `roadmap` |
-| no artifacts for target phase | `analyze` |
-| latest artifact = analyze | `plan` |
-| latest artifact = plan | `execute` |
-| latest artifact = execute | `verify` |
-| latest artifact = verify | → refine from result files |
-
-**Refine from verify results:**
-
-| Condition | Position |
-|-----------|----------|
-| verification.json: passed==false or gaps[] non-empty | `verify-failed` |
-| passed==true, no review.json, has auto-test report | `review` |
-| passed==true, no review.json, no auto-test report | `business-test` (full) / `review` (standard/quick) |
-| review.json: verdict=="BLOCK" | `review-failed` |
-| review.json: verdict!="BLOCK" | `test` |
-| uat.md: all passed | `milestone-audit` |
-| uat.md: has failures | `test-failed` |
-
-### A_RESOLVE_PHASE
-
-Priority: regex from intent `phase\s*(\d+)` -> latest in-progress artifact's phase -> first incomplete phase -> null (brainstorm/init/roadmap) -> request_user_input if ambiguous.
-
-### A_DETERMINE_QUALITY_MODE
-
-| Condition | Mode | Pipeline |
-|-----------|------|----------|
-| Has REQ-*.md + phase scope | full | verify -> business-test -> review -> test-gen -> test |
-| Default | standard | verify -> review -> test (test-gen if coverage < 80%) |
-| User --quality quick | quick | verify -> review --tier quick |
-
-### A_DECOMPOSE_TASKS
-
-Build the boundary contract + outcome sub-goal checklist, then **register it as a Codex goal via the built-in tool**. Runs once at session creation, before chain build. Skipped when position in {brainstorm, init}.
-
-**1. Classify intent breadth:**
-
-| Pattern | Breadth | Clarify? |
-|---------|---------|----------|
-| 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp | broad | MUST (ignores auto_mode) |
-| named single file/function/bug, "fix X", "add Y to Z" | narrow | skip — auto-derive |
-| otherwise | medium | clarify unless auto_mode |
-
-**2. Clarify boundary** (broad/medium) — `request_user_input`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
-
-| Round | Question | Drives |
-|-------|----------|--------|
-| Scope | 哪些目录/文件/层在范围内?明确排除什么? | boundary_contract.in_scope / out_of_scope |
-| Constraints | 必须向后兼容?公共 API 冻结?行为/性能预算?测试门槛? | boundary_contract.constraints + execution_criteria |
-| Done | 什么可观测结果算"完成"?(如:测试全绿 + 行为零变更 + X 指标) | boundary_contract.definition_of_done |
-
-narrow → derive defaults from intent + codebase, skip questions.
-
-**3. Derive `execution_criteria`** (执行准则 — 3-6 short imperative rules every step obeys): backward-compat stance, scope-freeze ("只改请求范围"), test/coverage bar, fix-don't-hide, incremental commit.
-
-**4. Derive `task_decomposition`** (子目标清单 — outcome-oriented, NOT lifecycle stages). Each entry:
-```json
-{ "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" }
-```
-**Cleverness rule**: `done_when` MUST be objectively verifiable and SHOULD reference an artifact ralph already produces, so `post-goal-audit` can re-verify after context loss. Map each sub-goal to the lifecycle phase(s) producing its evidence — the existing pipeline becomes the machinery that satisfies the goals.
-
-**5. Persist** (additive) into session: `boundary_contract`, `execution_criteria`, `task_decomposition`, `goal_checklist_path` = `{session_dir}/goal-checklist.md`. Write the checklist file (see Appendix: Goal Checklist Template).
-
-**6. Register goal via `create_goal`:**
-```
-create_goal({
-  objective: "Ralph: {intent} — converge all {N} sub-goals within boundary",
-  success_criteria: task_decomposition.map(g => `${g.id}: ${g.done_when}`),
-  constraints: [...execution_criteria, "stay within boundary_contract"]
-})
-```
-Goal stays bound until A_APPLY_GOAL_DONE / A_FINALIZE calls `update_goal`. Skipped feature → no create_goal beyond the default lifecycle goal in A_CREATE_SESSION.
-
-### A_BUILD_STEPS
-
-**Lifecycle stages:**
-
-| Stage | Skill | Barrier | Quality Mode | Decision after |
-|-------|-------|---------|-------------|----------------|
-| brainstorm | maestro-brainstorm "{intent}" | yes | all | — |
-| init | maestro-init | no | all | — |
-| roadmap | maestro-roadmap "{intent}" | yes | all | — |
-| analyze | maestro-analyze {phase} | yes | all | — |
-| plan | maestro-plan {phase} | yes | all | — |
-| execute | maestro-execute {phase} | yes | all | — |
-| verify | maestro-verify {phase} | no | all | post-verify |
-| business-test | quality-auto-test {phase} | no | full only | post-business-test |
-| review | quality-review {phase} | no | all (quick: --tier quick) | post-review |
-| test-gen | quality-auto-test {phase} | no | full; standard if coverage<80% | — |
-| test | quality-test {phase} | no | full, standard | post-test |
-| milestone-audit | maestro-milestone-audit | no | all | — |
-| goal-audit | *(decision-only, no skill)* | — | all (only if decomposed) | post-goal-audit |
-| milestone-complete | maestro-milestone-complete | no | all | post-milestone |
-
-**Build rules:**
-1. Start from `lifecycle_position`, end at `milestone-complete`
-2. Skip stages with existing completed artifacts (check state.json)
-3. Filter stages by `quality_mode` — skip non-applicable stages (see Quality Mode column)
-4. Quick mode: `review` appends `--tier quick`; skips `business-test`, `test-gen`, `test`
-5. Insert decision node after each stage with non-empty Decision column: `{ type: "decision", decision: "<gate>", retry_count: 0, max_retries: 2 }`
-6. **If `task_decomposition` present**: insert a `goal-audit` pure-decision node (no skill) immediately before `milestone-complete` → `decision:post-goal-audit`
-7. Step type for runnable stages = `"skill"` (executed directly in-context, no spawn). `barrier` field retained as optional metadata only — execution is sequential regardless
-8. Args use placeholders `{phase}`, `{intent}`, `{dirs}` — resolved at step execution time
-9. Append `-y` to all skill args when `auto_mode` is true (see -y propagation table in context)
-10. Dynamically-inserted steps (by `post-goal-audit` / fix-loops) carry optional `goal_ref: "G{n}"`
-
-### A_CREATE_SESSION
-
-1. Write `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json` (see Session JSON Schema) — include decomposition fields only if produced (additive)
-2. Initialize tracking:
-   - If decomposed: goal already registered by A_DECOMPOSE_TASKS. Else: `create_goal({ objective: "Ralph lifecycle: {quality_mode} mode, {N} steps from {lifecycle_position}" })`
-   - `update_plan({ plan: steps.map(step => ({ step, status: "pending" })) })`
-3. If decomposed: display sub-goal checklist summary (path + G-ids + done_when). Display chain overview.
-
-### A_EXEC_STEP
-
-Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechanism**.
-
-1. Conditional step eval: `check_coverage` → read validation.json, skip step if ≥ threshold
-2. Resolve `{phase}` / `{intent}` / `{dirs}` placeholders; arg enrichment (plan → `--dir {analysis_dir}`, execute → `--dir {plan_dir}`); append `-y` if auto_mode
-3. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
-4. **Invoke the skill directly**: execute `$skill {resolved_args}` in the coordinator's own context (NO spawn_agents_on_csv, NO worker). Read its produced artifacts directly.
-5. On success: capture summary + artifacts; mark step `status="done"`; update context (analyze→analysis_dir, plan→plan_dir, execute→exec_status, brainstorm→brainstorm_dir, roadmap→spec_session_id)
-6. On failure: mark `status="failed"`; auto_mode → retry once → still failed → S_PAUSED
-7. Persist status.json + `update_plan` after every step
-
-### A_DELEGATE_EVALUATE
-
-1. Resolve result files per decision type (post-verify: verification.json, post-business-test: report.json, post-review: review.json, post-test: uat.md + test-results.json)
-2. Execute `maestro delegate` with analysis prompt → parse verdict: STATUS (proceed/fix/escalate), REASON, GAP_SUMMARY, CONFIDENCE_SCORE, WEAKEST_DIMENSION
-3. Confidence adjustment: score < 60 + proceed → fix; score > 95 + fix + retry > 0 → suggest proceed
-
-### A_GOAL_AUDIT_EVALUATE
-
-Re-checks the goal-checklist and decides whether `steps[]` must dynamically grow. Only runs when `task_decomposition` present.
-
-1. Read `session.task_decomposition` + `goal_checklist_path`
-2. For each sub-goal `status != "done"`: resolve its `evidence` artifact under the current phase scratch dir
-3. Delegate read-only audit:
-   ```
-   maestro delegate "PURPOSE: 审计子目标达成情况，决定是否需要补充执行步骤
-   TASK: 逐个读取未完成子目标的 evidence 产物 | 对照 done_when 判定 met/unmet | 给出每个 unmet 子目标的差距与目标 phase
-   CONTEXT: @{goal_checklist_path} @{evidence artifacts} | 执行准则: {execution_criteria} | 边界: {boundary_contract}
-   EXPECTED: ---VERDICT--- STATUS(all_met|has_unmet) / UNMET=[{id:G2,gap:'...',target_phase:execute}] / CONFIDENCE_SCORE(0-100) ---END---
-   CONSTRAINTS: 只评估不修改 | 严格按 done_when 判定 | 不得超出 boundary_contract"
-   --role analyze --mode analysis
-   ```
-4. On result: parse UNMET. For each met sub-goal → set `task_decomposition[i].status="done"` + flip `[ ]→[x]` in goal-checklist.md
-5. Verdict: `all_met` → A_APPLY_GOAL_DONE; `has_unmet` → A_APPLY_GOAL_FIX
-   GUARD: retry_count >= max_retries AND still unmet → escalate (insert quality-debug, S_PAUSED for human)
-
-### A_STRUCTURAL_EVALUATE
-
-**post-milestone**: Read state.json → next milestone → update session (milestone, phase, reset gates), re-infer quality_mode, insert lifecycle steps. No next → complete.
-**post-debug-escalate**: Pause (always, even -y). Display: max retries reached, manual intervention needed.
-
-### A_INSERT_FIX_LOOP
-
-Insert fix template by decision type after current position, reindex:
-- **post-verify**: debug → plan --gaps → execute → verify → decision:post-verify
-- **post-business-test**: debug --from-business-test → plan --gaps → execute → verify → decision:post-verify → auto-test → decision:post-business-test
-- **post-review**: debug → plan --gaps → execute → verify → decision:post-verify → review → decision:post-review
-- **post-test**: debug --from-uat → plan --gaps → execute → verify → decision:post-verify → [auto-test + decision:post-business-test (full)] → review → decision:post-review → [auto-test (full; standard if <80%)] → test → decision:post-test
-
-### A_APPLY_GOAL_FIX
-
-**Dynamic step-growth core.** For every unmet sub-goal, inject scoped skill steps so `steps[]` grows toward convergence:
-
-1. For each `unmet` sub-goal `G{n}` (grouped by `target_phase` to avoid duplicate runs), insert before the `goal-audit` node a scoped mini-loop (see Appendix: Fix-Loop Templates → post-goal-audit), each inserted step tagged `goal_ref: "G{n}"`, type `"skill"`
-2. Re-append a fresh `decision:post-goal-audit {retry+1}` after inserted steps (re-loops until all met or max retries)
-3. Reindex steps, increment retry_count, persist status.json + `update_plan` (steps[] grew)
-4. Display: ◆ Goal audit: {k} sub-goals unmet → +{N} steps inserted (G{ids}), retry {r}/{max}
-
-### A_APPLY_GOAL_DONE
-
-1. Set all `task_decomposition[*].status="done"`, persist status.json
-2. Append `ALL_GOALS_DONE` sentinel to goal-checklist.md
-3. `update_goal({ status: "complete" })` — releases the decomposition goal constraint
-4. Mark goal-audit decision completed; proceed to `milestone-complete`
-5. Display: ◆ Goal audit: 全部子目标达成 ✓ — goal 已释放
-
-### A_ADVANCE_MILESTONE
-
-Update session: milestone, phase, reset passed_gates. Re-infer quality_mode. Build + insert new lifecycle steps for next milestone (re-append goal-audit before milestone-complete if decomposed).
-
-### A_FINALIZE
-
-1. Set `session.status = "completed"`, write status.json
-2. Sync `update_plan`: all steps → "completed"
-3. `update_goal({ status: "complete" })` — release goal constraint (idempotent if already released by A_APPLY_GOAL_DONE)
-4. Display completion report
-
-### A_PAUSE_SESSION
-
-1. Set `session.status = "paused"`, write status.json
-2. Do NOT call `update_goal` — goal stays bound for `execute`/`continue` resume
-3. Display: use `$maestro-ralph execute` to continue
-
-### A_SHOW_STATUS
-
-1. Find latest ralph session
-2. Display: Session, Status, Position, Quality mode, Progress, Current step
-3. List steps: [✓] done, [▸] running, [ ] pending, [◆] decision (with goal_ref if set)
-4. If `task_decomposition` present: show `Sub-goals: {done}/{total}` + unmet G-ids (graceful skip if absent — backward compat)
-
-</actions>
-
-</state_machine>
-
-<appendix>
-
-### Session JSON Schema
-
-```json
-{
-  "session_id": "ralph-{YYYYMMDD-HHmmss}",
-  "source": "ralph", "intent": "", "status": "running|paused|completed",
-  "lifecycle_position": "", "phase": null, "milestone": null,
-  "auto_mode": false, "quality_mode": "standard", "passed_gates": [],
-  "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null, "analysis_dir": null, "brainstorm_dir": null },
-  "steps": [{ "index": 0, "type": "skill|decision", "skill": "", "args": "", "barrier": false, "status": "pending", "goal_ref": null }],
-  "waves": [], "current_step": 0,
-
-  "_comment": "↓ OPTIONAL additive decomposition block. Absent → no decomposition; readers MUST tolerate missing keys. Never remove/rename above fields.",
-  "boundary_contract": { "in_scope": [], "out_of_scope": [], "constraints": [], "definition_of_done": "" },
-  "execution_criteria": [],
-  "task_decomposition": [
-    { "id": "G1", "goal": "", "boundary": "", "done_when": "", "evidence": "", "lifecycle": [], "status": "pending|done" }
-  ],
-  "goal_checklist_path": ""
-}
-```
-
-> **Extensibility contract (two dimensions)**:
-> 1. **Schema-additive** — decomposition block fields optional; absence = old behavior.
-> 2. **Step-dynamic** — `steps[]` is a living array: `post-goal-audit` (and fix/escalate/milestone decisions) **append/reindex steps at runtime** until sub-goals converge. The JSON "extends" primarily by growing `steps[]`, not by freezing a plan. `goal_ref` (optional, default null) traces dynamically-added steps to the spawning sub-goal. `waves` retained as empty array for backward-compat (no longer populated — spawning removed).
-
-### Goal Checklist Template
-
-Written to `{session_dir}/goal-checklist.md`. Stable within the session; never renamed (so the registered `create_goal` success criteria stay traceable).
-
-```markdown
-# Ralph Goal Checklist — {session_id}
-> Intent: {intent}
-
-## 执行准则 / Execution Criteria
-- {criterion 1}
-- {criterion 2}
-
-## 边界契约 / Boundary Contract
-- In scope: {in_scope}
-- Out of scope: {out_of_scope}
-- Constraints: {constraints}
-- Definition of Done: {definition_of_done}
-
-## 子目标 / Sub-goals
-- [ ] G1: {goal} — done when: {done_when} (evidence: {evidence})
-- [ ] G2: {goal} — done when: {done_when} (evidence: {evidence})
-
-<!-- A_GOAL_AUDIT_EVALUATE flips [ ]→[x] when evidence confirms;
-     A_APPLY_GOAL_DONE appends `ALL_GOALS_DONE` once all [x]. -->
-```
-
-### Fix-Loop Templates
-
-- **post-verify**: `$quality-debug "{gap}"` → `$maestro-plan --gaps {phase}` → `$maestro-execute {phase}` → `$maestro-verify {phase}` → decision:post-verify {retry+1}
-- **post-business-test**: debug --from-business-test → plan --gaps → execute → verify → decision:post-verify {0} → auto-test → decision:post-business-test {retry+1}
-- **post-review**: debug → plan --gaps → execute → review → decision:post-review {retry+1}
-- **post-test**: debug --from-uat → plan --gaps → execute → verify → decision:post-verify {0} → auto-test → decision:post-business-test {0} → review → decision:post-review {0} → auto-test → test → decision:post-test {retry+1}
-- **post-goal-audit** (per unmet sub-goal group — dynamically grows steps[]):
-  ```
-  # for each unmet G{n}, scoped to its target_phase:
-  $maestro-plan --gaps {target_phase} "G{n}: {gap}"   [goal_ref: G{n}]
-  $maestro-execute {target_phase}                      [goal_ref: G{n}]
-  $maestro-verify {target_phase}                       [goal_ref: G{n}]
-  # after all unmet groups inserted:
-  decision:post-goal-audit {retry+1}
-  ```
-  Only unmet sub-goals' phases re-run (no full-pipeline replay); loop exits on `all_met` (→ A_APPLY_GOAL_DONE) or retry max (→ escalate). Growth bounded.
-
-### Error Codes
-
-| Condition | Recovery |
-|-----------|----------|
-| No intent and no running session | Prompt for intent |
-| Cannot infer lifecycle position | Show raw state, ask user |
-| Artifact dir not found for decision | Show glob results, ask user |
-| Delegate verdict parse failed | Fallback: treat as "fix" |
-| Step skill invocation failed | Mark step failed; auto_mode retry once then pause |
-| No session for execute/continue | Suggest $maestro-ralph "intent" |
-
-### Success Criteria
-
-- [ ] Lifecycle position inferred from bootstrap + artifact chain + result files
-- [ ] Quality mode governs step generation
-- [ ] Decomposition runs as initial step; broad intent boundary-clarified via ≤3 questions (ignores auto_mode); narrow auto-derives
-- [ ] Goal registered via built-in `create_goal` with sub-goal success criteria (NOT a user-copied prompt)
-- [ ] status.json enriched additively with boundary_contract + execution_criteria + task_decomposition; absent = old behavior preserved
-- [ ] goal-checklist.md generated with verifiable done_when + ALL_GOALS_DONE sentinel
-- [ ] post-goal-audit decision inserted before milestone-complete (only when decomposed)
-- [ ] Unmet sub-goals DYNAMICALLY grow steps[] via scoped per-goal mini-loops (goal_ref tagged), loop until all_met or max retries → escalate
-- [ ] Skills invoked DIRECTLY in-context — NO spawn_agents_on_csv, NO wave/CSV/worker
-- [ ] Sequential execution; status.json + update_plan persisted after every step and decision
-- [ ] Quality-gate / goal-gate decisions delegate-evaluated via maestro delegate --role analyze
-- [ ] Confidence-based verdict adjustment applied
-- [ ] -y: auto-follow verdict, no STOP (except post-debug-escalate)
-- [ ] update_goal released on convergence (A_APPLY_GOAL_DONE / A_FINALIZE); held while paused
-
-</appendix>
+---
+name: maestro-ralph
+description: Use when the optimal command sequence is unclear and needs automated state-based determination
+argument-hint: "<intent> [-y] | status | continue"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+<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 → execute
+- **`/maestro-ralph continue`** — Resume via maestro-ralph-execute
+- **`/maestro-ralph status`** — Display session progress
+
+Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
+
+Node types:
+- **internal** (default): ralph-execute `Read({command_path})` 命令 .md，按内容内联执行
+- **decision**: 回 ralph 评估
+- **external**: 仅在显式声明时使用（`maestro delegate --to claude`）
+
+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  ◀─┐ internal → Read(command_path) inline
+                              │         │ decision → Skill("maestro-ralph")
+                              └─────────┘ writes step.completion_confirmed
+                       loop until all completion_confirmed | paused
+```
+</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)
+Remaining     → intent
+```
+
+**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. **Ralph never executes steps** — only creates sessions and evaluates decisions
+2. **Handoff via Skill("maestro-ralph-execute")** — at session creation and after decision evaluation
+3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
+4. **Default type = internal** — `external` 仅显式标注时出现，build 不默认生成
+5. **status.json 是唯一真源** — 不生成 markdown 清单或侧文件
+6. **每个 step 必须 `completion_confirmed: true`** — 基于 `--- COMPLETION STATUS ---` 的 `STATUS: DONE`；缺失则视为未完成
+7. **command_path 在 A_BUILD_STEPS 解析** — 全局优先 `~/.claude/commands/{name}.md`，fallback 项目 `.claude/commands/{name}.md`，写入 status.json
+8. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词
+9. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+10. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE_ROUTE     — 解析参数、路由入口                  PERSIST: —
+S_STATUS          — 显示 session 进度                   PERSIST: —
+S_CONTINUE        — 恢复执行                            PERSIST: —
+S_RESOLVE_PHASE   — 解析 phase + phase_is_new + D-007 milestone PERSIST: session.phase, session.phase_is_new, session.milestone
+S_INFER           — 基于已解析 phase 推断 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: —
+S_DISPATCH        — 移交 maestro-ralph-execute           PERSIST: —
+S_DECISION_EVAL   — 委托评估质量门                       PERSIST: —
+S_APPLY_VERDICT   — 应用裁决 + 插入命令                  PERSIST: session.steps[], session.passed_gates[]
+S_FALLBACK        — 请求用户输入                         PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE_ROUTE:
+  → S_STATUS        WHEN: intent == "status"
+  → S_CONTINUE      WHEN: intent == "continue"
+  → S_DECISION_EVAL WHEN: running session with decision step in "running" status
+  → S_RESOLVE_PHASE WHEN: intent is non-empty                  ← phase 必须先于 position
+  → S_FALLBACK      WHEN: no intent AND no running session
+
+S_STATUS:
+  → END             DO: A_SHOW_STATUS
+
+S_CONTINUE:
+  → S_DISPATCH      WHEN: running session found
+  → S_FALLBACK      WHEN: no running session               DO: display "无运行中的 ralph 会话"
+
+S_RESOLVE_PHASE:
+  → S_INFER         WHEN: phase resolved or null            DO: A_RESOLVE_PHASE
+  → S_FALLBACK      WHEN: ambiguous
+                     GUARD: auto_confirm does NOT skip phase ambiguity
+
+S_INFER:
+  → S_RESOLVE_SCOPE WHEN: position resolved                 DO: A_INFER_POSITION
+  → S_FALLBACK      WHEN: cannot infer
+
+S_RESOLVE_SCOPE:
+  → S_QUALITY_MODE  DO: A_RESOLVE_SCOPE_VERDICT
+                     GUARD: position ∈ {brainstorm, blueprint, init} → skip (scope_verdict = null)
+
+S_QUALITY_MODE:
+  → S_PLANNING_MODE DO: A_DETERMINE_QUALITY_MODE
+
+S_PLANNING_MODE:
+  → S_DECOMPOSE     DO: A_DETERMINE_PLANNING_MODE
+                     GUARD: lifecycle_position ∈ {brainstorm, blueprint, init, analyze-macro, roadmap} → skip (force independent)
+
+S_DECOMPOSE:
+  → S_BUILD_CHAIN   DO: A_DECOMPOSE_TASKS
+                     GUARD: broad intent → MUST clarify boundary even if auto_confirm
+                     GUARD: narrow intent → auto-derive, skip questions
+                     GUARD: position ∈ {brainstorm, blueprint, init} → skip decomposition
+
+S_BUILD_CHAIN:
+  → S_CREATE_SESSION DO: A_BUILD_STEPS
+
+S_CREATE_SESSION:
+  → S_CONFIRM       WHEN: not auto_confirm                  DO: A_CREATE_SESSION
+  → S_DISPATCH      WHEN: auto_confirm                      DO: A_CREATE_SESSION
+
+S_CONFIRM:
+  → S_DISPATCH      WHEN: user selects "Proceed"
+  → S_BUILD_CHAIN   WHEN: user selects "Edit"
+  → END             WHEN: user selects "Cancel"
+
+S_DISPATCH:
+  → END             DO: Skill({ skill: "maestro-ralph-execute" })
+
+S_DECISION_EVAL:
+  → S_APPLY_VERDICT WHEN: quality-gate (post-verify, post-business-test, post-review, post-test)
+                     DO: A_DELEGATE_EVALUATE
+  → S_APPLY_VERDICT WHEN: goal-gate (post-goal-audit)
+                     DO: A_GOAL_AUDIT_EVALUATE
+  → S_APPLY_VERDICT WHEN: scope-gate (post-analyze-scope)
+                     DO: A_SCOPE_EVALUATE
+  → S_APPLY_VERDICT WHEN: structural (post-milestone, post-debug-escalate)
+                     DO: A_STRUCTURAL_EVALUATE
+
+S_APPLY_VERDICT:
+  → S_DISPATCH      WHEN: verdict == "proceed"              DO: A_APPLY_PROCEED
+  → S_DISPATCH      WHEN: post-goal-audit + unmet sub-goals  DO: A_APPLY_GOAL_FIX
+  → S_DISPATCH      WHEN: post-goal-audit + all sub-goals met DO: A_APPLY_GOAL_DONE
+  → S_DISPATCH      WHEN: post-analyze-scope                 DO: A_APPLY_SCOPE_VERDICT
+  → S_DISPATCH      WHEN: verdict == "fix"                  DO: A_APPLY_FIX
+  → S_DISPATCH      WHEN: verdict == "escalate"             DO: A_APPLY_ESCALATE
+  → S_DISPATCH      WHEN: post-milestone + next milestone   DO: A_ADVANCE_MILESTONE
+  → END             WHEN: post-milestone + no next milestone DO: mark completed
+  → END             WHEN: post-debug-escalate (always STOP)  DO: A_PAUSE_ESCALATE
+  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
+  GUARD: auto_confirm → skip user prompt, apply adjusted verdict
+  GUARD: not auto_confirm → AskUserQuestion with override options
+
+S_FALLBACK:
+  → S_PARSE_ROUTE   WHEN: user provides input               DO: AskUserQuestion
+  → END             WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_SHOW_STATUS
+
+1. Find latest ralph session (by created_at)
+2. Display: Session, Status, Position, Progress, Current step
+3. List steps: [✓] completion_confirmed, [▸] current, [ ] pending, [◆] decision；附 `command_scope`(global/project) + `command_path`
+4. If `task_decomposition` present (absent → skip):
+   ```
+   Sub-goals  ({done}/{total})    source: {session_dir}/status.json#/task_decomposition
+   [x] G1 done_when={done_when}   evidence={evidence}   confirmed={completion_confirmed}
+   [ ] G2 done_when={done_when}   evidence={evidence}   confirmed=false ◀ unmet
+   ```
+
+### A_RESOLVE_PHASE
+
+前置于 A_INFER_POSITION。产出 `phase` + `phase_is_new` + `milestone`（D-007 反查）三元组。
+
+**Priority:**
+
+| Step | 行为 | phase_is_new |
+|------|------|--------------|
+| 1 | intent 匹配 `phase\s*(\d+)` → 取 state.json 对应 phase | false |
+| 2 | intent 派生短语 → 在 `state.json.milestones[*].phase_slugs` / `artifacts[*].path` 查找 | false (匹配) / true (无匹配) |
+| 3 | 未派生 → 取最新 in-progress artifact 的 phase | false |
+| 4 | 仍无 → state.json 首个 incomplete phase | false |
+| 5 | position 将是 brainstorm/blueprint/init/roadmap/analyze-macro → phase = null | n/a |
+| 6 | 仍模糊 → `AskUserQuestion` | 由用户回答确定 |
+
+**D-007 Phase→Milestone 反查**（数字 phase 已解析时）：
+```
+resolve_milestone(phase_number):
+  for ms in state.json.milestones:
+    if str(phase_number) in ms.phase_slugs: return ms.id
+  return state.json.current_milestone   # fallback
+```
+写入 `session.milestone`；禁止直接使用 `current_milestone` 当做 phase 所属 milestone。
+
+**写入 session**: `phase`, `phase_is_new`, `milestone`。
+
+**新派生 phase 时 milestone 处理**：
+- state.json 当前 milestone 仍 active → 沿用，新增 phase
+- intent 派生新 milestone 名 → 写入 session 仅作标签；`state.json.milestones` 由 `maestro-roadmap` / `maestro-milestone-release` 创建
+
+### A_INFER_POSITION
+
+**Intent-based overrides** (按顺序匹配，先命中先用):
+
+| Pattern | Position |
+|---------|----------|
+| brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
+| blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
+| broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
+
+**Bootstrap detection:**
+
+| Condition | Position |
+|-----------|----------|
+| No `.workflow/` + no source files | `brainstorm` |
+| No `.workflow/` + has source files | `init` |
+| Has `.workflow/` but no state.json | `init` |
+| Has state.json | → phase-aware artifact inference |
+
+**Phase-aware artifact inference** (使用 A_RESOLVE_PHASE 已写入的 `session.phase` + `session.phase_is_new`)：
+
+| Condition | Position |
+|-----------|----------|
+| `phase_is_new == true` (新 phase) | `analyze` |
+| no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` |
+| no milestones AND no roadmap.md AND no analyze artifact | `analyze-macro` |
+| `phase == null` (brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
+| phase 已存在 + 无任何 artifact | `analyze` |
+| phase 已存在 + 最新 artifact = analyze | `plan` |
+| phase 已存在 + 最新 artifact = plan | `execute` |
+| phase 已存在 + 最新 artifact = execute | `verify` |
+| phase 已存在 + 最新 artifact = verify | → refine from result files |
+
+**关键不变量**：artifact 过滤按 `session.phase`，不读 `state.json.current_phase`。`phase_is_new` → 直接 `analyze`。
+
+### A_RESOLVE_SCOPE_VERDICT
+
+仅当 `lifecycle_position ∈ {analyze-macro, roadmap, plan}` 且存在最新 analyze artifact 时执行。
+
+1. 定位最新 macro analyze artifact（`type=="analyze"` 且 `scope=="macro"`，按 created_at DESC）→ 记 `session.analyze_macro_id = ANL-xxx`
+2. 读 `{artifact_path}/conclusions.json` 的 `scope_verdict` 字段（`large | medium | small`）
+3. 写入 `session.scope_verdict`；缺失时设 `unknown`
+4. 路由建议（A_BUILD_STEPS 据此决定是否插入 roadmap、plan 是否走 `--from`）：
+
+| scope_verdict | 链路 |
+|---------------|------|
+| `large` | analyze-macro → roadmap → analyze → plan → execute → ... |
+| `medium` / `small` | analyze-macro → plan --from analyze:{ANL_ID} → execute → ...（跳过 roadmap + analyze-phase） |
+| `unknown` | 默认走 large 路径，post-analyze-scope 决策节点再纠正 |
+
+**Refine from verify results:**
+
+| Condition | Position |
+|-----------|----------|
+| verification.json: passed==false or gaps[] | `verify-failed` |
+| passed==true, no review.json | `business-test` |
+| review.json: verdict=="BLOCK" | `review-failed` |
+| review.json: verdict!="BLOCK" | `test` |
+| uat.md: all passed | `milestone-audit` |
+| uat.md: has failures | `test-failed` |
+
+### A_DETERMINE_QUALITY_MODE
+
+决定下游质量管线长度。读 `session.quality_mode_override`（CLI 标志 `--quality`），无则按规则推断：
+
+| Condition | Mode | Pipeline (verify 之后) |
+|-----------|------|-------------------------|
+| Has `specs/REQ-*.md` + 当前 phase 业务范围明确 | `full` | business-test → review → test-gen → test |
+| Default | `standard` | review → test-gen (当 coverage<80%) → test |
+| `--quality quick` | `quick` | review --tier quick |
+
+写入 `session.quality_mode`。A_BUILD_STEPS 据此过滤 stage（见下）。
+
+### A_DETERMINE_PLANNING_MODE
+
+决定里程碑的规划粒度：一次性规划整个里程碑（统一）还是逐 phase 走完整生命周期（独立）。
+
+**Auto-resolve rules (按优先级):**
+
+| Condition | Mode | Reason |
+|-----------|------|--------|
+| lifecycle_position ∈ {brainstorm, init, roadmap} | `independent` | 前期阶段不涉及多 phase 规划 |
+| `phase_is_new == true` | `independent` | 新 phase 尚无里程碑上下文 |
+| intent 显式指定 phase 编号（如 "phase 2"、"P3"） | `independent` | 用户明确针对单个 phase |
+| milestone 仅含 1 个 phase（读 state.json） | `independent` | 统一无意义 |
+| milestone 含多个 phase + `auto_confirm` | `unified` | 自动模式倾向高效 |
+| milestone 含多个 phase + 非 `auto_confirm` | → AskUserQuestion | 征询用户选择 |
+
+**AskUserQuestion** (仅当 milestone 含 ≥2 phase 且非 auto_confirm):
+
+```
+question: "当前里程碑含 {N} 个 phase，选择规划模式？"
+options:
+  - label: "统一规划 (Recommended)"
+    description: "一次性分析+规划整个里程碑所有 phase，analyze/plan 走里程碑级，适合 phase 间关联紧密"
+  - label: "独立规划"
+    description: "逐个 phase 走完整生命周期（analyze→plan→execute→verify→...），适合 phase 间独立性高"
+```
+
+写入 `session.planning_mode`（`"unified"` 或 `"independent"`）。`A_BUILD_STEPS` 据此决定 skill args 是否携带 `{phase}` 占位符。
+
+### A_DECOMPOSE_TASKS
+
+Runs once before chain build; additive to status.json.
+
+**1. Classify intent breadth:**
+
+| Pattern | Breadth | Clarify? |
+|---------|---------|----------|
+| 重构/全面/重写/重做/整体/迁移 · overhaul/migrate/rewrite/revamp | broad | MUST (ignores auto_confirm) |
+| named single file/function/bug, "fix X", "add Y to Z" | narrow | skip — auto-derive |
+| otherwise | medium | clarify unless auto_confirm |
+
+**2. Clarify boundary** (broad/medium) — `AskUserQuestion`, ≤3 rounds, options pre-filled from intent + a quick Glob/Grep scan of the target module:
+
+| Round | Question | Drives |
+|-------|----------|--------|
+| Scope | 哪些目录/文件/层在范围内?明确排除什么? | boundary_contract.in_scope / out_of_scope |
+| Constraints | 必须向后兼容?公共 API 冻结?行为/性能预算?测试门槛? | boundary_contract.constraints + execution_criteria |
+| Done | 什么可观测结果算"完成"?(如:测试全绿 + 行为零变更 + X 指标) | boundary_contract.definition_of_done |
+
+narrow → derive defaults from intent + codebase, skip questions.
+
+**3. Derive `execution_criteria`**: backward-compat、scope-freeze、test/coverage bar、fix-don't-hide、incremental commit。
+
+**4. Derive `task_decomposition`** (子目标清单 — outcome-oriented, NOT lifecycle stages). Each entry:
+```json
+{ "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" }
+```
+`done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。
+
+**5. Persist** (additive): `boundary_contract`, `execution_criteria`, `task_decomposition`。每个 sub-goal 含 `status: "pending"` + `completion_confirmed: false`。
+
+**6. Stage** the Goal Prompt (Appendix) for A_CREATE_SESSION to emit.
+
+### A_BUILD_STEPS
+
+Generate steps from `session.lifecycle_position` to `milestone-complete`.
+
+| Stage | Skill (independent) | Skill (unified) | Type | Decision after | quality_mode |
+|-------|---------------------|-----------------|------|----------------|--------------|
+| brainstorm | `maestro-brainstorm "{intent}"` | *(same)* | internal | — | all |
+| blueprint | `maestro-blueprint "{intent}"` | *(same)* | internal | — | all |
+| init | `maestro-init` | *(same)* | internal | — | all |
+| analyze-macro | `maestro-analyze "{intent}"` | *(same)* | internal | `post-analyze-scope` | all |
+| roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | internal | — | all |
+| analyze | `maestro-analyze {phase}` | `maestro-analyze` | internal | — | all |
+| plan | `maestro-plan {phase}` *(scope=phase)* / `maestro-plan --from analyze:{analyze_macro_id}` *(scope=standalone)* / `maestro-plan --from blueprint:{blueprint_id}` *(scope=standalone)* | `maestro-plan` | internal | — | all |
+| execute | `maestro-execute {phase}` | `maestro-execute` | internal | — | all |
+| verify | `maestro-verify {phase}` | `maestro-verify` | internal | `post-verify` | all |
+| business-test | `quality-auto-test {phase}` | `quality-auto-test` | internal | `post-business-test` | full only |
+| review | `quality-review {phase}` | `quality-review` | internal | `post-review` | all (quick: append `--tier quick`) |
+| test-gen | `quality-auto-test {phase}` | `quality-auto-test` | internal | — | full / standard if coverage<80% |
+| test | `quality-test {phase}` | `quality-test` | internal | `post-test` | full, standard |
+| milestone-audit | `maestro-milestone-audit` | *(same)* | internal | — | all |
+| goal-audit | *(decision-only)* | *(same)* | decision | `post-goal-audit` | all (only if decomposed) |
+| milestone-complete | `maestro-milestone-complete` | *(same)* | internal | `post-milestone` | all |
+
+**Build rules (按顺序应用):**
+
+0. **planning_mode 选列**：`unified` → Skill (unified) 列；`independent` → Skill (independent) 列
+1. **起点**：从 `session.lifecycle_position` 开始
+2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
+3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
+4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ type: "decision", decision: "<gate>", retry_count: 0, max_retries: 2 }`
+5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/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}`
+9. **command_path 解析**（每个非 decision step）：
+   - 取 skill 名（args 前的第一个 token）
+   - 全局优先：`~/.claude/commands/{name}.md` 存在 → `command_scope = "global"`
+   - Fallback：`.claude/commands/{name}.md` 存在 → `command_scope = "project"`
+   - 两者都缺 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`
+11. **scope_verdict gating**（仅当 chain 起点 = `analyze-macro`）：
+    - `scope_verdict ∈ {medium, small}` → 跳过 `roadmap` + `analyze` 两 stage；`plan` 选 standalone 列（`--from analyze:{analyze_macro_id}`），不带 `{phase}`
+    - `scope_verdict == large` → 保留 `roadmap` + `analyze`；`plan` 选 phase 列（`{phase}`）
+    - `scope_verdict == unknown` → 默认 large 路径；由 `post-analyze-scope` 决策节点在 macro analyze 完成后纠正（A_APPLY_SCOPE_VERDICT）
+12. **--from 自动注入**：
+    - `analyze_macro_id` 存在且当前 step 是 `roadmap` → args 改为 `--from analyze:{analyze_macro_id}`
+    - `analyze_macro_id` 存在且 `scope_verdict ∈ {medium, small}` 且当前 step 是 `plan` → args 改为 `--from analyze:{analyze_macro_id}`
+    - `blueprint_id` 存在 → 当前 step 是 `plan` → args 改为 `--from blueprint:{blueprint_id}`（优先级低于 phase 数字参数）
+    - 写入 `step.source_artifact_ref` 以便审计
+13. **D-007 Milestone-ref 标注**：每个含 `{phase}` 占位符的 step → `step.milestone_id = session.milestone`（由 A_RESOLVE_PHASE 反查得出），禁止读 `current_milestone`
+14. **动态插入步骤**（A_APPLY_*）同样应用规则 7-13
+
+### A_CREATE_SESSION
+
+1. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E006 + 列出缺失 skill
+2. Write `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json` (Appendix: Session Schema)
+3. Display chain overview：每步显示 `{index}. {skill} [{type}] [{command_scope}]`
+4. If `task_decomposition` present: display the **Goal Prompt block** (Appendix: Goal Prompt Template)
+
+### A_DELEGATE_EVALUATE
+
+1. Resolve artifact dir: `.workflow/scratch/{artifact.path}/` with fallback glob
+2. Parse decision metadata: `{ decision, retry_count, max_retries }`
+3. Map result files:
+   | Decision | Files |
+   |----------|-------|
+   | post-verify | verification.json |
+   | post-business-test | .tests/auto-test/report.json |
+   | post-review | review.json |
+   | post-test | uat.md, .tests/test-results.json |
+4. Check artifact for confidence section → include as signal
+5. Execute delegate (run_in_background, STOP, wait for callback):
+   ```
+   maestro delegate "PURPOSE: 评估 {decision} 质量门结果
+   TASK: 读取结果 | 分析状态 | 评估严重性 | 给出建议
+   EXPECTED: ---VERDICT--- STATUS/REASON/GAP_SUMMARY/CONFIDENCE(high|medium|low)/CONFIDENCE_SCORE(0-100)/WEAKEST_DIMENSION ---END---
+   CONSTRAINTS: 只评估 | 置信度<60% 倾向 fix | retry {n}/{max} 达上限必须 escalate"
+   --role analyze --mode analysis
+   ```
+6. On callback: parse verdict; if parse fails → fallback STATUS="fix"
+7. Confidence adjustment: <60 + proceed → fix; >95 + fix + retry>0 → suggest proceed
+8. **Decision log**: Append to `{session_dir}/decisions.ndjson`:
+   ```json
+   { "id": "DEC-{timestamp}", "timestamp": "{ISO}", "source": "ralph",
+     "node_id": "{step.decision}", "type": "quality-gate",
+     "verdict": "{adjusted_verdict}", "confidence_score": {N},
+     "close_call": {N>=50 && N<=70}, "summary": "{REASON}" }
+   ```
+
+### A_STRUCTURAL_EVALUATE
+
+**post-milestone:** Read state.json → next milestone? → insert lifecycle steps / complete
+**post-debug-escalate:** Always STOP → set paused, display "请人工介入"
+
+### A_SCOPE_EVALUATE
+
+仅由 `post-analyze-scope` 决策节点触发；macro analyze 完成后读 `conclusions.json.scope_verdict` 决定下游链路。
+
+1. 定位刚完成的 macro analyze artifact → `analyze_macro_id`, `conclusions_path = {artifact_path}/conclusions.json`
+2. 读取 `conclusions.scope_verdict`（`large | medium | small`），缺失 → `unknown`
+3. 写入 `session.scope_verdict` + `session.analyze_macro_id`
+4. Append `{session_dir}/decisions.ndjson`:
+   ```json
+   { "id": "DEC-{timestamp}", "type": "scope-gate",
+     "source": "ralph", "node_id": "post-analyze-scope",
+     "verdict": "{scope_verdict}", "analyze_macro_id": "{ANL_ID}" }
+   ```
+5. → A_APPLY_SCOPE_VERDICT
+
+### A_GOAL_AUDIT_EVALUATE
+
+Runs only when `task_decomposition` present.
+
+1. Read `session.task_decomposition` from status.json
+2. For each sub-goal `status != "done"`: resolve `evidence` artifact under current phase scratch dir
+3. Delegate read-only audit (run_in_background, STOP, wait):
+   ```
+   maestro delegate "PURPOSE: 审计未完成子目标，判定 met / unmet
+   TASK:
+     1. 读取 status.json.task_decomposition 中 status!=done 的子目标
+     2. 打开 evidence 产物，对照 done_when 严格判定
+     3. 输出 met / unmet，unmet 给出 gap + target_phase
+   CONTEXT:
+     status.json   = {session_dir}/status.json
+     evidence      = {evidence artifacts}
+     execution_criteria = {execution_criteria}
+     boundary_contract  = {boundary_contract}
+   EXPECTED:
+     ---VERDICT---
+     STATUS=all_met|has_unmet
+     UNMET=[{id:G2,gap:'...',target_phase:execute}, ...]
+     CONFIDENCE_SCORE=0-100
+     ---END---
+   CONSTRAINTS:
+     - 只评估，不修改文件
+     - 严格按 done_when 判定；evidence 缺失 → unmet
+     - 不得建议超出 boundary_contract 的修改
+   "
+   --role analyze --mode analysis
+   ```
+4. On callback: 对每个 met 子目标，set `task_decomposition[i].status="done"` + `completion_confirmed=true` + `completed_at=now`
+5. Append `{session_dir}/decisions.ndjson` with `"type": "goal-gate"`, `unmet_count`, `unmet_ids`
+6. Verdict: `all_met` → A_APPLY_GOAL_DONE; `has_unmet` → A_APPLY_GOAL_FIX
+   GUARD: retry_count >= max_retries AND still unmet → A_APPLY_ESCALATE
+
+### A_APPLY_PROCEED
+
+1. Mark decision completed, write status.json
+2. Display: ◆ Decision: {type} → proceed ({reason})
+
+### A_APPLY_FIX
+
+1. Insert fix-loop commands after current step (see Appendix: Fix-Loop Templates)
+2. Reindex steps, increment retry_count, write status.json
+3. Display: ◆ Decision: {type} → fix, +{N} commands inserted
+
+### A_APPLY_ESCALATE
+
+1. Insert `[quality-debug "{gap_summary}", decision:post-debug-escalate]`
+2. Increment retry_count, reindex, write status.json
+
+### A_APPLY_SCOPE_VERDICT
+
+由 `post-analyze-scope` 触发，依据 `session.scope_verdict` 重塑下游链路。
+
+1. 读 `session.scope_verdict`
+2. 路径 A（`large`）：保持当前链；为后续 `roadmap` step 注入 `--from analyze:{analyze_macro_id}`；为后续 `plan` step 选 phase 列；继续推进
+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 列表驱动）
+4. 路径 C（`unknown`）：
+   - 非 auto_confirm → AskUserQuestion 二选一（large / medium-small）；auto_confirm → 默认 large
+5. Reindex steps，标 decision completed，write status.json
+6. Display: ◆ Scope verdict: {verdict} → {kept|collapsed to standalone via analyze:{ANL_ID}}
+
+### A_APPLY_GOAL_FIX
+
+1. 对每个 unmet 子目标 `G{n}`（按 `target_phase` 分组去重）：在 `goal-audit` 节点前插入 scoped mini-loop（见 Appendix: Fix-Loop Templates → post-goal-audit），每条插入 step `goal_ref: "G{n}"`，按 A_BUILD_STEPS 规则 9 解析 `command_path`
+2. 重新追加 `decision:post-goal-audit {retry+1}`
+3. Reindex steps, increment retry_count, write status.json
+4. Display: ◆ Goal audit: {k} unmet → +{N} steps inserted (G{ids}), retry {r}/{max}
+
+### A_APPLY_GOAL_DONE
+
+1. status.json: set 每个 `task_decomposition[*].status="done"`, `completion_confirmed=true`, `completed_at=now`，顶层 `task_decomposition_all_done=true`
+2. Mark goal-audit decision completed；proceed to `milestone-complete`
+3. Display: ◆ Goal audit: all met ✓
+
+### A_ADVANCE_MILESTONE
+
+1. Update session: milestone, phase, reset passed_gates
+2. Insert full lifecycle steps for next milestone
+3. Reindex, write status.json
+
+### A_PAUSE_ESCALATE
+
+1. Set session status = "paused", write status.json
+2. Display: ◆ 已达最大重试次数，debug 已执行。请人工介入。
+3. Display: /maestro-ralph continue 恢复
+
+</actions>
+
+</state_machine>
+
+<appendix>
+
+### Session Schema
+
+```json
+{
+  "session_id": "ralph-{YYYYMMDD-HHmmss}",
+  "source": "ralph", "status": "running",
+  "intent": "", "lifecycle_position": "",
+  "phase": null, "phase_is_new": false,
+  "milestone": "",                // D-007 反查结果，禁止读 current_milestone
+  "auto_mode": false,
+  "quality_mode": "standard",     // "full" | "standard" | "quick"
+  "planning_mode": "independent", // "unified" | "independent"
+  "scope_verdict": null,          // "large" | "medium" | "small" | "unknown" | null
+  "analyze_macro_id": null,       // "ANL-xxx" 来自最新 macro analyze
+  "blueprint_id": null,           // "BLP-xxx" 若存在
+  "cli_tool": "claude", "passed_gates": [],
+  "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null,
+    "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null },
+  "steps": [{
+    "index": 0,
+    "type": "internal|external|decision",
+    "skill": "",
+    "args": "",
+    "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
+    "scope": null,                // "phase"|"standalone"|"milestone"|null（plan 等需要）
+    "command_scope": "global|project|missing|null",
+    "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+    "milestone_id": null,         // D-007 反查注入；仅含 {phase} 占位符的 step 有
+    "source_artifact_ref": null,  // "analyze:ANL-xxx" | "blueprint:BLP-xxx" | null
+    "status": "pending|running|completed|skipped|failed",
+    "goal_ref": null,
+    "completion_confirmed": false,
+    "completion_status": null,
+    "completion_evidence": null,
+    "completed_at": null
+  }],
+  "waves": [], "current_step": 0,
+
+  // Optional decomposition block (additive; absent → decomposition off)
+  "boundary_contract": {
+    "in_scope": [], "out_of_scope": [], "constraints": [], "definition_of_done": ""
+  },
+  "execution_criteria": [],
+  "task_decomposition": [
+    { "id": "G1", "goal": "", "boundary": "", "done_when": "",
+      "evidence": "", "lifecycle": [], "status": "pending|done",
+      "completion_confirmed": false, "completed_at": null }
+  ],
+  "task_decomposition_all_done": false
+}
+```
+
+新增字段可选，缺省=旧行为；既有字段名不删不改。
+
+### Fix-Loop Templates
+
+所有插入 step 默认 `type: "internal"`，按 A_BUILD_STEPS 规则 9 解析 `command_path` + `command_scope`。
+
+**post-verify:**
+```
+quality-debug "{gap_summary}"
+maestro-plan --gaps {phase}
+maestro-execute {phase}
+maestro-verify {phase}
+decision:post-verify {retry+1}
+```
+
+**post-business-test:**
+```
+quality-debug --from-business-test "{gap_summary}"
+maestro-plan --gaps {phase}
+maestro-execute {phase}
+maestro-verify {phase}
+decision:post-verify {retry: 0}
+quality-auto-test {phase}
+decision:post-business-test {retry+1}
+```
+
+**post-review:**
+```
+quality-debug "{gap_summary}"
+maestro-plan --gaps {phase}
+maestro-execute {phase}
+quality-review {phase}
+decision:post-review {retry+1}
+```
+
+**post-test:**
+```
+quality-debug --from-uat "{gap_summary}"
+maestro-plan --gaps {phase}
+maestro-execute {phase}
+maestro-verify {phase}
+decision:post-verify {retry: 0}
+quality-auto-test {phase}
+decision:post-business-test {retry: 0}
+quality-review {phase}
+decision:post-review {retry: 0}
+quality-auto-test {phase}
+quality-test {phase}
+decision:post-test {retry+1}
+```
+
+**post-goal-audit:** (per unmet sub-goal group)
+```
+# for each unmet sub-goal G{n}, scoped to target_phase:
+maestro-plan --gaps {target_phase} "G{n}: {gap}"     [goal_ref: G{n}]
+maestro-execute {target_phase}                       [goal_ref: G{n}]
+maestro-verify {target_phase}                        [goal_ref: G{n}]
+# after all unmet groups inserted:
+decision:post-goal-audit {retry+1}
+```
+
+### Goal Prompt Template
+
+链路概览后逐字显示（仅当 decomposition 已产出）：
+
+```
+📋 任务分解完成。复制下面一行设定目标，会话在子目标全部达成前不停：
+
+/goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
+
+随后运行 /maestro-ralph continue 立即开始执行。
+```
+
+`/goal` 由用户输入；ralph 只输出此提示词。判据以 status.json 为权威。
+
+### Error Codes
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and no running session | Prompt for intent |
+| E002 | error | Cannot infer lifecycle position | Show raw state, ask |
+| E003 | error | Artifact dir not found for decision | Show glob, ask |
+| E004 | error | Delegate verdict parse failed | Fallback: "fix" |
+| E005 | error | Delegate execution failed | Fallback: "fix" |
+| E006 | error | command_scope == "missing" for one or more steps | List missing skills, abort build |
+| W001 | warning | Decision expanded chain | Auto-handled |
+| W002 | warning | Max retries, escalating | Auto-handled |
+| W003 | warning | Multiple running sessions | Use latest, warn |
+| W004 | warning | Low delegate confidence | Show warning |
+
+### Success Criteria
+
+- [ ] Phase 先于 position 解析；phase_is_new 标记写入 session
+- [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
+- [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
+- [ ] Intent overrides 识别 brainstorm / blueprint / analyze-macro
+- [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
+- [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
+- [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路
+- [ ] plan step args 支持三路径：`{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}`，写入 step.source_artifact_ref
+- [ ] roadmap step args 自动注入 `--from analyze:{analyze_macro_id}`（若存在）
+- [ ] artifact 过滤按 session.phase；unified 按 milestone
+- [ ] quality_mode 由 A_DETERMINE_QUALITY_MODE 决定，过滤 build steps
+- [ ] Decomposition: broad intent ≤3 question clarify；narrow auto-derive
+- [ ] status.json 唯一真源：boundary_contract + execution_criteria + task_decomposition；无外部清单
+- [ ] 每个 step 默认 `type: "internal"`，含 `command_scope` + `command_path`（全局优先 fallback 项目）
+- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence`（初始 false/null）
+- [ ] 每个 sub-goal 含 `completion_confirmed`（初始 false）
+- [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前
+- [ ] Unmet sub-goals 动态 grow steps[]（goal_ref tagged）；max retries → escalate
+- [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
+- [ ] Chain 必须以 `milestone-complete` 结尾
+- [ ] Decision nodes 由 maestro delegate --role analyze 评估
+- [ ] Ralph 不执行 step，只 evaluate；Skill("maestro-ralph-execute") handoff
+
+</appendix>