@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -3,28 +3,70 @@
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** How to format a new row for any bkit JSONL ledger (`docs/deferrals.jsonl`, `docs/failures.jsonl`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `.bkit/issues.jsonl`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`). Codec: `.bkit/core/engine/ledgers/telemetry.ts`. Which `kind` → which ledger + workflow write timing: `.bkit/workflows.md` § Telemetry Ledgers.
6
+ > **Purpose:** How to format a new row for any bkit JSONL ledger (`docs/deferrals.jsonl`, `docs/failures.jsonl`, `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `.bkit/issues.jsonl`, `.bkit/friction.jsonl`, `.bkit/stats.jsonl`). The codec is `.bkit/core/engine/ledgers/telemetry.ts`. Which `kind` goes to which ledger, and when each workflow writes it, is in `.bkit/workflows.md` § Telemetry Ledgers.
7
7
  >
8
8
  > **Rules:**
9
9
  >
10
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
- > - Describe current state / rules, not reasons / history; state what to do, not why.
12
- > - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
13
- > - One row per line. never edit or reorder a prior line — row STATE changes via same-`key` append (§ Updating a Row); sole exception: the install / upgrade schema migration (§ Versioning).
14
- > - Before append: read file. Skip only if identity-matching row exists and nothing changed — changed field = update, not duplicate.
15
- > - Rows removed only by bkit's harvest: every `.bkit/friction.jsonl` row, `chat` / `run` rows in `.bkit/stats.jsonl` (§ Friction Is a Drained Queue).
16
- > - Best-effort append — always exit 0; never gate workflows on telemetry success.
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - This file ships to every project that installs bkit. Describe the current setup only.
12
+ > - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
13
+ > - Write one row per line.
14
+ > - NEVER edit, reorder or delete a prior line. Change a row through a same-`key` append (§ Updating a Row). The only exceptions are the `bkit install` / `bkit upgrade` schema migration (§ Versioning), `bkit ledgers compact` (§ Compaction), and bkit's harvest (`pnpm harvest`, bkit repo only), which prunes a `.bkit/friction.jsonl` row or a `chat` / `run` row of `.bkit/stats.jsonl` only after the exact row is stored in `harvest/` and read back, and never prunes a malformed line (§ Friction Is a Drained Queue).
15
+ > - Before you append, read the file. Skip the append only if a row with the same identity exists and nothing has changed. A changed field makes the new row an update, not a duplicate.
16
+ > - Appends are best-effort: always exit 0. Never gate a workflow on telemetry success.
17
+
18
+ ## Read Idiom
19
+
20
+ **Engine readers:** `normalize()` and `fold()` in `.bkit/core/engine/ledgers/telemetry.ts` handle older schemas and current-state reads across all telemetry kinds.
21
+
22
+ - **Identity:** Group by § Identity / Dedup. A bare `key` suffices only within one keyed kind and one repo.
23
+ - **Winner:** Keep the highest numeric `ts` per identity; the later line wins a tie.
24
+ - **Filters:** Apply status and query filters after folding, so superseded rows stay superseded. Decisions / knowledge default to `ACTIVE`; open failures / deferrals include `TRIAGED` and exclude `CLOSED` (§ Updating a Row).
25
+ - **History:** Retain the rows needed for the requested time range instead of reducing them to current state.
26
+ - **Workflow logs:** Read `status.jsonl` through the workflow's status commands. These are event histories with their own replay rules, outside this fold.
27
+
28
+ **Humans and scripts:** This Python example folds decisions and knowledge separately, each containing one keyed kind from one repo, then prints active rows. Run from the repo root; output is stdout only.
29
+
30
+ ```python
31
+ import json
32
+ import math
33
+ from pathlib import Path
34
+
35
+
36
+ def latest_rows(records):
37
+ latest = {}
38
+ for row in records:
39
+ key, timestamp = row["key"], row["ts"]
40
+ if not isinstance(key, str) or not key:
41
+ raise ValueError("Ledger key must be a nonempty string")
42
+ if isinstance(timestamp, bool) or not isinstance(timestamp, (int, float)) or not math.isfinite(timestamp):
43
+ raise ValueError("Ledger ts must be a finite number")
44
+ previous = latest.get(key)
45
+ if previous is None or timestamp >= previous["ts"]:
46
+ latest[key] = row
47
+ return latest
48
+
49
+
50
+ for name in ["decisions", "knowledge"]:
51
+ records = [json.loads(line) for line in Path(f"docs/{name}.jsonl").read_text().splitlines() if line.strip()]
52
+ for row in latest_rows(records).values():
53
+ if row.get("status", "ACTIVE") == "ACTIVE":
54
+ print(json.dumps(row))
55
+ ```
56
+
57
+ - **First row:** Handle a new identity separately; never compare its numeric `ts` with a string default.
58
+ - **Failures:** Report missing files, invalid JSON and invalid `key` / `ts` fields as read failures, not empty results.
17
59
 
18
60
  ## Write Idiom
19
61
 
20
- **Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`; rows = JSON array without `schema` / `ts` / `bkit`.
62
+ **Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`. The rows are a JSON array without `schema` / `ts` / `bkit`.
21
63
 
22
- - **Fills:** `schema: 3`, a minted `ts` per row, `repo` when absent, `bkit.version` from `.bkit/version`.
23
- - **Checks** every row (validation, author vs § Ledgers & Writers) before writing any; one refused row → exit 8, nothing written.
24
- - **Refused:** supplied `schema` / `ts` / `bkit`; flat `bkitVersion` / `workflow` / `step` / `subagent` / `model` (they live in `bkit` / `by`); a kind the ledger does not take; a total not matching its parts.
25
- - `--ledger=stats` takes `compliance` / `counter` / `outcome` (`bkit workflows close` writes through it).
26
- - Subagent with no shell → hands its rows to the orchestrator as that JSON, `by.subagent` and `by.model` already set.
27
- - `feature` rows: `bkit roadmap feature`. `chat` / `run` rows: bkit's harvest script, into `harvest/stats.jsonl` only.
64
+ - **Fills:** `schema: 3`, a minted `ts` per row, `repo` when absent, and `bkit.version` from `.bkit/version`. On `deferral` / `failure` / `knowledge` / `decision` rows, it also fills `firstTs` and `updates` from the entry's earlier rows (§ Compaction), replacing any supplied values.
65
+ - **Checks** every row before writing any: validation, and the author against § Ledgers & Writers. One refused row → exit 8, and nothing is written.
66
+ - **Refused:** a supplied `schema` / `ts` / `bkit`; a flat `bkitVersion` / `workflow` / `step` / `subagent` / `model`, since those live in `bkit` / `by`; a kind the ledger does not take; and a total that does not match its parts.
67
+ - `--ledger=stats` takes `compliance` / `counter` / `outcome` rows. `bkit workflows close` writes through it.
68
+ - A subagent with no shell hands its rows to the orchestrator as that JSON, with `by.subagent` and `by.model` already set.
69
+ - `bkit roadmap feature` writes `feature` rows, and fills `firstTs` and `updates` the same way. A `--row` that already carries `updates` (a row an earlier call printed) is appended byte for byte. bkit's harvest script writes `chat` / `run` rows, into `harvest/stats.jsonl` only.
28
70
 
29
71
  **Humans and scripts:** the `jq` idiom:
30
72
 
@@ -33,30 +75,33 @@ jq -c -n '{ schema: 3, ts: null, kind: "deferral", repo: $REPO, bkit: { version:
33
75
  >> "$FILE" || echo "[bkit-telemetry] append failed: $FILE"
34
76
  ```
35
77
 
36
- - **`ts`:** Unix ms, always minted by `jq`'s `now` AT append TIME — `jq '… | .ts = (now*1000|floor)'`. The `ts: null` placeholder holds field order only; the pipe overwrites it. Drop the pipe and the row fails validation instead of landing a fake value — never seed the placeholder with a number.
37
- - **`ts` is never a literal.** Not hand-typed, not copied off an example row or the line above, not `date +%s%3N` (BSD/macOS incompatible). A fabricated past `ts` is indistinguishable from a real one and silently reorders the last-wins fold that every reader, the harvest, and every age report depend on. Whole-second values (`ts % 1000 == 0`) fail the live-ledger gate — a real mint is never round: `bkit ledgers append` moves one 1 ms on; a `jq` append that lands on one is re-run.
38
- - **Log prefix:** every telemetry log line starts `[bkit-telemetry]` — load-bearing for log-drain grep.
78
+ - **`ts`:** Unix ms, always minted by `jq`'s `now` at append time: `jq '… | .ts = (now*1000|floor)'`. The `ts: null` placeholder only holds the field's place in the order, and the pipe overwrites it. Without the pipe, the row fails validation instead of landing a fake value. Never seed the placeholder with a number.
79
+ - **`ts` is never a literal.** Do not hand-type it, copy it from an example row or the line above, or take it from `date +%s%3N`, which does not work on BSD / macOS. A fabricated past `ts` looks the same as a real one, and it silently reorders the last-wins fold that every reader, the harvest and every age report depend on. Whole-second values (`ts % 1000 == 0`) fail the live-ledger gate, because a real mint is never round: `bkit ledgers append` moves such a value 1 ms on, and a `jq` append that lands on one is re-run.
80
+ - **`firstTs` / `updates`:** Omit them. The next compaction stamps them (§ Compaction).
81
+ - **Log prefix:** Every telemetry log line starts with `[bkit-telemetry]`, because log-drain greps match on it.
39
82
 
40
83
  ## Ledgers & Writers
41
84
 
42
- One file per `kind`; writers:
85
+ Each `kind` goes to one file. Its writers:
43
86
 
44
87
  <!-- prettier-ignore -->
45
88
  | Kind | File | Written by |
46
89
  | --- | --- | --- |
47
- | `compliance` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (its grader, one row per rule) |
48
- | `outcome` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (one row per workflow run, keyed by `repo`+`by.workflow`+`run.parentSha`); re-appended by the close's CI dispatch (§ Per-Kind Fields) |
49
- | `counter` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (attempt counters) |
90
+ | `compliance` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (its grader, one row per rule); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
91
+ | `outcome` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (one row per workflow run, keyed by `repo`+`by.workflow`+`run.parentSha`); re-appended by the close's CI dispatch (§ Per-Kind Fields); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
92
+ | `counter` | `.bkit/stats.jsonl` | `bkit workflows close` of design / plan / build / debug / ship (attempt counters); utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
50
93
  | `chat` | `harvest/stats.jsonl` (bkit repo only) | bkit's harvest script: per agent chat on the maintainer's machine, any repo or host |
51
94
  | `run` | `harvest/stats.jsonl` (bkit repo only) | Same script: per workflow run in the run logs of every repo a chat ran in |
52
- | `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship) on observed friction |
53
- | `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator), build orchestrator (`LOW` challenge finding → `low-severity`, through `bkit challenge merge`), ship orchestrator (assumed accept nobody confirmed → `needs-decision`, through `bkit decisions pending --defer`) |
95
+ | `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship / auto) on observed friction; utility orchestrator (a direct chat outside any workflow that meets friction); the engine itself, as the active workflow, on a bkit command's undeclared non-zero exit (`category: "tool-failure"`, `scope: "bkit-repo"`, in the active run's own book root; `BKIT_ENGINE_JOURNAL=off` disables it), and from `status row --type=owner-pause` on each owner pause (`category: "human-confirm"`, same book root and kill switch) |
96
+ | `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator), build orchestrator (`LOW` challenge finding → `low-severity`, through `bkit challenge merge`), ship orchestrator (assumed accept nobody confirmed → `needs-decision`, through `bkit decisions pending --defer`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
54
97
  | `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@bkit-audit-generate` (`MEDIUM`+ findings; rerun closes rows it no longer finds); `@bkit-utility-update-failures` (close / triage / locator) |
55
- | `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-plan-execute`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct) |
56
- | `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-plan-update` (decision changed by review), `@bkit-utility-update-decisions` (supersede / correct), build orchestrator (Decision Pause accept), plan orchestrator (open question answered after close), ship orchestrator (assumed accept confirmed by the owner, through `bkit decisions apply --by=owner`); orchestrators ONLY after explicit human approval |
98
+ | `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-plan-tests`, `@bkit-build-plan-tasks`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct), utility orchestrator (a direct chat outside any workflow, the owner deciding in it) |
99
+ | `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-plan-update` (decision changed by review), `@bkit-utility-update-decisions` (supersede / correct), build orchestrator (Decision Pause accept), design orchestrator (owner's answer to an open question after close), plan orchestrator (open question answered after close), ship orchestrator (assumed accept confirmed by the owner, through `bkit decisions apply --by=owner`), utility orchestrator (a direct chat outside any workflow, the owner deciding in it); orchestrators ONLY after explicit human approval |
57
100
  | `feature` | `.bkit/issues.jsonl` | design / plan / build / debug orchestrators at their phase close; ship Step 6 into the worktree ledger (rides the PR); `ABANDONED` only by a human, or an agent on explicit human instruction |
58
101
 
59
- **Writers are exhaustive:** only agents listed as writers for a given kind are allowed to write that specific kind; no exceptions. For the five `bkit ledgers append` kinds this column is `KIND_WRITERS` in `.bkit/core/engine/ledgers/telemetry.ts`, the check `append` runs; `telemetry.test.ts` fails when either side changes alone.
102
+ **Writers are exhaustive:** Only the agents listed as writers for a kind may write that kind, with no exceptions. For the five `bkit ledgers append` kinds, this column is `KIND_WRITERS` in `.bkit/core/engine/ledgers/telemetry.ts`, the check that `append` runs. `telemetry.test.ts` fails when either side changes alone.
103
+
104
+ **Stats readers keep `utility` rows apart:** `bkit stats` and the harvest report read `outcome`, `counter` and `compliance` rows in two groups: rows a workflow wrote, and rows a direct chat wrote (`by.workflow` `utility`). Each figure (run counts, durations, change size vs failures, attempt-counter trust, compliance rates, build challenge size, agent context peaks) is computed once per group, and no figure adds the two together, because no workflow run stands behind a `utility` row. The harvest's run check reads workflow `outcome` rows only, since a `utility` row has no run log.
60
105
 
61
106
  ## Generic Fields (all kinds)
62
107
 
@@ -67,23 +112,25 @@ Every row opens with the same top section, in this order:
67
112
  | --- | --- | --- |
68
113
  | `schema` | `3` | Row format. `2` = older `plan` block (§ Shared Blocks); row without it = older shape, read through `normalize()` (§ Versioning). |
69
114
  | `ts` | `number` | Unix milliseconds — primary id. Minted at append, never a literal (§ Write Idiom). |
115
+ | `firstTs` | `number?` | `deferral` / `failure` / `knowledge` / `decision` / `feature` only: `ts` of the entry's first row, never later than `ts`. Filled by the writer and by compaction (§ Compaction). |
116
+ | `updates` | `number?` | Same kinds: rows the entry has had, this one included (integer >= 1). Same-`ts` rows count once. |
70
117
  | `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`, `chat`, `run`. |
71
118
  | `key` | `string?` | Keyed kinds only (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature` / `chat` / `run`). See § Key & References. |
72
119
  | `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`; its fingerprint on `chat` / `run` rows (§ Per-Kind Fields). |
73
120
  | `bkit` | `{version}` | `version` = bkit version that emitted the row (`null` on `chat` / `run` when none found). `chat` adds its bkit-use fields. |
74
- | `by` | `{workflow?, step, subagent?, model?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `audit`; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
121
+ | `by` | `{workflow?, step, subagent?, model?}` | Who wrote it — § Who Wrote It. `workflow`: `design` / `plan` / `build` / `debug` / `ship` / `auto` / `audit`; `utility` for a direct chat outside any workflow; `chat-stats` on `chat` (the harvest script's scan); the run's workflow on `run`. |
75
122
  | `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
76
123
 
77
- Values, every kind:
124
+ Values in every kind:
78
125
 
79
- - **Absent vs `null`:** absent = does not apply; `null` = applies, could not be measured.
80
- - **Units:** durations in minutes, unit in the name (`totalMinutes`, `activeMinutes`); timestamps unix ms.
81
- - **Totals beside parts:** fixed parts (`code` / `tests` / `docs`) → `total` next to them; open-ended parts → `total` next to a `by<What>` map (`byStep`, `byModel`, `byAgent`, `byTool`, `byCategory`, `byVerb`). Writer computes every total from its parts just before the write; `validate()` refuses a row whose total does not match (minute totals within 0.1 per part).
82
- - **Run join key:** `run.parentSha` = HEAD at the run's close, also on its `workflow-done` status row; every `compliance` / `counter` / `outcome` row of one run carries it; `chat` carries `run.parentShas`.
126
+ - **Absent vs `null`:** Absent = the field does not apply. `null` = it applies but could not be measured.
127
+ - **Units:** Durations are in minutes, with the unit in the name (`totalMinutes`, `activeMinutes`). Timestamps are unix ms.
128
+ - **Totals beside parts:** Fixed parts (`code` / `tests` / `docs`) have a `total` next to them. Open-ended parts have a `total` next to a `by<What>` map (`byStep`, `byModel`, `byAgent`, `byTool`, `byCategory`, `byVerb`). The writer computes every total from its parts just before the write. `validate()` refuses a row whose total does not match, with minute totals allowed within 0.1 per part.
129
+ - **Run join key:** `run.parentSha` = HEAD at the run's close. It is also on the run's `workflow-done` status row. Every `compliance` / `counter` / `outcome` row of one run carries it, and `chat` carries `run.parentShas`.
83
130
 
84
131
  ## Shared Blocks
85
132
 
86
- Same name, same shape on `outcome` and `run`:
133
+ These blocks have the same name and the same shape on `outcome` and `run`:
87
134
 
88
135
  <!-- prettier-ignore -->
89
136
  | Block | Shape |
@@ -93,7 +140,7 @@ Same name, same shape on `outcome` and `run`:
93
140
  | `steps` | `{total:{n,totalMinutes,activeMinutes?}, byStep:{<step>:{n,totalMinutes,activeMinutes?}}}`; minutes since the previous status row, `session` / `owner-pause` / `owner-answer` rows skipped (they mark a chat or an owner wait, not a step); time before the first step only in `time.totalMinutes`. `activeMinutes` on `run` only. |
94
141
  | `ci` | `[{status,reason,attempts}]`, one per close-step CI dispatch (`status` e.g. `dispatched` / `unresolved`). |
95
142
  | `plan` | `{source:"file"\|"converted", total:{tasks,kb}, groups:[{tasks:[{tests,testFiles}]}]}`. `converted` = the build rewrote its input into `{FID}-plan.md` (a `build-plan-convert` status row). `total.tasks` = the sum over `groups`; `tests` / `testFiles` `null` = task has no `TEST FIRST`. `schema: 2` rows hold `source:"file"\|"brief"` (`brief` = no plan file, carries only `source`), `subPlans:[{kb, tasks}]` in place of `groups` and `complexity:{verdict,tasksChecked,reasons?}` — read as stored; the `workflowTelemetry` baseline counts `brief` as `converted`. |
