maestro-flow 0.5.37 → 0.5.39

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

@@ -1,7 +1,7 @@
 ---
 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]
+argument-hint: <target> [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]
 allowed-tools:
   - ask_question
   - define_subagent
@@ -14,6 +14,8 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
+<base>@~/.maestro/workflows/odyssey-base.md</base>
+
 <purpose>
 Deep UI polish cycle: survey → 6-dimension audit → divergent creative exploration →
 fix → verify → generalize → discover → persist. Every pixel is a learning opportunity.
@@ -24,85 +26,35 @@ fix → verify → generalize → discover → persist. Every pixel is a learnin
 **范围外:** 后端逻辑 / 数据模型 / API 设计 / 业务规则 → `/odyssey-planex` | 深度 bug 调查 → `/odyssey-debug` | 代码质量审查 → `/odyssey-review-test-fix`
 **探索自由度:** 边界内最大自由 — S_DIVERGE 阶段鼓励发散思维，不设创意上限。审查 + 发散可发现任何视觉/交互/可访问性细节。在约束下尽可能完善每个像素。
 **Zero-residual principle:** Every finding/idea MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing design debt" is not a valid skip reason — if discovered within scope, it must be addressed.
+⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+  - Brand/style direction requiring human creative judgment
+  - Layout restructuring that changes user flow significantly
+  - Requires new design tokens or breaking component API
+❌ "Unsure how to fix", "Large scope", "Pre-existing issue" are NOT valid decision reasons — either fix it, or explain specifically why it's unfixable
 </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. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
-   - High visual certainty (missing hover state, insufficient contrast, etc.) → fix directly
-   - Design direction uncertain (color choices, layout restructure, etc.) → record decision for user judgment
-   - No speculative changes, especially brand/style-level modifications
-   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
-     - Brand/style direction requiring human creative judgment
-     - Layout restructuring that changes user flow significantly
-     - Requires new design tokens or breaking component API
-   - ❌ "Unsure how to fix", "Large scope", "Pre-existing issue" are NOT valid decision reasons — either fix it, or explain specifically why it's unfixable
-
-3. **多 CLI 辅助** — 利用 `maestro delegate` 调用多个 CLI 工具交叉验证
-   - survey 阶段: `--role explore` 发现设计系统用法
-   - audit/diverge: `--role analyze` 获取多视角创意
-   - fix 前后: `--role review` 确认视觉正确性
-
-4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
-</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 |
+**Target resolution:** Component path → audit component | Page/route → audit page | `staged`/`HEAD` → diff UI changes | Feature area → resolve to components/pages
 
 **Flags:**
 | Flag | Effect | Default |
 |------|--------|---------|
 | `--dimensions <list>` | Comma-separated subset of 6 dimensions | all 6 |
-| `--fix-threshold <severity>` | 修复到哪个 severity 为止（all = 全部修复）| all |
+| `--fix-threshold <severity>` | 修复到哪个 severity 为止 | 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 | — |
+| `--heartbeat` | Enable heartbeat progress reporting | false |
 
 **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": 5,
-  "created_at": "", "updated_at": ""
-}
-```
+**Output — 3 files:** `session.json` (state + audit/diverge results + patterns + phase_goals) | `evidence.ndjson` (phases: survey, audit, diverge, fix, discovery, decision, self-iteration) | `understanding.md` (8-section narrative)
 
-**evidence.ndjson unified schema:** `{"ts":"","phase":"<phase>","type":"<type>","dimension":"","title":"","severity":"","file":"","line":0,"description":"","suggestion":"","category":"","impact":"","effort":""}`
+**session.json unique fields:** `target`, `dimensions`, `audit_result` {dimensions_audited, finding_count, severity_distribution}, `diverge_result` {improvements_proposed, creative_ideas}, `patterns[]` {id, source_finding, layer, signature, description, risk, fix_template, confidence}, `confirmation` {test_result, cli_review, overall}, `generalization_stats` {patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}
 
 **phase_goals[]:**
 | ID | Goal | Phase | skip_when |
@@ -110,52 +62,27 @@ SESSION_DIR/
 | 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 |
+| G4 | Zero remaining: all findings/ideas fixed and verified | 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`)
+**understanding.md:** §1 Target & Design Context | §2 Survey | §3 Audit | §4 Diverge | §5 Verify | §6 Generalize | §7 Discover | §8 Learnings
 
 ### Pre-load（可选，缺失不阻塞）
+ARCHITECTURE.md | `maestro search "<target>" --json` (top 5) | `maestro load --type spec --category ui` | `maestro load --type spec --category coding` | `maestro search --category ui` → load knowhow | Glob prior sessions
 
