@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
@@ -1,128 +1,166 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
-
3
1
  <!-- bkit:start -->
4
2
 
5
3
  {{BKIT_MANAGED_MARKER}}
6
4
 
5
+ <!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. -->
6
+
7
7
  # Architecture Review
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Judgment on codebase shape — package graph, intended layers, server, and client boundary, and coupling the import graph cannot see.
10
+ > **Purpose:** A judgment on the codebase's shape: the package graph, the intended layers, the server and client boundary, and the coupling the import graph cannot see.
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - A code graph confirms presence; a missing edge proves nothing. Corroborate every load-bearing claim with a language server or text search before it is a finding.
15
- > - Build the graph locally and code-only; NEVER send the corpus or credentials to a model backend.
14
+ > - A code graph confirms presence. A missing edge proves nothing.
15
+ > - Corroborate every load-bearing claim with a language server or text search before it becomes a finding.
16
+ > - Build the graph locally, from code only.
17
+ > - NEVER send the corpus or credentials to a model backend.
16
18
 
17
19
  ## Universal Instructions
18
20
 
19
21
  ### Context & Goals
20
22
 
21
- File reading cannot answer acyclic package graph, hub modules, or copied types. Code graph + language server fail differently: graph edges may be false; omitted edges prove nothing. Target failure: **shape enforced in a diagram or clean graph but not in source** — type-only cycle treated as runtime, manifest edge as package dependency, privileged module reachable from client bundle.
23
+ Reading files cannot show whether the package graph is acyclic, which modules are hubs, or where types were copied. A code graph and a language server fail in different ways: graph edges can be false, and edges the graph omits prove nothing. The failure this audit targets is a shape enforced in a diagram or a clean graph, but not in source. Examples: a type-only cycle treated as a runtime cycle, a manifest edge treated as a package dependency, or a privileged module reachable from the client bundle.
22
24
 
23
- **Applies when:** more than one package, or a written layer model. None → one `N/A` row with evidence, never "clean".
25
+ **Applies when:** the repo has more than one package, or a written layer model. **If** neither holds → write one `N/A` row with its evidence, and never report the surface as "clean".
24
26
 
25
- **Cadence:** quarterly. Extra pass when a cycle adds a package, moves a module, or changes path aliases or project references. Production-checklist walk = part of quarterly pass.
27
+ **Cadence:** Run once a quarter. Run an extra pass when a cycle adds a package, moves a module, or changes path aliases or project references. The walk through the production checklists is part of the quarterly pass.
26
28
 
27
29
  **Anchor Standards:**
28
30
 
29
31
  - C4 model (System Context, Container, Component).
30
- - Architecture decision records (e.g. adr.github.io) and architectural fitness functions (e.g. _Building Evolutionary Architectures_).
31
- - Product quality model, nine characteristics (e.g. ISO/IEC 25010:2023).
32
- - Quality-attribute scenarios (e.g. ATAM utility tree).
33
- - Package metrics: afferent coupling (Ca), efferent coupling (Ce), instability, abstractness, Stable Dependencies Principle (e.g. Robert C. Martin).
34
- - Compiler-resolving dependency linter (e.g. dependency-cruiser, import-linter); record version.
35
- - Workspace boundary checker (e.g. `turbo boundaries`, Nx module boundaries); record version.
36
- - Layer-boundary linter (e.g. eslint-plugin-boundaries, ArchUnit).
37
- - Well-architected pillars as a lens (e.g. AWS Well-Architected, Azure Well-Architected).
38
- - Server and client component boundary, including a build-failing server-only guard (e.g. Next.js Server and Client Components, `server-only`).
39
- - Host production checklists (e.g. Vercel, Supabase, Fly).
32
+ - Architecture decision records (e.g., adr.github.io) and architectural fitness functions (e.g., _Building Evolutionary Architectures_).
33
+ - Product quality model, nine characteristics (e.g., ISO/IEC 25010:2023).
34
+ - Quality-attribute scenarios (e.g., ATAM utility tree).
35
+ - Package metrics: afferent coupling (Ca), efferent coupling (Ce), instability, abstractness, Stable Dependencies Principle (e.g., Robert C. Martin).
36
+ - Compiler-resolving dependency linter (e.g., dependency-cruiser, import-linter); record version.
37
+ - Workspace boundary checker (e.g., `turbo boundaries`, Nx module boundaries); record version.
38
+ - Layer-boundary linter (e.g., eslint-plugin-boundaries, ArchUnit).
39
+ - Well-architected pillars as a lens (e.g., AWS Well-Architected, Azure Well-Architected).
40
+ - Server and client component boundary, including a build-failing server-only guard (e.g., Next.js Server and Client Components, `server-only`).
41
+ - Host production checklists (e.g., Vercel, Supabase, Fly).
40
42
 
41
43
  ### Scope
42
44
 
43
- - Package dependency graph: cycles, back-edges, coupling metrics, fan-in, fan-out, duplicate symbols.
44
- - Conformance to a written layer matrix, public entry points, and deep imports.
45
- - Server and client boundary, and privileged modules.
46
- - Coupling with no import edge: events, data ownership, change coupling.
47
- - Shape against recorded decisions, context, and container views, and quality-attribute scenarios.
48
- - Production-checklist gaps, routed to the audit that owns each.
45
+ - Check the package dependency graph: cycles, back-edges, coupling metrics, fan-in, fan-out and duplicate symbols.
46
+ - Check conformance to a written layer matrix, public entry points and deep imports.
47
+ - Check the server and client boundary, and the privileged modules.
48
+ - Find the coupling that has no import edge: events, data ownership and change coupling.
49
+ - Compare the shape with the recorded decisions, the context and container views, and the quality-attribute scenarios.
50
+ - Find production-checklist gaps, and route each one to the audit that owns it.
49
51
 
50
52
  ### Out of Scope
51
53
 
52
54
  <!-- prettier-ignore -->
53
55
  | Excluded item | Why | Where it belongs |
54
56
  | --- | --- | --- |
55
- | Whether a symbol is reachable | Reachability, not shape | `bkit-audit-dead-code` |
56
- | Confirmed same-name copies, once named | Duplication sweep | `bkit-audit-duplication` |
57
- | Auth holes and secret exposure in depth | Security sweep | `bkit-audit-security` |
58
- | A table written from several places, in depth | Database sweep | `bkit-audit-database` |
59
- | Cold-start time and request latency | Hot paths | `bkit-audit-app-performance` |
60
- | Job retries and idempotency in depth | Reliability sweep | `bkit-audit-reliability` |
61
- | Changing packages, layers, or the graph | Audit reports only | Plan from this report |
57
+ | Whether a symbol is reachable | It is about reachability, not shape | `bkit-audit-dead-code` |
58
+ | Confirmed same-name copies, once named | The duplication audit owns them | `bkit-audit-duplication` |
59
+ | Auth holes and secret exposure in depth | The security audit owns them | `bkit-audit-security` |
60
+ | A table written from several places, in depth | The database audit owns it | `bkit-audit-database` |
61
+ | Cold-start time and request latency | The performance audit owns hot paths | `bkit-audit-app-performance` |
62
+ | Job retries and idempotency in depth | The reliability audit owns them | `bkit-audit-reliability` |
63
+ | Changing packages, layers, or the graph | The audit only reports | A plan made from this report |
62
64
 
