@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
@@ -3,18 +3,17 @@
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** Every template bkit ships and never installs — what each does, where to copy it, how to install the tool behind it.
6
+ > **Purpose:** Every template bkit ships but never installs: what each one does, where to copy it, and how to install the tool behind it.
7
7
  >
8
8
  > **Rules:**
9
9
  >
10
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
- > - Describe current state / rules, not reasons / history; state what to do, not why.
12
- > - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy.
13
- > - Adapt app roots, workspace package scope, rules JSON. Examples use `apps/web`, `apps/mobile`, `packages/api`, `@scope`.
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - `bkit install` and `bkit upgrade` never write these files and never overwrite a copy, with one exception: they rewrite an adopted copy where bkit's exact shipped old text matches (the brand migrations, `docs/migrations.md`), never otherwise.
12
+ > - Adapt the app roots, the workspace package scope and the rules JSON. The examples use `apps/web`, `apps/mobile`, `packages/api` and `@scope`.
14
13
 
15
14
  ## What each template is for
16
15
 
17
- Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a repo shows a stack every worktree shares) → adopt it once a second worktree touches that stack. Sections below: install steps and traps.
16
+ The adoption order is the `bkit tips` order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
18
17
 
19
18
  <!-- prettier-ignore -->
20
19
  | Template | What it's for | Skip it and |
@@ -22,6 +21,7 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
22
21
  | direnv | Loads `.bkit/.env` tokens whenever the project opens. | Saved tokens never load; every sign-in fails while the file looks right. |
23
22
  | Serena | Agents look code up like an editor ("where is this defined, what uses it?"). Read-only. | Agents grep and read whole files: more accidental changes, more correction rounds, higher token cost. |
24
23
  | CI workflow + CI scripts | Runs every check on GitHub on every change; one capstone check gates merge; `/bkit-ship` waits for it. | "Shipped" means merged, not checked. |
24
+ | Health check | After CI promotes a release, probes production's health URL. | A release that went live broken stays unnoticed until a user reports it. |
25
25
  | Git hooks (Husky) | Same checks locally on commit and push, in seconds. | Failures surface minutes later in CI, after the agent moved on. |
26
26
  | Prettier ignore list | One formatting baseline; stops Prettier reformatting bkit's managed files. | Reviews fill with spacing noise; every bkit upgrade shows false changes. |
27
27
  | slop-scan | Flags net-new junk code AI tends to write (filler, dead code, type escapes). | Junk passes skim review and piles up. |
@@ -38,7 +38,7 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
38
38
  | Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
39
39
  | tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
40
40
  | Disk prune | Your own cleanup steps (build caches, Docker, simulators) run on commit, on push, and before a worktree is made on a low disk. bkit deletes nothing itself. | Caches fill the disk until no worktree can be made; every workflow stops. |
41
- | Local stack lock | One run at a time on local services every worktree shares (Docker database, emulator); a second run waits and names the run holding them. | A reset or stop from one worktree wipes the stack under another worktree's test run; the failures look like real bugs. |
41
+ | Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder. | Test gates compete for CPU, or a reset stops the stack under another worktree's test run. |
42
42
  | Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
43
43
  | Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
44
44
 
@@ -48,12 +48,13 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
48
48
  | Tool | Copy from | To | Output you commit |
49
49
  | --- | --- | --- | --- |
50
50
  | CI workflow | `.bkit/templates/.github/workflows/bkit-ci.yml` | `.github/workflows/bkit-ci.yml` | that file |
51
- | CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/resolve-push-base.mjs` + `.test.mjs`, CI's push base, also run by pre-push; `check-accepted-divergences.mjs` + `accepted-divergences.json`; `check-dependency-audit.mjs` + `accepted-advisories.json`). `check-capstone.mjs` + `check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
51
+ | CI scripts | `.bkit/templates/scripts/ci/` | `scripts/ci/` | the scripts you adopt (`lanes/bkit-resolve-push-base.mjs` + `.test.mjs`, CI's push base, also run by pre-push; `bkit-check-accepted-divergences.mjs` + `bkit-accepted-divergences.json`; `bkit-check-dependency-audit.mjs` + `bkit-accepted-advisories.json`, also run by pre-push). `bkit-check-capstone.mjs` + `bkit-check-capstone.test.mjs` are required with `bkit-ci.yml`, not optional |
52
+ | Health check | `.bkit/templates/.github/workflows/bkit-health.yml` | `.github/workflows/bkit-health.yml` | that file |
52
53
  | Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
53
54
  | Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
54
55
  | Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
55
56
  | lint-staged | `.bkit/templates/.lintstagedrc.json` | `.lintstagedrc.json` | that file |
56
- | Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/House/` | `.vale.ini`, `.vale/styles/House/` | `.vale.ini` + the four House styles |
57
+ | Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/Bkit/` | `.vale.ini`, `.vale/styles/Bkit/` | `.vale.ini` + the four Bkit styles |
57
58
  | slop-scan | `.bkit/templates/slop-scan.config.json`, `.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs` | `slop-scan.config.json`, `scripts/slop/bkit-slop-type-suppression.mjs` | both files |
58
59
  | Oxlint | `.bkit/templates/.oxlintrc.json` | `.oxlintrc.json` | that file |
59
60
  | direnv | `.bkit/templates/.envrc` | `.envrc` | that file |
@@ -70,89 +71,101 @@ Adoption order = `bkit tips` order. Local stack lock has no tip (nothing in a re
70
71
  | Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
71
72
  | tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
72
73
  | Disk prune | `.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs`, `bkit-disk-prune.machine.mjs` | `scripts/cleanup/bkit-disk-prune.mjs`, `~/.config/bkit/disk-prune.mjs` | `scripts/cleanup/bkit-disk-prune.mjs` only |
73
- | Local stack lock | `.bkit/templates/scripts/ci/bkit-local-stack-lock.sh` | `scripts/ci/` | that file |
74
+ | Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh` | `scripts/ci/` | that file |
75
+ | Local test sleep prevention | `.bkit/templates/scripts/ci/bkit-test-awake.mjs`, `bkit-test-awake.test.mjs` | `scripts/ci/` | both files |
74
76
  | Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
75
77
  | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
76
78
 
77
- Placeholders. Copies keep them raw; replace each in your copy:
79
+ Placeholders: the copies keep them raw, so replace each one in your copy:
78
80
 
79
81
  <!-- prettier-ignore -->
80
82
  | Placeholder | In | Put | Typical value |
81
83
  | --- | --- | --- | --- |
82
- | `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
84
+ | `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches), `bkit-health.yml` (`on.workflow_run` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
85
+ | `{{PRODUCTION_URL}}` | `bkit-health.yml` (`env.PRODUCTION_URL`) | the origin production serves | `https://example.com` |
83
86
  | `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
84
87
  | `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
85
- | `{{SCRIPT_PATH}}` | `ai.bkit.launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
86
- | `{{ENV_FILE}}` | `ai.bkit.launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
88
+ | `{{SCRIPT_PATH}}` | `bkit-launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
89
+ | `{{ENV_FILE}}` | `bkit-launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
87
90
 
88
91
  - `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
89
- - **What changed on upgrade.** `bkit upgrade` lists changed / added / removed template paths. For each one you adopted: `diff .bkit/templates/<path> <path>`, merge what you want (placeholder lines differ by design). `git diff .bkit/templates` in the upgrade commit = the package change.
90
- - Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) → ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do; check your adopted copy does too.
91
- - Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python + shell launchers; git hooks: POSIX `sh`; local stack lock: bash + perl, as shell runners source it).
92
- - `bkit.depUpdater: "none"` → skips install-time absence advisory for updaters.
93
- - No manifest key for any template. `docs/templates/bkit-audit-adoption.md` lists every template each run: adopted and wired, or not adopted and why.
92
+ - **What changed on upgrade.** `bkit upgrade` lists the changed, added and removed template paths. For each one you adopted, run `diff .bkit/templates/<path> <path>`, and merge what you want. The placeholder lines differ by design. `git diff .bkit/templates` in the upgrade commit shows the package change.
93
+ - Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do. Check that your adopted copy does too.
94
+ - Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python and shell launchers; git hooks: POSIX `sh`; local stack lock: bash and perl, because shell runners source it).
95
+ - `bkit.dependencies.updater` names the adopted updater (`"renovate"` / `"dependabot"`). Install fills it from the config present. `"none"` skips the install-time absence advisory. `bkit check` blocks when the setting and the configs disagree.
96
+ - No template has a manifest key. `docs/templates/bkit-audit-adoption.md` lists every template on each run, as adopted and wired, or as not adopted with the reason.
94
97
 
95
98
  ## Context-fetch blocks — `.agents/context.md`
96
99
 
97
- `/bkit-debug` runs every `context-fetch` block below `<!-- bkit:end -->` in `.agents/context.md`; cloud setup runs every `context-fetch:provision` block there. One file per provider holds its fetch blocks (one per context; copy one or more), each fetch block's provision block (stack CLI only), the `allowed-domains` it needs beyond bkit's derived egress set, and its `mcp-servers` names. Block rules (markers, contexts, self-skip, output bounds) → the managed block of `.agents/context.md`.
100
+ `/bkit-debug` runs every `context-fetch` block below `<!-- bkit:end -->` in `.agents/context.md`, and cloud setup runs every `context-fetch:provision` block there. Each provider has one file, which holds:
101
+
102
+ - its fetch blocks, one per context, of which you copy one or more
103
+ - each fetch block's provision block (stack CLI only)
104
+ - the `allowed-domains` it needs beyond bkit's derived egress set
105
+ - its `mcp-servers` names
106
+
107
+ The block rules (markers, contexts, self-skip, output bounds) are in the managed block of `.agents/context.md`. Each fetch block bounds its own output at the source, with a window, a severity / level filter, a row / line cap, a page cap or a per-lane tail, because everything it prints is written into an artifact that an agent then reads. A block that bounds nothing downloads a whole-run dump, and only the post-hoc clamp catches it (`bkit check` advises, `context-fetch-unbounded`).
108
+
109
+ For selected CI, `context fetch --ci-selection-file` supplies the four `BKIT_CI_*` identity inputs listed below and validates the `bkit-ci-evidence` receipt defined in `.agents/context.md`. The receipt follows complete metadata, job and log reads; empty, partial or mismatched evidence stays unchecked. An unpinned block discovers its own source. Consumer-owned blocks remain unchanged on upgrade; Debug adapts a temporary script for the selected identity.
98
110
 
99
111
  <!-- prettier-ignore -->
100
112
  | File | Fits | `context=` | Fetches | Secret / non-secret env | Domains | CLI (provision) |
101
113
  | --- | --- | --- | --- | --- | --- | --- |
102
- | `github.md` | GitHub Actions | `ci`, `diff` | `ci`: failing run: failed jobs / steps, `::error` annotations, failed-step logs tail-bounded per failed job; `diff`: `git diff --stat` (capped) since the last green CI run on trunk | `GH_TOKEN` / `CI_LOG_TAIL`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
103
- | `playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
104
- | `maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
105
- | `tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
106
- | `sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
107
- | `vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
108
- | `supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
109
- | `stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
110
- | `resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
111
- | `inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window, paged; error class only, never error text | `INNGEST_SIGNING_KEY` / `INNGEST_ENV` (required with a branch key), `SINCE_ISO`, `UNTIL_ISO`, `INNGEST_N`, `INNGEST_MAX_PAGES` | `inngest.com` | — |
112
- | `cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills; service account only when the gcloud login cannot mint a token | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE`, `GCP_FILTER` | `googleapis.com`, `google.com` | `gcloud` (yes) |
113
- | `expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: newest 50 builds' status + errored-build log lines (capped per build); `e2e`: recent and FAILURE run lists, failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_N`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_WF_N`, `EAS_WF_FAIL_N`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
114
- | `serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
115
-
116
- MCP names listed: `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest`, `serena`. Every tool on a listed server runs without a prompt, writes included — list only servers you trust with that.
117
-
118
- Placeholders. Each sits on a commented assignment line or an env default in the block; replace it in your copy:
114
+ | `bkit-github.md` | GitHub Actions | `ci`, `diff` | `ci`: exact selected run/attempt, complete identity receipt and bounded logs for every failed job; `diff`: selected failing commit against an ancestral same-workflow green baseline | `GH_TOKEN` / `CI_LOG_TAIL`; optional `BKIT_CI_RUN_ID`, `BKIT_CI_RUN_ATTEMPT`, `BKIT_CI_REPO`, `BKIT_CI_HEAD_SHA`; configured `bkit.testing.ciWorkflow`; `BASELINE_BRANCH`, `BASELINE_WORKFLOW`, `DIFF_STAT_N` (`diff`) | — | `gh` (base tool) |
115
+ | `bkit-playwright.md` | Playwright on GitHub Actions | `e2e` | failing run's report artifact, failing specs first; inlined files, lines and binary paths capped | `GH_TOKEN` / `E2E_ARTIFACT`, `E2E_JOB_RE`, `E2E_MAX_FILES`, `E2E_MAX_LINES`, `E2E_MAX_BIN` | — | `gh` (base tool) |
116
+ | `bkit-maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
117
+ | `bkit-tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
118
+ | `bkit-sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
119
+ | `bkit-vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
120
+ | `bkit-supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
121
+ | `bkit-stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
122
+ | `bkit-resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
123
+ | `bkit-inngest.md` | Inngest Cloud | `runtime` | `inngest/function.failed` events in a window, paged; error class only, never error text | `INNGEST_SIGNING_KEY` / `INNGEST_ENV` (required with a branch key), `SINCE_ISO`, `UNTIL_ISO`, `INNGEST_N`, `INNGEST_MAX_PAGES` | `inngest.com` | — |
124
+ | `bkit-cloudrun.md` | Google Cloud Run | `runtime` | container errors + memory-limit kills; service account only when the gcloud login cannot mint a token | `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY` (headless) / `GCP_PROJECT_ID`, `GCP_SERVICE`, `GCP_FILTER` | `googleapis.com`, `google.com` | `gcloud` (yes) |
125
+ | `bkit-expo.md` | Expo EAS Build + EAS Workflows (Maestro) | `runtime`, `e2e` | `runtime`: newest 50 builds' status + errored-build log lines (capped per build); `e2e`: recent and FAILURE run lists, failed jobs' per-flow exceptions, JUnit (capped), screenshots, Maestro commands, hierarchy dumps, XCUITest + JS console | `EXPO_TOKEN` / `EXPO_APP_DIR`, `EAS_PLATFORM`, `EAS_PROFILE`, `EAS_N`, `EAS_LOG_N` (`runtime`); `EAS_WF_FILE`, `EAS_WF_N`, `EAS_WF_FAIL_N`, `EAS_JUNIT_N` (`e2e`) | `expo.dev`, `googleapis.com` (`runtime`), `eascdn.net` (`e2e`) | `eas` (yes) |
126
+ | `bkit-serena.md` | Serena MCP server | — | nothing: provision only, installs `serena` in cloud | — | — | `uv` (yes) |
127
+
128
+ The MCP names these files list are `sentry` / `Sentry`, `vercel` / `Vercel`, `supabase` / `Supabase`, `inngest` and `serena`. Every tool on a listed server runs without a prompt, writes included, so list only servers you trust with that.
129
+
130
+ Placeholders: each one sits on a commented assignment line or an env default in the block. Replace it in your copy:
119
131
 
120
132
  <!-- prettier-ignore -->
121
133
  | Placeholder | In | Put |
122
134
  | --- | --- | --- |
123
- | `your-team-slug` | `vercel.md` (`VERCEL_SCOPE`) | Vercel team slug |
124
- | `your-project-ref` | `supabase.md` (`SUPABASE_PROJECT_ID`) | project ref of the environment whose logs you want |
125
- | `your-org-slug`, `your-project-slug` | `sentry.md` (`SENTRY_ORG`, `SENTRY_PROJECT`) | Sentry slugs |
126
- | `de.sentry.io` (commented) | `sentry.md` (`SENTRY_HOST`) | uncomment for an EU-region org; default `sentry.io` |
127
- | `your-gcp-project-id`, `your-service-name` | `cloudrun.md` (`GCP_PROJECT_ID`, `GCP_SERVICE`) | GCP project id; optional service name |
128
- | `^your-e2e-job-name$` | `playwright.md` (`E2E_JOB_RE`) | anchored job name of that lane only |
129
- | `^your-maestro-e2e-job-name$`, `Your per-flow results step\|Your failure classification step` | `maestro.md` (`MAESTRO_JOB_RE`, `MAESTRO_STEPS`) | anchored regex matching the Maestro lanes' job names; `\|`-separated names of the steps that print results |
130
- | `dev`, `bkit-ci.yml` | `github.md` `context=diff` (`BASELINE_BRANCH`, `BASELINE_WORKFLOW`) | trunk branch, CI workflow file |
131
- | `apps/mobile` | `expo.md`, both blocks (`EXPO_APP_DIR`) | the EAS-linked app folder |
132
- | `serena-agent==1.7.0` | `serena.md` | the Serena version you run locally |
135
+ | `your-team-slug` | `bkit-vercel.md` (`VERCEL_SCOPE`) | Vercel team slug |
136
+ | `your-project-ref` | `bkit-supabase.md` (`SUPABASE_PROJECT_ID`) | project ref of the environment whose logs you want |
137
+ | `your-org-slug`, `your-project-slug` | `bkit-sentry.md` (`SENTRY_ORG`, `SENTRY_PROJECT`) | Sentry slugs |
138
+ | `de.sentry.io` (commented) | `bkit-sentry.md` (`SENTRY_HOST`) | uncomment for an EU-region org; default `sentry.io` |
139
+ | `your-gcp-project-id`, `your-service-name` | `bkit-cloudrun.md` (`GCP_PROJECT_ID`, `GCP_SERVICE`) | GCP project id; optional service name |
140
+ | `^your-e2e-job-name$` | `bkit-playwright.md` (`E2E_JOB_RE`) | anchored job name of that lane only |
141
+ | `^your-maestro-e2e-job-name$`, `Your per-flow results step\|Your failure classification step` | `bkit-maestro.md` (`MAESTRO_JOB_RE`, `MAESTRO_STEPS`) | anchored regex matching the Maestro lanes' job names; `\|`-separated names of the steps that print results |
142
+ | `dev`, `bkit-ci.yml` | `bkit-github.md` `context=diff` (`BASELINE_BRANCH`, `BASELINE_WORKFLOW`) | trunk branch, CI workflow file |
143
+ | `apps/mobile` | `bkit-expo.md`, both blocks (`EXPO_APP_DIR`) | the EAS-linked app folder |
144
+ | `serena-agent==1.7.0` | `bkit-serena.md` | the Serena version you run locally |
133
145
 
134
146
  Adopt:
135
147
 
136
- 1. Copy the file's blocks below `<!-- bkit:end -->` in `.agents/context.md`: each fetch block you want, its provision block, its `allowed-domains` and `mcp-servers` blocks (several of each merge).
148
+ 1. Copy the file's blocks below `<!-- bkit:end -->` in `.agents/context.md`: each fetch block you want, its provision block, and its `allowed-domains` and `mcp-servers` blocks. Several blocks of each kind merge.
137
149
  2. Replace the placeholders. Commit non-secret selectors inline so cloud agents inherit them.
138
150
  3. Set the secret env vars locally (app env via `.envrc`, not `.bkit/.env`) and in each cloud dashboard (`.bkit/cloud.md`).
139
- 4. `bkit install` → the provision recipes reach `.claude/bkit-cloud.md`'s setup script, the domains reach the cloud allowlist and local fetch permissions, the MCP names reach every host's allow rules.
151
+ 4. Run `bkit install`. The provision recipes reach `.claude/bkit-cloud.md`'s setup script and `.codex/bkit-cloud.md`'s install script (`.cursor/environment.json` `install` and the Claude session hook run them through `bkit context provision`). The domains reach the cloud allowlist and the local fetch permissions, and the MCP names reach every host's allow rules.
140
152
 
141
- - No credentials, or an API / auth error → block self-skips: `exit 0` plus `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean. `TRUNCATED` on stdout = page cap or a failed later page stopped the read; raise the block's `*_MAX_PAGES` knob.
142
- - Runtime and EAS blocks' `# Customise:` suggests a positive control: run once over a window holding a known event; nothing back = reader broken, not clean.
143
- - `bkit check` advisories point at these files: `context-fetch-missing`, `context-fetch-context-missing`, `context-fetch-source-not-enabled`, `context-fetch-provision-missing`.
144
- - Another backend → author a block in the same shape (rules in the managed block of `.agents/context.md`).
153
+ - **If** credentials are missing, or the block hits an API / auth error → it self-skips with `exit 0` and `[context-fetch:<name>] skipped — …` on stderr. `/bkit-debug` narrates that as not checked, never as clean.
154
+ - `TRUNCATED` on stdout means the page cap or a failed later page stopped the read. Raise the block's `*_MAX_PAGES` knob.
155
+ - The `# Customise:` note in the runtime and EAS blocks suggests a positive control: run the block once over a window that holds a known event. Nothing back means the reader is broken, not that the source is clean.
156
+ - `bkit check` advisories point at these files: `context-fetch-missing`, `context-fetch-context-missing`, `context-fetch-source-not-enabled`, `context-fetch-provision-missing`, `context-fetch-unbounded`.
157
+ - For another backend, author a block in the same shape. The rules are in the managed block of `.agents/context.md`.
145
158
 
146
159
  ## Gate tool scripts — `package.json`
147
160
 
148
- bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The tool scripts their defaults chain are yours; `gate-missing-called-scripts` names any that are missing.
161
+ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names, and adds each one only if it is missing. The tool scripts their defaults chain are yours, and `gate-missing-called-scripts` names any that are missing.
149
162
 
150
163
  <!-- prettier-ignore -->
151
164
  | Gate (default) | Chains | Needs |
152
165
  | --- | --- | --- |
153
166
  | `bkit:gate:format` | `pnpm lint-staged` | lint-staged devDep + `.lintstagedrc.json` + prettier |
154
- | `bkit:gate:min` | `format:check`, `lint:prose`, `slop:delta` | the scripts below + any test reading a min-push file |
155
- | `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` | the scripts below |
167
+ | `bkit:gate:min` | `format:check`, `bkit:lint:prose`, `bkit:slop:delta` | the scripts below + any test reading a min-push file |
168
+ | `bkit:gate:static` | `typecheck`, `lint`, `format:check`, `bkit:lint:prose`, `bkit:slop:delta` | the scripts below |
156
169
  | `bkit:gate:static-unit` | `bkit:gate:static` + `test` | a `test` script |
157
170
  | `bkit:gate:install-static-unit-build` | `pnpm install --frozen-lockfile` + `bkit:gate:static-unit` + `build` | a `build` script |
158
171
 
@@ -161,9 +174,9 @@ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The to
161
174
  "typecheck": "tsc --noEmit",
162
175
  "lint": "oxlint -c .oxlintrc.json --type-aware --deny-warnings",
163
176
  "format:check": "prettier --check .",
164
- "lint:prose": "bkit ci prose",
177
+ "bkit:lint:prose": "bkit ci prose",
165
178
  "lint:slop": "slop-scan scan .",
166
- "slop:delta": "bkit ci slop",
179
+ "bkit:slop:delta": "bkit ci slop",
167
180
  "prepare": "husky"
168
181
  }
169
182
  ```
@@ -172,36 +185,109 @@ bkit seeds only the `bkit:gate:*` / `bkit:deps:*` names (add-if-missing). The to
172
185
  pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
173
186
  ```
174
187
 
175
- - `lint` must exist: without it `pnpm lint` falls through to any `lint` binary on `PATH` → gate green via the wrong program. Value above runs the Oxlint test rules (§ Oxlint), fails on any hit; needs `oxlint` + `oxlint-tsgolint`, fails loudly without them. Own linter → chain both: `<your linter> && oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
176
- - No `tsconfig.json` → `"typecheck": "echo \"[bkit] typecheck: no tsconfig.json — skipping\" >&2"`.
177
- - `slop:delta` runs `bkit ci slop` (bkit devDep on `PATH` through the package script). CI passes the base sha as its one bare argument.
178
- - `lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), e.g. `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
179
- - Non-Node stack → point each gate at your own commands; keep the gate names.
180
- - `bkit:test:file` (not seeded; `test-file-script-missing` until declared) runs ONE test file — bkit appends its repo-relative path — and writes a JUnit report to `$BKIT_TEST_REPORT`; `/bkit-build` reads it for test-first. Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`. Call the runner directly, not through a caching task runner.
188
+ - `lint` must exist. Without it, `pnpm lint` falls through to any `lint` binary on `PATH`, and the gate goes green through the wrong program.
189
+ - The value above runs the Oxlint test rules (§ Oxlint) and fails on any hit. It needs `oxlint` and `oxlint-tsgolint`, and fails loudly without them.
190
+ - **If** you have your own linter → chain both: `<your linter> && oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
191
+ - **If** there is no `tsconfig.json` → use `"typecheck": "echo \"[bkit] typecheck: no tsconfig.json — skipping\" >&2"`.
192
+ - `bkit:slop:delta` runs `bkit ci slop` (the bkit devDep is on `PATH` through the package script). CI passes the base sha as its one bare argument.
193
+ - `bkit:lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with the repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), for example `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
194
+ - **If** the stack is not Node → point each gate at your own commands, and keep the gate names.
195
+ - `bkit:test:file` runs one test file and writes a JUnit report to `$BKIT_TEST_REPORT`. bkit appends the file's repo-relative path. `/bkit-build` reads the report for test-first. It is not seeded, and `test-file-script-missing` fires until it is declared.
196
+ - Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`.
197
+ - Call the runner directly, not through a caching task runner.
198
+ - `bkit:lint:file` lints one test file with the static gate's rules, and exits 0 when clean. bkit appends the path. `bkit tests red` runs it on each planned test file before running the file, and records a `lint` gap for the file's tests while it fails. It is not seeded, and `lint-file-script-missing` fires once `bkit:test:file` is declared without it.
199
+ - ESLint: `"bkit:lint:file": "eslint --max-warnings=0"`.
200
+ - Ruff: `"bkit:lint:file": "ruff check"`.
201
+ - `bkit:gate:changed` checks only the files an agent step changed: the tests that import them, the tests that name their paths, and static checks on them; exit 0 when clean. `bkit tests changed` appends the repo-relative paths and never calls it with none. It is not seeded, and `gate-changed-script-missing` fires until it is declared; undeclared, agents run the whole `bkit:gate:static` / `bkit:gate:static-unit` instead.
202
+ - Vitest + ESLint: a script running `vitest related --run "$@" && eslint --max-warnings=0 --no-error-on-unmatched-pattern "$@"`, plus a text search of the test files for each path.
203
+
204
+ ## Local test sleep prevention
205
+
206
+ Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
207
+
208
+ ```json
209
+ {
210
+ "bkit:test:unit": "node scripts/ci/bkit-test-awake.mjs vitest run",
211
+ "bkit:test:file": "node scripts/ci/bkit-test-awake.mjs vitest run",
212
+ "bkit:gate:static-unit": "node scripts/ci/bkit-test-awake.mjs --shell \"pnpm bkit:gate:static && pnpm bkit:test:unit\""
213
+ }
214
+ ```
215
+
216
+ Keep each script's existing runner flags and report settings when adding the prefix. Run the wrapper's tests with `node --test scripts/ci/bkit-test-awake.test.mjs`. For a direct runner invocation, use `node scripts/ci/bkit-test-awake.mjs pnpm exec vitest run path/to/example.test.ts`.
217
+
218
+ On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. Keep the lid open; `docs/testing.md` § Local test sleep prevention describes the limits.
219
+
220
+ `bkit tests` already protects the commands it launches using the packaged wrapper. Adopt this template for direct scripts and hooks. Existing consumer-owned scripts are not rewritten on upgrade.
181
221
 