-| 层级 | 命令 | 作用 |
-|------|------|------|
-| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` | 模块边界，组件结构 |
-| Wiki search | `maestro search "<target keywords>" --json` | 先前 UI 决策（取 top 5） |
-| UI specs | `maestro load --type spec --category ui` | 设计规范、token、组件约定 |
-| Coding specs | `maestro load --type spec --category coding` | 编码规范 |
-| Role knowledge | `maestro search --category ui` → 选相关 → `maestro load --type knowhow --id <id>` | 累积设计知识 |
-| Prior sessions | `grep_search(".workflow/scratch/*-ui-odyssey-*")` | 相关会话 |
-
-### Knowledge Persistence（S_RECORD 中写入产出文件）
-
-S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，按以下分类结构化：
-
+### Knowledge Persistence（S_RECORD 写入 understanding.md §8）
 | 分类 | 写入内容 | 后续建议命令 |
 |------|---------|-------------|
 | 设计 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 **3 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). Round 3 = combine both + targeted deep-dive on remaining gaps.
-
-**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
+适用阶段: S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE
 </self_iteration>
 
 <state_machine>
@@ -179,7 +106,6 @@ S_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:
@@ -188,7 +114,6 @@ S_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
@@ -198,213 +123,123 @@ 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 → cross_phase_loops++
-S_DISCOVER → S_FIX          : discovery finds fixable sibling, !skip_fix → cross_phase_loops++
-S_DISCOVER → S_RECORD       : triage complete AND remaining_actionable == 0
-S_DISCOVER → S_RECORD       : loops >= max_loops → MUST log each unfixed item with specific reason (blanket "pre-existing" is forbidden)
+S_DISCOVER → S_AUDIT  : new component to audit → cross_phase_loops++
+S_DISCOVER → S_FIX    : fixable sibling, !skip_fix → cross_phase_loops++
+S_DISCOVER → S_RECORD : remaining_actionable == 0 OR loops >= max_loops (MUST log each unfixed item)
 
-S_RECORD   → END            DO A_RECORD
+S_RECORD   → END      DO A_RECORD
 </transitions>
 
 <actions>
 
 ### A_INTAKE
-1. Parse arguments: target description, flags, `--dimensions` subset
+1. Parse arguments: target, flags, `--dimensions` subset
 2. Generate slug, create `SESSION_DIR`
-3. Search: `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
+3. Pre-load: `maestro search` + 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)
+5. Write `session.json` + `understanding.md` §1
 6. Emit Goal Prompt (see Appendix)
-
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): INTAKE — 目标解析"`
+📌 `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
-```
-Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
-
-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 — 视觉调查"`
+1. **Design system inventory**: Scan for design tokens, CSS variables, theme imports
+2. **Current state analysis**: Styling patterns, layout strategy, component hierarchy
+3. **CLI-assisted** (optional): `maestro delegate` with `--role analyze` — survey tokens, spacing, typography, hierarchy, consistency
+4. Append evidence (phase: "survey"). Update §2. Mark G1 done.
+📌 `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 |
+| Dimension | Focus |
+|-----------|-------|
+| visual_hierarchy | Spacing, typography scale, color contrast, alignment, whitespace, visual weight |
+| interaction_states | Hover, focus, active, disabled, loading, error, empty, selected states |
+| accessibility | WCAG AA contrast, focus management, aria labels, keyboard nav, screen reader |
+| responsiveness | Breakpoints, overflow, touch targets, fluid typography, container queries |
+| micro_interactions | Transitions, animations, feedback indicators, loading states, progress |
+| 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 — 多维审查"`
+Merge → evidence (phase: "audit"). Write `audit_result`. Update §3 (severity matrix). Mark G2 done.
+📌 `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 |
+Goes beyond defect fixing — "what would make this delightful?"
 
-Each returns: `[{idea, category (polish|delight), impact (high|medium|low), effort (small|medium|large), description, inspiration}]`
+**Step 1 — 2 parallel Agents:**
+- **Polish Agent**: Shadows, borders, transitions, hover states, feedback, empty states, skeleton loading, scroll behavior
+- **Delight Agent**: Motion design, progressive disclosure, smart defaults, contextual hints, celebratory feedback, personality in copy
 
-**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
-```
-Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
+Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
 
-**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.
+**Step 2 — CLI-assisted** (optional): `maestro delegate` with `--role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
 
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): DIVERGE — 发散探索"`
+**Step 3 — Consolidate**: Merge audit findings + divergent ideas → prioritized list (severity x impact x effort).
+Append evidence (phase: "diverge"). Update §4. Mark G3 done.
+📌 `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 — 优化实现"`
+Skip if `--skip-fix`.
+1. **穷尽修复**: ALL findings/ideas by priority tier (critical→high→medium→low + high-impact ideas). After each tier, re-review — new findings append.
+2. Each fix → evidence (phase: "fix")
+3. **Normal**: ask_question per-fix. **`-y`**: auto-proceed, record `deferred`.
+📌 `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
-```
-Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
-
-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 — 验证"`
+1. Run tests (lint, unit, visual regression)
+2. **CLI-assisted**: `maestro delegate` with `--role review` — visual correctness, interaction states, accessibility, responsive
+3. `needs_rework` → S_FIX. `verified` → mark G4 done. Update §5, write `confirmation`.
+📌 `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 — 泛化扫描"`
+按 base A_GENERALIZE 执行。Pattern 来源: audit findings + diverge ideas (severity >= medium OR impact = high)。Mark G5 done.
+📌 `git commit -m "odyssey-ui({slug}): GENERALIZE — 泛化扫描"`
 
 ### A_DISCOVER