63
65
  ### Pre-Flight / Dependencies
64
66
 
65
67
  #### Core
66
68
 
67
- - [ ] **Permissions:** blocked calls recorded
68
- - [ ] **Code Graph:** Steps 2-4 — local code-only extractor, e.g. graphify via a wrapper that strips API keys. Fallback: dependency linter and text search; graph counts `Not Checked`.
69
- - [ ] **Dependency Linter:** Steps 5-6 — resolves through the compiler, e.g. dependency-cruiser, import-linter. Fallback: read import statements; say so per claim.
70
- - [ ] **Git History:** Steps 1, 9, 13 — change coupling and the diff since the previous report. Fallback: change coupling `Not Checked`.
71
- - [ ] **Web:** Step 12 — fetch anchor standards. Fallback: versions recorded as unread.
69
+ - [ ] **Permissions:** every blocked call is recorded.
70
+ - [ ] **Code Graph:** Steps 2-4 — a local, code-only extractor (e.g., graphify through a wrapper that strips API keys). Fallback: use the dependency linter and text search, and mark the graph counts `Not Checked`.
71
+ - [ ] **Dependency Linter:** Steps 5-6 — a linter that resolves through the compiler (e.g., dependency-cruiser, import-linter). Fallback: read the import statements, and say so for each claim.
72
+ - [ ] **Git History:** Steps 1, 9, 13 — change coupling and the diff since the previous report. Fallback: mark change coupling `Not Checked`.
73
+ - [ ] **Web:** Step 12 — fetch the anchor standards. Fallback: record the versions as unread.
72
74
 
73
75
  #### Conditional
74
76
 
75
- - [ ] **Language Server:** Typed language → Steps 7, 11 — references, e.g. Serena, `tsserver`, gopls. Fallback: text search; name it per claim. Repeat any surprising low count.
76
- - [ ] **Workspace Boundaries:** Monorepo task runner with a boundaries command → Step 5 — e.g. `turbo boundaries`, Nx. Fallback: layer matrix by hand.
77
- - [ ] **Host Checklists:** Managed host → Step 10 — production checklist, e.g. vendor docs, dashboard. Fallback: docs only; live settings `Not Checked`.
77
+ - [ ] **Language Server:** **If** the language is typed → Steps 7, 11 — references (e.g., Serena, `tsserver`, gopls). Fallback: text search, and name the tool for each claim. Repeat any surprisingly low count.
78
+ - [ ] **Workspace Boundaries:** **If** a monorepo task runner has a boundaries command → Step 5 — its boundary check (e.g., `turbo boundaries`, Nx). Fallback: check the layer matrix by hand.
79
+ - [ ] **Host Checklists:** **If** the app runs on a managed host → Step 10 — the production checklist (e.g., vendor docs, dashboard). Fallback: use the docs only, and mark live settings `Not Checked`.
78
80
 
79
81
  ### 🔒 Gate 1: Prerequisites Check
80
82
 
81
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
82
- - [ ] **Gate 1 — Verified:** All Core items checked. All applicable Conditional items checked.
83
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
84
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
83
85
 
84
86
  ### Probe Steps
85
87
 
