maestro-flow 0.4.13 → 0.4.14

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

@@ -14,7 +14,7 @@ allowed-tools:
 <!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
 
 <purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
 </purpose>
 
 <required_reading>
@@ -32,7 +32,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/brainstorm-{slug}-{YYYYMMDD}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 **Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).

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

@@ -19,10 +19,12 @@ 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 "intent"`** — New session: infer → decompose → build → (decomposition → emit /goal prompt, STOP；否则 dispatch ralph-execute)
+- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
 - **`/maestro-ralph status`** — Display session progress
 
+> 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `invoke_skill("maestro-ralph")` handoff，无需用户手动切换。
+
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Node types:
@@ -70,15 +72,16 @@ Remaining     → intent
 
 <invariants>
 1. **Ralph never executes steps** — only creates sessions and evaluates decisions
-2. **Handoff via invoke_skill("maestro-ralph-execute")** — at session creation and after decision evaluation
+2. **Handoff via invoke_skill("maestro-ralph-execute")** — 仅当 session 无 `task_decomposition` 时在创建后自动 handoff；decomposition 路径 STOP 等用户输入。decision 评估后始终 handoff
 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；字段可选/累加，既有字段不删不改
+8. **Internal step 加载契约** — ralph-execute 读 `command_path` 后，必须解析并加载该命令 `<required_reading>` 引用的所有文件（"入口 + workflow"形式的核心），并把 `<deferred_reading>` 路径记录到 `step.deferred_reads`；加载完成后输出 `✓ skill {name} 加载完成`。ralph 在 build 阶段只解析路径，不读 .md 内容
+9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词后 STOP，等用户输入
+10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 </invariants>
 
 <state_machine>
@@ -148,8 +151,9 @@ 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
+  → END             WHEN: task_decomposition present        DO: A_CREATE_SESSION (emits Goal Prompt → STOP，等用户输入 /goal 后手动 /maestro-ralph-execute)
+  → S_CONFIRM       WHEN: not auto_confirm AND no decomposition DO: A_CREATE_SESSION
+  → S_DISPATCH      WHEN: auto_confirm AND no decomposition  DO: A_CREATE_SESSION
 
 S_CONFIRM:
   → S_DISPATCH      WHEN: user selects "Proceed"
@@ -413,7 +417,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    - 全局优先：`~/.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`
+   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 ralph-execute A_EXEC_INTERNAL 负责（保持入口/工作流分离）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`
 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}`）
@@ -431,7 +436,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 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)
+4. If `task_decomposition` present: display **Goal Prompt block** (Appendix) → STOP，等用户输入 `/goal`（auto_confirm 也不跳过）
 
 ### A_DELEGATE_EVALUATE
 
@@ -620,7 +625,8 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
-    "completed_at": null
+    "completed_at": null,
+    "deferred_reads": []          // 由 ralph-execute A_EXEC_INTERNAL 解析 .md 时填充
   }],
   "waves": [], "current_step": 0,
 
@@ -704,11 +710,9 @@ decision:post-goal-audit {retry+1}
 链路概览后逐字显示（仅当 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。
+📋 任务分解完成。复制以下 /goal 设定终止条件，随后运行 /maestro-ralph-execute：
 
-随后运行 /maestro-ralph continue 立即开始执行。
+/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 /maestro-ralph-execute 推进 step；decision 节点由其自动 handoff 回 ralph 评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
 ```
 
 `/goal` 由用户输入；ralph 只输出此提示词。判据以 status.json 为权威。
@@ -744,7 +748,8 @@ decision:post-goal-audit {retry+1}
 - [ ] 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）
+- [ ] Ralph build 阶段只解析路径，不读 .md 内容；`<required_reading>` 加载由 ralph-execute A_EXEC_INTERNAL 完成
+- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 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

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

