@cbartens/bkit 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -10,20 +10,31 @@
10
10
  > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
11
  > - Describe current state / rules, not reasons / history; state what to do, not why.
12
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).
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
14
  > - Before append: read file. Skip only if identity-matching row exists and nothing changed — changed field = update, not duplicate.
15
- > - `.bkit/friction.jsonl` rows removed only by `bkit harvest` (§ Friction Is a Drained Queue).
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
16
  > - Best-effort append — always exit 0; never gate workflows on telemetry success.
17
17
 
18
18
  ## Write Idiom
19
19
 
20
+ **Engine and workflow writers:** `bkit ledgers append --ledger=<decisions|deferrals|failures|knowledge|friction|stats> --rows=<file|->`; rows = JSON array without `schema` / `ts` / `bkit`.
21
+
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.
28
+
29
+ **Humans and scripts:** the `jq` idiom:
30
+
20
31
  ```bash
21
- jq -c -n '{ ts: null, kind: "deferral", repo: $REPO, bkitVersion: $VER, step: $STEP, … } | .ts = (now*1000|floor)' \
32
+ jq -c -n '{ schema: 3, ts: null, kind: "deferral", repo: $REPO, bkit: { version: $VER }, by: { step: $STEP }, … } | .ts = (now*1000|floor)' \
22
33
  >> "$FILE" || echo "[bkit-telemetry] append failed: $FILE"
23
34
  ```
24
35
 
25
- - **`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 the envelope gate instead of landing a fake value — never seed the placeholder with a number.
26
- - **`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, `bkit harvest`, and every age report depend on. Whole-second values (`ts % 1000 == 0`) are rejected — a real mint is never round.
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.
27
38
  - **Log prefix:** every telemetry log line starts `[bkit-telemetry]` — load-bearing for log-drain grep.
28
39
 
29
40
  ## Ledgers & Writers
@@ -33,63 +44,90 @@ One file per `kind`; writers:
33
44
  <!-- prettier-ignore -->
34
45
  | Kind | File | Written by |
35
46
  | --- | --- | --- |
36
- | `compliance` | `.bkit/stats.jsonl` | `bkit comply` grader at each workflow close step |
37
- | `outcome` | `.bkit/stats.jsonl` | every workflow at its close (one run row per workflow run; keyed by `repo`+`workflow`+`parentSha`) |
38
- | `counter` | `.bkit/stats.jsonl` | every workflow at its close step (attempt counters) |
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) |
50
+ | `chat` | `harvest/stats.jsonl` (bkit repo only) | bkit's harvest script: per agent chat on the maintainer's machine, any repo or host |
51
+ | `run` | `harvest/stats.jsonl` (bkit repo only) | Same script: per workflow run in the run logs of every repo a chat ran in |
39
52
  | `friction` | `.bkit/friction.jsonl` | orchestrator workflows (design / plan / build / debug / ship) on observed friction |
40
- | `deferral` | `docs/deferrals.jsonl` | `@bkit-design-generate`, `@bkit-plan-generate`, `@bkit-plan-update`, `@bkit-build-challenge-remediate` (blocked), `@bkit-debug-abort-handover`, `@bkit-ship-deferred-sweep` (adjudication only), `@bkit-utility-update-deferrals` (close / triage / locator) |
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`) |
41
54
  | `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) |
