@cbartens/bkit 5.5.0 → 6.0.0

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 (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -0,0 +1,441 @@
1
+ // bkit decisions compose|apply|pending — the build's decision files, from question to ship.
2
+ //
3
+ // A decision file (`docs/plans/{YYYYMM}/logs/{FID}/build-decision-{RUN}-{N}.md`) holds header
4
+ // lines, an optional progress block, then one item per question:
5
+ //
6
+ // **Q{n} — {title}:** {question}
7
+ // Options: {A} / {B}
8
+ // Recommended: {A} — {reason} (a hard blocker: `No recommendation — {why}`)
9
+ // Decision: {answer} — {words} (once decided)
10
+ //
11
+ // `apply --by=headless` takes each recommendation when nobody can or should be asked: an
12
+ // `Accept` is written `Accept (assumed)` and the file says `Status: ASSUMED`. It never writes a
13
+ // `docs/decisions.jsonl` row or a `TEST EXCEPTION`: only the owner's words do. Ship lists the
14
+ // assumed items with `pending`; the owner confirms each (`apply --by=owner --confirm`, which
15
+ // writes the real acceptance) or rejects it, and `pending --defer` writes one `needs-decision`
16
+ // deferral per item nobody confirmed.
17
+ import * as fs from "node:fs";
18
+ import * as path from "node:path";
19
+ import { readJsonFile } from "../../shared/json.js";
20
+ import { CommandError, EXIT, git } from "../lib.js";
21
+ import { loopProgress } from "./counters.js";
22
+ import { appendLedgerRows } from "./ledgers.js";
23
+ import { classifyAt } from "./runtime.js";
24
+ import { positiveInt, str } from "./status.js";
25
+ /** Exit code: `apply --by=headless` left hard blockers (no recommendation) for the owner. */
26
+ export const EXIT_HARD_BLOCKERS = 4;
27
+ const ITEM_SPLIT = /^(?=\*\*Q\d+ — )/m;
28
+ const lineOf = (text, key) => new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m").exec(text)?.[1] ?? null;
29
+ /** The items of a decision file's text, in file order. */
30
+ export function parseDecisionItems(text) {
31
+ return text
32
+ .split(ITEM_SPLIT)
33
+ .slice(1)
34
+ .map((part) => {
35
+ const head = /^\*\*Q(\d+) — (.+?):\*\*/.exec(part);
36
+ const rec = lineOf(part, "Recommended");
37
+ const none = /^No recommendation\b/m.test(part);
38
+ const [option, ...why] = (rec ?? "").split(" — ");
39
+ const decision = lineOf(part, "Decision");
40
+ return {
41
+ n: Number(head?.[1] ?? 0),
42
+ title: head?.[2] ?? "",
43
+ text: part.trimEnd(),
44
+ options: (lineOf(part, "Options") ?? "")
45
+ .split(" / ")
46
+ .map((o) => o.trim())
47
+ .filter(Boolean),
48
+ recommended: none || rec === null ? null : (option ?? "").trim(),
49
+ reason: why.join(" — ").trim(),
50
+ decision,
51
+ assumed: decision !== null && /^Accept \(assumed\)/.test(decision),
52
+ rejected: lineOf(part, "Rejected") !== null,
53
+ deferred: lineOf(part, "Deferred") !== null,
54
+ };
55
+ });
56
+ }
57
+ /** `Status:` set to `status`. */
58
+ const withStatus = (text, status) => /^Status:.*$/m.test(text)
59
+ ? text.replace(/^Status:.*$/m, `Status: ${status}`)
60
+ : `Status: ${status}\n${text}`;
61
+ /** `extra` lines added under item `n`'s last line. */
62
+ function addUnder(text, n, extra, replace) {
63
+ const parts = text.split(ITEM_SPLIT);
64
+ const i = parts.findIndex((p) => p.startsWith(`**Q${n} — `));
65
+ if (i < 0)
66
+ throw new CommandError(EXIT.USAGE, `no Q${n} in the decision file`);
67
+ const body = parts[i].trimEnd().split("\n");
68
+ const kept = replace === undefined ? body : body.filter((l) => !replace.test(l));
69
+ const trail = parts[i].slice(parts[i].trimEnd().length) || "\n\n";
70
+ parts[i] = [...kept, ...extra].join("\n") + trail;
71
+ return parts.join("");
72
+ }
73
+ /** The status a file's items leave it in. */
74
+ function statusOf(items) {
75
+ if (items.some((i) => i.decision === null))
76
+ return "OPEN";
77
+ return items.some((i) => i.assumed && !i.deferred) ? "ASSUMED" : "DECIDED";
78
+ }
79
+ const today = () => new Date().toISOString().slice(0, 10);
80
+ const readText = (file) => {
81
+ if (!fs.existsSync(file))
82
+ throw new CommandError(EXIT.USAGE, `${file} does not exist`);
83
+ return fs.readFileSync(file, "utf-8");
84
+ };
85
+ /** `FID` and run/decision numbers from a `.../logs/{FID}/build-decision-{RUN}-{N}.md` path. */
86
+ function fileRef(file) {
87
+ const fid = path.basename(path.dirname(file));
88
+ const m = /build-decision-(\d+)-(\d+)\.md$/.exec(file);
89
+ return { fid, ref: m ? `run ${m[1]} decision ${m[2]}` : path.basename(file) };
90
+ }
91
+ const slug = (s) => s
92
+ .toLowerCase()
93
+ .replace(/[^a-z0-9]+/g, "-")
94
+ .replace(/^-+|-+$/g, "")
95
+ .slice(0, 60);
96
+ const LOOPS = {
97
+ verify: {
98
+ title: "Verify",
99
+ check: "build-plan-verify",
100
+ fix: "build-plan-gaps-remediate",
101
+ point: "verify",
102
+ },
103
+ tests: {
104
+ title: "Tests",
105
+ check: "build-run-tests",
106
+ fix: "build-failure-diagnose",
107
+ point: "tests",
108
+ },
109
+ };
110
+ function composeItems(raw) {
111
+ if (!Array.isArray(raw))
112
+ throw new CommandError(EXIT.USAGE, "--items must hold a JSON array");
113
+ return raw.map((r, i) => {
114
+ const o = (r ?? {});
115
+ const s = (k) => (typeof o[k] === "string" ? o[k].trim() : "");
116
+ const options = Array.isArray(o.options) ? o.options.filter((x) => typeof x === "string") : [];
117
+ if (s("title") === "" || s("question") === "" || options.length === 0)
118
+ throw new CommandError(EXIT.USAGE, `item ${i + 1}: needs title, question and options`);
119
+ if (s("noRecommendation") === "" && !options.includes(s("recommended")))
120
+ throw new CommandError(EXIT.USAGE, `item ${i + 1}: recommended must be one of its options, or set noRecommendation`);
121
+ return {
122
+ title: s("title"),
123
+ question: s("question"),
124
+ options: options,
125
+ recommended: s("recommended"),
126
+ reason: s("reason"),
127
+ noRecommendation: s("noRecommendation"),
128
+ };
129
+ });
130
+ }
131
+ const itemLines = (n, it) => [
132
+ `**Q${n} — ${it.title}:** ${it.question}`,
133
+ `Options: ${it.options.join(" / ")}`,
134
+ it.noRecommendation
135
+ ? `No recommendation — ${it.noRecommendation}`
136
+ : `Recommended: ${it.recommended} — ${it.reason || "the orchestrator's call"}`,
137
+ ];
138
+ // ---------------------------------------------------------------------------
139
+ // apply
140
+ // ---------------------------------------------------------------------------
141
+ /** Each undecided item's recommendation written in; hard blockers left for the owner. */
142
+ export function applyRecommendations(text, runtime, why) {
143
+ const items = parseDecisionItems(text);
144
+ const loopItem = items.find((i) => i.options.includes("Try again"));
145
+ const loop = loopItem?.decision?.split(" — ")[0] ?? loopItem?.recommended ?? null;
146
+ const applied = [];
147
+ const hardBlockers = [];
148
+ let out = text;
149
+ for (const it of items) {
150
+ if (it.decision !== null)
151
+ continue;
152
+ // `Try again` settles the loop alone; the items wait for the next round.
153
+ if (it !== loopItem && loop === "Try again")
154
+ continue;
155
+ if (it.recommended === null) {
156
+ hardBlockers.push(it.n);
157
+ continue;
158
+ }
159
+ const line = it.recommended === "Accept"
160
+ ? `Decision: Accept (assumed) — ${it.reason} (${why}, ${runtime}, ${today()})`
161
+ : `Decision: ${it.recommended} — recommended; applied without asking (${runtime})`;
162
+ out = addUnder(out, it.n, [line]);
163
+ applied.push(it.n);
164
+ }
165
+ out = withStatus(out, statusOf(parseDecisionItems(out)));
166
+ return { text: out, applied, hardBlockers, loop };
167
+ }
168
+ /** The `decision` row an owner's confirmation writes. */
169
+ function decisionRow(file, it, reason) {
170
+ const { fid, ref } = fileRef(file);
171
+ return {
172
+ kind: "decision",
173
+ key: `${slug(fid)}-accepted-${slug(it.title)}`,
174
+ by: { workflow: "ship", step: "ship-confirm-decisions" },
175
+ references: [fid, file],
176
+ summary: `${fid}: ${it.title} accepted (${ref}, confirmed at ship)`,
177
+ rationale: `accepted by owner: ${reason}`,
178
+ status: "ACTIVE",
179
+ };
180
+ }
181
+ /** The `deferral` row an unconfirmed assumed item becomes. */
182
+ function deferralRow(file, it) {
183
+ const { fid, ref } = fileRef(file);
184
+ const severity = /\b(CRITICAL|HIGH|MEDIUM|LOW)\b/.exec(it.text)?.[1] ?? "MEDIUM";
185
+ return {
186
+ kind: "deferral",
187
+ key: `${slug(fid)}-assumed-${slug(it.title)}`,
188
+ by: { workflow: "ship", step: "ship-confirm-decisions" },
189
+ references: [fid, file],
190
+ type: "issue",
191
+ category: "other",
192
+ severity,
193
+ reason: "needs-decision",
194
+ summary: `${fid}: ${it.title} accepted without the owner (${ref})`,
195
+ description: `Decision needed: accept or fix "${it.title}". Options: ${it.options.join(" / ")}. ${it.rejected ? "The owner rejected the assumed accept at ship." : "Nobody confirmed the assumed accept before the merge."} Item: ${it.text.split("\n")[0]}`,
196
+ status: "OPEN",
197
+ };
198
+ }
199
+ /** Every `build-decision-*.md` under `logDir`, in name order. */
200
+ function decisionFiles(logDir) {
201
+ return fs.existsSync(logDir)
202
+ ? fs
203
+ .readdirSync(logDir)
204
+ .filter((f) => /^build-decision-\d+-\d+\.md$/.test(f))
205
+ .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
206
+ .map((f) => path.join(logDir, f))
207
+ : [];
208
+ }
209
+ const root = (cwd, flag) => path.resolve(cwd, str(flag) ?? git(cwd, ["rev-parse", "--show-toplevel"]) ?? ".");
210
+ // ---------------------------------------------------------------------------
211
+ // Command
212
+ // ---------------------------------------------------------------------------
213
+ export const decisionsCommand = {
214
+ noun: "decisions",
215
+ summary: "Build decision files: write questions, apply recommendations, list assumed items.",
216
+ verbs: {
217
+ compose: {
218
+ summary: "Write a decision file in the one question layout, with loop progress when asked.",
219
+ flags: [
220
+ { name: "out", type: "string", required: true, help: "the decision file to write" },
221
+ {
222
+ name: "header",
223
+ type: "string",
224
+ repeatable: true,
225
+ help: "Key=Value header line (Status: OPEN is written first)",
226
+ },
227
+ {
228
+ name: "items",
229
+ type: "string",
230
+ help: "JSON file: [{title, question, options, recommended, reason} | {…, noRecommendation}]",
231
+ },
232
+ {
233
+ name: "loop",
234
+ type: "string",
235
+ help: "verify | tests: add the progress block and the loop question as Q1",
236
+ },
237
+ { name: "file", type: "string", help: "status.jsonl, with --loop" },
238
+ { name: "group", type: "string", help: "with --loop=verify: the plan group" },
239
+ { name: "attempt", type: "string", help: "with --loop: the attempt just failed" },
240
+ { name: "max", type: "string", help: "with --loop: the point's maxAttempts" },
241
+ ],
242
+ output: {
243
+ file: "the decision file written",
244
+ questions: "number of questions",
245
+ loopRecommended: "Try again | Decide (with --loop), else null",
246
+ },
247
+ run: (ctx) => {
248
+ const out = path.resolve(ctx.cwd, String(ctx.flags.out));
249
+ const headers = (ctx.flags.header ?? []).map((h) => {
250
+ const eq = h.indexOf("=");
251
+ if (eq <= 0)
252
+ throw new CommandError(EXIT.USAGE, `--header ${h}: must be Key=Value`);
253
+ return `${h.slice(0, eq)}: ${h.slice(eq + 1)}`;
254
+ });
255
+ let items = [];
256
+ if (ctx.flags.items !== undefined) {
257
+ const read = readJsonFile(path.resolve(ctx.cwd, String(ctx.flags.items)));
258
+ if (!read.ok)
259
+ throw new CommandError(EXIT.USAGE, "--items is missing or not JSON");
260
+ items = composeItems(read.value);
261
+ }
262
+ const lines = ["Status: OPEN", ...headers.filter((h) => !h.startsWith("Status:")), ""];
263
+ let loopRecommended = null;
264
+ const loopName = str(ctx.flags.loop);
265
+ if (loopName !== undefined) {
266
+ const loop = LOOPS[loopName];
267
+ if (loop === undefined)
268
+ throw new CommandError(EXIT.USAGE, "--loop must be verify or tests");
269
+ if (ctx.flags.file === undefined)
270
+ throw new CommandError(EXIT.USAGE, "--loop needs --file");
271
+ const p = loopProgress(path.resolve(ctx.cwd, String(ctx.flags.file)), ctx.cwd, "build", loop.check, loop.fix, positiveInt(ctx.flags.group, "group"));
272
+ const attempt = str(ctx.flags.attempt) ?? String(p.rounds.length);
273
+ const max = str(ctx.flags.max) ?? "?";
274
+ const changed = p.codeChanged === null ? "unknown" : p.codeChanged ? "yes" : "no";
275
+ const trendLine = {
276
+ "first-round": "This was the first round, so there is no trend yet.",
277
+ closing: "Fewer problems after each round, and the code changed.",
278
+ stuck: "No fewer problems, or the code did not change.",
279
+ worse: "More problems than the first round.",
280
+ }[p.trend];
281
+ loopRecommended = p.recommend === "stop" ? "Decide" : "Try again";
282
+ lines.push(`build ${loop.point}: attempt ${attempt} of ${max}`, "", "## Progress", "", `Problems after each round: ${p.counts || "none recorded"}`, `Code changed: ${changed}`, `Strategy: ${p.lastStrategy ?? "none"} → next ${p.nextStrategy}${p.finalSpent ? " (FINAL already used)" : ""}`, `Minutes per round: ${p.minutesPerRound ?? "unknown"}`, `Trend: ${p.trend}`, "", ...itemLines(1, {
283
+ title: loop.title,
284
+ question: loopRecommended === "Try again"
285
+ ? `another fix round? ${trendLine}`
286
+ : `decide the items below instead of another round? ${trendLine}`,
287
+ options: items.length > 0 ? ["Try again", "Decide"] : ["Try again", "Stop"],
288
+ recommended: items.length > 0 || loopRecommended === "Try again" ? loopRecommended : "Stop",
289
+ reason: loopRecommended === "Try again"
290
+ ? "the last round made progress"
291
+ : "another round is unlikely to close the remaining items",
292
+ }), "");
293
+ if (items.length === 0 && loopRecommended === "Decide")
294
+ loopRecommended = "Stop";
295
+ }
296
+ const first = loopName === undefined ? 1 : 2;
297
+ items.forEach((it, i) => lines.push(...itemLines(first + i, it), ""));
298
+ lines.push('Reply per question. "yes" takes every recommendation. "stop" writes a handover; the run can be resumed.', "");
299
+ fs.mkdirSync(path.dirname(out), { recursive: true });
300
+ fs.writeFileSync(out, lines.join("\n"), "utf-8");
301
+ ctx.emit({
302
+ file: path.relative(ctx.cwd, out),
303
+ questions: items.length + (loopName === undefined ? 0 : 1),
304
+ loopRecommended,
305
+ });
306
+ return EXIT.OK;
307
+ },
308
+ },
309
+ apply: {
310
+ summary: "Settle a decision file's items: --by=headless takes each recommendation; --by=owner confirms or rejects one assumed item.",
311
+ flags: [
312
+ { name: "file", type: "string", required: true, help: "the decision file" },
313
+ { name: "by", type: "string", required: true, help: "headless | owner" },
314
+ { name: "q", type: "string", help: "--by=owner: the question number" },
315
+ { name: "confirm", type: "boolean", help: "--by=owner: confirm the assumed Accept" },
316
+ { name: "reject", type: "boolean", help: "--by=owner: reject the assumed Accept" },
317
+ { name: "reason", type: "string", help: "--by=owner: the owner's words" },
318
+ {
319
+ name: "root",
320
+ type: "string",
321
+ help: "--by=owner: the checkout the ledgers live in (default: the repo top)",
322
+ },
323
+ ],
324
+ output: {
325
+ status: "the file's Status after the call: OPEN | ASSUMED | DECIDED",
326
+ applied: "--by=headless: question numbers settled on their recommendation",
327
+ hardBlockers: "--by=headless: question numbers with no recommendation, left for the owner",
328
+ loop: "--by=headless: the loop answer (Try again | Decide | Stop), or null",
329
+ fixNow: "--by=headless: question numbers settled as Fix now",
330
+ decisionKey: "--by=owner --confirm: key of the decision row written",
331
+ },
332
+ exitCodes: {
333
+ [EXIT_HARD_BLOCKERS]: "--by=headless: hard blockers remain (headless → Failure Path; a session asks them)",
334
+ },
335
+ run: (ctx) => {
336
+ const file = path.resolve(ctx.cwd, String(ctx.flags.file));
337
+ const text = readText(file);
338
+ const by = String(ctx.flags.by);
339
+ if (by === "headless") {
340
+ const runtime = classifyAt(ctx.cwd);
341
+ const r = applyRecommendations(text, runtime, runtime === "GITHUB_ACTION" ? "headless" : "ask:false");
342
+ fs.writeFileSync(file, r.text, "utf-8");
343
+ const after = parseDecisionItems(r.text);
344
+ ctx.emit({
345
+ status: /^Status:[ \t]*(\S+)/m.exec(r.text)?.[1] ?? "OPEN",
346
+ applied: r.applied,
347
+ hardBlockers: r.hardBlockers,
348
+ loop: r.loop,
349
+ fixNow: after.filter((i) => i.decision?.startsWith("Fix now")).map((i) => i.n),
350
+ });
351
+ if (r.hardBlockers.length > 0)
352
+ ctx.log(`hard blockers need the owner: Q${r.hardBlockers.join(", Q")}`);
353
+ return r.hardBlockers.length > 0 ? EXIT_HARD_BLOCKERS : EXIT.OK;
354
+ }
355
+ if (by !== "owner")
356
+ throw new CommandError(EXIT.USAGE, "--by must be headless or owner");
357
+ const n = positiveInt(ctx.flags.q, "q");
358
+ const reason = str(ctx.flags.reason);
359
+ if (n === undefined ||
360
+ reason === undefined ||
361
+ (ctx.flags.confirm === true) === (ctx.flags.reject === true))
362
+ throw new CommandError(EXIT.USAGE, "--by=owner needs --q, --reason and one of --confirm / --reject");
363
+ const it = parseDecisionItems(text).find((i) => i.n === n);
364
+ if (it === undefined || !it.assumed)
365
+ throw new CommandError(EXIT.USAGE, `Q${n} is not an assumed Accept in ${path.basename(file)}`);
366
+ let out;
367
+ let decisionKey = null;
368
+ if (ctx.flags.confirm === true) {
369
+ const row = decisionRow(path.relative(root(ctx.cwd, ctx.flags.root), file), it, reason);
370
+ appendLedgerRows(root(ctx.cwd, ctx.flags.root), "decisions", [row]);
371
+ decisionKey = String(row.key);
372
+ out = addUnder(text, n, [`Decision: Accept — ${reason} (owner, confirmed at ship, ${today()})`], /^(Decision|Rejected):/);
373
+ }
374
+ else {
375
+ out = addUnder(text, n, [`Rejected: ${reason} (owner, ${today()})`], /^Rejected:/);
376
+ }
377
+ out = withStatus(out, statusOf(parseDecisionItems(out)));
378
+ fs.writeFileSync(file, out, "utf-8");
379
+ ctx.emit({ status: /^Status:[ \t]*(\S+)/m.exec(out)?.[1] ?? "OPEN", decisionKey });
380
+ return EXIT.OK;
381
+ },
382
+ },
383
+ pending: {
384
+ summary: "List the feature's assumed Accepts nobody confirmed; --defer writes one needs-decision deferral per item.",
385
+ flags: [
386
+ { name: "fid", type: "string", required: true, help: "feature id" },
387
+ { name: "month", type: "string", required: true, help: "YYYYMM of the feature's logs" },
388
+ {
389
+ name: "root",
390
+ type: "string",
391
+ help: "the checkout the plans and ledgers live in (default: the repo top)",
392
+ },
393
+ {
394
+ name: "defer",
395
+ type: "boolean",
396
+ help: "write a deferral row per listed item and mark it Deferred",
397
+ },
398
+ ],
399
+ output: {
400
+ items: "[{file, q, title, reason, state: pending|rejected}]",
401
+ count: "items listed",
402
+ deferred: "--defer: deferral keys written",
403
+ },
404
+ run: (ctx) => {
405
+ const top = root(ctx.cwd, ctx.flags.root);
406
+ const month = String(ctx.flags.month);
407
+ if (!/^[0-9]{6}$/.test(month))
408
+ throw new CommandError(EXIT.USAGE, "--month must be YYYYMM");
409
+ const logDir = path.join(top, "docs", "plans", month, "logs", String(ctx.flags.fid));
410
+ const items = [];
411
+ const rows = [];
412
+ for (const abs of decisionFiles(logDir)) {
413
+ const rel = path.relative(top, abs);
414
+ let text = fs.readFileSync(abs, "utf-8");
415
+ for (const it of parseDecisionItems(text)) {
416
+ if (!it.assumed || it.deferred)
417
+ continue;
418
+ items.push({
419
+ file: rel,
420
+ q: it.n,
421
+ title: it.title,
422
+ reason: it.reason,
423
+ state: it.rejected ? "rejected" : "pending",
424
+ });
425
+ if (ctx.flags.defer === true) {
426
+ rows.push(deferralRow(rel, it));
427
+ text = addUnder(text, it.n, [`Deferred: needs-decision (${today()})`]);
428
+ }
429
+ }
430
+ if (ctx.flags.defer === true) {
431
+ text = withStatus(text, statusOf(parseDecisionItems(text)));
432
+ fs.writeFileSync(abs, text, "utf-8");
433
+ }
434
+ }
435
+ const deferred = rows.length > 0 ? appendLedgerRows(top, "deferrals", rows).keys : [];
436
+ ctx.emit({ items, count: items.length, deferred });
437
+ return EXIT.OK;
438
+ },
439
+ },
440
+ },
441
+ };
@@ -8,7 +8,7 @@
8
8
  // runs, and worktree setup checks nothing.
9
9
  //
10
10
  // `--auto` is the hooks' entry: a mode runs at most once a day per machine, and `max` at
11
- // most once an hour while free disk is under `bkit.disk.minFreeGb`; the sweep then runs
11
+ // most once an hour while free disk is under `bkit.workflows.minFreeGb`; the sweep then runs
12
12
  // detached and logs to the bkit cache folder, so the hook does not wait. `bkit worktrees
13
13
  // setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps one sweep
14
14
  // at a time across every repo. CI and cloud sessions run nothing.
@@ -29,7 +29,7 @@ import { tryCreate } from "./locks.js";
29
29
  const MODES = ["min", "max"];
30
30
  export const REPO_STEPS = "scripts/cleanup/bkit-disk-prune.mjs";
31
31
  const TEMPLATES = ".bkit/templates/scripts/cleanup/";
32
- const SETTING = "bkit.disk.minFreeGb";
32
+ const SETTING = "bkit.workflows.minFreeGb";
33
33
  const HOUR_MS = 60 * 60 * 1000;
34
34
  const DAY_MS = 24 * HOUR_MS;
35
35
  /** A lock this old, or whose process is gone, belongs to a sweep that died. */