@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,9 +11,19 @@
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
 
17
28
  import { spawnSync } from "node:child_process";
18
29
  import * as fs from "node:fs";
@@ -22,21 +33,38 @@ import {
22
33
  CONTEXT_FETCH_CONTEXTS,
23
34
  parseContextFetchStart,
24
35
  } from "../../checks/before/context-fetch.js";
25
- import { extractContextFetchProvisionRecipes } from "../../install/cloud-env.js";
36
+ import {
37
+ UNAVAILABLE_RELPATH,
38
+ extractContextFetchProvisionRecipes,
39
+ renderCloudContextFetchProvision,
40
+ } from "../../install/cloud-env.js";
26
41
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
27
- import { lastRun } from "../../ledgers/status.js";
42
+ import { lastRun, validateCiSelection, type CiSelection } from "../../ledgers/status.js";
28
43
  import {
29
44
  CommandError,
30
45
  EXIT,
31
46
  git,
47
+ outboxRel,
48
+ outboxRoot,
32
49
  type CommandSpec,
33
50
  type FlagSpec,
34
51
  type RunContext,
35
52
  } from "../lib.js";
36
- import { resolveRepoSlug } from "../../ledgers/telemetry.js";
53
+ import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
54
+ import { parseJson } from "../../shared/json.js";
55
+ import { checkedTable } from "../../shared/text.js";
37
56
  import { buildComment } from "./issues.js";
38
- import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
57
+ import {
58
+ derivedTestMatrix,
59
+ parsePlanBlocks,
60
+ reuseInventory,
61
+ type PlanGroup,
62
+ type PlanTaskBlock,
63
+ } from "./plan-blocks.js";
64
+ import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
65
+ import { EXIT_NO_STATUS, FILE_FLAG, positiveInt, readRuns, str } from "./status.js";
39
66
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
67
+ import { RED_PROVEN, doneTasks, redEntries, redKey, testSpan } from "./tests.js";
40
68
 
41
69
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
42
70
  export const EXIT_ARTIFACT = 4;
@@ -83,8 +111,61 @@ export interface ClampRecord {
83
111
  keptBytes: number;
84
112
  lineCapped: number;
85
113
  ceilingHit: boolean;
114
+ /** The untouched original in the outbox, main-checkout relative; null when nothing was cut. */
115
+ raw: string | null;
116
+ /** The exact command and inputs that produced the file; null when the caller did not say. */
117
+ source: string | null;
118
+ /** When the source ran (UTC); a re-run returns the source's data now, not then. */
119
+ fetchedAt: string | null;
120
+ /** `context fetch` only: `table` when the output was rendered as a table, else `raw`. */
121
+ render?: Render;
122
+ }
123
+
124
+ /** How `context fetch` writes a block's output. */
125
+ export type Render = "table" | "raw";
126
+ const RENDERS: readonly Render[] = ["table", "raw"];
127
+
128
+ /** Where a cut file's original goes and what produced it. */
129
+ export interface Provenance {
130
+ /** Folder for `{name}.raw.{ext}`; null when there is none (outside a git repo). */
131
+ rawDir: string | null;
132
+ source?: string;
133
+ fetchedAt?: string;
134
+ /** An untouched copy already in the outbox (the runner's own log): no second copy. */
135
+ original?: string;
136
+ }
137
+
138
+ /**
139
+ * Copy the original of a file about to be trimmed or rendered to
140
+ * `{rawDir}/{name}.raw.{ext}`, byte for byte; `content` stands in for a file that
141
+ * was never written whole. Returns the copy's path.
142
+ */
143
+ export function keepRaw(file: string, rawDir: string, content?: Buffer): string {
144
+ const ext = path.extname(file);
145
+ const raw = path.join(rawDir, `${path.basename(file, ext)}.raw${ext}`);
146
+ fs.mkdirSync(rawDir, { recursive: true });
147
+ if (content === undefined) fs.copyFileSync(file, raw);
148
+ else fs.writeFileSync(raw, content);
149
+ return raw;
86
150
  }
87
151
 
152
+ /** `keepRaw`, with a failed copy handed back as its error so the caller picks the exit code. */
153
+ function keepRawOrError(file: string, rawDir: string): string | Error {
154
+ try {
155
+ return keepRaw(file, rawDir);
156
+ } catch (err) {
157
+ return err instanceof Error ? err : new Error(String(err));
158
+ }
159
+ }
160
+
161
+ /** The outbox folder a feature's originals go to (the outbox root without a fid); null outside a repo. */
162
+ export function rawDirFor(cwd: string, fid: string | undefined): string | null {
163
+ const root = outboxRoot(cwd);
164
+ return root === null ? null : path.join(root, fid ?? "");
165
+ }
166
+
167
+ const utcNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
168
+
88
169
  const LEDGER = { maxLines: 200, maxBytes: 51200 };