42
- | `knowledge` | `docs/knowledge.jsonl` | `@bkit-build-challenge-remediate`, `@bkit-build-plan-gaps-remediate`, `@bkit-debug-failure-remediate` (after verified fix), `@bkit-utility-update-knowledge` (supersede / correct) |
43
- | `decision` | `docs/decisions.jsonl` | `@bkit-debug-failure-remediate` (forced arch), `@bkit-plan-generate`, `@bkit-utility-update-decisions` (supersede / correct) |
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 |
44
57
  | `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 |
45
58
 
46
- **Writers are exhaustive:** only agents listed as writers for a given kind are allowed to write that specific kind; no exceptions.
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.
47
60
 
48
61
  ## Generic Fields (all kinds)
49
62
 
63
+ Every row opens with the same top section, in this order:
64
+
50
65
  <!-- prettier-ignore -->
51
66
  | Field | Type | Meaning |
52
67
  | --- | --- | --- |
53
- | `ts` | `number` | Unix milliseconds — primary id. Minted via `jq '… \| .ts = (now*1000\|floor)'`, never a literal (§ Write Idiom). |
54
- | `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`. |
55
- | `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`. |
56
- | `bkitVersion` | `string` | bkit version that emitted the row — sole version stamp; readers tally rows per `bkitVersion` for triage. |
57
- | `workflow` | `string` | Emitting workflow: `design` / `plan` / `build` / `debug` / `ship` / `audit` (part of the dedup tuple for `compliance` / `counter` / `outcome`). |
58
- | `step` | `string` | The workflow step the row was emitted at, e.g. `build-close-workflow`, `ship-close-gate`. Never an agent name. See § Who Wrote It. |
59
- | `subagent` | `string?` | The subagent that wrote the row, e.g. `bkit-build-challenge-remediate`. Set on every subagent-written row; absent on orchestrator-written rows. See § Who Wrote It. |
60
- | `model` | `string?` | The model that wrote the row, from the writing subagent's own frontmatter `model:`. Set only where `subagent` is set. See § Who Wrote It. |
68
+ | `schema` | `3` | Row format. `2` = older `plan` block (§ Shared Blocks); row without it = older shape, read through `normalize()` (§ Versioning). |
69
+ | `ts` | `number` | Unix milliseconds — primary id. Minted at append, never a literal (§ Write Idiom). |
70
+ | `kind` | `string` | Closed enum: `compliance`, `outcome`, `counter`, `friction`, `deferral`, `failure`, `knowledge`, `decision`, `feature`, `chat`, `run`. |
71
+ | `key` | `string?` | Keyed kinds only (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature` / `chat` / `run`). See § Key & References. |
72
+ | `repo` | `string` | Origin repo slug, e.g. `cbartens/bkit`; its fingerprint on `chat` / `run` rows (§ Per-Kind Fields). |
73
+ | `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`. |
61
75
  | `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
62
76
 
77
+ Values, every kind:
78
+
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`.
83
+
84
+ ## Shared Blocks
85
+
86
+ Same name, same shape on `outcome` and `run`:
87
+
88
+ <!-- prettier-ignore -->
89
+ | Block | Shape |
90
+ | --- | --- |
91
+ | `time` | `{start, end, totalMinutes}` (`end` - `start`); `chat` / `run` add `activeMinutes`, `lastActivity`. |
92
+ | `lines` | `{total:{added,deleted,changed,files}, code, tests, docs, merges}`; each part `{added,deleted,files}`; `changed` = `added` + `deleted`. git `--numstat` from the run's first to last commit, first-parent, cut at merges (dev syncs out); `docs/plans/**`, `docs/*.jsonl`, `.bkit/*.jsonl` out. `null` = git lacks the commits or the first is not an ancestor of the last. |
93
+ | `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
+ | `ci` | `[{status,reason,attempts}]`, one per close-step CI dispatch (`status` e.g. `dispatched` / `unresolved`). |
95
+ | `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. |
97
+
63
98
  ## Per-Kind Fields
64
99
 
65
100
  <!-- prettier-ignore -->
66
- | Kind | Fields (beyond envelope) |
101
+ | Kind | Fields (beyond the top section) |
67
102
  | --- | --- |
68
- | `counter` | `counterName`, `counterValue:number`, `counterSource:"model-self-report"\|"shell-bus"`, `parentSha`. |
69
- | `outcome` | `parentSha?` (run anchor), `prNumber:number?` (ship-only), `linesAdded:number`, `linesDeleted:number`, `linesChanged:number`, `filesChanged:number`, `taskCount:number`, `durationSeconds:number`, `ciTrySuccess:number?`, `correctiveCommits:number?`, `reviewIterations:number?`, `deferrals:number`, `failures:number` (the repo's cumulative UNIQUE entity count at close, folded — not lines; per-cycle is the delta against the previous `outcome` row), `frictionAdded:number?`, `deferralsAdded:number?`, `failuresAdded:number?` (per-run deltas — rows this run added to each ledger, counted from `workflow`+`ts>=`workflow-started), `planSource:"brief"?` (build / ship run with no `{FID}-plan*.md` — copied from its `status.jsonl` `workflow-meta` row; absent = run had a plan; summary baselines brief runs only against brief runs), `coverage?:{unit?,integration?,e2e?}` (per-tier, each `{lines,branches,functions,statements}:number` %; best-effort — a tier is absent when its coverage report is not produced, opt-in). |
70
- | `compliance` | `rule`, `result:"pass"\|"fail"\|"n/a"`, `evidence?`, `phase`, `parentSha`. |
103
+ | `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). |
105
+ | `compliance` | `run:{parentSha}`, `rule:{id, verdict:"pass"\|"fail"\|"n/a", evidence?}` (`evidence` on fail rows). |
71
106
  | `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`. |
72
107
  | `deferral` | `key`, `type:"issue"\|"feature"`, `category` (§ Categories), `severity`, `reason` (§ Deferral Reason), `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"?`. |
73
108
  | `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky/intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
74
109
  | `knowledge` | `key`, `summary`, `description?`, `rootCause?`, `remediation?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
75
110
  | `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. |
76
113
  | `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). |
