maestro-flow 0.5.40 → 0.5.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/.agents/skills/maestro-analyze/SKILL.md +0 -42
  2. package/.agents/skills/maestro-blueprint/SKILL.md +0 -22
  3. package/.agents/skills/maestro-brainstorm/SKILL.md +4 -24
  4. package/.agents/skills/maestro-execute/SKILL.md +1 -1
  5. package/.agents/skills/maestro-grill/SKILL.md +0 -16
  6. package/.agents/skills/maestro-milestone-audit/SKILL.md +0 -15
  7. package/.agents/skills/maestro-plan/SKILL.md +5 -62
  8. package/.agents/skills/maestro-roadmap/SKILL.md +0 -8
  9. package/.agents/skills/odyssey-debug/SKILL.md +109 -143
  10. package/.agents/skills/odyssey-improve/SKILL.md +127 -141
  11. package/.agents/skills/odyssey-planex/SKILL.md +140 -231
  12. package/.agents/skills/odyssey-review-test-fix/SKILL.md +136 -90
  13. package/.agents/skills/odyssey-ui/SKILL.md +123 -143
  14. package/.agents/skills/team-adversarial-swarm/workflows/wf-swarm-synthesize.js +248 -248
  15. package/.agents/skills/team-coordinate/specs/role-spec-template.md +197 -198
  16. package/.agents/skills/team-roadmap-dev/SKILL.md +164 -164
  17. package/.agents/skills/team-roadmap-dev/specs/team-config.json +1 -1
  18. package/.agents/skills/team-swarm/roles/analyst/role.md +172 -176
  19. package/.agy/skills/maestro-analyze/SKILL.md +0 -42
  20. package/.agy/skills/maestro-blueprint/SKILL.md +0 -22
  21. package/.agy/skills/maestro-brainstorm/SKILL.md +4 -24
  22. package/.agy/skills/maestro-execute/SKILL.md +1 -1
  23. package/.agy/skills/maestro-grill/SKILL.md +0 -16
  24. package/.agy/skills/maestro-milestone-audit/SKILL.md +0 -15
  25. package/.agy/skills/maestro-plan/SKILL.md +5 -62
  26. package/.agy/skills/maestro-roadmap/SKILL.md +0 -8
  27. package/.agy/skills/odyssey-debug/SKILL.md +109 -143
  28. package/.agy/skills/odyssey-improve/SKILL.md +127 -141
  29. package/.agy/skills/odyssey-planex/SKILL.md +140 -231
  30. package/.agy/skills/odyssey-review-test-fix/SKILL.md +136 -90
  31. package/.agy/skills/odyssey-ui/SKILL.md +123 -143
  32. package/.agy/skills/team-adversarial-swarm/workflows/wf-swarm-synthesize.js +248 -248
  33. package/.agy/skills/team-coordinate/specs/role-spec-template.md +197 -198
  34. package/.agy/skills/team-roadmap-dev/SKILL.md +141 -153
  35. package/.agy/skills/team-roadmap-dev/specs/team-config.json +1 -1
  36. package/.agy/skills/team-swarm/roles/analyst/role.md +172 -176
  37. package/.claude/commands/maestro-analyze.md +0 -42
  38. package/.claude/commands/maestro-blueprint.md +0 -22
  39. package/.claude/commands/maestro-brainstorm.md +4 -24
  40. package/.claude/commands/maestro-execute.md +1 -1
  41. package/.claude/commands/maestro-grill.md +0 -16
  42. package/.claude/commands/maestro-milestone-audit.md +0 -15
  43. package/.claude/commands/maestro-plan.md +5 -62
  44. package/.claude/commands/maestro-roadmap.md +0 -8
  45. package/.claude/commands/odyssey-debug.md +109 -143
  46. package/.claude/commands/odyssey-improve.md +127 -141
  47. package/.claude/commands/odyssey-planex.md +140 -231
  48. package/.claude/commands/odyssey-review-test-fix.md +136 -90
  49. package/.claude/commands/odyssey-ui.md +123 -143
  50. package/.claude/skills/team-adversarial-swarm/workflows/wf-swarm-synthesize.js +248 -248
  51. package/.claude/skills/team-coordinate/specs/role-spec-template.md +197 -198
  52. package/.claude/skills/team-roadmap-dev/SKILL.md +169 -169
  53. package/.claude/skills/team-roadmap-dev/specs/team-config.json +1 -1
  54. package/.claude/skills/team-swarm/roles/analyst/role.md +181 -185
  55. package/.codex/skills/odyssey-debug/SKILL.md +114 -169
  56. package/.codex/skills/odyssey-improve/SKILL.md +144 -188
  57. package/.codex/skills/odyssey-planex/SKILL.md +162 -242
  58. package/.codex/skills/odyssey-review-test-fix/SKILL.md +96 -90
  59. package/.codex/skills/odyssey-ui/SKILL.md +128 -173
  60. package/dashboard/dist-server/src/commands/install-backend.js +31 -16
  61. package/dashboard/dist-server/src/commands/install-backend.js.map +1 -1
  62. package/dashboard/dist-server/src/core/component-defs.js +25 -0
  63. package/dashboard/dist-server/src/core/component-defs.js.map +1 -1
  64. package/dashboard/dist-server/src/tools/spec-loader.js +32 -20
  65. package/dashboard/dist-server/src/tools/spec-loader.js.map +1 -1
  66. package/dashboard/dist-server/src/tools/spec-seeds.d.ts +8 -0
  67. package/dashboard/dist-server/src/tools/spec-seeds.js +114 -0
  68. package/dashboard/dist-server/src/tools/spec-seeds.js.map +1 -1
  69. package/dist/src/commands/install-backend.d.ts.map +1 -1
  70. package/dist/src/commands/install-backend.js +31 -16
  71. package/dist/src/commands/install-backend.js.map +1 -1
  72. package/dist/src/commands/spec.d.ts.map +1 -1
  73. package/dist/src/commands/spec.js +13 -3
  74. package/dist/src/commands/spec.js.map +1 -1
  75. package/dist/src/core/component-defs.d.ts.map +1 -1
  76. package/dist/src/core/component-defs.js +25 -0
  77. package/dist/src/core/component-defs.js.map +1 -1
  78. package/dist/src/tools/spec-init.d.ts +4 -3
  79. package/dist/src/tools/spec-init.d.ts.map +1 -1
  80. package/dist/src/tools/spec-init.js +9 -5
  81. package/dist/src/tools/spec-init.js.map +1 -1
  82. package/dist/src/tools/spec-loader.d.ts.map +1 -1
  83. package/dist/src/tools/spec-loader.js +32 -20
  84. package/dist/src/tools/spec-loader.js.map +1 -1
  85. package/dist/src/tools/spec-seeds.d.ts +8 -0
  86. package/dist/src/tools/spec-seeds.d.ts.map +1 -1
  87. package/dist/src/tools/spec-seeds.js +114 -0
  88. package/dist/src/tools/spec-seeds.js.map +1 -1
  89. package/dist/src/utils/update-notices.js +11 -0
  90. package/dist/src/utils/update-notices.js.map +1 -1
  91. package/package.json +1 -1
  92. package/workflows/agy-instructions.md +147 -161
  93. package/workflows/claude-instructions.md +100 -48
  94. package/workflows/codex-instructions.md +147 -161
  95. package/workflows/execute.md +4 -3
  96. package/workflows/explore-usage.md +41 -81
  97. package/workflows/grill.md +11 -0
  98. package/workflows/milestone-audit.md +8 -0
  99. package/workflows/odyssey-base-codex.md +305 -0
  100. package/workflows/odyssey-base.md +89 -91
  101. package/workflows/plan.md +6 -0
