@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,138 +1,215 @@
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
  # Dead Code Audit
8
8
 
9
9
  > [!CAUTION]
10
- > **Purpose:** Reachability of code, config, routes, events, schema, and assets — what looks live and never runs.
10
+ > **Purpose:** The reachability of code, config, routes, events, schema and assets: what looks live and never runs.
11
11
  >
12
12
  > **Rules:**
13
13
  >
14
- > - NEVER delete code, files, routes, schema objects, or dependencies. The report names the destination; applying it is the next step.
15
- > - A detector proves use, never absence. Dead only when every method that would have found a use found none, and the file was opened. never write a finding from tool output alone.
14
+ > - NEVER delete code, files, routes, schema objects or dependencies. Name the destination in the report, and leave applying it to the next step.
15
+ > - A detector proves use, never absence. Call a candidate dead only when every method that would have found a use found none, and the file was opened.
16
+ > - Never write a finding from tool output alone.
16
17
 
17
18
  ## Universal Instructions
18
19
 
19
20
  ### Context & Goals
20
21
 
21
- Dead code = control that looks live, is not: limiter on unset env var; E2E assertion on test id no component renders; config key calling API removed from pinned dependency. Target failure: **a control that reads as live in review and never executes**.
22
+ Dead code is a control that looks live and is not. Examples: a limiter on an env var that is never set, an E2E assertion on a test id that no component renders, or a config key that calls an API the pinned dependency removed. The failure this audit targets is a control that reads as live in review and never executes.
22
23
 
23
- **Applies when:** application source, config, or package manifest. None → one `N/A` row with evidence, never "clean".
24
+ **Applies when:** the project has application source, config or a package manifest. **If** it has none → write one `N/A` row with its evidence, and never report the surface as "clean".
24
25
 
25
- **Cadence:** quarterly; extra pass when a cycle deletes a feature or moves a package.
26
+ **Cadence:** Run once a quarter. Run an extra pass when a cycle deletes a feature or moves a package.
26
27
 
27
28
  **Anchor Standards:**
28
29
 
29
- - Reachability scanner, version run, including production mode, workspaces, and issue types (e.g. knip, ts-prune, vulture).
30
- - Compiler unused and unreachable options (e.g. TypeScript `noUnusedLocals`, `noUnusedParameters`, `allowUnreachableCode`; Ruff `F401`, `F841`).
31
- - Always-true / always-false condition lint (e.g. typescript-eslint `no-unnecessary-condition`).
32
- - Unused-index advisor (e.g. Supabase Splinter `0005_unused_index`, engine index stats).
33
- - Database inspection CLI (e.g. `supabase inspect db`); record CLI version.
34
- - Feature-flag cleanup (e.g. Uber Piranha).
35
- - Runtime-usage dead-code removal (e.g. Meta SCARF).
36
- - i18n key checkers (e.g. `i18n-check`).
30
+ - Reachability scanner, version run, including production mode, workspaces, and issue types (e.g., knip, ts-prune, vulture).
31
+ - Compiler unused and unreachable options (e.g., TypeScript `noUnusedLocals`, `noUnusedParameters`, `allowUnreachableCode`; Ruff `F401`, `F841`).
32
+ - Always-true / always-false condition lint (e.g., typescript-eslint `no-unnecessary-condition`).
33
+ - Unused-index advisor (e.g., Supabase Splinter `0005_unused_index`, engine index stats).
34
+ - Database inspection CLI (e.g., `supabase inspect db`); record the version.
35
+ - Feature-flag cleanup (e.g., Uber Piranha).
36
+ - Runtime-usage dead-code removal (e.g., Meta SCARF).
37
+ - i18n key checkers (e.g., `i18n-check`).
37
38
 
38
39
  ### Scope
39
40
 
40
- - In-function unused locals, parameters, unreachable code, always-true/false conditions.
41
- - Module reachability: files, exports, types, duplicates; default run beside production mode.
42
- - Dependency reachability (own pass): unused, unlisted, unresolved, binaries, version-catalog entries.
43
- - Env-var reachability: referenced vs declared; gates.
44
- - Feature flags; config keys nothing reads; values always overridden.
45
- - Assertion surface (test ids), route surface (forwarders, stale pointers), client fetches with no route.
46
- - Schema objects nothing reaches.
47
- - Events, background functions, crons — both ends.
48
- - i18n keys, static assets, scripts.
49
- - Runtime executions — separate from static references.
41
+ - Find in-function unused locals and parameters, unreachable code, and always-true or always-false conditions.
42
+ - Check module reachability (files, exports, types and duplicates), with the default run beside a production-mode run.
43
+ - Check dependency reachability in its own pass: unused, unlisted and unresolved dependencies, binaries, and version-catalog entries.
44
+ - Check env-var reachability: referenced vars against declared ones, and the vars that gate a control.
45
+ - Find feature flags, config keys that nothing reads, and values that are always overridden.
46
+ - Check the assertion surface (test ids), the route surface (forwarders, stale pointers), and client fetches with no route.
47
+ - Find schema objects that nothing reaches.
48
+ - Check both ends of events, background functions and crons.
49
+ - Check i18n keys, static assets and scripts.
50
+ - Measure runtime executions separately from static references.
50
51
 
51
52
  ### Out of Scope
52
53
 
53
54
  <!-- prettier-ignore -->
54
55
  | Excluded item | Why | Where it belongs |
55
56
  | --- | --- | --- |