77
114
 
78
- ## Who Wrote It — `step` vs `subagent` vs `model`
115
+ ## Who Wrote It — `by.step` vs `by.subagent` vs `by.model`
79
116
 
80
117
  <!-- prettier-ignore -->
81
- | Row written by | `workflow` | `step` | `subagent` | `model` |
118
+ | Row written by | `by.workflow` | `by.step` | `by.subagent` | `by.model` |
82
119
  | --- | --- | --- | --- | --- |
83
- | **The orchestrator** (a workflow itself) | `ship` | `ship-close-gate` | *(absent)* | *(absent)* |
84
- | **A subagent** it invoked | `build` | the step that invoked it, e.g. `build-challenge` | `bkit-build-challenge-remediate` | that prompt's own `model:` |
120
+ | **The orchestrator** (a workflow itself) | `ship` | `ship-close-workflow` | *(absent)* | *(absent)* |
121
+ | **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:` |
85
122
 
86
123
  Subagent: on every appended row, from your prompt file:
87
124
 
88
- - **`subagent`** = your frontmatter `name:`.
89
- - **`model`** = your frontmatter `model:`.
90
- - **`step`** = invoking workflow step (named in your Context).
125
+ - **`by.subagent`** = your frontmatter `name:`.
126
+ - **`by.model`** = your frontmatter `model:`.
127
+ - **`by.step`** = invoking workflow step (named in your Context); never an agent name.
128
+ - **`by.workflow`** = invoking workflow.
91
129
 
92
- Orchestrator: omit `subagent` and `model`.
130
+ Orchestrator: omit `by.subagent` and `by.model`.
93
131
 
94
132
  ## Key & References
95
133
 
@@ -110,26 +148,26 @@ Orchestrator: omit `subagent` and `model`.
110
148
  - No separate identity field: `ts` = id; `references` = pointers only.
111
149
  - Omit when nothing to point at.
112
150
 
113
- ## Friction Is a Drained Queue — the one non-append-only ledger
151
+ ## Friction Is a Drained Queue — the non-append-only rows
114
152
 
115
- `.bkit/friction.jsonl` = drained work queue — only file rows are removed from:
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:
116
154
 
117
155
  <!-- prettier-ignore -->
118
156
  | Actor | May do |
119
157
  | --- | --- |
120
158
  | **A consumer repo** | append only. |
121
- | **`bkit harvest`** (from the bkit repo) | MOVES rows out: copies each into bkit's `harvest/` store, then prunes it from the consumer. |
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. |
122
160
 
123
- Row vanishing from `.bkit/friction.jsonl` = `bkit harvest` banked it centrally.
161
+ Row vanishing from `.bkit/friction.jsonl` = the harvest banked it centrally.
124
162
 
125
163
  Prune gates (in order):
126
164
 
127
165
  - **Durability first** — prune only after exact row fsync'd to store and read back.
128
- - **Content, never identity** — gate byte-for-byte; `fold` collapses same-identity rows — identity gate deletes rows store does not hold.
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.
129
167
  - **Malformed lines** — never pruned.
130
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.
131
169
 
132
- `stats.jsonl` = COPY-only; `deferrals` / `failures` = COUNT-only (envelope metadata; prose never leaves consumer). Contract: `.bkit/core/engine/commands/harvest.ts`.
170
+ `stats.jsonl` = COPIED whole; only its `chat` / `run` rows pruned. `deferrals` / `failures` = COUNT-only (top-section metadata; prose never leaves the repo).
133
171
 
134
172
  ## Summary vs Description
135
173
 
@@ -147,7 +185,7 @@ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision`
147
185
  | `MEDIUM` | Degraded behaviour or a repeated cost; safe to schedule. |