96
- | `build` | `{verify:[{group,attempt,verdict,failures,testOrderGaps}], gapsRemediate:[{group,attempt,verdict,strategy}], holistic:{verdict,failures}\|null, challenge:{verdict, findings:{total,CRITICAL,HIGH,MEDIUM,LOW}\|null, gate?:{size,linesChanged,filesChanged,skipped}}\|null, redTests}`; `gate` = the run's latest `challenge-gate` status row (`bkit challenge gate`; `skipped` = challenge-1 left out on a small change), absent when the run has none; `findings` = plan tasks `bkit challenge merge` appended (by `**Severity:**`) plus its `LOW` deferral rows this run (`by.step` `build-challenge`); `redTests` = `build-task-red` step rows. |
143
+ | `build` | `{verify:[{group,attempt,verdict,failures}], gapsRemediate:[{group,attempt,verdict,strategy}], holistic:{verdict,failures}\|null, challenge:{verdict, findings:{total,CRITICAL,HIGH,MEDIUM,LOW}\|null, gate?:{size,linesChanged,filesChanged,skipped}}\|null, redTests}`; `gate` = the run's latest `challenge-gate` status row (`bkit challenge gate`; `skipped` = challenge-1 left out on a small change), absent when the run has none; `findings` = plan tasks `bkit challenge merge` appended (by `**Severity:**`) plus its `LOW` deferral rows this run (`by.step` `build-challenge`); `redTests` = `build-tests-red` step rows. |
97
144
 
98
145
  ## Per-Kind Fields
99
146
 
@@ -101,15 +148,15 @@ Same name, same shape on `outcome` and `run`:
101
148
  | Kind | Fields (beyond the top section) |
102
149
  | --- | --- |
103
150
  | `counter` | `run:{parentSha}`, `counter:{name, value:number, source:"model-self-report"\|"shell-bus"}`. |
