@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -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.dependencies.updater: "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.testing.ciCapstone` 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.testing.ciCapstone`.
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.testing.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.testing.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,7 +332,7 @@ 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.
@@ -232,34 +340,39 @@ pnpm add -D prettier@^3.5.3
232
340
 
233
341
  ## lint-staged — `.lintstagedrc.json`
234
342
 
235
- 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.
236
344
 
237
345
  ```bash
238
346
  pnpm add -D lint-staged@^17.0.0 prettier@^3.5.3
239
347
  ```
240
348
 
241
- - 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.
242
- - Globs must not overlap: lint-staged runs entries concurrently, so two entries writing one file race. Second entry negates the first.
243
- - 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.
244
353
 
245
- ## Vale — prose lint, with House styles
354
+ ## Vale — prose lint, with Bkit styles
246
355
 
247
- `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.
248
357
 
249
358
  ```bash
250
359
  brew install vale
251
360
  vale sync
252
361
  ```
253
362
 
254
- - Copy `.vale.ini` and all four `.vale/styles/House/*.yml`.
255
- - `.gitignore`: `.vale/styles/write-good` (`vale sync` downloads it; the House styles stay tracked).
256
- - CI: the `bkit-ci.yml` template installs a pinned Vale and runs `vale sync`. Cursor: the `Dockerfile` template installs it.
257
- - Adapt: add `[glob]` scope blocks for your own docs; turn rules off per path, not globally.
258
- - 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.
259
372
 
260
373
  ## slop-scan — `slop-scan.config.json`
261
374
 
262
- `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.
263
376
 
264
377
  ```bash
265
378
  pnpm add -D slop-scan@^0.3.0
@@ -267,13 +380,16 @@ mkdir -p scripts/slop
267
380
  cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
268
381
  ```
269
382
 
270
- - 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.
271
- - Adapt: `ignores` for generated / vendored trees; per-file `overrides` with a reason, never a rule disabled repo-wide.
272
- - 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.
273
389
 
274
390
  ## Oxlint — test-file lint, `.oxlintrc.json`
275
391
 
276
- 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.
277
393
 
278
394
  ```bash
279
395
  pnpm add -D oxlint@^1.87.0 oxlint-tsgolint@^7.0.2004
@@ -286,109 +402,159 @@ Set `lint` to the value in § Gate tool scripts.
286
402
  | Rule | Fails on |
287
403
  | --- | --- |
288
404
  | `vitest/expect-expect` | A test with no assertion. |
289
- | `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. |
290
406
  | `vitest/no-conditional-expect` | An `expect` inside a branch or `catch`: it may never run. |
291
407
  | `vitest/valid-expect` (`maxArgs: 2`) | `expect(x)` with no matcher; more than a value and a message. |
292
408
  | `typescript/no-floating-promises` | A promise nobody awaits: the test ends before its assertion runs. |
293
409
 
294
- - 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.
295
- - `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.
296
- - 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.
297
- - No path argument → lints the working directory. Narrow it (`oxlint … src`); tests outside root `tsconfig.json` → add `--tsconfig <file>`.
298
- - 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.
299
- - 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`.
300
- - Why not ESLint: typescript-eslint's type-aware rules need TypeScript `<6.1`.
301
- - 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.
302
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.
303
425
 
304
426
  ## direnv — `.envrc`
305
427
 
306
- 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.
307
429
 
308
430
  ```bash
309
431
  brew install direnv # then add the shell hook from the link
310
432
  direnv allow
311
433
  ```
312
434
 
313
- - 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.
314
437
 
315
438
  ## Launchd GUI environment — tokens for Dock-launched apps
316
439
 
317
- 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.
318
441
 
319
442
  <!-- prettier-ignore -->
320
443
  | File | Copy from | To | Commit |
321
444
  | --- | --- | --- | --- |
322
445
  | Loader | `.bkit/templates/scripts/launchd/bkit-launchd-env.sh` | `scripts/launchd/bkit-launchd-env.sh` | that file |
323
- | LaunchAgent | `.bkit/templates/scripts/launchd/ai.bkit.launchd.plist` | `~/Library/LaunchAgents/ai.bkit.launchd.plist` | never (machine-local) |
324
- | 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) |
325
448
 
326
449
  ```bash
327
450
  cp .bkit/templates/scripts/launchd/bkit-launchd-env.sh scripts/launchd/
328
451
  chmod +x scripts/launchd/bkit-launchd-env.sh
329
452
  mkdir -p ~/.config/bkit
330
- 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
331
454
  chmod 600 ~/.config/bkit/launchd.env # tokens stay owner-only
332
455
  # fill in the tokens, then place the agent:
333
- 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
334
457
  # replace {{SCRIPT_PATH}} and {{ENV_FILE}} with absolute paths in the copied plist
335
458
  launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist 2>/dev/null || true
336
459
  launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist
337
460
  launchctl getenv BKIT_OPENROUTER_API_KEY # bootstrap proof
338
461
  ```
339
462
 
340
- - `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.
341
- - 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.
342
- - 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.
343
- - 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.
344
- - Loader self-skips (log line + `exit 0`) when the env file is absent or `launchctl` is off `PATH` (Linux CI).
345
- - 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.
346
- - 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.
347
- - `launchctl setenv` reaches apps launched after the load; a running app keeps its environment until relaunch (set and unset alike).
348
- - **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.
349
480
  - Remove: `launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.
350
481
 
351
482
  ## Cursor — `settings.json`, `environment.json`, `Dockerfile`
352
483
 
353
- 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.
354
485
 
355
- - `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.
356
487
  - `environment.json` `install`: `pnpm install --frozen-lockfile`, then `vale sync` when `.vale.ini` exists.
357
488
  - Secrets: Cloud Agents dashboard → Runtime Secrets (`.bkit/cloud.md`).
358
- - 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.
359
492
 
360
493
  ## Dependabot and Renovate
361
494
 
362
- 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.
363
496
 
364
- 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:
365
498
 
366
499
  ```bash
367
500
  gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
368
501
  gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
369
502
  ```
370
503
 
371
- 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.
372
507
 
373
508
  ```bash
374
509
  gh secret set BKIT_GH_TOKEN
375
510
  ```
376
511
 
377
- - 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.
378
- - Examples extend `config:best-practices`; major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`); `lockFileMaintenance` runs monthly; PRs rebase only on conflict.
379
- - 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.
380
- - `bkit-renovate.yml` pins `renovate-version` to an exact release; the same kind of `# renovate:` comment keeps it current.
381
- - `enabled: false` on a Renovate package rule does not stop digest pinning; use `ignorePaths` to keep Renovate off a file.
382
- - Land config on default branch before bot runs. Examples set `baseBranchPatterns: ["dev"]`.
383
- - 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).
384
550
 
385
551
  ## Trivy — vulnerability, config and secret scan
386
552
 
387
- 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/.
388
554
 
389
- 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.
390
556
 
391
- 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:
392
558
 
393
559
  ```yaml
394
560
  vulnerabilities:
@@ -403,34 +569,39 @@ misconfigurations:
403
569
  expired_at: 2026-11-18
404
570
  ```
405
571
 
406
- - Past `expired_at` the finding fails again. Keep it within the fix-time policy (`docs/deployments.md` § Dependency updaters).
407
- - `scripts/ci/check-dependency-audit.mjs` adopted → the scan skips `pnpm-lock.yaml`; accept pnpm advisories in `accepted-advisories.json` only.
408
- - Keep `--include-dev-deps`: without it Trivy drops npm / yarn / pnpm dev dependencies, and a dev-tooling lockfile scans zero packages and passes.
409
- - 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.
410
- - The `.cursor/Dockerfile` template runs as root → `DS-0002`. Add a non-root `USER` or accept it.
411
- - 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>`.
412
580
  - Results print in the job log. Security-tab upload (SARIF) is free on public repos only.
413
581
 
414
582
  ## Serena — symbol lookup
415
583
 
416
- 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.
417
585
 
418
586
  ```bash
419
587
  brew install uv
420
588
  uv tool install -p 3.13 serena-agent
421
589
  ```
422
590
 
423
- PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
424
-
425
- - 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`).
426
- - 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.
427
- - 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).
428
- - `.mcp.json` (Claude Code) calls `scripts/serena/bkit-serena-mcp.sh` → finds binary when GUI app has no login-shell `PATH`.
429
- - Cursor's `.cursor/mcp.json` cannot use that wrapper → point `command` at `${HOME}/.local/bin/serena`, pass `--context ide`.
430
- - 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`.
431
- - 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.
432
- - List `serena` in `.agents/context.md` `mcp-servers` block → every host runs its tools without a prompt; workflow subagents cannot answer one.
433
- - 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.
434
605
 
435
606
  `.gitignore`:
436
607
 
@@ -439,53 +610,62 @@ PyPI name `serena-agent`, CLI `serena`. PyPI `serena` is an unrelated package.
439
610
  !.serena/project.yml
440
611
  ```
441
612
 
442
- - 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.
443
- - `--context codex` still lists excluded tools but refuses each call (`not active`).
444
- - Serena line numbers are 0-based → add 1 before citing `file:line`.
445
- - Small / empty answer for an exported symbol = query did not resolve, not "nothing uses it" → corroborate with text search.
446
- - 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.
447
621
 
448
622
  ## Issue forms — `.github/ISSUE_TEMPLATE/`
449
623
 
450
- 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.
451
625
 
452
626
  <!-- prettier-ignore -->
453
627
  | Form | Use when | Next step | Asks for |
454
628
  | --- | --- | --- | --- |
455
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 |
456
- | `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` as plan 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 |
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 |
457
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 |
458
632
 
459
- - 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`.
460
- - 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 first writes `{FID}-plan.md` from them (`@bkit-build-plan-convert`), then builds its tasks and checks each `TEST FIRST` test failed before its code; an existing `{FID}-plan.md` wins and the issue text is not read; `build:lite` checks nothing. Nothing ticks the boxes.
461
- - Debug commits to the branch it runs on: start it on the branch the fix lands on.
462
- - Copy the folder, commit on the default branch; GitHub reads forms from there only. Blank issues stay enabled.
463
- - `labels:` applies `enhancement` / `bug` only when the repo has them; missing labels are skipped, never created. Never add `bkit:*` labels: workflows own them.
464
- - 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.
465
643
 
466
644
  ## graphify — map
467
645
 
468
- 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.
469
649
 
470
650
  ```bash
471
651
  uv tool install "$(bash scripts/graphify/bkit-graphify.sh spec)"
472
652
  ```
473
653
 
474
- 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.
475
655
 
476
656
  `package.json` scripts:
477
657
 
478
658
  ```json
479
659
  {
480
- "graph": "bash scripts/graphify/bkit-graphify.sh build",
481
- "graph:check": "bash scripts/graphify/bkit-graphify.sh check",
482
- "graph:clean": "bash scripts/graphify/bkit-graphify.sh clean",
483
- "graph:graphml": "bash scripts/graphify/bkit-graphify.sh graphml",
484
- "graph:refresh": "bash scripts/graphify/bkit-graphify.sh refresh",
485
- "graph:rollup": "bash scripts/graphify/bkit-graphify.sh rollup",
486
- "graph:scoped": "bash scripts/graphify/bkit-graphify.sh scoped",
487
- "graph:tree": "bash scripts/graphify/bkit-graphify.sh tree",
488
- "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"
489
669
  }
490
670
  ```
491
671
 
@@ -501,43 +681,76 @@ export GRAPHIFY_OUT=docs/graphify-out
501
681
  graphify-out/
502
682
  ```
503
683
 
504
- - 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`.
505
- - `.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`.
506
- - 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.
507
694
  - `.graphifyignore` merges `.gitignore`.
508
- - Keep `package.json` in corpus — excluding it drops workspace `name` fields graphify resolves package imports with; graph still looks complete.
509
- - Keep `tsconfig.json` out; graphify reads `paths` regardless.
510
- - 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.
511
698
 
512
699
  <!-- prettier-ignore -->
513
700
  | Command | Does |
514
701
  | --- | --- |
515
- | `pnpm graph` | Extract + cluster. Local. No API key. |
516
- | `pnpm graph:clean` | Same, after deleting `docs/graphify-out/`. Required after any tsconfig `paths` change. `--force` does not invalidate the module-resolution cache. |
517
- | `pnpm graph:update` | Re-extract changed files, then recluster. |
518
- | `pnpm graph:rollup` | Package and module views, plus `docs/capabilities.md`. |
519
- | `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. |
520
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. |
521
- | `pnpm graph:refresh` | Rebuild register in a throwaway checkout of HEAD → copy over `docs/capabilities.md`. Fixes a red gate; commit result. |
522
- | `pnpm graph:scoped [path]` | One subtree. Default `apps/web/src`. |
523
- | `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`).
524
718
 
525
- - `docs/graphify-out/` = raw `graph.json`; `docs/graphify-out/reports/` = derived views.
526
- - Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before first rollup (Overrides block must exist) → `pnpm graph:rollup` rewrites it after.
527
- - Add capability → rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. Shipped rules JSON = one example row; replace it.
528
- - 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`.
529
721
 
530
- `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:
531
731
 
532
732
  ```bash
533
733
  npx -y @mermaid-js/mermaid-cli -i docs/graphify-out/reports/graph-packages.mmd -o tmp/graph-packages.svg
534
734
  ```
535
735
 
536
- - `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.
537
- - `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.
538
- - `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.
539
- - 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.
540
- - 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.
541
754
 
542
755
  Do not run:
543
756
 
@@ -548,21 +761,33 @@ Do not run:
548
761
  | `graphify install --project` | Writes a skill. `/bkit-ship` removes skills not named in `.agents/skills.md`. |
549
762
  | `graphify hook install` | Rebuilds on every commit. bkit commits many times per workflow run. |
550
763
 
551
- - Code-graph answer confirms what is present; does not prove what is absent. Missing edge looks like a real gap.
552
- - 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`.
553
766
 
554
767
  ## Secrets sync — one source, every store
555
768
 
556
- 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.
557
770
 
558
- - Copy both files. Edit `bkit-secrets.config.mjs` only; `bkit-secrets.mjs` stays byte-identical across repos.
559
- - 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).
560
- - 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.
561
778
  - `.gitignore`: `scripts/secrets/bkit-secrets-state.json`.
562
- - `.bkit/.env` overlay → agent / bkit tooling secrets only; app and stack credentials stay in app env files.
563
- - 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.
564
- - 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.
565
- - 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).
566
791
 
567
792
  <!-- prettier-ignore -->
568
793
  | Command (`node scripts/secrets/bkit-secrets.mjs …`) | Does |
@@ -573,7 +798,7 @@ Local gitignored env files = source of truth; `bkit-secrets.mjs sync` makes ever
573
798
  | `check [file]` | Local only: sources, env file vs example (exit 2 on a missing required key), every copy of every secret. |
574
799
  | `--store <name>` | Narrow `sync` / `drift` / `list` to one store. Every run covers both environments; no per-environment option. |
575
800
 
576
- `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.
577
802
 
578
803
  How `drift` proves a value without printing it:
579
804
 
@@ -585,16 +810,17 @@ How `drift` proves a value without printing it:
585
810
  | EAS (plaintext / sensitive) | `env:list --include-sensitive` | SHA-256 of live value vs source |
586
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`) |
587
812
 
588
- - No recorded push → `unverified`, never `ok`. First sync records one.
589
- - `bkit-secrets-state.json` = fingerprints + times only, per machine. Push from another machine or by hand → `changed-elsewhere` until next sync here.
590
- - `manual` copies listed on every `check` / `drift`; update by hand on rotation.
591
- - 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.
592
818
 
593
- 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.
594
820
 
595
821
  ## Prettier tables — keep table diffs to the changed row
596
822
 
597
- 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.
598
824
 
599
825
  <!-- prettier-ignore -->
600
826
  | Command | Does |
@@ -602,30 +828,39 @@ Prettier aligns markdown tables with no config toggle; one edited cell re-pads e
602
828
  | `node scripts/prettier/bkit-insert-ignore.mjs` | Rewrite `.agents/`, `docs/`, `README.md` (or the paths given). |
603
829
  | `node scripts/prettier/bkit-insert-ignore.mjs --check` | Write nothing; exit 1 if any file would change. Gate form. |
604
830
 
605
- - 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.
606
- - 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.
607
- - A pipe inside an inline-code span is escaped to `\|` only when that restores the separator's column count; an existing `\|` stays literal.
608
- - 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.
609
839
 
610
840
  ## tmp/ prune — old scratch files
611
841
 
612
- 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.
613
843
 
614
844
  ```bash
615
845
  mkdir -p scripts/cleanup
616
846
  cp .bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs scripts/cleanup/
617
847
  ```
618
848
 
619
- - 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.
620
- - Not a gate: a failed prune prints a warning; the push goes on.
621
- - `--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.
622
- - Scope: `tmp/` at the top of the checkout the cwd sits in; each worktree prunes its own. `tmp/` itself stays.
623
- - 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.
624
859
  - Hand run: `node scripts/cleanup/bkit-tmp-prune.mjs`. Files to keep belong outside `tmp/`.
625
860
 
626
861
  ## Disk prune — cleanup steps you own
627
862
 
628
- `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.
629
864
 
630
865
  ```bash
631
866
  mkdir -p scripts/cleanup ~/.config/bkit
@@ -639,34 +874,72 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
639
874
  | `scripts/cleanup/bkit-disk-prune.mjs` | this checkout: build caches, leftover agent worktrees | checkout top, first | yes |
640
875
  | `~/.config/bkit/disk-prune.mjs` (`$XDG_CONFIG_HOME/bkit/` when set) | shared tools: Docker, pnpm store, Xcode, Gradle, simulators | home folder | never |
641
876
 
642
- - 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.
643
- - 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.
644
- - 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.
645
- - 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).
646
- - 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.
647
- - `--auto`: detached, always exit 0. Each mode at most once a day per machine; `max` at most hourly while free disk < `bkit.workflows.minFreeGb` (`package.json`, GB, default 40). Log: `~/.cache/bkit/disk-prune.log` (`$XDG_CACHE_HOME/bkit/` when set).
648
- - Worktrees: `bkit worktrees setup` create / resume under `bkit.workflows.minFreeGb` → runs `max` steps, waits. Still under → exit 12, nothing created; stderr lists what `max` steps still cover. No step file → no check.
649
- - One sweep per machine at a time (`disk-prune.lock` beside the log). Failed step → logged, next runs. CI / cloud → nothing runs.
650
- - 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.
651
-
652
- ## Local stack lock — one run at a time on a shared stack
653
-
654
- 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`.
655
911
 
656
912
  ```bash
657
913
  mkdir -p scripts/ci
658
- cp .bkit/templates/scripts/ci/bkit-local-stack-lock.sh scripts/ci/
914
+ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
659
915
  ```
660
916
 
661
917
  <!-- prettier-ignore -->
662
918
  | Wire into | How | Holds the lock |
663
919
  | --- | --- | --- |
664
- | `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 |
665
- | 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` |
666
-
667
- - 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`.
668
- - 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.
669
- - Lock file: `~/.cache/bkit/local-stack-lock/<name>.lock` (`$XDG_CACHE_HOME/bkit/` when set), outside every checkout.
670
- - Never stale: a small perl process holds the lock (flock) and exits within a second of its caller, however the caller ends.
671
- - 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.
672
- - 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.