maestro-flow 0.5.39 → 0.5.40

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -35,7 +35,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
+Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip ONLY when `-y/--yes`, `--revise`, `--review`, or `-c` is set. Text requirements always require at least scope + strategy confirmation — never auto-classify input as "specific enough" to skip.
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
 - Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
@@ -73,8 +73,8 @@ Wave 1: 3 analysis rows (parallel). Wave 2: 1 assembly row.
 2. **CSV is source of truth**: Master tasks.csv holds all state
 3. **Context propagation**: prev_context from master CSV, not memory
 4. **Discovery board append-only**: Never modify/delete discoveries.ndjson
-5. **Graceful degradation**: Wave 1 fails -> Wave 2 proceeds with seed input only. When degradation activates, flag downstream outputs as LOW CONFIDENCE.
-6. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation.
+5. **Graceful degradation**: Wave 1 fails -> Wave 2 proceeds with seed input only. When degradation activates, flag downstream outputs as LOW CONFIDENCE. Record `degradation_event` in discoveries.ndjson. This is a defined degradation path, not a violation of invariant 6.
+6. **Invariant violation = BLOCK** — violating any invariant above blocks the current operation. Defined degradation paths (invariant 5) are not violations.
 7. **Requirement mapping completeness** — every Active requirement from project.md MUST be mapped to exactly one phase. No circular dependencies in phase ordering.
 8. **Artifact verification before completion** — .workflow/roadmap.md MUST exist with Milestone > Phase hierarchy and progress table. Artifact MUST be registered in state.json. If missing: DO NOT report completion.
 </invariants>
@@ -104,10 +104,13 @@ S_CSV_GEN:
   -> S_WAVE_1       DO: generate analysis CSV
 
 S_WAVE_1:
-  -> S_WAVE_2       DO: A_SPAWN_WAVE_1
+  -> S_WAVE_2       WHEN: 1+ completed    DO: A_SPAWN_WAVE_1. For failed analysis tasks: exclude from prev_context and append gap_note to W2 instruction listing missing angles.
+  -> S_WAVE_1       WHEN: all failed, retry available   DO: retry once
+  -> S_WAVE_2       WHEN: all failed, retry exhausted   DO: proceed with seed input only, flag LOW CONFIDENCE (invariant 5 degradation)
 
 S_WAVE_2:
-  -> S_AGGREGATE    DO: A_SPAWN_WAVE_2
+  -> S_AGGREGATE    WHEN: completed    DO: A_SPAWN_WAVE_2
+  -> ERROR          WHEN: failed       DO: abort "Roadmap generation failed"
 
 S_AGGREGATE:
   -> END            DO: A_AGGREGATE_RESULTS
@@ -178,7 +181,7 @@ Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depen
 2. Interactive refinement (max 3 rounds, skip if -y): Approve / Refine / Regenerate
 3. Generate context.md (summary + analysis findings + roadmap stats)
 4. Write .workflow/roadmap.md with Milestone > Phase hierarchy
-5. Update state.json milestones + current_milestone
+5. Update state.json milestones + current_milestone + register RDM artifact
 6. **Generate context-package.json** (schema `context-package/1.0`):
    ```jsonc
    {
@@ -194,7 +197,11 @@ Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depen
    }
    ```
    Register `context_package` path in RDM artifact entry so downstream `--from roadmap:ID` can resolve.
-7. Next-step routing: need analysis -> maestro-analyze; ready to plan -> maestro-plan; UI first -> maestro-impeccable build; need formal specs -> maestro-blueprint
+7. **Next-step suggestion** (suggest only, NEVER auto-execute): display the recommended next command. The user decides whether to proceed.
+   - Need analysis → `maestro-analyze`
+   - Ready to plan → `maestro-plan`
+   - UI first → `maestro-impeccable build`
+   - Need formal specs → `maestro-blueprint`
 
 </actions>
 
