@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
@@ -13,7 +13,7 @@
13
13
 
14
14
  ## What each template is for
15
15
 
16
- The adoption order is the `bkit tips` order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
16
+ The adoption order of the tool templates is the `bkit tips` order; for the project docs it is § Project docs — adoption order. The machine lock has no tip, so adopt it when test gates or local services need to run one at a time across checkouts. The health check has no tip either: the `bkit-stub-health` advisory raises it while your CI copy keeps that stub. The sections below give each template's install steps and traps.
17
17
 
18
18
  <!-- prettier-ignore -->
19
19
  | Template | What it's for | Skip it and |
@@ -33,12 +33,13 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
33
33
  | Secrets sync | One local file → every secret store; proves copies match without printing values. | Hand-copied secrets drift: "works for me, broken in production". |
34
34
  | Issue forms | Three forms (idea, well-defined change, bug) asking for what design, plan / build and debug read first. | Issues arrive as a title and a line; agents guess at scope, "done" and repro steps. |
35
35
  | graphify | Code map (`docs/capabilities.md`) agents check before building something again. | Agents rediscover structure each run; ripple effects missed. |
36
+ | Component map | Purpose-based overview of the repository's responsibilities and main journeys. | Readers have to infer what the system does from implementation details. |
36
37
  | Dependabot / Renovate | Small grouped update PRs; pinned Actions; security fixes skip the queue. | Updates pile into one large risky upgrade. |
37
38
  | Trivy | Fails CI on a known-vulnerable package in any language, a risky container or cluster setting, or a committed secret; a daily run catches advisories with no fix yet. | A vulnerable package or leaked key merges unnoticed; an advisory with no fixed release never shows up anywhere. |
38
39
  | Prettier tables | One edited cell = one changed row in the diff. | A one-word table edit diffs as the whole table. |
39
40
  | tmp/ prune | Each push deletes scratch files agents left in `tmp/` untouched for a week. | `tmp/` keeps growing; old logs and scratch files are never cleared. |
40
41
  | Disk prune | Your own cleanup steps (build caches, Docker, simulators) run on commit, on push, and before a worktree is made on a low disk. bkit deletes nothing itself. | Caches fill the disk until no worktree can be made; every workflow stops. |
41
- | Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder. | Test gates compete for CPU, or a reset stops the stack under another worktree's test run. |
42
+ | Machine lock | Named locks run one gate at a time across repositories; the unnamed lock protects local services every worktree shares. A second run waits and names the holder, and `run` stops a command that holds the tests lock past the hold limit. | Test gates compete for CPU, a reset stops the stack under another worktree's test run, or a hung gate holds the lock and every push waits. |
42
43
  | Cursor editor + cloud agent | Format-on-save, recommended extensions, Cursor cloud-agent image. | Cursor edits miss project formatting; no Cursor cloud agent. |
43
44
  | Launchd GUI env | macOS apps opened from the Dock get the same tokens as the terminal. | Dock-launched editors start signed out. |
44
45
 
@@ -52,8 +53,8 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
52
53
  | Health check | `.bkit/templates/.github/workflows/bkit-health.yml` | `.github/workflows/bkit-health.yml` | that file |
53
54
  | Cloud-agent workflow | `.bkit/templates/.github/workflows/bkit-cloud.yml` | `.github/workflows/bkit-cloud.yml` | that file |
54
55
  | Git hooks (Husky) | `.bkit/templates/.husky/pre-commit`, `.bkit/templates/.husky/pre-push` | `.husky/pre-commit`, `.husky/pre-push` | both files |
55
- | Prettier ignore list | `.bkit/templates/.prettierignore` | `.prettierignore` | that file |
56
- | lint-staged | `.bkit/templates/.lintstagedrc.json` | `.lintstagedrc.json` | that file |
56
+ | Prettier ignore list | `.bkit/templates/prettierignore.example` | `.prettierignore` | that file |
57
+ | lint-staged | `.bkit/templates/lintstagedrc.example.json` | `.lintstagedrc.json` | that file |
57
58
  | Vale | `.bkit/templates/.vale.ini`, `.bkit/templates/.vale/styles/Bkit/` | `.vale.ini`, `.vale/styles/Bkit/` | `.vale.ini` + the four Bkit styles |
58
59
  | slop-scan | `.bkit/templates/slop-scan.config.json`, `.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs` | `slop-scan.config.json`, `scripts/slop/bkit-slop-type-suppression.mjs` | both files |
59
60
  | Oxlint | `.bkit/templates/.oxlintrc.json` | `.oxlintrc.json` | that file |
@@ -67,14 +68,15 @@ The adoption order is the `bkit tips` order. The machine lock has no tip, so ado
67
68
  | Serena | `.bkit/templates/scripts/serena/`, `.bkit/templates/.serena/project.yml` | `scripts/serena/`, `.serena/project.yml`, merge `bkit-serena.mcp.json` into `.mcp.json` | `project.yml` only |
68
69
  | Issue forms | `.bkit/templates/.github/ISSUE_TEMPLATE/` | `.github/ISSUE_TEMPLATE/` | the forms you use |
69
70
  | graphify | `.bkit/templates/scripts/graphify/`, `.bkit/templates/.graphifyignore`, `.bkit/templates/docs/capabilities.md` | same paths at the repo root | `docs/capabilities.md` |
71
+ | Component map | `.bkit/templates/docs/components.md` | `docs/components.md` | the populated document |
70
72
  | Secrets sync | `.bkit/templates/scripts/secrets/` | `scripts/secrets/` | both files; never `bkit-secrets-state.json` |
71
73
  | Prettier tables | `.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs` | `scripts/prettier/` | that file |
72
74
  | tmp/ prune | `.bkit/templates/scripts/cleanup/bkit-tmp-prune.mjs` | `scripts/cleanup/` | that file |
73
75
  | Disk prune | `.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs`, `bkit-disk-prune.machine.mjs` | `scripts/cleanup/bkit-disk-prune.mjs`, `~/.config/bkit/disk-prune.mjs` | `scripts/cleanup/bkit-disk-prune.mjs` only |
74
- | Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh` | `scripts/ci/` | that file |
76
+ | Machine lock | `.bkit/templates/scripts/ci/bkit-machine-lock.sh`, `bkit-test-awake.mjs` | `scripts/ci/` | both files |
75
77
  | Local test sleep prevention | `.bkit/templates/scripts/ci/bkit-test-awake.mjs`, `bkit-test-awake.test.mjs` | `scripts/ci/` | both files |
76
78
  | Context-fetch blocks | `.bkit/templates/context/bkit-<provider>.md` | below `<!-- bkit:end -->` in `.agents/context.md` | the blocks you use |
77
- | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file |
79
+ | Cloud SessionStart hook | `.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh` | `.claude/hooks/bkit-cloud-bootstrap.sh` | that file; it compares `BKIT_CLOUD_ALLOWLIST_FINGERPRINT` with `.bkit/allowlist.json` and warns on a mismatch, and `bkit check` raises `cloud-bootstrap-fingerprint-missing` for a copy that never reads the variable |
78
80
 
79
81
  Placeholders: the copies keep them raw, so replace each one in your copy:
80
82
 
@@ -83,14 +85,14 @@ Placeholders: the copies keep them raw, so replace each one in your copy:
83
85
  | --- | --- | --- | --- |
84
86
  | `{{DEFAULT_BRANCH}}` | `bkit-ci.yml` (`on.push` / `on.pull_request` branches; stub comments), `bkit-trivy.yml` (`on.push` / `on.pull_request` branches), `bkit-health.yml` (`on.workflow_run` branches) | your production branch | `origin/HEAD` unless it is `dev`, else `main` |
85
87
  | `{{PRODUCTION_URL}}` | `bkit-health.yml` (`env.PRODUCTION_URL`) | the origin production serves | `https://example.com` |
