@cbartens/bkit 6.1.0 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -225,7 +225,7 @@ This section applies to `.bkit/core/prompts/*.md`, `.bkit/core/workflows/*.md`,
225
225
 
226
226
  ## Docs
227
227
 
228
- This section applies to `.agents/**`, `.bkit/*.md` and `docs/*.md`. § All Agent-Read Files applies as well.
228
+ This section applies to `.agents/**`, `.bkit/*.md`, `docs/*.md` and `.bkit/templates/docs/*.md`. § All Agent-Read Files applies as well.
229
229
 
230
230
  - **Rules header:** Open every doc with a `> [!CAUTION]` box holding `**Purpose:**` and `**Rules:**`.
231
231
  - Why: The box tells an agent what belongs in the doc and how to edit it before it reads the rest. The **Authoring** rule in `.agents/rules.md` has every agent follow it.
@@ -238,6 +238,31 @@ This section applies to `.agents/**`, `.bkit/*.md` and `docs/*.md`. § All Agent
238
238
  - **Index:** Give each new doc one row in `.agents/docs.md`, with the phases that read it and a one-line scope, and copy no text from the doc into it.
239
239
  - Why: The index is how agents find docs. Every prompt's Process starts by reading `.agents/docs.md` and loading the docs it lists for the task.
240
240
 
241
+ - **Mermaid for diagrams:** Draw every diagram of flow, order, dependency or relationship as Mermaid; directory trees and command output stay plain text.
242
+ - Why: Mermaid renders on GitHub and reads as text to an agent, while ASCII art breaks when edited and misreads in a diff. A doc needs no chart, but a chart it has follows this rule.
243
+ - Say in one sentence what the arrows mean, and use node names from the doc's tables.
244
+ - Keep a chart to about 15 nodes, and split larger ones with `subgraph` or a second chart.
245
+ - Use only `flowchart`, `sequenceDiagram`, `erDiagram` or `stateDiagram-v2`, quote every label, and set no colours, `style` or `classDef`.
246
+ - Example: `.bkit/core/.bkit/templates.md` § Project docs — adoption order.
247
+
248
+ - **Project-doc starters:** A starter in `.bkit/templates/docs/*.md` opens with a rules box holding **Purpose**, the rules, **Not here** and **Update when**.
249
+ - Why: A person or the `bkit-utility-update-documentation` prompt fills a starter, and each works from the starter alone, so the starter carries the steps and the rules.
250
+ - **Purpose** says what the doc holds and the question it answers, with no "Read before …" clause, because the phase columns of `.agents/docs.md` say when to read it.
251
+ - **Not here** names what belongs elsewhere and where. **Update when** names the events that change the doc.
252
+ - A section marked `> **bkit practice:**` keeps its heading text and stays a separate section from the project's blanks.
253
+ - Example: `.bkit/templates/docs/components.md`.
254
+
255
+ - **Starter facts only:** In a starter in `.bkit/templates/docs/*.md`, write the current state with no history, take every fact from code, config or an approved spec, and never copy template example text as a fact.
256
+ - Why: Agents act on what a doc says, so a stale or invented line causes wrong work.
257
+ - Put each unknown under `## Open questions`.
258
+
259
+ - **Starter: write once, link elsewhere:** In a starter in `.bkit/templates/docs/*.md`, write each topic once, link to it from other docs, and name the file that holds a value instead of typing the value.
260
+ - Why: A second copy of a value goes stale and contradicts the first.
261
+ - Use a table for facts, and prose only for reasoning.
262
+
263
+ - **Starter empty state:** In a starter in `.bkit/templates/docs/*.md`, write `Not applicable: {reason}` for a doc, or a section, that does not apply to the project.
264
+ - Why: A reason separates a doc that does not apply from one nobody filled in.
265
+
241
266
  ## Prompts and Workflows
242
267
 
243
268
  This section applies to `.bkit/core/prompts/*.md`, the subagent prompts, and `.bkit/core/workflows/*.md`, the orchestrator prompts behind the slash commands. § All Agent-Read Files applies as well. § Output Formatting covers what these files ask an agent to write. § Prompts Only and § Workflows Only add rules for one kind of file.
