@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,5 +1,6 @@
1
- // bkit context clamp|clamp-log|ledger-scan|list-blocks|run-block|finalise —
2
- // size-bound context artifacts and fetch the consumer's evidence.
1
+ // bkit context clamp|clamp-log|ledger-scan|diff|brief|list-blocks|run-block|finalise|provision —
2
+ // size-bound context artifacts, write the run's diff and a build group's brief,
3
+ // fetch the consumer's evidence, and run its cloud provision recipes.
3
4
  //
4
5
  // clamp is a runaway backstop, NOT a routine cap: a normal run never fires it.
5
6
  // Every removal is marked in place and footered. Profiles:
@@ -10,21 +11,36 @@
10
11
  // plus every line matching the signal pattern with 2 lines of
11
12
  // context. Lines over 2000 bytes are shortened in place. Hard
12
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.
13
20
  //
14
21
  // Bytes are counted as raw bytes (as `LC_ALL=C awk` counts them), never as
15
22
  // characters, so a multi-byte line is measured by what it costs on disk.
23
+ //
24
+ // A cut file keeps its untouched original as `{name}.raw.{ext}` in the outbox
25
+ // (`keepRaw`), never under `logs/`; the record names it (`raw`) with the command
26
+ // that produced the file (`source`) and when it ran (`fetchedAt`).
16
27
  import { spawnSync } from "node:child_process";
17
28
  import * as fs from "node:fs";
18
29
  import * as path from "node:path";
19
30
  import { CONTEXT_FETCH_CONTEXTS, parseContextFetchStart, } from "../../checks/before/context-fetch.js";
20
- import { extractContextFetchProvisionRecipes } from "../../install/cloud-env.js";
31
+ import { UNAVAILABLE_RELPATH, extractContextFetchProvisionRecipes, renderCloudContextFetchProvision, } from "../../install/cloud-env.js";
21
32
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
22
- import { lastRun } from "../../ledgers/status.js";
23
- import { CommandError, EXIT, git, } from "../lib.js";
24
- import { resolveRepoSlug } from "../../ledgers/telemetry.js";
33
+ import { lastRun, validateCiSelection } from "../../ledgers/status.js";
34
+ import { CommandError, EXIT, git, outboxRel, outboxRoot, } from "../lib.js";
35
+ import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
36
+ import { parseJson } from "../../shared/json.js";
37
+ import { checkedTable } from "../../shared/text.js";
25
38
  import { buildComment } from "./issues.js";
