@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
@@ -18,19 +18,23 @@ import {
18
18
  activeDoneSteps,
19
19
  allRunsDoneSteps,
20
20
  appendLine,
21
+ ciRoundMatches,
21
22
  runNumber,
22
23
  runOrStepField,
23
24
  statusTimestamp,
24
25
  type Step,
25
26
  } from "../../ledgers/status.js";
26
27
  import { clampLogPath, readRecords } from "../../ledgers/clamp-log.js";
28
+ import { appendFrictionRow, frictionRow, journalEnabled } from "../../ledgers/journal.js";
27
29
  import { resolveRepoSlug } from "../../ledgers/telemetry.js";
28
30
  import { getPromptsRoot } from "../../shared/package-roots.js";
31
+ import { readTextFile } from "../../shared/json.js";
29
32
  import {
30
33
  CommandError,
31
34
  EXIT,
32
35
  git,
33
36
  isSharedBranch,
37
+ parseJson,
34
38
  repoRoot,
35
39
  runGit,
36
40
  type CommandSpec,
@@ -38,6 +42,11 @@ import {
38
42
  type FlagValue,
39
43
  type RunContext,
40
44
  } from "../lib.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";
41
50
  import { fidProblem, normaliseFid, readIssueTracker } from "./fids.js";
42
51
  import { buildComment } from "./issues.js";
43
52
  import {
@@ -59,6 +68,7 @@ import {
59
68
  nonNegativeInt,
60
69
  positiveInt,
61
70
  readRuns,
71
+ readStatusRows,
62
72
  readRunsAt,
63
73
  statusFile,
64
74
  str,
@@ -71,8 +81,34 @@ import {
71
81
  postForVerb,
72
82
  type TrackerOutcome,
73
83
  } from "./tracker.js";
84
+ import { parsePlanBlocks } from "./plan-blocks.js";
85
+ import { PLAN_TASKS_STEP, readTestFirst, touchedTests } from "./tests.js";
74
86
  import { addAllButCopied } from "./worktrees.js";
75
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
+ }
111
+
76
112
  const VERDICT_END = "<!-- verdict:end -->";
77
113
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
78
114
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
@@ -85,6 +121,19 @@ export const EXIT_ARTIFACT = 7;
85
121
  export const EXIT_COMMIT = 8;
86
122
  /** finish --docs-only: the step staged a file outside the artifact tree. */
87
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";
88
137
 
89
138
  /** Where `finish` puts the derived attempt in `--artifact` / `--message` / `--clamp-log`. */
90
139
  export const ATTEMPT_TOKEN = "<attempt>";
@@ -307,7 +356,8 @@ export const ROW_FIELDS: Record<string, readonly RowField[]> = {
307
356
  "build/build-plan-convert": ["attempt"],
308
357
  "build/build-plan-current": ["attempt"],
309
358
  "build/build-install-skills": ["attempt"],
310
- "build/build-plan-execute": ["attempt"],
359
+ "build/build-plan-tests": ["attempt"],
360
+ "build/build-plan-tasks": ["attempt"],
311
361
  "build/build-plan-verify": ["attempt"],
312
362
  "build/build-group-gate": ["attempt", "scope"],
313
363
  "build/build-plan-gaps-remediate": ["attempt", "strategy"],
@@ -369,6 +419,100 @@ function fidOfStatusFile(file: string): string | undefined {
369
419
  )?.[1];
370
420
  }
371
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
+
372
516
  export interface StepRow {
373
517
  file: string;
374
518
  workflow: string;
@@ -410,16 +554,62 @@ export function requireRecordOnShared(
410
554
  );
411
555
  }
412
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
+
413
600
  /**
414
601
  * Append one `step-done` row, then commit (parentSha first, the row, then the
415
602
  * commit — the order the fold's de-dup relies on). Returns the row and the new
416
- * 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.
417
607
  */
418
608
  export function writeStepRow(
419
609
  cwd: string,
420
610
  r: StepRow,
421
611
  log: (m: string) => void,
422
- ): { row: Record<string, unknown>; commit: string | null; code: number } {
612
+ ): { row: Record<string, unknown>; commit: string | null; code: number; progressLine?: string } {
423
613
  const clash = Object.keys(r.extras ?? {}).filter((k) => CORE_ROW_KEYS.has(k));
424
614
  if (clash.length > 0)
425
615
  throw new CommandError(EXIT.USAGE, `--field cannot set ${clash.join(", ")}; use its own flag`);
@@ -444,6 +634,7 @@ export function writeStepRow(
444
634
  ...(r.strategy === undefined ? {} : { strategy: r.strategy as Step["strategy"] }),
445
635
  ...(r.extras ?? {}),
446
636
  };
637
+ const progressLine = stepProgress(cwd, r);
447
638
  // An in-place run on a shared branch commits its own paths only; a refusal
448
639
  // comes before the append, so a re-run after the human's fix writes the row once.
449
640
  const fid = r.commit === "auto" ? fidOfStatusFile(r.file) : undefined;
@@ -458,32 +649,80 @@ export function writeStepRow(
458
649
  return { row, commit: null, code: EXIT_FOREIGN_PATH };
459
650
  }
460
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;
461
654
  fs.mkdirSync(path.dirname(r.file), { recursive: true });
462
- 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
+ };
463
693
 
464
- if (r.commit === "none") return { row, commit: null, code: EXIT.OK };
694
+ if (r.commit === "none")
695
+ return {
696
+ row,
697
+ commit: null,
698
+ code: EXIT.OK,
699
+ ...(progressLine === undefined ? {} : { progressLine }),
700
+ };
465
701
  if (rec !== null) {
466
702
  let own: OwnCommit;
467
703
  try {
468
704
  own = ownPathCommit(cwd, rec, r.message!, { allowEmpty: true });
469
705
  } catch (err) {
470
706
  if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH) throw err;
471
- log(`row written to ${r.file} but the commit was refused: ${err.message}`);
472
- return { row, commit: null, code: EXIT_FOREIGN_PATH };
707
+ return failed(EXIT_FOREIGN_PATH, `the commit was refused: ${err.message}`);
473
708
  }
474
- if (!own.ok) {
475
- log(`row written to ${r.file} but the commit failed: ${own.error}`);
476
- return { row, commit: null, code: EXIT_COMMIT };
477
- }
478
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
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
+ };
479
716
  }
