@cbartens/bkit 5.5.1 → 6.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (425) hide show
  1. package/.bkit/README.md +167 -154
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +18 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +112 -102
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +167 -154
  11. package/.bkit/core/.bkit/authoring.md +747 -0
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +283 -195
  14. package/.bkit/core/.bkit/comparison.md +45 -43
  15. package/.bkit/core/.bkit/install.md +166 -95
  16. package/.bkit/core/.bkit/jsonl.md +339 -196
  17. package/.bkit/core/.bkit/pipeline.md +142 -145
  18. package/.bkit/core/.bkit/prompts.md +295 -264
  19. package/.bkit/core/.bkit/providers.md +460 -277
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +530 -256
  22. package/.bkit/core/.bkit/trackers.md +116 -65
  23. package/.bkit/core/.bkit/workflows.md +742 -618
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +6 -80
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +128 -130
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -94
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +96 -98
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +100 -103
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +141 -107
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +99 -97
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +122 -121
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +158 -101
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +114 -96
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +76 -97
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +123 -101
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +86 -99
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +76 -93
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +102 -95
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +165 -108
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -109
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +265 -113
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +119 -118
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +140 -111
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +111 -106
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +100 -99
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +107 -103
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +105 -105
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +134 -85
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +124 -125
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +99 -78
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -76
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -78
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +125 -93
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +97 -96
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +170 -98
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +207 -121
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +78 -95
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +163 -139
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +114 -96
  68. package/.bkit/core/docs/templates/bkit-plan.md +158 -281
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +104 -31
  71. package/.bkit/core/engine/checks/after/github.ts +95 -17
  72. package/.bkit/core/engine/checks/after/index.ts +21 -8
  73. package/.bkit/core/engine/checks/after/suppression.ts +8 -5
  74. package/.bkit/core/engine/checks/after/tools.ts +125 -123
  75. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  76. package/.bkit/core/engine/checks/before/env.ts +3 -3
  77. package/.bkit/core/engine/checks/before/files.ts +5 -4
  78. package/.bkit/core/engine/checks/before/index.ts +25 -1
  79. package/.bkit/core/engine/checks/before/repo.ts +208 -2
  80. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  81. package/.bkit/core/engine/checks/tips/catalogue.ts +82 -20
  82. package/.bkit/core/engine/checks/tips/detect.ts +66 -0
  83. package/.bkit/core/engine/checks/tips/index.ts +52 -11
  84. package/.bkit/core/engine/cli.ts +251 -130
  85. package/.bkit/core/engine/commands/analysis.ts +282 -199
  86. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  87. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  88. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  89. package/.bkit/core/engine/commands/comply.ts +77 -103
  90. package/.bkit/core/engine/commands/install/doctor.ts +2 -2
  91. package/.bkit/core/engine/commands/install/install.ts +57 -18
  92. package/.bkit/core/engine/commands/install/uninstall.ts +86 -55
  93. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  94. package/.bkit/core/engine/commands/land.ts +139 -18
  95. package/.bkit/core/engine/commands/lib.ts +381 -22
  96. package/.bkit/core/engine/commands/registry.ts +10 -2
  97. package/.bkit/core/engine/commands/setup/setup.ts +8 -7
  98. package/.bkit/core/engine/commands/stats.ts +260 -0
  99. package/.bkit/core/engine/commands/tips.ts +10 -5
  100. package/.bkit/core/engine/commands/workflow/branches.ts +2215 -176
  101. package/.bkit/core/engine/commands/workflow/challenge.ts +748 -0
  102. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  103. package/.bkit/core/engine/commands/workflow/context.ts +1249 -47
  104. package/.bkit/core/engine/commands/workflow/counters.ts +483 -95
  105. package/.bkit/core/engine/commands/workflow/decisions.ts +585 -0
  106. package/.bkit/core/engine/commands/workflow/disk.ts +238 -56
  107. package/.bkit/core/engine/commands/workflow/fids.ts +811 -33
  108. package/.bkit/core/engine/commands/workflow/issues.ts +413 -64
  109. package/.bkit/core/engine/commands/workflow/ledgers.ts +1333 -36
  110. package/.bkit/core/engine/commands/workflow/locks.ts +28 -2
  111. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +691 -0
  112. package/.bkit/core/engine/commands/workflow/plan-versions.ts +21 -0
  113. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  114. package/.bkit/core/engine/commands/workflow/prs.ts +178 -33
  115. package/.bkit/core/engine/commands/workflow/repo.ts +66 -8
  116. package/.bkit/core/engine/commands/workflow/roadmap.ts +72 -22
  117. package/.bkit/core/engine/commands/workflow/run-facts.ts +492 -0
  118. package/.bkit/core/engine/commands/workflow/runs.ts +827 -79
  119. package/.bkit/core/engine/commands/workflow/runtime.ts +25 -1
  120. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  121. package/.bkit/core/engine/commands/workflow/status.ts +329 -33
  122. package/.bkit/core/engine/commands/workflow/step-table.ts +381 -0
  123. package/.bkit/core/engine/commands/workflow/steps.ts +841 -105
  124. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  125. package/.bkit/core/engine/commands/workflow/summary.ts +544 -0
  126. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  127. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  128. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  129. package/.bkit/core/engine/commands/workflow/tests.ts +2124 -330
  130. package/.bkit/core/engine/commands/workflow/tracker.ts +1195 -0
  131. package/.bkit/core/engine/commands/workflow/workflows.ts +1197 -235
  132. package/.bkit/core/engine/commands/workflow/worktrees.ts +543 -24
  133. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  134. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  135. package/.bkit/core/engine/install/manifest.ts +67 -17
  136. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  137. package/.bkit/core/engine/install/modules/cloud.ts +24 -16
  138. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  139. package/.bkit/core/engine/install/modules/core.ts +1196 -45
  140. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  141. package/.bkit/core/engine/install/modules/opencode.ts +18 -6
  142. package/.bkit/core/engine/install/template-notes.ts +130 -0
  143. package/.bkit/core/engine/install/version-file.ts +9 -4
  144. package/.bkit/core/engine/install/write.ts +5 -0
  145. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  146. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  147. package/.bkit/core/engine/ledgers/migrate.ts +92 -0
  148. package/.bkit/core/engine/ledgers/status.ts +249 -21
  149. package/.bkit/core/engine/ledgers/telemetry.ts +1397 -253
  150. package/.bkit/core/engine/render/hosts.ts +118 -14
  151. package/.bkit/core/engine/render/models.ts +12 -0
  152. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  153. package/.bkit/core/engine/shared/branches.ts +4 -1
  154. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  155. package/.bkit/core/engine/shared/egress.ts +8 -1
  156. package/.bkit/core/engine/shared/json.ts +25 -7
  157. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  158. package/.bkit/core/engine/shared/settings.ts +243 -31
  159. package/.bkit/core/engine/shared/text.ts +361 -0
  160. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  161. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  162. package/.bkit/core/engine/tools/grammar-density.ts +215 -0
  163. package/.bkit/core/engine/tools/instructions-sources.ts +832 -0
  164. package/.bkit/core/engine/tools/instructions.ts +1802 -0
  165. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  166. package/.bkit/core/hooks/gateguard-engine.js +54 -29
  167. package/.bkit/core/hooks/guardrails-shell.js +4 -5
  168. package/.bkit/core/hooks/guardrails-tiers.js +10 -4
  169. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  170. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  171. package/.bkit/core/hooks/readguard-engine.js +29 -10
  172. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  173. package/.bkit/core/prompts/bkit-audit-generate.md +202 -94
  174. package/.bkit/core/prompts/bkit-build-challenge-1.md +76 -34
  175. package/.bkit/core/prompts/bkit-build-challenge-2.md +85 -38
  176. package/.bkit/core/prompts/bkit-build-install-skills.md +50 -28
  177. package/.bkit/core/prompts/bkit-build-plan-convert.md +85 -0
  178. package/.bkit/core/prompts/bkit-build-plan-current.md +59 -36
  179. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +101 -36
  180. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  181. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  182. package/.bkit/core/prompts/bkit-build-plan-verify.md +104 -43
  183. package/.bkit/core/prompts/bkit-debug-abort-handover.md +47 -32
  184. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +109 -57
  185. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +65 -39
  186. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +53 -31
  187. package/.bkit/core/prompts/bkit-debug-failure-soak.md +65 -34
  188. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +46 -31
  189. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +45 -31
  190. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +43 -30
  191. package/.bkit/core/prompts/bkit-design-generate.md +80 -46
  192. package/.bkit/core/prompts/bkit-design-organise.md +83 -32
  193. package/.bkit/core/prompts/bkit-design-review-1.md +70 -50
  194. package/.bkit/core/prompts/bkit-design-review-2.md +65 -46
  195. package/.bkit/core/prompts/bkit-design-spike.md +64 -40
  196. package/.bkit/core/prompts/bkit-design-update.md +53 -28
  197. package/.bkit/core/prompts/bkit-plan-generate.md +101 -29
  198. package/.bkit/core/prompts/bkit-plan-review-1.md +78 -41
  199. package/.bkit/core/prompts/bkit-plan-review-2.md +78 -35
  200. package/.bkit/core/prompts/bkit-plan-scope-check.md +116 -0
  201. package/.bkit/core/prompts/bkit-plan-update.md +86 -31
  202. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +94 -50
  203. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +91 -41
  204. package/.bkit/core/prompts/bkit-ship-update-docs.md +45 -24
  205. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +65 -49
  206. package/.bkit/core/prompts/bkit-utility-update-decisions.md +87 -42
  207. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +81 -37
  208. package/.bkit/core/prompts/bkit-utility-update-documentation.md +43 -25
  209. package/.bkit/core/prompts/bkit-utility-update-failures.md +84 -37
  210. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +88 -42
  211. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +92 -39
  212. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -60
  213. package/.bkit/core/workflows/bkit-auto.md +89 -58
  214. package/.bkit/core/workflows/bkit-build.md +967 -517
  215. package/.bkit/core/workflows/bkit-debug.md +555 -387
  216. package/.bkit/core/workflows/bkit-design.md +319 -283
  217. package/.bkit/core/workflows/bkit-plan.md +319 -342
  218. package/.bkit/core/workflows/bkit-ship.md +525 -328
  219. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  220. package/.bkit/shared/.bkit/.env.example +2 -2
  221. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  222. package/.bkit/shared/.claude/settings.json +14 -0
  223. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  224. package/.bkit/shared/.codex/hooks.json +20 -0
  225. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  226. package/.bkit/shared/.cursor/mcp.json +1 -1
  227. package/.bkit/shared/.cursor/rules/bkit-rules.mdc +1 -1
  228. package/.bkit/shared/.gitattributes +1 -1
  229. package/.bkit/shared/.mcp.json +1 -1
  230. package/.bkit/shared/.opencode/opencode.json +12 -1
  231. package/.bkit/shared/CLAUDE.md +6 -2
  232. package/.bkit/shared/GEMINI.md +5 -2
  233. package/.bkit/shared/docs/architecture.md +4 -7
  234. package/.bkit/shared/docs/data-schema.md +4 -7
  235. package/.bkit/shared/docs/deployments.md +241 -168
  236. package/.bkit/shared/docs/design.md +11 -12
  237. package/.bkit/shared/docs/noise.md +8 -7
  238. package/.bkit/shared/docs/observability.md +5 -8
  239. package/.bkit/shared/docs/security.md +35 -17
  240. package/.bkit/shared/docs/setup.md +29 -18
  241. package/.bkit/shared/docs/technology.md +3 -6
  242. package/.bkit/shared/docs/testing.md +289 -174
  243. package/.bkit/shared/gitignore +6 -2
  244. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  245. package/.bkit/templates/.cursor/Dockerfile +12 -8
  246. package/.bkit/templates/.cursor/environment.json +1 -1
  247. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  248. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +45 -12
  249. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  250. package/.bkit/templates/.github/renovate.json5 +34 -6
  251. package/.bkit/templates/.github/workflows/bkit-ci.yml +54 -51
  252. package/.bkit/templates/.github/workflows/bkit-cloud.yml +34 -33
  253. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  254. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  255. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  256. package/.bkit/templates/.husky/pre-commit +2 -2
  257. package/.bkit/templates/.husky/pre-push +96 -36
  258. package/.bkit/templates/.prettierignore +6 -0
  259. package/.bkit/templates/.vale.ini +27 -27
  260. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  261. package/.bkit/templates/context/bkit-expo.md +70 -52
  262. package/.bkit/templates/context/bkit-github.md +93 -56
  263. package/.bkit/templates/context/bkit-inngest.md +21 -15
  264. package/.bkit/templates/context/bkit-maestro.md +22 -16
  265. package/.bkit/templates/context/bkit-playwright.md +23 -17
  266. package/.bkit/templates/context/bkit-resend.md +12 -10
  267. package/.bkit/templates/context/bkit-sentry.md +30 -20
  268. package/.bkit/templates/context/bkit-serena.md +8 -7
  269. package/.bkit/templates/context/bkit-stripe.md +14 -13
  270. package/.bkit/templates/context/bkit-supabase.md +16 -13
  271. package/.bkit/templates/context/bkit-tavily.md +14 -11
  272. package/.bkit/templates/context/bkit-vercel.md +27 -18
  273. package/.bkit/templates/docs/capabilities.md +15 -14
  274. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  275. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  276. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  277. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  278. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  279. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  280. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  281. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  282. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  283. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  284. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  285. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +10 -2
  286. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  287. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  288. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  289. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  290. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  291. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  292. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  293. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  294. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  295. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  296. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  297. package/.bkit/templates/slop-scan.config.json +9 -2
  298. package/CHANGELOG.md +231 -0
  299. package/README.md +278 -89
  300. package/dist/checks/after/auth.js +36 -33
  301. package/dist/checks/after/ci-yml.js +91 -30
  302. package/dist/checks/after/github.js +91 -17
  303. package/dist/checks/after/index.js +22 -11
  304. package/dist/checks/after/suppression.js +8 -5
  305. package/dist/checks/after/tools.js +111 -114
  306. package/dist/checks/before/context-fetch.js +218 -33
  307. package/dist/checks/before/env.js +3 -3
  308. package/dist/checks/before/files.js +5 -3
  309. package/dist/checks/before/index.js +20 -3
  310. package/dist/checks/before/repo.js +197 -2
  311. package/dist/checks/status-holes.js +739 -114
  312. package/dist/checks/tips/catalogue.js +70 -19
  313. package/dist/checks/tips/detect.js +62 -0
  314. package/dist/checks/tips/index.js +51 -9
  315. package/dist/cli.js +234 -124
  316. package/dist/commands/analysis.js +174 -141
  317. package/dist/commands/ci/ci.js +302 -25
  318. package/dist/commands/ci/pins.js +142 -0
  319. package/dist/commands/ci/push-gate.js +194 -0
  320. package/dist/commands/comply.js +54 -91
  321. package/dist/commands/install/doctor.js +2 -2
  322. package/dist/commands/install/install.js +50 -19
  323. package/dist/commands/install/uninstall.js +82 -55
  324. package/dist/commands/install/upgrade.js +21 -11
  325. package/dist/commands/land.js +137 -17
  326. package/dist/commands/lib.js +295 -21
  327. package/dist/commands/registry.js +10 -2
  328. package/dist/commands/setup/setup.js +8 -7
  329. package/dist/commands/stats.js +175 -0
  330. package/dist/commands/tips.js +7 -3
  331. package/dist/commands/workflow/branches.js +1873 -152
  332. package/dist/commands/workflow/challenge.js +609 -0
  333. package/dist/commands/workflow/completeness.js +97 -0
  334. package/dist/commands/workflow/context.js +1045 -46
  335. package/dist/commands/workflow/counters.js +385 -86
  336. package/dist/commands/workflow/decisions.js +484 -0
  337. package/dist/commands/workflow/disk.js +214 -56
  338. package/dist/commands/workflow/fids.js +706 -33
  339. package/dist/commands/workflow/issues.js +349 -59
  340. package/dist/commands/workflow/ledgers.js +1123 -37
  341. package/dist/commands/workflow/locks.js +26 -2
  342. package/dist/commands/workflow/plan-blocks.js +501 -0
  343. package/dist/commands/workflow/plan-versions.js +22 -0
  344. package/dist/commands/workflow/plans.js +205 -0
  345. package/dist/commands/workflow/prs.js +154 -35
  346. package/dist/commands/workflow/repo.js +58 -8
  347. package/dist/commands/workflow/roadmap.js +58 -23
  348. package/dist/commands/workflow/run-facts.js +421 -0
  349. package/dist/commands/workflow/runs.js +670 -72
  350. package/dist/commands/workflow/runtime.js +15 -1
  351. package/dist/commands/workflow/skills.js +1 -0
  352. package/dist/commands/workflow/status.js +282 -34
  353. package/dist/commands/workflow/step-table.js +308 -0
  354. package/dist/commands/workflow/steps.js +703 -96
  355. package/dist/commands/workflow/summary-findings.js +117 -0
  356. package/dist/commands/workflow/summary.js +388 -0
  357. package/dist/commands/workflow/tasks.js +378 -0
  358. package/dist/commands/workflow/test-blocks.js +231 -0
  359. package/dist/commands/workflow/tests-changed.js +172 -0
  360. package/dist/commands/workflow/tests.js +1695 -305
  361. package/dist/commands/workflow/tracker.js +983 -0
  362. package/dist/commands/workflow/workflows.js +1014 -222
  363. package/dist/commands/workflow/worktrees.js +432 -26
  364. package/dist/install/cloud-env.js +233 -99
  365. package/dist/install/context-ci-workflow.js +85 -0
  366. package/dist/install/manifest.js +64 -17
  367. package/dist/install/modules/antigravity.js +3 -2
  368. package/dist/install/modules/cloud.js +25 -16
  369. package/dist/install/modules/codex.js +12 -2
  370. package/dist/install/modules/core.js +1090 -48
  371. package/dist/install/modules/cursor.js +6 -6
  372. package/dist/install/modules/opencode.js +13 -7
  373. package/dist/install/template-notes.js +116 -0
  374. package/dist/install/version-file.js +9 -4
  375. package/dist/ledgers/compact.js +87 -0
  376. package/dist/ledgers/journal.js +233 -0
  377. package/dist/ledgers/migrate.js +81 -0
  378. package/dist/ledgers/status.js +176 -13
  379. package/dist/ledgers/telemetry.js +1010 -125
  380. package/dist/render/hosts.js +104 -14
  381. package/dist/render/models.js +12 -0
  382. package/dist/shared/bkit-latest.js +26 -4
  383. package/dist/shared/branches.js +3 -1
  384. package/dist/shared/dep-updater.js +49 -0
  385. package/dist/shared/egress.js +8 -1
  386. package/dist/shared/json.js +20 -7
  387. package/dist/shared/package-manager.js +6 -0
  388. package/dist/shared/settings.js +181 -24
  389. package/dist/shared/text.js +333 -0
  390. package/dist/shared/timeouts.js +2 -0
  391. package/dist/tools/cli-doc.js +97 -0
  392. package/dist/tools/grammar-density.js +183 -0
  393. package/dist/tools/instructions-sources.js +720 -0
  394. package/dist/tools/instructions.js +1623 -0
  395. package/package.json +156 -51
  396. package/.bkit/core/.bkit/lite.md +0 -73
  397. package/.bkit/core/engine/commands/harvest.ts +0 -459
  398. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -166
  399. package/.bkit/core/engine/tools/wording.ts +0 -748
  400. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +0 -69
  401. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +0 -71
  402. package/.bkit/core/prompts/bkit-build-challenge-tests.md +0 -74
  403. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -76
  404. package/.bkit/core/prompts/bkit-build-summary.md +0 -94
  405. package/.bkit/core/prompts/bkit-debug-summary.md +0 -96
  406. package/.bkit/core/prompts/bkit-design-summary.md +0 -107
  407. package/.bkit/core/prompts/bkit-plan-complexity-check.md +0 -67
  408. package/.bkit/core/prompts/bkit-plan-complexity-split.md +0 -88
  409. package/.bkit/core/prompts/bkit-plan-review-3.md +0 -93
  410. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +0 -85
  411. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +0 -85
  412. package/.bkit/core/prompts/bkit-plan-summary.md +0 -107
  413. package/.bkit/core/prompts/bkit-ship-summary.md +0 -78
  414. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  415. package/dist/commands/harvest.js +0 -353
  416. package/dist/commands/workflow/workstreams.js +0 -143
  417. package/dist/tools/wording.js +0 -680
  418. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  419. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  420. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  421. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  422. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  423. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  424. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  425. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -11,15 +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 { activeDoneSteps, appendLine, 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, repoRoot, runGit, } from "../lib.js";
