maestro-flow 0.5.39 → 0.5.41

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

@@ -1,259 +1,291 @@
 ---
 name: odyssey-ui
-description: "Long-running UI optimization cycle — visual survey, multi-dimensional audit, divergent exploration, fix, verify, generalize, and design knowledge persistence"
+description: "Long-running UI optimization cycle — visual survey, multi-dimensional audit, divergent exploration, fix, verify, generalize, discover, and design knowledge persistence"
 argument-hint: '"<target>" [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]'
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
-<base>@~/.maestro/workflows/odyssey-base.md</base>
+<base>@~/.maestro/workflows/odyssey-base-codex.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.
-
-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 code
-
-**三句哲学约束（穷尽迭代）:**
-1. **零遗留** — 每个 finding/idea 必须是 action item（修复 / issue / 决策），不允许只报告不处理
-2. **穷尽迭代** — 按 impact×severity 递降逐轮修复，直到 0 remaining actionable 才退出 fix loop
-3. **改进即标准** — 每次修复后重审同区域，发现新视觉问题继续修，直到该区域无可改善
+survey -> 6-dimension audit -> divergent creative exploration ->
+fix -> verify -> generalize -> discover -> persist.
+Exhaustive iteration until all findings addressed or deferred.
 </purpose>
 
 <boundary>
-**范围内:** 目标组件/页面的视觉体验优化 — 审查 6 维度 → 发散探索 → 修复 → 泛化到兄弟组件
-**范围外:** 后端逻辑 / 数据模型 / 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
+**In scope:** Target component/page visual experience optimization -- audit 6 dimensions -> divergent exploration -> fix -> generalize to sibling components.
+**Out of scope:** Backend logic / data model / API design -> `$odyssey-planex` | Deep bug investigation -> `$odyssey-debug` | Code quality review -> `$odyssey-review-test-fix`
+
+**Exploration freedom:** Maximum freedom within boundary -- S_DIVERGE encourages divergent thinking with no creative ceiling. Audit + diverge may discover any visual/interaction/accessibility detail.
+**Zero-residual:** Every finding/idea MUST have a concrete action (fix / issue / decision). "Pre-existing design debt" is not a valid skip reason.
+
+**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
 </boundary>
 
 <context>
-$ARGUMENTS — target and optional flags.
+$ARGUMENTS
 
