@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
@@ -1,6 +1,6 @@
1
1
  // --- Antigravity hook contract: identical in bkit's three Antigravity hooks (bkit renders
2
- // it from one source). Needs `fs`, `os` and `path` in scope; the host's own code above
3
- // declares them.
2
+ // it from one source). Needs `fs`, `os`, `path` and `crypto` in scope; the host's own code
3
+ // above declares them.
4
4
  //
5
5
  // Live-verified on the agy CLI: PreToolUse stdin is `{ conversationId, toolCall: { name,
6
6
  // args }, workspacePaths, stepIdx, ... }` — no tool_name / tool_input / session_id / cwd.
@@ -41,28 +41,43 @@ function agCallSignature(toolName, input) {
41
41
  }
42
42
 
43
43
  // One record per (hook, conversation): two hooks on the same call each let its retry through.
44
+ // Per user: on a temp dir users share (Linux `/tmp`) another user's copy cannot be written.
44
45
  function agRetryFile(hook, sessionId) {
45
46
  const safe =
46
47
  typeof sessionId === "string" ? sessionId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) : "";
47
- return path.join(os.tmpdir(), "bkit-antigravity-retry", `${hook}.${safe || "no-session"}.json`);
48
+ const user = typeof process.getuid === "function" ? `-${process.getuid()}` : "";
49
+ return path.join(
50
+ os.tmpdir(),
51
+ `bkit-antigravity-retry${user}`,
52
+ `${hook}.${safe || "no-session"}.json`,
53
+ );
48
54
  }
49
55
 
50
56
  /**
51
57
  * Delivers an advisory the only way Antigravity shows one to the model: deny the call
52
58
  * with the advisory as the reason, once. The identical call right after is the agent's
53
- * retry and is allowed.
59
+ * retry and is allowed. Fail-open: a retry-store error allows the call — each call is
60
+ * its own process, so a deny it cannot record would block every retry.
54
61
  */