86
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
87
- - [ ] **Step 2 — Graph:** Build locally, code-only, credentials stripped, via project wrapper (never bare extract). Record tool version, `built_at_commit`, node count, edge count, cross-package edge count. Graph commit != reviewed `HEAD` → findings invalid; rebuild. Derived output untracked; clean rebuild deletes only that output. After path-alias change → clean rebuild — force flag that does not clear module-resolution cache keeps stale unresolved edges. Syntax-only graph (e.g. tree-sitter) does not consult language server: path aliases and manifest names are separate inputs; losing either drops edges with no error. Keep manifests in corpus so workspace imports resolve → drop manifest-to-manifest edges before matrix. Skip whole-repo render; use package and module rollups. Dated extractor backups (if the tool keeps them) accumulate; clean rebuild clears them. **Done when:** commit, counts, tool list in `Graph`, or absent tool in `Not Checked`.
88
- - [ ] **Step 3 — Report:** Read extractor report. Every finding-like section checked against source before it counts. Import cycles: type-only edges erased at compile time != runtime cycle — check every edge. Cross-package edges: do not dismiss as impossible once aliases resolve; do dismiss manifest-to-manifest. God nodes: high degree = look, not defect. Community dump with numbered labels and near-zero cohesion → clustering found no structure — skip. **Done when:** each section dispositioned in `Graph`.
89
- - [ ] **Step 4 — Structure:** Query built graph, then graph file. Filters first: code only (source extensions; drop manifests and config); tests separated with repo's one test-path rule — do not type a shorter list. Test files cross boundaries; counting them as product hides shape. Views with/without test code can both be correct — record which. Dependency-shaped edges only (import, re-export, dynamic import). Nesting != dependency. Name-matching edges (e.g. `indirect_call`) can invent links between unrelated files sharing a function name — exclude. Blast-radius under-reports: missed callers in anonymous callbacks, calls in module-level initialisers. Blast-radius set = starting set, never complete. Checks (each a series): (1) package dependency matrix, code-only, back-edges (library→app, leaf→consumer) — should be DAG; per workspace Ca, Ce, instability I = Ce/(Ca+Ce), abstractness (share of exported types and interfaces); flag package depending on less stable one. (2) File-level cycles (SCC over import edges); component >1 file = candidate → type-only check. (3) Fan-in: files everything imports. (4) Fan-out: most imports — barrels and god modules. (5) Duplicate symbol names: group callables by label across distinct non-test source files; >=3 definitions = prompt. False positives: per-directory handlers, platform splits (e.g. `.native` / `.web`). Signal = type/component duplicated where canonical exists. Same grouping over test code alone. Copies without shared name → text search. Confirmed hits → `bkit-audit-duplication`. **Done when:** matrix, cycles, rankings, duplicates in `Structure`.
90
- - [ ] **Step 5 — Layers:** Back-edge hunt with no written model lets legal wrong dependency pass. Carry allowed package-layer matrix from previous report. No matrix → draft from recorded architecture decisions, mark proposed. Diff code-only matrix; every disallowed edge = candidate. Encode matrix as forbidden rules for compiler-resolving linter, config under repo-root `tmp/` only, type-only edges excluded; check extractor import cycles. Clean rule = fitness function to propose under `Process Improvements`. Run workspace boundary checker; record version; clean result = candidate for package-DAG gate, not proof. Native/restricted app: every package it imports transitively has no server-only or host-only module (e.g. `fs`, server-only import, service-role client) — forbidden rule so bundle break or client secret caught by structure. Public entry points: every workspace package declares them where the ecosystem supports it (e.g. Node `exports` map, Go `internal/`); deep imports past them = candidates. Name enforcing rule each would need. **Done when:** every disallowed edge in `Layers`, with rule that would forbid it.
91
- - [ ] **Step 6 — Boundary:** List modules importing privileged data client, service-role secret, or non-public secret; confirm each imports guard that turns client import into build error (e.g. `server-only`), where the stack has one; none → reach check alone, say so. Confirm no client-entry module reaches one transitively — client entry pulls imports into client bundle. Text search → list; linter or blast-radius → reach; `Cross-Check` confirms. **Done when:** every privileged module in `Boundary` with guard, reach, verdict.
92
- - [ ] **Step 7 — Cross-Check:** Language server answers from disk — no mid-edit staleness; resolves what tree-sitter graph cannot. Graph misses anonymous-callback callers; language server misses what project graph cannot reach. Confirm fan-in and blast-radius with references before write-up. Pace reference queries — back-to-back calls can return partial count indistinguishable from real; repeat surprising low count after pause. Empty = inconclusive. Blind spots neither tool sees: middleware guards, config-referenced files, runtime-registered handlers, mock-factory keys, packages outside language-server project graph. Text search for non-source files, string literals, unknown names. **Done when:** every load-bearing claim in `Cross-Check` names both tools, or the blind spot.
93
- - [ ] **Step 8 — References:** Pick 2-3 well-regarded OSS repos on same stack; compare shape: package boundaries, shared code location, config/env split, client code sharing. Record repo name, commit/tag, comparison. Difference = soft signal, not finding alone: report only with problem it would solve here, low-confidence, never rank above graph finding. **Done when:** repos, revisions, comparisons in `References`, or `none`.
94
- - [ ] **Step 9 — Coupling:** Three couplings carry no import edge. Events/runtime wiring: every event sent vs handler registered, plus schedules, DB triggers, outbound DB HTTP, edge functions, inbound webhooks. Flag producer without consumer, consumer without producer, two packages coupled only via event. Data ownership: table and routine call sites per package and app. Flag table written from >1 module/app; table written via privileged client from >1 place. Change coupling: file pairs in commits since previous report, different packages or clients, co-change in >half commits with no import edge. Confirmed pairs → `bkit-audit-duplication`. **Done when:** events, tables, pairs in `Coupling`.
95
- - [ ] **Step 10 — Judgment:** Four criteria. Decisions vs code: every architecture-scoped decision still honoured + what enforces it (lint, dependency rule, test). Unenforced decision = finding. Shape with no decision = undocumented architecture. Context/containers: C4 System Context and Container as Mermaid, from previous report corrected. Every external service in code and env schema appears; nothing retired on diagram. Capability register = package-level view only. Quality attributes: pick product-quality characteristics that matter; one scenario each (stimulus, environment, response, response measure); carry forward; judge shape meets each. Production checklists (quarterly): walk host checklists → route each gap to owning audit. **Done when:** decisions, views, scenarios, routed gaps in `Judgment`.
96
- - [ ] **Step 11 — Verify:** No finding without opening file. Confirm: cycle is runtime not type-only; cross-package edge is real source import not shared manifest name; privileged call site unguarded not middleware-blind; duplicated name is real duplication not platform split/local handler. Cite `file:line`. Destinations (name; do not file): confirmed copies and change-coupled pairs → `bkit-audit-duplication`; reachability or event without producer/consumer → `bkit-audit-dead-code`; server-only from client or secret in native bundle → `bkit-audit-security`; table multi-writer → `bkit-audit-database`; production-checklist gap → owning audit (`bkit-audit-security`, `bkit-audit-app-performance`, `bkit-audit-database`, `bkit-audit-reliability`); else → slug this report names. **Done when:** every surviving candidate has `file:line`, tool, destination.
97
- - [ ] **Step 12 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per anchor standard and product-quality characteristic → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
98
- - [ ] **Step 13 — Anything Else:** (a) Everything since previous report's commit touching shape (workspaces add/remove, manifest deps between workspaces, export maps, path aliases and project references, moved modules, new jobs/events, migrations adding tables, new external services in env schema) → one-line verdict each. (b) Bounded ~30 min: what senior architect flags that no step asks; read since previous run (incidents, `bkit-audit-logs`, new `docs/failures.jsonl`, vendor status) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
88
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
89
+ - [ ] **Step 2 — Graph:** Build the graph locally, from code only, with credentials stripped, through the project wrapper (never a bare extract). Record the tool version, `built_at_commit`, the node count, the edge count and the cross-package edge count. **If** the graph commit != the reviewed `HEAD` → the findings are invalid, so rebuild. Keep the derived output untracked. A clean rebuild deletes only that output. **If** path aliases changed → do a clean rebuild, because a force flag that does not clear the module-resolution cache keeps stale unresolved edges. A syntax-only graph (e.g., tree-sitter) does not consult the language server. Path aliases and manifest names are separate inputs, and losing either one drops edges with no error. Keep the manifests in the corpus so workspace imports resolve, then drop manifest-to-manifest edges before building the matrix. Skip the whole-repo render, and use package and module rollups. **If** the tool keeps dated extractor backups → they accumulate, and a clean rebuild clears them. **Done when:** `Graph` holds the commit, the counts and the tool list, or `Not Checked` names the absent tool.
90
+ - [ ] **Step 3 — Report:** Read the extractor's report. Check every finding-like section against source before it counts. Import cycles: a type-only edge is erased at compile time, so it is not a runtime cycle. Check every edge. Cross-package edges: once aliases resolve, do not dismiss them as impossible, but do dismiss manifest-to-manifest edges. God nodes: a high degree is a reason to look, not a defect. **If** a community dump has numbered labels and near-zero cohesion → the clustering found no structure, so skip it. **Done when:** `Graph` gives each section a disposition.
91
+ - [ ] **Step 4 — Structure:** Query the built graph first, then the graph file.
92
+ - Apply the filters first: code only (source extensions; drop manifests and config), with tests separated by the repo's one test-path rule. Do not type a shorter list.
93
+ - Test files cross boundaries, so counting them as product hides the shape. Views with and without test code can both be correct, so record which one you use.
94
+ - Keep dependency-shaped edges only (import, re-export, dynamic import). Nesting is not dependency.
95
+ - Exclude name-matching edges (e.g., `indirect_call`), because they can invent links between unrelated files that share a function name.
96
+ - Blast radius under-reports: it misses callers in anonymous callbacks and calls in module-level initialisers. A blast-radius set is a starting set, never a complete one.
97
+ - Run these checks, each as a series:
98
+ - (1) Package dependencies:
99
+ - Build the package dependency matrix, code only, and find the back-edges (library→app, leaf→consumer). It should be a DAG.
100
+ - For each workspace, compute Ca, Ce, instability I = Ce/(Ca+Ce) and abstractness (the share of exported types and interfaces).
101
+ - Flag a package that depends on a less stable one.
102
+ - (2) Find file-level cycles (SCC over import edges). A component of more than 1 file is a candidate for the type-only check.
103
+ - (3) Fan-in: rank the files everything imports.
104
+ - (4) Fan-out: rank the files with the most imports, which are barrels and god modules.
105
+ - (5) Duplicate symbol names:
106
+ - Group callables by label across distinct non-test source files. A name with >=3 definitions is a prompt to look. Per-directory handlers and platform splits (e.g., `.native` / `.web`) are false positives. The signal is a type or component duplicated where a canonical one exists.
107
+ - Run the same grouping over test code alone.
108
+ - Find copies without a shared name with text search.
109
+ - Confirmed hits go to `bkit-audit-duplication`.
110
+
111
+ **Done when:** `Structure` holds the matrix, the cycles, the rankings and the duplicates.
112
+
113
+ - [ ] **Step 5 — Layers:** A back-edge hunt with no written model lets a legal but wrong dependency pass.
114
+ - Carry the allowed package-layer matrix forward from the previous report.
115
+ - **If** there is no matrix → draft one from the recorded architecture decisions, and mark it proposed.
116
+ - Diff the code-only matrix against it. Every disallowed edge is a candidate.
117
+ - Encode the matrix as forbidden rules for the compiler-resolving linter, with its config under the repo-root `tmp/` only and type-only edges excluded.
118
+ - Check the extractor's import cycles. A rule that runs clean is a fitness function to propose under `Process Improvements`.
119
+ - Run the workspace boundary checker, and record its version. A clean result is a candidate for a package-DAG gate, not proof.
120
+ - **If** there is a native or restricted app →
121
+ - Check that no package it imports transitively has a server-only or host-only module (e.g., `fs`, a server-only import, a service-role client).
122
+ - Write a forbidden rule for it, so a bundle break or a client secret is caught by structure.
123
+ - Public entry points:
124
+ - Check that every workspace package declares them where the ecosystem supports it (e.g., the Node `exports` map, Go `internal/`). Deep imports past them are candidates.
125
+ - Name the enforcing rule each one would need.
126
+
127
+ **Done when:** `Layers` holds every disallowed edge, with the rule that would forbid it.
128
+
129
+ - [ ] **Step 6 — Boundary:** List the modules that import a privileged data client, a service-role secret or a non-public secret. Confirm that each one imports a guard that turns a client import into a build error (e.g., `server-only`), where the stack has one. **If** the stack has none → the reach check stands alone, so say so. Confirm that no client-entry module reaches one transitively, because a client entry pulls its imports into the client bundle. Compute that reach over runtime edges only: a type-only import is erased at compile time. Use text search for the list, the linter or blast radius for reach, and `Cross-Check` to confirm. **Done when:** `Boundary` holds every privileged module, with its guard, reach and verdict.
130
+ - [ ] **Step 7 — Cross-Check:** The language server answers from disk, so it shows no mid-edit staleness, and it resolves what the tree-sitter graph cannot. The graph misses callers in anonymous callbacks. The language server misses what the project graph cannot reach. Confirm fan-in and blast radius with references before the write-up. Pace the reference queries, because back-to-back calls can return a partial count that looks the same as a real one. **If** a count is surprisingly low → repeat it after a pause. An empty result is inconclusive. Neither tool sees these blind spots: middleware guards, config-referenced files, runtime-registered handlers, mock-factory keys, packages outside the language server's project graph, and dynamic imports whose specifier is not a literal (e.g., a variable or cast string, or a bundler ignore comment). Use text search for non-source files, string literals and unknown names. **Done when:** every load-bearing claim in `Cross-Check` names both tools, or the blind spot.
131
+ - [ ] **Step 8 — References:** Pick 2-3 well-regarded OSS repos on the same stack, and compare their shape: package boundaries, where shared code lives, the config and env split, and how client code is shared. Record the repo name, the commit or tag, and the comparison. A difference is a soft signal, not a finding on its own. Report it only with the problem it would solve here, mark it low-confidence, and never rank it above a graph finding. **Done when:** `References` holds the repos, revisions and comparisons, or `none`.
132
+ - [ ] **Step 9 — Coupling:** Three kinds of coupling carry no import edge. Events and runtime wiring: compare every event sent with the handlers registered, plus schedules, DB triggers, outbound DB HTTP, edge functions and inbound webhooks. Flag a producer without a consumer, a consumer without a producer, and two packages coupled only through an event. Data ownership: list the table and routine call sites per package, app, and script or CLI directory. Flag a table written from more than 1 module or app, and a table written through a privileged client from more than 1 place. Change coupling: find the file pairs, in commits since the previous report, that sit in different packages or clients and change together in more than half of the commits, with no import edge. Confirmed pairs go to `bkit-audit-duplication`. **Done when:** `Coupling` holds the events, tables and pairs.
133
+ - [ ] **Step 10 — Judgment:** Judge the shape on four criteria. Decisions against code: check that every architecture-scoped decision is still honoured, and name what enforces it (a lint, a dependency rule, a test). A decision nothing enforces is a finding. Shape with no decision behind it is undocumented architecture. Context and containers: draw the C4 System Context and Container views in Mermaid, from the previous report's views, corrected. Every external service in the code and the env schema appears, and nothing retired stays on the diagram. The capability register is a package-level view only. Annotate the Container view with each compute and data region, read live. A request that crosses regions on every call is a finding. Quality attributes: pick the product-quality characteristics that matter, and write one scenario for each (stimulus, environment, response, response measure). Carry them forward, and judge whether the shape meets each one. Production checklists (quarterly): walk the host checklists, and route each gap to the audit that owns it. **Done when:** `Judgment` holds the decisions, the views, the scenarios and the routed gaps.
134
+ - [ ] **Step 11 — Verify:** Give no finding without opening the file. Confirm that a cycle is runtime, not type-only; that a cross-package edge is a real source import, not a shared manifest name; that a privileged call site is unguarded, not guarded by middleware the tools cannot see; and that a duplicated name is real duplication, not a platform split or a local handler. Cite `file:line`. Destinations (name; do not file): confirmed copies and change-coupled pairs go to `bkit-audit-duplication`; reachability, or an event without a producer or consumer, goes to `bkit-audit-dead-code`; a server-only module reached from the client, or a secret in the native bundle, goes to `bkit-audit-security`; a table with several writers goes to `bkit-audit-database`; a production-checklist gap goes to the audit that owns it (`bkit-audit-security`, `bkit-audit-app-performance`, `bkit-audit-database`, `bkit-audit-reliability`); anything else goes to the slug this report names. **Done when:** every surviving candidate has its `file:line`, tool and destination.
135
+ - [ ] **Step 12 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. Give `Standards Coverage` one row per anchor standard and one per product-quality characteristic, each marked checked (naming the step), not applicable (saying why) or finding. Mark each recommended practice the project does not apply as adopt (with a proposed step), reject (saying why) or not applicable. **Done when:** no row is empty.
136
+ - [ ] **Step 13 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches shape: workspaces added or removed, manifest dependencies between workspaces, export maps, path aliases and project references, moved modules, new jobs and events, migrations that add tables, and new external services in the env schema. (b) Spend a bounded pass of about 30 minutes on what a senior architect would flag that no step asks about. Read what happened since the previous run (incidents, `bkit-audit-logs`, new `docs/failures.jsonl` rows, vendor status), and ask what no step would catch. **Done when:** `Beyond the Steps` holds both passes, or says `none`. **If** one class of issue is seen on 2 runs → propose a step for it in `Process Improvements`.
99
137
 
