maestro-flow 0.5.34 → 0.5.36

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

@@ -27,6 +27,7 @@ Produces plan.json + TASK files; registers PLN artifact in state.json.
 - [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
 - [task.json](~/.maestro/templates/task.json) — read when generating task files
 - [state.json](~/.maestro/templates/state.json) — read when registering artifact
+- [boundary-grill.md](~/.maestro/workflows/boundary-grill.md) — read when boundary conflicts detected (in P4)
 </deferred_reading>
 
 <context>
@@ -52,7 +53,7 @@ Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), outpu
 
 **Ad-hoc milestone (D-008):** When scope resolves to "standalone" via the standard standalone resolution (no `--from` source), and `current_milestone == null`, plan auto-creates an adhoc milestone (`type: "adhoc"`) in state.json before proceeding. This ensures downstream milestone-audit/complete have a valid milestone context. See workflow plan.md § "Ad-hoc Milestone Auto-Creation".
 
-**Exception (`--from analyze:ANL-xxx` / `blueprint:BLP-xxx`):** When scope is set to "standalone" by `--from`, skip adhoc milestone auto-creation — the upstream analyze/blueprint artifact already provides the milestone context (or is intentionally milestone-free). Adhoc creation in this path would conflict with the `--from` semantic of "this is a one-shot plan rooted in an existing artifact".
+**`--from analyze:*` / `blueprint:*`**: scope=standalone → skip adhoc milestone auto-creation.
 
 ### Role Knowledge
 `maestro search --category arch` → select relevant → `maestro wiki load`
@@ -86,11 +87,19 @@ Follow '~/.maestro/workflows/plan.md' completely.
 - REQUIRED: Main flow inline planning is FORBIDDEN (see P3 Agent Constraint below).
 - BLOCKED if missing: plan.json or TASK files not produced by planner agent — do not proceed to checking.
 
+**GATE P3.5 → P4: Boundary Grill → Plan Check**
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md`.
+Input: plan.json tasks + convergence criteria + upstream context. Scope guard: "only plan scope; do not re-analyze or re-scope".
+IF conflicts → results to plan.json `boundary_grill` section + affected TASK files. DEC conflicts add `boundary_warning` to confidence.
+NON-BLOCKING: warnings, not hard stops.
+
 **GATE P4 → P5: Plan Check → User Confirmation**
 - REQUIRED: Plan-checker passed (or minor issues acknowledged).
+- REQUIRED: Boundary grill completed (conflicts resolved or accepted as risks).
 - REQUIRED: Confidence scored with 5-dimension factor model.
 - REQUIRED: Pressure pass completed on highest-complexity task.
-- BLOCKED if: plan-checker found critical issues — fix plan before presenting to user.
+- REQUIRED: If plan touches UI (检出 `dashboard/` 或 UI 关键词 `landing|page|dashboard|frontend|UI|component|界面`), each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical-slice delivery, not backend-only).
+- BLOCKED if: plan-checker found critical issues, OR UI plan missing `[UI-observable]` coverage — fix plan before presenting to user.
 
 **GATE P5 → Completion: User Confirmation → Done**
 - REQUIRED: User confirmation captured (execute/modify/cancel).
@@ -152,8 +161,6 @@ For each created TASK-{NNN}.json that has issue_id:
   Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
 ```
 
-This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
-
 ### Mode: Revise / Check
 
 Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
