maestro-flow 0.5.33 → 0.5.34

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-ralph/SKILL.md

@@ -356,6 +356,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 |
@@ -374,6 +375,7 @@ 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
@@ -408,7 +410,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
 
@@ -686,7 +688,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，不阻塞。
@@ -729,6 +735,7 @@ 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

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

@@ -51,6 +51,7 @@ Remaining     → intent (new session)
 9. **Decomposition is outcome-oriented** — sub-goals 为可观测交付，禁止 lifecycle 复刻；`/goal` 由用户输入
 10. **planning_mode governs arg granularity** — `unified` → skill args 无 `{phase}`；`independent` → 含 `{phase}`
 11. **task_decomposition 驱动 steps[] 动态生长** — `post-goal-audit` 按 unmet 子目标插入 scoped mini-loop；字段累加，既有字段不删不改
+12. **禁止以上下文消耗为由中断自调用链** — harness 自动处理 context compression（消息摘要），模型无需判断上下文剩余空间。自调用的唯一合法终止条件是：router 命中终止条件（S_COMPLETE / S_FALLBACK / END）、session paused、或 decision 末尾的 A_PAUSE_ESCALATE。以"上下文不足"、"已连续完成 N 个 step"、"避免 context overflow"等理由中断属于 invariant violation
 </invariants>
 
 <router>
@@ -449,7 +450,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 1. 校验所有 step 的 `command_scope != "missing"`；否则 raise E006 + 列出缺失 skill
 2. Write `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json`
 3. Display chain overview：每步显示 `{index}. {skill} [{command_scope}]`
-4. `task_decomposition` 存在 → display Goal Prompt block，继续进入 tick
+4. **Goal Prompt 显示（强制）**：`task_decomposition` 存在时，chain overview 之后**必须逐字显示** Goal Prompt block（Appendix），不得省略或摘要。显示后继续进入 tick
 
 ### A_LOCATE_SESSION
 
@@ -841,7 +842,11 @@ decomposition 产出后，链路概览之后逐字显示：
 ```
 📋 任务分解完成。可随时复制以下 /goal 设定终止条件：
 
-/goal 直到 {session_dir}/status.json 的 task_decomposition[*] 与 steps[*] 全部 completion_confirmed=true 才停。每轮以 status.json 为唯一行动手册，通过 /maestro-ralph-beta 推进 tick；decision 节点由 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-beta 推进 tick；decision 节点由 ralph 内联评估。禁止手动执行 skill 或修改 boundary_contract.out_of_scope。
 ```
 
 ### Error Codes

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>

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。不允许"只报告不处理"。

package/.agents/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_user，不得自行 resolve。

package/.agents/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_user。

package/.agents/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_user。不允许"只报告不处理"。

package/.agents/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/agents/role-design-author.md

@@ -189,9 +189,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
@@ -204,7 +206,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/.agy/skills/maestro/SKILL.md

@@ -49,6 +49,7 @@ $ARGUMENTS — user intent text, or special keywords.
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
 11. **schema** — `ralph_protocol_version: "1"` 标记 CLI-driven session；新增字段全部可选
 12. **Invariant violation = BLOCK** — 违反上述任一 invariant 即阻断当前操作，不可绕过。特别是 invariant 1（dispatch via ralph-execute）和 invariant 2（session before execution）和 invariant 10（completion_confirmed 由 CLI 写入）为硬约束。
+14. **禁止以上下文消耗为由中断执行** — harness 自动处理 context compression，以"上下文不足"或"避免 context overflow"为由中断属于 invariant violation
 13. **Classification evidence** — S_CLASSIFY 的 chain 选择决策 MUST 记录到 status.json 的 `classification_rationale` 字段：匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 S_CREATE。
 </invariants>
 
