@cbartens/bkit 0.0.0-stage → 5.0.1

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 +417 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +417 -0
  8. package/.bkit/core/.bkit/cloud.md +493 -0
  9. package/.bkit/core/.bkit/comparison.md +321 -0
  10. package/.bkit/core/.bkit/install.md +401 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +470 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1550 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +149 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +701 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +530 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/suppression.ts +53 -0
  70. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +187 -0
  73. package/.bkit/core/engine/checks/before/files.ts +204 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +867 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +254 -0
  86. package/.bkit/core/engine/commands/install/install.ts +550 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +995 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1037 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +495 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +924 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +173 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +620 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/payload-links.ts +150 -0
  124. package/.bkit/core/engine/install/placeholders.ts +108 -0
  125. package/.bkit/core/engine/install/template-copies.ts +119 -0
  126. package/.bkit/core/engine/install/version-file.ts +284 -0
  127. package/.bkit/core/engine/install/write.ts +467 -0
  128. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  129. package/.bkit/core/engine/ledgers/status.ts +213 -0
  130. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  131. package/.bkit/core/engine/render/hosts.ts +372 -0
  132. package/.bkit/core/engine/render/models.ts +323 -0
  133. package/.bkit/core/engine/render/parts.ts +38 -0
  134. package/.bkit/core/engine/render/trackers.ts +170 -0
  135. package/.bkit/core/engine/shared/egress.ts +345 -0
  136. package/.bkit/core/engine/shared/json.ts +16 -0
  137. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  138. package/.bkit/core/engine/shared/package-json.ts +29 -0
  139. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  140. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  141. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  142. package/.bkit/core/engine/shared/settings.ts +72 -0
  143. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  144. package/.bkit/core/engine/tools/wording.ts +748 -0
  145. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  146. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  147. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  148. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  149. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  150. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  155. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  156. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  157. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  158. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  159. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  160. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  161. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  162. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  165. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  166. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  169. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  170. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  171. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  172. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  173. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  174. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  175. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  176. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  178. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  179. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  180. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  181. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  182. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  185. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  186. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  187. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  188. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  189. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  198. package/.bkit/core/workflows/bkit-auto.md +121 -0
  199. package/.bkit/core/workflows/bkit-build.md +802 -0
  200. package/.bkit/core/workflows/bkit-debug.md +649 -0
  201. package/.bkit/core/workflows/bkit-design.md +495 -0
  202. package/.bkit/core/workflows/bkit-plan.md +510 -0
  203. package/.bkit/core/workflows/bkit-ship.md +650 -0
  204. package/.bkit/shared/.bkit/.env.example +86 -0
  205. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  206. package/.bkit/shared/.claude/settings.json +88 -0
  207. package/.bkit/shared/.codex/hooks.json +26 -0
  208. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  209. package/.bkit/shared/.cursor/hooks.json +26 -0
  210. package/.bkit/shared/.cursor/mcp.json +15 -0
  211. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  212. package/.bkit/shared/.gitattributes +37 -0
  213. package/.bkit/shared/.mcp.json +16 -0
  214. package/.bkit/shared/.opencode/opencode.json +62 -0
  215. package/.bkit/shared/CLAUDE.md +11 -0
  216. package/.bkit/shared/LICENSE.md +22 -0
  217. package/.bkit/shared/docs/architecture.md +19 -0
  218. package/.bkit/shared/docs/data-schema.md +19 -0
  219. package/.bkit/shared/docs/deployments.md +433 -0
  220. package/.bkit/shared/docs/design.md +39 -0
  221. package/.bkit/shared/docs/noise.md +19 -0
  222. package/.bkit/shared/docs/observability.md +25 -0
  223. package/.bkit/shared/docs/security.md +42 -0
  224. package/.bkit/shared/docs/setup.md +30 -0
  225. package/.bkit/shared/docs/technology.md +18 -0
  226. package/.bkit/shared/docs/testing.md +413 -0
  227. package/.bkit/shared/gitignore +97 -0
  228. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +187 -0
  229. package/.bkit/templates/.cursor/Dockerfile +68 -0
  230. package/.bkit/templates/.cursor/environment.json +6 -0
  231. package/.bkit/templates/.cursor/settings.json +11 -0
  232. package/.bkit/templates/.envrc +7 -0
  233. package/.bkit/templates/.github/dependabot.yml +52 -0
  234. package/.bkit/templates/.github/renovate.json5 +224 -0
  235. package/.bkit/templates/.github/workflows/bkit-ci.yml +1062 -0
  236. package/.bkit/templates/.github/workflows/bkit-cloud.yml +564 -0
  237. package/.bkit/templates/.github/workflows/bkit-renovate.yml +102 -0
  238. package/.bkit/templates/.graphifyignore +108 -0
  239. package/.bkit/templates/.husky/pre-commit +16 -0
  240. package/.bkit/templates/.husky/pre-push +91 -0
  241. package/.bkit/templates/.lintstagedrc.json +3 -0
  242. package/.bkit/templates/.prettierignore +41 -0
  243. package/.bkit/templates/.serena/project.yml +243 -0
  244. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  245. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  246. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  247. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  248. package/.bkit/templates/.vale.ini +67 -0
  249. package/.bkit/templates/LICENSE.md +22 -0
  250. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  251. package/.bkit/templates/context/bkit-expo.md +186 -0
  252. package/.bkit/templates/context/bkit-github.md +79 -0
  253. package/.bkit/templates/context/bkit-inngest.md +45 -0
  254. package/.bkit/templates/context/bkit-maestro.md +76 -0
  255. package/.bkit/templates/context/bkit-playwright.md +62 -0
  256. package/.bkit/templates/context/bkit-resend.md +36 -0
  257. package/.bkit/templates/context/bkit-sentry.md +65 -0
  258. package/.bkit/templates/context/bkit-serena.md +33 -0
  259. package/.bkit/templates/context/bkit-stripe.md +36 -0
  260. package/.bkit/templates/context/bkit-supabase.md +59 -0
  261. package/.bkit/templates/context/bkit-tavily.md +49 -0
  262. package/.bkit/templates/context/bkit-vercel.md +64 -0
  263. package/.bkit/templates/docs/capabilities.md +72 -0
  264. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  266. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  268. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  280. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  281. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  282. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  283. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  284. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  286. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  288. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  289. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  290. package/.bkit/templates/slop-scan.config.json +120 -0
  291. package/CHANGELOG.md +1503 -0
  292. package/LICENSE.md +161 -0
  293. package/README.md +184 -2
  294. package/dist/checks/after/auth.js +140 -0
  295. package/dist/checks/after/ci-yml.js +681 -0
  296. package/dist/checks/after/github.js +400 -0
  297. package/dist/checks/after/index.js +431 -0
  298. package/dist/checks/after/managed.js +187 -0
  299. package/dist/checks/after/suppression.js +39 -0
  300. package/dist/checks/after/tools.js +351 -0
  301. package/dist/checks/before/context-fetch.js +426 -0
  302. package/dist/checks/before/env.js +163 -0
  303. package/dist/checks/before/files.js +187 -0
  304. package/dist/checks/before/index.js +162 -0
  305. package/dist/checks/before/mcp.js +111 -0
  306. package/dist/checks/before/repo.js +71 -0
  307. package/dist/checks/before/version.js +60 -0
  308. package/dist/checks/status-holes.js +393 -0
  309. package/dist/cli.js +688 -0
  310. package/dist/commands/analysis.js +325 -0
  311. package/dist/commands/ci/ci.js +438 -0
  312. package/dist/commands/comply.js +310 -0
  313. package/dist/commands/harvest.js +354 -0
  314. package/dist/commands/install/check.js +61 -0
  315. package/dist/commands/install/doctor.js +209 -0
  316. package/dist/commands/install/install.js +475 -0
  317. package/dist/commands/install/uninstall.js +839 -0
  318. package/dist/commands/install/upgrade.js +782 -0
  319. package/dist/commands/launch.js +118 -0
  320. package/dist/commands/lib.js +363 -0
  321. package/dist/commands/registry.js +50 -0
  322. package/dist/commands/setup/setup.js +158 -0
  323. package/dist/commands/telemetry.js +29 -0
  324. package/dist/commands/workflow/branches.js +1265 -0
  325. package/dist/commands/workflow/context.js +846 -0
  326. package/dist/commands/workflow/counters.js +227 -0
  327. package/dist/commands/workflow/fids.js +224 -0
  328. package/dist/commands/workflow/issues.js +585 -0
  329. package/dist/commands/workflow/ledgers.js +472 -0
  330. package/dist/commands/workflow/locks.js +364 -0
  331. package/dist/commands/workflow/prs.js +904 -0
  332. package/dist/commands/workflow/repo.js +199 -0
  333. package/dist/commands/workflow/roadmap.js +495 -0
  334. package/dist/commands/workflow/runs.js +1717 -0
  335. package/dist/commands/workflow/runtime.js +257 -0
  336. package/dist/commands/workflow/skills.js +110 -0
  337. package/dist/commands/workflow/status.js +392 -0
  338. package/dist/commands/workflow/steps.js +1093 -0
  339. package/dist/commands/workflow/tests.js +144 -0
  340. package/dist/commands/workflow/workflows.js +1342 -0
  341. package/dist/commands/workflow/workstreams.js +141 -0
  342. package/dist/commands/workflow/worktrees.js +473 -0
  343. package/dist/install/cloud-env.js +818 -0
  344. package/dist/install/managed-block.js +182 -0
  345. package/dist/install/manifest.js +376 -0
  346. package/dist/install/modules/claude.js +288 -0
  347. package/dist/install/modules/cloud.js +151 -0
  348. package/dist/install/modules/codex.js +193 -0
  349. package/dist/install/modules/core.js +531 -0
  350. package/dist/install/modules/cursor.js +186 -0
  351. package/dist/install/modules/index.js +152 -0
  352. package/dist/install/modules/opencode.js +504 -0
  353. package/dist/install/payload-links.js +119 -0
  354. package/dist/install/placeholders.js +87 -0
  355. package/dist/install/template-copies.js +106 -0
  356. package/dist/install/version-file.js +204 -0
  357. package/dist/install/write.js +342 -0
  358. package/dist/ledgers/clamp-log.js +27 -0
  359. package/dist/ledgers/status.js +156 -0
  360. package/dist/ledgers/telemetry.js +637 -0
  361. package/dist/render/hosts.js +339 -0
  362. package/dist/render/models.js +288 -0
  363. package/dist/render/parts.js +33 -0
  364. package/dist/render/trackers.js +135 -0
  365. package/dist/shared/egress.js +299 -0
  366. package/dist/shared/json.js +16 -0
  367. package/dist/shared/log-prefix.js +7 -0
  368. package/dist/shared/package-json.js +22 -0
  369. package/dist/shared/package-manager.js +32 -0
  370. package/dist/shared/package-roots.js +145 -0
  371. package/dist/shared/protected-paths.js +153 -0
  372. package/dist/shared/settings.js +44 -0
  373. package/dist/shared/timeouts.js +19 -0
  374. package/dist/tools/wording.js +680 -0
  375. package/package.json +101 -4
