self-evolving-workflow 0.0.0-stage → 0.1.3

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 (173) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +90 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +479 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/common.d.ts +9 -0
  12. package/dist/common.js +42 -0
  13. package/dist/context-envelope.d.ts +59 -0
  14. package/dist/context-envelope.js +23 -0
  15. package/dist/host-adapters.d.ts +34 -0
  16. package/dist/host-adapters.js +151 -0
  17. package/dist/http.d.ts +3 -0
  18. package/dist/http.js +90 -0
  19. package/dist/index.d.ts +16 -0
  20. package/dist/index.js +13 -0
  21. package/dist/knowledge-cli.d.ts +183 -0
  22. package/dist/knowledge-cli.js +654 -0
  23. package/dist/knowledge-reads.d.ts +71 -0
  24. package/dist/knowledge-reads.js +193 -0
  25. package/dist/memory.d.ts +97 -0
  26. package/dist/memory.js +250 -0
  27. package/dist/retrospective.d.ts +57 -0
  28. package/dist/retrospective.js +248 -0
  29. package/dist/search.d.ts +36 -0
  30. package/dist/search.js +112 -0
  31. package/dist/skill-addition.d.ts +25 -0
  32. package/dist/skill-addition.js +89 -0
  33. package/dist/skill-design.d.ts +96 -0
  34. package/dist/skill-design.js +226 -0
  35. package/dist/skill-replay.d.ts +55 -0
  36. package/dist/skill-replay.js +451 -0
  37. package/dist/skill-route.d.ts +30 -0
  38. package/dist/skill-route.js +75 -0
  39. package/dist/transcript-evidence.d.ts +3 -0
  40. package/dist/transcript-evidence.js +58 -0
  41. package/dist/upstream/chunker.d.ts +24 -0
  42. package/dist/upstream/chunker.js +96 -0
  43. package/dist/upstream/file-protocol.d.ts +45 -0
  44. package/dist/upstream/file-protocol.js +117 -0
  45. package/dist/upstream/frontmatter.d.ts +47 -0
  46. package/dist/upstream/frontmatter.js +86 -0
  47. package/dist/upstream/graph-search.d.ts +33 -0
  48. package/dist/upstream/graph-search.js +67 -0
  49. package/dist/upstream/l1-extraction.d.ts +26 -0
  50. package/dist/upstream/l1-extraction.js +405 -0
  51. package/dist/upstream/llm.d.ts +8 -0
  52. package/dist/upstream/llm.js +1 -0
  53. package/dist/upstream/merge.d.ts +50 -0
  54. package/dist/upstream/merge.js +153 -0
  55. package/dist/upstream/prompts.d.ts +53 -0
  56. package/dist/upstream/prompts.js +185 -0
  57. package/dist/upstream/search-utils.d.ts +34 -0
  58. package/dist/upstream/search-utils.js +55 -0
  59. package/dist/upstream/slug.d.ts +26 -0
  60. package/dist/upstream/slug.js +103 -0
  61. package/dist/upstream/template.d.ts +29 -0
  62. package/dist/upstream/template.js +80 -0
  63. package/dist/upstream/tokenize.d.ts +4 -0
  64. package/dist/upstream/tokenize.js +29 -0
  65. package/dist/wiki-change.d.ts +76 -0
  66. package/dist/wiki-change.js +299 -0
  67. package/dist/wiki-entry.d.ts +26 -0
  68. package/dist/wiki-entry.js +93 -0
  69. package/dist/wiki-ingest.d.ts +12 -0
  70. package/dist/wiki-ingest.js +126 -0
  71. package/dist/wiki-migration.d.ts +16 -0
  72. package/dist/wiki-migration.js +268 -0
  73. package/dist/wiki-tokens.d.ts +1 -0
  74. package/dist/wiki-tokens.js +46 -0
  75. package/dist/wiki.d.ts +103 -0
  76. package/dist/wiki.js +330 -0
  77. package/dist/workflow-cli.d.ts +2 -0
  78. package/dist/workflow-cli.js +258 -0
  79. package/dist/workflow-install.d.ts +36 -0
  80. package/dist/workflow-install.js +148 -0
  81. package/dist/workflow-knowledge.d.ts +16 -0
  82. package/dist/workflow-knowledge.js +24 -0
  83. package/dist/workflow-mcp.d.ts +2 -0
  84. package/dist/workflow-mcp.js +144 -0
  85. package/dist/workflow-names.d.ts +4 -0
  86. package/dist/workflow-names.js +18 -0
  87. package/dist/workflow-runtime.d.ts +622 -0
  88. package/dist/workflow-runtime.js +627 -0
  89. package/dist/workflow-skills.d.ts +48 -0
  90. package/dist/workflow-skills.js +141 -0
  91. package/package.json +76 -4
  92. package/skills/ew-odyssey/SKILL.md +237 -0
  93. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  94. package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
  95. package/skills/ew-odyssey/references/odyssey-base.md +278 -0
  96. package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
  97. package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
  98. package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
  99. package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
  100. package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
  101. package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
  102. package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
  103. package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
  104. package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
  105. package/skills/ew-odyssey/references/odyssey-review.md +251 -0
  106. package/skills/ew-odyssey/references/odyssey-security.md +249 -0
  107. package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
  108. package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
  109. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
  110. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
  111. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
  112. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
  113. package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
  114. package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
  115. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
  116. package/skills/ew-orchestrate/SKILL.md +236 -0
  117. package/skills/ew-orchestrate/references/auto-policy.md +165 -0
  118. package/skills/ew-orchestrate/references/companion-route.md +52 -0
  119. package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
  120. package/skills/ew-orchestrate/references/goal.md +53 -0
  121. package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
  122. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
  123. package/skills/ew-orchestrate/references/planning.md +137 -0
  124. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
  125. package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
  126. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
  127. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
  128. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
  129. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
  130. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
  131. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
  132. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
  133. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
  134. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
  135. package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
  136. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
  137. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  138. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
  139. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
  140. package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
  141. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
  142. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
  143. package/skills/ew-skill-design/SKILL.md +28 -0
  144. package/skills/ew-skill-design/references/package-contract.md +28 -0
  145. package/skills/ew-skill-design/references/validation.md +7 -0
  146. package/skills/team-swarm/SKILL.md +231 -0
  147. package/skills/team-swarm/references/mcp-coordination.md +10 -0
  148. package/skills/team-swarm/roles/analyst/role.md +181 -0
  149. package/skills/team-swarm/roles/ant/role.md +149 -0
  150. package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
  151. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
  152. package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  153. package/skills/team-swarm/roles/coordinator/role.md +228 -0
  154. package/skills/team-swarm/roles/scorer/role.md +150 -0
  155. package/skills/team-swarm/scripts/aco.py +646 -0
  156. package/skills/team-swarm/scripts/pheromone.py +144 -0
  157. package/skills/team-swarm/scripts/scoring.py +111 -0
  158. package/skills/team-swarm/scripts/test_aco.py +606 -0
  159. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  160. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  161. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  162. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  163. package/skills/team-swarm/specs/swarm-protocol.md +123 -0
  164. package/skills/workflow-closeout/SKILL.md +10 -0
  165. package/skills/workflow-evolve/SKILL.md +79 -0
  166. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  167. package/skills/workflow-evolve/references/auto-loop.md +20 -0
  168. package/skills/workflow-evolve/references/history-review.md +14 -0
  169. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
  170. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  171. package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
  172. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  173. package/workflows/index.json +23 -0