@@ -485,8 +510,9 @@ A doc template is the skeleton of a document an agent fills in: the plan (`docs/
485
510
  | Build | `@bkit-build-plan-tasks` | Works each task until its `DONE WHEN` holds, and logs `DONE` or `BLOCKED`. It never edits a planned test and never ticks a task box. |
486
511
  | Verify | `@bkit-build-plan-verify`, then `bkit tasks tick` | Checks each task against the code. The engine ticks the tasks that pass. |
487
512
 
488
- - **Template is shape, prompt owns rules:** A template holds headings, tables, placeholders, checkbox labels, owner callouts and the markers the engine parses, and nothing else.
513
+ - **Fill-in steps in the template, acting rules in the prompt:** A template holds headings, tables, placeholders, checkbox labels, owner callouts, the markers the engine parses and the instructions for filling it in; the rules for acting on it live in the prompts.
489
514
  - Why: Different agents write, review, convert, build and verify the plan, and a rule in the template reaches all of them, whether it applies or not.
515
+ - Project-doc starters in `.bkit/templates/docs/*.md` carry their own fill-in steps, because no prompt fills them.
490
516
  - Every rule for filling, reviewing or acting on a template lives in the prompt that acts on it, as a labelled Contract bullet worded the same in every prompt that carries it. `.bkit/instructions.md` § Template Instructions names the prompts that carry each rule and keeps their wording identical.
491
517
  - Exception: **Audit templates carry their procedure**.
492
518
  - Example (`docs/templates/bkit-plan.md` § Agent Execution Runbook): the plan template holds the shape of a task block.
@@ -628,17 +654,26 @@ This section applies to `.bkit/core/workflows/*.md`. § Prompts and Workflows ap
628
654
  - [ ] Each unconfirmed item deferred (`decisions pending --defer`)
629
655
  ```
630
656
 
631
- - **Human questions:** Only the orchestrator asks the owner, in the session, with every question of the round in one plain-text message, never through a subagent or a host question tool.
657
+ - **Human questions:** Only the orchestrator asks the owner, in the session, in plain text, never through a subagent or a host question tool, at every question point.
632
658
  - Why: The owner answers a whole round at once and may answer with one word, so "yes" must safely take the recommendations and a letter must map to exactly one option. Recording the wait and the reply lets a resumed run see where it stopped.
633
659
  - Each question takes this shape:
634
660
  ```markdown
635
- **Q{n} — {title}:** {the question, worded so that "yes" accepts the recommendation}
636
- Options: A) {option} / B) {option}
637
- Recommended: A) {option}
661
+ **Q{n} — {title}:** {what you are deciding, in plain English, worded so "yes" takes the recommendation}
662
+ A) {option} — {what happens if you pick it}
663
+ B) {option} — {what happens if you pick it}
664
+ Recommended: A) {option} — {why}
665
+ Default if unanswered: {what happens}
638
666
  ```
639
- - A question no agent can settle (a hard blocker) has `No recommendation` in place of the `Recommended:` line.
640
- - Number questions from `Q1`, and letter options `A)`, `B)`, `C)` in order.
641
- - Say what the owner must decide and what each option does, in plain English, before naming any file, test or identifier.
667
+ - Number questions from `Q1`, and letter options `A)`, `B)`, `C)` in order, one option per line.
668
+ - Say what the owner must decide, what each option does and the reason for the recommendation, in plain English, before naming any file, test or identifier.
669
+ - `Default if unanswered:` takes one phrase from this closed set, and joins two with `; `: `the run waits for you`, `taken as A when nobody can be asked`, `the run stops when nobody can be asked`, `the plan assumes A`, `the plan stops at Gate 1 until you answer`, `the design assumes A`, `written as a needs-decision deferral`.
670
+ - A point that never has a recommendation drops the "yes" half of the question and of the reply line.
671
+ - A question no agent can settle (a hard blocker) has `Recommended: none — {why}` in place of a recommendation, and "yes" never answers it.
672
+ - The stop option reads `Stop — the run ends here with a handover; the next run resumes here` mid-run, and `Stop — nothing changes; the run can be started again` at Step 1.
673
+ - End each message once with the reply line, naming what "stop" does at that point: `Reply with a letter per question, or "yes" to take every recommendation. "stop" ends here with a handover; the next run resumes here.`
674
+ - When a round has 3 or more questions, add `Or say "one by one" and I'll ask them one at a time.` The "one by one" route counts as the one turn or pause it replaces, and follows the count of questions asked in the message.
675
+ - A step that needs an action, not a decision, writes `**Action needed — {title}:** {what to do}. Then say "continue".`
676
+ - Before a status file exists, write no status rows. Wait with `end turn → wait for the answer; no status file yet`.
642
677
  - Look facts up in the repo, docs and tools. Ask the owner only for decisions.
643
678
  - Run each round in this order:
644
679
  1. Narrate the round.
@@ -646,11 +681,21 @@ This section applies to `.bkit/core/workflows/*.md`. § Prompts and Workflows ap
646
681
  3. End the turn.
647
682
  4. When the reply arrives, record it with `bkit status row --type=owner-answer` before doing anything else.
648
683
  - Before the branches of a step that routes on the answer, say that a reply naming a letter (`B`, `B)` or `B) {option}`) means the option that letter labels.
649
- - Example (`bkit-debug.md` § Loop Question): "yes" stops the loop, which is the recommendation. The question already gives the reason, so the `Recommended:` line needs none.
684
+ - Example (`bkit-debug.md` § Loop Question): the count did not fall.
685
+ ```markdown
686
+ **Q1 — Fix:** The count did not fall between the first and the last round (4 → 4). Stop here instead of trying again?
687
+ A) Stop — the run ends here with a handover; the next run resumes here
688
+ B) Try again — another round runs with the same limit
689
+ Recommended: A) Stop — another round is unlikely to change a count that stayed at 4
690
+ Default if unanswered: the run waits for you
691
+ ```
692
+ - Example (`bkit-build.md` § Verify gap): a task fails its check.
650
693
  ```markdown
651
- **Q1 — Fix:** The last fix attempt left no fewer failures. Stop here instead of trying again?
652
- Options: A) Stop / B) Try again
653
- Recommended: A) Stop
694
+ **Q1 — Gap:** Task 3 still fails its check after the fix. Accept it as it is?
695
+ A) Accept — the task is logged as accepted and the build continues
696
+ B) Fix now — the fix runs again before the build continues
697
+ Recommended: B) Fix now — the failing check is in code this plan changed
698
+ Default if unanswered: taken as A when nobody can be asked
654
699
  ```
655
700
  - Example (`bkit-design.md` § Step 3 — Grill): the shape for a round of several questions.
656
701
 
@@ -48,6 +48,8 @@ CI check names come from `package.json` `bkit.testing.ciCapstone` (default `bkit
48
48
 
49
49
  No workflow file calls a script outside a `bkit` command; the slop plugin `bkit-slop-type-suppression.mjs` is a copy-and-own template (`scripts/slop/`). `bkit-cloud.yml` reads the debug limits from `package.json` with `jq` because its guards run before bkit is installed.
50
50
 
51
+ **Bounded correction:** `bkit ledgers append --operation=<id>` is replay-safe; a guaranteed no-write rejection prints a structured error (effects = none, correctable = true) with a `scope`. The corrected candidate is `bkit ledgers append --correction-of=<rejected operation> --operation=<fresh id>`; `bkit counters correction` spends from the same two-retry budget per scope, and a replay of a counted operation spends nothing only for the same request: `--request-hash` carries the candidate's canonical hash (`ledgers append --correction-of` passes it itself), and the same id with other rows is refused. `bkit ledgers query` reads a ledger's canonical winners without writing, so an agent checks state instead of guessing it. `bkit runs handoff` records CI poll observations so a re-entered `bkit runs dispatch --invocation=<id>` resumes from persisted rows, with no counter supplied. `bkit counters correction` works inside a workflow run only.
52
+
51
53
  First install, upgrade and uninstall: `.bkit/install.md`. Upgrade prompt to paste into your AI: `.bkit/install.md` § Upgrade — already installed.
52
54
 
53
55
  <!-- cli:start -->
@@ -57,10 +59,10 @@ First install, upgrade and uninstall: `.bkit/install.md`. Upgrade prompt to past
57
59
  <!-- prettier-ignore -->
58
60
  | Command | Flags | What it does |
59
61
  | --- | --- | --- |
60
- | `bkit install` | `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>` `--auto=<claude\|cursor\|opencode>` `--tracker=<name>` `--auto-revert` | Install or re-sync the named modules plus the core files. |
62
+ | `bkit install` | `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>` `--auto=<claude\|cursor\|opencode\|codex>` `--tracker=<name>` `--auto-revert` | Install or re-sync the named modules plus the core files. |
61
63
  | `bkit check` | — | Drift gate: exit 1 when a managed file needs re-rendering. The CI gate. |
62
64
  | `bkit upgrade` | `--to=<version>` `--latest` `--auto-apply` `--dry-run` | Re-render everything installed; --to / --latest bump @cbartens/bkit first. |
63
- | `bkit uninstall` | `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>` `--auto=<claude\|cursor\|opencode>` `--dry-run` `--force` `--nuke` `--yes` | Remove bkit-managed files and strip managed blocks; no flags = everything. |
65
+ | `bkit uninstall` | `--claude` `--codex` `--antigravity` `--cursor` `--opencode=<provider>` `--auto=<claude\|cursor\|opencode\|codex>` `--dry-run` `--force` `--nuke` `--yes` | Remove bkit-managed files and strip managed blocks; no flags = everything. |
64
66
  | `bkit doctor` | — | Preflight and advisory replay; rewrites .bkit/advisories.md only. Exits 0. |
65
67
  | `bkit tips` | `--workflow=<name>` `--all` | What this repo has not set up yet, most useful first. Exits 0. |
66
68
  | `bkit status` | — | Current host and provider. Writes nothing. Exits 0. |
@@ -83,11 +85,11 @@ Sync, push, land and rebase branches; stamp and read a doc's base-commit anchor.
83
85
  | Verb | Use | Flags | What it does |
84
86
  | --- | --- | --- | --- |
85
87
  | `parse` | workflow | **`--prompt-file`** `--workflow` | Read an explicitly named or existing branch from the session prompt. |
86
- | `sync` | workflow | `--head` `--merge` `--merge-docs` `--fid` `--file` `--sentinel` | Fetch origin/dev; report whether it is an ancestor of HEAD (Path A/B) and how far docs/ and the ledgers are behind; optionally merge it in. |
88
+ | `sync` | workflow | `--feature-state` `--month` `--reconcile-feature` `--head` `--merge` `--target` `--merge-docs` `--fid` `--file` `--sentinel` | Fetch origin/dev; report whether it is an ancestor of HEAD (Path A/B) and how far docs/ and the ledgers are behind; optionally merge it in. |
87
89
  | `regenerate` | workflow | `--fid` `--attempt` `--file` | Run a declared bkit:generate on the feature branch and commit only the paths it changed (ship Step 10's fix round). |
88
- | `push` | workflow | **`--mode`** `--set-upstream` `--ahead-of` `--commit` `--label` `--file` `--workflow` `--require-ci` `--open-pr` `--fid` | Push the current branch with exactly one git push: plain for dev/main, --force-with-lease otherwise; 81 tests lock held. |
90
+ | `push` | workflow | **`--mode`** `--set-upstream` `--ahead-of` `--commit` `--label` `--file` `--workflow` `--require-ci` `--open-pr` `--fid` | Push the current branch with exactly one git push: plain for dev/main, --force-with-lease otherwise; when the pre-push hook's lock status file says so, 81 tests lock held, 4 tests lock refused the run or stopped it at the hold limit. |
89
91
  | `fast-forward` | workflow | **`--onto`** | Fetch a remote branch and fast-forward the checkout onto it; refuse when diverged. |
90
- | `scan-diff` | by hand | **`--base`** `--paths` `--marker` `--code` `--disabled-tests` `--expect-none` | Exit 0 when the branch's diff from --base matches (paths, an added marker line, a source change, or a disabled test); 1 when not — --disabled-tests turns that round: 1 when a test was disabled or lost an assertion, 0 when none was. |
92
+ | `scan-diff` | by hand | `--base` `--paths` `--marker` `--code` `--disabled-tests` `--expect-none` | Exit 0 when the branch's diff from --base matches (paths, an added marker line, a source change, or a disabled test); 1 when not — --disabled-tests turns that round: 1 when a test was disabled or lost an assertion, 0 when none was. |
91
93
  | `force-build` | workflow | **`--fid`** **`--file`** **`--workflow`** `--label` `--open-pr` `--title-set` | Force a full CI build: put [force build] on the open PR's title, then push an empty marker commit (once per run). |
92
94
  | `rebase` | workflow | `--log-file` `--sentinel` `--file` | Drive a rebase to completion, auto-resolving ledger (union), lockfile (regenerate), generated-register (take the target's copy, rebuild after), embedded generated-block (take the target's block, merge the rest, rebuild after) and install-record (merge entry by entry, the target's value where both changed) conflicts; refuse and abort on anything else. |
93
95
  | `sync-dev` | workflow | — | After a merge, fast-forward local dev to origin/dev without checking it out or pushing; frozen install when the main checkout is on dev and moved. |
@@ -113,7 +115,7 @@ Gates CI and the git hooks run.
113
115
  | Verb | Use | Flags | What it does |
114
116
  | --- | --- | --- | --- |
115
117
  | `slop` | by hand | `--base` | Fail when the working tree adds or worsens slop on net against a base ref. |
116
- | `prose` | by hand | `--glob` | Run Vale over the markdown files the globs select; fail when Vale or required styles are unavailable. |
118
+ | `prose` | by hand | `--glob` | Run Vale over tracked and unignored Markdown, or explicit globs; fail when sources, Vale or required styles are unavailable. |
117
119
  | `skip-token` | by hand | `--ref` | Whether a commit message carries a GitHub skip-CI token ([skip ci] and kin). |
118
120
  | `min-push` | by hand | `--ref` `--base` `--update` | Exit 0 when every file a push changes is one bkit writes or bkit.testing.minPushPaths / ciSkipPaths adds (the pre-push light gate). |
119
121
  | `push-gate` | by hand | **`--gate`** | Run a consumer push gate and record successful full-gate proof for the exact clean commit. |
@@ -140,7 +142,7 @@ Clamp context artifacts; scan ledgers; write the run's diff and a build group's
140
142
  | `clamp-log` | workflow | `--log` `--fid` `--step` `--attempt` `--reset` | Read a step's clamp records (the status row's clamped array), or reset the log. |
141
143
  | `ledger-scan` | workflow | **`--terms`** **`--source`** **`--artifact`** `--log` `--fid` `--step` `--attempt` `--reset-log` | Write a ledger's lines matching query terms, strongest first, then clamp (ledger profile). |
142
144
  | `diff` | workflow | **`--artifact`** `--base` `--log` `--fid` `--step` `--attempt` `--reset-log` | Write the run's diff ({base}...HEAD, docs/plans/** excluded) as one artifact — whole, or a per-file budget past the guard — and print its numbers. |
143
- | `brief` | workflow | **`--plan`** `--group` `--next` **`--dir`** `--tests-only` `--file` `--note-file` | Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes; --tests-only writes the tests step's brief as build-brief-tests-{group}-{n}.md, with the Derived Test Matrix rows for the group's tests in place of the inventory and architecture entries. |
145
+ | `brief` | workflow | **`--plan`** `--group` `--next` **`--dir`** `--tests-only` `--file` `--note-file` | Write one group's brief (why and what, where it fits, its open task blocks, the earlier tasks they depend on, the Reuse Inventory rows and Architecture entries for their files, deviations) as build-brief-{group}-{n}.md, and print only its path and sizes; --tests-only writes the tests step's brief as build-brief-tests-{group}-{n}.md, with the Derived Test Matrix rows for the group's tests in place of the inventory and architecture entries, and the tests the group takes over from earlier tasks under their own section. |
144
146
  | `list-blocks` | by hand | — | Enumerate the consumer's context-fetch blocks and narrate coverage per context. |
145
147
  | `provision` | by hand | — | Run each context-fetch:provision recipe below bkit:end on its own and list the failed ones in .bkit/.unavailable. |
146
148
  | `run-block` | workflow | **`--idx`** **`--script`** **`--fid`** **`--month`** `--attempt` `--file` `--ci-selection-file` | Run one customised block; write its output fenced (clamped first), its skip line, or nothing. |
@@ -158,8 +160,9 @@ Attempt counters derived from status.jsonl, and the ask points' limits.
158
160
  | `run` | workflow | **`--file`** **`--workflow`** | Which run of the workflow this invocation is (1-based; a resume keeps its number). |
159
161
  | `route` | workflow | **`--name`** `--value` `--of` `--rows` `--file` `--workflow` `--group` `--all-runs` `--max` `--point` `--continue` `--exceeded` | Compare a counter to its max: exit 0 continue, exit 1 exceeded; with --point, also whether to ask. |
160
162
  | `grant` | workflow | **`--name`** `--value` `--of` `--rows` `--file` `--workflow` `--group` `--all-runs` **`--point`** | Give one loop one more full allowance after the owner chose to continue at its used-up limit: exit 0 granted, exit 1 not (below the limit, ask off or headless). |
163
+ | `correction` | workflow | **`--file`** **`--workflow`** **`--scope`** **`--operation`** `--request-hash` `--limit` | Spend one corrected retry of a rejected sub-step: exit 0 allowed (or a replay of a counted operation), exit 1 the scope's budget is used up. The budget is two per scope in the active run unless a stricter --limit names one. |
161
164
  | `max` | workflow | `--point` `--file` `--workflow` `--group` | The ask points' limits and ask settings: one by --point, or all. |
162
- | `progress` | workflow | **`--file`** **`--workflow`** **`--check`** **`--fix`** `--group` | Progress report for a fix loop in the active run: counts per round, code change, strategy, trend. |
165
+ | `progress` | workflow | **`--file`** **`--workflow`** **`--check`** **`--fix`** `--group` `--since-clean` | Progress report for a fix loop in the active run: counts per round, code change, strategy, trend. |
163
166
  | `rows` | workflow | **`--file`** **`--workflow`** **`--type`** **`--position`** | Count rows of one audit type in the active run (since its workflow-started row). |
164
167
 
165
168
  ### `decisions`
@@ -169,8 +172,9 @@ Build decision files: write questions, apply recommendations, list assumed items
169
172
  <!-- prettier-ignore -->
170
173
  | Verb | Use | Flags | What it does |
171
174
  | --- | --- | --- | --- |
172
- | `compose` | workflow | **`--out`** `--header` `--items` `--loop` `--file` `--group` `--attempt` `--max` | Write a decision file in the one question layout, with loop progress when asked. |
175
+ | `compose` | workflow | **`--out`** `--header` `--items` `--loop` `--file` `--group` `--attempt` `--max` `--base-check` | Write a decision file in the one question layout, with loop progress when asked. |
173
176
  | `apply` | workflow | **`--file`** **`--by`** `--q` `--confirm` `--reject` `--reason` `--root` | Settle a decision file's items: --by=headless takes each recommendation; --by=owner confirms or rejects one assumed item. |
177
+ | `skip` | workflow | **`--file`** | Whether a settled verify or holistic pause may route continue: exit 0 and route=continue when all five conditions hold, else exit 1 naming the first fact that fails. |
174
178
  | `pending` | workflow | **`--fid`** **`--month`** `--root` `--defer` | List the feature's assumed Accepts nobody confirmed; --defer writes one needs-decision deferral per item. |
175
179
 
176
180
  ### `disk`
@@ -208,7 +212,7 @@ Tracker payloads (issue text, label transitions, comments); --post / --write sen
208
212
  | `related` | workflow | **`--hits-file`** **`--out`** `--top` `--fid` `--issue` | Fetch each hit of the orchestrator's related-issue search and write the related-issues file. |
209
213
  | `blocked-by` | by hand | `--fid` `--issue` | The issues blocking the run's issue, with their states and the ones still open. |
210
214
  | `labels` | workflow | `--label` `--phase` `--failed` `--board` `--issue` `--owner-repo` `--write` `--fid` | Label arithmetic for a transition, the tracker state, and the board payload. |
211
- | `comment` | workflow | `--kind` `--audit-slug` `--step-number` `--step-title` `--workflow` `--workflow-heading` `--verdict` `--failures` `--scope` `--group` `--group-count` `--attempt` `--strategy` `--field` `--owner-repo` `--tree` `--pr-number` `--pr-url` `--run-id` `--artifact` `--ref` `--line` `--body-file` `--section` `--sub-step` `--error` `--error-file` `--stderr-file` `--post` `--fid` `--issue` `--file` | The exact body of a ###### bkit:generated step, failure, handover, or audit comment. |
215
+ | `comment` | workflow | `--kind` `--purpose` `--audit-slug` `--result-file` `--step-number` `--step-title` `--workflow` `--workflow-heading` `--verdict` `--failures` `--scope` `--group` `--group-count` `--attempt` `--strategy` `--field` `--owner-repo` `--tree` `--pr-number` `--pr-url` `--run-id` `--artifact` `--ref` `--line` `--body-file` `--section` `--sub-step` `--error` `--error-file` `--stderr-file` `--post` `--session-dir` `--fid` `--issue` `--file` | The exact body of a ###### bkit:generated step, failure, handover, or audit comment; workflow steps only, never for ad-hoc comments. |
212
216
 
213
217
  ### `ledgers`
214
218
 
@@ -220,7 +224,8 @@ Stage and commit bookkeeping by allow-list; union ledgers; check a range is book
220
224
  | `commit` | workflow | `--root` **`--month`** **`--fid`** `--scope` **`--mode`** `--stage-tracked-updates` `--path` `--squash-of` `--only-if-dirty-tracked` `--message` | Stage (and commit) the bookkeeping allow-list for one feature. |
221
225
  | `union` | workflow | **`--src`** **`--dst`** | Append a worktree's new ledger rows into another checkout (never .bkit/issues.jsonl). |
222
226
  | `only-bookkeeping` | by hand | `--root` **`--month`** **`--fid`** **`--from`** **`--to`** | Exit 0 when every path changed in from..to is on the --scope=pr allow-list. |
223
- | `append` | by hand | `--root` **`--ledger`** **`--rows`** | Append validated rows to one ledger, minting each row's ts at append time. |
227
+ | `append` | by hand | `--root` **`--ledger`** **`--rows`** `--invocation` `--operation` `--issue-operation` `--correction-of` | Append validated rows to one ledger, minting each row's ts at append time. |
228
+ | `query` | by hand | `--root` **`--ledger`** `--key` `--status` `--limit` `--cursor` | Read one ledger's canonical winners (filtered after the fold), paged, with line diagnostics and coverage. Writes nothing. |
224
229
  | `triage` | workflow | `--root` **`--fid`** **`--plan`** | Bucket each deferral row the FID declared by the four Deferral Reason tests, and write the unjustified ones. |
225
230
  | `check` | by hand | `--root` **`--plan`** | Check that every decision / deferral key on a plan's `**Ledger rows:**` line is on disk. |
226
231
  | `compact` | by hand | `--root` `--ledger` `--dry-run` | Rewrite keyed ledgers to their fold winners, stamping each winner's firstTs + updates. |
@@ -232,7 +237,7 @@ Acquire and release the per-feature workflow lock.
232
237
  <!-- prettier-ignore -->
233
238
  | Verb | Use | Flags | What it does |
234
239
  | --- | --- | --- | --- |
235
- | `acquire` | workflow | **`--kind`** **`--workflow`** **`--fid`** `--month` | Take the workflow lock, reclaiming a dead holder's. |
240
+ | `acquire` | workflow | **`--kind`** **`--workflow`** **`--fid`** `--month` | Take the workflow lock, reclaiming a dead holder's; a live holder exits 8 and prints heldBy. |
236
241
  | `release` | workflow | **`--kind`** **`--workflow`** **`--fid`** `--month` `--token` | Remove a lock this caller owns (and the feature's shared-checkout record); another owner's lock is left in place. |
237
242
 
238
243
  ### `plans`
@@ -253,10 +258,10 @@ Open and probe pull requests, and audit the close transport.
253
258
  | Verb | Use | Flags | What it does |
254
259
  | --- | --- | --- | --- |
255
260
  | `open` | workflow | **`--fid`** **`--title`** `--issue` `--base` `--head` `--plan` `--note` `--existing` `--file` `--workflow` | Open a PR whose body carries the bkit:issue / bkit:fid marker (exit 80: use MCP). |
256
- | `probe` | by hand | `--head` `--base` `--state` `--number` | The open (or open-then-merged) PR for a branch, or one PR by number. |
257
- | `merge` | workflow | **`--number`** `--subject` `--match-head` `--delete-branch` `--label` `--expect-merged` | Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back. |
261
+ | `probe` | by hand | `--head` `--base` `--state` `--number` `--ship-entry` `--owner-repo` `--facts-file` | The open (or open-then-merged) PR for a branch, or one PR by number. |
262
+ | `merge` | workflow | `--ship-retry` `--facts-file` `--owner-repo` **`--number`** `--subject` `--match-head` `--delete-branch` `--label` `--expect-merged` | Squash-merge a PR with an empty body (skipped when already MERGED) and read its state back. |
258
263
  | `update-branch` | workflow | **`--number`** `--only-if-required` | Refresh a PR's head from its base server-side (exit 80: use update_pull_request_branch). |
259
- | `checks` | by hand | **`--number`** | A PR's check rollup, classified: green when present and none failed or pending (exit 80: use MCP). |
264
+ | `checks` | by hand | **`--number`** | A PR's check rollup, classified: green when present and none failed, cancelled or pending (exit 80: use MCP). |
260
265
  | `verbose-ci` | workflow | **`--number`** **`--state`** | Add ` bkit [verbose ci]` to a PR title, or strip it (with an optional `bkit ` prefix); a no-op when already so. |
261
266
  | `scan-body` | by hand | **`--sha`** `--remote-ref` | Check a landed commit's body (not its subject) for a CI-suppressing token. |
262
267
  | `cross-check` | workflow | **`--file`** **`--transport`** | An mcp close with gh recorded unavailable must have a transport-fallback row. |
@@ -292,9 +297,10 @@ CI runs: wait for one, prove one was dispatched, re-validate and gate a merge on
292
297
  | --- | --- | --- | --- |
293
298
  | `locate` | workflow | **`--prompt-file`** `--issue-text-file` **`--branch`** **`--repo`** `--file` **`--selection-out`** `--evidence-file` | Select and validate the red CI run for the adopted debug branch before local discovery: exit 0 selects red CI, 1 selects local discovery, 2 rejects arguments, 8 rejects ambiguous references, 80 requests read fallback, and 82 requires owner action for unavailable or mismatched evidence. |
294
299
  | `wait` | by hand | `--pr` `--head` `--branch` `--until` `--budget-s` `--interval-s` `--once` `--dispatch-if-absent` | Bounded poll for a CI check on a PR (--pr) or a CI run at a head (--head --branch), present or completed. |
295
- | `dispatch` | workflow | `--pr` `--sha` **`--fid`** `--label` `--file` `--workflow` `--step` `--artifact` `--field` `--budget-s` `--interval-s` `--poll-result` `--attempts` `--all-errored` `--retriggered` | CI-Dispatch Gate after the last push: poll, one clean re-trigger, the ciDispatch verdict, and the body scan. A run in place on dev has no PR: it polls the push-event run at the pushed sha, and its re-trigger commits and pushes only the run's own work. |
296
- | `gate` | workflow | `--ci-selection-file` `--head` `--pr` `--squash-of` `--snapshot` `--record` `--validated` `--month` `--fid` `--repo` `--branch` `--fetch` `--event` `--file` `--capstone-only` | Ship merge gate: the capstone job present and green at the head (exit 0), or why not. |
297
- | `revalidate` | workflow | **`--pr`** **`--entry-head`** **`--code-head`** **`--branch`** **`--month`** **`--fid`** **`--file`** `--reason` `--repo` | Ship: pick the head CI must pass at, probe for a run there, dispatch only when none, wait for it to complete. |
300
+ | `handoff` | workflow | `--invocation` **`--repo`** `--pr` **`--head`** **`--branch`** `--budget-s` `--interval-s` **`--result`** **`--polls`** | Persist one batch of CI poll observations into the invocation's run and derive the phase, cumulative attempts and errors, next action and verdict from the persisted rows (poll-again \| retrigger \| reconcile-retrigger \| verdict). Rows for another repo, PR or head never count. |
301
+ | `dispatch` | workflow | `--invocation` `--pr` `--sha` **`--fid`** `--label` `--file` `--workflow` `--step` `--artifact` `--field` `--budget-s` `--interval-s` | CI-Dispatch Gate after the last push: poll, one clean re-trigger, the ciDispatch verdict, and the body scan. A run in place on dev has no PR: it polls the push-event run at the pushed sha, and its re-trigger commits and pushes only the run's own work. It needs a workflow run's --invocation and resumes from the rows that run persisted (its own polls and `runs handoff` turns): attempts, errors and the re-trigger checkpoint are never supplied. |
302
+ | `gate` | workflow | `--ci-selection-file` `--fresh-base` `--facts-file` `--head` `--pr` `--squash-of` `--snapshot` `--record` `--validated` `--month` `--fid` `--repo` `--branch` `--fetch` `--event` `--file` `--capstone-only` `--wait` `--budget-s` `--interval-s` | Ship merge gate: the capstone job present and green at the head (exit 0), or why not. |
303
+ | `revalidate` | workflow | `--require-reconciled` **`--pr`** **`--entry-head`** **`--code-head`** **`--branch`** **`--month`** **`--fid`** **`--file`** `--reason` `--repo` | Ship: pick the head CI must pass at, probe for a run there, dispatch only when none, wait for it to complete. |
298
304
  | `mirror` | workflow | **`--head`** `--branch` `--repo` `--ci-workflow` `--capstone` `--absent-minutes` `--max-minutes` `--interval-s` | Release PR: wait for the branch's push run at the head and copy its capstone verdict. |
299
305
  | `context` | workflow | **`--phase`** **`--arg`** `--marker` | /bkit-auto Step 1: the phase and mode, the repo, and the issue / FID / PR / run the dispatch carries. |
300
306
  | `declared` | by hand | — | Whether the repo declares a CI workflow: .github/workflows/<bkit.testing.ciWorkflow> exists (exit 0) or not (exit 1). |
@@ -336,8 +342,9 @@ Read and annotate a workflow's status.jsonl.
336
342
  | Verb | Use | Flags | What it does |
337
343
  | --- | --- | --- | --- |
338
344
  | `path` | by hand | **`--workflow`** **`--fid`** **`--month`** | Where this workflow's status.jsonl lives. |
339
- | `route` | workflow | `--file` **`--workflow`** `--step` `--group` `--require` `--expect` `--prompt-file` `--fid` `--month` | Routing state: last verdict / failures / strategy of a step, debug and push mode; with --prompt-file, debug's start decisions. |
340
- | `resume` | by hand | **`--file`** **`--workflow`** | The step a stopped run continues at: after its last DONE step, setup steps and retired rows aside. |
345
+ | `route` | workflow | `--file` **`--workflow`** `--step` `--group` `--require` `--expect` `--prompt-file` `--fid` `--month` | Routing state: last verdict / failures / strategy of a step, debug and push mode; with --step, nextStrategy and repeatTests (the next fix round's label, from the tests failing again); with --prompt-file, debug's start decisions. |
346
+ | `invocation` | workflow | `--workflow` `--step` `--file` `--group` `--attempt` `--agent` `--host` `--configured-model` `--observed-model` `--standalone` `--name` | Issue an engine-bound invocation: a run's step (and agent), or a runless audit or utility call. |
347
+ | `resume` | by hand | **`--file`** **`--workflow`** | The step a stopped run continues at: after its last DONE step, setup steps and retired rows aside; gateRerun and rerunFrom say whether an open red-gate pause re-runs its gate first, and which. |
341
348
  | `meta` | workflow | **`--file`** **`--workflow`** `--debug-mode` `--push-mode` `--debug-attempt` `--opened-pr` `--ci-selection-file` | Append a workflow-meta row (run-level routing state). |
342
349
  | `row` | workflow | **`--file`** **`--workflow`** **`--type`** `--field` | Append a typed audit row the fold does not model (ship's gate refusals, CI probes, merge CI); an owner-pause row also logs a human-confirm friction row. |
343
350
 
@@ -349,10 +356,10 @@ Write a step's status row, finish a step in one call, read a verdict header, che
349
356
  | Verb | Use | Flags | What it does |
350
357
  | --- | --- | --- | --- |
351
358
  | `done` | workflow | **`--file`** **`--workflow`** **`--step`** `--status` `--verdict` `--agent` `--allowed` `--failures` `--attempt` `--group` `--strategy` `--artifact` `--field` `--parent-sha` `--commit` `--message` | Append a step-done row and commit it (parentSha captured first). |
352
- | `finish` | workflow | **`--file`** **`--workflow`** **`--step`** `--artifact` `--optional-artifact` `--agent` `--verdict` `--allowed` `--failures` `--attempt` `--attempt-of` `--count-field` `--group` `--strategy` `--scope` `--field` `--clamp-log` `--docs-only` `--plan` `--parent-sha` `--commit` `--message` `--done-fallback` `--verbose-ci-local` `--number` `--title` `--post` `--group-count` `--link-ref` `--tree` `--owner-repo` `--comment-body` `--comment-field` | End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment. |
353
- | `verdict` | by hand | **`--file`** `--agent` `--allowed` `--field` | Read an artifact's header down to <!-- verdict:end -->. |
359
+ | `finish` | workflow | **`--file`** **`--workflow`** **`--step`** `--artifact` `--optional-artifact` `--agent` `--verdict` `--allowed` `--failures` `--attempt` `--attempt-of` `--count-field` `--group` `--strategy` `--scope` `--field` `--clamp-log` `--docs-only` `--plan` `--parent-sha` `--commit` `--message` `--done-fallback` `--verbose-ci-local` `--number` `--title` `--post` `--group-count` `--link-ref` `--tree` `--owner-repo` `--comment-body` `--comment-field` | End a step: read the verdict header(s), derive the attempt, check the gate, write the row, commit, print the tracker comment. Exit 11 on a build tests step that changed an earlier task's recorded test no open task of the group names, and on a code step that changed a planned test; for each BLOCKED test a ticked task owns, a code step first adds a takeover task to the plan and its build-takeover row, and prints them under contradicts. |
360
+ | `verdict` | by hand | **`--file`** `--agent` `--allowed` `--field` `--result-file` | Read an artifact's header down to <!-- verdict:end -->. |
354
361
  | `gate` | workflow | `--file` `--ref` **`--workflow`** **`--step`** `--group` `--progress-number` `--attempt` `--attempt-of` `--artifact` `--verdict-required` `--agent` `--allowed` `--placeholder` `--fid` `--issue` `--month` `--token` | Mechanical gate checks for one step: placeholders, FID, lock, artifacts, verdict, status row (with its attempt / strategy / scope where the step writes them). |
355
- | `stub` | workflow | **`--from`** **`--to`** `--strip-header` | Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top. |
362
+ | `stub` | workflow | `--from` **`--to`** `--agent` `--result-file` `--invocation` `--strip-header` | Seed a versioned artifact: copy the prior version, then put a PENDING verdict header on top. |
356
363
 
357
364
  ### `tasks`
358
365
 
@@ -361,8 +368,9 @@ Tick a plan's task boxes, from the tasks a verify judged satisfied.
361
368
  <!-- prettier-ignore -->
362
369
  | Verb | Use | Flags | What it does |
363
370
  | --- | --- | --- | --- |
364
- | `tick` | workflow | **`--plan`** **`--group`** `--tasks` `--green` | Tick the named tasks of one task group, less those a `tests green` report gaps; exit 0 ticked (including none), 1 a plan with no task blocks, 2 a bad flag value or plan. |
371
+ | `tick` | workflow | **`--plan`** `--group` `--tasks` `--decision` `--green` | Tick the named tasks of one task group, less those a `tests green` report gaps; exit 0 ticked (including none), 1 a plan with no task blocks, 2 a bad flag value or plan, a `--green` report with no Gaps section or fewer gap lines than its `Gaps:` header, or a `--decision` file that is not a verify or holistic pause of this group with a green gate. |
365
372
  | `open` | by hand | **`--plan`** **`--group`** **`--log`** | Print the group's tasks holding neither a `DONE` nor a `BLOCKED` line in the plan-execute log, and whether any is open; exit 0 (including none), 1 a plan with no task blocks, 2 a missing file or group. |
373
+ | `takeover` | workflow | **`--plan`** **`--file`** `--pending` | Print the takeover group whose tests half has not run: the plan's takeover tasks (added by `steps finish` on a code step that contradicts a ticked task's planned test, each named by a build-takeover row) in the latest group holding a planned test with no `tests red` entry yet, or null. Writes nothing. Exit 0 (including nothing pending), 1 a plan with no task blocks, 2 a bad flag value or plan. |
366
374
  | `currency` | by hand | **`--plan`** `--base` `--against` | Print each task whose CREATE / READ / UPDATE / DELETE paths or symbols moved between --base and --against, with its matched paths, needles and diff hunks (run logs under docs/plans/*/logs/ are left out); exit 0 (including no match), 1 a plan with no task blocks, 2 a bad plan. |