182
222
  ## CI workflow — `bkit-ci.yml`
183
223
 
184
- Parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actionlint, `bkit check`) and `bkit-tests-unit`, joined by the `bkit-tests-check` capstone, plus the commented full CI scaffold reference for the other tiers. Workflows care: `/bkit-ship` waits on its runs and merges only when the `bkit.capstoneJob` job (default `bkit-tests-check`) is present and green at the head; `bkit setup protect-main` makes that job the required check; `bkit-cloud.yml` triggers on a workflow named `bkit-ci`. `bkit install` reads your copy for advisories (`bkit-stub-*`, `ci-yml-missing-actionlint`, `ci-yml-capstone-contract-drift`). Reference: https://docs.github.com/en/actions.
224
+ The parallel lanes `bkit-tests-static` (typecheck, lint, prettier, Vale, slop, actionlint, `bkit check`, pinned checksums) and `bkit-tests-unit` are joined by the `bkit-tests-check` capstone. The file also carries the commented full CI scaffold reference for the other tiers. Reference: https://docs.github.com/en/actions.
225
+
226
+ Workflows care about it:
227
+
228
+ - `/bkit-ship` waits on its runs, and merges only when the `bkit.testing.ciCapstone` job (default `bkit-tests-check`) is present and green at the head.
229
+ - `bkit setup protect-main` makes that job the required check.
230
+ - `bkit-cloud.yml` triggers on a workflow named `bkit-ci`.
231
+ - `bkit install` reads your copy for advisories (`bkit-stub-*`, `ci-yml-missing-actionlint`, `ci-yml-capstone-contract-drift`).
185
232
 
186
- - Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json` (`pnpm/action-setup` reads it; do not add `with: version:`).
187
- - Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`. Non-Node repo → replace the Node / pnpm setup, install and check steps with your stack's.
188
- - Capstone: `bkit-tests-check` `needs:` every lane and runs on `!cancelled()`, never `always()`. Each lane you adopt from the reference goes into its `needs:` and its assert, or that lane's failure cannot red the merge. Its assert is `scripts/ci/check-capstone.mjs` (copy it and `check-capstone.test.mjs` from `.bkit/templates/scripts/ci/` with the workflow; REQUIRED — the step reds with a copy-the-script message when the file is missing, and never skips). The script reds on a lane that did not succeed, a lane that ran when the plan said skip, a lane that succeeded with 0 tests or a non-numeric count, and a plan that does not parse. It reads each lane's executed-test count once the lane writes one (the `Run Unit Tests` step comment shows the vitest form); `EMPTY_COUNT: warn` makes an unreported count a warning, a count of 0 a failure. Each lane you adopt goes into `LANES` and its `<LANE>_RESULT` / `<LANE>_RAN` variables. Renaming the job → set `bkit.capstoneJob`.
233
+ Setup:
234
+
235
+ - Install: nothing beyond the gate tool scripts above, a `test` script, and `packageManager` in `package.json`. `pnpm/action-setup` reads it, so do not add `with: version:`.
236
+ - Adapt: `{{DEFAULT_BRANCH}}`, `{{NODE_VERSION}}`.
237
+ - **If** the repo is not Node → replace the Node / pnpm setup, install and check steps with your stack's.
238
+ - Capstone: `bkit-tests-check` `needs:` every lane, and runs on `!cancelled()`, never `always()`.
239
+ - Each lane you adopt from the reference goes into its `needs:` and its assert. Otherwise that lane's failure cannot red the merge.
240
+ - Its assert is `scripts/ci/bkit-check-capstone.mjs`. Copy it and `bkit-check-capstone.test.mjs` from `.bkit/templates/scripts/ci/` with the workflow. The script is required: when the file is missing, the step reds with a copy-the-script message, and it never skips.
241
+ - The script reds on a lane that did not succeed, a lane that ran when the plan said skip, a lane that succeeded with 0 tests or a non-numeric count, and a plan that does not parse.
242
+ - It reads each lane's executed-test count once the lane writes one. The `Run Unit Tests` step comment shows the vitest form. `EMPTY_COUNT: warn` makes an unreported count a warning, and a count of 0 a failure.
243
+ - Each lane you adopt goes into `LANES` and its `<LANE>_RESULT` / `<LANE>_RAN` variables.
244
+ - **If** you rename the job → set `bkit.testing.ciCapstone`.
189
245
  - Adopt a scaffold lane only when its tier exists (`docs/testing.md`). Each `# bkit-stub:<id> —` header raises an install advisory until you enable or delete that stub.
