@cbartens/bkit 5.5.1 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +35 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +19 -18
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +91 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +12 -11
  15. package/.bkit/core/.bkit/trackers.md +51 -28
  16. package/.bkit/core/.bkit/workflows.md +394 -355
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -29
  55. package/.bkit/core/engine/checks/after/github.ts +95 -17
  56. package/.bkit/core/engine/checks/after/index.ts +10 -7
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +46 -91
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +6 -6
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +407 -64
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +58 -8
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +185 -8
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +250 -3
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +157 -20
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +29 -15
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +32 -14
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +72 -18
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +29 -14
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +27 -12
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +41 -18
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +11 -11
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +16 -7
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +1 -1
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +4 -4
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  199. package/CHANGELOG.md +112 -0
  200. package/README.md +50 -35
  201. package/dist/checks/after/ci-yml.js +39 -28
  202. package/dist/checks/after/github.js +91 -17
  203. package/dist/checks/after/index.js +11 -8
  204. package/dist/checks/after/suppression.js +8 -5
  205. package/dist/checks/after/tools.js +39 -82
  206. package/dist/checks/before/env.js +2 -2
  207. package/dist/checks/before/files.js +5 -3
  208. package/dist/checks/before/index.js +15 -2
  209. package/dist/checks/before/repo.js +163 -2
  210. package/dist/checks/tips/catalogue.js +14 -5
  211. package/dist/checks/tips/detect.js +32 -0
  212. package/dist/checks/tips/index.js +4 -4
  213. package/dist/cli.js +19 -47
  214. package/dist/commands/analysis.js +109 -100
  215. package/dist/commands/ci/ci.js +6 -6
  216. package/dist/commands/comply.js +54 -91
  217. package/dist/commands/install/doctor.js +2 -2
  218. package/dist/commands/install/install.js +50 -19
  219. package/dist/commands/install/uninstall.js +59 -28
  220. package/dist/commands/land.js +16 -12
  221. package/dist/commands/lib.js +51 -16
  222. package/dist/commands/registry.js +4 -0
  223. package/dist/commands/setup/setup.js +7 -7
  224. package/dist/commands/stats.js +136 -0
  225. package/dist/commands/tips.js +7 -3
  226. package/dist/commands/workflow/branches.js +656 -56
  227. package/dist/commands/workflow/challenge.js +556 -0
  228. package/dist/commands/workflow/context.js +709 -30
  229. package/dist/commands/workflow/counters.js +208 -75
  230. package/dist/commands/workflow/decisions.js +441 -0
  231. package/dist/commands/workflow/disk.js +2 -2
  232. package/dist/commands/workflow/fids.js +689 -33
  233. package/dist/commands/workflow/issues.js +343 -59
  234. package/dist/commands/workflow/ledgers.js +762 -27
  235. package/dist/commands/workflow/locks.js +24 -2
  236. package/dist/commands/workflow/plan-blocks.js +437 -0
  237. package/dist/commands/workflow/plan-versions.js +22 -0
  238. package/dist/commands/workflow/prs.js +142 -32
  239. package/dist/commands/workflow/repo.js +52 -8
  240. package/dist/commands/workflow/roadmap.js +9 -7
  241. package/dist/commands/workflow/run-facts.js +426 -0
  242. package/dist/commands/workflow/runs.js +144 -43
  243. package/dist/commands/workflow/runtime.js +12 -1
  244. package/dist/commands/workflow/status.js +130 -29
  245. package/dist/commands/workflow/step-table.js +276 -0
  246. package/dist/commands/workflow/steps.js +171 -80
  247. package/dist/commands/workflow/summary.js +275 -0
  248. package/dist/commands/workflow/tests.js +834 -136
  249. package/dist/commands/workflow/tracker.js +983 -0
  250. package/dist/commands/workflow/workflows.js +834 -195
  251. package/dist/commands/workflow/workstreams.js +11 -5
  252. package/dist/commands/workflow/worktrees.js +147 -9
  253. package/dist/install/manifest.js +11 -9
  254. package/dist/install/modules/cloud.js +22 -13
  255. package/dist/install/modules/core.js +247 -3
  256. package/dist/install/modules/opencode.js +2 -2
  257. package/dist/install/version-file.js +6 -2
  258. package/dist/ledgers/migrate.js +81 -0
  259. package/dist/ledgers/status.js +61 -8
  260. package/dist/ledgers/telemetry.js +905 -124
  261. package/dist/render/hosts.js +4 -0
  262. package/dist/render/models.js +12 -0
  263. package/dist/shared/branches.js +3 -1
  264. package/dist/shared/egress.js +7 -0
  265. package/dist/shared/json.js +20 -7
  266. package/dist/shared/settings.js +125 -17
  267. package/dist/shared/text.js +333 -0
  268. package/dist/tools/grammar-density.js +183 -0
  269. package/dist/tools/instructions-sources.js +721 -0
  270. package/dist/tools/instructions.js +1579 -0
  271. package/package.json +113 -24
  272. package/.bkit/core/engine/commands/harvest.ts +0 -459
  273. package/.bkit/core/engine/tools/wording.ts +0 -748
  274. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  275. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  276. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  277. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  278. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  279. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  280. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  281. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  282. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  283. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  284. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  285. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  286. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  287. package/dist/commands/harvest.js +0 -353
  288. package/dist/tools/wording.js +0 -680
