maestro-flow 0.5.31 → 0.5.33

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

@@ -23,6 +23,7 @@ Treats every bug as a learning signal with exhaustive iteration until root cause
 **范围内:** 单一 bug/issue 的完整闭环 — 考古 → 探索 → 诊断 → 修复 → 确认 → 泛化同类 → 沉淀
 **范围外:** 新功能开发 → `/odyssey-planex` | 代码质量审查 → `/odyssey-review-test-fix` | UI 视觉优化 → `/odyssey-ui` | 架构重设计 → `/maestro-plan`
 **探索自由度:** 边界内自由探索 — 可追踪任意调用链、分析任意历史、测试任意假设。泛化阶段可扫描全项目寻找同类问题。
+**Zero-residual principle:** Every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing issue" is not a valid skip reason — if discovered within scope, it must be addressed.
 **模板支持:** `--template <name>` 从预定义调查策略启动，跳过假设生成直接进入针对性诊断：
 
 | Template | 调查策略 | 适用场景 |
@@ -42,10 +43,15 @@ Treats every bug as a learning signal with exhaustive iteration until root cause
    - session.json / evidence.ndjson 为运行时状态，不纳入 commit
    - 确保每个阶段的进展可回溯、可恢复
 
-2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
-   - 有把握 → 直接修改代码，commit
-   - 需要决策 → 记录 `evidence.ndjson {"phase":"decision","status":"pending"}` 不改代码
-   - 禁止猜测性修改，宁可多记录一条 decision 也不冒险改错
+2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
+   - Confident → edit code directly, commit
+   - Needs decision → record `evidence.ndjson {"phase":"decision","status":"pending"}`, don't touch code
+   - No speculative changes
+   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+     - Cross-module architectural tradeoffs requiring human direction
+     - Ambiguous business semantics where the fix could alter intended behavior
+     - Requires new dependency or breaking API change
+   - ❌ "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 工具交叉验证
    - 关键判断用不同 `--role`（analyze / review / explore）获取多视角
@@ -78,7 +84,7 @@ SESSION_DIR/
   "root_cause": null, "patterns": [], "confirmation": null,
   "phase_goals": [], "phase_goals_all_done": false, "self_iteration_log": [],
   "generalization_stats": null,
-  "cross_phase_loops": 0, "max_loops": 3,
+  "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
 ```
@@ -157,11 +163,12 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，
 | Depth | ≥80% 发现有 file:line 级证据 | 多数仅泛泛描述 |
 | Actionability | 每条结论有具体后续动作 | 仅"建议关注"类无操作性结论 |
 
-**规则:** 阶段完成 → 评估 3 维度 → 任一 insufficient → 重入（每阶段最多 2 轮）。
-- Round 1: 扩范围 — 增加目录、git log depth ×2、增加 delegate 角度
-- Round 2: 换视角 — 不同 CLI tool、反向追踪、手动 code reading
+**Rules:** phase complete → evaluate 3 dimensions → any insufficient → re-enter (max **3 rounds** per stage).
+- Round 1: widen scope — more dirs, git log depth ×2, extra delegate angles
+- Round 2: shift perspective — different CLI tool, reverse trace, manual code reading
+- Round 3: combine both + targeted deep-dive on remaining gaps
 
-**退出:** 全 sufficient → 推进 | 2 轮上限 → 记录 gap 继续。记录至 `evidence.ndjson` + `session.json.self_iteration_log[]`.
+**Exit:** all sufficient → advance | 3-round cap → log remaining gaps and continue. Record to `evidence.ndjson` + `session.json.self_iteration_log[]`.
 </self_iteration>
 
 <state_machine>
@@ -200,9 +207,10 @@ S_CONFIRM → S_FIX           : needs_rework
 S_GENERALIZE → S_DISCOVER   : similar code found
 S_GENERALIZE → S_RECORD     : no similar code
 
-S_DISCOVER → S_DIAGNOSE     : discovery finds new bug worth investigating, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_FIX          : discovery finds same-pattern bug, fix template applies, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_RECORD       : triage complete OR loops >= max_loops (剩余项 → issue/decision)
+S_DISCOVER → S_DIAGNOSE     : discovery finds new bug worth investigating → cross_phase_loops++
+S_DISCOVER → S_FIX          : discovery finds same-pattern bug, fix template applies, !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_RECORD   → END            : A_RECORD complete
 </transitions>
@@ -242,7 +250,7 @@ EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanatio
 CONSTRAINTS: Focus on behavioral changes, not formatting
 " --role analyze --mode analysis
 ```
