@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,16 +7,21 @@
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
  import { spawn, spawnSync } from "node:child_process";
24
+ import { createHash } from "node:crypto";
20
25
  import * as fs from "node:fs";
21
26
  import * as os from "node:os";
22
27
  import * as path from "node:path";
@@ -24,6 +29,7 @@ import { pathToFileURL } from "node:url";
24
29
  import { isCloudOrCi } from "../../checks/before/env.js";
25
30
  import { readJsonFile } from "../../shared/json.js";
26
31
  import { readBkitConfig } from "../../shared/settings.js";
32
+ import { TIMEOUTS } from "../../shared/timeouts.js";
27
33
  import { CommandError, EXIT, git } from "../lib.js";
28
34
  import { tryCreate } from "./locks.js";
29
35
  const MODES = ["min", "max"];
@@ -34,27 +40,41 @@ const HOUR_MS = 60 * 60 * 1000;
34
40
  const DAY_MS = 24 * HOUR_MS;
35
41
  /** A lock this old, or whose process is gone, belongs to a sweep that died. */
36
42
  const LOCK_STALE_MS = HOUR_MS;
43
+ /** How often a running sweep renews its lock, so a long sweep is never taken for a dead one. */
44
+ const LOCK_RENEW_MS = 10 * 60 * 1000;
45
+ /** How often a waiting sweep tries the lock again. */
46
+ const LOCK_POLL_MS = 5_000;
37
47
  const GB = 1e9;
38
48
  const configDir = () => path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), "bkit");
39
49
  const cacheDir = () => path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "bkit");
40
50
  export const machineStepsPath = () => path.join(configDir(), "disk-prune.mjs");
41
51
  export const sweepLogPath = () => path.join(cacheDir(), "disk-prune.log");
42
52
  const lockPath = () => path.join(cacheDir(), "disk-prune.lock");
43
- const stampPath = (name) => path.join(cacheDir(), `disk-prune-${name}.stamp`);
53
+ /** One stamp per limit: the machine file's under `machine`, a checkout's repo file's under its top. */
54
+ const stampPath = (key, name) => path.join(cacheDir(), key === MACHINE
55
+ ? `disk-prune-${name}.stamp`
56
+ : `disk-prune-${name}-${createHash("sha256").update(key).digest("hex").slice(0, 12)}.stamp`);
57
+ /** A checkout's stamps this old belong to a checkout no hook has run in since (a removed worktree). */
58
+ const STAMP_STALE_MS = 7 * DAY_MS;
59
+ const REPO_STAMP = /^disk-prune-[a-z]+-[0-9a-f]{12}\.stamp$/;
44
60
  const notesPath = () => path.join(cacheDir(), "disk-prune-notes.json");
45
61
  /** Notes older than this are dropped: no sweep has run there since. */
46
62
  const NOTES_STALE_MS = 7 * DAY_MS;
63
+ const MACHINE = "machine";
47
64
  const gb = (bytes) => (bytes === null ? "?" : `${(bytes / GB).toFixed(1)} GB`);
48
65
  const errorText = (err) => (err instanceof Error ? err.message : String(err));
66
+ const SCOPES = ["repo", "machine"];
49
67
  const checkoutTop = (cwd) => git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
50
- /** The step files that exist for `cwd`, repo first. */
51
- function stepFilePaths(cwd) {
68
+ /** The step files that exist for `cwd`, repo first; only `scopes`' files when given. */
69
+ function stepFilePaths(cwd, scopes) {
52
70
  const top = checkoutTop(cwd);
53
71
  return [
54
72
  { scope: "repo", file: path.join(top, REPO_STEPS), cwd: top },
55
73
  { scope: "machine", file: machineStepsPath(), cwd: os.homedir() },
56
- ].filter((f) => fs.existsSync(f.file));
74
+ ].filter((f) => (scopes === undefined || scopes.includes(f.scope)) && fs.existsSync(f.file));
57
75
  }
76
+ /** Whose limits a step file counts against: the machine's, or its checkout's. */
77
+ const stampKey = (f) => (f.scope === "machine" ? MACHINE : f.cwd);
58
78
  const isAction = (v) => typeof v === "string" || typeof v === "function";
