maestro-flow 0.5.34 → 0.5.35

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

@@ -23,6 +23,7 @@ $ARGUMENTS — intent text, flags, or keywords.
 **Parse:**
 ```
 -y flag       → auto_confirm = true
+--roadmap     → wants_roadmap = true (强制多发布 roadmap 路径；roadmap 默认 opt-in)
 .md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
 Remaining     → intent
 ```
@@ -56,7 +57,7 @@ S_PARSE_ROUTE     — 解析参数、路由入口                  PERSIST: —
 S_STATUS          — 显示 session 进度                   PERSIST: —
 S_CONTINUE        — 恢复执行                            PERSIST: —
 S_RESOLVE_PHASE   — 解析 phase + phase_is_new + D-007 milestone PERSIST: session.phase, session.phase_is_new, session.milestone
-S_INFER           — 基于已解析 phase 推断 lifecycle_position PERSIST: session.lifecycle_position
+S_INFER           — 基于已解析 phase 推断 lifecycle_position PERSIST: session.lifecycle_position, session.wants_roadmap
 S_RESOLVE_SCOPE   — 读 macro analyze conclusions.scope_verdict PERSIST: session.scope_verdict, session.analyze_macro_id
 S_QUALITY_MODE    — 决定质量管线模式                     PERSIST: session.quality_mode
 S_PLANNING_MODE   — 决定统一/独立规划模式               PERSIST: session.planning_mode
@@ -128,7 +129,7 @@ S_DISPATCH:
   → END             DO: Skill({ skill: "maestro-ralph-execute" })
 
 S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取自该字段)
-  → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test)
+  → S_APPLY_VERDICT WHEN: quality-gate (post-execute, post-business-test, post-review, post-test, post-frontend-verify)
                      DO: A_DELEGATE_EVALUATE
   → S_APPLY_VERDICT WHEN: goal-gate (post-goal-audit)
                      DO: A_GOAL_AUDIT_EVALUATE
@@ -215,6 +216,14 @@ resolve_milestone(phase_number):
 | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
 | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
 
+**Roadmap opt-in detection** (设 `session.wants_roadmap`，缺省 `false`):
+```
+wants_roadmap = (--roadmap flag)
+             OR (intent 含多发布信号: 多发布|多版本|分阶段交付|按里程碑发布|v1.*v2|multi-release|roadmap)
+             OR (.workflow/roadmap.md 已存在)   ← 向后兼容：既有 roadmap 项目行为不变
+```
+默认 `false` → large 项目走单一多波次 `plan --from analyze`，不引入 roadmap 横切层；roadmap 仅多发布场景 opt-in。
+
 **Bootstrap detection:**
 
 | Condition | Position |
@@ -229,7 +238,7 @@ resolve_milestone(phase_number):
 | Condition | Position |
 |-----------|----------|
 | `phase_is_new == true` (新 phase) | `analyze` |
