@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -3,17 +3,16 @@
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** Human-facing reference. Five-phase pipeline + every subagent (phases in execution order, then audit and utilities) + every audit template. Evaluation, onboarding — not agent workflow doc-matrix. bkit vs other frameworks and vs _Agentic Design Patterns_: `.bkit/comparison.md`.
6
+ > **Purpose:** A reference for people: the five-phase pipeline, every subagent (the phases in the order they run, then the audit and the utilities) and every audit template. It serves evaluation and onboarding, and it is not one of the docs agents load during a workflow. How bkit compares with other frameworks and with _Agentic Design Patterns_ is in `.bkit/comparison.md`.
7
7
  >
8
8
  > **Rules:**
9
9
  >
10
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
- > - Describe current state / rules, not reasons / history; state what to do, not why.
12
- > - Keep prose factual; house / write-good linters apply to `*.md`; no hype adjectives.
13
- > - Headings linked from outside carry a fixed `<a id>` above them; keep the id when rewording the heading.
14
- > - No model, effort or tier per subagent: those live in `.bkit/prompts.md` § Models only.
15
- > - Pipeline or subagents change → update to match `.bkit/core/workflows/*` and `.bkit/core/.bkit/prompts.md`.
16
- > - Audit templates added, removed or renamed → update § Audits to match `.bkit/core/docs/templates/bkit-audit-*.md`.
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - Keep the prose factual, with no hype adjectives. The house and write-good linters apply to `*.md`.
12
+ > - A heading linked from outside this file carries a fixed `<a id>` above it. Keep the id when you reword the heading.
13
+ > - Leave out each subagent's model, effort and tier. Those live only in `.bkit/prompts.md` § Models.
14
+ > - **If** the pipeline or the subagents change → update this file to match `.bkit/core/workflows/*` and `.bkit/core/.bkit/prompts.md`.
15
+ > - **If** an audit template is added, removed or renamed → update § Audits to match `.bkit/core/docs/templates/bkit-audit-*.md`.
17
16
 
18
17
  **Contents**
19
18
 
@@ -24,11 +23,11 @@
24
23
 
25
24
  ## What this is
26
25
 
27
- bkit turns a single coding-agent request into gated, peer-reviewed engineering. Five commands — `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship` — each fans out to specialised single-purpose subagents (49 in total, phases + audit + utilities). Many run parallel under different _lenses_ (bug review vs security review) → independent review before human sees output. Same pipeline on five hosts: Claude Code, Cursor, Codex, Google Antigravity, opencode.
26
+ bkit turns a single coding-agent request into gated, peer-reviewed engineering. Each of its five commands, `/bkit-design` → `/bkit-plan` → `/bkit-build` → `/bkit-debug` → `/bkit-ship`, fans out to specialised single-purpose subagents: 40 in total, counting the phases, the audit and the utilities. Many run in parallel under different lenses, such as bug review and security review, so the output gets an independent review before a person sees it. The same pipeline runs on five hosts: Claude, Codex, Antigravity, Cursor and OpenCode.
28
27
 
29
28
  Beside those commands, 35 read-only audit templates live at `docs/templates/bkit-audit-*.md`. `@bkit-audit-generate` runs one and writes `docs/audits/{YYYYMM}/{slug}.md`. `/bkit-plan` takes a design, one or more of those reports, or both.
30
29
 
31
- Each phase lists subagents in execution order. "Parallel" = same-time run, merged after; distinct lenses = multi-perspective review. Orchestrator steps (git, worktree, tracker) noted but not listed as subagents. Model and thinking depth per subagent and host: `.bkit/prompts.md` § Models.
30
+ Each phase below lists its subagents in the order they run. "Parallel" means the subagents run at the same time and their outputs are merged afterwards. Distinct lenses mean the review comes from several perspectives. Orchestrator steps (git, worktree, tracker) are noted but not listed as subagents. The model and thinking depth of each subagent on each host are in `.bkit/prompts.md` § Models.
32
31
 
33
32
  <a id="pipeline-map"></a>
34
33
 
