@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -1,15 +1,18 @@
1
- // bkit issues text|labels|comment — tracker payloads, prepared but never sent.
1
+ // bkit issues text|labels|comment — tracker payloads, and with --post / --write the call itself.
2
2
  //
3
- // The tracker calls stay in the workflows, through MCP: a workflow touches only
4
- // its own issue, and only through the tracker's MCP server. These verbs do the
5
- // arithmetic the workflows stated as prose — which comments count as human input,
6
- // which labels a transition adds and drops, the board update, and the exact text
7
- // of every `###### bkit:generated` comment — so no step re-derives it by hand.
3
+ // These verbs do the arithmetic the workflows stated as prose — which comments count
4
+ // as human input, which labels a transition adds and drops, the board update, and the
5
+ // exact text of every `###### bkit:generated` comment — so no step re-derives it by
6
+ // hand. A workflow touches only its own issue. The tracker I/O goes through
7
+ // `tracker.ts`; when it fails the verb prints `tracker.done: false` and the workflow
8
+ // sends the same payload through the tracker's MCP server.
8
9
  import * as fs from "node:fs";
9
10
  import * as path from "node:path";
10
11
  import { CommandError, EXIT, parseJson, repoRoot, } from "../lib.js";
11
12
  import { readBkitConfig } from "../../shared/settings.js";
12
13
  import { str } from "./status.js";
14
+ import { isCloudOrCi } from "../../checks/before/env.js";
15
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, POST_FLAG, TRACKER_OUTPUT, attempt, classifyFailure, commentFileOf, fetchIssue, moveOnBoard, postForVerb, readBlockers, readLabels, redact, runActionKey, skipOf, stampMarker, trackerTarget, writeLabels, } from "./tracker.js";
13
16
  /** Exit code: an input file is missing or not in the expected shape. */
14
17
  export const EXIT_BAD_INPUT = 3;
15
18
  function readInput(cwd, file, flag) {
@@ -21,30 +24,22 @@ function readInput(cwd, file, flag) {
21
24
  // ---------------------------------------------------------------------------
22
25
  // text
23
26
  // ---------------------------------------------------------------------------
24
- /** First line of every comment bkit posts; such comments are never workflow input. */
25
- export const GENERATED_MARKER = "###### bkit:generated";
27
+ export { GENERATED_MARKER };
26
28
  /** A human writes this as a whole line to discard everything above it. */
27
29
  export const CUT_MARKER = "###### bkit:ignore-earlier";
28
30
  // Whole line only: naming the token inline is prose, not a live marker.
29
31
  const CUT_LINE = /^[ \t]*###### bkit:ignore-earlier[ \t]*\r?$/;
30
- export const isGenerated = (body) => (body.replace(/^\s+/, "").split(/\r?\n/, 1)[0] ?? "").trim() === GENERATED_MARKER;
31
- /** Keep only what follows the LAST whole-line cut marker; the marker itself goes too. */
32
+ // The same cut as Jira's HTML comment page renders it: its own `<h6>` element.
33
+ const CUT_ANY = /^[ \t]*###### bkit:ignore-earlier[ \t]*\r?$|<h6\b[^>]*>\s*bkit:ignore-earlier\s*<\/h6>/gm;
34
+ // The marker as a whole first line (bare or stamped with its hash), or as Jira's HTML `<h6>`.
35
+ const GENERATED_FIRST = /^(?:######[ \t]+bkit:generated(?:[ \t]+[0-9a-f]{12})?[ \t]*$|<h6\b[^>]*>\s*bkit:generated(?:\s+[0-9a-f]{12})?\s*<\/h6>)/;
36
+ export const isGenerated = (body) => GENERATED_FIRST.test(body.replace(/^\s+/, "").split(/\r?\n/, 1)[0] ?? "");
37
+ /** Keep only what follows the LAST cut marker (whole line, or Jira's HTML `<h6>`); the marker itself goes too. */
32
38
  export function cutEarlier(text) {
33
- const lines = text.split("\n");
34
- let last = -1;
35
- lines.forEach((line, i) => {
36
- if (CUT_LINE.test(line))
37
- last = i;
38
- });
39
- if (last === -1)
39
+ const last = [...text.matchAll(CUT_ANY)].at(-1);
40
+ if (last === undefined)
40
41
  return { text, cut: false };
41
- return {
42
- text: lines
43
- .slice(last + 1)
44
- .join("\n")
45
- .replace(/^\s*\n/, ""),
46
- cut: true,
47
- };
42
+ return { text: text.slice(last.index + last[0].length).replace(/^\s*\n/, ""), cut: true };
48
43
  }
49
44
  /**
50
45
  * Comments as an MCP read returns them: a bare array, or one wrapped under
@@ -105,6 +100,24 @@ export function issueText(description, comments) {
105
100
  const { text, cut } = cutEarlier(joined);
106
101
  return { text, kept: human.length, dropped: comments.length - human.length, cut };
107
102
  }
103
+ /**
104
+ * The issue as separate parts, oldest first: the description, then each human comment.
105
+ * The last cut marker drops every part above it and the text above it in its own part;
106
+ * nothing else is dropped.
107
+ */
108
+ export function issueParts(description, comments) {
109
+ const parts = [
110
+ { kind: "description", text: description },
111
+ ...comments
112
+ .filter((c) => !isGenerated(c.body))
113
+ .map((c) => ({ kind: "comment", text: c.body, createdAt: c.createdAt })),
114
+ ];
115
+ const last = parts.map((p) => cutEarlier(p.text).cut).lastIndexOf(true);
116
+ const kept = last === -1
117
+ ? parts
118
+ : [{ ...parts[last], text: cutEarlier(parts[last].text).text }, ...parts.slice(last + 1)];
119
+ return kept.map((p) => ({ ...p, text: p.text.trim() })).filter((p) => p.text !== "");
120
+ }
108
121
  function textVerb(ctx) {
109
122
  const descFile = str(ctx.flags.descriptionFile);
110
123
  const commentsFile = str(ctx.flags.commentsFile);
@@ -178,7 +191,7 @@ export function transitionLabels(current, t) {
178
191
  }
179
192
  /**
180
193
  * The issue state the workflows set for the same transition, on a tracker whose
181
- * board status is the issue state: `bkit.linear` or `bkit.jira`. A shipped
194
+ * board status is the issue state: `bkit.tracker.linear` or `bkit.tracker.jira`. A shipped
182
195
  * or failed issue waits on a human (`review`); a phase starting is `progress`.
183
196
  * The workflows write it alone, so a name the team or project lacks leaves the
184
197
  * labels landed. Null under github (the Projects v2 board moves instead) and
@@ -210,10 +223,10 @@ function onOff(v, flag) {
210
223
  const BOARD_STATES = new Set(["progress", "review"]);
211
224
  /**
212
225
  * The two `projects_write` payloads that move an issue on the Projects v2 board,
213
- * from `bkit.github`. Payload keys are the MCP tool's own argument names: the
226
+ * from `bkit.tracker.github`. Payload keys are the MCP tool's own argument names: the
214
227
  * board item is found by its issue, and Status is set by option name.
215
228
  */
216
- function boardPayload(ctx, status) {
229
+ function boardPayload(ctx, status, target) {
217
230
  const { issueTracker: tracker, github } = readBkitConfig(repoRoot(ctx.cwd));
218
231
  if (tracker !== "github") {
219
232
  if (tracker === "linear" || tracker === "jira")
@@ -227,11 +240,11 @@ function boardPayload(ctx, status) {
227
240
  ctx.log("GitHub project not configured in package.json");
228
241
  return { board: null, boardSkipped: "not-configured" };
229
242
  }
230
- ctx.log(`bkit.github.project "${github.projectUrl}" is not a GitHub Projects board URL`);
243
+ ctx.log(`bkit.tracker.github.project "${github.projectUrl}" is not a GitHub Projects board URL`);
231
244
  return { board: null, boardSkipped: "project-url-invalid" };
232
245
  }
233
- const issue = String(ctx.flags.issue ?? "").replace(/^#/, "");
234
- const ownerRepo = String(ctx.flags.ownerRepo ?? "");
246
+ const issue = (target?.issue ?? String(ctx.flags.issue ?? "")).replace(/^#/, "");
247
+ const ownerRepo = target?.ownerRepo ?? String(ctx.flags.ownerRepo ?? "");
235
248
  const [itemOwner, itemRepo, extra] = ownerRepo.split("/");
236
249
  if (!/^[0-9]+$/.test(issue) || !itemOwner || !itemRepo || extra !== undefined) {
237
250
  throw new CommandError(EXIT.USAGE, "--board needs --issue=<number> and --owner-repo=<owner>/<repo>");
@@ -252,7 +265,8 @@ function boardPayload(ctx, status) {
252
265
  boardSkipped: null,
253
266
  };
254
267
  }
255
- function labelsVerb(ctx) {
268
+ /** The flags of a label transition, checked. */
269
+ function labelTransition(ctx) {
256
270
  const phase = str(ctx.flags.phase);
257
271
  if (phase !== undefined && !PHASE_LABELS.includes(`bkit:${phase}`)) {
258
272
  throw new CommandError(EXIT.USAGE, "--phase must be design, plan, build, debug, ship, or merged");
@@ -264,21 +278,82 @@ function labelsVerb(ctx) {
264
278
  if (board !== undefined && !BOARD_STATES.has(board)) {
265
279
  throw new CommandError(EXIT.USAGE, "--board must be progress or review");
266
280
  }
267
- const t = { phase, failed };
268
- const { add, remove, labels } = transitionLabels(ctx.flags.label ?? [], t);
269
- const { board: payload, boardSkipped } = board === undefined
270
- ? { board: null, boardSkipped: null }
271
- : boardPayload(ctx, board);
272
- ctx.emit({
281
+ return { t: { phase, failed }, board: board };
282
+ }
283
+ /** The printed transition for `current` labels. */
284
+ function transitionOut(ctx, current, t, board) {
285
+ const { add, remove, labels } = transitionLabels(current, t);
286
+ return {
273
287
  add,
274
288
  remove,
275
289
  labels,
276
290
  changed: add.length + remove.length > 0,
277
291
  autoRouteSuffix: labels.includes(AUTO_LABEL) ? AUTO_ROUTE_SUFFIX : "",
278
292
  trackerState: trackerState(t, board, readBkitConfig(repoRoot(ctx.cwd))),
279
- board: payload,
280
- boardSkipped,
293
+ };
294
+ }
295
+ function labelsVerb(ctx) {
296
+ if (ctx.flags.write === true)
297
+ return labelsWrite(ctx);
298
+ const { t, board } = labelTransition(ctx);
299
+ const out = transitionOut(ctx, ctx.flags.label ?? [], t, board);
300
+ const { board: payload, boardSkipped } = board === undefined ? { board: null, boardSkipped: null } : boardPayload(ctx, board);
301
+ ctx.emit({ ...out, board: payload, boardSkipped });
302
+ return EXIT.OK;
303
+ }
304
+ /**
305
+ * `--write`: read the issue's labels, write the transition (and the Linear / Jira
306
+ * state), then move the board item. Each write that fails prints `done: false`
307
+ * with its reason; the workflow sends the printed payload through the MCP instead.
308
+ */
309
+ async function labelsWrite(ctx) {
310
+ const { t, board } = labelTransition(ctx);
311
+ const target = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
312
+ const skip = skipOf(target);
313
+ const given = ctx.flags.label ?? [];
314
+ if (skip) {
315
+ ctx.emit({
316
+ ...transitionOut(ctx, given, t, board),
317
+ board: null,
318
+ boardSkipped: null,
319
+ tracker: skip,
320
+ });
321
+ return EXIT.OK;
322
+ }
323
+ // A malformed board target is a usage error: refused before any label is written.
324
+ let { board: payload, boardSkipped } = board === undefined
325
+ ? { board: null, boardSkipped: null }
326
+ : boardPayload(ctx, board, {
327
+ issue: target.issue ?? "",
328
+ ownerRepo: target.ownerRepo || String(ctx.flags.ownerRepo ?? ""),
329
+ });
330
+ let current = given;
331
+ const read = await attempt("labels", ctx.log, async () => {
332
+ current = await readLabels(target);
281
333
  });
334
+ const out = transitionOut(ctx, current, t, board);
335
+ const tracker = "done" in read && !read.done
336
+ ? read
337
+ : await attempt("labels", ctx.log, () => writeLabels(target, {
338
+ add: out.add,
339
+ remove: out.remove,
340
+ labels: out.labels,
341
+ state: out.trackerState,
342
+ }));
343
+ let boardWrite = null;
344
+ const project = readBkitConfig(repoRoot(ctx.cwd)).github;
345
+ if (payload !== null && board !== undefined && project.project) {
346
+ if (isCloudOrCi()) {
347
+ // A cloud run's token can comment and label but never reach a Projects v2 board.
348
+ payload = null;
349
+ boardSkipped = "cloud";
350
+ }
351
+ else {
352
+ const { owner, number } = project.project;
353
+ boardWrite = await attempt("board", ctx.log, () => moveOnBoard(target, { owner, number, status: project[board] }));
354
+ }
355
+ }
356
+ ctx.emit({ ...out, board: payload, boardSkipped, tracker, boardWrite });
282
357
  return EXIT.OK;
283
358
  }
284
359
  // ---------------------------------------------------------------------------
@@ -297,7 +372,7 @@ const FIELD_LABELS = {
297
372
  verdict: "Verdict",
298
373
  failures: "Failures",
299
374
  scope: "Scope",
300
- subPlan: "Sub-plan",
375
+ group: "Group",
301
376
  attempt: "Attempt",
302
377
  strategy: "Strategy",
303
378
  };
@@ -317,12 +392,9 @@ function headerFields(ctx) {
317
392
  out.push([f.slice(0, eq), f.slice(eq + 1)]);
318
393
  }
319
394
  }
320
- else if (key === "subPlan") {
321
- const count = str(ctx.flags.subPlanCount);
322
- out.push([
323
- "Sub-plan",
324
- `${String(ctx.flags.subPlan)}${count === undefined ? "" : `/${count}`}`,
325
- ]);
395
+ else if (key === "group") {
396
+ const count = str(ctx.flags.groupCount);
397
+ out.push(["Group", `${String(ctx.flags.group)}${count === undefined ? "" : `/${count}`}`]);
326
398
  }
327
399
  else if (FIELD_LABELS[key] !== undefined) {
328
400
  out.push([FIELD_LABELS[key], String(ctx.flags[key])]);
@@ -448,18 +520,19 @@ export function buildComment(cwd, o) {
448
520
  lines.push(readInput(cwd, s.slice(eq + 1), "section").replace(/\n+$/, ""));
449
521
  }
450
522
  // A whole-line cut marker copied in from an artifact would fire on the next
451
- // run's issue text; inline, it is only a mention.
452
- return lines
523
+ // run's issue text; inline, it is only a mention. The marker carries the body's
524
+ // hash, which is how a re-run finds the comment already posted.
525
+ return stampMarker(lines
453
526
  .join("\n")
454
527
  .split("\n")
455
528
  .map((l) => (CUT_LINE.test(l) ? `\`${CUT_MARKER}\`` : l))
456
- .join("\n");
529
+ .join("\n"));
457
530
  }
458
531
  /** `bkit issues comment`'s flags as a `CommentInput`. */
459
532
  export function commentBody(ctx) {
460
533
  const kind = str(ctx.flags.kind) ?? "step";
461
- if (ctx.flags.subPlanCount !== undefined && ctx.flags.subPlan === undefined) {
462
- throw new CommandError(EXIT.USAGE, "--sub-plan-count needs --sub-plan");
534
+ if (ctx.flags.groupCount !== undefined && ctx.flags.group === undefined) {
535
+ throw new CommandError(EXIT.USAGE, "--group-count needs --group");
463
536
  }
464
537
  return buildComment(ctx.cwd, {
465
538
  kind: kind,
@@ -486,14 +559,121 @@ export function commentBody(ctx) {
486
559
  });
487
560
  }
488
561
  // ---------------------------------------------------------------------------
562
+ // fetch / related — issue text straight to files, never through the orchestrator
563
+ // ---------------------------------------------------------------------------
564
+ /** Exit code 80 with the failure's reason, for the verbs that only talk to the tracker. */
565
+ function useMcp(ctx, err) {
566
+ const reason = classifyFailure(err);
567
+ ctx.log(redact(`tracker read failed (${reason}): ${err.message ?? String(err)}`));
568
+ ctx.emit({ reason });
569
+ return EXIT.USE_MCP;
570
+ }
571
+ async function fetchVerb(ctx) {
572
+ const out = str(ctx.flags.sessionDir) || str(ctx.flags.outbox);
573
+ if (!out)
574
+ throw new CommandError(EXIT.USAGE, "give --session-dir or --outbox");
575
+ const t = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
576
+ const skip = skipOf(t);
577
+ if (skip) {
578
+ ctx.emit(skip);
579
+ return EXIT.OK;
580
+ }
581
+ let issue;
582
+ try {
583
+ issue = await fetchIssue(t);
584
+ }
585
+ catch (err) {
586
+ return useMcp(ctx, err);
587
+ }
588
+ const dir = path.resolve(ctx.cwd, out);
589
+ const files = {
590
+ description: path.join(dir, "issue-description.md"),
591
+ comments: path.join(dir, "issue-comments.json"),
592
+ facts: path.join(dir, "issue-facts.json"),
593
+ };
594
+ const facts = { title: issue.title, url: issue.url, state: issue.state, labels: issue.labels };
595
+ fs.mkdirSync(dir, { recursive: true });
596
+ fs.writeFileSync(files.description, issue.body);
597
+ const comments = sortOldestFirst(issue.comments).comments;
598
+ fs.writeFileSync(files.comments, `${JSON.stringify(comments, null, 2)}\n`);
599
+ fs.writeFileSync(files.facts, `${JSON.stringify(facts, null, 2)}\n`);
600
+ ctx.emit({ ...facts, files });
601
+ return EXIT.OK;
602
+ }
603
+ /** Hit ids from a search the orchestrator ran: ids, or objects carrying `number` / `identifier` / `key` / `id`. */
604
+ function readHits(cwd, file) {
605
+ const parsed = parseJson(readInput(cwd, file, "hits-file"));
606
+ const bad = () => new CommandError(EXIT_BAD_INPUT, `--hits-file ${file} is not a JSON list of issue ids`);
607
+ if (!parsed.ok || !Array.isArray(parsed.value))
608
+ throw bad();
609
+ return parsed.value.map((h) => {
610
+ const o = (h ?? {});
611
+ const id = typeof h === "object" ? (o.number ?? o.identifier ?? o.key ?? o.id) : h;
612
+ if (typeof id !== "string" && typeof id !== "number")
613
+ throw bad();
614
+ return String(id).trim().replace(/^#/, "").toUpperCase();
615
+ });
616
+ }
617
+ async function relatedVerb(ctx) {
618
+ const hitsFile = String(ctx.flags.hitsFile);
619
+ const outFile = String(ctx.flags.out);
620
+ const top = ctx.flags.top === undefined ? 10 : Number(ctx.flags.top);
621
+ if (!Number.isInteger(top) || top < 1)
622
+ throw new CommandError(EXIT.USAGE, "--top must be a positive integer");
623
+ const own = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
624
+ const hits = [...new Set(readHits(ctx.cwd, hitsFile))]
625
+ .filter((id) => id !== own.issue)
626
+ .slice(0, top);
627
+ const sections = [];
628
+ for (const id of hits) {
629
+ let issue;
630
+ try {
631
+ issue = await fetchIssue({ ...own, issue: id });
632
+ }
633
+ catch (err) {
634
+ return useMcp(ctx, err);
635
+ }
636
+ const ref = own.tracker === "github" ? `#${id}` : id;
637
+ const { text } = issueText(issue.body, sortOldestFirst(issue.comments).comments);
638
+ sections.push(`## ${ref} — ${issue.title} (${issue.state})${text ? `\n\n${text}` : ""}\n`);
639
+ }
640
+ const body = sections.length === 0 ? "None.\n" : sections.join("\n");
641
+ const abs = path.resolve(ctx.cwd, outFile);
642
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
643
+ fs.writeFileSync(abs, body);
644
+ ctx.emit({ path: outFile, bytes: Buffer.byteLength(body), hits: hits.length });
645
+ return EXIT.OK;
646
+ }
647
+ async function blockedByVerb(ctx) {
648
+ const t = trackerTarget(ctx.cwd, { fid: str(ctx.flags.fid), issue: str(ctx.flags.issue) });
649
+ const skip = skipOf(t);
650
+ if (skip) {
651
+ ctx.emit(skip);
652
+ return EXIT.OK;
653
+ }
654
+ let blockers;
655
+ try {
656
+ blockers = await readBlockers(t);
657
+ }
658
+ catch (err) {
659
+ return useMcp(ctx, err);
660
+ }
661
+ ctx.emit({
662
+ blockers: blockers.map(({ id, state }) => ({ id, state })),
663
+ open: blockers.filter((b) => b.open).length,
664
+ });
665
+ return EXIT.OK;
666
+ }
667
+ // ---------------------------------------------------------------------------
489
668
  // Command
490
669
  // ---------------------------------------------------------------------------
491
670
  export const issuesCommand = {
492
671
  noun: "issues",
493
- summary: "Prepare tracker payloads (issue text, label transitions, comments); MCP sends them.",
672
+ summary: "Tracker payloads (issue text, label transitions, comments); --post / --write send them.",
494
673
  verbs: {
495
674
  text: {
496
675
  summary: "ISSUE_TEXT: description + human comments, after the bkit:ignore-earlier cut.",
676
+ use: "workflow",
497
677
  flags: [
498
678
  { name: "description-file", type: "string", help: "file holding the issue description" },
499
679
  {
@@ -511,8 +691,78 @@ export const issuesCommand = {
511
691
  exitCodes: { [EXIT_BAD_INPUT]: "an input file is missing or not a list of comments" },
512
692
  run: textVerb,
513
693
  },
694
+ fetch: {
695
+ summary: "Read the run's issue into issue-description.md, issue-comments.json and issue-facts.json; prints the facts, never the body.",
696
+ use: "by-hand",
697
+ flags: [
698
+ { name: "fid", type: "string", help: "the run's FID (names the issue)" },
699
+ { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
700
+ { name: "session-dir", type: "string", help: "write the three files here" },
701
+ {
702
+ name: "outbox",
703
+ type: "string",
704
+ help: "write the three files here (instead of --session-dir)",
705
+ },
706
+ ],
707
+ output: {
708
+ title: "issue title",
709
+ url: "issue URL",
710
+ state: "tracker state name (GitHub: open | closed)",
711
+ labels: "label names",
712
+ files: "{description, comments, facts}: raw description, comments oldest first as JSON, {title, url, state, labels} as JSON",
713
+ skipped: "no-issue | tracker-none: nothing read, nothing written",
714
+ reason: "exit 80: network | auth | scope | rate-limit | not-found | http-<n>; read the issue via the tracker MCP",
715
+ },
716
+ exitCodes: {},
717
+ run: fetchVerb,
718
+ },
719
+ related: {
720
+ summary: "Fetch each hit of the orchestrator's related-issue search and write the related-issues file.",
721
+ use: "workflow",
722
+ flags: [
723
+ {
724
+ name: "hits-file",
725
+ type: "string",
726
+ required: true,
727
+ help: "JSON list of hit ids (or objects with number / identifier / key) in rank order",
728
+ },
729
+ { name: "out", type: "string", required: true, help: "the related-issues file to write" },
730
+ { name: "top", type: "string", help: "keep the first N hits (default 10)" },
731
+ {
732
+ name: "fid",
733
+ type: "string",
734
+ help: "the run's FID: its own issue is dropped from the hits",
735
+ },
736
+ { name: "issue", type: "string", help: "the run's issue id (instead of --fid)" },
737
+ ],
738
+ output: {
739
+ path: "the file written: one `## {ref} — {title} ({state})` section per hit, else `None.`",
740
+ bytes: "its size in bytes",
741
+ hits: "hits fetched",
742
+ reason: "exit 80: why a hit could not be read; nothing was written",
743
+ },
744
+ exitCodes: { [EXIT_BAD_INPUT]: "--hits-file is missing or not a JSON list of issue ids" },
745
+ run: relatedVerb,
746
+ },
747
+ "blocked-by": {
748
+ summary: "The issues blocking the run's issue, with their states and the ones still open.",
749
+ use: "by-hand",
750
+ flags: [
751
+ { name: "fid", type: "string", help: "the run's FID (names the issue)" },
752
+ { name: "issue", type: "string", help: "the issue id (instead of --fid)" },
753
+ ],
754
+ output: {
755
+ blockers: "[{id, state}]: GitHub from the body's bkit:blocked-by block, Linear from blocks relations, Jira from is-blocked-by links",
756
+ open: "how many blockers are not closed / done / canceled (0 = unblocked)",
757
+ skipped: "no-issue | tracker-none: nothing read",
758
+ reason: "exit 80: network | auth | scope | rate-limit | not-found | http-<n>; read the blockers via the tracker MCP",
759
+ },
760
+ exitCodes: {},
761
+ run: blockedByVerb,
762
+ },
514
763
  labels: {
515
764
  summary: "Label arithmetic for a transition, the tracker state, and the board payload.",
765
+ use: "workflow",
516
766
  flags: [
517
767
  { name: "label", type: "string", repeatable: true, help: "a label the issue carries now" },
518
768
  {
@@ -526,8 +776,18 @@ export const issuesCommand = {
526
776
  type: "string",
527
777
  help: "also move the Projects v2 item: progress | review",
528
778
  },
529
- { name: "issue", type: "string", help: "issue number (with --board)" },
779
+ {
780
+ name: "issue",
781
+ type: "string",
782
+ help: "issue number (with --board); with --write, the issue to write (instead of --fid)",
783
+ },
530
784
  { name: "owner-repo", type: "string", help: "<owner>/<repo> of the issue (with --board)" },
785
+ {
786
+ name: "write",
787
+ type: "boolean",
788
+ help: "read the issue's labels, write the transition and state, move the board; prints `tracker` and `boardWrite`",
789
+ },
790
+ { name: "fid", type: "string", help: "with --write: the run's FID (names the issue)" },
531
791
  ],
532
792
  output: {
533
793
  add: "labels to add",
@@ -537,12 +797,15 @@ export const issuesCommand = {
537
797
  autoRouteSuffix: `"${AUTO_ROUTE_SUFFIX}" when the label set carries ${AUTO_LABEL}, else ""`,
538
798
  trackerState: "Linear or Jira issue state for this transition, from package.json; null under github, none, or no state move",
539
799
  board: "projects_write payloads {addItem, updateItem}, or null",
540
- boardSkipped: "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name>",
800
+ boardSkipped: "why board is null with --board: opted-out | not-configured | project-url-invalid | tracker-<name> | cloud (--write on a cloud or CI runtime: the next local run moves it)",
801
+ tracker: "with --write: the label (and state) write: {done: true, action: labels} | {done: false, action, reason} (write `labels` / `trackerState` via the tracker MCP) | {skipped}",
802
+ boardWrite: "with --write and a board payload: {done: true, action: board} | {done: false, action, reason} (send `board` via the MCP); null when nothing to move",
541
803
  },
542
804
  run: labelsVerb,
543
805
  },
544
806
  comment: {
545
807
  summary: "The exact body of a ###### bkit:generated step, failure, handover, or audit comment.",
808
+ use: "workflow",
546
809
  flags: [
547
810
  { name: "kind", type: "string", help: "step (default) | failure | handover | audit" },
548
811
  { name: "audit-slug", type: "string", help: "audit: template slug, e.g. security" },
@@ -557,8 +820,8 @@ export const issuesCommand = {
557
820
  { name: "verdict", type: "string", help: "header field Verdict" },
558
821
  { name: "failures", type: "string", help: "header field Failures" },
559
822
  { name: "scope", type: "string", help: "header field Scope" },
560
- { name: "sub-plan", type: "string", help: "header field Sub-plan (x of x/y)" },
561
- { name: "sub-plan-count", type: "string", help: "y of Sub-plan x/y" },
823
+ { name: "group", type: "string", help: "header field Group (x of x/y)" },
824
+ { name: "group-count", type: "string", help: "y of Group x/y" },
562
825
  { name: "attempt", type: "string", help: "header field Attempt" },
563
826
  { name: "strategy", type: "string", help: "header field Strategy" },
564
827
  {
@@ -599,13 +862,40 @@ export const issuesCommand = {
599
862
  type: "string",
600
863
  help: "failure: captured stderr (last 20 lines kept)",
601
864
  },
865
+ POST_FLAG,
866
+ { name: "fid", type: "string", help: "with --post: the run's FID (names the issue)" },
867
+ { name: "issue", type: "string", help: "with --post: the issue id (instead of --fid)" },
868
+ {
869
+ name: "file",
870
+ type: "string",
871
+ help: "with --post: the run's status.jsonl; the post is recorded there and a re-run of the same comment is deduped by that row",
872
+ },
602
873
  ],
603
- output: { comment: "the comment body" },
874
+ output: {
875
+ comment: "the comment body",
876
+ commentFile: COMMENT_FILE_OUTPUT,
877
+ tracker: TRACKER_OUTPUT,
878
+ },
604
879
  exitCodes: {
605
880
  [EXIT_BAD_INPUT]: "a --body-file / --section / --stderr-file / --error-file file is missing",
606
881
  },
607
- run: (ctx) => {
608
- ctx.emit({ comment: commentBody(ctx) });
882
+ run: async (ctx) => {
883
+ const comment = commentBody(ctx);
884
+ const commentFile = commentFileOf(ctx.cwd, comment);
885
+ if (ctx.flags.post !== true) {
886
+ ctx.emit({ comment, commentFile });
887
+ return EXIT.OK;
888
+ }
889
+ const file = str(ctx.flags.file)
890
+ ? path.resolve(ctx.cwd, String(ctx.flags.file))
891
+ : undefined;
892
+ const key = runActionKey(file, str(ctx.flags.workflow), str(ctx.flags.kind) ?? "step", str(ctx.flags.stepNumber), str(ctx.flags.subStep), str(ctx.flags.attempt));
893
+ const tracker = await postForVerb(ctx, comment, {
894
+ fid: str(ctx.flags.fid),
895
+ issue: str(ctx.flags.issue),
896
+ ...(key === undefined ? {} : { file, key }),
897
+ });
898
+ ctx.emit({ comment, commentFile, tracker });
609
899
  return EXIT.OK;
610
900
  },
611
901
  },