@cbartens/bkit 5.2.4 → 5.4.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 (271) hide show
  1. package/.bkit/README.md +27 -11
  2. package/.bkit/core/.agents/context.md +1 -1
  3. package/.bkit/core/.agents/docs.md +1 -1
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +1 -1
  5. package/.bkit/core/.agents/rules.md +18 -1
  6. package/.bkit/core/.bkit/README.md +26 -10
  7. package/.bkit/core/.bkit/cloud.md +40 -39
  8. package/.bkit/core/.bkit/comparison.md +68 -345
  9. package/.bkit/core/.bkit/install.md +16 -9
  10. package/.bkit/core/.bkit/lite.md +73 -0
  11. package/.bkit/core/.bkit/pipeline.md +346 -0
  12. package/.bkit/core/.bkit/prompts.md +90 -74
  13. package/.bkit/core/.bkit/providers.md +42 -23
  14. package/.bkit/core/.bkit/templates.md +138 -19
  15. package/.bkit/core/.bkit/trackers.md +49 -4
  16. package/.bkit/core/.bkit/workflows.md +144 -123
  17. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +1 -1
  18. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +7 -4
  19. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +8 -5
  20. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  21. package/.bkit/core/docs/templates/bkit-audit-adoption.md +2 -2
  22. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  23. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  26. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  28. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  30. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  31. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  32. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  34. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  35. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +26 -21
  37. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  39. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  40. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  41. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  42. package/.bkit/core/docs/templates/bkit-audit-issues.md +3 -2
  43. package/.bkit/core/docs/templates/bkit-audit-llm.md +22 -15
  44. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  45. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-prompts.md +7 -7
  48. package/.bkit/core/docs/templates/bkit-audit-red-team.md +12 -9
  49. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  50. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-security.md +14 -12
  52. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-testing.md +10 -8
  54. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  55. package/.bkit/core/docs/templates/bkit-plan.md +8 -6
  56. package/.bkit/core/engine/checks/after/auth.ts +9 -9
  57. package/.bkit/core/engine/checks/after/ci-yml.ts +14 -12
  58. package/.bkit/core/engine/checks/after/github.ts +29 -120
  59. package/.bkit/core/engine/checks/after/index.ts +2 -2
  60. package/.bkit/core/engine/checks/after/managed.ts +8 -28
  61. package/.bkit/core/engine/checks/after/tools.ts +3 -15
  62. package/.bkit/core/engine/checks/before/context-fetch.ts +1 -21
  63. package/.bkit/core/engine/checks/before/index.ts +7 -43
  64. package/.bkit/core/engine/checks/before/mcp.ts +17 -8
  65. package/.bkit/core/engine/checks/before/repo.ts +9 -12
  66. package/.bkit/core/engine/checks/status-holes.ts +4 -6
  67. package/.bkit/core/engine/checks/tips/catalogue.ts +76 -24
  68. package/.bkit/core/engine/checks/tips/detect.ts +45 -2
  69. package/.bkit/core/engine/checks/tips/index.ts +77 -26
  70. package/.bkit/core/engine/cli.ts +57 -27
  71. package/.bkit/core/engine/commands/analysis.ts +36 -26
  72. package/.bkit/core/engine/commands/comply.ts +42 -32
  73. package/.bkit/core/engine/commands/harvest.ts +12 -12
  74. package/.bkit/core/engine/commands/install/doctor.ts +57 -28
  75. package/.bkit/core/engine/commands/install/install.ts +73 -130
  76. package/.bkit/core/engine/commands/install/uninstall.ts +191 -33
  77. package/.bkit/core/engine/commands/install/upgrade.ts +49 -43
  78. package/.bkit/core/engine/commands/land.ts +156 -0
  79. package/.bkit/core/engine/commands/lib.ts +45 -18
  80. package/.bkit/core/engine/commands/registry.ts +2 -0
  81. package/.bkit/core/engine/commands/tips.ts +12 -5
  82. package/.bkit/core/engine/commands/workflow/branches.ts +386 -286
  83. package/.bkit/core/engine/commands/workflow/counters.ts +21 -12
  84. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  85. package/.bkit/core/engine/commands/workflow/fids.ts +46 -0
  86. package/.bkit/core/engine/commands/workflow/issues.ts +73 -28
  87. package/.bkit/core/engine/commands/workflow/ledgers.ts +3 -1
  88. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  89. package/.bkit/core/engine/commands/workflow/prs.ts +15 -4
  90. package/.bkit/core/engine/commands/workflow/repo.ts +2 -2
  91. package/.bkit/core/engine/commands/workflow/roadmap.ts +49 -53
  92. package/.bkit/core/engine/commands/workflow/runs.ts +8 -7
  93. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  94. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  95. package/.bkit/core/engine/commands/workflow/steps.ts +25 -15
  96. package/.bkit/core/engine/commands/workflow/tests.ts +17 -5
  97. package/.bkit/core/engine/commands/workflow/workflows.ts +436 -267
  98. package/.bkit/core/engine/commands/workflow/workstreams.ts +4 -2
  99. package/.bkit/core/engine/commands/workflow/worktrees.ts +24 -6
  100. package/.bkit/core/engine/install/cloud-env.ts +10 -31
  101. package/.bkit/core/engine/install/manifest.ts +14 -7
  102. package/.bkit/core/engine/install/modules/antigravity.ts +15 -26
  103. package/.bkit/core/engine/install/modules/claude.ts +20 -28
  104. package/.bkit/core/engine/install/modules/cloud.ts +5 -2
  105. package/.bkit/core/engine/install/modules/codex.ts +15 -29
  106. package/.bkit/core/engine/install/modules/core.ts +106 -70
  107. package/.bkit/core/engine/install/modules/cursor.ts +6 -20
  108. package/.bkit/core/engine/install/modules/index.ts +7 -1
  109. package/.bkit/core/engine/install/modules/opencode.ts +48 -70
  110. package/.bkit/core/engine/install/network-allowlist.ts +73 -0
  111. package/.bkit/core/engine/install/placeholders.ts +16 -35
  112. package/.bkit/core/engine/install/write.ts +59 -12
  113. package/.bkit/core/engine/ledgers/telemetry.ts +6 -4
  114. package/.bkit/core/engine/render/hosts.ts +47 -67
  115. package/.bkit/core/engine/render/models.ts +29 -11
  116. package/.bkit/core/engine/shared/branches.ts +13 -0
  117. package/.bkit/core/engine/shared/egress.ts +3 -3
  118. package/.bkit/core/engine/shared/json.ts +18 -1
  119. package/.bkit/core/engine/shared/package-json.ts +63 -0
  120. package/.bkit/core/engine/shared/package-roots.ts +0 -10
  121. package/.bkit/core/engine/shared/protected-paths.ts +5 -130
  122. package/.bkit/core/engine/shared/settings.ts +44 -0
  123. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  124. package/.bkit/core/hooks/antigravity-hook.js +1 -0
  125. package/.bkit/core/hooks/guardrails-shell.js +186 -40
  126. package/.bkit/core/hooks/guardrails-tiers.js +5 -78
  127. package/.bkit/core/prompts/bkit-audit-generate.md +103 -7
  128. package/.bkit/core/prompts/bkit-build-challenge-1.md +1 -1
  129. package/.bkit/core/prompts/bkit-build-challenge-2.md +1 -1
  130. package/.bkit/core/prompts/bkit-build-challenge-reconcile.md +1 -1
  131. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  132. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  133. package/.bkit/core/prompts/bkit-build-install-skills.md +1 -1
  134. package/.bkit/core/prompts/bkit-build-plan-current.md +1 -1
  135. package/.bkit/core/prompts/bkit-build-plan-execute.md +4 -4
  136. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  137. package/.bkit/core/prompts/bkit-build-plan-verify.md +2 -2
  138. package/.bkit/core/prompts/bkit-debug-abort-handover.md +1 -1
  139. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +1 -1
  140. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  141. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +78 -0
  142. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  143. package/.bkit/core/prompts/bkit-debug-summary.md +3 -3
  144. package/.bkit/core/prompts/bkit-design-spike.md +1 -1
  145. package/.bkit/core/prompts/bkit-design-summary.md +2 -2
  146. package/.bkit/core/prompts/bkit-design-update.md +1 -1
  147. package/.bkit/core/prompts/bkit-plan-complexity-check.md +1 -1
  148. package/.bkit/core/prompts/bkit-plan-generate.md +1 -1
  149. package/.bkit/core/prompts/bkit-plan-scope-check-1.md +1 -1
  150. package/.bkit/core/prompts/bkit-plan-scope-check-2.md +1 -1
  151. package/.bkit/core/prompts/bkit-plan-summary.md +1 -1
  152. package/.bkit/core/prompts/bkit-plan-update.md +1 -1
  153. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  154. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +1 -1
  155. package/.bkit/core/prompts/bkit-ship-update-docs.md +1 -1
  156. package/.bkit/core/prompts/bkit-utility-update-decisions.md +9 -2
  157. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +9 -2
  158. package/.bkit/core/prompts/bkit-utility-update-documentation.md +2 -1
  159. package/.bkit/core/prompts/bkit-utility-update-failures.md +9 -2
  160. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +9 -2
  161. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +11 -4
  162. package/.bkit/core/workflows/bkit-auto.md +2 -2
  163. package/.bkit/core/workflows/bkit-build.md +10 -10
  164. package/.bkit/core/workflows/bkit-debug.md +80 -44
  165. package/.bkit/core/workflows/bkit-design.md +22 -13
  166. package/.bkit/core/workflows/bkit-plan.md +33 -16
  167. package/.bkit/core/workflows/bkit-ship.md +87 -98
  168. package/.bkit/shared/.claude/bkit-cloud.md +58 -25
  169. package/.bkit/shared/.claude/settings.json +19 -0
  170. package/.bkit/shared/.cursor/mcp.json +2 -1
  171. package/.bkit/shared/.opencode/opencode.json +19 -1
  172. package/.bkit/shared/docs/deployments.md +49 -29
  173. package/.bkit/shared/docs/security.md +8 -6
  174. package/.bkit/shared/docs/testing.md +9 -5
  175. package/.bkit/shared/gitignore +1 -2
  176. package/.bkit/templates/.cursor/Dockerfile +30 -16
  177. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +78 -0
  178. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +91 -0
  179. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +56 -0
  180. package/.bkit/templates/.github/renovate.json5 +91 -12
  181. package/.bkit/templates/.github/workflows/bkit-ci.yml +73 -55
  182. package/.bkit/templates/.github/workflows/bkit-cloud.yml +3 -1
  183. package/.bkit/templates/.github/workflows/bkit-renovate.yml +8 -1
  184. package/.bkit/templates/.github/workflows/bkit-trivy.yml +67 -0
  185. package/.bkit/templates/.husky/pre-commit +6 -0
  186. package/.bkit/templates/.husky/pre-push +15 -3
  187. package/.bkit/templates/.lintstagedrc.json +5 -1
  188. package/.bkit/templates/.oxlintrc.json +21 -0
  189. package/.bkit/templates/docs/capabilities.md +1 -1
  190. package/.bkit/templates/scripts/ci/check-capstone.mjs +176 -0
  191. package/.bkit/templates/scripts/ci/check-capstone.test.mjs +311 -0
  192. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  193. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  194. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +2 -2
  195. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +43 -20
  196. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +33 -11
  197. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -2
  198. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +5 -5
  199. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +79 -19
  200. package/CHANGELOG.md +98 -3
  201. package/README.md +252 -122
  202. package/dist/checks/after/auth.js +10 -11
  203. package/dist/checks/after/ci-yml.js +11 -14
  204. package/dist/checks/after/github.js +32 -125
  205. package/dist/checks/after/index.js +3 -2
  206. package/dist/checks/after/managed.js +8 -24
  207. package/dist/checks/after/tools.js +3 -16
  208. package/dist/checks/before/context-fetch.js +1 -21
  209. package/dist/checks/before/index.js +6 -42
  210. package/dist/checks/before/mcp.js +14 -9
  211. package/dist/checks/before/repo.js +8 -11
  212. package/dist/checks/status-holes.js +5 -7
  213. package/dist/checks/tips/catalogue.js +65 -18
  214. package/dist/checks/tips/detect.js +41 -2
  215. package/dist/checks/tips/index.js +61 -25
  216. package/dist/cli.js +52 -26
  217. package/dist/commands/analysis.js +21 -5
  218. package/dist/commands/comply.js +40 -31
  219. package/dist/commands/harvest.js +12 -13
  220. package/dist/commands/install/doctor.js +55 -23
  221. package/dist/commands/install/install.js +72 -122
  222. package/dist/commands/install/uninstall.js +165 -31
  223. package/dist/commands/install/upgrade.js +46 -39
  224. package/dist/commands/land.js +129 -0
  225. package/dist/commands/lib.js +41 -16
  226. package/dist/commands/registry.js +2 -0
  227. package/dist/commands/tips.js +10 -3
  228. package/dist/commands/workflow/branches.js +303 -248
  229. package/dist/commands/workflow/counters.js +17 -7
  230. package/dist/commands/workflow/disk.js +452 -0
  231. package/dist/commands/workflow/fids.js +39 -0
  232. package/dist/commands/workflow/issues.js +63 -27
  233. package/dist/commands/workflow/ledgers.js +3 -1
  234. package/dist/commands/workflow/locks.js +35 -130
  235. package/dist/commands/workflow/prs.js +8 -5
  236. package/dist/commands/workflow/repo.js +2 -2
  237. package/dist/commands/workflow/roadmap.js +50 -57
  238. package/dist/commands/workflow/runs.js +5 -5
  239. package/dist/commands/workflow/runtime.js +3 -2
  240. package/dist/commands/workflow/status.js +32 -12
  241. package/dist/commands/workflow/steps.js +19 -11
  242. package/dist/commands/workflow/tests.js +16 -3
  243. package/dist/commands/workflow/workflows.js +390 -249
  244. package/dist/commands/workflow/workstreams.js +4 -2
  245. package/dist/commands/workflow/worktrees.js +15 -6
  246. package/dist/install/cloud-env.js +10 -23
  247. package/dist/install/manifest.js +14 -7
  248. package/dist/install/modules/antigravity.js +15 -26
  249. package/dist/install/modules/claude.js +17 -21
  250. package/dist/install/modules/cloud.js +6 -2
  251. package/dist/install/modules/codex.js +15 -29
  252. package/dist/install/modules/core.js +95 -63
  253. package/dist/install/modules/cursor.js +6 -9
  254. package/dist/install/modules/index.js +6 -1
  255. package/dist/install/modules/opencode.js +41 -72
  256. package/dist/install/network-allowlist.js +62 -0
  257. package/dist/install/placeholders.js +16 -35
  258. package/dist/install/write.js +55 -15
  259. package/dist/ledgers/telemetry.js +5 -4
  260. package/dist/render/hosts.js +30 -55
  261. package/dist/render/models.js +20 -9
  262. package/dist/shared/branches.js +11 -0
  263. package/dist/shared/egress.js +0 -2
  264. package/dist/shared/json.js +14 -0
  265. package/dist/shared/package-json.js +61 -0
  266. package/dist/shared/package-roots.js +0 -8
  267. package/dist/shared/protected-paths.js +5 -122
  268. package/dist/shared/settings.js +23 -1
  269. package/dist/shared/timeouts.js +8 -7
  270. package/package.json +21 -17
  271. package/.bkit/core/.agents/shortcuts.md +0 -73
@@ -12,8 +12,8 @@
12
12
  // ship's one-commit flush (`--flush`), and print the handover comment.
13
13
  // close grade compliance, then the `workflow-done` row, the run's counter and
14
14
  // outcome rows in `.bkit/stats.jsonl`, this workflow's telemetry report
15
- // and the artifact links. `--flush` is ship's close: under the dev lock,
16
- // on dev or a detached origin/dev worktree, commit and land it.
15
+ // and the artifact links. `--flush` is ship's close: land it on dev
16
+ // through a throwaway origin/dev checkout, then remove the worktree.
17
17
  // promote design / plan close: the highest versioned draft becomes the
18
18
  // canonical doc (anchor stamped, a superseded canonical archived).
19
19
  // links the feature docs and this workflow's logs on a ref, as markdown links.
@@ -22,23 +22,22 @@ import * as path from "node:path";
22
22
  import { appendLine, fold, runNumber, runOrStepField, statusTimestamp, } from "../../ledgers/status.js";
23
23
  import { appendLine as telemetryLine, foldFrom, resolveRepoSlug, validate, workflowTelemetry, } from "../../ledgers/telemetry.js";
24
24
  import { readBkitVersion } from "../../install/version-file.js";
25
- import { TIMEOUTS } from "../../shared/timeouts.js";
26
25
  import { gradeCompliance } from "../comply.js";
27
- import { CommandError, EXIT, git, parseJson, repoRoot, runGh, runGit, statusLocation, statusRelPath, } from "../lib.js";
26
+ import { landDir, pushToDev } from "../land.js";
27
+ import { CommandError, DEV, EXIT, git, isSharedBranch, parseJson, repoRoot, runGh, runGit, statusLocation, statusRelPath, } from "../lib.js";
28
28
  import { anchorBkitStatus, pushBranch, readAnchor, stampAnchor } from "./branches.js";
29
29
  import { AUTO_LABEL, AUTO_ROUTE_SUFFIX, buildComment, linearState, transitionLabels, } from "./issues.js";
30
30
  import { EXIT_EMPTY, commitBookkeeping, unionLedgers } from "./ledgers.js";
31
- import { EXIT_REMOVE_FAILED, EXIT_SPLIT_BUCKET, acquireDevLock, acquireWorkflowLock, lockRoot, owns, readHolder, releaseLock, resolveMonth, workflowLockPath, } from "./locks.js";
31
+ import { EXIT_REMOVE_FAILED, EXIT_SPLIT_BUCKET, acquireWorkflowLock, owns, readHolder, releaseLock, resolveMonth, workflowLockPath, } from "./locks.js";
32
32
  import { mergePr, probePr } from "./prs.js";
33
33
  import { FEATURE_STATUS } from "./roadmap.js";
34
34
  import { EXIT_NO_STATUS, WORKFLOW_FLAG, positiveInt, readRuns, readStatusEvents, readStatusRows, str, } from "./status.js";
35
35
  import { writeStepRow } from "./steps.js";
36
+ import { removeWorktree } from "./worktrees.js";
36
37
  /** Sentinels a workflow leaves in its logs folder; either one existing means a handover is due. */
37
38
  export const SENTINELS = [".rebase-failed", ".deferred-blocked"];
38
39
  /** Exit code (start --lock-held): the lock is missing or belongs to another owner. */
39
40
  export const EXIT_LOCK_NOT_HELD = 6;
40
- /** Exit code (handover --push): the handover artifact is missing or empty. */
41
- export const EXIT_HANDOVER_MISSING = 8;
42
41
  /** Exit code (handover --push): the branch has an open PR, so nothing was pushed. */
43
42
  export const EXIT_OPEN_PR_KEPT = 9;
44
43
  /** Exit code (handover, close --flush): a push failed. */
@@ -52,16 +51,11 @@ function workflowName(workflow) {
52
51
  throw new CommandError(EXIT.USAGE, `--workflow must be ${Object.keys(FEATURE_STATUS).join(", ")}`);
53
52
  return workflow;
54
53
  }
55
- /**
56
- * start and close work in the current tree (ship: its book root), the root
57
- * `git rev-parse --show-toplevel` reports.
58
- */
54
+ /** start and close work in the current tree, the root `git rev-parse --show-toplevel` reports. */
59
55
  function whereInTree(cwd, o) {
60
56
  const root = repoRoot(cwd);
61
57
  const month = resolveMonth(root, o.fid, o.month);
62
- const tree = o.workflow === "ship"
63
- ? lockRoot(cwd, o.workflow, o.devPushes)
64
- : (git(cwd, ["rev-parse", "--show-toplevel"]) ?? root);
58
+ const tree = git(cwd, ["rev-parse", "--show-toplevel"]) ?? root;
65
59
  const status = o.file ? path.resolve(cwd, o.file) : path.join(tree, statusRelPath(month, o.fid));
66
60
  return { root, month, tree, status };
67
61
  }
@@ -99,13 +93,12 @@ function abortRebase(tree, log) {
99
93
  }
100
94
  /** The workflow-failed state: row, rebase abort, lock release, sentinels. */
101
95
  function failState(ctx, workflow, fid) {
102
- const devPushes = ctx.flags.devPushes === true;
103
96
  const root = repoRoot(ctx.cwd);
104
97
  const month = resolveMonth(root, fid, str(ctx.flags.month) || undefined);
105
98
  const file = str(ctx.flags.file) || undefined;
106
99
  const status = file
107
100
  ? path.resolve(ctx.cwd, file)
108
- : statusLocation({ cwd: ctx.cwd, workflow, fid, month, devPushes }).path;
101
+ : statusLocation({ cwd: ctx.cwd, workflow, fid, month }).path;
109
102
  // The run's own tree: the feature worktree when there is one, else this checkout.
110
103
  // Never the main checkout behind a worktree, where a rebase would be a human's.
111
104
  const worktree = path.join(root, ".worktrees", fid);
@@ -126,7 +119,7 @@ function failState(ctx, workflow, fid) {
126
119
  else {
127
120
  ctx.log(`${status} does not exist — no workflow-failed row written`);
128
121
  }
129
- const lockFile = workflowLockPath(lockRoot(ctx.cwd, workflow, devPushes), month, fid);
122
+ const lockFile = workflowLockPath(root, month, fid);
130
123
  const { removeFailed, ...lock } = releaseLock(lockFile, {
131
124
  workflow,
132
125
  fid,
@@ -137,7 +130,7 @@ function failState(ctx, workflow, fid) {
137
130
  if (removeFailed)
138
131
  ctx.log(`lock removal failed: ${lockFile}`);
139
132
  // Each sentinel is cleared where it was created: `.rebase-failed` in the run's
140
- // tree, `.deferred-blocked` beside status.jsonl (ship: the book root).
133
+ // tree, `.deferred-blocked` beside status.jsonl.
141
134
  const logDirs = new Set([path.join(tree, logDirRel(month, fid)), path.dirname(status)]);
142
135
  const sentinels = [];
143
136
  for (const dir of logDirs) {
@@ -221,97 +214,237 @@ function readText(cwd, rel) {
221
214
  // ---------------------------------------------------------------------------
222
215
  // handover
223
216
  // ---------------------------------------------------------------------------
217
+ /** Non-empty lines; a final newline ends the last line rather than starting an empty one. */
218
+ const textLines = (text) => text.split("\n").filter((l) => l.trim() !== "");
219
+ /** `rel` in `tree` differs from its HEAD copy, or is untracked: the run wrote it. */
220
+ const ownWrite = (tree, rel) => (git(tree, ["status", "--porcelain", "--untracked-files=all", "--", rel]) ?? "") !== "";
221
+ /** Copy each `.md` log in the run's log folder that dev lacks, or that the run rewrote. */
222
+ function carryLogs(src, dst, rel) {
223
+ if (!fs.existsSync(path.join(src, rel)))
224
+ return [];
225
+ fs.mkdirSync(path.join(dst, rel), { recursive: true });
226
+ const copied = [];
227
+ for (const f of fs.readdirSync(path.join(src, rel)).filter((n) => n.endsWith(".md"))) {
228
+ const from = path.join(src, rel, f);
229
+ const to = path.join(dst, rel, f);
230
+ const same = fs.existsSync(to) && fs.readFileSync(to).equals(fs.readFileSync(from));
231
+ if (same || (fs.existsSync(to) && !ownWrite(src, path.join(rel, f))))
232
+ continue;
233
+ fs.copyFileSync(from, to);
234
+ copied.push(path.join(rel, f));
235
+ }
236
+ return copied;
237
+ }
224
238
  /**
225
- * Ship's Failure Path flush: copy branch-side logs and ledger rows into the book
226
- * root, then ONE `chore({fid}): ship FAILED bkit [skip ci]` commit and ONE push —
227
- * to dev under the dev lock when this runtime pushes dev, else the current branch.
239
+ * Carry a run's book (its feature worktree) into a dev checkout: its `.md` logs,
240
+ * and its ledger rows unioned line-wise (both hold rows the other does not).
228
241
  */
229
- async function shipFlush(ctx, o) {
230
- const root = repoRoot(ctx.cwd);
231
- const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
232
- const bookRoot = o.devPushes ? root : top;
242
+ function carryBook(src, dst, month, fid) {
243
+ carryLogs(src, dst, logDirRel(month, fid));
244
+ unionLedgers(src, dst);
245
+ }
246
+ /** Shared ledgers a run may append to, outside its own log folder. */
247
+ const SHARED_LEDGERS = [
248
+ ":(glob)docs/*.jsonl",
249
+ ":(glob).bkit/*.jsonl",
250
+ ":(exclude).bkit/issues.jsonl",
251
+ ];
252
+ /**
253
+ * Carry ONLY the run's own record out of a dev / main / detached checkout, which
254
+ * other sessions and local-only commits share: the `.md` logs it wrote in its log
255
+ * folder; the lines of that folder's `.jsonl` files its HEAD lacks; and, from the
256
+ * shared ledgers, lines its HEAD lacks that are rows of `workflow` at or after
257
+ * the run's start (`startMs`). No start known → no shared-ledger row is carried.
258
+ */
259
+ function carryOwnBook(src, dst, o, log) {
233
260
  const rel = logDirRel(o.month, o.fid);
234
- const src = o.worktree ?? path.join(root, ".worktrees", o.fid);
235
- if (fs.existsSync(path.join(src, rel)) && path.resolve(src) !== path.resolve(bookRoot)) {
236
- fs.mkdirSync(path.join(bookRoot, rel), { recursive: true });
237
- for (const f of fs.readdirSync(path.join(src, rel)).filter((n) => n.endsWith(".md"))) {
238
- const to = path.join(bookRoot, rel, f);
239
- if (!fs.existsSync(to))
240
- fs.copyFileSync(path.join(src, rel, f), to);
241
- }
242
- unionLedgers(src, bookRoot);
243
- }
244
- let wt = bookRoot;
245
- let target = "";
246
- let release;
247
- if (o.devPushes) {
248
- let lock;
249
- try {
250
- lock = await acquireDevLock({
251
- cwd: root,
252
- workflow: "ship",
253
- fid: o.fid,
254
- deadlineS: 60,
255
- log: ctx.log,
256
- });
257
- }
258
- catch {
259
- // Busy: the FAILED record rides along on the next dev commit; never a second failure.
260
- ctx.log(`dev lock busy — ship FAILED bookkeeping left uncommitted in ${bookRoot}`);
261
- return { code: EXIT.OK, pushed: false, ref: null, skipped: "dev-lock-busy" };
262
- }
263
- release = () => releaseLock(lock.path, { workflow: "ship", fid: o.fid, token: lock.token });
264
- runGit(root, ["checkout", "dev"]);
265
- if (git(root, ["branch", "--show-current"]) !== "dev") {
266
- release();
267
- ctx.log(`not on dev after checkout — FAILED bookkeeping left uncommitted in ${bookRoot}`);
268
- return { code: EXIT_FLUSH_FAILED, pushed: false, ref: null, skipped: null };
269
- }
270
- runGit(root, ["pull", "--ff-only", "origin", "dev"]);
271
- wt = root;
272
- target = "dev";
261
+ const carried = { files: carryLogs(src, dst, rel), lines: new Map() };
262
+ const uncommitted = (file) => {
263
+ const head = new Set(textLines(git(src, ["show", `HEAD:${file}`]) ?? "").map((l) => l.trim()));
264
+ return textLines(fs.readFileSync(path.join(src, file), "utf-8")).filter((l) => !head.has(l.trim()));
265
+ };
266
+ const add = (file, lines) => {
267
+ const to = path.join(dst, file);
268
+ const existing = fs.existsSync(to) ? fs.readFileSync(to, "utf-8") : "";
269
+ const have = new Set(textLines(existing).map((l) => l.trim()));
270
+ const fresh = lines.filter((l) => !have.has(l.trim()));
271
+ if (fresh.length === 0)
272
+ return;
273
+ fs.mkdirSync(path.dirname(to), { recursive: true });
274
+ const sep = existing !== "" && !existing.endsWith("\n") ? "\n" : "";
275
+ fs.appendFileSync(to, `${sep}${fresh.join("\n")}\n`);
276
+ carried.lines.set(file, fresh);
277
+ };
278
+ const listed = (specs) => (git(src, ["ls-files", "--cached", "--others", "--exclude-standard", "--", ...specs]) ?? "")
279
+ .split("\n")
280
+ .filter((f) => f !== "" && fs.existsSync(path.join(src, f)));
281
+ for (const file of listed([`:(glob)${rel}/*.jsonl`]))
282
+ add(file, uncommitted(file));
283
+ if (o.startMs === undefined) {
284
+ log(`no ${o.workflow} start row for ${o.fid} — no shared-ledger row carried`);
285
+ return carried;
273
286
  }
274
- else {
275
- ctx.log("RUNTIME_DEVPUSHES=false — the FAILED record commits on the current branch");
276
- target = git(wt, ["branch", "--show-current"]) ?? "";
287
+ for (const file of listed(SHARED_LEDGERS)) {
288
+ const own = uncommitted(file).filter((l) => {
289
+ const parsed = parseJson(l);
290
+ const row = parsed.ok ? parsed.value : null;
291
+ return row?.workflow === o.workflow && Number(row.ts) >= o.startMs;
292
+ });
293
+ if (own.length > 0)
294
+ add(file, own);
277
295
  }
278
- try {
279
- if (target === "") {
280
- ctx.log(`push target empty (detached HEAD?) — bookkeeping left uncommitted in ${wt}`);
281
- return { code: EXIT_FLUSH_FAILED, pushed: false, ref: null, skipped: null };
296
+ return carried;
297
+ }
298
+ /**
299
+ * After a landing from a dev / main / detached checkout: hand back what was
300
+ * carried, so a later fast-forward of dev does not stop on it. A carried `.md`
301
+ * log identical to the landed copy is removed when untracked, or returns to HEAD
302
+ * when tracked. A carried ledger loses exactly the carried lines; it returns to
303
+ * HEAD when that leaves it equal, and an untracked one left empty is removed.
304
+ * Anything staged, or a log changed since it landed, stays and is named.
305
+ */
306
+ function handBack(tree, sha, carried, log) {
307
+ const back = [];
308
+ const kept = [];
309
+ const staged = (rel) => !runGit(tree, ["diff", "--cached", "--quiet", "--", rel]).ok;
310
+ const tracked = (rel) => runGit(tree, ["ls-files", "--error-unmatch", "--", rel]).ok;
311
+ for (const rel of carried.files) {
312
+ const abs = path.join(tree, rel);
313
+ const landed = runGit(tree, ["show", `${sha}:${rel}`]);
314
+ const same = landed.ok && fs.existsSync(abs) && fs.readFileSync(abs, "utf-8").trim() === landed.stdout;
315
+ if (!same || staged(rel))
316
+ kept.push(rel);
317
+ else if (!tracked(rel)) {
318
+ fs.rmSync(abs);
319
+ back.push(rel);
282
320
  }
283
- const before = headSha(wt);
284
- try {
285
- commitBookkeeping({
286
- root: wt,
287
- month: o.month,
288
- fid: o.fid,
289
- scope: "full",
290
- mode: "commit",
291
- message: `chore(${o.fid}): ship FAILED bkit [skip ci]`,
292
- }, ctx.log);
321
+ else if (runGit(tree, ["restore", "--source=HEAD", "--worktree", "--", rel]).ok)
322
+ back.push(rel);
323
+ else
324
+ kept.push(rel);
325
+ }
326
+ for (const [rel, lines] of carried.lines) {
327
+ const abs = path.join(tree, rel);
328
+ if (!fs.existsSync(abs) || staged(rel)) {
329
+ kept.push(rel);
330
+ continue;
293
331
  }
294
- catch (err) {
295
- if (err instanceof CommandError && err.code === EXIT_EMPTY) {
296
- ctx.log("no bookkeeping delta to record — nothing committed, nothing pushed");
297
- return { code: EXIT.OK, pushed: false, ref: null, skipped: "nothing-to-commit" };
332
+ const drop = new Map();
333
+ for (const l of lines)
334
+ drop.set(l.trim(), (drop.get(l.trim()) ?? 0) + 1);
335
+ const left = fs
336
+ .readFileSync(abs, "utf-8")
337
+ .split("\n")
338
+ .filter((l) => {
339
+ const n = drop.get(l.trim()) ?? 0;
340
+ if (n === 0)
341
+ return true;
342
+ drop.set(l.trim(), n - 1);
343
+ return false;
344
+ })
345
+ .join("\n");
346
+ const head = runGit(tree, ["show", `HEAD:${rel}`]);
347
+ if (head.ok && left.trim() === head.stdout.trim()) {
348
+ if (!runGit(tree, ["restore", "--source=HEAD", "--worktree", "--", rel]).ok) {
349
+ kept.push(rel);
350
+ continue;
298
351
  }
299
- ctx.log(`bookkeeping commit failed — FAILED bookkeeping left uncommitted in ${wt}: ${err.message}`);
300
- return { code: EXIT_FLUSH_FAILED, pushed: false, ref: null, skipped: null };
301
352
  }
302
- if (headSha(wt) === before) {
353
+ else if (!tracked(rel) && left.trim() === "")
354
+ fs.rmSync(abs);
355
+ else
356
+ fs.writeFileSync(abs, left.endsWith("\n") || left === "" ? left : `${left}\n`);
357
+ back.push(rel);
358
+ }
359
+ if (back.length > 0)
360
+ log(`handed back ${back.length} file(s) now on dev: ${back.join(", ")}`);
361
+ if (kept.length > 0)
362
+ log(`kept in ${tree}, not all on dev: ${kept.join(", ")}`);
363
+ }
364
+ /** Thrown by a landing's build when the book adds nothing to dev. */
365
+ const NOTHING_TO_LAND = new Error("no bookkeeping delta");
366
+ /**
367
+ * Land a failed run's record on dev: carry its book (the run's tree) into a
368
+ * throwaway origin/dev checkout, commit it as ONE
369
+ * `chore({fid}): {workflow} FAILED bkit [skip ci]` and push it. Ship's Failure
370
+ * Path always lands here; the other workflows land here only from a `dev` /
371
+ * `main` / detached checkout, where a commit in the checkout would publish code.
372
+ * `shared` (the book is such a checkout) → only the run's own record is carried
373
+ * (`carryOwnBook`), and `carried` says what, for the hand-back.
374
+ * Not landed → the record stays in the book, and the next run carries it.
375
+ */
376
+ async function landFailedRecord(ctx, o) {
377
+ const root = repoRoot(ctx.cwd);
378
+ const { book } = o;
379
+ const kept = `${o.workflow} FAILED record kept in ${book} — the next ${o.workflow} of ${o.fid} carries it`;
380
+ const stop = (code, why) => {
381
+ ctx.log(`${why} — ${kept}`);
382
+ return { code, pushed: false, ref: null, skipped: null };
383
+ };
384
+ // Read leniently: an unreadable row only leaves the run's start unknown.
385
+ const statusAbs = path.join(book, statusRelPath(o.month, o.fid));
386
+ const starts = (fs.existsSync(statusAbs) ? textLines(fs.readFileSync(statusAbs, "utf-8")) : [])
387
+ .map((l) => parseObject(l))
388
+ .filter((e) => e?.type === "workflow-started" && e.workflow === o.workflow)
389
+ .map((e) => Date.parse(String(e?.at)))
390
+ .filter((ms) => Number.isFinite(ms));
391
+ const startMs = starts.length > 0 ? Math.max(...starts) : NaN;
392
+ let carried;
393
+ let res;
394
+ try {
395
+ res = await pushToDev({
396
+ root,
397
+ dir: landDir(root, o.fid),
398
+ build: (dir) => {
399
+ if (o.shared)
400
+ carried = carryOwnBook(book, dir, {
401
+ month: o.month,
402
+ fid: o.fid,
403
+ workflow: o.workflow,
404
+ startMs: Number.isFinite(startMs) ? startMs : undefined,
405
+ }, ctx.log);
406
+ else
407
+ carryBook(book, dir, o.month, o.fid);
408
+ const before = headSha(dir);
409
+ try {
410
+ commitBookkeeping({
411
+ root: dir,
412
+ month: o.month,
413
+ fid: o.fid,
414
+ scope: "full",
415
+ mode: "commit",
416
+ message: `chore(${o.fid}): ${o.workflow} FAILED bkit [skip ci]`,
417
+ }, ctx.log);
418
+ }
419
+ catch (err) {
420
+ throw err instanceof CommandError && err.code === EXIT_EMPTY ? NOTHING_TO_LAND : err;
421
+ }
422
+ if (headSha(dir) === before)
423
+ throw NOTHING_TO_LAND;
424
+ },
425
+ log: ctx.log,
426
+ });
427
+ }
428
+ catch (err) {
429
+ if (err === NOTHING_TO_LAND) {
303
430
  ctx.log("no bookkeeping delta to record — nothing committed, nothing pushed");
304
431
  return { code: EXIT.OK, pushed: false, ref: null, skipped: "nothing-to-commit" };
305
432
  }
306
- const push = runGit(wt, ["push", "origin", target]);
307
- if (!push.ok) {
308
- ctx.log(`git push origin ${target} failed: ${push.stderr}`);
309
- return { code: EXIT_PUSH_FAILED, pushed: false, ref: null, skipped: null };
310
- }
311
- return { code: EXIT.OK, pushed: true, ref: target, skipped: null };
433
+ return stop(EXIT_FLUSH_FAILED, `bookkeeping commit failed: ${err.message}`);
312
434
  }
313
- finally {
314
- release?.();
435
+ switch (res.kind) {
436
+ case "landed":
437
+ return { code: EXIT.OK, pushed: true, ref: DEV, skipped: null, sha: res.sha, carried };
438
+ case "refused":
439
+ return stop(EXIT_PUSH_FAILED, `dev refused the push: ${res.stderr}`);
440
+ case "push-failed":
441
+ return stop(EXIT_PUSH_FAILED, `dev push failed without a server answer: ${res.stderr}`);
442
+ case "exhausted":
443
+ return stop(EXIT_PUSH_FAILED, `dev moved before each of ${res.attempts} pushes`);
444
+ case "fetch-failed":
445
+ return stop(EXIT_FLUSH_FAILED, `fetch of dev failed: ${res.stderr}`);
446
+ case "setup-failed":
447
+ return stop(EXIT_FLUSH_FAILED, `throwaway checkout failed: ${res.stderr}`);
315
448
  }
316
449
  }
317
450
  async function handoverVerb(ctx) {
@@ -333,20 +466,26 @@ async function handoverVerb(ctx) {
333
466
  let ref = str(ctx.flags.ref) ?? null;
334
467
  let pushed = false;
335
468
  let skipped = null;
336
- if (push) {
337
- if (!present) {
338
- ctx.log(`${artifact} is missing or empty — nothing to hand over`);
339
- return EXIT_HANDOVER_MISSING;
340
- }
341
- runGit(ctx.cwd, ["add", "-A"]);
342
- const made = runGit(ctx.cwd, [
343
- "commit",
344
- "-m",
345
- `docs(${fid}): ${workflow} aborted bkit [skip ci]`,
346
- ]);
469
+ const tree = worktree === undefined ? (git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? base) : base;
470
+ const branch = git(tree, ["branch", "--show-current"]) ?? "";
471
+ // A dev / main / detached checkout is shared: only the run's own record leaves it.
472
+ const shared = branch === "" || isSharedBranch(branch);
473
+ let handed;
474
+ if (push && shared) {
475
+ const r = await landFailedRecord(ctx, { workflow, fid, month, book: tree, shared });
476
+ if (r.sha !== undefined && r.carried !== undefined)
477
+ handed = { sha: r.sha, carried: r.carried };
478
+ code = r.code;
479
+ pushed = r.pushed;
480
+ ref = r.ref;
481
+ skipped = r.skipped;
482
+ }
483
+ else if (push) {
484
+ runGit(tree, ["add", "-A"]);
485
+ const made = runGit(tree, ["commit", "-m", `docs(${fid}): ${workflow} aborted bkit [skip ci]`]);
347
486
  if (!made.ok)
348
487
  ctx.log(`abort commit: ${made.stderr || made.stdout}`);
349
- const r = pushBranch(ctx.cwd, { mode: "abort", openPr: str(ctx.flags.openPr) }, ctx.log);
488
+ const r = pushBranch(tree, { mode: "abort", openPr: str(ctx.flags.openPr) }, ctx.log);
350
489
  if (r.code === EXIT.USE_MCP)
351
490
  return r.code;
352
491
  pushed = r.out.pushed;
@@ -360,12 +499,9 @@ async function handoverVerb(ctx) {
360
499
  : EXIT_PUSH_FAILED;
361
500
  }
362
501
  else if (flush) {
363
- const r = await shipFlush(ctx, {
364
- fid,
365
- month,
366
- devPushes: ctx.flags.devPushes === true,
367
- worktree: worktree === undefined ? undefined : base,
368
- });
502
+ const r = await landFailedRecord(ctx, { workflow, fid, month, book: tree, shared });
503
+ if (r.sha !== undefined && r.carried !== undefined)
504
+ handed = { sha: r.sha, carried: r.carried };
369
505
  code = r.code;
370
506
  pushed = r.pushed;
371
507
  ref = r.ref;
@@ -381,6 +517,8 @@ async function handoverVerb(ctx) {
381
517
  bodyFile: artifact,
382
518
  })
383
519
  : null;
520
+ if (handed !== undefined)
521
+ handBack(tree, handed.sha, handed.carried, ctx.log);
384
522
  ctx.emit({
385
523
  handover: present ? artifact : null,
386
524
  pushed,
@@ -550,7 +688,7 @@ export function closeWorkflow(cwd, o, log) {
550
688
  if (o.squashSha !== undefined && !/^[0-9a-f]{7,40}$/.test(o.squashSha))
551
689
  throw new CommandError(EXIT.USAGE, `--squash-sha "${o.squashSha}" is not a commit sha`);
552
690
  // Graded first, so the report below carries this run's grade.
553
- const violations = gradeCompliance(where.tree, workflow, log);
691
+ const violations = gradeCompliance(where.tree, workflow, log, o.squashSha);
554
692
  const step = `${workflow}-close-workflow`;
555
693
  if (o.recordStep === true) {
556
694
  writeStepRow(where.tree, { file: where.status, workflow, step, artifacts: [], commit: "none" }, log);
@@ -615,7 +753,7 @@ export function closeWorkflow(cwd, o, log) {
615
753
  : ["[bkit-telemetry] stats.jsonl not found — no telemetry rows yet"];
616
754
  const ref = o.ref ??
617
755
  (["design", "plan", "ship"].includes(workflow)
618
- ? "dev"
756
+ ? DEV
619
757
  : (git(cwd, ["branch", "--show-current"]) ?? "HEAD"));
620
758
  const artifacts = artifactLinks(where.root, ref, where.month, o.fid, workflow, o.ownerRepo ?? repo);
621
759
  let comment = null;
@@ -669,124 +807,136 @@ export function closeWorkflow(cwd, o, log) {
669
807
  };
670
808
  }
671
809
  /**
672
- * Ship's close: under the dev lock, on dev (this runtime pushes it) or on a
673
- * detached `origin/dev` worktree in the outbox (it does not), run the close, commit
674
- * `docs({fid}): ship DONE bkit [skip ci]`, release the workflow lock, then land the
675
- * commit — push dev, push `HEAD:dev`, or, when that is refused, a `ship-close/{fid}`
676
- * PR merged with an empty body.
810
+ * Publish a close commit dev refused through its own `ship-close/{fid}` PR,
811
+ * merged with an empty body. Returns where it landed, or why it did not.
812
+ */
813
+ function closePr(ctx, dir, fid, subject) {
814
+ const branch = `ship-close/${fid}`;
815
+ const head = headSha(dir);
816
+ if (!runGit(dir, ["push", "origin", `HEAD:refs/heads/${branch}`]).ok)
817
+ return { failed: `close branch push failed` };
818
+ const created = runGh(dir, [
819
+ "pr",
820
+ "create",
821
+ "--base",
822
+ DEV,
823
+ "--head",
824
+ branch,
825
+ "--title",
826
+ `docs(${fid}): ship DONE`,
827
+ "--body",
828
+ "",
829
+ ]);
830
+ if (!created.ok)
831
+ return { failed: `gh pr create failed: ${created.stderr}` };
832
+ const pr = probePr(dir, { head: branch, base: DEV, state: "open" });
833
+ const number = pr.kind === "ok" ? pr.pr?.number : undefined;
834
+ if (number === undefined)
835
+ return { failed: `close PR not found for ${branch}` };
836
+ const merged = mergePr(dir, { number: String(number), subject, matchHead: head, deleteBranch: true }, ctx.log);
837
+ if (!merged.out.merged)
838
+ ctx.log(`close PR #${number} opened but not merged — merge it by hand`);
839
+ return { ref: branch, via: merged.out.merged ? "close-pr" : "close-pr-open" };
840
+ }
841
+ /**
842
+ * Ship's close, in the run's tree (the feature worktree, or the adopted
843
+ * checkout): the close rows there, then ONE `docs({fid}): ship DONE bkit [skip ci]`
844
+ * commit built in a throwaway origin/dev checkout carrying the run's book and
845
+ * landed on dev — a refused push publishes it through a `ship-close/{fid}` PR.
846
+ * Only a close that landed (or opened its PR) releases the workflow lock; once
847
+ * the close is on dev, the feature worktree and `branch` are removed. A close
848
+ * that did not land keeps the lock for the Failure Path.
677
849
  */
678
850
  async function shipClose(ctx, o, token) {
679
851
  const root = repoRoot(ctx.cwd);
680
- const outbox = o.outbox === undefined ? undefined : path.resolve(ctx.cwd, o.outbox);
681
- if (outbox === undefined)
852
+ if (o.outbox === undefined)
682
853
  throw new CommandError(EXIT.USAGE, "--flush needs --outbox");
683
854
  const month = resolveMonth(root, o.fid, o.month);
684
- const lock = await acquireDevLock({
685
- cwd: root,
686
- workflow: "ship",
687
- fid: o.fid,
688
- deadlineS: TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S,
689
- log: ctx.log,
690
- });
691
- const fail = (why) => {
692
- ctx.log(why);
855
+ const book = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
856
+ const subject = `docs(${o.fid}): ship DONE bkit [skip ci]`;
857
+ const kept = `close bookkeeping kept in ${book}`;
858
+ const out = closeWorkflow(book, { ...o, recordStep: true, message: undefined }, ctx.log);
859
+ let viaPr = null;
860
+ let res;
861
+ try {
862
+ res = await pushToDev({
863
+ root,
864
+ dir: landDir(root, o.fid),
865
+ build: (dir) => {
866
+ carryBook(book, dir, month, o.fid);
867
+ commitBookkeeping({
868
+ root: dir,
869
+ month,
870
+ fid: o.fid,
871
+ scope: "full",
872
+ mode: "commit-allow-empty",
873
+ message: subject,
874
+ }, ctx.log);
875
+ },
876
+ refused: async (dir, stderr) => {
877
+ ctx.log(`dev refused the close push — publishing it through a PR: ${stderr}`);
878
+ viaPr = closePr(ctx, dir, o.fid, subject);
879
+ },
880
+ log: ctx.log,
881
+ });
882
+ }
883
+ catch (err) {
884
+ ctx.log(`close commit failed: ${err.message} — ${kept}`);
693
885
  return { code: EXIT_FLUSH_FAILED, out: null };
694
- };
695
- let closeRoot = "";
886
+ }
887
+ // A close that did not land keeps the lock: the Failure Path releases it.
696
888
  let landed = null;
697
- let out = {};
698
- try {
699
- let wt;
700
- if (o.devPushes) {
701
- runGit(root, ["checkout", "dev"]);
702
- if (git(root, ["branch", "--show-current"]) !== "dev")
703
- return fail("not on dev after checkout — aborting dev ops");
704
- wt = root;
705
- }
706
- else {
707
- ctx.log("RUNTIME_DEVPUSHES=false — the close commit lands through a detached origin/dev worktree");
708
- wt = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
709
- }
710
- out = closeWorkflow(wt, { ...o, recordStep: true, message: undefined }, ctx.log);
711
- if (o.devPushes) {
712
- closeRoot = wt;
713
- }
714
- else {
715
- if (!runGit(wt, ["fetch", "origin", "dev"]).ok)
716
- return fail(`fetch origin dev failed — close bookkeeping left uncommitted in ${wt}`);
717
- closeRoot = path.join(outbox, "close");
718
- if (fs.existsSync(closeRoot))
719
- runGit(wt, ["worktree", "remove", "--force", closeRoot]);
720
- runGit(wt, ["worktree", "prune"]);
721
- if (!runGit(wt, ["worktree", "add", "--detach", closeRoot, "origin/dev"]).ok)
722
- return fail(`close worktree add failed — close bookkeeping left uncommitted in ${wt}`);
723
- unionLedgers(wt, closeRoot);
724
- }
725
- commitBookkeeping({
726
- root: closeRoot,
727
- month,
728
- fid: o.fid,
729
- scope: "full",
730
- mode: "commit-allow-empty",
731
- message: `docs(${o.fid}): ship DONE bkit [skip ci]`,
732
- }, ctx.log);
733
- const released = releaseLock(workflowLockPath(lockRoot(ctx.cwd, "ship", o.devPushes), month, o.fid), { workflow: "ship", fid: o.fid, token });
734
- if (released.removeFailed)
735
- return fail("Lock removal failed");
736
- if (o.devPushes) {
737
- if (!runGit(closeRoot, ["push", "origin", "dev"]).ok) {
738
- ctx.log("dev push failed");
739
- return { code: EXIT_PUSH_FAILED, out };
889
+ switch (res.kind) {
890
+ case "landed":
891
+ landed = { ref: DEV, via: "head-push" };
892
+ break;
893
+ case "refused": {
894
+ const pr = viaPr;
895
+ if (pr === null || "failed" in pr) {
896
+ ctx.log(`${pr === null ? "close PR not attempted" : pr.failed} — ${kept}`);
897
+ return { code: EXIT_FLUSH_FAILED, out: null };
740
898
  }
741
- landed = { ref: "dev", via: "dev-push" };
899
+ landed = pr;
900
+ break;
742
901
  }
902
+ case "push-failed":
903
+ ctx.log(`dev push failed without a server answer: ${res.stderr} — ${kept}`);
904
+ return { code: EXIT_PUSH_FAILED, out };
905
+ case "exhausted":
906
+ ctx.log(`dev moved before each of ${res.attempts} pushes — ${kept}`);
907
+ return { code: EXIT_PUSH_FAILED, out };
908
+ case "fetch-failed":
909
+ ctx.log(`fetch of dev failed: ${res.stderr} — ${kept}`);
910
+ return { code: EXIT_FLUSH_FAILED, out: null };
911
+ case "setup-failed":
912
+ ctx.log(`throwaway checkout failed: ${res.stderr} — ${kept}`);
913
+ return { code: EXIT_FLUSH_FAILED, out: null };
743
914
  }
744
- finally {
745
- releaseLock(lock.path, { workflow: "ship", fid: o.fid, token: lock.token });
915
+ const released = releaseLock(workflowLockPath(root, month, o.fid), {
916
+ workflow: "ship",
917
+ fid: o.fid,
918
+ token,
919
+ });
920
+ if (released.removeFailed) {
921
+ ctx.log("Lock removal failed");
922
+ return { code: EXIT_FLUSH_FAILED, out: null };
923
+ }
924
+ // The book is on dev only once the close landed or its PR merged.
925
+ let worktree = null;
926
+ if (landed.via === "close-pr-open") {
927
+ ctx.log(`close PR not merged — ${kept} until it is`);
746
928
  }
747
- if (!o.devPushes) {
748
- if (runGit(closeRoot, ["push", "origin", "HEAD:dev"]).ok) {
749
- landed = { ref: "dev", via: "head-push" };
929
+ else {
930
+ if (landed.via === "close-pr" && !runGit(root, ["fetch", "origin", DEV]).ok)
931
+ ctx.log(`fetch of dev after the close PR failed — origin/${DEV} is stale until the next fetch`);
932
+ try {
933
+ worktree = removeWorktree(root, o.fid, o.branch, ctx.log);
750
934
  }
751
- else {
752
- // dev refused the push: publish the close commit through its own PR.
753
- const branch = `ship-close/${o.fid}`;
754
- const head = headSha(closeRoot);
755
- if (!runGit(closeRoot, ["push", "origin", `HEAD:refs/heads/${branch}`]).ok)
756
- return fail(`close branch push failed — close bookkeeping left in ${closeRoot}`);
757
- const created = runGh(closeRoot, [
758
- "pr",
759
- "create",
760
- "--base",
761
- "dev",
762
- "--head",
763
- branch,
764
- "--title",
765
- `docs(${o.fid}): ship DONE`,
766
- "--body",
767
- "",
768
- ]);
769
- if (!created.ok)
770
- return fail(`gh pr create failed: ${created.stderr}`);
771
- const pr = probePr(closeRoot, { head: branch, base: "dev", state: "open" });
772
- const number = pr.kind === "ok" ? pr.pr?.number : undefined;
773
- if (number === undefined)
774
- return fail(`close PR not found for ${branch}`);
775
- const merged = mergePr(closeRoot, {
776
- number: String(number),
777
- subject: `docs(${o.fid}): ship DONE bkit [skip ci]`,
778
- matchHead: head,
779
- deleteBranch: true,
780
- }, ctx.log);
781
- if (!merged.out.merged)
782
- ctx.log(`close PR #${number} opened but not merged — merge it by hand`);
783
- landed = { ref: branch, via: merged.out.merged ? "close-pr" : "close-pr-open" };
935
+ catch (err) {
936
+ ctx.log(`${err.message} — remove ${book} by hand`);
784
937
  }
785
- const top = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root;
786
- runGit(top, ["worktree", "remove", "--force", closeRoot]);
787
- runGit(top, ["worktree", "prune"]);
788
938
  }
789
- return { code: EXIT.OK, out: { ...out, closeRoot, landed } };
939
+ return { code: EXIT.OK, out: { ...out, landed, worktree } };
790
940
  }
791
941
  // ---------------------------------------------------------------------------
792
942
  // promote
@@ -917,11 +1067,6 @@ const MONTH_FLAG = {
917
1067
  type: "string",
918
1068
  help: "month bucket YYYYMM (default: the feature's bucket, else this UTC month)",
919
1069
  };
920
- const DEV_PUSHES_FLAG = {
921
- name: "dev-pushes",
922
- type: "boolean",
923
- help: "ship only: this runtime pushes to dev (logs book in the main checkout)",
924
- };
925
1070
  const STATUS_FILE_FLAG = {
926
1071
  name: "file",
927
1072
  type: "string",
@@ -951,7 +1096,6 @@ export const workflowsCommand = {
951
1096
  WORKFLOW_FLAG,
952
1097
  FID_FLAG,
953
1098
  MONTH_FLAG,
954
- DEV_PUSHES_FLAG,
955
1099
  STATUS_FILE_FLAG,
956
1100
  {
957
1101
  name: "lock-held",
@@ -975,7 +1119,6 @@ export const workflowsCommand = {
975
1119
  run: (ctx) => {
976
1120
  const workflow = workflowName(String(ctx.flags.workflow));
977
1121
  const fid = String(ctx.flags.fid);
978
- const devPushes = ctx.flags.devPushes === true;
979
1122
  const token = str(ctx.flags.token);
980
1123
  if (token !== undefined && ctx.flags.lockHeld !== true)
981
1124
  throw new CommandError(EXIT.USAGE, "--token applies with --lock-held only");
@@ -983,12 +1126,11 @@ export const workflowsCommand = {
983
1126
  workflow,
984
1127
  fid,
985
1128
  month: str(ctx.flags.month),
986
- devPushes,
987
1129
  file: str(ctx.flags.file),
988
1130
  });
989
1131
  let lock;
990
1132
  if (ctx.flags.lockHeld === true) {
991
- const file = workflowLockPath(lockRoot(ctx.cwd, workflow, devPushes), where.month, fid);
1133
+ const file = workflowLockPath(where.root, where.month, fid);
992
1134
  checkHeldLock(file, { workflow, fid, token });
993
1135
  lock = { path: file };
994
1136
  }
@@ -999,7 +1141,6 @@ export const workflowsCommand = {
999
1141
  workflow,
1000
1142
  fid,
1001
1143
  month: where.month,
1002
- devPushes,
1003
1144
  log: ctx.log,
1004
1145
  }),
1005
1146
  };
@@ -1036,7 +1177,6 @@ export const workflowsCommand = {
1036
1177
  WORKFLOW_FLAG,
1037
1178
  { ...FID_FLAG, required: false, help: "feature id (needed with --token)" },
1038
1179
  MONTH_FLAG,
1039
- DEV_PUSHES_FLAG,
1040
1180
  STATUS_FILE_FLAG,
1041
1181
  {
1042
1182
  ...TOKEN_FLAG,
@@ -1095,7 +1235,7 @@ export const workflowsCommand = {
1095
1235
  run: failVerb,
1096
1236
  },
1097
1237
  handover: {
1098
- summary: "After the handover subagent: commit and abort-push it (--push), or ship's one-commit flush (--flush); print the handover comment.",
1238
+ summary: "Keep a failed run's record: commit and push it on the feature branch, or land its logs and ledgers on dev (--push from dev / main, ship's --flush); print the handover comment.",
1099
1239
  flags: [
1100
1240
  WORKFLOW_FLAG,
1101
1241
  FID_FLAG,
@@ -1103,12 +1243,12 @@ export const workflowsCommand = {
1103
1243
  {
1104
1244
  name: "push",
1105
1245
  type: "boolean",
1106
- help: "git add -A, commit `docs({fid}): {workflow} aborted bkit [skip ci]`, push --mode=abort",
1246
+ help: "feature branch: git add -A, commit `docs({fid}): {workflow} aborted bkit [skip ci]`, push --mode=abort; dev / main / detached: lands like --flush, the checkout untouched",
1107
1247
  },
1108
1248
  {
1109
1249
  name: "flush",
1110
1250
  type: "boolean",
1111
- help: "ship: copy the worktree's logs and ledgers into the book root, ONE FAILED commit, ONE push",
1251
+ help: "ship: carry the run's logs and ledgers into a throwaway origin/dev checkout, ONE `chore({fid}): {workflow} FAILED bkit [skip ci]` commit, landed on dev",
1112
1252
  },
1113
1253
  {
1114
1254
  name: "open-pr",
@@ -1116,11 +1256,10 @@ export const workflowsCommand = {
1116
1256
  help: "--push: the open-PR answer from MCP (a number, or none) instead of asking gh",
1117
1257
  },
1118
1258
  { name: "ref", type: "string", help: "link the handover at this ref (no push / flush)" },
1119
- DEV_PUSHES_FLAG,
1120
1259
  {
1121
1260
  name: "worktree",
1122
1261
  type: "string",
1123
- help: "ship: the worktree holding the handover and the branch-side logs (default: cwd / .worktrees/{fid})",
1262
+ help: "the run's tree: holds the handover and the logs, and is where --push commits (default: cwd's checkout)",
1124
1263
  },
1125
1264
  OWNER_REPO_FLAG,
1126
1265
  ],
@@ -1128,15 +1267,14 @@ export const workflowsCommand = {
1128
1267
  handover: "the handover artifact, or null when absent",
1129
1268
  pushed: "the push (or flush push) ran and succeeded",
1130
1269
  ref: "where the handover now lives, or null when nothing was pushed",
1131
- skipped: "why nothing was pushed: open-pr | skip-ci | dev-lock-busy | nothing-to-commit (null otherwise)",
1270
+ skipped: "why nothing was pushed: open-pr | skip-ci | nothing-to-commit (null otherwise)",
1132
1271
  comment: "the handover comment body (null when there is no handover); links only when pushed",
1133
1272
  },
1134
1273
  exitCodes: {
1135
1274
  [EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
1136
- [EXIT_HANDOVER_MISSING]: "--push: the handover artifact is missing or empty (nothing committed)",
1137
1275
  [EXIT_OPEN_PR_KEPT]: "--push: the branch has an open PR, nothing pushed (the comment has no link)",
1138
- [EXIT_PUSH_FAILED]: "the push failed (the comment has no link)",
1139
- [EXIT_FLUSH_FAILED]: "--flush: not on dev after checkout, detached HEAD, or the FAILED commit failed",
1276
+ [EXIT_PUSH_FAILED]: "the push failed, or dev refused / kept moving under the FAILED landing (the comment has no link)",
1277
+ [EXIT_FLUSH_FAILED]: "the dev fetch, the throwaway checkout or the FAILED commit failed; the record stays in the run's tree",
1140
1278
  },
1141
1279
  run: handoverVerb,
1142
1280
  },
@@ -1146,7 +1284,6 @@ export const workflowsCommand = {
1146
1284
  WORKFLOW_FLAG,
1147
1285
  FID_FLAG,
1148
1286
  MONTH_FLAG,
1149
- DEV_PUSHES_FLAG,
1150
1287
  STATUS_FILE_FLAG,
1151
1288
  {
1152
1289
  name: "pr-number",
@@ -1195,9 +1332,14 @@ export const workflowsCommand = {
1195
1332
  {
1196
1333
  name: "flush",
1197
1334
  type: "boolean",
1198
- help: "ship: under the dev lock, close on dev (or a detached origin/dev worktree), commit `ship DONE`, release the lock (--token), push",
1335
+ help: "ship: commit `ship DONE` in a throwaway origin/dev checkout carrying the run's book, land it on dev (refused: a ship-close PR), release the lock (--token), remove the worktree",
1199
1336
  },
1200
1337
  { ...TOKEN_FLAG, help: "--flush: the workflow lock token to release" },
1338
+ {
1339
+ name: "branch",
1340
+ type: "string",
1341
+ help: "--flush: the shipped branch, deleted locally and on origin with the worktree once the close is on dev",
1342
+ },
1201
1343
  ],
1202
1344
  output: {
1203
1345
  row: "the appended workflow-done row",
@@ -1213,14 +1355,14 @@ export const workflowsCommand = {
1213
1355
  comment: "the close comment (--number with --outbox), else null",
1214
1356
  roadmapFoldNeeded: "always true: append the feature row and re-render the board (not run here)",
1215
1357
  featureStatus: "roadmap status this close moves the feature to",
1216
- closeRoot: "--flush: the checkout the close commit was made in",
1217
- landed: "--flush: {ref, via: dev-push | head-push | close-pr | close-pr-open}",
1358
+ landed: "--flush: {ref, via: head-push | close-pr | close-pr-open}",
1359
+ worktree: "--flush: the `bkit worktrees remove` result once the close is on dev; null while the close PR is unmerged or the removal failed",
1218
1360
  },
1219
1361
  exitCodes: {
1220
1362
  [EXIT_NO_STATUS]: "status.jsonl missing, unreadable, or not valid NDJSON (nothing written)",
1221
1363
  [EXIT_SPLIT_BUCKET]: "no --month and the feature has logs in more than one month bucket",
1222
- [EXIT_PUSH_FAILED]: "--flush: the dev push failed",
1223
- [EXIT_FLUSH_FAILED]: "--flush: not on dev after checkout, the dev fetch / close worktree failed, the lock stayed, or the close PR could not be opened",
1364
+ [EXIT_PUSH_FAILED]: "--flush: dev moved before every push, or the push failed without a server answer; the lock is kept",
1365
+ [EXIT_FLUSH_FAILED]: "--flush: the dev fetch, the throwaway checkout or the close commit failed, the close PR could not be opened (the lock is kept), or the lock could not be removed",
1224
1366
  },
1225
1367
  run: async (ctx) => {
1226
1368
  const f = ctx.flags;
@@ -1228,7 +1370,6 @@ export const workflowsCommand = {
1228
1370
  workflow: String(f.workflow),
1229
1371
  fid: String(f.fid),
1230
1372
  month: str(f.month),
1231
- devPushes: f.devPushes === true,
1232
1373
  file: str(f.file),
1233
1374
  prNumber: positiveInt(f.prNumber, "pr-number"),
1234
1375
  squashSha: str(f.squashSha),
@@ -1246,7 +1387,7 @@ export const workflowsCommand = {
1246
1387
  if (f.flush === true) {
1247
1388
  if (input.workflow !== "ship")
1248
1389
  throw new CommandError(EXIT.USAGE, "--flush is ship only");
1249
- const r = await shipClose(ctx, input, str(f.token));
1390
+ const r = await shipClose(ctx, { ...input, branch: str(f.branch) }, str(f.token));
1250
1391
  if (r.out)
1251
1392
  ctx.emit(r.out);
1252
1393
  return r.code;
@@ -1317,7 +1458,7 @@ export const workflowsCommand = {
1317
1458
  const fid = String(ctx.flags.fid);
1318
1459
  const root = repoRoot(ctx.cwd);
1319
1460
  const month = resolveMonth(root, fid, str(ctx.flags.month));
1320
- const artifacts = artifactLinks(root, str(ctx.flags.ref) ?? "dev", month, fid, workflow, str(ctx.flags.ownerRepo) ?? (resolveRepoSlug(root) || "unknown/repo"));
1461
+ const artifacts = artifactLinks(root, str(ctx.flags.ref) ?? DEV, month, fid, workflow, str(ctx.flags.ownerRepo) ?? (resolveRepoSlug(root) || "unknown/repo"));
1321
1462
  let comment = null;
1322
1463
  const outbox = str(ctx.flags.outbox);
1323
1464
  if (outbox !== undefined) {