@cbartens/bkit 6.0.0 → 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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -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 +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  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 +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -11,18 +11,50 @@
11
11
  // and print the step's tracker comment.
12
12
  import * as fs from "node:fs";
13
13
  import * as path from "node:path";
14
- import { actionKey, activeDoneSteps, allRunsDoneSteps, appendLine, runNumber, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
14
+ import { actionKey, activeDoneSteps, allRunsDoneSteps, appendLine, ciRoundMatches, runNumber, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
15
15
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
16
+ import { appendFrictionRow, frictionRow, journalEnabled } from "../../ledgers/journal.js";
16
17
  import { resolveRepoSlug } from "../../ledgers/telemetry.js";
17
18
  import { getPromptsRoot } from "../../shared/package-roots.js";
18
- import { CommandError, EXIT, git, isSharedBranch, repoRoot, runGit, } from "../lib.js";
19
+ import { readTextFile } from "../../shared/json.js";
20
+ import { CommandError, EXIT, git, isSharedBranch, parseJson, repoRoot, runGit, } from "../lib.js";
21
+ import { activeRunStart, savedPointLimit } from "./counters.js";
22
+ import { isResumable, runProgress, WORKFLOW_STEPS } from "./step-table.js";
23
+ import { planFiles } from "./run-facts.js";
24
+ import { mergeFindings, parseFindings } from "./challenge.js";
19
25
  import { fidProblem, normaliseFid, readIssueTracker } from "./fids.js";
20
26
  import { buildComment } from "./issues.js";
21
27
  import { EXIT_FOREIGN_PATH, activeRecord, ownPathCommit, ownSet, } from "./ledgers.js";
22
28
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
23
- import { EXIT_NO_STATUS, FILE_FLAG, GROUP_FLAG, STEP_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readRunsAt, statusFile, str, } from "./status.js";
29
+ import { EXIT_NO_STATUS, FILE_FLAG, GROUP_FLAG, STEP_FLAG, WORKFLOW_FLAG, extraField, nonNegativeInt, positiveInt, readRuns, readStatusRows, readRunsAt, statusFile, str, } from "./status.js";
24
30
  import { COMMENT_FILE_OUTPUT, POST_FLAG, TRACKER_OUTPUT, commentFileOf, postForVerb, } from "./tracker.js";
31
+ import { parsePlanBlocks } from "./plan-blocks.js";
32
+ import { PLAN_TASKS_STEP, readTestFirst, touchedTests } from "./tests.js";
25
33
  import { addAllButCopied } from "./worktrees.js";
34
+ /**
35
+ * An `agent-rework` friction row for a refused planned-test edit: the step reruns, so
36
+ * `bkit stats` counts it. Best effort — a ledger that cannot be written never changes
37
+ * the refusal.
38
+ */
39
+ function recordTestLockFriction(top, step, named) {
40
+ if (!journalEnabled())
41
+ return;
42
+ const row = frictionRow({
43
+ workflow: "build",
44
+ step,
45
+ noun: "steps",
46
+ verb: "finish",
47
+ code: EXIT_TESTS_TOUCHED,
48
+ bookRoot: top,
49
+ parentSha: git(top, ["rev-parse", "HEAD"]) ?? undefined,
50
+ });
51
+ row["category"] = "agent-rework";
52
+ row["severity"] = "LOW";
53
+ row["summary"] = "a code step edited a planned test case";
54
+ row["description"] =
55
+ `\`bkit steps finish\` refused ${step} with exit ${EXIT_TESTS_TOUCHED}: ${named} changed after the group's red; the step reruns.`;
56
+ appendFrictionRow(top, row);
57
+ }
26
58
  const VERDICT_END = "<!-- verdict:end -->";
27
59
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
28
60
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
@@ -34,6 +66,18 @@ export const EXIT_ARTIFACT = 7;
34
66
  export const EXIT_COMMIT = 8;
35
67
  /** finish --docs-only: the step staged a file outside the artifact tree. */
36
68
  export const EXIT_OUTSIDE_DOCS = 9;
69
+ /** finish (build plan-execute / plan-gaps-remediate): a planned test case differs from the lines the group's tests step recorded. */
70
+ export const EXIT_TESTS_TOUCHED = 11;
71
+ /** finish: a saved artifact holds a later attempt than the one finished. */
72
+ export const EXIT_LATER_ATTEMPT = 12;
73
+ /** finish: the step's commit would change `bkit.workflows` in package.json. */
74
+ export const EXIT_WORKFLOWS_CHANGED = 13;
75
+ /** finish (build plan-tests): the tests step's commit changes a file that is not one of the group's planned tests. */
76
+ export const EXIT_SOURCE_TOUCHED = 15;
77
+ /** The step whose subagent writes the group's TEST FIRST tests, before any task code. */
78
+ export const PLAN_TESTS_STEP = "build-plan-tests";
79
+ /** The step whose subagent closes the group's verification gaps: a code step, like plan-execute. */
80
+ export const PLAN_REMEDIATE_STEP = "build-plan-gaps-remediate";
37
81
  /** Where `finish` puts the derived attempt in `--artifact` / `--message` / `--clamp-log`. */
38
82
  export const ATTEMPT_TOKEN = "<attempt>";
39
83
  /** Where `finish` puts the first `DONE` line's description in `--message`. */
@@ -227,7 +271,8 @@ export const ROW_FIELDS = {
227
271
  "build/build-plan-convert": ["attempt"],
228
272
  "build/build-plan-current": ["attempt"],
229
273
  "build/build-install-skills": ["attempt"],
230
- "build/build-plan-execute": ["attempt"],
274
+ "build/build-plan-tests": ["attempt"],
275
+ "build/build-plan-tasks": ["attempt"],
231
276
  "build/build-plan-verify": ["attempt"],
232
277
  "build/build-group-gate": ["attempt", "scope"],
233
278
  "build/build-plan-gaps-remediate": ["attempt", "strategy"],
@@ -276,6 +321,81 @@ const CORE_ROW_KEYS = new Set([
276
321
  function fidOfStatusFile(file) {
277
322
  return /(?:^|\/)docs\/plans\/[0-9]{6}\/logs\/([^/]+)\/status\.jsonl$/.exec(file.split(path.sep).join("/"))?.[1];
278
323
  }
324
+ /** Loop budgets use the same point names as the workflow counter routes. */
325
+ function progressPoint(workflow, step, soak) {
326
+ if (workflow === "build") {
327
+ if (["build-plan-verify", "build-group-gate", "build-plan-gaps-remediate"].includes(step))
328
+ return "build.verify";
329
+ if (step === "build-challenge")
330
+ return "build.challenge";
331
+ if (["build-run-tests", "build-failure-diagnose", "build-failure-remediate"].includes(step))
332
+ return "build.tests";
333
+ }
334
+ if (workflow === "debug") {
335
+ if (step === "debug-failure-soak" || soak)
336
+ return "debug.soak";
337
+ if (["debug-run-tests", "debug-failure-diagnose", "debug-failure-remediate"].includes(step))
338
+ return "debug.fix";
339
+ }
340
+ if (workflow === "ship" &&
341
+ ["ship-merge-pr", "ship-failure-diagnose", "ship-failure-remediate"].includes(step))
342
+ return "ship.merge";
343
+ return undefined;
344
+ }
345
+ /** Prepare output before a completion mutates the log; progress is never persisted. */
346
+ function stepProgress(cwd, r, number) {
347
+ if (r.status === "FAILED" || !isResumable(r.workflow))
348
+ return undefined;
349
+ const entry = WORKFLOW_STEPS[r.workflow].find((s) => number === undefined ? s.step === r.step : s.number === number);
350
+ if (entry === undefined) {
351
+ if (number !== undefined)
352
+ throw new CommandError(EXIT.USAGE, "--progress-number is not a workflow step");
353
+ return undefined;
354
+ }
355
+ if (fs.existsSync(r.file) && !readTextFile(r.file).ok)
356
+ throw new CommandError(EXIT_NO_STATUS, `${r.file} is unreadable`);
357
+ const runs = fs.existsSync(r.file) ? readRuns(r.file) : [];
358
+ const run = runs.filter((item) => item.workflow === r.workflow).at(-1);
359
+ const abs = path.resolve(cwd, r.file);
360
+ const canonical = /^(.*)\/docs\/plans\/([0-9]{6})\/logs\/([^/]+)\/status\.jsonl$/.exec(abs.split(path.sep).join("/"));
361
+ let groups = [];
362
+ if (r.workflow === "build" && canonical !== null) {
363
+ const [file] = planFiles(canonical[1], canonical[2], canonical[3]);
364
+ if (file !== undefined) {
365
+ const text = readTextFile(file);
366
+ if (!text.ok)
367
+ throw new CommandError(EXIT.USAGE, `progress plan ${file} is unreadable`);
368
+ const plan = parsePlanBlocks(text.text);
369
+ if (plan.errors.length > 0 || plan.fenceOpen !== undefined)
370
+ throw new CommandError(EXIT.USAGE, `invalid progress plan: ${plan.errors.map((e) => e.message).join("; ") || "unclosed code fence"}`);
371
+ groups = plan.groups.map((g) => g.group);
372
+ }
373
+ }
374
+ const prior = run?.steps.filter((s) => s.status === "DONE") ?? [];
375
+ const same = prior.filter((s) => s.step === r.step && (r.group === undefined || s.group === r.group));
376
+ const soak = runOrStepField(runs, r.workflow, "debugMode") === "SOAK";
377
+ const point = progressPoint(r.workflow, r.step, soak);
378
+ const soakAttempt = Number(r.extras?.soakAttempt ?? runOrStepField(runs, r.workflow, "soakAttempt"));
379
+ const challengeRound = Number(r.extras?.round ?? runOrStepField(runs, r.workflow, "round"));
380
+ const attempt = point === "debug.soak" && Number.isSafeInteger(soakAttempt) && soakAttempt > 0
381
+ ? soakAttempt
382
+ : point === "debug.fix" && r.step === "debug-failure-remediate"
383
+ ? allRunsDoneSteps(runs, r.workflow, { step: r.step }).length + 1
384
+ : point === "build.challenge" && Number.isSafeInteger(challengeRound) && challengeRound > 0
385
+ ? challengeRound
386
+ : (r.attempt ?? same.at(-1)?.attempt);
387
+ return runProgress({
388
+ workflow: r.workflow,
389
+ step: r.step,
390
+ number,
391
+ groups,
392
+ group: r.group,
393
+ attempt,
394
+ max: point === undefined
395
+ ? undefined
396
+ : savedPointLimit(r.file, r.workflow, point, r.group, point === "debug.fix" || point === "debug.soak"),
397
+ }).progressLine;
398
+ }
279
399
  /** Exit code: a debug run on a shared branch has no shared-checkout record, so nothing was written or committed. */
280
400
  export const EXIT_NO_RECORD = 14;
281
401
  /**
@@ -291,10 +411,47 @@ export function requireRecordOnShared(cwd, workflow, rec) {
291
411
  return;
292
412
  throw new CommandError(EXIT_NO_RECORD, `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`);
293
413
  }
414
+ /** Throws EXIT_COMMIT when git cannot name the index, before anything is written. */
415
+ function indexSnapshot(cwd) {
416
+ const res = runGit(cwd, ["rev-parse", "--path-format=absolute", "--git-path", "index"]);
417
+ if (!res.ok || res.stdout === "")
418
+ throw new CommandError(EXIT_COMMIT, `nothing written: git cannot name the index: ${res.stderr}`);
419
+ return {
420
+ file: res.stdout,
421
+ bytes: fs.existsSync(res.stdout) ? fs.readFileSync(res.stdout) : null,
422
+ };
423
+ }
424
+ /**
425
+ * Put the index back byte-for-byte as `snap` holds it, through git's own `index.lock`, so
426
+ * a git command holding the lock is never overwritten. A refused commit wrote nothing, so
427
+ * every path — staged before the attempt or by it, fully or partly — must read as it did:
428
+ * a row left staged rides the next pathspec-less commit. Returns why it could not, or null.
429
+ */
430
+ function restoreIndex(snap) {
431
+ const lock = `${snap.file}.lock`;
432
+ try {
433
+ fs.writeFileSync(lock, snap.bytes ?? "", { flag: "wx" });
434
+ }
435
+ catch (err) {
436
+ if (err.code !== "EEXIST")
437
+ fs.rmSync(lock, { force: true });
438
+ return `${lock} could not be taken: ${err.message}`;
439
+ }
440
+ if (snap.bytes !== null) {
441
+ fs.renameSync(lock, snap.file);
442
+ return null;
443
+ }
444
+ fs.rmSync(snap.file, { force: true });
445
+ fs.rmSync(lock, { force: true });
446
+ return null;
447
+ }
294
448
  /**
295
449
  * Append one `step-done` row, then commit (parentSha first, the row, then the
296
450
  * commit — the order the fold's de-dup relies on). Returns the row and the new
297
- * commit; `code` is EXIT_COMMIT when the row landed but the commit failed.
451
+ * commit; `code` is EXIT_COMMIT when the commit failed, and the appended row is
452
+ * rolled back, so a re-run after the human's fix writes the same attempt once.
453
+ * `code` is EXIT.NEEDS_HUMAN when the commit failed and the row stays in `r.file`
454
+ * (another writer appended after it) or the index could not be put back.
298
455
  */
299
456
  export function writeStepRow(cwd, r, log) {
300
457
  const clash = Object.keys(r.extras ?? {}).filter((k) => CORE_ROW_KEYS.has(k));
@@ -320,6 +477,7 @@ export function writeStepRow(cwd, r, log) {
320
477
  ...(r.strategy === undefined ? {} : { strategy: r.strategy }),
321
478
  ...(r.extras ?? {}),
322
479
  };
480
+ const progressLine = stepProgress(cwd, r);
323
481
  // An in-place run on a shared branch commits its own paths only; a refusal
324
482
  // comes before the append, so a re-run after the human's fix writes the row once.
325
483
  const fid = r.commit === "auto" ? fidOfStatusFile(r.file) : undefined;
@@ -337,10 +495,58 @@ export function writeStepRow(cwd, r, log) {
337
495
  return { row, commit: null, code: EXIT_FOREIGN_PATH };
338
496
  }
339
497
  }
498
+ // A plain commit stages the whole tree, so the index is kept to be put back on failure.
499
+ const snap = r.commit === "auto" && rec === null ? indexSnapshot(cwd) : null;
340
500
  fs.mkdirSync(path.dirname(r.file), { recursive: true });
341
- fs.appendFileSync(r.file, appendLine(row));
501
+ const existed = fs.existsSync(r.file);
502
+ const line = appendLine(row);
503
+ fs.appendFileSync(r.file, line);
504
+ // A refused commit takes exactly this attempt's bytes back off `r.file`, so the step's
505
+ // attempt is unchanged and a re-run after the human's fix lands the same attempt once.
506
+ // Returns null once the row is off disk (or the file is gone), else why it stays.
507
+ const rollback = () => {
508
+ if (!fs.existsSync(r.file))
509
+ return null;
510
+ let body;
511
+ try {
512
+ body = fs.readFileSync(r.file);
513
+ }
514
+ catch (err) {
515
+ return `it could not be read back: ${err.message}`;
516
+ }
517
+ const mine = Buffer.from(line);
518
+ const tail = body.subarray(Math.max(0, body.length - mine.length));
519
+ if (!tail.equals(mine))
520
+ return "another writer appended to it after this attempt's row";
521
+ if (!existed && body.length === mine.length)
522
+ fs.rmSync(r.file, { force: true });
523
+ else
524
+ fs.truncateSync(r.file, body.length - mine.length);
525
+ return null;
526
+ };
527
+ // The failure reason first, then the index and the file are put back: exit `code` means
528
+ // nothing written, nothing committed; a row that cannot come off disk needs a human, as a
529
+ // re-run would write it twice.
530
+ const failed = (code, reason) => {
531
+ log(reason);
532
+ const index = snap === null ? null : restoreIndex(snap);
533
+ if (index !== null)
534
+ log(`the index could not be put back as it was: ${index}`);
535
+ const kept = rollback();
536
+ if (kept !== null) {
537
+ log(`the step-done row stays in ${r.file}: ${kept}; nothing committed — remove that row before re-running`);
538
+ return { row, commit: null, code: EXIT.NEEDS_HUMAN };
539
+ }
540
+ log(`no row written to ${r.file}: the row was rolled back`);
541
+ return { row, commit: null, code: index === null ? code : EXIT.NEEDS_HUMAN };
542
+ };
342
543
  if (r.commit === "none")
343
- return { row, commit: null, code: EXIT.OK };
544
+ return {
545
+ row,
546
+ commit: null,
547
+ code: EXIT.OK,
548
+ ...(progressLine === undefined ? {} : { progressLine }),
549
+ };
344
550
  if (rec !== null) {
345
551
  let own;
346
552
  try {
@@ -349,22 +555,27 @@ export function writeStepRow(cwd, r, log) {
349
555
  catch (err) {
350
556
  if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH)
351
557
  throw err;
352
- log(`row written to ${r.file} but the commit was refused: ${err.message}`);
353
- return { row, commit: null, code: EXIT_FOREIGN_PATH };
354
- }
355
- if (!own.ok) {
356
- log(`row written to ${r.file} but the commit failed: ${own.error}`);
357
- return { row, commit: null, code: EXIT_COMMIT };
558
+ return failed(EXIT_FOREIGN_PATH, `the commit was refused: ${err.message}`);
358
559
  }
359
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
560
+ if (!own.ok)
561
+ return failed(EXIT_COMMIT, `the commit failed: ${own.error}`);
562
+ return {
563
+ row,
564
+ commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout,
565
+ code: EXIT.OK,
566
+ ...(progressLine === undefined ? {} : { progressLine }),
567
+ };
360
568
  }
361
569
  const add = addAllButCopied(cwd);
362
570
  const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message]) : add;
363
- if (!made.ok) {
364
- log(`row written to ${r.file} but the commit failed: ${made.stderr || made.stdout}`);
365
- return { row, commit: null, code: EXIT_COMMIT };
366
- }
367
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
571
+ if (!made.ok)
572
+ return failed(EXIT_COMMIT, `the commit failed: ${made.stderr || made.stdout}`);
573
+ return {
574
+ row,
575
+ commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout,
576
+ code: EXIT.OK,
577
+ ...(progressLine === undefined ? {} : { progressLine }),
578
+ };
368
579
  }
369
580
  /** Every mechanical gate check for one step; `ok` false names the first problem per check. */
370
581
  function gateChecks(cwd, o) {
@@ -496,6 +707,110 @@ export function doneDescription(file) {
496
707
  }
497
708
  /** Staged paths a docs-only step may not touch: anything outside the artifact tree and its ledgers. */
498
709
  const DOCS_ONLY = /^docs\/plans\/|^docs\/(deferrals|decisions|failures)\.jsonl$|^\.bkit\/(friction|stats)\.jsonl$/;
710
+ /**
711
+ * Staged paths the tests step's commit may not carry: a modified or deleted file that is
712
+ * not a TEST FIRST file of the group's open tasks, one of `allowed` (the step's artifacts
713
+ * and the run's logs folder, as given) or a docs ledger; or an added file a CREATE line of
714
+ * the plan names. Stages everything first, as the commit would.
715
+ */
716
+ function sourceTouched(cwd, o) {
717
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
718
+ const rel = (p) => path.relative(top, path.resolve(cwd, p)).split(path.sep).join("/");
719
+ const planText = fs.existsSync(o.plan) ? fs.readFileSync(o.plan, "utf-8") : "";
720
+ const parsed = parsePlanBlocks(planText);
721
+ const done = new Set(parsed.tasks.filter((t) => t.done).map((t) => t.task));
722
+ const tests = new Set();
723
+ for (const s of readTestFirst(planText, o.group))
724
+ if (s.kind === "test" && !done.has(s.task))
725
+ for (const t of s.tests)
726
+ tests.add(t.test);
727
+ const created = new Set(parsed.tasks.flatMap((t) => t.create.map((c) => c.file)));
728
+ const allowed = o.allowed.map(rel);
729
+ const under = (p) => allowed.some((a) => p === a || p.startsWith(`${a}/`));
730
+ const own = (p) => tests.has(p) || under(p) || DOCS_ONLY.test(p);
731
+ addAllButCopied(cwd);
732
+ const out = runGit(cwd, ["diff", "--cached", "--name-status", "-z"]).stdout.split("\0");
733
+ const source = [];
734
+ for (let i = 0; i < out.length;) {
735
+ const status = out[i] ?? "";
736
+ if (status === "")
737
+ break;
738
+ const two = status.startsWith("R") || status.startsWith("C");
739
+ const [a, b] = [out[i + 1] ?? "", two ? (out[i + 2] ?? "") : ""];
740
+ i += two ? 3 : 2;
741
+ const changed = status.startsWith("A") || status.startsWith("C") ? [] : [a];
742
+ const added = status.startsWith("A") ? [a] : two ? [b] : [];
743
+ for (const p of changed)
744
+ if (!own(p))
745
+ source.push(p);
746
+ for (const p of added)
747
+ if (created.has(p) && !tests.has(p))
748
+ source.push(p);
749
+ }
750
+ return [...new Set(source)].sort();
751
+ }
752
+ const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
753
+ /**
754
+ * Saved artifacts of a later attempt than `attempt`, for each pattern whose file name
755
+ * holds `<attempt>`, matched with any number there. An artifact already committed at
756
+ * `startSha` (the active run's start) belongs to an earlier run, so it does not count.
757
+ */
758
+ function laterAttempts(cwd, patterns, attempt, startSha) {
759
+ const later = [];
760
+ for (const p of patterns) {
761
+ const dir = path.dirname(p);
762
+ const base = path.basename(p);
763
+ if (isUrl(p) || !base.includes(ATTEMPT_TOKEN) || dir.includes(ATTEMPT_TOKEN))
764
+ continue;
765
+ const abs = path.resolve(cwd, dir);
766
+ if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
767
+ continue;
768
+ const shape = new RegExp(`^${base.split(ATTEMPT_TOKEN).map(escapeRegex).join("([0-9]+)")}$`);
769
+ for (const name of fs.readdirSync(abs)) {
770
+ const n = (shape.exec(name)?.slice(1) ?? []).map(Number);
771
+ if (n.length === 0 || n.some((x) => x !== n[0]) || n[0] <= attempt)
772
+ continue;
773
+ const rel = path.join(dir, name);
774
+ if (startSha !== undefined && runGit(cwd, ["cat-file", "-e", `${startSha}:./${rel}`]).ok)
775
+ continue;
776
+ if (!later.some((l) => l.rel === rel))
777
+ later.push({ rel, n: n[0] });
778
+ }
779
+ }
780
+ return later.sort((a, b) => a.n - b.n || a.rel.localeCompare(b.rel)).map((l) => l.rel);
781
+ }
782
+ const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
783
+ /** Dotted keys whose values differ between two `bkit.workflows` objects, sorted. */
784
+ export function changedKeys(a, b, at = "") {
785
+ if (isRecord(a) && isRecord(b))
786
+ return [...new Set([...Object.keys(a), ...Object.keys(b)])]
787
+ .sort()
788
+ .flatMap((k) => changedKeys(a[k], b[k], at === "" ? k : `${at}.${k}`));
789
+ return JSON.stringify(a) === JSON.stringify(b) ? [] : [at === "" ? "bkit.workflows" : at];
790
+ }
791
+ /**
792
+ * The `bkit.workflows` keys the working tree's package.json changes from HEAD's (`git add -A`
793
+ * commits the working tree). Empty when either side cannot be read as JSON.
794
+ */
795
+ /** True when the active shared-checkout record for `fid` holds `rel` as dirty before the run. */
796
+ function recordedPath(cwd, fid, rel) {
797
+ const rec = fid === undefined ? null : activeRecord(cwd, fid);
798
+ return rec !== null && rec.paths.some((p) => p.path === rel);
799
+ }
800
+ function workflowsChange(cwd) {
801
+ const top = git(cwd, ["rev-parse", "--show-toplevel"]) ?? cwd;
802
+ const file = path.join(top, "package.json");
803
+ const head = runGit(top, ["cat-file", "-e", "HEAD:package.json"]).ok
804
+ ? parseJson(runGit(top, ["show", "HEAD:package.json"]).stdout)
805
+ : { ok: true, value: {} };
806
+ const work = fs.existsSync(file)
807
+ ? parseJson(fs.readFileSync(file, "utf-8"))
808
+ : { ok: true, value: {} };
809
+ if (!head.ok || !work.ok)
810
+ return [];
811
+ const workflows = (pkg) => (isRecord(pkg) && isRecord(pkg.bkit) ? pkg.bkit.workflows : undefined) ?? {};
812
+ return changedKeys(workflows(head.value), workflows(work.value));
813
+ }
499
814
  /** `soakAttempt` → `Soak Attempt`, for a comment header. */
500
815
  const titleCase = (key) => key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
501
816
  /** `<attempt>` filled in, once the attempt is known. */
@@ -573,6 +888,9 @@ async function finish(ctx) {
573
888
  continue;
574
889
  if (k === "Failures")
575
890
  failures = (failures ?? 0) + Number(v);
891
+ // A `true | false` field is true when any agent sets it: one reviewer's flag is never outvoted.
892
+ else if (v === "true" && fields[k] === "false")
893
+ fields[k] = v;
576
894
  else if (!(k in fields))
577
895
  fields[k] = v;
578
896
  }
@@ -595,12 +913,75 @@ async function finish(ctx) {
595
913
  if (strategy !== undefined && !STRATEGIES.includes(strategy))
596
914
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
597
915
  delete fields.Strategy;
916
+ if (workflow === "build" && step === "build-challenge") {
917
+ try {
918
+ extras.challengeFindings = mergeFindings(artifacts
919
+ .filter((a) => !isUrl(a))
920
+ .map((a) => parseFindings(fs.readFileSync(path.resolve(ctx.cwd, a), "utf-8"), a, ctx.cwd)), new Set()).findings.map(({ severity, location, title }) => ({ severity, location, title }));
921
+ }
922
+ catch (error) {
923
+ extras.challengeFindings = null;
924
+ ctx.log(`challenge findings unavailable: ${String(error)}; the original verdict remains unresolved until the report is corrected`);
925
+ }
926
+ }
927
+ if (workflow === "debug" && step === "debug-failure-reproduce" && fields.Reproduced !== undefined)
928
+ extras.reproduced = fields.Reproduced;
598
929
  const clampLog = str(f.clampLog);
599
930
  if (clampLog !== undefined) {
600
931
  const [clampStep, clampAttempt] = fill(clampLog, attempt).split(":");
601
932
  const fid = path.basename(path.dirname(file));
602
933
  extras.clamped = readRecords(clampLogPath(ctx.cwd, fid, clampStep, positiveInt(clampAttempt, "clamp-log attempt")), (l) => ctx.log(`skipping a malformed clamp record: ${l}`));
603
934
  }
935
+ if (workflow === "debug" && step === "debug-run-tests") {
936
+ const active = readRuns(file).at(-1);
937
+ const rows = readStatusRows(file);
938
+ const start = rows
939
+ .map((r, i) => (r.type === "workflow-started" && r.workflow === "debug" ? i : -1))
940
+ .filter((i) => i >= 0)
941
+ .at(-1) ?? -1;
942
+ const round = rows
943
+ .slice(start + 1)
944
+ .reverse()
945
+ .find((r) => r.type === "test-run" &&
946
+ r.workflow === workflow &&
947
+ r.step === step &&
948
+ r.attempt === attempt);
949
+ if (extras.source === "ci" || round?.source === "ci") {
950
+ const matching = active?.workflow === "debug" &&
951
+ active.status === "IN_PROGRESS" &&
952
+ round &&
953
+ ciRoundMatches(round, active.ciSelection, active.ciGeneration) &&
954
+ extras.source === "ci" &&
955
+ extras.ciGeneration === active.ciGeneration &&
956
+ verdict === "FAIL" &&
957
+ failures === undefined &&
958
+ extras.scope === round.scope &&
959
+ artifacts.includes(String(round.artifact));
960
+ if (!matching)
961
+ throw new CommandError(EXIT.USAGE, "CI evidence does not match the active selection");
962
+ const text = fs.readFileSync(path.resolve(ctx.cwd, String(round.artifact)), "utf-8");
963
+ const required = [
964
+ "Verdict: FAIL",
965
+ "Source: ci",
966
+ `Scope: ${round.scope}`,
967
+ `Repository: ${round.repo}`,
968
+ `Workflow: ${round.workflowPath} (${round.workflowId})`,
969
+ `Run: ${round.ciRun}`,
970
+ `Run attempt: ${round.runAttempt}`,
971
+ `CI generation: ${round.ciGeneration}`,
972
+ `Commit: ${round.headSha}`,
973
+ `URL: ${round.ciUrl}`,
974
+ "The local gate was not run.",
975
+ ];
976
+ if (!required.every((line) => text.split(/\r?\n/).includes(line)))
977
+ throw new CommandError(EXIT.USAGE, "CI evidence artifact identity mismatch");
978
+ delete extras.clamped;
979
+ }
980
+ else if ((clampLog !== undefined || round !== undefined) &&
981
+ (!Array.isArray(extras.clamped) || extras.clamped.length === 0)) {
982
+ throw new CommandError(EXIT.USAGE, "local test completion needs clamp evidence");
983
+ }
984
+ }
604
985
  // What the gate would refuse, refused before anything is written.
605
986
  const pre = gateChecks(ctx.cwd, {
606
987
  workflow,
@@ -626,6 +1007,71 @@ async function finish(ctx) {
626
1007
  const commit = str(f.commit) ?? "auto";
627
1008
  if (!["auto", "none"].includes(commit))
628
1009
  throw new CommandError(EXIT.USAGE, "--commit must be auto or none");
1010
+ // A code step never edits a planned test case: each one's own lines must still be the
1011
+ // lines the group's tests step recorded at its red. Every other edit to the file is
1012
+ // ordinary code-step work the verifier reads in the diff.
1013
+ if (workflow === "build" &&
1014
+ (step === PLAN_TASKS_STEP || step === PLAN_REMEDIATE_STEP) &&
1015
+ group !== undefined) {
1016
+ const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
1017
+ const tests = touchedTests(top, file, workflow, group);
1018
+ if (tests.length > 0) {
1019
+ const touched = [...new Set(tests.map((t) => t.test))];
1020
+ const named = tests.map((t) => `\`${t.test}\` "${t.name}"`).join(", ");
1021
+ 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)`;
1022
+ ctx.log(problem);
1023
+ recordTestLockFriction(top, step, named);
1024
+ ctx.emit({
1025
+ pass: false,
1026
+ reask: agents.length ? { agent: agents[0], artifact: artifacts[0] } : null,
1027
+ problem,
1028
+ touched,
1029
+ tests,
1030
+ });
1031
+ return EXIT_TESTS_TOUCHED;
1032
+ }
1033
+ }
1034
+ // The tests step writes the group's tests: its commit may change those files, its own
1035
+ // artifacts and the run's logs only, and add files no CREATE line of the plan names.
1036
+ if (workflow === "build" && step === PLAN_TESTS_STEP && commit === "auto") {
1037
+ const planArg = str(f.plan);
1038
+ if (planArg === undefined)
1039
+ throw new CommandError(EXIT.USAGE, `--plan is required to finish ${PLAN_TESTS_STEP}`);
1040
+ if (group === undefined)
1041
+ throw new CommandError(EXIT.USAGE, `--group is required to finish ${PLAN_TESTS_STEP}`);
1042
+ const source = sourceTouched(ctx.cwd, {
1043
+ plan: path.resolve(ctx.cwd, planArg),
1044
+ group,
1045
+ allowed: [...artifacts, path.dirname(file)],
1046
+ });
1047
+ if (source.length > 0) {
1048
+ ctx.log(`the tests step changed ${source.join(", ")}: it writes the group's TEST FIRST files only — put the rest back (nothing written)`);
1049
+ ctx.emit({ pass: false, source });
1050
+ return EXIT_SOURCE_TOUCHED;
1051
+ }
1052
+ }
1053
+ // The attempt finished is the latest one this run saved artifacts for.
1054
+ if (attempt !== undefined) {
1055
+ const startSha = activeRunStart(file, workflow)?.parentSha;
1056
+ const later = laterAttempts(ctx.cwd, [...list(f.artifact), ...list(f.optionalArtifact)], attempt, typeof startSha === "string" && startSha !== "" ? startSha : undefined);
1057
+ if (later.length > 0) {
1058
+ ctx.log(`attempt ${attempt} is not the latest: this run saved ${later.join(", ")} after it — finish the latest attempt (nothing written)`);
1059
+ ctx.emit({ pass: false, attempt, later });
1060
+ return EXIT_LATER_ATTEMPT;
1061
+ }
1062
+ }
1063
+ // A run never changes its own limits: the step commit may not carry a bkit.workflows edit.
1064
+ // With a shared-checkout record the commit carries the run's own paths only, so a
1065
+ // package.json that was already dirty when the run started stays out of it: a recorded
1066
+ // one the run then changed is refused as foreign by the commit itself.
1067
+ if (commit === "auto" && !recordedPath(ctx.cwd, fidOfStatusFile(file), "package.json")) {
1068
+ const changed = workflowsChange(ctx.cwd);
1069
+ if (changed.length > 0) {
1070
+ ctx.log(`the step's commit would change bkit.workflows in package.json (${changed.join(", ")}): restore HEAD's values, then finish again (nothing written)`);
1071
+ ctx.emit({ pass: false, changed });
1072
+ return EXIT_WORKFLOWS_CHANGED;
1073
+ }
1074
+ }
629
1075
  if (f.docsOnly === true && commit === "auto") {
630
1076
  addAllButCopied(ctx.cwd);
631
1077
  const outside = runGit(ctx.cwd, ["diff", "--cached", "--name-only"])
@@ -741,6 +1187,7 @@ async function finish(ctx) {
741
1187
  row: written.row,
742
1188
  parentSha: written.row.parentSha,
743
1189
  commit: written.commit,
1190
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
744
1191
  pass,
745
1192
  checks,
746
1193
  comment,
@@ -785,6 +1232,7 @@ export const stepsCommand = {
785
1232
  verbs: {
786
1233
  done: {
787
1234
  summary: "Append a step-done row and commit it (parentSha captured first).",
1235
+ use: "workflow",
788
1236
  flags: [
789
1237
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
790
1238
  WORKFLOW_FLAG,
@@ -825,12 +1273,13 @@ export const stepsCommand = {
825
1273
  output: {
826
1274
  row: "the appended step-done row",
827
1275
  commit: "the new commit's sha, or null with --commit=none",
1276
+ progressLine: "the exact chat progress line after a successful numbered completion",
828
1277
  },
829
1278
  textOmit: ["row"],
830
1279
  exitCodes: {
831
1280
  [EXIT_NO_STATUS]: "--attempt=next could not read status.jsonl",
832
1281
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory",
833
- [EXIT_COMMIT]: "the row was written but the commit failed",
1282
+ [EXIT_COMMIT]: "nothing written, nothing committed: the commit failed and the row was rolled back",
834
1283
  [EXIT_FOREIGN_PATH]: "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
835
1284
  [EXIT_NO_RECORD]: "a debug run on dev/main with no shared-checkout record: nothing written or committed",
836
1285
  },
@@ -882,12 +1331,17 @@ export const stepsCommand = {
882
1331
  commit: commit,
883
1332
  message: str(f.message),
884
1333
  }, ctx.log);
885
- ctx.emit({ row: written.row, commit: written.commit });
1334
+ ctx.emit({
1335
+ row: written.row,
1336
+ commit: written.commit,
1337
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
1338
+ });
886
1339
  return written.code;
887
1340
  },
888
1341
  },
889
1342
  finish: {
890
1343
  summary: "End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment.",
1344
+ use: "workflow",
891
1345
  flags: [
892
1346
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
893
1347
  WORKFLOW_FLAG,
@@ -956,6 +1410,11 @@ export const stepsCommand = {
956
1410
  type: "boolean",
957
1411
  help: "refuse (exit 9) when the step staged anything outside docs/plans/ and the docs ledgers",
958
1412
  },
1413
+ {
1414
+ name: "plan",
1415
+ type: "string",
1416
+ help: `${PLAN_TESTS_STEP}: the plan file whose TEST FIRST lines bound the step's commit (required there with --commit=auto)`,
1417
+ },
959
1418
  ...COMMIT_FLAGS.map((c) => c.name === "message"
960
1419
  ? {
961
1420
  ...c,
@@ -1011,12 +1470,17 @@ export const stepsCommand = {
1011
1470
  parentSha: "the row's parentSha: HEAD before the step's commit",
1012
1471
  commit: "the new commit's sha, or null with --commit=none",
1013
1472
  pass: "every gate check passed",
1473
+ progressLine: "the exact chat progress line after a successful numbered completion",
1014
1474
  checks: "[{check, ok, detail}] per gate check",
1015
1475
  comment: "the step's tracker comment body (with --number), else null",
1016
1476
  commentFile: COMMENT_FILE_OUTPUT,
1017
1477
  tracker: TRACKER_OUTPUT,
1018
- reask: "verdict read failed: {agent, artifact} to re-ask (exit 4 / 5 / 6 only)",
1019
- problem: "why the verdict read failed (exit 4 / 5 / 6 only)",
1478
+ reask: "verdict read failed, or a planned test was touched: {agent, artifact} to re-ask (exit 4 / 5 / 6 / 11 only)",
1479
+ problem: "why the verdict read failed, or which planned tests the code step touched (exit 4 / 5 / 6 / 11 only)",
1480
+ touched: "planned test files of the group that differ from the blob its tests step recorded (exit 11 only)",
1481
+ source: "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)",
1482
+ later: "artifacts of a later attempt this run saved (exit 12 only)",
1483
+ changed: "bkit.workflows keys the commit would change, dotted (exit 13 only)",
1020
1484
  },
1021
1485
  textOmit: ["row", { key: "checks", when: (_checks, out) => out.pass === true }],
1022
1486
  exitCodes: {
@@ -1025,15 +1489,20 @@ export const stepsCommand = {
1025
1489
  [EXIT_PENDING]: "an --agent's header still has a PENDING field — re-ask it (nothing written)",
1026
1490
  [EXIT_INVALID]: "an --agent's header is invalid (no verdict:end, a value outside its set, Failures disagreeing with Verdict) — re-ask it (nothing written)",
1027
1491
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory (nothing written)",
1028
- [EXIT_COMMIT]: "the row was written but the commit failed",
1492
+ [EXIT_COMMIT]: "nothing written, nothing committed: the commit failed and the row was rolled back",
1029
1493
  [EXIT_FOREIGN_PATH]: "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1030
1494
  [EXIT_NO_RECORD]: "a debug run on dev/main with no shared-checkout record: nothing written or committed",
1031
1495
  [EXIT_OUTSIDE_DOCS]: "--docs-only and the step staged a file outside the artifact tree (nothing written)",
1496
+ [EXIT_TESTS_TOUCHED]: "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)",
1497
+ [EXIT_LATER_ATTEMPT]: "this run saved an artifact of a later attempt (`later`) than the one finished (nothing written)",
1498
+ [EXIT_WORKFLOWS_CHANGED]: "the commit would change bkit.workflows in package.json (`changed` names the keys) (nothing written)",
1499
+ [EXIT_SOURCE_TOUCHED]: "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)",
1032
1500
  },
1033
1501
  run: finish,
1034
1502
  },
1035
1503
  verdict: {
1036
1504
  summary: "Read an artifact's header down to <!-- verdict:end -->.",
1505
+ use: "by-hand",
1037
1506
  flags: [
1038
1507
  { name: "file", type: "string", required: true, help: "the subagent's artifact" },
1039
1508
  ...ALLOWED_FLAGS,
@@ -1062,6 +1531,7 @@ export const stepsCommand = {
1062
1531
  },
1063
1532
  gate: {
1064
1533
  summary: "Mechanical gate checks for one step: placeholders, FID, lock, artifacts, verdict, status row (with its attempt / strategy / scope where the step writes them).",
1534
+ use: "workflow",
1065
1535
  flags: [
1066
1536
  {
1067
1537
  ...FILE_FLAG,
@@ -1076,6 +1546,11 @@ export const stepsCommand = {
1076
1546
  WORKFLOW_FLAG,
1077
1547
  STEP_FLAG,
1078
1548
  GROUP_FLAG,
1549
+ {
1550
+ name: "progress-number",
1551
+ type: "string",
1552
+ help: "render this completed numbered position without writing a status row",
1553
+ },
1079
1554
  {
1080
1555
  name: "attempt",
1081
1556
  type: "string",
@@ -1117,7 +1592,11 @@ export const stepsCommand = {
1117
1592
  help: "the workflow lock must be held with this token (needs --fid)",
1118
1593
  },
1119
1594
  ],
1120
- output: { pass: "true when every check passed", checks: "[{check, ok, detail}] per check" },
1595
+ output: {
1596
+ pass: "true when every check passed",
1597
+ checks: "[{check, ok, detail}] per check",
1598
+ progressLine: "with --progress-number: the exact chat progress line after the gate passes",
1599
+ },
1121
1600
  exitCodes: {
1122
1601
  [EXIT_NO_STATUS]: "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1123
1602
  },
@@ -1126,6 +1605,29 @@ export const stepsCommand = {
1126
1605
  const file = str(f.file) === undefined ? undefined : statusFile(ctx);
1127
1606
  const workflow = String(f.workflow);
1128
1607
  const group = positiveInt(f.group, "group");
1608
+ const progressNumber = positiveInt(f.progressNumber, "progress-number");
1609
+ if (progressNumber !== undefined &&
1610
+ (!isResumable(workflow) ||
1611
+ !WORKFLOW_STEPS[workflow].some((s) => s.number === progressNumber)))
1612
+ throw new CommandError(EXIT.USAGE, "--progress-number is not a workflow step");
1613
+ if (progressNumber !== undefined && isResumable(workflow)) {
1614
+ const step = String(f.step);
1615
+ const recordedNumber = WORKFLOW_STEPS[workflow].find((s) => s.step === step)?.number;
1616
+ const gateNumber = workflow === "ship" &&
1617
+ (step === "ship-worktree-setup" || step === "ship-regression-guard")
1618
+ ? 3
1619
+ : workflow === "ship" && step === "ship-bookkeeping-push"
1620
+ ? 9
1621
+ : recordedNumber;
1622
+ if (progressNumber !== recordedNumber && progressNumber !== gateNumber)
1623
+ throw new CommandError(EXIT.USAGE, "--progress-number does not match the gated step");
1624
+ if (file === undefined &&
1625
+ (progressNumber !== 1 ||
1626
+ !str(f.fid) ||
1627
+ !/^[0-9]{6}$/.test(str(f.month) ?? "") ||
1628
+ !str(f.token)))
1629
+ throw new CommandError(EXIT.USAGE, "gate progress needs --file, or Step 1 with --fid, --month and --token");
1630
+ }
1129
1631
  if (f.attempt !== undefined && f.attemptOf !== undefined)
1130
1632
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1131
1633
  if (f.attemptOf !== undefined && file === undefined)
@@ -1157,12 +1659,26 @@ export const stepsCommand = {
1157
1659
  const pass = checks.every((c) => c.ok);
1158
1660
  for (const c of checks.filter((x) => !x.ok))
1159
1661
  ctx.log(`${c.check}: ${c.detail}`);
1160
- ctx.emit({ pass, checks });
1662
+ const progressFile = file ??
1663
+ path.resolve(ctx.cwd, "docs", "plans", str(f.month) ?? "", "logs", str(f.fid) ?? "", "status.jsonl");
1664
+ const progressLine = pass && progressNumber !== undefined
1665
+ ? stepProgress(ctx.cwd, {
1666
+ file: progressFile,
1667
+ workflow,
1668
+ step: String(f.step),
1669
+ group,
1670
+ attempt,
1671
+ artifacts: [],
1672
+ commit: "none",
1673
+ }, progressNumber)
1674
+ : undefined;
1675
+ ctx.emit({ pass, checks, ...(progressLine === undefined ? {} : { progressLine }) });
1161
1676
  return pass ? EXIT.OK : EXIT.NO;
1162
1677
  },
1163
1678
  },
1164
1679
  stub: {
1165
1680
  summary: "Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top.",
1681
+ use: "workflow",
1166
1682
  flags: [
1167
1683
  { name: "from", type: "string", required: true, help: "the prior versioned artifact" },
1168
1684
  { name: "to", type: "string", required: true, help: "the artifact to create" },