orkeon-code 0.0.0-stage → 1.0.0-rc.1

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 (423) hide show
  1. package/.orkeon-version +1 -0
  2. package/LICENSE.md +21 -0
  3. package/NOTICE.md +17 -0
  4. package/README.fr.md +169 -0
  5. package/README.md +162 -2
  6. package/config/appsettings.anthropic.example.json +77 -0
  7. package/config/appsettings.example.json +71 -0
  8. package/config/appsettings.jev.example.json +128 -0
  9. package/config/appsettings.kev.example.json +130 -0
  10. package/config/appsettings.liquid.example.json +129 -0
  11. package/config/appsettings.ollama-whisper.example.json +92 -0
  12. package/config/appsettings.ollama.example.json +70 -0
  13. package/config/appsettings.whisper.example.json +31 -0
  14. package/mcp/whisper/README.md +293 -0
  15. package/mcp/whisper/pyproject.toml +32 -0
  16. package/mcp/whisper/uv.lock +1641 -0
  17. package/mcp/whisper/whisper_mcp.py +1053 -0
  18. package/orkeon-code +897 -0
  19. package/orkeon-code.mjs +71 -0
  20. package/orkeon-code.ps1 +837 -0
  21. package/package.json +57 -4
  22. package/scripts/install.ps1 +156 -0
  23. package/scripts/install.sh +148 -0
  24. package/scripts/session-start.ork.ts +90 -0
  25. package/scripts/session-start.sh +74 -0
  26. package/scripts/setup-fixture.sh +88 -0
  27. package/src/commands/.orkeon/orkeon-cli.d.ts +562 -0
  28. package/src/commands/_lib/args.ts +193 -0
  29. package/src/commands/_lib/dev/dev-batches.ts +368 -0
  30. package/src/commands/_lib/dev/dev-implement.ts +188 -0
  31. package/src/commands/_lib/dev/dev-source.ts +65 -0
  32. package/src/commands/_lib/dev/dev.ts +344 -0
  33. package/src/commands/_lib/dev-step.ts +142 -0
  34. package/src/commands/_lib/dispatch.ts +231 -0
  35. package/src/commands/_lib/effort.ts +15 -0
  36. package/src/commands/_lib/git/branch.ts +95 -0
  37. package/src/commands/_lib/git/commit.ts +94 -0
  38. package/src/commands/_lib/git/diff.ts +97 -0
  39. package/src/commands/_lib/git/review.ts +109 -0
  40. package/src/commands/_lib/memory/memory-admit.ts +150 -0
  41. package/src/commands/_lib/memory/memory.ts +51 -0
  42. package/src/commands/_lib/pr-context.ts +32 -0
  43. package/src/commands/_lib/project/analyze.ts +24 -0
  44. package/src/commands/_lib/session/export.ts +104 -0
  45. package/src/commands/_lib/session/resume.ts +160 -0
  46. package/src/commands/_lib/session/tasks.ts +184 -0
  47. package/src/commands/_lib/settings/advisor.ts +80 -0
  48. package/src/commands/_lib/settings/agents.ts +147 -0
  49. package/src/commands/_lib/settings/config.ts +141 -0
  50. package/src/commands/_lib/settings/hooks.ts +58 -0
  51. package/src/commands/_lib/settings/mode.ts +91 -0
  52. package/src/commands/_lib/settings/model.ts +146 -0
  53. package/src/commands/_lib/settings/permissions.ts +309 -0
  54. package/src/commands/_lib/settings/session-config.ts +49 -0
  55. package/src/commands/_lib/settings/skills.ts +51 -0
  56. package/src/commands/_lib/speech/say.ts +96 -0
  57. package/src/commands/_lib/speech/transcribe.ts +130 -0
  58. package/src/commands/_lib/speech/voice.ts +146 -0
  59. package/src/commands/_lib/status/cache.ts +31 -0
  60. package/src/commands/_lib/status/context.ts +57 -0
  61. package/src/commands/_lib/status/doctor.ts +186 -0
  62. package/src/commands/_lib/status/meta.ts +45 -0
  63. package/src/commands/_lib/status/status.ts +129 -0
  64. package/src/commands/_lib/status/usage-tools.ts +49 -0
  65. package/src/commands/_lib/status/usage.ts +139 -0
  66. package/src/commands/_lib/view.ts +29 -0
  67. package/src/commands/dev/dev-batches.cmd.ts +108 -0
  68. package/src/commands/dev/dev-learn.cmd.ts +29 -0
  69. package/src/commands/dev/dev-plan.cmd.ts +52 -0
  70. package/src/commands/dev/dev-spec.cmd.ts +55 -0
  71. package/src/commands/dev/dev-status.cmd.ts +16 -0
  72. package/src/commands/git/branch.cmd.ts +27 -0
  73. package/src/commands/git/commit.cmd.ts +48 -0
  74. package/src/commands/git/diff.cmd.ts +26 -0
  75. package/src/commands/git/review.cmd.ts +36 -0
  76. package/src/commands/memory/memory.cmd.ts +48 -0
  77. package/src/commands/project/analyze.cmd.ts +32 -0
  78. package/src/commands/project/debug-tool-call.cmd.ts +67 -0
  79. package/src/commands/project/files.cmd.ts +22 -0
  80. package/src/commands/project/init-verifiers.cmd.ts +14 -0
  81. package/src/commands/project/init.cmd.ts +14 -0
  82. package/src/commands/project/verify.cmd.ts +27 -0
  83. package/src/commands/session/assistant.cmd.ts +40 -0
  84. package/src/commands/session/btw.cmd.ts +18 -0
  85. package/src/commands/session/clear.cmd.ts +19 -0
  86. package/src/commands/session/compact.cmd.ts +16 -0
  87. package/src/commands/session/copy.cmd.ts +44 -0
  88. package/src/commands/session/exit.cmd.ts +9 -0
  89. package/src/commands/session/export.cmd.ts +28 -0
  90. package/src/commands/session/rename.cmd.ts +17 -0
  91. package/src/commands/session/resume.cmd.ts +19 -0
  92. package/src/commands/session/rewind.cmd.ts +26 -0
  93. package/src/commands/session/summary.cmd.ts +27 -0
  94. package/src/commands/session/tasks.cmd.ts +44 -0
  95. package/src/commands/settings/advisor.cmd.ts +38 -0
  96. package/src/commands/settings/agents.cmd.ts +19 -0
  97. package/src/commands/settings/config.cmd.ts +17 -0
  98. package/src/commands/settings/effort.cmd.ts +40 -0
  99. package/src/commands/settings/fast.cmd.ts +17 -0
  100. package/src/commands/settings/hooks.cmd.ts +17 -0
  101. package/src/commands/settings/mode.cmd.ts +20 -0
  102. package/src/commands/settings/model.cmd.ts +20 -0
  103. package/src/commands/settings/output-style.cmd.ts +48 -0
  104. package/src/commands/settings/permissions.cmd.ts +25 -0
  105. package/src/commands/settings/proactive.cmd.ts +15 -0
  106. package/src/commands/settings/skills.cmd.ts +17 -0
  107. package/src/commands/speech/say.cmd.ts +24 -0
  108. package/src/commands/speech/transcribe.cmd.ts +29 -0
  109. package/src/commands/speech/voice.cmd.ts +30 -0
  110. package/src/commands/status/context.cmd.ts +18 -0
  111. package/src/commands/status/doctor.cmd.ts +27 -0
  112. package/src/commands/status/release-notes.cmd.ts +9 -0
  113. package/src/commands/status/status.cmd.ts +25 -0
  114. package/src/commands/status/usage.cmd.ts +21 -0
  115. package/src/crews/.orkeon/orkeon.d.ts +3946 -0
  116. package/src/crews/_probe-shared-memory/domain/probe-verdict.ts +183 -0
  117. package/src/crews/_probe-shared-memory/probe.ork.ts +98 -0
  118. package/src/crews/advisor/application/run-advisor.ts +40 -0
  119. package/src/crews/advisor/crew.ork.ts +43 -0
  120. package/src/crews/advisor/domain/advice.ts +135 -0
  121. package/src/crews/agent-run/application/run-agent-run.ts +42 -0
  122. package/src/crews/agent-run/crew.ork.ts +67 -0
  123. package/src/crews/analyze/application/run-analyze.ts +118 -0
  124. package/src/crews/analyze/crew.ork.ts +40 -0
  125. package/src/crews/analyze/domain/harvest.ts +301 -0
  126. package/src/crews/code-review/application/prompts.ts +133 -0
  127. package/src/crews/code-review/application/review.ts +71 -0
  128. package/src/crews/code-review/application/run-code-review.ts +123 -0
  129. package/src/crews/code-review/crew.ork.ts +51 -0
  130. package/src/crews/code-review/domain/lenses.ts +193 -0
  131. package/src/crews/code-review/domain/report.ts +59 -0
  132. package/src/crews/code-review/domain/scope.ts +112 -0
  133. package/src/crews/dev-batches/application/plan-close.ts +181 -0
  134. package/src/crews/dev-batches/application/run-dev-batches.ts +669 -0
  135. package/src/crews/dev-batches/application/run-wave.ts +450 -0
  136. package/src/crews/dev-batches/application/seed-harvest.ts +162 -0
  137. package/src/crews/dev-batches/crew.ork.ts +143 -0
  138. package/src/crews/dev-batches/domain/batch-waves.ts +70 -0
  139. package/src/crews/dev-batches/domain/batches-budget.ts +52 -0
  140. package/src/crews/dev-batches/domain/batches-log.ts +54 -0
  141. package/src/crews/dev-batches/domain/wave-order.ts +43 -0
  142. package/src/crews/dev-change/application/change-prompt.ts +104 -0
  143. package/src/crews/dev-change/application/evidence.ts +169 -0
  144. package/src/crews/dev-change/application/run-dev-change.ts +315 -0
  145. package/src/crews/dev-change/crew.ork.ts +112 -0
  146. package/src/crews/dev-change/domain/change-answer.ts +159 -0
  147. package/src/crews/dev-change/domain/change-render.ts +79 -0
  148. package/src/crews/dev-implement/application/close.ts +183 -0
  149. package/src/crews/dev-implement/application/count-open-steps.ts +24 -0
  150. package/src/crews/dev-implement/application/locate-sheet.ts +80 -0
  151. package/src/crews/dev-implement/application/observe.ts +50 -0
  152. package/src/crews/dev-implement/application/report-writes.ts +41 -0
  153. package/src/crews/dev-implement/application/run-dev-implement.ts +811 -0
  154. package/src/crews/dev-implement/application/run-role.ts +27 -0
  155. package/src/crews/dev-implement/application/suite-job.ts +118 -0
  156. package/src/crews/dev-implement/application/touched.ts +74 -0
  157. package/src/crews/dev-implement/crew.ork.ts +68 -0
  158. package/src/crews/dev-implement/domain/contracts.ts +256 -0
  159. package/src/crews/dev-implement/domain/correction.ts +102 -0
  160. package/src/crews/dev-implement/domain/cycles.ts +35 -0
  161. package/src/crews/dev-implement/domain/implement-budget.ts +29 -0
  162. package/src/crews/dev-implement/domain/roles.ts +53 -0
  163. package/src/crews/dev-implement/domain/sheet-edits.ts +75 -0
  164. package/src/crews/dev-implement/domain/sheet-ticks.ts +22 -0
  165. package/src/crews/dev-implement/domain/step-checks.ts +136 -0
  166. package/src/crews/dev-implement/domain/step-section.ts +127 -0
  167. package/src/crews/dev-learn/application/learn-backlog.ts +58 -0
  168. package/src/crews/dev-learn/application/learn-prompt.ts +140 -0
  169. package/src/crews/dev-learn/application/run-dev-learn.ts +553 -0
  170. package/src/crews/dev-learn/crew.ork.ts +52 -0
  171. package/src/crews/dev-learn/domain/learn-answer.ts +235 -0
  172. package/src/crews/dev-learn/domain/owner-lines.ts +86 -0
  173. package/src/crews/dev-learn/domain/proposals-render.ts +96 -0
  174. package/src/crews/dev-plan/application/anchor-paths.ts +76 -0
  175. package/src/crews/dev-plan/application/inventory.ts +170 -0
  176. package/src/crews/dev-plan/application/plan-prompt.ts +159 -0
  177. package/src/crews/dev-plan/application/run-dev-plan.ts +455 -0
  178. package/src/crews/dev-plan/crew.ork.ts +109 -0
  179. package/src/crews/dev-plan/domain/inventory-model.ts +95 -0
  180. package/src/crews/dev-plan/domain/plan-answer.ts +738 -0
  181. package/src/crews/dev-plan/domain/plan-render.ts +307 -0
  182. package/src/crews/dev-spec/application/run-dev-spec.ts +206 -0
  183. package/src/crews/dev-spec/application/spec-prompt.ts +98 -0
  184. package/src/crews/dev-spec/crew.ork.ts +108 -0
  185. package/src/crews/dev-spec/domain/spec-answer.ts +253 -0
  186. package/src/crews/dev-spec/domain/spec-render.ts +76 -0
  187. package/src/crews/dev-verify/application/audit.ts +259 -0
  188. package/src/crews/dev-verify/application/auditor-prompt.ts +323 -0
  189. package/src/crews/dev-verify/application/capture.ts +303 -0
  190. package/src/crews/dev-verify/application/run-dev-verify.ts +409 -0
  191. package/src/crews/dev-verify/application/run-gate.ts +202 -0
  192. package/src/crews/dev-verify/crew.ork.ts +103 -0
  193. package/src/crews/dev-verify/domain/audit-answer.ts +150 -0
  194. package/src/crews/dev-verify/domain/auditor-charter.ts +21 -0
  195. package/src/crews/dev-verify/domain/capture-sections.ts +137 -0
  196. package/src/crews/dev-verify/domain/commands.ts +103 -0
  197. package/src/crews/dev-verify/domain/gate.ts +126 -0
  198. package/src/crews/dev-verify/domain/mechanical-table.ts +163 -0
  199. package/src/crews/dev-verify/domain/runtime-cut.ts +13 -0
  200. package/src/crews/dev-verify/domain/sheet-facts.ts +4 -0
  201. package/src/crews/dev-verify/domain/text.ts +20 -0
  202. package/src/crews/dev-verify/domain/verdict.ts +127 -0
  203. package/src/crews/git-commit/application/draft.ts +154 -0
  204. package/src/crews/git-commit/application/run-git-commit.ts +116 -0
  205. package/src/crews/git-commit/crew.ork.ts +52 -0
  206. package/src/crews/git-commit/domain/commit.ts +220 -0
  207. package/src/crews/init-verifiers/application/authoring.ts +89 -0
  208. package/src/crews/init-verifiers/application/prompts.ts +103 -0
  209. package/src/crews/init-verifiers/application/run-init-verifiers.ts +25 -0
  210. package/src/crews/init-verifiers/crew.ork.ts +34 -0
  211. package/src/crews/init-verifiers/domain/commands-section.ts +36 -0
  212. package/src/crews/init-verifiers/domain/readiness.ts +23 -0
  213. package/src/crews/main-loop/application/auto-compact.ts +77 -0
  214. package/src/crews/main-loop/application/context-gather.ts +133 -0
  215. package/src/crews/main-loop/application/run-main-loop.ts +350 -0
  216. package/src/crews/main-loop/application/turn-prompt.ts +112 -0
  217. package/src/crews/main-loop/crew.ork.ts +119 -0
  218. package/src/crews/main-loop/domain/autocompact.ts +27 -0
  219. package/src/crews/main-loop/domain/prompt-assembly.ts +521 -0
  220. package/src/crews/main-loop/domain/turn-chains.ts +129 -0
  221. package/src/crews/project-init/application/detect.ts +122 -0
  222. package/src/crews/project-init/application/prompts.ts +101 -0
  223. package/src/crews/project-init/application/run-project-init.ts +31 -0
  224. package/src/crews/project-init/crew.ork.ts +35 -0
  225. package/src/crews/project-init/domain/conventions.ts +36 -0
  226. package/src/crews/project-init/domain/existing-files.ts +63 -0
  227. package/src/crews/project-init/domain/package-map.ts +73 -0
  228. package/src/crews/session-compact/crew.ork.ts +55 -0
  229. package/src/crews/shared-memory-admit/crew.ork.ts +48 -0
  230. package/src/crews/speech/application/run-speech.ts +25 -0
  231. package/src/crews/speech/crew.ork.ts +37 -0
  232. package/src/shared/application/agents/child-agent.ts +255 -0
  233. package/src/shared/application/agents/run-sub-agent.ts +96 -0
  234. package/src/shared/application/answer-language.ts +14 -0
  235. package/src/shared/application/attached-skills.ts +36 -0
  236. package/src/shared/application/compaction/compact-session.ts +237 -0
  237. package/src/shared/application/compaction/extract-memories.ts +38 -0
  238. package/src/shared/application/compaction/restore-context.ts +78 -0
  239. package/src/shared/application/config-store.ts +123 -0
  240. package/src/shared/application/dev/brief-inventory.ts +113 -0
  241. package/src/shared/application/dev/close-batch.ts +83 -0
  242. package/src/shared/application/dev/find-repo-pack.ts +77 -0
  243. package/src/shared/application/dev/learn-decision.ts +252 -0
  244. package/src/shared/application/dev/load-dev-context.ts +266 -0
  245. package/src/shared/application/dev/measure-access-cost.ts +68 -0
  246. package/src/shared/application/dev/plan-source.ts +112 -0
  247. package/src/shared/application/dev/preflight.ts +71 -0
  248. package/src/shared/application/dev/project-files.ts +17 -0
  249. package/src/shared/application/dev/question-round.ts +52 -0
  250. package/src/shared/application/dev/resolve-work-folder.ts +133 -0
  251. package/src/shared/application/dev/script-tool-slot.ts +27 -0
  252. package/src/shared/application/dev/settle-questions.ts +55 -0
  253. package/src/shared/application/dev/source-review.ts +63 -0
  254. package/src/shared/application/dev/source-step.ts +150 -0
  255. package/src/shared/application/dev/spend.ts +42 -0
  256. package/src/shared/application/dev/step-precedents.ts +89 -0
  257. package/src/shared/application/dev/tool-call-policy.ts +89 -0
  258. package/src/shared/application/dev/tool-callbacks.ts +215 -0
  259. package/src/shared/application/dev/tool-trace-recorder.ts +45 -0
  260. package/src/shared/application/dev/verdict-sources.ts +48 -0
  261. package/src/shared/application/dev/wrapped-tools.ts +145 -0
  262. package/src/shared/application/extra-tools.ts +70 -0
  263. package/src/shared/application/git/batch-worktree.ts +97 -0
  264. package/src/shared/application/git/commit-files.ts +186 -0
  265. package/src/shared/application/git/merge-batch.ts +63 -0
  266. package/src/shared/application/git/open-pull-request.ts +51 -0
  267. package/src/shared/application/instructions-file.ts +19 -0
  268. package/src/shared/application/json-file.ts +34 -0
  269. package/src/shared/application/llm-profile.ts +35 -0
  270. package/src/shared/application/permission-rules.ts +159 -0
  271. package/src/shared/application/ports/approvals.ts +20 -0
  272. package/src/shared/application/ports/clock.ts +5 -0
  273. package/src/shared/application/ports/code-index.ts +93 -0
  274. package/src/shared/application/ports/crew.ts +60 -0
  275. package/src/shared/application/ports/files.ts +21 -0
  276. package/src/shared/application/ports/human.ts +13 -0
  277. package/src/shared/application/ports/llm.ts +54 -0
  278. package/src/shared/application/ports/memory.ts +30 -0
  279. package/src/shared/application/ports/progress.ts +23 -0
  280. package/src/shared/application/ports/runtime.ts +15 -0
  281. package/src/shared/application/ports/session.ts +74 -0
  282. package/src/shared/application/ports/shared-memory.ts +26 -0
  283. package/src/shared/application/ports/shell.ts +40 -0
  284. package/src/shared/application/ports/telemetry.ts +45 -0
  285. package/src/shared/application/ports/tools.ts +46 -0
  286. package/src/shared/application/ports/usage.ts +45 -0
  287. package/src/shared/application/ports.ts +27 -0
  288. package/src/shared/application/project-manifests.ts +106 -0
  289. package/src/shared/application/session-io.ts +84 -0
  290. package/src/shared/application/session-state.ts +36 -0
  291. package/src/shared/application/shared-memory/admit-entries.ts +177 -0
  292. package/src/shared/application/shared-memory/harvest-after-gaps.ts +72 -0
  293. package/src/shared/application/shared-memory/harvest-mistakes.ts +44 -0
  294. package/src/shared/application/shared-memory/import-agent-memory.ts +117 -0
  295. package/src/shared/application/shared-memory/memory-files.ts +110 -0
  296. package/src/shared/application/shared-memory/memory-settings.ts +93 -0
  297. package/src/shared/application/shared-memory/push-candidate.ts +146 -0
  298. package/src/shared/application/shared-memory/recall-precedents.ts +69 -0
  299. package/src/shared/application/state-snapshot.ts +38 -0
  300. package/src/shared/application/workflow/workflow-state.ts +135 -0
  301. package/src/shared/domain/agent-policy/behavior-flags.ts +168 -0
  302. package/src/shared/domain/agent-policy/extra-tools.ts +69 -0
  303. package/src/shared/domain/agent-policy/memory-categories.ts +6 -0
  304. package/src/shared/domain/agent-policy/mode-policy.ts +51 -0
  305. package/src/shared/domain/agent-policy/output-styles.ts +11 -0
  306. package/src/shared/domain/agent-policy/permission.ts +623 -0
  307. package/src/shared/domain/agent-policy/rule-sets.ts +412 -0
  308. package/src/shared/domain/agent-policy/tool-access.ts +77 -0
  309. package/src/shared/domain/agent-registry.ts +142 -0
  310. package/src/shared/domain/agents/built-in-charters.ts +43 -0
  311. package/src/shared/domain/agents/chain.ts +30 -0
  312. package/src/shared/domain/agents/charter.ts +61 -0
  313. package/src/shared/domain/agents/exclusive.ts +24 -0
  314. package/src/shared/domain/agents/instances.ts +249 -0
  315. package/src/shared/domain/code-intel-contract.ts +356 -0
  316. package/src/shared/domain/code-intel-routing.ts +113 -0
  317. package/src/shared/domain/compact-outcome.ts +44 -0
  318. package/src/shared/domain/compaction-thresholds.ts +161 -0
  319. package/src/shared/domain/compaction.ts +379 -0
  320. package/src/shared/domain/config-schema.ts +421 -0
  321. package/src/shared/domain/dev/access-cost.ts +226 -0
  322. package/src/shared/domain/dev/artefacts.ts +50 -0
  323. package/src/shared/domain/dev/batches-concurrency.ts +36 -0
  324. package/src/shared/domain/dev/batches-state.ts +49 -0
  325. package/src/shared/domain/dev/build-commands.ts +44 -0
  326. package/src/shared/domain/dev/call-guard.ts +341 -0
  327. package/src/shared/domain/dev/carried-text.ts +49 -0
  328. package/src/shared/domain/dev/design-rules.ts +100 -0
  329. package/src/shared/domain/dev/learn-proposals.ts +175 -0
  330. package/src/shared/domain/dev/learn-state.ts +93 -0
  331. package/src/shared/domain/dev/path-args.ts +42 -0
  332. package/src/shared/domain/dev/path-rebase.ts +93 -0
  333. package/src/shared/domain/dev/plan-checks.ts +190 -0
  334. package/src/shared/domain/dev/plan-format.ts +180 -0
  335. package/src/shared/domain/dev/project-files.ts +43 -0
  336. package/src/shared/domain/dev/questions.ts +249 -0
  337. package/src/shared/domain/dev/reading-rule.ts +41 -0
  338. package/src/shared/domain/dev/repo-pack.ts +237 -0
  339. package/src/shared/domain/dev/review-answer.ts +150 -0
  340. package/src/shared/domain/dev/review-prompt.ts +221 -0
  341. package/src/shared/domain/dev/reviewer-charter.ts +31 -0
  342. package/src/shared/domain/dev/sheet-facts.ts +83 -0
  343. package/src/shared/domain/dev/spec-format.ts +183 -0
  344. package/src/shared/domain/dev/step-budget.ts +72 -0
  345. package/src/shared/domain/dev/step-rules.ts +110 -0
  346. package/src/shared/domain/dev/test-commands.ts +90 -0
  347. package/src/shared/domain/dev/test-output.ts +33 -0
  348. package/src/shared/domain/dev/test-paths.ts +40 -0
  349. package/src/shared/domain/dev/tool-guards.ts +64 -0
  350. package/src/shared/domain/dev/trait-pattern.ts +83 -0
  351. package/src/shared/domain/dev/verdict-format.ts +169 -0
  352. package/src/shared/domain/dev/whitespace.ts +34 -0
  353. package/src/shared/domain/dev/work-folder.ts +67 -0
  354. package/src/shared/domain/dev/yaml-subset.ts +403 -0
  355. package/src/shared/domain/git/close.ts +273 -0
  356. package/src/shared/domain/git/pull-request.ts +96 -0
  357. package/src/shared/domain/git/worktree.ts +46 -0
  358. package/src/shared/domain/index-languages.ts +16 -0
  359. package/src/shared/domain/instructions-file.ts +18 -0
  360. package/src/shared/domain/iso-day.ts +4 -0
  361. package/src/shared/domain/llm-failure.ts +106 -0
  362. package/src/shared/domain/llm-profile.ts +25 -0
  363. package/src/shared/domain/marked-message.ts +33 -0
  364. package/src/shared/domain/model-catalog.ts +86 -0
  365. package/src/shared/domain/permission-modes.ts +103 -0
  366. package/src/shared/domain/prelude.ts +92 -0
  367. package/src/shared/domain/project-manifests.ts +83 -0
  368. package/src/shared/domain/search-routing.ts +85 -0
  369. package/src/shared/domain/secret-patterns.ts +45 -0
  370. package/src/shared/domain/session-keys.ts +85 -0
  371. package/src/shared/domain/session-start.ts +60 -0
  372. package/src/shared/domain/session-summary.ts +13 -0
  373. package/src/shared/domain/severity.ts +72 -0
  374. package/src/shared/domain/sha1.ts +61 -0
  375. package/src/shared/domain/shared-memory/agent-memory-import.ts +143 -0
  376. package/src/shared/domain/shared-memory/candidates.ts +41 -0
  377. package/src/shared/domain/shared-memory/entry.ts +145 -0
  378. package/src/shared/domain/shared-memory/front-matter.ts +183 -0
  379. package/src/shared/domain/shared-memory/gate.ts +44 -0
  380. package/src/shared/domain/shared-memory/harvest.ts +61 -0
  381. package/src/shared/domain/shared-memory/layout.ts +187 -0
  382. package/src/shared/domain/shared-memory/precedents-block.ts +93 -0
  383. package/src/shared/domain/shared-memory/refused.ts +84 -0
  384. package/src/shared/domain/shared-memory/verdict-rows.ts +134 -0
  385. package/src/shared/domain/snip-turns.ts +45 -0
  386. package/src/shared/domain/speech.ts +20 -0
  387. package/src/shared/domain/strip.ts +88 -0
  388. package/src/shared/domain/tool-trace.ts +122 -0
  389. package/src/shared/domain/types.ts +67 -0
  390. package/src/shared/domain/verifiers.ts +37 -0
  391. package/src/shared/domain/vfs.ts +9 -0
  392. package/src/shared/domain/workflow/state-file.ts +140 -0
  393. package/src/shared/infrastructure/globals.ts +52 -0
  394. package/src/shared/infrastructure/orkeon/approvals.ts +24 -0
  395. package/src/shared/infrastructure/orkeon/child-agents.ts +127 -0
  396. package/src/shared/infrastructure/orkeon/code-index.ts +120 -0
  397. package/src/shared/infrastructure/orkeon/crew-host.ts +27 -0
  398. package/src/shared/infrastructure/orkeon/crew-memory.ts +12 -0
  399. package/src/shared/infrastructure/orkeon/dev-deps.ts +172 -0
  400. package/src/shared/infrastructure/orkeon/files.ts +40 -0
  401. package/src/shared/infrastructure/orkeon/github-pull-requests.ts +29 -0
  402. package/src/shared/infrastructure/orkeon/host-provider.ts +22 -0
  403. package/src/shared/infrastructure/orkeon/human-input.ts +59 -0
  404. package/src/shared/infrastructure/orkeon/llm-profile.ts +38 -0
  405. package/src/shared/infrastructure/orkeon/llm.ts +109 -0
  406. package/src/shared/infrastructure/orkeon/memory-store.ts +41 -0
  407. package/src/shared/infrastructure/orkeon/memory-tools.ts +131 -0
  408. package/src/shared/infrastructure/orkeon/permission-rules.ts +42 -0
  409. package/src/shared/infrastructure/orkeon/progress.ts +24 -0
  410. package/src/shared/infrastructure/orkeon/run-state.ts +17 -0
  411. package/src/shared/infrastructure/orkeon/runtime-info.ts +30 -0
  412. package/src/shared/infrastructure/orkeon/runtime-tools.ts +60 -0
  413. package/src/shared/infrastructure/orkeon/script-tools.ts +134 -0
  414. package/src/shared/infrastructure/orkeon/session-store.ts +138 -0
  415. package/src/shared/infrastructure/orkeon/session-switch.ts +23 -0
  416. package/src/shared/infrastructure/orkeon/shared-memory.ts +61 -0
  417. package/src/shared/infrastructure/orkeon/shell-jobs.ts +75 -0
  418. package/src/shared/infrastructure/orkeon/shell.ts +31 -0
  419. package/src/shared/infrastructure/orkeon/telemetry.ts +63 -0
  420. package/src/shared/infrastructure/orkeon/tool-catalogue.ts +75 -0
  421. package/src/shared/infrastructure/orkeon/tool-results.ts +120 -0
  422. package/src/shared/infrastructure/orkeon/usage.ts +74 -0
  423. package/src/shared/infrastructure/orkeon/wiring.ts +118 -0
