@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
@@ -5,7 +5,7 @@ import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { spawnSync } from "node:child_process";
7
7
  import type { PreflightFinding } from "../before/index.js";
8
- import { readBkitConfig } from "../../shared/settings.js";
8
+ import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
9
9
 
10
10
  /** True when `cmd --version` runs (binary on PATH, exits 0). */
11
11
  function toolVersionRuns(cmd: string): boolean {
@@ -73,12 +73,13 @@ export function detectWorkflowLintToolsMissing(cwd: string): PreflightFinding |
73
73
  }
74
74
 
75
75
  /**
76
- * Detect bkit-stub:<id> sentinel comments in installed config files. Each sentinel
76
+ * Detect bkit-stub:<id> sentinel comments in the CI workflow (`bkit.testing.ciWorkflow`,
77
+ * default `bkit-ci.yml`), the file every stub lives in. Each sentinel
77
78
  * marks a commented-in YAML / shell block that bkit ships disabled by default;
78
79
  * the corresponding advisory points the installing AI/user at the block so they
79
80
  * can decide whether to enable, customise, or delete it.
80
81
  *
81
- * Each stub is keyed on (file, id). To dismiss an advisory: remove the sentinel
82
+ * Each stub is keyed on its id. To dismiss an advisory: remove the sentinel
82
83
  * header line. Uncommenting the block alone does NOT silence the advisory —
83
84
  * delete the `# bkit-stub:<id> — ...` header line at the same time.
84
85
  *
@@ -89,8 +90,6 @@ export function detectWorkflowLintToolsMissing(cwd: string): PreflightFinding |
89
90
  interface BkitStub {
90
91
  /** Stub identifier; matches the `# bkit-stub:<id> — ...` header line in the file. */
91
92
  id: string;
92
- /** Path relative to cwd. */
93
- file: string;
94
93
  /** Short description of what enabling the block does — surfaced to the installing AI. */
95
94
  description: string;
96
95
  }