56
- | Module-graph shape | Architecture sweep | `bkit-audit-architecture` |
57
- | Git state, working-tree leftovers, layout | Repo sweep | `bkit-audit-repo` |
58
- | Config that is read but disagrees across environments or with its dashboard | Config sweep | `bkit-audit-config` |
59
- | Unused indexes as capacity | Database sweep | `bkit-audit-database` |
60
- | An unlisted dependency, or one with an advisory, beyond naming it | Dependency sweep | `bkit-audit-dependencies` |
61
- | An i18n key read but missing from the catalogue, as copy | Usability sweep | `bkit-audit-usability` |
62
- | A detector switched off, as a gate change | Gates sweep | `bkit-audit-gates` |
63
- | Wiring a reachability scanner into CI | Gate change | `bkit-audit-gates` |
64
- | Deleting code, files, routes, schema, or dependencies | Audit reports only | Plan from this report |
57
+ | Module-graph shape | The architecture sweep covers it | `bkit-audit-architecture` |
58
+ | Git state, working-tree leftovers, layout | The repo sweep covers it | `bkit-audit-repo` |
59
+ | Config that is read but disagrees across environments or with its dashboard | The config sweep covers it | `bkit-audit-config` |
60
+ | Unused indexes as capacity | The database sweep covers it | `bkit-audit-database` |
61
+ | An unlisted dependency, or one with an advisory, beyond naming it | The dependency sweep covers it | `bkit-audit-dependencies` |
62
+ | An i18n key read but missing from the catalogue, as copy | The usability sweep covers it | `bkit-audit-usability` |
63
+ | A detector switched off, as a gate change | The gates sweep covers it | `bkit-audit-gates` |
64
+ | Wiring a reachability scanner into CI | It is a gate change | `bkit-audit-gates` |
65
+ | Deleting code, files, routes, schema, or dependencies | The audit only reports | A plan made from this report |
65
66
 
66
67
  ### Pre-Flight / Dependencies
67
68
 
68
69
  #### Core
69
70
 
70
- - [ ] **Permissions:** blocked calls recorded
71
- - [ ] **Clean Tree:** Steps 2-17 — clean `git status` at recorded commit; one checkout all steps. Fallback: detached worktree off integration branch; dirty-path candidates = hypotheses.
72
- - [ ] **Text Search:** Steps 5-14 — repo search (`git grep`, ripgrep). Fallback: none → those steps `Not Checked`.
73
- - [ ] **Reachability Scanner:** Steps 3-4 — ad hoc, not committed dependency (e.g. `pnpm dlx knip`, vulture). Fallback: language-server refs + text search; scanner categories `Not Checked`.
74
- - [ ] **Web:** Step 16 — fetch anchor standards. Fallback: versions unread.
71
+ - [ ] **Permissions:** every blocked call is recorded.
72
+ - [ ] **Clean Tree:** Steps 2-17 — a clean `git status` at the recorded commit, with one checkout for every step. Fallback: use a detached worktree off the integration branch, and treat candidates on dirty paths as hypotheses.
73
+ - [ ] **Text Search:** Steps 5-14 — repo search (`git grep`, ripgrep). Fallback: none. Mark those steps `Not Checked`.
74
+ - [ ] **Reachability Scanner:** Steps 3-4 — an ad hoc scanner, not a committed dependency (e.g., `pnpm dlx knip`, vulture). Fallback: use language-server references and text search, and mark the scanner categories `Not Checked`.
75
+ - [ ] **Web:** Step 16 — fetch the anchor standards. Fallback: record the versions as unread.
75
76
 
76
77
  #### Conditional
77
78
 
78
- - [ ] **Compiler Unused Checks:** Compiled language → Step 2 — resolved compiler/linter config, not base file. Fallback: `Detectors` `Not Checked`.
79
- - [ ] **Language Server:** Typed language → Steps 13-14 — refs (Serena, `tsserver`, pyright). Fallback: text search only; name it; re-run every empty result before recording dead.
80
- - [ ] **Git History:** Flags or introduction dates → Step 6 — `git log -S`. Fallback: flag ages `Not Checked`.
81
- - [ ] **E2E Locators:** E2E asserts test ids → Step 7. Fallback: skip with evidence; `Assertions` = `N/A`.
82
- - [ ] **Hosted DB:** SQL migrations or hosted DB → Step 10 — inspection CLI + unused-index advisor (e.g. `supabase inspect db`, Splinter `0005_unused_index`). Fallback: static grep only; runtime zero-use `Not Checked`.
83
- - [ ] **Runtime Counts:** Production request/job/query stats → Step 15 — e.g. host per-route counts, job-runner runs, `pg_stat_statements`. Fallback: static only; "zero executions" `Not Checked`.
79
+ - [ ] **Compiler Unused Checks:** **If** the language is compiled → Step 2 — the resolved compiler and linter config, not the base file. Fallback: mark `Detectors` `Not Checked`.
80
+ - [ ] **Language Server:** **If** the language is typed → Steps 13-14 — references (Serena, `tsserver`, pyright). Fallback: text search only. Name it, and re-run every empty result before recording a candidate as dead.
81
+ - [ ] **Git History:** **If** the run needs flag ages or introduction dates → Step 6 — `git log -S`. Fallback: mark flag ages `Not Checked`.
82
+ - [ ] **E2E Locators:** **If** E2E tests assert test ids → Step 7. Fallback: skip the step with evidence, and set `Assertions` to `N/A`.
83
+ - [ ] **Hosted DB:** **If** the project has SQL migrations or a hosted DB → Step 10 — the inspection CLI and the unused-index advisor (e.g., `supabase inspect db`, Splinter `0005_unused_index`). Fallback: static grep only. Mark runtime zero-use `Not Checked`.
84
+ - [ ] **Runtime Counts:** **If** production request, job or query stats exist → Step 15 — e.g., host per-route counts, job-runner runs, `pg_stat_statements`. Fallback: static checks only. Mark "zero executions" `Not Checked`.
84
85
 