@@ -215,7 +222,11 @@ Status verdicts:
 - [ ] .task/TASK-*.json files created for each task
 - [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
 - [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] UI plans: each delivery wave has ≥1 `[UI-observable]` convergence criterion (vertical slice; verified at runtime by ralph frontend-verify gate)
 - [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Boundary grill executed in P3.5 (skip if no conflicts detected)
+- [ ] Boundary grill results written to plan.json `boundary_grill` section (if conflicts found)
+- [ ] DEC conflicts reflected in confidence `boundary_warning` factor
 - [ ] Plan confidence scored in P4 with 5-dimension factor model
 - [ ] Plan readiness gate checked before P4.5 collision detection
 - [ ] Pressure pass completed on highest-complexity task

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

@@ -24,7 +24,8 @@ $ARGUMENTS — intent text, flags, or keywords.
 
 **Parse:**
 ```
--y flag       → auto_confirm = true
+-y flag       → auto_confirm = true   # 唯一来源：用户显式传入；ralph 不内部推断（invariant 14）
+--roadmap     → wants_roadmap = true (强制多发布 roadmap 路径；roadmap 默认 opt-in)
 .md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
 Remaining     → intent
 ```
@@ -49,6 +50,9 @@ Remaining     → intent
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段可选/累加，既有字段不删不改
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作。不得以 "效率" 或 "意图明确" 为由绕过。特别是 invariant 1（ralph 不执行 step）和 invariant 6（completion_confirmed 由 CLI 写入）不可隐性违反。
 13. **Delegate fallback 必须标记** — A_DELEGATE_EVALUATE 解析 verdict 失败时 fallback 为 "fix"，但 MUST 在 decisions.ndjson 记录 `"parse_failed": true, "confidence_score": 0`，后续 step 继承 LOW CONFIDENCE 标记。
+14. **auto_confirm 单一来源** — `auto_confirm` 仅由用户 `-y` 标志设定；ralph 不得内部推断。`session.auto_mode` 仅反映用户输入。
+15. **分解契约单一所有者** — `boundary_contract` / `task_decomposition` 由 session 创建者拥有（`source=="ralph"` → `decomposition_owner="ralph"`；`source=="maestro"` → `"maestro"`）。contract 已存在时，后续 S_DECOMPOSE MUST 跳过 ask_user，仅做 shape 校验 + 缺省补齐；goal-audit 只更新 `task_decomposition[*].status/completion_confirmed/completed_at`，禁止改 `goal/done_when/boundary`。
+16. **控制权优先级（范式治理）** — FSM 独占 session 生命周期 + step 排序 + retry/fix/escalate + cross-step decision 节点；Pipeline 命令只拥有自身 artifact GATE（GATE 失败 → `maestro ralph complete <idx> --status BLOCKED|NEEDS_RETRY`，自身 GATE 全过 → DONE）；Router 命令不得出现在 FSM step 内。
 </invariants>
 
 <state_machine>
@@ -58,7 +62,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
@@ -130,7 +134,7 @@ S_DISPATCH:
   → END             DO: invoke_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
@@ -138,11 +142,14 @@ S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取
                      DO: A_SCOPE_EVALUATE
   → S_APPLY_VERDICT WHEN: structural (post-milestone, post-debug-escalate)
                      DO: A_STRUCTURAL_EVALUATE
+  → S_APPLY_VERDICT WHEN: reground-gate (post-reground)
+                     DO: A_REGROUND_EVALUATE
 
 S_APPLY_VERDICT:
   → S_DISPATCH      WHEN: verdict == "proceed"              DO: A_APPLY_PROCEED
-  → S_DISPATCH      WHEN: post-goal-audit + unmet sub-goals  DO: A_APPLY_GOAL_FIX
-  → S_DISPATCH      WHEN: post-goal-audit + all sub-goals met DO: A_APPLY_GOAL_DONE
+  → S_DISPATCH      WHEN: post-goal-audit + has_unmet         DO: A_APPLY_GOAL_FIX
+  → S_DISPATCH      WHEN: post-goal-audit + all_met + INTENT_ALIGNED=true  DO: A_APPLY_GOAL_DONE
+  → END             WHEN: post-goal-audit + all_met + INTENT_ALIGNED=false DO: A_REGROUND_HALT（尾部漂移熔断）
   → S_DISPATCH      WHEN: post-analyze-scope                 DO: A_APPLY_SCOPE_VERDICT
   → S_DISPATCH      WHEN: verdict == "fix"                  DO: A_APPLY_FIX
   → S_DISPATCH      WHEN: verdict == "escalate"             DO: A_APPLY_ESCALATE
@@ -150,11 +157,15 @@ S_APPLY_VERDICT:
   → END             WHEN: post-milestone + standard + no next milestone DO: mark completed
   → END             WHEN: post-milestone + adhoc                       DO: mark completed (adhoc self-contained)
   → END             WHEN: post-debug-escalate (always STOP)  DO: A_PAUSE_ESCALATE
+  → END             WHEN: post-reground + drifted + confidence_score >= 60  DO: A_REGROUND_HALT
+  → S_DISPATCH      WHEN: post-reground + aligned                           DO: A_APPLY_PROCEED
+  → S_DISPATCH      WHEN: post-reground + drifted + confidence_score < 60   DO: A_APPLY_PROCEED (标 LOW CONFIDENCE)
   GUARD: retry_count >= max_retries → force escalate
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
   GUARD: not auto_confirm → ask_user with override options
+  GUARD: post-reground + drifted + confidence_score >= 60 → A_REGROUND_HALT（漂移熔断为安全门，auto_confirm 不跳过）
 
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: ask_user
@@ -212,11 +223,19 @@ resolve_milestone(phase_number):
 
 | Pattern | Position |
 |---------|----------|
-| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时跳过，直接 `brainstorm`**） |
+| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时透传 `-y`，grill 以 Auto mode 代码代答，不跳过**） |
 | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
 | 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 |
@@ -231,7 +250,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` |
@@ -252,9 +271,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:**
 
@@ -266,7 +285,8 @@ resolve_milestone(phase_number):
 | passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
-| uat.md: all passed | `milestone-audit` |
+| uat.md: all passed + `session.milestone` 存在 | `milestone-audit` |
+| uat.md: all passed + `session.milestone=null` (standalone) | 标记 session completed（无 milestone 可审计） |
 | uat.md: has failures | `test-failed` |
 
 ### A_DETERMINE_QUALITY_MODE
@@ -311,7 +331,9 @@ options:
 
 ### A_DECOMPOSE_TASKS
 
-Runs once before chain build; additive to status.json.
+Runs once before chain build; additive to status.json. 设 `session.decomposition_owner = "ralph"`。
+
+**0. Ownership guard** (invariant 15): 若 `session.boundary_contract` 或 `session.task_decomposition` 已非空（上游 maestro 已写入，`decomposition_owner == "maestro"`）→ MUST 跳过下述提问，仅做 shape 校验 + 缺省字段补齐，直接进入步骤 6。
 
 **1. Classify intent breadth:**
 
@@ -337,10 +359,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`。
 
@@ -348,11 +370,11 @@ narrow → derive defaults from intent + codebase, skip questions.
 
 ### A_BUILD_STEPS
 
-Generate steps from `session.lifecycle_position` to `milestone-complete`.
+Generate steps from `session.lifecycle_position` to `milestone-complete`（`session.milestone` 存在时）或最后一个质量门（standalone 时）。
 
 | Stage | invoke_skill(independent) | invoke_skill(unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
-| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
+| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**auto_confirm → 透传 `-y` 到 grill args，不删除 stage**) |
 | brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
 | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
 | init | `maestro-init` | *(same)* | — | all |
@@ -366,6 +388,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 |
@@ -379,10 +402,12 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 1. **起点**：从 `session.lifecycle_position` 开始
 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.5. **grill auto_confirm 透传**：`auto_confirm == true` 时为 `grill` step args 追加 `-y`（grill 自身 Auto mode 用代码代答，见 maestro-grill `<context>` Mode selection）；保留 `grill` stage 与 brainstorm 的 `--from grill:*`（grill 仍产出 grill-report/terminology/context-package）
+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` 结尾
+5.5. **re-grounding 插入**：当 `task_decomposition` 存在 **且** 链路含 ≥3 个执行 step（不含 decision 节点）时，从第 3 个执行 step 起每隔 3 个执行 step 后插入 `{ decision: "post-reground", retry_count: 0, max_retries: 0, command_scope: null, command_path: null }`。不在最后一个执行 step 之后插入（由 goal-audit 覆盖）；不与已有 quality-gate decision 节点相邻（顺延到下一个 3-step 边界）；fix-loop 动态插入的 step（index > 原始 chain 长度）不纳入计数
+6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
 9. **command_path 解析**（每个执行 step，decision 节点跳过）：
@@ -394,13 +419,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
@@ -423,6 +451,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):
    ```
@@ -481,14 +510,18 @@ Runs only when `task_decomposition` present.
      1. 读取 status.json.task_decomposition 中 status!=done 的子目标
      2. 打开 evidence 产物，对照 done_when 严格判定
      3. 输出 met / unmet，unmet 给出 gap + target_phase
+     4. 对照 intent + definition_of_done 判定累积产出是否仍服务原始意图（意图保真检查）
    CONTEXT:
-     status.json   = {session_dir}/status.json
-     evidence      = {evidence artifacts}
+     status.json        = {session_dir}/status.json
+     intent             = {session.intent}
+     definition_of_done = {boundary_contract.definition_of_done}
+     evidence           = {evidence artifacts}
      execution_criteria = {execution_criteria}
      boundary_contract  = {boundary_contract}
    EXPECTED:
      ---VERDICT---
      STATUS=all_met|has_unmet
+     INTENT_ALIGNED=true|false
      UNMET=[{id:G2,gap:'...',target_phase:execute}, ...]
      CONFIDENCE_SCORE=0-100
      ---END---
@@ -501,9 +534,64 @@ Runs only when `task_decomposition` present.
    ```
 4. On callback: 对每个 met 子目标，set `task_decomposition[i].status="done"` + `completion_confirmed=true` + `completed_at=now`
 5. Append `{session_dir}/decisions.ndjson` with `"type": "goal-gate"`, `unmet_count`, `unmet_ids`
-6. Verdict: `all_met` → A_APPLY_GOAL_DONE; `has_unmet` → A_APPLY_GOAL_FIX
+6. Verdict routing:
+   - `all_met` + `INTENT_ALIGNED=true` → A_APPLY_GOAL_DONE
+   - `all_met` + `INTENT_ALIGNED=false` → A_REGROUND_HALT（尾部漂移熔断，auto_confirm 不跳过）
+   - `has_unmet` → A_APPLY_GOAL_FIX
    GUARD: retry_count >= max_retries AND still unmet → A_APPLY_ESCALATE
 
+### A_REGROUND_EVALUATE
+
+仅当 `task_decomposition` 存在。周期触发（build rule 5.5）。
+
+1. 从 status.json 读取：`session.intent`、`session.boundary_contract`、`steps[]` 中 `status=="completed"` 的 step + `completion_evidence`、`task_decomposition` 中已 done 子目标的 `goal` + `done_when`
+2. Delegate read-only audit (run_in_background, STOP, wait):
+   ```
+   maestro delegate "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
+   TASK:
+     1. 读取 intent + boundary_contract.definition_of_done
+     2. 读取已完成 steps 的 completion_evidence + 已 done 子目标 done_when
+     3. 判定累积产出是否仍服务 intent；是否有 step 产出超出 in_scope 或触碰 out_of_scope
+     4. 输出 aligned / drifted，drifted 给出 drift_description + corrective_action
+   CONTEXT:
+     intent             = {session.intent}
+     definition_of_done = {boundary_contract.definition_of_done}
+     in_scope           = {boundary_contract.in_scope}
+     out_of_scope       = {boundary_contract.out_of_scope}
+     completed_steps    = [{index, skill, stage, completion_evidence}, ...]
+     done_goals         = [{id, goal, done_when}, ...]
+   EXPECTED:
+     ---VERDICT---
+     STATUS=aligned|drifted
+     DRIFT_DESCRIPTION=<空或具体描述>
+     CORRECTIVE_ACTION=<空或建议>
+     CONFIDENCE_SCORE=0-100
+     ---END---
+   CONSTRAINTS:
+     - 只评估，不修改文件
+     - aligned 阈值：≥80% 已完成产出直接服务 intent
+     - 单个 step 触碰 out_of_scope → 直接判 drifted"
+   --role analyze --mode analysis
+   ```
+3. On callback: parse verdict
+4. Append `{session_dir}/decisions.ndjson`：`{ "id": "DEC-{ts}", "type": "reground-gate", "source": "ralph", "node_id": "post-reground", "verdict": "{aligned|drifted}", "confidence_score": {N}, "drift_description": "...", "corrective_action": "..." }`
+5. Verdict routing：`aligned` → A_APPLY_PROCEED；`drifted` + `confidence_score >= 60` → A_REGROUND_HALT；`drifted` + `confidence_score < 60` → A_APPLY_PROCEED（标 LOW CONFIDENCE）
+
+### A_REGROUND_HALT
+
+漂移熔断（安全门，auto_confirm 不跳过）。
+
+1. Set `session.status = "paused"`，write status.json
+2. Display:
+   ```
+   ⚠️ Re-grounding 检测失败 — 执行已偏离 intent。
+   Intent: {session.intent}
+   Drift:  {drift_description}
+   建议回归: {corrective_action}
+   选项：1) /maestro-ralph continue 忽略漂移继续  2) 手动修正后 continue  3) /maestro-ralph status 查看后决定
+   ```
+3. GUARD: auto_confirm 对本动作无效——漂移熔断不可自动跳过
+
 ### A_APPLY_PROCEED
 
 1. Mark decision completed, write status.json
@@ -524,14 +612,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 → ask_user 二选一（large / medium-small）；auto_confirm → 默认 large
+   - 非 auto_confirm → ask_user 二选一（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}}
 
@@ -578,9 +666,12 @@ Runs only when `task_decomposition` present.
   "phase": null, "phase_is_new": false,
   "milestone": "",                // D-007 反查结果，禁止读 current_milestone
   "auto_mode": false,
+  "decomposition_owner": "ralph", // 分解契约所有者（invariant 15）；缺省按 source 推断
+
   "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": [],
@@ -672,6 +763,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,14 +818,15 @@ decision:post-goal-audit {retry+1}
 - [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
 - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
 - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
-- [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
+- [ ] auto_confirm=true 时 grill step args 追加 `-y`（grill 以 Auto mode 执行，stage 不跳过，产出 grill-report/terminology/context-package）
 - [ ] 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 agent --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
@@ -739,5 +840,8 @@ decision:post-goal-audit {retry+1}
 - [ ] Chain 必须以 `milestone-complete` 结尾
 - [ ] Decision nodes 由 maestro delegate --role analyze 评估
 - [ ] Ralph 不执行 step，只 evaluate；invoke_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/.agents/skills/maestro-ralph-execute/SKILL.md

@@ -136,19 +136,44 @@ S_FALLBACK:
 | maestro-brainstorm | topic | `"{intent}"` |
 | maestro-roadmap | description | `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` |
-| maestro-plan | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
-| maestro-execute | phase or --dir | `{phase}`, or `--dir {scratch_dir}` |
+| maestro-plan | phase, --from, or --dir | see --from auto-injection below |
+| maestro-execute | phase or --dir | see --from auto-injection below |
 | quality-debug | gap context | Read previous step's error/gap |
 | quality-* | phase | `{phase}` |
 
-**Artifact dir resolution for --dir:**
+**--from auto-injection (phase-level artifact chaining):**
+
+Phase-level steps 在 build 阶段无法预知前序 artifact ID。A_RESOLVE_ARGS 运行时从 state.json 查找并注入显式引用，打通 analyze→plan→execute 数据管道：
+
 ```
