@cbartens/bkit 0.0.0-stage → 5.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 (373) hide show
  1. package/.bkit/README.md +421 -0
  2. package/.bkit/core/.agents/context.md +95 -0
  3. package/.bkit/core/.agents/docs.md +62 -0
  4. package/.bkit/core/.agents/rules.md +147 -0
  5. package/.bkit/core/.agents/skills.md +43 -0
  6. package/.bkit/core/.bkit/LICENSE.md +151 -0
  7. package/.bkit/core/.bkit/README.md +421 -0
  8. package/.bkit/core/.bkit/cloud.md +502 -0
  9. package/.bkit/core/.bkit/comparison.md +318 -0
  10. package/.bkit/core/.bkit/install.md +496 -0
  11. package/.bkit/core/.bkit/jsonl.md +497 -0
  12. package/.bkit/core/.bkit/prompts.md +474 -0
  13. package/.bkit/core/.bkit/providers.md +598 -0
  14. package/.bkit/core/.bkit/templates.md +471 -0
  15. package/.bkit/core/.bkit/trackers.md +95 -0
  16. package/.bkit/core/.bkit/workflows.md +1546 -0
  17. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +82 -0
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +93 -0
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +74 -0
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +115 -0
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +135 -0
  22. package/.bkit/core/.cursor/hooks/bkit-gateguard.cjs +111 -0
  23. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +169 -0
  24. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +63 -0
  25. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +225 -0
  26. package/.bkit/core/AGENTS.md +77 -0
  27. package/.bkit/core/LICENSE.md +149 -0
  28. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +272 -0
  29. package/.bkit/core/docs/templates/bkit-audit-adoption.md +223 -0
  30. package/.bkit/core/docs/templates/bkit-audit-agents.md +230 -0
  31. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +227 -0
  32. package/.bkit/core/docs/templates/bkit-audit-analytics.md +266 -0
  33. package/.bkit/core/docs/templates/bkit-audit-annotations.md +230 -0
  34. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +270 -0
  35. package/.bkit/core/docs/templates/bkit-audit-app-store.md +254 -0
  36. package/.bkit/core/docs/templates/bkit-audit-architecture.md +221 -0
  37. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +241 -0
  38. package/.bkit/core/docs/templates/bkit-audit-config.md +230 -0
  39. package/.bkit/core/docs/templates/bkit-audit-cost.md +218 -0
  40. package/.bkit/core/docs/templates/bkit-audit-coverage.md +221 -0
  41. package/.bkit/core/docs/templates/bkit-audit-database.md +229 -0
  42. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +251 -0
  43. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +283 -0
  44. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +268 -0
  45. package/.bkit/core/docs/templates/bkit-audit-documentation.md +280 -0
  46. package/.bkit/core/docs/templates/bkit-audit-duplication.md +253 -0
  47. package/.bkit/core/docs/templates/bkit-audit-failures.md +259 -0
  48. package/.bkit/core/docs/templates/bkit-audit-flakes.md +237 -0
  49. package/.bkit/core/docs/templates/bkit-audit-gates.md +250 -0
  50. package/.bkit/core/docs/templates/bkit-audit-issues.md +273 -0
  51. package/.bkit/core/docs/templates/bkit-audit-llm.md +239 -0
  52. package/.bkit/core/docs/templates/bkit-audit-logs.md +266 -0
  53. package/.bkit/core/docs/templates/bkit-audit-models.md +210 -0
  54. package/.bkit/core/docs/templates/bkit-audit-privacy.md +211 -0
  55. package/.bkit/core/docs/templates/bkit-audit-prompts.md +216 -0
  56. package/.bkit/core/docs/templates/bkit-audit-red-team.md +220 -0
  57. package/.bkit/core/docs/templates/bkit-audit-reliability.md +222 -0
  58. package/.bkit/core/docs/templates/bkit-audit-repo.md +224 -0
  59. package/.bkit/core/docs/templates/bkit-audit-security.md +274 -0
  60. package/.bkit/core/docs/templates/bkit-audit-slop.md +200 -0
  61. package/.bkit/core/docs/templates/bkit-audit-testing.md +270 -0
  62. package/.bkit/core/docs/templates/bkit-audit-usability.md +237 -0
  63. package/.bkit/core/docs/templates/bkit-plan.md +476 -0
  64. package/.bkit/core/engine/checks/after/auth.ts +247 -0
  65. package/.bkit/core/engine/checks/after/ci-yml.ts +739 -0
  66. package/.bkit/core/engine/checks/after/github.ts +424 -0
  67. package/.bkit/core/engine/checks/after/index.ts +556 -0
  68. package/.bkit/core/engine/checks/after/managed.ts +217 -0
  69. package/.bkit/core/engine/checks/after/tools.ts +427 -0
  70. package/.bkit/core/engine/checks/after/vercel.ts +101 -0
  71. package/.bkit/core/engine/checks/before/context-fetch.ts +429 -0
  72. package/.bkit/core/engine/checks/before/env.ts +201 -0
  73. package/.bkit/core/engine/checks/before/files.ts +202 -0
  74. package/.bkit/core/engine/checks/before/index.ts +206 -0
  75. package/.bkit/core/engine/checks/before/mcp.ts +127 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +77 -0
  77. package/.bkit/core/engine/checks/before/version.ts +67 -0
  78. package/.bkit/core/engine/checks/status-holes.ts +479 -0
  79. package/.bkit/core/engine/cli.ts +871 -0
  80. package/.bkit/core/engine/commands/analysis.ts +550 -0
  81. package/.bkit/core/engine/commands/ci/ci.ts +483 -0
  82. package/.bkit/core/engine/commands/comply.ts +415 -0
  83. package/.bkit/core/engine/commands/harvest.ts +459 -0
  84. package/.bkit/core/engine/commands/install/check.ts +70 -0
  85. package/.bkit/core/engine/commands/install/doctor.ts +247 -0
  86. package/.bkit/core/engine/commands/install/install.ts +528 -0
  87. package/.bkit/core/engine/commands/install/uninstall.ts +972 -0
  88. package/.bkit/core/engine/commands/install/upgrade.ts +1026 -0
  89. package/.bkit/core/engine/commands/launch.ts +139 -0
  90. package/.bkit/core/engine/commands/lib.ts +494 -0
  91. package/.bkit/core/engine/commands/registry.ts +53 -0
  92. package/.bkit/core/engine/commands/setup/setup.ts +184 -0
  93. package/.bkit/core/engine/commands/telemetry.ts +32 -0
  94. package/.bkit/core/engine/commands/workflow/branches.ts +1514 -0
  95. package/.bkit/core/engine/commands/workflow/context.ts +961 -0
  96. package/.bkit/core/engine/commands/workflow/counters.ts +268 -0
  97. package/.bkit/core/engine/commands/workflow/fids.ts +243 -0
  98. package/.bkit/core/engine/commands/workflow/issues.ts +675 -0
  99. package/.bkit/core/engine/commands/workflow/ledgers.ts +575 -0
  100. package/.bkit/core/engine/commands/workflow/locks.ts +478 -0
  101. package/.bkit/core/engine/commands/workflow/prs.ts +1087 -0
  102. package/.bkit/core/engine/commands/workflow/repo.ts +220 -0
  103. package/.bkit/core/engine/commands/workflow/roadmap.ts +576 -0
  104. package/.bkit/core/engine/commands/workflow/runs.ts +2140 -0
  105. package/.bkit/core/engine/commands/workflow/runtime.ts +300 -0
  106. package/.bkit/core/engine/commands/workflow/skills.ts +118 -0
  107. package/.bkit/core/engine/commands/workflow/status.ts +455 -0
  108. package/.bkit/core/engine/commands/workflow/steps.ts +1300 -0
  109. package/.bkit/core/engine/commands/workflow/tests.ts +161 -0
  110. package/.bkit/core/engine/commands/workflow/workflows.ts +1573 -0
  111. package/.bkit/core/engine/commands/workflow/workstreams.ts +164 -0
  112. package/.bkit/core/engine/commands/workflow/worktrees.ts +534 -0
  113. package/.bkit/core/engine/install/cloud-env.ts +925 -0
  114. package/.bkit/core/engine/install/managed-block.ts +212 -0
  115. package/.bkit/core/engine/install/manifest.ts +448 -0
  116. package/.bkit/core/engine/install/modules/claude.ts +362 -0
  117. package/.bkit/core/engine/install/modules/cloud.ts +174 -0
  118. package/.bkit/core/engine/install/modules/codex.ts +219 -0
  119. package/.bkit/core/engine/install/modules/core.ts +600 -0
  120. package/.bkit/core/engine/install/modules/cursor.ts +231 -0
  121. package/.bkit/core/engine/install/modules/index.ts +242 -0
  122. package/.bkit/core/engine/install/modules/opencode.ts +573 -0
  123. package/.bkit/core/engine/install/placeholders.ts +108 -0
  124. package/.bkit/core/engine/install/template-copies.ts +119 -0
  125. package/.bkit/core/engine/install/version-file.ts +284 -0
  126. package/.bkit/core/engine/install/write.ts +467 -0
  127. package/.bkit/core/engine/ledgers/clamp-log.ts +32 -0
  128. package/.bkit/core/engine/ledgers/status.ts +213 -0
  129. package/.bkit/core/engine/ledgers/telemetry.ts +1143 -0
  130. package/.bkit/core/engine/render/hosts.ts +372 -0
  131. package/.bkit/core/engine/render/models.ts +323 -0
  132. package/.bkit/core/engine/render/parts.ts +38 -0
  133. package/.bkit/core/engine/render/trackers.ts +170 -0
  134. package/.bkit/core/engine/shared/egress.ts +345 -0
  135. package/.bkit/core/engine/shared/json.ts +16 -0
  136. package/.bkit/core/engine/shared/log-prefix.ts +9 -0
  137. package/.bkit/core/engine/shared/package-json.ts +29 -0
  138. package/.bkit/core/engine/shared/package-manager.ts +38 -0
  139. package/.bkit/core/engine/shared/package-roots.ts +163 -0
  140. package/.bkit/core/engine/shared/protected-paths.ts +164 -0
  141. package/.bkit/core/engine/shared/settings.ts +72 -0
  142. package/.bkit/core/engine/shared/timeouts.ts +20 -0
  143. package/.bkit/core/engine/tools/wording.ts +748 -0
  144. package/.bkit/core/hooks/gateguard-edit-payload.js +18 -0
  145. package/.bkit/core/hooks/gateguard-engine.js +193 -0
  146. package/.bkit/core/hooks/guardrails-shell.js +154 -0
  147. package/.bkit/core/hooks/guardrails-tiers.js +68 -0
  148. package/.bkit/core/hooks/preflight-linear.sh +73 -0
  149. package/.bkit/core/prompts/bkit-audit-generate.md +66 -0
  150. package/.bkit/core/prompts/bkit-build-challenge-1.md +79 -0
  151. package/.bkit/core/prompts/bkit-build-challenge-2.md +81 -0
  152. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +68 -0
  153. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +70 -0
  154. package/.bkit/core/prompts/bkit-build-challenge-tests.md +73 -0
  155. package/.bkit/core/prompts/bkit-build-install-skills.md +67 -0
  156. package/.bkit/core/prompts/bkit-build-plan-current.md +75 -0
  157. package/.bkit/core/prompts/bkit-build-plan-execute.md +72 -0
  158. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +73 -0
  159. package/.bkit/core/prompts/bkit-build-plan-verify.md +88 -0
  160. package/.bkit/core/prompts/bkit-build-summary.md +93 -0
  161. package/.bkit/core/prompts/bkit-debug-abort-handover.md +90 -0
  162. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +151 -0
  163. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +78 -0
  164. package/.bkit/core/prompts/bkit-debug-failure-soak.md +73 -0
  165. package/.bkit/core/prompts/bkit-debug-summary.md +95 -0
  166. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +72 -0
  167. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +72 -0
  168. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +75 -0
  169. package/.bkit/core/prompts/bkit-design-generate.md +110 -0
  170. package/.bkit/core/prompts/bkit-design-organise.md +85 -0
  171. package/.bkit/core/prompts/bkit-design-review-1.md +121 -0
  172. package/.bkit/core/prompts/bkit-design-review-2.md +111 -0
  173. package/.bkit/core/prompts/bkit-design-spike.md +97 -0
  174. package/.bkit/core/prompts/bkit-design-summary.md +106 -0
  175. package/.bkit/core/prompts/bkit-design-update.md +66 -0
  176. package/.bkit/core/prompts/bkit-plan-complexity-check.md +66 -0
  177. package/.bkit/core/prompts/bkit-plan-complexity-split.md +87 -0
  178. package/.bkit/core/prompts/bkit-plan-generate.md +74 -0
  179. package/.bkit/core/prompts/bkit-plan-review-1.md +90 -0
  180. package/.bkit/core/prompts/bkit-plan-review-2.md +80 -0
  181. package/.bkit/core/prompts/bkit-plan-review-3.md +92 -0
  182. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +84 -0
  183. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +84 -0
  184. package/.bkit/core/prompts/bkit-plan-summary.md +106 -0
  185. package/.bkit/core/prompts/bkit-plan-update.md +68 -0
  186. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +90 -0
  187. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +94 -0
  188. package/.bkit/core/prompts/bkit-ship-summary.md +77 -0
  189. package/.bkit/core/prompts/bkit-ship-update-docs.md +71 -0
  190. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +91 -0
  191. package/.bkit/core/prompts/bkit-utility-update-decisions.md +75 -0
  192. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +76 -0
  193. package/.bkit/core/prompts/bkit-utility-update-documentation.md +61 -0
  194. package/.bkit/core/prompts/bkit-utility-update-failures.md +76 -0
  195. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +75 -0
  196. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +82 -0
  197. package/.bkit/core/workflows/bkit-auto.md +121 -0
  198. package/.bkit/core/workflows/bkit-build.md +802 -0
  199. package/.bkit/core/workflows/bkit-debug.md +642 -0
  200. package/.bkit/core/workflows/bkit-design.md +495 -0
  201. package/.bkit/core/workflows/bkit-plan.md +510 -0
  202. package/.bkit/core/workflows/bkit-ship.md +650 -0
  203. package/.bkit/shared/.bkit/.env.example +108 -0
  204. package/.bkit/shared/.claude/bkit-cloud.md +117 -0
  205. package/.bkit/shared/.claude/settings.json +88 -0
  206. package/.bkit/shared/.codex/hooks.json +26 -0
  207. package/.bkit/shared/.cursor/bkit-cloud.md +84 -0
  208. package/.bkit/shared/.cursor/hooks.json +26 -0
  209. package/.bkit/shared/.cursor/mcp.json +15 -0
  210. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +12 -0
  211. package/.bkit/shared/.gitattributes +37 -0
  212. package/.bkit/shared/.mcp.json +16 -0
  213. package/.bkit/shared/.opencode/opencode.json +62 -0
  214. package/.bkit/shared/CLAUDE.md +11 -0
  215. package/.bkit/shared/LICENSE.md +22 -0
  216. package/.bkit/shared/docs/architecture.md +19 -0
  217. package/.bkit/shared/docs/data-schema.md +19 -0
  218. package/.bkit/shared/docs/deployments.md +438 -0
  219. package/.bkit/shared/docs/design.md +39 -0
  220. package/.bkit/shared/docs/noise.md +19 -0
  221. package/.bkit/shared/docs/observability.md +25 -0
  222. package/.bkit/shared/docs/security.md +42 -0
  223. package/.bkit/shared/docs/setup.md +30 -0
  224. package/.bkit/shared/docs/technology.md +18 -0
  225. package/.bkit/shared/docs/testing.md +413 -0
  226. package/.bkit/shared/gitignore +92 -0
  227. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +192 -0
  228. package/.bkit/templates/.cursor/Dockerfile +68 -0
  229. package/.bkit/templates/.cursor/environment.json +6 -0
  230. package/.bkit/templates/.cursor/settings.json +11 -0
  231. package/.bkit/templates/.envrc +7 -0
  232. package/.bkit/templates/.github/dependabot.yml +52 -0
  233. package/.bkit/templates/.github/renovate.json5 +239 -0
  234. package/.bkit/templates/.github/workflows/bkit-ci.yml +1082 -0
  235. package/.bkit/templates/.github/workflows/bkit-cloud.yml +566 -0
  236. package/.bkit/templates/.github/workflows/bkit-renovate.yml +107 -0
  237. package/.bkit/templates/.graphifyignore +108 -0
  238. package/.bkit/templates/.husky/pre-commit +16 -0
  239. package/.bkit/templates/.husky/pre-push +91 -0
  240. package/.bkit/templates/.lintstagedrc.json +3 -0
  241. package/.bkit/templates/.prettierignore +41 -0
  242. package/.bkit/templates/.serena/project.yml +243 -0
  243. package/.bkit/templates/.vale/styles/House/Filler.yml +11 -0
  244. package/.bkit/templates/.vale/styles/House/Hedging.yml +12 -0
  245. package/.bkit/templates/.vale/styles/House/LLMSlop.yml +13 -0
  246. package/.bkit/templates/.vale/styles/House/Verbose.yml +12 -0
  247. package/.bkit/templates/.vale.ini +67 -0
  248. package/.bkit/templates/LICENSE.md +22 -0
  249. package/.bkit/templates/context/bkit-cloudrun.md +84 -0
  250. package/.bkit/templates/context/bkit-expo.md +186 -0
  251. package/.bkit/templates/context/bkit-github.md +79 -0
  252. package/.bkit/templates/context/bkit-inngest.md +45 -0
  253. package/.bkit/templates/context/bkit-maestro.md +76 -0
  254. package/.bkit/templates/context/bkit-playwright.md +62 -0
  255. package/.bkit/templates/context/bkit-resend.md +36 -0
  256. package/.bkit/templates/context/bkit-sentry.md +65 -0
  257. package/.bkit/templates/context/bkit-serena.md +33 -0
  258. package/.bkit/templates/context/bkit-stripe.md +36 -0
  259. package/.bkit/templates/context/bkit-supabase.md +59 -0
  260. package/.bkit/templates/context/bkit-tavily.md +49 -0
  261. package/.bkit/templates/context/bkit-vercel.md +64 -0
  262. package/.bkit/templates/docs/capabilities.md +72 -0
  263. package/.bkit/templates/scripts/ci/accepted-divergences.json +21 -0
  264. package/.bkit/templates/scripts/ci/check-accepted-divergences.mjs +152 -0
  265. package/.bkit/templates/scripts/ci/check-accepted-divergences.test.mjs +130 -0
  266. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +98 -0
  267. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +86 -0
  268. package/.bkit/templates/scripts/graphify/bkit-graph-drift-rules.json +23 -0
  269. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +208 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-eager-rules.json +35 -0
  271. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +236 -0
  272. package/.bkit/templates/scripts/graphify/bkit-graph-external-rules.json +17 -0
  273. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +290 -0
  274. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +19 -0
  275. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +120 -0
  276. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +232 -0
  277. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +36 -0
  278. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +927 -0
  279. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +351 -0
  280. package/.bkit/templates/scripts/launchd/ai.bkit.launchd.plist +26 -0
  281. package/.bkit/templates/scripts/launchd/bkit-launchd-env.sh +53 -0
  282. package/.bkit/templates/scripts/launchd/launchd.env.example +13 -0
  283. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +275 -0
  284. package/.bkit/templates/scripts/secrets/bkit-secrets.config.mjs +66 -0
  285. package/.bkit/templates/scripts/secrets/bkit-secrets.mjs +785 -0
  286. package/.bkit/templates/scripts/serena/bkit-serena-mcp.sh +30 -0
  287. package/.bkit/templates/scripts/serena/bkit-serena.mcp.json +9 -0
  288. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +286 -0
  289. package/.bkit/templates/slop-scan.config.json +120 -0
  290. package/CHANGELOG.md +1486 -0
  291. package/LICENSE.md +161 -0
  292. package/README.md +185 -2
  293. package/dist/checks/after/auth.js +232 -0
  294. package/dist/checks/after/ci-yml.js +718 -0
  295. package/dist/checks/after/github.js +400 -0
  296. package/dist/checks/after/index.js +447 -0
  297. package/dist/checks/after/managed.js +187 -0
  298. package/dist/checks/after/tools.js +351 -0
  299. package/dist/checks/after/vercel.js +102 -0
  300. package/dist/checks/before/context-fetch.js +426 -0
  301. package/dist/checks/before/env.js +173 -0
  302. package/dist/checks/before/files.js +185 -0
  303. package/dist/checks/before/index.js +162 -0
  304. package/dist/checks/before/mcp.js +111 -0
  305. package/dist/checks/before/repo.js +71 -0
  306. package/dist/checks/before/version.js +60 -0
  307. package/dist/checks/status-holes.js +393 -0
  308. package/dist/cli.js +692 -0
  309. package/dist/commands/analysis.js +325 -0
  310. package/dist/commands/ci/ci.js +438 -0
  311. package/dist/commands/comply.js +310 -0
  312. package/dist/commands/harvest.js +354 -0
  313. package/dist/commands/install/check.js +61 -0
  314. package/dist/commands/install/doctor.js +207 -0
  315. package/dist/commands/install/install.js +461 -0
  316. package/dist/commands/install/uninstall.js +815 -0
  317. package/dist/commands/install/upgrade.js +771 -0
  318. package/dist/commands/launch.js +118 -0
  319. package/dist/commands/lib.js +362 -0
  320. package/dist/commands/registry.js +50 -0
  321. package/dist/commands/setup/setup.js +158 -0
  322. package/dist/commands/telemetry.js +29 -0
  323. package/dist/commands/workflow/branches.js +1265 -0
  324. package/dist/commands/workflow/context.js +846 -0
  325. package/dist/commands/workflow/counters.js +227 -0
  326. package/dist/commands/workflow/fids.js +224 -0
  327. package/dist/commands/workflow/issues.js +585 -0
  328. package/dist/commands/workflow/ledgers.js +472 -0
  329. package/dist/commands/workflow/locks.js +364 -0
  330. package/dist/commands/workflow/prs.js +904 -0
  331. package/dist/commands/workflow/repo.js +199 -0
  332. package/dist/commands/workflow/roadmap.js +495 -0
  333. package/dist/commands/workflow/runs.js +1717 -0
  334. package/dist/commands/workflow/runtime.js +257 -0
  335. package/dist/commands/workflow/skills.js +110 -0
  336. package/dist/commands/workflow/status.js +392 -0
  337. package/dist/commands/workflow/steps.js +1093 -0
  338. package/dist/commands/workflow/tests.js +144 -0
  339. package/dist/commands/workflow/workflows.js +1342 -0
  340. package/dist/commands/workflow/workstreams.js +141 -0
  341. package/dist/commands/workflow/worktrees.js +473 -0
  342. package/dist/install/cloud-env.js +819 -0
  343. package/dist/install/managed-block.js +182 -0
  344. package/dist/install/manifest.js +376 -0
  345. package/dist/install/modules/claude.js +288 -0
  346. package/dist/install/modules/cloud.js +152 -0
  347. package/dist/install/modules/codex.js +193 -0
  348. package/dist/install/modules/core.js +511 -0
  349. package/dist/install/modules/cursor.js +186 -0
  350. package/dist/install/modules/index.js +152 -0
  351. package/dist/install/modules/opencode.js +504 -0
  352. package/dist/install/placeholders.js +87 -0
  353. package/dist/install/template-copies.js +106 -0
  354. package/dist/install/version-file.js +204 -0
  355. package/dist/install/write.js +342 -0
  356. package/dist/ledgers/clamp-log.js +27 -0
  357. package/dist/ledgers/status.js +156 -0
  358. package/dist/ledgers/telemetry.js +637 -0
  359. package/dist/render/hosts.js +339 -0
  360. package/dist/render/models.js +288 -0
  361. package/dist/render/parts.js +33 -0
  362. package/dist/render/trackers.js +135 -0
  363. package/dist/shared/egress.js +299 -0
  364. package/dist/shared/json.js +16 -0
  365. package/dist/shared/log-prefix.js +7 -0
  366. package/dist/shared/package-json.js +22 -0
  367. package/dist/shared/package-manager.js +32 -0
  368. package/dist/shared/package-roots.js +145 -0
  369. package/dist/shared/protected-paths.js +153 -0
  370. package/dist/shared/settings.js +44 -0
  371. package/dist/shared/timeouts.js +19 -0
  372. package/dist/tools/wording.js +680 -0
  373. package/package.json +101 -4