-| no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` |
+| no milestones AND no roadmap.md AND has analyze macro artifact | `roadmap` if `wants_roadmap` else `plan` (--from analyze) |
 | no milestones AND no roadmap.md AND no analyze artifact | `analyze-macro` |
 | `phase == null` (grill/brainstorm/blueprint/init/roadmap/analyze-macro override 已定) | n/a |
 | phase 已存在 + 无任何 artifact | `analyze` |
@@ -250,9 +259,9 @@ resolve_milestone(phase_number):
 
 | scope_verdict | 链路 |
 |---------------|------|
-| `large` | analyze-macro → roadmap → analyze → plan → execute → ... |
-| `medium` / `small` | analyze-macro → plan --from analyze:{ANL_ID} → execute → ...（跳过 roadmap + analyze-phase） |
-| `unknown` | 默认走 large 路径，post-analyze-scope 决策节点再纠正 |
+| `large` + `wants_roadmap` | analyze-macro → roadmap → analyze → plan → execute → ...（多发布 opt-in） |
+| `large`（默认）/ `medium` / `small` | analyze-macro → plan --from analyze:{ANL_ID} → execute → ...（跳过 roadmap + analyze-phase；单一多波次计划） |
+| `unknown` | 默认走 standalone（plan --from analyze）路径，post-analyze-scope 决策节点再纠正 |
 
 **Refine from post-execute results:**
 
@@ -335,10 +344,10 @@ narrow → derive defaults from intent + codebase, skip questions.
 ```json
 { "id": "G1", "goal": "<deliverable>", "boundary": "<in/out note>",
   "done_when": "<objectively checkable condition>",
-  "evidence": "verification.json|review.json|uat.md|<test path>",
+  "evidence": "verification.json|review.json|uat.md|e2e-results.json|<test path>",
   "lifecycle": ["analyze","execute"], "status": "pending" }
 ```
-`done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。
+`done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。涉及前端可用性的子目标，`done_when` 应引用 `e2e-results.json`（frontend-verify 门产出），不得仅以后端 API/build 证据判定可用。
 
 **5. Persist** (additive): `boundary_contract`, `execution_criteria`, `task_decomposition`。每个 sub-goal 含 `status: "pending"` + `completion_confirmed: false`。
 
@@ -364,6 +373,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 | review | `quality-review {phase}` | `quality-review` | `post-review` | all (quick: append `--tier quick`) |
 | test-gen | `quality-auto-test {phase}` | `quality-auto-test` | — | full / standard if coverage<80% |
 | test | `quality-test {phase}` | `quality-test` | `post-test` | full, standard |
+| frontend-verify | `quality-test {phase} --frontend-verify` | `quality-test --frontend-verify` | `post-frontend-verify` | all（**仅当 phase 交付 UI 时插入**：检出 `dashboard/` 或 UI 关键词 `landing\|page\|dashboard\|frontend\|UI\|component\|界面`） |
 | milestone-audit | `maestro-milestone-audit` | *(same)* | — | all |
 | goal-audit | *(decision-only)* | *(same)* | `post-goal-audit` | all (only if decomposed) |
 | milestone-complete | `maestro-milestone-complete` | *(same)* | `post-milestone` | all |
@@ -378,6 +388,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
 3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
+3.6. **frontend-verify UI 门控**：仅当当前 phase 交付前端（检出 `dashboard/` 目录，或 phase 目标/计划含 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`）时保留 `frontend-verify` stage + `post-frontend-verify` decision；纯后端 phase 删除该 stage
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
@@ -392,13 +403,16 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    - **不在 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}`）
-    - `scope_verdict == unknown` → 默认 large 路径；由 `post-analyze-scope` 决策节点在 macro analyze 完成后纠正（A_APPLY_SCOPE_VERDICT）
+    - `scope_verdict == large` **且** `wants_roadmap` → 保留 `roadmap` + `analyze`；`plan` 选 phase 列（`{phase}`）
+    - 其余（`medium` / `small`，或 `large` 但非 `wants_roadmap`）→ 跳过 `roadmap` + `analyze` 两 stage；`plan` 选 standalone 列（`--from analyze:{analyze_macro_id}`），不带 `{phase}`
+    - `scope_verdict == unknown` → 默认 standalone（非 roadmap）路径；由 `post-analyze-scope` 决策节点在 macro analyze 完成后纠正（A_APPLY_SCOPE_VERDICT）
 12. **--from 自动注入**：
     - `analyze_macro_id` 存在且当前 step 是 `roadmap` → args 改为 `--from analyze:{analyze_macro_id}`
-    - `analyze_macro_id` 存在且 `scope_verdict ∈ {medium, small}` 且当前 step 是 `plan` → args 改为 `--from analyze:{analyze_macro_id}`
+    - `analyze_macro_id` 存在且当前 `plan` step 处于 standalone 列（即非 wants_roadmap 路径：`medium`/`small`，或 `large` 但非 `wants_roadmap`）→ args 改为 `--from analyze:{analyze_macro_id}`
     - `blueprint_id` 存在 → 当前 step 是 `plan` → args 改为 `--from blueprint:{blueprint_id}`（优先级低于 phase 数字参数）
+    - **phase-level deferred chaining**（独立模式，step 含 `{phase}` 占位符）：build 阶段前序 artifact 尚未产出，由 A_RESOLVE_ARGS（ralph-execute）运行时从 state.json 查找同 phase+milestone 最新 completed artifact 注入：
+      - `plan` step → `--from analyze:{phase_analyze_id}`，写 `source_artifact_ref`
+      - `execute` step → `--dir {plan_path}`（现有逻辑），写 `source_artifact_ref = "plan:{id}"`
     - 写入 `step.source_artifact_ref` 以便审计
 13. **D-007 Milestone-ref 标注**：每个含 `{phase}` 占位符的 step → `step.milestone_id = session.milestone`（由 A_RESOLVE_PHASE 反查得出），禁止读 `current_milestone`
 14. **动态插入步骤**（A_APPLY_*）同样应用规则 7-13
@@ -421,6 +435,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
    | post-business-test | .tests/auto-test/report.json |
    | post-review | review.json |
    | post-test | uat.md, .tests/test-results.json |
+   | post-frontend-verify | e2e-results.json |
 4. Check artifact for confidence section → include as signal
 5. Execute delegate (run_in_background, STOP, wait for callback):
    ```