@@ -0,0 +1,108 @@
1
+ // @orkeon-script 1.0
2
+ /// <reference path="../.orkeon/orkeon.d.ts" />
3
+ //
4
+ // DevSpec crew (/dev-spec). Composition root: it builds one agent from the reviewer's charter (read tools only)
5
+ // and wires application/run-dev-spec, which inventories the code by the index, asks the model for the business
6
+ // spec as JSON (once more on a refused answer), writes <work>/<code>/SPEC-<code>.md, asks its open questions one at
7
+ // a time through human_input (each answer written before the next question), folds the answers into the body, then
8
+ // has the read-only reviewer question the spec once. Unattended, the questions stay in the file: BLOCKED.
9
+ // The reviewer's act runs in a background child, `dev-reviewer` (its charter: read tools only, plan mode), which
10
+ // /tasks lists and stops while it runs, as /dev-plan's (A-3, approach A2); on a host without background children
11
+ // it runs inline.
12
+ //
13
+ // Input (globalThis.inputs): { code: string, request?: string (the brief, a path to it, or a revision request),
14
+ // hooks?: the /hooks registry, effort?: "low" | "medium" | "high" | "xhigh" | "max" | null,
15
+ // memoryRecall?: false (a session rule denies it: the agent gets none),
16
+ // concurrency?: number, maxInstances?: number }
17
+ // Run standalone: orkeon run src/crews/dev-spec/crew.ork.ts --inputs '{"code":"prune","request":"…"}'
18
+ //
19
+ // Budget (STEP_BUDGETS["dev-spec"]): about 50 index calls for the inventory, about 20 file and git calls, at most
20
+ // seven extract calls (draft, folds, re-asks) and one review of 20 iterations (about 3 tool calls each): well under
21
+ // 200 tool calls. The reviewer runs as a child (delegationDepth 1): the runtime gives it what the parent has left
22
+ // at its spawn, so its 60 calls are an estimate, not a cap. The wall time counts the person's answers: one hour.
23
+
24
+ import { CrewBuilder, publishCrew, inputs, ToolBuilder } from "../../shared/infrastructure/globals.ts";
25
+ import {
26
+ orkeonAgent,
27
+ orkeonClock,
28
+ orkeonCodeIndex,
29
+ orkeonConfigStore,
30
+ orkeonFiles,
31
+ orkeonHumanInput,
32
+ orkeonMemoryToolPorts,
33
+ orkeonSessionIo,
34
+ orkeonSharedMemory,
35
+ orkeonShell,
36
+ } from "../../shared/infrastructure/orkeon/wiring.ts";
37
+ import { memoryReadTools, memoryRecallOn, memoryRecallTools } from "../../shared/infrastructure/orkeon/memory-tools.ts";
38
+ import { createLlm } from "../../shared/infrastructure/orkeon/llm.ts";
39
+ import { providerEffort } from "../../shared/domain/agent-policy/behavior-flags.ts";
40
+ import { memoryDirOf } from "../../shared/application/shared-memory/memory-settings.ts";
41
+ import { devToolCallbacks } from "../../shared/application/dev/tool-callbacks.ts";
42
+ import { childAgentBody, openChildAct } from "../../shared/infrastructure/orkeon/child-agents.ts";
43
+ import { charterCatalogue } from "../../shared/domain/agents/charter.ts";
44
+ import { instanceLimits } from "../../shared/domain/agents/instances.ts";
45
+ import { REVIEWER_CHARTER } from "../../shared/domain/dev/reviewer-charter.ts";
46
+ import { STEP_BUDGETS } from "../../shared/domain/dev/step-budget.ts";
47
+ import { stepPrecedents } from "../../shared/application/dev/step-precedents.ts";
48
+ import { runDevSpec } from "./application/run-dev-spec.ts";
49
+
50
+ const ports = { shell: orkeonShell(), files: orkeonFiles(), config: orkeonConfigStore(), index: orkeonCodeIndex(), human: orkeonHumanInput() };
51
+ // memory_recall is attached unless a session rule denies every call of it (the command says so).
52
+ const memoryOn = memoryRecallOn(inputs());
53
+ const effort = providerEffort(inputs().effort);
54
+ const session = orkeonSessionIo();
55
+ const limits = instanceLimits(inputs());
56
+ // The host's gate first, then these callbacks: the step's rule sets again and the /hooks the command passed.
57
+ const callbacksFor = (ctx: any) => devToolCallbacks(
58
+ { step: "dev-spec", hooks: inputs().hooks, readTools: memoryReadTools(memoryOn) }, { shell: ports.shell, log: ctx.log, memoryDir: memoryDirOf(ports.config) },
59
+ );
60
+
61
+ /** The reviewer, added to the crew by its first act (a sequential crew would run an agent it holds from the start). */
62
+ const reviewer = () => {
63
+ const builder = orkeonAgent()
64
+ .name(REVIEWER_CHARTER.name)
65
+ .role(REVIEWER_CHARTER.role)
66
+ .goal(REVIEWER_CHARTER.goal)
67
+ .tools(charterCatalogue(REVIEWER_CHARTER))
68
+ .withAutonomousTools(memoryRecallTools(ToolBuilder, orkeonMemoryToolPorts, memoryOn))
69
+ .maxIterations(REVIEWER_CHARTER.maxIterations)
70
+ .body(childAgentBody(callbacksFor));
71
+ return effort === undefined ? builder : builder.effort(effort);
72
+ };
73
+
74
+ const builder = orkeonAgent()
75
+ .name("dev-spec-writer")
76
+ .role("Business analyst")
77
+ .goal("Write what a feature does and the rules it follows, in business words, and settle its open questions with the person")
78
+ // The catalogue is the reviewer's: read tools only. The spec itself is an extract call, which offers none.
79
+ .tools(charterCatalogue(REVIEWER_CHARTER))
80
+ .withAutonomousTools(memoryRecallTools(ToolBuilder, orkeonMemoryToolPorts, memoryOn))
81
+ .maxIterations(REVIEWER_CHARTER.maxIterations)
82
+ .body(async (_input: any, ctx: any) => {
83
+ const clock = orkeonClock();
84
+ const child = openChildAct(
85
+ createLlm(ctx.llm, callbacksFor(ctx), { effort }), ctx, crew, { state: session, clock, log: ctx.log, effort },
86
+ { crew: "dev-spec", step: "dev-spec" },
87
+ { agent: REVIEWER_CHARTER.name, charter: REVIEWER_CHARTER.name, task: "review of the spec", builder: reviewer },
88
+ );
89
+ try {
90
+ // T1: the shared memory's precedents in the draft's prompt, unless memory_recall is denied.
91
+ const precedents = stepPrecedents({ ...ports, memory: orkeonSharedMemory(), log: ctx.log }, { on: memoryOn });
92
+ return await runDevSpec(inputs(), { ...ports, llm: child.llm, log: ctx.log, clock, precedents });
93
+ } finally {
94
+ await child.close();
95
+ }
96
+ });
97
+ const writer = (effort === undefined ? builder : builder.effort(effort)).build();
98
+
99
+ const crew = CrewBuilder()
100
+ .name("dev-spec")
101
+ .process("sequential")
102
+ .budget(STEP_BUDGETS["dev-spec"])
103
+ .concurrency(limits.concurrency)
104
+ .maxInstances(limits.maxInstances)
105
+ .withAgent(writer)
106
+ .build();
107
+
108
+ publishCrew(crew);
@@ -0,0 +1,253 @@
1
+ // The model's spec as JSON: the schema it is extracted into, and the check that turns the extraction into a
2
+ // SpecAnswer or the list of what is wrong with it. The self-check of the harness's spec template, as code: a use
3
+ // case has an actor, an intent, a `Where` and a short scenario; a rule is one testable line with an origin and a
4
+ // severity, applied to use cases that exist; every vocabulary term is used; a TBD has its open question; nothing
5
+ // technical is named; every cell fits its table. Ids are code's: UC-nn and BR-nn by position. Pure, no IO.
6
+ import type { Checked } from "../../../shared/domain/agents/charter.ts";
7
+ import { MAX_QUESTIONS, QUESTION_SCHEMA, breaksCell, draftQuestionProblems } from "../../../shared/domain/dev/questions.ts";
8
+ import type { DraftQuestion } from "../../../shared/domain/dev/questions.ts";
9
+
10
+ export interface SpecUseCase {
11
+ name: string; actor: string; intent: string; frequency: string; where: string;
12
+ scenario: string[]; variants: string; errors: string; outcome: string;
13
+ }
14
+ export type RuleSeverity = "blocking" | "warning" | "informational";
15
+ export interface SpecRule { name: string; statement: string; origin: string; severity: RuleSeverity; appliesTo: string[]; example: string }
16
+ export type SpecDatum = { datum: string; description: string; source: string; importance: string };
17
+ export type SpecTransition = { state: string; event: string; next: string; condition: string };
18
+ export interface SpecAnswer {
19
+ name: string; summary: string; context: string;
20
+ vocabulary: Array<{ term: string; definition: string }>;
21
+ /** The lines of a mermaid flowchart, without the fence; "" when the feature has no branch nor lifecycle. */
22
+ overview: string;
23
+ useCases: SpecUseCase[]; rules: SpecRule[]; data: SpecDatum[]; states: SpecTransition[];
24
+ crossCutting: string[];
25
+ relations: Array<{ upstream: string; downstream: string }>;
26
+ outOfScope: Array<{ exclusion: string; reason: string }>;
27
+ assumptions: Array<{ assumption: string; validatedBy: string }>;
28
+ questions: DraftQuestion[];
29
+ }
30
+
31
+ const RULE_SEVERITIES: readonly RuleSeverity[] = ["blocking", "warning", "informational"];
32
+ const DATA_SOURCES = ["entered", "computed", "imported", "catalogue"] as const;
33
+ const DATA_IMPORTANCE = ["essential", "secondary", "expert"] as const;
34
+ export const MAX_USE_CASES = 12;
35
+ export const MAX_RULES = 24;
36
+ export const MAX_SCENARIO_STEPS = 7;
37
+ const MAX_NAME_CHARS = 80;
38
+ const MAX_STATEMENT_CHARS = 200;
39
+ const MAX_LIST = 20;
40
+
41
+ const str = { type: "string" };
42
+ const strings = { type: "array", items: str };
43
+ const table = (keys: readonly string[]): object => ({
44
+ type: "array",
45
+ items: { type: "object", properties: Object.fromEntries(keys.map((k) => [k, str])), required: [...keys] },
46
+ });
47
+
48
+ export const SPEC_ANSWER_SCHEMA: object = {
49
+ type: "object",
50
+ properties: {
51
+ name: str, summary: str, context: str,
52
+ vocabulary: table(["term", "definition"]),
53
+ overview: str,
54
+ useCases: {
55
+ type: "array",
56
+ items: {
57
+ type: "object",
58
+ properties: {
59
+ name: str, actor: str, intent: str, frequency: str, where: str, scenario: strings,
60
+ variants: str, errors: str, outcome: str,
61
+ },
62
+ required: ["name", "actor", "intent", "frequency", "where", "scenario", "variants", "errors", "outcome"],
63
+ },
64
+ },
65
+ rules: {
66
+ type: "array",
67
+ items: {
68
+ type: "object",
69
+ properties: {
70
+ name: str, statement: str, origin: str, severity: { type: "string", enum: [...RULE_SEVERITIES] },
71
+ appliesTo: strings, example: str,
72
+ },
73
+ required: ["name", "statement", "origin", "severity", "appliesTo", "example"],
74
+ },
75
+ },
76
+ data: table(["datum", "description", "source", "importance"]),
77
+ states: table(["state", "event", "next", "condition"]),
78
+ crossCutting: strings,
79
+ relations: table(["upstream", "downstream"]),
80
+ outOfScope: table(["exclusion", "reason"]),
81
+ assumptions: table(["assumption", "validatedBy"]),
82
+ questions: { type: "array", items: QUESTION_SCHEMA },
83
+ },
84
+ required: [
85
+ "name", "summary", "context", "vocabulary", "overview", "useCases", "rules", "data", "states", "crossCutting",
86
+ "relations", "outOfScope", "assumptions", "questions",
87
+ ],
88
+ };
89
+
90
+ /** Words of a technical document, never of a business spec (the template's business purity). */
91
+ const TECHNICAL: ReadonlyArray<[RegExp, string]> = [
92
+ [/`/, "a code mark (`)"],
93
+ [/\b[A-Za-z_][A-Za-z0-9_]*\(\)/, "a call such as name()"],
94
+ [/\b[\w-]+\.(ts|tsx|js|mjs|cs|py|java|go|rs|rb|php|json|ya?ml|sql|xml|csproj)\b/i, "a file name"],
95
+ [/\bHTTP\b|\b[1-5]\d\d (OK|Not Found|Bad Request|Unauthorized|Forbidden)\b/, "an HTTP status"],
96
+ [/\bexit code\b/i, "an exit code"],
97
+ [/\bstack trace\b/i, "a stack trace"],
98
+ [/\bendpoints?\b/i, "an endpoint"],
99
+ [/\b(class|interface|enum|DTO|repository pattern|framework)\b/, "a type or a framework"],
100
+ ];
101
+
102
+ const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
103
+ const text = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
104
+ const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
105
+ const textList = (v: unknown): string[] => list(v).map(text).filter((t) => t !== "");
106
+
107
+ function rows<K extends string>(v: unknown, keys: readonly K[]): Array<Record<K, string>> {
108
+ return list(v).map((item) => {
109
+ const o = isObject(item) ? item : {};
110
+ return Object.fromEntries(keys.map((k) => [k, text(o[k])])) as Record<K, string>;
111
+ });
112
+ }
113
+
114
+ /** The value read leniently: every field present, strings trimmed, missing lists empty. */
115
+ function readSpecAnswer(value: unknown): SpecAnswer {
116
+ const o = isObject(value) ? value : {};
117
+ return {
118
+ name: text(o.name), summary: text(o.summary), context: text(o.context),
119
+ vocabulary: rows(o.vocabulary, ["term", "definition"]),
120
+ overview: typeof o.overview === "string" ? o.overview.trim() : "",
121
+ useCases: list(o.useCases).map((u) => {
122
+ const x = isObject(u) ? u : {};
123
+ return {
124
+ name: text(x.name), actor: text(x.actor), intent: text(x.intent), frequency: text(x.frequency),
125
+ where: text(x.where), scenario: textList(x.scenario), variants: text(x.variants), errors: text(x.errors),
126
+ outcome: text(x.outcome),
127
+ };
128
+ }),
129
+ rules: list(o.rules).map((r) => {
130
+ const x = isObject(r) ? r : {};
131
+ return {
132
+ name: text(x.name), statement: text(x.statement), origin: text(x.origin),
133
+ severity: text(x.severity).toLowerCase() as RuleSeverity, appliesTo: textList(x.appliesTo), example: text(x.example),
134
+ };
135
+ }),
136
+ data: rows(o.data, ["datum", "description", "source", "importance"]),
137
+ states: rows(o.states, ["state", "event", "next", "condition"]),
138
+ crossCutting: textList(o.crossCutting),
139
+ relations: rows(o.relations, ["upstream", "downstream"]),
140
+ outOfScope: rows(o.outOfScope, ["exclusion", "reason"]),
141
+ assumptions: rows(o.assumptions, ["assumption", "validatedBy"]),
142
+ questions: list(o.questions).map((q) => {
143
+ const x = isObject(q) ? q : {};
144
+ return { severity: text(x.severity), question: text(x.question), impact: text(x.impact), options: textList(x.options) };
145
+ }),
146
+ };
147
+ }
148
+
149
+ const oneLine = (t: string): boolean => !/[\r\n]/.test(t);
150
+ export const useCaseId = (k: number): string => `UC-${String(k + 1).padStart(2, "0")}`;
151
+ export const ruleId = (k: number): string => `BR-${String(k + 1).padStart(2, "0")}`;
152
+
153
+ /** Every text of the answer a reader sees, but the overview (a flowchart's syntax) and the vocabulary. */
154
+ function bodyTexts(a: SpecAnswer): string[] {
155
+ return [
156
+ a.name, a.summary, a.context,
157
+ ...a.useCases.flatMap((u) => [u.name, u.actor, u.intent, u.frequency, u.where, ...u.scenario, u.variants, u.errors, u.outcome]),
158
+ ...a.rules.flatMap((r) => [r.name, r.statement, r.origin, r.example]),
159
+ ...a.data.flatMap((d) => [d.datum, d.description]),
160
+ ...a.states.flatMap((s) => [s.state, s.event, s.next, s.condition]),
161
+ ...a.crossCutting,
162
+ ...a.relations.flatMap((r) => [r.upstream, r.downstream]),
163
+ ...a.outOfScope.flatMap((r) => [r.exclusion, r.reason]),
164
+ ...a.assumptions.flatMap((r) => [r.assumption, r.validatedBy]),
165
+ ...a.questions.flatMap((q) => [q.question, q.impact, ...q.options]),
166
+ ];
167
+ }
168
+
169
+ function cellProblems(name: string, items: ReadonlyArray<Record<string, string>>, problems: string[]): void {
170
+ items.forEach((row, i) => {
171
+ for (const [key, value] of Object.entries(row)) {
172
+ if (breaksCell(value)) { problems.push(`${name} ${i + 1}: ${key} is one line, no '|'`); return; }
173
+ }
174
+ if (Object.values(row).every((v) => v === "")) problems.push(`${name} ${i + 1} is empty`);
175
+ });
176
+ }
177
+
178
+ export function checkSpecAnswer(value: unknown): Checked<SpecAnswer> {
179
+ if (!isObject(value)) return { ok: false, problems: ["the answer is not an object"] };
180
+ const a = readSpecAnswer(value);
181
+ const problems: string[] = [];
182
+
183
+ if (a.name === "" || !oneLine(a.name) || a.name.length > MAX_NAME_CHARS || a.name.includes("—")) {
184
+ problems.push(`name: one line of at most ${MAX_NAME_CHARS} characters, no '—'`);
185
+ }
186
+ if (a.summary === "") problems.push("summary: two or three sentences: what, for whom, why");
187
+ if (a.context === "") problems.push("context: the problem, for whom, the cost of doing nothing");
188
+
189
+ if (a.useCases.length === 0) problems.push("useCases: at least one use case");
190
+ if (a.useCases.length > MAX_USE_CASES) problems.push(`useCases: at most ${MAX_USE_CASES}`);
191
+ a.useCases.forEach((u, i) => {
192
+ const id = useCaseId(i);
193
+ if (u.name === "" || !oneLine(u.name) || u.name.length > MAX_NAME_CHARS) problems.push(`${id}: the name is one line of at most ${MAX_NAME_CHARS} characters`);
194
+ if (u.actor === "") problems.push(`${id}: no actor`);
195
+ if (u.intent === "") problems.push(`${id}: no intent`);
196
+ if (u.where === "") problems.push(`${id}: no Where: the surface and the moment the actor meets it`);
197
+ if (u.scenario.length === 0 || u.scenario.length > MAX_SCENARIO_STEPS) {
198
+ problems.push(`${id}: the nominal scenario has 1 to ${MAX_SCENARIO_STEPS} steps`);
199
+ }
200
+ if ([u.actor, u.intent, u.frequency, u.where, ...u.scenario].some((t) => !oneLine(t))) problems.push(`${id}: a field or a step spans lines`);
201
+ });
202
+
203
+ const ucIds = new Set(a.useCases.map((_, i) => useCaseId(i)));
204
+ if (a.rules.length > MAX_RULES) problems.push(`rules: at most ${MAX_RULES}`);
205
+ a.rules.forEach((r, i) => {
206
+ const id = ruleId(i);
207
+ if (r.name === "" || !oneLine(r.name) || r.name.length > MAX_NAME_CHARS) problems.push(`${id}: the name is one line of at most ${MAX_NAME_CHARS} characters`);
208
+ if (r.statement === "" || !oneLine(r.statement) || r.statement.length > MAX_STATEMENT_CHARS || r.statement.includes(" · ")) {
209
+ problems.push(`${id}: the statement is one testable line of at most ${MAX_STATEMENT_CHARS} characters`);
210
+ }
211
+ if (r.origin === "") problems.push(`${id}: no origin (regulation, standard, practice, product choice, existing behaviour)`);
212
+ if (!RULE_SEVERITIES.includes(r.severity)) problems.push(`${id}: severity is blocking, warning or informational`);
213
+ if (r.appliesTo.length === 0) problems.push(`${id}: appliesTo names UC-nn ids or cross-cutting`);
214
+ for (const t of r.appliesTo) {
215
+ if (t !== "cross-cutting" && !ucIds.has(t)) problems.push(`${id}: appliesTo '${t}' is no use case of the answer`);
216
+ }
217
+ });
218
+
219
+ cellProblems("vocabulary", a.vocabulary, problems);
220
+ cellProblems("data", a.data, problems);
221
+ cellProblems("states", a.states, problems);
222
+ cellProblems("relations", a.relations, problems);
223
+ cellProblems("outOfScope", a.outOfScope, problems);
224
+ cellProblems("assumptions", a.assumptions, problems);
225
+ for (const d of a.data) {
226
+ if (d.source !== "" && !(DATA_SOURCES as readonly string[]).includes(d.source)) problems.push(`data '${d.datum}': source is ${DATA_SOURCES.join(", ")}`);
227
+ if (d.importance !== "" && !(DATA_IMPORTANCE as readonly string[]).includes(d.importance)) {
228
+ problems.push(`data '${d.datum}': importance is ${DATA_IMPORTANCE.join(", ")}`);
229
+ }
230
+ }
231
+ for (const [name, n] of [["crossCutting", a.crossCutting.length], ["vocabulary", a.vocabulary.length], ["data", a.data.length]] as const) {
232
+ if (n > MAX_LIST) problems.push(`${name}: at most ${MAX_LIST} rows`);
233
+ }
234
+ if (a.overview !== "" && (a.overview.includes("```") || !/^(flowchart|graph|stateDiagram)/.test(a.overview))) {
235
+ problems.push("overview: the lines of one mermaid flowchart, without the fence, or \"\"");
236
+ }
237
+
238
+ const body = bodyTexts(a).join("\n");
239
+ const lower = body.toLowerCase();
240
+ for (const v of a.vocabulary) {
241
+ if (v.term !== "" && !lower.includes(v.term.toLowerCase())) problems.push(`vocabulary: '${v.term}' is used nowhere else`);
242
+ }
243
+ if (/\bTBD\b/.test(body) && a.questions.length === 0) problems.push("a TBD in the body has no open question");
244
+ for (const [pattern, what] of TECHNICAL) {
245
+ const hit = bodyTexts(a).find((t) => pattern.test(t));
246
+ if (hit !== undefined) problems.push(`business purity: ${what} in "${hit.slice(0, 60)}"; say it in business words`);
247
+ }
248
+
249
+ if (a.questions.length > MAX_QUESTIONS) problems.push(`questions: at most ${MAX_QUESTIONS}`);
250
+ a.questions.forEach((q, i) => problems.push(...draftQuestionProblems(q, i + 1)));
251
+
252
+ return problems.length > 0 ? { ok: false, problems } : { ok: true, value: a };
253
+ }
@@ -0,0 +1,76 @@
1
+ // The spec file as code writes it from a checked SpecAnswer, its open questions and its decisions: the harness's
2
+ // template (sections 1 to 12) with a section 13 of decisions, a section left out when it has nothing to say (the
3
+ // numbers stay the template's, so a reader and /dev-plan find each section where they expect it). A use case and a
4
+ // rule carry a `- **Statement**:` line first, which spec-format.ts reads for /dev-plan. Pure, no IO.
5
+ import { decisionTable, questionTable } from "../../../shared/domain/dev/questions.ts";
6
+ import type { Decision, Question } from "../../../shared/domain/dev/questions.ts";
7
+ import { ruleId, useCaseId } from "./spec-answer.ts";
8
+ import type { SpecAnswer } from "./spec-answer.ts";
9
+
10
+ export const specFileName = (code: string): string => `SPEC-${code}.md`;
11
+ export const SPEC_DECISIONS_SECTION = "## 13. Decisions";
12
+ export const SPEC_QUESTIONS_SECTION = "## 12. Open questions";
13
+
14
+ export interface SpecRenderInput { code: string; answer: SpecAnswer; open: readonly Question[]; decisions: readonly Decision[] }
15
+
16
+ const section = (heading: string, body: readonly string[]): string[] => (body.length === 0 ? [] : [heading, "", ...body, ""]);
17
+ const table = (header: readonly string[], rows: ReadonlyArray<readonly string[]>): string[] =>
18
+ rows.length === 0 ? [] : [
19
+ `| ${header.join(" | ")} |`, `|${header.map(() => "---").join("|")}|`,
20
+ ...rows.map((r) => `| ${r.map((c) => c || "—").join(" | ")} |`),
21
+ ];
22
+ const sentence = (t: string): string => (t === "" || /[.!?]$/.test(t) ? t : `${t}.`);
23
+
24
+ function useCaseBlock(a: SpecAnswer): string[] {
25
+ return a.useCases.flatMap((u, i) => {
26
+ const head = [`**Statement**: ${u.intent}`, `**Actor**: ${u.actor}`];
27
+ if (u.frequency !== "") head.push(`**Frequency**: ${u.frequency}`);
28
+ const lines = [`### ${useCaseId(i)} — ${u.name}`, `- ${head.join(" · ")}`, `- **Where**: ${u.where}`, "- **Nominal scenario**:"];
29
+ u.scenario.forEach((s, k) => lines.push(` ${k + 1}. ${s}`));
30
+ if (u.variants !== "") lines.push(`- **Variants**: ${u.variants}`);
31
+ if (u.errors !== "") lines.push(`- **Errors**: ${u.errors}`);
32
+ if (u.outcome !== "") lines.push(`- **Expected outcome**: ${u.outcome}`);
33
+ lines.push("");
34
+ return lines;
35
+ });
36
+ }
37
+
38
+ function ruleBlock(a: SpecAnswer): string[] {
39
+ return a.rules.flatMap((r, i) => {
40
+ const applies = r.appliesTo.join(", ");
41
+ const lines = [
42
+ `### ${ruleId(i)} — ${r.name}`,
43
+ `- **Statement**: ${r.statement} · **Origin**: ${r.origin} · **Severity**: ${r.severity}`,
44
+ `- **Applies to**: ${applies}`,
45
+ ];
46
+ if (r.example !== "") lines.push(`- **Example**: ${r.example}`);
47
+ lines.push("");
48
+ return lines;
49
+ });
50
+ }
51
+
52
+ export function renderSpec(input: SpecRenderInput): string {
53
+ const a = input.answer;
54
+ const lines: string[] = [`# ${input.code} — ${a.name}`, ""];
55
+ if (a.summary !== "") lines.push(...a.summary.split(/\r?\n/).map((l) => `> ${l}`.trimEnd()), "");
56
+ lines.push(...section("## 1. Context", [a.context]));
57
+ lines.push(...section("## 2. Vocabulary", table(["Term", "Definition"], a.vocabulary.map((v) => [v.term, v.definition]))));
58
+ lines.push(...section("## 3. Overview", a.overview === "" ? [] : ["```mermaid", a.overview, "```"]));
59
+ lines.push("## 4. Use cases", "", ...useCaseBlock(a));
60
+ if (a.rules.length > 0) lines.push("## 5. Business rules", "", ...ruleBlock(a));
61
+ lines.push(...section("## 6. Data", table(
62
+ ["Datum", "Description", "Source", "Importance"], a.data.map((d) => [d.datum, d.description, d.source, d.importance]),
63
+ )));
64
+ lines.push(...section("## 7. States and transitions", table(
65
+ ["State", "Event", "Next state", "Condition"], a.states.map((s) => [s.state, s.event, s.next, s.condition]),
66
+ )));
67
+ lines.push(...section("## 8. Cross-cutting behaviours", a.crossCutting.map((c) => `- ${sentence(c)}`)));
68
+ lines.push(...section("## 9. Relations", table(["Upstream", "Downstream"], a.relations.map((r) => [r.upstream, r.downstream]))));
69
+ lines.push(...section("## 10. Out of scope", table(["Exclusion", "Reason"], a.outOfScope.map((r) => [r.exclusion, r.reason]))));
70
+ lines.push(...section("## 11. Assumptions", table(
71
+ ["#", "Assumption", "To be validated by"], a.assumptions.map((r, i) => [`A${i + 1}`, r.assumption, r.validatedBy]),
72
+ )));
73
+ lines.push(...section(SPEC_QUESTIONS_SECTION, questionTable(input.open)));
74
+ lines.push(...section(SPEC_DECISIONS_SECTION, decisionTable(input.decisions)));
75
+ return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
76
+ }