100
138
  ### 🔒 Gate 2: Probes Check
101
139
 
102
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
103
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
140
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
141
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
104
142
  - [ ] **Presence only:** no finding rests on a missing edge alone.
105
- - [ ] **Graph commit:** graph was built from the reviewed commit, or the mismatch is itself a finding.
106
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
143
+ - [ ] **Graph commit:** the graph was built from the reviewed commit, or the mismatch is itself a finding.
144
+ - [ ] **Gate 2 — Verified:** every item above holds.
107
145
 
108
146
  ## Findings
109
147
 
110
148
  <!-- prettier-ignore -->
111
149
  | Severity | Use |
112
150
  | --- | --- |
113
- | `CRITICAL` | Privileged or secret-bearing module reachable from a client bundle or a native app |
114
- | `HIGH` | Runtime cycle or back-edge across the intended layers; privileged call site unguarded by anything either tool can see |
115
- | `MEDIUM` | Architecture decision nothing enforces; confirmed duplicate where a canonical symbol exists; event with no producer or no consumer |
116
- | `LOW` | Low-confidence shape difference versus a reference repo; diagram drift that changes no boundary |
151
+ | `CRITICAL` | A privileged or secret-bearing module is reachable from a client bundle or a native app |
152
+ | `HIGH` | A runtime cycle or a back-edge across the intended layers. A privileged call site that nothing either tool can see guards |
153
+ | `MEDIUM` | An architecture decision that nothing enforces. A confirmed duplicate where a canonical symbol exists. An event with no producer or no consumer |
154
+ | `LOW` | A low-confidence shape difference from a reference repo. Diagram drift that changes no boundary |
117
155
 