@@ -243,4 +250,3 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 ```
 Status verdicts: **DONE** (normal), **DONE_WITH_CONCERNS** (caveats; pass `--concerns`), **NEEDS_RETRY** (transient error), **BLOCKED** (hard blocker; pass `--reason`).
 </ralph_completion>
-</output>

package/.codex/skills/manage-learn/SKILL.md

@@ -47,7 +47,7 @@ $manage-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag
 </context>
 
 <invariants>
-1. **No LLM or CLI calls**: This skill is pure file I/O — parse, infer, append, confirm. No `exec_command`, no `spawn_agent`.
+1. **No LLM or CLI calls**: This skill is pure file I/O — parse, infer, append, confirm. No `shell_exec`, no `spawn_agent`.
 2. **Bootstrap on demand**: Create `.workflow/knowhow/` structure on first use; do not require it to exist.
 3. **Append-only learnings.md**: Never rewrite or delete existing entries.
 4. **Stable INS-ids**: `INS-{8hex}` from `hash(insightText + timestamp)` — same text at different times gets different ids.

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

@@ -98,6 +98,36 @@ $ARGUMENTS — issue description and optional flags.
 | 可复用泛化 pattern | `/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** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+Success → result_status=completed | Failure → result_status=failed with error | Timeout → completed with partial.
+NEVER continue indefinitely. NEVER exit silently. Read-only — do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv.
+```
+
+### tasks.csv
+```csv
+id,title,description,task_type,deps,wave,status,findings,evidence,error
+```
+- Wave 1: Archaeology (git-timeline, git-blame) — parallel
+- Wave 2: Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) — parallel, depends on root cause
+- Single-agent stages (explore, diagnose, fix, confirm) remain inline
+</csv_schema>
+
 <self_iteration>
 适用阶段: S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE
 </self_iteration>
@@ -152,9 +182,25 @@ S_RECORD   → END            : A_RECORD complete
 Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
 
 ### A_ARCHAEOLOGY
-**2 parallel agents (spawn_agents_on_csv):** Timeline (`git log --oneline -20 -- {files}`) + Blame (top 3 suspicious files `git blame -L {region}`). Append evidence (phase: "archaeology").
+**Step 1 — Git archaeology (spawn_agents_on_csv, Wave 1):**
+
+Write `tasks.csv` with Wave 1 rows:
+```csv
+id,title,description,task_type,deps,wave,status,findings,evidence,error
+"arch-timeline","Git Timeline","Run git log --oneline -20 -- {files}. Return [{sha,date,author,message,files_changed}] as JSON.","archaeology","","1","pending","","",""
+"arch-blame","Git Blame","Top 3 suspicious files: git blame -L {region}. Return [{file,line_range,sha,author,date,content}] as JSON.","archaeology","","1","pending","","",""
+```
+
+```javascript
+spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
+  instruction: ARCHAEOLOGY_INSTRUCTION + TERMINATION_CONTRACT,
+  max_concurrency:2, max_runtime_seconds:300,
+  output_csv_path:"wave-1-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })
+```
+
+Merge results → evidence.ndjson (phase: "archaeology").
 
-**CLI change review** via `maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
+**Step 2 — CLI change review** via `maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
 - PURPOSE: Review recent modifications related to {issue}
 - EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
 
@@ -200,7 +246,42 @@ Increment `diagnosis_retries`. < 3: broaden via `maestro delegate --role analyze
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): CONFIRM — 修复验证"`
 
 ### A_GENERALIZE