190
- - Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and set `bkit.ciWorkflow` to the new file name.
191
- - Keep `fetch-depth: 0` on the static lane: `slop:delta` checks the PR base out as a worktree.
246
+ - Keep the `name: bkit-ci` line, or rename `workflows: [bkit-ci]` in `bkit-cloud.yml` and `bkit-health.yml` and set `bkit.testing.ciWorkflow` to the new file name.
247
+ - Keep `fetch-depth: 0` on the static lane, because `bkit:slop:delta` checks the PR base out as a worktree.
248
+ - **If** CI script copies are named without the `bkit-` prefix (`check-capstone.mjs`, `accepted-advisories.json`, …) → the `bkit check` advisory `ci-scripts-old-names` lists each rename.
249
+ - Rename a file and its paths in `.github/workflows/*.yml`, `.husky/pre-push` and `scripts/ci/` in one commit, because the `Check Dependency Audit` step is guarded by `hashFiles` and skips silently when only the file moved.
250
+
251
+ ## Health check — `bkit-health.yml`
252
+
253
+ It probes production after every finished `bkit-ci` run on the default branch, green or red, because `bkit-tests-deploy` promotes before the E2E and `@live` lanes run, so a red run can still have put a release live. The `bkit-health-promoted` job asks the host which commit production serves. The `bkit-health` job probes the health URL only when that commit is the run's own, and shows as skipped otherwise. It is not a required check. It fits a deploy that `bkit-ci` promotes. When the host deploys on its own after merge, trigger on `deployment_status` instead (`docs/deployments.md` § Smoke trigger plumbing).
254
+
255
+ - Install: the secrets `VERCEL_TOKEN` and `VERCEL_TEAM_ID`, the same ones the CI scaffold's Vercel lanes read.
256
+ - **If** you use another host → replace `Did This Run Promote?` with a call to its API that prints the commit production serves.
257
+ - Adapt: `{{DEFAULT_BRANCH}}`, `{{PRODUCTION_URL}}`, and `HEALTH_PATH` (default `/api/health`).
258
+ - The promote check fails when the host's answer cannot be read, because a skipped probe would look green.
259
+ - The probe retries for up to 240 seconds, because a release the host reports as live can still be warming up.
260
+ - The probe checks only for a 200. Check the body your endpoint returns too, so an error page that answers 200 fails.
261
+ - More probes (a curl script over key routes, a small tagged browser suite) go in as further steps of the `bkit-health` job. A step that runs a repo script needs `actions/checkout` with `ref: ${{ github.event.workflow_run.head_sha }}` first.
262
+ - One health workflow per repo: keep any other post-deploy probe as a step here, not as a second workflow.
192
263
 
193
264
  ## Cloud-agent workflow — `bkit-cloud.yml`
194
265
 
195
- Post-CI router: CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`; failed `dev` CI → `/bkit-debug {FID}`; `workflow_dispatch` runs any phase. A `context` job resolves phase + arg once, then two runner jobs, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). Runs bkit workflows; `bkit install --auto=claude|opencode` points at it. Full recipe: `.bkit/cloud.md` § Post-CI auto-routing.
266
+ A post-CI router that runs bkit workflows:
267
+
268
+ - CI pass on `feat/**` → `/bkit-ship`, fail → `/bkit-debug`.
269
+ - Failed `dev` CI → `/bkit-debug {FID}`.
270
+ - `workflow_dispatch` runs any phase.
271
+
272
+ A `context` job resolves the phase and argument once. Then two runner jobs follow, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). `bkit install --auto=claude|opencode` points at this file. The full recipe is in `.bkit/cloud.md` § Post-CI auto-routing.
196
273
 
197
274
  - Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template) or `--auto=opencode` (needs `--opencode=<provider>` first). Both need `--tracker=github`.
198
- - Secrets: `ANTHROPIC_API_KEY` (or keyless: `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables) + the Claude GitHub App (`/install-github-app`) for `claude`; `OPENCODE_PROVIDER_KEY` for `opencode`. Repo Actions permissions: read and write, PR creation allowed.
275
+ - Secrets for `claude`: `ANTHROPIC_API_KEY`, or keyless with the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables, plus the Claude GitHub App (`/install-github-app`).
276
+ - Secrets for `opencode`: `OPENCODE_PROVIDER_KEY`.
277
+ - Repo Actions permissions: read and write, with PR creation allowed.
199
278
  - Adapt: `{{CLOUD_RUNNER}}` in all three jobs.
200
- - Traps: the file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade` — diff it on every upgrade. The opencode install version is a plain argument; the `# renovate:` comment above it lets the example `renovate.json5` bump it. Keep the file out of updater `ignorePaths` so action pins refresh.
279
+ - Traps:
280
+ - The file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade`. Diff it on every upgrade.
281
+ - The OpenCode install version is a plain argument. The `# renovate:` comment above it lets the example `renovate.json5` bump it.
282
+ - Keep the file out of the updater's `ignorePaths` so action pins refresh.
201
283
 
202
284
  ## Git hooks — Husky
203
285
 
204
- `pre-commit` runs `bkit:gate:format`; `pre-push` runs `bkit check` first, so a drifted install fails in seconds, then `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push), plus the CI-suppressing-token guards and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune). Workflows care: they commit and push without `--no-verify`, so a failing hook stops a workflow. One exception: the throwaway `.worktrees/_land-{FID}` checkout that lands bookkeeping on `dev` (docs, logs, ledgers, `[skip ci]`) runs no hooks and logs that it skipped them. Reference: https://typicode.github.io/husky/.
286
+ `pre-commit` runs `bkit:gate:format`. `pre-push` runs `bkit check` first, so a drifted install fails in seconds. Then it runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push). It also runs the CI-suppressing-token guards, the dependency audit (§ Dependency audit) and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune).
287
+
288
+ Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log.
289
+
290
+ Workflows care because they commit and push without `--no-verify`, so a failing hook stops a workflow. The throwaway `.worktrees/_land-{FID}` checkout runs its selected gate explicitly before pushing, with hooks disabled (§ One landing routine in `.bkit/workflows.md`). Reference: https://typicode.github.io/husky/.
205
291
 
206
292
  ```bash
207
293
  pnpm add -D husky@^9.1.7 # plus "prepare": "husky" (§ Gate tool scripts)
@@ -210,13 +296,35 @@ chmod +x .husky/pre-commit .husky/pre-push
210
296
 
211
297
  - `.gitignore`: `.husky/_` (bkit's `.gitignore` block already lists it).
212
298
  - Adapt: repo-only checks go below the bkit lines in each hook. What a gate runs belongs in the `bkit:gate:*` script, not the hook.
213
- - Min push: every file changed since each pushed commit left `origin/dev` (else `origin/main`) matches `bkit.minPushPaths` (`package.json` globs: `*` one folder, `**` any depth; default `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl`; `[]` = off) → `bkit:gate:min` replaces the full gate; `MIN_PUSH=1`. `bkit ci min-push` decides from files, never `[skip ci]` (a typed label; GitHub reads the last commit only). No files / unreadable range / no ref list → full gate.
214
- - Min-push paths: files no code, build or test reads. Never `docs/**` (a doc can be test input). A test reading a ledger → into `bkit:gate:min`.
215
- - `[skip ci]` guards: feature branch → blocked only while a PR is open (workflows push `[skip ci]` code heads mid-run). `dev` / `main` → blocked unless a min push: GitHub skips CI for the whole push.
216
- - Slop base: `dev` push + `scripts/ci/lanes/resolve-push-base.mjs` copied → the hook runs it with `--local --branch=dev --head=<pushed sha>` and exports `SLOP_BASE_REF` = CI's push base (head of the last green CI push run on `dev`, else `origin/dev`), printing the base and its source. Pre-push and CI slop then share a base, so a finding an earlier red push landed fails locally too. Run lookup fails (`gh` missing, logged out) → loud `WARNING`, base `origin/dev`, push goes on. Other branches, or no copy → `bkit ci slop` merge-base default. A repo-owned pre-push check that diffs against CI's base (migration immutability) reads `SLOP_BASE_REF` when set.
217
- - Slow repo extras (Docker, database, build) → wrap in `if [ "$MIN_PUSH" != "1" ]; then … fi`.
218
- - Traps: hooks run on every workflow commit; keep them to seconds (pre-commit) and deterministic checks that reach no deployed service (pre-push). Integration runs at pre-push once `bkit:gate:static-unit-integration` is declared (a local database in Docker is fine); E2E and `@live` belong in CI.
219
- - Run each check once: nothing in `bkit:gate:format` that the push gate runs again (`gate-commit-repeats-push` advisory), and `pnpm test` (the unit tier) matches no `*.integration.test.*` file — a unit config with no integration exclude runs those tests in the unit gate and again in the integration gate.
299
+ - Min push:
300
+ - **If** every file changed since each pushed commit left `origin/dev` (else `origin/main`) is one bkit writes or one `bkit.testing.minPushPaths` adds → `bkit:gate:min` replaces the full gate, and `MIN_PUSH=1`.
301
+ - The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed.
302
+ - `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
303
+ - What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` — 14 steps) plus `docs/plans/**`.
304
+ - The setting takes `package.json` globs: `*` matches one folder and `**` any depth. The default is `[]`, which leaves what bkit writes alone, because the setting only adds to it.
305
+ - `bkit ci min-push` decides from files, never from `[skip ci]`, because that is a typed label and GitHub reads the last commit only.
306
+ - Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch can still qualify from its complete bookkeeping-only branch diff.
307
+ - Min-push paths: list only files that no code, build or test reads.
308
+ - Never list `docs/**`, because a doc can be test input.
309
+ - **If** a test reads a ledger → put that test into `bkit:gate:min`.
310
+ - `[skip ci]` guards:
311
+ - On a feature branch, the push is blocked only while a PR is open, because workflows push `[skip ci]` code heads mid-run.
312
+ - With a PR open, `bkit ci bookkeeping-push --from=<remote head>` lets the push through when every file changed since the head the remote holds is on ship's `--scope=pr` allow-list. Such a push adds nothing that CI has not tested at that head.
313
+ - A rewritten head or a code file still blocks.
314
+ - On `dev` / `main`, the skip-CI check uses the complete branch diff, independently of local gate receipts. Code cannot skip CI merely because its local gate passed.
315
+ - Slop base:
316
+ - **If** the push is to `dev` **and** `scripts/ci/lanes/bkit-resolve-push-base.mjs` is copied → the hook runs it with `--local --branch=dev --head=<pushed sha>`, and exports `SLOP_BASE_REF` as CI's push base. That base is the head of the last green CI push run on `dev`, else `origin/dev`. The hook prints the base and its source.
317
+ - Pre-push and CI slop then share a base, so a finding that an earlier red push landed fails locally too.
318
+ - **If** the run lookup fails (`gh` missing, logged out) → the hook prints a loud `WARNING`, uses the base `origin/dev`, and the push goes on.
319
+ - **If** the branch is another branch, or there is no copy → `bkit ci slop` uses its merge-base default.
320
+ - A repo-owned pre-push check that diffs against CI's base (migration immutability) reads `SLOP_BASE_REF` when it is set.
321
+ - **If** the repo has slow extras (Docker, database, build) → wrap them in `if [ "$MIN_PUSH" != "1" ]; then … fi`.
322
+ - Traps:
323
+ - Hooks run on every workflow commit. Keep pre-commit to seconds, and keep pre-push to deterministic checks that reach no deployed service.
324
+ - Integration runs at pre-push once `bkit:gate:static-unit-integration` is declared. A local database in Docker is fine. E2E and `@live` belong in CI.
325
+ - Run each check once:
326
+ - Put nothing in `bkit:gate:format` that the push gate runs again (`gate-commit-repeats-push` advisory).
327
+ - `pnpm test` (the unit tier) must match no `*.integration.test.*` file. A unit config with no integration exclude runs those tests in the unit gate and again in the integration gate.
220
328
 
221
329
  ## Prettier — `.prettierignore` first
222
330
 
@@ -224,41 +332,47 @@ chmod +x .husky/pre-commit .husky/pre-push
224
332
  pnpm add -D prettier@^3.5.3
225
333
  ```
226
334
 
227
- 1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example`, `docs/roadmap.md` in its own layout; prettier reformatting them fights the next `bkit install` (`bkit check` drift).
335
+ 1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
228
336
  2. Add `format:check` (§ Gate tool scripts). Reference: https://prettier.io/docs/install.
229
337
 
230
338
  - Keep the `.bkit/templates/` line.
339
+ - Keep the three `docs/plans/*/logs/*/` gate-log lines: build and debug commit raw `bkit tests run` output there, and `format:check` fails on it.
231
340
 
232
341
  ## lint-staged — `.lintstagedrc.json`
233
342
 
234
- Runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
343
+ It runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
235
344
 
236
345
  ```bash
237
346
  pnpm add -D lint-staged@^17.0.0 prettier@^3.5.3
238
347
  ```
239
348
 
240
- - Staged `docs/plans/**/*.md` + `docs/audits/**/*.md` (design, plan, audit docs) run `scripts/prettier/bkit-insert-ignore.mjs` before prettier → committed tables carry `<!-- prettier-ignore -->` and `| --- |` separators. Needs § Prettier tables copied; without it, commits touching those files fail.
241
- - Globs must not overlap: lint-staged runs entries concurrently, so two entries writing one file race. Second entry negates the first.
242
- - Adapt: add per-glob commands (eslint `--fix`, etc.) — keep them seconds-fast.
349
+ - Staged `docs/plans/**/*.md` and `docs/audits/**/*.md` (design, plan, audit docs) run `scripts/prettier/bkit-insert-ignore.mjs` before prettier, so committed tables carry `<!-- prettier-ignore -->` and `| --- |` separators.
350
+ - This needs § Prettier tables copied. Without it, commits that touch those files fail.
351
+ - Globs must not overlap, because lint-staged runs entries concurrently, so two entries that write one file race. The second entry negates the first.
352
+ - Adapt: add per-glob commands (eslint `--fix`, etc.), and keep them seconds-fast.
243
353
 
244
- ## Vale — prose lint, with House styles
354
+ ## Vale — prose lint, with Bkit styles
245
355
 
246
- `lint:prose` (`bkit ci prose`, in `bkit:gate:static`) runs Vale with the `write-good` package and bkit's House styles (`Filler`, `Hedging`, `LLMSlop`, `Verbose`) on `.agents/**`. Workflows reach Vale only through the gate. Reference: https://vale.sh/docs/install.
356
+ `bkit:lint:prose` (`bkit ci prose`, in `bkit:gate:static`) runs Vale with the `write-good` package and bkit's Bkit styles (`Filler`, `Hedging`, `LLMSlop`, `Verbose`) on `.agents/**`. Workflows reach Vale only through the gate. Reference: https://vale.sh/docs/install.
247
357
 
248
358
  ```bash
249
359
  brew install vale
250
360
  vale sync
251
361
  ```
252
362
 
253
- - Copy `.vale.ini` and all four `.vale/styles/House/*.yml`.
254
- - `.gitignore`: `.vale/styles/write-good` (`vale sync` downloads it; the House styles stay tracked).
255
- - CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`. Cursor: the `Dockerfile` template installs it.
256
- - Adapt: add `[glob]` scope blocks for your own docs; turn rules off per path, not globally.
257
- - Traps: no Vale on `PATH` → `lint:prose` prints a skip line and the prose gate is not enforcing. A missing `write-good` is copied from the main worktree, else `vale sync` runs; when both fail it prints a loud skip warning. Keep the `.bkit/templates/**` block (rules off for the copies).
363
+ - Copy `.vale.ini` and all four `.vale/styles/Bkit/*.yml`.
364
+ - `.gitignore`: `.vale/styles/write-good`. `vale sync` downloads it, and the Bkit styles stay tracked.
365
+ - CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`.
366
+ - Cursor: the `Dockerfile` template installs it.
367
+ - Adapt: add `[glob]` scope blocks for your own docs. Turn rules off per path, not globally.
368
+ - Traps:
369
+ - **If** Vale is not on `PATH` → `bkit:lint:prose` fails, so a push from a machine without Vale stops at pre-push. Install Vale there.
370
+ - A missing `write-good` is copied from the main worktree, else `vale sync` runs. When both fail, `bkit:lint:prose` fails.
371
+ - Keep the `.bkit/templates/**` block, which turns rules off for the copies.
258
372
 
259
373
  ## slop-scan — `slop-scan.config.json`
260
374
 
261
- `lint:slop` reports; `slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base: `--base` / bare argument, else `$SLOP_BASE_REF`, else the merge-base with `origin/dev` (else `origin/main`). CI passes its planner base; pre-push on a `dev` push exports the same base as `SLOP_BASE_REF` (§ Git hooks), so both compare against the last green CI push run. Reference: https://github.com/benvinegar/slop-scan.
375
+ `lint:slop` reports. `bkit:slop:delta` (`bkit ci slop`, in `bkit:gate:static`) fails on net-new findings against the base. The base is `--base` / the bare argument, else `$SLOP_BASE_REF`, else the merge-base with `origin/dev` (else `origin/main`). CI passes its planner base, and pre-push on a `dev` push exports the same base as `SLOP_BASE_REF` (§ Git hooks), so both compare against the last green CI push run. On failure it logs each net-new / worsened finding (`path:line`, rule, message; line shifts dropped) and emits them as `findings`. Reference: https://github.com/benvinegar/slop-scan.
262
376
 
263
377
  ```bash
264
378
  pnpm add -D slop-scan@^0.3.0
@@ -266,13 +380,16 @@ mkdir -p scripts/slop
266
380
  cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
267
381
  ```
268
382
 
269
- - The plugin is a template: copy `scripts/slop/bkit-slop-type-suppression.mjs` and point the config's `plugins` entry at it (`boundary/type-suppression`, `boundary/gate-suppression`). No plugin → drop the `plugins` entry and both `boundary/*` rules.
270
- - Adapt: `ignores` for generated / vendored trees; per-file `overrides` with a reason, never a rule disabled repo-wide.
271
- - Traps: keep `**/.bkit/templates/**` in `ignores`, or copied `.mjs` / `.py` count as net-new slop on the upgrade commit. Nothing imports the copied plugin — a reachability scanner (knip, ts-prune, vulture) reads it as dead: register it as an entry point, and where `scripts/` is its own scanner workspace, register there, not the root workspace.
383
+ - The plugin is a template. Copy `scripts/slop/bkit-slop-type-suppression.mjs`, and point the config's `plugins` entry at it (`boundary/type-suppression`, `boundary/gate-suppression`).
384
+ - **If** you use no plugin → drop the `plugins` entry and both `boundary/*` rules.
385
+ - Adapt: add `ignores` for generated / vendored trees. Use per-file `overrides` with a reason, never a rule disabled repo-wide.
386
+ - Traps:
387
+ - Keep `**/.bkit/templates/**` in `ignores`, or the copied `.mjs` / `.py` files count as net-new slop on the upgrade commit.
388
+ - Nothing imports the copied plugin, so a reachability scanner (knip, ts-prune, vulture) reads it as dead. Register it as an entry point. Where `scripts/` is its own scanner workspace, register it there, not in the root workspace.
272
389
 
273
390
  ## Oxlint — test-file lint, `.oxlintrc.json`
274
391
 
275
- Fails `lint` on a test that cannot fail. Oxlint (fast linter) runs five rules on test files only; all other checks off. JS / TS repos with Vitest or Jest. Reference: https://oxc.rs/docs/guide/usage/linter.html.
392
+ It fails `lint` on a test that cannot fail. Oxlint (a fast linter) runs five rules on test files only, with all other checks off. It fits JS / TS repos with Vitest or Jest. Reference: https://oxc.rs/docs/guide/usage/linter.html.
276
393
 
277
394
  ```bash
278
395
  pnpm add -D oxlint@^1.87.0 oxlint-tsgolint@^7.0.2004
@@ -285,109 +402,159 @@ Set `lint` to the value in § Gate tool scripts.
285
402
  | Rule | Fails on |
286
403
  | --- | --- |
287
404
  | `vitest/expect-expect` | A test with no assertion. |
288
- | `vitest/no-conditional-in-test` | `if`, `?:`, `&&`, `??` or `||` inside a test: the branch under test may never run. |
405
+ | `vitest/no-conditional-in-test` | `if`, `?:`, `&&`, `??` or `\|\|` inside a test: the branch under test may never run. |
289
406
  | `vitest/no-conditional-expect` | An `expect` inside a branch or `catch`: it may never run. |
290
407
  | `vitest/valid-expect` (`maxArgs: 2`) | `expect(x)` with no matcher; more than a value and a message. |
291
408
  | `typescript/no-floating-promises` | A promise nobody awaits: the test ends before its assertion runs. |
292
409
 
293
- - Scope: `**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`; source files are not linted. The `vitest/` rules read Jest-style `describe` / `it` / `expect` too.
294
- - `ignorePatterns` skips `.bkit/templates/` and `scripts/ci/**/*.test.mjs`: CI script tests run on plain Node with their own `test()` helper, which the rules misread.
295
- - Keep `--type-aware`: without it `typescript/no-floating-promises` never runs, gate stays green. `oxlint-tsgolint` (peer of `oxlint`) bundles its own TypeScript engine → no `typescript` dependency. Tested pair: `oxlint` 1.87.0 + `oxlint-tsgolint` 7.0.2004.
296
- - No path argument → lints the working directory. Narrow it (`oxlint … src`); tests outside root `tsconfig.json` → add `--tsconfig <file>`.
297
- - Adapt: `files` glob; `assertFunctionNames` on `expect-expect` (default `expect`) when your own helper asserts, e.g. `["expect", "expectHttpError"]`. Turn a rule off per file in `overrides`, never repo-wide.
298
- - Existing suite → many hits. Fix each in its test: one `it` per case (`it.each` for tables), `await expect(…).rejects` in place of `try` / `catch`, `await` on every promise. No baseline file, no disable comment, no `.skip`.
299
- - Why not ESLint: typescript-eslint's type-aware rules need TypeScript `<6.1`.
300
- - Non-JS repo → keep its own linter and its test-lint rules (e.g. `flake8-pytest-style`); `lint` stays yours.
410
+ - Scope: `**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}`. Source files are not linted. The `vitest/` rules read Jest-style `describe` / `it` / `expect` too.
411
+ - `ignorePatterns` skips `.bkit/templates/` and `scripts/ci/**/*.test.mjs`, because CI script tests run on plain Node with their own `test()` helper, which the rules misread.
412
+ - Keep `--type-aware`. Without it, `typescript/no-floating-promises` never runs, and the gate stays green.
413
+ - `oxlint-tsgolint` (a peer of `oxlint`) bundles its own TypeScript engine, so there is no `typescript` dependency. The tested pair is `oxlint` 1.87.0 and `oxlint-tsgolint` 7.0.2004.
414
+ - With no path argument, it lints the working directory. Narrow it (`oxlint … src`).
415
+ - **If** tests sit outside the root `tsconfig.json` → add `--tsconfig <file>`.
416
+ - Adapt: the `files` glob, and `assertFunctionNames` on `expect-expect` (default `expect`) when your own helper asserts, for example `["expect", "expectHttpError"]`. Turn a rule off per file in `overrides`, never repo-wide.
417
+ - **If** you have an existing suite → expect many hits. Fix each one in its test:
418
+ - one `it` per case (`it.each` for tables)
419
+ - `await expect(…).rejects` in place of `try` / `catch`
420
+ - `await` on every promise
421
+ - no baseline file, no disable comment, no `.skip`
422
+ - ESLint is not used because typescript-eslint's type-aware rules need TypeScript `<6.1`.
423
+ - **If** the repo is not JS → keep its own linter and its test-lint rules (for example `flake8-pytest-style`). `lint` stays yours.
301
424
  - `bkit tips` suggests it (tip `test-lint`) when `package.json` lists `vitest` or `jest` and the repo has no Oxlint config, no `oxlint` dependency and no ESLint config naming a test plugin.
302
425
 
303
426
  ## direnv — `.envrc`
304
427
 
305
- Loads `.bkit/.env` on `cd`, so local sessions see `BKIT_GH_TOKEN`, tracker keys. bkit reads your `.envrc` (its `dotenv*` and `unset` lines, never executed) to fill the env blocks of `.claude/bkit-cloud.md` / `.cursor/bkit-cloud.md`; preflight's direnv advisories key on it. Reference: https://direnv.net/docs/installation.html.
428
+ It loads `.bkit/.env` on `cd`, so local sessions see `BKIT_GH_TOKEN` and the tracker keys. bkit reads your `.envrc` (its `dotenv*` and `unset` lines, never executed) to fill the env blocks of `.claude/bkit-cloud.md` / `.codex/bkit-cloud.md` / `.cursor/bkit-cloud.md`. Preflight's direnv advisories key on it. Reference: https://direnv.net/docs/installation.html.
306
429
 
307
430
  ```bash