118
- Within a severity: boundary / secrets first.
156
+ Within a severity, list boundary and secrets findings first.
119
157
 
120
158
  <!-- prettier-ignore -->
121
159
  | ID | Severity | Location | Evidence | Expected |
122
160
  | --- | --- | --- | --- | --- |
123
161
  | PENDING | PENDING | PENDING | PENDING | PENDING |
124
162
 
125
- Empty and clean → one row `None`.
163
+ **If** the run finds nothing → write one row: `None`.
126
164
 
127
165
  ## Report
128
166
 
@@ -195,13 +233,17 @@ PENDING
195
233
 
196
234
  ### 🔒 Gate 3: Report Check
197
235
 
198
- - [ ] **No placeholders:** no `PENDING` left
199
- - [ ] **Summary:** names count per severity, tools available, and the graph commit.
200
- - [ ] **Series:** node, edge, and cross-package counts, and the coupling table, beside previous report's numbers, or marked baseline.
201
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
202
- - [ ] **Process Improvements:** `Universal` and `Project` filled
203
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
204
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
236
+ - [ ] **No placeholders:** no `PENDING` is left.
237
+ - [ ] **Summary:** `Summary` gives the count per severity.
238
+ - [ ] **Tools:** `Summary` names the tools available.
239
+ - [ ] **Graph commit named:** `Summary` names the graph commit.
240
+ - [ ] **Series:** the report shows node, edge, and cross-package counts, and the coupling table, beside the previous report's numbers, or marks the run as baseline.
241
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
242
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
243
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
244
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
245
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
246
+ - [ ] **Gate 3 — Verified:** every item above holds.
205
247
 
206
248
  <!-- bkit:end -->
207
249
 
@@ -1,9 +1,9 @@
1
- <!-- Note: Reports live at `docs/audits/{YYYYMM}/{slug}.md`. `{YYYYMM}` = UTC month of this run. `{slug}` = template basename without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md` (`{TIMESTAMP}` = `date -u +%Y%m%dT%H%M%SZ`). Never overwrite. The report is stamped with a `bkit:anchor` block recording the audited commit (`baseSha`) and branch (`baseRef`); never hand-author or edit it. `@bkit-audit-generate` fills this template. -->
2
-
3
1
  <!-- bkit:start -->
4
2
 
5
3
  {{BKIT_MANAGED_MARKER}}
6
4
 
5
+ <!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. -->
6
+
7
7
  # CI Performance Audit
8
8
 
9
9
  > [!CAUTION]
@@ -11,84 +11,84 @@
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - never dispatch, rerun, or cancel a workflow. A runner-class experiment is named, not run.
15
- > - Billable rates are read this run from the billing pages. never copy a previous report's prices.
14
+ > - Never dispatch, rerun or cancel a workflow.
15
+ > - Name a runner-class experiment, but do not run it.
16
+ > - Read the billable rates from the billing pages during this run.
17
+ > - Never copy a previous report's prices.
16
18
 
17
19
  ## Universal Instructions
18
20
 
19
21
  ### Context & Goals
20
22
 
21
- CI time gets re-argued from impressions. Two mistakes recur:
22
-
23
- - Lane duration alone != wall-clock savings — only finish time relative to the run shows whether trimming it helps.
24
- - Cost and latency are different purchases: state which a change buys, every time.
25
- - Target failure: effort on a lane that does not hold the run open, or a latency change reported as money saved.
23
+ CI time gets re-argued from impressions, and two mistakes recur. First, a lane's duration alone does not equal wall-clock savings: only its finish time relative to the run shows whether trimming it helps. Second, cost and latency are different purchases, so state which one a change buys, every time. The failure this audit targets is effort spent on a lane that does not hold the run open, or a latency change reported as money saved.
26
24
 
27
- **Applies when:** a CI workflow. None → one `N/A` row with evidence, never "clean".
25
+ **Applies when:** the repo has a CI workflow. **If** it has none → write one `N/A` row with its evidence, and never report the surface as "clean".
28
26
 
29
- **Cadence:** quarterly; extra pass when workflow topology changes (new lane, runner class, or cache).
27
+ **Cadence:** Run once a quarter. Run an extra pass when the workflow topology changes (a new lane, runner class or cache).
30
28
 
31
29
  **Anchor Standards:**
32
30
 
33
31
  - DORA software delivery performance: change lead time, deployment frequency, failed-deployment recovery time, change fail rate, and deployment rework rate.
34
- - Host CI metrics (e.g. GitHub Actions usage and performance: job run time, queue time, failure rate). Living docs; record the date read.
35
- - Task-runner remote cache and affected selection (e.g. Turborepo remote caching and `--affected`), at the version in the lockfile.
36
- - Package-manager store cache in CI (e.g. pnpm via `actions/setup-node` `cache: pnpm`), at the pinned setup version.
37
- - Browser-test sharding and report merge (e.g. Playwright sharding and `merge-reports`), at the version in the lockfile.
38
- - Concurrency groups and job timeouts (e.g. GitHub Actions `concurrency` and `timeout-minutes`).
39
- - Runner billing (e.g. GitHub-hosted and larger runners, a remote builder such as Depot, mobile-build credits such as EAS). Record the date read.
32
+ - Host CI metrics (e.g., GitHub Actions usage and performance: job run time, queue time, failure rate). Living docs; record the date read.
33
+ - Task-runner remote cache and affected selection (e.g., Turborepo remote caching and `--affected`), at the version in the lockfile.
34
+ - Package-manager store cache in CI (e.g., pnpm via `actions/setup-node` `cache: pnpm`), at the pinned setup version.
35
+ - Browser-test sharding and report merge (e.g., Playwright sharding and `merge-reports`), at the version in the lockfile.
36
+ - Concurrency groups and job timeouts (e.g., GitHub Actions `concurrency` and `timeout-minutes`).
37
+ - Runner billing (e.g., GitHub-hosted and larger runners, a remote builder such as Depot, mobile-build credits such as EAS). Record the date read.
40
38
  - bkit block of `docs/deployments.md` (bkit version from `.bkit/version`): § Run-level decision matrix; § One run per branch or pull request; § Parallel test lanes (one lane per tier); § turbo `//` over-triggers `web_affected` on docs-only diffs (turbo monorepos); § One CI run per dev commit (release PR mirrors the `dev` push run)
