@cbartens/bkit 6.0.0 → 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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -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 +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  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 +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,6 +1,6 @@
1
- // bkit context clamp|clamp-log|ledger-scan|diff|brief|list-blocks|run-block|finalise —
1
+ // bkit context clamp|clamp-log|ledger-scan|diff|brief|list-blocks|run-block|finalise|provision —
2
2
  // size-bound context artifacts, write the run's diff and a build group's brief,
3
- // and fetch the consumer's evidence.
3
+ // fetch the consumer's evidence, and run its cloud provision recipes.
4
4
  //
5
5
  // clamp is a runaway backstop, NOT a routine cap: a normal run never fires it.
6
6
  // Every removal is marked in place and footered. Profiles:
@@ -11,6 +11,12 @@
11
11
  // plus every line matching the signal pattern with 2 lines of
12
12
  // context. Lines over 2000 bytes are shortened in place. Hard
13
13
  // ceiling 12000 lines / 1.5 MB.
14
+ // ci / e2e / the debug-evidence algorithm with their context's own section
15
+ // runtime headers added to the signal pattern, so a header naming a kept
16
+ // block's owner survives without a signal word (`===== job …
17
+ // =====`, `===== file: … =====`, `===== step: …`, `===== vercel
18
+ // …`). `context fetch` picks the profile of the block's
19
+ // `context=`; any other context clamps as debug-evidence.
14
20
  //
15
21
  // Bytes are counted as raw bytes (as `LC_ALL=C awk` counts them), never as
16
22
  // characters, so a multi-byte line is measured by what it costs on disk.
@@ -22,19 +28,19 @@ import { spawnSync } from "node:child_process";
22
28
  import * as fs from "node:fs";
23
29
  import * as path from "node:path";
24
30
  import { CONTEXT_FETCH_CONTEXTS, parseContextFetchStart, } from "../../checks/before/context-fetch.js";
25
- import { extractContextFetchProvisionRecipes } from "../../install/cloud-env.js";
31
+ import { UNAVAILABLE_RELPATH, extractContextFetchProvisionRecipes, renderCloudContextFetchProvision, } from "../../install/cloud-env.js";
26
32
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
27
- import { lastRun } from "../../ledgers/status.js";
33
+ import { lastRun, validateCiSelection } from "../../ledgers/status.js";
28
34
  import { CommandError, EXIT, git, outboxRel, outboxRoot, } from "../lib.js";
29
35
  import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
30
36
  import { parseJson } from "../../shared/json.js";
31
37
  import { checkedTable } from "../../shared/text.js";
32
38
  import { buildComment } from "./issues.js";
