maestro-flow 0.5.38 → 0.5.39

package/.claude/commands/odyssey-improve.md

@@ -1,7 +1,7 @@
 ---
 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:
   - Read
   - Write
@@ -12,6 +12,8 @@ allowed-tools:
   - Agent
   - AskUserQuestion
 ---
+<base>@~/.maestro/workflows/odyssey-base.md</base>
+
 <purpose>
 Deep codebase improvement: survey → 6-dimension audit → diagnose → fix → verify → generalize → discover → persist.
 Baseline-first approach with exhaustive iteration until zero remaining actionable findings.
@@ -24,31 +26,6 @@ Baseline-first approach with exhaustive iteration until zero remaining actionabl
 **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`，无需用户确认
-   - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-improve({slug}): {phase} — {摘要}"`
-   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
-
-2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
-   - 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` 发现依赖/复杂度热点
-   - audit/diagnose: `--role analyze` 获取多视角分析
-   - fix 前后: `--role review` 确认改进正确性
-
-4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
-</execution_discipline>
-
 <context>
 $ARGUMENTS — target and optional flags.
 
@@ -70,6 +47,7 @@ $ARGUMENTS — target and optional flags.
 | `--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 allocation, cache efficiency, bundle size, lazy loading
@@ -81,37 +59,11 @@ $ARGUMENTS — target and optional flags.
 
 **Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-improve-odyssey-{slug}/`
 
-**Output — 3 files:**
-```
-SESSION_DIR/
-  ├── session.json       # state + audit_result + diagnoses + patterns + phase_goals
-  ├── evidence.ndjson    # append-only (phase: survey|audit|diagnosis|fix|discovery|decision|self-iteration)
-  └── understanding.md   # 9-section evolving narrative
-```
-
-**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": [],
-  "confirmation": null,
-  "generalization_stats": null,
-  "phase_goals": [], "phase_goals_all_done": false,
-  "self_iteration_log": [],
-  "cross_phase_loops": 0, "max_loops": 5,
-  "created_at": "", "updated_at": ""
-}
-```
-
-**evidence.ndjson unified schema:** `{"ts":"","phase":"<phase>","type":"<type>","dimension":"","title":"","severity":"","file":"","line":0,"description":"","suggestion":"","measurement":""}`
-
-Phase-specific fields:
+**Output:** `session.json` (state + audit + diagnoses + patterns + goals) | `evidence.ndjson` (append-only) | `understanding.md` (9-section narrative)
+
+**session.json unique fields:** `target`, `dimensions`, `baseline_metrics`, `audit_result`, `diagnoses`, `confirmation`, `generalization_stats` (`progress_metrics`, `directions_tried` from base)
+
+**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`
@@ -131,8 +83,6 @@ Phase-specific fields:
 | 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 (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
@@ -140,15 +90,9 @@ Lifecycle: `pending → done | skipped | failed` (all set `completion_confirmed`
 8. Improvement Metrics ← S_RECORD (before/after) | 9. Engineering Learnings ← S_RECORD
 
 ### Pre-load（可选，缺失不阻塞）
-
-| 层级 | 命令 | 作用 |
-|------|------|------|
-| Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` | 模块边界，作为分析上下文 |
-| Wiki search | `maestro search "<target keywords>" --json` | 先前优化、相关决策（取 top 5） |
-| Coding specs | `maestro load --type spec --category coding` | 编码规范 |
-| Debug specs | `maestro load --type spec --category debug` | 已知性能/安全模式 |
-| Role knowledge | `maestro search --category coding` → 选相关 → `maestro load --type knowhow --id <id>` | 累积领域知识 |
-| Prior sessions | `Glob(".workflow/scratch/*-improve-odyssey-*")` | 相关会话 |
+- 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-*")` → 先前会话
 
 ### Knowledge Persistence（S_RECORD 中写入产出文件）
 
@@ -160,25 +104,9 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §9 Learnings**，
 | 安全规则 | 漏洞类别 + 修复 + 预防方法 | `/spec-add debug "..."` |
 | 架构约束 | 违反描述 + 正确边界 + 检查方法 | `/spec-add arch "..."` |
 | 可靠性 pattern | 故障模式 + 处理策略 + 验证手段 | `/spec-add coding "..."` |
-
-**两步模式：** 执行中写入产出文件（临时记录）→ 任务完成后用户通过 next_step_routing 沉淀为永久知识。执行过程中不调用外部 Skill。
 </context>
 