41
39
  - bkit block of `docs/testing.md` (bkit version from `.bkit/version`): § CI verbosity (`[verbose ci]`)
42
40
 
43
41
  ### Scope
44
42
 
45
- - Per-lane duration, queue, finish time, and whether the lane holds the run open.
46
- - Distributions (p50 and p90), not a single run, and job timeouts.
47
- - Change lead time push → green → deployed, split by segment.
48
- - Step timings, cache hit rate, shard balance, per-job setup cost, artifacts — on lanes that matter.
49
- - Every cache: hit or miss, restore time vs cold rebuild, usage vs eviction limit.
50
- - What a change actually runs: path filters and required checks.
51
- - Local gate, timed separately, cache forced off.
52
- - Re-runs, failures that passed later, duplicate runs — as minutes.
53
- - Billable minutes and cost per successful merge; latency or cost on every finding.
43
+ - Measure each lane's duration, queue time and finish time, and whether the lane holds the run open.
44
+ - Report distributions (p50 and p90), not a single run.
45
+ - Check the job timeouts.
46
+ - Measure change lead time from push → green → deployed, split by segment.
47
+ - On the lanes that matter, measure step timings, cache hit rate, shard balance, per-job setup cost and artifacts.
48
+ - Check every cache: hit or miss, restore time against a cold rebuild, and usage against the eviction limit.
49
+ - Check what a change actually runs: path filters and required checks.
50
+ - Time the local gate separately, with the cache forced off.
51
+ - Count re-runs, failures that passed later and duplicate runs, as minutes.
52
+ - Measure billable minutes and the cost per successful merge.
53
+ - State latency or cost on every finding.
54
54
 
55
55
  ### Out of Scope
56
56
 
57
57
  <!-- prettier-ignore -->
58
58
  | Excluded item | Why | Where it belongs |
59
59
  | --- | --- | --- |
60
- | Spend outside CI minutes | Whole bill | `bkit-audit-cost` |
61
- | Which checks should gate | Gate sweep | `bkit-audit-gates` |
62
- | Product request latency | Hot paths | `bkit-audit-app-performance` |
63
- | Why a test flakes, beyond minutes lost | Flake sweep | `bkit-audit-flakes` |
64
- | Changing workflows, runners, or caches | Audit reports only | Plan from this report |
60
+ | Spend outside CI minutes | The cost audit owns the whole bill | `bkit-audit-cost` |
61
+ | Which checks should gate | The gates audit owns it | `bkit-audit-gates` |
62
+ | Product request latency | The performance audit owns hot paths | `bkit-audit-app-performance` |
63
+ | Why a test flakes, beyond minutes lost | The flakes audit owns it | `bkit-audit-flakes` |
64
+ | Changing workflows, runners, or caches | The audit only reports | A plan made from this report |
65
65
 
66
66
  ### Pre-Flight / Dependencies
67
67
 
68
68
  #### Core
69
69
 
70
- - [ ] **Permissions:** blocked calls recorded
71
- - [ ] **CI API:** Steps 2-6, 10-11 — read-only run and job metadata, e.g. `gh run view`, `gh api`. Fallback: workflow files only; timings `Not Checked`.
72
- - [ ] **Workflow Files:** Steps 3, 7-10 — workflows, task graph, cache config readable. Fallback: none; those steps `Not Checked`.
73
- - [ ] **Web:** Step 12 — fetch anchor standards and current runner prices. Fallback: versions and prices unread. never reuse a previous report's prices.
70
+ - [ ] **Permissions:** every blocked call is recorded.
71
+ - [ ] **CI API:** Steps 2-6, 10-11 — read-only run and job metadata (e.g., `gh run view`, `gh api`). Fallback: use the workflow files only, and mark timings `Not Checked`.
72
+ - [ ] **Workflow Files:** Steps 3, 7-10 — readable workflows, task graph and cache config. Fallback: none. Mark those steps `Not Checked`.
73
+ - [ ] **Web:** Step 12 — fetch the anchor standards and the current runner prices. Fallback: record the versions and prices as unread. Never reuse a previous report's prices.
74
74
 
75
75
  #### Conditional
76
76
 
77
- - [ ] **Host Metrics:** Host publishes queue time → Step 3 — e.g. Actions performance page. Fallback: queue from timestamps only.
78
- - [ ] **Cache API:** Cache listing exists → Step 7 — e.g. `gh cache list`. Fallback: log lines only; eviction `Not Checked`.
79
- - [ ] **Remote Builders:** Job only waits on external builder → Step 6 — builder API or log, e.g. EAS GraphQL. Fallback: wrapper-job duration only; worker time `Not Checked`.
80
- - [ ] **Local Gate:** Pre-push or local CI command exists → Step 9. Fallback: skip with evidence.
77
+ - [ ] **Host Metrics:** **If** the host publishes queue time → Step 3 — the host's queue figures (e.g., the Actions performance page). Fallback: derive queue time from timestamps only.
78
+ - [ ] **Cache API:** **If** a cache listing exists → Step 7 — the cache list (e.g., `gh cache list`). Fallback: use log lines only, and mark eviction `Not Checked`.
79
+ - [ ] **Remote Builders:** **If** a job only waits on an external builder → Step 6 — the builder API or log (e.g., EAS GraphQL). Fallback: use the wrapper-job duration only, and mark worker time `Not Checked`.
80
+ - [ ] **Local Gate:** **If** a pre-push or local CI command exists → Step 9 — that command. Fallback: skip the step with evidence.
81
81
 
82
82
  ### 🔒 Gate 1: Prerequisites Check
83
83
 
84
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
85
- - [ ] **Gate 1 — Verified:** All Core items checked. All applicable Conditional items checked.
84
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
85
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
86
86
 
87
87
  ### Probe Steps
88
88
 
89
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
90
- - [ ] **Step 2 — Reference:** Name reference run ids, event type, date. Push to integration branch vs pull request = different pipelines (some lanes push-only); never compare as one number without saying so. Record green/red per run — red lanes exit early and under-report duration. Runner classes and external queues drift; date matters. **Done when:** `Reference` holds ids, event types, conclusions, date.
91
- - [ ] **Step 3 — Lanes:** Per job: conclusion, duration, start, column for holds-the-run-open (duration alone is not that column). Add queue time — duration start→completion hides runner wait. Queue = run created → job started; with `needs:` subtract upstream finish for runner wait; keep `needs:` wait for Step 5. Cross-check host average queue per job. e.g. GitHub Actions:
89
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
90
+ - [ ] **Step 2 — Reference:** Name the reference run ids, the event type and the date. A push to the integration branch and a pull request are different pipelines (some lanes run on push only), so never compare them as one number without saying so. Record green or red for each run, because red lanes exit early and under-report duration. Runner classes and external queues drift, so the date matters. **Done when:** `Reference` holds the ids, event types, conclusions and date.
91
+ - [ ] **Step 3 — Lanes:** For each job, record the conclusion, duration and start, and a column for whether it holds the run open (duration alone is not that column). Add queue time, because the duration from start to completion hides the runner wait. Queue time = run created → job started. **If** the job has `needs:` → subtract the upstream finish to get the runner wait, and keep the `needs:` wait for Step 5. Cross-check the host's average queue time per job. For example, on GitHub Actions:
92
92
 
