@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,30 +1,41 @@
1
1
  // bkit ci — the gates CI and the git hooks run.
2
2
  //
3
- // `slop` — the enforcing slop gate (`slop:delta`). `lint:slop` (`slop-scan scan`) only
3
+ // `slop` — the enforcing slop gate (`bkit:slop:delta`). `lint:slop` (`slop-scan scan`) only
4
4
  // reports. This gate checks the base ref out as a detached worktree, runs
5
5
  // `slop-scan delta` against the working tree, and fails when the change makes the repo
6
6
  // worse on NET: more findings, or a higher score. It gates on the net figures, not on
7
7
  // "added": slop-scan's delta is keyed by position, so editing above a pre-existing
8
8
  // finding reports it as resolved at the old line and added at the new one, netting to
9
- // zero. The pre-existing baseline is never the change's to fix.
9
+ // zero. The pre-existing baseline is never the change's to fix. On failure it names each
10
+ // net-new or worsened finding (`path:line`, rule, message), with line shifts dropped.
10
11
  //
11
- // `prose` — the prose gate (`lint:prose`): Vale over the markdown files the globs
12
- // select. Skips with a log line when vale is not installed; restores the gitignored
13
- // write-good package from the main worktree (else `vale sync`) when it is missing.
12
+ // `prose` — the prose gate (`bkit:lint:prose`): Vale over the markdown files the globs
13
+ // select. Restores the gitignored write-good package from the main worktree (else
14
+ // `vale sync`) when it is missing, and fails when vale or write-good is unavailable.
14
15
  //
15
16
  // `skip-token` — whether a commit message carries a GitHub skip-CI token
16
17
  // (`SKIP_CI_TOKEN`), for the `.husky/pre-push` CI-suppressor guard.
17
18
  //
18
- // `min-push` — whether every file a push changes matches `bkit.minPushPaths`, so
19
+ // `min-push` — whether every file a push changes is one bkit's workflows write (ship's bookkeeping
20
+ // allow-list, the plans tree) or one `bkit.testing.minPushPaths` / `ciSkipPaths` adds, so
19
21
  // `.husky/pre-push` runs `bkit:gate:min`. Files decide, never `[skip ci]` (a typed label
20
22
  // GitHub reads off the last commit only).
23
+ //
24
+ // `bookkeeping-push` — whether a feature-branch push adds bookkeeping only on top of the
25
+ // head the remote holds (ship's `--scope=pr` allow-list, the one `bkit ledgers
26
+ // only-bookkeeping` and the merge gate's carry-forward read). The `.husky/pre-push`
27
+ // CI-suppressor guard lets a `[skip ci]` head through to an open PR on exit 0: the PR's
28
+ // checks at the remote head still cover every line of code.
29
+ //
30
+ // `pins` — downloads each `*_VERSION` + `*_SHA256` pinned tool the files name and checks
31
+ // the hash, so a version-only Renovate bump goes red in its own PR (`pins.ts`).
21
32
 
22
33
  import { spawnSync, type SpawnSyncReturns } from "node:child_process";
23
34
  import * as fs from "node:fs";
24
35
  import * as os from "node:os";
25
36
  import * as path from "node:path";
26
37
 