-按 base A_GENERALIZE 执行。Pattern 来源: root cause + fix。统计写入 `session.json.generalization_stats`。Mark G4 done.
+Skip if `--skip-generalize`. Pattern 来源: root cause + fix。
+
+**Step 1 — Multi-layer pattern extraction:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex patterns (direct Grep) | `eval(`, missing `await`, unclosed resource |
+| Semantic | Anti-pattern description (Agent scan) | Unhandled async errors, unvalidated input |
+| Structural | Architecture-level similarity | Same import structure, missing override |
+
+Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template}]`
+
+**Step 2 — 4-agent scan (spawn_agents_on_csv, Wave 2):**
+
+Append Wave 2 rows to `tasks.csv`:
+```csv
+"gen-syntax","Syntax Grep","Grep syntax-layer signatures '${signature}' across project. Return [{file,line,context,risk_level,layer:'syntax',confidence}].","generalization","","2","pending","","",""
+"gen-semantic","Semantic Scan","Check related modules for anti-pattern: ${description}. Return [{file,line,context,risk_level,layer:'semantic',confidence}].","generalization","","2","pending","","",""
+"gen-structural","Structural Match","Find structurally similar files to ${buggy_files}, check for anti-pattern. Return [{file,line,description,risk,layer:'structural',confidence}].","generalization","","2","pending","","",""
+"gen-historical","Historical Grep","Run git log -S '${signature}' --oneline. Return [{sha,file,date,type:'introduced|fixed',context}].","generalization","","2","pending","","",""
+```
+
+```javascript
+spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
+  instruction: GENERALIZATION_INSTRUCTION + TERMINATION_CONTRACT,
+  max_concurrency:4, max_runtime_seconds:300,
+  output_csv_path:"wave-2-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })
+```
+
+**Step 3 — Cross-layer dedup**: same file:line multi-layer → boost confidence | single-layer → `needs_review` | historical fixed → `regression_risk`
+
+**Step 4 — Iterative deepening**: module ≥3 hits → targeted deep scan (max 1 round).
+
+**Step 5 — Quality Gate** (self-iteration).
+
+**Step 6:** Write `session.json.generalization_stats`: `{patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}`. Update §7. Mark G4 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): GENERALIZE — 泛化扫描完成"`
 

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

@@ -109,6 +109,38 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，
 | 可靠性 pattern | 故障模式 + 处理策略 + 验证手段 | `/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 (dependency-audit, complexity-scan) | 2 agents |
+| 2 | Audit (performance, security, architecture, reliability, observability, maintainability) | 6 agents |
+| 3 | Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) | 4 agents |
+</csv_schema>
+
 Self-iteration 适用阶段: S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE
 
 <state_machine>
@@ -181,19 +213,34 @@ S_RECORD   → END            DO A_RECORD
 Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
 
 ### A_SURVEY
-Current state survey — understand what exists before proposing changes.
+**spawn_agents_on_csv (Wave 1):**
+
+Write `tasks.csv` with Wave 1 rows:
+```csv
+"survey-deps","Dependency Audit","Analyze dependencies for {target_files}: package versions, known CVEs, unused deps, circular imports, dep depth. Return [{dep,version,issue_type,severity,detail}].","survey","","","1","pending","","",""
+"survey-complexity","Complexity Scan","Measure complexity for {target_files}: cyclomatic complexity, function length, nesting depth, file size, export count. Return [{file,metric,value,threshold,status}].","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 })`
 
-1. Dependency audit (package.json/lock), complexity scan (size/nesting), test coverage map, error handling scan (empty catch, unhandled promise)
-2. **CLI-assisted** (optional): `maestro delegate` with `--role analyze --mode analysis` for dependency health, complexity hotspots, coverage gaps, error patterns. Execute `run_in_background: true`.
-3. Append evidence.ndjson (phase: "survey"). Update `understanding.md` §2. Mark G1 done.
+Merge → evidence.ndjson (phase: "survey"). Extract `baseline_metrics` from survey results. Update `understanding.md` §2. Mark G1 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): SURVEY — 现状调查"`
 
 ### A_AUDIT
-Spawn 6 parallel agents via `spawn_agents_on_csv` (one per dimension from Dimensions list above, or `--dimensions` subset).
-Each returns: `[{title, severity, dimension, file, line, description, suggestion, measurement}]`
-
-Merge → evidence.ndjson (phase: "audit"). Write `session.json.audit_result`.
+**spawn_agents_on_csv (Wave 2)** — 6 agents (one per dimension, or `--dimensions` subset):
+
+Append Wave 2 rows to `tasks.csv`:
+```csv
+"audit-perf","Performance","Hot paths, N+1 queries, memory allocation, cache strategy, bundle analysis, lazy loading for {target_files}","audit","performance","","2","pending","","",""
+"audit-security","Security","OWASP Top 10: injection, broken auth, data exposure, XXE, access control, misconfig, XSS, deserialization, deps, logging for {target_files}","audit","security","","2","pending","","",""
+"audit-arch","Architecture","Layer boundaries, circular deps, coupling metrics, interface contracts, SRP compliance, dependency direction for {target_files}","audit","architecture","","2","pending","","",""
+"audit-reliability","Reliability","Error handling completeness, retry logic, timeout config, circuit breakers, graceful degradation, resource cleanup for {target_files}","audit","reliability","","2","pending","","",""
+"audit-observability","Observability","Logging coverage, structured logs, metrics emission, trace propagation, error reporting, health endpoints for {target_files}","audit","observability","","2","pending","","",""
+"audit-maintain","Maintainability","Dead code, complex conditionals, test coverage gaps, magic numbers, naming clarity, doc debt for {target_files}","audit","maintainability","","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 })`
+
+Merge → evidence.ndjson (phase: "audit"). Write `session.json.audit_result` with dimensions audited, finding count, severity distribution.
 Update `understanding.md` §3 (findings by dimension + severity matrix). Mark G2 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): AUDIT — 多维审查"`
