maestro-flow 0.5.38 → 0.5.40

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

@@ -1,13 +1,14 @@
 ---
 name: odyssey-improve
 description: "Long-running codebase improvement cycle — multi-dimensional audit, deep diagnosis, targeted fix, verify, generalize, and engineering knowledge persistence"
-argument-hint: '"<target>" [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c]'
+argument-hint: '"<target>" [--dimensions <list>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]'
 allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
+<base>@~/.maestro/workflows/odyssey-base.md</base>
 
 <purpose>
-Deep codebase improvement: survey (dependency + complexity baseline) -> audit (6 dimensions) ->
-diagnose (root cause analysis) -> fix -> verify -> generalize -> discover -> record.
+Deep codebase improvement: survey → 6-dimension audit → diagnose → fix → verify → generalize → discover → persist.
+Baseline-first approach with exhaustive iteration until zero remaining actionable findings.
 
 Core philosophy:
 - **Measure before improving** — baseline first, then optimize
@@ -22,149 +23,92 @@ Core philosophy:
 </purpose>
 
 <boundary>
-**范围内:** 目标代码运行质量提升 — 性能/安全/架构/可靠性/可观测性/可维护性
-**范围外:** UI → `$odyssey-ui` | 新功能 → `$odyssey-planex` | 单一 bug → `$odyssey-debug` | 代码审查 → `$odyssey-review-test-fix`
-**探索自由度:** profiling、安全扫描、架构分析、依赖审计，在约束下尽可能发现深层问题
-
+**范围内:** 目标代码的运行质量提升 — 性能/安全/架构/可靠性/可观测性/可维护性多维度审查 → 诊断 → 修复 → 泛化
+**范围外:** 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>
-**三条铁律（所有阶段适用）:**
-1. **Phase auto-commit** — 阶段完成后**自动** `git commit`，无需用户确认（session.json/evidence.ndjson 不纳入）
-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` 多 `--role`（analyze/review/explore）交叉验证关键判断
-</execution_discipline>
-
 <context>
 $ARGUMENTS — target and optional flags.
 
 **Target resolution:**
 | Input | Resolution |
 |-------|-----------|
-| Module/directory path | Analyze those source files |
-| Package name | Resolve to source directory |
-| `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` (source files only) |
-| Feature area keyword | Grep for keyword, collect relevant source files |
+| Module/dir path | Audit that module |
+| `HEAD` / `staged` | Review changes in diff |
+| Feature area keyword | Resolve to related files |
+| `--all` | Full project scan (use with caution) |
 
 **Flags:**
-| Flag | Effect |
-|------|--------|
-| `--dimensions <list>` | Comma-separated subset (default: all 6) |
-| `--skip-fix` | Audit-only — skip S_FIX and S_VERIFY |
-| `--skip-generalize` | Skip S_GENERALIZE and S_DISCOVER |
-| `--auto` | CLI delegates without confirmation |
-| `-y` | Auto-confirm at all decision points (see appendix) |
-| `-c` | Resume most recent session |
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--dimensions <list>` | Comma-separated subset of 6 dimensions | all 6 |
+| `--fix-threshold <severity>` | 修复到哪个 severity 为止（all = 全部修复）| all |
+| `--skip-fix` | Audit + diagnose 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 /loop heartbeat protocol (see base) | false |
 
 **Dimensions (6):**
-1. **performance** — hot paths, N+1 queries, memory leaks, cache misses, bundle size
-2. **security** — OWASP Top 10, injection, auth bypass, data exposure, dependency vulns
-3. **architecture** — layer violations, circular deps, coupling, interface design, SRP
-4. **reliability** — error handling, retry logic, timeout config, graceful degradation, resource cleanup
-5. **observability** — logging coverage, metrics, traces, error reporting, health checks
-6. **maintainability** — cyclomatic complexity, dead code, coverage gaps, doc debt
+1. **performance** — hot paths, N+1 queries, memory allocation, cache efficiency, bundle size, lazy loading
+2. **security** — OWASP Top 10, injection, auth bypass, data exposure, dependency vulnerabilities, secrets
+3. **architecture** — layer violations, circular dependencies, coupling metrics, interface contracts, SRP violations
+4. **reliability** — error handling gaps, retry logic, timeout handling, graceful degradation, resource cleanup
+5. **observability** — logging coverage, metric gaps, trace propagation, error reporting, health checks
+6. **maintainability** — code complexity (cyclomatic), dead code, test coverage gaps, documentation debt
 
 **Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-improve-odyssey-{slug}/`
 
-**Output — 3 files:**
-```
-SESSION_DIR/
-  ├── session.json       # state + baseline + audit_result + diagnoses + patterns + phase_goals
-  ├── evidence.ndjson    # ALL evidence (phase: survey|audit|diagnose|fix|discovery|decision|self-iteration)
-  └── understanding.md   # 9-section evolving narrative (§1-§9, one per major phase)
-```
-
-**session.json schema:**
-```json
-{
-  "session_id": "improve-odyssey-{YYYYMMDD-HHmmss}",
-  "target": "", "dimensions": [],
-  "flags": { "skip_fix": false, "skip_generalize": false, "auto": false, "auto_confirm": false },
-  "current_state": "S_INTAKE",
-  "baseline_metrics": {},
-  "audit_result": { "dimensions_audited": [], "finding_count": 0, "severity_distribution": {} },
-  "diagnoses": [],
-  "patterns": [],
-  "generalization_stats": null,
-  "phase_goals": [], "phase_goals_all_done": false,
-  "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 5,
-  "created_at": "", "updated_at": ""
-}
-```
+**Output:** `session.json` (state + audit + diagnoses + patterns + goals) | `evidence.ndjson` (append-only) | `understanding.md` (9-section narrative)
 
-**evidence.ndjson:** `{"ts":"","phase":"survey|audit|diagnose|fix|discovery|decision|self-iteration","type":"","dimension":"","title":"","severity":"","file":"","line":0,"description":"","suggestion":"","metrics":{}}`
+**session.json unique fields:** `target`, `dimensions`, `baseline_metrics`, `audit_result`, `diagnoses`, `confirmation`, `generalization_stats` (`progress_metrics`, `directions_tried` from base)
 
-**phase_goals[] — auto-derived from flags:**
+**evidence.ndjson phase-specific fields:**
+- `survey`: `category` (dependency|complexity|coverage|error_pattern), `detail`
+- `audit`: `dimension`, `severity`, `measurement`
+- `diagnosis`: `finding_ref`, `hypothesis`, `result` (confirmed|disproved|inconclusive), `root_cause`
+- `fix`: `finding_ref`, `change_summary`, `risk`
+- `discovery`: `file`, `line`, `classification` (safe|risk|issue), `action` (fix|issue|decision|skip)
+- `decision`: `question`, `options`, `context`, `status` (pending|resolved|deferred), `resolution`
+- `self-iteration`: `stage`, `round`, `assessment`, `expansion`
 
+**phase_goals[]:**
 | ID | Goal | Phase | skip_when |
 |----|------|-------|-----------|
 | G1 | Survey completed | S_SURVEY | — |
 | G2 | Audit completed | S_AUDIT | — |
 | G3 | Diagnosis completed | S_DIAGNOSE | — |
-| G4 | Fix applied and verified | S_VERIFY | skip_fix |
+| G4 | Zero remaining: all findings fixed and verified | `remaining_actionable == 0` within fix_threshold | S_VERIFY | skip_fix |
 | G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
 | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
 | G7 | Learnings persisted | S_RECORD | — |
 
-Lifecycle: `pending -> done | skipped | failed` (all set `completion_confirmed`)
-
-**understanding.md — 9 sections:**
-§1 Target & Baseline (S_INTAKE) | §2 Survey (S_SURVEY) | §3 Audit Findings (S_AUDIT) |
-§4 Root Cause Diagnosis (S_DIAGNOSE) | §5 Fix & Verification (S_FIX+S_VERIFY) |
-§6 Generalization (S_GENERALIZE) | §7 Discoveries (S_DISCOVER) |
-§8 Improvement Metrics (S_RECORD) | §9 Engineering Learnings (S_RECORD)
+**understanding.md — 9 sections (written by owning phase):**
+1. Target & Baseline ← S_INTAKE | 2. Current State Survey ← S_SURVEY | 3. Audit Findings ← S_AUDIT
+4. Root Cause Diagnosis ← S_DIAGNOSE | 5. Fix & Verification ← S_FIX+S_VERIFY
+6. Generalization ← S_GENERALIZE | 7. Discoveries ← S_DISCOVER
+8. Improvement Metrics ← S_RECORD (before/after) | 9. Engineering Learnings ← S_RECORD
 
-### Pre-load
+### Pre-load（可选，缺失不阻塞）
+- ARCHITECTURE.md → 模块边界 | `maestro search "<target>" --json` → 先前优化（top 5）
+- `maestro load --type spec --category coding` + `--category debug` → 编码规范 + 已知模式
+- `maestro search --category coding` → knowhow | `Glob(".workflow/scratch/*-improve-odyssey-*")` → 先前会话
 
-| Layer | Command | Purpose |
-|-------|---------|---------|
-| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` | Module boundaries |
-| Wiki search | `maestro search "<target keywords>" --json` | Prior investigations (top 5) |
-| Specs | `maestro load --type spec --category coding --keyword "<target>"` | Coding conventions |
-| Debug specs | `maestro load --type spec --category debug` | Known issues, workarounds |
-| Role knowledge | `maestro search --category arch` -> select -> `maestro load --type knowhow --id <id>` | Domain knowledge |
-| Prior sessions | `Glob(".workflow/scratch/*-improve-odyssey-*")` | Related sessions |
+### Knowledge Persistence（S_RECORD 中写入产出文件）
 