-Run_in_background, STOP, wait for callback. Append results to evidence.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow). Append results to evidence.
 
 Update `understanding.md` §2.
 
@@ -261,7 +269,7 @@ CONSTRAINTS: Max 20 entries/category | Symptom-related code paths
 Symptoms: {issue}  Archaeology hints: {suspicious_commits}
 " --role explore --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 Parse → write `explore.json` + append `evidence.ndjson` (phase: "explore"). Update §3. Mark G2 done.
 
@@ -297,7 +305,7 @@ EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regress
 CONSTRAINTS: Focus on correctness, not style
 " --role review --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 3. Write `session.json.confirmation`: `{test_result, cli_review, overall: "confirmed|needs_rework", timestamp}`
 4. Update §6. `needs_rework` → S_FIX. `confirmed` → mark G3 done, advance.
@@ -340,7 +348,12 @@ Write §7 + `session.json.generalization_stats`: `{patterns_extracted, total_hit
 
 ### A_DISCOVER
 1. **Triage** each hit: read ±10 lines context → classify `safe`/`risk`/`bug`
-2. **Route**: see Appendix `-y` behavior table. Append evidence (phase: "discovery" + "decision")
+2. **Route**:
+   - `bug` + directly fixable → **fix immediately** (not just log an issue) → back to S_FIX
+   - `bug` + requires cross-module/architectural decision → create issue (with fix suggestion + impact analysis)
+   - `risk` → evaluate if guard/validation can mitigate directly; if yes, fix it
+   - `safe` → mark skip
+   See Appendix `-y` behavior table. Append evidence (phase: "discovery" + "decision")
 3. Update §8. Mark G5 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): DISCOVER — 发现分类完成"`
@@ -438,6 +451,7 @@ Odyssey 输出提示词后继续执行不阻塞。`/goal` 由用户任意时刻
 - [ ] Multi-layer patterns (syntax/semantic/structural) extracted (unless --skip-generalize)
 - [ ] 4-agent scan + cross-layer dedup + iterative deepening for ≥3 hits/module
 - [ ] Discoveries classified and routed (fix/issue/decision/skip)
+- [ ] **Every unfixed finding has individual classification and reason** — blanket "pre-existing" labels are forbidden
 - [ ] Decision journal: all human-judgment items in evidence.ndjson phase=decision
 - [ ] phase_goals derived from flags, skip_when applied, each phase marks its goal
 - [ ] Goal audit in A_RECORD — unmet goals surfaced, phase_goals_all_done set correctly

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

@@ -23,6 +23,7 @@ Baseline-first approach with exhaustive iteration until zero remaining actionabl
 **范围内:** 目标代码的运行质量提升 — 性能/安全/架构/可靠性/可观测性/可维护性多维度审查 → 诊断 → 修复 → 泛化
 **范围外:** UI 视觉优化 → `/odyssey-ui` | 新功能实现 → `/odyssey-planex` | 单一 bug 调查 → `/odyssey-debug` | 代码风格审查 → `/odyssey-review-test-fix`
 **探索自由度:** 边界内自由探索 — 可 profiling、安全扫描、架构分析、依赖审计。在约束下尽可能发现深层问题。
+**Zero-residual principle:** Every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing issue" is not a valid skip reason — if discovered within scope, it must be addressed.
 </boundary>
 
 <execution_discipline>
@@ -32,10 +33,15 @@ Baseline-first approach with exhaustive iteration until zero remaining actionabl
    - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-improve({slug}): {phase} — {摘要}"`
    - session.json / evidence.ndjson 为运行时状态，不纳入 commit
 
