@cbartens/bkit 5.3.0 → 5.5.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 (186) hide show
  1. package/.bkit/README.md +20 -7
  2. package/.bkit/core/.agents/docs.md +1 -1
  3. package/.bkit/core/.agents/rules.md +14 -9
  4. package/.bkit/core/.bkit/README.md +19 -6
  5. package/.bkit/core/.bkit/cloud.md +77 -46
  6. package/.bkit/core/.bkit/comparison.md +3 -3
  7. package/.bkit/core/.bkit/install.md +21 -18
  8. package/.bkit/core/.bkit/lite.md +6 -6
  9. package/.bkit/core/.bkit/pipeline.md +6 -3
  10. package/.bkit/core/.bkit/prompts.md +14 -10
  11. package/.bkit/core/.bkit/providers.md +7 -7
  12. package/.bkit/core/.bkit/templates.md +46 -10
  13. package/.bkit/core/.bkit/trackers.md +92 -38
  14. package/.bkit/core/.bkit/workflows.md +140 -116
  15. package/.bkit/core/AGENTS.md +2 -2
  16. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +3 -2
  17. package/.bkit/core/docs/templates/bkit-audit-adoption.md +1 -1
  18. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  19. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  20. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  21. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  22. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +2 -2
  23. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  24. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  25. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +4 -2
  26. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  27. package/.bkit/core/docs/templates/bkit-audit-cost.md +3 -2
  28. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -2
  30. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +5 -5
  31. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +14 -13
  33. package/.bkit/core/docs/templates/bkit-audit-documentation.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-duplication.md +2 -2
  35. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  36. package/.bkit/core/docs/templates/bkit-audit-flakes.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -2
  38. package/.bkit/core/docs/templates/bkit-audit-issues.md +25 -8
  39. package/.bkit/core/docs/templates/bkit-audit-llm.md +3 -2
  40. package/.bkit/core/docs/templates/bkit-audit-logs.md +10 -6
  41. package/.bkit/core/docs/templates/bkit-audit-models.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  43. package/.bkit/core/docs/templates/bkit-audit-prompts.md +5 -5
  44. package/.bkit/core/docs/templates/bkit-audit-red-team.md +3 -2
  45. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  46. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  47. package/.bkit/core/docs/templates/bkit-audit-security.md +11 -9
  48. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-testing.md +6 -5
  50. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  51. package/.bkit/core/engine/checks/after/auth.ts +88 -45
  52. package/.bkit/core/engine/checks/after/github.ts +18 -5
  53. package/.bkit/core/engine/checks/after/index.ts +1 -1
  54. package/.bkit/core/engine/checks/after/tools.ts +1 -1
  55. package/.bkit/core/engine/checks/before/env.ts +28 -18
  56. package/.bkit/core/engine/checks/before/mcp.ts +4 -2
  57. package/.bkit/core/engine/checks/status-holes.ts +0 -1
  58. package/.bkit/core/engine/checks/tips/catalogue.ts +31 -2
  59. package/.bkit/core/engine/checks/tips/index.ts +49 -27
  60. package/.bkit/core/engine/cli.ts +27 -18
  61. package/.bkit/core/engine/commands/ci/ci.ts +107 -0
  62. package/.bkit/core/engine/commands/comply.ts +25 -16
  63. package/.bkit/core/engine/commands/install/install.ts +11 -4
  64. package/.bkit/core/engine/commands/install/uninstall.ts +46 -0
  65. package/.bkit/core/engine/commands/land.ts +156 -0
  66. package/.bkit/core/engine/commands/lib.ts +10 -8
  67. package/.bkit/core/engine/commands/registry.ts +2 -0
  68. package/.bkit/core/engine/commands/tips.ts +7 -3
  69. package/.bkit/core/engine/commands/workflow/branches.ts +382 -282
  70. package/.bkit/core/engine/commands/workflow/disk.ts +556 -0
  71. package/.bkit/core/engine/commands/workflow/fids.ts +23 -15
  72. package/.bkit/core/engine/commands/workflow/issues.ts +106 -42
  73. package/.bkit/core/engine/commands/workflow/ledgers.ts +28 -11
  74. package/.bkit/core/engine/commands/workflow/locks.ts +38 -152
  75. package/.bkit/core/engine/commands/workflow/prs.ts +14 -3
  76. package/.bkit/core/engine/commands/workflow/repo.ts +6 -0
  77. package/.bkit/core/engine/commands/workflow/roadmap.ts +53 -54
  78. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -2
  79. package/.bkit/core/engine/commands/workflow/status.ts +33 -11
  80. package/.bkit/core/engine/commands/workflow/steps.ts +26 -17
  81. package/.bkit/core/engine/commands/workflow/workflows.ts +442 -269
  82. package/.bkit/core/engine/commands/workflow/workstreams.ts +3 -2
  83. package/.bkit/core/engine/commands/workflow/worktrees.ts +11 -1
  84. package/.bkit/core/engine/install/manifest.ts +31 -10
  85. package/.bkit/core/engine/install/modules/cloud.ts +3 -1
  86. package/.bkit/core/engine/install/modules/core.ts +97 -4
  87. package/.bkit/core/engine/install/modules/opencode.ts +5 -0
  88. package/.bkit/core/engine/install/placeholders.ts +13 -17
  89. package/.bkit/core/engine/install/write.ts +37 -1
  90. package/.bkit/core/engine/render/trackers.ts +35 -23
  91. package/.bkit/core/engine/shared/egress.ts +6 -0
  92. package/.bkit/core/engine/shared/settings.ts +96 -1
  93. package/.bkit/core/engine/shared/timeouts.ts +8 -7
  94. package/.bkit/core/hooks/guardrails-tiers.js +1 -1
  95. package/.bkit/core/prompts/bkit-audit-generate.md +80 -7
  96. package/.bkit/core/prompts/bkit-build-challenge-remediate.md +1 -1
  97. package/.bkit/core/prompts/bkit-build-challenge-tests.md +1 -1
  98. package/.bkit/core/prompts/bkit-build-plan-execute.md +1 -1
  99. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +1 -1
  100. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +1 -1
  101. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +1 -1
  102. package/.bkit/core/prompts/bkit-debug-failure-soak.md +1 -1
  103. package/.bkit/core/prompts/bkit-design-generate.md +2 -1
  104. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +1 -1
  105. package/.bkit/core/prompts/bkit-utility-update-decisions.md +4 -2
  106. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +4 -2
  107. package/.bkit/core/prompts/bkit-utility-update-documentation.md +12 -2
  108. package/.bkit/core/prompts/bkit-utility-update-failures.md +4 -2
  109. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +4 -2
  110. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +12 -5
  111. package/.bkit/core/prompts/bkit-utility-update-tracker.md +159 -0
  112. package/.bkit/core/workflows/bkit-auto.md +19 -6
  113. package/.bkit/core/workflows/bkit-build.md +64 -22
  114. package/.bkit/core/workflows/bkit-debug.md +72 -28
  115. package/.bkit/core/workflows/bkit-design.md +101 -37
  116. package/.bkit/core/workflows/bkit-plan.md +82 -31
  117. package/.bkit/core/workflows/bkit-ship.md +127 -108
  118. package/.bkit/shared/.bkit/.env.example +8 -0
  119. package/.bkit/shared/.claude/bkit-cloud.md +12 -12
  120. package/.bkit/shared/.claude/settings.json +4 -1
  121. package/.bkit/shared/.cursor/bkit-cloud.md +2 -2
  122. package/.bkit/shared/.cursor/mcp.json +11 -4
  123. package/.bkit/shared/.mcp.json +11 -4
  124. package/.bkit/shared/.opencode/opencode.json +2 -0
  125. package/.bkit/shared/docs/deployments.md +44 -29
  126. package/.bkit/shared/docs/security.md +1 -1
  127. package/.bkit/shared/docs/testing.md +3 -3
  128. package/.bkit/shared/gitignore +1 -2
  129. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +2 -2
  130. package/.bkit/templates/.github/renovate.json5 +1 -1
  131. package/.bkit/templates/.github/workflows/bkit-ci.yml +29 -56
  132. package/.bkit/templates/.github/workflows/bkit-cloud.yml +40 -12
  133. package/.bkit/templates/.husky/pre-commit +10 -4
  134. package/.bkit/templates/.husky/pre-push +69 -12
  135. package/.bkit/templates/.lintstagedrc.json +5 -1
  136. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.mjs +138 -0
  137. package/.bkit/templates/scripts/ci/lanes/check-tree-cache.test.mjs +181 -0
  138. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.machine.mjs +197 -0
  139. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +164 -0
  140. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +1 -1
  141. package/CHANGELOG.md +85 -1
  142. package/README.md +102 -100
  143. package/dist/checks/after/auth.js +81 -45
  144. package/dist/checks/after/github.js +17 -5
  145. package/dist/checks/after/index.js +1 -1
  146. package/dist/checks/after/tools.js +1 -1
  147. package/dist/checks/before/env.js +24 -17
  148. package/dist/checks/before/mcp.js +4 -2
  149. package/dist/checks/status-holes.js +0 -1
  150. package/dist/checks/tips/catalogue.js +28 -2
  151. package/dist/checks/tips/index.js +44 -28
  152. package/dist/cli.js +27 -19
  153. package/dist/commands/ci/ci.js +100 -0
  154. package/dist/commands/comply.js +20 -13
  155. package/dist/commands/install/install.js +10 -4
  156. package/dist/commands/install/uninstall.js +42 -0
  157. package/dist/commands/land.js +129 -0
  158. package/dist/commands/lib.js +9 -6
  159. package/dist/commands/registry.js +2 -0
  160. package/dist/commands/tips.js +7 -3
  161. package/dist/commands/workflow/branches.js +300 -243
  162. package/dist/commands/workflow/disk.js +452 -0
  163. package/dist/commands/workflow/fids.js +22 -15
  164. package/dist/commands/workflow/issues.js +90 -41
  165. package/dist/commands/workflow/ledgers.js +26 -11
  166. package/dist/commands/workflow/locks.js +35 -130
  167. package/dist/commands/workflow/prs.js +8 -3
  168. package/dist/commands/workflow/repo.js +5 -0
  169. package/dist/commands/workflow/roadmap.js +52 -57
  170. package/dist/commands/workflow/runtime.js +3 -2
  171. package/dist/commands/workflow/status.js +32 -12
  172. package/dist/commands/workflow/steps.js +20 -13
  173. package/dist/commands/workflow/workflows.js +397 -251
  174. package/dist/commands/workflow/workstreams.js +3 -2
  175. package/dist/commands/workflow/worktrees.js +11 -1
  176. package/dist/install/manifest.js +30 -10
  177. package/dist/install/modules/cloud.js +3 -1
  178. package/dist/install/modules/core.js +95 -5
  179. package/dist/install/modules/opencode.js +6 -0
  180. package/dist/install/placeholders.js +13 -19
  181. package/dist/install/write.js +26 -2
  182. package/dist/render/trackers.js +34 -20
  183. package/dist/shared/egress.js +6 -0
  184. package/dist/shared/settings.js +44 -0
  185. package/dist/shared/timeouts.js +8 -7
  186. package/package.json +11 -2
