@cbartens/bkit 5.5.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (297) hide show
  1. package/.bkit/README.md +30 -20
  2. package/.bkit/core/.agents/docs.md +1 -0
  3. package/.bkit/core/.agents/rules.md +51 -26
  4. package/.bkit/core/.bkit/README.md +29 -19
  5. package/.bkit/core/.bkit/authoring.md +117 -0
  6. package/.bkit/core/.bkit/cloud.md +11 -11
  7. package/.bkit/core/.bkit/comparison.md +5 -5
  8. package/.bkit/core/.bkit/install.md +20 -20
  9. package/.bkit/core/.bkit/jsonl.md +202 -122
  10. package/.bkit/core/.bkit/lite.md +1 -1
  11. package/.bkit/core/.bkit/pipeline.md +49 -52
  12. package/.bkit/core/.bkit/prompts.md +106 -167
  13. package/.bkit/core/.bkit/providers.md +29 -32
  14. package/.bkit/core/.bkit/templates.md +44 -18
  15. package/.bkit/core/.bkit/trackers.md +60 -28
  16. package/.bkit/core/.bkit/workflows.md +399 -359
  17. package/.bkit/core/AGENTS.md +16 -22
  18. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +14 -38
  19. package/.bkit/core/docs/templates/bkit-audit-adoption.md +16 -40
  20. package/.bkit/core/docs/templates/bkit-audit-agents.md +19 -43
  21. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +16 -40
  22. package/.bkit/core/docs/templates/bkit-audit-analytics.md +14 -38
  23. package/.bkit/core/docs/templates/bkit-audit-annotations.md +11 -35
  24. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +15 -39
  25. package/.bkit/core/docs/templates/bkit-audit-app-store.md +12 -36
  26. package/.bkit/core/docs/templates/bkit-audit-architecture.md +16 -40
  27. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +16 -40
  28. package/.bkit/core/docs/templates/bkit-audit-config.md +18 -42
  29. package/.bkit/core/docs/templates/bkit-audit-cost.md +16 -40
  30. package/.bkit/core/docs/templates/bkit-audit-coverage.md +15 -39
  31. package/.bkit/core/docs/templates/bkit-audit-database.md +16 -40
  32. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +15 -39
  33. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +15 -38
  34. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +16 -40
  35. package/.bkit/core/docs/templates/bkit-audit-documentation.md +11 -35
  36. package/.bkit/core/docs/templates/bkit-audit-duplication.md +18 -42
  37. package/.bkit/core/docs/templates/bkit-audit-failures.md +13 -37
  38. package/.bkit/core/docs/templates/bkit-audit-flakes.md +12 -36
  39. package/.bkit/core/docs/templates/bkit-audit-gates.md +14 -38
  40. package/.bkit/core/docs/templates/bkit-audit-issues.md +15 -39
  41. package/.bkit/core/docs/templates/bkit-audit-llm.md +16 -40
  42. package/.bkit/core/docs/templates/bkit-audit-logs.md +14 -38
  43. package/.bkit/core/docs/templates/bkit-audit-models.md +12 -36
  44. package/.bkit/core/docs/templates/bkit-audit-privacy.md +12 -36
  45. package/.bkit/core/docs/templates/bkit-audit-prompts.md +15 -39
  46. package/.bkit/core/docs/templates/bkit-audit-red-team.md +15 -39
  47. package/.bkit/core/docs/templates/bkit-audit-reliability.md +15 -39
  48. package/.bkit/core/docs/templates/bkit-audit-repo.md +12 -36
  49. package/.bkit/core/docs/templates/bkit-audit-security.md +13 -37
  50. package/.bkit/core/docs/templates/bkit-audit-slop.md +14 -38
  51. package/.bkit/core/docs/templates/bkit-audit-testing.md +12 -36
  52. package/.bkit/core/docs/templates/bkit-audit-usability.md +16 -40
  53. package/.bkit/core/docs/templates/bkit-plan.md +97 -226
  54. package/.bkit/core/engine/checks/after/ci-yml.ts +39 -30
  55. package/.bkit/core/engine/checks/after/github.ts +101 -72
  56. package/.bkit/core/engine/checks/after/index.ts +10 -12
  57. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  58. package/.bkit/core/engine/checks/after/tools.ts +47 -92
  59. package/.bkit/core/engine/checks/before/env.ts +2 -2
  60. package/.bkit/core/engine/checks/before/files.ts +5 -4
  61. package/.bkit/core/engine/checks/before/index.ts +18 -1
  62. package/.bkit/core/engine/checks/before/repo.ts +168 -2
  63. package/.bkit/core/engine/checks/tips/catalogue.ts +16 -5
  64. package/.bkit/core/engine/checks/tips/detect.ts +34 -0
  65. package/.bkit/core/engine/checks/tips/index.ts +10 -7
  66. package/.bkit/core/engine/cli.ts +20 -53
  67. package/.bkit/core/engine/commands/analysis.ts +171 -140
  68. package/.bkit/core/engine/commands/ci/ci.ts +6 -6
  69. package/.bkit/core/engine/commands/comply.ts +77 -103
  70. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  71. package/.bkit/core/engine/commands/install/install.ts +57 -18
  72. package/.bkit/core/engine/commands/install/uninstall.ts +65 -28
  73. package/.bkit/core/engine/commands/land.ts +18 -12
  74. package/.bkit/core/engine/commands/lib.ts +79 -17
  75. package/.bkit/core/engine/commands/registry.ts +4 -0
  76. package/.bkit/core/engine/commands/setup/setup.ts +7 -7
  77. package/.bkit/core/engine/commands/stats.ts +204 -0
  78. package/.bkit/core/engine/commands/tips.ts +10 -5
  79. package/.bkit/core/engine/commands/workflow/branches.ts +741 -62
  80. package/.bkit/core/engine/commands/workflow/challenge.ts +673 -0
  81. package/.bkit/core/engine/commands/workflow/context.ts +853 -29
  82. package/.bkit/core/engine/commands/workflow/counters.ts +267 -84
  83. package/.bkit/core/engine/commands/workflow/decisions.ts +541 -0
  84. package/.bkit/core/engine/commands/workflow/disk.ts +2 -2
  85. package/.bkit/core/engine/commands/workflow/fids.ts +793 -33
  86. package/.bkit/core/engine/commands/workflow/issues.ts +427 -105
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +884 -27
  88. package/.bkit/core/engine/commands/workflow/locks.ts +26 -2
  89. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +582 -0
  90. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  91. package/.bkit/core/engine/commands/workflow/prs.ts +166 -30
  92. package/.bkit/core/engine/commands/workflow/repo.ts +59 -7
  93. package/.bkit/core/engine/commands/workflow/roadmap.ts +16 -7
  94. package/.bkit/core/engine/commands/workflow/run-facts.ts +501 -0
  95. package/.bkit/core/engine/commands/workflow/runs.ts +179 -49
  96. package/.bkit/core/engine/commands/workflow/runtime.ts +22 -1
  97. package/.bkit/core/engine/commands/workflow/status.ts +142 -29
  98. package/.bkit/core/engine/commands/workflow/step-table.ts +339 -0
  99. package/.bkit/core/engine/commands/workflow/steps.ts +213 -88
  100. package/.bkit/core/engine/commands/workflow/summary.ts +398 -0
  101. package/.bkit/core/engine/commands/workflow/tests.ts +1013 -148
  102. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  103. package/.bkit/core/engine/commands/workflow/workflows.ts +984 -207
  104. package/.bkit/core/engine/commands/workflow/workstreams.ts +11 -5
  105. package/.bkit/core/engine/commands/workflow/worktrees.ts +276 -22
  106. package/.bkit/core/engine/install/manifest.ts +11 -9
  107. package/.bkit/core/engine/install/modules/cloud.ts +21 -13
  108. package/.bkit/core/engine/install/modules/core.ts +325 -7
  109. package/.bkit/core/engine/install/modules/opencode.ts +2 -2
  110. package/.bkit/core/engine/install/version-file.ts +6 -2
  111. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  112. package/.bkit/core/engine/ledgers/status.ts +92 -15
  113. package/.bkit/core/engine/ledgers/telemetry.ts +1261 -254
  114. package/.bkit/core/engine/render/hosts.ts +4 -0
  115. package/.bkit/core/engine/render/models.ts +12 -0
  116. package/.bkit/core/engine/shared/branches.ts +4 -1
  117. package/.bkit/core/engine/shared/egress.ts +7 -0
  118. package/.bkit/core/engine/shared/json.ts +25 -7
  119. package/.bkit/core/engine/shared/settings.ts +202 -33
  120. package/.bkit/core/engine/shared/text.ts +361 -0
  121. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  122. package/.bkit/core/engine/tools/instructions-sources.ts +834 -0
  123. package/.bkit/core/engine/tools/instructions.ts +1751 -0
  124. package/.bkit/core/hooks/gateguard-engine.js +24 -23
  125. package/.bkit/core/hooks/guardrails-shell.js +2 -3
  126. package/.bkit/core/hooks/guardrails-tiers.js +7 -1
  127. package/.bkit/core/hooks/readguard-engine.js +2 -2
  128. package/.bkit/core/prompts/bkit-audit-generate.md +62 -25
  129. package/.bkit/core/prompts/bkit-build-challenge-1.md +40 -17
  130. package/.bkit/core/prompts/bkit-build-challenge-2.md +44 -17
  131. package/.bkit/core/prompts/bkit-build-install-skills.md +26 -13
  132. package/.bkit/core/prompts/bkit-build-plan-convert.md +74 -0
  133. package/.bkit/core/prompts/bkit-build-plan-current.md +26 -13
  134. package/.bkit/core/prompts/bkit-build-plan-execute.md +74 -26
  135. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +64 -23
  136. package/.bkit/core/prompts/bkit-build-plan-verify.md +57 -33
  137. package/.bkit/core/prompts/bkit-debug-abort-handover.md +30 -14
  138. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +34 -14
  139. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +34 -17
  140. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +26 -13
  141. package/.bkit/core/prompts/bkit-debug-failure-soak.md +31 -16
  142. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +21 -11
  143. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +20 -11
  144. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +20 -11
  145. package/.bkit/core/prompts/bkit-design-generate.md +33 -13
  146. package/.bkit/core/prompts/bkit-design-organise.md +25 -12
  147. package/.bkit/core/prompts/bkit-design-review-1.md +31 -15
  148. package/.bkit/core/prompts/bkit-design-review-2.md +28 -13
  149. package/.bkit/core/prompts/bkit-design-spike.md +30 -13
  150. package/.bkit/core/prompts/bkit-design-update.md +33 -19
  151. package/.bkit/core/prompts/bkit-plan-generate.md +75 -19
  152. package/.bkit/core/prompts/bkit-plan-review-1.md +50 -27
  153. package/.bkit/core/prompts/bkit-plan-review-2.md +59 -28
  154. package/.bkit/core/prompts/bkit-plan-scope-check.md +109 -0
  155. package/.bkit/core/prompts/bkit-plan-update.md +61 -24
  156. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +27 -15
  157. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +31 -16
  158. package/.bkit/core/prompts/bkit-ship-update-docs.md +30 -15
  159. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +24 -14
  160. package/.bkit/core/prompts/bkit-utility-update-decisions.md +32 -14
  161. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +29 -14
  162. package/.bkit/core/prompts/bkit-utility-update-documentation.md +28 -13
  163. package/.bkit/core/prompts/bkit-utility-update-failures.md +31 -14
  164. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +33 -14
  165. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +38 -17
  166. package/.bkit/core/prompts/bkit-utility-update-tracker.md +43 -20
  167. package/.bkit/core/workflows/bkit-auto.md +54 -46
  168. package/.bkit/core/workflows/bkit-build.md +577 -458
  169. package/.bkit/core/workflows/bkit-debug.md +348 -333
  170. package/.bkit/core/workflows/bkit-design.md +201 -237
  171. package/.bkit/core/workflows/bkit-plan.md +210 -321
  172. package/.bkit/core/workflows/bkit-ship.md +328 -278
  173. package/.bkit/shared/.bkit/.env.example +2 -2
  174. package/.bkit/shared/.claude/settings.json +11 -0
  175. package/.bkit/shared/.cursor/mcp.json +1 -1
  176. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  177. package/.bkit/shared/.gitattributes +1 -1
  178. package/.bkit/shared/.mcp.json +1 -1
  179. package/.bkit/shared/.opencode/opencode.json +11 -0
  180. package/.bkit/shared/CLAUDE.md +2 -2
  181. package/.bkit/shared/GEMINI.md +2 -2
  182. package/.bkit/shared/docs/architecture.md +1 -1
  183. package/.bkit/shared/docs/data-schema.md +1 -1
  184. package/.bkit/shared/docs/deployments.md +16 -28
  185. package/.bkit/shared/docs/design.md +1 -1
  186. package/.bkit/shared/docs/noise.md +1 -1
  187. package/.bkit/shared/docs/observability.md +2 -2
  188. package/.bkit/shared/docs/security.md +1 -1
  189. package/.bkit/shared/docs/setup.md +1 -1
  190. package/.bkit/shared/docs/technology.md +1 -1
  191. package/.bkit/shared/docs/testing.md +27 -10
  192. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +1 -1
  193. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +26 -5
  194. package/.bkit/templates/.github/workflows/bkit-ci.yml +22 -84
  195. package/.bkit/templates/.github/workflows/bkit-cloud.yml +21 -19
  196. package/.bkit/templates/.husky/pre-push +52 -13
  197. package/.bkit/templates/.prettierignore +7 -0
  198. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +194 -0
  199. package/.bkit/templates/scripts/ci/check-capstone.mjs +2 -4
  200. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +4 -23
  201. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.mjs +104 -23
  202. package/.bkit/templates/scripts/ci/lanes/resolve-push-base.test.mjs +103 -6
  203. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +1 -1
  204. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +3 -1
  205. package/.bkit/templates/scripts/prettier/bkit-insert-ignore.mjs +49 -29
  206. package/CHANGELOG.md +142 -0
  207. package/README.md +58 -34
  208. package/dist/checks/after/ci-yml.js +39 -29
  209. package/dist/checks/after/github.js +99 -72
  210. package/dist/checks/after/index.js +11 -13
  211. package/dist/checks/after/suppression.js +8 -5
  212. package/dist/checks/after/tools.js +40 -83
  213. package/dist/checks/before/env.js +2 -2
  214. package/dist/checks/before/files.js +5 -3
  215. package/dist/checks/before/index.js +15 -2
  216. package/dist/checks/before/repo.js +163 -2
  217. package/dist/checks/tips/catalogue.js +14 -5
  218. package/dist/checks/tips/detect.js +32 -0
  219. package/dist/checks/tips/index.js +7 -5
  220. package/dist/cli.js +19 -47
  221. package/dist/commands/analysis.js +109 -100
  222. package/dist/commands/ci/ci.js +6 -6
  223. package/dist/commands/comply.js +54 -91
  224. package/dist/commands/install/doctor.js +2 -2
  225. package/dist/commands/install/install.js +50 -19
  226. package/dist/commands/install/uninstall.js +59 -28
  227. package/dist/commands/land.js +16 -12
  228. package/dist/commands/lib.js +51 -16
  229. package/dist/commands/registry.js +4 -0
  230. package/dist/commands/setup/setup.js +7 -7
  231. package/dist/commands/stats.js +136 -0
  232. package/dist/commands/tips.js +7 -3
  233. package/dist/commands/workflow/branches.js +656 -56
  234. package/dist/commands/workflow/challenge.js +556 -0
  235. package/dist/commands/workflow/context.js +709 -30
  236. package/dist/commands/workflow/counters.js +208 -75
  237. package/dist/commands/workflow/decisions.js +441 -0
  238. package/dist/commands/workflow/disk.js +2 -2
  239. package/dist/commands/workflow/fids.js +689 -33
  240. package/dist/commands/workflow/issues.js +362 -99
  241. package/dist/commands/workflow/ledgers.js +762 -27
  242. package/dist/commands/workflow/locks.js +24 -2
  243. package/dist/commands/workflow/plan-blocks.js +437 -0
  244. package/dist/commands/workflow/plan-versions.js +22 -0
  245. package/dist/commands/workflow/prs.js +142 -32
  246. package/dist/commands/workflow/repo.js +52 -7
  247. package/dist/commands/workflow/roadmap.js +9 -7
  248. package/dist/commands/workflow/run-facts.js +426 -0
  249. package/dist/commands/workflow/runs.js +144 -43
  250. package/dist/commands/workflow/runtime.js +12 -1
  251. package/dist/commands/workflow/status.js +130 -29
  252. package/dist/commands/workflow/step-table.js +276 -0
  253. package/dist/commands/workflow/steps.js +171 -80
  254. package/dist/commands/workflow/summary.js +275 -0
  255. package/dist/commands/workflow/tests.js +834 -136
  256. package/dist/commands/workflow/tracker.js +983 -0
  257. package/dist/commands/workflow/workflows.js +834 -195
  258. package/dist/commands/workflow/workstreams.js +11 -5
  259. package/dist/commands/workflow/worktrees.js +221 -22
  260. package/dist/install/manifest.js +11 -9
  261. package/dist/install/modules/cloud.js +22 -13
  262. package/dist/install/modules/core.js +326 -7
  263. package/dist/install/modules/opencode.js +2 -2
  264. package/dist/install/version-file.js +6 -2
  265. package/dist/ledgers/migrate.js +81 -0
  266. package/dist/ledgers/status.js +61 -8
  267. package/dist/ledgers/telemetry.js +905 -124
  268. package/dist/render/hosts.js +4 -0
  269. package/dist/render/models.js +12 -0
  270. package/dist/shared/branches.js +3 -1
  271. package/dist/shared/egress.js +7 -0
  272. package/dist/shared/json.js +20 -7
  273. package/dist/shared/settings.js +147 -26
  274. package/dist/shared/text.js +333 -0
  275. package/dist/tools/grammar-density.js +183 -0
  276. package/dist/tools/instructions-sources.js +721 -0
  277. package/dist/tools/instructions.js +1579 -0
  278. package/package.json +114 -23
  279. package/.bkit/core/engine/commands/harvest.ts +0 -459
  280. package/.bkit/core/engine/tools/wording.ts +0 -748
  281. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  282. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  283. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  284. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  285. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  286. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  287. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  288. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  289. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  290. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  291. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  292. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  293. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  294. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +0 -138
  295. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +0 -181
  296. package/dist/commands/harvest.js +0 -353
  297. package/dist/tools/wording.js +0 -680