367
375
 
368
376
  ### `tests`
@@ -372,11 +380,13 @@ Run the deepest declared local gate, or one test file to record a red and audit
372
380
  <!-- prettier-ignore -->
373
381
  | Verb | Use | Flags | What it does |
374
382
  | --- | --- | --- | --- |
375
- | `changed` | by hand | `--lock-wait-s` `--base` `--fallback` | Check only the files changed since --base: run `bkit:gate:changed` with them as arguments, else the --fallback gate; exit 0 PASS or nothing changed, 1 FAIL, 4 could not run, 81 tests lock held. |
376
- | `run` | by hand | **`--gate`** **`--log`** `--tail` `--lock-wait-s` `--artifact` `--fid` `--step` `--attempt` `--file` `--workflow` `--ci-run` `--ci-url` | Run the first declared --gate, and with --file append a test-run status row for the run; exit 0 PASS, 1 FAIL, 4 could not run, 81 tests lock held. |
377
- | `red` | workflow | **`--file`** **`--workflow`** **`--group`** **`--plan`** **`--log`** `--writer-log` | Run every TEST FIRST test of one group's open tasks before any task code exists, and write one build-tests-red row holding a state and blob per planned test; a test an earlier row of the group proved red, its file unchanged since, is not run again. Exit 0 every test red, 1 a gap (a test passing, absent from its report, failing lint, or its file missing), 3 bkit:test:file undeclared (blobs recorded, nothing ran), 4 a script could not run. |
378
- | `green` | workflow | **`--file`** **`--workflow`** `--group` **`--plan`** **`--log`** | Audit a plan's test-first evidence (each TEST FIRST test red at its group's tests step, by the build-tests-red row, or accepted there as passing before any task code; the named test passing now); exit 0 no gaps, 1 gaps or a plan with no task markers. |
379
- | `plan-check` | by hand | **`--plan`** `--existence` **`--log`** | Check a plan's group and task blocks: the block format, DONE WHEN and TEST FIRST on every task, DEPENDS ON order, the caps from package.json `bkit.workflows.tasks` (defaults: 5 tasks and 25 TEST FIRST tests per group; 10 tests across 3 test files per task), a Reuse Inventory NEW row per CREATE file, a Supersession Inventory row per DELETE, a `Task` on every Derived Test Matrix row and a row per test-bearing task, and that each READ / UPDATE / DELETE file and symbol exists; exit 0 no problems, 1 refused. |
383
+ | `base` | workflow | `--log` `--file` `--workflow` `--out` | Check whether the failing tests of a red gate also fail on the commit the branch started from; exit 0 for every verdict. |
384
+ | `changed` | by hand | `--lock-wait-s` `--base` `--fallback` | Check only the files changed since --base: run `bkit:gate:changed` with them as arguments, else the --fallback gate; exit 0 PASS or nothing changed, 1 FAIL, 4 could not run, 81 tests lock held (read from the lock status file, never from the exit code alone). |
385
+ | `jump` | by hand | **`--run`** `--checkout` | Move the waiting run named <run> to the front of the tests line; the holder keeps the lock. Every use needs the human's approval, so ask them to approve it; exit 0 moved, 1 no single run matched, 3 the lock script failed. |
386
+ | `run` | by hand | **`--gate`** **`--log`** `--tail` `--lock-wait-s` `--artifact` `--fid` `--step` `--attempt` `--file` `--workflow` `--changed-since` `--since-pass-of` `--ci-run` `--ci-url` | Run the first declared --gate, or with --changed-since only the files changed since that commit, and with --file append a test-run status row for the run; exit 0 PASS (also when nothing changed), 1 FAIL, 4 could not run, 81 tests lock held (read from the lock status file, never from the exit code alone). |
387
+ | `red` | workflow | **`--file`** **`--workflow`** **`--group`** **`--plan`** **`--log`** `--writer-log` | Run every TEST FIRST test of one group's open tasks before any task code exists, and write one build-tests-red row holding a state and blob per planned test; a test an earlier row of the group proved red, its file unchanged since, is not run again. A test a later task takes over from an earlier one (same file and name) carries `from`, and one that passes after the rewrite is recorded taken-over. Exit 0 every test red, 1 a gap (a test passing, absent from its report, failing lint, or its file missing), 3 bkit:test:file undeclared (blobs recorded, nothing ran), 4 a script could not run. |
388
+ | `green` | workflow | **`--file`** **`--workflow`** `--group` **`--plan`** **`--log`** | Audit a plan's test-first evidence (each TEST FIRST test red at its group's tests step, by the build-tests-red row, or accepted there as passing before any task code; the named test passing now); a taken-over test is listed under takenOver with its diff since the earlier task's red, never as a gap or unproven; exit 0 no gaps, 1 gaps or a plan with no task markers. |
389
+ | `plan-check` | by hand | **`--plan`** `--existence` **`--log`** `--ledger-rows` | Check a plan's group and task blocks: the block format, DONE WHEN and TEST FIRST on every task, DEPENDS ON order, the caps from package.json `bkit.workflows.tasks` (defaults: 5 tasks and 25 TEST FIRST tests per group; 10 tests across 3 test files per task), a Reuse Inventory NEW row per CREATE file, a Supersession Inventory row per DELETE, a `Task` on every Derived Test Matrix row and a row per test-bearing task, and that each READ / UPDATE / DELETE file and symbol exists; lists each later task's TEST FIRST test an earlier task also names under takeovers, reported only; exit 0 no problems, 1 refused. |
380
390
 