@@ -16,14 +16,15 @@ import * as path from "node:path";
16
16
  import { gitEnv } from "../../ledgers/telemetry.js";
17
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";
@@ -40,8 +41,6 @@ export const EXIT_FETCH_FAILED = 10;
40
41
  export const EXIT_MERGE_CONFLICT = 11;
41
42
  export const EXIT_ANCHOR_SKIP = 12;
42
43
  export const EXIT_NO_FILE = 13;
43
- export const EXIT_PULL_FAILED = 14;
44
- export const EXIT_RUNTIME_REFUSED = 15;
45
44
  export const EXIT_INSTALL_FAILED = 16;
46
45
  export const EXIT_LAND_STOPPED = 17;
47
46
  export const EXIT_LANDED_UNVERIFIED = 18;
@@ -81,13 +80,6 @@ function rebaseInProgress(top) {
81
80
  });
82
81
  }
83
82
  const currentBranch = (cwd) => git(cwd, ["branch", "--show-current"]) ?? "";
84
- const boolString = (v, flag) => {
85
- if (v === "true")
86
- return true;
87
- if (v === "false")
88
- return false;
89
- throw new CommandError(EXIT.USAGE, `--${flag} must be true or false, got "${String(v)}"`);
90
- };
91
83
  // ---------------------------------------------------------------------------