@@ -37,9 +36,9 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
37
36
  ```
38
37
  ┌────────────────────── bkit-auto (opt-in cloud router) ─────────────────┐
39
38
  │ workflow_run on feat/** → ship (CI green) / debug (CI red) │
40
- │ workflow_dispatch → ship|debug|plan|build (design: local only) │
39
+ │ workflow_dispatch → ship|debug|design|plan|build │
41
40
  │ Dispatches the matching /bkit-* skill — runs unattended in cloud │
42
- │ (Claude Code on the web / Cursor cloud agents / opencode). │
41
+ │ (Claude on the web / Cursor cloud agents / OpenCode). │
43
42
  │ Opt-in: `bkit install --auto=claude|cursor|opencode`. See `.bkit/cloud.md`. │
44
43
  └────────────────────────────────────────────────────────────────────────┘
45
44
  │
@@ -50,95 +49,99 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
50
49
  last round confirms a DRAFT acceptance scenario;
51
50
  skipped headless: recommended answers recorded as assumed)
52
51
  2. fetch related (semantic tracker search, rank order → related-issues.md)
53
- 3. brainstorm × 3 (parallel, distinct lenses, no sibling reads)
52
+ 3. brainstorm x 3 (parallel, distinct lenses, no sibling reads)
54
53
  • pragmatic • optimal-tradeoff • risk / pre-mortem
55
54
  4. generate design (synthesise across lenses + related issues)
56
- 5. review × 2 (parallel, cross-tier models)
55
+ 5. review x 2 (parallel, distinct lenses, on different models)
57
56
  • feasibility (web) • operability (failure modes, observability, on-call)
58
57
  6. spike (only if review flags load-bearing unknowns:
59
58
  throwaway probe code, confined to the run's log folder)
60
59
  7. update design (fold reviews + spike back in)
61
- 8. organise (decompose into workstreams + DAG)
62
- 9. summary (tracker-facing)
60
+ 8. organise (workstreams + DAG, grouped into plans: the filed unit)
61
+ 9. summary (engine-written from status rows, tracker-facing)
63
62
 
64
63
  /bkit-plan ───── output: detailed plan ───────────────────────────────────────
65
- 1. generate plan
64
+ 1. generate plan (task groups within bkit.workflows.tasks caps, in build order;
65
+ engine plan-check right after, one fix retry)
66
66
  2. fetch context (tracker: related issues; ledgers: prior deferrals,
67
67
  prior failures, strongest term-overlap first, top 40
68
68
  → feeds all three reviewers below)
69
- 3. review × 3 (parallel, distinct lenses)
70
- • tightness + design-coverage • dependency-correctness • regression-risk
71
- 4. update plan (merge critiques, max-wins on CRITICAL)
72
- 5. scope-check × 2 (parallel)
73
- • internal-completeness • scope audit (cross-family)
74
- 6. update plan (merge scope findings)
75
- 7. complexity-check (single vs split)
76
- 8. complexity-split (only if SPLIT)
77
- 9. summary (tracker-facing)
69
+ 3. review x 2 + scope-check (parallel, one round, distinct lenses)
70
+ • plan text: tightness, dependency order • code: regression risk
71
+ • scope check: template, criteria, verification
72
+ 4. update plan (merge all three in one pass, max-wins on CRITICAL;
73
+ engine plan-check right after, one fix retry)
74
+ 5. summary (engine-written from status rows, tracker-facing)
78
75
 
79
76
  /bkit-build ─── output: code, PR to dev, CI takes over ──────────────────────
80
- 1. plan-current (plan still executable against code landed since it was written?)
81
- 2. install-skills
82
- 3. execute build (producer — implement tasks)
83
- 4. verify build (critic — verify each task; tick only on confirmed artifacts)
84
- ↶ producer-critic loop, capped 3 attempts
85
- 5. gaps-remediate (fix verifier gaps, re-verify)
86
- 6. verify build (holistic second pass across whole plan)
87
- 7. challenge × 2 (parallel, distinct lenses, no sibling reads)
88
- • bug-hunting • security
89
- 8. challenge-reconcile (merge findings, severity + verdict max-wins)
90
- 9. challenge-remediate (classify-gate: architectural → FAIL; else fix + test)
91
- 10. challenge-tests (edge-case tests for changed files)
92
- 11. run tests (local tier: lint + typecheck + unit + slop:delta + bkit check;
93
- no integration / e2e / @live — those run in CI)
77
+ 1. plan-check (engine: plan in group and task blocks, within caps?)
78
+ ↳ no plan, no task markers, or comments newer than the plan → plan-convert writes {FID}-plan.md
79
+ (from the prompt, issue and any plan; where they disagree, the newer text wins)
80
+ 2. plan-current (plan still executable against code landed since it was written?)
81
+ 3. install-skills
82
+ ┌ per task group, in order ─────────────────────────────────────────────
83
+ │ 4. brief (engine: the group's open tasks + plan context)
84
+ │ 5. tests, then code (one agent writes planned tests, engine proves reds,
85
+ │ another implements; either may hand over once)
86
+ │ 6. verify group (critic — the group's own diff; passes satisfied task numbers, engine ticks)
87
+ │ ↶ producer-critic loop, configured verify limit;
88
+ │ unfixable gaps / no progress → Decision Pause (human, in session)
89
+ │ 7. gaps-remediate (fix verifier gaps, re-verify)
90
+ └ group gate between groups (static + unit) ─────────────────────────────
91
+ 8. verify build (holistic second pass across whole plan, once)
92
+ 9. challenge (size gate first: under 300 lines and 10 files → security only;
93
+ else both in parallel, distinct lenses, no sibling reads)
94
+ • bug-hunting (large changes) • security (always)
95
+ 10. challenge merge (engine: findings become plan tasks, each with a test first;
96
+ a repeated finding reopens its open task; LOW → deferred;
97
+ fixable → back to the group loop, a last-round fix not
98
+ challenged again; unfixable → Decision Pause; two rounds at most)
99
+ 11. run tests (deepest declared local gate, plus bkit check;
100
+ includes integration when declared, excludes @live)
94
101
  ↳ on test failure → /bkit-debug (debug-failure-diagnose + remediate)
95
- 12. summary (tracker-facing + PR link)
96
- → PR opened; CI runs the full multi-tier scaffold (see "CI test scaffold" below)
102
+ 12. summary (engine-written from status rows + plan tasks, tracker-facing;
103
+ no plan file or an unticked task → FAIL)
104
+ → publish=true: PR opened; CI runs the adopted scaffold below
105
+ publish=false on a local run: worktree retained, no push or PR
97
106
 
98
107
  /bkit-debug ─── side-rail, invoked on test/CI failure ────────────────────────
99
- 1. run tests (broader tier than build: lint + typecheck + unit
100
- + integration + e2e + optional @live canary —
101
- reproduces against the deployed boundary)
102
- 2. fetch context (only if tests FAIL; CI: failed jobs/steps + error
103
- annotations + failed-step logs; e2e test reports; local
104
- test output; diff vs last-passing CI; runtime logs via
105
- context-fetch blocks; tracker: related issues by error
106
- signature → feeds diagnose below)
107
- [repro] (first run passes — bug not reproduced yet):
108
- 2. fetch context, then reproduce (tests that fail on the reported
109
- symptoms → back to 1; can't reproduce → summary)
108
+ 1. select failure (validated selected CI evidence first when available;
109
+ otherwise declared local gates + optional live tier)
110
+ 2. fetch context (CI, diff, E2E, runtime, web and related-issue evidence)
111
+ [repro]: reproduce reported symptoms before remediation;
112
+ unresolved CI reproduction blocks resolution
110
113
  Normal mode (localisable failure):
111
114
  3. diagnose (reads docs/knowledge.jsonl for prior failures;
112
115
  Standard → Pivot → Final strategy escalation)
113
116
  4. remediate (apply diagnosis fix)
114
117
  5. re-run tests
115
- 6. summary
116
- ↳ if diagnose can't localise, or loop exhausts 3 strategies → Soak mode
118
+ 6. summary (engine-written from status rows)
119
+ ↳ if diagnose can't localise, or configured fix limit is used → Soak mode
117
120
  Soak mode (non-localisable / runtime-only failure):
118
121
  1. soak loop (one accumulating context per iteration:
119
122
  instrument OR smallest evidence-backed fix;
120
- strips all scaffolding before declaring a fix)
123
+ strips all scaffolding before declaring a fix;
124
+ configured soak limit applies across feature runs)
125
+ CI-only failure: exact pushed-head CI proof required before close
121
126
  Escape hatch:
122
127
  abort-handover (unrecoverable failure → human handover doc + stop)
123
128
 
124
129
  /bkit-ship ─── output: squash-merged PR, hard stop before main ──────────────
125
- 1. conflict-resolve (only if rebase sentinels exist)
130
+ 1. integrate dev (local merge when behind; resolve remaining conflicts)
126
131
  2. deferred-sweep (pre-merge completeness gate; FAIL blocks merge)
127
- 3. run tests (wait for CI on squash-merge SHA; bkit-tests-check
128
- must be green — every planned tier ran and passed;
129
- a planned bkit-tests-live-web failure reds it)
130
- 4. merge (orchestrator-only guarded git op)
132
+ 3. docs + summary (update docs, assess unresolved findings, prune skills)
133
+ 4. merge (push bookkeeping, validate CI at the covered head,
134
+ guarded squash-merge; generated-only red may regenerate)
131
135
  ↳ on post-merge failure → /bkit-debug (diagnose + remediate)
132
- 5. update-docs / summary (parallel)
133
- 6. prune skills + update local dev + close (orchestrator-only;
134
- close removes the worktree)
136
+ 5. verify merge CI (a failed merge run is recorded before Failure Path)
137
+ 6. close (land the record on dev, then remove the worktree)
135
138
  ```
136
139
 
137
140
  <a id="ci-scaffold"></a>
138
141
 
139
142
  ## CI test scaffold (runs on every PR + push)
140
143
 
141
- The template `bkit-ci.yml` (copied into `.bkit/templates/`, adopted and owned by the consumer) is static: two lanes run in parallel and the `bkit-tests-check` capstone joins them as the single branch-protection check. No planner. The capstone fails unless both lanes concluded `success`, and fails a unit lane that reports zero executed tests.
144
+ The template `bkit-ci.yml` is copied into `.bkit/templates/`, and the consumer adopts and owns it. It is static: two lanes run in parallel, and the `bkit-tests-check` capstone joins them as the single branch-protection check. There is no planner. The capstone fails unless both lanes concluded `success`, and it fails when the unit lane reports zero executed tests.
142
145
 
143
146
  ```
144
147
  bkit-tests-static (typecheck, lint, format, prose lint, slop, actionlint, bkit check)
@@ -148,101 +151,96 @@ bkit-tests-unit (unit tests; writes the executed-test count)
148
151
  bkit-tests-check (capstone: needs both lanes; sole required check)
149
152
  ```
150
153
 
151
- Add the lanes the repo has (integration, E2E, migration, live) as further `needs:` of the capstone. Full tier rules: `docs/testing.md`.
154
+ Add the lanes the repo has (integration, E2E, migration, live) as further `needs:` of the capstone. The full tier rules are in `docs/testing.md`.
152
155
 
153
- Hard stops after Design, Plan, and Ship (production merge needs explicit human approval). Shared subagents cross-invoked: `bkit-debug-failure-diagnose` / `bkit-debug-failure-remediate` run inside Build and Ship failure paths as well as the Debug phase.
156
+ The pipeline stops hard after Design, Plan and Ship. A production merge needs explicit human approval. Some subagents are shared across phases: `bkit-debug-failure-diagnose` and `bkit-debug-failure-remediate` run inside the Build and Ship failure paths as well as in the Debug phase.
154
157
 
155
- With `bkit-auto` enabled, the loop is unattended: Build opens a PR → CI runs → on green `bkit-auto` dispatches `/bkit-ship`, on red it dispatches `/bkit-debug`; debug re-pushes, CI re-runs, auto-routes again — no local session required until a human gate fires.
158
+ With `bkit-auto` enabled, the loop runs unattended. Build opens a PR, and CI runs. On green, `bkit-auto` dispatches `/bkit-ship`. On red, it dispatches `/bkit-debug`, debug re-pushes, CI re-runs, and `bkit-auto` routes again. No local session is needed until a human gate fires.
156
159
 
157
160
  <a id="bkit-design"></a>
158
161
 
159
162
  ## Phase 1 — `/bkit-design`
160
163
 
161
- Output: reviewed design (`docs/plans/{YYYYMM}/{FID}-design.md`). Hard stop for human approval.
164
+ Output: the reviewed design (`docs/plans/{YYYYMM}/{FID}-design.md`). The phase stops hard for human approval.
162
165
 
163
166
  <!-- prettier-ignore -->
164
167
  | Subagent | Lens / focus | What it does |
165
168
  | --- | --- | --- |
166
- | `bkit-design-brainstorm-ideate-1` | Pragmatic | Independent design exploration. Forbidden from reading siblings (circular-reasoning guard). |
169
+ | `bkit-design-brainstorm-ideate-1` | Pragmatic | Independent design exploration. Forbidden from reading its siblings, as a guard against circular reasoning. |
167
170
  | `bkit-design-brainstorm-ideate-2` | Optimal-tradeoff | Same task, different lens, on a different model from its siblings. |
168
171
  | `bkit-design-brainstorm-ideate-3` | Risk / pre-mortem | Same task, failure-mode lens. |