@@ -4,54 +4,41 @@ description: "Long-running debug cycle — archaeology, diagnosis, fix, confirma
4
4
  argument-hint: "<issue> [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
5
5
  allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
6
6
  ---
7
- <base>@~/.maestro/workflows/odyssey-base.md</base>
7
+ <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
8
8
 
9
9
  <purpose>
10
- Closed-loop deep debugging: archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.
11
- Treats every bug as a learning signal with exhaustive iteration until root cause confirmed or INCONCLUSIVE.
12
-
13
- Core philosophy:
14
- - **Archaeology before hypothesis** — look at what changed before guessing why
15
- - **Fix one, find many** — a single bug reveals a class of bugs
16
- - **Decision journal** — human-judgment items recorded, not lost
17
- - **CLI-assisted review** — delegate for second-opinion analysis
18
-
19
- **三句哲学约束(穷尽迭代):**
20
- 1. **零遗留** — 根因必须确认到底,修复必须验证通过,泛化必须扫描穷尽
21
- 2. **穷尽迭代** — 假设失败不放弃:扩范围 → 换视角 → 升级工具,直到根因确认或明确 INCONCLUSIVE
22
- 3. **改进即标准** — 修复后重新确认同区域无新问题,泛化发现的同类 bug 全部处理
10
+ archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.
11
+ Exhaustive iteration until root cause confirmed or INCONCLUSIVE.
23
12
  </purpose>