19
- import { FID_PATTERNS, normaliseFid, readIssueTracker } from "./fids.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";
25
+ import { fidProblem, normaliseFid, readIssueTracker } from "./fids.js";
20
26
  import { buildComment } from "./issues.js";
27
+ import { EXIT_FOREIGN_PATH, activeRecord, ownPathCommit, ownSet, } from "./ledgers.js";
21
28
  import { readHolder, resolveMonth, workflowLockPath } from "./locks.js";
22
- import { EXIT_NO_STATUS, FILE_FLAG, STEP_FLAG, SUB_PLAN_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";
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";
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
+ }
23
58
  const VERDICT_END = "<!-- verdict:end -->";
24
59
  const DEFAULT_VERDICTS = ["PASS", "CONCERNS", "FAIL"];
25
60
  const STRATEGIES = ["STANDARD", "PIVOT", "FINAL"];
@@ -31,6 +66,18 @@ export const EXIT_ARTIFACT = 7;
31
66
  export const EXIT_COMMIT = 8;
32
67
  /** finish --docs-only: the step staged a file outside the artifact tree. */
33
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";
34
81
  /** Where `finish` puts the derived attempt in `--artifact` / `--message` / `--clamp-log`. */
35
82
  export const ATTEMPT_TOKEN = "<attempt>";