55
62
  function adviseOnce(hook, sessionId, signature, advisory) {
56
63
  const file = agRetryFile(hook, sessionId);
57
- const last = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
58
- if (last === signature) {
59
- fs.rmSync(file, { force: true });
64
+ // One-way digest of the call signature: the retry store is world-readable and has no
65
+ // TTL, so no tool argument (a shell command line with an inline secret, a file path)
66
+ // may rest on disk in cleartext.
67
+ const digest = crypto.createHash("sha256").update(signature).digest("hex");
68
+ try {
69
+ const last = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
70
+ if (last === digest) {
71
+ fs.rmSync(file, { force: true });
72
+ return { decision: "allow" };
73
+ }
74
+ fs.mkdirSync(path.dirname(file), { recursive: true });
75
+ fs.writeFileSync(file, digest, "utf-8");
76
+ } catch {
60
77
  return { decision: "allow" };
61
78
  }
62
- fs.mkdirSync(path.dirname(file), { recursive: true });
63
- fs.writeFileSync(file, signature, "utf-8");
64
79
  return {
65
80
  decision: "deny",
66
- reason: `${advisory}\nBlocked once so you see this; repeat the same call to proceed.`,
81
+ reason: `${advisory}\nThis call was held once so you see this advisory. Repeat the same call to proceed.`,
67
82
  };
68
83
  }
@@ -59,28 +59,29 @@ function isGateConfig(filePath) {
59
59
  function investigationChecklist(filePath) {
60
60
  const base = path.basename(filePath);
61
61
  return (
62
- `[bkit GateGuard] First edit to \`${base}\` this session - confirm following, and investigate anything you cannot answer BEFORE editing:\n` +
63
- `- Confirm you read this file and exact symbols / lines you are about to change.\n` +
64
- `- Confirm precise field names, types, and signatures being changed.\n` +
65
- `- Confirm callers / importers changes affect (search code / read source, do NOT assume).\n` +
66
- `- Confirm symbols / flags / configs changes require exist (search code / read source, do NOT assume).\n` +
67
- `- Confirm external data contracts (DB schemas, APIs / SDKs) changes affect (verify actual shape, do NOT assume).\n` +
68
- `- Confirm changes follow patterns / conventions already in this file / its neighbours where feasible (read source, do NOT assume).\n` +
69
- `- Confirm user instructions or plan tasks changes serve (quote them, do NOT trust memory).\n` +
70
- `Self-review is weak; the investigation itself is what changes the output. Advisory — proceed once satisfied.`
62
+ `[bkit GateGuard] First edit to \`${base}\` this session. Before you edit, confirm each point below, and investigate any you cannot answer:\n` +
63
+ `- Confirm you read this file and the exact symbols and lines you are about to change.\n` +
64
+ `- Confirm the exact field names, types and signatures you are changing.\n` +
65
+ `- Confirm the callers and importers the change affects, by searching or reading the code.\n` +
66
+ `- Confirm the symbols, flags and configs the change needs exist, by searching or reading the code.\n` +
67
+ `- Confirm the external data contracts (database schemas, APIs and SDKs) the change affects, by checking their actual shape.\n` +
68
+ `- Confirm the change follows the patterns and conventions already in this file or its neighbours where feasible, by reading the code.\n` +
69
+ `- Confirm the user instructions or plan tasks the change serves, by quoting them, not from memory.\n` +
70
+ `Advisory: proceed once satisfied.`
71
71
  );
72
72
  }
73
73
 
74
74
  function reuseChecklist(filePath) {
75
75
  const base = path.basename(filePath);
76
76
  return (
77
- `[bkit GateGuard] New file \`${base}\` this session - confirm following, and investigate anything you cannot answer BEFORE adding:\n` +
78
- `- Confirm existing code does NOT already provide capability (search code / read source, do NOT assume).\n` +
79
- `- Confirm existing code CANNOT be reused / extended to provide capability (search code / read source, do NOT assume).\n` +
80
- `- Confirm anything code supersedes is deleted, NOT left as duplicate work (verify removal, do NOT assume).\n` +
81
- `- Confirm location / naming fits project architecture / topology / standards (search code / read source, do NOT assume).\n` +
82
- `- Confirm structures / patterns / conventions follow closest equivalent files where feasible (read source, do NOT assume).\n` +
83
- `Bolt-on drift starts here; evolve existing code first. Advisory — proceed once satisfied.`
77
+ `[bkit GateGuard] New file \`${base}\` this session. Before you add it, confirm each point below, and investigate any you cannot answer:\n` +
78
+ `- Confirm existing code does not already provide the capability, by searching or reading the code.\n` +
79
+ `- Confirm existing code cannot be reused or extended to provide the capability, by searching or reading the code.\n` +
80
+ `- Confirm anything the new code supersedes is deleted rather than left as duplicate work, by checking the removal.\n` +
81
+ `- Confirm the location and naming fit the project's architecture, topology and standards, by searching or reading the code.\n` +
82
+ `- Confirm the structures, patterns and conventions follow the closest equivalent files where feasible, by reading the code.\n` +
83
+ `Evolve existing code first.\n` +
84
+ `Advisory: proceed once satisfied.`
84
85
  );
85
86
  }
86
87
 
@@ -99,27 +100,42 @@ function isDocsPath(filePath) {
99
100
  function docAuthoringAdvisory() {
100
101
  return (
101
102
  `[bkit GateGuard] docs/*.md authoring:\n` +
102
- `- Read THIS file's header block and follow its purpose and rules if present.\n` +
103
- `- Check .agents/docs.md index first and confirm topic belongs in THIS doc, not another.\n` +
104
- `- Use dense token-efficient phrasing; NO filler / hedging / restating; tables > prose, bullets > paragraphs.\n` +
105
- `- Describe current state / rules, NOT reasons / history; state what to do, NOT why. ONLY exceptions: Docs where purpose IS the record.\n` +
106
- `Advisory — proceed once satisfied.`
103
+ `- Read this file's \`> [!CAUTION]\` header and follow its \`Purpose\` and \`Rules\`.\n` +
104
+ `- Find the topic's home in the \`.agents/docs.md\` index first, and confirm that it is this doc.\n` +
105
+ `- Follow \`.bkit/authoring.md\` § All Agent-Read Files and § Docs.\n` +
106
+ `Advisory: proceed once satisfied.`
107
107
  );
108
108
  }
109
109
 
110
110
  function configAdvisory(filePath) {
111
111
  const base = path.basename(filePath);
112
112
  return (
113
- `[bkit GateGuard] \`${base}\` quality-gate config (lint / format / types / test / slop):\n` +
114
- `- Prefer FIXING code over weakening any gates.\n` +
115
- `- If changes genuinely warranted, use targeted per-file / per-rule opt-outs over blanket disable.\n` +
116
- `- ALWAYS get explicit human sign-off for any quality-gate config changes.\n` +
117
- `Set BKIT_ALLOW_CONFIG_EDIT=1 to silence this. Advisory — proceed once satisfied.`
113
+ `[bkit GateGuard] \`${base}\` quality-gate config (lint, format, types, tests or slop):\n` +
114
+ `- Prefer fixing the code over weakening any gate.\n` +
115
+ `- If a change is genuinely warranted, use targeted opt-outs per file or per rule rather than a blanket disable.\n` +
116
+ `- ALWAYS get explicit human sign-off for any quality-gate config change.\n` +
117
+ `- If you are inside a \`/bkit-*\` workflow, where no sign-off is available:\n` +
118
+ ` - Record the block and continue.\n` +
119
+ ` - NEVER self-approve the opt-out.\n` +
120
+ `With BKIT_ALLOW_CONFIG_EDIT=1 set, this file gets the normal first-edit or new-file checklist instead.\n` +
121
+ `Advisory: proceed once satisfied.`
118
122
  );
119
123
  }
120
124
 
125
+ // Per user: on a temp dir users share (Linux `/tmp`) another user's copy cannot be written.
121
126
  function stateDir() {
122
- return path.join(os.tmpdir(), "bkit-gateguard");
127
+ return path.join(
128
+ os.tmpdir(),
129
+ typeof process.getuid === "function" ? `bkit-gateguard-${process.getuid()}` : "bkit-gateguard",
130
+ );
131
+ }
132
+
133
+ // (session, file) warnings this process could not write to its state file, standing in
134
+ // for it for the process's life.
135
+ const warnedInProcess = new Set();
136
+
137
+ function inProcessKey(sessionId, filePath) {
138
+ return JSON.stringify([sessionId, filePath]);
123
139
  }
124
140
 
125
141
  // Dedup scope: the session, narrowed to one agent when the host names it. A Claude Code
@@ -148,6 +164,7 @@ function readState(sessionId) {
148
164
  }
149
165
 
150
166
  function alreadyWarned(sessionId, filePath) {
167
+ if (warnedInProcess.has(inProcessKey(sessionId, filePath))) return true;
151
168
  return Boolean(readState(sessionId).files[filePath]);
152
169
  }
153
170
 
@@ -176,6 +193,9 @@ function gcOldState() {
176
193
  // The advisory for the first touch of `filePath` this session, or null when GateGuard
177
194
  // is off, the path is unusable, or this session was already warned about it. Records
178
195
  // the touch. `isNewFile` picks the reuse checklist over the read-this-file checklist.
196
+ // Fail-open: a state-file write error still returns the checklist and the process
197
+ // remembers it, as advisory only — a deny no later call can see was given would block
198
+ // every retry of the edit.
179
199
  function firstTouchAdvice(filePath, sessionId, isNewFile) {
180
200
  const mode = process.env.BKIT_GATEGUARD;
181
201
  if (mode === "off") return null;
@@ -196,8 +216,13 @@ function firstTouchAdvice(filePath, sessionId, isNewFile) {
196
216
  ? `${baseContext}\n\n${docAuthoringAdvisory()}`
197
217
  : baseContext;
198
218
 
199
- markWarned(sid, filePath);
200
- gcOldState();
219
+ try {
220
+ markWarned(sid, filePath);
221
+ gcOldState();
222
+ } catch {
223
+ warnedInProcess.add(inProcessKey(sid, filePath));
224
+ return { mode: "advisory", context };
225
+ }
201
226
 
202
227
  return { mode: mode === "deny" ? "deny" : "advisory", context };
203
228
  }
@@ -189,11 +189,10 @@ function shellEditTargets(cmd) {
189
189
  /** Shared advisory string, identical on every host. */
190
190
  function shellEditAdvisory(hits) {
191
191
  return (
192
- `bkit guardrails: this command edits files through the shell (${hits.join("; ")}). ` +
193
- "Pre-edit gates only see edit/write tools, so a shell rewrite bypasses every one of " +
194
- "them. Use the edit/write tool instead unless this is one of the sanctioned exceptions " +
195
- "in .agents/rules.md (generating files from a script, or a bulk mechanical rewrite). " +
196
- "Not blocked — proceed if it is."
192
+ `bkit guardrails: this command edits files through the shell (${hits.join("; ")}). The command is allowed. ` +
193
+ "Pre-edit gates see only the edit and write tools, so a shell edit gets past every one of them.\n" +
194
+ "Use the edit or write tool instead.\n" +
195
+ "If this is one of the exceptions in .agents/rules.md (generating files from a script, a bulk mechanical rewrite, or appending a log line to your own step output file with `>>`), proceed."
197
196
  );
198
197
  }
199
198
 
@@ -98,7 +98,7 @@ function gitDenyRule(g) {
98
98
  if (g.long.has("--force") || g.short.has("f") || g.args.some((a) => a.startsWith("+"))) {
99
99
  return {
100
100
  what: "git force-push",
101
- fix: "Do not force-push (--force, -f or a +refspec). Use a normal push, or --force-with-lease only when the user explicitly asks for it on a personal branch.",
101
+ fix: "NEVER force-push (--force, -f or a +refspec). Use a normal push, or --force-with-lease only when the user explicitly asks for it on a personal branch.",
102
102
  };
103
103
  }
104
104
  return null;
@@ -144,16 +144,22 @@ function denyRule(c) {
144
144
  const denied = g && gitDenyRule(g);
145
145
  if (denied) return denied;
146
146
  }
147
- if (/\brm\s+-rf\s+(\/(?:\s|$|\*)|~\/\*|\$HOME\/\*)/.test(c)) {
147
+ // rm with both -r and -f (-rf, -fr, -Rf, -r -f) on /, ~ or $HOME itself, bare, with a
148
+ // trailing slash, or with a trailing /*. A path below them (~/projects/x) is not matched.
149
+ if (
150
+ /\brm\s+(?:-[a-zA-Z]*(?:[rR][a-zA-Z]*f|f[a-zA-Z]*[rR])[a-zA-Z]*|-[rR]\s+-f|-f\s+-[rR])\s+(?:\/|~\/?|\$HOME\/?|\$\{HOME\}\/?)\*?(?=\s|$|[;&|)])/.test(
151
+ c,
152
+ )
153
+ ) {
148
154
  return {
149
155
  what: "recursive delete of a filesystem root",
150
- fix: "Do not run rm -rf against /, ~, or $HOME. Narrow the path to the target directory.",
156
+ fix: "NEVER run rm -rf against /, ~, or $HOME. Narrow the path to the target directory.",
151
157
  };
152
158
  }
153
159
  if (/\bchmod\s+-R\s+777\s+\//.test(c)) {
154
160
  return {
155
161
  what: "chmod -R 777 on the filesystem root",
156
- fix: "Do not world-writable-chmod the filesystem root.",
162
+ fix: "NEVER make the filesystem root world-writable.",
157
163
  };
158
164
  }
159
165
  return null;
@@ -4,16 +4,16 @@
4
4
 
5
5
  # BKIT_LINEAR_API_KEY required to call the Linear GraphQL API.
6
6
  if [[ -z "${BKIT_LINEAR_API_KEY:-}" ]]; then
7
- echo "Guard pre-check: FAIL — BKIT_LINEAR_API_KEY not set; cannot validate ${LINEAR_ISSUE_ID:-(unset)}." >&2
8
- emit_context "Guard pre-check: FAIL — BKIT_LINEAR_API_KEY missing for ${LINEAR_ISSUE_ID:-(unset)}. HARD STOP: refuse any Linear-related work, report the failure to the user, and stop."
7
+ echo "Guard pre-check: FAIL. BKIT_LINEAR_API_KEY not set, so ${LINEAR_ISSUE_ID:-(unset)} cannot be validated." >&2
8
+ emit_context "Guard pre-check: FAIL. BKIT_LINEAR_API_KEY is not set, so bkit cannot check ${LINEAR_ISSUE_ID:-(unset)}. HARD STOP: refuse any Linear-related work. Report the failure to the user, then stop."
9
9
  exit 1
10
10
  fi
11
11
 
12
12
  # LINEAR_ISSUE_ID required (Claude's trigger above already demands it; a Cursor Cloud
13
13
  # Agent sets it from workflow context).
14
14
  if [[ -z "${LINEAR_ISSUE_ID:-}" ]]; then
15
- echo "Guard pre-check: FAIL — LINEAR_ISSUE_ID not set." >&2
16
- emit_context "Guard pre-check: FAIL — LINEAR_ISSUE_ID not set. HARD STOP: refuse any Linear-related work, report the failure to the user, and stop."
15
+ echo "Guard pre-check: FAIL. LINEAR_ISSUE_ID not set." >&2
16
+ emit_context "Guard pre-check: FAIL. LINEAR_ISSUE_ID is not set. HARD STOP: refuse any Linear-related work. Report the failure to the user, then stop."
17
17
  exit 1
18
18
  fi
19
19
 
@@ -31,8 +31,8 @@ RESPONSE=$(curl -sS \
31
31
  -H "Authorization: ${BKIT_LINEAR_API_KEY}" \
32
32
  --data "$BODY" \
33
33
  "https://api.linear.app/graphql" 2>/dev/null) || {
34
- echo "Guard pre-check: FAIL — Linear API request failed for ${LINEAR_ISSUE_ID}." >&2
35
- emit_context "Guard pre-check: FAIL — Linear API unreachable for ${LINEAR_ISSUE_ID}. HARD STOP: refuse any Linear-related work, report the failure to the user, and stop."
34
+ echo "Guard pre-check: FAIL. Linear API request failed for ${LINEAR_ISSUE_ID}." >&2
35
+ emit_context "Guard pre-check: FAIL. The Linear API could not be reached for ${LINEAR_ISSUE_ID}. HARD STOP: refuse any Linear-related work. Report the failure to the user, then stop."
36
36
  exit 1
37
37
  }
38
38
 
@@ -60,12 +60,12 @@ fi
60
60
 
61
61
  # Guard 2: Issue must not be in a terminal state.
62
62
  if [[ "$ISSUE_STATE" == "Cancelled" || "$ISSUE_STATE" == "Done" ]]; then
63
- FAIL_REASON="Issue is in terminal state: ${ISSUE_STATE}"
63
+ FAIL_REASON="the issue is in a terminal state (${ISSUE_STATE})"
64
64
  fi
65
65
 
66
66
  if [[ -n "$FAIL_REASON" ]]; then
67
- echo "Guard pre-check: FAIL — issue: ${ISSUE_ID_DISPLAY} | ${FAIL_REASON}" >&2
68
- emit_context "Guard pre-check: FAIL — issue ${ISSUE_ID_DISPLAY} | ${FAIL_REASON}. HARD STOP: refuse any Linear-related work on this issue, report the failure to the user, and stop."
67
+ echo "Guard pre-check: FAIL. Issue ${ISSUE_ID_DISPLAY}: ${FAIL_REASON}" >&2
68
+ emit_context "Guard pre-check: FAIL. Issue ${ISSUE_ID_DISPLAY}: ${FAIL_REASON}. HARD STOP: refuse any Linear-related work on this issue. Report the failure to the user, then stop."
69
69
  exit 1
70
70
  fi
71
71
 
@@ -0,0 +1,8 @@
1
+ # --- Rules-read advisory: the one session-start nudge (bkit renders it from this one
2
+ # source into each SessionStart host's hook). Advisory only: it names `.agents/rules.md`
3
+ # and no other file, never blocks a session and never changes the exit code. Needs
4
+ # `emit_context`, which the host's own code above defines.
5
+
6
+ BKIT_RULES_ADVISORY='[bkit] Required reading before any other action: read `.agents/rules.md` and follow every rule in it.'
7
+
8
+ emit_context "$BKIT_RULES_ADVISORY"
@@ -148,10 +148,17 @@ function isCovered(ranges, [start, end]) {
148
148
  return mergeRanges(ranges).some(([s, e]) => s <= start && end <= e);
149
149
  }
150
150
 
151
+ // Per user: on a temp dir users share (Linux `/tmp`) another user's copy cannot be written.
151
152
  function readStateDir() {
152
- return path.join(os.tmpdir(), "bkit-readguard");
153
+ return path.join(
154
+ os.tmpdir(),
155
+ typeof process.getuid === "function" ? `bkit-readguard-${process.getuid()}` : "bkit-readguard",
156
+ );
153
157
  }
154
158
 
159
+ // Read logs this process could not write, standing in for them for the process's life.
160
+ const readLogsInProcess = new Map();
161
+
155
162
  function safeKey(value, fallback) {
156
163
  const s = typeof value === "string" ? value.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) : "";
157
164
  return s || fallback;
@@ -169,6 +176,7 @@ function readLogFile(sessionId, agentId) {
169
176
  // Absent log is the normal first-read case (guarded, no throw); a corrupt one throws
170
177
  // to the host's top-level fail-open boundary and that one call no-ops.
171
178
  function loadReadLog(file) {
179
+ if (readLogsInProcess.has(file)) return readLogsInProcess.get(file);
172
180
  if (!fs.existsSync(file)) return { files: {} };
173
181
  const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
174
182
  return parsed && typeof parsed.files === "object" && parsed.files ? parsed : { files: {} };
@@ -191,9 +199,12 @@ function gcOldReadLogs() {
191
199
  * conversation is summarised: earlier read output is no longer in context.
192
200
  */
193
201
  function resetReadLog(sessionId) {
202
+ const prefix = `${safeKey(sessionId, "no-session")}.`;
203
+ for (const file of readLogsInProcess.keys()) {
204
+ if (path.basename(file).startsWith(prefix)) readLogsInProcess.delete(file);
205
+ }
194
206
  const dir = readStateDir();
195
207
  if (!fs.existsSync(dir)) return;
196
- const prefix = `${safeKey(sessionId, "no-session")}.`;
197
208
  for (const name of fs.readdirSync(dir)) {
198
209
  if (name.startsWith(prefix)) fs.rmSync(path.join(dir, name), { force: true });
199
210
  }
@@ -210,17 +221,20 @@ function repeatReadMessage(repeats, cwd) {
210
221
  `- \`${displayPath(file, cwd)}\` lines ${range[0]}-${range[1] === OPEN_END ? "end" : range[1]}`,
211
222
  );
212
223
  return (
213
- `[bkit ReadGuard] Repeat read this conversation - unchanged since your last read:\n` +
224
+ `[bkit ReadGuard] Repeat read in this conversation. These lines are unchanged since your last read:\n` +
214
225
  `${lines.join("\n")}\n` +
215
- `Use the earlier output; do NOT read these lines again. Re-read ONLY if that output is no longer in your context (summarised, or read by another agent).\n` +
216
- `Advisory — proceed once satisfied.`
226
+ `Use the earlier output instead of reading these lines again.\n` +
227
+ `If that output is no longer in your context (summarised, or read by another agent), re-read the lines.\n` +
228
+ `Advisory: proceed once satisfied.`
217
229
  );
218
230
  }
219
231
 
220
232
  /**
221
233
  * The advisory for reading `targets` again, or null when ReadGuard is off, nothing is
222
234
  * trackable, or no target repeats an earlier read of the same unchanged file by the
223
- * same (session, agent). Records every trackable target.
235
+ * same (session, agent). Records every trackable target. Fail-open: a log write error
236
+ * still returns the note and the process keeps the log, so a long-lived host (opencode)
237
+ * still sees its repeats.
224
238
  */
225
239
  function repeatReadAdvice(targets, sessionId, agentId, cwd) {
226
240
  if (process.env.BKIT_READGUARD === "off") return null;
@@ -249,11 +263,16 @@ function repeatReadAdvice(targets, sessionId, agentId, cwd) {
249
263
  changed = true;
250
264
  }
251
265
 
252
- if (changed) {
253
- fs.mkdirSync(readStateDir(), { recursive: true });
254
- fs.writeFileSync(logFile, JSON.stringify(log), "utf-8");
266
+ try {
267
+ if (changed) {
268
+ fs.mkdirSync(readStateDir(), { recursive: true });
269
+ fs.writeFileSync(logFile, JSON.stringify(log), "utf-8");
270
+ readLogsInProcess.delete(logFile);
271
+ }
272
+ gcOldReadLogs();
273
+ } catch {
274
+ readLogsInProcess.set(logFile, log);
255
275
  }
256
- gcOldReadLogs();
257
276
 
258
277
  return repeats.length > 0 ? repeatReadMessage(repeats, cwd) : null;
259
278
  }
@@ -0,0 +1,61 @@
1
+ // --- Rules-read advisory: the one first-tool-call nudge (bkit renders it from this one
2
+ // source into every host hook whose host has no session-start event: opencode, Codex,
3
+ // Antigravity). Advisory only: it names `.agents/rules.md` and no other file, never blocks
4
+ // and never throws. Needs `fs`, `os` and `path` in scope; the host's own code above
5
+ // declares them. Plain declarations only — no `export` and no `import`: renderParts copies
6
+ // these bytes into each host template, so either would make the rendered CJS hook invalid.
7
+
8
+ const RULES_READ_ADVISORY =
9
+ "[bkit] Required reading before any other action: read `.agents/rules.md` and follow every rule in it.";
10
+
11
+ /**
12
+ * The OS-temp dir holding one state file per session the advisory already reached. Per
13
+ * user: on a temp dir users share (Linux `/tmp`) another user's copy cannot be written.
14
+ */
15
+ function rulesAdvisoryStateDir() {
16
+ const user = typeof process.getuid === "function" ? `-${process.getuid()}` : "";
17
+ return path.join(os.tmpdir(), `bkit-rules-advisory${user}`);
18
+ }
19
+
20
+ /** State files this process could not write, standing in for them for the process's life. */
21
+ const rulesAdvisedInProcess = new Set();
22
+
23
+ /** One state file per session id; a payload with no id falls back to one shared bucket. */
24
+ function rulesAdvisoryFile(sessionId) {
25
+ const safe =
26
+ typeof sessionId === "string" ? sessionId.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 128) : "";
27
+ return path.join(rulesAdvisoryStateDir(), `${safe || "no-session"}.json`);
28
+ }
29
+
30
+ /** Opportunistic TTL: drops state files older than 24h. */
31
+ function rulesAdvisoryGc() {
32
+ const dir = rulesAdvisoryStateDir();
33
+ if (!fs.existsSync(dir)) return;
34
+ const cutoff = Date.now() - 24 * 60 * 60 * 1000;
35
+ for (const name of fs.readdirSync(dir)) {
36
+ const file = path.join(dir, name);
37
+ const stat = fs.statSync(file, { throwIfNoEntry: false });
38
+ if (stat && stat.mtimeMs < cutoff) fs.rmSync(file, { force: true });
39
+ }
40
+ }
41
+
42
+ /**
43
+ * The advisory the first time `sessionId` is seen, null after. State lives in the OS temp
44
+ * dir — never in the consumer repo — and is GC'd after 24h. Fail-open: a state-file error
45
+ * returns the advisory instead of throwing, so the nudge is never lost to a bad state, and
46
+ * the process remembers it, so a long-lived host (opencode) does not repeat it every call.
47
+ */
48
+ function rulesReadAdviceOnce(sessionId) {
49
+ const file = rulesAdvisoryFile(sessionId);
50
+ try {
51
+ if (fs.existsSync(file)) return null;
52
+ fs.mkdirSync(rulesAdvisoryStateDir(), { recursive: true });
53
+ fs.writeFileSync(file, JSON.stringify({ at: Date.now() }), "utf-8");
54
+ rulesAdvisoryGc();
55
+ return RULES_READ_ADVISORY;
56
+ } catch {
57
+ if (rulesAdvisedInProcess.has(file)) return null;
58
+ rulesAdvisedInProcess.add(file);
59
+ return RULES_READ_ADVISORY;
60
+ }
61
+ }