308
431
  brew install direnv # then add the shell hook from the link
309
432
  direnv allow
310
433
  ```
311
434
 
312
- - Adapt: one `dotenv_if_exists <path>` line per extra env file; `unset` keys that must stay out of the shell (they are dropped from the cloud env blocks too).
435
+ - Adapt: add one `dotenv_if_exists <path>` line per extra env file.
436
+ - `unset` the keys that must stay out of the shell. They are dropped from the cloud env blocks too.
313
437
 
314
438
  ## Launchd GUI environment — tokens for Dock-launched apps
315
439
 
316
- Dock/Spotlight launches start under `launchd`, which never runs the login shell or direnv → GUI apps (opencode desktop, Cursor) start without `BKIT_*` and provider calls fail on authentication. The template set pairs a loader script with a machine-local env file; the LaunchAgent runs the loader at login and again on every write to that file.
440
+ Dock / Spotlight launches start under `launchd`, which never runs the login shell or direnv, so GUI apps (OpenCode desktop, Cursor) start without `BKIT_*`, and provider calls fail on authentication. The template set pairs a loader script with a machine-local env file. The LaunchAgent runs the loader at login, and again on every write to that file.
317
441
 
318
442
  <!-- prettier-ignore -->
319
443
  | File | Copy from | To | Commit |
320
444
  | --- | --- | --- | --- |
321
445
  | Loader | `.bkit/templates/scripts/launchd/bkit-launchd-env.sh` | `scripts/launchd/bkit-launchd-env.sh` | that file |
322
- | LaunchAgent | `.bkit/templates/scripts/launchd/ai.bkit.launchd.plist` | `~/Library/LaunchAgents/ai.bkit.launchd.plist` | never (machine-local) |
323
- | Tokens | `.bkit/templates/scripts/launchd/launchd.env.example` | `~/.config/bkit/launchd.env` | never (machine-local) |
446
+ | LaunchAgent | `.bkit/templates/scripts/launchd/bkit-launchd.plist` | `~/Library/LaunchAgents/ai.bkit.launchd.plist` | never (machine-local) |
447
+ | Tokens | `.bkit/templates/scripts/launchd/bkit-launchd.env.example` | `~/.config/bkit/launchd.env` | never (machine-local) |
324
448
 
325
449
  ```bash
326
450
  cp .bkit/templates/scripts/launchd/bkit-launchd-env.sh scripts/launchd/
327
451
  chmod +x scripts/launchd/bkit-launchd-env.sh
328
452
  mkdir -p ~/.config/bkit
329
- cp .bkit/templates/scripts/launchd/launchd.env.example ~/.config/bkit/launchd.env
453
+ cp .bkit/templates/scripts/launchd/bkit-launchd.env.example ~/.config/bkit/launchd.env
330
454
  chmod 600 ~/.config/bkit/launchd.env # tokens stay owner-only
331
455
  # fill in the tokens, then place the agent:
332
- cp .bkit/templates/scripts/launchd/ai.bkit.launchd.plist ~/Library/LaunchAgents/
456
+ cp .bkit/templates/scripts/launchd/bkit-launchd.plist ~/Library/LaunchAgents/ai.bkit.launchd.plist
333
457
  # replace {{SCRIPT_PATH}} and {{ENV_FILE}} with absolute paths in the copied plist
334
458
  launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist 2>/dev/null || true
335
459
  launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
336
460
  launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