@@ -45,12 +45,23 @@ import {
45
45
  import { readBkitConfig } from "../../shared/settings.js";
46
46
  import { TIMEOUTS } from "../../shared/timeouts.js";
47
47
  import { FID_PATTERNS, fromBranch, fromMarker, issueIdOf, readIssueTracker } from "./fids.js";
48
+ import type { IssueTracker } from "../../install/manifest.js";
48
49
  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";
50
+ import { fetchRemoteRef, pushBranch } from "./branches.js";
51
+ import { activeRecord, checkOnlyBookkeeping, retriggerCommit } from "./ledgers.js";
52
+ import {
53
+ closeTransportRow,
54
+ crossCheckFile,
55
+ devRequiresChecks,
56
+ prRepoSlug,
57
+ probePr,
58
+ type PrInfo,
59
+ } from "./prs.js";
51
60
  import { resolveOwnerRepo, splitSlug } from "./repo.js";
61
+ import { restateOutcome } from "./run-facts.js";
52
62
  import { extraField, str } from "./status.js";
53
63
  import { writeStepRow } from "./steps.js";
64
+ import { attempt, issueRef, readLabels, trackerTarget } from "./tracker.js";
54
65
 
55
66
  // ---------------------------------------------------------------------------
56
67
  // gh
@@ -87,7 +98,7 @@ export function checkNamespace(capstoneJob: string): string {
87
98
  return i > 0 ? capstoneJob.slice(0, i) : capstoneJob;
88
99
  }
89
100
 
90
- /** Whether `.github/workflows/<bkit.ciWorkflow>` exists — the only honest ground for a `no-ci` pass. */
101
+ /** Whether `.github/workflows/<bkit.testing.ciWorkflow>` exists — the only honest ground for a `no-ci` pass. */
91
102
  export function ciDeclared(root: string): { declared: boolean; ciWorkflow: string; path: string } {
92
103
  const { ciWorkflow } = readBkitConfig(root);
93
104
  const rel = path.join(".github", "workflows", ciWorkflow);
@@ -289,6 +300,11 @@ export interface DispatchOptions {
289
300
  supplied?: SuppliedPoll;
290
301
  /** The re-trigger commit is already pushed (re-entry after a hand-off in the re-poll). */
291
302
  retriggered: boolean;
303
+ /**
304
+ * The sha the run's last push landed on a shared branch, for a run with no PR.
305
+ * An own-commit push lands copies, so it is not necessarily local HEAD.
306
+ */
307
+ sha?: string;
292
308
  }
293
309
 
294
310
  export interface DispatchResult {
@@ -301,6 +317,8 @@ export interface DispatchResult {
301
317
  attempts: number;
302
318
  retrigger: boolean;
303
319
  ciWorkflow: string;
320
+ /** The branch the CI run is looked up on when there is no PR to read, else null. */
321
+ runBranch: string | null;
304
322
  }
305
323
 
306
324
  /** Exit code: the re-trigger commit or its push failed. */
@@ -327,7 +345,19 @@ export async function ciDispatchGate(
327
345
  const root = checkoutRoot(o.cwd);
328
346
  const { capstoneJob } = readBkitConfig(root);
329
347
  const declared = ciDeclared(root);
330
- const head = () => git(o.cwd, ["rev-parse", "HEAD"]) ?? "";
348
+ const branch = git(o.cwd, ["branch", "--show-current"]) ?? "";
349
+ const shared = branch !== "" && isSharedBranch(branch);
350
+ // A run in place on a shared branch has no PR: CI is the push-event run at the pushed sha.
351
+ const byRun = o.pr === null && shared;
352
+ // The sha an own-commit push landed; null while the head is local HEAD.
353
+ let landed: string | null = byRun ? (o.sha ?? null) : null;
354
+ const head = () => landed ?? git(o.cwd, ["rev-parse", "HEAD"]) ?? "";
355
+ /** The landed copy lives on the remote only; the scan and the suppressor check read it locally. */
356
+ const fetchLanded = () => {
357
+ if (landed === null || runGit(o.cwd, ["cat-file", "-e", `${landed}^{commit}`]).ok) return;
358
+ runGit(o.cwd, ["fetch", "origin", branch]);
359
+ };
360
+ fetchLanded();
331
361
  const res: DispatchResult = {
332
362
  phase: "done",
333
363
  handoff: 0,
@@ -336,13 +366,22 @@ export async function ciDispatchGate(
336
366
  attempts: 0,
337
367
  retrigger: o.retriggered,
338
368
  ciWorkflow: declared.ciWorkflow,
369
+ runBranch: byRun ? branch : null,
339
370
  };
340
- const target: WaitTarget = {
341
- kind: "pr-present",
342
- pr: o.pr ?? undefined,
343
- ciWorkflow: declared.ciWorkflow,
344
- namespace: checkNamespace(capstoneJob),
345
- };
371
+ const target: WaitTarget = byRun
372
+ ? {
373
+ kind: "run-present",
374
+ head: res.head,
375
+ branch,
376
+ ciWorkflow: declared.ciWorkflow,
377
+ namespace: checkNamespace(capstoneJob),
378
+ }
379
+ : {
380
+ kind: "pr-present",
381
+ pr: o.pr ?? undefined,
382
+ ciWorkflow: declared.ciWorkflow,
383
+ namespace: checkNamespace(capstoneJob),
384
+ };
346
385
  const poll = async (phase: "poll" | "repoll"): Promise<SuppliedPoll | null> => {
347
386
  // A supplied result answers only the poll that was handed off; later polls run fresh.
348
387
  if (o.supplied && (phase === "repoll") === o.retriggered) {
@@ -352,9 +391,12 @@ export async function ciDispatchGate(
352
391
  return o.supplied;
353
392
  }
354
393
  // 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 };
394
+ if (o.pr === null && !byRun) return { pollResult: "err", attempts: 0, allErrored: true };
395
+ if (byRun) target.head = head();
356
396
  deps.log(
357
- `polling for a ${target.namespace} check on PR #${o.pr} (budget ${o.budgetS}s, interval ${o.intervalS}s)`,
397
+ byRun
398
+ ? `polling for a ${target.ciWorkflow} run on ${branch} at ${target.head} (budget ${o.budgetS}s, interval ${o.intervalS}s)`
399
+ : `polling for a ${target.namespace} check on PR #${o.pr} (budget ${o.budgetS}s, interval ${o.intervalS}s)`,
358
400
  );
359
401
  const w = await waitLoop(
360
402
  { budgetS: o.budgetS, intervalS: o.intervalS, once: false },
@@ -399,13 +441,34 @@ export async function ciDispatchGate(
399
441
  );
400
442
  return verdict("unresolved", "timeout-dirty");
401
443
  }
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)) {
444
+ const message = `chore(${o.fid}): re-trigger${o.autoRouteSuffix}`;
445
+ // A run in place on a shared branch commits and pushes only its own work; with
446
+ // no record of the run there, nothing is committed or pushed.
447
+ const rec = shared ? activeRecord(o.cwd, o.fid) : null;
448
+ if (shared && rec === null) {
449
+ deps.log(
450
+ `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`,
451
+ );
452
+ res.phase = "repoll";
453
+ res.handoff = EXIT_RETRIGGER_FAILED;
454
+ return res;
455
+ }
456
+ let pushed: boolean;
457
+ if (rec === null) {
458
+ landed = null;
459
+ pushed =
460
+ runGit(o.cwd, ["commit", "--allow-empty", "-m", message]).ok && pushCurrentBranch(o.cwd);
461
+ } else {
462
+ const made = retriggerCommit(o.cwd, rec, message);
463
+ if (!made.ok) deps.log(`re-trigger commit failed: ${made.error}`);
464
+ const out = made.ok
465
+ ? await pushBranch(o.cwd, { mode: "feature", fid: o.fid }, deps.log)
466
+ : null;
467
+ landed = out?.out.pushed === true ? out.out.sha : landed;
468
+ pushed = out?.out.pushed === true && out.out.sha !== null;
469
+ if (pushed) fetchLanded();
470
+ }
471
+ if (!pushed) {
409
472
  deps.log("re-trigger commit or push failed — no verdict; route to the Failure Path");
410
473
  res.phase = "repoll";
411
474
  res.handoff = EXIT_RETRIGGER_FAILED;
@@ -465,7 +528,7 @@ export const GATE = {
465
528
  SUPERSEDED: 14,
466
529
  /** The selected run was cancelled. */
467
530
  CANCELLED: 15,
468
- /** A lane named in bkit.shipGateRequiredLanes concluded skipped. */
531
+ /** A lane named in bkit.testing.shipGate concluded skipped. */
469
532
  LANE_SKIPPED: 16,
470
533
  /** --validated is not an ancestor of the head plus bookkeeping-only commits. */
471
534
  NOT_BOOKKEEPING: 17,
@@ -900,7 +963,7 @@ export function shipGate(o: GateOptions, gh: Gh, log: (m: string) => void): Gate
900
963
  );
901
964
  const required = r.skippedLanes.filter((l) => requiredLanes.includes(l));
902
965
  if (required.length) {
903
- log(`declared in bkit.shipGateRequiredLanes: ${requiredLanes.join(",")}`);
966
+ log(`declared in bkit.testing.shipGate: ${requiredLanes.join(",")}`);
904
967
  return refuse(
905
968
  GATE.LANE_SKIPPED,
906
969
  `required lane(s) concluded 'skipped' at head ${r.head} — vacuous green: ${required.join(", ")}`,
@@ -1064,12 +1127,12 @@ const REPO_FLAG: FlagSpec = {
1064
1127
  const CI_WORKFLOW_FLAG: FlagSpec = {
1065
1128
  name: "ci-workflow",
1066
1129
  type: "string",
1067
- help: "CI workflow file (default: package.json bkit.ciWorkflow)",
1130
+ help: "CI workflow file (default: package.json bkit.testing.ciWorkflow)",
1068
1131
  };
1069
1132
  const CAPSTONE_FLAG: FlagSpec = {
1070
1133
  name: "capstone",
1071
1134
  type: "string",
1072
- help: "capstone job name (default: package.json bkit.capstoneJob)",
1135
+ help: "capstone job name (default: package.json bkit.testing.ciCapstone)",
1073
1136
  };
1074
1137
  const BUDGET_FLAG: FlagSpec = { name: "budget-s", type: "string", help: "poll budget in seconds" };
1075
1138
  const INTERVAL_FLAG: FlagSpec = {
@@ -1237,6 +1300,20 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1237
1300
  }
1238
1301
  pr = found.pr;
1239
1302
  }
1303
+ const sha = str(f.sha);
1304
+ if (sha !== undefined && !/^[0-9a-f]{40}$/i.test(sha)) {
1305
+ throw new CommandError(
1306
+ EXIT.USAGE,
1307
+ "--sha must be the full 40-hex-digit commit sha (the CI run is matched on the full sha)",
1308
+ );
1309
+ }
1310
+ const onShared = isSharedBranch(git(ctx.cwd, ["branch", "--show-current"]) ?? "");
1311
+ if (sha !== undefined && (pr !== null || !onShared)) {
1312
+ throw new CommandError(
1313
+ EXIT.USAGE,
1314
+ "--sha goes with a run in place on a shared branch that has no PR",
1315
+ );
1316
+ }
1240
1317
  const pollResult = str(f.pollResult);
1241
1318
  if (pollResult !== undefined && !["found", "none", "err"].includes(pollResult)) {
1242
1319
  throw new CommandError(EXIT.USAGE, "--poll-result must be found, none, or err");
@@ -1263,6 +1340,7 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1263
1340
  allErrored: f.allErrored === true,
1264
1341
  },
1265
1342
  retriggered: f.retriggered === true,
1343
+ sha,
1266
1344
  },
1267
1345
  d,
1268
1346
  );
@@ -1295,6 +1373,10 @@ async function runDispatch(ctx: RunContext): Promise<number> {
1295
1373
  },
1296
1374
  ctx.log,
1297
1375
  ).row;
1376
+ if (/-close-workflow$/.test(step!)) {
1377
+ const tree = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1378
+ restateOutcome(tree, status, String(f.workflow ?? "build"), { ...r.ciDispatch }, ctx.log);
1379
+ }
1298
1380
  if (code === EXIT.OK || code === EXIT_SKIP_TOKEN) {
1299
1381
  const check = crossCheckFile(status, "gh", ctx.log);
1300
1382
  if (!check.ok) {
@@ -1344,8 +1426,12 @@ function dispatchCode(
1344
1426
  ): number {
1345
1427
  if (r.handoff === EXIT.AGENT_WAIT || r.handoff === EXIT.USE_MCP) {
1346
1428
  const again = r.phase === "repoll" ? " --retriggered" : "";
1429
+ const [wait, keep] =
1430
+ r.runBranch === null
1431
+ ? [`--pr=${pr ?? "<n>"}`, ""]
1432
+ : [`--head=${r.head} --branch=${r.runBranch} --until=present`, ` --sha=${r.head}`];
1347
1433
  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}`,
1434
+ `${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
1435
  );
1350
1436
  return r.handoff;
1351
1437
  }
@@ -1400,6 +1486,14 @@ function runGate(ctx: RunContext): number {
1400
1486
  const given = [f.head, f.pr, f.squashOf].filter((v) => v !== undefined).length;
1401
1487
  if (given !== 1)
1402
1488
  throw new CommandError(EXIT.USAGE, "give exactly one of --head, --pr, --squash-of");
1489
+ if (f.fetch === true) {
1490
+ const branch = str(f.branch);
1491
+ if (branch === undefined) throw new CommandError(EXIT.USAGE, "--fetch needs --branch");
1492
+ // Best-effort: the gate reads CI, not the local ref; a failed fetch is logged, not fatal.
1493
+ const fetched = fetchRemoteRef(ctx.cwd, `origin/${branch}`);
1494
+ if (fetched !== null && !fetched.ok)
1495
+ ctx.log(`fetch of origin/${branch} failed: ${fetched.stderr.trim()}`);
1496
+ }
1403
1497
  const root = checkoutRoot(ctx.cwd);
1404
1498
  const gh: Gh = (args) => runGh(ctx.cwd, args);
1405
1499
  const record = str(f.record);
@@ -1550,14 +1644,6 @@ function runGate(ctx: RunContext): number {
1550
1644
  // revalidate
1551
1645
  // ---------------------------------------------------------------------------
1552
1646
 
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
1647
  async function runRevalidate(ctx: RunContext): Promise<number> {
1562
1648
  const f = ctx.flags;
1563
1649
  const repoFlag = str(f.repo);
@@ -1718,25 +1804,31 @@ async function runContext(ctx: RunContext): Promise<number> {
1718
1804
  prState: null,
1719
1805
  runId: null,
1720
1806
  };
1807
+ const tracker = readIssueTracker(ctx.cwd);
1721
1808
  if (chosen.mode === "BRIEF") {
1722
- ctx.emit({ ...out, issueId: arg });
1809
+ ctx.emit(await withIssue(ctx, { ...out, issueId: arg }, tracker));
1723
1810
  return EXIT.OK;
1724
1811
  }
1725
- const tracker = readIssueTracker(ctx.cwd);
1726
1812
  if (!/^[0-9]+$/.test(arg)) {
1727
1813
  // CI_DEV: a post-merge dev failure names the FID slug; checked before any path sees it.
1728
1814
  if (!FID_PATTERNS.any.test(arg)) {
1729
1815
  ctx.log(`Invalid CI_DEV FID: ${arg}`);
1730
1816
  return EXIT_NO_FID;
1731
1817
  }
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
- });
1818
+ ctx.emit(
1819
+ await withIssue(
1820
+ ctx,
1821
+ {
1822
+ ...out,
1823
+ mode: "CI_DEV",
1824
+ fid: arg,
1825
+ issueId: tracker === "none" ? null : issueIdOf(arg, "any"),
1826
+ branch: DEV,
1827
+ headSha: git(ctx.cwd, ["rev-parse", "origin/dev"]) ?? "",
1828
+ },
1829
+ tracker,
1830
+ ),
1831
+ );
1740
1832
  return EXIT.OK;
1741
1833
  }
1742
1834
  const view = runGh(ctx.cwd, [
@@ -1801,10 +1893,35 @@ async function runContext(ctx: RunContext): Promise<number> {
1801
1893
  ctx.emit(out);
1802
1894
  return EXIT_NO_FID;
1803
1895
  }
1804
- ctx.emit({ ...out, fid: parsed.fid, issueId: parsed.issueId });
1896
+ if (parsed.issueId === null && tracker !== "none") {
1897
+ ctx.log(`FID ${parsed.fid} names no issue; /bkit-auto runs from an issue only`);
1898
+ ctx.emit(out);
1899
+ return EXIT_NO_FID;
1900
+ }
1901
+ ctx.emit(await withIssue(ctx, { ...out, fid: parsed.fid, issueId: parsed.issueId }, tracker));
1805
1902
  return EXIT.OK;
1806
1903
  }
1807
1904
 
1905
+ /**
1906
+ * `ref` (the issue as a workflow argument: `#N` on GitHub, the key uppercased on
1907
+ * Linear / Jira) and `labels` (read from the tracker; null when there is no issue
1908
+ * or the read failed, logged).
1909
+ */
1910
+ async function withIssue(
1911
+ ctx: RunContext,
1912
+ out: Record<string, unknown>,
1913
+ tracker: IssueTracker,
1914
+ ): Promise<Record<string, unknown>> {
1915
+ const id = typeof out.issueId === "string" && out.issueId !== "" ? out.issueId : null;
1916
+ const ref = issueRef(id, tracker);
1917
+ if (id === null || tracker === "none") return { ...out, ref, labels: null };
1918
+ let labels: string[] | null = null;
1919
+ const read = await attempt("labels", ctx.log, async () => {
1920
+ labels = await readLabels(trackerTarget(ctx.cwd, { issue: id }));
1921
+ });
1922
+ return { ...out, ref, labels: "done" in read && read.done ? labels : null };
1923
+ }
1924
+
1808
1925
  async function runMirror(ctx: RunContext): Promise<number> {
1809
1926
  const f = ctx.flags;
1810
1927
  const head = String(f.head);
@@ -1890,12 +2007,17 @@ export const runsCommand: CommandSpec = {
1890
2007
  },
1891
2008
  dispatch: {
1892
2009
  summary:
1893
- "CI-Dispatch Gate after the last push: poll, one clean re-trigger, the ciDispatch verdict, and the body scan.",
2010
+ "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.",
1894
2011
  flags: [
1895
2012
  {
1896
2013
  name: "pr",
1897
2014
  type: "string",
1898
- help: "PR number (default: the open PR from this branch into dev)",
2015
+ 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)",
2016
+ },
2017
+ {
2018
+ name: "sha",
2019
+ type: "string",
2020
+ 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
2021
  },
1900
2022
  {
1901
2023
  name: "fid",
@@ -1951,8 +2073,8 @@ export const runsCommand: CommandSpec = {
1951
2073
  ciDispatch:
1952
2074
  "{outcome, head, attempts, retrigger, reason?} — record with `bkit steps done --field ciDispatch=…` (local only, never pushed); null on a hand-off",
1953
2075
  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)",
2076
+ pr: "PR number polled (null when none was found, or a run in place on dev, whose run is read at head)",
2077
+ 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
2078
  attempts: "poll attempts so far",
1957
2079
  retrigger: "a re-trigger commit was pushed",
1958
2080
  scanResult:
@@ -2006,6 +2128,11 @@ export const runsCommand: CommandSpec = {
2006
2128
  type: "string",
2007
2129
  help: "PR branch: tells a superseded head (14) from no run (10)",
2008
2130
  },
2131
+ {
2132
+ name: "fetch",
2133
+ type: "boolean",
2134
+ help: "fetch origin/<--branch> first (best-effort, logged on failure)",
2135
+ },
2009
2136
  {
2010
2137
  name: "event",
2011
2138
  type: "string",
@@ -2169,6 +2296,9 @@ export const runsCommand: CommandSpec = {
2169
2296
  owner: "owner half",
2170
2297
  repo: "repo half",
2171
2298
  issueId: "the issue (BRIEF: the arg; CI: from the marker or branch; null under no tracker)",
2299
+ ref: 'the issue as the phase workflow\'s argument: #N (GitHub), the key uppercased (Linear / Jira), else issueId verbatim or ""',
2300
+ labels:
2301
+ "the issue's labels read from the tracker; null with no issue or when the read failed (read them via the tracker MCP)",
2172
2302
  fid: "the FID (CI / CI_DEV), else null",
2173
2303
  prNumber: "the PR (CI), else null",
2174
2304
  branch: "the PR head branch (CI), dev (CI_DEV), else null",
@@ -2182,13 +2312,13 @@ export const runsCommand: CommandSpec = {
2182
2312
  [EXIT_PR_NOT_OPEN]: "the PR is not OPEN",
2183
2313
  [EXIT_NO_RUN_ID]: "no CI run at the PR head",
2184
2314
  [EXIT_NO_FID]:
2185
- "no valid FID (CI_DEV slug off the allowlist, or no marker / feat/{FID} branch)",
2315
+ "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
2316
  },
2187
2317
  run: runContext,
2188
2318
  },
2189
2319
  declared: {
2190
2320
  summary:
2191
- "Whether the repo declares a CI workflow: .github/workflows/<bkit.ciWorkflow> exists (exit 0) or not (exit 1).",
2321
+ "Whether the repo declares a CI workflow: .github/workflows/<bkit.testing.ciWorkflow> exists (exit 0) or not (exit 1).",
2192
2322
  flags: [],
2193
2323
  output: {
2194
2324
  declared: "the workflow file exists",
@@ -25,7 +25,15 @@ import * as fs from "node:fs";
25
25
  import * as path from "node:path";
26
26
 
27
27
  import { statusTimestamp } from "../../ledgers/status.js";
28
- import { CommandError, EXIT, repoRoot, runTool, type CommandSpec, type FlagSpec } from "../lib.js";
28
+ import {
29
+ CommandError,
30
+ EXIT,
31
+ git,
32
+ repoRoot,
33
+ runTool,
34
+ type CommandSpec,
35
+ type FlagSpec,
36
+ } from "../lib.js";
29
37
  import {
30
38
  EXIT_NO_STATUS,
31
39
  FILE_FLAG,
@@ -116,6 +124,19 @@ const capable = (runtime: Runtime) =>
116
124
  /** No human can reply into the session: a GitHub Actions run. */
117
125
  const headless = (runtime: unknown) => runtime === "GITHUB_ACTION";
118
126
 
127
+ /**
128
+ * `classify` for a process working in `cwd`, which may be a build worktree: the Cursor
129
+ * marker sits in the main checkout (`repoRoot`), as `runtime detect` reads it. Outside a
130
+ * git repo the marker is looked for under `cwd`.
131
+ */
132
+ export function classifyAt(cwd: string): Runtime {
133
+ const common = git(cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
134
+ return classify(process.env, common ? path.dirname(common) : cwd, () => undefined);
135
+ }
136
+
137
+ /** Whether a process working in `cwd` runs headless, classified like `runtime detect`. */
138
+ export const headlessRun = (cwd: string): boolean => headless(classifyAt(cwd));
139
+
119
140
  /** The full table: classification, default capabilities, and the one live gh probe. */
120
141
  export function detect(cwd: string, root: string, log: (m: string) => void): RuntimeTable {
121
142
  const runtime = classify(process.env, root, log);