24
13
 
25
14
  <boundary>
26
- **范围内:** 单一 bug/issue 的完整闭环 — 考古 → 探索 → 诊断 → 修复 → 确认 → 泛化同类 → 沉淀
27
- **范围外:** 新功能开发 → `$odyssey-planex` | 代码质量审查 → `$odyssey-review-test-fix` | UI 视觉优化 → `$odyssey-ui` | 架构重设计 → `/maestro-plan`
28
- **探索自由度:** 边界内自由探索 — 可追踪任意调用链、分析任意历史、测试任意假设。泛化阶段可扫描全项目寻找同类问题。
29
- **Zero-residual principle:** Every finding MUST have a concrete action (fix / issue / decision). "Pre-existing issue" is not a valid skip reason.
30
- **模板支持:** `--template <name>` 从预定义调查策略启动:
31
-
32
- | Template | 调查策略 | 适用场景 |
33
- |----------|---------|---------|
34
- | `performance` | profilinghot pathallocation cache | 性能劣化 |
35
- | `memory-leak` | heap snapshot retention chainlifecycle | 内存泄漏 |
36
- | `race-condition` | timelineconcurrent accesslock analysis | 竞态条件 |
37
- | `regression` | git bisectdiff analysisboundary check | 回归问题 |
38
- | `crash` | stack trace → null chain → error propagation | 崩溃/异常 |
15
+ **In scope:** Single bug/issue full loop.
16
+ **Out of scope:** Features → `$odyssey-planex` | Quality review → `$odyssey-review-test-fix` | UI → `$odyssey-ui` | Architecture → `/maestro-plan`
17
+
18
+ **`--template <name>`:**
19
+
20
+ | Template | Strategy | Use case |
21
+ |----------|----------|----------|
22
+ | `performance` | profiling → hot path → allocation → cache | Performance degradation |
23
+ | `memory-leak` | heap snapshot retention chainlifecycle | Memory leaks |
24
+ | `race-condition` | timelineconcurrent accesslock analysis | Race conditions |
25
+ | `regression` | git bisect diff analysisboundary check | Regressions |
26
+ | `crash` | stack tracenull chainerror propagation | Crashes / exceptions |
39
27
  </boundary>
40
28
 
41
29
  <context>
42
- $ARGUMENTS — issue description and optional flags.
30
+ $ARGUMENTS
43
31
 
44
- **Flags:** `--skip-fix` analysis-only | `--skip-generalize` quick fix | `--template <name>` 预定义策略 | `--auto` no delegate confirmation | `-y` auto-confirm all decisions | `-c` resume last session | `--heartbeat` enable /loop heartbeat
32
+ **Flags:** `--skip-fix` analysis-only | `--skip-generalize` quick fix | `--template <name>` | `--auto` no delegate confirmation | `-y` auto-confirm | `-c` resume | `--heartbeat` /loop heartbeat
45
33
 
46
- **Session**: `SESSION_DIR = .workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/`
34
+ **Session**: `.workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/`
47
35
  **Output**: `session.json` | `evidence.ndjson` | `explore.json` | `understanding.md`
48
36
 
49
- **session.json unique fields:**
37
+ **session.json debug-specific fields:**
50
38
  ```json
51
39
  { "issue": "", "diagnosis_retries": 0, "root_cause": null, "confirmation": null,
52
- "patterns": [], "generalization_stats": null, "cross_phase_loops": 0, "max_loops": 5 }
40
+ "patterns": [], "generalization_stats": null }
53
41
  ```
54
- 共有字段(`progress_metrics`, `directions_tried` 等)见 base。
55
42
 
56
43
  **evidence.ndjson phases:** `archaeology|explore|diagnosis|discovery|decision|self-iteration`
57
44
  - `archaeology`: `sha`, `author`, `date`, `message`, `relevance`
@@ -79,23 +66,14 @@ $ARGUMENTS — issue description and optional flags.
79
66
  4. Hypotheses ← S_DIAGNOSE | 5. Root Cause ← S_DIAGNOSE | 6. Fix & Confirmation ← S_FIX+S_CONFIRM
80
67
  7. Generalization ← S_GENERALIZE | 8. Discoveries ← S_DISCOVER | 9. Learnings ← S_RECORD
81
68
 
82
- ### Pre-load(可选,缺失不阻塞)
69
+ **Knowledge Persistence categories (§9):**
83
70
 
84
- | 命令 | 作用 |
85
- |------|------|
86
- | Read `.workflow/codebase/ARCHITECTURE.md` | 模块边界 |
87
- | `maestro search "<issue keywords>" --json` | 先前调查(top 5) |
88
- | `maestro load --type spec --category debug --keyword "<symptom>"` | 已知 issue/workaround |
89
- | `Glob(".workflow/scratch/*-debug-odyssey-*")` | 相关 odyssey 会话 |
90
-
91
- ### Knowledge Persistence(S_RECORD → understanding.md §9)
92
-
93
- | 分类 | 后续建议命令 |
94
- |------|-------------|
95
- | 反复根因模式 | `/spec-add debug "..."` |
96
- | 非显而易见 workaround | `/spec-add learning "..."` |
97
- | 架构边界违反 | `/spec-add arch "..."` |
98
- | 可复用泛化 pattern | `/spec-add coding "..."` |
71
+ | Category | Content | Follow-up |
72
+ |----------|---------|-----------|
73
+ | Recurring root cause pattern | Type + triggers + fix + detection | `/spec-add debug` |
74
+ | Non-obvious workaround | Problem + steps + why obvious fix fails | `/spec-add learning` |
75
+ | Architecture boundary violation | Violation + correct boundary + verification | `/spec-add arch` |
76
+ | Reusable generalization pattern | Signature + risk + fix template + scope | `/spec-add coding` |
99
77
  </context>
100
78
 
101
79
  <csv_schema>
@@ -128,8 +106,14 @@ id,title,description,task_type,deps,wave,status,findings,evidence,error
128
106
  - Single-agent stages (explore, diagnose, fix, confirm) remain inline
129
107
  </csv_schema>
130
108
 
109
+ <invariants>
110
+ Base execution_discipline applies. Debug additions:
111
+ 1. **Evidence append-only** — never delete or overwrite evidence.ndjson entries
112
+ 2. **Phase goal tracking** — mark goal done/failed before transition; no silent skips
113
+ </invariants>
114
+
131
115
  <self_iteration>
132
- 适用阶段: S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE
116
+ Applies to: **S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE**. Logic in base.
133
117
  </self_iteration>
134
118
 
135
119
  <state_machine>
@@ -143,14 +127,14 @@ S_INTAKE → S_INTAKE : -c + session found → A_RESUME_SESSION
143
127
  S_INTAKE → S_ARCHAEOLOGY : issue parsed → A_INTAKE
144
128
  S_INTAKE → S_INTAKE : no issue, no session → request_user_input
145
129
 
146
- S_ARCHAEOLOGY → S_EXPLORE : A_ARCHAEOLOGY complete
147
- S_EXPLORE → S_DIAGNOSE : A_EXPLORE complete
130
+ S_ARCHAEOLOGY → S_EXPLORE : complete
131
+ S_EXPLORE → S_DIAGNOSE : complete
148
132
 
149
- S_DIAGNOSE → S_FIX : root cause confirmed, !skip_fix
150
- S_DIAGNOSE → S_GENERALIZE : root cause confirmed, skip_fix, !skip_generalize
151
- S_DIAGNOSE → S_RECORD : root cause confirmed, skip_fix, skip_generalize
133
+ S_DIAGNOSE → S_FIX : confirmed, !skip_fix
134
+ S_DIAGNOSE → S_GENERALIZE : confirmed, skip_fix, !skip_generalize
135
+ S_DIAGNOSE → S_RECORD : confirmed, skip_fix, skip_generalize
152
136
  S_DIAGNOSE → S_DIAGNOSE : all hypotheses failed, retries < 3 → A_ESCALATE_DIAGNOSIS
