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,248 @@
1
+ ---
2
+ name: ew-odyssey-improve
3
+ prepare: odyssey-improve
4
+ session-mode: inherited
5
+ ---
6
+
7
+ # Workflow: Odyssey Improve
8
+
9
+ 6-dimension runtime quality improvement — performance/security/architecture/reliability/observability/maintainability audit → diagnose → fix → generalize.
10
+
11
+ ---
12
+
13
+ ## State Chain
14
+
15
+ ```
16
+ S_INTAKE → S_SURVEY → S_AUDIT → S_DIAGNOSE → S_FIX → S_VERIFY → [back-half]
17
+ ```
18
+
19
+ Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared phases](odyssey-base.md) §Shared Back-Half).
20
+
21
+ ---
22
+
23
+ ## Boundary
24
+
25
+ **In scope:** Runtime quality improvement — performance/security/architecture/reliability/observability/maintainability audit → diagnose → fix → generalize. **Out of scope:** UI visual → `--mode ui` | New features → `--mode planex` | Single bug → `--mode debug` | Style review → `--mode review`. Zero-residual applies.
26
+
27
+ ---
28
+
29
+ ## Context
30
+
31
+ ### Target Resolution
32
+
33
+ | Input | Resolution |
34
+ |-------|-----------|
35
+ | Module/dir path | Audit that module |
36
+ | `HEAD` / `staged` | Review changes in diff |
37
+ | Feature area keyword | Resolve to related files |
38
+ | `--all` | Full project scan (use with caution) |
39
+
40
+ ### Dimensions (6)
41
+
42
+ 1. **performance** — hot paths, N+1, memory allocation, cache efficiency, bundle size, lazy loading
43
+ 2. **security** — OWASP Top 10, injection, auth bypass, data exposure, dependency vulns, secrets
44
+ 3. **architecture** — layer violations, circular deps, coupling, interface contracts, SRP
45
+ 4. **reliability** — error handling gaps, retry, timeout, graceful degradation, resource cleanup
46
+ 5. **observability** — logging coverage, metric gaps, trace propagation, error reporting, health checks
47
+ 6. **maintainability** — cyclomatic complexity, dead code, test coverage gaps, doc debt
48
+
49
+ ### Session Fields
50
+
51
+ ```json
52
+ { "target": "", "dimensions": [], "baseline_metrics": {},
53
+ "audit_result": {}, "diagnoses": [], "confirmation": null,
54
+ "generalization_stats": null }
55
+ ```
56
+
57
+ ### evidence.ndjson Phases
58
+
59
+ `survey|audit|diagnosis|fix|discovery|decision|self-iteration`
60
+
61
+ - `survey`: `category` (dependency|complexity|coverage|error_pattern), `detail`
62
+ - `audit`: `dimension`, `severity`, `measurement`
63
+ - `diagnosis`: `finding_ref`, `hypothesis`, `result`, `root_cause`
64
+ - `fix`: `finding_ref`, `change_summary`, `risk`
65
+
66
+ ### phase_goals[]
67
+
68
+ | ID | Goal | Phase | skip_when |
69
+ |----|------|-------|-----------|
70
+ | G1 | Survey completed | S_SURVEY | — |
71
+ | G2 | Audit completed | S_AUDIT | — |
72
+ | G3 | Diagnosis completed | S_DIAGNOSE | — |
73
+ | G4 | Zero remaining: all findings fixed and verified | S_VERIFY | skip_fix |
74
+ | G5 | Pattern generalized | S_GENERALIZE | skip_generalize |
75
+ | G6 | Discoveries triaged | S_DISCOVER | skip_generalize |
76
+ | G7 | Learnings persisted | S_RECORD | — |
77
+
78
+ ### understanding.md — 9 Sections
79
+
80
+ 1. Target & Baseline
81
+ 2. Current State Survey
82
+ 3. Audit Findings
83
+ 4. Root Cause Diagnosis
84
+ 5. Fix & Verification
85
+ 6. Generalization
86
+ 7. Discoveries
87
+ 8. Improvement Metrics (before/after)
88
+ 9. Engineering Learnings
89
+
90
+ ---
91
+
92
+ ## State Machine
93
+
94
+ ### Transitions
95
+
96
+ ```
97
+ S_SURVEY → S_AUDIT : complete
98
+ S_AUDIT → S_DIAGNOSE : critical/high findings exist
99
+ S_AUDIT → S_GENERALIZE : no critical/high, !skip_generalize
100
+ S_AUDIT → S_RECORD : no findings OR skip_generalize
101
+ S_DIAGNOSE → S_FIX : root causes identified, !skip_fix
102
+ S_DIAGNOSE → S_GENERALIZE : root causes identified, skip_fix, !skip_generalize
103
+ S_DIAGNOSE → S_RECORD : root causes identified, skip_fix, skip_generalize
104
+ S_DIAGNOSE → S_DIAGNOSE : hypotheses failed, retries < 3 → A_ESCALATE_DIAGNOSIS
105
+ S_DIAGNOSE → S_RECORD : retries >= 3 → INCONCLUSIVE
106
+ S_FIX → S_VERIFY : fix implemented
107
+ S_VERIFY → S_GENERALIZE : verified, !skip_generalize
108
+ S_VERIFY → S_RECORD : verified, skip_generalize
109
+ S_VERIFY → S_FIX : needs_rework
110
+ ```
111
+
112
+ ### Actions
113
+
114
+ **A_INTAKE extra** — Baseline capture: record current metrics (test pass rate, bundle size, dependency count, complexity hotspots) to `session.json.baseline_metrics`.
115
+
116
+ **A_SURVEY** — (1) Dependency audit (package.json/lock), complexity scan (size/nesting), test coverage map, error handling scan (empty catch, unhandled promise). (2) CLI-assisted (optional): `evolve delegate --role analyze --mode analysis` for dependency health / complexity hotspots / coverage gaps / error patterns (`run_in_background: true`). (3) Evidence phase=survey. Update §2. Mark G1.
117
+
118
+ Commit: `"odyssey-improve({slug}): SURVEY — current state survey complete"`
119
+
120
+ **A_AUDIT** — Spawn 6 parallel Agents (one per dimension, or `--dimensions` subset). Each returns `[{title, severity, dimension, file, line, description, suggestion, measurement}]`. Merge → evidence phase=audit. Write `session.json.audit_result`. Update §3 (findings by dimension + severity matrix). Mark G2.
121
+
122
+ **GATE: all-dimensions-audited** — all 6 dimensions (or `--dimensions` subset) completed with structured findings, merged into severity matrix, evidence phase=audit logged per dimension. Zero dimensions reviewed is BLOCKED (W002 partial from agent failure is a warning).
123
+
124
+ Commit: `"odyssey-improve({slug}): AUDIT — dimension audit complete"`
125
+
126
+ **A_DIAGNOSE** — Root cause analysis for critical/high findings — don't fix symptoms. (1) Group by dimension, prioritize by severity; for each: hypothesis → trace code path + git history → evidence phase=diagnosis. (2) Ambiguity → evidence phase=decision; Normal: request_user_input | `-y`: defer. (3) CLI-assisted for complex findings (`run_in_background: true`). (4) Write `session.json.diagnoses[]`. Update §4. Mark G3.
127
+
128
+ Commit: `"odyssey-improve({slug}): DIAGNOSE — root cause analysis complete"`
129
+
130
+ **A_ESCALATE_DIAGNOSIS** — `retries++`. < 3: `evolve delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
131
+
132
+ **A_FIX** — (1) Exhaustive fix: ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify **current tier's dimension only** (not all dimensions); new findings at same or higher severity append to current tier. Cross-dimension regression checks run once at S_VERIFY after all tiers. **No partial-tier advancement** — each tier fully addressed (fixed or individually classified) before advancing; blanket "pre-existing" skip forbidden. (2) For each fix: implement → **run tests covering the modified area immediately** → evidence phase=fix. **Incremental verification** — each discrete fix step verified before proceeding; NEVER batch unrelated changes. **Rollback safety** — if tests fail after a fix step, revert that specific change (`git checkout -- {file}`) before attempting alternatives; NEVER proceed with failing tests. **Behavioral equivalence** — fixes MUST preserve existing behavior; no API changes, no new functionality. Beneficial changes discovered during fixing → evidence phase=decision as recommendations, NOT applied. **Scope lock** — once tier plan confirmed, no scope expansion without re-confirmation. (3) Normal: request_user_input per-fix | `-y`: auto-proceed, record `deferred`.
133
+
134
+ Commit: `"odyssey-improve({slug}): FIX — {dimension} {tier} tier addressed"`
135
+
136
+ **A_VERIFY** — (1) Run tests covering modified areas. (2) Re-capture metrics, compare with `baseline_metrics`. (3) CLI-assisted: `evolve delegate --role review --mode analysis` (`run_in_background: true`). (4) `needs_rework` → S_FIX; `verified` → mark G4. (5) Write `confirmation`. Update §5 (before/after metrics table).
137
+
138
+ **GATE: zero-remaining-verified** — every diagnosed finding is fixed and verified, individually classified (issue / decision), or skipped via `--skip-fix`; tests pass over modified areas; metrics re-captured and compared against `baseline_metrics`; no unaddressed actionable findings; before/after table written to understanding.md §8.
139
+
140
+ Commit: `"odyssey-improve({slug}): VERIFY — fix verification complete"`
141
+
142
+ ---
143
+
144
+ ## Generalize Source
145
+
146
+ Diagnosed root causes + applied fixes across all dimensions. **Discover routing:** `bug` → S_FIX; new critical → S_DIAGNOSE.
147
+
148
+ ---
149
+
150
+ ## Knowledge Persistence (§9)
151
+
152
+ Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
153
+
154
+
155
+ A_RECORD extra: §8 improvement metrics — re-capture and build before/after comparison table from `baseline_metrics` vs current.
156
+
157
+ | Category | Content | Follow-up |
158
+ |----------|---------|-----------|
159
+ | Performance pattern | Bottleneck type + fix approach + measurement | `stage spec → coding` |
160
+ | Security rule | Vulnerability class + fix + prevention | `stage spec → debug` |
161
+ | Architecture constraint | Violation + correct boundary + check | `stage spec → arch` |
162
+ | Reliability pattern | Failure mode + handling strategy + verification | `stage spec → coding` |
163
+
164
+ ---
165
+
166
+ ## Completion Summary
167
+
168
+ ```
169
+ --- IMPROVE ODYSSEY COMPLETE ---
170
+ Target: {target}
171
+ Dimensions: {dimensions}
172
+ Findings: {critical}C / {high}H / {medium}M / {low}L
173
+ Diagnosed: {count}
174
+ Fixed: {count} ({verified} verified)
175
+ Metrics: {improved} improved / {regressed} regressed
176
+ Patterns: {count} ({by_layer})
177
+ Scan hits: {total} ({cross_layer_confirmed} confirmed)
178
+ Issues: {N} created
179
+ Decisions: {N} resolved, {M} pending, {K} deferred
180
+ Learnings: {N} persisted
181
+ Self-iter: {N} rounds across {M} stages
182
+ Cross-loops: {N}
183
+ Goals: {done}/{total} ({skipped} skipped)
184
+ ---
185
+ ```
186
+
187
+ ---
188
+
189
+ ## Mode `-y` Points
190
+
191
+ | Decision Point | Normal | `-y` |
192
+ |---------------|--------|------|
193
+ | A_FIX confirmation | request_user_input | auto-proceed `deferred` |
194
+ | A_DIAGNOSE ambiguity | request_user_input | best-effort `deferred` |
195
+ | A_ESCALATE 3-strike | request_user_input | auto INCONCLUSIVE |
196
+ | A_DISCOVER routing | request_user_input | auto create issue |
197
+ | Ambiguous items | request_user_input | all `deferred` |
198
+
199
+ ---
200
+
201
+ ## Phase Gates
202
+
203
+ - **Discovery gate** (SURVEY): evidence for the phase logged, understanding.md updated. Survey requires all scan types attempted.
204
+ - **Audit gate** (DIAGNOSE): all dimension agents completed, findings merged with severity classification. Zero dimensions reviewed is BLOCKED (W002 partial allowed).
205
+ - **FIX gate:** current severity tier fully addressed. Per-fix evidence phase=fix logged. **Per-change test verification** — each fix step runs tests before proceeding. **Rollback on failure** — failed fix reverted immediately. **Behavioral equivalence** — no API/behavior changes; beneficial changes logged as recommendations only. Auto-commit per tier. No partial-tier advancement.
206
+ - **VERIFY gate:** tests pass; metrics re-captured; confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
207
+
208
+ ---
209
+
210
+ ## Error Codes
211
+
212
+ | Code | Severity | Condition | Recovery |
213
+ |------|----------|-----------|----------|
214
+ | E001 | error | No target provided | Provide target or -c |
215
+ | E002 | error | Target path not found | Check path |
216
+ | W001 | warning | No dependency manifest / no test coverage tool | Proceed with defaults |
217
+ | W002 | warning | Some dimension agents failed | Partial coverage accepted |
218
+ | W004 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD |
219
+ | W005 | warning | Pending decisions | Filter evidence phase=decision |
220
+
221
+ ---
222
+
223
+ ## Success Criteria
224
+
225
+ - [ ] Target resolved; session + output files created; baseline metrics captured
226
+ - [ ] Survey completed with all scan types attempted (dependency, complexity, coverage, error handling)
227
+ - [ ] 6-dimension audit completed with structured findings + severity matrix
228
+ - [ ] understanding.md sections written progressively (§1–§9)
229
+ - [ ] Fix + verify (unless --skip-fix); zero-residual — every finding has concrete action
230
+ - [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
231
+ - [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
232
+ - [ ] §8 improvement metrics: before/after comparison table from baseline_metrics
233
+ - [ ] Session resumable via -c; completion summary emitted
234
+
235
+ ---
236
+
237
+ ## Next Step Routing
238
+
239
+ | Condition | Next |
240
+ |-----------|------|
241
+ | Discovery issues created | `Open the follow-up findings in the project issue tracker` |
242
+ | Deeper debug needed | `/ew-odyssey <finding> --mode debug` |
243
+ | Formal review of changes | `/ew-odyssey <changed-files> --mode review` |
244
+ | UI-related findings | `/ew-odyssey <component> --mode ui` |
245
+ | Document pattern | `Review the module and stage the reusable method via Agent Memory closeout` |
246
+ | Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
247
+ | Design/perf/arch pattern to persist | `stage spec → coding|arch` |
248
+ | Pending decisions | Filter evidence phase=decision status=pending |
@@ -0,0 +1,352 @@
1
+ <!-- session-mode: inherited -->
2
+
3
+ # Workflow: Odyssey Planex (Codex — CSV Wave)
4
+
5
+ Single requirement delivery loop — requirement parsing → acceptance criteria → plan → execute → verify → generalize.
6
+
7
+ ---
8
+
9
+ ## State Chain
10
+
11
+ ```
12
+ S_INTAKE → S_PLAN → S_EXECUTE → S_VERIFY → S_FIX → [back-half]
13
+ ```
14
+
15
+ FIX↔VERIFY loop until all criteria pass. Back-half: `S_GENERALIZE → S_DISCOVER → S_RECORD → END` (see [shared phases](odyssey-base.md) §Shared Back-Half).
16
+
17
+ ---
18
+
19
+ ## Boundary
20
+
21
+ **In scope:** Single requirement delivery loop — requirement parsing → all acceptance criteria passing + generalization.
22
+ **Out of scope:** Multi-requirement orchestration → `/ew-orchestrate --goal roadmap` | Deep debugging → `--mode debug` | Code review → `--mode review` | UI optimization → `--mode ui`
23
+
24
+ ---
25
+
26
+ ## Context
27
+
28
+ ### `--template <name>`
29
+
30
+ | Template | Criteria pattern | Use case |
31
+ |----------|-----------------|----------|
32
+ | `feature` | User story acceptance + boundary tests + UI verification | New feature |
33
+ | `bugfix` | Regression tests + root cause confirmation + boundary coverage | Bug fix |
34
+ | `refactor` | Behavior preservation + performance baseline + API compatibility | Refactoring |
35
+ | `migration` | Data consistency + rollback verification + performance comparison | Data/API migration |
36
+ | `api-endpoint` | Request/response contract + error handling + permission checks | API development |
37
+
38
+ ### Target Resolution
39
+
40
+ Requirement parsed from `<intent>`.
41
+
42
+ ### Session Fields
43
+
44
+ ```json
45
+ { "requirement": "",
46
+ "acceptance_criteria": [{"id":"AC1","criterion":"","verify_method":"test|grep|cli-review|manual","status":"pending","evidence":"","passed_at":null}],
47
+ "plan": {"tasks":[{"id":"T1","title":"","description":"","criteria_refs":["AC1"],"status":"pending","files_modified":[],"domain":"general","executor":"agent"}],"created_at":""},
48
+ "execution_config": {"method":"auto","default_executor":"","domain_routing":{"frontend":"","backend":"","default":"agent"},"code_review_tool":"Skip","verification_tool":"Auto","confirmed":false},
49
+ "iterations": [{"iteration":1,"started_at":"","completed_at":"","criteria_before":{"passed":0,"total":0},"criteria_after":{"passed":0,"total":0},"gaps_fixed":[],"files_modified":[]}],
50
+ "current_iteration": 0,
51
+ "patterns": [], "generalization_stats": null }
52
+ ```
53
+
54
+ ### evidence.ndjson Phases
55
+
56
+ `planning|execution|verification|fix|decision|generalization|discovery|self-iteration`
57
+
58
+ ### phase_goals[]
59
+
60
+ | ID | Goal | done_when | phase | skip_when |
61
+ |----|------|-----------|-------|-----------|
62
+ | G1 | Acceptance criteria defined | ≥1 criterion in acceptance_criteria[] | S_INTAKE | — |
63
+ | G2 | Plan created | session.json.plan populated | S_PLAN | — |
64
+ | G3 | Implementation complete | all plan tasks executed | S_EXECUTE | — |
65
+ | G4 | All criteria pass | all acceptance_criteria[].status == passed | S_VERIFY | — |
66
+ | G5 | Pattern generalized | patterns[] ≥1 entry | S_GENERALIZE | skip_generalize |
67
+ | G6 | Discoveries triaged | all scan hits classified | S_DISCOVER | skip_generalize |
68
+ | G7 | Learnings persisted | spec entries created OR no actionable | S_RECORD | — |
69
+
70
+ ### understanding.md — 8 Sections
71
+
72
+ 1. Requirement & Criteria
73
+ 2. Plan
74
+ 3. Execution
75
+ 4. Verification
76
+ 5. Fix Log
77
+ 6. Generalization
78
+ 7. Discoveries
79
+ 8. Learnings
80
+
81
+ ---
82
+
83
+ ## State Machine
84
+
85
+ ### Transitions
86
+
87
+ ```
88
+ S_PLAN → S_EXECUTE
89
+ S_EXECUTE → S_VERIFY
90
+ S_VERIFY → S_GENERALIZE : all passed AND !skip_generalize
91
+ S_VERIFY → S_RECORD : all passed AND skip_generalize
92
+ S_VERIFY → S_FIX : some failed AND iteration < max
93
+ S_VERIFY → S_PLAN : fundamental plan flaw → cross_phase_loops++ (replan). Criteria preservation: acceptance_criteria[] statuses preserved; only plan.tasks[] regenerated. Passed criteria retain `passed`; failed criteria reset to `pending` for re-verification.
94
+ S_VERIFY → S_RECORD : some failed AND iteration >= max (escalate)
95
+ S_FIX → S_VERIFY (loop)
96
+ ```
97
+
98
+ Discover routes to S_EXECUTE (not FIX): area needing same implementation → new task, `cross_phase_loops++`.
99
+
100
+ ### Actions
101
+
102
+ **A_INTAKE extra** — Define acceptance criteria: analyze requirement → derive testable criteria, each with `verify_method` (test|grep|cli-review|manual). Normal: `request_user_input` to confirm/edit | `-y`: auto-derive, record `{"phase":"decision","type":"criteria-confirmation","status":"deferred"}`. Mark G1.
103
+
104
+ **GATE: criteria-defined** — ≥1 criterion in `acceptance_criteria[]`, each with a testable `criterion` and assigned `verify_method` (test|grep|cli-review|manual); confirmed by user or auto-derived with deferred confirmation under `-y`; G1 marked.
105
+
106
+ **A_PLAN** — (1) Decompose requirement into ordered tasks mapped to acceptance criteria. (2) CLI-assisted planning (optional):
107
+ ```bash
108
+ evolve delegate "PURPOSE: Create implementation plan for: {requirement}
109
+ TASK: Decompose into subtasks | Map to acceptance criteria | Identify dependencies
110
+ MODE: analysis
111
+ CONTEXT: @**/* | Criteria: {criteria_summary}
112
+ EXPECTED: JSON [{task_id, title, description, criteria_refs, deps}]
113
+ " --role analyze --mode analysis
114
+ ```
115
+ Run `run_in_background: true`, wait for callback. (3) Write `session.json.plan`, append evidence (planning), update §2. Mark G2.
116
+
117
+ Commit: `"odyssey-planex({slug}): PLAN — requirement decomposed into tasks"`
118
+
119
+ **A_EXECUTE** —
120
+
121
+ - **Step 1 — Execution Options Confirmation.** Skip if `-y` OR `--method` explicitly set OR `execution_config.confirmed == true` (resume). Load tools: `the Codex or Agy executables available to the host`. `request_user_input` 3 questions: Executor (Auto domain routing | Agent all | specific CLI | custom) / Review (Skip | {tool}) / Verify (Auto | specific tool | Skip). Parse → write `execution_config`, set `confirmed: true`. `--skip-verify` overrides verification to `"Skip"`.
122
+
123
+ - **Step 2 — Executor Resolution** (method == "auto"): domain routing — frontend (UI/component/page/style, .tsx/.jsx/.vue/.css/.html/.svelte) | backend (API/server/db/service, .go/.rs/.java/.py/.sql/.proto) | general (mixed/config/tests, .ts/.js/other). Resolution: `execution_config.domain_routing[domain]` → fallback `.default` ("agent").
124
+
125
+ - **Step 3 — Task Execution** per plan order. Independent tasks parallelize via CSV wave.
126
+
127
+ **CSV wave pattern** — generate `execute-tasks.csv` with one row per plan task:
128
+
129
+ ```csv
130
+ id,title,description,criteria,specs_content,prior_summaries,scope,status,summary,files_modified,error
131
+ ```
132
+
133
+ **Row generation** — for each task in `plan.tasks[]`:
134
+ ```csv
135
+ "{task.id}","{task.title}","Implement task {task.id}: {task.title}. {task.description}. Success = criteria [{task.criteria_refs}] satisfied. Read existing code first. Verify convergence criteria after changes. Scope limited to task files. Follow project specs.","{criteria_refs mapped to criterion text}","{specs_content}","{prior task summaries}","{scope}","","","",""
136
+ ```
137
+
138
+ **Agent path (executor == "agent"):**
139
+ ```javascript
140
+ MANDATORY, NOT SUBSTITUTABLE by manual implementation:
141
+ spawn_agents_on_csv({
142
+ csv_path: `${sessionFolder}/execute-tasks.csv`,
143
+ id_column: "id",
144
+ instruction: "You are implementing a task from the plan. Read 'description' for full instructions, 'criteria' for acceptance criteria. Implement the code changes, verify convergence. Write summary of changes made and files_modified as JSON array.",
145
+ max_concurrency: maxConcurrency,
146
+ max_runtime_seconds: 3600,
147
+ output_csv_path: `${sessionFolder}/execute-results.csv`,
148
+ output_schema: { id, status, summary, files_modified, error }
149
+ })
150
+ ```
151
+
152
+ Merge results from `execute-results.csv` back into task statuses.
153
+
154
+ **CLI path** — for tasks routed to a specific CLI tool, use sequential `evolve delegate` calls:
155
+ ```bash
156
+ evolve delegate "PURPOSE: Implement task ${task_id}: ${title}; success = criteria ${criteria_refs} satisfied
157
+ TASK: ${description} | Read existing code first | Verify convergence criteria after changes
158
+ MODE: write
159
+ CONTEXT: @${scope}/**/* | Criteria: ${criteria_summary}
160
+ EXPECTED: Working code changes, convergence evidence, summary of what was done
161
+ CONSTRAINTS: Scope limited to task files | Follow project specs
162
+
163
+ ## Acceptance Criteria (must satisfy)
164
+ ${criteria_refs.map(ref => criteria[ref].criterion).join('\n')}
165
+
166
+ ## Implementation Steps
167
+ ${task.description}
168
+
169
+ ## Project Specs
170
+ ${specs_content}
171
+
172
+ ## Prior Task Summaries
173
+ ${prior_summaries}
174
+ " --to ${resolved_executor} --mode write --id planex-${slug}-${task_id}
175
+ ```
176
+ Run `run_in_background: true`, wait for callback. **Deviation Rule (MANDATORY hard limit — max 3 retries per task):** first attempt normal dispatch → retry `--resume planex-${slug}-${task_id}` simplified → fallback to `spawn_agent()` path → all 3 fail → mark task `blocked`, checkpoint, continue remaining. NEVER exceed 3 attempts on a single task.
177
+
178
+ **Mixed routing** — when some tasks route to agent and others to CLI: partition tasks by executor, run agent-routed tasks via `spawn_agents_on_csv`, run CLI-routed tasks via sequential `evolve delegate`. Merge all results.
179
+
180
+ - **Step 4 — Per-Task Evidence:** `{"phase":"execution","type":"task-completed","task_id":"T1","executor":"...","files_modified":[],"summary":"","attempt":1}`; update task status.
181
+
182
+ - **Step 5 — Post-Execution Validation.** Skip if `verification_tool == "Skip"` OR `--skip-verify` OR no completed tasks. **Check 1** Summary Consistency (task status vs git diff). **Check 2** CLI Verification Gate:
183
+ ```bash
184
+ evolve delegate "PURPOSE: Verify execution output meets acceptance criteria; success = all criteria verified with file:line evidence
185
+ TASK:
186
+ 1. CONVERGENCE: For each criterion, read actual code, verify behavior exists, report status with evidence
187
+ 2. EXISTENCE: Verify all expected files exist on disk
188
+ 3. SUBSTANCE: Verify real implementation — flag stubs, placeholders, TODO-only
189
+ 4. ANTI-PATTERNS: Scan for TODO/FIXME/HACK, console.log debug, disabled tests
190
+ MODE: analysis
191
+ CONTEXT: @${modified_files}
192
+ EXPECTED: JSON { convergence: [{criterion, status, evidence}], issues: [{type, file, line, severity}], overall: passed|gaps_found }
193
+ CONSTRAINTS: Read-only | Check ALL criteria exhaustively | Evidence must be file:line
194
+
195
+ ## Acceptance Criteria (verify each)
196
+ ${acceptance_criteria.map(c => c.criterion).join('\n')}
197
+
198
+ ## Modified Files
199
+ ${modified_files.join('\n')}
200
+ " --to ${execution_config.verification_tool} --mode analysis
201
+ ```
202
+ Run `run_in_background: true`. `overall == "passed"` → proceed to S_VERIFY with boosted confidence; `gaps_found` → log findings, proceed. **Check 3** Code Review (if `code_review_tool != "Skip"`): `evolve delegate "Review git diff for correctness, style, bugs" --to ${code_review_tool} --mode analysis --rule analysis-review-code-quality`.
203
+
204
+ - **Step 6 — Completion:** update §3. Mark G3.
205
+
206
+ **GATE: plan-executed** — all plan tasks executed (`completed`) or explicitly `blocked` after 3 retries with logged evidence; per-task execution evidence recorded; post-execution validation (convergence, existence, substance, anti-patterns) completed unless `--skip-verify`; G3 marked.
207
+
208
+ Commit: `"odyssey-planex({slug}): EXECUTE — task implementation complete"`
209
+
210
+ **A_VERIFY** — Iron gate; verify each criterion by method:
211
+
212
+ | Method | Action |
213
+ |--------|--------|
214
+ | `test` | Run relevant tests, check pass/fail |
215
+ | `grep` | Grep for expected pattern |
216
+ | `cli-review` | `evolve delegate "PURPOSE: Verify criterion {id}: {criterion}\nTASK: Read implementation \| Check behavior \| Report pass/fail with file:line\nMODE: analysis\nCONTEXT: @{relevant_files}\nEXPECTED: JSON {criterion_id, status, evidence}" --role review --mode analysis` |
217
+ | `manual` | Normal: `request_user_input` / `-y`: record `deferred` |
218
+
219
+ Record per criterion: `{"phase":"verification","type":"criterion-check","criterion_id":"AC1","method":"","result":"passed|failed","evidence":"","iteration":N}`. Update `acceptance_criteria[].status`. Append to `iterations[]`. Update §4 pass/fail table. **Route:** all passed → mark G4 → next. Some failed + iteration < max → S_FIX. Some failed + iteration >= max → Normal: `request_user_input` (continue/lower bar/accept) / `-y`: `deferred`, proceed S_RECORD.
220
+
221
+ **GATE: all-criteria-passed** — every `acceptance_criteria[].status == passed` with recorded evidence and `passed_at`, verified by the declared `verify_method`; iterations logged in `iterations[]`; if max iterations exceeded, criteria may be `deferred` only with explicit user consent (or `-y` auto-accept); G4 marked.
222
+
223
+ Commit: `"odyssey-planex({slug}): VERIFY — criteria verification iteration {N}"`
224
+
225
+ **A_FIX** — (1) Increment `current_iteration`. (2) For each failed criterion: diagnose gap → targeted code fix (not re-implementation). (3) CLI fix review (optional): `evolve delegate` review fixes for regressions, EXPECTED `{verdict, regression_risk, concerns}`. (4) Append evidence (fix), update §5 → S_VERIFY.
226
+
227
+ Commit: `"odyssey-planex({slug}): FIX — iteration {N} gap fixes"`
228
+
229
+ ---
230
+
231
+ ## Generalize Source
232
+
233
+ Implementation patterns from executed tasks (API contract shapes, validation shapes, error response format, config structure).
234
+
235
+ ---
236
+
237
+ ## Iteration Model
238
+
239
+ ```
240
+ S_EXECUTE → S_VERIFY ──all pass──→ S_GENERALIZE → S_DISCOVER → S_RECORD
241
+ │ │
242
+ some fail + iter < max 3-layer scan, 0 hits ─→ S_RECORD
243
+ ▼
244
+ S_FIX ──→ S_VERIFY (loop)
245
+ ```
246
+
247
+ Max iterations (default 3) prevents infinite loops.
248
+
249
+ ---
250
+
251
+ ## Knowledge Persistence (§8)
252
+
253
+ Include verified reusable findings in the Run summary and harvest the completed Session through Agent Memory closeout.
254
+
255
+
256
+ | Category | Content | Follow-up |
257
+ |----------|---------|-----------|
258
+ | Multi-round fix cycle pattern | Problem scenario + fix iteration + final approach | `stage spec → debug` |
259
+ | Reusable implementation pattern | Pattern + applicable scope + code template | `stage spec → coding` |
260
+ | Acceptance criteria template | Standard template + verify_method suggestion | `stage spec → review` |
261
+ | Generalization pattern | Signature + risk + fix template | `stage spec → coding` |
262
+
263
+ ---
264
+
265
+ ## Completion Summary
266
+
267
+ ```
268
+ --- PLANEX ODYSSEY COMPLETE ---
269
+ Requirement: {requirement}
270
+ Criteria: {passed}/{total} passed
271
+ Iterations: {N} cycles
272
+ Patterns: {patterns_extracted} ({by_layer} distribution)
273
+ Scan hits: {total_hits} ({cross_layer_confirmed} cross-layer confirmed)
274
+ Issues: {N} created | Decisions: {N} resolved, {M} pending, {K} deferred
275
+ Learnings: {N} spec entries
276
+ Self-iter: {N} rounds across {M} stages
277
+ Goals: {done}/{total} confirmed ({skipped} skipped)
278
+ Status: {ALL_PASSED|PARTIAL|ESCALATED}
279
+ ---
280
+ ```
281
+
282
+ ---
283
+
284
+ ## Mode `-y` Points
285
+
286
+ | Decision Point | Normal | `-y` |
287
+ |---------------|--------|------|
288
+ | S_INTAKE criteria | `request_user_input` | auto-derive `deferred` |
289
+ | S_EXECUTE options | `request_user_input` | defaults (auto/Skip/Auto) `confirmed:true` |
290
+ | S_EXECUTE task blocked | `request_user_input` | auto continue, log blocked |
291
+ | S_VERIFY manual criterion | `request_user_input` | `deferred` |
292
+ | S_VERIFY max iteration | `request_user_input` | auto accept `deferred` |
293
+ | A_DISCOVER routing | `request_user_input` | auto-route to execute, issue for rest |
294
+
295
+ ---
296
+
297
+ ## Phase Gates
298
+
299
+ - **Audit gate** (PLAN+EXECUTE): plan tasks mapped to criteria; all tasks executed or blocked after 3 retries.
300
+ - **FIX gate:** current severity tier fully addressed. Per-fix evidence phase=fix logged. Auto-commit per tier.
301
+ - **VERIFY gate:** every criterion verified by its method. confirmation written, understanding.md updated, verify goal marked. needs_rework → route back to FIX.
302
+
303
+ ---
304
+
305
+ ## CSV Session Structure
306
+
307
+ ```
308
+ {sessionFolder}/
309
+ ├── execute-tasks.csv # input tasks for spawn_agents_on_csv
310
+ ├── execute-results.csv # output from spawn_agents_on_csv
311
+ ├── session.json # master session state
312
+ ├── understanding.md # progressive documentation
313
+ ├── evidence.ndjson # evidence log
314
+ ```
315
+
316
+ ---
317
+
318
+ ## Error Codes
319
+
320
+ | Code | Severity | Condition | Recovery |
321
+ |------|----------|-----------|----------|
322
+ | E001 | error | No requirement | Provide requirement or -c |
323
+ | W007 | warning | CLI review regression concern | Review before next iteration |
324
+
325
+ ---
326
+
327
+ ## Success Criteria
328
+
329
+ - [ ] Requirement parsed; session + output files created; acceptance criteria defined
330
+ - [ ] Plan decomposed into tasks mapped to acceptance criteria
331
+ - [ ] All tasks executed (or blocked after 3 retries); execution evidence logged
332
+ - [ ] understanding.md sections written progressively (§1–§8)
333
+ - [ ] Criteria verified by method (test/grep/cli-review/manual); fix loop if needed
334
+ - [ ] Multi-layer generalization + discovery triage (unless --skip-generalize)
335
+ - [ ] phase_goals derived, tracked, and hardened-audited; goal_mode injected via prepare goal:true
336
+ - [ ] Session resumable via -c; completion summary emitted
337
+ - [ ] Status: ALL_PASSED / PARTIAL / ESCALATED
338
+
339
+ ---
340
+
341
+ ## Next Step Routing
342
+
343
+ | Condition | Next |
344
+ |-----------|------|
345
+ | Discovery issues created | `Open the follow-up findings in the project issue tracker` |
346
+ | Deeper debug needed | `$ew-odyssey <finding> --mode debug` |
347
+ | Formal review of changes | `$ew-odyssey <changed-files> --mode review` |
348
+ | UI-related findings | `$ew-odyssey <component> --mode ui` |
349
+ | Document pattern | `Review the module and stage the reusable method via Agent Memory closeout` |
350
+ | Second opinion | `evolve delegate "<review prompt>" --mode analysis` |
351
+ | Reusable pattern to persist | `stage spec → coding` |
352
+ | Pending decisions | Filter evidence phase=decision status=pending |