@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
@@ -14,22 +14,21 @@ import * as fs from "node:fs";
14
14
  import * as os from "node:os";
15
15
  import * as path from "node:path";
16
16
  import { gitEnv } from "../../ledgers/telemetry.js";
17
- import { bodySkipToken, CommandError, EXIT, git, parseJson, repoRoot, runGit, SKIP_CI_TOKEN, } from "../lib.js";
17
+ import { bodySkipToken, CommandError, DEV, EXIT, git, isSharedBranch, parseJson, repoRoot, runGit, SKIP_CI_TOKEN, } from "../lib.js";
18
18
  import { bkitVersionStatus } from "../../shared/bkit-latest.js";
19
+ import { landBackoffMs, landDir, pushToDev, sleep } from "../land.js";
19
20
  import { TIMEOUTS } from "../../shared/timeouts.js";
20
21
  import { commitBookkeeping } from "./ledgers.js";
21
- import { acquireDevLock, lockRoot, releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
22
- import { closeTransportRow, crossCheckFile, mergePr, openPrFor, probePr } from "./prs.js";
22
+ import { releaseLock, resolveMonth, workflowLockPath } from "./locks.js";
23
+ import { closeTransportRow, crossCheckRows, mergePr, openPrFor, probePr, updateBranch, } from "./prs.js";
23
24
  import { appendFeature } from "./roadmap.js";
24
25
  import { detect } from "./runtime.js";
25
- import { readStatusRows } from "./status.js";
26
- import { removeWorktree } from "./worktrees.js";
26
+ import { readStatusRows, readStatusRowsAt } from "./status.js";
27
+ import { removeWorktree, worktreeDir } from "./worktrees.js";
27
28
  import { COULD_NOT_RUN_EXIT_CODES, LOCKFILE_REGENERATE, installCommand, } from "../../shared/package-manager.js";
28
29
  import { str } from "./status.js";
29
30
  const REMOTE = "origin";
30
- const DEV = "dev";
31
31
  const UPSTREAM = `${REMOTE}/${DEV}`;
32
- const SHARED_BRANCHES = new Set([DEV, "main"]);
33
32
  /** Exit codes, distinct across verbs so a code means one thing anywhere in this noun. */
34
33
  export const EXIT_REFUSED = 3;
35
34
  export const EXIT_NO_REBASE = 4;
@@ -42,8 +41,6 @@ export const EXIT_FETCH_FAILED = 10;
42
41
  export const EXIT_MERGE_CONFLICT = 11;
43
42
  export const EXIT_ANCHOR_SKIP = 12;
44
43
  export const EXIT_NO_FILE = 13;
45
- export const EXIT_PULL_FAILED = 14;
46
- export const EXIT_RUNTIME_REFUSED = 15;
47
44
  export const EXIT_INSTALL_FAILED = 16;
48
45
  export const EXIT_LAND_STOPPED = 17;
49
46
  export const EXIT_LANDED_UNVERIFIED = 18;
@@ -83,13 +80,6 @@ function rebaseInProgress(top) {
83
80
  });
84
81
  }
85
82
  const currentBranch = (cwd) => git(cwd, ["branch", "--show-current"]) ?? "";
86
- const boolString = (v, flag) => {
87
- if (v === "true")
88
- return true;
89
- if (v === "false")
90
- return false;
91
- throw new CommandError(EXIT.USAGE, `--${flag} must be true or false, got "${String(v)}"`);
92
- };
93
83
  // ---------------------------------------------------------------------------
94
84
  // Conflict classification and resolution (rebase, and sync's docs merge)
95
85
  // ---------------------------------------------------------------------------
@@ -477,7 +467,7 @@ export function pushBranch(cwd, o, log) {
477
467
  return notPushed(EXIT_SKIP_CI, { skipped: "skip-ci" });
478
468
  }
479
469
  }
