maestro-flow 0.5.33 → 0.5.35

package/.agents/skills/maestro-help/phases/02-search-present.md

@@ -67,16 +67,18 @@
 
 **Guide 映射**:
 
-| 命令 | Guide 文档 |
-|------|-----------|
-| maestro-analyze/plan/execute | `guide/command-usage-guide.md` (主干管线) |
-| maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` |
-| maestro-ralph | `guide/maestro-ralph-guide.md` |
-| maestro (协调器) | `guide/maestro-coordinator-guide.md` |
-| manage-* | `guide/command-usage-guide.md` (管理) |
-| quality-* | `guide/command-usage-guide.md` (质量) |
-| delegate | `guide/delegate-async-guide.md` |
-| overlay/amend | `guide/overlay-guide.md` |
+| 命令 | Guide 文档 | 状态 |
+|------|-----------|------|
+| maestro-analyze/plan/execute | `guide/command-usage-guide.md` (主干管线) | planned |
+| maestro-init/roadmap/blueprint | `guide/quick-start-guide.md` | planned |
+| maestro-ralph | `guide/maestro-ralph-guide.md` | planned |
+| maestro (协调器) | `guide/maestro-coordinator-guide.md` | planned |
+| manage-* | `guide/command-usage-guide.md` (管理) | planned |
+| quality-* | `guide/command-usage-guide.md` (质量) | planned |
+| delegate | `guide/delegate-async-guide.md` | planned |
+| overlay/amend | `guide/overlay-guide.md` | planned |
+
+> **注意**: Guide 文档目前尚未创建（标记为 planned），命令详情回退到 catalog 描述和 source 文件。
 
 ### Mode 3: Smart Recommendations
 
@@ -114,21 +116,59 @@
 ```markdown
 ## Skills ({total} 个)
 
-### Meta (2)
+### Meta (6)
 - **workflow-skill-designer** — 设计 orchestrator+phases 工作流 skill
 - **skill-iter-tune** — 迭代 execute-evaluate-improve 调优
+- **prompt-generator** — 生成或转换 prompt 文件
+- **skill-generator** — 创建新 skill（sequential/autonomous 模式）
+- **skill-simplify** — SKILL.md 简化与功能完整性验证
+- **skill-tuning** — 通用 skill 诊断和优化
 
-### Team (6)
+### Team (25)
 - **team-coordinate** — 通用团队协调，动态生成 role-specs
 - **team-executor** — 团队执行，恢复会话
-- **team-lifecycle-v4** — 8 角色完整生命周期
-- **team-quality-assurance** — QA 质量保障流水线
+- **team-lifecycle-v4** — 完整生命周期流水线
+- **team-quality-assurance** — QA 质量保障
 - **team-review** — 多维度代码审查
 - **team-tech-debt** — 技术债务识别和清理
-- **team-testing** — 测试规划和执行
+- **team-testing** — 渐进式测试覆盖
+- **team-adversarial-swarm** — ACO 群智能 + 对抗决策门
+- **team-arch-opt** — 架构优化
+- **team-brainstorm** — 头脑风暴
+- **team-designer** — 团队 skill 生成器（v4 架构）
+- **team-frontend** — 前端开发（内置 ui-ux-pro-max）
+- **team-frontend-debug** — 前端调试（Chrome DevTools MCP）
+- **team-interactive-craft** — 交互组件制作（零依赖）
+- **team-issue** — Issue 解决
+- **team-motion-design** — 动效设计
+- **team-perf-opt** — 性能优化
+- **team-planex** — Plan-and-Execute 管线
+- **team-roadmap-dev** — 路线图驱动开发
+- **team-swarm** — 群智能（ACO + Python 控制器）
+- **team-ui-polish** — UI 打磨（Impeccable 标准）
+- **team-uidesign** — UI 设计（Token→审计→实现）
+- **team-ultra-analyze** — 深度协作分析
+- **team-ux-improve** — UX 改进
+- **team-visual-a11y** — 视觉无障碍 QA
 
 ### Knowledge (1)
 - **codify-to-knowhow** — Manifest 驱动的知识资产生成
+
+### Quality (2)
+- **insight-challenge** — 对抗性审查
+- **delegation-check** — 委派提示词分离违规检查
+
+### Scholar (10)
+- **scholar-writing** — 端到端学术论文写作
+- **scholar-review** — 学术论文审查（自审 + 回复）
+- **scholar-rebuttal-pro** — 审稿回复（证据策略）
+- **scholar-ideation** — 研究构思
+- **scholar-experiment** — 实验结果分析
+- **scholar-citation-verify** — 四层引用验证
+- **scholar-anti-ai-writing** — 去除 AI 写作痕迹
+- **scholar-latex-organizer** — LaTeX 模板整理
+- **scholar-publish** — 会议发表准备
+- **scholar-thesis-docx** — 学位论文 Word 文档
 ```
 
 **Agents**:

package/.agents/skills/maestro-help/phases/03-workflow-guide.md

@@ -123,18 +123,45 @@ const taskPatterns = [
 4. `/quality-auto-test [phase] --re-run` — 重跑失败场景
 ```
 