36
83
  /** Where `finish` puts the first `DONE` line's description in `--message`. */
@@ -220,22 +267,18 @@ export const ROW_FIELDS = {
220
267
  "plan/plan-fetch-context": ["attempt"],
221
268
  "plan/plan-review": ["attempt"],
222
269
  "plan/plan-apply-review": ["attempt"],
223
- "plan/plan-scope-check": ["attempt"],
224
- "plan/plan-apply-scope": ["attempt"],
225
- "plan/plan-complexity-check": ["attempt"],
226
- "plan/plan-complexity-split": ["attempt"],
227
270
  "plan/plan-summary": ["attempt"],
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
- "build/build-subplan-gate": ["attempt", "scope"],
277
+ "build/build-group-gate": ["attempt", "scope"],
233
278
  "build/build-plan-gaps-remediate": ["attempt", "strategy"],
234
279
  "build/build-plan-verify-holistic": ["attempt"],
235
280
  "build/build-challenge": ["attempt"],
236
- "build/build-challenge-reconcile": ["attempt"],
237
- "build/build-challenge-remediate": ["attempt"],
238
- "build/build-challenge-tests": ["attempt"],
281
+ "build/build-decision": ["attempt"],
239
282
  "build/build-run-tests": ["attempt", "scope"],
240
283
  "build/build-failure-diagnose": ["attempt", "strategy"],
241
284
  "build/build-failure-remediate": ["attempt", "strategy"],
@@ -267,14 +310,148 @@ const CORE_ROW_KEYS = new Set([
267
310
  "artifacts",
268
311
  "verdict",
269
312
  "attempt",
270
- "subPlan",
313
+ "group",
271
314
  "failures",
272
315
  "strategy",
273
316
  ]);
317
+ // ---------------------------------------------------------------------------
318
+ // Writing the row
319
+ // ---------------------------------------------------------------------------
320
+ /** The FID a `docs/plans/{month}/logs/{fid}/status.jsonl` path belongs to; undefined for any other file. */
321
+ function fidOfStatusFile(file) {
322
+ return /(?:^|\/)docs\/plans\/[0-9]{6}\/logs\/([^/]+)\/status\.jsonl$/.exec(file.split(path.sep).join("/"))?.[1];
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
+ }
399
+ /** Exit code: a debug run on a shared branch has no shared-checkout record, so nothing was written or committed. */
400
+ export const EXIT_NO_RECORD = 14;
401
+ /**
402
+ * A debug run on `dev` / `main` works in place, so its record must exist before
403
+ * it writes or commits (`git add -A` there would carry work the run does not own).
404
+ * Throws EXIT_NO_RECORD when the checkout is on a shared branch and `rec` is null.
405
+ */
406
+ export function requireRecordOnShared(cwd, workflow, rec) {
407
+ if (workflow !== "debug" || rec !== null)
408
+ return;
409
+ const branch = git(cwd, ["branch", "--show-current"]) ?? "";
410
+ if (!isSharedBranch(branch))
411
+ return;
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`);
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
+ }
274
448
  /**
275
449
  * Append one `step-done` row, then commit (parentSha first, the row, then the
276
450
  * commit — the order the fold's de-dup relies on). Returns the row and the new
277
- * 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.
278
455
  */
279
456
  export function writeStepRow(cwd, r, log) {
280
457
  const clash = Object.keys(r.extras ?? {}).filter((k) => CORE_ROW_KEYS.has(k));
@@ -295,22 +472,110 @@ export function writeStepRow(cwd, r, log) {
295
472
  artifacts: r.artifacts,
296
473
  ...(r.verdict === undefined ? {} : { verdict: r.verdict }),
297
474
  ...(r.attempt === undefined ? {} : { attempt: r.attempt }),
298
- ...(r.subPlan === undefined ? {} : { subPlan: r.subPlan }),
475
+ ...(r.group === undefined ? {} : { group: r.group }),
299
476
  ...(r.failures === undefined ? {} : { failures: r.failures }),
300
477
  ...(r.strategy === undefined ? {} : { strategy: r.strategy }),
301
478
  ...(r.extras ?? {}),
302
479
  };
480
+ const progressLine = stepProgress(cwd, r);
481
+ // An in-place run on a shared branch commits its own paths only; a refusal
482
+ // comes before the append, so a re-run after the human's fix writes the row once.
483
+ const fid = r.commit === "auto" ? fidOfStatusFile(r.file) : undefined;
484
+ const rec = fid === undefined ? null : activeRecord(cwd, fid);
485
+ if (r.commit === "auto")
486
+ requireRecordOnShared(cwd, r.workflow, rec);
487
+ if (rec !== null) {
488
+ try {
489
+ ownSet(cwd, rec);
490
+ }
491
+ catch (err) {
492
+ if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH)
493
+ throw err;
494
+ log(`no row written to ${r.file}: the commit would be refused: ${err.message}`);
495
+ return { row, commit: null, code: EXIT_FOREIGN_PATH };
496
+ }
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;
303
500
  fs.mkdirSync(path.dirname(r.file), { recursive: true });
304
- 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
+ };
305
543
  if (r.commit === "none")
306
- return { row, commit: null, code: EXIT.OK };
307
- const add = runGit(cwd, ["add", "-A"]);
308
- const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message]) : add;
309
- if (!made.ok) {
310
- log(`row written to ${r.file} but the commit failed: ${made.stderr || made.stdout}`);
311
- return { row, commit: null, code: EXIT_COMMIT };
544
+ return {
545
+ row,
546
+ commit: null,
547
+ code: EXIT.OK,
548
+ ...(progressLine === undefined ? {} : { progressLine }),
549
+ };
550
+ if (rec !== null) {
551
+ let own;
552
+ try {
553
+ own = ownPathCommit(cwd, rec, r.message, { allowEmpty: true });
554
+ }
555
+ catch (err) {
556
+ if (!(err instanceof CommandError) || err.code !== EXIT_FOREIGN_PATH)
557
+ throw err;
558
+ return failed(EXIT_FOREIGN_PATH, `the commit was refused: ${err.message}`);
559
+ }
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
+ };
312
568
  }
313
- return { row, commit: runGit(cwd, ["rev-parse", "HEAD"]).stdout, code: EXIT.OK };
569
+ const add = addAllButCopied(cwd);
570
+ const made = add.ok ? runGit(cwd, ["commit", "--allow-empty", "-m", r.message]) : add;
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
+ };
314
579
  }
315
580
  /** Every mechanical gate check for one step; `ok` false names the first problem per check. */
316
581
  function gateChecks(cwd, o) {
@@ -325,9 +590,7 @@ function gateChecks(cwd, o) {
325
590
  if (o.fid !== undefined) {
326
591
  const tracker = readIssueTracker(cwd);
327
592
  const fid = normaliseFid(o.fid, tracker);
328
- add(`fid ${fid}`, FID_PATTERNS[tracker].test(fid)
329
- ? undefined
330
- : `does not match the ${tracker} shape ${FID_PATTERNS[tracker].source}`, `${tracker} shape`);
593
+ add(`fid ${fid}`, fidProblem(fid, tracker, o.issue), o.issue === "" && tracker !== "none" ? "issue-less shape" : `${tracker} shape`);
331
594
  if (o.token !== undefined) {
332
595
  const root = repoRoot(cwd);
333
596
  const lock = workflowLockPath(root, resolveMonth(root, o.fid, o.month), o.fid);
@@ -342,6 +605,9 @@ function gateChecks(cwd, o) {
342
605
  else if (o.token !== undefined) {
343
606
  throw new CommandError(EXIT.USAGE, "--token needs --fid");
344
607
  }
608
+ else if (o.issue !== undefined) {
609
+ throw new CommandError(EXIT.USAGE, "--issue needs --fid");
610
+ }
345
611
  for (const a of o.artifacts) {
346
612
  if (isUrl(a))
347
613
  continue;
@@ -367,7 +633,7 @@ function gateChecks(cwd, o) {
367
633
  if (o.file === undefined)
368
634
  return checks;
369
635
  const runs = o.ref === undefined ? readRuns(o.file) : readRunsAt(o.file, o.ref);
370
- const rows = activeDoneSteps(runs, o.workflow, { step: o.step, subPlan: o.subPlan });
636
+ const rows = activeDoneSteps(runs, o.workflow, { step: o.step, group: o.group });
371
637
  const row = rows.filter((r) => o.attempt === undefined || r.attempt === o.attempt).at(-1);
372
638
  const rowProblems = [];
373
639
  if (!row) {
@@ -400,14 +666,22 @@ function gateChecks(cwd, o) {
400
666
  // finish
401
667
  // ---------------------------------------------------------------------------
402
668
  const POSITIONS = ["next", "current", "count"];
403
- /** `<step>:<next|current|count>[:<since>]` → the counter it names, from the active run. */
404
- function derivedCounter(file, workflow, spec, subPlan, since) {
405
- const [step, position, specSince] = spec.split(":");
406
- if (!step || !POSITIONS.includes(position ?? "")) {
407
- throw new CommandError(EXIT.USAGE, `"${spec}" must be <step>:<next|current|count>[:<since>]`);
669
+ /**
670
+ * `<step>:<next|current|count>[:all]` → the counter it names, from the active run, or
671
+ * from every run of the workflow with `:all`.
672
+ */
673
+ function derivedCounter(file, workflow, spec, group) {
674
+ const [step, position, scope] = spec.split(":");
675
+ if (!step ||
676
+ !POSITIONS.includes(position ?? "") ||
677
+ (scope !== undefined && scope !== "all")) {
678
+ throw new CommandError(EXIT.USAGE, `"${spec}" must be <step>:<next|current|count>[:all]`);
408
679
  }
409
680
  const count = fs.existsSync(file)
410
- ? activeDoneSteps(readRuns(file), workflow, { step, subPlan }, specSince ?? since).length
681
+ ? (scope === "all" ? allRunsDoneSteps : activeDoneSteps)(readRuns(file), workflow, {
682
+ step,
683
+ group,
684
+ }).length
411
685
  : 0;
412
686
  if (position === "current" && count === 0) {
413
687
  throw new CommandError(EXIT.NO, `${step}: no DONE row in the active run — the step's own row is missing`);
@@ -433,18 +707,121 @@ export function doneDescription(file) {
433
707
  }
434
708
  /** Staged paths a docs-only step may not touch: anything outside the artifact tree and its ledgers. */
435
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
+ }
436
814
  /** `soakAttempt` → `Soak Attempt`, for a comment header. */
437
815
  const titleCase = (key) => key.replace(/([A-Z])/g, " $1").replace(/^./, (c) => c.toUpperCase());
438
816
  /** `<attempt>` filled in, once the attempt is known. */
439
817
  const fill = (s, attempt) => attempt === undefined ? s : s.split(ATTEMPT_TOKEN).join(String(attempt));
440
818
  const list = (v) => v ?? [];
441
- function finish(ctx) {
819
+ async function finish(ctx) {
442
820
  const f = ctx.flags;
443
821
  const file = statusFile(ctx);
444
822
  const workflow = String(f.workflow);
445
823
  const step = String(f.step);
446
- const subPlan = positiveInt(f.subPlan, "sub-plan");
447
- const since = str(f.since);
824
+ const group = positiveInt(f.group, "group");
448
825
  const agents = list(f.agent);
449
826
  // Attempt: given, next from the log, or another step's counter.
450
827
  if ([f.attempt, f.attemptOf].filter((v) => v !== undefined).length > 1)
@@ -452,11 +829,11 @@ function finish(ctx) {
452
829
  let attempt;
453
830
  let derived = false;
454
831
  if (f.attemptOf !== undefined) {
455
- attempt = derivedCounter(file, workflow, String(f.attemptOf), subPlan, since);
832
+ attempt = derivedCounter(file, workflow, String(f.attemptOf), group);
456
833
  derived = true;
457
834
  }
458
835
  else if (f.attempt === "next") {
459
- attempt = derivedCounter(file, workflow, `${step}:next`, subPlan, since);
836
+ attempt = derivedCounter(file, workflow, `${step}:next`, group);
460
837
  derived = true;
461
838
  }
462
839
  else {
@@ -467,7 +844,7 @@ function finish(ctx) {
467
844
  const eq = spec.indexOf("=");
468
845
  if (eq <= 0)
469
846
  throw new CommandError(EXIT.USAGE, `--count-field "${spec}" must be key=<counter>`);
470
- extras[spec.slice(0, eq)] = derivedCounter(file, workflow, spec.slice(eq + 1), subPlan, since);
847
+ extras[spec.slice(0, eq)] = derivedCounter(file, workflow, spec.slice(eq + 1), group);
471
848
  }
472
849
  const scope = str(f.scope);
473
850
  if (scope !== undefined)
@@ -511,6 +888,9 @@ function finish(ctx) {
511
888
  continue;
512
889
  if (k === "Failures")
513
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;
514
894
  else if (!(k in fields))
515
895
  fields[k] = v;
516
896
  }
@@ -533,12 +913,75 @@ function finish(ctx) {
533
913
  if (strategy !== undefined && !STRATEGIES.includes(strategy))
534
914
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
535
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;
536
929
  const clampLog = str(f.clampLog);
537
930
  if (clampLog !== undefined) {
538
931
  const [clampStep, clampAttempt] = fill(clampLog, attempt).split(":");
539
932
  const fid = path.basename(path.dirname(file));
540
933
  extras.clamped = readRecords(clampLogPath(ctx.cwd, fid, clampStep, positiveInt(clampAttempt, "clamp-log attempt")), (l) => ctx.log(`skipping a malformed clamp record: ${l}`));
541
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
+ }
542
985
  // What the gate would refuse, refused before anything is written.
543
986
  const pre = gateChecks(ctx.cwd, {
544
987
  workflow,
@@ -564,8 +1007,73 @@ function finish(ctx) {
564
1007
  const commit = str(f.commit) ?? "auto";
565
1008
  if (!["auto", "none"].includes(commit))
566
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
+ }
567
1075
  if (f.docsOnly === true && commit === "auto") {
568
- runGit(ctx.cwd, ["add", "-A"]);
1076
+ addAllButCopied(ctx.cwd);
569
1077
  const outside = runGit(ctx.cwd, ["diff", "--cached", "--name-only"])
570
1078
  .stdout.split("\n")
571
1079
  .filter((p) => p !== "" && !DOCS_ONLY.test(p));
@@ -586,32 +1094,6 @@ function finish(ctx) {
586
1094
  runOrStepField(readRuns(file), workflow, "pushMode") === "LOCAL")
587
1095
  message += " bkit [verbose ci]";
588
1096
  }
589
- const written = writeStepRow(ctx.cwd, {
590
- file,
591
- workflow,
592
- step,
593
- verdict,
594
- failures,
595
- attempt,
596
- subPlan,
597
- strategy,
598
- artifacts,
599
- extras,
600
- parentSha: str(f.parentSha),
601
- commit: commit,
602
- message,
603
- }, ctx.log);
604
- const checks = gateChecks(ctx.cwd, {
605
- file,
606
- workflow,
607
- step,
608
- subPlan,
609
- attempt,
610
- artifacts,
611
- verdictRequired: false,
612
- allowed,
613
- placeholders: [],
614
- });
615
1097
  // The step's tracker comment: header fields in one fixed order.
616
1098
  let comment = null;
617
1099
  const number = str(f.number);
@@ -619,16 +1101,14 @@ function finish(ctx) {
619
1101
  const title = str(f.title);
620
1102
  if (title === undefined)
621
1103
  throw new CommandError(EXIT.USAGE, "--number needs --title");
622
- const count = str(f.subPlanCount);
1104
+ const count = str(f.groupCount);
623
1105
  const header = [
624
1106
  ...(verdict === undefined ? [] : [["Verdict", verdict]]),
625
1107
  ...(failures === undefined ? [] : [["Failures", String(failures)]]),
626
1108
  ...(scope === undefined ? [] : [["Scope", scope]]),
627
- ...(subPlan === undefined
1109
+ ...(group === undefined
628
1110
  ? []
629
- : [
630
- ["Sub-plan", `${subPlan}${count === undefined ? "" : `/${count}`}`],
631
- ]),
1111
+ : [["Group", `${group}${count === undefined ? "" : `/${count}`}`]]),
632
1112
  ...(derived && attempt !== undefined
633
1113
  ? [["Attempt", String(attempt)]]
634
1114
  : []),
@@ -661,6 +1141,41 @@ function finish(ctx) {
661
1141
  bodyFile: f.commentBody === true ? fileArtifacts[0] : undefined,
662
1142
  });
663
1143
  }
1144
+ // --post: post, then record the engine-action row, then the step row and commit
1145
+ // carry both. A re-run with the same key and body is deduped, never posted twice.
1146
+ let tracker;
1147
+ if (f.post === true) {
1148
+ if (comment === null)
1149
+ throw new CommandError(EXIT.USAGE, "--post needs --number");
1150
+ const key = actionKey(workflow, fs.existsSync(file) ? runNumber(readRuns(file), workflow) : 1, step, group, attempt, "comment");
1151
+ tracker = await postForVerb(ctx, comment, { fid: fidOfStatusFile(file), file, key });
1152
+ }
1153
+ const written = writeStepRow(ctx.cwd, {
1154
+ file,
1155
+ workflow,
1156
+ step,
1157
+ verdict,
1158
+ failures,
1159
+ attempt,
1160
+ group,
1161
+ strategy,
1162
+ artifacts,
1163
+ extras,
1164
+ parentSha: str(f.parentSha),
1165
+ commit: commit,
1166
+ message,
1167
+ }, ctx.log);
1168
+ const checks = gateChecks(ctx.cwd, {
1169
+ file,
1170
+ workflow,
1171
+ step,
1172
+ group,
1173
+ attempt,
1174
+ artifacts,
1175
+ verdictRequired: false,
1176
+ allowed,
1177
+ placeholders: [],
1178
+ });
664
1179
  const pass = checks.every((c) => c.ok);
665
1180
  for (const c of checks.filter((x) => !x.ok))
666
1181
  ctx.log(`${c.check}: ${c.detail}`);
@@ -670,10 +1185,15 @@ function finish(ctx) {
670
1185
  attempt: attempt ?? null,
671
1186
  fields,
672
1187
  row: written.row,
1188
+ parentSha: written.row.parentSha,
673
1189
  commit: written.commit,
1190
+ ...(written.progressLine === undefined ? {} : { progressLine: written.progressLine }),
674
1191
  pass,
675
1192
  checks,
676
1193
  comment,
1194
+ // Written after the step's commit, so the commit never carries it.
1195
+ commentFile: commentFileOf(ctx.cwd, comment),
1196
+ ...(tracker === undefined ? {} : { tracker }),
677
1197
  });
678
1198
  if (written.code !== EXIT.OK)
679
1199
  return written.code;
@@ -699,7 +1219,11 @@ const COMMIT_FLAGS = [
699
1219
  type: "string",
700
1220
  help: "commit the step started from (default: HEAD now, before this commit)",
701
1221
  },
702
- { name: "commit", type: "string", help: "auto (default: git add -A + commit) or none" },
1222
+ {
1223
+ name: "commit",
1224
+ type: "string",
1225
+ help: "auto (default: git add -A, never the worktree.copy entries, + commit) or none",
1226
+ },
703
1227
  { name: "message", type: "string", help: "commit message (required unless --commit=none)" },
704
1228
  ];
705
1229
  export const stepsCommand = {
@@ -708,6 +1232,7 @@ export const stepsCommand = {
708
1232
  verbs: {
709
1233
  done: {
710
1234
  summary: "Append a step-done row and commit it (parentSha captured first).",
1235
+ use: "workflow",
711
1236
  flags: [
712
1237
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
713
1238
  WORKFLOW_FLAG,
@@ -729,7 +1254,7 @@ export const stepsCommand = {
729
1254
  type: "string",
730
1255
  help: "non-negative integer (0 included), or `next` to derive it from the log",
731
1256
  },
732
- SUB_PLAN_FLAG,
1257
+ GROUP_FLAG,
733
1258
  { name: "strategy", type: "string", help: "STANDARD|PIVOT|FINAL" },
734
1259
  {
735
1260
  name: "artifact",
@@ -748,11 +1273,15 @@ export const stepsCommand = {
748
1273
  output: {
749
1274
  row: "the appended step-done row",
750
1275
  commit: "the new commit's sha, or null with --commit=none",
1276
+ progressLine: "the exact chat progress line after a successful numbered completion",
751
1277
  },
1278
+ textOmit: ["row"],
752
1279
  exitCodes: {
753
1280
  [EXIT_NO_STATUS]: "--attempt=next could not read status.jsonl",
754
1281
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory",
755
- [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",
1283
+ [EXIT_FOREIGN_PATH]: "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1284
+ [EXIT_NO_RECORD]: "a debug run on dev/main with no shared-checkout record: nothing written or committed",
756
1285
  },
757
1286
  run: (ctx) => {
758
1287
  const f = ctx.flags;
@@ -775,7 +1304,7 @@ export const stepsCommand = {
775
1304
  if (strategy !== undefined && !STRATEGIES.includes(strategy)) {
776
1305
  throw new CommandError(EXIT.USAGE, "--strategy must be STANDARD|PIVOT|FINAL");
777
1306
  }
778
- const subPlan = positiveInt(f.subPlan, "sub-plan");
1307
+ const group = positiveInt(f.group, "group");
779
1308
  const commit = str(f.commit) ?? "auto";
780
1309
  if (!["auto", "none"].includes(commit))
781
1310
  throw new CommandError(EXIT.USAGE, "--commit must be auto or none");
@@ -784,7 +1313,7 @@ export const stepsCommand = {
784
1313
  if (bad.length > 0)
785
1314
  throw new CommandError(EXIT_ARTIFACT, bad.join("; "));
786
1315
  const attempt = f.attempt === "next"
787
- ? derivedCounter(file, workflow, `${step}:next`, subPlan, undefined)
1316
+ ? derivedCounter(file, workflow, `${step}:next`, group)
788
1317
  : nonNegativeInt(f.attempt, "attempt");
789
1318
  const written = writeStepRow(ctx.cwd, {
790
1319
  file,
@@ -794,7 +1323,7 @@ export const stepsCommand = {
794
1323
  verdict,
795
1324
  failures,
796
1325
  attempt,
797
- subPlan,
1326
+ group,
798
1327
  strategy,
799
1328
  artifacts,
800
1329
  extras: Object.fromEntries(list(f.field).map(extraField)),
@@ -802,12 +1331,17 @@ export const stepsCommand = {
802
1331
  commit: commit,
803
1332
  message: str(f.message),
804
1333
  }, ctx.log);
805
- 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
+ });
806
1339
  return written.code;
807
1340
  },
808
1341
  },
809
1342
  finish: {
810
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",
811
1345
  flags: [
812
1346
  { ...FILE_FLAG, help: "path to status.jsonl (created if absent)" },
813
1347
  WORKFLOW_FLAG,
@@ -847,18 +1381,13 @@ export const stepsCommand = {
847
1381
  type: "string",
848
1382
  help: "<step>:<next|current|count> — the attempt is that step's counter in the active run",
849
1383
  },
850
- {
851
- name: "since",
852
- type: "string",
853
- help: "run field holding a timestamp (soakEntryAt); only rows after it count",
854
- },
855
1384
  {
856
1385
  name: "count-field",
857
1386
  type: "string",
858
1387
  repeatable: true,
859
- help: "key=<step>:<next|current|count>[:<since>] — a row field holding another counter",
1388
+ help: "key=<step>:<next|current|count>[:all] — a row field holding another counter; :all counts every run",
860
1389
  },
861
- SUB_PLAN_FLAG,
1390
+ GROUP_FLAG,
862
1391
  {
863
1392
  name: "strategy",
864
1393
  type: "string",
@@ -881,6 +1410,11 @@ export const stepsCommand = {
881
1410
  type: "boolean",
882
1411
  help: "refuse (exit 9) when the step staged anything outside docs/plans/ and the docs ledgers",
883
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
+ },
884
1418
  ...COMMIT_FLAGS.map((c) => c.name === "message"
885
1419
  ? {
886
1420
  ...c,
@@ -899,7 +1433,11 @@ export const stepsCommand = {
899
1433
  },
900
1434
  { name: "number", type: "string", help: "step number: print the step's tracker comment" },
901
1435
  { name: "title", type: "string", help: "step title for the comment heading" },
902
- { name: "sub-plan-count", type: "string", help: "y of the comment's Sub-plan x/y" },
1436
+ {
1437
+ ...POST_FLAG,
1438
+ help: "post the comment (needs --number) to the issue the status file's FID names, before the row and commit; prints `tracker`",
1439
+ },
1440
+ { name: "group-count", type: "string", help: "y of the comment's Group x/y" },
903
1441
  {
904
1442
  name: "link-ref",
905
1443
  type: "string",
@@ -929,26 +1467,42 @@ export const stepsCommand = {
929
1467
  attempt: "the attempt recorded, or null",
930
1468
  fields: "the other header fields the agents' prompts declare (Spike, Mode, Affected)",
931
1469
  row: "the appended step-done row",
1470
+ parentSha: "the row's parentSha: HEAD before the step's commit",
932
1471
  commit: "the new commit's sha, or null with --commit=none",
933
1472
  pass: "every gate check passed",
1473
+ progressLine: "the exact chat progress line after a successful numbered completion",
934
1474
  checks: "[{check, ok, detail}] per gate check",
935
1475
  comment: "the step's tracker comment body (with --number), else null",
936
- reask: "verdict read failed: {agent, artifact} to re-ask (exit 4 / 5 / 6 only)",
937
- problem: "why the verdict read failed (exit 4 / 5 / 6 only)",
1476
+ commentFile: COMMENT_FILE_OUTPUT,
1477
+ tracker: TRACKER_OUTPUT,
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)",
938
1484
  },
1485
+ textOmit: ["row", { key: "checks", when: (_checks, out) => out.pass === true }],
939
1486
  exitCodes: {
940
1487
  [EXIT_NO_STATUS]: "status.jsonl is not valid NDJSON",
941
1488
  [EXIT_EMPTY]: "an --agent's artifact is missing or empty (nothing written)",
942
1489
  [EXIT_PENDING]: "an --agent's header still has a PENDING field — re-ask it (nothing written)",
943
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)",
944
1491
  [EXIT_ARTIFACT]: "an --artifact is missing, empty, or outside the working directory (nothing written)",
945
- [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",
1493
+ [EXIT_FOREIGN_PATH]: "nothing written, nothing committed: a path that was dirty before an in-place run changed during it",
1494
+ [EXIT_NO_RECORD]: "a debug run on dev/main with no shared-checkout record: nothing written or committed",
946
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)",
947
1500
  },
948
1501
  run: finish,
949
1502
  },
950
1503
  verdict: {
951
1504
  summary: "Read an artifact's header down to <!-- verdict:end -->.",
1505
+ use: "by-hand",
952
1506
  flags: [
953
1507
  { name: "file", type: "string", required: true, help: "the subagent's artifact" },
954
1508
  ...ALLOWED_FLAGS,
@@ -977,6 +1531,7 @@ export const stepsCommand = {
977
1531
  },
978
1532
  gate: {
979
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",
980
1535
  flags: [
981
1536
  {
982
1537
  ...FILE_FLAG,
@@ -990,7 +1545,12 @@ export const stepsCommand = {
990
1545
  },
991
1546
  WORKFLOW_FLAG,
992
1547
  STEP_FLAG,
993
- SUB_PLAN_FLAG,
1548
+ GROUP_FLAG,
1549
+ {
1550
+ name: "progress-number",
1551
+ type: "string",
1552
+ help: "render this completed numbered position without writing a status row",
1553
+ },
994
1554
  {
995
1555
  name: "attempt",
996
1556
  type: "string",
@@ -1020,6 +1580,11 @@ export const stepsCommand = {
1020
1580
  help: "NAME=value — the held placeholder must be non-empty",
1021
1581
  },
1022
1582
  { name: "fid", type: "string", help: "the FID must match the wired tracker's shape" },
1583
+ {
1584
+ name: "issue",
1585
+ type: "string",
1586
+ help: 'the run\'s issue id, or "" for a run with no issue (then the FID must be issue-less); needs --fid',
1587
+ },
1023
1588
  { name: "month", type: "string", help: "month bucket of the lock (with --token)" },
1024
1589
  {
1025
1590
  name: "token",
@@ -1027,7 +1592,11 @@ export const stepsCommand = {
1027
1592
  help: "the workflow lock must be held with this token (needs --fid)",
1028
1593
  },
1029
1594
  ],
1030
- 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
+ },
1031
1600
  exitCodes: {
1032
1601
  [EXIT_NO_STATUS]: "status.jsonl missing (on disk, or on --ref), unreadable, or not valid NDJSON",
1033
1602
  },
@@ -1035,7 +1604,30 @@ export const stepsCommand = {
1035
1604
  const f = ctx.flags;
1036
1605
  const file = str(f.file) === undefined ? undefined : statusFile(ctx);
1037
1606
  const workflow = String(f.workflow);
1038
- const subPlan = positiveInt(f.subPlan, "sub-plan");
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
+ }
1039
1631
  if (f.attempt !== undefined && f.attemptOf !== undefined)
1040
1632
  throw new CommandError(EXIT.USAGE, "give --attempt or --attempt-of, not both");
1041
1633
  if (f.attemptOf !== undefined && file === undefined)
@@ -1046,19 +1638,20 @@ export const stepsCommand = {
1046
1638
  if (ref !== undefined && f.attemptOf !== undefined)
1047
1639
  throw new CommandError(EXIT.USAGE, "--attempt-of reads the file on disk; give --attempt with --ref");
1048
1640
  const attempt = f.attemptOf !== undefined
1049
- ? derivedCounter(file, workflow, String(f.attemptOf), subPlan, undefined)
1641
+ ? derivedCounter(file, workflow, String(f.attemptOf), group)
1050
1642
  : nonNegativeInt(f.attempt, "attempt");
1051
1643
  const checks = gateChecks(ctx.cwd, {
1052
1644
  file,
1053
1645
  ref,
1054
1646
  workflow,
1055
1647
  step: String(f.step),
1056
- subPlan,
1648
+ group,
1057
1649
  attempt,
1058
1650
  artifacts: list(f.artifact).map((a) => fill(a, attempt)),
1059
1651
  verdictRequired: f.verdictRequired === true,
1060
1652
  allowed: allowedVerdicts(f),
1061
1653
  fid: str(f.fid),
1654
+ issue: str(f.issue),
1062
1655
  month: str(f.month),
1063
1656
  token: str(f.token),
1064
1657
  placeholders: list(f.placeholder),
@@ -1066,12 +1659,26 @@ export const stepsCommand = {
1066
1659
  const pass = checks.every((c) => c.ok);
1067
1660
  for (const c of checks.filter((x) => !x.ok))
1068
1661
  ctx.log(`${c.check}: ${c.detail}`);
1069
- 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 }) });
1070
1676
  return pass ? EXIT.OK : EXIT.NO;
1071
1677
  },
1072
1678
  },
1073
1679
  stub: {
1074
1680
  summary: "Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top.",
1681
+ use: "workflow",
1075
1682
  flags: [
1076
1683
  { name: "from", type: "string", required: true, help: "the prior versioned artifact" },
1077
1684
  { name: "to", type: "string", required: true, help: "the artifact to create" },