@cbartens/bkit 6.1.1 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -1,21 +1,98 @@
1
- <!-- bkit:start -->
2
-
3
- {{BKIT_MANAGED_MARKER}}
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/deployments.md`, fill the project slots, keep the bkit practice sections, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/observability.md`, `docs/testing.md`.
4
+ >
5
+ > **Finish against:** `docs/data-schema.md` for `### This project` under `## Applying migrations at deploy time`, which waits for the schema.
6
+ >
7
+ > **Where the facts come from:** the CI and deploy workflow files, the hosting configuration, the branch protection settings, the secret stores and the release history.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/deployments.md`.
12
+ > 2. Fill `## Environments` with one row per environment: its branch, URL and when it deploys. Read hosting and the data store from `docs/architecture.md` § Environments.
13
+ > 3. Redraw `## Release path` as the route a change takes from a branch to production.
14
+ > 4. Fill `## Secrets and env config` with how each environment's config is synced. Read the secret names from `docs/security.md` § Secrets.
15
+ > 5. Fill `## Branch protection` with the required checks and rules of each protected branch.
16
+ > 6. Replace the example steps in `## Production rollback runbook` and `## Dev rollback runbook` with the project's own. Keep both headings.
17
+ > 7. Fill the `### This project` slot under `## Applying migrations at deploy time` with what applies migrations, and when.
18
+ > 8. Keep every section marked `bkit practice`. Edit its text only to correct it for the stack, and never change its heading.
19
+ > 9. Record unresolved facts under `## Open questions`.
20
+ > 10. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/deployments.md` | ○ | ○ | ○ | ● | ● | Deployment and CI/CD: environments, release path, secrets, branch protection, run-level tiers and rollback. |
21
+ > 11. Check the document against each completion check, then delete this introduction.
22
+ >
23
+ > **If it does not apply:** write `Not applicable: {reason}` under a project slot that does not apply, such as `## Branch protection` for a project with no protected branch.
24
+ >
25
+ > **Completion checks:**
26
+ >
27
+ > - Every environment in `docs/architecture.md` § Environments has a row in `## Environments`.
28
+ > - The chart in `## Release path` names every environment that a release reaches.
29
+ > - Every secret in `docs/security.md` § Secrets has a sync route in `## Secrets and env config`.
30
+ > - Both rollback runbooks hold the project's own steps, with no example step left.
31
+ > - Every section is marked as a project slot or as bkit practice.
32
+ > - No example row remains.
4
33
 
5
34
  # Deployments
6
35
 
7
36
  > [!CAUTION]
8
- > **Purpose:** The rules for deployment, environment config and the CI/CD pipeline: secrets sync, branch protection and run-level tiers.
37
+ > **Purpose:** Deployment and CI/CD: environments, release path, secrets, branch protection, run-level tiers and rollback.
9
38
  >
10
39
  > **Rules:**
11
40
  >
12
- > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
13
- > - Pre-push runs the project's gate set locally (see "Pre-push checklist" below).
14
- > - Never use `--no-verify`.
41
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
42
+ > - Pre-push runs the project's gate set locally. The gate scripts are in `docs/testing.md`.
43
+ >
44
+ > **bkit practice:** every section marked `bkit practice` is bkit's own advice. Sections marked **bkit practice** keep their heading text and stay separate sections. Do not rename, merge or compress them, because bkit's CI template, advisories and audits cite them by name. Every section marked `Project slot` holds the project's own facts.
45
+ >
46
+ > **Not here:** Commit-message tags, phase-close prerequisites, post-merge routing and the ship gate go in `.bkit/workflows.md` § Test and release mechanics. Hosting and the data store go in `docs/architecture.md` § Environments. Secret names go in `docs/security.md` § Secrets.
47
+ >
48
+ > **Update when:** An environment, release step, secret route, protected branch or rollback step is added, changed or removed.
49
+
50
+ ## Environments
51
+
52
+ > **Project slot:** one row per environment. Hosting and the data store are in `docs/architecture.md` § Environments.
53
+
54
+ <!-- prettier-ignore -->
55
+ | Environment | Branch | URL | Deploys when |
56
+ | --- | --- | --- | --- |
57
+ | [Environment] | [Branch it deploys from.] | [Address.] | [Event that starts a deploy.] |
58
+ | [e.g., Production] | The default branch. | [e.g., the public site address.] | A release pull request merges. |
59
+
60
+ ## Release path
61
+
62
+ > **Project slot:** the route a change takes to production.
63
+
64
+ ```mermaid
65
+ flowchart LR
66
+ FEATURE["Feature branch"] --> DEV["Integration branch"]
67
+ DEV --> MAIN["Default branch"]
68
+ MAIN --> PROD["Production"]
69
+ ```
70
+
71
+ ## Secrets and env config
72
+
73
+ > **Project slot:** how each environment's config is synced. The secret names are in `docs/security.md` § Secrets.
74
+
75
+ <!-- prettier-ignore -->
76
+ | Environment | Config store | Synced by | Checked by |
77
+ | --- | --- | --- | --- |
78
+ | [Environment] | [Store that holds its config.] | [Command or workflow that syncs it.] | [How a mismatch is found.] |
79
+ | [e.g., Production] | The hosting platform's environment settings. | A sync script run by the release workflow. | A comparison step that prints no values. |
80
+
81
+ ## Branch protection
82
+
83
+ > **Project slot:** the rules on each protected branch.
84
+
85
+ <!-- prettier-ignore -->
86
+ | Branch | Required checks | Other rules |
87
+ | --- | --- | --- |
88
+ | [Branch] | [Checks that must pass.] | [Reviews, history and push rules.] |
89
+ | [e.g., Default branch] | The capstone check. | No force pushes. |
15
90
 
16
91
  ## Production rollback runbook
17
92
 
18
- > Use this runbook when a bad release is live. Move production back to the last good deployment, then fix forward through `dev`. Production moves first, and `main` keeps its history. The steps work on any host. The commands use Vercel as the example.
93
+ > **Project slot:** the steps are bkit's procedure. Replace each bracketed example with this project's own commands, and change a step only where the host or database differs. Keep the heading, because plans cite it.
94
+
95
+ > Use this runbook when a bad release is live. Move production back to the last good deployment, then fix forward through `dev`. Production moves first, and `main` keeps its history. The steps work on any host.
19
96
 
20
97
  ### Preconditions
21
98
 
@@ -24,15 +101,10 @@
24
101
 
25
102
  ### Playbook
26
103
 
