@cbartens/bkit 5.5.1 → 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 (288) 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 +35 -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 +19 -18
  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 +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  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 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  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 +6 -6
  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 +407 -64
  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 +58 -8
  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 +185 -8
  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 +250 -3
  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 +157 -20
  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 +29 -15
  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 +32 -14
  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 +72 -18
  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 +29 -14
  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 +27 -12
  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 +41 -18
  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 +11 -11
  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 +16 -7
  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 +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. 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
 
17
22
  import { spawnSync } from "node:child_process";
18
23
  import * as fs from "node:fs";
@@ -29,14 +34,26 @@ import {
29
34
  CommandError,
30
35
  EXIT,
31
36
  git,
37
+ outboxRel,
38
+ outboxRoot,
32
39
  type CommandSpec,
33
40
  type FlagSpec,
34
41
  type RunContext,
35
42
  } from "../lib.js";
36
- import { resolveRepoSlug } from "../../ledgers/telemetry.js";
43
+ import { gitEnv, resolveRepoSlug } from "../../ledgers/telemetry.js";
44
+ import { parseJson } from "../../shared/json.js";
45
+ import { checkedTable } from "../../shared/text.js";
37
46
  import { buildComment } from "./issues.js";
47
+ import {
48
+ parsePlanBlocks,
49
+ reuseInventory,
50
+ type PlanGroup,
51
+ type PlanTaskBlock,
52
+ } from "./plan-blocks.js";
53
+ import { COMMENT_FILE_OUTPUT, commentFileOf } from "./tracker.js";
38
54
  import { EXIT_NO_STATUS, positiveInt, readRuns, str } from "./status.js";
39
55
  import { EXIT_COMMIT, writeStepRow } from "./steps.js";
56
+ import { doneTasks, redRows } from "./tests.js";
40
57
 
41
58
  /** Exit code: the artifact to clamp is missing, unreadable, or could not be replaced. */
42
59
  export const EXIT_ARTIFACT = 4;
@@ -83,8 +100,61 @@ export interface ClampRecord {
83
100
  keptBytes: number;
84
101
  lineCapped: number;
85
102
  ceilingHit: boolean;
103
+ /** The untouched original in the outbox, main-checkout relative; null when nothing was cut. */
104
+ raw: string | null;
105
+ /** The exact command and inputs that produced the file; null when the caller did not say. */
106
+ source: string | null;
107
+ /** When the source ran (UTC); a re-run returns the source's data now, not then. */
108
+ fetchedAt: string | null;
109
+ /** `context fetch` only: `table` when the output was rendered as a table, else `raw`. */
110
+ render?: Render;
111
+ }
112
+
113
+ /** How `context fetch` writes a block's output. */
114
+ export type Render = "table" | "raw";
115
+ const RENDERS: readonly Render[] = ["table", "raw"];
116
+
117
+ /** Where a cut file's original goes and what produced it. */
118
+ export interface Provenance {
119
+ /** Folder for `{name}.raw.{ext}`; null when there is none (outside a git repo). */
120
+ rawDir: string | null;
121
+ source?: string;
122
+ fetchedAt?: string;
123
+ /** An untouched copy already in the outbox (the runner's own log): no second copy. */
124
+ original?: string;
125
+ }
126
+
127
+ /**
128
+ * Copy the original of a file about to be trimmed or rendered to
129
+ * `{rawDir}/{name}.raw.{ext}`, byte for byte; `content` stands in for a file that
130
+ * was never written whole. Returns the copy's path.
131
+ */
132
+ export function keepRaw(file: string, rawDir: string, content?: Buffer): string {
133
+ const ext = path.extname(file);
134
+ const raw = path.join(rawDir, `${path.basename(file, ext)}.raw${ext}`);
135
+ fs.mkdirSync(rawDir, { recursive: true });
136
+ if (content === undefined) fs.copyFileSync(file, raw);
137
+ else fs.writeFileSync(raw, content);
138
+ return raw;
139
+ }
140
+
141
+ /** `keepRaw`, with a failed copy handed back as its error so the caller picks the exit code. */
142
+ function keepRawOrError(file: string, rawDir: string): string | Error {
143
+ try {
144
+ return keepRaw(file, rawDir);
145
+ } catch (err) {
146
+ return err instanceof Error ? err : new Error(String(err));
147
+ }
148
+ }
149
+
150
+ /** The outbox folder a feature's originals go to (the outbox root without a fid); null outside a repo. */
151
+ export function rawDirFor(cwd: string, fid: string | undefined): string | null {
152
+ const root = outboxRoot(cwd);
153
+ return root === null ? null : path.join(root, fid ?? "");
86
154
  }
87
155
 
156
+ const utcNow = () => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
157
+
88
158
  const LEDGER = { maxLines: 200, maxBytes: 51200 };