-### Knowledge Persistence (two-step model)
+S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，按以下分类结构化：
 
-Write to understanding.md §9 during execution (temporary). Completion summary suggests follow-up commands.
-
-| Category | Content | Follow-up |
-|----------|---------|-----------|
-| Recurring root cause | Pattern + trigger + fix template | `$spec-add debug "..."` |
-| Non-obvious workaround | Problem + solution + scope | `$spec-add learning "..."` |
-| Architecture violation | Violation + correct boundary + check method | `$spec-add arch "..."` |
-| Reusable pattern | Pattern signature + risk + fix template | `$spec-add coding "..."` |
-
-**Two-step:** Execute writes to output files (temporary) -> completion suggests permanent knowledge capture commands. No external skill calls during execution.
+| 分类 | 写入内容 | 后续建议命令 |
+|------|---------|-------------|
+| 性能 pattern | 瓶颈类型 + 修复方案 + 度量方法 | `/spec-add coding "..."` |
+| 安全规则 | 漏洞类别 + 修复 + 预防方法 | `/spec-add debug "..."` |
+| 架构约束 | 违反描述 + 正确边界 + 检查方法 | `/spec-add arch "..."` |
+| 可靠性 pattern | 故障模式 + 处理策略 + 验证手段 | `/spec-add coding "..."` |
 </context>
 
-<self_iteration>
-**Quality Gate** — auto-evaluate after each analytical phase. Insufficient -> re-enter (max **3 rounds**).
-
-| Dimension | Sufficient | Insufficient |
-|-----------|-----------|-------------|
-| Coverage | All known related files/modules analyzed | Missed targets discoverable via grep/glob |
-| 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 directories, deeper dependency analysis, additional delegate angles). Round 2 = shift perspective (different CLI tool, reverse trace, manual code reading). Round 3 = combine both + targeted deep-dive on remaining gaps.
-
-**Applicable stages:** S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE
-
-**Exit:** All sufficient -> advance | 3-round cap -> record gap, continue. Logged to `evidence.ndjson` + `session.json.self_iteration_log[]`.
-</self_iteration>
-
 <csv_schema>
 
 ### Shared Output Schema (all waves)
@@ -197,48 +141,78 @@ id,title,description,task_type,dimension,deps,wave,status,findings,evidence,erro
 | 3 | Generalization (syntax-grep, semantic-scan, structural-match, historical-grep) | 4 agents |
 </csv_schema>
 