@@ -0,0 +1,30 @@
1
+ <!-- bkit:start -->
2
+
3
+ {{BKIT_MANAGED_MARKER}}
4
+
5
+ # Setup
6
+
7
+ > [!CAUTION]
8
+ > **Purpose:** Local dev — CLIs, configuration, secrets, troubleshooting. Humans only.
9
+ >
10
+ > **Rules:**
11
+ >
12
+ > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
+ > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
14
+ > - Describe current state / rules, not reasons / history; state what to do, not why.
15
+ > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
+ > - Local seed / test fixtures must never run against remote projects.
17
+
18
+ ## Templates
19
+
20
+ Optional, copy and own, never installed. Catalog and install steps: `.bkit/templates.md`.
21
+
22
+ ## Agent hosts
23
+
24
+ Run each host (`claude`, `opencode`, `codex`) in its own terminal window — not inside an IDE or a desktop app.
25
+
26
+ - Separate processes: restart one host without quitting the others.
27
+ - Terminal sessions inherit the direnv-loaded `.bkit/.env`; GUI-launched apps do not (`.bkit/providers.md` § macOS GUI-isolation).
28
+ - macOS: [Ghostty](https://ghostty.org).
29
+
30
+ <!-- bkit:end -->
@@ -0,0 +1,18 @@
1
+ <!-- bkit:start -->
2
+
3
+ {{BKIT_MANAGED_MARKER}}
4
+
5
+ # Technology
6
+
7
+ > [!CAUTION]
8
+ > **Purpose:** Chosen frameworks, libraries, styling systems, coding conventions. WHY a choice was made → `decisions.jsonl`.
9
+ >
10
+ > **Rules:**
11
+ >
12
+ > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
+ > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
14
+ > - Describe current state / rules, not reasons / history; state what to do, not why.
15
+ > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
+ > - List technology and usage; **Why** → `decisions.jsonl`.
17
+
18
+ <!-- bkit:end -->
@@ -0,0 +1,413 @@
1
+ <!-- bkit:start -->
2
+
3
+ {{BKIT_MANAGED_MARKER}}
4
+
5
+ # Testing
6
+
7
+ > [!CAUTION]
8
+ > **Purpose:** Testing strategy — tier boundaries, framework choices, naming conventions, CI execution.
9
+ >
10
+ > **Rules:**
11
+ >
12
+ > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
13
+ > - Notation: one job per mark — `.bkit/prompts.md` § `Notation`.
14
+ > - Describe current state / rules, not reasons / history; state what to do, not why.
15
+ > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
16
+ > - Tiers strictly separated — Static · Unit · Integration · E2E · @live · Smoke.
17
+ > - Pre-push: `pnpm bkit:gate:static-unit`, then `bkit check`; the `.husky/pre-push` template runs `bkit:gate:static` (no tests) on revert branches / commits. Gate scripts are consumer-owned; bkit's default = typecheck + lint + format:check + prose + slop:delta + `pnpm test` (unit + in-process integration). E2E, @live, service-backed integration excluded (CI — see below). never `--no-verify`.
18
+
19
+ ## CI test tiers (the bkit scaffold)
20
+
21
+ CI runs tiers through bkit scaffold — **one parallel lane (job) per tier**, not steps in one job (step-by-step: `.github/workflows/bkit-ci.yml` § "full CI scaffold reference"; run-level shape: `deployments.md` § Run-level decision matrix).
22
+
23
+ Graph **flat and wide** for static / unit / build / integration: scope fans out; capstone joins. **One exception:** when `bkit-tests-migration` owns the shared-remote migration apply, e2e / live `needs:` that lane (ordering) — never gate live behind static / unit / build / e2e:
24
+
25
+ ```
26
+ bkit-tests-scope ─┬─ bkit-tests-static
27
+ always-on ├─ bkit-tests-unit
28
+ never skips ├─ bkit-tests-build-web ─────────────────────┐
29
+ (~15s) ├─ bkit-tests-integration │
30
+ ├─ bkit-tests-build-ios │
31
+ ├─ bkit-tests-build-android │
32
+ └─ bkit-tests-migration ─┬─→ bkit-tests-deploy (default-branch push only; promotes)
33
+ │ │
34
+ │ ▼
35
+ └─→ bkit-tests-reset ─┬─→ bkit-tests-e2e-web
36
+ (lease) ├─→ bkit-tests-live-web
37
+ ├─→ bkit-tests-e2e-ios
38
+ └─→ bkit-tests-e2e-android
39
+ │
40
+ ▼
41
+ bkit-tests-cleanup (always(); releases the lease)
42
+ │
43
+ ▼
44
+ bkit-tests-check (needs: scope + every lane you have, deploy included)
45
+
46
+ static/unit/integration/build-*: needs:[bkit-tests-scope]; if: run_level != 'none'
47
+ bkit-tests-migration: needs:[bkit-tests-scope]; no job-level if (always-on)
48
+ bkit-tests-deploy: needs:[bkit-tests-migration, bkit-tests-build-web]; default-branch push only
49
+ bkit-tests-reset: needs:[scope, migration]; if: tenant_target != ''
50
+ e2e-web / live-web / e2e-ios / e2e-android:
51
+ needs:[scope, migration, deploy, reset, <build>];
52
+ if: !cancelled() && scope==success && <own gate>
53
+ && migration != 'failure' && deploy != 'failure'
54
+ && reset != 'failure'
55
+ ```
56
+
57
+ Adopt only lanes your repo has. Add a lane the moment its tier exists, because a tier with no lane is a tier nothing gates. The jobs above the reference in `bkit-ci.yml` are the starter: `bkit-tests-static` and `bkit-tests-unit`, joined by the `bkit-tests-check` capstone `/bkit-ship` merges on. Every lane you add joins the capstone's `needs:` and its assert. The reference is the target. A starter stub that still sits inside `bkit-tests-unit` is the pre-split shape.
58
+
59
+ Adopt in this order. Stop at the first tier this repo does not have. You write the step bodies; these files name the job, the `needs`, the `if`, and the rule.
60
+
61
+ 1. Keep `bkit-tests-static` and `bkit-tests-unit`.
62
+ 2. Add `bkit-tests-scope`. Every later `if:` reads `plan`. One marker parse. Push base = last green run (`deployments.md` § One run).
63
+ 3. Move integration out of unit into `bkit-tests-integration`.
64
+ 4. Add `bkit-tests-build-web`. Compile, or create this SHA's deployment and publish `deployment_url` + `deployment_id` un-promoted on the default branch. Do not also enable `bkit-stub:vercel-await`.
65
+ 5. Add `bkit-tests-migration` when you have migrations. Remote apply of new migrations (e.g. `supabase db push --linked --include-all`) lives here, after the from-empty replay. On the default branch it waits for static / unit / integration / `build-web` before touching production's database. Immutability and slop-delta use the planner base on every event.
66
+ 6. Add `bkit-tests-reset` / `-cleanup` only when two or more lanes share one long-lived resource. Otherwise provision fresh and drop both.
67
+ 7. Add `bkit-tests-e2e-web`. Full suite on a PR and on a push. Feature → `dev` PR hits a local stack. `TEST_URL` only. A pass on retry is a failure.
68
+ 8. Add device build and device E2E only for a platform you ship. Same rule on a PR, a push, and a dispatch. `bkit-tests-e2e-ios` needs `build-ios` and `build-web`; android the same with its build lane.
69
+ 9. Add `bkit-tests-live-web` for a push to `dev` or the default branch when `web_affected`. Not a PR. Not a dispatch. Do not `needs:` static, unit, integration, or e2e.
70
+ 10. `bkit-tests-check` `needs:` every lane you kept. Sole required check. The assert is a script (§ Validated means executed).
71
+ 11. `bkit-tests-deploy` on a default-branch push, **before** the E2E / `@live` lanes. Promotes that exact `deployment_id`; each tenant lane `needs:` it and refuses unless production serves this run's build. Not a required check (`deployments.md` § Promote before the lanes).
72
+ 12. Health is `health.yml`, `workflow_run` after that CI success. A logging probe is a step inside each runtime lane, not a job.
73
+
74
+ Scripts these files do not ship, so the plan names them and you write them: marker parser, capstone assert, lease acquire and release. The last-green push base ships as a template (`.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs`, copied to `scripts/ci/lanes/`).
75
+
76
+ - **`bkit-tests-scope`** (always-on) computes `run_level` (+ optional `run_migration`) + emits `bkit-test-plan` contract — what should run.
77
+ - **`bkit-tests-static` / `-unit` / `-integration` / `-e2e-web`** — one **lane per tier**, separate parallel jobs. A platform suffix (`-web` / `-ios` / `-android`) is required when that tier exists for more than one platform; `static` / `unit` / `integration` / `migration` stay bare. Integration / web E2E gate on `web_affected` / `run_e2e`; each lane emits executed-count for capstone and (coverage tiers) posts own coverage comment. Start `-static` + `-unit`, add lane per tier (`deployments.md` § Parallel test lanes). E2E: do **not** put remote migration apply here, because that lives in `-migration`. Web E2E on a feature → `dev` PR hits a local stack with this PR's migrations; every other event hits the deployment. Same outcome rules everywhere (retries, traces, flake handling). A pass on retry is a failure. Target from `TEST_URL` alone. No spec filtered by tag.
78
+ - **`bkit-tests-migration`** (optional; DB repos) — always-on ordering + provisioning lane: (1) fresh-DB replay + seed assert (plan- / path-gated per-step); (2) on every push to `dev`/`main`, remote apply of new migrations (e.g. `supabase db push --linked --include-all`) (un-gated by `run_migration`, so it self-heals a remote left behind). No job-level `if:`, because e2e / live `needs:` it; a skip would cascade. Capstone asserts `success` whenever scope succeeded. See § Provision backing services fresh.
79
+ - **`bkit-tests-build-web`** — web compile, or the host deployment gate (e.g. Vercel: create this SHA's deployment, publish `deployment_url` + `deployment_id`, leave it un-promoted on the default branch). Emits no `*_ran`.
80
+ - **`bkit-tests-build-ios` / `-e2e-ios` / `bkit-tests-build-android` / `-e2e-android`** (optional) — device build and device flows. Same rule on a PR, a push, and a dispatch: not a post-merge canary. `bkit-tests-e2e-ios` `needs:` scope, migration, reset, `bkit-tests-build-ios`, and `bkit-tests-build-web`. Android matches, with `bkit-tests-build-android`. A planned red reds the capstone. Drop any platform you do not ship. e.g. a hosted build service plus a device-flow runner.
81
+ - **`bkit-tests-live-web`** runs `@live` against the deployed URL (`run_live`; drop the job if no deploy). Push to `dev` or the default branch only, when `web_affected`. Not a pull request. Not a dispatch. `needs:` planner + migration + reset + `bkit-tests-build-web`. Do **not** gate behind static / unit / integration / e2e. A planned failure reds the capstone. `/bkit-ship` still filters a job named `bkit-tests-live`; this name does not match, so the capstone is the gate.
82
+ - **`bkit-tests-reset` / `bkit-tests-cleanup`** (optional; one shared long-lived resource) — reset takes the lease and puts the resource in its known state **before** any lane uses it; cleanup runs last, `if: always()`, and releases the lease. Planner names at most one target. Empty target skips both. Capstone reds if a planned reset skipped or either job failed. DROP both when the resource is provisioned fresh per run (§ Provision backing services fresh — the preferred answer).
83
+ - **Logging probe** (optional step, not a lane) — inside each runtime lane, emit one marked event and ask the error tracker whether it arrived. e.g. Sentry. Skip when that lane did not run the probe.
84
+ - **`bkit-tests-deploy`** (optional) — on a push to the default branch only, **before** the E2E / `@live` lanes. Promotes the exact `deployment_id` `bkit-tests-build-web` published; each tenant lane `needs:` it and starts by proving production serves this run's build (by deployment id). Carries its own `concurrency:` group (`cancel-in-progress: false`) and is not a required check. A red job means the previous deployment stays live.
85
+ - **Health** (optional, separate workflow) — `workflow_run` after CI succeeds on the default branch; smoke the deployment this SHA promoted. Not a required check. Copy the stub to `.github/workflows/health.yml`.
86
+ - **`bkit-tests-check`** capstone — `needs:` **all** lanes; fails if any expected tier skipped or executed zero → green required check = **validated**, not merely "nothing failed". Sole branch-protection required check.
87
+
88
+ ### Accepted divergences
89
+
90
+ CI branches on the event in a few places. Each is a deliberate, recorded divergence from "one script runs everywhere" — not an accident. Every such site is registered so a new one is caught.
91
+
92
+ **The guard.** A step that reads an event field (`github.event_name`, `github.ref`, `github.ref_name`, `github.base_ref`, `github.head_ref`, `github.event.head_commit.message`, `github.event.pull_request.title`) — and, by extension, a script / hook / test that reads `CI` or `GITHUB_*` or takes the pre-push revert path — must be listed in the registry (`scripts/ci/accepted-divergences.json`) with its decision and reason. The guard (`scripts/ci/check-accepted-divergences.mjs`) reds on an unregistered site, on a registered site that no longer exists, and on a decision missing from the table below. A new comparison inside an already-registered step is a new site.
93
+
94
+ <!-- prettier-ignore -->
95
+ | Decision | Rule |
96
+ | --- | --- |
97
+ | `one-run-per-branch` | Concurrency key is the PR number, else the ref; the default branch queues, every other event cancels the older run. |
98
+ | `diff-base` | A PR plans against its base. A push plans against the branch's last green run. |
99
+ | `pr-affected-only` | A PR runs lint, typecheck, format, unit, and integration for affected packages. A push runs everything. |
100
+ | `b1-local-e2e-on-pr` | A feature → `dev` PR's web E2E hits a local stack with this PR's migrations. Every other event hits the deployment. |
101
+ | `b3-live-push-only` | `@live` runs on `dev` / default-branch pushes and on dispatch only. |
102
+ | `b4-remote-db-push` | Only `dev` / default-branch pushes apply migrations to a shared remote database. A PR never does. |
103
+ | `main-basic-lanes-before-production-migration` | On a default-branch push, `bkit-tests-migration` waits for static / unit / integration / `build-web` before it pushes production's migrations. |
104
+ | `release-promotes-first` | On a default-branch push the release promotes production before the E2E / `@live` lanes run; each refuses unless production serves this run's build. |
105
+ | `promotion-lag` | A `dev` push notes when the default branch lags. It tests nothing. |
106
+ | `ci-fresh-stack` | The local integration runner resets its database. CI's volume is already empty. Both start from the same state. |
107
+ | `local-runner-stands-down` | The laptop E2E entrypoints are no-ops under `CI`. |
108
+ | `human-confirmation` | A laptop reset of a remote tenant needs an explicit yes. The CI run is the approval. |
109
+ | `revert-recovery` | A revert push skips the pre-push unit and integration tiers. CI still runs every tier. |
110
+ | `output-channel` | CI prints annotations and job summaries. A terminal prints lines. |
111
+ | `ci-strict-time-limits` | Unit time limits grow with a laptop's load, re-read as each test file starts so a mid-run ramp cannot starve late files. Under `CI` they stay fixed. |
112
+ | `playwright-outcomes` | Same retries, traces, and flake handling on every machine. A pass on retry is a failure. The target comes from `TEST_URL` alone. No spec is filtered by tag. |
113
+
114
+ ### Which resources may each lane touch?
115
+
116
+ Every lane must **declare** what it may reach; declaration enforced by lane env — not by comment. Lane that can reach shared remote instance eventually will → cross-run interference, not failure.
117
+
118
+ <!-- prettier-ignore -->
119
+ | Lane | Real external APIs | Stateful backing service (DB / cache / queue) | Deployed app |
120
+ | --- | --- | --- | --- |
121
+ | `bkit-tests-static` | none | none | none |
122
+ | `bkit-tests-unit` | none — **mocked** | none | none |
123
+ | `bkit-tests-build-web` | none | none | creates this SHA's deployment; does not promote it |
124
+ | `bkit-tests-build-ios` / `-android` | the build host (e.g. a device-build service) | none | none |
125
+ | `bkit-tests-integration` | none — **mocked** | **ephemeral, CI-local, fresh each run** | none |
126
+ | `bkit-tests-migration` | none | **ephemeral, replayed from EMPTY** (plan- / path-gated) + **shared remote push** on every `dev`/`main` push | none |
127
+ | `bkit-tests-reset` / `-cleanup` | none | the **one** shared long-lived resource this run named | none |
128
+ | `bkit-tests-e2e-web` | none — **mocked** | ephemeral **local** (feature → `dev` PR) / the leased shared one (other events) | this SHA's deployment |
129
+ | `bkit-tests-e2e-ios` / `-android` | the device host | the leased shared resource | the deployed backend |
130
+ | `bkit-tests-live-web` | **real** | the deployed environment's **real** instance | **real** deployed URL |
131
+ | `bkit-tests-deploy` | the host API | none | promotes the deployment the tenant lanes then test |
132
+
133
+ Read table as rule: **`bkit-tests-live-web` and the device E2E lanes are the lanes that may spend real external quota**; **only those, plus push-side `-e2e-web`, may touch the shared long-lived resource**, and only between reset and cleanup. Everything else provisions its own (§ Provision backing services fresh).
134
+
135
+ > [!IMPORTANT]
136
+ > **"Real external API" and "real remote backing service" are two INDEPENDENT axes — never one flag.**
137
+ > Most expensive mistake in this doc. Single overloaded gate (`LIVE_API`, `TEST_REAL`, …) meaning both "hit real third-party APIs" and "hit real remote database" collapses unrelated needs. Real consumer result: **10 suites needing ONLY real DB (no external API) sat in serial push-only `@live` lane** — invisible on PRs, inflated gating lane. Moving to `-integration` (ephemeral local DB): `@live` 86→44 tests, PR coverage for first time. Gate each axis on what it needs: external-boundary test → API credential; DB test → DB URL (prefer **ephemeral** — no gate needed).
138
+
139
+ **Moving suite between lanes = three edits; third bites.** Retag file, move to new lane — **delete old gate**. Suite with `skipIf(!LIVE_API)` in lane that doesn't set `LIVE_API` **silently skips forever** — green lane, plausible count, coverage gone (hollow-green via back door, § Validated means executed). After lane move: assert destination executed count **up** by moved test count.
140
+
141
+ **Missing gate variable → honest detectable skip — never silent pass.** Tier needing URL / credential run lacks must report skipped (and, if planned, fail capstone), not exit 0 having run nothing. Per-file assert where it matters — e.g. (Vitest JSON) `numPassedTests >= 1 && numPendingTests === 0` — catches ghost-green no-op and quiet skip.
142
+
143
+ ### Validated means executed, not "didn't fail"
144
+
145
+ Green capstone = planned tiers ran tests and passed — not merely nothing visibly failed. Three states per tier, gated independently:
146
+
147
+ - **Absent** — no declared entrypoint (e.g. a `test:integration` / `test:live` script, an enabled E2E step). The capstone asserts nothing; a repo with no integration / E2E / `@live` tier is fully valid (bkit's own repo has none).
148
+ - **Declared + planned to run** — assert the tier ran **and** executed **> 0** tests. This closes the green-with-zero hole: `--passWithNoTests` matching nothing, a `@live`-tagged suite whose owning package declares no live entrypoint (e.g. no `test:live` script, so `turbo run test:live` runs nothing), or every test `skipIf`-gated off, so all exit 0 and look green.
149
+ - **Declared + correctly skipped** (light run / not `web_affected`) — assert it was skipped, not vacuously passed.
150
+
151
+ A declared tier therefore emits an **executed count** (a runner's machine summary — e.g. vitest `numPassedTests + numFailedTests`); the capstone asserts `count > 0` for every declared-and-planned tier. The same rule at install time is "every tagged suite has a CI home": each `@live`-tagged test must live in a package whose declared entrypoint (e.g. a `test:live` script) the tier actually invokes, or the tag is dead code.
152
+
153
+ **The assert is a script, not a heredoc in the workflow.** It is the only required check, and a shell heredoc inside YAML cannot be unit-tested. Move the decision into a script the normal test command already runs, with the environment as an argument. Four cases must red: a lane that failed; a gated lane that ran when its gate said skip; a tier reporting success with zero tests; a plan that will not parse. The checkout that fetches that script is ungated and not `continue-on-error`. A checkout gated on `run_level == 'full'` leaves every other run with no script, and the required check exits on "cannot find module" without reading the plan.
154
+
155
+ **Namespace.** `bkit-tests-scope` is the planner. A loop over every `bkit-tests-*` job skips it, and a scope failure then leaves the capstone green. Exempt `bkit-tests-scope`, `bkit-tests-reset`, and `bkit-tests-cleanup` by name from any guard that treats every `bkit-tests-*` job as a counting lane. Point branch protection at `bkit-tests-check`.
156
+
157
+ **A per-tier count won't catch a file that stops running everywhere.** `count > 0` proves each tier ran tests; it does not prove every test file ran in some lane. A file renamed out of its glob, moved to a lane whose filter excludes it, or left carrying a stale `skipIf` (the lane-move trap above) can quietly stop executing in **every** lane — each lane green, each count still plausible. The capstone is the only job that `needs:` every lane, so it is the only place to answer this, on the **union**: reconcile the on-disk test-file inventory against the set of files that executed across all lanes. Skipped in one lane but run in another is fine, but only **dead in every lane** is the bug. Its checkout stays `continue-on-error` and must not be the script checkout above. Keep it a **non-blocking** diagnostic (it must never red the required check) and **full-runs-only** (a PR's unit lane is affected-scoped, and `bkit-tests-live-web` is absent, so the PR delta is expected and large — a cry-wolf guard gets turned off); start report-only, then flip to an assert once the allowlist of legitimately-never-run files is seeded from a real inventory.
158
+
159
+ **Executed is not the same as exercised.** `count > 0` proves a test ran; it does not prove the test reached the behaviour it claims to cover. A **hollow boundary test** — non-mock, owns a CI home, executes, passes — can still cover nothing if it short-circuits before the boundary. Worked example: a golden test for an external OCR lane called the extractor with the wrong argument shape, so the input field was `undefined`, the extractor returned `{ text: "", extractor: "none" }` in ~2ms, **no API call was ever made**, and the assertion (on a field that didn't exist) was never reached — green in CI, covering zero. A boundary test must therefore assert a **ground-truth signal only the real boundary can produce** — a specific returned value / shape / identity / latency floor (e.g. `extractor === "mistral-ocr"` and `text.length > 50`), never "did not throw" or a value a degenerate / short-circuit path could also return. Two corollaries: (1) when a deploy / `@live` tier exists, route external / deployed-boundary behaviours (3rd-party API, model, payment, deployed schema, RLS / tenancy) to `@live`, because a passing local fixture is not evidence prod is correct (§ Schema-invariant DB checks); (2) type-system escapes at a boundary call-site are forbidden — e.g. TS `as unknown as` / `as any` casts and `@ts-ignore` / `@ts-nocheck` / `@ts-expect-error` directives, Python `# type: ignore`, alike, because they suppress the contract drift (a renamed SDK field, a changed signature) the boundary test exists to catch, so the bug ships while the test passes against the wrong shape.
160
+
161
+ **Never manufacture a vacuous green.** A pass-with-no-tests option (e.g. `passWithNoTests: true` / `--passWithNoTests`) makes a runner report PASS with zero tests run — the exact hole the executed-count gate exists to close; it is a **banned override** in any bkit-managed test config. Two adjacent guards: emit the executed count as a build **output** (not a log line) so a build-cache replay (e.g. a task runner like turbo) restores the real number, and let a cache short-circuit report a `cached` sentinel (validated-on-cache, not a hollow 0); assert unit / integration counts only on **non-PR full runs**, because a PR run is affected-scoped and can legitimately resolve to 0 affected tests.
162
+
163
+ ### Step names say whether a red is real
164
+
165
+ One verb scheme across every step in `bkit-ci.yml`, so a red run can be triaged from the step name alone before opening a log:
166
+
167
+ <!-- prettier-ignore -->
168
+ | Verb | Means |
169
+ | --- | --- |
170
+ | `Assert` | a red here is a real failure |
171
+ | `Check` | looks and reports, cannot red the lane |
172
+ | `Run` | invokes a named tool or suite |
173
+ | `Report` / `Upload` / `Count` / `Merge` / `Fetch` | move or publish results |
174
+
175
+ `Guard`, `Validate`, `Verify` and `Audit` are **not** in the scheme: each means "fail the job if this isn't true", which is `Assert`. `Check` is the load-bearing half: it is reserved for a step that genuinely cannot red the lane, either because it carries `continue-on-error: true` or because its body only ever warns. A step named `Check` that can fail the build is the one naming error this scheme exists to prevent, because it trains you to skim past a real failure.
176
+
177
+ Two smaller rules that follow from the same idea:
178
+
179
+ - **Name the tool the way the tool is named.** `Run actionlint`, not `Run Actionlint`; `Run bkit Check`, not `Run Bkit Check`. A step name that misspells its own tool is a step name you cannot grep for.
180
+ - **Drop a qualifier the job name already carries.** Inside `bkit-tests-unit`, `Run Unit Tests` beats `Run Vitest Unit Tests`, because the lane already said which tier, and the runner is visible in the command. Keep a bracket only when it disambiguates two steps that would otherwise share a name and mirrors a literal flag or tool: `Run Slop Scan (full)` / `(delta)`, `Run Shell Tests (bats)`.
181
+
182
+ ### A guard asserts the rule, not the sentence that explains it
183
+
184
+ A shape guard over a config file reads that file as text, so it is easy to anchor it on whatever string happens to be nearby. Anchor on the **rule**; a guard pinned to the prose around the rule fails the moment someone improves the comment, and passes for years after the rule itself is deleted.
185
+
186
+ The failure mode is specific and it is not hypothetical: a guard asserting `expect(content).toMatch(/bootstrap paradox/)` was protecting a real invariant — that a lane checks the repo out before calling a local composite. Tidying the phrase "bootstrap paradox" out of the comment reddened the guard while the invariant was untouched. Assert the thing that must hold (`must already be checked out`, a step id, a flag, an `if:` shape), not the words chosen to describe it.
187
+
188
+ Three practical rules:
189
+
190
+ - **Pin the mechanism, not the wording.** `expect(step).not.toMatch(/exit [1-9]/)` proves a step is non-blocking; matching a comment that says "this only warns" proves nothing about the code.
191
+ - **Derive the list, never hand-write it.** A guard that enumerates lanes goes stale the day a lane is added. Derive the set from the file under test — count the `VERBOSE_CI` declarations, read the `needs:` array — so a new lane is covered without editing the guard.
192
+ - **Prove it can fail.** Put the bug back and watch the guard red before you trust it. A guard that has never failed is indistinguishable from a guard that cannot.
193
+
194
+ **The exception, stated so it is not mistaken for the rule.** When the shipped artefact is prose — a rules file an agent reads, a CLI help string, an advisory message — the wording is the behaviour, and asserting on it is correct. The distinction is whether the text is the deliverable or a description of one.
195
+
196
+ ### Composite actions: two rules that fail silently
197
+
198
+ A composite action (`uses: ./.github/actions/setup`) is the right way to stop copy-pasting a setup block across lanes. Two of its rules are not obvious and neither fails loudly:
199
+
200
+ - **A composite cannot own the checkout that fetches it.** A local `uses: ./…` path is resolved from the runner's own filesystem, so the repo must already be checked out before the runner can read the composite's `action.yml` at all. Putting `actions/checkout` inside the composite and making the composite each lane's first step is a bootstrap paradox, so the lane reds with "can't find action.yml". Every adopting lane runs `actions/checkout` as its **own** first step, with its own explicit `fetch-depth`, before it calls the composite.
201
+ - **Job-level `env:` reaches a composite step's process, but not its `env` expression context.** The `env` context inside a composite reflects only what the composite itself declares, so `if: env.VERBOSE_CI == '1'` on a composite step is **permanently false**, so the step silently never runs, and nothing reds. Gate in the shell instead (`if [ "${VERBOSE_CI:-}" != "1" ]; then exit 0; fi`) and say so in a comment, or the next person tidies it back into an `if:`.
202
+
203
+ The same expression-context trap has a neighbour outside composites: the `env` context is not available to a **job-level `env:` value** either, so `NODE_OPTIONS: ${{ env.VERBOSE_CI && '…' || '' }}` resolves empty on every run. Spell the marker test out — see § CI verbosity.
204
+
205
+ ### E2E on PRs: run the full suite, watch which DB it hits
206
+
207
+ Two PR-time E2E concerns, both gated on **real preconditions** (event, head ref), never a kill-switch flag:
208
+
209
+ - **Parity — PR and push run the full suite.** `pull_request` runs the **same** E2E spec set as the `dev`/`{{DEFAULT_BRANCH}}` push. Scale a slow suite by sharding (parallel lanes / more workers). PR↔push differ only by **DB target** (below) and **push-only tiers** (e.g. `@live`).
210
+ - **Correctness — migration-coupled PRs.** If preview deploys share one `dev` database, that database does not yet carry a PR's unmerged migration (it applies only on the post-merge push). A PR that adds / renames a column **and** uses it in the same PR therefore deterministically 500s pre-merge; a force-all-E2E marker does **not** help (same migration-less DB). Fix: on **feature→`dev` PRs** run E2E against a **local** DB that has applied this PR's migrations (reset local → prod build → run vs `localhost`); keep preview-backed E2E for `dev`/`main` **pushes** (deploy fidelity). The `dev`→`main` release PR (head ref `dev`) already targets the migrated `dev` DB, so it stays on remote. Repos with more than one migration system must apply **all** of them locally.
211
+
212
+ ### Concurrent invocations collide on disk, not just in the database
213
+
214
+ Per-shard data isolation (§ Optional hardening) is necessary, **not** sufficient. One job launching several runner processes concurrently → anything keyed on the runner's **own worker index** collides: that index restarts at 0 in every process.
215
+
216
+ Consumer fanned one E2E step over 12 concurrent Playwright invocations. Each wrote its minted session into one shared auth dir as `user-w<N>.json`, `<N>` = `workerInfo.parallelIndex` → two lanes both wrote `user-w0.json`, later write won, browsers loaded sessions their own worker never built: 486 `Cannot read properties of undefined` + 102 sign-in redirects. DB rows never collided (random owners → tenant tag is a label, not a key); the collision was purely on disk, and the suite's cross-tenant bleed tripwire could not see it, because a clobbered file still holds a valid identity.
217
+
218
+ - **Make the index global.** Distinct lane index per invocation → `laneIndex * workersPerLane + parallelIndex`. Unset → offset 0, local runs byte-identical.
219
+ - **Throw on a bad value, never clamp.** An index silently reading as 0 is the defect being prevented.
220
+ - **Assert distinctness, not presence.** A guard checking each invocation has an index passes with two lanes sharing 0 — bug restored.
221
+ - **Bands unique, never dense.** A `--workers=1` lane leaves most of its band unused; that waste is the point. Tightening spacing to real worker counts is how bands overlap again.
222
+ - **Test the loop by running it.** Loop-generated invocations are invisible to a static scan → execute the real `run:` body in the guard, control plus mutations (pinned lane index, stripped cache-dir suffix) that must red.
223
+
224
+ Same rule for every per-worker artefact keyed that way — transform caches, blob report dirs, JSON output names, artifact dirs — and the fix removes the reason to serialise the lanes at all.
225
+
226
+ Two further axes, same root cause:
227
+
228
+ - **Shared identity vs per-principal rate limits.** Four lanes driving one fixture owner created more records in a minute than the product allows one user → 429 on three of four. The limiter was working; the fixture was pretending four lanes are one person. Per-lane fixture identity under a suffix, teardown deletes by id, and guard the fixture build **separately** from the lanes.
229
+ - **Shared service load.** A per-navigation auth call became 3,500 `GET /auth/v1/user` in 4 minutes under a 12-lane fan-out, stalling the provider and reddening the `@live` lane on a **separate machine**. Audit per-request calls to shared external services before fanning out — verify locally first (JWKS), call the service only when the local check cannot decide. Distinct from the phase-split lever (`deployments.md` § Parallel test lanes): this cuts per-request cost, not peak concurrency.
230
+
231
+ ## Which tier does a behaviour need?
232
+
233
+ Assign every behaviour its **lowest sufficient tier(s)** — the lowest tier that actually exercises it. A behaviour may need more than one. Never substitute a lower or mocked tier for a boundary a higher tier validates; **under-tiering** (a lower / mocked tier where the rubric demands a higher / `@live` one — a user-visible flow with no E2E row, an external-API behaviour tested only against a local fixture, a migration with no fresh-DB replay) is a defect, not a shortcut.
234
+
235
+ <!-- prettier-ignore -->
236
+ | Behaviour | Required tier |
237
+ | --- | --- |
238
+ | Any change (every commit) | **Static** — type / lint / format / prose / drift; pre-push + CI fail-fast |
239
+ | Pure function / single module, no I/O | **Unit** |
240
+ | Crosses a LOCAL stateful boundary (own DB / own API, no 3rd party) | **Integration** vs a freshly-provisioned instance, no mocks at the boundary |
241
+ | Crosses an EXTERNAL / DEPLOYED boundary (3rd-party API, model / LLM, payment, deployed schema, RLS / tenancy) | **@live (golden)** — reaches the real boundary, asserts a boundary-only signal |
242
+ | User-visible UI flow / DOM state | **E2E** |
243
+ | Design token value / reference-doc parity | **Unit** — reference doc vs each implementation, asserted independently (§ Design assertions) |
244
+ | Rendered geometry, contrast, touch-target size | **E2E** — computed style + a11y scan in the existing browser project (§ Design assertions) |
245
+ | New / changed migration or seed | **fresh-DB replay** (`bkit-tests-migration`) — replays from empty + the seed loads |
246
+ | Post-deploy health of a deployed surface | **Smoke** (post-CI or post-deploy — see `deployments.md`) |
247
+
248
+ A plan's `Derived Test Matrix` (`docs/templates/bkit-plan.md`) is the per-feature application of this rubric: one row per behaviour, each mapped to a build + verify task. Boundary rows carry the rigor above — reach the boundary; assert a signal only it can produce; no `as unknown as` at the call-site.
249
+
250
+ ## What each tier must do
251
+
252
+ Tier-by-tier rules: **do** the rule, avoid the **Not** (the failure it prevents). Stack tools (Vitest / Playwright / a Supabase-style local stack / a Vercel-style preview) appear only as worked examples, because the rule is the principle; implement it for your stack.
253
+
254
+ ### Static
255
+
256
+ - Run the whole non-test gate set: typecheck · format check · lint · prose lint · code-slop scan (full **plus** a PR **delta** gate that fails only net-new findings) · drift check · workflow linter. Locally this set is one script, `bkit:gate:static`, and `bkit:gate:static-unit` chains the unit tier on top — the same scripts pre-push, the build loop and the remediate agents all run, so a green push and a green agent gate mean the same thing. CI runs the rest fail-fast **before** any env pull or heavy tier.
257
+ - Scan a **clean tree** — run static **before** the test tiers write coverage / result artifacts, or the scan flags the artifacts instead of your code.
258
+ - On PRs scope to the **affected graph** (e.g. a monorepo task runner's `--filter=...[base]`) over a **non-shallow checkout** (full history) — never a shallow clone that fails affected-selection open to "everything".
259
+ - **Not:** a green CI that never ran the slop / drift / prose gates because they sat behind a test step that exited early.
260
+
261
+ ### Unit
262
+
263
+ - Pure functions and single-module logic, in-process, **no I/O**. Mock or inject the slow / side-effecting collaborators.
264
+ - **Not:** a "unit" test that opens a DB connection or hits the network: that is an integration or @live behaviour wearing a unit suffix, and it will flake.
265
+
266
+ ### Integration
267
+
268
+ - Cross a **local** stateful boundary (your own DB / API) against a **freshly-provisioned** instance, **no mocks at the boundary** (§ Provision backing services fresh).
269
+ - **Self-seed each test's own fixtures** (e.g. in `beforeAll`); do **not** assert on rows the seed file plants. Coupling to the shared seed makes the tier brittle to seed edits and lets seed regressions hide, because the seed has its own gate (§ Migration-replay + seed).
270
+ - Design for **unique-ID independence**: each case creates uniquely-keyed data and never assumes a clean shared store, so the suite parallelises. Transaction-rollback isolation is a pgTAP-style fast-path; application-level tests can't use it, so pin file-level serialism where files must share one local instance.
271
+ - The DB boundary stays hermetic-local, but a **read-only** external API may legitimately be exercised here behind an opt-in flag; anything with **spend, side effects, a deployed schema, or tenancy / RLS** belongs in @live, not here.
272
+ - Source real credentials **explicitly** when the runner does not auto-load `.env`, then **override** the backing-service vars to the local instance so a stray remote URL can't redirect the tier at production data.
273
+ - **Not:** an "integration" test green against a long-lived shared dev DB carrying another run's rows — reproducibility unproven.
274
+
275
+ ### Deploy-reachability (between integration and E2E)
276
+
277
+ - Before any tier runs against a freshly-deployed URL, assert it is **actually serving** — **ready ≠ serving**. A platform can report a deployment ready while it 404s / 500s; a bare "did the deploy finish" check passes anyway.
278
+ - Make a missing target an **honest failure**, not a silent skip: assert ≥1 reachability test actually ran (per-file executed-count), so an unreachable target reds the build instead of green-no-op.
279
+ - **Not:** an E2E suite that "passes" because every spec silently skipped against a target that was never serving.
280
+
281
+ ### E2E
282
+
283
+ - Drive the real UI against the **specific commit's** preview — resolve the deploy by commit SHA, never a static branch alias that may point at a stale build — after confirming it is ready + serving.
284
+ - Locally, run against a **production build**, not a dev server: a dev file-watcher remounts components mid-test and breaks stateful UI (dialogs, wizards).
285
+ - Use **stable selectors** (test-ids) and **condition-based waits**; never a fixed-time or network-idle wait. Don't gate a response-wait on status — match URL + method, then assert success explicitly, or a non-2xx silently spins to timeout.
286
+ - Clean up what you create (`afterAll`) and warn on accumulated `test_` / `e2e_` rows so leaked fixtures can't slowly corrupt a shared environment.
287
+ - On a pull request and on a push, run the **same** spec set — § "E2E on PRs". Scale a slow suite by sharding, not by dropping specs.
288
+ - **Not:** clicking by visible text and waiting on `networkidle` — the two classic flaky-E2E footguns.
289
+
290
+ ### @live (golden)
291
+
292
+ - Cross the **real external / deployed boundary** and assert a **ground-truth signal only it can produce** (§ Validated means executed). Two shapes: **in-process** (the test calls the real SDK / model / API directly) and **deployed-endpoint** (the test fetches the running app) — use whichever observes the boundary you're validating.
293
+ - Push to `dev` or the default branch only, when `web_affected` (`run_live`). A planned failure reds the capstone. It does not run on a pull request or a dispatch. A newer run on the same ref cancels the older one (`deployments.md` § One run per branch or pull request).
294
+ - **Honest skip vs hollow:** when there is genuinely nothing deployed to validate, **skip with a recorded reason** (the capstone then asserts nothing about its count) — distinct from a tier that ran 0 tests. But a **missing credential with the tier enabled must fail loudly at connect**, never skip, because a vacuous skip hides infra rot.
295
+ - Never blast a production system with test traffic: use a **synthetic-identity namespace** + a guarded teardown that refuses to delete anything outside it.
296
+ - **Not:** a non-mock @live test that short-circuits before the boundary (the hollow case), or one that asserts only "did not throw".
297
+
298
+ ### Migration-replay + seed (the fresh-DB gate)
299
+
300
+ - Prove every migration **replays from an empty database** on a fresh ephemeral instance, then the **seed loads** — the always-on sibling gate `bkit-tests-migration` (§ Provision backing services fresh). Distinct from the deploy-time "apply only new migrations onto the already-migrated remote" step (`deployments.md` § Applying migrations at deploy time) — that remote push also lives in the **same** always-on lane, after the replay, so a from-empty failure never reaches shared remote.
301
+ - **Assert the seed actually loaded** — check a known row exists. A reset / replay can exit 0 while a conditional insert silently no-ops or the seed aborts mid-file; a green replay is not proof the fixture is present (the seed analog of the hollow-boundary rule).
302
+ - Generate the seed from a **single deterministic source** — a pure data definition with no wall-clock `now()`, no random values, explicit IDs / enums so triggers don't randomise it — and regenerate the checked-in seed file from it. Two hand-maintained copies drift.
303
+ - **Replay-from-empty, not reused-volume.** A bare "start the local stack" can reuse a stale data volume and silently skip newer migrations, so it is **not** a freshness proof; only a reset / replay from empty is.
304
+ - Trigger the gate on **every** migration / seed source — including the seed **generator** and its data definition, not just the emitted seed file — and replay **every** migration chain (a second ORM / CMS chain this gate never replays is an unverified hole).
305
+ - **Not:** treating a reset / replay command's exit 0 as "seed loaded", or proving freshness with a volume-reusing start command.
306
+
307
+ ### Smoke
308
+
309
+ - After deploy, run a **fast, dependency-light** probe of the live surface (a handful of health / route / contract checks, or a tiny tagged browser subset) — breadth ("is the app fundamentally up?"), not depth.
310
+ - It is an **observability gate, not a merge gate**: own workflow, never in branch protection. When `bkit-tests-deploy` promotes inside CI, this probe is the health workflow, not a second file (`deployments.md` § Smoke trigger plumbing, § Promote before the lanes).
311
+ - **Not:** a smoke suite wired into branch protection, or one so heavy it can't run on every deploy.
312
+
313
+ ## Design assertions are a dimension, not a lane
314
+
315
+ **NEVER add a design lane.** The lane axis is **resource profile** (a millisecond file read vs a booted app + browser), not subject matter, because design assertions span both. A `bkit-tests-design` job (or a design-only browser project) splits one concern across two profiles and buys nothing existing lanes don't provide. Fold each assertion into the tier that already fits it: CI topology, the capstone's `needs:`, the browser-project partition all stay **unchanged** (a real consumer's full design-system rollout landed with `bkit-ci.yml` byte-unchanged).
316
+
317
+ <!-- prettier-ignore -->
318
+ | Design assertion | Lane |
319
+ | --- | --- |
320
+ | Token parity — reference doc vs each implementation (stylesheet variables, theme object) | `bkit-tests-unit` |
321
+ | Static guards — no raw hex, no arbitrary-value utility classes (utility-CSS repos, e.g. Tailwind) | `bkit-tests-static` (lint rule, anchored on the **class boundary** so e.g. Tailwind `p-[3px]` reds but a legitimate substring does not) |
322
+ | Repo-wide raw-hex contract (scans the source tree off disk, no I/O beyond the filesystem) | `bkit-tests-unit` |
323
+ | Contract depth — component-level token / test-id / behaviour assertions | `bkit-tests-unit` |
324
+ | Computed style + measured geometry (resolved pixels, touch-target size) | `bkit-tests-e2e-web` — ordinary specs in the **existing** browser project, selected by path |
325
+ | Accessibility scan (contrast, target size) | `bkit-tests-e2e-web` — the scanner is an imported helper, not a project fixture |
326
+ | Design-source parity (a rendered style guide vs the reference doc) | `bkit-tests-unit` |
327
+ | Visual regression (screenshot baselines) | **opt-in, not baseline** (§ Optional hardening) — highest maintenance cost of the set |
328
+
329
+ - **One reference, asserted independently.** The reference doc owns the token contract and its parsing rules (`design.md` § Machine-checked reference). What lanes care about: each implementation is its **own** test, so one red names its culprit.
330
+ - **Merge-gated from day one — never an advisory window.** Assertions live inside lanes the capstone already gates, so a design red blocks merge on the first PR that adds one. No promotion step to schedule → no deferral row to forget.
331
+ - **A group tag carries zero routing power.** Tag design tests in the test **title** (never a filename convention) + add a `test:design` script for local iteration only. The tag must never appear in an execution gate or inverse-grep filter, because a test without it still runs in its normal lane. Keep the **standard filename** in a location the package's include glob already matches: a bespoke `*.design.test.ts` or an unreached dir runs in **zero** lanes — green everywhere, covering nothing (§ Validated means executed). Pass-with-no-tests is mandatory on every fan-out; each runner spells that flag differently, and a browser runner hard-errors on a path / project name matching nothing.
332
+ - **Cache footgun — design tests read files outside their own package.** A token-parity test reads the reference doc; a raw-hex contract scans the source tree. Under a per-package-hash runner, editing the reference doc changes no package hash → a warm cache replays a **PASS against a reference the code now contradicts**. Put the reference doc (+ any rendered style guide) in the runner's **global dependencies** + mark the design-selection task **uncached**. Same trap class: a design run overwriting the machine-readable results file the executed-count gate consumes, so re-run the full suite before trusting either.
333
+ - **Keep the first honest reds.** A first real geometry / a11y sweep surfaces genuine defects (undersized controls, failing contrast). File as issues, allowlist behind a **named constant**, and ship the allowlist's **stale-entry check** in the same change, because an allowlist that never rejects a fixed entry decays into a silent exemption. Enumerate sweep scope by **role and tag**, never by test-id presence (library-generated markup escapes the gate by construction). Measure **every** theme before asserting any, or a light-theme red hides dark-theme offenders.
334
+
335
+ ## Schema-invariant DB checks (e.g. RLS coverage)
336
+
337
+ Access-policy coverage is stack-specific: bkit ships the **pattern** (two routes below), not a drop-in test. Supabase / PostgREST is the worked example — implement it for your backing store (swap the catalog source + anon-probe for your stack's equivalent).
338
+
339
+ Assert DB-level invariants (e.g. "every public table has RLS enabled", no hardcoded list) one of two co-equal ways. Pick by **deploy topology**, not by whether you can run a local DB-test runner (e.g. pgTAP):
340
+
341
+ - **pgTAP** (hermetic-fixture route) — e.g. `supabase/tests/*.sql` run by `supabase db test` in the `bkit-stub:test-db` step against a CI-local fixture built from `supabase/migrations`. Fast, hermetic, offline; keeps the invariant out of app code. Caveat: the fixture can differ from prod, so a migration that doesn't reproduce the live schema leaves this green while prod access policies are actually broken. Best when there is **no** deploy / `@live` tier, or for pure-logic DB unit tests.
342
+ - **@live catalog-RPC** — a privileged, server-only catalog query called from the `@live` tier (e.g. Supabase: `SECURITY DEFINER`, service_role-only RPC `public.rls_coverage_gaps()` over REST), validating the **real deployed schema** in `bkit-tests-live-web`. Needs a deploy + the RPC. **Recommended default once you have a deploy / `@live` tier**, because for access-policy / tenancy invariants especially, a passing local-fixture check is not evidence that prod is locked down. (e.g. Supabase: direct port-5432 from CI runners is IPv4-flaky, so use the REST path the tier already has.)
343
+ - **PostgREST gotcha** — `GET /rest/v1/` (OpenAPI) is service_role-only by default: fetch the exposed surface with the service-role key, then probe each table with the ANON key (only the leak assertion must be anon).
344
+
345
+ An auto-discovering access-policy suite (e.g. RLS: RLS-enabled / anon-reads-`[]` / cross-tenant-denial, no hardcoded table list, so it catches the next table too) belongs in `bkit-tests-live-web`.
346
+
347
+ ## Provision backing services fresh
348
+
349
+ A tier that needs a stateful backing service (database, cache, queue, search index) must run against a **freshly-provisioned** instance, not a long-lived shared one. Green against a shared environment carrying accumulated state is **not** evidence of reproducibility, because a migration that never re-applies cleanly, a seed that aborts on an empty store, or a row another run left behind all stay invisible until the service is rebuilt from scratch. Prove a fresh provision + seed succeeds **in CI**: e.g. an ephemeral per-PR database started fresh each run (Supabase: `supabase db reset` + seed). Reserve the shared remote / dev instance for the `@live` tier and push-side E2E (they validate the real deployed schema); it is never the integration tier's source of truth.
350
+
351
+ bkit's `bkit-tests-migration` lane (`bkit-stub:bkit-tests-migration`) is the ready-made home: **always-on** (no job-level `if:` because e2e / live `needs:` it for remote-push ordering; a skip cascades). Replay + seed assert stay plan- / path-gated per-step. On every push to `dev`/`main` the same lane owns remote apply of new migrations (e.g. `supabase db push --linked --include-all`) (un-gated by `run_migration` so it self-heals; after replay so from-empty failure never reaches remote). Capstone asserts `result == success` whenever scope succeeded. Fold into `bkit-tests-check`'s `needs:`.
352
+
353
+ **Local integration freshness.** If your local stack reuses a warm data volume (e.g. Docker + `supabase start`), a bare start can leave migrations unapplied (stale-volume footgun). Prefer a reset-by-default runner over a bare integration run (e.g. `turbo run test:integration`) — mirror local E2E: reset unless `--no-reset`. Shape: `pnpm test:integration:local` → script that starts local stack, hides remote env file (e.g. `.env.local`), resets from empty (e.g. `supabase db reset --local`), then runs integration (CI passthrough, because CI boots its own hermetic stack).
354
+
355
+ **"Fresh" means replay-from-empty, not a reused volume.** A bare "start the local stack" command often **reuses an existing data volume** and applies only what's missing, so a "fresh" start can silently run a months-old schema while reporting success. Only a reset / replay from an **empty** store is a freshness proof. And a green replay is not a green **seed**: assert the seed actually loaded (a known row exists), because the reset can exit 0 while a conditional insert no-ops or the seed aborts mid-file (§ Migration-replay + seed carries the full seed-determinism rules).
356
+
357
+ **Multiple migration systems:** a repo running more than one migration chain (e.g. a SQL chain for the public schema **and** an ORM / CMS chain such as Payload or Prisma) must fresh-apply **every** chain here and trigger on **every** migration source dir. A chain this gate never replays is an unverified hole, so a broken migration in it lands green.
358
+
359
+ ## Optional hardening (adopt when the cost is justified)
360
+
361
+ Beyond the gates above, three practices raise confidence further — opt-in, not baseline:
362
+
363
+ - **Mutation testing** (e.g. StrykerJS over a Vitest suite) automates the "executed ≠ exercised" intent: it injects bugs into production code and fails when no test catches them. Run it locally, on demand. It is not a CI lane and not a nightly workflow. Gate a local run on a survival-score threshold, never 100% (equivalent mutants make perfection unreachable). Capstone asks "did tests run?"; mutation asks "do they catch injected bugs?".
364
+ - **E2E sharding** (`--shard` matrix + report merge) cuts wall-clock on a large browser suite, but it is **gated on per-shard data isolation** (the unique-ID independence above). A single shared seed pins `workers: 1` and blocks sharding until the data is isolated. Isolated data is still not enough once several invocations share one job — § Concurrent invocations collide on disk, not just in the database.
365
+ - **Bounded flaky-retry with tracking.** A capped retry on the flake-prone E2E tier is low-risk **only** when paired with explicit flake **tracking**, because an auto-retry that silently passes hides a real regression, the inverse of "validated ≠ didn't fail".
366
+
367
+ ## Coverage on PRs
368
+
369
+ Shipped stubs target Vitest (`bkit-stub:coverage`) and Playwright (`bkit-stub:e2e-coverage`); on another runner keep the rules (per-tier, report-only, ratchet from current) and swap the tooling.
370
+
371
+ Report coverage on each PR **without a paid product or a third-party service** — e.g. the `bkit-stub:coverage` block in `.github/workflows/bkit-ci.yml` runs `davelosert/vitest-coverage-report-action` entirely inside Actions with `GITHUB_TOKEN`, posting sticky per-PR comments (safe for private repos; no coverage data leaves the runner). Replaces GitHub Code Quality's coverage-on-PR value (`deployments.md` § Disable GitHub Code Quality billing) — **not** CodeQL security scanning, a separate product.
372
+
373
+ **Per-tier, not merged.** Unit and integration are measured and commented **separately** (two runs into `coverage/unit` and `coverage/integration`, two comments keyed by a distinct `name:`). A single merged number is the weakest option: coverage is a **union**, so a line covered only by an integration test reads as covered and **hides a missing unit test**, so a merged gate lets integration mask a hollow unit suite. The two numbers also have different denominators, so they can't be honestly combined into one.
374
+
375
+ - **Report-only by default.** No `thresholds`, so coverage never reds the lane, so enabling the block on an existing repo can't break it.
376
+ - **Reporters are load-bearing.** The action reads `coverage-summary.json` (from the `json-summary` reporter, mandatory) and `coverage-final.json` (from `json`, required for `file-coverage-mode: changes`). Enable both in `coverage.reporter` or the step no-ops.
377
+ - **Two runs, separate dirs.** `vitest run --coverage --coverage.reportsDirectory=coverage/unit --exclude '**/*.integration.test.ts'` for unit; a second run into `coverage/integration` for the integration tier. Separate dirs also avoid the last-writer-wins **clobber** a second same-dir `--coverage` run would cause.
378
+ - **Thresholds are opt-in and per tier:**
379
+ - **Unit = the gate.** Pass `--coverage.thresholds.branches=<current>` as a CLI flag on the **unit** run only, because **branches** is the meaningful floor (line / statement % overstates confidence); set it to your **current** coverage and ratchet up. vitest coverage is per-**run** (root config), **not** per-project, so `projects` does **not** scope it and a `thresholds` block in `vitest.config` would red **both** runs, because the per-run flag (or a second `vitest.<tier>.config.ts` run with `-c`) is what keeps the gate off integration. 80% is convention, not best practice, because a fetishised high bar breeds assertion-free line-touching tests; the executed-≠-exercised rule (§ Validated means executed) matters far more than the number.
380
+ - **Integration = report-only.** Gate integration on **execution** (the capstone's `integration_ran > 0`), **not** a %. A whole-repo integration % is denominator-noise, because integration covers boundaries / flows, not pure logic, and rarely drives every branch, so a hard threshold on it punishes the correct pyramid shape. If you want a real integration %, add `--coverage.include='src/server/**'` on the integration run (same CLI-flag idiom as `--exclude`) to scope it to the integration surface, **then** set a floor, or **ratchet from current** — never a number picked from thin air.
381
+ - **Share the unit gate with the build workflow.** Put the unit run (`--coverage … --coverage.thresholds.branches=<current>`) in a `test:coverage:unit` script and chain it into `bkit:gate:static-unit` — the CI unit lane calls the script, `/bkit-build` Run Tests calls the gate, so the threshold has **one source** and a regression fails in the worktree, not only on the PR. Never duplicate the command and sync it by comment, because that drifts. The build runs only the deepest declared `bkit:gate:*`, never the script by name: **left out of the chain, it never gates the build**. (bkit's own repo does exactly this.)
382
+ - **Permissions.** The report steps need `pull-requests: write` — declare it at **job level** on the lane that posts. Job-level `permissions:` **replaces** the workflow-level block (not additive), and the SHA-cache step calls `gh run list`, so re-include `actions: read` too or it breaks. **Separate lanes:** with a lane per tier (recommended — see `deployments.md` § Parallel test lanes), each coverage comment posts from its own lane (unit-cov → `bkit-tests-unit`, integration-cov → `bkit-tests-integration`), so put the block on **each** lane that reports. With the combined starter, both live on `bkit-tests-unit`.
383
+ - **Fork PRs.** `GITHUB_TOKEN` is read-only for PRs from a fork, so the steps fail — the shipped `head.repo == repo` guard skips them there; adopt the action's `workflow_run` two-workflow pattern if you must comment on fork PRs. The integration step is also guarded on `hashFiles(...)` so a repo with **no integration tier** skips it cleanly.
384
+ - **Base-branch delta** (▲▼ vs the default branch) is **not** shipped by default, because it needs the base's `coverage-summary.json` (a second run or a stored artifact); wire the action's `json-summary-compare-path` if you want it.
385
+
386
+ ### E2E coverage on PRs
387
+
388
+ The **E2E tier** (`bkit-stub:e2e-coverage`) reports Playwright coverage the same free, in-Actions, private-repo-safe way — a **third** sticky comment keyed `name: e2e`, never merged into the unit / integration numbers. Unlike vitest there is **no `--coverage` flag**: Playwright is black-box and doesn't instrument your source, so it's a 3-part pipeline.
389
+
390
+ - **Collect during the run.** Either an **Istanbul instrumented build** (`vite-plugin-istanbul` exposes `window.__coverage__`, scraped in a Playwright fixture — works on every browser) or the **V8 API** (`page.coverage`, Chromium-only, needs source maps). Istanbul is the cross-browser default.
391
+ - **Report with Monocart.** `monocart-coverage-reports` (wired via the `monocart-reporter` Playwright reporter) ingests **either** V8 or Istanbul input and emits Istanbul-format `coverage/e2e/coverage-summary.json` + `coverage-final.json` — the **same two files** the vitest action reads (`reports: ['json-summary', 'json', 'lcov']`), so no new commenter is needed.
392
+ - **Comment by reuse.** Point `davelosert/vitest-coverage-report-action@v2` at `coverage/e2e` with `name: e2e`. If Monocart's `coverage-final.json` isn't accepted for `file-coverage-mode: changes`, drop to `file-coverage-mode: all`, or comment via a cobertura action (`irongut/CodeCoverageSummary`) on Monocart's `cobertura` report.
393
+ - **Report-only — no threshold by default.** A whole-app E2E % is denominator-noise (E2E exercises user **flows**, not every branch), so gate the tier on the **E2E step succeeding**, not a number. For a real E2E %, scope Monocart's `entryFilter`/`sourceFilter` to the surface E2E is meant to cover, **then** ratchet from current — never a picked number.
394
+ - **Permissions / forks.** The E2E coverage report runs in the **`bkit-tests-e2e-web` lane** (or, with the combined starter, in `bkit-tests-unit`), and needs that lane's job-level `pull-requests: write` + `actions: read` + `contents: read` block, or the comment can't post. The `head.repo == repo` guard skips fork PRs; a `hashFiles('coverage/e2e/coverage-summary.json')` guard skips repos with no E2E coverage.
395
+
396
+ ## CI verbosity (`[verbose ci]`)
397
+
398
+ See `deployments.md` § Commit-message force tags for the marker mechanics (where to put it: PR title for feature-branch pushes, commit message for direct push to `dev` / `{{DEFAULT_BRANCH}}`). This section covers the testing-specific knobs.
399
+
400
+ **Knobs flipped under the marker** — shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs; add your stack's equivalents:
401
+
402
+ - `TURBO_LOG_LEVEL=full` — surfaces Vitest / build output across all turbo steps (otherwise compressed to errors-only)
403
+ - `NODE_OPTIONS=--trace-warnings --trace-deprecation` — stacks on deprecations / transitive-dep regressions. Set as a job-level `env:` key in static YAML, never written to `$GITHUB_ENV`: the runner blocklists `NODE_OPTIONS` for that command, rejects the write with an `::error::`, and still concludes the step `success`, so the flag reaches nothing while the run goes green. Spell the `contains()` marker test out rather than reusing `env.VERBOSE_CI`, because the `env` context is not available to a job-level `env:` value. A step with its own `env:` block replaces the job-level value rather than merging, so it must restate the flags
404
+ - `DEBUG=vercel:*,supabase:*` — Vercel deploy + Supabase migration internal chain (no `pw:*`, because it duplicates Playwright trace)
405
+ - Playwright (when `bkit-stub:e2e` enabled): appends `--trace=on` only, because `--video` and `--screenshot` are `playwright.config.ts use:` keys, not CLI flags (Playwright errors on unknown CLI options). The trace.zip captures snapshots / network / console / source, which covers the dominant diagnose use case. Never pass `--reporter=line` — let `playwright.config.ts`'s chain run
406
+
407
+ **Use when:** debug returns thin evidence (no `file:line`, only "tests failed", e2e fail without trace). `bkit-debug` / `failure-diagnose` auto-recommends. Never on first attempt; never on `bkit-ship`, because verbose on a green run is pure cost — artifact storage + run time.
408
+
409
+ **Hostile gap — Playwright `--reporter=line` override.** If your `playwright test` invocation passes `--reporter=line`, drop it. With the marker on, traces are written but no reporter surfaces them → wasted artifact upload. `bkit install` flags this as an advisory.
410
+
411
+ **Artifact paths** (already in `.gitignore` via bkit template): `test-results/`, `playwright-report/`, `blob-report/`, `playwright/.auth/`. Never commit these, because traces alone run 1-50MB each.
412
+
413
+ <!-- bkit:end -->
@@ -0,0 +1,97 @@
1
+ # Dependencies
2
+ node_modules/
3
+ .pnpm-store/
4
+
5
+ # Build outputs
6
+ dist/
7
+ build/
8
+ .cache/
9
+ *.tsbuildinfo
10
+ .turbo/
11
+
12
+ # Logs
13
+ *.log
14
+ npm-debug.log*
15
+ yarn-debug.log*
16
+ yarn-error.log*
17
+ pnpm-debug.log*
18
+
19
+ # Env / secrets (force-allow .env.example)
20
+ .env
21
+ .env.*
22
+ !.env.example
23
+ *.pem
24
+ *.key
25
+
26
+ # OS / editor
27
+ .DS_Store
28
+ Thumbs.db
29
+ *.swp
30
+
31
+ # Tmp / pack artifacts
32
+ tmp/**
33
+ *.tgz
34
+
35
+ # <!-- bkit:start -->
36
+
37
+ # {{BKIT_MANAGED_MARKER}}
38
+
39
+ # Worktrees, plan logs, per-run sentinels. Sentinels are written mid-run, read by
40
+ # the same run's Failure Path, cleared at next Step 1 — never bookkeeping, so
41
+ # path-scoped staging must not commit them.
42
+ .worktrees/
43
+ docs/plans/*/logs/**/raw/
44
+ docs/plans/*/logs/**/.lock
45
+ # Per-run sentinels sit in BOOK_PATHS-staged logs — without these lines a Failure
46
+ # Path commit captures them and the next `rm -f` shows as a tracked deletion.
47
+ docs/plans/*/logs/**/.deferred-blocked
48
+ docs/plans/*/logs/**/.rebase-failed
49
+
50
+ # Repo-global dev critical-section lock (cross-FID)
51
+ .bkit/.dev.lock
52
+ .bkit/.runtime-cursor
53
+
54
+ .bkit/.roadmap-shortlist.json
55
+ .bkit/.roadmap-reverse-sync.json
56
+
57
+ # Claude Code /schedule daemon lock
58
+ .claude/scheduled_tasks.lock
59
+
60
+ # Cloud setup docs — `bkit install` inlines resolved .envrc secrets; never commit.
61
+ # One per host: .claude/bkit-cloud.md (Claude Code web), .cursor/bkit-cloud.md (Cursor Background Agents)
62
+ .claude/bkit-cloud.md
63
+ .cursor/bkit-cloud.md
64
+
65
+ # Claude native worktrees (isolation:worktree / EnterWorktree) — transient full-tree
66
+ # copies; ignore or slop:delta double-counts the checkout
67
+ .claude/worktrees/
68
+
69
+ # cursor / opencode — no project-local worktree or runtime dir to ignore.
70
+ # Cursor agents run in remote VMs; opencode state lives at ~/.local/share/opencode
71
+ # (XDG_DATA_HOME). bkit-managed files in .opencode/ are tracked.
72
+
73
+ # husky 9 stub (auto-generated by `husky` from prepare)
74
+ .husky/_
75
+
76
+ # Coverage (vitest --coverage) — regenerated each run, never commit
77
+ coverage/
78
+
79
+ # Playwright artifacts — grow under [verbose ci]
80
+ test-results/
81
+ playwright-report/
82
+ blob-report/
83
+ .last-run.json
84
+ playwright/.auth/
85
+
86
+ # Advisories — regenerated by `bkit install` / `check` / `doctor`
87
+ .bkit/advisories.md
88
+
89
+ # Local MCP / agent secrets — never commit
90
+ .bkit/.env
91
+
92
+ # Payload view links — `bkit install` / `upgrade` symlink these into
93
+ # node_modules/@cbartens/bkit; they dangle on a fresh clone or in CI, so never commit.
94
+ .bkit/core
95
+ .bkit/shared
96
+
97
+ # <!-- bkit:end -->