@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
@@ -66,7 +66,7 @@ jobs:
66
66
  # app-id: ${{ secrets.RENOVATE_APP_ID }}
67
67
  # private-key: ${{ secrets.RENOVATE_APP_PRIVATE_KEY }}
68
68
  # then set `token: ${{ steps.app-token.outputs.token }}` below.
69
- - uses: renovatebot/github-action@a63d9a7bc606f7336fd20b47f2f32259a35e6213 # v46.3.9
69
+ - uses: renovatebot/github-action@1c0cf989c02653fba0efe7ca5772338860ca71dc # v46.3.12
70
70
  with:
71
71
  # PAT secret (default). FINE-GRAINED repository permissions (this repo):
72
72
  # Contents: Read and write · Pull requests: Read and write ·
@@ -85,7 +85,7 @@ jobs:
85
85
  # uses GitHub releases (they carry publish dates, so `minimumReleaseAge` applies);
86
86
  # the image tags on ghcr.io carry none.
87
87
  # renovate: datasource=github-releases depName=renovatebot/renovate
88
- renovate-version: "44.176.2"
88
+ renovate-version: "44.221.6"
89
89
  env:
90
90
  # Scope to THIS repo only — never org-wide autodiscover.
91
91
  RENOVATE_REPOSITORIES: ${{ github.repository }}
@@ -24,7 +24,10 @@ set -e
24
24
  # background, still has the whole run. The path is printed first (tail -f it while the push
25
25
  # runs) and last, with the exit code. Git's ref list on stdin reaches the inner run unchanged,
26
26
  # and the hook exits with the inner run's code. Output goes to stderr, where git sends a
27
- # hook's output anyway. `git push --no-verify`, and a checkout without husky installed (a
27
+ # hook's output anyway. When the repo has an `.envrc`, `direnv` is on PATH and CI is unset, the
28
+ # inner run goes through `direnv exec .`, so the gate sees the repo's variables whatever shell
29
+ # pushed; an `.envrc` that fails to load blocks first with direnv's own output, plus the
30
+ # `direnv allow .` fix when direnv reports it untrusted. The keys in `.bkit/.env` are unset for the gate. `git push --no-verify`, and a checkout without husky installed (a
28
31
  # linked worktree), run no hook and write no log.
29
32
  if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
30
33
  PRE_PUSH_LOG=tmp/pre-push.log
@@ -33,7 +36,24 @@ if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
33
36
  {
34
37
  echo "[pre-push] log: $PRE_PUSH_LOG"
35
38
  pre_push_rc=0
36
- BKIT_PRE_PUSH_LOGGED=1 FORCE_COLOR=1 sh "$0" "$@" 2>&1 || pre_push_rc=$?
39
+ if [ -f .envrc ] && [ -z "${CI:-}" ] && command -v direnv > /dev/null 2>&1; then
40
+ if direnv_probe=$(direnv exec . true < /dev/null 2>&1); then
41
+ BKIT_PRE_PUSH_LOGGED=1 FORCE_COLOR=1 direnv exec . sh "$0" "$@" 2>&1 || pre_push_rc=$?
42
+ else
43
+ printf '%s\n' "$direnv_probe"
44
+ case "$direnv_probe" in
45
+ *" is blocked"* | *" not allowed"*)
46
+ echo "[pre-push] .envrc is not trusted: run \`direnv allow .\` in this folder, then push again."
47
+ ;;
48
+ *)
49
+ echo "[pre-push] .envrc failed to load (direnv output above): fix it, then push again."
50
+ ;;
51
+ esac
52
+ pre_push_rc=1
53
+ fi
54
+ else
55
+ BKIT_PRE_PUSH_LOGGED=1 FORCE_COLOR=1 sh "$0" "$@" 2>&1 || pre_push_rc=$?
56
+ fi
37
57
  echo "[pre-push] log: $PRE_PUSH_LOG (exit $pre_push_rc)"
38
58
  echo "$pre_push_rc" > "$PRE_PUSH_RC_FILE"
39
59
  } | tee "$PRE_PUSH_LOG" >&2
@@ -42,6 +62,22 @@ if [ -z "${BKIT_PRE_PUSH_LOGGED:-}" ]; then
42
62
  exit "$pre_push_rc"
43
63
  fi
44
64
 
65
+ # The bkit tooling keys are unset for the gate: its tests, lint plugins and dependency code never
66
+ # need them, and their output lands in the agent-readable log. Two sources: the fixed list
67
+ # (.bkit/templates.md § Git hooks — Husky), whichever path loaded them (cloud dashboard env, an app
68
+ # env file, ~/.zshrc, launchd), and every key `.bkit/.env` names, in direnv's dotenv grammar
69
+ # (`KEY=v`, `KEY = v`, `KEY: v`, optional `export `).
70
+ for gate_key in BKIT_GH_TOKEN BKIT_LINEAR_API_KEY BKIT_JIRA_API_KEY BKIT_ANTHROPIC_API_KEY \
71
+ BKIT_CURSOR_API_KEY BKIT_OPENCODE_API_KEY BKIT_OPENROUTER_API_KEY BKIT_OLLAMA_API_KEY \
72
+ BKIT_OPENAI_API_KEY; do
73
+ unset "$gate_key"
74
+ done
75
+ if [ -f .bkit/.env ]; then
76
+ for gate_key in $(sed -n 's/^[[:space:]]*\(export[[:space:]][[:space:]]*\)\{0,1\}\([A-Za-z_][A-Za-z0-9_]*\)[[:space:]]*[=:].*/\2/p' .bkit/.env); do
77
+ unset "$gate_key"
78
+ done
79
+ fi
80
+
45
81
  # Git exports GIT_DIR to a hook and everything it starts (from a linked worktree:
46
82
  # <main>/.git/worktrees/<name>). It beats a child's cwd and -C, so a test's `git -C "$tmp" init`
47
83
  # re-initialises this repo (core.bare=true in the shared .git/config) and a fixture's
@@ -106,6 +142,45 @@ case "$HEAD_SUBJECT" in
106
142
  'Revert "'*) IS_REVERT=1 ;;
107
143
  esac
108
144
 
145
+ # Open-PR lookup: one `gh pr list` for every branch except dev / main, shared by the
146
+ # CI-suppressor guard (the number) and the PR conflict check (the number and its base).
147
+ # gh absent or failing leaves PR_LOOKUP naming why; the check that needs an answer warns.
148
+ OPEN_PR=""
149
+ PR_BASE=""
150
+ PR_LOOKUP=""
151
+ PR_LOOKUP_FULL=0
152
+ case "$BRANCH" in
153
+ dev|main|"") ;;
154
+ *)
155
+ if command -v gh >/dev/null 2>&1; then
156
+ # strip hook-injected GIT_DIR/GIT_WORK_TREE so gh resolves the repo from cwd (worktree-safe)
157
+ # push target owner/name from the URL in $2: a PR from that repo counts even when gh reports it cross-repository (a fork checkout)
158
+ PR_TARGET=${2%.git}
159
+ PR_TARGET_NAME=${PR_TARGET##*/}
160
+ PR_TARGET_OWNER=${PR_TARGET%/*}
161
+ PR_TARGET_OWNER=${PR_TARGET_OWNER##*[/:]}
162
+ case "$PR_TARGET_OWNER$PR_TARGET_NAME" in *[!A-Za-z0-9._-]*|"") PR_TARGET_OWNER=""; PR_TARGET_NAME="" ;; esac
163
+ # --limit 1000: fork PRs sharing the head name must not push the same-repo PR off the page; a full page with no match is an unknown, not "no PR"
164
+ PR_JQ='map(select((.isCrossRepository | not) or (.headRepositoryOwner.login == "'"$PR_TARGET_OWNER"'" and .headRepository.name == "'"$PR_TARGET_NAME"'"))) as $m | if ($m | length) > 0 then "\($m[0].number) \($m[0].baseRefName)" elif length >= 1000 then "FULL" else empty end'
165
+ if PR_INFO=$(env -u GIT_DIR -u GIT_WORK_TREE gh pr list --head "$BRANCH" --state open --limit 1000 --json number,baseRefName,isCrossRepository,headRepositoryOwner,headRepository --jq "$PR_JQ" < /dev/null 2>/dev/null); then
166
+ if [ "$PR_INFO" = "FULL" ]; then
167
+ PR_LOOKUP="1000 open PRs share this head branch name and none is from this repo"
168
+ PR_LOOKUP_FULL=1
169
+ PR_INFO=""
170
+ else
171
+ PR_LOOKUP=ok
172
+ fi
173
+ OPEN_PR=${PR_INFO%% *}
174
+ case "$PR_INFO" in *" "*) PR_BASE=${PR_INFO#* } ;; esac
175
+ else
176
+ PR_LOOKUP="gh pr list failed (offline, or gh not signed in)"
177
+ fi
178
+ else
179
+ PR_LOOKUP="gh is not installed"
180
+ fi
181
+ ;;
182
+ esac
183
+
109
184
  # CI-suppressor HEAD guard: blocks a push whose HEAD commit carries a [skip ci]-class
110
185
  # token while the branch has an OPEN PR (that token silences GitHub's pull_request
111
186
  # trigger). Covers manual pushes (rebase + force-push, post-close commits). No open PR
@@ -113,7 +188,7 @@ esac
113
188
  # gh absent -> allow. `bkit ci skip-token` exits 0 when HEAD's message carries one of
114
189
  # the tokens GitHub honours; bkit owns that list.
115
190
  # Exception, the same one ship's merge gate makes: a push that adds only files on ship's
116
- # `--scope=pr` allow-list (.bkit/workflows.md § `/bkit-ship` — 14 steps) on top of the
191
+ # `--scope=pr` allow-list (.bkit/workflows.md § `/bkit-ship` — 12 steps) on top of the
117
192
  # head the remote already holds leaves nothing new for CI to test, so the PR's checks at
118
193
  # that head still cover the code. `bkit ci bookkeeping-push` exits 0 for exactly that
119
194
  # shape. A rewritten head (force-push) or any code file still blocks. The merge gate
@@ -122,9 +197,7 @@ case "$BRANCH" in
122
197
  dev|main) ;;
123
198
  *)
124
199
  if pnpm -s bkit ci skip-token < /dev/null > /dev/null; then
125
- if command -v gh >/dev/null 2>&1; then
126
- # strip hook-injected GIT_DIR/GIT_WORK_TREE so gh resolves the repo from cwd (worktree-safe)
127
- OPEN_PR=$(env -u GIT_DIR -u GIT_WORK_TREE gh pr list --head "$BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || echo "")
200
+ if [ "$PR_LOOKUP" != "gh is not installed" ]; then
128
201
  if [ -n "$OPEN_PR" ]; then
129
202
  if [ -n "$PUSH_BRANCH_REMOTE_SHA" ] &&
130
203
  pnpm -s bkit ci bookkeeping-push --from="$PUSH_BRANCH_REMOTE_SHA" < /dev/null > /dev/null; then
@@ -134,6 +207,10 @@ case "$BRANCH" in
134
207
  echo "[pre-push] Add a clean trigger commit and re-push: git commit --allow-empty -m \"chore: trigger CI\" && git push" >&2
135
208
  exit 1
136
209
  fi
210
+ elif [ "$PR_LOOKUP_FULL" = "1" ]; then
211
+ echo "[pre-push] BLOCKED: HEAD on '$BRANCH' carries a CI-suppressing token and $PR_LOOKUP — an open PR for this branch cannot be ruled out." >&2
212
+ echo "[pre-push] Add a clean trigger commit and re-push: git commit --allow-empty -m \"chore: trigger CI\" && git push" >&2
213
+ exit 1
137
214
  fi
138
215
  else
139
216
  echo "[pre-push] WARN: HEAD on '$BRANCH' carries a CI-suppressing token but gh is unavailable to check for an open PR; allowing. If a PR is open, ensure HEAD triggers CI." >&2
@@ -171,6 +248,46 @@ done
171
248
  # block (seconds to ~30s, needing nothing the gates build) here too. Slow extras go below
172
249
  # the gates.
173
250
  #
251
+ # PR conflict: a feature branch whose open PR no longer merges into its base never starts CI,
252
+ # so the push stops here, before the gates. Fetches the base, then a trial merge of the pushed
253
+ # commit (`git merge-tree` exit 1 = conflicts; the work tree is untouched). A lookup, fetch or
254
+ # merge-tree that cannot answer warns and goes on: CI reports the conflict itself.
255
+ case "$BRANCH" in
256
+ dev|main|"") ;;
257
+ *)
258
+ if [ "$PR_LOOKUP" != "ok" ]; then
259
+ [ -z "$PR_LOOKUP" ] || echo "[pre-push] WARN: PR conflict check skipped — $PR_LOOKUP, so whether '$BRANCH' has an open PR that conflicts is unknown." >&2
260
+ elif [ -n "$OPEN_PR" ] && [ -n "$PR_BASE" ] && [ -n "$PUSH_BRANCH_SHA" ]; then
261
+ if [ "${BKIT_PR_CONFLICT_CHECK:-}" = "false" ]; then
262
+ echo "[pre-push] PR conflict check off (BKIT_PR_CONFLICT_CHECK=false)." >&2
263
+ # a shallow clone has no shared history with the base: the fetch would download all of it and merge-tree still refuse
264
+ elif [ "$(git rev-parse --is-shallow-repository 2>/dev/null)" = "true" ]; then
265
+ echo "[pre-push] WARN: PR conflict check skipped — shallow clone; run git fetch --unshallow to enable it." >&2
266
+ # explicit refspec: a single-branch clone's `git fetch origin <base>` would leave no origin/<base>
267
+ elif git fetch --quiet origin "+refs/heads/$PR_BASE:refs/remotes/origin/$PR_BASE" < /dev/null > /dev/null 2>&1; then
268
+ PR_MERGE_RC=0
269
+ # empty attribute source: GitHub applies no merge=union driver, so neither does this trial merge
270
+ PR_MERGE_OUT=$(git --attr-source="$(git hash-object -t tree /dev/null)" merge-tree --write-tree --name-only "refs/remotes/origin/$PR_BASE" "$PUSH_BRANCH_SHA" < /dev/null 2>/dev/null) || PR_MERGE_RC=$?
271
+ # exit 1 is a conflict only when the first output line is the result tree's OID
272
+ case "$PR_MERGE_OUT" in
273
+ [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]*) ;;
274
+ *) [ "$PR_MERGE_RC" != "1" ] || PR_MERGE_RC=2 ;;
275
+ esac
276
+ if [ "$PR_MERGE_RC" = "1" ]; then
277
+ echo "[pre-push] BLOCKED: PR #$OPEN_PR does not merge into '$PR_BASE', so CI would not start. Conflicting files:" >&2
278
+ echo "$PR_MERGE_OUT" | sed '1d;/^$/,$d;s/^/[pre-push] /' >&2
279
+ echo "[pre-push] Fix: git fetch origin $PR_BASE && git merge origin/$PR_BASE (or rebase), resolve, commit, push again." >&2
280
+ exit 1
281
+ elif [ "$PR_MERGE_RC" != "0" ]; then
282
+ echo "[pre-push] WARN: PR conflict check skipped — git merge-tree failed (exit $PR_MERGE_RC)." >&2
283
+ fi
284
+ else
285
+ echo "[pre-push] WARN: PR conflict check skipped — could not fetch '$PR_BASE' from origin." >&2
286
+ fi
287
+ fi
288
+ ;;
289
+ esac
290
+
174
291
  # bkit mirror-drift gate — fails if `.agents/*` was edited without `bkit install`
175
292
  # regenerating the `.claude/*`/`.cursor/*` mirrors (same check CI runs).
176
293
  # Outside the gate scripts: it validates the bkit install, not your source.
@@ -3,7 +3,7 @@
3
3
 
4
4
  # Serena — MCP server in cloud sessions
5
5
 
6
- Fits: repos that wire the Serena MCP server (`.bkit/templates.md` § Serena). There is no fetch block. A provision block on its own installs the `serena` binary in Claude cloud sessions, so the MCP server starts there too, and the `mcp-servers` entry lets every host run its tools without a prompt.
6
+ Fits: repos that wire the Serena MCP server (`.bkit/templates.md` § Serena). This template has no fetch block. A provision block on its own installs the `serena` binary in Claude cloud sessions, so the MCP server starts there too, and the `mcp-servers` entry lets every host run its tools without a prompt.
7
7
 
8
8
  - Secret: none.
9
9
  - CLI: `uv`, which is pre-installed on the Claude cloud image. The setup script runs as root, so the block pins uv's tool venv and bin dir to world-readable paths. Under root's `$HOME` (mode 0700), the session user could not run the binary.
@@ -3,77 +3,116 @@
3
3
 
4
4
  # Vercel — runtime logs
5
5
 
6
- Fits: apps deployed on Vercel. The `context=runtime` block returns the error and fatal lines from serverless and edge functions in a time window (default the last 4 h, in the preview environment). It prints a PII-safe projection that keeps `traceId`, to stitch to the `sentry` block.
6
+ Fits: apps deployed on Vercel. The `context=runtime` block queries error and fatal runtime logs in a time window (default the last 4 h, in the preview environment). It keeps `traceId` for correlation with the `sentry` block. Review the projected fields before enabling it: messages and request paths can contain personal data.
7
7
 
8
- - Secret: `VERCEL_TOKEN`, in the local env and in the cloud dashboard. No `vercel login` in headless runs, because headless agents cannot run it.
8
+ - Secret: `VERCEL_TOKEN`, in the local env and in the cloud dashboard. Use token authentication for headless runs.
9
9
  - Non-secret: `VERCEL_SCOPE`, the team slug. Uncomment its line in the block so cloud agents inherit it.
10
+ - Non-secret: `VERCEL_PROJECT`, the project ID or name. When unset, the CLI uses the linked project.
10
11
  - Non-secret: `VERCEL_ENV` (`preview` by default, or `production`).
11
12
  - Non-secret: `SINCE` / `UNTIL`, as ISO-8601 or relative times.
12
- - Non-secret: `VERCEL_MAX_PAGES`, the number of pages of 50 lines each (default 20).
13
- - CLI: `vercel`. The provision block installs it in cloud.
14
- - Each call returns at most 50 lines, the newest inside the window, whatever `--limit` says. The block pages backwards with `--until`, up to `VERCEL_MAX_PAGES`.
15
- - `--no-branch` is required, because without it CLI 50.x reads only the checked-out git branch.
16
- - `--level error` also returns `info` lines, so jq filters on `.level`.
17
- - For counts over a wide window, the Vercel MCP `get_runtime_logs` with `group_by` works better than lines.
13
+ - Non-secret: `VERCEL_MAX_PAGES`, an integer from 1 to 9999 pages of at most 50 records each (default 20).
14
+ - CLIs: `jq` and Vercel CLI 64.x or 65.x. Provisioning installs `vercel@65.0.0` only when absent. An unsupported installed version is reported without replacing it; update the CLI or review this recipe against that version's contract.
15
+ - The [Vercel logs contract](https://vercel.com/docs/cli/logs) wraps each event in `.data` and ends each page with a summary. The block follows `pagination.next` until `hasMore` is false or the page cap is reached. Continuations carry the original query and time window.
16
+ - A failed first page or invalid response self-skips. Failed later pages, excluded intervals and the page cap produce `TRUNCATED` output naming what remains unread.
17
+ - An empty result remains inconclusive until a known-error control and an independent dashboard read corroborate it.
18
18
 
19
- Copy the blocks below into `.agents/context.md`, below `<!-- bkit:end -->`.
19
+ Copy the blocks below into `.agents/context.md`, below `<!-- bkit:end -->`. Existing copies are owned by the project; re-adopt this recipe explicitly when updating their CLI contract.
20
20
 
21
21
  <!-- context-fetch:start vercel context=runtime -->
22
22
 
23
23
  ```bash
24
- # Vercel errors (read-only). Headless: set VERCEL_TOKEN and VERCEL_SCOPE (the team slug), and
25
- # do not use `vercel login`. The block targets the preview env by default (--environment below).
26
- # Set VERCEL_ENV=production to fetch production logs instead.
27
- # VERCEL_SCOPE is non-secret. Uncomment and set the line below so both local and cloud agents
28
- # inherit it, because headless cloud agents never read .bkit/.env:
24
+ # Vercel runtime errors (read-only), using the CLI 64.x / 65.x JSON Lines contract.
25
+ # Set VERCEL_TOKEN and VERCEL_SCOPE for headless authentication. The default env is preview.
26
+ # Uncomment this non-secret selector so local and cloud agents inherit it:
29
27
  # VERCEL_SCOPE="your-team-slug"
30
- # --no-branch: without it CLI 50.x filters to the checked-out git branch, and any other branch
31
- # reads 0 lines. Each call returns at most 50 lines, the newest in the window, whatever --limit
32
- # says, so the loop pages backwards with --until until a page comes back short. --level error
33
- # lets `info` through, so jq keeps error / fatal only. SINCE / UNTIL take ISO-8601
34
- # (2026-01-31T22:50:00Z) or a relative time (4h).
35
- # A failed first call → `skipped`. A failed later page or the page cap → a TRUNCATED line naming
36
- # the unread part.
37
- # Customise: VERCEL_ENV; SINCE / UNTIL; VERCEL_MAX_PAGES (x 50 lines); --source; path or status filter; jq keys to the log shape. Positive control (suggested): run once over a window holding a known error (e.g. a 5xx seen in the dashboard); nothing back = reader broken, not clean.
38
- command -v vercel >/dev/null && [ -n "${VERCEL_TOKEN:-}" ] && [ -n "${VERCEL_SCOPE:-}" ] \
39
- || { echo "[context-fetch:vercel] skipped — vercel CLI / VERCEL_TOKEN / VERCEL_SCOPE missing" >&2; exit 0; }
40
- VERCEL_PAGE=50
41
- VERCEL_ALL=$(mktemp); VERCEL_CHUNK=$(mktemp)
42
- trap 'rm -f "$VERCEL_ALL" "$VERCEL_CHUNK"' EXIT
43
- VERCEL_UNTIL="${UNTIL:-}"; VERCEL_PAGES=0; VERCEL_NOTE=""
44
- while [ "$VERCEL_PAGES" -lt "${VERCEL_MAX_PAGES:-20}" ]; do
28
+ # Set VERCEL_PROJECT when the checkout has no linked project.
29
+ # Cursor continuations retain the project, environment, query and time window.
30
+ # A skipped source is unavailable; TRUNCATED output names the unread remainder or intervals.
31
+ # Customise: VERCEL_ENV; VERCEL_PROJECT; SINCE / UNTIL; VERCEL_MAX_PAGES (x 50 records); --query; the projected keys and redaction. Positive control (suggested): run once over a window holding a known error and corroborate it in the dashboard; nothing back = reader broken, not clean.
32
+ command -v vercel >/dev/null && command -v jq >/dev/null && [ -n "${VERCEL_TOKEN:-}" ] && [ -n "${VERCEL_SCOPE:-}" ] \
33
+ || { echo "[context-fetch:vercel] skipped — vercel CLI / jq / VERCEL_TOKEN / VERCEL_SCOPE missing" >&2; exit 0; }
34
+ VERCEL_VERSION=$(vercel --version 2>/dev/null) \
35
+ || { echo "[context-fetch:vercel] skipped — vercel version unavailable" >&2; exit 0; }
36
+ case "$VERCEL_VERSION" in
37
+ 64.*|65.*) ;;
38
+ *) echo "[context-fetch:vercel] skipped — unsupported vercel CLI $VERCEL_VERSION; requires 64.x or 65.x" >&2; exit 0 ;;
39
+ esac
40
+ VERCEL_MAX_PAGES="${VERCEL_MAX_PAGES:-20}"
41
+ case "$VERCEL_MAX_PAGES" in
42
+ ''|0*|*[!0-9]*|?????*) echo "[context-fetch:vercel] skipped — VERCEL_MAX_PAGES must be an integer from 1 to 9999" >&2; exit 0 ;;
43
+ esac
44
+ if ! mkdir -p tmp || ! VERCEL_TMP=$(mktemp -d tmp/bkit-vercel.XXXXXX); then
45
+ echo "[context-fetch:vercel] skipped — temporary directory unavailable" >&2
46
+ exit 0
47
+ fi
48
+ trap 'rm -rf "$VERCEL_TMP"' 0
49
+ VERCEL_ALL="$VERCEL_TMP/logs"; VERCEL_CHUNK="$VERCEL_TMP/page"; VERCEL_NOTES="$VERCEL_TMP/notes"
50
+ : > "$VERCEL_ALL"; : > "$VERCEL_NOTES"
51
+ VERCEL_NEXT=""; VERCEL_PAGES=0
52
+ while [ "$VERCEL_PAGES" -lt "$VERCEL_MAX_PAGES" ]; do
45
53
  VERCEL_PAGES=$((VERCEL_PAGES + 1))
46
- if ! vercel logs \
47
- --token "$VERCEL_TOKEN" \
48
- --scope "$VERCEL_SCOPE" \
49
- --no-branch \
50
- --environment "${VERCEL_ENV:-preview}" \
51
- --level error --level fatal \
52
- --source serverless --source edge-function \
53
- --since "${SINCE:-4h}" \
54
- ${VERCEL_UNTIL:+--until "$VERCEL_UNTIL"} \
55
- --limit "$VERCEL_PAGE" \
56
- --json > "$VERCEL_CHUNK" 2>/dev/null; then
54
+ set -- logs runtime --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --limit 50 --json
55
+ if [ -n "$VERCEL_NEXT" ]; then
56
+ set -- "$@" --next "$VERCEL_NEXT"
57
+ else
58
+ set -- "$@" --environment "${VERCEL_ENV:-preview}" --query 'level:(error OR fatal)' --since "${SINCE:-4h}"
59
+ [ -z "${UNTIL:-}" ] || set -- "$@" --until "$UNTIL"
60
+ [ -z "${VERCEL_PROJECT:-}" ] || set -- "$@" --project "$VERCEL_PROJECT"
61
+ fi
62
+ if ! vercel "$@" > "$VERCEL_CHUNK" 2>/dev/null; then
63
+ [ "$VERCEL_PAGES" -gt 1 ] \
64
+ || { echo "[context-fetch:vercel] skipped — vercel logs exited non-zero (authentication, query, project or network failure)" >&2; exit 0; }
65
+ printf 'page %s failed — remaining cursor pages unread\n' "$VERCEL_PAGES" >> "$VERCEL_NOTES"
66
+ break
67
+ fi
68
+ if ! jq -se '
69
+ (map(select(.type == "summary")) | length) == 1 and
70
+ (last.type == "summary") and
71
+ (all(.[]; .type == "log" or .type == "summary" or .type == "warning")) and
72
+ (all(.[] | select(.type == "log"); (.data | type) == "object")) and
73
+ (last.recordsReturned == (map(select(.type == "log")) | length)) and
74
+ (last.recordsReturned <= 50) and
75
+ (last.timeRange.start | type == "string") and (last.timeRange.end | type == "string") and
76
+ (last.excludedIntervals | type == "array") and
77
+ ((last.pagination.hasMore == false and last.pagination.next == null) or
78
+ (last.pagination.hasMore == true and
79
+ (last.pagination.next == null or (last.pagination.next | type == "string" and length > 0))))
80
+ ' "$VERCEL_CHUNK" >/dev/null 2>&1; then
57
81
  [ "$VERCEL_PAGES" -gt 1 ] \
58
- || { echo "[context-fetch:vercel] skipped — vercel logs exited non-zero (bad token, scope or project, or host unreachable)" >&2; exit 0; }
59
- VERCEL_NOTE="page $VERCEL_PAGES failed — lines older than $VERCEL_UNTIL NOT read"; break
82
+ || { echo "[context-fetch:vercel] skipped — invalid JSON events or summary; source unavailable" >&2; exit 0; }
83
+ printf 'page %s has an invalid JSON response or summary — this page and remaining pages unread\n' "$VERCEL_PAGES" >> "$VERCEL_NOTES"
84
+ break
85
+ fi
86
+ jq -c 'select(.type == "log") | .data | select(.level == "error" or .level == "fatal") |
87
+ {time: .timestamp, level, source, requestPath, traceId, message}' "$VERCEL_CHUNK" >> "$VERCEL_ALL"
88
+ jq -r 'select(.type == "summary") | .excludedIntervals[] |
89
+ "excluded interval unread: \(.start) to \(.end)"' "$VERCEL_CHUNK" >> "$VERCEL_NOTES"
90
+ VERCEL_CURSOR=$(jq -r 'select(.type == "summary") | .pagination.next // empty' "$VERCEL_CHUNK")
91
+ if [ -z "$VERCEL_CURSOR" ]; then
92
+ if jq -e 'select(.type == "summary") | .pagination.hasMore' "$VERCEL_CHUNK" >/dev/null; then
93
+ echo "continuation unavailable — remaining pages unread" >> "$VERCEL_NOTES"
94
+ fi
95
+ break
96
+ fi
97
+ if [ "$VERCEL_CURSOR" = "$VERCEL_NEXT" ]; then
98
+ echo "cursor did not advance — remaining pages unread" >> "$VERCEL_NOTES"
99
+ break
60
100
  fi
61
- cat "$VERCEL_CHUNK" >> "$VERCEL_ALL"
62
- [ "$(grep -c . "$VERCEL_CHUNK")" -ge "$VERCEL_PAGE" ] || break
63
- # The next page ends 1 s after this page's oldest line. The overlap is de-duplicated by id below.
64
- VERCEL_NEXT=$(jq -rs 'map(.timestamp) | min / 1000 | floor + 1 | todate' "$VERCEL_CHUNK")
65
- [ "$VERCEL_NEXT" != "$VERCEL_UNTIL" ] \
66
- || { VERCEL_NOTE="over $VERCEL_PAGE lines inside one second at $VERCEL_NEXT — narrow --source or the window"; break; }
67
- VERCEL_UNTIL="$VERCEL_NEXT"
68
- [ "$VERCEL_PAGES" -lt "${VERCEL_MAX_PAGES:-20}" ] \
69
- || VERCEL_NOTE="stopped at VERCEL_MAX_PAGES=${VERCEL_MAX_PAGES:-20} — lines older than $VERCEL_UNTIL NOT read"
101
+ VERCEL_NEXT="$VERCEL_CURSOR"
102
+ [ "$VERCEL_PAGES" -lt "$VERCEL_MAX_PAGES" ] \
103
+ || printf 'stopped at VERCEL_MAX_PAGES=%s — remaining cursor pages unread\n' "$VERCEL_MAX_PAGES" >> "$VERCEL_NOTES"
70
104
  done
71
- VERCEL_LINES=$(jq -c 'select(.level == "error" or .level == "fatal")' "$VERCEL_ALL" | jq -sc 'unique_by(.id) | sort_by(-.timestamp) | .[]')
105
+ VERCEL_COUNT=$(jq -s 'length' "$VERCEL_ALL")
72
106
  printf '===== vercel %s error/fatal lines, since %s%s — %s lines, %s page(s) =====\n' \
73
- "${VERCEL_ENV:-preview}" "${SINCE:-4h}" "${UNTIL:+ until $UNTIL}" "$(printf '%s' "$VERCEL_LINES" | grep -c .)" "$VERCEL_PAGES"
74
- [ -z "$VERCEL_NOTE" ] || { printf '===== TRUNCATED: %s =====\n' "$VERCEL_NOTE"; echo "[context-fetch:vercel] truncated — $VERCEL_NOTE" >&2; }
75
- printf '%s\n' "$VERCEL_LINES" | grep . \
76
- | jq -c '{time: (.timestamp / 1000 | floor | todate), level, source, requestPath, responseStatusCode, traceId, message}' # PII-safe projection; traceId stitches to the sentry block, message is free-text — adjust keys to your log shape
107
+ "${VERCEL_ENV:-preview}" "${SINCE:-4h}" "${UNTIL:+ until $UNTIL}" "$VERCEL_COUNT" "$VERCEL_PAGES"
108
+ while IFS= read -r VERCEL_NOTE; do
109
+ printf '===== TRUNCATED: %s =====\n' "$VERCEL_NOTE"
110
+ printf '[context-fetch:vercel] truncated — %s\n' "$VERCEL_NOTE" >&2
111
+ done < "$VERCEL_NOTES"
112
+ cat "$VERCEL_ALL"
113
+ if [ "$VERCEL_COUNT" -eq 0 ]; then
114
+ echo "===== Empty result is inconclusive: retry a known-error window and corroborate in the dashboard. ====="
115
+ fi
77
116
  ```
78
117
 
79
118
  <!-- context-fetch:end -->
@@ -81,9 +120,14 @@ printf '%s\n' "$VERCEL_LINES" | grep . \
81
120
  <!-- context-fetch:provision vercel -->
82
121
 
83
122
  ```bash
84
- # Install the vercel CLI in cloud if it is absent. The block guards itself and does nothing when
85
- # the CLI is present.
86
- command -v vercel >/dev/null 2>&1 || pnpm add -g vercel
123
+ # Install the supported CLI only when absent; report incompatible installations without replacing them.
124
+ command -v vercel >/dev/null 2>&1 || pnpm add -g vercel@65.0.0 || exit 1
125
+ VERCEL_VERSION=$(vercel --version 2>/dev/null) \
126
+ || { echo "[context-fetch:vercel] provision failed — vercel version unavailable" >&2; exit 1; }
127
+ case "$VERCEL_VERSION" in
128
+ 64.*|65.*) ;;
129
+ *) echo "[context-fetch:vercel] provision failed — unsupported vercel CLI $VERCEL_VERSION; requires 64.x or 65.x" >&2; exit 1 ;;
130
+ esac
87
131
  ```
88
132
 
89
133
  <!-- context-fetch:end -->
@@ -0,0 +1,98 @@
1
+ > Starter document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/architecture.md`, fill it in, then delete this introduction.
2
+ >
3
+ > **Fill these first:** `docs/technology.md`.
4
+ >
5
+ > **Finish against:** none.
6
+ >
7
+ > **Where the facts come from:** the repository's top-level folders and package manifests, the build and deploy configuration, the CI configuration and the infrastructure files.
8
+ >
9
+ > **Fill in:**
10
+ >
11
+ > 1. Copy this starter to `docs/architecture.md`.
12
+ > 2. List the top-level source folders and the package manifests, and group them into runtimes: parts that run in one process or one place.
13
+ > 3. Draw `## System context` as one chart with a `subgraph` per runtime, and name each runtime and external system as the tables below name them.
14
+ > 4. Fill `## Containers` with one row per runtime and what it owns.
15
+ > 5. Fill `## Package boundaries` with who may call whom, and name the check that enforces each boundary.
16
+ > 6. Fill `## File placement` with one row per kind of file the repository holds. Agents place every new file by this table.
17
+ > 7. Fill `## Environments` with where each part runs. Leave each environment's branch, URL and release trigger to `docs/deployments.md`.
18
+ > 8. Record unresolved facts under `## Open questions`.
19
+ > 9. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/architecture.md` | ● | ● | ● | ○ | ○ | How the system is built and where it runs: runtimes, package boundaries, file placement and environments. |
20
+ > 10. Check the document against each completion check, then delete this introduction.
21
+ >
22
+ > **If it does not apply:** every project has a structure. Write `Not applicable: {reason}` under a section that does not apply, such as `## Package boundaries` for a single-package repository.
23
+ >
24
+ > **Completion checks:**
25
+ >
26
+ > - Exactly one Mermaid chart, and it renders in a Mermaid-capable viewer.
27
+ > - Every runtime in the chart has a row in `## Containers`.
28
+ > - Every top-level source folder appears in a row of `## File placement`.
29
+ > - Every environment names where it runs, with no branch, URL or release trigger.
30
+ > - No example row remains.
31
+
32
+ # Architecture
33
+
34
+ > [!CAUTION]
35
+ > **Purpose:** How the system is built and where it runs: runtimes, package boundaries, file placement and environments.
36
+ >
37
+ > **Rules:**
38
+ >
39
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
40
+ > - Hold topology and boundaries only. Library lists and operational rules go in the domain docs.
41
+ > - Cite the repository evidence for each fact: a path, a configuration file or a CI job.
42
+ >
43
+ > **Not here:** The chosen libraries go in `docs/technology.md`. Each environment's branch, URL and release trigger go in `docs/deployments.md` § Environments. Purpose-based responsibilities go in `docs/components.md`.
44
+ >
45
+ > **Update when:** A package, runtime or kind of file is added or removed, a boundary shifts, or an environment is added or removed.
46
+
47
+ ## System context
48
+
49
+ [The runtimes of the system and the external systems each one talks to. The arrows show which part calls which.]
50
+
51
+ ```mermaid
52
+ flowchart LR
53
+ subgraph CLIENT["Client runtime"]
54
+ UI["User interface"]
55
+ end
56
+ subgraph SERVER["Server runtime"]
57
+ API["Report service"]
58
+ end
59
+ STORE["Record storage"]
60
+ UI --> API
61
+ API --> STORE
62
+ ```
63
+
64
+ ## Containers
65
+
66
+ <!-- prettier-ignore -->
67
+ | Runtime | Owns | Talks to |
68
+ | --- | --- | --- |
69
+ | [Runtime name] | [What it is responsible for.] | [Other runtimes and external systems.] |
70
+ | [e.g., Report service] | Report preparation and saving. | The user interface and record storage. |
71
+
72
+ ## Package boundaries
73
+
74
+ <!-- prettier-ignore -->
75
+ | Package or folder | May call | Must not call | Enforced by |
76
+ | --- | --- | --- | --- |
77
+ | [Package or folder] | [What it may depend on.] | [What it must not depend on.] | [Check or review step.] |
78
+ | [e.g., Report service] | The shared library. | The user interface. | The import-boundary lint rule. |
79
+
80
+ ## File placement
81
+
82
+ <!-- prettier-ignore -->
83
+ | Kind of file | Goes in | Naming |
84
+ | --- | --- | --- |
85
+ | [Kind of file] | [Folder.] | [Name pattern.] |
86
+ | [e.g., Unit test] | Next to the file it tests. | The source file's name with a test suffix. |
87
+
88
+ ## Environments
89
+
90
+ <!-- prettier-ignore -->
91
+ | Environment | Hosting | Data store | Who uses it |
92
+ | --- | --- | --- | --- |
93
+ | [Environment] | [Where the parts run.] | [Which store it uses.] | [Who uses it.] |
94
+ | [e.g., Production] | A managed hosting platform. | The production database. | End users. |
95
+
96
+ ## Open questions
97
+
98
+ [Each unresolved fact, who can answer it and which section it affects.]
@@ -1,6 +1,21 @@
1
- > Example output. Copy it to `docs/capabilities.md` and own it. `bkit install` does not write this file and does not overwrite a copy.
1
+ > Generated document. `bkit install` does not write this file and does not overwrite a copy. Copy it to `docs/capabilities.md`, build it with the command below, then delete this introduction.
2
2
  >
3
- > `pnpm bkit:graph:rollup` rewrites everything outside the Overrides block, so do not edit the generated body. To add a capability, add it in `scripts/graphify/bkit-graph-drift-rules.json`. How to run the tools is in `.bkit/templates.md`.
3
+ > **Fill these first:** `docs/deployments.md`.
4
+ >
5
+ > **Prerequisites:** the code exists, and the graphify templates are adopted as `.bkit/templates.md` § graphify — map describes.
6
+ >
7
+ > **Build it:**
8
+ >
9
+ > 1. Copy this starter to `docs/capabilities.md`.
10
+ > 2. Add each capability to `scripts/graphify/bkit-graph-drift-rules.json`. That file is the source of truth, and it stays hand-maintained.
11
+ > 3. Run `pnpm bkit:graph:rollup` to build the register from the working tree. Run it while you edit, when you want to see the result before staging.
12
+ > 4. Run `pnpm bkit:graph:refresh` to build the register from the staged files in a throwaway checkout. Run it before a commit, so the committed file matches the committed code.
13
+ > 5. Edit only the text outside the `graphify:start` and `graphify:end` marker lines. Each run rewrites everything between them.
14
+ > 6. Record unresolved facts under `## Open questions`.
15
+ > 7. Add this row to the `## Project Documents` table in `.agents/docs.md`: | `docs/capabilities.md` | ● | ● | ● | — | ○ | One row per capability, with its owner module, the literal marker that finds every use of it, and whether anything bypasses the owner. |
16
+ > 8. Check the document against each completion check, then delete this introduction.
17
+ >
18
+ > **Completion checks:** the register has a row for every capability in `scripts/graphify/bkit-graph-drift-rules.json`, every responsibility in `docs/components.md` that owns a capability appears in both documents, and the text between the two marker lines no longer reads `Not built`.
4
19
 
5
20
  # Capabilities
6
21
 
@@ -9,41 +24,30 @@
9
24
  >
10
25
  > **Rules:**
11
26
  >
12
- > - This file is generated. `pnpm bkit:graph:refresh` rewrites it.
27
+ > - Follow `.bkit/authoring.md` § Docs when you edit this file.
28
+ > - `pnpm bkit:graph:rollup` and `pnpm bkit:graph:refresh` rewrite everything between the `graphify:start` and `graphify:end` marker lines. Never edit between them, and keep exactly one of each.
13
29
  > - The source of truth is `scripts/graphify/bkit-graph-drift-rules.json`. Each status is derived from the tree, never typed in.
30
+ > - To add a capability, add a rule there: capability, lane, owner module and one literal marker.
14
31
  > - Markers are literal, never regex. A regex metacharacter in a marker matches nothing, and the row then reads as a clean result.
15
- > - Optional `scope`: path prefixes.
16
- > - Optional `surface`: `product` (default), `tests` or `all`.
32
+ > - Match the mechanism, not the name, because a marker such as `createClient(` misses an owner that imports it under another name.
33
+ > - Optional `scope`: path prefixes that narrow the tree scanned, for a marker that means different things per package.
34
+ > - Optional `surface`: `product` (default), `tests` or `all`. `tests` is every `e2e/` folder and every `.test.` or `.spec.` file, and `product` is every other file.
17
35
  > - Optional `budgets`: the exact non-owner site count allowed per scope prefix. Measured = declared → `budgeted`.
18
- > - Only the Overrides block is hand-maintained. A malformed block aborts the run.
19
-
20
- ## Status Vocabulary
21
-
22
- <!-- prettier-ignore -->
23
- | Status | Meaning | Action |
24
- | --- | --- | --- |
25
- | `split` | Two or more implementations, no single owner | Centralise, or budget it and say why in `note` |
26
- | `bypassed` | Owner exists, some callers skip it | Repoint the callers, or budget them |
27
- | `dead` | A client fetches a path nothing serves | Check the call site |
28
- | `gap` | No owner file yet | Name the owner before the first caller |
29
- | `budgeted` | A `split` or `bypassed` whose site count matches the declared budget | None, until a site appears or disappears |
30
- | `one` | Every caller goes through the owner | None |
36
+ > - The generator reads the Overrides block before it writes. A malformed block aborts the run.
37
+ >
38
+ > **Not here:** The purpose-based view of responsibilities goes in `docs/components.md`. Implementation boundaries and deployment topology go in `docs/architecture.md`. Issue state stays in the tracker.
39
+ >
40
+ > **Update when:** A rule in `scripts/graphify/bkit-graph-drift-rules.json` is added, changed or removed, or a code change moves a status. Run `pnpm bkit:graph:refresh` in the same change.
31
41
 
32
- ## Register
42
+ <!-- graphify:start -->
33
43
 
34
44
  Not built. Run `pnpm bkit:graph:rollup`.
35
45
 
36
- ## Unreachable API calls
37
-
38
- Not scanned.
39
-
40
- ## Import-time side effects
41
-
42
- Not scanned.
46
+ <!-- graphify:end -->
43
47
 
44
48
  ## Overrides
45
49
 
46
- This is the only hand-maintained region. Use it to rename a node, hide a node or an edge, pin a note, or force nodes into a named group. Each `hide_nodes` entry needs a one-line reason in `hide_nodes_why`.
50
+ Use this block to rename a node, hide a node or an edge, pin a note, or force nodes into a named group. Each `hide_nodes` entry needs a one-line reason in `hide_nodes_why`.
47
51
 
48
52
  <!-- overrides:start -->
49
53
 
@@ -60,14 +64,6 @@ This is the only hand-maintained region. Use it to rename a node, hide a node or
60
64
 
61
65
  <!-- overrides:end -->
62
66
 
63
- ## User-facing routes → backend capabilities
64
-
65
- No route layer yet. Run `pnpm bkit:graph:rollup`.
66
-
67
- ## Architecture — packages
68
-
69
- Filled by `pnpm bkit:graph:rollup`.
70
-
71
- ## Architecture — modules
67
+ ## Open questions
72
68
 
73
- Filled by `pnpm bkit:graph:rollup`.
69
+ [Each unresolved fact, who can answer it and which section it affects.]