27
- 1. **Move production back** to the last good deployment. Do not rebuild, and make no git change. Move every production host the release moved (the site, and webhook or background-job aliases), never the website alone. With `bkit-tests-deploy` adopted, run the switch from a `workflow_dispatch` rollback workflow in the deploy job's `concurrency:` group (`cancel-in-progress: false`), so a release and a rollback never switch production at once. For example, on Vercel:
28
- ```bash
29
- vercel ls --meta githubCommitSha=<green-sha>
30
- vercel promote <prior-deployment-url>
31
- ```
104
+ 1. **Move production back** to the last good deployment. Do not rebuild, and make no git change. Move every production host the release moved (the site, and webhook or background-job aliases), never the website alone. With `bkit-tests-deploy` adopted, run the switch from a `workflow_dispatch` rollback workflow in the deploy job's `concurrency:` group (`cancel-in-progress: false`), so a release and a rollback never switch production at once. For example:
105
+ [e.g., list the deployments of the green commit with the host's CLI, then promote the prior deployment.]
32
106
  2. **Mark the bad deployment** when `bkit-tests-deploy` is adopted. `bkit-tests-deploy` refuses the deployment id in repo variable `ROLLED_BACK_DEPLOYMENT_ID` (§ Promote before the lanes), so a "Re-run all jobs" of the bad run cannot promote it again.
33
- ```bash
34
- gh variable set ROLLED_BACK_DEPLOYMENT_ID --body <bad-deployment-id>
35
- ```
107
+ [e.g., set the repository variable `ROLLED_BACK_DEPLOYMENT_ID` to the bad deployment id with the `gh` CLI.]
36
108
  3. **Verify** the rollback with § Post-rollback verification.
37
109
  4. **Fix forward through `dev`.** Revert the bad change on a `revert-*` branch off `dev`, or ship the fix. Open a PR into `dev`, then release `dev` → `main` as usual. Hold every other release PR into `main` until it carries the fix, because a release cut from `main`'s tip ships the bad commit again. The release descends from the commit production serves, so `bkit-tests-deploy` promotes it. Never rewind or re-seed the database. Ship a corrective migration instead (§ Applying migrations at deploy time). The rolled-back build must work on the newer schema, so expand first and contract later.
38
110
  5. **Reset `main` — last resort.** Do this only when `main` holds commits that a `dev` release cannot undo (for example, a squash that landed on `main` without going through `dev`), and only after step 1. If you reset first, `bkit-tests-deploy` refuses every release until production moves, including the run the reset starts, because production's commit is no longer an ancestor of `main`. The reset is a push to `main`. With `bkit-tests-deploy`, it starts a release run that builds and promotes a fresh deployment of `<green-sha>`. You need `jq`, a local repo on `main` and a clean tree.
@@ -62,6 +134,8 @@
62
134
 
63
135
  ## Dev rollback runbook
64
136
 
137
+ > **Project slot:** the steps are bkit's procedure. Replace each bracketed example with this project's own commands, and change a step only where the host or database differs. Keep the heading, because plans cite it.
138
+
65
139
  > Use this runbook to unwind a bad commit on `dev` to the prior known-good SHA when the rolled-out range included applied migrations. A code-only rollback leaves the dev DB ahead of the code, so schema-aware tests (schema introspection, access-policy integration) fail on an otherwise clean tree. The steps work with any database. The commands use Supabase as the example.
66
140
 
67
141
  ### Preconditions
@@ -78,11 +152,8 @@
78
152
  git revert --no-edit <green-sha>..HEAD
79
153
  git diff --stat <green-sha> HEAD # empty = tree matches known-good
80
154
  ```
81
- 2. **Reset the dev DB.** Drop every schema your migrations create (`CASCADE`), then truncate the migration ledger. Name only your own app-managed schemas. For example, on Supabase (`public` is shown; add each schema your migrations create):
82
- ```bash
83
- psql "$SUPABASE_DB_URL" -c 'DROP SCHEMA IF EXISTS public CASCADE;'
84
- psql "$SUPABASE_DB_URL" -c 'TRUNCATE supabase_migrations.schema_migrations;'
85
- ```
155
+ 2. **Reset the dev DB.** Drop every schema your migrations create (`CASCADE`), then truncate the migration ledger. Name only the schemas your own migrations create.
156
+ [e.g., drop each schema the migrations create with `DROP SCHEMA ... CASCADE`, then truncate the migration ledger table.]
86
157
  3. **Push the revert.** The push run's `bkit-tests-migration` re-applies every migration on the reverted tree, because an empty ledger makes every migration new. NEVER apply by hand. **If** `dev` is protected → push the revert on a `revert-*` branch and merge its PR. The apply then runs on the merge push to `dev`.
87
158
  ```bash
88
159
  git push origin dev
@@ -103,50 +174,10 @@
103
174
  - The migration ledger must match the reverted tree's migration files. For example, on Supabase, compare `psql "$SUPABASE_DB_URL" -c 'SELECT version FROM supabase_migrations.schema_migrations ORDER BY version;'` with `ls supabase/migrations/`.
104
175
  - Re-run the schema-aware test suite (e.g. `pnpm test:integration`) to confirm DB and code agree.
105
176
 
106
- ## Commit-message force tags
107
-
108
- bkit's `bkit-ci.yml` recognises the tags below. They are case-sensitive and use the literal `[...]` form. A tag may appear anywhere in its source string. Tags compose: several on the same commit or PR title each fire independently.
109
-
110
- **Where to put the tag:**
111
-
112
- - **Direct push to `dev` or `{{DEFAULT_BRANCH}}`** (no PR): put the tag in the commit message (`github.event.head_commit.message`).
113
- - **Feature branch with an open PR** (open, synchronize or edit): put the tag in the PR title (`github.event.pull_request.title`). The commit message is not read, because the workflow fires on `pull_request`, not `push`.
114
- - **Both surfaces** are checked by `contains()` in the env block, and a marker in either one wins for its event. Pick the right one: `[verbose ci]` in a feature-branch commit message has no effect, because only the PR title is read.
115
- - **`workflow_dispatch`**: neither field is filled, so every marker is inert. The planner sets `MSG=""` for events other than `push` and `pull_request`, and silently drops `[force full]`, `[force build]` and `[verbose ci]`. Steer a dispatch with inputs, never a marker. Inputs are mandatory when the dispatch default is expensive, for example when a dispatch forces the metered native build lanes past their reuse gate and spends build quota on every run. Gate the lookup behind an input that defaults to `false`.
116
-
117
- <!-- prettier-ignore -->
118
- | Tag | Effect | Scope |
119
- | --- | --- | --- |
120
- | `[force cache]` | Busts the task-runner cache for the run — recompute instead of replaying cache hits (e.g. turbo: `TURBO_FORCE=1`). Use when investigating suspected ghost-greens. | Read by `Detect Direct Push` |
121
- | `[force build]` | The lighter hammer. Exposes `should_force_build=true` + `run_level=full`. It does not bypass `web_affected`, so integration, e2e and @live run only when web is genuinely affected. Use it to rebuild without paying @live's side effects. Deploy steps act on it only when they gate on the output. | Read by `Detect Direct Push` |
122
- | `[force full]` | The hammer. Sets `run_level=full` and bypasses `web_affected`, so integration, `bkit-tests-e2e-web`, and `bkit-tests-live-web` run on any commit, including docs-only. The E2E spec set does not change, because a PR already runs the full suite. `@live` stays push-only: a docs-only `[force full]` push reaches it through the effective `web_affected`, but a PR or a dispatch never does. | Read by `Detect Direct Push` step |
123
- | `[verbose ci]` | Escalates log detail for one run. Shipped stub flips turbo / Node / Vercel / Supabase / Playwright knobs: `TURBO_LOG_LEVEL=full`, `NODE_OPTIONS=--trace-warnings --trace-deprecation` (a job-level `env:` key, never a `$GITHUB_ENV` write, which the runner rejects while still reporting success), `DEBUG=vercel:*,supabase:*`, plus Playwright `--trace=on` (when E2E stub enabled). Add your stack's equivalents to the same `env:`. Use when `bkit-debug` diagnose returns thin evidence; never for routine pushes (trace.zip files are MB-scale). See `testing.md` for the full knob list and the `--reporter=line` hostile gap. | Read by the job-level `env:` of `bkit-tests-static` (copy the same `env:` onto each lane) |
124
- | `[skip ci]` / `[skip actions]` | Honoured natively by GitHub Actions, so it suppresses workflow dispatch entirely. Use sparingly: the suppressed run will not appear in `gh run list`, and downstream `workflow_run` triggers will not fire. | Native GitHub behaviour, not a bkit-level toggle |
125
-
126
- **Two deploy-forcing markers only: `[force build]` and `[force full]`.** There is no granular `[force e2e]` or `[force live]`, because they would be silent no-ops gated behind `web_affected`. `[force full]` is the single gate bypass ("validate everything"): one effective `web_affected` drives integration, e2e and @live the same way.
127
-
128
- - **Precedence: `[skip ci]` / `[skip actions]` vetoes any force marker.** A `[skip ci]` commit never dispatches, because GitHub suppresses it natively before `bkit-ci.yml` runs. No force marker undoes that. To validate a commit that would be skipped, drop `[skip ci]` and push with `[force full]`.
129
- - **`[force cache]` is a separate axis.** It busts task-runner replay (for example, turbo `TURBO_FORCE=1`), which is a different axis from which lanes run. It is never folded into `[force full]`. Combine `[force full] [force cache]` for "everything, fresh."
130
- - **Marker parity (deploy-forcing set).** The e2e and @live lanes resolve a per-SHA deployment, so a marker that force-runs them must also force the host build. Otherwise the lane dies at "resolve deployment URL". The host build-cancel script (for example, Vercel `ignoreCommand`) must honor every marker in the deploy-forcing set: the shipped `[force build]` and `[force full]`, plus any consumer marker that widens a deploy-backed lane. Assert this in CI (`grep -qF` over the cancel script). `[force cache]`, `[verbose ci]` and `[skip ci]` act on the test plane only, and the cancel script does not honor them.
131
- - **Match a signature, not a spelling.** A value-list marker (`[platform web ios]`) is invisible to a substring test for `[platform web]`. Match the opening token (`[platform `) on both sides. An assertion pinned to one spelling stays green while the cancel script kills the build the marker asked for.
132
- - **A widening marker is an or term, never a condition.** A marker that adds a lane the affected graph missed must only widen. Used as a condition (`contains(plan.platforms, 'web')` in a lane `if:`), it also removes: `[platform ios]` on a web-touching commit silently drops the web lane, and the run goes green. Guard the direction with a check over the workflow text, and mutation-prove it both ways. Intent alone does not hold this shape.
133
- - **Widen the job gate and the step gates together, or not at all.** A job-level `if:` alone starts the lane while every step inside it skips. The result is a green lane that ran nothing, which is the capstone's own failure mode, arriving where the capstone cannot see it. Step-level readers of a plan value can far outnumber its job-level readers, so count them before you widen a shared plan value.
134
- - **Forcing a subset** (builds without their tests): do not widen the shared value. Derive a new boolean beside it (`build_forced` next to `web_affected`), and gate only the lanes it owns. This is valid only for a lane with no step-level reader of that value. Assert that directly, with an error message that names what breaks when someone adds one.
135
- - **Invoke the marker parser unconditionally.** A substring pre-gate in front of a parser is a silent no-op. A pre-gate on the literal `[screenshots ` with a trailing space never matches a bare `[screenshots]`, so the step exits 0 with an empty plan, and the run goes green having captured nothing. Run the parser every time, and let it own every failure class (unknown value, invalid combination, arguments to a bare flag), loudly, in the planner, before any lane starts.
136
-
137
- A direct push to `dev` (no merged PR ancestry) auto-busts the task-runner cache (for example, turbo `TURBO_FORCE=1`) regardless of tags. See the `bkit-debug` runbook for why the cache is busted.
138
-
139
- ## Autonomous phase-close prerequisites
140
-
141
- The design and plan Close Workflow lands docs on `dev` in one of two ways. Every runtime first builds the close commit off `origin/dev` and pushes it straight to `dev`. When that push goes through, no repo setting is required, and no PR is created. When GitHub refuses it (branch protection or a ruleset on `dev`), the close opens a PR and squash-merges it, which adds two repo prerequisites. Neither is pre-flighted, because no admin-scope token is required. Instead, a missing prerequisite shows itself when the close's own merge fails loudly.
142
-
143
- - **Branch protection on `dev` permits the autonomous merge**, because no human review is required. The PR-path merge does not wait for checks: its merge subject carries `bkit [skip ci]`, so a docs-only close dispatches no run to wait for. A rule requiring status checks to pass will block it.
144
- - **"Automatically delete head branches" is enabled** (repo Settings → General). The PR-path close deliberately does not pass `--delete-branch`, because `gh` would also delete the local branch. That fails when the branch is checked out in a worktree, and returns non-zero after a successful merge. Head-branch cleanup relies on the repo setting instead.
145
-
146
- Confirm both before running phase closes from a cloud agent session.
147
-
148
177
  ## Run-level decision matrix
149
178
 
179
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
180
+
150
181
  bkit ships a mostly flat, wide scaffold. `bkit-tests-scope` always runs. It reads the markers once, computes `run_level`, the optional `run_migration` and `tenant_target`, and emits the `bkit-test-plan` JSON. It fans out to every lane (`bkit-tests-static` / `-unit` / `-build-web` / `-build-ios` / `-build-android` / `-integration` / `-e2e-web` / `-e2e-ios` / `-e2e-android` / `-live-web` / `-migration` / `-reset` / `-cleanup`), and `bkit-tests-check` joins them. `bkit-tests-deploy` runs on a push to the default branch only, promotes the release before the E2E / `@live` lanes run, and is not required. Static/unit/integration/build wait only on the planner.
151
182
 
152
183
  **Ordering edges:**
@@ -164,20 +195,22 @@ Adopt only the lanes this repo has. Lane names and the adopt order are in `testi
164
195
  | --- | --- | --- | --- |
165
196
  | `none` | `[skip ci]` / `[skip actions]`; or release-PR mirror mode (the capstone copies the `dev` push run — § One CI run per dev commit). | Planner, then stop. | Every test lane. |
166
197
  | `partial` | Push to `dev` that came from a merged PR, and no `[force build]` / `[force full]`. | Static, unit, integration when `web_affected`, build lanes, migration. `@live` (`bkit-tests-live-web`) still runs on this push when `web_affected`. | `bkit-tests-e2e-web`. Deploy (not the default branch). |
167
- | `full` | Pull request; `workflow_dispatch`; push to `{{DEFAULT_BRANCH}}`; direct push to `dev` (no merged PR); `[force build]` / `[force full]`. | Partial's lanes, plus `bkit-tests-e2e-web` when `web_affected`. Same spec set as a push (`testing.md` § E2E on PRs). | `@live` off a PR and off a dispatch. On a default-branch push, `bkit-tests-deploy` promotes before the E2E / `@live` lanes run. It is not required, and its own `concurrency:` group stops two releases overlapping. Health runs as `workflow_run` after CI. |
198
+ | `full` | Pull request; `workflow_dispatch`; push to `main`; direct push to `dev` (no merged PR); `[force build]` / `[force full]`. | Partial's lanes, plus `bkit-tests-e2e-web` when `web_affected`. Same spec set as a push (`testing.md` § E2E on PRs). | `@live` off a PR and off a dispatch. On a default-branch push, `bkit-tests-deploy` promotes before the E2E / `@live` lanes run. It is not required, and its own `concurrency:` group stops two releases overlapping. Health runs as `workflow_run` after CI. |
168
199
 
169
200
  Device lanes follow `plan.run_native_*`, not `run_level`. The same rule holds on a PR, a push (including `partial`), and a dispatch.
170
201
 
171
202
  ## One run per branch or pull request
172
203
 
204
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
205
+
173
206
  ```yaml
174
207
  group: ci-${{ github.workflow }}-${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || github.ref }}
