@cbartens/bkit 5.5.0 → 6.0.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 (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -113,6 +113,7 @@ export function applyOpencodeAgent(
113
113
  const effort = parsed.get("effort");
114
114
  const toolsBlock = extractFrontmatterField(fmBlock, "tools");
115
115
 
116
+ // autoCompactWindow dropped: no per-agent setting, see providers.md § Context compaction.
116
117
  let newFm = "---\n";
117
118
  newFm += `mode: subagent\n`;
118
119
  newFm += `name: ${name}\n`;
@@ -203,6 +204,7 @@ export function applyCodexAgent(
203
204
  const body = afterFm.trim();
204
205
 
205
206
  const effort = parsed.get("effort");
207
+ // autoCompactWindow dropped: a role file's model_auto_compact_token_limit is discarded (openai/codex core/src/agent/role.rs:37-48).
206
208
  let out = "";
207
209
  out += tomlString("name", name);
208
210
  out += tomlString("description", parsed.get("description") ?? "");
@@ -398,6 +400,7 @@ export function applyT3(
398
400
  const effort = parsed.get("effort");
399
401
  const toolsBlock = extractFrontmatterField(fmBlock, "tools");
400
402
 
403
+ // autoCompactWindow dropped: no per-agent setting, see providers.md § Context compaction.
401
404
  let newFm = "---\n";
402
405
  newFm += `name: ${name}\n`;
403
406
  if (description.includes("\n")) {
@@ -480,6 +483,7 @@ export function applyAntigravityPrompt(
480
483
  const effort = parsed.get("effort");
481
484
  const toolsBlock = extractFrontmatterField(fmBlock, "tools");
482
485
 
486
+ // autoCompactWindow dropped: no per-agent setting, see providers.md § Context compaction.
483
487
  let newFm = "---\n";
484
488
  newFm += `name: ${name}\n`;
485
489
  if (description.includes("\n")) {
@@ -219,6 +219,18 @@ export function applyModelOverrides(
219
219
  }
220
220
  }
221
221
 
222
+ /**
223
+ * Override rows (from `overridesPath`) naming no agent in `known`, deduplicated in file
224
+ * order. `applyModelOverrides` skips such rows, so they are reported, not applied.
225
+ */
226
+ export function unknownModelOverrides(overridesPath: string, known: ReadonlySet<string>): string[] {
227
+ const out: string[] = [];
228
+ for (const o of parseModelOverrides(overridesPath)) {
229
+ if (!known.has(o.prompt) && !out.includes(o.prompt)) out.push(o.prompt);
230
+ }
231
+ return out;
232
+ }
233
+
222
234
  /**
223
235
  * Effort → provider thinking map from prompts.md.
224
236
  * Row key = Default column (canonical prompt `effort:`).
@@ -7,7 +7,10 @@
7
7
  /** The integration branch feature work lands on. */
8
8
  export const DEV = "dev";
9
9
 
10
+ /** The release branch: bkit never opens a PR into it or merges into it. */
11
+ export const MAIN = "main";
12
+
10
13
  /** True for `dev` and `main`: no feature work happens on them, no force-push touches them. */
11
14
  export function isSharedBranch(branch: string): boolean {
12
- return branch === DEV || branch === "main";
15
+ return branch === DEV || branch === MAIN;
13
16
  }
@@ -148,6 +148,13 @@ export const BKIT_EGRESS_SOURCES: readonly EgressSource[] = [
148
148
  hosts: ["api.githubcopilot.com"],
149
149
  bases: ["githubcopilot.com"],
150
150
  },
151
+ // The engine's own tracker calls (`gh api` REST and GraphQL), beside the MCP server.
152
+ {
153
+ id: "tracker-github-api",
154
+ kind: "tracker-mcp",
155
+ hosts: ["api.github.com"],
156
+ bases: ["github.com"],
157
+ },
151
158
  {
152
159
  id: "mcp-linear",
153
160
  kind: "tracker-mcp",
@@ -1,4 +1,4 @@
1
- // shared/json.ts — `JSON.parse` without the throw, for consumer-authored input.
1
+ // shared/json.ts — `JSON.parse` and file reads without the throw, for consumer-authored input.
2
2
  //
3
3
  // Every read of a file bkit does not own (package.json, .mcp.json, settings JSON,
4
4
  // .bkit/version) must fail open into a result the caller reports in its own terms,
@@ -20,14 +20,32 @@ export function parseJson(raw: string): JsonRead {
20
20
  }
21
21
  }
22
22
 
23
- /** `parseJson` over the file at `file`; `{ ok: false }` also when the file cannot be read. */
24
- export function readJsonFile(file: string): JsonRead {
25
- let raw: string;
23
+ export type TextRead = { ok: true; text: string } | { ok: false };
24
+
25
+ /** The file at `file` as UTF-8 text, or `{ ok: false }` when it cannot be read. */
26
+ export function readTextFile(file: string): TextRead {
27
+ try {
28
+ return { ok: true, text: fs.readFileSync(file, "utf-8") };
29
+ } catch {
30
+ // Missing, unreadable or a directory: the result says so, and the caller reports it.
31
+ return { ok: false };
32
+ }
33
+ }
34
+
35
+ export type DirRead = { ok: true; names: string[] } | { ok: false };
36
+
37
+ /** The entry names of the directory `dir`, or `{ ok: false }` when it cannot be read. */
38
+ export function readDirNames(dir: string): DirRead {
26
39
  try {
27
- raw = fs.readFileSync(file, "utf-8");
40
+ return { ok: true, names: fs.readdirSync(dir) };
28
41
  } catch {
29
- // Missing, unreadable or a directory: the result says so, like malformed JSON.
42
+ // Missing, unreadable or not a directory: the result says so, and the caller reports it.
30
43
  return { ok: false };
31
44
  }
32
- return parseJson(raw);
45
+ }
46
+
47
+ /** `parseJson` over the file at `file`; `{ ok: false }` also when the file cannot be read. */
48
+ export function readJsonFile(file: string): JsonRead {
49
+ const read = readTextFile(file);
50
+ return read.ok ? parseJson(read.text) : { ok: false };
33
51
  }
@@ -29,6 +29,32 @@ export interface LinearConfig extends TrackerStates {
29
29
  project: string | null;
30
30
  }
31
31
 
32
+ /** A GitHub Projects v2 board, read from its URL. */
33
+ export interface GithubBoard {
34
+ /** `org` for `/orgs/<login>/projects/<n>`, `user` for `/users/<login>/projects/<n>`; the MCP `owner_type`. */
35
+ ownerType: "org" | "user";
36
+ owner: string;
37
+ number: number;
38
+ }
39
+
40
+ /** `bkit.github`: the Projects v2 board issues sit on, and the Status option names each moment moves to. */
41
+ export interface GithubConfig extends TrackerStates {
42
+ /** Board from the `project` URL. false = board sync off; null = not configured or not a board URL. */
43
+ project: GithubBoard | false | null;
44
+ /** `project` as written when it is a string; null otherwise. */
45
+ projectUrl: string | null;
46
+ }
47
+
48
+ const BOARD_URL =
49
+ /^https:\/\/github\.com\/(orgs|users)\/([^/?#\s]+)\/projects\/([1-9][0-9]*)(?:[/?#].*)?$/;
50
+
51
+ /** The board a `https://github.com/{orgs|users}/<login>/projects/<n>[/views/…]` URL names; null otherwise. */
52
+ export function parseGithubBoardUrl(url: string): GithubBoard | null {
53
+ const m = BOARD_URL.exec(url.trim());
54
+ if (!m) return null;
55
+ return { ownerType: m[1] === "orgs" ? "org" : "user", owner: m[2]!, number: Number(m[3]) };
56
+ }
57
+
32
58
  /** `bkit.jira`: the site and project issues live in, and the status names each moment moves to. */
33
59
  export interface JiraConfig extends TrackerStates {
34
60
  /** Site URL, e.g. `https://acme.atlassian.net`; the MCP server's `cloudId`. null = not configured. */
@@ -37,6 +63,42 @@ export interface JiraConfig extends TrackerStates {
37
63
  project: string | null;
38
64
  }
39
65
 
66
+ /** `bkit.workflows.tasks`: the plan caps `tests plan-check` and `challenge merge` enforce. */
67
+ export interface TaskCaps {
68
+ /** Tasks in one plan group. */
69
+ maxPerGroup: number;
70
+ /** Planned TEST FIRST tests in one plan group. */
71
+ maxTestsPerGroup: number;
72
+ /** TEST FIRST tests one task names. */
73
+ maxTestsPerTask: number;
74
+ /** Distinct test files one task's TEST FIRST names. */
75
+ maxTestFilesPerTask: number;
76
+ }
77
+
78
+ /** Every point a workflow can stop and ask the owner at, as `<workflow>.<point>`. */
79
+ export const ASK_POINTS = [
80
+ "design.grill",
81
+ "build.verify",
82
+ "build.challenge",
83
+ "build.tests",
84
+ "debug.fix",
85
+ "debug.soak",
86
+ "ship.merge",
87
+ ] as const;
88
+ export type AskPoint = (typeof ASK_POINTS)[number];
89
+
90
+ /** One `bkit.workflows.<workflow>.<point>` block. */
91
+ export interface AskSetting {
92
+ /** Stop and ask the owner; false = carry on with the recommendation. Headless never asks. */
93
+ ask: boolean;
94
+ /** The hard limit: `maxTurns` for the grill, `maxAttempts` elsewhere. */
95
+ max: number;
96
+ }
97
+
98
+ /** The limit key a point's block holds. */
99
+ export const limitKey = (point: AskPoint): "maxTurns" | "maxAttempts" =>
100
+ point === "design.grill" ? "maxTurns" : "maxAttempts";
101
+
40
102
  export interface BkitConfig {
41
103
  /** CI workflow file under `.github/workflows/`. */
42
104
  ciWorkflow: string;
@@ -50,12 +112,12 @@ export interface BkitConfig {
50
112
  diskMinFreeGb: number;
51
113
  /** Which tracker issues live in: github, linear, jira or none. */
52
114
  issueTracker: IssueTracker;
115
+ /** `bkit.github`; each moment's state is the name of a board Status option. */
116
+ github: GithubConfig;
53
117
  /** `bkit.linear`; each moment's state is a state name, or a state type such as `started`. */
54
118
  linear: LinearConfig;
55
119
  /** `bkit.jira`. */
56
120
  jira: JiraConfig;
57
- /** The GitHub Projects v2 board settings; false = opted out, null = not configured. */
58
- githubProject: Record<string, unknown> | false | null;
59
121
  /** CI lanes whose `skipped` conclusion refuses a ship merge; empty = the capstone's green decides. */
60
122
  shipGateRequiredLanes: string[];
61
123
  /**
@@ -69,11 +131,15 @@ export interface BkitConfig {
69
131
  opencodeProviders: OpencodeProvider[];
70
132
  /** The post-CI cloud-agent variant; `none` is both the default and the explicit opt-out. */
71
133
  cloudAgents: CloudAgents;
72
- /** `bkit.depUpdater` is `"none"`: silences the missing-dependency-updater advisory. */
134
+ /** Per ask point: whether to ask, and its hard limit; each invalid key takes its default. */
135
+ asks: Record<AskPoint, AskSetting>;
136
+ /** Plan caps; each key that is not an integer >= 1 takes its default. */
137
+ tasks: TaskCaps;
138
+ /** `bkit.dependencies.updater` is `"none"`: silences the missing-dependency-updater advisory. */
73
139
  depUpdaterOptOut: boolean;
74
- /** `bkit.issueTracker` is present with any value, so `none` is a choice, not an undecided install. */
140
+ /** `bkit.tracker.default` is set, so `none` is a choice; absent or `""` (what install seeds) = undecided. */
75
141
  issueTrackerExplicit: boolean;
76
- /** `bkit.cloudAgents` is present with any value, so `none` is a choice, not an undecided install. */
142
+ /** `bkit.cloud.agent` is set, so `none` is a choice; absent or `""` (what install seeds) = undecided. */
77
143
  cloudAgentsExplicit: boolean;
78
144
  }
79
145
 
@@ -84,10 +150,11 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
84
150
  worktreeInstall: true,
85
151
  diskMinFreeGb: 40,
86
152
  issueTracker: DEFAULT_ISSUE_TRACKER,
153
+ // The Status options of GitHub's Kanban and Team planning board templates.
154
+ github: { project: null, projectUrl: null, progress: "In progress", review: "In review" },
87
155
  // `started` is a state type every Linear team has; In Review is a name a default team lacks.
88
156
  linear: { team: null, project: null, progress: "started", review: "In Review" },
89
157
  jira: { site: null, project: null, progress: "In Progress", review: "In Review" },
90
- githubProject: null,
91
158
  shipGateRequiredLanes: [],
92
159
  // What bkit's workflows write: plan / design / build logs and the ledgers. Never
93
160
  // `docs/**`: a project doc can be a test's input, so a docs edit can red a test.
@@ -95,6 +162,18 @@ export const CONFIG_DEFAULTS: Readonly<BkitConfig> = {
95
162
  opencodeProvider: null,
96
163
  opencodeProviders: [],
97
164
  cloudAgents: DEFAULT_CLOUD_AGENTS,
165
+ // `.bkit/workflows.md` § Ask points.
166
+ asks: {
167
+ "design.grill": { ask: true, max: 6 },
168
+ "build.verify": { ask: true, max: 2 },
169
+ "build.challenge": { ask: true, max: 2 },
170
+ "build.tests": { ask: true, max: 2 },
171
+ "debug.fix": { ask: true, max: 2 },
172
+ "debug.soak": { ask: true, max: 2 },
173
+ "ship.merge": { ask: true, max: 2 },
174
+ },
175
+ // Plan caps, `.bkit/workflows.md` § Test-first.
176
+ tasks: { maxPerGroup: 3, maxTestsPerGroup: 15, maxTestsPerTask: 10, maxTestFilesPerTask: 3 },
98
177
  depUpdaterOptOut: false,
99
178
  issueTrackerExplicit: false,
100
179
  cloudAgentsExplicit: false,
@@ -115,6 +194,75 @@ function trackerStates(raw: Record<string, unknown>, defaults: TrackerStates): T
115
194
  };
116
195
  }
117
196
 
197
+ const TASK_CAP_KEYS = Object.keys(CONFIG_DEFAULTS.tasks) as (keyof TaskCaps)[];
198
+
199
+ const validCap = (v: unknown): v is number => Number.isInteger(v) && (v as number) >= 1;
200
+
201
+ /**
202
+ * The keys of a `bkit.workflows.tasks` value that fall back to their default: each set key
203
+ * that is not an integer >= 1, or `["tasks"]` when the value is set but not an object.
204
+ */
205
+ export function invalidTaskCaps(raw: unknown): string[] {
206
+ if (raw === undefined) return [];
207
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return ["tasks"];
208
+ const set = raw as Record<string, unknown>;
209
+ return TASK_CAP_KEYS.filter((k) => set[k] !== undefined && !validCap(set[k]));
210
+ }
211
+
212
+ /** `bkit.workflows.tasks` read key by key; a missing or invalid key takes its default. */
213
+ function taskCaps(raw: unknown): TaskCaps {
214
+ const set = record(raw);
215
+ const caps = { ...CONFIG_DEFAULTS.tasks };
216
+ for (const k of TASK_CAP_KEYS) if (validCap(set[k])) caps[k] = set[k];
217
+ return caps;
218
+ }
219
+
220
+ /** The `bkit.workflows.<workflow>.<point>` block `workflows` holds for `point`. */
221
+ const askBlock = (workflows: Record<string, unknown>, point: AskPoint): unknown => {
222
+ const [workflow, name] = point.split(".") as [string, string];
223
+ const block = workflows[workflow];
224
+ return block !== null && typeof block === "object" && !Array.isArray(block)
225
+ ? (block as Record<string, unknown>)[name]
226
+ : undefined;
227
+ };
228
+
229
+ /**
230
+ * The dotted keys under `bkit.workflows` that fall back to their default: each set `ask`
231
+ * that is not a boolean, each set limit that is not an integer >= 1, or the point itself
232
+ * when it is set but not an object.
233
+ */
234
+ export function invalidAskSettings(workflows: unknown): string[] {
235
+ const set = record(workflows);
236
+ const bad: string[] = [];
237
+ for (const point of ASK_POINTS) {
238
+ const raw = askBlock(set, point);
239
+ if (raw === undefined) continue;
240
+ if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
241
+ bad.push(point);
242
+ continue;
243
+ }
244
+ const block = raw as Record<string, unknown>;
245
+ if (block.ask !== undefined && typeof block.ask !== "boolean") bad.push(`${point}.ask`);
246
+ const key = limitKey(point);
247
+ if (block[key] !== undefined && !validCap(block[key])) bad.push(`${point}.${key}`);
248
+ }
249
+ return bad;
250
+ }
251
+
252
+ /** Every ask point read from `bkit.workflows`; a missing or invalid key takes its default. */
253
+ function askSettings(workflows: Record<string, unknown>): Record<AskPoint, AskSetting> {
254
+ const out = {} as Record<AskPoint, AskSetting>;
255
+ for (const point of ASK_POINTS) {
256
+ const block = record(askBlock(workflows, point));
257
+ const limit = block[limitKey(point)];
258
+ out[point] = {
259
+ ask: typeof block.ask === "boolean" ? block.ask : CONFIG_DEFAULTS.asks[point].ask,
260
+ max: validCap(limit) ? limit : CONFIG_DEFAULTS.asks[point].max,
261
+ };
262
+ }
263
+ return out;
264
+ }
265
+
118
266
  /**
119
267
  * Read `package.json` `bkit` from `root` (the main checkout). A missing file,
120
268
  * missing key, or wrongly typed value falls back to the default for that key.
@@ -122,20 +270,30 @@ function trackerStates(raw: Record<string, unknown>, defaults: TrackerStates): T
122
270
  export function readBkitConfig(root: string): BkitConfig {
123
271
  // A missing or unparseable package.json takes every default; `bkit check` reports the file.
124
272
  const read = readPackageJson(root);
125
- const bkit = ((read.ok ? read.pkg.bkit : undefined) ?? {}) as Record<string, unknown>;
126
- const worktree = (bkit.worktree ?? {}) as Record<string, unknown>;
273
+ const bkit = record(read.ok ? read.pkg.bkit : undefined);
274
+ const tracker = record(bkit.tracker);
275
+ const cloud = record(bkit.cloud);
276
+ const opencode = record(record(bkit.providers).opencode);
277
+ const testing = record(bkit.testing);
278
+ const workflows = record(bkit.workflows);
279
+ const worktree = record(workflows.worktree);
127
280
  const copy = worktree.copy;
128
- const minFreeGb = ((bkit.disk ?? {}) as Record<string, unknown>).minFreeGb;
129
- const project = bkit.githubProject;
130
- const lanes = bkit.shipGateRequiredLanes;
131
- const book = bkit.minPushPaths;
132
- const provider = bkit.opencodeProvider;
133
- const providers = bkit.opencodeProviders;
134
- const linear = record(bkit.linear);
135
- const jira = record(bkit.jira);
281
+ const minFreeGb = workflows.minFreeGb;
282
+ const lanes = testing.shipGate;
283
+ const book = testing.minPushPaths;
284
+ const provider = opencode.default;
285
+ const providers = opencode.installed;
286
+ const github = record(tracker.github);
287
+ const linear = record(tracker.linear);
288
+ const jira = record(tracker.jira);
289
+ const projectUrl = optionalString(github.project);
136
290
  return {
137
- ciWorkflow: nonEmptyString(bkit.ciWorkflow) ? bkit.ciWorkflow : CONFIG_DEFAULTS.ciWorkflow,
138
- capstoneJob: nonEmptyString(bkit.capstoneJob) ? bkit.capstoneJob : CONFIG_DEFAULTS.capstoneJob,
291
+ ciWorkflow: nonEmptyString(testing.ciWorkflow)
292
+ ? testing.ciWorkflow
293
+ : CONFIG_DEFAULTS.ciWorkflow,
294
+ capstoneJob: nonEmptyString(testing.ciCapstone)
295
+ ? testing.ciCapstone
296
+ : CONFIG_DEFAULTS.capstoneJob,
139
297
  worktreeCopy:
140
298
  Array.isArray(copy) && copy.every(nonEmptyString)
141
299
  ? [...copy]
@@ -146,7 +304,13 @@ export function readBkitConfig(root: string): BkitConfig {
146
304
  typeof minFreeGb === "number" && Number.isFinite(minFreeGb) && minFreeGb >= 0
147
305
  ? minFreeGb
148
306
  : CONFIG_DEFAULTS.diskMinFreeGb,
149
- issueTracker: parseIssueTracker(bkit.issueTracker) ?? CONFIG_DEFAULTS.issueTracker,
307
+ issueTracker: parseIssueTracker(tracker.default) ?? CONFIG_DEFAULTS.issueTracker,
308
+ github: {
309
+ project:
310
+ github.project === false ? false : projectUrl ? parseGithubBoardUrl(projectUrl) : null,
311
+ projectUrl,
312
+ ...trackerStates(github, CONFIG_DEFAULTS.github),
313
+ },
150
314
  linear: {
151
315
  team: optionalString(linear.team),
152
316
  project: optionalString(linear.project),
@@ -157,12 +321,6 @@ export function readBkitConfig(root: string): BkitConfig {
157
321
  project: optionalString(jira.project),
158
322
  ...trackerStates(jira, CONFIG_DEFAULTS.jira),
159
323
  },
160
- githubProject:
161
- project === false
162
- ? false
163
- : project !== null && typeof project === "object" && !Array.isArray(project)
164
- ? (project as Record<string, unknown>)
165
- : null,
166
324
  shipGateRequiredLanes: Array.isArray(lanes) ? lanes.filter(nonEmptyString) : [],
167
325
  // An explicit [] is kept: it switches the min push off.
168
326
  minPushPaths: Array.isArray(book)
@@ -175,13 +333,20 @@ export function readBkitConfig(root: string): BkitConfig {
175
333
  (v): v is OpencodeProvider => typeof v === "string" && isOpencodeProvider(v),
176
334
  )
177
335
  : [],
178
- cloudAgents: parseCloudAgents(bkit.cloudAgents) ?? CONFIG_DEFAULTS.cloudAgents,
179
- depUpdaterOptOut: bkit.depUpdater === "none",
180
- issueTrackerExplicit: bkit.issueTracker !== undefined,
181
- cloudAgentsExplicit: bkit.cloudAgents !== undefined,
336
+ cloudAgents: parseCloudAgents(cloud.agent) ?? CONFIG_DEFAULTS.cloudAgents,
337
+ asks: askSettings(workflows),
338
+ tasks: taskCaps(workflows.tasks),
339
+ depUpdaterOptOut: record(bkit.dependencies).updater === "none",
340
+ issueTrackerExplicit: tracker.default !== undefined && tracker.default !== "",
341
+ cloudAgentsExplicit: cloud.agent !== undefined && cloud.agent !== "",
182
342
  };
183
343
  }
184
344
 
345
+ /** The CI workflow file `bkit.testing.ciWorkflow` names, as `.github/workflows/<file>` relative to `root`. */
346
+ export function ciWorkflowPath(root: string): string {
347
+ return `.github/workflows/${readBkitConfig(root).ciWorkflow}`;
348
+ }
349
+
185
350
  /** Where the wired tracker's issues live, for the workflows' tracker calls. */
186
351
  export interface TrackerScope {
187
352
  /** Linear team key; null under any other tracker or when unset. */
@@ -190,14 +355,18 @@ export interface TrackerScope {
190
355
  trackerProject: string | null;
191
356
  /** Jira site URL (the MCP `cloudId`); null under any other tracker or when unset. */
192
357
  trackerSite: string | null;
358
+ /** GitHub Projects v2 board; null under any other tracker, when off, or when unset. */
359
+ trackerBoard: GithubBoard | null;
193
360
  }
194
361
 
195
362
  export function trackerScope(
196
- cfg: Pick<BkitConfig, "issueTracker" | "linear" | "jira">,
363
+ cfg: Pick<BkitConfig, "issueTracker" | "github" | "linear" | "jira">,
197
364
  ): TrackerScope {
365
+ const none = { trackerTeam: null, trackerProject: null, trackerSite: null, trackerBoard: null };
366
+ if (cfg.issueTracker === "github") return { ...none, trackerBoard: cfg.github.project || null };
198
367
  if (cfg.issueTracker === "linear")
199
- return { trackerTeam: cfg.linear.team, trackerProject: cfg.linear.project, trackerSite: null };
368
+ return { ...none, trackerTeam: cfg.linear.team, trackerProject: cfg.linear.project };
200
369
  if (cfg.issueTracker === "jira")
201
- return { trackerTeam: null, trackerProject: cfg.jira.project, trackerSite: cfg.jira.site };
202
- return { trackerTeam: null, trackerProject: null, trackerSite: null };
370
+ return { ...none, trackerProject: cfg.jira.project, trackerSite: cfg.jira.site };
371
+ return none;
203
372
  }