@@ -0,0 +1,497 @@
1
+ # JSONL Entry Format
2
+
3
+ {{BKIT_MANAGED_MARKER}}
4
+
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.
7
+ >
8
+ > **Rules:**
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).
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).
16
+ > - Best-effort append — always exit 0; never gate workflows on telemetry success.
17
+
18
+ ## Write Idiom
19
+
20
+ ```bash
21
+ jq -c -n '{ ts: null, kind: "deferral", repo: $REPO, bkitVersion: $VER, step: $STEP, … } | .ts = (now*1000|floor)' \
22
+ >> "$FILE" || echo "[bkit-telemetry] append failed: $FILE"
23
+ ```
24
+
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.
27
+ - **Log prefix:** every telemetry log line starts `[bkit-telemetry]` — load-bearing for log-drain grep.
28
+
29
+ ## Ledgers & Writers
30
+
31
+ One file per `kind`; writers:
32
+
33
+ <!-- prettier-ignore -->
34
+ | Kind | File | Written by |
35
+ | --- | --- | --- |
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) |
39
+ | `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) |
41
+ | `failure` | `docs/failures.jsonl` | any agent on a discovered bug; `@bkit-debug-abort-handover`; `@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) |
44
+ | `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
+
46
+ **Writers are exhaustive:** only agents listed as writers for a given kind are allowed to write that specific kind; no exceptions.
47
+
48
+ ## Generic Fields (all kinds)
49
+
50
+ <!-- prettier-ignore -->
51
+ | Field | Type | Meaning |
52
+ | --- | --- | --- |
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` (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. |
61
+ | `references` | `string[]?` | Pointers that place the row: feature ids, tracker ids, PRs, commit SHAs, paths, a sibling `ts`. See § Key & References. |
62
+
63
+ ## Per-Kind Fields
64
+
65
+ <!-- prettier-ignore -->
66
+ | Kind | Fields (beyond envelope) |
67
+ | --- | --- |
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`. |
71
+ | `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
+ | `deferral` | `key`, `type:"issue"\|"feature"`, `category` (§ Categories), `severity`, `reason` (§ Deferral Reason), `summary?`, `description`, `remediation?`, `source?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"?`. |
73
+ | `failure` | `key`, `category?` (§ Categories; `"testing"` = flaky/intermittent test), `summary?`, `severity`, `description`, `rootCause?`, `remediation?`, `status:"OPEN"\|"TRIAGED"\|"CLOSED"\|string?`. |
74
+ | `knowledge` | `key`, `summary`, `description?`, `rootCause?`, `remediation?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
75
+ | `decision` | `key`, `summary`, `description?`, `rationale?`, `alternatives?`, `status:"ACTIVE"\|"SUPERSEDED"?`. |
76
+ | `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
+
78
+ ## Who Wrote It — `step` vs `subagent` vs `model`
79
+
80
+ <!-- prettier-ignore -->
81
+ | Row written by | `workflow` | `step` | `subagent` | `model` |
82
+ | --- | --- | --- | --- | --- |
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:` |
85
+
86
+ Subagent: on every appended row, from your prompt file:
87
+
88
+ - **`subagent`** = your frontmatter `name:`.
89
+ - **`model`** = your frontmatter `model:`.
90
+ - **`step`** = invoking workflow step (named in your Context).
91
+
92
+ Orchestrator: omit `subagent` and `model`.
93
+
94
+ ## Key & References
95
+
96
+ `key` = written-once stable slug; recurrence = same-`key` append.
97
+
98
+ - **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.
99
+ - **Cite the `key`.** Identity for other rows, docs, memory; `ts` = tiebreaker. Content slugs avoid counter collisions.
100
+
101
+ `references` = pointers placing this row:
102
+
103
+ <!-- prettier-ignore -->
104
+ ```jsonl
105
+ "references": ["681", "ISSUE-217", "PR-412", "a1b2c3d", "docs/plans/202607/681-e2e-parallelism-design.md", "1718900000600"]
106
+ ```
107
+
108
+ - Feature ids / `{FID}`, tracker ids (`ISSUE-217`), PRs, commit SHAs, file paths, sibling row `ts`.
109
+ - Keep items as source wrote; trailing qualifiers (`ISSUE-142 §A2`) = meaning, not noise.
110
+ - No separate identity field: `ts` = id; `references` = pointers only.
111
+ - Omit when nothing to point at.
112
+
113
+ ## Friction Is a Drained Queue — the one non-append-only ledger
114
+
115
+ `.bkit/friction.jsonl` = drained work queue — only file rows are removed from:
116
+
117
+ <!-- prettier-ignore -->
118
+ | Actor | May do |
119
+ | --- | --- |
120
+ | **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. |
122
+
123
+ Row vanishing from `.bkit/friction.jsonl` = `bkit harvest` banked it centrally.
124
+
125
+ Prune gates (in order):
126
+
127
+ - **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.
129
+ - **Malformed lines** — never pruned.
130
+ - **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
+
132
+ `stats.jsonl` = COPY-only; `deferrals` / `failures` = COUNT-only (envelope metadata; prose never leaves consumer). Contract: `.bkit/core/engine/commands/harvest.ts`.
133
+
134
+ ## Summary vs Description
135
+
136
+ Kinds with both (`friction` / `deferral` / `failure` / `knowledge` / `decision` / `feature`): `summary` = short title; `description` = prose. One sentence → `description` only.
137
+
138
+ ## Severity
139
+
140
+ `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:
141
+
142
+ <!-- prettier-ignore -->
143
+ | Value | Means |
144
+ | --- | --- |
145
+ | `CRITICAL` | Data loss, security hole, or a broken workflow with no workaround. Triage before the next release. |
146
+ | `HIGH` | Real damage or a blocked path, but a workaround exists. |
147
+ | `MEDIUM` | Degraded behaviour or a repeated cost; safe to schedule. |
148
+ | `LOW` | Cosmetic, nit, or a speculative future idea. |
149
+
150
+ - Same enum the challenge prompts assign. Finding → row (e.g. `@bkit-build-challenge-remediate` BLOCKED → `docs/deferrals.jsonl`): carry ITS severity unchanged.
151
+ - not `bkit install` preflight `blocker` / `advisory` — different axis.
152
+ - Pick level the ROW earns. All-`LOW` ledger = useless as no severity.
153
+
154
+ ## Deferral Reason
155
+
156
+ `reason` required on `deferral`, absent elsewhere. Why the work is deferred — distinct from `status` (how far) and `severity` (how much). Closed enum, lowercase:
157
+
158
+ <!-- prettier-ignore -->
159
+ | Value | Means | Also required |
160
+ | --- | --- | --- |
161
+ | `scope-declared` | design/plan called it out of scope before work started. | `references` to that doc §. |
162
+ | `hard-blocked` | external blocker (credential, upstream fix, feature) blocks it now. | Name blocker in `description`. |
163
+ | `needs-decision` | human decision missing; guessing worse than waiting. | State decision + options. |
164
+ | `own-cycle` | plan-sized — new architecture, not a mechanical fix. | Say what makes it plan-sized. |
165
+ | `unjustified` | ADJUDICATOR-only — in-scope work that should have been finished. | Which test it failed. |
166
+
167
+ - First four → deferral. None fit → unfinished work, do IT (`.agents/rules.md` § "Finish over deferrals").
168
+ - `unjustified` never self-assigned — writer picks first four; reviewer adjudicating another's deferral sets it via same-`key` append.
169
+ - Set once, carried verbatim by every later row — the rate it feeds counts the deferral that should not have been written.
170
+ - No free prose — an unadjudicable reason reads as justification while being none; the enum closes that.
171
+
172
+ **The four tests.** Reviewer marks `unjustified` when all hold:
173
+
174
+ 1. `remediation` names specific files + a bounded edit, not a new architecture.
175
+ 2. Surface inside files the cycle already touched.
176
+ 3. No external blocker — no missing decision, credential, upstream fix, confirmation.
177
+ 4. `scope-declared` with no pre-existing declaration — the row is the only place it was called out of scope.
178
+
179
+ Test 4 carries the weight: genuine deferral declared out of scope before work started; unjustified declared at moment of avoidance. Both timestamps in ledger.
180
+
181
+ ## Ship Date
182
+
183
+ `shippedAt` OPTIONAL on `feature`, absent elsewhere. Unix ms the feature shipped. `docs/roadmap.md` § Shipped ranks on `shippedAt // ts`.
184
+
185
+ - 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.
186
+ - may be a literal (unlike `ts`, § Write Idiom) — it is not row identity. Source it: issue `closed_at`, merge-commit date.
187
+ - never a guess. No defensible source = omit and accept `ts` ordering.
188
+
189
+ ## Categories
190
+
191
+ Free-form; closest term, `other` if none. `deferral` + `failure` → domain set; `friction` → friction set — do not mix.
192
+
193
+ **Domain — `deferral` + `failure`:**
194
+
195
+ <!-- prettier-ignore -->
196
+ | Term | Covers |
197
+ | --- | --- |
198
+ | `agentic` | agent / workflow / prompt / orchestration behaviour |
199
+ | `correctness` | logic / behaviour bugs in shipped code |
200
+ | `testing` | tests, coverage, flaky / intermittent tests (see note below) |
201
+ | `infra` | CI, build, packaging, distribution, deploy, environment |
202
+ | `tooling` | CLI, dev scripts, local tooling |
203
+ | `observability` | logging, telemetry, tracing, metrics |
204
+ | `security` | auth, secrets, input validation, data exposure |
205
+ | `architecture` | structural / design |
206
+ | `docs` | documentation |
207
+ | `other` | none of the above |
208
+
209
+ **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.
210
+
211
+ **Friction — `friction`:**
212
+
213
+ <!-- prettier-ignore -->
214
+ | Term | Covers |
215
+ | --- | --- |
216
+ | `human-confirm` | human confirmation prompt |
217
+ | `permission-prompt` | tool / permission approval prompt |
218
+ | `agent-rework` | agent redo / self-correction |
219
+ | `manual-install` | manual dependency / tool install |
220
+ | `tool-failure` | tool / command error |
221
+ | `destructive-backout` | reverted a destructive action |
222
+ | `other` | none of the above |
223
+
224
+ ## Updating a Row
225
+
226
+ Fields that change after first write:
227
+
228
+ <!-- prettier-ignore -->
229
+ | Field | Changes when |
230
+ | --- | --- |
231
+ | `status` | work closes (`OPEN` -> `CLOSED`), or a decision or knowledge row is `SUPERSEDED`. |
232
+ | `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. |
233
+ | `remediation` | the fix is known — usually after the row was logged mid-workflow. |
234
+ | `severity` | re-triage says it was worse or milder than first thought. |
235
+ | `confidence` | (`friction` only) the same thing recurs (raise) or is contradicted (lower). |
236
+ | `lastConfirmed` | (`friction` only) re-observed. |
237
+ | `recurrenceCount` | (`friction` only) it happens again. |
238
+
239
+ **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.
240
+
241
+ **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
+
243
+ - **NEVER edit or delete a line.** Correct via same-`key` append.
244
+ - **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
+
246
+ `.bkit/friction.jsonl` excluded — rows are removed from it (§ Friction Is a Drained Queue); union would resurrect a drain.
247
+
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`.
249
+
250
+ **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
+
252
+ **`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.
253
+
254
+ **`TRIAGED` is STILL open WORK.** Open-entry counts — CI gate on open `CRITICAL` failures, audit debt lens, age report — test `status != "CLOSED"`. Only `CLOSED` is done.
255
+
256
+ Not on `knowledge` or `decision` — both use `ACTIVE` / `SUPERSEDED`. Absent `status` = `ACTIVE`.
257
+
258
+ **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.
259
+
260
+ Readers count ENTITIES, never lines — `fold` first.
261
+
262
+ ## These Ledgers Are Inputs, Not a Diary
263
+
264
+ `docs/deferrals.jsonl` + `docs/failures.jsonl` = backlog — deferred scope + known bugs; `severity` ranks, `ts` ages. READ:
265
+
266
+ - **Before designing or planning** — grep for existing entry or past deferral reason.
267
+ - **On a triage sweep** — walk open entries vs tracker + codebase; close, `TRIAGED`, or re-`severity` via append (§ Updating a Row).
268
+ - **When a bug looks familiar** — same-`key` `failure` = recurrence.
269
+
270
+ Rank existing: `severity: CRITICAL` first, then oldest `ts`.
271
+
272
+ ## Identity / Dedup
273
+
274
+ Identity tuple, not bare `ts`:
275
+
276
+ <!-- prettier-ignore -->
277
+ | Kind | Identity tuple |
278
+ | --- | --- |
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)` |
283
+
284
+ Identity match = same thing — not automatically skip:
285
+
286
+ - **Nothing changed** -> skip.
287
+ - **Something changed** -> **append** (§ Updating a Row).
288
+
289
+ ## Versioning
290
+
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.
292
+
293
+ ## Examples
294
+
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:
296
+
297
+ `.bkit/stats.jsonl` (`compliance` / `outcome` / `counter`):
298
+
299
+ <!-- prettier-ignore -->
300
+ ```jsonl
301
+ {
302
+ "ts": 1718900000000,
303
+ "kind": "compliance",
304
+ "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"
313
+ }
314
+ {
315
+ "ts": 1718900000100,
316
+ "kind": "outcome",
317
+ "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
+ "sweepVerdict": "clean",
338
+ "coverage": { "unit": { "lines": 87.4, "branches": 79.1, "functions": 90.2, "statements": 87.0 }, "integration": { "lines": 68.3 }, "e2e": { "lines": 41.5 } }
339
+ }
340
+ {
341
+ "ts": 1718900000200,
342
+ "kind": "counter",
343
+ "repo": "cbartens/bkit",
344
+ "bkitVersion": "4.2.0",
345
+ "workflow": "build",
346
+ "step": "build-close-workflow",
347
+ "counterName": "BUILD_ATTEMPT",
348
+ "counterValue": 2,
349
+ "counterSource": "shell-bus",
350
+ "parentSha": "a1b2c3d"
351
+ }
352
+ ```
353
+
354
+ `.bkit/friction.jsonl`:
355
+
356
+ <!-- prettier-ignore -->
357
+ ```jsonl
358
+ {
359
+ "ts": 1718900000300,
360
+ "kind": "friction",
361
+ "repo": "cbartens/bkit",
362
+ "bkitVersion": "4.2.0",
363
+ "workflow": "ship",
364
+ "step": "ship-update-docs",
365
+ "key": "ship-dev-commit-blocked-by-pre-commit-hook",
366
+ "category": "tool-failure",
367
+ "scope": "bkit-repo",
368
+ "severity": "HIGH",
369
+ "summary": "ship Step 9 dev commit blocked by the pre-commit hook",
370
+ "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",
371
+ "remediation": "commit via a temp branch (docs/ship-{FID}) from dev in a temp worktree, then FF-merge dev",
372
+ "source": "orchestrator",
373
+ "status": "OPEN",
374
+ "confidence": 0.9,
375
+ "lastConfirmed": 1721578400000,
376
+ "recurrenceCount": 2,
377
+ "references": ["342", "docs/plans/202607/342-injection-hardening-plan.md"]
378
+ }
379
+ ```
380
+
381
+ `docs/deferrals.jsonl`:
382
+
383
+ <!-- prettier-ignore -->
384
+ ```jsonl
385
+ {
386
+ "ts": 1718900000400,
387
+ "kind": "deferral",
388
+ "repo": "cbartens/bkit",
389
+ "bkitVersion": "4.2.0",
390
+ "workflow": "design",
391
+ "step": "design-brainstorm",
392
+ "subagent": "bkit-design-generate",
393
+ "model": "claude-opus-4-8",
394
+ "key": "pnpm-tag-drop-readme-note",
395
+ "type": "issue",
396
+ "category": "infra",
397
+ "severity": "LOW",
398
+ "reason": "scope-declared",
399
+ "summary": "pnpm tag-drop README note for the install snippet",
400
+ "description": "pnpm normaliser strips the #vX.Y.Z pin from github:cbartens/bkit git-dep entries in package.json; document the workaround in README or fix upstream",
401
+ "remediation": "note the pin workaround in the README install snippet",
402
+ "source": "phase",
403
+ "status": "OPEN",
404
+ "references": ["ISSUE-131", "ISSUE-130", "README.md", "docs/plans/202607/131-install-snippet-design.md § Non-goals"]
405
+ }
406
+ ```
407
+
408
+ `docs/failures.jsonl`:
409
+
410
+ <!-- prettier-ignore -->
411
+ ```jsonl
412
+ {
413
+ "ts": 1718900000500,
414
+ "kind": "failure",
415
+ "repo": "cbartens/bkit",
416
+ "bkitVersion": "4.2.0",
417
+ "workflow": "debug",
418
+ "step": "debug-diagnose",
419
+ "subagent": "bkit-debug-failure-diagnose",
420
+ "model": "claude-opus-4-8",
421
+ "key": "bkit-install-flips-core-bare",
422
+ "category": "tooling",
423
+ "summary": "bkit install flips core.bare=true",
424
+ "severity": "HIGH",
425
+ "description": "`pnpm bkit install` leaves git config core.bare=true, which breaks git checkout/status afterward",
426
+ "rootCause": "the install engine writes core.bare while staging and does not restore it on the success path",
427
+ "remediation": "run `git config core.bare false` after install",
428
+ "status": "OPEN",
429
+ "references": ["176", "a1b2c3d", ".bkit/core/engine/commands/install/install.ts"]
430
+ }
431
+ ```
432
+
433
+ `docs/knowledge.jsonl`:
434
+
435
+ <!-- prettier-ignore -->
436
+ ```jsonl
437
+ {
438
+ "ts": 1718900000600,
439
+ "kind": "knowledge",
440
+ "repo": "cbartens/bkit",
441
+ "bkitVersion": "4.2.0",
442
+ "workflow": "debug",
443
+ "step": "debug-remediate",
444
+ "subagent": "bkit-debug-failure-remediate",
445
+ "model": "claude-sonnet-4-6",
446
+ "key": "gh-mcp-401-after-token-rotation",
447
+ "summary": "GitHub MCP / gh 401 immediately after a token rotation",
448
+ "description": "401 from the GitHub MCP server or gh despite a freshly-rotated, valid, correctly-scoped PAT in .bkit/.env",
449
+ "rootCause": "the MCP server captures GH_MCP_TOKEN at process launch, so a mid-session rotation leaves it holding the dead token",
450
+ "remediation": "restart/reload the MCP server after rotating; for a one-off CLI, prefix `direnv exec . gh …`",
451
+ "status": "ACTIVE",
452
+ "references": ["ISSUE-137", ".bkit/.env"]
453
+ }
454
+ ```
455
+
456
+ `docs/decisions.jsonl`:
457
+
458
+ <!-- prettier-ignore -->
459
+ ```jsonl
460
+ {
461
+ "ts": 1718900000700,
462
+ "kind": "decision",
463
+ "repo": "cbartens/bkit",
464
+ "bkitVersion": "4.2.0",
465
+ "workflow": "plan",
466
+ "step": "plan-generate",
467
+ "subagent": "bkit-plan-generate",
468
+ "model": "claude-opus-4-8",
469
+ "key": "bkit-distribution-via-github-packages",
470
+ "summary": "distribute @cbartens/bkit via the GitHub Packages npm registry",
471
+ "description": "move @cbartens/bkit off the github: git-dep install onto the GitHub Packages npm registry",
472
+ "rationale": "eliminates four friction classes of the git-dep model: two-surface git auth, the CI auth shim, the prepare:tsc OOM trap, and pnpm dropping the version pin",
473
+ "alternatives": "npmjs.org public (package is private), continue git-dep, Releases tarball, vendor per-consumer, dual-publish git+registry",
474
+ "status": "ACTIVE",
475
+ "references": ["ISSUE-138", "ISSUE-130", "package.json", ".github/workflows/release.yml"]
476
+ }
477
+ ```
478
+
479
+ `.bkit/issues.jsonl`:
480
+
481
+ <!-- prettier-ignore -->
482
+ ```jsonl
483
+ {
484
+ "ts": 1718900000800,
485
+ "kind": "feature",
486
+ "repo": "cbartens/bkit",
487
+ "bkitVersion": "4.2.0",
488
+ "workflow": "build",
489
+ "step": "build-close-workflow",
490
+ "key": "412-export-csv",
491
+ "category": "correctness",
492
+ "summary": "CSV export for the reporting page",
493
+ "description": "adds a bounded CSV export button to the reporting page, streamed server-side",
494
+ "status": "BUILT",
495
+ "references": ["412", "docs/plans/202607/412-export-csv-plan.md"]
496
+ }
497
+ ```