@@ -19,7 +19,7 @@
19
19
  // Detection rules: every `fires` is local (files, settings, environment) — no network.
20
20
  // Where an advisory already detects the gap, `fires` calls that detector and `advisories`
21
21
  // names its ids, so the tip and the advisory can never disagree and one
22
- // `bkit.ignoreAdvisories` entry silences both.
22
+ // `bkit.advisories.ignore` entry silences both.
23
23
 
24
24
  import * as fs from "node:fs";
25
25
  import * as path from "node:path";
@@ -48,11 +48,12 @@ import {
48
48
  hasLintStagedConfig,
49
49
  hasMcpServer,
50
50
  hasTestLinter,
51
+ readsBkitText,
51
52
  unlockedMcpServers,
52
53
  } from "./detect.js";
53
54
 
54
55
  export interface SetupTip {
55
- /** `bkit.ignoreAdvisories` key; never an advisory id (those go in `advisories`). */
56
+ /** `bkit.advisories.ignore` key; never an advisory id (those go in `advisories`). */
56
57
  id: string;
57
58
  /** Contexts the tip matters in; absent = shown only after every context's own tips. */
58
59
  workflows?: readonly TipsContext[];
@@ -90,9 +91,9 @@ export const SETUP_TIPS: readonly SetupTip[] = [
90
91
  title: "Connect an issue tracker",
91
92
  line: "bkit isn't connected to an issue tracker, so it can't read the task it's working on or record what it did. Connect GitHub, Linear or Jira, or switch this tip off if you don't want one.",
92
93
  why: "Every workflow starts by reading the issue it's working on and reports progress back to it as it goes. Without a tracker, you have to paste in what the agent should look at each time, and nothing records what changed or why.",
93
- ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.issueTracker` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
94
+ ask: 'Connect bkit to GitHub Issues: re-run `bkit install` with the tool flags I use plus `--tracker=github` (it records `bkit.tracker.default` in package.json and adds the tracker server to .mcp.json). If I don\'t want a tracker, set `"issueTracker": "none"` under `bkit` in package.json instead.',
94
95
  steps:
95
- '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "issueTracker": "none" }` in `package.json`.',
96
+ '`.bkit/install.md` § Optional post-install decisions. Opt out: `"bkit": { "tracker": { "default": "none" } }` in `package.json`.',
96
97
  advisories: ["tracker-setup-none"],
97
98
  fires: (cwd) => buildTrackerSetupAdvisory(cwd)?.id === "tracker-setup-none",
98
99
  },
@@ -164,7 +165,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
164
165
  title: "Automatic checks on every change",
165
166
  line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
166
167
  why: 'This runs your tests and checks on GitHub every time something changes, and bkit\'s ship step waits for it to pass before merging. Without it, "shipped" only means "merged", not "checked".',
167
- ask: "Copy .bkit/templates/.github/workflows/bkit-ci.yml to .github/workflows/bkit-ci.yml, replace `main` and `{{NODE_VERSION}}` in it with my default branch and Node major version, and add the `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
168
+ ask: "Copy .bkit/templates/.github/workflows/bkit-ci.yml to .github/workflows/<the file package.json `bkit.testing.ciWorkflow` names; default bkit-ci.yml>, replace `main` and `{{NODE_VERSION}}` in it with my default branch and Node major version, and add the `typecheck`, `lint`, `format:check`, `lint:prose`, `slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
168
169
  steps: "`.bkit/templates.md` § CI workflow and § Gate tool scripts.",
169
170
  fires: (cwd) => !exists(cwd, `.github/workflows/${readBkitConfig(cwd).ciWorkflow}`),
170
171
  },