85
86
  ### 🔒 Gate 1: Prerequisites Check
86
87
 
87
- - [ ] **Gaps named:** every missing item names its fallback and `Not Checked` entry.
88
- - [ ] **Gate 1 — Verified:** All Core items checked. All applicable Conditional items checked.
88
+ - [ ] **Gaps named:** every missing item names its fallback and its `Not Checked` entry.
89
+ - [ ] **Gate 1 — Verified:** every item above, every Core item and every applicable Conditional item is checked.
89
90
 
90
91
  ### Probe Steps
91
92
 
92
- - [ ] **Step 1 — Previous Run:** **Done when:** closure rate in `Previous Run`, or run marked baseline.
93
- - [ ] **Step 2 — Detectors:** Compiled language → scanner sees module exports only; dead branch/parameter inside live function → compiler + linter. Read resolved config per workspace, not base: unused-local, unused-parameter, no-unreachable-code; linter unused-vars, unreachable, always-true/false (e.g. `@typescript-eslint/no-unnecessary-condition`). Workspace override or file disable switches one off silently. Detector off = finding → `bkit-audit-gates` (gate candidate). Linter cannot run on project's compiler version (e.g. peer dependency range excludes it) → same detector-off finding; its rules → `Not Checked`. **Done when:** `Detectors` lists each config and resolved value.
94
- - [ ] **Step 3 — Reachability:** Ad hoc scanner, same resolved version both runs; record version. Do not add it as a dependency, and do not wire a CI gate this run. Report baseline-config readiness. First readiness check: scanner ignores exports used inside their own file (e.g. knip `ignoreExportsUsedInFile`); without it export signal = noise → run with and without, report both counts. Gate before `False Positives` exclusions encoded → structural noise → disabled. Do not encode test-only code as ignore entries or negated project patterns — plugins add test files as entries; production mode separates. Check scanner stderr before trusting: plugin load failure drops entry class → false unused files. Signal: files, exports, types, duplicates. Dependency categories → `Dependencies` pass, not mixed. Same version in production mode (or strict: implies production + each workspace uses only its own deps). Export used default run, unused production → test/config-only class. Report both runs side by side. Scanner has no class-member check (e.g. knip 6: no `classMembers` issue type) and project has classes → gap in `Not Checked`; fallback = language-server references per public member. **Done when:** version, both runs, with/without in-file-use counts, plugin-load errors in `Reachability`.
95
- - [ ] **Step 4 — Dependencies:** Scanner dependency mode per workspace, categories the scanner offers (e.g. knip: unused, unlisted, unresolved, unlisted binaries, catalog entries unreferenced). Before unused verdict → search name across manifest scripts, config, CI. Config-only consumers (e.g. linter, formatter, CSS presets, bundler plugins, `@types/*`) = usual false hits. Unused = install/supply-chain surface; unlisted = hoisted from another workspace. Unlisted or advisory → `bkit-audit-dependencies`. **Done when:** `Dependencies` row per candidate: name · class · config-or-CI reader · verdict.
96
- - [ ] **Step 5 — Env Vars:** Text search only — env names are string literals; language server cannot see them. Every referenced env vs declared (examples, task runner, typed env schema — sources in `Project Instructions`). Referenced, never declared → control cannot switch on. Triage: platform-injected = fine; optional + safe default = fine (read default); gates control (absence disables limiter, auth, feature) = finding. Third group → path never executed in any environment. Omitted declaration source → `Process Improvements` gap. Gating var → `docs/failures.jsonl` via `@bkit-utility-update-failures`, and `bkit-audit-duplication`. **Done when:** `Env Vars` row per referenced-undeclared: group · absence effect · verdict.
97
- - [ ] **Step 6 — Config:** Deadness no scanner reports. (a) Feature flags stuck on/off; hardcoded or same every environment → branch never runs. Per flag: every read + value per environment; all same → other branch dead = finding. Age flags (`git log -S`); >90 days, rollout complete = finding even if environments differ. (b) Config keys no reader, or name removed object — search key; language server reads typed source only. (c) Default replaced in every environment by later layer = lying docs. Dead control → `docs/failures.jsonl` like `Env Vars`, not tidiness. **Done when:** `Config` row per flag/unread key: value per environment · age · verdict.
98
- - [ ] **Step 7 — Assertions:** E2E asserts test ids → unmatched locator passes; test id no component renders = vacuous spec, green CI. Extract asserted E2E ids vs component-rendered ids (both string literals). **Done when:** `Assertions` lists asserted-but-unrendered ids, or `none`.
99
- - [ ] **Step 8 — Routes:** Two checks; the second is where the defects are. (a) Forwarders. A route whose page only redirects renders nothing: no content, an extra round trip, and it reads in every route list as a page. Use the project's derived list, do not eyeball the tree. The usual justification is that old bookmarked or emailed links must keep working — check that claim against the deployment doc before accepting it. (b) What still points at a forwarder, or at a path that moved. Grep the old path, not the new one. Stale cache-invalidation call (e.g. Next.js `revalidatePath` / `revalidateTag`) refreshes the stub; the page a user reads is never invalidated. Stale end-to-end helpers drive every spec through the redirect. A middleware allowlist arm that can no longer match reads as a live carve-out. A deep-link or email builder whose redirect drops a query param loses the token or id silently. A doc comment naming the old directory is free to fix, and it makes the next reader mistrust every other comment in the file. Relative imports hide the dependency: a repo-wide grep for the path string misses `./old/page`. After a route delete, run the typecheck before believing a grep was complete. Stale generated route types are build output: remove them and re-run, do not read them as source errors. A test that pins the call argument (`toHaveBeenCalledWith` the path) cannot tell a live pointer from a dead one. "A test covers it" is no evidence in this step. **Done when:** `Routes` row per forwarder and per stale pointer: kind · `file:line` · verdict.
100
- - [ ] **Step 9 — Fetches:** Clients call API paths with raw fetch → the mirror of `Routes`. Route-side asks whether a route has a caller. This asks whether a call has a route. Neither finds the other's class. Compiler-checked RPC clients are out of scope (a missing route fails typecheck). Raw fetch is the whole exposure: a URL inside a template literal, so lint, typecheck, and the reachability scanner all pass on a path that 404s. Two routing layers (where the stack has them) → model both. The outer framework decides whether a handler runs (static directory vs catch-all that forwards a subtree). The inner router then routes within what was forwarded. A route correctly mounted on the inner router and unreachable from the outer layer is its own class (`stranded`). Checking either layer alone says the route is fine. Read a finding as two questions: the path has no handler, and why nobody noticed. The answer is at the call site — `if (res.ok)` skips the block, `if (!res.ok) return success` fails open. A 404 is a successful HTTP response, so nothing throws. The report names the guard and the route. Confirm against the deployment (status code of the path beside a known-live path) before writing it up. Two false positives, do not reintroduce them: a path in a doc comment is not a call; a prefix test (`startsWith`) is not a request. The dangerous failure is silent: an extractor that stops at `?` never reports the URL, so it is not seen. When changing extraction, the fetched-path count must go up, not merely the findings list get shorter. No project script → extract literals and match routes by hand; record the gap in `Process Improvements`. **Done when:** `Fetches` row per unreachable call and per stranded route: path · call-site guard · deployment status · verdict.
101
- - [ ] **Step 10 — Schema:** SQL migrations or hosted DB — only step here. Unused column/orphan SQL function still costs migrations + access review. From the schema source (migrations, schema file, or generated types): per table, column, view, SQL function, access policy (e.g. RLS) → search code (table calls, columns, RPC), other SQL (triggers, policies, functions), deployed serverless functions (e.g. edge functions). Zero refs all three = candidate. Runtime on deployed DB: table no scans/writes since stats reset (record reset time); inspection-CLI table/index stats; unused-index advisor. Unused indexes → also `bkit-audit-database` — name, do not duplicate capacity finding. Thin/pre-launch traffic → zero-use = static candidate, never proof alone. **Done when:** `Schema` row per candidate: object · static refs · runtime counts · reset time · verdict.
102
- - [ ] **Step 11 — Events:** Jobs, crons, event bus — mirror of `Fetches` for background work. Event names = string literals; scanner + language server blind. List every send, registered function + trigger/cron, every cron + target. Sent event → registered function; registered trigger → sender or cron; cron → existing target. No trigger = dead function; no function = unfireable control → route like `Env Vars`. **Done when:** `Events` row per name: sender · function · cron target · verdict.
103
- - [ ] **Step 12 — Strings:** (a) Message catalogue — diff keys vs reads each app/shared UI both ways (`i18n-check` or search script). No reader = dead; read missing = renders key name; language server often blind → search. Missing catalogue → `bkit-audit-usability`. (b) Static assets — list shipped (incl. email templates); search basename in code, config, CSS; scanner skips assets; native bundle ships unused. (c) Scripts — per manifest script + scripts tree file → search name in CI, hooks, task runner, docs, other scripts, plus its stem and every process-spawn site (e.g. `spawn`, `exec`, a directory listing filtered by extension) — runtime-built path misses name search; no invoker = candidate; doc-only = candidate + reader to update. **Done when:** `Strings` row per unused key, missing key, unread asset, uninvoked script.
104
- - [ ] **Step 13 — False Positives:** Filter these before reading anything as a finding. They are structural and recur every run. Ambient module augmentation: zero importers by design; applied through the compiler include. Never dead. Platform file splits (e.g. RN `.ios` / `.android` / `.web`): one specifier resolves to a per-platform file the scanner cannot follow, so unresolved entries are noise. The filter hides the opposite, so check once per run: for each platform pair, the platform that would load that variant imports the parent. A single-platform component carrying the other platform's file is dead and invisible, because both resolve through the same specifier. Files referenced from config, not code: check the referencing config before believing unused (app config, CI, test-runner project dependencies, agent hooks, deployed functions, an explicit worker registry). Test-only exports: only importer is a test = a seam, not dead code. Report separately from unreferenced code; never delete. A drift test is not a reader: generated artefact referenced only by its generator and a drift test (no runtime reader) = finding, not seam. A default export a preview server requires while code imports the named one. Mock-factory keys: no scanner and no language server sees them; a key inside a mock factory is a real use. **Done when:** `Candidates` names each class and what it removed.
105
- - [ ] **Step 14 — Eliminate:** Language server before opening files. One reference found means the candidate is not dead, and that verdict is sound even though the converse is not. Per surviving unused-export candidate: find the symbol, then find references. Any hit ends it. Empty → fall through to text search, and re-run the empty language-server query once more before recording it. Record both measurements. Pace reference queries: back-to-back calls collapse to zero, and a partial answer looks exactly like a dead symbol. Empty is inconclusive, not absence. Text search over-reports (comments, same-named symbols in other modules); the language server under-reports. Agreement is the signal. Run search in addition to the language server, never instead of it. An unused export needs zero matches repo-wide other than its own definition: search, subtract the defining file, ignore prose comments. An unused file is not reached from JSON, YAML, or other config no typed tool reads. An env-var finding is a control, not an optional setting with a working default. A test id asserted in end-to-end tests exists on a component. No finding without opening the file. Cite `file:line` and the method. Non-typed surfaces (markdown, ledgers, YAML, SQL, shell, string literals) are search, not the language server. **Done when:** every survivor in `Candidates` has `file:line`, method, and the zero-reference re-run.
106
- - [ ] **Step 15 — Runtime:** Production request/job/query stats → static says unreferenced; production says ran. Rank survivors: recent window of per-route counts/logs, job runs, SQL function query stats. "Zero executions" != "zero static references". Thin/pre-launch → signal, never proof; uncalled route != dead. **Done when:** `Runtime` holds window, source, zero-execution rows, or skip.
107
- - [ ] **Step 16 — Standards:** Confirm current version per anchor standard; read changes since previous report's version. `Standards Coverage`: row per anchor + scanner issue type → checked (name step) / not applicable (why) / finding. Unapplied recommended practice → adopt (propose step) / reject (why) / not applicable. **Done when:** no empty row.
108
- - [ ] **Step 17 — Anything Else:** (a) Since previous commit, reachability-touching changes (features/packages deleted/moved, exports/files, deps, env/flags, routes/fetch URLs, events/functions/crons, migrations, i18n, assets, manifest scripts) → one-line verdict each. (b) ~30 min bounded pass: senior code-health flags no step asks; since previous run (incidents, new `docs/failures.jsonl`, `bkit-audit-logs` reports, 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`.
93
+ - [ ] **Step 1 — Previous Run:** **Done when:** `Previous Run` holds the closure rate, or the run is marked baseline.
94
+ - [ ] **Step 2 — Detectors:** **If** the language is compiled → the scanner sees module exports only, so a dead branch or parameter inside a live function needs the compiler and the linter. Read the resolved config of each workspace, not the base file: the compiler's unused-local, unused-parameter and no-unreachable-code options, and the linter's unused-vars, unreachable and always-true / always-false rules (e.g., `@typescript-eslint/no-unnecessary-condition`). A workspace override or a file-level disable switches one off silently. **If** a detector is off → record a finding, and name it for `bkit-audit-gates` as a gate candidate. Read every unused-import hit in shipped source, because a module that is imported but never registered shows up only there. **If** the linter cannot run on the project's compiler version (e.g., its peer dependency range excludes that version) → record the same detector-off finding, and mark its rules `Not Checked`. **Done when:** `Detectors` lists each config and its resolved value.
95
+ - [ ] **Step 3 — Reachability:** Run the scanner ad hoc, at the same resolved version for both runs, and record the version.
96
+ - Do not add it as a dependency, and do not wire a CI gate this run.
97
+ - Report how ready a baseline config is. The first readiness check is that the scanner ignores exports used inside their own file (e.g., knip `ignoreExportsUsedInFile`). Without that setting the export signal is noise, so run with it and without it, and report both counts. A gate wired before the `False Positives` exclusions are encoded fails on structural noise, and gets disabled.
98
+ - Do not encode test-only code as ignore entries or negated project patterns: plugins add test files as entries, and production mode separates them.
99
+ - Check the scanner's stderr before trusting its output, because a plugin that fails to load drops a whole class of entries and produces false unused files. The signal is files, exports, types and duplicates. Dependency categories go to the `Dependencies` pass, not mixed in here.
100
+ - Run the same version in production mode (or strict mode, which implies production mode and has each workspace use only its own dependencies).
101
+ - **If** an export is used in the default run **and** unused in the production run → it belongs to the test-only or config-only class.
102
+ - Report both runs side by side.
103
+ - Open every duplicate-export alias with zero readers, and run once with entry exports included (e.g., knip `--include-entry-exports`).
104
+ - **If** the scanner has no class-member check (e.g., knip 6 has no `classMembers` issue type) **and** the project has classes → record the gap in `Not Checked`, and fall back to language-server references for each public member.
105
+
106
+ **Done when:** `Reachability` holds the version, both runs, the counts with and without in-file use, and the plugin-load errors.
107
+
108
+ - [ ] **Step 4 — Dependencies:** Run the scanner's dependency mode for each workspace, in the categories the scanner offers (e.g., knip: unused, unlisted, unresolved, unlisted binaries, unreferenced catalog entries). Before giving an unused verdict, search for the name across manifest scripts, config and CI. Config-only consumers are the usual false hits (e.g., linter, formatter, CSS presets, bundler plugins, `@types/*`). An unused dependency is install and supply-chain surface. An unlisted one is hoisted from another workspace. **If** a dependency is unlisted **or** has an advisory → name it for `bkit-audit-dependencies`. **Done when:** `Dependencies` holds one row per candidate: name · class · config-or-CI reader · verdict.
109
+ - [ ] **Step 5 — Env Vars:** Use text search only, because env names are string literals that a language server cannot see. Compare every referenced env var with the declared ones (examples, task runner, typed env schema; the sources are in `Project Instructions`). A var that is referenced and never declared is a control that cannot switch on. Triage each one: a platform-injected var is fine, and an optional var with a safe default is fine (read the default). A var that gates a control, whose absence disables a limiter, auth or a feature, is a finding. The third group is a path that never executes in any environment. Then compare each declared var that gates a control with the secret names set in every runtime environment that runs it (e.g., the host's env list, the secret-sync map), by name only, NEVER the value. A gating var missing from one of those environments is a finding. **If** the run's token cannot read an environment's list → mark that environment `Not Checked` with the permission it needs, never clean. **If** a declaration source was omitted → record the gap in `Process Improvements`. **If** a var gates a control → route it to `docs/failures.jsonl` through `@bkit-utility-update-failures`, and to `bkit-audit-duplication`. **Done when:** `Env Vars` holds one row per referenced-but-undeclared var: group · effect of its absence · verdict, and one row per gating var missing from a runtime environment.
110
+ - [ ] **Step 6 — Config:** Look for the deadness that no scanner reports. (a) Feature flags stuck on or off: a flag that is hardcoded, or the same in every environment, leaves a branch that never runs. For each flag, record every read and its value in each environment. **If** the values are all the same → the other branch is dead, and that is a finding. Age each flag with `git log -S`. **If** a flag is older than 90 days **and** its rollout is complete → record a finding even when the environments differ. (b) Config keys with no reader, or whose name points at a removed object: search for the key, because a language server reads typed source only. (c) A default that a later layer replaces in every environment makes the docs lie. Route a dead control to `docs/failures.jsonl` as in `Env Vars`, not as tidiness. **Done when:** `Config` holds one row per flag or unread key: value per environment · age · verdict.
111
+ - [ ] **Step 7 — Assertions:** **If** E2E tests assert test ids → an unmatched locator passes, so a test id that no component renders makes a vacuous spec with green CI. Extract the test ids the E2E tests assert and the ids that components render (both are string literals), and compare them. **Done when:** `Assertions` lists the asserted-but-unrendered ids, or `none`.
112
+ - [ ] **Step 8 — Routes:** Run two checks; the second is where the defects are.
113
+ - (a) Forwarders. A route whose page only redirects renders nothing: it has no content, adds a round trip, and reads in every route list as a page.
114
+ - Use the project's derived route list rather than eyeballing the tree.
115
+ - The usual justification is that old bookmarked or emailed links must keep working, so check that claim against the deployment doc before accepting it.
116
+ - (b) What still points at a forwarder, or at a path that moved.
117
+ - Grep for the old path, not the new one.
118
+ - A stale cache-invalidation call (e.g., Next.js `revalidatePath` / `revalidateTag`) refreshes the stub, so the page a user reads is never invalidated.
119
+ - Stale end-to-end helpers drive every spec through the redirect.
120
+ - A middleware allowlist arm that can no longer match reads as a live carve-out.
121
+ - A deep-link or email builder whose redirect drops a query param loses the token or id silently.
122
+ - A doc comment naming the old directory is free to fix, and it makes the next reader mistrust every other comment in the file.
123
+ - Relative imports hide the dependency: a repo-wide grep for the path string misses `./old/page`.
124
+ - After a route delete, run the typecheck before believing a grep was complete.
125
+ - Stale generated route types are build output: remove them and re-run, rather than reading them as source errors.
126
+ - A test that pins the call argument (`toHaveBeenCalledWith` the path) cannot tell a live pointer from a dead one, so "a test covers it" is no evidence in this step.
127
+
128
+ **Done when:** `Routes` holds one row per forwarder and per stale pointer: kind · `file:line` · verdict.
129
+
130
+ - [ ] **Step 9 — Fetches:** **If** clients call API paths with raw fetch → run the mirror of `Routes`.
131
+ - The route side asks whether a route has a caller, and this step asks whether a call has a route. Neither finds the other's class.
132
+ - Compiler-checked RPC clients are out of scope, because a missing route fails the typecheck.
133
+ - Include URL pointers outside code (e.g., env-derived webhook URLs, sync configs, fixtures).
134
+ - Raw fetch is the whole exposure: the URL sits inside a template literal, so lint, typecheck and the reachability scanner all pass on a path that returns 404.
135
+ - **If** the stack has two routing layers → model both.
136
+ - The outer framework decides whether a handler runs (a static directory, or a catch-all that forwards a subtree), and the inner router then routes within what was forwarded.
137
+ - A route correctly mounted on the inner router and unreachable from the outer layer is its own class (`stranded`). Checking either layer alone says the route is fine.
138
+ - Read each finding as two questions: the path has no handler, and why nobody noticed. The answer is at the call site: `if (res.ok)` skips the block, and `if (!res.ok) return success` fails open. A 404 is a successful HTTP response, so nothing throws.
139
+ - Name the guard and the route in the report.
140
+ - Before writing a finding up, confirm it against the deployment: the status code of the path beside a known-live path.
141
+ - Do not reintroduce two false positives: a path in a doc comment is not a call, and a prefix test (`startsWith`) is not a request.
142
+ - When you change the extraction, the fetched-path count must go up, not only the findings list get shorter. The dangerous failure is silent: an extractor that stops at `?` never reports the URL, so nobody sees it.
143
+ - **If** the project has no script for this → extract the literals and match routes by hand, and record the gap in `Process Improvements`.
144
+
145
+ **Done when:** `Fetches` holds one row per unreachable call and per stranded route: path · call-site guard · deployment status · verdict.
146
+
147
+ - [ ] **Step 10 — Schema:** This step is the only one here for SQL migrations or a hosted DB. An unused column or an orphan SQL function still costs migrations and access review. From the schema source (migrations, schema file or generated types), take each table, column, view, SQL function and access policy (e.g., RLS), and search for it in code (table calls, columns, RPC), in other SQL (triggers, policies, functions) and in deployed serverless functions (e.g., edge functions). An object with zero references in all three is a candidate. At runtime on the deployed DB, check for tables with no scans or writes since the stats reset (record the reset time), read the inspection CLI's table and index stats, and run the unused-index advisor. Name unused indexes for `bkit-audit-database` as well, without duplicating its capacity finding. **If** traffic is thin **or** the app is pre-launch → zero use marks a static candidate, never proof on its own. **Done when:** `Schema` holds one row per candidate: object · static refs · runtime counts · reset time · verdict.
148
+ - [ ] **Step 11 — Events:** Jobs, crons and the event bus are the mirror of `Fetches` for background work. Event names are string literals, so the scanner and the language server are blind to them. List every send, every registered function with its trigger or cron, and every cron with its target. Check that each sent event reaches a registered function, that each registered trigger has a sender or a cron, and that each cron has an existing target. A function with no trigger is dead. An event with no function is a control that cannot fire, so route it as in `Env Vars`. **Done when:** `Events` holds one row per name: sender · function · cron target · verdict.
149
+ - [ ] **Step 12 — Strings:** (a) Message catalogue: diff the keys against the reads in each app and in shared UI, both ways (`i18n-check` or a search script). A key with no reader is dead. A read key missing from the catalogue renders the key name. A language server is often blind here, so search. Name each key missing from the catalogue for `bkit-audit-usability`. (b) Static assets: list the shipped assets (email templates included), and search for each basename in code, config and CSS. The scanner skips assets, and a native bundle ships unused ones. (c) Scripts: for each manifest script and each file in the scripts tree, search for its name in CI, hooks, the task runner, docs and other scripts. Also search for its stem and check every process-spawn site (e.g., `spawn`, `exec`, a directory listing filtered by extension), because a path built at runtime escapes a name search. A script with no invoker is a candidate. A script invoked only from docs is a candidate, with the reader to update. **Done when:** `Strings` holds one row per unused key, missing key, unread asset and uninvoked script.
150
+ - [ ] **Step 13 — False Positives:** Filter these classes before reading anything as a finding. They are structural and recur on every run.
151
+ - Ambient module augmentation has zero importers by design and applies through the compiler include, so it is never dead.
152
+ - Platform file splits (e.g., RN `.ios` / `.android` / `.web`): one specifier resolves to a per-platform file the scanner cannot follow, so unresolved entries are noise.
153
+ - The filter hides the opposite case, so check once per run that, for each platform pair, the platform that would load that variant imports the parent.
154
+ - A single-platform component carrying the other platform's file is dead and invisible, because both resolve through the same specifier.
155
+ - Files referenced from config, not code: check the referencing config before believing a file unused (app config, CI, test-runner project dependencies, agent hooks, deployed functions, an explicit worker registry).
156
+ - Test-only exports: an export whose only importer is a test is a seam, not dead code.
157
+ - Report them apart from unreferenced code, and never delete them.
158
+ - A drift test is not a reader: a generated artefact referenced only by its generator and a drift test (no runtime reader) is a finding, not a seam.
159
+ - A default export that a preview server requires while code imports the named one.
160
+ - Mock-factory keys: no scanner and no language server sees them, so a key inside a mock factory is a real use.
161
+
162
+ **Done when:** `Candidates` names each class and what it removed.
163
+
164
+ - [ ] **Step 14 — Eliminate:** Use the language server before opening files. One reference found means the candidate is not dead, and that verdict is sound even though the converse is not.
165
+ - For each surviving unused-export candidate, find the symbol, then find its references. Any hit ends the candidate.
166
+ - **If** the result is empty → fall through to text search, and re-run the empty language-server query once more before recording it.
167
+ - Record both measurements.
168
+ - Pace the reference queries: back-to-back calls collapse to zero, and a partial answer looks exactly like a dead symbol. An empty result is inconclusive, not proof of absence.
169
+ - Text search over-reports (comments, same-named symbols in other modules), and the language server under-reports, so agreement between them is the signal.
170
+ - Run the search in addition to the language server, never instead of it:
171
+ - An unused export needs zero matches repo-wide other than its own definition: search, subtract the defining file, and ignore prose comments.
172
+ - An unused file is not reached from JSON, YAML or other config that no typed tool reads.
173
+ - An env-var finding is a control, not an optional setting with a working default.
174
+ - A test id asserted in end-to-end tests exists on a component.
175
+ - Write no finding without opening the file, and cite `file:line` and the method.
176
+ - Non-typed surfaces (markdown, ledgers, YAML, SQL, shell, string literals) take search, not the language server.
177
+
178
+ **Done when:** every survivor in `Candidates` has its `file:line`, its method and the zero-reference re-run.
179
+
180
+ - [ ] **Step 15 — Runtime:** **If** production request, job or query stats exist → compare them with the static results: static analysis says what is unreferenced, and production says what ran. Rank the survivors by a recent window of per-route counts or logs, job runs and SQL function query stats. "Zero executions" is not "zero static references". **If** traffic is thin **or** the app is pre-launch → the counts are a signal, never proof, and an uncalled route is not dead. **Done when:** `Runtime` holds the window, the source and the zero-execution rows, or the skip.
181
+ - [ ] **Step 16 — 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 and per scanner issue type, 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.
182
+ - [ ] **Step 17 — Anything Else:** (a) Give a one-line verdict on each change since the previous report's commit that touches reachability: features or packages deleted or moved, exports and files, dependencies, env vars and flags, routes and fetch URLs, events, functions and crons, migrations, i18n, assets, and manifest scripts. (b) In a bounded pass of about 30 minutes, note what a senior code-health reviewer would flag that no step asks about. Read what happened since the previous run (incidents, new `docs/failures.jsonl` rows, `bkit-audit-logs` reports, vendor status incidents), 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`.
109
183
 
110
184
  ### 🔒 Gate 2: Probes Check
111
185
 
112
- - [ ] **Steps complete:** every step `[x]`, or explicit skip with evidence the surface is absent.
113
- - [ ] **Evidence:** every finding cites re-checkable evidence and the tool behind it.
114
- - [ ] **Candidates eliminated:** every survivor opened the file; a method that found a use ended it; every zero-reference result was re-run and both measurements are recorded.
115
- - [ ] **Tree untouched:** no code, config, schema, or dependency change.
116
- - [ ] **Gate 2 — Verified:** Every checkbox above independently verified and checked off.
186
+ - [ ] **Steps complete:** every step is `[x]`, or skipped with evidence that its surface is absent.
187
+ - [ ] **Evidence:** every finding cites evidence someone can check again, and the tool that produced it.
188
+ - [ ] **Candidates eliminated:** every survivor's file was opened.
189
+ - [ ] **Use ends a candidate:** every candidate for which a method found a use was ended.
190
+ - [ ] **Re-runs:** every zero-reference result was re-run.
191
+ - [ ] **Re-runs recorded:** both measurements of every re-run are recorded.
192
+ - [ ] **Tree untouched:** no code, config, schema or dependency changed.
193
+ - [ ] **Gate 2 — Verified:** every item above holds.
117
194
 
118
195
  ## Findings
119
196
 
120
197
  <!-- prettier-ignore -->
121
198
  | Severity | Use |
122
199
  | --- | --- |
123
- | `CRITICAL` | Dead control on auth, a limiter, or validation (the path never executes); client fetch whose error path treats failure as success, so the missing route never surfaces |
124
- | `HIGH` | User-facing or background path with no handler, or a handler nothing can reach; end-to-end assertion that passes because the target does not exist; event or cron with one end missing |
125
- | `MEDIUM` | File or export with zero references after elimination; feature flag older than 90 days with rollout complete; unused or unlisted dependency; i18n key with no reader, or a reader missing from the catalogue |
126
- | `LOW` | Doc comment naming a moved path; test-only export (own class, never a delete); preview-only default export |
200
+ | `CRITICAL` | A dead control on auth, a limiter or validation (the path never executes). A client fetch whose error path treats failure as success, so the missing route never surfaces |
201
+ | `HIGH` | A user-facing or background path with no handler, or a handler nothing can reach. An end-to-end assertion that passes because its target does not exist. An event or cron with one end missing |
202
+ | `MEDIUM` | A file or export with zero references after elimination. A feature flag older than 90 days whose rollout is complete. An unused or unlisted dependency. An i18n key with no reader, or a reader whose key is missing from the catalogue |
203
+ | `LOW` | A doc comment naming a moved path. A test-only export (its own class, never a delete). A preview-only default export |
127
204
 
128
- Within a severity: dead controls first.
205
+ Within a severity, list dead controls first.
129
206
 
130
207
  <!-- prettier-ignore -->
131
208
  | ID | Severity | Location | Evidence | Expected |
132
209
  | --- | --- | --- | --- | --- |
133
210
  | PENDING | PENDING | PENDING | PENDING | PENDING |
134
211
 
135
- Empty and clean → one row `None`.
212
+ **If** the run finds nothing → write one row: `None`.
136
213
 
137
214
  ## Report
138
215
 
@@ -225,13 +302,17 @@ PENDING
225
302
 
226
303
  ### 🔒 Gate 3: Report Check
227
304
 
228
- - [ ] **No placeholders:** no `PENDING` left
229
- - [ ] **Summary:** names count per severity and candidate / surviving counts.
230
- - [ ] **Series:** `Reachability` counts and `Runtime` zeroes beside previous report's numbers, or marked baseline.
231
- - [ ] **Writes:** only this report, template `Project Instructions`, and ledger rows changed; throwaway worktrees / remote targets removed.
232
- - [ ] **Process Improvements:** `Universal` and `Project` filled
233
- - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID in exactly one row; every row has a `Next Step`.
234
- - [ ] **Gate 3 — Verified:** Every checkbox above independently verified and checked off.
305
+ - [ ] **No placeholders:** no `PENDING` is left.
306
+ - [ ] **Summary:** `Summary` gives the count per severity.
307
+ - [ ] **Candidates:** `Summary` gives the candidate count.
308
+ - [ ] **Survivors:** `Summary` gives the surviving count.
309
+ - [ ] **Series:** the report shows `Reachability` counts and `Runtime` zeroes beside the previous report's numbers, or marks the run as baseline.
310
+ - [ ] **Writes:** this run changed only this report, the template's `Project Instructions` and its own `docs/failures.jsonl` rows.
311
+ - [ ] **Throwaways removed:** every throwaway worktree or remote target is removed.
312
+ - [ ] **Process Improvements:** `Universal` and `Project` are both filled.
313
+ - [ ] **Suggested Issues:** every `MEDIUM`+ finding ID is in exactly one `Suggested Issues` row.
314
+ - [ ] **Next Step:** every `Suggested Issues` row has a `Next Step`.
315
+ - [ ] **Gate 3 — Verified:** every item above holds.
235
316
 
236
317
  <!-- bkit:end -->
237
318