maestro-flow 0.4.15 → 0.4.16

package/.claude/commands/maestro-ralph-execute.md

@@ -34,24 +34,24 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 | Kind | Identifier | Execution | Flow after |
 |------|-----------|-----------|------------|
 | decision step | `step.decision` 非空 | `Skill("maestro-ralph")` | Execution ends here |
-| 执行 step | `step.decision == null` | `Read({file_path: step.command_path})` + 内联解释执行 | Self-invoke next |
+| 执行 step | `step.decision == null` | `Bash("maestro ralph next")` → 内联按其 stdout 执行 → `Bash("maestro ralph complete N --status ...")` | Self-invoke next |
 
 HARD RULES:
-- 执行 step：通过 `Read({command_path})` 把命令 .md 加载进当前会话，再按内容执行
-- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；缺失 required_reading 视为加载失败
-- decision step：A_EXEC_DECISION 通过 `Skill({ skill: "maestro-ralph" })` handoff 给 ralph 评估
-- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（缺失 → 报错 E002）
-- 每个 step 必须产出 `--- COMPLETION STATUS ---` 块，否则视为 NEEDS_RETRY
+- 执行 step：**统一通过 `maestro ralph next` CLI 加载**。CLI 负责读 command_path、解析 `<required_reading>` + `<deferred_reading>`、拼接 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`。不要再在会话里手动 Read + 解析 required_reading
+- decision step：A_EXEC_DECISION 通过 `Skill({ skill: "maestro-ralph" })` handoff 给 ralph 评估（不走 CLI）
+- `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（缺失 → ralph next 返回 E006/E007 并拒绝执行）
+- 每个 step 结束必须调用 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`。STATUS 仅 4 个合法值：`DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`（**`NEEDS_CONTEXT` 已废除**，context 容量由 harness 自动压缩处理）
 </context>
 
 <invariants>
-1. **执行 = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
-2. **Required reading must be loaded** — 命令 .md 中的 `<required_reading>` 引用的所有文件必须立即 Read；缺一 → 视为加载失败，pause session（E007）
-3. **Deferred reading recorded only** — `<deferred_reading>` 列出的文件路径需记录，执行过程按需 Read；不在加载阶段读取
-4. **Skill loaded confirmation** — 所有 required_reading 加载完成后必须输出一行确认：`✓ skill {step.skill} 加载完成 (required: N, deferred: M)`
-5. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+1. **执行 = `ralph next` + inline + `ralph complete`** — 调 `maestro ralph next` 拿到 skill 内容，按 stdout 内联执行
+2. **Required reading 由 CLI 负责** — `ralph next` 自动展开 + 加载 `<required_reading>` 引用的所有文件，缺失 → 退出码 1（E007），不写 active_step_index，不进入执行
+3. **Deferred reading recorded only** — `<deferred_reading>` 路径由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
+4. **一致性取代锁** — 同一 session 同时最多一个 step 持 `active_step_index`；CLI 校验失败直接退出码 3，不静默推进
+5. **Completion 通过 CLI 调用** — 每个 step 末尾调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`，由 CLI 写 `completion_*` + 清 `active_step_index`
 6. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-7. **status.json 每步骤后写盘** — resume-safe
+7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
+8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
 </invariants>
 
 <state_machine>
@@ -78,11 +78,12 @@ S_RESOLVE_ARGS:
 
 S_EXECUTE:
   → END             WHEN: step.decision != null              DO: A_EXEC_DECISION
-  → S_POST_EXEC     WHEN: step.decision == null + success    DO: A_EXEC_STEP
-  → S_HANDLE_FAIL   WHEN: step.decision == null + failure    DO: A_EXEC_STEP
+  → S_POST_EXEC     WHEN: step.decision == null + ralph complete invoked with DONE|DONE_WITH_CONCERNS  DO: A_EXEC_STEP
+  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit≠0 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
 
 S_POST_EXEC:
-  → S_LOCATE        DO: A_MARK_COMPLETE + Skill("maestro-ralph-execute")
+  → S_LOCATE        DO: Bash("maestro ralph complete ...") + Skill("maestro-ralph-execute")
+                     NOTE: CLI 已写完 completion_*, status, active_step_index；无需额外写盘
 
 S_HANDLE_FAIL:
   → S_LOCATE        WHEN: auto + not retried               DO: A_RETRY
@@ -105,8 +106,8 @@ S_FALLBACK:
 
 1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
 2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
-3. Extract: session_id, source, steps[], current_step, phase, milestone, intent, auto_mode, context, cli_tool
-4. Find first step with `status == "pending"` → next step
+3. Extract: session_id, source, steps[], phase, milestone, intent, auto_mode, context, cli_tool, active_step_index
+4. **不在此处选 pending step**——pending 选择由 `maestro ralph next` CLI 内部完成；A_LOCATE_SESSION 只确认 session 存在且 running，由 A_EXEC_STEP 调 CLI 推进
 
 ### A_RESOLVE_ARGS
 
@@ -154,54 +155,35 @@ Write enriched args back to status.json.
 
 ### A_EXEC_STEP
 
-1. Validate `step.command_path != null`；否则 raise E002，pause session
-2. Mark step running, write status.json
-3. Display: `[{index}/{total}] {step.skill} [{step.command_scope}]`
-4. `Read({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话
-5. **解析 reading 标签**（"入口 + workflow"形式核心步骤）：
-   - 抽取 frontmatter `argument-hint` / `allowed-tools`
-   - 抽取 `<required_reading>` 块的所有 `@path` 引用 → 立刻 `Read({ file_path: <expanded path> })` 加载（`~/` / `@~/` 展开为用户主目录）；任一文件缺失或读取失败 → raise E007，pause session
-   - 抽取 `<deferred_reading>` 块的所有路径 → 仅记录到 `step.deferred_reads = [...]`，执行阶段按需 Read
-   - 抽取 `<purpose>/<context>/<state_machine>/<execution>/<actions>` 等指令块
-6. **加载完成确认**：required_reading 全部成功 Read 后，输出一行：
-   ```
-   ✓ skill {step.skill} 加载完成 (required: {N}, deferred: {M})
-   ```
-   其中 N = required_reading 引用数，M = deferred_reading 路径数（缺省块按 0 计）
-7. 计算 `effective_args`：`step.args` + (`auto ? " -y" : ""`)
-8. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作；执行过程中如触发 deferred_reading 引用的资源 → 按需 Read
-9. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-10. Return success / failure
-
-### A_MARK_COMPLETE
-
-1. 从 step 输出中提取 `--- COMPLETION STATUS ---` 块（required）
-2. 解析并写入：
-   - `STATUS: DONE` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE"`
-   - `STATUS: DONE_WITH_CONCERNS` → `step.status = "completed"`, `step.completion_confirmed = true`, `step.completion_status = "DONE_WITH_CONCERNS"`, `step.concerns = <CONCERNS>`
-   - `STATUS: NEEDS_RETRY` → `step.status = "pending"`, `step.retried = true`, `step.completion_confirmed = false`, → S_HANDLE_FAIL
-   - `STATUS: BLOCKED` / `NEEDS_CONTEXT` → `session.status = "paused"`, `step.completion_status` 记录原因, `step.completion_confirmed = false`
-   - 缺失 `--- COMPLETION STATUS ---` 块 → 视为 NEEDS_RETRY（不允许 heuristic fallback）
-3. 写入 `step.completion_evidence`（artifact 路径 / 关键输出节选）
-4. 扫描输出抓取 context 信号：`PHASE: N` → session.phase；`scratch_dir: path` → context.scratch_dir；`BLP-xxx` → context.blueprint_session_id
-5. `step.completed_at = now`，写 status.json
-6. **Sub-goal evidence 校验**（task_decomposition 存在时）：若 `step.goal_ref` 对应子目标的 `lifecycle` 覆盖当前 stage 且 evidence artifact 已生成 → 暂不直接置 done，仍交由 post-goal-audit 决策；仅在 step 显式确认时更新 `task_decomposition[*].completion_confirmed = false` 占位（保持 pending）
-7. Display: `[{index}/{total}] ✓ {step.skill} completed (confirmed)`
+1. **Load** — `Bash("maestro ralph next")`
+   - 退出码 0 → 按 stdout 内联执行
+   - 退出码 2 → 交给 S_LOCATE
+   - 退出码 3 → active_step_index 已被占用
+   - 退出码 1 → pause session
+2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
+3. **Complete**:
+   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
+   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `Bash("maestro ralph retry N")`
+   - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+
+完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
 
 ### A_RETRY
 