@@ -406,6 +407,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
406
407
  },
407
408
 
408
409
  // --- setup: only some setups -----------------------------------------------------------
410
+ {
411
+ id: "bkit-output-json",
412
+ title: "Scripts that read bkit's replies",
413
+ line: "A hook, script or CI step reads bkit's replies as JSON, but bkit replies in plain text unless the call passes `--json`. Add `--json` to those bkit calls.",
414
+ why: "bkit answers in short text lines by default because agents read them. A script expecting JSON gets nothing it can parse, so its step quietly does nothing.",
415
+ ask: "Add --json to every bkit call whose output a hook, script or CI workflow parses (piped to jq, or read with JSON.parse), then rerun `bkit tips` until this tip is gone.",
416
+ steps:
417
+ "`.bkit/workflows.md` § Workflow commands. Files: `.claude/hooks/`, `.husky/`, `.github/workflows/`, `scripts/`.",
418
+ fires: (cwd) => readsBkitText(cwd).length > 0,
419
+ },
409
420
  {
410
421
  id: "cursor-files",
411
422
  title: "Cursor editor settings",
@@ -185,3 +185,37 @@ export function hasTestLinter(cwd: string): boolean {
185
185
  }
186
186
  return eslintConfigs.some((text) => TEST_LINT_PLUGIN.test(text));
187
187
  }
188
+
189
+ /** Consumer-owned folders whose files may run bkit and read what it prints. */
190
+ const OUTPUT_READER_DIRS = [".claude/hooks", ".husky", ".github/workflows", "scripts"];
191
+
192
+ /**
193
+ * A line that reads bkit's stdout as JSON without asking for it: a bkit call piped to `jq`,
194
+ * or a bkit argument list (`"bkit", "<noun>", "<verb>", …]`) passed to a spawn.
195
+ */
196
+ const READS_BKIT_TEXT = [
197
+ /\bbkit\b(?:(?!--json)[^\n|])*\|\s*jq\b/i,
198
+ /"bkit",\s*"[a-z-]+",\s*"[a-z-]+"(?:(?!"--json")[^\n\]])*\]/,
199
+ ];
200
+
201
+ /** Files under `dir` (relative to `cwd`), `node_modules` left out, at most 4 levels down. */
202
+ function filesUnder(cwd: string, dir: string, depth = 4): string[] {
203
+ const abs = path.join(cwd, dir);
204
+ if (depth === 0 || !fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) return [];
205
+ return fs.readdirSync(abs, { withFileTypes: true }).flatMap((e) => {
206
+ const rel = path.posix.join(dir, e.name);
207
+ if (e.isDirectory()) return e.name === "node_modules" ? [] : filesUnder(cwd, rel, depth - 1);
208
+ return e.isFile() ? [rel] : [];
209
+ });
210
+ }
211
+
212
+ /**
213
+ * Hooks, CI workflows and scripts that parse bkit's output as JSON without `--json`;
214
+ * bkit prints text by default, so each one reads nothing.
215
+ */
216
+ export function readsBkitText(cwd: string): string[] {
217
+ return OUTPUT_READER_DIRS.flatMap((dir) => filesUnder(cwd, dir)).filter((rel) => {
218
+ const text = readText(cwd, rel);
219
+ return text.split("\n").some((line) => READS_BKIT_TEXT.some((re) => re.test(line)));
220
+ });
221
+ }
@@ -32,10 +32,10 @@ export function silenceLine(ids: readonly string[]): string {
32
32
  const names = ids.map((id) => `\`${id}\``);
33
33
  const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0];