104
- | `outcome` | `run:{parentSha, pr?}` (`pr` ship-only), `time` (`null` = no start row), `ending:"done"\|"close-failed"` (`close-failed` = work done, its close's CI never started), `lines?\|null`, `steps?`, `ci?`, `ledgers:{deferrals:{repo,added?}, failures:{repo,added?}, friction:{added?}}` (`repo` = the repo's distinct folded entries at close, not lines; `added` = distinct keys this run added — rows of `by.workflow` at or after its start; absent when the start is unknown), `plan?` (plan / build / ship), `build?` (build), `context?:{host:"claude-code", byAgent:{<agent type>:{peak, runs}}}` (the run's subagents per agent type: `runs` = subagents with a model call in the run, `peak` = largest input + cache write + cache read tokens of one model call in the run; read at close from the subagent transcripts of the closing Claude Code chat and of every chat the run's `session` status rows name, each call counted when its own timestamp falls between the run's start and the close; absent on other hosts or with no data; `bkit stats` judges peaks against 160,000 tokens), `ship?:{coverage?:{unit?,integration?,e2e?}}` (each `{lines,branches,functions,statements}` %; a tier absent when its coverage report is not produced). The close's CI dispatch re-appends it: dispatch added to `ci`, `ending` `close-failed` when CI never started; newer row supersedes (§ Identity / Dedup). |
151
+ | `outcome` | `run:{parentSha, pr?}` (`pr` ship-only), `time` (`null` = no start row), `ending:"done"\|"close-failed"\|"held"` (`close-failed` = work done, its close's CI never started; `held` = a local build that published nothing), `publish?:boolean` (a build's resolved publish value; `false` with `held`), `lines?\|null`, `steps?`, `ci?`, `ledgers:{deferrals:{repo,added?}, failures:{repo,added?}, friction:{added?}}` (`repo` = the repo's distinct folded entries at close, not lines; `added` = distinct keys this run added — rows of `by.workflow` at or after its start; absent when the start is unknown), `plan?` (plan / build / ship), `build?` (build), `context?:{host:"claude-code", byAgent:{<agent type>:{peak, runs}}}` (the run's subagents per agent type: `runs` = subagents with a model call in the run, `peak` = largest input + cache write + cache read tokens of one model call in the run; read at close from the subagent transcripts of the closing Claude chat and of every chat the run's `session` status rows name, each call counted when its own timestamp falls between the run's start and the close; absent on other hosts or with no data; `bkit stats` judges peaks against 160,000 tokens), `ship?:{coverage?:{unit?,integration?,e2e?}}` (each `{lines,branches,functions,statements}` %; a tier absent when its coverage report is not produced). The close's CI dispatch re-appends it: dispatch added to `ci`, `ending` `close-failed` when CI never started; newer row supersedes (§ Identity / Dedup). |
105
152
  | `compliance` | `run:{parentSha}`, `rule:{id, verdict:"pass"\|"fail"\|"n/a", evidence?}` (`evidence` on fail rows). |
106
153
  | `friction` | `key`, `category` (§ Categories), `scope:"bkit-repo"\|"consumer"\|"universal"`, `severity`, `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?` (see § Updating a Row), `confidence?:number`, `lastConfirmed?:number`, `recurrenceCount?:number`. |
107
154
  | `deferral` | `key`, `type:"issue"\|"feature"`, `category` (§ Categories), `severity`, `reason` (§ Deferral Reason), `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"?`. |
108
- | `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky/intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
155
+ | `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky / intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
109
156
  | `knowledge` | `key`, `summary`, `description?`, `rootCause?`, `remediation?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
110
157
  | `decision` | `key`, `summary`, `description?`, `rationale?`, `alternatives?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
111
- | `chat` | `key` (`<platform>:<session id>`); `bkit` adds `versionSource:"repo-history"\|"prompt"\|"none"` (`prompt` = an expanded workflow command's managed marker), `via` (`command` / `subagent`; empty = no bkit; `command` only when the chat ran a `/bkit-*` command itself), `workflows`, `prompts` (bkit prompt families, audit and utility included), `cli:{total, byVerb}`; `session:{platform, id, hostVersion?, entrypoint?, prompts}` (`platform` `claude-code` / `codex` / `opencode` / `cursor` / `antigravity`; `prompts` = messages the human typed); `time:{start, end, totalMinutes, activeMinutes, spans, lastActivity}` (`ts` = `end`; `spans` = `[[startMs,endMs]]`, chat + subagents, split at gaps over 5 min; `activeMinutes` = their sum; `lastActivity` = last write to the chat's files); `issue:{id, all, mentioned, source:"command"\|"summary"\|"mention"\|"none"}` (fingerprints; named only in the host's summary of an earlier chat → `summary`); `run:{parentShas}` (printed by `bkit workflows close` — exact join to `run.parentSha`); `effort` (turns per level); `usage:{total:{turns, tokens, context:{start,peak}, compactions}, main:{turns, tokens, context:{peak}, compactions, mix}, byModel:{<model>:{turns, tokens}}, byRun:{<run key>:{main:{turns, tokens}, agents:{turns, tokens}}}\|null}` (`tokens` = `{input, cacheWrite, cacheRead, output, outputEst, read}`, `read` = the three sent types; `mix` = calls by kind `{read, edit, grep, shellRead, shellList, tests, serena}`; `byRun` = the chat's model calls per run it worked on — a run's `session` rows name the chat, or same repo, the run's issue in `issue.all` and overlapping time — each call to the run whose first-to-last status row window holds its time, the later-started run when two do; `{}` = no run, `null` = a call has no time, e.g. Cursor, Antigravity); `agents:{total:{n, errors}, byAgent:{<agent type>:{n, errors, instances:[{turns, contextPeak, contextAt10}], usage, mix, planReads:{full, partial}}}}` (`contextAt10` = context read by the instance's 10th model call, `null` under 10; `planReads` = reads of a `docs/plans/<YYYYMM>/<FID>-plan(-N).md` file, `partial` = a line range or `sed` / `head` / `tail`); `tools:{total:{calls, errors}, byTool:{<tool>:{calls, errors, byCategory?}}, filesRead}`; `scan:{files, bytes, settled, tokensRecorded}` (`settled` = unchanged for the settle window, `false` = open: counted and marked, not in medians; `tokensRecorded` false = host records none, e.g. Cursor). New same-`key` row when `scan.bytes` or `scan.settled` changes, or the stored row has no `usage.byRun`. `schema: 2` chat rows hold `ctx` / `ctxPeak`; readers rename them to `context` / `contextPeak`. `repo` and issues are fingerprints: `fp:` + 12 hex of sha256(`owner/repo` / `owner/repo#N`); no paths, branch names or prompt text. Field reference: the script's header. |
112
- | `run` | `key` (`<fid>:<workflow>:<start>`); `run:{fid, issue, n, parentSha, parentShas}` (`fid` = fingerprint of `owner/repo:<FID>`; `issue` = fingerprint of the FID's leading number, else `null`; `n` = nth run of that workflow in the log; `parentSha` = its last `workflow-done` row's, else its last close step's, else `null` — exact join to the run's `outcome` / `counter` / `compliance`; `parentShas` = every commit its status rows name); `time:{start, end, totalMinutes, activeMinutes, activeFrom:{chats,bytes}, lastActivity}` (first / last status row; `activeMinutes` = run time inside the spans of counted chats naming its issue by command or summary, `null` = none yet; `lastActivity` = log's last row, after-end rows included); `ending:"done"\|"close-failed"\|"failed"\|"decision-pause"\|"stopped"` (last end row; `close-failed` = after `workflow-done` only the close failed: last close's CI dispatch `unresolved`, or a `workflow-failed` row with no close after it; no end row → `decision-pause` if its `build-decision-*.md` is `Status: OPEN`, else `stopped`); `ci`, `steps` (with `activeMinutes`), `lines` (build, debug), `plan` (a feature's last plan run), `build` (build; `testOrderGaps` `null` = round's report gone — an earlier build's counts only if written before the next build started) — § Shared Blocks; `owner:{waitBeforeMinutes, total:{stops, minutes}, stops:[{minutes, open, reason}]}` (owner waits from `owner-pause` → next `owner-answer` status rows, pauses before an answer joined into one stop; `open` = no answer yet, `minutes: null`; `reason` `decision` / `grill` / `draft`; `waitBeforeMinutes` = the same log's previous run's last row to this run's first, `null` for the first); `usage:{total, main, agents}\|null` (each `{turns, tokens}`; sum of the matched chats' `usage.byRun[key]`; `null` = no chat matched, or one has no `byRun`); `scan:{rows, afterEnd, settled}` (`afterEnd` = rows after the end row, e.g. a hand rewind; `settled` = last row older than the settle window). `ts` = scan time. New same-`key` row when `scan.rows`, `time.activeFrom`, `scan.settled`, `usage` or `owner` changes. No limits applied; no FID text, paths or branch names. |
158
+ | `chat` | `key` (`<platform>:<session id>`); `bkit` adds `versionSource:"repo-history"\|"prompt"\|"none"` (`prompt` = an expanded workflow command's managed marker), `via` (`command` / `subagent`; empty = no bkit; `command` only when the chat ran a `/bkit-*` command itself), `workflows`, `prompts` (bkit prompt families, audit and utility included), `cli:{total, byVerb}`; `session:{platform, id, hostVersion?, entrypoint?, prompts}` (`platform` `claude-code` / `codex` / `opencode` / `cursor` / `antigravity`; `prompts` = messages the human typed); `time:{start, end, totalMinutes, activeMinutes, spans, lastActivity}` (`ts` = `end`; `spans` = `[[startMs,endMs]]`, chat + subagents, split at gaps over 5 min; `activeMinutes` = their sum; `lastActivity` = last write to the chat's files); `issue:{id, all, mentioned, source:"command"\|"summary"\|"mention"\|"none"}` (fingerprints; named only in the host's summary of an earlier chat → `summary`); `run:{parentShas}` (printed by `bkit workflows close` — exact join to `run.parentSha`); `effort` (turns per level); `usage:{total:{turns, tokens, context:{start,peak}, compactions}, main:{turns, tokens, context:{peak}, compactions, mix}, byModel:{<model>:{turns, tokens}}, byRun:{<run key>:{main:{turns, tokens}, agents:{turns, tokens}}}\|null}` (`tokens` = `{input, cacheWrite, cacheRead, output, outputEst, read}`, `read` = the three sent types; `mix` = calls by kind `{read, edit, grep, shellRead, shellList, tests, serena}`; `byRun` = the chat's model calls per run it worked on — a run's `session` rows name the chat, or same repo, the run's issue in `issue.all` and overlapping time — each call to the run whose first-to-last status row window holds its time, the later-started run when two do; `{}` = no run, `null` = a call has no time, e.g. Antigravity, Cursor); `agents:{total:{n, errors}, byAgent:{<agent type>:{n, errors, instances:[{turns, contextPeak, contextAt10}], usage, mix, planReads:{full, partial}}}}` (`contextAt10` = context read by the instance's 10th model call, `null` under 10; `planReads` = reads of a `docs/plans/<YYYYMM>/<FID>-plan(-N).md` file, `partial` = a line range or `sed` / `head` / `tail`); `tools:{total:{calls, errors}, byTool:{<tool>:{calls, errors, byCategory?}}, filesRead}`; `scan:{files, bytes, settled, tokensRecorded}` (`settled` = unchanged for the settle window, `false` = open: counted and marked, not in medians; `tokensRecorded` false = host records none, e.g. Cursor). New same-`key` row when `scan.bytes` or `scan.settled` changes, or the stored row has no `usage.byRun`. `schema: 2` chat rows hold `ctx` / `ctxPeak`; readers rename them to `context` / `contextPeak`. `repo` and issues are fingerprints: `fp:` + 12 hex of sha256(`owner/repo` / `owner/repo#N`); no paths, branch names or prompt text. Field reference: the script's header. |
159
+ | `run` | `key` (`<fid>:<workflow>:<start>`); `run:{fid, issue, n, parentSha, parentShas}` (`fid` = fingerprint of `owner/repo:<FID>`; `issue` = fingerprint of the FID's leading number, else `null`; `n` = nth run of that workflow in the log; `parentSha` = its last `workflow-done` row's, else its last close step's, else `null` — exact join to the run's `outcome` / `counter` / `compliance`; `parentShas` = every commit its status rows name); `time:{start, end, totalMinutes, activeMinutes, activeFrom:{chats,bytes}, lastActivity}` (first / last status row; `activeMinutes` = run time inside the spans of counted chats naming its issue by command or summary, `null` = none yet; `lastActivity` = log's last row, after-end rows included); `ending:"done"\|"close-failed"\|"failed"\|"decision-pause"\|"stopped"\|"held"` (last end row; `held` = the last `workflow-done` row says `ending: held`; `close-failed` = after `workflow-done` only the close failed: last close's CI dispatch `unresolved`, or a `workflow-failed` row with no close after it; no end row → `decision-pause` if its `build-decision-*.md` is `Status: OPEN`, else `stopped`); `ci`, `steps` (with `activeMinutes`), `lines` (build, debug), `plan` (a feature's last plan run), `build` (build) — § Shared Blocks; `owner:{waitBeforeMinutes, total:{stops, minutes}, stops:[{minutes, open, reason}]}` (owner waits from `owner-pause` → next `owner-answer` status rows, pauses before an answer joined into one stop; `open` = no answer yet, `minutes: null`; `reason` `decision` / `grill` / `draft`; `waitBeforeMinutes` = the same log's previous run's last row to this run's first, `null` for the first); `usage:{total, main, agents}\|null` (each `{turns, tokens}`; sum of the matched chats' `usage.byRun[key]`; `null` = no chat matched, or one has no `byRun`); `scan:{rows, afterEnd, settled}` (`afterEnd` = rows after the end row, e.g. a hand rewind, or the `engine-call` / `completeness` rows the engine journals after a terminator, which add to `afterEnd` and `scan.rows` with no rewind; `settled` = last row older than the settle window). `ts` = scan time. New same-`key` row when `scan.rows`, `time.activeFrom`, `scan.settled`, `usage` or `owner` changes. No limits applied; no FID text, paths or branch names. |
113
160
  | `feature` | `key` (the FID), `category` (§ Categories), `summary?`, `description`, `status:"DESIGNED"\|"PLANNED"\|"BUILT"\|"DEBUGGED"\|"SHIPPED"\|"ABANDONED"` (required — no severity; see `docs/roadmap.md`), `shippedAt:number?` (§ Ship Date). |
114
161
 
115
162
  ## Who Wrote It — `by.step` vs `by.subagent` vs `by.model`
@@ -117,65 +164,67 @@ Same name, same shape on `outcome` and `run`:
117
164
  <!-- prettier-ignore -->
118
165
  | Row written by | `by.workflow` | `by.step` | `by.subagent` | `by.model` |
119
166
  | --- | --- | --- | --- | --- |
120
- | **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | *(absent)* | *(absent)* |
167
+ | **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | (absent) | (absent) |
121
168
  | **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-plan-gaps-remediate` | `bkit-build-plan-gaps-remediate` | that prompt's own `model:` |
169
+ | **A direct chat** outside any workflow | `utility` | `manual` | (absent) | (absent) |
122
170
 
123
- Subagent: on every appended row, from your prompt file:
171
+ Subagent: set these on every row you append, from your prompt file:
124
172
 
125
173
  - **`by.subagent`** = your frontmatter `name:`.
126
174
  - **`by.model`** = your frontmatter `model:`.
127
- - **`by.step`** = invoking workflow step (named in your Context); never an agent name.
128
- - **`by.workflow`** = invoking workflow.
175
+ - **`by.step`** = the invoking workflow step, named in your Context. Never an agent name.
176
+ - **`by.workflow`** = the invoking workflow.
129
177
 
130
178
  Orchestrator: omit `by.subagent` and `by.model`.
131
179
 
132
180
  ## Key & References
133
181
 
134
- `key` = written-once stable slug; recurrence = same-`key` append.
182
+ `key` = a stable slug, written once. A recurrence is a same-`key` append.
135
183
 
136
- - **Mint it from the CONTENT, never from a counter.** Descriptive slug (`gh-mcp-401-after-token-rotation`), optionally issue-prefixed (`681-e2e-parallelism-via-runner-matrix`). Counter-derived ids collide under concurrency — two workflows read same max off their base commit, mint same id, silent collision.
137
- - **Cite the `key`.** Identity for other rows, docs, memory; `ts` = tiebreaker. Content slugs avoid counter collisions.
184
+ - **Mint it from the content, never from a counter.** Use a descriptive slug (`gh-mcp-401-after-token-rotation`), optionally prefixed with the issue (`681-e2e-parallelism-via-runner-matrix`). Counter-derived ids collide under concurrency: two workflows read the same maximum off their base commit, mint the same id, and collide silently.
185
+ - **Cite the `key`.** It is the identity for other rows, docs and memory, and `ts` is the tiebreaker. Content slugs avoid counter collisions.
138
186
 
139
- `references` = pointers placing this row:
187
+ `references` = the pointers that place this row:
140
188
 
141
189
  <!-- prettier-ignore -->
142
190
  ```jsonl
143
- "references": ["681", "ISSUE-217", "PR-412", "a1b2c3d", "docs/plans/202607/681-e2e-parallelism-design.md", "1718900000600"]
191
+ "references": ["681", "ISSUE-217", "PR-412", "a1b2c3d", "docs/plans/202607/681-e2e-parallelism-design.md", "gh-mcp-401-after-token-rotation"]
144
192
  ```
145
193
 
146
- - Feature ids / `{FID}`, tracker ids (`ISSUE-217`), PRs, commit SHAs, file paths, sibling row `ts`.
147
- - Keep items as source wrote; trailing qualifiers (`ISSUE-142 §A2`) = meaning, not noise.
148
- - No separate identity field: `ts` = id; `references` = pointers only.
149
- - Omit when nothing to point at.
194
+ - A pointer is a feature id / `{FID}`, a tracker id (`ISSUE-217`), a PR, a commit SHA, a file path, or a row's `key` in the same or another ledger.
195
+ - Keep each item as the source wrote it. A trailing qualifier (`ISSUE-142 §A2`) is meaning, not noise.
196
+ - There is no separate identity field: `key` is the identity, and `references` holds pointers only.
197
+ - Omit the field when there is nothing to point at.
198
+ - Pointers between ledgers never need rewriting: a correction is a same-`key` append. When a correction affects rows in other ledgers that point at it, the ledger updater (`@bkit-utility-update-decisions`, `-knowledge`, `-deferrals`, `-failures`) reports those rows under `Cross-Ledger Impact`. Each row's own ledger writer appends any change.
150
199
 
151
200
  ## Friction Is a Drained Queue — the non-append-only rows
152
201
 
153
- `.bkit/friction.jsonl` = drained work queue. `chat` / `run` rows in `.bkit/stats.jsonl` = drained too (they belong in `harvest/`). No other row is ever removed:
202
+ `.bkit/friction.jsonl` is a drained work queue. The `chat` / `run` rows in `.bkit/stats.jsonl` are drained too, because they belong in `harvest/`. No other row is ever removed, apart from the superseded keyed-ledger rows that `bkit ledgers compact` drops (§ Compaction):
154
203
 
155
204
  <!-- prettier-ignore -->
156
205
  | Actor | May do |
157
206
  | --- | --- |
158
207
  | **A consumer repo** | append only. |
159
- | **bkit's harvest** (`pnpm harvest`, bkit repo only, unshipped) | MOVES rows out: copies each into bkit's `harvest/` store, then prunes it from the repo. |
208
+ | **bkit's harvest** (`pnpm harvest`, bkit repo only, unshipped) | moves rows out: copies each into bkit's `harvest/` store, then prunes it from the repo. |
160
209
 
161
- Row vanishing from `.bkit/friction.jsonl` = the harvest banked it centrally.
210
+ A row that vanishes from `.bkit/friction.jsonl` was banked centrally by the harvest.
162
211
 
163
- Prune gates (in order):
212
+ The prune gates, in order:
164
213
 
165
- - **Durability first** — prune only after exact row fsync'd to store and read back.
166
- - **Content, never identity** — gate byte-for-byte on the row's `normalize()` shape (old-shape row matches its migrated copy); `fold` collapses same-identity rows — identity gate deletes rows store does not hold.
167
- - **Malformed lines** — never pruned.
168
- - **Store accumulates** — every distinct row, deduped by content only; never cleared, never rewritten from `fold` (winners shift between runs). Readers fold it. `harvest` NEVER commits, either repo.
214
+ - **Durability first:** Prune a row only after the exact row is fsync'd to the store and read back.
215
+ - **Content, never identity:** Gate byte-for-byte on the row's `normalize()` shape. An old-shape row matches its migrated copy. `fold` collapses same-identity rows, so an identity gate deletes rows the store does not hold.
216
+ - **Malformed lines:** Never pruned.
217
+ - **Store accumulates:** The store keeps every distinct row, deduped by content only. It is never cleared, and never rewritten from `fold`, because the winners shift between runs. Readers fold it. `harvest` never commits, in either repo.
169
218
 
170
- `stats.jsonl` = COPIED whole; only its `chat` / `run` rows pruned. `deferrals` / `failures` = COUNT-only (top-section metadata; prose never leaves the repo).
219
+ `stats.jsonl` is copied whole, and only its `chat` / `run` rows are pruned. `deferrals` / `failures` are count-only, from their top-section metadata. Their prose never leaves the repo.
171
220
 
172
221
  ## Summary vs Description
173
222
 
174
- Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature`): `summary` = short title; `description` = prose. One sentence → `description` only.
223
+ On the kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature`), `summary` = a short title and `description` = the prose. When the text is one sentence, write `description` only.
175
224
 
176
225
  ## Severity
177
226
 
178
- `severity` is required on `friction` / `deferral` / `failure`, and must not appear on any other kind (`knowledge` / `decision` / `feature` have no triage severity — `feature` tracks phase via `status`, not how badly something is broken; `compliance` / `outcome` / `counter` are machine-generated). Closed enum — exactly these four, uppercase:
227
+ `severity` is required on `friction` / `deferral` / `failure`, and must not appear on any other kind. `knowledge` / `decision` / `feature` have no triage severity: `feature` tracks its phase through `status`, not how badly something is broken. `compliance` / `outcome` / `counter` are machine-generated by `bkit workflows close`, or written by a direct chat (`by.workflow` `utility`). `severity` is a closed enum of exactly these four values, in uppercase:
179
228
 
180
229
  <!-- prettier-ignore -->
181
230
  | Value | Means |
@@ -185,49 +234,50 @@ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision`
185
234
  | `MEDIUM` | Degraded behaviour or a repeated cost; safe to schedule. |
186
235
  | `LOW` | Cosmetic, nit, or a speculative future idea. |
187
236
 
188
- - Same enum the challenge prompts assign. Finding → row (e.g. `bkit challenge merge` `LOW` → `docs/deferrals.jsonl`): carry ITS severity unchanged.
189
- - not `bkit install` preflight `blocker` / `advisory` — different axis.
190
- - Pick level the ROW earns. All-`LOW` ledger = useless as no severity.
237
+ - It is the same enum the challenge prompts assign. When a finding becomes a row (e.g. `bkit challenge merge` `LOW` → `docs/deferrals.jsonl`), carry its severity unchanged.
238
+ - It is not the `bkit install` preflight's `blocker` / `advisory`, which measure a different axis.
239
+ - Pick the level the row earns. A ledger where every row is `LOW` is as useless as one with no severity.
191
240
 
192
241
  ## Deferral Reason
193
242
 
194
- `reason` required on `deferral`, absent elsewhere. Why the work is deferred — distinct from `status` (how far) and `severity` (how much). Closed enum, lowercase:
243
+ `reason` is required on `deferral`, and absent on every other kind. It says why the work is deferred, which is distinct from `status` (how far) and `severity` (how much). It is a closed enum, in lowercase:
195
244
 
196
245
  <!-- prettier-ignore -->
197
246
  | Value | Means | Also required |
198
247
  | --- | --- | --- |
199
- | `scope-declared` | design/plan called it out of scope before work started. | `references` to that doc §. |
248
+ | `scope-declared` | design / plan called it out of scope before work started. | `references` to that doc §. |
200
249
  | `hard-blocked` | external blocker (credential, upstream fix, feature) blocks it now. | Name blocker in `description`. |
201
250
  | `needs-decision` | human decision missing; guessing worse than waiting. | State decision + options. |
202
251
  | `own-cycle` | plan-sized — new architecture, not a mechanical fix. | Say what makes it plan-sized. |
203
252
  | `low-severity` | `LOW` challenge finding, written by `bkit challenge merge`. | Name the finding. |
204
- | `unjustified` | ADJUDICATOR-only — in-scope work that should have been finished. | Which test it failed. |
253
+ | `unjustified` | adjudicator-only — in-scope work that should have been finished. | Which test it failed. |
205
254
 
206
- - First four, or `low-severity` where it applies → deferral. None fit → unfinished work, do IT (`.agents/rules.md` § "Finish over deferrals").
207
- - `unjustified` never self-assigned — writer picks first four; reviewer adjudicating another's deferral sets it via same-`key` append.
208
- - Set once, carried verbatim by every later row — the rate it feeds counts the deferral that should not have been written.
209
- - No free prose — an unadjudicable reason reads as justification while being none; the enum closes that.
255
+ - **If** one of the first four fits, or `low-severity` where it applies → it is a deferral.
256
+ - **Else** → it is unfinished work, so do it (`.agents/rules.md` § "Finish over deferrals").
257
+ - `unjustified` is never self-assigned. The writer picks from the first four. A reviewer adjudicating another agent's deferral sets it through a same-`key` append.
258
+ - It is set once and carried verbatim by every later row, because the rate it feeds counts the deferral that should not have been written.
259
+ - It is never free prose. A reason nobody can adjudicate reads as a justification while being none, and the closed enum prevents that.
210
260
 
211
- **The four tests.** Reviewer marks `unjustified` when all hold; never applied to a `low-severity` row:
261
+ **The four tests.** A reviewer marks a row `unjustified` when all four hold. The tests never apply to a `low-severity` row:
212
262
 
213
- 1. `remediation` names specific files + a bounded edit, not a new architecture.
214
- 2. Surface inside files the cycle already touched.
215
- 3. No external blocker — no missing decision, credential, upstream fix, confirmation.
216
- 4. `scope-declared` with no pre-existing declaration — the row is the only place it was called out of scope.
263
+ 1. `remediation` names specific files and a bounded edit, not a new architecture.
264
+ 2. The surface is inside files the cycle already touched.
265
+ 3. There is no external blocker: no missing decision, credential, upstream fix or confirmation.
266
+ 4. The row is `scope-declared` with no pre-existing declaration: the row is the only place the work was called out of scope.
217
267
 
218
- Test 4 carries the weight: genuine deferral declared out of scope before work started; unjustified declared at moment of avoidance. Both timestamps in ledger.
268
+ Test 4 carries the weight. A genuine deferral was declared out of scope before the work started. An unjustified one was declared at the moment of avoidance. The ledger holds both timestamps.
219
269
 
220
270
  ## Ship Date
221
271
 
222
- `shippedAt` OPTIONAL on `feature`, absent elsewhere. Unix ms the feature shipped. `docs/roadmap.md` § Shipped ranks on `shippedAt // ts`.
272
+ `shippedAt` is optional on `feature`, and absent on every other kind. It is the Unix ms when the feature shipped. `docs/roadmap.md` § Shipped ranks on `shippedAt // ts`.
223
273
 
224
- - Set only on `status:"SHIPPED"` rows, and only when the ship predates the append — a backfill. Live phase close: OMIT, `ts` already is the ship time.
225
- - may be a literal (unlike `ts`, § Write Idiom) — it is not row identity. Source it: issue `closed_at`, merge-commit date.
226
- - never a guess. No defensible source = omit and accept `ts` ordering.
274
+ - Set it only on `status:"SHIPPED"` rows, and only when the ship predates the append, as in a backfill. At a live phase close, omit it, because `ts` already is the ship time.
275
+ - It may be a literal, unlike `ts` (§ Write Idiom), because it is not row identity. Source it from the issue's `closed_at` or the merge-commit date.
276
+ - Never guess it. **If** there is no defensible source → omit it, and accept the `ts` ordering.
227
277
 
228
278
  ## Categories
229
279
 
230
- Free-form; closest term, `other` if none. `deferral` + `failure` → domain set; `friction` → friction set — do not mix.
280
+ Categories are free-form. Use the closest term, or `other` if none fits. `deferral` and `failure` use the domain set, and `friction` uses the friction set. Do not mix them.
231
281
 
232
282
  **Domain — `deferral` + `failure`:**
233
283
 
@@ -245,72 +295,85 @@ Free-form; closest term, `other` if none. `deferral` + `failure` → domain set;
245
295
  | `docs` | documentation |
246
296
  | `other` | none of the above |
247
297
 
248
- **Flaky / intermittent tests** = `failure` with `category:"testing"`: `key` = spec path + test title, minted once; re-observation = same-`key` append (§ Updating a Row) → flake-count = same-`key` row count; first/last `ts` = first-/last-seen. Do not add pass-rate or counter field.
298
+ **Flaky / intermittent tests** = `failure` rows with `category:"testing"`. Their `key` = the spec path + the test title, minted once. Each re-observation is a same-`key` append (§ Updating a Row), so the flake count = the winner's `updates`. `firstTs` / `ts` = first seen / last seen. Do not add a pass-rate or counter field.
249
299
 
250
300
  **Friction — `friction`:**
251
301
 
252
302
  <!-- prettier-ignore -->
253
303
  | Term | Covers |
254
304
  | --- | --- |
255
- | `human-confirm` | human confirmation prompt |
305
+ | `human-confirm` | human confirmation prompt; the engine writes it when `status row --type=owner-pause` records a workflow stopping to ask the owner, so the agent does not log one. `key` = `owner-pause/<workflow>.<reason>` (`owner-pause/<workflow>` with no `reason`), kept under 60 chars like `tool-failure`; `severity` `LOW`. A follow-up wait writes no row: the status file already holds an `owner-pause` row with the same workflow and `reason` and no `step-done` row after it. A later pause at the same point appends a recurrence, as for `tool-failure`. A failed write keeps the status row and exits 4 |
256
306
  | `permission-prompt` | tool / permission approval prompt |
257
307
  | `agent-rework` | agent redo / self-correction |
258
308
  | `manual-install` | manual dependency / tool install |
259
- | `tool-failure` | tool / command error |
309
+ | `tool-failure` | tool / command error; the engine writes it on a bkit command's exit that is neither a shared routing code nor one of the verb's own `exitCodes`, or on a non-`CommandError` throw. `key` = `<noun>-<verb>/<step>` (`<step>` = the command's `--step=`, else `<noun>-<verb>`), kept under 60 chars because the identity-gated prune truncates a friction key at about 68. The first row carries `recurrenceCount` 1; a recurrence appends the same-`key` winner again with a later `ts`, `recurrenceCount` raised by one and `lastConfirmed` = that `ts` (§ Updating a Row). A `CLOSED` winner comes back `OPEN`, so a fixed failure that returns reaches triage again; a `TRIAGED` one stays `TRIAGED` |
260
310
  | `destructive-backout` | reverted a destructive action |
261
311
  | `other` | none of the above |
262
312
 
263
313
  ## Updating a Row
264
314
 
265
- Fields that change after first write:
315
+ Fields that change after the first write:
266
316
 
267
317
  <!-- prettier-ignore -->
268
318
  | Field | Changes when |
269
319
  | --- | --- |
270
- | `status` | work closes (`OPEN` -> `CLOSED`), or a decision or knowledge row is `SUPERSEDED`. |
271
- | `reason` | (`deferral` only) reviewer adjudicates -> `unjustified`, naming the failed test in `description` and setting `status` -> `TRIAGED`. One-way: never rewritten, carried verbatim by every later row — fold is last-wins, so omitting it erases the verdict and its rate. Gated on the live ledger. |
320
+ | `status` | work closes (`OPEN` → `CLOSED`), or a decision or knowledge row is `SUPERSEDED`. |
321
+ | `reason` | `deferral` only: a reviewer adjudicates → `unjustified`, naming the failed test in `description` and setting `status` → `TRIAGED`. One-way: never rewritten, and carried verbatim by every later row. Fold is last-wins, so omitting it erases the verdict and its rate. Gated on the live ledger. |
272
322
  | `remediation` | the fix is known — usually after the row was logged mid-workflow. |
273
323
  | `severity` | re-triage says it was worse or milder than first thought. |
274
- | `confidence` | (`friction` only) the same thing recurs (raise) or is contradicted (lower). |
275
- | `lastConfirmed` | (`friction` only) re-observed. |
276
- | `recurrenceCount` | (`friction` only) it happens again. |
324
+ | `confidence` | `friction` only: the same thing recurs (raise) or is contradicted (lower). |
325
+ | `lastConfirmed` | `friction` only: re-observed. |
326
+ | `recurrenceCount` | `friction` only: it happens again. |
327
+
328
+ **Update by appending a new row with the same `key`, never by editing the old line.** `fold()` takes the last row by `ts`, and older rows are history. A recurrence is an update.
329
+
330
+ **Hard, not stylistic:** `.gitattributes` sets `merge=union` on every append-only ledger, so merges concatenate and never conflict. Union keeps both sides of a conflicting hunk. Edit a line, and the stale copy survives beside its replacement. `fold` takes the last row by `ts`, so the stale copy wins whenever its `ts` is later.
331
+
332
+ - NEVER edit, reorder or delete a prior line. Change a row through a same-`key` append (§ Updating a Row). The only exceptions are the `bkit install` / `bkit upgrade` schema migration (§ Versioning), `bkit ledgers compact` (§ Compaction), and bkit's harvest (`pnpm harvest`, bkit repo only), which prunes a `.bkit/friction.jsonl` row or a `chat` / `run` row of `.bkit/stats.jsonl` only after the exact row is stored in `harvest/` and read back, and never prunes a malformed line (§ Friction Is a Drained Queue).
333
+ - **Never hand-write `ts`, in either direction:** Mint it at write time (§ Write Idiom). A future value outranks every later correction permanently, so the row can never be superseded. A backdated value loses to the rows it actually followed, so the correction it was meant to be silently never applies.
277
334
 
278
- **Update by APPENDING a new row with the same `key`, never by editing the old line.** `fold()` last-wins by `ts`; older rows = history. Recurrence = update.
335
+ `.bkit/friction.jsonl` is excluded, because rows are removed from it (§ Friction Is a Drained Queue) and union would resurrect a drained row.
279
336
 
280
- **Hard, not stylistic:** `.gitattributes` sets `merge=union` on every append-only ledger — merges concatenate, never conflict. Union keeps both sides of a conflicting hunk: edit a line and the stale copy survives beside its replacement; `fold` last-wins by `ts` -> stale wins whenever its `ts` is later.
337
+ To update a row, copy the prior row, change what changed, and append it. Through `bkit ledgers append`, drop `schema` / `ts` / `bkit` (`firstTs` / `updates` are recomputed), and set `by` to the writer of the new row. Carry `key` verbatim, because a reworded `key` forks the entry. Same `key` = one entry. `fold` returns the last row, so "how long open" / "time to fix" = its `ts` - `firstTs`.
281
338
 
282
- - **NEVER edit or delete a line.** Correct via same-`key` append. Sole exception: the `bkit install` / `bkit upgrade` schema migration (§ Versioning).
283
- - **never hand-write `ts`, in either direction** — mint at write time (§ Write Idiom). Future: outranks every later correction, permanently; row can never be superseded. Backdated: loses to rows it actually followed, so the correction it was meant to be silently never applies.
339
+ **Triage** = sweeping `docs/deferrals.jsonl` / `docs/failures.jsonl` for work that has moved on, and appending a same-`key` row with `status: "CLOSED"`, the current `references` (PR, commit, closing issue) and a re-triaged `severity` where earned.
284
340
 
285
- `.bkit/friction.jsonl` excluded — rows are removed from it (§ Friction Is a Drained Queue); union would resurrect a drain.
341
+ **`TRIAGED`** = the middle state of the triaged trio (`friction` / `deferral` / `failure`, the kinds with `severity`). The ladder: `OPEN` (raised, cause unknown) → `TRIAGED` (analysed, disposition known, not fixed) → `CLOSED` (fixed, refuted, or not ours). Append it the same way as a close, with the disposition in `references`: an issue, a mapped `Fix N`, or why it is not ours.
286
342
 
287
- Copy prior row, change deltas, append. Through `bkit ledgers append`: drop `schema` / `ts` / `bkit`, set `by` to the writer of the new row. Carry `key` verbatim — reworded `key` forks entry. Same `key` = one entry; `fold` returns last → "how long open" / "time to fix" from dated `ts`.
343
+ **`TRIAGED` is still open work.** Open-entry counts (the audit debt lens, the age report) test `status != "CLOSED"`. Only `CLOSED` is done.
288
344
 
289
- **Triage** = sweep `docs/deferrals.jsonl` / `docs/failures.jsonl` for moved-on work → append same-`key` row with `status: "CLOSED"`, current `references` (PR, commit, closing issue), re-triaged `severity` if earned.
345
+ The ladder is not used on `knowledge` or `decision`: both use `ACTIVE` / `SUPERSEDED`. An absent `status` = `ACTIVE`.
290
346
 
291
- **`TRIAGED`** = middle state on triaged trio (`friction` / `deferral` / `failure` — kinds with `severity`). Ladder: `OPEN` (raised, cause unknown) -> `TRIAGED` (analysed, disposition known, not fixed) -> `CLOSED` (fixed, refuted, not ours). Append like close; disposition in `references`: issue, mapped `Fix N`, or why not ours.
347
+ **Readers** of either ledger: Fold by `key`, with the highest `ts` winning. Read only the winning rows whose `status` is `ACTIVE` or absent, and never read any other rows.
292
348
 
293
- **`TRIAGED` is STILL open WORK.** Open-entry counts — audit debt lens, age report — test `status != "CLOSED"`. Only `CLOSED` is done.
349
+ Readers count entities, never lines, so `fold` first.
294
350
 
295
- Not on `knowledge` or `decision` — both use `ACTIVE` / `SUPERSEDED`. Absent `status` = `ACTIVE`.
351
+ ## Compaction
296
352
 
297
- **Readers** of either ledger: fold by `key`, highest `ts` wins → read only winning rows where `status` is `ACTIVE` or absent; never read any other rows.
353
+ `bkit ledgers compact [--ledger=<knowledge|decisions|deferrals|failures|issues|all>] [--dry-run]` rewrites `docs/knowledge.jsonl`, `docs/decisions.jsonl`, `docs/deferrals.jsonl`, `docs/failures.jsonl`, `.bkit/issues.jsonl` to their fold winners:
298
354
 
299
- Readers count ENTITIES, never lines — `fold` first.
355
+ - **Drops** each row that a same-identity row with a higher `ts` supersedes. With equal `ts`, the later line wins, as in `fold`. The winner stays on its line.
356
+ - **Stamps** each winner with `firstTs` (the earliest `firstTs` / `ts` across the entry) and `updates` (a stamped row counts as its `updates`, each later row adds 1, and same-`ts` rows count once). Stale values are corrected.
357
+ - **Keeps byte-for-byte:** malformed, non-object, blank and keyless lines; rows of other kinds; a winner already carrying the right values.
358
+ - **Reader-invisible:** `fold` returns the same winners, apart from `firstTs` / `updates`.
359
+ - **Idempotent:** A second run changes nothing. When `merge=union` brings dropped rows back, the next run drops them again, with the counts unchanged.
360
+ - **Writes** through a temp file and a rename, only when something changes. `--dry-run` only counts.
361
+ - **Runs** at the end of each ledger's updater, best-effort, on its own ledger: `@bkit-utility-update-knowledge` / `-decisions` / `-deferrals` / `-failures`, `@bkit-utility-update-roadmap` → `issues`. Never at append, and never at install / upgrade.
362
+ - No schema change: `firstTs` / `updates` are optional, and a row without them is a one-row entry.
300
363
 
301
364
  ## These Ledgers Are Inputs, Not a Diary
302
365
 
303
- `docs/deferrals.jsonl` + `docs/failures.jsonl` = backlog — deferred scope + known bugs; `severity` ranks, `ts` ages. READ:
366
+ `docs/deferrals.jsonl` and `docs/failures.jsonl` are the backlog: deferred scope and known bugs. `severity` ranks them, and `firstTs` ages them (`ts` when absent). Read them:
304
367
 
305
- - **Before designing or planning** — grep for existing entry or past deferral reason.
306
- - **On a triage sweep** — walk open entries vs tracker + codebase; close, `TRIAGED`, or re-`severity` via append (§ Updating a Row).
307
- - **When a bug looks familiar** — same-`key` `failure` = recurrence.
368
+ - **Before designing or planning:** Grep for an existing entry or a past deferral reason.
369
+ - **On a triage sweep:** Walk the open entries against the tracker and the codebase. For each one, close it, mark it `TRIAGED` or re-set its `severity`, through an append (§ Updating a Row).
370
+ - **When a bug looks familiar:** A same-`key` `failure` is a recurrence.
308
371
 
309
- Rank existing: `severity: CRITICAL` first, then oldest `ts`.
372
+ Rank the existing entries `severity: CRITICAL` first, then by oldest `firstTs` (`ts` when absent).
310
373
 
311
374
  ## Identity / Dedup
312
375
 
313
- Identity tuple, not bare `ts`:
376
+ Identity is a tuple, not a bare `ts`:
314
377
 
315
378
  <!-- prettier-ignore -->
316
379
  | Kind | Identity tuple |
@@ -320,14 +383,14 @@ Identity tuple, not bare `ts`:
320
383
  | `counter` | `(repo, by.workflow, run.parentSha, counter.name)` |
321
384
  | `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` \| `feature` \| `chat` \| `run` | `(kind, repo, key)` |
322
385
 
323
- Identity match = same thing — not automatically skip:
386
+ An identity match means the same thing, not an automatic skip:
324
387
 
325
- - **Nothing changed** -> skip.
326
- - **Something changed** -> **append** (§ Updating a Row).
388
+ - **Nothing changed** → skip.
389
+ - **Something changed** → append (§ Updating a Row).
327
390
 
328
391
  ## `engine-action` rows
329
392
 
330
- Not a ledger: a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.jsonl`). An engine action unsafe to repeat — a tracker comment, a marker commit, a CI re-trigger, a PR open — appends one once it is done, and checks for it first, so a re-run of the same block does not act twice. Actions safe to repeat (a label already set) record nothing.
393
+ This is not a ledger but a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.jsonl`). An engine action unsafe to repeat — a tracker comment, a marker commit, a CI re-trigger, a PR open — appends one once it is done, and checks for it first, so a re-run of the same block does not act twice. Actions safe to repeat (a label already set) record nothing.
331
394
 
332
395
  <!-- prettier-ignore -->
333
396
  | Field | Value |
@@ -345,15 +408,15 @@ Not a ledger: a row in a run's `status.jsonl` (`.bkit/workflows.md` § `status.j
345
408
 
346
409
  ## Versioning
347
410
 
348
- `schema: 3` = row format; `bkit.version` = the bkit that wrote it. `schema: 2` rows differ only in the `plan` block (§ Shared Blocks); read as stored, never rewritten.
411
+ `schema: 3` = the row format, and `bkit.version` = the bkit that wrote it. `schema: 2` rows differ only in the `plan` block (§ Shared Blocks). They are read as stored and never rewritten.
349
412
 
350
- - **Readers normalize every row:** `normalize()` in `.bkit/core/engine/ledgers/telemetry.ts` returns a `schema` row as is; a row without one → `schema: 2` shape: `bkitVersion` → `bkit.version`, `workflow` / `step` / `subagent` / `model` → `by.*` (`null` / empty dropped), any kind's `parentSha` → `run.parentSha`, flat run fields → their blocks, `chat` total tokens summed from its models, fields with no place dropped. `merge=union` can bring an old-shape line back from a branch → no reader assumes a migrated file; one comparing rows across ledgers compares them normalized.
351
- - **No version gating:** readers ingest all well-formed rows, report counts per `bkit.version`; unexpected version surfaces for triage.
352
- - **Migration:** `bkit install` / `bkit upgrade` rewrite each ledger line without `schema` through `normalize()`, in place. Idempotent — a `schema` line, a malformed line or a non-object line stays byte-for-byte. An old line whose rewrite the file already holds (`merge=union` of a branch from before the rewrite doubles every row) is dropped. The one sanctioned edit of a prior line (§ Updating a Row). `bkit check` counts each ledger still holding such a line as a pending write → drift, exit 1 until `bkit upgrade` runs. Ledgers carry no canonical hash: appended rows are never drift.
413
+ - **Readers normalize every row:** `normalize()` in `.bkit/core/engine/ledgers/telemetry.ts` returns a `schema` row as is. It turns a row without one into the `schema: 2` shape: `bkitVersion` → `bkit.version`, `workflow` / `step` / `subagent` / `model` → `by.*` (`null` / empty dropped), any kind's `parentSha` → `run.parentSha`, flat run fields → their blocks, `chat` total tokens summed from its models, and fields with no place dropped. `merge=union` can bring an old-shape line back from a branch, so no reader assumes a migrated file. A reader comparing rows across ledgers compares them normalized.
414
+ - **No version gating:** Readers ingest every well-formed row and report counts per `bkit.version`. An unexpected version surfaces for triage.
415
+ - **Migration:** `bkit install` / `bkit upgrade` rewrite each ledger line without `schema` through `normalize()`, in place. The rewrite is idempotent: a `schema` line, a malformed line or a non-object line stays byte-for-byte. An old line whose rewrite the file already holds is dropped (`merge=union` of a branch from before the rewrite doubles every row). This migration is a sanctioned edit of a prior line (§ Updating a Row), beside § Compaction. `bkit check` counts each ledger still holding such a line as a pending write, which is drift: exit 1 until `bkit upgrade` runs. Ledgers carry no canonical hash, so appended rows are never drift.
353
416
 
354
417
  ## Examples
355
418
 
356
- Indented for readability — **on disk each row = single physical line** (§ Write Idiom). One example per ledger. Each shows the kind's fields, optional ones included where they apply to its workflow (§ Per-Kind Fields; `build` block: the `run` example):
419
+ The rows are indented here for readability. On disk, each row is a single physical line (§ Write Idiom). There is one example per ledger. Each shows the kind's fields, with the optional ones included where they apply to its workflow (§ Per-Kind Fields). The `build` block appears in the `run` example.
357
420
 
358
421
  `.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`); `harvest/stats.jsonl` (`chat` / `run`):
359
422
 
@@ -415,7 +478,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
415
478
  "byModel": { "claude-opus-5-5": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 } } },
416
479
  "byRun": { "fp:5d41402abc4b:build:1718900000000": { "main": { "turns": 60, "tokens": { "input": 400, "cacheWrite": 210000, "cacheRead": 4189600, "output": 31000, "outputEst": 27000, "read": 4400000 } }, "agents": { "turns": 60, "tokens": { "input": 500, "cacheWrite": 200000, "cacheRead": 5209500, "output": 21000, "outputEst": 21000, "read": 5410000 } } } }
417
480
  },
