self-evolving-workflow 0.0.0-stage → 0.1.4

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 (375) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +195 -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 +473 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/codex-memory.d.ts +24 -0
  12. package/dist/codex-memory.js +217 -0
  13. package/dist/common.d.ts +16 -0
  14. package/dist/common.js +52 -0
  15. package/dist/context-envelope.d.ts +59 -0
  16. package/dist/context-envelope.js +23 -0
  17. package/dist/host-adapters.d.ts +34 -0
  18. package/dist/host-adapters.js +151 -0
  19. package/dist/http.d.ts +3 -0
  20. package/dist/http.js +90 -0
  21. package/dist/index.d.ts +16 -0
  22. package/dist/index.js +13 -0
  23. package/dist/knowledge-cli.d.ts +198 -0
  24. package/dist/knowledge-cli.js +761 -0
  25. package/dist/knowledge-reads.d.ts +72 -0
  26. package/dist/knowledge-reads.js +201 -0
  27. package/dist/memory-config.d.ts +44 -0
  28. package/dist/memory-config.js +204 -0
  29. package/dist/memory-evidence.d.ts +13 -0
  30. package/dist/memory-evidence.js +40 -0
  31. package/dist/memory-history.d.ts +46 -0
  32. package/dist/memory-history.js +432 -0
  33. package/dist/memory.d.ts +96 -0
  34. package/dist/memory.js +362 -0
  35. package/dist/retrospective.d.ts +57 -0
  36. package/dist/retrospective.js +240 -0
  37. package/dist/search.d.ts +36 -0
  38. package/dist/search.js +112 -0
  39. package/dist/skill-addition.d.ts +25 -0
  40. package/dist/skill-addition.js +89 -0
  41. package/dist/skill-design.d.ts +96 -0
  42. package/dist/skill-design.js +226 -0
  43. package/dist/skill-replay.d.ts +55 -0
  44. package/dist/skill-replay.js +448 -0
  45. package/dist/skill-route.d.ts +30 -0
  46. package/dist/skill-route.js +75 -0
  47. package/dist/transcript-evidence.d.ts +3 -0
  48. package/dist/transcript-evidence.js +58 -0
  49. package/dist/upstream/chunker.d.ts +24 -0
  50. package/dist/upstream/chunker.js +96 -0
  51. package/dist/upstream/file-protocol.d.ts +45 -0
  52. package/dist/upstream/file-protocol.js +117 -0
  53. package/dist/upstream/frontmatter.d.ts +47 -0
  54. package/dist/upstream/frontmatter.js +86 -0
  55. package/dist/upstream/graph-search.d.ts +33 -0
  56. package/dist/upstream/graph-search.js +67 -0
  57. package/dist/upstream/l1-extraction.d.ts +26 -0
  58. package/dist/upstream/l1-extraction.js +405 -0
  59. package/dist/upstream/llm.d.ts +8 -0
  60. package/dist/upstream/llm.js +1 -0
  61. package/dist/upstream/merge.d.ts +50 -0
  62. package/dist/upstream/merge.js +153 -0
  63. package/dist/upstream/prompts.d.ts +53 -0
  64. package/dist/upstream/prompts.js +181 -0
  65. package/dist/upstream/search-utils.d.ts +34 -0
  66. package/dist/upstream/search-utils.js +55 -0
  67. package/dist/upstream/slug.d.ts +26 -0
  68. package/dist/upstream/slug.js +103 -0
  69. package/dist/upstream/template.d.ts +29 -0
  70. package/dist/upstream/template.js +80 -0
  71. package/dist/upstream/tokenize.d.ts +4 -0
  72. package/dist/upstream/tokenize.js +29 -0
  73. package/dist/wiki-change.d.ts +76 -0
  74. package/dist/wiki-change.js +299 -0
  75. package/dist/wiki-entry.d.ts +26 -0
  76. package/dist/wiki-entry.js +93 -0
  77. package/dist/wiki-ingest.d.ts +12 -0
  78. package/dist/wiki-ingest.js +126 -0
  79. package/dist/wiki-migration.d.ts +16 -0
  80. package/dist/wiki-migration.js +268 -0
  81. package/dist/wiki-tokens.d.ts +1 -0
  82. package/dist/wiki-tokens.js +46 -0
  83. package/dist/wiki.d.ts +103 -0
  84. package/dist/wiki.js +330 -0
  85. package/dist/workflow-cli.d.ts +2 -0
  86. package/dist/workflow-cli.js +319 -0
  87. package/dist/workflow-install.d.ts +37 -0
  88. package/dist/workflow-install.js +148 -0
  89. package/dist/workflow-knowledge.d.ts +18 -0
  90. package/dist/workflow-knowledge.js +32 -0
  91. package/dist/workflow-mcp.d.ts +2 -0
  92. package/dist/workflow-mcp.js +137 -0
  93. package/dist/workflow-names.d.ts +4 -0
  94. package/dist/workflow-names.js +31 -0
  95. package/dist/workflow-runtime.d.ts +735 -0
  96. package/dist/workflow-runtime.js +747 -0
  97. package/dist/workflow-skills.d.ts +48 -0
  98. package/dist/workflow-skills.js +141 -0
  99. package/docs/images/impeccable-skill.png +0 -0
  100. package/docs/images/workflow-overview.png +0 -0
  101. package/docs/images/workflow-skills.png +0 -0
  102. package/package.json +77 -4
  103. package/skills/ew-impeccable/LICENSE +191 -0
  104. package/skills/ew-impeccable/NOTICE.md +19 -0
  105. package/skills/ew-impeccable/SKILL.md +91 -0
  106. package/skills/ew-impeccable/UPSTREAM.md +23 -0
  107. package/skills/ew-impeccable/reference/adapt.md +314 -0
  108. package/skills/ew-impeccable/reference/adapt.native.md +60 -0
  109. package/skills/ew-impeccable/reference/android.md +46 -0
  110. package/skills/ew-impeccable/reference/animate.md +91 -0
  111. package/skills/ew-impeccable/reference/audit.md +138 -0
  112. package/skills/ew-impeccable/reference/audit.native.md +141 -0
  113. package/skills/ew-impeccable/reference/bolder.md +35 -0
  114. package/skills/ew-impeccable/reference/clarify.md +96 -0
  115. package/skills/ew-impeccable/reference/colorize.md +88 -0
  116. package/skills/ew-impeccable/reference/craft-floor.md +44 -0
  117. package/skills/ew-impeccable/reference/craft.md +5 -0
  118. package/skills/ew-impeccable/reference/critique.md +808 -0
  119. package/skills/ew-impeccable/reference/degraded/asset-producer.md +36 -0
  120. package/skills/ew-impeccable/reference/degraded/documenter.md +23 -0
  121. package/skills/ew-impeccable/reference/degraded/finish-reviewer.md +72 -0
  122. package/skills/ew-impeccable/reference/degraded/manual-edit-applier.md +91 -0
  123. package/skills/ew-impeccable/reference/delight.md +72 -0
  124. package/skills/ew-impeccable/reference/distill.md +113 -0
  125. package/skills/ew-impeccable/reference/doctor.md +56 -0
  126. package/skills/ew-impeccable/reference/document.md +418 -0
  127. package/skills/ew-impeccable/reference/extract.md +68 -0
  128. package/skills/ew-impeccable/reference/harden.md +338 -0
  129. package/skills/ew-impeccable/reference/hooks.md +113 -0
  130. package/skills/ew-impeccable/reference/init.md +133 -0
  131. package/skills/ew-impeccable/reference/ios.md +51 -0
  132. package/skills/ew-impeccable/reference/layout.md +86 -0
  133. package/skills/ew-impeccable/reference/live-setup.md +102 -0
  134. package/skills/ew-impeccable/reference/live.md +326 -0
  135. package/skills/ew-impeccable/reference/new-work.md +209 -0
  136. package/skills/ew-impeccable/reference/onboard.md +236 -0
  137. package/skills/ew-impeccable/reference/operate.md +61 -0
  138. package/skills/ew-impeccable/reference/optimize.md +260 -0
  139. package/skills/ew-impeccable/reference/overdrive.md +127 -0
  140. package/skills/ew-impeccable/reference/polish.md +105 -0
  141. package/skills/ew-impeccable/reference/quieter.md +101 -0
  142. package/skills/ew-impeccable/reference/routing.md +20 -0
  143. package/skills/ew-impeccable/reference/shape.md +59 -0
  144. package/skills/ew-impeccable/reference/typeset.md +82 -0
  145. package/skills/ew-impeccable/reference/visualize.md +46 -0
  146. package/skills/ew-impeccable/scripts/build-phase.mjs +1022 -0
  147. package/skills/ew-impeccable/scripts/command-metadata.json +94 -0
  148. package/skills/ew-impeccable/scripts/comp-diff.mjs +391 -0
  149. package/skills/ew-impeccable/scripts/comp-spec.mjs +513 -0
  150. package/skills/ew-impeccable/scripts/concept-seed.mjs +814 -0
  151. package/skills/ew-impeccable/scripts/context-signals.mjs +325 -0
  152. package/skills/ew-impeccable/scripts/context.mjs +1521 -0
  153. package/skills/ew-impeccable/scripts/critique-storage.mjs +473 -0
  154. package/skills/ew-impeccable/scripts/data/font-index-failures.json +121 -0
  155. package/skills/ew-impeccable/scripts/data/font-index.json +1 -0
  156. package/skills/ew-impeccable/scripts/detect-csp.mjs +246 -0
  157. package/skills/ew-impeccable/scripts/detect.mjs +30 -0
  158. package/skills/ew-impeccable/scripts/detector/browser/injected/index.mjs +2580 -0
  159. package/skills/ew-impeccable/scripts/detector/cli/main.mjs +498 -0
  160. package/skills/ew-impeccable/scripts/detector/design-system.mjs +1311 -0
  161. package/skills/ew-impeccable/scripts/detector/detect-antipatterns-browser.js +9486 -0
  162. package/skills/ew-impeccable/scripts/detector/detect-antipatterns.mjs +51 -0
  163. package/skills/ew-impeccable/scripts/detector/engines/browser/detect-url.mjs +434 -0
  164. package/skills/ew-impeccable/scripts/detector/engines/regex/detect-text.mjs +1439 -0
  165. package/skills/ew-impeccable/scripts/detector/engines/static-html/css-cascade.mjs +1242 -0
  166. package/skills/ew-impeccable/scripts/detector/engines/static-html/detect-html.mjs +263 -0
  167. package/skills/ew-impeccable/scripts/detector/engines/visual/screenshot-contrast.mjs +189 -0
  168. package/skills/ew-impeccable/scripts/detector/findings.mjs +23 -0
  169. package/skills/ew-impeccable/scripts/detector/node/file-system.mjs +225 -0
  170. package/skills/ew-impeccable/scripts/detector/profile/profiler.mjs +166 -0
  171. package/skills/ew-impeccable/scripts/detector/registry/antipatterns.mjs +636 -0
  172. package/skills/ew-impeccable/scripts/detector/rules/checks.mjs +5750 -0
  173. package/skills/ew-impeccable/scripts/detector/shared/color.mjs +596 -0
  174. package/skills/ew-impeccable/scripts/detector/shared/constants.mjs +127 -0
  175. package/skills/ew-impeccable/scripts/detector/shared/fonts.mjs +30 -0
  176. package/skills/ew-impeccable/scripts/detector/shared/inline-ignores.mjs +148 -0
  177. package/skills/ew-impeccable/scripts/detector/shared/page.mjs +7 -0
  178. package/skills/ew-impeccable/scripts/detector/vendor/MDN-DATA-LICENSE +116 -0
  179. package/skills/ew-impeccable/scripts/detector/vendor/THIRD_PARTY_LICENSES.md +227 -0
  180. package/skills/ew-impeccable/scripts/detector/vendor/static-html-parser.build-entry.txt +11 -0
  181. package/skills/ew-impeccable/scripts/detector/vendor/static-html-parser.bundle.mjs +9121 -0
  182. package/skills/ew-impeccable/scripts/doctor.mjs +330 -0
  183. package/skills/ew-impeccable/scripts/embed-prompt.mjs +166 -0
  184. package/skills/ew-impeccable/scripts/font-match.mjs +457 -0
  185. package/skills/ew-impeccable/scripts/generate-image.mjs +447 -0
  186. package/skills/ew-impeccable/scripts/hook-admin.mjs +829 -0
  187. package/skills/ew-impeccable/scripts/hook-before-edit.mjs +538 -0
  188. package/skills/ew-impeccable/scripts/hook-lib.mjs +2493 -0
  189. package/skills/ew-impeccable/scripts/hook.mjs +79 -0
  190. package/skills/ew-impeccable/scripts/lib/artifact-schema.mjs +93 -0
  191. package/skills/ew-impeccable/scripts/lib/composition-catalog.mjs +200 -0
  192. package/skills/ew-impeccable/scripts/lib/concept-catalog.mjs +395 -0
  193. package/skills/ew-impeccable/scripts/lib/design-parser.mjs +880 -0
  194. package/skills/ew-impeccable/scripts/lib/font-fingerprint.mjs +564 -0
  195. package/skills/ew-impeccable/scripts/lib/font-index.mjs +130 -0
  196. package/skills/ew-impeccable/scripts/lib/hero-checks.mjs +246 -0
  197. package/skills/ew-impeccable/scripts/lib/image-metrics.mjs +306 -0
  198. package/skills/ew-impeccable/scripts/lib/impeccable-config.mjs +640 -0
  199. package/skills/ew-impeccable/scripts/lib/impeccable-paths.mjs +137 -0
  200. package/skills/ew-impeccable/scripts/lib/is-generated.mjs +72 -0
  201. package/skills/ew-impeccable/scripts/lib/live-path-globs.mjs +37 -0
  202. package/skills/ew-impeccable/scripts/lib/open-system-browser.mjs +26 -0
  203. package/skills/ew-impeccable/scripts/lib/png.mjs +281 -0
  204. package/skills/ew-impeccable/scripts/lib/provider.mjs +5 -0
  205. package/skills/ew-impeccable/scripts/lib/raster.mjs +194 -0
  206. package/skills/ew-impeccable/scripts/lib/roll-selection.mjs +369 -0
  207. package/skills/ew-impeccable/scripts/lib/staleness-deep.mjs +491 -0
  208. package/skills/ew-impeccable/scripts/lib/staleness-notice.mjs +169 -0
  209. package/skills/ew-impeccable/scripts/lib/staleness.mjs +532 -0
  210. package/skills/ew-impeccable/scripts/lib/surface-briefs.mjs +149 -0
  211. package/skills/ew-impeccable/scripts/lib/target-args.mjs +42 -0
  212. package/skills/ew-impeccable/scripts/lib/target-slug.mjs +33 -0
  213. package/skills/ew-impeccable/scripts/lib/template-extensions.mjs +146 -0
  214. package/skills/ew-impeccable/scripts/live/accept-css.mjs +617 -0
  215. package/skills/ew-impeccable/scripts/live/accept-verify.mjs +60 -0
  216. package/skills/ew-impeccable/scripts/live/browser-script-parts.mjs +84 -0
  217. package/skills/ew-impeccable/scripts/live/completion.mjs +28 -0
  218. package/skills/ew-impeccable/scripts/live/event-validation.mjs +199 -0
  219. package/skills/ew-impeccable/scripts/live/frameworks/astro.mjs +47 -0
  220. package/skills/ew-impeccable/scripts/live/frameworks/detect-utils.mjs +73 -0
  221. package/skills/ew-impeccable/scripts/live/frameworks/index.mjs +143 -0
  222. package/skills/ew-impeccable/scripts/live/frameworks/journal.mjs +197 -0
  223. package/skills/ew-impeccable/scripts/live/frameworks/nextjs.mjs +49 -0
  224. package/skills/ew-impeccable/scripts/live/frameworks/nuxt.mjs +161 -0
  225. package/skills/ew-impeccable/scripts/live/frameworks/script-src.mjs +17 -0
  226. package/skills/ew-impeccable/scripts/live/frameworks/static-html.mjs +26 -0
  227. package/skills/ew-impeccable/scripts/live/frameworks/sveltekit.mjs +71 -0
  228. package/skills/ew-impeccable/scripts/live/frameworks/tag-strategy.mjs +247 -0
  229. package/skills/ew-impeccable/scripts/live/frameworks/tanstack-start.mjs +70 -0
  230. package/skills/ew-impeccable/scripts/live/frameworks/vite-generic.mjs +42 -0
  231. package/skills/ew-impeccable/scripts/live/generation-preflight.mjs +149 -0
  232. package/skills/ew-impeccable/scripts/live/insert-ui.mjs +458 -0
  233. package/skills/ew-impeccable/scripts/live/instructions.mjs +142 -0
  234. package/skills/ew-impeccable/scripts/live/manual-apply.mjs +939 -0
  235. package/skills/ew-impeccable/scripts/live/manual-edit-routes.mjs +357 -0
  236. package/skills/ew-impeccable/scripts/live/manual-edits-buffer.mjs +152 -0
  237. package/skills/ew-impeccable/scripts/live/poll-lanes.mjs +14 -0
  238. package/skills/ew-impeccable/scripts/live/project-ignores.mjs +139 -0
  239. package/skills/ew-impeccable/scripts/live/roots.mjs +508 -0
  240. package/skills/ew-impeccable/scripts/live/session-store.mjs +563 -0
  241. package/skills/ew-impeccable/scripts/live/source-lock.mjs +105 -0
  242. package/skills/ew-impeccable/scripts/live/source-search.mjs +105 -0
  243. package/skills/ew-impeccable/scripts/live/svelte-ast.mjs +969 -0
  244. package/skills/ew-impeccable/scripts/live/svelte-component.mjs +1366 -0
  245. package/skills/ew-impeccable/scripts/live/sveltekit-adapter.mjs +304 -0
  246. package/skills/ew-impeccable/scripts/live/tanstack-adapter.mjs +259 -0
  247. package/skills/ew-impeccable/scripts/live/ui-surfaces.mjs +75 -0
  248. package/skills/ew-impeccable/scripts/live/vocabulary.mjs +171 -0
  249. package/skills/ew-impeccable/scripts/live-accept.mjs +938 -0
  250. package/skills/ew-impeccable/scripts/live-browser-dom.js +167 -0
  251. package/skills/ew-impeccable/scripts/live-browser-ignores.js +242 -0
  252. package/skills/ew-impeccable/scripts/live-browser-session.js +144 -0
  253. package/skills/ew-impeccable/scripts/live-browser.js +12851 -0
  254. package/skills/ew-impeccable/scripts/live-commit-manual-edits.mjs +1200 -0
  255. package/skills/ew-impeccable/scripts/live-complete.mjs +107 -0
  256. package/skills/ew-impeccable/scripts/live-copy-edit-agent.mjs +800 -0
  257. package/skills/ew-impeccable/scripts/live-discard-manual-edits.mjs +51 -0
  258. package/skills/ew-impeccable/scripts/live-inject.mjs +463 -0
  259. package/skills/ew-impeccable/scripts/live-insert.mjs +292 -0
  260. package/skills/ew-impeccable/scripts/live-manual-edit-evidence.mjs +368 -0
  261. package/skills/ew-impeccable/scripts/live-poll.mjs +430 -0
  262. package/skills/ew-impeccable/scripts/live-resume.mjs +123 -0
  263. package/skills/ew-impeccable/scripts/live-server.mjs +1698 -0
  264. package/skills/ew-impeccable/scripts/live-status.mjs +71 -0
  265. package/skills/ew-impeccable/scripts/live-target.mjs +30 -0
  266. package/skills/ew-impeccable/scripts/live-wrap.mjs +927 -0
  267. package/skills/ew-impeccable/scripts/live.mjs +334 -0
  268. package/skills/ew-impeccable/scripts/modern-screenshot.umd.js +14 -0
  269. package/skills/ew-impeccable/scripts/palette.mjs +628 -0
  270. package/skills/ew-impeccable/scripts/pin.mjs +352 -0
  271. package/skills/ew-impeccable/scripts/serve-question.mjs +1783 -0
  272. package/skills/ew-impeccable/scripts/surface-brief.mjs +74 -0
  273. package/skills/ew-knowledge/SKILL.md +35 -0
  274. package/skills/ew-knowledge/references/closeout-protocol.md +68 -0
  275. package/skills/ew-knowledge/references/knowledge-route.md +73 -0
  276. package/skills/ew-knowledge/references/wiki-maintenance.md +27 -0
  277. package/skills/ew-odyssey/SKILL.md +106 -0
  278. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  279. package/skills/ew-odyssey/references/odyssey-base.md +104 -0
  280. package/skills/ew-odyssey/references/odyssey-debug.md +264 -0
  281. package/skills/ew-odyssey/references/odyssey-defensive.md +351 -0
  282. package/skills/ew-odyssey/references/odyssey-improve.md +230 -0
  283. package/skills/ew-odyssey/references/odyssey-planex.md +294 -0
  284. package/skills/ew-odyssey/references/odyssey-review.md +233 -0
  285. package/skills/ew-odyssey/references/odyssey-security.md +231 -0
  286. package/skills/ew-odyssey/references/odyssey-ui.md +232 -0
  287. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +102 -0
  288. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +117 -0
  289. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +95 -0
  290. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +105 -0
  291. package/skills/ew-odyssey/references/prepare/odyssey-review.md +105 -0
  292. package/skills/ew-odyssey/references/prepare/odyssey-security.md +91 -0
  293. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +88 -0
  294. package/skills/ew-odyssey/references/runtime-adapters.md +31 -0
  295. package/skills/ew-orchestrate/SKILL.md +89 -0
  296. package/skills/ew-orchestrate/references/auto-policy.md +66 -0
  297. package/skills/ew-orchestrate/references/boundary-grill.md +51 -0
  298. package/skills/ew-orchestrate/references/companion-route.md +40 -0
  299. package/skills/ew-orchestrate/references/ew-orchestrate.md +44 -0
  300. package/skills/ew-orchestrate/references/goal.md +51 -0
  301. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +33 -0
  302. package/skills/ew-orchestrate/references/planning.md +54 -0
  303. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +70 -0
  304. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +24 -0
  305. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +8 -0
  306. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +138 -0
  307. package/skills/ew-orchestrate/steps/ew-auto-test/SKILL.md +80 -0
  308. package/skills/ew-orchestrate/steps/ew-auto-test/references/prepare.md +23 -0
  309. package/skills/ew-orchestrate/steps/ew-auto-test/references/workflow.md +31 -0
  310. package/skills/ew-orchestrate/steps/ew-blueprint/SKILL.md +122 -0
  311. package/skills/ew-orchestrate/steps/ew-blueprint/references/prepare.md +21 -0
  312. package/skills/ew-orchestrate/steps/ew-blueprint/references/workflow.md +28 -0
  313. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +49 -0
  314. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +50 -0
  315. package/skills/ew-orchestrate/steps/ew-debug/SKILL.md +85 -0
  316. package/skills/ew-orchestrate/steps/ew-debug/references/prepare.md +27 -0
  317. package/skills/ew-orchestrate/steps/ew-debug/references/workflow.md +31 -0
  318. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +74 -0
  319. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +27 -0
  320. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +87 -0
  321. package/skills/ew-orchestrate/steps/ew-grill/SKILL.md +62 -0
  322. package/skills/ew-orchestrate/steps/ew-grill/references/prepare.md +26 -0
  323. package/skills/ew-orchestrate/steps/ew-grill/references/workflow.md +31 -0
  324. package/skills/ew-orchestrate/steps/ew-init/SKILL.md +56 -0
  325. package/skills/ew-orchestrate/steps/ew-init/references/prepare.md +25 -0
  326. package/skills/ew-orchestrate/steps/ew-init/references/workflow.md +28 -0
  327. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +131 -0
  328. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +8 -0
  329. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  330. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +100 -0
  331. package/skills/ew-orchestrate/steps/ew-retrospective/SKILL.md +68 -0
  332. package/skills/ew-orchestrate/steps/ew-retrospective/references/prepare.md +18 -0
  333. package/skills/ew-orchestrate/steps/ew-retrospective/references/workflow.md +34 -0
  334. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +45 -0
  335. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +17 -0
  336. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +116 -0
  337. package/skills/ew-orchestrate/steps/ew-roadmap/SKILL.md +62 -0
  338. package/skills/ew-orchestrate/steps/ew-roadmap/references/prepare.md +27 -0
  339. package/skills/ew-orchestrate/steps/ew-roadmap/references/workflow.md +28 -0
  340. package/skills/ew-orchestrate/steps/ew-test/SKILL.md +99 -0
  341. package/skills/ew-orchestrate/steps/ew-test/references/prepare.md +23 -0
  342. package/skills/ew-orchestrate/steps/ew-test/references/workflow.md +23 -0
  343. package/skills/ew-orchestrate/steps/ew-verify/SKILL.md +73 -0
  344. package/skills/ew-orchestrate/steps/ew-verify/references/prepare.md +21 -0
  345. package/skills/ew-orchestrate/steps/ew-verify/references/workflow.md +29 -0
  346. package/skills/ew-skill-design/SKILL.md +30 -0
  347. package/skills/ew-skill-design/references/package-contract.md +40 -0
  348. package/skills/ew-skill-design/references/validation.md +21 -0
  349. package/skills/team-swarm/SKILL.md +68 -0
  350. package/skills/team-swarm/references/mcp-coordination.md +14 -0
  351. package/skills/team-swarm/roles/analyst/role.md +181 -0
  352. package/skills/team-swarm/roles/ant/role.md +149 -0
  353. package/skills/team-swarm/roles/coordinator/commands/converge.md +112 -0
  354. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +136 -0
  355. package/skills/team-swarm/roles/coordinator/commands/iterate.md +171 -0
  356. package/skills/team-swarm/roles/coordinator/role.md +170 -0
  357. package/skills/team-swarm/roles/scorer/role.md +150 -0
  358. package/skills/team-swarm/scripts/aco.py +646 -0
  359. package/skills/team-swarm/scripts/pheromone.py +144 -0
  360. package/skills/team-swarm/scripts/scoring.py +111 -0
  361. package/skills/team-swarm/scripts/test_aco.py +606 -0
  362. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  363. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  364. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  365. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  366. package/skills/team-swarm/specs/swarm-protocol.md +119 -0
  367. package/skills/workflow-evolve/SKILL.md +64 -0
  368. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  369. package/skills/workflow-evolve/references/auto-loop.md +23 -0
  370. package/skills/workflow-evolve/references/history-review.md +15 -0
  371. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +86 -0
  372. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  373. package/skills/workflow-evolve/scripts/evolve-loop.mjs +260 -0
  374. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  375. package/workflows/index.json +33 -0