-Read state.json → filter artifacts by milestone + phase
-plan commands: latest type=="analyze" → --dir .workflow/scratch/{path}
-execute commands: latest type=="plan" → --dir .workflow/scratch/{path}
+Read state.json.artifacts（含 milestone_history 内归档 artifacts）
+→ filter by milestone={session.milestone} + phase={session.phase} + status=="completed"
+
+plan step（含 {phase} 占位符，args 无 --from 且无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="analyze" artifact → id = ANL-xxx
+  2. 命中 → args 追加 --from analyze:{id}
+  3. 写 step.source_artifact_ref = "analyze:{id}"
+
+execute step（含 {phase} 占位符，args 无 --dir）:
+  1. 查同 phase+milestone 最新 completed type=="plan" artifact → id = PLN-xxx, path = scratch/...
+  2. 命中 → args 追加 --dir .workflow/scratch/{path}
+  3. 写 step.source_artifact_ref = "plan:{id}"
 ```
 
-Write enriched args back to status.json.
+兜底：查询无结果 → 不注入，由命令自身 discovery 逻辑处理。已有 `--from` 或 `--dir` 的 step 不覆盖。
+
+**Goal context injection:**
+
+当 step.goal_ref 非空且 session.task_decomposition 存在时：
+```
+goal = session.task_decomposition.find(g => g.id == step.goal_ref)
+if goal:
+  goal_snippet = { id: goal.id, goal: goal.goal, done_when: goal.done_when,
+                   boundary: goal.boundary, evidence: goal.evidence }
+  → 传递给 A_EXEC_STEP 用于 inline execution 前注入（见 step 2 goal context pre-injection）
+```
+
+Write enriched args + source_artifact_ref back to status.json.
 
 ### A_EXEC_DECISION
 
@@ -164,13 +189,24 @@ Write enriched args back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-3. **Complete**:
+2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+   ```
+   <goal_context>
+   Sub-goal: {goal.id} — {goal.goal}
+   Done when: {goal.done_when}
+   Boundary: {goal.boundary}
+   Evidence target: {goal.evidence}
+   Execution criteria: {session.execution_criteria joined by '; '}
+   </goal_context>
+   ```
+   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
+3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+4. **Complete**:
    - `shell("maestro ralph complete N --status DONE [--evidence <path>]")`
    - `shell("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
    - `shell("maestro ralph retry N")`
    - `shell("maestro ralph complete N --status BLOCKED --reason \"...\"")`
-4. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
+5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `invoke_skill({ skill: "maestro-ralph-execute" })` 自调用。
 
@@ -246,5 +282,10 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] Context signals 由执行 step 显式写回 status.json.context（非 ralph-execute 内嵌扫描）
 - [ ] Auto mode: retry 一次后 pause；interactive 提供 retry/skip/abort
 - [ ] 自调用持续到全部 completion_confirmed 或 paused
