@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
@@ -0,0 +1,832 @@
1
+ // tools/instructions-sources.ts — the sections of `.bkit/instructions.md` that copy a
2
+ // master elsewhere, read from that master and compared with the store.
3
+ //
4
+ // Masters: `## Rules` ← the `bkit:start` / `bkit:end` block of `.bkit/core/.agents/rules.md`;
5
+ // `## Project Rules` ← `## Project Rules` of `.agents/rules.md`; `## Hook Text` ← the
6
+ // messages built in `HOOK_SOURCES`; `## Permissions` ← the shipped Claude settings and
7
+ // opencode config; `## Special Behaviors` and `## Authoring Rules` ← `CATALOG_SOURCES`.
8
+ // Check mode runs in `tools/instructions-sources.test.ts`; `pnpm instructions:sync`
9
+ // rewrites the rule text and catalog copies. Hook text and permissions are fixed by hand.
10
+
11
+ import * as fs from "node:fs";
12
+ import * as path from "node:path";
13
+
14
+ /** One `## {heading}` section of a markdown file, heading line excluded, up to the next `## `. */
15
+ export function sectionOf(md: string, heading: string): string | undefined {
16
+ const m = new RegExp(`(?:^|\\n)## ${escapeRe(heading)}\\n`).exec(md);
17
+ if (!m) return undefined;
18
+ const rest = md.slice(m.index + m[0].length);
19
+ const end = rest.search(/^## /m);
20
+ return end === -1 ? rest : rest.slice(0, end);
21
+ }
22
+
23
+ const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
24
+
25
+ export interface RuleRef {
26
+ path: string;
27
+ section?: string;
28
+ }
29
+
30
+ export interface Carrier {
31
+ /** `workflow`, `prompt`, `repo-agent`, `audit`, `plan-template`, `entry`, `hook` or `permission`. */
32
+ surface: string;
33
+ /** `verbatim`, `condensed`, `partial`, `specialised`, `applies` or `cites`. */
34
+ relation: string;
35
+ /** As written: `all`, `all except …`, or backticked names and `prefix-*` families. */
36
+ names: string;
37
+ }
38
+
39
+ export interface DriftItem {
40
+ /** The item line as written, ` - ` dropped. */
41
+ raw: string;
42
+ cites: { name: string; line: number }[];
43
+ /** The quoted excerpt the cited lines hold. */
44
+ excerpt?: string;
45
+ /** Why the drift stays, from a `- kept:` line under the item. */
46
+ kept?: string;
47
+ }
48
+
49
+ export interface RuleEntry {
50
+ /** The `### {name}` heading: the rule's ID, unique across `## Rules` and `## Project Rules`. */
51
+ name: string;
52
+ text: string;
53
+ retired: string[];
54
+ refs: RuleRef[];
55
+ /** `## Clauses` entry carrying the rule's text. */
56
+ clause?: string;
57
+ carriers: Carrier[];
58
+ drift: DriftItem[];
59
+ /** Entries reviewed as distinct despite reading alike. */
60
+ distinctFrom: string[];
61
+ /** Prompts that copy the whole rule bullet, as written (`all`, `all except …`, names). */
62
+ carry?: string;
63
+ }
64
+
65
+ export const CARRIER_SURFACES = [
66
+ "workflow",
67
+ "prompt",
68
+ "repo-agent",
69
+ "audit",
70
+ "plan-template",
71
+ "entry",
72
+ "hook",
73
+ "permission",
74
+ ];
75
+
76
+ /** A rule's `### {name}`, which tags, clause `- rule:` / `- tags:` lines and prose cite it by. */
77
+ export const RULE_NAME = /^[a-z0-9][a-z0-9-]*/;
78
+
79
+ const CITES = /^((?:`[^`:]+:\d+`(?:, )?)+): ?(.*)$/;
80
+
81
+ /** One drift item line (` - ` dropped) with its `kept` reason. */
82
+ export function parseDriftItem(raw: string, kept?: string): DriftItem {
83
+ const m = CITES.exec(raw);
84
+ const cites = m
85
+ ? [...m[1]!.matchAll(/`([^`:]+):(\d+)`/g)].map((c) => ({ name: c[1]!, line: Number(c[2]) }))
86
+ : [];
87
+ const excerpt = m ? /"([^"]+)"/.exec(m[2]!)?.[1] : undefined;
88
+ return {
89
+ raw,
90
+ cites,
91
+ ...(excerpt === undefined ? {} : { excerpt }),
92
+ ...(kept === undefined ? {} : { kept }),
93
+ };
94
+ }
95
+
96
+ /** `- {key}:` lines of an entry, each with the lines indented under it. */
97
+ export function entryKeys(section: string): { key: string; value: string; children: string[] }[] {
98
+ const out: { key: string; value: string; children: string[] }[] = [];
99
+ let inBlock = false;
100
+ for (const line of section.split("\n")) {
101
+ if (/^`{3,}/.test(line)) inBlock = !inBlock;
102
+ if (inBlock) continue;
103
+ const top = /^- ([a-z-]+):(?: (.*))?$/.exec(line);
104
+ if (top) out.push({ key: top[1]!, value: top[2] ?? "", children: [] });
105
+ else if (/^ {2,}- /.test(line) && out.length > 0) out[out.length - 1]!.children.push(line);
106
+ else if (line.trim() === "") continue;
107
+ else if (!/^ {2,}/.test(line)) out.push({ key: "", value: line, children: [] });
108
+ }
109
+ return out;
110
+ }
111
+
112
+ /** The two rule masters: the bkit-block template and the repo's own rules file. */
113
+ export interface RuleMasters {
114
+ bkit: string;
115
+ project: string;
116
+ }
117
+
118
+ const RULE_SECTIONS = [
119
+ { heading: "Rules", region: "bkit" },
120
+ { heading: "Project Rules", region: "project" },
121
+ ] as const;
122
+
123
+ /** Top-level `- ` bullets of the bkit block, or of `## Project Rules` below `bkit:end`, in file order. */
124
+ export function ruleBullets(rulesMd: string, region: "bkit" | "project"): string[] {
125
+ const start = rulesMd.indexOf("<!-- bkit:start -->");
126
+ const end = rulesMd.indexOf("<!-- bkit:end -->");
127
+ let body: string;
128
+ if (region === "bkit") {
129
+ body = start === -1 || end === -1 ? "" : rulesMd.slice(start, end);
130
+ } else {
131
+ body = sectionOf(end === -1 ? rulesMd : rulesMd.slice(end), "Project Rules") ?? "";
132
+ }
133
+ return body
134
+ .split("\n")
135
+ .filter((l) => l.startsWith("- "))
136
+ .map((l) => l.slice(2));
137
+ }
138
+
139
+ /** One entry per `### {name}` of `## {heading}` in the store. */
140
+ export function parseRuleEntries(md: string, heading: "Rules" | "Project Rules"): RuleEntry[] {
141
+ const body = sectionOf(md, heading);
142
+ if (body === undefined) throw new Error(`[bkit-instructions] no \`## ${heading}\` section`);
143
+ return body
144
+ .split(/^### /m)
145
+ .slice(1)
146
+ .map((section) => {
147
+ const name = section.slice(0, section.indexOf("\n")).trim();
148
+ const block = (kind: string) =>
149
+ [...section.matchAll(new RegExp(`^\`\`\`${kind}\\n([\\s\\S]*?)^\`\`\`$`, "gm"))].flatMap(
150
+ (m) => m[1]!.split("\n").filter((l) => l.trim() !== ""),
151
+ );
152
+ const refs: RuleRef[] = [];
153
+ const refsAt = section.search(/^- refs:$/m);
154
+ if (refsAt !== -1) {
155
+ for (const line of section.slice(refsAt).split("\n").slice(1)) {
156
+ const m = /^ {2}- `([^`]+)`(?: § (.+))?$/.exec(line);
157
+ if (!m) break;
158
+ refs.push(m[2] === undefined ? { path: m[1]! } : { path: m[1]!, section: m[2] });
159
+ }
160
+ }
161
+ const carriers: Carrier[] = [];
162
+ const drift: DriftItem[] = [];
163
+ let clause: string | undefined;
164
+ let carry: string | undefined;
165
+ const distinctFrom: string[] = [];
166
+ for (const k of entryKeys(section)) {
167
+ if (CARRIER_SURFACES.includes(k.key)) {
168
+ for (const c of k.children) {
169
+ const m = /^ {2}- ([a-z]+): (.+)$/.exec(c);
170
+ if (m) carriers.push({ surface: k.key, relation: m[1]!, names: m[2]! });
171
+ }
172
+ } else if (k.key === "drift") {
173
+ for (let i = 0; i < k.children.length; i++) {
174
+ const item = /^ {2}- (.+)$/.exec(k.children[i]!);
175
+ if (!item) continue;
176
+ const kept = /^ {4}- kept: (.+)$/.exec(k.children[i + 1] ?? "")?.[1];
177
+ drift.push(parseDriftItem(item[1]!, kept));
178
+ }
179
+ } else if (k.key === "clause") {
180
+ clause = /`([^`]+)`/.exec(k.value)?.[1];
181
+ } else if (k.key === "carry") {
182
+ carry = k.value;
183
+ } else if (k.key === "distinct-from") {
184
+ distinctFrom.push(...[...k.value.matchAll(/`([^`]+)`/g)].map((m) => m[1]!));
185
+ }
186
+ }
187
+ return {
188
+ name,
189
+ text: block("text").join("\n"),
190
+ retired: block("retired"),
191
+ refs,
192
+ ...(clause === undefined ? {} : { clause }),
193
+ carriers,
194
+ drift,
195
+ distinctFrom,
196
+ ...(carry === undefined ? {} : { carry }),
197
+ };
198
+ });
199
+ }
200
+
201
+ const globRe = (base: string) =>
202
+ new RegExp(`^${base.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")}$`);
203
+
204
+ /** Repo files a ref path names; a `*` in the basename matches any characters. */
205
+ function refFiles(root: string, ref: string): string[] {
206
+ const abs = path.join(root, ref);
207
+ if (!ref.includes("*")) return fs.existsSync(abs) ? [abs] : [];
208
+ const dir = path.dirname(abs);
209
+ if (!fs.existsSync(dir)) return [];
210
+ const re = globRe(path.basename(abs));
211
+ return fs
212
+ .readdirSync(dir)
213
+ .filter((f) => re.test(f))
214
+ .map((f) => path.join(dir, f));
215
+ }
216
+
217
+ /** True when `ref` names a repo file (or glob) and, with `section`, one of its files has that heading. */
218
+ export function refExists(root: string, ref: string, section?: string): boolean {
219
+ const files = refFiles(root, ref);
220
+ if (files.length === 0) return false;
221
+ if (section === undefined) return true;
222
+ const heading = new RegExp(`^#{1,6} ${escapeRe(section)}$`, "m");
223
+ return files.some((f) => fs.statSync(f).isFile() && heading.test(fs.readFileSync(f, "utf-8")));
224
+ }
225
+
226
+ /** Findings for `## Rules` and `## Project Rules` against their masters. */
227
+ export function checkRules(
228
+ store: string,
229
+ masters: RuleMasters,
230
+ exists: (ref: string, section?: string) => boolean,
231
+ ): string[] {
232
+ const out: string[] = [];
233
+ const seen = new Set<string>();
234
+ for (const s of RULE_SECTIONS) {
235
+ const entries = parseRuleEntries(store, s.heading);
236
+ const bullets = ruleBullets(masters[s.region], s.region);
237
+ const n = Math.max(entries.length, bullets.length);
238
+ for (let i = 0; i < n; i++) {
239
+ const e = entries[i];
240
+ const bullet = bullets[i];
241
+ if (!e) {
242
+ out.push(`${s.heading} bullet ${i + 1} of rules.md has no entry — ${bullet}`);
243
+ continue;
244
+ }
245
+ const tag = `\`${e.name}\``;
246
+ if (RULE_NAME.exec(e.name)?.[0] !== e.name) out.push(`${tag}: name must be kebab-case`);
247
+ if (seen.has(e.name)) out.push(`${tag}: name used by another rule; names are rule IDs`);
248
+ seen.add(e.name);
249
+ if (bullet === undefined) {
250
+ out.push(`${tag}: no rules.md bullet at position ${i + 1}`);
251
+ continue;
252
+ }
253
+ if (e.text !== bullet)
254
+ out.push(`${tag}: text differs from rules.md — run pnpm instructions:sync`);
255
+ for (const r of e.refs) {
256
+ if (!exists(r.path, r.section)) {
257
+ out.push(`${tag}: ref \`${r.path}\`${r.section ? ` § ${r.section}` : ""} does not exist`);
258
+ }
259
+ }
260
+ }
261
+ }
262
+ return out;
263
+ }
264
+
265
+ /**
266
+ * Copy each changed rules.md bullet into its entry's `text` block and move the old text
267
+ * to the front of its `retired` block. Entries are matched by position; a deleted or
268
+ * added bullet is fixed by hand.
269
+ */
270
+ export function syncRules(store: string, masters: RuleMasters): string {
271
+ const lines = store.split("\n");
272
+ for (const s of RULE_SECTIONS) {
273
+ const bullets = ruleBullets(masters[s.region], s.region);
274
+ const head = lines.indexOf(`## ${s.heading}`);
275
+ if (head === -1) continue;
276
+ let entry = -1;
277
+ for (let i = head + 1; i < lines.length && !lines[i]!.startsWith("## "); i++) {
278
+ if (lines[i]!.startsWith("### ")) entry++;
279
+ if (lines[i] !== "```text" || entry < 0) continue;
280
+ const close = lines.indexOf("```", i + 1);
281
+ const old = lines.slice(i + 1, close).join("\n");
282
+ const bullet = bullets[entry];
283
+ if (bullet === undefined || bullet === old) {
284
+ i = close;
285
+ continue;
286
+ }
287
+ lines.splice(i + 1, close - i - 1, bullet);
288
+ const after = i + 2;
289
+ let j = after + 1;
290
+ while (j < lines.length && lines[j] === "") j++;
291
+ if (lines[j] === "```retired") lines.splice(j + 1, 0, old);
292
+ else lines.splice(after + 1, 0, "", "```retired", old, "```");
293
+ i = after;
294
+ }
295
+ }
296
+ return lines.join("\n");
297
+ }
298
+
299
+ // ---------------------------------------------------------------------------
300
+ // Hook Text ← `.bkit/core/hooks/*.js` and the per-host guardrails hooks
301
+ // ---------------------------------------------------------------------------
302
+
303
+ /** Hook files whose messages `## Hook Text` copies. */
304
+ export const HOOK_SOURCES = [
305
+ ".bkit/core/hooks/gateguard-engine.js",
306
+ ".bkit/core/hooks/guardrails-read.js",
307
+ ".bkit/core/hooks/guardrails-shell.js",
308
+ ".bkit/core/hooks/guardrails-tiers.js",
309
+ ".bkit/core/hooks/readguard-engine.js",
310
+ ".bkit/core/.claude/hooks/bkit-guardrails.cjs",
311
+ ".bkit/core/.codex/hooks/bkit-guardrails.cjs",
312
+ ".bkit/core/.cursor/hooks/bkit-guardrails.cjs",
313
+ ".bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs",
314
+ ];
315
+
316
+ export interface HookMessage {
317
+ file: string;
318
+ /** The enclosing `function {name}`. */
319
+ fn: string;
320
+ /** Cooked text; each interpolation kept as `${expr}`, its source spelling. */
321
+ text: string;
322
+ /** Literal parts, an interpolation between each pair. */
323
+ parts: string[];
324
+ }
325
+
326
+ interface Literal {
327
+ start: number;
328
+ end: number;
329
+ parts: string[];
330
+ holes: string[];
331
+ }
332
+
333
+ const COOK: Record<string, string> = { n: "\n", t: "\t" };
334
+ const cook = (ch: string) => COOK[ch] ?? ch;
335
+
336
+ /** Index after the `${…}` expression opened at `i` (just past `${`), skipping nested strings. */
337
+ function skipExpr(src: string, i: number): number {
338
+ let depth = 1;
339
+ while (i < src.length) {
340
+ const c = src[i]!;
341
+ if (c === "'" || c === '"' || c === "`") {
342
+ i = readLiteral(src, i).end;
343
+ continue;
344
+ }
345
+ if (c === "{") depth++;
346
+ if (c === "}" && --depth === 0) return i + 1;
347
+ i++;
348
+ }
349
+ return i;
350
+ }
351
+
352
+ function readLiteral(src: string, start: number): Literal {
353
+ const q = src[start]!;
354
+ const parts = [""];
355
+ const holes: string[] = [];
356
+ let i = start + 1;
357
+ while (i < src.length && src[i] !== q) {
358
+ const c = src[i]!;
359
+ if (c === "\\") {
360
+ parts[parts.length - 1] += cook(src[i + 1]!);
361
+ i += 2;
362
+ } else if (q === "`" && c === "$" && src[i + 1] === "{") {
363
+ const end = skipExpr(src, i + 2);
364
+ holes.push(src.slice(i + 2, end - 1));
365
+ parts.push("");
366
+ i = end;
367
+ } else {
368
+ parts[parts.length - 1] += c;
369
+ i++;
370
+ }
371
+ }
372
+ return { start, end: i + 1, parts, holes };
373
+ }
374
+
375
+ /** Every string literal of a JS source, comments and regex literals skipped. */
376
+ function literals(src: string): Literal[] {
377
+ const out: Literal[] = [];
378
+ let prev = "";
379
+ let i = 0;
380
+ while (i < src.length) {
381
+ const c = src[i]!;
382
+ if (c === "/" && src[i + 1] === "/") {
383
+ i = src.indexOf("\n", i);
384
+ if (i === -1) break;
385
+ continue;
386
+ }
387
+ if (c === "/" && src[i + 1] === "*") {
388
+ i = src.indexOf("*/", i + 2) + 2;
389
+ continue;
390
+ }
391
+ if (c === "/" && (prev === "" || "(,=:[!&|?{};+".includes(prev))) {
392
+ i++;
393
+ let inClass = false;
394
+ while (i < src.length && (src[i] !== "/" || inClass)) {
395
+ if (src[i] === "\\") i++;
396
+ else if (src[i] === "[") inClass = true;
397
+ else if (src[i] === "]") inClass = false;
398
+ i++;
399
+ }
400
+ i++;
401
+ prev = "/";
402
+ continue;
403
+ }
404
+ if (c === "'" || c === '"' || c === "`") {
405
+ const lit = readLiteral(src, i);
406
+ out.push(lit);
407
+ i = lit.end;
408
+ prev = c;
409
+ continue;
410
+ }
411
+ if (!/\s/.test(c)) prev = c;
412
+ i++;
413
+ }
414
+ return out;
415
+ }
416
+
417
+ const MESSAGE_START = /^(?:\[bkit [A-Za-z]+\]|bkit (?:[A-Za-z]+ )?guardrails:|Blocked)/;
418
+
419
+ /**
420
+ * Agent-facing messages of a hook file: literals joined by `+` into one string, kept when
421
+ * the string opens with a bkit hook prefix (`[bkit GateGuard]`, `bkit … guardrails:`,
422
+ * `Blocked`), is a `fix:` value, or is the argument right after a kept message (Cursor's
423
+ * `agent_message`).
424
+ */
425
+ export function hookMessages(src: string, file: string): HookMessage[] {
426
+ const lits = literals(src);
427
+ const fns = [...src.matchAll(/\bfunction\s+(\w+)\s*\(/g)].map((m) => ({
428
+ at: m.index!,
429
+ name: m[1]!,
430
+ }));
431
+ const out: HookMessage[] = [];
432
+ let lastEnd = -1;
433
+ for (let k = 0; k < lits.length; k++) {
434
+ const group = [lits[k]!];
435
+ while (k + 1 < lits.length && /^\s*\+\s*$/.test(src.slice(lits[k]!.end, lits[k + 1]!.start))) {
436
+ group.push(lits[++k]!);
437
+ }
438
+ const parts = [""];
439
+ const holes: string[] = [];
440
+ for (const lit of group) {
441
+ parts[parts.length - 1] += lit.parts[0];
442
+ for (let h = 0; h < lit.holes.length; h++) {
443
+ holes.push(lit.holes[h]!);
444
+ parts.push(lit.parts[h + 1]!);
445
+ }
446
+ }
447
+ const start = group[0]!.start;
448
+ const isFix = /\bfix:\s*$/.test(src.slice(Math.max(0, start - 20), start));
449
+ const isNextArg = lastEnd !== -1 && /^\s*,\s*$/.test(src.slice(lastEnd, start));
450
+ if (!isFix && !isNextArg && !MESSAGE_START.test(parts[0]!)) continue;
451
+ lastEnd = group[group.length - 1]!.end;
452
+ const text = parts.map((p, h) => (h === 0 ? p : `\${${holes[h - 1]}}${p}`)).join("");
453
+ const fn = fns.filter((f) => f.at < group[0]!.start).pop()?.name ?? "";
454
+ out.push({ file, fn, text, parts });
455
+ }
456
+ return out;
457
+ }
458
+
459
+ const escapeLiteral = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
460
+
461
+ /** One `### ` entry of `## Hook Text`; `texts` = its text block split at blank lines. */
462
+ interface HookEntry {
463
+ name: string;
464
+ file: string;
465
+ fn: string;
466
+ texts: string[];
467
+ }
468
+
469
+ function parseHookEntries(md: string): HookEntry[] {
470
+ const body = sectionOf(md, "Hook Text") ?? "";
471
+ return body
472
+ .split(/^### /m)
473
+ .slice(1)
474
+ .map((section) => {
475
+ const name = section.slice(0, section.indexOf("\n")).trim();
476
+ const src = /^- source: `([^`]+)` `([^`]+)`$/m.exec(section);
477
+ const text = /^```text\n([\s\S]*?)\n```$/m.exec(section)?.[1] ?? "";
478
+ return { name, file: src?.[1] ?? "", fn: src?.[2] ?? "", texts: text.split("\n\n") };
479
+ });
480
+ }
481
+
482
+ /**
483
+ * Findings for `## Hook Text` against the hook files (`file` → content), both ways: each
484
+ * message matches one text of an entry with its file and function (`${…}` on either side
485
+ * matches anything), and each entry text matches a message.
486
+ */
487
+ export function checkHooks(store: string, sources: Map<string, string>): string[] {
488
+ const out: string[] = [];
489
+ const entries = parseHookEntries(store);
490
+ for (const e of entries) {
491
+ if (!e.file || !e.fn) out.push(`\`${e.name}\`: source must be \`{file}\` \`{function}\``);
492
+ }
493
+ const used = new Set<string>();
494
+ for (const [file, src] of sources) {
495
+ for (const m of hookMessages(src, file)) {
496
+ const re = new RegExp(`^${m.parts.map(escapeLiteral).join("[\\s\\S]*")}$`);
497
+ const hits = new Set<string>();
498
+ for (const e of entries) {
499
+ if (e.file !== file || e.fn !== m.fn) continue;
500
+ e.texts.forEach((t, i) => {
501
+ if (re.test(t)) {
502
+ hits.add(t);
503
+ used.add(`${e.name}\0${i}`);
504
+ }
505
+ });
506
+ }
507
+ if (hits.size === 0) {
508
+ out.push(`${file} \`${m.fn}\`: no \`## Hook Text\` entry for ${JSON.stringify(m.text)}`);
509
+ } else if (hits.size > 1) {
510
+ out.push(
511
+ `${file} \`${m.fn}\`: ${hits.size} different entry texts match ${JSON.stringify(m.text)}`,
512
+ );
513
+ }
514
+ }
515
+ }
516
+ for (const e of entries) {
517
+ if (!e.file || !e.fn) continue;
518
+ e.texts.forEach((t, i) => {
519
+ if (!used.has(`${e.name}\0${i}`)) {
520
+ out.push(
521
+ `\`${e.name}\`: no longer emitted by \`${e.file}\` \`${e.fn}\` — ${JSON.stringify(t)}`,
522
+ );
523
+ }
524
+ });
525
+ }
526
+ return out;
527
+ }
528
+
529
+ // ---------------------------------------------------------------------------
530
+ // Permissions ← `.bkit/shared/.claude/settings.json` and `.bkit/shared/.opencode/opencode.json`
531
+ // ---------------------------------------------------------------------------
532
+
533
+ const TIERS = ["deny", "ask", "allow"] as const;
534
+
535
+ /** Findings for `## Permissions` against the shipped Claude settings and opencode config. */
536
+ export function checkPermissions(
537
+ store: string,
538
+ settings: { permissions?: Partial<Record<(typeof TIERS)[number], string[]>> },
539
+ opencode: { permission?: unknown },
540
+ ): string[] {
541
+ const out: string[] = [];
542
+ const body = sectionOf(store, "Permissions") ?? "";
543
+ const groupsOf = new Map<string, string[]>();
544
+ const stored: Record<string, Map<string, string>> = {
545
+ deny: new Map(),
546
+ ask: new Map(),
547
+ allow: new Map(),
548
+ };
549
+ let opencodeSeen = false;
550
+ for (const section of body.split(/^### /m).slice(1)) {
551
+ const name = section.slice(0, section.indexOf("\n")).trim();
552
+ const tier = /^- tier: (.+)$/m.exec(section)?.[1] ?? "";
553
+ if (tier === "opencode `permission`") {
554
+ opencodeSeen = true;
555
+ const json = /^```json\n([\s\S]*?)\n```$/m.exec(section)?.[1] ?? "null";
556
+ if (JSON.stringify(JSON.parse(json)) !== JSON.stringify(opencode.permission ?? null)) {
557
+ out.push(
558
+ `\`${name}\`: differs from \`.bkit/shared/.opencode/opencode.json\` \`permission\``,
559
+ );
560
+ }
561
+ continue;
562
+ }
563
+ if (!(TIERS as readonly string[]).includes(tier)) {
564
+ out.push(`\`${name}\`: tier must be deny, ask, allow or opencode \`permission\``);
565
+ continue;
566
+ }
567
+ const patterns = (/^```text\n([\s\S]*?)\n```$/m.exec(section)?.[1] ?? "")
568
+ .split("\n")
569
+ .filter((l) => l !== "");
570
+ const count = Number(/^- count: (\d+)$/m.exec(section)?.[1] ?? NaN);
571
+ if (count !== patterns.length)
572
+ out.push(`\`${name}\`: count ${count}, holds ${patterns.length}`);
573
+ for (const p of patterns) {
574
+ groupsOf.set(p, [...(groupsOf.get(p) ?? []), name]);
575
+ stored[tier]!.set(p, name);
576
+ }
577
+ }
578
+ for (const [p, groups] of groupsOf) {
579
+ if (groups.length > 1) out.push(`\`${p}\` is in ${groups.length} groups: ${groups.join(", ")}`);
580
+ }
581
+ for (const tier of TIERS) {
582
+ const shipped = new Set(settings.permissions?.[tier] ?? []);
583
+ for (const p of shipped) {
584
+ if (!stored[tier]!.has(p)) out.push(`${tier}: \`${p}\` is shipped but in no group`);
585
+ }
586
+ for (const [p, group] of stored[tier]!) {
587
+ if (!shipped.has(p)) out.push(`${tier}: \`${p}\` is in \`${group}\` but not shipped`);
588
+ }
589
+ }
590
+ if (!opencodeSeen) out.push("no `opencode-permission` group");
591
+ return out;
592
+ }
593
+
594
+ // ---------------------------------------------------------------------------
595
+ // Special Behaviors ← `.bkit/core/.bkit/prompts.md`; Authoring Rules ← `workflows.md`
596
+ // ---------------------------------------------------------------------------
597
+
598
+ /** Catalog files the two sections copy. `authoring.md` is read in place, never copied. */
599
+ export const CATALOG_SOURCES = [".bkit/core/.bkit/prompts.md", ".bkit/core/.bkit/workflows.md"];
600
+
601
+ const FENCE_OPEN = /^(`{3,})/;
602
+
603
+ /** Per line: true when the line is a fence marker or inside a fenced block. */
604
+ function fencedLines(lines: string[]): boolean[] {
605
+ let fence = "";
606
+ return lines.map((l) => {
607
+ if (fence) {
608
+ if (l === fence) fence = "";
609
+ return true;
610
+ }
611
+ const m = FENCE_OPEN.exec(l);
612
+ if (m) fence = m[1]!;
613
+ return Boolean(m);
614
+ });
615
+ }
616
+
617
+ /**
618
+ * Body of the heading named `heading` (any level), up to the next heading of the same or
619
+ * a higher level outside a fenced block; blank lines at both ends dropped.
620
+ */
621
+ export function catalogSection(md: string, heading: string): string | undefined {
622
+ const lines = md.split("\n");
623
+ const fenced = fencedLines(lines);
624
+ const level = (l: string) => /^(#{1,6}) /.exec(l)?.[1]!.length ?? 0;
625
+ const at = lines.findIndex(
626
+ (l, i) => !fenced[i] && level(l) > 0 && l.replace(/^#+ /, "") === heading,
627
+ );
628
+ if (at === -1) return undefined;
629
+ const own = level(lines[at]!);
630
+ let end = at + 1;
631
+ while (
632
+ end < lines.length &&
633
+ !(level(lines[end]!) > 0 && !fenced[end] && level(lines[end]!) <= own)
634
+ )
635
+ end++;
636
+ const body = lines.slice(at + 1, end);
637
+ while (body.length > 0 && body[0]!.trim() === "") body.shift();
638
+ while (body.length > 0 && body[body.length - 1]!.trim() === "") body.pop();
639
+ return body.join("\n");
640
+ }
641
+
642
+ /** Cells of each `| … |` row of a section's table, header and separator dropped. */
643
+ function tableRows(body: string): string[][] {
644
+ return body
645
+ .split("\n")
646
+ .filter((l) => l.startsWith("| ") && l.endsWith(" |"))
647
+ .map((l) => l.slice(2, -2).split(" | "))
648
+ .slice(2);
649
+ }
650
+
651
+ /** One `### ` entry of a store section, with the line indexes sync rewrites. */
652
+ interface CatalogEntry {
653
+ name: string;
654
+ keys: Map<string, { value: string; line: number }>;
655
+ file: string;
656
+ heading: string;
657
+ text: string;
658
+ /** Indexes of the text block's opening and closing fence lines. */
659
+ open: number;
660
+ close: number;
661
+ }
662
+
663
+ function catalogEntries(lines: string[], section: string): CatalogEntry[] {
664
+ const fenced = fencedLines(lines);
665
+ const head = lines.findIndex((l, i) => !fenced[i] && l === `## ${section}`);
666
+ if (head === -1) return [];
667
+ const out: CatalogEntry[] = [];
668
+ let cur: CatalogEntry | undefined;
669
+ for (let i = head + 1; i < lines.length; i++) {
670
+ const l = lines[i]!;
671
+ if (!fenced[i] && l.startsWith("## ")) break;
672
+ if (!fenced[i] && l.startsWith("### ")) {
673
+ cur = {
674
+ name: l.slice(4).trim(),
675
+ keys: new Map(),
676
+ file: "",
677
+ heading: "",
678
+ text: "",
679
+ open: -1,
680
+ close: -1,
681
+ };
682
+ out.push(cur);
683
+ continue;
684
+ }
685
+ if (!cur) continue;
686
+ const key = /^- ([a-z]+): (.+)$/.exec(l);
687
+ if (key && !fenced[i]) {
688
+ cur.keys.set(key[1]!, { value: key[2]!, line: i });
689
+ const src = /^`([^`]+)` § (.+)$/.exec(key[2]!);
690
+ if (key[1] === "source" && src) [cur.file, cur.heading] = [src[1]!, src[2]!];
691
+ }
692
+ const open = /^(`{3,})text$/.exec(l);
693
+ if (open && cur.open === -1) {
694
+ cur.open = i;
695
+ cur.close = lines.indexOf(open[1]!, i + 1);
696
+ cur.text = lines.slice(i + 1, cur.close).join("\n");
697
+ }
698
+ }
699
+ return out;
700
+ }
701
+
702
+ const BEHAVIORS = "Special Behaviors";
703
+ const AUTHORING = "Authoring Rules";
704
+
705
+ interface Want {
706
+ entry: CatalogEntry;
707
+ text?: string;
708
+ keys: Record<string, string>;
709
+ }
710
+
711
+ /** What each entry should hold, and findings for rows and sections without one. */
712
+ function catalogWants(
713
+ lines: string[],
714
+ catalogs: Map<string, string>,
715
+ ): { wants: Want[]; out: string[] } {
716
+ const out: string[] = [];
717
+ const wants: Want[] = [];
718
+ const behaviors = catalogEntries(lines, BEHAVIORS);
719
+ const byTable = new Map<string, CatalogEntry[]>();
720
+ for (const e of behaviors) {
721
+ const k = `${e.file}\0${e.heading}`;
722
+ byTable.set(k, [...(byTable.get(k) ?? []), e]);
723
+ }
724
+ for (const [k, entries] of byTable) {
725
+ const [file, heading] = k.split("\0") as [string, string];
726
+ const body = catalogs.has(file) ? catalogSection(catalogs.get(file)!, heading) : undefined;
727
+ if (body === undefined) {
728
+ out.push(`\`${file}\` § ${heading}: not found`);
729
+ continue;
730
+ }
731
+ const rows = tableRows(body);
732
+ rows.forEach((row, i) => {
733
+ const e = entries[i];
734
+ if (!e) out.push(`${row[0]}: no \`## ${BEHAVIORS}\` entry`);
735
+ else
736
+ wants.push({
737
+ entry: e,
738
+ text: row[2] ?? "",
739
+ keys: { behavior: row[0] ?? "", agents: row[1] ?? "" },
740
+ });
741
+ });
742
+ for (const e of entries.slice(rows.length))
743
+ out.push(`\`${e.name}\`: no row in \`${file}\` § ${heading}`);
744
+ }
745
+ for (const e of catalogEntries(lines, AUTHORING)) {
746
+ const body = catalogs.has(e.file)
747
+ ? catalogSection(catalogs.get(e.file)!, e.heading)
748
+ : undefined;
749
+ if (body === undefined) out.push(`\`${e.name}\`: \`${e.file}\` § ${e.heading} not found`);
750
+ else wants.push({ entry: e, text: body, keys: {} });
751
+ }
752
+ for (const e of behaviors) {
753
+ if (!e.file) out.push(`\`${e.name}\`: source must be \`{file}\` § {heading}`);
754
+ }
755
+ return { wants, out };
756
+ }
757
+
758
+ /** Findings for `## Special Behaviors` and `## Authoring Rules` against the catalogs (`file` → content). */
759
+ export function checkCatalogs(store: string, catalogs: Map<string, string>): string[] {
760
+ const { wants, out } = catalogWants(store.split("\n"), catalogs);
761
+ for (const w of wants) {
762
+ for (const [k, v] of Object.entries(w.keys)) {
763
+ if (w.entry.keys.get(k)?.value !== v) out.push(`\`${w.entry.name}\`: ${k} differs`);
764
+ }
765
+ if (w.entry.text !== w.text) {
766
+ out.push(
767
+ `\`${w.entry.name}\`: ${Object.keys(w.keys).length > 0 ? "notes" : "text"} differ${Object.keys(w.keys).length > 0 ? "" : "s"} — run pnpm instructions:sync`,
768
+ );
769
+ }
770
+ }
771
+ return out;
772
+ }
773
+
774
+ /** The store with each Special Behaviors and Authoring Rules copy refreshed from its catalog. */
775
+ export function syncCatalogs(store: string, catalogs: Map<string, string>): string {
776
+ const lines = store.split("\n");
777
+ const { wants } = catalogWants(lines, catalogs);
778
+ // Bottom-up, so earlier indexes stay valid.
779
+ wants.sort((a, b) => b.entry.open - a.entry.open);
780
+ for (const w of wants) {
781
+ const text = w.text ?? "";
782
+ if (w.entry.open !== -1 && w.entry.text !== text) {
783
+ const fence = text.includes("```") ? "````" : "```";
784
+ lines.splice(
785
+ w.entry.open,
786
+ w.entry.close - w.entry.open + 1,
787
+ `${fence}text`,
788
+ ...text.split("\n"),
789
+ fence,
790
+ );
791
+ }
792
+ for (const [k, v] of Object.entries(w.keys)) {
793
+ const at = w.entry.keys.get(k);
794
+ if (at && at.value !== v) lines[at.line] = `- ${k}: ${v}`;
795
+ }
796
+ }
797
+ return lines.join("\n");
798
+ }
799
+
800
+ // ---------------------------------------------------------------------------
801
+ // Every copied section, read from `root`
802
+ // ---------------------------------------------------------------------------
803
+
804
+ const readAt = (root: string, rel: string) => fs.readFileSync(path.join(root, rel), "utf-8");
805
+
806
+ export function ruleMasters(root: string): RuleMasters {
807
+ return {
808
+ bkit: readAt(root, ".bkit/core/.agents/rules.md"),
809
+ project: readAt(root, ".agents/rules.md"),
810
+ };
811
+ }
812
+
813
+ const catalogsAt = (root: string) => new Map(CATALOG_SOURCES.map((f) => [f, readAt(root, f)]));
814
+
815
+ /** Findings for every store section that copies a master, read from `root`. */
816
+ export function checkSources(root: string, store: string): string[] {
817
+ return [
818
+ ...checkRules(store, ruleMasters(root), (ref, section) => refExists(root, ref, section)),
819
+ ...checkHooks(store, new Map(HOOK_SOURCES.map((f) => [f, readAt(root, f)]))),
820
+ ...checkPermissions(
821
+ store,
822
+ JSON.parse(readAt(root, ".bkit/shared/.claude/settings.json")),
823
+ JSON.parse(readAt(root, ".bkit/shared/.opencode/opencode.json")),
824
+ ),
825
+ ...checkCatalogs(store, catalogsAt(root)),
826
+ ];
827
+ }
828
+
829
+ /** The store with every generated copy refreshed from its master. */
830
+ export function syncSources(root: string, store: string): string {
831
+ return syncCatalogs(syncRules(store, ruleMasters(root)), catalogsAt(root));
832
+ }