59
79
  function stepProblem(step) {
60
80
  if (step === null || typeof step !== "object")
@@ -121,14 +141,23 @@ function sizeOf(patterns, cwd) {
121
141
  .split("\n")
122
142
  .reduce((sum, line) => sum + Number(line.split(/\s/)[0] ?? 0) * 1024, 0);
123
143
  }
124
- function due(name, everyMs, now) {
125
- const st = fs.statSync(stampPath(name), { throwIfNoEntry: false });
144
+ function due(key, name, everyMs, now) {
145
+ const st = fs.statSync(stampPath(key, name), { throwIfNoEntry: false });
126
146
  return st === undefined || now - st.mtimeMs >= everyMs;
127
147
  }
128
- function touch(...names) {
148
+ /** Stamp `names` for `key`, and drop checkout stamps no hook has renewed in 7 days. */
149
+ function touch(key, ...names) {
129
150
  fs.mkdirSync(cacheDir(), { recursive: true });
130
151
  for (const name of names)
131
- fs.writeFileSync(stampPath(name), `${new Date().toISOString()}\n`);
152
+ fs.writeFileSync(stampPath(key, name), `${new Date().toISOString()}\n`);
153
+ for (const entry of fs.readdirSync(cacheDir())) {
154
+ if (!REPO_STAMP.test(entry))
155
+ continue;
156
+ const file = path.join(cacheDir(), entry);
157
+ const st = fs.statSync(file, { throwIfNoEntry: false });
158
+ if (st !== undefined && Date.now() - st.mtimeMs >= STAMP_STALE_MS)
159
+ fs.rmSync(file, { force: true });
160
+ }
132
161
  }
133
162
  function pidAlive(pid) {
134
163
  try {
@@ -139,40 +168,117 @@ function pidAlive(pid) {
139
168
  return err.code === "EPERM";
140
169
  }
141
170
  }
142
- /** Take the sweep lock; a dead or hour-old holder's lock is replaced. False when held. */
171
+ /**
172
+ * Take the sweep lock; a lock whose holder is gone, or that no holder renewed for an hour, is
173
+ * replaced. False when held. The stale lock is renamed aside before it is removed, so a lock
174
+ * another sweep took after this one's check is put back, never deleted.
175
+ */
143
176
  function takeLock() {
144
177
  const file = lockPath();
145
178
  const line = `${new Date().toISOString()} ${process.pid}`;
146
179
  if (tryCreate(file, line))
147
180
  return true;
148
181
  const st = fs.statSync(file, { throwIfNoEntry: false });
149
- const holder = st === undefined ? "" : fs.readFileSync(file, "utf-8");
182
+ if (st === undefined)
183
+ return tryCreate(file, line);
184
+ const holder = fs.readFileSync(file, "utf-8");
150
185
  const pid = Number(holder.split(/\s+/)[1]);
151
- const live = st !== undefined && Date.now() - st.mtimeMs < LOCK_STALE_MS;
186
+ const live = Date.now() - st.mtimeMs < LOCK_STALE_MS;
152
187
  if (live && Number.isInteger(pid) && pid > 0 && pidAlive(pid))
153
188
  return false;
154
- fs.rmSync(file, { force: true });
189
+ const aside = `${file}.${process.pid}.${Date.now()}.stale`;
190
+ try {
191
+ fs.renameSync(file, aside);
192
+ }
193
+ catch (err) {
194
+ if (err.code !== "ENOENT")
195
+ throw err;
196
+ return tryCreate(file, line);
197
+ }
198
+ const taken = fs.readFileSync(aside, "utf-8");
199
+ if (taken !== holder) {
200
+ restoreLock(aside, file);
201
+ return false;
202
+ }
203
+ fs.rmSync(aside, { force: true });
155
204
  return tryCreate(file, line);
156
205
  }
206
+ /** Put a lock renamed aside back at `file`, unless a third sweep has taken `file` since. */
207
+ function restoreLock(aside, file) {
208
+ try {
209
+ fs.linkSync(aside, file);
210
+ }
211
+ catch (err) {
212
+ if (err.code !== "EEXIST")
213
+ throw err;
214
+ }
215
+ fs.rmSync(aside, { force: true });
216
+ }
217
+ /**
218
+ * Take the sweep lock, waiting while another sweep holds it. False only when it is still held
219
+ * after `maxWaitMs` (default `LOCK_STALE_MS`): a sweep that long renews its lock, so `takeLock`
220
+ * never replaces it.
221
+ */
222
+ async function waitForLock(pollMs, log, maxWaitMs = LOCK_STALE_MS + pollMs) {
223
+ if (takeLock())
224
+ return true;
225
+ log(`another sweep is running (${lockPath()}) — waiting for it to end`);
226
+ const deadline = Date.now() + maxWaitMs;
227
+ while (Date.now() < deadline) {
228
+ await new Promise((resolve) => setTimeout(resolve, pollMs));
229
+ if (takeLock())
230
+ return true;
231
+ }
232
+ return false;
233
+ }
234
+ const holdsLock = (file) => fs.existsSync(file) && fs.readFileSync(file, "utf-8").split(/\s+/)[1] === String(process.pid);
235
+ /** Mark this sweep's lock as live; another process's lock is left alone. */
236
+ function renewLock() {
237
+ const file = lockPath();
238
+ const now = new Date();
239
+ if (holdsLock(file))
240
+ fs.utimesSync(file, now, now);
241
+ }
157
242
  function releaseLock() {
158
243
  const file = lockPath();
159
- const pid = fs.existsSync(file) ? fs.readFileSync(file, "utf-8").split(/\s+/)[1] : undefined;
160
- if (pid === String(process.pid))
244
+ if (holdsLock(file))
161
245
  fs.rmSync(file, { force: true });
162
246
  }
247
+ /**
248
+ * Run a step's shell command and log its last 20 output lines. Spawned, not run in step: the
249
+ * lock renewal timer has to fire while a long command runs.
250
+ */
163
251
  function shell(command, cwd, log) {
164
- const r = spawnSync("sh", ["-c", command], { cwd, encoding: "utf-8", maxBuffer: 1 << 26 });
165
- const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
166
- if (out !== "")
167
- for (const line of out.split("\n").slice(-20))
168
- log(` ${line}`);
169
- return r.error ? 127 : (r.status ?? 1);
252
+ return new Promise((resolve) => {
253
+ const child = spawn("sh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
254
+ let out = "";
255
+ const keep = (chunk) => {
256
+ out = `${out}${chunk.toString()}`.slice(-(1 << 16));
257
+ };
258
+ child.stdout.on("data", keep);
259
+ child.stderr.on("data", keep);
260
+ let settled = false;
261
+ const finish = (status) => {
262
+ if (settled)
263
+ return;
264
+ settled = true;
265
+ const text = out.trim();
266
+ if (text !== "")
267
+ for (const line of text.split("\n").slice(-20))
268
+ log(` ${line}`);
269
+ resolve(status);
270
+ };
271
+ child.on("error", () => finish(127));
272
+ child.on("close", (status) => finish(status ?? 1));
273
+ });
170
274
  }
171
275
  async function skipReason(step, ctx) {
172
276
  if (step.skip === undefined)
173
277
  return null;
174
278
  if (typeof step.skip === "string") {
175
- return shell(step.skip, ctx.cwd, ctx.log) === 0 ? `skip check passed: ${step.skip}` : null;
279
+ return (await shell(step.skip, ctx.cwd, ctx.log)) === 0
280
+ ? `skip check passed: ${step.skip}`
281
+ : null;
176
282
  }
177
283
  const answer = await step.skip(ctx);
178
284
  if (!answer)
@@ -185,7 +291,7 @@ async function runStep(step, ctx) {
185
291
  if (reason !== null)
186
292
  return { outcome: "skipped", detail: reason };
187
293
  if (typeof step.run === "string") {
188
- const status = shell(step.run, ctx.cwd, ctx.log);
294
+ const status = await shell(step.run, ctx.cwd, ctx.log);
189
295
  if (status !== 0)
190
296
  return { outcome: "failed", detail: `exit ${status}` };
191
297
  }
@@ -199,8 +305,9 @@ async function runStep(step, ctx) {
199
305
  }
200
306
  }
201
307
  /**
202
- * Run the `mode` steps from every step file for `cwd`, one at a time, repo file first.
203
- * `dryRun` runs nothing and sizes each step's paths instead.
308
+ * Run the `mode` steps from every step file for `cwd` (only `scopes`' files when given), one
309
+ * at a time, repo file first. `dryRun` runs nothing and sizes each step's paths instead.
310
+ * While another sweep runs, `wait` waits for it to end; without it the sweep stops.
204
311
  */
205
312
  export async function sweep(opts) {
206
313
  const result = {
@@ -213,7 +320,7 @@ export async function sweep(opts) {
213
320
  };
214
321
  if (isCloudOrCi())
215
322
  return { ...result, reason: "ci" };
216
- const files = await Promise.all(stepFilePaths(opts.cwd).map(loadStepFile));
323
+ const files = await Promise.all(stepFilePaths(opts.cwd, opts.scopes).map(loadStepFile));
217
324
  result.files = files.map((f) => ({
218
325
  scope: f.scope,
219
326
  file: f.file,
@@ -243,10 +350,15 @@ export async function sweep(opts) {
243
350
  }
244
351
  return result;
245
352
  }
246
- if (!takeLock()) {
353
+ const locked = opts.wait
354
+ ? !(await waitForLock(opts.pollMs ?? LOCK_POLL_MS, opts.log, opts.maxWaitMs))
355
+ : !takeLock();
356
+ if (locked) {
247
357
  opts.log(`another sweep is running (${lockPath()})`);
248
358
  return { ...result, reason: "locked" };
249
359
  }
360
+ const renewal = setInterval(renewLock, opts.renewMs ?? LOCK_RENEW_MS);
361
+ renewal.unref();
250
362
  try {
251
363
  result.freeBefore = freeBytes(opts.cwd);
252
364
  opts.log(`${new Date().toISOString()} ${opts.mode} sweep, ${gb(result.freeBefore)} free`);
@@ -264,6 +376,7 @@ export async function sweep(opts) {
264
376
  saveNotes(checkoutTop(opts.cwd), result.notes);
265
377
  }
266
378
  finally {
379
+ clearInterval(renewal);
267
380
  releaseLock();
268
381
  }
269
382
  return result;
@@ -324,59 +437,78 @@ export function formatNotes(notes) {
324
437
  // ---------------------------------------------------------------------------
325
438
  // Scheduling (hooks) and the worktree check
326
439
  // ---------------------------------------------------------------------------
327
- /** Start `bkit disk prune --mode=<mode>` detached, its output appended to the sweep log. */
328
- function spawnDetached(mode, cwd) {
440
+ /**
441
+ * The `bkit` arguments of the sweep `--auto` starts: the due `scopes` only, and waiting for
442
+ * a running sweep to end, so a hook that fires mid-sweep still gets its turn.
443
+ */
444
+ export function detachedArgs(mode, scopes) {
445
+ const only = scopes.length === 1 ? [`--scope=${scopes[0]}`] : [];
446
+ return ["disk", "prune", `--mode=${mode}`, ...only, "--wait"];
447
+ }
448
+ /** Start the `--auto` sweep detached, its output appended to the sweep log. */
449
+ function spawnDetached(mode, cwd, scopes) {
329
450
  fs.mkdirSync(cacheDir(), { recursive: true });
330
451
  const fd = fs.openSync(sweepLogPath(), "a");
331
- const child = spawn(process.execPath, [...process.execArgv, process.argv[1], "disk", "prune", `--mode=${mode}`], { cwd, detached: true, stdio: ["ignore", fd, fd] });
452
+ const child = spawn(process.execPath, [...process.execArgv, process.argv[1], ...detachedArgs(mode, scopes)], { cwd, detached: true, stdio: ["ignore", fd, fd] });
332
453
  child.unref();
333
454
  fs.closeSync(fd);
334
455
  }
335
456
  /**
336
- * `--auto`: start a detached sweep when one is due. Under `minFreeGb` free → `max`, at
337
- * most hourly; else `mode`, at most daily. A `max` run also counts as that day's `min`.
457
+ * `--auto`: start a detached sweep of the step files that are due. Under `minFreeGb` free →
458
+ * `max`, at most hourly; else `mode`, at most daily. A `max` run also counts as that day's
459
+ * `min`. The machine file is due by the machine's stamps, the repo file by its checkout's.
338
460
  */
339
461
  export function schedule(opts) {
340
462
  if (isCloudOrCi())
341
463
  return { started: null, reason: "ci" };
342
- if (stepFilePaths(opts.cwd).length === 0)
464
+ const files = stepFilePaths(opts.cwd);
465
+ if (files.length === 0)
343
466
  return { started: null, reason: "no-steps" };
344
467
  const now = opts.now ?? Date.now();
345
468
  const start = opts.start ?? spawnDetached;
346
469
  const free = freeBytes(opts.cwd);
347
- if (free !== null && free < opts.minFreeGb * GB) {
348
- if (!due("low", HOUR_MS, now))
349
- return { started: null, reason: "not-due" };
350
- touch("low", "max", "min");
351
- start("max", opts.cwd);
352
- return { started: "max", reason: "low-disk" };
353
- }
354
- if (!due(opts.mode, DAY_MS, now))
470
+ const low = free !== null && free < opts.minFreeGb * GB;
471
+ const mode = low ? "max" : opts.mode;
472
+ const dueFiles = files.filter((f) => low ? due(stampKey(f), "low", HOUR_MS, now) : due(stampKey(f), mode, DAY_MS, now));
473
+ if (dueFiles.length === 0)
355
474
  return { started: null, reason: "not-due" };
356
- touch(...(opts.mode === "max" ? ["max", "min"] : ["min"]));
357
- start(opts.mode, opts.cwd);
358
- return { started: opts.mode, reason: "due" };
475
+ const names = low ? ["low", "max", "min"] : mode === "max" ? ["max", "min"] : ["min"];
476
+ for (const f of dueFiles)
477
+ touch(stampKey(f), ...names);
478
+ start(mode, opts.cwd, dueFiles.map((f) => f.scope));
479
+ return { started: mode, reason: low ? "low-disk" : "due" };
359
480
  }
360
481
  /**
361
482
  * Before worktree setup mints: under `minFreeGb` free with step files present, run the
362
- * `max` steps and check again. Null = carry on; else why the worktree must not be made.
483
+ * `max` steps (waiting for a running sweep to end first) and check again. Null = carry on;
484
+ * else why the worktree must not be made.
363
485
  */
364
486
  export async function ensureDiskSpace(opts) {
365
- if (isCloudOrCi() || stepFilePaths(opts.cwd).length === 0)
487
+ const files = isCloudOrCi() ? [] : stepFilePaths(opts.cwd);
488
+ if (files.length === 0)
366
489
  return null;
367
490
  const min = opts.minFreeGb * GB;
368
491
  const before = freeBytes(opts.cwd);
369
492
  if (before === null || before >= min)
370
493
  return null;
371
494
  opts.log(`${gb(before)} free, under ${SETTING} (${opts.minFreeGb} GB) — running your max cleanup steps`);
372
- touch("low", "max", "min");
373
- const ran = await sweep({ cwd: opts.cwd, mode: "max", dryRun: false, log: opts.log });
495
+ for (const f of files)
496
+ touch(stampKey(f), "low", "max", "min");
497
+ const ran = await sweep({
498
+ cwd: opts.cwd,
499
+ mode: "max",
500
+ dryRun: false,
501
+ wait: true,
502
+ pollMs: opts.pollMs,
503
+ maxWaitMs: opts.maxWaitMs ?? TIMEOUTS.DISK_SETUP_SWEEP_WAIT_S * 1000,
504
+ log: opts.log,
505
+ });
374
506
  const after = freeBytes(opts.cwd);
375
507
  if (after === null || after >= min)
376
508
  return null;
377
509
  opts.log("what your max steps still cover:");
378
510
  await sweep({ cwd: opts.cwd, mode: "max", dryRun: true, log: opts.log });
379
- const locked = ran.reason === "locked" ? " (another sweep was running — re-run once it ends)" : "";
511
+ const locked = ran.reason === "locked" ? " (another sweep still holds the lock — re-run once it ends)" : "";
380
512
  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`;
381
513
  }
382
514
  // ---------------------------------------------------------------------------
@@ -388,6 +520,7 @@ export const diskCommand = {
388
520
  verbs: {
389
521
  prune: {
390
522
  summary: `Run the min or max steps from ${REPO_STEPS} and ~/.config/bkit/disk-prune.mjs.`,
523
+ use: "by-hand",
391
524
  flags: [
392
525
  {
393
526
  name: "mode",
@@ -400,10 +533,20 @@ export const diskCommand = {
400
533
  type: "boolean",
401
534
  help: "run nothing; list each step with the size of its paths",
402
535
  },
536
+ {
537
+ name: "scope",
538
+ type: "string",
539
+ help: "repo or machine: run only that file's steps (default: both)",
540
+ },
541
+ {
542
+ name: "wait",
543
+ type: "boolean",
544
+ help: "while another sweep runs, wait for it to end instead of stopping (the sweep --auto starts always waits)",
545
+ },
403
546
  {
404
547
  name: "auto",
405
548
  type: "boolean",
406
- help: `for hooks: run detached, at most once a day per mode; max at most hourly while free disk is under ${SETTING}`,
549
+ 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}`,
407
550
  },
408
551
  ],
409
552
  output: {
@@ -421,9 +564,17 @@ export const diskCommand = {
421
564
  if (!MODES.includes(mode))
422
565
  throw new CommandError(EXIT.USAGE, "--mode must be min or max");
423
566
  const dryRun = ctx.flags.dryRun === true;
567
+ const scope = ctx.flags.scope === undefined ? undefined : String(ctx.flags.scope);
568
+ if (scope !== undefined && !SCOPES.includes(scope))
569
+ throw new CommandError(EXIT.USAGE, "--scope must be repo or machine");
570
+ const scopes = scope === undefined ? undefined : [scope];
424
571
  if (ctx.flags.auto === true) {
425
572
  if (dryRun)
426
573
  throw new CommandError(EXIT.USAGE, "give --auto or --dry-run, not both");
574
+ if (scopes)
575
+ throw new CommandError(EXIT.USAGE, "give --auto or --scope, not both");
576
+ if (ctx.flags.wait === true)
577
+ throw new CommandError(EXIT.USAGE, "give --auto or --wait, not both");
427
578
  const plan = schedule({
428
579
  cwd: ctx.cwd,
429
580
  mode: mode,
@@ -442,7 +593,14 @@ export const diskCommand = {
442
593
  });
443
594
  return EXIT.OK;
444
595
  }
445
- const r = await sweep({ cwd: ctx.cwd, mode: mode, dryRun, log: ctx.log });
596
+ const r = await sweep({
597
+ cwd: ctx.cwd,
598
+ mode: mode,
599
+ dryRun,
600
+ scopes,
601
+ wait: ctx.flags.wait === true,
602
+ log: ctx.log,
603
+ });
446
604
  ctx.emit({ mode, started: null, ...r });
447
605
  const failed = r.files.some((f) => f.error !== null) || r.steps.some((s) => s.outcome === "failed");
448
606
  return failed ? EXIT.NO : EXIT.OK;
@@ -393,6 +393,15 @@ export function parentDesignLink(text) {
393
393
  const m = /\*\*Parent design:\*\*[^\n]*?docs\/plans\/([0-9]{6})\/([a-z0-9][a-z0-9-]*)-design\.md/.exec(text);
394
394
  return m ? { month: m[1], fid: m[2] } : null;
395
395
  }
396
+ /** The `WS-{N}` ids on the first `**Workstreams:**` line in the texts; [] when none. */
397
+ export function workstreamIds(...texts) {
398
+ for (const text of texts) {
399
+ const line = /\*\*Workstreams:\*\*([^\n]*)/.exec(text)?.[1];
400
+ if (line !== undefined)
401
+ return [...new Set(line.match(/WS-\d+/g) ?? [])];
402
+ }
403
+ return [];
404
+ }
396
405
  /** Every `docs/audits/{YYYYMM}/*.md` path in the texts, first mention order, unique. */
397
406
  export function auditPaths(...texts) {
398
407
  const seen = new Set();
@@ -575,6 +584,7 @@ export const fidsCommand = {
575
584
  verbs: {
576
585
  check: {
577
586
  summary: "Validate a FID for the tracker: exit 0 valid, exit 1 not.",
587
+ use: "by-hand",
578
588
  flags: [
579
589
  { name: "fid", type: "string", required: true, help: "feature id to check" },
580
590
  { ...TRACKER_FLAG, help: `${TRACKER_FLAG.help}; any = any tracker's shape (CI_DEV)` },
@@ -612,6 +622,7 @@ export const fidsCommand = {
612
622
  },
613
623
  parse: {
614
624
  summary: "--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).",
625
+ use: "by-hand",
615
626
  flags: [
616
627
  {
617
628
  name: "prompt-file",
@@ -704,6 +715,7 @@ export const fidsCommand = {
704
715
  },
705
716
  resolve: {
706
717
  summary: "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).",
718
+ use: "workflow",
707
719
  flags: [
708
720
  {
709
721
  name: "prompt-file",
@@ -809,6 +821,7 @@ export const fidsCommand = {
809
821
  },
810
822
  plans: {
811
823
  summary: "A feature's plan in a month bucket: docs/plans/{YYYYMM}/{FID}-plan.md, or none.",
824
+ use: "by-hand",
812
825
  flags: [
813
826
  { name: "fid", type: "string", required: true, help: "feature id" },
814
827
  { name: "month", type: "string", required: true, help: "YYYYMM bucket" },
@@ -824,7 +837,8 @@ export const fidsCommand = {
824
837
  },
825
838
  },
826
839
  design: {
827
- summary: "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).",
840
+ summary: "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).",
841
+ use: "by-hand",
828
842
  flags: [
829
843
  { name: "fid", type: "string", required: true, help: "feature id" },
830
844
  {
@@ -852,6 +866,7 @@ export const fidsCommand = {
852
866
  parentPath: "its repo-relative path, else null",
853
867
  parentSource: "link | fid | null",
854
868
  auditPaths: "every docs/audits/{YYYYMM}/*.md path the description, then the prompt, names, first mention order",
869
+ workstreams: "the WS-{N} ids the first **Workstreams:** line (description, then prompt) names: the plan covers only those; [] = the whole design",
855
870
  },
856
871
  exitCodes: {
857
872
  [EXIT_NO_FILE]: "a --description-file / --prompt-file is missing, or a linked design or named audit path is not a file",
@@ -893,12 +908,14 @@ export const fidsCommand = {
893
908
  parentPath: parent?.path ?? null,
894
909
  parentSource: parent?.source ?? null,
895
910
  auditPaths: audits,
911
+ workstreams: workstreamIds(...texts),
896
912
  });
897
913
  return parent ? EXIT.OK : EXIT.NO;
898
914
  },
899
915
  },
900
916
  find: {
901
917
  summary: "The feature already logged for an issue: exit 0 one, exit 1 none, exit 4 several.",
918
+ use: "by-hand",
902
919
  flags: [
903
920
  {
904
921
  name: "issue",
@@ -673,6 +673,7 @@ export const issuesCommand = {
673
673
  verbs: {
674
674
  text: {
675
675
  summary: "ISSUE_TEXT: description + human comments, after the bkit:ignore-earlier cut.",
676
+ use: "workflow",
676
677
  flags: [
677
678
  { name: "description-file", type: "string", help: "file holding the issue description" },
678
679
  {
@@ -692,6 +693,7 @@ export const issuesCommand = {
692
693
  },
693
694
  fetch: {
694
695
  summary: "Read the run's issue into issue-description.md, issue-comments.json and issue-facts.json; prints the facts, never the body.",
696
+ use: "by-hand",
695
697
  flags: [
696
698
  { name: "fid", type: "string", help: "the run's FID (names the issue)" },
697
699
  { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
@@ -716,6 +718,7 @@ export const issuesCommand = {
716
718
  },
717
719
  related: {
718
720
  summary: "Fetch each hit of the orchestrator's related-issue search and write the related-issues file.",
721
+ use: "workflow",
719
722
  flags: [
720
723
  {
721
724
  name: "hits-file",
@@ -743,6 +746,7 @@ export const issuesCommand = {
743
746
  },
744
747
  "blocked-by": {
745
748
  summary: "The issues blocking the run's issue, with their states and the ones still open.",
749
+ use: "by-hand",
746
750
  flags: [
747
751
  { name: "fid", type: "string", help: "the run's FID (names the issue)" },
748
752
  { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
@@ -758,6 +762,7 @@ export const issuesCommand = {
758
762
  },
759
763
  labels: {
760
764
  summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
765
+ use: "workflow",
761
766
  flags: [
762
767
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
763
768
  {
@@ -800,6 +805,7 @@ export const issuesCommand = {
800
805
  },
801
806
  comment: {
802
807
  summary: "The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
808
+ use: "workflow",
803
809
  flags: [
804
810
  { name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
805
811
  { name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },