@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -14,18 +14,27 @@ import * as fs from "node:fs";
14
14
  import * as path from "node:path";
15
15
 
16
16
  import {
17
+ actionKey,
17
18
  activeDoneSteps,
19
+ allRunsDoneSteps,
18
20
  appendLine,
21
+ ciRoundMatches,
22
+ runNumber,
19
23
  runOrStepField,
20
24
  statusTimestamp,
21
25
  type Step,
22
26
  } from "../../ledgers/status.js";
23
27
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
28
+ import { appendFrictionRow, frictionRow, journalEnabled } from "../../ledgers/journal.js";
24
29
  import { resolveRepoSlug } from "../../ledgers/telemetry.js";
25
30
  import { getPromptsRoot } from "../../shared/package-roots.js";
31
+ import { readTextFile } from "../../shared/json.js";
26
32
  import {
27
33
  CommandError,
28
34
  EXIT,
35
+ git,
36
+ isSharedBranch,
37
+ parseJson,
29
38
  repoRoot,
30
39
  runGit,
31
40
  type CommandSpec,
@@ -33,23 +42,72 @@ import {
33
42
  type FlagValue,
34
43
  type RunContext,
35
44
  } from "../lib.js";
36
- import { FID_PATTERNS, normaliseFid, readIssueTracker } from "./fids.js";
45
+ import { activeRunStart, savedPointLimit } from "./counters.js";
46
+ import type { AskPoint } from "../../shared/settings.js";
47
+ import { isResumable, runProgress, WORKFLOW_STEPS } from "./step-table.js";
48
+ import { planFiles } from "./run-facts.js";
49
+ import { mergeFindings, parseFindings } from "./challenge.js";
50
+ import { fidProblem, normaliseFid, readIssueTracker } from "./fids.js";
37
51
  import { buildComment } from "./issues.js";
52
+ import {
53
+ EXIT_FOREIGN_PATH,
54
+ activeRecord,
55
+ ownPathCommit,
56
+ ownSet,
57
+ type OwnCommit,
58
+ type SharedCheckoutRecord,
59
+ } from "./ledgers.js";
38
60
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
39
61
  import {
40
62
  EXIT_NO_STATUS,
41
63
  FILE_FLAG,
64
+ GROUP_FLAG,
42
65
  STEP_FLAG,
43
- SUB_PLAN_FLAG,
44
66
  WORKFLOW_FLAG,
45
67
  extraField,
46
68
  nonNegativeInt,
47
69
  positiveInt,
48
70
  readRuns,
71
+ readStatusRows,
49
72
  readRunsAt,
50
73
  statusFile,
51
74
  str,
52
75
  } from "./status.js";
76
+ import {
77
+ COMMENT_FILE_OUTPUT,
78
+ POST_FLAG,
79
+ TRACKER_OUTPUT,
80
+ commentFileOf,
81
+ postForVerb,
82
+ type TrackerOutcome,
83
+ } from "./tracker.js";
84
+ import { parsePlanBlocks } from "./plan-blocks.js";
85
+ import { PLAN_TASKS_STEP, readTestFirst, touchedTests } from "./tests.js";
86
+ import { addAllButCopied } from "./worktrees.js";
87
+
88
+ /**
89
+ * An `agent-rework` friction row for a refused planned-test edit: the step reruns, so
90
+ * `bkit stats` counts it. Best effort — a ledger that cannot be written never changes
91
+ * the refusal.
92
+ */
93
+ function recordTestLockFriction(top: string, step: string, named: string): void {
94
+ if (!journalEnabled()) return;
95
+ const row = frictionRow({
96
+ workflow: "build",
97
+ step,
98
+ noun: "steps",
99
+ verb: "finish",
100
+ code: EXIT_TESTS_TOUCHED,
101
+ bookRoot: top,
102
+ parentSha: git(top, ["rev-parse", "HEAD"]) ?? undefined,
103
+ });
104
+ row["category"] = "agent-rework";
105
+ row["severity"] = "LOW";
106
+ row["summary"] = "a code step edited a planned test case";
107
+ row["description"] =
108
+ `\`bkit steps finish\` refused ${step} with exit ${EXIT_TESTS_TOUCHED}: ${named} changed after the group's red; the step reruns.`;
109
+ appendFrictionRow(top, row);
110
+ }
53
111
 
54
112
  const VERDICT_END = "<!-- verdict:end -->";
55
113
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
@@ -63,6 +121,19 @@ export const EXIT_ARTIFACT = 7;
63
121
  export const EXIT_COMMIT = 8;
64
122
  /** finish --docs-only: the step staged a file outside the artifact tree. */
65
123
  export const EXIT_OUTSIDE_DOCS = 9;
124
+ /** finish (build plan-execute / plan-gaps-remediate): a planned test case differs from the lines the group's tests step recorded. */
125
+ export const EXIT_TESTS_TOUCHED = 11;
126
+ /** finish: a saved artifact holds a later attempt than the one finished. */
127
+ export const EXIT_LATER_ATTEMPT = 12;
128
+ /** finish: the step's commit would change `bkit.workflows` in package.json. */
129
+ export const EXIT_WORKFLOWS_CHANGED = 13;
130
+ /** finish (build plan-tests): the tests step's commit changes a file that is not one of the group's planned tests. */
131
+ export const EXIT_SOURCE_TOUCHED = 15;
132
+
133
+ /** The step whose subagent writes the group's TEST FIRST tests, before any task code. */
134
+ export const PLAN_TESTS_STEP = "build-plan-tests";
135
+ /** The step whose subagent closes the group's verification gaps: a code step, like plan-execute. */
136
+ export const PLAN_REMEDIATE_STEP = "build-plan-gaps-remediate";
66
137
 
67
138
  /** Where `finish` puts the derived attempt in `--artifact` / `--message` / `--clamp-log`. */
68
139
  export const ATTEMPT_TOKEN = "<attempt>";
@@ -281,22 +352,18 @@ export const ROW_FIELDS: Record<string, readonly RowField[]> = {
281
352
  "plan/plan-fetch-context": ["attempt"],
282
353
  "plan/plan-review": ["attempt"],
283
354
  "plan/plan-apply-review": ["attempt"],
284
- "plan/plan-scope-check": ["attempt"],
285
- "plan/plan-apply-scope": ["attempt"],
286
- "plan/plan-complexity-check": ["attempt"],
287
- "plan/plan-complexity-split": ["attempt"],
288
355
  "plan/plan-summary": ["attempt"],
356
+ "build/build-plan-convert": ["attempt"],
289
357
  "build/build-plan-current": ["attempt"],
290
358
  "build/build-install-skills": ["attempt"],
291
- "build/build-plan-execute": ["attempt"],
359
+ "build/build-plan-tests": ["attempt"],
360
+ "build/build-plan-tasks": ["attempt"],
292
361
  "build/build-plan-verify": ["attempt"],
293
- "build/build-subplan-gate": ["attempt", "scope"],
362
+ "build/build-group-gate": ["attempt", "scope"],
294
363
  "build/build-plan-gaps-remediate": ["attempt", "strategy"],
295
364
  "build/build-plan-verify-holistic": ["attempt"],
296
365
  "build/build-challenge": ["attempt"],
297
- "build/build-challenge-reconcile": ["attempt"],
298
- "build/build-challenge-remediate": ["attempt"],
299
- "build/build-challenge-tests": ["attempt"],
366
+ "build/build-decision": ["attempt"],
300
367
  "build/build-run-tests": ["attempt", "scope"],
301
368
  "build/build-failure-diagnose": ["attempt", "strategy"],
302
369
  "build/build-failure-remediate": ["attempt", "strategy"],
@@ -336,7 +403,7 @@ const CORE_ROW_KEYS = new Set([
336
403
  "artifacts",
337
404
  "verdict",
338
405
  "attempt",
339
- "subPlan",
406
+ "group",
340
407
  "failures",
341
408
  "strategy",
342
409
  ]);
@@ -345,6 +412,107 @@ const CORE_ROW_KEYS = new Set([
345
412
  // Writing the row
346
413
  // ---------------------------------------------------------------------------
347
414
 
415
+ /** The FID a `docs/plans/{month}/logs/{fid}/status.jsonl` path belongs to; undefined for any other file. */
416
+ function fidOfStatusFile(file: string): string | undefined {
417
+ return /(?:^|\/)docs\/plans\/[0-9]{6}\/logs\/([^/]+)\/status\.jsonl$/.exec(
418
+ file.split(path.sep).join("/"),
419
+ )?.[1];
420
+ }
421
+
422
+ /** Loop budgets use the same point names as the workflow counter routes. */
423
+ function progressPoint(workflow: string, step: string, soak: boolean): AskPoint | undefined {
424
+ if (workflow === "build") {
425
+ if (["build-plan-verify", "build-group-gate", "build-plan-gaps-remediate"].includes(step))
426
+ return "build.verify";
427
+ if (step === "build-challenge") return "build.challenge";
428
+ if (["build-run-tests", "build-failure-diagnose", "build-failure-remediate"].includes(step))
429
+ return "build.tests";
430
+ }
431
+ if (workflow === "debug") {
432
+ if (step === "debug-failure-soak" || soak) return "debug.soak";
433
+ if (["debug-run-tests", "debug-failure-diagnose", "debug-failure-remediate"].includes(step))
434
+ return "debug.fix";
435
+ }
436
+ if (
437
+ workflow === "ship" &&
438
+ ["ship-merge-pr", "ship-failure-diagnose", "ship-failure-remediate"].includes(step)
439
+ )
440
+ return "ship.merge";
441
+ return undefined;
442
+ }
443
+
444
+ /** Prepare output before a completion mutates the log; progress is never persisted. */
445
+ function stepProgress(cwd: string, r: StepRow, number?: number): string | undefined {
446
+ if (r.status === "FAILED" || !isResumable(r.workflow)) return undefined;
447
+ const entry = WORKFLOW_STEPS[r.workflow].find((s) =>
448
+ number === undefined ? s.step === r.step : s.number === number,
449
+ );
450
+ if (entry === undefined) {
451
+ if (number !== undefined)
452
+ throw new CommandError(EXIT.USAGE, "--progress-number is not a workflow step");
453
+ return undefined;
454
+ }
455
+ if (fs.existsSync(r.file) && !readTextFile(r.file).ok)
456
+ throw new CommandError(EXIT_NO_STATUS, `${r.file} is unreadable`);
457
+ const runs = fs.existsSync(r.file) ? readRuns(r.file) : [];
458
+ const run = runs.filter((item) => item.workflow === r.workflow).at(-1);
459
+ const abs = path.resolve(cwd, r.file);
460
+ const canonical = /^(.*)\/docs\/plans\/([0-9]{6})\/logs\/([^/]+)\/status\.jsonl$/.exec(
461
+ abs.split(path.sep).join("/"),
462
+ );
463
+ let groups: number[] = [];
464
+ if (r.workflow === "build" && canonical !== null) {
465
+ const [file] = planFiles(canonical[1]!, canonical[2]!, canonical[3]!);
466
+ if (file !== undefined) {
467
+ const text = readTextFile(file);
468
+ if (!text.ok) throw new CommandError(EXIT.USAGE, `progress plan ${file} is unreadable`);
469
+ const plan = parsePlanBlocks(text.text);
470
+ if (plan.errors.length > 0 || plan.fenceOpen !== undefined)
471
+ throw new CommandError(
472
+ EXIT.USAGE,
473
+ `invalid progress plan: ${plan.errors.map((e) => e.message).join("; ") || "unclosed code fence"}`,
474
+ );
475
+ groups = plan.groups.map((g) => g.group);
476
+ }
477
+ }
478
+ const prior = run?.steps.filter((s) => s.status === "DONE") ?? [];
479
+ const same = prior.filter(
480
+ (s) => s.step === r.step && (r.group === undefined || s.group === r.group),
481
+ );
482
+ const soak = runOrStepField(runs, r.workflow, "debugMode") === "SOAK";
483
+ const point = progressPoint(r.workflow, r.step, soak);
484
+ const soakAttempt = Number(
485
+ r.extras?.soakAttempt ?? runOrStepField(runs, r.workflow, "soakAttempt"),
486
+ );
487
+ const challengeRound = Number(r.extras?.round ?? runOrStepField(runs, r.workflow, "round"));
488
+ const attempt =
489
+ point === "debug.soak" && Number.isSafeInteger(soakAttempt) && soakAttempt > 0
490
+ ? soakAttempt
491
+ : point === "debug.fix" && r.step === "debug-failure-remediate"
492
+ ? allRunsDoneSteps(runs, r.workflow, { step: r.step }).length + 1
493
+ : point === "build.challenge" && Number.isSafeInteger(challengeRound) && challengeRound > 0
494
+ ? challengeRound
495
+ : (r.attempt ?? same.at(-1)?.attempt);
496
+ return runProgress({
497
+ workflow: r.workflow,
498
+ step: r.step,
499
+ number,
500
+ groups,
501
+ group: r.group,
502
+ attempt,
503
+ max:
504
+ point === undefined
505
+ ? undefined
506
+ : savedPointLimit(
507
+ r.file,
508
+ r.workflow,
509
+ point,
510
+ r.group,
511
+ point === "debug.fix" || point === "debug.soak",
512
+ ),
513
+ }).progressLine;
514
+ }
515
+
348
516
  export interface StepRow {
349
517
  file: string;
350
518
  workflow: string;
@@ -353,27 +521,95 @@ export interface StepRow {
353
521
  verdict?: string;
354
522
  failures?: number;
355
523
  attempt?: number;
356
- subPlan?: number;
524
+ group?: number;
357
525
  strategy?: string;
358
526
  artifacts: string[];
359
527
  extras?: Record<string, unknown>;
360
528
  /** Default: HEAD now, before this step's commit. */
361
529
  parentSha?: string;
362
- /** auto: `git add -A` + commit `message`; none: the row only. */
530
+ /** auto: `git add -A` minus the `bkit.workflows.worktree.copy` entries + commit `message` (an in-place shared-branch run: its own paths only); none: the row only. */
363
531
  commit: "auto" | "none";
364
532
  message?: string;
365
533
  }
366
534
 
535
+ /** Exit code: a debug run on a shared branch has no shared-checkout record, so nothing was written or committed. */
536
+ export const EXIT_NO_RECORD = 14;
537
+
538
+ /**
539
+ * A debug run on `dev` / `main` works in place, so its record must exist before
540
+ * it writes or commits (`git add -A` there would carry work the run does not own).
541
+ * Throws EXIT_NO_RECORD when the checkout is on a shared branch and `rec` is null.
542
+ */
543
+ export function requireRecordOnShared(
544
+ cwd: string,
545
+ workflow: string,
546
+ rec: SharedCheckoutRecord | null,
547
+ ): void {
548
+ if (workflow !== "debug" || rec !== null) return;
549
+ const branch = git(cwd, ["branch", "--show-current"]) ?? "";
550
+ if (!isSharedBranch(branch)) return;
551
+ throw new CommandError(
552
+ EXIT_NO_RECORD,
553
+ `no shared-checkout record for this run on ${branch} — nothing written or committed (the record is gone or belongs to another run); a plain commit here would carry work the run does not own`,
554
+ );
555
+ }
556
+
557
+ /** The index file `git` commits from in `cwd`, with its bytes now (null: no index yet). */
558
+ interface IndexSnapshot {
559
+ file: string;
560
+ bytes: Buffer | null;
561
+ }
562
+
563
+ /** Throws EXIT_COMMIT when git cannot name the index, before anything is written. */
564
+ function indexSnapshot(cwd: string): IndexSnapshot {
565
+ const res = runGit(cwd, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
566
+ if (!res.ok || res.stdout === "")
567
+ throw new CommandError(
568
+ EXIT_COMMIT,
569
+ `nothing written: git cannot name the index: ${res.stderr}`,
570
+ );
571
+ return {
572
+ file: res.stdout,
573
+ bytes: fs.existsSync(res.stdout) ? fs.readFileSync(res.stdout) : null,
574
+ };
575
+ }
576
+
577
+ /**
578
+ * Put the index back byte-for-byte as `snap` holds it, through git's own `index.lock`, so
579
+ * a git command holding the lock is never overwritten. A refused commit wrote nothing, so
580
+ * every path — staged before the attempt or by it, fully or partly — must read as it did:
581
+ * a row left staged rides the next pathspec-less commit. Returns why it could not, or null.
582
+ */
583
+ function restoreIndex(snap: IndexSnapshot): string | null {
584
+ const lock = `${snap.file}.lock`;
585
+ try {
586
+ fs.writeFileSync(lock, snap.bytes ?? "", { flag: "wx" });
587
+ } catch (err) {
588
+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") fs.rmSync(lock, { force: true });
589
+ return `${lock} could not be taken: ${(err as Error).message}`;
590
+ }
591
+ if (snap.bytes !== null) {
592
+ fs.renameSync(lock, snap.file);
593
+ return null;
594
+ }
595
+ fs.rmSync(snap.file, { force: true });
596
+ fs.rmSync(lock, { force: true });
597
+ return null;
598
+ }
599
+
367
600
  /**
368
601
  * Append one `step-done` row, then commit (parentSha first, the row, then the
369
602
  * commit — the order the fold's de-dup relies on). Returns the row and the new
370
- * commit; `code` is EXIT_COMMIT when the row landed but the commit failed.
603
+ * commit; `code` is EXIT_COMMIT when the commit failed, and the appended row is
604
+ * rolled back, so a re-run after the human's fix writes the same attempt once.
605
+ * `code` is EXIT.NEEDS_HUMAN when the commit failed and the row stays in `r.file`
606
+ * (another writer appended after it) or the index could not be put back.
371
607
  */
372
608
  export function writeStepRow(
373
609
  cwd: string,
374
610
  r: StepRow,
375
611
  log: (m: string) => void,
376
- ): { row: Record<string, unknown>; commit: string | null; code: number } {
612
+ ): { row: Record<string, unknown>; commit: string | null; code: number; progressLine?: string } {
377
613
  const clash = Object.keys(r.extras ?? {}).filter((k) => CORE_ROW_KEYS.has(k));
378
614
  if (clash.length > 0)
379
615
  throw new CommandError(EXIT.USAGE, `--field cannot set ${clash.join(", ")}; use its own flag`);
@@ -393,22 +629,100 @@ export function writeStepRow(
393
629
  artifacts: r.artifacts,
394
630
  ...(r.verdict === undefined ? {} : { verdict: r.verdict as Step["verdict"] }),
395
631
  ...(r.attempt === undefined ? {} : { attempt: r.attempt }),
396
- ...(r.subPlan === undefined ? {} : { subPlan: r.subPlan }),
632
+ ...(r.group === undefined ? {} : { group: r.group }),
397
633
  ...(r.failures === undefined ? {} : { failures: r.failures }),
398
634
  ...(r.strategy === undefined ? {} : { strategy: r.strategy as Step["strategy"] }),
399
635
  ...(r.extras ?? {}),
400
636
  };
637
+ const progressLine = stepProgress(cwd, r);
638
+ // An in-place run on a shared branch commits its own paths only; a refusal
639
+ // comes before the append, so a re-run after the human's fix writes the row once.
640
+ const fid = r.commit === "auto" ? fidOfStatusFile(r.file) : undefined;
641
+ const rec = fid === undefined ? null : activeRecord(cwd, fid);
642
+ if (r.commit === "auto") requireRecordOnShared(cwd, r.workflow, rec);
643
+ if (rec !== null) {
644
+ try {
645
+ ownSet(cwd, rec);
646
+ } catch (err) {
647
+ if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH) throw err;
648
+ log(`no row written to ${r.file}: the commit would be refused: ${err.message}`);
649
+ return { row, commit: null, code: EXIT_FOREIGN_PATH };
650
+ }
651
+ }
652
+ // A plain commit stages the whole tree, so the index is kept to be put back on failure.
653
+ const snap = r.commit === "auto" && rec === null ? indexSnapshot(cwd) : null;
401
654
  fs.mkdirSync(path.dirname(r.file), { recursive: true });
402
- fs.appendFileSync(r.file, appendLine(row));
655
+ const existed = fs.existsSync(r.file);
656
+ const line = appendLine(row);
657
+ fs.appendFileSync(r.file, line);
658
+ // A refused commit takes exactly this attempt's bytes back off `r.file`, so the step's
659
+ // attempt is unchanged and a re-run after the human's fix lands the same attempt once.
660
+ // Returns null once the row is off disk (or the file is gone), else why it stays.
661
+ const rollback = (): string | null => {
662
+ if (!fs.existsSync(r.file)) return null;
663
+ let body: Buffer;
664
+ try {
665
+ body = fs.readFileSync(r.file);
666
+ } catch (err) {
667
+ return `it could not be read back: ${(err as Error).message}`;
668
+ }
669
+ const mine = Buffer.from(line);
670
+ const tail = body.subarray(Math.max(0, body.length - mine.length));
671
+ if (!tail.equals(mine)) return "another writer appended to it after this attempt's row";
672
+ if (!existed && body.length === mine.length) fs.rmSync(r.file, { force: true });
673
+ else fs.truncateSync(r.file, body.length - mine.length);
674
+ return null;
675
+ };
676
+ // The failure reason first, then the index and the file are put back: exit `code` means
677
+ // nothing written, nothing committed; a row that cannot come off disk needs a human, as a
678
+ // re-run would write it twice.
679
+ const failed = (code: number, reason: string) => {
680
+ log(reason);
681
+ const index = snap === null ? null : restoreIndex(snap);
682
+ if (index !== null) log(`the index could not be put back as it was: ${index}`);
683
+ const kept = rollback();
684
+ if (kept !== null) {
685
+ log(
686
+ `the step-done row stays in ${r.file}: ${kept}; nothing committed — remove that row before re-running`,
687
+ );
688
+ return { row, commit: null, code: EXIT.NEEDS_HUMAN };
689
+ }
690
+ log(`no row written to ${r.file}: the row was rolled back`);
691
+ return { row, commit: null, code: index === null ? code : EXIT.NEEDS_HUMAN };
692
+ };
403
693
 
404
- if (r.commit === "none") return { row, commit: null, code: EXIT.OK };
405
- const add = runGit(cwd, ["add", "-A"]);
406
- const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message!]) : add;
407
- if (!made.ok) {
408
- log(`row written to ${r.file} but the commit failed: ${made.stderr || made.stdout}`);
409
- return { row, commit: null, code: EXIT_COMMIT };
694
+ if (r.commit === "none")
695
+ return {
696
+ row,
697
+ commit: null,
698
+ code: EXIT.OK,
699
+ ...(progressLine === undefined ? {} : { progressLine }),
700
+ };
701
+ if (rec !== null) {
702
+ let own: OwnCommit;
703
+ try {
704
+ own = ownPathCommit(cwd, rec, r.message!, { allowEmpty: true });
705
+ } catch (err) {
706
+ if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH) throw err;
707
+ return failed(EXIT_FOREIGN_PATH, `the commit was refused: ${err.message}`);
708
+ }
709
+ if (!own.ok) return failed(EXIT_COMMIT, `the commit failed: ${own.error}`);
710
+ return {
711
+ row,
712
+ commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout,
713
+ code: EXIT.OK,
714
+ ...(progressLine === undefined ? {} : { progressLine }),
715
+ };
410
716
  }
411
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
717
+ const add = addAllButCopied(cwd);
718
+ const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message!]) : add;
719
+ if (!made.ok) return failed(EXIT_COMMIT, `the commit failed: ${made.stderr || made.stdout}`);
720
+ return {
721
+ row,
722
+ commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout,
723
+ code: EXIT.OK,
724
+ ...(progressLine === undefined ? {} : { progressLine }),
725
+ };
412
726
  }
413
727
 
414
728
  // ---------------------------------------------------------------------------
@@ -427,12 +741,14 @@ interface GateOptions {
427
741
  ref?: string;
428
742
  workflow: string;
429
743
  step: string;
430
- subPlan?: number;
744
+ group?: number;
431
745
  attempt?: number;
432
746
  artifacts: string[];
433
747
  verdictRequired: boolean;
434
748
  allowed: string[];
435
749
  fid?: string;
750
+ /** The run's issue id, "" for a run with no issue; absent checks the tracker shape alone. */
751
+ issue?: string;
436
752
  month?: string;
437
753
  token?: string;
438
754
  placeholders: string[];
@@ -459,10 +775,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
459
775
  const fid = normaliseFid(o.fid, tracker);
460
776
  add(
461
777
  `fid ${fid}`,
462
- FID_PATTERNS[tracker].test(fid)
463
- ? undefined
464
- : `does not match the ${tracker} shape ${FID_PATTERNS[tracker].source}`,
465
- `${tracker} shape`,
778
+ fidProblem(fid, tracker, o.issue),
779
+ o.issue === "" && tracker !== "none" ? "issue-less shape" : `${tracker} shape`,
466
780
  );
467
781
  if (o.token !== undefined) {
468
782
  const root = repoRoot(cwd);
@@ -480,6 +794,8 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
480
794
  }
481
795
  } else if (o.token !== undefined) {
482
796
  throw new CommandError(EXIT.USAGE, "--token needs --fid");
797
+ } else if (o.issue !== undefined) {
798
+ throw new CommandError(EXIT.USAGE, "--issue needs --fid");
483
799
  }
484
800
 
485
801
  for (const a of o.artifacts) {
@@ -513,7 +829,7 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
513
829
 
514
830
  if (o.file === undefined) return checks;
515
831
  const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
516
- const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
832
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, group: o.group });
517
833
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
518
834
  const rowProblems: string[] = [];
