@cbartens/bkit 6.0.0 → 6.1.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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -7,17 +7,22 @@
7
7
  // folder). Each exports a list of steps; `max` also runs every `min` step. No file → nothing
8
8
  // runs, and worktree setup checks nothing.
9
9
  //
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.workflows.minFreeGb`; the sweep then runs
12
- // detached and logs to the bkit cache folder, so the hook does not wait. `bkit worktrees
13
- // setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps one sweep
14
- // at a time across every repo. CI and cloud sessions run nothing.
10
+ // `--auto` is the hooks' entry: a mode runs at most once a day, and `max` at most once an
11
+ // hour while free disk is under `bkit.workflows.minFreeGb`. The machine file's steps keep one
12
+ // limit for the whole machine; each checkout's repo steps keep their own, so a sweep another
13
+ // repo started never uses up this checkout's day. The sweep then runs detached, only for the
14
+ // files that are due, and logs to the bkit cache folder, so the hook does not wait. `bkit
15
+ // worktrees setup` calls `ensureDiskSpace` before it mints. A lock in the cache folder keeps
16
+ // one sweep at a time across every repo; the detached sweep and the worktree check wait for
17
+ // their turn, so a day already counted is never lost to a running sweep. A hand run stops
18
+ // unless it passes `--wait`. CI and cloud sessions run nothing.
15
19
  //
16
20
  // A step calls `note()` for what it found but would not delete on its own (a worktree with
17
21
  // uncommitted files, say). Each sweep replaces its checkout's notes in the cache folder;
18
22
  // `bkit tips` lists them first, so the workflow that prints its tips surfaces them.
19
23
 
20
24
  import { spawn, spawnSync } from "node:child_process";
25
+ import { createHash } from "node:crypto";
21
26
  import * as fs from "node:fs";
22
27
  import * as os from "node:os";
23
28
  import * as path from "node:path";
@@ -26,6 +31,7 @@ import { pathToFileURL } from "node:url";
26
31
  import { isCloudOrCi } from "../../checks/before/env.js";
27
32
  import { readJsonFile } from "../../shared/json.js";
28
33
  import { readBkitConfig } from "../../shared/settings.js";
34
+ import { TIMEOUTS } from "../../shared/timeouts.js";
29
35
  import { CommandError, EXIT, git, type CommandSpec } from "../lib.js";
30
36
  import { tryCreate } from "./locks.js";
31
37
 
@@ -40,6 +46,10 @@ const HOUR_MS = 60 * 60 * 1000;
40
46
  const DAY_MS = 24 * HOUR_MS;
41
47
  /** A lock this old, or whose process is gone, belongs to a sweep that died. */
42
48
  const LOCK_STALE_MS = HOUR_MS;
49
+ /** How often a running sweep renews its lock, so a long sweep is never taken for a dead one. */
50
+ const LOCK_RENEW_MS = 10 * 60 * 1000;
51
+ /** How often a waiting sweep tries the lock again. */
52
+ const LOCK_POLL_MS = 5_000;
43
53
  const GB = 1e9;
44
54
 
45
55
  const configDir = () =>
@@ -49,10 +59,21 @@ const cacheDir = () =>
49
59
  export const machineStepsPath = () => path.join(configDir(), "disk-prune.mjs");
50
60
  export const sweepLogPath = () => path.join(cacheDir(), "disk-prune.log");
51
61
  const lockPath = () => path.join(cacheDir(), "disk-prune.lock");
52
- const stampPath = (name: string) => path.join(cacheDir(), `disk-prune-${name}.stamp`);
62
+ /** One stamp per limit: the machine file's under `machine`, a checkout's repo file's under its top. */
63
+ const stampPath = (key: string, name: string) =>
64
+ path.join(
65
+ cacheDir(),
66
+ key === MACHINE
67
+ ? `disk-prune-${name}.stamp`
68
+ : `disk-prune-${name}-${createHash("sha256").update(key).digest("hex").slice(0, 12)}.stamp`,
69
+ );
70
+ /** A checkout's stamps this old belong to a checkout no hook has run in since (a removed worktree). */
71
+ const STAMP_STALE_MS = 7 * DAY_MS;
72
+ const REPO_STAMP = /^disk-prune-[a-z]+-[0-9a-f]{12}\.stamp$/;
53
73
  const notesPath = () => path.join(cacheDir(), "disk-prune-notes.json");
54
74
  /** Notes older than this are dropped: no sweep has run there since. */