418
- "agents": { "total": { "n": 1, "errors": 2 }, "byAgent": { "bkit-build-plan-execute": { "n": 1, "errors": 2, "instances": [{ "turns": 60, "contextPeak": 150000, "contextAt10": 64000 }], "usage": { "turns": 60, "tokens": { "input": 500, "cacheWrite": 200000, "cacheRead": 5209500, "output": 21000, "outputEst": 21000, "read": 5410000 }, "context": { "peak": 150000 }, "compactions": 0 }, "mix": { "read": 7, "edit": 19, "grep": 20, "shellRead": 11, "shellList": 0, "tests": 8, "serena": 0 }, "planReads": { "full": 1, "partial": 4 } } } },
481
+ "agents": { "total": { "n": 1, "errors": 2 }, "byAgent": { "bkit-build-plan-tasks": { "n": 1, "errors": 2, "instances": [{ "turns": 60, "contextPeak": 150000, "contextAt10": 64000 }], "usage": { "turns": 60, "tokens": { "input": 500, "cacheWrite": 200000, "cacheRead": 5209500, "output": 21000, "outputEst": 21000, "read": 5410000 }, "context": { "peak": 150000 }, "compactions": 0 }, "mix": { "read": 7, "edit": 19, "grep": 20, "shellRead": 11, "shellList": 0, "tests": 8, "serena": 0 }, "planReads": { "full": 1, "partial": 4 } } } },
419
482
  "tools": { "total": { "calls": 100, "errors": 3 }, "byTool": { "Bash": { "calls": 80, "errors": 3, "byCategory": { "git": 30, "grep / rg": 25, "test runner": 15, "bkit cli": 10 } }, "Read": { "calls": 20, "errors": 0 } }, "filesRead": 14 },