86
- | `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
88
+ | `{{NODE_VERSION}}` | `bkit-ci.yml` (`actions/setup-node` `node-version`, both lanes), `bkit-cloud.yml` (`actions/setup-node` `node-version`, the context job's bkit install) | your Node major, or swap the line for `node-version-file: .nvmrc` | `.nvmrc`, then `engines.node`, then `22` |
87
89
  | `{{CLOUD_RUNNER}}` | `bkit-cloud.yml` (`runs-on`, all three jobs) | a runner label | `ubuntu-latest` |
88
90
  | `{{SCRIPT_PATH}}` | `bkit-launchd.plist` (`ProgramArguments`) | absolute path to the loader script, outside a TCC-protected folder (see § Launchd GUI environment) | `/Users/<you>/.config/bkit/bkit-launchd-env.sh` |
89
91
  | `{{ENV_FILE}}` | `bkit-launchd.plist` (`ProgramArguments`, `WatchPaths`) | absolute path to your env file | `/Users/<you>/.config/bkit/launchd.env` |
90
92
 
91
93
  - `bkit install` / `bkit upgrade` refresh `.bkit/templates/` to the package's templates, unsubstituted. `bkit check` fails on a stale copy. `bkit uninstall` removes the folder, never an adopted copy.
92
94
  - **What changed on upgrade.** `bkit upgrade` lists the changed, added and removed template paths. For each one you adopted, run `diff .bkit/templates/<path> <path>`, and merge what you want. The placeholder lines differ by design. `git diff .bkit/templates` in the upgrade commit shows the package change.
93
- - Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The `.prettierignore`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do. Check that your adopted copy does too.
95
+ - Repo gates that scan the whole repo (prettier, Vale, slop-scan, eslint, tsc) must ignore `.bkit/templates/`. The `prettierignore.example`, `.vale.ini`, `slop-scan.config.json` and `.oxlintrc.json` templates already do. Check that your adopted copy does too.
94
96
  - Templates are written in Node unless the tool they wrap already needs another runtime (graphify and Serena: Python and shell launchers; git hooks: POSIX `sh`; local stack lock: bash and perl, because shell runners source it).
95
97
  - `bkit.dependencies.updater` names the adopted updater (`"renovate"` / `"dependabot"`). Install fills it from the config present. `"none"` skips the install-time absence advisory. `bkit check` blocks when the setting and the configs disagree.
96
98
  - No template has a manifest key. `docs/templates/bkit-audit-adoption.md` lists every template on each run, as adopted and wired, or as not adopted with the reason.
@@ -116,7 +118,7 @@ For selected CI, `context fetch --ci-selection-file` supplies the four `BKIT_CI_
116
118
  | `bkit-maestro.md` | Maestro iOS and Android lanes on GitHub Actions | `e2e` | every failed Maestro job's log, sliced to the result steps, each slice tail-bounded | `GH_TOKEN` / `MAESTRO_JOB_RE`, `MAESTRO_STEPS`, `MAESTRO_LOG_TAIL` | — | `gh` (base tool) |
117
119
  | `bkit-tavily.md` | any | `web` | web search for upstream causes (untrusted output) | `BKIT_TAVILY_API_KEY` / `QUERY` | — | — |
118
120
  | `bkit-sentry.md` | Sentry | `runtime` | unresolved issues seen in a window (organization issues endpoint), optional environment; trace / window recipes; detector-header strip | `SENTRY_AUTH_TOKEN` / `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_HOST`, `SENTRY_SINCE`, `SENTRY_ENV`, `SENTRY_N` | `sentry.io` | — |
119
- | `bkit-vercel.md` | Vercel | `runtime` | serverless + edge error / fatal logs in a window, paged past the CLI's 50-line cap, all branches (`--no-branch`) | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel` (yes) |
121
+ | `bkit-vercel.md` | Vercel | `runtime` | error / fatal logs in a window, typed records and summary cursors; excluded intervals, failed pages and page caps reported explicitly | `VERCEL_TOKEN` / `VERCEL_SCOPE`, `VERCEL_PROJECT`, `VERCEL_ENV`, `SINCE`, `UNTIL`, `VERCEL_MAX_PAGES` | `vercel.com` | `vercel@65.0.0` (yes; installed 64.x / 65.x supported) |
120
122
  | `bkit-supabase.md` | hosted Supabase | `runtime` | Postgres `ERROR` / `FATAL` / `PANIC` counts per hour, severity, SQLSTATE and role; one call per day of window | `SUPABASE_ACCESS_TOKEN` / `SUPABASE_PROJECT_ID`, `SINCE_ISO`, `UNTIL_ISO` | `supabase.com` | — |
121
123
  | `bkit-stripe.md` | Stripe | `runtime` | failure / dispute / refund events, filtered by type and window at the source, paged; events whose webhook delivery failed | `STRIPE_SECRET_KEY` / `STRIPE_SINCE_S`, `STRIPE_MAX_PAGES` | `stripe.com` | — |
122
124
  | `bkit-resend.md` | Resend | `runtime` | bounced / complained / failed / delayed sends, paged back to the window start | `RESEND_API_KEY` / `SINCE_ISO`, `RESEND_MAX_PAGES` | `resend.com` | — |
@@ -190,10 +192,12 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
190
192
  - **If** you have your own linter → chain both: `<your linter> && oxlint -c .oxlintrc.json --type-aware --deny-warnings`.
191
193
  - **If** there is no `tsconfig.json` → use `"typecheck": "echo \"[bkit] typecheck: no tsconfig.json — skipping\" >&2"`.
192
194
  - `bkit:slop:delta` runs `bkit ci slop` (the bkit devDep is on `PATH` through the package script). CI passes the base sha as its one bare argument.
193
- - `bkit:lint:prose` runs `bkit ci prose`: Vale over every `*.md` outside `node_modules/`. Narrow it with the repeatable `--glob=<pattern>` (`*`, `**`, `?`, relative to the repo root), for example `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
195
+ - `bkit:lint:prose` runs `bkit ci prose`: Vale over tracked and unignored untracked Markdown in the current Git checkout, excluding nested checkouts. Outside Git, it walks Markdown files while skipping nested checkouts. Both defaults skip `node_modules/` and `.git/`; unavailable source reads fail the gate. Explicit, repeatable `--glob=<pattern>` selections (`*`, `**`, `?`, relative to the repo root) can intentionally include ignored or nested paths, for example `bkit ci prose --glob='docs/*.md' --glob='.agents/*.md'`.
194
196
  - **If** the stack is not Node → point each gate at your own commands, and keep the gate names.
195
197
  - `bkit:test:file` runs one test file and writes a JUnit report to `$BKIT_TEST_REPORT`. bkit appends the file's repo-relative path. `/bkit-build` reads the report for test-first. It is not seeded, and `test-file-script-missing` fires until it is declared.
196
198
  - Vitest: `"bkit:test:file": "vitest run --reporter=default --reporter=junit --outputFile.junit=\"$BKIT_TEST_REPORT\""`.
199
+ - jest: `jest --runTestsByPath` with the `jest-junit` reporter and `JEST_JUNIT_OUTPUT_FILE="$BKIT_TEST_REPORT"`.
200
+ - **If** jest gets the path without `--runTestsByPath` → it reads the path as a regex, so a folder such as `(tabs)` matches no file and no report is written.
197
201
  - Call the runner directly, not through a caching task runner.
198
202
  - `bkit:lint:file` lints one test file with the static gate's rules, and exits 0 when clean. bkit appends the path. `bkit tests red` runs it on each planned test file before running the file, and records a `lint` gap for the file's tests while it fails. It is not seeded, and `lint-file-script-missing` fires once `bkit:test:file` is declared without it.
199
203
  - ESLint: `"bkit:lint:file": "eslint --max-warnings=0"`.
@@ -203,7 +207,7 @@ pnpm add -D prettier@^3.5.3 slop-scan@^0.3.0 lint-staged@^17.0.0 husky@^9.1.7
203
207
 
204
208
  ## Local test sleep prevention
205
209
 
206
- Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
210
+ Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into `scripts/ci/`. Install its command-launching dependency with `pnpm add -D cross-spawn@7.0.6`; it handles Windows package-command shims and argument escaping, and the wrapper loads it only on Windows. Prefix each local test script, including individual-file runners, with `node scripts/ci/bkit-test-awake.mjs`. Wrap a complete command chain with `--shell` and one double-quoted command string. Leave CI calling the same scripts.
207
211
 
208
212
  ```json