169
172
  | `bkit-design-generate` | Synthesiser | Merges three brainstorms into one design. Merges across lenses rather than collapsing to consensus. |
170
173
  | `bkit-design-review-1` | Feasibility (web) | Adversarial review with live web search; checks ecosystem feasibility per capability. |
171
- | `bkit-design-review-2` | Operability (cross-tier) | Parallel review on a different model from review-1: failure modes, observability, on-call ergonomics. |
174
+ | `bkit-design-review-2` | Operability | Parallel review on a different model from review-1: failure modes, observability, on-call ergonomics. |
172
175
  | `bkit-design-spike` | Probe unknowns | Only when a review flags load-bearing unknowns: settles them with throwaway probe code, confined to the run's log folder. |
173
176
  | `bkit-design-update` | Apply review | Folds both reviews (and the spike, if run) back into the design. |
174
- | `bkit-design-organise` | Structure | Cleans and organises the final design doc. |
175
- | `bkit-design-summary` | Summarise | Writes the tracker-facing summary (capped, scannable). |
177
+ | `bkit-design-organise` | Structure | Splits the reviewed design into dependency-annotated workstreams and plans. |
176
178
 
177
179
  <a id="bkit-plan"></a>
178
180
 
179
181
  ## Phase 2 — `/bkit-plan`
180
182
 
181
- Output: executable plan (`{FID}-plan.md`, split into `-plan-N.md` if too large). Consumes design. Hard stop.
183
+ Output: an executable plan (`{FID}-plan.md`), its tasks in groups the build runs one at a time. The phase consumes the design, and stops hard.
182
184
 
183
185
  <!-- prettier-ignore -->
184
186
  | Subagent | Lens / focus | What it does |
185
187
  | --- | --- | --- |
186
- | `bkit-plan-generate` | Generate | Turns the design into a tasked plan. |
187
- | `bkit-plan-review-1` | Tightness + design-coverage | Read-only critique; flags vague or missing `Done when:` as CRITICAL. Parallel. |
188
- | `bkit-plan-review-2` | Dependency-correctness | Same scope, dependency lens. Depth-sensitive: stays on the top model tier. Parallel. |
189
- | `bkit-plan-review-3` | Regression-risk | Same scope, regression lens. Parallel. |
190
- | `bkit-plan-update` | Apply review (merge) | Merges all three critiques, max-wins on CRITICAL findings. |
191
- | `bkit-plan-scope-check-1` | Internal-completeness | Mechanical scope audit — verifies template structure and criteria slots. Parallel. |
192
- | `bkit-plan-scope-check-2` | Scope audit (cross-family) | Second scope audit in parallel for independent coverage. |
193
- | `bkit-plan-update` | Apply scope fixes | Second merge pass folding scope-check findings in. |
194
- | `bkit-plan-complexity-check` | Single → split classifier | Decides whether the plan is too big for one build and must be split. |
195
- | `bkit-plan-complexity-split` | Splitter | If SPLIT: divides the plan into sequenced sub-plans. |
196
- | `bkit-plan-summary` | Summarise | Tracker-facing summary. |
188
+ | `bkit-plan-generate` | Generate | Turns the design into groups of task blocks, in build order. |
189
+ | `bkit-plan-review-1` | Tightness + dependency order + design-coverage | Read-only critique of the plan text; flags drift, out-of-order tasks and missing prerequisites as CRITICAL. Parallel. |
190
+ | `bkit-plan-review-2` | Regression-risk | Same scope, reads the code: traces each task's surfaces to their consumers. Parallel. |
191
+ | `bkit-plan-scope-check` | Internal-completeness | Mechanical scope audit: verifies the template structure, and each task's scope and verification. Each task's `DONE WHEN` / `TEST FIRST` belong to `bkit tests plan-check`. Parallel. |
192
+ | `bkit-plan-update` | Apply review (merge) | Merges all three critiques in one pass, max-wins on CRITICAL findings. |
197
193
 
198
194
  <a id="bkit-build"></a>
199
195
 
200
196
  ## Phase 3 — `/bkit-build`
201
197
 
202
- Output: PR to `dev`. Heaviest phase — most steps verify rather than produce. CI takes over after PR.
198
+ Output: a PR to `dev`. This is the heaviest phase: most of its steps verify rather than produce. CI takes over after the PR.
203
199
 
204
200
  <!-- prettier-ignore -->
205
201
  | Subagent | Lens / focus | What it does |
206
202
  | --- | --- | --- |
203
+ | `bkit-build-plan-convert` | Plan writer | Runs only when the plan is missing, has no task markers, or is older than an issue comment. Writes `{FID}-plan.md` as groups of task blocks within the `bkit.workflows.tasks` caps, from the build-input file (prompt and issue) and any existing plan, whose other sections it keeps. Where they disagree, the newer text wins. |
207
204
  | `bkit-build-plan-current` | Plan freshness | Judges whether changes landed since the plan was written leave it executable; findings feed execute. |
208
205
  | `bkit-build-install-skills` | Setup | Installs the skills the plan needs for this build. |
209
- | `bkit-build-plan-execute` | Producer | Implements the plan tasks; iterates edit → lint/typecheck/test → edit. |
210
- | `bkit-build-plan-verify` | Critic | Verifies each task against the plan; ticks boxes only on confirmed artifacts. Producer-critic loop, capped at 3 attempts. |
206
+ | `bkit-build-plan-tests` | Test writer | Writes one task group's planned tests from its tests brief, touching test files only; the engine then records each one failing. |
207
+ | `bkit-build-plan-tasks` | Producer | Implements one task group's tasks from its brief against the tests already recorded failing, touching no planned test. Iterates edit → lint/typecheck/test → edit. Near its turn cap it hands over (`HANDOVER`), and the group re-runs once. |
208
+ | `bkit-build-plan-verify` | Critic | Verifies each task of one group against the group's own diff. Passes the satisfied task numbers, and `bkit tasks tick` sets the boxes. The producer-critic loop uses `bkit.workflows.build.verify.maxAttempts` for its limit. |
211
209
  | `bkit-build-plan-gaps-remediate` | Gap-fixer | Fills gaps the verifier found, then re-verifies. |
212
210
  | `bkit-build-plan-verify` | Holistic critic | Second, whole-of-plan verification pass across everything built. |
213
- | `bkit-build-challenge-1` | Bug-hunting | Adversarial review of the full diff. Forbidden from reading its sibling. Parallel. |
214
- | `bkit-build-challenge-2` | Security | Same diff, security lens. Depth-sensitive: stays on the top model tier. Parallel. |
215
- | `bkit-build-challenge-reconcile` | Merge findings | Unifies both challenges. `Severity` and verdict max-wins; downgrades need explicit justification. |
216
- | `bkit-build-challenge-remediate` | Fixer (classify-gate) | Any architectural finding → FAIL (no silent fixes); else applies mechanical fixes and re-runs tests. |
217
- | `bkit-build-challenge-tests` | Test author | Adds edge-case tests for changed files; runs the test suite. |
218
- | `bkit-debug-failure-diagnose` | Diagnostician | (If tests fail) diagnoses with Standard / Pivot / Final strategy escalation. Shared with debug. |
219
- | `bkit-debug-failure-remediate` | Fixer | (If tests fail) applies the diagnosed fix. |
220
- | `bkit-build-summary` | Summarise | Tracker-facing summary plus PR link. |
211
+ | `bkit-build-challenge-1` | Bug-hunting | Adversarial review of the full diff. Writes each finding as a plan task with a test first. Forbidden from reading its sibling. Parallel. Runs only on a large change (300+ lines or 10+ files, `docs/plans/**` excluded, measured by `bkit challenge gate`). A small change runs `-2` alone. `bkit challenge merge` then appends the findings to the plan, and execute and verify fix them. |
212
+ | `bkit-build-challenge-2` | Security | Same diff, security lens. Runs on every change, alone on a small one. |
213
+ | `bkit-debug-failure-diagnose` | Diagnostician | When tests fail, diagnoses with Standard / Pivot / Final strategy escalation. Shared with debug. |
214
+ | `bkit-debug-failure-remediate` | Fixer | When tests fail, applies the diagnosed fix. |
221
215
 
222
216
  <a id="bkit-debug"></a>
223
217
 
224
218
  ## Phase 4 — `/bkit-debug`
225
219
 
226
- Output: remediated commit on feature branch. Two modes — normal (diagnose → remediate localisable failure) and soak (one accumulating-context instrument-or-fix loop for non-localisable / runtime-only failures). Normal escalates to soak when diagnose can't localise, or normal loop exhausts three strategies; observation logging (`[DEBUG-OBSERVE]`) inside soak, stripped before fix ships.
220
+ Output: a remediated commit on the adopted branch, which may be `dev`. The phase has two modes:
227
221
 
228
- **Context fetch.** Per failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md` — failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily) — writing one artifact per context and narrating `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. Fail-soft and block-driven: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
222
+ - Normal mode diagnoses a failure that can be localised, then remediates it.
223
+ - Soak mode runs one accumulating-context instrument-or-fix loop for failures that cannot be localised or that appear only at runtime.
224
+
225
+ Normal mode escalates to soak when diagnose cannot localise the failure, or when the configured fix-attempt limit is used. Fix and soak limits are counted across the feature's debug runs. Soak mode adds observation logging (`[DEBUG-OBSERVE]`), and strips it before the fix ships.
226
+
227
+ **Context fetch.** On each failed attempt, `/bkit-debug` runs each `context-fetch` bash block below `<!-- bkit:end -->` in `.agents/context.md`. The contexts are failing CI logs, the diff since the last green run, end-to-end reports, runtime errors (Sentry, Vercel, Supabase, Stripe and more) and web search (Tavily). It writes one artifact per context, and narrates `CHECKED` / `SELF-SKIPPED` / `NOT CONFIGURED` before fetching. The fetch is fail-soft and driven by the blocks: bkit hardcodes no CI host, workflow filename or test framework, and a context with no block is never read as a clean result.
229
228
 
230
229
  **Normal mode**
231
230
 
232
231
  <!-- prettier-ignore -->
233
232
  | Subagent | Lens / focus | What it does |
234
233
  | --- | --- | --- |
235
- | `bkit-debug-failure-reproduce` | Reproducer (`[repro]` only) | Nothing fails yet → tests failing on the reported symptoms, never a fix; soak mode → tests repeat the scenario. Not reproduced → tests removed, run ends at Summary; reproduced but the re-run passes with no fix → Summary. |
234
+ | `bkit-debug-failure-reproduce` | Reproducer (`[repro]` only) | Writes tests that fail on the reported symptoms, never a fix. On selected CI evidence, a successful reproduction is required for the current generation; failure to reproduce blocks resolution. On the local path, a successful reproduction returns to Run Tests, while failure to reproduce proceeds to Summary. |
236
235
  | `bkit-debug-failure-diagnose` | Diagnostician | Reproduces and diagnoses. Accumulates per-attempt context; escalates Standard → Pivot → Final. |
237
236
  | `bkit-debug-failure-remediate` | Fixer | Applies whatever the strategy-aware diagnosis produced, with a test loop. |
238
- | `bkit-debug-summary` | Summarise | Tracker-facing summary. |
239
237
 
240
238
  **Soak mode**
241
239
 
242
240
  <!-- prettier-ignore -->
243
241
  | Subagent | Lens / focus | What it does |
244
242
  | --- | --- | --- |