-<self_iteration>
-**Quality Gate** — auto-evaluate after each analytical phase. Insufficient → re-enter (max **3 rounds**).
-
-| Dimension | Sufficient | Insufficient |
-|-----------|-----------|-------------|
-| Coverage | All target files/modules analyzed across dimensions | Missed files discoverable via grep/glob |
-| 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). Round 3 = combine both + targeted deep-dive on remaining gaps.
-
-**Log:** `evidence.ndjson ← {"phase":"self-iteration","type":"quality-gate","stage":"S_XXX","round":N,"assessment":{},"expansion":""}`
-
-**Applicable stages:** S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE
-</self_iteration>
+Self-iteration 适用阶段: S_SURVEY, S_AUDIT, S_DIAGNOSE, S_GENERALIZE
 
 <state_machine>
 
@@ -252,38 +180,14 @@ Find latest session via Glob → read `session.json` → display summary → jum
 ### A_SURVEY
 Current state survey — understand what exists before proposing changes.
 
-1. **Dependency audit**: Read package.json/lock files, scan for outdated/vulnerable deps
-2. **Complexity scan**: Identify high-complexity files (file size, function count, nesting depth)
-3. **Test coverage map**: Which modules have coverage, which don't
-4. **Error handling scan**: Grep for empty catch, unhandled promise, missing error boundaries
-5. **CLI-assisted survey** (optional):
-```bash
-maestro delegate "PURPOSE: Survey codebase health of: {target}
-TASK: Dependency health | Complexity hotspots | Test coverage gaps | Error handling patterns
-MODE: analysis
-CONTEXT: @{target_files}
-EXPECTED: JSON {dependency_health, complexity_hotspots, coverage_gaps, error_patterns}
-CONSTRAINTS: Focus on runtime quality, not style
-" --role analyze --mode analysis
-```
-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.
+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.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): SURVEY — 现状调查"`
 
 ### A_AUDIT
-Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset):
-
-| Agent | Dimension | Focus |
-|-------|-----------|-------|
-| Performance | performance | Hot paths, N+1 queries, memory allocation, cache efficiency, bundle size, lazy loading |
-| Security | security | OWASP Top 10, injection, auth bypass, data exposure, dependency vulns, secrets |
-| Architecture | architecture | Layer violations, circular deps, coupling, interface contracts, SRP violations |
-| Reliability | reliability | Error handling gaps, retry logic, timeout handling, graceful degradation, cleanup |
-| Observability | observability | Logging coverage, metric gaps, trace propagation, error reporting, health checks |
-| Maintainability | maintainability | Cyclomatic complexity, dead code, test coverage gaps, documentation debt |
-
+Spawn 6 parallel Agents (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`.
@@ -294,25 +198,10 @@ Update `understanding.md` §3 (findings by dimension + severity matrix). Mark G2
 ### A_DIAGNOSE
 Root cause analysis for critical/high findings — don't fix symptoms.
 
-1. Group findings by dimension, prioritize by severity
-2. For each critical/high finding:
-   - Form hypothesis about root cause
-   - Test: trace code path, check git history, verify with evidence
-   - Record to evidence.ndjson (phase: "diagnosis")
-3. **Decision journal**: ambiguity → evidence (phase: "decision"); Normal: AskUserQuestion | `-y`: defer
-4. **CLI-assisted diagnosis** for complex findings:
-```bash
-maestro delegate "PURPOSE: Diagnose root cause of: {finding}
-TASK: Trace code path | Check for systemic pattern | Identify fix approach
-MODE: analysis
-CONTEXT: @{relevant_files} | Finding: {finding_detail}
-EXPECTED: JSON {root_cause, systemic, fix_approach, risk}
-CONSTRAINTS: Focus on root cause, not symptom
-" --role analyze --mode analysis
-```
-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.
+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: AskUserQuestion | `-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.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): DIAGNOSE — 根因诊断"`
 
@@ -329,68 +218,21 @@ Skip if `--skip-fix`. Implement improvements for diagnosed root causes.
 📌 **Auto-commit**: `git add -A && git commit -m "odyssey-improve({slug}): FIX — 改进实现"`
 
 ### A_VERIFY
-Verify improvements with measurement comparison.
-
 1. Run tests covering modified areas
