@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,16 +4,22 @@
4
4
  import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
6
  import { writeTier1, writeTier2, ensurePackageJsonScripts } from "../write.js";
7
- import { readBkitVersion, writeBkitVersion, hashFile, mergeCanonicalHashes, } from "../version-file.js";
8
- import { extractManagedBlock, stripManagedBlock } from "../managed-block.js";
7
+ import { readBkitVersion, writeBkitVersion, hashFile, mergeCanonicalHashes, sha256, } from "../version-file.js";
8
+ import { extractManagedBlock, findLineAnchoredMarkers, selectMarkers, stripManagedBlock, } from "../managed-block.js";
9
9
  import { listFilesRecursive, syncTemplateCopies } from "../template-copies.js";
10
10
  import { PAYLOAD_LINK_RELPATHS, syncPayloadLinks } from "../payload-links.js";
11
11
  import { writeNetworkAllowlist } from "../network-allowlist.js";
12
+ import { migrateContextCiWorkflow } from "../context-ci-workflow.js";
13
+ import { migrateTemplateNotes } from "../template-notes.js";
14
+ import { isAdvisorySuppressed } from "../../checks/after/suppression.js";
12
15
  import { parseJson, readJsonFile } from "../../shared/json.js";
13
16
  import { readInstallingVersion } from "../../shared/package-json.js";