175
- cancel-in-progress: ${{ github.ref != 'refs/heads/{{DEFAULT_BRANCH}}' }}
208
+ cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
176
209
  ```
177
210
 
178
211
  A newer run cancels the older one on every event except the default branch, which queues. That run promotes the deployment, so cancelling it mid-promote could strand production across two releases (§ Promote before the lanes). A pull request keys on its number, and a push or dispatch keys on the ref, so a PR and a `dev` push still overlap. A `workflow_run` observer sees the latest run on that ref only.
179
212
 
180
- A push diffs against the head of the last successful CI run on that branch, not `github.event.before`. Fall back to `github.event.before` only when there is no such run, or when that run's head is no longer an ancestor. A `workflow_dispatch` has no base commit, so short-circuit the affected step to fully affected. `HEAD~1` is only for the delta gates on a dispatch. Markers are inert on a dispatch, so steer it with inputs (§ Commit-message force tags). The planner parses markers once, and every lane reads `plan.markers_present`. The only re-read of the commit or PR text is the workflow-level task-runner cache bust (for example, `TURBO_FORCE`). Validate the plan JSON with `has()` / `!= null`, because jq `//` treats `false` as absent and drops a real `run_live: false`.
213
+ A push diffs against the head of the last successful CI run on that branch, not `github.event.before`. Fall back to `github.event.before` only when there is no such run, or when that run's head is no longer an ancestor. A `workflow_dispatch` has no base commit, so short-circuit the affected step to fully affected. `HEAD~1` is only for the delta gates on a dispatch. Markers are inert on a dispatch, so steer it with inputs (`.bkit/workflows.md` § Commit-message force tags). The planner parses markers once, and every lane reads `plan.markers_present`. The only re-read of the commit or PR text is the workflow-level task-runner cache bust (for example, `TURBO_FORCE`). Validate the plan JSON with `has()` / `!= null`, because jq `//` treats `false` as absent and drops a real `run_live: false`.
181
214
 