209
213
  {
@@ -215,7 +219,7 @@ Copy `.bkit/templates/scripts/ci/bkit-test-awake.mjs` and its adjacent test into
215
219
 
216
220
  Keep each script's existing runner flags and report settings when adding the prefix. Run the wrapper's tests with `node --test scripts/ci/bkit-test-awake.test.mjs`. For a direct runner invocation, use `node scripts/ci/bkit-test-awake.mjs pnpm exec vitest run path/to/example.test.ts`.
217
221
 
218
- On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. Keep the lid open; `docs/testing.md` § Local test sleep prevention describes the limits.
222
+ On macOS, the wrapper holds `caffeinate -is -w` against its own process and releases it when the command exits. It forwards cancellation to the command and retains the caller's process group so external hard timeouts still reach the tests. POSIX `--shell` chains stop after cancellation and wait for descendant cleanup. Signals reach command owners first; surviving orphan roots receive cancellation after their owner exits. Live owners retain responsibility for their descendants and machine-lock lifetime. A command that starts cleanup children during cancellation must wait for them before exiting. If process inspection is unavailable, the wrapper reports that limitation and waits for foreground completion or a successful cleanup inspection. Linux and Windows do not require `caffeinate`. Test timeouts are unchanged. A Ctrl-C at the terminal already reaches the command, so the wrapper does not send INT again, but a `--shell` chain still waits for descendant cleanup. `--hold-s <N> [--grace-s <G>] [--stopped-file <P>] [--pass-fds <A,B>] --` before the command is the machine lock's hold limit (§ Machine lock): after N seconds the wrapper stops the command and every process under it and exits 124. `--stopped-file` names a file the wrapper creates as that stop starts, so a caller can tell it from the command's own 124. `--pass-fds` hands the command the listed open descriptors above 2, which it otherwise does not receive. Leave it to the lock script; a test script does not pass it. Keep the lid open; `.bkit/workflows.md` § Test and release mechanics describes the limits.
219
223
 
220
224
  `bkit tests` already protects the commands it launches using the packaged wrapper. Adopt this template for direct scripts and hooks. Existing consumer-owned scripts are not rewritten on upgrade.
221
225
 
@@ -269,13 +273,16 @@ A post-CI router that runs bkit workflows:
269
273
  - Failed `dev` CI → `/bkit-debug {FID}`.
270
274
  - `workflow_dispatch` runs any phase.
271
275
 
272
- A `context` job resolves the phase and argument once. Then two runner jobs follow, each skipped without its secret: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action) and `opencode` (`opencode run`, https://opencode.ai/docs/github/). `bkit install --auto=claude|opencode` points at this file. The full recipe is in `.bkit/cloud.md` § Post-CI auto-routing.
276
+ A `context` job resolves the phase and argument once. Then three runner jobs follow, and only the one `bkit.cloud.agent` names starts, when its secret is set: `claude` (`claude-code-action`, https://github.com/anthropics/claude-code-action), `opencode` (`opencode run`, https://opencode.ai/docs/github/) and `codex` (`openai/codex-action`, https://github.com/openai/codex-action). `bkit install --auto=claude|opencode|codex` points at this file. The full recipe is in `.bkit/cloud.md` § Post-CI auto-routing.
273
277
 
274
- - Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template) or `--auto=opencode` (needs `--opencode=<provider>` first). Both need `--tracker=github`.
275
- - Secrets for `claude`: `ANTHROPIC_API_KEY`, or keyless with the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables, plus the Claude GitHub App (`/install-github-app`).
276
- - Secrets for `opencode`: `OPENCODE_PROVIDER_KEY`.
278
+ - Install: `bkit install --auto=claude` (points at the `.claude/hooks/bkit-cloud-bootstrap.sh` template), `--auto=opencode` (needs `--opencode=<provider>` first) or `--auto=codex` (needs `--codex`). Each works with any wired tracker (GitHub, Linear or Jira).
279
+ - Secrets for `claude`: `BKIT_ANTHROPIC_API_KEY`, or keyless with the `ANTHROPIC_FEDERATION_RULE_ID` and `ANTHROPIC_ORGANIZATION_ID` repo variables, plus the Claude GitHub App (`/install-github-app`).
280
+ - Secrets for `opencode`: the installed provider's key, one of `BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`.
281
+ - Secrets for `codex`: `BKIT_OPENAI_API_KEY`.
282
+ - Tracker secrets: `BKIT_LINEAR_API_KEY` under Linear, `BKIT_JIRA_API_KEY` under Jira. The workflow reads them at step scope.
277
283
  - Repo Actions permissions: read and write, with PR creation allowed.
278
- - Adapt: `{{CLOUD_RUNNER}}` in all three jobs.
284
+ - Adapt: `{{CLOUD_RUNNER}}` in all four jobs.
285
+ - The `codex` job runs `drop-sudo` on the runner (irreversible), so use an ephemeral runner.
279
286
  - Traps:
280
287
  - The file runs bkit by command name, so a changed invocation reaches you only as a changed template path on `bkit upgrade`. Diff it on every upgrade.
281
288
  - The OpenCode install version is a plain argument. The `# renovate:` comment above it lets the example `renovate.json5` bump it.
@@ -285,7 +292,7 @@ A `context` job resolves the phase and argument once. Then two runner jobs follo
285
292
 
286
293
  `pre-commit` runs `bkit:gate:format`. `pre-push` runs `bkit check` first, so a drifted install fails in seconds. Then it runs `bkit:gate:static-unit-integration` when package.json declares it, else `bkit:gate:static-unit` (`bkit:gate:static` on revert branches / commits; `bkit:gate:min` on a min push). It also runs the CI-suppressing-token guards, the dependency audit (§ Dependency audit) and the `tmp/` prune (§ tmp/ prune). Each hook ends by starting the disk prune (§ Disk prune).
287
294
 
288
- Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log.
295
+ Pre-push re-runs itself once with all its output copied to `tmp/pre-push.log`, which is rewritten on each push. It prints that path first and last, with the exit code. `--no-verify` and a checkout without husky (a linked worktree) write no log. When the repo has an `.envrc`, `direnv` is on `PATH` and `CI` is unset, the inner run goes through `direnv exec .`, so the gate loads `.envrc` itself. On every path, with or without direnv, the gate unsets the bkit tooling keys (`BKIT_GH_TOKEN`, `BKIT_LINEAR_API_KEY`, `BKIT_JIRA_API_KEY`, `BKIT_ANTHROPIC_API_KEY`, `BKIT_CURSOR_API_KEY`, `BKIT_OPENCODE_API_KEY`, `BKIT_OPENROUTER_API_KEY`, `BKIT_OLLAMA_API_KEY`, `BKIT_OPENAI_API_KEY`) however they were loaded, plus every key `.bkit/.env` names. An `.envrc` that direnv cannot load blocks in seconds, before `bkit check`, and prints direnv's own output; only when direnv reports the file untrusted does it add the `direnv allow .` fix. A repo whose hook copy lacks this gets the `pre-push-direnv` tip.
289
296
 
290
297
  Workflows care because they commit and push without `--no-verify`, so a failing hook stops a workflow. The throwaway `.worktrees/_land-{FID}` checkout runs its selected gate explicitly before pushing, with hooks disabled (§ One landing routine in `.bkit/workflows.md`). Reference: https://typicode.github.io/husky/.
291
298
 
@@ -298,13 +305,15 @@ chmod +x .husky/pre-commit .husky/pre-push
298
305
  - Adapt: repo-only checks go below the bkit lines in each hook. What a gate runs belongs in the `bkit:gate:*` script, not the hook.
299
306
  - Min push:
300
307
  - **If** every file changed since each pushed commit left `origin/dev` (else `origin/main`) is one bkit writes or one `bkit.testing.minPushPaths` adds → `bkit:gate:min` replaces the full gate, and `MIN_PUSH=1`.
301
- - The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed.
302
- - `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
303
- - What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` — 14 steps) plus `docs/plans/**`.
308
+ - The hook passes each remote-old and pushed-new commit as `bkit ci min-push --update=<old>:<new>`. A fast-forward bookkeeping increment also qualifies when a successful local full-gate receipt covers an ancestor of the old commit and every change since that checked commit is allowed. A new branch qualifies the same way: a receipt on an ancestor of the pushed commit, with only bookkeeping paths changed since it and no later failure, takes the minimum gate.
309
+ - `bkit ci push-gate --gate=<script>` runs the selected consumer script. A successful deepest full push gate records its clean, unchanged commit and script definitions in the repository's Git metadata. A failed or interrupted full check prevents reuse of earlier evidence until a later full check succeeds. A check still running blocks reuse too; one whose process has exited without finishing counts as failed, and the next full check on that commit clears it. A tests-lock wait that gives up (the lock script's exit 75, with `gave-up` in its status file) is not a check, so it leaves the evidence as it was. `bkit tests run` records the same receipt when it runs the deepest full gate (build Step 12) without `--changed-since`; there, uncommitted paths inside the min-push (bookkeeping) paths do not block it, since every engine call appends to `status.jsonl`, and any uncommitted code, a lock wait (exit 81) or a lighter gate records none. Minimum and revert gates create no full-gate evidence. Receipts are local; a new clone starts without them.
310
+ - What bkit writes = ship's `--scope=pr` allow-list (`.bkit/workflows.md` § `/bkit-ship` — 12 steps) plus `docs/plans/**` and `docs/audits/**`.
311
+ - A change to a top-level `docs/templates/bkit-audit-*.md` also counts as written by bkit when the file's text through its single `<!-- bkit:end -->` line is the same at both ends of the range, so only the `Project Instructions` section below it changed. A new, deleted or renamed template, a second marker line, or any change at or above the marker keeps the full gate. A template with CRLF line endings never qualifies, because a marker followed by `\r` is not line-anchored. Other templates, such as `docs/templates/bkit-plan.md`, keep the full gate. "What bkit writes" in the `bkit ci min-push` summary covers the audit reports and the audit templates' project sections.
304
312
  - The setting takes `package.json` globs: `*` matches one folder and `**` any depth. The default is `[]`, which leaves what bkit writes alone, because the setting only adds to it.
305
313
  - `bkit ci min-push` decides from files, never from `[skip ci]`, because that is a typed label and GitHub reads the last commit only.
306
- - Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch can still qualify from its complete bookkeeping-only branch diff.
314
+ - Empty trigger commits need checked-ancestor evidence. Missing evidence, unreadable ranges, rewritten history, or any outgoing ref carrying new code keeps the full gate. A new branch qualifies from a receipted ancestor plus bookkeeping-only commits, or from its complete bookkeeping-only branch diff; a new branch with code after the receipted ancestor keeps the full gate.
307
315
  - Min-push paths: list only files that no code, build or test reads.
316
+ - The floor already covers `docs/plans/**` and `docs/audits/**`, so the setting lists neither.
308
317
  - Never list `docs/**`, because a doc can be test input.
309
318
  - **If** a test reads a ledger → put that test into `bkit:gate:min`.
310
319
  - `[skip ci]` guards:
@@ -312,6 +321,13 @@ chmod +x .husky/pre-commit .husky/pre-push
312
321
  - With a PR open, `bkit ci bookkeeping-push --from=<remote head>` lets the push through when every file changed since the head the remote holds is on ship's `--scope=pr` allow-list. Such a push adds nothing that CI has not tested at that head.
