@cbartens/bkit 6.1.1 → 6.2.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 (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -14,7 +14,7 @@
14
14
  // Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
15
15
  // never name an outside service — examples of specific services go in `steps`, which is
16
16
  // for the agent. A template's benefit reads the same here, in its `.bkit/templates.md`
17
- // section opener and in the README's "Templates ready to adopt" row; change all three in
17
+ // section opener and in `DETAILS.md` § Templates ready to adopt; change all three in
18
18
  // the same commit.
19
19
  //
20
20
  // Detection rules: every `fires` is local (files, settings, environment) — no network. The
@@ -38,7 +38,7 @@ import {
38
38
  } from "../before/env.js";
39
39
  import { detectGhMcpToken, hasGithubMcpServer } from "../after/auth.js";
40
40
  import { buildTrackerSetupAdvisory } from "../after/github.js";
41
- import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
41
+ import { buildDepUpdaterSetupAdvisory, detectProjectDocs } from "../after/tools.js";
42
42
  import { detectInstalledHostModules } from "../../install/hosts.js";
43
43
  import { readBkitConfig } from "../../shared/settings.js";
44
44
  import type { ComplyPhase, TipsContext } from "../../cli.js";
@@ -50,6 +50,8 @@ import {
50
50
  hasJsTestRunner,
51
51
  hasLintStagedConfig,
52
52
  hasMcpServer,
53
+ hasNoProjectGoals,
54
+ hasProjectGoalsHeading,
53
55
  hasNewerBkit,
54
56
  hasTestLinter,
55
57
  hasUnsharedFriction,
@@ -74,6 +76,8 @@ export interface SetupTip {
74
76
  ask: string;
75
77
  /** Where the agent finds the exact steps. */
76
78
  steps: string;
79
+ /** Per-repo `ask` / `steps`; `collectTips` applies it before returning the tip. */
80
+ resolve?: (cwd: string) => { ask: string; steps: string };
77
81
  /** False when no `bkit.advisories.ignore` entry may silence the tip. */
78
82
  silenceable?: false;
79
83
  /** Advisory ids this tip reuses the check of; a trailing `*` matches an id prefix. */
@@ -90,6 +94,37 @@ export const ALL_WORKFLOWS: readonly ComplyPhase[] = ["design", "plan", "build",
90
94
  /** Every `bkit tips --workflow=` context: the phase workflows, then the two agent closes. */
91
95
  export const EVERY_CONTEXT: readonly TipsContext[] = [...ALL_WORKFLOWS, "audit", "utility"];
92
96
 
97
+ const CLOUD_STEPS = "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.";
98
+
99
+ /** The `cloud` tip's `ask` / `steps` for the recorded `bkit.cloud.agent`. */
100
+ function cloudTipText(agent: string): { ask: string; steps: string } {
101
+ const copy =
102
+ "copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml";
103
+ const tail = "then tell me which dashboard settings are left.";
104
+ switch (agent) {
105
+ case "claude":
106
+ return {
107
+ ask: `Check my cloud-agent setup against .bkit/cloud.md: install the Claude GitHub App on the repo, ${copy} and .bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh to .claude/hooks/, run \`gh secret set BKIT_ANTHROPIC_API_KEY\` (or, keyless, \`gh variable set\` ANTHROPIC_FEDERATION_RULE_ID and ANTHROPIC_ORGANIZATION_ID from a Claude Console federation rule), ${tail}`,
108
+ steps: CLOUD_STEPS,
109
+ };
110
+ case "codex":
111
+ return {
112
+ ask: `Check my cloud-agent setup against .bkit/cloud.md: confirm bkit was installed with --codex, ${copy}, run \`gh secret set BKIT_OPENAI_API_KEY\`, ${tail}`,
113
+ steps: CLOUD_STEPS,
114
+ };
115
+ case "opencode":
116
+ return {
117
+ ask: `Check my cloud-agent setup against .bkit/cloud.md: ${copy}, set the opencode provider's BKIT_ API key as a repo secret (the name is in .bkit/cloud.md), ${tail}`,
118
+ steps: CLOUD_STEPS,
119
+ };
120
+ default:
121
+ return {
122
+ ask: `Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.cursor/environment.json and .bkit/templates/.cursor/Dockerfile to .cursor/, ${tail}`,
123
+ steps: CLOUD_STEPS,
124
+ };
125
+ }
126
+ }
127
+
93
128
  export const SETUP_TIPS: readonly SetupTip[] = [
94
129
  // --- current: is bkit itself up to date ---------------------------------------------
95
130
  {
@@ -131,7 +166,9 @@ export const SETUP_TIPS: readonly SetupTip[] = [
131
166
  advisories: ["gh-mcp-token-unset-shell", "gh-mcp-token-empty-shell"],
132
167
  fires: (cwd) =>
133
168
  readBkitConfig(cwd).issueTracker === "github" &&
134
- (!hasGithubMcpServer(cwd) || detectGhMcpToken(cwd) !== null),
169
+ (!hasGithubMcpServer(cwd) ||
170
+ // The pre-push hook's inner run unsets the .bkit/.env keys on purpose, so a missing token there is not real.
171
+ (!process.env.BKIT_PRE_PUSH_LOGGED && detectGhMcpToken(cwd) !== null)),
135
172
  },
136
173
  {
137
174
  id: "bkit-env",
@@ -207,7 +244,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
207
244
  title: "Consistent formatting",
208
245
  line: "There's no shared formatting setup, so reviews fill up with spacing changes that hide the real ones. Add Prettier with bkit's ignore file.",
209
246
  why: "Prettier (a code formatter) makes every file follow the same layout. bkit's ignore file stops it reformatting bkit's own files, which would otherwise show up as false changes every time bkit updates.",
210
- ask: 'Copy .bkit/templates/.prettierignore to .prettierignore first, then run `pnpm add -D prettier` and add `"format:check": "prettier --check ."` to the package.json scripts.',
247
+ ask: 'Copy .bkit/templates/prettierignore.example to .prettierignore first, then run `pnpm add -D prettier` and add `"format:check": "prettier --check ."` to the package.json scripts.',
211
248
  steps: "`.bkit/templates.md` § Prettier.",
212
249
  fires: (cwd) => !exists(cwd, ".prettierignore"),
213
250
  },
@@ -247,7 +284,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
247
284
  title: "Quick tidy-up on commit",
248
285
  line: "The commit check has nothing to run. Add lint-staged so it tidies just the files you're committing.",
249
286
  why: "It formats only the handful of files in each change, in about a second. Without it the commit check either does nothing or is slow enough that people start skipping it.",
250
- ask: "Run `pnpm add -D lint-staged prettier` and copy .bkit/templates/.lintstagedrc.json to .lintstagedrc.json.",
287
+ ask: "Run `pnpm add -D lint-staged prettier` and copy .bkit/templates/lintstagedrc.example.json to .lintstagedrc.json.",
251
288
  steps: "`.bkit/templates.md` § lint-staged.",
252
289
  fires: (cwd) => !hasLintStagedConfig(cwd),
253
290
  },
@@ -259,8 +296,9 @@ export const SETUP_TIPS: readonly SetupTip[] = [
259
296
  title: "Finish cloud setup",
260
297
  line: "You've turned on cloud agents, but setup isn't finished, so cloud runs will stop partway. Finish the remaining steps.",
261
298
  why: "With cloud agents, bkit runs on its own: a change that passes its checks gets shipped and one that fails gets investigated, with nobody at the keyboard. That only works once every piece is in place.",
262
- ask: "Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml and .bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh to .claude/hooks/ (for Cursor: .bkit/templates/.cursor/environment.json and .bkit/templates/.cursor/Dockerfile to .cursor/), run `gh secret set ANTHROPIC_API_KEY` (or, keyless, `gh variable set` ANTHROPIC_FEDERATION_RULE_ID and ANTHROPIC_ORGANIZATION_ID from a Claude Console federation rule), then tell me which dashboard settings are left.",
299
+ ask: "Check my cloud-agent setup against .bkit/cloud.md: copy .bkit/templates/.github/workflows/bkit-cloud.yml to .github/workflows/bkit-cloud.yml, set the agent's credential as a repo secret under its BKIT_ name, then tell me which dashboard settings are left.",
263
300
  steps: "`.bkit/cloud.md`; `.bkit/templates.md` § Cloud-agent workflow and § Cursor.",
301
+ resolve: (cwd) => cloudTipText(readBkitConfig(cwd).cloudAgents),
264
302
  fires: (cwd) => {
265
303
  const cloud = readBkitConfig(cwd).cloudAgents;
266
304
  if (cloud === "none") return false;
@@ -359,6 +397,38 @@ export const SETUP_TIPS: readonly SetupTip[] = [
359
397
  steps: "`.bkit/templates.md` § graphify.",
360
398
  fires: (cwd) => !exists(cwd, "scripts/graphify"),
361
399
  },
400
+ {
401
+ id: "project-docs",
402
+ workflows: ["design", "plan", "build"],
403
+ title: "Project docs",
404
+ line: "Fill the project docs in waves, because each doc reads facts the earlier ones record.",
405
+ why: "Agents read your architecture, testing and security docs before they plan and build. A doc that is missing or still holds the starter text gives them nothing to go on, so they guess from the code each time.",
406
+ caution:
407
+ "Ignoring either the missing-doc advisory or the unfilled-doc advisory also silences this tip and the other advisory.",
408
+ ask: "Fill in my project docs in the order of .bkit/templates.md § Project docs — adoption order: copy each missing starter from .bkit/templates/docs/ to docs/, fill it from the repository, and add its row to .agents/docs.md.",
409
+ steps: "`.bkit/templates.md` § Project docs — adoption order.",
410
+ advisories: ["project-docs-missing", "project-docs-unpopulated"],
411
+ fires: (cwd) =>
412
+ detectProjectDocs(cwd).some(
413
+ (f) => f.id === "project-docs-missing" || f.id === "project-docs-unpopulated",
414
+ ),
415
+ },
416
+ {
417
+ id: "project-goals",
418
+ workflows: ["design", "plan"],
419
+ title: "Project goals",
420
+ line: "Agents have rules but no goals, so when two options both fit the rules they choose by guesswork. Write down what this project optimises for.",
421
+ why: "Design and plan agents choose between options on every run. The rules say what is allowed, not what matters most here, so each agent weighs speed, cost and polish its own way.",
422
+ ask: "Add a `## Project Goals` section to .agents/rules.md, between Project Rules and Project Settings, with a few goals in priority order. Ask me what this project optimises for first.",
423
+ steps: "`.bkit/prompts.md` § Special Behaviors, where the Project Goals row sits.",
424
+ resolve: (cwd) => ({
425
+ ask: hasProjectGoalsHeading(cwd)
426
+ ? "Fill the `## Project Goals` section that already exists in .agents/rules.md instead of adding a second one, with a few goals in priority order. Ask me what this project optimises for first."
427
+ : "Add a `## Project Goals` section to .agents/rules.md, between Project Rules and Project Settings, with a few goals in priority order. Ask me what this project optimises for first.",
428
+ steps: "`.bkit/prompts.md` § Special Behaviors, where the Project Goals row sits.",
429
+ }),
430
+ fires: hasNoProjectGoals,
431
+ },
362
432
  {
363
433
  id: "dependabot-renovate",
364
434
  workflows: ["ship", "audit"],
@@ -432,6 +502,34 @@ export const SETUP_TIPS: readonly SetupTip[] = [
432
502
  );
433
503
  },
434
504
  },
505
+ {
506
+ id: "pre-push-pr-conflict",
507
+ workflows: ["plan", "ship"],
508
+ title: "Stop a push whose PR no longer merges",
509
+ line: "Your pre-push hook runs the whole gate even when the branch's open PR conflicts with its base, and CI never starts.",
510
+ why: "The newer hook looks up the open PR once, fetches its base and trial-merges the pushed commit. A conflict stops the push in seconds and names the files; a lookup or fetch that cannot answer only warns.",
511
+ ask: "Paste the `Open-PR lookup` block (above the CI-suppressor guard, which now reads the PR number from it) and the `PR conflict` block (before `pnpm bkit check`) of .bkit/templates/.husky/pre-push into .husky/pre-push, and add the `PUSH_BRANCH_SHA` line of its stdin loop: without it the check never runs.",
512
+ steps: "`.bkit/templates.md` § Git hooks.",
513
+ fires: (cwd) => {
514
+ if (!exists(cwd, ".husky/pre-push")) return false;
515
+ const hook = fs.readFileSync(path.join(cwd, ".husky/pre-push"), "utf-8");
516
+ return !hook.includes("merge-tree") || !hook.includes("PUSH_BRANCH_SHA=");
517
+ },
518
+ },
519
+ {
520
+ id: "pre-push-direnv",
521
+ workflows: ["plan", "ship"],
522
+ title: "Load .envrc when the pre-push hook runs",
523
+ line: "Your pre-push hook runs the gate without your .envrc variables when the shell that pushed never loaded them.",
524
+ why: "The newer hook runs its logged inner run through `direnv exec .`, so the gate always sees the repo's variables, and an untrusted .envrc stops the push in seconds with the fix instead of failing deep in the gate. The unset loops right after that block keep the fixed list of bkit tooling keys (BKIT_GH_TOKEN, ...), and every key `.bkit/.env` names, out of the gate and its log, however they were loaded.",
525
+ ask: "Replace the log block of .husky/pre-push (the `BKIT_PRE_PUSH_LOGGED` block) and the `.bkit/.env` unset block that follows it with the ones in .bkit/templates/.husky/pre-push.",
526
+ steps: "`.bkit/templates.md` § Git hooks.",
527
+ fires: (cwd) => {
528
+ if (!exists(cwd, ".husky/pre-push") || !exists(cwd, ".envrc")) return false;
529
+ const hook = fs.readFileSync(path.join(cwd, ".husky/pre-push"), "utf-8");
530
+ return !hook.includes("direnv exec");
531
+ },
532
+ },
435
533
  {
436
534
  id: "disk-prune",
437
535
  workflows: ALL_WORKFLOWS,
@@ -448,11 +546,10 @@ export const SETUP_TIPS: readonly SetupTip[] = [
448
546
  {
449
547
  id: "share-friction",
450
548
  title: "Tell bkit what slowed you down",
451
- line: "Your workflows have noted problems with bkit itself that its makers never see. Send them, with your stats, as one issue on bkit's issue page.",
549
+ line: "Your workflows logged problems its makers never see. Send them with your stats as one issue.",
452
550
  why: "Workflows note every place bkit got in the way: a command that failed, rework, a manual step. Those notes stay in this repo, so the people who fix bkit never learn about them. One report from you is how they reach the fix list.",
453
- caution:
454
- "bkit's issue page is public. Your agent removes project names, paths and links first, and shows you the exact text before anything is posted.",
455
- ask: "Share this repo's bkit friction and stats with bkit's makers as one new issue: follow the paste block in .bkit/README.md § Share friction with bkit, show me the exact title and text, and post only after I say yes.",
551
+ caution: "bkit's issues are public. Your agent strips project names, paths and links first.",
552
+ ask: "Share this repo's bkit friction and stats as one issue per .bkit/README.md § Share friction with bkit. Show me the exact text; post only after I say yes.",
456
553
  steps: "`.bkit/README.md` § Share friction with bkit.",
457
554
  fires: hasUnsharedFriction,
458
555
  },
@@ -132,11 +132,17 @@ const LINT_STAGED_CONFIGS = [
132
132
  ".lintstagedrc.yaml",
133
133
  ".lintstagedrc.yml",
134
134
  ".lintstagedrc.mjs",
135
- ".lintstagedrc.cjs",
135
+ ".lintstagedrc.mts",
136
136
  ".lintstagedrc.js",
137
+ ".lintstagedrc.ts",
138
+ ".lintstagedrc.cjs",
139
+ ".lintstagedrc.cts",
137
140
  "lint-staged.config.mjs",
138
- "lint-staged.config.cjs",
141
+ "lint-staged.config.mts",
139
142
  "lint-staged.config.js",
143
+ "lint-staged.config.ts",
144
+ "lint-staged.config.cjs",
145
+ "lint-staged.config.cts",
140
146
  ];
141
147
 
142
148
  /** True when any `.github/workflows/*.yml` / `*.yaml` contains `needle`. */
@@ -149,9 +155,11 @@ export function anyWorkflowMentions(cwd: string, needle: string): boolean {
149
155
  .some((f) => readText(cwd, path.join(".github", "workflows", f)).includes(needle));
150
156
  }
151
157
 
152
- /** True when lint-staged is configured: any of its config files, or `package.json` `lint-staged`. */
158
+ /** True when lint-staged is configured: any of its config files, `package.json` or `package.yaml` / `package.yml` `lint-staged` key. */
153
159
  export function hasLintStagedConfig(cwd: string): boolean {
154
160
  if (LINT_STAGED_CONFIGS.some((rel) => exists(cwd, rel))) return true;
161
+ if (["package.yaml", "package.yml"].some((rel) => /^lint-staged\s*:/m.test(readText(cwd, rel))))
162
+ return true;
155
163
  const pkg = readPackageJson(cwd);
156
164
  return pkg.ok && pkg.pkg["lint-staged"] !== undefined;
157
165
  }
@@ -223,6 +231,31 @@ export function readsBkitText(cwd: string): string[] {
223
231
  });
224
232
  }
225
233
 
234
+ /** `.agents/rules.md` below `<!-- bkit:end -->` with HTML comments removed; null without the file. */
235
+ function rulesBelowEnd(cwd: string): string | null {
236
+ const text = readText(cwd, ".agents/rules.md");
237
+ if (!text) return null;
238
+ const end = text.indexOf("<!-- bkit:end -->");
239
+ return (end === -1 ? text : text.slice(end)).replace(/<!--[\s\S]*?-->/g, "");
240
+ }
241
+
242
+ /** True when the rules file already has a `## Project Goals` heading below `<!-- bkit:end -->`. */
243
+ export function hasProjectGoalsHeading(cwd: string): boolean {
244
+ return /^## Project Goals/m.test(rulesBelowEnd(cwd) ?? "");
245
+ }
246
+
247
+ /**
248
+ * True when `.agents/rules.md` exists and no `## Project Goals` section, read below
249
+ * `<!-- bkit:end -->`, holds a list item (`-`, `*`, `+` or `1.` / `1)`) once HTML comments
250
+ * are removed.
251
+ */
252
+ export function hasNoProjectGoals(cwd: string): boolean {
253
+ const below = rulesBelowEnd(cwd);
254
+ if (below === null) return false;
255
+ const sections = [...below.matchAll(/^## Project Goals[^\n]*\n([\s\S]*?)(?=^## |(?![\s\S]))/gm)];
256
+ return !sections.some((m) => /^\s*(?:[-*+]|\d+[.)])\s/m.test(m[1] ?? ""));
257
+ }
258
+
226
259
  /**
227
260
  * True when `.bkit/friction.jsonl` holds an entry worth sending to bkit: its fold winner
228
261
  * is `OPEN` (or has no status) and its `scope` is not `consumer`. A shared entry gets a
@@ -124,7 +124,7 @@ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_
124
124
  for (const tip of catalogue) {
125
125
  if (!tip.fires(base)) continue;
126
126
  if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
127
- else tips.push(tip);
127
+ else tips.push(tip.resolve ? { ...tip, ...tip.resolve(base) } : tip);
128
128
  }
129
129
  const star = !ignored.has(STAR_TIP_ID) && !ignored.has(STAR_TIP_OLD_ID);
130
130
  return { tips, suppressed, star };
@@ -24,7 +24,7 @@ export type ModuleFlag =
24
24
  "core" | "claude" | "cursor" | "opencode" | "codex" | "antigravity" | "cloud";
25
25
 
26
26
  /** Cloud-agent variant chosen via `--auto=<variant>`. */
27
- export const CLOUD_VARIANTS = ["claude", "cursor", "opencode"] as const;
27
+ export const CLOUD_VARIANTS = ["claude", "cursor", "opencode", "codex"] as const;
28
28
  export type CloudVariant = (typeof CLOUD_VARIANTS)[number];
29
29
 
30
30
  /** Narrow an unknown string to `CloudVariant` or return `null` if invalid. */
@@ -589,7 +589,7 @@ export const CLASSIC_VERB_HELP: readonly ClassicVerbHelp[] = [
589
589
  "--antigravity",
590
590
  "--cursor",
591
591
  "--opencode=<provider>",
592
- "--auto=<claude|cursor|opencode>",
592
+ "--auto=<claude|cursor|opencode|codex>",
593
593
  "--tracker=<name>",
594
594
  "--auto-revert",
595
595
  ],
@@ -645,7 +645,7 @@ export const CLASSIC_VERB_HELP: readonly ClassicVerbHelp[] = [
645
645
  "--antigravity",
646
646
  "--cursor",
647
647
  "--opencode=<provider>",
648
- "--auto=<claude|cursor|opencode>",
648
+ "--auto=<claude|cursor|opencode|codex>",
649
649
  "--dry-run",
650
650
  "--force",
651
651
  "--nuke",
@@ -827,7 +827,7 @@ Module flags (composable; symmetric install ↔ uninstall):
827
827
  opencode-zen, opencode-go (opencode-native gateways;
828
828
  auth via BKIT_OPENCODE_API_KEY).
829
829
  Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js,
830
- bkit-readguard.js).
830
+ bkit-readguard.js, bkit-guardrails.js).
831
831
  Configure your provider key; verify with \`bkit doctor\`. All installed
832
832
  providers tracked in bkit.providers.opencode.installed.
833
833
  --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
@@ -851,14 +851,14 @@ Dependency updaters (copy an example and own it):
851
851
  blocks when that value and the configs disagree.
852
852
  All templates and install steps: .bkit/templates.md
853
853
 
854
- --auto=<claude|cursor|opencode>
855
- Cloud-agent (auto-dispatch) integration (opt-in). --auto=claude needs
856
- tracker=github + the ANTHROPIC_API_KEY repo secret (or the
857
- ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID repo variables
858
- for keyless federation) + the Claude GitHub App; --auto=cursor
859
- needs tracker=linear; --auto=opencode needs tracker=github + a remote
860
- opencode provider (OPENCODE_PROVIDER_KEY). Bare --auto is accepted on
861
- uninstall only.
854
+ --auto=<claude|cursor|opencode|codex>
855
+ Cloud-agent (auto-dispatch) integration (opt-in). Every variant needs
856
+ a wired tracker (github, linear or jira). Claude needs the
857
+ BKIT_ANTHROPIC_API_KEY repo secret or the ANTHROPIC_FEDERATION_RULE_ID
858
+ + ANTHROPIC_ORGANIZATION_ID repo variables, plus the Claude GitHub App.
859
+ Codex needs --codex and BKIT_OPENAI_API_KEY. OpenCode needs --opencode
860
+ and its configured provider's BKIT_ key. Cursor uses its dashboard
861
+ triggers. Bare --auto is accepted on uninstall only.
862
862
 
863
863
  Cross-cutting / modifiers:
864
864
  --tracker=<name> Wire issue tracker integration. Values: github, linear, jira, none
@@ -966,7 +966,7 @@ export function validateModuleFlagsForVerb(
966
966
  // The CLI entrypoint, run only when this file is executed and driven by real
967
967
  // argv/fs/process.exit side effects; install.integration.test.ts exercises it through
968
968
  // spawned processes. Pure decision logic lives in exported functions
969
- // (validateModuleFlagsForVerb above, validateCloudTrackerMatch in commands/install/install.ts)
969
+ // (validateModuleFlagsForVerb above, validateCloudTrackerWired in commands/install/install.ts)
970
970
  // for unit coverage.
971
971
  export async function main() {
972
972
  const commandExit = await runCommand(process.argv.slice(2), COMMANDS, {
@@ -17,7 +17,7 @@
17
17
  // (`SKIP_CI_TOKEN`), for the `.husky/pre-push` CI-suppressor guard.
18
18
  //
19
19
  // `min-push` — whether every file a push changes is one bkit's workflows write (ship's bookkeeping
20
- // allow-list, the plans tree) or one `bkit.testing.minPushPaths` / `ciSkipPaths` adds, so
20
+ // allow-list, the plans tree, the audit reports) or one `bkit.testing.minPushPaths` / `ciSkipPaths` adds, so
21
21
  // `.husky/pre-push` runs `bkit:gate:min`. Files decide, never `[skip ci]` (a typed label
22
22
  // GitHub reads off the last commit only).
23
23
  //
@@ -53,8 +53,10 @@ import {
53
53
  bookPathspecs,
54
54
  changedOutside,
55
55
  checkOnlyBookkeeping,
56
+ gitRaw,
56
57
  globPathspecs,
57
58
  } from "../workflow/ledgers.js";
59
+ import { managedHead } from "../../install/managed-block.js";
58
60
  import { pins } from "./pins.js";
59
61
  import { hasVerifiedIncrement, runPushGate } from "./push-gate.js";
60
62
 
@@ -247,7 +249,7 @@ const tail = (text: string) => text.trim().split("\n").slice(-20).join("\n");
247
249
  * the signal would. Without the listeners Node dies on the signal and leaves the base
248
250
  * worktree registered in the repo.
249
251
  */
250
- async function withCleanup<T>(body: () => T, cleanup: () => void): Promise<T> {
252
+ export async function withCleanup<T>(body: () => T, cleanup: () => void): Promise<T> {
251
253
  const received: NodeJS.Signals[] = [];
252
254
  const onSignal = (sig: NodeJS.Signals) => received.push(sig);
253
255
  for (const sig of CLEANUP_SIGNALS) process.on(sig, onSignal);
@@ -602,14 +604,14 @@ function skipToken(ctx: RunContext): number {
602
604
  /**
603
605
  * The min-push pathspecs: ship's `pr` bookkeeping allow-list for every month and feature
604
606
  * (the same list `bkit ci bookkeeping-push` and the ship gate accept untested, including
605
- * `bkit.testing.ciSkipPaths`), the plans tree bkit's workflows write, and whatever the repo
607
+ * `bkit.testing.ciSkipPaths`), the plans tree and audit reports bkit's workflows write, and whatever the repo
606
608
  * adds in `bkit.testing.minPushPaths` (`:(glob)` unless an entry carries its own magic).
607
609
  * The engine hardcodes no consumer file: the floor is what bkit itself writes.
608
610
  */
609
611
  export function minPushPathspecs(cfg: Pick<BkitConfig, "minPushPaths" | "ciSkipPaths">): string[] {
610
612
  return [
611
613
  ...bookPathspecs("*", "*", "pr", cfg.ciSkipPaths),
612
- ...globPathspecs(["docs/plans/**", ...cfg.minPushPaths]),
614
+ ...globPathspecs(["docs/plans/**", "docs/audits/**", ...cfg.minPushPaths]),
613
615
  ];
614
616
  }
615
617
 
@@ -623,6 +625,48 @@ export function pushBase(cwd: string, sha: string): string | null {
623
625
  return null;
624
626
  }
625
627
 
628
+ /** An audit template the project owns below its managed block; no other template qualifies. */
629
+ const AUDIT_TEMPLATE_RE = /^docs\/templates\/bkit-audit-[^/]+\.md$/;
630
+
631
+ export type MinPushOutside =
632
+ | { ok: true; changed: string[]; outside: string[]; sections: string[] }
633
+ | { ok: false; stderr: string };
634
+
635
+ /**
636
+ * `changedOutside` plus the audit-template exception: a top-level `docs/templates/bkit-audit-*.md`
637
+ * present at both commits whose text through the `bkit:end` line is identical at both (so only
638
+ * the project section below it changed) is moved from `outside` to `sections`.
639
+ */
640
+ export function minPushOutside(
641
+ root: string,
642
+ from: string,
643
+ to: string,
644
+ paths: readonly string[],
645
+ ): MinPushOutside {
646
+ const diff = changedOutside(root, from, to, paths);
647
+ if (!diff.ok) return diff;
648
+ const sections: string[] = [];
649
+ const outside: string[] = [];
650
+ const head = (sha: string, file: string): string | null => {
651
+ const res = gitRaw(root, ["cat-file", "blob", `${sha}:${file}`]);
652
+ return res.status === 0 ? managedHead(res.stdout) : null;
653
+ };
654
+ for (const file of diff.outside) {
655
+ if (AUDIT_TEMPLATE_RE.test(file)) {
656
+ const before = head(from, file);
657
+ if (before !== null && before === head(to, file)) {
658
+ sections.push(file);
659
+ continue;
660
+ }
661
+ }
662
+ outside.push(file);
663
+ }
664
+ return { ok: true, changed: diff.changed, outside, sections };
665
+ }
666
+
667
+ const sectionNote = (file: string) =>
668
+ `${file}: only its project section below <!-- bkit:end --> changed`;
669
+
626
670
  function minPush(ctx: RunContext): number {
627
671
  const top = runGit(ctx.cwd, ["rev-parse", "--show-toplevel"]);
628
672
  if (!top.ok) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${ctx.cwd}`);
@@ -640,10 +684,11 @@ function minPush(ctx: RunContext): number {
640
684
 
641
685
  const changed = new Set<string>();
642
686
  const outside = new Set<string>();
687
+ const sections = new Set<string>();
643
688
  for (const ref of refs) {
644
689
  const sha = git(ctx.cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
645
690
  const base = sha ? (baseFlag ?? pushBase(ctx.cwd, sha)) : null;
646
- const diff = sha && base ? changedOutside(top.stdout, base, sha, paths) : null;
691
+ const diff = sha && base ? minPushOutside(top.stdout, base, sha, paths) : null;
647
692
  if (!diff?.ok) {
648
693
  const why = !sha
649
694
  ? `cannot read commit '${ref}'`
@@ -656,7 +701,9 @@ function minPush(ctx: RunContext): number {
656
701
  }
657
702
  for (const p of diff.changed) changed.add(p);
658
703
  for (const p of diff.outside) outside.add(p);
704
+ for (const p of diff.sections) sections.add(p);
659
705
  }
706
+ for (const p of [...sections].sort()) ctx.log(sectionNote(p));
660
707
 
661
708
  const result = (reason: string | null, code: number, message: string) => {
662
709
  ctx.log(message);
@@ -686,6 +733,7 @@ function minPush(ctx: RunContext): number {
686
733
  function minPushUpdates(ctx: RunContext, cwd: string, updates: string[], paths: string[]): number {
687
734
  const changed = new Set<string>();
688
735
  const outside = new Set<string>();
736
+ const sections = new Set<string>();
689
737
  let unknown = false;
690
738
  let failed = false;
691
739
  for (const update of updates) {
@@ -699,17 +747,19 @@ function minPushUpdates(ctx: RunContext, cwd: string, updates: string[], paths:
699
747
  unknown = true;
700
748
  continue;
701
749
  }
702
- const increment = isNew ? null : changedOutside(cwd, oldSha, newSha, paths);
750
+ const increment = isNew ? null : minPushOutside(cwd, oldSha, newSha, paths);
703
751
  const base = pushBase(cwd, newSha);
704
- const whole = base ? changedOutside(cwd, base, newSha, paths) : null;
705
- if (hasVerifiedIncrement(cwd, oldSha, newSha, paths)) {
752
+ const whole = base ? minPushOutside(cwd, base, newSha, paths) : null;
753
+ if (hasVerifiedIncrement(cwd, oldSha, newSha, (a, b) => minPushOutside(cwd, a, b, paths))) {
706
754
  if (increment?.ok) for (const file of increment.changed) changed.add(file);
755
+ if (increment?.ok) for (const file of increment.sections) sections.add(file);
707
756
  ctx.log(`${oldSha}..${newSha}: covered by a successful full push gate`);
708
757
  continue;
709
758
  }
710
759
  if (whole?.ok) {
711
760
  for (const file of whole.changed) changed.add(file);
712
761
  for (const file of whole.outside) outside.add(file);
762
+ for (const file of whole.sections) sections.add(file);
713
763
  if (
714
764
  whole.changed.length > 0 &&
715
765
  whole.outside.length === 0 &&
@@ -719,6 +769,7 @@ function minPushUpdates(ctx: RunContext, cwd: string, updates: string[], paths:
719
769
  } else unknown = true;
720
770
  failed = true;
721
771
  }
772
+ for (const file of [...sections].sort()) ctx.log(sectionNote(file));
722
773
  const reason = !failed ? null : unknown ? "unknown" : outside.size ? "outside" : "no-changes";
723
774
  ctx.emit({
724
775
  minPush: !failed,
@@ -890,12 +941,14 @@ export const ciCommand: CommandSpec = {
890
941
  },
891
942
  ],
892
943
  output: {
893
- minPush: "true when every changed file matches a min-push path",
944
+ minPush:
945
+ "true when every changed file matches a min-push path, or is a docs/templates/bkit-audit-*.md changed only below its <!-- bkit:end -->",
894
946
  reason: "null when a min push; else no-changes | outside | unknown",
895
947
  changed: "files the push changes, across every ref",
896
- outside: "the changed files no min-push path matches",
948
+ outside:
949
+ "the changed files no min-push path matches (an audit template changed only below its <!-- bkit:end --> is not listed)",
897
950
  paths:
898
- "the min-push pathspecs in force: ship's pr bookkeeping allow-list (with bkit.testing.ciSkipPaths), docs/plans/**, bkit.testing.minPushPaths",
951
+ "the min-push pathspecs in force: ship's pr bookkeeping allow-list (with bkit.testing.ciSkipPaths), docs/plans/**, docs/audits/**, bkit.testing.minPushPaths",
899
952
  },
900
953
  exitCodes: {
901
954
  [EXIT_RANGE_UNKNOWN]: "a pushed commit, its base, or its git diff could not be read",