@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
@@ -13,7 +13,7 @@ description: "Ship Feature — Autonomous merge and archive"
13
13
  - **Order:** Execute steps sequentially unless stated otherwise.
14
14
  - **No improv:** Skip no step, and add no step of your own; how deeply you investigate within a step is your call.
15
15
  - **Narrate:** Emit user-visible lines at key points (step start, subagent return, pivot, blocker). After each completed numbered step, show its printed `progressLine` word for word as plain text outside code blocks. Show each completed row's line once; delayed bookkeeping and repeated validation gates add no second line. `/bkit-auto` shows its delegated workflow's lines. Headless runs show the same lines without waiting for acknowledgement. Silence between actions = compliance regression; Auto-apply does not mean silent.
16
- - **Failures:** Apply explicit recovery routes, including **Sandbox recovery** and **Read-only helper recovery**, before **Failure Path**.
16
+ - **Failures:** Apply explicit recovery routes, including **Sandbox recovery**, **Read-only helper recovery** and **Bounded correction**, before **Failure Path**.
17
17
  - **If** a step, tool or command still fails, or a gate cannot pass → **Failure Path**.
18
18
  - **Sandbox recovery:** **If** the host reports a sandbox or permission denial:
19
19
  - Retry the same operation once through the host's approval mechanism only when permitted.
@@ -34,37 +34,43 @@ description: "Ship Feature — Autonomous merge and archive"
34
34
  - **Recovery scope:** Repository code, bkit commands, test and gate failures keep their explicit recovery or failure routes.
35
35
  - **Placeholders:** Assert `{PLACEHOLDERS}` such as `{FID}`, `{YYYYMM}`, etc non-empty if required before making tool calls<!-- bkit:tracker true start --> (`{ISSUE_ID}` may be empty)<!-- bkit:tracker true end -->. **Else** → **Failure Path**.
36
36
  - **Commands:** Blocks run `"{BKIT}" <noun> <verb> --flag=value`; `{BKIT}` = `bkit` printed by Step 1 `repo info`, until then `"$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")/node_modules/.bin/bkit"`. Stdout is `key: value` lines, nested keys indented under their parent (`a.b` = `b` under `a:`), lists of rows as tables: hold named keys under bare `UPPER_SNAKE` names, a `"quoted"` value without its quotes, and write a held name as `{VAR}` where it goes into a command or a `Context:` / `Read:` / `Create:` line. Exit non-zero with no `Route:` or recovery under **Failures** → **Failure Path**; exit 80 → mapped MCP tool (**gh MCP fallback**); exit 81 → end turn, re-run block. A flag still holding a literal `{PLACEHOLDER}` exits 2.
37
+ - **Bounded correction:** **If** a bkit command fails with a structured error that declares effects = none and correctable = true (a guaranteed no-write rejection, checked by the engine fill before any write) → correct only what the error names, and retry with `--correction-of=<the rejected --operation>` and a fresh `--operation`. Allow two corrected retries per printed `scope`; a replay of a counted operation spends nothing. After a verified retry (`correction.verified`) resume the same sub-step. **If** the error reports uncertain effects → reconcile first by re-running the original `--operation`, and make no corrected candidate until that settles. A stricter command-specific route or limit wins over this allowance. Authorization failures, gate and check failures, exhausted budgets and unverified retries keep **Failure Path**.
38
+ - **Deterministic bookkeeping:** Use the engine's validated execution context and artifact data for metadata, counts, paths and serialization. Agents supply substantive findings and judgments. Do not invent missing attribution or replace conflicting evidence with a guess.
39
+ - **Recoverable execution errors:** Apply the command's explicit recovery route first. If validation guarantees that no changes were made, correct the input from verified evidence and retry at most twice. Keep this correction budget across helper rewrites, tool switches and resume. Verify the required outputs and continue from the interrupted sub-step after success.
40
+ - **Uncertain effects:** Inspect and reconcile the operation's durable state before retrying a write. Retry only when the engine can establish that it will not duplicate or corrupt an effect. Preserve work and report a blocker when the outcome cannot be established.
41
+ - **Failure boundary:** Enter Failure Path when the applicable recovery budget is exhausted, a required check still fails, required information or authorization is unavailable, or recovery cannot proceed safely. Recovery does not permit weakening tests, bypassing gates or granting approval. A recovered command error alone does not fail the workflow.
42
+ - **Recovery precedence:** A specific recovery route supplies its own limit and eligibility before the generic two-correction route. Optional model telemetry unavailability is diagnostic, while missing author or run authority or required substantive evidence blocks the affected action. A permission escalation follows its existing authorization policy, never the generic correction allowance.
37
43
 
38
44
  **Contract:** The terms between this agent and whoever runs it.
39
45
 
40
46
  - **Friction:** Watch own context and subagent returns for manual installs, agent rework, repeated tool failures, destructive backouts → append rows to `.bkit/friction.jsonl` with `bkit ledgers append` (`.bkit/jsonl.md` § Write Idiom) → continue or escalate; `status row --type=owner-pause` logs each owner pause itself, so do not log one; logging does not replace **Failure Path**.
41
47
  - **Finish:** `bkit steps finish` reads each `--agent`'s header from the `--artifact` in the same position, derives the attempt (`--attempt-of`; `<attempt>` in a path becomes it), checks artifacts and row, writes the row (ship: `--commit=none`, bookkeeping to `$BOOK_ROOT`), prints `comment`. Exit 5 **or** 6 → invoke `reask.agent` again with `"Your prior output '<reask.artifact>' has an invalid header. Re-emit only its header fields + '<!-- verdict:end -->' at top of that file. Do not redo work."` → wait for subagent and re-run the block → **If** still non-zero → **Failure Path**. Exit 8 → nothing written, nothing committed: fix what the hook's message names, then re-run this block — the step's attempt is unchanged. Hold `verdict` as the step's verdict, `fields` as its other header fields, `attempt` as its attempt.
42
- - **Resume:** After Step 2, unless Step 1 or 2 routed elsewhere, `"{BKIT}" status resume --workflow=ship --file="{STATUS}"` names where the active `IN_PROGRESS` run picks up — after its last `DONE` step; Steps 1-2 ALWAYS run again and rows of steps this workflow no longer has are ignored → continue at Step `number`; `after` = `ship-failure-remediate` → Step 12 sub-step 4 with `verdict` = PASS.
48
+ - **Resume:** After Step 2, unless Step 1 or 2 routed elsewhere, `"{BKIT}" status resume --workflow=ship --file="{STATUS}"` names where the active `IN_PROGRESS` run picks up — after its last `DONE` step; Steps 1-2 run again on every resume, and rows of steps this workflow no longer has are ignored → continue at Step `number`. For `number` from 3 through 10, return to Step 3 instead, which compares recorded feature coverage before reusing completed agents.
43
49
  - **Status:** `$BOOK_ROOT/.../status.jsonl` = append-only NDJSON event log, one event per line. `step-done` carries `parentSha` captured at step START, optional `verdict` (`PASS|CONCERNS|FAIL`, or a word the step's agent adds, e.g. execute's `HANDOVER`), `failures`, `attempt`, `strategy` (`STANDARD|PIVOT|FINAL`). **If** `failures` present → `PASS => failures=0`, `FAIL => failures>0`, `CONCERNS => failures>=0`.
44
- - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); Step 14 releases it via `bkit workflows close --flush --token=`, the **Failure Path** via `bkit workflows fail --token=`. **If** existing lock — its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle → **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) → reclaimed.
50
+ - **Locks:** Step 1 takes `$REPO_ROOT/docs/plans/{YYYYMM}/logs/{FID}/.lock` with `bkit locks acquire --kind=workflow` (hold `token`); Step 12 releases it via `bkit workflows close --flush --token=`, the **Failure Path** via `bkit workflows fail --token=`. **If** existing lock — its owning workflow's folded status.jsonl decides: `IN_PROGRESS` and last step <30min idle → `locks acquire` exits 8 and the run stops without the **Failure Path**; any other holder (`DONE`, `FAILED`, `IN_PROGRESS` idle >=30min, no run) → reclaimed.
45
51
  - **Status branch:** From Step 2 all steps write `$BOOK_ROOT/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl` (`{STATUS}`); `BOOK_ROOT` = `{WORKTREE_PATH}`. Stage path-scoped via `bkit ledgers commit`; NEVER stage all files (`-A`) or blanket `docs/`. One commit per flush block: Commit + Push Bookkeeping → `docs({FID}): ship bookkeeping bkit [skip ci]` → push `{SHIP_BRANCH}` (pre-merge: docs, logs, ledgers, skill removals); Close Workflow → `docs({FID}): ship DONE bkit [skip ci]`, **Failure Path** → `chore({FID}): ship FAILED bkit [skip ci]` → push `dev` from a throwaway `origin/dev` checkout; a refused close push → close PR.
46
- - **Worktrees:** **If** `runtimeWorktrees` = true (mint mode) → Step 2 `cd`s into `.worktrees/{FID}`. **Else** → adopt current branch in place, `WORKTREE_PATH=$REPO_ROOT`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` → **Failure Path**; Step 14 ends in `{REPO_ROOT}`.
47
- - **gh MCP fallback:** `gh` primary for PR / CI / merge surface. **If** a command exits 80, **or** `runtimeGithubCli` = false in the `runtime-resolved` row of `{STATUS}` → use mapped MCP tool (needs `actions` toolset in `.mcp.json`): `bkit prs open` / `bkit branches land` stage `open` → `create_pull_request` with the printed `title` / `base` / `head` and the content of the printed `bodyFile` as `body`, byte-for-byte; `bkit prs probe --number` → `pull_request_read` (`get`, minimal fields); `bkit prs probe --head` / `bkit workflows handover --push` → `list_pull_requests`; `bkit prs merge` / `bkit branches land` stage `merge` → `merge_pull_request` (printed skip-token-free `subject` as `commit_message`, empty body; `--match-head` SHA as `sha`); `bkit prs verbose-ci` → `update_pull_request`; `bkit prs update-branch --number` → `update_pull_request_branch`; `bkit prs checks --number` → `pull_request_read` (`get_status`); `bkit runs wait` / `bkit runs dispatch` / `bkit runs revalidate` / `bkit runs gate` → `actions_list`; `gh run view {id} --json jobs` → `actions_get`; `gh run view --log-failed` → `get_job_logs` (`failed_only=true`). Max 1 transition per run, recorded as a `transport-fallback` row via `bkit prs transport-row --file={STATUS} --kind=fallback --from=<gh command> --to=<MCP tool> --reason=<why> --asserted-by=<re-read>` — **Skip if** `{STATUS}` not set. Tracker reads and writes go through `bkit` verbs; the tracker MCP ONLY when a verb prints `tracker.done: false` or exits 80.
52
+ - **Worktrees:** **If** `runtimeWorktrees` = true (mint mode) → Step 2 `cd`s into `.worktrees/{FID}`. **Else** → adopt current branch in place, `WORKTREE_PATH=$REPO_ROOT`. cwd persists across subsequent Bash calls. **If** steps ever find `pwd` != `{WORKTREE_PATH}` → **Failure Path**; Step 12 ends in `{REPO_ROOT}`.
53
+ - **gh MCP fallback:** `gh` primary for PR / CI / merge surface. **If** a command exits 80, **or** `runtimeGithubCli` = false in the `runtime-resolved` row of `{STATUS}` → use mapped MCP tool (needs `actions` toolset in `.mcp.json`): `bkit prs open` / `bkit branches land` stage `open` → `create_pull_request` with the printed `title` / `base` / `head` and the content of the printed `bodyFile` as `body`, byte-for-byte; `bkit prs probe --number` → `pull_request_read` (`get`, minimal fields); `bkit prs probe --head` / `bkit workflows handover --push` → `list_pull_requests`; `bkit prs merge` / `bkit branches land` stage `merge` → `merge_pull_request` (printed skip-token-free `subject` as `commit_message`, empty body; `--match-head` SHA as `sha`); `bkit prs verbose-ci` → `update_pull_request`; `bkit prs update-branch --number` → `update_pull_request_branch`; `bkit prs checks --number` → `pull_request_read` (`get_check_runs`, the check-run conclusions for the PR head; or `actions_list` runs for the head SHA), never `get_status`; `bkit runs wait` / `bkit runs dispatch` / `bkit runs revalidate` / `bkit runs gate` → `actions_list`; `gh run view {id} --json jobs` → `actions_get`; `gh run view --log-failed` → `get_job_logs` (`failed_only=true`). Max 1 transition per run, recorded as a `transport-fallback` row via `bkit prs transport-row --file={STATUS} --kind=fallback --from=<gh command> --to=<MCP tool> --reason=<why> --asserted-by=<re-read>` — **Skip if** `{STATUS}` not set. Tracker reads and writes go through `bkit` verbs; the tracker MCP ONLY when a verb prints `tracker.done: false` or exits 80.
48
54
 
49
55
  <!-- bkit:tracker github start -->
50
56
 
51
57
  - **Tracker:** GitHub Issues — `bkit` verbs read and write it; MCP server `github` (`.mcp.json` `mcpServers.github`) ONLY when a verb exits 80 or prints `done` = false. Tools: `mcp__github__issue_read` (method `get` / `get_comments` / `get_labels`), `mcp__github__issue_write` (method `update`), `mcp__github__add_issue_comment`, `mcp__github__list_issues`, `mcp__github__projects_write` (method `add_project_item` / `update_project_item`); board status sync needs `projects` toolset in `.mcp.json` (`X-MCP-Toolsets`) and `package.json` `bkit.tracker.github.project`, absent either → silently skipped. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, NEVER gate; **If** failure → retry once after 5s → continue.
52
- - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`; `boardWrite.done` = false → `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_write({BOARD}.updateItem)`.
53
- - **Comments:** A step's `bkit` block posts the `comment` it prints with `--post` before its gate and prints `tracker`; every gate includes `Issue comment attempted (Step N section)`. **If** `tracker.done` = false → post the content of the printed `commentFile` byte-for-byte as a new comment via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })`; NEVER shorten, reword, or rebuild it. NEVER edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
58
+ - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (the opt-in the cloud gate job reads before it starts a run), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__github__issue_write({ method: "update", owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, labels: [{LABELS}] })`; `boardWrite.done` = false → `mcp__github__projects_write({BOARD}.addItem)` → `mcp__github__projects_write({BOARD}.updateItem)`.
59
+ - **Comments:** The engine may append routine reports to its own eligible progress comment; explicit session/run ownership keeps invocations separate. Attention and terminal reports use new comments. Comment preparation, delivery, MCP fallback and friction failures are nonfatal: attempt best-effort friction and continue substantive work. **If** `tracker.done` = false and `commentFile` is available → attempt one new comment from that file byte-for-byte via `mcp__github__add_issue_comment({ owner: "{OWNER}", repo: "{REPO}", issue_number: {ISSUE_ID}, body: "{BODY}" })`; NEVER edit prior tracker content or rebuild the fallback body. A missing file or exhausted fallback is an attempted report, not a workflow blocker. Every comment gate requires an attempt or an applicable skip. **If** `SESSION_DIR` is not held → re-run the workflow's Step 1 `repo info` call and hold `sessionDir` as `SESSION_DIR` before the call; keep `--session-dir` on the call, because `bkit issues comment` refuses a call with no workflow-run proof.
54
60
 
55
61
  <!-- bkit:tracker github end -->
56
62
  <!-- bkit:tracker linear start -->
57
63
 
58
64
  - **Tracker:** Linear — `bkit` verbs read and write it; MCP server `linear` (`.mcp.json` `mcpServers.linear`) ONLY when a verb exits 80 or prints `done` = false. Tools: `mcp__linear__get_issue`, `mcp__linear__save_issue`, `mcp__linear__save_issue_label`, `mcp__linear__save_comment`, `mcp__linear__list_comments`, `mcp__linear__list_issues`. Assert `{ISSUE_ID}` / `{STATE}` / `{LABELS}` non-empty before tool calls; `save_*` writes best-effort, NEVER gate; **If** failure → retry once after 5s → continue. `save_issue` ALWAYS includes `id` and is all-or-nothing (one state or label name the team lacks rejects the whole call) → labels and state in separate calls, labels first; create each printed `add` entry first via `save_issue_label({ name })` (`already exists` = done). `Could not find state` / `Could not find label` → log `Unapplied: <state|label> "<name>" not in team`, no retry, continue.
59
- - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
60
- - **Comments:** A step's `bkit` block posts the `comment` it prints with `--post` before its gate and prints `tracker`; every gate includes `Issue comment attempted (Step N section)`. **If** `tracker.done` = false → post the content of the printed `commentFile` byte-for-byte as a new comment via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`); NEVER shorten, reword, or rebuild it. NEVER edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content.
65
+ - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (the opt-in the cloud gate job reads before it starts a run), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__linear__save_issue_label({ name })` per printed `add` entry → `mcp__linear__save_issue({ id: "{ISSUE_ID}", labels: [{LABELS}] })` → `mcp__linear__save_issue({ id: "{ISSUE_ID}", state: "{TRACKER_STATE}" })`.
66
+ - **Comments:** The engine may append routine reports to its own eligible progress comment; explicit session/run ownership keeps invocations separate. Attention and terminal reports use new comments. Comment preparation, delivery, MCP fallback and friction failures are nonfatal: attempt best-effort friction and continue substantive work. **If** `tracker.done` = false and `commentFile` is available → attempt one new comment from that file byte-for-byte via `mcp__linear__save_comment({ issueId: "{ISSUE_ID}", body: "{BODY}" })` (no `id`); NEVER edit prior tracker content or rebuild the fallback body. A missing file or exhausted fallback is an attempted report, not a workflow blocker. Every comment gate requires an attempt or an applicable skip. **If** `SESSION_DIR` is not held → re-run the workflow's Step 1 `repo info` call and hold `sessionDir` as `SESSION_DIR` before the call; keep `--session-dir` on the call, because `bkit issues comment` refuses a call with no workflow-run proof.
61
67
 
62
68
  <!-- bkit:tracker linear end -->
63
69
  <!-- bkit:tracker jira start -->
64
70
 
65
71
  - **Tracker:** Jira — `bkit` verbs read and write it over the same Rovo MCP endpoint; MCP server `jira` (`.mcp.json` `mcpServers.jira`) ONLY when a verb exits 80 or prints `done` = false. Tools: `mcp__jira__getJiraIssue`, `mcp__jira__editJiraIssue`, `mcp__jira__transitionJiraIssue`, `mcp__jira__addOrEditJiraIssueComment`, `mcp__jira__searchJiraIssuesUsingJql`, `mcp__jira__executeRead`; every call passes `cloudId: "{TRACKER_SITE}"`. Assert `{ISSUE_ID}` / `{TRACKER_SITE}` / `{STATE}` / `{LABELS}` non-empty before tool calls; writes best-effort, NEVER gate; **If** failure → retry once after 5s → continue. `getJiraIssue` ALWAYS passes `view: "evidence"` (other views omit labels). `editJiraIssue` `fields.labels` replaces the whole set → pass full printed `LABELS`; labels and status in separate calls, labels first; NEVER pass `fields` / `update` to `transitionJiraIssue`. Status change: `executeRead({ name: "listJiraIssueTransitions", inputs: { issueIdOrKey } })` → transition whose `to.name` = target status → `transitionJiraIssue({ issueIdOrKey, transitionId })`; none → log `Unapplied: status "<name>" not reachable`, no retry, continue. Comment reads: `executeRead({ name: "listJiraIssueComments", inputs: { issueIdOrKey, maxResults: 100, startAt } })`, oldest first, raise `startAt` while `isLast` is false; page with `appliedContentFormat` = `html` → re-read it one comment per call (`maxResults: 1`).
66
- - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (bkit-auto trigger gate), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
67
- - **Comments:** A step's `bkit` block posts the `comment` it prints with `--post` before its gate and prints `tracker`; every gate includes `Issue comment attempted (Step N section)`. **If** `tracker.done` = false → post the content of the printed `commentFile` byte-for-byte as a new comment via `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`); NEVER shorten, reword, or rebuild it. NEVER edit, paraphrase, summarise, truncate, deduplicate, or reorder prior tracker content. Fallback body over 32,767 characters → post as consecutive comments split at line breaks, in order (the engine splits its own posts the same way).
72
+ - **Labels:** Phase labels `bkit:design`, `bkit:plan`, `bkit:build`, `bkit:debug`, `bkit:ship`, `bkit:merged` (mutually exclusive; a phase start drops the old phase, every `next:*` and `bkit:failed`). Additive labels: `bkit:auto` (the opt-in the cloud gate job reads before it starts a run), `bkit:failed` (Failure Path). `bkit issues labels --write` computes and writes each transition. Fallback (`tracker.done` = false): `mcp__jira__editJiraIssue({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", fields: { labels: [{LABELS}] } })` → move status to `{TRACKER_STATE}` (**Tracker** status change).
73
+ - **Comments:** The engine may append routine reports to its own eligible progress comment; explicit session/run ownership keeps invocations separate. Attention and terminal reports use new comments. Comment preparation, delivery, MCP fallback and friction failures are nonfatal: attempt best-effort friction and continue substantive work. **If** `tracker.done` = false and `commentFile` is available → attempt one new comment from that file byte-for-byte via `mcp__jira__addOrEditJiraIssueComment({ cloudId: "{TRACKER_SITE}", issueIdOrKey: "{ISSUE_ID}", commentBody: "{BODY}" })` (no `commentId`); NEVER edit prior tracker content or rebuild the fallback body. A missing file or exhausted fallback is an attempted report, not a workflow blocker. Every comment gate requires an attempt or an applicable skip. **If** `SESSION_DIR` is not held → re-run the workflow's Step 1 `repo info` call and hold `sessionDir` as `SESSION_DIR` before the call; keep `--session-dir` on the call, because `bkit issues comment` refuses a call with no workflow-run proof. Fallback body over 32,767 characters → post as consecutive comments split at line breaks, in order (the engine splits its own posts the same way).
68
74
 
69
75
  <!-- bkit:tracker jira end -->
70
76
  <!-- bkit:tracker true start -->
@@ -73,7 +79,7 @@ description: "Ship Feature — Autonomous merge and archive"
73
79
 
74
80
  <!-- bkit:tracker true end -->
75
81
 
76
- - **Limits:** `bkit.workflows.ship.merge` holds `ask` and `maxAttempts`, read via `bkit counters route --point=` in fenced routing blocks below. One count covers every failed arrival at the merge step — a merge-gate refusal (`ship-gate-refusal` rows, the regenerate round's red CI run included) or a failed merge (`ship-merge-pr` rows). Merge attempts used up with `ask` = true and not headless → the **Merge Question**, where `Try again` gives the merge step one more full allowance (`bkit counters grant`) and it asks again once that allowance is used up too; `ask` = false, or headless → **Failure Path**. Within the limit, `ask` applies only before a failure fix round, never to a refusal that just needs CI again or to the regenerate round, which no model decides. Assumed items from build are asked once, at **Confirm Assumed Items**, whatever `ship.merge.ask` says.
82
+ - **Limits:** `bkit.workflows.ship.merge` holds `ask` and `maxAttempts`, read via `bkit counters route --point=` in fenced routing blocks below. One count covers every failed arrival at the merge step — a merge-gate refusal (`ship-gate-refusal` rows, the regenerate round's red CI run included) or a failed merge (`ship-merge-pr` rows). Merge attempts used up with `ask` = true and not headless → the **Merge Question**, where `Try again` gives the merge step one more full allowance (`bkit counters grant`) and it asks again once that allowance is used up too; `ask` = false, or headless → **Failure Path**. Within the limit, ship never asks. Assumed items from build are asked once, at **Confirm Assumed Items**, whatever `ship.merge.ask` says.
77
83
 
78
84
  **Rules:** Copied word for word from `.agents/rules.md`.
79
85
 
@@ -88,9 +94,11 @@ description: "Ship Feature — Autonomous merge and archive"
88
94
 
89
95
  1. Write the error message / tool response to `{OUTBOX_ROOT}/error.md` (`--error-file` dropped while `{OUTBOX_ROOT}` is not held). `{STDERR_FILE}` = `{OUTBOX}/stderr.log` holding the failed shell command's stderr — drop `--stderr-file` when the failure was not a shell command or `{OUTBOX}` is not set yet; drop `--token` when `{LOCK_TOKEN}` is empty, `--pr` when `{PR_NUMBER}` is empty; `--max-exceeded` only when a `counters route` exit 1 (a `MAX_*` limit) sent the run here; `{LABEL_FLAGS}` = one `--label=<name>` per current `LABELS` entry. Abort any in-progress rebase or merge, record the failure, release the lock, delete the session folder (drop `--session-dir` while `{SESSION_DIR}` is not held), clear sentinels — **state only, no `add` / `commit` / `push`**; a MERGED PR moves the issue to `bkit:merged` plus `bkit:failed`, else the prior phase label persists:
90
96
  ```bash
91
- "{BKIT}" workflows fail --post --issue="{ISSUE_ID}" --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded --pr={PR_NUMBER} {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}" --session-dir="{SESSION_DIR}"
97
+ "{BKIT}" workflows fail --post --issue="{ISSUE_ID}" --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} --max-exceeded --pr={PR_NUMBER} {LABEL_FLAGS} --step-number={N} --step-title="{Step Name}" --sub-step={M} --error-file="{OUTBOX_ROOT}/error.md" --stderr-file="{STDERR_FILE}" --next-step="{NEXT_STEP}" --session-dir="{SESSION_DIR}"
92
98
  ```
99
+ Drop `--next-step` when `NEXT_STEP` is not held.
93
100
  Hold `handoverNeeded` as `HANDOVER_NEEDED`, `labels` as `LABELS` and `trackerState` as `TRACKER_STATE`.
101
+ **If** exit 6 (a refused `--next-step`, including an unsubstituted placeholder, which no other usage error shares) → the value was refused before any write: clear `NEXT_STEP` and run the block again without `--next-step`, then route on that exit.
94
102
  **If** exit non-zero → log `Lock removal failed` with the printed `lock` to stderr, then continue.
95
103
  2. <!-- bkit:tracker true start -->
96
104
  **Skip if** `ISSUE_ID` empty. **If** `tracker.done` = false → post `comment` via the tracker MCP per the header's fallback section. **If** `labelsWrite.done` = false → apply the printed `labels` / `trackerState` via the tracker MCP (**Labels** fallback).
@@ -98,11 +106,11 @@ description: "Ship Feature — Autonomous merge and archive"
98
106
  3. **If** `HANDOVER_NEEDED` = true → step 4. **Else** → step 5.
99
107
  4. Write the run's diff to the file the agent reads (a failure leaves it out):
100
108
  ```bash
101
- cd "{WORKTREE_PATH}" && "{BKIT}" context diff --reset-log --artifact="tmp/bkit-diff-{FID}.md" --fid={FID} --step=abort-handover >/dev/null
109
+ cd "{WORKTREE_PATH}" && "{BKIT}" context diff --reset-log --artifact="tmp/bkit-diff-{FID}.md" --base=origin/dev --fid={FID} --step=abort-handover >/dev/null
102
110
  ```
103
111
  **Subagent:** Invoke `@bkit-debug-abort-handover` using `Agent` tool:
104
112
  Context: You are a subagent in the Ship Debug phase. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
105
- Read: `{STATUS}`, `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md` (if present), `docs/plans/{YYYYMM}/logs/{FID}/ship-deferred-sweep.md` (if present), glob `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-diagnose-*.md`, glob `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-remediate-*-log.md`, `tmp/bkit-diff-{FID}.md` (the run's diff, if present).
113
+ Read: `{STATUS}`, `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md` (if present), `docs/plans/{YYYYMM}/logs/{FID}/ship-deferred-sweep.md` (if present), `tmp/bkit-diff-{FID}.md` (the run's diff, if present).
106
114
  Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-handover.md`.
107
115
  5. **If** `SUMMARY_VERDICT` = FAIL → read `{WORKTREE_PATH}/docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md` now, because the flush removes the worktree.
108
116
  Flush the run's book to `dev` as one commit and one push. **Skip if** `FID` **or** `YYYYMM` is empty. Drop `--worktree` when `WORKTREE_PATH` is not set:
@@ -112,7 +120,7 @@ description: "Ship Feature — Autonomous merge and archive"
112
120
  The block posts a non-null `comment`, which links the handover only where the flush pushed it.
113
121
  **If** `tracker.done` = false → post `comment` via the tracker MCP per the header's fallback section.
114
122
  **If** the push failed → do not claim success on the tracker.
115
- 6. **STOP**, no further downstream steps. **If** `SUMMARY_VERDICT` = FAIL → the final message is `ship-summary.md` content verbatim.<!-- bkit:tracker true start --> Line 1 of the final message = the no-issue warning, when one was emitted.<!-- bkit:tracker true end -->
123
+ 6. **STOP**, no further downstream steps. **If** `SUMMARY_VERDICT` = FAIL → the final message is `ship-summary.md` content verbatim.<!-- bkit:tracker true start --> Line 1 of the final message = the no-issue warning, when one was emitted.<!-- bkit:tracker true end --> **If** `NEXT_STEP` is held → the final message's last line is `Next step: {NEXT_STEP}`, after any verbatim summary.
116
124
 
117
125
  ---
118
126
 
@@ -132,7 +140,7 @@ description: "Ship Feature — Autonomous merge and archive"
132
140
  "{BKIT}" fids parse --prompt-file="{SESSION_DIR}/prompt.md"
133
141
  ```
134
142
  <!-- bkit:tracker true start -->
135
- **If** exit 8 → **STOP**; tell the user the prompt names more than one issue (`ambiguous`) and to name the issue as `#N`, its key or its URL; never the **Failure Path**.
143
+ **If** exit 8 → ask the owner in this session, plain text, not through a host question tool, in one message with no tests or edits: `**Q1 — Issue:** the prompt names more than one issue. Which one did you mean?`, then one option line per issue `fids parse` printed under `ambiguous` (`Use {issue} — the run works on {issue}`) and `Stop — nothing changes; the run can be started again`, lettered in that order, then `Recommended: none — only you know which issue you meant` and `Default if unanswered: the run waits for you; the run stops when nobody can be asked`, then the line `Reply with a letter per question. "stop" ends here; nothing has changed yet, so the run can be started again.` Write no status row (none exists yet); end turn → wait for the answer; no status file yet. On a pick, write the issue reference with the file-write tool to `{SESSION_DIR}/owner-answer.md` and re-run `fids parse --prompt-file="{SESSION_DIR}/owner-answer.md"`; on `Stop` → **STOP**; never the **Failure Path**.
136
144
  <!-- bkit:tracker true end -->
137
145
  Hold `fidNamed` as `FID_NAMED`. Hold `issue` as `ISSUE_ID`, `ref` as `REF`.
138
146
  <!-- bkit:tracker false start -->
@@ -146,7 +154,7 @@ description: "Ship Feature — Autonomous merge and archive"
146
154
  Route:
147
155
  - **If** exit 0 and `issueId` non-null → hold `issueId` as `ISSUE_ID`.
148
156
  - **If** exit 0 and `issueId` null → set `ISSUE_ID=""` → emit the no-issue warning once `FID` is held → continue; NEVER create a tracker issue.
149
- - **If** exit 3 → **STOP**; tell the user to rename `BRANCH` to `feat/{lowercase-slug}` or name an issue; never the **Failure Path**.
157
+ - **If** exit 3 → **Action needed — Branch name:** rename `BRANCH` to `feat/{lowercase-slug}`, or name an issue. Then say "continue". Write no status row (none exists yet); end turn → wait for the answer; no status file yet. On "continue" re-run this block; never the **Failure Path**.
150
158
  - **Else** → **Failure Path**.
151
159
  <!-- bkit:tracker true end -->
152
160
  3. <!-- bkit:tracker true start -->
@@ -169,7 +177,7 @@ description: "Ship Feature — Autonomous merge and archive"
169
177
  Route:
170
178
  - **If** exit 0 → hold `fid` as `FID`; one `FID` for all artifacts.
171
179
  - **If** exit 4 → **Failure Path** listing `fids` (name the `FID` in the session prompt to pick one).
172
- - **If** exit 9 → **STOP**; tell the user the prompt holds only a bare number and to name the issue as `#N`, its key or its URL; never the **Failure Path**.
180
+ - **If** exit 9 → **Action needed — Issue reference:** name the issue as `#N`, its key or its URL. Then say "continue". Write no status row (none exists yet); end turn → wait for the answer; no status file yet. On "continue" write the named reference with the file-write tool to `{SESSION_DIR}/owner-answer.md`, re-run `fids parse --prompt-file="{SESSION_DIR}/owner-answer.md"` and this block on it; never the **Failure Path**.
173
181
  - **Else** → **Failure Path**.
174
182
  5. Detect the runtime:
175
183
  ```bash
@@ -180,7 +188,7 @@ description: "Ship Feature — Autonomous merge and archive"
180
188
  ```bash
181
189
  "{BKIT}" locks acquire --kind=workflow --workflow=ship --fid="{FID}"
182
190
  ```
183
- Hold `token` as `LOCK_TOKEN`, `month` as `YYYYMM`.
191
+ Route: hold `token` as `LOCK_TOKEN`, `month` as `YYYYMM`. Follow `route`: `go` → next sub-step; `stop` → tell the owner `message` → **STOP**, with no **Failure Path**, label, comment or status row, because the other run is healthy and keeps its lock; no `route` → **Failure Path**.
184
192
  7. Resolve `SHIP_BRANCH`, then create or resume the worktree, or adopt it in place (no rebase — Path A). This runs straight after the lock, so every later failure has a book to keep its record in. `--branch` = the branch the session prompt names, dropped when it names none:
185
193
  <!-- bkit:tracker true start -->
186
194
  **If** `ISSUE_ID` empty → drop `--issue`.
@@ -204,7 +212,7 @@ description: "Ship Feature — Autonomous merge and archive"
204
212
  Then hold `path` as `STATUS` and `bookRoot` as `BOOK_ROOT`.
205
213
  Open the run and record the runtime. The block refuses a checkout not on `SHIP_BRANCH` (15), clears stale sentinels, and writes the `workflow-started` and `ship-start-workflow` rows:
206
214
  ```bash
207
- "{BKIT}" workflows start --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --branch="{SHIP_BRANCH}" --lock-held --token="{LOCK_TOKEN}" || exit 1
215
+ "{BKIT}" workflows start --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --branch="{SHIP_BRANCH}" --session-dir="{SESSION_DIR}" --lock-held --token="{LOCK_TOKEN}" || exit 1
208
216
  "{BKIT}" steps done --workflow=ship --step=ship-start-workflow --file="{STATUS}" --commit=none >/dev/null || exit 1
209
217
  "{BKIT}" runtime row --workflow=ship --file="{STATUS}" >/dev/null || exit 1
210
218
  "{BKIT}" runtime assert --workflow=ship --file="{STATUS}" >/dev/null
@@ -238,6 +246,7 @@ description: "Ship Feature — Autonomous merge and archive"
238
246
  ```
239
247
 
240
248
  - [ ] Mechanical checks passed (`steps gate`)
249
+ - [ ] Issue comment attempted when applicable
241
250
  - [ ] Issue resolved
242
251
  - [ ] Worktree ready and run opened
243
252
  - [ ] Outbox created
@@ -260,17 +269,41 @@ description: "Ship Feature — Autonomous merge and archive"
260
269
  "{BKIT}" workflows input --workflow=ship --fid={FID} --run={RUN} --file="{STATUS}" --prompt-file="{SESSION_DIR}/prompt.md"<!-- bkit:tracker true start --> --description-file="{SESSION_DIR}/issue-description.md" --comments-file="{SESSION_DIR}/issue-comments.json"<!-- bkit:tracker true end --> --plan="docs/plans/{YYYYMM}/{FID}-plan.md" || exit 1
261
270
  ```
262
271
  2. Find the branch's PR — open first, then merged:
272
+ Reconcile and publish before probing or opening a PR, including on resume:
273
+
274
+ ```bash
275
+ "{BKIT}" branches sync --reconcile-feature --fid="{FID}" --file="{STATUS}"
276
+ ```
277
+
278
+ Route — first match wins:
279
+ - **If** exit 24 → hold `target` as `MERGE_TARGET`, `pending` as `PENDING`, set `RECONCILE_NEXT` = Step 2 → Step 4 sub-step 2.
280
+ - **If** exit 0 → hold `reconciledHead` as `ENTRY_HEAD` and `CODE_HEAD` → publish the resulting local head before sweep/docs bookkeeping.
281
+ ```bash
282
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain --set-upstream --ahead-of=origin/dev >/dev/null
283
+ ```
284
+ Route:
285
+ **If** exit 81 → end turn, re-run this block. **If** another non-zero exit → **Failure Path**.
286
+ - **Else** → **Failure Path**.
287
+
263
288
  ```bash
264
- "{BKIT}" prs probe --head="{SHIP_BRANCH}" --state=all
289
+ "{BKIT}" prs probe --head="{SHIP_BRANCH}" --base=dev --state=all --ship-entry --owner-repo="{OWNER_REPO}"
265
290
  ```
291
+
266
292
  Hold `number` as `PR_NUMBER`, `baseRefName` as `PR_BASE`, and hold `state`.
293
+ **If** exit 80 **or** `runtimeGithubCli` = false → read open PRs first, then merged PRs through MCP, independently reread the selected PR, and write `{ ownerRepo, headRefName, baseRefName: "dev", pr }` to `{OUTBOX}/ship-entry-facts.json`. `pr` is the complete `PrInfo` shape (`number`, `url`, `state`, `baseRefName`, `headRefName`, `headRefOid`, `title`, `mergeCommit`, `mergeable`), or null when neither exists. Record the single transport transition under **gh MCP fallback**, then use the engine's result:
294
+
295
+ ```bash
296
+ "{BKIT}" prs probe --head="{SHIP_BRANCH}" --base=dev --state=all --ship-entry --owner-repo="{OWNER_REPO}" --facts-file="{OUTBOX}/ship-entry-facts.json"
297
+ ```
298
+
299
+ Missing or mismatched facts → **Failure Path** before opening or merging anything. A merged PR with extra feature work returns exit 1: open a new PR, preserving that work.
267
300
  Route — first match wins:
268
301
  - **If** exit 0 **and** `PR_BASE` != dev → **Failure Path**.
269
302
  - **If** exit 0 → sub-step 3.
270
303
  - **If** exit 1 → open a PR and set `SHIP_OPENED_PR` = true. **If** `docs/plans/{YYYYMM}/{FID}-plan.md` exists → the block names it in the PR body:
271
304
 
272
305
  ```bash
273
- "{BKIT}" branches push --mode=plain --set-upstream --ahead-of=origin/dev >/dev/null || exit $?
306
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain --set-upstream --ahead-of=origin/dev >/dev/null || exit $?
274
307
  OPEN_EXIT=0
275
308
  "{BKIT}" prs open --fid="{FID}" --title="feat({FID}): {summary}" --issue="{ISSUE_ID}" --plan="docs/plans/{YYYYMM}/{FID}-plan.md" --file="{STATUS}" --workflow=ship --note="⚠️ PR opened by /bkit-ship — no PR existed for this branch." || OPEN_EXIT=$?
276
309
  case "$OPEN_EXIT" in 0 | 80) "{BKIT}" status meta --file="{STATUS}" --workflow=ship --opened-pr >/dev/null || exit 1 ;; esac
@@ -280,7 +313,7 @@ description: "Ship Feature — Autonomous merge and archive"
280
313
  Route:
281
314
  - **If** exit 81 → end turn, re-run this block.
282
315
  - **If** exit 0 → continue with the next instruction.
283
- - **If** exit 80 → `create_pull_request` with the printed `title`, `body`, `base` and `head`.
316
+ - **If** exit 80 → `create_pull_request` with the printed `title`, `base` and `head`, and the content of the printed `bodyFile` as `body`.
284
317
  - **Else** → **Failure Path**.
285
318
 
286
319
  Re-run the `bkit prs probe` above.
@@ -288,8 +321,9 @@ description: "Ship Feature — Autonomous merge and archive"
288
321
  Assert `PR_NUMBER` non-empty and `PR_BASE` = dev. **If** the assertion fails → **Failure Path**.
289
322
 
290
323
  - **Else** → **Failure Path**.
324
+
291
325
  3. Route:
292
- - **If** `state` = MERGED → record the resume marker → Step 13:
326
+ - **If** `state` = MERGED → record the resume marker → Step 11:
293
327
  ```bash
294
328
  "{BKIT}" status row --file="{STATUS}" --workflow=ship --type=ship-merged-on-entry >/dev/null
295
329
  ```
@@ -302,16 +336,22 @@ description: "Ship Feature — Autonomous merge and archive"
302
336
  Assert `ENTRY_HEAD` non-empty.
303
337
  5. **If** `SHIP_OPENED_PR` = true → wait for CI on the new PR first, then assert its check rollup green:
304
338
  ```bash
305
- "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=present --budget-s=120 || exit 1
306
- "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=completed
307
- "{BKIT}" prs checks --number="{PR_NUMBER}" >/dev/null
339
+ "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=present --budget-s=120 || exit $?
340
+ WAIT_EXIT=0
341
+ "{BKIT}" runs wait --pr="{PR_NUMBER}" --until=completed || WAIT_EXIT=$?
342
+ [ "$WAIT_EXIT" -le 1 ] || exit "$WAIT_EXIT"
343
+ "{BKIT}" prs checks --number="{PR_NUMBER}"
308
344
  ```
309
- Route:
345
+ Hold `failed` as `CHECKS_FAILED`. `failed` counts only checks that concluded red; `cancelled` counts checks that finished without a verdict. Route:
346
+ - **If** exit 81 → end turn, re-run this block.
310
347
  - **If** exit 0 → next sub-step.
311
- - **If** exit 80 → read the checks with `pull_request_read` (`get_status`):
312
- - **If** there is no check, **or** any check failed or is pending → **Failure Path**.
313
- - **Else** → next sub-step.
314
- - **Else** → **Failure Path**.
348
+ - **If** exit 1 **and** `CHECKS_FAILED` > 0 (a check concluded red: the CI run is red) → hold `/bkit-debug {FID}` as `NEXT_STEP` → **Failure Path**.
349
+ - **If** exit 80 → read the check runs for the PR head with `pull_request_read` (`get_check_runs`), or `actions_list` runs for the head SHA:
350
+ - **If** any check concluded failure, timed out, startup failure or error (a commit status of `error`), and is not cancelled, action required or stale → hold `/bkit-debug {FID}` as `NEXT_STEP` → **Failure Path**.
351
+ - **If** there is no check, **or** any check is pending → **Failure Path**.
352
+ - **If** any check is cancelled, action required or stale → **Failure Path**.
353
+ - **Else** → next sub-step, only when every check passed (success, neutral or skipped).
354
+ - **Else** (the rollup is unreadable) → **Failure Path**.
315
355
  6. Finish (bookkeeping to `$BOOK_ROOT`, no branch commit):
316
356
  ```bash
317
357
  "{BKIT}" steps done --workflow=ship --step=ship-worktree-setup --file="{STATUS}" --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md" --commit=none >/dev/null || exit 1
@@ -343,9 +383,12 @@ description: "Ship Feature — Autonomous merge and archive"
343
383
  - **If** `ASSUMED_COUNT` = 0 → return to Step 2.
344
384
  - **If** `RUNTIME_HEADLESS` = true → step 4, since there is no one to ask.
345
385
  - **Else** → step 2.
346
- 2. Ask the owner in this session. Write in plain text, not through a host question tool. NEVER hand the questions to subagents. State what the owner must decide and what each option does, in plain English, before naming any file, test or identifier. Send one message:
347
- - For each entry of `ASSUMED_ITEMS`, in order, numbered from 1: `**Q{n} — {title}:** accepted without you during build ({reason}). Confirm it?`, then `Options: A) Confirm / B) Reject`, then `No recommendation — only you can accept it`.
348
- - End the message with the line `Reply per question. Ship merges either way; anything not confirmed is written as a needs-decision deferral.`
386
+ 2. Ask the owner in this session. Write in plain text, not through a host question tool. NEVER hand the questions to subagents. State 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. Send one message:
387
+ - For each entry of `ASSUMED_ITEMS`, in order, numbered from 1: `**Q{n} — {title}:** accepted without you during build ({reason}). Confirm it?`, then the option lines, each on its own line:
388
+ A) Confirm — the accept is recorded as yours, as a decision row
389
+ B) Reject — the item is written as a needs-decision deferral
390
+ - Then `Recommended: none — only you can accept it`, then `Default if unanswered: written as a needs-decision deferral`.
391
+ - End the message with the line `Reply with a letter per question. Ship merges either way; anything you do not confirm is written as a needs-decision deferral.`
349
392
 
350
393
  Then record the wait → end turn → wait for answers:
351
394
 
@@ -384,11 +427,21 @@ description: "Ship Feature — Autonomous merge and archive"
384
427
 
385
428
  ## 🤖 Step 3 — Base Check
386
429
 
387
- 1. Determine whether `origin/dev` is an ancestor of the PR head:
430
+ 1. Reconcile again on every integration retry, then publish before selecting `BASE_PATH`:
431
+ ```bash
432
+ "{BKIT}" branches sync --reconcile-feature --fid="{FID}" --file="{STATUS}"
433
+ ```
434
+ Hold `basePath` as `BASE_PATH`, `reconciledHead` as `ENTRY_HEAD` and `CODE_HEAD`. **If** exit 24 → hold `target` as `MERGE_TARGET`, `pending` as `PENDING`, set `RECONCILE_NEXT` = Step 3 → Step 4 sub-step 2. **If** another non-zero exit → **Failure Path**.
388
435
  ```bash
389
- "{BKIT}" branches sync --head="{ENTRY_HEAD}"
436
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain --set-upstream --ahead-of=origin/dev >/dev/null
390
437
  ```
391
- Hold `basePath` as `BASE_PATH`.
438
+ Route:
439
+ **If** exit 81 → end turn, re-run this block. **If** another non-zero exit → **Failure Path**.
440
+ Compute the merge-aware feature coverage state:
441
+ ```bash
442
+ "{BKIT}" branches sync --feature-state --month="{YYYYMM}" --fid="{FID}"
443
+ ```
444
+ Hold `featureCodeState` as `FEATURE_CODE_STATE`. Non-zero exit → **Failure Path**. Bookkeeping commits and proven automatic base-only merges retain coverage. New feature commits, imported feature merges and semantic conflict resolutions invalidate coverage. Unproven merge results remain in the state. Record this exact state with each successful sweep/docs completion below; read those rows from `{STATUS}` on resume.
392
445
  2. Route:
393
446
  - **If** `BASE_PATH` = A → Step 5 (skip integration — dev has not moved; no `bkit:generate`, because CI fails on a stale generated file and Step 10 regenerates when that is the only failure).
394
447
  - **If** `BASE_PATH` = B → Step 4 (integration required; its merge runs `bkit:generate`).
@@ -406,13 +459,13 @@ description: "Ship Feature — Autonomous merge and archive"
406
459
 
407
460
  ## 🧠 Step 4 — Integrate (Path B only)
408
461
 
409
- **Run only if** `BASE_PATH` = B.
462
+ **Run only if** `BASE_PATH` = B **or** a feature reconciliation left `PENDING` conflicts.
410
463
 
411
464
  1. Merge `origin/dev` into `SHIP_BRANCH` locally. The block commits the run's uncommitted work first, unions the append-only ledgers, regenerates a conflicted lockfile from `dev`'s copy, rebuilds a conflicted generated register from `dev`'s copy, takes `dev`'s copy of the generated block in a conflicted embedding doc (a doc the register's script copies that block into) and merges the rest of that doc, merges a conflicted install record (`.bkit/version`) entry by entry with `dev`'s value where both sides changed an entry, runs a declared `bkit:generate`, and leaves every other conflict in the tree for sub-step 2. GitHub ignores `merge=union`, so the merged commit, not a server-side update or a rebase, is what makes the PR mergeable. No commit the block makes carries a skip token, so the sub-step 3 push starts CI at the merged head and Step 9 waits on that run:
412
465
  ```bash
413
- cd "{WORKTREE_PATH}" && "{BKIT}" branches sync --merge --fid="{FID}" --file="{STATUS}" --sentinel="docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed"
466
+ cd "{WORKTREE_PATH}" && "{BKIT}" branches sync --merge --fid="{FID}" --file="{STATUS}" --target="origin/dev" --sentinel="docs/plans/{YYYYMM}/logs/{FID}/.rebase-failed"
414
467
  ```
415
- Hold `outcome` as `MERGE_OUTCOME`, `pending` as `PENDING`.
468
+ Hold `outcome` as `MERGE_OUTCOME`, `pending` as `PENDING`, `target` as `MERGE_TARGET`, and `head` as `CODE_HEAD` and `ENTRY_HEAD`. Set `RECONCILE_NEXT` empty for this dev integration.
416
469
  Route:
417
470
  - **If** exit 0 **and** `MERGE_OUTCOME` = merged → sub-step 3.
418
471
  - **If** exit 0 **and** `MERGE_OUTCOME` = current → Step 5. `dev` has not moved since Step 3.
@@ -420,7 +473,7 @@ description: "Ship Feature — Autonomous merge and archive"
420
473
  - **Else** → **Failure Path**. The block aborted the merge and wrote the sentinel.
421
474
  2. Resolve the conflicts the block left:
422
475
  1. **Subagent:** Invoke `@bkit-ship-conflict-resolve` using `Agent` tool:
423
- Context: You are a subagent in the Ship phase. A merge of `origin/dev` is in progress with conflicts outside the ledgers, the lockfile, the generated register, the embedding docs and the install record: `{PENDING}`. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
476
+ Context: You are a subagent in the Ship phase. A merge of the engine-recorded target `{MERGE_TARGET}` is in progress with conflicts outside the ledgers, the lockfile, the generated register, the embedding docs and the install record: `{PENDING}`. Continue only this target. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
424
477
  Read: `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md`, `docs/plans/{YYYYMM}/{FID}-plan.md` (if present), `{STATUS}`.
425
478
  Update: Conflicted source files.
426
479
  Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-conflict-resolve.md`.
@@ -431,14 +484,18 @@ description: "Ship Feature — Autonomous merge and archive"
431
484
  3. **If** `verdict` = PASS → sub-step 3. The subagent's re-run of the block committed the merge.
432
485
  **Else** → **Failure Path** (non-mechanical conflict → handover).
433
486
  3. Push the merged branch. The merge adds commits on top of the pushed head, so the push is plain, NEVER forced:
487
+
434
488
  ```bash
435
- "{BKIT}" branches push --mode=plain >/dev/null
489
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain >/dev/null
436
490
  ```
491
+
437
492
  Route:
438
493
  - **If** exit 81 → end turn, re-run this block.
439
494
  - **If** exit 0 → continue with the next instruction.
440
495
  - **Else** → **Failure Path**.
441
496
 
497
+ **If** `RECONCILE_NEXT` is held → return there and reconcile again. **Else** → refresh `ENTRY_HEAD` and `CODE_HEAD` with `git rev-parse HEAD` → Step 5, which recomputes coverage after the integration and any conflict resolution.
498
+
442
499
  ### 🔒 Gate 4 — Integrate
443
500
 
444
501
  - [ ] Path classified
@@ -451,10 +508,15 @@ description: "Ship Feature — Autonomous merge and archive"
451
508
 
452
509
  ## 🤖 Step 5 — Deferred Sweep
453
510
 
454
- 1. Fast-forward to the PR head, never onto a diverged branch:
455
- ```bash
456
- "{BKIT}" branches fast-forward --onto="origin/{SHIP_BRANCH}" >/dev/null || exit $?
457
- ```
511
+ Recompute coverage immediately before deciding whether to reuse the sweep:
512
+
513
+ ```bash
514
+ "{BKIT}" branches sync --feature-state --month="{YYYYMM}" --fid="{FID}"
515
+ ```
516
+
517
+ Refresh `FEATURE_CODE_STATE` from `featureCodeState`; non-zero exit → **Failure Path**.
518
+
519
+ 1. Read the latest successful `ship-feature-coverage` row for `step=ship-deferred-sweep` from `{STATUS}`. **If** its recorded feature-code state matches `FEATURE_CODE_STATE` and its artifact still exists → reuse it and skip to Step 6. **If** the state changed, differs or is missing → invoke the sweep again below. Never reuse a completion from a different feature state.
458
520
  2. Check for the plan:
459
521
  ```bash
460
522
  cd "{WORKTREE_PATH}" && "{BKIT}" fids plans --fid="{FID}" --month="{YYYYMM}"
@@ -468,10 +530,14 @@ description: "Ship Feature — Autonomous merge and archive"
468
530
  ```
469
531
  Write the run's diff to the file the agent reads:
470
532
  ```bash
471
- cd "{WORKTREE_PATH}" && "{BKIT}" context diff --reset-log --artifact="tmp/bkit-diff-{FID}.md" --fid={FID} --step=ship-deferred-sweep >/dev/null || exit 2
533
+ cd "{WORKTREE_PATH}" && "{BKIT}" context diff --reset-log --artifact="tmp/bkit-diff-{FID}.md" --base=origin/dev --fid={FID} --step=ship-deferred-sweep >/dev/null || exit 2
534
+ ```
535
+ Get the sweep's own invocation id from the engine and keep the printed `invocation` as `INVOCATION`. The invocation, its operations and their receipts are recorded in the book-root status file (`{STATUS}` under `$BOOK_ROOT`), so a resumed ship run reuses them:
536
+ ```bash
537
+ "{BKIT}" status invocation --workflow=ship --step=ship-deferred-sweep --file="{STATUS}" --agent=bkit-ship-deferred-sweep
472
538
  ```
473
539
  **Subagent:** Invoke `@bkit-ship-deferred-sweep` using `Agent` tool:
474
- Context: You are a subagent in the Ship phase. Pre-merge completeness gate. FID: `{FID}`. Diff base: `origin/dev` — run `bkit branches scan-diff --disabled-tests --base=origin/dev`. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
540
+ Context: You are a subagent in the Ship phase. Pre-merge completeness gate. FID: `{FID}`. Diff base: `origin/dev` — run `bkit branches scan-diff --disabled-tests --base=origin/dev`. Its ledger appends run under invocation `{INVOCATION}`. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
475
541
  Read: `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md`, `docs/plans/{YYYYMM}/{FID}-plan.md` (if present), `docs/plans/{YYYYMM}/{FID}-design.md` (if present), `{STATUS}`, `docs/deferrals.jsonl`, glob `docs/plans/{YYYYMM}/logs/{FID}/*-plan-verify*.md`, glob `docs/plans/{YYYYMM}/logs/{FID}/*-challenge*.md`, glob `docs/plans/{YYYYMM}/logs/{FID}/*-summary.md`, `tmp/bkit-diff-{FID}.md` (the run's diff).
476
542
  Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-deferred-sweep.md`.
477
543
  3. Finish (bookkeeping to `$BOOK_ROOT`):
@@ -479,7 +545,10 @@ description: "Ship Feature — Autonomous merge and archive"
479
545
  "{BKIT}" steps finish --workflow=ship --step=ship-deferred-sweep --file="{STATUS}" --agent=bkit-ship-deferred-sweep --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-deferred-sweep.md" --commit=none --number=5 --post --title="Deferred Sweep"
480
546
  ```
481
547
  4. Route:
482
- - **If** `verdict` = PASS → Step 6.
548
+ - **If** `verdict` = PASS → record the covered feature-code state → Step 6:
549
+ ```bash
550
+ "{BKIT}" status row --file="{STATUS}" --workflow=ship --type=ship-feature-coverage --field=step=ship-deferred-sweep --field="featureCodeState={FEATURE_CODE_STATE}" >/dev/null || exit 1
551
+ ```
483
552
  - **If** `verdict` = FAIL → write the `.deferred-blocked` sentinel below under `BOOK_ROOT`, then **Failure Path**.
484
553
  ```bash
485
554
  touch "{BOOK_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/.deferred-blocked"
@@ -488,7 +557,7 @@ description: "Ship Feature — Autonomous merge and archive"
488
557
 
489
558
  ### 🔒 Gate 5 — Deferred Sweep
490
559
 
491
- - [ ] Worktree fast-forwarded
560
+ - [ ] Reconciled feature-code state compared with recorded sweep coverage
492
561
  - [ ] Subagent invoked (`@bkit-ship-deferred-sweep`, no inline work)
493
562
  - [ ] Mechanical checks passed (`steps finish`)
494
563
 
@@ -496,6 +565,16 @@ description: "Ship Feature — Autonomous merge and archive"
496
565
 
497
566
  ## 🧠 Step 6 — Update Docs & Summary
498
567
 
568
+ Refresh coverage again before deciding whether to reuse the docs artifact:
569
+
570
+ ```bash
571
+ "{BKIT}" branches sync --feature-state --month="{YYYYMM}" --fid="{FID}"
572
+ ```
573
+
574
+ Hold the current `featureCodeState` as `FEATURE_CODE_STATE`; non-zero exit → **Failure Path**.
575
+
576
+ Read the latest successful `ship-feature-coverage` row for `step=ship-update-docs` from `{STATUS}`. **If** its recorded feature-code state matches `FEATURE_CODE_STATE` and the docs artifact exists → reuse it and skip sub-steps 1-3. **If** the state changed, differs or is missing → run the docs agent again. Always refresh the summary in sub-step 4.
577
+
499
578
  1. Write the FID's deferral lines to the artifact the docs agent reads `Pending Items` from:
500
579
  ```bash
501
580
  cd "{WORKTREE_PATH}" && "{BKIT}" context ledger-scan --terms="{FID}" --source=docs/deferrals.jsonl --artifact="{OUTBOX}/ship-pending-items.md" --fid={FID} --step=ship-update-docs --reset-log >/dev/null || exit 1
@@ -505,16 +584,19 @@ description: "Ship Feature — Autonomous merge and archive"
505
584
  Read: `docs/plans/{YYYYMM}/{FID}-plan.md` (if present), glob `docs/plans/{YYYYMM}/logs/{FID}/*.md` (excluding `*-summary.md` / `*-handover.md`), `{OUTBOX}/ship-pending-items.md`.
506
585
  Update: Doc files.
507
586
  Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-update-docs.md`.
587
+ Documentation maintenance findings (unresolved coverage and the `## Documentation Warnings` records) stay in the ship summary next to the edits; a missing document is reported and the ship continues.
508
588
  3. Wait for the subagent to complete. Then append the `SHIPPED` row to the worktree ledger, re-render the mechanical `roadmap-status` board from it, and finish the step (bookkeeping to `$BOOK_ROOT`). The block exits 1 when the row did not land:
509
589
  ```bash
510
590
  "{BKIT}" roadmap feature --root="{WORKTREE_PATH}" --workflow=ship --fid="{FID}" --step=ship-update-docs --strict >/dev/null || exit 1
511
591
  "{BKIT}" steps finish --workflow=ship --step=ship-update-docs --file="{STATUS}" --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-update-docs.md" --commit=none || exit 1
592
+ "{BKIT}" status row --file="{STATUS}" --workflow=ship --type=ship-feature-coverage --field=step=ship-update-docs --field="featureCodeState={FEATURE_CODE_STATE}" >/dev/null || exit 1
512
593
  ```
513
594
  4. Write `ship-summary.md` from this run's status rows and the PR's size:
514
595
  ```bash
515
596
  "{BKIT}" workflows summary --workflow=ship --file="{STATUS}" --pr={PR_NUMBER}
516
597
  ```
517
598
  **If** exit non-zero → **Failure Path**. Hold `verdict` as `SUMMARY_VERDICT`, `failures` as `SUMMARY_FAILURES`.
599
+ The summary's `## Documentation Warnings` section lists this run's attributed documentation gaps once per topic and gap, with the evidence and action each agent gave. It is advisory: it changes no verdict. Show it in the final return and do not re-aggregate it.
518
600
  5. Finish (bookkeeping to `$BOOK_ROOT`):
519
601
  ```bash
520
602
  "{BKIT}" steps finish --workflow=ship --step=ship-summary --file="{STATUS}" --attempt=1 --verdict={SUMMARY_VERDICT} --failures={SUMMARY_FAILURES} --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md" --commit=none --number=6 --post --title="Update Docs & Summary" --link-ref=dev --comment-body
@@ -563,7 +645,7 @@ description: "Ship Feature — Autonomous merge and archive"
563
645
  Hold `parentSha` as `CODE_HEAD`.
564
646
  2. **If** the printed `outcome` = committed → push, and NEVER force:
565
647
  ```bash
566
- "{BKIT}" branches push --mode=plain >/dev/null
648
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain >/dev/null
567
649
  ```
568
650
  Route:
569
651
  - **If** exit 81 → end turn, re-run this block.
@@ -580,10 +662,28 @@ description: "Ship Feature — Autonomous merge and archive"
580
662
 
581
663
  ## 🤖 Step 9 — Re-validate
582
664
 
665
+ **If** `RECONCILE_REQUIRED` = true → clear it → Step 3 before validation. A previous `DONE` row alone never proves coverage of imported feature code.
666
+
583
667
  1. Resolve the head CI must pass at. The block re-validates when the code moved **or** `REVALIDATE_REASON` = `gate-refusal`: it probes for a run at it first, dispatches only when none, and waits for it to complete. Drop `--reason` when `REVALIDATE_REASON` is empty:
668
+
584
669
  ```bash
585
- "{BKIT}" runs revalidate --pr="{PR_NUMBER}" --entry-head="{ENTRY_HEAD}" --code-head="{CODE_HEAD}" --branch="{SHIP_BRANCH}" --month="{YYYYMM}" --fid="{FID}" --file="{STATUS}" --reason="{REVALIDATE_REASON}" --repo="{OWNER_REPO}"
670
+ "{BKIT}" runs revalidate --pr="{PR_NUMBER}" --require-reconciled --entry-head="{ENTRY_HEAD}" --code-head="{CODE_HEAD}" --branch="{SHIP_BRANCH}" --month="{YYYYMM}" --fid="{FID}" --file="{STATUS}" --reason="{REVALIDATE_REASON}" --repo="{OWNER_REPO}"
586
671
  ```
672
+
673
+ Hold `reconcileRequired` as `RECONCILE_REQUIRED`.
674
+ Route:
675
+ - **If** exit 21 → set `RECONCILE_REQUIRED` = true → route the recorded failed arrival to reconciliation:
676
+ ```bash
677
+ "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-3 --exceeded=failure-path
678
+ ```
679
+ Hold `value` as `MERGE_ROUNDS`, `max` as `MERGE_MAX` and `ask` as `MERGE_ASK`.
680
+ - **If** exit 0 → Step 3.
681
+ - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 3 → **Merge Question**.
682
+ - **Else** → **Failure Path**.
683
+ - **If** exit 0 → continue with the next instruction.
684
+ - **If** exit 81 → end turn, re-run this block.
685
+ - **Else** → **Failure Path**.
686
+
587
687
  Hold `validatedHead` as `VALIDATED_HEAD`.
588
688
 
589
689
  ### 🔒 Gate 9 — Re-validate
@@ -601,11 +701,31 @@ description: "Ship Feature — Autonomous merge and archive"
601
701
 
602
702
  1. Assert the gate at the PR's current head, with CI checked at `VALIDATED_HEAD`. This gate is the ONLY merge precondition. The block writes the pre-merge snapshot to the outbox before the gate decides, refuses a title that carries a skip token (18), and records a refusal in `{STATUS}`:
603
703
  ```bash
604
- "{BKIT}" runs gate --pr="{PR_NUMBER}" --validated="{VALIDATED_HEAD}" --month="{YYYYMM}" --fid="{FID}" --repo="{OWNER_REPO}" --branch="{SHIP_BRANCH}" --fetch --file="{STATUS}" --snapshot="{OUTBOX}/pre-merge-snapshot.jsonl" --record="{STATUS}"
704
+ "{BKIT}" runs gate --pr="{PR_NUMBER}" --validated="{VALIDATED_HEAD}" --month="{YYYYMM}" --fid="{FID}" --repo="{OWNER_REPO}" --branch="{SHIP_BRANCH}" --fetch --fresh-base --file="{STATUS}" --snapshot="{OUTBOX}/pre-merge-snapshot.jsonl" --record="{STATUS}"
705
+ ```
706
+ **If** exit 80 **or** `runtimeGithubCli` = false → use narrowly scoped MCP PR/Actions reads and compare `dev` against `VALIDATED_HEAD`. The engine must establish `base.ref` = `dev`; a mismatch takes the **Failure Path**. Write `{ ownerRepo, prNumber, headRefName, baseRefName: "dev", pr, ci: { workflowRuns, jobs }, base: { ref: "dev", sha, comparedHead, status } }` to `{OUTBOX}/ship-gate-facts.json`. `workflowRuns` and `jobs` use the Actions API payloads, and `base.sha` is the freshly read dev commit used by the compare API. Each run must carry its positive integer `id`, `repository.full_name`, `head_repository.full_name`, configured workflow `path` (or matching numeric `workflow_id`), `head_sha`, `head_branch` and repository-scoped `html_url`. Both repositories must match `ownerRepo`; the head must match `VALIDATED_HEAD` and `headRefName`. Each job must carry `run_id`, `run_url` and `head_sha` matching its selected run and repository. Retain every jobs page in the paginated array. Independently reread the PR and base before accepting the facts, and record the single transport transition under **gh MCP fallback**. Missing, unavailable or mismatched evidence → **Failure Path** before mutation. Return the facts to the same gate:
707
+ ```bash
708
+ "{BKIT}" runs gate --pr="{PR_NUMBER}" --validated="{VALIDATED_HEAD}" --month="{YYYYMM}" --fid="{FID}" --repo="{OWNER_REPO}" --branch="{SHIP_BRANCH}" --fresh-base --facts-file="{OUTBOX}/ship-gate-facts.json" --file="{STATUS}" --snapshot="{OUTBOX}/pre-merge-snapshot.jsonl" --record="{STATUS}"
605
709
  ```
606
710
  Route:
607
711
  - **If** exit 0 → hold `mergeHead` as `GATE_HEAD` → sub-step 2.
608
- - **If** exit 11 (in progress — poll), 14 (stale green), 10 (no run) **or** 17 (non-bookkeeping change past `VALIDATED_HEAD`) → route on the failed arrivals at Step 10, without asking:
712
+ - **If** exit 19 (stale base) → the gate already recorded one failed arrival; route to integration:
713
+ ```bash
714
+ "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-3 --exceeded=failure-path
715
+ ```
716
+ Hold `value` as `MERGE_ROUNDS`, `max` as `MERGE_MAX` and `ask` as `MERGE_ASK`.
717
+ - **If** exit 0 → Step 3.
718
+ - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 3 → **Merge Question**.
719
+ - **Else** → **Failure Path**, preserving the branch and worktree on exhaustion.
720
+ - **If** exit 17 (non-bookkeeping change past `VALIDATED_HEAD`) → set `RECONCILE_REQUIRED` = true → route the recorded failed arrival to reconciliation:
721
+ ```bash
722
+ "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-3 --exceeded=failure-path
723
+ ```
724
+ Hold `value` as `MERGE_ROUNDS`, `max` as `MERGE_MAX` and `ask` as `MERGE_ASK`.
725
+ - **If** exit 0 → Step 3.
726
+ - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 3 → **Merge Question**.
727
+ - **Else** → **Failure Path**.
728
+ - **If** exit 11 (in progress — poll), 14 (stale green) **or** 10 (no run) → route on the failed arrivals at Step 10, without asking:
609
729
  ```bash
610
730
  "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-9 --exceeded=failure-path
611
731
  ```
@@ -613,6 +733,7 @@ description: "Ship Feature — Autonomous merge and archive"
613
733
  - **If** exit 0 → set `{REVALIDATE_REASON}` = `gate-refusal` → Step 9.
614
734
  - **If** exit 1 **and** `MERGE_ASK` = true → set `{REVALIDATE_REASON}` = `gate-refusal`, `LIMIT_NEXT` = Step 9 → **Merge Question**.
615
735
  - **Else** → **Failure Path** (exit 1: `ship.merge.maxAttempts` used up, max-retry exhaustion).
736
+ - **If** exit 12 **and** `regenerable` = false → the CI run is red and regenerating cannot fix it. Hold `/bkit-debug {FID}` as `NEXT_STEP` → **Failure Path**.
616
737
  - **If** exit 12 **and** `regenerable` = true → every failed CI step is one `bkit:generate` fixes (`bkit.testing.ciGenerated`). Route on the failed arrivals at Step 10, without asking:
617
738
  ```bash
618
739
  "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-9 --exceeded=failure-path
@@ -626,7 +747,7 @@ description: "Ship Feature — Autonomous merge and archive"
626
747
  - **If** exit 0 **and** `REGEN_OUTCOME` = committed → push the fix, and NEVER force:
627
748
 
628
749
  ```bash
629
- "{BKIT}" branches push --mode=plain >/dev/null
750
+ BKIT_PR_CONFLICT_CHECK=false "{BKIT}" branches push --mode=plain >/dev/null
630
751
  ```
631
752
 
632
753
  Route:
@@ -636,10 +757,10 @@ description: "Ship Feature — Autonomous merge and archive"
636
757
 
637
758
  Then set `REVALIDATE_REASON` empty → Step 9 (re-validate at the regenerated head, then re-run the merge gate).
638
759
 
639
- - **Else** → **Failure Path** (`unchanged`: regenerating does not fix the failed steps; `undeclared`; or the block failed).
640
- - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = sub-step 1, which routes the red run again within the new allowance → **Merge Question**.
641
- - **Else** → **Failure Path** (exit 1: `ship.merge.maxAttempts` used up, max-retry exhaustion).
642
- - **Else** (12, 13, 15, 16, 18 or 20) → **Failure Path**.
760
+ - **Else** → **Failure Path** (`unchanged`: regenerating does not fix the failed steps; `undeclared`; or the block failed). **If** `REGEN_OUTCOME` = `unchanged` **or** `undeclared` → hold `/bkit-debug {FID}` as `NEXT_STEP` first.
761
+ - **If** exit 1 **and** `MERGE_ASK` = true → hold `/bkit-debug {FID}` as `NEXT_STEP`, `LIMIT_NEXT` = sub-step 1, which routes the red run again within the new allowance → **Merge Question**.
762
+ - **Else** → hold `/bkit-debug {FID}` as `NEXT_STEP` → **Failure Path** (exit 1: `ship.merge.maxAttempts` used up, max-retry exhaustion).
763
+ - **Else** (13, 15, 16, 18 or 20) → **Failure Path**.
643
764
  2. Merge with an empty body and `--match-head`, so GitHub refuses when the head moved. Re-read the labels from the tracker, so that ` bkit [auto route]` rides the squash subject on `bkit:auto`. The labels are never carried forward from Step 1's `{LABELS}`. `{LABEL_FLAGS}` = one `--label=<name>` per re-read `LABELS` entry, empty when no tracker is wired<!-- bkit:tracker true start --> or `ISSUE_ID` is empty<!-- bkit:tracker true end -->:
644
765
  <!-- bkit:tracker true start -->
645
766
  **Skip if** `ISSUE_ID` empty. Re-read the issue:
@@ -649,28 +770,41 @@ description: "Ship Feature — Autonomous merge and archive"
649
770
  Hold `state` as `STATE`, `labels` as `LABELS`. **If** exit 80 → read them via the tracker MCP (**Tracker**).
650
771
  <!-- bkit:tracker true end -->
651
772
  ```bash
652
- "{BKIT}" prs merge --number="{PR_NUMBER}" --match-head="{GATE_HEAD}" --delete-branch {LABEL_FLAGS} --expect-merged
773
+ "{BKIT}" prs merge --number="{PR_NUMBER}" --match-head="{GATE_HEAD}" --ship-retry --owner-repo="{OWNER_REPO}" {LABEL_FLAGS} --expect-merged
653
774
  ```
654
775
  Route:
655
- - **If** exit 0 **or** 7 → hold `verdict` as `MERGE_VERDICT`, `failures` as `MERGE_FAILURES`, and hold `state`.
656
- - **If** exit 80 → `pull_request_read` (`get`) and assert `base.ref` = `dev`; mismatch → **Failure Path** with nothing merged; then `merge_pull_request` and read `state` back through `pull_request_read` → `MERGE_VERDICT` = PASS and `MERGE_FAILURES` = 0 when merged, else FAIL and 1.
657
- - **Else** (8: the PR's base is not `dev`, nothing merged) → **Failure Path**.
776
+ - **If** exit 0, 5, 7, 8, 9 **or** 10 → hold `route` as `MERGE_ROUTE`, `reason` as `MERGE_REASON`, `verdict` as `MERGE_VERDICT`, `failures` as `MERGE_FAILURES`, and hold `state` → sub-step 3. Missing output fields → **Failure Path**.
777
+ - **If** exit 80 **or** `runtimeGithubCli` = false → read fresh pre-attempt PR facts through `pull_request_read` (`get`). Refresh the scoped gate facts above with this PR, fresh CI and base evidence, and run that engine gate again before mutation. Only exit 0 authorizes `merge_pull_request`, with `sha` = the newly printed `GATE_HEAD`, the skip-token-free PR subject and an empty body. A gate refusal takes sub-step 1's route and consumes only its existing refusal row. After the attempt, independently reread post-attempt PR state through `pull_request_read`; never copy the mutation response or pre-attempt facts into `after`. Write `{ ownerRepo, prNumber, headRefName, baseRefName: "dev", matchHead, before, after }` to `{OUTBOX}/ship-merge-facts.json`, with complete `PrInfo` values for both reads and `matchHead` = `GATE_HEAD`. Missing or mismatched evidence → **Failure Path**. Record the single transport transition under **gh MCP fallback**, then classify without a second mutation:
778
+ ```bash
779
+ "{BKIT}" prs merge --number="{PR_NUMBER}" --match-head="{GATE_HEAD}" --ship-retry --owner-repo="{OWNER_REPO}" --facts-file="{OUTBOX}/ship-merge-facts.json" {LABEL_FLAGS} --expect-merged
780
+ ```
781
+ Hold the same route, reason, verdict, failures and state as the gh-backed result → sub-step 3.
782
+ - **Else** → **Failure Path**.
658
783
  3. Finish (bookkeeping to `$BOOK_ROOT`):
659
784
  ```bash
660
785
  "{BKIT}" steps finish --workflow=ship --step=ship-merge-pr --file="{STATUS}" --verdict={MERGE_VERDICT} --failures={MERGE_FAILURES} --attempt=next --commit=none --number=10 --post --title="Merge Gate + Merge PR"
661
786
  ```
662
787
  Hold `attempt` as `MERGE_ATTEMPT`.
663
788
  4. Route:
664
- - **If** `state` = MERGED → Step 13.
665
- - **If** `state` != MERGED → run counter routing:
789
+ - **If** `state` = MERGED → Step 11.
790
+ - **If** `MERGE_ROUTE` = revalidate (exit 9) → Step 9 through the durable counter:
666
791
  ```bash
667
- "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-11 --exceeded=failure-path
792
+ "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-9 --exceeded=failure-path
668
793
  ```
669
794
  Hold `value` as `MERGE_ROUNDS`, `max` as `MERGE_MAX` and `ask` as `MERGE_ASK`.
670
- - **If** exit 0 → Step 11.
671
- - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 11 → **Merge Question**.
795
+ Set `RECONCILE_REQUIRED` = true and `REVALIDATE_REASON` = gate-refusal, so imported feature work passes the state comparison and sweep/docs gates before CI.
796
+ - **If** exit 0 → Step 9.
797
+ - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 9 → **Merge Question**.
672
798
  - **Else** → **Failure Path** (exit 1: `ship.merge.maxAttempts` used up, max-retry exhaustion).
673
- - **Else** → **Failure Path**.
799
+ - **If** `MERGE_ROUTE` = integrate (exit 10) → Step 3 through the same durable counter:
800
+ ```bash
801
+ "{BKIT}" counters route --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --file="{STATUS}" --workflow=ship --point=ship.merge --continue=step-3 --exceeded=failure-path
802
+ ```
803
+ Hold `value` as `MERGE_ROUNDS`, `max` as `MERGE_MAX` and `ask` as `MERGE_ASK`.
804
+ - **If** exit 0 → Step 3.
805
+ - **If** exit 1 **and** `MERGE_ASK` = true → `LIMIT_NEXT` = Step 3 → **Merge Question**.
806
+ - **Else** → **Failure Path** on exhaustion.
807
+ - **Else** → terminal stop → **Failure Path**, naming `MERGE_REASON`. Each attempted merge is counted by its one `ship-merge-pr` row; each refused gate is counted by its one `ship-gate-refusal` row. Do not add another refusal row for either event.
674
808
 
675
809
  ### 🔒 Gate 10 — Merge Gate + Merge PR
676
810
 
@@ -685,14 +819,17 @@ description: "Ship Feature — Autonomous merge and archive"
685
819
 
686
820
  ## 🤖 Merge Question
687
821
 
688
- Asked from Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held) and from Step 11 before a fix round the diagnosis found no clear cause. State the failure in plain English before the technical cause.
822
+ Asked from Step 9 or Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held). State the failure in plain English before the technical cause.
689
823
 
690
824
  1. Ask the human in this session, in plain text, in one message:
691
- - `ship merge: attempt {MERGE_ROUNDS} of {MERGE_MAX}`, then the first question that matches:
692
- - **If** `LIMIT_NEXT` is held → `**Q1 — Merge:** The merge attempts are used up ({the last refusal or failure in one line}). Stop here instead of trying one more set of attempts?`
693
- - **Else** → `**Q1 — Merge:** failed, and the diagnosis found no clear cause ({the diagnosis in one line}). Stop here instead of a fix round?`
694
- - `Options: A) Stop / B) Try again`, then `Recommended: A) Stop — {reason}`.
695
- - End the message with the line `Reply per question. "yes" takes every recommendation. "stop" writes a handover; the run can be resumed.`
825
+ - `ship merge: attempt {MERGE_ROUNDS} of {MERGE_MAX}`, then `**Q1 — Merge:** The merge attempts are used up ({the last refusal or failure in one line}). Stop here instead of trying one more set of attempts?`
826
+ - The merge options:
827
+ ```text
828
+ A) Stop — the run ends here with a handover; the next run resumes here
829
+ B) Try again — one more set of merge attempts runs
830
+ ```
831
+ - Then `Recommended: A) Stop — {reason}`, then `Default if unanswered: the run waits for you`.
832
+ - End the message with the line `Reply with a letter per question, or "yes" to take every recommendation. "stop" ends here with a handover; the next run resumes here.`
696
833
 
697
834
  Record the wait → end turn → wait for the answer:
698
835
 
@@ -707,20 +844,18 @@ Asked from Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held)
707
844
  ```
708
845
 
709
846
  A reply that names a letter (`B`, `B)` or `B) {option}`) means the option that letter labels.
710
- - **If** the answer is `Try again` **and** `LIMIT_NEXT` is held → give the merge step one more full allowance, then clear `LIMIT_NEXT` and go to the step it named:
847
+ - **If** the answer is `Try again` → give the merge step one more full allowance, then clear `LIMIT_NEXT` and `NEXT_STEP` and go to the step `LIMIT_NEXT` named:
711
848
  ```bash
712
849
  "{BKIT}" counters grant --name=MERGE_ATTEMPT --of=ship-merge-pr:count --rows=ship-gate-refusal:count --point=ship.merge --file="{STATUS}" --workflow=ship >/dev/null || exit 1
713
850
  ```
714
- - **If** the answer is `Try again` → return to the calling step.
715
851
  - **If** the answer is `Stop` → create `docs/plans/{YYYYMM}/logs/{FID}/ship-handover.md` with the question, the answer and the line `Stopped by the owner; run stays IN_PROGRESS. /bkit-ship {FID} resumes at Step 10.`
852
+ **If** `NEXT_STEP` is held → add the line `Next step: {NEXT_STEP}` to the handover after the resume line, and end the final message with the same line.
716
853
  Then push it and release the lock. NEVER run `workflows fail`:
717
854
  ```bash
718
855
  "{BKIT}" workflows handover --post --workflow=ship --fid={FID} --month={YYYYMM} --push --worktree="{WORKTREE_PATH}"
719
856
  "{BKIT}" locks release --kind=workflow --workflow=ship --fid={FID} --month={YYYYMM} --token={LOCK_TOKEN} >/dev/null || exit 1
720
857
  ```
721
- Route:
722
- - **If** the handover exits non-zero → **Failure Path**.
723
- - **Else** → **STOP**, no further downstream steps.
858
+ Route: add `message` to the final message when it is not empty → follow `route`: `stop` → **STOP**, no further downstream steps; none printed → **Failure Path**.
724
859
  - **Else** → answer the reply in plain text and ask Q1 again in the same message, then record the wait and end the turn:
725
860
  ```bash
726
861
  "{BKIT}" status row --file="{STATUS}" --workflow=ship --type=owner-pause --field=reason=merge >/dev/null || exit 1
@@ -734,109 +869,40 @@ Asked from Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held)
734
869
 
735
870
  ---
736
871
 
737
- ## 🧠 Step 11 — Failure Diagnose
738
-
739
- **Run only if** `state` != MERGED.
740
-
741
- 1. **Subagent:** Invoke `@bkit-debug-failure-diagnose` using `Agent` tool:
742
- Context: You are a subagent in the Ship Debug phase. Merge failure during Ship workflow. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
743
- Read: `docs/plans/{YYYYMM}/logs/{FID}/ship-input-{RUN}.md`, `docs/plans/{YYYYMM}/{FID}-plan.md` (if present), `{STATUS}`.
744
- Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-diagnose-{MERGE_ATTEMPT}.md`.
745
- 2. Finish (bookkeeping to `$BOOK_ROOT`):
746
- ```bash
747
- "{BKIT}" steps finish --workflow=ship --step=ship-failure-diagnose --file="{STATUS}" --attempt-of=ship-merge-pr:current --agent=bkit-debug-failure-diagnose --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-failure-diagnose-<attempt>.md" --commit=none --number=11 --post --title="Failure Diagnose"
748
- ```
749
- Hold `verdict` as `DIAGNOSE_VERDICT`.
750
- 3. Ask before the fix round only when the diagnosis found no clear cause.
751
- **If** `MERGE_ASK` = false **or** `DIAGNOSE_VERDICT` = PASS → narrate `ship merge: attempt {MERGE_ROUNDS} of {MERGE_MAX}, fix round taken without asking ({the diagnosed cause})` → Step 12.
752
- **Else** → **Merge Question** → Step 12.
753
-
754
- ### 🔒 Gate 11 — Failure Diagnose
755
-
756
- - [ ] Subagent invoked (`@bkit-debug-failure-diagnose`, no inline work)
757
- - [ ] Mechanical checks passed (`steps finish`)
758
- - [ ] Fix round asked only with `ask` = true, not headless, and a diagnosis verdict other than PASS
759
-
760
- ---
761
-
762
- ## 🧠 Step 12 — Failure Remediate
763
-
764
- **Run only if** `state` != MERGED.
765
-
766
- 1. Derive the next strategy rung from `{STATUS}`:
767
- ```bash
768
- "{BKIT}" status route --file="{STATUS}" --workflow=ship --step=ship-failure-remediate --require=strategy
769
- ```
770
- Hold `nextStrategy` as `STRATEGY`.
771
- 2. **Subagent:** Invoke `@bkit-debug-failure-remediate` using `Agent` tool:
772
- Context: You are a subagent in the Ship Debug phase. Merge failure during Ship workflow. `Strategy`: `{STRATEGY}`. Switch into the working directory with `cd "{WORKTREE_PATH}"`, check it with `pwd`, and use it for every file operation that follows.
773
- Read: `{STATUS}`, `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-diagnose-{MERGE_ATTEMPT}.md`.
774
- Create: `docs/plans/{YYYYMM}/logs/{FID}/ship-failure-remediate-{MERGE_ATTEMPT}-log.md`.
775
- 3. Finish (bookkeeping to `$BOOK_ROOT`), which records the header's `Strategy`:
776
- ```bash
777
- "{BKIT}" steps finish --workflow=ship --step=ship-failure-remediate --file="{STATUS}" --attempt-of=ship-merge-pr:current --agent=bkit-debug-failure-remediate --artifact="docs/plans/{YYYYMM}/logs/{FID}/ship-failure-remediate-<attempt>-log.md" --commit=none --number=12 --post --title="Failure Remediate"
778
- ```
779
- 4. Route on `verdict`:
780
- - **If** `verdict` = PASS:
781
- - **If** `MERGE_ATTEMPT` is not held (resumed into this step) → read the merge round back:
782
- ```bash
783
- "{BKIT}" counters derive --file="{STATUS}" --workflow=ship --step=ship-merge-pr --position=current
784
- ```
785
- Hold `value` as `MERGE_ATTEMPT`.
786
- - Commit and push the fix, and NEVER force:
787
-
788
- ```bash
789
- "{BKIT}" ledgers commit --month="{YYYYMM}" --fid="{FID}" --scope=full --mode=commit --stage-tracked-updates --message="fix({FID}): failure-remediate attempt {MERGE_ATTEMPT}" >/dev/null \
790
- || { echo "[bkit-ship] failure-remediate commit failed" >&2; exit 1; }
791
- "{BKIT}" branches push --mode=plain >/dev/null
792
- ```
793
-
794
- Route:
795
- - **If** exit 81 → end turn, re-run this block.
796
- - **If** exit 0 → continue with the next instruction.
797
- - **Else** → **Failure Path**.
798
-
799
- - Set `REVALIDATE_REASON` empty → Step 9 (re-validate, then re-run the merge).
800
- - **Else** → **Failure Path**.
801
-
802
- ### 🔒 Gate 12 — Failure Remediate
803
-
804
- - [ ] Subagent invoked (`@bkit-debug-failure-remediate`, no inline work)
805
- - [ ] Mechanical checks passed (`steps finish`)
806
- - [ ] Fix committed and pushed
807
-
808
- ---
809
-
810
- ## 🤖 Step 13 — Update Local Dev
872
+ ## 🤖 Step 11 — Update Local Dev
811
873
 
812
874
  **Run only if** `state` = MERGED.
813
875
 
814
876
  1. Fast-forward local `dev` to `origin/dev`, then finish:
815
877
  ```bash
816
878
  "{BKIT}" branches sync-dev || exit 1
817
- "{BKIT}" steps finish --workflow=ship --step=ship-switch-to-dev --file="{STATUS}" --commit=none --number=13 --post --title="Update Local Dev" --tree=dev
879
+ "{BKIT}" steps finish --workflow=ship --step=ship-switch-to-dev --file="{STATUS}" --commit=none --number=11 --post --title="Update Local Dev" --tree=dev
818
880
  ```
819
881
 
820
- ### 🔒 Gate 13 — Update Local Dev
882
+ ### 🔒 Gate 11 — Update Local Dev
821
883
 
822
884
  - [ ] Local `dev` synced (`branches sync-dev`)
823
885
  - [ ] Mechanical checks passed (`steps finish`)
824
886
 
825
887
  ---
826
888
 
827
- ## 🤖 Step 14 — Close Workflow
889
+ ## 🤖 Step 12 — Close Workflow
828
890
 
829
- 1. Assert that the capstone passed at the squash commit. The block records the squash-merge CI verdict (`ship-merge-ci`) before routing:
891
+ 1. Assert that the capstone passed at the squash commit. The block reads the squash commit, waits until its CI run has finished, and records the squash-merge CI verdict (`ship-merge-ci`) before routing; it writes no row while the run is missing or still running:
830
892
  ```bash
831
- "{BKIT}" runs gate --squash-of="{PR_NUMBER}" --repo="{OWNER_REPO}" --capstone-only --record="{STATUS}"
893
+ "{BKIT}" runs gate --squash-of="{PR_NUMBER}" --repo="{OWNER_REPO}" --capstone-only --record="{STATUS}" --wait
832
894
  ```
833
- Hold `head` as `SQUASH_SHA`.
834
- 2. Close the run. The block keeps the summary in the outbox (the close removes the worktree it lives in), lands `docs({FID}): ship DONE bkit [skip ci]` on `dev` (a refused push opens a `ship-close/{FID}` PR), releases the lock, removes the worktree and `SHIP_BRANCH`, and returns to `REPO_ROOT`:
895
+ Route:
896
+ - **If** exit 0 → hold `head` as `SQUASH_SHA` → sub-step 2.
897
+ - **If** exit 81 → end turn, re-run this block.
898
+ - **If** exit 12 → the squash commit's CI is red. Hold `/bkit-debug {FID}` as `NEXT_STEP` → **Failure Path**.
899
+ - **Else** → **Failure Path**.
900
+ 2. Close the run. The block keeps the summary in the outbox, lands `docs({FID}): ship DONE bkit [skip ci]` on `dev` (a refused push opens a `ship-close/{FID}` PR), releases the lock, and returns to `REPO_ROOT`. Guarded cleanup removes only a clean worktree and a local branch whose inspected content is landed, binding local deletion to the inspected tip. It preserves dirty or unlanded work and reports retained paths/refs. The remote feature branch is deleted only at its inspected landed tip and retained when origin refuses that conditional deletion; this does not block close-record landing or lock release. Repository-managed automatic branch deletion is a separate GitHub setting outside this cleanup guarantee:
835
901
  <!-- bkit:tracker true start -->
836
902
  **If** the no-issue warning was emitted → add `--warning="<that warning>"`.
837
903
  <!-- bkit:tracker true end -->
838
904
  ```bash
839
- "{BKIT}" workflows close --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --pr-number="{PR_NUMBER}" --squash-sha="{SQUASH_SHA}" --owner-repo="{OWNER_REPO}" --outbox="{OUTBOX}" --flush --token="{LOCK_TOKEN}" --branch="{SHIP_BRANCH}" --number=14 --post --title="Close Workflow" --final-return --summary="docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md" --summary-missing="PR was already merged — no ship summary this run." --session-dir="{SESSION_DIR}"; rc=$?
905
+ "{BKIT}" workflows close --workflow=ship --fid="{FID}" --month="{YYYYMM}" --file="{STATUS}" --pr-number="{PR_NUMBER}" --squash-sha="{SQUASH_SHA}" --owner-repo="{OWNER_REPO}" --outbox="{OUTBOX}" --flush --token="{LOCK_TOKEN}" --branch="{SHIP_BRANCH}" --number=12 --post --title="Close Workflow" --final-return --summary="docs/plans/{YYYYMM}/logs/{FID}/ship-summary.md" --summary-missing="PR was already merged — no ship summary this run." --session-dir="{SESSION_DIR}"; rc=$?
840
906
  cd "{REPO_ROOT}"; exit $rc
841
907
  ```
842
908
  Hold `landed.via` as `CLOSE_VIA`, `finalReturn` as `FINAL_RETURN`.
@@ -851,7 +917,7 @@ Asked from Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held)
851
917
  4. Final return: display `{FINAL_RETURN}` verbatim as the final message to the user; do not summarise or trim; do not auto-invoke. **HARD STOP**.
852
918
  5. **If** user requests plain English explanation → restate the summary in plain English; name terms and say what they mean; identifiers stay verbatim; plainness lives in sentences, not nouns; do not re-run any step.
853
919
 
854
- ### 🔒 Gate 14 — Close Workflow
920
+ ### 🔒 Gate 12 — Close Workflow
855
921
 
856
922
  ```bash
857
923
  "{BKIT}" steps gate --file="{REPO_ROOT}/docs/plans/{YYYYMM}/logs/{FID}/status.jsonl" --ref=origin/dev --workflow=ship --step=ship-close-workflow
@@ -859,9 +925,9 @@ Asked from Step 10 when `ship.merge.maxAttempts` is used up (`LIMIT_NEXT` held)
859
925
 
860
926
  **If** `CLOSE_VIA` = close-pr-open → drop `--ref`, and gate with `--file="{STATUS}"`.
861
927
 
862
- - [ ] Squash-merge CI capstone green (`runs gate`)
928
+ - [ ] Squash-merge CI waited for and capstone green (`runs gate --wait`)
863
929
  - [ ] Close landed (`workflows close`)
864
- - [ ] Worktree removed and feature branch deleted, back in the repo root
930
+ - [ ] Guarded cleanup and retained paths/refs reported, back in the repo root
865
931
  - [ ] Mechanical checks passed (`steps gate`)
866
932
  - [ ] Logs retained
867
933
  - [ ] Final return displayed