maestro-flow 0.5.33 → 0.5.35

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

@@ -21,6 +21,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
 ```
@@ -54,7 +55,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
@@ -126,7 +127,7 @@ S_DISPATCH:
   → END             DO: view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph-execute/SKILL.md") + execute inline
 
 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
@@ -213,6 +214,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 |
@@ -227,7 +236,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` |
@@ -248,9 +257,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:**
 
@@ -333,10 +342,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`。
 
@@ -352,6 +361,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 | 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 |
+| spec-setup | `spec-setup` | *(same)* | — | all (**仅当 `.workflow/specs/` 不存在时插入**) |
 | analyze-macro | `maestro-analyze "{intent}"` | *(same)* | `post-analyze-scope` | all |
 | roadmap | `maestro-roadmap --from analyze:{analyze_macro_id}` | *(same)* | — | all |
 | analyze | `maestro-analyze {phase}` | `maestro-analyze` | — | all |
@@ -361,6 +371,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 |
@@ -370,10 +381,12 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 **Build rules (按顺序应用):**
 
 0. **planning_mode 选列**：`unified` → Skill (unified) 列；`independent` → Skill (independent) 列
+0.5. **specs 预检**：当 `lifecycle_position ∉ {grill, brainstorm, blueprint, init}` 且 `.workflow/specs/` 目录不存在时，在链路最前面插入 `spec-setup` 步骤（stage=`spec-setup`，无 decision）。确保下游 analyze/plan/execute 可获得项目约束规则注入
 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.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` 结尾
@@ -388,13 +401,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
@@ -404,7 +420,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 **Goal Prompt block** (Appendix)，不阻塞流程，继续 handoff
+4. **Goal Prompt 显示（强制）**：`task_decomposition` 存在时，chain overview 之后**必须逐字显示** Goal Prompt block（Appendix），不得省略或摘要。显示后继续 handoff，不阻塞
 
 ### A_DELEGATE_EVALUATE
 
@@ -417,6 +433,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):
    ```
@@ -518,14 +535,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_question 二选一（large / medium-small）；auto_confirm → 默认 large
+   - 非 auto_confirm → ask_question 二选一（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}}
 
@@ -575,6 +592,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": [],
@@ -666,6 +684,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:
@@ -682,7 +709,11 @@ decision:post-goal-audit {retry+1}
 ```
 📋 任务分解完成。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
 