313
322
  - A rewritten head or a code file still blocks.
314
323
  - On `dev` / `main`, the skip-CI check uses the complete branch diff, independently of local gate receipts. Code cannot skip CI merely because its local gate passed.
324
+ - PR conflict check:
325
+ - A fast check, run before `bkit check` and the gate. One `gh pr list --head <branch> --state open` lookup (every branch but `dev` / `main`) gives the PR number and its base; the `[skip ci]` guard reads the number from it.
326
+ - **If** the branch has an open PR → the hook fetches the base from `origin`, then runs `git merge-tree --write-tree --name-only` on `origin/<base>` and the pushed commit. Conflicts → the push is blocked, naming the files and the fix. This holds for a min push too, because a conflicting PR never starts CI.
327
+ - **If** `gh` is missing or fails, the clone is shallow (fix: `git fetch --unshallow`), the base fetch fails, or `git merge-tree` fails for another reason → the hook warns that the check was skipped, and the push goes on. No open PR → no fetch and no message.
328
+ - The lookup keeps same-repo PRs plus a cross-repository PR whose head repository is the push target. A fork PR with the same head branch name that is not the push target is ignored. It asks for up to 1000 open PRs; if a full page comes back with no match, the conflict check warns and skips, and the `[skip ci]` guard blocks a `[skip ci]` head, because it cannot tell that no PR is open. The base is fetched with an explicit refspec, and the trial merge ignores the work tree's `.gitattributes`, as GitHub does, so a `merge=union` ledger conflict blocks.
329
+ - `BKIT_PR_CONFLICT_CHECK=false` skips the whole check with one stderr line. `/bkit-ship` sets it on every push, because the conflict is what Step 4 merges away and a `dev` that moves after Step 4 is left to the Step 10 merge gate's `--fresh-base`. `/bkit-debug` sets it on its feature-branch pushes, so fix commits always reach `origin`.
330
+ - A repo whose hook copy lacks this gets the `pre-push-pr-conflict` tip.
315
331
  - Slop base:
316
332
  - **If** the push is to `dev` **and** `scripts/ci/lanes/bkit-resolve-push-base.mjs` is copied → the hook runs it with `--local --branch=dev --head=<pushed sha>`, and exports `SLOP_BASE_REF` as CI's push base. That base is the head of the last green CI push run on `dev`, else `origin/dev`. The hook prints the base and its source.
317
333
  - Pre-push and CI slop then share a base, so a finding that an earlier red push landed fails locally too.
@@ -332,7 +348,7 @@ chmod +x .husky/pre-commit .husky/pre-push
332
348
  pnpm add -D prettier@^3.5.3
333
349
  ```
334
350
 
335
- 1. Copy `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
351
+ 1. Copy `.bkit/templates/prettierignore.example` to `.prettierignore` before the first `prettier --write`. bkit writes `.claude/`, `.cursor/`, `.opencode/`, `.mcp.json`, `.bkit/.env.example` and `docs/roadmap.md` in its own layout, so prettier reformatting them fights the next `bkit install` (`bkit check` drift).
336
352
  2. Add `format:check` (§ Gate tool scripts). Reference: https://prettier.io/docs/install.
337
353
 
338
354
  - Keep the `.bkit/templates/` line.
@@ -340,6 +356,8 @@ pnpm add -D prettier@^3.5.3
340
356
 
341
357
  ## lint-staged — `.lintstagedrc.json`
342
358
 
359
+ Copy `.bkit/templates/lintstagedrc.example.json` to `.lintstagedrc.json`. The samples under `.bkit/templates/` carry non-dotfile names so prettier and lint-staged do not read them as live config; `bkit upgrade` removes the old dotfile-named samples (`.lintstagedrc.json`, `.prettierignore`) from `.bkit/templates/`. bkit writes no lint-staged config into your repo: when `bkit:gate:format` runs `lint-staged` without a `--config` path, lint-staged is a dependency and no config exists, install, check and upgrade print `no root lint-staged config — commits will fail. Fix: cp .bkit/templates/lintstagedrc.example.json .lintstagedrc.json` after their own log prefix (`[bkit-install]`, `[bkit-check]`, `[bkit-upgrade]`).
360
+
343
361
  It runs prettier over staged files. `bkit:gate:format` (the pre-commit hook) calls it. Reference: https://github.com/lint-staged/lint-staged.
344
362
 
345
363
  ```bash
@@ -391,6 +409,8 @@ cp .bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs scripts/slop/
391
409
 
392
410
  It fails `lint` on a test that cannot fail. Oxlint (a fast linter) runs five rules on test files only, with all other checks off. It fits JS / TS repos with Vitest or Jest. Reference: https://oxc.rs/docs/guide/usage/linter.html.
393
411
 
412
+ - The `.bkit/templates/.oxlintrc.json` sample keeps its dotfile name: oxlint run from a consumer root as `oxlint -c .oxlintrc.json` reports a violating test file at the root and reports nothing for the same file under `.bkit/templates/`, so the sample does not act as live config.
413
+
394
414
  ```bash
395
415
  pnpm add -D oxlint@^1.87.0 oxlint-tsgolint@^7.0.2004
396
416
  cp .bkit/templates/.oxlintrc.json .oxlintrc.json
@@ -433,6 +453,7 @@ direnv allow
433
453
  ```
434
454
 
435
455
  - Adapt: add one `dotenv_if_exists <path>` line per extra env file.
456
+ - The pre-push hook loads `.envrc` itself on push (§ Git hooks — Husky), so an agent's shell that never loaded it still pushes with it. Run `direnv allow .` once per folder, or the push blocks.
436
457
  - `unset` the keys that must stay out of the shell. They are dropped from the cloud env blocks too.
437
458
 
438
459
  ## Launchd GUI environment — tokens for Dock-launched apps
@@ -501,7 +522,7 @@ gh api -X PUT 'repos/{owner}/{repo}/vulnerability-alerts'
501
522
  gh api -X PUT 'repos/{owner}/{repo}/automated-security-fixes'
502
523
  ```
503
524
 
504
- Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI. There is no `gh` equivalent.
525
+ Renovate (Mend): commit `.github/renovate.json5` on the default branch, then install the App at https://github.com/apps/renovate in the GitHub UI. `gh` has no equivalent.
505
526
 
506
527
  Renovate (self-hosted): also copy `bkit-renovate.yml`, then set its platform token. Use a fine-grained PAT for one owner, and a classic one across owners. The permissions are in `docs/deployments.md` § Dependency updaters.
507
528
 
@@ -513,13 +534,13 @@ gh secret set BKIT_GH_TOKEN
513
534
  - The examples extend `config:best-practices`:
514
535
  - Major bumps wait for a tick on the Dependency Dashboard (`dependencyDashboardApproval`).
515
536
  - `lockFileMaintenance` runs monthly.
516
- - PRs rebase only on conflict.
537
+ - Renovate never rebases an open PR by itself (`rebaseWhen: "never"`). A PR that conflicts waits until you tick its rebase checkbox.
517
538
  - A `# renovate: datasource=<ds> depName=<name>` comment above a pinned CLI version (Dockerfile, `bkit-cloud.md`, workflows) lets the example `customManagers` entry bump it.
518
539
  - For checksum-paired pins (Vale, gh, jq, Node, actionlint), update the sha256 by hand in the same PR. `Check Pinned Checksums` in `bkit-ci.yml` (`bkit ci pins`) fails the PR until the Dockerfile's hashes match.
519
540
  - `bkit-renovate.yml` pins `renovate-version` to an exact release. The same kind of `# renovate:` comment keeps it current.
520
541
  - `enabled: false` on a Renovate package rule does not stop digest pinning. Use `ignorePaths` to keep Renovate off a file.
521
542
  - Land the config on the default branch before the bot runs. The examples set `baseBranchPatterns: ["dev"]`.
522
- - The App install, the self-hosted token, the private-package host rule and CVE handling are in `docs/deployments.md` § Dependency updaters.
543
+ - The App install and the self-hosted token are in `docs/deployments.md` § Dependency updaters. CVE handling is in `docs/deployments.md` § Manual CVE handling (when an alert fires).
523
544
 
524
545
  ## Dependency audit — known-vulnerable dependencies fail the push
525
546
 
@@ -552,7 +573,9 @@ cp .bkit/templates/scripts/ci/bkit-check-dependency-audit.mjs \
552
573
 
553
574
  It fails CI on a HIGH or CRITICAL finding: a vulnerable package in any lockfile Trivy reads (npm, pnpm, yarn, pip, poetry, uv, Go, Cargo, Maven, …), a risky setting in a Dockerfile / Terraform / Kubernetes / Helm file, or a secret in a tracked file. It runs on push, on pull request and daily. Reference: https://trivy.dev/docs/latest/.
554
575
 
555
- Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, and commit. It needs no secret, token or App. It blocks merges only once the `trivy` check is required in branch protection.
576
+ Copy `bkit-trivy.yml`, replace `{{DEFAULT_BRANCH}}`, and commit. It needs no secret, token or App. It blocks merges only once the `bkit-trivy` check is required in branch protection.
577
+
578
+ For an existing required `trivy` check, save the branch-protection and applicable ruleset settings before landing the workflow rename. Verify `bkit-trivy` on the candidate commit, then coordinate the context replacement with that landing. Preserve strict mode, `app_id` / `integration_id` bindings, bypass policies and unrelated checks. Do not disable protection to unblock the rename. Re-read the settings afterwards. Install, upgrade and doctor report stale requirements without changing remote settings; unavailable or capped reads remain explicitly unchecked.
556
579
 