-2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
-   - 有把握 → 直接修改代码，commit
-   - 需要决策 → 记录 `evidence.ndjson {"phase":"decision","status":"pending"}` 不改代码
-   - 禁止猜测性修改，宁可多记录一条 decision 也不冒险改错
+2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
+   - Confident → edit code directly, commit
+   - Needs decision → record `evidence.ndjson {"phase":"decision","status":"pending"}`, don't touch code
+   - No speculative changes
+   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+     - Cross-module architectural tradeoffs requiring human direction
+     - Ambiguous business semantics where the fix could alter intended behavior
+     - Requires new dependency or breaking API change
+   - ❌ "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` 发现依赖/复杂度热点
@@ -98,7 +104,7 @@ SESSION_DIR/
   "generalization_stats": null,
   "phase_goals": [], "phase_goals_all_done": false,
   "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 3,
+  "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
 ```
@@ -159,7 +165,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，
 </context>
 
 <self_iteration>
-**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max 2 rounds).
+**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max **3 rounds**).
 
 | Dimension | Sufficient | Insufficient |
 |-----------|-----------|-------------|
@@ -167,7 +173,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，
 | Depth | ≥80% findings have file:line evidence + measurement | Most findings lack specifics |
 | Actionability | Each conclusion has concrete fix or issue action | "Consider reviewing" without action |
 
-**Expansion:** Round 1 = widen scope (more modules, deeper import chain, extra delegate angles). Round 2 = shift perspective (different CLI tool, reverse dependency trace, manual code reading).
+**Expansion:** Round 1 = widen scope (more modules, 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":""}`
 
@@ -219,9 +225,10 @@ S_GENERALIZE:
   → S_DISCOVER     WHEN hits found                DO A_GENERALIZE
   → S_RECORD       WHEN no hits                   DO A_GENERALIZE
 
-S_DISCOVER → S_DIAGNOSE     : new critical issue found, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_FIX          : same-pattern fix, !skip_fix, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_RECORD       : triage complete OR loops >= max_loops (剩余项 → issue/decision)
+S_DISCOVER → S_DIAGNOSE     : new critical issue found → cross_phase_loops++
+S_DISCOVER → S_FIX          : same-pattern fix, !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_RECORD   → END            DO A_RECORD
 </transitions>
@@ -259,7 +266,7 @@ EXPECTED: JSON {dependency_health, complexity_hotspots, coverage_gaps, error_pat
 CONSTRAINTS: Focus on runtime quality, not style
 " --role analyze --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 6. Append evidence.ndjson (phase: "survey"). Update `understanding.md` §2. Mark G1 done.
 
@@ -303,7 +310,7 @@ EXPECTED: JSON {root_cause, systemic, fix_approach, risk}
 CONSTRAINTS: Focus on root cause, not symptom
 " --role analyze --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 5. Write `session.json.diagnoses[]`. Update `understanding.md` §4. Mark G3 done.
 
@@ -336,7 +343,7 @@ EXPECTED: JSON {verdict, metrics_improved, regressions, remaining_issues}
 CONSTRAINTS: Focus on correctness and measurable improvement
 " --role review --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 4. `needs_rework` → S_FIX. `verified` → mark G4 done, advance.
 5. Write `session.json.confirmation`. Update `understanding.md` §5 (before/after metrics table).
@@ -376,8 +383,13 @@ Update `understanding.md` §6. Write `session.json.generalization_stats`. Mark G
 
 ### A_DISCOVER
 1. **Triage** each hit: read ±10 lines context → classify `safe`/`risk`/`issue`
-2. **Route**: **Normal** → ask_user. **`-y`** → auto create issue, `deferred`.
-3. **Cross-phase loops**: new critical issue → S_DIAGNOSE; same-pattern fix → S_FIX; budget exhausted → S_RECORD.
+2. **Route**:
+   - `issue` + directly fixable → **fix immediately** → back to S_FIX
+   - `issue` + requires cross-module/architectural decision → create issue (with fix suggestion + impact analysis)
+   - `risk` → evaluate if guard/validation can mitigate directly; if yes, fix it
+   - `safe` → mark skip
+   **Normal**: ask_user for routing ambiguity. **`-y`**: auto-fix what's fixable, create issue for rest.
+3. **Cross-phase loops**: new critical issue → S_DIAGNOSE; same-pattern fix → S_FIX.
 4. Append evidence (phase: "discovery" + "decision"). Update `understanding.md` §7. Mark G6 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): DISCOVER — 发现分类"`