153
- S_DIAGNOSE → S_RECORD : retries >= 3 → mark INCONCLUSIVE
137
+ S_DIAGNOSE → S_RECORD : retries >= 3 → INCONCLUSIVE
154
138
 
155
139
  S_FIX → S_CONFIRM : fix implemented
156
140
  S_CONFIRM → S_GENERALIZE : confirmed, !skip_generalize
@@ -160,26 +144,26 @@ S_CONFIRM → S_FIX : needs_rework
160
144
  S_GENERALIZE → S_DISCOVER : similar code found
161
145
  S_GENERALIZE → S_RECORD : no similar code
162
146
 
163
- S_DISCOVER → S_DIAGNOSE : new bug worth investigating → cross_phase_loops++
164
- S_DISCOVER → S_FIX : same-pattern bug, fix template applies, !skip_fix → cross_phase_loops++
165
- S_DISCOVER → S_RECORD : triage complete, remaining_actionable == 0
166
- S_DISCOVER → S_RECORD : loops >= max_loops → log each unfixed item with specific reason
147
+ S_DISCOVER → S_DIAGNOSE : new bug → cross_phase_loops++
148
+ S_DISCOVER → S_FIX : same-pattern bug + fix_template, !skip_fix → cross_phase_loops++
149
+ S_DISCOVER → S_RECORD : remaining_actionable == 0
150
+ S_DISCOVER → S_RECORD : loops >= max_loops → log per-item reasons
167
151
 
168
- S_RECORD → END : A_RECORD complete
152
+ S_RECORD → END : complete
169
153
  </transitions>
170
154
 
171
155
  <actions>
172
156
 
173
157
  ### A_INTAKE
174
- 1. Parse arguments, generate slug, create `SESSION_DIR`
175
- 2. Search: `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + Grep keywords
176
- 3. Derive `phase_goals[]` from flags (apply `skip_when`)
158
+ 1. Parse arguments, generate slug, create SESSION_DIR
159
+ 2. `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + Grep keywords
160
+ 3. Derive `phase_goals[]` from flags
177
161
  4. Write `session.json` + `understanding.md` §1, emit Goal Prompt
178
162
 
179
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): INTAKE — 目标解析与上下文加载"`
163
+ Commit: `"odyssey-debug({slug}): INTAKE — parse target and load context"`
180
164
 
181
165
  ### A_RESUME_SESSION
182
- Find latest session via Glob → read `session.json` → display summary → jump to `current_state`.
166
+ Glob latest session → read `session.json` → jump to `current_state`.
183
167
 
184
168
  ### A_ARCHAEOLOGY
185
169
  **Step 1 — Git archaeology (spawn_agents_on_csv, Wave 1):**
@@ -204,61 +188,48 @@ Merge results → evidence.ndjson (phase: "archaeology").
204
188
  - PURPOSE: Review recent modifications related to {issue}
205
189
  - EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
206
190
 
207
- Update §2.
208
-
209
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): ARCHAEOLOGY — git 考古分析"`
191
+ Update §2. Commit: `"odyssey-debug({slug}): ARCHAEOLOGY — git history analysis"`
210
192
 
211
193
  ### A_EXPLORE
212
- Skip if no enabled CLI tools (W006).
194
+ Skip if no CLI tools (W006).
213
195
 
214
196
  `maestro delegate --role explore --mode analysis` (`run_in_background: true`):
215
- - PURPOSE: Gather codebase evidence — call chains, recent changes, error gaps, similar patterns
197
+ - PURPOSE: Call chains, recent changes, error gaps, similar patterns
216
198
  - EXPECTED: JSON {call_chains, recent_changes, error_gaps, similar_patterns}
217
199
 
218
- Parse → write `explore.json` + evidence (phase: "explore"). Update §3. Mark G2 done.
219
-
220
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): EXPLORE — 代码探索完成"`
200
+ Write `explore.json` + evidence phase=explore. Update §3. Mark G2. Commit: `"odyssey-debug({slug}): EXPLORE — codebase exploration"`
221
201
 
222
202
  ### A_DIAGNOSE
223
- 1. Form hypotheses from evidence, ranked [HIGH]/[MEDIUM]/[LOW] → §4
224
- 2. Test each: design test execute → evidence (phase: "diagnosis")
225
- 3. Decision journal: ambiguity → evidence (phase: "decision"); Normal: request_user_input | `-y`: defer
226
- 4. Root cause confirmed → `session.json.root_cause` + §5. Mark G1 done.
203
+ 1. Hypotheses from evidence, ranked [HIGH]/[MEDIUM]/[LOW] → §4
204
+ 2. Test each → evidence phase=diagnosis
205
+ 3. Ambiguity → evidence phase=decision; Normal: request_user_input | `-y`: defer
206
+ 4. Confirmed → `session.json.root_cause` + §5. Mark G1.
227
207
 
228
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): DIAGNOSE — 根因确认"`
208
+ Commit: `"odyssey-debug({slug}): DIAGNOSE — root cause confirmed"`
229
209
 
230
210
  ### A_ESCALATE_DIAGNOSIS
231
- Increment `diagnosis_retries`. < 3: broaden via `maestro delegate --role analyze`, new hypotheses, return S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → auto INCONCLUSIVE → S_RECORD.
211
+ `diagnosis_retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
232
212
 
233
213
  ### A_FIX
234
214
  1. Present root cause + proposed fix. Normal: request_user_input | `-y`: auto proceed
235
- 2. Implement fix, record evidence (phase: "decision")
215
+ 2. Implement fix, evidence phase=decision
236
216
 
237
- 📌 **Auto-commit**: `git add -A && git commit -m "odyssey-debug({slug}): FIX — {修复摘要}"`
217
+ Commit: `"odyssey-debug({slug}): FIX — {summary}"`
238
218
 
239
219
  ### A_CONFIRM
240
- 1. Run covering tests (auto-detect framework)
241
- 2. CLI fix review via `maestro delegate --role review --mode analysis` (`run_in_background: true`):
220
+ 1. Run covering tests
221
+ 2. `maestro delegate --role review --mode analysis` (`run_in_background: true`):
242
222
  - EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk}
243
- 3. Write `session.json.confirmation`: `{test_result, cli_review, overall: "confirmed|needs_rework"}`
244
- 4. Update §6. `needs_rework` → S_FIX. `confirmed` → mark G3 done.
223
+ 3. `session.json.confirmation`: `{test_result, cli_review, overall: "confirmed|needs_rework"}`
224
+ 4. Update §6. `needs_rework` → S_FIX. `confirmed` → mark G3.
245
225
 
246
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): CONFIRM — 修复验证"`
226
+ Commit: `"odyssey-debug({slug}): CONFIRM — fix verified"`
247
227
 
248
228
  ### A_GENERALIZE
249
- Skip if `--skip-generalize`. Pattern 来源: root cause + fix
229
+ Skip if `--skip-generalize`. Pattern source: root cause + fix.
230
+ Base shared_actions for 3-layer extraction + cross-layer dedup + iterative deepening.
250
231
 
251
- **Step 1Multi-layer pattern extraction:**
252
-
253
- | Layer | Method | Example |
254
- |-------|--------|---------|
255
- | Syntax | Regex patterns (direct Grep) | `eval(`, missing `await`, unclosed resource |
256
- | Semantic | Anti-pattern description (Agent scan) | Unhandled async errors, unvalidated input |
257
- | Structural | Architecture-level similarity | Same import structure, missing override |
258
-
259
- Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template}]`
260
-
261
- **Step 2 — 4-agent scan (spawn_agents_on_csv, Wave 2):**
232
+ **Wave 24-agent scan (spawn_agents_on_csv):**
262
233
 
263
234
  Append Wave 2 rows to `tasks.csv`:
264
235
  ```csv
@@ -275,76 +246,49 @@ spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
275
246
  output_csv_path:"wave-2-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })
276
247
  ```
277
248
 
278
- **Step 3 Cross-layer dedup**: same file:line multi-layer boost confidence | single-layer → `needs_review` | historical fixed → `regression_risk`
279
-
280
- **Step 4 — Iterative deepening**: module ≥3 hits → targeted deep scan (max 1 round).
249
+ Update §7. Mark G4. Commit: `"odyssey-debug({slug}): GENERALIZE pattern scan complete"`
281
250
 
282
- **Step 5 — Quality Gate** (self-iteration).
251
+ ### A_DISCOVER, A_RECORD
252
+ Base shared_actions. Debug overrides:
253
+ - **A_DISCOVER** routes scan hits per csv_schema wave results. Commit: `"odyssey-debug({slug}): DISCOVER — triage complete"`
254
+ - **A_RECORD** learnings per Knowledge Persistence table
283
255
 
284
- **Step 6:** Write `session.json.generalization_stats`: `{patterns_extracted, total_hits, cross_layer_confirmed, regression_risks, by_layer, deepening_triggered}`. Update §7. Mark G4 done.
285
-
286
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): GENERALIZE — 泛化扫描完成"`
287
-
288
- ### A_DISCOVER
289
- 按 base A_DISCOVER 执行。Mark G5 done.
290
-
291
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): DISCOVER — 发现分类完成"`
292
-
293
- ### A_RECORD
294
- 1. Finalize `understanding.md` §9,按 Knowledge Persistence 表分类记录
295
- 2. Mark G6 done. Pending decisions: Normal → request_user_input | `-y` → skip (show deferred count)
296
- 3. 其余按 base A_RECORD 执行
297
- 4. **Completion summary**:
256
+ **Completion summary:**
298
257
  ```
299
258
  --- DEBUG ODYSSEY COMPLETE ---
300
259
  Issue: {issue}
301
260
  Root cause: {root_cause.hypothesis}
302
261
  Fix: {applied|skipped|inconclusive}
303
- Patterns: {patterns_extracted} ({by_layer} distribution)
304
- Scan hits: {total_hits} ({cross_layer_confirmed} cross-layer confirmed)
262
+ Patterns: {patterns_extracted} ({by_layer})
263
+ Scan hits: {total_hits} ({cross_layer_confirmed} confirmed)
305
264
  Issues: {N} created
306
265
  Decisions: {N} resolved, {M} pending, {K} deferred
307
- Learnings: {N} spec entries persisted
308
- Self-iter: {N} quality gate rounds across {M} stages
309
- Goals: {done}/{total} confirmed ({skipped} skipped)
266
+ Learnings: {N} persisted
267
+ Self-iter: {N} rounds across {M} stages
268
+ Goals: {done}/{total} ({skipped} skipped)
310
269
  ---
311
270
  ```
312
271
 
313
- 📌 **Auto-commit**: `git add understanding.md && git commit -m "odyssey-debug({slug}): RECORD — 会话总结与知识沉淀"`
314
-
315
272
  </actions>
316
273
 
317
274
  <appendix>
318
275
 
319
- ### Goal Prompt Template
276
+ ### `-y` debug-specific points
277
+
278
+ | Decision Point | Normal | `-y` |
279
+ |---------------|--------|------|
280
+ | A_DIAGNOSE ambiguity | request_user_input | deferred |
281
+ | A_ESCALATE 3-strike | request_user_input | INCONCLUSIVE |
282
+ | A_FIX direction | request_user_input | auto proceed |
320
283
 
321
- **时机守卫:仅在 A_INTAKE 完成后显示一次。** 机制见 base。
284
+ ### Goal Prompt convergence rules
322
285
 
323
286
  ```
324
- 📋 Debug Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件:
325
-
326
- /goal 完成以下目标:
327
- {for each G in phase_goals where status != "skipped":}
328
- - {G.id}: {G.goal} — 完成条件: {G.done_when}
329
- {end for}
330
- 穷尽迭代:直到根因确认(或明确 INCONCLUSIVE)且修复验证通过
331
- 且泛化扫描穷尽且 phase_goals_all_done=true 才停。
332
- 泛化发现的同类 bug 全部修复或创建 issue,不允许遗留。
333
- 遇到 phase=decision 的 pending 必须 request_user_input,不得自行 resolve。
287
+ Stop when root cause confirmed (or INCONCLUSIVE), fix verified,
288
+ generalization exhausted, phase_goals_all_done=true.
289
+ All sibling bugs fixed or issued — no leftovers.
334
290
  ```
335
291
 
