maestro-flow 0.4.15 → 0.4.17

package/.agents/skills/maestro/SKILL.md

@@ -51,11 +51,11 @@ $ARGUMENTS — user intent text, or special keywords.
 3. **Auto flag pass-through** — 仅当用户传入 `-y` 时透传 `-y` 到 skill args
 4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
-6. **执行步骤统一 Read .md 内联** — chain 内每个执行 step 解析 `command_scope`/`command_path`（全局优先 `~/.claude/commands/{name}.md`，fallback 项目），由 ralph-execute `read_file({command_path})` 内联执行；CLI 仅在 decision 节点做只读分析
-7. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro(text) / analyze(numeric phase) / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 路由由 ralph 在 `post-analyze-scope` 决定
-8. **D-007 milestone 反查** — 数字 phase 步骤的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查得出
-9. **每个 step 必须 `completion_confirmed: true`** — 基于 `--- COMPLETION STATUS ---` 的 `STATUS: DONE`
-10. **schema 向后兼容** — 新增字段全部可选；既有字段名不删不改
+6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）；decision 节点不走 CLI，走 `invoke_skill("maestro-ralph")` handoff
+7. **Topology awareness** — chain catalog 含 brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
+8. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
+9. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
+10. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
 </invariants>
 
 <state_machine>
@@ -141,7 +141,7 @@ S_FALLBACK:
    - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
    - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
    - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