34
34
  const what = ids.length > 1 ? "these tips" : "this tip";
35
- return `**Want to silence ${what}?** Ask your agent to "add ${list} to \`bkit.ignoreAdvisories\` in package.json".`;
35
+ return `**Want to silence ${what}?** Ask your agent to "add ${list} to \`bkit.advisories.ignore\` in package.json".`;
36
36
  }
37
37
 
38
- /** `bkit.ignoreAdvisories` key that silences `STAR_TIP`. */
38
+ /** `bkit.advisories.ignore` key that silences `STAR_TIP`. */
39
39
  export const STAR_TIP_ID = "bkit-star";
40
40
 
41
41
  /** Older key that also silences `STAR_TIP`, so repos that set it keep the line off. */
@@ -54,7 +54,7 @@ export const STAR_TIP_PARAGRAPH = STAR_TIP.replace("Do you like bkit?", "**Do yo
54
54
 
55
55
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
56
56
  export const TIPS_SECTION_INTRO =
57
- "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.ignoreAdvisories` in package.json. Full template catalogue: .bkit/templates.md.";
57
+ "Things not set up yet, most useful first. For the person: each tip says what goes wrong today and a sentence to ask your agent. For an AI agent: follow each tip's Agent steps unless the person declines it. Silence a tip by adding its id to `bkit.advisories.ignore` in package.json. Full template catalogue: .bkit/templates.md.";
58
58
 
59
59
  /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
60
60
  export function matchesAdvisory(pattern: string, id: string): boolean {
@@ -71,9 +71,9 @@ export function isTipSilenced(tip: SetupTip, ignored: ReadonlySet<string>): bool
71
71
  export interface TipsResult {
72
72
  /** Firing tips, in priority order. */
73
73
  tips: SetupTip[];
74
- /** Firing tips the root `bkit.ignoreAdvisories` silenced. */
74
+ /** Firing tips the root `bkit.advisories.ignore` silenced. */
75
75
  suppressed: SuppressionNote[];
76
- /** False when the root `bkit.ignoreAdvisories` names `STAR_TIP_ID` or `STAR_TIP_OLD_ID`. */
76
+ /** False when the root `bkit.advisories.ignore` names `STAR_TIP_ID` or `STAR_TIP_OLD_ID`. */
77
77
  star: boolean;
78
78
  }
79
79
 
@@ -93,7 +93,7 @@ export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_
93
93
 
94
94
  /**
95
95
  * Drop advisory findings whose tip the root package.json silenced, so one
96
- * `bkit.ignoreAdvisories` entry silences a tip and the advisories it reuses. Blockers are
96
+ * `bkit.advisories.ignore` entry silences a tip and the advisories it reuses. Blockers are
97
97
  * never dropped.
98
98
  */
99
99
  export function dropTipSilencedAdvisories(
@@ -11,8 +11,7 @@ import { runCommand } from "./commands/lib.js";
11
11
  import { launchApp } from "./commands/launch.js";
12
12
  import { runStatus, runDoctor } from "./commands/install/doctor.js";
13
13
  import { runComplyCommand } from "./commands/comply.js";
14
- import { runHarvestCommand } from "./commands/harvest.js";
15
- import { runAnalysisCommand } from "./commands/analysis.js";
14
+ import { runStatsCommand } from "./commands/stats.js";
16
15
  import { runTelemetryCommand } from "./commands/telemetry.js";
17
16
  import { runTipsCommand } from "./commands/tips.js";
18
17
  import { runUpgradeCommand } from "./commands/install/upgrade.js";
@@ -47,8 +46,7 @@ export const CLASSIC_VERBS: ReadonlySet<string> = new Set([
47
46
  "uninstall",
48
47
  "upgrade",
49
48
  "comply",
50
- "harvest",
51
- "analysis",
49
+ "stats",
52
50
  "telemetry",
53
51
  "tips",
54
52
  "cursor",
@@ -66,8 +64,7 @@ export type Verb =
66
64
  | "cursor"
67
65
  | "opencode"
68
66
  | "comply"
69
- | "harvest"
70
- | "analysis"
67
+ | "stats"
71
68
  | "telemetry"
72
69
  | "tips"
73
70
  | "help";
@@ -260,24 +257,12 @@ export function parseArgs(argv: string[]): ParsedArgs {
260
257
  } else if (firstArg === "comply") {
261
258
  verb = "comply";
262
259
  args.shift();
263
- } else if (firstArg === "harvest") {
264
- verb = "harvest";
260
+ } else if (firstArg === "stats") {
261
+ verb = "stats";
265
262
  args.shift();
266
- // harvest takes no flags — reject any remaining args
263
+ // stats takes no flags — reject any remaining positional args
267
264
  if (args.length > 0 && !args[0]?.startsWith("-")) {
268
- console.error(
269
- `[bkit] \`bkit harvest\` takes no positional args. Run \`bkit help\` for usage.`,
270
- );
271
- process.exit(1);
272
- }
273
- } else if (firstArg === "analysis") {
274
- verb = "analysis";
275
- args.shift();
276
- // analysis takes no flags — reject any remaining positional args
277
- if (args.length > 0 && !args[0]?.startsWith("-")) {
278
- console.error(
279
- `[bkit] \`bkit analysis\` takes no positional args. Run \`bkit help\` for usage.`,
280
- );
265
+ console.error(`[bkit] \`bkit stats\` takes no positional args. Run \`bkit help\` for usage.`);
281
266
  process.exit(1);
282
267
  }
283
268
  } else if (firstArg === "telemetry") {
@@ -629,7 +614,7 @@ Usage:
629
614
  workflow runs this at its close; audit and utility do the
630
615
  same for audits and the ledger / roadmap updaters);
631
616
  --all lists every one. Ends with a star line ("bkit-star"
632
- in bkit.ignoreAdvisories silences it), except under
617
+ in bkit.advisories.ignore silences it), except under
633
618
  --workflow=audit|utility. Local checks only. Exits 0.
634
619
  bkit status Read-only host/provider status. Reports current host+provider
635
620
  (sampled from .claude/, .cursor/, package.json, and the
@@ -650,18 +635,6 @@ Usage:
650
635
  never gates a workflow. Appends kind:"compliance"
651
636
  rows to .bkit/stats.jsonl. Fail-open: always exits 0.
652
637
  Valid phases: design, plan, build, debug, ship.
653
- bkit harvest Cross-repo harvest — COPIES consumer .bkit/stats.jsonl
654
- and MOVES .bkit/friction.jsonl into harvest/ (COUNT-ONLY
655
- for docs/deferrals.jsonl and docs/failures.jsonl).
656
- Reads consumer paths from harvest/consumers.md.
657
- DESTRUCTIVE: harvested friction rows are REMOVED from
658
- the consumer, but only after they are fsync'd and read
659
- back from harvest/. stats.jsonl is never modified.
660
- harvest/ accumulates and is never cleared; it is
661
- gitignored, so it is the only record of pruned rows —
662
- back it up. Never commits
663
- in any repo. Deduplicates by per-kind composite
664
- identity. Advisory + fail-open: exits 0.
665
638
  bkit telemetry summary [--phase=<workflow>]
666
639
  Per-workflow telemetry report: THIS run's metrics
667
640
  (duration, size, friction/deferrals/failures added,
@@ -671,13 +644,12 @@ Usage:
671
644
  --phase=<workflow>: the workflow to report
672
645
  (design|plan|build|debug|ship). Without it, prints the
673
646
  ledger-health line only. Read-only: exits 0.
674
- bkit analysis Cross-repo analysis — reports counts/rates/elapsed-time,
675
- change-size vs outcome regression, dispatch-size threshold,
676
- counterSource trust labelling, per-rule compliance
677
- rate over kind:"compliance" rows, and the
678
- unjustified-deferral rate per (subagent, model)
679
- over kind:"deferral" rows. Reads from harvest/,
680
- .bkit/stats.jsonl and docs/deferrals.jsonl.
647
+ bkit stats This repo's stats report: counts, durations, change-size vs
648
+ outcome, counterSource trust, per-rule and per-version
649
+ compliance, and the unjustified-deferral rate per
650
+ (subagent, model). Reads .bkit/stats.jsonl,
651
+ .bkit/friction.jsonl and docs/deferrals.jsonl of THIS repo
652
+ only; writes .bkit/stats.md and prints it.
681
653
  Advisory + inform-only: exits 0.
682
654
  bkit help Print this message.
683
655
 
@@ -705,7 +677,7 @@ Module flags (composable; symmetric install ↔ uninstall):
705
677
  Ships .opencode/** (agents, commands, opencode.json, bkit-gateguard.js,
706
678
  bkit-readguard.js).
707
679
  Configure your provider key; verify with \`bkit doctor\`. All installed
708
- providers tracked in bkit.opencodeProviders.
680
+ providers tracked in bkit.providers.opencode.installed.
709
681
  --codex Codex CLI host. BARE flag — takes no value: Codex runs on one gateway
710
682
  (openai), so only --opencode is provider-pluggable. Ships .codex/agents/*.toml
711
683
  + .codex/hooks.json + .codex/hooks/bkit-{gateguard,guardrails,readguard}.cjs,
@@ -736,7 +708,7 @@ Dependency updaters (copy an example and own it):
736
708
 
737
709
  Cross-cutting / modifiers:
738
710
  --tracker=<name> Wire issue tracker integration. Values: github, linear, jira, none
739
- (default). Records bkit.issueTracker in package.json and substitutes
711
+ (default). Records bkit.tracker.default in package.json and substitutes
740
712
  tracker snippets into command mirrors. Re-renders every installed
741
713
  host, and works alone (bkit install --tracker=github). Switching is
742
714
  free; a switch removes the old linear or jira MCP entry unless you
@@ -754,7 +726,7 @@ Uninstall flags:
754
726
  --dry-run Print decision table (FILE / DECISION / REASON) without writing.
755
727
  --opencode=<provider>
756
728
  Surgical provider removal: removes that provider's block from
757
- opencode.json + drops it from bkit.opencodeProviders. Does NOT remove
729
+ opencode.json + drops it from bkit.providers.opencode.installed. Does NOT remove
758
730
  agents/commands/gateguard. If the removed provider was active, the first
759
731
  remaining provider becomes active and the agents are re-rendered to its
760
732
  model pins.
@@ -802,7 +774,7 @@ function commandsUsage(): string {
802
774
  return [
803
775
  "",
804
776
  "",
805
- "Workflow commands (bkit <noun> <verb> --flags; JSON on stdout; bkit <noun> --help):",
777
+ "Workflow commands (bkit <noun> <verb> --flags; text on stdout, --json for JSON; bkit <noun> --help):",
806
778
  ...COMMANDS.map((c) => ` bkit ${c.noun.padEnd(width)} ${c.summary}`),
807
779
  ].join("\n");
808
780
  }
@@ -884,13 +856,8 @@ export async function main() {
884
856
  return;
885
857
  }
886
858
 
887
- if (verb === "harvest") {
888
- runHarvestCommand();
889
- return;
890
- }
891
-
892
- if (verb === "analysis") {
893
- runAnalysisCommand();
859
+ if (verb === "stats") {
860
+ runStatsCommand();
894
861
  return;
895
862
  }
896
863