-2. **Measure improvement**: re-capture metrics, compare with `session.json.baseline_metrics`
-3. **CLI-assisted verification**:
-```bash
-maestro delegate "PURPOSE: Verify improvements for: {target}
-TASK: Check fix correctness | Test regressions | Measure impact | Compare with baseline
-MODE: analysis
-CONTEXT: @{modified_files} | Baseline: {baseline_metrics} | Fixes: {fix_summary}
-EXPECTED: JSON {verdict, metrics_improved, regressions, remaining_issues}
-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).
-
+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}): VERIFY — 改进验证"`
 
 ### A_GENERALIZE
-Multi-layer pattern extraction from diagnoses + fixes → 4-agent scan → cross-layer dedup.
-
-**Pattern extraction** from root causes + improvements:
-
-| Layer | Method | Example |
-|-------|--------|---------|
-| Syntax | Regex → direct Grep | Missing `await`, unclosed resource, empty catch, `eval(` |
-| Semantic | Agent understands anti-pattern → scans | Unhandled async errors, missing retry, N+1 query |
-| Structural | File/module structure similarity | Same import pattern, missing error boundary |
-| Historical | `git log -S "{pattern}"` | When similar issues were introduced/fixed |
-
-Write `session.json.patterns[]`: `[{id, source_finding, layer, signature, description, risk, fix_template, confidence}]`
-
-**4-agent parallel scan** (single message):
-
-| Agent | Strategy | Scope |
-|-------|----------|-------|
-| Syntax grep | Grep patterns matching found issues | Full project |
-| Semantic scan | Find modules with same anti-pattern | Related modules |
-| Structural match | Find structurally similar files | Full project |
-| Historical grep | `git log -S "{pattern}"` | Git history |
-
-**Cross-layer dedup**: Multi-layer hit → boost confidence. Single-layer → `needs_review`. Historical match on fixed code → `regression_risk`.
-
-**Iterative deepening**: Module with ≥3 hits → targeted deep scan (max 1 round).
-
-Update `understanding.md` §6. Write `session.json.generalization_stats`. Mark G5 done.
+按 base A_GENERALIZE 执行。Pattern 来源: diagnoses + fixes。Mark G5 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): GENERALIZE — 泛化扫描"`
 
 ### A_DISCOVER
-1. **Triage** each hit: read ±10 lines context → classify `safe`/`risk`/`issue`
-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**: AskUserQuestion 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.
+按 base A_DISCOVER 执行。Mark G6 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): DISCOVER — 发现分类"`
 
@@ -398,26 +240,8 @@ Update `understanding.md` §6. Write `session.json.generalization_stats`. Mark G
 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** → AskUserQuestion. **`-y`** → skip, show deferred count.
-4. **Goal audit**: all `phase_goals[*].completion_confirmed` true → `phase_goals_all_done = true`. Any false: **Normal** → AskUserQuestion (回退/跳过/接受) | **`-y`** → auto accept.
-5. `current_state = "COMPLETED"`. Emit completion summary:
-```
---- IMPROVE ODYSSEY COMPLETE ---
-Target:      {target}
-Dimensions:  {dimensions_audited}
-Findings:    {C}C {H}H {M}M {L}L
-Diagnosed:   {diagnosed_count} root causes identified
-Fix:         {fixed_count} improvements, verified={yes|skipped}
-Metrics:     {improved} improved, {regressed} regressed
-Patterns:    {extracted} ({by_layer} distribution)
-Scan hits:   {total} ({cross_layer} cross-layer confirmed)
-Issues:      {N} created
-Decisions:   {N} resolved, {M} pending, {K} deferred
-Learnings:   {N} entries in understanding.md §9
-Self-iter:   {N} quality gate rounds across {M} stages
-Cross-loops: {cross_phase_loops}/{max_loops} used
-Goals:       {done}/{total} ({skipped} skipped)
----
-```
+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).
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-improve({slug}): RECORD — 指标总结与知识沉淀"`
 
@@ -426,22 +250,13 @@ Goals:       {done}/{total} ({skipped} skipped)
 <appendix>
 
 ### Goal Prompt Template
-**⚠️ 时机守卫：仅在 A_INTAKE 完成后显示一次。A_RECORD 完成时禁止重新显示。**
+**⚠️ 仅在 A_INTAKE 完成后显示一次，A_RECORD 完成时不重复。**
 
