@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,748 @@
1
+ // bkit challenge merge — fold the build challenge reports into the plan.
2
+ //
3
+ // Each reviewer writes its findings as task blocks (`<!-- bkit:task N start -->`) under
4
+ // `## Findings Log`, read through `parsePlanBlocks` like the plan's own tasks. The merge
5
+ // dedupes them by location, drops the ones an earlier Decision Pause accepted, writes the
6
+ // CRITICAL / HIGH / MEDIUM ones into the plan as task blocks in new last groups (at most
7
+ // `bkit.workflows.tasks.maxPerGroup` tasks and `maxTestsPerGroup` tests each) and writes each LOW one
8
+ // as a deferral row. Task numbers carry on from the highest in the plan, so they stay
9
+ // unique. A finding at the location and severity of an earlier task that is still open
10
+ // reruns that task (its Round value gains this round) rather than adding a twin; one whose
11
+ // earlier task is done from an earlier round is a new task. It then names the route:
12
+ // `fix` (run the tasks: every one is fixable, in any round), `pause` (a task is not
13
+ // fixable: ask the owner) or `none`. More than `maxChallengeTasks` new tasks in one merge
14
+ // writes nothing and pauses. The plan is checked in memory before it is written, so a
15
+ // refused merge leaves every file as it was. A re-run with the same reports appends
16
+ // nothing.
17
+ //
18
+ // bkit challenge gate — size the run's diff before the reviewers start. A small change
19
+ // (under CHALLENGE_SMALL lines and files, `docs/plans/**` excluded) runs the security
20
+ // reviewer alone; a large one runs both. With the default base it fetches origin dev
21
+ // first; offline it measures against the local origin/dev. Each pass writes a
22
+ // `challenge-gate` status row.
23
+
24
+ import * as fs from "node:fs";
25
+ import * as path from "node:path";
26
+
27
+ import { appendLine, statusTimestamp } from "../../ledgers/status.js";
28
+ import { CommandError, DEV, EXIT, git, runGit, type CommandSpec } from "../lib.js";
29
+ import { DIFF_BASE, EXIT_BASE, diffNumstat, type DiffStat } from "./context.js";
30
+ import { parseDecisionItems } from "./decisions.js";
31
+ import { EXIT_ROW_REFUSED, EXIT_STAGE, appendLedgerRows } from "./ledgers.js";
32
+ import { derivedTestMatrix, parsePlanBlocks, type PlanTaskBlock } from "./plan-blocks.js";
33
+ import { readBkitConfig, type TaskCaps } from "../../shared/settings.js";
34
+ import { grantCount } from "./counters.js";
35
+ import { checkPlanText, planCaps, readTestFirst } from "./tests.js";
36
+ import { ledgerRows } from "./workflows.js";
37
+
38
+ /**
39
+ * The most tasks one merge writes: four full groups. More fresh findings than this write
40
+ * nothing and route to the Decision Pause, where the owner picks what to fix.
41
+ */
42
+ export const maxChallengeTasks = (caps: TaskCaps) => 4 * caps.maxPerGroup;
43
+
44
+ /** Exit code: a `--report` file does not exist. */
45
+ export const EXIT_NO_REPORT = 21;
46
+ /** Exit code: a report is not in task-block form. */
47
+ export const EXIT_OLD_FORMAT = 22;
48
+ /** Exit code: the merged plan fails the plan check; nothing was written. */
49
+ export const EXIT_PLAN_CHECK = 23;
50
+
51
+ /** A diff under both limits is small: the security reviewer (challenge-2) runs alone. */
52
+ export const CHALLENGE_SMALL = { lines: 300, files: 10 } as const;
53
+
54
+ export interface ChallengeGate {
55
+ size: "small" | "large";
56
+ /** The reviewers Step 10 runs. */
57
+ agents: string[];
58
+ /** Whether challenge-1 is left out. */
59
+ skipped: boolean;
60
+ }
61
+
62
+ /** Size a diff against `limit`: small when it changes fewer lines and fewer files. */
63
+ export function challengeGate(
64
+ stat: Pick<DiffStat, "linesChanged" | "filesChanged">,
65
+ limit: { lines: number; files: number } = CHALLENGE_SMALL,
66
+ ): ChallengeGate {
67
+ const small = stat.linesChanged < limit.lines && stat.filesChanged < limit.files;
68
+ return small
69
+ ? { size: "small", skipped: true, agents: ["bkit-build-challenge-2"] }
70
+ : {
71
+ size: "large",
72
+ skipped: false,
73
+ agents: ["bkit-build-challenge-1", "bkit-build-challenge-2"],
74
+ };
75
+ }
76
+
77
+ export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
78
+ const SEVERITY_ORDER: readonly Severity[] = ["CRITICAL", "HIGH", "MEDIUM", "LOW"];
79
+ const rank = (s: Severity) => SEVERITY_ORDER.indexOf(s);
80
+
81
+ export interface Finding {
82
+ severity: Severity;
83
+ /** `mechanical` | `architectural`, as the reviewer wrote it; absent when not given. */
84
+ cls?: string;
85
+ fixable: boolean;
86
+ /** Repo-relative path and first line number: `src/a.ts:10`. */
87
+ location: string;
88
+ title: string;
89
+ doneWhen: string;
90
+ /** The TEST FIRST entries as written, one per planned test. */
91
+ tests: string[];
92
+ }
93
+
94
+ /** A finding block's line `**Severity:** … · **Class:** … · **Fixable:** … · **Location:** …`. */
95
+ const META = /\*\*(Severity|Class|Fixable|Location|Round):\*\*/g;
96
+
97
+ /** The Severity / Class / Fixable / Location / Round values of a task block's meta line. */
98
+ function metaFields(text: string): Map<string, string> {
99
+ const values = new Map<string, string>();
100
+ for (const line of text.split("\n")) {
101
+ const hits = [...line.matchAll(META)];
102
+ hits.forEach((h, i) => {
103
+ const value = line.slice(h.index + h[0].length, hits[i + 1]?.index);
104
+ values.set(h[1]!, value.trim().replace(/[\s·]+$/, ""));
105
+ });
106
+ }
107
+ return values;
108
+ }
109
+
110
+ /** A task block's TEST FIRST entries, each the sub-bullet's text as written. */
111
+ function testEntries(block: PlanTaskBlock): string[] {
112
+ const lines = block.text.split("\n");
113
+ const at = (line: number) =>
114
+ lines[line - block.line]!.trim()
115
+ .replace(/^- /, "")
116
+ .replace(/^\*\*TEST FIRST:\*\*\s*/, "");
117
+ const tf = block.testFirst;
118
+ if (tf === undefined) return [];
119
+ return [...tf.tests.map((t) => t.line), ...tf.malformed].sort((a, b) => a - b).map(at);
120
+ }
121
+
122
+ /** `path:line` from a location value, the path repo-relative and normalised; null when none. */
123
+ export function normalizeLocation(raw: string, cwd: string): string | null {
124
+ const m = /`?([^`\s]+?):(\d+)/.exec(raw);
125
+ if (!m) return null;
126
+ let p = m[1]!.replace(/\\/g, "/");
127
+ if (path.isAbsolute(p)) p = path.relative(cwd, p).split(path.sep).join("/");
128
+ p = path.posix.normalize(p).replace(/^\.\//, "");
129
+ return `${p}:${Number(m[2])}`;
130
+ }
131
+
132
+ /** The header line `{name}: value` above `<!-- verdict:end -->`, or undefined. */
133
+ const headerValue = (text: string, name: string) =>
134
+ new RegExp(`^${name}:\\s*(\\S+)`, "m").exec(text.split("<!-- verdict:end -->")[0]!)?.[1];
135
+
136
+ /** The `## Findings Log` section of a report and its first line's number (1-based); "" when none. */
137
+ function findingsLog(text: string): { body: string; line: number } {
138
+ const lines = text.split("\n");
139
+ const start = lines.findIndex((l) => /^## Findings Log\b/.test(l));
140
+ if (start < 0) return { body: "", line: 0 };
141
+ const end = lines.findIndex((l, i) => i > start && /^## /.test(l));
142
+ return { body: lines.slice(start + 1, end < 0 ? undefined : end).join("\n"), line: start + 2 };
143
+ }
144
+
145
+ /** The group wrapper a Findings Log gets when the reviewer wrote task blocks only. */
146
+ const WRAP = ["<!-- bkit:group 1 start -->", "### TASK GROUP 1: Findings"];
147
+
148
+ /**
149
+ * One report's findings: each task block under `## Findings Log` (read through
150
+ * `parsePlanBlocks`; a log with no group marker is read as one group) with its
151
+ * `Severity`, `Fixable` and `Location` line and its DONE WHEN field. Refused (exit 22):
152
+ * a header naming findings with no task block, a block format error (old `**Task N:**`
153
+ * task lines included), or a block missing one of those fields.
154
+ */
155
+ export function parseFindings(text: string, source: string, cwd: string): Finding[] {
156
+ const log = findingsLog(text);
157
+ const wrapped = !/<!--\s*bkit:group\s/.test(log.body);
158
+ const body = wrapped ? [...WRAP, log.body, "<!-- bkit:group 1 end -->"].join("\n") : log.body;
159
+ const blocks = parsePlanBlocks(body);
160
+ const fileLine = (line: number) => log.line + line - 1 - (wrapped ? WRAP.length : 0);
161
+ const notBlocks = (why: string) =>
162
+ new CommandError(
163
+ EXIT_OLD_FORMAT,
164
+ `${source}: ${why} — the report is not in task-block form; re-run the challenge`,
165
+ );
166
+ const error = blocks.errors[0];
167
+ if (error !== undefined) throw notBlocks(`line ${fileLine(error.line)}: ${error.message}`);
168
+ const verdict = headerValue(text, "Verdict");
169
+ const failures = Number(headerValue(text, "Failures") ?? 0);
170
+ if (blocks.tasks.length === 0 && (verdict !== "PASS" || failures > 0))
171
+ throw notBlocks(`verdict ${verdict ?? "missing"} but no task block under ## Findings Log`);
172
+ return blocks.tasks.map((block) => {
173
+ const values = metaFields(block.text);
174
+ const refuse = (why: string) =>
175
+ new CommandError(EXIT_OLD_FORMAT, `${source}: finding TASK ${block.task} ${why}`);
176
+ const severity = values.get("Severity")?.split(/\s/)[0];
177
+ if (!SEVERITY_ORDER.includes(severity as Severity))
178
+ throw refuse("has no **Severity:** CRITICAL|HIGH|MEDIUM|LOW");
179
+ const fixable = values.get("Fixable")?.split(/\s/)[0];
180
+ if (fixable !== "true" && fixable !== "false") throw refuse("has no **Fixable:** true|false");
181
+ const location = normalizeLocation(values.get("Location") ?? "", cwd);
182
+ if (location === null) throw refuse("has no **Location:** path:line");
183
+ const doneWhen = block.doneWhen ?? "";
184
+ if (doneWhen === "") throw refuse("has no **DONE WHEN:**");
185
+ const cls = values.get("Class")?.split(/\s/)[0];
186
+ return {
187
+ severity: severity as Severity,
188
+ ...(cls ? { cls } : {}),
189
+ fixable: fixable === "true",
190
+ location,
191
+ title: block.title || `Challenge finding at ${location}`,
192
+ doneWhen,
193
+ tests: testEntries(block),
194
+ };
195
+ });
196
+ }
197
+
198
+ /**
199
+ * The reports' findings as one list, deduped by location: the worse severity's
200
+ * finding wins, and it is not fixable when either says so. Findings at an accepted
201
+ * location are dropped and counted.
202
+ */
203
+ export function mergeFindings(
204
+ reports: Finding[][],
205
+ accepted: ReadonlySet<string>,
206
+ ): { findings: Finding[]; dropped: number } {
207
+ const byLocation = new Map<string, Finding>();
208
+ for (const f of reports.flat()) {
209
+ const prior = byLocation.get(f.location);
210
+ if (prior === undefined) {
211
+ byLocation.set(f.location, f);
212
+ continue;
213
+ }
214
+ const worse = rank(f.severity) < rank(prior.severity) ? f : prior;
215
+ byLocation.set(f.location, { ...worse, fixable: prior.fixable && f.fixable });
216
+ }
217
+ const all = [...byLocation.values()];
218
+ const findings = all.filter((f) => !accepted.has(f.location));
219
+ return { findings, dropped: all.length - findings.length };
220
+ }
221
+
222
+ /**
223
+ * Locations named in a `Decision: Accept` item of any `build-decision-*.md` in `logDir`, the
224
+ * decision read by `parseDecisionItems` (so `Decision: A) Accept …` counts). An
225
+ * `Accept (assumed)` counts too, so the next round does not raise it again; the build summary
226
+ * and ship report it as assumed.
227
+ */
228
+ export function acceptedLocations(logDir: string, cwd: string): Set<string> {
229
+ const out = new Set<string>();
230
+ const files = fs.existsSync(logDir)
231
+ ? fs.readdirSync(logDir).filter((f) => /^build-decision-.*\.md$/.test(f))
232
+ : [];
233
+ for (const file of files) {
234
+ const items = parseDecisionItems(fs.readFileSync(path.join(logDir, file), "utf-8"));
235
+ for (const item of items) {
236
+ if (!/^Accept\b/.test(item.decision ?? "")) continue;
237
+ // `path:line`, the path with or without an extension (`src/a.ts:10`, `Makefile:12`).
238
+ for (const m of item.text.matchAll(/(?<![\w@./-])[\w@./-]*[A-Za-z_][\w@./-]*:\d+/g)) {
239
+ const loc = normalizeLocation(m[0], cwd);
240
+ if (loc !== null) out.add(loc);
241
+ }
242
+ }
243
+ }
244
+ return out;
245
+ }
246
+
247
+ /** One finding's task block. */
248
+ const taskBlock = (n: number, f: Finding, round: number) => [
249
+ `<!-- bkit:task ${n} start -->`,
250
+ `- [ ] **TASK ${n}:** ${f.title}`,
251
+ ` **Severity:** ${f.severity} · ${f.cls ? `**Class:** ${f.cls} · ` : ""}**Fixable:** ${f.fixable} · **Location:** \`${f.location}\` · **Round:** ${round}`,
252
+ ` - **DONE WHEN:** ${f.doneWhen}`,
253
+ " - **TEST FIRST:**",
254
+ ...f.tests.map((e) => ` - ${e}`),
255
+ `<!-- bkit:task ${n} end -->`,
256
+ ];
257
+
258
+ /** The test tier `docs/testing.md` records for a test file's name. */
259
+ const testTier = (file: string) =>
260
+ /\.integration\.test\./.test(file)
261
+ ? "Integration"
262
+ : /\.live\.test\./.test(file)
263
+ ? "@live (golden)"
264
+ : "Unit";
265
+
266
+ /**
267
+ * One `Derived Test Matrix` row per test a finding task appends: the test's own name and
268
+ * file from its `TEST FIRST` entry, its tier from the file's name, and the task number.
269
+ * A file or name holding a `|` would split the row's cells, so it is refused, not written.
270
+ */
271
+ function matrixRows(findings: Finding[], firstTask: number): { rows: string[]; refused: string[] } {
272
+ const refused: string[] = [];
273
+ const rows = findings.flatMap((f, i) =>
274
+ f.tests.map((entry) => {
275
+ const spans = [...entry.matchAll(/`([^`]+)`/g)].map((m) => m[1]!.trim());
276
+ const file = spans[0] ?? "";
277
+ const name = spans[1] ?? entry.replace(/[`|]/g, "").trim();
278
+ if (file.includes("|") || name.includes("|"))
279
+ refused.push(
280
+ `TASK ${firstTask + i} (${f.location}): its TEST FIRST test file or name holds a \`|\`, which breaks the Derived Test Matrix row`,
281
+ );
282
+ return `| ${name} | ${testTier(file)} | \`${file}\` | ${firstTask + i} |`;
283
+ }),
284
+ );
285
+ return { rows, refused };
286
+ }
287
+
288
+ /**
289
+ * The findings as groups of task blocks, numbered from `firstTask` and `firstGroup`: a
290
+ * group closes at `caps.maxPerGroup` tasks, or before a task that would take it past
291
+ * `caps.maxTestsPerGroup` tests.
292
+ */
293
+ function findingGroups(
294
+ findings: Finding[],
295
+ firstTask: number,
296
+ firstGroup: number,
297
+ round: number,
298
+ caps: TaskCaps,
299
+ ): { lines: string[]; tasks: number[] } {
300
+ const chunks: Finding[][] = [];
301
+ let tests = 0;
302
+ for (const f of findings) {
303
+ const n = f.tests.length;
304
+ const open = chunks.at(-1);
305
+ if (
306
+ open === undefined ||
307
+ open.length >= caps.maxPerGroup ||
308
+ tests + n > caps.maxTestsPerGroup
309
+ ) {
310
+ chunks.push([f]);
311
+ tests = n;
312
+ } else {
313
+ open.push(f);
314
+ tests += n;
315
+ }
316
+ }
317
+ const tasks = findings.map((_, i) => firstTask + i);
318
+ let next = firstTask;
319
+ const lines = chunks.flatMap((chunk, g) => [
320
+ ...(g === 0 ? [] : [""]),
321
+ `<!-- bkit:group ${firstGroup + g} start -->`,
322
+ `### TASK GROUP ${firstGroup + g}: Challenge round ${round} findings`,
323
+ ...chunk.flatMap((f) => taskBlock(next++, f, round)),
324
+ `<!-- bkit:group ${firstGroup + g} end -->`,
325
+ ]);
326
+ return { lines, tasks };
327
+ }
328
+
329
+ /** The 1-based plan lines the merge wrote: its plan-check answers for these only. */
330
+ interface Written {
331
+ from: number;
332
+ to: number;
333
+ /** The `Derived Test Matrix` rows it inserted, when the plan has a matrix. */
334
+ rows?: { from: number; to: number };
335
+ /** Matrix rows refused before writing: a test span that would break the table. */
336
+ refused: string[];
337
+ }
338
+
339
+ /**
340
+ * `plan` with the findings written as new groups after its last group (at the end when
341
+ * it has none), tasks numbered from `firstTask`, grouped within `caps`. A plan that
342
+ * carries a `Derived Test Matrix` gains a row per finding test, so the matrix check holds
343
+ * over the appended tasks too.
344
+ */
345
+ export function appendTasks(
346
+ plan: string,
347
+ findings: Finding[],
348
+ round: number,
349
+ firstTask: number,
350
+ caps: TaskCaps,
351
+ ): { text: string; tasks: number[]; written: Written } {
352
+ const blocks = parsePlanBlocks(plan);
353
+ const firstGroup = Math.max(0, ...blocks.groups.map((g) => g.group)) + 1;
354
+ const { lines: block, tasks } = findingGroups(findings, firstTask, firstGroup, round, caps);
355
+ const matrix = derivedTestMatrix(plan);
356
+ const { rows, refused } =
357
+ matrix === null ? { rows: [], refused: [] } : matrixRows(findings, firstTask);
358
+ // The matrix table's last row, or its separator line when it holds none: 0-based index.
359
+ const matrixAt = matrix === null ? -1 : (matrix.rows.at(-1)?.number ?? matrix.line + 1);
360
+ const lines = plan.split("\n");
361
+ if (matrixAt >= 0) lines.splice(matrixAt, 0, ...rows);
362
+ const rowLines =
363
+ matrixAt >= 0 && rows.length > 0
364
+ ? { from: matrixAt + 1, to: matrixAt + rows.length }
365
+ : undefined;
366
+ const last = blocks.groups.at(-1);
367
+ if (last === undefined) {
368
+ const body = lines.join("\n").replace(/\n*$/, "");
369
+ const from = body.split("\n").length + 2;
370
+ return {
371
+ text: `${body}\n\n${block.join("\n")}\n`,
372
+ tasks,
373
+ written: { from, to: from + block.length - 1, rows: rowLines, refused },
374
+ };
375
+ }
376
+ const shift = matrixAt >= 0 && matrixAt <= last.end ? rows.length : 0;
377
+ lines.splice(last.end + shift, 0, "", ...block);
378
+ const from = last.end + shift + 2;
379
+ // Matrix rows below the last group move down by the block and its blank line.
380
+ const moved =
381
+ rowLines !== undefined && shift === 0
382
+ ? { from: rowLines.from + block.length + 1, to: rowLines.to + block.length + 1 }
383
+ : rowLines;
384
+ return {
385
+ text: lines.join("\n"),
386
+ tasks,
387
+ written: { from, to: from + block.length - 1, rows: moved, refused },
388
+ };
389
+ }
390
+
391
+ /**
392
+ * Why the merged `text` may not be written: a refused matrix row, a plan-check problem on
393
+ * the lines the merge wrote (a malformed block, a group or task over its cap, a broken
394
+ * matrix row), or a written task whose TEST FIRST names no test.
395
+ */
396
+ function planProblems(text: string, written: Written, added: number[], caps: TaskCaps): string[] {
397
+ const at = (line: number, r?: { from: number; to: number }) =>
398
+ r !== undefined && line >= r.from && line <= r.to;
399
+ const problems = [
400
+ ...written.refused,
401
+ ...checkPlanText(text, caps)
402
+ .problems.filter((p) => at(p.line, written) || at(p.line, written.rows))
403
+ .map((p) => `line ${p.line}: ${p.message}`),
404
+ ];
405
+ const kinds = readTestFirst(text);
406
+ for (const n of added) {
407
+ const kind = kinds.find((s) => s.task === n)?.kind ?? "missing";
408
+ if (kind !== "test")
409
+ problems.push(`TASK ${n}: its TEST FIRST is ${kind}; every finding names a test`);
410
+ }
411
+ return problems;
412
+ }
413
+
414
+ /** Stable identity shared by the challenge writer and its resolution reader. */
415
+ export const lowDeferralKey = (fid: string, location: string): string =>
416
+ `${fid}-challenge-low-${location.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "")}`.toLowerCase();
417
+
418
+ /** LOW findings as `docs/deferrals.jsonl` rows, keyed by FID and location. */
419
+ export function lowDeferrals(fid: string, findings: Finding[]): Array<Record<string, unknown>> {
420
+ return findings
421
+ .filter((f) => f.severity === "LOW")
422
+ .map((f) => ({
423
+ kind: "deferral",
424
+ key: lowDeferralKey(fid, f.location),
425
+ type: "issue",
426
+ category: "correctness",
427
+ severity: "LOW",
428
+ reason: "low-severity",
429
+ summary: f.title,
430
+ description: `LOW build challenge finding at ${f.location}: ${f.title}. Done when: ${f.doneWhen}`,
431
+ source: f.location,
432
+ references: [fid],
433
+ by: { workflow: "build", step: "build-challenge" },
434
+ }));
435
+ }
436
+
437
+ /** A task the merge appended earlier: its number, tick, the rounds that reported it, its lines. */
438
+ interface MergedTask {
439
+ task: number;
440
+ done: boolean;
441
+ rounds: number[];
442
+ line: number;
443
+ end: number;
444
+ }
445
+
446
+ /** The key a finding and an earlier merged task share: location and severity. */
447
+ const findingKey = (location: string, severity: string) => `${location}|${severity}`;
448
+
449
+ /** Tasks the merge appended earlier, by `findingKey`, in plan order. */
450
+ function mergedTasks(plan: string, cwd: string): Map<string, MergedTask[]> {
451
+ const out = new Map<string, MergedTask[]>();
452
+ for (const t of parsePlanBlocks(plan).tasks) {
453
+ const values = metaFields(t.text);
454
+ const loc = normalizeLocation(values.get("Location") ?? "", cwd);
455
+ const sev = values.get("Severity")?.split(/\s/)[0];
456
+ const rounds = (values.get("Round") ?? "")
457
+ .split(/[\s,]+/)
458
+ .filter((r) => /^\d+$/.test(r))
459
+ .map(Number);
460
+ if (loc === null || sev === undefined || rounds.length === 0) continue;
461
+ const key = findingKey(loc, sev);
462
+ out.set(key, [
463
+ ...(out.get(key) ?? []),
464
+ { task: t.task, done: t.done, rounds, line: t.line, end: t.end },
465
+ ]);
466
+ }
467
+ return out;
468
+ }
469
+
470
+ /** `plan` with `round` added to the `**Round:**` value of each task in `tasks`. */
471
+ function stampRound(plan: string, tasks: MergedTask[], round: number): string {
472
+ const lines = plan.split("\n");
473
+ for (const t of tasks)
474
+ for (let i = t.line - 1; i < t.end; i++)
475
+ lines[i] = lines[i]!.replace(
476
+ /(\*\*Round:\*\*\s*)([\d,\s]*\d)/,
477
+ (_, label: string) => `${label}${[...t.rounds, round].join(", ")}`,
478
+ );
479
+ return lines.join("\n");
480
+ }
481
+
482
+ /** Write `text` to `file` through a temp file renamed over it. */
483
+ function writeAtomic(file: string, text: string): void {
484
+ const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.tmp`);
485
+ fs.writeFileSync(tmp, text);
486
+ fs.renameSync(tmp, file);
487
+ }
488
+
489
+ export const challengeCommand: CommandSpec = {
490
+ noun: "challenge",
491
+ summary:
492
+ "Size the build challenge (gate) and fold its reports into the plan (merge): findings become plan tasks or LOW deferrals.",
493
+ verbs: {
494
+ gate: {
495
+ summary:
496
+ "Size the run's diff ({base}...HEAD, docs/plans/** excluded) and name the reviewers: small runs challenge-2 alone, large runs both. Writes a challenge-gate status row.",
497
+ use: "workflow",
498
+ flags: [
499
+ {
500
+ name: "file",
501
+ type: "string",
502
+ required: true,
503
+ help: "the run's status.jsonl; the challenge-gate row is appended to it",
504
+ },
505
+ {
506
+ name: "base",
507
+ type: "string",
508
+ help: `merge base (default ${DIFF_BASE}, fetched first; a failed fetch is logged, not fatal)`,
509
+ },
510
+ ],
511
+ output: {
512
+ size: `small (under ${CHALLENGE_SMALL.lines} lines and ${CHALLENGE_SMALL.files} files) or large`,
513
+ skipped: "true when challenge-1 is left out",
514
+ agents: "comma-separated reviewers to run",
515
+ linesChanged: "lines added + deleted",
516
+ filesChanged: "files in the diff",
517
+ range: "the range measured ({base}...HEAD)",
518
+ },
519
+ exitCodes: { [EXIT_BASE]: "--base does not name a commit" },
520
+ run: (ctx) => {
521
+ const base = typeof ctx.flags.base === "string" ? ctx.flags.base : DIFF_BASE;
522
+ if (base === DIFF_BASE) {
523
+ const res = runGit(ctx.cwd, ["fetch", "origin", DEV]);
524
+ if (!res.ok)
525
+ ctx.log(
526
+ `git fetch origin dev failed — measuring against the last fetch: ${res.stderr}`,
527
+ );
528
+ }
529
+ if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null)
530
+ throw new CommandError(EXIT_BASE, `--base ${base} does not name a commit (fetch origin)`);
531
+ const range = `${base}...HEAD`;
532
+ const { stat } = diffNumstat(ctx.cwd, range);
533
+ const gate = challengeGate(stat);
534
+ const file = path.resolve(ctx.cwd, String(ctx.flags.file));
535
+ fs.appendFileSync(
536
+ file,
537
+ appendLine({
538
+ type: "challenge-gate",
539
+ workflow: "build",
540
+ at: statusTimestamp(),
541
+ range,
542
+ linesChanged: stat.linesChanged,
543
+ filesChanged: stat.filesChanged,
544
+ size: gate.size,
545
+ limit: { ...CHALLENGE_SMALL },
546
+ agents: gate.agents,
547
+ skipped: gate.skipped,
548
+ }),
549
+ );
550
+ ctx.emit({
551
+ size: gate.size,
552
+ skipped: gate.skipped,
553
+ agents: gate.agents.join(","),
554
+ linesChanged: stat.linesChanged,
555
+ filesChanged: stat.filesChanged,
556
+ range,
557
+ });
558
+ ctx.log(
559
+ `challenge gate: ${gate.size} — ${stat.linesChanged} lines, ${stat.filesChanged} files; run ${gate.agents.join(", ")}`,
560
+ );
561
+ return EXIT.OK;
562
+ },
563
+ },
564
+ merge: {
565
+ summary:
566
+ "Merge the challenge reports' findings into the plan as tasks (LOW → deferral rows); prints the route: fix | pause | none.",
567
+ use: "workflow",
568
+ flags: [
569
+ {
570
+ name: "report",
571
+ type: "string",
572
+ required: true,
573
+ repeatable: true,
574
+ help: "a challenge report (`build-challenge-{1,2}.md`); findings are task blocks under `## Findings Log`",
575
+ },
576
+ {
577
+ name: "plan",
578
+ type: "string",
579
+ required: true,
580
+ help: "the plan file (`{FID}-plan.md`) the tasks are appended to",
581
+ },
582
+ {
583
+ name: "log",
584
+ type: "string",
585
+ required: true,
586
+ help: "the run's log folder `docs/plans/{YYYYMM}/logs/{FID}`; its `build-decision-*.md` accepts drop findings",
587
+ },
588
+ {
589
+ name: "round",
590
+ type: "string",
591
+ required: true,
592
+ help: "challenge round, 1 up to bkit.workflows.build.challenge.maxAttempts, one more full set per allowance-granted row for build.challenge in the log folder's status.jsonl",
593
+ },
594
+ ],
595
+ output: {
596
+ route:
597
+ "fix (tasks to run, every one fixable), pause (a task is not fixable, or more than 4 x `bkit.workflows.tasks.maxPerGroup` new tasks) or none (nothing to run)",
598
+ fixTasks:
599
+ "comma-separated task numbers in `plan` this round runs: every task reopened, then every task appended; empty when none",
600
+ appended: "how many tasks this run wrote",
601
+ reopened:
602
+ "comma-separated numbers of open earlier tasks a finding reported again (same location and severity); this round is added to their **Round:** value; empty when none",
603
+ deferred:
604
+ "`docs/deferrals.jsonl` rows this run wrote (one per LOW finding not already deferred)",
605
+ dropped: "findings at a location a Decision Pause accepted",
606
+ plan: "the plan file the tasks are in (repo-relative as given)",
607
+ round: "the round, as given",
608
+ overflow: `set only when the findings would add more than 4 x \`bkit.workflows.tasks.maxPerGroup\` tasks: how many new CRITICAL / HIGH / MEDIUM findings the Decision Pause must choose from; nothing was written`,
609
+ problems: "on exit 23: why the merged plan failed the plan check",
610
+ },
611
+ exitCodes: {
612
+ [EXIT_STAGE]: "docs/deferrals.jsonl could not be written",
613
+ [EXIT_ROW_REFUSED]: "a LOW deferral row was refused by the ledger check",
614
+ [EXIT_NO_REPORT]: "a --report file does not exist",
615
+ [EXIT_OLD_FORMAT]:
616
+ "a report is not in task-block form: findings but no task block, a block format error, or a block missing Severity, Fixable, Location or DONE WHEN",
617
+ [EXIT_PLAN_CHECK]: "the merged plan fails the plan check; no file was changed",
618
+ },
619
+ run: (ctx) => {
620
+ const round = String(ctx.flags.round);
621
+ const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
622
+ const abs = (p: string) => path.resolve(ctx.cwd, p);
623
+ const rel = (p: string) => path.relative(ctx.cwd, p).split(path.sep).join("/");
624
+ const planArg = String(ctx.flags.plan);
625
+ const logDir = abs(String(ctx.flags.log));
626
+ // Each allowance the owner granted at the used-up limit adds one full set of rounds.
627
+ const grants = grantCount(
628
+ path.join(logDir, "status.jsonl"),
629
+ "build",
630
+ "build.challenge",
631
+ undefined,
632
+ false,
633
+ );
634
+ const maxRounds = readBkitConfig(top).asks["build.challenge"].max * (1 + grants);
635
+ if (!/^[1-9][0-9]*$/.test(round) || Number(round) > maxRounds)
636
+ throw new CommandError(
637
+ EXIT.USAGE,
638
+ `--round must be 1 to ${maxRounds} (bkit.workflows.build.challenge.maxAttempts x (1 + ${grants} allowance(s) granted)), got "${round}"`,
639
+ );
640
+ const roundN = Number(round);
641
+ const fid = path.basename(logDir);
642
+
643
+ const reports = (ctx.flags.report as string[]).map((r) => {
644
+ if (!fs.existsSync(abs(r)))
645
+ throw new CommandError(EXIT_NO_REPORT, `--report ${r} does not exist`);
646
+ return parseFindings(fs.readFileSync(abs(r), "utf-8"), r, ctx.cwd);
647
+ });
648
+ const { findings, dropped } = mergeFindings(reports, acceptedLocations(logDir, ctx.cwd));
649
+ const tasks = findings
650
+ .filter((f) => f.severity !== "LOW")
651
+ .sort((a, b) => rank(a.severity) - rank(b.severity));
652
+ const low = findings.filter((f) => f.severity === "LOW");
653
+
654
+ const planAbs = abs(planArg);
655
+ if (!fs.existsSync(planAbs))
656
+ throw new CommandError(EXIT.USAGE, `--plan ${planArg} does not exist`);
657
+ const before = fs.readFileSync(planAbs, "utf-8");
658
+ // Each finding against the earlier tasks at its location and severity: an open one
659
+ // runs again; a done one from this round is this round's re-run and is left alone;
660
+ // otherwise (none, or every match done in an earlier round: the fix did not hold)
661
+ // the finding is a new task.
662
+ const merged = mergedTasks(before, ctx.cwd);
663
+ const fresh: Finding[] = [];
664
+ const open: Array<{ f: Finding; at: MergedTask }> = [];
665
+ for (const f of tasks) {
666
+ const earlier = merged.get(findingKey(f.location, f.severity)) ?? [];
667
+ const at = earlier.find((t) => !t.done);
668
+ if (at !== undefined) open.push({ f, at });
669
+ else if (!earlier.some((t) => t.rounds.includes(roundN))) fresh.push(f);
670
+ }
671
+
672
+ // More findings than one merge may add: write nothing, the owner picks at the pause.
673
+ const caps = planCaps(ctx.cwd);
674
+ const most = maxChallengeTasks(caps);
675
+ if (fresh.length > most) {
676
+ ctx.emit({
677
+ route: "pause",
678
+ fixTasks: "",
679
+ appended: 0,
680
+ reopened: "",
681
+ deferred: 0,
682
+ dropped,
683
+ overflow: fresh.length,
684
+ plan: rel(planAbs),
685
+ round: roundN,
686
+ });
687
+ ctx.log(
688
+ `challenge merge: pause — ${fresh.length} task(s) exceed what one merge adds (${most}); nothing written`,
689
+ );
690
+ return EXIT.OK;
691
+ }
692
+
693
+ // Reopened tasks carry this round in their Round value; the plan's lines keep their count.
694
+ const reopened = [...new Map(open.map((x) => [x.at.task, x.at])).values()];
695
+ const stamped = stampRound(
696
+ before,
697
+ reopened.filter((t) => !t.rounds.includes(roundN)),
698
+ roundN,
699
+ );
700
+ let fixTasks = reopened.map((t) => t.task);
701
+ let after = stamped;
702
+ if (fresh.length > 0) {
703
+ const firstTask = Math.max(0, ...parsePlanBlocks(before).tasks.map((t) => t.task)) + 1;
704
+ const {
705
+ text,
706
+ tasks: added,
707
+ written,
708
+ } = appendTasks(stamped, fresh, roundN, firstTask, caps);
709
+ const problems = planProblems(text, written, added, caps);
710
+ if (problems.length > 0) {
711
+ ctx.emit({ plan: rel(planAbs), problems });
712
+ ctx.log(`challenge merge: plan check failed — ${problems.join("; ")}`);
713
+ return EXIT_PLAN_CHECK;
714
+ }
715
+ after = text;
716
+ fixTasks = [...fixTasks, ...added];
717
+ }
718
+
719
+ // Deferrals before the plan: a refused or failed append changes nothing, and a re-run
720
+ // after a failed plan write skips the rows already appended (same key).
721
+ const known = new Set(
722
+ ledgerRows(path.join(top, "docs", "deferrals.jsonl")).map((r) => String(r.key)),
723
+ );
724
+ const rows = lowDeferrals(fid, low).filter((r) => !known.has(String(r.key)));
725
+ if (rows.length > 0) appendLedgerRows(top, "deferrals", rows);
726
+ if (after !== before) writeAtomic(planAbs, after);
727
+
728
+ const running = [...fresh, ...open.map((x) => x.f)];
729
+ const route =
730
+ fixTasks.length === 0 ? "none" : running.some((f) => !f.fixable) ? "pause" : "fix";
731
+ ctx.emit({
732
+ route,
733
+ fixTasks: fixTasks.join(","),
734
+ appended: fresh.length,
735
+ reopened: reopened.map((t) => t.task).join(","),
736
+ deferred: rows.length,
737
+ dropped,
738
+ plan: rel(planAbs),
739
+ round: roundN,
740
+ });
741
+ ctx.log(
742
+ `challenge merge: ${route} — ${fresh.length} task(s) appended to ${rel(planAbs)}, ${reopened.length} open task(s) reported again, ${rows.length} LOW deferral row(s) written, ${dropped} accepted`,
743
+ );
744
+ return EXIT.OK;
745
+ },
746
+ },
747
+ },
748
+ };