-<invariants>
-1. **Measure before improve** — baseline metrics MUST precede any fix
-2. **Root cause over symptom** — NO FIX without diagnosis evidence
-3. **Evidence append-only** — evidence.ndjson is never overwritten
-4. **Session is source of truth** — session.json holds all state
-5. **Phase goal tracking** — each stage MUST mark its goal on completion
-6. **`-y` defers, never drops** — auto-confirm records `deferred`, never silently skips
-7. **CLI delegate is background** — all `maestro delegate` calls use run_in_background
-8. **Goal is outcome-oriented** — odyssey outputs prompt then continues
-9. **Verify improvement** — post-fix metrics MUST be compared with baseline
-10. **Decision journal integrity** — all human-judgment items recorded phase=decision
-11. **Resumable state** — current_state saved at every transition
-12. **Invariant violation = BLOCK** — violating any invariant blocks the operation
-</invariants>
-
-<execution>
-
-**States:** S_INTAKE -> S_SURVEY -> S_AUDIT -> S_DIAGNOSE -> S_FIX -> S_VERIFY -> S_GENERALIZE -> S_DISCOVER -> S_RECORD
-- S_FIX/S_VERIFY skip when `--skip-fix`
-- S_GENERALIZE/S_DISCOVER skip when `--skip-generalize`
-
-**Cross-phase loops:**
-- S_DIAGNOSE -> S_DIAGNOSE (hypothesis retry, max 3)
-- S_VERIFY -> S_FIX (rework on failed verification)
-- S_DISCOVER -> S_DIAGNOSE (new critical issue found, cross_phase_loops++)
-- S_DISCOVER -> S_FIX (same-pattern fix with template)
-- 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_INTAKE
-1. Parse target + flags -> resolve file list
+Self-iteration 适用阶段: S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE
+
+<state_machine>
+
+<states>
+S_INTAKE     — Parse target, load context, establish baseline metrics       PERSIST: session.json + understanding.md §1
+S_SURVEY     — Current state: dependency audit, complexity scan, coverage   PERSIST: evidence.ndjson (survey) + understanding.md §2
+S_AUDIT      — 6-dimension parallel deep audit                             PERSIST: evidence.ndjson (audit) + understanding.md §3
+S_DIAGNOSE   — Root cause analysis for critical/high findings              PERSIST: evidence.ndjson (diagnosis|decision) + understanding.md §4
+S_FIX        — Implement improvements (skip if --skip-fix)                 PERSIST: code changes + evidence.ndjson (fix)
+S_VERIFY     — Tests + measurement comparison (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     — Persist metrics + learnings + final report                  PERSIST: understanding.md §8-9 + spec entries
+</states>
+
+<transitions>
+S_INTAKE:
+  → S_INTAKE      WHEN -c + session found        DO A_RESUME
+  → S_SURVEY      WHEN target resolved            DO A_INTAKE
+  → S_INTAKE      WHEN no target                  DO request_user_input
+
+S_SURVEY       → S_AUDIT        DO A_SURVEY
+
+S_AUDIT:
+  → S_DIAGNOSE     WHEN critical/high findings exist       DO A_AUDIT
+  → S_GENERALIZE   WHEN no critical/high AND !skip_gen     DO A_AUDIT
+  → S_RECORD       WHEN no findings OR skip_gen            DO A_AUDIT
+
+S_DIAGNOSE:
+  → S_FIX          WHEN root causes identified AND !skip_fix           DO A_DIAGNOSE
+  → S_GENERALIZE   WHEN root causes identified AND skip_fix AND !skip_gen  DO A_DIAGNOSE
+  → S_RECORD       WHEN root causes identified AND skip_fix AND skip_gen   DO A_DIAGNOSE
+  → S_DIAGNOSE     WHEN hypotheses failed AND retries < 3             DO A_ESCALATE_DIAGNOSIS
+  → S_RECORD       WHEN hypotheses failed AND retries >= 3            DO mark INCONCLUSIVE
+
+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_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>
+
+<actions>
+
+### A_INTAKE
+1. Parse arguments: target description, flags, `--dimensions` subset
 2. Generate slug, create `SESSION_DIR`
-3. Search prior knowledge: `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + spec load (coding, debug)
-4. Derive `phase_goals[]` from flags (apply `skip_when`)
-5. Write `session.json` + `understanding.md` §1
-6. Display Goal Prompt (appendix), continue without blocking
+3. Search: `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + spec load coding/debug
+4. **Baseline capture**: Record current metrics (test pass rate, bundle size, dependency count, complexity hotspots) to `session.json.baseline_metrics`
+5. Derive `phase_goals[]` from flags (apply `skip_when`)
+6. Write `session.json` + `understanding.md` §1 (Target & Baseline)
+7. Emit Goal Prompt (see Appendix)
 
-**Resume (`-c`):** Glob latest session -> read `session.json` -> restore `current_state` -> jump.
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): INTAKE — 目标解析与基线采集"`
 
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_INTAKE — 目标解析"`
+### A_RESUME
+Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
 