@@ -230,7 +277,37 @@ Skip if `--skip-fix`. Implement improvements for diagnosed root causes.
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): VERIFY — 改进验证"`
 
 ### A_GENERALIZE
-按 base A_GENERALIZE 执行。Pattern 来源: diagnoses + fixes。Mark G5 done.
+Skip if `--skip-generalize`. Pattern 来源: diagnoses + fixes。
+
+**Step 1 — Multi-layer pattern extraction:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex patterns (direct Grep) | Missing `await`, unclosed resources, `catch {}` empty |
+| Semantic | Agent anti-pattern scan | Unvalidated input, missing error boundary, no timeout |
+| Structural | Architecture-level similarity | Same import structure, identical anti-pattern |
+| Historical | Git log for pattern introduction | When pattern was introduced, if ever fixed |
+
+Write `session.json.patterns[]`: `[{id, source_diagnosis, layer, signature, description, risk, fix_template}]`
+
+**Step 2 — 4-agent scan (spawn_agents_on_csv, Wave 3):**
+
+Append Wave 3 rows to `tasks.csv`:
+```csv
+"gen-syntax","Syntax Grep","Grep syntax-layer signatures '${signatures}' across project. Return [{file,line,context,risk_level,layer:'syntax',confidence}].","generalization","syntax","","3","pending","","",""
+"gen-semantic","Semantic Scan","Check related modules for anti-pattern: ${description}. Return [{file,line,context,risk_level,layer:'semantic',confidence}].","generalization","semantic","","3","pending","","",""
+"gen-structural","Structural Match","Find structurally similar files to ${diagnosed_files}, check for same anti-pattern. Return [{file,line,description,risk,layer:'structural',confidence}].","generalization","structural","","3","pending","","",""
+"gen-historical","Historical Grep","Run git log -S '${signature}' --oneline. Return [{sha,file,date,type:'introduced|fixed',context}].","generalization","historical","","3","pending","","",""
+```
+`spawn_agents_on_csv({ csv_path:"tasks.csv", max_concurrency:4, max_runtime_seconds:300, output_csv_path:"wave-3-results.csv", output_schema:SHARED_OUTPUT_SCHEMA })`
+
+**Step 3 — Cross-layer dedup**: same file:line multi-layer → boost confidence | single-layer → `needs_review` | historical fixed → `regression_risk`
+
+**Step 4 — Iterative deepening**: module ≥3 hits → targeted deep scan (max 1 round).
+
+**Step 5 — Quality Gate** (self-iteration).
+
+**Step 6:** Write `generalization_stats`: `{patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}`. Update §6. Mark G5 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): GENERALIZE — 泛化扫描"`
 

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

@@ -83,6 +83,39 @@ ARCHITECTURE.md | `maestro search "<target>" --json` (top 5) | `maestro load --t
 | 可复用泛化 pattern | pattern 签名 + 应用范围 | `/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>
+
 <self_iteration>
 适用阶段: S_SURVEY, S_AUDIT, S_DIVERGE, S_GENERALIZE
 </self_iteration>
@@ -147,41 +180,58 @@ S_RECORD   → END      DO A_RECORD
 Find latest session via Glob → read `session.json` → display summary → 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.
+**spawn_agents_on_csv (Wave 1):**
+
+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.ndjson (phase: "survey"). Update §2. Mark G1 done.
 📌 `git commit -m "odyssey-ui({slug}): SURVEY — 视觉调查"`
 
 ### A_AUDIT
