@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,172 @@
1
+ // bkit ci pins — download each version + sha256 pinned tool and check its hash.
2
+ //
3
+ // A file pins a tool as `<TOOL>_VERSION` plus `<TOOL>_SHA256` (shell `X="v"`, `export X=v`,
4
+ // Dockerfile `ARG X=v`) and downloads it from a URL that spells `${<TOOL>_VERSION}`.
5
+ // Renovate bumps the version and leaves the hash, so a version-only bump fails only when
6
+ // the image is rebuilt or the setup script reruns. This check fails first, naming the tool:
7
+ // on a hash that differs, a download that fails, or a downloaded version with no hash.
8
+ // A version no URL in the file uses (pnpm through corepack) is not a download: skipped.
9
+
10
+ import { createHash } from "node:crypto";
11
+ import * as fs from "node:fs";
12
+ import * as path from "node:path";
13
+
14
+ import { CommandError, EXIT, type RunContext } from "../lib.js";
15
+
16
+ /** One tool's pin in one file. */
17
+ export interface Pin {
18
+ tool: string;
19
+ version: string | null;
20
+ sha256: string | null;
21
+ /** The download URL with every known `*_VERSION` filled in; null when no URL uses the version. */
22
+ url: string | null;
23
+ /** Set when the pin cannot be checked as written. */
24
+ problem: "missing-sha256" | "missing-version" | "unresolved-url" | "ambiguous-url" | null;
25
+ }
26
+
27
+ export type PinStatus = "ok" | "mismatch" | "unreachable" | "skipped" | NonNullable<Pin["problem"]>;
28
+
29
+ export interface PinResult {
30
+ file: string;
31
+ tool: string;
32
+ version: string | null;
33
+ url: string | null;
34
+ status: PinStatus;
35
+ expected: string | null;
36
+ actual: string | null;
37
+ error: string | null;
38
+ }
39
+
40
+ export type Download = (url: string) => Promise<Buffer>;
41
+
42
+ const ASSIGNMENT =
43
+ /^\s*(?:ARG\s+|export\s+)?([A-Z][A-Z0-9]*)_(VERSION|SHA256)=("?)([^"\s]+)\3\s*$/gm;
44
+ const URL = /https?:\/\/[^\s"'<>]+/g;
45
+ const VERSION_REF = /\$\{?([A-Z][A-Z0-9]*)_VERSION\}?/g;
46
+ const ATTEMPTS = 3;
47
+ const TIMEOUT_MS = 120_000;
48
+
49
+ /** Every `*_VERSION` / `*_SHA256` pin in `text`, with the URL its version downloads from. */
50
+ export function parsePins(text: string): Pin[] {
51
+ const versions = new Map<string, string>();
52
+ const hashes = new Map<string, string>();
53
+ for (const m of text.matchAll(ASSIGNMENT)) {
54
+ (m[2] === "VERSION" ? versions : hashes).set(m[1], m[4]);
55
+ }
56
+ const urls = new Map<string, Set<string>>();
57
+ for (const [raw] of text.matchAll(URL)) {
58
+ for (const ref of raw.matchAll(VERSION_REF)) {
59
+ const filled = raw.replace(VERSION_REF, (whole, tool: string) => versions.get(tool) ?? whole);
60
+ const seen = urls.get(ref[1]) ?? new Set<string>();
61
+ urls.set(ref[1], seen.add(filled));
62
+ }
63
+ }
64
+
65
+ const tools = [...new Set([...versions.keys(), ...hashes.keys()])].sort();
66
+ return tools.map((tool): Pin => {
67
+ const version = versions.get(tool) ?? null;
68
+ const sha256 = hashes.get(tool) ?? null;
69
+ const found = [...(urls.get(tool) ?? [])];
70
+ const url = found.length === 1 ? found[0] : null;
71
+ const problem =
72
+ version === null
73
+ ? "missing-version"
74
+ : found.length > 1
75
+ ? "ambiguous-url"
76
+ : url !== null && url.includes("$")
77
+ ? "unresolved-url"
78
+ : url !== null && sha256 === null
79
+ ? "missing-sha256"
80
+ : null;
81
+ return { tool, version, sha256, url, problem };
82
+ });
83
+ }
84
+
85
+ /** GET `url` and return its body; retried, a non-2xx status or a timeout throws. */
86
+ export const fetchAsset: Download = async (url) => {
87
+ let last: unknown;
88
+ for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
89
+ try {
90
+ const res = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
91
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
92
+ return Buffer.from(await res.arrayBuffer());
93
+ } catch (err) {
94
+ last = err;
95
+ }
96
+ }
97
+ throw last instanceof Error ? last : new Error(String(last));
98
+ };
99
+
100
+ /** Check every pin of every file; each URL is downloaded once. */
101
+ export async function checkPins(
102
+ files: { file: string; text: string }[],
103
+ download: Download,
104
+ ): Promise<PinResult[]> {
105
+ const digests = new Map<string, Promise<string>>();
106
+ const digest = (url: string) => {
107
+ const known = digests.get(url);
108
+ if (known) return known;
109
+ const pending = download(url).then((body) => createHash("sha256").update(body).digest("hex"));
110
+ digests.set(url, pending);
111
+ return pending;
112
+ };
113
+
114
+ const results: PinResult[] = [];
115
+ for (const { file, text } of files) {
116
+ for (const pin of parsePins(text)) {
117
+ const base = { file, tool: pin.tool, version: pin.version, url: pin.url };
118
+ const expected = pin.sha256?.toLowerCase() ?? null;
119
+ const none = { expected, actual: null, error: null };
120
+ if (pin.problem) {
121
+ results.push({ ...base, ...none, status: pin.problem });
122
+ } else if (pin.url === null || expected === null) {
123
+ results.push({ ...base, ...none, status: "skipped" });
124
+ } else {
125
+ try {
126
+ const actual = await digest(pin.url);
127
+ const status = actual === expected ? "ok" : "mismatch";
128
+ results.push({ ...base, expected, actual, error: null, status });
129
+ } catch (err) {
130
+ const error = err instanceof Error ? err.message : String(err);
131
+ results.push({ ...base, ...none, status: "unreachable", error });
132
+ }
133
+ }
134
+ }
135
+ }
136
+ return results;
137
+ }
138
+
139
+ const FAILURE: Record<Exclude<PinStatus, "ok" | "skipped">, (r: PinResult) => string> = {
140
+ mismatch: (r) => `sha256 is ${r.actual}, the pin says ${r.expected} (${r.url})`,
141
+ unreachable: (r) => `download failed: ${r.error} (${r.url})`,
142
+ "missing-sha256": (r) => `downloaded from ${r.url} but has no ${r.tool}_SHA256 beside it`,
143
+ "missing-version": (r) => `${r.tool}_SHA256 has no ${r.tool}_VERSION beside it`,
144
+ "unresolved-url": (r) => `download URL still has an unknown variable: ${r.url}`,
145
+ "ambiguous-url": (r) => `${r.tool}_VERSION is used in more than one download URL`,
146
+ };
147
+
148
+ /** `bkit ci pins`: exit 0 when every download pin's sha256 matches what its URL serves. */
149
+ export async function pins(ctx: RunContext, download: Download = fetchAsset): Promise<number> {
150
+ const given = ctx.flags.file;
151
+ const names = Array.isArray(given) ? given : typeof given === "string" ? [given] : [];
152
+ if (names.length === 0) throw new CommandError(EXIT.USAGE, "give at least one --file");
153
+ const files = names.map((file) => {
154
+ const abs = path.resolve(ctx.cwd, file);
155
+ if (!fs.existsSync(abs)) throw new CommandError(EXIT.USAGE, `no such file: ${file}`);
156
+ return { file, text: fs.readFileSync(abs, "utf-8") };
157
+ });
158
+
159
+ const results = await checkPins(files, download);
160
+ for (const r of results) {
161
+ const label = `${r.tool} ${r.version ?? "(no version)"} in ${r.file}`;
162
+ if (r.status === "ok") ctx.log(`ok ${label}`);
163
+ else if (r.status === "skipped") ctx.log(`skipped ${label}: no download URL uses it`);
164
+ else ctx.log(`FAIL ${label}: ${FAILURE[r.status](r)}`);
165
+ }
166
+ for (const { file } of files) {
167
+ if (!results.some((r) => r.file === file)) ctx.log(`no *_VERSION / *_SHA256 pins in ${file}`);
168
+ }
169
+ const passed = results.every((r) => r.status === "ok" || r.status === "skipped");
170
+ ctx.emit({ passed, pins: results });
171
+ return passed ? EXIT.OK : EXIT.NO;
172
+ }
@@ -0,0 +1,223 @@
1
+ // Local full-gate receipts, shared by linked worktrees and bound to committed trees.
2
+ import { spawnSync } from "node:child_process";
3
+ import { createHash, randomUUID } from "node:crypto";
4
+ import * as fs from "node:fs";
5
+ import * as os from "node:os";
6
+ import * as path from "node:path";
7
+ import { gitEnv } from "../../ledgers/telemetry.js";
8
+ import { parseJson, readJsonFile } from "../../shared/json.js";
9
+ import { readPackageJson } from "../../shared/package-json.js";
10
+ import { scriptCommand, testCommand } from "../../shared/package-manager.js";
11
+ import { EXIT, git, outboxRoot, runGit } from "../lib.js";
12
+ import { changedOutside } from "../workflow/ledgers.js";
13
+
14
+ const UNIT = "bkit:gate:static-unit";
15
+ const INTEGRATION = "bkit:gate:static-unit-integration";
16
+ const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
17
+
18
+ function scriptsOf(pkg: unknown): Record<string, unknown> | null {
19
+ if (!pkg || typeof pkg !== "object" || !("scripts" in pkg)) return null;
20
+ const scripts = pkg.scripts;
21
+ if (!scripts || typeof scripts !== "object" || Array.isArray(scripts)) return null;
22
+ return scripts as Record<string, unknown>;
23
+ }
24
+
25
+ function gateDefinition(pkg: unknown): { gate: string; fingerprint: string } | null {
26
+ const values = scriptsOf(pkg);
27
+ if (!values) return null;
28
+ const gate = typeof values[INTEGRATION] === "string" ? INTEGRATION : UNIT;
29
+ if (typeof values[gate] !== "string" || values[gate].trim() === "") return null;
30
+ const fingerprint = createHash("sha256")
31
+ .update(JSON.stringify(Object.entries(values).sort(([a], [b]) => a.localeCompare(b))))
32
+ .digest("hex");
33
+ return { gate, fingerprint };
34
+ }
35
+
36
+ /** The deepest full push gate declared by this checkout. */
37
+ export function requiredPushGate(cwd: string): string | null {
38
+ const pkg = readPackageJson(cwd);
39
+ return pkg.ok ? (gateDefinition(pkg.pkg)?.gate ?? null) : null;
40
+ }
41
+
42
+ const receiptPath = (cwd: string, sha: string): string | null => {
43
+ const outbox = outboxRoot(cwd);
44
+ return outbox ? path.join(outbox, "push-gates", `${sha}.json`) : null;
45
+ };
46
+
47
+ function cleanHead(cwd: string): { sha: string; tree: string } | null {
48
+ const status = git(cwd, [
49
+ "status",
50
+ "--porcelain",
51
+ "--untracked-files=all",
52
+ "--ignore-submodules=none",
53
+ ]);
54
+ if (status !== "") return null;
55
+ const sha = git(cwd, ["rev-parse", "--verify", "HEAD^{commit}"]);
56
+ const tree = git(cwd, ["rev-parse", "--verify", "HEAD^{tree}"]);
57
+ return sha && tree ? { sha, tree } : null;
58
+ }
59
+
60
+ /** Execute a consumer gate; only a successful deepest full gate on an unchanged clean tree earns proof. */
61
+ export function runPushGate(cwd: string, gate: string, log: (message: string) => void): number {
62
+ const pkg = readPackageJson(cwd);
63
+ const script = pkg.ok ? scriptsOf(pkg.pkg)?.[gate] : null;
64
+ if (typeof script !== "string" || script.trim() === "") {
65
+ log(`package.json must declare a non-empty ${gate} script`);
66
+ return EXIT.USAGE;
67
+ }
68
+ const definition = pkg.ok ? gateDefinition(pkg.pkg) : null;
69
+ const before = cleanHead(cwd);
70
+ const head = git(cwd, ["rev-parse", "--verify", "HEAD^{commit}"]);
71
+ const file = head ? receiptPath(cwd, head) : null;
72
+ const attempt =
73
+ file && definition?.gate === gate ? path.join(`${file}.running`, randomUUID()) : null;
74
+ const fail = () => {
75
+ if (!attempt || !file) return;
76
+ fs.mkdirSync(path.dirname(file), { recursive: true });
77
+ fs.writeFileSync(
78
+ `${file}.failed`,
79
+ JSON.stringify({ version: 1, sha: head, gate, passed: false }) + "\n",
80
+ );
81
+ fs.rmSync(file, { force: true });
82
+ };
83
+ if (attempt) {
84
+ fs.mkdirSync(path.dirname(attempt), { recursive: true });
85
+ fs.writeFileSync(attempt, JSON.stringify({ pid: process.pid, sha: head }) + "\n");
86
+ fail();
87
+ }
88
+ const finish = (code: number) => {
89
+ if (attempt) fs.rmSync(attempt, { force: true });
90
+ return code;
91
+ };
92
+ const argv = testCommand(scriptCommand(gate));
93
+ log(`running ${scriptCommand(gate).join(" ")}`);
94
+ const result = spawnSync(argv[0]!, argv.slice(1), {
95
+ cwd,
96
+ env: gitEnv(),
97
+ stdio: ["ignore", 2, 2],
98
+ });
99
+ const status = result.error
100
+ ? 127
101
+ : (result.status ??
102
+ 128 + ((result.signal ? os.constants.signals[result.signal] : undefined) ?? 1));
103
+ if (result.error) log(result.error.message);
104
+ if (status !== 0 || !before || definition?.gate !== gate) {
105
+ fail();
106
+ return finish(status);
107
+ }
108
+ const after = cleanHead(cwd);
109
+ const afterPkg = readPackageJson(cwd);
110
+ if (
111
+ after?.sha !== before.sha ||
112
+ after.tree !== before.tree ||
113
+ !afterPkg.ok ||
114
+ gateDefinition(afterPkg.pkg)?.fingerprint !== definition.fingerprint
115
+ ) {
116
+ log("full gate passed, but the checkout changed — no reusable push receipt");
117
+ fail();
118
+ return finish(status);
119
+ }
120
+ if (file) {
121
+ fs.mkdirSync(path.dirname(file), { recursive: true });
122
+ fs.writeFileSync(
123
+ file,
124
+ JSON.stringify({ version: 1, ...before, ...definition, passed: true }) + "\n",
125
+ );
126
+ fs.rmSync(`${file}.failed`, { force: true });
127
+ log(`recorded full push gate for ${before.sha}`);
128
+ }
129
+ return finish(status);
130
+ }
131
+
132
+ /** Pending files survive interrupted runners; one read suffices to block earlier proof. */
133
+ function pendingAttempt(file: string): boolean {
134
+ const dir = `${file}.running`;
135
+ if (!fs.existsSync(dir)) return false;
136
+ const handle = fs.opendirSync(dir);
137
+ try {
138
+ return handle.readSync() !== null;
139
+ } finally {
140
+ handle.closeSync();
141
+ }
142
+ }
143
+
144
+ function validReceipt(
145
+ cwd: string,
146
+ file: string,
147
+ sha: string,
148
+ definition: { gate: string; fingerprint: string },
149
+ ): boolean {
150
+ const read = readJsonFile(file);
151
+ if (!read.ok || !read.value || typeof read.value !== "object") return false;
152
+ const receipt = read.value as Record<string, unknown>;
153
+ return (
154
+ receipt.version === 1 &&
155
+ receipt.passed === true &&
156
+ receipt.sha === sha &&
157
+ receipt.gate === definition.gate &&
158
+ receipt.fingerprint === definition.fingerprint &&
159
+ receipt.tree === git(cwd, ["rev-parse", `${sha}^{tree}`])
160
+ );
161
+ }
162
+
163
+ /** Every commit not covered by this success must be free of failed or unreadable gate evidence. */
164
+ function noLaterFailure(
165
+ cwd: string,
166
+ dir: string,
167
+ sha: string,
168
+ newSha: string,
169
+ definition: { gate: string; fingerprint: string },
170
+ ): boolean {
171
+ const range = git(cwd, ["rev-list", "--max-count=129", newSha, `^${sha}`]);
172
+ if (range === null) return false;
173
+ const commits = range ? range.split("\n") : [];
174
+ if (commits.length > 128) return false;
175
+ for (const commit of [sha, ...commits]) {
176
+ const file = path.join(dir, `${commit}.json`);
177
+ if (
178
+ fs.existsSync(`${file}.failed`) ||
179
+ pendingAttempt(file) ||
180
+ (fs.existsSync(file) && !validReceipt(cwd, file, commit, definition))
181
+ )
182
+ return false;
183
+ }
184
+ return true;
185
+ }
186
+
187
+ /** A bounded ancestor search; absent, malformed or stale proof always requires the full gate. */
188
+ export function hasVerifiedIncrement(
189
+ cwd: string,
190
+ oldSha: string,
191
+ newSha: string,
192
+ paths: string[],
193
+ ): boolean {
194
+ if (
195
+ !SHA.test(oldSha) ||
196
+ !SHA.test(newSha) ||
197
+ /^0+$/.test(oldSha) ||
198
+ !runGit(cwd, ["merge-base", "--is-ancestor", oldSha, newSha]).ok
199
+ )
200
+ return false;
201
+ const raw = git(cwd, ["show", `${newSha}:package.json`]);
202
+ const parsed = raw === null ? null : parseJson(raw);
203
+ const definition = parsed?.ok ? gateDefinition(parsed.value) : null;
204
+ const localPkg = readPackageJson(cwd);
205
+ if (
206
+ !definition ||
207
+ !localPkg.ok ||
208
+ gateDefinition(localPkg.pkg)?.fingerprint !== definition.fingerprint
209
+ )
210
+ return false;
211
+ const ancestors = git(cwd, ["rev-list", "--max-count=128", oldSha]);
212
+ const firstFile = receiptPath(cwd, oldSha);
213
+ if (!ancestors || !firstFile) return false;
214
+ const dir = path.dirname(firstFile);
215
+ for (const sha of ancestors.split("\n")) {
216
+ const file = path.join(dir, `${sha}.json`);
217
+ if (!validReceipt(cwd, file, sha, definition)) continue;
218
+ const diff = changedOutside(cwd, sha, newSha, paths);
219
+ if (diff.ok && diff.outside.length === 0 && noLaterFailure(cwd, dir, sha, newSha, definition))
220
+ return true;
221
+ }
222
+ return false;
223
+ }
@@ -15,18 +15,15 @@
15
15
  // See DE-34 for the shared-entrypoint + crash-isolation contract.
16
16
 
17
17
  import { execFileSync } from "node:child_process";
18
- import * as fs from "node:fs";
19
18
  import * as path from "node:path";
20
- import { readJsonFile } from "../shared/json.js";
21
- import { getPkgRoot } from "../shared/package-roots.js";
22
19
  import { isMirrorPath } from "../shared/protected-paths.js";
23
20
  import {
24
21
  gitEnv,
25
22
  resolveGitSha,
26
- resolveRepoSlug,
27
23
  type TelemetryEnvelope,
28
24
  type CompliancePayload,
29
25
  } from "../ledgers/telemetry.js";
26
+ import { appendLedgerRows } from "./workflow/ledgers.js";
30
27
  import type { ComplyPhase } from "../cli.js";
31
28
 
32
29
  // ---------------------------------------------------------------------------
@@ -200,26 +197,28 @@ export function runGrader(input: GraderInput): Violation[] {
200
197
 
201
198
  export interface ComplianceRowInput {
202
199
  violations: Violation[];
203
- phase: string;
200
+ /** The graded workflow (`by.workflow`). */
201
+ workflow: string;
202
+ /** The run's join key: HEAD at its close, shared with its counter and outcome rows. */
204
203
  parentSha: string;
205
- repo: string;
206
- bkitVersion: string;
207
- /** Additional envelope fields (step, subagent, etc.). */
208
- extra?: Partial<TelemetryEnvelope>;
204
+ /** The step the grade ran at (`by.step`). */
205
+ step: string;
209
206
  }
210
207
 
208
+ /** A compliance row as handed to `bkit ledgers append`: no schema, ts, repo or bkit. */
209
+ export type ComplianceRowDraft = {
210
+ kind: "compliance";
211
+ by: { workflow: string; step: string };
212
+ } & CompliancePayload;
213
+
211
214
  export type ComplianceRow = TelemetryEnvelope & CompliancePayload;
212
215
 
213
216
  /**
214
217
  * Build one `kind:"compliance"` row per rule.
215
218
  * Rules that produced no violation emit a "pass" row.
216
- * Every row carries `bkitVersion`.
217
- *
218
- * Called by the CLI dispatch after `runGrader`.
219
219
  */
220
- export function buildComplianceRows(input: ComplianceRowInput): ComplianceRow[] {
221
- const ts = Date.now();
222
- const { violations, phase, parentSha, repo, bkitVersion, extra } = input;
220
+ export function buildComplianceRows(input: ComplianceRowInput): ComplianceRowDraft[] {
221
+ const { violations, workflow, parentSha, step } = input;
223
222
 
224
223
  const violationByRule = new Map<RuleId, Violation>();
225
224
  for (const v of violations) {
@@ -227,35 +226,17 @@ export function buildComplianceRows(input: ComplianceRowInput): ComplianceRow[]
227
226
  }
228
227
 
229
228
  const ALL_RULES: RuleId[] = ["no-mirror-edit", "skip-ci-not-head"];
230
- const rows: ComplianceRow[] = [];
231
-
232
- for (const ruleId of ALL_RULES) {
229
+ return ALL_RULES.map((ruleId) => {
233
230
  const violation = violationByRule.get(ruleId);
234
- const result: "pass" | "fail" | "n/a" = violation != null ? violation.result : "pass";
231
+ const verdict: "pass" | "fail" | "n/a" = violation != null ? violation.result : "pass";
235
232
  const evidence = violation?.evidence;
236
-
237
- const envelope: TelemetryEnvelope = {
238
- ts: ts + rows.length, // micro-offset so each row has a unique ts within the batch
233
+ return {
239
234
  kind: "compliance",
240
- repo,
241
- bkitVersion,
242
- workflow: phase,
243
- step: "close-gate",
244
- ...(extra ?? {}),
245
- };
246
-
247
- const payload: CompliancePayload = {
248
- rule: ruleId,
249
- result,
250
- ...(evidence != null ? { evidence } : {}),
251
- phase,
252
- parentSha,
235
+ by: { workflow, step },
236
+ run: { parentSha },
237
+ rule: { id: ruleId, verdict, ...(evidence != null ? { evidence } : {}) },
253
238
  };
254
-
255
- rows.push({ ...envelope, ...payload });
256
- }
257
-
258
- return rows;
239
+ });
259
240
  }
260
241
 
261
242
  // ---------------------------------------------------------------------------
@@ -263,16 +244,23 @@ export function buildComplianceRows(input: ComplianceRowInput): ComplianceRow[]
263
244
  // ---------------------------------------------------------------------------
264
245
 
265
246
  /**
266
- * Append compliance rows to the stats ledger.
267
- * Best-effort: prints `[bkit-comply] append failed: …` on error, never throws.
247
+ * Append compliance rows to `<root>/.bkit/stats.jsonl` through `bkit ledgers append`.
248
+ * Best-effort: prints `[bkit-comply] append failed: …` and returns false on error,
249
+ * never throws.
268
250
  */
269
- export function appendComplianceRows(rows: ComplianceRow[], statsPath: string): void {
251
+ export function appendComplianceRows(
252
+ rows: ComplianceRowDraft[],
253
+ root: string,
254
+ log: (m: string) => void = (m) => console.error(m),
255
+ ): boolean {
256
+ if (rows.length === 0) return false;
270
257
  try {
271
- const ndjson = rows.map((r) => JSON.stringify(r)).join("\n") + "\n";
272
- fs.appendFileSync(statsPath, ndjson, "utf8");
258
+ appendLedgerRows(root, "stats", rows);
259
+ return true;
273
260
  } catch (err: unknown) {
274
261
  const msg = err instanceof Error ? err.message : String(err);
275
- console.error(`[bkit-comply] append failed: ${statsPath} — ${msg}`);
262
+ log(`[bkit-comply] append failed: ${path.join(root, ".bkit", "stats.jsonl")} — ${msg}`);
263
+ return false;
276
264
  }
277
265
  }
278
266
 
@@ -280,37 +268,45 @@ export function appendComplianceRows(rows: ComplianceRow[], statsPath: string):
280
268
  // One grading pass, as `bkit workflows close` runs it before its report
281
269
  // ---------------------------------------------------------------------------
282
270
 
271
+ /** The run a grade belongs to: the close's join key and step. */
272
+ export interface GradedRun {
273
+ parentSha: string;
274
+ step: string;
275
+ }
276
+
283
277
  /**
284
278
  * Grade `phase` over HEAD~1..HEAD (HEAD alone in a one-commit repo) and append
285
279
  * its compliance rows to `<cwd>/.bkit/stats.jsonl`. With `squashSha` (ship's
286
280
  * close, run in the feature worktree) the squash commit is graded instead —
287
281
  * its subject and `squash~1..squash` — so the grade covers the whole feature
288
- * as it reaches main, not the worktree's last commit. Fail-open: any
289
- * error is logged and returns null, so a close never stops on the grader.
282
+ * as it reaches main, not the worktree's last commit. The rows carry `run`'s
283
+ * `parentSha` and step (default: HEAD and `close-gate`), so they join the
284
+ * close's other rows. Fail-open: any error is logged and returns null, so a
285
+ * close never stops on the grader.
290
286
  */
291
287
  export function gradeCompliance(
292
288
  cwd: string,
293
289
  phase: string,
294
290
  log: (m: string) => void,
295
291
  squashSha?: string,
292
+ run?: GradedRun,
296
293
  ): Violation[] | null {
297
294
  try {
298
295
  const squashParent = squashSha === undefined ? "" : resolveGitSha(`${squashSha}~1`, cwd);
299
- const parentSha = squashParent || resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
300
- if (!parentSha) {
296
+ const base = squashParent || resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
297
+ if (!base) {
301
298
  log("[bkit-comply] cannot resolve a parent SHA (no commits?) — skipping grade");
302
299
  return null;
303
300
  }
304
301
  const headSha = squashParent ? squashSha : undefined;
305
- const violations = runGrader({ parentSha, phase, cwd, ...(headSha ? { headSha } : {}) });
302
+ const violations = runGrader({ parentSha: base, phase, cwd, ...(headSha ? { headSha } : {}) });
306
303
  const rows = buildComplianceRows({
307
304
  violations,
308
- phase,
309
- parentSha,
310
- repo: resolveRepoSlug(cwd) || "unknown/repo",
311
- bkitVersion: readBkitVersion(),
305
+ workflow: phase,
306
+ parentSha: run?.parentSha ?? resolveGitSha("HEAD", cwd),
307
+ step: run?.step ?? "close-gate",
312
308
  });
313
- appendComplianceRows(rows, path.join(cwd, ".bkit", "stats.jsonl"));
309
+ appendComplianceRows(rows, cwd, log);
314
310
  log(
315
311
  violations.length > 0
316
312
  ? `[bkit-comply] Compliance violations found:\n${formatComplianceSummary(violations)}`
@@ -346,33 +342,6 @@ export function formatComplianceSummary(violations: Violation[]): string {
346
342
  return lines.join("\n");
347
343
  }
348
344
 
349
- // ---------------------------------------------------------------------------
350
- // bkitVersion reader (used by CLI dispatch and tests)
351
- // ---------------------------------------------------------------------------
352
-
353
- /**
354
- * Read the bkit version from the package.json nearest to `searchFrom` (default: the
355
- * running bkit package's root). Returns "0.0.0" on any read/parse error (fail-open).
356
- */
357
- export function readBkitVersion(searchFrom?: string): string {
358
- // Walk up looking for a package.json with a `version` field; stop at the filesystem root.
359
- let dir = path.resolve(searchFrom ?? getPkgRoot());
360
- for (let i = 0; i < 8; i++) {
361
- const candidate = path.join(dir, "package.json");
362
- if (fs.existsSync(candidate)) {
363
- const read = readJsonFile(candidate);
364
- // Fail-open: a package.json that cannot be read ends the search with the default.
365
- if (!read.ok || read.value === null) return "0.0.0";
366
- const pkg = read.value as { version?: string };
367
- if (typeof pkg.version === "string") return pkg.version;
368
- }
369
- const parent = path.dirname(dir);
370
- if (parent === dir) break;
371
- dir = parent;
372
- }
373
- return "0.0.0";
374
- }
375
-
376
345
  // comply — compliance grader (advisory, never gating, fail-open).
377
346
  // Runs `runGrader` over `git diff parentSha..HEAD`, appends `kind:"compliance"`
378
347
  // rows to `.bkit/stats.jsonl`, and logs violations. Always exits 0 (fail-open);
@@ -385,27 +354,28 @@ export function runComplyCommand(complyPhase: ComplyPhase | null): void {
385
354
  const phase = complyPhase ?? "unknown";
386
355
  const logPrefix = "[bkit-comply]";
387
356
 
388
- // parentSha MUST be a resolved hex SHA: diffPaths returns [] for anything not
389
- // matching /^[0-9a-f]{7,40}$/, and parentSha is part of the compliance identity().
390
- // Resolves HEAD~1, else HEAD; neither → skip the grade.
391
- const statsPath = path.join(cwd, ".bkit", "stats.jsonl");
392
- const parentSha = resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
393
- if (!parentSha) {
357
+ // The grade's diff base MUST be a resolved hex SHA: diffPaths returns [] for anything
358
+ // not matching /^[0-9a-f]{7,40}$/. Resolves HEAD~1, else HEAD; neither → skip the grade.
359
+ const base = resolveGitSha("HEAD~1", cwd) || resolveGitSha("HEAD", cwd);
360
+ if (!base) {
394
361
  console.log(`${logPrefix} cannot resolve a parent SHA (no commits?) — skipping grade`);
395
362
  return;
396
363
  }
397
364
 
398
- console.log(`${logPrefix} Running compliance grader (phase=${phase}, parentSha=${parentSha})`);
399
-
400
- const violations = runGrader({ parentSha, phase, cwd });
401
-
402
- // The origin remote's owner/repo, the same slug every other telemetry writer uses.
403
- const repo = resolveRepoSlug(cwd) || "unknown/repo";
404
-
405
- const bkitVersion = readBkitVersion();
406
-
407
- const rows = buildComplianceRows({ violations, phase, parentSha, repo, bkitVersion });
408
- appendComplianceRows(rows, statsPath);
365
+ console.log(`${logPrefix} Running compliance grader (phase=${phase}, base=${base})`);
366
+
367
+ const violations = runGrader({ parentSha: base, phase, cwd });
368
+ // A row names the closing workflow it grades: without one, the grade is printed only.
369
+ const rows =
370
+ complyPhase === null
371
+ ? []
372
+ : buildComplianceRows({
373
+ violations,
374
+ workflow: complyPhase,
375
+ parentSha: resolveGitSha("HEAD", cwd),
376
+ step: "close-gate",
377
+ });
378
+ const written = complyPhase !== null && appendComplianceRows(rows, cwd);
409
379
 
410
380
  if (violations.length > 0) {
411
381
  const summary = formatComplianceSummary(violations);
@@ -414,9 +384,13 @@ export function runComplyCommand(complyPhase: ComplyPhase | null): void {
414
384
  console.log(`${logPrefix} All rules pass.`);
415
385
  }
416
386
 
417
- console.log(
418
- `${logPrefix} Appended ${rows.length} compliance row(s) to .bkit/stats.jsonl (advisory — not gating).`,
419
- );
387
+ if (complyPhase === null) {
388
+ console.log(`${logPrefix} no --phase: rows not written to .bkit/stats.jsonl.`);
389
+ } else if (written) {
390
+ console.log(
391
+ `${logPrefix} Appended ${rows.length} compliance row(s) to .bkit/stats.jsonl (advisory — not gating).`,
392
+ );
393
+ }
420
394
  } catch (err: unknown) {
421
395
  // Fail-open: any unexpected error in the dispatch body must not gate the workflow.
422
396
  const msg = err instanceof Error ? err.message : String(err);