@@ -157,11 +158,16 @@ S_FALLBACK:
    ```
    📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：
 
-   /goal 目标达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
+   /goal 完成以下子目标：
+   {for each G in task_decomposition:}
+   - {G.id}: {G.goal} — 完成条件: {G.done_when}
+   {end for}
+   达成条件: {session_dir}/status.json 中 task_decomposition[*].status == "done" 且 task_decomposition[*].completion_confirmed == true 且 steps[*].completion_confirmed == true。未达成时：阅读 {session_dir}/status.json 取得 execution_criteria / boundary_contract / task_decomposition / steps 作为行动手册，调用 /maestro-ralph continue 推进；严禁手动执行 skill 或越界修改 status.json.boundary_contract.out_of_scope。
    ```
 
 ### A_CREATE_SESSION
 
+0. **Specs 预检**：当 chain 包含 `analyze-macro` / `analyze` / `plan` / `execute` 等执行 stage 且 `.workflow/specs/` 目录不存在时，在 steps 最前面插入 `spec-setup`（stage=`spec-setup`，无 decision）。确保下游可获得项目约束规则注入。chain ∈ {grill, brainstorm, blueprint, init, status, quick} 时跳过
 1. Read `.workflow/state.json` 获取 phase / milestone（含 D-007 反查 `phase_slugs`）；读最新 macro analyze artifact 注入 `scope_verdict` + `analyze_macro_id`（如存在）；读最新 blueprint artifact 注入 `blueprint_id`
 2. Create `.workflow/.maestro/maestro-{YYYYMMDD-HHMMSS}/status.json`（与 ralph 共用 schema）：
    ```json
@@ -221,6 +227,7 @@ S_FALLBACK:
 - [ ] plan 支持 `{phase}` / `--from analyze:{ANL_ID}` / `--from blueprint:{BLP_ID}` 三路径；`source_artifact_ref` 写入 step
 - [ ] Broad lifecycle intents decomposed (≤3 boundary questions); narrow/single-step skip
 - [ ] status.json 唯一真源；无 markdown 清单；post-goal-audit 节点在 decomposed 时追加；/goal 提示词以 status.json 为判据
+- [ ] Specs 预检：chain 含执行 stage + `.workflow/specs/` 不存在 → steps 最前面插入 `spec-setup`
 - [ ] Chain selected and confirmed (or auto-confirmed)
 - [ ] Session dir created with status.json before execution; decomposition fields additive-only
 - [ ] 执行 step 含 `command_scope` + `command_path` + `completion_confirmed`；decision step 由 `step.decision` 标识

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

@@ -50,11 +50,11 @@ Single source of truth: **[index/catalog.json](index/catalog.json)**
 
 | Field | Purpose |
 |-------|---------|
-| `commands[]` | 56 个 slash 命令，含分类和描述 |
-| `skills[]` | 10 个 Skill，含分类和描述 |
-| `agents[]` | 22 个 Agent，含分类和描述 |
+| `commands[]` | 64 个 slash 命令，含分类和描述 |
+| `skills[]` | 44 个 Skill，含分类和描述 |
+| `agents[]` | 24 个 Agent，含分类和描述 |
 | `cli_commands[]` | 21 个终端命令 |
-| `guide_files[]` | 17 个 Guide 文档索引 |
+| `guide_files[]` | 17 个 Guide 文档索引（planned，尚未创建） |
 | `essential_commands[]` | 10 个核心命令（新手用） |
 | `workflows` | 主干管线、快速渠道、Issue 闭环、初始化路径 |
 
@@ -190,6 +190,11 @@ $ARGUMENTS → Parse:
 | `/maestro-quick` | 快速任务 |
 | `/maestro-overlay` | Overlay 管理 |
 | `/maestro-amend` | 修正补丁 |
+| `/maestro-grill` | 压力测试 — 对计划或需求进行代码库现实性压力测试 |
+| `/maestro-next` | 智能导航 — 检测状态并推荐下一步最优命令 |
+| `/maestro-companion` | 知识伴侣 — 上下文加载、洞察捕获、技能路由 |
+| `/maestro-swarm-workflow` | Swarm 并行加速器 — 多 agent 并发执行 |
+| `/maestro-universal-workflow` | 动态对抗工作流生成器 |
 
 ### 理解层 + 执行管线 (pipeline)
 
@@ -217,9 +222,23 @@ $ARGUMENTS → Parse:
 | `/manage-issue` | Issue 管理 |
 | `/manage-issue-discover` | Issue 发现 |
 | `/manage-knowhow` | 知识管理 |
+| `/manage-knowhow-capture` | 知识捕获 |
 | `/manage-status` | 状态查看 |
 | `/manage-wiki` | Wiki 管理 |
 | `/manage-harvest` | 收获 |
+| `/manage-codebase-rebuild` | 代码库重建 |
+| `/manage-kg-extractors` | 知识图谱提取器管理 |
+| `/manage-knowledge-audit` | 知识审计 |
+
+### Odyssey 长周期循环 (odyssey)
+
+| 命令 | 用途 |
+|------|------|
+| `/odyssey-debug` | 长周期调试 — 考古、诊断、修复、泛化 |
+| `/odyssey-improve` | 长周期代码改进 — 多维审计、深度诊断、定向修复 |
+| `/odyssey-review-test-fix` | 深度审查修复循环 |
+| `/odyssey-planex` | 需求驱动迭代 — 计划/执行/验证/修复循环 |
+| `/odyssey-ui` | 长周期 UI 优化 — 视觉调研、多维审计、修复 |
 
 ## Workflow Mapping
 
@@ -238,7 +257,7 @@ Roadmap > Milestone > Phase > Task
 
 ```
 上游起源层（并列，可选）