14
- import { CONFIG_DEFAULTS } from "../../shared/settings.js";
15
- import { getCoreRoot, getSharedRoot, getBkitDocsRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
16
- import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_PUSH_GATES, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
17
+ import { detectDepUpdater } from "../../shared/dep-updater.js";
18
+ import { ASK_POINTS, CONFIG_DEFAULTS, ciWorkflowPath, limitKey } from "../../shared/settings.js";
19
+ import { CI_SCRIPT_UNITS } from "../../checks/after/ci-yml.js";
20
+ import { getCoreRoot, getSharedRoot, getBkitDocsRoot, getTemplatesRoot, TEMPLATE_COPIES_DIR, } from "../../shared/package-roots.js";
21
+ import { getInstallManifest, BKIT_GATE_SCRIPTS, BKIT_OPTIONAL_GATES, BKIT_PUSH_GATES, BKIT_GATE_CHANGED_SCRIPT, BKIT_LINT_FILE_SCRIPT, BKIT_TEST_FILE_SCRIPT, } from "../manifest.js";
22
+ import { migrateLedgers } from "../../ledgers/migrate.js";
17
23
  export function listMdFiles(dir, prefix) {
18
24
  if (!fs.existsSync(dir))
19
25
  return [];
@@ -184,24 +190,37 @@ function runCoreTemplates(dryRun, tokens, ws, logPrefix) {
184
190
  // in-repo without spelunking node_modules. Force-overwritten (Tier 1) — bkit owns
185
191
  // them, so a consumer edit is replaced. Source of truth is the package's own
186
192
  // `.bkit/core/.bkit/<name>`. (`advisories.md` is a regenerated runtime artifact and
187
- // `wording.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
193
+ // `instructions.md` is repo-only tooling — neither belongs here. `LICENSE.md` is the MIT
188
194
  // notice that travels with the files bkit writes: MIT requires the copyright and
189
195
  // permission notice in every copy.)
190
196
  export const BKIT_CANONICAL_DOCS = [
197
+ "authoring.md",
191
198
  "cloud.md",
199
+ "cli.md",
192
200
  "comparison.md",
193
201
  "install.md",
194
202
  "jsonl.md",
195
203
  "LICENSE.md",
196
- "lite.md",
197
204
  "pipeline.md",
198
205
  "providers.md",
199
206
  "prompts.md",
207
+ "router.md",
200
208
  "templates.md",
201
209
  "trackers.md",
202
210
  "workflows.md",
203
211
  "README.md",
204
212
  ];
213
+ // The token map for `.bkit/*.md` docs: only `{{BKIT_MANAGED_MARKER}}` resolves. The other
214
+ // tokens map to themselves, so a doc that tells the consumer which token to replace in a
215
+ // template (`templates.md`) still names the token.
216
+ export function bkitDocTokens(tokens) {
217
+ return {
218
+ ...tokens,
219
+ DEFAULT_BRANCH: "{{DEFAULT_BRANCH}}",
220
+ PROJECT_NAME: "{{PROJECT_NAME}}",
221
+ REPO_SLUG: "{{REPO_SLUG}}",
222
+ };
223
+ }
205
224
  // Mirror the package's canonical `.bkit/*.md` docs into the consumer's `.bkit/`.
206
225
  // Tier 1 (force-overwrite + ws-tracked for dry-run/install parity). Each source carries
207
226
  // the `{{BKIT_MANAGED_MARKER}}` token. Skipped in dogfood: the consumer destination
@@ -209,6 +228,7 @@ export const BKIT_CANONICAL_DOCS = [
209
228
  export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
210
229
  const tag = dryRun ? "[dry-run] " : "";
211
230
  const docsRoot = getBkitDocsRoot();
231
+ const docTokens = bkitDocTokens(tokens);
212
232
  // Per-doc write strategy from the manifest: markered-text docs (e.g. prompts.md,
213
233
  // which carries the consumer-owned `## Model Overrides` section below `bkit:end`)
214
234
  // are block-merged so consumer content survives; the rest are force-overwritten.
@@ -222,53 +242,168 @@ export function runBkitDocs(dryRun, tokens, ws, logPrefix) {
222
242
  const dstPath = path.join(".bkit", name);
223
243
  const prevLen = ws.writes.length;
224
244
  if (formatByPath.get(path.join(".bkit", name)) === "markered-text") {
225
- writeTier2(srcPath, dstPath, tokens, "html-comment", dryRun, ws);
245
+ writeTier2(srcPath, dstPath, docTokens, "html-comment", dryRun, ws);
226
246
  }
227
247
  else {
228
- writeTier1(srcPath, dstPath, tokens, dryRun, ws);
248
+ writeTier1(srcPath, dstPath, docTokens, dryRun, ws);
229
249
  }
230
250
  if (ws.writes.length > prevLen) {
231
251
  console.log(`${logPrefix} ${tag}core: ${dstPath}`);
232
252
  }
233
253
  }
234
- migrateShortcutsToLite(dryRun, ws, logPrefix);
254
+ migrateRetiredLite(dryRun, ws, logPrefix);
235
255
  migrateRetiredDevLock(dryRun, ws, logPrefix);
256
+ migrateLedgerSchema(dryRun, ws, logPrefix);
257
+ migrateJiraKeyName(dryRun, logPrefix);
258
+ migrateModelOverrideAgentNames(dryRun, ws, logPrefix);
259
+ migrateTemplateNotes(dryRun, ws, logPrefix);
260
+ migrateContextCiWorkflow(dryRun, ws, logPrefix);
261
+ migrateSlopTypeSuppression(dryRun, ws, logPrefix);
262
+ const renames = migrateBrandedTemplateFiles(dryRun, ws, logPrefix);
263
+ migrateBrandedFileTokens(dryRun, ws, logPrefix, renames);
264
+ migrateBrandedCheckNames(dryRun, ws, logPrefix, tokens.DEFAULT_BRANCH);
265
+ migrateValeHouseStyle(dryRun, ws, logPrefix);
236
266
  }
237
- // Migration (5.1.0 – 5.2.4 installs, `docs/migrations.md`): the lite workflows lived at
238
- // `.agents/shortcuts.md`. The consumer's own lines below `bkit:end` (minus the seeded
239
- // heading) move under `.bkit/lite.md`'s consumer section; the old file is deleted. Runs
240
- // after the docs loop, so `.bkit/lite.md` is already written. The delete is recorded in
241
- // ws (as orphan-mirror deletes are) so `bkit check` fails until upgrade runs.
242
- const RETIRED_SHORTCUTS = path.join(".agents", "shortcuts.md");
243
- const RETIRED_SHORTCUTS_HEADING = "## Project Shortcuts";
244
- export function migrateShortcutsToLite(dryRun, ws, logPrefix) {
245
- if (!fs.existsSync(RETIRED_SHORTCUTS))
267
+ // Migration (installs up to 6.0.x, `docs/migrations.md`): agents renamed since. A
268
+ // consumer's `## Model Overrides` row below `bkit:end` in `.bkit/prompts.md` naming an
269
+ // old agent is renamed in place, provider and model kept, so the override keeps applying
270
+ // (`parseModelOverrides` reports a row naming no agent as unknown and skips it). Runs
271
+ // after the docs loop, which block-merges the file and leaves the consumer region alone.
272
+ // A row already naming the new agent wins: the old row is then left for the unknown
273
+ // report. Recorded in ws as an update; the canonical hash covers the managed block only.
274
+ const PROMPTS_FILE = path.join(".bkit", "prompts.md");
275
+ const MODEL_OVERRIDES_HEADING = "## Model Overrides";
276
+ export const RENAMED_AGENTS = {
277
+ "bkit-build-plan-execute": "bkit-build-plan-tasks",
278
+ };
279
+ export function migrateModelOverrideAgentNames(dryRun, ws, logPrefix) {
280
+ if (!fs.existsSync(PROMPTS_FILE))
246
281
  return;
247
- if (!fs.existsSync(path.join(getBkitDocsRoot(), "lite.md")))
282
+ const text = fs.readFileSync(PROMPTS_FILE, "utf-8");
283
+ const endIdx = findLineAnchoredMarkers(text, selectMarkers("html-comment")[1])[0];
284
+ if (endIdx === undefined)
248
285
  return;
249
- const tag = dryRun ? "[dry-run] " : "";
250
- const dst = path.join(".bkit", "lite.md");
251
- const old = fs.readFileSync(RETIRED_SHORTCUTS, "utf-8");
252
- if (extractManagedBlock(old, "html-comment") === null) {
253
- console.warn(`${logPrefix} ${RETIRED_SHORTCUTS} has no single bkit managed block — left in place. Move your own lines into ${dst} below \`<!-- bkit:end -->\`, then delete it.`);
286
+ const headingAt = text.indexOf(MODEL_OVERRIDES_HEADING, endIdx);
287
+ if (headingAt === -1)
254
288
  return;
255
- }
256
- const own = stripManagedBlock(old, "html-comment")
257
- .split("\n")
258
- .filter((line) => line.trim() !== RETIRED_SHORTCUTS_HEADING)
289
+ const head = text.slice(0, headingAt);
290
+ const lines = text.slice(headingAt).split("\n");
291
+ // The first cell of a table row, backticks and padding aside.
292
+ const promptCell = (line) => /^\s*\|/.test(line) ? line.split("|")[1]?.trim().replace(/^`|`$/g, "") : undefined;
293
+ const named = new Set(lines.map(promptCell).filter((c) => c !== undefined));
294
+ const renamed = [];
295
+ const out = lines.map((line) => {
296
+ const cell = promptCell(line);
297
+ const to = cell === undefined ? undefined : RENAMED_AGENTS[cell];
298
+ if (cell === undefined || to === undefined || named.has(to))
299
+ return line;
300
+ renamed.push(`${cell} -> ${to}`);
301
+ return line.replace(cell, to);
302
+ });
303
+ if (renamed.length === 0)
304
+ return;
305
+ if (!dryRun)
306
+ fs.writeFileSync(PROMPTS_FILE, head + out.join("\n"), "utf-8");
307
+ ws.writes.push({ path: PROMPTS_FILE, action: "update" });
308
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${PROMPTS_FILE} — Model Overrides renamed: ${renamed.join(", ")}`);
309
+ }
310
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): the Jira key was
311
+ // `BKIT_JIRA_API_TOKEN`; the engine and the MCP configs now read `BKIT_JIRA_API_KEY`.
312
+ // `.bkit/.env` lines naming the old key are renamed in place, value kept. Logged only,
313
+ // never recorded in ws: a ws write gets a canonical hash, and a secrets file never does.
314
+ // A file already naming the new key is left alone.
315
+ const ENV_FILE = path.join(".bkit", ".env");
316
+ const OLD_JIRA_KEY = "BKIT_JIRA_API_TOKEN";
317
+ const NEW_JIRA_KEY = "BKIT_JIRA_API_KEY";
318
+ export function migrateJiraKeyName(dryRun, logPrefix) {
319
+ if (!fs.lstatSync(ENV_FILE, { throwIfNoEntry: false })?.isFile())
320
+ return;
321
+ const text = fs.readFileSync(ENV_FILE, "utf-8");
322
+ const assigns = (key) => new RegExp(`^\\s*(export\\s+)?${key}=`, "m").test(text);
323
+ if (!assigns(OLD_JIRA_KEY) || assigns(NEW_JIRA_KEY))
324
+ return;
325
+ if (!dryRun)
326
+ fs.writeFileSync(ENV_FILE, text.split(OLD_JIRA_KEY).join(NEW_JIRA_KEY), "utf-8");
327
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${ENV_FILE} — ${OLD_JIRA_KEY} renamed to ${NEW_JIRA_KEY}`);
328
+ }
329
+ // Migration (5.1.0 – 6.0.x installs, `docs/migrations.md`): the lite workflows are retired.
330
+ // The managed block of `.bkit/lite.md` (and of its 5.1.0 – 5.2.4 predecessor
331
+ // `.agents/shortcuts.md`) is stripped; the consumer's own lines (minus the seeded headings)
332
+ // land in `.bkit/lite.md` under a sentinel first line, or the file is deleted when none
333
+ // remain. A file holding the sentinel and no managed block is the already-retired stub:
334
+ // silent, no write. A blockless or multi-block `.bkit/lite.md` is left byte-for-byte with
335
+ // a logged fix. Writes are recorded in ws (dry-run parity; `bkit check` fails until upgrade).
336
+ export const RETIRED_LITE_STUB_SENTINEL = "<!-- bkit:retired-lite-stub -->";
337
+ const RETIRED_SHORTCUTS = path.join(".agents", "shortcuts.md");
338
+ const RETIRED_SHORTCUTS_HEADING = "## Project Shortcuts";
339
+ const RETIRED_LITE = path.join(".bkit", "lite.md");
340
+ const RETIRED_LITE_HEADING = "## Project Lite Workflows";
341
+ /** The consumer lines left once the managed block and the given seeded heading are removed. */
342
+ function consumerLines(text, heading) {
343
+ const lines = stripManagedBlock(text, "html-comment").split("\n");
344
+ return lines
345
+ .filter((line) => line.trim() !== heading)
259
346
  .join("\n")
260
347
  .trim();
261
- if (own.length > 0) {
262
- if (!dryRun) {
263
- const current = fs.readFileSync(dst, "utf-8");
264
- fs.writeFileSync(dst, `${current.replace(/\n*$/, "\n\n")}${own}\n`, "utf-8");
348
+ }
349
+ export function migrateRetiredLite(dryRun, ws, logPrefix) {
350
+ const hasShortcuts = fs.existsSync(RETIRED_SHORTCUTS);
351
+ const hasLite = fs.existsSync(RETIRED_LITE);
352
+ if (!hasShortcuts && !hasLite)
353
+ return;
354
+ const tag = dryRun ? "[dry-run] " : "";
355
+ let liteOwn = "";
356
+ let liteIsManaged = false;
357
+ if (hasLite) {
358
+ const lite = fs.readFileSync(RETIRED_LITE, "utf-8");
359
+ if (extractManagedBlock(lite, "html-comment") !== null) {
360
+ liteIsManaged = true;
361
+ liteOwn = consumerLines(lite, RETIRED_LITE_HEADING);
362
+ }
363
+ else if (lite.split("\n")[0]?.trim() === RETIRED_LITE_STUB_SENTINEL) {
364
+ liteOwn = lite.slice(lite.indexOf("\n") + 1).trim();
365
+ }
366
+ else {
367
+ console.warn(`${logPrefix} ${RETIRED_LITE} has no single bkit managed block — left in place. The lite workflows are retired: keep your own lines in it (or in your own docs) and delete any leftover bkit-managed text.`);
368
+ return;
265
369
  }
266
- ws.writes.push({ path: dst, action: "update" });
267
370
  }
268
- if (!dryRun)
269
- fs.rmSync(RETIRED_SHORTCUTS);
270
- ws.writes.push({ path: RETIRED_SHORTCUTS, action: "write" });
271
- console.log(`${logPrefix} ${tag}core: moved ${RETIRED_SHORTCUTS} → ${dst}`);
371
+ let shortcutsOwn = "";
372
+ let shortcutsMovable = false;
373
+ if (hasShortcuts) {
374
+ const old = fs.readFileSync(RETIRED_SHORTCUTS, "utf-8");
375
+ if (extractManagedBlock(old, "html-comment") === null) {
376
+ console.warn(`${logPrefix} ${RETIRED_SHORTCUTS} has no single bkit managed block — left in place. Move your own lines into ${RETIRED_LITE}, then delete it.`);
377
+ }
378
+ else {
379
+ shortcutsMovable = true;
380
+ shortcutsOwn = consumerLines(old, RETIRED_SHORTCUTS_HEADING);
381
+ }
382
+ }
383
+ const own = [liteOwn, shortcutsOwn].filter((part) => part.length > 0).join("\n\n");
384
+ const stubText = `${RETIRED_LITE_STUB_SENTINEL}\n\n${own}\n`;
385
+ const liteChanges = liteIsManaged || (own.length > 0 && shortcutsOwn.length > 0);
386
+ if (liteChanges) {
387
+ if (own.length > 0) {
388
+ if (!dryRun) {
389
+ fs.mkdirSync(path.dirname(RETIRED_LITE), { recursive: true });
390
+ fs.writeFileSync(RETIRED_LITE, stubText, "utf-8");
391
+ }
392
+ ws.writes.push({ path: RETIRED_LITE, action: hasLite ? "update" : "write" });
393
+ }
394
+ else if (hasLite) {
395
+ if (!dryRun)
396
+ fs.rmSync(RETIRED_LITE);
397
+ ws.writes.push({ path: RETIRED_LITE, action: "write" });
398
+ }
399
+ console.log(`${logPrefix} ${tag}core: retired ${RETIRED_LITE}`);
400
+ }
401
+ if (shortcutsMovable) {
402
+ if (!dryRun)
403
+ fs.rmSync(RETIRED_SHORTCUTS);
404
+ ws.writes.push({ path: RETIRED_SHORTCUTS, action: "write" });
405
+ console.log(`${logPrefix} ${tag}core: retired ${RETIRED_SHORTCUTS}`);
406
+ }
272
407
  }
273
408
  // Migration (installs up to 5.3.x, `docs/migrations.md`): `.bkit/.dev.lock` was the
274
409
  // repo-wide dev lock. Nothing reads it now, so one a crashed run left behind is deleted.
@@ -282,6 +417,17 @@ export function migrateRetiredDevLock(dryRun, ws, logPrefix) {
282
417
  ws.writes.push({ path: RETIRED_DEV_LOCK, action: "write" });
283
418
  console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: removed ${RETIRED_DEV_LOCK} (the dev lock is gone)`);
284
419
  }
420
+ // Migration (installs up to 5.5.x, `docs/migrations.md`): ledger rows written before
421
+ // `schema: 2` are rewritten into the current shape (`.bkit/jsonl.md` § Generic Fields).
422
+ // Recorded in ws so `bkit check` fails until upgrade runs; ledgers never get a
423
+ // canonical hash (`mergeCanonicalHashes`).
424
+ export function migrateLedgerSchema(dryRun, ws, logPrefix) {
425
+ for (const { file, rewritten, dropped } of migrateLedgers(process.cwd(), dryRun)) {
426
+ ws.writes.push({ path: file, action: "update" });
427
+ const copies = dropped > 0 ? `, ${dropped} old copy(ies) of rewritten rows dropped` : "";
428
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: ${file} — ${rewritten} row(s) rewritten to schema 2${copies}`);
429
+ }
430
+ }
285
431
  // ---------------------------------------------------------------------------
286
432
  // Source-rendered host outputs — agents (.agents/prompts source) and commands
287
433
  // (.bkit/workflows source). Extracted from the host module functions so BOTH
@@ -311,10 +457,13 @@ export function seedCorePackageJsonScripts(ctx) {
311
457
  const { dryRun, ws, logPrefix } = ctx;
312
458
  const tag = dryRun ? "[dry-run] " : "";
313
459
  const written = [];
460
+ if (migrateBrandedScriptNames(dryRun, ws, logPrefix))
461
+ written.push("package.json");
314
462
  const gates = ensurePackageJsonScripts({ ...BKIT_GATE_SCRIPTS }, dryRun, ws);
315
463
  if (gates.added.length > 0) {
316
- written.push("package.json");
317
- console.log(`${logPrefix} ${tag}core: package.json scripts added [${gates.added.join(", ")}]`);
464
+ if (!written.includes("package.json"))
465
+ written.push("package.json");
466
+ console.log(`${logPrefix} ${tag}core: package.json scripts added [${gates.added.join(", ")}] — what a gate may run: .bkit/workflows.md § Local gate scripts`);
318
467
  }
319
468
  if (migrateLinearTeamKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
320
469
  written.push("package.json");
@@ -322,8 +471,143 @@ export function seedCorePackageJsonScripts(ctx) {
322
471
  if (migrateGithubProjectKey(dryRun, ws, logPrefix) && !written.includes("package.json")) {
323
472
  written.push("package.json");
324
473
  }
474
+ if (migrateBkitLayout(dryRun, ws, logPrefix) && !written.includes("package.json")) {
475
+ written.push("package.json");
476
+ }
477
+ if (pruneMinPushPaths(dryRun, ws, logPrefix) && !written.includes("package.json")) {
478
+ written.push("package.json");
479
+ }
480
+ if (seedBkitDefaults(dryRun, ws, logPrefix) && !written.includes("package.json")) {
481
+ written.push("package.json");
482
+ }
325
483
  return written;
326
484
  }
485
+ /**
486
+ * Every `bkit.*` setting, written on every install and upgrade so consumers see them all;
487
+ * add-if-missing, nested blocks included. A key with a default gets it; a choice not made
488
+ * yet is `""` or `[]`, which every reader treats as unset. `dependencies.updater` is the one
489
+ * choice install makes: `seedBkitDefaults` fills it from the updater config present.
490
+ */
491
+ export const SEEDED_BKIT_DEFAULTS = {
492
+ tracker: {
493
+ default: "",
494
+ github: {
495
+ project: "",
496
+ progress: CONFIG_DEFAULTS.github.progress,
497
+ review: CONFIG_DEFAULTS.github.review,
498
+ },
499
+ linear: {
500
+ team: "",
501
+ project: "",
502
+ progress: CONFIG_DEFAULTS.linear.progress,
503
+ review: CONFIG_DEFAULTS.linear.review,
504
+ },
505
+ jira: {
506
+ site: "",
507
+ project: "",
508
+ progress: CONFIG_DEFAULTS.jira.progress,
509
+ review: CONFIG_DEFAULTS.jira.review,
510
+ },
511
+ },
512
+ cloud: { agent: "" },
513
+ providers: { opencode: { default: "", installed: [] } },
514
+ testing: {
515
+ // What bkit writes (ship's bookkeeping allow-list, the plans tree) is always a min push;
516
+ // the seed adds nothing, because a project doc can be a test's input.
517
+ minPushPaths: [...CONFIG_DEFAULTS.minPushPaths],
518
+ ciWorkflow: CONFIG_DEFAULTS.ciWorkflow,
519
+ ciCapstone: CONFIG_DEFAULTS.capstoneJob,
520
+ ciRequired: [...CONFIG_DEFAULTS.ciRequired],
521
+ // Project docs ship's [skip ci] bookkeeping commit may carry onto the PR untested; a
522
+ // repo names its own (bkit's: CHANGELOG.md, README.md), so the seed is the empty choice.
523
+ ciSkipPaths: [...CONFIG_DEFAULTS.ciSkipPaths],
524
+ // CI steps whose failure bkit:generate fixes, beyond the floor bkit's own template
525
+ // steps form (CI_GENERATED_FLOOR); a repo names its own, so the seed is the empty choice.
526
+ ciGenerated: [...CONFIG_DEFAULTS.ciGenerated],
527
+ },
528
+ workflows: {
529
+ minFreeGb: CONFIG_DEFAULTS.diskMinFreeGb,
530
+ worktree: { copy: [...CONFIG_DEFAULTS.worktreeCopy], install: CONFIG_DEFAULTS.worktreeInstall },
531
+ tasks: { ...CONFIG_DEFAULTS.tasks },
532
+ ...withBuildPublish(askBlocks()),
533
+ },
534
+ // bkit-utility-update-roadmap list length; the prompt falls back to 25 too.
535
+ prompts: { roadmapNext: 25 },
536
+ dependencies: { updater: "" },
537
+ advisories: { ignore: [] },
538
+ };
539
+ /** `{design: {grill: {ask, maxTurns}}, build: {...}, ...}`, from `CONFIG_DEFAULTS.asks`. */
540
+ function askBlocks() {
541
+ const out = {};
542
+ for (const point of ASK_POINTS) {
543
+ const [workflow, name] = point.split(".");
544
+ const d = CONFIG_DEFAULTS.asks[point];
545
+ (out[workflow] ??= {})[name] = { ask: d.ask, [limitKey(point)]: d.max };
546
+ }
547
+ return out;
548
+ }
549
+ /** Merge the `build.publish` choice beside the build ask blocks. */
550
+ function withBuildPublish(blocks) {
551
+ return { ...blocks, build: { ...blocks.build, publish: { remote: true, local: true } } };
552
+ }
553
+ const plainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
554
+ // Copy each `defaults` key missing from `target`, descending into blocks both sides hold.
555
+ // A present key keeps its value, whatever it is. Pushes each added key's dotted path.
556
+ function addMissingKeys(target, defaults, prefix, added) {
557
+ for (const [k, v] of Object.entries(defaults)) {
558
+ if (!Object.prototype.hasOwnProperty.call(target, k)) {
559
+ target[k] = structuredClone(v);
560
+ added.push(`${prefix}${k}`);
561
+ }
562
+ else if (plainObject(v) && plainObject(target[k])) {
563
+ addMissingKeys(target[k], v, `${prefix}${k}.`, added);
564
+ }
565
+ }
566
+ }
567
+ // Add each SEEDED_BKIT_DEFAULTS key missing from `package.json` `bkit`, creating the block
568
+ // when absent. Runs after the legacy-key migrations, which test `=== undefined`. Returns
569
+ // true when package.json changed.
570
+ export function seedBkitDefaults(dryRun, ws, logPrefix) {
571
+ const pkgPath = "package.json";
572
+ if (!fs.existsSync(pkgPath))
573
+ return false;
574
+ const raw = fs.readFileSync(pkgPath, "utf-8");
575
+ const parsed = parseJson(raw);
576
+ if (!parsed.ok)
577
+ return false;
578
+ const pkg = parsed.value;
579
+ if (pkg.bkit !== undefined && !plainObject(pkg.bkit))
580
+ return false;
581
+ const cfg = (pkg.bkit ?? {});
582
+ const added = [];
583
+ addMissingKeys(cfg, SEEDED_BKIT_DEFAULTS, "bkit.", added);
584
+ const updater = fillDepUpdater(cfg);
585
+ if (added.length === 0 && !updater)
586
+ return false;
587
+ pkg.bkit = cfg;
588
+ ws.writes.push({ path: pkgPath, action: "update" });
589
+ if (!dryRun)
590
+ writePackageJsonLike(raw, pkg);
591
+ const dry = dryRun ? "[dry-run] " : "";
592
+ if (added.length > 0) {
593
+ console.log(`${logPrefix} ${dry}core: added ${added.join(", ")} to package.json`);
594
+ }
595
+ if (updater) {
596
+ console.log(`${logPrefix} ${dry}core: set bkit.dependencies.updater to "${updater}" (its config is present)`);
597
+ }
598
+ return true;
599
+ }
600
+ // An empty `dependencies.updater` takes the one updater whose config is present; a set value
601
+ // stays. Returns the updater written, else null.
602
+ function fillDepUpdater(cfg) {
603
+ const deps = cfg.dependencies;
604
+ if (!plainObject(deps) || deps.updater !== "")
605
+ return null;
606
+ const found = detectDepUpdater(".");
607
+ if (found)
608
+ deps.updater = found;
609
+ return found;
610
+ }
327
611
  /** Rewrite package.json with `pkg`, keeping the file's indent and trailing newline. */
328
612
  function writePackageJsonLike(raw, pkg) {
329
613
  const indentMatch = raw.match(/\n([ \t]+)"/);
@@ -331,6 +615,582 @@ function writePackageJsonLike(raw, pkg) {
331
615
  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
332
616
  fs.writeFileSync("package.json", JSON.stringify(pkg, null, indent) + trailingNewline, "utf-8");
333
617
  }
618
+ // Migration (up to 6.0.x installs, `docs/migrations.md`): the package.json scripts bkit runs
619
+ // carry the `bkit:` prefix. Old name -> new name. A `graph*` key moves only when its value
620
+ // runs bkit's graph scripts; any other `graph*` script is the consumer's own.
621
+ export const BKIT_SCRIPT_RENAMES = {
622
+ "lint:prose": "bkit:lint:prose",
623
+ "slop:delta": "bkit:slop:delta",
624
+ graph: "bkit:graph",
625
+ ...Object.fromEntries(["check", "clean", "graphml", "refresh", "rollup", "scoped", "tree", "update"].map((verb) => [
626
+ `graph:${verb}`,
627
+ `bkit:graph:${verb}`,
628
+ ])),
629
+ };
630
+ const GRAPH_VALUE_GUARD = "scripts/graphify/bkit-";
631
+ // The pairs a migration acts on. A pair is inactive when `package.json` holds both keys, or
632
+ // when the old key is a `graph*` script whose value is not bkit's; a pair with neither key
633
+ // is active, so its tokens in other values and in default gate chains are rewritten.
634
+ function activeScriptRenames(scripts, renames) {
635
+ const has = (k) => Object.prototype.hasOwnProperty.call(scripts, k);
636
+ const active = {};
637
+ const bothPresent = [];
638
+ for (const [oldName, newName] of Object.entries(renames)) {
639
+ if (has(oldName) && has(newName)) {
640
+ bothPresent.push(oldName);
641
+ continue;
642
+ }
643
+ const value = scripts[oldName];
644
+ if (has(oldName) &&
645
+ oldName.startsWith("graph") &&
646
+ !(typeof value === "string" && value.includes(GRAPH_VALUE_GUARD))) {
647
+ continue;
648
+ }
649
+ active[oldName] = newName;
650
+ }
651
+ return { active, bothPresent };
652
+ }
653
+ function isLink(p) {
654
+ return fs.lstatSync(p, { throwIfNoEntry: false })?.isSymbolicLink() === true;
655
+ }
656
+ // True when `p` or any directory above it (within the relative path) is a symlink.
657
+ function linkedPath(p) {
658
+ const parts = path.normalize(p).split(path.sep);
659
+ for (let i = 1; i <= parts.length; i++) {
660
+ if (isLink(parts.slice(0, i).join(path.sep)))
661
+ return true;
662
+ }
663
+ return false;
664
+ }
665
+ // Exact v6.0.0 template bytes, also present immediately before 22d6b75f3.
666
+ const RETIRED_SLOP_PLUGIN_HASH = "3748c27577fb384118c4754378038e3d68d087c28fb314a85b7d427f6093292d";
667
+ // Migration (up to 6.0.x installs, docs/migrations.md): replace the shipped slop plugin
668
+ // that reports inert skip text. The copy stays consumer-owned; edited copies need a merge.
669
+ function migrateSlopTypeSuppression(dryRun, ws, logPrefix) {
670
+ const file = path.join("scripts", "slop", "bkit-slop-type-suppression.mjs");
671
+ const stat = fs.lstatSync(file, { throwIfNoEntry: false });
672
+ if (!stat)
673
+ return;
674
+ const tag = dryRun ? "[dry-run] " : "";
675
+ const manual = (reason) => {
676
+ console.warn(`${logPrefix} ${tag}core: ${file} left unchanged (${reason}); merge the corrected .bkit/templates/${file} by hand to avoid false skip/focus findings in inert text`);
677
+ };
678
+ if (linkedPath(file) || !stat.isFile()) {
679
+ manual("the path is not a regular file or sits under a symlink");
680
+ return;
681
+ }
682
+ const current = fs.readFileSync(file);
683
+ const template = fs.readFileSync(path.join(getTemplatesRoot(), file));
684
+ if (current.equals(template))
685
+ return;
686
+ if (sha256(current) !== RETIRED_SLOP_PLUGIN_HASH) {
687
+ manual("the copy differs from the shipped version");
688
+ return;
689
+ }
690
+ if (!dryRun)
691
+ fs.writeFileSync(file, template);
692
+ ws.writes.push({ path: file, action: "update", unhashed: true });
693
+ console.log(`${logPrefix} ${tag}core: ${file} — slop plugin updated`);
694
+ }
695
+ // Every `.github/workflows/*.yml` / `*.yaml` regular file outside `skip`.
696
+ function otherWorkflows(skip) {
697
+ const dir = path.join(".github", "workflows");
698
+ if (!fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory())
699
+ return [];
700
+ const skipped = new Set(skip.map((f) => path.normalize(f)));
701
+ return fs
702
+ .readdirSync(dir)
703
+ .filter((f) => /\.ya?ml$/.test(f))
704
+ .map((f) => path.join(dir, f))
705
+ .filter((f) => !skipped.has(f) && fs.lstatSync(f).isFile());
706
+ }
707
+ // Every regular `action.yml` / `action.yaml` file under `.github/actions/`, at any depth.
708
+ function compositeActions() {
709
+ const dir = path.join(".github", "actions");
710
+ if (!fs.lstatSync(dir, { throwIfNoEntry: false })?.isDirectory())
711
+ return [];
712
+ const walk = (d) => fs.readdirSync(d).flatMap((f) => {
713
+ const p = path.join(d, f);
714
+ const st = fs.lstatSync(p);
715
+ if (st.isDirectory())
716
+ return walk(p);
717
+ return st.isFile() && /^action\.ya?ml$/.test(f) ? [p] : [];
718
+ });
719
+ return walk(dir);
720
+ }
721
+ function escapeRegExp(text) {
722
+ return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
723
+ }
724
+ /**
725
+ * Rewrites `pnpm [flags] [run] [flags] <old>` to the new name, keeping the flags and `run`.
726
+ * Each flag is a value-less `-x` / `--x[=v]` token, except the package selectors (`-F`, `-C`,
727
+ * `-r`, `--recursive`, `--filter`, `--dir`, `--prefix`), which leave the call alone; `<old>` ends at a character outside
728
+ * `[\w:-]` or at the end of the text. Anything else (`npm run`, `echo`, `--filter web`) stays.
729
+ */
730
+ export function renameScriptTokens(text, renames) {
731
+ const names = Object.keys(renames).sort((a, b) => b.length - a.length);
732
+ if (names.length === 0)
733
+ return text;
734
+ const re = new RegExp(`\\bpnpm((?:\\s+(?:run|(?!-(?:F|C|r|-filter|-dir|-prefix|-recursive))--?\\w[\\w-]*(?:=\\S*)?))*)(\\s+)(${names.map(escapeRegExp).join("|")})(?![\\w:-])`, "g");
735
+ return text.replace(re, (_m, flags, gap, old) => `pnpm${flags}${gap}${renames[old]}`);
736
+ }
737
+ /**
738
+ * Each old script name still in `text`, with its 1-based line. A name without `:` (`graph`) is
739
+ * a plain word, so it counts only after `pnpm` / `npm` / `yarn` / `bun` on the same line and
740
+ * before any `#`.
741
+ */
742
+ export function findOldScriptNames(text, renames) {
743
+ const found = [];
744
+ const lines = text.split("\n");
745
+ for (const name of Object.keys(renames)) {
746
+ const re = name.includes(":")
747
+ ? new RegExp(`(?<![\\w:./-])${escapeRegExp(name)}(?![\\w:-])`)
748
+ : new RegExp(`\\b(?:pnpm|npm|yarn|bun)\\b[^#\\n]*\\s${escapeRegExp(name)}(?![\\w:./-])`);
749
+ lines.forEach((l, i) => {
750
+ if (re.test(l))
751
+ found.push({ line: i + 1, name });
752
+ });
753
+ }
754
+ return found;
755
+ }
756
+ // Renames the old script keys in place (values kept), rewrites old `pnpm` tokens in every
757
+ // script value, and warns on an old name it cannot reach. Returns true when package.json
758
+ // changed.
759
+ export function migrateBrandedScriptNames(dryRun, ws, logPrefix) {
760
+ const pkgPath = "package.json";
761
+ if (!fs.existsSync(pkgPath))
762
+ return false;
763
+ const raw = fs.readFileSync(pkgPath, "utf-8");
764
+ const parsed = parseJson(raw);
765
+ if (!parsed.ok) {
766
+ console.warn(`${logPrefix} core: package.json is not valid JSON; script names not migrated`);
767
+ return false;
768
+ }
769
+ const pkg = parsed.value;
770
+ if (!plainObject(pkg.scripts))
771
+ return false;
772
+ const scripts = pkg.scripts;
773
+ const { active, bothPresent } = activeScriptRenames(scripts, BKIT_SCRIPT_RENAMES);
774
+ const tag = dryRun ? "[dry-run] " : "";
775
+ for (const oldName of bothPresent) {
776
+ console.warn(`${logPrefix} ${tag}core: package.json scripts hold both "${oldName}" and "${BKIT_SCRIPT_RENAMES[oldName]}"; left "${oldName}" in place — remove it once nothing uses it`);
777
+ }
778
+ const next = {};
779
+ const renamed = [];
780
+ let changed = false;
781
+ for (const [key, value] of Object.entries(scripts)) {
782
+ const newKey = active[key];
783
+ if (newKey !== undefined) {
784
+ renamed.push(key);
785
+ changed = true;
786
+ }
787
+ let newValue = value;
788
+ if (typeof value === "string") {
789
+ newValue = renameScriptTokens(value, active);
790
+ if (newValue !== value)
791
+ changed = true;
792
+ }
793
+ next[newKey ?? key] = newValue;
794
+ }
795
+ if (!changed)
796
+ return false;
797
+ for (const [key, value] of Object.entries(next)) {
798
+ if (typeof value !== "string")
799
+ continue;
800
+ for (const { name } of findOldScriptNames(value, active)) {
801
+ console.warn(`${logPrefix} ${tag}core: package.json script "${key}" still runs the old name "${name}"; rename it to "${active[name]}" by hand`);
802
+ }
803
+ }
804
+ pkg.scripts = next;
805
+ ws.writes.push({ path: pkgPath, action: "update" });
806
+ if (!dryRun)
807
+ writePackageJsonLike(raw, pkg);
808
+ console.log(`${logPrefix} ${tag}core: package.json script names branded${renamed.length > 0 ? ` [${renamed.join(", ")}]` : ""}`);
809
+ return true;
810
+ }
811
+ function renamePathTokens(text, pathRenames) {
812
+ let out = text;
813
+ for (const { from, to } of pathRenames) {
814
+ out = out.replace(new RegExp(`${escapeRegExp(from)}(?![\\w.-])`, "g"), to);
815
+ }
816
+ return out;
817
+ }
818
+ export function migrateBrandedFileTokens(dryRun, ws, logPrefix, pathRenames = []) {
819
+ const tag = dryRun ? "[dry-run] " : "";
820
+ let scripts = {};
821
+ let pkgRaw;
822
+ let pkg;
823
+ if (fs.existsSync("package.json")) {
824
+ pkgRaw = fs.readFileSync("package.json", "utf-8");
825
+ const parsed = parseJson(pkgRaw);
826
+ if (parsed.ok && plainObject(parsed.value)) {
827
+ pkg = parsed.value;
828
+ if (plainObject(pkg.scripts))
829
+ scripts = pkg.scripts;
830
+ }
831
+ }
832
+ const { active } = activeScriptRenames(scripts, BKIT_SCRIPT_RENAMES);
833
+ const tokenFiles = [
834
+ path.join(".husky", "pre-commit"),
835
+ path.join(".husky", "pre-push"),
836
+ ciWorkflowPath("."),
837
+ ];
838
+ const files = [...new Set([...tokenFiles, path.join(".github", "workflows", "bkit-trivy.yml")])];
839
+ for (const file of files) {
840
+ if (!fs.lstatSync(file, { throwIfNoEntry: false })?.isFile())
841
+ continue;
842
+ const text = fs.readFileSync(file, "utf-8");
843
+ let next = tokenFiles.includes(file) ? renameScriptTokens(text, active) : text;
844
+ next = renamePathTokens(next, pathRenames);
845
+ if (tokenFiles.includes(file)) {
846
+ for (const { name, line } of findOldScriptNames(next, active)) {
847
+ console.warn(`${logPrefix} ${tag}core: ${file}:${line} still runs the old script name "${name}"; rename it to "${active[name]}" by hand`);
848
+ }
849
+ }
850
+ if (next === text)
851
+ continue;
852
+ if (!dryRun)
853
+ fs.writeFileSync(file, next, "utf-8");
854
+ ws.writes.push({ path: file, action: "update", unhashed: true });
855
+ console.log(`${logPrefix} ${tag}core: ${file} — branded script and path names rewritten`);
856
+ }
857
+ for (const file of otherWorkflows(files)) {
858
+ for (const { name, line } of findOldScriptNames(fs.readFileSync(file, "utf-8"), active)) {
859
+ console.warn(`${logPrefix} ${tag}core: ${file}:${line} still runs the old script name "${name}"; rename it to "${active[name]}" by hand`);
860
+ }
861
+ }
862
+ if (pkg === undefined || pkgRaw === undefined || pathRenames.length === 0)
863
+ return;
864
+ let changed = false;
865
+ const nextScripts = {};
866
+ for (const [key, value] of Object.entries(scripts)) {
867
+ const nextValue = typeof value === "string" ? renamePathTokens(value, pathRenames) : value;
868
+ if (nextValue !== value)
869
+ changed = true;
870
+ nextScripts[key] = nextValue;
871
+ }
872
+ if (!changed)
873
+ return;
874
+ pkg.scripts = nextScripts;
875
+ ws.writes.push({ path: "package.json", action: "update", unhashed: true });
876
+ if (!dryRun)
877
+ writePackageJsonLike(pkgRaw, pkg);
878
+ console.log(`${logPrefix} ${tag}core: package.json — branded CI script paths rewritten`);
879
+ }
880
+ // sha256 of every distinct release content of the CI script `.mjs` files, per old path, from
881
+ // each `v*` tag. An unedited copy matches one of them.
882
+ export const SHIPPED_CI_SCRIPT_HASHES = {
883
+ "scripts/ci/check-capstone.mjs": [
884
+ "3813d9fe3cfae79788990b0a7a4914d18350dde165a3c2fe5940e8348362cea6",
885
+ "45078e630f5ec9ff4e7704c99ac5f56fd37b9c2e94c052f084c03feddc86ef71",
886
+ ],
887
+ "scripts/ci/check-capstone.test.mjs": [
888
+ "0554d64652dcc32ea368a4791372e860a5e3314ecfb7084256627015333c7afb",
889
+ "ad58a0095528fdb3fe7310586b4091824f29fda261542df73c324c8dd574a0d6",
890
+ ],
891
+ "scripts/ci/check-dependency-audit.mjs": [
892
+ "b410ab27cdbeed8d659fdf523d1af9b519beb874901186bb59e2889646cdaa19",
893
+ ],
894
+ "scripts/ci/check-dependency-audit.test.mjs": [
895
+ "db3643ae6ef7ad01d628e6110aa2f7b47cdf2423ca07efc1a8bc6176eb98b6a2",
896
+ ],
897
+ "scripts/ci/check-accepted-divergences.mjs": [
898
+ "3b410c53535e66b7a65b54d574ba7f7e47139bfba58a883a60697b8ab44deef4",
899
+ "66e6f1f9ce22b52afe93454c268613b8f5b03c1c58b5817cac958435fefbe5b1",
900
+ ],
901
+ "scripts/ci/check-accepted-divergences.test.mjs": [
902
+ "743e623f0dcb118a96744d31611fb599e9041a8007a3202fb46c30d72a3e183e",
903
+ "f130f5784349c21c5ae4f02626243362d9c29f783b9ad4b9c158beeca9bf4107",
904
+ ],
905
+ "scripts/ci/lanes/resolve-push-base.mjs": [
906
+ "016c4dacf34ce6edffcc7c7f666027a0a34669ce299d755679c877540fc751e7",
907
+ "11930bf63081ca2b5201799e0262acfcfc148e15bce41e17ebead688a94fe8ce",
908
+ "84acc7ff1596234af0c614236608e2009e794da9549bf77a4cc9560c2784a8f8",
909
+ ],
910
+ "scripts/ci/lanes/resolve-push-base.test.mjs": [
911
+ "1ce7b5fdf1de756f56e6b9710952c1e272c633107b06c0d47780fce36b90d1ad",
912
+ "32e17be38751f2744d660acdd99c6a08e7f437cdeaeb7075bc876b1cd31f0237",
913
+ "6883deb2b20f99af68721b085fbf3e2ab14e4b58d17dd676afaf734c75195e96",
914
+ ],
915
+ };
916
+ // Migration (up to 6.0.x installs, `docs/migrations.md`): the CI script files carry the
917
+ // `bkit-` prefix. A unit (script, test and data file, `CI_SCRIPT_UNITS`) moves whole when each
918
+ // present `.mjs` matches a shipped release and no `bkit-` target exists: the old files go, the
919
+ // `.mjs` targets come from the shipped templates, the data file moves byte for byte. Any
920
+ // other unit stays, with a warning naming the manual move (the `ci-scripts-old-names`
921
+ // advisory lists it too). Returns the renames applied plus those already applied (old absent,
922
+ // new present), for the path-token rewrite.
923
+ export function migrateBrandedTemplateFiles(dryRun, ws, logPrefix) {
924
+ const tag = dryRun ? "[dry-run] " : "";
925
+ const renames = [];
926
+ const templates = getTemplatesRoot();
927
+ for (const unit of CI_SCRIPT_UNITS) {
928
+ const exists = (p) => fs.lstatSync(p, { throwIfNoEntry: false }) !== undefined;
929
+ const present = unit.filter(([from]) => exists(from));
930
+ const done = unit.filter(([from, to]) => !exists(from) && exists(to));
931
+ for (const [from, to] of done)
932
+ renames.push({ from, to });
933
+ if (present.length === 0)
934
+ continue;
935
+ const linkedTargets = present.map(([, to]) => to).filter((to) => linkedPath(to));
936
+ const linkedAll = [
937
+ ...new Set([...present.map(([from]) => from).filter((f) => linkedPath(f)), ...linkedTargets]),
938
+ ];
939
+ if (linkedAll.length > 0) {
940
+ console.warn(`${logPrefix} ${tag}core: ${linkedAll.join(", ")} is a symlink (or sits under one); ${present.map(([from]) => from).join(", ")} not moved to the bkit- names; move them by hand and update every reference`);
941
+ continue;
942
+ }
943
+ const referenced = [
944
+ ...otherWorkflows([ciWorkflowPath("."), path.join(".github", "workflows", "bkit-trivy.yml")]),
945
+ ...compositeActions(),
946
+ ].flatMap((file) => {
947
+ const lines = fs.readFileSync(file, "utf-8").split("\n");
948
+ return present.flatMap(([from]) => lines.flatMap((l, i) => new RegExp(`${escapeRegExp(from)}(?![\\w.-])`).test(l)
949
+ ? [{ file, line: i + 1, from }]
950
+ : []));
951
+ });
952
+ if (referenced.length > 0) {
953
+ for (const { file, line, from } of referenced) {
954
+ console.warn(`${logPrefix} ${tag}core: ${file}:${line} still names ${from}; the unit was not moved to the bkit- names — move the files by hand and update that reference`);
955
+ }
956
+ continue;
957
+ }
958
+ const edited = present.filter(([from]) => from.endsWith(".mjs") &&
959
+ !SHIPPED_CI_SCRIPT_HASHES[from]?.includes(sha256(fs.readFileSync(from))));
960
+ const taken = present.filter(([, to]) => exists(to));
961
+ const noTemplate = present.filter(([, to]) => to.endsWith(".mjs") && !fs.existsSync(path.join(templates, to)));
962
+ if (edited.length > 0 || taken.length > 0 || noTemplate.length > 0) {
963
+ const why = edited.length > 0
964
+ ? `${edited.map(([from]) => from).join(", ")} differs from every shipped release`
965
+ : taken.length > 0
966
+ ? `${taken.map(([, to]) => to).join(", ")} already exists`
967
+ : "the shipped template is missing";
968
+ console.warn(`${logPrefix} ${tag}core: ${present.map(([from]) => from).join(", ")} not moved to the bkit- names (${why}); move them by hand and update every reference`);
969
+ continue;
970
+ }
971
+ for (const [from, to] of present) {
972
+ if (!dryRun) {
973
+ fs.mkdirSync(path.dirname(to), { recursive: true });
974
+ if (to.endsWith(".mjs"))
975
+ fs.copyFileSync(path.join(templates, to), to);
976
+ else
977
+ fs.copyFileSync(from, to);
978
+ fs.rmSync(from);
979
+ }
980
+ ws.writes.push({ path: from, action: "write", unhashed: true });
981
+ ws.writes.push({ path: to, action: "write", unhashed: true });
982
+ renames.push({ from, to });
983
+ console.log(`${logPrefix} ${tag}core: ${from} moved to ${to}`);
984
+ }
985
+ }
986
+ return renames;
987
+ }
988
+ // The old `bkit-stub:health` block, as shipped by every release up to 6.0.x.
989
+ const OLD_HEALTH_STUB = [
990
+ "# bkit-stub:health — copy into .github/workflows/health.yml. workflow_run cannot share a file with",
991
+ "# push / pull_request. WHEN: you have a live URL to smoke after CI. Trigger on CI completed, default",
992
+ "# branch only, if the CI run succeeded. Then hit the health URL of the deployment this SHA promoted.",
993
+ "# e.g. poll the host until that deployment is ready, then GET /health. Not a required check.",
994
+ "# DROP if you have no deployed health URL.",
995
+ ].join("\n");
996
+ // Exact old workflow `name:` lines the three shipped example workflows carried, with the
997
+ // branded line and the check each one renames. `job` names the job whose display name the
998
+ // workflow name branded (the job has no `name:` of its own, so its check showed the bare id).
999
+ const BRANDED_WORKFLOWS = [
1000
+ { file: "bkit-renovate.yml", oldName: "Renovate", newName: "bkit-renovate", job: "renovate" },
1001
+ { file: "bkit-trivy.yml", oldName: "Trivy", newName: "bkit-trivy", job: "trivy" },
1002
+ ];
1003
+ const CHECK_RENAME_FIX = "update the branch-protection required checks (and any ruleset) to the new name";
1004
+ // Migration (up to 6.0.x installs, `docs/migrations.md`): the shipped example workflows and
1005
+ // the health stub in the CI workflow carry bkit- check names. Only the exact shipped old
1006
+ // lines are rewritten, so a customised `name:` stays; the job `name:` is inserted only when
1007
+ // the workflow name was rewritten and the job has none. The health stub block is replaced
1008
+ // by the current one when it is byte-identical to the shipped old one. Writes are `unhashed`:
1009
+ // the files stay the consumer's. One log line per renamed check names old -> new, because
1010
+ // branch protection matches the check name.
1011
+ export function migrateBrandedCheckNames(dryRun, ws, logPrefix, defaultBranch = "main") {
1012
+ const tag = dryRun ? "[dry-run] " : "";
1013
+ const wfDir = path.join(".github", "workflows");
1014
+ const finish = (file, text, next, renamed) => {
1015
+ if (next === text)
1016
+ return;
1017
+ if (!dryRun)
1018
+ fs.writeFileSync(file, next, "utf-8");
1019
+ ws.writes.push({ path: file, action: "update", unhashed: true });
1020
+ for (const line of renamed) {
1021
+ console.log(`${logPrefix} ${tag}core: ${file} — check renamed ${line}; ${CHECK_RENAME_FIX}`);
1022
+ }
1023
+ };
1024
+ const readFile = (file) => fs.lstatSync(file, { throwIfNoEntry: false })?.isFile()
1025
+ ? fs.readFileSync(file, "utf-8")
1026
+ : undefined;
1027
+ const cloud = path.join(wfDir, "bkit-cloud.yml");
1028
+ const cloudText = readFile(cloud);
1029
+ if (cloudText !== undefined) {
1030
+ const renamed = [];
1031
+ const next = cloudText.replace(/^( {4}name: )(context|claude|opencode)( \(\$\{\{ github\.event_name \}\}\))$/gm, (_m, pre, job, post) => {
1032
+ renamed.push(`bkit-cloud / ${job}${post} -> bkit-cloud / bkit-cloud-${job}${post}`);
1033
+ return `${pre}bkit-cloud-${job}${post}`;
1034
+ });
1035
+ finish(cloud, cloudText, next, renamed);
1036
+ }
1037
+ for (const { file, oldName, newName, job } of BRANDED_WORKFLOWS) {
1038
+ const target = path.join(wfDir, file);
1039
+ const text = readFile(target);
1040
+ if (text === undefined)
1041
+ continue;
1042
+ const nameLine = new RegExp(`^name: ${escapeRegExp(oldName)}$`, "m");
1043
+ if (!nameLine.test(text))
1044
+ continue;
1045
+ let next = text.replace(nameLine, `name: ${newName}`);
1046
+ const jobStart = new RegExp(`^ {2}${escapeRegExp(job)}:[ \\t]*\\n`, "m").exec(next);
1047
+ if (jobStart !== null) {
1048
+ const bodyStart = jobStart.index + jobStart[0].length;
1049
+ const rest = next.slice(bodyStart);
1050
+ const end = rest.search(/^(?: {2}[^\s#]|[^\s#])/m);
1051
+ const body = end === -1 ? rest : rest.slice(0, end);
1052
+ if (!/^ {4}name:/m.test(body)) {
1053
+ next = `${next.slice(0, bodyStart)} name: ${newName}\n${next.slice(bodyStart)}`;
1054
+ }
1055
+ const after = new RegExp(`^ {2}${escapeRegExp(job)}:[ \\t]*\\n`, "m").exec(next);
1056
+ const afterRest = after === null ? "" : next.slice(after.index + after[0].length);
1057
+ const afterEnd = afterRest.search(/^(?: {2}[^\s#]|[^\s#])/m);
1058
+ const afterBody = afterEnd === -1 ? afterRest : afterRest.slice(0, afterEnd);
1059
+ if ((afterBody.match(/^ {4}name:/gm) ?? []).length > 1) {
1060
+ console.warn(`${logPrefix} ${tag}core: ${target} not renamed (a second job name: would make the workflow invalid YAML); rename by hand: name: ${oldName} -> name: ${newName} and set the ${job} job name: to ${newName}`);
1061
+ continue;
1062
+ }
1063
+ }
1064
+ finish(target, text, next, [`${oldName} / ${job} -> ${newName} / ${newName}`]);
1065
+ }
1066
+ const ci = ciWorkflowPath(".");
1067
+ const ciText = readFile(ci);
1068
+ if (ciText !== undefined && ciText.includes(OLD_HEALTH_STUB)) {
1069
+ const template = readFile(path.join(getTemplatesRoot(), ".github", "workflows", "bkit-ci.yml"));
1070
+ const current = template?.match(/^# bkit-stub:health[^\n]*\n(?:#[^\n]*\n)*?#[^\n]*DROP if you have no deployed health URL\./m)?.[0];
1071
+ if (current !== undefined) {
1072
+ const next = ciText.replace(OLD_HEALTH_STUB, () => current.replace(/\{\{DEFAULT_BRANCH\}\}/g, () => defaultBranch));
1073
+ if (next !== ciText) {
1074
+ if (!dryRun)
1075
+ fs.writeFileSync(ci, next, "utf-8");
1076
+ ws.writes.push({ path: ci, action: "update", unhashed: true });
1077
+ console.log(`${logPrefix} ${tag}core: ${ci} — old bkit-stub:health text replaced by the current block`);
1078
+ }
1079
+ }
1080
+ }
1081
+ }
1082
+ // sha256 of every distinct release content of the four shipped `House` Vale rules, from each
1083
+ // `v*` tag, across `.agents/templates/.vale/styles/House/` and `.bkit/templates/.vale/styles/House/`.
1084
+ // An unedited copy matches one of them. Same shape as `RETIRED_DRIVER_HASHES` (write.ts).
1085
+ export const SHIPPED_HOUSE_RULE_HASHES = {
1086
+ Filler: [
1087
+ "96139df9ffc61835e23014addac887d9465169d62cd1be24c2f272f838166524",
1088
+ "9b10438de3158a1923c51375fcba56de7a8dd2f17de97d62385407eee2a6e377",
1089
+ "e04e9e76a4857de0d13ff106343e25000418c535a983317f5a2e1710fa68cbc7",
1090
+ ],
1091
+ Hedging: [
1092
+ "7289b6bfe98f48803734c016c6ba49661071b5d8ded0f4678509b37c6ab8aff9",
1093
+ "b7425861cb3085cc798379d8e92f01a0420aa2c40f7be1ba1bbfabd908767a37",
1094
+ "c46cda04406629377555d3add75e56edaad40521864743dbbd47781f2c048ef0",
1095
+ ],
1096
+ LLMSlop: [
1097
+ "17a22ab44f0bd37de4d4c972fbb39a71dc256712ba0cfc39320043381f180a8e",
1098
+ "c39313e229249786ba189bb1abe55728f83e325a54777b41b54e0a1dec47b4f7",
1099
+ "e1ce58da6c86d7bc746698fbf17fd3d0075980ca78f2d8b8c927ea3ddc35094e",
1100
+ ],
1101
+ Verbose: [
1102
+ "8278791997cca85a2df63b2c93decac480e685215e0569e8472aa433e7a27ac8",
1103
+ "bcb18beb903e7bd57780905778ea4d1a4f294589cf191375db144ecb11f4c619",
1104
+ "f7939a5be92562803183108581538a1b4ca73c3b8a1b68ceeb2b2149ba1a4357",
1105
+ ],
1106
+ };
1107
+ // Migration (up to 6.0.x installs, `docs/migrations.md`): the shipped Vale style is `Bkit`,
1108
+ // it was `House`. A `House/<rule>.yml` byte-identical to a shipped release moves to
1109
+ // `Bkit/<rule>.yml` when that is absent; an edited rule or a taken target stays with one
1110
+ // warning naming the manual move. In `.vale.ini`, `House.<moved>` becomes `Bkit.<moved>`;
1111
+ // `BasedOnStyles` swaps `House` for `Bkit` once `House/` is empty (the directory goes), else
1112
+ // appends `Bkit`. Own rules in `House/` stay. Writes are `unhashed`.
1113
+ export function migrateValeHouseStyle(dryRun, ws, logPrefix) {
1114
+ const tag = dryRun ? "[dry-run] " : "";
1115
+ const stylesDir = path.join(".vale", "styles");
1116
+ const houseDir = path.join(stylesDir, "House");
1117
+ const bkitDir = path.join(stylesDir, "Bkit");
1118
+ const linkedVale = [".vale", stylesDir, houseDir, bkitDir].find((p) => isLink(p));
1119
+ if (linkedVale === houseDir || linkedVale === ".vale" || linkedVale === stylesDir) {
1120
+ console.warn(`${logPrefix} ${tag}core: ${linkedVale} is a symlink; the House rules were not moved to the Bkit style — move them by hand: mv .vale/styles/House/<rule>.yml .vale/styles/Bkit/ and rename the House.<rule> toggles in .vale.ini to Bkit.<rule>`);
1121
+ return;
1122
+ }
1123
+ if (!fs.lstatSync(houseDir, { throwIfNoEntry: false })?.isDirectory())
1124
+ return;
1125
+ if (linkedVale !== undefined) {
1126
+ console.warn(`${logPrefix} ${tag}core: ${linkedVale} is a symlink; the House rules were not moved to the Bkit style — move them by hand: mv .vale/styles/House/<rule>.yml .vale/styles/Bkit/ and rename the House.<rule> toggles in .vale.ini to Bkit.<rule>`);
1127
+ return;
1128
+ }
1129
+ const moved = [];
1130
+ for (const [rule, hashes] of Object.entries(SHIPPED_HOUSE_RULE_HASHES)) {
1131
+ const from = path.join(houseDir, `${rule}.yml`);
1132
+ if (isLink(from)) {
1133
+ console.warn(`${logPrefix} ${tag}core: ${from} is a symlink and was not moved to the Bkit style; move it by hand: mv .vale/styles/House/${rule}.yml .vale/styles/Bkit/ and rename the House.${rule} toggle in .vale.ini to Bkit.${rule}`);
1134
+ continue;
1135
+ }
1136
+ if (!fs.lstatSync(from, { throwIfNoEntry: false })?.isFile())
1137
+ continue;
1138
+ const to = path.join(bkitDir, `${rule}.yml`);
1139
+ const stays = !hashes.includes(sha256(fs.readFileSync(from)))
1140
+ ? "differs from every shipped release"
1141
+ : fs.lstatSync(to, { throwIfNoEntry: false }) !== undefined
1142
+ ? `${to} already exists`
1143
+ : undefined;
1144
+ if (stays !== undefined) {
1145
+ console.warn(`${logPrefix} ${tag}core: ${from} not moved to the Bkit style (${stays}); move it by hand: mv .vale/styles/House/${rule}.yml .vale/styles/Bkit/ and rename the House.${rule} toggle in .vale.ini to Bkit.${rule}`);
1146
+ continue;
1147
+ }
1148
+ if (!dryRun) {
1149
+ fs.mkdirSync(bkitDir, { recursive: true });
1150
+ fs.copyFileSync(from, to);
1151
+ fs.rmSync(from);
1152
+ }
1153
+ ws.writes.push({ path: from, action: "write", unhashed: true });
1154
+ ws.writes.push({ path: to, action: "write", unhashed: true });
1155
+ moved.push(rule);
1156
+ console.log(`${logPrefix} ${tag}core: ${from} moved to ${to}`);
1157
+ }
1158
+ const remaining = fs.readdirSync(houseDir).filter((f) => !moved.some((r) => f === `${r}.yml`));
1159
+ const houseGone = remaining.length === 0;
1160
+ if (houseGone) {
1161
+ if (!dryRun)
1162
+ fs.rmSync(houseDir, { recursive: true });
1163
+ ws.writes.push({ path: houseDir, action: "write", unhashed: true });
1164
+ }
1165
+ if (moved.length === 0 && !houseGone)
1166
+ return;
1167
+ const ini = ".vale.ini";
1168
+ if (!fs.lstatSync(ini, { throwIfNoEntry: false })?.isFile())
1169
+ return;
1170
+ const text = fs.readFileSync(ini, "utf-8");
1171
+ let next = text;
1172
+ if (moved.length > 0) {
1173
+ next = next.replace(new RegExp(`^(\\s*)House\\.(${moved.join("|")})\\b`, "gm"), (_m, lead, rule) => `${lead}Bkit.${rule}`);
1174
+ }
1175
+ if (houseGone)
1176
+ next = next.replace(/^(#.*)\bHouse rules\b/gm, "$1Bkit rules");
1177
+ next = next.replace(/^(BasedOnStyles\s*=\s*)(.*)$/gm, (line, pre, list) => {
1178
+ const styles = list.split(",").map((s) => s.trim());
1179
+ if (!styles.includes("House"))
1180
+ return line;
1181
+ if (houseGone) {
1182
+ const swapped = styles.map((s) => (s === "House" ? "Bkit" : s));
1183
+ return pre + [...new Set(swapped)].join(", ");
1184
+ }
1185
+ return styles.includes("Bkit") ? line : `${line}, Bkit`;
1186
+ });
1187
+ if (next === text)
1188
+ return;
1189
+ if (!dryRun)
1190
+ fs.writeFileSync(ini, next, "utf-8");
1191
+ ws.writes.push({ path: ini, action: "update", unhashed: true });
1192
+ console.log(`${logPrefix} ${tag}core: ${ini} — House style names rewritten to Bkit`);
1193
+ }
334
1194
  // Status option ids of GitHub's Kanban and Team planning board templates; every board
335
1195
  // made from one carries the same ids.
336
1196
  const TEMPLATE_STATUS_OPTIONS = {
@@ -396,9 +1256,157 @@ export function migrateGithubProjectKey(dryRun, ws, logPrefix) {
396
1256
  const tag = dryRun ? "[dry-run] " : "";
397
1257
  console.log(`${logPrefix} ${tag}core: moved bkit.githubProject to bkit.github in package.json`);
398
1258
  for (const moment of unnamed)
399
- console.log(`${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`);
1259
+ console.log(`${logPrefix} ${tag}core: bkit.githubProject named its ${moment} Status option by id; set bkit.tracker.github.${moment} to that option's name (default "${CONFIG_DEFAULTS.github[moment]}")`);
1260
+ return true;
1261
+ }
1262
+ // Migration (up to 5.5.x installs, `docs/migrations.md`): `bkit` settings sat flat; they
1263
+ // are grouped into named sections. Each old key moves to its new path; a value already at
1264
+ // the new path wins, and two blocks merge key by key. `loopPause: true|false` becomes
1265
+ // `ask` on every point under `workflows.<workflow>`, where an `ask` already set wins.
1266
+ // Runs after the linearTeam and githubProject moves, which write the flat keys. Returns
1267
+ // true when package.json changed.
1268
+ export const BKIT_LAYOUT_MOVES = [
1269
+ ["issueTracker", "tracker.default"],
1270
+ ["github", "tracker.github"],
1271
+ ["linear", "tracker.linear"],
1272
+ ["jira", "tracker.jira"],
1273
+ ["cloudAgents", "cloud.agent"],
1274
+ ["opencodeProvider", "providers.opencode.default"],
1275
+ ["opencodeProviders", "providers.opencode.installed"],
1276
+ ["minPushPaths", "testing.minPushPaths"],
1277
+ ["capstoneJob", "testing.ciCapstone"],
1278
+ ["ciWorkflow", "testing.ciWorkflow"],
1279
+ ["shipGateRequiredLanes", "testing.ciRequired"],
1280
+ // 6.0.0 installs named the required-lane list `testing.shipGate`.
1281
+ ["testing.shipGate", "testing.ciRequired"],
1282
+ ["disk.minFreeGb", "workflows.minFreeGb"],
1283
+ ["worktree", "workflows.worktree"],
1284
+ ["tasks", "workflows.tasks"],
1285
+ ["roadmapNext", "prompts.roadmapNext"],
1286
+ ["depUpdater", "dependencies.updater"],
1287
+ ["ignoreAdvisories", "advisories.ignore"],
1288
+ ];
1289
+ // Migration (up to 6.0.x installs, `docs/migrations.md`): `bkit.testing.minPushPaths` was the
1290
+ // whole min-push list, so installs seeded and repos restated what bkit itself writes. The
1291
+ // engine now always allows that floor (ship's bookkeeping allow-list, `docs/plans/**`) and
1292
+ // `bkit.testing.ciSkipPaths`; the setting only adds. Entries the floor already covers are
1293
+ // dropped from the list. Returns true when package.json changed.
1294
+ export const MIN_PUSH_FLOOR_ENTRIES = [
1295
+ "docs/plans/**",
1296
+ "docs/*.jsonl",
1297
+ ".bkit/*.jsonl",
1298
+ ];
1299
+ export function pruneMinPushPaths(dryRun, ws, logPrefix) {
1300
+ const pkgPath = "package.json";
1301
+ if (!fs.existsSync(pkgPath))
1302
+ return false;
1303
+ const raw = fs.readFileSync(pkgPath, "utf-8");
1304
+ const parsed = parseJson(raw);
1305
+ if (!parsed.ok)
1306
+ return false;
1307
+ const pkg = parsed.value;
1308
+ if (!plainObject(pkg.bkit) || !plainObject(pkg.bkit.testing))
1309
+ return false;
1310
+ const testing = pkg.bkit.testing;
1311
+ if (!Array.isArray(testing.minPushPaths))
1312
+ return false;
1313
+ const skip = Array.isArray(testing.ciSkipPaths) ? testing.ciSkipPaths : [];
1314
+ const covered = new Set([...MIN_PUSH_FLOOR_ENTRIES, ...skip]);
1315
+ const kept = testing.minPushPaths.filter((p) => !covered.has(p));
1316
+ if (kept.length === testing.minPushPaths.length)
1317
+ return false;
1318
+ const dropped = testing.minPushPaths.filter((p) => covered.has(p)).map(String);
1319
+ testing.minPushPaths = kept;
1320
+ ws.writes.push({ path: pkgPath, action: "update" });
1321
+ if (!dryRun)
1322
+ writePackageJsonLike(raw, pkg);
1323
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: dropped [${dropped.join(", ")}] from bkit.testing.minPushPaths in package.json — bkit always allows what it writes, and ciSkipPaths counts`);
400
1324
  return true;
401
1325
  }
1326
+ // Fill `into` with each `from` key it lacks, descending into blocks both sides hold.
1327
+ function mergeMissing(into, from) {
1328
+ for (const [k, v] of Object.entries(from)) {
1329
+ if (into[k] === undefined)
1330
+ into[k] = v;
1331
+ else if (plainObject(v) && plainObject(into[k]))
1332
+ mergeMissing(into[k], v);
1333
+ }
1334
+ }
1335
+ export function migrateBkitLayout(dryRun, ws, logPrefix) {
1336
+ const pkgPath = "package.json";
1337
+ if (!fs.existsSync(pkgPath))
1338
+ return false;
1339
+ const raw = fs.readFileSync(pkgPath, "utf-8");
1340
+ const parsed = parseJson(raw);
1341
+ if (!parsed.ok)
1342
+ return false;
1343
+ const pkg = parsed.value;
1344
+ if (!plainObject(pkg.bkit))
1345
+ return false;
1346
+ const cfg = pkg.bkit;
1347
+ const moved = [];
1348
+ for (const [from, to] of BKIT_LAYOUT_MOVES) {
1349
+ const fromPath = from.split(".");
1350
+ const fromParent = fromPath
1351
+ .slice(0, -1)
1352
+ .reduce((o, k) => (plainObject(o) ? o[k] : undefined), cfg);
1353
+ const fromKey = fromPath[fromPath.length - 1];
1354
+ if (!plainObject(fromParent) || !Object.prototype.hasOwnProperty.call(fromParent, fromKey))
1355
+ continue;
1356
+ const old = fromParent[fromKey];
1357
+ const toPath = to.split(".");
1358
+ let parent = cfg;
1359
+ let blocked = false;
1360
+ for (const k of toPath.slice(0, -1)) {
1361
+ if (parent[k] === undefined)
1362
+ parent[k] = {};
1363
+ if (!plainObject(parent[k])) {
1364
+ blocked = true;
1365
+ break;
1366
+ }
1367
+ parent = parent[k];
1368
+ }
1369
+ // A non-object where the new section belongs: leave the old key for `bkit check` to show.
1370
+ if (blocked)
1371
+ continue;
1372
+ const toKey = toPath[toPath.length - 1];
1373
+ if (parent[toKey] === undefined)
1374
+ parent[toKey] = old;
1375
+ else if (plainObject(parent[toKey]) && plainObject(old))
1376
+ mergeMissing(parent[toKey], old);
1377
+ delete fromParent[fromKey];
1378
+ if (fromParent !== cfg && Object.keys(fromParent).length === 0)
1379
+ delete cfg[fromPath[0]];
1380
+ moved.push(`bkit.${from} -> bkit.${to}`);
1381
+ }
1382
+ if (Object.prototype.hasOwnProperty.call(cfg, "loopPause")) {
1383
+ const old = cfg.loopPause;
1384
+ if (typeof old === "boolean") {
1385
+ if (cfg.workflows === undefined)
1386
+ cfg.workflows = {};
1387
+ if (plainObject(cfg.workflows))
1388
+ mergeMissing(cfg.workflows, askOnly(old));
1389
+ }
1390
+ delete cfg.loopPause;
1391
+ moved.push("bkit.loopPause -> bkit.workflows.<workflow>.<point>.ask");
1392
+ }
1393
+ if (moved.length === 0)
1394
+ return false;
1395
+ ws.writes.push({ path: pkgPath, action: "update" });
1396
+ if (!dryRun)
1397
+ writePackageJsonLike(raw, pkg);
1398
+ console.log(`${logPrefix} ${dryRun ? "[dry-run] " : ""}core: moved ${moved.join(", ")} in package.json`);
1399
+ return true;
1400
+ }
1401
+ /** `{design: {grill: {ask}}, build: {verify: {ask}, ...}, ...}` with every `ask` = `ask`. */
1402
+ function askOnly(ask) {
1403
+ const out = {};
1404
+ for (const point of ASK_POINTS) {
1405
+ const [workflow, name] = point.split(".");
1406
+ (out[workflow] ??= {})[name] = { ask };
1407
+ }
1408
+ return out;
1409
+ }
402
1410
  // Migration (up to 5.4.x installs, `docs/migrations.md`): the Linear team lived at
403
1411
  // `bkit.linearTeam`; it is `bkit.linear.team`, beside the project and state names. An
404
1412
  // existing `bkit.linear.team` wins over the old key. Returns true when package.json changed.
@@ -466,11 +1474,17 @@ export function gateLeafScripts(gate, declared, seen = new Set()) {
466
1474
  }
467
1475
  return leaves;
468
1476
  }
1477
+ /**
1478
+ * What a gate may run. bkit never reads a gate's value beyond its seeded default, so it
1479
+ * cannot check this; every gate advisory restates it (`.bkit/workflows.md` § Local gate
1480
+ * scripts).
1481
+ */
1482
+ export const GATE_CONTENTS_NOTE = "Gate contents (`.bkit/workflows.md` § Local gate scripts): every gate but `bkit:gate:static-unit-integration-e2e` and `bkit:gate:static-unit-integration-e2e-live` runs on a push or inside `/bkit-build`, so it MUST NOT run tests that need a deployed boundary or remote service; local services (a database in Docker) are fine.";
469
1483
  /**
470
1484
  * Advisories for the `bkit:gate:*` scripts: the scripts a still-default gate
471
1485
  * chains that package.json does not declare, the deeper test tiers the repo has
472
- * but no gate runs, a commit gate that repeats the push gate, and a missing
473
- * `bkit:test:file`. Judges the scripts as install
1486
+ * but no gate runs, a commit gate that repeats the push gate, a missing
1487
+ * `bkit:test:file`, and a missing `bkit:gate:changed`. Judges the scripts as install
474
1488
  * leaves them (missing gate names at their seeded defaults), so install, `bkit check`
475
1489
  * and `bkit upgrade` report the same set. Read-only; an absent or unparseable
476
1490
  * package.json yields none.
@@ -504,7 +1518,7 @@ export function detectGateAdvisories(cwd) {
504
1518
  id: "gate-missing-called-scripts",
505
1519
  severity: "advisory",
506
1520
  detect: `The bkit:gate scripts call scripts package.json does not declare: ${names.join(", ")}.`,
507
- action: `Every bkit workflow runs a \`bkit:gate*\` script, so a missing link fails the whole gate. Add ${names.join(", ")} to package.json (\`.bkit/templates.md\` lists the tool scripts and the devDeps they need), or edit the \`bkit:gate*\` scripts to drop what this repo does not have.`,
1521
+ action: `Every bkit workflow runs a \`bkit:gate*\` script, so a missing link fails the whole gate. Add ${names.join(", ")} to package.json (\`.bkit/templates.md\` lists the tool scripts and the devDeps they need), or edit the \`bkit:gate*\` scripts to drop what this repo does not have.\n\n${GATE_CONTENTS_NOTE}`,
508
1522
  });
509
1523
  }
510
1524
  // A repo that HAS a deeper tier but declares no gate for it is gated at
@@ -524,7 +1538,8 @@ export function detectGateAdvisories(cwd) {
524
1538
  detect: "package.json declares deeper test tiers than any `bkit:gate*` script runs, so `/bkit-build`, `/bkit-debug` and the pre-push hook gate at `bkit:gate:static-unit` and never execute them.",
525
1539
  action: "Each workflow runs the DEEPEST gate you declare, and `.husky/pre-push` runs `bkit:gate:static-unit-integration` when it is declared; an undeclared one is skipped, never guessed. Add the gates you want the agent loop to run:\n\n" +
526
1540
  unwired.join("\n") +
527
- "\n\nOrder matters — each chains the one above it. Omit a level deliberately to keep it CI-only (E2E in the build loop costs a production build on every remediation attempt). `.bkit/templates.md` lists the tool scripts the gates chain.",
1541
+ "\n\nOrder matters — each chains the one above it. Omit a level deliberately to keep it CI-only (E2E in the build loop costs a production build on every remediation attempt). `.bkit/templates.md` lists the tool scripts the gates chain.\n\n" +
1542
+ GATE_CONTENTS_NOTE,
528
1543
  });
529
1544
  }
530
1545
  // The commit gate is the fast one: a script it shares with the push gate runs on every
@@ -539,7 +1554,7 @@ export function detectGateAdvisories(cwd) {
539
1554
  id: "gate-commit-repeats-push",
540
1555
  severity: "advisory",
541
1556
  detect: `\`bkit:gate:format\` (pre-commit) runs ${names}, which \`${pushGate}\` (pre-push) runs again.`,
542
- action: `Drop ${names} from \`bkit:gate:format\`. The commit gate formats staged files and nothing else; every whole-repo check runs once, at pre-push.`,
1557
+ action: `Drop ${names} from \`bkit:gate:format\`. The commit gate formats staged files and nothing else; every whole-repo check runs once, at pre-push.\n\n${GATE_CONTENTS_NOTE}`,
543
1558
  });
544
1559
  }
545
1560
  // /bkit-build records each task's red through this script; without it test-first is
@@ -552,6 +1567,29 @@ export function detectGateAdvisories(cwd) {
552
1567
  action: `Add \`${BKIT_TEST_FILE_SCRIPT}\` to package.json: it runs the ONE test file bkit appends as its argument (repo-relative path) and writes a JUnit report to the path in \`$BKIT_TEST_REPORT\`. Vitest example:\n\n "${BKIT_TEST_FILE_SCRIPT}": "vitest run --reporter=default --reporter=junit --outputFile.junit=\\"$BKIT_TEST_REPORT\\""\n\nCall the runner directly, not through a task runner that caches results or runs dependent packages first. A monorepo routes the path to the package and config that own it.`,
553
1568
  });
554
1569
  }
1570
+ // A red recorded before the linter sees the test: a lint rewrite after it reads as an
1571
+ // edited test, and no red can be recorded again once the task's code makes it pass.
1572
+ if (BKIT_TEST_FILE_SCRIPT in declared && !(BKIT_LINT_FILE_SCRIPT in declared)) {
1573
+ findings.push({
1574
+ id: "lint-file-script-missing",
1575
+ severity: "advisory",
1576
+ detect: `package.json declares \`${BKIT_TEST_FILE_SCRIPT}\` but not \`${BKIT_LINT_FILE_SCRIPT}\`, so \`/bkit-build\` records a task's red before the linter sees the test; a lint fix after it pauses the build for an owner exception.`,
1577
+ action: `Add \`${BKIT_LINT_FILE_SCRIPT}\` to package.json: it lints the ONE test file bkit appends as its argument (repo-relative path) with the rules your static gate applies, exiting 0 when clean. \`bkit tests red\` runs it before the test and records no red while it fails. Examples:\n\n "${BKIT_LINT_FILE_SCRIPT}": "eslint --max-warnings=0"\n "${BKIT_LINT_FILE_SCRIPT}": "ruff check"\n\nUse the same linter config as the static gate, or the gate can still demand a rewrite after the red.`,
1578
+ });
1579
+ }
1580
+ // Build and debug agents check their own change through this script; without it each
1581
+ // one runs a whole gate after every change. bkit cannot seed it: what finds the tests
1582
+ // a file affects is the stack's.
1583
+ const changedId = "gate-changed-script-missing";
1584
+ if (!(BKIT_GATE_CHANGED_SCRIPT in declared) &&
1585
+ !isAdvisorySuppressed(cwd, changedId, "advisory")) {
1586
+ findings.push({
1587
+ id: changedId,
1588
+ severity: "advisory",
1589
+ detect: `package.json does not declare \`${BKIT_GATE_CHANGED_SCRIPT}\`, so \`/bkit-build\` and \`/bkit-debug\` agents run a whole gate (\`bkit:gate:static\` or \`bkit:gate:static-unit\`) after every change instead of checking only what changed.`,
1590
+ action: `Add \`${BKIT_GATE_CHANGED_SCRIPT}\` to package.json. \`bkit tests changed\` calls it with the changed files as its arguments (repo-relative paths: uncommitted, untracked and committed since the step began; deleted files left out) and never with none. It runs the tests that import those files, the tests that name their paths, and the static checks (lint, format, typecheck) on those files, exiting 0 when clean. Vitest + ESLint example, with \`scripts/gate-changed.sh\` holding \`vitest related --run "$@" && eslint --max-warnings=0 --no-error-on-unmatched-pattern "$@" && prettier --check --ignore-unknown "$@"\`:\n\n "${BKIT_GATE_CHANGED_SCRIPT}": "sh scripts/gate-changed.sh"\n\n\`vitest related\` finds only importers; also run the tests that read a changed file by its path (a text search of the test files for each path). The orchestrator's group gate, pre-push and CI still run the whole gates. To keep the whole gate on every change, add \`${changedId}\` to \`bkit.advisories.ignore\` in package.json.\n\n${GATE_CONTENTS_NOTE}`,
1591
+ });
1592
+ }
555
1593
  return findings;
556
1594
  }
557
1595
  /** One command that cannot fail: `true`, `:`, `exit 0`, or an `echo`. */
@@ -587,7 +1625,8 @@ export function detectNoopGates(cwd) {
587
1625
  id: "gate-noop",
588
1626
  severity: "advisory",
589
1627
  detect: `These bkit:gate scripts are empty or cannot fail, so they check nothing: ${noop.join(", ")}.`,
590
- action: 'Every bkit workflow and the pre-push hook trust a green `bkit:gate*` script, so a no-op gate passes every agent run and push. Point each at the checks it should run (e.g. `"bkit:gate:static": "pnpm typecheck && pnpm lint"`), or delete it from package.json and run `bkit upgrade` to get bkit\'s default back.',
1628
+ action: 'Every bkit workflow and the pre-push hook trust a green `bkit:gate*` script, so a no-op gate passes every agent run and push. Point each at the checks it should run (e.g. `"bkit:gate:static": "pnpm typecheck && pnpm lint"`), or delete it from package.json and run `bkit upgrade` to get bkit\'s default back.\n\n' +
1629
+ GATE_CONTENTS_NOTE,
591
1630
  },
592
1631
  ];
593
1632
  }
@@ -669,6 +1708,9 @@ export function runCoreModule(ctx) {
669
1708
  // Exclude .bkit/version itself and .agents/ internal files (not consumer-facing).
670
1709
  const newCanonicalEntries = {};
671
1710
  for (const entry of ws.writes) {
1711
+ // Brand-migrated copy-and-own files carry no hash.
1712
+ if (entry.unhashed)
1713
+ continue;
672
1714
  const absPath = path.isAbsolute(entry.path) ? entry.path : path.resolve(cwd, entry.path);
673
1715
  const relPath = path.relative(cwd, absPath);
674
1716
  if (relPath === path.join(".bkit", "version"))
@@ -721,7 +1763,7 @@ export function runCoreModule(ctx) {
721
1763
  "2. See `.bkit/install.md` for consumer setup and `.bkit/README.md` for ongoing ops.\n\n" +
722
1764
  "Note: bkit seeded the bkit:gate:* / bkit:deps:* package.json scripts every workflow\n" +
723
1765
  "runs (existing values are never touched). The tool scripts they chain (typecheck,\n" +
724
- "lint, format:check, lint:prose, slop:delta) and the devDeps those need are yours to\n" +
1766
+ "lint, format:check, bkit:lint:prose, bkit:slop:delta) and the devDeps those need are yours to\n" +
725
1767
  "add: see .bkit/templates.md.",
726
1768
  });
727
1769
  }