maestro-flow 0.5.2 → 0.5.3

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

@@ -0,0 +1,464 @@
+---
+name: odyssey-ui
+description: Long-running UI optimization cycle — visual survey, multi-dimensional audit, divergent exploration, fix, verify, generalize, and design knowledge persistence
+argument-hint: <target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - replace_file_content
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Deep UI polish cycle: survey (capture current state) → audit (6 dimensions) → diverge (creative
+exploration beyond bugs) → fix → verify → generalize (举一反三) → discover → persist.
+
+Unlike `maestro-impeccable` (single command/chain execution), this is a persistent session with
+evidence trails, decision journal, and iterative improvement. Every visual detail is an opportunity
+to learn and replicate.
+
+Core philosophy:
+- **Every pixel tells a story** — subtle details create the experience
+- **Diverge before converge** — explore creatively, then implement methodically
+- **Find one, polish all** — a single improvement reveals a class of opportunities
+- **Browser is truth** — verify in real rendering, not just in code
+
+**三句哲学约束（穷尽迭代）:**
+1. **零遗留** — 每个 finding/idea 必须是 action item（修复 / issue / 决策），不允许只报告不处理
+2. **穷尽迭代** — 按 impact×severity 递降逐轮修复，直到 0 remaining actionable findings 才退出 fix loop
+3. **改进即标准** — 每次修复后重审同区域，发现新视觉问题继续修，直到该区域无可改善
+
+Entry: `/odyssey-ui "target"` (full cycle) | `-c` (resume) | `--skip-fix` (audit-only)
+</purpose>
+
+<boundary>
+**范围内:** 目标组件/页面的视觉体验优化 — 审查 6 维度 → 发散探索 → 修复 → 泛化到兄弟组件
+**范围外:** 后端逻辑 / 数据模型 / API 设计 / 业务规则 → `/odyssey-planex` | 深度 bug 调查 → `/odyssey-debug` | 代码质量审查 → `/odyssey-review-test-fix`
+**探索自由度:** 边界内最大自由 — S_DIVERGE 阶段鼓励发散思维，不设创意上限。审查 + 发散可发现任何视觉/交互/可访问性细节。在约束下尽可能完善每个像素。
+</boundary>
+
+<execution_discipline>
+**三条铁律（所有阶段适用）:**
+
+1. **Phase auto-commit** — 每个阶段完成后**自动** `git commit`，无需用户确认
+   - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-ui({slug}): {phase} — {摘要}"`
+   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
+
+2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
+   - 视觉确定性高（缺少 hover state、对比度不足等）→ 直接修复
+   - 设计方向不确定（色彩选择、布局重构等）→ 记录 decision 等用户判断
+   - 禁止猜测性修改，尤其是品牌/风格层面的改动
+
+3. **多 CLI 辅助** — 利用 `maestro delegate` 调用多个 CLI 工具交叉验证
+   - survey 阶段: `--role explore` 发现设计系统用法
+   - audit/diverge: `--role analyze` 获取多视角创意
+   - fix 前后: `--role review` 确认视觉正确性
+</execution_discipline>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution:**
+| Input | Resolution |
+|-------|-----------|
+| Component path | Audit that component |
+| Page/route path | Audit that page |
+| `staged` / `HEAD` | Review UI changes in diff |
+| Feature area name | Resolve to related components/pages |
+
+**Flags:**
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--dimensions <list>` | Comma-separated subset of 6 dimensions | all 6 |
+| `--fix-threshold <severity>` | 修复到哪个 severity 为止（all = 全部修复）| all |
+| `--skip-fix` | Audit + diverge only, no code changes | false |
+| `--skip-generalize` | Skip S_GENERALIZE and S_DISCOVER | false |
+| `--auto` | CLI delegates without confirmation | false |
+| `-y` | Auto-confirm all decisions (see appendix) | false |
+| `-c` | Resume most recent session | — |
+
+**Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
+
+**Output — 3 files:**
+```
+SESSION_DIR/
+  ├── session.json       # state + audit_result + diverge_result + patterns + phase_goals
+  ├── evidence.ndjson    # append-only (phase: survey|audit|diverge|fix|discovery|decision|self-iteration)
+  └── understanding.md   # 8-section evolving narrative
+```
+
+**session.json schema:**
+```json
+{
+  "session_id": "ui-odyssey-{YYYYMMDD-HHmmss}",
+  "target": "", "dimensions": [],
+  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
+  "current_state": "S_INTAKE",
+  "audit_result": { "dimensions_audited": [], "finding_count": 0, "severity_distribution": { "critical": 0, "high": 0, "medium": 0, "low": 0 } },
+  "diverge_result": { "improvements_proposed": 0, "creative_ideas": 0 },
+  "patterns": [{ "id": "P1", "source_finding": "F1", "layer": "syntax|semantic|structural", "signature": "", "description": "", "risk": "", "fix_template": "", "confidence": "high|medium|low" }],
+  "confirmation": { "test_result": {}, "cli_review": {}, "overall": "confirmed|needs_rework" },
+  "generalization_stats": { "patterns_extracted": 0, "total_hits": 0, "cross_layer_confirmed": 0, "regression_risks": 0, "by_layer": {}, "deepening_triggered": false },
+  "phase_goals": [], "phase_goals_all_done": false,
+  "self_iteration_log": [],
+  "cross_phase_loops": 0, "max_loops": 3,
+  "created_at": "", "updated_at": ""
+}
+```
+
+**evidence.ndjson unified schema:** `{"ts":"","phase":"<phase>","type":"<type>","dimension":"","title":"","severity":"","file":"","line":0,"description":"","suggestion":"","category":"","impact":"","effort":""}`
+
+**phase_goals[]:**
+| ID | Goal | Phase | skip_when |
+|----|------|-------|-----------|
+| G1 | Survey completed | S_SURVEY | — |
+| G2 | Audit completed | S_AUDIT | — |
+| G3 | Divergent exploration done | S_DIVERGE | — |
+| G4 | Zero remaining: all findings/ideas fixed and verified | 0 remaining actionable within fix_threshold | S_VERIFY | skip_fix |
+| G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
+| G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
+| G7 | Learnings persisted | S_RECORD | — |
+
+Lifecycle: `pending → done | skipped | failed` (all set `completion_confirmed`)
+
+### Pre-load（可选，缺失不阻塞）
+
+| 层级 | 命令 | 作用 |
+|------|------|------|
+| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` | 模块边界，组件结构 |
+| Wiki search | `maestro search "<target keywords>" --json` | 先前 UI 决策（取 top 5） |
+| UI specs | `maestro spec load --category ui` | 设计规范、token、组件约定 |
+| Coding specs | `maestro spec load --category coding` | 编码规范 |
+| Role knowledge | `maestro search --category ui` → 选相关 → `maestro wiki load <id>` | 累积设计知识 |
+| Prior sessions | `grep_search(".workflow/scratch/*-ui-odyssey-*")` | 相关会话 |
+
+### Knowledge Persistence（S_RECORD 中写入产出文件）
+
+S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，按以下分类结构化：
+
+| 分类 | 写入内容 | 后续建议命令 |
+|------|---------|-------------|
+| 设计 pattern | 组件模式 + 适用场景 + token 引用 | `/spec-add ui "..."` |
+| 交互规范 | 状态定义 + 转场规则 + 反馈模式 | `/spec-add ui "..."` |
+| 可访问性规则 | WCAG 要求 + 实现方案 | `/spec-add ui "..."` |
+| 可复用泛化 pattern | pattern 签名 + 应用范围 | `/spec-add coding "..."` |
+
+**两步模式：** 执行中写入产出文件（临时记录）→ 任务完成后用户通过 next_step_routing 沉淀为永久知识。执行过程中不调用外部 Skill。
+</context>
+
+<self_iteration>
+**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max 2 rounds).
+
+| Dimension | Sufficient | Insufficient |
+|-----------|-----------|-------------|
+| Coverage | All target components/pages analyzed across dimensions | Missed files discoverable via grep/glob |
+| Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
+| Actionability | Each conclusion has concrete improvement action | "Consider reviewing" without action |
+
+**Expansion:** Round 1 = widen scope (more components, deeper import chain, extra delegate angles). Round 2 = shift perspective (different CLI tool, reverse dependency trace, manual code reading).
+
+**Log:** `evidence.ndjson ← {"phase":"self-iteration","type":"quality-gate","stage":"S_XXX","round":N,"assessment":{},"expansion":""}`
+
+**Applicable stages:** S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE
+</self_iteration>
+
+<state_machine>
+
+<states>
+S_INTAKE     — Parse target, load design context, resume session           PERSIST: session.json + understanding.md §1
+S_SURVEY     — Visual landscape: design tokens, pattern inventory          PERSIST: evidence.ndjson (survey) + understanding.md §2
+S_AUDIT      — 6-dimension parallel review                                 PERSIST: evidence.ndjson (audit) + understanding.md §3
+S_DIVERGE    — Divergent creative exploration: polish + delight            PERSIST: evidence.ndjson (diverge) + understanding.md §4
+S_FIX        — Implement improvements (skip if --skip-fix)                 PERSIST: code changes + evidence.ndjson (fix)
+S_VERIFY     — Visual verification + test (skip if --skip-fix)             PERSIST: session.json.confirmation + understanding.md §5
+S_GENERALIZE — Pattern extraction + 4-agent scan (skip if --skip-gen)      PERSIST: session.json.patterns + understanding.md §6
+S_DISCOVER   — Classify hits, create issues (skip if --skip-gen)           PERSIST: evidence.ndjson (discovery|decision) + understanding.md §7
+S_RECORD     — Design knowledge persistence + final report                 PERSIST: understanding.md §8 + spec entries
+</states>
+
+<transitions>
+S_INTAKE:
+  → S_INTAKE      WHEN -c + session found        DO A_RESUME
+  → S_SURVEY      WHEN target resolved            DO A_INTAKE
+  → S_INTAKE      WHEN no target                  DO ask_question
+
+S_SURVEY       → S_AUDIT        DO A_SURVEY
+
+S_AUDIT        → S_DIVERGE      DO A_AUDIT
+
+S_DIVERGE:
+  → S_FIX          WHEN !skip_fix AND actionable findings/ideas           DO A_DIVERGE
+  → S_GENERALIZE   WHEN (skip_fix OR no actionable) AND !skip_gen        DO A_DIVERGE
+  → S_RECORD       WHEN (skip_fix OR no actionable) AND skip_gen         DO A_DIVERGE
+
+S_FIX          → S_VERIFY       DO A_FIX
+
+S_VERIFY:
+  → S_GENERALIZE   WHEN verified AND !skip_gen    DO A_VERIFY
+  → S_RECORD       WHEN verified AND skip_gen     DO A_VERIFY
+  → S_FIX          WHEN needs_rework              DO A_VERIFY
+
+S_GENERALIZE:
+  → S_DISCOVER     WHEN hits found                DO A_GENERALIZE
+  → S_RECORD       WHEN no hits                   DO A_GENERALIZE
+
+S_DISCOVER → S_AUDIT        : discovery reveals new component to audit, loops < max_loops → cross_phase_loops++
+S_DISCOVER → S_FIX          : discovery finds fixable sibling, !skip_fix, loops < max_loops → cross_phase_loops++
+S_DISCOVER → S_RECORD       : triage complete OR loops >= max_loops (剩余项 → issue/decision)
+
+S_RECORD   → END            DO A_RECORD
+</transitions>
+
+<actions>
+
+### A_INTAKE
+1. Parse arguments: target description, flags, `--dimensions` subset
+2. Generate slug, create `SESSION_DIR`
+3. Search: `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
+4. Derive `phase_goals[]` from flags (apply `skip_when`)
+5. Write `session.json` + `understanding.md` §1 (Target & Design Context)
+6. Emit Goal Prompt (see Appendix)
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): INTAKE — 目标解析"`
+
+### A_RESUME
+Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
+
+### A_SURVEY
+Visual landscape survey — understand the current state before proposing changes.
+
+1. **Design system inventory**: Scan target files for design tokens, CSS variables, theme imports. Catalog what's used.
+2. **Current state analysis**: Read component code, identify styling patterns, layout strategy, component hierarchy.
+3. **CLI-assisted survey** (optional):
+```bash
+maestro delegate "PURPOSE: Survey UI design state of: {target}
+TASK: Identify design tokens in use | Catalog spacing/typography patterns | Map component hierarchy | Check consistency with design system
+MODE: analysis
+CONTEXT: @{target_files}
+EXPECTED: JSON {tokens_used, spacing_patterns, typography_scale, component_hierarchy, consistency_issues}
+" --role analyze --mode analysis
+```
+Run_in_background, STOP, wait for callback.
+
+4. Append evidence.ndjson (phase: "survey"). Update `understanding.md` §2. Mark G1 done.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): SURVEY — 视觉调查"`
+
+### A_AUDIT
+Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset):
+
+| Agent | Dimension | Focus |
+|-------|-----------|-------|
+| Visual Hierarchy | visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
+| Interaction States | interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
+| Accessibility | accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
+| Responsiveness | responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
+| Micro-interactions | micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
+| Edge Cases | edge_cases | Long text truncation, empty data, error states, extreme values, i18n, RTL |
+
+Each returns `[{title, severity, file, line, description, suggestion, dimension}]`.
+Merge → evidence.ndjson (phase: "audit"). Write `session.json.audit_result`.
+Update `understanding.md` §3 (findings by dimension + severity matrix). Mark G2 done.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): AUDIT — 多维审查"`
+
+### A_DIVERGE
+**The unique phase** — divergent creative exploration. Goes beyond defect fixing to ask "what would make this delightful?"
+
+**Step 1 — Creative exploration (2 parallel Agents):**
+
+| Agent | Angle | Prompt Focus |
+|-------|-------|-------------|
+| Polish Agent | "What subtle details are missing?" | Shadows, borders, transitions, hover states, feedback, empty states, skeleton loading, scroll behavior |
+| Delight Agent | "What would make this experience memorable?" | Motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy |
+
+Each returns: `[{idea, category (polish|delight), impact (high|medium|low), effort (small|medium|large), description, inspiration}]`
+
+**Step 2 — CLI-assisted design review** (optional):
+```bash
+maestro delegate "PURPOSE: Creative UI review of: {target}
+TASK: Identify polish opportunities | Suggest micro-interaction improvements | Review visual rhythm and harmony | Propose delight moments
+MODE: analysis
+CONTEXT: @{target_files} | Audit summary: {audit_findings_summary}
+EXPECTED: JSON [{category, idea, rationale, reference}]
+" --role analyze --mode analysis
+```
+Run_in_background, STOP, wait for callback.
+
+**Step 3 — Consolidate**: Merge audit findings + divergent ideas → prioritized improvement list (severity x impact x effort matrix).
+Append evidence.ndjson (phase: "diverge"). Update `understanding.md` §4. Mark G3 done.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): DIVERGE — 发散探索"`
+
+### A_FIX
+Skip if `--skip-fix`. Implement improvements prioritized by impact.
+
+1. **穷尽修复**: Fix ALL findings/ideas by priority tier (critical→high→medium→low + high-impact ideas), not just top items. After each tier, re-review modified area — new findings append.
+2. For each fix: implement → append evidence.ndjson (phase: "fix")
+3. **Normal**: ask_question per-fix confirmation. **`-y`**: auto-proceed, record `deferred`.
+
+📌 **Auto-commit**: `git add -A && git commit -m "odyssey-ui({slug}): FIX — 优化实现"`
+
+### A_VERIFY
+Visual verification — confirm improvements work in practice.
+
+1. Run tests if applicable (lint, unit, visual regression)
+2. **CLI-assisted visual review**:
+```bash
+maestro delegate "PURPOSE: Verify UI improvements for: {target}
+TASK: Check visual correctness | Verify interaction states | Confirm accessibility | Test responsive behavior
+MODE: analysis
+CONTEXT: @{modified_files} | Improvements: {fix_summary}
+EXPECTED: JSON {verdict, verified_improvements, remaining_issues, regression_risk}
+" --role review --mode analysis
+```
+Run_in_background, STOP, wait for callback.
+
+3. `needs_rework` → S_FIX. `verified` → mark G4 done, advance.
+4. Update `understanding.md` §5. Write `session.json.confirmation`.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): VERIFY — 验证"`
+
+### A_GENERALIZE
+Multi-layer pattern extraction from findings + improvements → 4-agent scan → cross-layer dedup.
+
+**Pattern extraction** from audit findings + diverge ideas (severity >= medium OR impact = high):
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex → direct Grep | Missing `aria-label`, hardcoded px values, inline styles |
+| Semantic | Agent understands anti-pattern → scans | Inconsistent hover states, missing loading feedback |
+| Structural | File/module structure similarity | Same component type missing responsive treatment |
+
+Write `session.json.patterns[]`.
+
+**4-agent parallel scan** (single message):
+
+| Agent | Strategy | Scope |
+|-------|----------|-------|
+| Syntax grep | Grep CSS/style patterns matching found issues | Full project |
+| Semantic scan | Find components with same interaction pattern but missing states | Related modules |
+| Structural match | Find structurally similar components (same imports, layout) | Full project |
+| Historical grep | `git log -S "{pattern}"` for when similar UI patterns were introduced/fixed | Git history |
+
+**Cross-layer dedup**: Multi-layer hit → boost confidence. Single-layer → `needs_review`. Historical match on fixed code → `regression_risk`.
+
+**Iterative deepening**: Module with ≥3 hits → targeted deep scan (max 1 round).
+
+Update `understanding.md` §6 (per-pattern summary, cross-layer matrix). Write `session.json.generalization_stats`. Mark G5 done.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): GENERALIZE — 泛化扫描"`
+
+### A_DISCOVER
+Classify each hit: `needs_treatment` / `low_risk` / `already_handled`.
+**Normal**: ask_question for routing. **`-y`**: auto create issue, `deferred`.
+Append evidence (phase: "discovery" + "decision"). Update `understanding.md` §7. Mark G6 done.
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): DISCOVER — 发现分类"`
+
+### A_RECORD
+1. Finalize `understanding.md` §8: design learnings
+2. Write learnings to understanding.md §8: 按 Knowledge Persistence 表分类记录（临时），completion summary 列出建议的 `/spec-add` 命令
+3. Pending decisions: **Normal** → ask_question. **`-y`** → skip, display deferred count
+4. **Goal audit**: all `phase_goals[*].completion_confirmed` true → `phase_goals_all_done = true`. Any false: **Normal** → ask_question (回退/跳过/接受) | **`-y`** → auto accept
+5. Mark G7 done. `current_state = "COMPLETED"`. Emit completion summary:
+```
+--- UI ODYSSEY COMPLETE ---
+Target:     {target}
+Dimensions: {dimensions_audited}
+Findings:   {C}C {H}H {M}M {L}L
+Diverge:    {improvements} polish + {creative} delight ideas
+Fix:        {fixed_count} applied, verified={yes|skipped}
+Patterns:   {extracted} ({by_layer} distribution)
+Scan hits:  {total} ({cross_layer} cross-layer confirmed)
+Issues:     {N} created
+Decisions:  {N} resolved, {M} pending, {K} deferred
+Learnings:  {N} entries in understanding.md §8
+Self-iter:  {N} quality gate rounds across {M} stages
+Goals:      {done}/{total} ({skipped} skipped)
+---
+```
+
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): RECORD — 会话总结"`
+
+</actions>
+
+<appendix>
+
+### Goal Prompt Template
+**⚠️ 时机守卫：仅在 A_INTAKE 完成后显示一次（session 创建后、开始 survey 前）。A_RECORD 完成时禁止重新显示。**
+
+```
+📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
+
+/goal 穷尽迭代：直到 session.json 的 audit + diverge findings 均已处理（fix/issue/decision）
+且 phase_goals_all_done=true 才停。修复按 impact×severity 逐轮迭代。
+每轮修复后重审修改区域，新发现追加继续修。
+遇到 phase=decision 的 pending 必须 ask_question。不允许"只报告不处理"。
+```
+
+完成时仅输出 completion summary，不重复此提示。
+
+### `-y` Auto-Confirm (5 decision points)
+| Decision Point | Normal | `-y` |
+|----------------|--------|------|
+| A_FIX improvement confirmation | ask_question | auto-proceed, `deferred` |
+| A_DISCOVER hit routing | ask_question | auto create issue, `deferred` |
+| A_DISCOVER ambiguous items | ask_question | all `deferred` |
+| A_RECORD pending decisions | ask_question | skip, show deferred count |
+| A_RECORD goal audit | ask_question | auto accept |
+
+`deferred` items shown as "待决策" in completion summary; recoverable via `-c`.
+
+### Phase Goal Lifecycle
+`pending → done (confirmed=true)` normal | `pending → skipped (confirmed=true)` flags/manual | `pending → failed (confirmed=false)` exception
+
+`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
+
+</appendix>
+
+</state_machine>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No target specified | Provide target |
+| E002 | error | Target path not found | Check path |
+| E003 | error | Resume but no session found | Start new session |
+| W001 | warning | No design system detected | Proceed with defaults |
+| W002 | warning | Some dimension agents failed | Partial coverage |
+| W003 | warning | Generalization 0 hits | Skip discovery |
+| W004 | warning | Delegate parse failed | Use raw output |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved and session created
+- [ ] Design system inventory captured in survey
+- [ ] All dimensions audited (6 parallel agents) with structured findings
+- [ ] Severity matrix produced
+- [ ] Divergent exploration: polish + delight ideas generated
+- [ ] Improvements implemented and verified (unless --skip-fix)
+- [ ] Multi-layer generalization scan + cross-layer dedup (unless --skip-generalize)
+- [ ] Quality Gate self-iteration triggered when insufficient
+- [ ] Discoveries classified and routed
+- [ ] understanding.md §8 finalized with design learnings
+- [ ] phase_goals G1-G7 tracked and audited
+- [ ] Goal Prompt displayed once
+- [ ] `-y`: no blocking prompts, deferred counted
+- [ ] Session resumable via -c
+</success_criteria>
+
+<next_step_routing>
+| Condition | Next step |
+|-----------|-----------|
+| Finding needs deeper debug | `/odyssey-debug "<finding>"` |
+| Issues created from discoveries | `/manage-issue list --source ui-odyssey` |
+| Design pattern worth documenting | `/spec-add ui "..."` |
+| Want full review of changes | `/odyssey-review-test-fix <changed-files>` |
+| Sibling components to polish | `/odyssey-ui "<sibling>"` |
+</next_step_routing>

package/.claude/commands/maestro-ralph-beta.md

@@ -299,14 +299,15 @@ resolve_milestone(phase_number):
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
-| phase 已存在 + 最新 artifact = execute | `verify` |
-| phase 已存在 + 最新 artifact = verify | → refine from result files |
+| phase 已存在 + 最新 artifact = execute | → refine from post-execute results |
 
-**Refine from verify results:**
+**Refine from post-execute results:**
+
+在 execute artifact 的 scratch dir 中检查结果文件（verification.json 由 execute 内置 gate 产出）：
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] | `verify-failed` |
+| 无 verification.json 或 passed==false 或 gaps[] | `execute` (触发 post-execute fix loop) |
 | passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
@@ -332,7 +333,7 @@ resolve_milestone(phase_number):
 
 读 `session.quality_mode_override`（CLI `--quality`），无则按规则推断：
 
-| Condition | Mode | Pipeline (verify 之后) |
+| Condition | Mode | Pipeline (execute 之后) |
 |-----------|------|-------------------------|
 | Has `specs/REQ-*.md` + 当前 phase 业务范围明确 | `full` | business-test → review → test-gen → test |
 | Default | `standard` | review → test-gen (当 coverage<80%) → test |
@@ -361,7 +362,7 @@ options:
   - label: "统一规划 (Recommended)"
     description: "一次性分析+规划整个里程碑所有 phase，analyze/plan 走里程碑级，适合 phase 间关联紧密"
   - label: "独立规划"
-    description: "逐个 phase 走完整生命周期（analyze→plan→execute→verify→...），适合 phase 间独立性高"
+    description: "逐个 phase 走完整生命周期（analyze→plan→execute→...），适合 phase 间独立性高"
 ```
 
 写入 `session.planning_mode`（`"unified"` 或 `"independent"`）。