337
461
  ```
338
462
 
339
- - `WatchPaths` re-runs the loader on every env-file write → rotate a token by editing the value, revoke it by deleting the line or emptying the value (`KEY=""`); no re-bootstrap.
340
- - Loader loads `BKIT_*` keys only (others logged as skipped). An empty value runs `launchctl unsetenv`. Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path); a recorded key missing from the env file is unset on the next run.
341
- - One failing key is logged and skipped; the rest still load and the loader exits 1. A failed unset stays recorded and retries on the next run.
342
- - Log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
343
- - Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
344
- - launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`: macOS TCC denies it and `/tmp/bkit-launchd.log` reads `Operation not permitted`. Repo under one of those → keep the adopted copy in git but place the loader launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path) and point `{{SCRIPT_PATH}}` there.
345
- - Env-file rules: blank lines and `#` comments ignored; optional `export ` prefix; key must match `[A-Za-z0-9_]`; matching surrounding quotes stripped from the value.
346
- - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch (set and unset alike).
347
- - **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for; prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
463
+ - `WatchPaths` re-runs the loader on every env-file write, so no re-bootstrap is needed.
464
+ - To rotate a token, edit the value.
465
+ - To revoke a token, delete the line or empty the value (`KEY=""`).
466
+ - The loader loads `BKIT_*` keys only, and logs the others as skipped. An empty value runs `launchctl unsetenv`.
467
+ - Loaded key names are recorded in `.launchd-loaded-keys` next to the env file (mode 600; `BKIT_LAUNCHD_STATE` overrides the path). A recorded key that is missing from the env file is unset on the next run.
468
+ - One failing key is logged and skipped. The rest still load, and the loader exits 1. A failed unset stays recorded and retries on the next run.
469
+ - The log `~/Library/Logs/bkit-launchd.log` records key names only, never values. `BKIT_LAUNCHD_LOG` and `BKIT_LAUNCHD_ENV` override the log and env-file defaults.
470
+ - The loader self-skips (a log line and `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
471
+ - launchd cannot exec a loader under `~/Documents`, `~/Desktop` or `~/Downloads`, because macOS TCC denies it. `/tmp/bkit-launchd.log` then reads `Operation not permitted`.
472
+ - **If** the repo sits under one of those → keep the adopted copy in git, but place the loader that launchd runs at `~/.config/bkit/bkit-launchd-env.sh` (or another unprotected path), and point `{{SCRIPT_PATH}}` there.
473
+ - Env-file rules:
474
+ - Blank lines and `#` comments are ignored.
475
+ - The `export ` prefix is optional.
476
+ - A key must match `[A-Za-z0-9_]`.
477
+ - Matching surrounding quotes are stripped from the value.
478
+ - `launchctl setenv` reaches apps launched after the load. A running app keeps its environment until relaunch, for set and unset alike.
479
+ - **Exposure:** `launchctl setenv` makes every loaded token visible to every app started in the login session, not only the app that needs it. Load only tokens you accept that for. Prefer `bkit cursor` / `bkit opencode` (per-process env) where possible.
348
480
  - Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
349
481
 
350
482
  ## Cursor — `settings.json`, `environment.json`, `Dockerfile`
351
483
 
352
- Editor defaults (`settings.json`: prettier format-on-save, extension recommendations) and the Cursor Cloud Agent image (`environment.json` → `Dockerfile` + per-snapshot `install`). Cloud agents run bkit workflows; `bkit install --auto=cursor` (needs `--tracker=linear`) points at the two cloud files. Reference: https://cursor.com/docs/cloud-agent/setup.
484
+ These are the editor defaults (`settings.json`: prettier format-on-save, extension recommendations) and the Cursor Cloud Agent image (`environment.json` → `Dockerfile` + per-snapshot `install`). Cloud agents run bkit workflows. `bkit install --auto=cursor` (needs `--tracker=linear`) points at the two cloud files. Reference: https://cursor.com/docs/cloud-agent/setup.
353
485
 
354
- - `Dockerfile`: the `bkit toolchain` section installs what bkit's workflows use (git, jq, python3, pinned and sha256-checked gh and Vale, corepack-pinned pnpm). Node 24 is installed outside it from a sha256-checked nodejs.org tarball. Adapt `FROM`, the Node version and repo extras outside the toolchain section.
486
+ - `Dockerfile`: the `bkit toolchain` section installs what bkit's workflows use (git, jq, python3, pinned and sha256-checked gh and Vale, corepack-pinned pnpm). Node 24 is installed outside it from a sha256-checked nodejs.org tarball. Adapt `FROM`, the Node version and the repo extras outside the toolchain section.
355
487
  - `environment.json` `install`: `pnpm install --frozen-lockfile`, then `vale sync` when `.vale.ini` exists.
356
488
  - Secrets: Cloud Agents dashboard → Runtime Secrets (`.bkit/cloud.md`).
357
- - Traps: the corepack pnpm pin must match `packageManager`. Keep the `bkit toolchain` section as shipped so the template diff on upgrade stays readable.
489
+ - Traps:
490
+ - The corepack pnpm pin must match `packageManager`.
491
+ - Keep the `bkit toolchain` section as shipped, so the template diff on upgrade stays readable.
358
492
 
359
493
  ## Dependabot and Renovate
360
494
 
361
- Opens dependency PRs. No bkit workflow reads either. Pick one; copy only its files. Reference: Dependabot https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference; Renovate https://docs.renovatebot.com/, self-hosted action https://github.com/renovatebot/github-action.
495
+ Each one opens dependency PRs. No bkit workflow reads either. Pick one, and copy only its files. Reference: Dependabot https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference; Renovate https://docs.renovatebot.com/, self-hosted action https://github.com/renovatebot/github-action.
362
496
 
363
- Dependabot — commit `.github/dependabot.yml` on the default branch, then enable alerts and security updates:
497
+ Dependabot: commit `.github/dependabot.yml` on the default branch, then enable alerts and security updates:
364
498
 
365
499
  ```bash
366
500
  gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
367
501
  gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
368
502
  ```
369
503
 
370
- Renovate (Mend) — commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate (GitHub UI only; no `gh` equivalent). Renovate (self-hosted) — also copy `bkit-renovate.yml`, then set its platform token (fine-grained PAT for one owner, classic across owners; permissions → `docs/deployments.md` § Dependency updaters):
504
+ Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI. There is no `gh` equivalent.
505
+
506
+ Renovate (self-hosted): also copy `bkit-renovate.yml`, then set its platform token. Use a fine-grained PAT for one owner, and a classic one across owners. The permissions are in `docs/deployments.md` § Dependency updaters.
371
507
 
372
508
  ```bash
373
509
  gh secret set BKIT_GH_TOKEN
374
510
  ```
375
511
 
376
- - Examples ignore `.bkit/templates/**`, `.agents/skills/**` (bkit rewrites them), `docs/plans/**` and the `tests` / `__fixtures__` trees. Your copied workflows (`bkit-ci.yml`, `bkit-cloud.yml`) stay in scope so their pins refresh.
377
- - Examples extend `config:best-practices`; major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`); `lockFileMaintenance` runs monthly; PRs rebase only on conflict.
378
- - A `# renovate: datasource=<ds> depName=<name>` comment above a pinned CLI version (Dockerfile, `bkit-cloud.md`, workflows) lets the example `customManagers` entry bump it. Checksum-paired pins (Vale, gh, jq, Node, actionlint): update the sha256 by hand in the same PR.
379
- - `bkit-renovate.yml` pins `renovate-version` to an exact release; the same kind of `# renovate:` comment keeps it current.
380
- - `enabled: false` on a Renovate package rule does not stop digest pinning; use `ignorePaths` to keep Renovate off a file.
381
- - Land config on default branch before bot runs. Examples set `baseBranchPatterns: ["dev"]`.
382
- - App install, self-hosted token, private-package host rule, CVE handling → `docs/deployments.md` § Dependency updaters.
512
+ - The examples ignore `.bkit/templates/**`, `.agents/skills/**` (bkit rewrites them), `docs/plans/**` and the `tests` / `__fixtures__` trees. Your copied workflows (`bkit-ci.yml`, `bkit-cloud.yml`) stay in scope so their pins refresh.
513
+ - The examples extend `config:best-practices`:
514
+ - Major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`).
515
+ - `lockFileMaintenance` runs monthly.
516
+ - PRs rebase only on conflict.
517
+ - A `# renovate: datasource=<ds> depName=<name>` comment above a pinned CLI version (Dockerfile, `bkit-cloud.md`, workflows) lets the example `customManagers` entry bump it.
518
+ - For checksum-paired pins (Vale, gh, jq, Node, actionlint), update the sha256 by hand in the same PR. `Check Pinned Checksums` in `bkit-ci.yml` (`bkit ci pins`) fails the PR until the Dockerfile's hashes match.
519
+ - `bkit-renovate.yml` pins `renovate-version` to an exact release. The same kind of `# renovate:` comment keeps it current.
520
+ - `enabled: false` on a Renovate package rule does not stop digest pinning. Use `ignorePaths` to keep Renovate off a file.
521
+ - Land the config on the default branch before the bot runs. The examples set `baseBranchPatterns: ["dev"]`.
522
+ - The App install, the self-hosted token, the private-package host rule and CVE handling are in `docs/deployments.md` § Dependency updaters.
523
+
524
+ ## Dependency audit — known-vulnerable dependencies fail the push
525
+
526
+ A library with a published security advisory can sit in the lockfile for months, because the updater only offers a fix, and nothing fails the check when one is missing. This gate stops a known high or critical advisory on the machine, at the push, before it reaches a remote run. It is optional, and the files are yours once copied. Reference: https://docs.npmjs.com/cli/v10/commands/npm-audit.
527
+
528
+ ```bash
529
+ mkdir -p scripts/ci
530
+ cp .bkit/templates/scripts/ci/bkit-check-dependency-audit.mjs \
531
+ .bkit/templates/scripts/ci/bkit-check-dependency-audit.test.mjs \
532
+ .bkit/templates/scripts/ci/bkit-accepted-advisories.json scripts/ci/
533
+ ```
534
+
535
+ - Wiring:
536
+ - The `Dependency audit` block in the `.husky/pre-push` template runs it above the gates. The block is skipped while `scripts/ci/bkit-check-dependency-audit.mjs` is absent.
537
+ - **If** your hook lacks the block → paste it above the gates.
538
+ - The `Check Dependency Audit` step (`bkit-tests-static`) self-skips until the script is copied.
539
+ - Recommendation: adopt it, and an advisory is seen at the first push, not at the first remote run. It reads the advisory registry that the push already needs, so the network is no extra requirement.
540
+ - Acceptances:
541
+ - A row in `scripts/ci/bkit-accepted-advisories.json` needs `advisory`, `reason` and a `YYYY-MM-DD` `expires`.
542
+ - The expiry may not run past the severity's `blocking` days (default critical 7, high 30).
543
+ - A row that the audit no longer reports fails.
544
+ - Upgrade before accepting: `pnpm update -r <pkg>`.
545
+ - It fails closed: a blocking advisory, an unusable answer or an unreachable registry stops the push. It never passes on no answer.
546
+ - `--unreachable=warn` relaxes only the unreachable case, to one warning, and the push goes on. It is for a caller that leaves the check to CI. The shipped hook and the CI step both use the default `fail`.
547
+ - A registry that answered badly (401, 500, a missing endpoint) is a failure, not "unreachable".
548
+ - The audit runs with pnpm's fetch retries off, so a refused or unresolved registry fails in under a second instead of hanging the push. A slow, working registry is never cut off.
549
+ - Once it is adopted, the Trivy scan skips `pnpm-lock.yaml`, so accept pnpm advisories here only (§ Trivy).
383
550
 
384
551
  ## Trivy — vulnerability, config and secret scan
385
552
 
386
- Fails CI on a HIGH or CRITICAL finding: a vulnerable package in any lockfile Trivy reads (npm, pnpm, yarn, pip, poetry, uv, Go, Cargo, Maven, …), a risky setting in a Dockerfile / Terraform / Kubernetes / Helm file, or a secret in a tracked file. Runs on push, pull request and daily. Reference: https://trivy.dev/docs/latest/.
553
+ It fails CI on a HIGH or CRITICAL finding: a vulnerable package in any lockfile Trivy reads (npm, pnpm, yarn, pip, poetry, uv, Go, Cargo, Maven, …), a risky setting in a Dockerfile / Terraform / Kubernetes / Helm file, or a secret in a tracked file. It runs on push, on pull request and daily. Reference: https://trivy.dev/docs/latest/.
387
554
 
388
- Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, commit. No secret, token or App. Blocks merges only once the `trivy` check is required in branch protection.
555
+ Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, and commit. It needs no secret, token or App. It blocks merges only once the `trivy` check is required in branch protection.
389
556
 
390
- Accept a finding in `.trivyignore.yaml` at the repo root (read only when present):
557
+ Accept a finding in `.trivyignore.yaml` at the repo root, which is read only when present:
391
558
 
392
559
  ```yaml
393
560
  vulnerabilities:
@@ -402,34 +569,39 @@ misconfigurations:
402
569
  expired_at: 2026-11-18
403
570
  ```
404
571
 
405
- - Past `expired_at` the finding fails again. Keep it within the fix-time policy (`docs/deployments.md` § Dependency updaters).
406
- - `scripts/ci/check-dependency-audit.mjs` adopted → the scan skips `pnpm-lock.yaml`; accept pnpm advisories in `accepted-advisories.json` only.
407
- - Keep `--include-dev-deps`: without it Trivy drops npm / yarn / pnpm dev dependencies, and a dev-tooling lockfile scans zero packages and passes.
408
- - Pin = image tag + `sha256:` digest; Renovate bumps both. Never `aquasecurity/trivy-action` or `setup-trivy` by tag (tags re-pointed at a credential stealer, March 2026); never releases 0.69.4 – 0.69.6.
409
- - The `.cursor/Dockerfile` template runs as root → `DS-0002`. Add a non-root `USER` or accept it.
410
- - Reads Dockerfiles, not built images. OS packages in an image you build → add a step after your build running the same pinned image with `image <your-image-ref>`.
572
+ - Past `expired_at`, the finding fails again. Keep it within the fix-time policy (`docs/deployments.md` § Dependency updaters).
573
+ - **If** `scripts/ci/bkit-check-dependency-audit.mjs` is adopted → the scan skips `pnpm-lock.yaml`. Accept pnpm advisories in `bkit-accepted-advisories.json` only.
574
+ - Keep `--include-dev-deps`. Without it, Trivy drops npm / yarn / pnpm dev dependencies, and a dev-tooling lockfile scans zero packages and passes.
575
+ - The pin is the image tag plus its `sha256:` digest, and Renovate bumps both.
576
+ - Never use `aquasecurity/trivy-action` or `setup-trivy` by tag, because those tags are known to have pointed at a credential stealer. Never use releases 0.69.4-0.69.6.
577
+ - The `.cursor/Dockerfile` template runs as root, which raises `DS-0002`. Add a non-root `USER` or accept it.
578
+ - It reads Dockerfiles, not built images.
579
+ - **If** an image you build has OS packages → add a step after your build that runs the same pinned image with `image <your-image-ref>`.
411
580
  - Results print in the job log. Security-tab upload (SARIF) is free on public repos only.
412
581
 
413
582
  ## Serena — symbol lookup
414
583
 
415
- Local language server, wired as MCP server; agents use it. Does not rewrite `CLAUDE.md` / `.claude/settings.json`. Reference: https://github.com/oraios/serena.
584
+ A local language server, wired as an MCP server, which agents use. It does not rewrite `CLAUDE.md` / `.claude/settings.json`. Reference: https://github.com/oraios/serena.
416
585
 
417
586
  ```bash
418
587
  brew install uv
419
588
  uv tool install -p 3.13 serena-agent
420
589
  ```
421
590
 
422
- PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
423
-
424
- - Set `project_name`, `typescript_version` in `.serena/project.yml`. `typescript_version` must match `package.json`, not Serena's bundled compiler. TypeScript >= 7 ships no `tsserver` → language server fails to start (`Could not find a valid TypeScript installation`) → set `"5.9.3"` (Serena's bundled, last with `tsserver`).
425
- - Trust the project: add its path to `trusted_project_path_patterns` in `~/.serena/serena_config.yml`. Untrusted → Serena ignores all of `ls_specific_settings` (`typescript_version`, indexing waits) with only a log `WARNING`; lookups still answer on bundled defaults.
426
- - Adapt `ignored_paths` to the repo: index the code a change touches, skip committed build output and byte-copied payloads (each indexed copy answers every reference twice).
427
- - `.mcp.json` (Claude Code) calls `scripts/serena/bkit-serena-mcp.sh` → finds binary when GUI app has no login-shell `PATH`.
428
- - Cursor's `.cursor/mcp.json` cannot use that wrapper → point `command` at `${HOME}/.local/bin/serena`, pass `--context ide`.
429
- - Codex: `.codex/config.toml` → `[mcp_servers.serena]`, `command` = absolute path to `serena`, `args = ["start-mcp-server", "--context", "codex", "--project-from-cwd"]`. bkit writes no `.codex/config.toml`.
430
- - OpenCode: `.opencode/opencode.json` → `mcp.serena` = `{ "type": "local", "command": ["<absolute path to serena>", "start-mcp-server", "--context", "ide", "--project-from-cwd"] }`. `bkit upgrade` keeps custom `mcp` entries.
431
- - List `serena` in `.agents/context.md` `mcp-servers` block → every host runs its tools without a prompt; workflow subagents cannot answer one.
432
- - bkit code-reading subagents carry `mcp__serena__*` in `tools:`. Serena not wired → Claude Code drops the entry; agent runs on text search.
591
+ The PyPI name is `serena-agent`, and the CLI is `serena`. PyPI `serena` is an unrelated package.
592
+
593
+ - Set `project_name` and `typescript_version` in `.serena/project.yml`. `typescript_version` must match `package.json`, not Serena's bundled compiler.
594
+ - **If** TypeScript is >= 7 → it ships no `tsserver`, so the language server fails to start (`Could not find a valid TypeScript installation`). Set `"5.9.3"`, Serena's bundled version and the last one with `tsserver`.
595
+ - Trust the project: add its path to `trusted_project_path_patterns` in `~/.serena/serena_config.yml`.
596
+ - **If** the project is untrusted → Serena ignores all of `ls_specific_settings` (`typescript_version`, indexing waits), with only a log `WARNING`. Lookups still answer on the bundled defaults.
597
+ - Adapt `ignored_paths` to the repo. Index the code a change touches. Skip committed build output and byte-copied payloads, because each indexed copy answers every reference twice.
598
+ - `.mcp.json` (Claude) calls `scripts/serena/bkit-serena-mcp.sh`, which finds the binary when a GUI app has no login-shell `PATH`.
599
+ - Codex: in `.codex/config.toml`, add `[mcp_servers.serena]` with `command` set to the absolute path to `serena` and `args = ["start-mcp-server", "--context", "codex", "--project-from-cwd"]`. bkit writes no `.codex/config.toml`.
600
+ - Cursor's `.cursor/mcp.json` cannot use that wrapper. Point `command` at `${HOME}/.local/bin/serena`, and pass `--context ide`.
601
+ - OpenCode: in `.opencode/opencode.json`, set `mcp.serena` to `{ "type": "local", "command": ["<absolute path to serena>", "start-mcp-server", "--context", "ide", "--project-from-cwd"] }`. `bkit upgrade` keeps custom `mcp` entries.
602
+ - List `serena` in the `.agents/context.md` `mcp-servers` block, so every host runs its tools without a prompt, because workflow subagents cannot answer one.
603
+ - bkit code-reading subagents carry `mcp__serena__*` in `tools:`.
604
+ - **If** Serena is not wired → Claude drops the entry, and the agent runs on text search.
433
605
 