@@ -472,6 +484,7 @@ Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比
 - [ ] Cross-phase loops used when discoveries warrant
 - [ ] 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: improvement metrics (before/after comparison)
 - [ ] understanding.md §9: engineering learnings
 - [ ] phase_goals G1-G7 tracked and audited

package/.agents/skills/odyssey-planex/SKILL.md

@@ -23,6 +23,7 @@ plan → execute → verify → fix gaps → iterate until ALL criteria pass.
 **范围内:** 单一需求的实现闭环 — 从需求解析到验收标准全部通过 + 泛化同类场景
 **范围外:** 多需求编排 → `/maestro-roadmap` | 深度 debugging → `/odyssey-debug` | 代码审查 → `/odyssey-review-test-fix` | UI 优化 → `/odyssey-ui`
 **探索自由度:** 边界内自由探索 — 可自主分解任务、选择实现策略、迭代修复。verify→fix 循环内可尝试不同方案。
+**Zero-residual principle:** Every failing criterion MUST be fixed or explicitly escalated with specific reason. "Close enough" is not passing. "Pre-existing gap" is not a valid skip reason — if within scope, address it.
 **模板支持:** `--template <name>` 从预定义需求模板启动，自动生成匹配的验收标准和任务分解：
 
 | Template | 预设 criteria 模式 | 适用场景 |
@@ -41,10 +42,15 @@ plan → execute → verify → fix gaps → iterate until ALL criteria pass.
    - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-planex({slug}): {phase} — {摘要}"`
    - session.json / evidence.ndjson 为运行时状态，不纳入 commit
 
-2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
-   - 有把握 → 直接修改代码，commit
-   - 需要决策 → 记录 `evidence.ndjson {"phase":"decision","status":"pending"}` 不改代码
-   - 禁止猜测性修改
+2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
+   - Confident → edit code directly, commit
+   - Needs decision → record `evidence.ndjson {"phase":"decision","status":"pending"}`, don't touch code
+   - No speculative changes
+   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+     - Cross-module architectural tradeoffs requiring human direction
+     - Ambiguous business semantics where the fix could alter intended behavior
+     - Requires new dependency or breaking API change
+   - ❌ "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 工具交叉验证
    - 计划阶段: `--role analyze` 获取任务分解建议
@@ -108,7 +114,7 @@ SESSION_DIR/
   "phase_goals": [],
   "phase_goals_all_done": false,
   "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 3,
+  "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
 ```
@@ -162,9 +168,9 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 | Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
 | Actionability | Each conclusion has concrete next action | Only vague "consider" recommendations |
 
-**Rules:** stage complete → evaluate 3 dims → any insufficient → re-enter (max **2 rounds** per stage). Record to evidence.ndjson `{"phase":"self-iteration","type":"quality-gate","stage":"S_XXX","round":N,"assessment":{...},"expansion":"strategy"}`.
+**Rules:** stage complete → evaluate 3 dims → any insufficient → re-enter (max **3 rounds** per stage). Record to evidence.ndjson `{"phase":"self-iteration","type":"quality-gate","stage":"S_XXX","round":N,"assessment":{...},"expansion":"strategy"}`.
 
-**Expansion:** Round 1 = broaden scope (more dirs, more delegate angles). Round 2 = shift perspective (different CLI tool, reverse-trace from expected result).
+**Expansion:** Round 1 = broaden scope (more dirs, more delegate angles). Round 2 = shift perspective (different CLI tool, reverse-trace from expected result). Round 3 = combine both + targeted deep-dive on remaining gaps.
 
 **Applies to:** S_PLAN, S_VERIFY, S_GENERALIZE
 </self_iteration>
@@ -201,8 +207,9 @@ S_FIX → S_VERIFY (loop)
 S_GENERALIZE → S_DISCOVER  WHEN hits found
 S_GENERALIZE → S_RECORD    WHEN no hits
 
-S_DISCOVER → S_EXECUTE     : discovery finds area needing same implementation, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_RECORD      : triage complete OR loops >= max_loops (剩余项 → issue)
+S_DISCOVER → S_EXECUTE     : discovery finds area needing same implementation → 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_RECORD → END
 </transitions>
@@ -232,7 +239,7 @@ S_RECORD → END
    EXPECTED: JSON [{task_id, title, description, criteria_refs, deps}]
    " --role analyze --mode analysis
    ```