381
391
  ### `workflows`
382
392
 
@@ -385,11 +395,11 @@ Start, fail, hand over, summarize and close a phase workflow run; promote and li
385
395
  <!-- prettier-ignore -->
386
396
  | Verb | Use | Flags | What it does |
387
397
  | --- | --- | --- | --- |
388
- | `start` | workflow | **`--workflow`** **`--fid`** `--month` `--file` `--lock-held` `--token` `--branch` | Take the feature lock and open a run (workflow-started unless resuming). |
389
- | `fail` | workflow | **`--workflow`** `--fid` `--month` `--file` `--token` `--max-exceeded` `--label` `--pr` `--step-number` `--step-title` `--sub-step` `--error-file` `--error` `--stderr-file` `--post` `--issue` `--session-dir` | Failure Path: workflow-failed row, abort rebase, release lock, clear sentinels (with --token); the bkit:failed labels and the failure comment. |
398
+ | `start` | workflow | **`--workflow`** **`--fid`** `--month` `--file` `--session-dir` `--lock-held` `--token` `--branch` | Take the feature lock and open a run (workflow-started unless resuming). |
399
+ | `fail` | workflow | **`--workflow`** `--fid` `--month` `--file` `--token` `--max-exceeded` `--label` `--pr` `--step-number` `--step-title` `--sub-step` `--error-file` `--error` `--stderr-file` `--next-step` `--post` `--issue` `--session-dir` | Failure Path: workflow-failed row, abort rebase, release lock, clear sentinels (with --token); the bkit:failed labels and the failure comment. |
390
400
  | `handover` | workflow | **`--workflow`** **`--fid`** `--month` `--push` `--flush` `--open-pr` `--ref` `--list-stray` `--worktree` `--owner-repo` `--post` | Keep a failed run's record: commit and push it on the feature branch, or land its logs and ledgers on dev (--push from dev / main, ship's --flush); print the handover comment. |
