@cbartens/bkit 5.5.0 → 6.0.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 (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -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 —
2
+ // size-bound context artifacts, write the run's diff and a build group's brief,
3
+ // and fetch the consumer's evidence.
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:
@@ -13,6 +14,10 @@
13
14
  //
14
15
  // Bytes are counted as raw bytes (as `LC_ALL=C awk` counts them), never as
15
16
  // characters, so a multi-byte line is measured by what it costs on disk.
17
+ //
18
+ // A cut file keeps its untouched original as `{name}.raw.{ext}` in the outbox
19
+ // (`keepRaw`), never under `logs/`; the record names it (`raw`) with the command
20
+ // that produced the file (`source`) and when it ran (`fetchedAt`).
16
21
  import { spawnSync } from "node:child_process";
17
22
  import * as fs from "node:fs";
18
23
  import * as path from "node:path";
@@ -20,11 +25,16 @@ import { CONTEXT_FETCH_CONTEXTS, parseContextFetchStart, } from "../../checks/be
20
25
  import { extractContextFetchProvisionRecipes } from "../../install/cloud-env.js";
21
26
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
22
27
  import { lastRun } from "../../ledgers/status.js";
23
- import { CommandError, EXIT, git, } from "../lib.js";
24
- import { resolveRepoSlug } from "../../ledgers/telemetry.js";
28
+ import { CommandError, EXIT, git, outboxRel, outboxRoot, } from "../lib.js";
29
+ import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
30
+ import { parseJson } from "../../shared/json.js";
31
+ import { checkedTable } from "../../shared/text.js";
25
32
  import { buildComment } from "./issues.js";
33
+ import { parsePlanBlocks, reuseInventory, } from "./plan-blocks.js";
34
+ import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
26
35
  import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
27
36
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
37
+ import { doneTasks, redRows } from "./tests.js";
28
38
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
29
39
  export const EXIT_ARTIFACT = 4;
30
40
  // ---------------------------------------------------------------------------
@@ -52,6 +62,37 @@ export const fenced = (payload) => Buffer.concat([
52
62
  payload,
53
63
  Buffer.from(`${FENCE_CLOSE}\n`),
54
64
  ]);
65
+ const RENDERS = ["table", "raw"];
66
+ /**
67
+ * Copy the original of a file about to be trimmed or rendered to
68
+ * `{rawDir}/{name}.raw.{ext}`, byte for byte; `content` stands in for a file that
69
+ * was never written whole. Returns the copy's path.
70
+ */
71
+ export function keepRaw(file, rawDir, content) {
72
+ const ext = path.extname(file);
73
+ const raw = path.join(rawDir, `${path.basename(file, ext)}.raw${ext}`);
74
+ fs.mkdirSync(rawDir, { recursive: true });
75
+ if (content === undefined)
76
+ fs.copyFileSync(file, raw);
77
+ else
78
+ fs.writeFileSync(raw, content);
79
+ return raw;
80
+ }
81
+ /** `keepRaw`, with a failed copy handed back as its error so the caller picks the exit code. */
82
+ function keepRawOrError(file, rawDir) {
83
+ try {
84
+ return keepRaw(file, rawDir);
85
+ }
86
+ catch (err) {
87
+ return err instanceof Error ? err : new Error(String(err));
88
+ }
89
+ }
90
+ /** The outbox folder a feature's originals go to (the outbox root without a fid); null outside a repo. */
91
+ export function rawDirFor(cwd, fid) {
92
+ const root = outboxRoot(cwd);
93
+ return root === null ? null : path.join(root, fid ?? "");
94
+ }
95
+ const utcNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
55
96
  const LEDGER = { maxLines: 200, maxBytes: 51200 };
56
97
  const EVIDENCE = {
57
98
  softLines: 3000,
@@ -264,7 +305,7 @@ function selectEvidence(buf) {
264
305
  * left byte-identical; otherwise the kept content plus footer replace it via a
265
306
  * sibling temp file, never truncating in place.
266
307
  */
267
- export function clampFile(file, profile, artifact = file) {
308
+ export function clampFile(file, profile, artifact = file, keep) {
268
309
  if (!CLAMP_PROFILES.includes(profile)) {
269
310
  throw new CommandError(EXIT.USAGE, `unknown profile '${profile}' (known: ${CLAMP_PROFILES.join(", ")})`);
270
311
  }
@@ -274,6 +315,8 @@ export function clampFile(file, profile, artifact = file) {
274
315
  }
275
316
  const buf = read.buf;
276
317
  const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
318
+ const source = keep?.source ?? null;
319
+ const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
277
320
  const untouched = (s) => ({
278
321
  artifact,
279
322
  clamped: false,
@@ -283,9 +326,20 @@ export function clampFile(file, profile, artifact = file) {
283
326
  keptBytes: s?.keptBytes ?? buf.length,
284
327
  lineCapped: 0,
285
328
  ceilingHit: false,
329
+ raw: null,
330
+ source,
331
+ fetchedAt,
286
332
  });
287
333
  if (sel === null || sel.body.length === 0)
288
334
  return untouched(sel);
335
+ let raw = keep?.original ?? null;
336
+ if (raw === null && keep?.rawDir) {
337
+ const kept = keepRawOrError(file, keep.rawDir);
338
+ // The trim would lose the only copy: refuse it, the file stays whole.
339
+ if (kept instanceof Error)
340
+ throw new CommandError(EXIT_ARTIFACT, `cannot keep the original of '${artifact}': ${kept.message}`);
341
+ raw = kept;
342
+ }
289
343
  const footer = [];
290
344
  if (sel.lineCapped > 1) {
291
345
  footer.push(`> [bkit] ${sel.lineCapped} over-long lines were shortened; each says so inline.`);
@@ -310,6 +364,9 @@ export function clampFile(file, profile, artifact = file) {
310
364
  keptBytes: sel.keptBytes,
311
365
  lineCapped: sel.lineCapped,
312
366
  ceilingHit: sel.ceilingHit,
367
+ raw: raw === null ? null : outboxRel(path.dirname(file), raw),
368
+ source,
369
+ fetchedAt,
313
370
  };
314
371
  }
315
372
  function readable(file) {
@@ -375,7 +432,15 @@ const RECORD_OUTPUT = {
375
432
  keptBytes: "content bytes kept",
376
433
  lineCapped: "over-long lines shortened in place",
377
434
  ceilingHit: "true when the hard ceiling dropped matching lines too",
435
+ raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
436
+ source: "the command that produced the file (--source), or null",
437
+ fetchedAt: "when the source ran (UTC; the clamp time with --source), or null",
378
438
  };
439
+ /** Say so when a cut had nowhere to keep its original. */
440
+ function warnNoRaw(ctx, record, keep) {
441
+ if (record.clamped && record.raw === null && keep.rawDir === null)
442
+ ctx.log(`${record.artifact}: not inside a git repo — original not kept`);
443
+ }
379
444
  // ---------------------------------------------------------------------------
380
445
  // Ledger scan — plan Step 4's related deferrals / failures
381
446
  // ---------------------------------------------------------------------------
@@ -518,24 +583,405 @@ function asCaptured(out) {
518
583
  return Buffer.concat([bytes.subarray(0, end), Buffer.from("\n")]);
519
584
  }
520
585
  // ---------------------------------------------------------------------------
586
+ // Diff artifact — the one definition of "the run's diff"
587
+ //
588
+ // Build briefs, the challenge size gate and per-group verify read the same range
589
+ // the same way: `{base}...HEAD` with `docs/plans/**` excluded, written to one
590
+ // file. Past the guard the file holds a per-file budget instead of the whole diff
591
+ // (`--stat`, then the largest files first, each cut), and its first line says so.
592
+ // ---------------------------------------------------------------------------
593
+ /** Exit code: --base does not name a commit. */
594
+ export const EXIT_BASE = 5;
595
+ export const DIFF_BASE = "origin/dev";
596
+ export const DIFF_EXCLUDES = ["docs/plans/**"];
597
+ export const PARTIAL_MARK = "partial diff coverage";
598
+ export const DIFF_GUARD = {
599
+ fullLines: 10000,
600
+ topFiles: 20,
601
+ perFileLines: 500,
602
+ totalLines: 50000,
603
+ };
604
+ /** git's stdout as bytes; empty when git fails (a range it rejects diffs as nothing). */
605
+ function gitBytes(cwd, args) {
606
+ const res = spawnSync("git", args, { cwd, env: gitEnv(), maxBuffer: 1 << 29 });
607
+ return res.status === 0 ? (res.stdout ?? Buffer.alloc(0)) : Buffer.alloc(0);
608
+ }
609
+ const excludeSpec = () => ["--", ".", ...DIFF_EXCLUDES.map((e) => `:(exclude)${e}`)];
610
+ /** Per-file `--numstat` rows over the range and excludes; a binary file counts with no lines. */
611
+ export function diffNumstat(cwd, range) {
612
+ const files = [];
613
+ let linesAdded = 0;
614
+ let linesDeleted = 0;
615
+ const rows = gitBytes(cwd, ["diff", "--numstat", "--no-renames", range, ...excludeSpec()])
616
+ .toString("utf-8")
617
+ .split("\n");
618
+ for (const row of rows) {
619
+ if (row === "")
620
+ continue;
621
+ const [a, d, ...rest] = row.split("\t");
622
+ const added = Number(a) || 0;
623
+ const deleted = Number(d) || 0;
624
+ linesAdded += added;
625
+ linesDeleted += deleted;
626
+ files.push({ path: rest.join("\t"), lines: added + deleted });
627
+ }
628
+ return {
629
+ files,
630
+ stat: {
631
+ filesChanged: files.length,
632
+ linesAdded,
633
+ linesDeleted,
634
+ linesChanged: linesAdded + linesDeleted,
635
+ },
636
+ };
637
+ }
638
+ const joinLines = (lines) => lines.length === 0 ? Buffer.alloc(0) : Buffer.concat([...lines.flatMap((l) => [l, lineOf("")])]);
639
+ /** {@link writeDiffArtifact}; the artifact, or the error text when the write fails. */
640
+ function tryWriteDiffArtifact(...args) {
641
+ try {
642
+ return { ok: true, result: writeDiffArtifact(...args) };
643
+ }
644
+ catch (err) {
645
+ // Reported as the artifact exit code, with the reason.
646
+ return { ok: false, error: err.message };
647
+ }
648
+ }
649
+ /** Write the range's diff to `out`: whole under the guard, else a per-file budget; the record says which. */
650
+ export function writeDiffArtifact(cwd, out, artifact, range, guard = DIFF_GUARD, keep = { rawDir: null }) {
651
+ const fetchedAt = utcNow();
652
+ const { files, stat } = diffNumstat(cwd, range);
653
+ const full = gitBytes(cwd, ["diff", range, ...excludeSpec()]);
654
+ const diffLines = records(full).length;
655
+ let content;
656
+ let partial = false;
657
+ let ceilingHit = false;
658
+ const omitted = [];
659
+ if (diffLines === 0) {
660
+ content = lineOf(`No changes in ${range} outside ${DIFF_EXCLUDES.join(", ")}.`);
661
+ }
662
+ else if (diffLines <= guard.fullLines) {
663
+ content = full;
664
+ }
665
+ else {
666
+ partial = true;
667
+ const ranked = [...files].sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path));
668
+ const shown = ranked.slice(0, guard.topFiles);
669
+ const stat0 = gitBytes(cwd, ["diff", "--stat", range, ...excludeSpec()]);
670
+ // Header, omitted-files line, a blank, --stat and a blank count toward the total.
671
+ const room0 = guard.totalLines - (4 + records(stat0).length);
672
+ const body = [];
673
+ let used = 0;
674
+ const add = (b) => {
675
+ body.push(b);
676
+ used += records(b).length;
677
+ };
678
+ let stopped = false;
679
+ for (const f of ranked) {
680
+ if (stopped || !shown.includes(f)) {
681
+ omitted.push(f.path);
682
+ continue;
683
+ }
684
+ const room = Math.min(guard.perFileLines, room0 - used);
685
+ if (room <= 0) {
686
+ ceilingHit = true;
687
+ stopped = true;
688
+ omitted.push(f.path);
689
+ add(lineOf(`# total line budget reached; ${f.path} and smaller files not shown`));
690
+ continue;
691
+ }
692
+ const lines = records(gitBytes(cwd, ["diff", range, "--", f.path]));
693
+ const kept = lines.slice(0, room);
694
+ if (kept.length < lines.length && room < guard.perFileLines)
695
+ ceilingHit = true;
696
+ add(lineOf(`### ${f.path}`));
697
+ add(joinLines(kept));
698
+ if (kept.length < lines.length) {
699
+ omitted.push(f.path);
700
+ add(lineOf(`# ${lines.length - kept.length} more lines of ${f.path} not shown`));
701
+ }
702
+ add(lineOf(""));
703
+ }
704
+ omitted.sort((a, b) => a.localeCompare(b));
705
+ content = Buffer.concat([
706
+ lineOf(`# ${PARTIAL_MARK}: ${range} has ${diffLines} diff lines across ${stat.filesChanged} files; showing the ${shown.length} largest files, ${guard.perFileLines} lines each, at most ${guard.totalLines} lines in all. Say "${PARTIAL_MARK}" in any verdict read from this file.`),
707
+ lineOf(`# not shown whole: ${omitted.join(", ")}`),
708
+ lineOf(""),
709
+ stat0,
710
+ lineOf(""),
711
+ ...body,
712
+ ]);
713
+ }
714
+ const raw = partial && keep.rawDir !== null ? keepRaw(out, keep.rawDir, full) : null;
715
+ fs.mkdirSync(path.dirname(out), { recursive: true });
716
+ fs.writeFileSync(out, content);
717
+ const record = {
718
+ artifact,
719
+ clamped: partial,
720
+ origLines: diffLines,
721
+ keptLines: partial ? records(content).length : diffLines,
722
+ origBytes: full.length,
723
+ keptBytes: content.length,
724
+ lineCapped: 0,
725
+ ceilingHit,
726
+ raw: raw === null ? null : outboxRel(cwd, raw),
727
+ source: `git diff ${range} -- . ${DIFF_EXCLUDES.map((e) => `':(exclude)${e}'`).join(" ")}`,
728
+ fetchedAt,
729
+ };
730
+ return { range, stat, diffLines, partial, omitted, record };
731
+ }
732
+ // ---------------------------------------------------------------------------
733
+ // Brief — what one group's build agents read
734
+ //
735
+ // The engine writes it so the orchestrator never reads the plan: the plan's
736
+ // why and what, where the group sits, the group's open task blocks verbatim,
737
+ // one-line summaries of the earlier tasks they depend on, the Reuse Inventory
738
+ // rows and Architecture entries for the open tasks' files, and the deviations
739
+ // note when there is one.
740
+ // ---------------------------------------------------------------------------
741
+ /** A brief whose work section is over this many bytes warns: the group may not fit one fresh context. */
742
+ export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
743
+ /** The plan sections a brief carries as its why and what, by heading text. */
744
+ const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
745
+ /** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
746
+ const EXECUTE_LOG = /^build-plan-execute-.+-log\.md$/;
747
+ /** A heading's text without leading emoji and marks. */
748
+ const headingText = (text) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
749
+ /**
750
+ * The body of the first heading named `name`, up to the next heading of the
751
+ * same or a higher level. Lines inside code fences are never headings.
752
+ */
753
+ function planSection(lines, name) {
754
+ let start = -1;
755
+ let level = 0;
756
+ let fence = false;
757
+ for (let i = 0; i < lines.length; i++) {
758
+ const line = lines[i];
759
+ if (/^\s*(`{3,}|~{3,})/.test(line))
760
+ fence = !fence;
761
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
762
+ if (m === null)
763
+ continue;
764
+ if (start >= 0 && m[1].length <= level)
765
+ return lines.slice(start, i).join("\n").trim();
766
+ if (start < 0 && headingText(m[2]) === name) {
767
+ start = i + 1;
768
+ level = m[1].length;
769
+ }
770
+ }
771
+ return start < 0 ? undefined : lines.slice(start).join("\n").trim();
772
+ }
773
+ /** Every task number a plan-execute log in `dir` records `DONE`. */
774
+ function loggedDone(dir) {
775
+ const done = new Set();
776
+ if (!fs.existsSync(dir))
777
+ return done;
778
+ for (const f of fs.readdirSync(dir).filter((f) => EXECUTE_LOG.test(f)))
779
+ for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8")))
780
+ done.add(n);
781
+ return done;
782
+ }
783
+ /** The plan sections whose entries a brief copies for the group's files. */
784
+ const INVENTORY_SECTION = "Reuse Inventory";
785
+ const ARCHITECTURE_SECTION = "Architecture & Component Changes";
786
+ /** Backticked repo-relative paths in `text`, normalised. */
787
+ const backticked = (text) => [...text.matchAll(/`([^`]+)`/g)].map((m) => path.posix.normalize(m[1]));
788
+ /**
789
+ * The Reuse Inventory table's header and separator lines (`reuseInventory`), and its rows
790
+ * whose `File` cell names a file in `files`. No table or no `File` column → no rows.
791
+ */
792
+ function inventoryRows(lines, files) {
793
+ const table = reuseInventory(lines.join("\n"));
794
+ if (table === null)
795
+ return { head: [], rows: [] };
796
+ const rows = table.rows.filter((r) => r.files.some((f) => files.has(f))).map((r) => r.line);
797
+ return { head: table.head, rows };
798
+ }
799
+ /**
800
+ * The Architecture & Component Changes entries whose heading names a file in `files`:
801
+ * the heading through the line before the next heading of the same or a higher level.
802
+ * Lines inside code fences are never headings.
803
+ */
804
+ function architectureEntries(lines, files) {
805
+ const body = (planSection(lines, ARCHITECTURE_SECTION) ?? "").split("\n");
806
+ const heads = [];
807
+ let fence = false;
808
+ body.forEach((line, i) => {
809
+ if (/^\s*(`{3,}|~{3,})/.test(line))
810
+ fence = !fence;
811
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
812
+ if (m !== null)
813
+ heads.push({ i, level: m[1].length, text: m[2] });
814
+ });
815
+ return heads.flatMap((h, k) => {
816
+ if (!backticked(h.text).some((f) => files.has(f)))
817
+ return [];
818
+ const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.i ?? body.length;
819
+ return [body.slice(h.i, end).join("\n").trim()];
820
+ });
821
+ }
822
+ /** The next free `build-brief-{group}-{n}.md` in `dir`. */
823
+ function nextBriefPath(dir, group) {
824
+ const re = new RegExp(`^build-brief-${group}-([0-9]+)\\.md$`);
825
+ const taken = fs.existsSync(dir)
826
+ ? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
827
+ : [];
828
+ return path.join(dir, `build-brief-${group}-${Math.max(0, ...taken) + 1}.md`);
829
+ }
830
+ /** The brief's text and its work section's size in bytes. */
831
+ export function briefText(o) {
832
+ const lines = o.plan.split("\n");
833
+ const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
834
+ const out = [`# Brief: group ${o.group.group} — ${o.group.title}`, "", `Plan: ${title}`, ""];
835
+ out.push("## Why and what", "");
836
+ for (const name of BRIEF_SECTIONS) {
837
+ const body = planSection(lines, name);
838
+ if (body !== undefined && body !== "")
839
+ out.push(`### ${name}`, "", body, "");
840
+ }
841
+ out.push("## Where it fits", "");
842
+ const nextGroup = o.groups.find((g) => g.group > o.group.group && g.tasks.some((t) => !o.isDone(t)));
843
+ for (const g of o.groups) {
844
+ const state = g.tasks.every(o.isDone)
845
+ ? "done"
846
+ : g === o.group
847
+ ? "this group"
848
+ : g === nextGroup
849
+ ? "next"
850
+ : g.group > o.group.group
851
+ ? "later"
852
+ : "open";
853
+ out.push(`- Group ${g.group}: ${g.title} — ${state}`);
854
+ for (const t of g.tasks)
855
+ out.push(` - TASK ${t.task}: ${t.title} — ${o.isDone(t) ? "done" : "open"}`);
856
+ }
857
+ out.push("");
858
+ const open = o.group.tasks.filter((t) => !o.isDone(t));
859
+ const work = ["## The work", ""];
860
+ for (const t of open)
861
+ work.push(t.text.trim(), "");
862
+ const openNums = new Set(open.map((t) => t.task));
863
+ const reds = o.reds.filter((r) => openNums.has(Number(r.task)));
864
+ if (reds.length > 0) {
865
+ work.push("### Reds already recorded", "");
866
+ for (const r of reds)
867
+ work.push(`- TASK ${Number(r.task)}: red already recorded for \`${String(r.test)}\` \`${String(r.testName)}\` — test written and seen failing; code may be partly done in the files it names`);
868
+ work.push("");
869
+ }
870
+ const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
871
+ .filter((n) => !o.group.tasks.some((t) => t.task === n))
872
+ .sort((a, b) => a - b)
873
+ .map((n) => o.groups.flatMap((g) => g.tasks).find((t) => t.task === n))
874
+ .filter((t) => t !== undefined);
875
+ if (deps.length > 0) {
876
+ work.push("### Earlier tasks this group depends on", "");
877
+ for (const t of deps) {
878
+ const files = [...new Set([...t.create, ...t.update, ...t.delete].map((r) => r.file))];
879
+ const where = files.length > 0 ? ` — ${files.map((f) => `\`${f}\``).join(", ")}` : "";
880
+ work.push(`- TASK ${t.task} (group ${t.group}, ${o.isDone(t) ? "done" : "open"}): ${t.title}${where}`);
881
+ }
882
+ work.push("");
883
+ }
884
+ work.push(...planEntries(lines, open, work, o.planFile));
885
+ out.push(...work);
886
+ if (o.note !== undefined)
887
+ out.push("## Deviations", "", o.note.trim(), "");
888
+ return {
889
+ text: out.join("\n"),
890
+ workBytes: Buffer.byteLength(work.join("\n")),
891
+ };
892
+ }
893
+ /**
894
+ * The Reuse Inventory rows, then the Architecture entries, for the files on the open
895
+ * tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
896
+ * within BRIEF_WORK_WARN_BYTES; the rest are counted in a closing line naming where to
897
+ * read them.
898
+ */
899
+ function planEntries(lines, open, work, planFile) {
900
+ const files = new Set(open.flatMap((t) => [...t.create, ...t.update, ...t.delete].map((r) => path.posix.normalize(r.file))));
901
+ const inventory = inventoryRows(lines, files);
902
+ const arch = architectureEntries(lines, files);
903
+ const keptRows = [];
904
+ const keptArch = [];
905
+ const render = (rowsLeft, archLeft) => {
906
+ const part = [];
907
+ if (keptRows.length > 0)
908
+ part.push("### Reuse Inventory rows", "", ...inventory.head, ...keptRows, "");
909
+ if (keptArch.length > 0)
910
+ part.push("### Architecture entries", "", ...keptArch.flatMap((e) => [e, ""]));
911
+ if (rowsLeft + archLeft > 0)
912
+ part.push(`Reuse Inventory rows left out: ${rowsLeft}; Architecture entries left out: ${archLeft} — read them in ${planFile} § ${INVENTORY_SECTION} and § ${ARCHITECTURE_SECTION}.`, "");
913
+ return part;
914
+ };
915
+ const fits = (rowsLeft, archLeft) => Buffer.byteLength([...work, ...render(rowsLeft, archLeft)].join("\n")) <= BRIEF_WORK_WARN_BYTES;
916
+ // The counts passed to `fits` are those not yet kept, an upper bound on the final ones.
917
+ let rowsLeft = inventory.rows.length;
918
+ let archLeft = arch.length;
919
+ for (const row of inventory.rows) {
920
+ keptRows.push(row);
921
+ if (fits(rowsLeft - 1, archLeft))
922
+ rowsLeft--;
923
+ else
924
+ keptRows.pop();
925
+ }
926
+ for (const entry of arch) {
927
+ keptArch.push(entry);
928
+ if (fits(rowsLeft, archLeft - 1))
929
+ archLeft--;
930
+ else
931
+ keptArch.pop();
932
+ }
933
+ return render(rowsLeft, archLeft);
934
+ }
935
+ // ---------------------------------------------------------------------------
521
936
  // Command
522
937
  // ---------------------------------------------------------------------------
938
+ const RUN_BLOCK_FLAGS = [
939
+ { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
940
+ {
941
+ name: "script",
942
+ type: "string",
943
+ required: true,
944
+ help: "file holding the block body as customised for this failure (run with bash)",
945
+ },
946
+ FID_FLAG,
947
+ MONTH_FLAG,
948
+ ...ATTEMPT_FLAGS,
949
+ ];
950
+ const RUN_BLOCK_OUTPUT = {
951
+ outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
952
+ artifact: "the artifact path, or null when nothing was written",
953
+ skip: "the block's [context-fetch:<name>] stderr line, or null",
954
+ clamp: "the payload's clamp record, or null",
955
+ reason: "why the block was not run, or null",
956
+ };
523
957
  export const contextCommand = {
524
958
  noun: "context",
525
- summary: "Clamp context artifacts; scan ledgers; list, run and record consumer context-fetch blocks.",
959
+ summary: "Clamp context artifacts; scan ledgers; write the run's diff and a build group's brief; list, run and record consumer context-fetch blocks.",
526
960
  verbs: {
527
961
  clamp: {
528
962
  summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
529
963
  flags: [
530
964
  { name: "artifact", type: "string", required: true, help: "file to clamp" },
531
965
  { name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
966
+ {
967
+ name: "source",
968
+ type: "string",
969
+ help: "the exact command and inputs that produced the artifact (recorded with the time)",
970
+ },
532
971
  ...LOG_FLAGS,
533
972
  ],
534
973
  output: RECORD_OUTPUT,
535
- exitCodes: { [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced" },
974
+ exitCodes: {
975
+ [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced; or its original could not be kept",
976
+ },
536
977
  run: (ctx) => {
537
978
  const artifact = String(ctx.flags.artifact);
538
- const record = clampFile(path.resolve(ctx.cwd, artifact), String(ctx.flags.profile), artifact);
979
+ const keep = {
980
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
981
+ source: str(ctx.flags.source),
982
+ };
983
+ const record = clampFile(path.resolve(ctx.cwd, artifact), String(ctx.flags.profile), artifact, keep);
984
+ warnNoRaw(ctx, record, keep);
539
985
  const log = logPath(ctx);
540
986
  if (log !== undefined)
541
987
  appendRecord(log, record);
@@ -590,6 +1036,7 @@ export const contextCommand = {
590
1036
  kept: "lines written (at most 40)",
591
1037
  clamp: "the clamp record",
592
1038
  },
1039
+ textOmit: ["clamp"],
593
1040
  exitCodes: { [EXIT_ARTIFACT]: "artifact could not be written or replaced" },
594
1041
  run: (ctx) => {
595
1042
  const log = logPath(ctx);
@@ -601,12 +1048,18 @@ export const contextCommand = {
601
1048
  }
602
1049
  const sourceFile = path.resolve(ctx.cwd, String(ctx.flags.source));
603
1050
  const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf-8") : undefined;
604
- const scan = ledgerScan(source, String(ctx.flags.terms));
1051
+ const terms = String(ctx.flags.terms);
1052
+ const scan = ledgerScan(source, terms);
605
1053
  const artifact = String(ctx.flags.artifact);
606
1054
  const out = path.resolve(ctx.cwd, artifact);
607
1055
  fs.mkdirSync(path.dirname(out), { recursive: true });
608
1056
  fs.writeFileSync(out, scan.content);
609
- const clamp = clampFile(out, "ledger", artifact);
1057
+ const keep = {
1058
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1059
+ source: `bkit context ledger-scan --source=${String(ctx.flags.source)} --terms="${terms}"`,
1060
+ };
1061
+ const clamp = clampFile(out, "ledger", artifact, keep);
1062
+ warnNoRaw(ctx, clamp, keep);
610
1063
  if (log !== undefined)
611
1064
  appendRecord(log, clamp);
612
1065
  ctx.log(`${artifact}: ${scan.total} matching line(s), ${scan.kept} kept`);
@@ -614,6 +1067,178 @@ export const contextCommand = {
614
1067
  return EXIT.OK;
615
1068
  },
616
1069
  },
1070
+ diff: {
1071
+ summary: "Write the run's diff ({base}...HEAD, docs/plans/** excluded) as one artifact — whole, or a per-file budget past the guard — and print its numbers.",
1072
+ flags: [
1073
+ { name: "artifact", type: "string", required: true, help: "file to write" },
1074
+ {
1075
+ name: "base",
1076
+ type: "string",
1077
+ help: `merge base or a group's start commit (default ${DIFF_BASE})`,
1078
+ },
1079
+ ...LOG_FLAGS,
1080
+ {
1081
+ name: "reset-log",
1082
+ type: "boolean",
1083
+ help: "empty the clamp log first (the step's first writer)",
1084
+ },
1085
+ ],
1086
+ output: {
1087
+ artifact: "the artifact path as given",
1088
+ base: "the base used",
1089
+ range: "the range diffed ({base}...HEAD)",
1090
+ filesChanged: "files in the diff (--numstat, same excludes)",
1091
+ linesAdded: "lines added",
1092
+ linesDeleted: "lines deleted",
1093
+ linesChanged: "linesAdded + linesDeleted",
1094
+ diffLines: "lines in the whole diff",
1095
+ 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`,
1096
+ omitted: "files whose diff is not in the artifact whole (not shown, or cut); [] unless partial — the artifact's second line lists them too",
1097
+ clamp: "the clamp record (clamped = partial; raw = the whole diff in the outbox when partial)",
1098
+ },
1099
+ textOmit: ["clamp"],
1100
+ exitCodes: {
1101
+ [EXIT_BASE]: "--base does not name a commit",
1102
+ [EXIT_ARTIFACT]: "the artifact could not be written",
1103
+ },
1104
+ run: (ctx) => {
1105
+ const base = str(ctx.flags.base) ?? DIFF_BASE;
1106
+ if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
1107
+ throw new CommandError(EXIT_BASE, `--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`);
1108
+ }
1109
+ const artifact = String(ctx.flags.artifact);
1110
+ const log = logPath(ctx);
1111
+ if (ctx.flags.resetLog === true) {
1112
+ if (log === undefined)
1113
+ throw new CommandError(EXIT.USAGE, "--reset-log needs --log, or --fid and --step");
1114
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1115
+ fs.writeFileSync(log, "");
1116
+ }
1117
+ const written = tryWriteDiffArtifact(ctx.cwd, path.resolve(ctx.cwd, artifact), artifact, `${base}...HEAD`, DIFF_GUARD, { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) });
1118
+ if (!written.ok)
1119
+ throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
1120
+ const result = written.result;
1121
+ if (log !== undefined)
1122
+ appendRecord(log, result.record);
1123
+ if (result.partial) {
1124
+ ctx.log(`${artifact}: ${result.diffLines} diff lines, over the ${DIFF_GUARD.fullLines}-line guard — per-file budget written (${PARTIAL_MARK})`);
1125
+ }
1126
+ ctx.emit({
1127
+ artifact,
1128
+ base,
1129
+ range: result.range,
1130
+ ...result.stat,
1131
+ diffLines: result.diffLines,
1132
+ partial: result.partial,
1133
+ omitted: result.omitted,
1134
+ clamp: result.record,
1135
+ });
1136
+ return EXIT.OK;
1137
+ },
1138
+ },
1139
+ brief: {
1140
+ summary: "Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes.",
1141
+ flags: [
1142
+ { name: "plan", type: "string", required: true, help: "the plan file" },
1143
+ { name: "group", type: "string", help: "the group to brief" },
1144
+ {
1145
+ name: "next",
1146
+ type: "boolean",
1147
+ help: "brief the first group with an open task (none open → nothing written, group null)",
1148
+ },
1149
+ {
1150
+ name: "dir",
1151
+ type: "string",
1152
+ required: true,
1153
+ help: "the run's logs folder: the brief is written there, and its build-plan-execute-*-log.md DONE lines mark tasks done",
1154
+ },
1155
+ {
1156
+ name: "file",
1157
+ type: "string",
1158
+ help: "status.jsonl, to name the reds already recorded for open tasks",
1159
+ },
1160
+ {
1161
+ name: "note-file",
1162
+ type: "string",
1163
+ help: "text for the Deviations section (left out when not given)",
1164
+ },
1165
+ ],
1166
+ output: {
1167
+ artifact: "the brief's path (null when --next finds no open group)",
1168
+ bytes: "the brief's size in bytes",
1169
+ group: "the group briefed (null when --next finds no open group)",
1170
+ tasks: "the open task numbers the brief carries",
1171
+ workBytes: "the work section's size in bytes (0 when --next finds no open group)",
1172
+ workCap: `the work section's cap in bytes (${BRIEF_WORK_WARN_BYTES}): Reuse Inventory rows and Architecture entries past it are left out and counted; task blocks over it warn on stderr`,
1173
+ },
1174
+ exitCodes: {
1175
+ [EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
1176
+ [EXIT_NO_STATUS]: "--file names a missing or malformed status.jsonl",
1177
+ },
1178
+ run: (ctx) => {
1179
+ const groupFlag = positiveInt(ctx.flags.group, "group");
1180
+ if ((groupFlag === undefined) === (ctx.flags.next !== true))
1181
+ throw new CommandError(EXIT.USAGE, "give exactly one of --group=N and --next");
1182
+ const planFile = path.resolve(ctx.cwd, String(ctx.flags.plan));
1183
+ if (!fs.existsSync(planFile))
1184
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)} does not exist`);
1185
+ const plan = fs.readFileSync(planFile, "utf-8");
1186
+ const blocks = parsePlanBlocks(plan);
1187
+ if (blocks.errors.length > 0) {
1188
+ const e = blocks.errors[0];
1189
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)}:${e.line}: ${e.message} — run \`bkit tests plan-check\``);
1190
+ }
1191
+ const dir = path.resolve(ctx.cwd, String(ctx.flags.dir));
1192
+ const done = loggedDone(dir);
1193
+ const isDone = (t) => t.done || done.has(t.task);
1194
+ const group = groupFlag === undefined
1195
+ ? blocks.groups.find((g) => g.tasks.some((t) => !isDone(t)))
1196
+ : blocks.groups.find((g) => g.group === groupFlag);
1197
+ if (group === undefined && groupFlag !== undefined)
1198
+ throw new CommandError(EXIT.USAGE, `the plan has no group ${groupFlag}`);
1199
+ if (group === undefined) {
1200
+ ctx.emit({
1201
+ artifact: null,
1202
+ bytes: 0,
1203
+ group: null,
1204
+ tasks: [],
1205
+ workBytes: 0,
1206
+ workCap: BRIEF_WORK_WARN_BYTES,
1207
+ });
1208
+ return EXIT.OK;
1209
+ }
1210
+ const noteFlag = str(ctx.flags.noteFile);
1211
+ const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1212
+ if (noteFile !== undefined && !fs.existsSync(noteFile))
1213
+ throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1214
+ const status = str(ctx.flags.file);
1215
+ const { text, workBytes } = briefText({
1216
+ plan,
1217
+ planFile: String(ctx.flags.plan),
1218
+ group,
1219
+ groups: blocks.groups,
1220
+ isDone,
1221
+ reds: status === undefined ? [] : redRows(path.resolve(ctx.cwd, status), "build"),
1222
+ note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1223
+ });
1224
+ const out = nextBriefPath(dir, group.group);
1225
+ fs.mkdirSync(dir, { recursive: true });
1226
+ fs.writeFileSync(out, text);
1227
+ if (workBytes > BRIEF_WORK_WARN_BYTES) {
1228
+ ctx.log(`${out}: the work section is ${humanBytes(workBytes)}, over ${humanBytes(BRIEF_WORK_WARN_BYTES)} — the group may not fit one fresh context`);
1229
+ }
1230
+ const artifact = path.isAbsolute(String(ctx.flags.dir)) ? out : path.relative(ctx.cwd, out);
1231
+ ctx.emit({
1232
+ artifact,
1233
+ bytes: Buffer.byteLength(text),
1234
+ group: group.group,
1235
+ tasks: group.tasks.filter((t) => !isDone(t)).map((t) => t.task),
1236
+ workBytes,
1237
+ workCap: BRIEF_WORK_WARN_BYTES,
1238
+ });
1239
+ return EXIT.OK;
1240
+ },
1241
+ },
617
1242
  "list-blocks": {
618
1243
  summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
619
1244
  flags: [],
@@ -648,30 +1273,40 @@ export const contextCommand = {
648
1273
  },
649
1274
  "run-block": {
650
1275
  summary: "Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
1276
+ flags: RUN_BLOCK_FLAGS,
1277
+ output: RUN_BLOCK_OUTPUT,
1278
+ textOmit: ["clamp"],
1279
+ exitCodes: {
1280
+ [EXIT_ARTIFACT]: "the payload could not be clamped or written",
1281
+ [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
1282
+ },
1283
+ run: (ctx) => runBlock(ctx),
1284
+ },
1285
+ fetch: {
1286
+ summary: "run-block, with a JSON array of flat objects written as a markdown table; the raw output stays in the outbox.",
651
1287
  flags: [
652
- { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1288
+ ...RUN_BLOCK_FLAGS,
653
1289
  {
654
- name: "script",
1290
+ name: "render",
655
1291
  type: "string",
656
- required: true,
657
- help: "file holding the block body as customised for this failure (run with bash)",
1292
+ help: "table (default): a JSON array of flat objects becomes a markdown table when it reads back unchanged, else the output is written as printed; raw: as printed",
658
1293
  },
659
- FID_FLAG,
660
- MONTH_FLAG,
661
- ...ATTEMPT_FLAGS,
662
1294
  ],
663
1295
  output: {
664
- outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
665
- artifact: "the artifact path, or null when nothing was written",
666
- skip: "the block's [context-fetch:<name>] stderr line, or null",
667
- clamp: "the payload's clamp record, or null",
668
- reason: "why the block was not run, or null",
1296
+ ...RUN_BLOCK_OUTPUT,
1297
+ render: "table | raw: how the output was written; null when nothing was written",
669
1298
  },
1299
+ textOmit: ["clamp"],
670
1300
  exitCodes: {
671
1301
  [EXIT_ARTIFACT]: "the payload could not be clamped or written",
672
1302
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
673
1303
  },
674
- run: (ctx) => runBlock(ctx),
1304
+ run: (ctx) => {
1305
+ const render = str(ctx.flags.render) ?? "table";
1306
+ if (!RENDERS.includes(render))
1307
+ throw new CommandError(EXIT.USAGE, `--render must be ${RENDERS.join("|")}`);
1308
+ return runBlock(ctx, render);
1309
+ },
675
1310
  },
676
1311
  finalise: {
677
1312
  summary: "The context-fetch status row's fields: verdict, artifacts, contexts configured, clamped; --record writes and commits the row and prints the step comment.",
@@ -702,6 +1337,7 @@ export const contextCommand = {
702
1337
  row: "--record: the step-done row written, else null",
703
1338
  commit: "--record: the new commit's sha, else null",
704
1339
  comment: "the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
1340
+ commentFile: COMMENT_FILE_OUTPUT,
705
1341
  },
706
1342
  exitCodes: {
707
1343
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
@@ -774,13 +1410,28 @@ export const contextCommand = {
774
1410
  row: record ? written.row : null,
775
1411
  commit: written.commit,
776
1412
  comment,
1413
+ commentFile: commentFileOf(ctx.cwd, comment),
777
1414
  });
778
1415
  return written.code;
779
1416
  },
780
1417
  },
781
1418
  },
782
1419
  };
783
- function runBlock(ctx) {
1420
+ /** A block's output as a checked markdown table, or why it stays as printed. */
1421
+ function tableOf(stdout) {
1422
+ const parsed = parseJson(stdout.toString("utf-8"));
1423
+ if (!parsed.ok)
1424
+ return { reason: "not JSON" };
1425
+ const table = checkedTable(parsed.value);
1426
+ return table.ok ? { text: table.text } : { reason: table.reason };
1427
+ }
1428
+ /**
1429
+ * Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
1430
+ * (`context fetch`), a JSON array of flat objects is written as a table instead; the
1431
+ * output as printed goes to the outbox first, and the record says which was written.
1432
+ */
1433
+ function runBlock(ctx, render) {
1434
+ const shape = (out, written) => render === undefined ? out : { ...out, render: written };
784
1435
  const idx = positiveInt(ctx.flags.idx, "idx");
785
1436
  const attempt = debugAttempt(ctx);
786
1437
  const fid = String(ctx.flags.fid);
@@ -790,7 +1441,7 @@ function runBlock(ctx) {
790
1441
  const block = fetchBlocks(consumerSection(readContextMd(ctx) ?? "")).find((b) => b.idx === idx);
791
1442
  const notRun = (reason) => {
792
1443
  ctx.log(`context-fetch: ${reason} — NOT RUN`);
793
- ctx.emit({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason });
1444
+ ctx.emit(shape({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason }, null));
794
1445
  return EXIT.OK;
795
1446
  };
796
1447
  if (!block)
@@ -802,6 +1453,7 @@ function runBlock(ctx) {
802
1453
  if (block.body === "")
803
1454
  return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
804
1455
  const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1456
+ const fetchedAt = utcNow();
805
1457
  // The inline block ran inside the step's shell, so these were in scope for it.
806
1458
  const res = spawnSync("bash", [script], {
807
1459
  cwd: ctx.cwd,
@@ -825,22 +1477,49 @@ function runBlock(ctx) {
825
1477
  const shown = `context-fetch context=${block.context} name=${block.name || "default"}`;
826
1478
  if (stdout.some((b) => b !== 0x0a && b !== 0)) {
827
1479
  fs.mkdirSync(path.dirname(out), { recursive: true });
828
- fs.writeFileSync(out, asCaptured(stdout));
829
- const clamp = clampFile(out, "debug-evidence", artifact);
1480
+ const keep = {
1481
+ rawDir: rawDirFor(ctx.cwd, fid),
1482
+ source: fs.readFileSync(script, "utf-8"),
1483
+ fetchedAt,
1484
+ };
1485
+ let payload = asCaptured(stdout);
1486
+ let written = null;
1487
+ if (render !== undefined) {
1488
+ const table = render === "table" ? tableOf(stdout) : null;
1489
+ if (table !== null && "text" in table) {
1490
+ // The table replaces the printed output: keep that output whole first.
1491
+ if (keep.rawDir !== null)
1492
+ keep.original = keepRaw(out, keep.rawDir, stdout);
1493
+ payload = Buffer.from(`${table.text}\n`);
1494
+ written = "table";
1495
+ }
1496
+ else {
1497
+ if (table !== null)
1498
+ ctx.log(`render: raw (${table.reason})`);
1499
+ written = "raw";
1500
+ }
1501
+ }
1502
+ fs.writeFileSync(out, payload);
1503
+ let clamp = clampFile(out, "debug-evidence", artifact, keep);
1504
+ warnNoRaw(ctx, clamp, keep);
1505
+ if (written !== null) {
1506
+ const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
1507
+ clamp = { ...clamp, raw, render: written };
1508
+ }
830
1509
  appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
831
1510
  fs.writeFileSync(out, fenced(fs.readFileSync(out)));
832
1511
  ctx.log(`${shown} CHECKED — data returned`);
833
- ctx.emit({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null });
1512
+ ctx.emit(shape({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null }, written));
834
1513
  return EXIT.OK;
835
1514
  }
836
1515
  if (skip !== undefined) {
837
1516
  fs.mkdirSync(path.dirname(out), { recursive: true });
838
1517
  fs.writeFileSync(out, `${skip}\n`);
839
1518
  ctx.log(`${shown} SELF-SKIPPED (${skip}) — NOT CHECKED; this is NOT evidence that this source was clean (Trusted egress may also silently block the host — see .agents/context.md § Allowed domains)`);
840
- ctx.emit({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null });
1519
+ ctx.emit(shape({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null }, null));
841
1520
  return EXIT.OK;
842
1521
  }
843
1522
  ctx.log(`${shown} produced neither data nor a skip breadcrumb — NOT CHECKED (unexpected silent exit; treat as unavailable, never as clean)`);
844
- ctx.emit({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null });
1523
+ ctx.emit(shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null));
845
1524
  return EXIT.OK;
846
1525
  }