@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
@@ -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 (39 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,24 +49,24 @@ 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)
60
+ 8. organise (workstreams + DAG, grouped into plans: the filed unit)
62
61
  9. summary (engine-written from status rows, tracker-facing)
63
62
 
64
63
  /bkit-plan ───── output: detailed plan ───────────────────────────────────────
65
- 1. generate plan (groups within bkit.workflows.tasks caps, in build order;
64
+ 1. generate plan (task groups within bkit.workflows.tasks caps, in build order;
66
65
  engine plan-check right after, one fix retry)
67
66
  2. fetch context (tracker: related issues; ledgers: prior deferrals,
68
67
  prior failures, strongest term-overlap first, top 40
69
68
  → feeds all three reviewers below)
70
- 3. review × 2 + scope-check (parallel, one round, distinct lenses)
69
+ 3. review x 2 + scope-check (parallel, one round, distinct lenses)
71
70
  • plan text: tightness, dependency order • code: regression risk
72
71
  • scope check: template, criteria, verification
73
72
  4. update plan (merge all three in one pass, max-wins on CRITICAL;
@@ -80,74 +79,69 @@ Each phase lists subagents in execution order. "Parallel" = same-time run, merge
80
79
  (from the prompt, issue and any plan; where they disagree, the newer text wins)
81
80
  2. plan-current (plan still executable against code landed since it was written?)
82
81
  3. install-skills
83
- ┌ per plan group, in order ─────────────────────────────────────────────
82
+ ┌ per task group, in order ─────────────────────────────────────────────
84
83
  │ 4. brief (engine: the group's open tasks + plan context)
85
- │ 5. execute group (producer — implement the group's tasks, reds first;
86
- │ turn cap near → HANDOVER, re-run once)
87
- │ 6. verify group (critic — the group's own diff; tick only on confirmed artifacts)
88
- │ ↶ producer-critic loop, capped 3 attempts;
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;
89
88
  │ unfixable gaps / no progress → Decision Pause (human, in session)
90
89
  │ 7. gaps-remediate (fix verifier gaps, re-verify)
91
- └ group gate between groups ─────────────────────────────────────────────
90
+ └ group gate between groups (static + unit) ─────────────────────────────
92
91
  8. verify build (holistic second pass across whole plan, once)
93
92
  9. challenge (size gate first: under 300 lines and 10 files → security only;
94
93
  else both in parallel, distinct lenses, no sibling reads)
95
94
  • bug-hunting (large changes) • security (always)
96
95
  10. challenge merge (engine: findings become plan tasks, each with a test first;
97
96
  a repeated finding reopens its open task; LOW → deferred;
98
- fixable → back to the group loop, once; unfixable or a
99
- second round's findings → Decision Pause; two rounds at most)
100
- 11. run tests (local tier: lint + typecheck + unit + slop:delta + bkit check;
101
- no integration / e2e / @live — those run in CI)
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)
102
101
  ↳ on test failure → /bkit-debug (debug-failure-diagnose + remediate)
103
102
  12. summary (engine-written from status rows + plan tasks, tracker-facing;
104
103
  no plan file or an unticked task → FAIL)
105
- → PR opened; CI runs the full multi-tier scaffold (see "CI test scaffold" below)
104
+ → publish=true: PR opened; CI runs the adopted scaffold below
105
+ publish=false on a local run: worktree retained, no push or PR
106
106
 
107
107
  /bkit-debug ─── side-rail, invoked on test/CI failure ────────────────────────
108
- 1. run tests (broader tier than build: lint + typecheck + unit
109
- + integration + e2e + optional @live canary —
110
- reproduces against the deployed boundary)
111
- 2. fetch context (only if tests FAIL; CI: failed jobs/steps + error
112
- annotations + failed-step logs; e2e test reports; local
113
- test output; diff vs last-passing CI; runtime logs via
114
- context-fetch blocks; tracker: related issues by error
115
- signature → feeds diagnose below)
116
- [repro] (first run passes — bug not reproduced yet):
117
- 2. fetch context, then reproduce (tests that fail on the reported
118
- 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
119
113
  Normal mode (localisable failure):
120
114
  3. diagnose (reads docs/knowledge.jsonl for prior failures;
121
115
  Standard → Pivot → Final strategy escalation)
122
116
  4. remediate (apply diagnosis fix)
123
117
  5. re-run tests
124
118
  6. summary (engine-written from status rows)
125
- ↳ if diagnose can't localise, or loop exhausts 3 strategies → Soak mode
119
+ ↳ if diagnose can't localise, or configured fix limit is used → Soak mode
126
120
  Soak mode (non-localisable / runtime-only failure):
127
121
  1. soak loop (one accumulating context per iteration:
128
122
  instrument OR smallest evidence-backed fix;
129
- 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
130
126
  Escape hatch:
131
127
  abort-handover (unrecoverable failure → human handover doc + stop)
132
128
 
133
129
  /bkit-ship ─── output: squash-merged PR, hard stop before main ──────────────
134
- 1. conflict-resolve (only if rebase sentinels exist)
130
+ 1. integrate dev (local merge when behind; resolve remaining conflicts)
135
131
  2. deferred-sweep (pre-merge completeness gate; FAIL blocks merge)
136
- 3. run tests (wait for CI on squash-merge SHA; bkit-tests-check
137
- must be green — every planned tier ran and passed;
138
- a planned bkit-tests-live-web failure reds it)
139
- 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)
140
135
  ↳ on post-merge failure → /bkit-debug (diagnose + remediate)
141
- 5. update-docs, then summary (engine-written, with PR size)
142
- 6. prune skills + update local dev + close (orchestrator-only;
143
- 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)
144
138
  ```
145
139
 
146
140
  <a id="ci-scaffold"></a>
147
141
 
148
142
  ## CI test scaffold (runs on every PR + push)
149
143
 
150
- 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.
151
145
 
152
146
  ```
153
147
  bkit-tests-static (typecheck, lint, format, prose lint, slop, actionlint, bkit check)
@@ -157,36 +151,36 @@ bkit-tests-unit (unit tests; writes the executed-test count)
157
151
  bkit-tests-check (capstone: needs both lanes; sole required check)
158
152
  ```
159
153
 
160
- 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`.
161
155
 
162
- 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.
163
157
 
164
- 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.
165
159
 
166
160
  <a id="bkit-design"></a>
167
161
 
168
162
  ## Phase 1 — `/bkit-design`
169
163
 
170
- 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.
171
165
 
172
166
  <!-- prettier-ignore -->
173
167
  | Subagent | Lens / focus | What it does |
174
168
  | --- | --- | --- |
175
- | `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. |
176
170
  | `bkit-design-brainstorm-ideate-2` | Optimal-tradeoff | Same task, different lens, on a different model from its siblings. |
177
171
  | `bkit-design-brainstorm-ideate-3` | Risk / pre-mortem | Same task, failure-mode lens. |
178
172
  | `bkit-design-generate` | Synthesiser | Merges three brainstorms into one design. Merges across lenses rather than collapsing to consensus. |
179
173
  | `bkit-design-review-1` | Feasibility (web) | Adversarial review with live web search; checks ecosystem feasibility per capability. |
180
- | `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. |
181
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. |
182
176
  | `bkit-design-update` | Apply review | Folds both reviews (and the spike, if run) back into the design. |
183
- | `bkit-design-organise` | Structure | Cleans and organises the final design doc. |
177
+ | `bkit-design-organise` | Structure | Splits the reviewed design into dependency-annotated workstreams and plans. |
184
178
 
185
179
  <a id="bkit-plan"></a>
186
180
 
187
181
  ## Phase 2 — `/bkit-plan`
188
182
 
189
- Output: executable plan (`{FID}-plan.md`, its tasks in groups the build runs one at a time). 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.
190
184
 
191
185
  <!-- prettier-ignore -->
192
186
  | Subagent | Lens / focus | What it does |
@@ -194,44 +188,50 @@ Output: executable plan (`{FID}-plan.md`, its tasks in groups the build runs one
194
188
  | `bkit-plan-generate` | Generate | Turns the design into groups of task blocks, in build order. |
195
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. |
196
190
  | `bkit-plan-review-2` | Regression-risk | Same scope, reads the code: traces each task's surfaces to their consumers. Parallel. |
197
- | `bkit-plan-scope-check` | Internal-completeness | Mechanical scope audit — verifies template structure, scope and verification per task; per-task `DONE WHEN` / `TEST FIRST` belong to `bkit tests plan-check`. Depth-sensitive: stays on the top model tier. 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. |
198
192
  | `bkit-plan-update` | Apply review (merge) | Merges all three critiques in one pass, max-wins on CRITICAL findings. |
199
193
 
200
194
  <a id="bkit-build"></a>
201
195
 
202
196
  ## Phase 3 — `/bkit-build`
203
197
 
204
- 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.
205
199
 
206
200
  <!-- prettier-ignore -->
207
201
  | Subagent | Lens / focus | What it does |
208
202
  | --- | --- | --- |
209
- | `bkit-build-plan-convert` | Plan writer | 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. |
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. |
210
204
  | `bkit-build-plan-current` | Plan freshness | Judges whether changes landed since the plan was written leave it executable; findings feed execute. |
211
205
  | `bkit-build-install-skills` | Setup | Installs the skills the plan needs for this build. |
212
- | `bkit-build-plan-execute` | Producer | Implements one plan group's tasks from its brief, each task's tests seen failing first; iterates edit → lint/typecheck/test → edit. Near its turn cap it hands over (`HANDOVER`) and the group re-runs once. |
213
- | `bkit-build-plan-verify` | Critic | Verifies each task of one group against the group's own diff; ticks boxes only on confirmed artifacts. Producer-critic loop, capped at 3 attempts per group. |
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. |
214
209
  | `bkit-build-plan-gaps-remediate` | Gap-fixer | Fills gaps the verifier found, then re-verifies. |
215
210
  | `bkit-build-plan-verify` | Holistic critic | Second, whole-of-plan verification pass across everything built. |
216
- | `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 one runs `-2` alone. `bkit challenge merge` then appends the findings to the plan, and execute + verify fix them. |
217
- | `bkit-build-challenge-2` | Security | Same diff, security lens. Depth-sensitive: stays on the top model tier. Runs on every change, alone on a small one. |
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. |
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. |
220
215
 
221
216
  <a id="bkit-debug"></a>
222
217
 
223
218
  ## Phase 4 — `/bkit-debug`
224
219
 
225
- 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:
226
221
 
227
- **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.
228
228
 
229
229
  **Normal mode**
230
230
 
231
231
  <!-- prettier-ignore -->
232
232
  | Subagent | Lens / focus | What it does |
233
233
  | --- | --- | --- |
234
- | `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. |
235
235
  | `bkit-debug-failure-diagnose` | Diagnostician | Reproduces and diagnoses. Accumulates per-attempt context; escalates Standard → Pivot → Final. |
236
236
  | `bkit-debug-failure-remediate` | Fixer | Applies whatever the strategy-aware diagnosis produced, with a test loop. |
237
237
 
@@ -240,7 +240,7 @@ Output: remediated commit on feature branch. Two modes — normal (diagnose →
240
240
  <!-- prettier-ignore -->
241
241
  | Subagent | Lens / focus | What it does |
242
242
  | --- | --- | --- |
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` (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). |
244
244
 
245
245
  **Escape hatch**
246
246
 
@@ -253,78 +253,78 @@ Output: remediated commit on feature branch. Two modes — normal (diagnose →
253
253
 
254
254
  ## Phase 5 — `/bkit-ship`
255
255
 
256
- 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.
257
257
 
258
258
  <!-- prettier-ignore -->
259
259
  | Subagent | Lens / focus | What it does |
260
260
  | --- | --- | --- |
261
- | `bkit-ship-conflict-resolve` | Conflict resolver | Resolves merge conflicts against the integration branch, then runs the tests. |
262
- | `bkit-ship-deferred-sweep` | Pre-merge completeness gate | Builds the intended-delivery set from plan `Acceptance Scenario` sections + `DONE WHEN` fields; 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. |
263
- | `bkit-debug-failure-diagnose` | Diagnostician | (If post-merge checks fail) diagnoses the regression. Shared with debug. |
264
- | `bkit-debug-failure-remediate` | Fixer | (If post-merge checks fail) applies the fix. |
265
- | `bkit-ship-update-docs` | Docs | Updates knowledge / decisions / completed 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. |
266
266
 
267
- 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.
268
268
 
269
269
  ## Audits
270
270
 
271
- 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.
272
272
 
273
273
  <!-- prettier-ignore -->
274
274
  | Subagent | Lens / focus | What it does |
275
275
  | --- | --- | --- |
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`). 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. |
277
277
 
278
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.
279
279
 
280
- 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`.
281
281
 
282
282
  <!-- prettier-ignore -->
283
283
  | Area | Audit | Template | What it finds |
284
284
  | --- | --- | --- | --- |
285
285
  | **Security and privacy** | Security | `security` | Holes in sign-in, permissions, secrets and input checks, plus documented protections that never run. |
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. |
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. |
288
288
  | **Code quality** | Architecture | `architecture` | Code that breaks the intended layers: server code reaching the client, modules tied together with no visible import. |
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. |
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. |
294
294
  | **Tests and CI** | Testing | `testing` | Tests that can't fail, don't run, or skip what the product must and must never do. |
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. |
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. |
300
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. |
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. |
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. |
306
306
  | **Users and reach** | Accessibility | `accessibility` | What automated accessibility checks miss against WCAG 2.2 AA, plus the manual checks nothing automates. |
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. |
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. |
311
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. |
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. |
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. |
314
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. |
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. |
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. |
320
320
 
321
- 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).
322
322
 
323
323
  <a id="utilities"></a>
324
324
 
325
325
  ## Utilities
326
326
 
327
- 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.
328
328
 
329
329
  <!-- prettier-ignore -->
330
330
  | Subagent | Lens / focus | What it does |
@@ -332,13 +332,13 @@ No command and no phase label. Run on demand, one subagent per run.
332
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. |
333
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. |
334
334
  | `bkit-utility-update-documentation` | Docs drift | Syncs every doc listed in `.agents/docs.md` with the current system — drift cleanup across several plans. |
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. |
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. |
336
336
  | `bkit-utility-update-knowledge` | Gotchas ledger | Same over `docs/knowledge.jsonl`. Never retracts an entry about upstream behaviour for lack of local evidence. |
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. |
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. |
338
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. |
339
339
  | `bkit-utility-compress-markdown` | Compressor | Rewrites one markdown file in fewer tokens without changing its meaning. Overwrites the file. |
340
340
 
341
- 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).
342
342
 
343
343
  ---
344
344