-**Target resolution:** Component path → audit component | Page/route → audit page | `staged`/`HEAD` → diff UI changes | Feature area → resolve to 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 |
-| `--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 |
+**Flags:** `--dimensions <list>` subset of 6 dims | `--fix-threshold <severity>` | `--skip-fix` audit+diverge only | `--skip-generalize` skip S_GENERALIZE+S_DISCOVER | `--auto` no delegate confirmation | `-y` auto-confirm | `-c` resume | `--heartbeat` /loop heartbeat
 
-**Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
+**Session**: `.workflow/scratch/{YYYYMMDD}-ui-odyssey-{slug}/`
+**Output**: `session.json` | `evidence.ndjson` | `understanding.md`
 
-**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)
+**session.json -- ui-specific fields:**
+```json
+{ "target": "", "dimensions": [], "audit_result": null, "diverge_result": null,
+  "patterns": [], "confirmation": null, "generalization_stats": null }
+```
 
-**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}
+**evidence.ndjson phases:** `survey|audit|diverge|fix|discovery|decision|self-iteration`
 
 **phase_goals[]:**
+
 | ID | Goal | Phase | skip_when |
 |----|------|-------|-----------|
-| G1 | Survey completed | S_SURVEY | — |
-| G2 | Audit completed | S_AUDIT | — |
-| G3 | Divergent exploration done | S_DIVERGE | — |
+| 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 | S_VERIFY | skip_fix |
 | G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
 | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
-| G7 | Learnings persisted | S_RECORD | — |
+| G7 | Learnings persisted | S_RECORD | -- |
 
-**understanding.md:** §1 Target & Design Context | §2 Survey | §3 Audit | §4 Diverge | §5 Verify | §6 Generalize | §7 Discover | §8 Learnings
+**understanding.md -- 8 sections:**
+1. Target & Design Context <- S_INTAKE | 2. Survey <- S_SURVEY | 3. Audit <- S_AUDIT | 4. Diverge <- S_DIVERGE
+5. Verify <- S_VERIFY | 6. Generalize <- S_GENERALIZE | 7. Discover <- S_DISCOVER | 8. Learnings <- S_RECORD
 
-### 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
+**Knowledge Persistence (S_RECORD writes understanding.md section 8):**
 
-### Knowledge Persistence（S_RECORD 写入 understanding.md §8）
-| 分类 | 写入内容 | 后续建议命令 |
-|------|---------|-------------|
-| 设计 pattern | 组件模式 + 适用场景 + token 引用 | `/spec-add ui "..."` |
-| 交互规范 | 状态定义 + 转场规则 + 反馈模式 | `/spec-add ui "..."` |
-| 可访问性规则 | WCAG 要求 + 实现方案 | `/spec-add ui "..."` |
-| 可复用泛化 pattern | pattern 签名 + 应用范围 | `/spec-add coding "..."` |
+| Category | Content | Follow-up |
+|----------|---------|-----------|
+| Design pattern | Component pattern + applicable scenarios + token references | `/spec-add ui "..."` |
+| Interaction spec | State definitions + transition rules + feedback patterns | `/spec-add ui "..."` |
+| Accessibility rules | WCAG requirements + implementation approach | `/spec-add ui "..."` |
+| Reusable generalization pattern | Pattern signature + application scope | `/spec-add coding "..."` |
 </context>
 
+<csv_schema>
+
+### Shared Output Schema (all waves)
+```json
+{
+  "type": "object",
+  "properties": {
+    "id": { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "findings": { "type": "string", "maxLength": 500 },
+    "evidence": { "type": "string" },
+    "error": { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+**Termination contract:** Call `report_agent_job_result` EXACTLY ONCE. Read-only. Do NOT modify source files, tasks.csv, wave-*.csv, results.csv, or call spawn_agents_on_csv.
+
+### tasks.csv
+```csv
+id,title,description,task_type,dimension,deps,wave,status,findings,evidence,error
+```
+
+**Waves:**
+| Wave | Tasks | Parallelism |
+|------|-------|-------------|
+| 1 | Survey (design-tokens-audit, pattern-inventory) | 2 agents |
+| 2 | Audit (visual-hierarchy, interaction-states, accessibility, responsiveness, micro-interactions, edge-cases) | 6 agents |
+| 3 | Diverge (polish-agent, delight-agent) | 2 agents |
+| 4 | Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) | 4 agents |
+</csv_schema>
+
+<invariants>
+1-5: See base (evidence append-only, session is state, phase goal tracking, auto-commit, zero silent drops).
+6. **Browser is truth** -- verify in real rendering, not just code review
+7. **Diverge before converge** -- explore creatively first, then implement methodically
+</invariants>
+
 <self_iteration>
-适用阶段: S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE
+Applies to: **S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE**. Logic in base.
 </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
+S_INTAKE -> S_SURVEY -> S_AUDIT -> S_DIVERGE -> S_FIX -> S_VERIFY -> S_GENERALIZE -> S_DISCOVER -> S_RECORD -> END
 </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 request_user_input
-
-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  : 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_INTAKE -> S_INTAKE       : -c + session found -> A_RESUME
+S_INTAKE -> S_SURVEY       : target resolved -> A_INTAKE
+S_INTAKE -> S_INTAKE       : no target -> request_user_input
+
+S_SURVEY  -> S_AUDIT       : complete
+S_AUDIT   -> S_DIVERGE     : complete
+
+S_DIVERGE -> S_FIX          : !skip_fix AND actionable findings/ideas
+S_DIVERGE -> S_GENERALIZE   : (skip_fix OR no actionable) AND !skip_gen
+S_DIVERGE -> S_RECORD       : (skip_fix OR no actionable) AND skip_gen
+
+S_FIX     -> S_VERIFY       : fix implemented
+S_VERIFY  -> S_GENERALIZE   : verified AND !skip_gen
+S_VERIFY  -> S_RECORD       : verified AND skip_gen
+S_VERIFY  -> S_FIX          : needs_rework
+
+S_GENERALIZE -> S_DISCOVER  : hits found
+S_GENERALIZE -> S_RECORD    : no hits
+
+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 (log per-item reasons)
+
+S_RECORD   -> END           : complete
 </transitions>
 
 <actions>
 
 ### A_INTAKE
 1. Parse arguments: target, flags, `--dimensions` subset
-2. Generate slug, create `SESSION_DIR`
-3. Pre-load: `maestro search` + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
+2. Generate slug, create SESSION_DIR
+3. `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
-6. Emit Goal Prompt (see Appendix)
-📌 `git commit -m "odyssey-ui({slug}): INTAKE — 目标解析"`
+5. Write `session.json` + `understanding.md` section 1, emit Goal Prompt
+
+Commit: `"odyssey-ui({slug}): INTAKE -- target parsed"`
 
 ### A_RESUME
-Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
+Glob latest session -> read `session.json` -> jump to `current_state`.
 
 ### A_SURVEY
-1. **Design system inventory**: Scan for design tokens, CSS variables, theme imports
-2. **Current state analysis**: Styling patterns, layout strategy, component hierarchy
-3. **spawn_agents_on_csv (Wave 1)** — 2 agents: design-tokens-audit, pattern-inventory
-4. Append evidence (phase: "survey"). Update §2. Mark G1 done.
-📌 `git commit -m "odyssey-ui({slug}): SURVEY — 视觉调查"`
+**spawn_agents_on_csv (Wave 1):**
 
-### A_AUDIT
-**spawn_agents_on_csv (Wave 2)** — 6 parallel agents (one per dimension, or `--dimensions` subset):
+Write `tasks.csv` with Wave 1 rows:
+```csv
+"survey-tokens","Design Token Audit","Scan {target_files} for CSS variables, design tokens, theme values. Return [{token,usage_count,consistency,file,line}].","survey","","","1","pending","","",""
+"survey-patterns","Pattern Inventory","Catalog component patterns, layout, spacing, typography in {target_files}. Return [{pattern,files,consistency}].","survey","","","1","pending","","",""
+```
+`spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:2, max_runtime_seconds:300, output_csv_path:"wave-1-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })`
+
+Merge -> evidence (phase: "survey"). Update section 2. Mark G1 done.
+Commit: `"odyssey-ui({slug}): SURVEY -- visual landscape"`
 
-| 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 |
+### A_AUDIT
+**spawn_agents_on_csv (Wave 2)** -- 6 agents (one per dimension, or `--dimensions` subset):
+
+Append Wave 2 rows to `tasks.csv`:
+```csv
+"audit-hierarchy","Visual Hierarchy","Spacing, typography scale, contrast, alignment, whitespace, visual weight","audit","visual-hierarchy","","2","pending","","",""
+"audit-interaction","Interaction States","hover/focus/active/disabled/loading/error/empty/selected states","audit","interaction-states","","2","pending","","",""
+"audit-a11y","Accessibility","WCAG AA contrast, focus mgmt, aria, keyboard nav, screen reader","audit","accessibility","","2","pending","","",""
+"audit-responsive","Responsiveness","Breakpoints, overflow, touch targets >=44px, fluid typography","audit","responsiveness","","2","pending","","",""
+"audit-motion","Micro-interactions","Transitions, animations, feedback, loading states, scroll behavior","audit","micro-interactions","","2","pending","","",""
+"audit-edge","Edge Cases","Long text, empty data, error states, extreme values, i18n, RTL","audit","edge-cases","","2","pending","","",""
+```
+`spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:6, max_runtime_seconds:600, output_csv_path:"wave-2-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })`
 
 Each returns `[{title, severity, file, line, description, suggestion, dimension}]`.
-Merge → evidence (phase: "audit"). Write `audit_result`. Update §3 (severity matrix). Mark G2 done.
-📌 `git commit -m "odyssey-ui({slug}): AUDIT — 多维审查"`
+Merge -> evidence (phase: "audit"). Write `audit_result` with dimensions, finding count, severity distribution. Update section 3 (severity matrix). Mark G2 done.
+Commit: `"odyssey-ui({slug}): AUDIT -- 6-dimension review"`
 
 ### A_DIVERGE
-Goes beyond defect fixing — "what would make this delightful?"
-
-**Step 1 — spawn_agents_on_csv (Wave 3)** — 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
+**spawn_agents_on_csv (Wave 3)** -- 2 agents:
 
-Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
-
-**Step 2 — CLI-assisted** (optional): `maestro delegate` with `--role analyze` — polish opportunities, micro-interactions, visual rhythm, delight moments
+Append Wave 3 rows to `tasks.csv`:
+```csv
+"diverge-polish","Polish Agent","Missing subtle details: shadows, borders, transitions, hover feedback, empty states, skeleton loading, scroll behavior. Return [{idea,category:'polish',impact,effort,description}].","diverge","","","3","pending","","",""
+"diverge-delight","Delight Agent","What makes this memorable: motion design, progressive disclosure, smart defaults, celebratory feedback, personality. Return [{idea,category:'delight',impact,effort,description}].","diverge","","","3","pending","","",""
+```
+`spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:2, max_runtime_seconds:300, output_csv_path:"wave-3-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })`
+
+**Optional CLI delegate** for creative review:
+```bash
+maestro delegate "PURPOSE: Creative UI review for: {target}
+TASK: Identify polish opportunities | Suggest delight moments | Evaluate visual rhythm
+MODE: analysis  CONTEXT: @{target_files} | Survey: {token_summary} | Audit: {top_findings}
+EXPECTED: JSON [{idea, category, impact, effort, description}]
+CONSTRAINTS: User-perceptible improvements only
+" --role analyze --mode analysis
+```
+Execute with `run_in_background: true`, then wait for callback.
 
-**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 — 发散探索"`
+Consolidate: audit findings + divergent ideas -> prioritized improvement list (impact/effort matrix). Write `diverge_result`. Append evidence (phase: "diverge"). Update section 4. Mark G3 done.
+Commit: `"odyssey-ui({slug}): DIVERGE -- creative exploration"`
 
 ### A_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**: request_user_input per-fix. **`-y`**: auto-proceed, record `deferred`.
-📌 `git commit -m "odyssey-ui({slug}): FIX — 优化实现"`
+1. **Exhaustive fix**: 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: request_user_input per-fix. `-y`: auto-proceed, record `deferred`.
+
+Commit: `"odyssey-ui({slug}): FIX -- improvements applied"`
 
 ### A_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 — 验证"`
+2. CLI-assisted: `maestro delegate --role review` -- visual correctness, interaction states, accessibility, responsive
+3. `needs_rework` -> S_FIX. `verified` -> mark G4 done. Update section 5, write `confirmation`.
+
+Commit: `"odyssey-ui({slug}): VERIFY -- visual verification"`
 
 ### A_GENERALIZE
-按 base A_GENERALIZE 执行。Pattern 来源: audit findings + diverge ideas (severity >= medium OR impact = high)。
-**spawn_agents_on_csv (Wave 4)** — 4 agents: syntax-grep, semantic-scan, structural-match, historical-grep.
-Mark G5 done.
-📌 `git commit -m "odyssey-ui({slug}): GENERALIZE — 泛化扫描"`
-
-### A_DISCOVER
-按 base A_DISCOVER 执行。Mark G6 done.
-📌 `git commit -m "odyssey-ui({slug}): DISCOVER — 发现分类"`
-
-### A_RECORD
-1. Finalize §8: 按 Knowledge Persistence 表分类记录，completion summary 列出建议的 `/spec-add` 命令
-2. Pending decisions: **Normal** → request_user_input. **`-y`** → skip, show deferred count
-3. Goal audit: all confirmed → `phase_goals_all_done = true`. **Normal** → request_user_input | **`-y`** → auto accept
-4. Mark G7 done. Emit completion summary:
+Skip if `--skip-generalize`. Pattern source: audit findings + diverge ideas (severity >= medium OR impact = high).
+
+**Wave 4 -- 4-agent scan (spawn_agents_on_csv):**
+
+Append Wave 4 rows to `tasks.csv`:
+```csv
+"gen-syntax","Syntax Grep","Grep CSS/style patterns matching '${signatures}' across project","generalization","syntax","","4","pending","","",""
+"gen-semantic","Semantic Scan","Find components with same interaction pattern but missing states","generalization","semantic","","4","pending","","",""
+"gen-structural","Structural Match","Find structurally similar components, check for same issues","generalization","structural","","4","pending","","",""
+"gen-historical","Historical Grep","git log -S '${signature}' for UI pattern history","generalization","historical","","4","pending","","",""
+```
+`spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:4, max_runtime_seconds:600, output_csv_path:"wave-4-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })`
+
+Cross-layer dedup + iterative deepening per base. Update section 6. Mark G5 done.
+Commit: `"odyssey-ui({slug}): GENERALIZE -- pattern scan"`
+
+### A_DISCOVER, A_RECORD
+Base shared_actions. UI overrides:
+- **A_DISCOVER** routing per base triage logic
+- **A_RECORD** learnings per Knowledge Persistence table
+
+**Completion summary:**
 ```
 --- UI ODYSSEY COMPLETE ---
-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)
+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} created
+Decisions:  {N} resolved, {M} pending, {K} deferred
+Learnings:  {N} entries
+Self-iter:  {N} rounds
+Goals:      {done}/{total} ({skipped} skipped)
 ---
 ```
-📌 `git commit -m "odyssey-ui({slug}): RECORD — 会话总结"`
 
 </actions>
 
 <appendix>
 
-### Goal Prompt Template
-**⚠️ 仅在 A_INTAKE 完成后显示一次。A_RECORD 完成时禁止重新显示。**
-
-```
-📋 UI Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
-
-/goal 完成以下目标：
-{for each G in phase_goals where status != "skipped":}
-- {G.id}: {G.goal} — 完成条件: {G.done_when}
-{end for}
-穷尽迭代：直到 audit + diverge findings 均已处理（fix/issue/decision）
-且 phase_goals_all_done=true 才停。修复按 impact×severity 逐轮迭代。
-每轮修复后重审修改区域，新发现追加继续修。
-遇到 phase=decision 的 pending 必须 request_user_input。不允许"只报告不处理"。
-```
+### `-y` ui-specific points
 
-### `-y` Auto-Confirm (5 decision points)
 | Decision Point | Normal | `-y` |
 |----------------|--------|------|
 | A_FIX improvement confirmation | request_user_input | auto-proceed, `deferred` |
-| A_DISCOVER hit routing | request_user_input | auto create issue, `deferred` |
-| A_DISCOVER ambiguous items | request_user_input | all `deferred` |
-| A_RECORD pending decisions | request_user_input | skip, show deferred count |
-| A_RECORD goal audit | request_user_input | auto accept |
 
-`deferred` → "待决策" in completion summary; recoverable via `-c`.
+### Goal Prompt convergence rules
+
+```
+Exhaustive iteration: process all audit + diverge findings (fix/issue/decision)
+until phase_goals_all_done=true. Fix by impact x severity per tier.
+Re-review modified areas after each fix round -- new findings appended.
+phase=decision pending items MUST request_user_input. No report-only items.
+```
 
 </appendix>
 
@@ -273,15 +305,15 @@ Learnings: {N} entries | Self-iter: {N} rounds | Goals: {done}/{total} ({skipped
 - [ ] Improvements implemented and verified (unless --skip-fix)
 - [ ] 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
+- [ ] understanding.md section 8 finalized; phase_goals G1-G7 tracked; `-y` no blocking prompts
 </success_criteria>
 
 <next_step_routing>
-| Condition | Next step |
-|-----------|-----------|
+| Condition | Next |
+|-----------|------|
 | 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>` |
+| Full review of changes | `$odyssey-review-test-fix <changed-files>` |
 | Sibling components to polish | `$odyssey-ui "<sibling>"` |
 </next_step_routing>

package/.codex/skills/quality-review/SKILL.md

@@ -149,9 +149,9 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 3. **CSV is Source of Truth**: Master tasks.csv holds all state
 4. **Context Propagation**: prev_context built from master CSV, not from memory
 5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
-6. **Skip on Failure**: If all dimension agents failed, skip aggregation
+6. **Skip on Failure**: If all dimension agents failed, skip aggregation and flag all downstream outputs as LOW CONFIDENCE. Record `degradation_event` in discoveries.ndjson. **Note**: timed-out workers that report `completed` with empty findings are treated as effectively failed for degradation purposes if `severity_counts` is all-zero AND `findings` is empty. This is a defined degradation path, not a violation of invariant 2.
 7. **Cleanup Temp Files**: Remove wave-{N}.csv and wave-{N}-results.csv after results are merged
-8. **DO NOT STOP**: Continuous execution until all waves complete
+8. **Pipeline continuity**: Continuous execution until all waves complete. When invariant 6 (skip on failure) activates, the pipeline continues in degraded mode.
 </invariants>
 
 <execution>
@@ -275,9 +275,9 @@ CONSTRAINTS:
 
 #### Wave 2: Aggregation + Deep-Dive
 
-Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation.
+Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation (invariant 6).
 
-Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
+Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task). **Failed-dependency handling**: exclude failed task IDs from prev_context. If SOME wave 1 tasks failed, append gap_note listing missing dimensions so the aggregation agent knows its coverage is incomplete.
 Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` with `REVIEW_AGGREGATION_INSTRUCTION` (same termination contract; output_schema returns `result_status` enum [completed|failed], findings, plus `verdict` enum [PASS|WARN|BLOCK]) → merge results into master `tasks.csv` (map `result_status` → master `status` column) → delete both `wave-2.csv` and `wave-2-results.csv`.
 
 ### Phase 3: Results Aggregation
@@ -344,7 +344,14 @@ Generate `context.md`:
 | Medium findings > 5 | WARN |
 | Otherwise | PASS |
 
-**Issue creation** by level threshold:
+**Side-effect confirmation gate** (skip when `-y/--yes`):
+Before writing to external stores, present a summary to the user via `request_user_input`:
+- Issues to create (count + severity + titles)
+- Phase index update (artifact dir)
+- Artifact registration in state.json
+The user can approve all, selectively exclude, or skip entirely.
+
+**Issue creation** (approved items only) by level threshold:
 
 | Level | Create Issues For |
 |-------|------------------|
@@ -354,11 +361,11 @@ Generate `context.md`:
 
 **Spec conflict check**: If any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark <file> <line> --note "<evidence>"` on the spec entry. Code is the single source of truth. Log spec conflicts in review.json as `spec_conflicts[]`.
 
-**Phase index update**: Update `{artifact_dir}/index.json` with review status.
+**Phase index update** (after confirmation): Update `{artifact_dir}/index.json` with review status.
 
-**Register artifact**: Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
+**Register artifact** (after confirmation): Append to `state.json.artifacts[]` with `type: "review"`, `id: REV-NNN`, `path: "scratch/{YYYYMMDD}-review-P{N}-{slug}"`, `depends_on: exec_art.id`. Output directory is independent scratch, not shared with plan.
 
-Display summary. If spec conflicts detected, suggest: `maestro spec conflict list` → `$manage-knowledge-audit --scope spec`.
+Display summary. **Next-step suggestion** (suggest only, NEVER auto-execute): if spec conflicts detected, suggest `maestro spec conflict list` → `$manage-knowledge-audit --scope spec`. The user decides whether to proceed.
 
 ### Shared Discovery Board Protocol
 
@@ -410,8 +417,8 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"s
 - [ ] Aggregation + deep-dive executed (wave 2)
 - [ ] review.json produced with verdict and severity distribution
 - [ ] context.md produced with full review report
-- [ ] Issues auto-created for qualifying severity findings
-- [ ] Phase index.json updated with review status
+- [ ] Issues created for qualifying severity findings (after user confirmation in interactive mode; auto in -y mode)
+- [ ] Phase index.json updated with review status (after user confirmation in interactive mode; auto in -y mode)
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Ralph-invoked: `maestro ralph complete <idx> --status {STATUS}` called with correct verdict
 </success_criteria>

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -25,15 +25,12 @@
 
 2. **Explore domain** (use CLI analysis tools):
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Research domain for {requirement}
+   shell_exec(`maestro delegate "PURPOSE: Research domain for {requirement}
    TASK: • Identify problem statement • Define target users • Extract constraints • Map integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Structured research context with problem/users/domain/constraints
-   CONSTRAINTS: Read-only analysis" --role analyze --mode analysis --rule analysis-trace-code-execution`,
-     yield_time_ms: 30000, max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   CONSTRAINTS: Read-only analysis" --role analyze --mode analysis --rule analysis-trace-code-execution`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    ```
 
 3. **Extract structured context**:
@@ -296,15 +293,12 @@
 
 2. **Explore codebase** (use CLI analysis tools):
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Explore codebase for {requirement}
+   shell_exec(`maestro delegate "PURPOSE: Explore codebase for {requirement}
    TASK: • Identify relevant files • Find existing patterns • Locate integration points
    CONTEXT: @**/* | Memory: {requirement}
    EXPECTED: Exploration findings with file paths and patterns
-   CONSTRAINTS: Read-only analysis" --role explore --mode analysis --rule analysis-trace-code-execution`,
-     yield_time_ms: 30000, max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   CONSTRAINTS: Read-only analysis" --role explore --mode analysis --rule analysis-trace-code-execution`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    ```
 
 3. **Generate implementation plan**: