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,202 @@
1
+
2
+ > **Agent timeout**: `spawn_agent` 异步执行且无内置超时 — 除明确短任务外一律 `spawn_agent` 后立即 `wait_agent({ timeout_ms: 3600000 })`(上限 1 小时)阻塞等待,绝不依赖 30000 默认值;`timed_out: true` 且 Agent 未完成时再次 `wait_agent` 续等,不丢弃。批量场景使用 `spawn_agents_on_csv({ max_runtime_seconds: 3600, ... })`。
3
+
4
+ > **Plan tracking**: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 `update_plan({ explanation?, plan: [{ step, status }] })` 维护(整体提交步骤数组,status: `pending` | `in_progress` | `completed`),权威状态始终在 session 工件中;依赖/认领(addBlockedBy/owner)是工件字段,不是工具参数。
5
+ # Command: iterate
6
+
7
+ ## Two Entry Points
8
+
9
+ | Entry | Trigger | Action |
10
+ |-------|---------|--------|
11
+ | **Iteration start** | Phase 3 invoked OR previous iteration converged=false | Run "Iteration Start" workflow |
12
+ | **Iteration end** | All ants of current iter reported via callback | Run "Iteration End" workflow |
13
+
14
+ ## Iteration Start Workflow
15
+
16
+ ### Step 1: Determine iteration number
17
+
18
+ ```
19
+ k = session.iteration + 1
20
+ ```
21
+
22
+ If `k > session.max_iterations`: force converge to Phase 4 (safety net).
23
+
24
+ ### Step 2: Call aco.py select
25
+
26
+ ```
27
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> select --iter <k>
28
+ ```
29
+
30
+ Parse stdout JSON. Expected:
31
+ ```json
32
+ {
33
+ "status": "ok",
34
+ "iteration": <k>,
35
+ "n_assignments": <N>,
36
+ "assignments": [
37
+ {
38
+ "ant_id": "ANT-<k>-<i>",
39
+ "start_node": "<node>",
40
+ "edge_preferences": {"a::b": 0.4, ...},
41
+ "max_path_length": <int>,
42
+ "iteration": <k>
43
+ }, ...
44
+ ]
45
+ }
46
+ ```
47
+
48
+ On error -> log to issues.md, request_user_input (retry / abort).
49
+
50
+ For a Run, `select --iter <k>` persists `assignments/<k>.json` before dispatch. Re-run the same command after an interruption to recover the original IDs and start nodes. Use the roster and task mapping to reuse live jobs and completed artifacts. Create a worker only for an assignment that still needs one.
51
+
52
+ ### Step 3: Create ant tasks
53
+
54
+ For each assignment:
55
+
56
+ ```
57
+ update_plan({
58
+ subject: "ANT-<k>-<i>: explore from <start_node>",
59
+ description: "Session: <session_path>\nAssignment: <assignment JSON>\nObjective: <config.ant_prompt.objective>"
60
+ })
61
+ update_plan({ taskId: <new>, owner: "ant" })
62
+ ```
63
+
64
+ Set the task ID to match `ANT-<k>-<i>` (or record mapping in `.msg/meta.json` if framework auto-assigns IDs).
65
+
66
+ ### Step 4: Spawn N ant workers in parallel
67
+
68
+ For each assignment, spawn one team-worker:
69
+
70
+ ```
71
+ spawn_agent({ task_name: "ant_<k>_<i>", message: "Spawn ant <ANT-k-i>", fork_turns: "none", agent_type: "team_worker" })
72
+ ```
73
+
74
+ All N spawns in a single message (parallel).
75
+
76
+ ### Step 5: Update session state
77
+
78
+ ```
79
+ session.iteration = <k> (mark "in progress")
80
+ session.active_workers = [<list of ant IDs>]
81
+ ```
82
+
83
+ Persist the iteration and assignment IDs in team-session.json.
84
+
85
+ ### Step 6: STOP
86
+
87
+ Wait for ant callbacks. Each ant uses evolve team report for its assignment. When ALL N reported, callback handler invokes "Iteration End" workflow.
88
+
89
+ ---
90
+
91
+ ## Iteration End Workflow
92
+
93
+ ### Step 1: Verify completion
94
+
95
+ Check `ANT-<k>-*` task statuses. If any still in_progress: not yet complete, do nothing.
96
+
97
+ If all completed -> proceed.
98
+
99
+ ### Step 2: (Conditional) Spawn scorer
100
+
101
+ If `config.scoring.mode == "llm"`:
102
+
103
+ ```
104
+ spawn_agent({
105
+ subagent_type: "team-worker",
106
+ team_name: "swarm",
107
+ name: "scorer-<k>",
108
+ run_in_background: true,
109
+ prompt: `## Role Assignment
110
+ role: scorer
111
+ role_spec: <skill_root>/roles/scorer/role.md
112
+ session: <session_path>
113
+ session_id: <run-id>
114
+ run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
115
+ team_name: swarm
116
+ requirement: score iteration <k> ants
117
+ inner_loop: false
118
+
119
+ ## Context
120
+ Iteration to score: <k>
121
+ Output file: {run_dir}/work/team/scores/iter-<k>-scores.json
122
+ Read all artifacts: {run_dir}/outputs/ant-<k>-*.json`
123
+ })
124
+ ```
125
+
126
+ STOP and await scorer callback. On callback resume at Step 3.
127
+
128
+ The callback must identify `SCORE-<k>` and the same iteration. Check that the output covers all ant artifacts for this iteration before invoking `update`. Once the controller has committed the iteration, replay with the same scoring decision and inputs.
129
+
130
+ If `scoring.mode == "script"` or `"fallback"` -> proceed directly to Step 3.
131
+
132
+ ### Step 3: Call aco.py update
133
+
134
+ ```
135
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> update --iter <k>
136
+ ```
137
+
138
+ Parse stdout JSON. Expected:
139
+ ```json
140
+ {
141
+ "status": "ok",
142
+ "iteration": <k>,
143
+ "n_ants_processed": <N>,
144
+ "mean_score": <float>,
145
+ "best_score": <float>,
146
+ "delta": <float>,
147
+ "elite_updated": <bool>,
148
+ "hallucinations_flagged": [<ant_ids>],
149
+ "stats": {<pheromone stats>}
150
+ }
151
+ ```
152
+
153
+ ### Step 4: Log iteration result
154
+
155
+ Save the phase summary in team-session.json.
156
+
157
+ If `hallucinations_flagged.length > N/2`: append warning to wisdom/issues.md (high-noise iteration).
158
+
159
+ ### Step 5: Call aco.py converged
160
+
161
+ ```
162
+ Bash: python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> converged
163
+ ```
164
+
165
+ Parse:
166
+ ```json
167
+ { "converged": <bool>, "triggered_by": [...], "reason": "...", "metrics": {...} }
168
+ ```
169
+
170
+ ### Step 6: Branch on convergence
171
+
172
+ ```
173
+ if converged:
174
+ update session: completed_iterations.push(k), status = "converging"
175
+ -> proceed to Phase 4 (converge.md)
176
+ else:
177
+ update session: completed_iterations.push(k), active_workers = []
178
+ -> re-enter "Iteration Start" workflow with k+1
179
+ ```
180
+
181
+ ### Step 7: Output progress to user
182
+
183
+ After each iteration:
184
+ ```
185
+ [coordinator] Iteration <k>/<max> complete.
186
+ [coordinator] best=<best_score> mean=<mean_score> delta=<delta>
187
+ [coordinator] entropy=<entropy> hallucinations=<count>
188
+ [coordinator] Status: <converged | continuing to iter k+1>
189
+ ```
190
+
191
+ ---
192
+
193
+ ## Edge Cases
194
+
195
+ | Condition | Handling |
196
+ |-----------|----------|
197
+ | Ant task failed | Mark task failed; if >50% failed in iter -> halt, request_user_input |
198
+ | Ant produced no artifact | Script's update will skip it; if all skipped -> error -> halt |
199
+ | `aco.py update` fails | Retry once; if persistent -> halt with error report |
200
+ | Scorer worker fails | Record the failure. For an intentional self-score fallback in a Run, use `update --iter <k> --allow-score-fallback` and record that choice for replay. |
201
+ | Iteration takes too long | After timeout (configurable), check the host job and Evolve assignment roster |
202
+ | User sends `feedback <text>` mid-iteration | Append to wisdom/learnings.md; apply at next iteration start (not mid-iter) |
@@ -0,0 +1,228 @@
1
+ ---
2
+ role: coordinator
3
+ ---
4
+
5
+ > **Plan tracking**: codex 无 TaskCreate/TaskUpdate/TodoWrite 任务板。进度清单用 `update_plan({ explanation?, plan: [{ step, status }] })` 维护(整体提交步骤数组,status: `pending` | `in_progress` | `completed`),权威状态始终在 session 工件中;依赖/认领(addBlockedBy/owner)是工件字段,不是工具参数。
6
+
7
+ # Coordinator Role — team-swarm
8
+
9
+ ## Identity
10
+
11
+ - **Name**: `coordinator` | **Tag**: `[coordinator]`
12
+ - **Responsibility**: Translate user intent into swarm-config -> drive K-iteration outer loop -> dispatch N ants per iteration -> consume script verdicts -> deliver final synthesis
13
+
14
+ ## Boundaries
15
+
16
+ ### MUST
17
+ - Generate `swarm-config.json` from user task description (Phase 1)
18
+ - Invoke `scripts/aco.py` for ALL numeric decisions (selection, update, convergence)
19
+ - Spawn ant workers with strict role-spec assignment + path hints from script
20
+ - After each iteration callback: call `aco.py update` -> `aco.py converged` -> decide loop/exit
21
+ - Persist session state in the Evolve assignment roster and Python controller checkpoints
22
+ - Trigger analyst for final synthesis when converged
23
+
24
+ ### MUST NOT
25
+ - Make selection/update/convergence decisions on its own — these belong to the script
26
+ - Modify `pheromone/*.json`, `best.json`, or `trails/*.jsonl` directly — script owns these
27
+ - Skip the convergence check after each iteration
28
+ - Spawn more than `config.swarm.n_ants` ants per iteration
29
+ - Exceed `config.convergence.max_iterations` outer loops
30
+
31
+ ---
32
+
33
+ ## Message Types
34
+
35
+ | Type | Direction | Trigger |
36
+ |------|-----------|---------|
37
+ | state_update | outbound | Iteration start/end, session init |
38
+ | task_unblocked | outbound | Ant batch ready |
39
+ | ant_done | inbound | Individual ant completion (rolled up to batch check) |
40
+ | iteration_complete | inbound | All ants in batch reported |
41
+ | capability_gap | inbound | Ant requests config change |
42
+ | error | inbound | Worker / script failure |
43
+
44
+ ## Command Execution Protocol
45
+
46
+ When coordinator needs to execute a phase command:
47
+
48
+ 1. Read the command file: `roles/coordinator/commands/<command-name>.md`
49
+ 2. Follow the workflow defined inline
50
+ 3. Commands are inline execution guides — NOT separate agents
51
+
52
+ ## Toolbox
53
+
54
+ | Tool | Type | Purpose |
55
+ |------|------|---------|
56
+ | [Initialization](commands/init-swarm.md) | Command | Phase 2: build swarm-config + call `aco.py init` |
57
+ | [Iteration](commands/iterate.md) | Command | Phase 3: single iteration loop body (select/spawn/update) |
58
+ | [Convergence](commands/converge.md) | Command | Phase 4: convergence handler + analyst spawn |
59
+ | `scripts/aco.py` | Script | All numeric decisions (Bash subprocess) |
60
+ | team-worker | Subagent | Worker spawning (ant, scorer, analyst) |
61
+ | update_plan / list_agents / wait_agent / update_plan | System | Task lifecycle |
62
+ | evolve team | Evolve runtime | Assignment and result receipts |
63
+ | send_message / request_user_input | System | Comms |
64
+
65
+ ---
66
+
67
+ ## Entry Router
68
+
69
+ | Detection | Condition | Handler |
70
+ |-----------|-----------|---------|
71
+ | Worker callback | Message contains `[ant]` / `[scorer]` / `[analyst]` | -> handleCallback |
72
+ | Status check | Args contain `check` or `status` | -> handleCheck |
73
+ | Manual resume | Args contain `resume` or `continue` | -> handleResume |
74
+ | Iteration complete | All ants of current iteration reported | -> Phase 3.5 (update + converged?) |
75
+ | Pipeline complete | aco.py converged returned true | -> Phase 4 |
76
+ | Interrupted session | Active session exists in `{run_dir}/work/team/` | -> Phase 0 |
77
+ | New session | None of above | -> Phase 1 |
78
+
79
+ ---
80
+
81
+ ## Phase 0: Session Resume Check
82
+
83
+ 1. **Exact Run locator first**: when the birth packet supplies `run_id` / `run_dir`, inspect only `{run_dir}/work/team/team-session.json`. An exact `run_dir` contains at most one team session; do not scan sibling Runs and do not enter a multiple-candidate branch.
84
+ 2. Reconcile the exact candidate through the runtime lifecycle adapter before resuming: canonical Run status, broker-backed live agents, non-terminal team tasks, and the ordered activity clock (message/task -> meta -> sidecar -> legacy filesystem fallback).
85
+ 3. Resume only a verified matching `team-swarm` session whose canonical lifecycle is `active` or `paused`. Reconcile list_agents vs `session.iteration` vs `pheromone/current.json` before dispatching any worker.
86
+ 4. **Locator-less legacy recovery**: enumerate and rank candidates through the runtime resume ranker, then show the ranked evidence with request_user_input. Never select candidate index 0 implicitly; ties, `stale_candidate`, `unknown`, or `inconsistent` health always require an explicit choice.
87
+ 5. `stale_candidate` is derived health, never a lifecycle and never cleanup eligibility. An operator may explicitly resume an active/paused stale candidate after reviewing evidence, or request an audited transition to `abandoned`; TTL alone must not persist abandonment or delete state.
88
+ 6. Abandonment and cleanup are separate confirmed operations. Abandon only after rechecking Run status, live agents, non-terminal tasks, and activity; cleanup requires a second confirmation and may remove only `{run_dir}/work/team`, never `run.json`, `outputs/`, artifacts, evidence, or Session metadata.
89
+ 7. Reopen the saved assignment batch for this iteration. Match each task with its roster entry, callback and artifact. Wait for live workers and retain completed work. Retry only a missing or failed assignment. For LLM scoring, recover the scorer job and score file before updating. If `pheromone/updates/<k>.json` exists, use its `scoring` value for replay (`fallback` requires `--allow-score-fallback`). Continue with the controller's committed iteration.
90
+
91
+ ---
92
+
93
+ ## Phase 1: Task Analysis + Config Generation
94
+
95
+ **Objective**: Translate user task into `swarm-config.json`.
96
+
97
+ **Workflow**:
98
+
99
+ 1. Parse user task description (text-level only, no codebase exploration)
100
+ 2. Clarify via request_user_input if ambiguous:
101
+ - What is the search space? (file glob, explicit node list, abstract decisions)
102
+ - What is the objective? (find best X, discover Y, optimize Z)
103
+ - How should results be scored? (test pass rate, lint, custom rule, LLM judge)
104
+ - Budget? (max iterations, max ants per iter, token budget)
105
+ 3. Generate `swarm-config.json` (see template at `specs/swarm-config-template.json`):
106
+ - `swarm.n_ants` (default 5)
107
+ - `swarm.max_iterations` -> mirrored into `convergence.max_iterations`
108
+ - `aco.alpha/beta/rho/q` (defaults sane)
109
+ - `task_space.nodes` OR `task_space.auto_discover_from`
110
+ - `scoring.mode` ∈ {script, llm, fallback} based on user answer
111
+ - `ant_prompt.objective` — the actual goal injected into ant role-spec at spawn
112
+ 4. Keep config in memory until the Run birth packet provides the exact `run_dir` (self-start Run allocation is the first action of Phase 2). Never write into a guessed Run directory.
113
+
114
+ **CRITICAL**: Phase 1 does NOT call `aco.py`. It only produces the config.
115
+
116
+ ---
117
+
118
+ ## Phase 2: Init Swarm + Session Setup
119
+
120
+ Delegate to `@commands/init-swarm.md`:
121
+
122
+ 1. Resolve or self-start the exact Session/Run as described in `init-swarm.md` before any Run-scoped file write.
123
+ 2. Create session folder structure:
124
+ ```
125
+ {run_dir}/work/team/
126
+ ├── swarm-config.json (from Phase 1)
127
+ ├── pheromone/, trails/, scores/, artifacts/, wisdom/
128
+ ├── .msg/
129
+ └── role-binding.json (paths to role.md files)
130
+ ```
131
+ 3. TeamCreate with team_name = `swarm`
132
+ 4. Bash: `python <skill_root>/scripts/aco.py --session {run_dir}/work/team --run-dir <run_dir> init`
133
+ 5. Parse stdout JSON: capture `n_nodes`, `n_edges`, `pheromone_path`
134
+ 6. Initialize team-session.json with `iteration: 0`, `status: "active"`
135
+ 7. Record the config summary in team-session.json
136
+
137
+ ### Run Lifecycle Integration
138
+
139
+ Before creating the session folder or writing `swarm-config.json`:
140
+
141
+ 1. **Resolve Run** (birth-packet first): if the dispatch context already carries `run_id` / `run_dir` (injected by an orchestrator), retain them in memory and persist them at init-swarm Step 7 after creating the parent directory; skip self-start — a second allocation mints a duplicate Run. Otherwise execute this receipt-chained self-start recipe; every revision comes from the immediately preceding receipt and `--actor` carries the authorized identity (`--participant` defaults to it; the CLI derives a stable request ID per distinct invocation):
142
+ ```bash
143
+ evolve session open "<task summary>" --id <slug> --actor {actor_id} --json
144
+ evolve session chain insert --session {session_id} --step-id {step_id} --command team-swarm --arg "<task summary>" --actor {actor_id} --expected-orchestration-revision {open_orchestration_revision} --json
145
+ evolve run next --session {session_id} --actor {actor_id} --expected-orchestration-revision {insert_orchestration_revision} --json
146
+ ```
147
+ - Slug format: `YYYYMMDD-team-swarm-<topic>` (ASCII, ≤64 chars)
148
+ - Store returned canonical `session_id`, `run_id`, and `run_dir` in `team-session.json`:
149
+ ```json
150
+ "run": { "session_id": "<canonical-session-id>", "run_id": "<id>", "run_dir": "<path>" }
151
+ ```
152
+ 2. **Resume**: Resolve exact `session_id` + `run_id` + `run_dir` from the birth packet or `team-session.json.run`; never infer a Run ID from output files. Read `evolve run check <run_id> --session <session_id> --json` for status/output blockers, then `evolve run brief <run_id> --session <session_id> --json` for the structured `continuation`. If sealed, follow the brief's continuation; allocate another Run only through a freshly fenced `run next` when it reports a pending step. If the locator is absent or inconsistent, fail closed rather than minting a duplicate Run.
153
+
154
+ ---
155
+
156
+ ## Phase 3: Iteration Loop
157
+
158
+ **Objective**: Run iteration k = 1..K. Each iteration = spawn-and-stop + callback resume.
159
+
160
+ **Per-iteration workflow** (delegate to `@commands/iterate.md`):
161
+
162
+ 1. Increment iteration counter: k = session.iteration + 1
163
+ 2. Bash: `python aco.py --session {run_dir}/work/team select --iter <k>`
164
+ -> returns `{assignments: [{ant_id, start_node, edge_preferences, max_path_length}, ...]}`
165
+ 3. For each assignment:
166
+ - update_plan `ANT-<k>-<i>` with description including session path + assignment
167
+ - update_plan set owner = `ant`
168
+ 4. Spawn N × team-worker(ant) in background, each with assignment injected into prompt:
169
+ ```
170
+ role: ant
171
+ role_spec: <skill_root>/roles/ant/role.md
172
+ session: {run_dir}/work/team
173
+ session_id: <run-id>
174
+ run_dir: <exact run_dir from the birth packet or team-session.json.run.run_dir>
175
+ team_name: swarm
176
+ requirement: <ant_prompt.objective> | Assignment: <full assignment JSON>
177
+ inner_loop: false
178
+ ```
179
+ 5. STOP
180
+
181
+ **On all-ants-complete callback** (Phase 3.5):
182
+
183
+ 1. Verify all `ANT-<k>-*` tasks have status = completed
184
+ 2. (Optional, if `scoring.mode == "llm"`) Spawn scorer worker for iteration k, await callback
185
+ 3. Bash: `python aco.py --session {run_dir}/work/team --run-dir <run_dir> update --iter <k>`
186
+ -> parse `{best_score, mean_score, delta, hallucinations_flagged, ...}`
187
+ 4. Bash: `python aco.py --session {run_dir}/work/team converged`
188
+ -> parse `{converged, triggered_by, reason, metrics}`
189
+ 5. Update session.iteration = k, log state_update
190
+ 6. Branch:
191
+ - `converged == true` -> Phase 4
192
+ - `converged == false` -> loop back to step 1 (iteration k+1)
193
+
194
+ ---
195
+
196
+ ## Phase 4: Converge + Synthesize
197
+
198
+ Delegate to `@commands/converge.md`:
199
+
200
+ 1. Bash: `python aco.py --session {run_dir}/work/team --run-dir <run_dir> report` -> capture best + top_k + curve
201
+ 2. Spawn analyst worker:
202
+ ```
203
+ role: analyst
204
+ role_spec: <skill_root>/roles/analyst/role.md
205
+ requirement: synthesize swarm results | session: {run_dir}/work/team
206
+ ```
207
+ 3. Await analyst callback -> `best-solution.md` written
208
+ 4. Build completion report:
209
+ - Total iterations, total ants
210
+ - Best score + best path + best solution summary
211
+ - Convergence reason
212
+ - Top 5 trails table
213
+ 5. Execute completion action (interactive request_user_input: Archive / Keep / Export)
214
+
215
+ ---
216
+
217
+ ## Error Handling
218
+
219
+ | Error | Resolution |
220
+ |-------|------------|
221
+ | `aco.py` exits non-zero | Capture stderr, log to issues.md, retry once with same args |
222
+ | Ant produces invalid JSON | Script's `update` skips that artifact + logs warning; coordinator continues |
223
+ | All ants in iteration fail | Halt loop, request_user_input (retry / abort) |
224
+ | Convergence flag never trips | max_iterations safety net always triggers |
225
+ | Script not found | Resolve `<skill_root>/scripts/aco.py`; if missing, fail with install hint |
226
+ | Hallucination cluster (>50% ants flagged) | Pause, request_user_input (continue / refine config) |
227
+ | Task description too vague | request_user_input before Phase 1 config generation |
228
+ | Session corruption | Phase 0 reconciliation; if irrecoverable, archive and start fresh |
@@ -0,0 +1,150 @@
1
+ ---
2
+ role: scorer
3
+ prefix: SCORE
4
+ inner_loop: false
5
+ output_tag: "[scorer]"
6
+ message_types:
7
+ ---
8
+
9
+ # Scorer Role — Phase 2-4
10
+
11
+ ## Boundaries
12
+
13
+ ### MUST
14
+ - Read ALL `ant-<iter>-*.json` artifacts for the target iteration
15
+ - Apply a uniform scoring rubric across the batch (consistency over absolute correctness)
16
+ - Produce `{run_dir}/work/team/scores/iter-<k>-scores.json` matching the schema in specs/ant-output-schema.md
17
+ - Provide a one-line `rationale` per ant
18
+ - Use a different model from the ant if possible (configured via evolve delegate) to reduce same-source bias
19
+
20
+ ### MUST NOT
21
+ - Modify ant artifacts
22
+ - Score ants outside the target iteration
23
+ - Use self_score as a starting reference (introduces anchoring bias) — score blind first, compare second
24
+ - Assign scores without grounding in evidence claimed by the ant
25
+
26
+ ## Phase 2: Context Loading
27
+
28
+ | Input | Source | Required |
29
+ |-------|--------|----------|
30
+ | Target iteration | Task description (`Iteration to score: <k>`) | Yes |
31
+ | Objective | `{run_dir}/work/team/swarm-config.json#ant_prompt.objective` | Yes |
32
+ | Scoring rubric | `{run_dir}/work/team/swarm-config.json#scoring.rubric` (if defined) | Optional |
33
+ | Ant artifacts | `{run_dir}/outputs/ant-<k>-*.json` | Yes |
34
+ | Task space | `{run_dir}/work/team/task-space.json` (for context) | Optional |
35
+
36
+ Workflow:
37
+ 1. Extract `k` from task description
38
+ 2. `Glob("{run_dir}/outputs/ant-<k>-*.json")` -> N artifacts
39
+ 3. Read all N artifacts in parallel
40
+ 4. Read swarm-config.json -> capture objective + rubric
41
+
42
+ ## Phase 3: Blind Batch Scoring
43
+
44
+ ### 3.1 Build rubric
45
+
46
+ If `config.scoring.rubric` provided, use verbatim. Otherwise default rubric:
47
+
48
+ | Dimension | Weight |
49
+ |-----------|--------|
50
+ | Path relevance to objective | 0.35 |
51
+ | Evidence strength (count + specificity) | 0.30 |
52
+ | Candidate solution quality | 0.25 |
53
+ | Path coherence (decisions follow logical chain) | 0.10 |
54
+
55
+ ### 3.2 Score each artifact
56
+
57
+ For each ant artifact (process them blind to self_score order):
58
+
59
+ 1. Extract: `path`, `path_decisions[].rationale`, `evidence`, `candidate_solution`
60
+ 2. **Do NOT read** `self_score` / `self_confidence` until after scoring
61
+ 3. Apply rubric:
62
+ - Each dimension -> 0.0..1.0
63
+ - Weighted sum -> `verified_score`
64
+ 4. One-line rationale: which dimensions drove the score
65
+ 5. Append to scores dict
66
+
67
+ ### 3.3 Calibrate across batch
68
+
69
+ After all individual scores:
70
+ - Compute mean + std of verified_scores
71
+ - If all scores within ±0.05 (compressed range) -> spread them apart by re-ranking with finer rubric application
72
+ - If exactly one is 1.0 and rest are < 0.3 -> double-check the outlier
73
+
74
+ ### 3.4 Compose scores file
75
+
76
+ ```json
77
+ {
78
+ "iteration": <k>,
79
+ "scorer_type": "llm",
80
+ "rubric_used": "default | custom_from_config",
81
+ "scores": {
82
+ "ANT-<k>-1": { "verified_score": <float>, "rationale": "<one-line>" },
83
+ "ANT-<k>-2": { "verified_score": <float>, "rationale": "<one-line>" },
84
+ ...
85
+ },
86
+ "calibration": {
87
+ "mean": <float>,
88
+ "std": <float>,
89
+ "min": <float>,
90
+ "max": <float>
91
+ },
92
+ "computed_at": "<iso8601>"
93
+ }
94
+ ```
95
+
96
+ ## Phase 4: Verify + Publish
97
+
98
+ ### Behavioral Traits
99
+
100
+ #### Accuracy
101
+ - Every `verified_score` in [0.0, 1.0]
102
+ - Every `ANT-<k>-i` in the input set has a score entry
103
+ - `rationale` references at least one dimension of the rubric
104
+
105
+ #### Feedback Contract
106
+ | Field | Required | Content |
107
+ |-------|----------|---------|
108
+ | artifacts_written | Always | `{run_dir}/work/team/scores/iter-<k>-scores.json` |
109
+ | n_ants_scored | Always | int |
110
+ | verification_method | Always | "blind_then_calibrated + range_check" |
111
+
112
+ #### Quality Gate
113
+ - All N ant artifacts must have a score entry — partial scoring is NOT acceptable
114
+ - If a single artifact is unparseable -> assign verified_score = 0.0 with rationale "artifact_invalid", continue
115
+ - Validation fails -> retry Phase 3 once
116
+
117
+ ### Verification Steps
118
+
119
+ 1. Re-read the scores file via Read
120
+ 2. Parse JSON, validate schema
121
+ 3. Confirm `len(scores) == n_ants_in_iteration`
122
+ 4. Confirm score range
123
+ 5. Write hallucination delta to wisdom for coordinator visibility:
124
+ - For each ant, compute `delta = |self_score - verified_score|`
125
+ - If `delta > 0.4` for >50% of ants in this iter -> append warning to `{run_dir}/work/team/wisdom/issues.md`
126
+
127
+ ### State Update
128
+
129
+ ```json
130
+ {
131
+ "task_id": "SCORE-<k>",
132
+ "role": "scorer",
133
+ "status": "completed",
134
+ "iteration": <k>,
135
+ "n_ants_scored": <N>,
136
+ "mean_verified_score": <float>,
137
+ "artifact_path": "{run_dir}/work/team/scores/iter-<k>-scores.json",
138
+ "verification": "blind_scored + schema_validated"
139
+ }
140
+ ```
141
+
142
+ ## Error Handling
143
+
144
+ | Scenario | Resolution |
145
+ |----------|------------|
146
+ | No artifacts found for iteration | Report error - coordinator either misrouted or ants all failed |
147
+ | Artifact parse fails | Score = 0.0, rationale = "artifact_invalid", continue |
148
+ | Rubric ambiguous for a path | Default to 0.5 with rationale "rubric_uncertain", lower confidence in calibration |
149
+ | All scores identical | Force differentiation via secondary tiebreaker (path length, evidence count) |
150
+ | Scores file write fails | Retry; on second failure report blocker |