33
- import { parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
39
+ import { derivedTestMatrix, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
34
40
  import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
35
- import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
41
+ import { EXIT_NO_STATUS, FILE_FLAG, positiveInt, readRuns, str } from "./status.js";
36
42
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
37
- import { doneTasks, redRows } from "./tests.js";
43
+ import { RED_PROVEN, doneTasks, redEntries, redKey, testSpan } from "./tests.js";
38
44
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
39
45
  export const EXIT_ARTIFACT = 4;
40
46
  // ---------------------------------------------------------------------------
@@ -106,12 +112,15 @@ const EVIDENCE = {
106
112
  hardLines: 12000,
107
113
  hardBytes: 1572864,
108
114
  };
109
- export const CLAMP_PROFILES = ["ledger", "debug-evidence"];
115
+ export const CLAMP_PROFILES = ["ledger", "debug-evidence", "ci", "e2e", "runtime"];
110
116
  /**
111
117
  * Lowercase substrings matched against a lowercased line. Broad: `error` also covers
112
- * `##[error]`, `fail` covers `FAILED`; the ceiling bounds over-matching.
118
+ * `##[error]`, `fail` covers `FAILED`; the ceiling bounds over-matching. Every profile keeps
119
+ * `===== TRUNCATED: … =====`, the line `.agents/context.md` asks every block to print when
120
+ * it stops short of its window, so a partial read never looks complete.
113
121
  */
114
122
  const SIGNALS = [
123
+ "===== truncated: ",
115
124
  "error",
116
125
  "fail",
117
126
  "exception",
@@ -126,6 +135,50 @@ const SIGNALS = [
126
135
  "●",
127
136
  "×",
128
137
  ].map((s) => Buffer.from(s));
138
+ /**
139
+ * Section-header markers a context's shipped blocks print, lowercased like them. A profile
140
+ * named for the context adds them, so a header that names a kept block's owner survives
141
+ * without a signal word. Sourced from `.bkit/templates/context/`: `github` (`ci`);
142
+ * `playwright` + `maestro` + `expo-workflows` (`e2e`); every runtime block that prints a
143
+ * banner — `vercel`, `cloudrun`, `supabase`, `inngest`, `resend`, `stripe`, `expo`
144
+ * (`runtime`). `sentry` prints no banner. A context with no entry clamps as
145
+ * `debug-evidence`.
146
+ */
147
+ const CONTEXT_MARKERS = {
148
+ ci: ["===== job ", "===== run "],
149
+ e2e: [
150
+ "===== file: ",
151
+ "===== step: ",
152
+ "===== maestro job ",
153
+ "===== playwright report ",
154
+ // `expo-workflows` (`context=e2e`).
155
+ "===== eas workflow runs",
156
+ "===== failing steps",
157
+ "===== screen-hierarchy dumps",
158
+ "===== app js console per flow",
159
+ "===== distinct app messages",
160
+ "===== junit ",
161
+ ],
162
+ runtime: [
163
+ "===== vercel ",
164
+ "===== cloud run ",
165
+ "===== supabase ",
166
+ "===== inngest ",
167
+ "===== resend ",
168
+ "===== stripe ",
169
+ "===== webhook deliveries failed",
170
+ "===== eas builds",
171
+ ],
172
+ };
173
+ /** Each context profile's signal set: {@link SIGNALS} plus that context's markers. */
174
+ const PROFILE_SIGNALS = Object.fromEntries(Object.entries(CONTEXT_MARKERS).map(([profile, markers]) => [
175
+ profile,
176
+ [...SIGNALS, ...markers.map((m) => Buffer.from(m))],
177
+ ]));
178
+ /** The signals a profile matches; a profile with no markers of its own is the base set. */
179
+ const signalsFor = (profile) => PROFILE_SIGNALS[profile] ?? SIGNALS;
180
+ /** The clamp profile a block's context selects; any context without its own profile is `debug-evidence`. */
181
+ const contextProfile = (context) => CONTEXT_MARKERS[context] === undefined ? "debug-evidence" : context;
129
182
  /** awk records: a final line with no newline is one, a trailing newline does not start another. */
130
183
  function records(buf) {
131
184
  const out = [];
@@ -140,12 +193,12 @@ function records(buf) {
140
193
  out.push(buf.subarray(start));
141
194
  return out;
142
195
  }
143
- function hasSignal(line) {
196
+ function hasSignal(line, signals) {
144
197
  const lower = Buffer.from(line);
145
198
  for (let i = 0; i < lower.length; i++)
146
199
  if (lower[i] >= 65 && lower[i] <= 90)
147
200
  lower[i] += 32;
148
- return SIGNALS.some((s) => lower.includes(s));
201
+ return signals.some((s) => lower.includes(s));
149
202
  }
150
203
  /** awk's human size: B, rounded KB, or MB to one decimal (ties to even, as printf). */
151
204
  export function humanBytes(b) {
@@ -187,7 +240,7 @@ function selectLedger(buf) {
187
240
  body: rows.slice(0, keep).flatMap((r) => [r, Buffer.from("\n")]),
188
241
  };
189
242
  }
190
- function selectEvidence(buf) {
243
+ function selectEvidence(buf, signals) {
191
244
  const p = EVIDENCE;
192
245
  const raw = records(buf);
193
246
  const n = raw.length;
@@ -232,7 +285,7 @@ function selectEvidence(buf) {
232
285
  // otherwise lose its immunity.
233
286
  let ceiling = false;
234
287
  for (let i = 0; i < n; i++) {
235
- if (!hasSignal(raw[i]))
288
+ if (!hasSignal(raw[i], signals))
236
289
  continue;
237
290
  const a = Math.max(0, i - p.context);
238
291
  const b = Math.min(n - 1, i + p.context);
@@ -314,7 +367,7 @@ export function clampFile(file, profile, artifact = file, keep) {
314
367
  throw new CommandError(EXIT_ARTIFACT, `cannot read artifact '${artifact}': ${read.problem}`);
315
368
  }
316
369
  const buf = read.buf;
317
- const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
370
+ const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf, signalsFor(profile));
318
371
  const source = keep?.source ?? null;
319
372
  const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
320
373
  const untouched = (s) => ({
@@ -392,6 +445,43 @@ function replaceFile(file, tmp, content) {
392
445
  return err.message;
393
446
  }
394
447
  }
448
+ /** The context-fetch context a clamp record belongs to, from its `context-<context>-…` artifact basename. */
449
+ function contextOfArtifact(artifact) {
450
+ const context = /^context-([a-z0-9]+)-/.exec(path.basename(artifact))?.[1];
451
+ return context !== undefined && CONTEXT_FETCH_CONTEXTS.includes(context) ? context : undefined;
452
+ }
453
+ const numberOr0 = (v) => (typeof v === "number" ? v : 0);
454
+ /** The context-fetch clamp records totalled per context; a record naming no context is skipped. */
455
+ export function summariseRecords(records) {
456
+ const summary = {};
457
+ for (const value of records) {
458
+ const r = value;
459
+ if (r === null || typeof r.artifact !== "string")
460
+ continue;
461
+ const context = contextOfArtifact(r.artifact);
462
+ if (context === undefined)
463
+ continue;
464
+ const s = (summary[context] ??= {
465
+ artifacts: 0,
466
+ origLines: 0,
467
+ keptLines: 0,
468
+ origBytes: 0,
469
+ keptBytes: 0,
470
+ table: 0,
471
+ raw: 0,
472
+ });
473
+ s.artifacts++;
474
+ s.origLines += numberOr0(r.origLines);
475
+ s.keptLines += numberOr0(r.keptLines);
476
+ s.origBytes += numberOr0(r.origBytes);
477
+ s.keptBytes += numberOr0(r.keptBytes);
478
+ if (r.render === "table")
479
+ s.table++;
480
+ else if (r.render === "raw")
481
+ s.raw++;
482
+ }
483
+ return summary;
484
+ }
395
485
  // ---------------------------------------------------------------------------
396
486
  // Clamp log — records cross the gap between the block that writes an artifact
397
487
  // and the block that records the step's status row.
@@ -435,6 +525,7 @@ const RECORD_OUTPUT = {
435
525
  raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
436
526
  source: "the command that produced the file (--source), or null",
437
527
  fetchedAt: "when the source ran (UTC; the clamp time with --source), or null",
528
+ render: "context fetch only: table when the output was rendered as a table, else raw",
438
529
  };
439
530
  /** Say so when a cut had nowhere to keep its original. */
440
531
  function warnNoRaw(ctx, record, keep) {
@@ -743,7 +834,9 @@ export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
743
834
  /** The plan sections a brief carries as its why and what, by heading text. */
744
835
  const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
745
836
  /** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
746
- const EXECUTE_LOG = /^build-plan-execute-.+-log\.md$/;
837
+ // `build-plan-execute-*` is the log's name from before the step rename: a run in flight
838
+ // across the rename keeps its DONE lines (`docs/migrations.md`).
839
+ const TASKS_LOG = /^build-plan-(?:tasks|execute)-.+-log\.md$/;
747
840
  /** A heading's text without leading emoji and marks. */
748
841
  const headingText = (text) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
749
842
  /**
@@ -775,7 +868,7 @@ function loggedDone(dir) {
775
868
  const done = new Set();
776
869
  if (!fs.existsSync(dir))
777
870
  return done;
778
- for (const f of fs.readdirSync(dir).filter((f) => EXECUTE_LOG.test(f)))
871
+ for (const f of fs.readdirSync(dir).filter((f) => TASKS_LOG.test(f)))
779
872
  for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8")))
780
873
  done.add(n);
781
874
  return done;
@@ -819,19 +912,43 @@ function architectureEntries(lines, files) {
819
912
  return [body.slice(h.i, end).join("\n").trim()];
820
913
  });
821
914
  }
822
- /** The next free `build-brief-{group}-{n}.md` in `dir`. */
823
- function nextBriefPath(dir, group) {
824
- const re = new RegExp(`^build-brief-${group}-([0-9]+)\\.md$`);
915
+ /** The next free `{prefix}-{group}-{n}.md` in `dir`: the code briefs and the tests briefs count apart. */
916
+ function nextBriefPath(dir, group, prefix = "build-brief") {
917
+ const re = new RegExp(`^${prefix}-${group}-([0-9]+)\\.md$`);
825
918
  const taken = fs.existsSync(dir)
826
919
  ? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
827
920
  : [];
828
- return path.join(dir, `build-brief-${group}-${Math.max(0, ...taken) + 1}.md`);
921
+ return path.join(dir, `${prefix}-${group}-${Math.max(0, ...taken) + 1}.md`);
922
+ }
923
+ /** The TEST FIRST tests of `tasks`, in plan order. */
924
+ export const plannedTests = (tasks) => tasks.flatMap((t) => (t.testFirst?.tests ?? []).map((x) => ({ task: t.task, ...x })));
925
+ /**
926
+ * The planned tests of `open` that already exist in the tree under `top`: the tests step
927
+ * updates each one in place (adding expectations, never removing or loosening one) rather
928
+ * than writing a second test of that name.
929
+ */
930
+ export function existingPlannedTests(top, open) {
931
+ const out = [];
932
+ for (const t of plannedTests(open)) {
933
+ const abs = path.join(top, t.test);
934
+ if (!fs.existsSync(abs))
935
+ continue;
936
+ const span = testSpan(fs.readFileSync(abs, "utf-8"), t.name);
937
+ if (span !== null)
938
+ out.push({ task: t.task, test: t.test, name: t.name, line: span.start });
939
+ }
940
+ return out;
829
941
  }
830
942
  /** The brief's text and its work section's size in bytes. */
831
943
  export function briefText(o) {
832
944
  const lines = o.plan.split("\n");
833
945
  const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
834
- const out = [`# Brief: group ${o.group.group} — ${o.group.title}`, "", `Plan: ${title}`, ""];
946
+ const out = [
947
+ `# Brief: group ${o.group.group} — ${o.group.title}${o.testsOnly ? " (tests)" : ""}`,
948
+ "",
949
+ `Plan: ${title}`,
950
+ "",
951
+ ];
835
952
  out.push("## Why and what", "");
836
953
  for (const name of BRIEF_SECTIONS) {
837
954
  const body = planSection(lines, name);
@@ -859,14 +976,6 @@ export function briefText(o) {
859
976
  const work = ["## The work", ""];
860
977
  for (const t of open)
861
978
  work.push(t.text.trim(), "");
862
- const openNums = new Set(open.map((t) => t.task));
863
- const reds = o.reds.filter((r) => openNums.has(Number(r.task)));
864
- if (reds.length > 0) {
865
- work.push("### Reds already recorded", "");
866
- for (const r of reds)
867
- work.push(`- TASK ${Number(r.task)}: red already recorded for \`${String(r.test)}\` \`${String(r.testName)}\` — test written and seen failing; code may be partly done in the files it names`);
868
- work.push("");
869
- }
870
979
  const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
871
980
  .filter((n) => !o.group.tasks.some((t) => t.task === n))
872
981
  .sort((a, b) => a - b)
@@ -881,7 +990,18 @@ export function briefText(o) {
881
990
  }
882
991
  work.push("");
883
992
  }
884
- work.push(...planEntries(lines, open, work, o.planFile));
993
+ if (o.testsOnly) {
994
+ work.push(...matrixRows(o.plan, open));
995
+ const existing = (o.existing ?? []).filter((e) => open.some((t) => t.task === e.task));
996
+ if (existing.length > 0) {
997
+ work.push("### Planned tests that already exist", "");
998
+ for (const e of existing)
999
+ work.push(`- TASK ${e.task} \`${e.test}\` \`${e.name}\` — exists at \`${e.test}:${e.line}\`; update that test in place: add expectations, never remove or loosen one`);
1000
+ work.push("");
1001
+ }
1002
+ }
1003
+ else
1004
+ work.push(...planEntries(lines, open, work, o.planFile));
885
1005
  out.push(...work);
886
1006
  if (o.note !== undefined)
887
1007
  out.push("## Deviations", "", o.note.trim(), "");
@@ -890,6 +1010,17 @@ export function briefText(o) {
890
1010
  workBytes: Buffer.byteLength(work.join("\n")),
891
1011
  };
892
1012
  }
1013
+ /** The Derived Test Matrix rows naming a TEST FIRST file of `open`, under the table's header. */
1014
+ function matrixRows(plan, open) {
1015
+ const matrix = derivedTestMatrix(plan);
1016
+ if (matrix === null)
1017
+ return [];
1018
+ const files = new Set(plannedTests(open).map((t) => path.posix.normalize(t.test)));
1019
+ const rows = matrix.rows.filter((r) => [...r.line.matchAll(/`([^`]+)`/g)].some((m) => files.has(path.posix.normalize(m[1]))));
1020
+ return rows.length === 0
1021
+ ? []
1022
+ : ["### Derived Test Matrix rows", "", ...matrix.head, ...rows.map((r) => r.line), ""];
1023
+ }
893
1024
  /**
894
1025
  * The Reuse Inventory rows, then the Architecture entries, for the files on the open
895
1026
  * tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
@@ -946,9 +1077,14 @@ const RUN_BLOCK_FLAGS = [
946
1077
  FID_FLAG,
947
1078
  MONTH_FLAG,
948
1079
  ...ATTEMPT_FLAGS,
1080
+ {
1081
+ name: "ci-selection-file",
1082
+ type: "string",
1083
+ help: "validated CI selection JSON; pin child evidence reads and require a matching complete CI receipt",
1084
+ },
949
1085
  ];
950
1086
  const RUN_BLOCK_OUTPUT = {
951
- outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
1087
+ outcome: "checked (validated data written) | unchecked (selected CI evidence invalid) | self-skipped (skip line written) | silent (nothing) | not-run",
952
1088
  artifact: "the artifact path, or null when nothing was written",
953
1089
  skip: "the block's [context-fetch:<name>] stderr line, or null",
954
1090
  clamp: "the payload's clamp record, or null",
@@ -960,9 +1096,10 @@ export const contextCommand = {
960
1096
  verbs: {
961
1097
  clamp: {
962
1098
  summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
1099
+ use: "workflow",
963
1100
  flags: [
964
1101
  { name: "artifact", type: "string", required: true, help: "file to clamp" },
965
- { name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
1102
+ { name: "profile", type: "string", required: true, help: CLAMP_PROFILES.join(" | ") },
966
1103
  {
967
1104
  name: "source",
968
1105
  type: "string",
@@ -993,6 +1130,7 @@ export const contextCommand = {
993
1130
  },
994
1131
  "clamp-log": {
995
1132
  summary: "Read a step's clamp records (the status row's clamped array), or reset the log.",
1133
+ use: "workflow",
996
1134
  flags: [
997
1135
  ...LOG_FLAGS,
998
1136
  { name: "reset", type: "boolean", help: "empty the log first (the step's first writer)" },
@@ -1015,6 +1153,7 @@ export const contextCommand = {
1015
1153
  },
1016
1154
  "ledger-scan": {
1017
1155
  summary: "Write a ledger's lines matching query terms, strongest first, then clamp (ledger profile).",
1156
+ use: "workflow",
1018
1157
  flags: [
1019
1158
  { name: "terms", type: "string", required: true, help: "space-separated query terms" },
1020
1159
  {
@@ -1069,6 +1208,7 @@ export const contextCommand = {
1069
1208
  },
1070
1209
  diff: {
1071
1210
  summary: "Write the run's diff ({base}...HEAD, docs/plans/** excluded) as one artifact — whole, or a per-file budget past the guard — and print its numbers.",
1211
+ use: "workflow",
1072
1212
  flags: [
1073
1213
  { name: "artifact", type: "string", required: true, help: "file to write" },
1074
1214
  {
@@ -1137,7 +1277,8 @@ export const contextCommand = {
1137
1277
  },
1138
1278
  },
1139
1279
  brief: {
1140
- summary: "Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes.",
1280
+ summary: "Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes; --tests-only writes the tests step's brief as build-brief-tests-{group}-{n}.md, with the Derived Test Matrix rows for the group's tests in place of the inventory and architecture entries.",
1281
+ use: "workflow",
1141
1282
  flags: [
1142
1283
  { name: "plan", type: "string", required: true, help: "the plan file" },
1143
1284
  { name: "group", type: "string", help: "the group to brief" },
@@ -1150,12 +1291,17 @@ export const contextCommand = {
1150
1291
  name: "dir",
1151
1292
  type: "string",
1152
1293
  required: true,
1153
- help: "the run's logs folder: the brief is written there, and its build-plan-execute-*-log.md DONE lines mark tasks done",
1294
+ help: "the run's logs folder: the brief is written there, and its build-plan-tasks-*-log.md DONE lines mark tasks done",
1154
1295
  },
1155
1296
  {
1156
- name: "file",
1157
- type: "string",
1158
- help: "status.jsonl, to name the reds already recorded for open tasks",
1297
+ name: "tests-only",
1298
+ type: "boolean",
1299
+ help: "the tests step's brief: build-brief-tests-{group}-{n}.md (a group with no planned test writes nothing, tests 0)",
1300
+ },
1301
+ {
1302
+ ...FILE_FLAG,
1303
+ required: false,
1304
+ help: "with --tests-only: the run's status.jsonl; a planned test a build-tests-red row of the group already proved red is left out, and a task with no test left is not briefed",
1159
1305
  },
1160
1306
  {
1161
1307
  name: "note-file",
@@ -1168,12 +1314,12 @@ export const contextCommand = {
1168
1314
  bytes: "the brief's size in bytes",
1169
1315
  group: "the group briefed (null when --next finds no open group)",
1170
1316
  tasks: "the open task numbers the brief carries",
1317
+ tests: "the TEST FIRST tests of those tasks (0 when --next finds no open group)",
1171
1318
  workBytes: "the work section's size in bytes (0 when --next finds no open group)",
1172
1319
  workCap: `the work section's cap in bytes (${BRIEF_WORK_WARN_BYTES}): Reuse Inventory rows and Architecture entries past it are left out and counted; task blocks over it warn on stderr`,
1173
1320
  },
1174
1321
  exitCodes: {
1175
1322
  [EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
1176
- [EXIT_NO_STATUS]: "--file names a missing or malformed status.jsonl",
1177
1323
  },
1178
1324
  run: (ctx) => {
1179
1325
  const groupFlag = positiveInt(ctx.flags.group, "group");
@@ -1202,6 +1348,30 @@ export const contextCommand = {
1202
1348
  bytes: 0,
1203
1349
  group: null,
1204
1350
  tasks: [],
1351
+ tests: 0,
1352
+ workBytes: 0,
1353
+ workCap: BRIEF_WORK_WARN_BYTES,
1354
+ });
1355
+ return EXIT.OK;
1356
+ }
1357
+ const testsOnly = ctx.flags.testsOnly === true;
1358
+ const statusArg = str(ctx.flags.file);
1359
+ const proven = testsOnly && statusArg !== undefined
1360
+ ? redEntries(path.resolve(ctx.cwd, statusArg), "build", group.group)
1361
+ : new Map();
1362
+ const left = (t) => plannedTests([t]).filter((x) => {
1363
+ const red = proven.get(redKey(x.task, x.test, x.name));
1364
+ return red === undefined || !RED_PROVEN.has(red.state);
1365
+ });
1366
+ const open = group.tasks.filter((t) => !isDone(t) && (!testsOnly || left(t).length > 0));
1367
+ const tests = testsOnly ? open.flatMap(left).length : plannedTests(open).length;
1368
+ if (testsOnly && tests === 0) {
1369
+ ctx.emit({
1370
+ artifact: null,
1371
+ bytes: 0,
1372
+ group: group.group,
1373
+ tasks: open.map((t) => t.task),
1374
+ tests,
1205
1375
  workBytes: 0,
1206
1376
  workCap: BRIEF_WORK_WARN_BYTES,
1207
1377
  });
@@ -1211,17 +1381,19 @@ export const contextCommand = {
1211
1381
  const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1212
1382
  if (noteFile !== undefined && !fs.existsSync(noteFile))
1213
1383
  throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1214
- const status = str(ctx.flags.file);
1215
1384
  const { text, workBytes } = briefText({
1216
1385
  plan,
1217
1386
  planFile: String(ctx.flags.plan),
1218
1387
  group,
1219
1388
  groups: blocks.groups,
1220
- isDone,
1221
- reds: status === undefined ? [] : redRows(path.resolve(ctx.cwd, status), "build"),
1389
+ isDone: (t) => isDone(t) || (group.tasks.includes(t) && !open.includes(t)),
1390
+ testsOnly,
1391
+ existing: testsOnly
1392
+ ? existingPlannedTests(git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd, open)
1393
+ : undefined,
1222
1394
  note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1223
1395
  });
1224
- const out = nextBriefPath(dir, group.group);
1396
+ const out = nextBriefPath(dir, group.group, testsOnly ? "build-brief-tests" : undefined);
1225
1397
  fs.mkdirSync(dir, { recursive: true });
1226
1398
  fs.writeFileSync(out, text);
1227
1399
  if (workBytes > BRIEF_WORK_WARN_BYTES) {
@@ -1232,7 +1404,8 @@ export const contextCommand = {
1232
1404
  artifact,
1233
1405
  bytes: Buffer.byteLength(text),
1234
1406
  group: group.group,
1235
- tasks: group.tasks.filter((t) => !isDone(t)).map((t) => t.task),
1407
+ tasks: open.map((t) => t.task),
1408
+ tests,
1236
1409
  workBytes,
1237
1410
  workCap: BRIEF_WORK_WARN_BYTES,
1238
1411
  });
@@ -1241,12 +1414,13 @@ export const contextCommand = {
1241
1414
  },
1242
1415
  "list-blocks": {
1243
1416
  summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
1417
+ use: "by-hand",
1244
1418
  flags: [],
1245
1419
  output: {
1246
1420
  blocks: "[{idx, context, name, known, prefix, suffix, body}] in file order",
1247
1421
  coverage: "blocks per context (runtime, ci, diff, e2e, web)",
1248
1422
  contextsConfigured: "contexts with at least one block, in narration order",
1249
- provision: "bash body of each context-fetch:provision block below bkit:end, in file order (bkit-cloud-bootstrap.sh runs them)",
1423
+ provision: "bash body of each context-fetch:provision block below bkit:end, in file order",
1250
1424
  },
1251
1425
  run: (ctx) => {
1252
1426
  const blocks = fetchBlocks(consumerSection(readContextMd(ctx) ?? ""));
@@ -1271,8 +1445,20 @@ export const contextCommand = {
1271
1445
  return EXIT.OK;
1272
1446
  },
1273
1447
  },
1448
+ provision: {
1449
+ summary: "Run each context-fetch:provision recipe below bkit:end on its own and list the failed ones in .bkit/.unavailable.",
1450
+ use: "by-hand",
1451
+ flags: [],
1452
+ output: {
1453
+ recipes: "recipes run",
1454
+ unavailable: "[{name, reason}] for each failed recipe, in file order",
1455
+ file: "the failure list's path from the repo root; null when none failed",
1456
+ },
1457
+ run: (ctx) => runProvision(ctx),
1458
+ },
1274
1459
  "run-block": {
1275
1460
  summary: "Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
1461
+ use: "workflow",
1276
1462
  flags: RUN_BLOCK_FLAGS,
1277
1463
  output: RUN_BLOCK_OUTPUT,
1278
1464
  textOmit: ["clamp"],
@@ -1284,6 +1470,7 @@ export const contextCommand = {
1284
1470
  },
1285
1471
  fetch: {
1286
1472
  summary: "run-block, with a JSON array of flat objects written as a markdown table; the raw output stays in the outbox.",
1473
+ use: "workflow",
1287
1474
  flags: [
1288
1475
  ...RUN_BLOCK_FLAGS,
1289
1476
  {
@@ -1310,6 +1497,7 @@ export const contextCommand = {
1310
1497
  },
1311
1498
  finalise: {
1312
1499
  summary: "The context-fetch status row's fields: verdict, artifacts, contexts configured, clamped; --record writes and commits the row and prints the step comment.",
1500
+ use: "workflow",
1313
1501
  flags: [
1314
1502
  FID_FLAG,
1315
1503
  MONTH_FLAG,
@@ -1334,14 +1522,16 @@ export const contextCommand = {
1334
1522
  artifacts: "those artifacts, relative to the working directory",
1335
1523
  contextsConfigured: "contexts with at least one block",
1336
1524
  clamped: "this attempt's clamp records",
1525
+ clampSummary: "those records totalled per context: artifacts written, lines and bytes fetched -> kept, and how many were written as a table vs raw",
1337
1526
  row: "--record: the step-done row written, else null",
1338
1527
  commit: "--record: the new commit's sha, else null",
1528
+ progressLine: "--record: the exact chat progress line after a successful numbered completion",
1339
1529
  comment: "the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
1340
1530
  commentFile: COMMENT_FILE_OUTPUT,
1341
1531
  },
1342
1532
  exitCodes: {
1343
1533
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
1344
- [EXIT_COMMIT]: "--record: the row was written but the commit failed",
1534
+ [EXIT_COMMIT]: "--record: nothing written, nothing committed: the commit failed and the row was rolled back",
1345
1535
  },
1346
1536
  run: (ctx) => {
1347
1537
  const attempt = debugAttempt(ctx);
@@ -1360,6 +1550,7 @@ export const contextCommand = {
1360
1550
  const blocks = fetchBlocks(consumerSection(readContextMd(ctx) ?? ""));
1361
1551
  const contextsConfigured = CONTEXT_FETCH_CONTEXTS.filter((c) => blocks.some((b) => b.context === c));
1362
1552
  const clamped = readRecords(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), (l) => ctx.log(`skipping a malformed clamp record: ${l}`));
1553
+ const clampSummary = summariseRecords(clamped);
1363
1554
  const verdict = artifacts.length > 0 ? "PASS" : "FAIL";
1364
1555
  let written = {
1365
1556
  row: {},
@@ -1371,6 +1562,7 @@ export const contextCommand = {
1371
1562
  const file = str(ctx.flags.file);
1372
1563
  if (file === undefined)
1373
1564
  throw new CommandError(EXIT.USAGE, "--record needs --file");
1565
+ const active = lastRun(readRuns(path.resolve(ctx.cwd, file)), "debug");
1374
1566
  written = writeStepRow(ctx.cwd, {
1375
1567
  file: path.resolve(ctx.cwd, file),
1376
1568
  workflow: "debug",
@@ -1378,7 +1570,16 @@ export const contextCommand = {
1378
1570
  verdict,
1379
1571
  attempt,
1380
1572
  artifacts,
1381
- extras: { contextsConfigured, clamped },
1573
+ extras: {
1574
+ contextsConfigured,
1575
+ clamped,
1576
+ clampSummary,
1577
+ ...(active &&
1578
+ validateCiSelection(active.ciSelection) &&
1579
+ active.ciSelection.mode === "ci"
1580
+ ? { ciGeneration: active.ciGeneration }
1581
+ : {}),
1582
+ },
1382
1583
  commit: "auto",
1383
1584
  message: str(ctx.flags.message),
1384
1585
  }, ctx.log);
@@ -1407,8 +1608,10 @@ export const contextCommand = {
1407
1608
  artifacts,
1408
1609
  contextsConfigured,
1409
1610
  clamped,
1611
+ clampSummary,
1410
1612
  row: record ? written.row : null,
1411
1613
  commit: written.commit,
1614
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
1412
1615
  comment,
1413
1616
  commentFile: commentFileOf(ctx.cwd, comment),
1414
1617
  });
@@ -1425,6 +1628,42 @@ function tableOf(stdout) {
1425
1628
  const table = checkedTable(parsed.value);
1426
1629
  return table.ok ? { text: table.text } : { reason: table.reason };
1427
1630
  }
1631
+ /** Selected CI evidence is usable only with one complete receipt and actual logs. */
1632
+ function ciEvidenceProblem(stdout, selection) {
1633
+ const lines = stdout.toString("utf-8").split("\n");
1634
+ const receipts = lines.filter((line) => line.startsWith("bkit-ci-evidence: "));
1635
+ if (receipts.length !== 1)
1636
+ return "selected CI evidence needs exactly one identity receipt";
1637
+ const parsed = parseJson(receipts[0].slice("bkit-ci-evidence: ".length));
1638
+ if (!parsed.ok ||
1639
+ parsed.value === null ||
1640
+ typeof parsed.value !== "object" ||
1641
+ Array.isArray(parsed.value))
1642
+ return "selected CI evidence receipt is malformed";
1643
+ const receipt = parsed.value;
1644
+ for (const field of [
1645
+ "provider",
1646
+ "repo",
1647
+ "runId",
1648
+ "runAttempt",
1649
+ "headSha",
1650
+ "workflowId",
1651
+ ]) {
1652
+ if (receipt[field] !== selection[field])
1653
+ return `selected CI evidence ${field} does not match`;
1654
+ }
1655
+ if (receipt.complete !== true)
1656
+ return "selected CI evidence is incomplete";
1657
+ const logs = lines
1658
+ .filter((line) => !line.startsWith("bkit-ci-evidence: "))
1659
+ .join("\n")
1660
+ .trim();
1661
+ if (logs === "")
1662
+ return "selected CI evidence contains no logs";
1663
+ if (/\[context-fetch:[^\n]*skipped|===== TRUNCATED:/i.test(logs))
1664
+ return "selected CI evidence is skipped or partial";
1665
+ return null;
1666
+ }
1428
1667
  /**
1429
1668
  * Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
1430
1669
  * (`context fetch`), a JSON array of flat objects is written as a table instead; the
@@ -1454,11 +1693,32 @@ function runBlock(ctx, render) {
1454
1693
  return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
1455
1694
  const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1456
1695
  const fetchedAt = utcNow();
1696
+ const selectionFile = str(ctx.flags.ciSelectionFile);
1697
+ let selection;
1698
+ if (selectionFile !== undefined) {
1699
+ const file = path.resolve(ctx.cwd, selectionFile);
1700
+ if (!fs.existsSync(file))
1701
+ throw new CommandError(EXIT.USAGE, `--ci-selection-file ${selectionFile} does not exist`);
1702
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
1703
+ if (!parsed.ok || !validateCiSelection(parsed.value))
1704
+ throw new CommandError(EXIT.USAGE, "--ci-selection-file must contain a validated CI or local selection");
1705
+ selection = parsed.value;
1706
+ }
1707
+ const childEnv = { ...process.env };
1708
+ for (const key of ["BKIT_CI_RUN_ID", "BKIT_CI_RUN_ATTEMPT", "BKIT_CI_REPO", "BKIT_CI_HEAD_SHA"])
1709
+ delete childEnv[key];
1710
+ if (selection?.mode === "ci")
1711
+ Object.assign(childEnv, {
1712
+ BKIT_CI_RUN_ID: selection.runId,
1713
+ BKIT_CI_RUN_ATTEMPT: String(selection.runAttempt),
1714
+ BKIT_CI_REPO: selection.repo,
1715
+ BKIT_CI_HEAD_SHA: selection.headSha,
1716
+ });
1457
1717
  // The inline block ran inside the step's shell, so these were in scope for it.
1458
1718
  const res = spawnSync("bash", [script], {
1459
1719
  cwd: ctx.cwd,
1460
1720
  env: {
1461
- ...process.env,
1721
+ ...childEnv,
1462
1722
  REPO_ROOT: repoRoot,
1463
1723
  CONTEXT: block.context,
1464
1724
  NAME: block.name,
@@ -1475,6 +1735,11 @@ function runBlock(ctx, render) {
1475
1735
  const artifact = path.join(logDir(String(ctx.flags.month), fid), `${block.prefix}-${block.suffix}${attempt}.md`);
1476
1736
  const out = path.resolve(ctx.cwd, artifact);
1477
1737
  const shown = `context-fetch context=${block.context} name=${block.name || "default"}`;
1738
+ const evidenceProblem = selection?.mode === "ci" && block.context === "ci"
1739
+ ? res.status !== 0 || skip !== undefined
1740
+ ? "selected CI evidence command failed or self-skipped"
1741
+ : ciEvidenceProblem(stdout, selection)
1742
+ : null;
1478
1743
  if (stdout.some((b) => b !== 0x0a && b !== 0)) {
1479
1744
  fs.mkdirSync(path.dirname(out), { recursive: true });
1480
1745
  const keep = {
@@ -1482,7 +1747,8 @@ function runBlock(ctx, render) {
1482
1747
  source: fs.readFileSync(script, "utf-8"),
1483
1748
  fetchedAt,
1484
1749
  };
1485
- let payload = asCaptured(stdout);
1750
+ const printed = asCaptured(stdout);
1751
+ let payload = printed;
1486
1752
  let written = null;
1487
1753
  if (render !== undefined) {
1488
1754
  const table = render === "table" ? tableOf(stdout) : null;
@@ -1500,16 +1766,28 @@ function runBlock(ctx, render) {
1500
1766
  }
1501
1767
  }
1502
1768
  fs.writeFileSync(out, payload);
1503
- let clamp = clampFile(out, "debug-evidence", artifact, keep);
1769
+ let clamp = clampFile(out, contextProfile(block.context), artifact, keep);
1504
1770
  warnNoRaw(ctx, clamp, keep);
1505
1771
  if (written !== null) {
1506
1772
  const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
1507
1773
  clamp = { ...clamp, raw, render: written };
1508
1774
  }
1775
+ // Fetched is what the block printed; the table is only what the artifact keeps.
1776
+ if (written === "table") {
1777
+ clamp = { ...clamp, origLines: records(printed).length, origBytes: printed.length };
1778
+ }
1509
1779
  appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
1510
1780
  fs.writeFileSync(out, fenced(fs.readFileSync(out)));
1511
- ctx.log(`${shown} CHECKED — data returned`);
1512
- ctx.emit(shape({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null }, written));
1781
+ ctx.log(evidenceProblem === null
1782
+ ? `${shown} CHECKED — data returned`
1783
+ : `${shown} UNCHECKED — ${evidenceProblem}`);
1784
+ ctx.emit(shape({
1785
+ outcome: evidenceProblem === null ? "checked" : "unchecked",
1786
+ artifact,
1787
+ skip: skip ?? null,
1788
+ clamp,
1789
+ reason: evidenceProblem,
1790
+ }, written));
1513
1791
  return EXIT.OK;
1514
1792
  }
1515
1793
  if (skip !== undefined) {
@@ -1523,3 +1801,45 @@ function runBlock(ctx, render) {
1523
1801
  ctx.emit(shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null));
1524
1802
  return EXIT.OK;
1525
1803
  }
1804
+ /**
1805
+ * Run the consumer's provision recipes through the same region the cloud setup scripts
1806
+ * inline, with `REPO_ROOT` set so the region rewrites the failure list there. Recipe
1807
+ * output goes to stderr; stdout carries only this command's report. Never fails on a
1808
+ * recipe: a failure is reported, not raised.
1809
+ */
1810
+ function runProvision(ctx) {
1811
+ const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1812
+ const file = path.join(repoRoot, UNAVAILABLE_RELPATH);
1813
+ const region = renderCloudContextFetchProvision(ctx.cwd);
1814
+ const recipes = region === "" ? 0 : (region.match(/^bkit_provision '/gm) ?? []).length;
1815
+ if (region === "") {
1816
+ fs.rmSync(file, { force: true });
1817
+ }
1818
+ else {
1819
+ const res = spawnSync("bash", ["-c", `set -uo pipefail\n${region}`], {
1820
+ cwd: ctx.cwd,
1821
+ env: { ...process.env, REPO_ROOT: repoRoot },
1822
+ stdio: ["ignore", 2, 2],
1823
+ });
1824
+ if (res.error)
1825
+ throw new CommandError(EXIT.USAGE, `bash did not run: ${res.error.message}`);
1826
+ }
1827
+ const unavailable = fs.existsSync(file)
1828
+ ? fs
1829
+ .readFileSync(file, "utf-8")
1830
+ .split("\n")
1831
+ .filter((l) => l !== "")
1832
+ .map((l) => {
1833
+ const at = l.indexOf(": ");
1834
+ return at === -1
1835
+ ? { name: l, reason: "" }
1836
+ : { name: l.slice(0, at), reason: l.slice(at + 2) };
1837
+ })
1838
+ : [];
1839
+ ctx.emit({
1840
+ recipes,
1841
+ unavailable,
1842
+ file: unavailable.length === 0 ? null : UNAVAILABLE_RELPATH,
1843
+ });
1844
+ return EXIT.OK;
1845
+ }