@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -9,6 +9,14 @@ import {
9
9
  getTemplatesRoot,
10
10
  TEMPLATE_COPIES_DIR,
11
11
  } from "../shared/package-roots.js";
12
+ import { hasLintStagedConfig } from "../checks/tips/detect.js";
13
+ import { readDependencyNames, readPackageJson } from "../shared/package-json.js";
14
+ import {
15
+ adoptedProjectDocPath,
16
+ inspectRepoFile,
17
+ PROJECT_DOC_TOPICS,
18
+ type ProjectDocTopic,
19
+ } from "./project-docs.js";
12
20
  import type { WriteSet } from "./write.js";
13
21
 
14
22
  export function listFilesRecursive(dir: string): string[] {
@@ -111,20 +119,39 @@ export const TEMPLATE_CHANGE_CONSEQUENCES: Readonly<Record<string, string>> = {
111
119
  "your adopted copy's guardrails exemptions are now stale; your slop gate may go red",
112
120
  };
113
121
 
114
- /** ` changed: <dest>`, plus the consequence when that template's adopted copy backs a gate. */
115
- function formatChangedLine(rel: string): string {
122
+ /** Where the project keeps its copy of a changed `docs/{topic}.md` starter, or null. */
123
+ function adoptedDocCopy(rel: string, cwd: string): string | null {
124
+ const match = /^docs\/([^/]+)\.md$/.exec(rel);
125
+ if (match === null) return null;
126
+ const topic = match[1];
127
+ if (topic === "components") return inspectRepoFile(cwd, rel) === "regular" ? rel : null;
128
+ return PROJECT_DOC_TOPICS.includes(topic as ProjectDocTopic)
129
+ ? adoptedProjectDocPath(cwd, topic as ProjectDocTopic)
130
+ : null;
131
+ }
132
+
133
+ /**
134
+ * ` changed: <dest>`, plus the consequence when that template's adopted copy backs a gate, and
135
+ * `adopted at <path>, review your copy` when the project keeps a copy of a changed doc starter.
136
+ */
137
+ function formatChangedLine(rel: string, cwd: string): string {
116
138
  const line = ` changed: ${path.join(TEMPLATE_COPIES_DIR, rel)}`;
117
139
  const note = TEMPLATE_CHANGE_CONSEQUENCES[rel];
118
- return note === undefined ? line : `${line} — ${note}`;
140
+ const adopted = adoptedDocCopy(rel, cwd);
141
+ const parts = [
142
+ ...(note === undefined ? [] : [note]),
143
+ ...(adopted === null ? [] : [`adopted at ${adopted}, review your copy`]),
144
+ ];
145
+ return parts.length === 0 ? line : `${line} \u2014 ${parts.join("; ")}`;
119
146
  }
120
147
 
121
148
  /**
122
149
  * The upgrade report for a template sync: one line per changed, added or removed
123
150
  * template, then where to read about adopting them. Empty when nothing changed.
124
151
  */
125
- export function formatTemplateChanges(changes: TemplateCopyChanges): string {
152
+ export function formatTemplateChanges(changes: TemplateCopyChanges, cwd: string): string {
126
153
  const lines = [
127
- ...changes.changed.map(formatChangedLine),
154
+ ...changes.changed.map((rel) => formatChangedLine(rel, cwd)),
128
155
  ...changes.added.map((p) => ` added: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
129
156
  ...changes.removed.map((p) => ` removed: ${path.join(TEMPLATE_COPIES_DIR, p)}`),
130
157
  ];
@@ -135,3 +162,29 @@ export function formatTemplateChanges(changes: TemplateCopyChanges): string {
135
162
  TEMPLATES_POINTER,
136
163
  ].join("\n");
137
164
  }
165
+
166
+ /** The line install, check and upgrade print after their log prefix when a gating lint-staged has no config to read. */
167
+ export const MISSING_LINT_STAGED_CONFIG_LINE =
168
+ "no root lint-staged config — commits will fail. Fix: cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json";
169
+
170
+ // True when `bkit:gate:format` runs `lint-staged` without a `--config` / `-c` path.
171
+ function formatGateRunsBareLintStaged(cwd: string): boolean {
172
+ const pkg = readPackageJson(cwd);
173
+ const scripts = pkg.ok ? (pkg.pkg.scripts as Record<string, unknown> | undefined) : undefined;
174
+ const format = scripts?.["bkit:gate:format"];
175
+ if (typeof format !== "string" || !/\blint-staged\b/.test(format)) return false;
176
+ return !/(?:^|\s)(?:--config(?:[=\s]|$)|-c(?:[=\s]|$))/.test(format);
177
+ }
178
+
179
+ // bkit writes no lint-staged config into a consumer repo. When the format gate runs lint-staged
180
+ // bare, lint-staged is installed and no config exists, the commit hook fails: print the one-line
181
+ // fix after the calling command's `logPrefix`. Prints in a dry run too; writes nothing. Returns
182
+ // true when it printed. No-op in dogfood.
183
+ export function warnMissingLintStagedConfig(cwd: string, logPrefix: string): boolean {
184
+ if (path.resolve(cwd) === getPkgRoot()) return false;
185
+ if (!formatGateRunsBareLintStaged(cwd)) return false;
186
+ if (!readDependencyNames(cwd).includes("lint-staged")) return false;
187
+ if (hasLintStagedConfig(cwd)) return false;
188
+ console.log(`${logPrefix} ${MISSING_LINT_STAGED_CONFIG_LINE}`);
189
+ return true;
190
+ }
@@ -197,6 +197,106 @@ export function deepMergeJson(base: JsonValue, override: JsonValue): JsonValue {
197
197
  return result;
198
198
  }
199
199
 
200
+ // ---------------------------------------------------------------------------
201
+ // mergeManagedJson — list-aware merge for managed Tier-2 JSON files
202
+ //
203
+ // - Objects: merge like deepMergeJson (template keys first, consumer-only keys appended)
204
+ // - Lists of plain values: template entries in template order, then consumer-only entries
205
+ // - Lists of objects (hook groups): a consumer group sharing a hook `command`, or the same
206
+ // bkit hook file (`bkit-*.cjs`), with a template group is replaced by it; other consumer groups follow the template's groups
207
+ // - Anything else: the template wins
208
+ // ---------------------------------------------------------------------------
209
+
210
+ function isPlainObject(v: JsonValue | undefined): v is { [k: string]: JsonValue } {
211
+ return v !== null && typeof v === "object" && !Array.isArray(v);
212
+ }
213
+
214
+ function groupCommands(group: { [k: string]: JsonValue }): string[] {
215
+ const out: string[] = [];
216
+ if (typeof group.command === "string") out.push(group.command);
217
+ const hooks = group.hooks;
218
+ if (!Array.isArray(hooks)) return out;
219
+ for (const h of hooks) {
220
+ if (isPlainObject(h) && typeof h.command === "string") out.push(h.command);
221
+ }
222
+ return out;
223
+ }
224
+
225
+ // The bkit hook file a command runs (`bkit-gateguard.cjs`, `bkit-preflight.sh`, ...), so an
226
+ // older spelling of the same bkit hook is still recognised as bkit's own.
227
+ function bkitHookFile(command: string): string | undefined {
228
+ return /\bbkit-[a-z0-9-]+\.(?:cjs|js|sh)\b/.exec(command)?.[0];
229
+ }
230
+
231
+ function mergeManagedList(base: JsonValue[], override: JsonValue[]): JsonValue[] {
232
+ const objectLists = [...base, ...override].every((e) => isPlainObject(e));
233
+ if (objectLists) {
234
+ const templateCommands = new Set<string>();
235
+ for (const g of override) {
236
+ for (const c of groupCommands(g as { [k: string]: JsonValue })) {
237
+ templateCommands.add(c);
238
+ const file = bkitHookFile(c);
239
+ if (file) templateCommands.add(`bkit-file:${file}`);
240
+ }
241
+ }
242
+ const isTemplateCommand = (c: string): boolean => {
243
+ const file = bkitHookFile(c);
244
+ return (
245
+ templateCommands.has(c) || (file !== undefined && templateCommands.has(`bkit-file:${file}`))
246
+ );
247
+ };
248
+ const templateKeys = new Set(override.map((g) => JSON.stringify(g)));
249
+ const merged = override.map((g) => ({ ...(g as { [k: string]: JsonValue }) }));
250
+ const kept: JsonValue[] = [];
251
+ for (const g of base) {
252
+ if (templateKeys.has(JSON.stringify(g))) continue;
253
+ const group = g as { [k: string]: JsonValue };
254
+ const cmds = groupCommands(group);
255
+ if (!cmds.some(isTemplateCommand)) {
256
+ kept.push(g);
257
+ continue;
258
+ }
259
+ // A replaced bkit group: its consumer-added hooks move into the matching template group.
260
+ if (!Array.isArray(group.hooks)) continue;
261
+ const extras = group.hooks.filter(
262
+ (h) => isPlainObject(h) && typeof h.command === "string" && !isTemplateCommand(h.command),
263
+ );
264
+ if (extras.length === 0) continue;
265
+ const target = merged.find((t) =>
266
+ groupCommands(t).some((c) =>
267
+ cmds.some(
268
+ (bc) =>
269
+ bc === c || (bkitHookFile(c) !== undefined && bkitHookFile(c) === bkitHookFile(bc)),
270
+ ),
271
+ ),
272
+ );
273
+ if (!target || !Array.isArray(target.hooks)) continue;
274
+ const have = new Set(target.hooks.map((h) => JSON.stringify(h)));
275
+ const add = extras.filter((h) => !have.has(JSON.stringify(h)));
276
+ target.hooks = [...target.hooks, ...add];
277
+ }
278
+ return [...merged, ...kept];
279
+ }
280
+ const seen = new Set(override.map((e) => JSON.stringify(e)));
281
+ const extras = base.filter((e) => !seen.has(JSON.stringify(e)));
282
+ return [...override, ...extras];
283
+ }
284
+
285
+ export function mergeManagedJson(base: JsonValue, override: JsonValue): JsonValue {
286
+ if (Array.isArray(override)) {
287
+ return Array.isArray(base) ? mergeManagedList(base, override) : override;
288
+ }
289
+ if (!isPlainObject(override) || !isPlainObject(base)) return override;
290
+ const result: { [k: string]: JsonValue } = {};
291
+ for (const [key, val] of Object.entries(override)) {
292
+ result[key] = key in base ? mergeManagedJson(base[key] as JsonValue, val) : val;
293
+ }
294
+ for (const [key, val] of Object.entries(base)) {
295
+ if (!(key in result)) result[key] = val;
296
+ }
297
+ return result;
298
+ }
299
+
200
300
  // ---------------------------------------------------------------------------
201
301
  // MCP tracker entry — bkit owns the template's parts of the entry, not the whole entry (#613)
202
302
  //
@@ -301,7 +401,7 @@ export function writeTier2JsonContained(
301
401
  }
302
402
 
303
403
  // Deep-merge: existing base, template override (template wins on conflicts)
304
- const merged = deepMergeJson(existing as JsonValue, template as JsonValue);
404
+ const merged = mergeManagedJson(existing as JsonValue, template as JsonValue);
305
405
  const mergedStr = JSON.stringify(merged, null, 2) + "\n";
306
406
  if (mergedStr === dstRaw) return; // idempotent guard
307
407
 
@@ -392,8 +492,8 @@ export function writeTier1(
392
492
 
393
493
  /**
394
494
  * sha256 of the driver (everything outside the managed block) of hook files a bkit
395
- * release shipped with a host contract the host does not accept, keyed by consumer path.
396
- * Register: docs/migrations.md.
495
+ * release shipped with an output the current managed block cannot work through, keyed by
496
+ * consumer path. Register: docs/migrations.md.
397
497
  */
398
498
  export const RETIRED_DRIVER_HASHES: Readonly<Record<string, readonly string[]>> = {
399
499
  // 5.1.0: Claude-shaped `hookSpecificOutput`; Antigravity reads `{ decision, reason }`.
@@ -403,6 +503,28 @@ export const RETIRED_DRIVER_HASHES: Readonly<Record<string, readonly string[]>>
403
503
  ".agents/plugins/bkit/hooks/bkit-guardrails.cjs": [
404
504
  "8e5d75f7e1a4527889dafa6a250ae370e2acf1b5fc7d58929dfc759489746e14",
405
505
  ],
506
+ // 5.0.0-6.1.1: emits `additionalContext` only, so the block's `{ verdict: "deny" }` is dropped.
507
+ ".claude/hooks/bkit-guardrails.cjs": [
508
+ "dae41b58e61b055c816ef50f35a763949ec99d1c532dccab980c88d21f4c84f3",
509
+ ],
510
+ };
511
+
512
+ const ANTIGRAVITY_DRIVER_FIX = {
513
+ isStale: (driver: string) => driver.includes("hookSpecificOutput"),
514
+ fix: 'writes Claude-shaped `hookSpecificOutput`, which Antigravity ignores — the hook never takes effect. Emit the managed block\'s result as Antigravity\'s `{ "decision": "allow" | "deny" | "ask", "reason": "…" }` (only a deny\'s reason reaches the model), or delete the file and re-run `bkit install --antigravity` to get bkit\'s driver.',
515
+ };
516
+
517
+ /** Per retired-driver path: what marks an edited driver as stale, and the printed fix. */
518
+ const EDITED_DRIVER_FIXES: Readonly<
519
+ Record<string, { isStale: (driver: string) => boolean; fix: string }>
520
+ > = {
521
+ ".agents/plugins/bkit/hooks/bkit-gateguard.cjs": ANTIGRAVITY_DRIVER_FIX,
522
+ ".agents/plugins/bkit/hooks/bkit-guardrails.cjs": ANTIGRAVITY_DRIVER_FIX,
523
+ ".claude/hooks/bkit-guardrails.cjs": {
524
+ // An object key, not the 5.0.0-6.1.1 header's "no `permissionDecision` is ever emitted".
525
+ isStale: (driver) => !/permissionDecision["']?\s*:/.test(driver),
526
+ fix: 'never emits a `permissionDecision`, so Claude Code runs every command the managed block refuses. When `bkitGuardrails()` returns `{ verdict: "deny", reason }`, emit `{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: result.reason } }`, or delete the file and re-run `bkit install` to get bkit\'s driver.',
527
+ },
406
528
  };
407
529
 
408
530
  /** The text outside a file's single managed block, or null without exactly one block. */
@@ -427,10 +549,9 @@ function hasRetiredDriver(dstPath: string, content: string, markerStyle: MarkerS
427
549
  const driver = driverText(content, markerStyle);
428
550
  if (driver === null) return false;
429
551
  if (RETIRED_DRIVER_HASHES[key]!.includes(sha256(driver))) return true;
430
- if (driver.includes("hookSpecificOutput")) {
431
- console.warn(
432
- `[bkit] ${dstPath}: your driver below \`// bkit:end\` writes Claude-shaped \`hookSpecificOutput\`, which Antigravity ignores — the hook never takes effect. Emit the managed block's result as Antigravity's \`{ "decision": "allow" | "deny" | "ask", "reason": "…" }\` (only a deny's reason reaches the model), or delete the file and re-run \`bkit install --antigravity\` to get bkit's driver.`,
433
- );
552
+ const edited = EDITED_DRIVER_FIXES[key];
553
+ if (edited?.isStale(driver)) {
554
+ console.warn(`[bkit] ${dstPath}: your driver below \`// bkit:end\` ${edited.fix}`);
434
555
  }
435
556
  return false;
436
557
  }
@@ -17,7 +17,7 @@ import * as fs from "node:fs";
17
17
  import * as path from "node:path";
18
18
 
19
19
  import { parseJson } from "../shared/json.js";
20
- import { appendLine, statusTimestamp } from "./status.js";
20
+ import { appendLine, appendLocked, statusTimestamp, type AppendCheckpoint } from "./status.js";
21
21
  import {
22
22
  APPEND_LEDGERS,
23
23
  SCHEMA,
@@ -28,7 +28,8 @@ import {
28
28
  writerProblem,
29
29
  } from "./telemetry.js";
30
30
 
31
- export type JournalResult = { ok: true } | { ok: false; error: string };
31
+ export type JournalResult =
32
+ { ok: true; receipt?: { offset: number; bytes: number } } | { ok: false; error: string };
32
33
 
33
34
  /** The kill switch: `BKIT_ENGINE_JOURNAL=off` keeps the seam from writing any row. */
34
35
  export function journalEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
@@ -225,22 +226,29 @@ export function appendJournalRow(file: string, row: EngineCallRow): JournalResul
225
226
  * `recurrenceCount` raised by one and `lastConfirmed` = that `ts`. No line is
226
227
  * ever rewritten, so a row another writer appends meanwhile is kept.
227
228
  */
228
- export function appendFrictionRow(bookRoot: string, row: Record<string, unknown>): JournalResult {
229
+ export function appendFrictionRow(
230
+ bookRoot: string,
231
+ row: Record<string, unknown>,
232
+ options: { checkpoint?: AppendCheckpoint } = {},
233
+ ): JournalResult {
229
234
  const checked = validate(row);
230
235
  if (!checked.ok) return { ok: false, error: checked.reason ?? "invalid friction row" };
231
236
  const who = writerProblem(row);
232
237
  if (who !== undefined) return { ok: false, error: who };
233
238
  const file = path.join(bookRoot, APPEND_LEDGERS.friction.file);
234
239
  try {
235
- fs.mkdirSync(path.dirname(file), { recursive: true });
236
- const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
237
- const prior = latestSameKey(text, row["key"]);
238
- const next = prior === undefined ? { ...row, recurrenceCount: 1 } : recurrence(prior, row);
239
- fs.appendFileSync(
240
+ // The recurrence is computed from the text read under the target lock, so a
241
+ // competing writer can never invalidate the prepared offset or count.
242
+ const landed = appendLocked(
240
243
  file,
241
- `${text !== "" && !text.endsWith("\n") ? "\n" : ""}${JSON.stringify(next)}\n`,
244
+ (text) => {
245
+ const prior = latestSameKey(text, row["key"]);
246
+ const next = prior === undefined ? { ...row, recurrenceCount: 1 } : recurrence(prior, row);
247
+ return `${JSON.stringify(next)}\n`;
248
+ },
249
+ { checkpoint: options.checkpoint },
242
250
  );
243
- return { ok: true };
251
+ return { ok: true, receipt: { offset: landed.offset, bytes: landed.bytes } };
244
252
  } catch (err) {
245
253
  return { ok: false, error: (err as Error).message };
246
254
  }
@@ -9,6 +9,7 @@ import * as fs from "node:fs";
9
9
  import * as path from "node:path";
10
10
 
11
11
  import { parseJson } from "../shared/json.js";
12
+ import { pendingLedgerIntentsFor, withTargetLock } from "./status.js";
12
13
  import { normalize } from "./telemetry.js";
13
14
 
14
15
  /** Every repo ledger whose rows carry the shared top section (`.bkit/jsonl.md`). */
@@ -79,14 +80,25 @@ export function migrateLedgers(
79
80
  for (const file of SCHEMA_LEDGERS) {
80
81
  const abs = path.join(root, file);
81
82
  if (!fs.lstatSync(abs, { throwIfNoEntry: false })?.isFile()) continue;
82
- const { text, rewritten, dropped } = migrateLedgerText(fs.readFileSync(abs, "utf-8"));
83
- if (rewritten + dropped === 0) continue;
84
- if (!dryRun) {
85
- const tmp = `${abs}.bkit-migrate.tmp`;
86
- fs.writeFileSync(tmp, text, "utf-8");
87
- fs.renameSync(tmp, abs);
88
- }
89
- out.push({ file, rewritten, dropped });
83
+ const migrate = () => {
84
+ const { text, rewritten, dropped } = migrateLedgerText(fs.readFileSync(abs, "utf-8"));
85
+ if (rewritten + dropped === 0) return undefined;
86
+ if (!dryRun) {
87
+ // A pending ledger operation holds an offset into the current bytes: refuse to move them.
88
+ const pending = pendingLedgerIntentsFor(root, file);
89
+ if (pending.length > 0)
90
+ throw new Error(
91
+ `${file} has ledger operation(s) with bytes but no receipt (${pending.map((p) => p.operation).join(", ")}); replay them before migrating`,
92
+ );
93
+ const tmp = `${abs}.bkit-migrate.tmp`;
94
+ fs.writeFileSync(tmp, text, "utf-8");
95
+ fs.renameSync(tmp, abs);
96
+ }
97
+ return { file, rewritten, dropped };
98
+ };
99
+ // Read and rewrite under the target lock, so a row appended meanwhile is never dropped.
100
+ const done = dryRun ? migrate() : withTargetLock(abs, migrate);
101
+ if (done !== undefined) out.push(done);
90
102
  }
91
103
  return out;
92
104
  }