@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
@@ -13,8 +13,8 @@
13
13
  // (b) `validate` REJECTS unknown `kind` before write. No reject path in status.ts.
14
14
  // (c) ms `ts` via now*1000|floor, NOT ISO `at`.
15
15
  //
16
- // Version provenance: every row records the emitting `bkitVersion`. Readers ingest
17
- // ALL well-formed rows (no version gating) and report row counts per `bkitVersion`
16
+ // Version provenance: every row records the emitting `bkit.version`. Readers ingest
17
+ // ALL well-formed rows (no version gating) and report row counts per `bkit.version`
18
18
  // so an unexpected version surfaces for triage.
19
19
  import { spawnSync } from "node:child_process";
20
20
  import * as fs from "node:fs";
@@ -99,6 +99,16 @@ export function resolveRepoSlug(cwd) {
99
99
  return "";
100
100
  return parseRemoteUrlToSlug(res.stdout);
101
101
  }
102
+ // ---------------------------------------------------------------------------
103
+ // Shared envelope (A2-mandatory fields on EVERY row, every kind)
104
+ // ---------------------------------------------------------------------------
105
+ /**
106
+ * Row format version. Rows written without `schema` are read through {@link normalize}.
107
+ * A schema-2 row differs only in its outcome `plan` block ({@link StoredPlanBlock}).
108
+ */
109
+ export const SCHEMA = 3;
110
+ /** The schema {@link normalize} stamps on a row written without one: the shape it builds. */
111
+ const NORMALIZED_SCHEMA = 2;
102
112
  export const VALID_KINDS = new Set([
103
113
  "compliance",
104
114
  "outcome",
@@ -109,6 +119,8 @@ export const VALID_KINDS = new Set([
109
119
  "knowledge",
110
120
  "decision",
111
121
  "feature",
122
+ "chat",
123
+ "run",
112
124
  ]);
113
125
  export const VALID_SEVERITIES = new Set(["CRITICAL", "HIGH", "MEDIUM", "LOW"]);
114
126
  /**
@@ -134,6 +146,7 @@ export const DEFERRAL_REASONS = new Set([
134
146
  "hard-blocked",
135
147
  "needs-decision",
136
148
  "own-cycle",
149
+ "low-severity",
137
150
  "unjustified",
138
151
  ]);
139
152
  /**
@@ -160,38 +173,686 @@ export const DEFERRAL_WRITERS = new Set([
160
173
  "bkit-design-generate",
161
174
  "bkit-plan-generate",
162
175
  "bkit-plan-update",
163
- "bkit-build-challenge-remediate",
164
176
  "bkit-debug-abort-handover",
165
177
  "bkit-ship-deferred-sweep",
166
178
  "bkit-utility-update-deferrals",
167
179
  ]);
180
+ /** A writer list that admits every name (`.bkit/jsonl.md` § Ledgers & Writers: "any agent"). */
181
+ export const ANY_WRITER = "any";
182
+ /**
183
+ * The ledgers `bkit ledgers append` lands rows in, and the kinds each takes.
184
+ * `feature` rows go through `bkit roadmap feature` (it re-renders the board);
185
+ * `chat` / `run` rows are written by bkit's harvest script, to `harvest/stats.jsonl`.
186
+ */
187
+ export const APPEND_LEDGERS = {
188
+ decisions: { file: "docs/decisions.jsonl", kinds: ["decision"] },
189
+ deferrals: { file: "docs/deferrals.jsonl", kinds: ["deferral"] },
190
+ failures: { file: "docs/failures.jsonl", kinds: ["failure"] },
191
+ knowledge: { file: "docs/knowledge.jsonl", kinds: ["knowledge"] },
192
+ friction: { file: ".bkit/friction.jsonl", kinds: ["friction"] },
193
+ stats: { file: ".bkit/stats.jsonl", kinds: ["compliance", "counter", "outcome"] },
194
+ };
195
+ /** The workflows whose close writes `.bkit/stats.jsonl` rows (`bkit workflows close`, `bkit comply`). */
196
+ const CLOSING_WORKFLOWS = new Set(["design", "plan", "build", "debug", "ship"]);
197
+ /**
198
+ * `.bkit/jsonl.md` § Ledgers & Writers as code, for the kinds in
199
+ * {@link APPEND_LEDGERS}. EXHAUSTIVE: a name absent from a set does not write the
200
+ * kind. `telemetry.test.ts` holds this to the doc table.
201
+ */
202
+ export const KIND_WRITERS = {
203
+ decision: {
204
+ subagents: new Set([
205
+ "bkit-debug-failure-remediate",
206
+ "bkit-plan-generate",
207
+ "bkit-plan-update",
208
+ "bkit-utility-update-decisions",
209
+ ]),
210
+ // Build: Decision Pause accept; plan: an open question answered after close; ship: an
211
+ // assumed accept the owner confirms (`bkit decisions apply --by=owner`). All ONLY after
212
+ // explicit human approval.
213
+ orchestrators: new Set(["build", "plan", "ship"]),
214
+ },
215
+ // Build: `bkit challenge merge` writes each LOW challenge finding (`low-severity`). Ship:
216
+ // `bkit decisions pending --defer` writes each assumed accept nobody confirmed (`needs-decision`).
217
+ deferral: { subagents: DEFERRAL_WRITERS, orchestrators: new Set(["build", "ship"]) },
218
+ failure: { subagents: ANY_WRITER, orchestrators: ANY_WRITER },
219
+ knowledge: {
220
+ subagents: new Set([
221
+ "bkit-build-plan-execute",
222
+ "bkit-build-plan-gaps-remediate",
223
+ "bkit-debug-failure-remediate",
224
+ "bkit-utility-update-knowledge",
225
+ ]),
226
+ orchestrators: new Set(),
227
+ },
228
+ friction: {
229
+ subagents: new Set(),
230
+ orchestrators: new Set(["design", "plan", "build", "debug", "ship"]),
231
+ },
232
+ compliance: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
233
+ counter: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
234
+ outcome: { subagents: new Set(), orchestrators: CLOSING_WORKFLOWS },
235
+ };
236
+ const writerList = (w) => w === ANY_WRITER ? "any" : w.size === 0 ? "none" : [...w].join(", ");
237
+ /** A row's `by` block, or an empty one when it has none. */
238
+ const byOf = (row) => row["by"] !== null && typeof row["by"] === "object" ? row["by"] : {};
239
+ /**
240
+ * Why `row` may not be written by its author, or undefined when it may. The author
241
+ * is `by.subagent` when set (with its `by.model`), else the orchestrator in
242
+ * `by.workflow` (`.bkit/jsonl.md` § Who Wrote It).
243
+ */
244
+ export function writerProblem(row) {
245
+ const kind = row["kind"];
246
+ const writers = KIND_WRITERS[kind];
247
+ if (writers === undefined)
248
+ return `${String(kind)} rows have no append writers`;
249
+ const by = byOf(row);
250
+ const subagent = by["subagent"];
251
+ if (subagent !== undefined) {
252
+ if (typeof subagent !== "string" || subagent === "") {
253
+ return "by.subagent must be a non-empty string";
254
+ }
255
+ if (typeof by["model"] !== "string" || by["model"] === "") {
256
+ return `subagent ${subagent} row missing by.model (its prompt's frontmatter model:)`;
257
+ }
258
+ if (writers.subagents === ANY_WRITER || writers.subagents.has(subagent))
259
+ return undefined;
260
+ return `subagent ${subagent} does not write ${kind} rows (subagents: ${writerList(writers.subagents)})`;
261
+ }
262
+ if (by["model"] !== undefined)
263
+ return "by.model is set only on subagent rows";
264
+ if (writers.orchestrators === ANY_WRITER)
265
+ return undefined;
266
+ const workflow = by["workflow"];
267
+ if (typeof workflow === "string" && writers.orchestrators.has(workflow))
268
+ return undefined;
269
+ return `the ${typeof workflow === "string" ? workflow : "(no workflow)"} orchestrator does not write ${kind} rows (orchestrators: ${writerList(writers.orchestrators)})`;
270
+ }
271
+ /**
272
+ * A `ts` minted now: `Date.now()`, or `after + 1` when the clock has not passed
273
+ * `after`, moved 1 ms off a whole second. The live-ledger gate fails whole-second
274
+ * values as hand-typed (`audits/repo/ledger-integrity.test.ts`), and a real mint
275
+ * must never trip it.
276
+ */
277
+ export function mintTs(after) {
278
+ let ts = Date.now();
279
+ if (after !== undefined && ts <= after)
280
+ ts = after + 1;
281
+ return ts % 1000 === 0 ? ts + 1 : ts;
282
+ }
283
+ /**
284
+ * The context one subagent may fill before it hands over (the plan template's "about 160k
285
+ * tokens" per build group). Rows store peaks only; readers judge them against this.
286
+ */
287
+ export const AGENT_CONTEXT_CAP = 160_000;
288
+ export const OUTCOME_ENDINGS = new Set(["done", "close-failed"]);
289
+ export const RUN_ENDINGS = new Set([
290
+ "done",
291
+ "close-failed",
292
+ "failed",
293
+ "decision-pause",
294
+ "stopped",
295
+ ]);
168
296
  // ---------------------------------------------------------------------------
169
297
  // Identity — per-kind composite tuple for dedup (NOT bare ts)
170
298
  // Mirrors ledgers/status.ts's tuple dedupe approach.
171
299
  // ---------------------------------------------------------------------------
172
300
  export function identity(event) {
301
+ const workflow = event.by?.workflow;
173
302
  switch (event.kind) {
174
303
  case "compliance":
175
- return `compliance ${event.repo} ${event.workflow} ${event.parentSha} ${event.rule}`;
304
+ return `compliance ${event.repo} ${workflow} ${event.run?.parentSha} ${event.rule?.id}`;
176
305
  case "outcome": {
177
- // One run row per workflow run: keyed by (repo, workflow, parentSha).
178
- // A ship row with no parentSha falls back to prNumber (then ts), so it stays
306
+ // One run row per workflow run: keyed by (repo, workflow, run.parentSha).
307
+ // A ship row with no parentSha falls back to run.pr (then ts), so it stays
179
308
  // uniquely keyed per PR.
180
- const anchor = event.parentSha ?? (event.prNumber !== undefined ? `pr${event.prNumber}` : `ts${event.ts}`);
181
- return `outcome ${event.repo} ${event.workflow} ${anchor}`;
309
+ const anchor = event.run?.parentSha ??
310
+ (event.run?.pr !== undefined ? `pr${event.run.pr}` : `ts${event.ts}`);
311
+ return `outcome ${event.repo} ${workflow} ${anchor}`;
182
312
  }
183
313
  case "counter":
184
- return `counter ${event.repo} ${event.workflow} ${event.parentSha} ${event.counterName}`;
314
+ return `counter ${event.repo} ${workflow} ${event.run?.parentSha} ${event.counter?.name}`;
185
315
  case "friction":
186
316
  case "deferral":
187
317
  case "failure":
188
318
  case "knowledge":
189
319
  case "decision":
190
320
  case "feature":
191
- // instinct-loop kinds (+ feature): identity = kind + key
321
+ case "chat":
322
+ case "run":
323
+ // keyed kinds: identity = kind + key
192
324
  return `${event.kind} ${event.repo} ${event.key ?? event.ts}`;
193
325
  }
194
326
  }
327
+ const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
328
+ /** `o` without its undefined fields, so an absent value stays absent. */
329
+ const defined = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
330
+ const tenthOf = (n) => Math.round(n * 10) / 10;
331
+ /** Fields of a row written without `schema` that the current shape moves or drops, per kind. */
332
+ const MOVED = {
333
+ compliance: ["rule", "result", "evidence", "phase"],
334
+ counter: ["counterName", "counterValue", "counterSource", "phase"],
335
+ outcome: [
336
+ "phase",
337
+ "prNumber",
338
+ "linesAdded",
339
+ "linesDeleted",
340
+ "linesChanged",
341
+ "filesChanged",
342
+ "taskCount",
343
+ "durationSeconds",
344
+ "ciTrySuccess",
345
+ "correctiveCommits",
346
+ "reviewIterations",
347
+ "deferrals",
348
+ "failures",
349
+ "frictionAdded",
350
+ "deferralsAdded",
351
+ "failuresAdded",
352
+ "planSource",
353
+ "coverage",
354
+ "redTests",
355
+ ],
356
+ };
357
+ const TOP_MOVED = ["schema", "bkitVersion", "workflow", "step", "subagent", "model", "parentSha"];
358
+ /**
359
+ * A row in a `schema` shape. A row that carries `schema` is returned as it is; a
360
+ * row written without one is stamped `schema: 2` and has its top section (`bkitVersion` -> `bkit.version`,
361
+ * `workflow` / `step` / `subagent` / `model` -> `by.*`) and the stats kinds' run
362
+ * fields moved into their blocks as far as the row holds them. Fields with no
363
+ * place in the schema-2 shape are dropped, and any kind's `parentSha` moves to
364
+ * `run.parentSha`. `bkit install` / `bkit upgrade` rewrite old rows through it
365
+ * (`./migrate.ts`); readers still call it, as a union merge can bring an old line back.
366
+ */
367
+ export function normalize(raw) {
368
+ if (!isObj(raw))
369
+ return {};
370
+ if (raw["schema"] !== undefined)
371
+ return raw;
372
+ const kind = String(raw["kind"]);
373
+ const moved = new Set([...TOP_MOVED, ...(MOVED[kind] ?? [])]);
374
+ const rest = Object.fromEntries(Object.entries(raw).filter(([k]) => !moved.has(k)));
375
+ const { ts, kind: _kind, key, repo, references, ...payload } = rest;
376
+ const out = defined({
377
+ schema: NORMALIZED_SCHEMA,
378
+ ts,
379
+ kind: raw["kind"],
380
+ key,
381
+ repo,
382
+ // "none": the harvest script found no bkit version for the row.
383
+ bkit: {
384
+ version: raw["bkitVersion"] === undefined || raw["bkitVersion"] === "none"
385
+ ? null
386
+ : raw["bkitVersion"],
387
+ },
388
+ // An old row's null or empty `workflow` / `subagent` / `model` meant "none": left out.
389
+ by: Object.fromEntries(["workflow", "step", "subagent", "model"]
390
+ .map((f) => [f, raw[f]])
391
+ .filter(([, v]) => v !== undefined && v !== null && v !== "")),
392
+ references,
393
+ });
394
+ const num = (f) => typeof raw[f] === "number" ? raw[f] : undefined;
395
+ switch (kind) {
396
+ case "compliance":
397
+ out["run"] = { parentSha: raw["parentSha"] };
398
+ out["rule"] = defined({ id: raw["rule"], verdict: raw["result"], evidence: raw["evidence"] });
399
+ break;
400
+ case "counter":
401
+ out["run"] = { parentSha: raw["parentSha"] };
402
+ out["counter"] = {
403
+ name: raw["counterName"],
404
+ value: raw["counterValue"],
405
+ source: raw["counterSource"],
406
+ };
407
+ break;
408
+ case "outcome": {
409
+ out["run"] = defined({ parentSha: raw["parentSha"], pr: raw["prNumber"] });
410
+ const seconds = num("durationSeconds");
411
+ if (seconds !== undefined)
412
+ out["time"] = { totalMinutes: tenthOf(seconds / 60) };
413
+ const added = num("linesAdded");
414
+ const deleted = num("linesDeleted");
415
+ if (added !== undefined && deleted !== undefined) {
416
+ out["lines"] = {
417
+ total: { added, deleted, changed: added + deleted, files: num("filesChanged") ?? 0 },
418
+ };
419
+ }
420
+ out["ledgers"] = {
421
+ deferrals: defined({ repo: num("deferrals"), added: num("deferralsAdded") }),
422
+ failures: defined({ repo: num("failures"), added: num("failuresAdded") }),
423
+ friction: defined({ added: num("frictionAdded") }),
424
+ };
425
+ if (raw["planSource"] === "brief")
426
+ out["plan"] = { source: "brief" };
427
+ if (isObj(raw["coverage"]))
428
+ out["ship"] = { coverage: raw["coverage"] };
429
+ if (num("redTests") !== undefined)
430
+ out["build"] = { redTests: num("redTests") };
431
+ break;
432
+ }
433
+ case "chat":
434
+ return { ...out, ...oldChat(raw) };
435
+ case "run":
436
+ return {
437
+ ...out,
438
+ by: defined({ workflow: raw["workflow"], step: raw["step"] ?? "scan" }),
439
+ ...oldRun(raw),
440
+ };
441
+ }
442
+ const run = out["run"] ?? (raw["parentSha"] !== undefined ? { parentSha: raw["parentSha"] } : undefined);
443
+ return { ...out, ...payload, ...defined({ run }) };
444
+ }
445
+ // The harvest script's own kinds, mapped in full: every schema-1 field has a
446
+ // place in the current shape or is dropped. `scripts/harvest/bkit-harvest.mjs`
447
+ // `normalize` maps them the same way.
448
+ const objOf = (v) => (isObj(v) ? v : {});
449
+ const numOr = (v, or = 0) => typeof v === "number" ? v : or;
450
+ const arrOf = (v) => (Array.isArray(v) ? v : []);
451
+ const TOKENS = ["input", "cacheWrite", "cacheRead", "output", "outputEst", "read"];
452
+ const oldTokens = (t) => Object.fromEntries(TOKENS.map((k) => [k, numOr(objOf(t)[k])]));
453
+ const oldMix = (m) => {
454
+ if (!isObj(m))
455
+ return undefined;
456
+ return {
457
+ read: numOr(m["read"]),
458
+ edit: numOr(m["edit"]),
459
+ grep: numOr(m["grep"]),
460
+ shellRead: numOr(m["sedCat"]),
461
+ shellList: numOr(m["findLs"]),
462
+ tests: numOr(m["tests"]),
463
+ serena: numOr(m["serena"]),
464
+ };
465
+ };
466
+ const sumNums = (xs) => xs.reduce((a, x) => a + (typeof x === "number" ? x : 0), 0);
467
+ /** Shell tools by host: the tool a schema-1 chat row's per-chat shell categories move under. */
468
+ const OLD_SHELL_TOOLS = [
469
+ "Bash",
470
+ "bash",
471
+ "Shell",
472
+ "shell",
473
+ "shell_command",
474
+ "local_shell",
475
+ "exec_command",
476
+ "run_command",
477
+ "run_terminal_cmd",
478
+ ];
479
+ function oldChat(r) {
480
+ const byAgent = {};
481
+ for (const [type, av] of Object.entries(objOf(r["agents"]))) {
482
+ const a = objOf(av);
483
+ const peaks = arrOf(a["ctxPeaks"]).filter((p) => typeof p === "number");
484
+ const n = numOr(a["n"], peaks.length);
485
+ byAgent[type] = defined({
486
+ n,
487
+ errors: numOr(a["errors"]),
488
+ // Per-instance turns were stored only as a sum: known when the type ran once.
489
+ instances: peaks.map((p) => ({
490
+ turns: n === 1 ? numOr(a["turns"], null) : null,
491
+ contextPeak: p,
492
+ })),
493
+ usage: {
494
+ turns: numOr(a["turns"]),
495
+ tokens: oldTokens(a),
496
+ context: { peak: numOr(a["ctxPeakMax"], Math.max(0, ...peaks)) },
497
+ compactions: numOr(a["compactions"]),
498
+ },
499
+ mix: oldMix(a["mix"]),
500
+ });
501
+ }
502
+ const byTool = {};
503
+ for (const [k, tv] of Object.entries(objOf(r["tools"]))) {
504
+ const t = objOf(tv);
505
+ byTool[k] = { calls: numOr(t["calls"]), errors: numOr(t["errors"]) };
506
+ }
507
+ const shellTool = OLD_SHELL_TOOLS.find((k) => byTool[k] !== undefined);
508
+ const bash = objOf(r["bash"]);
509
+ if (shellTool !== undefined && Object.keys(bash).length > 0)
510
+ byTool[shellTool]["byCategory"] = { ...bash };
511
+ const byModel = Object.fromEntries(Object.entries(objOf(r["models"])).map(([k, m]) => [
512
+ k,
513
+ { turns: numOr(objOf(m)["turns"]), tokens: oldTokens(m) },
514
+ ]));
515
+ const m = objOf(r["main"]);
516
+ const tokens = objOf(r["tokens"]);
517
+ const byVerb = objOf(r["bkitCli"]);
518
+ const agents = Object.values(byAgent).map(objOf);
519
+ const tools = Object.values(byTool);
520
+ const start = r["start"];
521
+ const end = r["end"];
522
+ return {
523
+ by: defined({ workflow: r["workflow"] ?? "chat-stats", step: r["step"] ?? "scan" }),
524
+ bkit: {
525
+ version: r["bkitVersion"] === undefined || r["bkitVersion"] === "none" ? null : r["bkitVersion"],
526
+ versionSource: r["bkitVersionSource"] ?? "none",
527
+ via: arrOf(r["bkitVia"]),
528
+ workflows: arrOf(r["bkitWorkflows"]),
529
+ prompts: arrOf(r["bkitKinds"]),
530
+ cli: { total: sumNums(Object.values(byVerb)), byVerb },
531
+ },
532
+ session: {
533
+ platform: r["platform"] ?? "claude-code",
534
+ id: r["sessionId"] ?? null,
535
+ hostVersion: r["hostVersion"] ?? null,
536
+ entrypoint: r["entrypoint"] ?? null,
537
+ prompts: numOr(r["userPrompts"]),
538
+ },
539
+ time: defined({
540
+ start: start ?? null,
541
+ end: end ?? null,
542
+ totalMinutes: typeof r["minutes"] === "number"
543
+ ? r["minutes"]
544
+ : typeof start === "number" && typeof end === "number"
545
+ ? tenthOf((end - start) / 60000)
546
+ : null,
547
+ activeMinutes: numOr(r["activeMinutes"], null),
548
+ spans: arrOf(r["active"]),
549
+ lastActivity: r["lastActivityAt"],
550
+ }),
551
+ issue: {
552
+ id: r["issue"] ?? null,
553
+ all: arrOf(r["issues"]),
554
+ mentioned: arrOf(r["mentioned"]),
555
+ source: r["issueSource"] ?? "none",
556
+ },
557
+ run: { parentShas: arrOf(r["parentShas"]) },
558
+ effort: objOf(r["effort"]),
559
+ usage: {
560
+ total: {
561
+ turns: numOr(r["turns"]),
562
+ // Summed from the models, as a fresh scan writes it: the old row's own total
563
+ // estimated output once over the whole chat, so it can differ from its parts.
564
+ tokens: Object.keys(byModel).length > 0
565
+ ? Object.fromEntries(TOKENS.map((k) => [k, sumNums(Object.values(byModel).map((x) => x.tokens[k]))]))
566
+ : oldTokens(tokens),
567
+ context: { start: numOr(tokens["ctxStart"]), peak: numOr(tokens["ctxPeak"]) },
568
+ compactions: numOr(r["compactions"]),
569
+ },
570
+ main: defined({
571
+ turns: numOr(m["turns"]),
572
+ tokens: oldTokens(m),
573
+ context: { peak: numOr(m["ctxPeak"]) },
574
+ compactions: numOr(m["compactions"]),
575
+ mix: oldMix(m["mix"]),
576
+ }),
577
+ byModel,
578
+ },
579
+ agents: {
580
+ total: {
581
+ n: numOr(r["subagents"], sumNums(agents.map((a) => a["n"]))),
582
+ errors: sumNums(agents.map((a) => a["errors"])),
583
+ },
584
+ byAgent,
585
+ },
586
+ tools: {
587
+ total: {
588
+ calls: sumNums(tools.map((t) => t["calls"])),
589
+ errors: sumNums(tools.map((t) => t["errors"])),
590
+ },
591
+ byTool,
592
+ filesRead: numOr(r["filesRead"]),
593
+ },
594
+ scan: defined({
595
+ files: r["sourceFiles"],
596
+ bytes: r["sourceBytes"],
597
+ settled: r["settled"],
598
+ tokensRecorded: r["tokensRecorded"],
599
+ }),
600
+ };
601
+ }
602
+ /** A schema-1 run row's plan: its per-task lists, grouped when unsplit. */
603
+ function oldPlan(p) {
604
+ const n = numOr(p["subPlans"], 1);
605
+ const tests = arrOf(p["testsPerTask"]);
606
+ const files = arrOf(p["testFilesPerTask"]);
607
+ const tasks = numOr(p["tasks"], tests.length);
608
+ const kb = numOr(p["kb"]);
609
+ const out = { source: "file", total: { tasks, kb } };
610
+ out["subPlans"] =
611
+ n === 1
612
+ ? [
613
+ {
614
+ kb,
615
+ tasks: Array.from({ length: tasks }, (_, i) => ({
616
+ tests: numOr(tests[i], null),
617
+ testFiles: numOr(files[i], null),
618
+ })),
619
+ },
620
+ ]
621
+ : // A split plan's per-task lists were stored flat: which sub-plan each task was in is not known.
622
+ Array.from({ length: n }, () => ({ kb: null, tasks: null }));
623
+ if (isObj(p["complexity"]))
624
+ out["complexity"] = p["complexity"];
625
+ return out;
626
+ }
627
+ function oldRun(r) {
628
+ const steps = Object.entries(objOf(r["steps"])).map(([k, v]) => [k, objOf(v)]);
629
+ const byStep = Object.fromEntries(steps.map(([k, st]) => [
630
+ k,
631
+ {
632
+ n: numOr(st["n"]),
633
+ totalMinutes: numOr(st["minutes"]),
634
+ activeMinutes: numOr(st["active"], null),
635
+ },
636
+ ]));
637
+ const parts = steps.map(([, st]) => st);
638
+ const isBuild = r["workflow"] === "build" ||
639
+ ["verify", "gapsRemediate", "holistic", "challenge", "redTests"].some((k) => k in r);
640
+ const ch = isObj(r["challenge"]) ? r["challenge"] : undefined;
641
+ const f = isObj(ch?.["findings"]) ? ch["findings"] : undefined;
642
+ const lines = objOf(r["lines"]);
643
+ const lineParts = ["code", "tests", "docs"].map((k) => objOf(lines[k]));
644
+ const linesOut = isObj(r["lines"]) && isObj(lines["code"])
645
+ ? (() => {
646
+ const added = sumNums(lineParts.map((p) => p["added"]));
647
+ const deleted = sumNums(lineParts.map((p) => p["deleted"]));
648
+ return {
649
+ total: {
650
+ added,
651
+ deleted,
652
+ changed: added + deleted,
653
+ files: sumNums(lineParts.map((p) => p["files"])),
654
+ },
655
+ code: lines["code"],
656
+ tests: lines["tests"],
657
+ docs: lines["docs"],
658
+ merges: lines["merges"],
659
+ };
660
+ })()
661
+ : r["lines"];
662
+ return defined({
663
+ run: {
664
+ fid: r["fid"] ?? null,
665
+ issue: r["issue"] ?? null,
666
+ n: numOr(r["run"], null),
667
+ parentSha: r["parentSha"] ?? null,
668
+ parentShas: arrOf(r["parentShas"]),
669
+ },
670
+ time: defined({
671
+ start: r["start"] ?? null,
672
+ end: r["end"] ?? null,
673
+ totalMinutes: numOr(r["minutes"], null),
674
+ activeMinutes: numOr(r["activeMinutes"], null),
675
+ activeFrom: r["activeFrom"] ?? null,
676
+ lastActivity: r["lastActivityAt"],
677
+ }),
678
+ ending: r["ending"],
679
+ ci: arrOf(r["closeCi"]).map((cv) => {
680
+ const c = objOf(cv);
681
+ return defined({
682
+ status: c["outcome"] ?? null,
683
+ reason: c["reason"] ?? undefined,
684
+ attempts: numOr(c["attempts"], null),
685
+ });
686
+ }),
687
+ steps: {
688
+ total: {
689
+ n: sumNums(parts.map((st) => st["n"])),
690
+ totalMinutes: tenthOf(sumNums(parts.map((st) => st["minutes"]))),
691
+ activeMinutes: parts.some((st) => typeof st["active"] !== "number")
692
+ ? null
693
+ : tenthOf(sumNums(parts.map((st) => st["active"]))),
694
+ },
695
+ byStep,
696
+ },
697
+ lines: linesOut,
698
+ plan: isObj(r["plan"]) ? oldPlan(r["plan"]) : r["plan"],
699
+ build: isBuild
700
+ ? defined({
701
+ verify: arrOf(r["verify"]),
702
+ gapsRemediate: arrOf(r["gapsRemediate"]),
703
+ holistic: r["holistic"] ?? undefined,
704
+ challenge: ch
705
+ ? {
706
+ verdict: ch["verdict"] ?? null,
707
+ findings: f ? { total: sumNums(Object.values(f)), ...f } : null,
708
+ }
709
+ : undefined,
710
+ redTests: numOr(r["redTests"]),
711
+ })
712
+ : undefined,
713
+ scan: defined({ rows: r["sourceRows"], afterEnd: r["afterEnd"], settled: r["settled"] }),
714
+ });
715
+ }
716
+ /** `normalize` typed for readers: every row a fold or report sees. */
717
+ export const normalizeEvent = (raw) => normalize(raw);
718
+ // ---------------------------------------------------------------------------
719
+ // Totals — every total beside its parts must equal them
720
+ // ---------------------------------------------------------------------------
721
+ const sumOf = (xs) => xs.reduce((a, x) => a + (typeof x === "number" ? x : 0), 0);
722
+ const field = (o, ...pathTo) => pathTo.reduce((v, k) => (isObj(v) ? v[k] : undefined), o);
723
+ const TOKEN_FIELDS = ["input", "cacheWrite", "cacheRead", "output", "outputEst", "read"];
724
+ /**
725
+ * The first total on `row` that does not equal its parts, or undefined. Only blocks
726
+ * the row carries are checked. Minute totals are summed from unrounded values, so
727
+ * each part may be off by its rounding: +-0.1 per part.
728
+ */
729
+ export function totalsProblem(row) {
730
+ const eq = (what, total, parts, tol = 0) => typeof total === "number" && Math.abs(total - parts) <= tol + 1e-9
731
+ ? undefined
732
+ : `${what} is ${String(total)}, its parts sum to ${tenthOf(parts)}`;
733
+ const checks = [];
734
+ const lines = row["lines"];
735
+ if (isObj(lines) && isObj(lines["total"])) {
736
+ const t = lines["total"];
737
+ checks.push(() => eq("lines.total.changed", t["changed"], sumOf([t["added"], t["deleted"]])));
738
+ if (["code", "tests", "docs"].some((p) => isObj(lines[p]))) {
739
+ for (const f of ["added", "deleted", "files"]) {
740
+ checks.push(() => eq(`lines.total.${f}`, t[f], sumOf(["code", "tests", "docs"].map((p) => field(lines, p, f)))));
741
+ }
742
+ }
743
+ }
744
+ const time = row["time"];
745
+ if (isObj(time) && typeof time["start"] === "number" && typeof time["end"] === "number") {
746
+ checks.push(() => eq("time.totalMinutes", time["totalMinutes"], (time["end"] - time["start"]) / 60000, 0.1));
747
+ const spans = time["spans"];
748
+ if (row["kind"] === "chat" &&
749
+ Array.isArray(spans) &&
750
+ typeof time["activeMinutes"] === "number") {
751
+ const ms = sumOf(spans.map((s) => (Array.isArray(s) ? Number(s[1]) - Number(s[0]) : 0)));
752
+ checks.push(() => eq("time.activeMinutes", time["activeMinutes"], ms / 60000, 0.1));
753
+ }
754
+ }
755
+ const steps = row["steps"];
756
+ if (isObj(steps) && isObj(steps["byStep"]) && isObj(steps["total"])) {
757
+ const parts = Object.values(steps["byStep"]);
758
+ for (const f of ["n", "totalMinutes", "activeMinutes"]) {
759
+ const total = steps["total"][f];
760
+ if (total === undefined || total === null)
761
+ continue;
762
+ const tol = f === "n" ? 0 : 0.1 * Math.max(1, parts.length);
763
+ checks.push(() => eq(`steps.total.${f}`, total, sumOf(parts.map((p) => field(p, f))), tol));
764
+ }
765
+ }
766
+ const plan = row["plan"];
767
+ if (isObj(plan) && isObj(plan["total"]) && Array.isArray(plan["groups"])) {
768
+ const groups = plan["groups"];
769
+ const total = plan["total"];
770
+ checks.push(() => eq("plan.total.tasks", total["tasks"], sumOf(groups.map((g) => arrOf(field(g, "tasks")).length))));
771
+ }
772
+ const build = row["build"];
773
+ if (isObj(build)) {
774
+ const findings = field(build, "challenge", "findings");
775
+ if (isObj(findings)) {
776
+ checks.push(() => eq("build.challenge.findings.total", findings["total"], sumOf(["CRITICAL", "HIGH", "MEDIUM", "LOW"].map((s) => findings[s]))));
777
+ }
778
+ if (typeof build["redTests"] === "number" && isObj(field(steps, "byStep"))) {
779
+ checks.push(() => eq("build.redTests", build["redTests"], Number(field(steps, "byStep", "build-task-red", "n") ?? 0)));
780
+ }
781
+ }
782
+ const usage = row["usage"];
783
+ const agents = row["agents"];
784
+ const byAgent = isObj(agents) && isObj(agents["byAgent"]) ? Object.values(agents["byAgent"]) : [];
785
+ if (isObj(usage)) {
786
+ const blocks = [
787
+ ["usage.total", usage["total"]],
788
+ ["usage.main", usage["main"]],
789
+ ...Object.entries(isObj(usage["byModel"]) ? usage["byModel"] : {}).map(([m, u]) => [`usage.byModel.${m}`, u]),
790
+ ...Object.entries(isObj(agents) && isObj(agents["byAgent"]) ? agents["byAgent"] : {}).map(([a, v]) => [`agents.byAgent.${a}.usage`, field(v, "usage")]),
791
+ ];
792
+ for (const [name, u] of blocks) {
793
+ const tokens = field(u, "tokens");
794
+ if (!isObj(tokens) || tokens["read"] === undefined)
795
+ continue;
796
+ checks.push(() => eq(`${name}.tokens.read`, tokens["read"], sumOf([tokens["input"], tokens["cacheWrite"], tokens["cacheRead"]])));
797
+ }
798
+ const total = usage["total"];
799
+ const models = isObj(usage["byModel"]) ? Object.values(usage["byModel"]) : [];
800
+ if (isObj(total) && models.length > 0) {
801
+ checks.push(() => eq("usage.total.turns", total["turns"], sumOf(models.map((m) => field(m, "turns")))));
802
+ for (const f of TOKEN_FIELDS) {
803
+ if (field(total, "tokens", f) === undefined)
804
+ continue;
805
+ checks.push(() => eq(`usage.total.tokens.${f}`, field(total, "tokens", f), sumOf(models.map((m) => field(m, "tokens", f)))));
806
+ }
807
+ }
808
+ if (isObj(total) && total["compactions"] !== undefined) {
809
+ checks.push(() => eq("usage.total.compactions", total["compactions"], sumOf([
810
+ field(usage, "main", "compactions"),
811
+ ...byAgent.map((a) => field(a, "usage", "compactions")),
812
+ ])));
813
+ }
814
+ const peak = field(total, "context", "peak");
815
+ if (typeof peak === "number") {
816
+ const peaks = [
817
+ field(usage, "main", "context", "peak"),
818
+ ...byAgent.flatMap((a) => Array.isArray(field(a, "instances"))
819
+ ? field(a, "instances").map((i) => field(i, "contextPeak"))
820
+ : []),
821
+ ].filter((v) => typeof v === "number");
822
+ if (peaks.length > 0)
823
+ checks.push(() => eq("usage.total.context.peak", peak, Math.max(...peaks)));
824
+ }
825
+ }
826
+ if (isObj(agents) && isObj(agents["total"]) && isObj(agents["byAgent"])) {
827
+ const total = agents["total"];
828
+ for (const f of ["n", "errors"]) {
829
+ checks.push(() => eq(`agents.total.${f}`, total[f], sumOf(byAgent.map((a) => field(a, f)))));
830
+ }
831
+ for (const [name, a] of Object.entries(agents["byAgent"])) {
832
+ const instances = field(a, "instances");
833
+ if (Array.isArray(instances)) {
834
+ checks.push(() => eq(`agents.byAgent.${name}.n`, field(a, "n"), instances.length));
835
+ }
836
+ }
837
+ }
838
+ const tools = row["tools"];
839
+ if (isObj(tools) && isObj(tools["total"]) && isObj(tools["byTool"])) {
840
+ const parts = Object.values(tools["byTool"]);
841
+ for (const f of ["calls", "errors"]) {
842
+ checks.push(() => eq(`tools.total.${f}`, field(tools, "total", f), sumOf(parts.map((p) => field(p, f)))));
843
+ }
844
+ }
845
+ const cli = field(row, "bkit", "cli");
846
+ if (isObj(cli) && isObj(cli["byVerb"])) {
847
+ checks.push(() => eq("bkit.cli.total", cli["total"], sumOf(Object.values(cli["byVerb"]))));
848
+ }
849
+ for (const check of checks) {
850
+ const problem = check();
851
+ if (problem !== undefined)
852
+ return problem;
853
+ }
854
+ return undefined;
855
+ }
195
856
  // ---------------------------------------------------------------------------
196
857
  // Validate — reject malformed + unknown kind before write
197
858
  // ---------------------------------------------------------------------------
@@ -200,13 +861,19 @@ export function validate(event) {
200
861
  return { ok: false, reason: "event must be an object" };
201
862
  }
202
863
  const e = event;
203
- // A2-mandatory envelope fields
204
- const mandatory = ["ts", "kind", "repo", "bkitVersion", "step"];
205
- for (const field of mandatory) {
864
+ if (e["schema"] !== SCHEMA) {
865
+ return { ok: false, reason: `schema must be ${SCHEMA} (got: ${String(e["schema"])})` };
866
+ }
867
+ for (const field of ["ts", "kind", "repo", "bkit", "by"]) {
206
868
  if (e[field] === undefined || e[field] === null) {
207
869
  return { ok: false, reason: `missing mandatory field: ${field}` };
208
870
  }
209
871
  }
872
+ for (const flat of ["bkitVersion", "workflow", "step", "subagent", "model"]) {
873
+ if (e[flat] !== undefined) {
874
+ return { ok: false, reason: `${flat} is not a top-level field (bkit.version, by.*)` };
875
+ }
876
+ }
210
877
  if (typeof e["ts"] !== "number") {
211
878
  return { ok: false, reason: "ts must be a number (ms unix)" };
212
879
  }
@@ -219,11 +886,35 @@ export function validate(event) {
219
886
  if (typeof e["repo"] !== "string" || e["repo"] === "") {
220
887
  return { ok: false, reason: "repo must be a non-empty string" };
221
888
  }
222
- if (typeof e["bkitVersion"] !== "string" || e["bkitVersion"] === "") {
223
- return { ok: false, reason: "bkitVersion must be a non-empty string" };
889
+ const bkit = e["bkit"];
890
+ // null on chat / run rows: the script found no bkit version in the repo's history at that time.
891
+ const unknownVersion = bkit !== undefined &&
892
+ isObj(bkit) &&
893
+ bkit["version"] === null &&
894
+ (e["kind"] === "chat" || e["kind"] === "run");
895
+ if (!isObj(bkit) ||
896
+ ((typeof bkit["version"] !== "string" || bkit["version"] === "") && !unknownVersion)) {
897
+ return {
898
+ ok: false,
899
+ reason: "bkit.version must be a non-empty string (null on chat / run rows)",
900
+ };
901
+ }
902
+ const by = e["by"];
903
+ if (!isObj(by))
904
+ return { ok: false, reason: "by must be an object" };
905
+ if (typeof by["step"] !== "string" || by["step"] === "") {
906
+ return { ok: false, reason: "by.step must be a non-empty string" };
907
+ }
908
+ for (const f of ["workflow", "subagent", "model"]) {
909
+ if (by[f] !== undefined && (typeof by[f] !== "string" || by[f] === "")) {
910
+ return { ok: false, reason: `by.${f} must be a non-empty string when present` };
911
+ }
224
912
  }
225
- if (typeof e["step"] !== "string" || e["step"] === "") {
226
- return { ok: false, reason: "step must be a non-empty string" };
913
+ if (by["model"] !== undefined && by["subagent"] === undefined) {
914
+ return { ok: false, reason: "by.model is set only on subagent rows" };
915
+ }
916
+ if (e["references"] !== undefined && !Array.isArray(e["references"])) {
917
+ return { ok: false, reason: "references must be an array when present" };
227
918
  }
228
919
  // kind-specific payload validation (minimal — structural check)
229
920
  const kind = e["kind"];
@@ -293,80 +984,160 @@ export function validate(event) {
293
984
  else if (e["reason"] !== undefined) {
294
985
  return { ok: false, reason: `${kind} rows do not carry reason` };
295
986
  }
987
+ const run = isObj(e["run"]) ? e["run"] : undefined;
988
+ if (kind === "compliance" || kind === "counter") {
989
+ if (typeof run?.["parentSha"] !== "string" || run["parentSha"] === "") {
990
+ return { ok: false, reason: `${kind} row missing run.parentSha` };
991
+ }
992
+ }
296
993
  if (kind === "compliance") {
297
- if (!e["rule"] || !e["result"] || !e["phase"] || !e["parentSha"]) {
298
- return { ok: false, reason: "compliance row missing required payload fields" };
994
+ const rule = e["rule"];
995
+ if (!isObj(rule) || typeof rule["id"] !== "string" || rule["id"] === "") {
996
+ return { ok: false, reason: "compliance row missing rule.id" };
997
+ }
998
+ if (!["pass", "fail", "n/a"].includes(rule["verdict"])) {
999
+ return {
1000
+ ok: false,
1001
+ reason: `compliance rule.verdict must be pass|fail|n/a (got: ${String(rule["verdict"])})`,
1002
+ };
1003
+ }
1004
+ }
1005
+ if (kind === "counter") {
1006
+ const c = e["counter"];
1007
+ if (!isObj(c) ||
1008
+ typeof c["name"] !== "string" ||
1009
+ c["name"] === "" ||
1010
+ typeof c["value"] !== "number") {
1011
+ return { ok: false, reason: "counter row needs counter.name and a numeric counter.value" };
1012
+ }
1013
+ if (c["source"] !== "model-self-report" && c["source"] !== "shell-bus") {
1014
+ return { ok: false, reason: "counter.source must be model-self-report or shell-bus" };
299
1015
  }
300
1016
  }
301
1017
  if (kind === "outcome") {
302
- // Every workflow run carries these; `prNumber` is ship-only (see below).
303
- const numFields = [
304
- "linesAdded",
305
- "linesDeleted",
306
- "linesChanged",
307
- "filesChanged",
308
- "taskCount",
309
- "durationSeconds",
310
- "deferrals",
311
- "failures",
312
- ];
313
- for (const f of numFields) {
314
- if (typeof e[f] !== "number") {
315
- return { ok: false, reason: `outcome missing or invalid numeric field: ${f}` };
316
- }
1018
+ if (run === undefined)
1019
+ return { ok: false, reason: "outcome row missing run" };
1020
+ if (run["parentSha"] !== undefined && typeof run["parentSha"] !== "string") {
1021
+ return { ok: false, reason: "outcome run.parentSha must be a string when present" };
1022
+ }
1023
+ if (run["pr"] !== undefined && typeof run["pr"] !== "number") {
1024
+ return { ok: false, reason: "outcome run.pr must be a number when present" };
1025
+ }
1026
+ const time = e["time"];
1027
+ // null: the run's start row is missing, so its time could not be measured.
1028
+ if (time !== null &&
1029
+ (!isObj(time) || ["start", "end", "totalMinutes"].some((f) => typeof time[f] !== "number"))) {
1030
+ return {
1031
+ ok: false,
1032
+ reason: "outcome row needs time.start, time.end and time.totalMinutes, or time: null",
1033
+ };
1034
+ }
1035
+ if (!OUTCOME_ENDINGS.has(e["ending"])) {
1036
+ return {
1037
+ ok: false,
1038
+ reason: `outcome ending must be done|close-failed (got: ${String(e["ending"])})`,
1039
+ };
317
1040
  }
318
- // prNumber — ship-only, optional; validate only when present.
319
- if (e["prNumber"] !== undefined && typeof e["prNumber"] !== "number") {
320
- return { ok: false, reason: "outcome prNumber must be a number when present" };
321
- }
322
- // parentSha — the run's identity anchor; optional (absent on some ship rows).
323
- if (e["parentSha"] !== undefined && typeof e["parentSha"] !== "string") {
324
- return { ok: false, reason: "outcome parentSha must be a string when present" };
325
- }
326
- // Optional per-run numeric metrics: validate type only when present.
327
- for (const f of [
328
- "frictionAdded",
329
- "deferralsAdded",
330
- "failuresAdded",
331
- "correctiveCommits",
332
- "reviewIterations",
333
- "ciTrySuccess",
334
- ]) {
335
- if (e[f] !== undefined && typeof e[f] !== "number") {
336
- return { ok: false, reason: `outcome ${f} must be a number when present` };
1041
+ const ledgers = e["ledgers"];
1042
+ if (typeof field(ledgers, "deferrals", "repo") !== "number" ||
1043
+ typeof field(ledgers, "failures", "repo") !== "number") {
1044
+ return {
1045
+ ok: false,
1046
+ reason: "outcome row needs ledgers.deferrals.repo and ledgers.failures.repo",
1047
+ };
1048
+ }
1049
+ for (const l of ["deferrals", "failures", "friction"]) {
1050
+ const added = field(ledgers, l, "added");
1051
+ if (added !== undefined && typeof added !== "number") {
1052
+ return { ok: false, reason: `outcome ledgers.${l}.added must be a number when present` };
337
1053
  }
338
1054
  }
339
- if (e["planSource"] !== undefined && e["planSource"] !== "brief") {
340
- return { ok: false, reason: 'outcome planSource must be "brief" when present' };
1055
+ const source = field(e["plan"], "source");
1056
+ if (e["plan"] !== undefined && source !== "file" && source !== "converted") {
1057
+ return {
1058
+ ok: false,
1059
+ reason: `outcome plan.source must be file|converted (got: ${String(source)})`,
1060
+ };
341
1061
  }
342
- // coverage is optional + per-tier; validate structure only when present.
343
- if (e["coverage"] !== undefined) {
344
- const cov = e["coverage"];
345
- if (typeof cov !== "object" || cov === null) {
346
- return { ok: false, reason: "outcome coverage must be an object" };
1062
+ const context = e["context"];
1063
+ if (context !== undefined) {
1064
+ const byAgent = field(context, "byAgent");
1065
+ if (!isObj(context) || typeof context["host"] !== "string" || !isObj(byAgent)) {
1066
+ return { ok: false, reason: "outcome context needs host and a byAgent object" };
1067
+ }
1068
+ for (const [agent, a] of Object.entries(byAgent)) {
1069
+ if (typeof field(a, "peak") !== "number" || typeof field(a, "runs") !== "number") {
1070
+ return {
1071
+ ok: false,
1072
+ reason: `outcome context.byAgent.${agent} needs numeric peak and runs`,
1073
+ };
1074
+ }
347
1075
  }
1076
+ }
1077
+ const cov = field(e["ship"], "coverage");
1078
+ if (cov !== undefined) {
1079
+ if (!isObj(cov))
1080
+ return { ok: false, reason: "outcome ship.coverage must be an object" };
348
1081
  for (const tier of ["unit", "integration", "e2e"]) {
349
1082
  const t = cov[tier];
350
1083
  if (t === undefined)
351
1084
  continue;
352
- if (typeof t !== "object" || t === null) {
353
- return { ok: false, reason: `outcome coverage.${tier} must be an object` };
354
- }
1085
+ if (!isObj(t))
1086
+ return { ok: false, reason: `outcome ship.coverage.${tier} must be an object` };
355
1087
  for (const m of ["lines", "branches", "functions", "statements"]) {
356
- const v = t[m];
357
- if (v !== undefined && typeof v !== "number") {
358
- return { ok: false, reason: `outcome coverage.${tier}.${m} must be a number` };
1088
+ if (t[m] !== undefined && typeof t[m] !== "number") {
1089
+ return { ok: false, reason: `outcome ship.coverage.${tier}.${m} must be a number` };
359
1090
  }
360
1091
  }
361
1092
  }
362
1093
  }
363
1094
  }
364
- if (kind === "counter") {
365
- if (!e["counterName"] || typeof e["counterValue"] !== "number" || !e["parentSha"]) {
366
- return { ok: false, reason: "counter row missing required payload fields" };
1095
+ if (kind === "chat") {
1096
+ if (!e["key"] || typeof e["key"] !== "string") {
1097
+ return { ok: false, reason: "chat row missing required field: key (<platform>:<sessionId>)" };
1098
+ }
1099
+ if (typeof field(e, "time", "start") !== "number" ||
1100
+ typeof field(e, "time", "end") !== "number") {
1101
+ return { ok: false, reason: "chat row needs time.start and time.end" };
1102
+ }
1103
+ if (typeof field(e, "scan", "bytes") !== "number") {
1104
+ return { ok: false, reason: "chat row needs scan.bytes" };
1105
+ }
1106
+ if (!Array.isArray(field(e, "run", "parentShas")) || !Array.isArray(field(e, "issue", "all"))) {
1107
+ return {
1108
+ ok: false,
1109
+ reason: "chat row needs run.parentShas and issue.all arrays (the join keys)",
1110
+ };
1111
+ }
1112
+ }
1113
+ if (kind === "run") {
1114
+ if (!e["key"] || typeof e["key"] !== "string") {
1115
+ return {
1116
+ ok: false,
1117
+ reason: "run row missing required field: key (<fid fp>:<workflow>:<start>)",
1118
+ };
1119
+ }
1120
+ if (typeof run?.["fid"] !== "string" || run["fid"] === "") {
1121
+ return { ok: false, reason: "run row missing required field: run.fid" };
1122
+ }
1123
+ if (typeof field(e, "time", "start") !== "number" ||
1124
+ typeof field(e, "time", "end") !== "number") {
1125
+ return { ok: false, reason: "run row needs time.start and time.end" };
367
1126
  }
368
- if (e["counterSource"] !== "model-self-report" && e["counterSource"] !== "shell-bus") {
369
- return { ok: false, reason: "counter counterSource must be model-self-report or shell-bus" };
1127
+ if (typeof field(e, "scan", "rows") !== "number") {
1128
+ return { ok: false, reason: "run row needs scan.rows" };
1129
+ }
1130
+ if (!RUN_ENDINGS.has(e["ending"])) {
1131
+ return {
1132
+ ok: false,
1133
+ reason: `run ending must be one of ${[...RUN_ENDINGS].join("|")} (got: ${String(e["ending"])})`,
1134
+ };
1135
+ }
1136
+ if (run["parentSha"] !== null && typeof run["parentSha"] !== "string") {
1137
+ return { ok: false, reason: "run run.parentSha must be a string or null" };
1138
+ }
1139
+ if (!Array.isArray(run["parentShas"])) {
1140
+ return { ok: false, reason: "run row needs a run.parentShas array (the join keys)" };
370
1141
  }
371
1142
  }
372
1143
  if (kind === "feature") {
@@ -380,13 +1151,17 @@ export function validate(event) {
380
1151
  return { ok: false, reason: "feature row missing required payload field: description" };
381
1152
  }
382
1153
  }
1154
+ const totals = totalsProblem(e);
1155
+ if (totals !== undefined)
1156
+ return { ok: false, reason: `totals: ${totals}` };
383
1157
  return { ok: true };
384
1158
  }
385
1159
  /**
386
1160
  * Tolerant parse — per-line try/catch, skips + counts unparseable lines.
387
1161
  * NEVER throws.
388
1162
  *
389
- * No version gating — ALL well-formed rows are kept regardless of `bkitVersion`.
1163
+ * No version gating — ALL well-formed rows are kept as written, `schema` or not;
1164
+ * {@link fold} reads each through {@link normalize}.
390
1165
  */
391
1166
  export function parse(raw) {
392
1167
  const result = {
@@ -429,13 +1204,13 @@ export function compareTs(a, b) {
429
1204
  return x < y ? -1 : x > y ? 1 : 0;
430
1205
  }
431
1206
  /**
432
- * Fold events into a Map keyed by per-kind composite identity.
433
- * Later rows (higher ts) win for the same key — last-write-wins fold.
434
- * Mirrors ledgers/status.ts's dedupe approach but with per-kind composite tuples.
1207
+ * Fold events into a Map keyed by per-kind composite identity, each row in the
1208
+ * current shape ({@link normalize}). Later rows (higher ts) win for the same key —
1209
+ * last-write-wins fold.
435
1210
  */
436
1211
  export function fold(events) {
437
1212
  // Sort by ts ascending so later rows overwrite earlier ones
438
- const sorted = [...events].sort(compareTs);
1213
+ const sorted = events.map(normalizeEvent).sort(compareTs);
439
1214
  const state = new Map();
440
1215
  for (const event of sorted) {
441
1216
  const key = identity(event);
@@ -456,8 +1231,9 @@ export function foldFrom(paths) {
456
1231
  totalMalformed += parsed.malformedLineCount;
457
1232
  }
458
1233
  const versionCounts = {};
459
- for (const e of allEvents) {
460
- const v = typeof e.bkitVersion === "string" && e.bkitVersion !== "" ? e.bkitVersion : "unknown";
1234
+ for (const e of allEvents.map(normalizeEvent)) {
1235
+ const version = e.bkit?.version;
1236
+ const v = typeof version === "string" && version !== "" ? version : "unknown";
461
1237
  versionCounts[v] = (versionCounts[v] ?? 0) + 1;
462
1238
  }
463
1239
  const rowCount = allEvents.length;
@@ -536,7 +1312,7 @@ export function workflowTelemetry(result, workflow) {
536
1312
  // Folded ENTITY count per workflow (not raw lines) — an updated row folds to one.
537
1313
  const workflowCounts = {};
538
1314
  for (const ev of events) {
539
- const w = ev.workflow || "unknown";
1315
+ const w = ev.by?.workflow || "unknown";
540
1316
  workflowCounts[w] = (workflowCounts[w] ?? 0) + 1;
541
1317
  }
542
1318
  const base = {
@@ -558,14 +1334,17 @@ export function workflowTelemetry(result, workflow) {
558
1334
  }
559
1335
  // This workflow's run rows (generalized outcome), oldest → newest.
560
1336
  const runs = events
561
- .filter((e) => e.kind === "outcome" && e.workflow === workflow)
1337
+ .filter((e) => e.kind === "outcome" && e.by?.workflow === workflow)
562
1338
  .sort(compareTs);
563
1339
  const cur = runs.at(-1);
564
- // Baseline only against runs of the same plan source — a brief run (no plan)
565
- // has no tasks and a different shape, so mixing them skews every median.
1340
+ // Baseline only against runs of the same plan source — a converted run's plan was
1341
+ // written by the build from its input, so mixing it with file runs skews every median.
1342
+ // An old `brief` row (no plan file) counts as converted.
1343
+ const oldBrief = (r) => r?.plan?.source === "brief";
1344
+ const converted = (r) => r?.plan?.source === "converted" || oldBrief(r);
566
1345
  const prev = runs
567
1346
  .slice(0, -1)
568
- .filter((r) => r.planSource === cur?.planSource)
1347
+ .filter((r) => converted(r) === converted(cur))
569
1348
  .slice(-RUN_BASELINE_WINDOW);
570
1349
  const repo = cur?.repo ?? events[0]?.repo ?? "unknown/repo";
571
1350
  // Rendered as a Markdown table so it drops straight into the tracker comment
@@ -578,61 +1357,63 @@ export function workflowTelemetry(result, workflow) {
578
1357
  if (cur) {
579
1358
  // med·N: median of the previous runs that carry the field, `—` until there are
580
1359
  // at least RUN_BASELINE_MIN of them (1–2 samples is noise, not a baseline).
581
- const medCell = (key, fmt = String) => {
582
- const vals = prev.map((r) => r[key]).filter((v) => typeof v === "number");
1360
+ const medCell = (get, fmt = String) => {
1361
+ const vals = prev.map(get).filter((v) => typeof v === "number");
583
1362
  if (vals.length < RUN_BASELINE_MIN)
584
1363
  return "—";
585
1364
  const m = median(vals);
586
1365
  return m === null ? "—" : fmt(m);
587
1366
  };
588
- // Core metrics — always shown.
589
- row("durationSeconds", `${cur.durationSeconds} (${humanizeDuration(cur.durationSeconds)})`, medCell("durationSeconds", (n) => `${n} (${humanizeDuration(n)})`));
590
- row("linesChanged", `${cur.linesChanged} (+${cur.linesAdded}/-${cur.linesDeleted})`, medCell("linesChanged"));
591
- row("filesChanged", `${cur.filesChanged}`, medCell("filesChanged"));
592
- // Conditional metrics — shown only when this run carries them.
593
- if (cur.planSource)
594
- row("planSource", cur.planSource, "—");
595
- if (cur.taskCount > 0)
596
- row("taskCount", `${cur.taskCount}`, medCell("taskCount"));
597
- if (typeof cur.reviewIterations === "number")
598
- row("reviewIterations", `${cur.reviewIterations}`, medCell("reviewIterations"));
599
- if (typeof cur.correctiveCommits === "number")
600
- row("correctiveCommits", `${cur.correctiveCommits}`, medCell("correctiveCommits"));
601
- if (typeof cur.ciTrySuccess === "number")
602
- row("ciTrySuccess", `${cur.ciTrySuccess}${cur.ciTrySuccess === 1 ? " (first-try)" : ""}`, medCell("ciTrySuccess"));
603
- // Instinct-loop deltas — frictionAdded is the featured signal (shown even at 0).
604
- if (typeof cur.frictionAdded === "number")
605
- row("frictionAdded", `${cur.frictionAdded}`, medCell("frictionAdded"));
606
- if (typeof cur.deferralsAdded === "number")
607
- row("deferralsAdded", `${cur.deferralsAdded}`, medCell("deferralsAdded"));
608
- if (typeof cur.failuresAdded === "number")
609
- row("failuresAdded", `${cur.failuresAdded}`, medCell("failuresAdded"));
610
- }
611
- // Compliance — this run's rows. The `outcome` and `compliance` rows are written
612
- // at different points in a close (different HEADs → different parentSha), so we
613
- // DON'T match on the run row's parentSha: we take the newest same-workflow
614
- // compliance group (its parentSha) as "this run".
615
- const complianceRows = events.filter((e) => e.kind === "compliance" && e.workflow === workflow);
616
- const compSha = complianceRows.slice().sort((a, b) => compareTs(b, a))[0]?.parentSha;
1367
+ const mins = (n) => `${n} (${humanizeDuration(n * 60)})`;
1368
+ const show = (label, get, fmt) => {
1369
+ const v = get(cur);
1370
+ if (typeof v === "number")
1371
+ row(label, fmt ? fmt(v) : String(v), medCell(get, fmt));
1372
+ };
1373
+ show("time.totalMinutes", (r) => r.time?.totalMinutes, mins);
1374
+ const total = cur.lines?.total;
1375
+ if (total) {
1376
+ row("lines.total.changed", `${total.changed} (+${total.added}/-${total.deleted})`, medCell((r) => r.lines?.total?.changed));
1377
+ show("lines.total.files", (r) => r.lines?.total?.files);
1378
+ }
1379
+ show("plan.total.tasks", (r) => r.plan?.total?.tasks);
1380
+ if (cur.ending === "close-failed")
1381
+ row("ending", "close-failed", "—");
1382
+ // Instinct-loop deltas — friction is the featured signal (shown even at 0).
1383
+ show("ledgers.friction.added", (r) => r.ledgers?.friction?.added);
1384
+ show("ledgers.deferrals.added", (r) => r.ledgers?.deferrals?.added);
1385
+ show("ledgers.failures.added", (r) => r.ledgers?.failures?.added);
1386
+ }
1387
+ // Compliance — this run's rows: the run row's run.parentSha, else the newest
1388
+ // same-workflow compliance group.
1389
+ const complianceRows = events.filter((e) => e.kind === "compliance" && e.by?.workflow === workflow);
1390
+ const newestSha = complianceRows.slice().sort((a, b) => compareTs(b, a))[0]?.run?.parentSha;
1391
+ const curSha = cur?.run?.parentSha;
1392
+ const compSha = complianceRows.some((c) => c.run?.parentSha === curSha) ? curSha : newestSha;
617
1393
  if (compSha) {
618
- const comp = complianceRows.filter((c) => c.parentSha === compSha);
619
- const pass = comp.filter((c) => c.result === "pass").length;
620
- const fail = comp.filter((c) => c.result === "fail").length;
621
- const na = comp.filter((c) => c.result === "n/a").length;
1394
+ const comp = complianceRows.filter((c) => c.run?.parentSha === compSha);
1395
+ const pass = comp.filter((c) => c.rule?.verdict === "pass").length;
1396
+ const fail = comp.filter((c) => c.rule?.verdict === "fail").length;
1397
+ const na = comp.filter((c) => c.rule?.verdict === "n/a").length;
622
1398
  const denom = pass + fail + na;
623
1399
  const rate = denom > 0 ? Math.round((pass / denom) * 100) : 0;
624
1400
  row("compliance", `${pass} pass · ${fail} fail · ${na} n/a (${rate}%)`, "—");
625
1401
  }
626
- // Attempts — the newest same-workflow *_ATTEMPT counter (this run).
627
- const attempt = events
628
- .filter((e) => e.kind === "counter" && e.workflow === workflow && /_ATTEMPT$/.test(e.counterName))
629
- .sort((a, b) => compareTs(b, a))[0];
1402
+ // Attempts — this run's *_ATTEMPT counter, else the newest same-workflow one.
1403
+ const attempts = events
1404
+ .filter((e) => e.kind === "counter" &&
1405
+ e.by?.workflow === workflow &&
1406
+ /_ATTEMPT$/.test(e.counter?.name ?? ""))
1407
+ .sort((a, b) => compareTs(b, a));
1408
+ const attempt = attempts.find((c) => c.run?.parentSha === curSha) ?? attempts[0];
630
1409
  if (attempt)
631
- row("attempts", `${attempt.counterName} ${attempt.counterValue}`, "—");
1410
+ row("attempts", `${attempt.counter.name} ${attempt.counter.value}`, "—");
632
1411
  if (tableRows.length > 0) {
633
1412
  lines.push(`| metric | this run | med·${RUN_BASELINE_WINDOW} |`, "| --- | --- | --- |", ...tableRows, "");
634
1413
  }
635
- lines.push(`\`med·${RUN_BASELINE_WINDOW}\` = median of the previous ${RUN_BASELINE_WINDOW} ${workflow}${cur?.planSource ? ` ${cur.planSource}` : ""} runs (— if < ${RUN_BASELINE_MIN}) · ledger ${result.rowCount} rows, ${result.malformedLineCount} malformed`);
1414
+ lines.push(`\`med·${RUN_BASELINE_WINDOW}\` = median of the previous ${RUN_BASELINE_WINDOW} ${workflow}${converted(cur) ? " converted" : ""} runs (— if < ${RUN_BASELINE_MIN}) · ledger ${result.rowCount} rows, ${result.malformedLineCount} malformed`);
1415
+ if ([cur, ...prev].some(oldBrief))
1416
+ lines.push("Old `plan.source: brief` rows count as `converted`.");
636
1417
  lines.push(...maxRowsLines);
637
1418
  return { ...base, lines };
638
1419
  }