55
75
  const NOTES_STALE_MS = 7 * DAY_MS;
76
+ const MACHINE = "machine";
56
77
 
57
78
  const gb = (bytes: number | null) => (bytes === null ? "?" : `${(bytes / GB).toFixed(1)} GB`);
58
79
  const errorText = (err: unknown) => (err instanceof Error ? err.message : String(err));
@@ -81,7 +102,8 @@ export interface Step {
81
102
  paths?: string[];
82
103
  }
83
104
 
84
- type Scope = "repo" | "machine";
105
+ export type Scope = "repo" | "machine";
106
+ const SCOPES: readonly string[] = ["repo", "machine"];
85
107
 
86
108
  interface StepFile {
87
109
  scope: Scope;
@@ -94,15 +116,21 @@ interface StepFile {
94
116
 
95
117
  const checkoutTop = (cwd: string) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
96
118
 
97
- /** The step files that exist for `cwd`, repo first. */
98
- function stepFilePaths(cwd: string): { scope: Scope; file: string; cwd: string }[] {
119
+ /** The step files that exist for `cwd`, repo first; only `scopes`' files when given. */
120
+ function stepFilePaths(
121
+ cwd: string,
122
+ scopes?: readonly Scope[],
123
+ ): { scope: Scope; file: string; cwd: string }[] {
99
124
  const top = checkoutTop(cwd);
100
125
  return [
101
126
  { scope: "repo" as const, file: path.join(top, REPO_STEPS), cwd: top },
102
127
  { scope: "machine" as const, file: machineStepsPath(), cwd: os.homedir() },
103
- ].filter((f) => fs.existsSync(f.file));
128
+ ].filter((f) => (scopes === undefined || scopes.includes(f.scope)) && fs.existsSync(f.file));
104
129
  }
105
130
 
131
+ /** Whose limits a step file counts against: the machine's, or its checkout's. */
132
+ const stampKey = (f: { scope: Scope; cwd: string }) => (f.scope === "machine" ? MACHINE : f.cwd);
133
+
106
134
  const isAction = (v: unknown) => typeof v === "string" || typeof v === "function";
107
135
 
108
136
  function stepProblem(step: unknown): string | null {
@@ -167,14 +195,22 @@ function sizeOf(patterns: string[], cwd: string): number | null {
167
195
  .reduce((sum, line) => sum + Number(line.split(/\s/)[0] ?? 0) * 1024, 0);
168
196
  }
169
197
 
170
- function due(name: string, everyMs: number, now: number): boolean {
171
- const st = fs.statSync(stampPath(name), { throwIfNoEntry: false });
198
+ function due(key: string, name: string, everyMs: number, now: number): boolean {
199
+ const st = fs.statSync(stampPath(key, name), { throwIfNoEntry: false });
172
200
  return st === undefined || now - st.mtimeMs >= everyMs;
173
201
  }
174
202
 
175
- function touch(...names: string[]): void {
203
+ /** Stamp `names` for `key`, and drop checkout stamps no hook has renewed in 7 days. */
204
+ function touch(key: string, ...names: string[]): void {
176
205
  fs.mkdirSync(cacheDir(), { recursive: true });
177
- for (const name of names) fs.writeFileSync(stampPath(name), `${new Date().toISOString()}\n`);
206
+ for (const name of names) fs.writeFileSync(stampPath(key, name), `${new Date().toISOString()}\n`);
207
+ for (const entry of fs.readdirSync(cacheDir())) {
208
+ if (!REPO_STAMP.test(entry)) continue;
209
+ const file = path.join(cacheDir(), entry);
210
+ const st = fs.statSync(file, { throwIfNoEntry: false });
211
+ if (st !== undefined && Date.now() - st.mtimeMs >= STAMP_STALE_MS)
212
+ fs.rmSync(file, { force: true });
213
+ }
178
214
  }
179
215
 
180
216
  function pidAlive(pid: number): boolean {
@@ -186,24 +222,80 @@ function pidAlive(pid: number): boolean {
186
222
  }
187
223
  }
188
224
 
189
- /** Take the sweep lock; a dead or hour-old holder's lock is replaced. False when held. */
225
+ /**
226
+ * Take the sweep lock; a lock whose holder is gone, or that no holder renewed for an hour, is
227
+ * replaced. False when held. The stale lock is renamed aside before it is removed, so a lock
228
+ * another sweep took after this one's check is put back, never deleted.
229
+ */
190
230
  function takeLock(): boolean {
191
231
  const file = lockPath();
192
232
  const line = `${new Date().toISOString()} ${process.pid}`;
193
233
  if (tryCreate(file, line)) return true;
194
234
  const st = fs.statSync(file, { throwIfNoEntry: false });
195
- const holder = st === undefined ? "" : fs.readFileSync(file, "utf-8");
235
+ if (st === undefined) return tryCreate(file, line);
236
+ const holder = fs.readFileSync(file, "utf-8");
196
237
  const pid = Number(holder.split(/\s+/)[1]);
197
- const live = st !== undefined && Date.now() - st.mtimeMs < LOCK_STALE_MS;
238
+ const live = Date.now() - st.mtimeMs < LOCK_STALE_MS;
198
239
  if (live && Number.isInteger(pid) && pid > 0 && pidAlive(pid)) return false;
199
- fs.rmSync(file, { force: true });
240
+ const aside = `${file}.${process.pid}.${Date.now()}.stale`;
241
+ try {
242
+ fs.renameSync(file, aside);
243
+ } catch (err) {
244
+ if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
245
+ return tryCreate(file, line);
246
+ }
247
+ const taken = fs.readFileSync(aside, "utf-8");
248
+ if (taken !== holder) {
249
+ restoreLock(aside, file);
250
+ return false;
251
+ }
252
+ fs.rmSync(aside, { force: true });
200
253
  return tryCreate(file, line);
201
254
  }
202
255
 
256
+ /** Put a lock renamed aside back at `file`, unless a third sweep has taken `file` since. */
257
+ function restoreLock(aside: string, file: string): void {
258
+ try {
259
+ fs.linkSync(aside, file);
260
+ } catch (err) {
261
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
262
+ }
263
+ fs.rmSync(aside, { force: true });
264
+ }
265
+
266
+ /**
267
+ * Take the sweep lock, waiting while another sweep holds it. False only when it is still held
268
+ * after `maxWaitMs` (default `LOCK_STALE_MS`): a sweep that long renews its lock, so `takeLock`
269
+ * never replaces it.
270
+ */
271
+ async function waitForLock(
272
+ pollMs: number,
273
+ log: (m: string) => void,
274
+ maxWaitMs: number = LOCK_STALE_MS + pollMs,
275
+ ): Promise<boolean> {
276
+ if (takeLock()) return true;
277
+ log(`another sweep is running (${lockPath()}) — waiting for it to end`);
278
+ const deadline = Date.now() + maxWaitMs;
279
+ while (Date.now() < deadline) {
280
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
281
+ if (takeLock()) return true;
282
+ }
283
+ return false;
284
+ }
285
+
286
+ const holdsLock = (file: string) =>
287
+ fs.existsSync(file) && fs.readFileSync(file, "utf-8").split(/\s+/)[1] === String(process.pid);
288
+
289
+ /** Mark this sweep's lock as live; another process's lock is left alone. */
290
+ function renewLock(): void {
291
+ const file = lockPath();
292
+ const now = new Date();
293
+ if (holdsLock(file)) fs.utimesSync(file, now, now);
294
+ }
295
+
203
296
  function releaseLock(): void {
204
297
  const file = lockPath();
205
- const pid = fs.existsSync(file) ? fs.readFileSync(file, "utf-8").split(/\s+/)[1] : undefined;
206
- if (pid === String(process.pid)) fs.rmSync(file, { force: true });
298
+ if (holdsLock(file)) fs.rmSync(file, { force: true });
207
299
  }
208
300
 
209
301
  // ---------------------------------------------------------------------------
@@ -234,17 +326,38 @@ export interface SweepResult {
234
326
  freeAfter: number | null;
235
327
  }
236
328
 
237
- function shell(command: string, cwd: string, log: (m: string) => void) {
238
- const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf-8", maxBuffer: 1 << 26 });
239
- const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
240
- if (out !== "") for (const line of out.split("\n").slice(-20)) log(` ${line}`);
241
- return r.error ? 127 : (r.status ?? 1);
329
+ /**
330
+ * Run a step's shell command and log its last 20 output lines. Spawned, not run in step: the
331
+ * lock renewal timer has to fire while a long command runs.
332
+ */
333
+ function shell(command: string, cwd: string, log: (m: string) => void): Promise<number> {
334
+ return new Promise((resolve) => {
335
+ const child = spawn("sh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
336
+ let out = "";
337
+ const keep = (chunk: Buffer) => {
338
+ out = `${out}${chunk.toString()}`.slice(-(1 << 16));
339
+ };
340
+ child.stdout.on("data", keep);
341
+ child.stderr.on("data", keep);
342
+ let settled = false;
343
+ const finish = (status: number) => {
344
+ if (settled) return;
345
+ settled = true;
346
+ const text = out.trim();
347
+ if (text !== "") for (const line of text.split("\n").slice(-20)) log(` ${line}`);
348
+ resolve(status);
349
+ };
350
+ child.on("error", () => finish(127));
351
+ child.on("close", (status) => finish(status ?? 1));
352
+ });
242
353
  }
243
354
 
244
355
  async function skipReason(step: Step, ctx: StepContext): Promise<string | null> {
245
356
  if (step.skip === undefined) return null;
246
357
  if (typeof step.skip === "string") {
247
- return shell(step.skip, ctx.cwd, ctx.log) === 0 ? `skip check passed: ${step.skip}` : null;
358
+ return (await shell(step.skip, ctx.cwd, ctx.log)) === 0
359
+ ? `skip check passed: ${step.skip}`
360
+ : null;
248
361
  }
249
362
  const answer = await step.skip(ctx);
250
363
  if (!answer) return null;
@@ -259,7 +372,7 @@ async function runStep(
259
372
  const reason = await skipReason(step, ctx);
260
373
  if (reason !== null) return { outcome: "skipped", detail: reason };
261
374
  if (typeof step.run === "string") {
262
- const status = shell(step.run, ctx.cwd, ctx.log);
375
+ const status = await shell(step.run, ctx.cwd, ctx.log);
263
376
  if (status !== 0) return { outcome: "failed", detail: `exit ${status}` };
264
377
  } else {
265
378
  await step.run(ctx);
@@ -271,13 +384,22 @@ async function runStep(
271
384
  }
272
385
 
273
386
  /**
274
- * Run the `mode` steps from every step file for `cwd`, one at a time, repo file first.
275
- * `dryRun` runs nothing and sizes each step's paths instead.
387
+ * Run the `mode` steps from every step file for `cwd` (only `scopes`' files when given), one
388
+ * at a time, repo file first. `dryRun` runs nothing and sizes each step's paths instead.
389
+ * While another sweep runs, `wait` waits for it to end; without it the sweep stops.
276
390
  */
277
391
  export async function sweep(opts: {
278
392
  cwd: string;
279
393
  mode: Mode;
280
394
  dryRun: boolean;
395
+ scopes?: readonly Scope[];
396
+ wait?: boolean;
397
+ /** How often a waiting sweep tries the lock again; tests shorten it. */
398
+ pollMs?: number;
399
+ /** Longest wait for the lock with `wait`; default a full stale lock age. */
400
+ maxWaitMs?: number;
401
+ /** How often a running sweep renews its lock; tests shorten it. */
402
+ renewMs?: number;
281
403
  log: (m: string) => void;
282
404
  }): Promise<SweepResult> {
283
405
  const result: SweepResult = {
@@ -289,7 +411,7 @@ export async function sweep(opts: {
289
411
  freeAfter: null,
290
412
  };
291
413
  if (isCloudOrCi()) return { ...result, reason: "ci" };
292
- const files = await Promise.all(stepFilePaths(opts.cwd).map(loadStepFile));
414
+ const files = await Promise.all(stepFilePaths(opts.cwd, opts.scopes).map(loadStepFile));
293
415
  result.files = files.map((f) => ({
294
416
  scope: f.scope,
295
417
  file: f.file,
@@ -321,10 +443,15 @@ export async function sweep(opts: {
321
443
  }
322
444
  return result;
323
445
  }
324
- if (!takeLock()) {
446
+ const locked = opts.wait
447
+ ? !(await waitForLock(opts.pollMs ?? LOCK_POLL_MS, opts.log, opts.maxWaitMs))
448
+ : !takeLock();
449
+ if (locked) {
325
450
  opts.log(`another sweep is running (${lockPath()})`);
326
451
  return { ...result, reason: "locked" };
327
452
  }
453
+ const renewal = setInterval(renewLock, opts.renewMs ?? LOCK_RENEW_MS);
454
+ renewal.unref();
328
455
  try {
329
456
  result.freeBefore = freeBytes(opts.cwd);
330
457
  opts.log(`${new Date().toISOString()} ${opts.mode} sweep, ${gb(result.freeBefore)} free`);
@@ -343,6 +470,7 @@ export async function sweep(opts: {
343
470
  opts.log(`${gb(result.freeBefore)} → ${gb(result.freeAfter)} free`);
344
471
  saveNotes(checkoutTop(opts.cwd), result.notes);
345
472
  } finally {
473
+ clearInterval(renewal);
346
474
  releaseLock();
347
475
  }
348
476
  return result;
@@ -407,13 +535,22 @@ export function formatNotes(notes: readonly string[]): string {
407
535
  // Scheduling (hooks) and the worktree check
408
536
  // ---------------------------------------------------------------------------
409
537
 
410
- /** Start `bkit disk prune --mode=<mode>` detached, its output appended to the sweep log. */
411
- function spawnDetached(mode: Mode, cwd: string): void {
538
+ /**
539
+ * The `bkit` arguments of the sweep `--auto` starts: the due `scopes` only, and waiting for
540
+ * a running sweep to end, so a hook that fires mid-sweep still gets its turn.
541
+ */
542
+ export function detachedArgs(mode: Mode, scopes: readonly Scope[]): string[] {
543
+ const only = scopes.length === 1 ? [`--scope=${scopes[0]}`] : [];
544
+ return ["disk", "prune", `--mode=${mode}`, ...only, "--wait"];
545
+ }
546
+
547
+ /** Start the `--auto` sweep detached, its output appended to the sweep log. */
548
+ function spawnDetached(mode: Mode, cwd: string, scopes: readonly Scope[]): void {
412
549
  fs.mkdirSync(cacheDir(), { recursive: true });
413
550
  const fd = fs.openSync(sweepLogPath(), "a");
414
551
  const child = spawn(
415
552
  process.execPath,
416
- [...process.execArgv, process.argv[1]!, "disk", "prune", `--mode=${mode}`],
553
+ [...process.execArgv, process.argv[1]!, ...detachedArgs(mode, scopes)],
417
554
  { cwd, detached: true, stdio: ["ignore", fd, fd] },
418
555
  );
419
556
  child.unref();
@@ -428,57 +565,77 @@ export interface Schedule {
428
565
  }
429
566
 
430
567
  /**
431
- * `--auto`: start a detached sweep when one is due. Under `minFreeGb` free → `max`, at
432
- * most hourly; else `mode`, at most daily. A `max` run also counts as that day's `min`.
568
+ * `--auto`: start a detached sweep of the step files that are due. Under `minFreeGb` free →
569
+ * `max`, at most hourly; else `mode`, at most daily. A `max` run also counts as that day's
570
+ * `min`. The machine file is due by the machine's stamps, the repo file by its checkout's.
433
571
  */
434
572
  export function schedule(opts: {
435
573
  cwd: string;
436
574
  mode: Mode;
437
575
  minFreeGb: number;
438
576
  now?: number;
439
- start?: (mode: Mode, cwd: string) => void;
577
+ start?: (mode: Mode, cwd: string, scopes: readonly Scope[]) => void;
440
578
  }): Schedule {
441
579
  if (isCloudOrCi()) return { started: null, reason: "ci" };
442
- if (stepFilePaths(opts.cwd).length === 0) return { started: null, reason: "no-steps" };
580
+ const files = stepFilePaths(opts.cwd);
581
+ if (files.length === 0) return { started: null, reason: "no-steps" };
443
582
  const now = opts.now ?? Date.now();
444
583
  const start = opts.start ?? spawnDetached;
445
584
  const free = freeBytes(opts.cwd);
446
- if (free !== null && free < opts.minFreeGb * GB) {
447
- if (!due("low", HOUR_MS, now)) return { started: null, reason: "not-due" };
448
- touch("low", "max", "min");
449
- start("max", opts.cwd);
450
- return { started: "max", reason: "low-disk" };
451
- }
452
- if (!due(opts.mode, DAY_MS, now)) return { started: null, reason: "not-due" };
453
- touch(...(opts.mode === "max" ? ["max", "min"] : ["min"]));
454
- start(opts.mode, opts.cwd);
455
- return { started: opts.mode, reason: "due" };
585
+ const low = free !== null && free < opts.minFreeGb * GB;
586
+ const mode = low ? "max" : opts.mode;
587
+ const dueFiles = files.filter((f) =>
588
+ low ? due(stampKey(f), "low", HOUR_MS, now) : due(stampKey(f), mode, DAY_MS, now),
589
+ );
590
+ if (dueFiles.length === 0) return { started: null, reason: "not-due" };
591
+ const names = low ? ["low", "max", "min"] : mode === "max" ? ["max", "min"] : ["min"];
592
+ for (const f of dueFiles) touch(stampKey(f), ...names);
593
+ start(
594
+ mode,
595
+ opts.cwd,
596
+ dueFiles.map((f) => f.scope),
597
+ );
598
+ return { started: mode, reason: low ? "low-disk" : "due" };
456
599
  }
457
600
 
458
601
  /**
459
602
  * Before worktree setup mints: under `minFreeGb` free with step files present, run the
460
- * `max` steps and check again. Null = carry on; else why the worktree must not be made.
603
+ * `max` steps (waiting for a running sweep to end first) and check again. Null = carry on;
604
+ * else why the worktree must not be made.
461
605
  */
462
606
  export async function ensureDiskSpace(opts: {
463
607
  cwd: string;
464
608
  minFreeGb: number;
465
609
  log: (m: string) => void;
610
+ /** How often to try the sweep lock again while another sweep runs; tests shorten it. */
611
+ pollMs?: number;
612
+ /** Longest wait for a running sweep; default `TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S`. */
613
+ maxWaitMs?: number;
466
614
  }): Promise<string | null> {
467
- if (isCloudOrCi() || stepFilePaths(opts.cwd).length === 0) return null;
615
+ const files = isCloudOrCi() ? [] : stepFilePaths(opts.cwd);
616
+ if (files.length === 0) return null;
468
617
  const min = opts.minFreeGb * GB;
469
618
  const before = freeBytes(opts.cwd);
470
619
  if (before === null || before >= min) return null;
471
620
  opts.log(
472
621
  `${gb(before)} free, under ${SETTING} (${opts.minFreeGb} GB) — running your max cleanup steps`,
473
622
  );
474
- touch("low", "max", "min");
475
- const ran = await sweep({ cwd: opts.cwd, mode: "max", dryRun: false, log: opts.log });
623
+ for (const f of files) touch(stampKey(f), "low", "max", "min");
624
+ const ran = await sweep({
625
+ cwd: opts.cwd,
626
+ mode: "max",
627
+ dryRun: false,
628
+ wait: true,
629
+ pollMs: opts.pollMs,
630
+ maxWaitMs: opts.maxWaitMs ?? TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S * 1000,
631
+ log: opts.log,
632
+ });
476
633
  const after = freeBytes(opts.cwd);
477
634
  if (after === null || after >= min) return null;
478
635
  opts.log("what your max steps still cover:");
479
636
  await sweep({ cwd: opts.cwd, mode: "max", dryRun: true, log: opts.log });
480
637
  const locked =
481
- ran.reason === "locked" ? " (another sweep was running — re-run once it ends)" : "";
638
+ ran.reason === "locked" ? " (another sweep still holds the lock — re-run once it ends)" : "";
482
639
  return `${gb(after)} free after your max cleanup steps, still under ${SETTING} (${opts.minFreeGb} GB)${locked} — free space by hand or add steps (.bkit/templates.md § Disk prune), then re-run`;
483
640
  }
484
641
 
@@ -492,6 +649,7 @@ export const diskCommand: CommandSpec = {
492
649
  verbs: {
493
650
  prune: {
494
651
  summary: `Run the min or max steps from ${REPO_STEPS} and ~/.config/bkit/disk-prune.mjs.`,
652
+ use: "by-hand",
495
653
  flags: [
496
654
  {
497
655
  name: "mode",
@@ -504,10 +662,20 @@ export const diskCommand: CommandSpec = {
504
662
  type: "boolean",
505
663
  help: "run nothing; list each step with the size of its paths",
506
664
  },
665
+ {
666
+ name: "scope",
667
+ type: "string",
668
+ help: "repo or machine: run only that file's steps (default: both)",
669
+ },
670
+ {
671
+ name: "wait",
672
+ type: "boolean",
673
+ help: "while another sweep runs, wait for it to end instead of stopping (the sweep --auto starts always waits)",
674
+ },
507
675
  {
508
676
  name: "auto",
509
677
  type: "boolean",
510
- help: `for hooks: run detached, at most once a day per mode; max at most hourly while free disk is under ${SETTING}`,
678
+ help: `for hooks: run detached, at most once a day per mode (machine steps once per machine, repo steps once per checkout); max at most hourly while free disk is under ${SETTING}`,
511
679
  },
512
680
  ],
513
681
  output: {
@@ -525,8 +693,15 @@ export const diskCommand: CommandSpec = {
525
693
  const mode = String(ctx.flags.mode);
526
694
  if (!MODES.includes(mode)) throw new CommandError(EXIT.USAGE, "--mode must be min or max");
527
695
  const dryRun = ctx.flags.dryRun === true;
696
+ const scope = ctx.flags.scope === undefined ? undefined : String(ctx.flags.scope);
697
+ if (scope !== undefined && !SCOPES.includes(scope))
698
+ throw new CommandError(EXIT.USAGE, "--scope must be repo or machine");
699
+ const scopes = scope === undefined ? undefined : [scope as Scope];
528
700
  if (ctx.flags.auto === true) {
529
701
  if (dryRun) throw new CommandError(EXIT.USAGE, "give --auto or --dry-run, not both");
702
+ if (scopes) throw new CommandError(EXIT.USAGE, "give --auto or --scope, not both");
703
+ if (ctx.flags.wait === true)
704
+ throw new CommandError(EXIT.USAGE, "give --auto or --wait, not both");
530
705
  const plan = schedule({
531
706
  cwd: ctx.cwd,
532
707
  mode: mode as Mode,
@@ -545,7 +720,14 @@ export const diskCommand: CommandSpec = {
545
720
  });
546
721
  return EXIT.OK;
547
722
  }
548
- const r = await sweep({ cwd: ctx.cwd, mode: mode as Mode, dryRun, log: ctx.log });
723
+ const r = await sweep({
724
+ cwd: ctx.cwd,
725
+ mode: mode as Mode,
726
+ dryRun,
727
+ scopes,
728
+ wait: ctx.flags.wait === true,
729
+ log: ctx.log,
730
+ });
549
731
  ctx.emit({ mode, started: null, ...r });
550
732
  const failed =
551
733
  r.files.some((f) => f.error !== null) || r.steps.some((s) => s.outcome === "failed");
@@ -472,6 +472,15 @@ export function parentDesignLink(text: string): { fid: string; month: string } |
472
472
  return m ? { month: m[1]!, fid: m[2]! } : null;
473
473
  }
474
474
 
475
+ /** The `WS-{N}` ids on the first `**Workstreams:**` line in the texts; [] when none. */
476
+ export function workstreamIds(...texts: string[]): string[] {
477
+ for (const text of texts) {
478
+ const line = /\*\*Workstreams:\*\*([^\n]*)/.exec(text)?.[1];
479
+ if (line !== undefined) return [...new Set(line.match(/WS-\d+/g) ?? [])];
480
+ }
481
+ return [];
482
+ }
483
+
475
484
  /** Every `docs/audits/{YYYYMM}/*.md` path in the texts, first mention order, unique. */
476
485
  export function auditPaths(...texts: string[]): string[] {
477
486
  const seen = new Set<string>();
@@ -674,6 +683,7 @@ export const fidsCommand: CommandSpec = {
674
683
  verbs: {
675
684
  check: {
676
685
  summary: "Validate a FID for the tracker: exit 0 valid, exit 1 not.",
686
+ use: "by-hand",
677
687
  flags: [
678
688
  { name: "fid", type: "string", required: true, help: "feature id to check" },
679
689
  { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = any tracker's shape (CI_DEV)` },
@@ -711,6 +721,7 @@ export const fidsCommand: CommandSpec = {
711
721
  parse: {
712
722
  summary:
713
723
  "--prompt-file: the issue and the FID a session prompt names. --marker / --branch: recover FID and issue id, the PR-body marker first, then a feat/{FID} branch (any slug; its issue id counts only when .bkit/issues.jsonl has a feature row for it, else the run is issue-less).",
724
+ use: "by-hand",
714
725
  flags: [
715
726
  {
716
727
  name: "prompt-file",
@@ -820,6 +831,7 @@ export const fidsCommand: CommandSpec = {
820
831
  resolve: {
821
832
  summary:
822
833
  "The run's FID, first hit wins: a FID the prompt names, the feat/{FID} branch, a FID logged for the issue on dev, a mint from the title (or prompt), a free -b, -c, ... suffix when a finished run used the mint; then the format check (exit 0 resolved, exit 1 fails the check).",
834
+ use: "workflow",
823
835
  flags: [
824
836
  {
825
837
  name: "prompt-file",
@@ -934,6 +946,7 @@ export const fidsCommand: CommandSpec = {
934
946
  },
935
947
  plans: {
936
948
  summary: "A feature's plan in a month bucket: docs/plans/{YYYYMM}/{FID}-plan.md, or none.",
949
+ use: "by-hand",
937
950
  flags: [
938
951
  { name: "fid", type: "string", required: true, help: "feature id" },
939
952
  { name: "month", type: "string", required: true, help: "YYYYMM bucket" },
@@ -950,7 +963,8 @@ export const fidsCommand: CommandSpec = {
950
963
  },
951
964
  design: {
952
965
  summary:
953
- "The plan's parent design: the **Parent design:** link in the description or prompt, else the feature's own docs/plans/{YYYYMM}/{FID}-design.md; plus the audit reports they name (exit 0 a parent, exit 1 none).",
966
+ "The plan's parent design: the **Parent design:** link in the description or prompt, else the feature's own docs/plans/{YYYYMM}/{FID}-design.md; plus the audit reports and the **Workstreams:** ids they name (exit 0 a parent, exit 1 none).",
967
+ use: "by-hand",
954
968
  flags: [
955
969
  { name: "fid", type: "string", required: true, help: "feature id" },
956
970
  {
@@ -979,6 +993,8 @@ export const fidsCommand: CommandSpec = {
979
993
  parentSource: "link | fid | null",
980
994
  auditPaths:
981
995
  "every docs/audits/{YYYYMM}/*.md path the description, then the prompt, names, first mention order",
996
+ workstreams:
997
+ "the WS-{N} ids the first **Workstreams:** line (description, then prompt) names: the plan covers only those; [] = the whole design",
982
998
  },
983
999
  exitCodes: {
984
1000
  [EXIT_NO_FILE]:
@@ -1024,12 +1040,14 @@ export const fidsCommand: CommandSpec = {
1024
1040
  parentPath: parent?.path ?? null,
1025
1041
  parentSource: parent?.source ?? null,
1026
1042
  auditPaths: audits,
1043
+ workstreams: workstreamIds(...texts),
1027
1044
  });
1028
1045
  return parent ? EXIT.OK : EXIT.NO;
1029
1046
  },
1030
1047
  },
1031
1048
  find: {
1032
1049
  summary: "The feature already logged for an issue: exit 0 one, exit 1 none, exit 4 several.",
1050
+ use: "by-hand",
1033
1051
  flags: [
1034
1052
  {
1035
1053
  name: "issue",
@@ -818,6 +818,7 @@ export const issuesCommand: CommandSpec = {
818
818
  verbs: {
819
819
  text: {
820
820
  summary: "ISSUE_TEXT: description + human comments, after the bkit:ignore-earlier cut.",
821
+ use: "workflow",
821
822
  flags: [
822
823
  { name: "description-file", type: "string", help: "file holding the issue description" },
823
824
  {
@@ -838,6 +839,7 @@ export const issuesCommand: CommandSpec = {
838
839
  fetch: {
839
840
  summary:
840
841
  "Read the run's issue into issue-description.md, issue-comments.json and issue-facts.json; prints the facts, never the body.",
842
+ use: "by-hand",
841
843
  flags: [
842
844
  { name: "fid", type: "string", help: "the run's FID (names the issue)" },
843
845
  { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
@@ -865,6 +867,7 @@ export const issuesCommand: CommandSpec = {
865
867
  related: {
866
868
  summary:
867
869
  "Fetch each hit of the orchestrator's related-issue search and write the related-issues file.",
870
+ use: "workflow",
868
871
  flags: [
869
872
  {
870
873
  name: "hits-file",
@@ -892,6 +895,7 @@ export const issuesCommand: CommandSpec = {
892
895
  },
893
896
  "blocked-by": {
894
897
  summary: "The issues blocking the run's issue, with their states and the ones still open.",
898
+ use: "by-hand",
895
899
  flags: [
896
900
  { name: "fid", type: "string", help: "the run's FID (names the issue)" },
897
901
  { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
@@ -909,6 +913,7 @@ export const issuesCommand: CommandSpec = {
909
913
  },
910
914
  labels: {
911
915
  summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
916
+ use: "workflow",
912
917
  flags: [
913
918
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
914
919
  {
@@ -956,6 +961,7 @@ export const issuesCommand: CommandSpec = {
956
961
  comment: {
957
962
  summary:
958
963
  "The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
964
+ use: "workflow",
959
965
  flags: [
960
966
  { name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
961
967
  { name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },