@cbartens/bkit 5.5.1 → 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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -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 +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  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 +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -12,7 +12,16 @@ import * as path from "node:path";
12
12
 
13
13
  import type { IssueTracker } from "../../install/manifest.js";
14
14
  import { readBkitConfig } from "../../shared/settings.js";
15
- import { appendLine, statusTimestamp, type StatusRow } from "../../ledgers/status.js";
15
+ import {
16
+ actionHash,
17
+ actionKey,
18
+ alreadyDone,
19
+ appendLine,
20
+ recordAction,
21
+ runNumber,
22
+ statusTimestamp,
23
+ type StatusRow,
24
+ } from "../../ledgers/status.js";
16
25
  import {
17
26
  bodySkipToken,
18
27
  CommandError,
@@ -21,6 +30,7 @@ import {
21
30
  ghUnavailable,
22
31
  git,
23
32
  isSharedBranch,
33
+ MAIN,
24
34
  parseJson,
25
35
  repoRoot,
26
36
  runGh,
@@ -32,8 +42,11 @@ import {
32
42
  type GhResult,
33
43
  type RunContext,
34
44
  } from "../lib.js";
45
+ import { fidProblem } from "./fids.js";
35
46
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX } from "./issues.js";
36
- import { EXIT_NO_STATUS, FILE_FLAG, readStatusRows, statusFile, str } from "./status.js";
47
+ import { resolveOwnerRepo } from "./repo.js";
48
+ import { writeBodyFile } from "./tracker.js";
49
+ import { EXIT_NO_STATUS, FILE_FLAG, readRuns, readStatusRows, statusFile, str } from "./status.js";
37
50
 
38
51
  // ---------------------------------------------------------------------------
39
52
  // gh
@@ -165,29 +178,18 @@ function refFlag(value: FlagValue, flag: string): string {
165
178
  // open
166
179
  // ---------------------------------------------------------------------------
167
180
 
168
- /** FID allowlists per tracker — the same ones `/bkit-auto` asserts when it reads the marker back. */
169
- const FID_FORMAT: Record<IssueTracker, RegExp> = {
170
- github: /^[0-9]+-[a-z0-9-]+$/,
171
- linear: /^[a-z]+-[0-9]+-[a-z0-9-]+$/,
172
- jira: /^[a-z][a-z0-9]+-[0-9]+-[a-z0-9-]+$/,
173
- none: /^[a-z0-9][a-z0-9-]*$/,
174
- };
175
- const ISSUE_FORMAT: Record<Exclude<IssueTracker, "none">, RegExp> = {
176
- github: /^[0-9]+$/,
177
- linear: /^[A-Z]+-[0-9]+$/,
178
- jira: /^[A-Z][A-Z0-9]+-[0-9]+$/,
179
- };
180
-
181
- /** The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). */
181
+ /**
182
+ * The PR-body marker line for this tracker (`.bkit/trackers.md` `pr-body-marker`). With
183
+ * no issue the marker is FID-only (`<!-- bkit:fid={FID} -->`, the `none` shape) and the
184
+ * FID any slug; with an issue, the FID must embed that same issue id.
185
+ */
182
186
  export function prMarker(tracker: IssueTracker, fid: string, issue: string | undefined): string {
183
- if (!FID_FORMAT[tracker].test(fid)) {
184
- throw new CommandError(EXIT.USAGE, `--fid "${fid}" is not a ${tracker} FID slug`);
185
- }
186
- if (tracker === "none") return `<!-- bkit:fid=${fid} -->`;
187
187
  const id = (issue ?? "").replace(/^#/, "");
188
- if (!ISSUE_FORMAT[tracker].test(id)) {
189
- throw new CommandError(EXIT.USAGE, `--issue "${issue ?? ""}" is not a ${tracker} issue id`);
188
+ const problem = fidProblem(fid, tracker, id);
189
+ if (problem !== undefined) {
190
+ throw new CommandError(EXIT.USAGE, `--fid "${fid}" / --issue "${issue ?? ""}": ${problem}`);
190
191
  }
192
+ if (tracker === "none" || id === "") return `<!-- bkit:fid=${fid} -->`;
191
193
  return tracker === "github"
192
194
  ? `<!-- bkit:issue=#${id} bkit:fid=${fid} -->`
193
195
  : `<!-- bkit:issue=${id} bkit:fid=${fid} -->`;
@@ -201,10 +203,16 @@ export function prBody(marker: string, notes: string[], plan: string | undefined
201
203
  .concat("\n");
202
204
  }
203
205
 
206
+ /** The CI marker `branches force-build` puts on the PR title; `prs merge` drops it from the squash subject. */
207
+ export const FORCE_BUILD = "[force build]";
208
+ const FORCE_BUILD_TAG = / ?(bkit )?\[force build\]/g;
209
+
204
210
  export const EXIT_PR_EXISTS = 3;
205
211
  export const EXIT_SKIP_CI_TITLE = 4;
206
212
  export const EXIT_GH_FAILED = 5;
207
213
  export const EXIT_WRONG_BASE = 6;
214
+ /** Exit code (open): `--base=main` — bkit never opens a PR into `main`. */
215
+ export const EXIT_BASE_MAIN = 7;
208
216
 
209
217
  export interface OpenInput {
210
218
  fid: string;
@@ -228,6 +236,8 @@ export interface OpenResult {
228
236
  head: string;
229
237
  title: string;
230
238
  body: string;
239
+ /** useMcp only: absolute path of a file holding `body` byte-for-byte. */
240
+ bodyFile?: string;
231
241
  } | null;
232
242
  }
233
243
 
@@ -246,6 +256,13 @@ export function openPrFor(cwd: string, o: OpenInput, log: (m: string) => void):
246
256
  }
247
257
 
248
258
  const base = refFlag(o.base ?? DEV, "base");
259
+ // `refs/heads/main`, `origin/main` and `heads/main` name the same branch for gh.
260
+ if (base.replace(/^(?:refs\/)?(?:heads\/|remotes\/)?(?:origin\/)?/, "") === MAIN) {
261
+ log(
262
+ `refusing to open a PR into ${MAIN}: bkit opens PRs into ${DEV} only, releases stay manual`,
263
+ );
264
+ return { code: EXIT_BASE_MAIN, out: null };
265
+ }
249
266
  const head = o.head === undefined ? currentBranch(cwd) : refFlag(o.head, "head");
250
267
  if (head === base || isSharedBranch(head)) {
251
268
  throw new CommandError(EXIT.USAGE, `refusing to open a PR from "${head}" into "${base}"`);
@@ -261,7 +278,17 @@ export function openPrFor(cwd: string, o: OpenInput, log: (m: string) => void):
261
278
  log(`${why} — create the PR through the GitHub MCP tool with this title and body`);
262
279
  return {
263
280
  code: EXIT.USE_MCP,
264
- out: { created: false, useMcp: true, number: null, url: null, base, head, title, body },
281
+ out: {
282
+ created: false,
283
+ useMcp: true,
284
+ number: null,
285
+ url: null,
286
+ base,
287
+ head,
288
+ title,
289
+ body,
290
+ bodyFile: writeBodyFile(cwd, "pr-body", body),
291
+ },
265
292
  };
266
293
  };
267
294
 
@@ -344,6 +371,25 @@ export function openPrFor(cwd: string, o: OpenInput, log: (m: string) => void):
344
371
  }
345
372
 
346
373
  function openPr(ctx: RunContext): number {
374
+ const fileFlag = str(ctx.flags.file);
375
+ const workflow = str(ctx.flags.workflow);
376
+ if (fileFlag !== undefined && workflow === undefined) {
377
+ throw new CommandError(EXIT.USAGE, "--file needs --workflow");
378
+ }
379
+ // A recorded open of this head into this base makes the PR now open on it this run's own.
380
+ let existing = str(ctx.flags.existing) as OpenInput["existing"];
381
+ let action: { file: string; key: string; hash: string } | undefined;
382
+ if (fileFlag !== undefined && workflow !== undefined) {
383
+ const file = path.resolve(ctx.cwd, fileFlag);
384
+ const head = str(ctx.flags.head) ?? currentBranch(ctx.cwd);
385
+ const run = fs.existsSync(file) ? runNumber(readRuns(file), workflow) : 1;
386
+ action = {
387
+ file,
388
+ key: actionKey(workflow, run, "pr-open"),
389
+ hash: actionHash(`${head}\n${str(ctx.flags.base) ?? DEV}`),
390
+ };
391
+ if (alreadyDone(action.file, action.key, action.hash)) existing = "reuse";
392
+ }
347
393
  const r = openPrFor(
348
394
  ctx.cwd,
349
395
  {
@@ -354,10 +400,18 @@ function openPr(ctx: RunContext): number {
354
400
  head: str(ctx.flags.head),
355
401
  plan: str(ctx.flags.plan),
356
402
  notes: (ctx.flags.note as string[] | undefined) ?? [],
357
- existing: str(ctx.flags.existing) as OpenInput["existing"],
403
+ existing,
358
404
  },
359
405
  ctx.log,
360
406
  );
407
+ if (action && r.code === EXIT.OK && r.out?.created === true) {
408
+ recordAction(action.file, {
409
+ action: "pr-open",
410
+ key: action.key,
411
+ hash: action.hash,
412
+ ref: r.out.url,
413
+ });
414
+ }
361
415
  if (r.out) ctx.emit(r.out);
362
416
  return r.code;
363
417
  }
@@ -368,6 +422,8 @@ function openPr(ctx: RunContext): number {
368
422
 
369
423
  /** Exit code (merge --expect-merged): the PR did not reach MERGED. */
370
424
  export const EXIT_NOT_MERGED = 7;
425
+ /** Exit code (merge): the PR's base is not `dev`, or could not be read — nothing merged. */
426
+ export const EXIT_BASE_NOT_DEV = 8;
371
427
 
372
428
  export interface MergeInput {
373
429
  number: string;
@@ -392,7 +448,9 @@ export interface MergeResult {
392
448
 
393
449
  /**
394
450
  * Squash-merge a PR with an explicit empty body (never the default concatenated
395
- * subjects), unless it is already MERGED, then read the state back. gh missing →
451
+ * subjects), unless it is already MERGED, then read the state back. A PR whose base
452
+ * (read by the same `pr view` that reads its state) is not `dev`, or is unreadable, is
453
+ * never merged (EXIT_BASE_NOT_DEV). gh missing →
396
454
  * EXIT.USE_MCP (merge through `merge_pull_request` with `subject`).
397
455
  */
398
456
  export function mergePr(cwd: string, o: MergeInput, log: (m: string) => void): MergeResult {
@@ -422,6 +480,12 @@ export function mergePr(cwd: string, o: MergeInput, log: (m: string) => void): M
422
480
  return result(EXIT_GH_FAILED, undefined, false);
423
481
  }
424
482
  if (before.pr?.state === "MERGED") return result(EXIT.OK, before.pr, true);
483
+ if (before.pr?.baseRefName !== DEV) {
484
+ log(
485
+ `refusing to merge PR ${o.number}: its base is ${before.pr?.baseRefName ?? "unknown"}, not ${DEV} — bkit merges into ${DEV} only, releases stay manual`,
486
+ );
487
+ return result(EXIT_BASE_NOT_DEV, before.pr, false);
488
+ }
425
489
  const args = ["pr", "merge", o.number, "--squash", "--subject", o.subject, "--body", ""];
426
490
  if (o.deleteBranch === true) args.push("--delete-branch");
427
491
  if (o.matchHead !== undefined) args.push("--match-head-commit", o.matchHead);
@@ -439,6 +503,14 @@ export function mergePr(cwd: string, o: MergeInput, log: (m: string) => void): M
439
503
  log(after.message);
440
504
  return result(EXIT_GH_FAILED, undefined, false);
441
505
  }
506
+ // A retarget between the base check and the merge is caught here, loudly.
507
+ if (after.pr?.state === "MERGED" && after.pr.baseRefName !== DEV) {
508
+ log(
509
+ `INTEGRITY FAILURE: PR ${o.number} merged into ${after.pr.baseRefName ?? "an unknown base"}, not ${DEV} — its base changed after the check; revert the merge`,
510
+ );
511
+ const r = result(EXIT_BASE_NOT_DEV, after.pr, false);
512
+ return { ...r, out: { ...r.out, verdict: "FAIL", failures: 1 } };
513
+ }
442
514
  return result(EXIT.OK, after.pr, false);
443
515
  }
444
516
 
@@ -451,17 +523,60 @@ export interface UpdateBranchResult {
451
523
  out: { number: string; updated: boolean } | null;
452
524
  }
453
525
 
526
+ /** Whether dev demands status checks (ruleset or branch protection): CI must then pass at the PR head. */
527
+ export function devRequiresChecks(gh: (args: string[]) => GhResult, repo: string): boolean {
528
+ const rules = gh(["api", `repos/${repo}/rules/branches/dev`]);
529
+ const read = rules.ok ? parseJson(rules.stdout) : { ok: false as const };
530
+ const list: unknown[] = read.ok && Array.isArray(read.value) ? read.value : [];
531
+ const hasCheckRule = list.some(
532
+ (r) =>
533
+ r !== null &&
534
+ typeof r === "object" &&
535
+ (r as { type?: unknown }).type === "required_status_checks",
536
+ );
537
+ if (hasCheckRule) return true;
538
+ return gh(["api", `repos/${repo}/branches/dev/protection/required_status_checks`]).ok;
539
+ }
540
+
454
541
  /**
455
- * Request a server-side base-into-head refresh (ship Step 4 B1). GitHub authors
456
- * the merge commit, so bkit cannot set its message and there is no local head to
457
- * read back — ship's Step 9 poll observes the new head. gh missing →
542
+ * Request a server-side base-into-head refresh. GitHub authors the merge commit,
543
+ * so bkit cannot set its message and there is no local head to read back. Ship
544
+ * does not call it: its Step 4 merges origin/dev locally (`branches sync --merge`). gh missing →
458
545
  * EXIT.USE_MCP (route through `update_pull_request_branch`).
546
+ *
547
+ * `onlyIfRequired`: refresh only when dev requires status checks. Otherwise the
548
+ * PR merges at the head CI already passed at, and the dev push run tests the
549
+ * merged result — a refresh would only re-run CI on the same feature change.
459
550
  */
460
551
  export function updateBranch(
461
552
  cwd: string,
462
553
  number: string,
463
554
  log: (m: string) => void,
555
+ o: { onlyIfRequired?: boolean } = {},
464
556
  ): UpdateBranchResult {
557
+ if (o.onlyIfRequired === true) {
558
+ const repo = resolveOwnerRepo(cwd)?.ownerRepo;
559
+ let ghMissing = false;
560
+ const gh = (args: string[]) => {
561
+ const res = runGh(cwd, args);
562
+ if (ghUnavailable(res)) ghMissing = true;
563
+ return res;
564
+ };
565
+ const required = repo === undefined || devRequiresChecks(gh, repo);
566
+ if (ghMissing) {
567
+ log(
568
+ "gh unavailable to read dev's required checks — update the branch through update_pull_request_branch",
569
+ );
570
+ return { code: EXIT.USE_MCP, out: null };
571
+ }
572
+ if (!required) {
573
+ log(
574
+ `dev requires no status checks — PR ${number} merges at the head CI passed at; the dev push run tests the merged result`,
575
+ );
576
+ return { code: EXIT.OK, out: { number, updated: false } };
577
+ }
578
+ if (repo === undefined) log("cannot resolve the repo to read dev's required checks — updating");
579
+ }
465
580
  const res = runGh(cwd, ["pr", "update-branch", number]);
466
581
  if (ghUnavailable(res)) {
467
582
  log(
@@ -783,6 +898,7 @@ export const prsCommand: CommandSpec = {
783
898
  verbs: {
784
899
  open: {
785
900
  summary: "Open a PR whose body carries the bkit:issue / bkit:fid marker (exit 80: use MCP).",
901
+ use: "workflow",
786
902
  flags: [
787
903
  { name: "fid", type: "string", required: true, help: "feature id" },
788
904
  { name: "title", type: "string", required: true, help: "PR title (no skip-CI token)" },
@@ -805,22 +921,32 @@ export const prsCommand: CommandSpec = {
805
921
  type: "string",
806
922
  help: "an open PR already on --head: fail (default, exit 3) | reuse",
807
923
  },
924
+ {
925
+ name: "file",
926
+ type: "string",
927
+ help: "status.jsonl: record the open as an engine-action row; a re-run this run reuses that PR (needs --workflow)",
928
+ },
929
+ { name: "workflow", type: "string", help: "--file: the workflow, for the run number" },
808
930
  ],
809
931
  output: {
810
932
  created: "true when this run created the PR",
811
- useMcp: "true when gh is unavailable: create it through MCP with title/body/base/head",
933
+ useMcp:
934
+ "true when gh is unavailable: create it through MCP with title/base/head and the body read from bodyFile",
812
935
  number: "PR number, or null",
813
936
  url: "PR URL, or null",
814
937
  base: "base branch (read back from the PR when created)",
815
938
  head: "head branch",
816
939
  title: "PR title",
817
940
  body: "PR body, marker first",
941
+ bodyFile:
942
+ "useMcp only: absolute path of a file holding `body` byte-for-byte (the MCP fallback reads it); absent otherwise",
818
943
  },
819
944
  exitCodes: {
820
945
  [EXIT_PR_EXISTS]: "--head already has an open PR (with --existing=fail)",
821
946
  [EXIT_SKIP_CI_TITLE]: "the title carries a CI-suppressing token",
822
947
  [EXIT_GH_FAILED]: "gh errored (probe, create after one retry, or read-back)",
823
948
  [EXIT_WRONG_BASE]: "the created PR's base is not --base",
949
+ [EXIT_BASE_MAIN]: `--base is ${MAIN}: bkit opens PRs into ${DEV} only (no gh call made)`,
824
950
  },
825
951
  run: (ctx) => {
826
952
  const existing = str(ctx.flags.existing);
@@ -832,6 +958,7 @@ export const prsCommand: CommandSpec = {
832
958
  },
833
959
  probe: {
834
960
  summary: "The open (or open-then-merged) PR for a branch, or one PR by number.",
961
+ use: "by-hand",
835
962
  flags: [
836
963
  HEAD_FLAG,
837
964
  { name: "base", type: "string", help: "only PRs into this base (default: any base)" },
@@ -871,6 +998,7 @@ export const prsCommand: CommandSpec = {
871
998
  merge: {
872
999
  summary:
873
1000
  "Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back.",
1001
+ use: "workflow",
874
1002
  flags: [
875
1003
  { name: "number", type: "string", required: true, help: "the PR number" },
876
1004
  {
@@ -908,6 +1036,7 @@ export const prsCommand: CommandSpec = {
908
1036
  exitCodes: {
909
1037
  [EXIT_GH_FAILED]: "gh could not read the PR",
910
1038
  [EXIT_NOT_MERGED]: "--expect-merged and the PR did not reach MERGED",
1039
+ [EXIT_BASE_NOT_DEV]: `the PR's base is not ${DEV}, or could not be read — nothing merged`,
911
1040
  },
912
1041
  run: (ctx) => {
913
1042
  const number = String(ctx.flags.number);
@@ -924,7 +1053,7 @@ export const prsCommand: CommandSpec = {
924
1053
  ctx.log(pr.kind === "failed" ? pr.message : `PR #${number} not found`);
925
1054
  return EXIT_GH_FAILED;
926
1055
  }
927
- subject = `${pr.pr.title} (#${number})`;
1056
+ subject = `${pr.pr.title.replace(FORCE_BUILD_TAG, "")} (#${number})`;
928
1057
  }
929
1058
  if (((ctx.flags.label as string[] | undefined) ?? []).includes(AUTO_LABEL))
930
1059
  subject += AUTO_ROUTE_SUFFIX;
@@ -946,10 +1075,19 @@ export const prsCommand: CommandSpec = {
946
1075
  "update-branch": {
947
1076
  summary:
948
1077
  "Refresh a PR's head from its base server-side (exit 80: use update_pull_request_branch).",
949
- flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
1078
+ use: "workflow",
1079
+ flags: [
1080
+ { name: "number", type: "string", required: true, help: "the PR number" },
1081
+ {
1082
+ name: "only-if-required",
1083
+ type: "boolean",
1084
+ help: "skip the update (updated: false) when dev requires no status checks",
1085
+ },
1086
+ ],
950
1087
  output: {
951
1088
  number: "the PR number",
952
- updated: "the update request succeeded (true even when already up to date)",
1089
+ updated:
1090
+ "the update request succeeded (true even when already up to date); false when --only-if-required skipped it",
953
1091
  },
954
1092
  exitCodes: {
955
1093
  [EXIT_GH_FAILED]: "gh could not update the branch (403 = actions:write scope)",
@@ -958,7 +1096,9 @@ export const prsCommand: CommandSpec = {
958
1096
  const number = String(ctx.flags.number);
959
1097
  if (!/^[1-9][0-9]*$/.test(number))
960
1098
  throw new CommandError(EXIT.USAGE, "--number must be a PR number");
961
- const r = updateBranch(ctx.cwd, number, ctx.log);
1099
+ const r = updateBranch(ctx.cwd, number, ctx.log, {
1100
+ onlyIfRequired: ctx.flags.onlyIfRequired === true,
1101
+ });
962
1102
  if (r.out) ctx.emit(r.out);
963
1103
  return r.code;
964
1104
  },
@@ -966,6 +1106,7 @@ export const prsCommand: CommandSpec = {
966
1106
  checks: {
967
1107
  summary:
968
1108
  "A PR's check rollup, classified: green when present and none failed or pending (exit 80: use MCP).",
1109
+ use: "by-hand",
969
1110
  flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
970
1111
  output: {
971
1112
  number: "the PR number",
@@ -991,6 +1132,7 @@ export const prsCommand: CommandSpec = {
991
1132
  "verbose-ci": {
992
1133
  summary:
993
1134
  "Add ` bkit [verbose ci]` to a PR title, or strip it (with an optional `bkit ` prefix); a no-op when already so.",
1135
+ use: "workflow",
994
1136
  flags: [
995
1137
  { name: "number", type: "string", required: true, help: "the PR number" },
996
1138
  { name: "state", type: "string", required: true, help: "on | off" },
@@ -1043,6 +1185,7 @@ export const prsCommand: CommandSpec = {
1043
1185
  },
1044
1186
  "scan-body": {
1045
1187
  summary: "Check a landed commit's body (not its subject) for a CI-suppressing token.",
1188
+ use: "by-hand",
1046
1189
  flags: [
1047
1190
  { name: "sha", type: "string", required: true, help: "the landed commit" },
1048
1191
  {
@@ -1061,6 +1204,7 @@ export const prsCommand: CommandSpec = {
1061
1204
  },
1062
1205
  "cross-check": {
1063
1206
  summary: "An mcp close with gh recorded unavailable must have a transport-fallback row.",
1207
+ use: "workflow",
1064
1208
  flags: [
1065
1209
  FILE_FLAG,
1066
1210
  {
@@ -1081,6 +1225,7 @@ export const prsCommand: CommandSpec = {
1081
1225
  },
1082
1226
  "transport-row": {
1083
1227
  summary: "Append a transport-fallback or close-transport audit row to status.jsonl.",
1228
+ use: "workflow",
1084
1229
  flags: [
1085
1230
  FILE_FLAG,
1086
1231
  { name: "kind", type: "string", required: true, help: "fallback | close" },
@@ -7,11 +7,12 @@
7
7
  // trails `origin/dev`, the main checkout, the bkit binary every later block calls,
8
8
  // and whether that bkit is behind the newest release ride along so Step 1 is one call.
9
9
 
10
+ import { randomBytes } from "node:crypto";
10
11
  import * as fs from "node:fs";
11
12
  import * as path from "node:path";
12
13
 
13
14
  import { parseRemoteUrlToSlug } from "../../ledgers/telemetry.js";
14
- import { DEV, EXIT, git, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
+ import { DEV, EXIT, git, outboxRoot, repoRoot, runGit, runTool, type CommandSpec } from "../lib.js";
15
16
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
16
17
  import { readBkitConfig, trackerScope } from "../../shared/settings.js";
17
18
 
@@ -36,9 +37,15 @@ export function resolveOwnerRepo(
36
37
  cwd,
37
38
  );
38
39
  if (gh.status === 0 && splitSlug(gh.stdout)) return { ownerRepo: gh.stdout.trim(), source: "gh" };
40
+ const slug = originOwnerRepo(cwd);
41
+ return slug === null ? null : { ownerRepo: slug, source: "remote" };
42
+ }
43
+
44
+ /** `owner/repo` from the `origin` remote URL alone (no network); null when origin names none. */
45
+ export function originOwnerRepo(cwd: string): string | null {
39
46
  const url = git(cwd, ["remote", "get-url", "origin"]);
40
47
  const slug = url ? parseRemoteUrlToSlug(url) : "";
41
- return splitSlug(slug) ? { ownerRepo: slug, source: "remote" } : null;
48
+ return splitSlug(slug) ? slug : null;
42
49
  }
43
50
 
44
51
  /**
@@ -94,6 +101,34 @@ export function actionsPermissionsReadable(
94
101
  return { readable: res.found && res.status === 0, status: res.status, detail };
95
102
  }
96
103
 
104
+ /** Session folders older than this are pruned by `repo info`. */
105
+ export const SESSION_TTL_MS = 7 * 86_400_000;
106
+ const SESSION_NAME = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z-[0-9a-f]+$/;
107
+
108
+ /**
109
+ * Creates `<outboxRoot>/sessions/<utc-time>-<random>/` and prunes session folders
110
+ * whose name stamps them older than {@link SESSION_TTL_MS}. Folders named any
111
+ * other way are left alone.
112
+ */
113
+ export function newSessionDir(outboxRoot: string, now: Date = new Date()): string {
114
+ const sessions = path.join(outboxRoot, "sessions");
115
+ fs.mkdirSync(sessions, { recursive: true });
116
+ for (const name of fs.readdirSync(sessions)) {
117
+ const m = SESSION_NAME.exec(name);
118
+ if (!m) continue;
119
+ const at = Date.UTC(+m[1]!, +m[2]! - 1, +m[3]!, +m[4]!, +m[5]!, +m[6]!);
120
+ if (now.getTime() - at > SESSION_TTL_MS)
121
+ fs.rmSync(path.join(sessions, name), { recursive: true, force: true });
122
+ }
123
+ const stamp = now
124
+ .toISOString()
125
+ .replace(/[-:]/g, "")
126
+ .replace(/\.\d{3}/, "");
127
+ const dir = path.join(sessions, `${stamp}-${randomBytes(4).toString("hex")}`);
128
+ fs.mkdirSync(dir);
129
+ return dir;
130
+ }
131
+
97
132
  export const repoCommand: CommandSpec = {
98
133
  noun: "repo",
99
134
  summary: "Repo facts for Step 1: owner/repo, current branch, and how far it trails dev.",
@@ -101,6 +136,7 @@ export const repoCommand: CommandSpec = {
101
136
  info: {
102
137
  summary:
103
138
  "owner/repo (gh, else the origin remote), the current branch, and commits behind origin/dev.",
139
+ use: "by-hand",
104
140
  flags: [
105
141
  {
106
142
  name: "fetch",
@@ -124,6 +160,8 @@ export const repoCommand: CommandSpec = {
124
160
  repoRoot: "the main checkout (the same from any worktree)",
125
161
  bkit: "the bkit binary the workflow blocks call: <repoRoot>/node_modules/.bin/bkit, else `bkit` on PATH",
126
162
  outboxRoot: "<git common dir>/bkit-outbox: per-run scratch files, never committed",
163
+ sessionDir:
164
+ "<outboxRoot>/sessions/<utc-time>-<random>/: a new, empty folder per call for this run's prompt.md and issue files; folders older than 7 days are pruned",
127
165
  bkitVersion:
128
166
  ".bkit/version pinnedVersion: the release this repo's bkit files came from (null when unpinned)",
129
167
  bkitLatest:
@@ -131,12 +169,22 @@ export const repoCommand: CommandSpec = {
131
169
  bkitOutdated:
132
170
  "true when bkitVersion is older than bkitLatest (null when either is unknown)",
133
171
  bkitAdvisory: "one line to show the user when bkitOutdated, else null",
134
- trackerTeam: "package.json bkit.linear.team under linear, else null",
172
+ trackerTeam: "package.json bkit.tracker.linear.team under linear, else null",
135
173
  trackerProject:
136
- "package.json bkit.linear.project under linear, bkit.jira.project under jira, else null",
137
- trackerSite: "package.json bkit.jira.site under jira (the MCP cloudId), else null",
174
+ "package.json bkit.tracker.linear.project under linear, bkit.tracker.jira.project under jira, else null",
175
+ trackerSite: "package.json bkit.tracker.jira.site under jira (the MCP cloudId), else null",
138
176
  trackerBoard:
139
- "{ownerType, owner, number} read from package.json bkit.github.project under github, else null",
177
+ "{ownerType, owner, number} read from package.json bkit.tracker.github.project under github, else null",
178
+ trackerProgress:
179
+ "the state an issue moves to when work starts: package.json bkit.tracker.<tracker>.progress for the wired tracker, at its default when unset (github `In progress`, linear `started`, jira `In Progress`); null under none",
180
+ trackerReview:
181
+ "the state an issue moves to when it is handed to a human: package.json bkit.tracker.<tracker>.review for the wired tracker, at its default when unset (github `In review`, linear `In Review`, jira `In Review`); null under none",
182
+ tasks:
183
+ "{maxPerGroup, maxTestsPerGroup, maxTestsPerTask, maxTestFilesPerTask}: the plan caps from package.json bkit.workflows.tasks, each missing or invalid key at its default",
184
+ buildPublishRemote:
185
+ "boolean: the remote build ending from package.json bkit.workflows.build.publish.remote; always true, a false value is refused",
186
+ buildPublishLocal:
187
+ "boolean: the local build ending from package.json bkit.workflows.build.publish.local; true publishes, false holds; true when unset or invalid",
140
188
  },
141
189
  exitCodes: {
142
190
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -173,6 +221,9 @@ export const repoCommand: CommandSpec = {
173
221
  const common = git(ctx.cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
174
222
  const latest = bkitVersionStatus(root, common);
175
223
  if (latest.advisory !== null) ctx.log(latest.advisory);
224
+ const outbox = outboxRoot(ctx.cwd) ?? path.join(root, ".git", "bkit-outbox");
225
+ const config = readBkitConfig(root);
226
+ const states = config.issueTracker === "none" ? null : config[config.issueTracker];
176
227
  ctx.emit({
177
228
  ...resolved,
178
229
  owner,
@@ -181,12 +232,18 @@ export const repoCommand: CommandSpec = {
181
232
  ...behind,
182
233
  repoRoot: root,
183
234
  bkit: resolveBkitBinary(root),
184
- outboxRoot: path.join(common ?? path.join(root, ".git"), "bkit-outbox"),
235
+ outboxRoot: outbox,
236
+ sessionDir: newSessionDir(outbox),
185
237
  bkitVersion: latest.version,
186
238
  bkitLatest: latest.latest,
187
239
  bkitOutdated: latest.outdated,
188
240
  bkitAdvisory: latest.advisory,
189
- ...trackerScope(readBkitConfig(root)),
241
+ ...trackerScope(config),
242
+ trackerProgress: states?.progress ?? null,
243
+ trackerReview: states?.review ?? null,
244
+ tasks: config.tasks,
245
+ buildPublishRemote: config.buildPublish.remote,
246
+ buildPublishLocal: config.buildPublish.local,
190
247
  });
191
248
  if (branch === null && ctx.flags.allowDetached !== true) {
192
249
  ctx.log("HEAD is detached — no current branch");
@@ -198,6 +255,7 @@ export const repoCommand: CommandSpec = {
198
255
  preflight: {
199
256
  summary:
200
257
  "Advisory: whether gh can read the repo's Actions permissions (dispatch may 403 without them).",
258
+ use: "by-hand",
201
259
  flags: [
202
260
  {
203
261
  name: "owner-repo",