@@ -522,14 +537,14 @@ Runs only when `task_decomposition` present.
 
 由 `post-analyze-scope` 触发，依据 `session.scope_verdict` 重塑下游链路。
 
-1. 读 `session.scope_verdict`
-2. 路径 A（`large`）：保持当前链；为后续 `roadmap` step 注入 `--from analyze:{analyze_macro_id}`；为后续 `plan` step 选 phase 列；继续推进
-3. 路径 B（`medium` / `small`）：
+1. 读 `session.scope_verdict` + `session.wants_roadmap`
+2. 路径 A（`large` 且 `wants_roadmap`）：保持当前链（roadmap+analyze）；为后续 `roadmap` step 注入 `--from analyze:{analyze_macro_id}`；为后续 `plan` step 选 phase 列；继续推进
+3. 路径 B（`medium` / `small`，或 `large` 但非 `wants_roadmap`）：
    - 删除 `goal-audit` 之前所有未完成的 `roadmap` + `analyze` (phase) step
    - 把下一个未完成的 `plan` step 改为 `maestro-plan --from analyze:{analyze_macro_id}`，去掉 `{phase}`，`source_artifact_ref = analyze:{analyze_macro_id}`
    - 后续 `execute` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
 4. 路径 C（`unknown`）：
-   - 非 auto_confirm → AskUserQuestion 二选一（large / medium-small）；auto_confirm → 默认 large
+   - 非 auto_confirm → AskUserQuestion 二选一（roadmap 多发布 / 单一计划）；auto_confirm → 默认路径 B（单一计划，不引入 roadmap）
 5. Reindex steps，标 decision completed，write status.json
 6. Display: ◆ Scope verdict: {verdict} → {kept|collapsed to standalone via analyze:{ANL_ID}}
 
@@ -579,6 +594,7 @@ Runs only when `task_decomposition` present.
   "quality_mode": "standard",     // "full" | "standard" | "quick"
   "planning_mode": "independent", // "unified" | "independent"
   "scope_verdict": null,          // "large" | "medium" | "small" | "unknown" | null
+  "wants_roadmap": false,         // roadmap opt-in：--roadmap | 多发布 intent | roadmap.md 已存在
   "analyze_macro_id": null,       // "ANL-xxx" 来自最新 macro analyze
   "blueprint_id": null,           // "BLP-xxx" 若存在
   "cli_tool": "claude", "passed_gates": [],
@@ -670,6 +686,15 @@ quality-test {phase}
 decision:post-test {retry+1}
 ```
 
+**post-frontend-verify:** (UI 写端点未接线/不可用时)
+```
+quality-debug --from-frontend-verify "{gap_summary}"
+maestro-plan --gaps {phase}
+maestro-execute {phase}
+quality-test {phase} --frontend-verify
+decision:post-frontend-verify {retry+1}
+```
+
 **post-goal-audit:** (per unmet sub-goal group)
 ```
 # for each unmet sub-goal G{n}, scoped to target_phase:
@@ -718,12 +743,13 @@ decision:post-goal-audit {retry+1}
 - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
 - [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
-- [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
+- [ ] 链路起点 = analyze-macro 时：large+wants_roadmap→roadmap+analyze+plan(phase)；其余(含 large 默认/medium/small)→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路
 - [ ] plan step args 支持三路径：`{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}`，写入 step.source_artifact_ref
 - [ ] roadmap step args 自动注入 `--from analyze:{analyze_macro_id}`（若存在）
 - [ ] artifact 过滤按 session.phase；unified 按 milestone
 - [ ] quality_mode 由 A_DETERMINE_QUALITY_MODE 决定，过滤 build steps
+- [ ] frontend-verify stage 仅在 phase 交付 UI 时插入（test 后、milestone-audit 前）；post-frontend-verify 走 quality-gate 评估，evidence=e2e-results.json
 - [ ] Decomposition: broad intent ≤3 question clarify；narrow auto-derive
 - [ ] status.json 唯一真源：boundary_contract + execution_criteria + task_decomposition；无外部清单
 - [ ] 执行 step 含 `command_scope` + `command_path`（通过 `maestro ralph skills --platform claude --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
@@ -737,5 +763,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Chain 必须以 `milestone-complete` 结尾
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
 - [ ] Ralph 不执行 step，只 evaluate；Skill("maestro-ralph-execute") handoff
+- [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
+- [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
+- [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
 
 </appendix>

package/.claude/commands/quality-test.md

@@ -1,7 +1,7 @@
 ---
 name: quality-test
 description: Use when implementation needs user acceptance testing with interactive verification and gap closure
-argument-hint: "[phase] [--smoke] [--auto-fix]"
+argument-hint: "[phase] [--smoke] [--auto-fix] [--frontend-verify]"
 allowed-tools:
   - Read
   - Write
@@ -27,6 +27,31 @@ Flags, artifact context resolution, and output directory format defined in workf
 </context>
 
 <execution>
+**Mode select:** `--frontend-verify` → 走下方 **Frontend Verify Mode**（确定性浏览器 smoke，**不是**对话式 UAT）；否则 Follow '~/.maestro/workflows/test.md' completely.
+
+### Frontend Verify Mode (`--frontend-verify`)
+
+补 ralph 链路缺失的运行时可用性门：确定性验证每个用户可观测能力真正经 UI 可触发，避免"后端绿灯=完成"。
+
+1. **Resolve targets**: 读 phase 的 `plan.json` / `.task/TASK-*.json`，提取所有 `[UI-observable]` convergence.criteria（plan 阶段产出）；缺失则枚举后端写端点（POST/PUT/PATCH/DELETE）作为待验证清单。
+2. **Start app**: `next start`（或从 dashboard/package.json 解析的既有启动脚本）；启动失败 → E003。
+3. **Drive browser**: 用 chrome-devtools MCP（`mcp__claude_dms3-chrome-devtools__*`：navigate / click / fill / take_snapshot / list_network_requests）逐条执行每个 `[UI-observable]` 流程，断言：UI 入口存在且可触发 → 对应写请求返回 2xx → DOM 出现预期结果。
+4. **Write evidence**: 产出 `e2e-results.json`（结构见下），逐条记 pass/fail + 证据（网络状态码、快照引用）。**确定性断言，禁止"无人应答=全过"**。
+5. **Verdict**: 任一 `[UI-observable]` fail 或写端点无 UI 入口 → STATUS=NEEDS_RETRY（ralph 经 post-frontend-verify 触发 Fix-Loop）；全过 → DONE。
+
+```json
+// e2e-results.json
+{ "phase": "{phase}", "app_url": "http://localhost:3000",
+  "checks": [ { "criterion": "[UI-observable] ...", "ui_entry": "<selector/route>",
+    "request": "POST /api/notes", "status": 201, "dom_assert": "list shows new item",
+    "passed": true } ],
+  "summary": { "total": 0, "passed": 0, "failed": 0 }, "verdict": "pass|fail" }
+```
+
+Ralph-invoked 完成：`maestro ralph complete <idx> --status {STATUS} --evidence e2e-results.json`。
+
+---
+
 Follow '~/.maestro/workflows/test.md' completely.
 
 ### Phase Gates (MANDATORY, BLOCKING)
@@ -144,4 +169,5 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 - [ ] Gaps updated with root_cause, fix_direction, affected_files
 - [ ] Gap-fix loop triggered if --auto-fix (max 2 iterations)
 - [ ] Next step routed (phase-transition if pass, verify if auto-fix success, debug --from-uat if issues, test-gen if low coverage)
+- [ ] `--frontend-verify`: 每条 [UI-observable] criterion 经真实浏览器断言，产出 e2e-results.json；任一 fail → NEEDS_RETRY（不放行）
 </success_criteria>

package/.claude/skills/maestro-help/SKILL.md

@@ -269,7 +269,7 @@ Odyssey 长周期循环（独立路径）
   odyssey-debug / odyssey-improve / odyssey-review-test-fix / odyssey-planex / odyssey-ui
 
 自适应引擎（高级）
-  ralph / ralph-beta → 自运行决策循环
+  ralph → 自运行决策循环
   swarm-workflow / universal-workflow → 多 agent 并行执行
 ```
 

package/.claude/skills/maestro-help/index/catalog.json

@@ -68,7 +68,6 @@
 
     {"name": "maestro-ralph", "command": "/maestro-ralph", "category": "ralph", "description": "Ralph 引擎 — 自适应生命周期决策节点管理", "source": "../../commands/maestro-ralph.md"},
     {"name": "maestro-ralph-execute", "command": "/maestro-ralph-execute", "category": "ralph", "description": "Ralph 执行 — 运行自适应决策链", "source": "../../commands/maestro-ralph-execute.md"},
-    {"name": "maestro-ralph-beta", "command": "/maestro-ralph-beta", "category": "ralph", "description": "Ralph Beta — 自运行循环控制器，单 skill 完成 build/tick/decide", "source": "../../commands/maestro-ralph-beta.md"},
 
     {"name": "maestro-impeccable", "command": "/maestro-impeccable", "category": "ui", "description": "UI 生产 — 设计系统生成 + impeccable 链式编排 + 质量门控", "source": "../../commands/maestro-impeccable.md"},
     {"name": "maestro-ui-codify", "command": "/maestro-ui-codify", "category": "ui", "description": "UI 固化 — 将设计产出转化为知识资产", "source": "../../commands/maestro-ui-codify.md"},

package/.claude/skills/maestro-help/phases/01-parse-intent.md

@@ -61,7 +61,7 @@ const knownCommands = [
   "maestro", "analyze", "plan", "execute", "init", "roadmap",
   "brainstorm", "blueprint", "quick", "overlay", "amend", "fork", "merge", "collab",
   "milestone-audit", "milestone-complete", "milestone-release",
-  "composer", "guard", "player", "ralph", "ralph-execute", "ralph-beta",
+  "composer", "guard", "player", "ralph", "ralph-execute",
   "grill", "next", "swarm-workflow", "universal-workflow", "companion",
   "impeccable", "ui-codify", "update",
   "tools-register", "tools-execute",

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

@@ -293,7 +293,7 @@ Read `.workflow/state.json` and route by condition:
      "scope_verdict": null, "analyze_macro_id": null, "blueprint_id": null,
      "auto_mode": false,
      "context": { "issue_id": null, "scratch_dir": null, "plan_dir": null,
-       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null },
+       "analysis_dir": null, "brainstorm_dir": null, "blueprint_dir": null, "grill_id": null },
      "steps": [{
        "index": 0, "type": "skill|decision",
        "skill": "", "args": "",
@@ -328,12 +328,27 @@ Read `.workflow/state.json` and route by condition:
 
 Direct in-context skill invocation — **replaces the old spawn/wave/CSV mechanism**.
 
-1. **buildSkillCall**: replace placeholders `{phase}`/`{plan_dir}`/`{analysis_dir}`/`{brainstorm_dir}`/`{spec_session_id}`; append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map)
+1. **buildSkillCall**: replace placeholders + append auto-yes flag if `auto_mode` (see Appendix: Auto-Yes Flag Map):
+
+   | Placeholder | Source |
+   |-------------|--------|
+   | `{phase}` | session.phase |
+   | `{plan_dir}` | session.context.plan_dir |
+   | `{analysis_dir}` | session.context.analysis_dir |
+   | `{brainstorm_dir}` | session.context.brainstorm_dir |
+   | `{spec_session_id}` | session.context.spec_session_id |
+   | `{GRL}` | session.context.grill_id |
+   | `{ANL}` | session.analyze_macro_id |
+   | `{BLP}` | session.blueprint_id |
+   | `{intent}` | session.intent |
+
+   **--from auto-injection**: 当 step 是 `maestro-plan`，args 含 `{phase}` 但无 `--from` 且无 `--dir`，且 `session.context.analysis_dir` 已填充 → 查 state.json 同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `step.source_artifact_ref`
 2. Mark step `status="running"`, persist status.json + `update_plan` (this step → in_progress)
 3. **Invoke the skill directly**: execute `$skill {resolved_args}` in coordinator context (NO spawn). Read its produced artifacts directly
 4. On success: capture summary; mark step `status="done"`. **Barrier-context update** (when step is a context-producing skill):
    | Skill | Read | Context Updates |
    |-------|------|-----------------|
+   | maestro-grill | grill-report.md, state.json | grill_id |
    | maestro-analyze | context.md, state.json | analysis_dir, gaps, phase |
    | maestro-plan | plan.json, .task/TASK-*.json | plan_dir, task_count |
    | maestro-brainstorm | .brainstorming/ | brainstorm_dir, features |

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-analyze
 description: Use when a topic needs structured multi-dimensional investigation before planning or decision-making
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] [--from <source>] \"<phase|topic> [-q|--quick] [--gaps [ISS-ID]]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -23,14 +23,22 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents per wave (default: 6)
+- `--concurrency N`: Max concurrent agents per wave (default: 6)
+- `-c, --continue`: Resume existing session
 - `--continue`: Resume existing session
 - `-q, --quick`: Skip exploration + scoring, Wave 3 only
 - `--gaps [ISS-ID]`: Issue root cause analysis. If ISS-ID: single issue. If omitted: all open/registered from issues.jsonl.
-- `--from <source>`: Load upstream context package (brainstorm:ID, analyze:ID, @file, or path). Resolves to context-package.json for upstream context inheritance.
+- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, analyze:ID, blueprint:BLP-xxx, @file, or path). Resolves to context-package.json via state.json artifact lookup for typed references, or direct path for @file/path.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/`
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, context-package.json (all modes), analysis.md + conclusions.json (full mode AND quick mode; quick writes minimal conclusions.json with `scope_verdict` + `implementation_scope[]` only)
+
+### Pre-load (runs unconditionally, including -y auto mode)
+1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
+2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
+4. **Role Knowledge**: `maestro search --category debug` → select relevant → `maestro wiki load`
+5. All optional — proceed without if unavailable (log warning)
 </context>
 
 <interview_protocol>
@@ -310,8 +318,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
 - [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-brainstorm
 description: Use when exploring ideas, evaluating approaches, or needing multi-perspective analysis before implementation
-argument-hint: "[topic] [-y|--yes] [-c|--concurrency N] [--continue] [--count N] [--skip-questions] [--review-only]"
+argument-hint: "[topic] [-y|--yes] [--concurrency N] [-c|--continue] [--count N] [--skip-questions] [--review-only]"
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -15,14 +15,31 @@ Wave 3 compares Decision Digests from each role's `analysis.md` §2 and patches
 <context>
 $ARGUMENTS — topic text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 6), `--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md)