391
401
  | `close` | workflow | **`--workflow`** **`--fid`** `--month` `--file` `--pr-number` `--squash-sha` `--ref` `--owner-repo` `--outbox` `--record-step` `--message` `--label` `--verbose-ci-local` `--number` `--title` `--post` `--tree` `--ending` `--publish` `--flush` `--token` `--branch` `--session-dir` `--final-return` `--summary-file` `--summary` `--summary-missing` `--warning` `--line` `--suggest` | Grade compliance, workflow-done row, counter + outcome telemetry, report, artifact links; --flush lands ship's close on dev. |
392
- | `input` | workflow | **`--workflow`** **`--fid`** `--month` `--file` **`--run`** **`--prompt-file`** `--description-file` `--comments-file` `--plan` `--design` `--audit` | Write logs/{FID}/{workflow}-input-{run}.md: the session prompt, the issue description and each human comment, then the plan, design and audit reports, each section dated. |
402
+ | `input` | workflow | **`--workflow`** **`--fid`** `--month` `--file` **`--run`** **`--prompt-file`** `--description-file` `--comments-file` `--plan` `--design` `--audit` | Write logs/{FID}/{workflow}-input-{run}.md: the session prompt, the issue description and each human comment, then the plan, design and audit reports, each section dated. An existing {workflow}-grill-{run}.md in the same folder is appended at the end. |
393
403
  | `promote` | workflow | **`--workflow`** **`--fid`** `--month` `--file` `--resolve` | Design / plan close: the highest versioned draft becomes the canonical doc (anchor stamped, a changed canonical archived). |