-### S_SURVEY
+### A_SURVEY
 **spawn_agents_on_csv (Wave 1):**
 
 Write `tasks.csv` with Wave 1 rows:
@@ -248,12 +222,12 @@ Write `tasks.csv` with Wave 1 rows:
 ```
 `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"). Extract `baseline_metrics` from survey results. Update §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}): S_SURVEY — 调查"`
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): SURVEY — 现状调查"`
 
-### S_AUDIT
-**spawn_agents_on_csv (Wave 2)** — 6 agents (one per dimension):
+### A_AUDIT
+**spawn_agents_on_csv (Wave 2)** — 6 agents (one per dimension, or `--dimensions` subset):
 
 Append Wave 2 rows to `tasks.csv`:
 ```csv
@@ -266,70 +240,44 @@ Append Wave 2 rows to `tasks.csv`:
 ```
 `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 `audit_result` with dimensions audited, finding count, severity distribution. Update §3. Mark G2 done.
-
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_AUDIT — 审查"`
-
-### S_DIAGNOSE
-Root cause analysis for top audit findings (severity >= high).
-
-1. **Rank findings** from audit, group by root cause pattern
-2. **CLI deep analysis** for top finding clusters:
-```bash
-maestro delegate "PURPOSE: Root cause analysis for codebase quality issues in {target}
-TASK: Trace origin of each finding | Identify shared root causes | Map dependency chains | Assess blast radius
-MODE: analysis
-CONTEXT: @{target_files} | Audit findings: {top_findings_json}
-EXPECTED: JSON [{finding_ids, root_cause, origin_file, origin_line, blast_radius, fix_approach, confidence}]
-CONSTRAINTS: Trace to origin, not just symptoms | Group related findings
-" --role analyze --mode analysis
-```
-Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
-
-3. **Hypothesis testing**: for each root cause — design verification -> execute -> evidence (phase: "diagnose")
-4. **Decision journal**: ambiguity -> evidence (phase: "decision"); Normal: request_user_input | `-y`: defer
-5. **Confirmed diagnoses** -> `session.json.diagnoses[]`: `[{id, finding_ids, root_cause, evidence_refs, confidence, fix_approach}]`
+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.
 
-**Escalation (3-strike):** Hypothesis fails -> retry with broader scope via `maestro delegate --role explore`. After 3 retries: Normal -> request_user_input | `-y` -> mark INCONCLUSIVE, proceed.
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): AUDIT — 多维审查"`
 
-Update §4. Mark G3 done.
+### A_DIAGNOSE
+Root cause analysis for critical/high findings — don't fix symptoms.
 
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_DIAGNOSE — 诊断"`
+1. Group by dimension, prioritize by severity. For each: hypothesis → trace code path + git history → evidence.ndjson (phase: "diagnosis")
+2. **Decision journal**: ambiguity → evidence (phase: "decision"); Normal: request_user_input | `-y`: defer
+3. **CLI-assisted** for complex findings: `maestro delegate --role analyze --mode analysis` to trace code path, check systemic pattern, identify fix approach. Execute `run_in_background: true`.
+4. Write `session.json.diagnoses[]`. Update `understanding.md` §4. Mark G3 done.
 
-### S_FIX
-Skip if `--skip-fix`.
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): DIAGNOSE — 根因诊断"`
 