93
93
  ```
94
94
  gh run view <id> --json jobs \
@@ -98,45 +98,45 @@ CI time gets re-argued from impressions. Two mistakes recur:
98
98
  --jq '.jobs[] | "\(.name)\t\(.created_at)\t\(.started_at)"'
99
99
  ```
100
100
 
101
- **Done when:** `Lanes` has duration, queue, finish, holding-the-run-open per job.
101
+ **Done when:** `Lanes` has the duration, queue, finish and holding-the-run-open column for each job.
102
102
 
103
- - [ ] **Step 4 — Distributions:** One run cannot separate regression from noise. Pull >=20 recent CI workflow runs per event type; keep green and red apart. Report p50 and p90 for total wall clock and critical-path lane finish, per event type. Say how typical Step 2 runs are. Every job timeout ~1.5x its p99 (in this sample size, slowest run). No timeout → host default (e.g. GitHub Actions 360 minutes) and bills all of it. e.g. `gh api "repos/{owner}/{repo}/actions/workflows/<workflow>/runs?event=push&branch=<branch>&per_page=30"`. **Done when:** p50 and p90 in `Distributions`; each job within timeout rule or finding.
104
- - [ ] **Step 5 — Lead Time:** Lane finish times = one segment. Report DORA change lead time for push to integration branch: push → all lanes green → deployed. Split queue (Step 3), critical-path execution, `needs:` waits, re-run time (Step 10). Name dominating segment — that is the one worth buying down. **Done when:** `Lead Time` names split and dominating segment.
105
- - [ ] **Step 6 — Timings:** Inside lanes that hold the run open or that a proposal would trim: step timings; task-runner cache hit rate (zero cached on a lane that should cache = finding); test counts executed (wall clock per test compares runs better than wall clock alone); remote-builder jobs — record builder queue and build time separately from wrapper; shard balance — slowest/fastest >~1.3x means one shard holds the lane; fixed cost per job (checkout, toolchain setup, install) x parallel jobs (splitting buys wall clock, pays setup again); artifact upload/download time and stored size (large reports every green run cost time and storage). e.g. `gh run view <id> --log --job=<jobId>` and grep cache and executed-count lines. **Done when:** `Timings` holds hit rate, counts, shard ratio or "not sharded", setup cost, artifact size per lane that matters.
106
- - [ ] **Step 7 — Caches:** Every cache, not only task runner. Hit or miss and restore time: package-manager store, framework build cache, browser binaries, native build caches (e.g. Gradle, CocoaPods, hosted mobile builds), image layer caches. Compare restore vs cold install — restore slower than rebuild = finding. Cache usage vs eviction limit — full cache evicts entries that matter. **Done when:** `Caches` row per cache: hit or miss · restore vs cold · over limit, or absent with evidence.
107
- - [ ] **Step 8 — Affected:** Do PR lanes run only what changed (affected graph or path filter)? For docs-only change and one-app-scoped change, read `on:` triggers, `paths` filters, job-level `if:` — which lanes each starts. Where `paths` filter is safe, propose it and say required-check interaction: workflow skipped by path filter leaves required checks pending; job skipped by `if` reports success. **Done when:** `Affected` says what each sample change starts and names any required-check trap.
108
- - [ ] **Step 9 — Local:** Time local gate on whole tree, cache forced off — warm or affected-only numbers are meaningless. Record beside CI critical path. **Done when:** `Local` holds forced whole-tree time, command, whether on critical path.
109
- - [ ] **Step 10 — Reruns:** Red lane costs full re-run. Read concurrency block before counting. If in-progress runs not cancelled on integration branch, fix-and-repush = two complete runs; if cancelled, count cancelled minutes separately from re-runs — neither is zero. Flakiest lane slowest lane compounds wall clock; minutes here, cause → `bkit-audit-flakes`. Over Step 4 window: runs attempt >1; jobs failed then passed same commit, per lane — both → minutes. Also commits under both push and PR; runs completing after newer run started. **Done when:** `Reruns` holds those minutes and what concurrency block does.
110
- - [ ] **Step 11 — Cost:** For Step 4 window: billable minutes per lane x runner class current per-minute price, remote-builder minutes, mobile-build credits — read prices this run. Derive cost per successful merge to integration branch, re-runs included. Spend outside CI minutes → `bkit-audit-cost`. Before recommending runner class change for CPU-bound lane, name one-run experiment on larger/different-architecture runner comparing cost and duration (running it is next step — changes workflow). Every finding states whether it buys latency or cost. **Done when:** `Cost` holds minutes, current prices, cost per merge, experiment name or "none".
111
- - [ ] **Step 12 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: one row per DORA metric, host performance metric, caching/sharding/concurrency/billing practice in anchor list → checked (name step) / not applicable (why) / finding. Per bkit anchor (doc section, rule, or issue shape): one row → followed (name step or evidence) / not applicable (why) / finding; departure with no recorded reason (e.g. `docs/decisions.jsonl` row, accepted-divergence entry) = finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
112
- - [ ] **Step 13 — Anything Else:** (a) Everything changed since previous report's commit touching pipeline (workflows and composite actions, jobs and `needs:`, runner classes, task-runner config and cache keys, shard settings, remote-build profiles, local pre-push gate) → one-line verdict each. (b) Bounded ~30 min pass: what senior CI engineer flags that no step asks; read since previous run (incidents, new `docs/failures.jsonl` rows) — what would no step catch? **Done when:** `Beyond the Steps` holds both passes, or `none`. Class seen on 2 runs → propose step in `Process Improvements`.
103
+ - [ ] **Step 4 — Distributions:** One run cannot separate a regression from noise. Pull >=20 recent CI workflow runs per event type, and keep green and red apart. Report p50 and p90 for the total wall clock and for the critical-path lane finish, per event type. Say how typical the Step 2 runs are. Check that every job timeout is about 1.5x its p99 (at this sample size, the slowest run). **If** a job has no timeout → it gets the host default (e.g., GitHub Actions 360 minutes) and bills all of it. For example: `gh api "repos/{owner}/{repo}/actions/workflows/<workflow>/runs?event=push&branch=<branch>&per_page=30"`. **Done when:** `Distributions` holds p50 and p90, and each job meets the timeout rule or is a finding.
104
+ - [ ] **Step 5 — Lead Time:** Lane finish times are one segment. Report DORA change lead time for a push to the integration branch: push → all lanes green → deployed. Split it into queue (Step 3), critical-path execution, `needs:` waits and re-run time (Step 10). Name the dominating segment, because that is the one worth buying down. **Done when:** `Lead Time` names the split and the dominating segment.
105
+ - [ ] **Step 6 — Timings:** Inside the lanes that hold the run open, or that a proposal would trim, record: step timings; the task-runner cache hit rate (zero cached on a lane that should cache is a finding); the test counts executed (wall clock per test compares runs better than wall clock alone); for remote-builder jobs, the builder queue and build time, recorded separately from the wrapper; shard balance (a slowest/fastest ratio above about 1.3x means one shard holds the lane); the fixed cost per job (checkout, toolchain setup, install) x the parallel jobs (splitting buys wall clock, but pays setup again); and artifact upload and download time and stored size (large reports on every green run cost time and storage). For example, run `gh run view <id> --log --job=<jobId>` and grep the cache and executed-count lines. **Done when:** `Timings` holds the hit rate, counts, shard ratio or "not sharded", setup cost and artifact size for each lane that matters.
106
+ - [ ] **Step 7 — Caches:** Check every cache, not only the task runner's. Record hit or miss and the restore time for the package-manager store, the framework build cache, browser binaries, native build caches (e.g., Gradle, CocoaPods, hosted mobile builds) and image layer caches. Compare each restore with a cold install. A restore slower than a rebuild is a finding. Compare cache usage with the eviction limit, because a full cache evicts entries that matter. **Done when:** `Caches` holds one row per cache, with hit or miss, restore against cold, and over limit, or the cache is absent with evidence.
107
+ - [ ] **Step 8 — Affected:** Check whether PR lanes run only what changed (an affected graph or a path filter). For a docs-only change and a change scoped to one app, read the `on:` triggers, `paths` filters and job-level `if:`, and record which lanes each change starts. **If** a `paths` filter is safe → propose it, and state its interaction with required checks: a workflow skipped by a path filter leaves required checks pending, while a job skipped by `if` reports success. **Done when:** `Affected` says what each sample change starts, and names any required-check trap.
108
+ - [ ] **Step 9 — Local:** Time the local gate on the whole tree, with the cache forced off, because warm or affected-only numbers are meaningless. Record it beside the CI critical path. **Done when:** `Local` holds the forced whole-tree time, the command, and whether it is on the critical path.
109
+ - [ ] **Step 10 — Reruns:** A red lane costs a full re-run. Read the concurrency block before counting. **If** in-progress runs are not cancelled on the integration branch → a fix-and-repush costs two complete runs. **If** they are cancelled → count the cancelled minutes separately from re-runs. Neither is zero. **If** the flakiest lane is also the slowest lane → it compounds the wall clock. Count its minutes here, and send the cause to `bkit-audit-flakes`. Over the Step 4 window, count the runs with attempt >1, and the jobs that failed then passed on the same commit, per lane, and record both as minutes. Also count the commits that ran under both push and PR, and the runs that completed after a newer run started. **Done when:** `Reruns` holds those minutes, and what the concurrency block does.
110
+ - [ ] **Step 11 — Cost:** For the Step 4 window, multiply the billable minutes per lane by the runner class's current per-minute price, and record the remote-builder minutes and mobile-build credits. Read the prices during this run. Derive the cost per successful merge to the integration branch, re-runs included. Spend outside CI minutes goes to `bkit-audit-cost`. Before recommending a runner-class change for a CPU-bound lane, name a one-run experiment on a larger or different-architecture runner that compares cost and duration. Name the experiment only, and do not run it in this audit, because running it changes the workflow. Every finding states whether it buys latency or cost. **Done when:** `Cost` holds the minutes, the current prices, the cost per merge, and the experiment name or "none".
111
+ - [ ] **Step 12 — Standards:** Confirm the current version of each anchor standard, and read what changed since the previous report's version. Give `Standards Coverage` one row per DORA metric, per host performance metric, and per caching, sharding, concurrency or billing practice in the anchor list, each marked checked (naming the step), not applicable (saying why) or finding. Give each bkit anchor (a doc section, rule or issue shape) one row, marked followed (with the step or evidence), not applicable (saying why) or finding. A departure with no recorded reason (e.g., a `docs/decisions.jsonl` row or an accepted-divergence entry) is a finding. Mark each recommended practice the project does not apply as adopt (with a proposed step), reject (saying why) or not applicable. **Done when:** no row is empty.
112
+ - [ ] **Step 13 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches the pipeline: workflows and composite actions, jobs and `needs:`, runner classes, task-runner config and cache keys, shard settings, remote-build profiles, and the local pre-push gate. (b) In a bounded pass of about 30 minutes, note what a senior CI engineer would flag that no step asks about. Read what happened since the previous run (incidents, new `docs/failures.jsonl` rows), and ask what no step would catch. **Done when:** `Beyond the Steps` holds both passes, or says `none`. **If** one class of issue is seen on 2 runs → propose a step for it in `Process Improvements`.
113
113
 