92
84
  // Conflict classification and resolution (rebase, and sync's docs merge)
93
85
  // ---------------------------------------------------------------------------
@@ -621,93 +613,28 @@ function syncVerb(ctx) {
621
613
  ctx.emit(out);
622
614
  return EXIT.OK;
623
615
  }
624
- async function switchVerb(ctx) {
625
- const devPushes = boolString(ctx.flags.devPushes, "dev-pushes");
626
- 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) {
627
622
  const root = repoRoot(ctx.cwd);
628
- // `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.
629
624
  if (git(root, ["config", "--get", "core.bare"]) === "true" &&
630
625
  fs.statSync(path.join(root, ".git"), { throwIfNoEntry: false })?.isDirectory()) {
631
626
  runGit(root, ["config", "core.bare", "false"]);
632
627
  }
633
- const out = {
634
- switched: false,
635
- branch: currentBranch(root),
636
- ahead: 0,
637
- pushed: false,
638
- installed: null,
639
- skipped: null,
640
- };
641
- if (!devPushes) {
642
- ctx.log(`this runtime does not push ${DEV} — skipping the local ${DEV} checkout; the merge already landed server-side`);
643
- ctx.emit({ ...out, skipped: "dev-pushes-false" });
644
- return EXIT.OK;
645
- }
646
- if (!worktrees) {
647
- ctx.log("refusing a local dev checkout in a runtime without worktrees (devPushes=true, worktrees=false)");
648
- return EXIT_RUNTIME_REFUSED;
649
- }
650
- const fid = String(ctx.flags.fid);
651
- // Still held at the deadline: acquireDevLock throws EXIT.NO naming the holder.
652
- const lock = await acquireDevLock({
653
- cwd: root,
654
- workflow: "ship",
655
- fid,
656
- deadlineS: TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S,
657
- log: ctx.log,
658
- });
659
- try {
660
- runGit(root, ["checkout", DEV]);
661
- out.branch = currentBranch(root);
662
- if (out.branch !== DEV) {
663
- ctx.log(`not on ${DEV} after checkout (on '${out.branch}') — aborting dev ops`);
664
- return EXIT_NOT_DEV;
665
- }
666
- out.switched = true;
667
- const fetch = runGit(root, ["fetch", REMOTE, DEV]);
668
- if (!fetch.ok) {
669
- ctx.log(`git fetch ${REMOTE} ${DEV} failed: ${fetch.stderr}`);
670
- return EXIT_FETCH_FAILED;
671
- }
672
- out.ahead = Number(git(root, ["rev-list", "--count", `${UPSTREAM}..${DEV}`]) ?? "0");
673
- if (out.ahead > 0) {
674
- const triggering = (git(root, ["log", "--format=%h %s", `${UPSTREAM}..${DEV}`]) ?? "")
675
- .split("\n")
676
- .filter((l) => l !== "" && !SKIP_CI_TOKEN.test(l));
677
- if (triggering.length > 0) {
678
- ctx.log(`local ${DEV} is ${out.ahead} commit(s) ahead of ${UPSTREAM}, ${triggering.length} of them would run CI:`);
679
- for (const l of triggering)
680
- ctx.log(` ${l}`);
681
- ctx.log(`ship will not push these: a CI run on ${DEV} can cancel the in-flight run validating this merge`);
682
- ctx.log(`reconcile, then re-run ship: git -C "${root}" pull --rebase ${REMOTE} ${DEV} && git -C "${root}" push ${REMOTE} ${DEV}`);
683
- return EXIT.NEEDS_HUMAN;
684
- }
685
- const pull = quietGit(root, ["pull", "--rebase", REMOTE, DEV]);
686
- if (!pull.ok) {
687
- ctx.log(`git pull --rebase ${REMOTE} ${DEV} failed: ${pull.stderr}`);
688
- return EXIT_PULL_FAILED;
689
- }
690
- const push = runGit(root, ["push", REMOTE, DEV]);
691
- if (!push.ok) {
692
- ctx.log(`git push ${REMOTE} ${DEV} failed: ${push.stderr}`);
693
- return EXIT_PUSH_FAILED;
694
- }
695
- out.pushed = true;
696
- }
697
- else {
698
- const pull = runGit(root, ["pull", "--ff-only", REMOTE, DEV]);
699
- if (!pull.ok) {
700
- ctx.log(`git pull --ff-only ${REMOTE} ${DEV} failed: ${pull.stderr}`);
701
- return EXIT_PULL_FAILED;
702
- }
703
- }
704
- out.installed = install(ctx, root);
705
- ctx.emit(out);
706
- return out.installed === false ? EXIT_INSTALL_FAILED : EXIT.OK;
707
- }
708
- finally {
709
- 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;
710
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;
711
638
  }
712
639
  /** Frozen install in the main checkout: false (logged) when it failed or could not run, null when there is nothing to install. */
713
640
  function install(ctx, root) {
@@ -750,89 +677,139 @@ function devPushesOf(root, status, log) {
750
677
  }
751
678
  class Stop extends CommandError {
752
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
+ }
753
696
  /**
754
- * The local close: under the dev lock, squash `feat/{fid}` into dev in the main
755
- * checkout, check the staged canonical docs are the branch's, commit the
756
- * 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.
757
701
  */
758
- async function landLocal(ctx, root, o) {
759
- const feat = `feat/${o.fid}`;
760
- const lock = await acquireDevLock({
761
- cwd: root,
762
- 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,
763
752
  fid: o.fid,
764
- deadlineS: TIMEOUTS.SHIP_DEV_LOCK_ACQUIRE_DEADLINE_S,
765
- log: ctx.log,
766
- });
767
- try {
768
- runGit(root, ["checkout", DEV]);
769
- const on = currentBranch(root);
770
- if (on !== DEV)
771
- throw new Stop(EXIT_NOT_DEV, `not on dev after checkout (on '${on}') — aborting dev ops`);
772
- const stray = (git(root, ["status", "--porcelain", "-uall", "--", `docs/plans/${o.month}/logs/${o.fid}/`]) ??
773
- "")
774
- .split("\n")
775
- .filter((l) => l.startsWith("??"));
776
- if (stray.length) {
777
- 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.`);
778
- }
779
- if (!runGit(root, ["pull", "--ff-only", REMOTE, DEV]).ok)
780
- throw new Stop(EXIT_PULL_FAILED, "dev fast-forward failed");
781
- const squash = runGit(root, ["merge", "--squash", "-X", "ours", feat]);
782
- if (!squash.ok) {
783
- 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}`);
784
- }
785
- const staged = (git(root, ["diff", "--cached", "--name-only"]) ?? "")
786
- .split("\n")
787
- .filter((p) => p !== "" && !CLOSE_DOCS.test(p));
788
- if (staged.length)
789
- throw new Stop(EXIT_LAND_STOPPED, `${o.workflow} close staged non-doc files:\n${staged.join("\n")}`);
790
- const docs = canonicalDocs(root, feat, o.workflow, o.month, o.fid);
791
- const main = `docs/plans/${o.month}/${o.fid}-${o.workflow}.md`;
792
- if (!docs.includes(main))
793
- throw new Stop(EXIT_LAND_STOPPED, `${feat} carries no ${main} — nothing committed or pushed; ${feat} kept`);
794
- const unlanded = docs.filter((d) => git(root, ["rev-parse", "-q", "--verify", `:${d}`]) !==
795
- git(root, ["rev-parse", `${feat}:${d}`]));
796
- if (unlanded.length) {
797
- 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`);
798
- }
799
- appendFeature(root, { workflow: o.workflow, fid: o.fid }, ctx.log);
800
- commitBookkeeping({
801
- root,
802
- month: o.month,
803
- fid: o.fid,
804
- scope: "core",
805
- mode: "commit-allow-empty",
806
- squashOf: feat,
807
- message: `docs(${o.fid}): ${o.workflow} DONE bkit [skip ci]`,
808
- }, ctx.log);
809
- if (!runGit(root, ["push", REMOTE, DEV]).ok)
810
- throw new Stop(EXIT_PUSH_FAILED, "dev push failed");
811
- const sha = git(root, ["rev-parse", "HEAD"]) ?? "";
812
- let worktree = null;
813
- try {
814
- worktree = { ...removeWorktree(root, o.fid, feat, ctx.log) };
815
- }
816
- catch (err) {
817
- // The close landed; a leftover worktree is a human's to remove.
818
- ctx.log(`worktree removal failed — remove .worktrees/${o.fid} by hand: ${err.message}`);
819
- }
820
- 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`);
821
788
  }
822
- finally {
823
- 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;
824
796
  }
797
+ return null;
825
798
  }
826
799
  /**
827
- * The PR close (a runtime that cannot push dev): commit the roadmap row on the
828
- * branch, push it, open or reuse the PR, squash-merge it with an empty body. gh
829
- * missing → EXIT.USE_MCP with what to create / merge; re-run with `--pr` (and
830
- * `--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).
831
806
  */
832
- function landPr(ctx, o) {
833
- const tree = git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? ctx.cwd;
807
+ async function landPr(ctx, root, o) {
834
808
  let prNumber = o.pr;
835
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`);
836
813
  runGit(tree, ["fetch", REMOTE, DEV, o.branch]);
837
814
  appendFeature(tree, { workflow: o.workflow, fid: o.fid }, ctx.log);
838
815
  commitBookkeeping({
@@ -870,33 +847,105 @@ function landPr(ctx, o) {
870
847
  let sha = o.mergedSha ?? "";
871
848
  let transport = o.mergedSha === undefined ? "gh" : "mcp";
872
849
  if (o.mergedSha === undefined) {
873
- const merged = mergePr(tree, { number: prNumber, subject }, ctx.log);
874
- if (merged.code === EXIT.USE_MCP) {
875
- ctx.emit({ stage: "merge", prNumber: Number(prNumber), subject, body: "" });
876
- 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);
877
869
  }
878
- if (!merged.out.merged)
879
- throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} did not reach MERGED (state=${merged.out.state ?? "unread"})`);
880
- sha = merged.out.mergeCommitOid ?? "";
881
870
  transport = "gh";
882
871
  }
883
872
  else {
884
- const back = probePr(tree, { number: prNumber, state: "open" });
873
+ const back = probePr(root, { number: prNumber, state: "open" });
885
874
  if (back.kind === "ok" && back.pr && back.pr.state !== "MERGED")
886
875
  throw new Stop(EXIT_LAND_STOPPED, `PR ${prNumber} is ${back.pr.state}, not MERGED`);
887
876
  }
888
877
  if (sha === "")
889
878
  throw new Stop(EXIT_LAND_STOPPED, `could not resolve the landed SHA for PR ${prNumber}`);
890
- if (!runGit(tree, ["fetch", REMOTE, DEV]).ok)
879
+ if (!runGit(root, ["fetch", REMOTE, DEV]).ok)
891
880
  throw new Stop(EXIT_LAND_STOPPED, "fetch of origin/dev after the merge failed");
892
- return {
893
- shape: "pr",
894
- transport,
895
- sha,
896
- canonicalRef: UPSTREAM,
897
- prNumber: Number(prNumber),
898
- worktree: null,
899
- };
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 !== "");
900
949
  }
