@cbartens/bkit 5.5.1 → 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 (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -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 +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  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 +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -5,7 +5,7 @@
5
5
  #!/usr/bin/env python3
6
6
  """Collapse the whole-symbol code graph into two readable views.
7
7
 
8
- Called by `pnpm graph:rollup` and `pnpm graph:graphml` (scripts/graphify/
8
+ Called by `pnpm bkit:graph:rollup` and `pnpm bkit:graph:graphml` (scripts/graphify/
9
9
  bkit-graphify.sh) through GRAPHIFY'S OWN interpreter, not the system python — it
10
10
  imports networkx, which is a graphify dependency and is not installed repo-wide.
11
11
 
@@ -16,9 +16,9 @@ Both outputs are opt-in, and the two commands ask for different ones:
16
16
 
17
17
  --build-dir a graphify-format graph.json per level, which the caller
18
18
  renders to interactive HTML via `graphify cluster-only`,
19
- then moves and deletes. This is `pnpm graph:rollup`.
19
+ then moves and deletes. This is `pnpm bkit:graph:rollup`.
20
20
  --*-graphml the same two views as GraphML for Gephi. Only `pnpm
21
- graph:graphml` asks for these — GraphML is not produced by
21
+ bkit:graph:graphml` asks for these — GraphML is not produced by
22
22
  default.
23
23
 
24
24
  Node attrs: symbols, files, internal_edges. Edge attrs: weight (number of
@@ -59,7 +59,7 @@ SRC = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".sql")
59
59
  # graphify misses two whole classes of import: a `.js` specifier is never
60
60
  # resolved to a `.tsx` file, and workspace subpaths through an `exports` map are
61
61
  # not resolved at all. bkit-graph-repair.py writes them into graph.json during
62
- # `pnpm graph`, so this reads them like any other edge and does NOT add them on
62
+ # `pnpm bkit:graph`, so this reads them like any other edge and does NOT add them on
63
63
  # read. A graph lacking any of them gets a warning, and the numbers below are
64
64
  # understated.
65
65
  # bkit-graph-imports.py is hyphenated, which `import` cannot spell, so it is loaded
@@ -207,61 +207,86 @@ def as_graphify_json(keyfn, out_dir):
207
207
  return len(payload["nodes"]), len(payload["links"])
208
208
 
209
209
 
210
- # Two visual channels, one meaning each:
211
- # colour = the CALLED capability. A node that is called owns a hue, and
212
- # every edge INTO it takes that hue, so all the callers of one
213
- # capability are one colour and can be followed back at a glance.
214
- # A node nothing calls has no hue and stays grey — web and mobile
215
- # routes only ever call, so the whole UI column is grey.
216
- # dash + fill = drift status.
217
- # Hues are mid-tone, legible on both the light and dark Mermaid themes. An undrifted
218
- # node sets no fill, so it keeps the theme's background and text colour.
219
- PALETTE = [
220
- "#d73a4a", "#0969da", "#1a7f37", "#9a6700", "#8250df", "#bf3989",
221
- "#0e7490", "#a0522d", "#5b8c00", "#b45309", "#6d28d9", "#be123c",
222
- "#0f766e", "#4d7c0f", "#a21caf", "#1d4ed8", "#c2410c", "#15803d",
223
- "#7c3aed", "#b91c1c", "#0891b2", "#65a30d", "#c026d3", "#2563eb",
224
- ]
225
- # Drift = a dashed border plus a tinted box; no tint and a solid border means no
226
- # drift. Each drift status has its own dash pattern. The status colours the BOX;
227
- # the label carries no emoji (GitHub renders Mermaid at securityLevel strict).
228
- # Every fill pins its own `color` (INK), so text stays dark on any theme.
229
- INK, PAPER = "#1f2328", "#ffffff"
230
- # ONE colour (amber) for every drift status; the status word and the dash pattern
231
- # tell them apart.
232
- WARN = "#ffcc80"
233
- # `budgeted` is the one marked state that is NOT a warning: solid border, blue tint.
234
- # It still gets a box. Blue, not green: green reads as `one`.
235
- SETTLED = "#cfe2f3"
236
- DRIFT_STYLE = {"split": f"stroke-width:4px,stroke-dasharray:2 3,fill:{WARN},color:{INK}",
237
- "bypassed": f"stroke-width:4px,stroke-dasharray:8 4,fill:{WARN},color:{INK}",
238
- "gap": f"stroke-width:3px,stroke-dasharray:1 5,fill:{WARN},color:{INK}",
239
- "dead": f"stroke-width:4px,stroke-dasharray:3 3,fill:{WARN},color:{INK}",
240
- "budgeted": f"stroke-width:3px,fill:{SETTLED},color:{INK}",
241
- "ok": "stroke-width:2px"}
242
-
243
-
244
- def hue(key):
245
- """Stable per-node colour. Hashed, not enumerated, so adding a node upstream
246
- does not recolour every node after it and churn the whole diff."""
247
- return PALETTE[int(hashlib.md5(key.encode()).hexdigest(), 16) % len(PALETTE)]
248
-
249
-
250
- GREY = "#8b949e"
251
-
252
-
253
- def style_lines(nodes, edge_target_keys):
254
- """`style` per node and `linkStyle` per edge.
255
-
256
- Pass the TARGET key of each edge, in emission order — linkStyle indexes are
257
- that order, and the colour belongs to the capability being called, not the
258
- caller. A node that is never a target keeps the grey default.
210
+ # Three visual channels, one meaning each:
211
+ # box colour = the top-level group a box sits in. The group's outline and every
212
+ # box inside it share one hue, picked from the group's key, so a
213
+ # group keeps its colour from run to run. A box in no group is grey.
214
+ # A chart with ONE top-level group draws it grey and gives every
215
+ # box its own hue, because one colour for the whole chart says nothing.
216
+ # red, dashed = an open drift status; each status has its own dash pattern.
217
+ # arrow width = how many links an edge carries, in thirds of the chart's own
218
+ # weights. Arrows are grey; a box is the only thing that is coloured.
219
+ # Every colour is a bkit README token, light-theme value, each at least 3:1 against
220
+ # both a white and a #0d1117 page. A fill is the token at low alpha, so it tints
221
+ # whatever background the theme draws and the theme's own text stays readable.
222
+ # The hues are the four phase colours (design, plan, build, ship). Debug red and
223
+ # gate amber are left out: here they mean an open problem and an accepted one.
224
+ PALETTE = ["#8250df", "#0969da", "#1a7f37", "#0a7b83"]
225
+ ISSUE = "#cf222e"
226
+ # `budgeted` is a drift status somebody has accepted, with a count the gate holds
227
+ # it to: solid gate amber, not dashed red.
228
+ NOTED = "#bf8700"
229
+ GREY = "#59636e"
230
+ ISSUE_DASH = {"split": "2 3", "bypassed": "8 4", "gap": "1 5", "dead": "3 3"}
231
+ GROUP_WASH, HUE_WASH, ISSUE_WASH = "0a", "14", "26" # alpha: 4%, 8% and 15%
232
+ # (width, alpha) for the light, middle and heavy third of the edges.
233
+ EDGE_TIERS = [(2, "80"), (3, "b3"), (6, "")]
234
+ # GitHub draws arrowheads at a fixed 8px whatever the line width; this scales them
235
+ # to match the thicker lines. Front matter, so it applies per diagram.
236
+ FRONT_MATTER = ["---", "config:", " layout: elk",
237
+ ' themeCSS: "marker { overflow: visible; } '
238
+ 'marker path { transform: scale(1.8); transform-origin: 5px 5px; }"',
239
+ " flowchart:", " useMaxWidth: false", "---"]
240
+
241
+
242
+ def hues(keys):
243
+ """Stable per-node colours. Each key starts at its hashed hue, not an enumerated
244
+ one, so adding a node upstream does not recolour every node after it and churn
245
+ the whole diff. A key whose hue is taken steps to the next free one, so the
246
+ palette is used up before any two nodes share a colour."""
247
+ out, taken = {}, collections.Counter()
248
+ for key in sorted(keys):
249
+ start = int(hashlib.md5(key.encode()).hexdigest(), 16) % len(PALETTE)
250
+ least = min(taken[c] for c in PALETTE)
251
+ i = next(j for j in range(len(PALETTE))
252
+ if taken[PALETTE[(start + j) % len(PALETTE)]] == least)
253
+ out[key] = PALETTE[(start + i) % len(PALETTE)]
254
+ taken[out[key]] += 1
255
+ return out
256
+
257
+
258
+ def node_style(cls, hue):
259
+ if cls in ISSUE_DASH:
260
+ return (f"stroke:{ISSUE},stroke-width:4px,stroke-dasharray:{ISSUE_DASH[cls]},"
261
+ f"fill:{ISSUE}{ISSUE_WASH}")
262
+ if cls == "budgeted":
263
+ return f"stroke:{NOTED},stroke-width:3px,fill:{NOTED}{ISSUE_WASH}"
264
+ return f"stroke:{hue},stroke-width:2px,fill:{hue}{HUE_WASH}"
265
+
266
+
267
+ def style_lines(nodes, edge_weights, groups=()):
268
+ """`style` per node and subgraph, and `linkStyle` per edge.
269
+
270
+ nodes are (id, colour key, status, own key) and groups are (id, colour key,
271
+ top level); a None colour key is grey. Pass each edge's weight in emission
272
+ order — linkStyle indexes are that order. An unweighted edge (None) is drawn
273
+ in the middle tier.
259
274
  """
260
- called = set(edge_target_keys)
261
- out = [f" style {nid} stroke:{hue(key) if key in called else GREY},{DRIFT_STYLE[cls]}"
262
- for nid, key, cls in nodes]
263
- for i, tgt_key in enumerate(edge_target_keys):
264
- out.append(f" linkStyle {i} stroke:{hue(tgt_key)},stroke-width:2px")
275
+ if len({c for _, c, top in groups if top}) == 1:
276
+ nodes = [(nid, own, cls, own) for nid, _, cls, own in nodes]
277
+ groups = [(gid, None, top) for gid, _, top in groups]
278
+ # A flagged box is drawn red or amber, so it takes no hue from the palette.
279
+ hue = hues({c for _, c, cls, _ in nodes if c and cls == "ok"}
280
+ | {c for _, c, _ in groups if c})
281
+ out = [f" style {gid} fill:{hue.get(c, GREY)}{GROUP_WASH},stroke:{hue.get(c, GREY)},stroke-width:2px"
282
+ if top else f" style {gid} fill:transparent,stroke:{hue.get(c, GREY)},stroke-width:1px"
283
+ for gid, c, top in groups]
284
+ out += [f" style {nid} {node_style(cls, hue.get(c, GREY))}" for nid, c, cls, _ in nodes]
285
+ known = sorted(w for w in edge_weights if w is not None)
286
+ cuts = (known[len(known) // 3], known[2 * len(known) // 3]) if known else (0, 0)
287
+ for i, w in enumerate(edge_weights):
288
+ width, alpha = EDGE_TIERS[1 if w is None else sum(w >= c for c in cuts)]
289
+ out.append(f" linkStyle {i} stroke:{GREY}{alpha},stroke-width:{width}px")
265
290
  return out
266
291
 
267
292
 
@@ -273,6 +298,7 @@ OV_DEFAULT = """{
273
298
  "rename": {},
274
299
  "note": {},
275
300
  "hide_nodes": [],
301
+ "hide_nodes_why": {},
276
302
  "hide_edges": [],
277
303
  "group": {}
278
304
  }"""
@@ -324,13 +350,33 @@ def resolve_paint(overlay, keys):
324
350
  best = k
325
351
  if best is not None:
326
352
  acc[best].append(val)
353
+ # The box counts its findings, e.g. "1 open finding" or "1 open · 2 budgeted
354
+ # findings"; the register table names them.
327
355
  out = {}
328
356
  for k, vals in acc.items():
329
357
  cls = max((v[0] for v in vals), key=lambda c: rank.get(c, 0))
330
- out[k] = (cls, " · ".join(v[1] for v in sorted(vals, key=lambda v: -rank.get(v[0], 0))))
358
+ budgeted = sum(v[0] == "budgeted" for v in vals)
359
+ counts = [f"{n} {word}" for n, word in ((len(vals) - budgeted, "open"), (budgeted, "budgeted")) if n]
360
+ out[k] = (cls, " · ".join(counts) + (" finding" if len(vals) == 1 else " findings"))
331
361
  return out
332
362
 
333
363
 
364
+ def base_parts(edges, keep, flagged):
365
+ """Parts nearly everything uses: {key: caller count}.
366
+
367
+ A base part calls nothing in the chart, and at least a quarter of the other
368
+ boxes (four at least) call it. Its arrows only say "everyone uses this", so the
369
+ chart leaves them out and the box counts its callers. A flagged box is never
370
+ one: its arrows show how far the problem reaches.
371
+ """
372
+ callers, calls = collections.defaultdict(set), {a for a, _ in edges}
373
+ for a, b in edges:
374
+ callers[b].add(a)
375
+ need = max(4, (len(keep) - 1) / 4)
376
+ return {k: len(callers[k]) for k in keep
377
+ if k not in calls and k not in flagged and len(callers[k]) >= need}
378
+
379
+
334
380
  def as_mermaid(keyfn, out, level, min_weight, overlay):
335
381
  """Emit the rollup as a Mermaid flowchart, nested by folder.
336
382
 
@@ -358,6 +404,8 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
358
404
  sid = lambda k: "n" + re.sub(r"[^a-z0-9]", "_", k.lower())
359
405
 
360
406
  resolved = resolve_paint(overlay, keep)
407
+ base = base_parts(edges, keep, resolved)
408
+ edges = {e: w for e, w in edges.items() if e[1] not in base}
361
409
 
362
410
  def paint(k):
363
411
  if k in resolved:
@@ -365,23 +413,37 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
365
413
  return cls, "<br/>" + note
366
414
  return "ok", ""
367
415
 
368
- L = ["---", "config:", " layout: elk", " flowchart:", " useMaxWidth: false", "---",
416
+ L = [*FRONT_MATTER,
369
417
  "flowchart LR",
370
- f" %% Generated by bkit-graphify-rollup.py from {raw.get('built_at_commit', '?')} — do not edit"]
371
- NODES, ELIST = [], []
372
- def node(k, label, indent):
418
+ " %% Generated by bkit-graphify-rollup.py — do not edit"]
419
+ NODES, ELIST, GROUPS = [], [], []
420
+ def node(k, label, indent, colour=None):
373
421
  cls, note = paint(k)
374
422
  label = renames.get(k, label)
423
+ if k in base:
424
+ note += f"<br/>used by {base[k]} parts, arrows left out"
375
425
  if k in extra_notes:
376
426
  note += "<br/>" + extra_notes[k]
377
- NODES.append((sid(k), k, cls))
427
+ NODES.append((sid(k), colour, cls, k))
378
428
  L.append(f'{indent}{sid(k)}["{label}<br/>'
379
429
  f'{symbols[k]} symbols · {len(files[k])} files{note}"]')
380
430
 
381
431
  if level == "package":
382
- # The group IS the node at this level; no subgraph per group.
432
+ # One subgraph per parent folder (apps, packages, .bkit/core/engine), drawn
433
+ # only around two or more boxes; a lone box keeps its full path instead.
434
+ parents = collections.defaultdict(list)
383
435
  for k in sorted(keep):
384
- node(k, k, " ")
436
+ parents[k.rsplit("/", 1)[0] if "/" in k else ""].append(k)
437
+ for p, members in sorted(parents.items()):
438
+ if not p or len(members) == 1:
439
+ for k in members:
440
+ node(k, k, " ")
441
+ continue
442
+ GROUPS.append((f"g{sid(p)}", p, True))
443
+ L.append(f' subgraph {GROUPS[-1][0]}["{p}"]')
444
+ for k in members:
445
+ node(k, k.rsplit("/", 1)[1], " ", p)
446
+ L.append(" end")
385
447
  else:
386
448
  # The folder tree, drawn as nested subgraphs — Mermaid nests them to any
387
449
  # depth. A chain of single-child directories (apps > apps/web > .../src)
@@ -391,9 +453,10 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
391
453
  if k in forced:
392
454
  grouped[forced[k]].append(k)
393
455
  for g, members in sorted(grouped.items()):
394
- L.append(f' subgraph g{sid("custom-" + g)}["{g}"]')
456
+ GROUPS.append((f'g{sid("custom-" + g)}', "custom-" + g, True))
457
+ L.append(f' subgraph {GROUPS[-1][0]}["{g}"]')
395
458
  for k in members:
396
- node(k, k, " ")
459
+ node(k, k, " ", "custom-" + g)
397
460
  L.append(" end")
398
461
 
399
462
  tree = {}
@@ -405,13 +468,13 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
405
468
  cur = cur.setdefault(seg, {})
406
469
  cur["__leaf__"] = k
407
470
 
408
- def emit(subtree, path, depth, root=False):
471
+ def emit(subtree, path, depth, root=False, top=None):
409
472
  dirs = {k: v for k, v in subtree.items() if k != "__leaf__"}
410
473
  leaf = subtree.get("__leaf__")
411
474
  pad = " " * (depth + 1)
412
475
  if leaf and not dirs:
413
476
  # At the top level the short name has lost its folder, so carry the path.
414
- node(leaf, path if root else path.split("/")[-1], pad)
477
+ node(leaf, path if root else path.split("/")[-1], pad, top)
415
478
  return
416
479
  title, inner = path, subtree
417
480
  while not inner.get("__leaf__") and len(
@@ -422,13 +485,15 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
422
485
  if inner.get("__leaf__") and not inner_dirs:
423
486
  # A box around exactly one node is the node, drawn twice. Emit the
424
487
  # node carrying the full path instead, so it keeps its context.
425
- node(inner["__leaf__"], title, pad)
488
+ node(inner["__leaf__"], title, pad, top)
426
489
  return
427
- L.append(f'{pad}subgraph g{sid(title)}["{title}"]')
490
+ GROUPS.append((f"g{sid(title)}", top or title, top is None))
491
+ top = top or title
492
+ L.append(f'{pad}subgraph {GROUPS[-1][0]}["{title}"]')
428
493
  if inner.get("__leaf__"):
429
- node(inner["__leaf__"], title.split("/")[-1], pad + " ")
494
+ node(inner["__leaf__"], title.split("/")[-1], pad + " ", top)
430
495
  for seg, sub in sorted((k, v) for k, v in inner.items() if k != "__leaf__"):
431
- emit(sub, f"{title}/{seg}", depth + 1)
496
+ emit(sub, f"{title}/{seg}", depth + 1, top=top)
432
497
  L.append(f"{pad}end")
433
498
 
434
499
  # The root segment is dropped: an `apps` box around apps/web and apps/mobile
@@ -441,9 +506,9 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
441
506
  emit(sub2, f"{seg}/{child}", 0, root=True)
442
507
 
443
508
  for (a, b), w in sorted(edges.items(), key=lambda x: -x[1]):
444
- ELIST.append(b)
509
+ ELIST.append(w)
445
510
  L.append(f" {sid(a)} -->|{w}| {sid(b)}")
446
- L += style_lines(NODES, ELIST)
511
+ L += style_lines(NODES, ELIST, GROUPS)
447
512
  # The YAML front matter must be the FIRST thing in the file. A leading %%
448
513
  # provenance comment makes Mermaid fail with a bare "Parse error on line 1"
449
514
  # that names nothing, so the marker goes inside the graph instead.
@@ -451,7 +516,7 @@ def as_mermaid(keyfn, out, level, min_weight, overlay):
451
516
  if out:
452
517
  with open(out, "w") as fh:
453
518
  fh.write(text)
454
- print(f"[graph] {out or 'inline'}: {len(keep)} nodes, {len(edges)} edges "
519
+ print(f"[graph] {out or 'inline'}: {len(keep)} nodes, {len(edges)} edges, {len(base)} base "
455
520
  f"(level={level}, min-weight={min_weight}, {len(overlay)} drift markers)")
456
521
  return text
457
522
 
@@ -512,24 +577,33 @@ def chain_block(surface, overlay, reach):
512
577
  provs = sorted(p for p in ext if p not in hidden
513
578
  and any(not is_test_code(c) for c in ext[p]["callers"]))
514
579
 
515
- L = ["---", "config:", " layout: elk", " flowchart:", " useMaxWidth: false", "---",
580
+ dead_any = (reach or {}).get("unreachable") or (reach or {}).get("strandedHonoRoutes")
581
+ if not (used_eps or mods or provs or dead_any):
582
+ return None, 0
583
+
584
+ L = [*FRONT_MATTER,
516
585
  "flowchart LR"]
517
586
  NODES, ELIST = [], []
587
+ col = [None]
588
+
589
+ def column(gid, title):
590
+ col[0] = gid
591
+ L.append(f' subgraph {gid}["{title}"]')
518
592
 
519
593
  def decl(nid, key, label, cls="ok", indent=" "):
520
- NODES.append((nid, key, cls))
594
+ NODES.append((nid, col[0], cls, key))
521
595
  L.append(f'{indent}{nid}["{label}"]')
522
596
 
523
597
  for platform, title in (("web", "apps/web routes"), ("native", "apps/mobile routes")):
524
598
  members = [r for r, d in sorted(routes.items())
525
599
  if d["platform"] == platform and r not in hidden]
526
600
  if members:
527
- L.append(f' subgraph gp_{platform}["UI — {title}"]')
601
+ column(f"gp_{platform}", f"UI — {title}")
528
602
  for r in members:
529
603
  decl(sid("r_", r), r, renames.get(r, r))
530
604
  L.append(" end")
531
605
 
532
- L.append(' subgraph gp_ep["API — /api/v1 endpoints"]')
606
+ column("gp_ep", "API — /api/v1 endpoints")
533
607
  for seg in used_eps:
534
608
  decl(sid("e_", seg), seg, f"/{seg}")
535
609
  L.append(" end")
@@ -547,7 +621,7 @@ def chain_block(surface, overlay, reach):
547
621
  stranded = [r for r in (reach or {}).get("strandedHonoRoutes", [])
548
622
  if r not in hidden and r not in dead_keys]
549
623
  if dead or stranded:
550
- L.append(' subgraph gp_dead["UNREACHABLE — 404 at runtime"]')
624
+ column("gp_dead", "UNREACHABLE — 404 at runtime")
551
625
  for key, sites, refused in dead:
552
626
  where = "<br/>".join(sites[:3]) + ("<br/>…" if len(sites) > 3 else "")
553
627
  decl(sid("d_", key), key, f"{key}<br/>{refused}<br/>{where}", "dead")
@@ -556,19 +630,19 @@ def chain_block(surface, overlay, reach):
556
630
  L.append(" end")
557
631
 
558
632
  all_routers = sorted({rf for v in routers.values() for rf in v} - hidden)
559
- L.append(' subgraph gp_rt["API — Hono routers"]')
633
+ column("gp_rt", "API — Hono routers")
560
634
  for rf in all_routers:
561
635
  decl(sid("t_", rf), rf, f"routes/{rf}.ts")
562
636
  L.append(" end")
563
637
 
564
- L.append(' subgraph gp_svc["BACKEND — modules"]')
638
+ column("gp_svc", "BACKEND — modules")
565
639
  for m in mods:
566
640
  cls, note = paint(m)
567
641
  decl(sid("s_", m), m, f"{renames.get(m, m)}{note}", cls)
568
642
  L.append(" end")
569
643
 
570
644
  if provs:
571
- L.append(' subgraph gp_ext["EXTERNAL — third-party APIs"]')
645
+ column("gp_ext", "EXTERNAL — third-party APIs")
572
646
  for pv in provs:
573
647
  d = ext[pv]
574
648
  # Reached by BOTH a client library and a hand-rolled fetch = two
@@ -588,10 +662,10 @@ def chain_block(surface, overlay, reach):
588
662
 
589
663
  drawn = set()
590
664
 
591
- def edge(a, b, tgt_key):
665
+ def edge(a, b):
592
666
  if (a, b) not in drawn:
593
667
  drawn.add((a, b))
594
- ELIST.append(tgt_key)
668
+ ELIST.append(None)
595
669
  L.append(f" {a} --> {b}")
596
670
 
597
671
  for r, d in sorted(routes.items()):
@@ -599,19 +673,19 @@ def chain_block(surface, overlay, reach):
599
673
  continue
600
674
  for seg in d["endpoints"]:
601
675
  if seg in used_eps:
602
- edge(sid("r_", r), sid("e_", seg), seg)
676
+ edge(sid("r_", r), sid("e_", seg))
603
677
  for seg in used_eps:
604
678
  for rf in routers[seg]:
605
679
  if rf not in hidden:
606
- edge(sid("e_", seg), sid("t_", rf), rf)
680
+ edge(sid("e_", seg), sid("t_", rf))
607
681
  for sv in svc_of[seg]:
608
682
  m = f"packages/services/src/{sv}"
609
683
  if m in mods:
610
- edge(sid("t_", rf), sid("s_", m), m)
684
+ edge(sid("t_", rf), sid("s_", m))
611
685
  for pv in provs:
612
686
  for c in ext[pv]["callers"]:
613
687
  if c in mods:
614
- edge(sid("s_", c), sid("x_", pv), pv)
688
+ edge(sid("s_", c), sid("x_", pv))
615
689
  # Only when the call sits in the route file itself. Any other dead call stands
616
690
  # alone; the call site in its label says where to look.
617
691
  route_of_file = {d["file"]: r for r, d in routes.items() if r not in hidden}
@@ -619,8 +693,8 @@ def chain_block(surface, overlay, reach):
619
693
  for site in sites:
620
694
  r = route_of_file.get(site.rsplit(":", 1)[0])
621
695
  if r:
622
- edge(sid("r_", r), sid("d_", key), key)
623
- L += style_lines(NODES, ELIST)
696
+ edge(sid("r_", r), sid("d_", key))
697
+ L += style_lines(NODES, ELIST, [(g, g, True) for g in re.findall(r"subgraph (gp_\w+)", "\n".join(L))])
624
698
  return "\n".join(L), len(routes)
625
699
 
626
700
 
@@ -637,8 +711,8 @@ def eager_block(eager):
637
711
  L = [
638
712
  f"{sites} module-scope side effects in {len(eager['files'])} of {eager['scanned']} "
639
713
  f"source files. A call here runs on **import**, not on first use, so every file "
640
- f"downstream pays for it, because under Jest that is a mandatory stub in tests that never "
641
- f"touch the thing. Sorted by reach.",
714
+ f"downstream pays for it, and a test that never touches the thing still has to stub it. "
715
+ f"Sorted by reach.",
642
716
  "",
643
717
  "<!-- prettier-ignore -->",
644
718
  "| File | Evaluates at import | Downstream files | of which tests |",
@@ -652,7 +726,7 @@ def eager_block(eager):
652
726
  if eager.get("not_in_graph"):
653
727
  L += ["", f"> [!WARNING]", f"> {eager['not_in_graph']} scanned files are absent from "
654
728
  "`graph.json`, so only the column-0 filter applied to them and their downstream "
655
- "counts are 0. Run `pnpm graph:update` and re-run the rollup."]
729
+ "counts are 0. Run `pnpm bkit:graph:update` and re-run the rollup."]
656
730
  return L
657
731
 
658
732
 
@@ -669,7 +743,7 @@ def reachability_block(reach):
669
743
  L = [
670
744
  "A request URL is a string inside a template literal, so nothing that reads types can",
671
745
  "see that it has no server-side counterpart, because `lint`, `check:type`, `knip` and",
672
- "`slop:delta` all pass on a path that 404s. This is the one drift class no graph query",
746
+ "`bkit:slop:delta` all pass on a path that 404s. This is the one drift class no graph query",
673
747
  "finds either: a string is not an edge. Scanned every run by",
674
748
  "`scripts/ci/guards/assert-routes-reachable.mjs`; run it alone for the full served-route inventory.",
675
749
  "",
@@ -719,9 +793,8 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
719
793
  Source of truth is bkit-graph-drift-rules.json (which capability, which owner,
720
794
  which literal marker); every status in the table is derived from live source
721
795
  by bkit-graph-drift.py, never typed in. Editing this file by hand loses the edit
722
- on the next `pnpm graph:rollup`.
796
+ on the next `pnpm bkit:graph:rollup`.
723
797
  """
724
- GRAPH_COMMIT = str(raw.get("built_at_commit") or "unknown")
725
798
  ROUTES_MMD, n_routes = chain_block(surface, overlay, reach)
726
799
  ROUTES_PROSE = (
727
800
  f"{n_routes} routes across web and native, each linked to the service domains it reaches. "
@@ -730,7 +803,8 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
730
803
  "symbol, followed through `v1.ts` to the router file and its service imports. Attribution "
731
804
  "is per symbol, not per file, so a domain named only in a shared helper's comment is not "
732
805
  "credited to every page that imports the helper."
733
- ) if ROUTES_MMD else "No route layer; run with `--surface`."
806
+ ) if ROUTES_MMD else ("No route layer: the surface scan found nothing to draw." if surface
807
+ else "No route layer; run with `--surface`.")
734
808
  order = {"split": 0, "gap": 1, "bypassed": 2, "budgeted": 3, "one": 4, "unchecked": 5}
735
809
  rows = sorted(rows, key=lambda r: (order.get(r["status"], 9), r["lane"], r["capability"]))
736
810
  counts = collections.Counter(r["status"] for r in rows)
@@ -760,15 +834,15 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
760
834
  ">",
761
835
  "> **Rules:**",
762
836
  ">",
763
- "> - Generated — do not edit. `pnpm graph:refresh` rewrites this file.",
837
+ "> - Generated — do not edit. `pnpm bkit:graph:refresh` rewrites this file.",
764
838
  f"> - Source of truth: `{rules_path}`. Every status derived from live source, never typed.",
765
839
  "> - Add a capability = add a rule there: capability · lane · owner module · one literal marker.",
766
- "> - Markers literal, never regex, because `new Ratelimit(` as a regex is an unclosed group matching nothing.",
840
+ "> - Markers literal, never regex, because `new Client(` as a regex is an unclosed group matching nothing.",
767
841
  "> - Match the mechanism, not the name, because `createClient(` misses an owner that aliases its import.",
768
842
  "> - Optional `scope` narrows the tree scanned when a marker means different things per package.",
769
843
  "> - Optional `surface`: `product` (default) · `tests` (any `e2e/` dir + every `.test.` / `.spec.` file) · `all`. The two surfaces partition the tree.",
770
844
  "> - Optional `budgets`: the exact non-owner site count allowed per scope prefix. Measured == declared everywhere ⇒ `budgeted`, which is not a warning.",
771
- "> - A budget is not a shrug, because `owned-query-shape-guard.test.ts` reds CI when the count moves either way, and a site landing outside every declared prefix reads as over budget.",
845
+ "> - A budget is not a shrug, because the row leaves `budgeted` and its Budget cell reads `over` or `stale` when the count moves either way, and a site landing outside every declared prefix reads as over budget.",
772
846
  "> - Test code is in `graph.json` on purpose (`.graphifyignore`) and out of every diagram here by rule (`is_test_code` in `bkit-graphify-rollup.py`): test folders, `.test.` / `.spec.` files, test-runner config. `hide_nodes` below is diagram-only too, for whatever else a picture should not draw.",
773
847
  "> - Status computed: no owner → `split`; owner absent → `gap`; owner present, others use marker → `bypassed`; else `one`. A `split|bypassed` at budget → `budgeted`.",
774
848
  "> - Externals: `scripts/graphify/bkit-graph-external-rules.json` — `sdk` · `hosts` · `env`. SDK and url = `split`.",
@@ -776,28 +850,30 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
776
850
  "> - That scan reads source, not the graph, because module-level initialiser calls are the one construct graphify drops.",
777
851
  "> - Nothing discovers an SDK itself; find gaps by listing non-workspace deps.",
778
852
  "> - Only the Overrides block is hand-maintained. It round-trips; malformed aborts the run.",
779
- "> - Colour = called capability, shared by its inbound edges. Grey = never called.",
780
- "> - Drift = dashed border + one amber box for all four. No ranking: each scan proves a shape, never an intent.",
781
- "> - `budgeted` = solid border + blue box. Still drawn, because a declared bypass is still a bypass, but it is settled, not an open question.",
853
+ "> - Box colour = the top-level group it sits in; a box in no group is grey. With one top-level group, that group is grey and each box has its own colour.",
854
+ "> - Arrows are grey; a thicker arrow carries more links.",
855
+ "> - A flagged box counts its open and budgeted findings; the Register table names them.",
856
+ "> - A part that calls nothing in the chart and that at least a quarter of the other boxes call (four at least) has its arrows left out and counts its callers.",
857
+ "> - Drift = thick dashed red border + a faint red box for all four. No ranking: each scan proves a shape, never an intent.",
858
+ "> - `budgeted` = solid amber border + a faint amber box. Still drawn, because a declared bypass is still a bypass, but it is settled, not an open question.",
782
859
  "> - Which status is which: `split` fine dash · `bypassed` long dash · `dead` even dash · `gap` dotted · `budgeted` no dash.",
783
- "> - A fetched URL is a STRING, never an edge, because `assert-routes-reachable.mjs` is the only check that sees it.",
784
- f"> - Table rescanned every run, never stale. Diagrams from `graph.json` @ `{GRAPH_COMMIT[:9]}`; when that differs from HEAD ⇒ run `pnpm graph:update` first.",
785
- "> - Detail-level module graph → `pnpm graph`. This doc is the altitude above that: capabilities, not files.",
860
+ "> - A fetched URL is a STRING, never an edge, because the reachability scan (§ Unreachable API calls) is the only check that sees it.",
861
+ "> - Table rescanned every run, never stale.",
862
+ "> - Detail-level module graph → `pnpm bkit:graph`. This doc is the altitude above that: capabilities, not files.",
786
863
  "",
787
864
  "## Status Vocabulary",
788
865
  "",
789
- "The first four are warnings, not verdicts, and they share one amber in the diagrams. Any",
866
+ "The first four are warnings, not verdicts, and they share one red in the diagrams. Any",
790
867
  "of them can turn out to be deliberate, because the scans prove a shape, never an intent.",
791
868
  "",
792
869
  "`budgeted` is what one of those four becomes once somebody has decided. The rule declares",
793
- "the exact number of non-owner sites allowed per scope prefix, its `note` says why that",
794
- "number is not zero, and `tooling/eslint/tests/owned-query-shape-guard.test.ts` reds CI the",
795
- "moment the count moves in either direction — too many (a copy appeared) or too few (the",
796
- "budget is stale). That guard is why the status can be quieter without being a place to",
797
- "hide work, and it is the half the register itself cannot do: `graphify` is a per-developer",
798
- "install, absent in CI, so nothing here can turn a build red.",
799
- "",
800
- "It still gets a box in the diagrams, drawn solid and blue rather than dashed and amber. A",
870
+ "the exact number of non-owner sites allowed per scope prefix, and its `note` says why that",
871
+ "number is not zero. The moment the count moves in either direction — too many (a copy",
872
+ "appeared) or too few (the budget is stale) — the row leaves `budgeted`, its Budget cell",
873
+ "reads `over` or `stale`, and `pnpm bkit:graph:check` fails until the register is refreshed.",
874
+ "That is why the status can be quieter without being a place to hide work.",
875
+ "",
876
+ "It still gets a box in the diagrams, drawn solid and amber rather than dashed and red. A",
801
877
  "budgeted bypass is still a bypass; the different drawing stops the picture asking the",
802
878
  "same question of it every sweep. Drawn identically, an unbounded marker (18 of 19) and a",
803
879
  "marker that is exactly at its declared count — whose note says the copies are probes and",
@@ -839,7 +915,7 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
839
915
  "this block is read back first and re-emitted verbatim. Rename a node, hide a node or an",
840
916
  "edge, pin a note, or force nodes into a named group. A malformed block aborts the run",
841
917
  "rather than being silently dropped. Every `hide_nodes` entry needs a one-line reason in",
842
- "`hide_nodes_why`; `tooling/eslint/tests/hide-nodes-registry.test.ts` fails CI otherwise.",
918
+ "`hide_nodes_why`.",
843
919
  "",
844
920
  OV_START,
845
921
  "",
@@ -853,12 +929,7 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
853
929
  "",
854
930
  ROUTES_PROSE,
855
931
  "",
856
- VIEW_ONLINE,
857
- "",
858
- "```mermaid",
859
- ROUTES_MMD,
860
- "```",
861
- "",
932
+ ] + ([VIEW_ONLINE, "", "```mermaid", ROUTES_MMD, "```", ""] if ROUTES_MMD else []) + [
862
933
  "## Architecture — packages",
863
934
  "",
864
935
  "Grouped by the folder tree, not by a clustering algorithm. Edge labels are the number of",
@@ -872,7 +943,7 @@ def as_capabilities_doc(out, min_weight, overlay, rows, rules_path, surface, ov_
872
943
  "",
873
944
  "## Architecture — modules",
874
945
  "",
875
- f"The same graph one level down: `apps/web` is a box, its subfolders are the nodes inside it.",
946
+ "The same graph one level down: each package is a box, its subfolders are the nodes inside it.",
876
947
  f"Cross-group edges lighter than {min_weight} are dropped — see `MMD_MIN_WEIGHT` in",
877
948
  "`scripts/graphify/bkit-graphify.sh`.",
878
949
  "",