-/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 完成以下子目标：
+{for each G in task_decomposition:}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+直到 {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 输出提示词后继续 handoff，不阻塞。
@@ -710,12 +741,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 agy --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
@@ -725,8 +757,12 @@ decision:post-goal-audit {retry+1}
 - [ ] post-goal-audit decision 仅在 decomposed 时插入，位于 milestone-complete 之前
 - [ ] Unmet sub-goals 动态 grow steps[]（goal_ref tagged）；max retries → escalate
 - [ ] planning_mode 显式决定；unified=无 `{phase}`, independent=带 `{phase}`
+- [ ] specs 预检：lifecycle_position 在 init 之后 + `.workflow/specs/` 不存在 → 链路最前面插入 `spec-setup`
 - [ ] 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/.agy/skills/maestro-ralph-execute/SKILL.md

@@ -51,6 +51,7 @@ HARD RULES:
 7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
 8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`；`NEEDS_CONTEXT` 已废除
 9. **CLI 输出禁止截断** — `maestro ralph next` 的 stdout 包含完整 skill prompt，必须全量捕获。**严禁** `| head`、`| tail`、`2>&1 | head -N` 等任何截断管道。Bash timeout 可加长但不可截断输出
+10. **禁止以上下文消耗为由中断自调用链** — harness 自动处理 context compression（消息摘要），模型无需判断上下文剩余空间。自调用链的唯一合法终止条件是：全部 `completion_confirmed`、session paused、或 decision handoff 到 ralph。以"上下文不足"、"已连续完成 N 个 step"、"避免 context overflow"等理由中断属于 invariant violation
 </invariants>
 
 <state_machine>
@@ -131,19 +132,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
 
@@ -159,13 +185,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**:
    - `run_command("maestro ralph complete N --status DONE [--evidence <path>]")`
    - `run_command("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
    - `run_command("maestro ralph retry N")`
    - `run_command("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 触发 `view_file(AbsolutePath="<agy-skills-dir>/maestro-ralph-execute/SKILL.md") + execute inline` 自调用。
 
@@ -241,5 +278,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/.agy/skills/manage-harvest/SKILL.md

@@ -46,6 +46,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
 3. **Never modify source artifacts** — harvest is purely extractive.
 4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
+5. **Conflict pre-check on spec routing** — when routing to spec (Stage 6b), compare new entry against existing specs with same keywords/category. If semantic conflict detected, set `confidence="low"` on the new entry and log conflict note. Use `maestro spec conflict mark` if contradiction is clear.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 
@@ -60,6 +61,8 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 | Wiki graph needs linking | `/manage-wiki connect --fix` |
 | Issues created | `/manage-issue list --source harvest` |
 | Specs extracted | `/spec-load --role implement` |
+| Specs extracted (冲突审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾 |
+| Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
 | Full phase retrospective | `/quality-retrospective` |
 </completion>
 

package/.agy/skills/manage-knowledge-audit/SKILL.md

@@ -45,10 +45,12 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 **GATE 1: Load → Detect** (Stages 1-2 → Stage 4)
 - REQUIRED: Scope 解析通过，互斥标志校验完成。
 - REQUIRED: 三存储按 scope 加载完成。
+- REQUIRED: 加载已有冲突标记: `maestro spec conflict list` → 合并到 finding 池。
 - BLOCKED if scope 非法或存储不可读: E001/E002。
 
 **GATE 2: Detect → Decision** (Stage 4 → Stage 5)
 - REQUIRED: Finding 池按 P0/P1/P2 分级输出。
+- REQUIRED: 已标记 `contested` 的条目自动归入 P0 finding（来源: conflict-marker）。
 - REQUIRED: 未 harvest 的 artifact 删除前触发抢救确认（W002）。
 - BLOCKED if finding 为空: 无需淘汰，直接输出报告。
 
@@ -63,6 +65,31 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 - **Deprecate over delete**: 文本存储首选 `status="deprecated"`，保留历史。
 - **Purge 仅 artifact**: `--purge` 不作用于 spec/knowhow。
 - **Rescue before delete**: 未抽取 artifact 删除前强制提示先 `/manage-harvest`。
+
+### Conflict Resolution Integration
+
+四态决策（扩展自三态 keep/deprecate/delete）：
+
+| 动作 | 适用场景 | 执行 |
+|------|---------|------|
+| `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
+| `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
+| `deprecate` | 内容过时或被取代 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
+
+**关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
+
+### Code-as-Truth 校验（审查核心原则）
+
+**代码是唯一真理源。** Spec/knowhow 中的任何声明，必须与代码实际行为一致。
+
+当 detector 发现 spec 条目声称某行为/规则时：
+1. **代码校验**: grep/read 代码中相关实现，确认 spec 声明是否与代码一致
+2. **不一致处理**:
+   - 代码正确、spec 过时 → `deprecate` 或 `delete` spec 条目
+   - 代码正确、spec 不完整 → `contest` 并建议补充
+   - 代码有 bug、spec 正确 → `keep` spec，生成 issue 修代码
+3. **禁止**: 仅凭 spec 文本判断正确性。每个 finding 的 evidence 必须包含代码引用（文件:行号）
 </execution>
 
 <completion>
@@ -73,6 +100,8 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | 复审淘汰记录 | 查看 `audit-report-{date}.md` |
 | 抢救未抽取 artifact | `/manage-harvest <artifact-id>` |
 | 验证 spec 现状 | `/spec-load --role implement` |
+| 查看冲突标记 | `maestro spec conflict list` |
+| 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
 | 周期巡检 | `--scope all --report` |
 </completion>
 

package/.agy/skills/odyssey-debug/SKILL.md

@@ -57,6 +57,8 @@ Treats every bug as a learning signal with exhaustive iteration until root cause
    - 关键判断用不同 `--role`（analyze / review / explore）获取多视角
    - 修复前后各做一次 CLI review 确认
    - 不同阶段可调用不同工具，综合多方意见再行动
+
+4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
 </execution_discipline>
 
 <context>
@@ -392,7 +394,11 @@ Goals:      {done}/{total} confirmed ({skipped} skipped)
 ```
 📋 Debug Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
 
-/goal 穷尽迭代：直到根因确认（或明确 INCONCLUSIVE）且修复验证通过
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+穷尽迭代：直到根因确认（或明确 INCONCLUSIVE）且修复验证通过
 且泛化扫描穷尽（所有 hits 已分类处理）且 phase_goals_all_done=true 才停。
 假设失败时扩范围→换视角→升级工具，不轻易放弃。
 泛化发现的同类 bug 全部修复或创建 issue，不允许遗留。

package/.agy/skills/odyssey-improve/SKILL.md

@@ -47,6 +47,8 @@ Baseline-first approach with exhaustive iteration until zero remaining actionabl
    - survey 阶段: `--role explore` 发现依赖/复杂度热点
    - audit/diagnose: `--role analyze` 获取多视角分析
    - fix 前后: `--role review` 确认改进正确性
+
+4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
 </execution_discipline>
 
 <context>
@@ -431,7 +433,11 @@ Goals:       {done}/{total} ({skipped} skipped)
 ```
 📋 Improve Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
 
-/goal 穷尽迭代：直到 session.json 的 audit_result 中所有 findings 均已处理（fix/issue/decision）
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+穷尽迭代：直到 session.json 的 audit_result 中所有 findings 均已处理（fix/issue/decision）
 且 phase_goals_all_done=true 才停。修复按 severity 逐轮迭代，每轮修复后 re-verify 修改区域。
 Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比确认改进。
 遇到 phase=decision 的 pending 必须 ask_question。不允许"只报告不处理"。

package/.agy/skills/odyssey-planex/SKILL.md

@@ -56,6 +56,8 @@ plan → execute → verify → fix gaps → iterate until ALL criteria pass.
    - 计划阶段: `--role analyze` 获取任务分解建议
    - 修复前后: `--role review` 确认无回归
    - verify 阶段: cli-review 类型标准自动 delegate
+
+4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
 </execution_discipline>
 
 <context>
@@ -515,7 +517,15 @@ Write understanding.md §6, generalization_stats. Mark G5 done.
 ```
 📋 Planex Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
 
-/goal 穷尽迭代：直到 acceptance_criteria[*] 全部 status==passed
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+验收标准：
+{for each AC in acceptance_criteria:}
+- {AC.id}: {AC.criterion} (验证方式: {AC.verify_method})
+{end for}
+穷尽迭代：直到 acceptance_criteria[*] 全部 status==passed
 且 phase_goals_all_done=true 才停。verify 失败自动 fix→re-verify 循环。
 每轮修复后重新验证，新发现的标准违反继续修，不超过 max_iterations。
 遇到 phase=decision 的 pending 必须 ask_question，不得自行 resolve。

package/.agy/skills/odyssey-review-test-fix/SKILL.md

@@ -46,6 +46,8 @@ fix ALL findings → confirm → generalize → discover → persist. Zero-resid
 3. **多 CLI 辅助** — 利用 `maestro delegate` 调用多个 CLI 工具交叉验证
    - 关键判断用不同 `--role`（analyze / review / explore）获取多视角
    - 修复前后各做一次 CLI review 确认
+
+4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
 </execution_discipline>
 
 <context>
@@ -366,7 +368,11 @@ Goals:      {done}/{total} ({skipped} skipped)
 ```
 📋 Review-Test-Fix Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
 
-/goal 穷尽迭代：直到 session.json 的 review_result.remaining_actionable == 0
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+穷尽迭代：直到 session.json 的 review_result.remaining_actionable == 0
 且 confirmation.verdict == "confirmed" 且 phase_goals_all_done == true 才停。
 修复按 severity 逐轮迭代（critical→high→medium→low），每轮修复后 re-review 修改区域。
 发现新问题追加到当前轮继续。遇到 phase=decision 的 pending 必须 ask_question。

package/.agy/skills/odyssey-ui/SKILL.md

@@ -47,6 +47,8 @@ fix → verify → generalize → discover → persist. Every pixel is a learnin
    - survey 阶段: `--role explore` 发现设计系统用法
    - audit/diverge: `--role analyze` 获取多视角创意
    - fix 前后: `--role review` 确认视觉正确性
+
+4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
 </execution_discipline>
 
 <context>
@@ -391,7 +393,11 @@ Goals:      {done}/{total} ({skipped} skipped)
 ```
 📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
 
-/goal 穷尽迭代：直到 session.json 的 audit + diverge findings 均已处理（fix/issue/decision）
+/goal 完成以下目标：
+{for each G in phase_goals where status != "skipped":}
+- {G.id}: {G.goal} — 完成条件: {G.done_when}
+{end for}
+穷尽迭代：直到 session.json 的 audit + diverge findings 均已处理（fix/issue/decision）
 且 phase_goals_all_done=true 才停。修复按 impact×severity 逐轮迭代。
 每轮修复后重审修改区域，新发现追加继续修。
 遇到 phase=decision 的 pending 必须 ask_question。不允许"只报告不处理"。

package/.agy/skills/quality-review/SKILL.md

@@ -52,6 +52,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
 - Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
 - Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
+- Conflict state: `maestro spec conflict list` → 当前已标记冲突的 spec 条目（review 时优先关注）
 - Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
@@ -75,6 +76,7 @@ Follow '~/.maestro/workflows/review.md' completely.
 - REQUIRED: review.json written with findings, severity distribution, and verdict.
 - REQUIRED: Issues auto-created based on level thresholds.
 - REQUIRED: index.json updated with review status.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark` on the spec entry. Code is the single source of truth.
 
 **Output writes to REVIEW_DIR** (not EXEC_DIR):
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict
@@ -129,6 +131,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 | PASS verdict | `/quality-test {phase}` |
 | WARN verdict (non-blocking issues) | `/quality-test {phase}` (proceed with caveats) |
 | BLOCK verdict (critical findings) | `/maestro-plan {phase} --gaps` (fix first) |
+| Spec contradictions found | `maestro spec conflict list` → `/manage-knowledge-audit --scope spec` |
 | Want code cleanup | `/quality-refactor {phase}` |
 </completion>
 

package/.agy/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:
   - ask_question
   - define_subagent
@@ -29,6 +29,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)
@@ -146,4 +171,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/agents/role-design-author.md

@@ -190,9 +190,11 @@ All behavioral statements MUST use MUST / SHOULD / MAY / MUST NOT / SHOULD NOT.
 - [ ] No interrogative sentences (all declarative)
 - [ ] system-architect: §3 contains "Data Model" and "State Machine" headings
 
-## Return Protocol
+## Completion Sequence (MANDATORY ORDER)
 
-Report completion with this structure (the orchestrator reads ONLY this, not the files):
+**Step A — Write files**: Use the Write tool to create every file under `output_dir/`. Then verify with Glob that `analysis.md` and each `analysis-F-*.md` exist on disk. If any Write call fails, emit `TASK BLOCKED` and stop.
+
+**Step B — Report summary**: ONLY AFTER Step A files are confirmed on disk, emit this text (the orchestrator reads this summary to track progress — it does NOT substitute for the files):
 
 ```
 TASK COMPLETE
@@ -205,7 +207,7 @@ rfc_keyword_count: {N}
 total_lines: {sum across all files}
 ```
 
-If blocked: report blocker with `TASK BLOCKED` prefix.
+Never emit `TASK COMPLETE` without files on disk. If blocked: report with `TASK BLOCKED` prefix.
 
 ## NEVER
 

package/.claude/agents/workflow-collab-planner.md

@@ -117,6 +117,7 @@ You are a collaborative planner that works within a pre-allocated task ID range.
 - Task files must use `convergence.criteria` (array of testable strings), not `done_when`
 - files must use `[{path, action, target, change}]` format, not `["path"]`
 - Each task must have convergence.criteria with min 2 testable conditions
+- Vertical slice for UI features: deliver backend + frontend + integration as one end-to-end capability per wave (no backend-only/frontend-only split); each UI delivery wave needs ≥1 task with a `[UI-observable]` convergence criterion (verifiable user-facing flow)
 - Each task must have `read_first[]` — files the executor MUST read before implementation
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb
 - Task definitions follow the same schema as workflow-planner output