-1. Present diagnoses + proposed fixes, prioritized by blast radius. Normal: `request_user_input` to confirm. `-y`: auto proceed.
-2. Implement fixes in priority order (highest blast radius first)
-3. Record each fix in evidence (phase: "fix" + "decision")
-4. Update §5
+### A_ESCALATE_DIAGNOSIS
+Increment retries. If < 3: broaden scope via `maestro delegate --role analyze`, form new hypotheses, return to S_DIAGNOSE. If >= 3: Normal → request_user_input (broaden/new/INCONCLUSIVE) | `-y` → auto INCONCLUSIVE, proceed to S_RECORD.
 
-📌 **Auto-commit**: `git add -A && git commit -m "odyssey-improve({slug}): S_FIX — 修复"`
+### A_FIX
+Skip if `--skip-fix`. Implement improvements for diagnosed root causes.
 
-### S_VERIFY
-Skip if `--skip-fix`.
+1. **穷尽修复**: Fix ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify modified area — new findings append to current tier.
+2. For each fix: implement → record evidence.ndjson (phase: "fix")
+3. **Normal**: request_user_input per-fix confirmation. **`-y`**: auto-proceed, record `deferred`.
 
-1. **Tests**: auto-detect framework, run covering tests on modified files
-2. **CLI fix review**:
-```bash
-maestro delegate "PURPOSE: Verify improvement fixes for: {target}
-TASK: Check correctness | Assess regression risk | Verify no new issues introduced | Compare metrics
-MODE: analysis
-CONTEXT: @{modified_files} | Diagnoses: {summary} | Diff: {git_diff} | Baseline: {baseline_metrics}
-EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk, metrics_comparison}
-CONSTRAINTS: Focus on correctness and measurable improvement
-" --role review --mode analysis
-```
-Execute with `run_in_background: true`, then wait for callback (do NOT halt the Odyssey flow).
+📌 **Auto-commit**: `git add -A && git commit -m "odyssey-improve({slug}): FIX — 改进实现"`
 
-3. **Metrics comparison**: measure post-fix metrics, compare with `baseline_metrics`
-4. `needs_rework` -> S_FIX (loop). `confirmed` -> mark G4 done, advance
-5. Update §5 with before/after metrics
+### A_VERIFY
+1. Run tests covering modified areas
+2. Re-capture metrics, compare with `session.json.baseline_metrics`
+3. **CLI-assisted**: `maestro delegate --role review --mode analysis` to check fix correctness, test regressions, measure impact vs baseline. Execute `run_in_background: true`.
+4. `needs_rework` → S_FIX. `verified` → mark G4 done, advance.
+5. Write `session.json.confirmation`. Update `understanding.md` §5 (before/after metrics table).
 
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_VERIFY — 验证"`
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): VERIFY — 改进验证"`
 
-### S_GENERALIZE
-Skip if `--skip-generalize`. Extract patterns from confirmed diagnoses, scan for siblings.
+### A_GENERALIZE
+Skip if `--skip-generalize`. Pattern 来源: diagnoses + fixes。
 
 **Step 1 — Multi-layer pattern extraction:**
 
@@ -353,129 +301,89 @@ Append Wave 3 rows to `tasks.csv`:
 ```
 `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 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 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}): S_GENERALIZE — 泛化"`