-1. `step.retried = true`, `step.status = "pending"`, `step.error = null`, `step.completion_confirmed = false`
-2. Write status.json
+1. `Bash("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`
+2. Display: `[{index}/{total}] ↻ {step.skill} retry`
 
 ### A_SKIP_STEP
 
-1. `step.status = "skipped"`, `step.completion_confirmed = false`
-2. Write status.json
+跳过执行 step — 手动编辑 `status.json`：将该 step `status` 设为 `"skipped"`，`completion_confirmed` 设为 `false`，并清 `active_step_index`（若指向此 step）。
+（不提供 CLI 子命令；跳过是非常规操作，避免自动化误用。）
 
 ### A_PAUSE_SESSION
 
-1. `session.status = "paused"`, write status.json
-2. Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
+通常由 `ralph complete N --status BLOCKED --reason "..."` 触发，CLI 已写 `session.status = "paused"`。手动 pause 场景下直接编辑 status.json。
+Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro-ralph continue 恢复。`
 
 ### A_COMPLETE_SESSION
 
@@ -236,29 +218,30 @@ Write enriched args back to status.json.
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
 | E001 | error | No running session found | Suggest /maestro or /maestro-ralph |
-| E002 | error | step.command_path missing for 执行 step | Pause, ask ralph to rebuild step |
-| E003 | error | status.json corrupt | Show path, manual check |
-| E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
-| E007 | error | required_reading file 缺失或读取失败 | List missing paths, pause session |
+| E006 | error | command_path missing/unreachable for 执行 step | `ralph next` 拒绝；编辑 status.json 或重 build |
+| E007 | error | required_reading 引用文件缺失 | `ralph next` 拒绝；CLI stderr 列出缺失路径 |
+| E008 | error | `ralph complete` idx ≠ active_step_index | 编辑 status.json 修正一致性 |
+| E009 | error | `ralph complete` step.status ≠ running | 重复 complete 或非法跳跃；编辑 status.json |
+| E010 | error | status.json schema 损坏 | `ralph check` 显示具体损坏字段 |
 | W001 | warning | Step completed with concerns | Log and continue |
-| W002 | warning | command .md 无 `<required_reading>` 标签 | 直接执行 .md 主体，跳过加载阶段 |
+| W005 | warning | active_step_index 指向已 completed step | `ralph next` 自动清理后继续 |
+| W007 | warning | step.skill ≠ command .md frontmatter.name | 提示但不阻塞 |
 
 ### Success Criteria
 
 - [ ] Session discovery covers maestro-* and ralph-*
 - [ ] `-y` parsed from args 或 session.auto_mode；auto=true 时透传 `-y` 到 skill args
 - [ ] Placeholders resolved；per-skill enrichment 正确
-- [ ] Decision 节点（`step.decision != null`）Skill("maestro-ralph") handoff
-- [ ] 执行 step 通过 Read({step.command_path}) 内联执行
-- [ ] 执行 step Read 后必须解析并加载 `<required_reading>` 引用的文件；缺失 → E007 pause
-- [ ] `<deferred_reading>` 仅记录路径到 `step.deferred_reads`，执行阶段按需 Read
-- [ ] required_reading 加载完成后输出 `✓ skill {name} 加载完成 (required: N, deferred: M)`
-- [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
-- [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置
-- [ ] step.completion_evidence 记录 artifact path / 输出节选
-- [ ] Context signals 传播 status.json
+- [ ] Decision 节点（`step.decision != null`）走 Skill("maestro-ralph") handoff（**不调 ralph next CLI**）
+- [ ] 执行 step 通过 `Bash("maestro ralph next")` 加载；CLI 返回拼好的 prompt + completion 协议
+- [ ] required_reading 由 CLI 自动加载并拼入 prompt；缺失 → CLI 退出码 1，pause session
+- [ ] `<deferred_reading>` 由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read
+- [ ] 每个 step 末尾必须调 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`
+- [ ] STATUS 枚举仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；CLI 拒绝 `NEEDS_CONTEXT`
+- [ ] active_step_index 一致性由 CLI 维护；E008/E009 直接退出，不静默推进
+- [ ] step.completion_evidence 通过 `--evidence` 传入并记录
+- [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
-- [ ] A_COMPLETE_SESSION 校验全部 step confirmed + sub-goal all_done
 
 </appendix>

package/.claude/commands/maestro-ralph.md

@@ -26,7 +26,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({command_path})` 命令 .md，按内容内联执行
+- **执行 step**: ralph-execute 调 `Bash("maestro ralph next")` 加载 command .md + required_reading 全文，按 stdout 内联执行
 - **decision step**: `step.decision` 字段非空；回 ralph 评估（CLI 只读分析）
 
 Key difference from maestro coordinator:
@@ -44,9 +44,9 @@ Mutual invocation with `/maestro-ralph-execute` forms a self-perpetuating work l
                               │           writes status.json
                               │           emits /goal prompt
                               ▼
-                       ralph-execute  ◀─┐ 执行 step → Read(command_path) inline
+                       ralph-execute  ◀─┐ 执行 step → `maestro ralph next` + inline + `ralph complete`
                               │         │ decision step → Skill("maestro-ralph")
-                              └─────────┘ writes step.completion_confirmed
+                              └─────────┘ CLI writes step.completion_confirmed
                        loop until all completion_confirmed | paused
 ```
 </purpose>
@@ -71,11 +71,11 @@ Remaining     → intent
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
 2. **Handoff via 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；字段可选/累加，既有字段不删不改
@@ -397,7 +397,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 (按顺序应用):**
 
@@ -412,11 +412,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: []`
+   - **预校验通过 `Bash("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}`）
@@ -595,6 +596,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
@@ -617,7 +620,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",
@@ -626,7 +629,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,
 
@@ -747,8 +751,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 之前

package/.claude/commands/maestro.md

@@ -49,11 +49,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({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，走 `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>
@@ -139,7 +139,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：`Bash("maestro ralph skills --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
 
@@ -169,30 +169,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 `TodoWrite`
 5. If `--super`: read `maestro-super.md`, follow it completely
 
@@ -226,7 +224,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/.claude/commands/manage-knowledge-audit.md

@@ -0,0 +1,88 @@
+---
+name: manage-knowledge-audit
+description: Audit and prune knowledge across spec / knowhow / artifact stores
+argument-hint: "--scope <spec|knowhow|artifact|all> [--level P0|P1|P2] [--timeline T1..T6] [--since YYYY-MM-DD] [--milestone <name>] [--include-archive] [--interactive] [--mark|--delete|--purge] [--dry-run] [--report]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+对称于 `manage-harvest`（写入入口）的知识淘汰入口。harvest 负责把 artifact 抽取为 spec/wiki/issue；audit 负责审查这三大存储中已积累的条目，识别矛盾、失效、老化、孤儿，并通过 keep/deprecate/delete 三态决策清理。
+
+覆盖 8 大场景类、28 子场景（显性/隐性矛盾、失效老化、元数据质量、Maestro 特化、时间线产物 T1-T6、knowhow 漂移、artifact 残留），定义见 workflow knowledge-audit.md。
+
+**闭环**：harvest 写入 → audit 审查 → 三态淘汰；与 `harvest --prune`（物理 GC）互补：audit 做语义层判定，且删除未抽取的 artifact 前反向触发 harvest 抢救。
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/knowledge-audit.md
+</required_reading>
+
+<deferred_reading>
+- @~/.maestro/workflows/harvest.md (audit 检测的 artifact 是 harvest 的产物源)
+- @~/.maestro/workflows/specs-add.md (deprecate 操作所需的 `<spec-entry>` 变形)
+</deferred_reading>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope（必选）：** `spec` | `knowhow` | `artifact` | `all`
+
+**删除策略**默认 `--interactive`（三态面板逐项决策）；非交互模式 `--mark`（仅打标）/ `--delete`（软删到 `.trash/`）/ `--purge`（物理擦除，仅 artifact 且需双重确认）。
+
+Flag 全集、scope 对应的扫描路径、Stage 步骤、检测算法定义在 workflow knowledge-audit.md。
+</context>
+
+<execution>
+Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
+
+**Key invariants:**
+1. **Backup before mutate** — Stage 6 必须把待变更文件打包到 `.workflow/.trash/knowledge-audit-{timestamp}/`，备份失败禁止 Stage 7。
+2. **Deprecate over delete** — 文本存储（spec/knowhow）首选注入 `status="deprecated"` 保留历史；只有 artifact 物理残留才走 delete/purge。
+3. **Purge requires double confirmation** — `--purge` 仅作用于 artifact scope，且 Stage 5 必须显式 `[y/N]` 二次确认 + 输入 artifact id。
+4. **Rescue before delete** — 删除未抽取的 artifact 前（`harvest-log.jsonl` 无记录），强制提示 "是否先 `/manage-harvest`？"。
+
+Scope 路径、8 类检测算法、三态决策面板、报告 schema 定义在 workflow knowledge-audit.md。
+
+**Next-step routing on completion:**
+- 复审淘汰记录 → `.workflow/.knowledge-audit/audit-report-{date}.md`
+- 抢救未抽取 artifact → `/manage-harvest <artifact-id>`
+- 验证 spec 现状 → `/spec-load --role implement`
+- 周期巡检 → 每 milestone 结束跑 `--scope all --report`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | `.workflow/` 未初始化 | 先跑 `/maestro-init` |
+| E002 | error | `--scope` 缺失或非法 | 提供 spec/knowhow/artifact/all |
+| E003 | error | `--purge` 与 `--dry-run` 同用 | 二选一 |
+| E004 | error | `--purge` 作用于非 artifact 范围 | purge 仅支持 artifact scope |
+| E005 | error | 备份失败（`.trash/` 写入异常） | 检查磁盘空间与权限，重试 |
+| W001 | warning | 检出冲突但用户选择 keep | 记入 report，不阻断 |
+| W002 | warning | 待删 artifact 无 harvest-log 记录 | 提示先跑 manage-harvest |
+| W003 | warning | 循环 supersedes 链 | 自动断环或交互选保留节点 |
+| W004 | warning | 检测耗时 >120s（大规模 spec 库） | 建议加 `--scope` 收敛或 `--since` 增量 |
+| W005 | warning | LLM detector 不可用 | 降级到正则+图算法子集，跳过 B/G 类语义场景 |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope 正确解析，互斥标志校验通过
+- [ ] 三存储按 scope 加载完成，构建出统一 finding 池
+- [ ] Stage 3 时间线索引建立（mtime ↔ session/milestone 状态）
+- [ ] Stage 4 按 P0/P1/P2 输出 finding 列表
+- [ ] 如非 `--report`：用户对每项做出三态决策
+- [ ] 未 harvest 的 artifact 删除前触发抢救确认
+- [ ] Stage 6 backup tarball 生成于 `.workflow/.trash/`
+- [ ] `deprecate` 通过元数据注入完成（spec/knowhow 文件未被物理删除）
+- [ ] `delete` 移动至 `.trash/`，索引同步更新
+- [ ] `purge` 仅在双重确认通过后执行
+- [ ] `audit-report-{date}.md` + `audit-log.jsonl` 写入完成
+- [ ] 摘要展示三存储变更计数与下一步路由
+</success_criteria>

package/dist/src/cli.js

@@ -36,6 +36,7 @@ const commandLoaders = {
     wiki: async () => (await import('./commands/wiki.js')).registerWikiCommand,
     hooks: async () => (await import('./commands/hooks.js')).registerHooksCommand,
     coordinate: async () => (await import('./commands/coordinate.js')).registerCoordinateCommand,
+    ralph: async () => (await import('./commands/ralph.js')).registerRalphCommand,
     launcher: async () => (await import('./commands/launcher.js')).registerLauncherCommand,
     delegate: async () => (await import('./commands/delegate.js')).registerDelegateCommand,
     'agent-msg': async () => (await import('./commands/msg.js')).registerMsgCommand,

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/font-guide.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from 'commander';
+interface PlatformGuide {
+    os: 'linux' | 'darwin' | 'win32' | 'unknown';
+    detected: boolean | null;
+    lines: string[];
+}
+export declare function getNerdFontGuide(font?: string): PlatformGuide;
+/** Print the font guide to stderr (matches install command output style). */
+export declare function printNerdFontGuide(font?: string): void;
+/** Register `maestro install fonts` standalone subcommand. */
+export declare function registerFontsSubcommand(install: Command): void;
+export {};
+//# sourceMappingURL=font-guide.d.ts.map

package/dist/src/commands/font-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-guide.d.ts","sourceRoot":"","sources":["../../../src/commands/font-guide.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,UAAU,aAAa;IACrB,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAiBD,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAqB,GAAG,aAAa,CAqD3E;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAqB,GAAG,IAAI,CAqBpE;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAQ9D"}