@cbartens/bkit 5.5.1 → 6.1.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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -12,8 +12,8 @@
12
12
  // - ADVISORY BY DEFAULT: emits `additionalContext` only, never blocks. Deny mode
13
13
  // is wired behind BKIT_GATEGUARD=deny (see MODES).
14
14
  // - FAIL OPEN: a single top-level catch swallows every error (the process exits
15
- // 0 with whatever was already emitted). Normal control paths use existence
16
- // guards, never try/catch; that catch is the only error sink.
15
+ // 0 with whatever was already emitted). The engine catches only its own state
16
+ // write: the checklist is still returned, as advisory.
17
17
  // - SUBAGENTS INCLUDED: a subagent edit is an edit. Dedup is per (session, agent,
18
18
  // file): a subagent shares its parent's session_id and carries its own agent_id,
19
19
  // so it gets its own checklist.
@@ -57,9 +57,9 @@ function bkitGuardrails(payload) {
57
57
  if (usesFetch(c) && !curlWgetHostAllowed(c, hookDirs(payload))) {
58
58
  notes.push(
59
59
  "bkit guardrails: outbound fetch to a host that is not on this repo's network allowlist " +
60
- "(.agents/context.md § allowed-domains, plus bkit's shipped tooling hosts). Not blocked — " +
61
- "confirm the destination is intended before relying on the result, and add the host to " +
62
- "allowed-domains if it is a standing dependency.",
60
+ "(.agents/context.md § allowed-domains, plus bkit's shipped tooling hosts). The command is allowed.\n" +
61
+ "Confirm the destination is intended before you rely on the result.\n" +
62
+ "If the host is a standing dependency, add it to allowed-domains.",
63
63
  );
64
64
  }
65
65
  const edits = shellEditTargets(c);
@@ -14,9 +14,10 @@
14
14
  # HARD STOP instruction) AND `stderr` (visible to the user). Exit code is
15
15
  # informational only.
16
16
  #
17
- # bkit generates the managed block at install: the Linear guard is shared with the
18
- # Cursor hook (bkit's `hooks/preflight-linear.sh`); the trigger, the brew check
19
- # and the output shape below are Claude's own.
17
+ # bkit generates the managed block at install: the Linear guard and the rules-read
18
+ # advisory are shared with the Cursor hook (bkit's `hooks/preflight-linear.sh` and
19
+ # `hooks/preflight-rules.sh`); the trigger, the brew check and the output shape below
20
+ # are Claude's own.
20
21
 
21
22
  # <!-- bkit:start -->
22
23
 
@@ -28,21 +29,51 @@ set -euo pipefail
28
29
  # Claude SessionStart payload: { session_id, transcript_path, cwd, permission_mode } — unused here.
29
30
  INPUT=$(cat)
30
31
 
31
- # emit_context — Claude SessionStart expects { hookSpecificOutput: { hookEventName, additionalContext } }.
32
+ # emit_context — Claude SessionStart expects ONE JSON document
33
+ # { hookSpecificOutput: { hookEventName, additionalContext } } on stdout. Each call
34
+ # accumulates its string; the EXIT trap writes the document once, so the advisory and
35
+ # the Linear guard result ride one document (two documents are unparseable).
32
36
  # (Cursor variant: emits { additional_context: ... } directly.)
37
+ BKIT_CONTEXT=""
33
38
  emit_context() {
34
- python3 - "$1" <<'PY'
35
- import json, sys
36
- print(json.dumps({
37
- "hookSpecificOutput": {
38
- "hookEventName": "SessionStart",
39
- "additionalContext": sys.argv[1],
40
- },
41
- }))
42
- PY
39
+ [[ -z "$BKIT_CONTEXT" ]] || BKIT_CONTEXT+=$'\n\n'
40
+ BKIT_CONTEXT+="$1"
43
41
  }
44
42
 
45
- # IDE session detection — skip silently when this isn't a background/cloud run.
43
+ # JSON-escape one string, so a context carrying a quote or a backslash cannot break the
44
+ # document. No python3 on this path: a python3-less IDE session must still get the
45
+ # advisory (Claude cannot block, so a lost advisory would be silent).
46
+ bkit_json_escape() {
47
+ local s=$1 i oct ch esc
48
+ s=${s//\\/\\\\}
49
+ s=${s//\"/\\\"}
50
+ s=${s//$'\n'/\\n}
51
+ s=${s//$'\r'/\\r}
52
+ s=${s//$'\t'/\\t}
53
+ # The rest of the C0 range (U+0000–U+001F) — bash cannot hold NUL, so 1–31 minus the
54
+ # three above. A raw control byte makes the whole document unparseable and the host
55
+ # discards it, taking the advisory and the Linear guard result with it.
56
+ for (( i = 1; i < 32; i++ )); do
57
+ case $i in 9 | 10 | 13) continue ;; esac
58
+ printf -v oct '%03o' "$i"
59
+ printf -v ch "\\$oct"
60
+ printf -v esc '\\u%04x' "$i"
61
+ s=${s//$ch/$esc}
62
+ done
63
+ printf '%s' "$s"
64
+ }
65
+
66
+ bkit_write_document() {
67
+ [[ -n "$BKIT_CONTEXT" ]] || return 0
68
+ printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' \
69
+ "$(bkit_json_escape "$BKIT_CONTEXT")"
70
+ }
71
+
72
+ trap bkit_write_document EXIT
73
+
74
+ # {{BKIT_PART preflight-rules.sh}}
75
+
76
+ # IDE session detection — the advisory above already fired; nothing else runs here.
46
77
  # Claude has no native is-background flag, so we use empty LINEAR_ISSUE_ID as the proxy.
47
78
  # (Cursor variant: parses `is_background_agent` from stdin JSON.)
48
79
  if [[ -z "${LINEAR_ISSUE_ID:-}" ]]; then
@@ -69,15 +69,15 @@ function decideShell(cmd, dirs) {
69
69
  case "ask":
70
70
  // Advisory on this host (Codex cannot prompt).
71
71
  return ask(
72
- `bkit Codex guardrails: this is a destructive or privileged command (${v.what}) and Codex cannot prompt for confirmation. It is on the PROHIBITED list in every bkit workflow. Do not run it unless the user asked for this exact command. Note that git clean and git checkout -- . destroy untracked files and uncommitted work, which no reflog can recover. Command: ${c}`,
72
+ `bkit Codex guardrails: this destructive or privileged command (${v.what}) ran without confirmation, because Codex cannot prompt for one. It is on the PROHIBITED list in every bkit workflow.\nTell the user that you ran it.\nIf the user did not ask for this exact command, NEVER run it again.\n\`git clean\` and \`git checkout -- .\` destroy untracked files and uncommitted work, which no reflog can recover.\nCommand: ${c}`,
73
73
  );
74
74
  case "secret":
75
75
  return ask(
76
- `bkit Codex guardrails: this command reads ${v.path}, an env/secrets or private-key file, and Codex cannot prompt for confirmation. Do not print secret values; prefer direnv / documented non-secret examples. Command: ${c}`,
76
+ `bkit Codex guardrails: this command read ${v.path}, an env, secrets or private-key file, without confirmation, because Codex cannot prompt for one.\nNEVER print secret values.\nPrefer direnv or documented non-secret examples.\nCommand: ${c}`,
77
77
  );
78
78
  case "fetch":
79
79
  return ask(
80
- `bkit Codex guardrails: outbound fetch to a host that is not on the network allowlist. Confirm the destination is intended before relying on the result. Command: ${c}`,
80
+ `bkit Codex guardrails: outbound fetch to a host that is not on the network allowlist.\nConfirm the destination is intended before you rely on the result.\nCommand: ${c}`,
81
81
  );
82
82
  default:
83
83
  // Shell-as-edit-channel: advisory on every host, never a block.
@@ -0,0 +1,57 @@
1
+ #!/usr/bin/env node
2
+ // bkit-rules.cjs — bkit rules-read advisory PreToolUse hook (Codex CLI).
3
+ //
4
+ // Codex's hook contract is the same family as Claude Code's — same stdin envelope
5
+ // (`tool_name`, `tool_input`, `session_id`, `cwd`), same stdout shape
6
+ // (`hookSpecificOutput` with `additionalContext`). bkit generates the advisory text and
7
+ // its once-per-session helper into it at install (bkit's
8
+ // `core/hooks/session-rules-advisory.js`), the same source as the opencode and
9
+ // Antigravity hooks.
10
+ //
11
+ // Codex has no session-start event, so the advisory rides the FIRST tool call instead:
12
+ // the hook writes it as `additionalContext` once per session, and every later call writes
13
+ // nothing. `additionalContext` is advisory only — no call is ever blocked.
14
+ //
15
+ // REGISTRATION: `.codex/hooks.json`, two single-value `PreToolUse` groups — `apply_patch`
16
+ // and `Bash`, the shape every shipped Codex matcher uses (alternation is not verified on
17
+ // that host). Codex loads project-local hooks only once the project `.codex/` layer is
18
+ // TRUSTED — until then this does not run. See .bkit/providers.md § GateGuard.
19
+ //
20
+ // CONTRACT — do not regress:
21
+ // - ADVISORY ONLY: emits `additionalContext`, never a permission decision.
22
+ // - FAIL OPEN: one top-level catch swallows every error and exits 0.
23
+ // - ONCE PER SESSION: dedup is by `session_id`, state in the OS temp dir, GC'd after
24
+ // 24h. Codex reports the parent's session_id inside a subagent and no agent id, so a
25
+ // subagent can miss an advisory its parent already consumed — the same limit
26
+ // GateGuard records. A payload carrying no session id falls back to one shared bucket.
27
+ //
28
+ // OWNERSHIP: everything between the markers is bkit-managed and overwritten on every
29
+ // `bkit install` / `bkit upgrade`. Add your own logic in the driver below the block.
30
+
31
+ "use strict";
32
+
33
+ // bkit:start
34
+
35
+ // {{BKIT_MANAGED_MARKER}}
36
+
37
+ const fs = require("node:fs");
38
+ const os = require("node:os");
39
+ const path = require("node:path");
40
+
41
+ // {{BKIT_PART session-rules-advisory.js}}
42
+
43
+ // bkit:end
44
+
45
+ function emit(payload) {
46
+ process.stdout.write(JSON.stringify({ hookSpecificOutput: payload }));
47
+ }
48
+
49
+ try {
50
+ const raw = fs.readFileSync(0, "utf-8");
51
+ if (raw.trim()) {
52
+ const advisory = rulesReadAdviceOnce(JSON.parse(raw).session_id);
53
+ if (advisory) emit({ hookEventName: "PreToolUse", additionalContext: advisory });
54
+ }
55
+ } catch {
56
+ process.exitCode = 0; // fail open — never block, never error out
57
+ }
@@ -69,17 +69,17 @@ function decideShell(cmd, dirs) {
69
69
  return deny(`Blocked: ${v.what} is denied by bkit Cursor guardrails.`, v.fix);
70
70
  case "ask":
71
71
  return ask(
72
- `bkit Cursor guardrails: confirm this destructive / privileged shell command (${v.what}).`,
72
+ `bkit Cursor guardrails: confirm this destructive or privileged shell command (${v.what}).`,
73
73
  `Command requires confirmation: ${c}`,
74
74
  );
75
75
  case "secret":
76
76
  return ask(
77
- "bkit Cursor guardrails: confirm a shell read of an env/secrets or private-key file.",
78
- `Reading ${v.path} through the shell may expose secrets. Prefer direnv / documented non-secret examples. Command: ${c}`,
77
+ "bkit Cursor guardrails: confirm a shell read of an env, secrets or private-key file.",
78
+ `Reading ${v.path} through the shell may expose secrets.\nPrefer direnv or documented non-secret examples.\nCommand: ${c}`,
79
79
  );
80
80
  case "fetch":
81
81
  return ask(
82
- "bkit Cursor guardrails: confirm outbound curl/wget (host not on network allowlist).",
82
+ "bkit Cursor guardrails: confirm an outbound curl or wget to a host that is not on the network allowlist.",
83
83
  `Command requires confirmation: ${c}`,
84
84
  );
85
85
  default:
@@ -96,12 +96,12 @@ function decideRead(filePath) {
96
96
  if (v.tier === "deny") {
97
97
  return deny(
98
98
  "Blocked: reading private-key material is denied by bkit Cursor guardrails.",
99
- `Do not read ${v.path}. Ask the user to supply needed material out-of-band.`,
99
+ `NEVER read ${v.path}.\nAsk the user to supply what you need without putting the key in this conversation.`,
100
100
  );
101
101
  }
102
102
  return ask(
103
- "bkit Cursor guardrails: confirm reading an env/secrets file.",
104
- `Reading ${v.path} may expose secrets. Prefer direnv / documented non-secret examples.`,
103
+ "bkit Cursor guardrails: confirm reading an env or secrets file.",
104
+ `Reading ${v.path} may expose secrets.\nPrefer direnv or documented non-secret examples.`,
105
105
  );
106
106
  }
107
107
 
@@ -12,9 +12,10 @@
12
12
  # blocks the session before the agent starts. Failures are also surfaced via
13
13
  # `additional_context` so the user sees the reason.
14
14
  #
15
- # bkit generates the managed block at install: the Linear guard is shared with the
16
- # Claude hook (bkit's `hooks/preflight-linear.sh`); the trigger, the runtime
17
- # marker and the output shape below are Cursor's own.
15
+ # bkit generates the managed block at install: the Linear guard and the rules-read
16
+ # advisory are shared with the Claude hook (bkit's `hooks/preflight-linear.sh` and
17
+ # `hooks/preflight-rules.sh`); the trigger, the runtime marker and the output shape
18
+ # below are Cursor's own.
18
19
 
19
20
  # <!-- bkit:start -->
20
21
 
@@ -26,6 +27,49 @@ set -euo pipefail
26
27
  # Cursor sessionStart payload: { session_id, is_background_agent, composer_mode } — used for IDE detection below.
27
28
  INPUT=$(cat)
28
29
 
30
+ # emit_context — Cursor sessionStart expects ONE JSON document { additional_context: ... }
31
+ # on stdout. Each call accumulates its string; the EXIT trap writes the document once, so
32
+ # the advisory and the Linear guard result ride one document. Defined above the bail so an
33
+ # IDE session gets the advisory too, and built with no python3: failClosed:true blocks the
34
+ # session on a non-zero exit, and an IDE session may not have python3 at all.
35
+ # (Claude variant: wraps in { hookSpecificOutput: { hookEventName, additionalContext } }.)
36
+ BKIT_CONTEXT=""
37
+ emit_context() {
38
+ [[ -z "$BKIT_CONTEXT" ]] || BKIT_CONTEXT+=$'\n\n'
39
+ BKIT_CONTEXT+="$1"
40
+ }
41
+
42
+ # JSON-escape one string, so a context carrying a quote or a backslash cannot break the
43
+ # document.
44
+ bkit_json_escape() {
45
+ local s=$1 i oct ch esc
46
+ s=${s//\\/\\\\}
47
+ s=${s//\"/\\\"}
48
+ s=${s//$'\n'/\\n}
49
+ s=${s//$'\r'/\\r}
50
+ s=${s//$'\t'/\\t}
51
+ # The rest of the C0 range (U+0000–U+001F) — bash cannot hold NUL, so 1–31 minus the
52
+ # three above. A raw control byte makes the whole document unparseable and the host
53
+ # discards it, taking the advisory and the Linear guard result with it.
54
+ for (( i = 1; i < 32; i++ )); do
55
+ case $i in 9 | 10 | 13) continue ;; esac
56
+ printf -v oct '%03o' "$i"
57
+ printf -v ch "\\$oct"
58
+ printf -v esc '\\u%04x' "$i"
59
+ s=${s//$ch/$esc}
60
+ done
61
+ printf '%s' "$s"
62
+ }
63
+
64
+ bkit_write_document() {
65
+ [[ -n "$BKIT_CONTEXT" ]] || return 0
66
+ printf '{"additional_context":"%s"}\n' "$(bkit_json_escape "$BKIT_CONTEXT")"
67
+ }
68
+
69
+ trap bkit_write_document EXIT
70
+
71
+ # {{BKIT_PART preflight-rules.sh}}
72
+
29
73
  # IDE session bailout — grep only, no python3 on the skip path (failClosed:true in
30
74
  # .cursor/hooks.json blocks the session if this exits non-zero). Background-agent
31
75
  # sessions run inside the bkit Dockerfile, where python3 is present for the code below.
@@ -44,15 +88,6 @@ if BKIT_REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) && [[ -d "$BKIT_R
44
88
  || echo "[bkit-runtime] could not write .bkit/.runtime-cursor — runtime will resolve as LOCAL" >&2
45
89
  fi
46
90
 
47
- # emit_context — Cursor sessionStart expects { additional_context: ... } directly.
48
- # (Claude variant: wraps in { hookSpecificOutput: { hookEventName, additionalContext } }.)
49
- emit_context() {
50
- python3 - "$1" <<'PY'
51
- import json, sys
52
- print(json.dumps({"additional_context": sys.argv[1]}))
53
- PY
54
- }
55
-
56
91
  # Brew dep preflight — N/A on Cursor Cloud.
57
92
  # Cursor Cloud runs in a containerised env where required CLIs (gh, jq, vale, pnpm, bun) are
58
93
  # pre-installed via .cursor/Dockerfile, so the laptop-side brew check makes no sense here.
@@ -0,0 +1,89 @@
1
+ // bkit-rules.js — bkit rules-read advisory plugin for opencode.
2
+ //
3
+ // Fires on opencode's tool hooks. On the FIRST tool call of a session it appends the
4
+ // rules-read advisory to the tool result, so the model is told to read `.agents/rules.md`
5
+ // before any other action; every later call appends nothing.
6
+ //
7
+ // CONTRACT — do not regress:
8
+ // - ADVISORY ONLY: appends the advisory to the tool RESULT in the after-execute hook —
9
+ // never blocks. stderr is NOT a model channel on 2.0's detached server.
10
+ // - FAIL OPEN: a top-level try/catch swallows every error; the plugin never throws.
11
+ // - ONCE PER SESSION: dedup is by sessionID, state in the OS temp dir, GC'd after 24h.
12
+ // A subagent runs in its own session, so it gets its own advisory; a payload carrying
13
+ // no session id falls back to one shared bucket. The token is spent only once the call
14
+ // is known to carry the advisory, so a call whose result never arrived leaves it for
15
+ // the next call instead of losing the nudge for the whole session.
16
+ // - NO SESSION-START EVENT: opencode has none, so the advisory rides the first tool
17
+ // call's result instead.
18
+ //
19
+ // The advisory text and its once-per-session helper are generated at install from bkit's
20
+ // `core/hooks/session-rules-advisory.js`, the same source as the Codex and Antigravity
21
+ // hooks.
22
+ //
23
+ // OWNERSHIP: everything between the markers below is bkit-managed and is overwritten on
24
+ // every `bkit install` / `bkit upgrade`. It is a pure advisory only — no client calls, no
25
+ // stderr write, no throw — so it composes with your own checks in the exported plugin
26
+ // that follows the managed block.
27
+
28
+ // bkit:start
29
+
30
+ // {{BKIT_MANAGED_MARKER}}
31
+
32
+ import * as fs from "node:fs";
33
+ import * as os from "node:os";
34
+ import * as path from "node:path";
35
+
36
+ // {{BKIT_PART session-rules-advisory.js}}
37
+
38
+ // bkit:end
39
+
40
+ // ---------------------------------------------------------------------------
41
+ // Driver — the one export shape OpenCode 1.x and 2.0 both load (same as
42
+ // `bkit-gateguard.js`): 2.0 calls `setup(ctx)` and registers `execute.after`; 1.18.29+
43
+ // calls `server()` and uses `"tool.execute.after"`. Both call the shared
44
+ // rulesReadAdviceOnce() above, so once-per-session behaviour is identical across the two.
45
+ // The file deliberately imports NOTHING from `@opencode/plugin`: that package only exists
46
+ // on 2.0, and importing it would break the module load on 1.x.
47
+ // ---------------------------------------------------------------------------
48
+
49
+ /** OpenCode 1.x after hook: append the advisory to `output.output`, the result text. */
50
+ async function bkitRulesAfterV1(hookInput, output) {
51
+ try {
52
+ // Check the delivery shape BEFORE spending the session's one advisory: a call that
53
+ // cannot carry it must leave the token for the next call.
54
+ if (!output || typeof output !== "object") return;
55
+ const advisory = rulesReadAdviceOnce(hookInput?.sessionID);
56
+ if (!advisory) return;
57
+ const existing = typeof output.output === "string" ? output.output : "";
58
+ output.output = existing.length > 0 ? `${existing}\n\n${advisory}` : advisory;
59
+ } catch {
60
+ // fail-open: never let an advisory error reach the host
61
+ }
62
+ }
63
+
64
+ /** OpenCode 2.0 after hook: append the advisory to `event.result.content`. */
65
+ async function bkitRulesAfterV2(event) {
66
+ try {
67
+ // Check the delivery shape BEFORE spending the session's one advisory: a call that
68
+ // cannot carry it must leave the token for the next call.
69
+ if (!event || event.status !== "completed" || !event.result) return;
70
+ const advisory = rulesReadAdviceOnce(event?.sessionID);
71
+ if (!advisory) return;
72
+ const content = Array.isArray(event.result.content) ? event.result.content : [];
73
+ event.result.content = [...content, { type: "text", text: advisory }];
74
+ } catch {
75
+ // fail-open: never let an advisory error reach the host
76
+ }
77
+ }
78
+
79
+ const bkitRulesPlugin = {
80
+ id: "bkit-rules",
81
+ async setup(ctx) {
82
+ await ctx.tool.hook("execute.after", bkitRulesAfterV2);
83
+ },
84
+ async server() {
85
+ return { "tool.execute.after": bkitRulesAfterV1 };
86
+ },
87
+ };
88
+
89
+ export default bkitRulesPlugin;
@@ -4,85 +4,11 @@
4
4
 
5
5
  {{BKIT_MANAGED_MARKER}}
6
6
 
7
- - **Rules:** Read `.agents/rules.md` → follow all rules.
8
-
9
- > [!CAUTION]
10
- > This file is a **workflow router only**. It does not execute workflows.
11
-
12
- ---
13
-
14
- ## Route
15
-
16
- ### Step 1 — Extract from prompt XML (not MCP)
17
-
18
- **If** prompt contains `<LINEAR_ISSUE>` XML block (Linear integration):
19
-
20
- - `ISSUE_ID` ← `<id>` tag value (e.g. `LIN-123` or team-specific prefix)
21
- - `DESCRIPTION` ← `<description>` tag content
22
- - `LABELS` ← all `<label name="...">` values in `<labels>` block
23
- - `COMMENTS` ← all `<comment>` entries from `<comment_thread>` + `<other_comment_threads>`, sorted newest-first by `created` attribute
24
-
25
- **Else** scan entire session prompt for issue ID — try patterns in order, first match wins:
26
-
27
- 1. `#\d+` → GitHub issue number (e.g. `#123`); strip `#`, set `ISSUE_ID` = `123`
28
- 2. `[A-Z][A-Z0-9]*-\d+` → prefixed issue ID (e.g. Linear `LIN-123`, Jira `PROJ-123`, `ISSUE-123`)
29
- 3. bare `\d+` → numeric fallback (GitHub provider only; ambiguous — prefer `#\d+`)
30
-
31
- Set `LABELS`, `DESCRIPTION`, `COMMENTS` = empty.
32
-
33
- **If** no `ISSUE_ID` → **STOP** with `No issue ID provided.`
34
-
35
- ### Step 2 — Route from user message
36
-
37
- In the bottom-most `USER:` entry in `# Message history` scan for commands (case-insensitive: Ship, Debug, Build, Plan, Design) → first match → `COMMAND`. **If** matched → skip Steps 3–4.
38
-
39
- ### Step 3 — Route from XML labels
40
-
41
- Scan `LABELS` for commands (Ship, Debug, Build, Plan, Design) → first match → `COMMAND`. **If** matched → skip Step 4.
42
-
43
- ### Step 4 — MCP fallback (labels only)
44
-
45
- Only if Steps 2–3 yield no `COMMAND`: read current issue labels via the configured tracker MCP (GitHub: `mcp__github__issue_read({ method: "get_labels", ... })`; Linear: `mcp__linear__get_issue({ id: "{ISSUE_ID}" })`; Jira: `mcp__jira__getJiraIssue({ cloudId: "<package.json bkit.jira.site>", issueIdOrKey: "{ISSUE_ID}", view: "evidence" })` → `fields.labels`) → scan returned labels → first match → `COMMAND`. Update `LABELS`, `DESCRIPTION`.
46
-
47
- ### Step 5 — No match
48
-
49
- Emit: `Workflow not found for issue {ISSUE_ID}. Valid commands: Design / Plan / Build / Debug / Ship.` → **STOP**. (Do not post a tracker comment — the router does not know which tracker MCP to call at this point.)
50
-
51
- ### Step 6 — Execute command
52
-
53
- Read and execute the matched command file for the current IDE.
54
-
55
- **Cursor** (`.cursor/commands/`):
56
-
57
- <!-- prettier-ignore -->
58
- | Label | Command |
59
- | --- | --- |
60
- | `Ship` | `.cursor/commands/bkit-ship.md` |
61
- | `Debug` | `.cursor/commands/bkit-debug.md` |
62
- | `Build` | `.cursor/commands/bkit-build.md` |
63
- | `Plan` | `.cursor/commands/bkit-plan.md` |
64
- | `Design` | `.cursor/commands/bkit-design.md` |
65
-
66
- **Claude Code** (`.claude/commands/`):
67
-
68
- <!-- prettier-ignore -->
69
- | Label | Command |
70
- | --- | --- |
71
- | `Ship` | `.claude/commands/bkit-ship.md` |
72
- | `Debug` | `.claude/commands/bkit-debug.md` |
73
- | `Build` | `.claude/commands/bkit-build.md` |
74
- | `Plan` | `.claude/commands/bkit-plan.md` |
75
- | `Design` | `.claude/commands/bkit-design.md` |
76
-
77
- **Antigravity** (`.agents/plugins/bkit/skills/`):
78
-
79
- <!-- prettier-ignore -->
80
- | Label | Command |
81
- | --- | --- |
82
- | `Ship` | `.agents/plugins/bkit/skills/bkit-ship/SKILL.md` |
83
- | `Debug` | `.agents/plugins/bkit/skills/bkit-debug/SKILL.md` |
84
- | `Build` | `.agents/plugins/bkit/skills/bkit-build/SKILL.md` |
85
- | `Plan` | `.agents/plugins/bkit/skills/bkit-plan/SKILL.md` |
86
- | `Design` | `.agents/plugins/bkit/skills/bkit-design/SKILL.md` |
7
+ - **Rules file:** Read `.agents/rules.md` → follow all rules.
8
+ - **Workflows:** **If** the prompt contains `bkit-{command}` (`bkit-design`, `bkit-plan`, `bkit-build`, `bkit-debug`, `bkit-ship`, `bkit-auto`) → read `.bkit/router.md` → follow it. **Else** → no workflow routing; handle the request as asked.
9
+ - **Memory hygiene:** Agent memories (notes a host keeps across sessions) are pointers, never copies.
10
+ - For a fact in `docs/*.md` or `.agents/rules.md`, save only its path, its section and a one-line hook.
11
+ - Query the tracker or `docs/roadmap.md` for an issue's state.
12
+ - Never save a snapshot of an issue's state in memory.
87
13
 
88
14
  <!-- bkit:end -->