420
483
  "scan": { "files": 5, "bytes": 4812345, "settled": true, "tokensRecorded": true }
421
484
  }
@@ -431,9 +494,9 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
431
494
  "time": { "start": 1718900000000, "end": 1718910000000, "totalMinutes": 166.7, "activeMinutes": 98.4, "activeFrom": { "chats": 1, "bytes": 4812345 }, "lastActivity": 1718910000000 },
432
495
  "ending": "done",
433
496
  "ci": [{ "status": "dispatched", "reason": null, "attempts": 1 }],
434
- "steps": { "total": { "n": 6, "totalMinutes": 63.7, "activeMinutes": 45.2 }, "byStep": { "build-plan-execute": { "n": 1, "totalMinutes": 41.2, "activeMinutes": 30.1 }, "build-plan-verify": { "n": 2, "totalMinutes": 18.5, "activeMinutes": 12 }, "build-task-red": { "n": 3, "totalMinutes": 4, "activeMinutes": 3.1 } } },
497
+ "steps": { "total": { "n": 6, "totalMinutes": 63.7, "activeMinutes": 45.2 }, "byStep": { "build-plan-tasks": { "n": 1, "totalMinutes": 41.2, "activeMinutes": 30.1 }, "build-plan-verify": { "n": 2, "totalMinutes": 18.5, "activeMinutes": 12 }, "build-tests-red": { "n": 3, "totalMinutes": 4, "activeMinutes": 3.1 } } },
435
498
  "lines": { "total": { "added": 1172, "deleted": 120, "changed": 1292, "files": 23 }, "code": { "added": 200, "deleted": 2, "files": 4 }, "tests": { "added": 938, "deleted": 104, "files": 14 }, "docs": { "added": 34, "deleted": 14, "files": 5 }, "merges": 1 },
