@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -11,7 +11,10 @@ import { spawnSync } from "node:child_process";
11
11
  import * as fs from "node:fs";
12
12
  import * as os from "node:os";
13
13
  import * as path from "node:path";
14
- import { gitEnv } from "../ledgers/telemetry.js";
14
+ import { appendFrictionRow, appendJournalRow, engineCallRow, frictionRow, journalEnabled, launchedByGit, rebasePaused, shouldRecordFriction, } from "../ledgers/journal.js";
15
+ import { fold } from "../ledgers/status.js";
16
+ import { gitEnv, resolveGitSha } from "../ledgers/telemetry.js";
17
+ import { parseJson } from "../shared/json.js";
15
18
  import { renderText } from "../shared/text.js";
16
19
  // ---------------------------------------------------------------------------
17
20
  // Exit codes
@@ -49,6 +52,38 @@ export class CommandError extends Error {
49
52
  this.code = code;
50
53
  }
51
54
  }
55
+ /** Parse a whole-number flag, using its fallback only when absent. */
56
+ export const wholeNumber = (v, flag, fallback, min = 0) => {
57
+ if (v === undefined)
58
+ return fallback;
59
+ const s = String(v);
60
+ if (!/^[0-9]+$/.test(s) || Number(s) < min) {
61
+ throw new CommandError(EXIT.USAGE, `--${flag} takes a whole number >= ${min} (got "${s}")`);
62
+ }
63
+ return Number(s);
64
+ };
65
+ /** The holder named by this run when its tests-lock wait gave up. */
66
+ export function testsLockHolder(log, who) {
67
+ const prefix = `[machine-lock] ❌ ${who} gave up after `;
68
+ for (const line of log.split(/\r?\n/)) {
69
+ if (!line.startsWith(prefix))
70
+ continue;
71
+ const holder = /^\d+s waiting for tests, in use by (.+)$/.exec(line.slice(prefix.length));
72
+ if (holder)
73
+ return holder[1];
74
+ }
75
+ return null;
76
+ }
77
+ /** Classify only a tests-lock outcome, leaving gate and nested-lock failures intact. */
78
+ export function classifyLockExit({ exitCode, log, who, }) {
79
+ const lines = log.split(/\r?\n/);
80
+ if (exitCode === 75 && testsLockHolder(log, who) !== null)
81
+ return "lock-wait";
82
+ if (exitCode === 73 &&
83
+ lines.some((line) => /^\[machine-lock\] ❌ (?:could not take the lock for tests:|cannot take tests while holding )/.test(line)))
84
+ return "could-not-run";
85
+ return "gate";
86
+ }
52
87
  // ---------------------------------------------------------------------------
53
88
  // Flags
54
89
  // ---------------------------------------------------------------------------
@@ -211,6 +246,160 @@ function omitNote(spec, key) {
211
246
  return "";
212
247
  return typeof o === "string" ? " (--json only)" : " (text: only when it matters)";
213
248
  }