394
404
  | `links` | workflow | **`--workflow`** **`--fid`** `--month` `--ref` `--owner-repo` `--outbox` `--number` `--title` `--post` | The feature's docs and this workflow's logs on a ref as markdown links; optionally the close comment. |
395
405
  | `summary` | workflow | **`--workflow`** **`--file`** `--plan` `--pr` `--publish` | The Summary step: write {workflow}-summary.md next to --file with the run's verdict, reasons and next command. |
@@ -402,6 +412,6 @@ Set up and remove the per-feature worktrees under .worktrees/.
402
412
  | Verb | Use | Flags | What it does |
403
413
  | --- | --- | --- | --- |
404
414
  | `setup` | workflow | **`--workflow`** **`--fid`** **`--month`** `--worktrees` `--detect` `--branch` `--issue` | Create, resume or adopt the feature's worktree (Step 2 — Worktree Setup). |
405
- | `remove` | workflow | **`--fid`** `--branch` | Remove .worktrees/{fid} when a workflow created it, prune stale entries, and delete the feature branch. |
415
+ | `remove` | workflow | **`--fid`** `--branch` | Remove a workflow-owned worktree when its work is safely on dev; conditionally delete its local and remote branch at their proved landed tips. |
406
416
 
407
417
  <!-- cli:end -->