@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
@@ -172,12 +172,12 @@ export function runCursorModule(ctx) {
172
172
  });
173
173
  // Generated copy-paste-ready Cursor Background Agents setup doc — `.cursor/bkit-cloud.md`.
174
174
  // Twin of `.claude/bkit-cloud.md` (runClaudeModule): UNTRACKED + gitignored, inlines REAL
175
- // secret values resolved from `.envrc` under the Cursor env-var policy (Linear tracker
176
- // adds BKIT_LINEAR_API_KEY, no autocompact knob). Never enters ws.writes / canonicalHashes /
177
- // `bkit check` drift — values are machine-local and expected to differ. Skipped on
178
- // dry-run (`bkit check`) so a read-only check never writes secrets. Upgrade regenerates
179
- // it via the same helper (see runUpgrade caller).
180
- if (!dryRun && writeCursorCloudDoc(process.cwd(), tokens, issueTracker)) {
175
+ // secret values resolved from `.envrc` — the same tracker-independent set as the Claude
176
+ // doc. Never enters ws.writes / canonicalHashes / `bkit check` drift — values are
177
+ // machine-local and expected to differ. Skipped on dry-run (`bkit check`) so a read-only
178
+ // check never writes secrets. Upgrade regenerates it via the same helper (see runUpgrade
179
+ // caller).
180
+ if (!dryRun && writeCursorCloudDoc(process.cwd(), tokens)) {
181
181
  console.log(`${logPrefix} ${tag}cursor: .cursor/bkit-cloud.md (generated — gitignored, holds resolved secrets)`);
182
182
  }
183
183
  }
@@ -5,7 +5,7 @@ import * as path from "node:path";
5
5
  import { writeTier2, deepMergeJson, ensureDir, isJsonObject, mergeTrackerEntry, } from "../write.js";
6
6
  import { stampManagedVersion } from "../version-file.js";
7
7
  import { applyOpencodeAgent, applyOpencodeCommand } from "../../render/hosts.js";
8
- import { getCoreRoot, getSharedRoot, getWorkflowsRoot, getPromptsRoot, } from "../../shared/package-roots.js";
8
+ import { getBkitDocsRoot, getCoreRoot, getSharedRoot, getWorkflowsRoot, getPromptsRoot, } from "../../shared/package-roots.js";
9
9
  import { DEFAULT_ISSUE_TRACKER } from "../manifest.js";
10
10
  import { substituteWorkflow } from "../../render/trackers.js";
11
11
  import { resolveNetworkAllowlist, extractMcpServers, networkAllowlistBases } from "../cloud-env.js";
@@ -14,7 +14,12 @@ import { parseJson, readJsonFile } from "../../shared/json.js";
14
14
  import { readBkitConfig } from "../../shared/settings.js";
15
15
  import { readInstallingVersion } from "../../shared/package-json.js";
16
16
  import { BKIT_PREFIX, installFile, listMdFiles, removeOrphans, trackMirrorWrite } from "./core.js";
