@cbartens/bkit 5.1.0 → 5.2.1

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 (193) hide show
  1. package/.bkit/README.md +11 -7
  2. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +39 -50
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +74 -56
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +72 -0
  5. package/.bkit/core/.agents/rules.md +8 -4
  6. package/.bkit/core/.agents/shortcuts.md +1 -1
  7. package/.bkit/core/.bkit/LICENSE.md +18 -140
  8. package/.bkit/core/.bkit/README.md +10 -6
  9. package/.bkit/core/.bkit/cloud.md +12 -15
  10. package/.bkit/core/.bkit/comparison.md +66 -14
  11. package/.bkit/core/.bkit/install.md +31 -8
  12. package/.bkit/core/.bkit/jsonl.md +0 -1
  13. package/.bkit/core/.bkit/prompts.md +14 -13
  14. package/.bkit/core/.bkit/providers.md +92 -26
  15. package/.bkit/core/.bkit/templates.md +38 -11
  16. package/.bkit/core/.bkit/workflows.md +63 -41
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +4 -3
  18. package/.bkit/core/.claude/hooks/bkit-readguard.cjs +60 -0
  19. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +8 -6
  20. package/.bkit/core/.codex/hooks/bkit-readguard.cjs +58 -0
  21. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +12 -19
  22. package/.bkit/core/.cursor/hooks/bkit-readguard.cjs +59 -0
  23. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +73 -22
  24. package/.bkit/core/.opencode/plugin/bkit-readguard.js +126 -0
  25. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  26. package/.bkit/core/docs/templates/bkit-plan.md +6 -3
  27. package/.bkit/core/engine/checks/after/auth.ts +32 -0
  28. package/.bkit/core/engine/checks/after/github.ts +4 -4
  29. package/.bkit/core/engine/checks/after/index.ts +36 -50
  30. package/.bkit/core/engine/checks/after/managed.ts +40 -0
  31. package/.bkit/core/engine/checks/before/index.ts +5 -4
  32. package/.bkit/core/engine/checks/before/mcp.ts +60 -54
  33. package/.bkit/core/engine/checks/status-holes.ts +1 -1
  34. package/.bkit/core/engine/checks/tips/catalogue.ts +356 -0
  35. package/.bkit/core/engine/checks/tips/detect.ts +144 -0
  36. package/.bkit/core/engine/checks/tips/index.ts +174 -0
  37. package/.bkit/core/engine/cli.ts +57 -9
  38. package/.bkit/core/engine/commands/install/doctor.ts +5 -1
  39. package/.bkit/core/engine/commands/install/install.ts +39 -9
  40. package/.bkit/core/engine/commands/install/uninstall.ts +32 -18
  41. package/.bkit/core/engine/commands/install/upgrade.ts +15 -28
  42. package/.bkit/core/engine/commands/launch.ts +33 -11
  43. package/.bkit/core/engine/commands/tips.ts +16 -0
  44. package/.bkit/core/engine/commands/workflow/runs.ts +57 -16
  45. package/.bkit/core/engine/commands/workflow/runtime.ts +10 -0
  46. package/.bkit/core/engine/commands/workflow/steps.ts +1 -0
  47. package/.bkit/core/engine/commands/workflow/tests.ts +647 -4
  48. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -4
  49. package/.bkit/core/engine/install/cloud-env.ts +7 -21
  50. package/.bkit/core/engine/install/hosts.ts +21 -0
  51. package/.bkit/core/engine/install/managed-block.ts +36 -0
  52. package/.bkit/core/engine/install/manifest.ts +46 -4
  53. package/.bkit/core/engine/install/modules/antigravity.ts +8 -7
  54. package/.bkit/core/engine/install/modules/claude.ts +6 -6
  55. package/.bkit/core/engine/install/modules/cloud.ts +2 -2
  56. package/.bkit/core/engine/install/modules/codex.ts +5 -5
  57. package/.bkit/core/engine/install/modules/core.ts +23 -9
  58. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  59. package/.bkit/core/engine/install/modules/opencode.ts +4 -4
  60. package/.bkit/core/engine/install/payload-links.ts +6 -10
  61. package/.bkit/core/engine/install/placeholders.ts +1 -1
  62. package/.bkit/core/engine/install/version-file.ts +17 -9
  63. package/.bkit/core/engine/install/write.ts +68 -1
  64. package/.bkit/core/engine/ledgers/telemetry.ts +0 -2
  65. package/.bkit/core/engine/shared/package-roots.ts +8 -10
  66. package/.bkit/core/hooks/antigravity-hook.js +67 -0
  67. package/.bkit/core/hooks/gateguard-edit-payload.js +4 -4
  68. package/.bkit/core/hooks/gateguard-engine.js +16 -6
  69. package/.bkit/core/hooks/guardrails-read.js +23 -0
  70. package/.bkit/core/hooks/readguard-engine.js +259 -0
  71. package/.bkit/core/hooks/readguard-payload.js +67 -0
  72. package/.bkit/core/prompts/bkit-audit-generate.md +1 -0
  73. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -0
  74. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -0
  75. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -0
  76. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -0
  77. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -0
  78. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -0
  79. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -0
  80. package/.bkit/core/prompts/bkit-build-plan-execute.md +5 -1
  81. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -0
  82. package/.bkit/core/prompts/bkit-build-plan-verify.md +11 -3
  83. package/.bkit/core/prompts/bkit-build-summary.md +1 -0
  84. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -0
  85. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -0
  86. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -0
  87. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -0
  88. package/.bkit/core/prompts/bkit-debug-summary.md +1 -0
  89. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +1 -0
  90. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +1 -0
  91. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +1 -0
  92. package/.bkit/core/prompts/bkit-design-generate.md +9 -4
  93. package/.bkit/core/prompts/bkit-design-organise.md +1 -0
  94. package/.bkit/core/prompts/bkit-design-review-1.md +1 -0
  95. package/.bkit/core/prompts/bkit-design-review-2.md +1 -0
  96. package/.bkit/core/prompts/bkit-design-spike.md +1 -0
  97. package/.bkit/core/prompts/bkit-design-summary.md +1 -0
  98. package/.bkit/core/prompts/bkit-design-update.md +1 -0
  99. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -0
  100. package/.bkit/core/prompts/bkit-plan-complexity-split.md +3 -2
  101. package/.bkit/core/prompts/bkit-plan-generate.md +1 -0
  102. package/.bkit/core/prompts/bkit-plan-review-1.md +1 -0
  103. package/.bkit/core/prompts/bkit-plan-review-2.md +1 -0
  104. package/.bkit/core/prompts/bkit-plan-review-3.md +1 -0
  105. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +2 -1
  106. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +2 -1
  107. package/.bkit/core/prompts/bkit-plan-summary.md +1 -0
  108. package/.bkit/core/prompts/bkit-plan-update.md +2 -1
  109. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -0
  110. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -0
  111. package/.bkit/core/prompts/bkit-ship-summary.md +1 -0
  112. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -0
  113. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +1 -0
  114. package/.bkit/core/prompts/bkit-utility-update-decisions.md +1 -0
  115. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +1 -0
  116. package/.bkit/core/prompts/bkit-utility-update-documentation.md +1 -0
  117. package/.bkit/core/prompts/bkit-utility-update-failures.md +1 -0
  118. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +1 -0
  119. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +1 -0
  120. package/.bkit/core/workflows/bkit-build.md +33 -21
  121. package/.bkit/core/workflows/bkit-debug.md +29 -22
  122. package/.bkit/core/workflows/bkit-design.md +81 -38
  123. package/.bkit/core/workflows/bkit-plan.md +8 -2
  124. package/.bkit/core/workflows/bkit-ship.md +8 -2
  125. package/.bkit/shared/.agents/plugins/bkit/hooks.json +13 -3
  126. package/.bkit/shared/.claude/settings.json +19 -0
  127. package/.bkit/shared/.codex/hooks.json +21 -0
  128. package/.bkit/shared/.cursor/hooks.json +6 -1
  129. package/.bkit/shared/.opencode/opencode.json +1 -1
  130. package/.bkit/shared/docs/deployments.md +1 -1
  131. package/.bkit/shared/docs/testing.md +12 -1
  132. package/.bkit/templates/.github/dependabot.yml +6 -0
  133. package/.bkit/templates/.github/renovate.json5 +3 -3
  134. package/.bkit/templates/.github/workflows/bkit-ci.yml +0 -13
  135. package/.bkit/templates/.prettierignore +1 -1
  136. package/.bkit/templates/context/bkit-expo.md +22 -13
  137. package/.bkit/templates/context/bkit-github.md +20 -6
  138. package/.bkit/templates/context/bkit-inngest.md +10 -4
  139. package/.bkit/templates/context/bkit-maestro.md +5 -5
  140. package/.bkit/templates/context/bkit-playwright.md +3 -3
  141. package/.bkit/templates/context/bkit-sentry.md +6 -5
  142. package/.bkit/templates/context/bkit-stripe.md +31 -8
  143. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +65 -19
  144. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +34 -0
  145. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +33 -12
  146. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +54 -0
  147. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +76 -6
  148. package/.bkit/templates/slop-scan.config.json +7 -2
  149. package/CHANGELOG.md +50 -0
  150. package/LICENSE.md +21 -161
  151. package/README.md +61 -28
  152. package/dist/checks/after/auth.js +28 -0
  153. package/dist/checks/after/github.js +4 -4
  154. package/dist/checks/after/index.js +29 -45
  155. package/dist/checks/after/managed.js +40 -1
  156. package/dist/checks/before/index.js +5 -4
  157. package/dist/checks/before/mcp.js +53 -53
  158. package/dist/checks/status-holes.js +1 -1
  159. package/dist/checks/tips/catalogue.js +297 -0
  160. package/dist/checks/tips/detect.js +130 -0
  161. package/dist/checks/tips/index.js +146 -0
  162. package/dist/cli.js +47 -9
  163. package/dist/commands/install/doctor.js +5 -1
  164. package/dist/commands/install/install.js +27 -7
  165. package/dist/commands/install/uninstall.js +31 -16
  166. package/dist/commands/install/upgrade.js +15 -32
  167. package/dist/commands/launch.js +27 -11
  168. package/dist/commands/tips.js +10 -0
  169. package/dist/commands/workflow/runs.js +52 -16
  170. package/dist/commands/workflow/runtime.js +8 -0
  171. package/dist/commands/workflow/steps.js +1 -0
  172. package/dist/commands/workflow/tests.js +541 -4
  173. package/dist/commands/workflow/workstreams.js +4 -4
  174. package/dist/install/cloud-env.js +3 -14
  175. package/dist/install/hosts.js +22 -0
  176. package/dist/install/managed-block.js +36 -0
  177. package/dist/install/manifest.js +45 -4
  178. package/dist/install/modules/antigravity.js +8 -7
  179. package/dist/install/modules/claude.js +6 -6
  180. package/dist/install/modules/cloud.js +2 -2
  181. package/dist/install/modules/codex.js +5 -5
  182. package/dist/install/modules/core.js +14 -5
  183. package/dist/install/modules/cursor.js +6 -6
  184. package/dist/install/modules/opencode.js +4 -4
  185. package/dist/install/payload-links.js +5 -5
  186. package/dist/install/placeholders.js +1 -1
  187. package/dist/install/version-file.js +12 -3
  188. package/dist/install/write.js +61 -2
  189. package/dist/shared/package-roots.js +8 -11
  190. package/package.json +4 -6
  191. package/.bkit/core/LICENSE.md +0 -149
  192. package/.bkit/shared/LICENSE.md +0 -22
  193. package/.bkit/templates/LICENSE.md +0 -22