@@ -41,6 +41,7 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 HARD RULES:
 - internal step：优先通过 `read_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `invoke_skill({skill})` 调用
+- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；不加载 required_reading 会导致命令执行不完整
 - decision 节点例外：A_EXEC_DECISION 必须使用 `invoke_skill({ skill: "maestro-ralph" })` 进行 handoff（这是 decision 节点的唯一允许用法）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
 - external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
@@ -49,10 +50,13 @@ HARD RULES:
 
 <invariants>
 1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
-2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
-3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
-4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-5. **status.json 每步骤后写盘** — resume-safe
+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. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+6. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+7. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+8. **status.json 每步骤后写盘** — resume-safe
 </invariants>
 
 <state_machine>
@@ -161,11 +165,20 @@ Write enriched args back to status.json.
 2. Mark step running, write status.json
 3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
 4. `read_file({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
-5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
-6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
-7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate
-8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-9. Return success / failure
+5. **解析 reading 标签**（"入口 + workflow"形式核心步骤）：
+   - 抽取 frontmatter `argument-hint` / `allowed-tools`
+   - 抽取 `<required_reading>` 块的所有 `@path` 引用 → 立刻 `read_file({ 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 flag（`auto ? (flag_map[step.skill] || "") : ""`）
+8. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate；执行过程中如触发 deferred_reading 引用的资源 → 按需 Read
+9. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+10. Return success / failure
 
 **Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
@@ -253,7 +266,9 @@ Write enriched args back to status.json.
 | E003 | error | status.json corrupt | Show path, manual check |
 | E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
 | E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| E007 | error | required_reading file 缺失或读取失败 | List missing paths, pause session |
 | W001 | warning | Step completed with concerns | Log and continue |
+| W002 | warning | command .md 无 `<required_reading>` 标签 | 直接执行 .md 主体，跳过加载阶段 |
 
 ### Success Criteria
 
@@ -262,6 +277,9 @@ Write enriched args back to status.json.
 - [ ] Placeholders resolved；per-skill enrichment 正确
 - [ ] Decision 节点 invoke_skill("maestro-ralph") handoff
 - [ ] Internal 节点通过 read_file({step.command_path}) 内联执行，禁止 invoke_skill()
+- [ ] Internal 节点 Read 后必须解析并加载 `<required_reading>` 引用的文件；缺失 → E007 pause
+- [ ] `<deferred_reading>` 仅记录路径到 `step.deferred_reads`，执行阶段按需 Read
+- [ ] required_reading 加载完成后输出 `✓ skill {name} 加载完成 (required: N, deferred: M)`
 - [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
 - [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
 - [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置

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

@@ -21,7 +21,7 @@ Verify execution results through three complementary methods:
 3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
 
 Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
+- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
 - **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.

package/.agy/skills/maestro-brainstorm/SKILL.md

@@ -14,7 +14,7 @@ allowed-tools:
   - write_to_file
 ---
 <purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
 </purpose>
 
 <required_reading>
@@ -32,7 +32,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/brainstorm-{slug}-{YYYYMMDD}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 **Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).

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

@@ -15,10 +15,12 @@ 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 "intent"`** — New session: infer → decompose → build → (decomposition → emit /goal prompt, STOP；否则 dispatch ralph-execute)
+- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
 - **`/maestro-ralph status`** — Display session progress
 
+> 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `Skill("maestro-ralph")` handoff，无需用户手动切换。
+
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Node types:
@@ -66,15 +68,16 @@ Remaining     → intent
 
 <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
+2. **Handoff via Skill("maestro-ralph-execute")** — 仅当 session 无 `task_decomposition` 时在创建后自动 handoff；decomposition 路径 STOP 等用户输入。decision 评估后始终 handoff
 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；字段可选/累加，既有字段不删不改
+8. **Internal step 加载契约** — ralph-execute 读 `command_path` 后，必须解析并加载该命令 `<required_reading>` 引用的所有文件（"入口 + workflow"形式的核心），并把 `<deferred_reading>` 路径记录到 `step.deferred_reads`；加载完成后输出 `✓ skill {name} 加载完成`。ralph 在 build 阶段只解析路径，不读 .md 内容
+9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词后 STOP，等用户输入
+10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 </invariants>
 
 <state_machine>
@@ -144,8 +147,9 @@ 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
+  → END             WHEN: task_decomposition present        DO: A_CREATE_SESSION (emits Goal Prompt → STOP，等用户输入 /goal 后手动 /maestro-ralph-execute)
+  → S_CONFIRM       WHEN: not auto_confirm AND no decomposition DO: A_CREATE_SESSION
+  → S_DISPATCH      WHEN: auto_confirm AND no decomposition  DO: A_CREATE_SESSION
 
 S_CONFIRM:
   → S_DISPATCH      WHEN: user selects "Proceed"
@@ -409,7 +413,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    - 全局优先：`~/.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`
+   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 ralph-execute A_EXEC_INTERNAL 负责（保持入口/工作流分离）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`
 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}`）
@@ -427,7 +432,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 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)
+4. If `task_decomposition` present: display **Goal Prompt block** (Appendix) → STOP，等用户输入 `/goal`（auto_confirm 也不跳过）
 
 ### A_DELEGATE_EVALUATE
 
@@ -616,7 +621,8 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
-    "completed_at": null
+    "completed_at": null,
+    "deferred_reads": []          // 由 ralph-execute A_EXEC_INTERNAL 解析 .md 时填充
   }],
   "waves": [], "current_step": 0,
 
@@ -700,11 +706,9 @@ decision:post-goal-audit {retry+1}
 链路概览后逐字显示（仅当 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。
