@cbartens/bkit 6.1.0 → 6.2.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 (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -33,6 +33,7 @@ import {
33
33
  statusTimestamp,
34
34
  type StatusEvent,
35
35
  type StatusRow,
36
+ withTargetLock,
36
37
  } from "../../ledgers/status.js";
37
38
  import {
38
39
  compareTs,
@@ -87,6 +88,7 @@ import {
87
88
  import {
88
89
  EXIT_EMPTY,
89
90
  activeRecord,
91
+ appendRunCommits,
90
92
  commitBookkeeping,
91
93
  ownPathCommit,
92
94
  ownSet,
@@ -94,6 +96,7 @@ import {
94
96
  appendLedgerRows,
95
97
  runRows,
96
98
  unionLedgers,
99
+ writeParkedCommits,
97
100
  } from "./ledgers.js";
98
101
  import { readIssueTracker } from "./fids.js";
99
102
  import {
@@ -114,15 +117,18 @@ import {
114
117
  import { buildSummary, refOf, SUMMARY_WORKFLOWS, type SummaryWorkflow } from "./summary.js";
115
118
  import { parsePlans, parseWorkstreams } from "./plans.js";
116
119
  import {
120
+ EXIT_LOCK_BUSY,
117
121
  EXIT_REMOVE_FAILED,
118
122
  EXIT_SPLIT_BUCKET,
119
123
  acquireWorkflowLock,
120
124
  owns,
121
125
  readHolder,
126
+ readRunsLenient,
122
127
  releaseLock,
123
128
  resolveMonth,
124
129
  workflowLockPath,
125
130
  } from "./locks.js";
131
+ import { openDecision } from "./open-decision.js";
126
132
  import { highestVersion } from "./plan-versions.js";
127
133
  import { mergePr, probePr } from "./prs.js";
128
134
  import { FEATURE_STATUS } from "./roadmap.js";
@@ -142,6 +148,7 @@ import {
142
148
  attempt,
143
149
  commentFileOf,
144
150
  postForVerb,
151
+ bindRunPublication,
145
152
  issueRef,
146
153
  readLabels,
147
154
  endedRunActionKey,
@@ -240,61 +247,6 @@ export function recordChat(file: string, workflow: string, env: NodeJS.ProcessEn
240
247
  fs.appendFileSync(file, appendLine(row));
241
248
  }
242
249
 
243
- /** An OPEN Decision Pause file of the current run, as `workflows start` prints it. */
244
- export interface OpenDecision {
245
- file: string;
246
- decision: number;
247
- question: string | null;
248
- from: string | null;
249
- pauseStep: number | null;
250
- group: number | null;
251
- verifyAttempt: number | null;
252
- testAttempt: number | null;
253
- plan: string | null;
254
- }
255
-
256
- /**
257
- * The highest-numbered `{workflow}-decision-{run}-{N}.md` in `logDir` whose header holds
258
- * `Status: OPEN`, or null. Only the given run's files count, so an earlier run's pause
259
- * never resurfaces. `file` is relative to `tree`.
260
- */
261
- export function openDecision(
262
- logDir: string,
263
- tree: string,
264
- workflow: string,
265
- run: number,
266
- ): OpenDecision | null {
267
- if (!fs.existsSync(logDir)) return null;
268
- const name = new RegExp(`^${workflow}-decision-${run}-([0-9]+)\\.md$`);
269
- const found = fs
270
- .readdirSync(logDir)
271
- .map((f) => ({ f, m: name.exec(f) }))
272
- .filter((x): x is { f: string; m: RegExpExecArray } => x.m !== null)
273
- .map(({ f, m }) => ({ f, n: Number(m[1]) }))
274
- .sort((a, b) => b.n - a.n);
275
- for (const { f, n } of found) {
276
- const text = fs.readFileSync(path.join(logDir, f), "utf-8");
277
- const field = (key: string) =>
278
- new RegExp(`^${key}:[ \\t]*(.+?)[ \\t]*$`, "m").exec(text)?.[1] ?? null;
279
- if (field("Status") !== "OPEN") continue;
280
- const num = (key: string) => {
281
- const v = field(key);
282
- return v !== null && /^[0-9]+$/.test(v) ? Number(v) : null;
283
- };
284
- return {
285
- file: path.relative(tree, path.join(logDir, f)),
286
- decision: n,
287
- question: field("Question"),
288
- from: field("From"),
289
- pauseStep: num("Pause step"),
290
- group: num("Group"),
291
- verifyAttempt: num("Verify attempt"),
292
- testAttempt: num("Test attempt"),
293
- plan: field("Plan"),
294
- };
295
- }
296
- return null;
297
- }
298
250
  const logDirRel = (month: string, fid: string) => path.join("docs", "plans", month, "logs", fid);
299
251
  const list = (v: FlagValue) => (v as string[] | undefined) ?? [];
300
252
 
@@ -389,6 +341,16 @@ function failState(ctx: RunContext, workflow: string, fid: string) {
389
341
  return { row, rebaseAborted, lock, sentinels, removeFailed, soak, status };
390
342
  }
391
343
 
344
+ /** Exit code: `workflows fail` refused `--next-step` before any write; no other usage error of that verb uses it. */
345
+ const EXIT_NEXT_STEP_REFUSED = 6;
346
+
347
+ /**
348
+ * The only `--next-step` shape `workflows fail` posts: a `/bkit-` command name, then optional
349
+ * space-separated arguments such as an FID or `#682`. The value goes into a code span in the
350
+ * failure comment, so nothing that could end the span or start markdown or HTML gets through.
351
+ */
352
+ const NEXT_STEP_SHAPE = /^\/bkit-[a-z0-9-]+(?: [#A-Za-z0-9._-]+)*$/;
353
+
392
354
  async function failVerb(ctx: RunContext): Promise<number> {
393
355
  const workflow = workflowName(String(ctx.flags.workflow));
394
356
  // An empty value is a placeholder not held yet (the failure came before it was set).
@@ -396,6 +358,10 @@ async function failVerb(ctx: RunContext): Promise<number> {
396
358
  const token = str(ctx.flags.token) || undefined;
397
359
  if (token !== undefined && fid === undefined)
398
360
  throw new CommandError(EXIT.USAGE, "--token needs --fid");
361
+ // Empty is absent; anything else is one /bkit-* command line, checked before any write.
362
+ const nextStep = str(ctx.flags.nextStep) || undefined;
363
+ if (nextStep !== undefined && !NEXT_STEP_SHAPE.test(nextStep))
364
+ throw new CommandError(EXIT_NEXT_STEP_REFUSED, "--next-step must be one /bkit-* command line");
399
365
 
400
366
  // State only for a run that took the lock: without the token the failure came
401
367
  // before Step 1 locked, and nothing here is this run's to change.
@@ -445,6 +411,7 @@ async function failVerb(ctx: RunContext): Promise<number> {
445
411
  subStep: str(ctx.flags.subStep),
446
412
  error: state.removeFailed ? `${error}; Lock removal failed` : error,
447
413
  stderrFile: str(ctx.flags.stderrFile) || undefined,
414
+ ...(nextStep === undefined ? {} : { lines: [`Next step: \`${nextStep}\``] }),
448
415
  });
449
416
  }
450
417
  if (ctx.flags.post === true && comment === null)
@@ -463,6 +430,7 @@ async function failVerb(ctx: RunContext): Promise<number> {
463
430
  fid,
464
431
  issue: str(ctx.flags.issue),
465
432
  ...(key === undefined ? {} : { file: state.status, key }),
433
+ purpose: "attention",
466
434
  })
467
435
  : undefined;
468
436
  const labelsWrite =
@@ -481,7 +449,8 @@ async function failVerb(ctx: RunContext): Promise<number> {
481
449
  trackerState: failedState,
482
450
  prState,
483
451
  comment,
484
- commentFile: commentFileOf(ctx.cwd, comment),
452
+ nextStep: nextStep ?? null,
453
+ commentFile: commentFileOf(ctx.cwd, comment, ctx),
485
454
  ...(tracker === undefined ? {} : { tracker }),
486
455
  ...(labelsWrite === undefined ? {} : { labelsWrite }),
487
456
  ...sessionRemoval(ctx),
@@ -632,13 +601,17 @@ function carryOwnBook(
632
601
  const uncommitted = (file: string) => runRows(src, file, rec);
633
602
  const add = (file: string, lines: string[]) => {
634
603
  const to = path.join(dst, file);
635
- const existing = fs.existsSync(to) ? fs.readFileSync(to, "utf-8") : "";
636
- const have = new Set(textLines(existing).map((l) => l.trim()));
637
- const fresh = lines.filter((l) => !have.has(l.trim()));
638
- if (fresh.length === 0) return;
639
604
  fs.mkdirSync(path.dirname(to), { recursive: true });
640
- const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
641
- fs.appendFileSync(to, `${sep}${fresh.join("\n")}\n`);
605
+ const fresh = withTargetLock(to, () => {
606
+ const existing = fs.existsSync(to) ? fs.readFileSync(to, "utf-8") : "";
607
+ const have = new Set(textLines(existing).map((l) => l.trim()));
608
+ const missing = lines.filter((l) => !have.has(l.trim()));
609
+ if (missing.length === 0) return missing;
610
+ const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
611
+ fs.appendFileSync(to, `${sep}${missing.join("\n")}\n`);
612
+ return missing;
613
+ });
614
+ if (fresh.length === 0) return;
642
615
  carried.lines.set(file, fresh);
643
616
  };
644
617
  const listed = (specs: string[]) =>
@@ -879,6 +852,17 @@ async function handoverVerb(ctx: RunContext): Promise<number> {
879
852
  }
880
853
  let handed: { sha: string; carried: Carried } | undefined;
881
854
  const rec = shared && (push || flush) ? activeRecord(tree, fid) : null;
855
+ // A run that stays open keeps its commit list, because the record goes below: a parked
856
+ // copy in this clone's git dir, and a row in its status log that lands with the handover.
857
+ const statusAbs = path.join(tree, statusRelPath(month, fid));
858
+ if (
859
+ rec !== null &&
860
+ fs.existsSync(statusAbs) &&
861
+ lastRun(readRunsLenient(statusAbs), workflow)?.status === "IN_PROGRESS"
862
+ ) {
863
+ appendRunCommits(statusAbs, workflow, rec);
864
+ writeParkedCommits(tree, workflow, rec);
865
+ }
882
866
  if (push && shared) {
883
867
  const r = await landFailedRecord(ctx, { workflow, fid, month, book: tree, shared });
884
868
  if (r.sha !== undefined && r.carried !== undefined) handed = { sha: r.sha, carried: r.carried };
@@ -928,16 +912,24 @@ async function handoverVerb(ctx: RunContext): Promise<number> {
928
912
  if (rec !== null) removeRecord(tree, fid);
929
913
  const tracker =
930
914
  ctx.flags.post === true && comment !== null
931
- ? await postForVerb(ctx, comment, { fid })
915
+ ? await postForVerb(ctx, comment, { fid, purpose: "attention" })
932
916
  : undefined;
917
+ // Every exit this verb reaches keeps the record somewhere, so the run stops either way: an
918
+ // open PR (9), a refused push (10) or a failed dev landing (11) only add the closing line.
919
+ const message =
920
+ code === EXIT.OK
921
+ ? ""
922
+ : `Record not pushed: the handover commit is only in ${tree}, and the links in this run's comments open once it is pushed`;
933
923
  ctx.emit({
934
924
  handover: present ? artifact : null,
935
925
  pushed,
936
926
  ref: pushed ? ref : null,
937
927
  skipped,
938
928
  comment,
939
- commentFile: commentFileOf(ctx.cwd, comment),
929
+ commentFile: commentFileOf(ctx.cwd, comment, ctx),
940
930
  ...(tracker === undefined ? {} : { tracker }),
931
+ route: "stop",
932
+ message,
941
933
  });
942
934
  return code;
943
935
  }
@@ -1567,7 +1559,7 @@ async function shipClose(
1567
1559
  `fetch of dev after the close PR failed — origin/${DEV} is stale until the next fetch`,
1568
1560
  );
1569
1561
  try {
1570
- worktree = removeWorktree(root, o.fid, o.branch, ctx.log);
1562
+ worktree = removeWorktree(root, o.fid, o.branch, ctx.log, { landed: true });
1571
1563
  } catch (err) {
1572
1564
  ctx.log(`${(err as Error).message} — remove ${book} by hand`);
1573
1565
  }
@@ -2017,8 +2009,12 @@ function inputVerb(ctx: RunContext): number {
2017
2009
  const text = inputText(ctx.cwd, audit, "audit");
2018
2010
  sections.push([`Audit Report — ${audit} — ${fileDate(ctx.cwd, audit)}`, text]);
2019
2011
  }
2020
- const body = sections.map(([h, text]) => `## ${h}\n\n${text}\n`).join("\n");
2021
2012
  const abs = path.join(path.dirname(status), `${workflow}-input-${run}.md`);
2013
+ const grill = path.join(path.dirname(status), `${workflow}-grill-${run}.md`);
2014
+ const sectionText = sections.map(([h, text]) => `## ${h}\n\n${text}\n`).join("\n");
2015
+ const body = fs.existsSync(grill)
2016
+ ? `${sectionText}\n${fs.readFileSync(grill, "utf-8")}`
2017
+ : sectionText;
2022
2018
  fs.mkdirSync(path.dirname(abs), { recursive: true });
2023
2019
  fs.writeFileSync(abs, body);
2024
2020
  ctx.emit({
@@ -2040,10 +2036,10 @@ async function postClose(
2040
2036
  out: Record<string, unknown>,
2041
2037
  ): Promise<Record<string, unknown>> {
2042
2038
  const comment = typeof out.comment === "string" ? out.comment : null;
2043
- const withFile = { ...out, commentFile: commentFileOf(ctx.cwd, comment) };
2039
+ const withFile = { ...out, commentFile: commentFileOf(ctx.cwd, comment, ctx) };
2044
2040
  if (ctx.flags.post !== true) return withFile;
2045
2041
  if (comment === null) throw new CommandError(EXIT.USAGE, "--post needs --number");
2046
- return { ...withFile, tracker: await postForVerb(ctx, comment, { fid }) };
2042
+ return { ...withFile, tracker: await postForVerb(ctx, comment, { fid, purpose: "terminal" }) };
2047
2043
  }
2048
2044
 
2049
2045
  export const workflowsCommand: CommandSpec = {
@@ -2059,6 +2055,7 @@ export const workflowsCommand: CommandSpec = {
2059
2055
  FID_FLAG,
2060
2056
  MONTH_FLAG,
2061
2057
  STATUS_FILE_FLAG,
2058
+ SESSION_DIR_FLAG,
2062
2059
  {
2063
2060
  name: "lock-held",
2064
2061
  type: "boolean",
@@ -2079,12 +2076,14 @@ export const workflowsCommand: CommandSpec = {
2079
2076
  run: "which run of the workflow this is (1-based)",
2080
2077
  lastDoneStep: "the current run's last DONE step: resume after it (null on a new run)",
2081
2078
  openDecision:
2082
- "{file, decision, question, from, pauseStep, group, verifyAttempt, testAttempt, plan} of the current run's highest {workflow}-decision-{run}-{N}.md holding Status: OPEN, else null",
2079
+ "{file, decision, question, from, pauseStep, group, verifyAttempt, testAttempt, plan, gate, sourceChanged, status} of the current run's highest {workflow}-decision-{run}-{N}.md holding Status: OPEN, or DECIDED / ASSUMED when no {workflow}-decision row names it, else null",
2083
2080
  },
2084
2081
  textOmit: ["row"],
2085
2082
  exitCodes: {
2086
2083
  [EXIT_NO_STATUS]: "status.jsonl is not valid",
2087
2084
  [EXIT_SPLIT_BUCKET]: "the feature has logs in more than one month bucket",
2085
+ [EXIT_LOCK_BUSY]:
2086
+ "without --lock-held: another run of the feature holds the lock and is still stepping",
2088
2087
  [EXIT_LOCK_NOT_HELD]: "--lock-held: the lock is missing or belongs to another owner",
2089
2088
  [EXIT_WRONG_BRANCH]: "--branch: the checkout is on another branch",
2090
2089
  },
@@ -2161,6 +2160,7 @@ export const workflowsCommand: CommandSpec = {
2161
2160
  recordChat(file, workflow, process.env);
2162
2161
  const runs = fold(readStatusEvents(file));
2163
2162
  const run = runNumber(runs, workflow);
2163
+ bindRunPublication(ctx, file, workflow, run);
2164
2164
  const current = resumed ? lastRun(runs, workflow) : undefined;
2165
2165
  ctx.emit({
2166
2166
  lock,
@@ -2170,7 +2170,15 @@ export const workflowsCommand: CommandSpec = {
2170
2170
  run,
2171
2171
  lastDoneStep: current?.steps.filter((s) => s.status === "DONE").at(-1)?.step ?? null,
2172
2172
  openDecision: resumed
2173
- ? openDecision(path.dirname(file), where.tree, workflow, run)
2173
+ ? openDecision(
2174
+ path.dirname(file),
2175
+ where.tree,
2176
+ workflow,
2177
+ run,
2178
+ (current?.steps ?? [])
2179
+ .filter((s) => s.step === `${workflow}-decision`)
2180
+ .flatMap((s) => s.artifacts),
2181
+ )
2174
2182
  : null,
2175
2183
  });
2176
2184
  return EXIT.OK;
@@ -2223,6 +2231,12 @@ export const workflowsCommand: CommandSpec = {
2223
2231
  type: "string",
2224
2232
  help: "the failed shell command's stderr (last 20 lines kept)",
2225
2233
  },
2234
+ {
2235
+ name: "next-step",
2236
+ type: "string",
2237
+ placeholderExit: EXIT_NEXT_STEP_REFUSED,
2238
+ help: "one /bkit-* command line to name as the next step: adds a `Next step:` line to the failure comment (empty = none)",
2239
+ },
2226
2240
  {
2227
2241
  ...POST_FLAG,
2228
2242
  help: "post the failure comment (needs --step-number) to the --fid / --issue issue and write its failed labels; prints `tracker` and `labelsWrite`",
@@ -2247,6 +2261,7 @@ export const workflowsCommand: CommandSpec = {
2247
2261
  trackerState: "the Linear or Jira state for the failed issue (null under github, none)",
2248
2262
  prState: "the --pr PR's state, or null",
2249
2263
  comment: "the failure comment body (with --step-number), else null",
2264
+ nextStep: "the --next-step command line, or null",
2250
2265
  commentFile: COMMENT_FILE_OUTPUT,
2251
2266
  tracker: TRACKER_OUTPUT,
2252
2267
  labelsWrite:
@@ -2255,6 +2270,8 @@ export const workflowsCommand: CommandSpec = {
2255
2270
  },
2256
2271
  textOmit: ["row"],
2257
2272
  exitCodes: {
2273
+ [EXIT_NEXT_STEP_REFUSED]:
2274
+ "a refused --next-step (not one /bkit-* command line, or an unsubstituted placeholder): refused before any write, so the call can run again without it",
2258
2275
  [EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
2259
2276
  [EXIT_REMOVE_FAILED]:
2260
2277
  "the lock file is still there after removing it (everything else was done; the comment says so)",
@@ -2307,6 +2324,10 @@ export const workflowsCommand: CommandSpec = {
2307
2324
  "the handover comment body (null when there is no handover); links only when pushed",
2308
2325
  commentFile: COMMENT_FILE_OUTPUT,
2309
2326
  tracker: `${TRACKER_OUTPUT}; absent when there is no handover`,
2327
+ route:
2328
+ "stop: the record is kept (pushed, or left in the run's tree on exit 9, 10 or 11) and the run ends here; workflows route on this, not on the exit code",
2329
+ message:
2330
+ "the line to add to the owner's final message: `Record not pushed: …` on exit 9, 10 or 11, empty otherwise",
2310
2331
  shared: "--list-stray: the checkout is dev / main / detached (remove nothing)",
2311
2332
  modified: "--list-stray: tracked paths with changes, outside the run's logs",
2312
2333
  untracked: "--list-stray: untracked paths, outside the run's logs",
@@ -2483,7 +2504,14 @@ export const workflowsCommand: CommandSpec = {
2483
2504
  squashSha: str(f.squashSha),
2484
2505
  ref: str(f.ref),
2485
2506
  ownerRepo: str(f.ownerRepo),
2486
- outbox: str(f.outbox),
2507
+ outbox:
2508
+ str(f.outbox) ??
2509
+ (str(f.sessionDir)
2510
+ ? path.join(
2511
+ path.dirname(path.dirname(path.resolve(ctx.cwd, String(f.sessionDir)))),
2512
+ String(f.fid),
2513
+ )
2514
+ : undefined),
2487
2515
  recordStep: f.recordStep === true,
2488
2516
  message: str(f.message),
2489
2517
  labels: list(f.label),
@@ -2516,7 +2544,7 @@ export const workflowsCommand: CommandSpec = {
2516
2544
  },
2517
2545
  input: {
2518
2546
  summary:
2519
- "Write logs/{FID}/{workflow}-input-{run}.md: the session prompt, the issue description and each human comment, then the plan, design and audit reports, each section dated.",
2547
+ "Write logs/{FID}/{workflow}-input-{run}.md: the session prompt, the issue description and each human comment, then the plan, design and audit reports, each section dated. An existing {workflow}-grill-{run}.md in the same folder is appended at the end.",
2520
2548
  use: "workflow",
2521
2549
  flags: [
2522
2550
  WORKFLOW_FLAG,