-```
-📋 Improve Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
-
-/goal 完成以下目标：
-{for each G in phase_goals where status != "skipped":}
-- {G.id}: {G.goal} — 完成条件: {G.done_when}
-{end for}
-穷尽迭代：直到 session.json 的 audit_result 中所有 findings 均已处理（fix/issue/decision）
-且 phase_goals_all_done=true 才停。修复按 severity 逐轮迭代，每轮修复后 re-verify 修改区域。
-Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比确认改进。
-遇到 phase=decision 的 pending 必须 AskUserQuestion。不允许"只报告不处理"。
-```
-
-完成时仅输出 completion summary，不重复此提示。
+列出所有非 skipped 的 phase_goals，附加收敛规则：
+- 穷尽迭代至所有 findings 已处理（fix/issue/decision）且 `phase_goals_all_done=true`
+- 修复按 severity 逐轮迭代，每轮 re-verify
+- Baseline 修复前采集，修复后对比确认改进
+- pending decision 必须 AskUserQuestion，不允许"只报告不处理"
 
 ### `-y` Auto-Confirm Behavior
 | Decision Point | Normal | `-y` |
@@ -456,11 +271,6 @@ Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比
 
 `deferred` items shown as "待决策" in completion summary; recoverable via `-c`.
 
-### Phase Goal Lifecycle
-`pending → done (confirmed=true)` normal | `pending → skipped (confirmed=true)` flags/manual | `pending → failed (confirmed=false)` exception
-
-`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
-
 </appendix>
 
 </state_machine>
@@ -470,30 +280,19 @@ Baseline metrics 必须在修复前采集，修复后必须与 baseline 对比
 |------|----------|-----------|----------|
 | E001 | error | No target specified | Provide target or use -c |
 | E002 | error | Target path not found | Check path |
-| E003 | error | Resume but no session found | Start new session |
 | W001 | warning | No dependency manifest found | Proceed without dep audit |
 | W002 | warning | Some dimension agents failed | Partial audit coverage |
-| W003 | warning | Generalization 0 hits | Skip discovery |
-| W004 | warning | Delegate parse failed | Use raw output |
 </error_codes>
 
 <success_criteria>
-- [ ] Target resolved, baseline metrics captured in session.json
-- [ ] Dependency + complexity + coverage survey completed
-- [ ] All dimensions audited (6 parallel agents) with structured findings
-- [ ] Severity matrix produced
-- [ ] Root causes diagnosed for critical/high findings (hypothesis-driven)
+- [ ] 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 scan + cross-layer dedup (unless --skip-generalize)
-- [ ] 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
+- [ ] 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
-- [ ] Goal Prompt displayed once
-- [ ] `-y`: no blocking prompts, deferred counted
 - [ ] Session resumable via -c
 </success_criteria>
 

package/.claude/commands/odyssey-planex.md

@@ -1,7 +1,7 @@
 ---
 name: odyssey-planex
 description: Requirement-driven iterative cycle — plan, execute, strict verify, fix loop until acceptance criteria met
-argument-hint: "<requirement> [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [-y] [-c]"
+argument-hint: "<requirement> [--max-iterations N] [--skip-generalize] [--auto] [--method agent|cli|auto] [--executor <tool>] [--skip-verify] [--heartbeat] [-y] [-c]"
 allowed-tools:
   - Read
   - Write
@@ -12,6 +12,8 @@ allowed-tools:
   - Agent
   - AskUserQuestion
 ---
+<base>@~/.maestro/workflows/odyssey-base.md</base>
+
 <purpose>
 Requirement-to-delivery closed loop: parse requirement → define acceptance criteria →
 plan → execute → verify → fix gaps → iterate until ALL criteria pass.
@@ -21,7 +23,6 @@ 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 模式 | 适用场景 |
@@ -33,31 +34,6 @@ plan → execute → verify → fix gaps → iterate until ALL criteria pass.
 | `api-endpoint` | 请求/响应契约 + 错误处理 + 权限校验 | API 开发 |
 </boundary>
 
-<execution_discipline>
-**三条铁律（所有阶段适用）:**
-
-1. **Phase auto-commit** — 每个阶段完成后**自动** `git commit`，无需用户确认
-   - 代码变更 + understanding.md → `git add` → `git commit -m "odyssey-planex({slug}): {phase} — {摘要}"`
-   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
-
-2. **Confident edits only, but must attempt** — only modify what you're confident about; record decisions only when genuinely requiring human judgment
-   - 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` 获取任务分解建议
-   - 修复前后: `--role review` 确认无回归
-   - verify 阶段: cli-review 类型标准自动 delegate
-
-4. **禁止以上下文消耗为由中断** — harness 自动处理 context compression，以"上下文不足"或"已执行 N 个阶段"为由中断属于纪律违反；必须完整走完状态机直到 S_RECORD → END
-</execution_discipline>
-
 <context>
 $ARGUMENTS — requirement description and optional flags.
 