-  brainstorm（发散/轻量）  |  blueprint（收敛/重型）
+  brainstorm（发散/轻量）  |  blueprint（收敛/重型）  |  grill（压力测试）
 
 理解层
   analyze 双层: 宏观(文本参数) → scope_verdict | 微观(数字参数) → Phase 级决策
@@ -248,6 +267,13 @@ Roadmap > Milestone > Phase > Task
 
 执行层
   plan → execute
+
+Odyssey 长周期循环（独立路径）
+  odyssey-debug / odyssey-improve / odyssey-review-test-fix / odyssey-planex / odyssey-ui
+
+自适应引擎（高级）
+  ralph / ralph-beta → 自运行决策循环
+  swarm-workflow / universal-workflow → 多 agent 并行执行
 ```
 
 ### 合法路径
@@ -265,6 +291,9 @@ Roadmap > Milestone > Phase > Task
 | 全自动 | /maestro 入口 | `/maestro -y "任务描述"` |
 | 代码审查 | 质量管线 | `/quality-review` → `/quality-auto-test` → `/quality-test` |
 | 团队开发 | Team Lite | `/maestro-collab` |
+| 长周期调试 | Odyssey 深度循环 | `/odyssey-debug "问题描述"` |
+| 长周期改进 | Odyssey 深度循环 | `/odyssey-improve "改进目标"` |
+| 需求迭代 | Odyssey 深度循环 | `/odyssey-planex "需求描述"` |
 
 ## Core Rules
 
@@ -292,9 +321,9 @@ Roadmap > Milestone > Phase > Task
 
 ## Statistics
 
-- **Slash 命令**: 56 个（7 个分类）
+- **Slash 命令**: 64 个（13 个分类：core/pipeline/milestone/manage/quality/spec/learn/worktree/team/ralph/ui/tools/odyssey）
 - **CLI 命令**: 21 个
-- **Skills**: 11 个（4 个分类）
-- **Agents**: 22 个（5 个分类）
-- **Guide 文档**: 17 个
-- **工作流路径**: 6 个合法路径 (Path A-F) + 3 个辅助流程
+- **Skills**: 44 个（5 个分类：meta/team/knowledge/quality/scholar）
+- **Agents**: 24 个（4 个分类：workflow/team/cli/ui）
+- **Guide 文档**: 17 个（planned，尚未创建）
+- **工作流路径**: 7 个合法路径 (Path A-G) + 4 个辅助流程