@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
@@ -304,15 +304,73 @@ OV_DEFAULT = """{
304
304
  }"""
305
305
 
306
306
 
307
+ GEN_START, GEN_END = "<!-- graphify:start -->", "<!-- graphify:end -->"
308
+ # The starter holds the text around the generated region: title, rules box, Overrides.
309
+ STARTER_DOC = ".bkit/templates/docs/capabilities.md"
310
+ # A doc with no marker pair that holds one of these lines is generated from top to
311
+ # bottom, so no hand-written text is lost when the starter's frame replaces it.
312
+ WHOLE_DOC_SIGNS = ("> - Generated — do not edit.", "> - This file is generated.")
313
+
314
+
315
+ def split_frame(text, path):
316
+ """Return (head, tail): the text up to and including the start marker line, and
317
+ the text from the end marker line on. None when the text has neither marker.
318
+
319
+ A marker counts only as a whole line, so prose that names one never matches.
320
+ Anything but exactly one pair in order RAISES; the file is never rewritten when
321
+ the generated region cannot be told from hand-written text.
322
+ """
323
+ lines = text.split("\n")
324
+ starts = [i for i, line in enumerate(lines) if line.strip() == GEN_START]
325
+ ends = [i for i, line in enumerate(lines) if line.strip() == GEN_END]
326
+ if not starts and not ends:
327
+ return None
328
+ if len(starts) != 1 or len(ends) != 1 or starts[0] > ends[0]:
329
+ raise SystemExit(f"[graph] {path}: needs exactly one {GEN_START} line followed by one "
330
+ f"{GEN_END} line. Refusing to overwrite it; fix the marker lines.")
331
+ return "\n".join(lines[:starts[0] + 1]), "\n".join(lines[ends[0]:])
332
+
333
+
334
+ def doc_frame(doc_path, ov_text):
335
+ """The hand-written text around the generated region of capabilities.md.
336
+
337
+ A doc with the marker pair keeps every byte outside it. A doc without the
338
+ pair is absent, or was written whole by an older copy of this script; its
339
+ frame is then the starter's, from the title on, with the overrides carried
340
+ over. Any other doc without the pair RAISES, because hand-written text in it
341
+ would be lost.
342
+ """
343
+ if doc_path and os.path.exists(doc_path):
344
+ text = open(doc_path, encoding="utf-8").read()
345
+ frame = split_frame(text, doc_path)
346
+ if frame:
347
+ return frame
348
+ if not any(sign in text for sign in WHOLE_DOC_SIGNS):
349
+ raise SystemExit(f"[graph] {doc_path}: no {GEN_START} and {GEN_END} lines. Refusing to "
350
+ "overwrite it; put the two marker lines around the generated sections.")
351
+ if not os.path.exists(STARTER_DOC):
352
+ raise SystemExit(f"[graph] {doc_path} has no {GEN_START} and {GEN_END} lines, and "
353
+ f"{STARTER_DOC} is missing. Copy the starter to {doc_path} first.")
354
+ starter = open(STARTER_DOC, encoding="utf-8").read()
355
+ title = re.search(r"^# ", starter, re.M)
356
+ frame = split_frame(starter[title.start():] if title else starter, STARTER_DOC)
357
+ if not frame:
358
+ raise SystemExit(f"[graph] {STARTER_DOC}: no {GEN_START} and {GEN_END} lines.")
359
+ head, tail = frame
360
+ if OV_START in tail and OV_END in tail:
361
+ before, rest = tail.split(OV_START, 1)
362
+ tail = f"{before}{OV_START}\n\n```json\n{ov_text}\n```\n\n{OV_END}{rest.split(OV_END, 1)[1]}"
363
+ return head, tail
364
+
365
+
307
366
  def read_overrides(doc_path):
308
- """Recover the hand-maintained overrides block from the generated doc.
367
+ """Recover the hand-maintained overrides block from capabilities.md.
309
368
 
310
- The doc is otherwise rewritten wholesale, so this one region round-trips:
311
- read before writing, re-emitted verbatim. It is the only part of
312
- capabilities.md a human is meant to touch.
369
+ The block sits outside the generated region, so a run leaves it as it is.
370
+ It is read first because it steers what the region draws.
313
371
 