182
215
  Migration-immutability and slop-delta run on every event against that same base. The starter's copies of those steps are still `pull_request`-only, and that `if:` is the shape from before the planner existed. Point them at the planner base once `bkit-tests-scope` exists. Pre-push on a `dev` push resolves the same base (`bkit-resolve-push-base.mjs --local`, `.bkit/templates.md` § Git hooks) and exports it as `SLOP_BASE_REF`. A repo-owned migration-immutability pre-push check reads that variable too.
183
216
 
@@ -258,7 +291,7 @@ This is optional. A same-repo promotion PR into the default branch (head `dev`,
258
291
 
259
292
  1. **A `dev` push resolves `run_level=full`.** Drop the merged-PR → `partial` arm from `Decide Run Level`. A `partial` push run skips E2E, and the release PR inherits that.
260
293
  2. **A push run diffs against the last green push run's head**, not `github.event.before`. Otherwise a red run N followed by an unrelated commit N+1 plans a green N+1 that never re-tests what N broke, and the mirror copies that green.
261
- 3. **Promotion hangs off the push to `{{DEFAULT_BRANCH}}`** (`bkit-tests-deploy`; § Promote before the lanes), never off the PR check. The mirror is the merge gate, and the default-branch push run is the release gate.
294
+ 3. **Promotion hangs off the push to `main`** (`bkit-tests-deploy`; § Promote before the lanes), never off the PR check. The mirror is the merge gate, and the default-branch push run is the release gate.
262
295
 
263
296
  **Operating it:**
264
297
 
@@ -267,10 +300,12 @@ This is optional. A same-repo promotion PR into the default branch (head `dev`,
267
300
  - A red push run that is re-run to green does not update the PR. Re-run the PR's `bkit-tests-check` afterwards.
268
301
  - A new `dev` push moves the PR head. `pull_request` concurrency cancels the old mirror and starts one for the new SHA.
269
302
  - The release PR gives up PR-only output (coverage comments, PR-only coverage measurement). None of it blocks a merge.
270
- - Feature → `dev` PRs are unaffected. `pull_request => run_level=full` (§ Consumer CI contract) still holds there, and `/bkit-ship`'s gate relies on that.
303
+ - Feature → `dev` PRs are unaffected. `pull_request => run_level=full` (`.bkit/workflows.md` § Consumer CI contract — `pull_request` resolves to `run_level=full`) still holds there, and `/bkit-ship`'s gate relies on that.
271
304
 
272
305
  ## Workflow-file limits GitHub does not enforce visibly
273
306
 
307
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
308
+
274
309
  **The 21,000-character expression cap.** GitHub compiles every block scalar containing a `${{ … }}` expression as one expression and refuses to compile the workflow past 21,000 characters:
275
310
 
276
311
  ```
@@ -283,77 +318,10 @@ The cap is undocumented and invisible to the toolchain, because the file stays v
283
318
  - **Guard below the cap, not at it.** 20,999 leaves the next edit no room, and it fails unreadably. In the static lane, scan `.github/workflows/*.{yml,yaml}`, measure every block scalar containing `${{`, and fail with a margin (for example, at 20,000).
284
319
  - **A long `run:` body is the symptom.** The fix is rarely compression. Move the logic into a script the step calls (`node scripts/ci/…`), which also makes it unit-testable.
285
320
 
286
- ## Post-merge dev CI auto-routing
287
-
288
- `bkit-cloud.yml`'s `workflow_run` trigger fires when CI completes on `feat/**` and `dev`, never on `main`. The per-branch success / failure matrix lives in `.bkit/cloud.md` § Branch-aware routing. The post-merge surfaces add the following on top of it:
289
-
290
- - **Trigger scope.** Dispatch jobs gate on `workflow_run.head_repository` being this repo, so a fork PR's CI completion never boots one. On `dev`, the same gate excludes `conclusion == 'success'` outright, so a green post-merge run costs zero runner minutes. The merge already happened, so that run only confirms the regression check passed.
291
- - **FID recovery on `dev`.** No open PR exists, so `{FID}` comes from the squash-merge commit scope (`feat({FID}): …`) first. The fallback is the `bkit:fid` marker in the body of the merged same-repo PR for that SHA. **If** neither resolves → it does nothing and dispatches nothing.
292
- - **Loop bound.** A `dev` CI failure dispatches `/bkit-debug` until the `{FID}` has `bkit.workflows.debug.fix.maxAttempts` + `bkit.workflows.debug.soak.maxAttempts` distinct failed CI SHAs (2 + 2 by default). `/bkit-debug` creates no branch of its own, so on this surface it remediates on `dev` itself, and its push re-triggers this same router. The cap is what ends that loop. `feat/**` is not capped here. `/bkit-debug` bounds it with the same two limits, counted across every debug run of the feature.
293
-
294
- **Auto-route contract:** whenever the issue carries `bkit:auto`, `/bkit-ship` adds the `bkit [auto route]` free-tier gate marker to the squash-merge `--subject` (not just the sync-merge commit). That marker is what lets `dev`-triggered runs through the existing `bkit-cloud.yml` gate, and there is no second gate path. The `[skip ci]` ship-DONE close commit that follows the squash merge never carries the marker and never triggers CI, so it cannot interact with this trigger. The trust surface, the kill switch and the cap's tamper caveat are in `docs/security.md` § CI Auto-Route Trust.
295
-
296
- **Docs-only-diff precondition:** the `dev`-trigger path routes every post-merge CI failure to `/bkit-debug`. That is correct for docs-only diffs only when the consumer's `bkit-ci.yml` deploy-await step treats a host-cancelled build as a skip, not a red (skip e2e and stay green; for example, Vercel `CANCELED`). **If** a consumer reds on a host-cancelled build → every docs-only squash-merge to `dev` falsely dispatches `/bkit-debug` and burns loop-cap budget. Verify this for each consumer before you rely on the `dev` trigger.
297
-
298
- **Consumer-repo acceptance note:** the full happy-path loop (squash-merge → post-merge CI → `workflow_run` → `/bkit-debug` dispatch → fix PR → re-merge) can only be exercised on consumer repos that have `bkit-cloud.yml` installed and its dispatch secrets wired (see the cloud-agent auth surfaces in `docs/security.md`). A consumer without `bkit-cloud.yml` installed, or without CI running on `push: branches: [dev]`, never emits the `workflow_run` event this trigger depends on. The feature then becomes a silent no-op, not a failure.
299
-
300
- ## Ship gate + bookkeeping
301
-
302
- `/bkit-ship` is keyed on `bkit branches sync --head=<PR head>`, which reports whether `origin/dev` is an ancestor of the PR head (`basePath`).
303
-
304
- - **Path A** (`dev` has not moved) resumes read-only: no merge, no bookkeeping commits, no push. Then it merges.
305
- - **Path B** (`dev` moved) merges `origin/dev` into the feature branch locally with `bkit branches sync --merge`, pushes it plain, and re-validates the merged head. The block commits the run's uncommitted work first, unions the append-only ledgers, takes a conflicted lockfile from `dev` before regenerating it, takes a conflicted generated register (`docs/capabilities.md`) from `dev` before rebuilding it, with `dev`'s copy of the generated block in a doc the register's script copies that block into, and merges a conflicted install record (`.bkit/version`) entry by entry, with `dev`'s value where both sides changed an entry; a conflict outside those goes to `@bkit-ship-conflict-resolve`, which hand-resolves it and re-runs the block. A server-side update-branch is never used, because GitHub ignores `merge=union` and reports a ledger-only divergence as a conflict.
306
-
307
- Both paths end at the same gate: `bkit runs gate --head=<current>` exits 0 (capstone concluded `success`) at the current PR head.
308
-
309
- ### Consumer CI contract — `pull_request` resolves to `run_level=full`
310
-
311
- The merge gate (`bkit runs gate`) asserts the capstone job's `conclusion=success` at the head being merged. That assertion only means something while `pull_request => run_level=full` holds: the capstone is green because every expected tier ran and passed, not because the lanes were skipped (see `## Run-level decision matrix` above). A consumer that narrows CI on `pull_request` has, by doing so, opted out of the merge-gate guarantee:
312
-
313
- - **`paths-ignore` / `paths` filters** that skip `pull_request` on some changes mean the capstone may not run at all. With no workflow run at the head, the gate refuses with code 10.
314
- - **A docs-only short-circuit** in the host's build-cancel (Vercel `ignoreCommand` / Netlify) that cancels the run mid-flight means the capstone may land `cancelled` (gate code 15) or never complete (code 11).
315
- - **A `[skip ci]` token** in a feature-branch commit subject when the PR opens makes GitHub suppress the `pull_request` run entirely. The PR's `statusCheckRollup` is then vacuously empty, so there is no run at the head (gate code 10).
316
-
317
- `bkit runs gate` covers the common violation shapes. It reports a skipped non-capstone lane but does not refuse it, because the judgement of planned versus vacuous belongs to the capstone, which takes every lane result as an input and already asserts it per lane. The gate cannot make that judgement itself, because the jobs API reports no reason for a skip: a job skipped by a job-level `if:` never reaches a runner, so it carries an empty `steps` array.
318
-
319
- **Code 16 is opt-in, and must stay that way.** It fires only for lanes named in `bkit.testing.ciRequired` (a package.json array), and the default empty list never refuses. A blanket refuse-on-any-skip can never be satisfied with the CI shape bkit ships. A lane whose `if:` is event-scoped cannot run pre-merge at any head: `bkit-tests-live-web` runs on a push to `dev` or the default branch only. A pre-merge gate that demands such a lane refuses every PR forever. Device lanes (`-ios` / `-android`) use the same rule on a pull request and a push, so do not treat them as post-merge canaries. Name a lane in `bkit.testing.ciRequired` only when your capstone does not assert it and the lane genuinely can run pre-merge. `BKIT_SHIP_GATE_OVERRIDE` remains the audited per-head escape hatch.
320
-
321
- **Code 12 on generated files gets one fix round (`bkit.testing.ciGenerated`).** When CI fails at the head, the gate reads the run's jobs and prints each failed step outside the capstone as `{job}/{step}` (`failedSteps`). A job that failed, timed out or was cancelled with no failed step prints as `{job}/`, which matches no entry. `regenerable` = true when every failed step is on the list: the fixed floor `CI_GENERATED_FLOOR` (`bkit-tests-static/Check Capability Register`, `bkit-tests-static/Run bkit Check`, the two template steps a stale `bkit:generate` output fails) plus the repo's `bkit.testing.ciGenerated`. Ship Step 10 then runs `bkit branches regenerate`, commits only what `bkit:generate` changed, pushes and lets CI re-check, within `bkit.workflows.ship.merge.maxAttempts`. One failed step off the list sends the whole refusal to the Failure Path, because fixing half of it still leaves CI red.
322
-
323
- - **Add** a step to `bkit.testing.ciGenerated` (a package.json array of `{job}/{step}`, the job id and the step's `name:` in your CI workflow) only when `bkit:generate` writes what that step checks. bkit's own repo lists `bkit-tests-static/Assert Dist Freshness`, because `bkit:generate` rebuilds `dist/`.
324
- - **A missing, malformed or empty list** leaves the floor alone. The key adds to the floor and cannot remove from it.
325
- - **A repo without a `bkit:generate` script** → `regenerate` reports `undeclared` and ship goes to the Failure Path.
326
-
327
- Codes 10-15 still carry the guarantee that a green result is not vacuous: a run exists, at this head, completed, not cancelled, with the capstone present and green. Code 14 (green at a superseded head) requires `--branch`. The head-keyed run query is filtered server-side, so a moved head returns the same empty list as a head that never ran, and only a second branch-scoped query separates them.
328
-
329
- A run that is present and degraded but not skipped (for example, a required lane ran a reduced test set because of a consumer config the gate cannot see) is a residual risk. It is named here, and not claimed as covered. The capstone is green because bkit's own `run_level` planner computed `full`, and a consumer narrowing inside a lane bkit does not own is invisible to the gate. Keep the capstone (`bkit-tests-check`) as the sole branch-protection required check, so `green == validated` survives a docs-only push. Do not add per-lane required checks, because a hollow lane then green-bars the capstone.
330
-
331
- **No duplicate dispatch on an already-triggered head (ship Step 9):** a branch push fires `pull_request` at the new SHA on its own, unless its HEAD carries `[skip ci]`. Ship's Step 4 merge push carries no skip token, so it fires a run there. The scaffold keys a pull request on `pr-{number}` and a `workflow_dispatch` on `github.ref`. The two are separate groups, so a redundant dispatch is never cancelled and burns a full duplicate run. Ship probes the head whose CI the gate will check (`VALIDATED_HEAD`) with `bkit runs wait --head=<VALIDATED_HEAD> --branch=<branch> --until=present --dispatch-if-absent`, which dispatches only when no run appears. The probe is not a pass condition. The completion wait (`bkit runs wait --head=<VALIDATED_HEAD> --until=completed`) reads only runs at that exact head, so a completed run from a superseded head never answers it. Gate codes 10 / 11 / 14 / 17 re-enter that probe-and-poll only, never the deferred sweep. `bkit.workflows.ship.merge.maxAttempts` bounds the retries, and it counts gate refusals and failed merges together.
332
-
333
- **No CI run for ship's own docs commit (validated-head carry-forward):** ship's pre-merge `[skip ci]` bookkeeping commit (docs, summaries, ledgers, skill removals) runs no CI.
334
-
335
- - **If** every path between the last CI-tested commit and the PR head is on the bookkeeping allow-list (`bkit ledgers only-bookkeeping`) → `bkit runs gate --validated=<sha>` checks CI at the tested commit.
336
- - **Else** → the gate refuses with code 17.
337
-
338
- The merge still pins the exact head (`--match-head-commit`). A green PR costs zero extra runs. The bookkeeping commit merges untested, and post-merge `dev` CI (the `ship-merge-ci` row) is the backstop. **If** `dev` requires status checks (classic branch protection or a ruleset) → GitHub refuses a head with no run, so ship runs CI at the PR head.
339
-
340
- ### Consumer rollback path
341
-
342
- To unwind a bad ship surface (the gate command, managed config, or a rewritten `bkit-ship.md`) without downgrading unrelated fixes:
343
-
344
- 1. **Pin the previous `@cbartens/bkit`** in `package.json`. The sliding `@v{N}` tag receives patches automatically, so a regression lands through the tag. Pin to the last known-good immutable `v{N}.x.y` or `@<sha>` (see § Sliding major-version tag). Re-install, and confirm that `bkit check` reports no drift.
345
- 2. **Hold `bkit upgrade` for `.bkit/core/workflows/bkit-ship.md`** until the regression is fixed upstream. The gate (`bkit runs gate`) and ship's waits ship inside the `@cbartens/bkit` package (`dist/`), not as files in your repo, so the version pin in step 1 is what rolls them back. Other bkit upgrades are independent.
346
- 3. **Audit any `BKIT_SHIP_GATE_OVERRIDE` rows** written in the meantime in `docs/plans/{YYYYMM}/logs/{FID}/status.jsonl`. Each `type:"ship-gate-override"` row is a sanctioned escape that turned a refusal into a merge. Treat every row as a PR whose capstone was not green at the merged head, and re-verify it against the pinned-good gate (`bkit runs gate --head=<sha>`). `[bkit-runs] override honoured for head …` is the matching `docs/observability.md` grep key.
347
- 4. **No per-workflow pin or revert exists.** The package pin plus the selective `bkit upgrade` hold is the recovery path. Document any incident in `docs/failures.jsonl`.
348
-
349
- Ship's docs sync, summaries, `SHIPPED` roadmap row and skill removals ride the PR as one `[skip ci]` commit on the feature branch before the merge. The other pre-merge pushes are opening a missing PR, the Path B merge push, a `bkit:generate` commit (Path A, and the regenerate round after a red CI run) and a Failure Remediate fix. Status rows (`status.jsonl`) go to the feature worktree's tree on every runtime (`BOOK_ROOT` = `{WORKTREE_PATH}`), and ship never checks out `dev`. See `.bkit/workflows.md` § `status.jsonl` — workflow state SoT. The post-merge tail is one `[skip ci]` close commit, built in a throwaway checkout of `origin/dev`, that carries the book:
350
-
351
- - Ship pushes it to `dev`.
352
- - **If** `dev` moved → ship rebuilds the commit and pushes again.
353
- - **If** the push is refused → ship opens a `ship-close/{FID}` PR.
354
-
355
321
  ## Smoke trigger plumbing
356
322
 
323
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
324
+
357
325
  Smoke runs after the deploy, in its own workflow, off the merge gate (what it actually probes is in `testing.md` § Smoke). When `bkit-tests-deploy` promotes inside CI, that probe is `bkit-health.yml` (`.bkit/templates.md` § Health check): one workflow, not a second smoke file. Pick the trigger by where the deploy happens, not by habit:
358
326
 
359
327
  - **If** the deploy happens inside CI → key smoke to `workflow_run` (the CI workflow `completed`, any conclusion), and probe only when production serves that run's commit. The deploy promotes before the tenant lanes, so a red run can still have put a release live. Fail, rather than skip, when production's commit cannot be read. Mind the 3-level `workflow_run` chain cap, because a fourth chained workflow will not fire.
@@ -364,6 +332,8 @@ Smoke runs after the deploy, in its own workflow, off the merge gate (what it ac
364
332
 
365
333
  ## Applying migrations at deploy time
366
334
 
335
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
336
+
367
337
  The deploy-time apply and the test-time replay gate are different guarantees. Keep both, preferably in the same always-on lane (`bkit-tests-migration`):
368
338
 
369
339
  - **Apply (deploy path):** push only the new migrations onto the already-migrated remote. The apply is idempotent: it applies what is not yet in the ledger, so it is safe to retry. It never replays from empty and never runs the seed.
@@ -379,8 +349,16 @@ The deploy-time apply and the test-time replay gate are different guarantees. Ke
379
349
  - Do not assume the deploy-time apply also validates a clean from-scratch install or the seed, because it does neither.
380
350
  - Do not put the remote push inside e2e while live is not gated on e2e.
381
351
 
352
+ ### This project
353
+
354
+ > **Project slot:** what applies this project's migrations, and when.
355
+
356
+ [What applies migrations to each environment, and when it runs.]
357
+
382
358
  ## Build-vs-migration race
383
359
 
360
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
361
+
384
362
  When your host auto-deploys on push (Vercel / Netlify Git integration) while CI applies migrations as a separate, unordered step, the deploy's build and the migration race. A build-time DB read that lands before the migration creates its object makes the first deploy that ships it fail with a hard error. Build-time reads come from any statically rendered or build-generated route. Examples in Next.js: `sitemap.ts` / `robots.ts`, `generateStaticParams` / `generateMetadata`, an OG-image route, a static (non-dynamic) page's server read, or marking a DB route `force-static` / ISR. The missing-object error signatures in Postgres, for example, are `42P01` (relation), `42703` (column), `42704` (type) and `3F000` (schema).
385
363
 
386
364
  **Fingerprint:** prod keeps serving the prior deployment, and a redeploy of the same SHA clears the error. A genuinely bad migration would not clear itself on a redeploy.
@@ -394,7 +372,9 @@ The race stays hidden until the first build-time DB read lands, so flag it in re
394
372
 
395
373
  ## Promote before the lanes (`bkit-tests-deploy`)
396
374
 
397
- With `bkit-tests-deploy` adopted, the host does not auto-build the default branch. `bkit-tests-build-web` creates this SHA's deployment, polls it until it is ready, and publishes `deployment_url` + `deployment_id`. The production alias still serves the previous release. `bkit-tests-deploy` `needs: [bkit-tests-migration, bkit-tests-build-web]`, runs on a push to the default branch only, and is not a required check. It promotes the exact `deployment_id` the build lane published, without looking the deployment up again by SHA. A `409` counts as success only when the body says this id is already current production. On `{{DEFAULT_BRANCH}}` it runs before the E2E / `@live` lanes. Each of those lanes `needs:` it and starts by proving, by deployment id, that production serves this run's build. A re-run after a rollback therefore refuses, instead of testing the old build and going green. A red deploy job means the release did not happen, and production still serves the previous deployment.
375
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
376
+
377
+ With `bkit-tests-deploy` adopted, the host does not auto-build the default branch. `bkit-tests-build-web` creates this SHA's deployment, polls it until it is ready, and publishes `deployment_url` + `deployment_id`. The production alias still serves the previous release. `bkit-tests-deploy` `needs: [bkit-tests-migration, bkit-tests-build-web]`, runs on a push to the default branch only, and is not a required check. It promotes the exact `deployment_id` the build lane published, without looking the deployment up again by SHA. A `409` counts as success only when the body says this id is already current production. On `main` it runs before the E2E / `@live` lanes. Each of those lanes `needs:` it and starts by proving, by deployment id, that production serves this run's build. A re-run after a rollback therefore refuses, instead of testing the old build and going green. A red deploy job means the release did not happen, and production still serves the previous deployment.
398
378
 
399
379
  Before it promotes, the job refuses and moves nothing in either of these cases:
400
380
 
@@ -406,7 +386,7 @@ A re-run of an old run then cannot move production back to an older release.
406
386
  - **If** production is unreadable, or its deployment records no commit → refuse.
407
387
  - **If** it is the same commit → promote, because the re-run is idempotent.
408
388
 
409
- Two guards keep a release honest. The deploy job carries its own `concurrency:` group (`cancel-in-progress: false`), so two releases never overlap. The workflow-level block queues on `{{DEFAULT_BRANCH}}` (§ One run per branch or pull request), so a newer push waits instead of cancelling a switch in flight. `bkit-tests-migration` waits for static / unit / integration / `build-web` before it touches production's database.
389
+ Two guards keep a release honest. The deploy job carries its own `concurrency:` group (`cancel-in-progress: false`), so two releases never overlap. The workflow-level block queues on `main` (§ One run per branch or pull request), so a newer push waits instead of cancelling a switch in flight. `bkit-tests-migration` waits for static / unit / integration / `build-web` before it touches production's database.
410
390
 
411
391
  Do not add a host-side "hold promotion until a named check passes" setting (for example, Vercel Deployment Checks). That list stays empty, because this job is the promotion. On Vercel, for example, `git.deploymentEnabled` is false for the default branch, and auto-assign of production domains is off.
412
392
 
@@ -414,6 +394,8 @@ The capstone `needs:` `bkit-tests-deploy`, so on a default-branch push a skipped
414
394
 
415
395
  ## Disable GitHub Code Quality billing
416
396
 
397
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
398
+
417
399
  GitHub Code Quality (coverage-on-PR plus the `Code Quality: CodeQL` runs) bills per active committer, plus Actions minutes, plus AI credits. It is opt-out: a repo with default setup enabled is billed silently until it is turned off.
418
400
 
419
401
  - **If** your repo has Code Quality default setup enabled → either disable it in repo → **Settings → Code security → Code Quality** (turn off default setup), or accept the per-committer charge.
@@ -421,6 +403,8 @@ GitHub Code Quality (coverage-on-PR plus the `Code Quality: CodeQL` runs) bills
421
403
 
422
404
  ## GitHub Actions pinning
423
405
 
406
+ > **bkit practice:** keep this section; bkit's CI template, advisories and audits cite its heading by name, so leave the heading text unchanged.
407
+
424
408
  **Pin every third-party dependency to an immutable digest, and pair each pin with an updater.** A floating ref (a `@v{N}` tag, a `ubuntu:26.04` image, an unversioned `curl … | bash`) is mutable, because a compromised maintainer can re-point it, on their next push, to malicious code that runs with your runner token. It is one exposure class across three surfaces:
425
409
 
426
410
  - **Actions:** pin every `uses:` to a 40-character commit SHA, never `@v{N}`. Resolve it with `git ls-remote https://github.com/<owner>/<repo>.git 'refs/tags/vX.Y.Z'`, and append a `# vX.Y.Z` comment so the version stays human-readable:
@@ -470,7 +454,7 @@ Use one, because both open PRs for the same packages. Record your choice in `bki
470
454
  <!-- prettier-ignore -->
471
455
  | Setting | Effect |
472
456
  | --- | --- |
473
- | `rebaseWhen: "conflicted"` | A PR is rebased only when it conflicts; the default re-runs CI on every auto-merge PR each time the base branch moves. |
457
+ | `rebaseWhen: "never"` | Renovate never rebases or updates an open PR by itself, so each update runs CI once. A PR that conflicts with `dev` waits until you tick its rebase checkbox. Otherwise each merge makes the other `pnpm-lock.yaml` PRs conflict, rebase and re-run the full CI. The Dependabot example sets `rebase-strategy: disabled` for the same reason. |
474
458
  | `schedule` | Every hour of Monday (UTC). A scheduled GitHub run can start hours after its cron time, so a window of a few hours misses the daily wake. |
475
459
  | `lockFileMaintenance.schedule` | Every hour of the first day of the month (UTC), for the same reason. |
476
460
  | Majors rule `dependencyDashboardApproval: true` | No branch, PR or CI run until you tick the update on the Dependency Dashboard issue. |
@@ -525,7 +509,7 @@ Fine-grained permissions for this repo:
525
509
 
526
510
  When Renovate is the updater, leave alerts on and turn security updates and version updates off so Dependabot does not open competing PRs.
527
511
 
528
- **Runner labels for bkit workflows.** `bkit-ci.yml`, `bkit-cloud.yml`, `bkit-renovate.yml` and `bkit-trivy.yml` are templates you copy and own; edit `runs-on` in your copy. The `bkit-cloud.yml` template ships the `{{CLOUD_RUNNER}}` placeholder in both jobs: replace it with a label (e.g. `ubuntu-latest`).
512
+ **Runner labels for bkit workflows.** `bkit-ci.yml`, `bkit-cloud.yml`, `bkit-renovate.yml` and `bkit-trivy.yml` are templates you copy and own; edit `runs-on` in your copy. The `bkit-cloud.yml` template ships the `{{CLOUD_RUNNER}}` placeholder in all four jobs (`context`, `claude`, `opencode`, `codex`): replace it with a label (e.g. `ubuntu-latest`).
529
513
 
530
514
  ### Manual CVE handling (when an alert fires)
531
515
 
@@ -538,4 +522,6 @@ Renovate's `osvVulnerabilityAlerts: true` opens CVE-driven PRs against `dev` imm
538
522
  4. Open a PR against `dev` titled `fix(security): bump <pkg> >=<fixed-version> (CVE-XXXX-YYYY)`. After the merge to `dev → main`, the alert closes automatically once GitHub re-scans the default branch.
539
523
  5. **If** a CVE has no impact on your usage pattern (for example, a dev-server-only vuln in a build tool that you never run as a server) → dismiss it in the GitHub UI with the "Vulnerable code is not actually used" reason and a one-line justification. Do not dismiss an alert without documenting why.
540
524
 
541
- <!-- bkit:end -->
525
+ ## Open questions
526
+
527
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -0,0 +1,117 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/design.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/components.md`.
4
+ >
5
+ > **Finish against:** `docs/technology.md`, once it names the styling tool; the token table in `## Machine-checked reference` waits for it.
6
+ >
7
+ > **Where the facts come from:** the stylesheet variables and theme files, the rendered style guide or design files, the user interface components in the repository and the accessibility settings.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/design.md`.
12
+ > 2. **If** the project has no user interface → write `Not applicable: no user interface` under the title, keep the rules box, delete every section except `## Open questions`, and go to step 9.
13
+ > 3. Fill `## Tokens` with the files that define the colour, spacing and sizing variables, and how the variables are named.
14
+ > 4. Fill `## Typography` with the font families, sizes and weights in use.
15
+ > 5. Fill `## Spacing and layout` with the scale, breakpoints and layout rules.
16
+ > 6. Fill `## Components` with the shared interface components and when each is used.
17
+ > 7. Confirm or change each default in `## Accessibility`.
18
+ > 8. Fill the token table in `## Machine-checked reference` with one row per colour, spacing and sizing variable, read from the implementation. Follow the steps in that section, and keep its two rules.
19
+ > 9. Record unresolved facts under `## Open questions`.
20
+ > 10. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/design.md` | ○ | ○ | ○ | — | — | The project's design system: tokens, typography, spacing and layout, components and accessibility rules. |
21
+ > 11. Check the document against each completion check, then delete this introduction.
22
+ >
23
+ > **If it does not apply:** write `Not applicable: no user interface` under the title and delete every section except `## Open questions`.
24
+ >
25
+ > **Completion checks:**
26
+ >
27
+ > - Every token in the implementation has a row in `## Machine-checked reference`, or an entry that says why it is undocumented.
28
+ > - Every default in `## Accessibility` is confirmed or replaced.
29
+ > - The token table in `## Machine-checked reference` has a header row and no row left as an example.
30
+ > - No example row remains.
31
+
32
+ # Design
33
+
34
+ > [!CAUTION]
35
+ > **Purpose:** The project's design system: tokens, typography, spacing and layout, components and accessibility rules.
36
+ >
37
+ > **Rules:**
38
+ >
39
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
40
+ > - Name each token once, in the table that holds its value.
41
+ > - Mark a value read from the implementation as transcribed until a human confirms it.
42
+ >
43
+ > **bkit practice:** `## Machine-checked reference` keeps its heading and its two rules, because the gates audit and the CI workflow cite it. Sections marked **bkit practice** keep their heading text and stay separate sections. Do not rename, merge or compress them, because bkit's CI template, advisories and audits cite them by name.
44
+ >
45
+ > **Not here:** Test lanes and design assertions go in `docs/testing.md`. The styling tool and its version go in `docs/technology.md`. Component ownership goes in `docs/components.md`.
46
+ >
47
+ > **Update when:** A token, a font, a shared component or an accessibility rule is added, changed or removed.
48
+
49
+ ## Tokens
50
+
51
+ [The files that define the colour, spacing and sizing variables, and how the variables are named.]
52
+
53
+ The token table is in `## Machine-checked reference`. A token's value is written in that table and nowhere else.
54
+
55
+ ## Typography
56
+
57
+ <!-- prettier-ignore -->
58
+ | Role | Family | Size and weight | Use |
59
+ | --- | --- | --- | --- |
60
+ | [Role] | [Font family.] | [Size and weight.] | [Where it is used.] |
61
+ | [e.g., Body text] | The project's text font. | Regular, base size. | Paragraphs. |
62
+
63
+ ## Spacing and layout
64
+
65
+ [The spacing scale, the breakpoints and the layout rules the interface follows.]
66
+
67
+ <!-- prettier-ignore -->
68
+ | Step | Value | Use |
69
+ | --- | --- | --- |
70
+ | [Step name] | [Value.] | [Where it is used.] |
71
+ | [e.g., Small gap] | The scale's second step. | Between a label and its field. |
72
+
73
+ ## Components
74
+
75
+ <!-- prettier-ignore -->
76
+ | Component | Use it for | Do not use it for |
77
+ | --- | --- | --- |
78
+ | [Component] | [When to use it.] | [What to use instead.] |
79
+ | [e.g., Primary button] | The one main action of a screen. | A second action on the same screen. |
80
+
81
+ ## Accessibility
82
+
83
+ [Each default below is a starting point. Confirm it or change it, and say why when it changes.]
84
+
85
+ - [Default: every colour comes from a theme token, with no ad-hoc hex value.]
86
+ - [Default: every colour supports a dark mode.]
87
+ - [Default: touch targets are at least 44 by 44 pixels.]
88
+ - [Default: text contrast meets WCAG 2.1 level AA.]
89
+
90
+ ## Machine-checked reference
91
+
92
+ > **bkit practice:** This table is the sole hand-maintained source for token values. Nothing generates it, so changing an expected value forces a human to restate the intent in the same pull request. Keep the section heading, because the gates audit and the CI workflow cite it.
93
+
94
+ Fill it in this way:
95
+
96
+ - **Select the table by its header row**, never by "any row containing a hex", because this document may hold more than one hex table. Renaming the header renames the contract, so update the parser in the same change.
97
+ - **Assert each implementation separately** (stylesheet variables, theme object, rendered style guide), so a red names its own culprit.
98
+
99
+ Two rules survive adoption:
100
+
101
+ - **No silent gap.** Every implementation token maps to a row here, or to an explicit "intentionally undocumented" entry with a reason. A dropped token must go red, not vanish.
102
+ - **Transcribed is not ratified.** A row read out of the implementation is tautological on day one, so mark it as transcribed until a human confirms the value is intended.
103
+
104
+ Choose your own columns, then pin them, because the header row is the contract. An example shape:
105
+
106
+ <!-- prettier-ignore -->
107
+ | Token | Light | Dark | Use |
108
+ | --- | --- | --- | --- |
109
+ | Background (`--background`) | `#FFFFFF` | `#0A0A0A` | Page surface |
110
+ | Foreground (`--foreground`) | `#181818` | `#F1EFEA` | Headings / body — 17.8:1 light, 17.2:1 dark (AAA) |
111
+ | Primary (`--primary`) | `#2563EB` | `#2563EB` | Aligned L+D — buttons / active. **Transcribed-not-ratified**: read from source, pending human confirmation |
112
+
113
+ Lane map, tagging, cache rules: `testing.md` § "Design assertions are a dimension, not a lane".
114
+
115
+ ## Open questions
116
+
117
+ [Each unresolved fact, who can answer it and which section it affects.]