@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
@@ -4,11 +4,12 @@
4
4
  // `audit` / `utility` for the agents); `bkit tips` prints the top three;
5
5
  // `.bkit/advisories.md` lists every firing tip under `Setup tips`.
6
6
  //
7
- // Array order is the priority: comms first (can workflows reach anything), then change
8
- // quality (design → build), delivery (debug → ship), running cost, nice-to-have, and
9
- // setup-specific plumbing last. `workflows` names where a tip matters: a workflow shows
10
- // its own tips first, in array order, then the rest. Comms tips name every context, so
11
- // they lead everywhere until fixed.
7
+ // Array order is the priority: an outdated bkit first (every workflow runs its old text and
8
+ // misses its fixes), then comms (can workflows reach anything), change quality (design →
9
+ // build), delivery (debug → ship), running cost, nice-to-have, and setup-specific plumbing
10
+ // last. `workflows` names where a tip matters: a workflow shows its own tips first, in
11
+ // array order, then the rest. The upgrade and comms tips name every context, so they lead
12
+ // everywhere until fixed; the upgrade tip alone cannot be silenced.
12
13
  //
13
14
  // Text rules: `line`, `why`, `caution` and `ask` are for the person, in plain English, and
14
15
  // never name an outside service — examples of specific services go in `steps`, which is
@@ -16,7 +17,9 @@
16
17
  // section opener and in the README's "Templates ready to adopt" row; change all three in
17
18
  // the same commit.
18
19
  //
19
- // Detection rules: every `fires` is local (files, settings, environment) — no network.
20
+ // Detection rules: every `fires` is local (files, settings, environment) — no network. The
21
+ // `cwd` it receives is the main checkout (checks/tips/index.ts `tipsBase`), never the
22
+ // calling worktree, so a tip reflects the repo the integration branch carries.
20
23
  // Where an advisory already detects the gap, `fires` calls that detector and `advisories`
21
24
  // names its ids, so the tip and the advisory can never disagree and one
22
25
  // `bkit.advisories.ignore` entry silences both.
@@ -47,7 +50,9 @@ import {
47
50
  hasJsTestRunner,
48
51
  hasLintStagedConfig,
49
52
  hasMcpServer,
53
+ hasNewerBkit,
50
54
  hasTestLinter,
55
+ hasUnsharedFriction,
51
56
  readsBkitText,
52
57
  unlockedMcpServers,
53
58
  } from "./detect.js";