557
580
  Accept a finding in `.trivyignore.yaml` at the repo root, which is read only when present:
558
581
 
@@ -621,7 +644,7 @@ The PyPI name is `serena-agent`, and the CLI is `serena`. PyPI `serena` is an un
621
644
 
622
645
  ## Issue forms — `.github/ISSUE_TEMPLATE/`
623
646
 
624
- Issues are the first input every workflow reads. There is one form per way work starts, and each form's intro names its next command. The section names, syntax and machine-read lines are in `.bkit/trackers.md` § Issue shapes. The forms are for the GitHub tracker only, because Linear and Jira have their own templates. Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
647
+ Issues are the first input every workflow reads. Each way work starts has one form, and each form's intro names its next command. The section names, syntax and machine-read lines are in `.bkit/trackers.md` § Issue shapes. These forms serve the GitHub tracker alone, because Linear and Jira have their own templates. Reference: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.
625
648
 
626
649
  <!-- prettier-ignore -->
627
650
  | Form | Use when | Next step | Asks for |
@@ -641,6 +664,84 @@ Issues are the first input every workflow reads. There is one form per way work
641
664
  - Never add `bkit:*` labels, because workflows own them.
642
665
  - **If** the repo has existing forms → copy only the `bkit-*` files you want. The names never collide.
643
666
 
667
+ ## Project documents — starters and the index
668
+
669
+ Twelve project docs ship as starters in `.bkit/templates/docs/`: architecture, technology, security, data-schema, testing, deployments, observability, design, noise and setup, plus components (§ Component map — purpose and responsibilities) and capabilities (§ graphify — map). Copy a starter to `docs/{topic}.md` and add a matching row to `.agents/docs.md` `## Project Documents` in the same change; install and upgrade refresh only the starter, never your copy. A doc you keep under another name takes a row whose Scope says `Equivalent to docs/{topic}.md`, and install then adds no second row. A prompt that reads one of these docs applies it only when the doc is present and warns when it is not. Fill the starters in the order of § Project docs — adoption order.
670
+
671
+ ## Project docs — adoption order
672
+
673
+ Fill the project docs in waves, because each doc reads facts the earlier ones record. Each starter's **Fill these first** line lists the docs in the **Fill these first** column below.
674
+
675
+ <!-- prettier-ignore -->
676
+ | Wave | Doc | Fill these first |
677
+ | --- | --- | --- |
678
+ | 1 | `docs/idea.md` | — |
679
+ | 2 | `docs/components.md` | `docs/idea.md` |
680
+ | 3 | `docs/technology.md` | `docs/components.md` |
681
+ | 3 | `docs/design.md` | `docs/components.md` |
682
+ | 4 | `docs/architecture.md` | `docs/technology.md` |
683
+ | 4 | `docs/setup.md` | `docs/technology.md` |
684
+ | 5 | `docs/security.md` | `docs/architecture.md` |
685
+ | 5 | `docs/testing.md` | `docs/architecture.md` |
686
+ | 5 | `docs/observability.md` | `docs/architecture.md` |
687
+ | 6 | `docs/data-schema.md` | `docs/security.md` |
688
+ | 6 | `docs/deployments.md` | `docs/testing.md`, `docs/observability.md` |
689
+ | 6 | `docs/noise.md` | `docs/observability.md` |
690
+ | 7 | `docs/capabilities.md` | `docs/deployments.md` |
691
+
692
+ A solid arrow means the first doc must exist before the second is started. A dotted arrow means the second doc starts without the first, but one section of it is finished or checked against the first, so come back to it once the first exists.
693
+
694
+ ```mermaid
695
+ flowchart LR
696
+ IDEA["idea.md"] --> COMP["components"]
697
+ COMP --> TECH["technology"]
698
+ COMP --> DES["design"]
699
+ TECH -.-> DES
700
+ TECH --> ARCH["architecture"]
701
+ TECH --> SET["setup"]
702
+ ARCH -.-> SET
703
+ SEC -.-> SET
704
+ ARCH --> SEC["security"]
705
+ ARCH --> TEST["testing"]
706
+ ARCH --> OBS["observability"]
707
+ SEC -.-> OBS
708
+ SEC --> DATA["data-schema"]
709
+ DATA -.-> SEC
710
+ TEST --> DEP["deployments"]
711
+ OBS --> DEP
712
+ OBS --> NOISE["noise"]
713
+ DATA -.-> DEP
714
+ DATA -.-> TEST
715
+ DEP --> CAP["capabilities"]
716
+ ```
717
+
718
+ The dotted arrows:
719
+
720
+ - **technology → design:** the colour and spacing variables table waits for technology to pick the styling tool. The rest of design does not.
721
+ - **architecture → setup:** the local services section (database, queues) is filled once architecture names them.
722
+ - **security → setup:** the environment variables table grows as security names secrets.
723
+ - **security → observability:** the log format section is checked against security's list of personal data, so none of it gets logged.
724
+ - **data-schema → testing:** the test data section (fixtures, seed, a fresh store per tier) is finished against the schema.
725
+ - **data-schema → deployments:** the migrations-at-deploy-time section waits for the schema.
726
+ - **data-schema → security:** the "Where stored" column of the PII table in `docs/security.md` is finished against `docs/data-schema.md`.
727
+
728
+ `docs/idea.md` is the owner's free-form notes. It has no template, is not indexed in `.agents/docs.md`, and stays after `docs/components.md` exists. The components starter reads these facts from it:
729
+
730
+ - Who the users are, the problem they have and the result they get.
731
+ - The platforms the app runs on.
732
+ - What the app does without a network connection.
733
+ - What must update live.
734
+ - The scale the app must handle.
735
+ - The hard external requirements, such as a law, a contract or a partner's interface.
736
+
737
+ **If** `docs/idea.md` is absent → the components starter takes the same facts from the README, an approved specification or the owner's answers.
738
+
739
+ ## Component map — purpose and responsibilities
740
+
741
+ Follow the removable population guide in `.bkit/templates/docs/components.md` to create `docs/components.md`. It covers evidence gathering for existing and planned repositories, component selection, example rows, document registration and completion checks.
742
+
743
+ The project owns the populated document. Installation and upgrades refresh the template source without overwriting the adopted copy. Neither graphify nor Floorplan is required; the template's rules header defines the boundaries between the purpose-based overview and other documentation.
744
+
644
745
  ## graphify — map
645
746
 
646
747
  graphify runs on demand only. It is not an installed skill or git hook. graphify ships an MCP server (`graphify-mcp`, stdio default). That server stays unwired, because its answers come from the `graph.json` snapshot, and build / debug agents invalidate the graph faster than it rebuilds. Serena, which has no index to go stale, owns the agent surface.
@@ -694,7 +795,7 @@ graphify-out/
694
795
  - `.graphifyignore` merges `.gitignore`.
695
796
  - Keep `package.json` in the corpus. Excluding it drops the workspace `name` fields that graphify resolves package imports with, and the graph still looks complete.
696
797
  - Keep `tsconfig.json` out, because graphify reads `paths` regardless.
697
- - Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys. There is no persistent LLM-off setting.
798
+ - Always run `scripts/graphify/bkit-graphify.sh`, which passes `--code-only` and `--no-label` and unsets API keys. No persistent LLM-off setting exists.
698
799
 
699
800
  <!-- prettier-ignore -->
700
801
  | Command | Does |
@@ -705,12 +806,15 @@ graphify-out/
705
806
  | `pnpm bkit:graph:rollup` | Package and module views, plus `docs/capabilities.md` and its diagram copies. |