-   Run_in_background, STOP, wait for callback.
+   Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 3. Write session.json.plan, append evidence (planning), update understanding.md §2. Mark G2 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-planex({slug}): PLAN — 计划制定"`
@@ -336,7 +343,7 @@ ${prior_summaries}
 " --to ${resolved_executor} --mode write --id planex-${slug}-${task_id}
 ```
 
-Run CLI delegate with `run_in_background: true`, STOP, wait for callback.
+Run CLI delegate with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 **Deviation Rule** — max 3 auto-fix attempts per task:
 1. First attempt: normal dispatch
@@ -377,7 +384,7 @@ ${modified_files.join('\n')}
 " --to ${execution_config.verification_tool} --mode analysis
 ```
 
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 On result:
 - `overall == "passed"` → proceed to S_VERIFY (criteria gate) with boosted confidence
@@ -570,6 +577,7 @@ Max iterations (default 3) prevents infinite loops. Each iteration records crite
 - [ ] Every criterion verified by its method after each iteration
 - [ ] Failing criteria trigger targeted fix (not full re-implementation)
 - [ ] Iteration count tracked, max respected
+- [ ] **Every unfixed criterion has individual classification and reason** — blanket "pre-existing" labels are forbidden
 - [ ] understanding.md updated per phase (§1-§8)
 - [ ] Multi-layer generalization + 4-agent scan (unless --skip-generalize)
 - [ ] Discoveries classified and routed (unless --skip-generalize)

package/.agents/skills/odyssey-review-test-fix/SKILL.md

@@ -22,7 +22,8 @@ fix ALL findings → confirm → generalize → discover → persist. Zero-resid
 <boundary>
 **范围内:** 目标代码的多维度深度审查 → 穷尽修复 ALL 发现（按 severity 递降）→ 泛化 pattern 到全项目
 **范围外:** 深度根因调查（根因不明时）→ `/odyssey-debug` | 需求实现 → `/odyssey-planex` | UI 视觉优化 → `/odyssey-ui`
-**探索自由度:** 边界内自由探索 — 可跨维度关联发现、追溯 git 历史、泛化扫描全项目。修复仅限 critical/high findings。
+**探索自由度:** 边界内自由探索 — 可跨维度关联发现、追溯 git 历史、泛化扫描全项目。修复 ALL findings within fix_threshold（默认 all = 穷尽所有 severity）。
+**Zero-residual principle:** Every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" is not allowed. "Pre-existing issue" is not a valid skip reason — if discovered within scope, it must be addressed.
 </boundary>
 
 <execution_discipline>
@@ -32,10 +33,15 @@ fix ALL findings → confirm → generalize → discover → persist. Zero-resid
    - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-review({slug}): {phase} — {摘要}"`
    - session.json / evidence.ndjson 为运行时状态，不纳入 commit
 
-2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
-   - 有把握 → 直接修改代码，commit
-   - 需要决策 → 记录 `evidence.ndjson {"phase":"decision","status":"pending"}` 不改代码
-   - 禁止猜测性修改
+2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
+   - Confident → edit code directly, commit
+   - Needs decision → record `evidence.ndjson {"phase":"decision","status":"pending"}`, don't touch code
+   - No speculative changes
+   - ⚠️ **Decision gate** — ONLY these qualify as decisions (not fixes):
+     - Cross-module architectural tradeoffs requiring human direction
+     - Ambiguous business semantics where the fix could alter intended behavior
+     - Requires new dependency or breaking API change
+   - ❌ "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 工具交叉验证
    - 关键判断用不同 `--role`（analyze / review / explore）获取多视角