-
-### S_DISCOVER
-Skip if no generalization hits.
-
-1. **Triage** each hit: read +-10 lines -> classify `safe` / `risk` / `bug` / `issue`
-2. **Route**:
-   - `bug`/`issue` + directly fixable → **fix immediately** → back to S_FIX
-   - `bug`/`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
-   See appendix for `-y` behavior. Append evidence (phase: "discovery" + "decision")
-3. **Cross-phase loop**:
-   - Discovery finds new critical issue → S_DIAGNOSE (cross_phase_loops++)
-   - Same-pattern with fix template → S_FIX (!skip_fix)
-   - 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)
-4. Update §7. Mark G6 done.
-
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_DISCOVER — 发现"`
-
-### S_RECORD
-1. Finalize §8: before/after metrics comparison table
-2. Write §9: structured by Knowledge Persistence table (temporary)
-3. Mark G7 done. Pending decisions: **Normal** -> `request_user_input`. **`-y`** -> skip, show deferred count
-4. **Goal audit**: all confirmed -> `phase_goals_all_done = true`. Any false: **Normal** -> `request_user_input` (回退/跳过/接受). **`-y`** -> auto accept
-5. **Completion**: `current_state = "COMPLETED"`, emit summary:
-```
---- IMPROVE ODYSSEY COMPLETE ---
-Target:      {target}
-Dimensions:  {audited_list}
-Baseline:    {baseline_summary}
-Audit:       {C}C {H}H {M}M {L}L across {dim_count} dimensions
-Diagnoses:   {N} root causes ({confirmed} confirmed, {inconclusive} inconclusive)
-Fix:         {F} applied, {S} skipped | Before: {baseline} -> After: {post_fix}
-Patterns:    {N} extracted ({by_layer} distribution)
-Scan:        {total} hits ({cross_layer} cross-layer confirmed)
-Issues:      {N} created
-Decisions:   {resolved}/{pending}/{deferred}
-Self-iter:   {R} quality gate rounds across {P} stages
-Goals:       {done}/{total} ({skipped} skipped)
----
-```
-**Next steps:** `$manage-issue list --source improve-odyssey`, `$learn-decompose <module>`,
-`$quality-review`, `$learn-second-opinion <understanding.md>`, `$learn-investigate "<question>"`
-
-📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): S_RECORD — 总结"`
-</execution>
-
-<appendix>
-
-### Goal Prompt Template
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): GENERALIZE — 泛化扫描"`
 
-**Time guard: display ONCE after S_INTAKE completes (session created, before survey). NEVER redisplay at S_RECORD completion.**
+### A_DISCOVER
+按 base A_DISCOVER 执行。Mark G6 done.
 
-```
-Improve Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): DISCOVER — 发现分类"`
 
-/goal 穷尽迭代：直到所有 findings 均已处理（fix/issue/decision）
-且 phase_goals_all_done=true 才停。修复按 severity 逐轮迭代，每轮修复后 re-verify。
-Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比。
-不允许"只报告不处理"。遇到 phase=decision 的 pending 必须 request_user_input。
-```
+### A_RECORD
+1. **understanding.md §8**: Improvement metrics — before/after comparison table from baseline_metrics vs current
+2. **understanding.md §9**: Engineering learnings — 按 Knowledge Persistence 表分类记录（临时），completion summary 列出建议的 `/spec-add` 命令
+3. Mark G7 done. Pending decisions: **Normal** → request_user_input. **`-y`** → skip, show deferred count.
+4. 其余按 base A_RECORD 执行。
+5. `current_state = "COMPLETED"`. Emit completion summary: Target, Dimensions, Findings (C/H/M/L), Diagnosed count, Fix count + verified, Metrics (improved/regressed), Patterns (count + layer distribution), Scan hits (cross-layer), Issues created, Decisions (resolved/pending/deferred), Learnings count, Self-iter rounds, Cross-loops used, Goals (done/total/skipped).
 
-Odyssey outputs prompt then continues without blocking. `/goal` entered by user at any time.
-
-### `-y` Auto-Confirm Behavior
+📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): RECORD — 指标总结与知识沉淀"`
 
-| Decision Point | Normal | `-y` mode |
-|----------------|--------|-----------|
-| S_DIAGNOSE ambiguity | request_user_input blocks | record `deferred`, best-effort continue |
-| S_DIAGNOSE 3-strike | request_user_input 3-way | auto INCONCLUSIVE |
-| S_FIX fix direction | request_user_input confirm | auto proceed by priority |
-| S_DISCOVER bug triage | request_user_input per hit | auto create issue |
-| S_DISCOVER ambiguous | request_user_input batch | all `deferred` |
-| S_RECORD pending decisions | request_user_input per-item | skip, show deferred count |
+</actions>
 
-`deferred` items shown as "待决策" in summary; recoverable via `-c`.
+<appendix>
 
-### Phase Goal Lifecycle
+### Goal Prompt Template
+**⚠️ 仅在 A_INTAKE 完成后显示一次，A_RECORD 完成时不重复。**
 