27
- import { readBkitConfig } from "../../shared/settings.js";
38
+ import { readBkitConfig, type BkitConfig } from "../../shared/settings.js";
28
39
  import {
29
40
  CommandError,
30
41
  commitMessage,
@@ -36,7 +47,14 @@ import {
36
47
  type CommandSpec,
37
48
  type RunContext,
38
49
  } from "../lib.js";
39
- import { changedOutside } from "../workflow/ledgers.js";
50
+ import {
51
+ bookPathspecs,
52
+ changedOutside,
53
+ checkOnlyBookkeeping,
54
+ globPathspecs,
55
+ } from "../workflow/ledgers.js";
56
+ import { pins } from "./pins.js";
57
+ import { hasVerifiedIncrement, runPushGate } from "./push-gate.js";
40
58
 
41
59
  /** Exit code: slop-scan could not be started (not installed, not executable). */
42
60
  export const EXIT_SLOP_UNAVAILABLE = 3;
@@ -124,6 +142,93 @@ export function readSummary(raw: string): Summary | { missing: string } {
124
142
  export const gateFails = (s: Summary): boolean =>
125
143
  s.netFindingCount > 0 || s.netRepoScore > SCORE_EPSILON;
126
144
 
145
+ /** A net-new or worsened finding, named for the log and the JSON output. */
146
+ export interface SlopFinding {
147
+ status: "added" | "worsened";
148
+ path: string | null;
149
+ line: number | null;
150
+ ruleId: string;
151
+ message: string;
152
+ }
153
+
154
+ /** The fields of a `slop-scan delta --json` change the gate reads; any may be absent. */
155
+ interface DeltaChange {
156
+ status?: unknown;
157
+ path?: unknown;
158
+ ruleId?: unknown;
159
+ base?: DeltaSnapshot | null;
160
+ head?: DeltaSnapshot | null;
161
+ }
162
+ interface DeltaSnapshot {
163
+ message?: unknown;
164
+ primaryLocation?: { line?: unknown } | null;
165
+ locations?: { line?: unknown }[];
166
+ }
167
+
168
+ const asArray = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
169
+
170
+ function toFinding(status: SlopFinding["status"], c: DeltaChange): SlopFinding {
171
+ const loc = c.head?.primaryLocation ?? c.head?.locations?.[0];
172
+ return {
173
+ status,
174
+ path: typeof c.path === "string" ? c.path : null,
175
+ line: typeof loc?.line === "number" ? loc.line : null,
176
+ ruleId: String(c.ruleId),
177
+ message: typeof c.head?.message === "string" ? c.head.message : "",
178
+ };
179
+ }
180
+
181
+ /**
182
+ * The net-new and worsened findings in a `slop-scan delta --json` report. Grouped by file
183
+ * and rule: a group that resolves as many as it adds is a line shift and is dropped; in a
184
+ * group that adds more, each resolved finding cancels one added finding with the same
185
+ * message, and the rest are listed. Empty when the report carries no change lists.
186
+ */
187
+ export function netNewFindings(raw: string): SlopFinding[] {
188
+ const parsed = parseJson(raw);
189
+ if (!parsed.ok) return [];
190
+ const report = parsed.value as { paths?: unknown; repoChanges?: unknown } | null;
191
+ const changes = [
192
+ ...asArray(report?.paths).flatMap((p) => asArray((p as { changes?: unknown })?.changes)),
193
+ ...asArray(report?.repoChanges),
194
+ ] as DeltaChange[];
195
+
196
+ const groups = new Map<string, { added: DeltaChange[]; resolved: DeltaChange[] }>();
197
+ const findings: SlopFinding[] = [];
198
+ for (const c of changes) {
199
+ if (c.status === "worsened") findings.push(toFinding("worsened", c));
200
+ if (c.status !== "added" && c.status !== "resolved") continue;
201
+ const key = `${String(c.path)}\0${String(c.ruleId)}`;
202
+ const group = groups.get(key) ?? { added: [], resolved: [] };
203
+ groups.set(key, group);
204
+ group[c.status].push(c);
205
+ }
206
+ for (const { added, resolved } of groups.values()) {
207
+ if (added.length <= resolved.length) continue;
208
+ const left = [...added];
209
+ for (const r of resolved) {
210
+ const i = left.findIndex((a) => a.head?.message === r.base?.message);
211
+ if (i >= 0) left.splice(i, 1);
212
+ }
213
+ findings.push(...left.map((c) => toFinding("added", c)));
214
+ }
215
+ return findings;
216
+ }
217
+
218
+ /** One log line per finding: status, `path:line`, rule, message. */
219
+ export function formatFindings(findings: SlopFinding[]): string[] {
220
+ if (findings.length === 0) {
221
+ return ["slop-scan's report names no single net-new finding; the rise is spread across files."];
222
+ }
223
+ return [
224
+ "Net-new / worsened findings:",
225
+ ...findings.map((f) => {
226
+ const where = `${f.path ?? "(repo)"}${f.line === null ? "" : `:${f.line}`}`;
227
+ return ` ${f.status.padEnd(8)} ${where} ${f.ruleId} ${f.message}`.trimEnd();
228
+ }),
229
+ ];
230
+ }
231
+
127
232
  /** Whether a failed slop-scan run means it never started, rather than that it failed. */
128
233
  function couldNotRun(res: ReturnType<typeof spawnSync>, viaNpx: boolean): boolean {
129
234
  if ((res.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return true;
@@ -171,7 +276,14 @@ function slop(ctx: RunContext): Promise<number> | number {
171
276
  if (!top.ok) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${ctx.cwd}`);
172
277
  const given = typeof ctx.flags.base === "string" ? ctx.flags.base : undefined;
173
278
  const baseRef = resolveBaseRef(ctx.cwd, given || process.env.SLOP_BASE_REF || undefined);
174
- const empty = { added: 0, resolved: 0, worsened: 0, netFindingCount: 0, netScore: 0 };
279
+ const empty = {
280
+ added: 0,
281
+ resolved: 0,
282
+ worsened: 0,
283
+ netFindingCount: 0,
284
+ netScore: 0,
285
+ findings: [],
286
+ };
175
287
 
176
288
  const sha = runGit(ctx.cwd, ["rev-parse", "--verify", "--quiet", `${baseRef}^{commit}`]);
177
289
  if (!sha.ok) {
@@ -252,8 +364,9 @@ function slop(ctx: RunContext): Promise<number> | number {
252
364
  `net findings ${s.netFindingCount}, net score ${s.netRepoScore.toFixed(2)}`,
253
365
  );
254
366
  const failed = gateFails(s);
367
+ const findings = netNewFindings(stdout);
255
368
  for (const line of failed
256
- ? FAIL_GUIDANCE
369
+ ? [...formatFindings(findings), ...FAIL_GUIDANCE]
257
370
  : ["OK — no net-new or worsened findings (baseline line-shifts ignored)."]) {
258
371
  ctx.log(line);
259
372
  }
@@ -267,6 +380,7 @@ function slop(ctx: RunContext): Promise<number> | number {
267
380
  worsened: s.worsenedCount,
268
381
  netFindingCount: s.netFindingCount,
269
382
  netScore: s.netRepoScore,
383
+ findings,
270
384
  });
271
385
  return failed ? EXIT.NO : EXIT.OK;
272
386
  }, removeWorktree);
@@ -382,16 +496,21 @@ function prose(ctx: RunContext): number {
382
496
  ctx.emit({ passed: true, skipped, files: 0 });
383
497
  return EXIT.OK;
384
498
  };
499
+ const unavailable = (skipped: string, message: string) => {
500
+ ctx.log(message);
501
+ ctx.emit({ passed: false, skipped, files: 0 });
502
+ return EXIT_VALE_FAILED;
503
+ };
385
504
  if (!onPath("vale")) {
386
- return skip(
505
+ return unavailable(
387
506
  "vale-missing",
388
- "vale not installed - skipping prose lint (install vale, then run vale sync, to enable)",
507
+ "vale not installed - prose lint unavailable (install vale, then run vale sync)",
389
508
  );
390
509
  }
391
510
  if (!restoreWriteGood(ctx)) {
392
- return skip(
511
+ return unavailable(
393
512
  "write-good-missing",
394
- "WARNING - PROSE LINT SKIPPED: vale is installed but .vale/styles/write-good could not be restored (main-worktree copy and vale sync both failed). The prose gate is NOT enforcing here - run: vale sync",
513
+ "PROSE LINT UNAVAILABLE: vale is installed but .vale/styles/write-good could not be restored (main-worktree copy and vale sync both failed). Run: vale sync",
395
514
  );
396
515
  }
397
516
  const files = proseFiles(ctx.cwd, globs);
@@ -428,9 +547,19 @@ function skipToken(ctx: RunContext): number {
428
547
  // min-push
429
548
  // ---------------------------------------------------------------------------
430
549
 
431
- /** `bkit.minPushPaths` as git pathspecs: `:(glob)` unless an entry carries its own magic. */
432
- export const minPushPathspecs = (paths: readonly string[]): string[] =>
433
- paths.map((p) => (p.startsWith(":") ? p : `:(glob)${p}`));
550
+ /**
551
+ * The min-push pathspecs: ship's `pr` bookkeeping allow-list for every month and feature
552
+ * (the same list `bkit ci bookkeeping-push` and the ship gate accept untested, including
553
+ * `bkit.testing.ciSkipPaths`), the plans tree bkit's workflows write, and whatever the repo
554
+ * adds in `bkit.testing.minPushPaths` (`:(glob)` unless an entry carries its own magic).
555
+ * The engine hardcodes no consumer file: the floor is what bkit itself writes.
556
+ */
557
+ export function minPushPathspecs(cfg: Pick<BkitConfig, "minPushPaths" | "ciSkipPaths">): string[] {
558
+ return [
559
+ ...bookPathspecs("*", "*", "pr", cfg.ciSkipPaths),
560
+ ...globPathspecs(["docs/plans/**", ...cfg.minPushPaths]),
561
+ ];
562
+ }
434
563
 
435
564
  /** Where a pushed commit's range starts: its merge-base with origin/dev, else origin/main. */
436
565
  export function pushBase(cwd: string, sha: string): string | null {
@@ -448,15 +577,21 @@ function minPush(ctx: RunContext): number {
448
577
  const given = ctx.flags.ref;
449
578
  const refs = Array.isArray(given) && given.length > 0 ? given.map(String) : ["HEAD"];
450
579
  const baseFlag = typeof ctx.flags.base === "string" && ctx.flags.base ? ctx.flags.base : null;
451
- const paths = readBkitConfig(top.stdout).minPushPaths;
452
- const specs = minPushPathspecs(paths);
580
+ const paths = minPushPathspecs(readBkitConfig(top.stdout));
581
+ const updates = ctx.flags.update;
582
+ if (Array.isArray(updates) && updates.length > 0) {
583
+ if ((Array.isArray(given) && given.length > 0) || baseFlag) {
584
+ throw new CommandError(EXIT.USAGE, "--update cannot be combined with --ref or --base");
585
+ }
586
+ return minPushUpdates(ctx, top.stdout, updates.map(String), paths);
587
+ }
453
588
 
454
589
  const changed = new Set<string>();
455
590
  const outside = new Set<string>();
456
591
  for (const ref of refs) {
457
592
  const sha = git(ctx.cwd, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
458
593
  const base = sha ? (baseFlag ?? pushBase(ctx.cwd, sha)) : null;
459
- const diff = sha && base ? changedOutside(top.stdout, base, sha, specs) : null;
594
+ const diff = sha && base ? changedOutside(top.stdout, base, sha, paths) : null;
460
595
  if (!diff?.ok) {
461
596
  const why = !sha
462
597
  ? `cannot read commit '${ref}'`
@@ -482,9 +617,6 @@ function minPush(ctx: RunContext): number {
482
617
  });
483
618
  return code;
484
619
  };
485
- if (paths.length === 0) {
486
- return result("no-paths", EXIT.NO, "bkit.minPushPaths is empty — not a min push");
487
- }
488
620
  if (changed.size === 0) {
489
621
  return result("no-changes", EXIT.NO, "the push changes no files — not proven a min push");
490
622
  }
@@ -499,12 +631,132 @@ function minPush(ctx: RunContext): number {
499
631
  return result(null, EXIT.OK, `all ${changed.size} changed files match min-push paths`);
500
632
  }
501
633
 
634
+ function minPushUpdates(ctx: RunContext, cwd: string, updates: string[], paths: string[]): number {
635
+ const changed = new Set<string>();
636
+ const outside = new Set<string>();
637
+ let unknown = false;
638
+ let failed = false;
639
+ for (const update of updates) {
640
+ const pair = /^([0-9a-f]{40}|[0-9a-f]{64}):([0-9a-f]{40}|[0-9a-f]{64})$/.exec(update);
641
+ if (!pair) throw new CommandError(EXIT.USAGE, "--update requires <old-sha>:<new-sha>");
642
+ const oldSha = pair[1]!;
643
+ const newSha = pair[2]!;
644
+ const isNew = /^0+$/.test(oldSha);
645
+ if (!isNew && !runGit(cwd, ["merge-base", "--is-ancestor", oldSha, newSha]).ok) {
646
+ failed = true;
647
+ unknown = true;
648
+ continue;
649
+ }
650
+ const increment = isNew ? null : changedOutside(cwd, oldSha, newSha, paths);
651
+ const base = pushBase(cwd, newSha);
652
+ const whole = base ? changedOutside(cwd, base, newSha, paths) : null;
653
+ if (hasVerifiedIncrement(cwd, oldSha, newSha, paths)) {
654
+ if (increment?.ok) for (const file of increment.changed) changed.add(file);
655
+ ctx.log(`${oldSha}..${newSha}: covered by a successful full push gate`);
656
+ continue;
657
+ }
658
+ if (whole?.ok) {
659
+ for (const file of whole.changed) changed.add(file);
660
+ for (const file of whole.outside) outside.add(file);
661
+ if (
662
+ whole.changed.length > 0 &&
663
+ whole.outside.length === 0 &&
664
+ (isNew || (increment?.ok && increment.changed.length > 0))
665
+ )
666
+ continue;
667
+ } else unknown = true;
668
+ failed = true;
669
+ }
670
+ const reason = !failed ? null : unknown ? "unknown" : outside.size ? "outside" : "no-changes";
671
+ ctx.emit({
672
+ minPush: !failed,
673
+ reason,
674
+ changed: changed.size,
675
+ outside: [...outside].sort(),
676
+ paths,
677
+ });
678
+ ctx.log(
679
+ failed
680
+ ? "push is not covered by minimum paths or verified full-gate proof"
681
+ : "every update qualifies for the minimum push gate",
682
+ );
683
+ return !failed ? EXIT.OK : unknown ? EXIT_RANGE_UNKNOWN : EXIT.NO;
684
+ }
685
+
686
+ // ---------------------------------------------------------------------------
687
+ // bookkeeping-push
688
+ // ---------------------------------------------------------------------------
689
+
690
+ /** A feature branch, as the workflows name one; the FID is the slug after `feat/`. */
691
+ const FEAT_BRANCH = /^feat\/([a-z0-9][a-z0-9-]*)$/;
692
+
693
+ function bookkeepingPush(ctx: RunContext): number {
694
+ const top = runGit(ctx.cwd, ["rev-parse", "--show-toplevel"]);
695
+ if (!top.ok) throw new CommandError(EXIT.USAGE, `not inside a git repository: ${ctx.cwd}`);
696
+ const from = String(ctx.flags.from);
697
+ const toRef = typeof ctx.flags.to === "string" && ctx.flags.to !== "" ? ctx.flags.to : "HEAD";
698
+ const branch =
699
+ typeof ctx.flags.branch === "string" && ctx.flags.branch !== ""
700
+ ? ctx.flags.branch
701
+ : (git(ctx.cwd, ["rev-parse", "--abbrev-ref", "HEAD"]) ?? "");
702
+ const result = (reason: string | null, code: number, outside: string[], message: string) => {
703
+ ctx.log(message);
704
+ ctx.emit({ bookkeepingPush: reason === null, reason, branch, from, to: toRef, outside });
705
+ return code;
706
+ };
707
+ const fid = FEAT_BRANCH.exec(branch)?.[1];
708
+ if (fid === undefined) {
709
+ return result(
710
+ "not-a-feature-branch",
711
+ EXIT.NO,
712
+ [],
713
+ `'${branch}' is not a feat/{FID} branch — not a bookkeeping push`,
714
+ );
715
+ }
716
+ if (/^0+$/.test(from)) {
717
+ return result(
718
+ "no-remote-head",
719
+ EXIT.NO,
720
+ [],
721
+ "the remote holds no head for this branch — nothing to carry CI forward from",
722
+ );
723
+ }
724
+ // Every plan month: the hook knows the branch, not the run's `{YYYYMM}`.
725
+ const check = checkOnlyBookkeeping(top.stdout, { month: "*", fid, from, to: toRef });
726
+ switch (check.kind) {
727
+ case "ok":
728
+ return result(null, EXIT.OK, [], `every file changed in ${from}..${toRef} is bookkeeping`);
729
+ case "not-ancestor":
730
+ return result(
731
+ "not-ancestor",
732
+ EXIT.NO,
733
+ [],
734
+ `${from} is not an ancestor of ${toRef} — the push rewrites the PR head`,
735
+ );
736
+ case "outside":
737
+ return result(
738
+ "outside",
739
+ EXIT.NO,
740
+ check.outside,
741
+ `${check.outside.length} changed file(s) outside the bookkeeping allow-list (first: ${check.outside[0]})`,
742
+ );
743
+ case "unknown-commit":
744
+ throw new CommandError(EXIT_RANGE_UNKNOWN, `cannot read commit '${check.ref}'`);
745
+ case "diff-failed":
746
+ throw new CommandError(
747
+ EXIT_RANGE_UNKNOWN,
748
+ `'git diff' failed for ${from}..${toRef}: ${check.stderr}`,
749
+ );
750
+ }
751
+ }
752
+
502
753
  export const ciCommand: CommandSpec = {
503
754
  noun: "ci",
504
755
  summary: "Gates CI and the git hooks run.",
505
756
  verbs: {
506
757
  slop: {
507
758
  summary: "Fail when the working tree adds or worsens slop on net against a base ref.",
759
+ use: "by-hand",
508
760
  flags: [
509
761
  {
510
762
  name: "base",
@@ -523,6 +775,8 @@ export const ciCommand: CommandSpec = {
523
775
  worsened: "findings worsened",
524
776
  netFindingCount: "net change in finding count — gated on",
525
777
  netScore: "net change in slop score — gated on",
778
+ findings:
779
+ "net-new and worsened findings ({status, path, line, ruleId, message}); line shifts dropped",
526
780
  },
527
781
  exitCodes: {
528
782
  [EXIT_SLOP_UNAVAILABLE]: "slop-scan could not run (not installed or not executable)",
@@ -533,7 +787,8 @@ export const ciCommand: CommandSpec = {
533
787
  },
534
788
  prose: {
535
789
  summary:
536
- "Run Vale over the markdown files the globs select; skip when vale is not installed.",
790
+ "Run Vale over the markdown files the globs select; fail when Vale or required styles are unavailable.",
791
+ use: "by-hand",
537
792
  flags: [
538
793
  {
539
794
  name: "glob",
@@ -543,7 +798,7 @@ export const ciCommand: CommandSpec = {
543
798
  },
544
799
  ],
545
800
  output: {
546
- passed: "false when vale reported alerts",
801
+ passed: "false when vale reported alerts or required tooling is unavailable",
547
802
  skipped: "vale-missing | write-good-missing | no-files when nothing was linted, else null",
548
803
  files: "how many files vale linted",
549
804
  },
@@ -554,6 +809,7 @@ export const ciCommand: CommandSpec = {
554
809
  },
555
810
  "skip-token": {
556
811
  summary: "Whether a commit message carries a GitHub skip-CI token ([skip ci] and kin).",
812
+ use: "by-hand",
557
813
  flags: [{ name: "ref", type: "string", help: "commit to read (default HEAD)" }],
558
814
  output: {
559
815
  ref: "the ref read",
@@ -564,7 +820,8 @@ export const ciCommand: CommandSpec = {
564
820
  },
565
821
  "min-push": {
566
822
  summary:
567
- "Exit 0 when every file a push changes matches bkit.minPushPaths (the pre-push light gate).",
823
+ "Exit 0 when every file a push changes is one bkit writes or bkit.testing.minPushPaths / ciSkipPaths adds (the pre-push light gate).",
824
+ use: "by-hand",
568
825
  flags: [
569
826
  {
570
827
  name: "ref",
@@ -573,18 +830,95 @@ export const ciCommand: CommandSpec = {
573
830
  help: "a pushed commit (default HEAD); its range starts at its merge-base with origin/dev, else origin/main",
574
831
  },
575
832
  { name: "base", type: "string", help: "start every range here instead" },
833
+ {
834
+ name: "update",
835
+ type: "string",
836
+ repeatable: true,
837
+ help: "actual <old-sha>:<new-sha> push update; permits verified bookkeeping increments; excludes --ref and --base",
838
+ },
576
839
  ],
577
840
  output: {
578
- minPush: "true when every changed file matches bkit.minPushPaths",
579
- reason: "null when a min push; else no-paths | no-changes | outside | unknown",
841
+ minPush: "true when every changed file matches a min-push path",
842
+ reason: "null when a min push; else no-changes | outside | unknown",
580
843
  changed: "files the push changes, across every ref",
581
844
  outside: "the changed files no min-push path matches",
582
- paths: "bkit.minPushPaths as read",
845
+ paths:
846
+ "the min-push pathspecs in force: ship's pr bookkeeping allow-list (with bkit.testing.ciSkipPaths), docs/plans/**, bkit.testing.minPushPaths",
583
847
  },
584
848
  exitCodes: {
585
849
  [EXIT_RANGE_UNKNOWN]: "a pushed commit, its base, or its git diff could not be read",
586
850
  },
587
851
  run: minPush,
588
852
  },
853
+ "push-gate": {
854
+ summary:
855
+ "Run a consumer push gate and record successful full-gate proof for the exact clean commit.",
856
+ use: "by-hand",
857
+ flags: [
858
+ {
859
+ name: "gate",
860
+ type: "string",
861
+ required: true,
862
+ help: "consumer package script to execute",
863
+ },
864
+ ],
865
+ output: { gate: "the script executed", passed: "whether it exited zero" },
866
+ run: (ctx) => {
867
+ const gate = String(ctx.flags.gate);
868
+ const status = runPushGate(ctx.cwd, gate, ctx.log);
869
+ ctx.emit({ gate, passed: status === 0 });
870
+ return status;
871
+ },
872
+ },
873
+ "bookkeeping-push": {
874
+ summary:
875
+ "Exit 0 when a feature-branch push adds bookkeeping only on top of the remote head (ship's --scope=pr allow-list).",
876
+ use: "by-hand",
877
+ flags: [
878
+ {
879
+ name: "from",
880
+ type: "string",
881
+ required: true,
882
+ help: "the head the remote holds (git's remote sha on the hook's stdin)",
883
+ },
884
+ { name: "to", type: "string", help: "the head being pushed (default HEAD)" },
885
+ {
886
+ name: "branch",
887
+ type: "string",
888
+ help: "the feat/{FID} branch (default the current branch); the FID picks the plan log dir",
889
+ },
890
+ ],
891
+ output: {
892
+ bookkeepingPush: "true when every file changed in from..to is bookkeeping",
893
+ reason:
894
+ "null when bookkeeping only; else not-a-feature-branch | no-remote-head | not-ancestor | outside",
895
+ branch: "the branch read",
896
+ from: "the remote head as given",
897
+ to: "the pushed head as given",
898
+ outside: "the changed files outside the allow-list",
899
+ },
900
+ exitCodes: {
901
+ [EXIT_RANGE_UNKNOWN]: "a commit or the git diff could not be read",
902
+ },
903
+ run: bookkeepingPush,
904
+ },
905
+ pins: {
906
+ summary:
907
+ "Download each *_VERSION + *_SHA256 pinned tool in the files and fail when a hash differs.",
908
+ use: "by-hand",
909
+ flags: [
910
+ {
911
+ name: "file",
912
+ type: "string",
913
+ repeatable: true,
914
+ help: "a file holding pins (shell `X=v`, `export X=v`, Dockerfile `ARG X=v`)",
915
+ },
916
+ ],
917
+ output: {
918
+ passed: "false when any pin failed",
919
+ pins: "one row per pin ({file, tool, version, url, status, expected, actual, error}); status ok | skipped (no download) | mismatch | unreachable | missing-sha256 | missing-version | unresolved-url | ambiguous-url",
920
+ },
921
+ run: (ctx) => pins(ctx),
922
+ },
589
923
  },
590
924
  };