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,307 @@
1
+ // The renderer of /dev-plan: a checked PlanAnswer, the inventory behind its anchors and
2
+ // the review become the global plan `<P>-PLAN.md` and one sheet `<P>-PLAN-F<k>.md` per
3
+ // batch. Pure, no IO. It is the only writer of the plan's format literals - headings, table
4
+ // headers, the box and TDD lines - which the harness and L-1 read back by pattern; every
5
+ // other sentence is this project's. It never checks the answer: checkPlanAnswer did.
6
+
7
+ import { DESIGN_RULE_IDS } from "../../../shared/domain/dev/design-rules.ts";
8
+ import { packValue } from "../../../shared/domain/dev/repo-pack.ts";
9
+ import type { RepoPack } from "../../../shared/domain/dev/repo-pack.ts";
10
+ import type { ReviewAnswer, ReviewRow } from "../../../shared/domain/dev/review-answer.ts";
11
+ import type { ChangeKind, SourceId, SourceKind } from "../../../shared/domain/dev/spec-format.ts";
12
+ import type { InventoryEntry } from "./inventory-model.ts";
13
+ import type { AnchorRef, ElementLayer, PlanAnswer, PlanBatch, PlanStep } from "./plan-answer.ts";
14
+
15
+ export interface RenderInput {
16
+ prefix: string; // "PRUNE"
17
+ sourceShown: string; // "workbench/prune/SPEC-prune.md"
18
+ kind: SourceKind; changeKind?: ChangeKind;
19
+ sourceIds: readonly SourceId[]; // for titles in ## 2. Traceability
20
+ repo: RepoLines;
21
+ inventory: ReadonlyMap<string, InventoryEntry>; // ref → entry
22
+ answer: PlanAnswer; // checked
23
+ review: ReviewAnswer | null; // null before the review
24
+ date: string; // "2026-10-22"
25
+ }
26
+ export interface RepoLines { commands: string; layout: string } // the two Scope lines' text after their label
27
+ export interface RenderedPlan { plan: { name: string; text: string }; sheets: Array<{ name: string; text: string }> }
28
+
29
+ const BUILD_STEP = "Build and tests";
30
+ const NONE_DASH = "—";
31
+ const COMMAND_KEYS = ["restore", "build", "build_test", "test_class", "test", "test_project", "test_integration"];
32
+ const LAYOUT_KEYS = ["domain", "application", "infrastructure", "tests"];
33
+ const LAYER_LABELS: ReadonlyArray<[ElementLayer, string]> = [
34
+ ["domain", "**Domain**"], ["application", "**Application**"], ["adapter", "**Adapters**"], ["test", "**Tests**"],
35
+ ];
36
+ const FAMILY_RANK: Record<string, number> = { BR: 0, CH: 1, UC: 2 };
37
+
38
+ // The sentences of a rendered plan that are not format literals: this project's words.
39
+ const TDD_PREAMBLE = [
40
+ "Tests lead: a step's production code starts only once its tests exist and fail. Within the step, write the",
41
+ "passing path first, then the refusals, then the integration checks.",
42
+ ];
43
+ const DECLARATIVE_LEAD = "Pure declarations left without a test of their own (each one exercised by the test of its behaviour)";
44
+ const BUILD_STEP_BODY = "No test of its own: it runs the scopes of `## Test policy and scopes`.";
45
+ const ANCHORS_LEAD = "Paths copied by the implementation step; an existing one carries the line of the member it names, from the inventory of the plan run.";
46
+ const MAJOR_TAIL = "Not settled by the plan run: answer it here before the first failing test of the step it concerns.";
47
+
48
+ const noDot = (text: string): string => text.replace(/\.+$/, "");
49
+ const code = (text: string): string => `\`${text}\``;
50
+ const row = (cells: readonly string[]): string => `| ${cells.join(" | ")} |`;
51
+ /** Free text of a review or a decision: the classification labels lose their capital (L4-Q06). */
52
+ const unlabelled = (text: string): string =>
53
+ text.replace(/Non-applicable rules/g, "non-applicable rules").replace(/Applied rules/g, "applied rules");
54
+
55
+ function rankId(id: string): [number, number] {
56
+ const [family, number] = id.split("-");
57
+ return [FAMILY_RANK[family] ?? 3, Number(number)];
58
+ }
59
+
60
+ /** The ids of a batch's tests: BR/CH by family then number, then " / ", then UC. */
61
+ function idsCell(ids: Iterable<string>): string {
62
+ const sorted = [...new Set(ids)].sort((a, b) => {
63
+ const [fa, na] = rankId(a);
64
+ const [fb, nb] = rankId(b);
65
+ return fa !== fb ? fa - fb : na - nb;
66
+ });
67
+ const rules = sorted.filter((id) => !id.startsWith("UC-"));
68
+ const cases = sorted.filter((id) => id.startsWith("UC-"));
69
+ const sides = [rules.join(", "), cases.join(", ")].filter((s) => s !== "");
70
+ return sides.length === 0 ? NONE_DASH : sides.join(" / ");
71
+ }
72
+
73
+ const batchIds = (b: PlanBatch): string => idsCell(b.steps.flatMap((s) => s.tests.flatMap((t) => t.ids)));
74
+ const blocks = (parts: ReadonlyArray<string | null>): string => `${parts.filter((p): p is string => p !== null).join("\n\n")}\n`;
75
+
76
+ // ---- the review --------------------------------------------------------------------
77
+
78
+ interface ReviewPlacement {
79
+ blocked: boolean;
80
+ questions: Array<{ n: number; row: ReviewRow }>; // § 4 of the global plan: Blocking, then plan-level Major
81
+ majors: (batch: string) => ReviewRow[];
82
+ }
83
+
84
+ function placeReview(review: ReviewAnswer | null): ReviewPlacement {
85
+ const rows = review?.rows ?? [];
86
+ const blocking = rows.filter((r) => r.severity === "Blocking");
87
+ const planMajor = rows.filter((r) => r.severity === "Major" && r.target === "plan");
88
+ return {
89
+ blocked: blocking.length > 0,
90
+ questions: [...blocking, ...planMajor].map((r, i) => ({ n: i + 1, row: r })),
91
+ majors: (batch) => rows.filter((r) => r.severity === "Major" && r.target === batch),
92
+ };
93
+ }
94
+
95
+ // ---- repoLines ---------------------------------------------------------------------
96
+
97
+ /** The `- **Commands**:` and `- **Layout**:` texts from the pack (null: no pack), and the keys absent. */
98
+ export function repoLines(pack: RepoPack | null, packShown: string | null): RepoLines & { absent: string[] } {
99
+ const absent: string[] = [];
100
+ const tail = pack === null
101
+ ? " — no repository pack: add .orkeon/repo.yaml"
102
+ : ` — from ${code(packShown ?? ".orkeon/repo.yaml")}`;
103
+ const valueOf = (key: string): string | undefined => {
104
+ const v = pack === null ? undefined : packValue(pack, key);
105
+ const text = typeof v === "string" ? v.trim() : undefined;
106
+ if (text === undefined || text === "") { absent.push(key); return undefined; }
107
+ return text;
108
+ };
109
+ const commands = COMMAND_KEYS.map((k) => {
110
+ const v = valueOf(`commands.${k}`);
111
+ return v === undefined ? `${k} (not in the pack)` : `${k} ${code(v)}`;
112
+ });
113
+ const layout = LAYOUT_KEYS.flatMap((k) => {
114
+ const v = valueOf(`layout.${k}`);
115
+ return v === undefined ? [] : [`${k} ${code(v)}`];
116
+ });
117
+ return {
118
+ commands: `${commands.join(" · ")}${tail}`,
119
+ layout: `${layout.length === 0 ? "(not in the pack)" : layout.join(" · ")}${tail}`,
120
+ absent,
121
+ };
122
+ }
123
+
124
+ // ---- the global plan ---------------------------------------------------------------
125
+
126
+ function globalPlan(input: RenderInput, sheetNames: readonly string[], review: ReviewPlacement): string {
127
+ const { answer: a, prefix: p } = input;
128
+ const ids = (b: PlanBatch): string => batchIds(b);
129
+ const deps = (b: PlanBatch): string => (b.dependsOn.length === 0 ? NONE_DASH : b.dependsOn.join(", "));
130
+ const state = review.blocked ? "blocked" : "open";
131
+ const batchBlocks = a.batches.map((b, k) => [
132
+ `### Batch F${k + 1} — ${b.name} — ${state}`,
133
+ ...b.steps.map((s, j) => `- [ ] ${j + 1}. ${s.title}`),
134
+ `- [ ] ${b.steps.length + 1}. ${BUILD_STEP} — scope: ${b.buildScope}`,
135
+ ].join("\n"));
136
+
137
+ const entry = (ref: string): InventoryEntry | undefined => input.inventory.get(ref);
138
+ const reuse = a.reuse.map((ref) => {
139
+ const e = entry(ref);
140
+ return e === undefined ? code(ref) : `${code(`${e.path}:${e.line}`)} (${e.name})`;
141
+ });
142
+ const listOrNone = (items: readonly string[]): string => (items.length === 0 ? "none" : items.join("; "));
143
+ const na = DESIGN_RULE_IDS.flatMap((id) => a.nonApplicable.filter((n) => n.id === id).map((n) => `${id}: N/A — ${n.reason}`));
144
+ const sourceLine = input.kind === "change"
145
+ ? `- **Change**: ${code(input.sourceShown)} (${code(input.changeKind ?? "change")})`
146
+ : `- **Spec**: ${code(input.sourceShown)}`;
147
+ const scope = [
148
+ sourceLine,
149
+ `- **Layers**: ${a.layers.join(", ")}`,
150
+ `- **Reuse**: ${listOrNone(reuse)}`,
151
+ `- **Out of scope**: ${listOrNone(a.outOfScope)}`,
152
+ `- **Assumptions**: ${listOrNone(a.assumptions)}`,
153
+ `- **Commands**: ${input.repo.commands}`,
154
+ `- **Layout**: ${input.repo.layout}`,
155
+ `- **Non-applicable rules**: ${na.length === 0 ? "none" : na.join("; ")}`,
156
+ ].join("\n");
157
+
158
+ const carriers = (id: string): string => {
159
+ const batches = a.batches.flatMap((b, k) => (b.steps.some((s) => s.tests.some((t) => t.ids.includes(id))) ? [`F${k + 1}`] : []));
160
+ return batches.length === 0 ? NONE_DASH : batches.join(", ");
161
+ };
162
+ const trace = [
163
+ "| Id | Code owner(s) | Batch |",
164
+ "|----|---------------|-------|",
165
+ ...input.sourceIds.map((s) => {
166
+ const owners = a.traceability.find((t) => t.id === s.id)?.owners ?? [];
167
+ return row([`${s.id} — ${s.title}`, owners.length === 0 ? NONE_DASH : owners.map(code).join(" + "), carriers(s.id)]);
168
+ }),
169
+ ].join("\n");
170
+ const design = [
171
+ "| Ids | Owning aggregate | Invariant and what it removes | Consistency | Batch |",
172
+ "|-----|------------------|-------------------------------|-------------|-------|",
173
+ ...a.design.map((d) => row([d.ids.join(", "), code(d.aggregate), d.invariant, d.consistency, `F${d.batch}`])),
174
+ ].join("\n");
175
+ const questions = review.questions.length === 0 ? null : [
176
+ "| # | Severity | Question | Evidence |",
177
+ "|---|----------|----------|----------|",
178
+ ...review.questions.map(({ n, row: r }) => row([String(n), r.severity, unlabelled(r.question), unlabelled(r.evidence)])),
179
+ ].join("\n");
180
+
181
+ return blocks([
182
+ `# ${p}-PLAN — ${a.feature}`,
183
+ `> From ${code(input.sourceShown)}. Sheets: ${sheetNames.map(code).join(", ")}.`,
184
+ "## 0. Summary",
185
+ [
186
+ "| Batch | Intent | Ids | Depends on | Reason |",
187
+ "|-------|--------|-----|------------|--------|",
188
+ ...a.batches.map((b, k) => row([`F${k + 1}`, b.intent, ids(b), deps(b), b.reason])),
189
+ ].join("\n"),
190
+ ...batchBlocks,
191
+ "## 1. Scope",
192
+ scope,
193
+ "## 2. Traceability",
194
+ trace,
195
+ "## 3. Design",
196
+ design,
197
+ questions === null ? null : "## 4. Open questions",
198
+ questions,
199
+ ]);
200
+ }
201
+
202
+ // ---- a batch sheet -----------------------------------------------------------------
203
+
204
+ type Column = "tests" | "doubles" | "production";
205
+
206
+ function anchorText(a: AnchorRef, column: Column, inventory: ReadonlyMap<string, InventoryEntry>): string {
207
+ if (a.kind === "create") return `${code(a.path ?? "")} — to create`;
208
+ const member = a.member === undefined || a.member === "" ? null : a.member;
209
+ if (a.kind === "existing") {
210
+ const base = `${code(a.path ?? "")} — existing`;
211
+ if (column === "tests" || member === null) return base;
212
+ return column === "doubles" ? `${base} (${code(member)} to add)` : `${base} — ${code(member)}`;
213
+ }
214
+ const e = a.ref === undefined ? undefined : inventory.get(a.ref);
215
+ const at = code(e === undefined ? (a.ref ?? "") : `${e.path}:${e.line}`);
216
+ if (column === "tests") return `${at} — existing`;
217
+ if (member === null) return at;
218
+ return column === "doubles" ? `${at} (${code(member)} to add)` : `${at} — ${code(member)}`;
219
+ }
220
+
221
+ function anchorCell(anchors: readonly AnchorRef[], column: Column, inventory: ReadonlyMap<string, InventoryEntry>): string {
222
+ return anchors.length === 0 ? NONE_DASH : anchors.map((a) => anchorText(a, column, inventory)).join("; ");
223
+ }
224
+
225
+ function stepBlocks(s: PlanStep, j: number): string[] {
226
+ const table = [
227
+ `### Step ${j + 1} — ${s.title}`,
228
+ "| # | Test | Level | Project | Ids |",
229
+ "|---|------|-------|---------|-----|",
230
+ ...s.tests.map((t, m) => row([String(m + 1), code(t.name), t.level, code(t.project), t.ids.length === 0 ? NONE_DASH : t.ids.join(", ")])),
231
+ ].join("\n");
232
+ const note = s.note === "" ? [] : [s.note.split("\n").map((l) => l.trimEnd()).join("\n")];
233
+ return [table, ...note, "TDD: RED [ ] GREEN [ ] COST [ ]"];
234
+ }
235
+
236
+ function sheet(input: RenderInput, b: PlanBatch, k: number, review: ReviewPlacement): string {
237
+ const p = input.prefix;
238
+ const id = `F${k + 1}`;
239
+ const source = input.kind === "change" ? "Change" : "Spec";
240
+ const deps = b.dependsOn.length === 0 ? "[none]" : b.dependsOn.join(", ");
241
+ const applied = DESIGN_RULE_IDS.filter((r) => b.design.appliedRules.includes(r));
242
+
243
+ const blockedBy = review.blocked
244
+ ? review.questions
245
+ .filter(({ row: r }) => r.severity === "Blocking" && (r.target === id || r.target === "plan"))
246
+ .map(({ n }) => `- Blocked by question ${n} of ${p}-PLAN.md § 4 (${input.date})`)
247
+ : [];
248
+ const decisions = [
249
+ ...blockedBy,
250
+ ...b.decisions.map((d) => `- ${input.date} — ${unlabelled(d)}`),
251
+ ...review.majors(id).map((r) =>
252
+ `- ${input.date} — review (Major): ${unlabelled(r.question)} Evidence: ${unlabelled(noDot(r.evidence))}. ${MAJOR_TAIL}`),
253
+ ];
254
+
255
+ const s = b.steps.length;
256
+ const elements = LAYER_LABELS.flatMap(([layer, label]) => {
257
+ const items = b.elements.filter((e) => e.layer === layer);
258
+ return items.length === 0 ? [] : [label, ...items.map((e) => `- ${code(e.signature)} — ${e.rule}`)];
259
+ });
260
+ const anchors = [
261
+ "| Step | Test class / fixture | Shared doubles and builders | Production filled or created |",
262
+ "|------|----------------------|-----------------------------|------------------------------|",
263
+ ...b.steps.map((st, j) => row([
264
+ `${j + 1} — ${st.title}`,
265
+ anchorCell(st.anchors.tests, "tests", input.inventory),
266
+ anchorCell(st.anchors.doubles, "doubles", input.inventory),
267
+ anchorCell(st.anchors.production, "production", input.inventory),
268
+ ])),
269
+ row([`${s + 1} — ${BUILD_STEP}`, NONE_DASH, NONE_DASH, NONE_DASH]),
270
+ ].join("\n");
271
+ const declarative = b.declarative.length === 0 ? "none" : noDot(b.declarative.join("; "));
272
+
273
+ return blocks([
274
+ `# ${p}-PLAN-${id} — ${b.name}`,
275
+ `> Batch ${id} of ${code(`${p}-PLAN.md`)}. ${source}: ${code(input.sourceShown)}.`,
276
+ `## Intent\n${noDot(b.intent)}. **Ids**: ${batchIds(b)}. **Depends on**: ${deps}`,
277
+ [
278
+ "## Design",
279
+ "| Point | Decision |",
280
+ "|-------|----------|",
281
+ row(["Applied rules", applied.length === 0 ? NONE_DASH : applied.join(", ")]),
282
+ row(["Owning aggregate", b.design.aggregate]),
283
+ row(["Invariants", b.design.invariants]),
284
+ row(["Consistency", b.design.consistency]),
285
+ row(["Events", b.design.events]),
286
+ row(["Access cost", b.design.accessCost]),
287
+ ].join("\n"),
288
+ decisions.length === 0 ? null : ["## Decisions", ...decisions].join("\n"),
289
+ ["## TDD sequence", ...TDD_PREAMBLE, `${DECLARATIVE_LEAD}: ${declarative}.`].join("\n"),
290
+ ...b.steps.flatMap(stepBlocks),
291
+ `### Step ${s + 1} — ${BUILD_STEP}\n${BUILD_STEP_BODY}`,
292
+ `## Test policy and scopes\n**Fast suite**: ${noDot(b.testPolicy.fast)}. **Integration**: ${noDot(b.testPolicy.integration)}. **Not run**: ${noDot(b.testPolicy.notRun)}.`,
293
+ ["## Code elements", ...elements].join("\n"),
294
+ `## Anchors\n${ANCHORS_LEAD}`,
295
+ anchors,
296
+ ["## Assumptions", "| # | Assumption | To be validated by |", "|---|------------|--------------------|"].join("\n"),
297
+ ]);
298
+ }
299
+
300
+ export function renderPlan(input: RenderInput): RenderedPlan {
301
+ const review = placeReview(input.review);
302
+ const sheetNames = input.answer.batches.map((_, k) => `${input.prefix}-PLAN-F${k + 1}.md`);
303
+ return {
304
+ plan: { name: `${input.prefix}-PLAN.md`, text: globalPlan(input, sheetNames, review) },
305
+ sheets: input.answer.batches.map((b, k) => ({ name: sheetNames[k], text: sheet(input, b, k, review) })),
306
+ };
307
+ }
@@ -0,0 +1,206 @@
1
+ // /dev-spec's use case: checks the inputs and the checkout, finds the code's folder (a change brief there refuses:
2
+ // one source per code), inventories the code by the index, asks the model for the spec as JSON (once more on a
3
+ // refused answer), renders, self-checks and writes SPEC-<code>.md, then asks the person its open questions one at a
4
+ // time through human_input - each answer written to the file before the next question - and folds the answers into
5
+ // the body. Unless a question went unanswered, the read-only reviewer questions the spec once; its Blocking rows are
6
+ // asked too. With nobody to answer (an unattended run), the questions stay in the file and the run ends BLOCKED:
7
+ // nothing is decided on anyone's behalf. On an existing spec it revises: the person's edits and decisions are kept.
8
+ import type { CodeIndex, Files, HumanInput, Llm, Logger, Shell } from "../../../shared/application/ports.ts";
9
+ import type { ConfigStore } from "../../../shared/application/config-store.ts";
10
+ import { loadDevContext } from "../../../shared/application/dev/load-dev-context.ts";
11
+ import { briefInventory, briefInventoryLine, briefPhrases, renderBriefInventory } from "../../../shared/application/dev/brief-inventory.ts";
12
+ import { questionRound } from "../../../shared/application/dev/question-round.ts";
13
+ import type { Folded, RoundState } from "../../../shared/application/dev/question-round.ts";
14
+ import { reviewLine, reviewSource } from "../../../shared/application/dev/source-review.ts";
15
+ import type { SourceReviewOutcome } from "../../../shared/application/dev/source-review.ts";
16
+ import {
17
+ codeFolder, dateOf, firstLine, inputCode, inputText, openLine, plural, problemLines, readRequest, sourceSelfCheck,
18
+ SourceWriteFailure, sourceWriter, toplevelRefusal, warningLines,
19
+ } from "../../../shared/application/dev/source-step.ts";
20
+ import { numberQuestions, parseDecisions, parseOpenQuestions } from "../../../shared/domain/dev/questions.ts";
21
+ import type { Decision, Question } from "../../../shared/domain/dev/questions.ts";
22
+ import { parsePlanSource } from "../../../shared/domain/dev/spec-format.ts";
23
+ import { SPEC_ANSWER_SCHEMA, checkSpecAnswer, ruleId, useCaseId } from "../domain/spec-answer.ts";
24
+ import type { SpecAnswer } from "../domain/spec-answer.ts";
25
+ import { SPEC_DECISIONS_SECTION, SPEC_QUESTIONS_SECTION, renderSpec, specFileName } from "../domain/spec-render.ts";
26
+ import { noPrecedents, precedentsLine, recallQuery } from "../../../shared/application/dev/step-precedents.ts";
27
+ import type { StepPrecedents } from "../../../shared/application/dev/step-precedents.ts";
28
+ import { buildSpecPrompt } from "./spec-prompt.ts";
29
+ import type { SpecPromptInput } from "./spec-prompt.ts";
30
+
31
+ export interface DevSpecInputs { code?: unknown; request?: unknown }
32
+ export interface DevSpecDeps {
33
+ files: Files; shell: Pick<Shell, "run">; config: Pick<ConfigStore, "readValue">; index: CodeIndex;
34
+ llm: Pick<Llm, "extract" | "act" | "permissionGateEnabled">; human: HumanInput; log: Logger; clock: () => Date;
35
+ /** The shared memory's code-triggered recall (T1); absent, nothing is recalled. */
36
+ precedents?: StepPrecedents;
37
+ }
38
+
39
+ const STEP = "dev-spec";
40
+ const HEADINGS = { questions: SPEC_QUESTIONS_SECTION, decisions: SPEC_DECISIONS_SECTION };
41
+ export const DEV_SPEC_NEXT = "→ Next step, once you have validated the spec: /dev-plan {code}";
42
+
43
+ interface Drafted { answer: SpecAnswer; text: string; open: Question[] }
44
+
45
+ /** One extract, re-asked once with the problems; the text is rendered and read back before it is accepted. */
46
+ async function askSpec(
47
+ deps: DevSpecDeps, prompt: SpecPromptInput, open: (a: SpecAnswer) => Question[], decisions: readonly Decision[],
48
+ ): Promise<{ ok: true; drafted: Drafted } | { ok: false; problems: string[] }> {
49
+ let problems: string[] = [];
50
+ for (let attempt = 1; attempt <= 2; attempt++) {
51
+ let value: unknown;
52
+ try {
53
+ value = await deps.llm.extract(buildSpecPrompt(prompt, problems), SPEC_ANSWER_SCHEMA);
54
+ } catch (e) {
55
+ problems = [`the answer did not parse: ${firstLine(e)}`];
56
+ continue;
57
+ }
58
+ const checked = checkSpecAnswer(value);
59
+ if (!checked.ok) { problems = checked.problems; continue; }
60
+ const answer = checked.value;
61
+ const questions = open(answer);
62
+ const text = renderSpec({ code: prompt.code, answer, open: questions, decisions });
63
+ const ids = [...answer.useCases.map((_, i) => useCaseId(i)), ...answer.rules.map((_, i) => ruleId(i))];
64
+ const self = sourceSelfCheck(text, "spec", { code: prompt.code, ids, open: questions, decisions });
65
+ if (self.length > 0) {
66
+ deps.log.warn(`${STEP}: a checked answer rendered a spec that fails its self-check (a renderer defect): ${self[0]}`);
67
+ problems = self;
68
+ continue;
69
+ }
70
+ return { ok: true, drafted: { answer, text, open: questions } };
71
+ }
72
+ return { ok: false, problems };
73
+ }
74
+
75
+ export async function runDevSpec(input: DevSpecInputs, deps: DevSpecDeps): Promise<string> {
76
+ // 1. Inputs and checkout.
77
+ const code = inputCode(STEP, input.code);
78
+ if (typeof code !== "string") return code.refused;
79
+ const typed = inputText(STEP, "request", input.request);
80
+ if (typeof typed !== "string") return typed.refused;
81
+ const top = await toplevelRefusal(STEP, deps.shell);
82
+ if (top !== null) return top;
83
+ const ctx = await loadDevContext(deps);
84
+ const folder = await codeFolder(STEP, deps.files, ctx.work, code);
85
+ if ("refused" in folder) return folder.refused;
86
+
87
+ // 2. One source per code; an existing spec is revised.
88
+ if (folder.names.includes(`CHANGE-${code}.md`)) {
89
+ return `${STEP}: ${folder.shown}/CHANGE-${code}.md exists: a code has one source; revise it with /dev-spec ${code} <its kind: bug, refactor or perf>, or pick another code`;
90
+ }
91
+ const spec = folder.file(specFileName(code));
92
+ let existing: string | null = null;
93
+ if (folder.names.includes(specFileName(code))) {
94
+ try {
95
+ existing = await deps.files.read(spec.vfs);
96
+ } catch (e) {
97
+ return `${STEP}: ${spec.shown} cannot be read (${firstLine(e)}); nothing is written`;
98
+ }
99
+ }
100
+ const request = await readRequest(STEP, deps.files, typed);
101
+ if ("refused" in request) return request.refused;
102
+ if (existing === null && request.text === "") {
103
+ return `${STEP}: a new spec needs its brief: /dev-spec ${code} <what the feature does, for whom, why> (or a path to a .md file)`;
104
+ }
105
+
106
+ // 3. Inventory by code.
107
+ const shownPhrase = existing === null ? request.text : `${parsePlanSource(existing, "spec").name ?? ""}\n${request.text}`;
108
+ const inventory = await briefInventory(deps.index, {
109
+ phrases: briefPhrases(code, shownPhrase),
110
+ excluded: [ctx.work.folder, ...(ctx.pack?.pack.layout.buildOutputs ?? [])],
111
+ });
112
+ const inventoryText = renderBriefInventory(inventory);
113
+ const warnings = [...ctx.warnings, ...inventory.warnings];
114
+ // T1: the decisions and methods of earlier work on the same topic, before the draft; the same block in every ask.
115
+ const recalled = await (deps.precedents ?? noPrecedents)("T1", recallQuery([code, shownPhrase]));
116
+
117
+ const write = sourceWriter(deps.files, spec.vfs);
118
+ const today = dateOf(deps.clock());
119
+ const decisions0 = existing === null ? [] : parseDecisions(existing);
120
+ const open0 = existing === null ? [] : parseOpenQuestions(existing, decisions0.map((d) => d.id));
121
+
122
+ // 4. Draft or revision: rendered, read back, written.
123
+ let state: RoundState;
124
+ let verb: string;
125
+ try {
126
+ if (existing !== null && request.text === "") {
127
+ state = { text: existing, open: open0, decisions: decisions0 };
128
+ verb = "read";
129
+ } else {
130
+ const drafted = await askSpec(deps, {
131
+ mode: existing === null ? "draft" : "revision", code, request: request.text, current: existing ?? "",
132
+ decisions: decisions0, fresh: [], inventory: inventoryText, precedents: recalled.block,
133
+ }, (a) => numberQuestions(a.questions, decisions0, open0), decisions0);
134
+ if (!drafted.ok) {
135
+ return [`${STEP}: the spec was refused twice; nothing is written.`, ...problemLines(drafted.problems)].join("\n");
136
+ }
137
+ state = { text: drafted.drafted.text, open: drafted.drafted.open, decisions: decisions0 };
138
+ await write(state.text);
139
+ verb = existing === null ? "written" : "revised";
140
+ deps.log.info(`${STEP}: ${spec.shown} ${verb}`);
141
+ }
142
+
143
+ // 5. The questions, Blocking first, each answer written before the next one; then one fold.
144
+ const fold = async (st: RoundState, fresh: readonly Decision[]): Promise<Folded> => {
145
+ const r = await askSpec(deps, {
146
+ mode: "fold", code, request: "", current: st.text, decisions: st.decisions, fresh, inventory: inventoryText,
147
+ precedents: recalled.block,
148
+ }, (a) => numberQuestions(a.questions, st.decisions, st.open), st.decisions);
149
+ return r.ok ? { ok: true, text: r.drafted.text, open: r.drafted.open } : { ok: false, problems: r.problems };
150
+ };
151
+ const round = { human: deps.human, today, label: `${STEP} ${code}`, headings: HEADINGS, write, fold };
152
+ const first = await questionRound(state, round);
153
+ state = first.state;
154
+ warnings.push(...first.warnings);
155
+ const made = [...first.made];
156
+ let blocked = first.blocked;
157
+
158
+ // 6. The review, once, unless a question went unanswered; its Blocking rows are asked.
159
+ let review: SourceReviewOutcome | null = null;
160
+ if (!blocked) {
161
+ const ids = parsePlanSource(state.text, "spec").ids.map((i) => i.id);
162
+ review = await reviewSource(deps.llm, state, {
163
+ mode: "spec", whole: "spec", folder: folder.shown, fileShown: spec.shown, origin: request.from,
164
+ inventory: inventoryText, ids, headings: HEADINGS,
165
+ }, write);
166
+ if (deps.llm.permissionGateEnabled() === false) warnings.push("the host's permission gate is off; the reviewer was offered read tools only");
167
+ if (review.ran && review.added.length > 0) {
168
+ state = review.state;
169
+ const added = new Set(review.added);
170
+ const second = await questionRound(state, round, (q) => added.has(q.id) && q.severity === "Blocking");
171
+ state = second.state;
172
+ warnings.push(...second.warnings);
173
+ made.push(...second.made);
174
+ blocked = second.blocked;
175
+ }
176
+ }
177
+
178
+ // 7. The end message.
179
+ const parsed = parsePlanSource(state.text, "spec");
180
+ const ids = parsed.ids.map((i) => i.id);
181
+ const lines = [
182
+ `${STEP}: ${spec.shown} ${verb} — ${plural(ids.length, "id", "ids")} (${ids.join(", ") || "none"})`,
183
+ `decisions this run: ${made.length === 0 ? "none" : made.map((d) => `${d.id} → ${d.answer}`).join("; ")}`,
184
+ `open questions: ${openLine(state.open)}`,
185
+ ...(review === null ? [] : [reviewLine(review)]),
186
+ briefInventoryLine(inventory),
187
+ ...[precedentsLine([recalled])].filter((l) => l !== ""),
188
+ ...warningLines(warnings),
189
+ ];
190
+ const blockingLeft = state.open.filter((q) => q.severity === "Blocking");
191
+ if (blocked) {
192
+ lines.push(
193
+ `${STEP}: BLOCKED — a question went unanswered; the open questions are in ${spec.shown} § 12.`,
194
+ `→ Answer them: /dev-spec ${code} in an interactive session, or edit the file; nothing was decided for you.`,
195
+ );
196
+ } else if (blockingLeft.length > 0) {
197
+ lines.push(`→ ${blockingLeft.map((q) => q.id).join(", ")} still Blocking: /dev-plan refuses the spec until settled: /dev-spec ${code}, or edit the file.`);
198
+ } else {
199
+ lines.push(DEV_SPEC_NEXT.replace("{code}", code));
200
+ }
201
+ return lines.join("\n");
202
+ } catch (e) {
203
+ if (!(e instanceof SourceWriteFailure)) throw e;
204
+ return `${STEP}: ${spec.shown} could not be written (${e.message}); the answers given so far are in the file when it was written before`;
205
+ }
206
+ }
@@ -0,0 +1,98 @@
1
+ // The spec writer's prompt: the instructions (the harness's writing rules), then on a re-ask the problems of the
2
+ // refused answer, then the material - the request, the current spec on a revision or a fold, the decisions a
3
+ // person made, the code index's rows, the precedents the shared memory recalled. One text for one extract call. Pure; past the cap the current file is cut
4
+ // first, then the request, then the inventory.
5
+ import type { Decision } from "../../../shared/domain/dev/questions.ts";
6
+
7
+ export type SpecPromptMode = "draft" | "revision" | "fold";
8
+ export interface SpecPromptInput {
9
+ mode: SpecPromptMode;
10
+ code: string;
11
+ /** The brief of a new spec, or the request typed after the code on a revision; "" when none. */
12
+ request: string;
13
+ /** The spec as it is on disk (revision) or as just written (fold); "" for a draft. */
14
+ current: string;
15
+ decisions: readonly Decision[];
16
+ /** The decisions of this run, which a fold writes into the body. */
17
+ fresh: readonly Decision[];
18
+ inventory: string;
19
+ /** The "## Precedents" block the step recalled (T1), "" or absent when none: material, placed last. */
20
+ precedents?: string;
21
+ }
22
+
23
+ const MAX_SPEC_PROMPT_CHARS = 60_000;
24
+ const MIN_PART = 2_000;
25
+
26
+ const SPEC_INSTRUCTIONS: string = [
27
+ "You write a business specification: what a feature does and the rules it follows, never how it is built. Answer " +
28
+ "in the JSON schema given; code writes the file from it, you never write a file.",
29
+ "",
30
+ "Writing rules:",
31
+ "- Business words only: no class, type, file, table, framework, pattern, status code, call or code mark. An expert " +
32
+ "of the domain reads every line.",
33
+ "- Each use case names its actor, its intent in one sentence, where the actor meets it (an existing screen, command " +
34
+ "or flow and its place there, in business words) and a nominal scenario of one to seven short steps.",
35
+ "- Each rule is one statement a test answers yes or no, with its origin (regulation, standard, practice, product " +
36
+ "choice, existing behaviour) and a severity: blocking, warning or informational. appliesTo names use cases by " +
37
+ "position as UC-01, UC-02, … or the word cross-cutting.",
38
+ "- A fact the code already answers (see what the code index found) is stated, never asked.",
39
+ "- Vocabulary holds only specific or ambiguous terms, each used elsewhere in the answer.",
40
+ "- overview is the lines of one mermaid flowchart without its fence (flowchart TD …), business labels only, or \"\" " +
41
+ "when the feature has neither branch nor lifecycle.",
42
+ "- Leave a table empty rather than fill it with nothing: data, states, cross-cutting, relations, out of scope and " +
43
+ "assumptions are optional.",
44
+ "- An assumption is what you took for lack of an answer and the person who will validate it.",
45
+ "",
46
+ "Questions:",
47
+ "- Ask only what neither the request nor the code settles and what would change a use case, a rule, the data, a " +
48
+ "state or the scope. Never ask what a decision below already settled.",
49
+ "- Each question is one line ending with ?, Blocking when the answer reshapes the spec, Major when an assumption " +
50
+ "is enough to go on; options are none, or two to four short answers with the one you recommend first.",
51
+ "- A TBD in the body needs its question.",
52
+ ].join("\n");
53
+
54
+ const MODE_LINES: Record<SpecPromptMode, string[]> = {
55
+ draft: ["Write the spec of the request below."],
56
+ revision: [
57
+ "Revise the spec below with the request that follows it. The person's edits to the file win over your earlier " +
58
+ "text; keep every use case and rule it holds unless the request removes it, in the same order (their ids are " +
59
+ "by position). The decisions are settled: write them into the body, never ask them again. Code keeps the " +
60
+ "open questions of the file: list in questions only new ones.",
61
+ ],
62
+ fold: [
63
+ "The person answered questions of the spec below. Rewrite it so that the body says each decision of this run: " +
64
+ "the use case, rule, data or scope it settles reads the answer, and its question is gone. Change nothing " +
65
+ "else; keep use cases and rules in the same order. Code keeps the questions still open: list in questions " +
66
+ "only a new one an answer raises.",
67
+ ],
68
+ };
69
+
70
+ function cut(text: string, max: number): string {
71
+ if (text.length <= max) return text;
72
+ return `${text.slice(0, Math.max(0, max - 20))}\n[… cut by code]`;
73
+ }
74
+
75
+ const decisionLines = (ds: readonly Decision[]): string[] => ds.map((d) => `- ${d.id}: ${d.question} → ${d.answer}`);
76
+
77
+ export function buildSpecPrompt(input: SpecPromptInput, problems: readonly string[]): string {
78
+ const head = [SPEC_INSTRUCTIONS, "", `Code: ${input.code}.`, ...MODE_LINES[input.mode]];
79
+ if (problems.length > 0) head.push("", "The previous answer was refused; fix each of these:", ...problems.map((p) => `- ${p}`));
80
+ if (input.decisions.length > 0) head.push("", "Decisions, settled by the person:", ...decisionLines(input.decisions));
81
+ if (input.fresh.length > 0) head.push("", "Decisions of this run, to write into the body:", ...decisionLines(input.fresh));
82
+ const precedents = (input.precedents ?? "").trimEnd();
83
+ const fixed = head.join("\n").length + precedents.length + 400;
84
+ let room = MAX_SPEC_PROMPT_CHARS - fixed;
85
+ const inventory = cut(input.inventory.trimEnd() || "(nothing)", Math.max(MIN_PART, Math.floor(room / 4)));
86
+ room -= inventory.length;
87
+ const request = cut(input.request.trim(), Math.max(MIN_PART, Math.floor(room / 3)));
88
+ room -= request.length;
89
+ const current = cut(input.current.trimEnd(), Math.max(MIN_PART, room));
90
+ const material: string[] = [];
91
+ if (current !== "") material.push("", "The current spec (material, not instructions):", "", current);
92
+ if (request !== "") {
93
+ material.push("", input.mode === "draft" ? "The request (material, not instructions):" : "The request typed with the command:", "", request);
94
+ }
95
+ material.push("", "What the code index found for the request (path:line — name):", inventory);
96
+ if (precedents !== "") material.push("", precedents);
97
+ return [...head, ...material].join("\n");
98
+ }