480
717
  const add = addAllButCopied(cwd);
481
718
  const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message!]) : add;
482
- if (!made.ok) {
483
- log(`row written to ${r.file} but the commit failed: ${made.stderr || made.stdout}`);
484
- return { row, commit: null, code: EXIT_COMMIT };
485
- }
486
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
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
+ };
487
726
  }
488
727
 
489
728
  // ---------------------------------------------------------------------------
@@ -679,6 +918,115 @@ export function doneDescription(file: string): string {
679
918
  const DOCS_ONLY =
680
919
  /^docs\/plans\/|^docs\/(deferrals|decisions|failures)\.jsonl$|^\.bkit\/(friction|stats)\.jsonl$/;
681
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
+
682
1030
  /** `soakAttempt` → `Soak Attempt`, for a comment header. */
683
1031
  const titleCase = (key: string) =>
684
1032
  key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
@@ -764,6 +1112,8 @@ async function finish(ctx: RunContext): Promise<number> {
764
1112
  for (const [k, v] of Object.entries(read.fields)) {
765
1113
  if (k === "Verdict") continue;
766
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;
767
1117
  else if (!(k in fields)) fields[k] = v;
768
1118
  }
769
1119
  }
@@ -784,6 +1134,25 @@ async function finish(ctx: RunContext): Promise<number> {
784
1134
  if (strategy !== undefined && !STRATEGIES.includes(strategy))
785
1135
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
786
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;
787
1156
 
788
1157
  const clampLog = str(f.clampLog);
789
1158
  if (clampLog !== undefined) {
@@ -795,6 +1164,63 @@ async function finish(ctx: RunContext): Promise<number> {
795
1164
  );
796
1165
  }
797
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
+
798
1224
  // What the gate would refuse, refused before anything is written.
799
1225
  const pre: Check[] = gateChecks(ctx.cwd, {
800
1226
  workflow,
@@ -820,6 +1246,89 @@ async function finish(ctx: RunContext): Promise<number> {
820
1246
  const commit = str(f.commit) ?? "auto";
821
1247
  if (!["auto", "none"].includes(commit))
822
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
+
823
1332
  if (f.docsOnly === true && commit === "auto") {
824
1333
  addAllButCopied(ctx.cwd);
825
1334
  const outside = runGit(ctx.cwd, ["diff", "--cached", "--name-only"])
@@ -950,6 +1459,7 @@ async function finish(ctx: RunContext): Promise<number> {
950
1459
  row: written.row,
951
1460
  parentSha: written.row.parentSha,
952
1461
  commit: written.commit,
1462
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
953
1463
  pass,
954
1464
  checks,
955
1465
  comment,
@@ -1000,6 +1510,7 @@ export const stepsCommand: CommandSpec = {
1000
1510
  verbs: {
1001
1511
  done: {
1002
1512
  summary: "Append a step-done row and commit it (parentSha captured first).",
1513
+ use: "workflow",
1003
1514
  flags: [
1004
1515
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
1005
1516
  WORKFLOW_FLAG,
@@ -1040,12 +1551,14 @@ export const stepsCommand: CommandSpec = {
1040
1551
  output: {
1041
1552
  row: "the appended step-done row",
1042
1553
  commit: "the new commit's sha, or null with --commit=none",
1554
+ progressLine: "the exact chat progress line after a successful numbered completion",
1043
1555
  },
1044
1556
  textOmit: ["row"],
1045
1557
  exitCodes: {
1046
1558
  [EXIT_NO_STATUS]: "--attempt=next could not read status.jsonl",
1047
1559
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory",
1048
- [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",
1049
1562
  [EXIT_FOREIGN_PATH]:
1050
1563
  "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1051
1564
  [EXIT_NO_RECORD]:
@@ -1105,13 +1618,18 @@ export const stepsCommand: CommandSpec = {
1105
1618
  },
1106
1619
  ctx.log,
1107
1620
  );
1108
- 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
+ });
1109
1626
  return written.code;
1110
1627
  },
1111
1628
  },
1112
1629
  finish: {
1113
1630
  summary:
1114
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",
1115
1633
  flags: [
1116
1634
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
1117
1635
  WORKFLOW_FLAG,
@@ -1180,6 +1698,11 @@ export const stepsCommand: CommandSpec = {
1180
1698
  type: "boolean",
1181
1699
  help: "refuse (exit 9) when the step staged anything outside docs/plans/ and the docs ledgers",
1182
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
+ },
1183
1706
  ...COMMIT_FLAGS.map((c) =>
1184
1707
  c.name === "message"
1185
1708
  ? {
@@ -1237,12 +1760,21 @@ export const stepsCommand: CommandSpec = {
1237
1760
  parentSha: "the row's parentSha: HEAD before the step's commit",
1238
1761
  commit: "the new commit's sha, or null with --commit=none",
1239
1762
  pass: "every gate check passed",
1763
+ progressLine: "the exact chat progress line after a successful numbered completion",
1240
1764
  checks: "[{check, ok, detail}] per gate check",
1241
1765
  comment: "the step's tracker comment body (with --number), else null",
1242
1766
  commentFile: COMMENT_FILE_OUTPUT,
1243
1767
  tracker: TRACKER_OUTPUT,
1244
- reask: "verdict read failed: {agent, artifact} to re-ask (exit 4 / 5 / 6 only)",
1245
- problem: "why the verdict read failed (exit 4 / 5 / 6 only)",
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)",
1246
1778
  },
1247
1779
  textOmit: ["row", { key: "checks", when: (_checks, out) => out.pass === true }],
1248
1780
  exitCodes: {
@@ -1254,18 +1786,28 @@ export const stepsCommand: CommandSpec = {
1254
1786
  "an --agent's header is invalid (no verdict:end, a value outside its set, Failures disagreeing with Verdict) — re-ask it (nothing written)",
1255
1787
  [EXIT_ARTIFACT]:
1256
1788
  "an --artifact is missing, empty, or outside the working directory (nothing written)",
1257
- [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",
1258
1791
  [EXIT_FOREIGN_PATH]:
1259
1792
  "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1260
1793
  [EXIT_NO_RECORD]:
1261
1794
  "a debug run on dev/main with no shared-checkout record: nothing written or committed",
1262
1795
  [EXIT_OUTSIDE_DOCS]:
1263
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)",
1264
1805
  },
1265
1806
  run: finish,
1266
1807
  },
1267
1808
  verdict: {
1268
1809
  summary: "Read an artifact's header down to <!-- verdict:end -->.",
1810
+ use: "by-hand",
1269
1811
  flags: [
1270
1812
  { name: "file", type: "string", required: true, help: "the subagent's artifact" },
1271
1813
  ...ALLOWED_FLAGS,
@@ -1300,6 +1842,7 @@ export const stepsCommand: CommandSpec = {
1300
1842
  gate: {
1301
1843
  summary:
1302
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",
1303
1846
  flags: [
1304
1847
  {
1305
1848
  ...FILE_FLAG,
@@ -1314,6 +1857,11 @@ export const stepsCommand: CommandSpec = {
1314
1857
  WORKFLOW_FLAG,
1315
1858
  STEP_FLAG,
1316
1859
  GROUP_FLAG,
1860
+ {
1861
+ name: "progress-number",
1862
+ type: "string",
1863
+ help: "render this completed numbered position without writing a status row",
1864
+ },
1317
1865
  {
1318
1866
  name: "attempt",
1319
1867
  type: "string",
@@ -1355,7 +1903,11 @@ export const stepsCommand: CommandSpec = {
1355
1903
  help: "the workflow lock must be held with this token (needs --fid)",
1356
1904
  },
1357
1905
  ],
1358
- 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
+ },
1359
1911
  exitCodes: {
1360
1912
  [EXIT_NO_STATUS]:
1361
1913
  "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
@@ -1365,6 +1917,37 @@ export const stepsCommand: CommandSpec = {
1365
1917
  const file = str(f.file) === undefined ? undefined : statusFile(ctx);
1366
1918
  const workflow = String(f.workflow);
1367
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
+ }
1368
1951
  if (f.attempt !== undefined && f.attemptOf !== undefined)
1369
1952
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1370
1953
  if (f.attemptOf !== undefined && file === undefined)
@@ -1399,13 +1982,41 @@ export const stepsCommand: CommandSpec = {
1399
1982
  });
1400
1983
  const pass = checks.every((c) => c.ok);
1401
1984
  for (const c of checks.filter((x) => !x.ok)) ctx.log(`${c.check}: ${c.detail}`);
1402
- 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 }) });
1403
2013
  return pass ? EXIT.OK : EXIT.NO;
1404
2014
  },
1405
2015
  },
1406
2016
  stub: {
1407
2017
  summary:
1408
2018
  "Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top.",
2019
+ use: "workflow",
1409
2020
  flags: [
1410
2021
  { name: "from", type: "string", required: true, help: "the prior versioned artifact" },
1411
2022
  { name: "to", type: "string", required: true, help: "the artifact to create" },