245
- | `bkit-debug-failure-soak` | Instrument-or-fix loop | One accumulating context against the failing boundary; each iteration either adds `[DEBUG-OBSERVE]` instrumentation or applies the smallest evidence-backed fix, stripping all scaffolding before declaring a fix. Bounded by `SOAK_ATTEMPT` (reset per soak entry). |
243
+ | `bkit-debug-failure-soak` | Instrument-or-fix loop | One accumulating context against the failing boundary; each iteration either adds `[DEBUG-OBSERVE]` instrumentation or applies the smallest evidence-backed fix, stripping all scaffolding before declaring a fix. Bounded by `SOAK_ATTEMPT` (counted across every debug run of the feature). |
246
244
 
247
245
  **Escape hatch**
248
246
 
@@ -255,79 +253,78 @@ Output: remediated commit on feature branch. Two modes — normal (diagnose →
255
253
 
256
254
  ## Phase 5 — `/bkit-ship`
257
255
 
258
- Output: squash-merged PR, updated docs, pruned skills, torn-down worktree. Safety-critical — hard guards on production branch, explicit human approval to touch `main`.
256
+ Output: a squash-merged PR, updated docs, pruned skills and a torn-down worktree. The phase is safety-critical: it has hard guards on the production branch, and touching `main` needs explicit human approval.
259
257
 
260
258
  <!-- prettier-ignore -->
261
259
  | Subagent | Lens / focus | What it does |
262
260
  | --- | --- | --- |
263
- | `bkit-ship-conflict-resolve` | Conflict resolver | Resolves merge conflicts against the integration branch, then runs the tests. |
264
- | `bkit-ship-deferred-sweep` | Pre-merge completeness gate | Builds the intended-delivery set from plan `Acceptance Scenario` sections + `Done when` lines; FAILs the merge if any unplanned gap (silent `TODO`, skipped test) is found. Declared deferrals resurfaced, never blocking. Gates only what the repo can prove — plan gate checkboxes, `Verification Plan` boxes and `Manual Verification` steps are build-phase process, never gated, and no plan precondition or merge condition blocks however a log or summary restates it. |
265
- | `bkit-debug-failure-diagnose` | Diagnostician | (If post-merge checks fail) diagnoses the regression. Shared with debug. |
266
- | `bkit-debug-failure-remediate` | Fixer | (If post-merge checks fail) applies the fix. |
267
- | `bkit-ship-update-docs` | Docs | Updates knowledge / decisions / completed docs. Parallel with summary. |
268
- | `bkit-ship-summary` | Summarise | Final tracker-facing summary. Parallel with docs. |
261
+ | `bkit-ship-conflict-resolve` | Conflict resolver | Resolves the remaining integration-branch merge conflicts and re-runs the merge block to commit them. |
262
+ | `bkit-ship-deferred-sweep` | Pre-merge completeness gate | Builds the intended-delivery set from the plan's `Acceptance Scenario` sections and `DONE WHEN` fields. FAILs the merge if it finds any unplanned gap (a silent `TODO`, a skipped test). Declared deferrals are resurfaced, never blocking. Gates only what the repo can prove: plan gate checkboxes, `Verification Plan` boxes and `Manual Verification` steps are build-phase process and never gated, and no plan precondition or merge condition blocks, however a log or summary restates it. |
263
+ | `bkit-ship-update-docs` | Docs | Syncs the cataloged docs before the merge, excluding the knowledge and decision ledgers. |
264
+ | `bkit-debug-failure-diagnose` | Diagnostician | Diagnoses a refused merge before a bounded fix attempt. Shared with debug. |
265
+ | `bkit-debug-failure-remediate` | Fixer | Applies the diagnosed fix before merge re-validation. |
269
266
 
270
- Orchestrator-only ship steps: regression guard, merge, skill pruning, update local dev (`bkit branches sync-dev`; never checks out `dev`), close (removes the worktree). Guarded git / tracker ops orchestrator performs directly, not subagents.
267
+ Orchestrator-only ship steps: regression guard, merge, skill pruning, update local dev (`bkit branches sync-dev`, which never checks out `dev`) and close (which removes the worktree). The orchestrator performs the guarded git and tracker operations itself, not through subagents.
271
268
 
272
269
  ## Audits
273
270
 
274
- No command and no phase label. One subagent, one template per run.
271
+ Audits have no command and no phase label. One subagent runs one template per run.
275
272
 
276
273
  <!-- prettier-ignore -->
277
274
  | Subagent | Lens / focus | What it does |
278
275
  | --- | --- | --- |
279
- | `bkit-audit-generate` | One template | Runs `docs/templates/bkit-audit-*.md`. Writes `docs/audits/{YYYYMM}/{slug}.md` (`{slug}` = basename without `bkit-audit-`; same slug already in that month → `{slug}-{TIMESTAMP}.md`). Report is the template through `bkit:end`. Refines that template's `Project Instructions` below `bkit:end`. Issue named in the invocation + tracker wired → posts the final summary there as one comment. No issue named + tracker wired → searches for the template's audit parent and posts there; none open → suggests one, with the summary saved for its first comment. |
276
+ | `bkit-audit-generate` | One template | Runs `docs/templates/bkit-audit-*.md`. Writes `docs/audits/{YYYYMM}/{slug}.md` (`{slug}` = basename without `bkit-audit-`; same slug already in that month → `{slug}-{TIMESTAMP}.md`). The report is the template through `bkit:end`. Refines that template's `Project Instructions` below `bkit:end`. Issue named in the invocation and tracker wired → posts the final summary there as one comment. No issue named and tracker wired → searches for the template's audit parent and posts there. None open → suggests one, with the summary saved for its first comment. |
280
277
 
281
278
  `/bkit-plan` reads a design doc, one or more reports, or both. The invocation names which findings are in scope. The rest of each report stays context. With neither, the issue is the plan's source: a well-defined change issue carries its narrative, success criteria, edge cases, tests and tasks into the plan.
282
279
 
283
- All 35 templates, by area. Template file = `docs/templates/bkit-audit-{template}.md`.
280
+ All 35 templates, by area. Each template's file is `docs/templates/bkit-audit-{template}.md`.
284
281
 
285
282
  <!-- prettier-ignore -->
286
283
  | Area | Audit | Template | What it finds |
287
284
  | --- | --- | --- | --- |
288
285
  | **Security and privacy** | Security | `security` | Holes in sign-in, permissions, secrets and input checks, plus documented protections that never run. |
289
- | | Red team | `red-team` | Attacks a test copy of the app, never production, one hostile request at a time. Keeps each request and response, then cleans up. |
290
- | | Privacy | `privacy` | Where personal data goes and how long it stays, whether deleting an account removes the person, whether the privacy policy matches the code. |
286
+ | | Red team | `red-team` | Attacks a test copy of the app, never production, one hostile request at a time. Keeps each request and response, then cleans up. |
287
+ | | Privacy | `privacy` | Where personal data goes and how long it stays, whether deleting an account removes the person, whether the privacy policy matches the code. |
291
288
  | **Code quality** | Architecture | `architecture` | Code that breaks the intended layers: server code reaching the client, modules tied together with no visible import. |
292
- | | Duplication | `duplication` | One behaviour built more than once: copied rules, competing mechanisms, restated types, merges that should not have happened. |
293
- | | Dead code | `dead-code` | Code, settings, routes, events, tables and assets that look live and never run. |
294
- | | Slop | `slop` | Every switched-off check: disabled lint rules, casts that hide type errors, skipped tests, config opt-outs. |
295
- | | Documentation | `documentation` | Docs that disagree with the code, links that land nowhere, facts agents rely on that nobody wrote down. |
296
- | | Dependencies | `dependencies` | Pending dependency updates merged as one verified batch; security advisories, licences, end-of-life packages, supply-chain settings. |
289
+ | | Duplication | `duplication` | One behaviour built more than once: copied rules, competing mechanisms, restated types, merges that should not have happened. |
290
+ | | Dead code | `dead-code` | Code, settings, routes, events, tables and assets that look live and never run. |
291
+ | | Slop | `slop` | Every switched-off check: disabled lint rules, casts that hide type errors, skipped tests, config opt-outs. |
292
+ | | Documentation | `documentation` | Docs that disagree with the code, links that land nowhere, facts agents rely on that nobody wrote down. |
293
+ | | Dependencies | `dependencies` | Pending dependency updates merged as one verified batch; security advisories, licences, end-of-life packages, supply-chain settings. |
297
294
  | **Tests and CI** | Testing | `testing` | Tests that can't fail, don't run, or skip what the product must and must never do. |
298
- | | Coverage | `coverage` | How much code the tests reach, against the minimum CI enforces, and the next minimum to set. |
299
- | | Flaky tests | `flakes` | Tests that pass only on retry or fail on one platform, and the change that makes each one reliable. |
300
- | | Gates | `gates` | Problems audits keep finding by hand that an automatic check could block, and the order to add those checks. |
301
- | | Annotations | `annotations` | Warnings buried in green CI runs: silent failures, deprecations with a deadline, ignored lint warnings. |
302
- | | CI performance | `ci-performance` | The lane that makes CI slow or expensive, and what each change would save. |
295
+ | | Coverage | `coverage` | How much code the tests reach, against the minimum CI enforces, and the next minimum to set. |
296
+ | | Flaky tests | `flakes` | Tests that pass only on retry or fail on one platform, and the change that makes each one reliable. |
297
+ | | Gates | `gates` | Problems audits keep finding by hand that an automatic check could block, and the order to add those checks. |
298
+ | | Annotations | `annotations` | Warnings buried in green CI runs: silent failures, deprecations with a deadline, ignored lint warnings. |
299
+ | | CI performance | `ci-performance` | The lane that makes CI slow or expensive, and what each change would save. |
303
300
  | **Running in production** | Reliability | `reliability` | What breaks when a service is slow, down or answers twice: missing timeouts, unsafe retries, races, failures no alert reports. |
304
- | | Database | `database` | Who can read and write what, migrations, data integrity, capacity, and whether a restore works. |
305
- | | Logs | `logs` | Error-tracker issues and logs sorted into real bugs, noise at the wrong level, and failures that never got reported. |
306
- | | App performance | `app-performance` | Web, phone and server speed, measured against published targets and your own budgets. |
307
- | | Config | `config` | Settings outside the code that disagree across environments, dashboards, repo and docs; anything with an expiry date. |
308
- | | Cost | `cost` | Vendor plans that don't fit your usage, what drives each bill, whether a spike shows up before the invoice. |
301
+ | | Database | `database` | Who can read and write what, migrations, data integrity, capacity, and whether a restore works. |
302
+ | | Logs | `logs` | Error-tracker issues and logs sorted into real bugs, noise at the wrong level, and failures that never got reported. |
303
+ | | App performance | `app-performance` | Web, phone and server speed, measured against published targets and your own budgets. |
304
+ | | Config | `config` | Settings outside the code that disagree across environments, dashboards, repo and docs; anything with an expiry date. |
305
+ | | Cost | `cost` | Vendor plans that don't fit your usage, what drives each bill, whether a spike shows up before the invoice. |
309
306
  | **Users and reach** | Accessibility | `accessibility` | What automated accessibility checks miss against WCAG 2.2 AA, plus the manual checks nothing automates. |
310
- | | Usability | `usability` | Screens that don't match their design or the other platforms, and main flows a person can't finish. |
311
- | | Analytics | `analytics` | Product events that don't fire, differ between web and phone, fire before consent, or carry personal data. |
312
- | | AI search & SEO | `aio-seo` | Whether search engines and AI answer engines can find, read and describe your public pages. |
313
- | | App Store | `app-store` | What keeps an iOS or Android app listed: deadlines, privacy declarations, permissions, signing, review readiness, crashes, ratings. |
307
+ | | Usability | `usability` | Screens that don't match their design or the other platforms, and main flows a person can't finish. |
308
+ | | Analytics | `analytics` | Product events that don't fire, differ between web and phone, fire before consent, or carry personal data. |
309
+ | | AI search & SEO | `aio-seo` | Whether search engines and AI answer engines can find, read and describe your public pages. |
310
+ | | App Store | `app-store` | What keeps an iOS or Android app listed: deadlines, privacy declarations, permissions, signing, review readiness, crashes, ratings. |
314
311
  | **AI features** | LLM | `llm` | What each AI model call can make happen, and what stops it when the input is hostile: prompts, tool limits, output checks, evals. |
315
- | | Models | `models` | Whether each AI call uses the best current model for the job, whether models and fallbacks still exist, whether one list holds them all. |
316
- | | Prompts | `prompts` | Product prompts that are unclear, badly structured, or off the model maker's current guide. |
312
+ | | Models | `models` | Whether each AI call uses the best current model for the job, whether models and fallbacks still exist, whether one list holds them all. |
313
+ | | Prompts | `prompts` | Product prompts that are unclear, badly structured, or off the model maker's current guide. |
317
314
  | **Project upkeep** | Issues | `issues` | Size and priority for every open issue, by rules a later run applies the same way; board, parent, milestone and blocking links. |
318
- | | Deferrals | `deferrals` | Postponed work sorted into done, replaced, tracked, parked, or in scope and never finished. |
319
- | | Failures | `failures` | Known bugs sorted into still reachable, already fixed, misdescribed, unconfirmed, or a repeat of an earlier one. |
320
- | | Repo | `repo` | Leftovers and layout: stale worktrees, branches and stashes, ignored files, files in the wrong place. |
321
- | | Agents | `agents` | Each AI tool's setup: which instructions load, permissions, hooks, tool servers, model choices, untrusted input each agent reads. |
322
- | | Adoption | `adoption` | Whether every file bkit installed is used and used correctly: install current, docs filled in, audits run on schedule, each template adopted or declined with a reason. |
315
+ | | Deferrals | `deferrals` | Postponed work sorted into done, replaced, tracked, parked, or in scope and never finished. |
316
+ | | Failures | `failures` | Known bugs sorted into still reachable, already fixed, misdescribed, unconfirmed, or a repeat of an earlier one. |
317
+ | | Repo | `repo` | Leftovers and layout: stale worktrees, branches and stashes, ignored files, files in the wrong place. |
318
+ | | Agents | `agents` | Each AI tool's setup: which instructions load, permissions, hooks, tool servers, model choices, untrusted input each agent reads. |
319
+ | | Adoption | `adoption` | Whether every file bkit installed is used and used correctly: install current, docs filled in, audits run on schedule, each template adopted or declined with a reason. |
323
320
 
324
- Agent-facing scope per template: `.bkit/prompts.md` § Audit (Ad-hoc).
321
+ The agent-facing scope of each template is in `.bkit/prompts.md` § Audit (Ad-hoc).
325
322
 
326
323
  <a id="utilities"></a>
327
324
 
328
325
  ## Utilities
329
326
 
330
- No command and no phase label. Run on demand, one subagent per run.
327
+ Utilities have no command and no phase label. They run on demand, one subagent per run.
331
328
 
332
329
  <!-- prettier-ignore -->
333
330
  | Subagent | Lens / focus | What it does |
@@ -335,13 +332,13 @@ No command and no phase label. Run on demand, one subagent per run.
335
332
  | `bkit-utility-update-roadmap` | Roadmap | Ranks the next items to work on from the board, the ledgers and due audits. Rewrites only the `roadmap-analysis` block. |
336
333
  | `bkit-utility-update-tracker` | Tracker hygiene | Brings open issues in line with the tracker rules: short titles, labels, board status, priority, size, milestone, parent and blocked-by, from the latest issues audit and the roadmap. Suggests new milestones and parent issues; never creates or closes issues. |
337
334
  | `bkit-utility-update-documentation` | Docs drift | Syncs every doc listed in `.agents/docs.md` with the current system — drift cleanup across several plans. |
338
- | `bkit-utility-update-decisions` | Decisions ledger | Checks each active `docs/decisions.jsonl` entry against the docs and the code; appends a corrected or superseded row where it no longer holds. |
335
+ | `bkit-utility-update-decisions` | Decisions ledger | Checks each active `docs/decisions.jsonl` entry against the docs and the code; appends a corrected or superseded row where it no longer holds. Lists rows in the other three ledgers that point at a corrected entry, for the caller to hand on. Never writes another ledger. |
339
336
  | `bkit-utility-update-knowledge` | Gotchas ledger | Same over `docs/knowledge.jsonl`. Never retracts an entry about upstream behaviour for lack of local evidence. |
340
- | `bkit-utility-update-deferrals` | Deferrals ledger | Closes `docs/deferrals.jsonl` entries the code already resolves, with evidence. An entry an open tracker issue covers is marked triaged, not closed. |
337
+ | `bkit-utility-update-deferrals` | Deferrals ledger | Closes `docs/deferrals.jsonl` entries the code already resolves, with evidence. An entry an open tracker issue covers is marked triaged, not closed. Same cross-ledger listing. |
341
338
  | `bkit-utility-update-failures` | Failures ledger | Same over `docs/failures.jsonl`, judged on whether the bug still reproduces from the code. A flaky entry closes only on a landed determinism fix. |
342
339
  | `bkit-utility-compress-markdown` | Compressor | Rewrites one markdown file in fewer tokens without changing its meaning. Overwrites the file. |
343
340
 
344
- Agent-facing scope per utility: `.bkit/prompts.md` § Utility (Ad-hoc).
341
+ The agent-facing scope of each utility is in `.bkit/prompts.md` § Utility (Ad-hoc).
345
342
 
346
343
  ---
347
344