@@ -98,61 +97,51 @@ interface BkitStub {
98
97
  const BKIT_STUBS: BkitStub[] = [
99
98
  {
100
99
  id: "auto-force-e2e",
101
- file: ".github/workflows/bkit-ci.yml",
102
100
  description:
103
101
  "Auto-trigger E2E on PRs whose diff touches sensitive paths (auth, migrations, payment, api, server).",
104
102
  },
105
103
  {
106
104
  id: "migrations-immutable",
107
- file: ".github/workflows/bkit-ci.yml",
108
105
  description:
109
106
  "Fail PRs that modify supabase/migrations/* files already present on the base branch — enforces migration immutability after merge.",
110
107
  },
111
108
  {
112
109
  id: "test-presence",
113
- file: ".github/workflows/bkit-ci.yml",
114
110
  description:
115
111
  "Warn when a workspace package declares a `test` script but contains zero `*.test.ts(x)` / `*.spec.ts(x)` files (guards against accidental deletion).",
116
112
  },
117
113
  {
118
114
  id: "supabase-migrate",
119
- file: ".github/workflows/bkit-ci.yml",
120
115
  description:
121
116
  "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).",
122
117
  },
123
118
  {
124
119
  id: "test-db",
125
- file: ".github/workflows/bkit-ci.yml",
126
120
  description:
127
121
  "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.",
128
122
  },
129
123
  {
130
124
  id: "vercel-await",
131
- file: ".github/workflows/bkit-ci.yml",
132
125
  description:
133
126
  "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.",
134
127
  },
135
128
  {
136
129
  id: "e2e",
137
- file: ".github/workflows/bkit-ci.yml",
138
130
  description:
139
131
  "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.",
140
132
  },
141
133
  {
142
134
  id: "smoke",
143
- file: ".github/workflows/bkit-ci.yml",
144
135
  description:
145
136
  "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.",
146
137
  },
147
138
  {
148
139
  id: "coverage",
149
- file: ".github/workflows/bkit-ci.yml",
150
140
  description:
151
141
  "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.",
152
142
  },
153
143
  {
154
144
  id: "e2e-coverage",
155
- file: ".github/workflows/bkit-ci.yml",
156
145
  description:
157
146
  "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.",
158
147
  },
@@ -161,97 +150,81 @@ const BKIT_STUBS: BkitStub[] = [
161
150
  // template bkit-ci.yml. Order matters when adopting — see that block.
162
151
  {
163
152
  id: "bkit-tests-scope",
164
- file: ".github/workflows/bkit-ci.yml",
165
153
  description:
166
154
  "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.",
167
155
  },
168
156
  {
169
157
  id: "affected-graph",
170
- file: ".github/workflows/bkit-ci.yml",
171
158
  description:
172
159
  "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).",
173
160
  },
174
161
  {
175
162
  id: "bkit-tests-live-web",
176
- file: ".github/workflows/bkit-ci.yml",
177
163
  description:
178
164
  "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.",
179
165
  },
180
166
  {
181
167
  id: "bkit-tests-migration",
182
- file: ".github/workflows/bkit-ci.yml",
183
168
  description:
184
169
  "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).",
185
170
  },
186
171
  {
187
172
  id: "bkit-tests-integration",
188
- file: ".github/workflows/bkit-ci.yml",
189
173
  description:
190
174
  "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:`.",
191
175
  },
192
176
  {
193
177
  id: "bkit-tests-e2e-web",
194
- file: ".github/workflows/bkit-ci.yml",
195
178
  description:
196
179
  "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.",
197
180
  },
198
181
  {
199
182
  id: "bkit-tests-build-web",
200
- file: ".github/workflows/bkit-ci.yml",
201
183
  description:
202
184
  "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:.",
203
185
  },
204
186
  {
205
187
  id: "bkit-tests-reset",
206
- file: ".github/workflows/bkit-ci.yml",
207
188
  description:
208
189
  "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.",
209
190
  },
210
191
  {
211
192
  id: "bkit-tests-cleanup",
212
- file: ".github/workflows/bkit-ci.yml",
213
193
  description:
214
194
  "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.",
215
195
  },
216
196
  {
217
197
  id: "bkit-tests-build-ios",
218
- file: ".github/workflows/bkit-ci.yml",
219
198
  description:
220
199
  "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.",
221
200
  },
222
201
  {
223
202
  id: "bkit-tests-e2e-ios",
224
- file: ".github/workflows/bkit-ci.yml",
225
203
  description:
226
204
  "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.",
227
205
  },
228
206
  {
229
207
  id: "bkit-tests-build-android",
230
- file: ".github/workflows/bkit-ci.yml",
231
208
  description:
232
209
  "Add `bkit-tests-build-android`. Same contract as bkit-tests-build-ios, android tokens. DROP if you have no Android app.",
233
210
  },
234
211
  {
235
212
  id: "bkit-tests-e2e-android",
236
- file: ".github/workflows/bkit-ci.yml",
237
213
  description:
238
214
  "Add `bkit-tests-e2e-android`. Same contract as bkit-tests-e2e-ios, android tokens. DROP if you have no Android app.",
239
215
  },
240
216
  {
241
217
  id: "logging-probe",
242
- file: ".github/workflows/bkit-ci.yml",
243
218
  description:
244
219
  "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.",
245
220
  },
246
221
  {
247
222
  id: "bkit-tests-deploy",
248
- file: ".github/workflows/bkit-ci.yml",
249
223
  description:
250
224
  "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.",
251
225
  },
252
226
  {
253
227
  id: "health",
254
- file: ".github/workflows/bkit-ci.yml",
255
228
  description:
256
229
  "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.",
257
230
  },
@@ -259,20 +232,10 @@ const BKIT_STUBS: BkitStub[] = [
259
232
 
260
233
  export function detectBkitStubs(cwd: string): PreflightFinding[] {
261
234
  const findings: PreflightFinding[] = [];
262
- // Cache file reads so repeated scans of the same file are O(1).
263
- const fileCache = new Map<string, string | null>();
264
- const readOnce = (file: string): string | null => {
265
- if (fileCache.has(file)) return fileCache.get(file) ?? null;
266
- const abs = path.join(cwd, file);
267
- try {
268
- const content = fs.existsSync(abs) ? fs.readFileSync(abs, "utf-8") : null;
269
- fileCache.set(file, content);
270
- return content;
271
- } catch {
272
- fileCache.set(file, null);
273
- return null;
274
- }
275
- };
235
+ const ciRel = ciWorkflowPath(cwd);
236
+ const ciPath = path.join(cwd, ciRel);
237
+ if (!fs.existsSync(ciPath)) return findings;
238
+ const content = fs.readFileSync(ciPath, "utf-8");
276
239
 
277
240
  // Track which stubs are still commented (sentinel present) so the pair-conflict
278
241
  // pass below can compare against per-stub "enabled" markers (the named YAML step
@@ -280,8 +243,6 @@ export function detectBkitStubs(cwd: string): PreflightFinding[] {
280
243
  const stubSentinelPresent = new Set<string>();
281
244
 
282
245
  for (const stub of BKIT_STUBS) {
283
- const content = readOnce(stub.file);
284
- if (content === null) continue;
285
246
  // Sentinel is the full HEADER form — `# bkit-stub:<id> — <description>` — the line the
286
247
  // advisory tells you to delete. Prose back-references ("the bkit-stub:coverage integration
287
248
  // report posts from HERE") do not match, and `# bkit-stub:e2e —` cannot match stub
@@ -293,10 +254,10 @@ export function detectBkitStubs(cwd: string): PreflightFinding[] {
293
254
  findings.push({
294
255
  id: `bkit-stub-${stub.id}`,
295
256
  severity: "advisory",
296
- detect: `${stub.file} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
257
+ detect: `${ciRel} contains the bkit-stub:${stub.id} sentinel — a commented-in block shipped disabled by default.`,
297
258
  action:
298
259
  `${stub.description}\n\n` +
299
- `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` +
260
+ `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` +
300
261
  `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` +
301
262
  `Until the sentinel is removed, this advisory fires every install / check.`,
302
263
  });
@@ -306,48 +267,42 @@ export function detectBkitStubs(cwd: string): PreflightFinding[] {
306
267
  // produces a silent fallback. Detection signal: the named uncommented YAML step
307
268
  // appears (sentinel removed → likely enabled), and the paired stub's sentinel
308
269
  // is still present (still disabled).
309
- const ciContent = readOnce(".github/workflows/bkit-ci.yml");
310
- if (ciContent) {
311
- // Match a YAML step name uncommented (leading `- name:` not preceded by `#`).
312
- const isStepEnabled = (stepName: string): boolean => {
313
- const re = new RegExp(
314
- `(^|\\n)\\s*- name:\\s*${stepName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`,
315
- );
316
- return re.test(ciContent);
317
- };
318
- const e2eEnabled = isStepEnabled("Run E2E Tests");
319
- const vercelEnabled = isStepEnabled("Await Vercel Preview");
270
+ // Match a YAML step name uncommented (leading `- name:` not preceded by `#`).
271
+ const isStepEnabled = (stepName: string): boolean => {
272
+ const re = new RegExp(
273
+ `(^|\\n)\\s*- name:\\s*${stepName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`,
274
+ );
275
+ return re.test(content);
276
+ };
277
+ const e2eEnabled = isStepEnabled("Run E2E Tests");
278
+ const vercelEnabled = isStepEnabled("Await Vercel Preview");
320
279
 
321
- if (vercelEnabled && stubSentinelPresent.has("e2e")) {
322
- findings.push({
323
- id: "bkit-stub-pair-vercel-without-e2e",
324
- severity: "advisory",
325
- detect:
326
- ".github/workflows/bkit-ci.yml has `Await Vercel Preview` enabled but `Run E2E Tests` is still commented (bkit-stub:e2e sentinel present).",
327
- action:
328
- "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.",
329
- });
330
- }
331
- if (e2eEnabled && stubSentinelPresent.has("vercel-await")) {
332
- findings.push({
333
- id: "bkit-stub-pair-e2e-without-vercel",
334
- severity: "advisory",
335
- detect:
336
- ".github/workflows/bkit-ci.yml has `Run E2E Tests` enabled but `Await Vercel Preview` is still commented (bkit-stub:vercel-await sentinel present).",
337
- action:
338
- "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.",
339
- });
340
- }
341
- if (e2eEnabled && stubSentinelPresent.has("auto-force-e2e")) {
342
- findings.push({
343
- id: "bkit-stub-pair-e2e-without-auto-force",
344
- severity: "advisory",
345
- detect:
346
- ".github/workflows/bkit-ci.yml has `Run E2E Tests` enabled but `bkit-stub:auto-force-e2e` is still commented.",
347
- action:
348
- "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.",
349
- });
350
- }
280
+ if (vercelEnabled && stubSentinelPresent.has("e2e")) {
281
+ findings.push({
282
+ id: "bkit-stub-pair-vercel-without-e2e",
283
+ severity: "advisory",
284
+ detect: `${ciRel} has \`Await Vercel Preview\` enabled but \`Run E2E Tests\` is still commented (bkit-stub:e2e sentinel present).`,
285
+ action:
286
+ "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.",
287
+ });
288
+ }
289
+ if (e2eEnabled && stubSentinelPresent.has("vercel-await")) {
290
+ findings.push({
291
+ id: "bkit-stub-pair-e2e-without-vercel",
292
+ severity: "advisory",
293
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`Await Vercel Preview\` is still commented (bkit-stub:vercel-await sentinel present).`,
294
+ action:
295
+ "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.",
296
+ });
297
+ }
298
+ if (e2eEnabled && stubSentinelPresent.has("auto-force-e2e")) {
299
+ findings.push({
300
+ id: "bkit-stub-pair-e2e-without-auto-force",
301
+ severity: "advisory",
302
+ detect: `${ciRel} has \`Run E2E Tests\` enabled but \`bkit-stub:auto-force-e2e\` is still commented.`,
303
+ action:
304
+ "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.",
305
+ });
351
306
  }
352
307
 
353
308
  return findings;
@@ -410,6 +365,6 @@ export function buildDepUpdaterSetupAdvisory(cwd: string): PreflightFinding | nu
410
365
  action:
411
366
  "Copy one example and own it:\n\n" +
412
367
  ` ${UPDATER_EXAMPLE_PATHS}\n\n` +
413
- 'Use one updater, not both. To silence this advisory, set `bkit.depUpdater` to `"none"` in package.json. See .bkit/templates.md.',
368
+ 'Use one updater, not both. To silence this advisory, set `bkit.dependencies.updater` to `"none"` in package.json. See .bkit/templates.md.',
414
369
  };
415
370
  }
@@ -19,7 +19,7 @@ const TRACKER_TOKENS: Partial<Record<IssueTracker, { key: string; description: s
19
19
  "Linear personal API key for the Linear MCP server and the Linear preflight hook (generate at https://linear.app/settings/api)",
20
20
  },
21
21
  jira: {
22
- key: "BKIT_JIRA_API_TOKEN",
22
+ key: "BKIT_JIRA_API_KEY",
23
23
  description:
24
24
  '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)',
25
25
  },
@@ -37,7 +37,7 @@ function tokenKeys(tracker: IssueTracker): string[] {
37
37
  * copied it to .bkit/.env and filled in their tokens.
38
38
  */
39
39
  // `tracker` adds its own token to the token prose (`TRACKER_TOKENS`). Defaults to
40
- // `linear`; the real Phase-3 caller passes the consumer's resolved `bkit.issueTracker`.
40
+ // `linear`; the real Phase-3 caller passes the consumer's resolved `bkit.tracker.default`.
41
41
  export function detectMissingDotenv(
42
42
  cwd: string,
43
43
  tracker: IssueTracker = "linear",
@@ -8,6 +8,7 @@ import { extractManagedBlock, stripManagedBlock } from "../../install/managed-bl
8
8
  import { readTemplate } from "../../render/parts.js";
9
9
  import { findTemplateSource, getPkgRoot } from "../../shared/package-roots.js";
10
10
  import { parseJson } from "../../shared/json.js";
11
+ import { ciWorkflowPath } from "../../shared/settings.js";
11
12
  import type { PreflightFinding } from "./index.js";
12
13
 
13
14
  /**
@@ -77,11 +78,12 @@ export function detectGitignoreBlockDuplicates(cwd: string): PreflightFinding |
77
78
  * surfaces — pure cost (artifact upload + storage) with zero diagnostic payoff.
78
79
  *
79
80
  * "Hostile" gap per the BAR-224 signal-vs-noise classification. Reads the consumer's
80
- * own bkit-ci.yml, active lines only: YAML comment lines are dropped first, so a commented
81
+ * own CI workflow (`bkit.testing.ciWorkflow`, default `bkit-ci.yml`), active lines only: YAML comment lines are dropped first, so a commented
81
82
  * template stub or a commented-out example never fires.
82
83
  */
83
84
  export function detectPlaywrightReporterHostile(cwd: string): PreflightFinding | null {
84
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
85
+ const ciRel = ciWorkflowPath(cwd);
86
+ const ciPath = path.join(cwd, ciRel);
85
87
  if (!fs.existsSync(ciPath)) return null;
86
88
  const content = fs.readFileSync(ciPath, "utf-8");
87
89
  // Filter out YAML comment lines (those starting with optional whitespace + `#`) before
@@ -99,8 +101,7 @@ export function detectPlaywrightReporterHostile(cwd: string): PreflightFinding |
99
101
  return {
100
102
  id: "playwright-reporter-line-override-hostile",
101
103
  severity: "advisory",
102
- detect:
103
- ".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.",
104
+ 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.`,
104
105
  action:
105
106
  '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.',
106
107
  };
@@ -10,6 +10,7 @@
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
 
14
15
  import type { ModuleFlag } from "../../cli.js";
15
16
  import { readInstallingVersion } from "../../shared/package-json.js";
@@ -20,6 +21,10 @@ import {
20
21
  detectMalformedPackageJson,
21
22
  detectNoPackageJson,
22
23
  detectNotGitRepo,
24
+ detectInvalidAskSettings,
25
+ detectInvalidTaskCaps,
26
+ detectTaskCapFormStale,
27
+ detectUnmarkedPlans,
23
28
  } from "./repo.js";
24
29
  import {
25
30
  MARKERED_TEXT_DRIFT_PATHS,
@@ -75,7 +80,7 @@ export function dedupeById(findings: PreflightFinding[]): PreflightFinding[] {
75
80
  * installingVersion: used by detectBkitVersionMajorDowngrade; defaults to the
76
81
  * package's own version read from its package.json at runtime.
77
82
  * issueTracker: when provided, narrows tracker-specific checks (e.g. MCP server
78
- * requirements). When omitted, read from consumer's `bkit.issueTracker` in package.json.
83
+ * requirements). When omitted, read from consumer's `bkit.tracker.default` in package.json.
79
84
  *
80
85
  * GitHub tracker gate: when `issueTracker === "github"`, the Linear preflight
81
86
  * gate is a no-op — the GitHub gate is enforced by workflow Step 1 via MCP.
@@ -128,6 +133,18 @@ export function runPreflight(
128
133
  const versionPinStale = detectBkitVersionPinStale(cwd);
129
134
  if (versionPinStale) advisories.push(versionPinStale);
130
135
 
136
+ const invalidTaskCaps = detectInvalidTaskCaps(cwd);
137
+ if (invalidTaskCaps) advisories.push(invalidTaskCaps);
138
+
139
+ const taskCapFormStale = detectTaskCapFormStale(cwd);
140
+ if (taskCapFormStale) advisories.push(taskCapFormStale);
141
+
142
+ const invalidAsks = detectInvalidAskSettings(cwd);
143
+ if (invalidAsks) advisories.push(invalidAsks);
144
+
145
+ const unmarkedPlans = detectUnmarkedPlans(cwd);
146
+ if (unmarkedPlans) advisories.push(unmarkedPlans);
147
+
131
148
  // BAR-224: [verbose ci] marker advisories
132
149
 
133
150
  const playwrightReporterHostile = detectPlaywrightReporterHostile(cwd);
@@ -1,11 +1,21 @@
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
 
4
4
  import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { spawnSync } from "node:child_process";
7
7
  import type { ModuleFlag } from "../../cli.js";
8
- import { readJsonFile } from "../../shared/json.js";
8
+ import { parsePlanBlocks } from "../../commands/workflow/plan-blocks.js";
9
+ import { parseJson, readJsonFile } from "../../shared/json.js";
10
+ import {
11
+ ASK_POINTS,
12
+ CONFIG_DEFAULTS,
13
+ invalidAskSettings,
14
+ invalidTaskCaps,
15
+ limitKey,
16
+ readBkitConfig,
17
+ type TaskCaps,
18
+ } from "../../shared/settings.js";
9
19
  import type { PreflightFinding } from "./index.js";
10
20
  import { isCloudOrCi } from "./env.js";
11
21
 
@@ -49,6 +59,162 @@ export function detectNotGitRepo(cwd: string, modules: Set<ModuleFlag>): Preflig
49
59
  };
50
60
  }
51
61
 
62
+ /**
63
+ * Advisory: `package.json` `bkit.workflows.tasks` holds a plan cap that is not an integer >= 1.
64
+ * Each such key falls back to its default in `readBkitConfig`.
65
+ */
66
+ export function detectInvalidTaskCaps(cwd: string): PreflightFinding | null {
67
+ const workflows = bkitWorkflows(cwd);
68
+ if (workflows === null) return null;
69
+ const bad = invalidTaskCaps(workflows.tasks);
70
+ if (bad.length === 0) return null;
71
+ const caps = CONFIG_DEFAULTS.tasks;
72
+ const keys = bad[0] === "tasks" ? (Object.keys(caps) as (keyof typeof caps)[]) : bad;
73
+ const named = bad.map((k) => `\`bkit.workflows.${k === "tasks" ? k : `tasks.${k}`}\``).join(", ");
74
+ return {
75
+ id: "bkit-tasks-invalid",
76
+ severity: "advisory",
77
+ detect: `package.json ${named} is not a whole number of 1 or more, so the plan check uses the default instead.`,
78
+ action: `Set each to a whole number of 1 or more in package.json, or delete it to keep the default: ${keys
79
+ .map((k) => `\`bkit.workflows.tasks.${k}\` (default ${caps[k as keyof typeof caps]})`)
80
+ .join(", ")}.`,
81
+ };
82
+ }
83
+
84
+ const TASK_CAP_KEY = /`bkit\.workflows\.tasks\.(\w+)`/g;
85
+
86
+ /**
87
+ * Each `bkit.workflows.tasks.<key>` the text names with a `(default N)` after it, on the same
88
+ * line and before the next named key.
89
+ */
90
+ export function taskCapDefaultsNamed(text: string): { key: string; value: number }[] {
91
+ const hits = [...text.matchAll(TASK_CAP_KEY)];
92
+ return hits.flatMap((m, i) => {
93
+ const from = m.index + m[0].length;
94
+ const lineEnd = text.indexOf("\n", from);
95
+ const end = Math.min(hits[i + 1]?.index ?? text.length, lineEnd === -1 ? text.length : lineEnd);
96
+ const n = /\(default (\d+)\)/.exec(text.slice(from, end));
97
+ return n ? [{ key: m[1]!, value: Number(n[1]) }] : [];
98
+ });
99
+ }
100
+
101
+ const CHANGE_FORM = ".github/ISSUE_TEMPLATE/bkit-change.yml";
102
+
103
+ /**
104
+ * Advisory: the change issue form names a plan cap with a `(default N)` that differs from the
105
+ * value `readBkitConfig` gives for that key.
106
+ */
107
+ export function detectTaskCapFormStale(cwd: string): PreflightFinding | null {
108
+ const file = path.join(cwd, CHANGE_FORM);
109
+ if (!fs.existsSync(file)) return null;
110
+ const caps = readBkitConfig(cwd).tasks;
111
+ const isCap = (k: string): k is keyof TaskCaps => Object.hasOwn(caps, k);
112
+ const stale = new Map<keyof TaskCaps, number>();
113
+ for (const { key, value } of taskCapDefaultsNamed(fs.readFileSync(file, "utf-8"))) {
114
+ if (isCap(key) && caps[key] !== value) stale.set(key, value);
115
+ }
116
+ if (stale.size === 0) return null;
117
+ const rows = [...stale];
118
+ return {
119
+ id: "bkit-tasks-form-stale",
120
+ severity: "advisory",
121
+ detect: `${CHANGE_FORM} shows plan caps that differ from package.json: ${rows
122
+ .map(([k, v]) => `\`bkit.workflows.tasks.${k}\` (default ${v}) is ${caps[k]}`)
123
+ .join(", ")}.`,
124
+ action: `In ${CHANGE_FORM}, change the number in each "(default N)" after the key: ${rows
125
+ .map(([k, v]) => `\`bkit.workflows.tasks.${k}\` "(default ${v})" → "(default ${caps[k]})"`)
126
+ .join(
127
+ ", ",
128
+ )}. Or set the key in package.json \`bkit.workflows.tasks\` to the number the form shows.`,
129
+ };
130
+ }
131
+
132
+ /** `package.json` `bkit.workflows` as an object; null when the file or block is unusable. */
133
+ function bkitWorkflows(cwd: string): Record<string, unknown> | null {
134
+ const read = readJsonFile(path.join(cwd, "package.json"));
135
+ if (!read.ok) return null;
136
+ const bkit = (read.value as { bkit?: unknown } | null)?.bkit;
137
+ if (bkit === null || typeof bkit !== "object" || Array.isArray(bkit)) return null;
138
+ const workflows = (bkit as { workflows?: unknown }).workflows;
139
+ return workflows !== null && typeof workflows === "object" && !Array.isArray(workflows)
140
+ ? (workflows as Record<string, unknown>)
141
+ : {};
142
+ }
143
+
144
+ /**
145
+ * Advisory when a `bkit.workflows.<workflow>.<point>` block holds an `ask` that is not
146
+ * true/false, a limit that is not a whole number of 1 or more, or is not an object. Each such
147
+ * key falls back to its default in `readBkitConfig`.
148
+ */
149
+ export function detectInvalidAskSettings(cwd: string): PreflightFinding | null {
150
+ const workflows = bkitWorkflows(cwd);
151
+ if (workflows === null) return null;
152
+ const bad = invalidAskSettings(workflows);
153
+ if (bad.length === 0) return null;
154
+ const defaults = bad.map((k) => {
155
+ const point = ASK_POINTS.find((p) => k === p || k.startsWith(`${p}.`))!;
156
+ const d = CONFIG_DEFAULTS.asks[point];
157
+ return `\`bkit.workflows.${point}\` (default \`{ "ask": ${d.ask}, "${limitKey(point)}": ${d.max} }\`)`;
158
+ });
159
+ return {
160
+ id: "bkit-ask-settings-invalid",
161
+ severity: "advisory",
162
+ 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.`,
163
+ action: `Fix or delete each in package.json: ${[...new Set(defaults)].join(", ")}.`,
164
+ };
165
+ }
166
+
167
+ const PLAN_FILE = /^(.+)-plan\.md$/;
168
+
169
+ /** The FID's `docs/plans/{month}/logs/{FID}/status.jsonl` holds a ship `workflow-done` row. */
170
+ function fidShipped(monthDir: string, fid: string): boolean {
171
+ const file = path.join(monthDir, "logs", fid, "status.jsonl");
172
+ if (!fs.existsSync(file)) return false;
173
+ return fs
174
+ .readFileSync(file, "utf-8")
175
+ .split("\n")
176
+ .some((line) => {
177
+ const row = parseJson(line);
178
+ if (!row.ok || typeof row.value !== "object" || row.value === null) return false;
179
+ const { type, workflow } = row.value as { type?: unknown; workflow?: unknown };
180
+ return type === "workflow-done" && workflow === "ship";
181
+ });
182
+ }
183
+
184
+ /**
185
+ * Advisory: a `docs/plans/{YYYYMM}/{FID}-plan.md` whose FID has not shipped holds no task
186
+ * blocks, so `/bkit-build` Step 3 converts it on the FID's next build. `archive/` and
187
+ * `logs/` sit below the month folder and are not read.
188
+ */
189
+ export function detectUnmarkedPlans(cwd: string): PreflightFinding | null {
190
+ const plans = path.join(cwd, "docs", "plans");
191
+ if (!fs.existsSync(plans)) return null;
192
+ const unmarked: string[] = [];
193
+ for (const month of fs.readdirSync(plans, { withFileTypes: true })) {
194
+ if (!month.isDirectory()) continue;
195
+ const monthDir = path.join(plans, month.name);
196
+ for (const entry of fs.readdirSync(monthDir, { withFileTypes: true })) {
197
+ const fid = entry.isFile() ? PLAN_FILE.exec(entry.name)?.[1] : undefined;
198
+ if (fid === undefined) continue;
199
+ const text = fs.readFileSync(path.join(monthDir, entry.name), "utf-8");
200
+ if (parsePlanBlocks(text).tasks.length > 0 || fidShipped(monthDir, fid)) continue;
201
+ unmarked.push(`docs/plans/${month.name}/${entry.name}`);
202
+ }
203
+ }
204
+ if (unmarked.length === 0) return null;
205
+ unmarked.sort();
206
+ const one = unmarked.length === 1;
207
+ return {
208
+ id: "plan-task-markers-missing",
209
+ severity: "advisory",
210
+ 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
211
+ .map((p) => `\`${p}\``)
212
+ .join(", ")}.`,
213
+ action:
214
+ "Nothing to do by hand: this matters only for builds still to run, and plans of shipped FIDs are not listed.",
215
+ };
216
+ }
217
+
52
218
  /**
53
219
  * Advisory: `bkit` is not on PATH.
54
220
  * bkit is a devDependency — without a shell alias, every invocation requires