480
- const shared = SHARED_BRANCHES.has(branch);
470
+ const shared = isSharedBranch(branch);
481
471
  if (mode === "abort" && !shared) {
482
472
  const pr = openPrFlag === undefined
483
473
  ? openPrNumber(cwd, branch)
@@ -598,7 +588,7 @@ function syncVerb(ctx) {
598
588
  ctx.log("no branch checked out (detached HEAD) — cannot merge dev's docs");
599
589
  return EXIT_DETACHED;
600
590
  }
601
- if (!SHARED_BRANCHES.has(branch) && docsBehind > 0) {
591
+ if (!isSharedBranch(branch) && docsBehind > 0) {
602
592
  ctx.log(`docs/ is ${docsBehind} commit(s) behind ${UPSTREAM} — merging it in`);
603
593
  if (!quietGit(top, ["merge", "--no-edit", UPSTREAM]).ok) {
604
594
  const outcome = resolveDocsMerge(top);
@@ -623,93 +613,28 @@ function syncVerb(ctx) {
623
613
  ctx.emit(out);
624
614
  return EXIT.OK;
625
615
  }
626
- async function switchVerb(ctx) {
627
- const devPushes = boolString(ctx.flags.devPushes, "dev-pushes");
628
- const worktrees = boolString(ctx.flags.worktrees, "worktrees");
616
+ /**
617
+ * Ship Step 13: after the merge, bring local dev up to origin/dev by a pure
618
+ * fast-forward without checking anything out, then a frozen install when the
619
+ * main checkout is on dev and moved. Never pushes.
620
+ */
621
+ function syncDevVerb(ctx) {
629
622
  const root = repoRoot(ctx.cwd);
630
- // `bkit install` can leave core.bare=true on the main checkout, which breaks every checkout below.
623
+ // `bkit install` can leave core.bare=true on the main checkout, which breaks `merge --ff-only` there.
631
624
  if (git(root, ["config", "--get", "core.bare"]) === "true" &&
632
625
  fs.statSync(path.join(root, ".git"), { throwIfNoEntry: false })?.isDirectory()) {
633
626
  runGit(root, ["config", "core.bare", "false"]);
634
627
  }
635
- const out = {
636
- switched: false,
637
- branch: currentBranch(root),
638
- ahead: 0,
639
- pushed: false,
640
- installed: null,
641
- skipped: null,
642
- };
643
- if (!devPushes) {
644
- ctx.log(`this runtime does not push ${DEV} — skipping the local ${DEV} checkout; the merge already landed server-side`);
645
- ctx.emit({ ...out, skipped: "dev-pushes-false" });
646
- return EXIT.OK;
647
- }
648
- if (!worktrees) {
649
- ctx.log("refusing a local dev checkout in a runtime without worktrees (devPushes=true, worktrees=false)");
650
- return EXIT_RUNTIME_REFUSED;
651
- }
652
- const fid = String(ctx.flags.fid);
653
- // Still held at the deadline: acquireDevLock throws EXIT.NO naming the holder.
654
- const lock = await acquireDevLock({
655
- cwd: root,
656
- workflow: "ship",
657
- fid,
658
- deadlineS: TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S,
659
- log: ctx.log,
660
- });
661
- try {
662
- runGit(root, ["checkout", DEV]);
663
- out.branch = currentBranch(root);
664
- if (out.branch !== DEV) {
665
- ctx.log(`not on ${DEV} after checkout (on '${out.branch}') — aborting dev ops`);
666
- return EXIT_NOT_DEV;
667
- }
668
- out.switched = true;
669
- const fetch = runGit(root, ["fetch", REMOTE, DEV]);
670
- if (!fetch.ok) {
671
- ctx.log(`git fetch ${REMOTE} ${DEV} failed: ${fetch.stderr}`);
672
- return EXIT_FETCH_FAILED;
673
- }
674
- out.ahead = Number(git(root, ["rev-list", "--count", `${UPSTREAM}..${DEV}`]) ?? "0");
675
- if (out.ahead > 0) {
676
- const triggering = (git(root, ["log", "--format=%h %s", `${UPSTREAM}..${DEV}`]) ?? "")
677
- .split("\n")
678
- .filter((l) => l !== "" && !SKIP_CI_TOKEN.test(l));
679
- if (triggering.length > 0) {
680
- ctx.log(`local ${DEV} is ${out.ahead} commit(s) ahead of ${UPSTREAM}, ${triggering.length} of them would run CI:`);
681
- for (const l of triggering)
682
- ctx.log(` ${l}`);
683
- ctx.log(`ship will not push these: a CI run on ${DEV} can cancel the in-flight run validating this merge`);
684
- ctx.log(`reconcile, then re-run ship: git -C "${root}" pull --rebase ${REMOTE} ${DEV} && git -C "${root}" push ${REMOTE} ${DEV}`);
685
- return EXIT.NEEDS_HUMAN;
686
- }
687
- const pull = quietGit(root, ["pull", "--rebase", REMOTE, DEV]);
688
- if (!pull.ok) {
689
- ctx.log(`git pull --rebase ${REMOTE} ${DEV} failed: ${pull.stderr}`);
690
- return EXIT_PULL_FAILED;
691
- }
692
- const push = runGit(root, ["push", REMOTE, DEV]);
693
- if (!push.ok) {
694
- ctx.log(`git push ${REMOTE} ${DEV} failed: ${push.stderr}`);
695
- return EXIT_PUSH_FAILED;
696
- }
697
- out.pushed = true;
698
- }
699
- else {
700
- const pull = runGit(root, ["pull", "--ff-only", REMOTE, DEV]);
701
- if (!pull.ok) {
702
- ctx.log(`git pull --ff-only ${REMOTE} ${DEV} failed: ${pull.stderr}`);
703
- return EXIT_PULL_FAILED;
704
- }
705
- }
706
- out.installed = install(ctx, root);
707
- ctx.emit(out);
708
- return out.installed === false ? EXIT_INSTALL_FAILED : EXIT.OK;
709
- }
710
- finally {
711
- releaseLock(lock.path, { workflow: "ship", fid, token: lock.token });
628
+ const fetch = runGit(root, ["fetch", REMOTE, DEV]);
629
+ if (!fetch.ok) {
630
+ ctx.log(`git fetch ${REMOTE} ${DEV} failed: ${fetch.stderr}`);
631
+ return EXIT_FETCH_FAILED;
712
632
  }
633
+ const devLocal = fastForwardDev(root, git(root, ["rev-parse", UPSTREAM]) ?? "", ctx.log);
634
+ const branch = currentBranch(root);
635
+ const installed = branch === DEV && devLocal === "fast-forwarded" ? install(ctx, root) : null;
636
+ ctx.emit({ devLocal, branch, installed });
637
+ return installed === false ? EXIT_INSTALL_FAILED : EXIT.OK;
713
638
  }
714
639
  /** Frozen install in the main checkout: false (logged) when it failed or could not run, null when there is nothing to install. */
715
640
  function install(ctx, root) {
@@ -752,89 +677,139 @@ function devPushesOf(root, status, log) {
752
677
  }
753
678
  class Stop extends CommandError {
754
679
  }
680
+ /** This run's artifacts written untracked into the main checkout instead of the worktree stop the close. */
681
+ function strayCheck(root, month, fid) {
682
+ const stray = (git(root, ["status", "--porcelain", "-uall", "--", `docs/plans/${month}/logs/${fid}/`]) ?? "")
683
+ .split("\n")
684
+ .filter((l) => l.startsWith("??"));
685
+ if (stray.length) {
686
+ throw new Stop(EXIT_LAND_STOPPED, `${fid} artifacts written to the main checkout instead of the worktree:\n${stray.join("\n")}\nMove them under .worktrees/${fid}/ or delete them, then re-run.`);
687
+ }
688
+ }
689
+ /** Non-empty lines of `rev:p`, trimmed; [] when `p` is absent there. */
690
+ function revLines(root, rev, p) {
691
+ return (git(root, ["show", `${rev}:${p}`]) ?? "")
692
+ .split("\n")
693
+ .map((l) => l.trim())
694
+ .filter((l) => l !== "");
695
+ }
755
696
  /**
756
- * The local close: under the dev lock, squash `feat/{fid}` into dev in the main
757
- * checkout, check the staged canonical docs are the branch's, commit the
758
- * bookkeeping plus what the squash brought, push dev, remove the worktree.
697
+ * Put back the `.jsonl` rows `branch` added that the squash dropped: `-X ours`
698
+ * keeps dev's side of a conflicting hunk, and a ledger git does not union-merge
699
+ * (a consumer's `.bkit/friction.jsonl`) loses the branch's rows there. Each
700
+ * missing row is appended to the staged file.
759
701
  */
760
- async function landLocal(ctx, root, o) {
761
- const feat = `feat/${o.fid}`;
762
- const lock = await acquireDevLock({
763
- cwd: root,
764
- workflow: o.workflow,
702
+ function restoreBranchRows(dir, branch) {
703
+ const base = git(dir, ["merge-base", "HEAD", branch]);
704
+ if (base === null)
705
+ return;
706
+ const changed = (git(dir, ["diff", "--name-only", "--no-renames", "--diff-filter=d", base, branch]) ?? "")
707
+ .split("\n")
708
+ .filter((p) => p.endsWith(".jsonl"));
709
+ for (const p of changed) {
710
+ const before = new Set(revLines(dir, base, p));
711
+ const file = path.join(dir, p);
712
+ const text = fs.existsSync(file) ? fs.readFileSync(file, "utf-8") : "";
713
+ const have = new Set(text.split("\n").map((l) => l.trim()));
714
+ const missing = revLines(dir, branch, p).filter((l) => !before.has(l) && !have.has(l));
715
+ if (missing.length === 0)
716
+ continue;
717
+ const sep = text !== "" && !text.endsWith("\n") ? "\n" : "";
718
+ fs.mkdirSync(path.dirname(file), { recursive: true });
719
+ fs.appendFileSync(file, `${sep}${missing.join("\n")}\n`);
720
+ runGit(dir, ["add", "--", p]);
721
+ }
722
+ }
723
+ /**
724
+ * Build the close in `dir`, a detached origin/dev checkout: squash `branch` with
725
+ * -X ours, put back ledger rows the squash dropped, check only docs came and the
726
+ * canonical docs are the branch's copy, add the roadmap row, commit `{workflow} DONE`.
727
+ */
728
+ function buildClose(ctx, dir, o) {
729
+ const squash = runGit(dir, ["merge", "--squash", "-X", "ours", o.branch]);
730
+ if (!squash.ok) {
731
+ throw new Stop(EXIT_LAND_STOPPED, `squash of ${o.branch} onto ${UPSTREAM} failed — nothing landed; ${o.branch} and its worktree kept: ${squash.stderr}`);
732
+ }
733
+ restoreBranchRows(dir, o.branch);
734
+ const staged = (git(dir, ["diff", "--cached", "--name-only"]) ?? "")
735
+ .split("\n")
736
+ .filter((p) => p !== "" && !CLOSE_DOCS.test(p));
737
+ if (staged.length)
738
+ throw new Stop(EXIT_LAND_STOPPED, `${o.workflow} close staged non-doc files:\n${staged.join("\n")}`);
739
+ const docs = canonicalDocs(dir, o.branch, o.workflow, o.month, o.fid);
740
+ const main = `docs/plans/${o.month}/${o.fid}-${o.workflow}.md`;
741
+ if (!docs.includes(main))
742
+ throw new Stop(EXIT_LAND_STOPPED, `${o.branch} carries no ${main} — nothing landed; ${o.branch} kept`);
743
+ const unlanded = docs.filter((d) => git(dir, ["rev-parse", "-q", "--verify", `:${d}`]) !==
744
+ git(dir, ["rev-parse", `${o.branch}:${d}`]));
745
+ if (unlanded.length) {
746
+ throw new Stop(EXIT_LAND_STOPPED, `squash did not stage the ${o.branch} copy of:\n${unlanded.join("\n")}\nnothing landed; ${o.branch} kept`);
747
+ }
748
+ appendFeature(dir, { workflow: o.workflow, fid: o.fid }, ctx.log);
749
+ commitBookkeeping({
750
+ root: dir,
751
+ month: o.month,
765
752
  fid: o.fid,
766
- deadlineS: TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S,
767
- log: ctx.log,
768
- });
769
- try {
770
- runGit(root, ["checkout", DEV]);
771
- const on = currentBranch(root);
772
- if (on !== DEV)
773
- throw new Stop(EXIT_NOT_DEV, `not on dev after checkout (on '${on}') — aborting dev ops`);
774
- const stray = (git(root, ["status", "--porcelain", "-uall", "--", `docs/plans/${o.month}/logs/${o.fid}/`]) ??
775
- "")
776
- .split("\n")
777
- .filter((l) => l.startsWith("??"));
778
- if (stray.length) {
779
- throw new Stop(EXIT_LAND_STOPPED, `${o.fid} artifacts written to the main checkout instead of the worktree:\n${stray.join("\n")}\nMove them under .worktrees/${o.fid}/ or delete them, then re-run.`);
780
- }
781
- if (!runGit(root, ["pull", "--ff-only", REMOTE, DEV]).ok)
782
- throw new Stop(EXIT_PULL_FAILED, "dev fast-forward failed");
783
- const squash = runGit(root, ["merge", "--squash", "-X", "ours", feat]);
784
- if (!squash.ok) {
785
- throw new Stop(EXIT_LAND_STOPPED, `squash of ${feat} into dev failed — nothing committed or pushed; ${feat} and its worktree kept. Clear what git names from the main checkout, then re-run: ${squash.stderr}`);
786
- }
787
- const staged = (git(root, ["diff", "--cached", "--name-only"]) ?? "")
788
- .split("\n")
789
- .filter((p) => p !== "" && !CLOSE_DOCS.test(p));
790
- if (staged.length)
791
- throw new Stop(EXIT_LAND_STOPPED, `${o.workflow} close staged non-doc files:\n${staged.join("\n")}`);
792
- const docs = canonicalDocs(root, feat, o.workflow, o.month, o.fid);
793
- const main = `docs/plans/${o.month}/${o.fid}-${o.workflow}.md`;
794
- if (!docs.includes(main))
795
- throw new Stop(EXIT_LAND_STOPPED, `${feat} carries no ${main} — nothing committed or pushed; ${feat} kept`);
796
- const unlanded = docs.filter((d) => git(root, ["rev-parse", "-q", "--verify", `:${d}`]) !==
797
- git(root, ["rev-parse", `${feat}:${d}`]));
798
- if (unlanded.length) {
799
- throw new Stop(EXIT_LAND_STOPPED, `squash did not stage the ${feat} copy of:\n${unlanded.join("\n")}\nnothing committed or pushed; ${feat} kept; the main checkout index still holds the squash`);
800
- }
801
- appendFeature(root, { workflow: o.workflow, fid: o.fid }, ctx.log);
802
- commitBookkeeping({
803
- root,
804
- month: o.month,
805
- fid: o.fid,
806
- scope: "core",
807
- mode: "commit-allow-empty",
808
- squashOf: feat,
809
- message: `docs(${o.fid}): ${o.workflow} DONE bkit [skip ci]`,
810
- }, ctx.log);
811
- if (!runGit(root, ["push", REMOTE, DEV]).ok)
812
- throw new Stop(EXIT_PUSH_FAILED, "dev push failed");
813
- const sha = git(root, ["rev-parse", "HEAD"]) ?? "";
814
- let worktree = null;
815
- try {
816
- worktree = { ...removeWorktree(root, o.fid, feat, ctx.log) };
817
- }
818
- catch (err) {
819
- // The close landed; a leftover worktree is a human's to remove.
820
- ctx.log(`worktree removal failed — remove .worktrees/${o.fid} by hand: ${err.message}`);
821
- }
822
- return { shape: "local", transport: "git", sha, canonicalRef: DEV, prNumber: null, worktree };
753
+ scope: "core",
754
+ mode: "commit-allow-empty",
755
+ squashOf: o.branch,
756
+ message: `docs(${o.fid}): ${o.workflow} DONE bkit [skip ci]`,
757
+ }, ctx.log);
758
+ }
759
+ /**
760
+ * The direct close, every runtime: build it in `.worktrees/_land-{fid}` off a
761
+ * fresh origin/dev and push it as dev. The main checkout is never touched. dev
762
+ * moved underneath → rebuild on the new dev and push again, with backoff,
763
+ * LAND_ATTEMPTS pushes in all. Any other refusal → null: the PR close takes over.
764
+ */
765
+ async function landDirect(ctx, root, o) {
766
+ const dir = landDir(root, o.fid);
767
+ const res = await pushToDev({ root, dir, build: (d) => buildClose(ctx, d, o), log: ctx.log });
768
+ switch (res.kind) {
769
+ case "landed":
770
+ return {
771
+ shape: "local",
772
+ transport: "git",
773
+ sha: res.sha,
774
+ prNumber: null,
775
+ pushAttempts: res.attempts,
776
+ };
777
+ case "refused":
778
+ ctx.log(`${REMOTE} refused the dev push — closing through a PR instead: ${res.stderr}`);
779
+ return null;
780
+ case "push-failed":
781
+ throw new Stop(EXIT_PUSH_FAILED, `dev push failed without a server answer — nothing landed; ${o.branch} and its worktree kept; re-run the land: ${res.stderr}`);
782
+ case "fetch-failed":
783
+ throw new Stop(EXIT_FETCH_FAILED, `git fetch ${REMOTE} ${DEV} failed — nothing landed; ${o.branch} kept`);
784
+ case "setup-failed":
785
+ throw new Stop(EXIT_LAND_STOPPED, `could not create ${dir} — nothing landed: ${res.stderr}`);
786
+ case "exhausted":
787
+ throw new Stop(EXIT_PUSH_FAILED, `dev moved before each of ${res.attempts} pushes — nothing landed; ${o.branch} and its worktree kept; re-run the land`);
823
788
  }
824
- finally {
825
- releaseLock(lock.path, { workflow: o.workflow, fid: o.fid, token: lock.token });
789
+ }
790
+ /** The checkout that has `branch` checked out, or null. */
791
+ function branchTree(root, branch) {
792
+ for (const block of (git(root, ["worktree", "list", "--porcelain"]) ?? "").split("\n\n")) {
793
+ const lines = block.split("\n");
794
+ if (lines.includes(`branch refs/heads/${branch}`))
795
+ return lines.find((l) => l.startsWith("worktree "))?.slice("worktree ".length) ?? null;
826
796
  }
797
+ return null;
827
798
  }
828
799
  /**
829
- * The PR close (a runtime that cannot push dev): commit the roadmap row on the
830
- * branch, push it, open or reuse the PR, squash-merge it with an empty body. gh
831
- * missing → EXIT.USE_MCP with what to create / merge; re-run with `--pr` (and
832
- * `--merged-sha` once merged).
800
+ * The PR close (the dev push was refused): commit the roadmap row on the branch
801
+ * in the checkout holding it, push it, open or reuse the PR, squash-merge it with
802
+ * an empty body. A merge that does not land on an open PR → update its branch
803
+ * from dev and try again, with backoff, LAND_ATTEMPTS tries in all; then stop with
804
+ * the PR left open. gh missing → EXIT.USE_MCP with what to create / merge; re-run
805
+ * with `--pr` (and `--merged-sha` once merged).
833
806
  */
834
- function landPr(ctx, o) {
835
- const tree = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
807
+ async function landPr(ctx, root, o) {
836
808
  let prNumber = o.pr;
837
809
  if (prNumber === undefined) {
810
+ const tree = branchTree(root, o.branch);
811
+ if (tree === null)
812
+ throw new Stop(EXIT_LAND_STOPPED, `no checkout has ${o.branch} checked out — the PR close commits the roadmap row on it; nothing landed`);
838
813
  runGit(tree, ["fetch", REMOTE, DEV, o.branch]);
839
814
  appendFeature(tree, { workflow: o.workflow, fid: o.fid }, ctx.log);
840
815
  commitBookkeeping({
@@ -872,33 +847,105 @@ function landPr(ctx, o) {
872
847
  let sha = o.mergedSha ?? "";
873
848
  let transport = o.mergedSha === undefined ? "gh" : "mcp";
874
849
  if (o.mergedSha === undefined) {
875
- const merged = mergePr(tree, { number: prNumber, subject }, ctx.log);
876
- if (merged.code === EXIT.USE_MCP) {
877
- ctx.emit({ stage: "merge", prNumber: Number(prNumber), subject, body: "" });
878
- return EXIT.USE_MCP;
850
+ for (let attempt = 1;; attempt++) {
851
+ const merged = mergePr(root, { number: prNumber, subject }, ctx.log);
852
+ if (merged.code === EXIT.USE_MCP) {
853
+ ctx.emit({ stage: "merge", prNumber: Number(prNumber), subject, body: "" });
854
+ return EXIT.USE_MCP;
855
+ }
856
+ if (merged.out.merged) {
857
+ sha = merged.out.mergeCommitOid ?? "";
858
+ break;
859
+ }
860
+ // An unread state (gh read failed) is retried like an open PR; only a closed PR stops at once.
861
+ if (merged.out.state !== null && merged.out.state !== "OPEN")
862
+ throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} did not reach MERGED (state=${merged.out.state})`);
863
+ if (attempt >= TIMEOUTS.LAND_ATTEMPTS)
864
+ throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} still not merged after ${attempt} tries — left open; merge it, then re-run with --pr=${prNumber} --merged-sha=<merge commit>`);
865
+ updateBranch(root, prNumber, ctx.log);
866
+ const wait = landBackoffMs(attempt);
867
+ ctx.log(`PR ${prNumber} not merged on try ${attempt} of ${TIMEOUTS.LAND_ATTEMPTS} — branch updated from dev; trying again in ${(wait / 1000).toFixed(1)}s`);
868
+ await sleep(wait);
879
869
  }
880
- if (!merged.out.merged)
881
- throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} did not reach MERGED (state=${merged.out.state ?? "unread"})`);
882
- sha = merged.out.mergeCommitOid ?? "";
883
870
  transport = "gh";
884
871
  }
885
872
  else {
886
- const back = probePr(tree, { number: prNumber, state: "open" });
873
+ const back = probePr(root, { number: prNumber, state: "open" });
887
874
  if (back.kind === "ok" && back.pr && back.pr.state !== "MERGED")
888
875
  throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} is ${back.pr.state}, not MERGED`);
889
876
  }
890
877
  if (sha === "")
891
878
  throw new Stop(EXIT_LAND_STOPPED, `could not resolve the landed SHA for PR ${prNumber}`);
892
- if (!runGit(tree, ["fetch", REMOTE, DEV]).ok)
879
+ if (!runGit(root, ["fetch", REMOTE, DEV]).ok)
893
880
  throw new Stop(EXIT_LAND_STOPPED, "fetch of origin/dev after the merge failed");
894
- return {
895
- shape: "pr",
896
- transport,
897
- sha,
898
- canonicalRef: UPSTREAM,
899
- prNumber: Number(prNumber),
900
- worktree: null,
901
- };
881
+ return { shape: "pr", transport, sha, prNumber: Number(prNumber), pushAttempts: 0 };
882
+ }
883
+ /**
884
+ * Bring local dev up to `sha` when that is a pure fast-forward — `merge
885
+ * --ff-only` when the main checkout is on dev, else move the branch pointer
886
+ * alone; nothing is checked out or pushed. Local commits origin/dev lacks (listed
887
+ * with the command that publishes them), or git refusing (an uncommitted edit the
888
+ * move would overwrite, dev checked out in another worktree), skip it with a log
889
+ * line: what landed is on origin/dev either way.
890
+ */
891
+ function fastForwardDev(root, sha, log) {
892
+ const local = git(root, ["rev-parse", "-q", "--verify", `refs/heads/${DEV}`]);
893
+ if (local === null)
894
+ return "none";
895
+ if (local === sha)
896
+ return "current";
897
+ if (!runGit(root, ["merge-base", "--is-ancestor", local, sha]).ok) {
898
+ const ahead = (git(root, ["log", "--format=%h %s", `${sha}..${local}`]) ?? "")
899
+ .split("\n")
900
+ .filter((l) => l !== "");
901
+ log(`local ${DEV} has ${ahead.length} commit(s) ${UPSTREAM} does not — not fast-forwarded:`);
902
+ for (const l of ahead)
903
+ log(` ${l}`);
904
+ log(`to publish them, on ${DEV} in ${root}: git pull --rebase ${REMOTE} ${DEV} && git push ${REMOTE} ${DEV}`);
905
+ return "skipped";
906
+ }
907
+ const moved = currentBranch(root) === DEV
908
+ ? runGit(root, ["merge", "--ff-only", "-q", sha])
909
+ : runGit(root, ["fetch", "-q", ".", `${sha}:refs/heads/${DEV}`]);
910
+ if (!moved.ok) {
911
+ log(`local ${DEV} not fast-forwarded — git refused: ${moved.stderr}`);
912
+ return "skipped";
913
+ }
914
+ return "fast-forwarded";
915
+ }
916
+ /**
917
+ * What `branch` changed that origin/dev does not hold, compared file by file
918
+ * against the branch's fork point: a file whose dev copy differs from the
919
+ * branch's, or (a `.jsonl` ledger, union-merged) a line the branch added that
920
+ * dev's copy lacks. `docs/roadmap.md` is re-rendered on every close, so it is
921
+ * not compared. The branch and its worktree are deleted only when this is empty.
922
+ */
923
+ function notOnDev(root, branch) {
924
+ const base = git(root, ["merge-base", UPSTREAM, branch]);
925
+ if (base === null)
926
+ return [`${branch}: no common history with ${UPSTREAM}`];
927
+ const lines = (rev, p) => revLines(root, rev, p);
928
+ return (git(root, ["diff", "--name-only", "--no-renames", "--diff-filter=d", base, branch]) ?? "")
929
+ .split("\n")
930
+ .filter((p) => p !== "" && p !== "docs/roadmap.md")
931
+ .filter((p) => {
932
+ if (!p.endsWith(".jsonl"))
933
+ return (git(root, ["rev-parse", `${branch}:${p}`]) !==
934
+ git(root, ["rev-parse", "-q", "--verify", `${UPSTREAM}:${p}`]));
935
+ const before = new Set(lines(base, p));
936
+ const onDev = new Set(lines(UPSTREAM, p));
937
+ return lines(branch, p).some((l) => !before.has(l) && !onDev.has(l));
938
+ });
939
+ }
940
+ /** Uncommitted or untracked files in the feature worktree; [] when there is no worktree. */
941
+ function uncommitted(root, fid) {
942
+ const wt = worktreeDir(root, fid);
943
+ if (!fs.existsSync(wt))
944
+ return [];
945
+ const status = runGit(wt, ["status", "--porcelain", "-uall"]);
946
+ if (!status.ok)
947
+ return [`git status in ${wt} failed: ${status.stderr}`];
948
+ return status.stdout.split("\n").filter((l) => l !== "");
902
949
  }
903
950
  async function landVerb(ctx) {
904
951
  const workflow = String(ctx.flags.workflow);
@@ -907,7 +954,7 @@ async function landVerb(ctx) {
907
954
  const fid = String(ctx.flags.fid);
908
955
  const root = repoRoot(ctx.cwd);
909
956
  const month = resolveMonth(root, fid, str(ctx.flags.month));
910
- // `bkit install` can leave core.bare=true on the main checkout, which breaks every checkout below.
957
+ // `bkit install` can leave core.bare=true on the main checkout, which breaks every worktree below.
911
958
  if (git(root, ["config", "--get", "core.bare"]) === "true" &&
912
959
  fs.statSync(path.join(root, ".git"), { throwIfNoEntry: false })?.isDirectory()) {
913
960
  runGit(root, ["config", "core.bare", "false"]);
@@ -915,37 +962,68 @@ async function landVerb(ctx) {
915
962
  const worktreeStatus = path.join(git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root, "docs", "plans", month, "logs", fid, "status.jsonl");
916
963
  try {
917
964
  const devPushes = devPushesOf(root, worktreeStatus, ctx.log);
918
- const landed = devPushes
919
- ? await landLocal(ctx, root, { workflow, fid, month })
920
- : landPr(ctx, {
965
+ const branch = str(ctx.flags.branch) || (devPushes ? `feat/${fid}` : currentBranch(ctx.cwd));
966
+ const pr = str(ctx.flags.pr);
967
+ if (devPushes && pr === undefined)
968
+ strayCheck(root, month, fid);
969
+ const landed = (pr === undefined ? await landDirect(ctx, root, { workflow, fid, month, branch }) : null) ??
970
+ (await landPr(ctx, root, {
921
971
  workflow,
922
972
  fid,
923
973
  month,
924
974
  issue: str(ctx.flags.issue) || undefined,
925
- branch: String(ctx.flags.branch ?? currentBranch(ctx.cwd)),
926
- pr: str(ctx.flags.pr),
975
+ branch,
976
+ pr,
927
977
  mergedSha: str(ctx.flags.mergedSha),
928
- });
978
+ }));
929
979
  if (typeof landed === "number")
930
980
  return landed;
931
- // The audit: canonical docs on dev, the landed body clean, the transport recorded.
981
+ runGit(root, ["fetch", REMOTE, DEV]);
982
+ const localDev = devPushes ? fastForwardDev(root, landed.sha, ctx.log) : null;
983
+ // The audit: canonical docs on origin/dev, the landed body clean, the transport recorded.
932
984
  const docs = canonicalDocs(root, landed.sha, workflow, month, fid);
933
985
  const main = `docs/plans/${month}/${fid}-${workflow}.md`;
934
- const missing = [main, ...docs].filter((d) => !runGit(root, ["cat-file", "-e", `${landed.canonicalRef}:${d}`]).ok);
935
- const status = path.join(root, "docs", "plans", month, "logs", fid, "status.jsonl");
936
- runGit(root, ["fetch", REMOTE, DEV]);
986
+ const missing = [main, ...docs].filter((d) => !runGit(root, ["cat-file", "-e", `${UPSTREAM}:${d}`]).ok);
937
987
  const token = bodySkipToken(root, landed.sha);
938
988
  if (token === undefined)
939
989
  throw new Stop(EXIT_LANDED_UNVERIFIED, `post-close body scan errored on ${landed.sha}`);
940
990
  const scanResult = token ? "skip-token-found" : "clean";
941
- if (!crossCheckFile(status, landed.transport, ctx.log).ok)
991
+ // A PR runtime's checkout holds the branch, so its status file is this run's.
992
+ // A runtime that pushes dev never writes the main checkout: the cross-check
993
+ // reads the landed commit's copy, and the transport is in the emitted result.
994
+ const status = path.join(root, "docs", "plans", month, "logs", fid, "status.jsonl");
995
+ const onDisk = !devPushes && fs.existsSync(status);
996
+ const rows = onDisk ? readStatusRows(status) : readStatusRowsAt(status, landed.sha);
997
+ const label = onDisk ? status : `${landed.sha}:${path.relative(root, status)}`;
998
+ if (!crossCheckRows(rows, label, landed.transport, ctx.log).ok)
942
999
  throw new Stop(EXIT_LANDED_UNVERIFIED, "close transport cross-check failed");
943
- closeTransportRow(status, { shape: landed.shape, sha: landed.sha, scanResult });
1000
+ if (onDisk)
1001
+ closeTransportRow(status, { shape: landed.shape, sha: landed.sha, scanResult });
1002
+ else
1003
+ ctx.log(`close-transport row not written — the main checkout is never written to; shape=${landed.shape} sha=${landed.sha} scan=${scanResult}`);
944
1004
  if (token)
945
1005
  throw new Stop(EXIT_LANDED_UNVERIFIED, `landed commit ${landed.sha} inherited a CI-suppression token in its body`);
946
1006
  if (missing.length)
947
- throw new Stop(EXIT_LANDED_UNVERIFIED, `canonical ${workflow} missing on dev: ${missing.join(", ")}`);
948
- const released = releaseLock(workflowLockPath(lockRoot(root, workflow, false), month, fid), {
1007
+ throw new Stop(EXIT_LANDED_UNVERIFIED, `canonical ${workflow} missing on ${UPSTREAM}: ${missing.join(", ")}`);
1008
+ const notLanded = notOnDev(root, branch);
1009
+ if (notLanded.length)
1010
+ throw new Stop(EXIT_LANDED_UNVERIFIED, `${branch} carries work ${UPSTREAM} does not — ${branch} and its worktree kept:\n${notLanded.join("\n")}`);
1011
+ let worktree = null;
1012
+ const left = devPushes ? uncommitted(root, fid) : [];
1013
+ if (left.length) {
1014
+ ctx.log(`.worktrees/${fid} holds work that was never committed, so it is not on ${UPSTREAM} — it and ${branch} kept; commit or move it, then remove them by hand:\n${left.join("\n")}`);
1015
+ worktree = { removed: false, reason: "uncommitted", files: left };
1016
+ }
1017
+ else if (devPushes) {
1018
+ try {
1019
+ worktree = { ...removeWorktree(root, fid, branch, ctx.log) };
1020
+ }
1021
+ catch (err) {
1022
+ // The close landed; a leftover worktree is a human's to remove.
1023
+ ctx.log(`worktree removal failed — remove .worktrees/${fid} by hand: ${err.message}`);
1024
+ }
1025
+ }
1026
+ const released = releaseLock(workflowLockPath(root, month, fid), {
949
1027
  workflow,
950
1028
  fid,
951
1029
  token: str(ctx.flags.token),
@@ -957,9 +1035,11 @@ async function landVerb(ctx) {
957
1035
  transport: landed.transport,
958
1036
  landedSha: landed.sha,
959
1037
  prNumber: landed.prNumber,
960
- canonicalRef: landed.canonicalRef,
1038
+ canonicalRef: UPSTREAM,
961
1039
  scanResult,
962
- worktree: landed.worktree,
1040
+ pushAttempts: landed.pushAttempts,
1041
+ localDev,
1042
+ worktree,
963
1043
  });
964
1044
  return EXIT.OK;
965
1045
  }
@@ -1059,7 +1139,7 @@ function anchorReadVerb(ctx) {
1059
1139
  // ---------------------------------------------------------------------------
1060
1140
  export const branchesCommand = {
1061
1141
  noun: "branches",
1062
- summary: "Sync, push, rebase and switch branches; stamp and read a doc's base-commit anchor.",
1142
+ summary: "Sync, push, land and rebase branches; stamp and read a doc's base-commit anchor.",
1063
1143
  verbs: {
1064
1144
  sync: {
1065
1145
  summary: `Fetch ${UPSTREAM}; report whether it is an ancestor of HEAD (Path A/B) and how far docs/ is behind; optionally merge it in.`,
@@ -1159,48 +1239,22 @@ export const branchesCommand = {
1159
1239
  },
1160
1240
  run: rebaseVerb,
1161
1241
  },
1162
- switch: {
1163
- summary: "After a merge, return the main checkout to dev and bring it level with origin/dev, under the dev lock.",
1164
- flags: [
1165
- {
1166
- name: "fid",
1167
- type: "string",
1168
- required: true,
1169
- help: "feature id, recorded in the dev lock",
1170
- },
1171
- {
1172
- name: "dev-pushes",
1173
- type: "string",
1174
- required: true,
1175
- help: "true | false — runtimeDevPushes; false skips the switch",
1176
- },
1177
- {
1178
- name: "worktrees",
1179
- type: "string",
1180
- required: true,
1181
- help: "true | false — runtimeWorktrees; a local dev checkout needs true",
1182
- },
1183
- ],
1242
+ "sync-dev": {
1243
+ summary: "After a merge, fast-forward local dev to origin/dev without checking it out or pushing; frozen install when the main checkout is on dev and moved.",
1244
+ flags: [],
1184
1245
  output: {
1185
- switched: "true when the checkout is now on dev",
1186
- branch: "branch checked out afterwards",
1187
- ahead: "local dev commits that were ahead of origin/dev (all skip-CI, rebased and pushed)",
1188
- pushed: "true when those commits were pushed",
1189
- installed: "dependency install result: true, false (failed, exit 16), null (no package.json)",
1190
- skipped: "dev-pushes-false when the runtime does not push dev (null otherwise)",
1246
+ devLocal: "fast-forwarded | current | skipped (local dev has commits origin/dev lacks, listed with the publish command, or git refused) | none (no local dev)",
1247
+ branch: "the branch the main checkout is on (unchanged)",
1248
+ installed: "dependency install result: true, false (failed, exit 16), null (not run: not on dev, dev did not move, or no package.json)",
1191
1249
  },
1192
1250
  exitCodes: {
1193
- [EXIT_NOT_DEV]: "the checkout is not on dev after git checkout dev",
1194
1251
  [EXIT_FETCH_FAILED]: `git fetch ${REMOTE} ${DEV} failed`,
1195
- [EXIT_PUSH_FAILED]: "pushing the rebased local dev commits failed",
1196
- [EXIT_PULL_FAILED]: "git pull failed: local dev is not level with origin/dev",
1197
- [EXIT_RUNTIME_REFUSED]: "--dev-pushes=true with --worktrees=false",
1198
1252
  [EXIT_INSTALL_FAILED]: "dependency install failed or the package manager could not run",
1199
1253
  },
1200
- run: switchVerb,
1254
+ run: syncDevVerb,
1201
1255
  },
1202
1256
  land: {
1203
- summary: "Design / plan close: land feat/{fid} on dev — the local squash under the dev lock, or the PR squash-merge — then audit it and release the lock.",
1257
+ summary: "Design / plan close: squash the branch onto origin/dev in a throwaway worktree and push it as dev (retrying with backoff when dev moved), else the PR squash-merge; then audit it, fast-forward local dev on a laptop and release the lock.",
1204
1258
  flags: [
1205
1259
  { name: "workflow", type: "string", required: true, help: "design | plan" },
1206
1260
  { name: "fid", type: "string", required: true, help: "feature id" },
@@ -1214,7 +1268,7 @@ export const branchesCommand = {
1214
1268
  {
1215
1269
  name: "branch",
1216
1270
  type: "string",
1217
- help: "PR close: the head branch (default: the current branch)",
1271
+ help: "the branch to land (default: feat/{fid} where the runtime pushes dev, else the current branch)",
1218
1272
  },
1219
1273
  {
1220
1274
  name: "pr",
@@ -1232,16 +1286,17 @@ export const branchesCommand = {
1232
1286
  transport: "git | gh | mcp",
1233
1287
  landedSha: "the commit that landed on dev",
1234
1288
  prNumber: "the PR (pr shape), else null",
1235
- canonicalRef: "dev (local) | origin/dev (pr) — where the canonical docs were verified",
1289
+ canonicalRef: "origin/dev — where the canonical docs were verified",
1236
1290
  scanResult: "the landed commit body's scan: clean",
1237
- worktree: "the worktree removal result (local), else null",
1291
+ pushAttempts: "dev pushes the direct close took (0 for a PR close)",
1292
+ localDev: "fast-forwarded | current | skipped (local commits, or git refused) | none (no local dev) | null (runtime does not push dev)",
1293
+ worktree: "the worktree removal result (runtime pushes dev), else null",
1238
1294
  stage: "exit 80 only: open (create the PR via MCP with title / body / base / head) | merge (merge via MCP with subject, empty body)",
1239
1295
  },
1240
1296
  exitCodes: {
1241
- [EXIT_PUSH_FAILED]: "the dev or branch push failed",
1242
- [EXIT_NOT_DEV]: "the main checkout is not on dev after checkout",
1243
- [EXIT_PULL_FAILED]: "dev could not fast-forward",
1244
- [EXIT_LAND_STOPPED]: "a guard stopped the land: stray files, failed squash, staged non-doc files, canonical blob mismatch, PR not opened / merged (nothing landed)",
1297
+ [EXIT_PUSH_FAILED]: "dev moved before every one of LAND_ATTEMPTS pushes, or the PR branch push failed (nothing landed)",
1298
+ [EXIT_FETCH_FAILED]: `git fetch ${REMOTE} ${DEV} failed (nothing landed)`,
1299
+ [EXIT_LAND_STOPPED]: "a guard stopped the land: stray files, failed squash, staged non-doc files, canonical blob mismatch, no checkout holds the branch, PR not opened / not merged after LAND_ATTEMPTS tries (nothing landed; the PR stays open)",
1245
1300
  [EXIT_LANDED_UNVERIFIED]: "landed, but the body scan, transport cross-check or canonical-on-dev check failed",
1246
1301
  [EXIT_LOCK_LEFT]: "landed and audited, but the workflow lock file survived removal",
1247
1302
  },