@@ -88,7 +94,7 @@ SESSION_DIR/
   "generalization_stats": { "patterns_extracted": 0, "total_hits": 0, "true_positives": 0, "false_positives": 0, "uncertain": 0, "cross_layer_confirmed": 0, "regression_risks": 0, "by_layer": {}, "deepening_triggered": false, "self_iteration_rounds": 0 },
   "phase_goals": [], "phase_goals_all_done": false,
   "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 3,
+  "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
 ```
@@ -132,7 +138,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 </context>
 
 <self_iteration>
-**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max 2 rounds).
+**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max 3 rounds).
 
 | Dimension | Sufficient | Insufficient |
 |-----------|-----------|-------------|
@@ -140,7 +146,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 | Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
 | Actionability | Each conclusion has concrete next action | "Consider reviewing" without action |
 
-**Expansion:** Round 1 = widen scope (more dirs, deeper git log, extra delegate angles). Round 2 = shift perspective (different CLI tool, reverse trace, manual reading).
+**Expansion:** Round 1 = widen scope (more dirs, deeper git log, extra delegate angles). Round 2 = shift perspective (different CLI tool, reverse trace, manual 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":""}`
 
@@ -186,9 +192,10 @@ S_GENERALIZE:
   → S_DISCOVER      WHEN hits found                 DO A_GENERALIZE
   → S_RECORD        WHEN no hits                    DO A_GENERALIZE
 
-S_DISCOVER → S_FIX          : discovery finds fixable sibling, !skip_fix, loops < max_loops → cross_phase_loops++
+S_DISCOVER → S_FIX          : discovery finds fixable sibling, !skip_fix → cross_phase_loops++
 S_DISCOVER → S_REVIEW       : discovery opens new review target, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_RECORD       : triage complete OR loops >= max_loops (剩余项 → issue/decision)
+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_RECORD   → END            DO A_RECORD
 </transitions>
@@ -254,7 +261,10 @@ for tier in fix_tiers:
 
 **Normal**: ask_user 确认每个 tier 的 candidates。**`-y`**: auto-fix all, record `deferred`.
 
-**Remaining check**: 所有 tiers 完成后，count unfixed findings within fix_threshold → 写入 `review_result.remaining_actionable`。若 > 0 且未超 max_loops → 回到 tier 1 重试。
+**Remaining check**: 所有 tiers 完成后，count unfixed findings within fix_threshold → 写入 `review_result.remaining_actionable`。
+- If > 0 → retry from tier 1 (NOT limited by max_loops — max_loops only limits cross-phase loops, not FIX-internal retries)
+- If remaining unchanged for 2 consecutive rounds (same findings stuck) → classify each stuck finding individually: record as decision (if meets Decision gate criteria) or issue (with fix suggestion)
+- ❌ Blanket "N remaining items are pre-existing" is forbidden — each item must have individual classification and reason
 
 📌 **Auto-commit per tier**: `git add -A && git commit -m "odyssey-review({slug}): FIX-{tier} — {N}项修复"`
 