148
186
  | `LOW` | Cosmetic, nit, or a speculative future idea. |
149
187
 
150
- - Same enum the challenge prompts assign. Finding → row (e.g. `@bkit-build-challenge-remediate` BLOCKED → `docs/deferrals.jsonl`): carry ITS severity unchanged.
188
+ - Same enum the challenge prompts assign. Finding → row (e.g. `bkit challenge merge` `LOW` → `docs/deferrals.jsonl`): carry ITS severity unchanged.
151
189
  - not `bkit install` preflight `blocker` / `advisory` — different axis.
152
190
  - Pick level the ROW earns. All-`LOW` ledger = useless as no severity.
153
191
 
@@ -162,14 +200,15 @@ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision`
162
200
  | `hard-blocked` | external blocker (credential, upstream fix, feature) blocks it now. | Name blocker in `description`. |
163
201
  | `needs-decision` | human decision missing; guessing worse than waiting. | State decision + options. |
164
202
  | `own-cycle` | plan-sized — new architecture, not a mechanical fix. | Say what makes it plan-sized. |
203
+ | `low-severity` | `LOW` challenge finding, written by `bkit challenge merge`. | Name the finding. |
165
204
  | `unjustified` | ADJUDICATOR-only — in-scope work that should have been finished. | Which test it failed. |
166
205
 
167
- - First four → deferral. None fit → unfinished work, do IT (`.agents/rules.md` § "Finish over deferrals").
206
+ - First four, or `low-severity` where it applies → deferral. None fit → unfinished work, do IT (`.agents/rules.md` § "Finish over deferrals").
168
207
  - `unjustified` never self-assigned — writer picks first four; reviewer adjudicating another's deferral sets it via same-`key` append.
169
208
  - Set once, carried verbatim by every later row — the rate it feeds counts the deferral that should not have been written.
170
209
  - No free prose — an unadjudicable reason reads as justification while being none; the enum closes that.
171
210
 
172
- **The four tests.** Reviewer marks `unjustified` when all hold:
211
+ **The four tests.** Reviewer marks `unjustified` when all hold; never applied to a `low-severity` row:
173
212
 
174
213
  1. `remediation` names specific files + a bounded edit, not a new architecture.
175
214
  2. Surface inside files the cycle already touched.
@@ -240,12 +279,12 @@ Fields that change after first write:
240
279
 
241
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.
242
281
 
243
- - **NEVER edit or delete a line.** Correct via same-`key` append.
282
+ - **NEVER edit or delete a line.** Correct via same-`key` append. Sole exception: the `bkit install` / `bkit upgrade` schema migration (§ Versioning).
244
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.
245
284
 
246
285
  `.bkit/friction.jsonl` excluded — rows are removed from it (§ Friction Is a Drained Queue); union would resurrect a drain.
247
286
 
248
- Copy prior row, change deltas, append. Carry `key` verbatim — reworded `key` forks entry. Same `key` = one entry; `fold` returns last → "how long open" / "time to fix" from dated `ts`.
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`.
249
288
 
250
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.
251
290
 
@@ -276,77 +315,126 @@ Identity tuple, not bare `ts`:
276
315
  <!-- prettier-ignore -->
277
316
  | Kind | Identity tuple |
278
317
  | --- | --- |
279
- | `compliance` | `(repo, workflow, parentSha, rule)` |
280
- | `outcome` | `(repo, workflow, parentSha)` — `prNumber` / `ts` fallback on rows without `parentSha` |
281
- | `counter` | `(repo, workflow, parentSha, counterName)` |
282
- | `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` | `(kind, repo, key)` |
318
+ | `compliance` | `(repo, by.workflow, run.parentSha, rule.id)` |
319
+ | `outcome` | `(repo, by.workflow, run.parentSha)` — `run.pr` / `ts` fallback on rows without `run.parentSha`; newest `ts` wins, so a re-appended outcome supersedes |
320
+ | `counter` | `(repo, by.workflow, run.parentSha, counter.name)` |
321
+ | `friction` \| `deferral` \| `failure` \| `knowledge` \| `decision` \| `feature` \| `chat` \| `run` | `(kind, repo, key)` |
283
322
 
284
323
  Identity match = same thing — not automatically skip:
285
324
 
286
325
  - **Nothing changed** -> skip.
287
326
  - **Something changed** -> **append** (§ Updating a Row).
288
327
 
