@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
@@ -22,8 +22,16 @@
22
22
 
23
23
  import * as fs from "node:fs";
24
24
  import * as path from "node:path";
25
+ import { readJsonFile } from "../../shared/json.js";
25
26
 
26
- import { statusTimestamp } from "../../ledgers/status.js";
27
+ import {
28
+ CI_TIERS,
29
+ lastRun,
30
+ statusTimestamp,
31
+ validateCiSelection,
32
+ type CiSelection,
33
+ type CiTier,
34
+ } from "../../ledgers/status.js";
27
35
  import {
28
36
  bodySkipToken,
29
37
  commitMessage,
@@ -35,22 +43,35 @@ import {
35
43
  parseJson,
36
44
  runGh,
37
45
  runGit,
46
+ runTool,
38
47
  SKIP_CI_TOKEN,
48
+ wholeNumber,
39
49
  type CommandSpec,
40
50
  type FlagSpec,
41
51
  type FlagValue,
42
52
  type GhResult,
43
53
  type RunContext,
44
54
  } from "../lib.js";
45
- import { readBkitConfig } from "../../shared/settings.js";
55
+ import { ciGeneratedSteps, readBkitConfig } from "../../shared/settings.js";
46
56
  import { TIMEOUTS } from "../../shared/timeouts.js";
47
57
  import { FID_PATTERNS, fromBranch, fromMarker, issueIdOf, readIssueTracker } from "./fids.js";
58
+ import type { IssueTracker } from "../../install/manifest.js";
48
59
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX } from "./issues.js";
49
- import { checkOnlyBookkeeping } from "./ledgers.js";
50
- import { closeTransportRow, crossCheckFile, prRepoSlug, probePr, type PrInfo } from "./prs.js";
60
+ import { fetchRemoteRef, pushBranch } from "./branches.js";
61
+ import { activeRecord, checkOnlyBookkeeping, retriggerCommit } from "./ledgers.js";
62
+ import {
63
+ closeTransportRow,
64
+ crossCheckFile,
65
+ devRequiresChecks,
66
+ prRepoSlug,
67
+ probePr,
68
+ type PrInfo,
69
+ } from "./prs.js";
51
70
  import { resolveOwnerRepo, splitSlug } from "./repo.js";
52
- import { extraField, str } from "./status.js";
71
+ import { restateOutcome } from "./run-facts.js";
72
+ import { extraField, readRuns, str } from "./status.js";
53
73
  import { writeStepRow } from "./steps.js";
74
+ import { attempt, issueRef, readLabels, trackerTarget } from "./tracker.js";
54
75
 
55
76
  // ---------------------------------------------------------------------------
56
77
  // gh
@@ -87,13 +108,403 @@ export function checkNamespace(capstoneJob: string): string {
87
108
  return i > 0 ? capstoneJob.slice(0, i) : capstoneJob;
88
109
  }
89
110
 
90
- /** Whether `.github/workflows/<bkit.ciWorkflow>` exists — the only honest ground for a `no-ci` pass. */
111
+ /** Whether `.github/workflows/<bkit.testing.ciWorkflow>` exists — the only honest ground for a `no-ci` pass. */
91
112
  export function ciDeclared(root: string): { declared: boolean; ciWorkflow: string; path: string } {
92
113
  const { ciWorkflow } = readBkitConfig(root);
93
114
  const rel = path.join(".github", "workflows", ciWorkflow);
94
115
  return { declared: fs.existsSync(path.join(root, rel)), ciWorkflow, path: rel };
95
116
  }
96
117
 