901
950
  async function landVerb(ctx) {
902
951
  const workflow = String(ctx.flags.workflow);
@@ -905,7 +954,7 @@ async function landVerb(ctx) {
905
954
  const fid = String(ctx.flags.fid);
906
955
  const root = repoRoot(ctx.cwd);
907
956
  const month = resolveMonth(root, fid, str(ctx.flags.month));
908
- // `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.
909
958
  if (git(root, ["config", "--get", "core.bare"]) === "true" &&
910
959
  fs.statSync(path.join(root, ".git"), { throwIfNoEntry: false })?.isDirectory()) {
911
960
  runGit(root, ["config", "core.bare", "false"]);
@@ -913,37 +962,68 @@ async function landVerb(ctx) {
913
962
  const worktreeStatus = path.join(git(ctx.cwd, ["rev-parse", "--show-toplevel"]) ?? root, "docs", "plans", month, "logs", fid, "status.jsonl");
914
963
  try {
915
964
  const devPushes = devPushesOf(root, worktreeStatus, ctx.log);
916
- const landed = devPushes
917
- ? await landLocal(ctx, root, { workflow, fid, month })
918
- : 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, {
919
971
  workflow,
920
972
  fid,
921
973
  month,
922
974
  issue: str(ctx.flags.issue) || undefined,
923
- branch: String(ctx.flags.branch ?? currentBranch(ctx.cwd)),
924
- pr: str(ctx.flags.pr),
975
+ branch,
976
+ pr,
925
977
  mergedSha: str(ctx.flags.mergedSha),
926
- });
978
+ }));
927
979
  if (typeof landed === "number")
928
980
  return landed;
929
- // 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.
930
984
  const docs = canonicalDocs(root, landed.sha, workflow, month, fid);
931
985
  const main = `docs/plans/${month}/${fid}-${workflow}.md`;
932
- const missing = [main, ...docs].filter((d) => !runGit(root, ["cat-file", "-e", `${landed.canonicalRef}:${d}`]).ok);
933
- const status = path.join(root, "docs", "plans", month, "logs", fid, "status.jsonl");
934
- runGit(root, ["fetch", REMOTE, DEV]);
986
+ const missing = [main, ...docs].filter((d) => !runGit(root, ["cat-file", "-e", `${UPSTREAM}:${d}`]).ok);
935
987
  const token = bodySkipToken(root, landed.sha);
936
988
  if (token === undefined)
937
989
  throw new Stop(EXIT_LANDED_UNVERIFIED, `post-close body scan errored on ${landed.sha}`);
938
990
  const scanResult = token ? "skip-token-found" : "clean";
939
- 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)
940
999
  throw new Stop(EXIT_LANDED_UNVERIFIED, "close transport cross-check failed");