328
+ ## `engine-action` rows
329
+
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.
331
+
332
+ <!-- prettier-ignore -->
333
+ | Field | Value |
334
+ | --- | --- |
335
+ | `type` | `engine-action` |
336
+ | `action` | what was done: `comment`, `commit`, `dispatch`, `pr-open`, … |
337
+ | `key` | the moment: workflow, run, step, sub-plan, attempt, kind, joined by `/`; an absent part is `-` (`build/2/build-plan-verify/1/3/comment`) |
338
+ | `hash` | sha256 hex of the body or payload acted on |
339
+ | `ref` | what the action made (comment URL, commit SHA, run id); `null` when it names none |
340
+ | `at` | UTC, whole seconds |
341
+
342
+ - **Same `key`, same `hash`** → already done: skip, print `deduped: true`.
343
+ - **Same `key`, new `hash`** → a deliberate edit: act again, append another row.
344
+ - **Helpers:** `actionKey`, `actionHash`, `alreadyDone`, `recordAction` in `.bkit/core/engine/ledgers/status.ts`. The row has no `workflow`; the fold, `runStatusRows`, `counters rows` and the status-holes audit all read by `type`, so they skip it.
345
+
289
346
  ## Versioning
290
347
 
291
- No schema version — `bkitVersion` only stamp. Readers ingest all well-formed rows (no version gating), report counts per `bkitVersion`; unexpected version surfaces for triage.
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.
349
+
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.
292
353
 
293
354
  ## Examples
294
355
 
295
- Indented for readability — **on disk each row = single physical line** (§ Write Idiom). One example per ledger. Each shows all kind fields including `?`-optional ones (§ Per-Kind Fields) real rows omit when N/A:
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):
296
357
 
297
- `.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`):
358
+ `.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`); `harvest/stats.jsonl` (`chat` / `run`):
298
359
 
299
360
  <!-- prettier-ignore -->