706
807
  | `pnpm bkit:graph:check` | Rebuild and fail if `docs/capabilities.md` is not what this tree produces, or a diagram copy differs from it. Reads uncommitted edits. Shipped as a self-skipping CI step (every push and pull request; on a PR, GitHub's test merge into the base); enabled in bkit's own CI. |
707
808
  | `bash scripts/graphify/bkit-graphify.sh check-at <rev>` | `check` in a throwaway checkout of `<rev>` (default HEAD); pre-push gate runs it on the commit pushed to dev. |
708
- | `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) → copy over `docs/capabilities.md` → rewrite the diagram copies. Stage the change first, so a run before its commit builds the new state. Fixes a red gate; commit result. |
809
+ | `pnpm bkit:graph:refresh` | Rebuild register in a throwaway checkout of the staged files (the index) → replace the generated region of `docs/capabilities.md` → rewrite the diagram copies. Stage the change first, so a run before its commit builds the new state. Fixes a red gate; commit result. |
709
810
  | `pnpm bkit:graph:scoped [path]` | One subtree. Default `apps/web/src`. |
710
811
  | `pnpm bkit:graph:graphml` | Opt-in GraphML for Gephi / yEd. |
711
812
 
712
813
  - `docs/graphify-out/` holds the raw `graph.json`, and `docs/graphify-out/reports/` holds the derived views.
713
- - Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup, because the Overrides block must exist. `pnpm bkit:graph:rollup` rewrites it after that.
814
+ - Copy `.bkit/templates/docs/capabilities.md` → `docs/capabilities.md` before the first rollup.
815
+ - `rollup`, `register` and `refresh` rewrite only the generated region of `docs/capabilities.md`: the text between its `<!-- graphify:start -->` line and its `<!-- graphify:end -->` line. The rest of the file is the project's.
816
+ - **If** the doc lacks exactly one marker pair in that order → the run stops and writes nothing.
817
+ - **If** the doc has no marker and its rules box says the whole file is generated → the run rebuilds it from the starter and keeps its Overrides block.
714
818
  - To add a capability, add a rule in `bkit-graph-drift-rules.json`: lane, owner module, one literal marker. The shipped rules JSON has one example row. Replace it.
715
819
  - The marker is a literal that only the owner should contain (a host, a header, a marker string). Never use the owner's exported function name, because every legitimate caller then reads as `bypassed`.
716
820
 
@@ -907,11 +1011,11 @@ cp .bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs ~/.config/bkit/di
907
1011
 
908
1012
  ## Machine lock
909
1013
 
910
- The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`.
1014
+ The machine lock queues test gates across repositories and protects shared local services across worktrees. Copy the script and wire it into the commands that need the lock. An unwired repository takes no lock. The script requires Bash 3.2+ and `/usr/bin/perl`. A `run` that takes the `tests` lock also needs `node` on `PATH` and the current `bkit-test-awake.mjs` (one that takes `--hold-s`) beside the script, because that file enforces the hold limit; without them that `run` exits 73.
911
1015
 
912
1016
  ```bash
913
1017
  mkdir -p scripts/ci
914
- cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
1018
+ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh .bkit/templates/scripts/ci/bkit-test-awake.mjs scripts/ci/
915
1019
  ```
916
1020
 
917
1021
  <!-- prettier-ignore -->
@@ -928,10 +1032,27 @@ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
928
1032
  - `release_local_stack_lock [name]` frees the lock early.
929
1033
  - `local_stack_lock_holder [name]` prints the holder, or every holder of `tests` slots.
930
1034
  - `local_stack_lock_file [name]` prints the lock file path.
931
- - `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order), and 75 means the wait gave up. Omit `<who>` to use `LOCAL_STACK_LOCK_WHO`, else `npm_lifecycle_event`, else `run`.
1035
+ - `run ["<who>"] [--lock <name>] -- <command> [args…]` passes the command's exit status on. Exit 2 means usage, 73 means the lock could not be taken (including lock order), 75 means the wait gave up, and 124 means the hold limit stopped the command. Omit `<who>` to use `LOCAL_STACK_LOCK_WHO`, else `npm_lifecycle_event`, else `run`.
1036
+ - Hold limit: a `run` that took the `tests` lock holds it at most `LOCAL_STACK_LOCK_HOLD_S` seconds (whole number >= 1, default 3600; any other value falls back to 3600 with one note). The limit counts every second the command runs, including time it spends waiting inside the lock.
1037
+ - At the limit, `run` sends TERM to the command and every process started under it, then KILL to those still running after `LOCAL_STACK_LOCK_HOLD_GRACE_S` seconds (whole number >= 0, default 10). It then frees the lock, prints a `[machine-lock]` line naming the holder, the limit and the time held, and exits 124. A command that ends before the stop keeps its own exit status.
1038
+ - Only `run` enforces the limit, and only the `run` that took the `tests` lock. These have no limit:
1039
+ - every other named lock and the unnamed stack lock, since a run may hold those for hours;
1040
+ - a nested `run` that reuses its live parent's lock;
1041
+ - `CI=true` / `CI=1`, which takes no lock;
1042
+ - a runner that sources the script and calls `take_local_stack_lock`.
1043
+ - The holder enforces the limit because the OS never hands the lock to a waiter while the holder is alive. A run waiting for the lock takes it within a second of the stop.
1044
+ - Under the limit, the command must be a program on `PATH`, because `run` starts it with `exec`. A shell function or builtin fails with exit 127 or 126; wrap shell code in `sh -c '…'`.
1045
+ - `run` starts the command under `node bkit-test-awake.mjs --hold-s <limit> --grace-s <grace> --stopped-file <file>` from the script's folder, and that supervisor does the stop, creates the file and exits 124. `run` reads exit 124 as a hold-limit stop only when that file exists; otherwise 124 is the command's own. A supervisor that cannot create the file still stops the command, and `run` reports that 124 as the command's own. Without `node` on `PATH`, or with that file missing or without `--hold-s`, `run` frees the lock, names the file, writes `outcome=refused` and exits 73.
1046
+ - If the supervisor itself is killed, `run` frees the lock and exits with its status while the command may still be running.
1047
+ - The supervisor lists the processes under the command once a second with the first `ps` on `PATH` and its `lstart` column (procps on Linux), so it also stops a process whose parent has exited. Without a `ps` that prints `lstart`, such as a slim image with no procps or a BusyBox `ps`, it prints one note and the limit stops only the command itself, not the processes under it.
1048
+ - A process whose parent exits within a second of starting it may survive the stop. It does not hold the lock, so the lock is still freed, but it may keep the caller's output pipe open, and a caller that reads that pipe to its end then waits for that process.
1049
+ - The command keeps the caller's process group and stdin, so it still reads the terminal and gets Ctrl-C. TERM, INT and HUP sent to `run` are passed on to the command (INT only when `run` does not have the terminal, since Ctrl-C reaches the command directly); `run` keeps the lock until the command ends, then exits with the signal's status. A signal that arrives once the hold-limit stop has started is not passed on, and the exit stays 124.
1050
+ - Give one long gate a longer limit by prefixing that gate's `package.json` script, for example `"bkit:gate:e2e": "LOCAL_STACK_LOCK_HOLD_S=10800 bash scripts/ci/bkit-machine-lock.sh run --lock tests -- <gate command>"`. Every other gate keeps the 3600-second default.
1051
+ - Status file: when `LOCAL_STACK_LOCK_STATUS_FILE` names a path and `run` exits 75, 73 or 124, `run` writes that file (a temp file beside it, then a rename) as three lines: `lock=<name>`, `outcome=gave-up`, `outcome=refused` or `outcome=held-too-long`, and `holder=<each holder's note, joined by "; ">` (for `held-too-long`, the stopped run's own note). The caller reads the outcome from the exit code and this file, never from the printed lines. `run` unsets the variable for its command, so a nested wrapper never writes the caller's file. `bkit tests run`, `bkit tests changed` and `bkit branches push` create the file and read it.
1052
+ - `slots` prints `slots=N workers=N` for the current environment and exits 0; it is the one place the slot rule lives. `queue [--lock <name>]` prints one `<who> — <checkout>` line per waiting run and held place, in queue order, and exits 0 with no output when nobody waits. `jump [--lock <name>] <who> [<checkout>]` moves that run to the front: exit 0 printing its line, 1 when none matches, 3 when several match (printing them), 73 when the marker cannot be written. `queue` and `jump` default to the `tests` lock.
932
1053
  - Named locks use `~/.cache/bkit/machine-lock/<name>.lock`, with no repository prefix. The holder line identifies the caller's checkout. A child inherits `LOCAL_STACK_LOCK_OWNER_<key>` and reuses only that named lock while its owner is alive.