89
159
  const EVIDENCE = {
90
160
  softLines: 3000,
@@ -301,7 +371,12 @@ function selectEvidence(buf: Buffer): Selection {
301
371
  * left byte-identical; otherwise the kept content plus footer replace it via a
302
372
  * sibling temp file, never truncating in place.
303
373
  */
304
- export function clampFile(file: string, profile: string, artifact = file): ClampRecord {
374
+ export function clampFile(
375
+ file: string,
376
+ profile: string,
377
+ artifact = file,
378
+ keep?: Provenance,
379
+ ): ClampRecord {
305
380
  if (!(CLAMP_PROFILES as readonly string[]).includes(profile)) {
306
381
  throw new CommandError(
307
382
  EXIT.USAGE,
@@ -314,6 +389,8 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
314
389
  }
315
390
  const buf = read.buf;
316
391
  const sel = profile === "ledger" ? selectLedger(buf) : selectEvidence(buf);
392
+ const source = keep?.source ?? null;
393
+ const fetchedAt = keep?.fetchedAt ?? (source === null ? null : utcNow());
317
394
  const untouched = (s: Selection | null): ClampRecord => ({
318
395
  artifact,
319
396
  clamped: false,
@@ -323,9 +400,24 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
323
400
  keptBytes: s?.keptBytes ?? buf.length,
324
401
  lineCapped: 0,
325
402
  ceilingHit: false,
403
+ raw: null,
404
+ source,
405
+ fetchedAt,
326
406
  });
327
407
  if (sel === null || sel.body.length === 0) return untouched(sel);
328
408
 
409
+ let raw: string | null = keep?.original ?? null;
410
+ if (raw === null && keep?.rawDir) {
411
+ const kept = keepRawOrError(file, keep.rawDir);
412
+ // The trim would lose the only copy: refuse it, the file stays whole.
413
+ if (kept instanceof Error)
414
+ throw new CommandError(
415
+ EXIT_ARTIFACT,
416
+ `cannot keep the original of '${artifact}': ${kept.message}`,
417
+ );
418
+ raw = kept;
419
+ }
420
+
329
421
  const footer: string[] = [];
330
422
  if (sel.lineCapped > 1) {
331
423
  footer.push(`> [bkit] ${sel.lineCapped} over-long lines were shortened; each says so inline.`);
@@ -353,6 +445,9 @@ export function clampFile(file: string, profile: string, artifact = file): Clamp
353
445
  keptBytes: sel.keptBytes,
354
446
  lineCapped: sel.lineCapped,
355
447
  ceilingHit: sel.ceilingHit,
448
+ raw: raw === null ? null : outboxRel(path.dirname(file), raw),
449
+ source,
450
+ fetchedAt,
356
451
  };
357
452
  }
358
453
 
@@ -420,8 +515,17 @@ const RECORD_OUTPUT: Record<string, string> = {
420
515
  keptBytes: "content bytes kept",
421
516
  lineCapped: "over-long lines shortened in place",
422
517
  ceilingHit: "true when the hard ceiling dropped matching lines too",
518
+ raw: "the untouched original in the outbox ({name}.raw.{ext}), or null when nothing was cut",
519
+ source: "the command that produced the file (--source), or null",
520
+ fetchedAt: "when the source ran (UTC; the clamp time with --source), or null",
423
521
  };
424
522
 
523
+ /** Say so when a cut had nowhere to keep its original. */
524
+ function warnNoRaw(ctx: RunContext, record: ClampRecord, keep: Provenance) {
525
+ if (record.clamped && record.raw === null && keep.rawDir === null)
526
+ ctx.log(`${record.artifact}: not inside a git repo — original not kept`);
527
+ }
528
+
425
529
  // ---------------------------------------------------------------------------
426
530
  // Ledger scan — plan Step 4's related deferrals / failures
427
531
  // ---------------------------------------------------------------------------
@@ -593,31 +697,496 @@ function asCaptured(out: Buffer): Buffer {
593
697
  return Buffer.concat([bytes.subarray(0, end), Buffer.from("\n")]);
594
698
  }
595
699
 
700
+ // ---------------------------------------------------------------------------
701
+ // Diff artifact — the one definition of "the run's diff"
702
+ //
703
+ // Build briefs, the challenge size gate and per-group verify read the same range
704
+ // the same way: `{base}...HEAD` with `docs/plans/**` excluded, written to one
705
+ // file. Past the guard the file holds a per-file budget instead of the whole diff
706
+ // (`--stat`, then the largest files first, each cut), and its first line says so.
707
+ // ---------------------------------------------------------------------------
708
+
709
+ /** Exit code: --base does not name a commit. */
710
+ export const EXIT_BASE = 5;
711
+
712
+ export const DIFF_BASE = "origin/dev";
713
+ export const DIFF_EXCLUDES = ["docs/plans/**"];
714
+ export const PARTIAL_MARK = "partial diff coverage";
715
+
716
+ export interface DiffGuard {
717
+ /** A diff longer than this is written as a per-file budget. */
718
+ fullLines: number;
719
+ /** Files shown in budget mode, largest change first. */
720
+ topFiles: number;
721
+ /** Lines kept per shown file. */
722
+ perFileLines: number;
723
+ /** Lines kept in all; the file stops there. */
724
+ totalLines: number;
725
+ }
726
+ export const DIFF_GUARD: DiffGuard = {
727
+ fullLines: 10000,
728
+ topFiles: 20,
729
+ perFileLines: 500,
730
+ totalLines: 50000,
731
+ };
732
+
733
+ export interface DiffStat {
734
+ filesChanged: number;
735
+ linesAdded: number;
736
+ linesDeleted: number;
737
+ linesChanged: number;
738
+ }
739
+
740
+ export interface DiffArtifact {
741
+ range: string;
742
+ stat: DiffStat;
743
+ diffLines: number;
744
+ partial: boolean;
745
+ /** Files whose diff is not in the artifact whole: not shown, or cut. */
746
+ omitted: string[];
747
+ record: ClampRecord;
748
+ }
749
+
750
+ /** git's stdout as bytes; empty when git fails (a range it rejects diffs as nothing). */
751
+ function gitBytes(cwd: string, args: string[]): Buffer {
752
+ const res = spawnSync("git", args, { cwd, env: gitEnv(), maxBuffer: 1 << 29 });
753
+ return res.status === 0 ? (res.stdout ?? Buffer.alloc(0)) : Buffer.alloc(0);
754
+ }
755
+
756
+ const excludeSpec = (): string[] => ["--", ".", ...DIFF_EXCLUDES.map((e) => `:(exclude)${e}`)];
757
+
758
+ /** Per-file `--numstat` rows over the range and excludes; a binary file counts with no lines. */
759
+ export function diffNumstat(
760
+ cwd: string,
761
+ range: string,
762
+ ): { files: { path: string; lines: number }[]; stat: DiffStat } {
763
+ const files: { path: string; lines: number }[] = [];
764
+ let linesAdded = 0;
765
+ let linesDeleted = 0;
766
+ const rows = gitBytes(cwd, ["diff", "--numstat", "--no-renames", range, ...excludeSpec()])
767
+ .toString("utf-8")
768
+ .split("\n");
769
+ for (const row of rows) {
770
+ if (row === "") continue;
771
+ const [a, d, ...rest] = row.split("\t");
772
+ const added = Number(a) || 0;
773
+ const deleted = Number(d) || 0;
774
+ linesAdded += added;
775
+ linesDeleted += deleted;
776
+ files.push({ path: rest.join("\t"), lines: added + deleted });
777
+ }
778
+ return {
779
+ files,
780
+ stat: {
781
+ filesChanged: files.length,
782
+ linesAdded,
783
+ linesDeleted,
784
+ linesChanged: linesAdded + linesDeleted,
785
+ },
786
+ };
787
+ }
788
+
789
+ const joinLines = (lines: Buffer[]): Buffer =>
790
+ lines.length === 0 ? Buffer.alloc(0) : Buffer.concat([...lines.flatMap((l) => [l, lineOf("")])]);
791
+
792
+ /** {@link writeDiffArtifact}; the artifact, or the error text when the write fails. */
793
+ function tryWriteDiffArtifact(
794
+ ...args: Parameters<typeof writeDiffArtifact>
795
+ ): { ok: true; result: DiffArtifact } | { ok: false; error: string } {
796
+ try {
797
+ return { ok: true, result: writeDiffArtifact(...args) };
798
+ } catch (err) {
799
+ // Reported as the artifact exit code, with the reason.
800
+ return { ok: false, error: (err as Error).message };
801
+ }
802
+ }
803
+
804
+ /** Write the range's diff to `out`: whole under the guard, else a per-file budget; the record says which. */
805
+ export function writeDiffArtifact(
806
+ cwd: string,
807
+ out: string,
808
+ artifact: string,
809
+ range: string,
810
+ guard: DiffGuard = DIFF_GUARD,
811
+ keep: Provenance = { rawDir: null },
812
+ ): DiffArtifact {
813
+ const fetchedAt = utcNow();
814
+ const { files, stat } = diffNumstat(cwd, range);
815
+ const full = gitBytes(cwd, ["diff", range, ...excludeSpec()]);
816
+ const diffLines = records(full).length;
817
+ let content: Buffer;
818
+ let partial = false;
819
+ let ceilingHit = false;
820
+ const omitted: string[] = [];
821
+ if (diffLines === 0) {
822
+ content = lineOf(`No changes in ${range} outside ${DIFF_EXCLUDES.join(", ")}.`);
823
+ } else if (diffLines <= guard.fullLines) {
824
+ content = full;
825
+ } else {
826
+ partial = true;
827
+ const ranked = [...files].sort((a, b) => b.lines - a.lines || a.path.localeCompare(b.path));
828
+ const shown = ranked.slice(0, guard.topFiles);
829
+ const stat0 = gitBytes(cwd, ["diff", "--stat", range, ...excludeSpec()]);
830
+ // Header, omitted-files line, a blank, --stat and a blank count toward the total.
831
+ const room0 = guard.totalLines - (4 + records(stat0).length);
832
+ const body: Buffer[] = [];
833
+ let used = 0;
834
+ const add = (b: Buffer) => {
835
+ body.push(b);
836
+ used += records(b).length;
837
+ };
838
+ let stopped = false;
839
+ for (const f of ranked) {
840
+ if (stopped || !shown.includes(f)) {
841
+ omitted.push(f.path);
842
+ continue;
843
+ }
844
+ const room = Math.min(guard.perFileLines, room0 - used);
845
+ if (room <= 0) {
846
+ ceilingHit = true;
847
+ stopped = true;
848
+ omitted.push(f.path);
849
+ add(lineOf(`# total line budget reached; ${f.path} and smaller files not shown`));
850
+ continue;
851
+ }
852
+ const lines = records(gitBytes(cwd, ["diff", range, "--", f.path]));
853
+ const kept = lines.slice(0, room);
854
+ if (kept.length < lines.length && room < guard.perFileLines) ceilingHit = true;
855
+ add(lineOf(`### ${f.path}`));
856
+ add(joinLines(kept));
857
+ if (kept.length < lines.length) {
858
+ omitted.push(f.path);
859
+ add(lineOf(`# ${lines.length - kept.length} more lines of ${f.path} not shown`));
860
+ }
861
+ add(lineOf(""));
862
+ }
863
+ omitted.sort((a, b) => a.localeCompare(b));
864
+ content = Buffer.concat([
865
+ lineOf(
866
+ `# ${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.`,
867
+ ),
868
+ lineOf(`# not shown whole: ${omitted.join(", ")}`),
869
+ lineOf(""),
870
+ stat0,
871
+ lineOf(""),
872
+ ...body,
873
+ ]);
874
+ }
875
+ const raw = partial && keep.rawDir !== null ? keepRaw(out, keep.rawDir, full) : null;
876
+ fs.mkdirSync(path.dirname(out), { recursive: true });
877
+ fs.writeFileSync(out, content);
878
+ const record: ClampRecord = {
879
+ artifact,
880
+ clamped: partial,
881
+ origLines: diffLines,
882
+ keptLines: partial ? records(content).length : diffLines,
883
+ origBytes: full.length,
884
+ keptBytes: content.length,
885
+ lineCapped: 0,
886
+ ceilingHit,
887
+ raw: raw === null ? null : outboxRel(cwd, raw),
888
+ source: `git diff ${range} -- . ${DIFF_EXCLUDES.map((e) => `':(exclude)${e}'`).join(" ")}`,
889
+ fetchedAt,
890
+ };
891
+ return { range, stat, diffLines, partial, omitted, record };
892
+ }
893
+
894
+ // ---------------------------------------------------------------------------
895
+ // Brief — what one group's build agents read
896
+ //
897
+ // The engine writes it so the orchestrator never reads the plan: the plan's
898
+ // why and what, where the group sits, the group's open task blocks verbatim,
899
+ // one-line summaries of the earlier tasks they depend on, the Reuse Inventory
900
+ // rows and Architecture entries for the open tasks' files, and the deviations
901
+ // note when there is one.
902
+ // ---------------------------------------------------------------------------
903
+
904
+ /** A brief whose work section is over this many bytes warns: the group may not fit one fresh context. */
905
+ export const BRIEF_WORK_WARN_BYTES = 8 * 1024;
906
+
907
+ /** The plan sections a brief carries as its why and what, by heading text. */
908
+ const BRIEF_SECTIONS = ["Context & Goals", "Narrative", "Success Criteria", "Out of Scope"];
909
+
910
+ /** The plan-execute logs whose `DONE — TASK N` lines mark a task done. */
911
+ const EXECUTE_LOG = /^build-plan-execute-.+-log\.md$/;
912
+
913
+ /** A heading's text without leading emoji and marks. */
914
+ const headingText = (text: string) => text.replace(/^[^A-Za-z0-9]+/, "").trim();
915
+
916
+ /**
917
+ * The body of the first heading named `name`, up to the next heading of the
918
+ * same or a higher level. Lines inside code fences are never headings.
919
+ */
920
+ function planSection(lines: string[], name: string): string | undefined {
921
+ let start = -1;
922
+ let level = 0;
923
+ let fence = false;
924
+ for (let i = 0; i < lines.length; i++) {
925
+ const line = lines[i]!;
926
+ if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
927
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
928
+ if (m === null) continue;
929
+ if (start >= 0 && m[1]!.length <= level) return lines.slice(start, i).join("\n").trim();
930
+ if (start < 0 && headingText(m[2]!) === name) {
931
+ start = i + 1;
932
+ level = m[1]!.length;
933
+ }
934
+ }
935
+ return start < 0 ? undefined : lines.slice(start).join("\n").trim();
936
+ }
937
+
938
+ /** Every task number a plan-execute log in `dir` records `DONE`. */
939
+ function loggedDone(dir: string): Set<number> {
940
+ const done = new Set<number>();
941
+ if (!fs.existsSync(dir)) return done;
942
+ for (const f of fs.readdirSync(dir).filter((f) => EXECUTE_LOG.test(f)))
943
+ for (const n of doneTasks(fs.readFileSync(path.join(dir, f), "utf-8"))) done.add(n);
944
+ return done;
945
+ }
946
+
947
+ /** The plan sections whose entries a brief copies for the group's files. */
948
+ const INVENTORY_SECTION = "Reuse Inventory";
949
+ const ARCHITECTURE_SECTION = "Architecture & Component Changes";
950
+
951
+ /** Backticked repo-relative paths in `text`, normalised. */
952
+ const backticked = (text: string) =>
953
+ [...text.matchAll(/`([^`]+)`/g)].map((m) => path.posix.normalize(m[1]!));
954
+
955
+ /**
956
+ * The Reuse Inventory table's header and separator lines (`reuseInventory`), and its rows
957
+ * whose `File` cell names a file in `files`. No table or no `File` column → no rows.
958
+ */
959
+ function inventoryRows(lines: string[], files: Set<string>): { head: string[]; rows: string[] } {
960
+ const table = reuseInventory(lines.join("\n"));
961
+ if (table === null) return { head: [], rows: [] };
962
+ const rows = table.rows.filter((r) => r.files.some((f) => files.has(f))).map((r) => r.line);
963
+ return { head: table.head, rows };
964
+ }
965
+
966
+ /**
967
+ * The Architecture & Component Changes entries whose heading names a file in `files`:
968
+ * the heading through the line before the next heading of the same or a higher level.
969
+ * Lines inside code fences are never headings.
970
+ */
971
+ function architectureEntries(lines: string[], files: Set<string>): string[] {
972
+ const body = (planSection(lines, ARCHITECTURE_SECTION) ?? "").split("\n");
973
+ const heads: Array<{ i: number; level: number; text: string }> = [];
974
+ let fence = false;
975
+ body.forEach((line, i) => {
976
+ if (/^\s*(`{3,}|~{3,})/.test(line)) fence = !fence;
977
+ const m = fence ? null : /^(#{1,6})\s+(.*)$/.exec(line);
978
+ if (m !== null) heads.push({ i, level: m[1]!.length, text: m[2]! });
979
+ });
980
+ return heads.flatMap((h, k) => {
981
+ if (!backticked(h.text).some((f) => files.has(f))) return [];
982
+ const end = heads.slice(k + 1).find((n) => n.level <= h.level)?.i ?? body.length;
983
+ return [body.slice(h.i, end).join("\n").trim()];
984
+ });
985
+ }
986
+
987
+ /** The next free `build-brief-{group}-{n}.md` in `dir`. */
988
+ function nextBriefPath(dir: string, group: number): string {
989
+ const re = new RegExp(`^build-brief-${group}-([0-9]+)\\.md$`);
990
+ const taken = fs.existsSync(dir)
991
+ ? fs.readdirSync(dir).map((f) => Number(re.exec(f)?.[1] ?? 0))
992
+ : [];
993
+ return path.join(dir, `build-brief-${group}-${Math.max(0, ...taken) + 1}.md`);
994
+ }
995
+
996
+ export interface BriefInput {
997
+ plan: string;
998
+ /** The plan's path as given, named where left-out entries can be read. */
999
+ planFile: string;
1000
+ group: PlanGroup;
1001
+ groups: PlanGroup[];
1002
+ isDone: (t: PlanTaskBlock) => boolean;
1003
+ reds: Array<Record<string, unknown>>;
1004
+ note?: string;
1005
+ }
1006
+
1007
+ /** The brief's text and its work section's size in bytes. */
1008
+ export function briefText(o: BriefInput): { text: string; workBytes: number } {
1009
+ const lines = o.plan.split("\n");
1010
+ const title = lines.find((l) => /^#\s/.test(l))?.replace(/^#\s+/, "") ?? "Plan";
1011
+ const out = [`# Brief: group ${o.group.group} — ${o.group.title}`, "", `Plan: ${title}`, ""];
1012
+
1013
+ out.push("## Why and what", "");
1014
+ for (const name of BRIEF_SECTIONS) {
1015
+ const body = planSection(lines, name);
1016
+ if (body !== undefined && body !== "") out.push(`### ${name}`, "", body, "");
1017
+ }
1018
+
1019
+ out.push("## Where it fits", "");
1020
+ const nextGroup = o.groups.find(
1021
+ (g) => g.group > o.group.group && g.tasks.some((t) => !o.isDone(t)),
1022
+ );
1023
+ for (const g of o.groups) {
1024
+ const state = g.tasks.every(o.isDone)
1025
+ ? "done"
1026
+ : g === o.group
1027
+ ? "this group"
1028
+ : g === nextGroup
1029
+ ? "next"
1030
+ : g.group > o.group.group
1031
+ ? "later"
1032
+ : "open";
1033
+ out.push(`- Group ${g.group}: ${g.title} — ${state}`);
1034
+ for (const t of g.tasks)
1035
+ out.push(` - TASK ${t.task}: ${t.title} — ${o.isDone(t) ? "done" : "open"}`);
1036
+ }
1037
+ out.push("");
1038
+
1039
+ const open = o.group.tasks.filter((t) => !o.isDone(t));
1040
+ const work = ["## The work", ""];
1041
+ for (const t of open) work.push(t.text.trim(), "");
1042
+ const openNums = new Set(open.map((t) => t.task));
1043
+ const reds = o.reds.filter((r) => openNums.has(Number(r.task)));
1044
+ if (reds.length > 0) {
1045
+ work.push("### Reds already recorded", "");
1046
+ for (const r of reds)
1047
+ work.push(
1048
+ `- 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`,
1049
+ );
1050
+ work.push("");
1051
+ }
1052
+ const deps = [...new Set(open.flatMap((t) => t.dependsOn))]
1053
+ .filter((n) => !o.group.tasks.some((t) => t.task === n))
1054
+ .sort((a, b) => a - b)
1055
+ .map((n) => o.groups.flatMap((g) => g.tasks).find((t) => t.task === n))
1056
+ .filter((t): t is PlanTaskBlock => t !== undefined);
1057
+ if (deps.length > 0) {
1058
+ work.push("### Earlier tasks this group depends on", "");
1059
+ for (const t of deps) {
1060
+ const files = [...new Set([...t.create, ...t.update, ...t.delete].map((r) => r.file))];
1061
+ const where = files.length > 0 ? ` — ${files.map((f) => `\`${f}\``).join(", ")}` : "";
1062
+ work.push(
1063
+ `- TASK ${t.task} (group ${t.group}, ${o.isDone(t) ? "done" : "open"}): ${t.title}${where}`,
1064
+ );
1065
+ }
1066
+ work.push("");
1067
+ }
1068
+ work.push(...planEntries(lines, open, work, o.planFile));
1069
+ out.push(...work);
1070
+
1071
+ if (o.note !== undefined) out.push("## Deviations", "", o.note.trim(), "");
1072
+ return {
1073
+ text: out.join("\n"),
1074
+ workBytes: Buffer.byteLength(work.join("\n")),
1075
+ };
1076
+ }
1077
+
1078
+ /**
1079
+ * The Reuse Inventory rows, then the Architecture entries, for the files on the open
1080
+ * tasks' CREATE / UPDATE / DELETE lines, each in plan order while the work section stays
1081
+ * within BRIEF_WORK_WARN_BYTES; the rest are counted in a closing line naming where to
1082
+ * read them.
1083
+ */
1084
+ function planEntries(
1085
+ lines: string[],
1086
+ open: PlanTaskBlock[],
1087
+ work: string[],
1088
+ planFile: string,
1089
+ ): string[] {
1090
+ const files = new Set(
1091
+ open.flatMap((t) =>
1092
+ [...t.create, ...t.update, ...t.delete].map((r) => path.posix.normalize(r.file)),
1093
+ ),
1094
+ );
1095
+ const inventory = inventoryRows(lines, files);
1096
+ const arch = architectureEntries(lines, files);
1097
+ const keptRows: string[] = [];
1098
+ const keptArch: string[] = [];
1099
+ const render = (rowsLeft: number, archLeft: number) => {
1100
+ const part: string[] = [];
1101
+ if (keptRows.length > 0)
1102
+ part.push("### Reuse Inventory rows", "", ...inventory.head, ...keptRows, "");
1103
+ if (keptArch.length > 0)
1104
+ part.push("### Architecture entries", "", ...keptArch.flatMap((e) => [e, ""]));
1105
+ if (rowsLeft + archLeft > 0)
1106
+ part.push(
1107
+ `Reuse Inventory rows left out: ${rowsLeft}; Architecture entries left out: ${archLeft} — read them in ${planFile} § ${INVENTORY_SECTION} and § ${ARCHITECTURE_SECTION}.`,
1108
+ "",
1109
+ );
1110
+ return part;
1111
+ };
1112
+ const fits = (rowsLeft: number, archLeft: number) =>
1113
+ Buffer.byteLength([...work, ...render(rowsLeft, archLeft)].join("\n")) <= BRIEF_WORK_WARN_BYTES;
1114
+ // The counts passed to `fits` are those not yet kept, an upper bound on the final ones.
1115
+ let rowsLeft = inventory.rows.length;
1116
+ let archLeft = arch.length;
1117
+ for (const row of inventory.rows) {
1118
+ keptRows.push(row);
1119
+ if (fits(rowsLeft - 1, archLeft)) rowsLeft--;
1120
+ else keptRows.pop();
1121
+ }
1122
+ for (const entry of arch) {
1123
+ keptArch.push(entry);
1124
+ if (fits(rowsLeft, archLeft - 1)) archLeft--;
1125
+ else keptArch.pop();
1126
+ }
1127
+ return render(rowsLeft, archLeft);
1128
+ }
1129
+
596
1130
  // ---------------------------------------------------------------------------
597
1131
  // Command
598
1132
  // ---------------------------------------------------------------------------
599
1133
 
1134
+ const RUN_BLOCK_FLAGS: FlagSpec[] = [
1135
+ { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1136
+ {
1137
+ name: "script",
1138
+ type: "string",
1139
+ required: true,
1140
+ help: "file holding the block body as customised for this failure (run with bash)",
1141
+ },
1142
+ FID_FLAG,
1143
+ MONTH_FLAG,
1144
+ ...ATTEMPT_FLAGS,
1145
+ ];
1146
+
1147
+ const RUN_BLOCK_OUTPUT: Record<string, string> = {
1148
+ outcome: "checked (data written) | self-skipped (skip line written) | silent (nothing) | not-run",
1149
+ artifact: "the artifact path, or null when nothing was written",
1150
+ skip: "the block's [context-fetch:<name>] stderr line, or null",
1151
+ clamp: "the payload's clamp record, or null",
1152
+ reason: "why the block was not run, or null",
1153
+ };
1154
+
600
1155
  export const contextCommand: CommandSpec = {
601
1156
  noun: "context",
602
1157
  summary:
603
- "Clamp context artifacts; scan ledgers; list, run and record consumer context-fetch blocks.",
1158
+ "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
1159
  verbs: {
605
1160
  clamp: {
606
1161
  summary: "Clamp an artifact to a size profile in place (a backstop, not a routine cap).",
607
1162
  flags: [
608
1163
  { name: "artifact", type: "string", required: true, help: "file to clamp" },
609
1164
  { name: "profile", type: "string", required: true, help: "ledger | debug-evidence" },
1165
+ {
1166
+ name: "source",
1167
+ type: "string",
1168
+ help: "the exact command and inputs that produced the artifact (recorded with the time)",
1169
+ },
610
1170
  ...LOG_FLAGS,
611
1171
  ],
612
1172
  output: RECORD_OUTPUT,
613
- exitCodes: { [EXIT_ARTIFACT]: "artifact missing, unreadable, or could not be replaced" },
1173
+ exitCodes: {
1174
+ [EXIT_ARTIFACT]:
1175
+ "artifact missing, unreadable, or could not be replaced; or its original could not be kept",
1176
+ },
614
1177
  run: (ctx) => {
615
1178
  const artifact = String(ctx.flags.artifact);
1179
+ const keep: Provenance = {
1180
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1181
+ source: str(ctx.flags.source),
1182
+ };
616
1183
  const record = clampFile(
617
1184
  path.resolve(ctx.cwd, artifact),
618
1185
  String(ctx.flags.profile),
619
1186
  artifact,
1187
+ keep,
620
1188
  );
1189
+ warnNoRaw(ctx, record, keep);
621
1190
  const log = logPath(ctx);
622
1191
  if (log !== undefined) appendRecord(log, record);
623
1192
  if (record.clamped)
@@ -672,6 +1241,7 @@ export const contextCommand: CommandSpec = {
672
1241
  kept: "lines written (at most 40)",
673
1242
  clamp: "the clamp record",
674
1243
  },
1244
+ textOmit: ["clamp"],
675
1245
  exitCodes: { [EXIT_ARTIFACT]: "artifact could not be written or replaced" },
676
1246
  run: (ctx) => {
677
1247
  const log = logPath(ctx);
@@ -683,18 +1253,216 @@ export const contextCommand: CommandSpec = {
683
1253
  }
684
1254
  const sourceFile = path.resolve(ctx.cwd, String(ctx.flags.source));
685
1255
  const source = fs.existsSync(sourceFile) ? fs.readFileSync(sourceFile, "utf-8") : undefined;
686
- const scan = ledgerScan(source, String(ctx.flags.terms));
1256
+ const terms = String(ctx.flags.terms);
1257
+ const scan = ledgerScan(source, terms);
687
1258
  const artifact = String(ctx.flags.artifact);
688
1259
  const out = path.resolve(ctx.cwd, artifact);
689
1260
  fs.mkdirSync(path.dirname(out), { recursive: true });
690
1261
  fs.writeFileSync(out, scan.content);
691
- const clamp = clampFile(out, "ledger", artifact);
1262
+ const keep: Provenance = {
1263
+ rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)),
1264
+ source: `bkit context ledger-scan --source=${String(ctx.flags.source)} --terms="${terms}"`,
1265
+ };
1266
+ const clamp = clampFile(out, "ledger", artifact, keep);
1267
+ warnNoRaw(ctx, clamp, keep);
692
1268
  if (log !== undefined) appendRecord(log, clamp);
693
1269
  ctx.log(`${artifact}: ${scan.total} matching line(s), ${scan.kept} kept`);
694
1270
  ctx.emit({ total: scan.total, kept: scan.kept, clamp });
695
1271
  return EXIT.OK;
696
1272
  },
697
1273
  },
1274
+ diff: {
1275
+ summary:
1276
+ "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.",
1277
+ flags: [
1278
+ { name: "artifact", type: "string", required: true, help: "file to write" },
1279
+ {
1280
+ name: "base",
1281
+ type: "string",
1282
+ help: `merge base or a group's start commit (default ${DIFF_BASE})`,
1283
+ },
1284
+ ...LOG_FLAGS,
1285
+ {
1286
+ name: "reset-log",
1287
+ type: "boolean",
1288
+ help: "empty the clamp log first (the step's first writer)",
1289
+ },
1290
+ ],
1291
+ output: {
1292
+ artifact: "the artifact path as given",
1293
+ base: "the base used",
1294
+ range: "the range diffed ({base}...HEAD)",
1295
+ filesChanged: "files in the diff (--numstat, same excludes)",
1296
+ linesAdded: "lines added",
1297
+ linesDeleted: "lines deleted",
1298
+ linesChanged: "linesAdded + linesDeleted",
1299
+ diffLines: "lines in the whole diff",
1300
+ 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`,
1301
+ omitted:
1302
+ "files whose diff is not in the artifact whole (not shown, or cut); [] unless partial — the artifact's second line lists them too",
1303
+ clamp:
1304
+ "the clamp record (clamped = partial; raw = the whole diff in the outbox when partial)",
1305
+ },
1306
+ textOmit: ["clamp"],
1307
+ exitCodes: {
1308
+ [EXIT_BASE]: "--base does not name a commit",
1309
+ [EXIT_ARTIFACT]: "the artifact could not be written",
1310
+ },
1311
+ run: (ctx) => {
1312
+ const base = str(ctx.flags.base) ?? DIFF_BASE;
1313
+ if (git(ctx.cwd, ["rev-parse", "-q", "--verify", `${base}^{commit}`]) === null) {
1314
+ throw new CommandError(
1315
+ EXIT_BASE,
1316
+ `--base ${base} does not name a commit (fetch origin, or pass the group's start sha)`,
1317
+ );
1318
+ }
1319
+ const artifact = String(ctx.flags.artifact);
1320
+ const log = logPath(ctx);
1321
+ if (ctx.flags.resetLog === true) {
1322
+ if (log === undefined)
1323
+ throw new CommandError(EXIT.USAGE, "--reset-log needs --log, or --fid and --step");
1324
+ fs.mkdirSync(path.dirname(log), { recursive: true });
1325
+ fs.writeFileSync(log, "");
1326
+ }
1327
+ const written = tryWriteDiffArtifact(
1328
+ ctx.cwd,
1329
+ path.resolve(ctx.cwd, artifact),
1330
+ artifact,
1331
+ `${base}...HEAD`,
1332
+ DIFF_GUARD,
1333
+ { rawDir: rawDirFor(ctx.cwd, str(ctx.flags.fid)) },
1334
+ );
1335
+ if (!written.ok) throw new CommandError(EXIT_ARTIFACT, `${artifact}: ${written.error}`);
1336
+ const result = written.result;
1337
+ if (log !== undefined) appendRecord(log, result.record);
1338
+ if (result.partial) {
1339
+ ctx.log(
1340
+ `${artifact}: ${result.diffLines} diff lines, over the ${DIFF_GUARD.fullLines}-line guard — per-file budget written (${PARTIAL_MARK})`,
1341
+ );
1342
+ }
1343
+ ctx.emit({
1344
+ artifact,
1345
+ base,
1346
+ range: result.range,
1347
+ ...result.stat,
1348
+ diffLines: result.diffLines,
1349
+ partial: result.partial,
1350
+ omitted: result.omitted,
1351
+ clamp: result.record,
1352
+ });
1353
+ return EXIT.OK;
1354
+ },
1355
+ },
1356
+ brief: {
1357
+ summary:
1358
+ "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.",
1359
+ flags: [
1360
+ { name: "plan", type: "string", required: true, help: "the plan file" },
1361
+ { name: "group", type: "string", help: "the group to brief" },
1362
+ {
1363
+ name: "next",
1364
+ type: "boolean",
1365
+ help: "brief the first group with an open task (none open → nothing written, group null)",
1366
+ },
1367
+ {
1368
+ name: "dir",
1369
+ type: "string",
1370
+ required: true,
1371
+ help: "the run's logs folder: the brief is written there, and its build-plan-execute-*-log.md DONE lines mark tasks done",
1372
+ },
1373
+ {
1374
+ name: "file",
1375
+ type: "string",
1376
+ help: "status.jsonl, to name the reds already recorded for open tasks",
1377
+ },
1378
+ {
1379
+ name: "note-file",
1380
+ type: "string",
1381
+ help: "text for the Deviations section (left out when not given)",
1382
+ },
1383
+ ],
1384
+ output: {
1385
+ artifact: "the brief's path (null when --next finds no open group)",
1386
+ bytes: "the brief's size in bytes",
1387
+ group: "the group briefed (null when --next finds no open group)",
1388
+ tasks: "the open task numbers the brief carries",
1389
+ workBytes: "the work section's size in bytes (0 when --next finds no open group)",
1390
+ 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`,
1391
+ },
1392
+ exitCodes: {
1393
+ [EXIT_ARTIFACT]: "the plan or note file is missing, or the plan's blocks do not parse",
1394
+ [EXIT_NO_STATUS]: "--file names a missing or malformed status.jsonl",
1395
+ },
1396
+ run: (ctx) => {
1397
+ const groupFlag = positiveInt(ctx.flags.group, "group");
1398
+ if ((groupFlag === undefined) === (ctx.flags.next !== true))
1399
+ throw new CommandError(EXIT.USAGE, "give exactly one of --group=N and --next");
1400
+ const planFile = path.resolve(ctx.cwd, String(ctx.flags.plan));
1401
+ if (!fs.existsSync(planFile))
1402
+ throw new CommandError(EXIT_ARTIFACT, `${String(ctx.flags.plan)} does not exist`);
1403
+ const plan = fs.readFileSync(planFile, "utf-8");
1404
+ const blocks = parsePlanBlocks(plan);
1405
+ if (blocks.errors.length > 0) {
1406
+ const e = blocks.errors[0]!;
1407
+ throw new CommandError(
1408
+ EXIT_ARTIFACT,
1409
+ `${String(ctx.flags.plan)}:${e.line}: ${e.message} — run \`bkit tests plan-check\``,
1410
+ );
1411
+ }
1412
+ const dir = path.resolve(ctx.cwd, String(ctx.flags.dir));
1413
+ const done = loggedDone(dir);
1414
+ const isDone = (t: PlanTaskBlock) => t.done || done.has(t.task);
1415
+ const group =
1416
+ groupFlag === undefined
1417
+ ? blocks.groups.find((g) => g.tasks.some((t) => !isDone(t)))
1418
+ : blocks.groups.find((g) => g.group === groupFlag);
1419
+ if (group === undefined && groupFlag !== undefined)
1420
+ throw new CommandError(EXIT.USAGE, `the plan has no group ${groupFlag}`);
1421
+ if (group === undefined) {
1422
+ ctx.emit({
1423
+ artifact: null,
1424
+ bytes: 0,
1425
+ group: null,
1426
+ tasks: [],
1427
+ workBytes: 0,
1428
+ workCap: BRIEF_WORK_WARN_BYTES,
1429
+ });
1430
+ return EXIT.OK;
1431
+ }
1432
+ const noteFlag = str(ctx.flags.noteFile);
1433
+ const noteFile = noteFlag === undefined ? undefined : path.resolve(ctx.cwd, noteFlag);
1434
+ if (noteFile !== undefined && !fs.existsSync(noteFile))
1435
+ throw new CommandError(EXIT_ARTIFACT, `${noteFlag} does not exist`);
1436
+ const status = str(ctx.flags.file);
1437
+ const { text, workBytes } = briefText({
1438
+ plan,
1439
+ planFile: String(ctx.flags.plan),
1440
+ group,
1441
+ groups: blocks.groups,
1442
+ isDone,
1443
+ reds: status === undefined ? [] : redRows(path.resolve(ctx.cwd, status), "build"),
1444
+ note: noteFile === undefined ? undefined : fs.readFileSync(noteFile, "utf-8"),
1445
+ });
1446
+ const out = nextBriefPath(dir, group.group);
1447
+ fs.mkdirSync(dir, { recursive: true });
1448
+ fs.writeFileSync(out, text);
1449
+ if (workBytes > BRIEF_WORK_WARN_BYTES) {
1450
+ ctx.log(
1451
+ `${out}: the work section is ${humanBytes(workBytes)}, over ${humanBytes(BRIEF_WORK_WARN_BYTES)} — the group may not fit one fresh context`,
1452
+ );
1453
+ }
1454
+ const artifact = path.isAbsolute(String(ctx.flags.dir)) ? out : path.relative(ctx.cwd, out);
1455
+ ctx.emit({
1456
+ artifact,
1457
+ bytes: Buffer.byteLength(text),
1458
+ group: group.group,
1459
+ tasks: group.tasks.filter((t) => !isDone(t)).map((t) => t.task),
1460
+ workBytes,
1461
+ workCap: BRIEF_WORK_WARN_BYTES,
1462
+ });
1463
+ return EXIT.OK;
1464
+ },
1465
+ },
698
1466
  "list-blocks": {
699
1467
  summary: "Enumerate the consumer's context-fetch blocks and narrate coverage per context.",
700
1468
  flags: [],
@@ -739,31 +1507,41 @@ export const contextCommand: CommandSpec = {
739
1507
  "run-block": {
740
1508
  summary:
741
1509
  "Run one customised block; write its output fenced (clamped first), its skip line, or nothing.",
1510
+ flags: RUN_BLOCK_FLAGS,
1511
+ output: RUN_BLOCK_OUTPUT,
1512
+ textOmit: ["clamp"],
1513
+ exitCodes: {
1514
+ [EXIT_ARTIFACT]: "the payload could not be clamped or written",
1515
+ [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
1516
+ },
1517
+ run: (ctx) => runBlock(ctx),
1518
+ },
1519
+ fetch: {
1520
+ summary:
1521
+ "run-block, with a JSON array of flat objects written as a markdown table; the raw output stays in the outbox.",
742
1522
  flags: [
743
- { name: "idx", type: "string", required: true, help: "block ordinal from list-blocks" },
1523
+ ...RUN_BLOCK_FLAGS,
744
1524
  {
745
- name: "script",
1525
+ name: "render",
746
1526
  type: "string",
747
- required: true,
748
- help: "file holding the block body as customised for this failure (run with bash)",
1527
+ 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
1528
  },
750
- FID_FLAG,
751
- MONTH_FLAG,
752
- ...ATTEMPT_FLAGS,
753
1529
  ],
754
1530
  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",
1531
+ ...RUN_BLOCK_OUTPUT,
1532
+ render: "table | raw: how the output was written; null when nothing was written",
761
1533
  },
1534
+ textOmit: ["clamp"],
762
1535
  exitCodes: {
763
1536
  [EXIT_ARTIFACT]: "the payload could not be clamped or written",
764
1537
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
765
1538
  },
766
- run: (ctx) => runBlock(ctx),
1539
+ run: (ctx) => {
1540
+ const render = str(ctx.flags.render) ?? "table";
1541
+ if (!(RENDERS as readonly string[]).includes(render))
1542
+ throw new CommandError(EXIT.USAGE, `--render must be ${RENDERS.join("|")}`);
1543
+ return runBlock(ctx, render as Render);
1544
+ },
767
1545
  },
768
1546
  finalise: {
769
1547
  summary:
@@ -796,6 +1574,7 @@ export const contextCommand: CommandSpec = {
796
1574
  commit: "--record: the new commit's sha, else null",
797
1575
  comment:
798
1576
  "the step comment (with --number): verdict, contexts, artifact links, a NOT CONFIGURED line per context with no block; else null",
1577
+ commentFile: COMMENT_FILE_OUTPUT,
799
1578
  },
800
1579
  exitCodes: {
801
1580
  [EXIT_NO_STATUS]: "--file: status.jsonl missing, unreadable, or not valid NDJSON",
@@ -878,6 +1657,7 @@ export const contextCommand: CommandSpec = {
878
1657
  row: record ? written.row : null,
879
1658
  commit: written.commit,
880
1659
  comment,
1660
+ commentFile: commentFileOf(ctx.cwd, comment),
881
1661
  });
882
1662
  return written.code;
883
1663
  },
@@ -885,7 +1665,22 @@ export const contextCommand: CommandSpec = {
885
1665
  },
886
1666
  };
887
1667
 
888
- function runBlock(ctx: RunContext): number {
1668
+ /** A block's output as a checked markdown table, or why it stays as printed. */
1669
+ function tableOf(stdout: Buffer): { text: string } | { reason: string } {
1670
+ const parsed = parseJson(stdout.toString("utf-8"));
1671
+ if (!parsed.ok) return { reason: "not JSON" };
1672
+ const table = checkedTable(parsed.value);
1673
+ return table.ok ? { text: table.text } : { reason: table.reason };
1674
+ }
1675
+
1676
+ /**
1677
+ * Run consumer block `--idx` and write what it printed, fenced and clamped. With `render`
1678
+ * (`context fetch`), a JSON array of flat objects is written as a table instead; the
1679
+ * output as printed goes to the outbox first, and the record says which was written.
1680
+ */
1681
+ function runBlock(ctx: RunContext, render?: Render): number {
1682
+ const shape = (out: Record<string, unknown>, written: Render | null) =>
1683
+ render === undefined ? out : { ...out, render: written };
889
1684
  const idx = positiveInt(ctx.flags.idx, "idx")!;
890
1685
  const attempt = debugAttempt(ctx);
891
1686
  const fid = String(ctx.flags.fid);
@@ -895,7 +1690,7 @@ function runBlock(ctx: RunContext): number {
895
1690
  const block = fetchBlocks(consumerSection(readContextMd(ctx) ?? "")).find((b) => b.idx === idx);
896
1691
  const notRun = (reason: string) => {
897
1692
  ctx.log(`context-fetch: ${reason} — NOT RUN`);
898
- ctx.emit({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason });
1693
+ ctx.emit(shape({ outcome: "not-run", artifact: null, skip: null, clamp: null, reason }, null));
899
1694
  return EXIT.OK;
900
1695
  };
901
1696
  if (!block) return notRun(`no block ${idx} after <!-- bkit:end -->`);
@@ -909,6 +1704,7 @@ function runBlock(ctx: RunContext): number {
909
1704
  return notRun(`block ${idx} (context=${block.context} name=${label}) has no fenced body`);
910
1705
 
911
1706
  const repoRoot = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1707
+ const fetchedAt = utcNow();
912
1708
  // The inline block ran inside the step's shell, so these were in scope for it.
913
1709
  const res = spawnSync("bash", [script], {
914
1710
  cwd: ctx.cwd,
@@ -936,12 +1732,38 @@ function runBlock(ctx: RunContext): number {
936
1732
 
937
1733
  if (stdout.some((b) => b !== 0x0a && b !== 0)) {
938
1734
  fs.mkdirSync(path.dirname(out), { recursive: true });
939
- fs.writeFileSync(out, asCaptured(stdout));
940
- const clamp = clampFile(out, "debug-evidence", artifact);
1735
+ const keep: Provenance = {
1736
+ rawDir: rawDirFor(ctx.cwd, fid),
1737
+ source: fs.readFileSync(script, "utf-8"),
1738
+ fetchedAt,
1739
+ };
1740
+ let payload = asCaptured(stdout);
1741
+ let written: Render | null = null;
1742
+ if (render !== undefined) {
1743
+ const table = render === "table" ? tableOf(stdout) : null;
1744
+ if (table !== null && "text" in table) {
1745
+ // The table replaces the printed output: keep that output whole first.
1746
+ if (keep.rawDir !== null) keep.original = keepRaw(out, keep.rawDir, stdout);
1747
+ payload = Buffer.from(`${table.text}\n`);
1748
+ written = "table";
1749
+ } else {
1750
+ if (table !== null) ctx.log(`render: raw (${table.reason})`);
1751
+ written = "raw";
1752
+ }
1753
+ }
1754
+ fs.writeFileSync(out, payload);
1755
+ let clamp = clampFile(out, "debug-evidence", artifact, keep);
1756
+ warnNoRaw(ctx, clamp, keep);
1757
+ if (written !== null) {
1758
+ const raw = clamp.raw ?? (keep.original ? outboxRel(path.dirname(out), keep.original) : null);
1759
+ clamp = { ...clamp, raw, render: written };
1760
+ }
941
1761
  appendRecord(clampLogPath(ctx.cwd, fid, "context-fetch", attempt), clamp);
942
1762
  fs.writeFileSync(out, fenced(fs.readFileSync(out)));
943
1763
  ctx.log(`${shown} CHECKED — data returned`);
944
- ctx.emit({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null });
1764
+ ctx.emit(
1765
+ shape({ outcome: "checked", artifact, skip: skip ?? null, clamp, reason: null }, written),
1766
+ );
945
1767
  return EXIT.OK;
946
1768
  }
947
1769
  if (skip !== undefined) {
@@ -950,12 +1772,14 @@ function runBlock(ctx: RunContext): number {
950
1772
  ctx.log(
951
1773
  `${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
1774
  );
953
- ctx.emit({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null });
1775
+ ctx.emit(shape({ outcome: "self-skipped", artifact, skip, clamp: null, reason: null }, null));
954
1776
  return EXIT.OK;
955
1777
  }
956
1778
  ctx.log(
957
1779
  `${shown} produced neither data nor a skip breadcrumb — NOT CHECKED (unexpected silent exit; treat as unavailable, never as clean)`,
958
1780
  );
959
- ctx.emit({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null });
1781
+ ctx.emit(
1782
+ shape({ outcome: "silent", artifact: null, skip: null, clamp: null, reason: null }, null),
1783
+ );
960
1784
  return EXIT.OK;
961
1785
  }