@@ -69,6 +74,8 @@ export interface SetupTip {
69
74
  ask: string;
70
75
  /** Where the agent finds the exact steps. */
71
76
  steps: string;
77
+ /** False when no `bkit.advisories.ignore` entry may silence the tip. */
78
+ silenceable?: false;
72
79
  /** Advisory ids this tip reuses the check of; a trailing `*` matches an id prefix. */
73
80
  advisories?: readonly string[];
74
81
  /** True when the gap exists. Local checks only. */
@@ -84,6 +91,21 @@ export const ALL_WORKFLOWS: readonly ComplyPhase[] = ["design", "plan", "build",
84
91
  export const EVERY_CONTEXT: readonly TipsContext[] = [...ALL_WORKFLOWS, "audit", "utility"];
85
92
 
86
93
  export const SETUP_TIPS: readonly SetupTip[] = [
94
+ // --- current: is bkit itself up to date ---------------------------------------------
95
+ {
96
+ id: "bkit-upgrade",
97
+ workflows: EVERY_CONTEXT,
98
+ title: "Upgrade bkit",
99
+ line: "A newer bkit is out, but this repo still runs an older one, so your workflows miss its fixes. Upgrade it.",
100
+ why: "Each release fixes problems found in earlier ones and improves the steps your workflows follow. Upgrading is one command, and it also refreshes the files bkit keeps in this repo so they match the new version.",
101
+ caution:
102
+ "Upgrading rewrites the files bkit manages in this repo. Look over what changed and commit it as one change.",
103
+ ask: "Upgrade bkit in this repo to the latest version: follow the paste block in .bkit/install.md § Upgrade — already installed, then show me what changed before committing.",
104
+ steps: "`.bkit/install.md` § Upgrade — already installed.",
105
+ silenceable: false,
106
+ fires: hasNewerBkit,
107
+ },
108
+
87
109
  // --- connect: can bkit talk to anything at all -------------------------------------
88
110
  {
89
111
  id: "tracker",
@@ -165,7 +187,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
165
187
  title: "Automatic checks on every change",
166
188
  line: "Nothing checks your changes automatically before they're merged, so broken code can land unnoticed. Add bkit's check workflow.",
167
189
  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".',
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.",
190
+ 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`, `bkit:lint:prose`, `bkit:slop:delta` and `test` scripts to package.json as listed in .bkit/templates.md § Gate tool scripts.",
169
191
  steps: "`.bkit/templates.md` § CI workflow and § Gate tool scripts.",
170
192
  fires: (cwd) => !exists(cwd, `.github/workflows/${readBkitConfig(cwd).ciWorkflow}`),
171
193
  },
@@ -195,7 +217,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
195
217
  title: "Catch junk code",
196
218
  line: "Nothing catches the junk code AI tends to write. Add slop-scan so new junk gets flagged before it's merged.",
197
219
  why: "Filler and dead code look fine when you skim a change, so they pile up unnoticed until the codebase is hard to trust. slop-scan flags only new problems, so it won't bury you in old ones.",
198
- ask: 'Run `pnpm add -D slop-scan`, copy .bkit/templates/slop-scan.config.json to slop-scan.config.json and .bkit/templates/scripts/slop/ to scripts/slop/, and add `"lint:slop": "slop-scan scan ."` and `"slop:delta": "bkit ci slop"` to the package.json scripts.',
220
+ ask: 'Run `pnpm add -D slop-scan`, copy .bkit/templates/slop-scan.config.json to slop-scan.config.json and .bkit/templates/scripts/slop/ to scripts/slop/, and add `"lint:slop": "slop-scan scan ."` and `"bkit:slop:delta": "bkit ci slop"` to the package.json scripts.',
199
221
  steps: "`.bkit/templates.md` § slop-scan.",
200
222
  fires: (cwd) => !exists(cwd, "slop-scan.config.json"),
201
223
  },
@@ -215,7 +237,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
215
237
  title: "Keep written docs tight",
216
238
  line: "Nothing checks the project's written docs, so they slowly fill with vague, padded wording that agents then have to read. Add Vale.",
217
239
  why: "Agents read your docs and instructions on every run. Padded writing costs time and money every time it's read, and vague rules get followed vaguely. Vale (a writing checker) flags it.",
218
- ask: "Run `brew install vale`, copy .bkit/templates/.vale.ini to .vale.ini and .bkit/templates/.vale/styles/House/ to .vale/styles/House/, then run `vale sync`.",
240
+ ask: "Run `brew install vale`, copy .bkit/templates/.vale.ini to .vale.ini and .bkit/templates/.vale/styles/Bkit/ to .vale/styles/Bkit/, then run `vale sync`.",
219
241
  steps: "`.bkit/templates.md` § Vale.",
220
242
  fires: (cwd) => !exists(cwd, ".vale.ini"),
221
243
  },
@@ -343,7 +365,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
343
365
  title: "Automatic updates",
344
366
  line: "Nothing keeps the project's libraries up to date. Add an updater so you get small, safe updates instead of one big risky one later.",
345
367
  why: "An updater opens a small pull request whenever a library you use has a new version. Skip it and updates pile up into one large upgrade that's far more likely to break something.",
346
- ask: "Copy .bkit/templates/.github/dependabot.yml to .github/dependabot.yml (or .bkit/templates/.github/renovate.json5 to .github/renovate.json5 for Renovate instead) and commit it to the default branch.",
368
+ ask: 'Copy .bkit/templates/.github/dependabot.yml to .github/dependabot.yml (or .bkit/templates/.github/renovate.json5 to .github/renovate.json5 for Renovate instead), set `bkit.dependencies.updater` in package.json to `"dependabot"` (or `"renovate"`), and commit both to the default branch.',
347
369
  steps: "`.bkit/templates.md` § Dependabot and Renovate.",
348
370
  advisories: ["dep-updater-absent"],
349
371
  fires: (cwd) => buildDepUpdaterSetupAdvisory(cwd)?.id === "dep-updater-absent",
@@ -360,6 +382,20 @@ export const SETUP_TIPS: readonly SetupTip[] = [
360
382
  fires: (cwd) =>
361
383
  exists(cwd, ".github/workflows") && !anyWorkflowMentions(cwd, "aquasecurity/trivy"),
362
384
  },
385
+ {
386
+ id: "dependency-audit",
387
+ workflows: ["ship", "audit"],
388
+ title: "Fail on a known-vulnerable dependency",
389
+ line: "A library with a published security advisory can sit in the lockfile for months: the updater only offers a fix, and nothing fails the check when one is missing. Add the gate that stops a known problem before it reaches CI.",
390
+ why: "An updater never blocks anything, so a risk with no fix yet, or one nobody merged, stays invisible. The gate names each exception with a reason and an expiry, fails on a new one, and fails even when it cannot get an answer — so a known problem is never a silent pass.",
391
+ ask: "Copy .bkit/templates/scripts/ci/bkit-check-dependency-audit.mjs and .bkit/templates/scripts/ci/bkit-accepted-advisories.json to scripts/ci/, then paste the `Dependency audit` block from .bkit/templates/.husky/pre-push into .husky/pre-push above the gates.",
392
+ steps:
393
+ "`.bkit/templates.md` § Dependency audit. Each acceptance needs a `reason` and a `YYYY-MM-DD` `expires`.",
394
+ fires: (cwd) =>
395
+ exists(cwd, ".husky/pre-push") &&
396
+ !exists(cwd, "scripts/ci/bkit-check-dependency-audit.mjs") &&
397
+ !exists(cwd, "scripts/ci/check-dependency-audit.mjs"),
398
+ },
363
399
  {
364
400
  id: "prettier-tables",
365
401
  workflows: ["design", "plan"],
@@ -385,12 +421,16 @@ export const SETUP_TIPS: readonly SetupTip[] = [
385
421
  workflows: ["plan", "ship"],
386
422
  title: "Quick pushes for logs and records",
387
423
  line: "Pushing only plan logs and records still runs every test. Add the quick path for those pushes.",
388
- why: "A workflow's last push is often just its logs and records. The quick path checks only formatting and wording on such a push, so it takes seconds and never waits on anything another session is using. Any other file still runs everything.",
389
- ask: 'Copy the min-push parts of .bkit/templates/.husky/pre-push into .husky/pre-push: PUSH_SHAS / PUSH_SHARED_SHAS in the stdin loop, the `Min push` and `CI-suppressor guard on dev / main` blocks, and the `bkit:gate:min` branch. Wrap slow checks below the gates in `if [ "$MIN_PUSH" != "1" ]`.',
424
+ why: "A workflow's last push is often just its logs and records. A successful full gate can cover the earlier code while the quick path checks the remaining bookkeeping. Any unverified code still runs the full gate.",
425
+ ask: 'Copy the min-push parts of .bkit/templates/.husky/pre-push into .husky/pre-push: PUSH_UPDATES / PUSH_SHARED_SHAS in the stdin loop, the `Min push` and `CI-suppressor guard on dev / main` blocks, and every `bkit ci push-gate` gate call. Wrap slow checks below the gates in `if [ "$MIN_PUSH" != "1" ]`.',
390
426
  steps: "`.bkit/templates.md` § Git hooks.",
391
- fires: (cwd) =>
392
- exists(cwd, ".husky/pre-push") &&
393
- !fs.readFileSync(path.join(cwd, ".husky/pre-push"), "utf-8").includes("bkit ci min-push"),
427
+ fires: (cwd) => {
428
+ if (!exists(cwd, ".husky/pre-push")) return false;
429
+ const hook = fs.readFileSync(path.join(cwd, ".husky/pre-push"), "utf-8");
430
+ return ["bkit ci min-push", "--update=", "bkit ci push-gate"].some(
431
+ (part) => !hook.includes(part),
432
+ );
433
+ },
394
434
  },
395
435
  {
396
436
  id: "disk-prune",
@@ -405,6 +445,17 @@ export const SETUP_TIPS: readonly SetupTip[] = [
405
445
  !exists(cwd, REPO_STEPS) &&
406
446
  !fs.existsSync(machineStepsPath()),
407
447
  },
448
+ {
449
+ id: "share-friction",
450
+ title: "Tell bkit what slowed you down",
451
+ line: "Your workflows have noted problems with bkit itself that its makers never see. Send them, with your stats, as one issue on bkit's issue page.",
452
+ why: "Workflows note every place bkit got in the way: a command that failed, rework, a manual step. Those notes stay in this repo, so the people who fix bkit never learn about them. One report from you is how they reach the fix list.",
453
+ caution:
454
+ "bkit's issue page is public. Your agent removes project names, paths and links first, and shows you the exact text before anything is posted.",
455
+ ask: "Share this repo's bkit friction and stats with bkit's makers as one new issue: follow the paste block in .bkit/README.md § Share friction with bkit, show me the exact title and text, and post only after I say yes.",
456
+ steps: "`.bkit/README.md` § Share friction with bkit.",
457
+ fires: hasUnsharedFriction,
458
+ },
408
459
 
409
460
  // --- setup: only some setups -----------------------------------------------------------
410
461
  {
@@ -414,7 +465,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
414
465
  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
466
  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
467
  steps:
417
- "`.bkit/workflows.md` § Workflow commands. Files: `.claude/hooks/`, `.husky/`, `.github/workflows/`, `scripts/`.",
468
+ "`.bkit/cli.md` § Contract. Files: `.claude/hooks/`, `.husky/`, `.github/workflows/`, `scripts/`.",
418
469
  fires: (cwd) => readsBkitText(cwd).length > 0,
419
470
  },
420
471
  {
@@ -431,7 +482,7 @@ export const SETUP_TIPS: readonly SetupTip[] = [
431
482
  title: "Tokens for apps opened from the Dock",
432
483
  line: "On a Mac, apps opened from the Dock don't see your sign-in tokens, so they start signed out even though the same thing works in the terminal. Add bkit's loader.",
433
484
  why: "The terminal loads your tokens, but apps started from the Dock or Finder skip that step. This one-time setup gives those apps the tokens too.",
434
- ask: "Copy .bkit/templates/scripts/launchd/bkit-launchd-env.sh to scripts/launchd/, .bkit/templates/scripts/launchd/launchd.env.example to ~/.config/bkit/launchd.env and .bkit/templates/scripts/launchd/ai.bkit.launchd.plist to ~/Library/LaunchAgents/ (fill in its paths), then run `launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.",
485
+ ask: "Copy .bkit/templates/scripts/launchd/bkit-launchd-env.sh to scripts/launchd/, .bkit/templates/scripts/launchd/bkit-launchd.env.example to ~/.config/bkit/launchd.env and .bkit/templates/scripts/launchd/bkit-launchd.plist to ~/Library/LaunchAgents/ai.bkit.launchd.plist (fill in its paths), then run `launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.bkit.launchd.plist`.",
435
486
  steps: "`.bkit/templates.md` § Launchd GUI environment.",
436
487
  fires: (cwd) => {
437
488
  if (process.platform !== "darwin" || isCloudOrCi()) return false;
@@ -3,6 +3,9 @@
3
3
 
4
4
  import * as fs from "node:fs";
5
5
  import * as path from "node:path";
6
+ import { git } from "../../commands/lib.js";
7
+ import { fold, parse } from "../../ledgers/telemetry.js";
8
+ import { BKIT_PACKAGE, cachedBkitOutdated } from "../../shared/bkit-latest.js";
6
9
  import { parseJson } from "../../shared/json.js";
7
10
  import { readDependencyNames, readPackageJson } from "../../shared/package-json.js";
8
11
 
@@ -219,3 +222,32 @@ export function readsBkitText(cwd: string): string[] {
219
222
  return text.split("\n").some((line) => READS_BKIT_TEXT.some((re) => re.test(line)));
220
223
  });
221
224
  }
225
+
226
+ /**
227
+ * True when `.bkit/friction.jsonl` holds an entry worth sending to bkit: its fold winner
228
+ * is `OPEN` (or has no status) and its `scope` is not `consumer`. A shared entry gets a
229
+ * same-`key` `TRIAGED` row, so it stops counting. Never in bkit's own repo.
230
+ */
231
+ export function hasUnsharedFriction(cwd: string): boolean {
232
+ const pkg = readPackageJson(cwd);
233
+ if (pkg.ok && pkg.pkg["name"] === BKIT_PACKAGE) return false;
234
+ const p = path.join(cwd, ".bkit", "friction.jsonl");
235
+ if (!fs.existsSync(p)) return false;
236
+ return [...fold(parse(fs.readFileSync(p, "utf-8")).events).values()].some((row) => {
237
+ const r = row as Record<string, unknown>;
238
+ return (
239
+ r["kind"] === "friction" &&
240
+ (r["status"] === undefined || r["status"] === "OPEN") &&
241
+ r["scope"] !== "consumer"
242
+ );
243
+ });
244
+ }
245
+
246
+ /**
247
+ * True when a newer bkit release is out than the one this repo runs, per the answer
248
+ * `bkit repo info` cached in git's common dir. Never asks the registry itself.
249
+ */
250
+ export function hasNewerBkit(cwd: string): boolean {
251
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
252
+ return common !== null && cachedBkitOutdated(cwd, common);
253
+ }
@@ -1,6 +1,15 @@
1
1
  // checks/tips/index.ts — collect the firing setup tips and render them for `bkit tips`, the
2
2
  // console checklist and `.bkit/advisories.md`. Catalogue + priority: ./catalogue.ts.
3
+ //
4
+ // Every `fires` reads the directory `tipsBase` returns — the main checkout, the tree the
5
+ // integration branch is checked out in — never the calling directory. A workflow runs in a
6
+ // worktree, but a worktree is an ephemeral branch: an empty or half-created one would fire
7
+ // every "file is missing" tip as a false gap. When no checkout is found at all, nothing fires.
3
8
 
9
+ import * as fs from "node:fs";
10
+ import * as path from "node:path";
11
+
12
+ import { git, mainCheckoutRoot } from "../../commands/lib.js";
4
13
  import type { PreflightFinding } from "../before/index.js";
5
14
  import {
6
15
  ignoredAdvisoryIds,
@@ -10,6 +19,33 @@ import {
10
19
  import type { TipsContext } from "../../cli.js";
11
20
  import { ALL_WORKFLOWS, SETUP_TIPS, type SetupTip } from "./catalogue.js";
12
21
 
22
+ /**
23
+ * The directory the tips are checked against: the main checkout's root — the tree the
24
+ * integration branch is checked out in — resolved from any worktree by
25
+ * `mainCheckoutRoot` (git's common dir), else `cwd` when git cannot say. A bare main
26
+ * repo has no checkout: the common dir's parent then belongs to no repo or to another
27
+ * one, so the caller's own top level is used. `null` when the base is not a checkout
28
+ * (holds neither `.git` nor `package.json`): a directory with nothing to check fires no
29
+ * tip rather than every "missing" tip as a false gap.
30
+ */
31
+ export function tipsBase(cwd: string): string | null {
32
+ const base = mainCheckoutOf(cwd) ?? git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
33
+ if (!fs.existsSync(base)) return null;
34
+ return fs.existsSync(path.join(base, ".git")) || fs.existsSync(path.join(base, "package.json"))
35
+ ? base
36
+ : null;
37
+ }
38
+
39
+ /** `mainCheckoutRoot(cwd)` when git there resolves to the same common dir, else null. */
40
+ function mainCheckoutOf(cwd: string): string | null {
41
+ const commonDir = (dir: string) =>
42
+ git(dir, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
43
+ const root = mainCheckoutRoot(cwd);
44
+ if (root === null || !fs.existsSync(root)) return null;
45
+ const own = commonDir(cwd);
46
+ return own !== null && commonDir(root) === own ? root : null;
47
+ }
48
+
13
49
  /** Tips `bkit tips` prints without `--all` or `--workflow`. */
14
50
  export const TIPS_CAP = 3;
15
51
 
@@ -54,15 +90,16 @@ export const STAR_TIP_PARAGRAPH = STAR_TIP.replace("Do you like bkit?", "**Do yo
54
90
 
55
91
  /** Intro of the Setup tips section: who reads which field, and how to silence a tip. */
56
92
  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.advisories.ignore` in package.json. Full template catalogue: .bkit/templates.md.";
93
+ "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; `bkit-upgrade` cannot be silenced. Full template catalogue: .bkit/templates.md.";
58
94
 
59
95
  /** True when advisory `id` matches catalogue pattern `pattern` (trailing `*` = prefix). */
60
96
  export function matchesAdvisory(pattern: string, id: string): boolean {
61
97
  return pattern.endsWith("*") ? id.startsWith(pattern.slice(0, -1)) : id === pattern;
62
98
  }
63
99
 
64
- /** True when `ignored` names the tip's id or any advisory id it reuses. */
100
+ /** True when `ignored` names the tip's id or any advisory id it reuses; never for an unsilenceable tip. */
65
101
  export function isTipSilenced(tip: SetupTip, ignored: ReadonlySet<string>): boolean {
102
+ if (tip.silenceable === false) return false;
66
103
  if (ignored.has(tip.id)) return true;
67
104
  const patterns = tip.advisories ?? [];
68
105
  return [...ignored].some((id) => patterns.some((p) => matchesAdvisory(p, id)));
@@ -79,11 +116,13 @@ export interface TipsResult {
79
116
 
80
117
  /** Every firing tip in priority order, minus the ones the root package.json silences. */
81
118
  export function collectTips(cwd: string, catalogue: readonly SetupTip[] = SETUP_TIPS): TipsResult {
82
- const ignored = ignoredAdvisoryIds(cwd);
119
+ const base = tipsBase(cwd);
120
+ if (base === null) return { tips: [], suppressed: [], star: false };
121
+ const ignored = ignoredAdvisoryIds(base);
83
122
  const tips: SetupTip[] = [];
84
123
  const suppressed: SuppressionNote[] = [];
85
124
  for (const tip of catalogue) {
86
- if (!tip.fires(cwd)) continue;
125
+ if (!tip.fires(base)) continue;
87
126
  if (isTipSilenced(tip, ignored)) suppressed.push({ id: tip.id, scope: "." });
88
127
  else tips.push(tip);
89
128
  }
@@ -102,7 +141,9 @@ export function dropTipSilencedAdvisories(
102
141
  onSuppressed?: SuppressionReporter,
103
142
  catalogue: readonly SetupTip[] = SETUP_TIPS,
104
143
  ): PreflightFinding[] {
105
- const ignored = ignoredAdvisoryIds(cwd);
144
+ const base = tipsBase(cwd);
145
+ if (base === null) return findings;
146
+ const ignored = ignoredAdvisoryIds(base);
106
147
  if (ignored.size === 0) return findings;
107
148
  const patterns = catalogue
108
149
  .filter((tip) => isTipSilenced(tip, ignored))
@@ -169,7 +210,7 @@ function formatWorkflowTips(
169
210
  star: boolean,
170
211
  ): string {
171
212
  const shown = orderForWorkflow(tips, workflow).slice(0, WORKFLOW_TIPS_CAP);
172
- const ids = shown.map((t) => t.id);
213
+ const ids = shown.filter((t) => t.silenceable !== false).map((t) => t.id);
173
214
  const parts = shown.map(tipParagraph);
174
215
  if (star) {
175
216
  parts.push(STAR_TIP_PARAGRAPH);