@@ -269,7 +279,7 @@ EXPECTED: JSON {verdict, findings_addressed, remaining_unfixed, regression_risk,
 CONSTRAINTS: Focus on correctness AND completeness — flag ANY remaining actionable improvement
 " --role review --mode analysis
 ```
-Run_in_background, STOP, wait.
+以 `run_in_background: true` 执行 delegate，等待回调后继续（不中断 Odyssey 流程）。
 
 **Zero-residual gate:**
 - `remaining_unfixed == 0 AND new_findings == 0` → `confirmed`, mark G3 done
@@ -311,7 +321,12 @@ Write `session.json.generalization_stats`. Mark G4 done.
 
 ### A_DISCOVER
 Classify each hit: `bug` / `risk` / `safe`.
-**Normal**: ask_user for bug routing. **`-y`**: auto create issue, `deferred`.
+- `bug` + directly fixable → **fix immediately** (not just log an issue) → back to S_FIX
+- `bug` + requires cross-module/architectural decision → create issue (with fix suggestion + impact analysis)
+- `risk` → evaluate if guard/validation can mitigate directly; if yes, fix it
+- `safe` → mark skip
+
+**Normal**: ask_user for routing ambiguity. **`-y`**: auto-fix what's fixable, create issue for rest.
 Append evidence (phase: discovery + decision). Update `understanding.md` §7. Mark G5 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-review({slug}): DISCOVER — 发现分类完成"`
@@ -396,6 +411,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 - [ ] **ALL findings within fix_threshold fixed** — remaining_actionable == 0 (unless --skip-fix)
 - [ ] Per-tier fix with re-review gate: modified area re-reviewed, new findings appended
 - [ ] Zero-residual confirmed by CLI external model
+- [ ] **Every unfixed finding has individual classification and reason** — blanket "pre-existing" labels are forbidden
 - [ ] Pattern generalized with multi-layer scan + deepening (unless --skip-generalize)
 - [ ] Quality Gate self-iteration triggered when insufficient
 - [ ] Discoveries classified and routed

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

@@ -23,6 +23,7 @@ fix → verify → generalize → discover → persist. Every pixel is a learnin
 **范围内:** 目标组件/页面的视觉体验优化 — 审查 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.
 </boundary>
 
 <execution_discipline>
@@ -32,10 +33,15 @@ fix → verify → generalize → discover → persist. Every pixel is a learnin
    - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-ui({slug}): {phase} — {摘要}"`
    - session.json / evidence.ndjson 为运行时状态，不纳入 commit
 
-2. **有把握才改** — 仅修改自己有把握的内容；不确定的记录决策等人判断
-   - 视觉确定性高（缺少 hover state、对比度不足等）→ 直接修复
-   - 设计方向不确定（色彩选择、布局重构等）→ 记录 decision 等用户判断
-   - 禁止猜测性修改，尤其是品牌/风格层面的改动
+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` 发现设计系统用法
@@ -89,7 +95,7 @@ SESSION_DIR/
   "generalization_stats": { "patterns_extracted": 0, "total_hits": 0, "cross_layer_confirmed": 0, "regression_risks": 0, "by_layer": {}, "deepening_triggered": false },
   "phase_goals": [], "phase_goals_all_done": false,
   "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 3,
+  "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
 ```
@@ -135,7 +141,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 </context>
 
 <self_iteration>
-**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max 2 rounds).
+**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max **3 rounds**).
 
 | Dimension | Sufficient | Insufficient |
 |-----------|-----------|-------------|
@@ -143,7 +149,7 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 | 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).
+**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":""}`
 
@@ -190,9 +196,10 @@ S_GENERALIZE:
   → S_DISCOVER     WHEN hits found                DO A_GENERALIZE
   → S_RECORD       WHEN no hits                   DO A_GENERALIZE
 
-S_DISCOVER → S_AUDIT        : discovery reveals new component to audit, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_FIX          : discovery finds fixable sibling, !skip_fix, loops < max_loops → cross_phase_loops++
-S_DISCOVER → S_RECORD       : triage complete OR loops >= max_loops (剩余项 → issue/decision)
+S_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_RECORD   → END            DO A_RECORD
 </transitions>
@@ -226,7 +233,7 @@ CONTEXT: @{target_files}
 EXPECTED: JSON {tokens_used, spacing_patterns, typography_scale, component_hierarchy, consistency_issues}
 " --role analyze --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+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.
 
@@ -271,7 +278,7 @@ CONTEXT: @{target_files} | Audit summary: {audit_findings_summary}
 EXPECTED: JSON [{category, idea, rationale, reference}]
 " --role analyze --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
 
 **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.
@@ -300,7 +307,7 @@ CONTEXT: @{modified_files} | Improvements: {fix_summary}
 EXPECTED: JSON {verdict, verified_improvements, remaining_issues, regression_risk}
 " --role review --mode analysis
 ```
-Run_in_background, STOP, wait for callback.
+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`.
@@ -339,7 +346,12 @@ Update `understanding.md` §6 (per-pattern summary, cross-layer matrix). Write `
 
 ### A_DISCOVER
 Classify each hit: `needs_treatment` / `low_risk` / `already_handled`.
-**Normal**: ask_user for routing. **`-y`**: auto create issue, `deferred`.
+- `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_user 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 — 发现分类"`
@@ -429,6 +441,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 - [ ] 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