89
170
  const EVIDENCE = {
90
171
  softLines: 3000,
@@ -98,13 +179,16 @@ const EVIDENCE = {
98
179
  hardLines: 12000,
99
180
  hardBytes: 1572864,
100
181
  };
101
- export const CLAMP_PROFILES = ["ledger", "debug-evidence"] as const;
182
+ export const CLAMP_PROFILES = ["ledger", "debug-evidence", "ci", "e2e", "runtime"] as const;
102
183
 
103
184
  /**
104
185
  * Lowercase substrings matched against a lowercased line. Broad: `error` also covers
105
- * `##[error]`, `fail` covers `FAILED`; the ceiling bounds over-matching.
186
+ * `##[error]`, `fail` covers `FAILED`; the ceiling bounds over-matching. Every profile keeps
187
+ * `===== TRUNCATED: … =====`, the line `.agents/context.md` asks every block to print when
188
+ * it stops short of its window, so a partial read never looks complete.
106
189
  */
107
190
  const SIGNALS = [
191
+ "===== truncated: ",
108
192
  "error",
109
193
  "fail",
110
194
  "exception",
@@ -120,6 +204,57 @@ const SIGNALS = [
120
204
  "×",
121
205
  ].map((s) => Buffer.from(s));
122
206
 
207
+ /**
208
+ * Section-header markers a context's shipped blocks print, lowercased like them. A profile
209
+ * named for the context adds them, so a header that names a kept block's owner survives
210
+ * without a signal word. Sourced from `.bkit/templates/context/`: `github` (`ci`);
211
+ * `playwright` + `maestro` + `expo-workflows` (`e2e`); every runtime block that prints a
212
+ * banner — `vercel`, `cloudrun`, `supabase`, `inngest`, `resend`, `stripe`, `expo`
213
+ * (`runtime`). `sentry` prints no banner. A context with no entry clamps as
214
+ * `debug-evidence`.
215
+ */
216
+ const CONTEXT_MARKERS: Record<string, readonly string[]> = {
217
+ ci: ["===== job ", "===== run "],
218
+ e2e: [
219
+ "===== file: ",
220
+ "===== step: ",
221
+ "===== maestro job ",
222
+ "===== playwright report ",
223
+ // `expo-workflows` (`context=e2e`).
224
+ "===== eas workflow runs",
225
+ "===== failing steps",
226
+ "===== screen-hierarchy dumps",
227
+ "===== app js console per flow",
228
+ "===== distinct app messages",
229
+ "===== junit ",
230
+ ],
231
+ runtime: [
232
+ "===== vercel ",
233
+ "===== cloud run ",
234
+ "===== supabase ",
235
+ "===== inngest ",
236
+ "===== resend ",
237
+ "===== stripe ",
238
+ "===== webhook deliveries failed",
239
+ "===== eas builds",
240
+ ],
241
+ };
242
+
243
+ /** Each context profile's signal set: {@link SIGNALS} plus that context's markers. */
244
+ const PROFILE_SIGNALS: Record<string, readonly Buffer[]> = Object.fromEntries(
245
+ Object.entries(CONTEXT_MARKERS).map(([profile, markers]) => [
246
+ profile,
247
+ [...SIGNALS, ...markers.map((m) => Buffer.from(m))],
248
+ ]),
249
+ );
250
+
251
+ /** The signals a profile matches; a profile with no markers of its own is the base set. */
252
+ const signalsFor = (profile: string): readonly Buffer[] => PROFILE_SIGNALS[profile] ?? SIGNALS;
253
+
254
+ /** The clamp profile a block's context selects; any context without its own profile is `debug-evidence`. */
255
+ const contextProfile = (context: string): string =>
256
+ CONTEXT_MARKERS[context] === undefined ? "debug-evidence" : context;
257
+
123
258
  /** awk records: a final line with no newline is one, a trailing newline does not start another. */
124
259
  function records(buf: Buffer): Buffer[] {
125
260
  const out: Buffer[] = [];
@@ -134,10 +269,10 @@ function records(buf: Buffer): Buffer[] {
134
269
  return out;
135
270
  }
136
271
 
137
- function hasSignal(line: Buffer): boolean {
272
+ function hasSignal(line: Buffer, signals: readonly Buffer[]): boolean {
138
273
  const lower = Buffer.from(line);
139
274
  for (let i = 0; i < lower.length; i++) if (lower[i]! >= 65 && lower[i]! <= 90) lower[i]! += 32;
140
- return SIGNALS.some((s) => lower.includes(s));
275
+ return signals.some((s) => lower.includes(s));
141
276
  }
142
277
 
143
278
  /** awk's human size: B, rounded KB, or MB to one decimal (ties to even, as printf). */
@@ -187,7 +322,7 @@ function selectLedger(buf: Buffer): Selection | null {
187
322
  };
188
323
  }
189
324
 
190
- function selectEvidence(buf: Buffer): Selection {
325
+ function selectEvidence(buf: Buffer, signals: readonly Buffer[]): Selection {
191
326
  const p = EVIDENCE;
192
327
  const raw = records(buf);
193
328
  const n = raw.length;
@@ -229,7 +364,7 @@ function selectEvidence(buf: Buffer): Selection {
229
364
  // otherwise lose its immunity.
230
365
  let ceiling = false;
231
366
  for (let i = 0; i < n; i++) {
232
- if (!hasSignal(raw[i]!)) continue;
367
+ if (!hasSignal(raw[i]!, signals)) continue;
233
368
  const a = Math.max(0, i - p.context);
234
369
  const b = Math.min(n - 1, i + p.context);
235
370
  let cl = 0;
@@ -301,7 +436,12 @@ function selectEvidence(buf: Buffer): Selection {
301
436
  * left byte-identical; otherwise the kept content plus footer replace it via a
302
437
  * sibling temp file, never truncating in place.
303
438
  */
304
- export function clampFile(file: string, profile: string, artifact = file): ClampRecord {
439
+ export function clampFile(
440
+ file: string,
441
+ profile: string,
442
+ artifact = file,
443
+ keep?: Provenance,
444
+ ): ClampRecord {
305
445
  if (!(CLAMP_PROFILES as readonly string[]).includes(profile)) {
306
446
  throw new CommandError(
307
447
  EXIT.USAGE,
@@ -313,7 +453,9 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
313
453
  throw new CommandError(EXIT_ARTIFACT, `cannot read artifact '${artifact}': ${read.problem}`);
314
454
  }
315
455
  const buf = read.buf;
316
- const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
456
+ const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf, signalsFor(profile));
457
+ const source = keep?.source ?? null;
458
+ const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
317
459
  const untouched = (s: Selection | null): ClampRecord => ({
318
460
  artifact,
319
461
  clamped: false,
@@ -323,9 +465,24 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
323
465
  keptBytes: s?.keptBytes ?? buf.length,
324
466
  lineCapped: 0,
325
467
  ceilingHit: false,
468
+ raw: null,
469
+ source,
470
+ fetchedAt,
326
471
  });
327
472
  if (sel === null || sel.body.length === 0) return untouched(sel);
328
473
 
474
+ let raw: string | null = keep?.original ?? null;
475
+ if (raw === null && keep?.rawDir) {
476
+ const kept = keepRawOrError(file, keep.rawDir);
477
+ // The trim would lose the only copy: refuse it, the file stays whole.
478
+ if (kept instanceof Error)
479
+ throw new CommandError(
480
+ EXIT_ARTIFACT,
481
+ `cannot keep the original of '${artifact}': ${kept.message}`,
482
+ );
483
+ raw = kept;
484
+ }
485
+
329
486
  const footer: string[] = [];
330
487
  if (sel.lineCapped > 1) {
331
488
  footer.push(`> [bkit] ${sel.lineCapped} over-long lines were shortened; each says so inline.`);
@@ -353,6 +510,9 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
353
510
  keptBytes: sel.keptBytes,
354
511
  lineCapped: sel.lineCapped,
355
512
  ceilingHit: sel.ceilingHit,
513
+ raw: raw === null ? null : outboxRel(path.dirname(file), raw),
514
+ source,
515
+ fetchedAt,
356
516
  };
357
517
  }
358
518
 
@@ -379,6 +539,61 @@ function replaceFile(file: string, tmp: string, content: Buffer): string | undef
379
539
  }
380
540
  }
381
541
 
542
+ // ---------------------------------------------------------------------------
543
+ // Clamp summary — the saving, per context, for the context-fetch status row
544
+ // ---------------------------------------------------------------------------
545
+
546
+ /** One context's clamp totals: what its blocks wrote, and how much of it survived. */
547
+ export interface ClampSummary {
548
+ /** Artifacts written for this context. */
549
+ artifacts: number;
550
+ /** Lines fetched / kept. */
551
+ origLines: number;
552
+ keptLines: number;
553
+ /** Bytes fetched / kept. */
554
+ origBytes: number;
555
+ keptBytes: number;
556
+ /** Artifacts written as a markdown table / as printed (`render`; a record without one counts as neither). */
557
+ table: number;
558
+ raw: number;
559
+ }
560
+
561
+ /** The context-fetch context a clamp record belongs to, from its `context-<context>-…` artifact basename. */
562
+ function contextOfArtifact(artifact: string): string | undefined {
563
+ const context = /^context-([a-z0-9]+)-/.exec(path.basename(artifact))?.[1];
564
+ return context !== undefined && CONTEXT_FETCH_CONTEXTS.includes(context) ? context : undefined;
565
+ }
566
+
567
+ const numberOr0 = (v: unknown): number => (typeof v === "number" ? v : 0);
568
+
569
+ /** The context-fetch clamp records totalled per context; a record naming no context is skipped. */
570
+ export function summariseRecords(records: readonly unknown[]): Record<string, ClampSummary> {
571
+ const summary: Record<string, ClampSummary> = {};
572
+ for (const value of records) {
573
+ const r = value as Partial<ClampRecord> | null;
574
+ if (r === null || typeof r.artifact !== "string") continue;
575
+ const context = contextOfArtifact(r.artifact);
576
+ if (context === undefined) continue;
577
+ const s = (summary[context] ??= {
578
+ artifacts: 0,
579
+ origLines: 0,
580
+ keptLines: 0,
581
+ origBytes: 0,
582
+ keptBytes: 0,
583
+ table: 0,
584
+ raw: 0,
585
+ });
586
+ s.artifacts++;
587
+ s.origLines += numberOr0(r.origLines);
588
+ s.keptLines += numberOr0(r.keptLines);
589
+ s.origBytes += numberOr0(r.origBytes);
590
+ s.keptBytes += numberOr0(r.keptBytes);
591
+ if (r.render === "table") s.table++;
592
+ else if (r.render === "raw") s.raw++;
593
+ }
594
+ return summary;
595
+ }
596
+
382
597
  // ---------------------------------------------------------------------------
383
598
  // Clamp log — records cross the gap between the block that writes an artifact
384
599
  // and the block that records the step's status row.
@@ -420,8 +635,18 @@ const RECORD_OUTPUT: Record<string, string> = {
420
635
  keptBytes: "content bytes kept",
421
636
  lineCapped: "over-long lines shortened in place",
422
637
  ceilingHit: "true when the hard ceiling dropped matching lines too",
638
+ raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
639
+ source: "the command that produced the file (--source), or null",
640
+ fetchedAt: "when the source ran (UTC; the clamp time with --source), or null",
641
+ render: "context fetch only: table when the output was rendered as a table, else raw",
423
642
  };
424
643
 
644
+ /** Say so when a cut had nowhere to keep its original. */
645
+ function warnNoRaw(ctx: RunContext, record: ClampRecord, keep: Provenance) {
646
+ if (record.clamped && record.raw === null && keep.rawDir === null)
647
+ ctx.log(`${record.artifact}: not inside a git repo — original not kept`);
648
+ }
649
+
425
650
  // ---------------------------------------------------------------------------
426
651
  // Ledger scan — plan Step 4's related deferrals / failures
427
652
  // ---------------------------------------------------------------------------
@@ -593,31 +818,555 @@ function asCaptured(out: Buffer): Buffer {
593
818
  return Buffer.concat([bytes.subarray(0, end), Buffer.from("\n")]);
594
819
  }
595
820
 
821
+ // ---------------------------------------------------------------------------
822
+ // Diff artifact — the one definition of "the run's diff"
823
+ //
824
+ // Build briefs, the challenge size gate and per-group verify read the same range
825
+ // the same way: `{base}...HEAD` with `docs/plans/**` excluded, written to one
826
+ // file. Past the guard the file holds a per-file budget instead of the whole diff
827
+ // (`--stat`, then the largest files first, each cut), and its first line says so.
828
+ // ---------------------------------------------------------------------------
829
+
830
+ /** Exit code: --base does not name a commit. */
831
+ export const EXIT_BASE = 5;
832
+
833
+ export const DIFF_BASE = "origin/dev";
834
+ export const DIFF_EXCLUDES = ["docs/plans/**"];
835
+ export const PARTIAL_MARK = "partial diff coverage";
836
+
837
+ export interface DiffGuard {
838
+ /** A diff longer than this is written as a per-file budget. */
839
+ fullLines: number;
840
+ /** Files shown in budget mode, largest change first. */
841
+ topFiles: number;
842
+ /** Lines kept per shown file. */
843
+ perFileLines: number;
844
+ /** Lines kept in all; the file stops there. */
845
+ totalLines: number;
846
+ }
847
+ export const DIFF_GUARD: DiffGuard = {
848
+ fullLines: 10000,
849
+ topFiles: 20,
850
+ perFileLines: 500,
851
+ totalLines: 50000,
852
+ };
853
+
854
+ export interface DiffStat {
855
+ filesChanged: number;
856
+ linesAdded: number;
857
+ linesDeleted: number;
858
+ linesChanged: number;
859
+ }
860
+
861
+ export interface DiffArtifact {
862
+ range: string;
863
+ stat: DiffStat;
864
+ diffLines: number;
865
+ partial: boolean;
866
+ /** Files whose diff is not in the artifact whole: not shown, or cut. */
867
+ omitted: string[];
868
+ record: ClampRecord;
869
+ }
870
+
871
+ /** git's stdout as bytes; empty when git fails (a range it rejects diffs as nothing). */
872
+ function gitBytes(cwd: string, args: string[]): Buffer {
873
+ const res = spawnSync("git", args, { cwd, env: gitEnv(), maxBuffer: 1 << 29 });
874
+ return res.status === 0 ? (res.stdout ?? Buffer.alloc(0)) : Buffer.alloc(0);
875
+ }
876
+
877
+ const excludeSpec = (): string[] => ["--", ".", ...DIFF_EXCLUDES.map((e) => `:(exclude)${e}`)];
878
+
879
+ /** Per-file `--numstat` rows over the range and excludes; a binary file counts with no lines. */
880
+ export function diffNumstat(
881
+ cwd: string,
882
+ range: string,
883
+ ): { files: { path: string; lines: number }[]; stat: DiffStat } {
884
+ const files: { path: string; lines: number }[] = [];
885
+ let linesAdded = 0;
886
+ let linesDeleted = 0;
887
+ const rows = gitBytes(cwd, ["diff", "--numstat", "--no-renames", range, ...excludeSpec()])
888
+ .toString("utf-8")
889
+ .split("\n");
890
+ for (const row of rows) {
891
+ if (row === "") continue;
892
+ const [a, d, ...rest] = row.split("\t");
893
+ const added = Number(a) || 0;
894
+ const deleted = Number(d) || 0;
895
+ linesAdded += added;
896
+ linesDeleted += deleted;
897
+ files.push({ path: rest.join("\t"), lines: added + deleted });
898
+ }
899
+ return {
900
+ files,
901
+ stat: {
902
+ filesChanged: files.length,
903
+ linesAdded,
904
+ linesDeleted,
905
+ linesChanged: linesAdded + linesDeleted,
906
+ },
907
+ };
908
+ }
909
+
910
+ const joinLines = (lines: Buffer[]): Buffer =>
911
+ lines.length === 0 ? Buffer.alloc(0) : Buffer.concat([...lines.flatMap((l) => [l, lineOf("")])]);
912
+
913
+ /** {@link writeDiffArtifact}; the artifact, or the error text when the write fails. */
914
+ function tryWriteDiffArtifact(
915
+ ...args: Parameters<typeof writeDiffArtifact>
916
+ ): { ok: true; result: DiffArtifact } | { ok: false; error: string } {
917
+ try {
918
+ return { ok: true, result: writeDiffArtifact(...args) };
919
+ } catch (err) {
920
+ // Reported as the artifact exit code, with the reason.
921
+ return { ok: false, error: (err as Error).message };
922
+ }
923
+ }
924
+
925
+ /** Write the range's diff to `out`: whole under the guard, else a per-file budget; the record says which. */
926
+ export function writeDiffArtifact(
927
+ cwd: string,
928
+ out: string,
929
+ artifact: string,
930
+ range: string,
931
+ guard: DiffGuard = DIFF_GUARD,
932
+ keep: Provenance = { rawDir: null },
933
+ ): DiffArtifact {
934
+ const fetchedAt = utcNow();
935
+ const { files, stat } = diffNumstat(cwd, range);
936
+ const full = gitBytes(cwd, ["diff", range, ...excludeSpec()]);
937
+ const diffLines = records(full).length;
938
+ let content: Buffer;
939
+ let partial = false;
940
+ let ceilingHit = false;
941
+ const omitted: string[] = [];
942
+ if (diffLines === 0) {
943
+ content = lineOf(`No changes in ${range} outside ${DIFF_EXCLUDES.join(", ")}.`);
944
+ } else if (diffLines <= guard.fullLines) {
945
+ content = full;
946
+ } else {
947
+ partial = true;
948
+ const ranked = [...files].sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path));
949
+ const shown = ranked.slice(0, guard.topFiles);
950
+ const stat0 = gitBytes(cwd, ["diff", "--stat", range, ...excludeSpec()]);
951
+ // Header, omitted-files line, a blank, --stat and a blank count toward the total.
952
+ const room0 = guard.totalLines - (4 + records(stat0).length);
953
+ const body: Buffer[] = [];
954
+ let used = 0;
955
+ const add = (b: Buffer) => {
956
+ body.push(b);
957
+ used += records(b).length;
958
+ };
959
+ let stopped = false;
960
+ for (const f of ranked) {
961
+ if (stopped || !shown.includes(f)) {
962
+ omitted.push(f.path);
963
+ continue;
964
+ }
965
+ const room = Math.min(guard.perFileLines, room0 - used);
966
+ if (room <= 0) {
967
+ ceilingHit = true;
968
+ stopped = true;
969
+ omitted.push(f.path);
970
+ add(lineOf(`# total line budget reached; ${f.path} and smaller files not shown`));
971
+ continue;
972
+ }
973
+ const lines = records(gitBytes(cwd, ["diff", range, "--", f.path]));
974
+ const kept = lines.slice(0, room);
975
+ if (kept.length < lines.length && room < guard.perFileLines) ceilingHit = true;
976
+ add(lineOf(`### ${f.path}`));
977
+ add(joinLines(kept));
978
+ if (kept.length < lines.length) {
979
+ omitted.push(f.path);
980
+ add(lineOf(`# ${lines.length - kept.length} more lines of ${f.path} not shown`));
981
+ }
982
+ add(lineOf(""));
983
+ }
984
+ omitted.sort((a, b) => a.localeCompare(b));
985
+ content = Buffer.concat([
986
+ lineOf(
987
+ `# ${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.`,
988
+ ),
989
+ lineOf(`# not shown whole: ${omitted.join(", ")}`),
990
+ lineOf(""),
991
+ stat0,
992
+ lineOf(""),
993
+ ...body,
994
+ ]);
995
+ }
996
+ const raw = partial && keep.rawDir !== null ? keepRaw(out, keep.rawDir, full) : null;
997
+ fs.mkdirSync(path.dirname(out), { recursive: true });
998
+ fs.writeFileSync(out, content);
999
+ const record: ClampRecord = {
1000
+ artifact,
1001
+ clamped: partial,
1002
+ origLines: diffLines,
1003
+ keptLines: partial ? records(content).length : diffLines,
1004
+ origBytes: full.length,
1005
+ keptBytes: content.length,
1006
+ lineCapped: 0,
1007
+ ceilingHit,
1008
+ raw: raw === null ? null : outboxRel(cwd, raw),
1009
+ source: `git diff ${range} -- . ${DIFF_EXCLUDES.map((e) => `':(exclude)${e}'`).join(" ")}`,
1010
+ fetchedAt,
1011
+ };
1012
+ return { range, stat, diffLines, partial, omitted, record };
1013
+ }
1014
+
1015
+ // ---------------------------------------------------------------------------
1016
+ // Brief — what one group's build agents read
1017
+ //
1018
+ // The engine writes it so the orchestrator never reads the plan: the plan's
1019
+ // why and what, where the group sits, the group's open task blocks verbatim,
1020
+ // one-line summaries of the earlier tasks they depend on, the Reuse Inventory
1021
+ // rows and Architecture entries for the open tasks' files, and the deviations
1022
+ // note when there is one.
1023
+ // ---------------------------------------------------------------------------
1024
+
1025
+ /** A brief whose work section is over this many bytes warns: the group may not fit one fresh context. */
1026
+ export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
1027
+
1028
+ /** The plan sections a brief carries as its why and what, by heading text. */
1029
+ const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
1030
+
1031
+ /** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
1032
+ // `build-plan-execute-*` is the log's name from before the step rename: a run in flight
1033
+ // across the rename keeps its DONE lines (`docs/migrations.md`).
1034
+ const TASKS_LOG = /^build-plan-(?:tasks|execute)-.+-log\.md$/;
1035
+
1036
+ /** A heading's text without leading emoji and marks. */
1037
+ const headingText = (text: string) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
1038
+
1039
+ /**
1040
+ * The body of the first heading named `name`, up to the next heading of the
1041
+ * same or a higher level. Lines inside code fences are never headings.
1042
+ */
1043
+ function planSection(lines: string[], name: string): string | undefined {
1044
+ let start = -1;
1045
+ let level = 0;
1046
+ let fence = false;
1047
+ for (let i = 0; i < lines.length; i++) {
1048
+ const line = lines[i]!;
1049
+ if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
1050
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
1051
+ if (m === null) continue;
1052
+ if (start >= 0 && m[1]!.length <= level) return lines.slice(start, i).join("\n").trim();
1053
+ if (start < 0 && headingText(m[2]!) === name) {
1054
+ start = i + 1;
1055
+ level = m[1]!.length;
1056
+ }
1057
+ }
1058
+ return start < 0 ? undefined : lines.slice(start).join("\n").trim();
1059
+ }
1060
+
1061
+ /** Every task number a plan-execute log in `dir` records `DONE`. */
1062
+ function loggedDone(dir: string): Set<number> {
1063
+ const done = new Set<number>();
1064
+ if (!fs.existsSync(dir)) return done;
1065
+ for (const f of fs.readdirSync(dir).filter((f) => TASKS_LOG.test(f)))
1066
+ for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8"))) done.add(n);
1067
+ return done;
1068
+ }
1069
+
1070
+ /** The plan sections whose entries a brief copies for the group's files. */
1071
+ const INVENTORY_SECTION = "Reuse Inventory";
1072
+ const ARCHITECTURE_SECTION = "Architecture & Component Changes";
1073
+
1074
+ /** Backticked repo-relative paths in `text`, normalised. */
1075
+ const backticked = (text: string) =>
1076
+ [...text.matchAll(/`([^`]+)`/g)].map((m) => path.posix.normalize(m[1]!));
1077
+
1078
+ /**
1079
+ * The Reuse Inventory table's header and separator lines (`reuseInventory`), and its rows
1080
+ * whose `File` cell names a file in `files`. No table or no `File` column → no rows.
1081
+ */
1082
+ function inventoryRows(lines: string[], files: Set<string>): { head: string[]; rows: string[] } {
1083
+ const table = reuseInventory(lines.join("\n"));
1084
+ if (table === null) return { head: [], rows: [] };
1085
+ const rows = table.rows.filter((r) => r.files.some((f) => files.has(f))).map((r) => r.line);
1086
+ return { head: table.head, rows };
1087
+ }
1088
+
1089
+ /**
1090
+ * The Architecture & Component Changes entries whose heading names a file in `files`:
1091
+ * the heading through the line before the next heading of the same or a higher level.
1092
+ * Lines inside code fences are never headings.
1093
+ */
1094
+ function architectureEntries(lines: string[], files: Set<string>): string[] {
1095
+ const body = (planSection(lines, ARCHITECTURE_SECTION) ?? "").split("\n");
1096
+ const heads: Array<{ i: number; level: number; text: string }> = [];
1097
+ let fence = false;
1098
+ body.forEach((line, i) => {
1099
+ if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
1100
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
1101
+ if (m !== null) heads.push({ i, level: m[1]!.length, text: m[2]! });
1102
+ });
1103
+ return heads.flatMap((h, k) => {
1104
+ if (!backticked(h.text).some((f) => files.has(f))) return [];
1105
+ const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.i ?? body.length;
1106
+ return [body.slice(h.i, end).join("\n").trim()];
1107
+ });
1108
+ }
1109
+
1110
+ /** The next free `{prefix}-{group}-{n}.md` in `dir`: the code briefs and the tests briefs count apart. */
1111
+ function nextBriefPath(dir: string, group: number, prefix = "build-brief"): string {
1112
+ const re = new RegExp(`^${prefix}-${group}-([0-9]+)\\.md$`);
1113
+ const taken = fs.existsSync(dir)
1114
+ ? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
1115
+ : [];
1116
+ return path.join(dir, `${prefix}-${group}-${Math.max(0, ...taken) + 1}.md`);
1117
+ }
1118
+
1119
+ /** The TEST FIRST tests of `tasks`, in plan order. */
1120
+ export const plannedTests = (tasks: PlanTaskBlock[]) =>
1121
+ tasks.flatMap((t) => (t.testFirst?.tests ?? []).map((x) => ({ task: t.task, ...x })));
1122
+
1123
+ export interface BriefInput {
1124
+ plan: string;
1125
+ /** The plan's path as given, named where left-out entries can be read. */
1126
+ planFile: string;
1127
+ group: PlanGroup;
1128
+ groups: PlanGroup[];
1129
+ isDone: (t: PlanTaskBlock) => boolean;
1130
+ /** The tests step's brief: the Derived Test Matrix rows for the group's tests replace the Reuse Inventory rows and Architecture entries. */
1131
+ testsOnly?: boolean;
1132
+ /** Tests-only: the planned tests a test in their file already carries, with the line that test starts on. */
1133
+ existing?: ExistingTest[];
1134
+ note?: string;
1135
+ }
1136
+
1137
+ /** A planned test whose file already holds a test of that name, at `line` (1-based). */
1138
+ export interface ExistingTest {
1139
+ task: number;
1140
+ test: string;
1141
+ name: string;
1142
+ line: number;
1143
+ }
1144
+
1145
+ /**
1146
+ * The planned tests of `open` that already exist in the tree under `top`: the tests step
1147
+ * updates each one in place (adding expectations, never removing or loosening one) rather
1148
+ * than writing a second test of that name.
1149
+ */
1150
+ export function existingPlannedTests(top: string, open: PlanTaskBlock[]): ExistingTest[] {
1151
+ const out: ExistingTest[] = [];
1152
+ for (const t of plannedTests(open)) {
1153
+ const abs = path.join(top, t.test);
1154
+ if (!fs.existsSync(abs)) continue;
1155
+ const span = testSpan(fs.readFileSync(abs, "utf-8"), t.name);
1156
+ if (span !== null) out.push({ task: t.task, test: t.test, name: t.name, line: span.start });
1157
+ }
1158
+ return out;
1159
+ }
1160
+
1161
+ /** The brief's text and its work section's size in bytes. */
1162
+ export function briefText(o: BriefInput): { text: string; workBytes: number } {
1163
+ const lines = o.plan.split("\n");
1164
+ const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
1165
+ const out = [
1166
+ `# Brief: group ${o.group.group} — ${o.group.title}${o.testsOnly ? " (tests)" : ""}`,
1167
+ "",
1168
+ `Plan: ${title}`,
1169
+ "",
1170
+ ];
1171
+
1172
+ out.push("## Why and what", "");
1173
+ for (const name of BRIEF_SECTIONS) {
1174
+ const body = planSection(lines, name);
1175
+ if (body !== undefined && body !== "") out.push(`### ${name}`, "", body, "");
1176
+ }
1177
+
1178
+ out.push("## Where it fits", "");
1179
+ const nextGroup = o.groups.find(
1180
+ (g) => g.group > o.group.group && g.tasks.some((t) => !o.isDone(t)),
1181
+ );
1182
+ for (const g of o.groups) {
1183
+ const state = g.tasks.every(o.isDone)
1184
+ ? "done"
1185
+ : g === o.group
1186
+ ? "this group"
1187
+ : g === nextGroup
1188
+ ? "next"
1189
+ : g.group > o.group.group
1190
+ ? "later"
1191
+ : "open";
1192
+ out.push(`- Group ${g.group}: ${g.title} — ${state}`);
1193
+ for (const t of g.tasks)
1194
+ out.push(` - TASK ${t.task}: ${t.title} — ${o.isDone(t) ? "done" : "open"}`);
1195
+ }
1196
+ out.push("");
1197
+
1198
+ const open = o.group.tasks.filter((t) => !o.isDone(t));
1199
+ const work = ["## The work", ""];
1200
+ for (const t of open) work.push(t.text.trim(), "");
1201
+ const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
1202
+ .filter((n) => !o.group.tasks.some((t) => t.task === n))
1203
+ .sort((a, b) => a - b)
1204
+ .map((n) => o.groups.flatMap((g) => g.tasks).find((t) => t.task === n))
1205
+ .filter((t): t is PlanTaskBlock => t !== undefined);
1206
+ if (deps.length > 0) {
1207
+ work.push("### Earlier tasks this group depends on", "");
1208
+ for (const t of deps) {
1209
+ const files = [...new Set([...t.create, ...t.update, ...t.delete].map((r) => r.file))];
1210
+ const where = files.length > 0 ? ` — ${files.map((f) => `\`${f}\``).join(", ")}` : "";
1211
+ work.push(
1212
+ `- TASK ${t.task} (group ${t.group}, ${o.isDone(t) ? "done" : "open"}): ${t.title}${where}`,
1213
+ );
1214
+ }
1215
+ work.push("");
1216
+ }
1217
+ if (o.testsOnly) {
1218
+ work.push(...matrixRows(o.plan, open));
1219
+ const existing = (o.existing ?? []).filter((e) => open.some((t) => t.task === e.task));
1220
+ if (existing.length > 0) {
1221
+ work.push("### Planned tests that already exist", "");
1222
+ for (const e of existing)
1223
+ work.push(
1224
+ `- 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`,
1225
+ );
1226
+ work.push("");
1227
+ }
1228
+ } else work.push(...planEntries(lines, open, work, o.planFile));
1229
+ out.push(...work);
1230
+
1231
+ if (o.note !== undefined) out.push("## Deviations", "", o.note.trim(), "");
1232
+ return {
1233
+ text: out.join("\n"),
1234
+ workBytes: Buffer.byteLength(work.join("\n")),
1235
+ };
1236
+ }
1237
+
1238
+ /** The Derived Test Matrix rows naming a TEST FIRST file of `open`, under the table's header. */
1239
+ function matrixRows(plan: string, open: PlanTaskBlock[]): string[] {
1240
+ const matrix = derivedTestMatrix(plan);
1241
+ if (matrix === null) return [];
1242
+ const files = new Set(plannedTests(open).map((t) => path.posix.normalize(t.test)));
1243
+ const rows = matrix.rows.filter((r) =>
1244
+ [...r.line.matchAll(/`([^`]+)`/g)].some((m) => files.has(path.posix.normalize(m[1]!))),
1245
+ );
1246
+ return rows.length === 0
1247
+ ? []
1248
+ : ["### Derived Test Matrix rows", "", ...matrix.head, ...rows.map((r) => r.line), ""];
1249
+ }
1250
+
1251
+ /**
1252
+ * The Reuse Inventory rows, then the Architecture entries, for the files on the open
1253
+ * tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
1254
+ * within BRIEF_WORK_WARN_BYTES; the rest are counted in a closing line naming where to
1255
+ * read them.
1256
+ */
1257
+ function planEntries(
1258
+ lines: string[],
1259
+ open: PlanTaskBlock[],
1260
+ work: string[],
1261
+ planFile: string,
1262
+ ): string[] {
1263
+ const files = new Set(
1264
+ open.flatMap((t) =>
1265
+ [...t.create, ...t.update, ...t.delete].map((r) => path.posix.normalize(r.file)),
1266
+ ),
1267
+ );
1268
+ const inventory = inventoryRows(lines, files);
1269
+ const arch = architectureEntries(lines, files);
1270
+ const keptRows: string[] = [];
1271
+ const keptArch: string[] = [];
1272
+ const render = (rowsLeft: number, archLeft: number) => {
1273
+ const part: string[] = [];
1274
+ if (keptRows.length > 0)
1275
+ part.push("### Reuse Inventory rows", "", ...inventory.head, ...keptRows, "");
1276
+ if (keptArch.length > 0)
1277
+ part.push("### Architecture entries", "", ...keptArch.flatMap((e) => [e, ""]));
1278
+ if (rowsLeft + archLeft > 0)
1279
+ part.push(
1280
+ `Reuse Inventory rows left out: ${rowsLeft}; Architecture entries left out: ${archLeft} — read them in ${planFile} § ${INVENTORY_SECTION} and § ${ARCHITECTURE_SECTION}.`,
1281
+ "",
1282
+ );
1283
+ return part;
1284
+ };
1285
+ const fits = (rowsLeft: number, archLeft: number) =>
1286
+ Buffer.byteLength([...work, ...render(rowsLeft, archLeft)].join("\n")) <= BRIEF_WORK_WARN_BYTES;
1287
+ // The counts passed to `fits` are those not yet kept, an upper bound on the final ones.
1288
+ let rowsLeft = inventory.rows.length;
1289
+ let archLeft = arch.length;
1290
+ for (const row of inventory.rows) {
1291
+ keptRows.push(row);
1292
+ if (fits(rowsLeft - 1, archLeft)) rowsLeft--;
1293
+ else keptRows.pop();
1294
+ }
1295
+ for (const entry of arch) {
1296
+ keptArch.push(entry);
1297
+ if (fits(rowsLeft, archLeft - 1)) archLeft--;
1298
+ else keptArch.pop();
1299
+ }
1300
+ return render(rowsLeft, archLeft);
1301
+ }
1302
+
596
1303
  // ---------------------------------------------------------------------------
597
1304
  // Command
598
1305
  // ---------------------------------------------------------------------------
599
1306
 
1307
+ const RUN_BLOCK_FLAGS: FlagSpec[] = [
1308
+ { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1309
+ {
1310
+ name: "script",
1311
+ type: "string",
1312
+ required: true,
1313
+ help: "file holding the block body as customised for this failure (run with bash)",
1314
+ },
1315
+ FID_FLAG,
1316
+ MONTH_FLAG,
1317
+ ...ATTEMPT_FLAGS,
1318
+ {
1319
+ name: "ci-selection-file",
1320
+ type: "string",
1321
+ help: "validated CI selection JSON; pin child evidence reads and require a matching complete CI receipt",
1322
+ },
1323
+ ];
1324
+
1325
+ const RUN_BLOCK_OUTPUT: Record<string, string> = {
1326
+ outcome:
1327
+ "checked (validated data written) | unchecked (selected CI evidence invalid) | self-skipped (skip line written) | silent (nothing) | not-run",
1328
+ artifact: "the artifact path, or null when nothing was written",
1329
+ skip: "the block's [context-fetch:<name>] stderr line, or null",
1330
+ clamp: "the payload's clamp record, or null",
1331
+ reason: "why the block was not run, or null",
1332
+ };
1333
+
600
1334
  export const contextCommand: CommandSpec = {
601
1335
  noun: "context",
602
1336
  summary:
603
- "Clamp context artifacts; scan ledgers; list, run and record consumer context-fetch blocks.",
1337
+ "Clamp context artifacts; scan ledgers; write the run's diff and a build group's brief; list, run and record consumer context-fetch blocks.",
604
1338
  verbs: {
605
1339
  clamp: {
606
1340
  summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
1341
+ use: "workflow",
607
1342
  flags: [
608
1343
  { name: "artifact", type: "string", required: true, help: "file to clamp" },
609
- { name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
1344
+ { name: "profile", type: "string", required: true, help: CLAMP_PROFILES.join(" | ") },
1345
+ {
1346
+ name: "source",
1347
+ type: "string",
1348
+ help: "the exact command and inputs that produced the artifact (recorded with the time)",
1349
+ },
610
1350
  ...LOG_FLAGS,
611
1351
  ],
612
1352
  output: RECORD_OUTPUT,
613
- exitCodes: { [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced" },
1353
+ exitCodes: {
1354
+ [EXIT_ARTIFACT]:
1355
+ "artifact missing, unreadable, or could not be replaced; or its original could not be kept",
1356
+ },
614
1357
  run: (ctx) => {
615
1358
  const artifact = String(ctx.flags.artifact);
1359
+ const keep: Provenance = {
1360
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1361
+ source: str(ctx.flags.source),
1362
+ };
616
1363
  const record = clampFile(
617
1364
  path.resolve(ctx.cwd, artifact),
618
1365
  String(ctx.flags.profile),
619
1366
  artifact,
1367
+ keep,
620
1368
  );
1369
+ warnNoRaw(ctx, record, keep);
621
1370
  const log = logPath(ctx);
622
1371
  if (log !== undefined) appendRecord(log, record);
623
1372
  if (record.clamped)
@@ -628,6 +1377,7 @@ export const contextCommand: CommandSpec = {
628
1377
  },
629
1378
  "clamp-log": {
630
1379
  summary: "Read a step's clamp records (the status row's clamped array), or reset the log.",
1380
+ use: "workflow",
631
1381
  flags: [
632
1382
  ...LOG_FLAGS,
633
1383
  { name: "reset", type: "boolean", help: "empty the log first (the step's first writer)" },
@@ -651,6 +1401,7 @@ export const contextCommand: CommandSpec = {
651
1401
  "ledger-scan": {
652
1402
  summary:
653
1403
  "Write a ledger's lines matching query terms, strongest first, then clamp (ledger profile).",
1404
+ use: "workflow",
654
1405
  flags: [
655
1406
  { name: "terms", type: "string", required: true, help: "space-separated query terms" },
656
1407
  {
@@ -672,6 +1423,7 @@ export const contextCommand: CommandSpec = {
672
1423
  kept: "lines written (at most 40)",
673
1424
  clamp: "the clamp record",
674
1425
  },
1426
+ textOmit: ["clamp"],
675
1427
  exitCodes: { [EXIT_ARTIFACT]: "artifact could not be written or replaced" },
676
1428
  run: (ctx) => {
677
1429
  const log = logPath(ctx);
@@ -683,27 +1435,261 @@ export const contextCommand: CommandSpec = {
683
1435
  }
684
1436
  const sourceFile = path.resolve(ctx.cwd, String(ctx.flags.source));
685
1437
  const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf-8") : undefined;
686
- const scan = ledgerScan(source, String(ctx.flags.terms));
1438
+ const terms = String(ctx.flags.terms);
1439
+ const scan = ledgerScan(source, terms);
687
1440
  const artifact = String(ctx.flags.artifact);
688
1441
  const out = path.resolve(ctx.cwd, artifact);
689
1442
  fs.mkdirSync(path.dirname(out), { recursive: true });
690
1443
  fs.writeFileSync(out, scan.content);
691
- const clamp = clampFile(out, "ledger", artifact);
1444
+ const keep: Provenance = {
1445
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1446
+ source: `bkit context ledger-scan --source=${String(ctx.flags.source)} --terms="${terms}"`,
1447
+ };
1448
+ const clamp = clampFile(out, "ledger", artifact, keep);
1449
+ warnNoRaw(ctx, clamp, keep);
692
1450
  if (log !== undefined) appendRecord(log, clamp);
693
1451
  ctx.log(`${artifact}: ${scan.total} matching line(s), ${scan.kept} kept`);
694
1452
  ctx.emit({ total: scan.total, kept: scan.kept, clamp });
695
1453
  return EXIT.OK;
696
1454
  },
697
1455
  },
1456
+ diff: {
1457
+ summary:
1458
+ "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.",
1459
+ use: "workflow",
1460
+ flags: [
1461
+ { name: "artifact", type: "string", required: true, help: "file to write" },
1462
+ {
1463
+ name: "base",
1464
+ type: "string",
1465
+ help: `merge base or a group's start commit (default ${DIFF_BASE})`,
1466
+ },
1467
+ ...LOG_FLAGS,
1468
+ {
1469
+ name: "reset-log",
1470
+ type: "boolean",
1471
+ help: "empty the clamp log first (the step's first writer)",
1472
+ },
1473
+ ],
1474
+ output: {
1475
+ artifact: "the artifact path as given",
1476
+ base: "the base used",
1477
+ range: "the range diffed ({base}...HEAD)",
1478
+ filesChanged: "files in the diff (--numstat, same excludes)",
1479
+ linesAdded: "lines added",
1480
+ linesDeleted: "lines deleted",
1481
+ linesChanged: "linesAdded + linesDeleted",
1482
+ diffLines: "lines in the whole diff",
1483
+ 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`,
1484
+ omitted:
1485
+ "files whose diff is not in the artifact whole (not shown, or cut); [] unless partial — the artifact's second line lists them too",
1486
+ clamp:
1487
+ "the clamp record (clamped = partial; raw = the whole diff in the outbox when partial)",
1488
+ },
1489
+ textOmit: ["clamp"],
1490
+ exitCodes: {
1491
+ [EXIT_BASE]: "--base does not name a commit",
1492
+ [EXIT_ARTIFACT]: "the artifact could not be written",
1493
+ },
1494
+ run: (ctx) => {
1495
+ const base = str(ctx.flags.base) ?? DIFF_BASE;
1496
+ if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
1497
+ throw new CommandError(
1498
+ EXIT_BASE,
1499
+ `--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`,
1500
+ );
1501
+ }
1502
+ const artifact = String(ctx.flags.artifact);
1503
+ const log = logPath(ctx);
1504
+ if (ctx.flags.resetLog === true) {
1505
+ if (log === undefined)
1506
+ throw new CommandError(EXIT.USAGE, "--reset-log needs --log, or --fid and --step");
1507
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1508
+ fs.writeFileSync(log, "");
1509
+ }
1510
+ const written = tryWriteDiffArtifact(
1511
+ ctx.cwd,
1512
+ path.resolve(ctx.cwd, artifact),
1513
+ artifact,
1514
+ `${base}...HEAD`,
1515
+ DIFF_GUARD,
1516
+ { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) },
1517
+ );
1518
+ if (!written.ok) throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
1519
+ const result = written.result;
1520
+ if (log !== undefined) appendRecord(log, result.record);
1521
+ if (result.partial) {
1522
+ ctx.log(
1523
+ `${artifact}: ${result.diffLines} diff lines, over the ${DIFF_GUARD.fullLines}-line guard — per-file budget written (${PARTIAL_MARK})`,
1524
+ );
1525
+ }
1526
+ ctx.emit({
1527
+ artifact,
1528
+ base,
1529
+ range: result.range,
1530
+ ...result.stat,
1531
+ diffLines: result.diffLines,
1532
+ partial: result.partial,
1533
+ omitted: result.omitted,
1534
+ clamp: result.record,
1535
+ });
1536
+ return EXIT.OK;
1537
+ },
1538
+ },
1539
+ brief: {
1540
+ summary:
1541
+ "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.",
1542
+ use: "workflow",
1543
+ flags: [
1544
+ { name: "plan", type: "string", required: true, help: "the plan file" },
1545
+ { name: "group", type: "string", help: "the group to brief" },
1546
+ {
1547
+ name: "next",
1548
+ type: "boolean",
1549
+ help: "brief the first group with an open task (none open → nothing written, group null)",
1550
+ },
1551
+ {
1552
+ name: "dir",
1553
+ type: "string",
1554
+ required: true,
1555
+ help: "the run's logs folder: the brief is written there, and its build-plan-tasks-*-log.md DONE lines mark tasks done",
1556
+ },
1557
+ {
1558
+ name: "tests-only",
1559
+ type: "boolean",
1560
+ help: "the tests step's brief: build-brief-tests-{group}-{n}.md (a group with no planned test writes nothing, tests 0)",
1561
+ },
1562
+ {
1563
+ ...FILE_FLAG,
1564
+ required: false,
1565
+ 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",
1566
+ },
1567
+ {
1568
+ name: "note-file",
1569
+ type: "string",
1570
+ help: "text for the Deviations section (left out when not given)",
1571
+ },
1572
+ ],
1573
+ output: {
1574
+ artifact: "the brief's path (null when --next finds no open group)",
1575
+ bytes: "the brief's size in bytes",
1576
+ group: "the group briefed (null when --next finds no open group)",
1577
+ tasks: "the open task numbers the brief carries",
1578
+ tests: "the TEST FIRST tests of those tasks (0 when --next finds no open group)",
1579
+ workBytes: "the work section's size in bytes (0 when --next finds no open group)",
1580
+ 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`,
1581
+ },
1582
+ exitCodes: {
1583
+ [EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
1584
+ },
1585
+ run: (ctx) => {
1586
+ const groupFlag = positiveInt(ctx.flags.group, "group");
1587
+ if ((groupFlag === undefined) === (ctx.flags.next !== true))
1588
+ throw new CommandError(EXIT.USAGE, "give exactly one of --group=N and --next");
1589
+ const planFile = path.resolve(ctx.cwd, String(ctx.flags.plan));
1590
+ if (!fs.existsSync(planFile))
1591
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)} does not exist`);
1592
+ const plan = fs.readFileSync(planFile, "utf-8");
1593
+ const blocks = parsePlanBlocks(plan);
1594
+ if (blocks.errors.length > 0) {
1595
+ const e = blocks.errors[0]!;
1596
+ throw new CommandError(
1597
+ EXIT_ARTIFACT,
1598
+ `${String(ctx.flags.plan)}:${e.line}: ${e.message} — run \`bkit tests plan-check\``,
1599
+ );
1600
+ }
1601
+ const dir = path.resolve(ctx.cwd, String(ctx.flags.dir));
1602
+ const done = loggedDone(dir);
1603
+ const isDone = (t: PlanTaskBlock) => t.done || done.has(t.task);
1604
+ const group =
1605
+ groupFlag === undefined
1606
+ ? blocks.groups.find((g) => g.tasks.some((t) => !isDone(t)))
1607
+ : blocks.groups.find((g) => g.group === groupFlag);
1608
+ if (group === undefined && groupFlag !== undefined)
1609
+ throw new CommandError(EXIT.USAGE, `the plan has no group ${groupFlag}`);
1610
+ if (group === undefined) {
1611
+ ctx.emit({
1612
+ artifact: null,
1613
+ bytes: 0,
1614
+ group: null,
1615
+ tasks: [],
1616
+ tests: 0,
1617
+ workBytes: 0,
1618
+ workCap: BRIEF_WORK_WARN_BYTES,
1619
+ });
1620
+ return EXIT.OK;
1621
+ }
1622
+ const testsOnly = ctx.flags.testsOnly === true;
1623
+ const statusArg = str(ctx.flags.file);
1624
+ const proven =
1625
+ testsOnly && statusArg !== undefined
1626
+ ? redEntries(path.resolve(ctx.cwd, statusArg), "build", group.group)
1627
+ : new Map<string, never>();
1628
+ const left = (t: PlanTaskBlock) =>
1629
+ plannedTests([t]).filter((x) => {
1630
+ const red = proven.get(redKey(x.task, x.test, x.name));
1631
+ return red === undefined || !RED_PROVEN.has(red.state);
1632
+ });
1633
+ const open = group.tasks.filter((t) => !isDone(t) && (!testsOnly || left(t).length > 0));
1634
+ const tests = testsOnly ? open.flatMap(left).length : plannedTests(open).length;
1635
+ if (testsOnly && tests === 0) {
1636
+ ctx.emit({
1637
+ artifact: null,
1638
+ bytes: 0,
1639
+ group: group.group,
1640
+ tasks: open.map((t) => t.task),
1641
+ tests,
1642
+ workBytes: 0,
1643
+ workCap: BRIEF_WORK_WARN_BYTES,
1644
+ });
1645
+ return EXIT.OK;
1646
+ }
1647
+ const noteFlag = str(ctx.flags.noteFile);
1648
+ const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1649
+ if (noteFile !== undefined && !fs.existsSync(noteFile))
1650
+ throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1651
+ const { text, workBytes } = briefText({
1652
+ plan,
1653
+ planFile: String(ctx.flags.plan),
1654
+ group,
1655
+ groups: blocks.groups,
1656
+ isDone: (t) => isDone(t) || (group.tasks.includes(t) && !open.includes(t)),
1657
+ testsOnly,
1658
+ existing: testsOnly
1659
+ ? existingPlannedTests(git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd, open)
1660
+ : undefined,
1661
+ note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1662
+ });
1663
+ const out = nextBriefPath(dir, group.group, testsOnly ? "build-brief-tests" : undefined);
1664
+ fs.mkdirSync(dir, { recursive: true });
1665
+ fs.writeFileSync(out, text);
1666
+ if (workBytes > BRIEF_WORK_WARN_BYTES) {
1667
+ ctx.log(
1668
+ `${out}: the work section is ${humanBytes(workBytes)}, over ${humanBytes(BRIEF_WORK_WARN_BYTES)} — the group may not fit one fresh context`,
1669
+ );
1670
+ }
1671
+ const artifact = path.isAbsolute(String(ctx.flags.dir)) ? out : path.relative(ctx.cwd, out);
1672
+ ctx.emit({
1673
+ artifact,
1674
+ bytes: Buffer.byteLength(text),
1675
+ group: group.group,
1676
+ tasks: open.map((t) => t.task),
1677
+ tests,
1678
+ workBytes,
1679
+ workCap: BRIEF_WORK_WARN_BYTES,
1680
+ });
1681
+ return EXIT.OK;
1682
+ },
1683
+ },
698
1684
  "list-blocks": {
699
1685
  summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
1686
+ use: "by-hand",
700
1687
  flags: [],
701
1688
  output: {
702
1689
  blocks: "[{idx, context, name, known, prefix, suffix, body}] in file order",
703
1690
  coverage: "blocks per context (runtime, ci, diff, e2e, web)",
704
1691
  contextsConfigured: "contexts with at least one block, in narration order",
705
- provision:
706
- "bash body of each context-fetch:provision block below bkit:end, in file order (bkit-cloud-bootstrap.sh runs them)",
1692
+ provision: "bash body of each context-fetch:provision block below bkit:end, in file order",
707
1693
  },
708
1694
  run: (ctx) => {
709
1695
  const blocks = fetchBlocks(consumerSection(readContextMd(ctx) ?? ""));
@@ -736,38 +1722,63 @@ export const contextCommand: CommandSpec = {
736
1722
  return EXIT.OK;
737
1723
  },
738
1724
  },
1725
+ provision: {
1726
+ summary:
1727
+ "Run each context-fetch:provision recipe below bkit:end on its own and list the failed ones in .bkit/.unavailable.",
1728
+ use: "by-hand",
1729
+ flags: [],
1730
+ output: {
1731
+ recipes: "recipes run",
1732
+ unavailable: "[{name, reason}] for each failed recipe, in file order",
1733
+ file: "the failure list's path from the repo root; null when none failed",
1734
+ },
1735
+ run: (ctx) => runProvision(ctx),
1736
+ },
739
1737
  "run-block": {
740
1738
  summary:
741
1739
  "Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
1740
+ use: "workflow",
1741
+ flags: RUN_BLOCK_FLAGS,
1742
+ output: RUN_BLOCK_OUTPUT,
1743
+ textOmit: ["clamp"],
1744
+ exitCodes: {
1745
+ [EXIT_ARTIFACT]: "the payload could not be clamped or written",
1746
+ [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
1747
+ },
1748
+ run: (ctx) => runBlock(ctx),
1749
+ },
1750
+ fetch: {
1751
+ summary:
1752
+ "run-block, with a JSON array of flat objects written as a markdown table; the raw output stays in the outbox.",
1753
+ use: "workflow",
742
1754
  flags: [
743
- { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1755
+ ...RUN_BLOCK_FLAGS,
744
1756
  {
745
- name: "script",
1757
+ name: "render",
746
1758
  type: "string",
747
- required: true,
748
- help: "file holding the block body as customised for this failure (run with bash)",
1759
+ 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",
749
1760
  },
750
- FID_FLAG,
751
- MONTH_FLAG,
752
- ...ATTEMPT_FLAGS,
753
1761
  ],
754
1762
  output: {
755
- outcome:
756
- "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
757
- artifact: "the artifact path, or null when nothing was written",
758
- skip: "the block's [context-fetch:<name>] stderr line, or null",
759
- clamp: "the payload's clamp record, or null",
760
- reason: "why the block was not run, or null",
1763
+ ...RUN_BLOCK_OUTPUT,
1764
+ render: "table | raw: how the output was written; null when nothing was written",
761
1765
  },
1766
+ textOmit: ["clamp"],
762
1767
  exitCodes: {
763
1768
  [EXIT_ARTIFACT]: "the payload could not be clamped or written",
764
1769
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
765
1770
  },
766
- run: (ctx) => runBlock(ctx),
1771
+ run: (ctx) => {
1772
+ const render = str(ctx.flags.render) ?? "table";
1773
+ if (!(RENDERS as readonly string[]).includes(render))
1774
+ throw new CommandError(EXIT.USAGE, `--render must be ${RENDERS.join("|")}`);
1775
+ return runBlock(ctx, render as Render);
1776
+ },
767
1777
  },
768
1778
  finalise: {
769
1779
  summary:
770
1780
  "The context-fetch status row's fields: verdict, artifacts, contexts configured, clamped; --record writes and commits the row and prints the step comment.",
1781
+ use: "workflow",
771
1782
  flags: [
772
1783
  FID_FLAG,
773
1784
  MONTH_FLAG,
@@ -792,14 +1803,20 @@ export const contextCommand: CommandSpec = {
792
1803
  artifacts: "those artifacts, relative to the working directory",
793
1804
  contextsConfigured: "contexts with at least one block",
794
1805
  clamped: "this attempt's clamp records",
1806
+ clampSummary:
1807
+ "those records totalled per context: artifacts written, lines and bytes fetched -> kept, and how many were written as a table vs raw",
795
1808
  row: "--record: the step-done row written, else null",
796
1809
  commit: "--record: the new commit's sha, else null",
1810
+ progressLine:
1811
+ "--record: the exact chat progress line after a successful numbered completion",
797
1812
  comment:
798
1813
  "the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
1814
+ commentFile: COMMENT_FILE_OUTPUT,
799
1815
  },
800
1816
  exitCodes: {
801
1817
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
802
- [EXIT_COMMIT]: "--record: the row was written but the commit failed",
1818
+ [EXIT_COMMIT]:
1819
+ "--record: nothing written, nothing committed: the commit failed and the row was rolled back",
803
1820
  },
804
1821
  run: (ctx) => {
805
1822
  const attempt = debugAttempt(ctx);
@@ -822,8 +1839,9 @@ export const contextCommand: CommandSpec = {
822
1839
  const clamped = readRecords(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), (l) =>
823
1840
  ctx.log(`skipping a malformed clamp record: ${l}`),
824
1841
  );
1842
+ const clampSummary = summariseRecords(clamped);
825
1843
  const verdict = artifacts.length > 0 ? "PASS" : "FAIL";
826
- let written: { row: Record<string, unknown>; commit: string | null; code: number } = {
1844
+ let written: ReturnType<typeof writeStepRow> = {
827
1845
  row: {},
828
1846
  commit: null,
829
1847
  code: EXIT.OK,
@@ -832,6 +1850,7 @@ export const contextCommand: CommandSpec = {
832
1850
  if (record) {
833
1851
  const file = str(ctx.flags.file);
834
1852
  if (file === undefined) throw new CommandError(EXIT.USAGE, "--record needs --file");
1853
+ const active = lastRun(readRuns(path.resolve(ctx.cwd, file)), "debug");
835
1854
  written = writeStepRow(
836
1855
  ctx.cwd,
837
1856
  {
@@ -841,7 +1860,16 @@ export const contextCommand: CommandSpec = {
841
1860
  verdict,
842
1861
  attempt,
843
1862
  artifacts,
844
- extras: { contextsConfigured, clamped },
1863
+ extras: {
1864
+ contextsConfigured,
1865
+ clamped,
1866
+ clampSummary,
1867
+ ...(active &&
1868
+ validateCiSelection(active.ciSelection) &&
1869
+ active.ciSelection.mode === "ci"
1870
+ ? { ciGeneration: active.ciGeneration }
1871
+ : {}),
1872
+ },
845
1873
  commit: "auto",
846
1874
  message: str(ctx.flags.message),
847
1875
  },
@@ -875,9 +1903,12 @@ export const contextCommand: CommandSpec = {
875
1903
  artifacts,
876
1904
  contextsConfigured,
877
1905
  clamped,
1906
+ clampSummary,
878
1907
  row: record ? written.row : null,
879
1908
  commit: written.commit,
1909
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
880
1910
  comment,
1911
+ commentFile: commentFileOf(ctx.cwd, comment),
881
1912
  });
882
1913
  return written.code;
883
1914
  },
@@ -885,7 +1916,60 @@ export const contextCommand: CommandSpec = {
885
1916
  },
886
1917
  };
887
1918
 
888
- function runBlock(ctx: RunContext): number {
1919
+ /** A block's output as a checked markdown table, or why it stays as printed. */
1920
+ function tableOf(stdout: Buffer): { text: string } | { reason: string } {
1921
+ const parsed = parseJson(stdout.toString("utf-8"));
1922
+ if (!parsed.ok) return { reason: "not JSON" };
1923
+ const table = checkedTable(parsed.value);
1924
+ return table.ok ? { text: table.text } : { reason: table.reason };
1925
+ }
1926
+
1927
+ /** Selected CI evidence is usable only with one complete receipt and actual logs. */
1928
+ function ciEvidenceProblem(
1929
+ stdout: Buffer,
1930
+ selection: Extract<CiSelection, { mode: "ci" }>,
1931
+ ): string | null {
1932
+ const lines = stdout.toString("utf-8").split("\n");
1933
+ const receipts = lines.filter((line) => line.startsWith("bkit-ci-evidence: "));
1934
+ if (receipts.length !== 1) return "selected CI evidence needs exactly one identity receipt";
1935
+ const parsed = parseJson(receipts[0]!.slice("bkit-ci-evidence: ".length));
1936
+ if (
1937
+ !parsed.ok ||
1938
+ parsed.value === null ||
1939
+ typeof parsed.value !== "object" ||
1940
+ Array.isArray(parsed.value)
1941
+ )
1942
+ return "selected CI evidence receipt is malformed";
1943
+ const receipt = parsed.value as Record<string, unknown>;
1944
+ for (const field of [
1945
+ "provider",
1946
+ "repo",
1947
+ "runId",
1948
+ "runAttempt",
1949
+ "headSha",
1950
+ "workflowId",
1951
+ ] as const) {
1952
+ if (receipt[field] !== selection[field]) return `selected CI evidence ${field} does not match`;
1953
+ }
1954
+ if (receipt.complete !== true) return "selected CI evidence is incomplete";
1955
+ const logs = lines
1956
+ .filter((line) => !line.startsWith("bkit-ci-evidence: "))
1957
+ .join("\n")
1958
+ .trim();
1959
+ if (logs === "") return "selected CI evidence contains no logs";
1960
+ if (/\[context-fetch:[^\n]*skipped|===== TRUNCATED:/i.test(logs))
1961
+ return "selected CI evidence is skipped or partial";
1962
+ return null;
1963
+ }
1964
+
1965
+ /**
1966
+ * Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
1967
+ * (`context fetch`), a JSON array of flat objects is written as a table instead; the
1968
+ * output as printed goes to the outbox first, and the record says which was written.
1969
+ */
1970
+ function runBlock(ctx: RunContext, render?: Render): number {
1971
+ const shape = (out: Record<string, unknown>, written: Render | null) =>
1972
+ render === undefined ? out : { ...out, render: written };
889
1973
  const idx = positiveInt(ctx.flags.idx, "idx")!;
890
1974
  const attempt = debugAttempt(ctx);
891
1975
  const fid = String(ctx.flags.fid);
@@ -895,7 +1979,7 @@ function runBlock(ctx: RunContext): number {
895
1979
  const block = fetchBlocks(consumerSection(readContextMd(ctx) ?? "")).find((b) => b.idx === idx);
896
1980
  const notRun = (reason: string) => {
897
1981
  ctx.log(`context-fetch: ${reason} — NOT RUN`);
898
- ctx.emit({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason });
1982
+ ctx.emit(shape({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason }, null));
899
1983
  return EXIT.OK;
900
1984
  };
901
1985
  if (!block) return notRun(`no block ${idx} after <!-- bkit:end -->`);
@@ -909,11 +1993,36 @@ function runBlock(ctx: RunContext): number {
909
1993
  return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
910
1994
 
911
1995
  const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1996
+ const fetchedAt = utcNow();
1997
+ const selectionFile = str(ctx.flags.ciSelectionFile);
1998
+ let selection: CiSelection | undefined;
1999
+ if (selectionFile !== undefined) {
2000
+ const file = path.resolve(ctx.cwd, selectionFile);
2001
+ if (!fs.existsSync(file))
2002
+ throw new CommandError(EXIT.USAGE, `--ci-selection-file ${selectionFile} does not exist`);
2003
+ const parsed = parseJson(fs.readFileSync(file, "utf-8"));
2004
+ if (!parsed.ok || !validateCiSelection(parsed.value))
2005
+ throw new CommandError(
2006
+ EXIT.USAGE,
2007
+ "--ci-selection-file must contain a validated CI or local selection",
2008
+ );
2009
+ selection = parsed.value;
2010
+ }
2011
+ const childEnv: NodeJS.ProcessEnv = { ...process.env };
2012
+ for (const key of ["BKIT_CI_RUN_ID", "BKIT_CI_RUN_ATTEMPT", "BKIT_CI_REPO", "BKIT_CI_HEAD_SHA"])
2013
+ delete childEnv[key];
2014
+ if (selection?.mode === "ci")
2015
+ Object.assign(childEnv, {
2016
+ BKIT_CI_RUN_ID: selection.runId,
2017
+ BKIT_CI_RUN_ATTEMPT: String(selection.runAttempt),
2018
+ BKIT_CI_REPO: selection.repo,
2019
+ BKIT_CI_HEAD_SHA: selection.headSha,
2020
+ });
912
2021
  // The inline block ran inside the step's shell, so these were in scope for it.
913
2022
  const res = spawnSync("bash", [script], {
914
2023
  cwd: ctx.cwd,
915
2024
  env: {
916
- ...process.env,
2025
+ ...childEnv,
917
2026
  REPO_ROOT: repoRoot,
918
2027
  CONTEXT: block.context,
919
2028
  NAME: block.name,
@@ -933,15 +2042,65 @@ function runBlock(ctx: RunContext): number {
933
2042
  );
934
2043
  const out = path.resolve(ctx.cwd, artifact);
935
2044
  const shown = `context-fetch context=${block.context} name=${block.name || "default"}`;
2045
+ const evidenceProblem =
2046
+ selection?.mode === "ci" && block.context === "ci"
2047
+ ? res.status !== 0 || skip !== undefined
2048
+ ? "selected CI evidence command failed or self-skipped"
2049
+ : ciEvidenceProblem(stdout, selection)
2050
+ : null;
936
2051
 
937
2052
  if (stdout.some((b) => b !== 0x0a && b !== 0)) {
938
2053
  fs.mkdirSync(path.dirname(out), { recursive: true });
939
- fs.writeFileSync(out, asCaptured(stdout));
940
- const clamp = clampFile(out, "debug-evidence", artifact);
2054
+ const keep: Provenance = {
2055
+ rawDir: rawDirFor(ctx.cwd, fid),
2056
+ source: fs.readFileSync(script, "utf-8"),
2057
+ fetchedAt,
2058
+ };
2059
+ const printed = asCaptured(stdout);
2060
+ let payload = printed;
2061
+ let written: Render | null = null;
2062
+ if (render !== undefined) {
2063
+ const table = render === "table" ? tableOf(stdout) : null;
2064
+ if (table !== null && "text" in table) {
2065
+ // The table replaces the printed output: keep that output whole first.
2066
+ if (keep.rawDir !== null) keep.original = keepRaw(out, keep.rawDir, stdout);
2067
+ payload = Buffer.from(`${table.text}\n`);
2068
+ written = "table";
2069
+ } else {
2070
+ if (table !== null) ctx.log(`render: raw (${table.reason})`);
2071
+ written = "raw";
2072
+ }
2073
+ }
2074
+ fs.writeFileSync(out, payload);
2075
+ let clamp = clampFile(out, contextProfile(block.context), artifact, keep);
2076
+ warnNoRaw(ctx, clamp, keep);
2077
+ if (written !== null) {
2078
+ const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
2079
+ clamp = { ...clamp, raw, render: written };
2080
+ }
2081
+ // Fetched is what the block printed; the table is only what the artifact keeps.
2082
+ if (written === "table") {
2083
+ clamp = { ...clamp, origLines: records(printed).length, origBytes: printed.length };
2084
+ }
941
2085
  appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
942
2086
  fs.writeFileSync(out, fenced(fs.readFileSync(out)));
943
- ctx.log(`${shown} CHECKED — data returned`);
944
- ctx.emit({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null });
2087
+ ctx.log(
2088
+ evidenceProblem === null
2089
+ ? `${shown} CHECKED — data returned`
2090
+ : `${shown} UNCHECKED — ${evidenceProblem}`,
2091
+ );
2092
+ ctx.emit(
2093
+ shape(
2094
+ {
2095
+ outcome: evidenceProblem === null ? "checked" : "unchecked",
2096
+ artifact,
2097
+ skip: skip ?? null,
2098
+ clamp,
2099
+ reason: evidenceProblem,
2100
+ },
2101
+ written,
2102
+ ),
2103
+ );
945
2104
  return EXIT.OK;
946
2105
  }
947
2106
  if (skip !== undefined) {
@@ -950,12 +2109,55 @@ function runBlock(ctx: RunContext): number {
950
2109
  ctx.log(
951
2110
  `${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)`,
952
2111
  );
953
- ctx.emit({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null });
2112
+ ctx.emit(shape({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null }, null));
954
2113
  return EXIT.OK;
955
2114
  }
956
2115
  ctx.log(
957
2116
  `${shown} produced neither data nor a skip breadcrumb — NOT CHECKED (unexpected silent exit; treat as unavailable, never as clean)`,
958
2117
  );
959
- ctx.emit({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null });
2118
+ ctx.emit(
2119
+ shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null),
2120
+ );
2121
+ return EXIT.OK;
2122
+ }
2123
+
2124
+ /**
2125
+ * Run the consumer's provision recipes through the same region the cloud setup scripts
2126
+ * inline, with `REPO_ROOT` set so the region rewrites the failure list there. Recipe
2127
+ * output goes to stderr; stdout carries only this command's report. Never fails on a
2128
+ * recipe: a failure is reported, not raised.
2129
+ */
2130
+ function runProvision(ctx: RunContext): number {
2131
+ const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
2132
+ const file = path.join(repoRoot, UNAVAILABLE_RELPATH);
2133
+ const region = renderCloudContextFetchProvision(ctx.cwd);
2134
+ const recipes = region === "" ? 0 : (region.match(/^bkit_provision '/gm) ?? []).length;
2135
+ if (region === "") {
2136
+ fs.rmSync(file, { force: true });
2137
+ } else {
2138
+ const res = spawnSync("bash", ["-c", `set -uo pipefail\n${region}`], {
2139
+ cwd: ctx.cwd,
2140
+ env: { ...process.env, REPO_ROOT: repoRoot },
2141
+ stdio: ["ignore", 2, 2],
2142
+ });
2143
+ if (res.error) throw new CommandError(EXIT.USAGE, `bash did not run: ${res.error.message}`);
2144
+ }
2145
+ const unavailable = fs.existsSync(file)
2146
+ ? fs
2147
+ .readFileSync(file, "utf-8")
2148
+ .split("\n")
2149
+ .filter((l) => l !== "")
2150
+ .map((l) => {
2151
+ const at = l.indexOf(": ");
2152
+ return at === -1
2153
+ ? { name: l, reason: "" }
2154
+ : { name: l.slice(0, at), reason: l.slice(at + 2) };
2155
+ })
2156
+ : [];
2157
+ ctx.emit({
2158
+ recipes,
2159
+ unavailable,
2160
+ file: unavailable.length === 0 ? null : UNAVAILABLE_RELPATH,
2161
+ });
960
2162
  return EXIT.OK;
961
2163
  }