-`pending -> done (confirmed=true)` normal | `pending -> skipped (confirmed=true)` flags/manual | `pending -> failed (confirmed=false)` incomplete
+列出所有非 skipped 的 phase_goals，附加收敛规则：
+- 穷尽迭代至所有 findings 已处理（fix/issue/decision）且 `phase_goals_all_done=true`
+- 修复按 severity 逐轮迭代，每轮 re-verify
+- Baseline 修复前采集，修复后对比确认改进
+- pending decision 必须 request_user_input，不允许"只报告不处理"
 
-`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
+### `-y` Auto-Confirm Behavior
+| Decision Point | Normal | `-y` |
+|---------------|--------|------|
+| A_FIX improvement confirmation | request_user_input | auto-proceed, `deferred` |
+| A_DIAGNOSE ambiguity | request_user_input | best-effort, `deferred` |
+| A_ESCALATE 3-strike | request_user_input 3-way | auto INCONCLUSIVE |
+| 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` items shown as "待决策" in completion summary; recoverable via `-c`.
 
 </appendix>
 
+</state_machine>
+
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | No target and no session to resume | Provide target or use -c |
-| E002 | error | Target not found or no source files | Check path, ensure source files exist |
-| E003 | error | Resume but no session found | Start new session |
-| W001 | warning | No relevant git history | Proceed with limited context |
-| W002 | warning | Audit dimension agent failed | Partial coverage, note gap |
-| W003 | warning | Generalization scan 0 hits | Skip discovery |
-| W004 | warning | Delegate parse failed | Use raw output |
+| E001 | error | No target specified | Provide target or use -c |
+| E002 | error | Target path not found | Check path |
+| W001 | warning | No dependency manifest found | Proceed without dep audit |
+| W002 | warning | Some dimension agents failed | Partial audit coverage |
 </error_codes>
 
 <success_criteria>
-- [ ] Target resolved to source files, session created with 3 output files
-- [ ] Prior knowledge searched (maestro search + sessions + architecture + specs)
-- [ ] Survey via spawn Wave 1, baseline_metrics extracted, evidence phase=survey
-- [ ] All 6 dimensions audited via spawn Wave 2, severity matrix produced
-- [ ] Root causes diagnosed with evidence refs, hypotheses tested phase=diagnose
-- [ ] Fixes applied priority-order and verified with metric comparison (unless --skip-fix)
-- [ ] `--skip-fix`: no source code modifications
-- [ ] Generalization via spawn Wave 3 + cross-layer dedup (unless --skip-generalize)
-- [ ] Discoveries classified and routed (fix/issue/decision/skip)
-- [ ] understanding.md tracks all 9 sections progressively
-- [ ] phase_goals G1-G7 derived from flags, each phase marks its goal
-- [ ] Goal Prompt displayed once; `-y` auto-resolves/defers
-- [ ] State saved at each transition (resumable via -c)
-- [ ] Quality Gate self-iteration logged in self_iteration_log
-- [ ] Before/after metrics comparison in completion summary
-- [ ] Completion summary with all stats
-- [ ] **Every unfixed finding has individual classification and reason** — blanket "pre-existing" labels are forbidden
+- [ ] Target resolved, baseline metrics captured
+- [ ] Survey + 6-dimension audit with structured findings and severity matrix
+- [ ] Root causes diagnosed for critical/high findings
+- [ ] Improvements implemented and verified with before/after metrics (unless --skip-fix)
+- [ ] Multi-layer generalization + cross-phase loops (unless --skip-generalize)
+- [ ] Every unfixed finding has individual classification and reason
+- [ ] understanding.md §8 (metrics) and §9 (learnings) completed
+- [ ] phase_goals G1-G7 tracked and audited
+- [ ] Session resumable via -c
 </success_criteria>
+
+<next_step_routing>
+| Condition | Next step |
+|-----------|-----------|
+| Security findings need deep investigation | `$odyssey-debug "<finding>"` |
+| UI-related findings | `$odyssey-ui "<component>"` |
+| Issues created from discoveries | `/manage-issue list --source improve-odyssey` |
+| Architecture pattern to document | `/spec-add arch "..."` |
+| Performance pattern to persist | `/spec-add coding "..."` |
+| Want formal review of changes | `$odyssey-review-test-fix <changed-files>` |
+| Decisions still pending | Filter evidence.ndjson phase=decision status=pending |
+</next_step_routing>