@@ -393,7 +394,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 { "id": "G1", "goal": "<deliverable>", "boundary": "<in/out note>",
   "done_when": "<objectively checkable condition>",
   "evidence": "verification.json|review.json|uat.md|<test path>",
-  "lifecycle": ["analyze","execute","verify"], "status": "pending" }
+  "lifecycle": ["analyze","execute"], "status": "pending" }
 ```
 `done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。
 
@@ -430,7 +431,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 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（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
+5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
@@ -657,7 +658,7 @@ Write enriched args back to status.json.
 3. `medium` / `small`：
    - 删除 `goal-audit` 之前未完成的 `roadmap` + `analyze` (phase) step
    - 下一个未完成的 `plan` step → `maestro-plan --from analyze:{analyze_macro_id}`，去掉 `{phase}`，`source_artifact_ref = analyze:{analyze_macro_id}`
-   - 后续 `execute` / `verify` 同 standalone scope
+   - 后续 `execute` 等沿用同一 standalone scope
 4. `unknown`：非 auto_confirm → AskUserQuestion 二选一（large / medium-small）；auto_confirm → 默认 large
 5. release 协议 — 完成分支；reindex
 6. Display: ◆ Scope verdict: {verdict} → {kept|collapsed to standalone via analyze:{ANL_ID}}
@@ -754,7 +755,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
     "index": 0,
     "skill": "",                   // 执行 step 有值；decision 节点为空字符串/null
     "args": "",
-    "stage": "",                   // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
+    "stage": "",                   // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|...
     "scope": null,                 // "phase"|"standalone"|"milestone"|null（plan 等需要）
     "decision": null,              // null = 执行 step；非 null = decision step (值为 gate 名)
     "retry_count": 0,              // decision step

package/.claude/commands/maestro-ralph.md

@@ -269,8 +269,7 @@ resolve_milestone(phase_number):
 | phase 已存在 + 无任何 artifact | `analyze` |
 | phase 已存在 + 最新 artifact = analyze | `plan` |
 | phase 已存在 + 最新 artifact = plan | `execute` |
-| phase 已存在 + 最新 artifact = execute | `verify` |
-| phase 已存在 + 最新 artifact = verify | → refine from result files |
+| phase 已存在 + 最新 artifact = execute | → refine from post-execute results |
 
 **关键不变量**：artifact 过滤按 `session.phase`，不读 `state.json.current_phase`。`phase_is_new` → 直接 `analyze`。
 
@@ -289,11 +288,13 @@ resolve_milestone(phase_number):
 | `medium` / `small` | analyze-macro → plan --from analyze:{ANL_ID} → execute → ...（跳过 roadmap + analyze-phase） |
 | `unknown` | 默认走 large 路径，post-analyze-scope 决策节点再纠正 |
 
-**Refine from verify results:**
+**Refine from post-execute results:**
+
+在 execute artifact 的 scratch dir 中检查结果文件（verification.json 由 execute 内置 gate 产出）：
 
 | Condition | Position |
 |-----------|----------|
-| verification.json: passed==false or gaps[] | `verify-failed` |
+| 无 verification.json 或 passed==false 或 gaps[] | `execute` (触发 post-execute fix loop) |
 | passed==true, no review.json | `business-test` |
 | review.json: verdict=="BLOCK" | `review-failed` |
 | review.json: verdict!="BLOCK" | `test` |
@@ -304,7 +305,7 @@ resolve_milestone(phase_number):
 
 决定下游质量管线长度。读 `session.quality_mode_override`（CLI 标志 `--quality`），无则按规则推断：
 
-| Condition | Mode | Pipeline (verify 之后) |
+| Condition | Mode | Pipeline (execute 之后) |
 |-----------|------|-------------------------|
 | Has `specs/REQ-*.md` + 当前 phase 业务范围明确 | `full` | business-test → review → test-gen → test |
 | Default | `standard` | review → test-gen (当 coverage<80%) → test |
@@ -335,7 +336,7 @@ options:
   - label: "统一规划 (Recommended)"
     description: "一次性分析+规划整个里程碑所有 phase，analyze/plan 走里程碑级，适合 phase 间关联紧密"
   - label: "独立规划"
-    description: "逐个 phase 走完整生命周期（analyze→plan→execute→verify→...），适合 phase 间独立性高"
+    description: "逐个 phase 走完整生命周期（analyze→plan→execute→...），适合 phase 间独立性高"
 ```
 
 写入 `session.planning_mode`（`"unified"` 或 `"independent"`）。`A_BUILD_STEPS` 据此决定 skill args 是否携带 `{phase}` 占位符。
@@ -369,7 +370,7 @@ narrow → derive defaults from intent + codebase, skip questions.
 { "id": "G1", "goal": "<deliverable>", "boundary": "<in/out note>",
   "done_when": "<objectively checkable condition>",
   "evidence": "verification.json|review.json|uat.md|<test path>",
-  "lifecycle": ["analyze","execute","verify"], "status": "pending" }
+  "lifecycle": ["analyze","execute"], "status": "pending" }
 ```
 `done_when` 必须客观可验证，且引用 ralph 已产出的 artifact；`lifecycle` 字段映射到产出 evidence 的生命周期 stage。
 
@@ -410,7 +411,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`.
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
 3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
 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（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
+5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
 6. **终点硬约束**：chain 以 `milestone-complete` 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
@@ -558,7 +559,7 @@ Runs only when `task_decomposition` present.
 3. 路径 B（`medium` / `small`）：
    - 删除 `goal-audit` 之前所有未完成的 `roadmap` + `analyze` (phase) step
    - 把下一个未完成的 `plan` step 改为 `maestro-plan --from analyze:{analyze_macro_id}`，去掉 `{phase}`，`source_artifact_ref = analyze:{analyze_macro_id}`
-   - 后续 `execute` / `verify` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
+   - 后续 `execute` 等沿用同一 standalone scope（不带 `{phase}`，由 plan 写出的 task 列表驱动）
 4. 路径 C（`unknown`）：
    - 非 auto_confirm → AskUserQuestion 二选一（large / medium-small）；auto_confirm → 默认 large
 5. Reindex steps，标 decision completed，write status.json
@@ -619,7 +620,7 @@ Runs only when `task_decomposition` present.
     "index": 0,
     "skill": "",                  // 执行 step 有值；decision 节点为空字符串/null
     "args": "",
-    "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|verify|...
+    "stage": "",                  // brainstorm|blueprint|init|analyze-macro|roadmap|analyze|plan|execute|...
     "scope": null,                // "phase"|"standalone"|"milestone"|null（plan 等需要）
     "decision": null,             // 非 null → decision 节点（值为 gate 名，如 "post-execute"）；null → 执行 step
     "retry_count": 0,             // decision 节点专用

package/.claude/commands/maestro.md

@@ -50,7 +50,7 @@ $ARGUMENTS — user intent text, or special keywords.
 4. **Decomposition contract shared with maestro-ralph** — broad/lifecycle intents run S_DECOMPOSE producing the SAME additive block (`boundary_contract`, `execution_criteria`, `task_decomposition`)。Reference maestro-ralph `A_DECOMPOSE_TASKS`
 5. **status.json 唯一真源** — 不生成 `goal-checklist.md` 或外部清单
 6. **执行步骤统一通过 `maestro ralph next` 加载** — `command_scope`/`command_path` 由 `maestro ralph skills --platform claude --json --quiet` 预校验（project 覆盖 global，限定 `.claude/`）；decision 节点不走 CLI，走 `Skill("maestro-ralph")` handoff
-7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
+7. **Topology awareness** — chain catalog 含 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / ...；scope_verdict 由 ralph 在 `post-analyze-scope` 决定
 8. **Grill is interactive-only** — `-y` auto mode MUST skip grill stage and route directly to brainstorm; grill requires Socratic Q&A with the user
 9. **D-007 milestone 反查** — 数字 phase 的 `milestone_id` 由 `state.json.milestones[].phase_slugs` 反查
 10. **每个 step 必须 `completion_confirmed: true`** — 由 `maestro ralph complete N --status DONE|DONE_WITH_CONCERNS` 写入
@@ -141,9 +141,9 @@ S_FALLBACK:
    - 正式规格/spec-generate/7-phase → `blueprint`
    - 项目初始化 → `init`
    - 宽/中等意图 + 无数字 phase → `analyze-macro`（产 scope_verdict，由 ralph 在 `post-analyze-scope` 决定是否插入 roadmap+analyze 或直跳 plan --from analyze）
-   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → `verify {phase}` → quality pipeline
-   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → verify
-   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → verify
+   - 数字 phase 上下文 → `analyze {phase}` → `plan {phase}` → `execute {phase}` → quality pipeline
+   - 已有 analyze artifact 想直达执行 → `plan --from analyze:{ANL_ID}` → execute → quality pipeline
+   - 已有 blueprint artifact → `plan --from blueprint:{BLP_ID}` → execute → quality pipeline
 4. 执行 step：`Bash("maestro ralph skills --platform claude --json --quiet")` 预校验 skill 名，命中写绝对路径到 `command_path`，未命中标 `missing`；同时写 `step.stage` / `step.scope` / `step.source_artifact_ref`。decision 节点不解析 command_path
 
 ### A_CLARIFY
@@ -159,7 +159,7 @@ S_FALLBACK:
 2. broad/medium → `AskUserQuestion` ≤3 轮：Scope / Constraints / Definition of Done
 3. 派生 `execution_criteria` + `task_decomposition`（每个 sub-goal 含 `done_when` + `evidence` + `lifecycle` + `completion_confirmed: false`）
 4. **status.json 唯一真源**：写入 `boundary_contract` / `execution_criteria` / `task_decomposition`；不生成 markdown 清单
-5. 在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
+5. 在最后一个 evidence-producing stage（execute/review/test）之后、`milestone-complete` 之前追加 `decision:post-goal-audit`。ralph-execute 在该节点按需动态生长 `steps[]`
 6. **输出 `/goal` 绑定提示词（不阻塞，用户可在执行过程中随时输入）：**
    ```
    📋 任务分解完成。可随时复制下面一行设定目标（执行过程中输入即可）：
@@ -221,7 +221,7 @@ S_FALLBACK:
 ### Success Criteria
 
 - [ ] Intent classified with task_type, complexity, clarity_score
-- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / verify / quality pipeline
+- [ ] Chain catalog 覆盖 grill / brainstorm / blueprint / analyze-macro / analyze / roadmap / plan(三路径) / execute / quality pipeline
 - [ ] `-y` 模式不触发 grill（交互式压力测试不支持自动模式，跳过直接走 brainstorm）
 - [ ] D-007: 数字 phase 步骤的 `milestone_id` 通过 `state.json.milestones[].phase_slugs` 反查
 - [ ] macro analyze 后跟 `decision:post-analyze-scope`（由 ralph 评估 scope_verdict 决定下游链路）