@cbartens/bkit 6.1.1 → 6.2.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 (313) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +42 -32
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -40,7 +40,7 @@ autoCompactWindow: 300000 # Claude-only compaction window; plain integer (`300k`
40
40
  | `low` | `claude-haiku-5-5` | Default Haiku rung. No agent pins Haiku; the tier stays available, with its per-provider pins in § Models (`low` → `high` buys +11.4 CursorBench points for $0.24/task). |
41
41
  | `medium` | `claude-sonnet-5-5` | Source modifiers with test loops, single-shot writers, scope audits, light utilities (Anthropic: `medium` for well-specified agentic tasks, `high` for harder or longer ones — a plan task or a diagnosis is well specified). Multi-doc writers pin `claude-sonnet-5-5` at `high`. |
42
42
  | `high` | `claude-opus-5-5` | Synthesizers, adversarial review, diagnosis. Highest rung any agent runs at. 1M context. |
43
- | `xhigh` | `claude-opus-5-5` | Reserved: no agent runs here. Same model ID as `high`, and differs by the `effort: xhigh` thinking-budget allocation. Escalate from `high` only on a measured quality gain (Anthropic: reserve `xhigh` and `max` for work where you've measured one). |
43
+ | `xhigh` | `claude-opus-5-5` | Reviewers and the debug escalation step (`bkit-debug-failure-soak`): `bkit-design-review-1`, `bkit-design-review-2` (pins `claude-sonnet-5-5`), `bkit-plan-review-1`, `bkit-plan-review-2`, `bkit-build-plan-current`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-ship-deferred-sweep`, `bkit-debug-failure-soak`. Same model ID as `high`, and differs by the `effort: xhigh` thinking-budget allocation. |
44
44
  | `max` | `claude-opus-5-5` | Same model as `xhigh`, and differs by the `effort: max` thinking-budget allocation. Reserved tier: escalate from `xhigh` only after observed truncation. |
45
45
 
46
46
  **Fable — not pinned.** `claude-fable-5-1` is the tier above Opus 5.5 ($10/$50 against $4/$20). Cursor Cloud lists `claude-fable-5-thinking-high`/`-xhigh`. No bkit agent pins Fable, and `max` stays on `claude-opus-5-5`.
@@ -75,7 +75,7 @@ Pinning `model:` locks an agent's model, whatever model the orchestrator session
75
75
 
76
76
  Subscription hosts keep the eager mapping, because on a plan you already paid for, spending the reasoning budget is the point.
77
77
 
78
- **`Google` is one model, many effort levels.** Antigravity pins `gemini-4-argon` on all 40 agents. The per-agent `effort` is the only dial, because Google's catalogue offers no rung between argon (61.2) and `gemini-3.8-flash` (16.5). Argon exposes `low/medium/high`, so an `xhigh`/`max` agent clamps to `high`. No agent uses those tiers today.
78
+ **`Google` is one model, many effort levels.** Antigravity pins `gemini-4-argon` on all 40 agents. The per-agent `effort` is the only dial, because Google's catalogue offers no rung between argon (61.2) and `gemini-3.8-flash` (16.5). Argon exposes `low/medium/high`, so an `xhigh`/`max` agent clamps to `high`.
79
79
 
80
80
  ### Field rationale
81
81
 
@@ -84,7 +84,7 @@ Subscription hosts keep the eager mapping, because on a plan you already paid fo
84
84
  | --- | --- | --- |
85
85
  | `name` | `@name` invocation in `commands/*.md` requires exact match | Never deviate. |
86
86
  | `description` | Surfaces in the picker and the `Agent` tool catalog. A one-sentence scope statement only: the H1 inside the markdown body carries the deliverable name (`# Build Skills Installed`, `# Plan Review`, etc.). | Keep it terse, and never duplicate the H1. |
87
- | `effort` | Maps to a Claude model via the table above, with two groups pinning opus at `medium` effort — a depth-sensitive lens (`bkit-plan-scope-check`) and the ledger / tracker agents that check entries against the codebase — and multi-doc writers pinning sonnet at `high`. Parallel fan-outs (triplet `-1`/`-2`/`-3` for ideate; pairs `-1`/`-2` for design review / plan review / challenge) mix `high`/`medium` effort to spread reasoning depth on Claude. On Cursor, the same fan-outs use different `model:` values for cross-family diversity. | `high` for adversarial / generative / diagnostic / cross-codebase work and multi-doc writers. `medium` for source modifiers with test loops and ledger upkeep. `xhigh` only on a measured quality gain. |
87
+ | `effort` | Maps to a Claude model via the table above, with two groups pinning opus at `medium` effort — a depth-sensitive lens (`bkit-plan-scope-check`) and the ledger / tracker agents that check entries against the codebase — and multi-doc writers pinning sonnet at `high`. Parallel fan-outs differ by model on Claude (`bkit-design-brainstorm-ideate-2` and `bkit-design-review-2` pin Sonnet, their siblings Opus), not by effort. On Cursor, the same fan-outs use different `model:` values for cross-family diversity. | By role: `high` for design and plan writers, plan conversion, per-group verify, debug first attempt and multi-doc writers. `xhigh` for reviewers and the debug escalation step. `medium` for agents that do the work (tests, code, fixes, conflicts) and ledger upkeep. |
88
88
  | `model` | Explicit Claude model pin, per the effort mapping table above. It locks the model whatever the orchestrator's session default is. Without it, subagents inherit the user's Claude default, and Opus thinking depth and 1M context disappear if the user runs Sonnet. | Brittle by version, because it needs an update on every model revision, but explicit and discoverable. Never use a family alias (`opus` / `sonnet`), because an alias does not lock the context-window variant. |
89
89
  | `tools` | Minimum capability sandbox. Enforced on Claude (native). Cursor: `bkit install` T3 transform passes the field through verbatim, but Cursor CLI 2026.10.01 does not enforce it (measured: a `tools: [Read]` subagent still has `Shell`, `Write`, `StrReplace`, and every MCP tool via `CallDynamicTool`). Removing `Edit`/`Bash` makes an agent provably non-mutating on Claude only. | Add `WebFetch`/`WebSearch` only for genuine ecosystem research (`bkit-design-review-1/2`) or to pin a probe against vendor docs before running it (`bkit-design-spike`). |
90
90
  | `permissionMode: acceptEdits` | End-to-end runs of `/design`/`/plan`/`/build`/`/debug`/`/ship` would break if a mid-workflow prompt blocked an agent. The Bash auto-approve surface lives in `.claude/settings.json` (`workflows.md` § Permissions). | Never deviate inside the pipeline. One-off ad-hoc invocations may use stricter modes. |
@@ -97,9 +97,9 @@ Subscription hosts keep the eager mapping, because on a plan you already paid fo
97
97
  | Tier | Use for | Example agents |
98
98
  | --- | --- | --- |
99
99
  | `low` | Pure synthesis with no verdict riding on it. | (none currently) |
100
- | `medium` | Source modifiers with test loops — implementers and fix executors (sonnet model) — single-shot writers, scope audits, skill curators, and ledger / tracker / roadmap upkeep against the codebase (opus model). | `bkit-design-brainstorm-ideate-2`, `bkit-design-review-2`, `bkit-plan-scope-check`, `bkit-build-plan-convert`, `bkit-build-plan-tests`, `bkit-build-plan-tasks`, `bkit-build-plan-gaps-remediate`, `bkit-build-install-skills`, `bkit-debug-failure-remediate`, `bkit-debug-abort-handover`, `bkit-ship-conflict-resolve`, `bkit-utility-compress-markdown`, `bkit-utility-update-deferrals`, `bkit-utility-update-failures`, `bkit-utility-update-decisions`, `bkit-utility-update-knowledge`, `bkit-utility-update-roadmap`, `bkit-utility-update-tracker` |
101
- | `high` | Top-of-pipeline synthesizers and their critique mergers, adversarial review, parallel-fan-out high-effort slots, failure diagnosis, observability instrumentation, feasibility research, audits, and multi-doc writers (sonnet model). | `bkit-design-brainstorm-ideate-1`, `bkit-design-brainstorm-ideate-3`, `bkit-design-generate`, `bkit-design-update`, `bkit-design-review-1`, `bkit-design-spike`, `bkit-design-organise`, `bkit-plan-generate`, `bkit-plan-update`, `bkit-plan-review-1`, `bkit-plan-review-2`, `bkit-build-plan-current`, `bkit-build-plan-verify`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-soak`, `bkit-debug-failure-reproduce`, `bkit-ship-deferred-sweep`, `bkit-ship-update-docs`, `bkit-audit-generate`, `bkit-utility-update-documentation` |
102
- | `xhigh` | Reserved — only on a measured quality gain over `high` for a recurring failure mode. Model-gated (Opus-only on current models). A stuck bug goes to Fable by hand (§ Orchestrators), not to an `xhigh` agent. | (none currently) |
100
+ | `medium` | Agents that do the work from a plan a reviewer has passed, with tests checking them: implementers and fix executors (sonnet model), plus the scope audit, skill curator, and ledger / tracker / roadmap upkeep against the codebase (opus model). | `bkit-plan-scope-check`, `bkit-build-plan-tests`, `bkit-build-plan-tasks`, `bkit-build-plan-gaps-remediate`, `bkit-build-install-skills`, `bkit-debug-failure-remediate`, `bkit-debug-abort-handover`, `bkit-ship-conflict-resolve`, `bkit-utility-compress-markdown`, `bkit-utility-update-deferrals`, `bkit-utility-update-failures`, `bkit-utility-update-decisions`, `bkit-utility-update-knowledge`, `bkit-utility-update-roadmap`, `bkit-utility-update-tracker` |
101
+ | `high` | Design and plan writers (two reviewers check their output), plan conversion (nothing reviews a plan converted at build start), the per-group plan verify (the plan it checks has passed two `xhigh` reviews and the engine records each planned test failing then passing), debug first attempt (diagnose, reproduce), instrumentation, feasibility research, audits, and multi-doc writers (sonnet model). | `bkit-design-brainstorm-ideate-1`, `bkit-design-brainstorm-ideate-2`, `bkit-design-brainstorm-ideate-3`, `bkit-build-plan-convert`, `bkit-design-generate`, `bkit-design-update`, `bkit-design-spike`, `bkit-design-organise`, `bkit-plan-generate`, `bkit-plan-update`, `bkit-build-plan-verify`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-reproduce`, `bkit-ship-update-docs`, `bkit-audit-generate`, `bkit-utility-update-documentation` |
102
+ | `xhigh` | Reviewers, because nothing checks the checker, and the debug escalation step (soak runs when diagnose could not find where the bug is, when fix attempts are used up, or when the run is tagged `[soak]`). Debug is a ladder: `high`, then `xhigh`, then Fable by hand (§ Orchestrators). `bkit-build-plan-verify` stays `high`. Claude accepts `xhigh` on Opus and Sonnet. | `bkit-design-review-1`, `bkit-design-review-2`, `bkit-plan-review-1`, `bkit-plan-review-2`, `bkit-build-plan-current`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-ship-deferred-sweep`, `bkit-debug-failure-soak` |
103
103
  | `max` | Reserved — only if `xhigh` proves insufficient on a recurring failure mode. Costliest tier; one-shot orchestrator-level work only. Lazy-escalate from `xhigh` based on observed truncation, never preemptively. | (none currently) |
104
104
 
105
105
  ### Tool set patterns
@@ -154,9 +154,9 @@ Canonical per-agent metadata, and the single source of truth for each agent's mo
154
154
 
155
155
  **Cells = bare provider-scoped model ID** (`deepseek-v4.1-flash`, `moonshotai/kimi-k3`), never with a provider prefix. `formatModelPin` adds the host-format prefixes at render, and also maps the key `opencode-zen` → OpenCode's own id `opencode`. A prefixed cell (`opencode/deepseek-v4.1-flash`) gets a double prefix.
156
156
 
157
- > **`OpenAI` column — provisional, not parity-proven.** Every other gateway column = a live catalog probe plus a per-model tool-calling smoke test. The `OpenAI` cells follow value inside the plan: `gpt-6-astra` (77.5) only on the 12 judges (Judges note below), and `gpt-6.1-sol` (68.7) on the 27 builders. Sol scores 96.0 Coding against astra's 93.7, so on code-writing agents it is both the better model and 5.9x cheaper per LiveBench task ($116.78 against $690.82). `gpt-6-luna` (30.9, $17.42/task) is the catalog's best value, and stays unused until a haiku tier exists. `gpt-6-astra` is OpenAI's opus analogue, not its fable: it costs the same $691 per task as `claude-opus-5.5`'s $684, for 77.5 against 72.8, and both sit at ~0.11 points per dollar. The fable-shaped tier (`gpt-daybreak-red`, $12.5/$75) is unmeasured on 2.0 and unpinned, exactly as `claude-fable-5.1` is unpinned on the Claude side. Re-pin from a real probe before relying on them.
157
+ > **`OpenAI` column — provisional, not parity-proven.** Every other gateway column = a live catalog probe that confirms each model exists; the per-model tool-calling smoke test has not been run on the current pins (§ Live model-ID verification). The `OpenAI` cells follow value inside the plan: `gpt-6-astra` (77.5) only on the 12 judges (Judges note below), and `gpt-6.1-sol` (68.7) on the 28 builders. Sol scores 96.0 Coding against astra's 93.7, so on code-writing agents it is both the better model and 5.9x cheaper per LiveBench task ($116.78 against $690.82). `gpt-6-luna` (30.9, $17.42/task) is the catalog's best value, and stays unused until a haiku tier exists. `gpt-6-astra` is OpenAI's opus analogue, not its fable: it costs the same $691 per task as `claude-opus-5.5`'s $684, for 77.5 against 72.8, and both sit at ~0.11 points per dollar. The fable-shaped tier (`gpt-daybreak-red`, $12.5/$75) is unmeasured on 2.0 and unpinned, exactly as `claude-fable-5.1` is unpinned on the Claude side. Re-pin from a real probe before relying on them.
158
158
 
159
- > **Haiku stays unpinned — deliberate.** `claude-haiku-5-5` is the cheapest Claude rung (40.0 Long Agentic, $188.84/task against opus's $684.16), and no agent runs it. The 17 medium-effort agents are not boilerplate: four are source modifiers with test loops, three are judges, six reconcile ledgers and the roadmap against the codebase, and the rest read a whole run before writing. Haiku's documented fit is a well-defined task, and a role prompt cannot promise that its input is well-defined. The quota dial is `Effort`, which is reversible per agent, and the model rung is not.
159
+ > **Haiku stays unpinned — deliberate.** `claude-haiku-5-5` is the cheapest Claude rung (40.0 Long Agentic, $188.84/task against opus's $684.16), and no agent runs it. The 15 medium-effort agents are not boilerplate: five are source modifiers with test loops, one is a scope audit, six reconcile ledgers and the roadmap against the codebase, and the rest read a whole run before writing. Haiku's documented fit is a well-defined task, and a role prompt cannot promise that its input is well-defined. The quota dial is `Effort`, which is reversible per agent, and the model rung is not.
160
160
 
161
161
  > **`Google` column — measured pin.** Every cell runs `gemini-4-argon`, which scores 61.2 Long Agentic on the 2.0 board and is served on the `google` provider (models.dev), so Antigravity's free tier and a Google subscription both reach it. `gemini-3.8-pro` is unmeasured on 2.0 and is not pinned, and `gemini-3.8-flash` 16.5 is not a candidate.
162
162
 
@@ -168,7 +168,7 @@ Canonical per-agent metadata, and the single source of truth for each agent's mo
168
168
  >
169
169
  > **Metered columns target the Claude bar; subscription columns spend the plan.** The OpenCode columns use Claude as the yardstick: each cell is the cheapest model closest to its tier's Claude bar (`providers.md` § Selecting pins). `Anthropic`, `OpenAI` and `Google` instead take each vendor's best value inside the plan. Any cell can be re-pinned.
170
170
  >
171
- > **Judges — 12 agents:** `bkit-design-brainstorm-ideate-3`, `bkit-design-review-1`, `bkit-plan-review-1`, `bkit-plan-review-2`, `bkit-plan-scope-check`, `bkit-build-plan-current`, `bkit-build-plan-verify`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-soak`, `bkit-ship-deferred-sweep`. They review, challenge, verify or escalate, and the other 27 are builders. **Key gates — 4 of the 12**, where a miss passes downstream unchecked: `bkit-build-plan-verify` (decides a build is done), `bkit-ship-deferred-sweep` (last check before merge), `bkit-debug-failure-diagnose` (a wrong root cause sends the fix loop after the wrong bug), `bkit-build-challenge-2` (a missed security finding ships).
171
+ > **Judges — 12 agents:** `bkit-design-brainstorm-ideate-3`, `bkit-design-review-1`, `bkit-plan-review-1`, `bkit-plan-review-2`, `bkit-plan-scope-check`, `bkit-build-plan-current`, `bkit-build-plan-verify`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-debug-failure-diagnose`, `bkit-debug-failure-soak`, `bkit-ship-deferred-sweep`. They review, challenge, verify or escalate, and the other 28 are builders. **Key gates — 4 of the 12**, where a miss passes downstream unchecked: `bkit-build-plan-verify` (decides a build is done), `bkit-ship-deferred-sweep` (last check before merge), `bkit-debug-failure-diagnose` (a wrong root cause sends the fix loop after the wrong bug), `bkit-build-challenge-2` (a missed security finding ships).
172
172
  >
173
173
  > **Per-tier quality targets; cheapest sufficient pin.** Each OpenCode cell is the cheapest model closest to its tier's Claude bar on LiveBench 2.0 Long Agentic: opus 72.8, sonnet 63.4 and haiku 40.0, the `claude-opus-5.5` / `claude-sonnet-5.5` / `claude-haiku-5.5` scores on the 2026-10-25 release (`providers.md` § LiveBench 2.0 board; process in § Selecting pins). A cell under its bar records the gap. **Any vendor may pin on an OpenCode column; cost is the limit** (`providers.md` § Budget band), and cost is what keeps Claude models off them.
174
174
  >
@@ -185,35 +185,35 @@ Canonical per-agent metadata, and the single source of truth for each agent's mo
185
185
  | Prompt | Anthropic | OpenAI | Google | Cursor | OpenRouter | Ollama | OpenCode Zen | OpenCode Go | Effort | Max Turns | Role |
186
186
  | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
187
187
  | `bkit-design-brainstorm-ideate-1` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | parallel slot 1 (pragmatic lens) |
188
- | `bkit-design-brainstorm-ideate-2` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | parallel slot 2 (optimal trade-off lens; Composer vs Grok siblings on Cursor; cross-tier on Claude) |
188
+ | `bkit-design-brainstorm-ideate-2` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | parallel slot 2 (optimal trade-off lens; Composer vs Grok siblings on Cursor; cross-tier on Claude) |
189
189
  | `bkit-design-brainstorm-ideate-3` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | parallel slot 3 (risk-premortem lens) |
190
190
  | `bkit-design-generate` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | generate design from brainstorms (top-of-pipeline synthesizer; whole-doc rewrite) |
191
- | `bkit-design-review-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | design review slot 1 (web search + feasibility analysis) |
192
- | `bkit-design-review-2` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | design review slot 2 (Composer vs Grok sibling on Cursor; cross-tier on Claude) |
191
+ | `bkit-design-review-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 100 | design review slot 1 (web search + feasibility analysis) |
192
+ | `bkit-design-review-2` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 100 | design review slot 2 (Composer vs Grok sibling on Cursor; cross-tier on Claude) |
193
193
  | `bkit-design-spike` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | settle review-named unknowns with throwaway probe code (conditional step) |
194
194
  | `bkit-design-update` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | merge review critiques into design (whole-doc rewrite — needs depth) |
195
195
  | `bkit-design-organise` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | decompose reviewed design into dependency-annotated workstreams grouped into plans; coverage self-verify + DAG cycle detection |
196
196
  | `bkit-plan-generate` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 400 | plan draft generator (top-of-pipeline synthesizer) |
197
- | `bkit-plan-review-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | review slot 1 (tightness + dependency order + design-coverage; reads the plan) |
198
- | `bkit-plan-review-2` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 100 | review slot 2 (regression-risk + design-coverage; reads the code) |
197
+ | `bkit-plan-review-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 100 | review slot 1 (tightness + dependency order + design-coverage; reads the plan) |
198
+ | `bkit-plan-review-2` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 100 | review slot 2 (regression-risk + design-coverage; reads the code) |
199
199
  | `bkit-plan-scope-check` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | scope audit (template, criteria, verification; mechanical audit — medium effort, depth-sensitive — opus) |
200
200
  | `bkit-plan-update` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | merge review + scope critiques into plan (whole-doc rewrite — needs depth) |
201
- | `bkit-build-plan-convert` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 50 | write an issue or a free-form plan as task blocks (single-doc writer with one check command) |
202
- | `bkit-build-plan-current` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | judge plan vs changes landed since its base commit |
201
+ | `bkit-build-plan-convert` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 50 | write an issue or a free-form plan as task blocks (single-doc writer with one check command) |
202
+ | `bkit-build-plan-current` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 200 | judge plan vs changes landed since its base commit |
203
203
  | `bkit-build-install-skills` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | installs matching skills under the registry's activation boundaries |
204
204
  | `bkit-build-plan-tests` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | writes one task group's planned tests before its code (test files only); uses the machine lock for shared services |
205
205
  | `bkit-build-plan-tasks` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | task executor for one task group (source modifier with test loop); uses the machine lock for shared services; re-runs tests-lock waits |
206
206
  | `bkit-build-plan-verify` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `high` | 100 | verify one group, or the whole plan once, vs the plan; re-runs tests-lock waits |
207
- | `bkit-build-plan-gaps-remediate` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | fix one group's verification gaps (source modifier with test loop); uses the machine lock for shared services; re-runs group-gate and changed-test lock waits |
208
- | `bkit-build-challenge-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | parallel slot 1 (bug-hunting lens) |
209
- | `bkit-build-challenge-2` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `high` | 200 | parallel slot 2 (security lens; depth-sensitive — both opus) |
207
+ | `bkit-build-plan-gaps-remediate` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | fix one group's, or the holistic pass's, verification gaps (source modifier with test loop); uses the machine lock for shared services; re-runs group-gate and changed-test lock waits |
208
+ | `bkit-build-challenge-1` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 200 | parallel slot 1 (bug-hunting lens) |
209
+ | `bkit-build-challenge-2` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `xhigh` | 200 | parallel slot 2 (security lens; depth-sensitive — both opus) |
210
210
  | `bkit-debug-failure-reproduce` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | failing tests from a bug report, no fix; opus over the sonnet test-writer tier — an off-symptom test sends the fix loop after the wrong bug |
211
211
  | `bkit-debug-failure-diagnose` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `high` | 200 | failure diagnosis (Final-strategy attempts especially benefit from depth before human handover) |
212
212
  | `bkit-debug-failure-remediate` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 200 | implement diagnosis fixes (source modifier with test loop); re-runs tests-lock waits |
213
- | `bkit-debug-failure-soak` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | soak fix — one accumulating-context instrument-or-fix step per iteration against the live boundary (orchestrator re-runs tests + loops) |
213
+ | `bkit-debug-failure-soak` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `xhigh` | 200 | soak fix — one accumulating-context instrument-or-fix step per iteration against the live boundary (orchestrator re-runs tests + loops) |
214
214
  | `bkit-debug-abort-handover` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 100 | handover writer |
215
215
  | `bkit-ship-conflict-resolve` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 200 | mechanical merge-conflict resolver (source modifier with test loop) |
216
- | `bkit-ship-deferred-sweep` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `high` | 200 | pre-merge completeness gate — intended-vs-actual + declared-deferral resurface |
216
+ | `bkit-ship-deferred-sweep` | `claude-opus-5-5` | `gpt-6-astra` | `gemini-4-argon` | `cursor-grok-4.5-high` | `openai/gpt-6.1-sol` | `deepseek-v4.1-flash:1017` | `gpt-6.1-sol` | `gemini-4-argon` | `xhigh` | 200 | pre-merge completeness gate — intended-vs-actual + declared-deferral resurface |
217
217
  | `bkit-ship-update-docs` | `claude-sonnet-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `composer-2.5` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 200 | sync cataloged docs (multi-doc writer) |
218
218
  | `bkit-audit-generate` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `high` | 400 | audit report from one template (top-of-pipeline synthesizer) |
219
219
  | `bkit-utility-update-deferrals` | `claude-opus-5-5` | `gpt-6.1-sol` | `gemini-4-argon` | `cursor-grok-4.5-high` | `deepseek/deepseek-v4.1-flash-1017` | `deepseek-v4.1-flash:1017` | `deepseek-v4.1-flash` | `deepseek-v4.1-flash` | `medium` | 400 | deferrals update |
@@ -289,7 +289,7 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
289
289
  | One repo | `"effortLevel": "<level>"` in `.claude/settings.local.json` (you only) or `.claude/settings.json` (whole team) — applies to every model, outranks `~/.claude/settings.json`. |
290
290
 
291
291
  - Never set `CLAUDE_CODE_EFFORT_LEVEL`, because it outranks subagent `effort:` frontmatter. Every subagent then runs at one level, and the § Effort tiers ladder is gone.
292
- - Never set `maxEffortLevel` below `high`, because it caps subagent `effort:` frontmatter. The `high` agents (§ Effort tiers) then run at the cap.
292
+ - Never set `maxEffortLevel` below `high`, because it caps subagent `effort:` frontmatter. The `high` and `xhigh` agents (§ Effort tiers) then run at the cap.
293
293
 
294
294
  **Codex session setup:** the orchestrator runs on the session model and effort. Subagents ignore both, because each `.codex/agents/*.toml` sets its own `model` and `model_reasoning_effort`.
295
295
 
@@ -304,13 +304,13 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
304
304
  | Agent | Scope |
305
305
  | --- | --- |
306
306
  | `bkit-design-brainstorm-ideate-1` | Independent design exploration — pragmatic lens; effort slot 1 (`high`). Runs parallel with `-2` and `-3`; writes `design-brainstorm-ideate-1.md`. Never references sibling output (circular reasoning guard). |
307
- | `bkit-design-brainstorm-ideate-2` | Same as `-1` — optimal trade-off lens; effort slot 2 (`medium`). Effort-diversity within the parallel triplet (Sonnet on Claude, Composer on Cursor vs Grok siblings). |
307
+ | `bkit-design-brainstorm-ideate-2` | Same as `-1` — optimal trade-off lens; effort slot 2 (`high`). Model diversity within the parallel triplet (Sonnet on Claude, Composer on Cursor vs Grok siblings). |
308
308
  | `bkit-design-brainstorm-ideate-3` | Same as `-1` — risk-premortem lens; effort slot 3 (`high`). Restores Opus depth for the failure-mode side of the brainstorm triplet. |
309
- | `bkit-design-generate` | Generate unified design draft from brainstorms and the design input; the input's `Grill decisions` section (design Step 3) holds the human's answers — `Settled` entries are strong pointers, not hard constraints — followed unless a brainstorm shows the answer fails; a departure gets a `Decisions` row and a `Risks & Open Questions` item asking the human to confirm. `Assumed, not confirmed` entries are defaults it may override with a stated reason; each `Open` entry becomes a `Risks & Open Questions` item. The section's `Draft Acceptance Scenario`, labelled `DRAFT only`, is the starting point for the design's `Acceptance Scenario`; every change to it gets a `Decisions` row, no confirmation item, because the human confirms the scenario again at the plan's `Acceptance Scenario confirmed` box. It reads the input directly because the ideate triplet may not carry every decision through. Emits `Reuse & Prior Art` (default `EXTEND`): duplication is cheapest to decide at design — net-new committed here is expensive to unwind at plan or build. Every net-new `Architecture` component traces to a `NEW` verdict; plan phase starts `Reuse Inventory` from it. Verdict only — sources, absence proof and rejected `NEW` reasons are checked by `bkit-design-review-1` and evidenced in the plan's `Search performed`. Appends `docs/deferrals.jsonl` if applicable. Does not write `docs/decisions.jsonl` — the design phase reads ADRs but never authors them (decisions land via debug remediation or build / ship doc-integration). Open questions in `Risks & Open Questions` are never bare — each carries 2-3 concrete options with trade-offs as the lettered `Options: A) {option} — {trade-off} · B) …`, a `Recommended` option and a `Default if unanswered`; the design phase states this requirement itself and does not read the plan template. |
309
+ | `bkit-design-generate` | Generate unified design draft from brainstorms and the design input; the input's `Grill decisions` section (design Step 3) holds the human's answers — `Settled` entries are strong pointers, not hard constraints — followed unless a brainstorm shows the answer fails; a departure gets a `Decisions` row and a `Risks & Open Questions` item asking the human to confirm. `Assumed, not confirmed` entries are defaults it may override with a stated reason; each `Open` entry becomes a `Risks & Open Questions` item. The section's `Draft Acceptance Scenario`, labelled `DRAFT only`, is the starting point for the design's `Acceptance Scenario`; every change to it gets a `Decisions` row, no confirmation item, because the human confirms the scenario again at the plan's `Acceptance Scenario confirmed` box. It reads the input directly because the ideate triplet may not carry every decision through. Emits `Reuse & Prior Art` (default `EXTEND`): duplication is cheapest to decide at design — net-new committed here is expensive to unwind at plan or build. Every net-new `Architecture` component traces to a `NEW` verdict; plan phase starts `Reuse Inventory` from it. Verdict only — sources, absence proof and rejected `NEW` reasons are checked by `bkit-design-review-1` and evidenced in the plan's `Search performed`. Appends `docs/deferrals.jsonl` if applicable. Does not write `docs/decisions.jsonl` — the design phase reads ADRs but never authors them (decisions land via debug remediation or build / ship doc-integration). Open questions in `Risks & Open Questions` are never bare — each carries 2-3 concrete options, one lettered option per line (`A) {option} — {trade-off}`), a `Recommended` option and a `Default if unanswered`, written in plain English; the design phase states this requirement itself and does not read the plan template. |
310
310
  | `bkit-design-review-1` | Feasibility research with `WebFetch`/`WebSearch`; prior-art search per capability — repo sweep first (in-repo candidate outranks an ecosystem one; an ecosystem-only sweep cannot see the repo's own near-miss helpers), then dependency built-ins and ecosystem practice. Repo sweep — worded identically here and in plan template Pre-Flight — adds language-server symbol references and committed capability map `docs/capabilities.md` to text search. Tools named by capability, never product: prompts stay stack-independent and work with none installed. Both only add candidates — empty language-server answer = unresolved query; code map confirms presence, not absence — so absence (`NEW` reason (a)) rests on recorded text search. `EXTEND-EXISTING` heads the recommendation enum; unrebutted `NEW` verdict over live candidate = `CONCERNS` finding; writes review log. Sole emitter of the `Spike` header field (`true` when an `Unknowns & Blockers` item is settleable only by running code) — gates workflow Step 7. |
311
- | `bkit-design-review-2` | Same as `-1`; runs in parallel with cross-tier model diversity. Also audits `Risks & Open Questions` format — question missing options, `Recommended` or `Default if unanswered` (the lettered `Options: A) …`) → OPTIONAL. Does not emit `Spike`. |
311
+ | `bkit-design-review-2` | Same as `-1`; runs at `xhigh` on Sonnet in parallel with `-1`, so it stays a second opinion from a different model. Also audits `Risks & Open Questions` format — question missing options, `Recommended` or `Default if unanswered` (one lettered option per line, `A) …`) → OPTIONAL; options sharing one line count as missing. Does not emit `Spike`. |
312
312
  | `bkit-design-spike` | Conditional — runs only when `bkit-design-review-1` sets `Spike` = true. Restates each unknown as a falsifiable claim, writes the smallest probe that could disprove it under `docs/plans/{YYYYMM}/logs/{FID}/spike/`, runs it, records captured output verbatim. Settles claims by evidence only — never infers a result from source reading, never simulates an unavailable service. PASS / CONCERNS / FAIL where FAIL = a design assumption is disproven (Step 8 revises against it) and CONCERNS = unsettleable this run (assumption carried forward unproven); per-claim `SETTLED` / `DISPROVEN` / `BLOCKED` stays in the body. Disproof needs evidence that an honest attempt failed — "could not get it working" is `BLOCKED`, never `DISPROVEN`, and no claim may be weakened or stubbed to make a probe pass. Probe code is throwaway and confined to the artifact tree; never touches tracked source or a repo manifest. |
313
- | `bkit-design-update` | Apply CRITICAL items and OPTIONAL items judged on merit from both reviews; whole-doc rewrite of design. Open questions a finding adds or rewords carry options as the lettered `Options: A) …`, `Recommended` and `Default if unanswered`; untouched regions stay verbatim. Given **Update** instead of **Create**, it skips the seed and edits that design in place. An `## Owner answers` input (the design orchestrator after close) is applied as CRITICAL items: the answered question leaves `Risks & Open Questions`, a `Decision: {key}` becomes a `Decisions` item, and overridden statements follow the answer. |
313
+ | `bkit-design-update` | Apply CRITICAL items and OPTIONAL items judged on merit from both reviews; whole-doc rewrite of design. Open questions a finding adds or rewords carry options, one lettered option per line (`A) …`), `Recommended` and `Default if unanswered`, written in plain English; untouched regions stay verbatim. Given **Update** instead of **Create**, it skips the seed and edits that design in place. An `## Owner answers` input (the design orchestrator after close) is applied as CRITICAL items: the answered question leaves `Risks & Open Questions`, a `Decision: {key}` becomes a `Decisions` item, and overridden statements follow the answer. |
314
314
  | `bkit-design-organise` | Decompose `design-v2-reviewed.md` into dependency-annotated workstreams (`WS-1`, `WS-2`, …) with inline `Requires`, then group them into plans (`P-1`, …) by the deliverable test: a plan splits off only for an independent deliverable, its own rollout / rollback, its own risk or owner, or independent release; a same-change mandate keeps workstreams together. No task count or task cap. Each plan states `Deliverable`, `Covers` (every workstream in exactly one plan) and `Requires` (plan ids; cross-plan workstream edges lift to plan edges, intra-plan edges drop). FAIL if either graph has a cycle. `Suggested Plans` is the suggestion; a plan is the filed unit. Workflow Step 11 posts the plan list on the parent issue. It never creates tracker issues. |
315
315
 
316
316
  ## Plan Phase
@@ -318,11 +318,11 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
318
318
  <!-- prettier-ignore -->
319
319
  | Agent | Scope |
320
320
  | --- | --- |
321
- | `bkit-plan-generate` | Read design and / or audit reports + template + docs → write new plan draft. Design absent and audits present is valid. Neither present → the issue is the source: a change-shape issue's `Narrative`, `Success Criteria`, `Edge Cases`, matrix rows and tasks carry over verbatim (Contract `Acceptance Scenario` and `Scenario detail`). Audit contract: if input includes audit-scope directives, plan covers only those findings; the rest of each report is context only, not backlog. Workstream contract: if input includes `**Workstream:**` directive, plan covers only that workstream's `Scope` content unless stated otherwise; surface `**Requires:**` at top of plan. Process = one step per major template section in **dependency (authoring) order, not template document order** — derived sections (Breaking Changes, Supersession, Security, Docs, Rollback) follow Architecture rather than preceding it: Context → Acceptance Scenario → Derived Test Matrix → Open Questions → Pre-Flight → Alternatives → Data Schema → Reuse Inventory → Architecture (+ `decisions.jsonl`) → Breaking Changes → Supersession → Security → Docs → Rollback → Out of Scope → Suggested Scope Expansion → Agent Execution Runbook (groups of task blocks in build order, each group and task within the `bkit.workflows.tasks` caps the workflow passes in Context; pick tests from matrix only; each row → exactly one task; every task has `DONE WHEN`; `READ` / `UPDATE` / `DELETE` only for symbols it opened; never writes its own `TEST EXCEPTION`, copies an input's word for word) → Verification. The workflow runs `bkit tests plan-check --existence=refuse` on the draft straight after; exit 1 re-invokes it once to fix only the lines the report names. Human-confirmation checkboxes stay unchecked at generate. Each section group lands in the draft before reading for the next group starts, so a turn-cap stop leaves finished groups on disk, not an all-`PENDING` stub. Every `Open Questions & Assumptions` question carries 2-3 concrete options with trade-offs as the lettered `Options: A) {option} — {trade-off} · B) …`, a `Recommended` option and a `Default if unanswered` (design's answer carried forward where it has one); a bare question is not acceptable output. `Out of Scope` entries must be `Exempt` (genuinely-additive), else a runbook task. `Suggested Scope Expansion` holds candidates, not tasks; no tracker / ledger scan here — surface overlaps come from the orchestrator Fetch Context step via `bkit-plan-review-1`. |
322
- | `bkit-plan-review-1` | Read-only critique of the plan text — tightness + dependency-order lens; effort slot 1 (`high`). Parallel with `-2` and `bkit-plan-scope-check`. Drift from source, design-coverage gaps and unjustified expansion → CRITICAL. Tasks declare `DEPENDS ON`, which `bkit tests plan-check` checks mechanically (a missing task, the task itself, a task in a later group); review-1 derives the graph regardless: what each task produces and consumes, read against runbook order (build order), because a declared field lists only the edges its author saw. A consumer before its producer, or a prerequisite no task produces and the repo lacks, is CRITICAL. Surfaces `Suggested Scope Expansion` candidates from the `related-*.md` context. A group that leaves a test failing which only a later group's task fixes is CRITICAL, because the build checks each group before the next. FAIL only for a task-order cycle no reorder resolves, or a plan that contradicts its source design — every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
323
- | `bkit-plan-review-2` | Same scope — regression-risk lens, reads the code; effort slot 2 (`high`). Traces each task's files, symbols, schemas and endpoints to their consumers. `TEST FIRST` / `DONE WHEN` check current code cannot pass, no task changing it → CRITICAL, cites the ruling `file:line`. A `TEST FIRST` test whose logic already passes on current code or an earlier task's code → CRITICAL, citing the code that satisfies it: new behaviour needs a new test, judged by reading the test, since no test runs at plan time. A planned test whose fake or fixture value differs from what the cited producing code (`file:line`) returns is CRITICAL, and so is a `TEST FIRST` test that only compares against a regenerated baseline (snapshot, coverage list, generated doc), which regenerating makes pass. FAIL only for a regression vector the source design itself requires and no plan edit mitigates — every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
324
- | `bkit-plan-scope-check` | Internal-completeness scope audit; one slot, parallel with both reviewers on the draft (`medium` effort, opus model — depth-sensitive lens). Owns the template checks: sections present; `Acceptance Scenario` / `Derived Test Matrix` missing or vague → CRITICAL; `Open Questions & Assumptions` question missing options, `Recommended` or `Default if unanswered` (the lettered `Options: A) …`) → OPTIONAL (mirrors `bkit-design-review-2` on the design side). Per-task `DONE WHEN` / `TEST FIRST`, the matrix rows' task mapping and each `DELETE`'s `Supersession Inventory` row are not this lens: `bkit tests plan-check` refuses each after every plan write. `Blocking` out-of-scope deferral → CRITICAL. Duplication guard is bidirectional: `Supersession Inventory` catches code the plan replaces but never deletes; `Reuse Inventory` catches capability the plan rebuilds instead of extending. Recorded search (exact commands, not a claim) is the evidence — empty `Search performed` = unsearched, not absence; untraced `[NEW]` → CRITICAL. FAIL only for a `Blocking` out-of-scope deferral no plan edit recovers — a broken template and every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
325
- | `bkit-plan-update` | Merge review / scope critique notes → in-place plan edits + record log. Invariant: every task's `**DONE WHEN:**` and `**TEST FIRST:**` fields survive critique-merge (may be tightened, `n/a` → named tests included; never removed / weakened). Writes review's `Suggested Scope Expansion` candidates into the plan section (advisory; never tasks). Open questions a finding adds or rewords carry options as the lettered `Options: A) …`, `Recommended` and `Default if unanswered`; untouched regions stay verbatim. Human-confirmation checkboxes survive the merge as found — an unconditional invariant beside `DONE WHEN`, not a clause of the open-question rule. Mirrors to `docs/deferrals.jsonl` only the `Out of Scope` `Exempt` rows its merge adds; `Suggested Scope Expansion` candidates are never appended — most were read from that ledger, so appending duplicates them. Writes a `docs/decisions.jsonl` row per decision its merge adds or changes, same `key` when changed, and keeps the plan's `**Ledger rows:**` line current for plan close's `bkit ledgers check`. Given **Update** instead of **Create** (the re-review round, or the plan orchestrator after close), it skips the seed and edits that plan in place. An `## Owner answers` input is applied as CRITICAL items: the answered question leaves `Open Questions & Assumptions`, a `Decision: {key}` joins the `**Ledger rows:**` line, and overridden tasks and statements follow the answer. |
321
+ | `bkit-plan-generate` | Read design and / or audit reports + template + docs → write new plan draft. Design absent and audits present is valid. Neither present → the issue is the source: a change-shape issue's `Narrative`, `Success Criteria`, `Edge Cases`, matrix rows and tasks carry over verbatim (Contract `Acceptance Scenario` and `Scenario detail`). Audit contract: if input includes audit-scope directives, plan covers only those findings; the rest of each report is context only, not backlog. Workstream contract: if input includes `**Workstream:**` directive, plan covers only that workstream's `Scope` content unless stated otherwise; surface `**Requires:**` at top of plan. Process = one step per major template section in **dependency (authoring) order, not template document order** — derived sections (Breaking Changes, Supersession, Security, Docs, Rollback) follow Architecture rather than preceding it: Context → Acceptance Scenario → Derived Test Matrix → Open Questions → Pre-Flight → Alternatives → Data Schema → Reuse Inventory → Architecture (+ `decisions.jsonl`) → Breaking Changes → Supersession → Security → Docs → Rollback → Out of Scope → Suggested Scope Expansion → Agent Execution Runbook (groups of task blocks in build order, each group and task within the `bkit.workflows.tasks` caps the workflow passes in Context; pick tests from matrix only; each row → exactly one task; every task has `DONE WHEN`; `READ` / `UPDATE` / `DELETE` only for symbols it opened; never writes its own `TEST EXCEPTION`, copies an input's word for word) → Verification. The workflow runs `bkit tests plan-check --existence=refuse` on the draft straight after; exit 1 re-invokes it once to fix only the lines the report names. Human-confirmation checkboxes stay unchecked at generate. Each section group lands in the draft before reading for the next group starts, so a turn-cap stop leaves finished groups on disk, not an all-`PENDING` stub. Every `Open Questions & Assumptions` question carries 2-3 concrete options, one lettered option per line (`A) {option} — {trade-off}`), a `Recommended` option and a `Default if unanswered`, written in plain English (design's answer carried forward where it has one); a bare question is not acceptable output. `Out of Scope` entries must be `Exempt` (genuinely-additive), else a runbook task. `Suggested Scope Expansion` holds candidates, not tasks; no tracker / ledger scan here — surface overlaps come from the orchestrator Fetch Context step via `bkit-plan-review-1`. |
322
+ | `bkit-plan-review-1` | Read-only critique of the plan text — tightness + dependency-order lens; effort slot 1 (`xhigh`). Parallel with `-2` and `bkit-plan-scope-check`. Drift from source, design-coverage gaps and unjustified expansion → CRITICAL. Tasks declare `DEPENDS ON`, which `bkit tests plan-check` checks mechanically (a missing task, the task itself, a task in a later group); review-1 derives the graph regardless: what each task produces and consumes, read against runbook order (build order), because a declared field lists only the edges its author saw. A consumer before its producer, or a prerequisite no task produces and the repo lacks, is CRITICAL. Surfaces `Suggested Scope Expansion` candidates from the `related-*.md` context. A group that leaves a test failing which only a later group's task fixes is CRITICAL, because the build checks each group before the next. FAIL only for a task-order cycle no reorder resolves, or a plan that contradicts its source design — every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
323
+ | `bkit-plan-review-2` | Same scope — regression-risk lens, reads the code; effort slot 2 (`xhigh`). Traces each task's files, symbols, schemas and endpoints to their consumers. `TEST FIRST` / `DONE WHEN` check current code cannot pass, no task changing it → CRITICAL, cites the ruling `file:line`. A `TEST FIRST` test whose logic already passes on current code or an earlier task's code → CRITICAL, citing the code that satisfies it: new behaviour needs a new test, judged by reading the test, since no test runs at plan time. A planned test whose fake or fixture value differs from what the cited producing code (`file:line`) returns is CRITICAL, and so is a `TEST FIRST` test that only compares against a regenerated baseline (snapshot, coverage list, generated doc), which regenerating makes pass. FAIL only for a regression vector the source design itself requires and no plan edit mitigates — every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
324
+ | `bkit-plan-scope-check` | Internal-completeness scope audit; one slot, parallel with both reviewers on the draft (`medium` effort, opus model — depth-sensitive lens). Owns the template checks: sections present; `Acceptance Scenario` / `Derived Test Matrix` missing or vague → CRITICAL; `Open Questions & Assumptions` question missing options, `Recommended` or `Default if unanswered` (one lettered option per line, `A) …`) → OPTIONAL (mirrors `bkit-design-review-2` on the design side). Open questions are written in plain English. Per-task `DONE WHEN` / `TEST FIRST`, the matrix rows' task mapping and each `DELETE`'s `Supersession Inventory` row are not this lens: `bkit tests plan-check` refuses each after every plan write. `Blocking` out-of-scope deferral → CRITICAL. Duplication guard is bidirectional: `Supersession Inventory` catches code the plan replaces but never deletes; `Reuse Inventory` catches capability the plan rebuilds instead of extending. Recorded search (exact commands, not a claim) is the evidence — empty `Search performed` = unsearched, not absence; untraced `[NEW]` → CRITICAL. FAIL only for a `Blocking` out-of-scope deferral no plan edit recovers — a broken template and every other gap is CRITICAL → CONCERNS so `bkit-plan-update` repairs it. Marks each CRITICAL `(plan edit)` or `(design change)`; header `Redesign: true` when any is a design change, which sends a `FAIL` review straight to the Failure Path instead of an apply round and its one re-review. |
325
+ | `bkit-plan-update` | Merge review / scope critique notes → in-place plan edits + record log. Invariant: every task's `**DONE WHEN:**` and `**TEST FIRST:**` fields survive critique-merge (may be tightened, `n/a` → named tests included; never removed / weakened). Writes review's `Suggested Scope Expansion` candidates into the plan section (advisory; never tasks). Open questions a finding adds or rewords carry options, one lettered option per line (`A) …`), `Recommended` and `Default if unanswered`, written in plain English; untouched regions stay verbatim. Human-confirmation checkboxes survive the merge as found — an unconditional invariant beside `DONE WHEN`, not a clause of the open-question rule. Mirrors to `docs/deferrals.jsonl` only the `Out of Scope` `Exempt` rows its merge adds; `Suggested Scope Expansion` candidates are never appended — most were read from that ledger, so appending duplicates them. Writes a `docs/decisions.jsonl` row per decision its merge adds or changes, same `key` when changed, and keeps the plan's `**Ledger rows:**` line current for the `bkit tests plan-check --ledger-rows` check after each apply round. Given **Update** instead of **Create** (the re-review round, or the plan orchestrator after close), it skips the seed and edits that plan in place. An `## Owner answers` input is applied as CRITICAL items: the answered question leaves `Open Questions & Assumptions`, a `Decision: {key}` joins the `**Ledger rows:**` line, and overridden tasks and statements follow the answer. |
326
326
 
327
327
  ## Build Phase
328
328
 
@@ -333,13 +333,13 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
333
333
  | `bkit-build-plan-current` | Judge whether changes landed on `origin/dev` since the plan's `bkit:anchor` `baseSha` leave its tasks executable. Runs `bkit tasks currency --plan= --base={BASE_SHA} --against=origin/dev` — the engine records each task's in-scope paths and symbols in the plan block and prints only the tasks whose path or symbol moved in `{BASE_SHA}...origin/dev`, each with its matched paths, needles and diff hunks — and reads those hunks only, no whole-range diff, no path outside a matched set. Same output shape as `bkit-build-challenge-*`: header count + one append-only findings section. `Executable` tasks are not findings and are not logged; `Reword` / `Broken` are, and `Affected` = their count. PASS = no affected task; CONCERNS = any `Reword`; FAIL = any `Broken`. All three are advisory — build proceeds on every verdict and `@bkit-build-plan-tasks` reads the findings as its currency input. Judges the plan against the codebase — the design doc is not an input and a superseded design is not a finding. Commit distance and elapsed time never carry the verdict. Does not revise the plan: remediation is a `/bkit-plan` re-run, never `bkit-plan-update` from build. |
334
334
  | `bkit-build-install-skills` | Identify and install relevant skills via `npx skills find`/`add`: quality-hurdle the source (official publisher, or 1000+ installs / 100+ stars), install one named skill per gap, report provenance. |
335
335
  | `bkit-build-plan-tests` | Write one task group's planned tests — every `TEST FIRST` test of the task blocks in the brief `bkit context brief --group --tests-only --file` writes, which leaves out the tests the group's red rows already proved. Each test fails on the behaviour its `fails on` text names, is lint-clean, and never names a test the task's `TEST EXCEPTION` names; a stub only where a test cannot load without one; no source code (`steps finish --step=build-plan-tests --plan` refuses a diff touching any other file, exit 15). Flat log `build-plan-tests-{GROUP}-log.md`: ``WROTE — TASK {N}: `{file}` `{name}` ``, ``PASSES — TASK {N}: `{file}` `{name}`: {reason}`` (the behaviour already exists; `bkit tests red` records the test `passed-accepted`), ``BLOCKED — TASK {N}: `{file}` `{name}` — {reason}``, `SOURCE — TASK {N}: {value} from {file}:{line}` (where a value the test checks or fakes comes from). Verdict PASS / HANDOVER / FAIL: `HANDOVER` = turn cap near with tests left; the workflow re-runs the tests half once with a fresh brief. Re-invoked with a red report → rewrites only the tests it lists as `vacuous`, `missing`, `no-report` or `lint`. Never runs `bkit tests red` itself; the orchestrator runs it once per group after the step. |
336
- | `bkit-build-plan-tasks` | Execute one task group — the task blocks in the brief `bkit context brief --next` writes; earlier tasks in the brief are context only; the brief's `Deviations` section, when present, is the owner's run instruction, applied to the tasks it names. An existing log is kept and its `Verdict` reset to `PENDING`. Verdict PASS / HANDOVER / FAIL: `HANDOVER` = turn cap near with tasks neither `DONE` nor `BLOCKED` → stop after the current task's log line; the workflow re-runs the group once with a fresh brief, not as a failed attempt. The group's `TEST FIRST` tests are already on disk, written by `bkit-build-plan-tests` and recorded red by the engine before this step: makes them pass and never edits, renames, moves or deletes a planned test or a `TEST EXCEPTION` field (`steps finish` refuses the step when a planned test file differs from its red blob, exit 11); a test recorded `passed-accepted` → `DONE — TASK {N}: already landed` when `DONE WHEN` already holds with no task code written; never undoes code to force a red (`.bkit/workflows.md` § Test-first). Honours the brief's `Reuse Inventory` rows and `Architecture` entries at the only point the decision can still be quietly discarded — `EXTEND` row modifies named artifact, never a parallel file; rows or entries the brief left out (8 KB work cap) → reads the plan section it names; reusable artifact found mid-build folds in, never forks; reads each task's `DONE WHEN` field as the completion criterion to satisfy; modify source; write stub artifact first then incremental `Task Log` entries — one `DONE — TASK {N}:` or `BLOCKED — TASK {N}:` line per task at line start, which the next brief reads to skip finished tasks. Reads `build-plan-current.md` when present: findings are fact, plan is intent — `Reword` tasks build at the paths the report names as current, `Broken` tasks whose work already landed log `DONE — TASK {N}: already landed`, the rest build the intent against current code. Never edits the plan file; tasks absent from the findings follow plan wording verbatim. Does not tick plan checkboxes (verify owns that). Does not write `docs/deferrals.jsonl` — a blocked task is a `BLOCKED` log line for verify to catch, not a deferral. |
337
- | `bkit-build-plan-verify` | Verify implementation vs plan; writes Plan Verification log. `Group` mode judges one group's briefs against the group diff (changes since the group's start commit); `Holistic` mode runs once after the last group, across every group, plus integration. Ticks are the engine's: the header's `Tasks` line names the task numbers the codebase satisfies and `bkit tasks tick --green=` writes the `[x]`; the prompt edits no plan and never ticks a box. `bkit tests green` prints `verdict` and a `fixable` per gap, so the prompt holds no kind→`Fixable` table and no verdict mapping. Its reads decide only a `null` gap: `delete-still-referenced` → each hit read, a different thing with the same name → no gap, else `Fixable: true`; each `Updated tests` entry → the test's diff since its `base` read: only added expectations → no gap, a removed or loosened expectation → a `Fixable: false` gap; `Unproven` tests → `Notes`, no gap, because the owner answers them once at the build's end. Each gap is appended as the report's `logLine` with the decided `Fixable` in place of `null`; every other gap keeps its printed `fixable`; header `Failures` = unresolved gap count and `Fixable` = `true` when any is (build → fixable-only remediate, then Decision Pause); a test a task's `TEST EXCEPTION` field names is no gap; `Already landed` tests → `Notes` — a `BLOCKED` log line or a deferral row never discharges a task, so unfinished work routes to `@bkit-build-plan-gaps-remediate` in-loop instead of surfacing at ship. Missing `DONE WHEN` on any task → FAIL (template structure broken; remediation cannot recover). |
338
- | `bkit-build-plan-gaps-remediate` | Fix specific gaps from the group's latest verify log + group gate log failures (the tests of the groups so far); a Context `Group gate` command is re-run after each fix until exit 0 — each newly exposed failure is a gap of the same round, other tests built on the same failing assumption are swept first — and logged `DONE — Group gate: exit 0`, which `PASS` needs; reads the group's briefs for its task blocks; Standard / Pivot / Final escalation. Context `Scope: fixable only` → `— Fixable: false` gaps out of scope. Header `Fixed` = `DONE — Gap` lines this attempt (0 → build Decision Pause). A supplied decision record → the owner's `Decision:` words steer the round. No strategy records a red by undoing or swapping out code, or rewrites a planned test case (`steps finish` exit 11 names the case); other tests in the same file are its to change; never touches a `TEST EXCEPTION` field (`.bkit/workflows.md` § Test-first). |
339
- | `bkit-build-challenge-1` | Adversarial review of `git diff origin/dev...HEAD` — bug-hunting lens; effort slot 1 (`high`). Parallel with `-2`. Writes each finding as one task block — `Severity`, `Class` (`mechanical\|architectural`), `Fixable`, `Location`, `DONE WHEN`, `TEST FIRST` within the per-task `bkit.workflows.tasks` caps the workflow passes in Context — that `bkit challenge merge` appends to the plan as a new last group. Reads each `TEST FIRST` test's logic against the code the diff leaves: it must fail there, or `tests red` refuses it as `passed` and the fix task blocks; a finding an existing plan task or test already covers gets no block. Never references sibling output (circular reasoning guard). |
340
- | `bkit-build-challenge-2` | Same as `-1` — security lens; effort slot 2 (`high` on Claude / opus — depth-sensitive; Grok on Cursor — first-party depth, same native pool as `-1`). |
336
+ | `bkit-build-plan-tasks` | Execute one task group — the task blocks in the brief `bkit context brief --next` writes; earlier tasks in the brief are context only; the brief's `Deviations` section, when present, is the owner's run instruction, applied to the tasks it names. An existing log is kept and its `Verdict` reset to `PENDING`. Verdict PASS / HANDOVER / FAIL: `HANDOVER` = turn cap near with tasks neither `DONE` nor `BLOCKED` → stop after the current task's log line; the workflow re-runs the group once with a fresh brief, not as a failed attempt. The group's `TEST FIRST` tests are already on disk, written by `bkit-build-plan-tests` and recorded red by the engine before this step: makes them pass and never edits, renames, moves or deletes a planned test or a `TEST EXCEPTION` field (`steps finish` refuses the step when a planned test case differs from its baseline, exit 11), except that a correct code change forcing a planned-test edit is kept and logged ``BLOCKED — TASK {N}: test `{file}` `{name}` — {why}`` plus the task's `DONE` line, which the owner answers at the end of the build; a test recorded `passed-accepted` → `DONE — TASK {N}: already landed` when `DONE WHEN` already holds with no task code written; never undoes code to force a red (`.bkit/workflows.md` § Test-first). Honours the brief's `Reuse Inventory` rows and `Architecture` entries at the only point the decision can still be quietly discarded — `EXTEND` row modifies named artifact, never a parallel file; rows or entries the brief left out (8 KB work cap) → reads the plan section it names; reusable artifact found mid-build folds in, never forks; reads each task's `DONE WHEN` field as the completion criterion to satisfy; modify source; write stub artifact first then incremental `Task Log` entries — one `DONE — TASK {N}:` or `BLOCKED — TASK {N}:` line per task at line start, which the next brief reads to skip finished tasks. Reads `build-plan-current.md` when present: findings are fact, plan is intent — `Reword` tasks build at the paths the report names as current, `Broken` tasks whose work already landed log `DONE — TASK {N}: already landed`, the rest build the intent against current code. Never edits the plan file; tasks absent from the findings follow plan wording verbatim. Does not tick plan checkboxes (verify owns that). Does not write `docs/deferrals.jsonl` — a blocked task is a `BLOCKED` log line for verify to catch, not a deferral. |
337
+ | `bkit-build-plan-verify` | Verify implementation vs plan; writes Plan Verification log. `Group` mode judges one group's briefs against the group diff (changes since the group's start commit); `Holistic` mode runs after the last group, and again after later groups, across every group, plus integration; it runs no tests (the workflow's holistic gate does) and logs each integration gap as an `INTEGRATION:` gap line ending `— Fixable: true`, or `— Fixable: false` only when closing it needs a choice the plan does not make. Ticks are the engine's: the header's `Tasks` line names the task numbers the codebase satisfies and `bkit tasks tick --green=` writes the `[x]`; the prompt edits no plan and never ticks a box. `bkit tests green` prints `verdict` and a `fixable` per gap, so the prompt holds no kind→`Fixable` table and no verdict mapping. Its reads decide only a `null` gap: `delete-still-referenced` → each hit read, a different thing with the same name → no gap, else `Fixable: true`; each `Updated tests` entry → the test's diff since its `base` read: only added expectations → no gap, a removed or loosened expectation → a `Fixable: false` gap; `Unproven` tests → `Notes`, no gap, because the owner answers them once at the build's end; `Changed by a code step` entries → `Notes`, no gap when the added lines only add setup or expectations, else a `test-loosened` gap (`Fixable: false` for a test of an earlier group or one an earlier verify logged). Each gap is appended as the report's `logLine` with the decided `Fixable` in place of `null`; every other gap keeps its printed `fixable`; header `Failures` = unresolved gap count and `Fixable` = `true` when any is (build → fixable-only remediate, then Decision Pause); a test a task's `TEST EXCEPTION` field names is no gap; `Already landed` tests → `Notes` — a `BLOCKED` log line or a deferral row never discharges a task, so unfinished work routes to `@bkit-build-plan-gaps-remediate` in-loop instead of surfacing at ship. Missing `DONE WHEN` on any task → FAIL (template structure broken; remediation cannot recover). |
338
+ | `bkit-build-plan-gaps-remediate` | Fix specific gaps from the group's latest verify log + group gate log failures, or, with Context `Mode: Holistic`, the holistic verify report's gap lines (reading the plan task blocks they name) + holistic gate log failures (the tests of the groups so far); a Context `Group gate` or `Holistic gate` command is re-run after each fix until exit 0 — each newly exposed failure is a gap of the same round, other tests built on the same failing assumption are swept first — and logged `DONE — Group gate: exit 0` or `DONE — Holistic gate: exit 0`, which `PASS` needs; reads the group's briefs for its task blocks; Standard / Pivot / Final escalation, Pivot and Final applied only to the gaps of the Context's `Repeat tests`. Context `Scope: fixable only` → `— Fixable: false` gaps out of scope. Header `Fixed` = `DONE — Gap` lines this attempt (0 → build Decision Pause). A supplied decision record → the owner's `Decision:` words steer the round. No strategy records a red by undoing or swapping out code, or rewrites a planned test case (`steps finish` exit 11 names the case); other tests in the same file are its to change, and a planned-test edit its code change forces is kept and logged ``BLOCKED — Gap {N}: test `{file}` `{name}` — {why}`` plus the gap's `DONE` line; never touches a `TEST EXCEPTION` field (`.bkit/workflows.md` § Test-first). |
339
+ | `bkit-build-challenge-1` | Adversarial review of the run's diff — bug-hunting lens; effort slot 1 (`xhigh`). Parallel with `-2`. Writes each finding as one task block — `Severity`, `Class` (`mechanical\|architectural`), `Fixable`, `Location`, `DONE WHEN`, `TEST FIRST` within the per-task `bkit.workflows.tasks` caps the workflow passes in Context — that `bkit challenge merge` appends to the plan as a new last group. Reads each `TEST FIRST` test's logic against the code the diff leaves: it must fail there, or `tests red` refuses it as `passed` and the fix task blocks; a finding an existing plan task or test already covers gets no block. Never references sibling output (circular reasoning guard). |
340
+ | `bkit-build-challenge-2` | Same as `-1` — security lens; effort slot 2 (`xhigh` on Claude / opus — depth-sensitive; Grok on Cursor — first-party depth, same native pool as `-1`). |
341
341
 
342
- > **Cross-phase reuse:** Build Steps 12-13 and Ship Steps 11-12 invoke `bkit-debug-failure-diagnose` / `bkit-debug-failure-remediate` (in-build test failures, in-ship merge failures). See the Debug Phase entries.
342
+ > **Cross-phase reuse:** Build Steps 13-14 invoke `bkit-debug-failure-diagnose` / `bkit-debug-failure-remediate` (in-build test failures). See the Debug Phase entries.
343
343
 
344
344
  ## Debug Phase
345
345
 
@@ -347,7 +347,7 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
347
347
  | Agent | Scope |
348
348
  | --- | --- |
349
349
  | `bkit-debug-failure-reproduce` | Bug report, no failing test → co-located tests failing on the reported symptoms, lowest tier reaching it; no implementation changes. Max 3 rewrites / 3 paths; not reproduced → test changes removed, `Reproduced: NO`. `Mode: SOAK` → tests repeat the scenario until they fail reliably. Wired into `/bkit-debug` § Failure Reproduce on `[repro]` + first-attempt PASS; `YES` → Run Tests records the red, or passes with no fix → Summary (`CONCERNS`: `Reproduced: YES` with no remediate / soak log); `NO` → Summary. |
350
- | `bkit-debug-failure-diagnose` | Investigate test / CI failure → diagnosis log; no fixes. Standard / Pivot / Final by attempt. Folds `docs/knowledge.jsonl` by `key`, highest `ts` wins → reads only winning rows where `status` is `ACTIVE` or absent → cites matching entries in `Prior Knowledge` → uses them to seed hypotheses. Output uses append-only ReAct `Hypothesis {N}` blocks; refuted hypotheses must remain. A supplied decision record → the owner's `Decision:` words steer the diagnosis. |
350
+ | `bkit-debug-failure-diagnose` | Investigate test / CI failure → diagnosis log; no fixes. Standard / Pivot / Final by attempt, Pivot and Final applied only to the failures of the Context's `Repeat tests`, which `Prior Attempts Reviewed` names. Folds `docs/knowledge.jsonl` by `key`, highest `ts` wins → reads only winning rows where `status` is `ACTIVE` or absent → cites matching entries in `Prior Knowledge` → uses them to seed hypotheses. Output uses append-only ReAct `Hypothesis {N}` blocks; refuted hypotheses must remain. A supplied decision record → the owner's `Decision:` words steer the diagnosis. |
351
351
  | `bkit-debug-failure-remediate` | Apply diagnosis fix; lint / typecheck / test gate; may append `knowledge.jsonl`/`decisions.jsonl`. |
352
352
  | `bkit-debug-failure-soak` | One accumulating context across iterations (reads its prior `debug-failure-soak-*-log.md`); applies the single next instrument-or-fix step against the failing boundary; refuses to theorise; adds `[DEBUG-OBSERVE]` scaffolding and strips every marker before declaring a fix (no-leak). Wired into `/bkit-debug` § Failure Remediate Soak (`DEBUG_MODE` = SOAK); the orchestrator re-runs the tests and loops it within `SOAK_ATTEMPT` (`debug.soak.maxAttempts`, counted across every debug run of the feature). Flat append-only `DONE`/`BLOCKED` log. |
353
353
  | `bkit-debug-abort-handover` | Read all prior diagnose / remediate / verify logs → handover doc + `failures.jsonl` / `deferrals.jsonl` append. Called from build / debug / ship Failure Paths. |
@@ -357,7 +357,7 @@ Cursor Cloud automation uses `composer-2.5` for metadata / API plumbing, and the
357
357
  <!-- prettier-ignore -->
358
358
  | Agent | Scope |
359
359
  | --- | --- |
360
- | `bkit-ship-conflict-resolve` | Mid-merge mechanical conflict resolver. Invoked from `/bkit-ship` Step 4 when `bkit branches sync --merge` exits 24: the merge of `origin/dev` is in progress with its ledgers, lockfile, generated register, embedding docs and install record already resolved, and the agent hand-resolves only the paths left conflicted, then re-runs the block, which commits the merge. Allowed: non-overlapping additive edits, formatting drift, dep-version supersedes, additive JSON entries. Refused: same-function edits, semantic overlaps, ambiguous intent — FAIL aborts the merge cleanly and routes to `bkit-debug-abort-handover`. Verifies via `bkit:gate:install-static-unit-build` before PASS. |
360
+ | `bkit-ship-conflict-resolve` | Mid-merge mechanical conflict resolver. Invoked from `/bkit-ship` Step 4 when `bkit branches sync --merge --target={sha}` exits 24. The supplied target is the pinned merge target, which must equal `MERGE_HEAD`; it may be the reconciled feature tip or fetched `dev` tip. The engine has already resolved ledgers, the lockfile, generated register, embedding docs and install record. The agent resolves only the remaining paths and re-runs the same target, which commits the merge. Allowed: non-overlapping additive edits, formatting drift, dep-version supersedes, additive JSON entries. Refused: same-function edits, semantic overlaps, ambiguous intent — FAIL aborts the merge cleanly and routes to `bkit-debug-abort-handover`. Verifies via `bkit:gate:install-static-unit-build` before PASS. |
361
361
  | `bkit-ship-deferred-sweep` | Pre-merge completeness gate. Builds the intended-delivery set from plan `Acceptance Scenario` sections + `DONE WHEN` fields and asserts each against the codebase. No plan file → `ship-input-*.md` is the plan; intended-delivery set = its requested outcomes. An unmet / unplanned gap → FAIL → Failure Path (merge never happens) only on >=1 of four blocking tests, each asserted against source, never inferred from a plan sentence: behaviour (absent / stub / wrong result), safety (guard weakened, known-broken path ships), false green (`bkit branches scan-diff --disabled-tests` names candidates; every hit is adjudicated against the base diff and current source), consumer break (shipped surface fails at runtime). Removed assertions need precise evidence of enabled equivalent coverage or an owner-approved retirement that leaves no current requirement uncovered; record each disposition under `Test Coverage Review`. Scan errors, actual disabling markers and missing or inconclusive coverage stay blocking, never exempt or lazy. Lane results are not evidence — bkit lanes are event-scoped, some push-to-`dev` only, so a pre-merge sweep reading them re-creates the unsatisfiable refusal that made gate code 16 opt-in; the gate + capstone own green. A gap passing none is `Lazy`: stale prose / comment / name, doc drift, unwritten ledger row, formatting, future-enhancement `TODO`, `DONE WHEN` met in substance not literal wording. Branch is green by this step, so aborting on a record-keeping gap leaves the work unmerged and the record unwritten. Declared deferrals (out-of-scope / future-work / non-goals across design, plan, `docs/deferrals.jsonl`, summaries) form the exempt set — never block, resurfaced verbatim in the ship summary's `Deferred & Out-of-Scope (Resurfaced)` section. Exemption is earned, not self-granted: the prompt holds no reason test — `bkit ledgers triage --fid= --plan=` applies the deferral tests and writes every `unjustified` / `TRIAGED` row itself, printing each plan-related row's `key`, `bucket` and test result, and one that fails moves to that third track `Lazy (unjustified)`, resurfaced as follow-up, never blocking the merge (a bounded fix is cheaper than an aborted ship). Both `Lazy` sources share one append shape; every item carries its row before the verdict is set. The intended-delivery set is those two sources and nothing else — every precondition, build process step and merge condition a plan states is advisory, never a gate: plan `Gate N` checkboxes, `Verification Plan` boxes and `Manual Verification` steps are build-phase process, never deliverables, and no phrasing in a plan, log or phase summary makes one blocking (the gate reaches only what the repo can be made to prove; the plan template carries the matching authoring rule). Invoked from `/bkit-ship` Step 5 (after Conflict Resolve, before Merge). |
362
362
  | `bkit-ship-update-docs` | Cross-reference changed files against every doc in `docs.md`; update stale. `Pending Items` comes from the `ship-pending-items.md` deferral scan the workflow writes with `bkit context ledger-scan --terms={FID} --source=docs/deferrals.jsonl`; the agent writes no ledger row and reads no `docs/deferrals.jsonl` directly. |
363
363
 
@@ -432,9 +432,9 @@ Hooks add text to an agent's context mid-run. The text reaches every agent and s
432
432
  | --- | --- | --- | --- | --- |
433
433
  | GateGuard | First edit per (session, agent, file) | First touch → investigation checklist (file read, callers, symbols, contracts, conventions, instructions quoted); new file → reuse-over-duplicate checklist; gate-config path → fix-code-not-gate advisory; `docs/**.md` (not `docs/plans/`) → density advisory appended | All five | `.bkit/core/hooks/gateguard-engine.js` |
434
434
  | ReadGuard | Repeat read of an unchanged line range, same agent | Use-earlier-output note; re-read only if the output left context | All five | `.bkit/core/hooks/readguard-engine.js` |
435
- | Guardrails | Shell edit (`sed -i`, redirect into a source file); unlisted `curl` / `wget` host on Claude, Codex; Codex ask tier | Advisory naming the bypassed gate; command still runs | Claude, Codex, Antigravity, Cursor | `.bkit/core/hooks/guardrails-shell.js`, `.bkit/core/hooks/guardrails-tiers.js` |
435
+ | Guardrails | Deny tier (force push, `rm -rf` on `/` / `~` / `$HOME`, `chmod -R 777 /`); Codex shell command that prints or sends a private key's content; shell edit by a known writer (`sed -i`, `tee`, redirect into a source file); unlisted `curl` / `wget` host on Claude, Codex; Codex ask tier | Deny tier → refusal with the reason, the command does not run (all five; OpenCode gets nothing else). Codex private-key content read → refusal (configured to deny, not verified on a real Codex host); Codex `.env` read → advisory. Rest → advisory naming the bypassed gate; the command still runs | All five | `.bkit/core/hooks/gateguard-engine.js` (`composeAdvice`), `.bkit/core/hooks/guardrails-shell.js`, `.bkit/core/hooks/guardrails-deny.js`, `.bkit/core/hooks/guardrails-tiers.js` |
436
436
 
437
- - **Never a must-do:** hook text is advisory and fails open. It never fires on an untrusted Codex `.codex/` layer, and it arrives after the edit on OpenCode. A prompt instruction that must hold stays in the prompt.
437
+ - **Never a must-do:** hook text is advisory and fails open. The guardrails deny tier refuses the command, but it fails open too. It never fires on an untrusted Codex `.codex/` layer, and it arrives after the edit on OpenCode. A prompt instruction that must hold stays in the prompt.
438
438
 
439
439
  ## Special Behaviors (frontmatter-adjacent contracts)
440
440
 
@@ -445,12 +445,129 @@ Hooks add text to an agent's context mid-run. The text reaches every agent and s
445
445
  | **Loop context accumulation** | `bkit-build-plan-verify`/`bkit-build-plan-gaps-remediate`, `bkit-debug-failure-diagnose` | Per-attempt log files (`*-{N}-*.md`): the agent globs its own prior logs and adjusts its strategy (Standard / Pivot / Final). Each loop stops at its ask point's limit (`bkit.workflows.<workflow>.<point>`) → Failure Path. With `ask` on, the orchestrator asks before each further round (`.bkit/workflows.md` § Ask points). `bkit-debug-failure-remediate` is strategy-blind: it applies whatever the strategy-aware diagnosis generates. See `.bkit/workflows.md` § Loop context accumulation. |
446
446
  | **Tracker-bound output (`Output cap: 500 token prose`)** | `bkit-debug-abort-handover` | Output is pasted verbatim into the tracker comment thread (workflow `comment-post-step` block). The cap applies to prose only. Sections that list items verbatim are exempt, because a reworded acceptance item or option loses the trade-off the human decides on. The output is self-contained: don't add references to other files the human reviewer can't open. **Cap belongs only here:** critique / review / diagnosis agents (`bkit-*-review-*`, `bkit-*-scope-check-*`, `bkit-build-plan-verify`, `bkit-build-challenge-*`, `bkit-debug-failure-diagnose`, `bkit-ship-deferred-sweep`) are uncapped because their output drives downstream apply steps (`*-update`, `*-remediate`) and detail compression there pushes interpretation cost onto the apply agent. |
447
447
  | **Stubbed output (verdict + section placeholders)** | All multi-section verdict-bearing agents — critique / review (`bkit-design-review-*`, `bkit-design-spike`, `bkit-plan-review-*`, `bkit-plan-scope-check`, `bkit-build-plan-current`, `bkit-build-plan-verify`, `bkit-build-challenge-1`, `bkit-build-challenge-2`, `bkit-debug-failure-diagnose`, `bkit-ship-deferred-sweep`), top-of-pipeline synthesizers (`bkit-design-generate`, `bkit-plan-generate`, `bkit-audit-generate`), the tracker-bound handover (`bkit-debug-abort-handover`), and source modifiers (`bkit-build-plan-tasks`, `bkit-build-plan-gaps-remediate`, `bkit-debug-failure-remediate`, `bkit-ship-conflict-resolve`) — see "Flat append-only log for source modifiers" row below. | Process shape: (1) Write the **Create** output stub, with `PENDING` in every placeholder (matches Output format); (2-3) re-read inputs + load docs; (4) Update **Create** output — replace each PENDING via `Edit` as content becomes available (standing directive for the analysis below); (5+) analysis steps fill PENDING incrementally as findings emerge. Output format ends each section's bracketed placeholder with "; initially set to `PENDING`." Truncation recovery is section-granular: the orchestrator greps for PENDING markers and re-issues the specific gaps. Per-step gate `No PENDING placeholders remain` paired with `Verdict valid` enforces completeness. Plan-update / design-update / design-organise follow the same shape but bootstrap from the prior v(N) with `bkit steps stub --from= --to=` (Bash; `--strip-header` drops the prior header) instead of fresh stub (Write), so steps 2-4 above are steps 1-3 there. |
448
- | **Untrusted-input prompt-defense** | every `.bkit/core/prompts/*.md` and every `.bkit/core/workflows/*.md` — no exceptions, no selection step | Two bullets in the `**Rules:**` block, identical in every file: the `external-input` and `external-skills` clauses in `.bkit/instructions.md`, copied from `.agents/rules.md`. `.bkit/core/engine/tools/instructions.test.ts` enumerates both directories and rejects missing clauses, near-copies and retired wording. It checks the data-not-instructions, report-directives and token-scope requirements, plus the skill-authority boundary. Every new prompt must carry both rules. Universal coverage avoids a per-file decision that could leave an agent unprotected. Threat model, write-time fence and spawn-line notice: `docs/security.md` § Untrusted Content & Prompt Injection. |
449
- | **Central agent rules (`**Rules file:**` bullet, `**Rules:**` block)** | every `.bkit/core/prompts/*.md` — no exceptions | `.agents/rules.md` is a 2x2: `bkit Rules` and `Project Rules` each split into `Universal Rules` (binds every agent) and `Orchestrator Rules` (workflows / commands only — git, CI, merge, tracker, and human-gate rules a leaf must not act on). **bkit rules are copied:** the `**Rules:**` block after `**Contract:**` holds, word for word and in `rules.md` order, every bkit `Universal Rules` bullet whose `- carry:` line in `.bkit/instructions.md` names the prompt (the agent acts on it: its carriers plus its tool set — `Bash` → `Destructive git`, `Other parallel agents`; `Edit` / `Write` → `File edits`, `Edit tools`). A rule never appears in `**Protocol:**` or `**Contract:**` as well. A leaf sees only the bkit rules its carry lines name. **Project rules are read:** a prompt with `Grep` or `Bash` says ``Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`; skip its `Orchestrator Rules`.``, so its agent never loads the bkit block it already carries; a prompt with neither says ``Read `.agents/rules.md` below `<!-- bkit:end -->` → …``. Either way a consumer's universal rules and `Project Settings` reach leaves while their orchestrator-only rules do not. The split is the consumer's declaration of which is which. Subsection names are shared across the two groups (`Agent Management`, `Git, CI & Merges`); a subsection is omitted only where it has no entry. **Position is contract:** `**Rules file:**` is always the first bullet of the `**Protocol:**` block, in every prompt and every workflow. Workflows and the repo-only `utility-*` agents (they push and merge) take the unscoped `**Rules file:**` line, and the entry files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/bkit-rules.mdc`, un-quoted `- **Rules:**`) the same text under `**Rules:**`: ``Read `.agents/rules.md` → follow all rules.``. `.bkit/core/engine/tools/instructions.test.ts` asserts the three header blocks, the `**Rules file:**` anchor, the block and order of every placed header clause, `rules-leaf` forbidden on workflows and `utility-*` agents, both groups under `bkit Rules`, and a universal counterpart for every orchestrator subsection; `.bkit/core/engine/tools/instructions-coverage.test.ts` asserts every prompt holds each rule its carry line names, no prompt holds a bkit rule no carry line names, and every prompt carries at least one. **Assertions stop at `bkit:end`:** `Project Rules` is consumer-owned; `bkit install` never writes it and `bkit check` ignores it. Header clauses (`**Order:**`, `**No improv:**`, `**No commits:**` (prompts with `Bash`)) stay inline in every prompt they apply to. `**Auto-apply:**` is `Orchestrator Rules` only and inlined in no prompt. |
448
+ | **Untrusted-input prompt-defense** | every `.bkit/core/prompts/*.md` and every `.bkit/core/workflows/*.md` — no exceptions, no selection step | Two bullets in the `**Rules:**` block, identical in every file: the `external-input` and `external-skills` clauses in `.bkit/instructions.md`, copied from `.agents/rules.md`. `.bkit/core/engine/tools/instructions.test.ts` enumerates both directories and rejects missing clauses, near-copies and retired wording. It checks the data-not-instructions, report-directives and token-scope requirements, plus the skill-authority boundary. Every new prompt must carry both rules. Universal coverage avoids a per-file decision that could leave an agent unprotected. Threat model, write-time fence and spawn-line notice: `.bkit/prompts.md` § Untrusted Content & Prompt Injection (threat model). |
449
+ | **Central agent rules (`**Rules file:**` bullet, `**Rules:**` block)** | every `.bkit/core/prompts/*.md` — no exceptions | `.agents/rules.md` is a 2x2: `bkit Rules` and `Project Rules` each split into `Universal Rules` (binds every agent) and `Orchestrator Rules` (workflows / commands only — git, CI, merge, tracker, and human-gate rules a leaf must not act on). **bkit rules are copied:** the `**Rules:**` block after `**Contract:**` holds, word for word and in `rules.md` order, every bkit `Universal Rules` bullet whose `- carry:` line in `.bkit/instructions.md` names the prompt (the agent acts on it: its carriers plus its tool set — `Bash` → `Destructive git`, `Other parallel agents`; `Edit` / `Write` → `File edits`, `Edit tools`). A rule never appears in `**Protocol:**` or `**Contract:**` as well. A leaf sees only the bkit rules its carry lines name. **Project rules are read:** a prompt with `Grep` or `Bash` says ``Find the line of `<!-- bkit:end -->` in `.agents/rules.md` (`grep -n`), then read the file from that line on → follow its `Universal Rules`, and break ties by its `Project Goals`, which never lower a severity or soften a verdict; skip its `Orchestrator Rules`.``, so its agent never loads the bkit block it already carries; a prompt with neither says ``Read `.agents/rules.md` below `<!-- bkit:end -->` → …``. Either way a consumer's universal rules, `Project Goals` (a third section a leaf reads, which breaks ties between options the rules both allow) and `Project Settings` reach leaves while their orchestrator-only rules do not. The split is the consumer's declaration of which is which. Subsection names are shared across the two groups (`Agent Management`, `Git, CI & Merges`); a subsection is omitted only where it has no entry. **Position is contract:** `**Rules file:**` is always the first bullet of the `**Protocol:**` block, in every prompt and every workflow. Workflows and the repo-only `utility-*` agents (they push and merge) take the unscoped `**Rules file:**` line, and the entry files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/bkit-rules.mdc`, un-quoted `- **Rules:**`) the same text under `**Rules:**`: ``Read `.agents/rules.md` → follow all rules.``. `.bkit/core/engine/tools/instructions.test.ts` asserts the three header blocks, the `**Rules file:**` anchor, the block and order of every placed header clause, `rules-leaf` forbidden on workflows and `utility-*` agents, both groups under `bkit Rules`, and a universal counterpart for every orchestrator subsection; `.bkit/core/engine/tools/instructions-coverage.test.ts` asserts every prompt holds each rule its carry line names, no prompt holds a bkit rule no carry line names, and every prompt carries at least one. **Assertions stop at `bkit:end`:** `Project Rules` is consumer-owned; `bkit install` never writes it and `bkit check` ignores it. Header clauses (`**Order:**`, `**No improv:**`, `**No commits:**` (prompts with `Bash`)) stay inline in every prompt they apply to. `**Auto-apply:**` is `Orchestrator Rules` only and inlined in no prompt. |
450
450
  | **`.agents/docs.md` read exemption** | `bkit-utility-compress-markdown` | A single-file mechanical utility that compresses prose in one supplied target. It does no domain reasoning, so the doc catalog earns nothing against its token cost. Every other prompt loads it. |
451
451
  | **`acceptEdits` hard requirement** | All in-pipeline agents | `Bash(*)`/`Edit(*)`/`Write(*)` blanket-allow lives in `.claude/settings.json`; `acceptEdits` skips per-call prompts. Stricter modes break end-to-end runs. |
452
452
  | **Plan task ticking owned by verify** | `bkit-build-plan-tasks` (ticks only applicable Pre-Flight and gate boxes), `bkit-build-plan-verify` (ticks task boxes `[ ]`→`[x]` only on verified codebase artifact) | Task checkboxes are verify's derived view of the codebase. The executor's durable progress record is its flat append-only log of `DONE —` lines, which keeps resume safe and keeps per-task `Edit` ticks out of its turn budget. Execute ticks each applicable Pre-Flight and gate box as that gate passes and continues without asking; it never ticks a task box or a human-confirmation box. |
453
453
  | **Flat append-only log for source modifiers** | `bkit-build-plan-tests`, `bkit-build-plan-tasks`, `bkit-build-plan-gaps-remediate`, `bkit-debug-failure-remediate` | Output format collapses to a single H1 + flat log body (no separate `Brief` / `Strategy` body sections: `Strategy` lives in the machine-parseable header alongside `Verdict`, and the reasoning is implicit in the `DONE —` / `BLOCKED —` lines). Stub state: `Verdict: PENDING` header + H1 + empty body. After every discrete unit of work (task / gap / finding / fix step): `Bash echo "DONE — {Unit} {N}: {name} — {outcome} ({path or commit ref})" >> {artifact}`. On failure: `BLOCKED — {Unit} {N}: {name} — {reason}`. Step 4 standing directive: `Update **Create** output — append DONE/BLOCKED log entries at EOF as content becomes available.` (vs canonical `replace each PENDING via Edit` for multi-section verdict-bearing agents). `Verdict` flips PENDING → PASS / CONCERNS / FAIL at the end via `Edit` on the header line. **Two wins:** (1) timeout resilience: partial progress is on disk after every appended line, so a budget-exhausted agent leaves a usable record, where ~30 ticks clustered at the end would all be lost on a timeout; (2) `Bash echo >>` is cheaper than `Edit`, because it needs no file read for an `old_string` match. **Skip-done logic** (read prior attempts via Read glob, skip units already in `DONE —`) is added only where the workflow already attempt-numbers and globs the artifact: `bkit-build-plan-gaps-remediate` (via `VERIFY_ATTEMPT`, glob already in its Read) and `bkit-build-plan-tasks` (one `build-plan-tasks-{GROUP}-log.md` per group; every attempt — a turn-cap re-run or a Decision Pause `Fix now` re-run — appends to it, and `bkit context brief --next` leaves out tasks it logs `DONE — TASK {N}:`). On PENDING (subagent timeout) the verify→remediate loop bounded by `build.verify.maxAttempts` absorbs recovery via `bkit-build-plan-gaps-remediate`. `bkit-debug-failure-remediate` is diagnosis-driven (each attempt takes a fresh strategy via `bkit-debug-failure-diagnose`), so skip-done would be the wrong shape. It gets stub+log only, but the flat log still feeds `bkit-debug-failure-diagnose`'s loop-context glob with finer evidence. |
454
+ | **Engine-owned model evidence** | every subagent whose rows carry `by.model` | `bkit ledgers append --invocation=<id>` fills the row's `by.model`, `by.configuredModel` and `by.modelSource` (`host`, `configured` or `unavailable`) from the issued invocation; an agent never copies a model name into a row. |
455
+
456
+ ### Untrusted Content & Prompt Injection (threat model)
457
+
458
+ **Threat model.** Every phase workflow combines three things:
459
+
460
+ - it ingests attacker-controlled text (commit messages, PR bodies, diffs, CI and runtime logs, web results, installed skill bodies)
461
+ - it holds a broad write token
462
+ - it can act (commit, push, merge, write files)
463
+
464
+ When all three are present, an embedded directive executes.
465
+
466
+ **Contract.** Follow `.agents/rules.md` § Security & Data, **External input** and **External skills**. Skill selection and permitted use are defined in `.agents/skills.md` § Activation Rules.
467
+
468
+ **Three layers, nearest the payload first:**
469
+
470
+ - **Fenced at the write.** A workflow that writes fetched external evidence to disk wraps it as it lands, in this order: instruction lines, `===== BEGIN UNTRUSTED =====`, the payload, `===== END UNTRUSTED =====`.
471
+ - The instruction comes before the payload, and nothing comes after the closer.
472
+ - The payload is wrapped once.
473
+ - First-party breadcrumbs are not fenced.
474
+ - Tracker bodies are not fenced, because they are the task specification. The header contract governs them.
475
+ - **Named on the spawn.** A subagent whose `Read:` list includes fenced artifacts is told so on its `Context:` line. That line is its last trusted instruction before it reads them.
476
+ - **Standing header contract.** Every agent prompt and workflow header carries both rules. They cover tool results (web search / fetch) that never become files, and skill bodies loaded by name.
477
+
478
+ **Per-file coverage is load-bearing.** Subagents spawn self-contained and never read `.agents/rules.md`. A rule placed only there reaches the orchestrating workflows but no leaf. The three registers exist by design. They are not redundant copies to collapse.
479
+
480
+ **No runtime telemetry.** "Flag injection attempts" produces no metric, log-grep or alert. Detection is a human reviewing the agent's output.
481
+
482
+ **Prose is defence-in-depth.** Prose is the layer an injection is designed to defeat. The load-bearing control is structural:
483
+
484
+ - give each job the narrowest-scoped token
485
+ - scan any text that reaches a privileged action (merge body, commit message)
486
+
487
+ Prose never substitutes for token scope.
488
+
489
+ ## Documentation Consultation Coverage
490
+
491
+ Every shipped prompt and audit template was reviewed for the project documents it should consult, with the same fields and outcomes as the workflow catalog (`workflows.md` § Documentation Consultation Coverage). Prompts share one load clause: read the `.agents/docs.md` index, load the listed documents, and warn and continue when the index or a document is missing, empty or still the starter. Prompts that produce gap reports write one `jsonl` record per gap under `## Documentation Warnings` with `topic`, `gap`, `recommendedPath`, `alternativeEvidence` and `action`; the workflow summary merges them. Audit templates are consulted through `bkit-audit-generate` step 4 unless a row says otherwise.
492
+
493
+ <!-- prettier-ignore -->
494
+ | Source | Recommended documents | Outcome | Applicability and reason |
495
+ | --- | --- | --- | --- |
496
+ | `.bkit/core/prompts/bkit-audit-generate.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Step 4 loads the surface documents with or without a plan and writes Documentation Warnings. |
497
+ | `.bkit/core/prompts/bkit-build-challenge-1.md` | `docs/architecture.md`, `docs/security.md` | added | Challenge cross-references findings against the architecture and security documents. |
498
+ | `.bkit/core/prompts/bkit-build-challenge-2.md` | `docs/security.md` | retained | Already cites the security document with warn-and-continue; the clause is now shared. |
499
+ | `.bkit/core/prompts/bkit-build-install-skills.md` | n/a | not-applicable | Installs skills from `.agents/skills.md`; it needs no project-document topic. |
500
+ | `.bkit/core/prompts/bkit-build-plan-convert.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Conversion carries consultation, sources, gaps and READ and UPDATE lines into the plan. |
501
+ | `.bkit/core/prompts/bkit-build-plan-current.md` | n/a | not-applicable | Compares plan references with the working tree; project documents add no evidence. |
502
+ | `.bkit/core/prompts/bkit-build-plan-gaps-remediate.md` | `docs/architecture.md`, `docs/testing.md` | corrected | Load-docs clause now warns and continues on a missing, empty or starter-only document instead of skipping it. |
503
+ | `.bkit/core/prompts/bkit-build-plan-tasks.md` | `docs/architecture.md`, `docs/data-schema.md`, `docs/design.md`, `docs/observability.md`, `docs/testing.md` | corrected | Load-docs clause now warns and continues on a missing, empty or starter-only document instead of skipping it. |
504
+ | `.bkit/core/prompts/bkit-build-plan-tests.md` | `docs/architecture.md`, `docs/testing.md` | corrected | Load-docs clause now warns and continues on a missing, empty or starter-only document instead of skipping it. |
505
+ | `.bkit/core/prompts/bkit-build-plan-verify.md` | `docs/observability.md`, `docs/testing.md` | corrected | Load-docs clause now warns and continues on a missing, empty or starter-only document instead of skipping it. |
506
+ | `.bkit/core/prompts/bkit-debug-abort-handover.md` | n/a | not-applicable | Writes the handover from run artifacts and keeps their warnings; it consults no document. |
507
+ | `.bkit/core/prompts/bkit-debug-failure-diagnose.md` | `docs/testing.md`, `docs/noise.md` | added | Diagnosis checks registered signal downgrades and test tiers before judging a failure. |
508
+ | `.bkit/core/prompts/bkit-debug-failure-remediate.md` | `docs/testing.md` | added | Remediation follows the testing document when present. |
509
+ | `.bkit/core/prompts/bkit-debug-failure-reproduce.md` | `docs/testing.md` | retained | Already cites the testing document with warn-and-continue. |
510
+ | `.bkit/core/prompts/bkit-debug-failure-soak.md` | `docs/testing.md` | added | Soak runs follow the tier rules in the testing document when present. |
511
+ | `.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md` | `docs/architecture.md`, `docs/technology.md` | added | Pragmatic lens starts from existing topology and stack choices. |
512
+ | `.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md` | `docs/architecture.md`, `docs/technology.md` | added | Trade-off lens starts from existing topology and stack choices. |
513
+ | `.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md` | `docs/architecture.md`, `docs/security.md` | added | Pre-mortem lens reads boundaries and trust assumptions. |
514
+ | `.bkit/core/prompts/bkit-design-generate.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md` | added | Draft design records the sources it consulted and warns on gaps. |
515
+ | `.bkit/core/prompts/bkit-design-organise.md` | `docs/architecture.md` | added | Workstream grouping respects documented boundaries. |
516
+ | `.bkit/core/prompts/bkit-design-review-1.md` | `docs/architecture.md`, `docs/technology.md` | added | Feasibility review checks the design against documented topology and stack. |
517
+ | `.bkit/core/prompts/bkit-design-review-2.md` | `docs/observability.md`, `docs/deployments.md` | retained | Already cites both documents with warn-and-continue. |
518
+ | `.bkit/core/prompts/bkit-design-spike.md` | n/a | not-applicable | Throwaway probes answer from code and the web; project documents add no evidence. |
519
+ | `.bkit/core/prompts/bkit-design-update.md` | `docs/architecture.md` | added | Applying review items keeps the design consistent with documented boundaries. |
520
+ | `.bkit/core/prompts/bkit-plan-generate.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Fills Documentation Consultation and Documentation Warnings and carries READ and UPDATE lines. |
521
+ | `.bkit/core/prompts/bkit-plan-review-1.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Critique checks that the plan consulted each assessed topic. |
522
+ | `.bkit/core/prompts/bkit-plan-review-2.md` | `docs/testing.md` | retained | Already cites the testing document with warn-and-continue. |
523
+ | `.bkit/core/prompts/bkit-plan-scope-check.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Scope audit checks the consultation table and warnings are complete. |
524
+ | `.bkit/core/prompts/bkit-plan-update.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/testing.md` | added | Preserves source evidence and updates it when a review changes the plan. |
525
+ | `.bkit/core/prompts/bkit-ship-conflict-resolve.md` | n/a | not-applicable | Resolves merge conflicts from git history and both sides; no project-document topic. |
526
+ | `.bkit/core/prompts/bkit-ship-deferred-sweep.md` | n/a | not-applicable | Reads the deferral ledger only; no project-document topic. |
527
+ | `.bkit/core/prompts/bkit-ship-update-docs.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/data-schema.md`, `docs/testing.md`, `docs/deployments.md`, `docs/observability.md`, `docs/design.md`, `docs/noise.md`, `docs/setup.md` | added | Checks presence, index accuracy and project content for every topic and reports unresolved coverage. |
528
+ | `.bkit/core/prompts/bkit-utility-compress-markdown.md` | n/a | not-applicable | Compresses the one file it is given; no project-document topic. |
529
+ | `.bkit/core/prompts/bkit-utility-update-decisions.md` | n/a | not-applicable | Ledger upkeep per `.bkit/jsonl.md`; no project-document topic. |
530
+ | `.bkit/core/prompts/bkit-utility-update-deferrals.md` | n/a | not-applicable | Ledger upkeep per `.bkit/jsonl.md`; no project-document topic. |
531
+ | `.bkit/core/prompts/bkit-utility-update-documentation.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/data-schema.md`, `docs/testing.md`, `docs/deployments.md`, `docs/observability.md`, `docs/design.md`, `docs/noise.md`, `docs/setup.md` | added | Reviews every relevant topic including absent ones, populates within scope and reports gaps. |
532
+ | `.bkit/core/prompts/bkit-utility-update-failures.md` | n/a | not-applicable | Ledger upkeep per `.bkit/jsonl.md`; no project-document topic. |
533
+ | `.bkit/core/prompts/bkit-utility-update-knowledge.md` | n/a | not-applicable | Ledger upkeep per `.bkit/jsonl.md`; no project-document topic. |
534
+ | `.bkit/core/prompts/bkit-utility-update-roadmap.md` | n/a | not-applicable | Roadmap upkeep from ledgers and the tracker; no project-document topic. |
535
+ | `.bkit/core/prompts/bkit-utility-update-tracker.md` | n/a | not-applicable | Tracker upkeep per `.bkit/trackers.md`; no project-document topic. |
536
+ | `.bkit/core/docs/templates/bkit-audit-accessibility.md` | `docs/design.md` | retained | Already cites the design document for tokens and components. |
537
+ | `.bkit/core/docs/templates/bkit-audit-adoption.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/data-schema.md`, `docs/testing.md`, `docs/deployments.md`, `docs/observability.md`, `docs/design.md`, `docs/noise.md`, `docs/setup.md` | added | Step 6 checks presence, index accuracy and content of every project document. |
538
+ | `.bkit/core/docs/templates/bkit-audit-agents.md` | n/a | not-applicable | Reviews instruction files, hosts and hooks that bkit manages; no project-document topic. |
539
+ | `.bkit/core/docs/templates/bkit-audit-aio-seo.md` | n/a | not-applicable | Crawls public pages for search and answer-engine readiness; no project-document topic. |
540
+ | `.bkit/core/docs/templates/bkit-audit-analytics.md` | `docs/observability.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
541
+ | `.bkit/core/docs/templates/bkit-audit-annotations.md` | n/a | not-applicable | Reviews code annotations against the code; no project-document topic. |
542
+ | `.bkit/core/docs/templates/bkit-audit-app-performance.md` | `docs/architecture.md`, `docs/observability.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
543
+ | `.bkit/core/docs/templates/bkit-audit-app-store.md` | `docs/deployments.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
544
+ | `.bkit/core/docs/templates/bkit-audit-architecture.md` | `docs/architecture.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
545
+ | `.bkit/core/docs/templates/bkit-audit-ci-performance.md` | `docs/deployments.md`, `docs/testing.md` | retained | Already cites both documents. |
546
+ | `.bkit/core/docs/templates/bkit-audit-config.md` | `docs/deployments.md` | retained | Already cites the deployments document. |
547
+ | `.bkit/core/docs/templates/bkit-audit-cost.md` | `docs/deployments.md` | retained | Already cites the deployments document. |
548
+ | `.bkit/core/docs/templates/bkit-audit-coverage.md` | `docs/testing.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
549
+ | `.bkit/core/docs/templates/bkit-audit-database.md` | `docs/data-schema.md`, `docs/setup.md` | corrected | Cited the setup document only; the schema document is now named for the active schema. |
550
+ | `.bkit/core/docs/templates/bkit-audit-dead-code.md` | `docs/architecture.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
551
+ | `.bkit/core/docs/templates/bkit-audit-deferrals.md` | n/a | not-applicable | Audits the deferral ledger; no project-document topic. |
552
+ | `.bkit/core/docs/templates/bkit-audit-dependencies.md` | `docs/deployments.md` | retained | Already cites the deployments document. |
553
+ | `.bkit/core/docs/templates/bkit-audit-documentation.md` | `docs/architecture.md`, `docs/technology.md`, `docs/security.md`, `docs/data-schema.md`, `docs/testing.md`, `docs/deployments.md`, `docs/observability.md`, `docs/design.md`, `docs/noise.md`, `docs/setup.md` | added | Step 3 checks presence, index accuracy and project content and writes Documentation Warnings. |
554
+ | `.bkit/core/docs/templates/bkit-audit-duplication.md` | `docs/architecture.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
555
+ | `.bkit/core/docs/templates/bkit-audit-failures.md` | n/a | not-applicable | Audits the failure ledger; no project-document topic. |
556
+ | `.bkit/core/docs/templates/bkit-audit-flakes.md` | `docs/testing.md` | retained | Already cites the testing document. |
557
+ | `.bkit/core/docs/templates/bkit-audit-gates.md` | `docs/deployments.md`, `docs/design.md`, `docs/testing.md` | retained | Already cites all three documents. |
558
+ | `.bkit/core/docs/templates/bkit-audit-issues.md` | n/a | not-applicable | Audits tracker issues; no project-document topic. |
559
+ | `.bkit/core/docs/templates/bkit-audit-llm.md` | `docs/technology.md`, `docs/security.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
560
+ | `.bkit/core/docs/templates/bkit-audit-logs.md` | `docs/observability.md`, `docs/noise.md` | retained | Already cites both documents. |
561
+ | `.bkit/core/docs/templates/bkit-audit-models.md` | `docs/technology.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
562
+ | `.bkit/core/docs/templates/bkit-audit-privacy.md` | `docs/security.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
563
+ | `.bkit/core/docs/templates/bkit-audit-prompts.md` | n/a | not-applicable | Reviews bkit prompts and agent files; no project-document topic. |
564
+ | `.bkit/core/docs/templates/bkit-audit-red-team.md` | `docs/security.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
565
+ | `.bkit/core/docs/templates/bkit-audit-reliability.md` | `docs/deployments.md` | retained | Already cites the deployments document. |
566
+ | `.bkit/core/docs/templates/bkit-audit-repo.md` | `docs/architecture.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
567
+ | `.bkit/core/docs/templates/bkit-audit-security.md` | `docs/security.md`, `docs/deployments.md` | retained | Already cites both documents. |
568
+ | `.bkit/core/docs/templates/bkit-audit-slop.md` | n/a | not-applicable | Scans code patterns against lint rules; no project-document topic. |
569
+ | `.bkit/core/docs/templates/bkit-audit-testing.md` | `docs/testing.md` | retained | Already cites the testing document. |
570
+ | `.bkit/core/docs/templates/bkit-audit-usability.md` | `docs/design.md` | added | Consulted through `bkit-audit-generate` step 4, which loads the surface's documents, warns and continues when one is missing, and writes `Documentation Warnings`. |
454
571
 
455
572
  ## Model Presets
456
573