941
- 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}`);
942
1004
  if (token)
943
1005
  throw new Stop(EXIT_LANDED_UNVERIFIED, `landed commit ${landed.sha} inherited a CI-suppression token in its body`);
944
1006
  if (missing.length)
945
- throw new Stop(EXIT_LANDED_UNVERIFIED, `canonical ${workflow} missing on dev: ${missing.join(", ")}`);
946
- 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), {
947
1027
  workflow,
948
1028
  fid,
949
1029
  token: str(ctx.flags.token),
@@ -955,9 +1035,11 @@ async function landVerb(ctx) {
955
1035
  transport: landed.transport,
956
1036
  landedSha: landed.sha,
957
1037
  prNumber: landed.prNumber,
958
- canonicalRef: landed.canonicalRef,
1038
+ canonicalRef: UPSTREAM,
959
1039
  scanResult,
960
- worktree: landed.worktree,
1040
+ pushAttempts: landed.pushAttempts,
1041
+ localDev,
1042
+ worktree,
961
1043
  });
962
1044
  return EXIT.OK;
963
1045
  }
@@ -1057,7 +1139,7 @@ function anchorReadVerb(ctx) {
1057
1139
  // ---------------------------------------------------------------------------
1058
1140
  export const branchesCommand = {
1059
1141
  noun: "branches",
1060
- 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.",
1061
1143
  verbs: {
1062
1144
  sync: {
1063
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.`,
@@ -1157,48 +1239,22 @@ export const branchesCommand = {
1157
1239
  },