249
+ /** Row types `fold` reads; the other rows a `status.jsonl` carries (engine-call, ...) stay out of it. */
250
+ const FOLD_TYPES = new Set([
251
+ "workflow-started",
252
+ "step-done",
253
+ "workflow-meta",
254
+ "workflow-done",
255
+ "workflow-failed",
256
+ ]);
257
+ /** Most `status.jsonl` files `resolveActiveRun` reads when it walks a checkout. */
258
+ const ACTIVE_RUN_SCAN_CAP = 500;
259
+ /** The workflow of the last run in `file` when that run is IN_PROGRESS, else undefined. */
260
+ function inProgressWorkflow(file) {
261
+ if (!fs.existsSync(file))
262
+ return undefined;
263
+ const events = [];
264
+ for (const line of fs.readFileSync(file, "utf-8").split("\n")) {
265
+ if (line.trim() === "")
266
+ continue;
267
+ const parsed = parseJson(line);
268
+ if (!parsed.ok || parsed.value === null || typeof parsed.value !== "object")
269
+ continue;
270
+ const type = parsed.value.type;
271
+ if (typeof type === "string" && FOLD_TYPES.has(type))
272
+ events.push(parsed.value);
273
+ }
274
+ const last = fold(events).at(-1);
275
+ return last?.status === "IN_PROGRESS" ? last.workflow : undefined;
276
+ }
277
+ /** The directories under `dir`, by name; none when `dir` is missing. */
278
+ function subdirs(dir) {
279
+ if (!fs.existsSync(dir))
280
+ return [];
281
+ return fs
282
+ .readdirSync(dir, { withFileTypes: true })
283
+ .filter((e) => e.isDirectory())
284
+ .map((e) => e.name);
285
+ }
286
+ /**
287
+ * The run a command call belongs to, or undefined. In order: the command's own
288
+ * `--file`; `--fid` (+ `--month`, default this UTC month) through `statusLocation`;
289
+ * the single IN_PROGRESS run among the `docs/plans/<month>/logs/<fid>/status.jsonl`
290
+ * files under the cwd's git toplevel (capped), only `--fid`'s own when it is set, so a
291
+ * run from an earlier month is found and another feature's run never is. From the main checkout a feature
292
+ * worktree's run is not found, so an out-of-worktree call is skipped, never
293
+ * attributed to another run. Reads with this module's own `node:fs` and `parseJson`
294
+ * and folds with `ledgers/status.ts`, so it never imports a `commands/**` module.
295
+ */
296
+ export function resolveActiveRun(opts) {
297
+ // A `--file` that is a run's `status.jsonl` names that run; any other file (a plan or
298
+ // design doc) says nothing about the run and falls through to `--fid` and the scan.
299
+ if (opts.file !== undefined && path.basename(opts.file) === "status.jsonl") {
300
+ const file = path.resolve(opts.cwd, opts.file);
301
+ const workflow = inProgressWorkflow(file);
302
+ const logs = path.dirname(path.dirname(file));
303
+ if (workflow === undefined ||
304
+ path.basename(logs) !== "logs" ||
305
+ path.basename(path.dirname(path.dirname(logs))) !== "plans") {
306
+ return undefined;
307
+ }
308
+ return {
309
+ workflow,
310
+ file,
311
+ bookRoot: path.dirname(path.dirname(path.dirname(path.dirname(logs)))),
312
+ };
313
+ }
314
+ if (opts.fid !== undefined) {
315
+ try {
316
+ const loc = statusLocation({
317
+ cwd: opts.cwd,
318
+ workflow: opts.workflow ?? "build",
319
+ fid: opts.fid,
320
+ month: opts.month ?? utcMonth(),
321
+ });
322
+ const workflow = inProgressWorkflow(loc.path);
323
+ if (workflow !== undefined)
324
+ return { workflow, file: loc.path, bookRoot: loc.bookRoot };
325
+ }
326
+ catch (err) {
327
+ if (!(err instanceof CommandError))
328
+ throw err;
329
+ }
330
+ }
331
+ const top = git(opts.cwd, ["rev-parse", "--show-toplevel"]);
332
+ if (top === null)
333
+ return undefined;
334
+ const found = [];
335
+ let read = 0;
336
+ for (const month of subdirs(path.join(top, "docs", "plans"))) {
337
+ for (const fid of subdirs(path.join(top, "docs", "plans", month, "logs"))) {
338
+ if (++read > ACTIVE_RUN_SCAN_CAP)
339
+ return undefined;
340
+ if (opts.fid !== undefined && fid !== opts.fid)
341
+ continue;
342
+ const file = path.join(top, statusRelPath(month, fid));
343
+ const workflow = inProgressWorkflow(file);
344
+ if (workflow !== undefined)
345
+ found.push({ workflow, file, bookRoot: top });
346
+ }
347
+ }
348
+ return found.length === 1 ? found[0] : undefined;
349
+ }
350
+ /** The journal `runCommand` uses unless a caller injects one: writes into the active run's own books. */
351
+ function engineJournal() {
352
+ let resolved = false;
353
+ let run;
354
+ const active = (i) => {
355
+ if (!resolved) {
356
+ resolved = true;
357
+ const text = (v) => (typeof v === "string" ? v : undefined);
358
+ run = resolveActiveRun({
359
+ cwd: i.cwd,
360
+ file: text(i.flags["file"]),
361
+ fid: text(i.flags["fid"]),
362
+ month: text(i.flags["month"]),
363
+ workflow: text(i.flags["workflow"]),
364
+ });
365
+ }
366
+ return run;
367
+ };
368
+ return {
369
+ call(i) {
370
+ // A call git launched (a hook's `bkit disk prune`) writes no row to the tracked status file.
371
+ if (!journalEnabled() || launchedByGit())
372
+ return;
373
+ const r = active(i);
374
+ // A paused rebase refuses `--continue` while the tracked status file has an unstaged row.
375
+ if (r === undefined || rebasePaused(path.dirname(r.file)))
376
+ return;
377
+ const wrote = appendJournalRow(r.file, engineCallRow({ workflow: r.workflow, noun: i.noun, verb: i.verb, flags: i.argv }));
378
+ if (!wrote.ok)
379
+ throw new Error(wrote.error);
380
+ },
381
+ failure(i) {
382
+ if (!journalEnabled())
383
+ return;
384
+ const r = active(i);
385
+ if (r === undefined)
386
+ return;
387
+ const step = i.flags["step"];
388
+ const row = frictionRow({
389
+ workflow: r.workflow,
390
+ step: typeof step === "string" ? step : undefined,
391
+ noun: i.noun,
392
+ verb: i.verb,
393
+ code: i.code,
394
+ bookRoot: r.bookRoot,
395
+ parentSha: resolveGitSha("HEAD", r.bookRoot),
396
+ });
397
+ const wrote = appendFrictionRow(r.bookRoot, row);
398
+ if (!wrote.ok)
399
+ throw new Error(wrote.error);
400
+ },
401
+ };
402
+ }
214
403
  /**
215
404
  * Run `argv` (without the leading `bkit`) if it names a registered command.
216
405
  * Returns the exit code, or null when `argv` is not a command, so the caller falls
@@ -256,6 +445,25 @@ export async function runCommand(argv, commands, options) {
256
445
  io.stdout(ctx.json ? `${JSON.stringify(output)}\n` : renderText(textOutput(spec, output)));
257
446
  },
258
447
  };
448
+ // The journal never changes the verb's exit code, output or throw: each write is
449
+ // swallowed, and the first failure logs one line.
450
+ const journal = options.journal ?? engineJournal();
451
+ let journalWarned = false;
452
+ const guarded = (write) => {
453
+ try {
454
+ write();
455
+ }
456
+ catch (err) {
457
+ if (journalWarned)
458
+ return;
459
+ journalWarned = true;
460
+ io.stderr(`[bkit-telemetry] journal write failed: ${err.message}\n`);
461
+ }
462
+ };
463
+ const excluded = new Set([...Object.keys(SHARED_EXIT_CODES), ...Object.keys(spec.exitCodes ?? {})].map(Number));
464
+ let input;
465
+ /** undefined: not dispatched; null: the verb threw; a number: its exit code. */
466
+ let outcome;
259
467
  try {
260
468
  const own = rest.filter((arg) => arg !== JSON_FLAG);
261
469
  if (own.some((arg) => arg.startsWith(`${JSON_FLAG}=`))) {
@@ -263,14 +471,27 @@ export async function runCommand(argv, commands, options) {
263
471
  }
264
472
  ctx.json = own.length !== rest.length;
265
473
  ctx.flags = parseFlags(own, spec.flags);
266
- return await spec.run(ctx);
474
+ input = { noun: cmd.noun, verb, argv: rest, flags: ctx.flags, cwd: ctx.cwd };
475
+ const entered = input;
476
+ guarded(() => journal.call(entered));
477
+ outcome = null;
478
+ const code = await spec.run(ctx);
479
+ outcome = code;
480
+ return code;
267
481
  }
268
482
  catch (err) {
269
483
  if (!(err instanceof CommandError))
270
484
  throw err;
271
485
  io.stderr(`${tag} ${err.message}\n`);
486
+ outcome = err.code;
272
487
  return err.code;
273
488
  }
489
+ finally {
490
+ if (input !== undefined && outcome !== undefined && shouldRecordFriction(outcome, excluded)) {
491
+ const failed = { ...input, code: outcome };
492
+ guarded(() => journal.failure(failed));
493
+ }
494
+ }
274
495
  }