300
361
  ```jsonl
301
362
  {
363
+ "schema": 3,
302
364
  "ts": 1718900000000,
303
365
  "kind": "compliance",
304
366
  "repo": "cbartens/bkit",
305
- "bkitVersion": "4.2.0",
306
- "workflow": "ship",
307
- "step": "ship-close-workflow",
308
- "rule": "no-mirror-edit",
309
- "result": "pass",
310
- "evidence": "no mirror files present in the diff",
311
- "phase": "ship",
312
- "parentSha": "a1b2c3d"
367
+ "bkit": { "version": "5.6.0" },
368
+ "by": { "workflow": "ship", "step": "ship-close-workflow" },
369
+ "run": { "parentSha": "a1b2c3d" },
370
+ "rule": { "id": "skip-ci-not-head", "verdict": "fail", "evidence": "HEAD a1b2c3d carries [skip ci]" }
313
371
  }
314
372
  {
373
+ "schema": 3,
315
374
  "ts": 1718900000100,
316
375
  "kind": "outcome",
317
376
  "repo": "cbartens/bkit",
318
- "bkitVersion": "4.2.0",
319
- "workflow": "ship",
320
- "step": "ship-close-gate",
321
- "parentSha": "a1b2c3d",
322
- "prNumber": 412,
323
- "linesAdded": 120,
324
- "linesDeleted": 34,
325
- "linesChanged": 154,
326
- "filesChanged": 7,
327
- "taskCount": 5,
328
- "durationSeconds": 2400,
329
- "ciTrySuccess": 1,
330
- "correctiveCommits": 0,
331
- "reviewIterations": 1,
332
- "deferrals": 1,
333
- "failures": 0,
334
- "frictionAdded": 1,
335
- "deferralsAdded": 1,
336
- "failuresAdded": 0,
337
- "coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } }
377
+ "bkit": { "version": "5.6.0" },
378
+ "by": { "workflow": "ship", "step": "ship-close-workflow" },
379
+ "run": { "parentSha": "a1b2c3d", "pr": 412 },
380
+ "time": { "start": 1718897600000, "end": 1718900000000, "totalMinutes": 40 },
381
+ "ending": "done",
382
+ "lines": { "total": { "added": 120, "deleted": 34, "changed": 154, "files": 7 }, "code": { "added": 80, "deleted": 20, "files": 4 }, "tests": { "added": 30, "deleted": 10, "files": 2 }, "docs": { "added": 10, "deleted": 4, "files": 1 }, "merges": 0 },
383
+ "steps": { "total": { "n": 2, "totalMinutes": 32.5 }, "byStep": { "ship-deferred-sweep": { "n": 1, "totalMinutes": 12.5 }, "ship-merge": { "n": 1, "totalMinutes": 20 } } },
384
+ "ci": [{ "status": "dispatched", "reason": null, "attempts": 1 }],
385
+ "ledgers": { "deferrals": { "repo": 14, "added": 1 }, "failures": { "repo": 9, "added": 0 }, "friction": { "added": 1 } },
386
+ "plan": { "source": "file", "total": { "tasks": 3, "kb": 48 }, "groups": [{ "tasks": [{ "tests": 2, "testFiles": 1 }, { "tests": 3, "testFiles": 2 }] }, { "tasks": [{ "tests": null, "testFiles": null }] }] },
387
+ "ship": { "coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } } }
338
388
  }
339
389
  {
390
+ "schema": 3,
340
391
  "ts": 1718900000200,
341
392
  "kind": "counter",
342
393
  "repo": "cbartens/bkit",
343
- "bkitVersion": "4.2.0",
344
- "workflow": "build",
345
- "step": "build-close-workflow",
346
- "counterName": "BUILD_ATTEMPT",
347
- "counterValue": 2,
348
- "counterSource": "shell-bus",
349
- "parentSha": "a1b2c3d"
394
+ "bkit": { "version": "5.6.0" },
395
+ "by": { "workflow": "build", "step": "build-close-workflow" },
396
+ "run": { "parentSha": "a1b2c3d" },
397
+ "counter": { "name": "BUILD_ATTEMPT", "value": 2, "source": "shell-bus" }
398
+ }
399
+ {
400
+ "schema": 3,
401
+ "ts": 1718903600000,
402
+ "kind": "chat",
403
+ "key": "claude-code:8f9f0a84-6f5a-503d-8484-d56d75424d11",
404
+ "repo": "fp:9f86d081884c",
405
+ "bkit": { "version": "5.6.0", "versionSource": "repo-history", "via": ["command", "subagent"], "workflows": ["build"], "prompts": ["build"], "cli": { "total": 10, "byVerb": { "steps finish": 6, "counters derive": 3, "workflows close": 1 } } },
406
+ "by": { "workflow": "chat-stats", "step": "scan" },
407
+ "session": { "platform": "claude-code", "id": "8f9f0a84-6f5a-503d-8484-d56d75424d11", "hostVersion": "2.1.299", "entrypoint": "sdk-cli", "prompts": 14 },
408
+ "time": { "start": 1718900000000, "end": 1718903600000, "totalMinutes": 60, "activeMinutes": 47.5, "spans": [[1718900000000, 1718902400000], [1718903150000, 1718903600000]], "lastActivity": 1718903600000 },
409
+ "issue": { "id": "fp:2c26b46b68ff", "all": ["fp:2c26b46b68ff"], "mentioned": [], "source": "command" },
410
+ "run": { "parentShas": ["a1b2c3d4e5f60718293a4b5c6d7e8f9012345678"] },
411
+ "effort": { "high": 118, "medium": 2 },
412
+ "usage": {
413
+ "total": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 }, "context": { "start": 21000, "peak": 180000 }, "compactions": 1 },
414
+ "main": { "turns": 60, "tokens": { "input": 400, "cacheWrite": 210000, "cacheRead": 4189600, "output": 31000, "outputEst": 27000, "read": 4400000 }, "context": { "peak": 180000 }, "compactions": 1, "mix": { "read": 4, "edit": 6, "grep": 12, "shellRead": 9, "shellList": 1, "tests": 5, "serena": 0 } },
415
+ "byModel": { "claude-opus-5-5": { "turns": 120, "tokens": { "input": 900, "cacheWrite": 410000, "cacheRead": 9399100, "output": 52000, "outputEst": 48000, "read": 9810000 } } },
416
+ "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
+ },
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 } } } },
419
+ "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
+ "scan": { "files": 5, "bytes": 4812345, "settled": true, "tokensRecorded": true }
421
+ }
422
+ {
423
+ "schema": 3,
424
+ "ts": 1718910000000,
425
+ "kind": "run",
426
+ "key": "fp:4e07408562be:build:1718900000000",
427
+ "repo": "fp:9f86d081884c",
428
+ "bkit": { "version": "5.6.0" },
429
+ "by": { "workflow": "build", "step": "scan" },
430
+ "run": { "fid": "fp:4e07408562be", "issue": "fp:2c26b46b68ff", "n": 1, "parentSha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678", "parentShas": ["a1b2c3d4e5f60718293a4b5c6d7e8f9012345678"] },
431
+ "time": { "start": 1718900000000, "end": 1718910000000, "totalMinutes": 166.7, "activeMinutes": 98.4, "activeFrom": { "chats": 1, "bytes": 4812345 }, "lastActivity": 1718910000000 },
432
+ "ending": "done",
433
+ "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 } } },
435
+ "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 },
437
+ "scan": { "rows": 31, "afterEnd": 0, "settled": true }
350
438
  }
351
439
  ```