1158
1240
  run: rebaseVerb,
1159
1241
  },
1160
- switch: {
1161
- summary: "After a merge, return the main checkout to dev and bring it level with origin/dev, under the dev lock.",
1162
- flags: [
1163
- {
1164
- name: "fid",
1165
- type: "string",
1166
- required: true,
1167
- help: "feature id, recorded in the dev lock",
1168
- },
1169
- {
1170
- name: "dev-pushes",
1171
- type: "string",
1172
- required: true,
1173
- help: "true | false — runtimeDevPushes; false skips the switch",
1174
- },
1175
- {
1176
- name: "worktrees",
1177
- type: "string",
1178
- required: true,
1179
- help: "true | false — runtimeWorktrees; a local dev checkout needs true",
1180
- },
1181
- ],
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: [],
1182
1245
  output: {
1183
- switched: "true when the checkout is now on dev",
1184
- branch: "branch checked out afterwards",
1185
- ahead: "local dev commits that were ahead of origin/dev (all skip-CI, rebased and pushed)",
1186
- pushed: "true when those commits were pushed",
1187
- installed: "dependency install result: true, false (failed, exit 16), null (no package.json)",
1188
- 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)",
1189
1249
  },
1190
1250
  exitCodes: {
1191
- [EXIT_NOT_DEV]: "the checkout is not on dev after git checkout dev",
1192
1251
  [EXIT_FETCH_FAILED]: `git fetch ${REMOTE} ${DEV} failed`,
1193
- [EXIT_PUSH_FAILED]: "pushing the rebased local dev commits failed",
1194
- [EXIT_PULL_FAILED]: "git pull failed: local dev is not level with origin/dev",
1195
- [EXIT_RUNTIME_REFUSED]: "--dev-pushes=true with --worktrees=false",
1196
1252
  [EXIT_INSTALL_FAILED]: "dependency install failed or the package manager could not run",
1197
1253
  },