519
835
  if (!row) {
@@ -549,20 +865,29 @@ function gateChecks(cwd: string, o: GateOptions): Check[] {
549
865
 
550
866
  const POSITIONS = ["next", "current", "count"] as const;
551
867
 
552
- /** `<step>:<next|current|count>[:<since>]` → the counter it names, from the active run. */
868
+ /**
869
+ * `<step>:<next|current|count>[:all]` → the counter it names, from the active run, or
870
+ * from every run of the workflow with `:all`.
871
+ */
553
872
  function derivedCounter(
554
873
  file: string,
555
874
  workflow: string,
556
875
  spec: string,
557
- subPlan: number | undefined,
558
- since: string | undefined,
876
+ group: number | undefined,
559
877
  ): number {
560
- const [step, position, specSince] = spec.split(":");
561
- if (!step || !(POSITIONS as readonly string[]).includes(position ?? "")) {
562
- throw new CommandError(EXIT.USAGE, `"${spec}" must be <step>:<next|current|count>[:<since>]`);
878
+ const [step, position, scope] = spec.split(":");
879
+ if (
880
+ !step ||
881
+ !(POSITIONS as readonly string[]).includes(position ?? "") ||
882
+ (scope !== undefined && scope !== "all")
883
+ ) {
884
+ throw new CommandError(EXIT.USAGE, `"${spec}" must be <step>:<next|current|count>[:all]`);
563
885
  }
564
886
  const count = fs.existsSync(file)
565
- ? activeDoneSteps(readRuns(file), workflow, { step, subPlan }, specSince ?? since).length
887
+ ? (scope === "all" ? allRunsDoneSteps : activeDoneSteps)(readRuns(file), workflow, {
888
+ step,
889
+ group,
890
+ }).length
566
891
  : 0;
567
892
  if (position === "current" && count === 0) {
568
893
  throw new CommandError(
@@ -593,6 +918,115 @@ export function doneDescription(file: string): string {
593
918
  const DOCS_ONLY =
594
919
  /^docs\/plans\/|^docs\/(deferrals|decisions|failures)\.jsonl$|^\.bkit\/(friction|stats)\.jsonl$/;
595
920
 
921
+ /**
922
+ * Staged paths the tests step's commit may not carry: a modified or deleted file that is
923
+ * not a TEST FIRST file of the group's open tasks, one of `allowed` (the step's artifacts
924
+ * and the run's logs folder, as given) or a docs ledger; or an added file a CREATE line of
925
+ * the plan names. Stages everything first, as the commit would.
926
+ */
927
+ function sourceTouched(
928
+ cwd: string,
929
+ o: { plan: string; group: number; allowed: string[] },
930
+ ): string[] {
931
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
932
+ const rel = (p: string) => path.relative(top, path.resolve(cwd, p)).split(path.sep).join("/");
933
+ const planText = fs.existsSync(o.plan) ? fs.readFileSync(o.plan, "utf-8") : "";
934
+ const parsed = parsePlanBlocks(planText);
935
+ const done = new Set(parsed.tasks.filter((t) => t.done).map((t) => t.task));
936
+ const tests = new Set<string>();
937
+ for (const s of readTestFirst(planText, o.group))
938
+ if (s.kind === "test" && !done.has(s.task)) for (const t of s.tests) tests.add(t.test);
939
+ const created = new Set(parsed.tasks.flatMap((t) => t.create.map((c) => c.file)));
940
+ const allowed = o.allowed.map(rel);
941
+ const under = (p: string) => allowed.some((a) => p === a || p.startsWith(`${a}/`));
942
+ const own = (p: string) => tests.has(p) || under(p) || DOCS_ONLY.test(p);
943
+ addAllButCopied(cwd);
944
+ const out = runGit(cwd, ["diff", "--cached", "--name-status", "-z"]).stdout.split("\0");
945
+ const source: string[] = [];
946
+ for (let i = 0; i < out.length;) {
947
+ const status = out[i] ?? "";
948
+ if (status === "") break;
949
+ const two = status.startsWith("R") || status.startsWith("C");
950
+ const [a, b] = [out[i + 1] ?? "", two ? (out[i + 2] ?? "") : ""];
951
+ i += two ? 3 : 2;
952
+ const changed = status.startsWith("A") || status.startsWith("C") ? [] : [a];
953
+ const added = status.startsWith("A") ? [a] : two ? [b] : [];
954
+ for (const p of changed) if (!own(p)) source.push(p);
955
+ for (const p of added) if (created.has(p) && !tests.has(p)) source.push(p);
956
+ }
957
+ return [...new Set(source)].sort();
958
+ }
959
+
960
+ const escapeRegex = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
961
+
962
+ /**
963
+ * Saved artifacts of a later attempt than `attempt`, for each pattern whose file name
964
+ * holds `<attempt>`, matched with any number there. An artifact already committed at
965
+ * `startSha` (the active run's start) belongs to an earlier run, so it does not count.
966
+ */
967
+ function laterAttempts(
968
+ cwd: string,
969
+ patterns: string[],
970
+ attempt: number,
971
+ startSha: string | undefined,
972
+ ): string[] {
973
+ const later: Array<{ rel: string; n: number }> = [];
974
+ for (const p of patterns) {
975
+ const dir = path.dirname(p);
976
+ const base = path.basename(p);
977
+ if (isUrl(p) || !base.includes(ATTEMPT_TOKEN) || dir.includes(ATTEMPT_TOKEN)) continue;
978
+ const abs = path.resolve(cwd, dir);
979
+ if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
980
+ const shape = new RegExp(`^${base.split(ATTEMPT_TOKEN).map(escapeRegex).join("([0-9]+)")}$`);
981
+ for (const name of fs.readdirSync(abs)) {
982
+ const n = (shape.exec(name)?.slice(1) ?? []).map(Number);
983
+ if (n.length === 0 || n.some((x) => x !== n[0]) || n[0]! <= attempt) continue;
984
+ const rel = path.join(dir, name);
985
+ if (startSha !== undefined && runGit(cwd, ["cat-file", "-e", `${startSha}:./${rel}`]).ok)
986
+ continue;
987
+ if (!later.some((l) => l.rel === rel)) later.push({ rel, n: n[0]! });
988
+ }
989
+ }
990
+ return later.sort((a, b) => a.n - b.n || a.rel.localeCompare(b.rel)).map((l) => l.rel);
991
+ }
992
+
993
+ const isRecord = (v: unknown): v is Record<string, unknown> =>
994
+ v !== null && typeof v === "object" && !Array.isArray(v);
995
+
996
+ /** Dotted keys whose values differ between two `bkit.workflows` objects, sorted. */
997
+ export function changedKeys(a: unknown, b: unknown, at = ""): string[] {
998
+ if (isRecord(a) && isRecord(b))
999
+ return [...new Set([...Object.keys(a), ...Object.keys(b)])]
1000
+ .sort()
1001
+ .flatMap((k) => changedKeys(a[k], b[k], at === "" ? k : `${at}.${k}`));
1002
+ return JSON.stringify(a) === JSON.stringify(b) ? [] : [at === "" ? "bkit.workflows" : at];
1003
+ }
1004
+
1005
+ /**
1006
+ * The `bkit.workflows` keys the working tree's package.json changes from HEAD's (`git add -A`
1007
+ * commits the working tree). Empty when either side cannot be read as JSON.
1008
+ */
1009
+ /** True when the active shared-checkout record for `fid` holds `rel` as dirty before the run. */
1010
+ function recordedPath(cwd: string, fid: string | undefined, rel: string): boolean {
1011
+ const rec = fid === undefined ? null : activeRecord(cwd, fid);
1012
+ return rec !== null && rec.paths.some((p) => p.path === rel);
1013
+ }
1014
+
1015
+ function workflowsChange(cwd: string): string[] {
1016
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
1017
+ const file = path.join(top, "package.json");
1018
+ const head = runGit(top, ["cat-file", "-e", "HEAD:package.json"]).ok
1019
+ ? parseJson(runGit(top, ["show", "HEAD:package.json"]).stdout)
1020
+ : { ok: true as const, value: {} };
1021
+ const work = fs.existsSync(file)
1022
+ ? parseJson(fs.readFileSync(file, "utf-8"))
1023
+ : { ok: true as const, value: {} };
1024
+ if (!head.ok || !work.ok) return [];
1025
+ const workflows = (pkg: unknown) =>
1026
+ (isRecord(pkg) && isRecord(pkg.bkit) ? pkg.bkit.workflows : undefined) ?? {};
1027
+ return changedKeys(workflows(head.value), workflows(work.value));
1028
+ }
1029
+
596
1030
  /** `soakAttempt` → `Soak Attempt`, for a comment header. */
597
1031
  const titleCase = (key: string) =>
598
1032
  key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
@@ -603,13 +1037,12 @@ const fill = (s: string, attempt: number | undefined) =>
603
1037
 
604
1038
  const list = (v: FlagValue) => (v as string[] | undefined) ?? [];
605
1039
 
606
- function finish(ctx: RunContext): number {
1040
+ async function finish(ctx: RunContext): Promise<number> {
607
1041
  const f = ctx.flags;
608
1042
  const file = statusFile(ctx);
609
1043
  const workflow = String(f.workflow);
610
1044
  const step = String(f.step);
611
- const subPlan = positiveInt(f.subPlan, "sub-plan");
612
- const since = str(f.since);
1045
+ const group = positiveInt(f.group, "group");
613
1046
  const agents = list(f.agent);
614
1047
 
615
1048
  // Attempt: given, next from the log, or another step's counter.
@@ -618,10 +1051,10 @@ function finish(ctx: RunContext): number {
618
1051
  let attempt: number | undefined;
619
1052
  let derived = false;
620
1053
  if (f.attemptOf !== undefined) {
621
- attempt = derivedCounter(file, workflow, String(f.attemptOf), subPlan, since);
1054
+ attempt = derivedCounter(file, workflow, String(f.attemptOf), group);
622
1055
  derived = true;
623
1056
  } else if (f.attempt === "next") {
624
- attempt = derivedCounter(file, workflow, `${step}:next`, subPlan, since);
1057
+ attempt = derivedCounter(file, workflow, `${step}:next`, group);
625
1058
  derived = true;
626
1059
  } else {
627
1060
  attempt = nonNegativeInt(f.attempt, "attempt");
@@ -631,7 +1064,7 @@ function finish(ctx: RunContext): number {
631
1064
  const eq = spec.indexOf("=");
632
1065
  if (eq <= 0)
633
1066
  throw new CommandError(EXIT.USAGE, `--count-field "${spec}" must be key=<counter>`);
634
- extras[spec.slice(0, eq)] = derivedCounter(file, workflow, spec.slice(eq + 1), subPlan, since);
1067
+ extras[spec.slice(0, eq)] = derivedCounter(file, workflow, spec.slice(eq + 1), group);
635
1068
  }
636
1069
  const scope = str(f.scope);
637
1070
  if (scope !== undefined) extras.scope = scope;
@@ -679,6 +1112,8 @@ function finish(ctx: RunContext): number {
679
1112
  for (const [k, v] of Object.entries(read.fields)) {
680
1113
  if (k === "Verdict") continue;
681
1114
  if (k === "Failures") failures = (failures ?? 0) + Number(v);
1115
+ // A `true | false` field is true when any agent sets it: one reviewer's flag is never outvoted.
1116
+ else if (v === "true" && fields[k] === "false") fields[k] = v;
682
1117
  else if (!(k in fields)) fields[k] = v;
683
1118
  }
684
1119
  }
@@ -699,6 +1134,25 @@ function finish(ctx: RunContext): number {
699
1134
  if (strategy !== undefined && !STRATEGIES.includes(strategy))
700
1135
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
701
1136
  delete fields.Strategy;
1137
+ if (workflow === "build" && step === "build-challenge") {
1138
+ try {
1139
+ extras.challengeFindings = mergeFindings(
1140
+ artifacts
1141
+ .filter((a) => !isUrl(a))
1142
+ .map((a) =>
1143
+ parseFindings(fs.readFileSync(path.resolve(ctx.cwd, a), "utf-8"), a, ctx.cwd),
1144
+ ),
1145
+ new Set(),
1146
+ ).findings.map(({ severity, location, title }) => ({ severity, location, title }));
1147
+ } catch (error) {
1148
+ extras.challengeFindings = null;
1149
+ ctx.log(
1150
+ `challenge findings unavailable: ${String(error)}; the original verdict remains unresolved until the report is corrected`,
1151
+ );
1152
+ }
1153
+ }
1154
+ if (workflow === "debug" && step === "debug-failure-reproduce" && fields.Reproduced !== undefined)
1155
+ extras.reproduced = fields.Reproduced;
702
1156
 
703
1157
  const clampLog = str(f.clampLog);
704
1158
  if (clampLog !== undefined) {
@@ -710,6 +1164,63 @@ function finish(ctx: RunContext): number {
710
1164
  );
711
1165
  }
712
1166
 
1167
+ if (workflow === "debug" && step === "debug-run-tests") {
1168
+ const active = readRuns(file).at(-1);
1169
+ const rows = readStatusRows(file);
1170
+ const start =
1171
+ rows
1172
+ .map((r, i) => (r.type === "workflow-started" && r.workflow === "debug" ? i : -1))
1173
+ .filter((i) => i >= 0)
1174
+ .at(-1) ?? -1;
1175
+ const round = rows
1176
+ .slice(start + 1)
1177
+ .reverse()
1178
+ .find(
1179
+ (r) =>
1180
+ r.type === "test-run" &&
1181
+ r.workflow === workflow &&
1182
+ r.step === step &&
1183
+ r.attempt === attempt,
1184
+ );
1185
+ if (extras.source === "ci" || round?.source === "ci") {
1186
+ const matching =
1187
+ active?.workflow === "debug" &&
1188
+ active.status === "IN_PROGRESS" &&
1189
+ round &&
1190
+ ciRoundMatches(round, active.ciSelection, active.ciGeneration) &&
1191
+ extras.source === "ci" &&
1192
+ extras.ciGeneration === active.ciGeneration &&
1193
+ verdict === "FAIL" &&
1194
+ failures === undefined &&
1195
+ extras.scope === round.scope &&
1196
+ artifacts.includes(String(round.artifact));
1197
+ if (!matching)
1198
+ throw new CommandError(EXIT.USAGE, "CI evidence does not match the active selection");
1199
+ const text = fs.readFileSync(path.resolve(ctx.cwd, String(round.artifact)), "utf-8");
1200
+ const required = [
1201
+ "Verdict: FAIL",
1202
+ "Source: ci",
1203
+ `Scope: ${round.scope}`,
1204
+ `Repository: ${round.repo}`,
1205
+ `Workflow: ${round.workflowPath} (${round.workflowId})`,
1206
+ `Run: ${round.ciRun}`,
1207
+ `Run attempt: ${round.runAttempt}`,
1208
+ `CI generation: ${round.ciGeneration}`,
1209
+ `Commit: ${round.headSha}`,
1210
+ `URL: ${round.ciUrl}`,
1211
+ "The local gate was not run.",
1212
+ ];
1213
+ if (!required.every((line) => text.split(/\r?\n/).includes(line)))
1214
+ throw new CommandError(EXIT.USAGE, "CI evidence artifact identity mismatch");
1215
+ delete extras.clamped;
1216
+ } else if (
1217
+ (clampLog !== undefined || round !== undefined) &&
1218
+ (!Array.isArray(extras.clamped) || extras.clamped.length === 0)
1219
+ ) {
1220
+ throw new CommandError(EXIT.USAGE, "local test completion needs clamp evidence");
1221
+ }
1222
+ }
1223
+
713
1224
  // What the gate would refuse, refused before anything is written.
714
1225
  const pre: Check[] = gateChecks(ctx.cwd, {
715
1226
  workflow,
@@ -735,8 +1246,91 @@ function finish(ctx: RunContext): number {
735
1246
  const commit = str(f.commit) ?? "auto";
736
1247
  if (!["auto", "none"].includes(commit))
737
1248
  throw new CommandError(EXIT.USAGE, "--commit must be auto or none");
1249
+
1250
+ // A code step never edits a planned test case: each one's own lines must still be the
1251
+ // lines the group's tests step recorded at its red. Every other edit to the file is
1252
+ // ordinary code-step work the verifier reads in the diff.
1253
+ if (
1254
+ workflow === "build" &&
1255
+ (step === PLAN_TASKS_STEP || step === PLAN_REMEDIATE_STEP) &&
1256
+ group !== undefined
1257
+ ) {
1258
+ const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1259
+ const tests = touchedTests(top, file, workflow, group);
1260
+ if (tests.length > 0) {
1261
+ const touched = [...new Set(tests.map((t) => t.test))];
1262
+ const named = tests.map((t) => `\`${t.test}\` "${t.name}"`).join(", ");
1263
+ const problem = `${named} differ${tests.length === 1 ? "s" : ""} from what the group's tests step recorded at its red: a code step never edits a planned test case — put ${tests.length === 1 ? "that test" : "those tests"} back as the tests step left ${tests.length === 1 ? "it" : "them"} (other edits to the file stay), or log the task BLOCKED naming the test and what it gets wrong (nothing written)`;
1264
+ ctx.log(problem);
1265
+ recordTestLockFriction(top, step, named);
1266
+ ctx.emit({
1267
+ pass: false,
1268
+ reask: agents.length ? { agent: agents[0], artifact: artifacts[0] } : null,
1269
+ problem,
1270
+ touched,
1271
+ tests,
1272
+ });
1273
+ return EXIT_TESTS_TOUCHED;
1274
+ }
1275
+ }
1276
+
1277
+ // The tests step writes the group's tests: its commit may change those files, its own
1278
+ // artifacts and the run's logs only, and add files no CREATE line of the plan names.
1279
+ if (workflow === "build" && step === PLAN_TESTS_STEP && commit === "auto") {
1280
+ const planArg = str(f.plan);
1281
+ if (planArg === undefined)
1282
+ throw new CommandError(EXIT.USAGE, `--plan is required to finish ${PLAN_TESTS_STEP}`);
1283
+ if (group === undefined)
1284
+ throw new CommandError(EXIT.USAGE, `--group is required to finish ${PLAN_TESTS_STEP}`);
1285
+ const source = sourceTouched(ctx.cwd, {
1286
+ plan: path.resolve(ctx.cwd, planArg),
1287
+ group,
1288
+ allowed: [...artifacts, path.dirname(file)],
1289
+ });
1290
+ if (source.length > 0) {
1291
+ ctx.log(
1292
+ `the tests step changed ${source.join(", ")}: it writes the group's TEST FIRST files only — put the rest back (nothing written)`,
1293
+ );
1294
+ ctx.emit({ pass: false, source });
1295
+ return EXIT_SOURCE_TOUCHED;
1296
+ }
1297
+ }
1298
+
1299
+ // The attempt finished is the latest one this run saved artifacts for.
1300
+ if (attempt !== undefined) {
1301
+ const startSha = activeRunStart(file, workflow)?.parentSha;
1302
+ const later = laterAttempts(
1303
+ ctx.cwd,
1304
+ [...list(f.artifact), ...list(f.optionalArtifact)],
1305
+ attempt,
1306
+ typeof startSha === "string" && startSha !== "" ? startSha : undefined,
1307
+ );
1308
+ if (later.length > 0) {
1309
+ ctx.log(
1310
+ `attempt ${attempt} is not the latest: this run saved ${later.join(", ")} after it — finish the latest attempt (nothing written)`,
1311
+ );
1312
+ ctx.emit({ pass: false, attempt, later });
1313
+ return EXIT_LATER_ATTEMPT;
1314
+ }
1315
+ }
1316
+
1317
+ // A run never changes its own limits: the step commit may not carry a bkit.workflows edit.
1318
+ // With a shared-checkout record the commit carries the run's own paths only, so a
1319
+ // package.json that was already dirty when the run started stays out of it: a recorded
1320
+ // one the run then changed is refused as foreign by the commit itself.
1321
+ if (commit === "auto" && !recordedPath(ctx.cwd, fidOfStatusFile(file), "package.json")) {
1322
+ const changed = workflowsChange(ctx.cwd);
1323
+ if (changed.length > 0) {
1324
+ ctx.log(
1325
+ `the step's commit would change bkit.workflows in package.json (${changed.join(", ")}): restore HEAD's values, then finish again (nothing written)`,
1326
+ );
1327
+ ctx.emit({ pass: false, changed });
1328
+ return EXIT_WORKFLOWS_CHANGED;
1329
+ }
1330
+ }
1331
+
738
1332
  if (f.docsOnly === true && commit === "auto") {
739
- runGit(ctx.cwd, ["add", "-A"]);
1333
+ addAllButCopied(ctx.cwd);
740
1334
  const outside = runGit(ctx.cwd, ["diff", "--cached", "--name-only"])
741
1335
  .stdout.split("\n")
742
1336
  .filter((p) => p !== "" && !DOCS_ONLY.test(p));
@@ -760,53 +1354,20 @@ function finish(ctx: RunContext): number {
760
1354
  message += " bkit [verbose ci]";
761
1355
  }
762
1356
 
763
- const written = writeStepRow(
764
- ctx.cwd,
765
- {
766
- file,
767
- workflow,
768
- step,
769
- verdict,
770
- failures,
771
- attempt,
772
- subPlan,
773
- strategy,
774
- artifacts,
775
- extras,
776
- parentSha: str(f.parentSha),
777
- commit: commit as "auto" | "none",
778
- message,
779
- },
780
- ctx.log,
781
- );
782
- const checks = gateChecks(ctx.cwd, {
783
- file,
784
- workflow,
785
- step,
786
- subPlan,
787
- attempt,
788
- artifacts,
789
- verdictRequired: false,
790
- allowed,
791
- placeholders: [],
792
- });
793
-
794
1357
  // The step's tracker comment: header fields in one fixed order.
795
1358
  let comment: string | null = null;
796
1359
  const number = str(f.number);
797
1360
  if (number !== undefined) {
798
1361
  const title = str(f.title);
799
1362
  if (title === undefined) throw new CommandError(EXIT.USAGE, "--number needs --title");
800
- const count = str(f.subPlanCount);
1363
+ const count = str(f.groupCount);
801
1364
  const header: Array<[string, string]> = [
802
1365
  ...(verdict === undefined ? [] : [["Verdict", verdict] as [string, string]]),
803
1366
  ...(failures === undefined ? [] : [["Failures", String(failures)] as [string, string]]),
804
1367
  ...(scope === undefined ? [] : [["Scope", scope] as [string, string]]),
805
- ...(subPlan === undefined
1368
+ ...(group === undefined
806
1369
  ? []
807
- : [
808
- ["Sub-plan", `${subPlan}${count === undefined ? "" : `/${count}`}`] as [string, string],
809
- ]),
1370
+ : [["Group", `${group}${count === undefined ? "" : `/${count}`}`] as [string, string]]),
810
1371
  ...(derived && attempt !== undefined
811
1372
  ? [["Attempt", String(attempt)] as [string, string]]
812
1373
  : []),
@@ -841,6 +1402,53 @@ function finish(ctx: RunContext): number {
841
1402
  });
842
1403
  }
843
1404
 
1405
+ // --post: post, then record the engine-action row, then the step row and commit
1406
+ // carry both. A re-run with the same key and body is deduped, never posted twice.
1407
+ let tracker: TrackerOutcome | undefined;
1408
+ if (f.post === true) {
1409
+ if (comment === null) throw new CommandError(EXIT.USAGE, "--post needs --number");
1410
+ const key = actionKey(
1411
+ workflow,
1412
+ fs.existsSync(file) ? runNumber(readRuns(file), workflow) : 1,
1413
+ step,
1414
+ group,
1415
+ attempt,
1416
+ "comment",
1417
+ );
1418
+ tracker = await postForVerb(ctx, comment, { fid: fidOfStatusFile(file), file, key });
1419
+ }
1420
+
1421
+ const written = writeStepRow(
1422
+ ctx.cwd,
1423
+ {
1424
+ file,
1425
+ workflow,
1426
+ step,
1427
+ verdict,
1428
+ failures,
1429
+ attempt,
1430
+ group,
1431
+ strategy,
1432
+ artifacts,
1433
+ extras,
1434
+ parentSha: str(f.parentSha),
1435
+ commit: commit as "auto" | "none",
1436
+ message,
1437
+ },
1438
+ ctx.log,
1439
+ );
1440
+ const checks = gateChecks(ctx.cwd, {
1441
+ file,
1442
+ workflow,
1443
+ step,
1444
+ group,
1445
+ attempt,
1446
+ artifacts,
1447
+ verdictRequired: false,
1448
+ allowed,
1449
+ placeholders: [],
1450
+ });
1451
+
844
1452
  const pass = checks.every((c) => c.ok);
845
1453
  for (const c of checks.filter((x) => !x.ok)) ctx.log(`${c.check}: ${c.detail}`);
846
1454
  ctx.emit({
@@ -849,10 +1457,15 @@ function finish(ctx: RunContext): number {
849
1457
  attempt: attempt ?? null,
850
1458
  fields,
851
1459
  row: written.row,
1460
+ parentSha: written.row.parentSha,
852
1461
  commit: written.commit,
1462
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
853
1463
  pass,
854
1464
  checks,
855
1465
  comment,
1466
+ // Written after the step's commit, so the commit never carries it.
1467
+ commentFile: commentFileOf(ctx.cwd, comment),
1468
+ ...(tracker === undefined ? {} : { tracker }),
856
1469
  });
857
1470
  if (written.code !== EXIT.OK) return written.code;
858
1471
  return pass ? EXIT.OK : EXIT.NO;
@@ -882,7 +1495,11 @@ const COMMIT_FLAGS: FlagSpec[] = [
882
1495
  type: "string",
883
1496
  help: "commit the step started from (default: HEAD now, before this commit)",
884
1497
  },
885
- { name: "commit", type: "string", help: "auto (default: git add -A + commit) or none" },
1498
+ {
1499
+ name: "commit",
1500
+ type: "string",
1501
+ help: "auto (default: git add -A, never the worktree.copy entries, + commit) or none",
1502
+ },
886
1503
  { name: "message", type: "string", help: "commit message (required unless --commit=none)" },
887
1504
  ];
888
1505
 
@@ -893,6 +1510,7 @@ export const stepsCommand: CommandSpec = {
893
1510
  verbs: {
894
1511
  done: {
895
1512
  summary: "Append a step-done row and commit it (parentSha captured first).",
1513
+ use: "workflow",
896
1514
  flags: [
897
1515
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
898
1516
  WORKFLOW_FLAG,
@@ -914,7 +1532,7 @@ export const stepsCommand: CommandSpec = {
914
1532
  type: "string",
915
1533
  help: "non-negative integer (0 included), or `next` to derive it from the log",
916
1534
  },
917
- SUB_PLAN_FLAG,
1535
+ GROUP_FLAG,
918
1536
  { name: "strategy", type: "string", help: "STANDARD|PIVOT|FINAL" },
919
1537
  {
920
1538
  name: "artifact",
@@ -933,11 +1551,18 @@ export const stepsCommand: CommandSpec = {
933
1551
  output: {
934
1552
  row: "the appended step-done row",
935
1553
  commit: "the new commit's sha, or null with --commit=none",
1554
+ progressLine: "the exact chat progress line after a successful numbered completion",
936
1555
  },
1556
+ textOmit: ["row"],
937
1557
  exitCodes: {
938
1558
  [EXIT_NO_STATUS]: "--attempt=next could not read status.jsonl",
939
1559
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory",
940
- [EXIT_COMMIT]: "the row was written but the commit failed",
1560
+ [EXIT_COMMIT]:
1561
+ "nothing written, nothing committed: the commit failed and the row was rolled back",
1562
+ [EXIT_FOREIGN_PATH]:
1563
+ "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1564
+ [EXIT_NO_RECORD]:
1565
+ "a debug run on dev/main with no shared-checkout record: nothing written or committed",
941
1566
  },
942
1567
  run: (ctx) => {
943
1568
  const f = ctx.flags;
@@ -959,7 +1584,7 @@ export const stepsCommand: CommandSpec = {
959
1584
  if (strategy !== undefined && !STRATEGIES.includes(strategy)) {
960
1585
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
961
1586
  }
962
- const subPlan = positiveInt(f.subPlan, "sub-plan");
1587
+ const group = positiveInt(f.group, "group");
963
1588
  const commit = str(f.commit) ?? "auto";
964
1589
  if (!["auto", "none"].includes(commit))
965
1590
  throw new CommandError(EXIT.USAGE, "--commit must be auto or none");
@@ -970,7 +1595,7 @@ export const stepsCommand: CommandSpec = {
970
1595
 
971
1596
  const attempt =
972
1597
  f.attempt === "next"
973
- ? derivedCounter(file, workflow, `${step}:next`, subPlan, undefined)
1598
+ ? derivedCounter(file, workflow, `${step}:next`, group)
974
1599
  : nonNegativeInt(f.attempt, "attempt");
975
1600
 
976
1601
  const written = writeStepRow(
@@ -983,7 +1608,7 @@ export const stepsCommand: CommandSpec = {
983
1608
  verdict,
984
1609
  failures,
985
1610
  attempt,
986
- subPlan,
1611
+ group,
987
1612
  strategy,
988
1613
  artifacts,
989
1614
  extras: Object.fromEntries(list(f.field).map(extraField)),
@@ -993,13 +1618,18 @@ export const stepsCommand: CommandSpec = {
993
1618
  },
994
1619
  ctx.log,
995
1620
  );
996
- ctx.emit({ row: written.row, commit: written.commit });
1621
+ ctx.emit({
1622
+ row: written.row,
1623
+ commit: written.commit,
1624
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
1625
+ });
997
1626
  return written.code;
998
1627
  },
999
1628
  },
1000
1629
  finish: {
1001
1630
  summary:
1002
1631
  "End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment.",
1632
+ use: "workflow",
1003
1633
  flags: [
1004
1634
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
1005
1635
  WORKFLOW_FLAG,
@@ -1039,18 +1669,13 @@ export const stepsCommand: CommandSpec = {
1039
1669
  type: "string",
1040
1670
  help: "<step>:<next|current|count> — the attempt is that step's counter in the active run",
1041
1671
  },
1042
- {
1043
- name: "since",
1044
- type: "string",
1045
- help: "run field holding a timestamp (soakEntryAt); only rows after it count",
1046
- },
1047
1672
  {
1048
1673
  name: "count-field",
1049
1674
  type: "string",
1050
1675
  repeatable: true,
1051
- help: "key=<step>:<next|current|count>[:<since>] — a row field holding another counter",
1676
+ help: "key=<step>:<next|current|count>[:all] — a row field holding another counter; :all counts every run",
1052
1677
  },
1053
- SUB_PLAN_FLAG,
1678
+ GROUP_FLAG,
1054
1679
  {
1055
1680
  name: "strategy",
1056
1681
  type: "string",
@@ -1073,6 +1698,11 @@ export const stepsCommand: CommandSpec = {
1073
1698
  type: "boolean",
1074
1699
  help: "refuse (exit 9) when the step staged anything outside docs/plans/ and the docs ledgers",
1075
1700
  },
1701
+ {
1702
+ name: "plan",
1703
+ type: "string",
1704
+ help: `${PLAN_TESTS_STEP}: the plan file whose TEST FIRST lines bound the step's commit (required there with --commit=auto)`,
1705
+ },
1076
1706
  ...COMMIT_FLAGS.map((c) =>
1077
1707
  c.name === "message"
1078
1708
  ? {
@@ -1093,7 +1723,11 @@ export const stepsCommand: CommandSpec = {
1093
1723
  },
1094
1724
  { name: "number", type: "string", help: "step number: print the step's tracker comment" },
1095
1725
  { name: "title", type: "string", help: "step title for the comment heading" },
1096
- { name: "sub-plan-count", type: "string", help: "y of the comment's Sub-plan x/y" },
1726
+ {
1727
+ ...POST_FLAG,
1728
+ help: "post the comment (needs --number) to the issue the status file's FID names, before the row and commit; prints `tracker`",
1729
+ },
1730
+ { name: "group-count", type: "string", help: "y of the comment's Group x/y" },
1097
1731
  {
1098
1732
  name: "link-ref",
1099
1733
  type: "string",
@@ -1123,13 +1757,26 @@ export const stepsCommand: CommandSpec = {
1123
1757
  attempt: "the attempt recorded, or null",
1124
1758
  fields: "the other header fields the agents' prompts declare (Spike, Mode, Affected)",
1125
1759
  row: "the appended step-done row",
1760
+ parentSha: "the row's parentSha: HEAD before the step's commit",
1126
1761
  commit: "the new commit's sha, or null with --commit=none",
1127
1762
  pass: "every gate check passed",
1763
+ progressLine: "the exact chat progress line after a successful numbered completion",
1128
1764
  checks: "[{check, ok, detail}] per gate check",
1129
1765
  comment: "the step's tracker comment body (with --number), else null",
1130
- reask: "verdict read failed: {agent, artifact} to re-ask (exit 4 / 5 / 6 only)",
1131
- problem: "why the verdict read failed (exit 4 / 5 / 6 only)",
1766
+ commentFile: COMMENT_FILE_OUTPUT,
1767
+ tracker: TRACKER_OUTPUT,
1768
+ reask:
1769
+ "verdict read failed, or a planned test was touched: {agent, artifact} to re-ask (exit 4 / 5 / 6 / 11 only)",
1770
+ problem:
1771
+ "why the verdict read failed, or which planned tests the code step touched (exit 4 / 5 / 6 / 11 only)",
1772
+ touched:
1773
+ "planned test files of the group that differ from the blob its tests step recorded (exit 11 only)",
1774
+ source:
1775
+ "files the tests step's commit would change that are not the group's TEST FIRST files, or add although a CREATE line names them (exit 15 only)",
1776
+ later: "artifacts of a later attempt this run saved (exit 12 only)",
1777
+ changed: "bkit.workflows keys the commit would change, dotted (exit 13 only)",
1132
1778
  },
1779
+ textOmit: ["row", { key: "checks", when: (_checks, out) => out.pass === true }],
1133
1780
  exitCodes: {
1134
1781
  [EXIT_NO_STATUS]: "status.jsonl is not valid NDJSON",
1135
1782
  [EXIT_EMPTY]: "an --agent's artifact is missing or empty (nothing written)",
@@ -1139,14 +1786,28 @@ export const stepsCommand: CommandSpec = {
1139
1786
  "an --agent's header is invalid (no verdict:end, a value outside its set, Failures disagreeing with Verdict) — re-ask it (nothing written)",
1140
1787
  [EXIT_ARTIFACT]:
1141
1788
  "an --artifact is missing, empty, or outside the working directory (nothing written)",
1142
- [EXIT_COMMIT]: "the row was written but the commit failed",
1789
+ [EXIT_COMMIT]:
1790
+ "nothing written, nothing committed: the commit failed and the row was rolled back",
1791
+ [EXIT_FOREIGN_PATH]:
1792
+ "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1793
+ [EXIT_NO_RECORD]:
1794
+ "a debug run on dev/main with no shared-checkout record: nothing written or committed",
1143
1795
  [EXIT_OUTSIDE_DOCS]:
1144
1796
  "--docs-only and the step staged a file outside the artifact tree (nothing written)",
1797
+ [EXIT_TESTS_TOUCHED]:
1798
+ "build plan-execute / plan-gaps-remediate: a planned test case of the group differs from the lines its tests step recorded in status.jsonl (`tests`: [{test, name}]; `touched`: their files) — re-ask `reask.agent` to put that test back or log the task BLOCKED; other edits to the file stay (nothing written; an agent-rework friction row is appended)",
1799
+ [EXIT_LATER_ATTEMPT]:
1800
+ "this run saved an artifact of a later attempt (`later`) than the one finished (nothing written)",
1801
+ [EXIT_WORKFLOWS_CHANGED]:
1802
+ "the commit would change bkit.workflows in package.json (`changed` names the keys) (nothing written)",
1803
+ [EXIT_SOURCE_TOUCHED]:
1804
+ "build plan-tests: the tests step changed a file no TEST FIRST line of the group's open tasks names, or added one a CREATE line of the plan names (`source`) (nothing written)",
1145
1805
  },
1146
1806
  run: finish,
1147
1807
  },
1148
1808
  verdict: {
1149
1809
  summary: "Read an artifact's header down to <!-- verdict:end -->.",
1810
+ use: "by-hand",
1150
1811
  flags: [
1151
1812
  { name: "file", type: "string", required: true, help: "the subagent's artifact" },
1152
1813
  ...ALLOWED_FLAGS,
@@ -1181,6 +1842,7 @@ export const stepsCommand: CommandSpec = {
1181
1842
  gate: {
1182
1843
  summary:
1183
1844
  "Mechanical gate checks for one step: placeholders, FID, lock, artifacts, verdict, status row (with its attempt / strategy / scope where the step writes them).",
1845
+ use: "workflow",
1184
1846
  flags: [
1185
1847
  {
1186
1848
  ...FILE_FLAG,
@@ -1194,7 +1856,12 @@ export const stepsCommand: CommandSpec = {
1194
1856
  },
1195
1857
  WORKFLOW_FLAG,
1196
1858
  STEP_FLAG,
1197
- SUB_PLAN_FLAG,
1859
+ GROUP_FLAG,
1860
+ {
1861
+ name: "progress-number",
1862
+ type: "string",
1863
+ help: "render this completed numbered position without writing a status row",
1864
+ },
1198
1865
  {
1199
1866
  name: "attempt",
1200
1867
  type: "string",
@@ -1224,6 +1891,11 @@ export const stepsCommand: CommandSpec = {
1224
1891
  help: "NAME=value — the held placeholder must be non-empty",
1225
1892
  },
1226
1893
  { name: "fid", type: "string", help: "the FID must match the wired tracker's shape" },
1894
+ {
1895
+ name: "issue",
1896
+ type: "string",
1897
+ help: 'the run\'s issue id, or "" for a run with no issue (then the FID must be issue-less); needs --fid',
1898
+ },
1227
1899
  { name: "month", type: "string", help: "month bucket of the lock (with --token)" },
1228
1900
  {
1229
1901
  name: "token",
@@ -1231,7 +1903,11 @@ export const stepsCommand: CommandSpec = {
1231
1903
  help: "the workflow lock must be held with this token (needs --fid)",
1232
1904
  },
1233
1905
  ],
1234
- output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1906
+ output: {
1907
+ pass: "true when every check passed",
1908
+ checks: "[{check, ok, detail}] per check",
1909
+ progressLine: "with --progress-number: the exact chat progress line after the gate passes",
1910
+ },
1235
1911
  exitCodes: {
1236
1912
  [EXIT_NO_STATUS]:
1237
1913
  "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
@@ -1240,7 +1916,38 @@ export const stepsCommand: CommandSpec = {
1240
1916
  const f = ctx.flags;
1241
1917
  const file = str(f.file) === undefined ? undefined : statusFile(ctx);
1242
1918
  const workflow = String(f.workflow);
1243
- const subPlan = positiveInt(f.subPlan, "sub-plan");
1919
+ const group = positiveInt(f.group, "group");
1920
+ const progressNumber = positiveInt(f.progressNumber, "progress-number");
1921
+ if (
1922
+ progressNumber !== undefined &&
1923
+ (!isResumable(workflow) ||
1924
+ !WORKFLOW_STEPS[workflow].some((s) => s.number === progressNumber))
1925
+ )
1926
+ throw new CommandError(EXIT.USAGE, "--progress-number is not a workflow step");
1927
+ if (progressNumber !== undefined && isResumable(workflow)) {
1928
+ const step = String(f.step);
1929
+ const recordedNumber = WORKFLOW_STEPS[workflow].find((s) => s.step === step)?.number;
1930
+ const gateNumber =
1931
+ workflow === "ship" &&
1932
+ (step === "ship-worktree-setup" || step === "ship-regression-guard")
1933
+ ? 3
1934
+ : workflow === "ship" && step === "ship-bookkeeping-push"
1935
+ ? 9
1936
+ : recordedNumber;
1937
+ if (progressNumber !== recordedNumber && progressNumber !== gateNumber)
1938
+ throw new CommandError(EXIT.USAGE, "--progress-number does not match the gated step");
1939
+ if (
1940
+ file === undefined &&
1941
+ (progressNumber !== 1 ||
1942
+ !str(f.fid) ||
1943
+ !/^[0-9]{6}$/.test(str(f.month) ?? "") ||
1944
+ !str(f.token))
1945
+ )
1946
+ throw new CommandError(
1947
+ EXIT.USAGE,
1948
+ "gate progress needs --file, or Step 1 with --fid, --month and --token",
1949
+ );
1950
+ }
1244
1951
  if (f.attempt !== undefined && f.attemptOf !== undefined)
1245
1952
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1246
1953
  if (f.attemptOf !== undefined && file === undefined)
@@ -1255,32 +1962,61 @@ export const stepsCommand: CommandSpec = {
1255
1962
  );
1256
1963
  const attempt =
1257
1964
  f.attemptOf !== undefined
1258
- ? derivedCounter(file!, workflow, String(f.attemptOf), subPlan, undefined)
1965
+ ? derivedCounter(file!, workflow, String(f.attemptOf), group)
1259
1966
  : nonNegativeInt(f.attempt, "attempt");
1260
1967
  const checks = gateChecks(ctx.cwd, {
1261
1968
  file,
1262
1969
  ref,
1263
1970
  workflow,
1264
1971
  step: String(f.step),
1265
- subPlan,
1972
+ group,
1266
1973
  attempt,
1267
1974
  artifacts: list(f.artifact).map((a) => fill(a, attempt)),
1268
1975
  verdictRequired: f.verdictRequired === true,
1269
1976
  allowed: allowedVerdicts(f),
1270
1977
  fid: str(f.fid),
1978
+ issue: str(f.issue),
1271
1979
  month: str(f.month),
1272
1980
  token: str(f.token),
1273
1981
  placeholders: list(f.placeholder),
1274
1982
  });
1275
1983
  const pass = checks.every((c) => c.ok);
1276
1984
  for (const c of checks.filter((x) => !x.ok)) ctx.log(`${c.check}: ${c.detail}`);
1277
- ctx.emit({ pass, checks });
1985
+ const progressFile =
1986
+ file ??
1987
+ path.resolve(
1988
+ ctx.cwd,
1989
+ "docs",
1990
+ "plans",
1991
+ str(f.month) ?? "",
1992
+ "logs",
1993
+ str(f.fid) ?? "",
1994
+ "status.jsonl",
1995
+ );
1996
+ const progressLine =
1997
+ pass && progressNumber !== undefined
1998
+ ? stepProgress(
1999
+ ctx.cwd,
2000
+ {
2001
+ file: progressFile,
2002
+ workflow,
2003
+ step: String(f.step),
2004
+ group,
2005
+ attempt,
2006
+ artifacts: [],
2007
+ commit: "none",
2008
+ },
2009
+ progressNumber,
2010
+ )
2011
+ : undefined;
2012
+ ctx.emit({ pass, checks, ...(progressLine === undefined ? {} : { progressLine }) });
1278
2013
  return pass ? EXIT.OK : EXIT.NO;
1279
2014
  },
1280
2015
  },
1281
2016
  stub: {
1282
2017
  summary:
1283
2018
  "Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top.",
2019
+ use: "workflow",
1284
2020
  flags: [
1285
2021
  { name: "from", type: "string", required: true, help: "the prior versioned artifact" },
1286
2022
  { name: "to", type: "string", required: true, help: "the artifact to create" },