-**spawn_agents_on_csv (Wave 2)** — 6 parallel agents (one per dimension, or `--dimensions` subset):
-
-| 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 |
+**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.
+Merge → evidence (phase: "audit"). Write `audit_result` with dimensions, finding count, severity distribution. Update §3 (severity matrix). Mark G2 done.
 📌 `git commit -m "odyssey-ui({slug}): AUDIT — 多维审查"`
 
 ### 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
-
-Each returns `[{idea, category (polish|delight), impact, effort, description, inspiration}]`
+**spawn_agents_on_csv (Wave 3)** — 2 agents:
 
-**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.
+Consolidate: audit findings + divergent ideas → prioritized improvement list (impact/effort matrix). Write `diverge_result`. Append evidence (phase: "diverge"). Update §4. Mark G3 done.
 📌 `git commit -m "odyssey-ui({slug}): DIVERGE — 发散探索"`
 
 ### A_FIX
@@ -198,9 +248,36 @@ Skip if `--skip-fix`.
 📌 `git commit -m "odyssey-ui({slug}): VERIFY — 验证"`
 
 ### 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.
+Skip if `--skip-generalize`. Pattern 来源: audit findings + diverge ideas (severity >= medium OR impact = high)。
+
+**Step 1 — Multi-layer pattern extraction:**
+
+| Layer | Method | Example |
+|-------|--------|---------|
+| Syntax | Regex patterns (direct Grep) | Missing `focus-visible`, hardcoded colors, `!important` |
+| Semantic | Agent anti-pattern scan | Missing hover state on interactive element, no empty state |
+| Structural | File/module similarity | Same component structure missing accessibility attrs |
+
+Write `session.json.patterns[]`: `[{id, source_finding, layer, signature, description, risk, fix_template}]`
+
+**Step 2 — 4-agent scan (spawn_agents_on_csv, Wave 4):**
+
+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 })`
+
+**Step 3 — Cross-layer dedup**: Multi-layer hit → boost confidence. Single → `needs_review`. Historical fix → `regression_risk`.
+
+**Step 4 — Iterative deepening**: module ≥3 hits → targeted deep scan. Max 1 round.
+
+**Step 5 — Quality Gate** (self-iteration).
+
+**Step 6:** Write `generalization_stats`. Update §6. Mark G5 done.
 📌 `git commit -m "odyssey-ui({slug}): GENERALIZE — 泛化扫描"`
 
 ### A_DISCOVER

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**:

package/.codex/skills/team-lifecycle-v4/roles/analyst/role.md

@@ -36,17 +36,13 @@ Research and codebase exploration for context gathering.
 4. If topic references file (@path or .md/.txt) -> read it
 5. CLI seed analysis:
    ```
-   exec_command({
-     cmd: `maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
+   shell_exec(`maestro delegate "PURPOSE: Analyze topic, extract structured seed info.
    TASK: * Extract problem statement * Identify target users * Determine domain
    * List constraints * Identify 3-5 exploration dimensions
    TOPIC: <topic-content>
    MODE: analysis
-   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --role analyze --mode analysis`,
-     yield_time_ms: 30000,
-     max_output_tokens: 6000
-   })
-   // ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --role analyze --mode analysis`, { timeout: 30000 })
+   // Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
    // NEVER skip — seed analysis result is required for context packaging
    ```
 6. Parse result JSON
@@ -60,16 +56,12 @@ Research and codebase exploration for context gathering.
 
 When project detected:
 ```
-exec_command({
-  cmd: `maestro delegate "PURPOSE: Explore codebase for context
+shell_exec(`maestro delegate "PURPOSE: Explore codebase for context
 TASK: * Identify tech stack * Map architecture patterns * Document conventions * List integration points
 MODE: analysis
 CONTEXT: @**/*
-EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --role explore --mode analysis`,
-  yield_time_ms: 30000,
-  max_output_tokens: 6000
-})
-// ⚠️ If session_id returned → poll write_stdin until completion (see @~/.maestro/workflows/delegate-protocol.codex.md)
+EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --role explore --mode analysis`, { timeout: 30000 })
+// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md
 // NEVER skip — codebase context is required for downstream roles
 ```