26
- import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
39
+ import { derivedTestMatrix, parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
40
+ import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
41
+ import { EXIT_NO_STATUS, FILE_FLAG, positiveInt, readRuns, str } from "./status.js";
27
42
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
43
+ import { RED_PROVEN, doneTasks, redEntries, redKey, testSpan } from "./tests.js";
28
44
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
29
45
  export const EXIT_ARTIFACT = 4;
30
46
  // ---------------------------------------------------------------------------
@@ -52,6 +68,37 @@ export const fenced = (payload) => Buffer.concat([
52
68
  payload,
53
69
  Buffer.from(`${FENCE_CLOSE}\n`),
54
70
  ]);
71
+ const RENDERS = ["table", "raw"];
72
+ /**
73
+ * Copy the original of a file about to be trimmed or rendered to
74
+ * `{rawDir}/{name}.raw.{ext}`, byte for byte; `content` stands in for a file that
75
+ * was never written whole. Returns the copy's path.
76
+ */
77
+ export function keepRaw(file, rawDir, content) {
78
+ const ext = path.extname(file);
79
+ const raw = path.join(rawDir, `${path.basename(file, ext)}.raw${ext}`);
80
+ fs.mkdirSync(rawDir, { recursive: true });
81
+ if (content === undefined)
82
+ fs.copyFileSync(file, raw);
83
+ else
84
+ fs.writeFileSync(raw, content);
85
+ return raw;
86
+ }
87
+ /** `keepRaw`, with a failed copy handed back as its error so the caller picks the exit code. */
88
+ function keepRawOrError(file, rawDir) {
89
+ try {
90
+ return keepRaw(file, rawDir);
91
+ }
92
+ catch (err) {
93
+ return err instanceof Error ? err : new Error(String(err));
94
+ }
95
+ }
96
+ /** The outbox folder a feature's originals go to (the outbox root without a fid); null outside a repo. */
97
+ export function rawDirFor(cwd, fid) {
98
+ const root = outboxRoot(cwd);
99
+ return root === null ? null : path.join(root, fid ?? "");
100
+ }
101
+ const utcNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
55
102
  const LEDGER = { maxLines: 200, maxBytes: 51200 };
56
103
  const EVIDENCE = {
57
104
  softLines: 3000,
@@ -65,12 +112,15 @@ const EVIDENCE = {
65
112
  hardLines: 12000,
66
113
  hardBytes: 1572864,
67
114
  };
68
- export const CLAMP_PROFILES = ["ledger", "debug-evidence"];
115
+ export const CLAMP_PROFILES = ["ledger", "debug-evidence", "ci", "e2e", "runtime"];
69
116
  /**
70
117
  * Lowercase substrings matched against a lowercased line. Broad: `error` also covers
71
- * `##[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.
72
121
  */
73
122
  const SIGNALS = [
123
+ "===== truncated: ",
74
124
  "error",
75
125
  "fail",
76
126
  "exception",
@@ -85,6 +135,50 @@ const SIGNALS = [
85
135
  "●",
86
136
  "×",
87
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;
88
182
  /** awk records: a final line with no newline is one, a trailing newline does not start another. */
89
183
  function records(buf) {
90
184
  const out = [];
@@ -99,12 +193,12 @@ function records(buf) {
99
193
  out.push(buf.subarray(start));
100
194
  return out;
101
195
  }
102
- function hasSignal(line) {
196
+ function hasSignal(line, signals) {
103
197
  const lower = Buffer.from(line);
104
198
  for (let i = 0; i < lower.length; i++)
105
199
  if (lower[i] >= 65 && lower[i] <= 90)
106
200
  lower[i] += 32;
107
- return SIGNALS.some((s) => lower.includes(s));
201
+ return signals.some((s) => lower.includes(s));
108
202
  }
109
203
  /** awk's human size: B, rounded KB, or MB to one decimal (ties to even, as printf). */
110
204
  export function humanBytes(b) {
@@ -146,7 +240,7 @@ function selectLedger(buf) {
146
240
  body: rows.slice(0, keep).flatMap((r) => [r, Buffer.from("\n")]),
147
241
  };
148
242
  }
149
- function selectEvidence(buf) {
243
+ function selectEvidence(buf, signals) {
150
244
  const p = EVIDENCE;
151
245
  const raw = records(buf);
152
246
  const n = raw.length;
@@ -191,7 +285,7 @@ function selectEvidence(buf) {
191
285
  // otherwise lose its immunity.
192
286
  let ceiling = false;
193
287
  for (let i = 0; i < n; i++) {
194
- if (!hasSignal(raw[i]))
288
+ if (!hasSignal(raw[i], signals))
195
289
  continue;
196
290
  const a = Math.max(0, i - p.context);
197
291
  const b = Math.min(n - 1, i + p.context);
@@ -264,7 +358,7 @@ function selectEvidence(buf) {
264
358
  * left byte-identical; otherwise the kept content plus footer replace it via a
265
359
  * sibling temp file, never truncating in place.
266
360
  */
267
- export function clampFile(file, profile, artifact = file) {
361
+ export function clampFile(file, profile, artifact = file, keep) {
268
362
  if (!CLAMP_PROFILES.includes(profile)) {
269
363
  throw new CommandError(EXIT.USAGE, `unknown profile '${profile}' (known: ${CLAMP_PROFILES.join(", ")})`);
270
364
  }
@@ -273,7 +367,9 @@ export function clampFile(file, profile, artifact = file) {
273
367
  throw new CommandError(EXIT_ARTIFACT, `cannot read artifact '${artifact}': ${read.problem}`);
274
368
  }
275
369
  const buf = read.buf;
276
- const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
370
+ const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf, signalsFor(profile));
371
+ const source = keep?.source ?? null;
372
+ const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
277
373
  const untouched = (s) => ({
278
374
  artifact,
279
375
  clamped: false,
@@ -283,9 +379,20 @@ export function clampFile(file, profile, artifact = file) {
283
379
  keptBytes: s?.keptBytes ?? buf.length,
284
380
  lineCapped: 0,
285
381
  ceilingHit: false,
382
+ raw: null,
383
+ source,
384
+ fetchedAt,
286
385
  });
287
386
  if (sel === null || sel.body.length === 0)
288
387
  return untouched(sel);
388
+ let raw = keep?.original ?? null;
389
+ if (raw === null && keep?.rawDir) {
390
+ const kept = keepRawOrError(file, keep.rawDir);
391
+ // The trim would lose the only copy: refuse it, the file stays whole.
392
+ if (kept instanceof Error)
393
+ throw new CommandError(EXIT_ARTIFACT, `cannot keep the original of '${artifact}': ${kept.message}`);
394
+ raw = kept;
395
+ }
289
396
  const footer = [];
290
397
  if (sel.lineCapped > 1) {
291
398
  footer.push(`> [bkit] ${sel.lineCapped} over-long lines were shortened; each says so inline.`);
@@ -310,6 +417,9 @@ export function clampFile(file, profile, artifact = file) {
310
417
  keptBytes: sel.keptBytes,
311
418
  lineCapped: sel.lineCapped,
312
419
  ceilingHit: sel.ceilingHit,
420
+ raw: raw === null ? null : outboxRel(path.dirname(file), raw),
421
+ source,
422
+ fetchedAt,
313
423
  };
314
424
  }
315
425
  function readable(file) {
@@ -335,6 +445,43 @@ function replaceFile(file, tmp, content) {
335
445
  return err.message;
336
446
  }
337
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
+ }
338
485
  // ---------------------------------------------------------------------------
339
486
  // Clamp log — records cross the gap between the block that writes an artifact
340
487
  // and the block that records the step's status row.
@@ -375,7 +522,16 @@ const RECORD_OUTPUT = {
375
522
  keptBytes: "content bytes kept",
376
523
  lineCapped: "over-long lines shortened in place",
377
524
  ceilingHit: "true when the hard ceiling dropped matching lines too",
525
+ raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
526
+ source: "the command that produced the file (--source), or null",
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",
378
529
  };
530
+ /** Say so when a cut had nowhere to keep its original. */
531
+ function warnNoRaw(ctx, record, keep) {
532
+ if (record.clamped && record.raw === null && keep.rawDir === null)
533
+ ctx.log(`${record.artifact}: not inside a git repo — original not kept`);
534
+ }
379
535
  // ---------------------------------------------------------------------------
380
536
  // Ledger scan — plan Step 4's related deferrals / failures
381
537
  // ---------------------------------------------------------------------------
@@ -518,24 +674,451 @@ function asCaptured(out) {
518
674
  return Buffer.concat([bytes.subarray(0, end), Buffer.from("\n")]);
519
675
  }
520
676
  // ---------------------------------------------------------------------------
677
+ // Diff artifact — the one definition of "the run's diff"
678
+ //
679
+ // Build briefs, the challenge size gate and per-group verify read the same range
680
+ // the same way: `{base}...HEAD` with `docs/plans/**` excluded, written to one
681
+ // file. Past the guard the file holds a per-file budget instead of the whole diff
682
+ // (`--stat`, then the largest files first, each cut), and its first line says so.
683
+ // ---------------------------------------------------------------------------
684
+ /** Exit code: --base does not name a commit. */
685
+ export const EXIT_BASE = 5;
686
+ export const DIFF_BASE = "origin/dev";
687
+ export const DIFF_EXCLUDES = ["docs/plans/**"];
688
+ export const PARTIAL_MARK = "partial diff coverage";
689
+ export const DIFF_GUARD = {
690
+ fullLines: 10000,
691
+ topFiles: 20,
692
+ perFileLines: 500,
693
+ totalLines: 50000,
694
+ };
695
+ /** git's stdout as bytes; empty when git fails (a range it rejects diffs as nothing). */
696
+ function gitBytes(cwd, args) {
697
+ const res = spawnSync("git", args, { cwd, env: gitEnv(), maxBuffer: 1 << 29 });
698
+ return res.status === 0 ? (res.stdout ?? Buffer.alloc(0)) : Buffer.alloc(0);
699
+ }
700
+ const excludeSpec = () => ["--", ".", ...DIFF_EXCLUDES.map((e) => `:(exclude)${e}`)];
701
+ /** Per-file `--numstat` rows over the range and excludes; a binary file counts with no lines. */
702
+ export function diffNumstat(cwd, range) {
703
+ const files = [];
704
+ let linesAdded = 0;
705
+ let linesDeleted = 0;
706
+ const rows = gitBytes(cwd, ["diff", "--numstat", "--no-renames", range, ...excludeSpec()])
707
+ .toString("utf-8")
708
+ .split("\n");
709
+ for (const row of rows) {
710
+ if (row === "")
711
+ continue;
712
+ const [a, d, ...rest] = row.split("\t");
713
+ const added = Number(a) || 0;
714
+ const deleted = Number(d) || 0;
715
+ linesAdded += added;
716
+ linesDeleted += deleted;
717
+ files.push({ path: rest.join("\t"), lines: added + deleted });
718
+ }
719
+ return {
720
+ files,
721
+ stat: {
722
+ filesChanged: files.length,
723
+ linesAdded,
724
+ linesDeleted,
725
+ linesChanged: linesAdded + linesDeleted,
726
+ },
727
+ };
728
+ }
729
+ const joinLines = (lines) => lines.length === 0 ? Buffer.alloc(0) : Buffer.concat([...lines.flatMap((l) => [l, lineOf("")])]);
730
+ /** {@link writeDiffArtifact}; the artifact, or the error text when the write fails. */
731
+ function tryWriteDiffArtifact(...args) {
732
+ try {
733
+ return { ok: true, result: writeDiffArtifact(...args) };
734
+ }
735
+ catch (err) {
736
+ // Reported as the artifact exit code, with the reason.
737
+ return { ok: false, error: err.message };
738
+ }
739
+ }
740
+ /** Write the range's diff to `out`: whole under the guard, else a per-file budget; the record says which. */
741
+ export function writeDiffArtifact(cwd, out, artifact, range, guard = DIFF_GUARD, keep = { rawDir: null }) {
742
+ const fetchedAt = utcNow();
743
+ const { files, stat } = diffNumstat(cwd, range);
744
+ const full = gitBytes(cwd, ["diff", range, ...excludeSpec()]);
745
+ const diffLines = records(full).length;
746
+ let content;
747
+ let partial = false;
748
+ let ceilingHit = false;
749
+ const omitted = [];
750
+ if (diffLines === 0) {
751
+ content = lineOf(`No changes in ${range} outside ${DIFF_EXCLUDES.join(", ")}.`);
752
+ }
753
+ else if (diffLines <= guard.fullLines) {
754
+ content = full;
755
+ }
756
+ else {
757
+ partial = true;
758
+ const ranked = [...files].sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path));
759
+ const shown = ranked.slice(0, guard.topFiles);
760
+ const stat0 = gitBytes(cwd, ["diff", "--stat", range, ...excludeSpec()]);
761
+ // Header, omitted-files line, a blank, --stat and a blank count toward the total.
762
+ const room0 = guard.totalLines - (4 + records(stat0).length);
763
+ const body = [];
764
+ let used = 0;
765
+ const add = (b) => {
766
+ body.push(b);
767
+ used += records(b).length;
768
+ };
769
+ let stopped = false;
770
+ for (const f of ranked) {
771
+ if (stopped || !shown.includes(f)) {
772
+ omitted.push(f.path);
773
+ continue;
774
+ }
775
+ const room = Math.min(guard.perFileLines, room0 - used);
776
+ if (room <= 0) {
777
+ ceilingHit = true;
778
+ stopped = true;
779
+ omitted.push(f.path);
780
+ add(lineOf(`# total line budget reached; ${f.path} and smaller files not shown`));
781
+ continue;
782
+ }
783
+ const lines = records(gitBytes(cwd, ["diff", range, "--", f.path]));
784
+ const kept = lines.slice(0, room);
785
+ if (kept.length < lines.length && room < guard.perFileLines)
786
+ ceilingHit = true;
787
+ add(lineOf(`### ${f.path}`));
788
+ add(joinLines(kept));
789
+ if (kept.length < lines.length) {
790
+ omitted.push(f.path);
791
+ add(lineOf(`# ${lines.length - kept.length} more lines of ${f.path} not shown`));
792
+ }
793
+ add(lineOf(""));
794
+ }
795
+ omitted.sort((a, b) => a.localeCompare(b));
796
+ content = Buffer.concat([
797
+ lineOf(`# ${PARTIAL_MARK}: ${range} has ${diffLines} diff lines across ${stat.filesChanged} files; showing the ${shown.length} largest files, ${guard.perFileLines} lines each, at most ${guard.totalLines} lines in all. Say "${PARTIAL_MARK}" in any verdict read from this file.`),
798
+ lineOf(`# not shown whole: ${omitted.join(", ")}`),
799
+ lineOf(""),
800
+ stat0,
801
+ lineOf(""),
802
+ ...body,
803
+ ]);
804
+ }
805
+ const raw = partial && keep.rawDir !== null ? keepRaw(out, keep.rawDir, full) : null;
806
+ fs.mkdirSync(path.dirname(out), { recursive: true });
807
+ fs.writeFileSync(out, content);
808
+ const record = {
809
+ artifact,
810
+ clamped: partial,
811
+ origLines: diffLines,
812
+ keptLines: partial ? records(content).length : diffLines,
813
+ origBytes: full.length,
814
+ keptBytes: content.length,
815
+ lineCapped: 0,
816
+ ceilingHit,
817
+ raw: raw === null ? null : outboxRel(cwd, raw),
818
+ source: `git diff ${range} -- . ${DIFF_EXCLUDES.map((e) => `':(exclude)${e}'`).join(" ")}`,
819
+ fetchedAt,
820
+ };
821
+ return { range, stat, diffLines, partial, omitted, record };
822
+ }
823
+ // ---------------------------------------------------------------------------
824
+ // Brief — what one group's build agents read
825
+ //
826
+ // The engine writes it so the orchestrator never reads the plan: the plan's
827
+ // why and what, where the group sits, the group's open task blocks verbatim,
828
+ // one-line summaries of the earlier tasks they depend on, the Reuse Inventory
829
+ // rows and Architecture entries for the open tasks' files, and the deviations
830
+ // note when there is one.
831
+ // ---------------------------------------------------------------------------
832
+ /** A brief whose work section is over this many bytes warns: the group may not fit one fresh context. */
833
+ export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
834
+ /** The plan sections a brief carries as its why and what, by heading text. */
835
+ const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
836
+ /** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
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$/;
840
+ /** A heading's text without leading emoji and marks. */
841
+ const headingText = (text) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
842
+ /**
843
+ * The body of the first heading named `name`, up to the next heading of the
844
+ * same or a higher level. Lines inside code fences are never headings.
845
+ */
846
+ function planSection(lines, name) {
847
+ let start = -1;
848
+ let level = 0;
849
+ let fence = false;
850
+ for (let i = 0; i < lines.length; i++) {
851
+ const line = lines[i];
852
+ if (/^\s*(`{3,}|~{3,})/.test(line))
853
+ fence = !fence;
854
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
855
+ if (m === null)
856
+ continue;
857
+ if (start >= 0 && m[1].length <= level)
858
+ return lines.slice(start, i).join("\n").trim();
859
+ if (start < 0 && headingText(m[2]) === name) {
860
+ start = i + 1;
861
+ level = m[1].length;
862
+ }
863
+ }
864
+ return start < 0 ? undefined : lines.slice(start).join("\n").trim();
865
+ }
866
+ /** Every task number a plan-execute log in `dir` records `DONE`. */
867
+ function loggedDone(dir) {
868
+ const done = new Set();
869
+ if (!fs.existsSync(dir))
870
+ return done;
871
+ for (const f of fs.readdirSync(dir).filter((f) => TASKS_LOG.test(f)))
872
+ for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8")))
873
+ done.add(n);
874
+ return done;
875
+ }
876
+ /** The plan sections whose entries a brief copies for the group's files. */
877
+ const INVENTORY_SECTION = "Reuse Inventory";
878
+ const ARCHITECTURE_SECTION = "Architecture & Component Changes";
879
+ /** Backticked repo-relative paths in `text`, normalised. */
880
+ const backticked = (text) => [...text.matchAll(/`([^`]+)`/g)].map((m) => path.posix.normalize(m[1]));
881
+ /**
882
+ * The Reuse Inventory table's header and separator lines (`reuseInventory`), and its rows
883
+ * whose `File` cell names a file in `files`. No table or no `File` column → no rows.
884
+ */
885
+ function inventoryRows(lines, files) {
886
+ const table = reuseInventory(lines.join("\n"));
887
+ if (table === null)
888
+ return { head: [], rows: [] };
889
+ const rows = table.rows.filter((r) => r.files.some((f) => files.has(f))).map((r) => r.line);
890
+ return { head: table.head, rows };
891
+ }
892
+ /**
893
+ * The Architecture & Component Changes entries whose heading names a file in `files`:
894
+ * the heading through the line before the next heading of the same or a higher level.
895
+ * Lines inside code fences are never headings.
896
+ */
897
+ function architectureEntries(lines, files) {
898
+ const body = (planSection(lines, ARCHITECTURE_SECTION) ?? "").split("\n");
899
+ const heads = [];
900
+ let fence = false;
901
+ body.forEach((line, i) => {
902
+ if (/^\s*(`{3,}|~{3,})/.test(line))
903
+ fence = !fence;
904
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
905
+ if (m !== null)
906
+ heads.push({ i, level: m[1].length, text: m[2] });
907
+ });
908
+ return heads.flatMap((h, k) => {
909
+ if (!backticked(h.text).some((f) => files.has(f)))
910
+ return [];
911
+ const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.i ?? body.length;
912
+ return [body.slice(h.i, end).join("\n").trim()];
913
+ });
914
+ }
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$`);
918
+ const taken = fs.existsSync(dir)
919
+ ? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
920
+ : [];
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;
941
+ }
942
+ /** The brief's text and its work section's size in bytes. */
943
+ export function briefText(o) {
944
+ const lines = o.plan.split("\n");
945
+ const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
946
+ const out = [
947
+ `# Brief: group ${o.group.group} — ${o.group.title}${o.testsOnly ? " (tests)" : ""}`,
948
+ "",
949
+ `Plan: ${title}`,
950
+ "",
951
+ ];
952
+ out.push("## Why and what", "");
953
+ for (const name of BRIEF_SECTIONS) {
954
+ const body = planSection(lines, name);
955
+ if (body !== undefined && body !== "")
956
+ out.push(`### ${name}`, "", body, "");
957
+ }
958
+ out.push("## Where it fits", "");
959
+ const nextGroup = o.groups.find((g) => g.group > o.group.group && g.tasks.some((t) => !o.isDone(t)));
960
+ for (const g of o.groups) {
961
+ const state = g.tasks.every(o.isDone)
962
+ ? "done"
963
+ : g === o.group
964
+ ? "this group"
965
+ : g === nextGroup
966
+ ? "next"
967
+ : g.group > o.group.group
968
+ ? "later"
969
+ : "open";
970
+ out.push(`- Group ${g.group}: ${g.title} — ${state}`);
971
+ for (const t of g.tasks)
972
+ out.push(` - TASK ${t.task}: ${t.title} — ${o.isDone(t) ? "done" : "open"}`);
973
+ }
974
+ out.push("");
975
+ const open = o.group.tasks.filter((t) => !o.isDone(t));
976
+ const work = ["## The work", ""];
977
+ for (const t of open)
978
+ work.push(t.text.trim(), "");
979
+ const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
980
+ .filter((n) => !o.group.tasks.some((t) => t.task === n))
981
+ .sort((a, b) => a - b)
982
+ .map((n) => o.groups.flatMap((g) => g.tasks).find((t) => t.task === n))
983
+ .filter((t) => t !== undefined);
984
+ if (deps.length > 0) {
985
+ work.push("### Earlier tasks this group depends on", "");
986
+ for (const t of deps) {
987
+ const files = [...new Set([...t.create, ...t.update, ...t.delete].map((r) => r.file))];
988
+ const where = files.length > 0 ? ` — ${files.map((f) => `\`${f}\``).join(", ")}` : "";
989
+ work.push(`- TASK ${t.task} (group ${t.group}, ${o.isDone(t) ? "done" : "open"}): ${t.title}${where}`);
990
+ }
991
+ work.push("");
992
+ }
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));
1005
+ out.push(...work);
1006
+ if (o.note !== undefined)
1007
+ out.push("## Deviations", "", o.note.trim(), "");
1008
+ return {
1009
+ text: out.join("\n"),
1010
+ workBytes: Buffer.byteLength(work.join("\n")),
1011
+ };
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
+ }
1024
+ /**
1025
+ * The Reuse Inventory rows, then the Architecture entries, for the files on the open
1026
+ * tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
1027
+ * within BRIEF_WORK_WARN_BYTES; the rest are counted in a closing line naming where to
1028
+ * read them.
1029
+ */
1030
+ function planEntries(lines, open, work, planFile) {
1031
+ const files = new Set(open.flatMap((t) => [...t.create, ...t.update, ...t.delete].map((r) => path.posix.normalize(r.file))));
1032
+ const inventory = inventoryRows(lines, files);
1033
+ const arch = architectureEntries(lines, files);
1034
+ const keptRows = [];
1035
+ const keptArch = [];
1036
+ const render = (rowsLeft, archLeft) => {
1037
+ const part = [];
1038
+ if (keptRows.length > 0)
1039
+ part.push("### Reuse Inventory rows", "", ...inventory.head, ...keptRows, "");
1040
+ if (keptArch.length > 0)
1041
+ part.push("### Architecture entries", "", ...keptArch.flatMap((e) => [e, ""]));
1042
+ if (rowsLeft + archLeft > 0)
1043
+ part.push(`Reuse Inventory rows left out: ${rowsLeft}; Architecture entries left out: ${archLeft} — read them in ${planFile} § ${INVENTORY_SECTION} and § ${ARCHITECTURE_SECTION}.`, "");
1044
+ return part;
1045
+ };
1046
+ const fits = (rowsLeft, archLeft) => Buffer.byteLength([...work, ...render(rowsLeft, archLeft)].join("\n")) <= BRIEF_WORK_WARN_BYTES;
1047
+ // The counts passed to `fits` are those not yet kept, an upper bound on the final ones.
1048
+ let rowsLeft = inventory.rows.length;
1049
+ let archLeft = arch.length;
1050
+ for (const row of inventory.rows) {
1051
+ keptRows.push(row);
1052
+ if (fits(rowsLeft - 1, archLeft))
1053
+ rowsLeft--;
1054
+ else
1055
+ keptRows.pop();
1056
+ }
1057
+ for (const entry of arch) {
1058
+ keptArch.push(entry);
1059
+ if (fits(rowsLeft, archLeft - 1))
1060
+ archLeft--;
1061
+ else
1062
+ keptArch.pop();
1063
+ }
1064
+ return render(rowsLeft, archLeft);
1065
+ }
1066
+ // ---------------------------------------------------------------------------
521
1067
  // Command
522
1068
  // ---------------------------------------------------------------------------
1069
+ const RUN_BLOCK_FLAGS = [
1070
+ { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1071
+ {
1072
+ name: "script",
1073
+ type: "string",
1074
+ required: true,
1075
+ help: "file holding the block body as customised for this failure (run with bash)",
1076
+ },
1077
+ FID_FLAG,
1078
+ MONTH_FLAG,
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
+ },
1085
+ ];
1086
+ const RUN_BLOCK_OUTPUT = {
1087
+ outcome: "checked (validated data written) | unchecked (selected CI evidence invalid) | self-skipped (skip line written) | silent (nothing) | not-run",
1088
+ artifact: "the artifact path, or null when nothing was written",
1089
+ skip: "the block's [context-fetch:<name>] stderr line, or null",
1090
+ clamp: "the payload's clamp record, or null",
1091
+ reason: "why the block was not run, or null",
1092
+ };
523
1093
  export const contextCommand = {
524
1094
  noun: "context",
525
- summary: "Clamp context artifacts; scan ledgers; list, run and record consumer context-fetch blocks.",
1095
+ summary: "Clamp context artifacts; scan ledgers; write the run's diff and a build group's brief; list, run and record consumer context-fetch blocks.",
526
1096
  verbs: {
527
1097
  clamp: {
528
1098
  summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
1099
+ use: "workflow",
529
1100
  flags: [
530
1101
  { name: "artifact", type: "string", required: true, help: "file to clamp" },
531
- { name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
1102
+ { name: "profile", type: "string", required: true, help: CLAMP_PROFILES.join(" | ") },
1103
+ {
1104
+ name: "source",
1105
+ type: "string",
1106
+ help: "the exact command and inputs that produced the artifact (recorded with the time)",
1107
+ },
532
1108
  ...LOG_FLAGS,
533
1109
  ],
534
1110
  output: RECORD_OUTPUT,
535
- exitCodes: { [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced" },
1111
+ exitCodes: {
1112
+ [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced; or its original could not be kept",
1113
+ },
536
1114
  run: (ctx) => {
537
1115
  const artifact = String(ctx.flags.artifact);
538
- const record = clampFile(path.resolve(ctx.cwd, artifact), String(ctx.flags.profile), artifact);
1116
+ const keep = {
1117
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1118
+ source: str(ctx.flags.source),
1119
+ };
1120
+ const record = clampFile(path.resolve(ctx.cwd, artifact), String(ctx.flags.profile), artifact, keep);
1121
+ warnNoRaw(ctx, record, keep);
539
1122
  const log = logPath(ctx);
540
1123
  if (log !== undefined)
541
1124
  appendRecord(log, record);
@@ -547,6 +1130,7 @@ export const contextCommand = {
547
1130
  },
548
1131
  "clamp-log": {
549
1132
  summary: "Read a step's clamp records (the status row's clamped array), or reset the log.",
1133
+ use: "workflow",
550
1134
  flags: [
551
1135
  ...LOG_FLAGS,
552
1136
  { name: "reset", type: "boolean", help: "empty the log first (the step's first writer)" },
@@ -569,6 +1153,7 @@ export const contextCommand = {
569
1153
  },
570
1154
  "ledger-scan": {
571
1155
  summary: "Write a ledger's lines matching query terms, strongest first, then clamp (ledger profile).",
1156
+ use: "workflow",
572
1157
  flags: [
573
1158
  { name: "terms", type: "string", required: true, help: "space-separated query terms" },
574
1159
  {
@@ -590,6 +1175,7 @@ export const contextCommand = {
590
1175
  kept: "lines written (at most 40)",
591
1176
  clamp: "the clamp record",
592
1177
  },
1178
+ textOmit: ["clamp"],
593
1179
  exitCodes: { [EXIT_ARTIFACT]: "artifact could not be written or replaced" },
594
1180
  run: (ctx) => {
595
1181
  const log = logPath(ctx);
@@ -601,12 +1187,18 @@ export const contextCommand = {
601
1187
  }
602
1188
  const sourceFile = path.resolve(ctx.cwd, String(ctx.flags.source));
603
1189
  const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf-8") : undefined;
604
- const scan = ledgerScan(source, String(ctx.flags.terms));
1190
+ const terms = String(ctx.flags.terms);
1191
+ const scan = ledgerScan(source, terms);
605
1192
  const artifact = String(ctx.flags.artifact);
606
1193
  const out = path.resolve(ctx.cwd, artifact);
607
1194
  fs.mkdirSync(path.dirname(out), { recursive: true });
608
1195
  fs.writeFileSync(out, scan.content);
609
- const clamp = clampFile(out, "ledger", artifact);
1196
+ const keep = {
1197
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1198
+ source: `bkit context ledger-scan --source=${String(ctx.flags.source)} --terms="${terms}"`,
1199
+ };
1200
+ const clamp = clampFile(out, "ledger", artifact, keep);
1201
+ warnNoRaw(ctx, clamp, keep);
610
1202
  if (log !== undefined)
611
1203
  appendRecord(log, clamp);
612
1204
  ctx.log(`${artifact}: ${scan.total} matching line(s), ${scan.kept} kept`);
@@ -614,14 +1206,221 @@ export const contextCommand = {
614
1206
  return EXIT.OK;
615
1207
  },
616
1208
  },
1209
+ diff: {
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",
1212
+ flags: [
1213
+ { name: "artifact", type: "string", required: true, help: "file to write" },
1214
+ {
1215
+ name: "base",
1216
+ type: "string",
1217
+ help: `merge base or a group's start commit (default ${DIFF_BASE})`,
1218
+ },
1219
+ ...LOG_FLAGS,
1220
+ {
1221
+ name: "reset-log",
1222
+ type: "boolean",
1223
+ help: "empty the clamp log first (the step's first writer)",
1224
+ },
1225
+ ],
1226
+ output: {
1227
+ artifact: "the artifact path as given",
1228
+ base: "the base used",
1229
+ range: "the range diffed ({base}...HEAD)",
1230
+ filesChanged: "files in the diff (--numstat, same excludes)",
1231
+ linesAdded: "lines added",
1232
+ linesDeleted: "lines deleted",
1233
+ linesChanged: "linesAdded + linesDeleted",
1234
+ diffLines: "lines in the whole diff",
1235
+ partial: `true when the diff exceeded ${DIFF_GUARD.fullLines} lines and the per-file budget (${DIFF_GUARD.topFiles} files, ${DIFF_GUARD.perFileLines} lines each, ${DIFF_GUARD.totalLines} in all) was written instead`,
1236
+ omitted: "files whose diff is not in the artifact whole (not shown, or cut); [] unless partial — the artifact's second line lists them too",
1237
+ clamp: "the clamp record (clamped = partial; raw = the whole diff in the outbox when partial)",
1238
+ },
1239
+ textOmit: ["clamp"],
1240
+ exitCodes: {
1241
+ [EXIT_BASE]: "--base does not name a commit",
1242
+ [EXIT_ARTIFACT]: "the artifact could not be written",
1243
+ },
1244
+ run: (ctx) => {
1245
+ const base = str(ctx.flags.base) ?? DIFF_BASE;
1246
+ if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
1247
+ throw new CommandError(EXIT_BASE, `--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`);
1248
+ }
1249
+ const artifact = String(ctx.flags.artifact);
1250
+ const log = logPath(ctx);
1251
+ if (ctx.flags.resetLog === true) {
1252
+ if (log === undefined)
1253
+ throw new CommandError(EXIT.USAGE, "--reset-log needs --log, or --fid and --step");
1254
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1255
+ fs.writeFileSync(log, "");
1256
+ }
1257
+ const written = tryWriteDiffArtifact(ctx.cwd, path.resolve(ctx.cwd, artifact), artifact, `${base}...HEAD`, DIFF_GUARD, { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) });
1258
+ if (!written.ok)
1259
+ throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
1260
+ const result = written.result;
1261
+ if (log !== undefined)
1262
+ appendRecord(log, result.record);
1263
+ if (result.partial) {
1264
+ ctx.log(`${artifact}: ${result.diffLines} diff lines, over the ${DIFF_GUARD.fullLines}-line guard — per-file budget written (${PARTIAL_MARK})`);
1265
+ }
1266
+ ctx.emit({
1267
+ artifact,
1268
+ base,
1269
+ range: result.range,
1270
+ ...result.stat,
1271
+ diffLines: result.diffLines,
1272
+ partial: result.partial,
1273
+ omitted: result.omitted,
1274
+ clamp: result.record,
1275
+ });
1276
+ return EXIT.OK;
1277
+ },
1278
+ },
1279
+ brief: {
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",
1282
+ flags: [
1283
+ { name: "plan", type: "string", required: true, help: "the plan file" },
1284
+ { name: "group", type: "string", help: "the group to brief" },
1285
+ {
1286
+ name: "next",
1287
+ type: "boolean",
1288
+ help: "brief the first group with an open task (none open → nothing written, group null)",
1289
+ },
1290
+ {
1291
+ name: "dir",
1292
+ type: "string",
1293
+ required: true,
1294
+ help: "the run's logs folder: the brief is written there, and its build-plan-tasks-*-log.md DONE lines mark tasks done",
1295
+ },
1296
+ {
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",
1305
+ },
1306
+ {
1307
+ name: "note-file",
1308
+ type: "string",
1309
+ help: "text for the Deviations section (left out when not given)",
1310
+ },
1311
+ ],
1312
+ output: {
1313
+ artifact: "the brief's path (null when --next finds no open group)",
1314
+ bytes: "the brief's size in bytes",
1315
+ group: "the group briefed (null when --next finds no open group)",
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)",
1318
+ workBytes: "the work section's size in bytes (0 when --next finds no open group)",
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`,
1320
+ },
1321
+ exitCodes: {
1322
+ [EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
1323
+ },
1324
+ run: (ctx) => {
1325
+ const groupFlag = positiveInt(ctx.flags.group, "group");
1326
+ if ((groupFlag === undefined) === (ctx.flags.next !== true))
1327
+ throw new CommandError(EXIT.USAGE, "give exactly one of --group=N and --next");
1328
+ const planFile = path.resolve(ctx.cwd, String(ctx.flags.plan));
1329
+ if (!fs.existsSync(planFile))
1330
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)} does not exist`);
1331
+ const plan = fs.readFileSync(planFile, "utf-8");
1332
+ const blocks = parsePlanBlocks(plan);
1333
+ if (blocks.errors.length > 0) {
1334
+ const e = blocks.errors[0];
1335
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)}:${e.line}: ${e.message} — run \`bkit tests plan-check\``);
1336
+ }
1337
+ const dir = path.resolve(ctx.cwd, String(ctx.flags.dir));
1338
+ const done = loggedDone(dir);
1339
+ const isDone = (t) => t.done || done.has(t.task);
1340
+ const group = groupFlag === undefined
1341
+ ? blocks.groups.find((g) => g.tasks.some((t) => !isDone(t)))
1342
+ : blocks.groups.find((g) => g.group === groupFlag);
1343
+ if (group === undefined && groupFlag !== undefined)
1344
+ throw new CommandError(EXIT.USAGE, `the plan has no group ${groupFlag}`);
1345
+ if (group === undefined) {
1346
+ ctx.emit({
1347
+ artifact: null,
1348
+ bytes: 0,
1349
+ group: null,
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,
1375
+ workBytes: 0,
1376
+ workCap: BRIEF_WORK_WARN_BYTES,
1377
+ });
1378
+ return EXIT.OK;
1379
+ }
1380
+ const noteFlag = str(ctx.flags.noteFile);
1381
+ const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1382
+ if (noteFile !== undefined && !fs.existsSync(noteFile))
1383
+ throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1384
+ const { text, workBytes } = briefText({
1385
+ plan,
1386
+ planFile: String(ctx.flags.plan),
1387
+ group,
1388
+ groups: blocks.groups,
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,
1394
+ note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1395
+ });
1396
+ const out = nextBriefPath(dir, group.group, testsOnly ? "build-brief-tests" : undefined);
1397
+ fs.mkdirSync(dir, { recursive: true });
1398
+ fs.writeFileSync(out, text);
1399
+ if (workBytes > BRIEF_WORK_WARN_BYTES) {
1400
+ ctx.log(`${out}: the work section is ${humanBytes(workBytes)}, over ${humanBytes(BRIEF_WORK_WARN_BYTES)} — the group may not fit one fresh context`);
1401
+ }
1402
+ const artifact = path.isAbsolute(String(ctx.flags.dir)) ? out : path.relative(ctx.cwd, out);
1403
+ ctx.emit({
1404
+ artifact,
1405
+ bytes: Buffer.byteLength(text),
1406
+ group: group.group,
1407
+ tasks: open.map((t) => t.task),
1408
+ tests,
1409
+ workBytes,
1410
+ workCap: BRIEF_WORK_WARN_BYTES,
1411
+ });
1412
+ return EXIT.OK;
1413
+ },
1414
+ },
617
1415
  "list-blocks": {
618
1416
  summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
1417
+ use: "by-hand",
619
1418
  flags: [],
620
1419
  output: {
621
1420
  blocks: "[{idx, context, name, known, prefix, suffix, body}] in file order",
622
1421
  coverage: "blocks per context (runtime, ci, diff, e2e, web)",
623
1422
  contextsConfigured: "contexts with at least one block, in narration order",
624
- 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",
625
1424
  },
626
1425
  run: (ctx) => {
627
1426
  const blocks = fetchBlocks(consumerSection(readContextMd(ctx) ?? ""));
@@ -646,35 +1445,59 @@ export const contextCommand = {
646
1445
  return EXIT.OK;
647
1446
  },
648
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
+ },
649
1459
  "run-block": {
650
1460
  summary: "Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
1461
+ use: "workflow",
1462
+ flags: RUN_BLOCK_FLAGS,
1463
+ output: RUN_BLOCK_OUTPUT,
1464
+ textOmit: ["clamp"],
1465
+ exitCodes: {
1466
+ [EXIT_ARTIFACT]: "the payload could not be clamped or written",
1467
+ [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
1468
+ },
1469
+ run: (ctx) => runBlock(ctx),
1470
+ },
1471
+ fetch: {
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",
651
1474
  flags: [
652
- { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1475
+ ...RUN_BLOCK_FLAGS,
653
1476
  {
654
- name: "script",
1477
+ name: "render",
655
1478
  type: "string",
656
- required: true,
657
- help: "file holding the block body as customised for this failure (run with bash)",
1479
+ help: "table (default): a JSON array of flat objects becomes a markdown table when it reads back unchanged, else the output is written as printed; raw: as printed",
658
1480
  },
659
- FID_FLAG,
660
- MONTH_FLAG,
661
- ...ATTEMPT_FLAGS,
662
1481
  ],
663
1482
  output: {
664
- outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
665
- artifact: "the artifact path, or null when nothing was written",
666
- skip: "the block's [context-fetch:<name>] stderr line, or null",
667
- clamp: "the payload's clamp record, or null",
668
- reason: "why the block was not run, or null",
1483
+ ...RUN_BLOCK_OUTPUT,
1484
+ render: "table | raw: how the output was written; null when nothing was written",
669
1485
  },
1486
+ textOmit: ["clamp"],
670
1487
  exitCodes: {
671
1488
  [EXIT_ARTIFACT]: "the payload could not be clamped or written",
672
1489
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
673
1490
  },
674
- run: (ctx) => runBlock(ctx),
1491
+ run: (ctx) => {
1492
+ const render = str(ctx.flags.render) ?? "table";
1493
+ if (!RENDERS.includes(render))
1494
+ throw new CommandError(EXIT.USAGE, `--render must be ${RENDERS.join("|")}`);
1495
+ return runBlock(ctx, render);
1496
+ },
675
1497
  },
676
1498
  finalise: {
677
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",
678
1501
  flags: [
679
1502
  FID_FLAG,
680
1503
  MONTH_FLAG,
@@ -699,13 +1522,16 @@ export const contextCommand = {
699
1522
  artifacts: "those artifacts, relative to the working directory",
700
1523
  contextsConfigured: "contexts with at least one block",
701
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",
702
1526
  row: "--record: the step-done row written, else null",
703
1527
  commit: "--record: the new commit's sha, else null",
1528
+ progressLine: "--record: the exact chat progress line after a successful numbered completion",
704
1529
  comment: "the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
1530
+ commentFile: COMMENT_FILE_OUTPUT,
705
1531
  },
706
1532
  exitCodes: {
707
1533
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
708
- [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",
709
1535
  },
710
1536
  run: (ctx) => {
711
1537
  const attempt = debugAttempt(ctx);
@@ -724,6 +1550,7 @@ export const contextCommand = {
724
1550
  const blocks = fetchBlocks(consumerSection(readContextMd(ctx) ?? ""));
725
1551
  const contextsConfigured = CONTEXT_FETCH_CONTEXTS.filter((c) => blocks.some((b) => b.context === c));
726
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);
727
1554
  const verdict = artifacts.length > 0 ? "PASS" : "FAIL";
728
1555
  let written = {
729
1556
  row: {},
@@ -735,6 +1562,7 @@ export const contextCommand = {
735
1562
  const file = str(ctx.flags.file);
736
1563
  if (file === undefined)
737
1564
  throw new CommandError(EXIT.USAGE, "--record needs --file");
1565
+ const active = lastRun(readRuns(path.resolve(ctx.cwd, file)), "debug");
738
1566
  written = writeStepRow(ctx.cwd, {
739
1567
  file: path.resolve(ctx.cwd, file),
740
1568
  workflow: "debug",
@@ -742,7 +1570,16 @@ export const contextCommand = {
742
1570
  verdict,
743
1571
  attempt,
744
1572
  artifacts,
745
- 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
+ },
746
1583
  commit: "auto",
747
1584
  message: str(ctx.flags.message),
748
1585
  }, ctx.log);
@@ -771,16 +1608,69 @@ export const contextCommand = {
771
1608
  artifacts,
772
1609
  contextsConfigured,
773
1610
  clamped,
1611
+ clampSummary,
774
1612
  row: record ? written.row : null,
775
1613
  commit: written.commit,
1614
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
776
1615
  comment,
1616
+ commentFile: commentFileOf(ctx.cwd, comment),
777
1617
  });
778
1618
  return written.code;
779
1619
  },
780
1620
  },
781
1621
  },
782
1622
  };
783
- function runBlock(ctx) {
1623
+ /** A block's output as a checked markdown table, or why it stays as printed. */
1624
+ function tableOf(stdout) {
1625
+ const parsed = parseJson(stdout.toString("utf-8"));
1626
+ if (!parsed.ok)
1627
+ return { reason: "not JSON" };
1628
+ const table = checkedTable(parsed.value);
1629
+ return table.ok ? { text: table.text } : { reason: table.reason };
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
+ }
1667
+ /**
1668
+ * Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
1669
+ * (`context fetch`), a JSON array of flat objects is written as a table instead; the
1670
+ * output as printed goes to the outbox first, and the record says which was written.
1671
+ */
1672
+ function runBlock(ctx, render) {
1673
+ const shape = (out, written) => render === undefined ? out : { ...out, render: written };
784
1674
  const idx = positiveInt(ctx.flags.idx, "idx");
785
1675
  const attempt = debugAttempt(ctx);
786
1676
  const fid = String(ctx.flags.fid);
@@ -790,7 +1680,7 @@ function runBlock(ctx) {
790
1680
  const block = fetchBlocks(consumerSection(readContextMd(ctx) ?? "")).find((b) => b.idx === idx);
791
1681
  const notRun = (reason) => {
792
1682
  ctx.log(`context-fetch: ${reason} — NOT RUN`);
793
- ctx.emit({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason });
1683
+ ctx.emit(shape({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason }, null));
794
1684
  return EXIT.OK;
795
1685
  };
796
1686
  if (!block)
@@ -802,11 +1692,33 @@ function runBlock(ctx) {
802
1692
  if (block.body === "")
803
1693
  return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
804
1694
  const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
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
+ });
805
1717
  // The inline block ran inside the step's shell, so these were in scope for it.
806
1718
  const res = spawnSync("bash", [script], {
807
1719
  cwd: ctx.cwd,
808
1720
  env: {
809
- ...process.env,
1721
+ ...childEnv,
810
1722
  REPO_ROOT: repoRoot,
811
1723
  CONTEXT: block.context,
812
1724
  NAME: block.name,
@@ -823,24 +1735,111 @@ function runBlock(ctx) {
823
1735
  const artifact = path.join(logDir(String(ctx.flags.month), fid), `${block.prefix}-${block.suffix}${attempt}.md`);
824
1736
  const out = path.resolve(ctx.cwd, artifact);
825
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;
826
1743
  if (stdout.some((b) => b !== 0x0a && b !== 0)) {
827
1744
  fs.mkdirSync(path.dirname(out), { recursive: true });
828
- fs.writeFileSync(out, asCaptured(stdout));
829
- const clamp = clampFile(out, "debug-evidence", artifact);
1745
+ const keep = {
1746
+ rawDir: rawDirFor(ctx.cwd, fid),
1747
+ source: fs.readFileSync(script, "utf-8"),
1748
+ fetchedAt,
1749
+ };
1750
+ const printed = asCaptured(stdout);
1751
+ let payload = printed;
1752
+ let written = null;
1753
+ if (render !== undefined) {
1754
+ const table = render === "table" ? tableOf(stdout) : null;
1755
+ if (table !== null && "text" in table) {
1756
+ // The table replaces the printed output: keep that output whole first.
1757
+ if (keep.rawDir !== null)
1758
+ keep.original = keepRaw(out, keep.rawDir, stdout);
1759
+ payload = Buffer.from(`${table.text}\n`);
1760
+ written = "table";
1761
+ }
1762
+ else {
1763
+ if (table !== null)
1764
+ ctx.log(`render: raw (${table.reason})`);
1765
+ written = "raw";
1766
+ }
1767
+ }
1768
+ fs.writeFileSync(out, payload);
1769
+ let clamp = clampFile(out, contextProfile(block.context), artifact, keep);
1770
+ warnNoRaw(ctx, clamp, keep);
1771
+ if (written !== null) {
1772
+ const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
1773
+ clamp = { ...clamp, raw, render: written };
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
+ }
830
1779
  appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
831
1780
  fs.writeFileSync(out, fenced(fs.readFileSync(out)));
832
- ctx.log(`${shown} CHECKED — data returned`);
833
- ctx.emit({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null });
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));
834
1791
  return EXIT.OK;
835
1792
  }
836
1793
  if (skip !== undefined) {
837
1794
  fs.mkdirSync(path.dirname(out), { recursive: true });
838
1795
  fs.writeFileSync(out, `${skip}\n`);
839
1796
  ctx.log(`${shown} SELF-SKIPPED (${skip}) — NOT CHECKED; this is NOT evidence that this source was clean (Trusted egress may also silently block the host — see .agents/context.md § Allowed domains)`);
840
- ctx.emit({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null });
1797
+ ctx.emit(shape({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null }, null));
841
1798
  return EXIT.OK;
842
1799
  }
843
1800
  ctx.log(`${shown} produced neither data nor a skip breadcrumb — NOT CHECKED (unexpected silent exit; treat as unavailable, never as clean)`);
844
- ctx.emit({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null });
1801
+ ctx.emit(shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null));
1802
+ return EXIT.OK;
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
+ });
845
1844
  return EXIT.OK;
846
1845
  }