@cbartens/bkit 5.5.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -0,0 +1,501 @@
1
+ // The measured blocks of a workflow run's `outcome` row (`.bkit/core/.bkit/jsonl.md`
2
+ // § Shared blocks): lines, steps, ci, plan and build, from git, the run's
3
+ // `status.jsonl` rows and its log folder. bkit's unshipped harvest script
4
+ // (`scripts/harvest/bkit-harvest.mjs`) computes the same blocks for its `run` rows, with the same rules.
5
+
6
+ import { createHash } from "node:crypto";
7
+ import * as fs from "node:fs";
8
+ import * as path from "node:path";
9
+
10
+ import type { StatusEvent } from "../../ledgers/status.js";
11
+ import {
12
+ foldFrom,
13
+ type BuildBlock,
14
+ CiDispatch,
15
+ type ContextBlock,
16
+ LineCounts,
17
+ LinesBlock,
18
+ PlanBlock,
19
+ PlanTask,
20
+ StepsBlock,
21
+ type TelemetryEvent,
22
+ type TimeBlock,
23
+ } from "../../ledgers/telemetry.js";
24
+ import { parseJson, readDirNames, readJsonFile, readTextFile } from "../../shared/json.js";
25
+ import { git } from "../lib.js";
26
+ import { appendLedgerRows } from "./ledgers.js";
27
+ import { readStatusEvents } from "./status.js";
28
+ import { parsePlanBlocks } from "./plan-blocks.js";
29
+ import { readTestFirst } from "./tests.js";
30
+
31
+ type Row = StatusEvent & Record<string, unknown>;
32
+
33
+ const msOf = (iso: unknown) => (typeof iso === "string" ? Date.parse(iso) : NaN);
34
+ /** Minutes to one decimal. */
35
+ export const minutesOf = (ms: number) => Math.round(ms / 6000) / 10;
36
+
37
+ /** `start` to `end`, unix ms. */
38
+ export function timeBlock(start: number, end: number): TimeBlock {
39
+ return { start, end, totalMinutes: minutesOf(end - start) };
40
+ }
41
+
42
+ /** Left out of a run's line counts: plans and run logs, and the ledgers. */
43
+ const LINES_EXCLUDE = [
44
+ ":(exclude)docs/plans/**",
45
+ ":(exclude,glob)docs/*.jsonl",
46
+ ":(exclude,glob).bkit/*.jsonl",
47
+ ];
48
+ const TEST_PATH =
49
+ /(^|\/)(__tests__|tests?|spec|e2e)\/|[._-](test|spec)\.[^/]+$|_test\.[^/]+$|(^|\/)test_[^/]+\.py$/i;
50
+ const DOCS_PATH = /\.mdx?$|(^|\/)docs\//i;
51
+
52
+ /** `code`, `tests` or `docs`, from a changed file's path. */
53
+ export const lineClass = (file: string): "code" | "tests" | "docs" =>
54
+ TEST_PATH.test(file) ? "tests" : DOCS_PATH.test(file) ? "docs" : "code";
55
+
56
+ /**
57
+ * Lines changed from `first` to `last`, cut at each merge on the first-parent
58
+ * chain (a dev sync) so merged-in work is not counted, each stretch diffed on its
59
+ * own. Null when git lacks either commit or `first` is not an ancestor of `last`.
60
+ */
61
+ export function runLines(cwd: string, first: string, last: string): LinesBlock | null {
62
+ if (!first || !last) return null;
63
+ if (git(cwd, ["merge-base", "--is-ancestor", first, last]) === null) return null;
64
+ const chain = git(cwd, [
65
+ "rev-list",
66
+ "--first-parent",
67
+ "--reverse",
68
+ "--parents",
69
+ `${first}..${last}`,
70
+ ]);
71
+ if (chain === null) return null;
72
+ const stretches: Array<[string, string]> = [];
73
+ let from = first;
74
+ for (const line of chain.split("\n").filter(Boolean)) {
75
+ const [sha, parent, ...merged] = line.split(" ");
76
+ if (merged.length === 0) continue;
77
+ stretches.push([from, parent!]);
78
+ from = sha!;
79
+ }
80
+ stretches.push([from, last]);
81
+ const blank = (): LineCounts => ({ added: 0, deleted: 0, files: 0 });
82
+ const parts = { code: blank(), tests: blank(), docs: blank() };
83
+ for (const [a, b] of stretches) {
84
+ if (a === b) continue;
85
+ const stat = git(cwd, ["diff", "--numstat", a, b, "--", ".", ...LINES_EXCLUDE]);
86
+ if (stat === null) return null;
87
+ for (const line of stat.split("\n").filter(Boolean)) {
88
+ const [added, deleted, file] = line.split("\t");
89
+ const c = parts[lineClass(file ?? "")];
90
+ c.files++;
91
+ // Binary files: `-` for both counts.
92
+ if (added !== "-") {
93
+ c.added += Number(added);
94
+ c.deleted += Number(deleted);
95
+ }
96
+ }
97
+ }
98
+ const sum = (k: keyof LineCounts) => parts.code[k] + parts.tests[k] + parts.docs[k];
99
+ const added = sum("added");
100
+ const deleted = sum("deleted");
101
+ return {
102
+ total: { added, deleted, changed: added + deleted, files: sum("files") },
103
+ ...parts,
104
+ merges: stretches.length - 1,
105
+ };
106
+ }
107
+
108
+ /** The run's status rows of `workflow` from its start row on, in `at` order. */
109
+ export function runStatusRows(events: StatusEvent[], workflow: string, startAt: string): Row[] {
110
+ return (events as Row[])
111
+ .filter((e) => e.workflow === workflow && typeof e.at === "string" && e.at >= startAt)
112
+ .sort((a, b) => msOf(a.at) - msOf(b.at));
113
+ }
114
+
115
+ /** Per step: its step-done rows and the minutes since the row before each, `MARK_ROWS` skipped. */
116
+ export function stepsBlock(all: Row[]): StepsBlock {
117
+ const rows = all.filter((r) => !MARK_ROWS.has(r.type));
118
+ const ms: Record<string, { n: number; ms: number }> = {};
119
+ for (let i = 1; i < rows.length; i++) {
120
+ const r = rows[i]!;
121
+ if (r.type !== "step-done" || typeof r.step !== "string") continue;
122
+ const s = (ms[r.step] ??= { n: 0, ms: 0 });
123
+ s.n++;
124
+ s.ms += Math.max(0, msOf(r.at) - msOf(rows[i - 1]!.at));
125
+ }
126
+ const byStep = Object.fromEntries(
127
+ Object.entries(ms).map(([k, v]) => [k, { n: v.n, totalMinutes: minutesOf(v.ms) }]),
128
+ );
129
+ const parts = Object.values(byStep);
130
+ return {
131
+ total: {
132
+ n: parts.reduce((a, p) => a + p.n, 0),
133
+ totalMinutes: Math.round(parts.reduce((a, p) => a + p.totalMinutes, 0) * 10) / 10,
134
+ },
135
+ byStep,
136
+ };
137
+ }
138
+
139
+ /** Every close step's CI dispatch, in order. */
140
+ export function ciList(rows: Row[]): CiDispatch[] {
141
+ return rows
142
+ .filter((r) => r.type === "step-done" && /-close-workflow$/.test(String(r.step ?? "")))
143
+ .map((r) => r.ciDispatch as Record<string, unknown> | undefined)
144
+ .filter((d) => d !== undefined && d !== null)
145
+ .map((d) => ciEntry(d!));
146
+ }
147
+
148
+ /** One `ciDispatch` value as a `ci` entry. */
149
+ export function ciEntry(d: Record<string, unknown>): CiDispatch {
150
+ return {
151
+ status: typeof d.outcome === "string" ? d.outcome : null,
152
+ reason: typeof d.reason === "string" ? d.reason : null,
153
+ attempts: typeof d.attempts === "number" ? d.attempts : null,
154
+ };
155
+ }
156
+
157
+ const kbOf = (file: string) => Math.round(fs.statSync(file).size / 1024);
158
+
159
+ /**
160
+ * Per plan group, per task: its TEST FIRST tests and distinct test files; null when the
161
+ * task has no such field.
162
+ */
163
+ export function planTasks(text: string): PlanTask[][] {
164
+ return parsePlanBlocks(text).groups.map((g) =>
165
+ readTestFirst(text, g.group).map((s) =>
166
+ s.kind === "test"
167
+ ? { tests: s.tests.length, testFiles: new Set(s.tests.map((t) => t.test)).size }
168
+ : s.kind === "missing"
169
+ ? { tests: null, testFiles: null }
170
+ : { tests: 0, testFiles: 0 },
171
+ ),
172
+ );
173
+ }
174
+
175
+ /** The plan file the run worked from, absolute: `[{FID}-plan.md]`, [] when it does not exist. */
176
+ export function planFiles(tree: string, month: string, fid: string): string[] {
177
+ const file = path.join(tree, "docs", "plans", month, `${fid}-plan.md`);
178
+ return fs.existsSync(file) ? [file] : [];
179
+ }
180
+
181
+ /**
182
+ * The plan the run worked from: `{FID}-plan.md`, its tasks per group. `source` is
183
+ * `converted` when the FID's status rows hold a `build-plan-convert` step row, else
184
+ * `file`. Undefined when no plan file exists.
185
+ */
186
+ export function planBlock(
187
+ tree: string,
188
+ month: string,
189
+ fid: string,
190
+ events: StatusEvent[],
191
+ ): PlanBlock | undefined {
192
+ const [file] = planFiles(tree, month, fid);
193
+ if (file === undefined) return undefined;
194
+ const groups = planTasks(fs.readFileSync(file, "utf-8")).map((tasks) => ({ tasks }));
195
+ const converted = events.some(
196
+ (e) => e.type === "step-done" && e.workflow === "build" && e.step === "build-plan-convert",
197
+ );
198
+ return {
199
+ source: converted ? "converted" : "file",
200
+ total: { tasks: groups.reduce((a, g) => a + g.tasks.length, 0), kb: kbOf(file) },
201
+ groups,
202
+ };
203
+ }
204
+
205
+ const TEST_ORDER_GAP =
206
+ /—\s*(no-red|late-red|red-mismatch|red-evidence-missing|test-changed)\s*—\s*not fixable/g;
207
+ /** A task `bkit challenge merge` appended: its severity field. Planned tasks carry none. */
208
+ const APPENDED_SEVERITY = /\*\*Severity:\*\*\s*(CRITICAL|HIGH|MEDIUM|LOW)\b/;
209
+
210
+ const field = (r: Row, k: string) => (r[k] === undefined ? null : r[k]);
211
+ const num = (v: unknown) => (typeof v === "number" ? v : null);
212
+ const str = (v: unknown) => (typeof v === "string" ? v : null);
213
+
214
+ /**
215
+ * Build-only facts from the run's step rows and its log folder: every verify and
216
+ * gaps-remediate round, the holistic verify, the challenge and the red-test runs. A
217
+ * verify report counts its test-order gaps only when its verdict and failure count
218
+ * match the round's row. Challenge findings are counted once a `build-challenge` row
219
+ * exists: CRITICAL / HIGH / MEDIUM from the tasks `challenge merge` appended to
220
+ * `plans`, LOW from its `build-challenge` rows among `deferrals` (the run's rows). The
221
+ * challenge block carries the latest `challenge-gate` row's size as `gate`, when one exists.
222
+ */
223
+ export function buildBlock(
224
+ rows: Row[],
225
+ logDir: string,
226
+ plans: string[],
227
+ deferrals: Array<Record<string, unknown>>,
228
+ ): BuildBlock {
229
+ const read = (file: string) => {
230
+ const f = path.join(logDir, file);
231
+ return fs.existsSync(f) ? fs.readFileSync(f, "utf-8") : null;
232
+ };
233
+ const steps = rows.filter((r) => r.type === "step-done");
234
+ const verify = steps
235
+ .filter((r) => r.step === "build-plan-verify")
236
+ .map((r) => {
237
+ const v = {
238
+ group: field(r, "group"),
239
+ attempt: field(r, "attempt"),
240
+ verdict: field(r, "verdict"),
241
+ failures: field(r, "failures"),
242
+ testOrderGaps: null as number | null,
243
+ };
244
+ const text = read(`build-plan-verify-${String(v.group)}-${String(v.attempt)}.md`);
245
+ if (
246
+ text !== null &&
247
+ /^Verdict:\s*(\w+)/m.exec(text)?.[1] === v.verdict &&
248
+ Number(/^Failures:\s*(\d+)/m.exec(text)?.[1]) === v.failures
249
+ )
250
+ v.testOrderGaps = [...text.matchAll(TEST_ORDER_GAP)].length;
251
+ return v;
252
+ });
253
+ const gapsRemediate = steps
254
+ .filter((r) => r.step === "build-plan-gaps-remediate")
255
+ .map((r) => ({
256
+ group: field(r, "group"),
257
+ attempt: field(r, "attempt"),
258
+ verdict: field(r, "verdict"),
259
+ strategy: field(r, "strategy"),
260
+ }));
261
+ const lastOf = (step: string) => steps.filter((r) => r.step === step).at(-1);
262
+ const hol = lastOf("build-plan-verify-holistic");
263
+ const ch = lastOf("build-challenge");
264
+ // `challenge-gate` rows are not fold events: read them as plain status rows.
265
+ const gate = (rows as Array<Record<string, unknown>>)
266
+ .filter((r) => r.type === "challenge-gate")
267
+ .at(-1);
268
+ let findings: NonNullable<NonNullable<BuildBlock["challenge"]>["findings"]> | null = null;
269
+ if (ch !== undefined) {
270
+ const f = { CRITICAL: 0, HIGH: 0, MEDIUM: 0, LOW: 0 };
271
+ for (const file of plans.filter((p) => fs.existsSync(p)))
272
+ for (const t of parsePlanBlocks(fs.readFileSync(file, "utf-8")).tasks) {
273
+ const sev = APPENDED_SEVERITY.exec(t.text)?.[1] as keyof typeof f | undefined;
274
+ if (sev !== undefined && sev !== "LOW") f[sev]++;
275
+ }
276
+ f.LOW = new Set(
277
+ deferrals
278
+ .filter(
279
+ (r) =>
280
+ r.kind === "deferral" &&
281
+ r.severity === "LOW" &&
282
+ (r.by as Record<string, unknown> | undefined)?.step === "build-challenge",
283
+ )
284
+ .map((r) => String(r.key)),
285
+ ).size;
286
+ findings = { total: f.CRITICAL + f.HIGH + f.MEDIUM + f.LOW, ...f };
287
+ }
288
+ return {
289
+ verify,
290
+ gapsRemediate,
291
+ holistic: hol ? { verdict: str(hol.verdict), failures: num(hol.failures) } : null,
292
+ challenge: ch
293
+ ? {
294
+ verdict: str(ch.verdict),
295
+ findings,
296
+ ...(gate === undefined
297
+ ? {}
298
+ : {
299
+ gate: {
300
+ size: str(gate.size),
301
+ linesChanged: num(gate.linesChanged),
302
+ filesChanged: num(gate.filesChanged),
303
+ skipped: gate.skipped === true,
304
+ },
305
+ }),
306
+ }
307
+ : null,
308
+ redTests: steps.filter((r) => r.step === "build-task-red").length,
309
+ };
310
+ }
311
+
312
+ /** Where Claude Code keeps the transcripts of the chats that ran a workflow. */
313
+ export interface ClaudeTranscripts {
314
+ /** The running chat's id; undefined outside Claude Code. */
315
+ sessionId: string | undefined;
316
+ /** Claude Code's config dir: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
317
+ claudeDir: string;
318
+ }
319
+
320
+ /**
321
+ * Claude Code sets `CLAUDE_CODE_SESSION_ID` in the environment of every shell command its
322
+ * session runs, so `bkit workflows close` (run by the workflow's own session) knows whose
323
+ * transcripts hold the run's subagents.
324
+ */
325
+ export function claudeTranscripts(env: NodeJS.ProcessEnv, home: string): ClaudeTranscripts {
326
+ return {
327
+ sessionId: env.CLAUDE_CODE_SESSION_ID,
328
+ claudeDir: env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"),
329
+ };
330
+ }
331
+
332
+ const SESSION_ID = /^[0-9A-Za-z][0-9A-Za-z_-]*$/;
333
+
334
+ /**
335
+ * The chat a host runs this command in, or undefined when the host names none. Claude Code
336
+ * only: it sets `CLAUDE_CODE_SESSION_ID`; nothing in this repo confirms a variable naming the
337
+ * chat on Codex, opencode, Cursor or Antigravity.
338
+ */
339
+ export function hostChat(
340
+ env: NodeJS.ProcessEnv,
341
+ ): { platform: "claude-code"; id: string } | undefined {
342
+ const id = env.CLAUDE_CODE_SESSION_ID;
343
+ return id !== undefined && SESSION_ID.test(id) ? { platform: "claude-code", id } : undefined;
344
+ }
345
+
346
+ /**
347
+ * A chat's fingerprint on `session` status rows: `fp:` + the first 12 hex of
348
+ * sha256(`<platform>:<chat id>`), the same as the harvest's fingerprint of its `chat` row key.
349
+ */
350
+ export const chatFingerprint = (platform: string, id: string) =>
351
+ `fp:${createHash("sha256").update(`${platform}:${id}`).digest("hex").slice(0, 12)}`;
352
+
353
+ /** Status rows that mark a moment rather than the end of a piece of work: step minutes skip them. */
354
+ export const MARK_ROWS: ReadonlySet<string> = new Set(["session", "owner-pause", "owner-answer"]);
355
+
356
+ /** The `session` fingerprints on the run's status rows, in row order, each once. */
357
+ export function runChats(rows: Row[]): string[] {
358
+ const out: string[] = [];
359
+ for (const r of rows as Array<Record<string, unknown>>)
360
+ if (r.type === "session" && typeof r.session === "string" && !out.includes(r.session))
361
+ out.push(r.session);
362
+ return out;
363
+ }
364
+
365
+ /** One Claude Code subagent transcript's model calls: `[ms, context]` each, or null when unreadable. */
366
+ function subagentCalls(file: string): Array<[number, number]> | null {
367
+ const read = readTextFile(file);
368
+ if (!read.ok) return null;
369
+ const calls: Array<[number, number]> = [];
370
+ for (const line of read.text.split("\n")) {
371
+ const parsed = line.trim() === "" ? null : parseJson(line);
372
+ if (parsed === null || !parsed.ok) continue;
373
+ const d = parsed.value as Record<string, unknown> | null;
374
+ if (d === null || typeof d !== "object") continue;
375
+ const m = d.message as Record<string, unknown> | undefined;
376
+ // `<synthetic>`: a message Claude Code wrote itself (an API error notice), not a model call.
377
+ if (d.type !== "assistant" || typeof m !== "object" || m === null) continue;
378
+ if (m.model === "<synthetic>") continue;
379
+ const at = msOf(d.timestamp);
380
+ if (!Number.isFinite(at)) continue;
381
+ const u = (m.usage ?? {}) as Record<string, unknown>;
382
+ const n = (k: string) => (typeof u[k] === "number" ? (u[k] as number) : 0);
383
+ calls.push([
384
+ at,
385
+ n("input_tokens") + n("cache_creation_input_tokens") + n("cache_read_input_tokens"),
386
+ ]);
387
+ }
388
+ return calls;
389
+ }
390
+
391
+ /**
392
+ * The run's subagents' context peaks per agent type, from every Claude Code chat that ran
393
+ * it: the chat running the close, and each chat whose fingerprint `chats` holds (the run's
394
+ * `session` rows). Transcripts: `<claudeDir>/projects/<project>/<session>/subagents/agent-*.jsonl`,
395
+ * each with its `agent-*.meta.json` naming the agent type (`unknown` without one). Each model
396
+ * call goes by its own timestamp: a subagent counts in `runs` when one of its calls falls in
397
+ * [startMs, endMs], and `peak` is the largest of those calls. Context of one model call =
398
+ * input + cache write + cache read tokens, the same sum the harvest's `contextPeak` takes.
399
+ * Undefined when no chat is known, no transcript is found or no subagent called the model
400
+ * in the run. Never throws: a folder or transcript that cannot be read counts as absent.
401
+ *
402
+ * Claude Code only. The other hosts bkit renders for record nothing here:
403
+ * - Cursor keeps no token counts in its local chats (the harvest reads them and finds none).
404
+ * - Codex (`~/.codex/sessions/.../rollout-*.jsonl`, `token_count` events) and opencode
405
+ * (`~/.local/share/opencode/opencode.db`) keep token counts, but nothing in this repo
406
+ * confirms an environment variable naming the running session, so a close cannot tell its
407
+ * own run's transcripts from another chat's.
408
+ * - Antigravity keeps protobuf in SQLite whose token fields nothing in this repo documents.
409
+ */
410
+ export function agentContextBlock(
411
+ startMs: number,
412
+ endMs: number,
413
+ src: ClaudeTranscripts,
414
+ chats: readonly string[] = [],
415
+ ): ContextBlock | undefined {
416
+ const sid = src.sessionId !== undefined && SESSION_ID.test(src.sessionId) ? src.sessionId : null;
417
+ const wanted = new Set(chats);
418
+ if (sid === null && wanted.size === 0) return undefined;
419
+ const projects = path.join(src.claudeDir, "projects");
420
+ const top = readDirNames(projects);
421
+ if (!top.ok) return undefined;
422
+ const files: string[] = [];
423
+ for (const p of top.names.sort()) {
424
+ const names = readDirNames(path.join(projects, p));
425
+ for (const name of names.ok ? names.names.sort() : []) {
426
+ if (!SESSION_ID.test(name)) continue;
427
+ if (name !== sid && !wanted.has(chatFingerprint("claude-code", name))) continue;
428
+ const dir = path.join(projects, p, name, "subagents");
429
+ const subs = readDirNames(dir);
430
+ for (const f of subs.ok ? subs.names.sort() : [])
431
+ if (f.endsWith(".jsonl")) files.push(path.join(dir, f));
432
+ }
433
+ }
434
+ const byAgent: ContextBlock["byAgent"] = {};
435
+ for (const file of files) {
436
+ const inRun = (subagentCalls(file) ?? []).filter(([at]) => at >= startMs && at <= endMs);
437
+ if (inRun.length === 0) continue;
438
+ const meta = readJsonFile(file.slice(0, -".jsonl".length) + ".meta.json");
439
+ const type = meta.ok ? (meta.value as Record<string, unknown> | null)?.agentType : undefined;
440
+ const a = (byAgent[typeof type === "string" && type !== "" ? type : "unknown"] ??= {
441
+ peak: 0,
442
+ runs: 0,
443
+ });
444
+ a.runs++;
445
+ a.peak = Math.max(a.peak, ...inRun.map(([, c]) => c));
446
+ }
447
+ return Object.keys(byAgent).length === 0 ? undefined : { host: "claude-code", byAgent };
448
+ }
449
+
450
+ /**
451
+ * After the close's CI dispatch: append the run's `outcome` row again with the
452
+ * dispatch added to `ci`, and `ending` `close-failed` when CI never started
453
+ * (`unresolved`). The run is the last `workflow-done` row of `workflow` in
454
+ * `status`; its `parentSha` names the outcome row. The newer row supersedes the
455
+ * close's under fold. Best-effort: a missing row or a refused append is logged.
456
+ */
457
+ export function restateOutcome(
458
+ tree: string,
459
+ status: string,
460
+ workflow: string,
461
+ dispatch: Record<string, unknown>,
462
+ log: (m: string) => void,
463
+ ): boolean {
464
+ const done = readStatusEvents(status)
465
+ .filter((e) => e.type === "workflow-done" && e.workflow === workflow)
466
+ .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0))
467
+ .at(-1) as Record<string, unknown> | undefined;
468
+ const sha = done?.parentSha;
469
+ if (typeof sha !== "string") {
470
+ log(`[bkit-telemetry] no ${workflow} workflow-done row with parentSha — outcome not restated`);
471
+ return false;
472
+ }
473
+ const stats = path.join(tree, ".bkit", "stats.jsonl");
474
+ const outcome = fs.existsSync(stats)
475
+ ? [...foldFrom([stats]).state.values()]
476
+ .filter(
477
+ (e): e is Extract<TelemetryEvent, { kind: "outcome" }> =>
478
+ e.kind === "outcome" && e.by?.workflow === workflow && e.run?.parentSha === sha,
479
+ )
480
+ .at(-1)
481
+ : undefined;
482
+ if (outcome === undefined) {
483
+ log(
484
+ `[bkit-telemetry] no ${workflow} outcome row for ${sha.slice(0, 12)} — outcome not restated`,
485
+ );
486
+ return false;
487
+ }
488
+ const { schema: _s, ts: _t, bkit: _b, ...draft } = outcome;
489
+ const entry = ciEntry(dispatch);
490
+ const ci = [...(draft.ci ?? []), entry];
491
+ try {
492
+ appendLedgerRows(tree, "stats", [
493
+ { ...draft, ending: entry.status === "unresolved" ? "close-failed" : "done", ci },
494
+ ]);
495
+ return true;
496
+ } catch (err) {
497
+ // Telemetry never gates a dispatch: report the refused append and carry on.
498
+ log(`[bkit-telemetry] outcome not restated: ${(err as Error).message}`);
499
+ return false;
500
+ }
501
+ }