352
440
 
@@ -355,13 +443,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
355
443
  <!-- prettier-ignore -->
356
444
  ```jsonl
357
445
  {
446
+ "schema": 3,
358
447
  "ts": 1718900000300,
359
448
  "kind": "friction",
360
- "repo": "cbartens/bkit",
361
- "bkitVersion": "4.2.0",
362
- "workflow": "ship",
363
- "step": "ship-update-docs",
364
449
  "key": "ship-dev-commit-blocked-by-pre-commit-hook",
450
+ "repo": "cbartens/bkit",
451
+ "bkit": { "version": "5.6.0" },
452
+ "by": { "workflow": "ship", "step": "ship-update-docs" },
365
453
  "category": "tool-failure",
366
454
  "scope": "bkit-repo",
367
455
  "severity": "HIGH",
@@ -382,15 +470,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
382
470
  <!-- prettier-ignore -->
383
471
  ```jsonl
384
472
  {
473
+ "schema": 3,
385
474
  "ts": 1718900000400,
386
475
  "kind": "deferral",
387
- "repo": "cbartens/bkit",
388
- "bkitVersion": "4.2.0",
389
- "workflow": "design",
390
- "step": "design-brainstorm",
391
- "subagent": "bkit-design-generate",
392
- "model": "claude-opus-4-8",
393
476
  "key": "pnpm-tag-drop-readme-note",
477
+ "repo": "cbartens/bkit",
478
+ "bkit": { "version": "5.6.0" },
479
+ "by": { "workflow": "design", "step": "design-brainstorm", "subagent": "bkit-design-generate", "model": "claude-opus-4-8" },
394
480
  "type": "issue",
395
481
  "category": "infra",
396
482
  "severity": "LOW",
@@ -409,23 +495,21 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
409
495
  <!-- prettier-ignore -->
410
496
  ```jsonl
411
497
  {
498
+ "schema": 3,
412
499
  "ts": 1718900000500,
413
500
  "kind": "failure",
501
+ "key": "hook-git-dir-leaks-into-temp-repo-tests",
414
502
  "repo": "cbartens/bkit",
415
- "bkitVersion": "4.2.0",
416
- "workflow": "debug",
417
- "step": "debug-diagnose",
418
- "subagent": "bkit-debug-failure-diagnose",
419
- "model": "claude-opus-4-8",
420
- "key": "bkit-install-flips-core-bare",
503
+ "bkit": { "version": "5.6.0" },
504
+ "by": { "workflow": "debug", "step": "debug-diagnose", "subagent": "bkit-debug-failure-diagnose", "model": "claude-opus-4-8" },
421
505
  "category": "tooling",
422
- "summary": "bkit install flips core.bare=true",
506
+ "summary": "Tests run from a git hook act on the real repo",
423
507
  "severity": "HIGH",
424
- "description": "`pnpm bkit install` leaves git config core.bare=true, which breaks git checkout/status afterward",
425
- "rootCause": "the install engine writes core.bare while staging and does not restore it on the success path",
426
- "remediation": "run `git config core.bare false` after install",
508
+ "description": "after a pre-push run, git config core.bare=true on the main checkout, which breaks git checkout/status",
509
+ "rootCause": "git exports GIT_DIR to hooks; a test running `git init --bare` with no path in its temp folder re-initialises the real repo as bare",
510
+ "remediation": "delete every GIT_* variable in the test setup before any test spawns git",
427
511
  "status": "OPEN",
428
- "references": ["176", "a1b2c3d", ".bkit/core/engine/commands/install/install.ts"]
512
+ "references": ["176", "a1b2c3d", "vitest.setup.ts"]
429
513
  }
430
514
  ```
431
515
 
@@ -434,15 +518,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
434
518
  <!-- prettier-ignore -->
435
519
  ```jsonl
436
520
  {
521
+ "schema": 3,
437
522
  "ts": 1718900000600,
438
523
  "kind": "knowledge",
439
- "repo": "cbartens/bkit",
440
- "bkitVersion": "4.2.0",
441
- "workflow": "debug",
442
- "step": "debug-remediate",
443
- "subagent": "bkit-debug-failure-remediate",
444
- "model": "claude-sonnet-4-6",
445
524
  "key": "gh-mcp-401-after-token-rotation",
525
+ "repo": "cbartens/bkit",
526
+ "bkit": { "version": "5.6.0" },
527
+ "by": { "workflow": "debug", "step": "debug-remediate", "subagent": "bkit-debug-failure-remediate", "model": "claude-sonnet-4-6" },
446
528
  "summary": "GitHub MCP / gh 401 immediately after a token rotation",
447
529
  "description": "401 from the GitHub MCP server or gh despite a freshly-rotated, valid, correctly-scoped PAT in .bkit/.env",
448
530
  "rootCause": "the MCP server captures GH_MCP_TOKEN at process launch, so a mid-session rotation leaves it holding the dead token",
@@ -457,15 +539,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
457
539
  <!-- prettier-ignore -->
458
540
  ```jsonl
459
541
  {
542
+ "schema": 3,
460
543
  "ts": 1718900000700,
461
544
  "kind": "decision",
462
- "repo": "cbartens/bkit",
463
- "bkitVersion": "4.2.0",
464
- "workflow": "plan",
465
- "step": "plan-generate",
466
- "subagent": "bkit-plan-generate",
467
- "model": "claude-opus-4-8",
468
545
  "key": "bkit-distribution-via-npmjs",
546
+ "repo": "cbartens/bkit",
547
+ "bkit": { "version": "5.6.0" },
548
+ "by": { "workflow": "plan", "step": "plan-generate", "subagent": "bkit-plan-generate", "model": "claude-opus-4-8" },
469
549
  "summary": "publish @cbartens/bkit publicly on npmjs",
470
550
  "description": "publish @cbartens/bkit publicly on npmjs; consumers install with no registry mapping, PAT, or CI/Vercel env",
471
551
  "rationale": "public install needs no registry mapping or token; release.yml publishes from CI via npm OIDC trusted publishing",
@@ -480,13 +560,13 @@ Indented for readability — **on disk each row = single physical line** (§ Wri
480
560
  <!-- prettier-ignore -->
481
561
  ```jsonl
482
562
  {
563
+ "schema": 3,
483
564
  "ts": 1718900000800,
484
565
  "kind": "feature",
485
- "repo": "cbartens/bkit",
486
- "bkitVersion": "4.2.0",
487
- "workflow": "build",
488
- "step": "build-close-workflow",
489
566
  "key": "412-export-csv",
567
+ "repo": "cbartens/bkit",
568
+ "bkit": { "version": "5.6.0" },
569
+ "by": { "workflow": "build", "step": "build-close-workflow" },
490
570
  "category": "correctness",
491
571
  "summary": "CSV export for the reporting page",
492
572
  "description": "adds a bounded CSV export button to the reporting page, streamed server-side",
@@ -22,7 +22,7 @@ NEVER a lite workflow for: schema / migrations, public API, dependencies, secret
22
22
 
23
23
  ## Contract
24
24
 
25
- Read `.agents/rules.md`. Work on the current branch; commit as you go; push only when shipping or when asked. Tracker-wired: issue → **In progress** + `bkit:<phase>` label at start (drops other `bkit:*` workflow labels, `next:*`, `bkit:failed` per `.agents/rules.md` § Tracker workflow labels), **In review** at end, one short comment per step. No tracker: skip the tracker lines.
25
+ Read `.agents/rules.md`. Work on the current branch; commit as you go; push only when shipping or when asked. Tracker-wired: issue → the `package.json` `bkit.tracker.<tracker>.progress` state (default github `In progress`, linear `started`, jira `In Progress`) + `bkit:<phase>` label at start (drops other `bkit:*` workflow labels, `next:*`, `bkit:failed` per `.agents/rules.md` § Tracker workflow labels), the `bkit.tracker.<tracker>.review` state (default `In review` on github, `In Review` on linear and jira) at end, one short comment per step. No tracker, or no issue named: skip the tracker lines.
26
26
 
27
27
  ## Paste
28
28