434
606
  `.gitignore`:
435
607
 
@@ -438,53 +610,62 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
438
610
  !.serena/project.yml
439
611
  ```
440
612
 
441
- - Keep `read_only: true`, `added_modes: ["no-memories"]`, and the full `excluded_tools` list from example → Serena stays lookup-only for agents. List excludes every tool that writes files / memories / project config, runs code or commands, or opens a browser. Serena edits bypass Edit / Write hooks. Removing an entry hands that tool to every bkit agent.
442
- - `--context codex` still lists excluded tools but refuses each call (`not active`).
443
- - Serena line numbers are 0-based → add 1 before citing `file:line`.
444
- - Small / empty answer for an exported symbol = query did not resolve, not "nothing uses it" → corroborate with text search.
445
- - pnpm monorepo: cross-package references need `composite` + `references` in TypeScript project graph before language server follows them.
613
+ - Keep `read_only: true`, `added_modes: ["no-memories"]` and the full `excluded_tools` list from the example, so Serena stays lookup-only for agents.
614
+ - The list excludes every tool that writes files / memories / project config, runs code or commands, or opens a browser.
615
+ - Serena edits bypass the Edit / Write hooks.
616
+ - Removing an entry hands that tool to every bkit agent.
617
+ - `--context codex` still lists the excluded tools, but refuses each call (`not active`).
618
+ - Serena line numbers are 0-based. Add 1 before citing `file:line`.
619
+ - A small or empty answer for an exported symbol means the query did not resolve, not "nothing uses it". Corroborate it with text search.
620
+ - pnpm monorepo: cross-package references need `composite` + `references` in the TypeScript project graph before the language server follows them.
446
621
 
447
622
  ## Issue forms — `.github/ISSUE_TEMPLATE/`
448
623
 
449
- Issues are the first input every workflow reads. One form per way work starts; each form's intro names its next command. Section names, syntax and machine-read lines: `.bkit/trackers.md` § Issue shapes. GitHub tracker ONLY (Linear and Jira have their own templates). Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
624
+ Issues are the first input every workflow reads. There is one form per way work starts, and each form's intro names its next command. The section names, syntax and machine-read lines are in `.bkit/trackers.md` § Issue shapes. The forms are for the GitHub tracker only, because Linear and Jira have their own templates. Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
450
625
 
451
626
  <!-- prettier-ignore -->
452
627
  | Form | Use when | Next step | Asks for |
453
628
  | --- | --- | --- | --- |
454
629
  | `bkit-idea.yml` | How it should work is still open | `/bkit-design #N` | problem, outcome, success criteria, constraints and non-goals, decisions already made, open questions |
455
- | `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N` / `build:lite` with no plan | the plan in short: narrative, success criteria, edge cases, test matrix, tasks with `Done when` + `Test first`, breaking changes and names, out of scope |
630
+ | `bkit-change.yml` | What to build and "done" are known | `/bkit-plan #N`, or `/bkit-build #N` with no plan | the plan in short: narrative, success criteria, edge cases, test matrix, tasks with `DONE WHEN` + `TEST FIRST` as task group and task blocks showing every plan task field (`CREATE` / `READ` / `UPDATE` / `DELETE`, `DEPENDS ON`, `DONE WHEN`, `TEST FIRST`, `TEST EXCEPTION`), breaking changes and names, out of scope |
456
631
  | `bkit-bug.yml` | Something does not work | a test or CI run already fails → `/bkit-debug #N`; nothing fails yet → `/bkit-debug #N [repro]` | failing test or CI run, what happened, what should, repro steps, how often, affected area, where and when, evidence |
457
632
 
458
- - Every form ends with References. The change form shows the lines workflows read: `**Parent design:**` and `**Audit reports:**` (plan), the blocked-by block (build). Other references are not fetched; write exact paths, ledger `key`s and `#N — title`.
459
- - A change issue is the plan's source when no design or audit report exists: its narrative, success criteria, edge cases, test rows and tasks carry over verbatim. `/bkit-build` with no plan builds those tasks and checks each `Test first` test failed before its code; `build:lite` checks nothing. Nothing ticks the boxes.
460
- - Debug commits to the branch it runs on: start it on the branch the fix lands on.
461
- - Copy the folder, commit on the default branch; GitHub reads forms from there only. Blank issues stay enabled.
462
- - `labels:` applies `enhancement` / `bug` only when the repo has them; missing labels are skipped, never created. Never add `bkit:*` labels: workflows own them.
463
- - Existing forms → copy only the `bkit-*` files you want; names never collide.
633
+ - Every form ends with References. The change form shows the lines workflows read: `**Parent design:**` and `**Audit reports:**` (plan), and the blocked-by block (build). Other references are not fetched. Write exact paths, ledger `key`s and `#N — title`.
634
+ - A change issue is the plan's source when no design or audit report exists. Its narrative, success criteria, edge cases, test rows and tasks carry over verbatim.
635
+ - `/bkit-build` with no plan first writes `{FID}-plan.md` from them (`@bkit-build-plan-convert`). Then it builds the tasks, and checks that each `TEST FIRST` test failed before its code.
636
+ - An existing `{FID}-plan.md` wins, and the issue text is not read.
637
+ - Nothing ticks the boxes.
638
+ - Debug commits to the branch it runs on, so start it on the branch the fix lands on.
639
+ - Copy the folder and commit it on the default branch, because GitHub reads forms from there only. Blank issues stay enabled.
640
+ - `labels:` applies `enhancement` / `bug` only when the repo has them. Missing labels are skipped, never created.
641
+ - Never add `bkit:*` labels, because workflows own them.
642
+ - **If** the repo has existing forms → copy only the `bkit-*` files you want. The names never collide.
464
643
 
465
644
  ## graphify — map
466
645
 
467
- On-demand only — not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default); it stays unwired because its answers come from the `graph.json` snapshot and build/debug agents invalidate the graph faster than it rebuilds — Serena (no index to go stale) owns the agent surface. Two gates keep `docs/capabilities.md` current on dev: pre-push block below (blocks a stale push to dev) + self-skipping CI step (every push). Agents read `docs/capabilities.md`; audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. Only tracked output: `docs/capabilities.md`. Mermaid views: `docs/graphify-out/reports/graph-packages.mmd`, `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
646
+ graphify runs on demand only. It is not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default). That server stays unwired, because its answers come from the `graph.json` snapshot, and build / debug agents invalidate the graph faster than it rebuilds. Serena, which has no index to go stale, owns the agent surface.
647
+
648
+ Two gates keep `docs/capabilities.md` current on dev: the pre-push block below, which blocks a stale push to dev or to a branch with an open PR into dev, and a self-skipping CI step on every push. Agents read `docs/capabilities.md`. Audit templates that need the graph build it via `scripts/graphify/bkit-graphify.sh`. The tracked outputs are `docs/capabilities.md` and any copies of its packages diagram (below). The Mermaid views are `docs/graphify-out/reports/graph-packages.mmd` and `graph-modules.mmd`. Reference: https://github.com/Graphify-Labs/graphify.
468
649
 
469
650
  ```bash
470
651
  uv tool install "$(bash scripts/graphify/bkit-graphify.sh spec)"
471
652
  ```
472
653
 
473
- PyPI name `graphifyy`, CLI `graphify`. `[sql]` adds `.sql` files to corpus. One pinned release builds and judges the register: `GRAPHIFY_SPEC` in `bkit-graphify.sh` (`spec` prints it; CI installs it). Another release draws different edges → `check`, `check-at`, `rollup`, `register`, `refresh` refuse it. Renovate bumps the pin (shipped `customManagers` scans `scripts/graphify/bkit-graphify.sh`); refresh the register in the same change.
654
+ The PyPI name is `graphifyy`, and the CLI is `graphify`. `[sql]` adds `.sql` files to the corpus. One pinned release builds and judges the register: `GRAPHIFY_SPEC` in `bkit-graphify.sh` (`spec` prints it, and CI installs it). Another release draws different edges, so `check`, `check-at`, `rollup`, `register` and `refresh` refuse it. Renovate bumps the pin (the shipped `customManagers` scans `scripts/graphify/bkit-graphify.sh`). Refresh the register in the same change.
474
655
 
475
656
  `package.json` scripts:
476
657
 
477
658
  ```json
478
659
  {
479
- "graph": "bash scripts/graphify/bkit-graphify.sh build",
480
- "graph:check": "bash scripts/graphify/bkit-graphify.sh check",
481
- "graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
482
- "graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
483
- "graph:refresh": "bash scripts/graphify/bkit-graphify.sh refresh",
484
- "graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
485
- "graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
486
- "graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
487
- "graph:update": "bash scripts/graphify/bkit-graphify.sh update"
660
+ "bkit:graph": "bash scripts/graphify/bkit-graphify.sh build",
661
+ "bkit:graph:check": "bash scripts/graphify/bkit-graphify.sh check",
662
+ "bkit:graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
663
+ "bkit:graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
664
+ "bkit:graph:refresh": "bash scripts/graphify/bkit-graphify.sh refresh",
665
+ "bkit:graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
666
+ "bkit:graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
667
+ "bkit:graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
668
+ "bkit:graph:update": "bash scripts/graphify/bkit-graphify.sh update"
488
669
  }
489
670
  ```
490
671
 
@@ -500,43 +681,76 @@ export GRAPHIFY_OUT=docs/graphify-out
500
681
  graphify-out/
501
682
  ```
502
683
 