@@ -0,0 +1,278 @@
1
+ <!-- session-mode: inherited -->
2
+
3
+ # Odyssey Shared Base
4
+
5
+ Shared by all Odyssey modes (debug, improve, planex, review, security, ui). Mode files own their front-half state machine, pattern source, category table, completion-summary format and error codes; everything below is single-source and MUST NOT be copied into a mode file.
6
+
7
+ <execution_discipline>
8
+
9
+ 1. **Phase auto-commit** — auto `git commit` after each phase
10
+ - Code changes + understanding.md → `git add` → `git commit -m "{mode}({slug}): {phase} — {summary}"`
11
+ - `outputs/session.json` / `outputs/evidence.ndjson` are workflow-owned formal artifacts (registered atomically by fenced `evolve run complete ... --advance`), excluded from phase commits
12
+
13
+ 2. **Confident edits only, but must attempt** — edit when confident; record decision only when human judgment truly needed
14
+ - Confident → edit + commit
15
+ - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`, no code change
16
+ - **Decision gate** — only these qualify: cross-module architecture tradeoffs needing human direction | business semantics ambiguity where fix may change intent | new dependency or breaking API required
17
+ - "Unsure how to fix", "Too large scope", "Pre-existing issue" are NOT valid decision reasons
18
+
19
+ 3. **Multi-CLI assist** — `evolve delegate` for cross-angle verification
20
+ - Different `--role` per phase (analyze / review / explore)
21
+ - All delegate calls `run_in_background: true`, wait for callback
22
+
23
+ 4. **Never abort for context exhaustion** — harness auto-compresses context; aborting due to "insufficient context" or "already ran N phases" is a discipline violation. Must complete through S_RECORD → END.
24
+
25
+ **Zero-residual:** Every finding must have an action (fix / issue / decision). "Report only" and "pre-existing skip" are forbidden.
26
+ </execution_discipline>
27
+
28
+ <shared_invariants>
29
+
30
+ These hold for every mode. Mode prepare files restate them as pre-flight guardrails on purpose — an invariant that is only reachable through a conditional ref is not a guardrail. Keep the per-mode statements **verbatim identical to the canonical text below**; this section is the single source of truth for the wording.
31
+
32
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
33
+ - **Thoroughness floor** — all 3 generalization layers (syntax/semantic/structural) must be attempted and logged. A single-layer quick grep does NOT satisfy it.
34
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
35
+ - **Per-item justification** — when `cross_phase_loops >= max_loops`, every unfixed finding needs its own reason. A blanket "pre-existing" is forbidden.
36
+
37
+ </shared_invariants>
38
+
39
+ <shared_schemas>
40
+
41
+ Artifact paths are declared in each mode's `prepare/ew-odyssey-<mode>.md` contract; the schemas below describe their content.
42
+
43
+ ### session.json standard fields
44
+
45
+ ```json
46
+ {
47
+ "session_id": "{mode}-odyssey-{YYYYMMDD-HHmmss}",
48
+ "current_state": "S_INTAKE",
49
+ "flags": { "skip_fix": false, "skip_generalize": false, "auto_confirm": false },
50
+ "phase_goals": [], "phase_goals_all_done": false,
51
+ "self_iteration_log": [],
52
+ "cross_phase_loops": 0, "max_loops": 5,
53
+ "created_at": "", "updated_at": ""
54
+ }
55
+ ```
56
+
57
+ Each mode adds its own fields (e.g. `issue`, `target`, `requirement`).
58
+
59
+ ### evidence.ndjson base schema
60
+
61
+ ```json
62
+ {"ts":"","phase":"","type":"","source":"","content":"","note":""}
63
+ ```
64
+
65
+ Each mode defines phase-specific extension fields (e.g. `hypothesis`, `severity`, `dimension`).
66
+
67
+ ### generalization_stats schema
68
+
69
+ ```json
70
+ {
71
+ "patterns_extracted": 0, "total_hits": 0,
72
+ "cross_layer_confirmed": 0, "regression_risks": 0,
73
+ "by_layer": {"syntax": 0, "semantic": 0, "structural": 0},
74
+ "deepening_triggered": false
75
+ }
76
+ ```
77
+
78
+ </shared_schemas>
79
+
80
+ <anti_stall>
81
+
82
+ ### progress_metrics fields
83
+
84
+ ```json
85
+ {
86
+ "progress_metrics": {
87
+ "phase_stats": {},
88
+ "stale_count": 0,
89
+ "last_productive_phase": "",
90
+ "convergence_trend": "unknown"
91
+ },
92
+ "directions_tried": []
93
+ }
94
+ ```
95
+
96
+ ### Progress Tracking
97
+
98
+ After each analytical phase:
99
+ 1. Count `new_findings` (deduplicated) and `repeated` (matching existing evidence)
100
+ 2. Write to `progress_metrics.phase_stats[state_name]`
101
+ 3. `new == 0` → `stale_count++`, `convergence_trend = "stalling"`
102
+ 4. `new > 0` → `stale_count = 0`, update `last_productive_phase`
103
+ 5. 2 consecutive phases with declining new → `convergence_trend = "diminishing"`
104
+
105
+ ### Direction Diversity
106
+
107
+ ```json
108
+ {
109
+ "phase": "S_DIAGNOSE", "round": 1,
110
+ "strategy_type": "scope_widen|perspective_shift|tool_switch|structural_pivot",
111
+ "strategy_desc": "expand search to utils/", "result": "2 new findings"
112
+ }
113
+ ```
114
+
115
+ **Dedup rule:** Check same-phase history before self-iteration → new strategy must differ in `strategy_type` or `strategy_desc` → all 4 types tried → force stale_count upgrade
116
+
117
+ ### Stall Escalation Ladder
118
+
119
+ | stale_count | Strategy |
120
+ |-------------|----------|
121
+ | 0 | Normal advance |
122
+ | 1 | **Shift perspective** — different CLI tool, reverse trace, manual read. Must differ from directions_tried |
123
+ | 2 | **Structural pivot** — redefine search dimensions, switch analysis framework, decompose sub-problems. Not parameter tuning |
124
+ | 3 | **Human escalation** — request_user_input / `-y` auto INCONCLUSIVE and advance |
125
+
126
+ ### /loop Heartbeat (optional, `--heartbeat`)
127
+
128
+ Suggest `/loop 270s`. Each phase updates `session.json.updated_at`. >15 min without update → alert + stale_count. 2 consecutive no-update → suggest `-c` resume.
129
+ </anti_stall>
130
+
131
+ <self_iteration>
132
+
133
+ ### Quality Gate
134
+
135
+ | Dimension | Sufficient | Insufficient |
136
+ |-----------|-----------|-------------|
137
+ | Coverage | All known related files/modules analyzed | Missed targets discoverable via grep/git log |
138
+ | Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
139
+ | Actionability | Each conclusion has concrete next action | "Consider reviewing" without action |
140
+
141
+ **Progress-aware iteration:**
142
+ - Phase complete → evaluate 3 dimensions + check `progress_metrics`
143
+ - Any insufficient AND `stale_count < 3` → re-enter with expansion strategy (must pass directions_tried dedup)
144
+ - Follow Stall Escalation Ladder for strategy selection
145
+
146
+ **Expansion strategies:**
147
+ - `scope_widen`: more directories, git log depth ×2, additional delegate angles
148
+ - `perspective_shift`: different CLI tool, reverse trace, manual reading
149
+ - `tool_switch`: switch to unused analysis tool
150
+ - `structural_pivot`: redefine problem framework, decompose sub-problems
151
+
152
+ **Exit:** all sufficient → advance | `stale_count >= 3` → log gaps, advance
153
+
154
+ **Log:** `evidence.ndjson {"phase":"self-iteration"}` + `session.json.self_iteration_log[]` + `directions_tried[]`
155
+ </self_iteration>
156
+
157
+ ## Shared Back-Half
158
+
159
+ `S_GENERALIZE → S_DISCOVER → S_RECORD → END` is identical across all modes. Mode files reference this section instead of restating it.
160
+
161
+ <shared_actions>
162
+
163
+ ### A_GENERALIZE
164
+
165
+ 3-layer pattern extraction → 4-agent concurrent scan → cross-layer dedup → iterative deepening.
166
+
167
+ **Pattern source:** specified by each mode's `## Generalize Source` (root cause / audit findings / implementation patterns).
168
+
169
+ **3-layer extraction:**
170
+
171
+ | Layer | Method | Example |
172
+ |-------|--------|---------|
173
+ | Syntax | Regex → Grep | `eval(`, missing `await`, inline styles |
174
+ | Semantic | Agent understands anti-pattern → scan | Unhandled async errors, missing validation |
175
+ | Structural | File/module structure similarity | Same import structure, missing override |
176
+
177
+ Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template, confidence}]`
178
+
179
+ **4-agent concurrent scan (single message):**
180
+
181
+ | Agent | Strategy | Scope |
182
+ |-------|----------|-------|
183
+ | Syntax grep | Grep regex | Full project |
184
+ | Semantic scan | Anti-pattern check | Related modules |
185
+ | Structural match | Structurally similar files | Full project |
186
+ | Historical grep | `git log -S` | Git history |
187
+
188
+ **Cross-layer dedup:** multi-layer hit → boost | single-layer → `needs_review` | historically fixed → `regression_risk`
189
+
190
+ **Iterative deepening:** module ≥3 hits → targeted deep scan (max 1 round)
191
+
192
+ **Persist:** understanding.md generalization section + `session.json.generalization_stats`
193
+
194
+ Zero hits after a full 3-layer scan is a warning, not a failure — mode files own that code (see Error Codes below).
195
+
196
+ Commit: `"...({slug}): GENERALIZE — generalization scan complete"`
197
+
198
+ ### A_DISCOVER
199
+
200
+ 1. **Triage** each hit ±10 lines context → classify `bug` / `risk` / `safe`
201
+ 2. **Route:**
202
+ - bug + fix_template applicable → immediate fix → back to S_FIX
203
+ - bug + needs cross-module decision or no fix_template → create issue (with fix suggestion + impact analysis)
204
+ - risk → assess if guard can be added directly; yes → fix; no → create issue
205
+ - safe → skip
206
+ Normal: request_user_input | `-y`: mode-specific, see each mode's `-y` decision table
207
+ 3. **Cross-phase loops:** `cross_phase_loops++`. `loops >= max_loops` → per-item justification required (see Shared Invariants)
208
+ 4. Append evidence + update understanding.md
209
+
210
+ Commit: `"...({slug}): DISCOVER — discovery triage complete"`
211
+
212
+ ### A_RECORD
213
+
214
+ 1. Finalize understanding.md final section — learnings structured by each mode's `## Knowledge Persistence` category table
215
+ 2. Mark record goal done. Pending decisions: Normal → request_user_input | `-y` → skip (show deferred count)
216
+ 3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`. Incomplete: Normal → request_user_input | `-y` → auto accept
217
+ 4. `current_state = "COMPLETED"`, emit completion summary (format defined by each mode)
218
+
219
+ Knowledge harvesting stages spec/knowhow candidates (never direct corpus writes) and is owned by `ref/finish-work.md` — do not restate its extraction or `archive.json` logic here. Staging happens BEFORE seal; promotion (sealed source + fresh receipt) is a separate post-seal step.
220
+
221
+ Commit: `"...({slug}): RECORD — summary and knowledge persistence"`
222
+
223
+ </shared_actions>
224
+
225
+ <shared_appendix>
226
+
227
+ ### Goal Prompt
228
+
229
+ **Timing guard: display ONCE after INTAKE completes. Never re-display at RECORD.**
230
+
231
+ ```
232
+ {Mode} Odyssey session created. Copy the /goal below to set termination criteria:
233
+
234
+ /goal Complete these goals:
235
+ {for each G in phase_goals where status != "skipped":}
236
+ - {G.id}: {G.goal} — done when: {G.done_when}
237
+ {end for}
238
+ {mode-specific convergence rules}
239
+ Pending phase=decision items must use request_user_input, never self-resolve.
240
+ ```
241
+
242
+ Continue execution after output, do not block.
243
+
244
+ ### `-y` generic rules
245
+
246
+ - Decision pending → best-effort continue, record `deferred`
247
+ - 3-strike escalation → auto INCONCLUSIVE
248
+ - Record pending → skip, show deferred count
249
+ - Record goal audit → auto accept
250
+
251
+ `deferred` items shown in completion summary; recoverable via `-c`. Discovery routing under `-y` is mode-specific — each mode lists it in its own `-y` decision table.
252
+
253
+ ### Phase Goal Lifecycle
254
+
255
+ `pending → done (confirmed=true)` | `pending → skipped (confirmed=true)` | `pending → failed (confirmed=false)`
256
+
257
+ `phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
258
+
259
+ ### Pre-load (optional, missing does not block)
260
+
261
+ | Layer | Command |
262
+ |-------|---------|
263
+ | Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` |
264
+ | Wiki search | `agent-memory wiki references "<keywords>"` (top 5) |
265
+ | Specs | `agent-memory wiki constraints --category <cat>` |
266
+ | Role knowledge | `agent-memory wiki references "<keywords>"` → `agent-memory wiki reference <id>` |
267
+ | Prior sessions | `evolve session list` |
268
+
269
+ ### Error Codes
270
+
271
+ **Code ownership:** `W0xx` warning codes are **mode-owned** — the same number means different things in different modes (e.g. `W003` is an archaeology failure in debug/review but a partial scan in security; `W004` is a zero-hit generalization in improve/security/ui). Never assume a warning code is shared. Only the two errors below are base-level.
272
+
273
+ | Code | Severity | Condition | Recovery |
274
+ |------|----------|-----------|----------|
275
+ | E003 | error | Resume requested but no session found | Start new |
276
+ | E004 | error | Delegate failed | Retry or proceed without |
277
+
278
+ </shared_appendix>
@@ -0,0 +1,305 @@
1
+ <!-- session-mode: inherited -->
2
+
3
+ # Workflow: Odyssey Debug (Codex)
4
+
5
+ Codex-adapted debug mode. Uses `spawn_agents_on_csv`, `request_user_input`, `update_plan`. Self-contained — no references to the Claude version.
6
+
7
+ ## State Chain
8
+
9
+ ```
10
+ S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_DIAGNOSE → S_FIX → S_CONFIRM → [back-half]
11
+ ```
12
+
13
+ Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared Codex phases](odyssey-base-codex.md)).
14
+
15
+ ---
16
+
17
+ ## Boundary
18
+
19
+ **In scope:** Single bug/issue full loop — symptom → root cause → fix → confirm → generalize.
20
+ **Out of scope:** Features → `--mode planex` | Quality review → `--mode review` | UI → `--mode ui` | Architecture → `/ew-orchestrate --goal plan`
21
+
22
+ ---
23
+
24
+ ## `--template <name>`
25
+
26
+ | Template | Strategy | Use case |
27
+ |----------|----------|----------|
28
+ | `performance` | profiling → hot path → allocation → cache | Performance degradation |
29
+ | `memory-leak` | heap snapshot → retention chain → lifecycle | Memory leaks |
30
+ | `race-condition` | timeline → concurrent access → lock analysis | Race conditions |
31
+ | `regression` | git bisect → diff analysis → boundary check | Regressions |
32
+ | `crash` | stack trace → null chain → error propagation | Crashes / exceptions |
33
+
34
+ ---
35
+
36
+ ## Target Resolution
37
+
38
+ Issue description parsed from `<intent>`.
39
+
40
+ ---
41
+
42
+ ## Session Fields
43
+
44
+ ```json
45
+ { "issue": "", "diagnosis_retries": 0, "root_cause": null, "confirmation": null,
46
+ "patterns": [], "generalization_stats": null }
47
+ ```
48
+
49
+ ---
50
+
51
+ ## evidence.ndjson Phases
52
+
53
+ `archaeology|explore|diagnosis|discovery|decision|self-iteration`
54
+
55
+ - `archaeology`: `sha`, `author`, `date`, `message`, `relevance`
56
+ - `explore`: `category` (call_chain|recent_change|error_gap|similar_pattern), `detail`
57
+ - `diagnosis`: `hypothesis`, `result` (confirmed|disproved|inconclusive)
58
+ - `discovery`: `file`, `line`, `classification` (safe|risk|bug), `action` (fix|issue|decision|skip)
59
+ - `decision`: `question`, `options`, `context`, `status` (pending|resolved|deferred), `resolution`
60
+ - `self-iteration`: `stage`, `round`, `assessment`, `expansion`
61
+
62
+ ---
63
+
64
+ ## explore.json
65
+
66
+ ```json
67
+ {"call_chains": [], "recent_changes": [], "error_gaps": [], "similar_patterns": [], "cli_tool": "", "timestamp": ""}
68
+ ```
69
+
70
+ ---
71
+
72
+ ## phase_goals[]
73
+
74
+ | ID | Goal | done_when | phase | skip_when |
75
+ |----|------|-----------|-------|-----------|
76
+ | G1 | Root cause identified | phase=diagnosis result=confirmed | S_DIAGNOSE | — |
77
+ | G2 | Explore context gathered | explore.json ≥1 category | S_EXPLORE | — |
78
+ | G3 | Fix applied and confirmed | confirmation.overall == confirmed | S_CONFIRM | skip_fix |
79
+ | G4 | Pattern generalized | patterns[] ≥1 entry | S_GENERALIZE | skip_generalize |
80
+ | G5 | Discoveries triaged | all scan hits classified | S_DISCOVER | skip_generalize |
81
+ | G6 | Learnings persisted | spec entries created OR none actionable | S_RECORD | — |
82
+
83
+ ---
84
+
85
+ ## understanding.md — 9 Sections
86
+
87
+ 1. Issue & Scope
88
+ 2. Archaeology
89
+ 3. Exploration
90
+ 4. Hypotheses
91
+ 5. Root Cause
92
+ 6. Fix & Confirmation
93
+ 7. Generalization
94
+ 8. Discoveries
95
+ 9. Learnings
96
+
97
+ ---
98
+
99
+ ## State Machine — Transitions
100
+
101
+ ```
102
+ S_ARCHAEOLOGY → S_EXPLORE : complete
103
+ S_EXPLORE → S_DIAGNOSE : complete
104
+ S_DIAGNOSE → S_FIX : confirmed, !skip_fix
105
+ S_DIAGNOSE → S_GENERALIZE : confirmed, skip_fix, !skip_generalize
106
+ S_DIAGNOSE → S_RECORD : confirmed, skip_fix, skip_generalize
107
+ S_DIAGNOSE → S_DIAGNOSE : all hypotheses failed, retries < 3 → A_ESCALATE_DIAGNOSIS
108
+ S_DIAGNOSE → S_RECORD : retries >= 3 → INCONCLUSIVE
109
+ S_FIX → S_CONFIRM : fix implemented
110
+ S_CONFIRM → S_GENERALIZE : confirmed, !skip_generalize
111
+ S_CONFIRM → S_RECORD : confirmed, skip_generalize
112
+ S_CONFIRM → S_FIX : needs_rework
113
+ ```
114
+
115
+ ---
116
+
117
+ ## Actions
118
+
119
+ ### A_ARCHAEOLOGY
120
+
121
+ 2 parallel agents via CSV wave.
122
+
123
+ Generate `archaeology.csv`:
124
+
125
+ ```csv
126
+ id,title,description,files,status,findings,error
127
+ "timeline","Git Timeline","Run git log --oneline -20 -- {files} to gather recent commit timeline for the affected files","{files}","","",""
128
+ "blame","Git Blame","Run git blame -L {region} on top 3 affected files to identify who changed the relevant code regions","{files}","","",""
129
+ ```
130
+
131
+ ```javascript
132
+ spawn_agents_on_csv({
133
+ csv_path: `${sessionFolder}/archaeology.csv`,
134
+ id_column: "id",
135
+ instruction: "You are investigating a bug. Read the 'description' column for your task. Execute the git commands described and analyze the results for relevance to the issue: {issue}. Write findings as a JSON array of relevant commits/changes with risk assessment.",
136
+ max_concurrency: 2,
137
+ max_runtime_seconds: 3600,
138
+ output_csv_path: `${sessionFolder}/archaeology-results.csv`,
139
+ output_schema: { id, status: ["completed"|"failed"], findings, error }
140
+ })
141
+ ```
142
+
143
+ Evidence phase=archaeology.
144
+
145
+ `evolve delegate --role analyze --mode analysis` (`run_in_background: true`):
146
+ - PURPOSE: review recent modifications related to {issue}
147
+ - EXPECTED: JSON `[{commit_sha, risk_level, analysis, could_cause_issue, explanation}]`
148
+
149
+ Update understanding.md §2 (Archaeology).
150
+
151
+ If an archaeology agent fails, log W003 and proceed with available results.
152
+
153
+ ### A_EXPLORE
154
+
155
+ Skip if no CLI tools (W006).
156
+
157
+ `evolve delegate --role explore --mode analysis` (`run_in_background: true`):
158
+ - PURPOSE: call chains, recent changes, error gaps, similar patterns
159
+ - EXPECTED: JSON `{call_chains, recent_changes, error_gaps, similar_patterns}`
160
+
161
+ Write `explore.json` + evidence phase=explore. Update understanding.md §3 (Exploration). Mark G2. `update_plan`(G2 → completed)
162
+
163
+ **GATE: discovery-complete** — archaeology/explore evidence logged, understanding.md §2-§3 updated, G2 marked (W003 partial / W006 skip acceptable).
164
+
165
+ ### A_DIAGNOSE
166
+
167
+ 1. Generate hypotheses from evidence, ranked [HIGH]/[MEDIUM]/[LOW] → understanding.md §4.
168
+ 2. Test each hypothesis → evidence phase=diagnosis.
169
+ 3. Ambiguity → evidence phase=decision:
170
+ - Normal: `request_user_input`
171
+ - `-y`: defer
172
+ 4. Confirmed → `session.json.root_cause` + understanding.md §5 (Root Cause). Mark G1. `update_plan`(G1 → completed)
173
+
174
+ **GATE: diagnosis-confirmed** — all hypotheses tested with evidence, root cause confirmed with reproduction or code/log evidence (or INCONCLUSIVE after 3-strike), understanding.md §4-§5 written. Zero hypotheses tested is BLOCKED.
175
+
176
+ ### A_ESCALATE_DIAGNOSIS
177
+
178
+ `diagnosis_retries++`.
179
+
180
+ - **retries < 3**: `evolve delegate --role analyze`, generate new hypotheses, → S_DIAGNOSE.
181
+ - **retries >= 3**:
182
+ - Normal: `request_user_input`
183
+ - `-y`: INCONCLUSIVE → S_RECORD
184
+
185
+ ### A_FIX
186
+
187
+ 1. Present root cause + proposed fix.
188
+ - Normal: `request_user_input`
189
+ - `-y`: auto proceed
190
+ 2. Implement fix, evidence phase=decision.
191
+
192
+ ### A_CONFIRM
193
+
194
+ 1. Run covering tests.
195
+ 2. `evolve delegate --role review --mode analysis` (`run_in_background: true`):
196
+ - EXPECTED: JSON `{verdict, findings [{severity, description, suggestion}], regression_risk}`
197
+ 3. `session.json.confirmation`:
198
+ ```json
199
+ {"test_result": "", "cli_review": {}, "overall": "confirmed|needs_rework"}
200
+ ```
201
+ 4. Update understanding.md §6 (Fix & Confirmation).
202
+ - `needs_rework` → S_FIX
203
+ - `confirmed` → mark G3. `update_plan`(G3 → completed)
204
+
205
+ **GATE: fix-confirmed** — fix implemented and tests pass, CLI review done, `confirmation.overall` set, understanding.md §6 written, G3 marked. `needs_rework` routes back to FIX; skippable only when `skip_fix == true`.
206
+
207
+ ---
208
+
209
+ ## Generalize Source
210
+
211
+ Confirmed root cause + applied fix.
212
+
213
+ **Thoroughness floor:** ALL 3 layers (syntax/semantic/structural) must be attempted and logged.
214
+
215
+ **Discover routing:** `bug` → back to S_FIX; new bug → S_DIAGNOSE.
216
+
217
+ ---
218
+
219
+ ## Knowledge Persistence (§9)
220
+
221
+ Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
222
+
223
+
224
+ | Category | Content | Follow-up |
225
+ |----------|---------|-----------|
226
+ | Recurring root cause pattern | Type + triggers + fix + detection | `stage spec → debug` |
227
+ | Non-obvious workaround | Problem + steps + why obvious fix fails | `stage spec → learning` |
228
+ | Architecture boundary violation | Violation + correct boundary + verification | `stage spec → arch` |
229
+ | Reusable generalization pattern | Signature + risk + fix template + scope | `stage spec → coding` |
230
+
231
+ ---
232
+
233
+ ## Completion Summary
234
+
235
+ ```
236
+ --- DEBUG ODYSSEY COMPLETE ---
237
+ Issue: {issue}
238
+ Root cause: {root_cause.hypothesis}
239
+ Fix: {applied|skipped|inconclusive}
240
+ Patterns: {patterns_extracted} ({by_layer})
241
+ Scan hits: {total_hits} ({cross_layer_confirmed} confirmed)
242
+ Issues: {N} created
243
+ Decisions: {N} resolved, {M} pending, {K} deferred
244
+ Learnings: {N} persisted
245
+ Self-iter: {N} rounds across {M} stages
246
+ Goals: {done}/{total} ({skipped} skipped)
247
+ ---
248
+ ```
249
+
250
+ ---
251
+
252
+ ## `-y` Decision Points
253
+
254
+ | Decision Point | Normal | `-y` |
255
+ |---------------|--------|------|
256
+ | A_DIAGNOSE ambiguity | `request_user_input` | deferred |
257
+ | A_ESCALATE 3-strike | `request_user_input` | INCONCLUSIVE |
258
+ | A_FIX direction | `request_user_input` | auto proceed |
259
+
260
+ ---
261
+
262
+ ## Mode-Specific Phase Gates
263
+
264
+ - **Discovery gate** (ARCHAEOLOGY/EXPLORE): evidence for the phase logged, understanding.md updated, discovery goal marked. Archaeology partial via W003 acceptable; explore W006 skip acceptable.
265
+ - **Audit gate** (DIAGNOSE): all hypotheses tested or confirmed, findings merged with severity classification. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
266
+ - **FIX gate:** current severity tier fully addressed. Per-fix evidence phase=fix logged. Auto-commit per tier.
267
+ - **CONFIRM gate:** tests pass; `remaining_actionable == 0` and new findings == 0; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
268
+
269
+ ---
270
+
271
+ ## Error Codes (debug-specific)
272
+
273
+ | Code | Severity | Condition | Recovery |
274
+ |------|----------|-----------|----------|
275
+ | E001 | error | No issue, no session | Provide issue or -c |
276
+ | W003 | warning | Archaeology agent or delegate failure | Proceed with available results |
277
+ | W006 | warning | No CLI tools | Skip explore |
278
+
279
+ ---
280
+
281
+ ## Success Criteria (debug-specific)
282
+
283
+ - [ ] Session + 4 output files + prior knowledge searched
284
+ - [ ] Archaeology + CLI review → evidence
285
+ - [ ] CLI exploration → explore.json
286
+ - [ ] Hypotheses tested, root cause with evidence refs
287
+ - [ ] understanding.md 9 sections progressive
288
+ - [ ] Fix + confirmed (unless --skip-fix)
289
+ - [ ] Generalization + scan (unless --skip-generalize)
290
+ - [ ] Discoveries classified; unfixed findings individually justified
291
+ - [ ] phase_goals + goal audit + resumable via -c
292
+ - [ ] Completion summary
293
+
294
+ ---
295
+
296
+ ## Next Step Routing (debug-specific)
297
+
298
+ | Condition | Next |
299
+ |-----------|------|
300
+ | Discovery issues | `Open the follow-up findings in the project issue tracker` |
301
+ | Document pattern | `Review the module and stage the reusable method via Agent Memory closeout` |
302
+ | Formal review | `$ew-odyssey <changed-files> --mode review` |
303
+ | Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
304
+ | Related question | `Use an Evolve analyze step for the question` |
305
+ | Pending decisions | Filter evidence phase=decision status=pending |