maestro-flow 0.5.33 → 0.5.35

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/.agents/skills/quality-test/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-test
 description: Use when implementation needs user acceptance testing with interactive verification and gap closure
-argument-hint: "[phase] [--smoke] [--auto-fix]"
+argument-hint: "[phase] [--smoke] [--auto-fix] [--frontend-verify]"
 allowed-tools:
   - read_file
   - write_file
@@ -29,6 +29,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/.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/agents/workflow-collab-planner.md

@@ -116,6 +116,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

package/.agy/agents/workflow-planner.md

@@ -159,11 +159,13 @@ These rules prevent over-splitting that wastes tokens on unnecessary agent spawn
    - **Low** (single file, single concern, zero cross-module): **1 task**
    - **Medium** (multiple files OR integration point): **1-4 tasks**
    - **High** (cross-module, architectural, new subsystem): **4-10 tasks**
+8. **Vertical slice for UI features (MANDATORY)** — 含用户界面的功能必须作为端到端纵向切片交付一个用户可观测能力（后端 endpoint + 前端 wiring + 集成同属一个交付波次），**禁止**拆成 backend-only / frontend-only 任务或按层切波。每个交付波次须闭合一个可用能力，而非一层。
 
 ## Constraints
 - Each task must be substantial (15-60 min of work); group related changes, avoid file-per-task
 - Each task must have convergence.criteria (min 2 testable conditions)
 - convergence.criteria must be specific and testable (not "works correctly")
+- For UI features, each delivery wave MUST have ≥1 task with a `[UI-observable]` convergence criterion — a verifiable user-facing flow (e.g. `[UI-observable] User can create a Note in the UI and see it in the list`). Backend-only criteria do NOT satisfy this; the runtime check is enforced by ralph's frontend-verify gate.
 - Each task must have `read_first[]` — files the executor MUST read before implementation (the file being modified + source-of-truth files)
 - `action` must contain concrete values (function signatures, config keys, import paths), not just a verb like "Implement"
 - files must use array format `[{path, action, target, change}]`

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 → 自运行决策循环
+  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 个辅助流程