package/LICENSE.md CHANGED
@@ -1,161 +1,21 @@
1
- # bkit licence
2
-
3
- bkit is source-available: anyone can read all of it, and you can use it for free if either licence below fits you.
4
-
5
- <!-- prettier-ignore -->
6
- | Licence | Free for |
7
- | --- | --- |
8
- | [PolyForm Noncommercial 1.0.0](#polyform-noncommercial-license-100) | Personal and hobby use, and charities, schools, research bodies, public safety and health bodies, environmental groups and government, whatever their size |
9
- | [PolyForm Small Business 1.0.0](#polyform-small-business-license-100) | Any use, commercial included, by a person or company with fewer than 100 people and under US$1M revenue in the prior tax year (2019 dollars, adjusted for inflation) |
10
-
11
- Pick whichever fits. If neither does, email bkit@bartens.biz for a commercial licence.
12
-
13
- - **What bkit's agents write for you is yours.** These licences cover bkit itself, not the code, docs or other output its agents produce in your repo.
14
- - **A folder with its own `LICENSE.md` is covered by that file instead of this one.** Everything in `.bkit/shared/` and `.bkit/templates/` is MIT-0, so you can do anything with those files, and a template you copy into your repo is yours.
15
- - This summary is a guide. Where it and the licence texts below differ, the licence texts apply.
16
-
17
- Required Notice: Copyright 2026 Christian Bartens (https://github.com/cbartens/bkit)
18
-
19
- ---
20
-
21
- # PolyForm Noncommercial License 1.0.0
22
-
23
- <https://polyformproject.org/licenses/noncommercial/1.0.0>
24
-
25
- ## Acceptance
26
-
27
- In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
28
-
29
- ## Copyright License
30
-
31
- The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
32
-
33
- ## Distribution License
34
-
35
- The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
36
-
37
- ## Notices
38
-
39
- You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
40
-
41
- > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
42
-
43
- ## Changes and New Works License
44
-
45
- The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
46
-
47
- ## Patent License
48
-
49
- The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
50
-
51
- ## Noncommercial Purposes
52
-
53
- Any noncommercial purpose is a permitted purpose.
54
-
55
- ## Personal Uses
56
-
57
- Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
58
-
59
- ## Noncommercial Organizations
60
-
61
- Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
62
-
63
- ## Fair Use
64
-
65
- You may have "fair use" rights for the software under the law. These terms do not limit them.
66
-
67
- ## No Other Rights
68
-
69
- These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
70
-
71
- ## Patent Defense
72
-
73
- If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
74
-
75
- ## Violations
76
-
77
- The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
78
-
79
- ## No Liability
80
-
81
- _**As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.**_
82
-
83
- ## Definitions
84
-
85
- The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
86
-
87
- **You** refers to the individual or entity agreeing to these terms.
88
-
89
- **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
90
-
91
- **Your licenses** are all the licenses granted to you for the software under these terms.
92
-
93
- **Use** means anything you do with the software requiring one of your licenses.
94
-
95
- ---
96
-
97
- # PolyForm Small Business License 1.0.0
98
-
99
- <https://polyformproject.org/licenses/small-business/1.0.0>
100
-
101
- ## Acceptance
102
-
103
- In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
104
-
105
- ## Copyright License
106
-
107
- The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
108
-
109
- ## Distribution License
110
-
111
- The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
112
-
113
- ## Notices
114
-
115
- You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
116
-
117
- > Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
118
-
119
- ## Changes and New Works License
120
-
121
- The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
122
-
123
- ## Patent License
124
-
125
- The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
126
-
127
- ## Fair Use
128
-
129
- You may have "fair use" rights for the software under the law. These terms do not limit them.
130
-
131
- ## Small Business
132
-
133
- Use of the software for the benefit of your company is use for a permitted purpose if your company has fewer than 100 total individuals working as employees and independent contractors, and less than 1,000,000 USD (2019) total revenue in the prior tax year. Adjust this revenue threshold for inflation according to the United States Bureau of Labor Statistics' consumer price index for all urban consumers, U.S. city average, for all items, not seasonally adjusted, with 1982–1984=100 reference base.
134
-
135
- ## No Other Rights
136
-
137
- These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
138
-
139
- ## Patent Defense
140
-
141
- If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
142
-
143
- ## Violations
144
-
145
- The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
146
-
147
- ## No Liability
148
-
149
- _**As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.**_
150
-
151
- ## Definitions
152
-
153
- The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
154
-
155
- **You** refers to the individual or entity agreeing to these terms.
156
-
157
- **Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
158
-
159
- **Your licenses** are all the licenses granted to you for the software under these terms.
160
-
161
- **Use** means anything you do with the software requiring one of your licenses.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Christian Bartens
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -8,7 +8,7 @@
8
8
  <p align="center">
9
9
  <a href="https://github.com/cbartens/bkit/actions/workflows/bkit-ci.yml"><img alt="CI" src="https://github.com/cbartens/bkit/actions/workflows/bkit-ci.yml/badge.svg?branch=main"></a>
10
10
  <a href="https://www.npmjs.com/package/@cbartens/bkit"><img alt="npm version" src="https://img.shields.io/npm/v/@cbartens/bkit"></a>
11
- <a href="#license"><img alt="License: PolyForm Noncommercial or PolyForm Small Business" src="https://img.shields.io/badge/license-PolyForm%20Noncommercial%20%2F%20Small%20Business-blue"></a>
11
+ <a href="#license"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
12
12
  <img alt="Node 20+" src="https://img.shields.io/badge/node-%E2%89%A520-339933">
13
13
  <img alt="Works with Claude Code, Cursor, Codex, Antigravity and opencode" src="https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Antigravity%20%C2%B7%20opencode-8250df">
14
14
  </p>
@@ -19,6 +19,7 @@
19
19
  <a href="#a-ci-pipeline-built-the-way-senior-teams-build-them">CI template</a> ·
20
20
  <a href="#right-context-at-the-right-step">Context</a> ·
21
21
  <a href="#faq">FAQ</a> ·
22
+ <a href=".bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks">Comparison</a> ·
22
23
  <a href=".bkit/install.md">Install guide</a>
23
24
  </p>
24
25
 
@@ -29,12 +30,12 @@ AI coding agents are fast, but on their own they skip the parts that make softwa
29
30
  - **For solo founders and makers** who have outgrown vibe coding: you get the habits of a senior engineering team without hiring one. You need to be able to read a plan and make a call, not write the code.
30
31
  - **For engineers** who want a proven agentic process instead of building their own: rules, prompts, workflows, guardrails, audits and a CI pipeline that already work together.
31
32
 
32
- **Battle-tested, not a weekend prompt pack.** bkit is built with bkit. Its rules, prompts and workflows have been refined over >1,000 commits, >500 issues and >100 merged pull requests run through its own pipeline, and that history is recorded in >200 lessons and >300 decisions agents read before they start.
33
+ **Researched and battle-tested, not a weekend prompt pack.** bkit is built with bkit. Its rules, prompts and workflows come from months of research into how agentic engineering works best, refined over >1,000 commits, >500 issues and >100 merged pull requests run through its own pipeline. That history is recorded in >200 lessons and >300 decisions agents read before they start. How it compares with other AI development frameworks, feature by feature: [`.bkit/comparison.md`](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks).
33
34
 
34
35
  <p align="center">
35
36
  <picture>
36
37
  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-features-dark.svg">
37
- <img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan: five reviewers, big work split up, learns from past bugs and postponed work, more than 30 audits. Build: writes and verifies, hunts bugs and security holes, checks the plan is still current, skills on demand. Debug: outside evidence from CI and your platforms, root cause first, hard-bug mode, knows when to stop. Ship: honest CI, nothing quietly dropped, docs and memory, never touches main. Every phase: any AI tool, best model per job, independent review, laptop to cloud." src=".github/assets/bkit-features-light.svg" width="100%">
38
+ <img alt="What ships with bkit, one coloured row per phase. Design: three rival designs, probe code for the risky unknowns, reads your history, reviewed for failure modes. Plan: five reviewers, big work split up, learns from past bugs and postponed work, more than 30 audits. Build: test first and verified, hunts bugs and security holes, checks the plan is still current, skills on demand. Debug: outside evidence from CI and your platforms, root cause first, hard-bug mode, knows when to stop. Ship: honest CI, nothing quietly dropped, docs and memory, never touches main. Every phase: any AI tool, best model per job, independent review, laptop to cloud." src=".github/assets/bkit-features-light.svg" width="100%">
38
39
  </picture>
39
40
  </p>
40
41
 
@@ -62,7 +63,7 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
62
63
  | --- | --- | --- |
63
64
  | Work out how to build it | `/bkit-design` | Reads related issues and past decisions, has three agents propose different approaches and two critique them, and writes throwaway code to test any risky unknowns the reviewers flag. You get one design to approve. |
64
65
  | Plan the work | `/bkit-plan` | A step-by-step plan, stress-tested by five reviewers who also see past bugs and postponed work. Too big for one build? It's split into pieces. You approve it. |
65
- | Build it | `/bkit-build` | Checks the plan still matches the code, writes it, verifies every task, hunts for bugs and security holes, adds edge-case tests, and opens a pull request. |
66
+ | Build it | `/bkit-build` | Checks the plan still matches the code, writes each task's tests before its code, verifies every task, hunts for bugs and security holes, adds edge-case tests, and opens a pull request. |
66
67
  | Fix what broke | `/bkit-debug` | Pulls evidence from CI and your platforms, finds the root cause, fixes it, re-tests and records the lesson. Hard runtime bugs get their own mode; if it can't fix something, it stops and writes you a clear handover. |
67
68
  | Ship it | `/bkit-ship` | Checks nothing planned was quietly dropped, waits for every test lane to pass, merges into `dev`, and updates the docs. |
68
69
  | Health check | >30 audits | One specialist checklist per area. Findings feed straight into `/bkit-plan`. |
@@ -86,18 +87,30 @@ One command per job. Each one runs a team of specialised agents, so you don't ha
86
87
  </picture>
87
88
  </p>
88
89
 
89
- Rules and prompts only go so far: an agent can be talked into calling something done. Reviewer agents fence in the design and the plan. From the first line of code, automated checks join them, and those can't be argued with.
90
+ Most AI development frameworks are prompts: they describe good work and trust the agent to deliver it. But an agent can be talked into calling something done, and a prompt can't stop it. bkit builds fences instead. Reviewer agents that didn't write the work fence in the design and the plan. From the first line of code, automated checks join them, and those can't be argued with.
90
91
 
91
92
  ## A CI pipeline built the way senior teams build them
92
93
 
93
- CI (continuous integration) is the robot that runs every check on every change, on GitHub's servers, before anything merges. It's the strongest fence there is, and most people who start with vibe coding have never set one up. bkit ships one ready to adopt, and its workflows are built around it:
94
+ The strongest fence is CI (continuous integration): the robot that runs every check on every change, on GitHub's servers, before anything merges. Most people who start with vibe coding have never set one up, and none of the AI development frameworks in our [comparison](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks) ships a full test pipeline for your project. bkit ships one ready to adopt, and its workflows are built around it. Agents and CI hand the work back and forth until every test passes:
95
+
96
+ 1. **`/bkit-build`** runs the quick checks on your machine, then opens a pull request, which starts CI.
97
+ 2. **CI** runs every lane and reports one result: a final check that's green only if every lane ran and passed.
98
+ 3. **Red?** `/bkit-debug` reads the logs of the lanes that failed, finds the root cause, fixes it and pushes, and CI runs again.
99
+ 4. **Green?** `/bkit-ship` checks nothing planned was quietly dropped, then merges into `dev`. Nothing less than green gets merged.
100
+ 5. **On autopilot**, the loop runs by itself: for issues labelled `bkit:auto`, CI's result starts ship or debug in a cloud session, with no laptop open.
101
+
102
+ <p align="center">
103
+ <picture>
104
+ <source media="(prefers-color-scheme: dark)" srcset=".github/assets/bkit-ci-dark.svg">
105
+ <img alt="bkit's CI pipeline, flowing left to right: plan the run (work out what to test); check and build (quick checks, unit tests, integration tests, web, iOS and Android builds, database migrations); set the stage (preview deploy, reset test data); test like a user (web, iOS and Android end-to-end tests, and a live-site check); tidy up. Every lane feeds one final check, the only one merging needs, which fails if any lane failed, was skipped or ran zero tests. /bkit-build starts CI by opening the pull request, /bkit-debug reads the logs of any lane that fails and fixes it, and /bkit-ship merges only when the final check is green." src=".github/assets/bkit-ci-light.svg" width="100%">
106
+ </picture>
107
+ </p>
94
108
 
95
109
  - **Ready on day one.** Two lanes run side by side: quick checks (type checking, formatting, a prose checker, a scanner for junk code AI tends to write, a workflow-file checker, and `bkit check`) and unit tests.
96
- - **A green tick means every test ran.** One final check joins all lanes and is the only one branch protection needs. It fails if any lane failed, was skipped or cancelled, or ran zero tests, so a half-finished run can't pass as tested.
110
+ - **A green tick means every test ran.** One final check joins all lanes and is the only one branch protection needs. It fails if any lane failed, was skipped or cancelled, or ran zero tests, so a half-finished run can't pass as tested. The gates audit flags any check that can never fail.
97
111
  - **Grows with your project.** >20 ready-to-enable building blocks: integration tests, end-to-end tests for web, iOS and Android, database migrations (locked once merged, with security-policy checks), coverage reports, waiting for preview deploys, live checks against the deployed site, smoke and health checks, and a planner that runs only what a change affects. `bkit check` reminds you of each one until you enable or delete it.
98
112
  - **Safe by default.** Every third-party action is pinned to an exact commit, the downloaded prose checker is checksum-verified, and pull-request titles never reach a script unescaped.
99
113
  - **Doesn't waste minutes.** A commit that already passed isn't re-tested, and a newer push cancels the older run, except on your production branch, where a deploy must never be cut off halfway.
100
- - **Wired into the workflows.** `/bkit-ship` merges only when the final check is green, `/bkit-debug` reads its failed logs, the cloud router starts from its result, and the gates audit flags any check that can never fail.
101
114
 
102
115
  ## Right context at the right step
103
116
 
@@ -120,7 +133,7 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
120
133
  ### The quality is real
121
134
 
122
135
  - **Everything is checked by an agent that didn't write it.** An AI checking its own work tends to approve it. bkit gives every design, plan and code change to separate reviewers, each with one job (one hunts bugs, another security holes). They never see each other's verdicts, and several review groups mix models on purpose, so one model's blind spot is less likely to get past all of them.
123
- - **"Done" is checked by code, not taken on trust.** Every step's output is verified before the next step starts, a task is ticked only when its result really exists, and a silent TODO or skipped test blocks the merge.
136
+ - **"Done" is checked by code, not taken on trust.** Every step's output is verified before the next step starts, a task is ticked only when its result really exists, each task's tests must be seen failing before its code is written, and a silent TODO or skipped test blocks the merge.
124
137
  - **Broken builds fix themselves, and stay fixed.** `/bkit-debug` finds the root cause before it changes anything, fixes it, re-runs the tests and records the lesson. Bugs that only show up at runtime get a dedicated mode that adds logging, fixes on evidence and removes the logging again.
125
138
  - **It knows when to stop.** If a failure can't be fixed, bkit writes a clear handover and stops, instead of guessing over and over.
126
139
 
@@ -148,19 +161,23 @@ Most AI tools forget everything when the chat ends. bkit keeps what it knows in
148
161
 
149
162
  ## Templates ready to adopt
150
163
 
151
- bkit installs only what its workflows run. Everything else, the things you or another tool run, ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. Copy in what you want and own it; bkit never writes over your copy. The install prompt asks your AI to adopt what fits. Catalogue, install steps and known traps: [`.bkit/templates.md`](.bkit/templates.md).
164
+ bkit installs only what its workflows run. Everything else, the things you or another tool run, ships as a template: install puts the latest set in your `.bkit/templates/`, and every upgrade lists which ones changed. Copy in what you want and own it; bkit never writes over your copy. The install prompt asks your AI to adopt what fits, and each workflow ends with a tip on the next one worth adding.
165
+
166
+ The ones that matter most, in the order to adopt them:
152
167
 
153
168
  <!-- prettier-ignore -->
154
- | Template | What it gives you |
169
+ | Template | What it's for |
155
170
  | --- | --- |
156
- | **CI pipeline** | Two lanes ready to go and >20 building blocks for the rest ([above](#a-ci-pipeline-built-the-way-senior-teams-build-them)). One final check is the only one branch protection needs. |
157
- | **Quality checks** | Type checking, formatting, a prose checker, a scanner for junk code AI tends to write, and a workflow-file checker, wired into git hooks and CI. Your `bkit:gate:*` scripts in `package.json` define what "the checks" are, and the gates audit flags any check that can never fail. |
158
- | **Context connectors** | >10 ready-made connectors that let `/bkit-debug` read CI, error trackers, hosting, databases, payments, email, queues and the web. |
171
+ | **CI pipeline** | Runs every check on GitHub on every change, and `/bkit-ship` waits for it before merging. Without it, "shipped" only means merged, not checked. Two lanes ready to go and >20 building blocks for the rest ([above](#a-ci-pipeline-built-the-way-senior-teams-build-them)). |
172
+ | **Quality checks** | Catches problems on your own machine in seconds, before they reach GitHub: type checking, formatting, a prose checker and a scanner for junk code AI tends to write, wired into git hooks and CI. Your `bkit:gate:*` scripts in `package.json` define what "the checks" are. |
173
+ | **Serena** | Lets agents look up code the way your editor does ("where is this defined, and what uses it?") instead of searching for words and reading whole files. Fewer accidental changes, and lower running costs because agents read less. Read-only. |
174
+ | **Context connectors** | Let `/bkit-debug` read the real errors instead of guessing from the code: >10 ready-made connectors for CI, error trackers, hosting, databases, payments, email, queues and the web. |
159
175
  | **Cloud agents** | When CI finishes, a cloud agent picks up: ship on green, debug on red. No laptop needed. |
160
- | **Dependency updates** | Ready-made Renovate or Dependabot setups: grouped minor updates, pinned GitHub Actions, and security fixes that skip the weekly queue. |
161
- | **Secrets sync** | One local file holds every key. One command pushes them to Vercel, GitHub Actions, Google Cloud, Supabase and Expo; another proves every copy matches without printing a value. |
162
- | **Serena** | Lets agents look up code the way your editor does ("where is this used?") instead of guessing from text search. Read-only. |
163
- | **graphify** | Draws a map of how your codebase fits together (`docs/capabilities.md`), so agents check what already exists before building it again. |
176
+ | **Secrets sync** | Keeps every password and key the same everywhere: one local file, one command to push it to Vercel, GitHub Actions, Google Cloud, Supabase and Expo, another to prove every copy matches without printing a value. Prevents "works for me, broken in production". |
177
+ | **graphify** | Keeps a map of how your code fits together (`docs/capabilities.md`), so agents check what already exists before building it again. |
178
+ | **Dependency updates** | Small, grouped update pull requests from Renovate or Dependabot instead of one big risky upgrade later. GitHub Actions stay pinned, and security fixes skip the queue. |
179
+
180
+ All templates, what each is for, and how to install them: [`.bkit/templates.md`](.bkit/templates.md).
164
181
 
165
182
  ## Quick start
166
183
 
@@ -193,7 +210,7 @@ No, but you do need to read a design and a plan and decide whether they're right
193
210
  bkit is heavier than a single prompt. For a one-off script or a quick experiment, just ask your AI. bkit pays off on a project you'll keep changing and want to trust.
194
211
 
195
212
  **What does it cost?**
196
- bkit is free for personal use, non-profits and small businesses (fewer than 100 people and under US$1M revenue); larger companies need a commercial licence ([License](#license)). It runs on AI subscriptions you already have (Claude, Cursor, ChatGPT for Codex, Google Antigravity), on Antigravity's free tier, or with your own key on pay-as-you-go providers through opencode (OpenRouter, Ollama or the opencode gateways). Several agents reviewing in parallel uses more of your quota than a single chat; that's the price of the second opinions.
213
+ bkit is free and open source under the MIT licence, for anyone, commercial use included ([License](#license)). It runs on AI subscriptions you already have (Claude, Cursor, ChatGPT for Codex, Google Antigravity), on Antigravity's free tier, or with your own key on pay-as-you-go providers through opencode (OpenRouter, Ollama or the opencode gateways). Several agents reviewing in parallel uses more of your quota than a single chat; that's the price of the second opinions.
197
214
 
198
215
  **Can it break my live site?**
199
216
  Not without your sign-off. Work happens in a separate copy of the repo, goes through a pull request, must pass every test, and merges into `dev`, never `main`.
@@ -201,6 +218,15 @@ Not without your sign-off. Work happens in a separate copy of the repo, goes thr
201
218
  **Which issue tracker?**
202
219
  GitHub Issues or Linear.
203
220
 
221
+ **Is this the bkit Vibecoding Kit?**
222
+ No. [bkit Vibecoding Kit](https://github.com/popup-studio-ai/bkit-claude-code) is a separate project that happens to share the name. This bkit is `@cbartens/bkit` on npm and lives at [github.com/cbartens/bkit](https://github.com/cbartens/bkit).
223
+
224
+ **How does it compare with other tools?**
225
+ Feature by feature against the main AI development frameworks, from spec toolkits to autonomous agents: [`.bkit/comparison.md`](.bkit/comparison.md#part-3--compared-with-other-ai-development-frameworks).
226
+
227
+ **Why doesn't bkit ship a compression proxy like caveman or Headroom?**
228
+ We measured both on 456 real Claude Code transcripts. They saved about 1–3% of token cost. Both protect Claude's prompt cache, so they only shrink tool output as it arrives, and that output was 27% of the cost. Headroom's text model also rewrote code along the way. bkit cuts reading instead, which loses nothing: agents find the definition first and read only those lines, and a hook flags re-reads of files that haven't changed. Method, results and scripts to measure your own sessions: [the comparison](tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md).
229
+
204
230
  <details>
205
231
  <summary><strong>For engineers: what's under the hood</strong></summary>
206
232
 
@@ -226,20 +252,27 @@ GitHub Issues or Linear.
226
252
  | [`.bkit/providers.md`](.bkit/providers.md) | Tool and provider differences, model pins |
227
253
  | [`.bkit/cloud.md`](.bkit/cloud.md) | Cloud agents: Claude Code on the web, Cursor, opencode |
228
254
  | [`.bkit/templates.md`](.bkit/templates.md) | Templates ready to adopt |
229
- | [`.bkit/comparison.md`](.bkit/comparison.md) | Full pipeline reference and agentic-patterns comparison |
255
+ | [`.bkit/comparison.md`](.bkit/comparison.md) | Full pipeline reference, agentic-patterns mapping, comparison with other AI development frameworks |
230
256
  | [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release |
231
257
 
232
- ## License
258
+ ## Credits
233
259
 
234
- bkit is source-available, not open source: anyone can read all of it, and it's free under either of two licences, whichever fits you.
260
+ bkit's process was worked out over months of building real products with it. These projects sharpened specific ideas along the way:
235
261
 
236
- - **[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0):** personal and hobby use, and charities, schools, research bodies and government, whatever their size.
237
- - **[PolyForm Small Business 1.0.0](https://polyformproject.org/licenses/small-business/1.0.0):** any use, commercial included, by a person or company with fewer than 100 people and under US$1M revenue.
262
+ <!-- prettier-ignore -->
263
+ | Project | Idea bkit took |
264
+ | --- | --- |
265
+ | [everything-claude-code](https://github.com/affaan-m/ECC) (affaan-m) | GateGuard, the hook that makes an agent investigate before it edits, name included; the warning when an agent edits lint or type-check settings; confidence and scope on recorded lessons; the untrusted-input notice on agents that read outside content. |
266
+ | [gstack](https://github.com/garrytan/gstack) (Garry Tan) | Writing the setup once and generating every AI tool's copy from it, with a check that the copies match; the completeness and search-before-building principles in the shared rules; resuming a run from saved state. |
267
+ | _Agentic Design Patterns_ (Antonio Gulli) | A "done when" line on every plan task, and testing hypotheses before fixing in debug. The book is also the yardstick in the [patterns comparison](.bkit/comparison.md#part-2--comparison-to-agentic-design-patterns). |
268
+ | [skills](https://github.com/mattpocock/skills) (Matt Pocock) | The interview that opens `/bkit-design`, adapted from `grill-me`: open questions are settled with you before any design work starts. |
238
269
 
239
- If neither fits, email bkit@bartens.biz for a commercial licence.
270
+ **Built on.** The templates set up these tools; thanks to their maintainers: [Serena](https://github.com/oraios/serena), [graphify](https://github.com/Graphify-Labs/graphify), [slop-scan](https://github.com/modem-dev/slop-scan), [Vale](https://github.com/vale-cli/vale) with [write-good](https://github.com/vale-cli/write-good), [Renovate](https://github.com/renovatebot/renovate), [Dependabot](https://docs.github.com/en/code-security/dependabot), [Husky](https://github.com/typicode/husky), [lint-staged](https://github.com/lint-staged/lint-staged), [Prettier](https://github.com/prettier/prettier), [actionlint](https://github.com/rhysd/actionlint) and [direnv](https://github.com/direnv/direnv).
271
+
272
+ ## License
240
273
 
241
- **The code bkit's agents write for you is yours.** The licences cover bkit itself, not what its agents produce in your repo.
274
+ bkit is [MIT](LICENSE.md): use it, change it and share it for any purpose, commercial included, as long as the copyright and licence notice stay with it.
242
275
 
243
- **Small pieces are MIT-0.** Everything in [`.bkit/shared/`](.bkit/shared/) and [`.bkit/templates/`](.bkit/templates/) is [MIT-0](https://opensource.org/license/mit-0): use it however you like, and a template you copy into your repo is yours. Every file bkit writes carries the licence and its URL in its marker, and the full PolyForm texts travel in the repo at [`.bkit/LICENSE.md`](.bkit/LICENSE.md) after install.
276
+ **The code bkit's agents write for you is yours.** The licence covers bkit itself, not what its agents produce in your repo.
244
277
 
245
- Full terms: [`LICENSE.md`](LICENSE.md).
278
+ The full text travels in your repo at [`.bkit/LICENSE.md`](.bkit/LICENSE.md) after install.
@@ -41,6 +41,34 @@ export function hasGithubMcpServer(cwd) {
41
41
  }
42
42
  return false;
43
43
  }
44
+ /**
45
+ * BKIT_GH_TOKEN unset or empty in the shell while a `github` MCP server is configured.
46
+ * Never in CI. The GitHub MCP server authenticates with `Authorization: Bearer
47
+ * ${BKIT_GH_TOKEN}` in .mcp.json, which powers the entire tracker + PR + Projects MCP
48
+ * surface.
49
+ */
50
+ export function detectGhMcpToken(cwd) {
51
+ if (!hasGithubMcpServer(cwd) || process.env.CI)
52
+ return null;
53
+ const status = detectShellGhMcpToken();
54
+ if (status === "missing") {
55
+ return {
56
+ id: "gh-mcp-token-unset-shell",
57
+ severity: "advisory",
58
+ detect: "BKIT_GH_TOKEN is not set in the shell environment (undefined). The GitHub MCP server authenticates with `Authorization: Bearer ${BKIT_GH_TOKEN}` — without it, every tracker, PR, and board MCP call fails to connect.",
59
+ action: "Set BKIT_GH_TOKEN in .bkit/.env (canonical local-secrets file, gitignored), then `direnv allow` and restart your editor so MCP servers pick it up:\n\n cp .bkit/.env.example .bkit/.env # if not already done\n # edit .bkit/.env — set BKIT_GH_TOKEN=<PAT>\n direnv allow\n\nUse a fine-grained PAT when every target repo sits under one owner (Contents, Pull requests, Issues, and Actions read & write, plus organization-scoped Projects read & write if you use board sync); use a classic PAT when one token must span owners (scopes repo / workflow / read:org / project / security_events). Generate at: https://github.com/settings/personal-access-tokens (fine-grained) or https://github.com/settings/tokens (classic). In cloud sessions (Claude Code web / Cursor Background Agents) set BKIT_GH_TOKEN in the dashboard env vars instead — repo files are not read for secrets there.",
60
+ };
61
+ }
62
+ if (status === "empty") {
63
+ return {
64
+ id: "gh-mcp-token-empty-shell",
65
+ severity: "advisory",
66
+ detect: 'BKIT_GH_TOKEN is set to an empty string (BKIT_GH_TOKEN=""). The GitHub MCP server sends an empty bearer token and fails to authenticate — distinct from unset, same effect.',
67
+ action: "Set a non-empty BKIT_GH_TOKEN in .bkit/.env (fine-grained PAT for one owner, or classic across owners; Contents / Pull requests / Issues / Actions read & write), then `direnv allow` and restart your editor so MCP servers reload.",
68
+ };
69
+ }
70
+ return null;
71
+ }
44
72
  /**
45
73
  * Detect whether a named secret is set on the consumer's GitHub repo.
46
74
  * Returns "present" | "missing" | "unknown".
@@ -75,7 +75,7 @@ export function readConsumerIssueTracker(cwd) {
75
75
  /**
76
76
  * Emit a tracker-specific setup advisory.
77
77
  *
78
- * - `github` → GitHub tracker: MCP auth is browser OAuth — no PAT needed for tracker calls.
78
+ * - `github` → GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN`; `gh` uses `gh auth login`.
79
79
  * - `linear` → existing Linear setup message (BKIT_LINEAR_API_KEY + LINEAR_ISSUE_ID).
80
80
  * - `none` → prompt to run `bkit install --tracker=github` or `--tracker=linear`.
81
81
  *
@@ -92,7 +92,7 @@ export function buildTrackerSetupAdvisory(cwd) {
92
92
  id: "tracker-setup-github",
93
93
  severity: "advisory",
94
94
  detect: "bkit tracker is configured as `github`. GitHub Issues + Projects v2 is the active tracker.",
95
- action: "GitHub tracker: MCP auth is browser OAuth — run `gh auth login` once for CLI surface. No PAT needed for tracker calls. The GitHub MCP server uses OAuth automatically on first tool call. Ensure the `github` MCP server is configured in `.mcp.json` and `.cursor/mcp.json`.",
95
+ action: "GitHub tracker: the GitHub MCP server authenticates with `BKIT_GH_TOKEN` (fine-grained PAT for one owner, classic PAT across owners) — set it in `.bkit/.env`, then `direnv allow`. Unset → every tracker and PR MCP call fails. The `gh` CLI signs in separately: run `gh auth login` once. Ensure the `github` MCP server is configured in `.mcp.json` and `.cursor/mcp.json`.",
96
96
  };
97
97
  }
98
98
  if (tracker === "linear") {
@@ -112,7 +112,7 @@ export function buildTrackerSetupAdvisory(cwd) {
112
112
  id: "tracker-setup-none",
113
113
  severity: "advisory",
114
114
  detect: "bkit tracker is not configured (`bkit.issueTracker` absent). Workflows run but every tracker call is a no-op.",
115
- action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` to enable tracker integration. GitHub tracker uses browser OAuth — no PAT required. Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
115
+ action: 'Optional post-install decision. Run `bkit install --tracker=github` (recommended) or `bkit install --tracker=linear` to enable tracker integration. GitHub tracker requires `BKIT_GH_TOKEN` in `.bkit/.env` (fine-grained PAT for one owner, classic PAT across owners). Linear tracker requires `BKIT_LINEAR_API_KEY` in `.bkit/.env`. To opt out and silence this advisory, set `bkit.issueTracker` to `"none"` in package.json.',
116
116
  };
117
117
  }
118
118
  /** True when package.json has an explicit `bkit.issueTracker` field (any value). */
@@ -379,7 +379,7 @@ export function buildCloudSetupAdvisory(cwd) {
379
379
  id: "cloud-router",
380
380
  severity: "advisory",
381
381
  detect: "Cloud agents: post-CI auto-routing is active (`.github/workflows/bkit-cloud.yml` present). The Claude GitHub App is required — run `/install-github-app` (Claude Code CLI) once if not already done.",
382
- action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.`,
382
+ action: `The workflow requires: the \`ANTHROPIC_API_KEY\` repo secret, the Claude GitHub App (\`/install-github-app\`), and GitHub Actions write permissions (org AND repo). See the \`bkit-auto-setup\` advisory (emitted by \`bkit install --auto=claude\`) and bkit's \`cloud.md\` § Post-CI auto-routing for the full checklist.\n\nbkit's agents comment as you, so every workflow those comments trigger notifies you, even ones that skip. To see only failures: GitHub → Settings → Notifications → System → Actions → "Only notify for failed workflows".`,
383
383
  };
384
384
  }
385
385
  // No router present — distinguish opt-out from undecided.