503
- - Copy `scripts/graphify/bkit-graph-pre-push.sh`; the `.husky/pre-push` template runs it above the gates (skipped while the script is absent and on a min push), so a stale register blocks in ~30s, not after the full gate. Your hook lacks the `Capability register` block → paste it from the template, above the gates. Push to dev → `check-at` on the pushed commit in a throwaway checkout → blocked on mismatch; uncommitted edits (a concurrent session's included) cannot change the answer. graphify not installed → loud "NOT checked" warning, push goes on (CI still checks). Other branches → warn-only staleness note. Reads `PUSH_DEV_SHA` from the bkit pre-push template's stdin loop; older hook copy → re-copy that loop from `.bkit/templates/.husky/pre-push`.
504
- - `.github/workflows/bkit-ci.yml` ships `Check Capability Register` (push events): installs the `spec` release, runs `pnpm graph:check` → stale register fails CI. Self-skips without `scripts/graphify/bkit-graphify.sh`.
505
- - graphify's MCP server is opt-in: install `graphifyy[mcp]` (`mcp` + `starlette`; HTTP transport also needs `uvicorn`) and pass the graph path explicitly — `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit/orientation, never build or debug.
684
+ - Copy `scripts/graphify/bkit-graph-pre-push.sh`. The `.husky/pre-push` template runs it above the gates, so a stale register blocks in ~30s, not after the full gate. It is skipped while the script is absent, and on a min push.
685
+ - **If** your hook lacks the `Capability register` block → paste it from the template, above the gates.
686
+ - It checks wherever CI's `Check Capability Register` would fail: a push to dev, and a push of a branch that has an open PR into dev (`gh pr list --head <branch> --base dev --state open`). It runs `check-at` on the pushed commit in a throwaway checkout, and blocks the push on a mismatch. Uncommitted edits, a concurrent session's included, cannot change the answer.
687
+ - **If** graphify is not installed → it prints a loud "NOT checked" warning, and the push goes on. CI still checks.
688
+ - **If** `gh` is not installed on a branch push, or its `pr list` call fails (offline, not signed in) → it prints the same "NOT checked" warning, because whether the branch has an open PR is unknown, and the push goes on. A lookup that cannot answer is never read as "no PR".
689
+ - On a branch with no open PR, it prints a warn-only staleness note.
690
+ - It reads `PUSH_DEV_SHA`, `BRANCH` and `PUSH_BRANCH_SHA` from the bkit pre-push template's stdin loop. **If** your hook copy is older → re-copy that loop and the `Capability register` call from `.bkit/templates/.husky/pre-push`. Until you do, the script checks the checked-out branch at `HEAD`.
691
+ - `.github/workflows/bkit-ci.yml` ships `Check Capability Register`. It installs the `spec` release and runs the pinned `check-at HEAD`, and a stale register fails CI. It self-skips without `scripts/graphify/bkit-graphify.sh`.
692
+ - It runs on every push and pull request, on the checked-out commit. On a PR, that is GitHub's test merge into the base, so a branch behind its base syncs, refreshes and commits to clear a red.
693
+ - graphify's MCP server is opt-in. Install `graphifyy[mcp]` (`mcp` + `starlette`; the HTTP transport also needs `uvicorn`), and pass the graph path explicitly, because `graphify-mcp` defaults to `graphify-out/graph.json`, not the pinned `docs/graphify-out/graph.json`. Snapshot-dated answers suit audit / orientation, never build or debug.
506
694
  - `.graphifyignore` merges `.gitignore`.
507
- - Keep `package.json` in corpus — excluding it drops workspace `name` fields graphify resolves package imports with; graph still looks complete.
508
- - Keep `tsconfig.json` out; graphify reads `paths` regardless.
509
- - Always run `scripts/graphify/bkit-graphify.sh` — passes `--code-only`, `--no-label`, unsets API keys. No persistent LLM-off setting.
695
+ - Keep `package.json` in the corpus. Excluding it drops the workspace `name` fields that graphify resolves package imports with, and the graph still looks complete.
696
+ - Keep `tsconfig.json` out, because graphify reads `paths` regardless.
697
+ - Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys. There is no persistent LLM-off setting.
510
698
 
511
699
  <!-- prettier-ignore -->
512
700
  | Command | Does |
513
701
  | --- | --- |
514
- | `pnpm graph` | Extract + cluster. Local. No API key. |
515
- | `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
516
- | `pnpm graph:update` | Re-extract changed files, then recluster. |
517
- | `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md`. |
518
- | `pnpm graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces. Reads uncommitted edits. Shipped as a self-skipping CI step (push events); enabled in bkit's own CI. |
702
+ | `pnpm bkit:graph` | Extract + cluster. Local. No API key. |
703
+ | `pnpm bkit:graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
704
+ | `pnpm bkit:graph:update` | Re-extract changed files, then recluster. |
705
+ | `pnpm bkit:graph:rollup` | Package and module views, plus `docs/capabilities.md` and its diagram copies. |
706
+ | `pnpm bkit:graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces, or a diagram copy differs from it. Reads uncommitted edits. Shipped as a self-skipping CI step (every push and pull request; on a PR, GitHub's test merge into the base); enabled in bkit's own CI. |
519
707
  | `bash scripts/graphify/bkit-graphify.sh check-at <rev>` | `check` in a throwaway checkout of `<rev>` (default HEAD); pre-push gate runs it on the commit pushed to dev. |
520
- | `pnpm graph:refresh` | Rebuild register in a throwaway checkout of HEAD → copy over `docs/capabilities.md`. Fixes a red gate; commit result. |
521
- | `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
522
- | `pnpm graph:graphml` | Opt-in GraphML for Gephi / yEd. |
708
+ | `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) → copy over `docs/capabilities.md` → rewrite the diagram copies. Stage the change first, so a run before its commit builds the new state. Fixes a red gate; commit result. |
709
+ | `pnpm bkit:graph:scoped [path]` | One subtree. Default `apps/web/src`. |
710
+ | `pnpm bkit:graph:graphml` | Opt-in GraphML for Gephi / yEd. |
711
+
712
+ - `docs/graphify-out/` holds the raw `graph.json`, and `docs/graphify-out/reports/` holds the derived views.
713
+ - Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup, because the Overrides block must exist. `pnpm bkit:graph:rollup` rewrites it after that.
714
+ - To add a capability, add a rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. The shipped rules JSON has one example row. Replace it.
715
+ - The marker is a literal that only the owner should contain (a host, a header, a marker string). Never use the owner's exported function name, because every legitimate caller then reads as `bypassed`.
716
+
717
+ `MMD_MIN_WEIGHT` (default 12, set in `bkit-graphify.sh`) drops light edges from the Mermaid views (`.mmd` files and the diagrams in `docs/capabilities.md`).
523
718
 
524
- - `docs/graphify-out/` = raw `graph.json`; `docs/graphify-out/reports/` = derived views.
525
- - Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before first rollup (Overrides block must exist) → `pnpm graph:rollup` rewrites it after.
526
- - Add capability → rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. Shipped rules JSON = one example row; replace it.
527
- - Marker = a literal only the owner should contain (a host, a header, a marker string) — never the owner's exported function name: every legitimate caller then reads as `bypassed`.
719
+ - **If** the repo has one module per file → edges are thinner, so lower the default in your copy.
720
+ - An env override changes `docs/capabilities.md` per shell, and fails `pnpm bkit:graph:check`.
528
721
 
529
- `MMD_MIN_WEIGHT` (default 12, set in `bkit-graphify.sh`) drops light edges from the Mermaid views (`.mmd` files and the diagrams in `docs/capabilities.md`). One module per file → thinner edges → lower the default in your copy; an env override changes `docs/capabilities.md` per shell and fails `pnpm graph:check`. Iterate in mermaid.live; render internal-architecture diagram locally:
722
+ To show the packages diagram in another doc, such as your `README.md`, copy `scripts/graphify/bkit-graph-embed.py`:
723
+
724
+ - Put one `<!-- graph:packages:start -->` and one `<!-- graph:packages:end -->` line in the doc, where the diagram goes.
725
+ - Add the doc's path to `GRAPH_EMBED_DOCS` in `bkit-graphify.sh`. Separate several paths with spaces.
726
+ - `rollup`, `register` and `refresh` rewrite the block from `docs/capabilities.md`, so commit the doc with the register.
727
+ - `check` fails when a copy differs from the register, so the pre-push block and CI gate the copies too.
728
+ - **If** a listed doc lacks exactly one marker pair → the run exits 2.
729
+
730
+ Iterate in mermaid.live, and render the internal-architecture diagram locally:
530
731
 
531
732
  ```bash
532
733
  npx -y @mermaid-js/mermaid-cli -i docs/graphify-out/reports/graph-packages.mmd -o tmp/graph-packages.svg
533
734
  ```
534
735
 
535
- - `bkit-graph-repair.py` runs between extract and cluster: restores `.js` specifiers pointing at `.tsx` files and workspace subpaths through an `exports` map. Bare `graphify update` drops that injection; `pnpm graph:update` restores it. `bkit-graph-eager.py` and `bkit-graphify-rollup.py` re-derive those imports from source and warn with the count graph.json lacks. Two files importing each other keep one link after clustering, so that pair never reads as missing.
536
- - `bkit-graph-surface.py` = route layer. Assumes `apps/web` / `apps/mobile` page routes, `packages/api/src/v1.ts`, workspace scope `@scope/services/`. Replace `@scope` and route globs or section stays empty. Route reachability runs only when `scripts/ci/guards/assert-routes-reachable.mjs` exists; else skipped.
537
- - `bkit-graph-imports.py` picks `react-native` vs `default` export conditions from importer path (`apps/mobile` vs `apps/web`). Change prefixes if app roots differ.
538
- - Source roots are hard-coded for an `apps/` + `packages/` monorepo: `ROOTS` in `bkit-graph-drift.py` (files the drift rules scan), `ROOTS` in `bkit-graph-eager.py` and `DEFAULT_ROOTS` in `bkit-graph-imports.py` (files those passes walk), `by_package` / `by_module` in `bkit-graphify-rollup.py` (diagram boxes). Other layout → adapt all five, else capabilities read `gap` and diagrams come out empty. One flat source folder → `by_module` = one node per file. No web routes / no imports between top-level folders → route and package diagrams stay empty; that is the answer, not a fault.
539
- - Extract warning `had syntax errors and may be partially extracted` can fire on valid code → symbols after that line are missing from the graph; treat that file as unmapped.
736
+ - `bkit-graph-repair.py` runs between extract and cluster. It restores `.js` specifiers that point at `.tsx` files, and workspace subpaths through an `exports` map.
737
+ - A bare `graphify update` drops that injection, and `pnpm bkit:graph:update` restores it.
738
+ - `bkit-graph-eager.py` and `bkit-graphify-rollup.py` re-derive those imports from source, and warn with the count that graph.json lacks.
739
+ - Two files that import each other keep one link after clustering, so that pair never reads as missing.
740
+ - `bkit-graph-surface.py` is the route layer. It assumes `apps/web` / `apps/mobile` page routes, `packages/api/src/v1.ts` and the workspace scope `@scope/services/`.
741
+ - Replace `@scope` and the route globs, or the section stays empty.
742
+ - Route reachability runs only when `scripts/ci/guards/assert-routes-reachable.mjs` exists. Otherwise it is skipped.
743
+ - `bkit-graph-imports.py` picks `react-native` vs `default` export conditions from the importer path (`apps/mobile` vs `apps/web`). Change the prefixes if your app roots differ.
744
+ - Source roots are hard-coded for an `apps/` + `packages/` monorepo:
745
+ - `ROOTS` in `bkit-graph-drift.py` (the files the drift rules scan)
746
+ - `ROOTS` in `bkit-graph-eager.py` and `DEFAULT_ROOTS` in `bkit-graph-imports.py` (the files those passes walk)
747
+ - `by_package` / `by_module` in `bkit-graphify-rollup.py` (the diagram boxes)
748
+ - **If** the repo has another layout → adapt all five. Otherwise capabilities read `gap`, and the diagrams come out empty.
749
+ - **If** the repo has one flat source folder → `by_module` gives one node per file.
750
+ - **If** the repo is a single package → have `by_package` return its top-level source folders, so each package box is one part of the codebase.
751
+ - The packages diagram groups package boxes by their parent folder and gives each group one colour, so the keys `by_package` returns decide the groups.
752
+ - **If** there are no web routes, or no imports between top-level folders → the route and package diagrams stay empty. That is the answer, not a fault.
753
+ - The extract warning `had syntax errors and may be partially extracted` can fire on valid code. The symbols after that line are then missing from the graph, so treat that file as unmapped.
540
754
 
541
755
  Do not run:
542
756
 
@@ -547,21 +761,33 @@ Do not run:
547
761
  | `graphify install --project` | Writes a skill. `/bkit-ship` removes skills not named in `.agents/skills.md`. |
548
762
  | `graphify hook install` | Rebuilds on every commit. bkit commits many times per workflow run. |
549
763
 
550
- - Code-graph answer confirms what is present; does not prove what is absent. Missing edge looks like a real gap.
551
- - Ignore rules are load-bearing: a noise-only pattern can drop edges the tool needs; output still looks plausible → re-measure after changing `.graphifyignore`.
764
+ - A code-graph answer confirms what is present. It does not prove what is absent, and a missing edge looks like a real gap.
765
+ - Ignore rules are load-bearing. A noise-only pattern can drop edges the tool needs, and the output still looks plausible, so re-measure after changing `.graphifyignore`.
552
766
 
553
767
  ## Secrets sync — one source, every store
554
768
 
555
- Local gitignored env files = source of truth; `bkit-secrets.mjs sync` makes every store match, `drift` proves it. Needs Node >= 20 plus the CLI of each store used (`gh`, `eas`, `gcloud`); Vercel, Supabase and Cursor go through their REST APIs.
769
+ The local gitignored env files are the source of truth. `bkit-secrets.mjs sync` makes every store match, and `drift` proves it. It needs Node >= 20 plus the CLI of each store used (`gh`, `eas`, `gcloud`). Vercel, Supabase and Cursor go through their REST APIs.
556
770
 
557
- - Copy both files. Edit `bkit-secrets.config.mjs` only; `bkit-secrets.mjs` stays byte-identical across repos.
558
- - Config = one row per secret naming every store holding a copy: `DATABASE_URL: ["vercel", "gcp"]`. Options per row: `from` (env key differs from store name), `derive` (`"${APP_URL}/path"`), `manual` (copies no API reaches), `"eas:secret"` (per-store option).
559
- - Delete unused entries under `stores`; a store no row names is skipped.
771
+ - Copy both files. Edit `bkit-secrets.config.mjs` only. `bkit-secrets.mjs` stays byte-identical across repos.
772
+ - The config has one row per secret, naming every store that holds a copy: `DATABASE_URL: ["vercel", "gcp"]`. The options per row are:
773
+ - `from`: the env key differs from the store name
774
+ - `derive`: `"${APP_URL}/path"`
775
+ - `manual`: copies no API reaches
776
+ - `"eas:secret"`: a per-store option
777
+ - Delete unused entries under `stores`. A store that no row names is skipped.
560
778
  - `.gitignore`: `scripts/secrets/bkit-secrets-state.json`.
561
- - `.bkit/.env` overlay → agent / bkit tooling secrets only; app and stack credentials stay in app env files.
562
- - Cursor store: option `environment` (name) or `environmentId` picks the Cloud Agents environment (ids from `GET /v1/environments`); token `CURSOR_API_KEY` (or `BKIT_CURSOR_API_KEY`). Secrets are write-only; `NAME: "cursor:environment_variable"` writes a non-secret env var instead of a Runtime Secret. `build_secret` names exist only in the dashboard — never written or deleted.
563
- - Cursor rows: list only the names the cloud workflow needs — minimal set `BKIT_GH_TOKEN`, plus `BKIT_LINEAR_API_KEY` on Linear setups, optional `VERCEL_TOKEN` / `SUPABASE_ACCESS_TOKEN` when the workflow reaches those stores. A first sync against a populated environment deletes every live name not listed (start with `--dry-run`). API errors surface with their code: `feature_unavailable` (environments API not enabled for the key), `key_not_supported` (`grok_` keys), `secret_name_ambiguous` (one name, several repo-scoped versions — pre-checked; remove the extra versions in the dashboard). Team-scope 403s (`team_admin_required`) are N/A — the adapter uses environment scope only.
564
- - Custom store: no upstream change → `type: "custom"` + `module` loads a repo-local adapter (see below).
779
+ - The `.bkit/.env` overlay holds agent / bkit tooling secrets only. App and stack credentials stay in the app env files.
780
+ - Cursor store:
781
+ - The option `environment` (name) or `environmentId` picks the Cloud Agents environment (ids from `GET /v1/environments`).
782
+ - The token is `CURSOR_API_KEY` (or `BKIT_CURSOR_API_KEY`).
783
+ - Secrets are write-only. `NAME: "cursor:environment_variable"` writes a non-secret env var instead of a Runtime Secret.
784
+ - `build_secret` names exist only in the dashboard. They are never written or deleted.
785
+ - Cursor rows: list only the names the cloud workflow needs.
786
+ - The minimal set is `BKIT_GH_TOKEN`, plus `BKIT_LINEAR_API_KEY` on Linear setups. `VERCEL_TOKEN` / `SUPABASE_ACCESS_TOKEN` are optional, for when the workflow reaches those stores.
787
+ - A first sync against a populated environment deletes every live name that is not listed, so the `--dry-run` rule below the command table applies to it too.
788
+ - API errors surface with their code: `feature_unavailable` (the environments API is not enabled for the key), `key_not_supported` (`grok_` keys), `secret_name_ambiguous` (one name, several repo-scoped versions; pre-checked, so remove the extra versions in the dashboard).
789
+ - Team-scope 403s (`team_admin_required`) do not apply, because the adapter uses environment scope only.
790
+ - **If** you need a custom store → no upstream change is needed: `type: "custom"` + `module` loads a repo-local adapter (see below).
565
791
 
566
792
  <!-- prettier-ignore -->
567
793
  | Command (`node scripts/secrets/bkit-secrets.mjs …`) | Does |
@@ -572,7 +798,7 @@ Local gitignored env files = source of truth; `bkit-secrets.mjs sync` makes ever
572
798
  | `check [file]` | Local only: sources, env file vs example (exit 2 on a missing required key), every copy of every secret. |
573
799
  | `--store <name>` | Narrow `sync` / `drift` / `list` to one store. Every run covers both environments; no per-environment option. |
574
800
 
575
- `sync` deletes every live name not listed for that store → `--dry-run` before every sync. No listed key resolving to a value skips deletes for that store.
801
+ `sync` deletes every live name that is not listed for that store, so ALWAYS run `--dry-run` before every sync. When no listed key resolves to a value, the deletes for that store are skipped.
576
802
 
577
803
  How `drift` proves a value without printing it:
578
804
 
@@ -584,16 +810,17 @@ How `drift` proves a value without printing it:
584
810
  | EAS (plaintext / sensitive) | `env:list --include-sensitive` | SHA-256 of live value vs source |
585
811
  | GitHub Actions, Supabase, Cursor, Vercel sensitive, EAS `secret` | write-only | state-file fingerprint vs source (`not-pushed`); store's last-updated time after recorded push (`changed-elsewhere`) |
586
812
 
587
- - No recorded push → `unverified`, never `ok`. First sync records one.
588
- - `bkit-secrets-state.json` = fingerprints + times only, per machine. Push from another machine or by hand → `changed-elsewhere` until next sync here.
589
- - `manual` copies listed on every `check` / `drift`; update by hand on rotation.
590
- - Vercel: branch-scoped preview vars left alone; an entry shared across environments is split before a write.
813
+ - **If** no push is recorded → the result is `unverified`, never `ok`. The first sync records one.
814
+ - `bkit-secrets-state.json` holds fingerprints and times only, per machine.
815
+ - **If** a push came from another machine or by hand → the result is `changed-elsewhere` until the next sync here.
816
+ - `manual` copies are listed on every `check` / `drift`. Update them by hand on rotation.
817
+ - Vercel: branch-scoped preview vars are left alone. An entry shared across environments is split before a write.
591
818
 
592
- New store type → entry in `STORES` of the template's `bkit-secrets.mjs` (`open` → `list` / `write` / `remove`; contract above it), never in a copy only. A repo-local store needs no upstream change: `type: "custom"` + `module: "./stores/x.mjs"` (resolved against `scripts/secrets/`) loads a module whose default export carries `label` + `open` (optional `perEnv`, `protects`, `setOptions`); the engine validates the adapter at load and its `open()` handle at run.
819
+ A new store type goes in as an entry in `STORES` of the template's `bkit-secrets.mjs` (`open` → `list` / `write` / `remove`; the contract is above it), never in a copy only. A repo-local store needs no upstream change: `type: "custom"` + `module: "./stores/x.mjs"` (resolved against `scripts/secrets/`) loads a module whose default export carries `label` + `open` (optional `perEnv`, `protects`, `setOptions`). The engine validates the adapter at load, and its `open()` handle at run.
593
820
 
594
821
  ## Prettier tables — keep table diffs to the changed row
595
822
 
596
- Prettier aligns markdown tables with no config toggle; one edited cell re-pads every row. `bkit-insert-ignore.mjs` puts `<!-- prettier-ignore -->` directly above each table head (no blank line between), strips cell padding, normalises separators to `---`. Idempotent. Node >= 20, no dependencies.
823
+ Prettier aligns markdown tables with no config toggle, so one edited cell re-pads every row. `bkit-insert-ignore.mjs` puts `<!-- prettier-ignore -->` directly above each table head (no blank line between), strips cell padding, and normalises separators to `---`. It is idempotent. It needs Node >= 20 and no dependencies.
597
824
 
598
825
  <!-- prettier-ignore -->
599
826
  | Command | Does |
@@ -601,30 +828,39 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
601
828
  | `node scripts/prettier/bkit-insert-ignore.mjs` | Rewrite `.agents/`, `docs/`, `README.md` (or the paths given). |
602
829
  | `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
603
830
 
604
- - Walks skip `skills/` trees (vendored), `docs/audits/`, `docs/plans/` (records, kept as written). A file named on the command line is always processed. New and edited records get it at commit: § lint-staged names each staged file.
605
- - Skips tables inside ``` / ~~~ fences, inside multi-line `<!-- -->` comments, and tables already wrapped. A comment opens on a line starting with `<!--` and runs to the first line holding `-->`; a one-line comment hides nothing.
606
- - A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
607
- - Exit 1 on damage it cannot repair, with or without `--check`: `truncated-row` (more cells than the separator; GFM drops the overflow) and `unrendered-table` (header ≠ separator count; GFM renders raw text). A bare pipe in cell prose is indistinguishable from a delimiter → escape it as `\|` by hand. Under `docs/audits/` and `docs/plans/` the same damage prints as a `WARN` and exits 0: records hold text quoted from elsewhere (issue comments, CI logs) that nobody can fix in place.
831
+ - Walks skip `skills/` trees (vendored), and `docs/audits/` and `docs/plans/` (records, kept as written). A file named on the command line is always processed. New and edited records get it at commit, because § lint-staged names each staged file.
832
+ - It skips tables inside ``` / ~~~ fences, tables inside multi-line `<!-- -->` comments, and tables already wrapped. A comment opens on a line starting with `<!--`, and runs to the first line holding `-->`. A one-line comment hides nothing.
833
+ - A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count. An existing `\|` stays literal.
834
+ - It exits 1 on damage it cannot repair, with or without `--check`:
835
+ - `truncated-row`: more cells than the separator, and GFM drops the overflow.
836
+ - `unrendered-table`: the header count != the separator count, and GFM renders raw text.
837
+ - A bare pipe in cell prose is indistinguishable from a delimiter. Escape it as `\|` by hand.
838
+ - Under `docs/audits/` and `docs/plans/`, the same damage prints as a `WARN` and exits 0, because records hold text quoted from elsewhere (issue comments, CI logs) that nobody can fix in place.
608
839
 
609
840
  ## tmp/ prune — old scratch files
610
841
 
611
- Each push deletes scratch files agents left in `tmp/` untouched for a week, then the folders that leaves empty. Node >= 20, no dependencies.
842
+ Each push deletes scratch files that agents left in `tmp/` untouched for a week, then the folders that leaves empty. It needs Node >= 20 and no dependencies.
612
843
 
613
844
  ```bash
614
845
  mkdir -p scripts/cleanup
615
846
  cp .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs scripts/cleanup/
616
847
  ```
617
848
 
618
- - Wiring: the `tmp/ prune` block in the `.husky/pre-push` template runs it with `--days=7`, ahead of the gates; skipped while `scripts/cleanup/bkit-tmp-prune.mjs` is absent. Your `.husky/pre-push` lacks the block → paste it above the gates.
619
- - Not a gate: a failed prune prints a warning; the push goes on.
620
- - `--days=<n>` (n >= 1, default 7). Exit 0 = swept or no `tmp/`; 1 = an entry could not be removed (each named on stderr); 2 = bad arguments.
621
- - Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree prunes its own. `tmp/` itself stays.
622
- - Age = file mtime. Symlinks never followed: a symlinked `tmp/` is skipped; a symlink inside is removed by its own age, target untouched. A folder goes only when empty and either the sweep emptied it or its own mtime is past the cutoff → a folder another process just made stays.
849
+ - Wiring:
850
+ - The `tmp/ prune` block in the `.husky/pre-push` template runs it with `--days=7`, ahead of the gates. The block is skipped while `scripts/cleanup/bkit-tmp-prune.mjs` is absent.
851
+ - **If** your `.husky/pre-push` lacks the block → paste it above the gates.
852
+ - It is not a gate: a failed prune prints a warning, and the push goes on.
853
+ - `--days=<n>` (n >= 1, default 7).
854
+ - Exit codes: 0 means swept or no `tmp/`; 1 means an entry could not be removed (each one named on stderr); 2 means bad arguments.
855
+ - Scope: `tmp/` at the top of the checkout the cwd sits in. Each worktree prunes its own, and `tmp/` itself stays.
856
+ - Age is the file mtime.
857
+ - Symlinks are never followed. A symlinked `tmp/` is skipped. A symlink inside is removed by its own age, and its target is untouched.
858
+ - A folder goes only when it is empty **and** either the sweep emptied it or its own mtime is past the cutoff, so a folder that another process just made stays.
623
859
  - Hand run: `node scripts/cleanup/bkit-tmp-prune.mjs`. Files to keep belong outside `tmp/`.
624
860
 
625
861
  ## Disk prune — cleanup steps you own
626
862
 
627
- `bkit disk prune` runs only steps you list; bkit deletes nothing. No step file → nothing runs.
863
+ `bkit disk prune` runs only the steps you list, and bkit itself deletes nothing. With no step file, nothing runs.
628
864
 
629
865
  ```bash
630
866
  mkdir -p scripts/cleanup ~/.config/bkit
@@ -638,34 +874,72 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
638
874
  | `scripts/cleanup/bkit-disk-prune.mjs` | this checkout: build caches, leftover agent worktrees | checkout top, first | yes |
639
875
  | `~/.config/bkit/disk-prune.mjs` (`$XDG_CONFIG_HOME/bkit/` when set) | shared tools: Docker, pnpm store, Xcode, Gradle, simulators | home folder | never |
640
876
 
641
- - Step list, default-exported: `{ name, mode, run, skip?, paths? }`. `min` = stale, cheap; `max` = all that comes back by itself + every `min` step. `run` / `skip`: shell command or `({ cwd, log, note })` function; `skip` exit 0 or returned reason → skipped. `paths`: what `--dry-run` sizes, the most the step can free.
642
- - Notes: `note(text)` = found, left for a person. Each sweep replaces its checkout's notes; `bkit tips` prints them first (from a worktree, the main checkout's too), so every workflow close surfaces them. No sweep for 7 days → dropped.
643
- - Example worktree step: removes a `.worktrees/*` only when nothing is lost — clean, every commit on a remote or at a merged pull request's head (`gh`; squash merges) — via `bkit worktrees remove`, or plain `git worktree remove` when no workflow made it. Branches stay. Keeps a locked one or one committed to in 2 days; notes the rest.
644
- - Adapt: keep a step only when what it deletes comes back by itself. Left out on purpose: named Docker volumes (local databases), runtimes and SDKs, whole pnpm store (`node_modules` hard-link into it).
645
- - Wiring: last block of each Husky template — `pre-commit` → `--mode=min --auto`; `pre-push` → `--mode=max --auto`, after every gate (workflow pushes too). Missing → paste at the end of yours.
646
- - `--auto`: detached, always exit 0. Each mode at most once a day per machine; `max` at most hourly while free disk < `bkit.disk.minFreeGb` (`package.json`, GB, default 40). Log: `~/.cache/bkit/disk-prune.log` (`$XDG_CACHE_HOME/bkit/` when set).
647
- - Worktrees: `bkit worktrees setup` create / resume under `bkit.disk.minFreeGb` → runs `max` steps, waits. Still under → exit 12, nothing created; stderr lists what `max` steps still cover. No step file → no check.
648
- - One sweep per machine at a time (`disk-prune.lock` beside the log). Failed step → logged, next runs. CI / cloud → nothing runs.
649
- - Hand run: `pnpm bkit disk prune --mode=max --dry-run` → each step + its `paths` size; without `--dry-run` → runs now. Exit 1 = a step failed or a step file did not load.
650
-
651
- ## Local stack lock — one run at a time on a shared stack
652
-
653
- Every worktree of a repo uses the same local services when their names and ports come from the repo's config (a Docker database, an emulator). A run that starts, resets or stops the stack, or tests against it, takes a machine-wide lock first; a second run waits and prints who holds it. bash + `/usr/bin/perl`, no dependencies.
877
+ - Step list, default-exported: `{ name, mode, run, skip?, paths? }`.
878
+ - `min` steps are stale and cheap. `max` covers all that comes back by itself, plus every `min` step.
879
+ - `run` / `skip`: a shell command or a `({ cwd, log, note })` function. When `skip` exits 0 or returns a reason, the step is skipped.
880
+ - `paths`: what `--dry-run` sizes, which is the most the step can free.
881
+ - Notes: `note(text)` records something found and left for a person.
882
+ - Each sweep replaces its checkout's notes.
883
+ - `bkit tips` prints them first (from a worktree, the main checkout's too), so every workflow close surfaces them.
884
+ - With no sweep for 7 days, they are dropped.
885
+ - The example worktree step removes a `.worktrees/*` only when nothing is lost: it is clean, and every commit is on a remote or at a merged pull request's head (`gh`; squash merges). It removes it via `bkit worktrees remove`, or plain `git worktree remove` when no workflow made it.
886
+ - Branches stay.
887
+ - It keeps a locked worktree, or one committed to in 2 days, and notes the rest.
888
+ - Adapt: keep a step only when what it deletes comes back by itself. These are left out on purpose: named Docker volumes (local databases), runtimes and SDKs, and the whole pnpm store (`node_modules` hard-link into it).
889
+ - Wiring: it is the last block of each Husky template.
890
+ - `pre-commit` → `--mode=min --auto`.
891
+ - `pre-push` → `--mode=max --auto`, after every gate (workflow pushes too).
892
+ - **If** the block is missing → paste it at the end of yours.
893
+ - `--auto`: runs detached, and always exits 0.
894
+ - Each mode runs at most once a day: the machine file's steps once per machine, the repo file's steps once per checkout, so another repo's sweep never uses up this checkout's day.
895
+ - `max` runs at most hourly while free disk < `bkit.workflows.minFreeGb` (`package.json`, GB, default 40), on the same split.
896
+ - Log: `~/.cache/bkit/disk-prune.log` (`$XDG_CACHE_HOME/bkit/` when set).
897
+ - Worktrees:
898
+ - **If** `bkit worktrees setup` creates or resumes a worktree under `bkit.workflows.minFreeGb` → it runs the `max` steps and waits.
899
+ - **If** free disk is still under → it exits 12, and nothing is created. stderr lists what the `max` steps still cover.
900
+ - With no step file, there is no check.
901
+ - One sweep runs per machine at a time (`disk-prune.lock` beside the log).
902
+ - The sweep `--auto` starts and the worktree check wait for a running sweep to end, so their turn is never lost.
903
+ - A hand run stops while another sweep runs, unless it passes `--wait`.
904
+ - A failed step is logged, and the next one runs.
905
+ - In CI / cloud, nothing runs.
906
+ - Hand run: `pnpm bkit disk prune --mode=max --dry-run` prints each step and its `paths` size. Without `--dry-run`, it runs now. `--scope=repo` or `--scope=machine` runs only that file's steps. Exit 1 means a step failed or a step file did not load.
907
+
908
+ ## Machine lock
909
+
910
+ The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`.
654
911
 
655
912
  ```bash
656
913
  mkdir -p scripts/ci
657
- cp .bkit/templates/scripts/ci/bkit-local-stack-lock.sh scripts/ci/
914
+ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
658
915
  ```
659
916
 
660
917
  <!-- prettier-ignore -->
661
918
  | Wire into | How | Holds the lock |
662
919
  | --- | --- | --- |
663
- | `package.json` scripts that start / reset / stop the stack | `"db:reset": "bash scripts/ci/bkit-local-stack-lock.sh run db:reset -- <reset command>"` | for the command; its exit status passes on |
664
- | local runners that test against the stack | `. scripts/ci/bkit-local-stack-lock.sh`, then `take_local_stack_lock "<who>"` before the first stack command; non-zero → exit | until the runner exits or calls `release_local_stack_lock` |
665
-
666
- - Functions: `take_local_stack_lock` waits; `try_local_stack_lock` returns 1 at once while another run holds it; `release_local_stack_lock` frees it early; `local_stack_lock_holder` prints the holder. Safe under `set -e`.
667
- - Name: `BKIT_LOCAL_STACK` when set, else the main checkout's folder name (`git rev-parse --git-common-dir`) → every worktree finds the same lock. A throwaway stack with its own names and ports sets its own `BKIT_LOCAL_STACK` and never waits on the shared one. Outside a git checkout with no `BKIT_LOCAL_STACK` → refuses, exit 1.
668
- - Lock file: `~/.cache/bkit/local-stack-lock/<name>.lock` (`$XDG_CACHE_HOME/bkit/` when set), outside every checkout.
669
- - Never stale: a small perl process holds the lock (flock) and exits within a second of its caller, however the caller ends.
670
- - Wait: `LOCAL_STACK_LOCK_WAIT_S` seconds (default 3600), a note naming the holder once a minute, then exit 1 naming it. A runner started by the holder (`LOCAL_STACK_LOCK_OWNER`) does not wait. `CI=true` / `CI=1` → no-op.
671
- - Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`): the raw command skips the lock. `.agents/rules.md` § Shared local stack.
920
+ | every test-running `bkit:gate:*` script in `package.json` | `"bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command>"` | for the whole gate, across repositories on this machine |
921
+ | a gate that chains commands | `"bkit:gate:static-unit": "bash scripts/ci/bkit-machine-lock.sh run --lock tests -- sh -c 'pnpm bkit:gate:static && pnpm test'"` | for the complete chain |
922
+ | `package.json` scripts that start / reset / stop the stack | `"db:reset": "bash scripts/ci/bkit-machine-lock.sh run db:reset -- <reset command>"` | for the command; its exit status passes on |
923
+ | local runners that test against the stack | `. scripts/ci/bkit-machine-lock.sh`, then `take_local_stack_lock "<who>"` before the first stack command; non-zero → exit | until the runner exits or calls `release_local_stack_lock` |
924
+
925
+ - API (all functions are safe under `set -e`):
926
+ - `take_local_stack_lock "<who>" [name]` waits; every refusal returns 1.
927
+ - `try_local_stack_lock "<who>" [name]` returns 1 at once while busy.
928
+ - `release_local_stack_lock [name]` frees the lock early.
929
+ - `local_stack_lock_holder [name]` prints the holder, or every holder of `tests` slots.
930
+ - `local_stack_lock_file [name]` prints the lock file path.
931
+ - `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order), and 75 means the wait gave up. Omit `<who>` to use `LOCAL_STACK_LOCK_WHO`, else `npm_lifecycle_event`, else `run`.
932
+ - Named locks use `~/.cache/bkit/machine-lock/<name>.lock`, with no repository prefix. The holder line identifies the caller's checkout. A child inherits `LOCAL_STACK_LOCK_OWNER_<key>` and reuses only that named lock while its owner is alive.
933
+ - The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1, default 1; an invalid value falls back to 1 with one note). Slot 1 uses `tests.lock`; later slots use `tests.<k>.lock`. The waiting note names every holder.
934
+ - Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1). Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
935
+ - Take locks in this order: `tests`, other named locks, then the unnamed stack lock. A request for `tests` while this shell or a live parent holds another lock is refused. A request for a named lock while holding the stack lock is also refused.
936
+ - The unnamed stack lock keeps `~/.cache/bkit/local-stack-lock/<stack>.lock` and `LOCAL_STACK_LOCK_OWNER` / `LOCAL_STACK_LOCK_PID`. A consumer's adopted copy keeps working and excludes this copy on the same stack.
937
+ - `<stack>` is `BKIT_LOCAL_STACK`, else the main checkout's folder name, so every worktree finds the same lock.
938
+ - A throwaway stack with its own names and ports sets its own `BKIT_LOCAL_STACK`.
939
+ - Outside a git checkout with no `BKIT_LOCAL_STACK`, the functions refuse with exit 1; `run` exits 73.
940
+ - Lock paths use `$XDG_CACHE_HOME/bkit/` when set. A small Perl process holds the file lock and exits within a second of its caller, however the caller ends.
941
+ - Wait: `LOCAL_STACK_LOCK_WAIT_S` when set, else 60 seconds without a TTY, else 3600 seconds. Waiting notes name the budget and holders once a minute; the give-up line names the holder again.
942
+ - A named release records held seconds by checkout in `<name>.last`, with one tab-separated line per checkout. A waiting note and give-up line name the current holder's `last run took <N>m<N>s`, or `no earlier run`.
943
+ - `CI=true` / `CI=1` makes every lock a no-op.
944
+ - `bkit tests run` and `bkit tests changed` pass `--lock-wait-s` and their run name to a wrapped gate; a tests-lock give-up of this run maps 75 → 81 with `lockHolder`, and a tests-lock refusal maps 73 → 4. A lock wait writes no `test-run` status row. Light runs (`red`, `green`, `bkit:test:file`) take no tests lock. Nested wraps reuse their live parent's tests lock. See `docs/testing.md` § Tests lock for host wait budgets.
945
+ - Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`), because the raw command skips the lock. See `.agents/rules.md` § Shared local stack.