-Classify each hit: `needs_treatment` / `low_risk` / `already_handled`.
-- `needs_treatment` + directly fixable → **fix immediately** → back to S_FIX
-- `needs_treatment` + requires design direction decision → create issue (with fix suggestion)
-- `low_risk` → evaluate if a quick guard/improvement is feasible; if yes, fix it
-- `already_handled` → mark skip
-
-**Normal**: ask_question for routing ambiguity. **`-y`**: auto-fix what's fixable, create issue for rest.
-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 — 发现分类"`
+按 base A_DISCOVER 执行。Mark G6 done.
+📌 `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:
+1. Finalize §8: 按 Knowledge Persistence 表分类记录，completion summary 列出建议的 `/spec-add` 命令
+2. Pending decisions: **Normal** → ask_question. **`-y`** → skip, show deferred count
+3. Goal audit: all confirmed → `phase_goals_all_done = true`. **Normal** → ask_question | **`-y`** → auto accept
+4. Mark G7 done. 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)
+Target: {target} | Dimensions: {dimensions_audited}
+Findings: {C}C {H}H {M}M {L}L | Diverge: {improvements} polish + {creative} delight
+Fix: {fixed_count} applied, verified={yes|skipped}
+Patterns: {extracted} ({by_layer}) | Scan hits: {total} ({cross_layer} cross-layer)
+Issues: {N} | Decisions: {N} resolved, {M} pending, {K} deferred
+Learnings: {N} entries | Self-iter: {N} rounds | Goals: {done}/{total} ({skipped} skipped)
 ---
 ```
-
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-ui({slug}): RECORD — 会话总结"`
+📌 `git commit -m "odyssey-ui({slug}): RECORD — 会话总结"`
 
 </actions>
 
 <appendix>
 
 ### Goal Prompt Template
-**⚠️ 时机守卫：仅在 A_INTAKE 完成后显示一次（session 创建后、开始 survey 前）。A_RECORD 完成时禁止重新显示。**
+**⚠️ 仅在 A_INTAKE 完成后显示一次。A_RECORD 完成时禁止重新显示。**
 
 ```
-📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件（执行过程中输入即可）：
+📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
 
 /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）
+穷尽迭代：直到 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` |
 |----------------|--------|------|
@@ -414,12 +249,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 | 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`.
+`deferred` → "待决策" in completion summary; recoverable via `-c`.
 
 </appendix>
 
@@ -430,29 +260,16 @@ Goals:      {done}/{total} ({skipped} skipped)
 |------|----------|-----------|----------|
 | 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
+- [ ] 6-dimension audit with severity matrix + divergent exploration (polish + delight)
 - [ ] 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
-- [ ] **Every unfixed finding has individual classification and reason** — blanket "pre-existing" labels are forbidden
-- [ ] 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
+- [ ] Multi-layer generalization + discoveries classified (unless --skip-generalize)
+- [ ] Every unfixed finding has individual classification and reason
+- [ ] understanding.md §8 finalized; phase_goals G1-G7 tracked; `-y` no blocking prompts
 </success_criteria>
 
 <next_step_routing>

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

@@ -187,7 +187,9 @@ Write enriched args + source_artifact_ref back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+2. **Goal context pre-injection**:
+   - GUARD: `ralph_protocol_version >= "2"` → skip（session_anchor 已含 goal context）
+   - WHEN `ralph_protocol_version < "2"` 或缺失 AND `step.goal_ref` 非空 → 在 stdout 顶部前置：
    ```
    <goal_context>
    Sub-goal: {goal.id} — {goal.goal}
@@ -197,13 +199,19 @@ Write enriched args + source_artifact_ref back to status.json.
    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
+3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
 4. **Complete**:
-   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `Bash("maestro ralph complete N --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
+   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
    - `Bash("maestro ralph retry N")`
    - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+
+   | Param | 必填 | 格式 | 示例 |
+   |-------|------|------|------|
+   | `--summary` | MUST | 动词开头，≤100 字 | `"实现搜索 API 分页逻辑，新增 3 端点"` |
+   | `--decisions` | SHOULD（可多次） | 每条一个决策 | `"选择 ELK 布局而非 dagre"` |
+   | `--caveats` | SHOULD | 后续注意事项 | `"X 模块 e2e 暂未覆盖新端点"` |
+   | `--deferred` | SHOULD（可多次） | 推迟工作 | `"性能优化留到 review 后"` |
 5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `Skill({ skill: "maestro-ralph-execute" })` 自调用。
@@ -282,8 +290,11 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。/maestro
 - [ ] 自调用持续到全部 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 injection：`ralph_protocol_version < "2"` → 前置 `<goal_context>` block；`>= "2"` → skip（session_anchor 覆盖）
 - [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
 - [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
+- [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] `--decisions`/`--caveats`/`--deferred` 为 SHOULD；存在关键决策/注意事项/推迟工作时填写
+- [ ] 结构化总结由 CLI 写入 status.json，session_anchor 自动聚合注入下游 step
 
 </appendix>