1198
- run: switchVerb,
1254
+ run: syncDevVerb,
1199
1255
  },
1200
1256
  land: {
1201
- 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.",
1202
1258
  flags: [
1203
1259
  { name: "workflow", type: "string", required: true, help: "design | plan" },
1204
1260
  { name: "fid", type: "string", required: true, help: "feature id" },
@@ -1212,7 +1268,7 @@ export const branchesCommand = {
1212
1268
  {
1213
1269
  name: "branch",
1214
1270
  type: "string",
1215
- 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)",
1216
1272
  },
1217
1273
  {
1218
1274
  name: "pr",
@@ -1230,16 +1286,17 @@ export const branchesCommand = {
1230
1286
  transport: "git | gh | mcp",
1231
1287
  landedSha: "the commit that landed on dev",
1232
1288
  prNumber: "the PR (pr shape), else null",
1233
- canonicalRef: "dev (local) | origin/dev (pr) — where the canonical docs were verified",
1289
+ canonicalRef: "origin/dev — where the canonical docs were verified",
1234
1290
  scanResult: "the landed commit body's scan: clean",
1235
- 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",
1236
1294
  stage: "exit 80 only: open (create the PR via MCP with title / body / base / head) | merge (merge via MCP with subject, empty body)",
1237
1295
  },
1238
1296
  exitCodes: {
1239
- [EXIT_PUSH_FAILED]: "the dev or branch push failed",
1240
- [EXIT_NOT_DEV]: "the main checkout is not on dev after checkout",
1241
- [EXIT_PULL_FAILED]: "dev could not fast-forward",
1242
- [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)",
1243
1300
  [EXIT_LANDED_UNVERIFIED]: "landed, but the body scan, transport cross-check or canonical-on-dev check failed",
1244
1301
  [EXIT_LOCK_LEFT]: "landed and audited, but the workflow lock file survived removal",
1245
1302
  },