@cbartens/bkit 5.5.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -1,6 +1,7 @@
1
1
  // commands/lib.ts — what every `bkit <noun> <verb>` command shares.
2
2
  //
3
- // Flag parsing, one JSON object on stdout, `[bkit-<noun>]`-tagged logs on stderr,
3
+ // Flag parsing, one output object on stdout (text, or JSON with `--json`),
4
+ // `[bkit-<noun>]`-tagged logs on stderr,
4
5
  // the exit-code table, `--help` rendering, and the repo facts several workflow
5
6
  // steps each re-derived by hand: repo root, UTC month, where `status.jsonl` lives,
6
7
  // the skip-CI tokens, and which branches are shared. A command declares its flags,
@@ -11,6 +12,7 @@ import * as fs from "node:fs";
11
12
  import * as os from "node:os";
12
13
  import * as path from "node:path";
13
14
  import { gitEnv } from "../ledgers/telemetry.js";
15
+ import { renderText } from "../shared/text.js";
14
16
  // ---------------------------------------------------------------------------
15
17
  // Exit codes
16
18
  // ---------------------------------------------------------------------------
@@ -178,8 +180,8 @@ export function verbHelp(cmd, verb) {
178
180
  "Flags:",
179
181
  flags.length ? table(flags) : " none",
180
182
  "",
181
- "Output (one JSON object on stdout):",
182
- table(Object.entries(spec.output)),
183
+ "Output (one object on stdout: `key: value` text, JSON with --json):",
184
+ table(Object.entries(spec.output).map(([key, help]) => [key, help + omitNote(spec, key)])),
183
185
  "",
184
186
  "Exit codes:",
185
187
  table(exitCodeRows(spec.exitCodes)),
@@ -195,6 +197,20 @@ const processIo = {
195
197
  stderr: (t) => process.stderr.write(t),
196
198
  };
197
199
  const isHelp = (arg) => arg === "--help" || arg === "-h";
200
+ /** Global boolean flag every verb takes; it is removed before the verb's own flags parse. */
201
+ const JSON_FLAG = "--json";
202
+ /** `output` less the keys `spec.textOmit` leaves out of text. */
203
+ function textOutput(spec, output) {
204
+ const omit = new Set((spec.textOmit ?? []).flatMap((o) => typeof o === "string" ? [o] : o.when(output[o.key], output) ? [o.key] : []));
205
+ return Object.fromEntries(Object.entries(output).filter(([k]) => !omit.has(k)));
206
+ }
207
+ /** `--help`'s note on an output key text leaves out: always, or only when it does not matter. */
208
+ function omitNote(spec, key) {
209
+ const o = (spec.textOmit ?? []).find((x) => (typeof x === "string" ? x : x.key) === key);
210
+ if (o === undefined)
211
+ return "";
212
+ return typeof o === "string" ? " (--json only)" : " (text: only when it matters)";
213
+ }
198
214
  /**
199
215
  * Run `argv` (without the leading `bkit`) if it names a registered command.
200
216
  * Returns the exit code, or null when `argv` is not a command, so the caller falls
@@ -231,16 +247,22 @@ export async function runCommand(argv, commands, options) {
231
247
  const ctx = {
232
248
  flags: {},
233
249
  cwd: options.cwd ?? process.cwd(),
250
+ json: false,
234
251
  log: (message) => io.stderr(`${tag} ${message}\n`),
235
252
  emit: (output) => {
236
253
  if (emitted)
237
- throw new Error(`${tag} ${verb} emitted twice — one JSON object per run`);
254
+ throw new Error(`${tag} ${verb} emitted twice — one output object per run`);
238
255
  emitted = true;
239
- io.stdout(`${JSON.stringify(output)}\n`);
256
+ io.stdout(ctx.json ? `${JSON.stringify(output)}\n` : renderText(textOutput(spec, output)));
240
257
  },
241
258
  };
242
259
  try {
243
- ctx.flags = parseFlags(rest, spec.flags);
260
+ const own = rest.filter((arg) => arg !== JSON_FLAG);
261
+ if (own.some((arg) => arg.startsWith(`${JSON_FLAG}=`))) {
262
+ throw new CommandError(EXIT.USAGE, `${JSON_FLAG} takes no value`);
263
+ }
264
+ ctx.json = own.length !== rest.length;
265
+ ctx.flags = parseFlags(own, spec.flags);
244
266
  return await spec.run(ctx);
245
267
  }
246
268
  catch (err) {
@@ -253,20 +275,20 @@ export async function runCommand(argv, commands, options) {
253
275
  // ---------------------------------------------------------------------------
254
276
  // Repo facts
255
277
  // ---------------------------------------------------------------------------
256
- /** Captured stdout / stderr cap for `runGit` / `runTool`; hook output (pre-push) counts. */
257
- const OUTPUT_LIMIT = 1 << 26;
278
+ /** Captured stdout / stderr cap for every git / gh spawn; hook output (pre-push) counts. */
279
+ export const OUTPUT_LIMIT = 1 << 26;
258
280
  /** Spawn error as a stderr lead line: ENOBUFS names the limit, anything else Node's message. */
259
281
  function spawnErrorText(cmd, args, err) {
260
282
  return err.code === "ENOBUFS"
261
283
  ? `${cmd} ${args[0] ?? ""}: output passed the ${OUTPUT_LIMIT / (1 << 20)} MiB limit (ENOBUFS)`
262
284
  : err.message;
263
285
  }
264
- /** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr. */
265
- export function runGit(cwd, args) {
286
+ /** `git <args>` in `cwd`, never throwing: exit status plus trimmed stdout / stderr; `env` adds vars. */
287
+ export function runGit(cwd, args, env = {}) {
266
288
  const res = spawnSync("git", args, {
267
289
  cwd,
268
290
  encoding: "utf-8",
269
- env: gitEnv(),
291
+ env: { ...gitEnv(), ...env },
270
292
  maxBuffer: OUTPUT_LIMIT,
271
293
  });
272
294
  const stderr = (res.stderr ?? "").trim();
@@ -288,7 +310,7 @@ export function git(cwd, args) {
288
310
  // for the command modules that already import it from this module.
289
311
  export { parseJson } from "../shared/json.js";
290
312
  // The shared-branch rule (`dev`, `main`) lives in shared/ so checks can read it too.
291
- export { DEV, isSharedBranch } from "../shared/branches.js";
313
+ export { DEV, MAIN, isSharedBranch } from "../shared/branches.js";
292
314
  /**
293
315
  * Run a tool other than git, never throwing. Hook-exported GIT_* vars are scrubbed
294
316
  * so gh and friends answer for `cwd`; `input` goes to stdin.
@@ -297,7 +319,7 @@ export function runTool(cmd, args, cwd, opts = {}) {
297
319
  const res = spawnSync(cmd, args, {
298
320
  cwd,
299
321
  encoding: "utf-8",
300
- env: gitEnv(),
322
+ env: { ...gitEnv(), ...opts.env },
301
323
  input: opts.input,
302
324
  maxBuffer: OUTPUT_LIMIT,
303
325
  });
@@ -316,9 +338,9 @@ export function runTool(cmd, args, cwd, opts = {}) {
316
338
  };
317
339
  }
318
340
  const signalNumber = (signal) => (signal ? os.constants.signals[signal] : undefined) ?? 1;
319
- /** `gh <args>` in `cwd`, never throwing; `input` goes to stdin. */
320
- export function runGh(cwd, args, input) {
321
- const res = runTool("gh", args, cwd, { input });
341
+ /** `gh <args>` in `cwd`, never throwing; `input` goes to stdin; `env` is added to the child's. */
342
+ export function runGh(cwd, args, input, env) {
343
+ const res = runTool("gh", args, cwd, { input, env });
322
344
  return {
323
345
  ok: res.found && res.status === 0,
324
346
  stdout: res.stdout.trim(),
@@ -343,6 +365,19 @@ export function repoRoot(cwd) {
343
365
  throw new CommandError(EXIT.USAGE, `not inside a git repository: ${cwd}`);
344
366
  return path.dirname(common);
345
367
  }
368
+ /** `<git common dir>/bkit-outbox`: per-run scratch files, never committed; null outside a git repo. */
369
+ export function outboxRoot(cwd) {
370
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
371
+ return common ? path.join(common, "bkit-outbox") : null;
372
+ }
373
+ /** An outbox path as a committed record names it: relative to the main checkout, never a home path. */
374
+ export function outboxRel(cwd, file) {
375
+ const root = outboxRoot(cwd);
376
+ if (root === null)
377
+ return file;
378
+ const rel = path.relative(path.dirname(path.dirname(root)), file);
379
+ return rel.startsWith("..") || path.isAbsolute(rel) ? file : rel.split(path.sep).join("/");
380
+ }
346
381
  /** `YYYYMM` in UTC, so every workflow picks the same month bucket at a month boundary. */
347
382
  export function utcMonth(now = new Date()) {
348
383
  return `${now.getUTCFullYear()}${String(now.getUTCMonth() + 1).padStart(2, "0")}`;
@@ -7,8 +7,10 @@
7
7
  import { ciCommand } from "./ci/ci.js";
8
8
  import { setupCommand } from "./setup/setup.js";
9
9
  import { branchesCommand } from "./workflow/branches.js";
10
+ import { challengeCommand } from "./workflow/challenge.js";
10
11
  import { contextCommand } from "./workflow/context.js";
11
12
  import { countersCommand } from "./workflow/counters.js";
13
+ import { decisionsCommand } from "./workflow/decisions.js";
12
14
  import { diskCommand } from "./workflow/disk.js";
13
15
  import { fidsCommand } from "./workflow/fids.js";
14
16
  import { issuesCommand } from "./workflow/issues.js";
@@ -34,6 +36,8 @@ export const COMMANDS = [
34
36
  repoCommand,
35
37
  fidsCommand,
36
38
  testsCommand,
39
+ challengeCommand,
40
+ decisionsCommand,
37
41
  locksCommand,
38
42
  workflowsCommand,
39
43
  worktreesCommand,
@@ -5,7 +5,7 @@
5
5
  // The policy also binds admins. `dev` is left unprotected — operators choose
6
6
  // direct-push or feat/PR.
7
7
  //
8
- // The required check is `bkit.capstoneJob`, the always-on job that asserts every
8
+ // The required check is `bkit.testing.ciCapstone`, the always-on job that asserts every
9
9
  // expected tier ran and passed, so "required check green" means validated, not
10
10
  // merely "the tests job did not fail". Before requiring it the command checks a
11
11
  // job by that name exists in the CI workflow: a required check no job produces
@@ -16,9 +16,9 @@ import { readBkitConfig } from "../../shared/settings.js";
16
16
  import { CommandError, EXIT, parseJson, repoRoot, runGh, } from "../lib.js";
17
17
  /** Exit code: `gh repo view` did not name the repository. */
18
18
  export const EXIT_NO_REPO = 3;
19
- /** Exit code: the CI workflow file named by `bkit.ciWorkflow` does not exist. */
19
+ /** Exit code: the CI workflow file named by `bkit.testing.ciWorkflow` does not exist. */
20
20
  export const EXIT_NO_CI_WORKFLOW = 4;
21
- /** Exit code: the CI workflow has no job named `bkit.capstoneJob`. */
21
+ /** Exit code: the CI workflow has no job named `bkit.testing.ciCapstone`. */
22
22
  export const EXIT_NO_CAPSTONE_JOB = 5;
23
23
  /** Exit code: a `gh api` call failed. */
24
24
  export const EXIT_GH_API_FAILED = 6;
@@ -138,8 +138,8 @@ export const setupCommand = {
138
138
  output: {
139
139
  repo: "owner/name the policy targets",
140
140
  branch: "always main",
141
- requiredCheck: "the required status check (bkit.capstoneJob)",
142
- ciWorkflow: "the CI workflow checked for that job (bkit.ciWorkflow)",
141
+ requiredCheck: "the required status check (bkit.testing.ciCapstone)",
142
+ ciWorkflow: "the CI workflow checked for that job (bkit.testing.ciWorkflow)",
143
143
  dryRun: "true with --dry-run",
144
144
  applied: "true when the policy was written to GitHub",
145
145
  payload: "the protection body sent (or that would be sent)",
@@ -148,8 +148,8 @@ export const setupCommand = {
148
148
  },
149
149
  exitCodes: {
150
150
  [EXIT_NO_REPO]: "gh repo view could not name the repository",
151
- [EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.ciWorkflow) does not exist",
152
- [EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.capstoneJob",
151
+ [EXIT_NO_CI_WORKFLOW]: "the CI workflow file (bkit.testing.ciWorkflow) does not exist",
152
+ [EXIT_NO_CAPSTONE_JOB]: "the CI workflow has no job named bkit.testing.ciCapstone",
153
153
  [EXIT_GH_API_FAILED]: "a gh api call failed",
154
154
  },
155
155
  run: protectMain,
@@ -0,0 +1,136 @@
1
+ // commands/stats.ts — `bkit stats`: this repo's stats report.
2
+ //
3
+ // Reads THIS repo's `.bkit/stats.jsonl`, `.bkit/friction.jsonl` and `docs/deferrals.jsonl`,
4
+ // runs the computations in commands/analysis.ts over them, writes `.bkit/stats.md` and
5
+ // prints it. Never reads another repo, chat history or `harvest/`: the cross-repo report is
6
+ // `harvest/stats.md`, written by the harvest script in bkit's own checkout.
7
+ //
8
+ // `.bkit/stats.md` is committed. It holds no timestamp, so it changes only when the ledgers do.
9
+ // `chat` / `run` rows left in `.bkit/stats.jsonl` (written there before they moved to
10
+ // `harvest/`) are not counted.
11
+ //
12
+ // Advisory + inform-only: never gates a workflow, always exits 0.
13
+ // See DE-34 for the shared-entrypoint + crash-isolation contract.
14
+ import * as fs from "node:fs";
15
+ import * as path from "node:path";
16
+ import { markdownTable } from "../shared/text.js";
17
+ import { runAnalysis } from "./analysis.js";
18
+ import { CHALLENGE_SMALL } from "./workflow/challenge.js";
19
+ /** The ledgers `bkit stats` reads, relative to the repo root. */
20
+ export const STATS_SOURCES = [
21
+ ".bkit/stats.jsonl",
22
+ ".bkit/friction.jsonl",
23
+ "docs/deferrals.jsonl",
24
+ ];
25
+ /** Where `bkit stats` writes its report, relative to the repo root. */
26
+ export const STATS_REPORT = ".bkit/stats.md";
27
+ /** Kinds the harvest owns: never counted in a repo's own report. */
28
+ const HARVEST_KINDS = new Set(["chat", "run"]);
29
+ const pct = (rate) => `${(rate * 100).toFixed(1)}%`;
30
+ /** A markdown table under a prettier-ignore marker, or nothing when there are no rows. */
31
+ function table(head, rows) {
32
+ const lines = markdownTable(head, rows);
33
+ return lines.length === 0 ? [] : ["<!-- prettier-ignore -->", ...lines, ""];
34
+ }
35
+ /** Sorted `[key, count]` pairs of a count map, largest first, then by name. */
36
+ function ranked(counts) {
37
+ return Object.entries(counts).sort(([a, x], [b, y]) => y - x || a.localeCompare(b));
38
+ }
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", "");
57
+ if (elapsed.count === 0) {
58
+ out.push("No outcome row records a duration.", "");
59
+ }
60
+ else {
61
+ out.push(...table(["Runs", "Mean (min)", "Median (min)", "Min (min)", "Max (min)"], [
62
+ [
63
+ elapsed.count,
64
+ elapsed.meanMinutes.toFixed(1),
65
+ elapsed.p50Minutes.toFixed(1),
66
+ elapsed.minMinutes,
67
+ elapsed.maxMinutes,
68
+ ],
69
+ ]));
70
+ }
71
+ out.push("## Change size vs failures", "");
72
+ out.push(`A run counts as an error when it added failures. Dispatch-size threshold: ${regression.dispatchSizeThreshold} lines added.`, "");
73
+ out.push(...table(["Lines added", "Runs", "Errors", "Error rate"], regression.buckets
74
+ .filter((b) => b.count > 0)
75
+ .map((b) => [b.label, b.count, b.errorCount, pct(b.errorRate)])));
76
+ 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", "");
80
+ 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]]));
82
+ }
83
+ const context = report.agentContext;
84
+ out.push("## Agent context peaks", "");
85
+ if (context.recorded === 0) {
86
+ out.push("No context data. A close records it from the Claude Code session that ran the workflow.", "");
87
+ }
88
+ else {
89
+ out.push(`Cap: ${context.cap} tokens per agent. ${context.recorded} of ${context.outcomes} runs recorded context.`, "");
90
+ 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
+ }
92
+ if (complianceRates.length > 0) {
93
+ out.push("## Compliance by rule", "");
94
+ 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
+ }
96
+ if (versionCompliance.length > 0) {
97
+ out.push("## Compliance by bkit version", "");
98
+ out.push(...table(["Version", "Runs", "Pass rate"], versionCompliance.map((v) => [v.version, v.totalRuns, pct(v.passRate)])));
99
+ }
100
+ if (deferralDiscipline.length > 0) {
101
+ out.push("## Deferral discipline", "");
102
+ out.push("Deferrals adjudicated unjustified, by the writer that deferred.", "");
103
+ out.push(...table(["Writer", "Model", "Deferrals", "Unjustified", "Rate", "Reasons"], deferralDiscipline.map((d) => [
104
+ d.writer,
105
+ d.model,
106
+ d.total,
107
+ d.unjustifiedCount,
108
+ pct(d.unjustifiedRate),
109
+ Object.entries(d.byReason)
110
+ .sort(([a], [b]) => a.localeCompare(b))
111
+ .map(([reason, n]) => `${reason}=${n}`)
112
+ .join(" "),
113
+ ])));
114
+ }
115
+ return out.join("\n").replace(/\n+$/, "\n");
116
+ }
117
+ /** Build this repo's report from the ledgers under `root`. */
118
+ export function buildRepoStats(root) {
119
+ 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.`);
121
+ }
122
+ // stats — this repo's stats report. Advisory + inform-only: exits 0.
123
+ // See DE-34 for the shared-entrypoint + crash-isolation contract.
124
+ export function runStatsCommand() {
125
+ try {
126
+ const root = process.cwd();
127
+ const markdown = buildRepoStats(root);
128
+ fs.writeFileSync(path.join(root, STATS_REPORT), markdown, "utf-8");
129
+ console.log(markdown);
130
+ console.error(`[bkit-stats] wrote ${STATS_REPORT}`);
131
+ }
132
+ catch (err) {
133
+ const msg = err instanceof Error ? err.message : String(err);
134
+ console.error(`[bkit-stats] stats error (fail-open): ${msg}`);
135
+ }
136
+ }
@@ -2,16 +2,20 @@
2
2
  // apply to this repo. Each workflow passes its name at its close and gets the one tip that
3
3
  // matters most there (`audit` / `utility` for the audit agent and the ledger / roadmap
4
4
  // updaters); bare `bkit tips` prints the top three. The star line closes bare and phase
5
- // output unless `bkit-star` is in `bkit.ignoreAdvisories`. Local checks only, no network; prints
5
+ // output unless `bkit-star` is in `bkit.advisories.ignore`. Local checks only, no network; prints
6
6
  // nothing when no tip fires and no star line shows; exits 0. What the last disk clean-up left
7
7
  // for the person to decide (`bkit disk prune` notes) comes first, outside the tip cap.
8
8
  import { collectTips, formatTips } from "../checks/tips/index.js";
9
9
  import { formatNotes, readNotes } from "./workflow/disk.js";
10
- export function runTipsCommand(all, workflow, cwd = process.cwd()) {
10
+ /** What `bkit tips` prints: disk-prune notes, then the tips; "" when nothing applies. */
11
+ export function tipsText(all, workflow, cwd) {
11
12
  const { tips, star } = collectTips(cwd);
12
- const output = [formatNotes(readNotes(cwd)), formatTips(tips, { all, workflow, star })]
13
+ return [formatNotes(readNotes(cwd)), formatTips(tips, { all, workflow, star })]
13
14
  .filter((part) => part !== "")
14
15
  .join("\n\n");
16
+ }
17
+ export function runTipsCommand(all, workflow, cwd = process.cwd()) {
18
+ const output = tipsText(all, workflow, cwd);
15
19
  if (output)
16
20
  console.log(output);
17
21
  }