+**Flags**: `-y` (auto), `--concurrency N` (default 6), `-c`/`--continue` (resume), `--count N` (roles, default 3 max 9), `--skip-questions`, `--review-only` (skip Wave 1/2; run Wave 3 only against existing */analysis.md), `--from <source>` (load upstream context package)
+
+**--from resolution** (upstream context loading):
+```
+--from grill:ID     → state.json.artifacts[type=grill, id=ID].context_package → load context-package.json
+--from blueprint:ID → state.json.artifacts[type=blueprint, id=ID].context_package → load
+--from @file        → load file directly as context-package.json
+--from path/        → load path/context-package.json
+```
+When loaded, pre-seed guidance-specification.md with:
+- `constraints[status=locked]` → §4 locked decisions (skip in interview)
+- `domain.terminology[]` → §2 Concepts & Terminology (seed)
+- `non_goals[]` → §3 Non-Goals (seed)
+- `open_questions[]` → interview priority topics
+- `insights[]` → W2 role analysis context
+
+When `--from` is absent, auto-discover from state.json: latest `type=grill` artifact in same milestone → load its `context_package` if available. No match → proceed without upstream context.
 
 **9 valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
-### Pre-load specs
+### Pre-load
 1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
 2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
-3. Both optional — proceed without if unavailable.
+3. **Project context**: Read `.workflow/project.md` (if exists) → Validated requirements (already shipped) as constraints, Active requirements as current scope. Read `state.json.accumulated_context` → deferred items as brainstorming seeds, key_decisions as locked constraints.
+4. All optional — proceed without if unavailable.
 
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/`
 
@@ -432,8 +449,17 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] discoveries.ndjson append-only throughout
 - [ ] context.md aggregates session results with next-step routing
 - [ ] Session sealed via finish-work (auto mode only)
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-execute
 description: Use when a confirmed plan is ready for implementation
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<phase> [--auto-commit] [--method agent|cli] [--dir <path>]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -75,8 +75,8 @@ $maestro-execute --continue "20260318-execute-P3-phase3"
 
 **Flags**:
 - `-y, --yes`: Skip all confirmations (auto mode)
-- `-c, --concurrency N`: Max concurrent agents within each wave (default: 5)
-- `--continue`: Resume existing session
+- `--concurrency N`: Max concurrent agents within each wave (default: 5)
+- `-c, --continue`: Resume existing session
 
 **Inner flags** (passed inside quotes):
 - `--auto-commit`: Atomic git commit after each task completion
@@ -335,6 +335,28 @@ After each wave: if blocked tasks exist, prompt user to continue or stop (AUTO_Y
 
 Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with error "Dependency {dep_id} blocked/failed".
 
+### Phase 2.5: Verification Gate
+
+**Objective**: Cross-validate execution results against convergence criteria using external model perspective.
+
+1. **Collect verification targets**: For each completed task, read `.summaries/TASK-{NNN}-summary.md` + convergence criteria from `.task/TASK-{NNN}.json`
+2. **Delegate verification**: Run `maestro delegate` with accumulated evidence:
+   ```
+   maestro delegate "PURPOSE: 验证执行结果是否满足 convergence criteria
+   TASK: 逐项检查 | 对照 criteria | 标注 pass/fail | 汇总 gaps
+   CONTEXT: @.summaries/ @.task/
+   EXPECTED: verification.json { tasks: [{ id, criteria_met: bool, gaps: [] }], overall_pass: bool }
+   CONSTRAINTS: 只验证不修改" --role analyze --mode analysis
+   ```
+3. **Write verification.json** to plan directory with per-task pass/fail and gap list
+4. **Gate decision**:
+   - `overall_pass == true` → proceed to Phase 3
+   - Critical gaps (task criteria all failed) → log warning, mark affected tasks as `needs_retry`
+   - Non-critical gaps → record as `concerns` in verification.json, proceed
+5. **Register VRF artifact**: `{ id: "VRF-{next}", type: "verify", scope, path: verification.json, depends_on: "EXC-{id}" }`
+
+Skip Phase 2.5 when `--skip-verify` flag present or task count == 0.
+
 ### Phase 3: Results Aggregation
 
 **Objective**: Update all state files and generate execution report.

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

@@ -110,8 +110,17 @@ Resume routing:
 - [ ] `context-package.json` generated with schema "context-package/1.0"
 - [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
 - [ ] Session sealed via finish-work
+- [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>
 
+<ralph_completion>
+When invoked as a ralph session step, end by calling the CLI (no standalone report):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
+</ralph_completion>
+
 <on_complete>
 @~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
 </on_complete>

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-plan
 description: Use when creating, revising, or verifying an execution plan for a phase or task
-argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
+argument-hint: "[-y|--yes] [--concurrency N] [-c|--continue] \"<phase> [--dir <path>] [--from <source>] [--gaps] [--spec SPEC-xxx] [--collab]\""
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
@@ -65,7 +65,7 @@ All mean: **follow the cycle anyway**.
 <context>
 $ARGUMENTS — phase number/text and optional flags.
 
-**Flags**: `-y` (auto), `-c N` (concurrency, default 4), `--continue` (resume), `--dir <path>`, `--from <source>` (load upstream context directly: analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, path), `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
+**Flags**: `-y` (auto), `--concurrency N` (default 4), `-c`/`--continue` (resume), `--dir <path>`, `--from <source>` (load upstream context directly: analyze:ANL-xxx, blueprint:BLP-xxx, brainstorm:ID, @file, path), `--gaps` (issue-linked), `--spec SPEC-xxx`, `--collab`, `--revise`, `--check`, `--tdd` (RED-GREEN-REFACTOR task chains)
 
 **Scope routing** (priority, per redesign §5.2):
 1. `--from analyze:ANL-xxx` → CONTEXT_DIR = ANL artifact path; scope=`standalone`