17
- import { isOpencodeProvider, opencodeProviderId } from "../../render/models.js";
17
+ import { buildOpencodeModelLookup, isOpencodeProvider, opencodeProviderId, } from "../../render/models.js";
18
+ /** The distinct models bkit's prompts.md § Models pins on one opencode gateway column. */
19
+ function shippedPins(provider) {
20
+ const lookup = buildOpencodeModelLookup(path.join(getBkitDocsRoot(), "prompts.md"), provider);
21
+ return [...new Set(lookup.values())].join(", ");
22
+ }
18
23
  export function renderOpencodeAgentsCommands(ctx) {
19
24
  const { dryRun, opencodeModelLookup, effortMap, opencodeProvider, logPrefix } = ctx;
20
25
  const tag = dryRun ? "[dry-run] " : "";
@@ -121,7 +126,7 @@ export function detectOpencodeYmlProviderDrift(cwd) {
121
126
  const ymlPath = path.join(cwd, ".github", "workflows", "opencode.yml");
122
127
  if (!fs.existsSync(ymlPath))
123
128
  return null;
124
- // The installed provider — package.json `bkit.opencodeProvider` is the authoritative record
129
+ // The installed provider — package.json `bkit.providers.opencode.default` is the authoritative record
125
130
  // written on install. Absent/broken/unsupported → the null-guard below skips silently.
126
131
  const provider = readBkitConfig(cwd).opencodeProvider;
127
132
  if (!provider)
@@ -216,7 +221,7 @@ export function renderOpencodeJson(templatePath, tracker, provider, cwd = proces
216
221
  // Same "oauth": false reason as github: the API token in the header is the only auth
217
222
  // bkit wires, so a bad one fails as a 401, not as an OAuth sign-in prompt.
218
223
  mcpEntry =
219
- '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_TOKEN}" } }';
224
+ '"jira": { "type": "remote", "url": "https://mcp.atlassian.com/v2/mcp", "oauth": false, "headers": { "Authorization": "Bearer {env:BKIT_JIRA_API_KEY}" } }';
220
225
  }
221
226
  else {
222
227
  mcpEntry = "";
@@ -445,8 +450,9 @@ export function runOpencodeModule(ctx) {
445
450
  }
446
451
  }
447
452
  }
448
- // --- bkit-gateguard.js / bkit-readguard.js — Tier-2 markered-text (slash-comment); see install/manifest.ts ---
449
- for (const plugin of ["bkit-gateguard.js", "bkit-readguard.js"]) {
453
+ // --- bkit-gateguard.js / bkit-readguard.js / bkit-rules.js — Tier-2 markered-text
454
+ // (slash-comment); see install/manifest.ts ---
455
+ for (const plugin of ["bkit-gateguard.js", "bkit-readguard.js", "bkit-rules.js"]) {
450
456
  const opencodeCore = path.join(getCoreRoot(), ".opencode", "plugin");
451
457
  const pluginSrc = path.join(opencodeCore, plugin);
452
458
  const pluginDst = `.opencode/plugin/${plugin}`;
@@ -493,7 +499,7 @@ export function runOpencodeModule(ctx) {
493
499
  ` env — {env:KEY} placeholders in opencode.json resolve empty without this. Quit the\n` +
494
500
  ` running app first (a running instance ignores the new env).\n` +
495
501
  ` 4. Model IDs: all four providers (openrouter, ollama, opencode-zen, opencode-go) install ready-to-run curated per-agent pins. ` +
496
- `Re-pin any agent via .bkit/prompts.md § Model Overrides or by probing the provider's live /v1/models — see .bkit/providers.md § Models. NOTE: every ollama pin (deepseek-v4.1-flash, kimi-k3) needs a paid Ollama plan. opencode-go pins (deepseek-v4.1-flash, kimi-k3) — prefer pins that stay within the Go 5h usage window; opencode-zen pins are existence-validated via models.dev (the /zen/v1/models REST probe cannot see Go-only models — models.dev is the source of truth).\n` +
502
+ `Re-pin any agent via .bkit/prompts.md § Model Overrides or by probing the provider's live /v1/models — see .bkit/providers.md § Provider models. NOTE: every ollama pin (${shippedPins("ollama")}) needs a paid Ollama plan. opencode-go pins (${shippedPins("opencode-go")}) — prefer pins that stay within the Go 5h usage window; opencode-zen pins are existence-validated via models.dev (the /zen/v1/models REST probe cannot see Go-only models — models.dev is the source of truth).\n` +
497
503
  ` 5. Verify with: \`bkit doctor\` (credentials + tools) and \`bkit status\` (installed hosts + providers).`,
498
504
  });
499
505
  }
@@ -0,0 +1,116 @@
1
+ // install/template-notes.ts — the old opening note above `<!-- bkit:start -->` in the
2
+ // installed doc templates (`docs/templates/bkit-*.md`).
3
+ //
4
+ // Each doc template opens its managed block with a `<!-- Note: … -->` comment, so every
5
+ // upgrade refreshes it. Installs from older releases still hold bkit's note above
6
+ // `<!-- bkit:start -->`, where upgrade never writes. This migration removes that copy
7
+ // when it is byte-identical to a wording bkit shipped. Any other text above the block is
8
+ // the consumer's and stays. Register: docs/migrations.md.
9
+ import * as fs from "node:fs";
10
+ import * as path from "node:path";
11
+ import { findLineAnchoredMarkers } from "./managed-block.js";
12
+ import { sha256 } from "./version-file.js";
13
+ /**
14
+ * sha256 of each opening-note line a doc template carried above `<!-- bkit:start -->`,
15
+ * collected from the history of `.bkit/core/docs/templates/` and
16
+ * `.bkit/templates/docs/templates/`.
17
+ */
18
+ export const RETIRED_TEMPLATE_NOTE_HASHES = new Set([
19
+ // Audit templates, 5.0.0 – 5.2.2 ("Never overwrite.", `@bkit-audit-generate` last).
20
+ "09669d937bb36d23473bfd32b1b4c850ab16f9404fb292312d4ece03430ae2ff",
21
+ // Audit templates, 5.2.3 – 6.0.0 (adds the `bkit:anchor` sentence).
22
+ "eeefcc0b47e569bf12f7215f40ce4d42d68b596a0ccea5f8e6127eb95f98bc61",
23
+ // Audit templates, unreleased dev wording (`@bkit-audit-generate` first).
24
+ "771ac2789eb695e49c4973711eacda22faff474a99aa954bc4fbb800a0389f53",
25
+ // Plan template, 5.0.0 – 5.2.2 ("also stamped … recording its base commit").
26
+ "f412345a8898a9201434c57672d522d8b5c44cb3cf64e4bb12057908c0031c3a",
27
+ // Plan template, 5.2.3 – 6.0.0 (names `baseSha`, `baseRef`, `designPath`, `designBaseSha`).
28
+ "7a49df77a90aa9d32ff43d4187302f31656f7195041ce143defaf7e5effc4e17",
29
+ // Plan template, pre-5.0.0 dev wording, written as `<\!-- Note:` ("set once at design start").
30
+ "b8c53cd711194b363c69c84657a04ed2c6c8dba428b0ea13b6810e368b00c721",
31
+ // Plan template, unreleased dev wording (`@bkit-plan-generate` first).
32
+ "c4b2c520134881923aab16c41501ccc263bbb21662435b4813dd9bf6ad82764f",
33
+ ]);
34
+ const START_MARKER = "<!-- bkit:start -->";
35
+ const TEMPLATES_DIR = path.join("docs", "templates");
36
+ const OWNED_TEMPLATE = /^bkit-.+\.md$/;
37
+ /** An opening-note line, in the form bkit wrote it or the escaped form one dev build wrote. */
38
+ const NOTE_LINE = /^<\\?!-- Note:/;
39
+ /** What every shipped note names: the report or plan folder, or the agent that fills it. */
40
+ const BKIT_NOTE_TEXT = /docs\/(?:audits|plans)\/\{YYYYMM\}|@bkit-/;
41
+ const BOM = "\uFEFF";
42
+ /**
43
+ * Removes each line above the single `<!-- bkit:start -->` whose text is a note wording
44
+ * bkit shipped, with the blank line after it. When nothing else is left above the block,
45
+ * every blank line there goes too. Every other line is kept. A leading byte-order mark is
46
+ * kept. A file without exactly one line-anchored start marker is returned unchanged; that
47
+ * includes a file with CRLF line endings throughout, whose marker the finder does not see.
48
+ */
49
+ export function stripRetiredTemplateNotes(content) {
50
+ const bom = content.startsWith(BOM) ? BOM : "";
51
+ const body = content.slice(bom.length);
52
+ const starts = findLineAnchoredMarkers(body, START_MARKER);
53
+ if (starts.length !== 1)
54
+ return { content, removed: 0, edited: [] };
55
+ // The last element is the start marker's own line up to the marker, so it always stays.
56
+ const lines = body.slice(0, starts[0]).split("\n");
57
+ const drop = new Set();
58
+ const edited = [];
59
+ lines.forEach((line, i) => {
60
+ if (!NOTE_LINE.test(line))
61
+ return;
62
+ if (RETIRED_TEMPLATE_NOTE_HASHES.has(sha256(line.replace(/\r$/, "")))) {
63
+ drop.add(i);
64
+ if (i + 1 < lines.length - 1 && lines[i + 1].trim() === "")
65
+ drop.add(i + 1);
66
+ }
67
+ else if (BKIT_NOTE_TEXT.test(line)) {
68
+ edited.push(line);
69
+ }
70
+ });
71
+ if (drop.size === 0)
72
+ return { content, removed: 0, edited };
73
+ const head = lines.filter((_, i) => !drop.has(i)).join("\n");
74
+ return {
75
+ content: bom + (head.trim() === "" ? "" : head) + body.slice(starts[0]),
76
+ removed: [...drop].filter((i) => NOTE_LINE.test(lines[i])).length,
77
+ edited,
78
+ };
79
+ }
80
+ /** Absolute paths already named in this process. */
81
+ const warned = new Set();
82
+ /**
83
+ * Migration (installs up to 6.0.x, `docs/migrations.md`): for each installed
84
+ * `docs/templates/bkit-*.md`, removes bkit's old opening note above `<!-- bkit:start -->`.
85
+ * The removal is recorded in ws, so `bkit check` fails until upgrade runs. A note that
86
+ * matches no shipped wording is kept. When it names what a bkit note names, install, upgrade
87
+ * and `bkit check` print one line naming the file.
88
+ */
89
+ export function migrateTemplateNotes(dryRun, ws, logPrefix) {
90
+ if (!fs.lstatSync(TEMPLATES_DIR, { throwIfNoEntry: false })?.isDirectory())
91
+ return;
92
+ const tag = dryRun ? "[dry-run] " : "";
93
+ for (const name of fs.readdirSync(TEMPLATES_DIR).sort()) {
94
+ if (!OWNED_TEMPLATE.test(name))
95
+ continue;
96
+ const rel = path.join(TEMPLATES_DIR, name);
97
+ if (!fs.lstatSync(rel).isFile())
98
+ continue;
99
+ const result = stripRetiredTemplateNotes(fs.readFileSync(rel, "utf-8"));
100
+ // Upgrade runs this pass again as its closing dry-run check, so each file is named once.
101
+ const abs = path.resolve(rel);
102
+ if (result.edited.length > 0 && !warned.has(abs)) {
103
+ warned.add(abs);
104
+ const line = result.edited[0];
105
+ const shown = line.length > 80 ? `${line.slice(0, 80)}…` : line;
106
+ console.warn(`${logPrefix} ${rel}: the note above \`<!-- bkit:start -->\` matches no note bkit shipped, so it was kept: ${shown} bkit's own note now sits inside the block, where upgrade refreshes it. If yours is an edited copy of bkit's old note, delete it.`);
107
+ }
108
+ if (result.removed === 0)
109
+ continue;
110
+ if (!dryRun)
111
+ fs.writeFileSync(rel, result.content, "utf-8");
112
+ if (!ws.writes.some((w) => w.path === rel))
113
+ ws.writes.push({ path: rel, action: "update" });
114
+ console.log(`${logPrefix} ${tag}core: ${rel} — removed bkit's old note above \`<!-- bkit:start -->\` (it now sits inside the block)`);
115
+ }
116
+ }
@@ -15,6 +15,7 @@ import * as path from "node:path";
15
15
  import * as crypto from "node:crypto";
16
16
  import { parseJson } from "../shared/json.js";
17
17
  import { getTemplatesRoot, templateRelPath } from "../shared/package-roots.js";
18
+ import { isSchemaLedger } from "../ledgers/migrate.js";
18
19
  // ---------------------------------------------------------------------------
19
20
  // Parse
20
21
  // ---------------------------------------------------------------------------
@@ -107,8 +108,9 @@ export function isConsumerModified(relPath, absolutePath, canonicalHashes) {
107
108
  * reads the file, uninstall deletes it — so an entry for an absent path is dead
108
109
  * bookkeeping, and a file recreated at that path later would be misclassified as
109
110
  * bkit-owned. A template-set path is never a file bkit owns: install copies it
110
- * byte-for-byte into `.bkit/templates/` and never writes the consumer's own copy,
111
- * so it must carry no ownership hash. Retired and renamed managed files leave such
111
+ * byte-for-byte into `.bkit/templates/` and never writes the consumer's own copy
112
+ * (bar the brand migrations, which rewrite it only where bkit's exact shipped old text matches,
113
+ * `docs/migrations.md`), so it must carry no ownership hash. Retired and renamed managed files leave such
112
114
  * entries behind, and a pure merge would preserve them forever (the
113
115
  * `.bkit/scripts/…` entry a #507 move left and the `scripts/graphify/**` +
114
116
  * `scripts/serena/bkit-serena-mcp.sh` entries a #489 move left are the observed
@@ -131,13 +133,16 @@ export function mergeCanonicalHashes(cwd, existing, fresh, removing = []) {
131
133
  for (const [relPath, hash] of Object.entries(existing)) {
132
134
  if (!fs.existsSync(path.join(cwd, relPath)) ||
133
135
  isRemoving(relPath) ||
134
- isTemplateSetPath(relPath)) {
136
+ isTemplateSetPath(relPath) ||
137
+ isSchemaLedger(relPath)) {
135
138
  pruned++;
136
139
  continue;
137
140
  }
138
141
  canonicalHashes[relPath] = hash;
139
142
  }
140
- return { canonicalHashes: { ...canonicalHashes, ...fresh }, pruned };
143
+ // A ledger is append-only data a migration may rewrite, never a managed file.
144
+ const kept = Object.fromEntries(Object.entries(fresh).filter(([p]) => !isSchemaLedger(p)));
145
+ return { canonicalHashes: { ...canonicalHashes, ...kept }, pruned };
141
146
  }
142
147
  /** True when `dest` is a member of the package's copy-and-own template set. */
143
148
  function isTemplateSetPath(dest) {
@@ -0,0 +1,87 @@
1
+ // `bkit ledgers compact`: the five keyed ledgers rewritten to their fold winners
2
+ // (`.bkit/jsonl.md` § Compaction). A superseded same-identity row is dropped; the
3
+ // winner stays in place and gains `firstTs` + `updates` from every row of its entry,
4
+ // so age and recurrence survive the drop. Malformed, non-object, blank and keyless
5
+ // lines, and rows of kinds outside `AGED_KINDS`, stay byte-for-byte, as does a
6
+ // winner already carrying the right values, so a second run changes nothing. A
7
+ // union merge that brings dropped rows back is undone by the next run.
8
+ import * as fs from "node:fs";
9
+ import * as path from "node:path";
10
+ import { parseJson } from "../shared/json.js";
11
+ import { APPEND_LEDGERS, compareTs, identity, isAgedRow, lineage, normalize, placeLineage, } from "./telemetry.js";
12
+ /** The ledgers compaction rewrites, by `--ledger` name. */
13
+ export const COMPACT_LEDGERS = {
14
+ knowledge: APPEND_LEDGERS.knowledge.file,
15
+ decisions: APPEND_LEDGERS.decisions.file,
16
+ deferrals: APPEND_LEDGERS.deferrals.file,
17
+ failures: APPEND_LEDGERS.failures.file,
18
+ issues: ".bkit/issues.jsonl",
19
+ };
20
+ /** A line's row when it is a JSON object, else undefined. */
21
+ function rowOf(body) {
22
+ const parsed = parseJson(body);
23
+ const row = parsed.ok ? parsed.value : undefined;
24
+ return row !== null && typeof row === "object" && !Array.isArray(row)
25
+ ? row
26
+ : undefined;
27
+ }
28
+ /** `text` with each entry's superseded rows dropped and its winner stamped, plus the counts. */
29
+ export function compactLedgerText(text) {
30
+ const lines = text.split("\n");
31
+ const groups = new Map();
32
+ lines.forEach((line, i) => {
33
+ const body = line.replace(/\r$/, "");
34
+ if (body.trim() === "")
35
+ return;
36
+ const raw = rowOf(body);
37
+ if (raw === undefined)
38
+ return;
39
+ const row = normalize(raw);
40
+ if (!isAgedRow(row))
41
+ return;
42
+ const id = identity(row);
43
+ groups.set(id, [...(groups.get(id) ?? []), { i, row, raw }]);
44
+ });
45
+ const drop = new Set();
46
+ const replace = new Map();
47
+ let rows = 0;
48
+ let stamped = 0;
49
+ for (const group of groups.values()) {
50
+ rows += group.length;
51
+ // The fold's winner: highest `ts`, the later line on a tie.
52
+ const winner = group.reduce((best, r) => compareTs({ ts: r.row["ts"] }, { ts: best.row["ts"] }) >= 0 ? r : best);
53
+ for (const r of group)
54
+ if (r !== winner)
55
+ drop.add(r.i);
56
+ const l = lineage(group.map((r) => r.row));
57
+ if (winner.row["firstTs"] === l.firstTs && winner.row["updates"] === l.updates)
58
+ continue;
59
+ const crlf = (lines[winner.i] ?? "").endsWith("\r") ? "\r" : "";
60
+ replace.set(winner.i, JSON.stringify(placeLineage(winner.raw, l)) + crlf);
61
+ stamped++;
62
+ }
63
+ const out = lines.flatMap((line, i) => (drop.has(i) ? [] : [replace.get(i) ?? line]));
64
+ return { text: out.join("\n"), rows, dropped: drop.size, stamped };
65
+ }
66
+ /**
67
+ * Compact each named ledger under `root`; with `dryRun`, only count. Writes via temp
68
+ * file + rename, and only when the text changes, so an interrupted run never leaves a
69
+ * torn ledger. A missing ledger is reported with zero counts.
70
+ */
71
+ export function compactLedgers(root, ledgers, dryRun) {
72
+ return ledgers.map((ledger) => {
73
+ const file = COMPACT_LEDGERS[ledger];
74
+ const abs = path.join(root, file);
75
+ if (!fs.lstatSync(abs, { throwIfNoEntry: false })?.isFile()) {
76
+ return { ledger, file, rows: 0, dropped: 0, stamped: 0, written: false };
77
+ }
78
+ const { text, ...counts } = compactLedgerText(fs.readFileSync(abs, "utf-8"));
79
+ const change = counts.dropped + counts.stamped > 0;
80
+ if (change && !dryRun) {
81
+ const tmp = `${abs}.bkit-compact.tmp`;
82
+ fs.writeFileSync(tmp, text, "utf-8");
83
+ fs.renameSync(tmp, abs);
84
+ }
85
+ return { ledger, file, ...counts, written: change && !dryRun };
86
+ });
87
+ }
@@ -0,0 +1,233 @@
1
+ // ledgers/journal.ts — the dispatch seam's row primitives.
2
+ //
3
+ // `commands/lib.ts` `runCommand` writes two kinds of row while a workflow run is
4
+ // active: an `engine-call` row in the run's `status.jsonl` (one per bkit command
5
+ // dispatched, except one git launched or one made while the run's repo has a rebase
6
+ // paused) and a `friction` row in the run's own `.bkit/friction.jsonl` (one per
7
+ // unexpected non-zero exit). `status row --type=owner-pause` writes a `human-confirm`
8
+ // friction row through the same append. This module builds and appends them. It is a leaf:
9
+ // it imports only `node:*`, `../shared/json.js`, `./status.js` and `./telemetry.js`, never a `commands/**`
10
+ // module, so `lib.ts` can import it without a cycle. The caller passes in the exit
11
+ // codes that are declared routing (`SHARED_EXIT_CODES` plus the verb's own).
12
+ //
13
+ // Every export is synchronous and never throws; a write returns a result object the
14
+ // caller logs and swallows, so the journal can never change a command's exit code.
15
+ import * as fs from "node:fs";
16
+ import * as path from "node:path";
17
+ import { parseJson } from "../shared/json.js";
18
+ import { appendLine, statusTimestamp } from "./status.js";
19
+ import { APPEND_LEDGERS, SCHEMA, compareTs, mintTs, resolveRepoSlug, validate, writerProblem, } from "./telemetry.js";
20
+ /** The kill switch: `BKIT_ENGINE_JOURNAL=off` keeps the seam from writing any row. */
21
+ export function journalEnabled(env = process.env) {
22
+ return env["BKIT_ENGINE_JOURNAL"] !== "off";
23
+ }
24
+ /**
25
+ * True when git launched this process: git exports `GIT_EXEC_PATH` to every hook
26
+ * (pre-commit, commit-msg, post-commit, pre-push, post-checkout, post-merge, ...) and
27
+ * to the children it spawns, and a plain shell does not set it.
28
+ */
29
+ export function launchedByGit(env = process.env) {
30
+ const value = env["GIT_EXEC_PATH"];
31
+ return value !== undefined && value !== "";
32
+ }
33
+ /**
34
+ * True while the repo holding `dir` has a rebase paused: its git dir holds `rebase-merge`
35
+ * or `rebase-apply`. A worktree's `.git` file names its own git dir. A row appended then
36
+ * leaves a tracked `status.jsonl` with an unstaged change, and `git rebase --continue`
37
+ * refuses to go on.
38
+ */
39
+ export function rebasePaused(dir) {
40
+ for (let at = path.resolve(dir);; at = path.dirname(at)) {
41
+ const dotGit = path.join(at, ".git");
42
+ if (fs.existsSync(dotGit)) {
43
+ let gitDir = dotGit;
44
+ if (fs.statSync(dotGit).isFile()) {
45
+ const named = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, "utf-8"))?.[1]?.trim();
46
+ if (named === undefined)
47
+ return false;
48
+ gitDir = path.resolve(at, named);
49
+ }
50
+ return ["rebase-merge", "rebase-apply"].some((d) => fs.existsSync(path.join(gitDir, d)));
51
+ }
52
+ if (path.dirname(at) === at)
53
+ return false;
54
+ }
55
+ }
56
+ /** Flag names in `argv` (`--name=value` and `--name value` both give `name`); values are never kept. */
57
+ function flagNames(argv) {
58
+ const names = argv
59
+ .filter((arg) => arg.startsWith("--") && arg.length > 2)
60
+ .map((arg) => {
61
+ const eq = arg.indexOf("=");
62
+ return arg.slice(2, eq === -1 ? undefined : eq);
63
+ });
64
+ return [...new Set(names)];
65
+ }
66
+ /** The `status.jsonl` row recording that a bkit command was dispatched. `flags` is the raw argv after the verb. */
67
+ export function engineCallRow(input) {
68
+ return {
69
+ type: "engine-call",
70
+ workflow: input.workflow,
71
+ at: input.at ?? statusTimestamp(),
72
+ noun: input.noun,
73
+ verb: input.verb,
74
+ flags: flagNames(input.flags),
75
+ };
76
+ }
77
+ /** True when `code` (null = the command threw) is not a declared routing exit. */
78
+ export function shouldRecordFriction(code, excludedCodes) {
79
+ return code === null || !excludedCodes.has(code);
80
+ }
81
+ /**
82
+ * Dedup key `<noun>-<verb>/<step>`. The identity-gated prune truncates a friction
83
+ * key at about 68 characters, so two longer keys with one prefix collide; the key
84
+ * stays under KEY_LIMIT by clipping the step.
85
+ */
86
+ export function frictionKey(noun, verb, step) {
87
+ const head = `${noun}-${verb}/`;
88
+ return head + step.slice(0, Math.max(0, KEY_LIMIT - head.length));
89
+ }
90
+ const KEY_LIMIT = 60;
91
+ /** `bkit.version` from `<bookRoot>/.bkit/version`; "unknown" when unreadable. */
92
+ function pinnedVersion(bookRoot) {
93
+ const file = path.join(bookRoot, ".bkit", "version");
94
+ if (!fs.existsSync(file))
95
+ return "unknown";
96
+ const hit = /"pinnedVersion"\s*:\s*"([^"]+)"/.exec(fs.readFileSync(file, "utf-8"));
97
+ return hit?.[1] ?? "unknown";
98
+ }
99
+ /**
100
+ * The `tool-failure` friction row for an unexpected exit. `by.step` is the failing
101
+ * command's own `--step=` value, else the `<noun>-<verb>` sentinel, so it is never
102
+ * empty. `run` carries `parentSha` only when it resolved.
103
+ */
104
+ export function frictionRow(input) {
105
+ const step = input.step && input.step !== "" ? input.step : `${input.noun}-${input.verb}`;
106
+ const how = input.code === null ? "threw an unhandled error" : `exited ${input.code}`;
107
+ const row = {
108
+ schema: SCHEMA,
109
+ ts: mintTs(),
110
+ kind: "friction",
111
+ key: frictionKey(input.noun, input.verb, step),
112
+ repo: resolveRepoSlug(input.bookRoot) || "unknown/repo",
113
+ bkit: { version: pinnedVersion(input.bookRoot) },
114
+ by: { workflow: input.workflow, step },
115
+ category: "tool-failure",
116
+ scope: "bkit-repo",
117
+ severity: "MEDIUM",
118
+ summary: `bkit ${input.noun} ${input.verb} ${how}`,
119
+ description: `\`bkit ${input.noun} ${input.verb}\` ${how} at ${step}; the code is not one the command declares as routing.`,
120
+ source: "orchestrator",
121
+ status: "OPEN",
122
+ };
123
+ if (input.parentSha !== undefined && input.parentSha !== "") {
124
+ row["run"] = { parentSha: input.parentSha };
125
+ }
126
+ return row;
127
+ }
128
+ /**
129
+ * The `human-confirm` friction row for an owner pause (`status row --type=owner-pause`).
130
+ * `key` is `owner-pause/<workflow>.<reason>`, or `owner-pause/<workflow>` with no
131
+ * reason, clipped to KEY_LIMIT. `run` carries `parentSha` only when it resolved.
132
+ */
133
+ export function pauseFrictionRow(input) {
134
+ const point = input.reason !== undefined && input.reason !== ""
135
+ ? `${input.workflow}.${input.reason}`
136
+ : input.workflow;
137
+ const row = {
138
+ schema: SCHEMA,
139
+ ts: mintTs(),
140
+ kind: "friction",
141
+ key: `owner-pause/${point}`.slice(0, KEY_LIMIT),
142
+ repo: resolveRepoSlug(input.bookRoot) || "unknown/repo",
143
+ bkit: { version: pinnedVersion(input.bookRoot) },
144
+ by: { workflow: input.workflow, step: "owner-pause" },
145
+ category: "human-confirm",
146
+ scope: "bkit-repo",
147
+ severity: "LOW",
148
+ summary: `${input.workflow} paused for the owner at ${point}`,
149
+ description: `The ${input.workflow} workflow stopped and asked the owner (\`owner-pause\` at ${point}).`,
150
+ source: "orchestrator",
151
+ status: "OPEN",
152
+ };
153
+ if (input.parentSha !== undefined && input.parentSha !== "") {
154
+ row["run"] = { parentSha: input.parentSha };
155
+ }
156
+ return row;
157
+ }
158
+ /** Append one `engine-call` row to a run's `status.jsonl`. */
159
+ export function appendJournalRow(file, row) {
160
+ try {
161
+ fs.appendFileSync(file, appendLine(row));
162
+ return { ok: true };
163
+ }
164
+ catch (err) {
165
+ return { ok: false, error: err.message };
166
+ }
167
+ }
168
+ /**
169
+ * Append a friction row to `<bookRoot>/.bkit/friction.jsonl` with `recurrenceCount` 1.
170
+ * A recurrence appends the same-`key` fold winner again with a later `ts`, its
171
+ * `recurrenceCount` raised by one and `lastConfirmed` = that `ts`. No line is
172
+ * ever rewritten, so a row another writer appends meanwhile is kept.
173
+ */
174
+ export function appendFrictionRow(bookRoot, row) {
175
+ const checked = validate(row);
176
+ if (!checked.ok)
177
+ return { ok: false, error: checked.reason ?? "invalid friction row" };
178
+ const who = writerProblem(row);
179
+ if (who !== undefined)
180
+ return { ok: false, error: who };
181
+ const file = path.join(bookRoot, APPEND_LEDGERS.friction.file);
182
+ try {
183
+ fs.mkdirSync(path.dirname(file), { recursive: true });
184
+ const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
185
+ const prior = latestSameKey(text, row["key"]);
186
+ const next = prior === undefined ? { ...row, recurrenceCount: 1 } : recurrence(prior, row);
187
+ fs.appendFileSync(file, `${text !== "" && !text.endsWith("\n") ? "\n" : ""}${JSON.stringify(next)}\n`);
188
+ return { ok: true };
189
+ }
190
+ catch (err) {
191
+ return { ok: false, error: err.message };
192
+ }
193
+ }
194
+ /**
195
+ * The row recording one more occurrence of `prior`: its fields with a `ts` later
196
+ * than its own, the raised count and `lastConfirmed`. A `CLOSED` prior reopens with
197
+ * `row`'s `status`, so a fixed failure that comes back reaches triage again. Falls
198
+ * back to `row`'s fields when `prior`'s no longer validate.
199
+ */
200
+ function recurrence(prior, row) {
201
+ const count = typeof prior["recurrenceCount"] === "number" ? prior["recurrenceCount"] : 1;
202
+ const ts = typeof prior["ts"] === "number" && row["ts"] <= prior["ts"]
203
+ ? mintTs(prior["ts"])
204
+ : row["ts"];
205
+ const raised = { recurrenceCount: count + 1, lastConfirmed: ts };
206
+ const reopened = prior["status"] === "CLOSED" ? { status: row["status"] } : {};
207
+ const carried = { ...prior, ts, ...raised, ...reopened };
208
+ return validate(carried).ok ? carried : { ...row, ts, ...raised };
209
+ }
210
+ /** The same-`key` friction row in `text` that `fold` keeps: highest `ts`, the later line on a tie. */
211
+ function latestSameKey(text, key) {
212
+ let best;
213
+ for (const line of text.split("\n")) {
214
+ if (!line.includes(JSON.stringify(key)))
215
+ continue;
216
+ const parsed = readRow(line);
217
+ if (parsed?.["kind"] !== "friction" || parsed["key"] !== key)
218
+ continue;
219
+ if (best === undefined || compareTs({ ts: parsed["ts"] }, { ts: best["ts"] }) >= 0) {
220
+ best = parsed;
221
+ }
222
+ }
223
+ return best;
224
+ }
225
+ function readRow(line) {
226
+ const parsed = parseJson(line);
227
+ if (!parsed.ok)
228
+ return undefined;
229
+ const value = parsed.value;
230
+ return value !== null && typeof value === "object" && !Array.isArray(value)
231
+ ? value
232
+ : undefined;
233
+ }
@@ -0,0 +1,81 @@
1
+ // Ledger rows written before `schema: 2` rewritten in place into the schema-2 shape
2
+ // (`docs/migrations.md`). Each line goes through `normalize`; a line that already
3
+ // carries `schema`, does not parse, or is not a JSON object stays byte-for-byte,
4
+ // so a second run changes nothing. Readers still normalize: a union merge can
5
+ // bring an old line back from a branch that predates the rewrite, beside its
6
+ // rewritten copy. The next run drops such a line instead of rewriting it twice.
7
+ import * as fs from "node:fs";
8
+ import * as path from "node:path";
9
+ import { parseJson } from "../shared/json.js";
10
+ import { normalize } from "./telemetry.js";
11
+ /** Every repo ledger whose rows carry the shared top section (`.bkit/jsonl.md`). */
12
+ export const SCHEMA_LEDGERS = [
13
+ ".bkit/stats.jsonl",
14
+ ".bkit/friction.jsonl",
15
+ ".bkit/issues.jsonl",
16
+ "docs/decisions.jsonl",
17
+ "docs/deferrals.jsonl",
18
+ "docs/failures.jsonl",
19
+ "docs/knowledge.jsonl",
20
+ ];
21
+ /** True for a repo ledger path: append-only data, never a bkit-managed file. */
22
+ export const isSchemaLedger = (relPath) => SCHEMA_LEDGERS.includes(relPath.split(path.sep).join("/"));
23
+ /** A line's row when it is a JSON object, else undefined. */
24
+ function rowOf(body) {
25
+ const parsed = parseJson(body);
26
+ const row = parsed.ok ? parsed.value : undefined;
27
+ return row !== null && typeof row === "object" && !Array.isArray(row)
28
+ ? row
29
+ : undefined;
30
+ }
31
+ /**
32
+ * `text` with every pre-schema row rewritten; `rewritten` counts the lines changed.
33
+ * A pre-schema row whose rewrite is already a schema line of `text` is dropped and
34
+ * counted in `dropped`: it is that row's copy from an unmigrated branch.
35
+ */
36
+ export function migrateLedgerText(text) {
37
+ let rewritten = 0;
38
+ let dropped = 0;
39
+ const bodies = text.split("\n").map((line) => line.replace(/\r$/, ""));
40
+ const present = new Set(bodies.filter((b) => rowOf(b)?.["schema"] !== undefined));
41
+ const lines = text.split("\n").flatMap((line, i) => {
42
+ const body = bodies[i] ?? "";
43
+ if (body.trim() === "")
44
+ return [line];
45
+ const row = rowOf(body);
46
+ if (row === undefined || row["schema"] !== undefined)
47
+ return [line];
48
+ const next = JSON.stringify(normalize(row));
49
+ if (present.has(next)) {
50
+ dropped++;
51
+ return [];
52
+ }
53
+ rewritten++;
54
+ return [next + line.slice(body.length)];
55
+ });
56
+ return { text: lines.join("\n"), rewritten, dropped };
57
+ }
58
+ /**
59
+ * Rewrite (or drop, as {@link migrateLedgerText} does) the pre-schema rows of every {@link SCHEMA_LEDGERS} file under `root`;
60
+ * with `dryRun`, only count them. Returns the files that have (or had) such rows,
61
+ * with their line counts. Writes via temp file + rename, so an interrupted run
62
+ * never leaves a torn ledger.
63
+ */
64
+ export function migrateLedgers(root, dryRun) {
65
+ const out = [];
66
+ for (const file of SCHEMA_LEDGERS) {
67
+ const abs = path.join(root, file);
68
+ if (!fs.lstatSync(abs, { throwIfNoEntry: false })?.isFile())
69
+ continue;
70
+ const { text, rewritten, dropped } = migrateLedgerText(fs.readFileSync(abs, "utf-8"));
71
+ if (rewritten + dropped === 0)
72
+ continue;
73
+ if (!dryRun) {
74
+ const tmp = `${abs}.bkit-migrate.tmp`;
75
+ fs.writeFileSync(tmp, text, "utf-8");
76
+ fs.renameSync(tmp, abs);
77
+ }
78
+ out.push({ file, rewritten, dropped });
79
+ }
80
+ return out;
81
+ }