336
- ### `-y` Auto-Confirm Behavior
337
-
338
- | Decision Point | Normal | `-y` mode |
339
- |---------------|--------|-----------|
340
- | A_DIAGNOSE ambiguity | request_user_input | `deferred`, best-effort continue |
341
- | A_ESCALATE 3-strike | request_user_input 3-way | auto INCONCLUSIVE |
342
- | A_FIX direction | request_user_input | auto proceed with suggested fix |
343
- | A_DISCOVER bug triage | request_user_input | auto create issue |
344
- | A_DISCOVER ambiguous | request_user_input batch | all `deferred` |
345
- | A_RECORD decisions | request_user_input per-item | skip, show deferred count |
346
- | A_RECORD goal audit | request_user_input 3-way | auto accept current state |
347
-
348
292
  </appendix>
349
293
 
350
294
  </state_machine>
@@ -352,33 +296,34 @@ Goals: {done}/{total} confirmed ({skipped} skipped)
352
296
  <error_codes>
353
297
  | Code | Severity | Condition | Recovery |
354
298
  |------|----------|-----------|----------|
355
- | E001 | error | No issue and no session to resume | Provide issue or use -c |
356
- | W001 | warning | No relevant git history | Proceed with limited context |
357
- | W002 | warning | All hypotheses inconclusive after 3 retries | INCONCLUSIVE |
358
- | W005 | warning | Pending decisions unresolved | Filter evidence.ndjson phase=decision |
359
- | W006 | warning | CLI exploration skipped (no tools) | Proceed without explore.json |
299
+ | E001 | error | No issue, no session | Provide issue or -c |
300
+ | E002 | error | Target path not found | Check path |
301
+ | W001 | warning | No relevant git history | Proceed |
302
+ | W002 | warning | 3 retries exhausted | INCONCLUSIVE |
303
+ | W005 | warning | Pending decisions | Filter evidence phase=decision |
304
+ | W006 | warning | No CLI tools | Skip explore |
360
305
  </error_codes>
361
306
 
362
307
  <success_criteria>
363
- - [ ] Session created with 4 output files, prior knowledge searched
364
- - [ ] Git archaeology + CLI change review → evidence phase=archaeology
308
+ - [ ] Session + 4 output files + prior knowledge searched
309
+ - [ ] Archaeology + CLI review → evidence phase=archaeology
365
310
  - [ ] CLI exploration → explore.json + evidence phase=explore
366
- - [ ] Hypotheses tested, root cause declared with evidence refs
367
- - [ ] understanding.md tracks all 9 sections progressively
368
- - [ ] Fix implemented + confirmed (unless --skip-fix)
369
- - [ ] Multi-layer generalization + scan (unless --skip-generalize)
370
- - [ ] Discoveries classified and routed; every unfixed finding individually justified
371
- - [ ] phase_goals derived, goal audit in A_RECORD, state resumable via -c
372
- - [ ] Completion summary with all stats
311
+ - [ ] Hypotheses tested, root cause with evidence refs
312
+ - [ ] understanding.md 9 sections progressive
313
+ - [ ] Fix + confirmed (unless --skip-fix)
314
+ - [ ] Generalization + scan (unless --skip-generalize)
315
+ - [ ] Discoveries classified; unfixed findings individually justified
316
+ - [ ] phase_goals + goal audit + resumable via -c
317
+ - [ ] Completion summary
373
318
  </success_criteria>
374
319
 
375
320
  <next_step_routing>
376
- | Condition | Next step |
377
- |-----------|-----------|
378
- | Issues from discoveries | `/manage-issue list --source debug-odyssey` |
379
- | Pattern worth documenting | `/learn-decompose <module>` |
380
- | Fix needs formal review | `/quality-review <phase>` |
381
- | Second opinion on root cause | `/learn-second-opinion <understanding.md>` |
321
+ | Condition | Next |
322
+ |-----------|------|
323
+ | Discovery issues | `/manage-issue list --source debug-odyssey` |
324
+ | Document pattern | `/learn-decompose <module>` |
325
+ | Formal review | `/quality-review <phase>` |
326
+ | Second opinion | `/learn-second-opinion <understanding.md>` |
382
327
  | Related question | `/learn-investigate "<question>"` |
383
- | Decisions still pending | Filter evidence.ndjson phase=decision status=pending |
328
+ | Pending decisions | Filter evidence phase=decision status=pending |
384
329
  </next_step_routing>