@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
@@ -1,15 +1,19 @@
1
- // bkit status route|meta|path|row — read and annotate a workflow's `status.jsonl`.
1
+ // bkit status route|resume|meta|path|row — read and annotate a workflow's `status.jsonl`.
2
2
 
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
 
6
+ import { BKIT_DEBUG_GATES } from "../../install/manifest.js";
7
+ import { readBkitConfig } from "../../shared/settings.js";
6
8
  import {
7
9
  activeDoneSteps,
10
+ allRunsDoneSteps,
8
11
  appendLine,
9
12
  fold,
10
13
  lastDoneStepAllRuns,
11
14
  lastRun,
12
15
  nextStrategy,
16
+ runNumber,
13
17
  runOrStepField,
14
18
  statusTimestamp,
15
19
  type StatusEvent,
@@ -27,6 +31,7 @@ import {
27
31
  type FlagValue,
28
32
  type RunContext,
29
33
  } from "../lib.js";
34
+ import { WORKFLOW_STEPS, isResumable, resumePoint } from "./step-table.js";
30
35
 
31
36
  // ---------------------------------------------------------------------------
32
37
  // Shared with counters / steps
@@ -50,10 +55,10 @@ export const STEP_FLAG: FlagSpec = {
50
55
  required: true,
51
56
  help: "step name",
52
57
  };
53
- export const SUB_PLAN_FLAG: FlagSpec = {
54
- name: "sub-plan",
58
+ export const GROUP_FLAG: FlagSpec = {
59
+ name: "group",
55
60
  type: "string",
56
- help: "only rows for this sub-plan (positive integer)",
61
+ help: "only rows for this plan group (positive integer)",
57
62
  };
58
63
 
59
64
  /** Exit code: status.jsonl missing, unreadable, or not valid NDJSON. */
@@ -166,7 +171,7 @@ type RouteField = (typeof ROUTE_FIELDS)[number];
166
171
  /** Exit code: a `--require`d field is missing or holds a value outside its set. */
167
172
  export const EXIT_ROUTE_MISSING = 4;
168
173
 
169
- function route(runs: WorkflowRun[], workflow: string, step: string | undefined, subPlan?: number) {
174
+ function route(runs: WorkflowRun[], workflow: string, step: string | undefined, group?: number) {
170
175
  const out: Record<string, unknown> = {
171
176
  verdict: null,
172
177
  failures: null,
@@ -175,11 +180,13 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
175
180
  debugMode: null,
176
181
  pushMode: null,
177
182
  debugAttempt: 0,
183
+ parentSha: null,
178
184
  };
179
185
  const problems: Partial<Record<RouteField, string>> = {};
180
186
 
181
187
  if (step !== undefined) {
182
- const last = activeDoneSteps(runs, workflow, { step, subPlan }).at(-1);
188
+ const last = activeDoneSteps(runs, workflow, { step, group }).at(-1);
189
+ if (typeof last?.parentSha === "string") out.parentSha = last.parentSha;
183
190
  if (!last) {
184
191
  problems.verdict = `no DONE ${step} row in the active ${workflow} run`;
185
192
  problems.failures = problems.verdict;
@@ -188,13 +195,15 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
188
195
  problems.failures = problems.verdict;
189
196
  } else {
190
197
  out.verdict = last.verdict;
191
- const failures = last.failures ?? 0;
192
- if (Number.isInteger(failures) && failures >= 0) out.failures = failures;
198
+ // An absent count on FAIL is unknown, never 0: a FAIL always has failures.
199
+ const failures = last.failures ?? (last.verdict === "FAIL" ? null : 0);
200
+ if (failures === null) out.failures = null;
201
+ else if (Number.isInteger(failures) && failures >= 0) out.failures = failures;
193
202
  else
194
203
  problems.failures = `${step} failures "${String(failures)}" is not a non-negative integer`;
195
204
  }
196
205
 
197
- const prior = lastDoneStepAllRuns(runs, workflow, { step, subPlan })?.strategy;
206
+ const prior = lastDoneStepAllRuns(runs, workflow, { step, group })?.strategy;
198
207
  if (prior === undefined || STRATEGIES.includes(prior)) {
199
208
  out.strategy = prior ?? null;
200
209
  out.nextStrategy = nextStrategy(prior);
@@ -219,6 +228,44 @@ function route(runs: WorkflowRun[], workflow: string, step: string | undefined,
219
228
  return { out, problems };
220
229
  }
221
230
 
231
+ /**
232
+ * The debug run's start decisions, from the session prompt and the feature's debug runs.
233
+ * `fixMax` is `bkit.workflows.debug.fix.maxAttempts`: once that many fix rounds ran across
234
+ * every debug run, the run starts in SOAK.
235
+ */
236
+ export function debugStart(runs: WorkflowRun[], promptText: string, fixMax: number) {
237
+ const attempt = runNumber(runs, "debug");
238
+ const latest = runs.at(-1);
239
+ // A resume: the newest run is debug's and still open. A finished run's modes never
240
+ // carry into the next run; its fix rounds count against `fixMax`.
241
+ const open = latest?.workflow === "debug" && latest.status === "IN_PROGRESS" ? latest : null;
242
+ const soaking =
243
+ open !== null &&
244
+ (runOrStepField([open], "debug", "debugMode") === "SOAK" ||
245
+ open.steps.some((s) => s.step === "debug-failure-soak" && s.status === "DONE"));
246
+ const fixes = allRunsDoneSteps(runs, "debug", { step: "debug-failure-remediate" }).length;
247
+ const debugMode = promptText.includes("[soak]") || soaking || fixes >= fixMax ? "SOAK" : "NORMAL";
248
+ return {
249
+ debugAttempt: attempt,
250
+ debugMode,
251
+ repro: promptText.includes("[repro]"),
252
+ gates: promptText.includes("[live=off]")
253
+ ? BKIT_DEBUG_GATES.filter((g) => !g.endsWith("-live"))
254
+ : [...BKIT_DEBUG_GATES],
255
+ };
256
+ }
257
+
258
+ /** `--file`, else the debug status.jsonl `--fid` and `--month` name. */
259
+ function routeFile(ctx: RunContext): string {
260
+ if (ctx.flags.file !== undefined) return statusFile(ctx);
261
+ const fid = str(ctx.flags.fid);
262
+ const month = str(ctx.flags.month);
263
+ if (fid === undefined || month === undefined || ctx.flags.promptFile === undefined)
264
+ throw new CommandError(EXIT.USAGE, "give --file, or --prompt-file with --fid and --month");
265
+ if (!/^[0-9]{6}$/.test(month)) throw new CommandError(EXIT.USAGE, "--month must be YYYYMM");
266
+ return statusLocation({ cwd: ctx.cwd, workflow: "debug", fid, month }).path;
267
+ }
268
+
222
269
  // ---------------------------------------------------------------------------
223
270
  // meta
224
271
  // ---------------------------------------------------------------------------
@@ -227,7 +274,6 @@ const META_FIELDS: Record<string, { key: string; check: (v: string) => unknown }
227
274
  "debug-mode": { key: "debugMode", check: (v) => oneOf(v, DEBUG_MODES, "--debug-mode") },
228
275
  "push-mode": { key: "pushMode", check: (v) => oneOf(v, PUSH_MODES, "--push-mode") },
229
276
  "debug-attempt": { key: "debugAttempt", check: (v) => positiveInt(v, "debug-attempt") },
230
- "plan-source": { key: "planSource", check: (v) => oneOf(v, PLAN_SOURCES, "--plan-source") },
231
277
  };
232
278
 
233
279
  /** Row types the fold reads; each has its own verb (workflows start|fail|close, steps done, status meta). */
@@ -239,15 +285,11 @@ const FOLDED_TYPES = new Set([
239
285
  "workflow-failed",
240
286
  ]);
241
287
 
242
- /** Markers that record the row's own time or a fact, not a value. */
288
+ /** Markers that record a fact, not a value. */
243
289
  const META_MARKS: Record<string, (at: string) => Record<string, unknown>> = {
244
- "soak-entry": (at) => ({ soakEntryAt: at }),
245
290
  "opened-pr": () => ({ openedPr: true }),
246
291
  };
247
292
 
248
- /** `brief` = the run had no plan file and works from its input file. */
249
- const PLAN_SOURCES = ["brief", "plan"];
250
-
251
293
  const camelFlag = (kebab: string) => kebab.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
252
294
 
253
295
  function oneOf(v: string, allowed: string[], flag: string): string {
@@ -290,16 +332,17 @@ export const statusCommand: CommandSpec = {
290
332
  },
291
333
  },
292
334
  route: {
293
- summary: "Routing state: last verdict / failures / strategy of a step, debug and push mode.",
335
+ summary:
336
+ "Routing state: last verdict / failures / strategy of a step, debug and push mode; with --prompt-file, debug's start decisions.",
294
337
  flags: [
295
- FILE_FLAG,
338
+ { ...FILE_FLAG, required: false, help: `${FILE_FLAG.help}; or --fid and --month` },
296
339
  WORKFLOW_FLAG,
297
340
  {
298
341
  ...STEP_FLAG,
299
342
  required: false,
300
343
  help: "step whose last DONE row gives verdict, failures, strategy",
301
344
  },
302
- SUB_PLAN_FLAG,
345
+ GROUP_FLAG,
303
346
  {
304
347
  name: "require",
305
348
  type: "string",
@@ -312,15 +355,30 @@ export const statusCommand: CommandSpec = {
312
355
  repeatable: true,
313
356
  help: "field=value — fail (exit 4) unless the field holds this value, e.g. debugMode=NORMAL",
314
357
  },
358
+ {
359
+ name: "prompt-file",
360
+ type: "string",
361
+ help: "debug only: the session prompt; decides this run's attempt, mode, repro and gates (a missing status.jsonl is a fresh run)",
362
+ },
363
+ { name: "fid", type: "string", help: "with --prompt-file, in place of --file: feature id" },
364
+ { name: "month", type: "string", help: "with --prompt-file, in place of --file: YYYYMM" },
315
365
  ],
316
366
  output: {
317
367
  verdict: "PASS|CONCERNS|FAIL of the step's last DONE row in the active run, or null",
318
- failures: "its failures (absent with a verdict = 0), or null",
368
+ failures:
369
+ "its failures (absent on PASS|CONCERNS = 0, absent on FAIL = null: count unknown), or null",
319
370
  strategy: "the step's last strategy across ALL runs, or null",
320
371
  nextStrategy: "next rung: STANDARD, PIVOT, FINAL (null without --step)",
321
- debugMode: "NORMAL|SOAK of the active run, or null",
372
+ debugMode:
373
+ "NORMAL|SOAK of the active run, or null; with --prompt-file, the mode this invocation runs in (SOAK on [soak] in the prompt, an open run already in SOAK, or bkit.workflows.debug.fix.maxAttempts fix rounds already run across every debug run; else NORMAL)",
322
374
  pushMode: "PR|LOCAL of the active run, or null",
323
- debugAttempt: "debugAttempt of the active run (0 when unset)",
375
+ debugAttempt:
376
+ "debugAttempt of the active run (0 when unset); with --prompt-file, this invocation's run number (a resume keeps its number)",
377
+ repro: "with --prompt-file: [repro] in the prompt",
378
+ gates:
379
+ "with --prompt-file: the gates to try, deepest first; [live=off] in the prompt drops the live gate",
380
+ parentSha:
381
+ "HEAD when the step's last DONE row in the active run was written — a build-group-start row's is the group's start commit, the base for `context diff` — or null",
324
382
  },
325
383
  exitCodes: {
326
384
  [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON",
@@ -355,13 +413,30 @@ export const statusCommand: CommandSpec = {
355
413
  throw new CommandError(EXIT.USAGE, `--require ${r} needs --step`);
356
414
  }
357
415
  }
358
- const runs = readRuns(statusFile(ctx));
416
+ const promptFile = str(ctx.flags.promptFile);
417
+ if (promptFile !== undefined && ctx.flags.workflow !== "debug")
418
+ throw new CommandError(EXIT.USAGE, "--prompt-file is for --workflow=debug");
419
+ const file = routeFile(ctx);
420
+ let promptText = "";
421
+ if (promptFile !== undefined) {
422
+ const abs = path.resolve(ctx.cwd, promptFile);
423
+ if (!fs.existsSync(abs))
424
+ throw new CommandError(EXIT.USAGE, `--prompt-file ${abs} does not exist`);
425
+ promptText = fs.readFileSync(abs, "utf-8");
426
+ }
427
+ const runs = promptFile !== undefined && !fs.existsSync(file) ? [] : readRuns(file);
359
428
  const { out, problems } = route(
360
429
  runs,
361
430
  String(ctx.flags.workflow),
362
431
  step,
363
- positiveInt(ctx.flags.subPlan, "sub-plan"),
432
+ positiveInt(ctx.flags.group, "group"),
364
433
  );
434
+ if (promptFile !== undefined) {
435
+ const root = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
436
+ const fixMax = readBkitConfig(root).asks["debug.fix"].max;
437
+ Object.assign(out, debugStart(runs, promptText, fixMax));
438
+ delete problems.debugMode;
439
+ }
365
440
  ctx.emit(out);
366
441
  const failed = required.filter((r) => problems[r as RouteField] !== undefined);
367
442
  for (const r of failed) ctx.log(problems[r as RouteField]!);
@@ -375,6 +450,42 @@ export const statusCommand: CommandSpec = {
375
450
  return failed.length === 0 && differ.length === 0 ? EXIT.OK : EXIT_ROUTE_MISSING;
376
451
  },
377
452
  },
453
+ resume: {
454
+ summary:
455
+ "The step a stopped run continues at: after its last DONE step, setup steps and retired rows aside.",
456
+ flags: [
457
+ { ...FILE_FLAG, help: "path to status.jsonl; a missing file is a run with no rows" },
458
+ { ...WORKFLOW_FLAG, help: `workflow name: ${Object.keys(WORKFLOW_STEPS).join(", ")}` },
459
+ ],
460
+ output: {
461
+ step: "the step's row name, or null for a step that writes no row",
462
+ number: "the step number to continue at (1 when no run is active)",
463
+ title: "the step heading's title",
464
+ after: "the DONE row that placed it, or null",
465
+ group: "that row's plan group, or null",
466
+ active: "whether the latest run is this workflow, still IN_PROGRESS",
467
+ challengeRound:
468
+ "build: the round Step 10's challenge runs as (1 up to bkit.workflows.build.challenge.maxAttempts), from the build-challenge rows' round field; null for other workflows",
469
+ challengeDone:
470
+ "build: true once the last allowed challenge round has merged, so Step 10 goes on to Step 11; null for other workflows",
471
+ },
472
+ exitCodes: { [EXIT_NO_STATUS]: "status.jsonl unreadable or not valid NDJSON" },
473
+ run: (ctx) => {
474
+ const workflow = String(ctx.flags.workflow);
475
+ if (!isResumable(workflow))
476
+ throw new CommandError(
477
+ EXIT.USAGE,
478
+ `--workflow must be ${Object.keys(WORKFLOW_STEPS).join("|")}, got "${workflow}"`,
479
+ );
480
+ const file = statusFile(ctx);
481
+ const root = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
482
+ const challengeMax = readBkitConfig(root).asks["build.challenge"].max;
483
+ ctx.emit({
484
+ ...resumePoint(fs.existsSync(file) ? readRuns(file) : [], workflow, challengeMax),
485
+ });
486
+ return EXIT.OK;
487
+ },
488
+ },
378
489
  meta: {
379
490
  summary: "Append a workflow-meta row (run-level routing state).",
380
491
  flags: [
@@ -382,12 +493,10 @@ export const statusCommand: CommandSpec = {
382
493
  WORKFLOW_FLAG,
383
494
  { name: "debug-mode", type: "string", help: "NORMAL|SOAK" },
384
495
  { name: "push-mode", type: "string", help: "PR|LOCAL" },
385
- { name: "debug-attempt", type: "string", help: "positive integer" },
386
- { name: "plan-source", type: "string", help: "brief|plan" },
387
496
  {
388
- name: "soak-entry",
389
- type: "boolean",
390
- help: "record soakEntryAt (the soak budget counts from here)",
497
+ name: "debug-attempt",
498
+ type: "string",
499
+ help: "positive integer, or run (the active run's number)",
391
500
  },
392
501
  { name: "opened-pr", type: "boolean", help: "record openedPr: this run opened the PR" },
393
502
  ],
@@ -399,7 +508,8 @@ export const statusCommand: CommandSpec = {
399
508
  const fields: Record<string, unknown> = {};
400
509
  for (const { key, check } of Object.values(META_FIELDS)) {
401
510
  const v = str(ctx.flags[key]);
402
- if (v !== undefined) fields[key] = check(v);
511
+ // `--debug-attempt=run`: the active run's number, read once the log is known to exist.
512
+ if (v !== undefined) fields[key] = key === "debugAttempt" && v === "run" ? v : check(v);
403
513
  }
404
514
  for (const [flag, mark] of Object.entries(META_MARKS)) {
405
515
  if (ctx.flags[camelFlag(flag)] === true) Object.assign(fields, mark(at));
@@ -413,6 +523,9 @@ export const statusCommand: CommandSpec = {
413
523
  );
414
524
  }
415
525
  if (!fs.existsSync(file)) throw new CommandError(EXIT_NO_STATUS, `${file} does not exist`);
526
+ if (fields.debugAttempt === "run") {
527
+ fields.debugAttempt = runNumber(readRuns(file), String(ctx.flags.workflow));
528
+ }
416
529
  const row = {
417
530
  type: "workflow-meta" as const,
418
531
  workflow: String(ctx.flags.workflow),
@@ -0,0 +1,339 @@
1
+ // The ordered steps of each workflow, and where a stopped run resumes.
2
+ //
3
+ // `bkit status resume` folds the active run and names the step to continue at.
4
+ // The rule: take the run's last DONE row for a step this table knows (rows for
5
+ // steps a workflow no longer has are ignored, except the retired steps mapped
6
+ // below, and Decision Pause rows that record their route), skip the setup steps
7
+ // (1-2 run again on every resume), and resume at the
8
+ // step after it — or at its `resumeOnVerdict` entry for the row's verdict, or its
9
+ // `resumeAt`, for a step whose next step depends on a verdict or that loops back. `workflow-shape.test.ts` holds this table to the
10
+ // workflows' `## Step N — Title` headings and `--step=` calls.
11
+
12
+ import type { WorkflowRun } from "../../ledgers/status.js";
13
+ import { CONFIG_DEFAULTS } from "../../shared/settings.js";
14
+
15
+ /** One row-writing step of a workflow, or a numbered step that writes no row (`step` absent). */
16
+ export interface WorkflowStep {
17
+ /** The `--step=` its status row carries. */
18
+ step?: string;
19
+ number: number;
20
+ /** The step heading's title, after `Step N — `. */
21
+ title: string;
22
+ /** Steps 1-2: run again on every resume, so their rows place no resume point. */
23
+ setup?: true;
24
+ /** The step a run whose last DONE row is this one resumes at, when not the next step. */
25
+ resumeAt?: string;
26
+ /** The step a run resumes at when this DONE row's `verdict` is a key here, before `resumeAt`. */
27
+ resumeOnVerdict?: Readonly<Record<string, string>>;
28
+ }
29
+
30
+ export type ResumableWorkflow = "plan" | "design" | "build" | "debug" | "ship";
31
+
32
+ export const WORKFLOW_STEPS: Readonly<Record<ResumableWorkflow, readonly WorkflowStep[]>> = {
33
+ plan: [
34
+ { step: "plan-start-workflow", number: 1, title: "Start Workflow", setup: true },
35
+ { step: "plan-worktree-setup", number: 2, title: "Worktree Setup", setup: true },
36
+ { step: "plan-generate", number: 3, title: "Generate Plan" },
37
+ { step: "plan-fetch-context", number: 4, title: "Fetch Context" },
38
+ { step: "plan-review", number: 5, title: "Review Plan" },
39
+ { step: "plan-apply-review", number: 6, title: "Apply Review" },
40
+ { step: "plan-summary", number: 7, title: "Summary" },
41
+ { step: "plan-close-workflow", number: 8, title: "Close Workflow" },
42
+ ],
43
+ design: [
44
+ { step: "design-start-workflow", number: 1, title: "Start Workflow", setup: true },
45
+ { step: "design-worktree-setup", number: 2, title: "Worktree Setup", setup: true },
46
+ { step: "design-grill", number: 3, title: "Grill" },
47
+ { step: "design-brainstorm-ideate", number: 4, title: "Brainstorm & Ideate" },
48
+ { step: "design-generate", number: 5, title: "Generate Design" },
49
+ { step: "design-review", number: 6, title: "Design Review" },
50
+ { step: "design-spike", number: 7, title: "Spike" },
51
+ { step: "design-apply-review", number: 8, title: "Apply Review" },
52
+ { step: "design-organise", number: 9, title: "Design Organise" },
53
+ { step: "design-summary", number: 10, title: "Summary" },
54
+ { step: "design-workstream-suggest", number: 11, title: "Suggest Workstreams" },
55
+ { step: "design-close-workflow", number: 12, title: "Close Workflow" },
56
+ ],
57
+ build: [
58
+ { step: "build-start-workflow", number: 1, title: "Start Workflow", setup: true },
59
+ { step: "build-worktree-setup", number: 2, title: "Worktree Setup", setup: true },
60
+ // A converted plan is checked again: Step 3 runs its plan check once more.
61
+ { step: "build-plan-convert", number: 3, title: "Branch Sync", resumeAt: "build-branch-sync" },
62
+ { step: "build-branch-sync", number: 3, title: "Branch Sync" },
63
+ { step: "build-plan-current", number: 4, title: "Plan Current" },
64
+ { step: "build-install-skills", number: 5, title: "Install Skills" },
65
+ // A group's start commit is recorded before its execute runs: Step 6 again.
66
+ {
67
+ step: "build-group-start",
68
+ number: 6,
69
+ title: "Plan Execute",
70
+ resumeAt: "build-plan-execute",
71
+ },
72
+ // A handover stops a group part-done: Step 6 runs again with a fresh brief.
73
+ {
74
+ step: "build-plan-execute",
75
+ number: 6,
76
+ title: "Plan Execute",
77
+ resumeOnVerdict: { HANDOVER: "build-plan-execute" },
78
+ },
79
+ // Verify, its group gate and the gaps fix route on the verify verdict: Step 7 again.
80
+ { step: "build-plan-verify", number: 7, title: "Plan Verify", resumeAt: "build-plan-verify" },
81
+ { step: "build-group-gate", number: 7, title: "Plan Verify", resumeAt: "build-plan-verify" },
82
+ {
83
+ step: "build-plan-gaps-remediate",
84
+ number: 8,
85
+ title: "Plan Gaps Remediate",
86
+ resumeAt: "build-plan-verify",
87
+ },
88
+ { step: "build-plan-verify-holistic", number: 9, title: "Plan Verify Holistic" },
89
+ // The reports are written: Step 10 continues at `bkit challenge merge`.
90
+ { step: "build-challenge", number: 10, title: "Build Challenge", resumeAt: "build-challenge" },
91
+ // Run Tests routes on its own verdict, and a fix loops back to it.
92
+ { step: "build-run-tests", number: 11, title: "Run Tests", resumeAt: "build-run-tests" },
93
+ { step: "build-failure-diagnose", number: 12, title: "Failure Diagnose" },
94
+ {
95
+ step: "build-failure-remediate",
96
+ number: 13,
97
+ title: "Failure Remediate",
98
+ resumeAt: "build-run-tests",
99
+ },
100
+ { step: "build-summary", number: 14, title: "Summary" },
101
+ { step: "build-create-pr", number: 15, title: "Close Workflow & Create PR" },
102
+ { step: "build-close-workflow", number: 15, title: "Close Workflow & Create PR" },
103
+ ],
104
+ debug: [
105
+ { step: "debug-start-workflow", number: 1, title: "Start Workflow", setup: true },
106
+ { step: "debug-worktree-setup", number: 2, title: "Worktree Setup", setup: true },
107
+ // Run Tests routes on its own verdict, and every fix loops back to it.
108
+ { step: "debug-run-tests", number: 3, title: "Run Tests", resumeAt: "debug-run-tests" },
109
+ { step: "context-fetch", number: 4, title: "Fetch Context" },
110
+ { step: "debug-failure-reproduce", number: 5, title: "Failure Reproduce" },
111
+ { step: "debug-failure-diagnose", number: 6, title: "Failure Diagnose" },
112
+ {
113
+ step: "debug-failure-remediate",
114
+ number: 7,
115
+ title: "Failure Remediate",
116
+ resumeAt: "debug-run-tests",
117
+ },
118
+ {
119
+ step: "debug-failure-soak",
120
+ number: 8,
121
+ title: "Failure Remediate Soak",
122
+ resumeAt: "debug-run-tests",
123
+ },
124
+ { step: "debug-push-remediation", number: 9, title: "Push Remediation" },
125
+ { step: "debug-summary", number: 10, title: "Summary" },
126
+ { step: "debug-create-pr", number: 11, title: "Close Workflow" },
127
+ { step: "debug-close-workflow", number: 11, title: "Close Workflow" },
128
+ ],
129
+ ship: [
130
+ { step: "ship-start-workflow", number: 1, title: "Start Workflow", setup: true },
131
+ {
132
+ step: "ship-worktree-setup",
133
+ number: 2,
134
+ title: "Verify PR (Worktree Setup + Regression Guard)",
135
+ setup: true,
136
+ },
137
+ {
138
+ step: "ship-regression-guard",
139
+ number: 2,
140
+ title: "Verify PR (Worktree Setup + Regression Guard)",
141
+ setup: true,
142
+ },
143
+ { number: 3, title: "Base Check" },
144
+ { step: "ship-conflict-resolve", number: 4, title: "Integrate (Path B only)" },
145
+ { step: "ship-deferred-sweep", number: 5, title: "Deferred Sweep" },
146
+ // Docs and summary are one step: the summary half still has to run.
147
+ {
148
+ step: "ship-update-docs",
149
+ number: 6,
150
+ title: "Update Docs & Summary",
151
+ resumeAt: "ship-summary",
152
+ },
153
+ { step: "ship-summary", number: 6, title: "Update Docs & Summary" },
154
+ { step: "ship-prune-skills", number: 7, title: "Prune Skills" },
155
+ { step: "ship-bookkeeping-push", number: 8, title: "Commit + Push Bookkeeping" },
156
+ { number: 9, title: "Re-validate" },
157
+ // The merge gate reads the PR state again: a merged PR goes on to Step 13.
158
+ {
159
+ step: "ship-merge-pr",
160
+ number: 10,
161
+ title: "Merge Gate + Merge PR",
162
+ resumeAt: "ship-merge-pr",
163
+ },
164
+ { step: "ship-failure-diagnose", number: 11, title: "Failure Diagnose" },
165
+ // A PASS fix is committed and pushed at Step 12 sub-step 4 (a re-run commits nothing
166
+ // new), then re-validated at Step 9; any other verdict re-reads the PR at Step 10.
167
+ {
168
+ step: "ship-failure-remediate",
169
+ number: 12,
170
+ title: "Failure Remediate",
171
+ resumeAt: "ship-merge-pr",
172
+ resumeOnVerdict: { PASS: "ship-failure-remediate" },
173
+ },
174
+ { step: "ship-switch-to-dev", number: 13, title: "Update Local Dev" },
175
+ { step: "ship-close-workflow", number: 14, title: "Close Workflow" },
176
+ ],
177
+ };
178
+
179
+ /**
180
+ * Rows of steps a workflow no longer has that still place a resume point: the
181
+ * old build challenge steps ran after the reports, so a run stopped in them
182
+ * resumes at Run Tests.
183
+ */
184
+ export const RETIRED_STEPS: Readonly<Partial<Record<ResumableWorkflow, Record<string, string>>>> = {
185
+ build: {
186
+ "build-challenge-reconcile": "build-run-tests",
187
+ "build-challenge-remediate": "build-run-tests",
188
+ "build-challenge-tests": "build-run-tests",
189
+ },
190
+ };
191
+
192
+ /**
193
+ * Decision Pause rows (`build-decision`, no step number) that place a resume point: the
194
+ * row's `route` names the step the decision sent the run to, either directly or keyed on
195
+ * the step of the last non-decision row before it (the loop the pause came from). A row
196
+ * without a known `route`, or a keyed route with no matching prior row, places none.
197
+ */
198
+ export const DECISION_ROUTES: Readonly<
199
+ Partial<
200
+ Record<
201
+ ResumableWorkflow,
202
+ { step: string; routes: Record<string, string | Readonly<Record<string, string>>> }
203
+ >
204
+ >
205
+ > = {
206
+ build: {
207
+ step: "build-decision",
208
+ routes: {
209
+ fix: "build-plan-execute",
210
+ verify: "build-plan-verify",
211
+ tests: "build-run-tests",
212
+ // Try again: a verify loop goes on to its gaps fix (Step 8), a tests loop to Step 12.
213
+ retry: {
214
+ "build-plan-verify": "build-plan-gaps-remediate",
215
+ "build-group-gate": "build-plan-gaps-remediate",
216
+ "build-run-tests": "build-failure-diagnose",
217
+ },
218
+ },
219
+ },
220
+ };
221
+
222
+ export const isResumable = (w: string): w is ResumableWorkflow => w in WORKFLOW_STEPS;
223
+
224
+ export interface ResumePoint {
225
+ /** The step to continue at: its row name (null for a step that writes no row), number and title. */
226
+ step: string | null;
227
+ number: number;
228
+ title: string;
229
+ /** The DONE row that placed the point, or null when none did (resume at Step 1). */
230
+ after: string | null;
231
+ /** That row's plan group, or null. */
232
+ group: number | null;
233
+ /** Whether the latest run is this workflow, still IN_PROGRESS. */
234
+ active: boolean;
235
+ /** Build only (null otherwise): the round Step 10's challenge runs as — see `challengeRound`. */
236
+ challengeRound: number | null;
237
+ /** Build only (null otherwise): the last allowed round has merged, so Step 10 goes on to Step 11. */
238
+ challengeDone: boolean | null;
239
+ }
240
+
241
+ const CHALLENGE_ROUTES = new Set(["build-plan-execute", "build-decision", "build-run-tests"]);
242
+ const roundOf = (s: WorkflowRun["steps"][number]): number => {
243
+ const round = Number((s as { round?: unknown }).round);
244
+ return Number.isInteger(round) && round >= 1 ? round : 1;
245
+ };
246
+
247
+ /** The run's DONE `build-challenge` rows and the route rows after them, in order. */
248
+ const challengeRows = (steps: WorkflowRun["steps"]) =>
249
+ steps.filter(
250
+ (s) => s.status === "DONE" && (s.step === "build-challenge" || CHALLENGE_ROUTES.has(s.step)),
251
+ );
252
+
253
+ /** Whether a challenge row at round `max` or later has a route row after it: no round is left. */
254
+ function challengeDone(steps: WorkflowRun["steps"], max: number): boolean {
255
+ const rows = challengeRows(steps);
256
+ return rows.some(
257
+ (s, i) => s.step === "build-challenge" && roundOf(s) >= max && rows[i + 1] !== undefined,
258
+ );
259
+ }
260
+
261
+ /**
262
+ * The build challenge's round, read from the run's `build-challenge` rows (each carries the
263
+ * `round` it ran as; a row without one counts as round 1) and the step row after each: the
264
+ * next of `build-plan-execute` (route fix), `build-decision` (route pause) or
265
+ * `build-run-tests` (route none). A challenge row with no such row after it has not merged
266
+ * yet, so the run keeps that row's round. Otherwise one past the highest round whose merge
267
+ * wrote tasks (route fix or pause), or that ran past round 1; at most `max`
268
+ * (`bkit.workflows.build.challenge.maxAttempts`).
269
+ */
270
+ function challengeRound(steps: WorkflowRun["steps"], max: number): number {
271
+ const rows = challengeRows(steps);
272
+ const last = rows.at(-1);
273
+ if (last?.step === "build-challenge") return roundOf(last);
274
+ const done = rows
275
+ .filter(
276
+ (s, i) =>
277
+ s.step === "build-challenge" && (roundOf(s) > 1 || rows[i + 1]?.step !== "build-run-tests"),
278
+ )
279
+ .map(roundOf);
280
+ return done.length === 0 ? 1 : Math.min(Math.max(...done) + 1, max);
281
+ }
282
+
283
+ /** Where `workflow`'s active run resumes; Step 1 when no run is active or no known step is DONE. */
284
+ export function resumePoint(
285
+ runs: WorkflowRun[],
286
+ workflow: ResumableWorkflow,
287
+ challengeMax = CONFIG_DEFAULTS.asks["build.challenge"].max,
288
+ ): ResumePoint {
289
+ const table = WORKFLOW_STEPS[workflow];
290
+ const retired = RETIRED_STEPS[workflow] ?? {};
291
+ const decision = DECISION_ROUTES[workflow];
292
+ const byStep = new Map(table.filter((s) => s.step !== undefined).map((s) => [s.step!, s]));
293
+ const latest = runs.at(-1);
294
+ const active = latest?.workflow === workflow && latest.status === "IN_PROGRESS";
295
+ const steps = active ? latest.steps : [];
296
+ const at = (entry: WorkflowStep, after: string | null, group: number | null) => ({
297
+ step: entry.step ?? null,
298
+ number: entry.number,
299
+ title: entry.title,
300
+ after,
301
+ group,
302
+ active,
303
+ challengeRound: workflow === "build" ? challengeRound(steps, challengeMax) : null,
304
+ challengeDone: workflow === "build" ? challengeDone(steps, challengeMax) : null,
305
+ });
306
+ const routeOf = (s: WorkflowRun["steps"][number]): string | undefined => {
307
+ if (decision === undefined || s.step !== decision.step) return undefined;
308
+ const route = decision.routes[String((s as { route?: unknown }).route)];
309
+ if (typeof route !== "object") return route;
310
+ const prior = steps
311
+ .slice(0, steps.lastIndexOf(s))
312
+ .filter((r) => r.status === "DONE" && r.step !== decision.step && byStep.has(r.step))
313
+ .at(-1);
314
+ return prior === undefined ? undefined : route[prior.step];
315
+ };
316
+ const done = steps.filter(
317
+ (s) =>
318
+ s.status === "DONE" && (byStep.has(s.step) || s.step in retired || routeOf(s) !== undefined),
319
+ );
320
+ const last = done.filter((s) => byStep.get(s.step)?.setup !== true).at(-1) ?? done.at(-1);
321
+ if (last === undefined) return at(table[0]!, null, null);
322
+ const routed = routeOf(last);
323
+ if (routed !== undefined) {
324
+ // A decision row carries no group: the group is the one the paused step worked on.
325
+ const before = done.slice(0, done.lastIndexOf(last)).reverse();
326
+ const prior = before.find((s) => (s.group ?? s.subPlan) !== undefined);
327
+ return at(byStep.get(routed)!, last.step, prior?.group ?? prior?.subPlan ?? null);
328
+ }
329
+ const group = last.group ?? last.subPlan ?? null;
330
+ const verdict = String((last as { verdict?: unknown }).verdict);
331
+ const target =
332
+ retired[last.step] ??
333
+ byStep.get(last.step)!.resumeOnVerdict?.[verdict] ??
334
+ byStep.get(last.step)!.resumeAt;
335
+ if (target !== undefined) return at(byStep.get(target)!, last.step, group);
336
+ const own = byStep.get(last.step)!;
337
+ const next = table.find((s) => s.number > own.number);
338
+ return at(next ?? own, last.step, group);
339
+ }