+**Odyssey 长周期循环** (深度自主):
+
+```markdown
+## Odyssey 长周期循环
+
+适用于需要深度考古、多轮诊断/修复/验证、知识泛化和持久化的复杂任务。
+每个 odyssey 命令都是自含闭环，自主循环直到完成。
+
+### 调试类
+1. `/odyssey-debug "问题描述"` — 考古→诊断→修复→确认→泛化→知识持久化
+
+### 代码改进
+1. `/odyssey-improve "改进目标"` — 多维审计→深度诊断→定向修复→验证→泛化
+
+### 审查修复
+1. `/odyssey-review-test-fix "审查范围"` — 考古→探索→多维审查→修复→泛化
+
+### 需求迭代
+1. `/odyssey-planex "需求描述"` — 计划→执行→严格验证→修复循环（直到验收通过）
+
+### UI 优化
+1. `/odyssey-ui "优化目标"` — 视觉调研→多维审计→发散探索→修复→验证
+```
+
 #### Step 4.3: 工作流全景图
 
 对需要全景视角的用户，展示 Mermaid 图：
 
 ```
-上游起源: brainstorm(发散) | blueprint(收敛) → 可选
+上游起源: brainstorm(发散) | blueprint(收敛) | grill(压力测试) → 可选
 理解层:   analyze "topic"(宏观) → scope_verdict 路由
 编排层:   roadmap(可选，仅 scope_verdict=large 时建议)
 执行层:   plan → execute → quality → milestone-audit → milestone-complete
 快速渠道: maestro-quick → (直接完成)
 Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute → close
-全自动: /maestro -y → (自动路由)
+全自动:   /maestro -y → (自动路由)
+Odyssey:  odyssey-debug / odyssey-improve / odyssey-planex / odyssey-ui → (自主循环)
+并行加速: swarm-workflow / universal-workflow → (多 agent 并发)
+智能导航: /maestro-next → (检测状态推荐下一步)
 ```
 
 #### Step 4.4: 关键概念说明
@@ -156,6 +183,11 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 - **Spec**: 项目约束规则（coding/arch/debug/test），自动注入到工作流
 - **Wiki**: 知识图谱，存储详细技术文档
 - **Ralph**: 自适应决策引擎，动态调整执行链
+- **Odyssey**: 长周期自主循环命令族（debug/improve/planex/ui/review-test-fix），自含考古→诊断→修复→泛化→知识持久化
+- **Swarm Workflow**: 将任务路由到固定 Workflow 脚本进行多 agent 并发执行
+- **Universal Workflow**: 动态生成对抗性 Workflow 脚本，支持复用和持久化
+- **Grill**: 在 brainstorm 之前的压力测试，用代码库现实检验想法/需求
+- **Next**: 智能导航，检测工作流状态并推荐最优下一步命令
 ```
 
 ### Mode 5: Beginner Onboarding
@@ -180,6 +212,7 @@ Issue 闭环: discover → create → analyze --gaps → plan --gaps → execute
 | 7 | `/maestro-plan` | 规划 | 分析完成后生成执行计划，支持 `--from analyze:ANL-xxx` 直达 |
 | 8 | `/maestro-execute` | 执行 | 计划完成后，执行实现 |
 | 9 | `/maestro-quick` | 快速任务 | 简单任务跳过管线 |
+| 10 | `/maestro-next` | 智能导航 | 不确定下一步时，自动检测状态推荐 |
 ```
 
 #### Step 5.2: 快速入门路径

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

@@ -90,7 +90,8 @@ Follow '~/.maestro/workflows/plan.md' completely.
 - REQUIRED: Plan-checker passed (or minor issues acknowledged).
 - 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).
@@ -215,6 +216,7 @@ 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")
 - [ ] Plan confidence scored in P4 with 5-dimension factor model
 - [ ] Plan readiness gate checked before P4.5 collision detection

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

@@ -25,6 +25,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
 ```
@@ -58,7 +59,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 +131,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
@@ -217,6 +218,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 |
@@ -231,7 +240,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 +261,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:**
 
@@ -337,10 +346,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`。
 
@@ -356,6 +365,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 |
@@ -365,6 +375,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 |
@@ -374,10 +385,12 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 **Build rules (按顺序应用):**
 
 0. **planning_mode 选列**：`unified` → invoke_skill(unified) 列；`independent` → invoke_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` 结尾
@@ -392,13 +405,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
@@ -408,7 +424,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
 
@@ -421,6 +437,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 +539,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}}
 
@@ -579,6 +596,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 +688,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:
@@ -686,7 +713,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，不阻塞。
@@ -714,12 +745,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 agent --json --quiet` 预校验，project 覆盖 global）；decision step 通过 `step.decision` 字段标识
@@ -729,8 +761,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；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

@@ -55,6 +55,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>
@@ -135,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
 
@@ -163,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" })` 自调用。
 
@@ -245,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/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/.agents/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/.agents/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/.agents/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_user。不允许"只报告不处理"。