@@ -71,6 +47,7 @@ $ARGUMENTS — requirement description and optional flags.
 | `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
 | `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
 | `--skip-verify` | Skip execution post-validation gate | false |
+| `--heartbeat` | Enable periodic progress heartbeat | false |
 | `-y` | Auto-confirm — decisions recorded as `deferred` | false |
 | `-c` | Resume most recent session | — |
 
@@ -114,6 +91,8 @@ SESSION_DIR/
   "phase_goals": [],
   "phase_goals_all_done": false,
   "self_iteration_log": [],
+  "progress_metrics": "→ base",
+  "directions_tried": "→ base",
   "cross_phase_loops": 0, "max_loops": 5,
   "created_at": "", "updated_at": ""
 }
@@ -155,24 +134,10 @@ S_RECORD 阶段将可沉淀知识 **写入 understanding.md §8 Learnings**，
 | 可复用实现模式 | 模式描述 + 适用场景 + 代码模板 | `/spec-add coding "..."` |
 | 验收标准模板 | 标准模板 + verify_method 建议 | `/spec-add review "..."` |
 | 泛化 pattern | pattern 签名 + 风险说明 + fix 模板 | `/spec-add coding "..."` |
-
-**两步模式：** 执行中写入产出文件（临时记录）→ 任务完成后用户通过 next_step_routing 沉淀为永久知识。执行过程中不调用外部 Skill。
 </context>
 
 <self_iteration>
-**Quality Gate** — auto-evaluate after each analytical stage. Insufficient → re-enter with expanded strategy.
-
-| Dimension | Sufficient | Insufficient |
-|-----------|-----------|-------------|
-| Coverage | All known files/modules analyzed | Missed targets discoverable via grep/git log |
-| 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 **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). Round 3 = combine both + targeted deep-dive on remaining gaps.
-
-**Applies to:** S_PLAN, S_VERIFY, S_GENERALIZE
+适用阶段: S_PLAN, S_VERIFY, S_GENERALIZE
 </self_iteration>
 
 <state_machine>