+- [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
+- [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
+- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
+- [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
 
 </appendix>

package/.agents/skills/maestro-tools-register/SKILL.md

@@ -70,12 +70,8 @@ Parse $ARGUMENTS to determine mode:
 - Update frontmatter via: `maestro wiki update <id> --frontmatter '{"tool": true, "category": "<cat>", "summary": "<summary>"}'`
 - Do NOT recreate the document — modify in place
 
-**For all modes** — identify the usage timing: when should an agent or user invoke this tool? This becomes the first line of the entry description (see Step 5).
-
 ### Step 3: Determine Category
 
-**Core principle**: `category` = **who consumes this tool** (which agent type discovers and uses it), not what the content is about.
-
 | Category | Consumer Agent | Decision Question | Signal Words |
 |---|---|---|---|
 | `coding` | code-developer, workflow-executor | 开发者实现时需要这个流程吗？ | build, deploy, integrate, configure, setup, migrate, api-contract |
@@ -89,8 +85,6 @@ Parse $ARGUMENTS to determine mode:
 - API verification steps (how to test) → `category: test` (RCP-*, tool: true)
 - Ask user when ambiguous: "This tool content serves both developers and testers. Split into separate documents?"
 
-**Ambiguous cases**: Choose the **primary consumer** — the agent that would fail without this knowledge.
-
 ### Step 4: Decide Inline vs Ref
 
 - Steps <10 and no code blocks → **inline mode**

package/.agents/skills/maestro-ui-codify/SKILL.md

@@ -45,8 +45,6 @@ Load project UI conventions before extracting design system:
 maestro spec load --category ui
 ```
 
-If specs not initialized, continue without — the workflow still produces valid output.
-
 ## 2. Execute Workflow
 
 Route to `~/.maestro/workflows/ui-codify.md` and follow completely.

package/.agents/skills/manage-kg-extractors/SKILL.md

@@ -17,8 +17,6 @@ allowed-tools:
 
 <purpose>
 Analyze current repository's code patterns to auto-generate `.workflow/kg/extractors.yaml` — a declarative config that teaches MaestroGraph's codegraph extractor to recognize project-specific symbols beyond standard function/class/method declarations.
-
-Detects: builder/factory API registrations, domain constant patterns, custom decorator conventions, framework-specific patterns, module-level constants.
 </purpose>
 
 <context>

package/.agents/skills/quality-test/SKILL.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_file
   - write_file
@@ -29,6 +29,29 @@ 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`)
+
+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)
@@ -146,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/.agents/skills/spec-load/SKILL.md

@@ -77,4 +77,3 @@ Follow '~/.maestro/workflows/specs-load.md' completely.
 - [ ] Legacy entries filtered by text grep fallback
 - [ ] Results displayed with file:category references
 </success_criteria>
-</output>

package/.agents/skills/spec-setup/SKILL.md

@@ -48,4 +48,3 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
 - [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
 </success_criteria>
-</output>