@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -10,9 +10,9 @@ import { readBkitConfig } from "../../shared/settings.js";
10
10
  import { detectOpencodeYmlProviderDrift } from "../../install/modules/opencode.js";
11
11
  import { detectManagedDuplicate, detectManagedStale } from "./managed.js";
12
12
  import { buildCloudDashboardsAdvisory, detectCiRouterSecrets, detectGhMcpToken } from "./auth.js";
13
- import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectMainBranchProtection, } from "./github.js";
14
- import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
15
- import { detectBkitCloudYmlAlwaysTrueGate, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
13
+ import { buildCloudSetupAdvisory, buildGithubProjectAdvisory, buildGithubProjectTokenScopeAdvisory, buildTrackerSetupAdvisory, detectActionsWritePermissions, detectMainBranchProtection, } from "./github.js";
14
+ import { buildDepUpdaterSetupAdvisory, detectBkitStubs, detectValeMissing, detectValePackageNotSynced, detectWorkflowLintToolsMissing, } from "./tools.js";
15
+ import { detectBkitCloudYmlAlwaysTrueGate, detectCiScriptsOldNames, detectCiYmlCapstoneContractDrift, detectCiYmlMissingActionlint, detectCiYmlRunInjection, detectGhaFloatingTags, detectRunLevelsNotComposed, detectTaggedTestsWithoutCiHome, detectTestIntegrationEnv, detectTurboIntegrationInputs, } from "./ci-yml.js";
16
16
  import { dropTipSilencedAdvisories, setupTipsChecklistLines, setupTipsMarkdownLines, } from "../tips/index.js";
17
17
  // ---------------------------------------------------------------------------
18
18
  // formatChecklist — pure renderer
@@ -43,7 +43,7 @@ export function suppressedNoteLines(suppressed) {
43
43
  return [];
44
44
  const n = suppressed.length;
45
45
  return [
46
- `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.ignoreAdvisories:`,
46
+ `${n} advisor${n === 1 ? "y" : "ies"} suppressed by bkit.advisories.ignore:`,
47
47
  ...suppressed.map((note) => `- ${note.id} (${note.scope})`),
48
48
  ];
49
49
  }
@@ -109,7 +109,7 @@ export function renderAdvisoriesMarkdown(findings, opts, suppressed = [], tips =
109
109
  // This is a generated, gitignored artifact — not authored prose. Advisory
110
110
  // strings (and reproduced config snippets like `.vale.ini`'s `write-good.So =
111
111
  // NO`) legitimately contain sentence-initial "So" and slop tokens. The shipped
112
- // `lint:prose` globs on-disk `.agents/*.md`, so without this whole-file Vale
112
+ // `bkit:lint:prose` globs on-disk `.agents/*.md`, so without this whole-file Vale
113
113
  // skip the husky hooks fail on a file the consumer cannot edit.
114
114
  lines.push("<!-- vale off -->");
115
115
  lines.push("");
@@ -243,7 +243,7 @@ export function readChangelogVersionDelta(version) {
243
243
  * cwd defaults to process.cwd().
244
244
  *
245
245
  * Pass `suppressed` to collect the advisories a package opted out of via
246
- * `bkit.ignoreAdvisories` (one note per id + owning package); the caller renders them with
246
+ * `bkit.advisories.ignore` (one note per id + owning package); the caller renders them with
247
247
  * `suppressedNoteLines` so a dismissal stays visible. Omitted by callers that do not render.
248
248
  */
249
249
  export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), suppressed) {
@@ -265,11 +265,11 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
265
265
  const ghMcpToken = detectGhMcpToken(cwd);
266
266
  if (ghMcpToken)
267
267
  phase3.push(ghMcpToken);
268
- // Main branch protection — bkit's PR-base gates (build Step 17, ship Step 2)
268
+ // Main branch protection — bkit's PR-base gates (build Step 16, ship Step 2)
269
269
  // assert feat/* PRs target dev. Enforcing it at the GitHub layer needs branch
270
270
  // protection on main restricting merges to PRs from dev.
271
271
  const protectionStatus = detectMainBranchProtection();
272
- const scriptHint = "\n\nQuick path: run `bkit setup protect-main --dry-run` to preview the policy, then drop `--dry-run` to apply. It requires the CI capstone job named by `package.json` `bkit.capstoneJob` (default `bkit-tests-check`, so the required check means 'validated', not just 'tests job did not fail') and pre-flights that the job exists in the `bkit.ciWorkflow` file before requiring it.";
272
+ const scriptHint = "\n\nQuick path: run `bkit setup protect-main --dry-run` to preview the policy, then drop `--dry-run` to apply. It requires the CI capstone job named by `package.json` `bkit.testing.ciCapstone` (default `bkit-tests-check`, so the required check means 'validated', not just 'tests job did not fail') and pre-flights that the job exists in the `bkit.testing.ciWorkflow` file before requiring it.";
273
273
  if (protectionStatus === "missing") {
274
274
  phase3.push({
275
275
  id: "main-branch-protection-missing",
@@ -278,7 +278,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
278
278
  action: "main only ever moves via a release PR (release/* -> main); bkit's build/ship workflows keep all feat/* PRs on dev. Gate main at the GitHub layer:\n\n" +
279
279
  " Settings → Branches → Add rule → Branch name pattern: main\n" +
280
280
  " - Require a pull request before merging\n" +
281
- " - Require status checks: bkit-tests-check (the always-on capstone — required-check green then means 'the planned tiers ran', not just 'nothing failed'; do NOT require bkit-tests-scope, it is always green)\n" +
281
+ ` - Require status checks: ${readBkitConfig(cwd).capstoneJob} (the always-on capstone — required-check green then means 'the planned tiers ran', not just 'nothing failed'; do NOT require bkit-tests-scope, it is always green)\n` +
282
282
  " - Do not allow bypassing the above settings (enforce for admins)\n" +
283
283
  " - Require linear history; block force-pushes and deletions\n\n" +
284
284
  "enforce-for-admins is load-bearing: agents act with the owner's admin token, so an admin-bypass exemption means the agent is the bypass. Covering admins is the only way protection actually constrains agents. dev is intentionally left unprotected — operators choose direct-push or feat/PR and own that tests ran." +
@@ -286,7 +286,7 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
286
286
  });
287
287
  }
288
288
  // Optional post-install decisions (opt-in add-ons):
289
- // 1. Issue tracker — branch on bkit.issueTracker.
289
+ // 1. Issue tracker — branch on bkit.tracker.default.
290
290
  // 2. Dependency updater — read-only. Suggests an example template. Never writes config.
291
291
  // 3. Cloud agents — branch on bkit-cloud.yml presence.
292
292
  const trackerSetup = buildTrackerSetupAdvisory(cwd);
@@ -297,6 +297,9 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
297
297
  const githubProjectSetup = buildGithubProjectAdvisory(cwd);
298
298
  if (githubProjectSetup)
299
299
  phase3.push(githubProjectSetup);
300
+ const githubProjectToken = buildGithubProjectTokenScopeAdvisory(cwd);
301
+ if (githubProjectToken)
302
+ phase3.push(githubProjectToken);
300
303
  const depUpdaterSetup = buildDepUpdaterSetupAdvisory(cwd);
301
304
  if (depUpdaterSetup)
302
305
  phase3.push(depUpdaterSetup);
@@ -334,6 +337,10 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
334
337
  const cloudGate = detectBkitCloudYmlAlwaysTrueGate(cwd);
335
338
  if (cloudGate)
336
339
  phase3.push(cloudGate);
340
+ // CI template copies named without the `bkit-` prefix.
341
+ const ciScriptNames = detectCiScriptsOldNames(cwd);
342
+ if (ciScriptNames)
343
+ phase3.push(ciScriptNames);
337
344
  // Self-installed opencode.yml (/oc handler) drifted from the installed opencode provider —
338
345
  // it hardcodes a model + secret that `bkit install --opencode=` does not rewrite. Not for
339
346
  // claude.yml (its @claude handler is provider-fixed). bkit-cloud.yml self-syncs, so exempt.
@@ -372,6 +379,10 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
372
379
  const runLevels = detectRunLevelsNotComposed(cwd);
373
380
  if (runLevels)
374
381
  phase3.push(runLevels);
382
+ // vale missing while bkit:lint:prose runs the prose gate
383
+ const valeMissing = detectValeMissing(cwd);
384
+ if (valeMissing)
385
+ phase3.push(valeMissing);
375
386
  // vale not synced
376
387
  const vale = detectValePackageNotSynced(cwd);
377
388
  if (vale)
@@ -406,6 +417,6 @@ export function runPostInstallCheck(preflightAdvisories, cwd = process.cwd(), su
406
417
  const phase3Ids = new Set(deduped.map((f) => f.id));
407
418
  const filteredPreflight = dedupedPreflight.filter((f) => !phase3Ids.has(f.id));
408
419
  // Final order: preflight advisories (that weren't superseded) first, then Phase 3.
409
- // An advisory a setup tip reuses goes quiet with that tip (`bkit.ignoreAdvisories`).
420
+ // An advisory a setup tip reuses goes quiet with that tip (`bkit.advisories.ignore`).
410
421
  return dropTipSilencedAdvisories([...filteredPreflight, ...deduped], cwd, onSuppressed);
411
422
  }
@@ -1,5 +1,5 @@
1
1
  // checks/after/suppression.ts — per-package advisory opt-out (`package.json`
2
- // `bkit.ignoreAdvisories`).
2
+ // `bkit.advisories.ignore`).
3
3
  //
4
4
  // A detector can be right in general and still fire on a package where the condition is
5
5
  // deliberately not applicable (a rule-linter whose test titles mention `@live`, an
@@ -12,9 +12,9 @@
12
12
  // suppressible whatever the manifest says.
13
13
  import { readPackageJson } from "../../shared/package-json.js";
14
14
  /**
15
- * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` key that is
16
- * absent or not an object, and an `ignoreAdvisories` that is absent or not an array all
17
- * yield no ids — never a throw.
15
+ * Advisory ids `dir/package.json` opts out of. A missing manifest, a `bkit` or
16
+ * `bkit.advisories` key that is absent or not an object, and an `advisories.ignore` that is
17
+ * absent or not an array all yield no ids — never a throw.
18
18
  */
19
19
  export function ignoredAdvisoryIds(dir) {
20
20
  const read = readPackageJson(dir);
@@ -23,7 +23,10 @@ export function ignoredAdvisoryIds(dir) {
23
23
  const bkit = read.pkg.bkit;
24
24
  if (typeof bkit !== "object" || bkit === null || Array.isArray(bkit))
25
25
  return new Set();
26
- const list = bkit.ignoreAdvisories;
26
+ const advisories = bkit.advisories;
27
+ if (typeof advisories !== "object" || advisories === null || Array.isArray(advisories))
28
+ return new Set();
29
+ const list = advisories.ignore;
27
30
  if (!Array.isArray(list))
28
31
  return new Set();
29
32
  return new Set(list.filter((id) => typeof id === "string"));
@@ -3,7 +3,9 @@
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import { spawnSync } from "node:child_process";
6
- import { readBkitConfig } from "../../shared/settings.js";
6
+ import { readPackageJson } from "../../shared/package-json.js";
7
+ import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
8
+ import { DEP_UPDATER_NAMES, findDepUpdaterConfigs, } from "../../shared/dep-updater.js";
7
9
  /** True when `cmd --version` runs (binary on PATH, exits 0). */
8
10
  function toolVersionRuns(cmd) {
9
11
  const res = spawnSync(cmd, ["--version"], {
@@ -12,13 +14,36 @@ function toolVersionRuns(cmd) {
12
14
  });
13
15
  return res.status === 0;
14
16
  }
17
+ /**
18
+ * Detect a prose gate that cannot run here: package.json `bkit:lint:prose` calls `bkit ci prose`,
19
+ * which fails without vale, and vale is not on PATH. Null when the gate is not adopted.
20
+ */
21
+ export function detectValeMissing(cwd) {
22
+ const read = readPackageJson(cwd);
23
+ if (!read.ok)
24
+ return null;
25
+ const scripts = read.pkg["scripts"];
26
+ const lintProse = typeof scripts === "object" && scripts !== null
27
+ ? scripts["bkit:lint:prose"]
28
+ : undefined;
29
+ if (typeof lintProse !== "string" || !lintProse.includes("bkit ci prose"))
30
+ return null;
31
+ if (toolVersionRuns("vale"))
32
+ return null;
33
+ return {
34
+ id: "vale-not-installed",
35
+ severity: "advisory",
36
+ detect: "package.json `bkit:lint:prose` runs `bkit ci prose`, but vale is not on PATH — the prose gate fails, so every pre-push gate that runs `bkit:lint:prose` fails on this machine.",
37
+ action: "Install vale, then download its styles:\n\n brew install vale # macOS; other platforms: https://vale.sh/docs/install\n vale sync\n\nCI and the cloud templates install vale already; this is for local machines.",
38
+ };
39
+ }
15
40
  /**
16
41
  * Detect whether vale is installed but write-good styles are not synced.
17
- * Returns null if vale is not on PATH (silent skip — not an error).
42
+ * Returns null if vale is not on PATH (`detectValeMissing` covers that case).
18
43
  */
19
44
  export function detectValePackageNotSynced(cwd) {
20
45
  if (!toolVersionRuns("vale"))
21
- return null; // vale not on PATH — silent skip
46
+ return null; // vale not on PATH — detectValeMissing
22
47
  if (fs.existsSync(path.join(cwd, ".vale", "styles", "write-good")))
23
48
  return null;
24
49
  // `vale sync` reads `Packages` from .vale.ini; without one it has nothing to download.
@@ -27,14 +52,14 @@ export function detectValePackageNotSynced(cwd) {
27
52
  id: "vale-package-not-synced",
28
53
  severity: "advisory",
29
54
  detect: "vale is on PATH but the repo has no .vale.ini and .vale/styles/write-good/ is absent — prose linting does not run.",
30
- action: "Adopt bkit's Vale template first: copy .bkit/templates/.vale.ini to .vale.ini and .bkit/templates/.vale/styles/House/*.yml to .vale/styles/House/. Then run `vale sync` (one-time per repo) to download the write-good package the copied .vale.ini names. `vale sync` reads its package list from .vale.ini, so it cannot fetch write-good before that file exists.",
55
+ action: "Adopt bkit's Vale template first: copy .bkit/templates/.vale.ini to .vale.ini and .bkit/templates/.vale/styles/Bkit/*.yml to .vale/styles/Bkit/. Then run `vale sync` (one-time per repo) to download the write-good package the copied .vale.ini names. `vale sync` reads its package list from .vale.ini, so it cannot fetch write-good before that file exists.",
31
56
  };
32
57
  }
33
58
  return {
34
59
  id: "vale-package-not-synced",
35
60
  severity: "advisory",
36
61
  detect: "vale is on PATH but .vale/styles/write-good/ is absent — vale packages not synced.",
37
- action: "Run `vale sync` (one-time per repo) to download the write-good package. lint:prose tries to self-heal this (copy from the main worktree, then `vale sync`) and warns loudly on stderr if it cannot — but until the package is present, prose linting does not run.",
62
+ action: "Run `vale sync` (one-time per repo) to download the write-good package. bkit:lint:prose tries to self-heal this (copy from the main worktree, then `vale sync`) and fails if it cannot.",
38
63
  };
39
64
  }
40
65
  /**
@@ -65,52 +90,38 @@ export function detectWorkflowLintToolsMissing(cwd) {
65
90
  const BKIT_STUBS = [
66
91
  {
67
92
  id: "auto-force-e2e",
68
- file: ".github/workflows/bkit-ci.yml",
69
93
  description: "Auto-trigger E2E on PRs whose diff touches sensitive paths (auth, migrations, payment, api, server).",
70
94
  },
71
95
  {
72
96
  id: "migrations-immutable",
73
- file: ".github/workflows/bkit-ci.yml",
74
97
  description: "Fail PRs that modify supabase/migrations/* files already present on the base branch — enforces migration immutability after merge.",
75
98
  },
76
99
  {
77
100
  id: "test-presence",
78
- file: ".github/workflows/bkit-ci.yml",
79
101
  description: "Warn when a workspace package declares a `test` script but contains zero `*.test.ts(x)` / `*.spec.ts(x)` files (guards against accidental deletion).",
80
102
  },
81
103
  {
82
104
  id: "supabase-migrate",
83
- file: ".github/workflows/bkit-ci.yml",
84
105
  description: "REMOTE `db push` belongs in `bkit-tests-migration`, not in the monolithic tests job and not in `bkit-tests-e2e-web`. Prefer the migration-lane stub (always-on; replay plan-/path-gated; push on every push to dev/main; e2e/live `needs:` it). Legacy single-job shape still documented under this stub for repos without a migration lane yet — migrate into bkit-tests-migration ASAP. Requires the host access token + project ref (e.g. SUPABASE_ACCESS_TOKEN, or the host's env pull).",
85
106
  },
86
107
  {
87
108
  id: "test-db",
88
- file: ".github/workflows/bkit-ci.yml",
89
109
  description: "Assert schema-invariant DB checks (e.g. 'every public table has RLS enabled', no hardcoded table list) so they aren't app-defined. Two co-equal routes — pick by deploy topology, not by whether you can run pgTAP locally: (1) pgTAP (`supabase db test` over `supabase/tests/*.sql`) against a CI-local fixture built from `supabase/migrations` — fast, hermetic, offline, but the fixture can differ from prod, so it can stay green while prod RLS is broken; best when there is no deploy/`@live` tier, or for pure-logic DB unit tests. (2) a `@live` catalog-RPC (SECURITY DEFINER, service_role-only, called over REST; direct port-5432 from CI runners is IPv4-flaky) that validates the real deployed schema in `bkit-tests-live-web` — the recommended default once you have a deploy + `@live` tier (RLS/tenancy especially: a passing local-fixture check is not evidence that prod is locked down). See docs/testing.md § Schema-invariant DB checks.",
90
110
  },
91
111
  {
92
112
  id: "vercel-await",
93
- file: ".github/workflows/bkit-ci.yml",
94
113
  description: "Poll the Vercel API for the PR's preview deployment by commit SHA and export `target_url` for E2E. Requires VERCEL_TOKEN, VERCEL_TEAM_ID, VERCEL_PROJECT_ID secrets.",
95
114
  },
96
115
  {
97
116
  id: "e2e",
98
- file: ".github/workflows/bkit-ci.yml",
99
117
  description: "Run `pnpm test:e2e` gated on `should_run_full` (the `[force full]` commit/PR tag) or `needs_e2e` (auto-force-e2e). Pairs with vercel-await for PR-time runs against the preview deployment.",
100
118
  },
101
- {
102
- id: "smoke",
103
- file: ".github/workflows/bkit-ci.yml",
104
- description: "Post-CI smoke test triggered by `workflow_run` after main-CI succeeds. Cannot share a file with push/pull_request triggers — copy the commented YAML to a new `.github/workflows/smoke.yml` file.",
105
- },
106
119
  {
107
120
  id: "coverage",
108
- file: ".github/workflows/bkit-ci.yml",
109
121
  description: "Report vitest coverage on PRs and in every run's job summary via davelosert/vitest-coverage-report-action (free, runs inside Actions with GITHUB_TOKEN — no third-party service, safe for private repos). PER-TIER: unit and integration are measured and commented SEPARATELY (a single merged number lets integration mask a hollow unit suite — coverage is a union). Report-only by default: nothing fails the build until a threshold is set. Enabling (documented in the stub header): (1) add `@vitest/coverage-v8` (pinned to your vitest major) plus a vitest.config coverage block with `reporter: ['text','json-summary','json']` and `reportOnFailure: true` — json-summary + json are load-bearing (the action reads coverage-summary.json and coverage-final.json); (2) run coverage TWICE into separate dirs — unit → coverage/unit (exclude integration files), integration → coverage/integration — so each tier gets its own honest number (avoids the last-writer-wins clobber a second same-dir run would cause); (3) add a JOB-LEVEL permissions block to bkit-tests-unit with `contents: read` + `pull-requests: write` — job-level REPLACES the workflow-level block (not additive), so omitting `contents: read` breaks the checkout; (4) two report steps with distinct `name:` (unit / integration) pointing at each dir's coverage-summary.json + coverage-final.json; the unit step runs on every event (`if: !cancelled()` plus a `hashFiles` guard on its summary), sets `vite-config-path: vitest.unit.config.ts` so the job summary and PR comment show the floor as the target, and comments only on same-repo PRs (`comment-on: pr`, else `none`). SEPARATE LANES (one job per tier): put the integration run + report + its OWN pull-requests: write block in bkit-tests-integration, not bkit-tests-unit — each lane posts its own comment. Thresholds are opt-in and PER TIER: UNIT is the gate — put `coverage.thresholds.branches` in a `vitest.unit.config.ts` (`mergeConfig` over vitest.config) that ONLY the unit run loads via `-c` (vitest coverage is per-RUN/root config, NOT per-project — `projects` does not scope it and a `thresholds` block in vitest.config reds BOTH runs; the report action reads the same file as raw text, so keep the floor on one unquoted `branches: <n>` line and no other metric name + colon + number in it; branches is the meaningful floor, set to current and ratchet up). INTEGRATION is REPORT-ONLY — gate it on EXECUTION (the capstone's integration_ran > 0), not a %: a whole-repo integration % is denominator-noise (it covers boundaries/flows, not pure logic). For a real integration %, add `--coverage.include=src/server/**` on the integration run (same CLI-flag idiom as --exclude) then set a floor, or ratchet from current — never a picked number. Fork PRs: GITHUB_TOKEN is read-only, so the unit step sets `comment-on: none` there (its job summary still lands) and the integration step keeps the `head.repo == repo` guard (or use the action's workflow_run two-workflow pattern). Guard the integration report on `hashFiles('coverage/integration/coverage-summary.json') != ''` so a repo with no integration tier skips it cleanly.",
110
122
  },
111
123
  {
112
124
  id: "e2e-coverage",
113
- file: ".github/workflows/bkit-ci.yml",
114
125
  description: "Report Playwright E2E code-coverage on PRs — the third coverage tier, sibling of `coverage` (unit/integration). Free, entirely inside Actions with GITHUB_TOKEN (no third-party service, private-repo safe). Report-only by default. Unlike vitest there is NO --coverage flag: Playwright is black-box and does not instrument your source, so enabling is a 3-part pipeline documented in the stub header: (1) COLLECT during the E2E run — either an Istanbul instrumented build (`vite-plugin-istanbul` → window.__coverage__, cross-browser, scraped in a Playwright fixture) or the V8 API (`page.coverage`, Chromium-only, needs source maps); (2) REPORT with Monocart (`monocart-coverage-reports`, via the `monocart-reporter` Playwright reporter) which ingests EITHER V8 or Istanbul input and emits Istanbul-format coverage/e2e/coverage-summary.json + coverage-final.json — the SAME two files davelosert reads, so no new commenter is needed; (3) COMMENT by reusing davelosert/vitest-coverage-report-action@v2 pointed at coverage/e2e with a DISTINCT `name: e2e` so its sticky comment does not collide with the unit/integration ones. This step posts from the bkit-tests-e2e-web lane (or, with the combined starter, the bkit-tests-unit job as `coverage`), and needs that lane's job-level permissions block (pull-requests: write + actions: read + contents: read) or the comment cannot post. Ship NO threshold: a whole-app E2E % is denominator-noise (E2E exercises flows, not every branch) — gate the tier on the E2E step succeeding, not a %; for a real E2E % scope Monocart's entryFilter/sourceFilter then ratchet from current. The head.repo == repo guard skips fork PRs (read-only GITHUB_TOKEN); the hashFiles('coverage/e2e/coverage-summary.json') guard skips repos with no E2E coverage. See docs/testing.md § E2E coverage on PRs.",
115
126
  },
116
127
  // --- The 4-job "green == validated" scaffold. ---
@@ -118,111 +129,81 @@ const BKIT_STUBS = [
118
129
  // template bkit-ci.yml. Order matters when adopting — see that block.
119
130
  {
120
131
  id: "bkit-tests-scope",
121
- file: ".github/workflows/bkit-ci.yml",
122
132
  description: "Promote run-level detection into a standalone always-on `bkit-tests-scope` job that emits ONE bkit-test-plan JSON (run_level / web_affected / run_e2e / run_live / run_migration), consumed by every tier via `fromJSON(needs.bkit-tests-scope.outputs.plan).<field>`. `run_migration` (#385) gates migration-lane HEAVY replay steps only — the migration job itself stays always-on so e2e/live can `needs:` it. This is the foundation of the scaffold that makes 'CI green' mean 'the planned tests actually ran'. The FULL CI SCAFFOLD REFERENCE (JOB 1) in `.bkit/templates/.github/workflows/bkit-ci.yml` lays the job out step by step (a single-package repo drops the [M] steps; the plan then comes from the commit markers and the event alone); `.bkit/templates.md` § CI workflow covers the `bkit-tests-check` capstone it feeds. Add the planner to the capstone's `needs:` and gate each lane on `run_level != 'none'`. NAME: keep it inside the bkit-tests-* namespace so bkit's CI-Dispatch Gate (which polls for any bkit-tests-* check on the pushed HEAD) can see it. NAMESPACE TRAP: it is the PLANNER, not a test lane — any capstone/guard that treats every bkit-tests-* job as a lane must exempt it BY NAME and assert its result explicitly, or a scope failure goes unasserted and the capstone stays green.",
123
133
  },
124
134
  {
125
135
  id: "affected-graph",
126
- file: ".github/workflows/bkit-ci.yml",
127
136
  description: "Inside bkit-tests-scope, replace any frozen path-allowlist with `turbo query affected --packages` so run_level / web_affected track the real dependency blast radius. Monorepo-only — drop for single-package repos. Capture turbo stdout/stderr SEPARATELY: `2>&1` merges turbo's banner into the JSON and jq silently falls back to [] (a ghost-green run).",
128
137
  },
129
138
  {
130
139
  id: "bkit-tests-live-web",
131
- file: ".github/workflows/bkit-ci.yml",
132
140
  description: "Add push-only `bkit-tests-live-web` running the @live tier against the deployed URL. Omit the job if you have no deploy. needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-web], each with result != 'failure' except scope (success) and the lane's own run_live gate. Do NOT also needs: 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.",
133
141
  },
134
142
  {
135
143
  id: "bkit-tests-migration",
136
- file: ".github/workflows/bkit-ci.yml",
137
144
  description: "Add always-on `bkit-tests-migration` (#385): (1) prove every migration replays from an EMPTY database (+ seed) on a fresh ephemeral instance; (2) on every push to `dev`/`main`, `db push --linked --include-all` to the shared remote (NOT inside e2e — that races @live). NO job-level `if:` — e2e/live `needs:` this lane; a skip cascades. Gate HEAVY replay steps via `plan.run_migration` (preferred) or an in-job Detect step. Remote push is un-gated by `run_migration` (self-heal) and runs AFTER replay so from-empty failure never reaches remote. Capstone asserts `result == success` whenever scope succeeded. Supply stack reset+seed (Supabase: `db reset --local`; Prisma: `migrate reset`; Drizzle/raw: replay + seed). Fold into bkit-tests-check `needs:` — NOT in series before static/unit (they share no state).",
138
145
  },
139
146
  {
140
147
  id: "bkit-tests-integration",
141
- file: ".github/workflows/bkit-ci.yml",
142
148
  description: "Add the integration tier as its OWN parallel lane (job) — `bkit-tests-integration`, NOT a step in bkit-tests-unit. WHEN: you have *.integration.test.ts (multi-module wiring / real infra boundaries). Separate lanes give each tier its own honest coverage number, executed-count, and permissions. Wiring: needs:[bkit-tests-scope]; if run_level != 'none'; self-contained (own checkout/setup/install); gate the heavy steps on web_affected; emit `integration_ran` (vitest --reporter=json) so bkit-tests-check can assert it ran > 0. The bkit-stub:coverage integration report (davelosert, name: integration, report-only) posts from THIS lane with its own job-level `pull-requests: write`. Fold the lane into bkit-tests-check's `needs:`.",
143
149
  },
144
150
  {
145
151
  id: "bkit-tests-e2e-web",
146
- file: ".github/workflows/bkit-ci.yml",
147
152
  description: "Add browser E2E as its own lane — `bkit-tests-e2e-web` (e.g. Playwright). WHEN: you have a browser suite and a deploy or a local stack to hit. needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-web], migration/reset/build result != 'failure'. A feature→dev PR hits a local stack with this PR's migrations; every other event hits the deployment. Same outcome rules everywhere; a pass on retry is a failure; target from TEST_URL alone. Emit e2e_ran. Fold into bkit-tests-check's needs:. DROP if you have no browser E2E.",
148
153
  },
149
154
  {
150
155
  id: "bkit-tests-build-web",
151
- file: ".github/workflows/bkit-ci.yml",
152
156
  description: "Add `bkit-tests-build-web`. WHEN: a later lane tests this commit's deployment, or a compile break should report on its own. Either compile the workspace, or create the host deployment and publish deployment_url + deployment_id un-promoted (e.g. Vercel). needs:[bkit-tests-scope]. Emits no *_ran count. Fold into bkit-tests-check's needs:.",
153
157
  },
154
158
  {
155
159
  id: "bkit-tests-reset",
156
- file: ".github/workflows/bkit-ci.yml",
157
160
  description: "Add `bkit-tests-reset`. WHEN: two or more lanes use ONE long-lived resource (demo tenant, seeded account). Runs after scope + migration, takes a lease, and puts the resource in its known state BEFORE those lanes start. needs: [bkit-tests-scope, bkit-tests-migration]; if tenant_target != ''. Pair with bkit-tests-cleanup. DROP both when the resource is provisioned fresh per run.",
158
161
  },
159
162
  {
160
163
  id: "bkit-tests-cleanup",
161
- file: ".github/workflows/bkit-ci.yml",
162
164
  description: "Add `bkit-tests-cleanup`, the other half of bkit-tests-reset. Runs last, if: always(), after every lane that used the shared resource. Puts it back and releases the lease, including when a lane failed or the run was cancelled. Capstone reds if a planned reset skipped or cleanup failed.",
163
165
  },
164
166
  {
165
167
  id: "bkit-tests-build-ios",
166
- file: ".github/workflows/bkit-ci.yml",
167
168
  description: "Add `bkit-tests-build-ios`. WHEN: you ship an iOS app. Same rule on a PR, a push, and a dispatch — not a post-merge canary. needs:[bkit-tests-scope]; if: plan.run_native_ios. Pair with bkit-tests-e2e-ios. DROP if you have no iOS app. e.g. a hosted device-build service.",
168
169
  },
169
170
  {
170
171
  id: "bkit-tests-e2e-ios",
171
- file: ".github/workflows/bkit-ci.yml",
172
172
  description: "Add `bkit-tests-e2e-ios`. needs: [bkit-tests-scope, bkit-tests-migration, bkit-tests-reset, bkit-tests-build-ios, bkit-tests-build-web]. The if: must name each needs.result because !cancelled() disables GitHub's skip-on-failed-needs. Emit native_e2e_ran. Fold into bkit-tests-check. DROP if you have no iOS app.",
173
173
  },
174
174
  {
175
175
  id: "bkit-tests-build-android",
176
- file: ".github/workflows/bkit-ci.yml",
177
176
  description: "Add `bkit-tests-build-android`. Same contract as bkit-tests-build-ios, android tokens. DROP if you have no Android app.",
178
177
  },
179
178
  {
180
179
  id: "bkit-tests-e2e-android",
181
- file: ".github/workflows/bkit-ci.yml",
182
180
  description: "Add `bkit-tests-e2e-android`. Same contract as bkit-tests-e2e-ios, android tokens. DROP if you have no Android app.",
183
181
  },
184
182
  {
185
183
  id: "logging-probe",
186
- file: ".github/workflows/bkit-ci.yml",
187
184
  description: "Inside each runtime lane (bkit-tests-e2e-web, bkit-tests-live-web, bkit-tests-e2e-ios, bkit-tests-e2e-android), emit one marked event and ask the error tracker whether it arrived. e.g. Sentry. Skip when that lane did not run the probe. A missing marker reds the lane. DROP if you have no error tracker. This is a step, not a job.",
188
185
  },
189
186
  {
190
187
  id: "bkit-tests-deploy",
191
- file: ".github/workflows/bkit-ci.yml",
192
188
  description: "Add `bkit-tests-deploy`. needs: [bkit-tests-check, bkit-tests-build-web]. Push to the default branch only. Not a required check. Promotes the exact deployment_id the build lane published. A red job means the previous deployment stays live. The host must not auto-build the default branch, and any hold-promotion-until-check setting stays empty.",
193
189
  },
194
190
  {
195
191
  id: "health",
196
- file: ".github/workflows/bkit-ci.yml",
197
- description: "Copy the commented workflow to .github/workflows/health.yml. workflow_run after CI succeeds on the default branch; smoke the deployment this SHA promoted. Not a required check. DROP if you have no deployed health URL.",
192
+ description: "Copy .bkit/templates/.github/workflows/bkit-health.yml to .github/workflows/bkit-health.yml, then replace {{DEFAULT_BRANCH}} and {{PRODUCTION_URL}} and swap the Vercel lookup for your host's API. It runs after every finished CI run on the default branch, green or red, probes production only when production serves that run's commit, and fails when it cannot tell. Not a required check. DROP if you have no deployed health URL.",
198
193
  },
199
194
  ];
200
195
  export function detectBkitStubs(cwd) {
201
196
  const findings = [];
202
- // Cache file reads so repeated scans of the same file are O(1).
203
- const fileCache = new Map();
204
- const readOnce = (file) => {
205
- if (fileCache.has(file))
206
- return fileCache.get(file) ?? null;
207
- const abs = path.join(cwd, file);
208
- try {
209
- const content = fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
210
- fileCache.set(file, content);
211
- return content;
212
- }
213
- catch {
214
- fileCache.set(file, null);
215
- return null;
216
- }
217
- };
197
+ const ciRel = ciWorkflowPath(cwd);
198
+ const ciPath = path.join(cwd, ciRel);
199
+ if (!fs.existsSync(ciPath))
200
+ return findings;
201
+ const content = fs.readFileSync(ciPath, "utf-8");
218
202
  // Track which stubs are still commented (sentinel present) so the pair-conflict
219
203
  // pass below can compare against per-stub "enabled" markers (the named YAML step
220
204
  // appearing uncommented).
221
205
  const stubSentinelPresent = new Set();
222
206
  for (const stub of BKIT_STUBS) {
223
- const content = readOnce(stub.file);
224
- if (content === null)
225
- continue;
226
207
  // Sentinel is the full HEADER form — `# bkit-stub:<id> — <description>` — the line the
227
208
  // advisory tells you to delete. Prose back-references ("the bkit-stub:coverage integration
228
209
  // report posts from HERE") do not match, and `# bkit-stub:e2e —` cannot match stub
@@ -235,9 +216,9 @@ export function detectBkitStubs(cwd) {
235
216
  findings.push({
236
217
  id: `bkit-stub-${stub.id}`,
237
218
  severity: "advisory",
238
- detect: `${stub.file} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
219
+ detect: `${ciRel} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
239
220
  action: `${stub.description}\n\n` +
240
- `Before enabling a CI lane, read docs/testing.md § CI test tiers and docs/deployments.md (one run per branch, push base, promote after the capstone). The FULL CI SCAFFOLD REFERENCE in bkit-ci.yml is the job graph: needs, if, step names. Write the job from that graph and from those docs. Uncomment only a block that is already commented YAML or shell.\n\n` +
221
+ `Before enabling a CI lane, read docs/testing.md § CI test tiers and docs/deployments.md (one run per branch, push base, promote after the capstone). The FULL CI SCAFFOLD REFERENCE in ${ciRel} is the job graph: needs, if, step names. Write the job from that graph and from those docs. Uncomment only a block that is already commented YAML or shell.\n\n` +
241
222
  `Decide with the user: (a) enable — uncomment the YAML/shell block AND delete the \`# bkit-stub:${stub.id} — ...\` header line; (b) customise — adjust paths/secrets/conditions before uncommenting; (c) dismiss — delete the entire stub block (header + commented body).\n\n` +
242
223
  `Until the sentinel is removed, this advisory fires every install / check.`,
243
224
  });
@@ -246,39 +227,36 @@ export function detectBkitStubs(cwd) {
246
227
  // produces a silent fallback. Detection signal: the named uncommented YAML step
247
228
  // appears (sentinel removed → likely enabled), and the paired stub's sentinel
248
229
  // is still present (still disabled).
249
- const ciContent = readOnce(".github/workflows/bkit-ci.yml");
250
- if (ciContent) {
251
- // Match a YAML step name uncommented (leading `- name:` not preceded by `#`).
252
- const isStepEnabled = (stepName) => {
253
- const re = new RegExp(`(^|\\n)\\s*- name:\\s*${stepName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
254
- return re.test(ciContent);
255
- };
256
- const e2eEnabled = isStepEnabled("Run E2E Tests");
257
- const vercelEnabled = isStepEnabled("Await Vercel Preview");
258
- if (vercelEnabled && stubSentinelPresent.has("e2e")) {
259
- findings.push({
260
- id: "bkit-stub-pair-vercel-without-e2e",
261
- severity: "advisory",
262
- detect: ".github/workflows/bkit-ci.yml has `Await Vercel Preview` enabled but `Run E2E Tests` is still commented (bkit-stub:e2e sentinel present).",
263
- action: "Either enable the `bkit-stub:e2e` block so the E2E step consumes `steps.vercel.outputs.target_url`, or remove the Vercel-await step — exporting `target_url` with no consumer wastes ~10 minutes of CI per PR.",
264
- });
265
- }
266
- if (e2eEnabled && stubSentinelPresent.has("vercel-await")) {
267
- findings.push({
268
- id: "bkit-stub-pair-e2e-without-vercel",
269
- severity: "advisory",
270
- detect: ".github/workflows/bkit-ci.yml has `Run E2E Tests` enabled but `Await Vercel Preview` is still commented (bkit-stub:vercel-await sentinel present).",
271
- action: "Enable the `bkit-stub:vercel-await` block so the E2E step's `TARGET_URL` resolves to the PR's Vercel preview deployment. Without it, `TARGET_URL` falls back to `http://localhost:3000` and the E2E run hits an empty origin.",
272
- });
273
- }
274
- if (e2eEnabled && stubSentinelPresent.has("auto-force-e2e")) {
275
- findings.push({
276
- id: "bkit-stub-pair-e2e-without-auto-force",
277
- severity: "advisory",
278
- detect: ".github/workflows/bkit-ci.yml has `Run E2E Tests` enabled but `bkit-stub:auto-force-e2e` is still commented.",
279
- action: "E2E now requires `[force full]` in the commit/PR title on every run. Enable `bkit-stub:auto-force-e2e` to auto-trigger for PRs touching sensitive paths (auth, migrations, payment, api, server) without the manual tag.",
280
- });
281
- }
230
+ // Match a YAML step name uncommented (leading `- name:` not preceded by `#`).
231
+ const isStepEnabled = (stepName) => {
232
+ const re = new RegExp(`(^|\\n)\\s*- name:\\s*${stepName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
233
+ return re.test(content);
234
+ };
235
+ const e2eEnabled = isStepEnabled("Run E2E Tests");
236
+ const vercelEnabled = isStepEnabled("Await Vercel Preview");
237
+ if (vercelEnabled && stubSentinelPresent.has("e2e")) {
238
+ findings.push({
239
+ id: "bkit-stub-pair-vercel-without-e2e",
240
+ severity: "advisory",
241
+ detect: `${ciRel} has \`Await Vercel Preview\` enabled but \`Run E2E Tests\` is still commented (bkit-stub:e2e sentinel present).`,
242
+ action: "Either enable the `bkit-stub:e2e` block so the E2E step consumes `steps.vercel.outputs.target_url`, or remove the Vercel-await step — exporting `target_url` with no consumer wastes ~10 minutes of CI per PR.",
243
+ });
244
+ }
245
+ if (e2eEnabled && stubSentinelPresent.has("vercel-await")) {
246
+ findings.push({
247
+ id: "bkit-stub-pair-e2e-without-vercel",
248
+ severity: "advisory",
249
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`Await Vercel Preview\` is still commented (bkit-stub:vercel-await sentinel present).`,
250
+ action: "Enable the `bkit-stub:vercel-await` block so the E2E step's `TARGET_URL` resolves to the PR's Vercel preview deployment. Without it, `TARGET_URL` falls back to `http://localhost:3000` and the E2E run hits an empty origin.",
251
+ });
252
+ }
253
+ if (e2eEnabled && stubSentinelPresent.has("auto-force-e2e")) {
254
+ findings.push({
255
+ id: "bkit-stub-pair-e2e-without-auto-force",
256
+ severity: "advisory",
257
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`bkit-stub:auto-force-e2e\` is still commented.`,
258
+ action: "E2E now requires `[force full]` in the commit/PR title on every run. Enable `bkit-stub:auto-force-e2e` to auto-trigger for PRs touching sensitive paths (auth, migrations, payment, api, server) without the manual tag.",
259
+ });
282
260
  }
283
261
  return findings;
284
262
  }
@@ -287,32 +265,23 @@ const UPDATER_EXAMPLE_PATHS = [
287
265
  ".bkit/templates/.github/workflows/bkit-renovate.yml",
288
266
  ".bkit/templates/.github/dependabot.yml",
289
267
  ].join("\n ");
290
- function updaterConfigPaths(cwd) {
291
- const renovateJson5 = path.join(cwd, ".github", "renovate.json5");
292
- const renovateJson = path.join(cwd, ".github", "renovate.json");
293
- const dependabotYml = path.join(cwd, ".github", "dependabot.yml");
294
- const dependabotYaml = path.join(cwd, ".github", "dependabot.yaml");
295
- const renovate = fs.existsSync(renovateJson5)
296
- ? renovateJson5
297
- : fs.existsSync(renovateJson)
298
- ? renovateJson
299
- : null;
300
- const dependabot = fs.existsSync(dependabotYml)
301
- ? dependabotYml
302
- : fs.existsSync(dependabotYaml)
303
- ? dependabotYaml
304
- : null;
305
- return { renovate, dependabot };
306
- }
268
+ const UPDATER_EXAMPLE = {
269
+ renovate: ".bkit/templates/.github/renovate.json5",
270
+ dependabot: ".bkit/templates/.github/dependabot.yml",
271
+ };
307
272
  /**
308
- * Read-only dependency-updater check.
273
+ * Read-only dependency-updater check: `bkit.dependencies.updater` against the configs present.
309
274
  *
310
275
  * - Both Renovate and Dependabot configs → they open competing PRs.
311
- * - No updater config, workflows exist, and the opt-out is unset → point
276
+ * - One config, and the setting does not name it → blocker.
277
+ * - The setting names an updater whose config is absent → blocker.
278
+ * - No updater config, workflows exist, and the setting is unset → point
312
279
  * at the example templates.
313
280
  */
314
281
  export function buildDepUpdaterSetupAdvisory(cwd) {
315
- const { renovate, dependabot } = updaterConfigPaths(cwd);
282
+ const configs = findDepUpdaterConfigs(cwd);
283
+ const { renovate, dependabot } = configs;
284
+ const setting = readBkitConfig(cwd).depUpdater;
316
285
  if (renovate && dependabot) {
317
286
  return {
318
287
  id: "dep-updater-both",
@@ -321,9 +290,37 @@ export function buildDepUpdaterSetupAdvisory(cwd) {
321
290
  action: "Keep one. Delete the config you are not using, and turn off that bot in the host UI.",
322
291
  };
323
292
  }
324
- if (renovate || dependabot)
325
- return null;
326
- if (readBkitConfig(cwd).depUpdaterOptOut)
293
+ const found = renovate ? "renovate" : dependabot ? "dependabot" : null;
294
+ if (found) {
295
+ if (setting === found)
296
+ return null;
297
+ const name = DEP_UPDATER_NAMES[found];
298
+ const file = configs[found];
299
+ if (setting === null) {
300
+ return {
301
+ id: "dep-updater-unset",
302
+ severity: "blocker",
303
+ detect: `${name} config found (\`${file}\`), but \`bkit.dependencies.updater\` is not \`"${found}"\`.`,
304
+ action: `Set \`bkit.dependencies.updater\` to \`"${found}"\` in package.json. \`bkit upgrade\` sets it when the field is empty.`,
305
+ };
306
+ }
307
+ return {
308
+ id: "dep-updater-mismatch",
309
+ severity: "blocker",
310
+ detect: `\`bkit.dependencies.updater\` is \`"${setting}"\`, but the repo has a ${name} config (\`${file}\`).`,
311
+ action: `Set \`bkit.dependencies.updater\` to \`"${found}"\` in package.json, or delete \`${file}\` and turn ${name} off in the host UI.`,
312
+ };
313
+ }
314
+ if (setting === "renovate" || setting === "dependabot") {
315
+ const name = DEP_UPDATER_NAMES[setting];
316
+ return {
317
+ id: "dep-updater-mismatch",
318
+ severity: "blocker",
319
+ detect: `\`bkit.dependencies.updater\` is \`"${setting}"\`, but no ${name} config was found, so nothing bumps dependencies.`,
320
+ action: `Copy \`${UPDATER_EXAMPLE[setting]}\` into place and own it, or set \`bkit.dependencies.updater\` to the updater you run, or \`"none"\`. See .bkit/templates.md.`,
321
+ };
322
+ }
323
+ if (setting === "none")
327
324
  return null;
328
325
  if (!fs.existsSync(path.join(cwd, ".github", "workflows")))
329
326
  return null;
@@ -333,6 +330,6 @@ export function buildDepUpdaterSetupAdvisory(cwd) {
333
330
  detect: "No dependency updater config. SHA-pinned actions and package bumps will not refresh on their own.",
334
331
  action: "Copy one example and own it:\n\n" +
335
332
  ` ${UPDATER_EXAMPLE_PATHS}\n\n` +
336
- 'Use one updater, not both. To silence this advisory, set `bkit.depUpdater` to `"none"` in package.json. See .bkit/templates.md.',
333
+ 'Use one updater, not both, and set `bkit.dependencies.updater` to its name (`"renovate"` or `"dependabot"`) in package.json. To silence this advisory, set it to `"none"`. See .bkit/templates.md.',
337
334
  };
338
335
  }