114
114
  ### 🔒 Gate 2: Probes Check
115
115
 
116
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
117
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
116
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
117
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
118
118
  - [ ] **Event types:** push and pull request are never treated as one pipeline.
119
- - [ ] **Prices current:** every rate was read this run, not copied from a prior report.
120
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
119
+ - [ ] **Prices current:** every rate was read this run, not copied from a previous report.
120
+ - [ ] **Gate 2 — Verified:** every item above holds.
121
121
 
122
122
  ## Findings
123
123
 
124
124
  <!-- prettier-ignore -->
125
125
  | Severity | Use |
126
126
  | --- | --- |
127
- | `CRITICAL` | No green path through the pipeline; a job with no timeout can bill the host maximum on every run |
128
- | `HIGH` | The dominating segment is the one a proposal would not touch; latency described as cost savings, or the reverse, on that segment |
129
- | `MEDIUM` | Cache miss on a lane that should cache; shard imbalance holding a lane open; setup cost paid again on every split; re-run minutes that rival the critical path |
130
- | `LOW` | A slow lane that does not hold the run open; artifact size that is not on the critical path |
127
+ | `CRITICAL` | There is no green path through the pipeline. A job with no timeout can bill the host maximum on every run |
128
+ | `HIGH` | The dominating segment is the one a proposal would not touch. Latency is described as cost savings, or the reverse, on that segment |
129
+ | `MEDIUM` | A cache miss on a lane that should cache. Shard imbalance that holds a lane open. Setup cost paid again on every split. Re-run minutes that rival the critical path |
130
+ | `LOW` | A slow lane that does not hold the run open. Artifact size that is not on the critical path |
131
131
 
132
- Within a severity: critical path first. Every finding states whether it buys latency or cost.
132
+ Within a severity, list critical-path findings first. Every finding states whether it buys latency or cost.
133
133
 
134
134
  <!-- prettier-ignore -->
135
135
  | ID | Severity | Location | Evidence | Expected |
136
136
  | --- | --- | --- | --- | --- |
137
137
  | PENDING | PENDING | PENDING | PENDING | PENDING |
138
138
 
139
- Empty and clean → one row `None`.
139
+ **If** the run finds nothing → write one row: `None`.
140
140
 
141
141
  ## Report
142
142
 
@@ -217,13 +217,16 @@ PENDING
217
217
 
218
218
  ### 🔒 Gate 3: Report Check
219
219
 
220
- - [ ] **No placeholders:** no `PENDING` left
221
- - [ ] **Summary:** names count per severity and the segment that dominates wall clock.
222
- - [ ] **Series:** every series beside previous report's numbers, or marked baseline.
223
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
224
- - [ ] **Process Improvements:** `Universal` and `Project` filled
225
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
226
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
220
+ - [ ] **No placeholders:** no `PENDING` is left.
221
+ - [ ] **Summary:** `Summary` gives the count per severity.
222
+ - [ ] **Dominant segment:** `Summary` names the segment that dominates wall clock.
223
+ - [ ] **Series:** the report shows every series beside the previous report's numbers, or marks the run as baseline.
224
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
225
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
226
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
227
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
228
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
229
+ - [ ] **Gate 3 — Verified:** every item above holds.
227
230
 
228
231
  <!-- bkit:end -->
229
232