+📋 任务分解完成。复制以下 /goal 设定终止条件，随后运行 /maestro-ralph-execute：
 
-随后运行 /maestro-ralph continue 立即开始执行。
+/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 /maestro-ralph-execute 推进 step；decision 节点由其自动 handoff 回 ralph 评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
 ```
 
 `/goal` 由用户输入；ralph 只输出此提示词。判据以 status.json 为权威。
@@ -740,7 +744,8 @@ decision:post-goal-audit {retry+1}
 - [ ] 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）
+- [ ] Ralph build 阶段只解析路径，不读 .md 内容；`<required_reading>` 加载由 ralph-execute A_EXEC_INTERNAL 完成
+- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 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

package/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -37,6 +37,7 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 HARD RULES:
 - internal step：优先通过 `view_file({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `Skill({skill})` 调用
+- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；不加载 required_reading 会导致命令执行不完整
 - decision 节点例外：A_EXEC_DECISION 必须使用 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph/SKILL.md") + execute inline` 进行 handoff（这是 decision 节点的唯一允许用法）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
 - external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
@@ -45,10 +46,13 @@ HARD RULES:
 
 <invariants>
 1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
-2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
-3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
-4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-5. **status.json 每步骤后写盘** — resume-safe
+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. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+6. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+7. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+8. **status.json 每步骤后写盘** — resume-safe
 </invariants>
 
 <state_machine>
@@ -157,11 +161,20 @@ Write enriched args back to status.json.
 2. Mark step running, write status.json
 3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
 4. `view_file({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
-5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
-6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
-7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate
-8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-9. Return success / failure
+5. **解析 reading 标签**（"入口 + workflow"形式核心步骤）：
+   - 抽取 frontmatter `argument-hint` / `allowed-tools`
+   - 抽取 `<required_reading>` 块的所有 `@path` 引用 → 立刻 `view_file({ 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 flag（`auto ? (flag_map[step.skill] || "") : ""`）
+8. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate；执行过程中如触发 deferred_reading 引用的资源 → 按需 Read
+9. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+10. Return success / failure
 
 **Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
@@ -249,7 +262,9 @@ Write enriched args back to status.json.
 | E003 | error | status.json corrupt | Show path, manual check |
 | E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
 | E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| E007 | error | required_reading file 缺失或读取失败 | List missing paths, pause session |
 | W001 | warning | Step completed with concerns | Log and continue |
+| W002 | warning | command .md 无 `<required_reading>` 标签 | 直接执行 .md 主体，跳过加载阶段 |
 
 ### Success Criteria
 
@@ -258,6 +273,9 @@ Write enriched args back to status.json.
 - [ ] Placeholders resolved；per-skill enrichment 正确
 - [ ] Decision 节点 Skill("maestro-ralph") handoff
 - [ ] Internal 节点通过 view_file({step.command_path}) 内联执行，禁止 Skill()
+- [ ] Internal 节点 Read 后必须解析并加载 `<required_reading>` 引用的文件；缺失 → E007 pause
+- [ ] `<deferred_reading>` 仅记录路径到 `step.deferred_reads`，执行阶段按需 Read
+- [ ] required_reading 加载完成后输出 `✓ skill {name} 加载完成 (required: N, deferred: M)`
 - [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
 - [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
 - [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置

package/.agy/skills/maestro-verify/SKILL.md

@@ -21,7 +21,7 @@ Verify execution results through three complementary methods:
 3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
 
 Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
+- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
 - **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.

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

@@ -12,7 +12,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/brainstorm-{slug}-{date}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, cross-role review, and resolution writeback. Two modes: Auto (full pipeline: guidance-specification → parallel {role}/ multi-file analysis → cross-role-reviewer compares Decision Digests for conflicts/gaps/synergies → user-confirmed resolutions patched into role files + logged in guidance §12) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` ready for downstream planning (roadmap / analyze / blueprint consume `guidance-specification.md`).
 </purpose>
 
 <required_reading>
@@ -30,7 +30,7 @@ $ARGUMENTS -- topic text for auto mode, or role name for single role mode.
 
 **Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
 **Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**All output** goes to `.workflow/scratch/brainstorm-{slug}-{YYYYMMDD}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
+**All output** goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/` (orchestrator MUST resolve this to an absolute path before passing to sub-agents).
 **Artifact registration**: On completion, registers artifact (type=brainstorm) in state.json.
 **Output boundary**: ALL file writes MUST target `{output_dir}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 **Produced files**: `guidance-specification.md`, `design-research.md` (optional), `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md` (per selected role).

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

@@ -39,6 +39,7 @@ Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
 HARD RULES:
 - internal step：优先通过 `Read({command_path})` 把命令 .md 加载进当前会话，再按内容执行；不要对 internal step 使用 `Skill({skill})` 调用
+- **必须遵循 `<required_reading>` / `<deferred_reading>` 标签**：命令 .md 通常采用"入口 + workflow"形式，主体逻辑放在 workflow 文件中并通过 `<required_reading>` 引用；不加载 required_reading 会导致命令执行不完整
 - decision 节点例外：A_EXEC_DECISION 必须使用 `Skill({ skill: "maestro-ralph" })` 进行 handoff（这是 decision 节点的唯一允许用法）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json；ralph-execute 不再自行解析（缺失 → 报错 E002）
 - external 仅在 `step.type == "external"` 显式声明时使用，并 always append `-y` 到 prompt args
@@ -47,10 +48,13 @@ HARD RULES:
 
 <invariants>
 1. **Internal = Read + inline** — 通过 Read 读取 `step.command_path`，按其指令在当前 session 内执行
-2. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
-3. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
-4. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
-5. **status.json 每步骤后写盘** — resume-safe
+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. **External = explicit only** — `step.type == "external"` 才走 delegate；默认绝不发起
+6. **必须显式 completion confirmation** — 每个 step 完成时需有 `STATUS: DONE` 且写入 `step.completion_confirmed = true`
+7. **Self-invocation chain** — 持续直到全部 `completion_confirmed` 或 paused
+8. **status.json 每步骤后写盘** — resume-safe
 </invariants>
 
 <state_machine>
@@ -159,11 +163,20 @@ Write enriched args back to status.json.
 2. Mark step running, write status.json
 3. Display: `[{index}/{total}] {step.skill} [internal · {step.command_scope}]`
 4. `Read({ file_path: step.command_path })` — 把命令 .md 全文加载进当前会话（prefer Read over Skill for internal steps；decision 节点另行使用 Skill 见 A_EXEC_DECISION）
-5. 解析 frontmatter `argument-hint` 与 `<purpose>/<state_machine>/<actions>` 等指令块
-6. 计算 `effective_args`：`step.args` + auto flag（`auto ? (flag_map[step.skill] || "") : ""`）
-7. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate
-8. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
-9. Return success / failure
+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 flag（`auto ? (flag_map[step.skill] || "") : ""`）
+8. 按读到的指令在本会话中**内联执行**：调用允许的工具完成命令所规定的工作，不再发起 delegate；执行过程中如触发 deferred_reading 引用的资源 → 按需 Read
+9. 执行结束：要求最后一段必须包含 `--- COMPLETION STATUS ---` 块（见 A_MARK_COMPLETE）
+10. Return success / failure
 
 **Auto flag map**: 所有 lifecycle skill → `-y`; `quality-test` → `-y --auto-fix`; 未列出 → 无 flag
 
@@ -251,7 +264,9 @@ Write enriched args back to status.json.
 | E003 | error | status.json corrupt | Show path, manual check |
 | E004 | error | Delegate failed + user abort | Mark paused, suggest resume |
 | E005 | error | COMPLETION STATUS block missing | Trigger NEEDS_RETRY |
+| E007 | error | required_reading file 缺失或读取失败 | List missing paths, pause session |
 | W001 | warning | Step completed with concerns | Log and continue |
+| W002 | warning | command .md 无 `<required_reading>` 标签 | 直接执行 .md 主体，跳过加载阶段 |
 
 ### Success Criteria
 
@@ -260,6 +275,9 @@ Write enriched args back to status.json.
 - [ ] Placeholders resolved；per-skill enrichment 正确
 - [ ] Decision 节点 Skill("maestro-ralph") handoff
 - [ ] Internal 节点通过 Read({step.command_path}) 内联执行，禁止 Skill()
+- [ ] Internal 节点 Read 后必须解析并加载 `<required_reading>` 引用的文件；缺失 → E007 pause
+- [ ] `<deferred_reading>` 仅记录路径到 `step.deferred_reads`，执行阶段按需 Read
+- [ ] required_reading 加载完成后输出 `✓ skill {name} 加载完成 (required: N, deferred: M)`
 - [ ] External 仅在显式声明时走 delegate，prompt 必带 `-y`
 - [ ] 每个 step 强制 `--- COMPLETION STATUS ---`；缺失 → NEEDS_RETRY
 - [ ] step.completion_confirmed = true 仅在 STATUS: DONE/DONE_WITH_CONCERNS 时设置

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

@@ -17,10 +17,12 @@ 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 "intent"`** — New session: infer → decompose → build → (decomposition → emit /goal prompt, STOP；否则 dispatch ralph-execute)
+- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
 - **`/maestro-ralph status`** — Display session progress
 
+> 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `Skill("maestro-ralph")` handoff，无需用户手动切换。
+
 Initial decomposition (S_DECOMPOSE): boundary-clarified via ≤3 questions for broad intents (重构/全面/迁移/重写). 写入 status.json 的 `boundary_contract` / `execution_criteria` / `task_decomposition`，附 `/goal` prompt。
 
 Node types:
@@ -68,15 +70,16 @@ Remaining     → intent
 
 <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
+2. **Handoff via Skill("maestro-ralph-execute")** — 仅当 session 无 `task_decomposition` 时在创建后自动 handoff；decomposition 路径 STOP 等用户输入。decision 评估后始终 handoff
 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；字段可选/累加，既有字段不删不改
+8. **Internal step 加载契约** — ralph-execute 读 `command_path` 后，必须解析并加载该命令 `<required_reading>` 引用的所有文件（"入口 + workflow"形式的核心），并把 `<deferred_reading>` 路径记录到 `step.deferred_reads`；加载完成后输出 `✓ skill {name} 加载完成`。ralph 在 build 阶段只解析路径，不读 .md 内容
+9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 用户绑定，ralph 只发提示词后 STOP，等用户输入
+10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
+11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 </invariants>
 
 <state_machine>
@@ -146,8 +149,9 @@ 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
+  → END             WHEN: task_decomposition present        DO: A_CREATE_SESSION (emits Goal Prompt → STOP，等用户输入 /goal 后手动 /maestro-ralph-execute)
+  → S_CONFIRM       WHEN: not auto_confirm AND no decomposition DO: A_CREATE_SESSION
+  → S_DISPATCH      WHEN: auto_confirm AND no decomposition  DO: A_CREATE_SESSION
 
 S_CONFIRM:
   → S_DISPATCH      WHEN: user selects "Proceed"
@@ -411,7 +415,8 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    - 全局优先：`~/.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`
+   - **不在 build 阶段读取 .md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 ralph-execute A_EXEC_INTERNAL 负责（保持入口/工作流分离）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`
 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}`）
@@ -429,7 +434,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 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)
+4. If `task_decomposition` present: display **Goal Prompt block** (Appendix) → STOP，等用户输入 `/goal`（auto_confirm 也不跳过）
 
 ### A_DELEGATE_EVALUATE
 
@@ -618,7 +623,8 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
-    "completed_at": null
+    "completed_at": null,
+    "deferred_reads": []          // 由 ralph-execute A_EXEC_INTERNAL 解析 .md 时填充
   }],
   "waves": [], "current_step": 0,
 
@@ -702,11 +708,9 @@ decision:post-goal-audit {retry+1}
 链路概览后逐字显示（仅当 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。
+📋 任务分解完成。复制以下 /goal 设定终止条件，随后运行 /maestro-ralph-execute：
 
-随后运行 /maestro-ralph continue 立即开始执行。
+/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 /maestro-ralph-execute 推进 step；decision 节点由其自动 handoff 回 ralph 评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
 ```
 
 `/goal` 由用户输入；ralph 只输出此提示词。判据以 status.json 为权威。
@@ -742,7 +746,8 @@ decision:post-goal-audit {retry+1}
 - [ ] 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）
+- [ ] Ralph build 阶段只解析路径，不读 .md 内容；`<required_reading>` 加载由 ralph-execute A_EXEC_INTERNAL 完成
+- [ ] 每个 step 含 `completion_confirmed` + `completion_status` + `completion_evidence` + `deferred_reads`（初始 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

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

@@ -19,7 +19,7 @@ Verify execution results through three complementary methods:
 3. **Nyquist test coverage validation** — requirement-to-test mapping with gap classification
 
 Supports dual-level verification:
-- **Single plan**: `verify --dir scratch/plan-xxx` — verifies one plan, writes `verification.json` into plan dir
+- **Single plan**: `verify --dir scratch/{YYYYMMDD}-plan-xxx` — verifies one plan, writes `verification.json` into plan dir
 - **Milestone**: `verify` (no args) — aggregates all execute artifacts for current milestone into `scratch/{YYYYMMDD}-verify-M{N}-{slug}/milestone-verification.json`
 
 Registers VRF artifact in state.json on completion.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Workflow orchestration CLI with MCP endpoint support and extensible architecture",
   "type": "module",
   "imports": {

package/workflows/analyze.md

@@ -60,12 +60,12 @@ Worktree guard: If .workflow/worktree-scope.json exists, reject phase args not i
 Auto-bootstrap: Create minimal .workflow/state.json if missing.
 
 Scope determination → OUTPUT_DIR:
-  (no args) + milestone + roadmap → scope="milestone", mode="micro", OUTPUT_DIR=.workflow/scratch/analyze-{milestone_slug}-{date}/
+  (no args) + milestone + roadmap → scope="milestone", mode="micro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-M{N}-{milestone_slug}/
   (no args) without milestone/roadmap → ERROR E001
-  (number) + milestone + roadmap   → scope="phase", mode="micro", OUTPUT_DIR=.workflow/scratch/analyze-{phase_slug}-{date}/
+  (number) + milestone + roadmap   → scope="phase", mode="micro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-P{N}-{phase_slug}/
   (number) without milestone/roadmap → ERROR
-  (text) + milestone               → scope="adhoc", mode="macro", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
-  (text) without milestone         → scope="standalone", mode="macro", OUTPUT_DIR=.workflow/scratch/analyze-{topic_slug}-{date}/
+  (text) + milestone               → scope="adhoc", mode="macro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-{topic_slug}/
+  (text) without milestone         → scope="standalone", mode="macro", OUTPUT_DIR=.workflow/scratch/{YYYYMMDD}-analyze-{topic_slug}/
 
 Macro mode additions (scope="adhoc" or "standalone"):
   - In Step 6 Synthesis, evaluate scope_verdict: "small" | "medium" | "large"
@@ -113,8 +113,8 @@ Parse $ARGUMENTS to determine mode and flags:
 - `-c` present: locate existing session folder (discussion.md exists), resume from last round
 - `-y` present: set AUTO_MODE=true
 - `-q` present: set QUICK_MODE=true (skip Steps 2-7, jump to Step 8: Decision Extraction)
-- Number (e.g., "3") = phase scope: resolve phase slug from roadmap, output to scratch/analyze-{phase-slug}-{date}/
-- Text (e.g., "microservices vs monolith") = adhoc/standalone scope: output to scratch/analyze-{slug}-{date}/
+- Number (e.g., "3") = phase scope: resolve phase slug from roadmap, output to scratch/{YYYYMMDD}-analyze-P{N}-{phase-slug}/
+- Text (e.g., "microservices vs monolith") = adhoc/standalone scope: output to scratch/{YYYYMMDD}-analyze-{slug}/
 - Missing/empty = milestone scope (if roadmap exists) or error E001
 
 **Session initialization:**

package/workflows/brainstorm.md

@@ -50,7 +50,7 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 ## Input
 
 - `$ARGUMENTS`: topic text (auto mode) or role name (single role mode)
-- All output goes to `.workflow/scratch/brainstorm-{slug}-{date}/`
+- All output goes to `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`
 - Registers artifact (type=brainstorm) in state.json on completion
 
 ### Parameters
@@ -86,7 +86,7 @@ Phase 3: Single Role Analysis → Detection → Context → Agent → Validation
 
 All brainstorm output goes to scratch:
 ```
-.workflow/scratch/brainstorm-{slug}-{date}/
+.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/
 ├── guidance-specification.md          # Phase 2 output — machine contract (downstream consumes this)
 ├── design-research.md                 # Optional Step 1.7 output
 ├── system-architect/                  # Phase 3 per-role analysis (one folder per selected role)
@@ -129,14 +129,14 @@ Parse $ARGUMENTS to determine execution mode:
 - Missing/empty args without flags = error E001
 
 **Session Detection**:
-- Check `.workflow/scratch/brainstorm-*/` for existing sessions
+- Check `.workflow/scratch/*-brainstorm-*/` for existing sessions
 - Multiple → AskUserQuestion to select | Single → use it
 - None + auto mode → will create new session
 - None + single role mode → error E002
 
 **Output Directory Resolution**:
 - Phase mode (number): resolve `state.json.artifacts[phase == phaseNum].path` → `.workflow/{path}/.brainstorming/` (ERROR if phase not found)
-- All output: `.workflow/scratch/brainstorm-{slug}-{date}/`
+- All output: `.workflow/scratch/{YYYYMMDD}-brainstorm-{slug}/`
 - Existing session: use existing session directory
 
 ---
@@ -330,7 +330,7 @@ When `ui-designer` is among the selected roles, establish the project's visual d
 For EACH selected role, spawn a `role-design-author` agent in parallel. Each agent produces a multi-file analysis under `{output_dir}/{role}/`.
 
 **Path resolution (orchestrator responsibility, BEFORE invocation)**:
-- Resolve `{output_dir}` to an **absolute path** (e.g., `D:/proj/.workflow/scratch/brainstorm-foo-20260521`). Do NOT pass the literal `.workflow/...` relative form — agent Write tool requires absolute paths.
+- Resolve `{output_dir}` to an **absolute path** (e.g., `D:/proj/.workflow/scratch/20260521-brainstorm-foo`). Do NOT pass the literal `.workflow/...` relative form — agent Write tool requires absolute paths.
 - Expand `~/` in `role_template_path` to the user home absolute path.
 - For absent optional fields (e.g., `style_skill` when role ≠ ui-designer, `design_research` when Step 1.7 was skipped), pass the literal string `null` — never a conditional placeholder like `{x if y}`.
 

package/workflows/debug.md

@@ -102,8 +102,8 @@ Display:
 
 | # | Location | Status | Current Hypothesis |
 |---|----------|--------|--------------------|
-| 1 | scratch/plan-auth-2026-04-20/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
-| 2 | scratch/debug-nav-crash-2026-03-14/ | checkpoint | Awaiting user input |
+| 1 | scratch/20260420-plan-P3-auth/.debug/jwt-expiry/ | investigating | Token not refreshed on 401 |
+| 2 | scratch/20260314-debug-nav-crash/ | checkpoint | Awaiting user input |
 
 Reply with a number to resume, or describe a new issue.
 ```
@@ -194,11 +194,11 @@ Create debug session directory and proceed to Step 6.
 | Mode | Directory |
 |------|-----------|
 | Phase-scoped (from UAT) | `{ARTIFACT_DIR}/.debug/{gap-slug}/` (ARTIFACT_DIR resolved from artifact registry) |
-| Standalone | `.workflow/scratch/debug-{slug}-{date}/` |
+| Standalone | `.workflow/scratch/{YYYYMMDD}-debug-{slug}/` |
 
 Resolve `DEBUG_DIR` from artifact registry:
 - Phase-scoped: look up phase in `.workflow/state.json` artifacts (type=execute), set `DEBUG_DIR = ".workflow/{art.path}/.debug/{gap-slug}/"`. Error if not found.
-- Standalone: `DEBUG_DIR = ".workflow/scratch/debug-{slug}-{date}/"`
+- Standalone: `DEBUG_DIR = ".workflow/scratch/{YYYYMMDD}-debug-{slug}/"`
 
 Create the directory.
 

package/workflows/harvest.md

@@ -67,7 +67,7 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | Source Type | Scan Path | Key Files | ID Pattern |
 |-------------|-----------|-----------|------------|
 | `analysis` | `.workflow/.analysis/ANL-*/` | `conclusions.json`, `*.md` | `ANL-*` |
-| `brainstorm` | `.workflow/scratch/brainstorm-*/` | `guidance-specification.md`, `*/analysis.md`, `design-research.md` | directory name |
+| `brainstorm` | `.workflow/scratch/*-brainstorm-*/` | `guidance-specification.md`, `*/analysis.md`, `design-research.md` | directory name |
 | `lite-plan` | `.workflow/.lite-plan/*/` | `plan.json`, `plan-overview.md` | directory name |
 | `lite-fix` | `.workflow/.lite-fix/*/` | `fix-plan.json` | directory name |
 | `debug` | `.workflow/.debug/*/` | `debug-log.md`, `hypothesis-*.md` | directory name |

package/workflows/init.md

@@ -43,7 +43,7 @@ state.json exists → Path C (existing) | source files exist → Path B (brownfi
 
    If `--auto` flag: skip interactive questioning, extract from @ referenced document.
    If `--from <source>` (alias: `--from-brainstorm`):
-   - Locate source directory (`.workflow/scratch/brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
+   - Locate source directory (`.workflow/scratch/*-brainstorm-*/`, `.workflow/scratch/*-import-*/`, etc.)
    - Load `context-package.json` (preferred) or fall back to `guidance-specification.md`:
      - `domain` (name, description, problem_statement) → project vision + core value
      - `requirements[]` → project goals (Active requirements)

package/workflows/plan.md

@@ -4,7 +4,7 @@
 
 Produces two-layer plan output: `plan.json` (overview with task_ids[] and waves[]) + `.task/TASK-{NNN}.json` (individual task definitions).
 
-All output goes to `.workflow/scratch/plan-{slug}-{date}/`.
+All output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting; scope prefix (`P{N}` for phase, `M{N}` for milestone, omit for standalone/adhoc) enables fallback identification.
 
 ---
 

package/workflows/quick.md

@@ -69,10 +69,10 @@ Quick tasks can run mid-phase -- validation only checks project exists, not phas
 **Create scratch directory:**
 
 Generate slug from $DESCRIPTION (lowercase, hyphens, max 40 chars).
-Set date to current date (YYYY-MM-DD).
+Set date to current date (YYYYMMDD).
 
 ```bash
-QUICK_DIR=".workflow/scratch/quick-${slug}-${date}"
+QUICK_DIR=".workflow/scratch/${date}-quick-${slug}"
 mkdir -p "$QUICK_DIR/.task"
 mkdir -p "$QUICK_DIR/.summaries"
 ```
@@ -80,7 +80,7 @@ mkdir -p "$QUICK_DIR/.summaries"
 Write index.json:
 ```json
 {
-  "id": "quick-{slug}-{date}",
+  "id": "{YYYYMMDD}-quick-{slug}",
   "type": "quick",
   "title": "{$DESCRIPTION}",
   "status": "active",
@@ -315,7 +315,7 @@ Read state.json. Add quick task to accumulated_context or quick_tasks array.
 Record:
 ```json
 {
-  "id": "quick-{slug}-{date}",
+  "id": "{YYYYMMDD}-quick-{slug}",
   "description": "{$DESCRIPTION}",
   "completed_at": "{ISO timestamp}",
   "directory": "{$QUICK_DIR}",

package/workflows/refactor.md

@@ -2,7 +2,7 @@
 
 Systematically reduce tech debt through scope analysis, task planning, and reflection-driven execution. Each refactoring round records strategy, outcome, and adjustments. Existing tests must pass after every change.
 
-Output: scratch/refactor-{slug}-{date}/ with index.json + reflection-log.md + .task/ + .summaries/
+Output: scratch/{YYYYMMDD}-refactor-{slug}/ with index.json + reflection-log.md + .task/ + .summaries/
 
 ---
 
@@ -24,13 +24,13 @@ Output: scratch/refactor-{slug}-{date}/ with index.json + reflection-log.md + .t
 
 Prompt user for scope type: module path, feature area, or full codebase.
 
-Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYY-MM-DD.
+Generate slug from scope (lowercase, hyphens, max 40 chars). Set date = YYYYMMDD.
 
 ---
 
 ### Step 2: Create Scratch Directory
 
-Create `REFACTOR_DIR=".workflow/scratch/refactor-${slug}-${date}"` with `.task/` and `.summaries/` subdirs.
+Create `REFACTOR_DIR=".workflow/scratch/${date}-refactor-${slug}"` with `.task/` and `.summaries/` subdirs.
 
 Write index.json: id, type="refactor", title, status="active", scope, plan (empty task_ids), execution (method=agent, counts=0), reflection (rounds=0).
 

package/workflows/retrospective.md

@@ -481,8 +481,8 @@ If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate
       "summary": "Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; should become a project-wide convention.",
       "confidence": "high",
       "evidence_refs": [
-        ".workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]",
-        ".workflow/scratch/plan-auth-2026-04-15/.summaries/TASK-005-summary.md:42"
+        ".workflow/scratch/20260415-plan-P1-auth/verification.json#gaps[2]",
+        ".workflow/scratch/20260415-plan-P1-auth/.summaries/TASK-005-summary.md:42"
       ],
       "tags": ["auth", "jwt", "security"],
       "routed_to": "spec",
@@ -508,7 +508,7 @@ Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; shou
 - **Phase**: 1 (01-auth)
 - **Lens**: technical
 - **Confidence**: high
-- **Evidence**: .workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]
+- **Evidence**: .workflow/scratch/20260415-plan-P1-auth/verification.json#gaps[2]
 - **Routed to**: spec (coding-conventions.md#INS-a1b2c3d4)
 
 </spec-entry>

package/workflows/ui-design.md

@@ -24,7 +24,7 @@ Pipeline position: analyze -> **ui-design** -> plan -> execute -> verify
 
 ```
 Input: <phase> (number) OR topic text
-Output: .workflow/scratch/ui-design-{slug}-{date}/
+Output: .workflow/scratch/{YYYYMMDD}-ui-design-{slug}/
 
 Resolve scope:
   number → phase slug from roadmap.md, scope="phase", register with phase

package/workflows/ui-style.md

@@ -23,7 +23,7 @@ If argument is phase number/slug:
   SCRATCH_MODE = false
 
 If argument is topic text (scratch mode):
-  PHASE_DIR = .workflow/scratch/ui-design-{slug}-{YYYYMMDD}
+  PHASE_DIR = .workflow/scratch/{YYYYMMDD}-ui-design-{slug}
   Create directory + minimal index.json (type="ui-design", goal=topic).
   SCRATCH_MODE = true
 ```

package/workflows/verify.md

@@ -82,7 +82,7 @@ Resolve PLAN_DIRS and VERIFY_MODE by input type:
   numeric arg     → phase mode, collect completed execute artifacts for that phase from state.json
 
 If no matching artifacts found: ERROR E001.
-Milestone mode creates output dir: .workflow/scratch/verify-{milestone_slug}-{date}/
+Milestone mode creates output dir: .workflow/scratch/{YYYYMMDD}-verify-{milestone_slug}/
 ```
 
 ---