@@ -261,7 +226,6 @@ AskUserQuestion({
       options: [
         { label: "Auto (Recommended)", description: "域路由: frontend→{frontendTool}, backend→{backendTool}, general→agent" },
         { label: "Agent", description: "Claude Code Agent 执行所有任务（最快）" },
-        // 每个 enabled CLI tool 一个选项
         ...availableTools.map(t => ({ label: t, description: `${t} CLI 执行所有任务` }))
       ]
     },
@@ -302,13 +266,6 @@ Per-task domain routing (when method == "auto"):
 
 Resolution: `execution_config.domain_routing[domain]` → fallback `domain_routing.default` ("agent").
 
-Log routing per task:
-```
-T1 [frontend] → agy
-T2 [backend]  → codex
-T3 [general]  → agent
-```
-
 #### Step 3: Task Execution
 
 Execute tasks per plan order. Independent tasks (no cross-dependency) may run in parallel.
@@ -440,50 +397,20 @@ Update understanding.md §4 with pass/fail table.
 
 ### A_GENERALIZE
 
-Extract reusable patterns from implementation, scan codebase for similar sites.
-
-**Pattern extraction (3 layers):**
-| Layer | Method | Example |
-|-------|--------|---------|
-| Syntax | Code regex patterns | validation/error handling patterns |
-| Semantic | Logic pattern description | missing similar checks at other entry points |
-| Structural | File/module structure match | sibling modules lacking same treatment |
-
-**4-agent parallel scan** (spawn 4 Agents):
-| Agent | Strategy | Scope |
-|-------|----------|-------|
-| Syntax grep | Grep syntax-layer signatures | full project |
-| Semantic scan | Check for same anti-pattern in related modules | related modules |
-| Structural match | Find structurally similar files | full project |
-| Historical grep | `git log -S "{pattern}"` | full git history |
-
-Each returns: `[{pattern_id, file, line, context, risk_level, layer, confidence}]`
-
-**Cross-layer dedup:** multi-layer hit on same file:line → boost confidence. Historical hit with existing fix → `already_handled`. Single layer only → `needs_review`.
-
-**Quality Gate** (self-iteration) → evaluate coverage/depth/actionability.
-
-Write understanding.md §6, generalization_stats. Mark G5 done.
+按 base A_GENERALIZE 执行。Pattern 来源: implementation patterns。Mark G5 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-planex({slug}): GENERALIZE — 泛化扫描"`
 
 ### A_DISCOVER
 
-1. **Triage:** per hit, read context (+-10 lines), classify as `already_handled` | `needs_treatment` | `low_risk`
-2. **Route:**
-   | Classification | Normal | `-y` |
-   |---------------|--------|------|
-   | needs_treatment | AskUserQuestion: create issue / plan next iter | auto create issue, `deferred` |
-   | low_risk | Record only | Record only |
-   | already_handled | Skip | Skip |
-3. Append evidence (discovery + decision), update understanding.md §7. Mark G6 done.
+按 base A_DISCOVER 执行。Mark G6 done.
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-planex({slug}): DISCOVER — 发现分类"`
 
 ### A_RECORD
 
 1. Finalize understanding.md §8 — iteration summary, what worked, what needed rework
-2. Write learnings to understanding.md §8: 按 Knowledge Persistence 表分类记录（临时），completion summary 列出建议的 `/spec-add` 命令
+2. Write learnings to understanding.md §8: 按 Knowledge Persistence 表分类记录
 3. Pending decisions: **Normal** → AskUserQuestion. **`-y`** → display deferred count.
 4. Goal audit: check all phase_goals[*].completion_confirmed. Mark G7 done.
 5. Output completion summary:
@@ -501,6 +428,7 @@ Write understanding.md §6, generalization_stats. Mark G5 done.
    Status:      {ALL_PASSED|PARTIAL|ESCALATED}
    ---
    ```
+6. 其余按 base A_RECORD 执行。
 
 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-planex({slug}): RECORD — 会话总结"`
 
@@ -566,35 +494,23 @@ Max iterations (default 3) prevents infinite loops. Each iteration records crite
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | No requirement provided | Provide requirement |
-| E003 | error | Resume but no session found | Start new |
-| E004 | error | Delegate failed | Retry or proceed without |
 | W001 | warning | No acceptance criteria derived | Manual definition needed |
 | W002 | warning | Max iterations reached, criteria still failing | Escalate to user |
 | W003 | warning | CLI review regression concern | Review before next iteration |
-| W004 | warning | Delegate parse failed | Use raw output |
 </error_codes>
 
 <success_criteria>
-- [ ] Requirement parsed and ≥1 acceptance criterion defined with verify_method
-- [ ] Plan created with tasks mapped to criteria
-- [ ] Execution options confirmed (executor/review/verify) before task dispatch
-- [ ] Tasks dispatched via resolved executor (agent/cli/auto domain routing)
-- [ ] Per-task deviation rule enforced (max 3 retries, fallback chain)
+- [ ] Requirement parsed with ≥1 acceptance criterion (verify_method assigned)
+- [ ] Plan tasks mapped to criteria; execution options confirmed
+- [ ] Tasks dispatched via resolved executor with deviation rule (max 3 retries)
 - [ ] Post-execution validation gate run (unless --skip-verify)
-- [ ] Tasks executed with evidence logged (executor, attempt count, files_modified)
-- [ ] 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)
-- [ ] Quality Gate self-iteration triggered when insufficient, logged in self_iteration_log
-- [ ] phase_goals G1-G7 tracked and audited
-- [ ] Goal Prompt displayed once after intake
-- [ ] `-y` mode: no blocking prompts, deferred counted
-- [ ] Session resumable via -c
-- [ ] Completion summary with iteration stats
+- [ ] Every criterion verified per method; failing → targeted fix (not re-implementation)
+- [ ] Iteration count tracked and max respected; unfixed criteria individually classified
+- [ ] understanding.md §1-§8 updated per phase; phase_goals G1-G7 audited
+- [ ] Generalization + discovery completed (unless --skip-generalize)
+- [ ] Quality Gate self-iteration triggered when insufficient
+- [ ] Goal Prompt displayed once after intake; `-y` mode: no blocking prompts
+- [ ] Session resumable via -c; completion summary output
 </success_criteria>
 
 <next_step_routing>