@@ -89,6 +89,14 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
 **Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+
+**D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
+```
+milestone_id = "ADH-{YYYYMMDD}-{slug}"
+state.json.milestones.push({ id: milestone_id, name: "{intent slug}", type: "adhoc", status: "active", phase_slugs: [] })
+state.json.current_milestone = milestone_id
+```
+**Exception**: `--from analyze:ANL-xxx` or `--from blueprint:BLP-xxx` → skip adhoc creation (upstream artifact provides milestone context or is intentionally milestone-free).
 </context>
 
 <csv_schema>
@@ -197,7 +205,22 @@ Each explores one angle: architecture (module boundaries, deps), patterns (simil
 Consumes all exploration findings + context.md + specs. Produces:
 - `plan.json`: summary, approach, task_ids, waves (with phase labels), confidence section
 - `.task/TASK-*.json`: each with read_first[], convergence.criteria[] (grep-verifiable), concrete action/implementation
-- Deep Work Rules: every task has read_first with file being modified + source of truth files
+
+**Deep Work Rules** (MANDATORY for every task):
+1. `read_first[]`: MUST contain the file being modified + source-of-truth files (tests, interfaces, schemas)
+2. `convergence.criteria[]`: MUST be grep-verifiable (e.g., `"src/auth.ts contains export function verifyToken("`) — no subjective language ("well-structured", "properly implemented")
+3. `action`: concrete implementation verb (create/modify/delete/refactor) + target path
+4. `implementation[]`: ordered steps with file:change pairs — each step < 60 min
+- Anti-pattern: `"Implement the feature"` (vague). Correct: `"Create src/auth.ts with verifyToken() and generateToken() functions using jsonwebtoken"`
+- Anti-pattern: `read_first: []` (empty). Every file change requires reading the target first.
+
+**Anti-splitting Rules**:
+1. One feature = one task (don't split "create auth module" into "create file" + "add exports")
+2. Group trivial changes (< 5 min each) into a single task
+3. `depends_on` only for genuine data/API dependencies, not arbitrary sequencing
+4. Task count guards: simple scope → 1-2 tasks, medium → 2-4, complex → 4-8
+
+**UI-observable criteria**: If plan touches UI paths (components/, pages/, styles/) or frontend keywords, at least 1 convergence criterion per delivery wave MUST be UI-observable (e.g., `"page renders without console errors"`, `"button click triggers API call"`).
 
 Verifies plan.json and every .task/*.json exists on disk before reporting completed; else report blocked.
 

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

@@ -426,6 +426,9 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
     - `analyze_macro_id` 存在且当前 step 是 `roadmap` → args 改为 `--from analyze:{analyze_macro_id}`
     - `analyze_macro_id` 存在且 `scope_verdict ∈ {medium, small}` 且当前 step 是 `plan` → args 改为 `--from analyze:{analyze_macro_id}`
     - `blueprint_id` 存在 → 当前 step 是 `plan` → args 改为 `--from blueprint:{blueprint_id}`（优先级低于 phase 数字参数）
+    - **phase-level deferred chaining**（独立模式，step 含 `{phase}` 占位符）：build 阶段前序 artifact 尚未产出，由 A_RESOLVE_ARGS（ralph-execute）运行时从 state.json 查找同 phase+milestone 最新 completed artifact 注入：
+      - `plan` step → `--from analyze:{phase_analyze_id}`，写 `source_artifact_ref`
+      - `execute` step → `--dir {plan_path}`（现有逻辑），写 `source_artifact_ref = "plan:{id}"`
     - 写入 `step.source_artifact_ref` 以便审计
 13. **D-007 Milestone-ref 标注**：每个含 `{phase}` 占位符的 step → `step.milestone_id = session.milestone`（由 A_RESOLVE_PHASE 反查得出），禁止读 `current_milestone`
 14. **动态插入步骤**（A_APPLY_*）同样应用规则 7-13
@@ -761,5 +764,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
 - [ ] Ralph 不执行 step，只 evaluate；`$maestro-ralph-execute` 直调 handoff
 - [ ] session.platform = "codex"；所有 CLI 调用携带 `--platform codex`
+- [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
+- [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
+- [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
 
 </appendix>