mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/git/sync-from-base.js

@@ -1,66 +1,10 @@
 /**
- * sync-from-base.js — Fetch and merge `origin/<baseBranch>` into the
- * current branch of a worktree, so a Story or Epic PR opens with the
- * latest base commits already integrated (Story #2580).
+ * sync-from-base.js — merge `origin/<baseBranch>` into a worktree's branch
+ * before the PR opens. Merge, not rebase (settled): a rebase force-pushes
+ * away review state and spends the capture stamp just the same.
  *
- * The race this addresses: when multiple `/single-story-deliver` sessions
- * run in parallel, each Story branch is forked from the same `main` SHA.
- * Whichever PR auto-merges first bumps `main`; the lagging PRs are then
- * "behind base" and (with branch-protection's `up-to-date branch` rule)
- * stall at the merge gate. Pulling the latest base commits into the
- * Story branch before push makes the initial CI run reflect a fresh
- * merge and reduces (does not eliminate) the residual race-with-merge
- * window. The merge queue is the proper fix for the residual race.
- *
- * Why merge, not rebase (Story #5267 — settled, do not re-open):
- *
- *   1. Mandrel states no rebase rule anywhere. `git-conventions.md`
- *      mandates branch shapes and commit subjects and is silent on how a
- *      branch takes on base commits, so there is no convention to honour
- *      here — only a trade-off to pick.
- *   2. Story branches are pushed and reviewed across iterations of the
- *      watch + fix loop. A rebase force-pushes, discarding in-flight
- *      reviewer context and any review state pinned to the old SHAs.
- *   3. A rebase would NOT save the pre-push capture stamp people reach
- *      for it to save. The stamp is keyed on the tree, and rebasing onto
- *      a moved base changes the tree exactly as merging it does — both
- *      invalidate the stamp, so the credit argument is a wash. The real
- *      remedy is the `changedPaths` reporting below: say out loud when
- *      the sync spent the stamp, rather than change how it is spent.
- *
- * The merge commit is squashed away when the PR lands, so the cosmetic
- * cost is zero.
- *
- * Outcomes (`{ synced, kind, ... }`):
- *
- *   - `{ synced: true, kind: 'noop-already-current', changedPaths: [] }`
- *     — `origin/<base>` is already an ancestor of HEAD; nothing to do.
- *   - `{ synced: true, kind: 'fast-forward', changedPaths }` — merge
- *     fast-forwarded.
- *   - `{ synced: true, kind: 'merge-commit', changedPaths }` — non-trivial
- *     merge succeeded; a merge commit landed on the active branch.
- *
- * `changedPaths` is the tracked paths the sync brought into the branch —
- * `git diff --name-only <pre-merge HEAD> HEAD` — and is what lets a caller
- * tell a sync that spent a pre-push capture stamp from one that did not.
- * It is `[]` for every non-mutating and every failing outcome.
- *   - `{ synced: false, kind: 'fetch-failed', stderr }` — `git fetch`
- *     could not retrieve `origin/<base>`. No mutation occurred.
- *   - `{ synced: false, kind: 'conflict', conflictFiles }` — merge
- *     conflicted and was aborted; caller must surface a recoverable
- *     surface (structured comment + `agent::blocked`) and stop.
- *   - `{ synced: false, kind: 'merge-failed', stderr }` — merge exited
- *     non-zero for a reason other than a parseable conflict (rare; treat
- *     as a hard blocker on the caller's side).
- *   - `{ synced: false, kind: 'merge-driver-missing', stderr }` — the
- *     worktree's `.gitattributes` routes `baselines/*.json` through the
- *     `mandrel-baseline` merge driver and this clone has no
- *     `merge.mandrel-baseline.driver` config, so git would text-merge
- *     generated baselines. Nothing was fetched or merged (Story #5277).
- *
- * The helper does not mutate any ticket state, post comments, or write
- * to anything other than the worktree's git refs / index. Callers own
- * the recovery surface.
+ * Mutates only git refs/index. `changedPaths` tells the caller whether the
+ * sync spent a capture stamp; `[]` on every non-mutating or failing outcome.
  */
 
 import {
@@ -74,15 +18,8 @@ import {
 } from '../git-utils.js';
 
 /**
- * Refuse the sync when the baseline merge driver is declared but unregistered
- * (Story #5277). `probeBaselineMergeDriver` owns the two-part question and why
- * each half matters; this is where the answer becomes a refusal.
- *
- * Base-sync is the one place the failure is catchable before it happens: it is
- * the merge that runs unattended, immediately before the push, on exactly the
- * files a concurrent sibling Story most often also refreshed. Refusing costs
- * one operator command; proceeding costs a silently wrong baseline on `main`
- * that nothing downstream re-derives.
+ * Refuse when the declared baseline merge driver is unregistered: git would
+ * text-merge generated baselines and silently land a wrong one on `main`.
  *
  * @param {string} cwd
  * @param {typeof defaultGitSpawn} gitSpawn
@@ -109,8 +46,6 @@ function refuseWithoutMergeDriver(cwd, gitSpawn) {
 }
 
 /**
- * Resolve the current HEAD SHA, or `null` when git cannot answer.
- *
  * @param {typeof defaultGitSpawn} gitSpawn
  * @param {string} cwd
  * @returns {string|null}
@@ -123,14 +58,7 @@ function readHead(gitSpawn, cwd) {
 }
 
 /**
- * The tracked paths that differ between `fromSha` and the current HEAD.
- *
- * Returns `[]` when the pre-merge SHA could not be read or the diff itself
- * failed. That is deliberately the quiet answer: the only consumer is the
- * caller's "your capture stamp may be dead" warning, and manufacturing that
- * warning out of a failed probe would cry wolf on every sync in a repo where
- * `rev-parse` is broken — a condition the merge one line earlier would
- * already have failed on.
+ * A failed probe answers `[]` so the stamp warning never cries wolf.
  *
  * @param {typeof defaultGitSpawn} gitSpawn
  * @param {string} cwd
@@ -149,24 +77,14 @@ function diffPaths(gitSpawn, cwd, fromSha) {
 }
 
 /**
- * Sync the active branch in `cwd` against `origin/<baseBranch>`. See
- * the module docstring for the full outcome envelope.
+ * A conflict is aborted before returning; the caller surfaces it.
  *
  * @param {object} opts
- * @param {string} opts.cwd Absolute path to the worktree (or main
- *   checkout) on which the merge should run. The caller is responsible
- *   for ensuring the desired branch is checked out — this helper does
- *   not switch branches.
- * @param {string} opts.baseBranch Name of the base branch on `origin`
- *   (e.g. `'main'` or `'epic/123'`). The helper fetches and merges
- *   `origin/<baseBranch>`.
- * @param {(tag: string, msg: string) => void} [opts.log] Progress sink.
- *   Receives `(tag, message)` for each non-trivial step. Defaults to a
- *   no-op so the helper is silent when called from a test.
+ * @param {string} opts.cwd Branch must already be checked out.
+ * @param {string} opts.baseBranch
+ * @param {(tag: string, msg: string) => void} [opts.log]
  * @param {typeof defaultGitFetchWithRetry} [opts.gitFetchWithRetry]
- *   Override for unit tests.
- * @param {typeof defaultGitSpawn} [opts.gitSpawn] Override for unit
- *   tests.
+ * @param {typeof defaultGitSpawn} [opts.gitSpawn]
  *
  * @returns {Promise<
  *   | { synced: true, kind: 'noop-already-current', changedPaths: string[] }
@@ -209,10 +127,6 @@ export async function syncBranchFromBase({
     };
   }
 
-  // Probe whether the merge would be a no-op (origin already an ancestor
-  // of HEAD) or a fast-forward (HEAD an ancestor of origin). The two
-  // probes are cheap and let us avoid invoking `git merge` when nothing
-  // needs to change.
   const originAlreadyMerged = gitSpawn(
     cwd,
     'merge-base',
@@ -225,9 +139,7 @@ export async function syncBranchFromBase({
     return { synced: true, kind: 'noop-already-current', changedPaths: [] };
   }
 
-  // Pin the pre-merge HEAD so a successful sync can name what it brought
-  // in. Read BEFORE the merge, because afterwards the only handle on the
-  // old tree is this SHA.
+  // Must be read before the merge.
   const preMergeHead = readHead(gitSpawn, cwd);
 
   const headBehindOrigin = gitSpawn(
@@ -254,8 +166,6 @@ export async function syncBranchFromBase({
     };
   }
 
-  // Non-zero merge exit — collect the conflicting file list before
-  // aborting so the caller can present a recoverable surface.
   const unmerged = gitSpawn(cwd, 'diff', '--name-only', '--diff-filter=U');
   const conflictFiles = (unmerged.stdout ?? '')
     .toString()
@@ -263,9 +173,7 @@ export async function syncBranchFromBase({
     .map((s) => s.trim())
     .filter((s) => s.length > 0);
 
-  // Always abort, even when the conflict list is empty — leaving the
-  // worktree in a half-merged state would block the operator's recovery
-  // loop on the next iteration.
+  // Always abort: a half-merged worktree blocks the next recovery.
   gitSpawn(cwd, 'merge', '--abort');
 
   if (conflictFiles.length > 0) {

package/.agents/scripts/lib/git-branch-cleanup.js

@@ -1,20 +1,8 @@
 /**
- * git-branch-cleanup.js — Shared branch deletion helpers (local + remote).
- *
- * Consolidates the "delete this branch from local and/or origin" pattern
- * used by `single-story-close.js` and other branch-reaping flows. Originally
- * carved out when more than one caller re-implemented the same idempotency
- * rules with subtle drift.
- *
- * All helpers:
- *   - Take an explicit `cwd` (worktree-isolation friendly).
- *   - Validate branch names via the canonical `assertBranchSafe` guard
- *     in protected mode (rejects `main`, `master`, `HEAD`, and `refs/*`
- *     before any destructive `git` invocation).
- *   - Treat "branch not found" / "remote ref does not exist" as success
- *     (idempotent), distinguishing it via `reason: 'not-found'`.
- *   - Return `{ deleted: bool, reason: string, stderr?: string }` and
- *     never throw on git's normal failure modes (caller inspects the result).
+ * git-branch-cleanup.js — local/remote branch deletion. Names pass the
+ * protected `assertBranchSafe` guard (no `main`/`master`/`HEAD`/`refs/*`)
+ * before any destructive call; "not found" counts as deleted (idempotent);
+ * git's normal failures are returned, never thrown.
  */
 
 import { assertBranchSafe, isSafeBranchName } from './branch-name-guard.js';
@@ -24,15 +12,9 @@ const NOT_FOUND_LOCAL = /not found|no such branch|did not match any/i;
 const NOT_FOUND_REMOTE = /remote ref does not exist|does not exist/i;
 
 /**
- * Delete a local branch.
- *
- * @param {string} name - Branch name.
- * @param {{ force?: boolean, cwd?: string }} [opts]
- *   - `force`: use `branch -D` (default true). When false, uses `branch -d`,
- *     which refuses to delete unmerged branches.
- *   - `cwd`: working directory (defaults to `process.cwd()`).
+ * @param {string} name
+ * @param {{ force?: boolean, cwd?: string }} [opts] `force` (default) = `-D`.
  * @returns {{ deleted: boolean, reason: string, stderr?: string }}
- *   `reason` is one of: `'deleted'`, `'not-found'`, `'unmerged'`, `'error'`.
  */
 export function deleteBranchLocal(name, opts = {}) {
   assertBranchSafe(name, { protected: true });
@@ -55,22 +37,14 @@ export function deleteBranchLocal(name, opts = {}) {
 }
 
 /**
- * Delete a branch on the remote.
- *
- * @param {string} name - Branch name (no `refs/heads/` prefix).
+ * @param {string} name
  * @param {{ remote?: string, cwd?: string, noVerify?: boolean }} [opts]
- *   - `noVerify`: pass `--no-verify` so a heavy `pre-push` hook does not
- *     block a delete-only push (the hook would still fire even though no
- *     commits are being uploaded). Default `false`.
+ *   `noVerify` skips a heavy `pre-push` hook on a delete-only push.
  * @returns {{ deleted: boolean, reason: string, stderr?: string }}
- *   `reason` is one of: `'deleted'`, `'not-found'`, `'error'`.
  */
 export function deleteBranchRemote(name, opts = {}) {
   assertBranchSafe(name, { protected: true });
   const remote = opts.remote ?? 'origin';
-  // Remote name (e.g. "origin") is a non-branch identifier; reuse the
-  // shared character-set predicate but raise a remote-scoped error so
-  // the failure message stays accurate.
   if (!isSafeBranchName(remote)) {
     throw new Error(`[git-branch-cleanup] Unsafe remote name: "${remote}".`);
   }
@@ -91,8 +65,7 @@ export function deleteBranchRemote(name, opts = {}) {
 }
 
 /**
- * Delete a branch in both locations. Always attempts both — a local
- * failure does not skip the remote attempt.
+ * Always attempts both sides — a local failure does not skip the remote.
  *
  * @param {string} name
  * @param {{ force?: boolean, remote?: string, cwd?: string, noVerify?: boolean }} [opts]
@@ -102,9 +75,6 @@ export function deleteBranchRemote(name, opts = {}) {
  *   local: ReturnType<typeof deleteBranchLocal>,
  *   remote: ReturnType<typeof deleteBranchRemote>,
  * }}
- *   Top-level `deleted` is true iff both sides succeeded (including
- *   idempotent not-found). `reason` is `'deleted'`, `'partial'`, or
- *   `'error'`.
  */
 export function deleteBranchEverywhere(name, opts = {}) {
   const local = deleteBranchLocal(name, opts);
@@ -118,26 +88,13 @@ export function deleteBranchEverywhere(name, opts = {}) {
 }
 
 /**
- * Delete N branches in a single batched git call (push --delete X Y Z, or
- * branch -D X Y Z), falling back to per-ref delete via
- * `deleteBranchLocal` / `deleteBranchRemote` if the batched call fails.
- * The fallback is what makes idempotency contract-correct: a batched call
- * fails as a unit if even one ref does not exist, but the per-ref retry
- * resolves each ref's outcome independently — `not-found` is reported as
- * deleted, real failures are surfaced.
+ * Delete N branches in one git call, falling back to per-ref deletes when it
+ * fails — a batch fails as a unit on one missing ref, so the fallback is what
+ * keeps not-found idempotent.
  *
- * @param {string[]} names - Branch names. Empty / falsy entries are
- *   filtered out before any git work.
+ * @param {string[]} names - Branch names; falsy entries are dropped.
  * @param {{ scope: 'local'|'remote', cwd?: string, force?: boolean, remote?: string, noVerify?: boolean }} opts
- *   - `scope`: required. `'local'` runs `git branch -D|-d`; `'remote'`
- *     runs `git push <remote> --delete`.
- *   - `force`, `remote`, `noVerify`: forwarded to the per-ref helper on
- *     the fallback path; `force` and `noVerify` are also honoured on the
- *     batched call.
  * @returns {{ deleted: string[], failed: Array<{ name: string, reason: string, stderr?: string }> }}
- *   `deleted` lists names that were successfully deleted (or were
- *   already gone). `failed` lists names whose per-ref retry returned a
- *   non-deleted result, with the lib's `reason` propagated.
  */
 function assertBatchedScope(scope) {
   if (scope !== 'local' && scope !== 'remote') {
@@ -183,8 +140,7 @@ export function deleteBranchesBatched(names, opts = {}) {
 
   const scope = opts.scope;
   assertBatchedScope(scope);
-  // Validate every name before any destructive call so a single bad
-  // entry can never leak into a batched git invocation.
+  // Validate all names first so a bad entry never reaches a batched call.
   for (const n of list) assertBranchSafe(n, { protected: true });
 
   const cwd = opts.cwd ?? process.cwd();
@@ -197,8 +153,5 @@ export function deleteBranchesBatched(names, opts = {}) {
     return { deleted: [...list], failed: [] };
   }
 
-  // Per-ref fallback. Each call independently classifies its outcome —
-  // already-gone refs are reported as `not-found` (counted as deleted),
-  // real failures surface in `failed[]`.
   return perRefFallback(list, scope, opts);
 }

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -1,26 +1,14 @@
 /**
- * git-branch-lifecycle.js — Shared git branch state machine helpers.
- *
- * Consolidates the "does this branch exist locally / remotely?" and
- * "ensure this branch exists and is checked out" logic that
- * `single-story-init.js` centralizes (formerly duplicated across the deleted
- * `story-init.js` and `dispatch-engine.js` entry seams).
- *
- * All helpers take an explicit `cwd`. Callers with worktree isolation
- * enabled pass the worktree path; single-tree callers pass `PROJECT_ROOT`.
- *
- * No helper here reads config, spawns its own logger, or knows about
- * GitHub. They are pure git-subprocess wrappers with validation on the
- * branch names they forward to git.
+ * git-branch-lifecycle.js — branch existence and seed/checkout helpers;
+ * names are validated before they reach git.
  */
 
 import { assertBranchSafe } from './branch-name-guard.js';
 import { gitPullWithRetry, gitSpawn, gitSync } from './git-utils.js';
 
 /**
- * Return the current branch name, or null if in detached HEAD state.
  * @param {string} cwd
- * @returns {string|null}
+ * @returns {string|null} null in detached HEAD state
  */
 export function currentBranch(cwd) {
   const result = gitSpawn(cwd, 'branch', '--show-current');
@@ -29,8 +17,6 @@ export function currentBranch(cwd) {
 }
 
 /**
- * Return true iff the given branch exists as a local ref in `cwd`'s repo.
- *
  * @param {string} branch
  * @param {string} cwd
  * @returns {boolean}
@@ -44,10 +30,7 @@ export function branchExistsLocally(branch, cwd) {
 }
 
 /**
- * Return true iff the given branch exists on the `origin` remote.
- *
- * Issues a network `ls-remote` call. Prefer `branchExistsViaTrackingRef`
- * after a `git fetch` has already populated the remote-tracking refs.
+ * Network call; prefer `branchExistsViaTrackingRef` after a fetch.
  *
  * @param {string} branch
  * @param {string} cwd
@@ -60,14 +43,7 @@ export function branchExistsRemotely(branch, cwd) {
 }
 
 /**
- * Return true iff the given branch exists on `origin` according to the
- * local remote-tracking ref (`refs/remotes/origin/<branch>`).
- *
- * This is a purely-local check (no network) that is authoritative whenever
- * a `git fetch origin` has already been run — e.g. inside `bootstrapWorktree`
- * and `bootstrapBranch` which always call `cachedGitFetch` first. Use this
- * instead of `branchExistsRemotely` in those paths to avoid a redundant
- * network round-trip.
+ * Local-only; authoritative once `git fetch origin` has run.
  *
  * @param {string} branch
  * @param {string} cwd
@@ -87,25 +63,10 @@ export function branchExistsViaTrackingRef(branch, cwd) {
 }
 
 /**
- * Pure: classify how a `story-<id>` branch should be seeded from the (local,
- * remote) ref-presence matrix. This is the single source of truth for
- * `single-story-init.js#decideStoryBranchSeed` (v2 `/mandrel-deliver` path).
- *
- * The init path previously re-implemented the same `local → no-op, remote →
- * fetch, else create` decision tree; it now delegates here so the branching
- * logic lives in exactly one place. The caller keeps its own keyword for
- * the "local ref already exists" outcome (`reuse` vs `none`) — synonyms for
- * "do not re-create / do not re-seed" preserved for its existing public/test
- * contract — so this classifier returns the neutral `'local'` keyword and
- * the caller maps it onto its own vocabulary.
+ * On `local`, do not `git branch` (it throws on an existing ref) or fetch.
  *
  * @param {{ localHas: boolean, remoteHas: boolean }} presence
  * @returns {'local'|'fetch'|'create'}
- *   - `local`  — a local ref already exists; the caller must not run
- *                `git branch` (which throws on the existing ref) and must not
- *                fetch.
- *   - `fetch`  — only the remote ref exists; materialise the local ref.
- *   - `create` — neither exists; branch from the base/Epic branch.
  */
 export function classifyBranchSeed({ localHas, remoteHas }) {
   if (localHas) return 'local';
@@ -114,39 +75,13 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
 }
 
 /**
- * Single-home for the story-branch seed-action *switch shell* that
- * `single-story-init.js#seedStoryBranch` owns (Story #4255). The deleted
- * Epic `story-init/branch-initializer.js` path had duplicated the same
- * shell before v2 cutover.
- *
- * The two callers differ in exactly two behavioural axes, both of which are
- * parameters here — no other conditional branching is introduced:
- *   - **`baseRef`** — the ref to branch from on `create` (`main` for v2
- *     `/mandrel-deliver`; pre-v2 Epic close used the Epic branch).
- *   - **`swallowCreateRace`** — when `true`, a `git branch` that exits
- *     non-zero with an "already exists" stderr is treated as reuse rather
- *     than a fatal error (pre-v2 concurrent wave dispatch). When `false`, any create failure
- *     throws (the v2 standalone path has no concurrent creator to race).
- *
- * The asymmetric surrounding wrappers (merged-sweep, fast-forward,
- * donor-prime, workspace-verify) are deliberately NOT folded in — they stay
- * in their respective callers.
- *
- * Caller-specific log lines and error text are passed in as the `messages`
- * data bag so behaviour stays byte-identical to the pre-extraction switches.
- * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injectable so
- * each caller can bind its own cwd (and tests can substitute stubs through the
- * parameter rather than by module mocking). Per
- * `.agents/rules/test-seams.md` rule 1 each seam **defaults to the real
- * implementation** bound to `cwd`, so a caller that only knows its checkout
- * passes `cwd` and nothing else; `single-story-init.js` keeps passing its own
- * pre-bound seams and is unaffected.
+ * Git seams default to the real implementation bound to `cwd`.
  *
  * @param {object} opts
  * @param {string} opts.storyBranch
- * @param {string} opts.baseRef            Ref to branch from on `create`.
- * @param {string} [opts.cwd]              Checkout the default seams bind to.
- * @param {boolean} [opts.swallowCreateRace=false]
+ * @param {string} opts.baseRef
+ * @param {string} [opts.cwd]
+ * @param {boolean} [opts.swallowCreateRace=false] "already exists" = reuse.
  * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} [opts.spawn]
  * @param {(branch: string) => boolean} [opts.existsLocally]
  * @param {(branch: string) => boolean} [opts.existsRemotely]
@@ -155,11 +90,10 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
  * @param {(b: string) => string} opts.messages.reuse
  * @param {(b: string) => string} opts.messages.fetch
  * @param {(b: string, ref: string) => string} opts.messages.create
- * @param {(b: string) => string} [opts.messages.createRace]  Used when `swallowCreateRace`.
+ * @param {(b: string) => string} [opts.messages.createRace]
  * @param {(b: string, ref: string, stderr: string) => string} opts.messages.createError
  * @param {(b: string, stderr: string) => string} [opts.messages.fetchError]
- *   When provided, a non-zero `fetch` exit throws with this message; when
- *   omitted, the fetch exit status is not inspected.
+ *   When absent, the fetch exit status is not inspected.
  */
 export function seedStoryBranchRef({
   storyBranch,
@@ -193,7 +127,6 @@ export function seedStoryBranchRef({
     return;
   }
 
-  // action === 'create'
   progress('GIT', messages.create(storyBranch, baseRef));
   const r = spawn(['branch', storyBranch, baseRef]);
   if (r.status !== 0) {
@@ -207,9 +140,8 @@ export function seedStoryBranchRef({
 }
 
 /**
- * Check out a Story branch, creating it from `epicBranch` if neither local
- * nor remote exists. Non-destructive: if the branch already exists, this
- * plain-`checkout`s it rather than `-B`-resetting.
+ * Check out a Story branch, creating it from `epicBranch` when absent.
+ * Non-destructive: an existing branch is plain-checked-out, never `-B`-reset.
  *
  * @param {string} storyBranch
  * @param {string} epicBranch
@@ -225,7 +157,6 @@ export async function checkoutStoryBranch(
   assertBranchSafe(storyBranch, epicBranch);
   const progress = opts.progress ?? (() => {});
 
-  // Short-circuit: already on the story branch — just sync.
   if (currentBranch(cwd) === storyBranch) {
     const remote = branchExistsRemotely(storyBranch, cwd);
     if (remote) {
@@ -261,10 +192,8 @@ export async function checkoutStoryBranch(
 }
 
 /**
- * Ensure an arbitrary branch exists locally, creating from `baseBranch` if
- * missing. Used by the dispatcher's task-dispatch path where the expected
- * side-effect is "branch ref exists"; the caller does not want HEAD to
- * move. After creation, HEAD is restored to `baseBranch`.
+ * Ensure a branch ref exists, creating it from `baseBranch`; HEAD is left on
+ * `baseBranch`.
  *
  * @param {string} branchName
  * @param {string} baseBranch