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.
- package/LICENSE +27 -0
- package/README.md +90 -2
- package/dist/agent-memory-prompts.d.ts +13 -0
- package/dist/agent-memory-prompts.js +55 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +6 -0
- package/dist/closeout.d.ts +105 -0
- package/dist/closeout.js +479 -0
- package/dist/code.d.ts +39 -0
- package/dist/code.js +124 -0
- package/dist/common.d.ts +9 -0
- package/dist/common.js +42 -0
- package/dist/context-envelope.d.ts +59 -0
- package/dist/context-envelope.js +23 -0
- package/dist/host-adapters.d.ts +34 -0
- package/dist/host-adapters.js +151 -0
- package/dist/http.d.ts +3 -0
- package/dist/http.js +90 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +13 -0
- package/dist/knowledge-cli.d.ts +183 -0
- package/dist/knowledge-cli.js +654 -0
- package/dist/knowledge-reads.d.ts +71 -0
- package/dist/knowledge-reads.js +193 -0
- package/dist/memory.d.ts +97 -0
- package/dist/memory.js +250 -0
- package/dist/retrospective.d.ts +57 -0
- package/dist/retrospective.js +248 -0
- package/dist/search.d.ts +36 -0
- package/dist/search.js +112 -0
- package/dist/skill-addition.d.ts +25 -0
- package/dist/skill-addition.js +89 -0
- package/dist/skill-design.d.ts +96 -0
- package/dist/skill-design.js +226 -0
- package/dist/skill-replay.d.ts +55 -0
- package/dist/skill-replay.js +451 -0
- package/dist/skill-route.d.ts +30 -0
- package/dist/skill-route.js +75 -0
- package/dist/transcript-evidence.d.ts +3 -0
- package/dist/transcript-evidence.js +58 -0
- package/dist/upstream/chunker.d.ts +24 -0
- package/dist/upstream/chunker.js +96 -0
- package/dist/upstream/file-protocol.d.ts +45 -0
- package/dist/upstream/file-protocol.js +117 -0
- package/dist/upstream/frontmatter.d.ts +47 -0
- package/dist/upstream/frontmatter.js +86 -0
- package/dist/upstream/graph-search.d.ts +33 -0
- package/dist/upstream/graph-search.js +67 -0
- package/dist/upstream/l1-extraction.d.ts +26 -0
- package/dist/upstream/l1-extraction.js +405 -0
- package/dist/upstream/llm.d.ts +8 -0
- package/dist/upstream/llm.js +1 -0
- package/dist/upstream/merge.d.ts +50 -0
- package/dist/upstream/merge.js +153 -0
- package/dist/upstream/prompts.d.ts +53 -0
- package/dist/upstream/prompts.js +185 -0
- package/dist/upstream/search-utils.d.ts +34 -0
- package/dist/upstream/search-utils.js +55 -0
- package/dist/upstream/slug.d.ts +26 -0
- package/dist/upstream/slug.js +103 -0
- package/dist/upstream/template.d.ts +29 -0
- package/dist/upstream/template.js +80 -0
- package/dist/upstream/tokenize.d.ts +4 -0
- package/dist/upstream/tokenize.js +29 -0
- package/dist/wiki-change.d.ts +76 -0
- package/dist/wiki-change.js +299 -0
- package/dist/wiki-entry.d.ts +26 -0
- package/dist/wiki-entry.js +93 -0
- package/dist/wiki-ingest.d.ts +12 -0
- package/dist/wiki-ingest.js +126 -0
- package/dist/wiki-migration.d.ts +16 -0
- package/dist/wiki-migration.js +268 -0
- package/dist/wiki-tokens.d.ts +1 -0
- package/dist/wiki-tokens.js +46 -0
- package/dist/wiki.d.ts +103 -0
- package/dist/wiki.js +330 -0
- package/dist/workflow-cli.d.ts +2 -0
- package/dist/workflow-cli.js +258 -0
- package/dist/workflow-install.d.ts +36 -0
- package/dist/workflow-install.js +148 -0
- package/dist/workflow-knowledge.d.ts +16 -0
- package/dist/workflow-knowledge.js +24 -0
- package/dist/workflow-mcp.d.ts +2 -0
- package/dist/workflow-mcp.js +144 -0
- package/dist/workflow-names.d.ts +4 -0
- package/dist/workflow-names.js +18 -0
- package/dist/workflow-runtime.d.ts +622 -0
- package/dist/workflow-runtime.js +627 -0
- package/dist/workflow-skills.d.ts +48 -0
- package/dist/workflow-skills.js +141 -0
- package/package.json +76 -4
- package/skills/ew-odyssey/SKILL.md +237 -0
- package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
- package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
- package/skills/ew-odyssey/references/odyssey-base.md +278 -0
- package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
- package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
- package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
- package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
- package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
- package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
- package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
- package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
- package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
- package/skills/ew-odyssey/references/odyssey-review.md +251 -0
- package/skills/ew-odyssey/references/odyssey-security.md +249 -0
- package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
- package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
- package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
- package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
- package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
- package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
- package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
- package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
- package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
- package/skills/ew-orchestrate/SKILL.md +236 -0
- package/skills/ew-orchestrate/references/auto-policy.md +165 -0
- package/skills/ew-orchestrate/references/companion-route.md +52 -0
- package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
- package/skills/ew-orchestrate/references/goal.md +53 -0
- package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
- package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
- package/skills/ew-orchestrate/references/planning.md +137 -0
- package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
- package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
- package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
- package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
- package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
- package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
- package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
- package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
- package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
- package/skills/ew-skill-design/SKILL.md +28 -0
- package/skills/ew-skill-design/references/package-contract.md +28 -0
- package/skills/ew-skill-design/references/validation.md +7 -0
- package/skills/team-swarm/SKILL.md +231 -0
- package/skills/team-swarm/references/mcp-coordination.md +10 -0
- package/skills/team-swarm/roles/analyst/role.md +181 -0
- package/skills/team-swarm/roles/ant/role.md +149 -0
- package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
- package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
- package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
- package/skills/team-swarm/roles/coordinator/role.md +228 -0
- package/skills/team-swarm/roles/scorer/role.md +150 -0
- package/skills/team-swarm/scripts/aco.py +646 -0
- package/skills/team-swarm/scripts/pheromone.py +144 -0
- package/skills/team-swarm/scripts/scoring.py +111 -0
- package/skills/team-swarm/scripts/test_aco.py +606 -0
- package/skills/team-swarm/specs/ant-output-schema.md +127 -0
- package/skills/team-swarm/specs/convergence-criteria.md +108 -0
- package/skills/team-swarm/specs/pheromone-schema.md +125 -0
- package/skills/team-swarm/specs/swarm-config-template.json +71 -0
- package/skills/team-swarm/specs/swarm-protocol.md +123 -0
- package/skills/workflow-closeout/SKILL.md +10 -0
- package/skills/workflow-evolve/SKILL.md +79 -0
- package/skills/workflow-evolve/references/agy-gate.md +27 -0
- package/skills/workflow-evolve/references/auto-loop.md +20 -0
- package/skills/workflow-evolve/references/history-review.md +14 -0
- package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
- package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
- package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
- package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
- 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 |
|