118
+ type CiReference = { kind: "run" | "pr"; repo: string; id: string; attempt?: number };
119
+
120
+ /** Only the winning reference kind is actionable; a run takes precedence over a PR. */
121
+ export function parseCiReference(input: string): CiReference | undefined {
122
+ const references: CiReference[] = [];
123
+ const urls = [...input.matchAll(/https:\/\/github\.com\/[^\s<>"`]+/g)].map((match) =>
124
+ match[0].replace(/[),.;\]]+$/, ""),
125
+ );
126
+ const parsed = urls.flatMap((url) => {
127
+ const ref =
128
+ /^https:\/\/github\.com\/([^/]+\/[^/]+)\/(actions\/runs|pull)\/([^/?#]*)([^?#]*)/.exec(url);
129
+ return ref ? [{ url, ref }] : [];
130
+ });
131
+ const winning = parsed.some(({ ref }) => ref[2] === "actions/runs") ? "actions/runs" : "pull";
132
+ for (const { url, ref } of parsed.filter(({ ref }) => ref[2] === winning)) {
133
+ const id = ref[3]!;
134
+ const suffix = ref[4]!;
135
+ const kind = ref[2] === "pull" ? "pr" : "run";
136
+ if (!/^[1-9][0-9]*$/.test(id))
137
+ throw new CommandError(EXIT.USAGE, `invalid ${kind} id in ${url}`);
138
+ let attempt: number | undefined;
139
+ if (kind === "run" && suffix !== "" && suffix !== "/") {
140
+ const pinned = /^\/attempts\/([1-9][0-9]*)\/?$/.exec(suffix);
141
+ if (!pinned || !Number.isSafeInteger(Number(pinned[1])))
142
+ throw new CommandError(EXIT.USAGE, `invalid run attempt in ${url}`);
143
+ attempt = Number(pinned[1]);
144
+ } else if (kind === "pr" && suffix !== "" && suffix !== "/") continue;
145
+ references.push({ kind, repo: ref[1]!, id, ...(attempt === undefined ? {} : { attempt }) });
146
+ }
147
+ const kind = references.some((ref) => ref.kind === "run") ? "run" : "pr";
148
+ const winners = [
149
+ ...new Map(
150
+ references.filter((ref) => ref.kind === kind).map((ref) => [JSON.stringify(ref), ref]),
151
+ ).values(),
152
+ ];
153
+ if (winners.length > 1)
154
+ throw new CommandError(8, `multiple ${kind} references were supplied; name one`);
155
+ return winners[0];
156
+ }
157
+
158
+ function selectionHeadRelation(
159
+ cwd: string,
160
+ selection: Extract<CiSelection, { mode: "ci" }>,
161
+ repo: string,
162
+ branch: string,
163
+ ): "current" | "ancestor" {
164
+ if (selection.repo.toLowerCase() !== repo.toLowerCase() || selection.headBranch !== branch) {
165
+ throw new CommandError(
166
+ 82,
167
+ `selected evidence belongs to ${selection.repo} branch ${selection.headBranch}; adopted ${repo} branch ${branch}. Supply branch=${selection.headBranch} in its checkout`,
168
+ );
169
+ }
170
+ const head = git(cwd, ["rev-parse", "--verify", `refs/heads/${branch}^{commit}`]);
171
+ if (head === selection.headSha) return "current";
172
+ if (head === null || !runGit(cwd, ["cat-file", "-e", `${selection.headSha}^{commit}`]).ok) {
173
+ throw new CommandError(
174
+ 82,
175
+ `selected commit ${selection.headSha} or branch ${branch} is unavailable; ancestry is unknown`,
176
+ );
177
+ }
178
+ const relation = runTool("git", ["merge-base", "--is-ancestor", selection.headSha, head], cwd);
179
+ if (relation.status === 0) return "ancestor";
180
+ throw new CommandError(
181
+ 82,
182
+ relation.status === 1
183
+ ? `selected commit ${selection.headSha} is divergent from ${branch}`
184
+ : `ancestry of ${selection.headSha} is unknown: ${relation.stderr}`,
185
+ );
186
+ }
187
+
188
+ function locateCi(ctx: RunContext): number {
189
+ const f = ctx.flags;
190
+ const repo = String(f.repo);
191
+ const branch = String(f.branch);
192
+ if (
193
+ !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(repo) ||
194
+ !runGit(ctx.cwd, ["check-ref-format", "--branch", branch]).ok
195
+ ) {
196
+ throw new CommandError(
197
+ EXIT.USAGE,
198
+ "--repo and --branch must name a repository and a valid branch",
199
+ );
200
+ }
201
+ const readInput = (flag: string) =>
202
+ f[flag] === undefined ? "" : fs.readFileSync(path.resolve(ctx.cwd, String(f[flag])), "utf8");
203
+ const prompt = readInput("promptFile");
204
+ const selectionFile = path.resolve(ctx.cwd, String(f.selectionOut));
205
+ const finish = (selection: CiSelection, failedJobs: Record<string, unknown>[] = []) => {
206
+ if (!validateCiSelection(selection))
207
+ throw new CommandError(82, "selected evidence has malformed or missing identity fields");
208
+ const headRelation =
209
+ selection.mode === "ci" ? selectionHeadRelation(ctx.cwd, selection, repo, branch) : null;
210
+ if (headRelation === "ancestor")
211
+ ctx.log(
212
+ `selected run ${selection.mode === "ci" ? selection.runId : ""} is historical ancestor evidence; inspect intervening changes before fixing`,
213
+ );
214
+ fs.mkdirSync(path.dirname(selectionFile), { recursive: true });
215
+ fs.writeFileSync(selectionFile, `${JSON.stringify(selection, null, 2)}\n`);
216
+ ctx.emit({
217
+ selection: selection.mode,
218
+ runId: selection.mode === "ci" ? selection.runId : null,
219
+ runUrl: selection.mode === "ci" ? selection.runUrl : null,
220
+ runAttempt: selection.mode === "ci" ? selection.runAttempt : null,
221
+ workflowId: selection.mode === "ci" ? selection.workflowId : null,
222
+ workflowPath: selection.mode === "ci" ? selection.workflowPath : null,
223
+ headSha: selection.mode === "ci" ? selection.headSha : null,
224
+ headRelation,
225
+ failedJobs,
226
+ tiers: selection.mode === "ci" ? selection.redTiers : [],
227
+ via: selection.mode === "ci" ? selection.via : null,
228
+ reason: selection.mode === "local" ? selection.reason : null,
229
+ selectionFile,
230
+ });
231
+ return selection.mode === "ci" ? EXIT.OK : 1;
232
+ };
233
+ if (/\[local\]/i.test(prompt)) return finish({ mode: "local", reason: "explicit-local" });
234
+ let reference = parseCiReference(prompt);
235
+ let via = reference ? `prompt-${reference.kind}` : "branch";
236
+ let saved: CiSelection | undefined;
237
+ if (!reference && f.file !== undefined && fs.existsSync(path.resolve(ctx.cwd, String(f.file)))) {
238
+ const active = lastRun(readRuns(path.resolve(ctx.cwd, String(f.file))), "debug");
239
+ if (active?.status === "IN_PROGRESS" && active.ciSelection !== undefined) {
240
+ if (!validateCiSelection(active.ciSelection))
241
+ throw new CommandError(82, "active saved CI selection is invalid");
242
+ saved = active.ciSelection;
243
+ if (saved.mode === "local") return finish(saved);
244
+ reference = { kind: "run", repo: saved.repo, id: saved.runId, attempt: saved.runAttempt };
245
+ via = saved.via;
246
+ }
247
+ }
248
+ if (!reference) {
249
+ const issue = readInput("issueTextFile");
250
+ // issues text already removes generated comments; refuse a raw generated payload too.
251
+ reference = parseCiReference(/^######\s+bkit:generated/m.test(issue) ? "" : issue);
252
+ if (reference) via = `issue-${reference.kind}`;
253
+ }
254
+ if (reference && reference.repo.toLowerCase() !== repo.toLowerCase())
255
+ throw new CommandError(
256
+ 82,
257
+ `reference repository ${reference.repo} does not match adopted repository ${repo}`,
258
+ );
259
+ const declared = ciDeclared(checkoutRoot(ctx.cwd));
260
+ if (!reference && !declared.declared)
261
+ return finish({ mode: "local", reason: "no-configured-ci" });
262
+ const api = (endpoint: string, extra: string[] = []) => {
263
+ const response = runGh(ctx.cwd, ["api", endpoint, ...extra]);
264
+ if (!response.ok)
265
+ throw new CommandError(
266
+ /HTTP 404/.test(response.stderr) ? 82 : EXIT.USE_MCP,
267
+ `CI evidence unavailable: ${response.stderr || GH_MISSING}`,
268
+ );
269
+ const parsed = jsonOrUndefined(response.stdout);
270
+ if (parsed === undefined) throw new CommandError(82, "CI evidence response is malformed");
271
+ return parsed;
272
+ };
273
+ const validateRun = (candidate: Record<string, unknown>) => {
274
+ const base = {
275
+ mode: "ci",
276
+ provider: "github",
277
+ repo,
278
+ runId: String(candidate.id),
279
+ runAttempt: Number(candidate.run_attempt),
280
+ runUrl: `https://github.com/${repo}/actions/runs/${candidate.id}/attempts/${candidate.run_attempt}`,
281
+ workflowId: String(candidate.workflow_id ?? ""),
282
+ workflowPath: text(candidate.path),
283
+ headBranch: text(candidate.head_branch),
284
+ headSha: text(candidate.head_sha),
285
+ conclusion: "failure",
286
+ redTiers: [],
287
+ via,
288
+ };
289
+ if (
290
+ !validateCiSelection(base) ||
291
+ text(obj(candidate.repository).full_name).toLowerCase() !== repo.toLowerCase() ||
292
+ text(obj(candidate.head_repository).full_name).toLowerCase() !== repo.toLowerCase()
293
+ )
294
+ throw new CommandError(
295
+ 82,
296
+ "run identity, repository or fork metadata is incomplete or mismatched",
297
+ );
298
+ if (candidate.head_branch !== branch)
299
+ throw new CommandError(
300
+ 82,
301
+ `run branch ${text(candidate.head_branch)} differs from adopted branch ${branch}; supply branch=${text(candidate.head_branch)} in its checkout`,
302
+ );
303
+ if (reference?.kind !== "run" && candidate.path !== declared.path)
304
+ throw new CommandError(82, "discovered run does not belong to the configured workflow");
305
+ };
306
+ let run: Record<string, unknown>;
307
+ let jobs: Record<string, unknown>[];
308
+ const requested: Record<string, unknown> = { repo, branch, kind: reference?.kind ?? "branch" };
309
+ if (reference?.kind === "run") {
310
+ requested.runId = reference.id;
311
+ if (reference.attempt !== undefined) requested.runAttempt = reference.attempt;
312
+ } else if (reference?.kind === "pr") requested.pr = reference.id;
313
+ else requested.workflow = declared.ciWorkflow;
314
+ if (f.evidenceFile !== undefined) {
315
+ const envelope = obj(jsonOrUndefined(readInput("evidenceFile")));
316
+ const request = obj(envelope.request);
317
+ if (
318
+ envelope.complete !== true ||
319
+ !Object.entries(requested).every(([key, value]) => request[key] === value)
320
+ )
321
+ throw new CommandError(82, "fallback evidence is incomplete or its request identity differs");
322
+ if (
323
+ envelope.noRed === true &&
324
+ !reference &&
325
+ typeof request.headSha === "string" &&
326
+ request.headSha === git(ctx.cwd, ["rev-parse", "HEAD"])
327
+ )
328
+ return finish({ mode: "local", reason: "automatic-no-red" });
329
+ run = obj(envelope.run);
330
+ if (reference?.kind === "pr") {
331
+ const head = obj(obj(envelope.pr).head);
332
+ if (
333
+ head.ref !== branch ||
334
+ head.sha !== run.head_sha ||
335
+ text(obj(head.repo).full_name).toLowerCase() !== repo.toLowerCase()
336
+ )
337
+ throw new CommandError(82, "fallback PR head is missing or differs from the selected run");
338
+ }
339
+ if (!Array.isArray(envelope.jobs) || envelope.jobs.some((job) => obj(job).id === undefined))
340
+ throw new CommandError(82, "fallback jobs are incomplete");
341
+ jobs = envelope.jobs.map(obj);
342
+ } else {
343
+ let expectedHead: string | undefined;
344
+ if (reference?.kind === "pr") {
345
+ const pr = obj(api(`/repos/${repo}/pulls/${reference.id}`));
346
+ const head = obj(pr.head);
347
+ if (
348
+ text(obj(head.repo).full_name).toLowerCase() !== repo.toLowerCase() ||
349
+ head.ref !== branch ||
350
+ !/^[0-9a-f]{40,64}$/.test(text(head.sha))
351
+ )
352
+ throw new CommandError(
353
+ 82,
354
+ `PR head does not match adopted ${repo} branch ${branch}; inspect its branch and fork repository`,
355
+ );
356
+ expectedHead = text(head.sha);
357
+ }
358
+ if (reference?.kind === "run") {
359
+ run = obj(
360
+ api(
361
+ `/repos/${repo}/actions/runs/${reference.id}${reference.attempt === undefined ? "" : `/attempts/${reference.attempt}`}`,
362
+ ),
363
+ );
364
+ } else {
365
+ const response = obj(
366
+ api(
367
+ `/repos/${repo}/actions/workflows/${queryValue(declared.ciWorkflow)}/runs?branch=${queryValue(branch)}&status=completed&per_page=100${expectedHead ? `&head_sha=${expectedHead}` : ""}`,
368
+ ),
369
+ );
370
+ if (
371
+ !Array.isArray(response.workflow_runs) ||
372
+ !Number.isSafeInteger(response.total_count) ||
373
+ Number(response.total_count) < 0 ||
374
+ Number(response.total_count) < response.workflow_runs.length
375
+ )
376
+ throw new CommandError(82, "workflow lookup returned an incomplete response");
377
+ const candidates = response.workflow_runs
378
+ .map(obj)
379
+ .filter((candidate) => candidate.status === "completed");
380
+ run =
381
+ candidates.sort(
382
+ (a, b) =>
383
+ text(b.created_at).localeCompare(text(a.created_at)) || Number(b.id) - Number(a.id),
384
+ )[0] ?? {};
385
+ if (Object.keys(run).length === 0) {
386
+ if (Number(response.total_count) > 0)
387
+ throw new CommandError(
388
+ 82,
389
+ "workflow lookup returned no completed records despite a nonempty result",
390
+ );
391
+ if (reference)
392
+ throw new CommandError(
393
+ 82,
394
+ "named PR has no completed red run; choose [local] to discover locally",
395
+ );
396
+ return finish({ mode: "local", reason: "automatic-no-red" });
397
+ }
398
+ if (expectedHead && run.head_sha !== expectedHead)
399
+ throw new CommandError(82, "PR lookup returned a run from another head");
400
+ }
401
+ validateRun(run);
402
+ if (
403
+ run.status !== "completed" ||
404
+ !["failure", "timed_out", "startup_failure"].includes(text(run.conclusion))
405
+ ) {
406
+ if (reference)
407
+ throw new CommandError(
408
+ 82,
409
+ `named evidence is ${text(run.status)}/${text(run.conclusion)}; choose [local] to discover locally`,
410
+ );
411
+ if (
412
+ run.status !== "completed" ||
413
+ !["success", "cancelled", "skipped", "neutral", "action_required", "stale"].includes(
414
+ text(run.conclusion),
415
+ )
416
+ )
417
+ throw new CommandError(82, "workflow run has an invalid state");
418
+ return finish({ mode: "local", reason: "automatic-no-red" });
419
+ }
420
+ const attempt = reference?.attempt ?? Number(run.run_attempt);
421
+ if (!Number.isSafeInteger(attempt) || attempt <= 0 || !/^[1-9][0-9]*$/.test(String(run.id)))
422
+ throw new CommandError(82, "run identity or attempt is missing");
423
+ const pages = api(
424
+ `/repos/${repo}/actions/runs/${run.id}/attempts/${attempt}/jobs?per_page=100`,
425
+ ["--paginate", "--slurp"],
426
+ );
427
+ if (!Array.isArray(pages) || pages.length === 0)
428
+ throw new CommandError(82, "job pagination returned no complete pages");
429
+ const total = obj(pages[0]).total_count;
430
+ if (
431
+ !Number.isSafeInteger(total) ||
432
+ Number(total) < 0 ||
433
+ pages.some((page) => !Array.isArray(obj(page).jobs) || obj(page).total_count !== total)
434
+ )
435
+ throw new CommandError(82, "job pagination returned incomplete pages");
436
+ jobs = pages.flatMap((page) => arr(obj(page).jobs).map(obj));
437
+ if (
438
+ jobs.length !== total ||
439
+ new Set(jobs.map((job) => job.id)).size !== total ||
440
+ jobs.some(
441
+ (job) =>
442
+ !Number.isSafeInteger(job.id) ||
443
+ typeof job.name !== "string" ||
444
+ typeof job.conclusion !== "string",
445
+ )
446
+ )
447
+ throw new CommandError(82, "job pagination did not return every job");
448
+ }
449
+ const attempt = reference?.attempt ?? Number(run.run_attempt);
450
+ validateRun(run);
451
+ if (
452
+ jobs.some(
453
+ (job) =>
454
+ !Number.isSafeInteger(job.id) ||
455
+ typeof job.name !== "string" ||
456
+ job.name.length === 0 ||
457
+ typeof job.conclusion !== "string",
458
+ ) ||
459
+ new Set(jobs.map((job) => job.id)).size !== jobs.length
460
+ )
461
+ throw new CommandError(82, "job identities or conclusions are incomplete");
462
+ if (reference?.kind === "run" && String(run.id) !== reference.id)
463
+ throw new CommandError(82, "selected run differs from the requested run");
464
+ if (
465
+ Number(run.run_attempt) !== attempt ||
466
+ run.status !== "completed" ||
467
+ text(obj(run.repository).full_name).toLowerCase() !== repo.toLowerCase() ||
468
+ text(obj(run.head_repository).full_name).toLowerCase() !== repo.toLowerCase()
469
+ )
470
+ throw new CommandError(82, "run attempt, repository or fork identity does not match");
471
+ const failedJobs = jobs.filter((job) =>
472
+ ["failure", "timed_out", "startup_failure"].includes(text(job.conclusion)),
473
+ );
474
+ const mapped = failedJobs
475
+ .filter((job) => job.name !== "bkit-tests-check")
476
+ .map(
477
+ (job) =>
478
+ /^bkit-tests-(static|unit|integration|e2e|live|migration)$/.exec(text(job.name))?.[1],
479
+ );
480
+ const tiers: CiTier[] = mapped.some((tier) => tier === undefined)
481
+ ? []
482
+ : CI_TIERS.filter((tier) => mapped.includes(tier));
483
+ const selection: CiSelection = {
484
+ mode: "ci",
485
+ provider: "github",
486
+ repo,
487
+ runId: String(run.id),
488
+ runAttempt: attempt,
489
+ runUrl: `https://github.com/${repo}/actions/runs/${run.id}/attempts/${attempt}`,
490
+ workflowId: String(run.workflow_id ?? ""),
491
+ workflowPath: text(run.path),
492
+ headBranch: text(run.head_branch),
493
+ headSha: text(run.head_sha),
494
+ conclusion: text(run.conclusion) as Extract<CiSelection, { mode: "ci" }>["conclusion"],
495
+ redTiers: tiers,
496
+ via,
497
+ };
498
+ if (
499
+ saved?.mode === "ci" &&
500
+ (saved.workflowId !== selection.workflowId ||
501
+ saved.headSha !== selection.headSha ||
502
+ saved.workflowPath !== selection.workflowPath)
503
+ )
504
+ throw new CommandError(82, "saved evidence identity differs from the returned run");
505
+ return finish(selection, failedJobs);
506
+ }
507
+
97
508
  /** Skip-token scan of a landed commit's body (see `bodySkipToken`). */
98
509
  export function scanBody(cwd: string, sha: string): "clean" | "skip-token-found" | "error" {
99
510
  const token = bodySkipToken(cwd, sha);
@@ -289,6 +700,11 @@ export interface DispatchOptions {
289
700
  supplied?: SuppliedPoll;
290
701
  /** The re-trigger commit is already pushed (re-entry after a hand-off in the re-poll). */
291
702
  retriggered: boolean;
703
+ /**
704
+ * The sha the run's last push landed on a shared branch, for a run with no PR.
705
+ * An own-commit push lands copies, so it is not necessarily local HEAD.
706
+ */
707
+ sha?: string;
292
708
  }
293
709
 
294
710
  export interface DispatchResult {
@@ -301,19 +717,23 @@ export interface DispatchResult {
301
717
  attempts: number;
302
718
  retrigger: boolean;
303
719
  ciWorkflow: string;
720
+ /** The branch the CI run is looked up on when there is no PR to read, else null. */
721
+ runBranch: string | null;
304
722
  }
305
723
 
306
724
  /** Exit code: the re-trigger commit or its push failed. */
307
725
  export const EXIT_RETRIGGER_FAILED = 6;
308
726
 
309
- function pushCurrentBranch(cwd: string): boolean {
727
+ /** Push the current branch; the failure text is kept so the gate can name why. */
728
+ function pushCurrentBranch(cwd: string): { ok: boolean; error: string } {
310
729
  const branch = git(cwd, ["branch", "--show-current"]);
311
- if (!branch) return false;
730
+ if (!branch) return { ok: false, error: "no branch checked out (detached HEAD)" };
312
731
  // Shared branches never force; a feature branch is rewritten only by this run.
313
732
  const args = isSharedBranch(branch)
314
733
  ? ["push", "origin", branch]
315
734
  : ["push", "--force-with-lease", "origin", branch];
316
- return runGit(cwd, args).ok;
735
+ const res = runGit(cwd, args);
736
+ return { ok: res.ok, error: res.ok ? "" : res.stderr || res.stdout };
317
737
  }
318
738
 
319
739
  /**
@@ -327,7 +747,19 @@ export async function ciDispatchGate(
327
747
  const root = checkoutRoot(o.cwd);
328
748
  const { capstoneJob } = readBkitConfig(root);
329
749
  const declared = ciDeclared(root);
330
- const head = () => git(o.cwd, ["rev-parse", "HEAD"]) ?? "";
750
+ const branch = git(o.cwd, ["branch", "--show-current"]) ?? "";
751
+ const shared = branch !== "" && isSharedBranch(branch);
752
+ // A run in place on a shared branch has no PR: CI is the push-event run at the pushed sha.
753
+ const byRun = o.pr === null && shared;
754
+ // The sha an own-commit push landed; null while the head is local HEAD.
755
+ let landed: string | null = byRun ? (o.sha ?? null) : null;
756
+ const head = () => landed ?? git(o.cwd, ["rev-parse", "HEAD"]) ?? "";
757
+ /** The landed copy lives on the remote only; the scan and the suppressor check read it locally. */
758
+ const fetchLanded = () => {
759
+ if (landed === null || runGit(o.cwd, ["cat-file", "-e", `${landed}^{commit}`]).ok) return;
760
+ runGit(o.cwd, ["fetch", "origin", branch]);
761
+ };
762
+ fetchLanded();
331
763
  const res: DispatchResult = {
332
764
  phase: "done",
333
765
  handoff: 0,
@@ -336,13 +768,22 @@ export async function ciDispatchGate(
336
768
  attempts: 0,
337
769
  retrigger: o.retriggered,
338
770
  ciWorkflow: declared.ciWorkflow,
771
+ runBranch: byRun ? branch : null,
339
772
  };
340
- const target: WaitTarget = {
341
- kind: "pr-present",
342
- pr: o.pr ?? undefined,
343
- ciWorkflow: declared.ciWorkflow,
344
- namespace: checkNamespace(capstoneJob),
345
- };
773
+ const target: WaitTarget = byRun
774
+ ? {
775
+ kind: "run-present",
776
+ head: res.head,
777
+ branch,
778
+ ciWorkflow: declared.ciWorkflow,
779
+ namespace: checkNamespace(capstoneJob),
780
+ }
781
+ : {
782
+ kind: "pr-present",
783
+ pr: o.pr ?? undefined,
784
+ ciWorkflow: declared.ciWorkflow,
785
+ namespace: checkNamespace(capstoneJob),
786
+ };
346
787
  const poll = async (phase: "poll" | "repoll"): Promise<SuppliedPoll | null> => {
347
788
  // A supplied result answers only the poll that was handed off; later polls run fresh.
348
789
  if (o.supplied && (phase === "repoll") === o.retriggered) {
@@ -352,9 +793,12 @@ export async function ciDispatchGate(
352
793
  return o.supplied;
353
794
  }
354
795
  // No PR to read is the shell's empty-PR poll: zero attempts, all errored.
355
- if (o.pr === null) return { pollResult: "err", attempts: 0, allErrored: true };
796
+ if (o.pr === null && !byRun) return { pollResult: "err", attempts: 0, allErrored: true };
797
+ if (byRun) target.head = head();
356
798
  deps.log(
357
- `polling for a ${target.namespace} check on PR #${o.pr} (budget ${o.budgetS}s, interval ${o.intervalS}s)`,
799
+ byRun
800
+ ? `polling for a ${target.ciWorkflow} run on ${branch} at ${target.head} (budget ${o.budgetS}s, interval ${o.intervalS}s)`
801
+ : `polling for a ${target.namespace} check on PR #${o.pr} (budget ${o.budgetS}s, interval ${o.intervalS}s)`,
358
802
  );
359
803
  const w = await waitLoop(
360
804
  { budgetS: o.budgetS, intervalS: o.intervalS, once: false },
@@ -399,14 +843,51 @@ export async function ciDispatchGate(
399
843
  );
400
844
  return verdict("unresolved", "timeout-dirty");
401
845
  }
402
- const committed = runGit(o.cwd, [
403
- "commit",
404
- "--allow-empty",
405
- "-m",
406
- `chore(${o.fid}): re-trigger${o.autoRouteSuffix}`,
407
- ]).ok;
408
- if (!committed || !pushCurrentBranch(o.cwd)) {
409
- deps.log("re-trigger commit or push failed — no verdict; route to the Failure Path");
846
+ const message = `chore(${o.fid}): re-trigger${o.autoRouteSuffix}`;
847
+ // A run in place on a shared branch commits and pushes only its own work; with
848
+ // no record of the run there, nothing is committed or pushed.
849
+ const rec = shared ? activeRecord(o.cwd, o.fid) : null;
850
+ if (shared && rec === null) {
851
+ deps.log(
852
+ `no shared-checkout record for ${o.fid} on ${branch} — refusing to re-trigger: a commit and push here would carry work the run does not own; route to the Failure Path`,
853
+ );
854
+ res.phase = "repoll";
855
+ res.handoff = EXIT_RETRIGGER_FAILED;
856
+ return res;
857
+ }
858
+ let pushed: boolean;
859
+ let failure = "";
860
+ if (rec === null) {
861
+ landed = null;
862
+ const before = git(o.cwd, ["rev-parse", "HEAD"]);
863
+ const made = runGit(o.cwd, ["commit", "--allow-empty", "-m", message]);
864
+ if (!made.ok) {
865
+ pushed = false;
866
+ failure = made.stderr || made.stdout;
867
+ } else {
868
+ const push = pushCurrentBranch(o.cwd);
869
+ pushed = push.ok;
870
+ if (!push.ok) {
871
+ failure = push.error;
872
+ // The commit never reached the remote: drop it so a re-run does not pile
873
+ // up orphan re-triggers. --soft restores the index exactly as the commit left it.
874
+ if (before !== null) runGit(o.cwd, ["reset", "--soft", before]);
875
+ }
876
+ }
877
+ } else {
878
+ const made = retriggerCommit(o.cwd, rec, message);
879
+ if (!made.ok) deps.log(`re-trigger commit failed: ${made.error}`);
880
+ const out = made.ok
881
+ ? await pushBranch(o.cwd, { mode: "feature", fid: o.fid }, deps.log)
882
+ : null;
883
+ landed = out?.out.pushed === true ? out.out.sha : landed;
884
+ pushed = out?.out.pushed === true && out.out.sha !== null;
885
+ if (pushed) fetchLanded();
886
+ }
887
+ if (!pushed) {
888
+ deps.log(
889
+ `re-trigger commit or push failed${failure ? `: ${failure}` : ""} — no verdict; route to the Failure Path`,
890
+ );
410
891
  res.phase = "repoll";
411
892
  res.handoff = EXIT_RETRIGGER_FAILED;
412
893
  return res;
@@ -465,7 +946,7 @@ export const GATE = {
465
946
  SUPERSEDED: 14,
466
947
  /** The selected run was cancelled. */
467
948
  CANCELLED: 15,
468
- /** A lane named in bkit.shipGateRequiredLanes concluded skipped. */
949
+ /** A lane named in bkit.testing.ciRequired concluded skipped. */
469
950
  LANE_SKIPPED: 16,
470
951
  /** --validated is not an ancestor of the head plus bookkeeping-only commits. */
471
952
  NOT_BOOKKEEPING: 17,
@@ -537,9 +1018,39 @@ export interface GateResult {
537
1018
  repo: string | null;
538
1019
  skippedLanes: string[];
539
1020
  nonBookkeepingPaths: string[];
1021
+ /**
1022
+ * Exit 12: `{job}/{step}` of each failed step outside the capstone; `{job}/` for a
1023
+ * failed job with no failed step. Empty when the jobs could not be read.
1024
+ */
1025
+ failedSteps: string[];
1026
+ /** Exit 12, and every failed step is one `bkit:generate` fixes (`ciGeneratedSteps`). */
1027
+ regenerable: boolean;
540
1028
  reason: string;
541
1029
  }
542
1030
 
1031
+ /** Job and step conclusions that are not a failure. */
1032
+ const NOT_FAILED = new Set(["success", "skipped", "neutral"]);
1033
+
1034
+ /**
1035
+ * The failed steps of a run's jobs as `{job}/{step}`, the capstone left out: it fails
1036
+ * only because another job did. A job that did not pass with no step that failed (a
1037
+ * runner or setup failure) is `{job}/`, which no list entry matches.
1038
+ */
1039
+ export function failedStepsOf(jobs: Array<Record<string, unknown>>, capstone: string): string[] {
1040
+ const out: string[] = [];
1041
+ for (const job of jobs) {
1042
+ const name = text(job.name);
1043
+ if (name === capstone || NOT_FAILED.has(text(job.conclusion))) continue;
1044
+ const steps = arr(job.steps)
1045
+ .map(obj)
1046
+ .filter((st) => st.conclusion !== null && st.conclusion !== undefined)
1047
+ .filter((st) => !NOT_FAILED.has(text(st.conclusion)))
1048
+ .map((st) => `${name}/${text(st.name)}`);
1049
+ out.push(...(steps.length > 0 ? steps : [`${name}/`]));
1050
+ }
1051
+ return out;
1052
+ }
1053
+
543
1054
  interface Run {
544
1055
  id: number | null;
545
1056
  head_sha: string;
@@ -591,9 +1102,11 @@ export function shipGate(o: GateOptions, gh: Gh, log: (m: string) => void): Gate
591
1102
  repo: o.repo || null,
592
1103
  skippedLanes: [],
593
1104
  nonBookkeepingPaths: [],
1105
+ failedSteps: [],
1106
+ regenerable: false,
594
1107
  reason: "",
595
1108
  };
596
- const requiredLanes = cfg.shipGateRequiredLanes;
1109
+ const requiredLanes = cfg.ciRequired;
597
1110
 
598
1111
  const refuse = (code: number, reason: string, runUrl?: string): GateResult => {
599
1112
  log(reason);
@@ -663,32 +1176,59 @@ export function shipGate(o: GateOptions, gh: Gh, log: (m: string) => void): Gate
663
1176
  return r;
664
1177
  };
665
1178
 
666
- /** The run's jobs, or the refusal. `--slurp` turns --paginate's one-document-per-page
667
- * stream into one array; without it a run with more than 100 jobs hides every page but the first. */
668
- const readJobs = (run: Run): Array<Record<string, unknown>> | GateResult => {
1179
+ /** The run's jobs. `--slurp` turns --paginate's one-document-per-page stream into one
1180
+ * array; without it a run with more than 100 jobs hides every page but the first. */
1181
+ const listJobs = (
1182
+ run: Run,
1183
+ ): Array<Record<string, unknown>> | "missing" | "api-error" | "invalid" => {
669
1184
  const jobsRes = gh([
670
1185
  "api",
671
1186
  `/repos/${r.repo}/actions/runs/${run.id}/jobs`,
672
1187
  "--paginate",
673
1188
  "--slurp",
674
1189
  ]);
675
- if (jobsRes.missing) return ghMissing();
676
- if (!jobsRes.ok) {
1190
+ if (jobsRes.missing) return "missing";
1191
+ if (!jobsRes.ok) return "api-error";
1192
+ const jobsJson = jsonOrUndefined(jobsRes.stdout);
1193
+ if (jobsJson === undefined) return "invalid";
1194
+ const pages = Array.isArray(jobsJson) ? jobsJson : [jobsJson];
1195
+ return pages.flatMap((p) => arr(obj(p).jobs).map(obj));
1196
+ };
1197
+
1198
+ /** The run's jobs, or the refusal. */
1199
+ const readJobs = (run: Run): Array<Record<string, unknown>> | GateResult => {
1200
+ const jobs = listJobs(run);
1201
+ if (jobs === "missing") return ghMissing();
1202
+ if (jobs === "api-error") {
677
1203
  return apiError(
678
1204
  `jobs query failed for run ${run.id} — API error (distinct from 'no capstone')`,
679
1205
  run.html_url,
680
1206
  );
681
1207
  }
682
- const jobsJson = jsonOrUndefined(jobsRes.stdout);
683
- if (jobsJson === undefined) {
1208
+ if (jobs === "invalid") {
684
1209
  return refuse(
685
1210
  GATE.API_ERROR,
686
1211
  `jobs response for run ${run.id} is not valid JSON`,
687
1212
  run.html_url,
688
1213
  );
689
1214
  }
690
- const pages = Array.isArray(jobsJson) ? jobsJson : [jobsJson];
691
- return pages.flatMap((p) => arr(obj(p).jobs).map(obj));
1215
+ return jobs;
1216
+ };
1217
+
1218
+ /** A failed run's failed steps, and whether `bkit:generate` fixes each one. Jobs that
1219
+ * cannot be read leave it unregenerable; the refusal itself does not change. */
1220
+ const classifyFailure = (run: Run): void => {
1221
+ const jobs = listJobs(run);
1222
+ if (!Array.isArray(jobs)) {
1223
+ log(`failed steps unknown: the jobs of run ${run.id} could not be read`);
1224
+ return;
1225
+ }
1226
+ r.failedSteps = failedStepsOf(jobs, r.capstone);
1227
+ const fixable = ciGeneratedSteps(cfg);
1228
+ r.regenerable = r.failedSteps.length > 0 && r.failedSteps.every((st) => fixable.includes(st));
1229
+ for (const st of r.failedSteps) log(`failed step: ${st}`);
1230
+ if (r.regenerable)
1231
+ log("every failed step is one bkit:generate fixes (bkit.testing.ciGenerated)");
692
1232
  };
693
1233
 
694
1234
  /** Capstone-only verdict: the capstone job's own result, whatever the run and its other jobs did. */
@@ -848,6 +1388,7 @@ export function shipGate(o: GateOptions, gh: Gh, log: (m: string) => void): Gate
848
1388
  if (o.capstoneOnly) return capstoneVerdict(selected);
849
1389
 
850
1390
  if (selected.conclusion === "failure") {
1391
+ classifyFailure(selected);
851
1392
  return refuse(GATE.FAILED, `selected run concluded FAILURE at head ${r.head}`, url);
852
1393
  }
853
1394
  if (selected.conclusion === "cancelled") {
@@ -900,7 +1441,7 @@ export function shipGate(o: GateOptions, gh: Gh, log: (m: string) => void): Gate
900
1441
  );
901
1442
  const required = r.skippedLanes.filter((l) => requiredLanes.includes(l));
902
1443
  if (required.length) {
903
- log(`declared in bkit.shipGateRequiredLanes: ${requiredLanes.join(",")}`);
1444
+ log(`declared in bkit.testing.ciRequired: ${requiredLanes.join(",")}`);
904
1445
  return refuse(
905
1446
  GATE.LANE_SKIPPED,
906
1447
  `required lane(s) concluded 'skipped' at head ${r.head} — vacuous green: ${required.join(", ")}`,
@@ -1046,15 +1587,6 @@ export const EXIT_SKIP_TOKEN = 4;
1046
1587
  /** Exit code: the pushed head's commit message could not be read for the body scan. */
1047
1588
  export const EXIT_SCAN_ERROR = 5;
1048
1589
 
1049
- const wholeNumber = (v: FlagValue, flag: string, fallback: number, min = 0): number => {
1050
- if (v === undefined) return fallback;
1051
- const s = String(v);
1052
- if (!/^[0-9]+$/.test(s) || Number(s) < min) {
1053
- throw new CommandError(EXIT.USAGE, `--${flag} takes a whole number >= ${min} (got "${s}")`);
1054
- }
1055
- return Number(s);
1056
- };
1057
-
1058
1590
  const HEAD_FLAG: FlagSpec = { name: "head", type: "string", help: "commit SHA" };
1059
1591
  const REPO_FLAG: FlagSpec = {
1060
1592
  name: "repo",
@@ -1064,12 +1596,12 @@ const REPO_FLAG: FlagSpec = {
1064
1596
  const CI_WORKFLOW_FLAG: FlagSpec = {
1065
1597
  name: "ci-workflow",
1066
1598
  type: "string",
1067
- help: "CI workflow file (default: package.json bkit.ciWorkflow)",
1599
+ help: "CI workflow file (default: package.json bkit.testing.ciWorkflow)",
1068
1600
  };
1069
1601
  const CAPSTONE_FLAG: FlagSpec = {
1070
1602
  name: "capstone",
1071
1603
  type: "string",
1072
- help: "capstone job name (default: package.json bkit.capstoneJob)",
1604
+ help: "capstone job name (default: package.json bkit.testing.ciCapstone)",
1073
1605
  };
1074
1606
  const BUDGET_FLAG: FlagSpec = { name: "budget-s", type: "string", help: "poll budget in seconds" };
1075
1607
  const INTERVAL_FLAG: FlagSpec = {
@@ -1237,6 +1769,20 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1237
1769
  }
1238
1770
  pr = found.pr;
1239
1771
  }
1772
+ const sha = str(f.sha);
1773
+ if (sha !== undefined && !/^[0-9a-f]{40}$/i.test(sha)) {
1774
+ throw new CommandError(
1775
+ EXIT.USAGE,
1776
+ "--sha must be the full 40-hex-digit commit sha (the CI run is matched on the full sha)",
1777
+ );
1778
+ }
1779
+ const onShared = isSharedBranch(git(ctx.cwd, ["branch", "--show-current"]) ?? "");
1780
+ if (sha !== undefined && (pr !== null || !onShared)) {
1781
+ throw new CommandError(
1782
+ EXIT.USAGE,
1783
+ "--sha goes with a run in place on a shared branch that has no PR",
1784
+ );
1785
+ }
1240
1786
  const pollResult = str(f.pollResult);
1241
1787
  if (pollResult !== undefined && !["found", "none", "err"].includes(pollResult)) {
1242
1788
  throw new CommandError(EXIT.USAGE, "--poll-result must be found, none, or err");
@@ -1263,6 +1809,7 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1263
1809
  allErrored: f.allErrored === true,
1264
1810
  },
1265
1811
  retriggered: f.retriggered === true,
1812
+ sha,
1266
1813
  },
1267
1814
  d,
1268
1815
  );
@@ -1276,11 +1823,12 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1276
1823
  if ((file === undefined) !== (step === undefined))
1277
1824
  throw new CommandError(EXIT.USAGE, "--file and --step go together");
1278
1825
  let row: Record<string, unknown> | null = null;
1826
+ let progressLine: string | undefined;
1279
1827
  let transport: Record<string, unknown> | null = null;
1280
1828
  const code = dispatchCode(r, pr, scanResult, ctx.log);
1281
1829
  if (file !== undefined && r.ciDispatch !== null) {
1282
1830
  const status = path.resolve(ctx.cwd, file);
1283
- row = writeStepRow(
1831
+ const written = writeStepRow(
1284
1832
  ctx.cwd,
1285
1833
  {
1286
1834
  file: status,
@@ -1294,7 +1842,13 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1294
1842
  commit: "none",
1295
1843
  },
1296
1844
  ctx.log,
1297
- ).row;
1845
+ );
1846
+ row = written.row;
1847
+ progressLine = written.progressLine;
1848
+ if (/-close-workflow$/.test(step!)) {
1849
+ const tree = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1850
+ restateOutcome(tree, status, String(f.workflow ?? "build"), { ...r.ciDispatch }, ctx.log);
1851
+ }
1298
1852
  if (code === EXIT.OK || code === EXIT_SKIP_TOKEN) {
1299
1853
  const check = crossCheckFile(status, "gh", ctx.log);
1300
1854
  if (!check.ok) {
@@ -1310,6 +1864,7 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1310
1864
  ciWorkflow: r.ciWorkflow,
1311
1865
  row,
1312
1866
  transport,
1867
+ ...(progressLine === undefined ? {} : { progressLine }),
1313
1868
  });
1314
1869
  return EXIT.NO;
1315
1870
  }
@@ -1331,6 +1886,7 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1331
1886
  ciWorkflow: r.ciWorkflow,
1332
1887
  row,
1333
1888
  transport,
1889
+ ...(progressLine === undefined ? {} : { progressLine }),
1334
1890
  });
1335
1891
  return code;
1336
1892
  }
@@ -1344,8 +1900,12 @@ function dispatchCode(
1344
1900
  ): number {
1345
1901
  if (r.handoff === EXIT.AGENT_WAIT || r.handoff === EXIT.USE_MCP) {
1346
1902
  const again = r.phase === "repoll" ? " --retriggered" : "";
1903
+ const [wait, keep] =
1904
+ r.runBranch === null
1905
+ ? [`--pr=${pr ?? "<n>"}`, ""]
1906
+ : [`--head=${r.head} --branch=${r.runBranch} --until=present`, ` --sha=${r.head}`];
1347
1907
  log(
1348
- `${r.handoff === EXIT.USE_MCP ? GH_MISSING : "this runtime cannot wait"}: resolve the ${r.phase} each turn with \`bkit runs wait --pr=${pr ?? "<n>"} --once\`, then re-run with --poll-result=<found|none|err> --attempts=<total>${again}`,
1908
+ `${r.handoff === EXIT.USE_MCP ? GH_MISSING : "this runtime cannot wait"}: resolve the ${r.phase} each turn with \`bkit runs wait ${wait} --once\`, then re-run with --poll-result=<found|none|err> --attempts=<total>${again}${keep}`,
1349
1909
  );
1350
1910
  return r.handoff;
1351
1911
  }
@@ -1397,9 +1957,28 @@ function logResolvedPrRepo(
1397
1957
 
1398
1958
  function runGate(ctx: RunContext): number {
1399
1959
  const f = ctx.flags;
1960
+ let selection: CiSelection | undefined;
1961
+ const selectionFile = str(f.ciSelectionFile);
1962
+ if (selectionFile !== undefined) {
1963
+ const parsed = readJsonFile(path.resolve(ctx.cwd, selectionFile));
1964
+ if (!parsed.ok || !validateCiSelection(parsed.value))
1965
+ throw new CommandError(
1966
+ EXIT.USAGE,
1967
+ "cannot read validated CI selection: unreadable JSON or invalid selection",
1968
+ );
1969
+ selection = parsed.value;
1970
+ }
1400
1971
  const given = [f.head, f.pr, f.squashOf].filter((v) => v !== undefined).length;
1401
1972
  if (given !== 1)
1402
1973
  throw new CommandError(EXIT.USAGE, "give exactly one of --head, --pr, --squash-of");
1974
+ if (f.fetch === true) {
1975
+ const branch = str(f.branch);
1976
+ if (branch === undefined) throw new CommandError(EXIT.USAGE, "--fetch needs --branch");
1977
+ // Best-effort: the gate reads CI, not the local ref; a failed fetch is logged, not fatal.
1978
+ const fetched = fetchRemoteRef(ctx.cwd, `origin/${branch}`);
1979
+ if (fetched !== null && !fetched.ok)
1980
+ ctx.log(`fetch of origin/${branch} failed: ${fetched.stderr.trim()}`);
1981
+ }
1403
1982
  const root = checkoutRoot(ctx.cwd);
1404
1983
  const gh: Gh = (args) => runGh(ctx.cwd, args);
1405
1984
  const record = str(f.record);
@@ -1491,7 +2070,7 @@ function runGate(ctx: RunContext): number {
1491
2070
  // A title carrying a skip token would squash into a dev commit CI never runs on.
1492
2071
  const title = pr?.kind === "ok" ? (pr.pr?.title ?? "") : "";
1493
2072
  const titleToken = f.pr !== undefined ? SKIP_CI_TOKEN.exec(title)?.[0] : undefined;
1494
- const r: GateResult =
2073
+ let r: GateResult =
1495
2074
  titleToken !== undefined
1496
2075
  ? {
1497
2076
  code: GATE.TITLE_SKIP,
@@ -1508,6 +2087,8 @@ function runGate(ctx: RunContext): number {
1508
2087
  repo: str(f.repo) ?? null,
1509
2088
  skippedLanes: [],
1510
2089
  nonBookkeepingPaths: [],
2090
+ failedSteps: [],
2091
+ regenerable: false,
1511
2092
  reason: `PR title '${title}' contains the CI-suppressing token ${titleToken}`,
1512
2093
  }
1513
2094
  : shipGate(
@@ -1529,6 +2110,54 @@ function runGate(ctx: RunContext): number {
1529
2110
  );
1530
2111
  if (titleToken !== undefined) ctx.log(r.reason);
1531
2112
 
2113
+ // Debug retains the configured gate above and also proves the original
2114
+ // selected workflow at the pushed head. A different workflow need not contain
2115
+ // the configured capstone, but its whole run must have completed successfully.
2116
+ let verifyingRun: Run | undefined;
2117
+ if (r.code === EXIT.OK && selection?.mode === "ci") {
2118
+ const repo = str(f.repo) ?? r.repo;
2119
+ let reason = "";
2120
+ let code: number = GATE.FAILED;
2121
+ if (repo !== selection.repo) {
2122
+ reason = "selected CI repository differs from the gated repository";
2123
+ } else {
2124
+ const response = gh([
2125
+ "api",
2126
+ `/repos/${selection.repo}/actions/workflows/${selection.workflowId}/runs?head_sha=${queryValue(head)}`,
2127
+ ]);
2128
+ if (!response.ok) {
2129
+ code = response.missing ? EXIT.USE_MCP : GATE.API_ERROR;
2130
+ reason = "selected workflow verification is unavailable";
2131
+ } else {
2132
+ const payload = jsonOrUndefined(response.stdout);
2133
+ const candidates = arr(obj(payload).workflow_runs)
2134
+ .filter(
2135
+ (value) =>
2136
+ String(obj(value).workflow_id) === selection.workflowId &&
2137
+ text(obj(obj(value).repository).full_name).toLowerCase() ===
2138
+ selection.repo.toLowerCase() &&
2139
+ text(obj(obj(value).head_repository).full_name).toLowerCase() ===
2140
+ selection.repo.toLowerCase() &&
2141
+ obj(value).head_branch === (str(f.branch) ?? selection.headBranch) &&
2142
+ (str(f.event) === undefined || obj(value).event === str(f.event)),
2143
+ )
2144
+ .map(toRun)
2145
+ .filter((run) => run.head_sha === head && run.id !== null);
2146
+ verifyingRun = latest(candidates.filter((run) => run.status === "completed"));
2147
+ if (!verifyingRun) {
2148
+ code = candidates.length > 0 ? GATE.IN_PROGRESS : GATE.NO_RUN;
2149
+ reason = `selected workflow ${selection.workflowId} has no completed run at pushed head ${head}`;
2150
+ } else if (verifyingRun.conclusion !== "success") {
2151
+ reason = `selected workflow verification concluded '${verifyingRun.conclusion}' at pushed head ${head}`;
2152
+ }
2153
+ }
2154
+ }
2155
+ if (reason) {
2156
+ ctx.log(reason);
2157
+ r = { ...r, code, passed: false, overridden: false, reason };
2158
+ }
2159
+ }
2160
+
1532
2161
  if (recordFile !== undefined && r.code !== EXIT.USE_MCP) {
1533
2162
  if (f.capstoneOnly === true) {
1534
2163
  const verdict = r.code === EXIT.OK ? "PASS" : "FAIL";
@@ -1542,7 +2171,17 @@ function runGate(ctx: RunContext): number {
1542
2171
  auditRow(recordFile, "ship-gate-refusal", { exitCode: r.code, head: r.mergeHead });
1543
2172
  }
1544
2173
  }
1545
- ctx.emit({ ...r });
2174
+ ctx.emit({
2175
+ ...r,
2176
+ ...(selection?.mode === "ci"
2177
+ ? {
2178
+ originalRunId: selection.runId,
2179
+ originalRunUrl: selection.runUrl,
2180
+ verifyingRunId: verifyingRun?.id ?? null,
2181
+ verifyingRunUrl: verifyingRun?.html_url ?? null,
2182
+ }
2183
+ : {}),
2184
+ });
1546
2185
  return r.code;
1547
2186
  }
1548
2187
 
@@ -1550,14 +2189,6 @@ function runGate(ctx: RunContext): number {
1550
2189
  // revalidate
1551
2190
  // ---------------------------------------------------------------------------
1552
2191
 
1553
- /** Whether dev demands status checks (ruleset or branch protection): CI must then pass at the PR head. */
1554
- function devRequiresChecks(gh: Gh, repo: string): boolean {
1555
- const rules = gh(["api", `repos/${repo}/rules/branches/dev`]);
1556
- const list = rules.ok ? arr(jsonOrUndefined(rules.stdout)) : [];
1557
- if (list.some((r) => obj(r).type === "required_status_checks")) return true;
1558
- return gh(["api", `repos/${repo}/branches/dev/protection/required_status_checks`]).ok;
1559
- }
1560
-
1561
2192
  async function runRevalidate(ctx: RunContext): Promise<number> {
1562
2193
  const f = ctx.flags;
1563
2194
  const repoFlag = str(f.repo);
@@ -1718,25 +2349,31 @@ async function runContext(ctx: RunContext): Promise<number> {
1718
2349
  prState: null,
1719
2350
  runId: null,
1720
2351
  };
2352
+ const tracker = readIssueTracker(ctx.cwd);
1721
2353
  if (chosen.mode === "BRIEF") {
1722
- ctx.emit({ ...out, issueId: arg });
2354
+ ctx.emit(await withIssue(ctx, { ...out, issueId: arg }, tracker));
1723
2355
  return EXIT.OK;
1724
2356
  }
1725
- const tracker = readIssueTracker(ctx.cwd);
1726
2357
  if (!/^[0-9]+$/.test(arg)) {
1727
2358
  // CI_DEV: a post-merge dev failure names the FID slug; checked before any path sees it.
1728
2359
  if (!FID_PATTERNS.any.test(arg)) {
1729
2360
  ctx.log(`Invalid CI_DEV FID: ${arg}`);
1730
2361
  return EXIT_NO_FID;
1731
2362
  }
1732
- ctx.emit({
1733
- ...out,
1734
- mode: "CI_DEV",
1735
- fid: arg,
1736
- issueId: tracker === "none" ? null : issueIdOf(arg, "any"),
1737
- branch: DEV,
1738
- headSha: git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "",
1739
- });
2363
+ ctx.emit(
2364
+ await withIssue(
2365
+ ctx,
2366
+ {
2367
+ ...out,
2368
+ mode: "CI_DEV",
2369
+ fid: arg,
2370
+ issueId: tracker === "none" ? null : issueIdOf(arg, "any"),
2371
+ branch: DEV,
2372
+ headSha: git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "",
2373
+ },
2374
+ tracker,
2375
+ ),
2376
+ );
1740
2377
  return EXIT.OK;
1741
2378
  }
1742
2379
  const view = runGh(ctx.cwd, [
@@ -1801,10 +2438,35 @@ async function runContext(ctx: RunContext): Promise<number> {
1801
2438
  ctx.emit(out);
1802
2439
  return EXIT_NO_FID;
1803
2440
  }
1804
- ctx.emit({ ...out, fid: parsed.fid, issueId: parsed.issueId });
2441
+ if (parsed.issueId === null && tracker !== "none") {
2442
+ ctx.log(`FID ${parsed.fid} names no issue; /bkit-auto runs from an issue only`);
2443
+ ctx.emit(out);
2444
+ return EXIT_NO_FID;
2445
+ }
2446
+ ctx.emit(await withIssue(ctx, { ...out, fid: parsed.fid, issueId: parsed.issueId }, tracker));
1805
2447
  return EXIT.OK;
1806
2448
  }
1807
2449
 
2450
+ /**
2451
+ * `ref` (the issue as a workflow argument: `#N` on GitHub, the key uppercased on
2452
+ * Linear / Jira) and `labels` (read from the tracker; null when there is no issue
2453
+ * or the read failed, logged).
2454
+ */
2455
+ async function withIssue(
2456
+ ctx: RunContext,
2457
+ out: Record<string, unknown>,
2458
+ tracker: IssueTracker,
2459
+ ): Promise<Record<string, unknown>> {
2460
+ const id = typeof out.issueId === "string" && out.issueId !== "" ? out.issueId : null;
2461
+ const ref = issueRef(id, tracker);
2462
+ if (id === null || tracker === "none") return { ...out, ref, labels: null };
2463
+ let labels: string[] | null = null;
2464
+ const read = await attempt("labels", ctx.log, async () => {
2465
+ labels = await readLabels(trackerTarget(ctx.cwd, { issue: id }));
2466
+ });
2467
+ return { ...out, ref, labels: "done" in read && read.done ? labels : null };
2468
+ }
2469
+
1808
2470
  async function runMirror(ctx: RunContext): Promise<number> {
1809
2471
  const f = ctx.flags;
1810
2472
  const head = String(f.head);
@@ -1849,9 +2511,63 @@ export const runsCommand: CommandSpec = {
1849
2511
  summary:
1850
2512
  "CI runs: wait for one, prove one was dispatched, re-validate and gate a merge on one; auto's start context.",
1851
2513
  verbs: {
2514
+ locate: {
2515
+ summary:
2516
+ "Select and validate the red CI run for the adopted debug branch before local discovery: exit 0 selects red CI, 1 selects local discovery, 2 rejects arguments, 8 rejects ambiguous references, 80 requests read fallback, and 82 requires owner action for unavailable or mismatched evidence.",
2517
+ use: "workflow",
2518
+ flags: [
2519
+ {
2520
+ name: "prompt-file",
2521
+ type: "string",
2522
+ required: true,
2523
+ help: "session prompt; [local] overrides all CI references",
2524
+ },
2525
+ {
2526
+ name: "issue-text-file",
2527
+ type: "string",
2528
+ help: "current issue description and human comments from issues text",
2529
+ },
2530
+ { name: "branch", type: "string", required: true, help: "adopted existing branch" },
2531
+ { name: "repo", type: "string", required: true, help: "owner/repository" },
2532
+ {
2533
+ name: "file",
2534
+ type: "string",
2535
+ help: "active debug status log; saved selection takes precedence over issue discovery",
2536
+ },
2537
+ {
2538
+ name: "selection-out",
2539
+ type: "string",
2540
+ required: true,
2541
+ help: "write the validated candidate selection; does not update active metadata",
2542
+ },
2543
+ {
2544
+ name: "evidence-file",
2545
+ type: "string",
2546
+ help: "normalized fallback JSON: exact request identity, run, complete jobs, complete:true; automatic no-red also identifies workflow and inspected head",
2547
+ },
2548
+ ],
2549
+ output: {
2550
+ selection: "ci | local",
2551
+ runId: "selected run ID, or null",
2552
+ runUrl: "selected attempt URL, or null",
2553
+ runAttempt: "frozen attempt, or null",
2554
+ workflowId: "selected workflow ID, or null",
2555
+ workflowPath: "selected workflow path, or null",
2556
+ headSha: "selected commit, or null",
2557
+ headRelation: "current | ancestor | null; divergent or unknown evidence exits 82",
2558
+ failedJobs: "complete failed-job list",
2559
+ tiers: "known failed tiers; empty when any failed job is unknown",
2560
+ via: "prompt-run | prompt-pr | issue-run | issue-pr | branch, or null",
2561
+ reason: "local selection reason, or null",
2562
+ selectionFile: "validated candidate JSON path",
2563
+ },
2564
+ exitCodes: { 8: "ambiguous winning references" },
2565
+ run: locateCi,
2566
+ },
1852
2567
  wait: {
1853
2568
  summary:
1854
2569
  "Bounded poll for a CI check on a PR (--pr) or a CI run at a head (--head --branch), present or completed.",
2570
+ use: "by-hand",
1855
2571
  flags: [
1856
2572
  { name: "pr", type: "string", help: "PR number: read its check rollup" },
1857
2573
  { ...HEAD_FLAG, help: "commit SHA: read the CI workflow's runs at it (with --branch)" },
@@ -1890,12 +2606,18 @@ export const runsCommand: CommandSpec = {
1890
2606
  },
1891
2607
  dispatch: {
1892
2608
  summary:
1893
- "CI-Dispatch Gate after the last push: poll, one clean re-trigger, the ciDispatch verdict, and the body scan.",
2609
+ "CI-Dispatch Gate after the last push: poll, one clean re-trigger, the ciDispatch verdict, and the body scan. A run in place on dev has no PR: it polls the push-event run at the pushed sha, and its re-trigger commits and pushes only the run's own work.",
2610
+ use: "workflow",
1894
2611
  flags: [
1895
2612
  {
1896
2613
  name: "pr",
1897
2614
  type: "string",
1898
- help: "PR number (default: the open PR from this branch into dev)",
2615
+ help: "PR number (default: the open PR from this branch into dev; none on dev itself: the push-event run at --sha is read instead)",
2616
+ },
2617
+ {
2618
+ name: "sha",
2619
+ type: "string",
2620
+ help: "a run in place on dev (no PR): the full 40-hex sha its push landed, which the CI run is looked up at (default: HEAD); an own-commit push lands copies, so pass the push's `sha`",
1899
2621
  },
1900
2622
  {
1901
2623
  name: "fid",
@@ -1951,8 +2673,8 @@ export const runsCommand: CommandSpec = {
1951
2673
  ciDispatch:
1952
2674
  "{outcome, head, attempts, retrigger, reason?} — record with `bkit steps done --field ciDispatch=…` (local only, never pushed); null on a hand-off",
1953
2675
  phase: "done | poll | repoll (which poll was handed to the agent)",
1954
- pr: "PR number polled (null when none was found)",
1955
- head: "the pushed head (the re-trigger commit after a re-trigger)",
2676
+ pr: "PR number polled (null when none was found, or a run in place on dev, whose run is read at head)",
2677
+ head: "the pushed head (the re-trigger commit after a re-trigger; on dev with a record, the sha its own-commit push landed)",
1956
2678
  attempts: "poll attempts so far",
1957
2679
  retrigger: "a re-trigger commit was pushed",
1958
2680
  scanResult:
@@ -1960,6 +2682,8 @@ export const runsCommand: CommandSpec = {
1960
2682
  ciWorkflow: "the CI workflow file the no-ci check looked for",
1961
2683
  row: "--file: the step-done row written (null on a hand-off)",
1962
2684
  transport: "--file: the close-transport row written for a passed verdict, else null",
2685
+ progressLine:
2686
+ "--file: the exact chat progress line after a numbered completion is recorded",
1963
2687
  },
1964
2688
  exitCodes: {
1965
2689
  [EXIT_SKIP_TOKEN]: "the pushed head's body carries a CI-suppression token",
@@ -1971,7 +2695,13 @@ export const runsCommand: CommandSpec = {
1971
2695
  gate: {
1972
2696
  summary:
1973
2697
  "Ship merge gate: the capstone job present and green at the head (exit 0), or why not.",
2698
+ use: "workflow",
1974
2699
  flags: [
2700
+ {
2701
+ name: "ci-selection-file",
2702
+ type: "string",
2703
+ help: "validated original debug selection: additionally require its workflow to succeed at the exact pushed head",
2704
+ },
1975
2705
  { ...HEAD_FLAG, help: "the PR head to merge (or --pr / --squash-of)" },
1976
2706
  {
1977
2707
  name: "pr",
@@ -2006,6 +2736,11 @@ export const runsCommand: CommandSpec = {
2006
2736
  type: "string",
2007
2737
  help: "PR branch: tells a superseded head (14) from no run (10)",
2008
2738
  },
2739
+ {
2740
+ name: "fetch",
2741
+ type: "boolean",
2742
+ help: "fetch origin/<--branch> first (best-effort, logged on failure)",
2743
+ },
2009
2744
  {
2010
2745
  name: "event",
2011
2746
  type: "string",
@@ -2031,6 +2766,12 @@ export const runsCommand: CommandSpec = {
2031
2766
  testedHead: "head the selected (or superseded) run tested",
2032
2767
  runId: "selected run id",
2033
2768
  runUrl: "selected run URL",
2769
+ originalRunId: "--ci-selection-file: original failing run ID",
2770
+ originalRunUrl: "--ci-selection-file: original failing attempt URL",
2771
+ verifyingRunId:
2772
+ "--ci-selection-file: selected workflow's verifying run ID at the pushed head",
2773
+ verifyingRunUrl:
2774
+ "--ci-selection-file: selected workflow's verifying run URL at the pushed head",
2034
2775
  conclusion: "selected run conclusion",
2035
2776
  capstone: "capstone job name",
2036
2777
  ciWorkflow: "CI workflow file",
@@ -2059,6 +2800,7 @@ export const runsCommand: CommandSpec = {
2059
2800
  revalidate: {
2060
2801
  summary:
2061
2802
  "Ship: pick the head CI must pass at, probe for a run there, dispatch only when none, wait for it to complete.",
2803
+ use: "workflow",
2062
2804
  flags: [
2063
2805
  { name: "pr", type: "string", required: true, help: "the PR number" },
2064
2806
  { name: "entry-head", type: "string", required: true, help: "the PR head read at Step 2" },
@@ -2108,6 +2850,7 @@ export const runsCommand: CommandSpec = {
2108
2850
  mirror: {
2109
2851
  summary:
2110
2852
  "Release PR: wait for the branch's push run at the head and copy its capstone verdict.",
2853
+ use: "workflow",
2111
2854
  flags: [
2112
2855
  { ...HEAD_FLAG, required: true, help: "the PR head (same SHA the push run tests)" },
2113
2856
  { name: "branch", type: "string", help: "branch whose push run to mirror (default dev)" },
@@ -2143,6 +2886,7 @@ export const runsCommand: CommandSpec = {
2143
2886
  context: {
2144
2887
  summary:
2145
2888
  "/bkit-auto Step 1: the phase and mode, the repo, and the issue / FID / PR / run the dispatch carries.",
2889
+ use: "workflow",
2146
2890
  flags: [
2147
2891
  {
2148
2892
  name: "phase",
@@ -2169,6 +2913,9 @@ export const runsCommand: CommandSpec = {
2169
2913
  owner: "owner half",
2170
2914
  repo: "repo half",
2171
2915
  issueId: "the issue (BRIEF: the arg; CI: from the marker or branch; null under no tracker)",
2916
+ ref: 'the issue as the phase workflow\'s argument: #N (GitHub), the key uppercased (Linear / Jira), else issueId verbatim or ""',
2917
+ labels:
2918
+ "the issue's labels read from the tracker; null with no issue or when the read failed (read them via the tracker MCP)",
2172
2919
  fid: "the FID (CI / CI_DEV), else null",
2173
2920
  prNumber: "the PR (CI), else null",
2174
2921
  branch: "the PR head branch (CI), dev (CI_DEV), else null",
@@ -2182,13 +2929,14 @@ export const runsCommand: CommandSpec = {
2182
2929
  [EXIT_PR_NOT_OPEN]: "the PR is not OPEN",
2183
2930
  [EXIT_NO_RUN_ID]: "no CI run at the PR head",
2184
2931
  [EXIT_NO_FID]:
2185
- "no valid FID (CI_DEV slug off the allowlist, or no marker / feat/{FID} branch)",
2932
+ "no valid FID or no issue (CI_DEV slug off the allowlist, no marker / feat/{FID} branch, or an issue-less FID: /bkit-auto runs issue-only)",
2186
2933
  },
2187
2934
  run: runContext,
2188
2935
  },
2189
2936
  declared: {
2190
2937
  summary:
2191
- "Whether the repo declares a CI workflow: .github/workflows/<bkit.ciWorkflow> exists (exit 0) or not (exit 1).",
2938
+ "Whether the repo declares a CI workflow: .github/workflows/<bkit.testing.ciWorkflow> exists (exit 0) or not (exit 1).",
2939
+ use: "by-hand",
2192
2940
  flags: [],
2193
2941
  output: {
2194
2942
  declared: "the workflow file exists",