436
- "build": { "verify": [{ "group": 1, "attempt": 1, "verdict": "FAIL", "failures": 2, "testOrderGaps": 0 }, { "group": 1, "attempt": 2, "verdict": "PASS", "failures": 0, "testOrderGaps": 0 }], "gapsRemediate": [{ "group": 1, "attempt": 1, "verdict": "PASS", "strategy": "STANDARD" }], "holistic": null, "challenge": { "verdict": "CONCERNS", "findings": { "total": 5, "CRITICAL": 0, "HIGH": 0, "MEDIUM": 2, "LOW": 3 } }, "redTests": 3 },
499
+ "build": { "verify": [{ "group": 1, "attempt": 1, "verdict": "FAIL", "failures": 2 }, { "group": 1, "attempt": 2, "verdict": "PASS", "failures": 0 }], "gapsRemediate": [{ "group": 1, "attempt": 1, "verdict": "PASS", "strategy": "STANDARD" }], "holistic": null, "challenge": { "verdict": "CONCERNS", "findings": { "total": 5, "CRITICAL": 0, "HIGH": 0, "MEDIUM": 2, "LOW": 3 } }, "redTests": 3 },
437
500
  "scan": { "rows": 31, "afterEnd": 0, "settled": true }
438
501
  }
439
502
  ```
@@ -449,12 +512,12 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
449
512
  "key": "ship-dev-commit-blocked-by-pre-commit-hook",
450
513
  "repo": "cbartens/bkit",
451
514
  "bkit": { "version": "5.6.0" },
452
- "by": { "workflow": "ship", "step": "ship-update-docs" },
515
+ "by": { "workflow": "ship", "step": "ship-bookkeeping-push" },
453
516
  "category": "tool-failure",
454
517
  "scope": "bkit-repo",
455
518
  "severity": "HIGH",
456
- "summary": "ship Step 9 dev commit blocked by the pre-commit hook",
457
- "description": "ship Steps 8-12 commit docs to dev, but the pre-commit hook refuses dev/main commits unless $PWD matches *.worktrees/*; git -C REPO_ROOT commit does not pass the guard and --no-verify is prohibited",
519
+ "summary": "ship bookkeeping commit on dev blocked by the pre-commit hook",
520
+ "description": "the ship bookkeeping commit runs on dev, but the pre-commit hook refuses dev/main commits unless $PWD matches *.worktrees/*; git -C REPO_ROOT commit does not pass the guard and --no-verify is prohibited",
458
521
  "remediation": "commit via a temp branch (docs/ship-{FID}) from dev in a temp worktree, then FF-merge dev",
459
522
  "source": "orchestrator",
460
523
  "status": "OPEN",
@@ -476,7 +539,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
476
539
  "key": "pnpm-tag-drop-readme-note",
477
540
  "repo": "cbartens/bkit",
478
541
  "bkit": { "version": "5.6.0" },
479
- "by": { "workflow": "design", "step": "design-brainstorm", "subagent": "bkit-design-generate", "model": "claude-opus-4-8" },
542
+ "by": { "workflow": "design", "step": "design-generate", "subagent": "bkit-design-generate", "model": "claude-opus-5-5" },
480
543
  "type": "issue",
481
544
  "category": "infra",
482
545
  "severity": "LOW",
@@ -501,7 +564,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
501
564
  "key": "hook-git-dir-leaks-into-temp-repo-tests",
502
565
  "repo": "cbartens/bkit",
503
566
  "bkit": { "version": "5.6.0" },
504
- "by": { "workflow": "debug", "step": "debug-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-4-8" },
567
+ "by": { "workflow": "debug", "step": "debug-failure-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-5-5" },
505
568
  "category": "tooling",
506
569
  "summary": "Tests run from a git hook act on the real repo",
507
570
  "severity": "HIGH",
@@ -524,7 +587,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
524
587
  "key": "gh-mcp-401-after-token-rotation",
525
588
  "repo": "cbartens/bkit",
526
589
  "bkit": { "version": "5.6.0" },
527
- "by": { "workflow": "debug", "step": "debug-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-4-6" },
590
+ "by": { "workflow": "debug", "step": "debug-failure-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-5-5" },
528
591
  "summary": "GitHub MCP / gh 401 immediately after a token rotation",
529
592
  "description": "401 from the GitHub MCP server or gh despite a freshly-rotated, valid, correctly-scoped PAT in .bkit/.env",
530
593
  "rootCause": "the MCP server captures GH_MCP_TOKEN at process launch, so a mid-session rotation leaves it holding the dead token",
@@ -545,7 +608,7 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
545
608
  "key": "bkit-distribution-via-npmjs",
546
609
  "repo": "cbartens/bkit",
547
610
  "bkit": { "version": "5.6.0" },
548
- "by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-4-8" },
611
+ "by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-5-5" },
549
612
  "summary": "publish @cbartens/bkit publicly on npmjs",
550
613
  "description": "publish @cbartens/bkit publicly on npmjs; consumers install with no registry mapping, PAT, or CI/Vercel env",
551
614
  "rationale": "public install needs no registry mapping or token; release.yml publishes from CI via npm OIDC trusted publishing",