@cbartens/bkit 6.0.0 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -2,7 +2,7 @@
2
2
  // task blocks between lowercase HTML-comment markers, each task's uppercase fields.
3
3
  //
4
4
  // <!-- bkit:group N start -->
5
- // ### GROUP N: {title}
5
+ // ### TASK GROUP N: {title} (`### GROUP N: {title}` is read too)
6
6
  // <!-- bkit:task M start -->
7
7
  // - [ ] **TASK M:** {title}
8
8
  // - **UPDATE:** `symbol` in `file`: what changes
@@ -31,6 +31,10 @@ export const PLAN_FIELDS = [
31
31
  ] as const;
32
32
  export type PlanField = (typeof PLAN_FIELDS)[number];
33
33
 
34
+ /** Why every plan reader (`tests`, `tasks`, `ledgers triage`) refuses a plan with no task blocks. */
35
+ export const NO_MARKERS_REASON =
36
+ "this plan has no task markers; run /bkit-build again to convert it";
37
+
34
38
  /** A CREATE / READ / UPDATE / DELETE line: `` `symbol` in `file`: what ``, or `` `file`: what ``. */
35
39
  export interface PlanRef {
36
40
  /** Absent on the file-only form. A Markdown section is `§ heading text`. */
@@ -56,7 +60,7 @@ export interface PlanTestFirst {
56
60
  malformed: number[];
57
61
  }
58
62
 
59
- /** An owner-accepted test-order gap: the tests it covers and its 1-based plan lines. */
63
+ /** An owner-accepted missing red: the tests it covers and its 1-based plan lines. */
60
64
  export interface PlanTestException {
61
65
  tests: PlanTest[];
62
66
  lines: number[];
@@ -128,13 +132,11 @@ const tableCells = (row: string) =>
128
132
  .map((c) => c.trim());
129
133
 
130
134
  /**
131
- * The plan's Reuse Inventory: the first table under the first heading naming Reuse
132
- * Inventory, before the next heading of the same or a higher level. Each row's `File`
133
- * cell gives its backticked paths, normalised. No heading, table or `File` column → null.
135
+ * The first table under the first heading matching `heading`, before the next heading of
136
+ * the same or a higher level: the header line's index and its cells. No heading or table → null.
134
137
  */
135
- export function reuseInventory(text: string): ReuseInventory | null {
136
- const lines = text.split(/\r?\n/);
137
- const start = lines.findIndex((l) => /^#{2,4} .*Reuse Inventory/i.test(l));
138
+ function firstTable(lines: string[], heading: RegExp): { head: number; cols: string[] } | null {
139
+ const start = lines.findIndex((l) => heading.test(l));
138
140
  if (start < 0) return null;
139
141
  const level = /^#+/.exec(lines[start]!)![0].length;
140
142
  const ends = (l: string) => new RegExp(`^#{1,${level}} `).test(l);
@@ -145,12 +147,23 @@ export function reuseInventory(text: string): ReuseInventory | null {
145
147
  break;
146
148
  }
147
149
  if (head < 0) return null;
148
- const cols = tableCells(lines[head]!);
149
- const file = cols.findIndex((c) => /^file\b/i.test(c));
150
- const decision = cols.findIndex((c) => /^decision\b/i.test(c));
150
+ return { head, cols: tableCells(lines[head]!) };
151
+ }
152
+
153
+ /**
154
+ * The plan's Reuse Inventory: the first table under the first heading naming Reuse
155
+ * Inventory, before the next heading of the same or a higher level. Each row's `File`
156
+ * cell gives its backticked paths, normalised. No heading, table or `File` column → null.
157
+ */
158
+ export function reuseInventory(text: string): ReuseInventory | null {
159
+ const lines = text.split(/\r?\n/);
160
+ const table = firstTable(lines, /^#{2,4} .*Reuse Inventory/i);
161
+ if (table === null) return null;
162
+ const file = table.cols.findIndex((c) => /^file\b/i.test(c));
163
+ const decision = table.cols.findIndex((c) => /^decision\b/i.test(c));
151
164
  if (file < 0) return null;
152
165
  const rows: InventoryRow[] = [];
153
- for (let i = head + 2; i < lines.length && /^\s*\|/.test(lines[i]!); i++) {
166
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]!); i++) {
154
167
  const cells = tableCells(lines[i]!);
155
168
  rows.push({
156
169
  line: lines[i]!,
@@ -160,7 +173,103 @@ export function reuseInventory(text: string): ReuseInventory | null {
160
173
  decision: decision < 0 ? "" : (cells[decision] ?? ""),
161
174
  });
162
175
  }
163
- return { head: lines.slice(head, head + 2), rows };
176
+ return { head: lines.slice(table.head, table.head + 2), rows };
177
+ }
178
+
179
+ /** One `Derived Test Matrix` row: its cells, its line, and the tasks its `Task` cell names. */
180
+ export interface MatrixRow {
181
+ /** The row as written. */
182
+ line: string;
183
+ /** 1-based plan line. */
184
+ number: number;
185
+ /** The row's cells, in header order. */
186
+ cells: string[];
187
+ /** The task numbers its `Task` cell names. */
188
+ tasks: number[];
189
+ }
190
+
191
+ /** The plan's `Derived Test Matrix` table: its header, the `Task` column and its rows. */
192
+ export interface DerivedTestMatrix {
193
+ /** The header and separator lines. */
194
+ head: string[];
195
+ /** 1-based line of the header row. */
196
+ line: number;
197
+ /** The `Task` column's index; null when the header carries none. */
198
+ taskColumn: number | null;
199
+ rows: MatrixRow[];
200
+ }
201
+
202
+ /** One `Supersession Inventory` row: its line and the backticked paths it names. */
203
+ export interface SupersessionRow {
204
+ /** The row as written. */
205
+ line: string;
206
+ /** 1-based plan line. */
207
+ number: number;
208
+ /** The row's backticked paths, normalised. */
209
+ files: string[];
210
+ }
211
+
212
+ /** The plan's `Derived Test Matrix` over `tableCells`; null when the plan has no such table. */
213
+ export function derivedTestMatrix(text: string): DerivedTestMatrix | null {
214
+ const lines = text.split(/\r?\n/);
215
+ const table = firstTable(lines, /^#{2,4} .*Derived Test Matrix/i);
216
+ if (table === null) return null;
217
+ const column = table.cols.findIndex((c) => /^task\b/i.test(c));
218
+ const rows: MatrixRow[] = [];
219
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]!); i++) {
220
+ const cells = tableCells(lines[i]!);
221
+ rows.push({
222
+ line: lines[i]!,
223
+ number: i + 1,
224
+ cells,
225
+ tasks: column < 0 ? [] : [...(cells[column] ?? "").matchAll(/\d+/g)].map((m) => Number(m[0])),
226
+ });
227
+ }
228
+ return {
229
+ head: lines.slice(table.head, table.head + 2),
230
+ line: table.head + 1,
231
+ taskColumn: column < 0 ? null : column,
232
+ rows,
233
+ };
234
+ }
235
+
236
+ /** The plan's `Supersession Inventory` rows over `tableCells`; null when the plan has no such table. */
237
+ export function supersessionInventory(text: string): SupersessionRow[] | null {
238
+ const lines = text.split(/\r?\n/);
239
+ const table = firstTable(lines, /^#{2,4} .*Supersession Inventory/i);
240
+ if (table === null) return null;
241
+ const column = table.cols.findIndex((c) => /^existing\b/i.test(c));
242
+ const rows: SupersessionRow[] = [];
243
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]!); i++) {
244
+ const cells = tableCells(lines[i]!);
245
+ rows.push({
246
+ line: lines[i]!,
247
+ number: i + 1,
248
+ files: spansOf(cells[column < 0 ? 0 : column] ?? "").map((f) => path.posix.normalize(f)),
249
+ });
250
+ }
251
+ return rows;
252
+ }
253
+
254
+ /** One `Out of Scope` row: the line as written, its 1-based line, and its cells. */
255
+ export interface OutOfScopeRow {
256
+ /** The row as written. */
257
+ line: string;
258
+ /** 1-based plan line. */
259
+ number: number;
260
+ /** The row's cells, in header order. */
261
+ cells: string[];
262
+ }
263
+
264
+ /** The plan's `Out of Scope` rows over `tableCells`; null when the plan has no such table. */
265
+ export function outOfScope(text: string): OutOfScopeRow[] | null {
266
+ const lines = text.split(/\r?\n/);
267
+ const table = firstTable(lines, /^#{2,4} .*Out of Scope/i);
268
+ if (table === null) return null;
269
+ const rows: OutOfScopeRow[] = [];
270
+ for (let i = table.head + 2; i < lines.length && /^\s*\|/.test(lines[i]!); i++)
271
+ rows.push({ line: lines[i]!, number: i + 1, cells: tableCells(lines[i]!) });
272
+ return rows;
164
273
  }
165
274
 
166
275
  /** The error for a code fence opened at `line` and never closed. */
@@ -176,7 +285,7 @@ const SINGLE_FIELDS: ReadonlySet<PlanField> = new Set([
176
285
  ]);
177
286
 
178
287
  const MARKER = /^\s*<!--\s*bkit:(group|task)\s+(\d+)\s+(start|end)\s*-->\s*$/;
179
- const GROUP_HEAD = /^###\s+GROUP\s+(\d+):\s*(.*)$/;
288
+ const GROUP_HEAD = /^###\s+(?:TASK\s+)?GROUP\s+(\d+):\s*(.*)$/;
180
289
  const TASK_HEAD = /^\s*- \[([ xX])\] \*\*TASK (\d+):\*\*\s*(.*)$/;
181
290
  const LABEL_LINE = /^(\s*)(?:- )?\*\*([A-Za-z][A-Za-z -]*?):\*\*\s*(.*)$/;
182
291
  const SUB_BULLET = /^(\s*)- (.*)$/;
@@ -389,7 +498,7 @@ export function parsePlanBlocks(text: string): PlanBlocks {
389
498
  if (h === null)
390
499
  err(
391
500
  n,
392
- `GROUP ${want.n} (line ${want.line}) is not followed by \`### GROUP ${want.n}: {title}\``,
501
+ `GROUP ${want.n} (line ${want.line}) is not followed by \`### TASK GROUP ${want.n}: {title}\``,
393
502
  );
394
503
  else if (Number(h[1]) !== want.n)
395
504
  err(
@@ -0,0 +1,257 @@
1
+ // bkit plans parse|comment — design Step 11: read the organised design's
2
+ // `## Suggested Workstreams` and `## Suggested Plans` and build the advisory comment
3
+ // for the feature's own issue.
4
+ //
5
+ // A workstream is a logical unit of the design; a plan is the filed unit (one issue,
6
+ // one plan doc, one branch / PR) covering one or more workstreams. Advisory only.
7
+ // Workflows never create tracker issues, comment on another issue, or set blockers,
8
+ // so nothing here matches plans to issues or builds blocked-by bodies. The tracker
9
+ // write itself stays an MCP call in the workflow; this prepares its body.
10
+
11
+ import * as fs from "node:fs";
12
+ import * as path from "node:path";
13
+
14
+ import { CommandError, EXIT, type CommandSpec, type FlagSpec, type RunContext } from "../lib.js";
15
+ import { COMMENT_FILE_OUTPUT, GENERATED_MARKER, commentFileOf, stampMarker } from "./tracker.js";
16
+
17
+ /** Exit code: no workstream parsed — the workflow's Failure Path. */
18
+ export const EXIT_NONE = 3;
19
+
20
+ export interface Workstream {
21
+ /** `WS-{N}`. */
22
+ id: string;
23
+ n: number;
24
+ name: string;
25
+ /** Workstream ids this one requires; [] for a root workstream. */
26
+ requires: string[];
27
+ /** The Requires value as written. */
28
+ requiresText: string;
29
+ }
30
+
31
+ export interface Plan {
32
+ /** `P-{N}`. */
33
+ id: string;
34
+ n: number;
35
+ name: string;
36
+ /** Workstream ids this plan covers. */
37
+ covers: string[];
38
+ /** Plan ids this one requires; [] for a root plan. */
39
+ requires: string[];
40
+ /** The Requires value as written. */
41
+ requiresText: string;
42
+ }
43
+
44
+ const HEADING = /^(#{1,6})\s+(.*?)\s*$/;
45
+ const INLINE = /^\W*(Requires|Covers)\W*:\**\s*(.*)$/i;
46
+
47
+ interface Block {
48
+ n: number;
49
+ name: string;
50
+ /** Lowercased `####` subsection (or inline `Requires:` / `Covers:` label) → its first value line. */
51
+ fields: Record<string, string>;
52
+ }
53
+
54
+ /**
55
+ * Every `### {PREFIX}-{N}: {NAME}` block under the LAST `## {title}` heading (the
56
+ * organise step appends it after a verbatim copy of the design), with the first
57
+ * value line of each `####` subsection. An inline `Requires: [...]` or `Covers: [...]`
58
+ * line directly under the block heading is read too.
59
+ */
60
+ function sectionBlocks(md: string, title: string, prefix: string): Block[] {
61
+ const lines = md.split("\n");
62
+ let start = -1;
63
+ lines.forEach((l, i) => {
64
+ if (new RegExp(`^##\\s+${title}\\s*$`).test(l)) start = i;
65
+ });
66
+ if (start === -1) return [];
67
+ const blockHeading = new RegExp(`^###\\s+${prefix}-(\\d+):\\s*(.*?)\\s*$`);
68
+ const out: Block[] = [];
69
+ let current: Block | undefined;
70
+ /** The `####` subsection the line sits in; undefined directly under the block heading. */
71
+ let sub: string | undefined;
72
+ for (const line of lines.slice(start + 1)) {
73
+ const h = HEADING.exec(line);
74
+ if (h && h[1]!.length <= 2) break;
75
+ const b = blockHeading.exec(line);
76
+ if (b) {
77
+ current = { n: Number(b[1]), name: b[2]!, fields: {} };
78
+ sub = undefined;
79
+ out.push(current);
80
+ continue;
81
+ }
82
+ if (!current) continue;
83
+ if (h) {
84
+ sub = h[2]!.toLowerCase();
85
+ continue;
86
+ }
87
+ const inline = sub === undefined ? INLINE.exec(line) : null;
88
+ const key = sub ?? inline?.[1]!.toLowerCase();
89
+ const value = (sub === undefined ? inline?.[2] : line)?.trim();
90
+ if (key !== undefined && value && current.fields[key] === undefined)
91
+ current.fields[key] = value;
92
+ }
93
+ return out;
94
+ }
95
+
96
+ const ids = (text: string, prefix: string) => text.match(new RegExp(`${prefix}-\\d+`, "g")) ?? [];
97
+
98
+ /** Every `### WS-{N}: {NAME}` block under the last `## Suggested Workstreams`, with its `Requires`. */
99
+ export function parseWorkstreams(md: string): Workstream[] {
100
+ return sectionBlocks(md, "Suggested Workstreams", "WS").map((b) => {
101
+ const requiresText = b.fields.requires ?? "";
102
+ return {
103
+ id: `WS-${b.n}`,
104
+ n: b.n,
105
+ name: b.name,
106
+ requires: ids(requiresText, "WS"),
107
+ requiresText,
108
+ };
109
+ });
110
+ }
111
+
112
+ /**
113
+ * Every `### P-{N}: {NAME}` block under the last `## Suggested Plans`, with its
114
+ * `Covers` and `Requires`. A design with no plan block yields one plan per
115
+ * workstream: `P-{N}` covers `WS-{N}`, its `Requires` mapped to plan ids.
116
+ */
117
+ export function parsePlans(md: string): Plan[] {
118
+ const plans = sectionBlocks(md, "Suggested Plans", "P").map((b) => {
119
+ const requiresText = b.fields.requires ?? "";
120
+ return {
121
+ id: `P-${b.n}`,
122
+ n: b.n,
123
+ name: b.name,
124
+ covers: ids(b.fields.covers ?? "", "WS"),
125
+ requires: ids(requiresText, "P"),
126
+ requiresText,
127
+ };
128
+ });
129
+ if (plans.length > 0) return plans;
130
+ return parseWorkstreams(md).map((w) => ({
131
+ id: `P-${w.n}`,
132
+ n: w.n,
133
+ name: w.name,
134
+ covers: [w.id],
135
+ requires: w.requires.map((r) => r.replace("WS-", "P-")),
136
+ requiresText: w.requiresText.replace(/WS-(\d+)/g, "P-$1"),
137
+ }));
138
+ }
139
+
140
+ /** `[]` or `[P-1, P-2]`. */
141
+ export const requiresList = (p: Plan) => `[${p.requires.join(", ")}]`;
142
+
143
+ /** `WS-1 (Data model), WS-2 (API)`: a plan's covered workstreams with their names. */
144
+ export function coversList(p: Plan, ws: Workstream[]): string {
145
+ return p.covers
146
+ .map((id) => {
147
+ const name = ws.find((w) => w.id === id)?.name;
148
+ return name === undefined ? id : `${id} (${name})`;
149
+ })
150
+ .join(", ");
151
+ }
152
+
153
+ /**
154
+ * The Step 11 comment: one line per plan with its covered workstreams, the filing
155
+ * line (one issue per plan; a single plan is planned on this issue), then the design
156
+ * doc link.
157
+ */
158
+ export function commentBody(
159
+ plans: Plan[],
160
+ ws: Workstream[],
161
+ opts: { ownerRepo: string; month: string; fid: string },
162
+ ): string {
163
+ const doc = `docs/plans/${opts.month}/${opts.fid}-design.md`;
164
+ const url = `https://github.com/${opts.ownerRepo}/blob/dev/${doc}`;
165
+ const filing =
166
+ plans.length === 1
167
+ ? "One plan covers every workstream: plan it on this issue, no new issue."
168
+ : `Filing one issue per plan: put \`**Parent design:** [${opts.fid}-design.md](${url})\` and \`**Workstreams:** {its Covers ids}\` in its body, and list the plan issues it requires in a blocked-by block (.bkit/trackers.md § Issue shapes).`;
169
+ const lines = [
170
+ GENERATED_MARKER,
171
+ "### Step 11 — Suggested Plans",
172
+ "Advisory only. NEVER auto-trigger.",
173
+ ...plans.map(
174
+ (p) => `- ${p.id}: ${p.name}. Covers: ${coversList(p, ws)}. Requires: ${requiresList(p)}`,
175
+ ),
176
+ filing,
177
+ `[${doc}](${url})`,
178
+ ];
179
+ return stampMarker(lines.join("\n"));
180
+ }
181
+
182
+ const ARTIFACT_FLAG: FlagSpec = {
183
+ name: "artifact",
184
+ type: "string",
185
+ required: true,
186
+ help: "the organised design, docs/plans/{YYYYMM}/logs/{FID}/design-v3-organised.md",
187
+ };
188
+
189
+ function read(ctx: RunContext): { workstreams: Workstream[]; plans: Plan[] } {
190
+ const file = path.resolve(ctx.cwd, String(ctx.flags.artifact));
191
+ if (!fs.existsSync(file)) throw new CommandError(EXIT.USAGE, `--artifact ${file} does not exist`);
192
+ const md = fs.readFileSync(file, "utf-8");
193
+ const workstreams = parseWorkstreams(md);
194
+ if (workstreams.length === 0) {
195
+ throw new CommandError(
196
+ EXIT_NONE,
197
+ `no "### WS-{N}: {NAME}" block under "## Suggested Workstreams" in ${file}`,
198
+ );
199
+ }
200
+ return { workstreams, plans: parsePlans(md) };
201
+ }
202
+
203
+ export const plansCommand: CommandSpec = {
204
+ noun: "plans",
205
+ summary:
206
+ "Parse the organised design's suggested plans and workstreams and build the advisory comment.",
207
+ verbs: {
208
+ parse: {
209
+ summary:
210
+ "List each P-{N} with its name, Covers and Requires; one plan per workstream when the design has no Suggested Plans.",
211
+ use: "by-hand",
212
+ flags: [ARTIFACT_FLAG],
213
+ output: {
214
+ plans: "[{id, n, name, covers, requires, requiresText}] in file order",
215
+ workstreams: "[{id, n, name, requires, requiresText}] in file order",
216
+ },
217
+ exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
218
+ run: (ctx) => {
219
+ const { workstreams, plans } = read(ctx);
220
+ ctx.emit({ plans, workstreams });
221
+ return EXIT.OK;
222
+ },
223
+ },
224
+ comment: {
225
+ summary:
226
+ "The Step 11 comment body for the feature's own issue (posted via MCP by the workflow).",
227
+ use: "workflow",
228
+ flags: [
229
+ ARTIFACT_FLAG,
230
+ { name: "fid", type: "string", required: true, help: "feature id" },
231
+ { name: "month", type: "string", required: true, help: "YYYYMM bucket of the design doc" },
232
+ {
233
+ name: "owner-repo",
234
+ type: "string",
235
+ required: true,
236
+ help: "owner/repo for the design doc link",
237
+ },
238
+ ],
239
+ output: {
240
+ comment: "the comment body",
241
+ commentFile: COMMENT_FILE_OUTPUT,
242
+ plans: "the parsed plans",
243
+ },
244
+ exitCodes: { [EXIT_NONE]: "no workstream parsed (Failure Path)" },
245
+ run: (ctx) => {
246
+ const { workstreams, plans } = read(ctx);
247
+ const body = commentBody(plans, workstreams, {
248
+ ownerRepo: String(ctx.flags.ownerRepo),
249
+ month: String(ctx.flags.month),
250
+ fid: String(ctx.flags.fid),
251
+ });
252
+ ctx.emit({ comment: body, commentFile: commentFileOf(ctx.cwd, body), plans });
253
+ return EXIT.OK;
254
+ },
255
+ },
256
+ },
257
+ };
@@ -539,9 +539,9 @@ export function devRequiresChecks(gh: (args: string[]) => GhResult, repo: string
539
539
  }
540
540
 
541
541
  /**
542
- * Request a server-side base-into-head refresh (ship Step 4 B1). GitHub authors
543
- * the merge commit, so bkit cannot set its message and there is no local head to
544
- * read back — ship's Step 9 poll observes the new head. gh missing →
542
+ * Request a server-side base-into-head refresh. GitHub authors the merge commit,
543
+ * so bkit cannot set its message and there is no local head to read back. Ship
544
+ * does not call it: its Step 4 merges origin/dev locally (`branches sync --merge`). gh missing →
545
545
  * EXIT.USE_MCP (route through `update_pull_request_branch`).
546
546
  *
547
547
  * `onlyIfRequired`: refresh only when dev requires status checks. Otherwise the
@@ -898,6 +898,7 @@ export const prsCommand: CommandSpec = {
898
898
  verbs: {
899
899
  open: {
900
900
  summary: "Open a PR whose body carries the bkit:issue / bkit:fid marker (exit 80: use MCP).",
901
+ use: "workflow",
901
902
  flags: [
902
903
  { name: "fid", type: "string", required: true, help: "feature id" },
903
904
  { name: "title", type: "string", required: true, help: "PR title (no skip-CI token)" },
@@ -957,6 +958,7 @@ export const prsCommand: CommandSpec = {
957
958
  },
958
959
  probe: {
959
960
  summary: "The open (or open-then-merged) PR for a branch, or one PR by number.",
961
+ use: "by-hand",
960
962
  flags: [
961
963
  HEAD_FLAG,
962
964
  { name: "base", type: "string", help: "only PRs into this base (default: any base)" },
@@ -996,6 +998,7 @@ export const prsCommand: CommandSpec = {
996
998
  merge: {
997
999
  summary:
998
1000
  "Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back.",
1001
+ use: "workflow",
999
1002
  flags: [
1000
1003
  { name: "number", type: "string", required: true, help: "the PR number" },
1001
1004
  {
@@ -1072,6 +1075,7 @@ export const prsCommand: CommandSpec = {
1072
1075
  "update-branch": {
1073
1076
  summary:
1074
1077
  "Refresh a PR's head from its base server-side (exit 80: use update_pull_request_branch).",
1078
+ use: "workflow",
1075
1079
  flags: [
1076
1080
  { name: "number", type: "string", required: true, help: "the PR number" },
1077
1081
  {
@@ -1102,6 +1106,7 @@ export const prsCommand: CommandSpec = {
1102
1106
  checks: {
1103
1107
  summary:
1104
1108
  "A PR's check rollup, classified: green when present and none failed or pending (exit 80: use MCP).",
1109
+ use: "by-hand",
1105
1110
  flags: [{ name: "number", type: "string", required: true, help: "the PR number" }],
1106
1111
  output: {
1107
1112
  number: "the PR number",
@@ -1127,6 +1132,7 @@ export const prsCommand: CommandSpec = {
1127
1132
  "verbose-ci": {
1128
1133
  summary:
1129
1134
  "Add ` bkit [verbose ci]` to a PR title, or strip it (with an optional `bkit ` prefix); a no-op when already so.",
1135
+ use: "workflow",
1130
1136
  flags: [
1131
1137
  { name: "number", type: "string", required: true, help: "the PR number" },
1132
1138
  { name: "state", type: "string", required: true, help: "on | off" },
@@ -1179,6 +1185,7 @@ export const prsCommand: CommandSpec = {
1179
1185
  },
1180
1186
  "scan-body": {
1181
1187
  summary: "Check a landed commit's body (not its subject) for a CI-suppressing token.",
1188
+ use: "by-hand",
1182
1189
  flags: [
1183
1190
  { name: "sha", type: "string", required: true, help: "the landed commit" },
1184
1191
  {
@@ -1197,6 +1204,7 @@ export const prsCommand: CommandSpec = {
1197
1204
  },
1198
1205
  "cross-check": {
1199
1206
  summary: "An mcp close with gh recorded unavailable must have a transport-fallback row.",
1207
+ use: "workflow",
1200
1208
  flags: [
1201
1209
  FILE_FLAG,
1202
1210
  {
@@ -1217,6 +1225,7 @@ export const prsCommand: CommandSpec = {
1217
1225
  },
1218
1226
  "transport-row": {
1219
1227
  summary: "Append a transport-fallback or close-transport audit row to status.jsonl.",
1228
+ use: "workflow",
1220
1229
  flags: [
1221
1230
  FILE_FLAG,
1222
1231
  { name: "kind", type: "string", required: true, help: "fallback | close" },
@@ -136,6 +136,7 @@ export const repoCommand: CommandSpec = {
136
136
  info: {
137
137
  summary:
138
138
  "owner/repo (gh, else the origin remote), the current branch, and commits behind origin/dev.",
139
+ use: "by-hand",
139
140
  flags: [
140
141
  {
141
142
  name: "fetch",
@@ -180,6 +181,10 @@ export const repoCommand: CommandSpec = {
180
181
  "the state an issue moves to when it is handed to a human: package.json bkit.tracker.<tracker>.review for the wired tracker, at its default when unset (github `In review`, linear `In Review`, jira `In Review`); null under none",
181
182
  tasks:
182
183
  "{maxPerGroup, maxTestsPerGroup, maxTestsPerTask, maxTestFilesPerTask}: the plan caps from package.json bkit.workflows.tasks, each missing or invalid key at its default",
184
+ buildPublishRemote:
185
+ "boolean: the remote build ending from package.json bkit.workflows.build.publish.remote; always true, a false value is refused",
186
+ buildPublishLocal:
187
+ "boolean: the local build ending from package.json bkit.workflows.build.publish.local; true publishes, false holds; true when unset or invalid",
183
188
  },
184
189
  exitCodes: {
185
190
  [EXIT_NO_REPO]: "neither gh nor the origin remote named an owner/repo",
@@ -237,6 +242,8 @@ export const repoCommand: CommandSpec = {
237
242
  trackerProgress: states?.progress ?? null,
238
243
  trackerReview: states?.review ?? null,
239
244
  tasks: config.tasks,
245
+ buildPublishRemote: config.buildPublish.remote,
246
+ buildPublishLocal: config.buildPublish.local,
240
247
  });
241
248
  if (branch === null && ctx.flags.allowDetached !== true) {
242
249
  ctx.log("HEAD is detached — no current branch");
@@ -248,6 +255,7 @@ export const repoCommand: CommandSpec = {
248
255
  preflight: {
249
256
  summary:
250
257
  "Advisory: whether gh can read the repo's Actions permissions (dispatch may 403 without them).",
258
+ use: "by-hand",
251
259
  flags: [
252
260
  {
253
261
  name: "owner-repo",