-4. 执行 step 解析 `command_scope` + `command_path`（全局优先 fallback 项目）；写入 `step.stage` / `step.scope` / `step.source_artifact_ref`（如 `--from` 注入时）。decision 节点通过 `step.decision` 字段标识
+4. 执行 step：`shell("maestro ralph skills --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
 
@@ -171,30 +171,28 @@ S_FALLBACK:
    ```json
    {
      "session_id", "source": "maestro", "intent", "task_type", "chain_name",
+     "ralph_protocol_version": "1", "active_step_index": null,
      "phase", "phase_is_new": false, "milestone": "",
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
-     "auto_mode": false, "cli_tool": "claude",   // cli_tool: decision 节点 delegate 评估时的 CLI 工具
+     "auto_mode": false, "cli_tool": "claude",
      "context": { "scratch_dir": null, "plan_dir": null, "analysis_dir": null,
        "brainstorm_dir": null, "blueprint_dir": null, "issue_id": null },
      "steps": [{
-       "index": 0,
-       "skill": "", "args": "",
-       "stage": "", "scope": null,
-       "decision": null,                 // 非 null → decision 节点；null → 执行节点
-       "command_scope": "global|project|missing|null",
-       "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+       "index": 0, "skill": "", "args": "",
+       "stage": "", "scope": null, "decision": null,
+       "command_scope": "global|project|missing|null", "command_path": "<abs> | null",
        "milestone_id": null, "source_artifact_ref": null,
        "status": "pending", "goal_ref": null,
        "completion_confirmed": false, "completion_status": null,
-       "completion_evidence": null, "completed_at": null
+       "completion_evidence": null, "completed_at": null,
+       "deferred_reads": [], "load": null
      }],
      "waves": [], "current_step": 0, "status": "running",
      "boundary_contract": {}, "execution_criteria": [],
      "task_decomposition": [], "task_decomposition_all_done": false
    }
    ```
-   Decomposition 字段仅在 A_DECOMPOSE_TASKS 产出时写入（additive）
-3. Validate: 所有 step 的 `command_scope != "missing"`；否则 raise E005 列出缺失 skill
+3. Validate: 所有 step 的 `command_scope != "missing"`，否则 raise E005 列出缺失 skill
 4. Initialize tracking via `track_tasks`
 5. If `--super`: read `maestro-super.md`, follow it completely
 
@@ -228,7 +226,9 @@ S_FALLBACK:
 - [ ] status.json 唯一真源；无 markdown 清单；post-goal-audit 节点在 decomposed 时追加；/goal 提示词以 status.json 为判据
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
-- [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed` 字段；decision step 通过 `step.decision` 字段标识
+- [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识
+- [ ] `command_scope`/`command_path` 由 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global）
+- [ ] Session schema 含 `ralph_protocol_version: "1"` + `active_step_index: null` + step.load 占位
 - [ ] 用户传入 `-y` 时透传到 skill args
 - [ ] All chains dispatched via maestro-ralph-execute
 - [ ] Low-complexity intents routed to maestro-quick

package/.agents/skills/maestro-init/SKILL.md

@@ -73,7 +73,7 @@ Other commands:
 - [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
 - [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
 - [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
-- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
+- [ ] `.workflow/config.json` created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
 - [ ] `.workflow/specs/` initialized with convention files
 - [ ] Research completed (if enabled) — 4 parallel agents spawned
 - [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)

package/.agents/skills/maestro-plan/SKILL.md

@@ -136,18 +136,19 @@ Next steps:
   /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-**Completion status:**
+**Completion (when invoked from ralph):**
+End the step by calling the CLI (no `--- COMPLETION STATUS ---` text block):
 ```
---- COMPLETION STATUS ---
-STATUS: DONE|NEEDS_CONTEXT
-CONCERNS: {description if applicable}
-NEXT: /maestro-execute
---- END STATUS ---
+maestro ralph complete <idx> --status DONE [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
 ```
 
-Status mapping:
-- **DONE** — Plan created/revised and confirmed → NEXT: /maestro-execute
-- **NEEDS_CONTEXT** — Ambiguous requirements, insufficient context to produce plan
+STATUS verdicts (CLI-enforced enum):
+- **DONE** — Plan created/revised and confirmed → next step picks up automatically
+- **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
+- **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
+- **BLOCKED** — External hard blocker (e.g., upstream artifact missing, dependency unavailable); pass `--reason "..."`
+
+> Ambiguous requirements are NOT a completion status — resolve them in-place via `ask_user` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
 
 ### Mode: Revise / Check
 

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

@@ -28,7 +28,7 @@ Entry points:
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Step kinds:
-- **执行 step**: ralph-execute `read_file({command_path})` 命令 .md，按内容内联执行
+- **执行 step**: ralph-execute 调 `shell("maestro ralph next")` 加载 command .md + required_reading 全文，按 stdout 内联执行
 - **decision step**: `step.decision` 字段非空；回 ralph 评估（CLI 只读分析）
 
 Key difference from maestro coordinator:
@@ -46,9 +46,9 @@ Mutual invocation with `/maestro-ralph-execute` forms a self-perpetuating work l
                               │           writes status.json
                               │           emits /goal prompt
                               ▼
-                       ralph-execute  ◀─┐ 执行 step → read_file(command_path) inline
+                       ralph-execute  ◀─┐ 执行 step → `maestro ralph next` + inline + `ralph complete`
                               │         │ decision step → invoke_skill("maestro-ralph")
-                              └─────────┘ writes step.completion_confirmed
+                              └─────────┘ CLI writes step.completion_confirmed
                        loop until all completion_confirmed | paused
 ```
 </purpose>
@@ -73,11 +73,11 @@ Remaining     → intent
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
 2. **Handoff via invoke_skill("maestro-ralph-execute")** — 创建 session 后始终自动 handoff；decision 评估后始终 handoff
 3. **Decision delegates read-only** — `maestro delegate --role analyze --mode analysis`
-4. **执行 step 通过 Read 命令 .md 内联执行**
+4. **执行 step 通过 `maestro ralph next` CLI 加载并内联执行**（详见 invariant 8）
 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. **执行 step 加载契约** — ralph-execute 读 `command_path` 后，必须解析并加载该命令 `<required_reading>` 引用的所有文件（"入口 + workflow"形式的核心），并把 `<deferred_reading>` 路径记录到 `step.deferred_reads`；加载完成后输出 `✓ skill {name} 加载完成`。ralph 在 build 阶段只解析路径，不读 .md 内容
+6. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE`（或 DONE_WITH_CONCERNS）写入；CLI 是唯一合法写入路径
+7. **command_path 在 A_BUILD_STEPS 解析** — 通过 `maestro ralph skills --json --quiet` 预校验（project 覆盖 global），命中即写绝对路径到 status.json；未命中标 `command_scope = "missing"`
+8. **执行 step 加载契约** — 由 `maestro ralph next` CLI 在执行期完成：解析 frontmatter + `<required_reading>` + `<deferred_reading>`，自动读取 required 文件全文并拼入 prompt；缺失 required → 退出码 1（E007），pause session。ralph build 阶段只通过 `maestro ralph skills` 校验路径存在性，不读 .md 内容
 9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 输出提示词后继续 handoff，用户可在执行过程中随时输入 `/goal`
 10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
@@ -399,7 +399,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 | goal-audit | *(decision-only)* | *(same)* | `post-goal-audit` | all (only if decomposed) |
 | milestone-complete | `maestro-milestone-complete` | *(same)* | `post-milestone` | all |
 
-> 所有执行 stage 统一通过 Read .md 内联执行；decision 节点单独作为独立 step 插入（见规则 4）。
+> 所有执行 stage 统一通过 `maestro ralph next` CLI 加载 + 内联执行；decision 节点单独作为独立 step 插入（见规则 4）。
 
 **Build rules (按顺序应用):**
 
@@ -414,11 +414,12 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
    - 取 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
-   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 ralph-execute A_EXEC_STEP 负责（保持入口/工作流分离）
-10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`
+   - **预校验通过 `shell("maestro ralph skills --json --quiet")`** 一次性拉取所有可用 commands + skills（global + project，project 覆盖 global），匹配 skill 名得到：
+     - 命中 commands → `command_scope = "global" | "project"`，`command_path = <绝对路径>`
+     - 命中 skills → 同上（type=skill）
+     - 未命中 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
+   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 `maestro ralph next` CLI 在执行期完成
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`, `load: null`（由 `ralph next` 写入）
 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}`）
@@ -597,6 +598,8 @@ Runs only when `task_decomposition` present.
 {
   "session_id": "ralph-{YYYYMMDD-HHmmss}",
   "source": "ralph", "status": "running",
+  "ralph_protocol_version": "1",   // CLI-driven; absent/0 → legacy inline ralph-execute
+  "active_step_index": null,       // CLI-managed; only one step held at a time
   "intent": "", "lifecycle_position": "",
   "phase": null, "phase_is_new": false,
   "milestone": "",                // D-007 反查结果，禁止读 current_milestone
@@ -619,7 +622,7 @@ Runs only when `task_decomposition` present.
     "retry_count": 0,             // decision 节点专用
     "max_retries": 2,             // decision 节点专用
     "command_scope": "global|project|missing|null",  // 执行 step；decision 节点固定 null
-    "command_path": "~/.claude/commands/{name}.md | .claude/commands/{name}.md | null",
+    "command_path": "<absolute path resolved by `maestro ralph skills --json --quiet`> | 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",
@@ -628,7 +631,8 @@ Runs only when `task_decomposition` present.
     "completion_status": null,
     "completion_evidence": null,
     "completed_at": null,
-    "deferred_reads": []          // 由 ralph-execute A_EXEC_STEP 解析 .md 时填充
+    "deferred_reads": [],         // 由 ralph next CLI 解析 .md 时填充
+    "load": null                  // { loaded_at, required_files[], deferred_files[], resolve_version } —— 由 ralph next 写入
   }],
   "waves": [], "current_step": 0,
 
@@ -749,8 +753,8 @@ decision:post-goal-audit {retry+1}
 - [ ] 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 含 `command_scope` + `command_path`（全局优先 fallback 项目）；decision step 通过 `step.decision` 字段标识
-- [ ] Ralph build 阶段只解析路径，不读 .md 内容；`<required_reading>` 加载由 ralph-execute A_EXEC_STEP 完成
+- [ ] 执行 step 含 `command_scope` + `command_path`（通过 `maestro ralph skills --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
+- [ ] Ralph build 阶段只通过 `ralph skills` 校验路径存在性，不读 .md 内容；`<required_reading>` 加载由 `maestro ralph next` CLI 完成
 - [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 false/null/[]）
 - [ ] 每个 sub-goal 含 `completion_confirmed`（初始 false）
 - [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前