933
- - The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1, default 1; an invalid value falls back to 1 with one note). Slot 1 uses `tests.lock`; later slots use `tests.<k>.lock`. The waiting note names every holder.
934
- - Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1). Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
1054
+ - The `tests` lock has `BKIT_TEST_SLOTS` slots (whole number >= 1). The default is 2 slots on a machine with 8 or more cores when the run is local, else 1; every other runtime defaults to 1 slot. A run is not local when `BKIT_RUNTIME` is set to anything but `LOCAL`; with `BKIT_RUNTIME` unset, it is not local when `.bkit/.runtime-cursor` exists in the main checkout or `CLAUDE_CODE_REMOTE` is set to anything but empty, `false`, `0` or `no` in any case. An invalid value falls back to that default with one note. Set `BKIT_TEST_SLOTS` per machine, never per repo. The value is per process: set it in every place runs start from (the shell profile and each host's user-level settings) or nowhere, because runs that read different values can hold `tests` slots at once. Slot 1 uses `tests.lock`; later slots use `tests.<k>.lock`. The waiting note names every holder.
1055
+ - Taking `tests` exports `BKIT_TEST_WORKERS` = max(1, floor(cores / slots) - 1), and `slots` prints the same number before any lock is taken. Pass it to your runner, for example `vitest run --maxWorkers="$BKIT_TEST_WORKERS"` inside the wrapped command. Cores come from `getconf _NPROCESSORS_ONLN`, else `nproc`, else `sysctl -n hw.ncpu`, else 1.
935
1056
  - Take locks in this order: `tests`, other named locks, then the unnamed stack lock. A request for `tests` while this shell or a live parent holds another lock is refused. A request for a named lock while holding the stack lock is also refused.
936
1057
  - The unnamed stack lock keeps `~/.cache/bkit/local-stack-lock/<stack>.lock` and `LOCAL_STACK_LOCK_OWNER` / `LOCAL_STACK_LOCK_PID`. A consumer's adopted copy keeps working and excludes this copy on the same stack.
937
1058
  - `<stack>` is `BKIT_LOCAL_STACK`, else the main checkout's folder name, so every worktree finds the same lock.
@@ -940,6 +1061,15 @@ cp .bkit/templates/scripts/ci/bkit-machine-lock.sh scripts/ci/
940
1061
  - Lock paths use `$XDG_CACHE_HOME/bkit/` when set. A small Perl process holds the file lock and exits within a second of its caller, however the caller ends.
941
1062
  - Wait: `LOCAL_STACK_LOCK_WAIT_S` when set, else 60 seconds without a TTY, else 3600 seconds. Waiting notes name the budget and holders once a minute; the give-up line names the holder again.
942
1063
  - A named release records held seconds by checkout in `<name>.last`, with one tab-separated line per checkout. A waiting note and give-up line name the current holder's `last run took <N>m<N>s`, or `no earlier run`.
1064
+ - Waiters are served in the order they started waiting. Each wait-mode take keeps a flock-held ticket in `<name>.queue/` beside its lock file (the unnamed stack lock uses `<stack>.queue/`), named `<monotonic seconds>-<pid>`, and a waiter tries the lock only when no earlier live ticket blocks it. Every lock shares this queue, including each `tests` slot.
1065
+ - A ticket holds the waiter's line on its first line and `slots=N`, the slots it asks for, on its second. A waiter may take slot `k` only while no live ticket ahead of it asks for `k` or more slots, so waiters asking for the same count keep arrival order, a 1-slot waiter ahead never blocks slot 2, and a ticket with no `slots=` line asks for every slot.
1066
+ - A ticket whose waiter died, or whose helper was killed, is skipped and removed; a waiter that gives up or is signalled drops its ticket.
1067
+ - A waiter that gives up leaves its ticket as `<ticket>.held` for 120 seconds; the same run (same name and checkout) asking again within that time takes its place back. Older held places are deleted. Names that are neither tickets nor held places are left alone.
1068
+ - The waiting note names the place in line (`2nd in line`). `try_local_stack_lock` never joins the line and reports busy (`N waiting in line`) while any live ticket exists, even when the lock is free.
1069
+ - A waiter stopped (for example with `SIGSTOP`) while first in line holds the line: `ls` the queue folder to see who is first.
1070
+ - A queue folder that cannot be created, or a ticket that cannot be written, refuses the take with the queue path (`run` exits 73).
1071
+ - `bkit tests jump <run>` asks the template's copy of the script (`jump --lock tests`) to move one waiting run to the front of the `tests` line by writing a `<ms>.jump` marker in `tests.queue/`; it exits 3 when the script cannot read the queue or write the marker. The holder keeps the lock, the newest jump goes first, and the marker goes when that run takes the lock or no waiting run matches it. `--checkout <path>` picks one when several runs share the name. Every use needs the human's approval (a host `ask`; denied on Codex, which cannot ask), so an agent cannot approve its own jump.
1072
+ - `bkit upgrade` replaces an unedited copy of `scripts/ci/bkit-machine-lock.sh` from a shipped release with the current template. It leaves an edited copy alone and warns to merge the template by hand when the copy has no queue, never names `LOCAL_STACK_LOCK_STATUS_FILE` or has no `LOCAL_STACK_LOCK_HOLD_S` hold limit; until merged, a wait that gives up reads as a gate failure (exit 1) instead of exit 81, and a hung run holds the lock until someone stops it. Beside such a lock copy it writes a missing `scripts/ci/bkit-test-awake.mjs` from the template and replaces an unedited shipped copy; it leaves an edited copy without `--hold-s` alone and warns to merge the template by hand, and until then every `run` that holds the tests lock is refused with exit 73.
943
1073
  - `CI=true` / `CI=1` makes every lock a no-op.
944
- - `bkit tests run` and `bkit tests changed` pass `--lock-wait-s` and their run name to a wrapped gate; a tests-lock give-up of this run maps 75 → 81 with `lockHolder`, and a tests-lock refusal maps 73 → 4. A lock wait writes no `test-run` status row. Light runs (`red`, `green`, `bkit:test:file`) take no tests lock. Nested wraps reuse their live parent's tests lock. See `docs/testing.md` § Tests lock for host wait budgets.
1074
+ - `bkit tests run` and `bkit tests changed` pass `--lock-wait-s`, their run name and a fresh `LOCAL_STACK_LOCK_STATUS_FILE` to a wrapped gate; exit 75 with `lock=tests` and `outcome=gave-up` in that file maps to 81 with `lockHolder` from `holder=`, and exit 73 with `outcome=refused` or exit 124 with `outcome=held-too-long` maps to 4 (could not run: a `test-run` row with a null verdict, never `FAIL`). Without that file, a 75, 73 or 124 is a gate failure (exit 1). A lock wait writes no `test-run` status row. Light runs (`red`, `green`, `bkit:test:file`) take no tests lock. Nested wraps reuse their live parent's tests lock. See `.bkit/workflows.md` § Test and release mechanics for host wait budgets.
945
1075
  - Fix hints and docs name the locked scripts, never the raw command (`supabase db reset`, `docker compose down`), because the raw command skips the lock. See `.agents/rules.md` § Shared local stack.
@@ -16,7 +16,28 @@
16
16
  > - Add its value to the enum in `.bkit/core/engine/install/manifest.ts`.
17
17
  > - Document its MCP server under `mcpServers.<name>` in `.bkit/shared/.mcp.json` and `.bkit/shared/.cursor/mcp.json`.
18
18
  > - Add a `<!-- bkit:tracker <name> -->` block after the last tracker block at every call site, and extend `GROUP_RE` in `.bkit/core/engine/render/trackers.ts`.
19
- > - There is no `none` marker. No-tracker content goes in a `false` block.
19
+ > - No `none` marker exists. No-tracker content goes in a `false` block.
20
+
21
+ ## Workflow comment delivery
22
+
23
+ The engine may append routine reports to its own eligible progress comment. Ownership comes from an explicit repo-info session or an exact workflow run, never another active run. A later human or unrelated comment, missing ownership evidence, or a capacity rollover starts a new comment. Attention reports and terminal summaries always use new comments.
24
+
25
+ The optional progress cache and run association live under the repository's Git-common `bkit-outbox` directory, shared by linked worktrees. Losing this state starts fresh. Remote text can confirm an owned comment, but never becomes the source of a replacement body. Reconciliation reads a bounded newest-created window, including paginated provider responses.
26
+
27
+ Preparation, delivery, reconciliation, receipt and friction failures are nonfatal. When `tracker.done` is false and `commentFile` exists, attempt one new MCP comment from that file byte-for-byte. MCP fallback never edits prior tracker content. Record best-effort redacted friction and continue substantive work even when the file or fallback is unavailable.
28
+
29
+ ### Verified provider contracts
30
+
31
+ Live contract evidence version 1 verified the following boundaries through the production transports. Every selected body budget counts the complete Markdown source in UTF-16 code units, including markers and part labels. These budgets are conservative delivery ceilings, rather than promises of each provider's maximum.
32
+
33
+ <!-- prettier-ignore -->
34
+ | Provider | Selected body budget | Observed counting boundary | Inspection and edit contract |
35
+ | --- | --- | --- | --- |
36
+ | GitHub | 65,536 | 262,144 UTF-8 body bytes accepted; the next byte rejected for ASCII and non-BMP text. | REST create/edit and GraphQL read agree on numeric comment/author IDs, timestamps and Markdown fingerprints. `last`/`before` pagination retains newest-created order after an older edit. |
37
+ | Linear | 100,000 | 100,000 Unicode scalars accepted; the next scalar rejected for ASCII and non-BMP text. UTF-16 counting stays conservative. | GraphQL create/edit/read return stable comment/user IDs, timestamps and Markdown fingerprints. Cursor pages are sorted by creation time before selecting the newest comments. |
38
+ | Jira Rovo | 32,767 | The selected ASCII/non-BMP payloads pass. Markdown-to-ADF conversion changes the raw-source boundary; larger payloads can fail with `CONTENT_LIMIT_EXCEEDED`. No universal raw-source maximum is claimed. | Deployed tool schemas accept ID-based edits and `responseContentFormat: markdown`, `view: evidence`, creation ordering and offset pagination. Require returned Markdown format, stable author/comment IDs and matching fingerprints before editing. |
39
+
40
+ All three preserve the generated h6 marker on the tested bodies. Repeated reads remain stable, an external edit starts fresh progress, and a terminal report creates a separate comment. Discarded acknowledgments can be recognized by bounded reads; inconclusive recognition tries a new comment and can duplicate an accepted report. Exhausted writes produce real best-effort friction and allow later reporting to continue. These probes do not establish universal notification silence: GitHub and Linear subscriber settings and Jira project notification schemes still apply.
20
41
 
21
42
  ## Marker contract
22
43
 
@@ -95,9 +116,9 @@ This renders `N. <body>` when a tracker is wired, and `N. _No tracker connected,
95
116
  | `issue-update-failed` | Failure Path additive `bkit:failed` | `issue_write` labels | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.tracker.linear.review` | `editJiraIssue` full label set, then transition to `bkit.tracker.jira.review` | skip |
96
117
  | `issue-update-merged` | Ship terminal — `bkit:merged` + In Review (issue left open; human closes) | `issue_write` `bkit:merged` (no close) | `save_issue_label` per new label, then `save_issue` labels, then `save_issue` state `bkit.tracker.linear.review` | `editJiraIssue` full label set, then transition to `bkit.tracker.jira.review` | skip |
97
118
  | `issue-update-status` | Projects v2 board status (best-effort) | `projects_write` add / update item | no-op (state carries) | no-op (status carries) | skip |
98
- | `comment-post-step` | new comment per workflow step | `add_issue_comment` | `save_comment` | `addOrEditJiraIssueComment` | skip |
119
+ | `comment-post-step` | engine-owned routine progress; create-only fallback | `add_issue_comment` | `save_comment` without `id` | `addOrEditJiraIssueComment` without `commentId` | skip |
99
120
  | `issue-blockers-check` | Gate on open blockers | parse body marker → read states | `get_issue` relations | JQL `linkedIssues(KEY, "is blocked by") AND statusCategory != Done` | skip |
100
- | `kill-switch-check` | Terminate if `bkit:auto` absent; skipped when `ISSUE_ID` empty | label check | label check | label check | inactive |
121
+ | `kill-switch-check` | Re-read the labels after the push (build Step 16, debug Step 11); the run is already finished, so an absent `bkit:auto` stops nothing and only adds a line to the final message; skipped when `ISSUE_ID` empty | label check | label check | label check | inactive |
101
122
  | `pr-body-metadata` | Parse PR-body issue / FID marker; FID-only marker (no issue) → `issueId: null`, `/bkit-auto` fails closed | `pull_request_read` + parse | same (GitHub PR) | same (GitHub PR) | FID-only, no fail-closed |
102
123
  | `pr-body-marker` | Literal PR-body marker line; no issue → `<!-- bkit:fid={FID} -->` alone | `<!-- bkit:issue=#{ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:issue={ISSUE_ID} bkit:fid={FID} -->` | `<!-- bkit:fid={FID} -->` |
103
124
 
@@ -118,7 +139,7 @@ Workflows read an issue's body and comments (`bkit issues text`), never its titl
118
139
 
119
140
  - Success Criteria: <=5 bullets, each an observable outcome.
120
141
  - Edge Cases: `| Scenario | Expected Behavior |`.
121
- - Derived Test Matrix: `| Test description | Type | Target file |`. Type = the lowest tier that exercises the test, named as in `docs/testing.md`. Exactly one task covers each row.
142
+ - Derived Test Matrix: `| Test description | Type | Target file |` in the issue; the plan form is the four columns `Test description | Type | Target file | Task`, with `Task` last. Type = the lowest tier that exercises the test, named as in `docs/testing.md`. Exactly one task covers each row.
122
143
  - Tasks, in build order, as task group and task blocks (`docs/templates/bkit-plan.md` § Agent Execution Runbook), sized by `package.json` `bkit.workflows.tasks`:
123
144
  - Each group holds <= `bkit.workflows.tasks.maxPerGroup` tasks (default 5) and <= `bkit.workflows.tasks.maxTestsPerGroup` `TEST FIRST` tests (default 25).
124
145
  - Each task has 1 to `bkit.workflows.tasks.maxTestsPerTask` tests (default 10) across <= `bkit.workflows.tasks.maxTestFilesPerTask` test files (default 3), or `n/a — {reason}` for docs, config, a pure refactor, or E2E / @live only.
@@ -179,7 +200,7 @@ Workflows read an issue's body and comments (`bkit issues text`), never its titl
179
200
  | design `Suggested Plans` (`P-N`; 2+ → design summary next step; 1 → planned on the design's own issue) | one issue per plan, never per workstream; title = plan name; body = its deliverable and covered workstream scopes, spec left to design; filed in `Requires` order | `**Parent design:**` line; `**Workstreams:**` line = its `Covers` ids; blocked-by block = plan issues filed for its `Requires` (linear → `blockedBy` relation; jira → `Blocks` link, `inwardIssue` = blocker) |
180
201
  | roadmap item with no issue (ledger row, audit candidate) | by recommended command, as audit row | ledger `key` / report path in References |
181
202
 
182
- **Audit parent** — one standing issue per audit template, shared by every run of that template. There is never one per run, and never one across templates.
203
+ **Audit parent** — one standing issue per audit template, shared by every run of that template. No audit parent is opened per run, and none spans templates.
183
204
 
184
205
  <!-- prettier-ignore -->
185
206
  | Field | Value |
@@ -236,17 +257,29 @@ bkit supports Jira Cloud only. `ISSUE_ID` is the issue key (`PROJ-123`), which g
236
257
  2. Each person opens https://id.atlassian.com/manage-profile/security/api-tokens → **Create API token with scopes** (not classic) → app **Atlassian MCP V2** (not **Jira**, not **Atlassian MCP**) → the Jira read / write / search scopes (`read:jira:agent-interface`, `write:jira:agent-interface`, `search:jira:agent-interface`). Copy the token, which is shown once, into `BKIT_JIRA_API_KEY` in `.bkit/.env`, then run `direnv allow`. The token works on MCP only, and the Jira REST API answers 401.
237
258
  3. Run `bkit install --tracker=jira`, then set `bkit.tracker.jira.site` and `bkit.tracker.jira.project`. In Claude, approve the project `.mcp.json` once in an interactive `claude` session. Until then, `claude mcp list` shows "Pending approval".
238
259
 
260
+ ### Authentication troubleshooting
261
+
262
+ The scoped **Atlassian MCP V2** token is a personal API token used as `Bearer` by bkit's Rovo transport. It needs no account email. The API-token management page alone does not identify the token's app or scopes. Jira REST guidance about `Basic` authentication with an email does not establish the authentication contract for this MCP endpoint.
263
+
264
+ For an authentication failure:
265
+
266
+ 1. Read this section and the project's active `docs/knowledge.jsonl` entries before asking for credentials. Check related tracker decisions and comments when the owner says the setup worked previously.
267
+ 2. Check that the running process loads `BKIT_JIRA_API_KEY` from the intended `.bkit/.env`, including in a linked worktree. After a credential update, compare the loaded and saved values without printing either value, and check for surrounding whitespace. Report presence and equality only.
268
+ 3. Verify the setup above: the token's app and scopes, the org's API-token permission, the `/v2/mcp` endpoint, the `Bearer` header and a non-default `User-Agent`. A scripted probe must use the engine's `initialize` handshake before tool calls.
269
+ 4. **If** initialization still returns HTTP 401 with `invalid_token` → record that the endpoint rejected the configured credential and which checks passed. Ask the owner to verify or replace the scoped token locally. Do not infer a missing email, switch to `Basic`, or add an email setting from this response. Tool schemas and write behaviour remain unverified until authentication succeeds.
270
+
239
271
  **Behaviour workflows rely on:**
240
272
 
241
273
  - Status changes only by transition. Workflows list the issue's transitions (`executeRead` `listJiraIssueTransitions`) and fire the one whose `to.name` = the target status. When none matches, the status change is `Unapplied`, and the labels still land. Basic team-managed boards may lack `In Review`, so set `bkit.tracker.jira.review` to a status the board has.
242
274
  - Labels: `getJiraIssue` returns them only with `view: "evidence"` (or `"full"`). `editJiraIssue` replaces the whole set. Jira creates a label on first use. Stored labels are case-sensitive, and JQL search is not.
243
275
  - Comments are posted as markdown, stored as Atlassian Document Format, and read back as markdown with the same meaning but not the same bytes (`-` bullets → `*`, `*em*` → `_em_`, extra blank lines; checkboxes and `> [!NOTE]` alerts come back escaped). One comment that Jira cannot express in markdown (a mention, an image, a panel) turns its whole page to HTML (`appliedContentFormat: "html"`), so reads by the engine and by the MCP fallback re-read that page one comment per call. A comment holds at most 32,767 characters, so the engine splits a longer one at line breaks into consecutive comments, each opening with `###### bkit:generated` and then `_(part i/n)_`.
244
276
  - Blockers use the native `Blocks` link. `createJiraIssueLink` reads backwards: `inwardIssue` = the blocker, and `outwardIssue` = the blocked issue.
245
- - There are no type labels: the issue type (Bug / Task / Story) carries the type.
277
+ - No type labels exist: the issue type (Bug / Task / Story) carries the type.
246
278
 
247
279
  <!-- prettier-ignore -->
248
280
  | Symptom | Fix |
249
281
  | --- | --- |
282
+ | HTTP 401 with `invalid_token` during initialization | Follow § Authentication troubleshooting; the response alone does not identify why the credential was rejected. |
250
283
  | Only 4 tools listed (`getTeamworkGraphContext` …), no Jira tools | URL `/v2/mcp`, not `/v1/mcp` |
251
284
  | Every call: `Cloud id: … isn't explicitly granted by the user` | Scoped **Atlassian MCP V2** token sent as `Bearer`, not classic token or `Basic` |
252
285
  | `missing the scope claim` | Classic token → create token with scopes |