@cbartens/bkit 5.5.1 → 6.0.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 (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -3,7 +3,7 @@
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 { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
7
7
  /** True when `cmd --version` runs (binary on PATH, exits 0). */
8
8
  function toolVersionRuns(cmd) {
9
9
  const res = spawnSync(cmd, ["--version"], {
@@ -65,52 +65,42 @@ export function detectWorkflowLintToolsMissing(cwd) {
65
65
  const BKIT_STUBS = [
66
66
  {
67
67
  id: "auto-force-e2e",
68
- file: ".github/workflows/bkit-ci.yml",
69
68
  description: "Auto-trigger E2E on PRs whose diff touches sensitive paths (auth, migrations, payment, api, server).",
70
69
  },
71
70
  {
72
71
  id: "migrations-immutable",
73
- file: ".github/workflows/bkit-ci.yml",
74
72
  description: "Fail PRs that modify supabase/migrations/* files already present on the base branch — enforces migration immutability after merge.",
75
73
  },
76
74
  {
77
75
  id: "test-presence",
78
- file: ".github/workflows/bkit-ci.yml",
79
76
  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
77
  },
81
78
  {
82
79
  id: "supabase-migrate",
83
- file: ".github/workflows/bkit-ci.yml",
84
80
  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
81
  },
86
82
  {
87
83
  id: "test-db",
88
- file: ".github/workflows/bkit-ci.yml",
89
84
  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
85
  },
91
86
  {
92
87
  id: "vercel-await",
93
- file: ".github/workflows/bkit-ci.yml",
94
88
  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
89
  },
96
90
  {
97
91
  id: "e2e",
98
- file: ".github/workflows/bkit-ci.yml",
99
92
  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
93
  },
101
94
  {
102
95
  id: "smoke",
103
- file: ".github/workflows/bkit-ci.yml",
104
96
  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
97
  },
106
98
  {
107
99
  id: "coverage",
108
- file: ".github/workflows/bkit-ci.yml",
109
100
  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
101
  },
111
102
  {
112
103
  id: "e2e-coverage",
113
- file: ".github/workflows/bkit-ci.yml",
114
104
  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
105
  },
116
106
  // --- The 4-job "green == validated" scaffold. ---
@@ -118,111 +108,81 @@ const BKIT_STUBS = [
118
108
  // template bkit-ci.yml. Order matters when adopting — see that block.
119
109
  {
120
110
  id: "bkit-tests-scope",
121
- file: ".github/workflows/bkit-ci.yml",
122
111
  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
112
  },
124
113
  {
125
114
  id: "affected-graph",
126
- file: ".github/workflows/bkit-ci.yml",
127
115
  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
116
  },
129
117
  {
130
118
  id: "bkit-tests-live-web",
131
- file: ".github/workflows/bkit-ci.yml",
132
119
  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
120
  },
134
121
  {
135
122
  id: "bkit-tests-migration",
136
- file: ".github/workflows/bkit-ci.yml",
137
123
  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
124
  },
139
125
  {
140
126
  id: "bkit-tests-integration",
141
- file: ".github/workflows/bkit-ci.yml",
142
127
  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
128
  },
144
129
  {
145
130
  id: "bkit-tests-e2e-web",
146
- file: ".github/workflows/bkit-ci.yml",
147
131
  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
132
  },
149
133
  {
150
134
  id: "bkit-tests-build-web",
151
- file: ".github/workflows/bkit-ci.yml",
152
135
  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
136
  },
154
137
  {
155
138
  id: "bkit-tests-reset",
156
- file: ".github/workflows/bkit-ci.yml",
157
139
  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
140
  },
159
141
  {
160
142
  id: "bkit-tests-cleanup",
161
- file: ".github/workflows/bkit-ci.yml",
162
143
  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
144
  },
164
145
  {
165
146
  id: "bkit-tests-build-ios",
166
- file: ".github/workflows/bkit-ci.yml",
167
147
  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
148
  },
169
149
  {
170
150
  id: "bkit-tests-e2e-ios",
171
- file: ".github/workflows/bkit-ci.yml",
172
151
  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
152
  },
174
153
  {
175
154
  id: "bkit-tests-build-android",
176
- file: ".github/workflows/bkit-ci.yml",
177
155
  description: "Add `bkit-tests-build-android`. Same contract as bkit-tests-build-ios, android tokens. DROP if you have no Android app.",
178
156
  },
179
157
  {
180
158
  id: "bkit-tests-e2e-android",
181
- file: ".github/workflows/bkit-ci.yml",
182
159
  description: "Add `bkit-tests-e2e-android`. Same contract as bkit-tests-e2e-ios, android tokens. DROP if you have no Android app.",
183
160
  },
184
161
  {
185
162
  id: "logging-probe",
186
- file: ".github/workflows/bkit-ci.yml",
187
163
  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
164
  },
189
165
  {
190
166
  id: "bkit-tests-deploy",
191
- file: ".github/workflows/bkit-ci.yml",
192
167
  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
168
  },
194
169
  {
195
170
  id: "health",
196
- file: ".github/workflows/bkit-ci.yml",
197
171
  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.",
198
172
  },
199
173
  ];
200
174
  export function detectBkitStubs(cwd) {
201
175
  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
- };
176
+ const ciRel = ciWorkflowPath(cwd);
177
+ const ciPath = path.join(cwd, ciRel);
178
+ if (!fs.existsSync(ciPath))
179
+ return findings;
180
+ const content = fs.readFileSync(ciPath, "utf-8");
218
181
  // Track which stubs are still commented (sentinel present) so the pair-conflict
219
182
  // pass below can compare against per-stub "enabled" markers (the named YAML step
220
183
  // appearing uncommented).
221
184
  const stubSentinelPresent = new Set();
222
185
  for (const stub of BKIT_STUBS) {
223
- const content = readOnce(stub.file);
224
- if (content === null)
225
- continue;
226
186
  // Sentinel is the full HEADER form — `# bkit-stub:<id> — <description>` — the line the
227
187
  // advisory tells you to delete. Prose back-references ("the bkit-stub:coverage integration
228
188
  // report posts from HERE") do not match, and `# bkit-stub:e2e —` cannot match stub
@@ -235,9 +195,9 @@ export function detectBkitStubs(cwd) {
235
195
  findings.push({
236
196
  id: `bkit-stub-${stub.id}`,
237
197
  severity: "advisory",
238
- detect: `${stub.file} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
198
+ detect: `${ciRel} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
239
199
  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` +
200
+ `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
201
  `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
202
  `Until the sentinel is removed, this advisory fires every install / check.`,
243
203
  });
@@ -246,39 +206,36 @@ export function detectBkitStubs(cwd) {
246
206
  // produces a silent fallback. Detection signal: the named uncommented YAML step
247
207
  // appears (sentinel removed → likely enabled), and the paired stub's sentinel
248
208
  // 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
- }
209
+ // Match a YAML step name uncommented (leading `- name:` not preceded by `#`).
210
+ const isStepEnabled = (stepName) => {
211
+ const re = new RegExp(`(^|\\n)\\s*- name:\\s*${stepName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
212
+ return re.test(content);
213
+ };
214
+ const e2eEnabled = isStepEnabled("Run E2E Tests");
215
+ const vercelEnabled = isStepEnabled("Await Vercel Preview");
216
+ if (vercelEnabled && stubSentinelPresent.has("e2e")) {
217
+ findings.push({
218
+ id: "bkit-stub-pair-vercel-without-e2e",
219
+ severity: "advisory",
220
+ detect: `${ciRel} has \`Await Vercel Preview\` enabled but \`Run E2E Tests\` is still commented (bkit-stub:e2e sentinel present).`,
221
+ 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.",
222
+ });
223
+ }
224
+ if (e2eEnabled && stubSentinelPresent.has("vercel-await")) {
225
+ findings.push({
226
+ id: "bkit-stub-pair-e2e-without-vercel",
227
+ severity: "advisory",
228
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`Await Vercel Preview\` is still commented (bkit-stub:vercel-await sentinel present).`,
229
+ 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.",
230
+ });
231
+ }
232
+ if (e2eEnabled && stubSentinelPresent.has("auto-force-e2e")) {
233
+ findings.push({
234
+ id: "bkit-stub-pair-e2e-without-auto-force",
235
+ severity: "advisory",
236
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`bkit-stub:auto-force-e2e\` is still commented.`,
237
+ 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.",
238
+ });
282
239
  }
283
240
  return findings;
284
241
  }
@@ -333,6 +290,6 @@ export function buildDepUpdaterSetupAdvisory(cwd) {
333
290
  detect: "No dependency updater config. SHA-pinned actions and package bumps will not refresh on their own.",
334
291
  action: "Copy one example and own it:\n\n" +
335
292
  ` ${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.',
293
+ 'Use one updater, not both. To silence this advisory, set `bkit.dependencies.updater` to `"none"` in package.json. See .bkit/templates.md.',
337
294
  };
338
295
  }
@@ -13,7 +13,7 @@ const TRACKER_TOKENS = {
13
13
  description: "Linear personal API key for the Linear MCP server and the Linear preflight hook (generate at https://linear.app/settings/api)",
14
14
  },
15
15
  jira: {
16
- key: "BKIT_JIRA_API_TOKEN",
16
+ key: "BKIT_JIRA_API_KEY",
17
17
  description: 'Atlassian API token with scopes for the app "Atlassian MCP V2", sent as Bearer to the Jira MCP server (create at https://id.atlassian.com/manage-profile/security/api-tokens; see .bkit/trackers.md § jira)',
18
18
  },
19
19
  };
@@ -28,7 +28,7 @@ function tokenKeys(tracker) {
28
28
  * copied it to .bkit/.env and filled in their tokens.
29
29
  */
30
30
  // `tracker` adds its own token to the token prose (`TRACKER_TOKENS`). Defaults to
31
- // `linear`; the real Phase-3 caller passes the consumer's resolved `bkit.issueTracker`.
31
+ // `linear`; the real Phase-3 caller passes the consumer's resolved `bkit.tracker.default`.
32
32
  export function detectMissingDotenv(cwd, tracker = "linear") {
33
33
  const examplePath = path.join(cwd, ".bkit", ".env.example");
34
34
  const envPath = path.join(cwd, ".bkit", ".env");
@@ -7,6 +7,7 @@ import { extractManagedBlock, stripManagedBlock } from "../../install/managed-bl
7
7
  import { readTemplate } from "../../render/parts.js";
8
8
  import { findTemplateSource, getPkgRoot } from "../../shared/package-roots.js";
9
9
  import { parseJson } from "../../shared/json.js";
10
+ import { ciWorkflowPath } from "../../shared/settings.js";
10
11
  /**
11
12
  * Strip out content inside bkit-managed block markers (HTML and slash style).
12
13
  * Used by detectors that need to inspect only consumer-owned content.
@@ -67,11 +68,12 @@ export function detectGitignoreBlockDuplicates(cwd) {
67
68
  * surfaces — pure cost (artifact upload + storage) with zero diagnostic payoff.
68
69
  *
69
70
  * "Hostile" gap per the BAR-224 signal-vs-noise classification. Reads the consumer's
70
- * own bkit-ci.yml, active lines only: YAML comment lines are dropped first, so a commented
71
+ * own CI workflow (`bkit.testing.ciWorkflow`, default `bkit-ci.yml`), active lines only: YAML comment lines are dropped first, so a commented
71
72
  * template stub or a commented-out example never fires.
72
73
  */
73
74
  export function detectPlaywrightReporterHostile(cwd) {
74
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
75
+ const ciRel = ciWorkflowPath(cwd);
76
+ const ciPath = path.join(cwd, ciRel);
75
77
  if (!fs.existsSync(ciPath))
76
78
  return null;
77
79
  const content = fs.readFileSync(ciPath, "utf-8");
@@ -92,7 +94,7 @@ export function detectPlaywrightReporterHostile(cwd) {
92
94
  return {
93
95
  id: "playwright-reporter-line-override-hostile",
94
96
  severity: "advisory",
95
- detect: ".github/workflows/bkit-ci.yml has a `playwright test` invocation that passes `--reporter=line`. Under `[verbose ci]` with `--trace=on`, trace artifacts are written but no reporter surfaces them — pure cost.",
97
+ detect: `${ciRel} has a \`playwright test\` invocation that passes \`--reporter=line\`. Under \`[verbose ci]\` with \`--trace=on\`, trace artifacts are written but no reporter surfaces them — pure cost.`,
96
98
  action: 'Drop the `--reporter=line` flag so `playwright.config.ts`\'s configured reporter chain runs (typically `[list, html, github, json]`). Verbose-aware pattern: have `test:e2e` read `VERBOSE_CI` and append `--trace=on` to its own `playwright test` call (e.g. `TRACE=; [ "$VERBOSE_CI" = "1" ] && TRACE=--trace=on; playwright test $TRACE`), then run it plainly as `pnpm test:e2e` — do NOT pass `--trace=on` through a turbo / pnpm `-- --trace=on` passthrough, which appends to the script string and breaks any test:e2e ending in a bash construct (fi / done / esac). Never pass `--reporter`. Note that `--video` and `--screenshot` are NOT Playwright CLI flags (they\'re `use:` keys in playwright.config.ts); the trace.zip already captures snapshots / network / console / source. Default-mode output stays clean via the config\'s `list` reporter.',
97
99
  };
98
100
  }
@@ -10,9 +10,10 @@
10
10
  // readBkitConfig — from shared/settings.ts (the consumer's `bkit` settings)
11
11
  // readInstallingVersion — from shared/package-json.ts (the version of the bkit doing the install)
12
12
  // readTemplate — from render/parts.ts (template with its shared parts spliced in)
13
+ // parsePlanBlocks — from commands/workflow/plan-blocks.ts (a plan's group and task blocks)
13
14
  import { readInstallingVersion } from "../../shared/package-json.js";
14
15
  import { readBkitConfig } from "../../shared/settings.js";
15
- import { detectBkitNotOnPath, detectMalformedPackageJson, detectNoPackageJson, detectNotGitRepo, } from "./repo.js";
16
+ import { detectBkitNotOnPath, detectMalformedPackageJson, detectNoPackageJson, detectNotGitRepo, detectInvalidAskSettings, detectInvalidTaskCaps, detectTaskCapFormStale, detectUnmarkedPlans, } from "./repo.js";
16
17
  import { MARKERED_TEXT_DRIFT_PATHS, detectGitignoreBlockDuplicates, detectPlaywrightReporterHostile, detectTier2JsonDrift, detectTier2TextDrift, } from "./files.js";
17
18
  import { detectBkitVersionMajorDowngrade, detectBkitVersionPinStale } from "./version.js";
18
19
  import { detectContextFetchContextMissing, detectContextFetchMissing, detectContextFetchProvisionMissing, detectContextFetchSourceNotEnabled, } from "./context-fetch.js";
@@ -42,7 +43,7 @@ export function dedupeById(findings) {
42
43
  * installingVersion: used by detectBkitVersionMajorDowngrade; defaults to the
43
44
  * package's own version read from its package.json at runtime.
44
45
  * issueTracker: when provided, narrows tracker-specific checks (e.g. MCP server
45
- * requirements). When omitted, read from consumer's `bkit.issueTracker` in package.json.
46
+ * requirements). When omitted, read from consumer's `bkit.tracker.default` in package.json.
46
47
  *
47
48
  * GitHub tracker gate: when `issueTracker === "github"`, the Linear preflight
48
49
  * gate is a no-op — the GitHub gate is enforced by workflow Step 1 via MCP.
@@ -87,6 +88,18 @@ export function runPreflight(modules, cwd = process.cwd(), installingVersion, is
87
88
  const versionPinStale = detectBkitVersionPinStale(cwd);
88
89
  if (versionPinStale)
89
90
  advisories.push(versionPinStale);
91
+ const invalidTaskCaps = detectInvalidTaskCaps(cwd);
92
+ if (invalidTaskCaps)
93
+ advisories.push(invalidTaskCaps);
94
+ const taskCapFormStale = detectTaskCapFormStale(cwd);
95
+ if (taskCapFormStale)
96
+ advisories.push(taskCapFormStale);
97
+ const invalidAsks = detectInvalidAskSettings(cwd);
98
+ if (invalidAsks)
99
+ advisories.push(invalidAsks);
100
+ const unmarkedPlans = detectUnmarkedPlans(cwd);
101
+ if (unmarkedPlans)
102
+ advisories.push(unmarkedPlans);
90
103
  // BAR-224: [verbose ci] marker advisories
91
104
  const playwrightReporterHostile = detectPlaywrightReporterHostile(cwd);
92
105
  if (playwrightReporterHostile)
@@ -1,9 +1,11 @@
1
1
  // checks/before/repo.ts — repo preconditions: package.json present and parseable, a git repo,
2
- // bkit on PATH.
2
+ // valid plan caps, a change issue form showing them, plans in task-block form, bkit on PATH.
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 { readJsonFile } from "../../shared/json.js";
6
+ import { parsePlanBlocks } from "../../commands/workflow/plan-blocks.js";
7
+ import { parseJson, readJsonFile } from "../../shared/json.js";
8
+ import { ASK_POINTS, CONFIG_DEFAULTS, invalidAskSettings, invalidTaskCaps, limitKey, readBkitConfig, } from "../../shared/settings.js";
7
9
  import { isCloudOrCi } from "./env.js";
8
10
  // ---------------------------------------------------------------------------
9
11
  // Blocker detectors
@@ -43,6 +45,165 @@ export function detectNotGitRepo(cwd, modules) {
43
45
  action: "Run `git init` to initialise a git repo, then re-run. bkit installs into a git repository — its managed .gitignore/.gitattributes blocks require one (core is implicit; there is no --core flag to omit).",
44
46
  };
45
47
  }
48
+ /**
49
+ * Advisory: `package.json` `bkit.workflows.tasks` holds a plan cap that is not an integer >= 1.
50
+ * Each such key falls back to its default in `readBkitConfig`.
51
+ */
52
+ export function detectInvalidTaskCaps(cwd) {
53
+ const workflows = bkitWorkflows(cwd);
54
+ if (workflows === null)
55
+ return null;
56
+ const bad = invalidTaskCaps(workflows.tasks);
57
+ if (bad.length === 0)
58
+ return null;
59
+ const caps = CONFIG_DEFAULTS.tasks;
60
+ const keys = bad[0] === "tasks" ? Object.keys(caps) : bad;
61
+ const named = bad.map((k) => `\`bkit.workflows.${k === "tasks" ? k : `tasks.${k}`}\``).join(", ");
62
+ return {
63
+ id: "bkit-tasks-invalid",
64
+ severity: "advisory",
65
+ detect: `package.json ${named} is not a whole number of 1 or more, so the plan check uses the default instead.`,
66
+ action: `Set each to a whole number of 1 or more in package.json, or delete it to keep the default: ${keys
67
+ .map((k) => `\`bkit.workflows.tasks.${k}\` (default ${caps[k]})`)
68
+ .join(", ")}.`,
69
+ };
70
+ }
71
+ const TASK_CAP_KEY = /`bkit\.workflows\.tasks\.(\w+)`/g;
72
+ /**
73
+ * Each `bkit.workflows.tasks.<key>` the text names with a `(default N)` after it, on the same
74
+ * line and before the next named key.
75
+ */
76
+ export function taskCapDefaultsNamed(text) {
77
+ const hits = [...text.matchAll(TASK_CAP_KEY)];
78
+ return hits.flatMap((m, i) => {
79
+ const from = m.index + m[0].length;
80
+ const lineEnd = text.indexOf("\n", from);
81
+ const end = Math.min(hits[i + 1]?.index ?? text.length, lineEnd === -1 ? text.length : lineEnd);
82
+ const n = /\(default (\d+)\)/.exec(text.slice(from, end));
83
+ return n ? [{ key: m[1], value: Number(n[1]) }] : [];
84
+ });
85
+ }
86
+ const CHANGE_FORM = ".github/ISSUE_TEMPLATE/bkit-change.yml";
87
+ /**
88
+ * Advisory: the change issue form names a plan cap with a `(default N)` that differs from the
89
+ * value `readBkitConfig` gives for that key.
90
+ */
91
+ export function detectTaskCapFormStale(cwd) {
92
+ const file = path.join(cwd, CHANGE_FORM);
93
+ if (!fs.existsSync(file))
94
+ return null;
95
+ const caps = readBkitConfig(cwd).tasks;
96
+ const isCap = (k) => Object.hasOwn(caps, k);
97
+ const stale = new Map();
98
+ for (const { key, value } of taskCapDefaultsNamed(fs.readFileSync(file, "utf-8"))) {
99
+ if (isCap(key) && caps[key] !== value)
100
+ stale.set(key, value);
101
+ }
102
+ if (stale.size === 0)
103
+ return null;
104
+ const rows = [...stale];
105
+ return {
106
+ id: "bkit-tasks-form-stale",
107
+ severity: "advisory",
108
+ detect: `${CHANGE_FORM} shows plan caps that differ from package.json: ${rows
109
+ .map(([k, v]) => `\`bkit.workflows.tasks.${k}\` (default ${v}) is ${caps[k]}`)
110
+ .join(", ")}.`,
111
+ action: `In ${CHANGE_FORM}, change the number in each "(default N)" after the key: ${rows
112
+ .map(([k, v]) => `\`bkit.workflows.tasks.${k}\` "(default ${v})" → "(default ${caps[k]})"`)
113
+ .join(", ")}. Or set the key in package.json \`bkit.workflows.tasks\` to the number the form shows.`,
114
+ };
115
+ }
116
+ /** `package.json` `bkit.workflows` as an object; null when the file or block is unusable. */
117
+ function bkitWorkflows(cwd) {
118
+ const read = readJsonFile(path.join(cwd, "package.json"));
119
+ if (!read.ok)
120
+ return null;
121
+ const bkit = read.value?.bkit;
122
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit))
123
+ return null;
124
+ const workflows = bkit.workflows;
125
+ return workflows !== null && typeof workflows === "object" && !Array.isArray(workflows)
126
+ ? workflows
127
+ : {};
128
+ }
129
+ /**
130
+ * Advisory when a `bkit.workflows.<workflow>.<point>` block holds an `ask` that is not
131
+ * true/false, a limit that is not a whole number of 1 or more, or is not an object. Each such
132
+ * key falls back to its default in `readBkitConfig`.
133
+ */
134
+ export function detectInvalidAskSettings(cwd) {
135
+ const workflows = bkitWorkflows(cwd);
136
+ if (workflows === null)
137
+ return null;
138
+ const bad = invalidAskSettings(workflows);
139
+ if (bad.length === 0)
140
+ return null;
141
+ const defaults = bad.map((k) => {
142
+ const point = ASK_POINTS.find((p) => k === p || k.startsWith(`${p}.`));
143
+ const d = CONFIG_DEFAULTS.asks[point];
144
+ return `\`bkit.workflows.${point}\` (default \`{ "ask": ${d.ask}, "${limitKey(point)}": ${d.max} }\`)`;
145
+ });
146
+ return {
147
+ id: "bkit-ask-settings-invalid",
148
+ severity: "advisory",
149
+ detect: `package.json ${bad.map((k) => `\`bkit.workflows.${k}\``).join(", ")} is not valid (\`ask\` takes true or false, a limit a whole number of 1 or more), so the default is used instead.`,
150
+ action: `Fix or delete each in package.json: ${[...new Set(defaults)].join(", ")}.`,
151
+ };
152
+ }
153
+ const PLAN_FILE = /^(.+)-plan\.md$/;
154
+ /** The FID's `docs/plans/{month}/logs/{FID}/status.jsonl` holds a ship `workflow-done` row. */
155
+ function fidShipped(monthDir, fid) {
156
+ const file = path.join(monthDir, "logs", fid, "status.jsonl");
157
+ if (!fs.existsSync(file))
158
+ return false;
159
+ return fs
160
+ .readFileSync(file, "utf-8")
161
+ .split("\n")
162
+ .some((line) => {
163
+ const row = parseJson(line);
164
+ if (!row.ok || typeof row.value !== "object" || row.value === null)
165
+ return false;
166
+ const { type, workflow } = row.value;
167
+ return type === "workflow-done" && workflow === "ship";
168
+ });
169
+ }
170
+ /**
171
+ * Advisory: a `docs/plans/{YYYYMM}/{FID}-plan.md` whose FID has not shipped holds no task
172
+ * blocks, so `/bkit-build` Step 3 converts it on the FID's next build. `archive/` and
173
+ * `logs/` sit below the month folder and are not read.
174
+ */
175
+ export function detectUnmarkedPlans(cwd) {
176
+ const plans = path.join(cwd, "docs", "plans");
177
+ if (!fs.existsSync(plans))
178
+ return null;
179
+ const unmarked = [];
180
+ for (const month of fs.readdirSync(plans, { withFileTypes: true })) {
181
+ if (!month.isDirectory())
182
+ continue;
183
+ const monthDir = path.join(plans, month.name);
184
+ for (const entry of fs.readdirSync(monthDir, { withFileTypes: true })) {
185
+ const fid = entry.isFile() ? PLAN_FILE.exec(entry.name)?.[1] : undefined;
186
+ if (fid === undefined)
187
+ continue;
188
+ const text = fs.readFileSync(path.join(monthDir, entry.name), "utf-8");
189
+ if (parsePlanBlocks(text).tasks.length > 0 || fidShipped(monthDir, fid))
190
+ continue;
191
+ unmarked.push(`docs/plans/${month.name}/${entry.name}`);
192
+ }
193
+ }
194
+ if (unmarked.length === 0)
195
+ return null;
196
+ unmarked.sort();
197
+ const one = unmarked.length === 1;
198
+ return {
199
+ id: "plan-task-markers-missing",
200
+ severity: "advisory",
201
+ detect: `${unmarked.length} ${one ? "plan has" : "plans have"} no task markers and will be converted to group and task blocks on the next \`/bkit-build\` of ${one ? "its" : "their"} FID: ${unmarked
202
+ .map((p) => `\`${p}\``)
203
+ .join(", ")}.`,
204
+ action: "Nothing to do by hand: this matters only for builds still to run, and plans of shipped FIDs are not listed.",
205
+ };
206
+ }
46
207
  /**
47
208
  * Advisory: `bkit` is not on PATH.
48
209
  * bkit is a devDependency — without a shell alias, every invocation requires
@@ -19,7 +19,7 @@
19
19
  // Detection rules: every `fires` is local (files, settings, environment) — no network.
20
20
  // Where an advisory already detects the gap, `fires` calls that detector and `advisories`
21
21
  // names its ids, so the tip and the advisory can never disagree and one
22
- // `bkit.ignoreAdvisories` entry silences both.
22
+ // `bkit.advisories.ignore` entry silences both.
23
23
  import * as fs from "node:fs";
24
24
  import * as path from "node:path";
25
25
  import { machineStepsPath, REPO_STEPS } from "../../commands/workflow/disk.js";
@@ -30,7 +30,7 @@ import { buildTrackerSetupAdvisory } from "../after/github.js";
30
30
  import { buildDepUpdaterSetupAdvisory } from "../after/tools.js";
31
31
  import { detectInstalledHostModules } from "../../install/hosts.js";
32
32
  import { readBkitConfig } from "../../shared/settings.js";
33
- import { anyWorkflowMentions, claudeSettingsHas, codexTopLevelHas, exists, hasJsTestRunner, hasLintStagedConfig, hasMcpServer, hasTestLinter, unlockedMcpServers, } from "./detect.js";
33
+ import { anyWorkflowMentions, claudeSettingsHas, codexTopLevelHas, exists, hasJsTestRunner, hasLintStagedConfig, hasMcpServer, hasTestLinter, readsBkitText, unlockedMcpServers, } from "./detect.js";
34
34
  const hosts = (cwd) => detectInstalledHostModules(cwd);
35
35
  /** Every phase workflow. A value import of `COMPLY_PHASES` would cycle through cli.ts. */
36
36
  export const ALL_WORKFLOWS = ["design", "plan", "build", "debug", "ship"];
@@ -44,8 +44,8 @@ export const SETUP_TIPS = [
44
44
  title: "Connect an issue tracker",
45
45
  line: "bkit isn't connected to an issue tracker, so it can't read the task it's working on or record what it did. Connect GitHub, Linear or Jira, or switch this tip off if you don't want one.",
46
46
  why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
47
- ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.issueTracker` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
48
- steps: '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "issueTracker": "none" }` in `package.json`.',
47
+ ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.tracker.default` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
48
+ steps: '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "tracker": { "default": "none" } }` in `package.json`.',
49
49
  advisories: ["tracker-setup-none"],
50
50
  fires: (cwd) => buildTrackerSetupAdvisory(cwd)?.id === "tracker-setup-none",
51
51
  },
@@ -112,7 +112,7 @@ export const SETUP_TIPS = [
112
112
  title: "Automatic checks on every change",
113
113
  line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
114
114
  why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
115
- ask: "Copy .bkit/templates/.github/workflows/bkit-ci.yml to .github/workflows/bkit-ci.yml, replace `main` and `{{NODE_VERSION}}` in it with my default branch and Node major version, and add the `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
115
+ ask: "Copy .bkit/templates/.github/workflows/bkit-ci.yml to .github/workflows/<the file package.json `bkit.testing.ciWorkflow` names; default bkit-ci.yml>, replace `main` and `{{NODE_VERSION}}` in it with my default branch and Node major version, and add the `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
116
116
  steps: "`.bkit/templates.md` § CI workflow and § Gate tool scripts.",
117
117
  fires: (cwd) => !exists(cwd, `.github/workflows/${readBkitConfig(cwd).ciWorkflow}`),
118
118
  },
@@ -339,6 +339,15 @@ export const SETUP_TIPS = [
339
339
  !fs.existsSync(machineStepsPath()),
340
340
  },
341
341
  // --- setup: only some setups -----------------------------------------------------------
342
+ {
343
+ id: "bkit-output-json",
344
+ title: "Scripts that read bkit's replies",
345
+ line: "A hook, script or CI step reads bkit's replies as JSON, but bkit replies in plain text unless the call passes `--json`. Add `--json` to those bkit calls.",
346
+ why: "bkit answers in short text lines by default because agents read them. A script expecting JSON gets nothing it can parse, so its step quietly does nothing.",
347
+ ask: "Add --json to every bkit call whose output a hook, script or CI workflow parses (piped to jq, or read with JSON.parse), then rerun `bkit tips` until this tip is gone.",
348
+ steps: "`.bkit/workflows.md` § Workflow commands. Files: `.claude/hooks/`, `.husky/`, `.github/workflows/`, `scripts/`.",
349
+ fires: (cwd) => readsBkitText(cwd).length > 0,
350
+ },
342
351
  {
343
352
  id: "cursor-files",
344
353
  title: "Cursor editor settings",