@@ -0,0 +1,646 @@
1
+ """ACO controller CLI - the script side of team-swarm.
2
+
3
+ Subcommands: init | select | update | converged | report
4
+ Spec: ../specs/swarm-protocol.md (script <-> coordinator contract)
5
+
6
+ All commands:
7
+ - read state from --session <path>
8
+ - emit JSON to stdout
9
+ - exit 0 success, 1 runtime error, 2 config invalid
10
+
11
+ Invoked by team-swarm coordinator via Bash. No prose output, no interactive prompts.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import argparse
16
+ import glob
17
+ import hashlib
18
+ import json
19
+ import os
20
+ import random
21
+ import re
22
+ import sys
23
+ import tempfile
24
+ import time
25
+ from contextlib import contextmanager
26
+ from pathlib import Path
27
+ from typing import List, Optional
28
+
29
+ # Local imports (script directory)
30
+ sys.path.insert(0, str(Path(__file__).parent))
31
+ from pheromone import PheromoneState # noqa: E402
32
+ from scoring import ( # noqa: E402
33
+ FallbackScorer,
34
+ ScriptScorer,
35
+ hallucination_check,
36
+ load_verified_scores,
37
+ resolve_score,
38
+ )
39
+
40
+ VERSION = "1.0"
41
+
42
+
43
+ # ---------------------------------------------------------------------------
44
+ # Session paths
45
+ # ---------------------------------------------------------------------------
46
+
47
+ class SessionPaths:
48
+ def __init__(self, session: Path, run_dir: Optional[Path] = None):
49
+ self.session = session
50
+ self.config = session / "swarm-config.json"
51
+ self.pheromone_dir = session / "pheromone"
52
+ self.pheromone_current = self.pheromone_dir / "current.json"
53
+ self.pheromone_init = self.pheromone_dir / "init.json"
54
+ self.pheromone_history = self.pheromone_dir / "history"
55
+ self.task_space = session / "task-space.json"
56
+ self.trails = session / "trails"
57
+ self.artifacts = session / "artifacts"
58
+ self.scores = session / "scores"
59
+ self.assignments = session / "assignments"
60
+ self.best = session / "best.json"
61
+ self.updates = self.pheromone_dir / "updates"
62
+ # run session: formal deliverables live in {run_dir}/outputs/
63
+ self.run_dir = run_dir
64
+ self.outputs = (run_dir / "outputs") if run_dir else self.artifacts
65
+
66
+ def ensure_dirs(self) -> None:
67
+ for d in [self.pheromone_dir, self.pheromone_history, self.trails, self.artifacts, self.scores]:
68
+ d.mkdir(parents=True, exist_ok=True)
69
+
70
+
71
+ def _emit(payload: dict) -> None:
72
+ print(json.dumps(payload, ensure_ascii=False))
73
+
74
+
75
+ def _fail(code: int, msg: str):
76
+ _emit({"status": "error", "message": msg})
77
+ sys.exit(code)
78
+
79
+
80
+ def _json(value: object) -> str:
81
+ return json.dumps(value, ensure_ascii=False, indent=2, allow_nan=False, sort_keys=True)
82
+
83
+
84
+ def _write_atomic(path: Path, content: str) -> None:
85
+ path.parent.mkdir(parents=True, exist_ok=True)
86
+ fd, temporary = tempfile.mkstemp(dir=path.parent)
87
+ try:
88
+ with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as file:
89
+ file.write(content)
90
+ file.flush()
91
+ os.fsync(file.fileno())
92
+ os.replace(temporary, path)
93
+ finally:
94
+ Path(temporary).unlink(missing_ok=True)
95
+
96
+
97
+ @contextmanager
98
+ def _controller_lock(session: Path):
99
+ with (session / ".aco.lock").open("a+b") as lock:
100
+ if os.name == "nt":
101
+ from msvcrt import locking, LK_NBLCK
102
+ lock.seek(0)
103
+ locking(lock.fileno(), LK_NBLCK, 1)
104
+ else:
105
+ from fcntl import flock, LOCK_EX, LOCK_NB
106
+ flock(lock.fileno(), LOCK_EX | LOCK_NB)
107
+ yield
108
+
109
+
110
+ def _project_update(paths: SessionPaths, iteration: int, receipt: dict) -> None:
111
+ if receipt["best"] is not None:
112
+ _write_atomic(paths.best, _json(receipt["best"]))
113
+ state = _json(receipt["state"])
114
+ _write_atomic(paths.pheromone_history / f"{iteration}.json", state)
115
+ trails = "\n".join(json.dumps(line, ensure_ascii=False, sort_keys=True) for line in receipt["trails"])
116
+ _write_atomic(paths.trails / f"{iteration}.jsonl", trails)
117
+ _write_atomic(paths.pheromone_current, state)
118
+
119
+ # ---------------------------------------------------------------------------
120
+ # init
121
+ # ---------------------------------------------------------------------------
122
+
123
+ def _discover_nodes(spec: dict) -> List[str]:
124
+ """Resolve task_space.nodes — supports explicit list or auto_discover_from glob."""
125
+ if isinstance(spec.get("nodes"), list):
126
+ return [str(n) for n in spec["nodes"]]
127
+ if "auto_discover_from" in spec:
128
+ pattern = spec["auto_discover_from"]
129
+ # Glob relative to cwd (workspace root), not session
130
+ matches = sorted(glob.glob(pattern, recursive=True))
131
+ if not matches:
132
+ raise ValueError(f"auto_discover_from '{pattern}' matched no files")
133
+ return matches
134
+ raise ValueError("task_space requires either 'nodes' list or 'auto_discover_from' glob")
135
+
136
+
137
+ def _run_dir(args: argparse.Namespace) -> Optional[Path]:
138
+ rd = getattr(args, "run_dir", None)
139
+ return Path(rd) if rd else None
140
+
141
+
142
+ def cmd_init(args: argparse.Namespace) -> None:
143
+ paths = SessionPaths(Path(args.session), _run_dir(args))
144
+ if not paths.config.exists():
145
+ _fail(2, f"config not found: {paths.config}")
146
+ if paths.pheromone_current.is_file() and PheromoneState.load(paths.pheromone_current).iteration > 0:
147
+ _fail(1, "cannot reinitialize an active Swarm")
148
+ if paths.run_dir and any(paths.assignments.glob("*.json")):
149
+ _fail(1, "cannot reinitialize a Swarm with recorded assignments")
150
+ config = json.loads(paths.config.read_text(encoding="utf-8"))
151
+
152
+ paths.ensure_dirs()
153
+
154
+ try:
155
+ nodes = _discover_nodes(config.get("task_space", {}))
156
+ except ValueError as e:
157
+ _fail(2, str(e))
158
+ return # unreachable, satisfies type checker
159
+
160
+ # Write task-space.json
161
+ task_space = {
162
+ "nodes": nodes,
163
+ "n_nodes": len(nodes),
164
+ "max_path_length": config.get("task_space", {}).get("max_path_length", 5),
165
+ "start_nodes": config.get("task_space", {}).get("start_nodes", "any"),
166
+ "edges": config.get("task_space", {}).get("edges", "complete"),
167
+ }
168
+ paths.task_space.write_text(json.dumps(task_space, indent=2, ensure_ascii=False), encoding="utf-8")
169
+
170
+ # Initialize pheromone
171
+ aco_cfg = config.get("aco", {})
172
+ state = PheromoneState.initialize(nodes, aco_cfg)
173
+ state.save(paths.pheromone_current)
174
+ state.save(paths.pheromone_init)
175
+
176
+ _emit({
177
+ "status": "ok",
178
+ "command": "init",
179
+ "session": str(paths.session),
180
+ "pheromone_path": str(paths.pheromone_current),
181
+ "task_space_path": str(paths.task_space),
182
+ "n_nodes": len(nodes),
183
+ "n_edges": len(state.tau),
184
+ })
185
+
186
+
187
+ # ---------------------------------------------------------------------------
188
+ # select
189
+ # ---------------------------------------------------------------------------
190
+
191
+ def _pick_start_node(nodes: List[str], state: PheromoneState, mode: str) -> str:
192
+ if mode == "weighted":
193
+ weights = [state.node_tau.get(n, 1.0) for n in nodes]
194
+ total = sum(weights)
195
+ if total == 0:
196
+ return random.choice(nodes)
197
+ r = random.uniform(0, total)
198
+ acc = 0.0
199
+ for n, w in zip(nodes, weights):
200
+ acc += w
201
+ if acc >= r:
202
+ return n
203
+ return nodes[-1]
204
+ return random.choice(nodes)
205
+
206
+
207
+ def cmd_select(args: argparse.Namespace) -> None:
208
+ paths = SessionPaths(Path(args.session), _run_dir(args))
209
+ selection = paths.assignments / f"{args.iter}.json"
210
+ if paths.run_dir and selection.is_file():
211
+ _emit(json.loads(selection.read_text(encoding="utf-8")))
212
+ return
213
+ state = PheromoneState.load(paths.pheromone_current)
214
+ if paths.run_dir and args.iter != state.iteration + 1:
215
+ _fail(1, f"expected iteration {state.iteration + 1} for a new assignment batch")
216
+ config = json.loads(paths.config.read_text(encoding="utf-8"))
217
+ task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
218
+
219
+ n_ants = config.get("swarm", {}).get("n_ants", 5)
220
+ nodes = task_space["nodes"]
221
+ max_len = task_space.get("max_path_length", 5)
222
+ start_mode = task_space.get("start_nodes", "any")
223
+
224
+ assignments = []
225
+ for i in range(1, n_ants + 1):
226
+ start = _pick_start_node(nodes, state, "weighted" if start_mode == "weighted" else "uniform")
227
+ edge_prefs = state.select_neighbors(start, nodes)
228
+ # Keep top-k edges to reduce noise
229
+ top_k = sorted(edge_prefs.items(), key=lambda x: -x[1])[:8]
230
+ assignments.append({
231
+ "ant_id": f"ANT-{args.iter}-{i}",
232
+ "start_node": start,
233
+ "edge_preferences": {f"{start}::{b}": w for b, w in top_k},
234
+ "max_path_length": max_len,
235
+ "iteration": args.iter,
236
+ })
237
+
238
+ result = {
239
+ "status": "ok",
240
+ "command": "select",
241
+ "iteration": args.iter,
242
+ "n_assignments": len(assignments),
243
+ "assignments": assignments,
244
+ }
245
+ if paths.run_dir:
246
+ _write_atomic(selection, _json(result))
247
+ _emit(result)
248
+
249
+
250
+ # ---------------------------------------------------------------------------
251
+ # update
252
+ # ---------------------------------------------------------------------------
253
+
254
+ def _load_iteration_artifacts(paths: SessionPaths, iteration: int) -> List[dict]:
255
+ pattern = str(paths.outputs / f"ant-{iteration}-*.json")
256
+ files = sorted(glob.glob(pattern))
257
+ if not files and paths.run_dir and paths.artifacts != paths.outputs:
258
+ pattern = str(paths.artifacts / f"ant-{iteration}-*.json")
259
+ files = sorted(glob.glob(pattern))
260
+ artifacts = []
261
+ for f in files:
262
+ try:
263
+ artifact = json.loads(Path(f).read_text(encoding="utf-8"))
264
+ except json.JSONDecodeError as e:
265
+ if paths.run_dir:
266
+ _fail(1, f"malformed ant artifact: {Path(f).name}")
267
+ print(f"warning: skipped malformed artifact {f}: {e}", file=sys.stderr)
268
+ continue
269
+ if paths.run_dir:
270
+ expected_id = Path(f).stem.upper()
271
+ if not isinstance(artifact, dict) or artifact.get("ant_id") != expected_id:
272
+ _fail(1, f"ant artifact ID must match {Path(f).name}")
273
+ artifacts.append(artifact)
274
+ return artifacts
275
+
276
+
277
+ def _validate_artifact(art: dict, valid_nodes: set, iteration: int, require_meta: bool = False) -> Optional[str]:
278
+ if not isinstance(art, dict):
279
+ return "artifact must be an object"
280
+ if require_meta:
281
+ meta = art.get("_meta")
282
+ if not isinstance(meta, dict):
283
+ return "missing or invalid _meta"
284
+ if (meta.get("kind"), meta.get("schema"), meta.get("role")) != (
285
+ "swarm-ant-result", "swarm-ant-result/1.0", "evidence"
286
+ ):
287
+ return "invalid ant artifact contract"
288
+ required = ["schema_version", "ant_id", "iteration", "path", "self_score", "self_confidence"]
289
+ for f in required:
290
+ if f not in art:
291
+ return f"missing field: {f}"
292
+ if not isinstance(art["path"], list) or not art["path"]:
293
+ return "path must be non-empty list"
294
+ if (art["schema_version"] != "1.0" or type(art["iteration"]) is not int or art["iteration"] != iteration
295
+ or not re.fullmatch(rf"ANT-{iteration}-[1-9][0-9]*", str(art["ant_id"]))):
296
+ return "invalid ant identity, schema or iteration"
297
+ for n in art["path"]:
298
+ if not isinstance(n, str) or n not in valid_nodes:
299
+ return f"path node '{n}' not in task_space"
300
+ for field in ("self_score", "self_confidence"):
301
+ if type(art[field]) not in (int, float) or not 0.0 <= art[field] <= 1.0:
302
+ return f"{field} out of [0,1]"
303
+ if require_meta:
304
+ evidence, solution = art.get("evidence"), art.get("candidate_solution")
305
+ if not isinstance(evidence, list) or not evidence or any(not isinstance(item, str) or not item.strip() for item in evidence):
306
+ return "missing ant evidence"
307
+ if not isinstance(solution, dict) or not isinstance(solution.get("summary"), str) or not solution["summary"].strip():
308
+ return "missing candidate solution"
309
+ decisions, path = art.get("path_decisions"), art["path"]
310
+ if not isinstance(decisions, list) or len(decisions) != len(path) - 1:
311
+ return "path decisions do not match path"
312
+ if any(not isinstance(item, dict) or (item.get("from"), item.get("to")) != (start, end)
313
+ for item, start, end in zip(decisions, path, path[1:])):
314
+ return "path decision endpoints do not match path"
315
+ return None
316
+
317
+
318
+ def cmd_update(args: argparse.Namespace) -> None:
319
+ paths = SessionPaths(Path(args.session), _run_dir(args))
320
+ config = json.loads(paths.config.read_text(encoding="utf-8"))
321
+ state = PheromoneState.load(paths.pheromone_current)
322
+ task_space = json.loads(paths.task_space.read_text(encoding="utf-8"))
323
+ valid_nodes = set(task_space["nodes"])
324
+
325
+ artifacts = _load_iteration_artifacts(paths, args.iter)
326
+ if not artifacts:
327
+ _fail(1, f"no artifacts found for iteration {args.iter}")
328
+
329
+ # Resolve scorers
330
+ scoring_cfg = config.get("scoring", {})
331
+ llm_run = paths.run_dir is not None and scoring_cfg.get("mode") == "llm"
332
+ if args.allow_score_fallback and not llm_run:
333
+ _fail(2, "--allow-score-fallback applies to a Run using llm scoring")
334
+ rule = None
335
+ if scoring_cfg.get("mode") in ("script", "hybrid"):
336
+ rule_path = scoring_cfg.get("script_path")
337
+ if rule_path:
338
+ # Relative scoring scripts belong to the project cwd, not the Run's work/team parent.
339
+ full = Path(rule_path) if Path(rule_path).is_absolute() else Path.cwd() / rule_path
340
+ if not full.is_file():
341
+ _fail(2, f"scoring script not found: {full}")
342
+ rule = full
343
+ fallback = FallbackScorer(scoring_cfg.get("self_score_discount", 0.5))
344
+ score_path = paths.scores / f"iter-{args.iter}-scores.json"
345
+ verified_scores = {} if args.allow_score_fallback else load_verified_scores(
346
+ score_path, iteration=args.iter if llm_run else None)
347
+ selected_path = paths.assignments / f"{args.iter}.json"
348
+ selection = None
349
+ if paths.run_dir and selected_path.is_file():
350
+ selection = json.loads(selected_path.read_text(encoding="utf-8"))
351
+ recipe = {
352
+ "config": config, "task_space": task_space, "artifacts": artifacts,
353
+ "verified_scores": verified_scores,
354
+ "script_hash": hashlib.sha256(rule.read_bytes()).hexdigest() if rule else None,
355
+ }
356
+ if args.allow_score_fallback:
357
+ recipe["allow_score_fallback"] = True
358
+ if selection is not None:
359
+ recipe["assignment_batch"] = selection
360
+ digest = hashlib.sha256(_json(recipe).encode("utf-8")).hexdigest()
361
+ receipt_path = paths.updates / f"{args.iter}.json"
362
+ if receipt_path.is_file():
363
+ receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
364
+ if receipt["input_sha256"] != digest:
365
+ _fail(1, f"iteration {args.iter} inputs changed after update")
366
+ _emit(receipt["result"])
367
+ return
368
+ if args.iter != state.iteration + 1:
369
+ _fail(1, f"expected iteration {state.iteration + 1}; completed legacy iterations lack replay receipts")
370
+ if llm_run and not args.allow_score_fallback and not score_path.is_file():
371
+ _fail(1, f"missing LLM scores file for iteration {args.iter}: {score_path.name}")
372
+ script_scorer = ScriptScorer(rule) if rule else None
373
+
374
+ selected_starts = None
375
+ if selection is not None:
376
+ selected_starts = {item["ant_id"]: item["start_node"] for item in selection["assignments"]}
377
+ valid_artifacts = {}
378
+ for art in artifacts:
379
+ err = _validate_artifact(art, valid_nodes, args.iter, require_meta=paths.run_dir is not None)
380
+ if err:
381
+ if paths.run_dir is not None:
382
+ _fail(1, f"invalid ant artifact: {err}")
383
+ print(f"warning: invalid ant artifact: {err}", file=sys.stderr)
384
+ continue
385
+ if art["ant_id"] in valid_artifacts:
386
+ _fail(1, f"duplicate ant identity: {art['ant_id']}")
387
+ if selected_starts is not None and selected_starts.get(art["ant_id"]) != art["path"][0]:
388
+ _fail(1, f"ant artifact does not match the saved assignment: {art['ant_id']}")
389
+ valid_artifacts[art["ant_id"]] = art
390
+
391
+ if llm_run and not args.allow_score_fallback:
392
+ missing = sorted(valid_artifacts.keys() - verified_scores.keys())
393
+ unexpected = sorted(verified_scores.keys() - valid_artifacts.keys())
394
+ if missing or unexpected:
395
+ _fail(1, f"LLM scores do not match iteration {args.iter} artifacts: missing {missing}, unexpected {unexpected}")
396
+
397
+ state.evaporate()
398
+ trail_log = []
399
+ hallucinations = []
400
+ scored = []
401
+ for art in valid_artifacts.values():
402
+ score, src = resolve_score(art, verified_scores, script_scorer, fallback)
403
+ if type(score) not in (int, float) or not 0.0 <= score <= 1.0:
404
+ _fail(1, f"invalid score for {art['ant_id']}")
405
+
406
+ if src == "verified_llm":
407
+ if hallucination_check(art["self_score"], score):
408
+ hallucinations.append(art["ant_id"])
409
+ score *= 0.5
410
+ scored.append({"ant_id": art["ant_id"], "score": score, "source": src})
411
+
412
+ state.deposit(art["path"], score)
413
+ trail_log.append({
414
+ "ant_id": art["ant_id"],
415
+ "path": art["path"],
416
+ "self_score": art["self_score"],
417
+ "verified_score": score,
418
+ "source": src,
419
+ })
420
+
421
+ if not scored:
422
+ _fail(1, f"no valid artifacts for iteration {args.iter}")
423
+ # Elitist: re-load best history, deposit extra on best path
424
+ best_data = None
425
+ if paths.best.exists():
426
+ best_data = json.loads(paths.best.read_text(encoding="utf-8"))
427
+ prev_best = best_data["score"] if best_data else 0.0
428
+ current_best = max(scored, key=lambda x: x["score"]) if scored else None
429
+ if current_best:
430
+ best_art = valid_artifacts[current_best["ant_id"]]
431
+ if best_data is None or current_best["score"] > best_data.get("score", -1):
432
+ best_data = {
433
+ "ant_id": current_best["ant_id"],
434
+ "iteration": args.iter,
435
+ "path": best_art["path"],
436
+ "score": current_best["score"],
437
+ "self_score": best_art["self_score"],
438
+ "candidate_solution": best_art.get("candidate_solution"),
439
+ "evidence": best_art.get("evidence", []),
440
+ "updated_at": time.time(),
441
+ }
442
+ # Elite deposit
443
+ state.deposit(best_data["path"], best_data["score"])
444
+
445
+ state.clip()
446
+ state.iteration = args.iter
447
+ mean_score = sum(s["score"] for s in scored) / len(scored) if scored else 0.0
448
+ best_score = best_data["score"] if best_data else 0.0
449
+ delta = best_score - prev_best
450
+
451
+ result = {
452
+ "status": "ok",
453
+ "command": "update",
454
+ "iteration": args.iter,
455
+ "n_ants_processed": len(scored),
456
+ "mean_score": round(mean_score, 4),
457
+ "best_score": round(best_score, 4),
458
+ "delta": round(delta, 4),
459
+ "elite_updated": current_best is not None and (best_data is None or current_best["ant_id"] == best_data["ant_id"]),
460
+ "hallucinations_flagged": hallucinations,
461
+ "stats": state.stats(),
462
+ }
463
+ receipt = {
464
+ "input_sha256": digest, "state": state.to_dict(), "best": best_data,
465
+ "trails": trail_log, "result": result,
466
+ }
467
+ if llm_run:
468
+ receipt["scoring"] = "fallback" if args.allow_score_fallback else "llm"
469
+ _write_atomic(receipt_path, _json(receipt))
470
+ _project_update(paths, args.iter, receipt)
471
+ _emit(result)
472
+
473
+
474
+ # ---------------------------------------------------------------------------
475
+ # converged
476
+ # ---------------------------------------------------------------------------
477
+
478
+ def cmd_converged(args: argparse.Namespace) -> None:
479
+ paths = SessionPaths(Path(args.session), _run_dir(args))
480
+ config = json.loads(paths.config.read_text(encoding="utf-8"))
481
+ cv = config.get("convergence", {})
482
+
483
+ state = PheromoneState.load(paths.pheromone_current)
484
+ iteration = state.iteration
485
+
486
+ triggered = []
487
+ metrics = {
488
+ "iteration": iteration,
489
+ "entropy": state.stats()["entropy"],
490
+ "best_score": 0.0,
491
+ "mean_score": 0.0,
492
+ "iterations_since_best_change": 0,
493
+ }
494
+
495
+ if paths.best.exists():
496
+ metrics["best_score"] = json.loads(paths.best.read_text(encoding="utf-8")).get("score", 0.0)
497
+
498
+ # max_iterations
499
+ max_iter = cv.get("max_iterations", 5)
500
+ if iteration >= max_iter:
501
+ triggered.append("max_iterations")
502
+
503
+ # entropy_floor
504
+ ef = cv.get("entropy_floor", {})
505
+ if ef.get("enabled", True) and metrics["entropy"] < ef.get("threshold", 0.5):
506
+ triggered.append("entropy_floor")
507
+
508
+ # target_score
509
+ ts = cv.get("target_score", {})
510
+ if ts.get("enabled", True) and metrics["best_score"] >= ts.get("value", 0.95):
511
+ triggered.append("target_score")
512
+
513
+ # stagnation
514
+ st = cv.get("stagnation", {})
515
+ if st.get("enabled", True):
516
+ patience = st.get("patience", 2)
517
+ min_delta = st.get("min_delta", 0.01)
518
+ # Use trails to compute per-iter best
519
+ trail_files = sorted(paths.trails.glob("*.jsonl"))
520
+ per_iter_best = []
521
+ for tf in trail_files:
522
+ lines = [json.loads(l) for l in tf.read_text().splitlines() if l.strip()]
523
+ if lines:
524
+ per_iter_best.append(max(l.get("verified_score", 0) for l in lines))
525
+ if len(per_iter_best) > patience:
526
+ recent = per_iter_best[-patience - 1:]
527
+ deltas = [abs(recent[i] - recent[i - 1]) for i in range(1, len(recent))]
528
+ metrics["iterations_since_best_change"] = sum(1 for d in deltas if d < min_delta)
529
+ if all(d < min_delta for d in deltas):
530
+ triggered.append("stagnation")
531
+
532
+ _emit({
533
+ "status": "ok",
534
+ "command": "converged",
535
+ "converged": len(triggered) > 0,
536
+ "iteration": iteration,
537
+ "triggered_by": triggered,
538
+ "reason": triggered[0] if triggered else "in_progress",
539
+ "metrics": metrics,
540
+ "recommendation": "ready for report" if triggered else f"continue to iteration {iteration + 1}",
541
+ })
542
+
543
+
544
+ # ---------------------------------------------------------------------------
545
+ # report
546
+ # ---------------------------------------------------------------------------
547
+
548
+ def cmd_report(args: argparse.Namespace) -> None:
549
+ paths = SessionPaths(Path(args.session), _run_dir(args))
550
+ state = PheromoneState.load(paths.pheromone_current)
551
+
552
+ best = None
553
+ if paths.best.exists():
554
+ best = json.loads(paths.best.read_text(encoding="utf-8"))
555
+
556
+ # Top-K trails across all iterations
557
+ all_trails = []
558
+ for tf in sorted(paths.trails.glob("*.jsonl")):
559
+ for line in tf.read_text().splitlines():
560
+ if line.strip():
561
+ all_trails.append(json.loads(line))
562
+ top_k = sorted(all_trails, key=lambda x: -x.get("verified_score", 0))[:5]
563
+
564
+ # Convergence curve
565
+ curve = []
566
+ for hf in sorted(paths.pheromone_history.glob("*.json"), key=lambda p: int(p.stem)):
567
+ snap = json.loads(hf.read_text(encoding="utf-8"))
568
+ curve.append({
569
+ "iteration": snap["iteration"],
570
+ "entropy": snap["stats"]["entropy"],
571
+ "tau_max": snap["stats"]["max"],
572
+ "tau_mean": snap["stats"]["mean"],
573
+ })
574
+
575
+ _emit({
576
+ "_meta": {
577
+ "kind": "swarm-report",
578
+ "schema": "swarm-report/1.0",
579
+ "role": "attachment",
580
+ },
581
+ "status": "ok",
582
+ "command": "report",
583
+ "best": best,
584
+ "top_k": top_k,
585
+ "convergence_curve": curve,
586
+ "final_pheromone_stats": state.stats(),
587
+ "iterations_completed": state.iteration,
588
+ })
589
+
590
+
591
+ # ---------------------------------------------------------------------------
592
+ # CLI
593
+ # ---------------------------------------------------------------------------
594
+
595
+ def build_parser() -> argparse.ArgumentParser:
596
+ p = argparse.ArgumentParser(prog="aco", description=f"ACO controller v{VERSION}")
597
+ p.add_argument("--session", required=True, help="path to session folder")
598
+ p.add_argument("--run-dir", dest="run_dir", default=None, help="run session outputs directory (formal deliverables)")
599
+ sub = p.add_subparsers(dest="command", required=True)
600
+
601
+ sub.add_parser("init", help="initialize pheromone + task-space from config")
602
+
603
+ s_select = sub.add_parser("select", help="produce N ant assignments for iteration k")
604
+ s_select.add_argument("--iter", type=int, required=True)
605
+
606
+ s_update = sub.add_parser("update", help="update pheromone from iteration artifacts")
607
+ s_update.add_argument("--iter", type=int, required=True)
608
+ s_update.add_argument("--allow-score-fallback", action="store_true",
609
+ help="score this LLM Run iteration using the fallback scorer")
610
+
611
+ sub.add_parser("converged", help="check convergence criteria")
612
+ sub.add_parser("report", help="emit full result report")
613
+
614
+ return p
615
+
616
+
617
+ def main(argv: Optional[List[str]] = None) -> None:
618
+ args = build_parser().parse_args(argv)
619
+ handlers = {
620
+ "init": cmd_init,
621
+ "select": cmd_select,
622
+ "update": cmd_update,
623
+ "converged": cmd_converged,
624
+ "report": cmd_report,
625
+ }
626
+ try:
627
+ session = Path(args.session)
628
+ if not session.is_dir():
629
+ _fail(2, f"session directory not found: {session}")
630
+ with _controller_lock(session):
631
+ paths = SessionPaths(session, _run_dir(args))
632
+ if paths.pheromone_current.is_file():
633
+ current = PheromoneState.load(paths.pheromone_current).iteration
634
+ pending = paths.updates / f"{current + 1}.json"
635
+ if pending.is_file():
636
+ receipt = json.loads(pending.read_text(encoding="utf-8"))
637
+ _project_update(paths, current + 1, receipt)
638
+ handlers[args.command](args)
639
+ except SystemExit:
640
+ raise
641
+ except Exception as e:
642
+ _fail(1, f"{type(e).__name__}: {e}")
643
+
644
+
645
+ if __name__ == "__main__":
646
+ main()