275
496
  // ---------------------------------------------------------------------------
276
497
  // Repo facts
@@ -305,6 +526,15 @@ export function git(cwd, args) {
305
526
  const res = runGit(cwd, args);
306
527
  return res.ok ? res.stdout : null;
307
528
  }
529
+ /**
530
+ * True when git's ignore rules match `rel` in `cwd`. A tracked file reads as not
531
+ * ignored, so an ignored `rel` is always an untracked file git would refuse to
532
+ * `add` when a pathspec names it (the guard `:(exclude)` and `--pathspec-from-file`
533
+ * trip). Check before naming a path in an add pathspec.
534
+ */
535
+ export function isIgnoredPath(cwd, rel) {
536
+ return runGit(cwd, ["check-ignore", "-q", "--", rel]).ok;
537
+ }
308
538
  /** `JSON.parse` as a result instead of a throw; each caller says what bad input means for it. */
309
539
  // Shared with the files that are not commands (checks, install): re-exported here
310
540
  // for the command modules that already import it from this module.
@@ -355,15 +585,24 @@ export function runGh(cwd, args, input, env) {
355
585
  * (its own credentials) can.
356
586
  */
357
587
  export const ghUnavailable = (res) => res.missing || res.status === 4 || (!res.ok && /\bHTTP 403\b/.test(res.stderr));
588
+ /**
589
+ * The main checkout's root from any worktree, or `null` when not inside a git repo.
590
+ * `--git-common-dir` points at the shared `.git`, so a linked worktree resolves to the
591
+ * same root as the main one.
592
+ */
593
+ export function mainCheckoutRoot(cwd) {
594
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
595
+ return common ? path.dirname(common) : null;
596
+ }
358
597
  /**
359
598
  * The main checkout's root, from any worktree. `--git-common-dir` points at the
360
599
  * shared `.git`, so a linked worktree resolves to the same root as the main one.
361
600
  */
362
601
  export function repoRoot(cwd) {
363
- const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
364
- if (!common)
602
+ const root = mainCheckoutRoot(cwd);
603
+ if (!root)
365
604
  throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
366
- return path.dirname(common);
605
+ return root;
367
606
  }
368
607
  /** `<git common dir>/bkit-outbox`: per-run scratch files, never committed; null outside a git repo. */
369
608
  export function outboxRoot(cwd) {
@@ -8,6 +8,7 @@ import { ciCommand } from "./ci/ci.js";
8
8
  import { setupCommand } from "./setup/setup.js";
9
9
  import { branchesCommand } from "./workflow/branches.js";
10
10
  import { challengeCommand } from "./workflow/challenge.js";
11
+ import { completenessCommand } from "./workflow/completeness.js";
11
12
  import { contextCommand } from "./workflow/context.js";
12
13
  import { countersCommand } from "./workflow/counters.js";
13
14
  import { decisionsCommand } from "./workflow/decisions.js";
@@ -16,6 +17,7 @@ import { fidsCommand } from "./workflow/fids.js";
16
17
  import { issuesCommand } from "./workflow/issues.js";
17
18
  import { ledgersCommand } from "./workflow/ledgers.js";
18
19
  import { locksCommand } from "./workflow/locks.js";
20
+ import { plansCommand } from "./workflow/plans.js";
19
21
  import { prsCommand } from "./workflow/prs.js";
20
22
  import { repoCommand } from "./workflow/repo.js";
21
23
  import { roadmapCommand } from "./workflow/roadmap.js";
@@ -24,14 +26,15 @@ import { runtimeCommand } from "./workflow/runtime.js";
24
26
  import { skillsCommand } from "./workflow/skills.js";
25
27
  import { statusCommand } from "./workflow/status.js";
26
28
  import { stepsCommand } from "./workflow/steps.js";
29
+ import { tasksCommand } from "./workflow/tasks.js";
27
30
  import { testsCommand } from "./workflow/tests.js";
28
31
  import { workflowsCommand } from "./workflow/workflows.js";
29
- import { workstreamsCommand } from "./workflow/workstreams.js";
30
32
  import { worktreesCommand } from "./workflow/worktrees.js";
31
33
  export const COMMANDS = [
32
34
  statusCommand,
33
35
  countersCommand,
34
36
  stepsCommand,
37
+ tasksCommand,
35
38
  runtimeCommand,
36
39
  repoCommand,
37
40
  fidsCommand,
@@ -50,7 +53,8 @@ export const COMMANDS = [
50
53
  ledgersCommand,
51
54
  contextCommand,
52
55
  roadmapCommand,
53
- workstreamsCommand,
56
+ plansCommand,
57
+ completenessCommand,
54
58
  ciCommand,
55
59
  setupCommand,
56
60
  ];
@@ -123,6 +123,7 @@ export const setupCommand = {
123
123
  verbs: {
124
124
  "protect-main": {
125
125
  summary: "Apply bkit's branch protection to main, requiring the capstone check.",
126
+ use: "by-hand",
126
127
  flags: [
127
128
  {
128
129
  name: "dry-run",
@@ -14,7 +14,7 @@
14
14
  import * as fs from "node:fs";
15
15
  import * as path from "node:path";
16
16
  import { markdownTable } from "../shared/text.js";
17
- import { runAnalysis } from "./analysis.js";
17
+ import { ROW_SOURCES, runAnalysis, } from "./analysis.js";
18
18
  import { CHALLENGE_SMALL } from "./workflow/challenge.js";
19
19
  /** The ledgers `bkit stats` reads, relative to the repo root. */
20
20
  export const STATS_SOURCES = [
@@ -24,6 +24,15 @@ export const STATS_SOURCES = [
24
24
  ];
25
25
  /** Where `bkit stats` writes its report, relative to the repo root. */
26
26
  export const STATS_REPORT = ".bkit/stats.md";
27
+ /** The rules box the report opens with, under its title. */
28
+ const STATS_HEADER = [
29
+ "> [!CAUTION]",
30
+ `> **Purpose:** This repo's workflow statistics, computed from ${STATS_SOURCES.map((s) => `\`${s}\``).join(", ")}. Workflow closes append the rows; rows a direct chat wrote (\`utility\`) are reported apart.`,
31
+ ">",
32
+ "> **Rules:**",
33
+ ">",
34
+ "> - Generated — do not edit. `bkit stats` rewrites this file.",
35
+ ].join("\n");
27
36
  /** Kinds the harvest owns: never counted in a repo's own report. */
28
37
  const HARVEST_KINDS = new Set(["chat", "run"]);
29
38
  const pct = (rate) => `${(rate * 100).toFixed(1)}%`;
@@ -36,24 +45,22 @@ function table(head, rows) {
36
45
  function ranked(counts) {
37
46
  return Object.entries(counts).sort(([a, x], [b, y]) => y - x || a.localeCompare(b));
38
47
  }
39
- /**
40
- * The report as markdown sections under `## ` headings. `title` is the `# ` heading;
41
- * `scope` the sentence under it saying which rows were read.
42
- */
43
- export function renderStatsMarkdown(report, title, scope) {
44
- const { counts, elapsed, regression, complianceRates, versionCompliance, deferralDiscipline } = report;
45
- const out = [`# ${title}`, "", scope, ""];
46
- out.push("## Rows", "");
47
- if (counts.total === 0) {
48
- out.push("No rows yet. Workflows append them at close.", "");
49
- return out.join("\n");
50
- }
51
- out.push(...table(["Kind", "Rows"], ranked(counts.byKind)));
52
- out.push(...table(["Workflow", "Rows"], ranked(counts.byWorkflow)));
53
- if (Object.keys(counts.byRepo).length > 1) {
54
- out.push(...table(["Repo", "Rows"], ranked(counts.byRepo)));
55
- }
56
- out.push("## Run durations", "");
48
+ /** Each source's section heading and the sentence under it. */
49
+ const SOURCE_SECTIONS = {
50
+ workflow: {
51
+ heading: "Workflow runs",
52
+ intro: "Rows a workflow close wrote at the end of a design, plan, build, debug or ship run.",
53
+ },
54
+ utility: {
55
+ heading: "Direct chats (`utility`)",
56
+ intro: "Rows a direct chat wrote outside any workflow run (`by.workflow` `utility`). They are never added to the workflow figures.",
57
+ },
58
+ };
59
+ /** One source's figures under `### ` headings. */
60
+ function runFigureSections(f, source) {
61
+ const { elapsed, regression, challengeGate, complianceRates, versionCompliance } = f;
62
+ const out = [];
63
+ out.push("### Run durations", "");
57
64
  if (elapsed.count === 0) {
58
65
  out.push("No outcome row records a duration.", "");
59
66
  }
@@ -68,35 +75,67 @@ export function renderStatsMarkdown(report, title, scope) {
68
75
  ],
69
76
  ]));
70
77
  }
71
- out.push("## Change size vs failures", "");
78
+ out.push("### Change size vs failures", "");
72
79
  out.push(`A run counts as an error when it added failures. Dispatch-size threshold: ${regression.dispatchSizeThreshold} lines added.`, "");
73
80
  out.push(...table(["Lines added", "Runs", "Errors", "Error rate"], regression.buckets
74
81
  .filter((b) => b.count > 0)
75
82
  .map((b) => [b.label, b.count, b.errorCount, pct(b.errorRate)])));
76
83
  out.push(`Attempt counters: ${regression.shellBusCount} counted by the shell (trusted), ${regression.modelSelfReportCount} reported by the model (untrusted).`, "");
77
- if (report.challengeGate.runs > 0) {
78
- const g = report.challengeGate;
79
- out.push("## Build challenge size", "");
84
+ if (challengeGate.runs > 0) {
85
+ out.push("### Build challenge size", "");
80
86
  out.push(`Small changes (under ${CHALLENGE_SMALL.lines} lines and ${CHALLENGE_SMALL.files} files) run the security reviewer alone.`, "");
81
- out.push(...table(["Runs", "Small (challenge-1 skipped)", "Large"], [[g.runs, g.small, g.large]]));
87
+ out.push(...table(["Runs", "Small (challenge-1 skipped)", "Large"], [[challengeGate.runs, challengeGate.small, challengeGate.large]]));
82
88
  }
83
- const context = report.agentContext;
84
- out.push("## Agent context peaks", "");
89
+ const context = f.agentContext;
90
+ out.push("### Agent context peaks", "");
85
91
  if (context.recorded === 0) {
86
- out.push("No context data. A close records it from the Claude Code session that ran the workflow.", "");
92
+ out.push(source === "workflow"
93
+ ? "No context data. A close records it from the Claude Code session that ran the workflow."
94
+ : "No outcome row records context.", "");
87
95
  }
88
96
  else {
89
97
  out.push(`Cap: ${context.cap} tokens per agent. ${context.recorded} of ${context.outcomes} runs recorded context.`, "");
90
98
  out.push(...table(["Agent type", "Subagents", "Runs", "Peak (tokens)", "Runs over cap"], context.byAgent.map((a) => [a.agent, a.subagents, a.runs, a.peak, a.overCap])));
91
99
  }
92
100
  if (complianceRates.length > 0) {
93
- out.push("## Compliance by rule", "");
101
+ out.push("### Compliance by rule", "");
94
102
  out.push(...table(["Rule", "Pass", "Fail", "n/a", "Pass rate"], complianceRates.map((r) => [r.rule, r.passCount, r.failCount, r.naCount, pct(r.passRate)])));
95
103
  }
96
104
  if (versionCompliance.length > 0) {
97
- out.push("## Compliance by bkit version", "");
105
+ out.push("### Compliance by bkit version", "");
98
106
  out.push(...table(["Version", "Runs", "Pass rate"], versionCompliance.map((v) => [v.version, v.totalRuns, pct(v.passRate)])));
99
107
  }
108
+ return out;
109
+ }
110
+ /**
111
+ * The report as markdown sections under `## ` headings. `title` is the `# ` heading;
112
+ * `header` the block under it: which rows were read, and the rules for reading the file.
113
+ */
114
+ export function renderStatsMarkdown(report, title, header) {
115
+ const { counts, runs, deferralDiscipline } = report;
116
+ const out = [`# ${title}`, "", header, ""];
117
+ out.push("## Rows", "");
118
+ if (counts.total === 0) {
119
+ out.push("No rows yet. Workflows append them at close.", "");
120
+ return out.join("\n");
121
+ }
122
+ out.push(...table(["Kind", "Workflow rows", "Direct-chat rows"], Object.entries(counts.byKind)
123
+ .sort(([a, x], [b, y]) => y.workflow - x.workflow || y.utility - x.utility || a.localeCompare(b))
124
+ .map(([kind, n]) => [kind, n.workflow, n.utility])));
125
+ out.push(...table(["Workflow", "Rows"], ranked(counts.byWorkflow)));
126
+ if (Object.keys(counts.byRepo).length > 1) {
127
+ out.push(...table(["Repo", "Rows"], ranked(counts.byRepo)));
128
+ }
129
+ for (const source of ROW_SOURCES) {
130
+ const f = runs[source];
131
+ const { heading, intro } = SOURCE_SECTIONS[source];
132
+ out.push(`## ${heading}`, "", intro, "");
133
+ if (source === "utility" && f.outcomes === 0 && f.compliance === 0) {
134
+ out.push("No outcome or compliance rows from direct chats.", "");
135
+ continue;
136
+ }
137
+ out.push(...runFigureSections(f, source));
138
+ }
100
139
  if (deferralDiscipline.length > 0) {
101
140
  out.push("## Deferral discipline", "");
102
141
  out.push("Deferrals adjudicated unjustified, by the writer that deferred.", "");
@@ -117,7 +156,7 @@ export function renderStatsMarkdown(report, title, scope) {
117
156
  /** Build this repo's report from the ledgers under `root`. */
118
157
  export function buildRepoStats(root) {
119
158
  const files = STATS_SOURCES.map((rel) => path.join(root, rel)).filter((p) => fs.existsSync(p));
120
- return renderStatsMarkdown(runAnalysis(files, HARVEST_KINDS), "bkit stats", `This repo only: ${STATS_SOURCES.map((s) => `\`${s}\``).join(", ")}. Written by \`bkit stats\`; workflow closes append the rows.`);
159
+ return renderStatsMarkdown(runAnalysis(files, HARVEST_KINDS), "bkit stats", STATS_HEADER);
121
160
  }
122
161
  // stats — this repo's stats report. Advisory + inform-only: exits 0.
123
162
  // See DE-34 for the shared-entrypoint + crash-isolation contract.