314
372
  An overrides block with no ```json fence, or with invalid JSON, RAISES; the
315
- file is never rewritten without its overrides.
373
+ file is never rewritten with overrides it could not read.
316
374
  """
317
375
  if not doc_path or not os.path.exists(doc_path):
318
376
  return json.loads(OV_DEFAULT), OV_DEFAULT
@@ -788,13 +846,15 @@ def reachability_block(reach):
788
846
 
789
847
  def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_text, eager,
790
848
  reach):
791
- """Write docs/capabilities.md — the tracked register, wholly generated.
849
+ """Write the generated region of docs/capabilities.md, the tracked register.
792
850
 
793
- Source of truth is bkit-graph-drift-rules.json (which capability, which owner,
794
- which literal marker); every status in the table is derived from live source
795
- by bkit-graph-drift.py, never typed in. Editing this file by hand loses the edit
796
- on the next `pnpm bkit:graph:rollup`.
851
+ Only the text between the GEN_START and GEN_END lines is rewritten; doc_frame
852
+ supplies the text around it. Source of truth is bkit-graph-drift-rules.json
853
+ (which capability, which owner, which literal marker); every status in the
854
+ table is derived from live source by bkit-graph-drift.py, never typed in. An
855
+ edit between the two lines is lost on the next `pnpm bkit:graph:rollup`.
797
856
  """
857
+ head, tail = doc_frame(out, ov_text)
798
858
  ROUTES_MMD, n_routes = chain_block(surface, overlay, reach)
799
859
  ROUTES_PROSE = (
800
860
  f"{n_routes} routes across web and native, each linked to the service domains it reaches. "
@@ -826,40 +886,26 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
826
886
  f"{issue} |")
827
887
 
828
888
  D = [
829
- "# Capabilities",
889
+ "## Reading the register",
830
890
  "",
831
- "> [!CAUTION]",
832
- "> **Purpose:** One row per app capability — owner module, the literal marker that finds",
833
- "> every use of it, whether anything bypasses the owner. The drift register.",
834
- ">",
835
- "> **Rules:**",
836
- ">",
837
- "> - Generated — do not edit. `pnpm bkit:graph:refresh` rewrites this file.",
838
- f"> - Source of truth: `{rules_path}`. Every status derived from live source, never typed.",
839
- "> - Add a capability = add a rule there: capability · lane · owner module · one literal marker.",
840
- "> - Markers literal, never regex, because `new Client(` as a regex is an unclosed group matching nothing.",
841
- "> - Match the mechanism, not the name, because `createClient(` misses an owner that aliases its import.",
842
- "> - Optional `scope` narrows the tree scanned when a marker means different things per package.",
843
- "> - Optional `surface`: `product` (default) · `tests` (any `e2e/` dir + every `.test.` / `.spec.` file) · `all`. The two surfaces partition the tree.",
844
- "> - Optional `budgets`: the exact non-owner site count allowed per scope prefix. Measured == declared everywhere ⇒ `budgeted`, which is not a warning.",
845
- "> - A budget is not a shrug, because the row leaves `budgeted` and its Budget cell reads `over` or `stale` when the count moves either way, and a site landing outside every declared prefix reads as over budget.",
846
- "> - Test code is in `graph.json` on purpose (`.graphifyignore`) and out of every diagram here by rule (`is_test_code` in `bkit-graphify-rollup.py`): test folders, `.test.` / `.spec.` files, test-runner config. `hide_nodes` below is diagram-only too, for whatever else a picture should not draw.",
847
- "> - Status computed: no owner → `split`; owner absent → `gap`; owner present, others use marker → `bypassed`; else `one`. A `split|bypassed` at budget → `budgeted`.",
848
- "> - Externals: `scripts/graphify/bkit-graph-external-rules.json` — `sdk` · `hosts` · `env`. SDK and url = `split`.",
849
- "> - Import-time scan: `scripts/graphify/bkit-graph-eager-rules.json` lists only what is pure. Unclassified = reported.",
850
- "> - That scan reads source, not the graph, because module-level initialiser calls are the one construct graphify drops.",
851
- "> - Nothing discovers an SDK itself; find gaps by listing non-workspace deps.",
852
- "> - Only the Overrides block is hand-maintained. It round-trips; malformed aborts the run.",
853
- "> - Box colour = the top-level group it sits in; a box in no group is grey. With one top-level group, that group is grey and each box has its own colour.",
854
- "> - Arrows are grey; a thicker arrow carries more links.",
855
- "> - A flagged box counts its open and budgeted findings; the Register table names them.",
856
- "> - A part that calls nothing in the chart and that at least a quarter of the other boxes call (four at least) has its arrows left out and counts its callers.",
857
- "> - Drift = thick dashed red border + a faint red box for all four. No ranking: each scan proves a shape, never an intent.",
858
- "> - `budgeted` = solid amber border + a faint amber box. Still drawn, because a declared bypass is still a bypass, but it is settled, not an open question.",
859
- "> - Which status is which: `split` fine dash · `bypassed` long dash · `dead` even dash · `gap` dotted · `budgeted` no dash.",
860
- "> - A fetched URL is a STRING, never an edge, because the reachability scan (§ Unreachable API calls) is the only check that sees it.",
861
- "> - Table rescanned every run, never stale.",
862
- "> - Detail-level module graph → `pnpm bkit:graph`. This doc is the altitude above that: capabilities, not files.",
891
+ f"- Built from `{rules_path}`. Every status derived from live source, never typed.",
892
+ "- A budget is not a shrug, because the row leaves `budgeted` and its Budget cell reads `over` or `stale` when the count moves either way, and a site landing outside every declared prefix reads as over budget.",
893
+ "- Test code is in `graph.json` on purpose (`.graphifyignore`) and out of every diagram here by rule (`is_test_code` in `bkit-graphify-rollup.py`): test folders, `.test.` / `.spec.` files, test-runner config. `hide_nodes` in the Overrides block is diagram-only too, for whatever else a picture should not draw.",
894
+ "- Status computed: no owner → `split`; owner absent → `gap`; owner present, others use marker → `bypassed`; else `one`. A `split|bypassed` at budget → `budgeted`.",
895
+ "- Externals: `scripts/graphify/bkit-graph-external-rules.json` — `sdk` · `hosts` · `env`. SDK and url = `split`.",
896
+ "- Import-time scan: `scripts/graphify/bkit-graph-eager-rules.json` lists only what is pure. Unclassified = reported.",
897
+ "- That scan reads source, not the graph, because module-level initialiser calls are the one construct graphify drops.",
898
+ "- Nothing discovers an SDK itself; find gaps by listing non-workspace deps.",
899
+ "- Box colour = the top-level group it sits in; a box in no group is grey. With one top-level group, that group is grey and each box has its own colour.",
900
+ "- Arrows are grey; a thicker arrow carries more links.",
901
+ "- A flagged box counts its open and budgeted findings; the Register table names them.",
902
+ "- A part that calls nothing in the chart and that at least a quarter of the other boxes call (four at least) has its arrows left out and counts its callers.",
903
+ "- Drift = thick dashed red border + a faint red box for all four. No ranking: each scan proves a shape, never an intent.",
904
+ "- `budgeted` = solid amber border + a faint amber box. Still drawn, because a declared bypass is still a bypass, but it is settled, not an open question.",
905
+ "- Which status is which: `split` fine dash · `bypassed` long dash · `dead` even dash · `gap` dotted · `budgeted` no dash.",
906
+ "- A fetched URL is a STRING, never an edge, because the reachability scan (§ Unreachable API calls) is the only check that sees it.",
907
+ "- Table rescanned every run, never stale.",
908
+ "- Detail-level module graph → `pnpm bkit:graph`. This doc is the altitude above that: capabilities, not files.",
863
909
  "",
864
910
  "## Status Vocabulary",
865
911
  "",
@@ -908,22 +954,6 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
908
954
  "## Import-time side effects",
909
955
  "",
910
956
  ] + eager_block(eager) + [
911
- "",
912
- "## Overrides",
913
- "",
914
- "The one hand-maintained region of this file. Everything else is rewritten on each run;",
915
- "this block is read back first and re-emitted verbatim. Rename a node, hide a node or an",
916
- "edge, pin a note, or force nodes into a named group. A malformed block aborts the run",
917
- "rather than being silently dropped. Every `hide_nodes` entry needs a one-line reason in",
918
- "`hide_nodes_why`.",
919
- "",
920
- OV_START,
921
- "",
922
- "```json",
923
- ov_text,
924
- "```",
925
- "",
926
- OV_END,
927
957
  "",
928
958
  "## User-facing routes → backend capabilities",
929
959
  "",
@@ -952,10 +982,9 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
952
982
  "```mermaid",
953
983
  as_mermaid(by_module, None, "module", min_weight, overlay).rstrip(),
954
984
  "```",
955
- "",
956
985
  ]
957
- with open(out, "w") as fh:
958
- fh.write("\n".join(D))
986
+ with open(out, "w", encoding="utf-8") as fh:
987
+ fh.write("\n".join([head, ""] + D + ["", tail]))
959
988
  print(f"[graph] {out}: {len(rows)} capabilities, {tally}")
960
989
 
961
990
 
@@ -104,7 +104,8 @@ Usage: pnpm bkit:graph[:clean|:update|:rollup|:refresh|:check|:graphml|:tree|:sc
104
104
  the register. Writes nothing tracked. Reads uncommitted
105
105
  edits — `check-at` does not.
106
106
  bkit:graph:refresh Rebuild the register in a clean checkout of the STAGED
107
- files (the index), copy it over docs/capabilities.md, and
107
+ files (the index), take its generated region (between
108
+ the graphify marker lines) into docs/capabilities.md, and
108
109
  rewrite the GRAPH_EMBED_DOCS copies. Stage your change
109
110
  first. Fixes a red gate; commit it.
110
111
  check-at <rev> `check` in a throwaway checkout of <rev>. Pre-push runs it
@@ -180,7 +181,7 @@ require_graph() {
180
181
  # and in CI (installs `$(bash scripts/graphify/bkit-graphify.sh spec)`). Another release draws
181
182
  # different edges → drift no one else can reproduce. PyPI `graphifyy`, CLI `graphify`.
182
183
  # renovate: datasource=pypi depName=graphifyy
183
- GRAPHIFY_SPEC="graphifyy[sql]==0.9.93"
184
+ GRAPHIFY_SPEC="graphifyy[sql]==0.9.111"
184
185
  if [ "${1:-}" = "spec" ]; then
185
186
  printf '%s\n' "$GRAPHIFY_SPEC"
186
187
  exit 0
@@ -234,10 +235,11 @@ repair() {
234
235
  # throwaway copy. Everything else written here ($REPORTS/*.json, the two .mmd)
235
236
  # is gitignored scratch in both modes, so one code path serves both.
236
237
  #
237
- # `check`'s copy must be SEEDED from the tracked doc. bkit-graphify-rollup.py reads
238
- # the hand-maintained Overrides block back out of the very file it is about to
239
- # overwrite (read_overrides(args.capabilities_doc)), so writing into an empty
240
- # path silently drops every override and reports the loss as drift.
238
+ # `check`'s copy must be SEEDED from the tracked doc. bkit-graphify-rollup.py rewrites
239
+ # only the text between the doc's two graphify marker lines, and reads the
240
+ # hand-maintained Overrides block out of the same file
241
+ # (read_overrides(args.capabilities_doc)), so writing into an empty path builds
242
+ # the starter's text and default overrides, and reports the difference as drift.
241
243
  capabilities() {
242
244
  local doc="$1"
243
245
  require_graph
@@ -285,6 +287,51 @@ embed() {
285
287
  python3 "$EMBED_PY" "$CAPABILITIES_DOC" "${docs[@]}" "$@"
286
288
  }
287
289
 
290
+ # Take the generated region of the built doc $1 (its two graphify marker lines and
291
+ # the text between them) into the working doc $2, and leave the rest of $2 as it
292
+ # is. A working doc without exactly one marker pair is absent, or generated from
293
+ # top to bottom, so the built doc replaces it whole.
294
+ adopt_region() {
295
+ python3 - "$1" "$2" <<'PYEOF'
296
+ import os
297
+ import re
298
+ import sys
299
+
300
+ START, END = "<!-- graphify:start -->", "<!-- graphify:end -->"
301
+
302
+
303
+ def frame(path):
304
+ if not os.path.exists(path):
305
+ return None
306
+ lines = open(path, encoding="utf-8").read().split("\n")
307
+ starts = [i for i, line in enumerate(lines) if line.strip() == START]
308
+ ends = [i for i, line in enumerate(lines) if line.strip() == END]
309
+ if len(starts) != 1 or len(ends) != 1 or starts[0] > ends[0]:
310
+ return None
311
+ return lines, starts[0], ends[0]
312
+
313
+
314
+ def overrides(lines):
315
+ m = re.search(r"<!-- overrides:start -->.*?<!-- overrides:end -->", "\n".join(lines), re.S)
316
+ return m.group(0) if m else ""
317
+
318
+
319
+ built_path, work_path = sys.argv[1:3]
320
+ built, work = frame(built_path), frame(work_path)
321
+ if built and work:
322
+ b, b_start, b_end = built
323
+ w, w_start, w_end = work
324
+ text = "\n".join(w[:w_start] + b[b_start:b_end + 1] + w[w_end + 1:])
325
+ if overrides(b) != overrides(w):
326
+ print(f"[graph] {work_path}: the Overrides block has unstaged edits, and the register "
327
+ "was built without them. Stage the file and run refresh again.", file=sys.stderr)
328
+ else:
329
+ text = open(built_path, encoding="utf-8").read()
330
+ with open(work_path, "w", encoding="utf-8") as fh:
331
+ fh.write(text)
332
+ PYEOF
333
+ }
334
+
288
335
  # Run this script's subcommands in a throwaway checkout of ONE commit: graphify reads the
289
336
  # working tree, so the build belongs to that commit, not to uncommitted edits here. Root
290
337
  # node_modules is linked in for the route scan. $1 = commit; an optional `--tree=<tree>`
@@ -403,13 +450,14 @@ case "${1:-build}" in
403
450
  at_commit "${2:-HEAD}" check
404
451
  ;;
405
452
  refresh)
406
- # Rebuild the register in a clean checkout of the staged files → copy over the tracked
407
- # file here. Staged = the commit about to be made, so running it before that commit
408
- # rebuilds the new state; unstaged edits stay out, as `bkit:graph:update && bkit:graph:rollup`
409
- # would not. Fixes a `check` / `check-at` red. Commit the result.
453
+ # Rebuild the register in a clean checkout of the staged files → take its generated
454
+ # region into the tracked file here. Staged = the commit about to be made, so running it
455
+ # before that commit rebuilds the new state; unstaged edits stay out of the build, as
456
+ # `bkit:graph:update && bkit:graph:rollup` would not, and an unstaged edit outside the
457
+ # region stays in the file. Fixes a `check` / `check-at` red. Commit the result.
410
458
  staged=$(git write-tree) || { echo "[graph] the index has unmerged paths — resolve them first" >&2; exit 1; }
411
459
  at_commit HEAD --tree="$staged" build register
412
- cp "$AT_DIR/$CAPABILITIES_DOC" "$CAPABILITIES_DOC"
460
+ adopt_region "$AT_DIR/$CAPABILITIES_DOC" "$CAPABILITIES_DOC"
413
461
  embed
414
462
  echo "[graph] $CAPABILITIES_DOC rebuilt from the staged files on $(git rev-parse --short HEAD) — commit it"
415
463
  ;;
@@ -84,6 +84,7 @@
84
84
  "files": [
85
85
  ".opencode/plugin/bkit-gateguard.js",
86
86
  ".opencode/plugin/bkit-readguard.js",
87
+ ".opencode/plugin/bkit-guardrails.js",
87
88
  ".opencode/plugin/bkit-rules.js"
88
89
  ],
89
90
  "rules": {
@@ -104,6 +105,7 @@
104
105
  "**/.codex/hooks/bkit-readguard.cjs",
105
106
  "**/.agents/plugins/bkit/hooks/bkit-readguard.cjs",
106
107
  "**/.opencode/plugin/bkit-readguard.js",
108
+ "**/.opencode/plugin/bkit-guardrails.js",
107
109
  "**/.opencode/plugin/bkit-rules.js",
108
110
  "**/.codex/hooks/bkit-rules.cjs",
109
111
  "**/.agents/plugins/bkit/hooks/bkit-rules.cjs"
package/CHANGELOG.md CHANGED
@@ -6,6 +6,85 @@ Format: `## [version] — YYYY-MM-DD`
6
6
 
7
7
  ---
8
8
 
9
+ ## [6.2.0] — 2026-11-17
10
+
11
+ ### Breaking Changes
12
+
13
+ - **BREAKING — Ten project docs are yours to edit; bkit ships them as starters and stops managing them.** `docs/{architecture,technology,security,data-schema,testing,deployments,observability,design,noise,setup}.md` leave managed ownership, and their starters live in `.bkit/templates/docs/`. `bkit upgrade` removes the `<!-- bkit:start -->` / `<!-- bkit:end -->` lines and the `bkit:managed` notice from each doc, keeps every other byte, and adds a row per doc to `## Project Documents` in `.agents/docs.md`. A doc with an ambiguous wrapper or a symlink is kept and reported. Later upgrades leave these docs alone, so merge starter changes by hand. See [#864 — Move project docs to templates with adoption warnings](https://github.com/cbartens/bkit/issues/864).
14
+ - **BREAKING — The sample lint-staged and Prettier-ignore configs have non-dotfile names.** `.bkit/templates/.lintstagedrc.json` → `.bkit/templates/lintstagedrc.example.json` and `.bkit/templates/.prettierignore` → `.bkit/templates/prettierignore.example`. `bkit upgrade` removes the old samples and writes no root config. A repo whose `bkit:gate:format` runs `lint-staged` without `--config` and has no root lint-staged config fails every commit; install, check and upgrade print `no root lint-staged config — commits will fail. Fix: cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json`. See [#892 — Template copies under .bkit/templates can't be committed after upgrade](https://github.com/cbartens/bkit/issues/892).
15
+ - **BREAKING — A gate that holds the tests lock needs `node` and the current `bkit-test-awake.mjs` beside the lock script.** `scripts/ci/bkit-machine-lock.sh run --lock tests` starts its command under `node bkit-test-awake.mjs --hold-s <limit>`. Without `node` on `PATH`, or without a `bkit-test-awake.mjs` that accepts `--hold-s` in the same folder, `run` writes `outcome=refused` and exits 73. The command must be a program on `PATH`, so wrap shell code in `sh -c`. `bkit upgrade` replaces unedited copies of both files and adds a missing `bkit-test-awake.mjs` beside an adopted lock script; an edited copy is kept with a warning to merge the template by hand. See [#998 — Tests lock: one gate runner, one stale-holder rule, one process supervisor](https://github.com/cbartens/bkit/issues/998).
16
+ - **BREAKING — `bkit issues comment` posts for workflow steps only.** Without proof of a workflow run (a session folder in the outbox, a status file holding a run, or an audit body file in its outbox folder) it exits 2 and posts nothing. Post ordinary comments as plain Markdown through the tracker MCP, so later workflow runs read them as human input. The check guards against misuse and is not a security boundary. See [#918 — Ad-hoc agent comments carry bkit:generated, so workflows drop them](https://github.com/cbartens/bkit/issues/918).
17
+
18
+ ### Added
19
+
20
+ - **Each workflow run keeps one progress comment on its issue.** Routine step reports are appended to the run's own comment on GitHub, Linear and Jira. A Decision Pause, a failure, a handover and the closing summary each arrive as a new comment, and a later human comment starts a fresh progress comment. `bkit issues comment --purpose routine|attention|terminal` selects the kind. See [#826 — Append routine workflow step updates to one comment per run](https://github.com/cbartens/bkit/issues/826).
21
+ - **Cloud runs can use Codex, and every cloud agent works with any wired tracker.** `bkit install --auto=codex --codex` records `bkit.cloud.agent: "codex"`, and the `bkit-cloud.yml` router gains a codex job that reads `BKIT_OPENAI_API_KEY`. Install refuses only tracker `none`. The codex job is not yet verified on a live run. See [#719 — Cloud variants: add --auto=codex and allow any tracker](https://github.com/cbartens/bkit/issues/719).
22
+ - **Build tells tests that already fail on the base branch apart from tests the feature broke.** `bkit tests base` labels each failing test base-red or branch-red and prints a verdict of `all`, `some`, `none` or `unknown`. The owner can accept the exact base-red tests once; later gates in that run stop only on new failures. See [#891 — Build: gate stuck on tests already red on dev, owner accept ignored](https://github.com/cbartens/bkit/issues/891).
23
+ - **Runs waiting for the tests lock are served in arrival order.** Each waiter takes a ticket in `<name>.queue/`, the waiting note names its place in line, and a waiter that gives up keeps its place for 120 seconds. `bkit-machine-lock.sh queue` prints the line, and `bkit tests jump <run>` moves one run to the front after human approval. `BKIT_TEST_SLOTS` defaults to 2 on a local machine with 8 or more cores, else 1; `bkit-machine-lock.sh slots` prints the slot and worker counts. See [#916 — Tests lock: waiting runs win at random, so one can wait out its limit](https://github.com/cbartens/bkit/issues/916).
24
+ - **A hung test run gives the tests lock back.** The `run` that took the `tests` lock stops its command after `LOCAL_STACK_LOCK_HOLD_S` seconds (default 3600) plus `LOCAL_STACK_LOCK_HOLD_GRACE_S` (default 10) and exits 124. `bkit tests run`, `bkit tests changed` and `bkit branches push` read the outcome from the file named by `LOCAL_STACK_LOCK_STATUS_FILE`: a wait that gave up exits 81 with `lockHolder`, and a refusal or a stopped run exits 4 with no verdict, never FAIL. Set a longer limit per gate, for example `LOCAL_STACK_LOCK_HOLD_S=10800`. See [#928 — Tests lock: a hung run holds it forever, so every push waits](https://github.com/cbartens/bkit/issues/928).
25
+ - **The pre-push hook loads `.envrc` itself.** When the repo has an `.envrc`, `direnv` is on `PATH` and `CI` is unset, the gate runs through `direnv exec .`. An `.envrc` that direnv cannot load blocks the push in seconds, with the `direnv allow .` fix when the file is untrusted. The gate also unsets the bkit tooling keys and every key `.bkit/.env` names. A repo whose hook copy lacks this gets the `pre-push-direnv` tip. See [#922 — Pre-push: load direnv itself; block in seconds if untrusted](https://github.com/cbartens/bkit/issues/922).
26
+ - **The pre-push hook blocks a push whose open PR conflicts with its base.** It looks up the branch's open PR, fetches the base, and runs a trial `git merge-tree`; a conflict blocks the push and names the files. When `gh` is missing, the clone is shallow or the fetch fails, the hook warns and the push goes on. `BKIT_PR_CONFLICT_CHECK=false` skips the check, and `/bkit-ship` and `/bkit-debug` set it on their own pushes. A repo whose hook copy lacks this gets the `pre-push-pr-conflict` tip. See [#923 — Pre-push: block in seconds when the PR conflicts](https://github.com/cbartens/bkit/issues/923).
27
+ - **The engine does the run bookkeeping that agents used to do by hand.** `bkit status invocation` issues an id per agent call, and `bkit ledgers append` fills the writer and model from it. An `--operation` id makes a repeated write return the first result, `bkit ledgers query` reads ledger rows, and `bkit steps stub` and `bkit issues comment` take `--result-file`. CI polling state survives a resume. `bkit runs dispatch` takes `--invocation` and drops `--poll-result`, `--attempts`, `--all-errored` and `--retriggered`. See [#860 — Move deterministic bookkeeping and safe recovery into the engine](https://github.com/cbartens/bkit/issues/860).
28
+ - **Every repo gets a `## Project Goals` section, and any agent may record a gotcha.** New installs carry `## Project Goals` in `.agents/rules.md` between `## Project Rules` and `## Project Settings`, and every agent prompt breaks ties by it without lowering a severity or softening a verdict. A repo installed earlier gets the `project-goals` tip on design and plan runs, because bkit never writes below `bkit:end`. The new `Discovered gotchas` rule has agents append a row to `docs/knowledge.jsonl` with `bkit ledgers append`. See [#1011 — Rules: ship a Project Goals section and name it in every prompt](https://github.com/cbartens/bkit/issues/1011).
29
+ - **The doc starters say how to fill them, and in what order.** Each of the twelve starters in `.bkit/templates/docs/` opens with fill-in steps, `docs/components.md` is new, and `.bkit/templates.md` § Project docs — adoption order names the sequence. `bkit check` and `bkit upgrade` raise `project-docs-unpopulated` for a doc that still holds starter text, and the upgrade report marks an adopted starter that changed. Prompts warn and continue when a doc is missing, and record the gap under `Documentation Warnings`. See [#887 — Review doc starters: population steps, order and shared rules](https://github.com/cbartens/bkit/issues/887).
30
+ - **Authoring rules show before shell edits too.** The edit guard prints the rules for a file an agent is about to change through a shell command, never runs the inspected code, and never blocks. `bkit upgrade` keeps a consumer's own hook groups and permission entries in managed settings files. See [#787 — Show authoring rules before every edit, including shell edits](https://github.com/cbartens/bkit/issues/787).
31
+ - **A later task can take over an earlier task's planned test.** A task names the earlier test on its own TEST FIRST line, and `bkit tests plan-check` lists it under takeovers. When a code step contradicts a ticked task's planned test, `bkit steps finish` adds a takeover task and a `build-takeover` row, and `bkit tasks takeover --pending` prints the group still to run. See [#978 — Build: no path for a later task to change an earlier planned test](https://github.com/cbartens/bkit/issues/978).
32
+
33
+ ### Changed
34
+
35
+ - **Build re-tests only what changed between fix rounds.** `bkit tests run --changed-since=<sha>` tests the files that differ from the newest passing run, so a doc-only fix round runs no tests, and the full suite runs once before the build ends. A passing run of the exact push gate is recorded for that commit, and the first push reuses it. See [#951 — Build: repeat whole-feature checks re-check everything, costing hours](https://github.com/cbartens/bkit/issues/951).
36
+ - **A failed whole-feature verify goes to a fix round instead of ending the run.** `bkit.workflows.build.holistic` (default `{ "ask": true, "maxAttempts": 2 }`) sets the fix rounds per run, and the engine picks each round's strategy from the tests that keep failing. A pause where the owner accepts every item continues without re-running the check. `bkit upgrade` lowers `bkit.workflows.build.verify.maxAttempts` to 2 once when it is higher; a value raised after that is kept. See [#965 — Build fix loop: one engine-decided rule for resume, skip and re-test](https://github.com/cbartens/bkit/issues/965).
37
+ - **Build and debug agents run only named test files while they work.** The `Local pre-commit` rule covers mid-step runs: name each test file, never a folder, a pattern, the full suite or a `bkit:gate:*` script. See [#920 — Build agents run folder-wide tests mid-step and block other worktrees](https://github.com/cbartens/bkit/issues/920).
38
+ - **The planned-test lock holds for every later step of a build run.** A code step that must change a planned test names it on a `BLOCKED` line; the change goes through, is recorded and is listed for the owner. See [#914 — Build: test lock fires late across groups, BLOCKED escape unread](https://github.com/cbartens/bkit/issues/914).
39
+ - **Build diffs start where the feature's own work starts.** Build, challenge and verify diffs measure from the later of the branch's meeting points with `origin/dev` and with local `dev`, so unpushed local `dev` commits stay out of the feature's diff. The scans that judge what a push publishes still compare against `origin/dev`. See [#960 — Build diffs count unpushed local dev commits as the feature's](https://github.com/cbartens/bkit/issues/960).
40
+ - **Ship reconciles the local and remote feature branches before it picks a path.** It pushes unpublished commits, merges the remote branch when both sides moved, and refuses a branch that carries unpushed `dev` commits before opening a PR. A merged PR with newer local commits gets a new PR, and a merge GitHub refuses routes back to validation. No push is forced. See [#842 — Ship fails when the local feature branch differs from GitHub's](https://github.com/cbartens/bkit/issues/842).
41
+ - **`/bkit-ship` has 12 steps and hands red CI to `/bkit-debug`.** Ship no longer diagnoses or fixes a failure itself; a red-CI stop names `/bkit-debug {FID}` as the next step. `bkit prs checks` counts cancelled, action-required and stale checks apart from failed ones, and the last step waits for CI on the merge commit. See [#911 — Ship: a failed merge never reaches the diagnose and fix steps](https://github.com/cbartens/bkit/issues/911).
42
+ - **Plan and design leave the feature branch local.** Plan Step 7 and design Step 10 no longer push it, so no remote branch or worktree is left behind. See [#976 — Plan: Step 7 push leaves the remote branch and worktree behind](https://github.com/cbartens/bkit/issues/976).
43
+ - **Every owner question uses one format.** Questions carry lettered options, a `Recommended:` line and a `Default if unanswered:` line, and `bkit tasks tick --decision` reads the lettered answers. See [#895 — One question format for every owner question in the workflows](https://github.com/cbartens/bkit/issues/895).
44
+ - **Agent effort follows the role.** Review, challenge, plan-currency, deferred-sweep and soak agents run at `xhigh`, design and plan writers at `high`, and builders at `medium`. See [#977 — Effort by role: high to design, xhigh to review, medium to build](https://github.com/cbartens/bkit/issues/977).
45
+ - **The shell guard parses commands and denies on every host.** It reads nested shells, `eval`, `xargs`, `find -exec`, process substitution and wrappers such as `timeout`, `env` and `nice`. A force push without `--force-with-lease`, `rm -rf` on `/`, `~` or `$HOME`, and a world-writable `chmod` on `/` are denied on all five hosts; `sudo` and `doas` ask. `bkit upgrade` replaces an unedited `.claude/hooks/bkit-guardrails.cjs` driver so the deny takes effect, and prints the line to add for an edited one. A command longer than 256 KiB, or one the parser cannot finish in time, is allowed. See [#967 — Shell guard: block with the new parser, warn only on known writers](https://github.com/cbartens/bkit/issues/967).
46
+ - **Codex and OpenCode close three guard gaps.** Codex refuses a command that prints or sends a private key's content; this is not verified on a real Codex host. OpenCode gets no derived allow rules for `curl` or `wget`, so every shell fetch asks, and uninstall strips only the grants bkit added. The Claude cloud bootstrap compares `BKIT_CLOUD_ALLOWLIST_FINGERPRINT` with the `fingerprint` in `.bkit/allowlist.json`, warns on a mismatch and continues. See [#803 — Close the Codex and OpenCode guard gaps (key reads, curl/wget, grants)](https://github.com/cbartens/bkit/issues/803).
47
+ - **The cloud router is one file that reads `BKIT_`-prefixed secrets.** `bkit-cloud.yml` picks the claude, opencode or codex job from `bkit.cloud.agent` and reads the opt-in label through the tracker verbs. The post-install check names an adopted copy that needs attention (`cloud-router-tracker-stale`, `cloud-router-codex-missing`, `cloud-router-agent-unset`, `cloud-router-secret-renamed`) and changes nothing. A copy that still reads the old secret names keeps them until you re-copy it.
48
+ - **The light pre-push gate accepts the audit reports bkit writes.** A push that changes only files bkit writes runs `bkit:gate:min` instead of the full gate. That set includes `docs/audits/**` and an edit to the `Project Instructions` section below `<!-- bkit:end -->` in a `docs/templates/bkit-audit-*.md`. See [#915 — Min-push ignores the audit reports bkit writes](https://github.com/cbartens/bkit/issues/915).
49
+ - **graphify rewrites `docs/capabilities.md` only between its markers.** `bkit-graphify-rollup.py` writes between `<!-- graphify:start -->` and `<!-- graphify:end -->`; one marker alone, markers out of order, or a hand-written doc with no markers stops the run. The pinned graphify version is 0.9.111. See [#1027 — Doc starters: capabilities markers and a stricter unfilled-doc check](https://github.com/cbartens/bkit/issues/1027).
50
+ - **The Renovate and Dependabot samples stop rebasing their own PRs.** `.github/renovate.json5` sets `rebaseWhen: "never"` and `.github/dependabot.yml` sets `rebase-strategy: disabled`. See [#617 — Harden the Renovate examples: preset, runner image, majors, ignores](https://github.com/cbartens/bkit/issues/617).
51
+
52
+ ### Fixed
53
+
54
+ - **The owner's Fix now answer is carried out.** Build rewrites the challenge task's DONE WHEN and TEST FIRST lines and adds a Fix task, and the run summary credits a fix that a later verify confirmed. See [#903 — Build: owner's Fix now answer is lost after the Decision Pause](https://github.com/cbartens/bkit/issues/903).
55
+ - **`bkit tasks tick` and `bkit tests plan-check` read their inputs strictly.** `tasks tick --green` reads gaps only from `## Gaps` and exits 2 on a report with no Gaps section or fewer gap lines than its header counts. `tests plan-check` requires the Derived Test Matrix header `Test description | Type | Target file | Task` and refuses a row without four cells. See [#989 — tasks tick reads gaps and accepted tasks too loosely](https://github.com/cbartens/bkit/issues/989).
56
+ - **The debug loop recommends Stop only on counts it can compare.** The trend reads "unknown" when a round's counts are missing or two rounds ran different tests. A debug run stopped on `dev` and resumed keeps its fix commits: `bkit workflows handover --push` records them and `bkit worktrees setup` rebuilds the list. See [#971 — Debug: Stop on dev then resume leaves fix commits unpushed](https://github.com/cbartens/bkit/issues/971).
57
+ - **`bkit runs context` hands over the right CI run.** It asks only for runs of `bkit.testing.ciWorkflow` at the PR head, gives debug the newest failed run and ship the newest run, and exits 8 when nothing matches. See [#972 — Auto: runs context can hand debug the wrong CI run](https://github.com/cbartens/bkit/issues/972).
58
+ - **A cloud ship waiting on CI is not cancelled when that CI finishes.** A router start with nothing to do gets its own concurrency group, `skip-<run id>`. Re-copy `.bkit/templates/.github/workflows/bkit-cloud.yml` to get it. See [#973 — Cloud: a ship waiting on CI is cancelled when that CI finishes](https://github.com/cbartens/bkit/issues/973).
59
+ - **Resuming a design or plan run keeps the owner's answers.** `bkit workflows input` re-appends the interview file on resume, and the owner-answers round runs in the main checkout and commits `status.jsonl`. See [#975 — Design: resuming a run erases the owner's interview answers](https://github.com/cbartens/bkit/issues/975).
60
+ - **Resume no longer trips over its own files.** The rebase note lives in the worktree's git dir as `bkit-rebase-note.md`, a `.bkit/.env` entry in `bkit.workflows.worktree.copy` copies cleanly, debug adopts a branch without rebasing it, and a CI evidence URL inside a Markdown link parses. See [#888 — Resumed rebase fails: setup writes the tracked rebase log mid-rebase](https://github.com/cbartens/bkit/issues/888).
61
+ - **Ship stops cleanly.** An owner Stop on an open PR does not end the run as a failure, a tests-lock wait in the push gate leaves the gate receipt alone, and `bkit workflows fail --next-step` refuses a bad value with exit 6 before it writes anything. See [#997 — Workflows: five step routes move from prose into the engine](https://github.com/cbartens/bkit/issues/997).
62
+ - **The session tracker guard stops on a tracker it does not know.** `preflight-tracker.sh` rejects an unknown tracker name and a `GITHUB_ISSUE_ID` that is not digits, and `bkit check` reports `tracker-setup-unknown` as a blocker. Values rendered into Markdown stay on one line. See [#968 — Sweep the deferrals and failures parked since v6.1.1 before v6.2](https://github.com/cbartens/bkit/issues/968).
63
+ - **Gate logs keep pnpm's own lines under `pnpm -s`.** Gate, lint and test logs hold the script pnpm ran and its exit code, so a gate that fails without printing still leaves evidence in its log. See [#931 — Gate logs lose pnpm's lines under pnpm -s, failing the pre-push gate](https://github.com/cbartens/bkit/issues/931).
64
+ - **Build and debug report a removed `bkit:auto` label in their final message.** The label's removal stops nothing mid-run, and the workflow docs say so. See [#986 — Docs claim more bkit:auto kill-switch enforcement than exists](https://github.com/cbartens/bkit/issues/986).
65
+ - **`doas` asks before it runs, as `sudo` does.** The shipped Claude Code and OpenCode settings put `doas` on the ask list.
66
+ - **Build and debug spell out their resume and pause routes one instruction per line.** The build Resume and gap-pause routes and the debug Resume, Foreign path and Failure Reproduce routes read as labelled route blocks; no run goes anywhere new.
67
+
68
+ ### Upgrade Notes
69
+
70
+ - Run `bkit upgrade` to refresh managed files. It strips the managed markers from the ten project docs, replaces unedited copies of `scripts/ci/bkit-machine-lock.sh`, `scripts/ci/bkit-test-awake.mjs` and the `.claude/hooks/bkit-guardrails.cjs` driver, and removes the old dotfile-named samples. If the repo has no root lint-staged config, run `cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json`.
71
+ - Re-copy these changed templates from `.bkit/templates/` where adopted, merging consumer customizations; adopted copies are consumer-owned and are not overwritten automatically: `.husky/pre-push`; `scripts/ci/bkit-machine-lock.sh`, `scripts/ci/bkit-test-awake.mjs` and `scripts/ci/bkit-test-awake.test.mjs`; `.github/workflows/bkit-cloud.yml`, `bkit-ci.yml` and `bkit-renovate.yml`; `.github/renovate.json5`, `.github/dependabot.yml` and `.github/ISSUE_TEMPLATE/bkit-idea.yml`; `.claude/hooks/bkit-cloud-bootstrap.sh`; `.cursor/Dockerfile`; `scripts/graphify/bkit-graphify.sh`, `bkit-graphify-rollup.py` and `bkit-graphify-graphml.py`; `slop-scan.config.json`; `context/bkit-serena.md`; and the starters under `docs/`. When you re-copy `bkit-cloud.yml`, set the `BKIT_`-prefixed secrets and run `pnpm bkit install --auto=<claude|opencode|codex>` to record `bkit.cloud.agent`.
72
+
73
+ ## [6.1.1] — 2026-11-04
74
+
75
+ ### Fixed
76
+
77
+ - **Cancelling a shell test chain waits for descendant cleanup.** The awake wrapper stops the running command, prevents the next shell command from starting, and holds sleep prevention until cleanup finishes. Direct commands retain their lock-owner lifecycle.
78
+ - **Default prose discovery stays within the current checkout.** `bkit ci prose` selects tracked and unignored Markdown, excludes nested checkouts, and fails when selected sources cannot be read. Explicit `--glob` selections still allow intentional ignored or nested paths.
79
+ - **Upgrade diagnostics distinguish script commands from comments and prose.** Script-name migration warnings now identify executable invocations. Tracker rendering preserves indentation without exposing trailing whitespace in installed host files. These changes address [#855 — 6.1 consumer adoption: cancellation and validation regressions](https://github.com/cbartens/bkit/issues/855).
80
+ - **OpenCode runtime files no longer make an uninstalled integration look broken.** Status and doctor use the managed agents directory to detect the host, preserving consumer runtime files.
81
+ - **The Vercel runtime recipe supports CLI 64 and 65.** It provisions CLI 65.0.0, reads typed log records and continuation cursors, and reports excluded intervals, failed pages and page limits explicitly.
82
+ - **Trivy guidance names the emitted `bkit-trivy` check.** Doctor detects stale required `trivy` checks and gives coordinated migration instructions that preserve branch protection. It changes no remote settings. The accepted-divergence template also removes an unnecessary field-normalization wrapper. These changes address [#856 — 6.1 upgrade: host detection, Vercel recipe and naming drift](https://github.com/cbartens/bkit/issues/856).
83
+
84
+ ### Upgrade Notes
85
+
86
+ - Run `bkit upgrade` to refresh managed files. Re-copy the awake wrapper and its tests, the Vercel context recipe, and the accepted-divergence guard from `.bkit/templates/` where adopted, merging consumer customizations. Existing adopted copies are consumer-owned and are not overwritten automatically. Coordinate any required-check rename with the workflow change and verify `bkit-trivy` before requiring it.
87
+
9
88
  ## [6.1.0] — 2026-11-04
10
89
 
11
90
  ### Breaking Changes