gh-stack 0.16.0 → 0.17.0

package/README.md

@@ -83,6 +83,18 @@ create <branch-name> [--description <desc>]
     Create a new git branch off the current branch and add it to
     the stack. The current branch must already be tracked.
 
+add [branch]
+    Track an EXISTING local branch (default: the current branch) in a
+    stack — without pushing or opening a PR. Walks local ancestry: if the
+    branch sits on top of an existing stack it's adopted into it (parent
+    auto-detected); otherwise a new stack is created from the chain.
+
+    Use this for a WIP branch you've created with `git checkout -b` but
+    aren't ready to submit. It fills the gap between creating a branch and
+    `submit`: until a branch is tracked, `sync`/`restack`/navigation don't
+    know about it, and `add` is how you track it without publishing. (When
+    you do run `submit`, it auto-tracks too — `add` is the no-push path.)
+
 submit [-d|--draft] [-n|--no-edit] [-t|--title <t>] [-b|--body <b>] [--body-file <f>] [--restack] [--dry-run]
     Push all downstack branches to GitHub, create PRs for branches
     that don't have them, number each PR title with its stack position
@@ -168,9 +180,10 @@ sync [--dry-run]
     and conflicting.
 
 merge [--dry-run] [-d|--delete-branch] [--collapse]
-merge --approved [--dry-run] [-d|--delete-branch]
-    Default (top-down collapse): squash-merge the stack top-down via
-    GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
+merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
+merge --base [--dry-run] [-d|--delete-branch]
+    Default (top-down collapse): squash-merge the whole stack top-down
+    via GitHub (PR3 → PR2 → PR1), then enables auto-merge for the base PR
     into main. The whole stack lands on main as a single squash commit.
     All merges happen on GitHub so PRs show as "Merged", Linear tickets
     close automatically, and GitHub Actions fire normally. Skips already-
@@ -181,20 +194,25 @@ merge --approved [--dry-run] [-d|--delete-branch]
     real conflict with main stops the merge (the stack is left intact —
     resolve with `gh-stack sync`, then re-run), while merely waiting on
     pending checks is fine (auto-merge gates on them).
-    --collapse  Stop after collapsing the stack into the base PR;
-                leaves the base PR open against main so you can
-                review the cumulative diff on GitHub. Re-run
-                `gh-stack merge` (without --collapse) to finish.
-
-    --approved (bottom-up, merge what's ready): merge approved PRs from
-    the BOTTOM up, each as its own squash commit on main, and leave the
-    unreviewed tail as a clean stack re-rooted on main. Stops at the
-    first PR that isn't approved. For each approved bottom PR it squash-
-    merges to main, re-roots the next branch onto main (replaying only
-    its own commits), pushes it, and repoints its PR base to main. A PR
-    already merged outside gh-stack is detected and advanced past, not
-    re-merged. For the "merge PRs as they get reviewed, keep stacking
-    the rest" workflow.
+
+    --approved  Collapse only the approved run. Walks approval from the
+                BASE up and stops at the first PR that isn't approved
+                (contiguous — an unapproved PR4 caps the run at PR3 even
+                if PR5 is approved). Collapses base..highest-approved into
+                a single squash commit on main and leaves the unapproved
+                tail in place; after the base PR lands, run `gh-stack sync`
+                to re-root the tail onto main. All approved ⇒ same as a
+                full merge.
+    --base      Squash-merge ONLY the bottom PR into main as its own
+                commit, then re-root the next branch onto main (replaying
+                just its own commits). One PR per run — run it again to
+                land the next. Approval is enforced by GitHub branch
+                protection, not gh-stack. A base PR already merged outside
+                gh-stack is detected and advanced past.
+    --collapse  With the default or --approved, stop after collapsing into
+                the base PR WITHOUT merging it to main, so you can review
+                the cumulative diff on GitHub. Re-run `gh-stack merge` to
+                finish. Alias: --stop-at-base.
 
 split [<branch>] [--name <name>]
     Cut a stack into two at <branch>. The cut branch and every branch
@@ -462,8 +480,12 @@ gh-stack status
 # When the whole stack is approved, merge it down as one squash commit
 gh-stack merge       # squash-merges down, pushes, enables auto-merge
 
-# Or: merge PRs as they get approved, bottom-up, keep stacking the rest
-gh-stack merge --approved   # merges approved bottom PRs, re-roots the tail on main
+# Or: only the approved part is ready — collapse the approved run into one
+# commit and leave the rest stacked (re-root the tail later with `sync`)
+gh-stack merge --approved   # collapses base..highest-approved → main, keeps the tail
+
+# Or: land just the bottom PR, one at a time
+gh-stack merge --base       # merges the bottom PR → main, re-roots the next
 
 # Or: collapse first to review the cumulative diff before shipping
 gh-stack merge --collapse   # squash-merges PRn..PR2 into PR1, stops there

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gh-stack",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Stacked PR manager for squash-merge workflows",
   "author": "Kiliman <kiliman@gmail.com>",
   "license": "MIT",

package/src/commands/add.ts

@@ -0,0 +1,107 @@
+// gh-stack add — register an existing local branch into a stack (no push, no PR).
+//
+// Fills the gap between `git checkout -b <wip>` and `submit`: it tracks the
+// branch (and any untracked ancestors) in the right stack by walking local
+// ancestry, so `sync` / `restack` / navigation work BEFORE you're ready to open
+// a PR. Network-free — nothing is pushed and no PR is created. That's the whole
+// point: `submit` is the command that publishes; `add` only updates metadata.
+//
+// Resolves the "catch-22" where a local WIP tip couldn't be synced because it
+// wasn't in a stack, and the only way into a stack was `submit` (which pushes).
+import * as p from "../lib/output.ts";
+import pc from "picocolors";
+import * as git from "../lib/git.ts";
+import { gateLegacyMetadata } from "../lib/safety.ts";
+import { readMetadata, writeMetadata, findStackForBranch, stackBase } from "../lib/metadata.ts";
+import { resolveOrCreateStack } from "../lib/chain.ts";
+import type { StackMetadata } from "../types.ts";
+
+export default async function add(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack add — track an existing local branch in a stack (no push, no PR)
+
+USAGE
+  gh-stack add [branch]
+
+Registers the branch (default: the current branch) into a stack so sync,
+restack, and navigation work before you've submitted it. Walks local ancestry:
+if the branch sits on top of an existing stack it's adopted into that stack;
+otherwise a new stack is created from the chain, rooted at the trunk.
+
+Network-free — nothing is pushed and no PR is opened. Run ${"`"}gh-stack submit${"`"} when
+you're ready to publish.
+
+EXAMPLES
+  gh-stack add                    Track the current branch
+  gh-stack add my-wip-branch      Track a specific local branch
+`);
+    return;
+  }
+
+  await gateLegacyMetadata();
+
+  const positional = args.find((a) => !a.startsWith("-"));
+  const branch = positional ?? (await git.currentBranch());
+
+  if (!(await git.localBranchExists(branch))) {
+    p.cancel(`Branch ${pc.yellow(branch)} doesn't exist locally.`);
+    process.exit(1);
+  }
+
+  const trunk = await git.trunkBranch();
+  if (branch === trunk || branch === "main" || branch === "master") {
+    p.cancel(
+      `${pc.yellow(branch)} is the trunk — nothing to add.\n\n  Checkout a feature branch first.`,
+    );
+    process.exit(1);
+  }
+
+  // submit self-heals from an empty store, so a missing metadata file is fine —
+  // resolveOrCreateStack will create the first stack from local ancestry.
+  const meta: StackMetadata = (await readMetadata()) ?? {
+    version: 2,
+    current_stack: null,
+    stacks: {},
+  };
+
+  const already = findStackForBranch(meta, branch);
+  if (already) {
+    p.log.info(`${pc.yellow(branch)} is already tracked in stack ${pc.yellow(already)}.`);
+    return;
+  }
+
+  let resolution;
+  try {
+    resolution = await resolveOrCreateStack(meta, branch, trunk);
+  } catch (err) {
+    p.cancel((err as Error).message);
+    process.exit(1);
+  }
+
+  meta.current_stack = resolution.stackName;
+  await writeMetadata(meta);
+
+  p.intro(pc.cyan("Add to Stack"));
+
+  const stack = meta.stacks[resolution.stackName]!;
+  const base = stackBase(stack);
+  const baseNote = base === "main" || base === "master" ? "" : ` ${pc.dim(`(base: ${base})`)}`;
+
+  if (resolution.created) {
+    p.log.success(
+      `Created stack ${pc.yellow(resolution.stackName)} from ${resolution.addedBranches.length} local branch(es)${baseNote}`,
+    );
+  } else {
+    p.log.success(
+      `Added ${resolution.addedBranches.length} branch(es) to ${pc.yellow(resolution.stackName)}${baseNote}`,
+    );
+  }
+  for (const b of resolution.addedBranches) {
+    console.log(`  ${pc.green("+")} ${b}`);
+  }
+
+  p.outro(
+    `Tracked — ${pc.green("gh-stack sync")}/${pc.green("restack")} now work. ${pc.dim("Run")} ${pc.green("gh-stack submit")} ${pc.dim("to open PRs.")}`,
+  );
+}

package/src/commands/bottom.ts

@@ -3,7 +3,7 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getOrderedBranches, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function bottom(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -43,7 +43,7 @@ Switches to the bottom-most branch of the current stack
     return;
   }
 
-  await git.checkout(target);
+  await checkoutOrExit(target);
 
   // Update tracking
   stack.last_branch = target;

package/src/commands/checkout.ts

@@ -3,7 +3,7 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { writeMetadata, getOrderedBranches, findStackForBranch } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 import { selectBranch, selectStack } from "../lib/ui.ts";
 
 export default async function checkout(args: string[]): Promise<void> {
@@ -45,20 +45,21 @@ TIP
       process.exit(0);
     }
 
-    // Update current_stack
-    meta.current_stack = stackName;
-    await writeMetadata(meta);
-
-    // Checkout last branch in stack
+    // Checkout the stack's last branch FIRST — only persist current_stack once
+    // the switch actually lands, so a refused checkout (e.g. dirty tree) leaves
+    // metadata pointing at the stack we're still on rather than the target.
     const stack = meta.stacks[stackName]!;
     const lastBranch = stack.last_branch;
 
     if (lastBranch && lastBranch !== currentBranch) {
       p.log.info(`Switching to stack ${pc.yellow(stackName)}`);
       p.log.info(`Checking out ${pc.yellow(lastBranch)}`);
-      await git.checkout(lastBranch);
+      await checkoutOrExit(lastBranch);
     }
 
+    meta.current_stack = stackName;
+    await writeMetadata(meta);
+
     p.outro(pc.green(`Switched to stack ${pc.yellow(stackName)}`));
   } else {
     // ── Branch switching ──
@@ -105,7 +106,7 @@ TIP
     }
 
     p.log.info(`Switching to ${pc.yellow(targetBranch)}`);
-    await git.checkout(targetBranch);
+    await checkoutOrExit(targetBranch);
 
     // Update last_branch
     stack.last_branch = targetBranch;

package/src/commands/down.ts

@@ -3,7 +3,7 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, stackBase, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function down(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -64,7 +64,7 @@ OPTIONS
     moved++;
   }
 
-  await git.checkout(currentBranch);
+  await checkoutOrExit(currentBranch);
 
   // Update tracking
   stack.last_branch = currentBranch;

package/src/commands/merge.ts

@@ -14,7 +14,12 @@ import { ensureMetadata, ensureCleanWorkingTree, ensureValidStack } from "../lib
 import { takeSnapshot } from "../lib/snapshot.ts";
 import { getBranchRefSha, getPrInfo, getPrMergeState, resyncPrHead } from "../lib/github.ts";
 import { confirmAction } from "../lib/ui.ts";
-import { planMerges, advanceNewBottom, type BranchReview } from "../lib/advance.ts";
+import {
+  planMerges,
+  advanceNewBottom,
+  type BranchReview,
+  type MergeAction,
+} from "../lib/advance.ts";
 
 const MAX_RETRIES = 12;
 const RETRY_DELAY_MS = 5000;
@@ -234,57 +239,63 @@ export default async function merge(args: string[]): Promise<void> {
   const deleteFlag = args.includes("--delete-branch") || args.includes("-d");
   const collapse = args.includes("--collapse") || args.includes("--stop-at-base");
   const approved = args.includes("--approved");
+  const baseOnly = args.includes("--base");
 
   if (args.includes("--help")) {
     console.log(`
-gh-stack merge — Squash-merge stack via GitHub
+gh-stack merge — Squash-merge a stack via GitHub
 
 USAGE
   gh-stack merge [--dry-run] [-d|--delete-branch] [--collapse]
-  gh-stack merge --approved [--dry-run] [-d|--delete-branch]
+  gh-stack merge --approved [--collapse] [--dry-run] [-d|--delete-branch]
+  gh-stack merge --base [--dry-run] [-d|--delete-branch]
 
 DEFAULT (top-down collapse)
-  Squash-merges the stack from top to bottom via GitHub:
+  Squash-merges the whole stack from top to bottom via GitHub:
     PR3 → squash into PR2, PR2 → squash into PR1, PR1 → auto-merge into main.
   The whole stack lands on main as a single squash commit.
 
---approved (bottom-up, merge what's ready)
-  Merges approved PRs from the BOTTOM of the stack up, each as its own
-  squash commit on main, and leaves the unreviewed tail as a clean stack
-  re-rooted on main. Stops at the first PR that isn't approved. For the
-  "merge PRs as they get reviewed, keep stacking the rest" workflow.
-
-  For each approved bottom PR it: squash-merges to main, re-roots the next
-  branch onto main (replaying only its own commits — no replay of the
-  squashed work), pushes it, and repoints its PR base to main. A PR already
-  merged outside gh-stack is detected and advanced past, not re-merged.
-
-All merges happen on GitHub, so PRs show as "Merged", Linear tickets
-close automatically, and all GitHub Actions/webhooks fire normally.
-
-Skips PRs that are already merged (safe to re-run after partial failure).
-Waits for GitHub to process between merges, and self-heals GitHub's
-spurious "Head branch is out of date" (a stale PR head pointer after a
-child squash) by re-syncing the branch and retrying — only a genuine
-conflict or failing required check is reported as a hard failure.
+--approved (collapse the approved run)
+  Like the default collapse, but only as far up as the stack is approved.
+  Walks approval from the BASE up and stops at the first PR that isn't
+  approved — contiguous, so an unapproved PR4 caps the run at PR3 even if
+  PR5 is approved. Collapses base..highest-approved into a single squash
+  commit on main and leaves the unapproved tail in place. After the base PR
+  lands, run ${pc.green("gh-stack sync")} to re-root the tail onto main. All approved ⇒
+  identical to a full merge.
+
+--base (merge just the bottom PR)
+  Squash-merges only the bottom PR into main as its own commit, then re-roots
+  the next branch onto main. One PR per run — run it again to land the next.
+  Approval is enforced by GitHub branch protection, not gh-stack.
+
+--collapse (stop before main)
+  With the default or --approved, stop after collapsing into the base PR
+  WITHOUT merging it to main — review the cumulative diff on GitHub, then
+  re-run ${pc.green("gh-stack merge")} to finish. Alias: --stop-at-base.
+
+All merges happen on GitHub, so PRs show as "Merged", Linear tickets close
+automatically, and Actions/webhooks fire normally. Already-merged PRs are
+skipped (safe to re-run after a partial failure), and a spurious "Head branch
+is out of date" (a stale PR head pointer after a child squash) self-heals by
+re-syncing and retrying — only a genuine conflict or failing required check is
+a hard failure.
 
 A snapshot is taken first; ${pc.green("gh-stack undo")} restores the prior state.
 
 OPTIONS
   -d, --delete-branch  Delete remote branches after merging
-      --approved       Merge approved PRs bottom-up; leave the rest as PRs
+      --approved       Collapse only the approved run (from the base up)
+      --base           Merge just the bottom PR into main, re-root the next
+      --collapse       Stop after collapsing into the base PR (don't merge to
+                       main); alias: --stop-at-base
       --dry-run        Show what would happen without doing anything
-      --collapse       Stop after collapsing the stack into the base PR;
-                       do NOT merge base PR into main. Lets you review the
-                       cumulative diff on GitHub first. Re-run ${pc.green("gh-stack merge")}
-                       (without --collapse) to finish the job.
-      --stop-at-base   Alias for --collapse
 `);
     return;
   }
 
-  if (approved) {
-    await mergeApproved(deleteFlag, dryRun);
+  if (baseOnly) {
+    await mergeBaseOnly(deleteFlag, dryRun);
     return;
   }
 
@@ -314,17 +325,63 @@ OPTIONS
     process.exit(1);
   }
 
-  if (ordered.length <= 1) {
-    // Single branch — just enable auto-merge
-    const basePr = stack.branches[ordered[0]!]?.pr;
+  // ── Determine the collapse range ──
+  // Default: the whole stack. --approved: only the contiguous-from-base
+  // APPROVED run — the first unapproved PR is the ceiling. The unapproved tail
+  // is left in place and re-rooted by a later `gh-stack sync` once the base PR
+  // lands on main (approach A — no CI blocking). All approved ⇒ whole stack.
+  let rangeOrdered = ordered;
+  let tail: string[] = [];
+  if (approved) {
+    const reviewSpinner = p.spinner();
+    reviewSpinner.start("Checking PR review status...");
+    // Fetch every branch's review state concurrently — sequential `gh` calls
+    // add up fast on a deep stack.
+    const reviews: BranchReview[] = await Promise.all(
+      ordered.map(async (branch) => {
+        const pr = stack.branches[branch]?.pr ?? null;
+        if (pr == null) return { branch, pr: null, prState: null, reviewDecision: null };
+        const info = await getPrInfo(pr);
+        return {
+          branch,
+          pr,
+          prState: info?.state ?? null,
+          reviewDecision: info?.reviewDecision ?? null,
+        };
+      }),
+    );
+    reviewSpinner.stop("Review status checked");
+
+    // planMerges walks bottom-up over the contiguous run of approved (or
+    // already-merged) branches, stopping at the first that isn't approved.
+    const plan = planMerges(reviews, { approveAndMerge: true });
+    if (plan.steps.length === 0) {
+      p.cancel(
+        `Nothing approved to merge — the base PR isn't approved yet${plan.stop ? ` (${plan.stop.reason})` : ""}.\n\n` +
+          `  Approval is taken contiguously from the base, so the bottom PR must be approved first.`,
+      );
+      return;
+    }
+    rangeOrdered = ordered.slice(0, plan.steps.length);
+    tail = ordered.slice(plan.steps.length);
+  }
+
+  if (rangeOrdered.length <= 1) {
+    // Only the base PR is in range (single-branch stack, or --approved with just
+    // the bottom approved). Nothing to collapse — enable auto-merge on the base.
+    const basePr = stack.branches[rangeOrdered[0]!]?.pr;
     if (collapse) {
       p.log.info(
-        `Single-branch stack — nothing to collapse. The base PR${basePr ? ` (#${basePr})` : ""} already targets main.`,
+        `Nothing to collapse — the base PR${basePr ? ` (#${basePr})` : ""} already targets main.`,
       );
       return;
     }
     if (basePr) {
-      p.log.info("Single branch stack — enabling auto-merge on GitHub.");
+      p.log.info(
+        tail.length > 0
+          ? `Base PR (#${basePr}) is approved — enabling auto-merge on GitHub.`
+          : "Single branch stack — enabling auto-merge on GitHub.",
+      );
       if (!dryRun) {
         try {
           await $`gh pr merge ${basePr} --squash --auto`.quiet();
@@ -336,11 +393,24 @@ OPTIONS
     } else {
       p.log.info("Single branch stack — merge via GitHub as normal.");
     }
+    if (tail.length > 0 && !dryRun) {
+      console.log();
+      p.log.info(
+        `${tail.length} unapproved branch(es) left in place. After PR #${basePr} lands, run ${pc.green("gh-stack sync")} to re-root them onto main.`,
+      );
+    }
     return;
   }
 
   p.intro(pc.cyan(collapse ? "Stack Collapse (via GitHub)" : "Stack Merge (via GitHub)"));
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
+  if (approved) {
+    p.log.info(
+      pc.dim(
+        `--approved: collapsing the ${rangeOrdered.length} approved branch(es) from the base up.`,
+      ),
+    );
+  }
   if (collapse) {
     p.log.info(
       pc.dim("--collapse: will stop after collapsing into base PR; base will NOT merge to main."),
@@ -348,9 +418,10 @@ OPTIONS
   }
   console.log();
 
-  // Check PR states and build the merge plan
-  const reversed = ordered.toReversed();
-  const baseBranch = ordered[0]!;
+  // Check PR states and build the merge plan — scoped to the collapse RANGE
+  // (the whole stack by default, the approved run under --approved).
+  const reversed = rangeOrdered.toReversed();
+  const baseBranch = rangeOrdered[0]!;
   const basePr = stack.branches[baseBranch]?.pr;
 
   console.log(`  ${pc.bold("Merge plan:")}`);
@@ -377,15 +448,17 @@ OPTIONS
       `    ${pc.blue(baseBranch)}${basePr ? ` (#${basePr})` : ""} → ${pc.green("main")} (auto-merge)`,
     );
   }
-  console.log();
-
-  if (dryRun) {
-    p.outro(pc.yellow("[DRY RUN] No changes made"));
-    return;
+  if (tail.length > 0) {
+    console.log(
+      `    ${pc.dim(`⏹ ${tail.length} unapproved branch(es) above left in place → re-root with `)}${pc.green("gh-stack sync")}${pc.dim(" after the base lands")}`,
+    );
   }
+  console.log();
 
-  // Check all PRs in stack have PR numbers
-  const missingPrs = ordered.filter((b) => !stack.branches[b]?.pr);
+  // Every PR in the collapse RANGE must have a number (tail branches aren't
+  // being merged now, so a local-only tip there is fine). Validate before the
+  // dry-run exit so previews surface the same blocker as a real merge.
+  const missingPrs = rangeOrdered.filter((b) => !stack.branches[b]?.pr);
   if (missingPrs.length > 0) {
     p.cancel(
       `Missing PR numbers for: ${missingPrs.join(", ")}\n\n  Run ${pc.green("gh-stack submit")} first to create PRs.`,
@@ -393,6 +466,11 @@ OPTIONS
     process.exit(1);
   }
 
+  if (dryRun) {
+    p.outro(pc.yellow("[DRY RUN] No changes made"));
+    return;
+  }
+
   const confirmed = await confirmAction(
     collapse
       ? "Collapse stack top-down via GitHub (stop at base PR)?"
@@ -633,6 +711,20 @@ OPTIONS
     pullSpinner.stop(pc.dim("Could not sync local branches — run git pull manually"));
   }
 
+  // --approved with an unapproved tail: the base PR is auto-merging the approved
+  // run as one commit, but branches remain. DON'T archive — leave the stack so
+  // `gh-stack sync` can re-root the tail onto main once the base lands (it
+  // detects the merged bottom and advances past it). (approach A)
+  if (tail.length > 0) {
+    p.outro(
+      pc.green(
+        `Approved run collapsed into PR #${basePr} → auto-merging to main. ` +
+          `After it lands, run \`gh-stack sync\` to re-root the ${tail.length} remaining branch(es).`,
+      ),
+    );
+    return;
+  }
+
   // Archive the stack
   if (!meta.archive) meta.archive = {};
   meta.archive[stackName] = { ...stack };
@@ -649,17 +741,13 @@ OPTIONS
 }
 
 /**
- * `gh-stack merge --approved` — merge approved PRs from the bottom of the stack
- * up, each as its own squash commit on main, advancing the rest of the stack
- * onto main as it goes. Stops at the first PR that isn't approved, leaving the
- * unreviewed tail as a clean stack re-rooted on main.
- *
- * The cascade is interleaved by necessity: each PR must be rebased off the
- * just-merged commits and pushed before the next one can merge cleanly, so we
- * merge → advance → merge → advance one branch at a time (see ./lib/advance.ts
- * for the re-root mechanics and fork-point resolution).
+ * `gh-stack merge --base` — squash-merge ONLY the bottom PR into main, then
+ * re-root the next branch onto main (replaying just its own commits, via
+ * advance.ts's fork-point resolution). One PR per run — run it again to land the
+ * next. Approval is NOT checked here; GitHub branch protection enforces it.
+ * A base PR already merged outside gh-stack is detected and advanced past.
  */
-async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void> {
+async function mergeBaseOnly(deleteFlag: boolean, dryRun: boolean): Promise<void> {
   // We rebase the surviving branches, so the same pre-flight guards as restack.
   if (await git.isRebaseInProgress()) {
     p.cancel(
@@ -699,62 +787,50 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
   const trunk = base;
   const targetRef = `origin/${trunk}`;
 
-  p.intro(pc.cyan("Merge Approved (bottom-up, via GitHub)"));
+  p.intro(pc.cyan("Merge Base PR (via GitHub)"));
   p.log.info(`Stack: ${pc.yellow(stackName)}`);
 
-  // Gather each branch's PR review state, bottom-up.
-  const reviewSpinner = p.spinner();
-  reviewSpinner.start("Checking PR review status...");
-  const reviews: BranchReview[] = [];
-  for (const branch of ordered) {
-    const pr = stack.branches[branch]?.pr ?? null;
-    let prState: string | null = null;
-    let reviewDecision: string | null = null;
-    if (pr != null) {
-      const info = await getPrInfo(pr);
-      prState = info?.state ?? null;
-      reviewDecision = info?.reviewDecision ?? null;
-    }
-    reviews.push({ branch, pr, prState, reviewDecision });
+  const baseBranch = ordered[0]!;
+  const basePr = stack.branches[baseBranch]?.pr ?? null;
+  if (basePr == null) {
+    p.cancel(
+      `Base branch ${pc.yellow(baseBranch)} has no PR.\n\n  Open it with ${pc.green("gh-stack submit")} first.`,
+    );
+    process.exit(1);
   }
-  reviewSpinner.stop("Review status checked");
 
-  const plan = planMerges(reviews, { approveAndMerge: true });
+  // Only the bottom PR is merged. If it already landed (e.g. via the GitHub UI),
+  // advance the stack past it instead of re-merging.
+  const baseState = await getPrMergeState(basePr);
+  const baseAction: MergeAction = baseState?.state === "MERGED" ? "advance-only" : "merge";
+  const plan = { steps: [{ branch: baseBranch, pr: basePr, action: baseAction }] };
+  const nextChild = ordered[1] ?? null;
 
-  // Show the plan.
   console.log();
   console.log(`  ${pc.bold("Plan:")}`);
-  for (const step of plan.steps) {
-    const label =
-      step.action === "advance-only"
+  console.log(
+    `    ${pc.yellow(baseBranch)} (#${basePr}) → ${
+      baseAction === "advance-only"
         ? pc.dim("already merged — advance past")
-        : `${pc.green("squash-merge")} → ${pc.green(trunk)}`;
-    console.log(`    ${pc.yellow(step.branch)}${step.pr ? ` (#${step.pr})` : ""} → ${label}`);
-  }
-  if (plan.stop) {
+        : `${pc.green("squash-merge")} → ${pc.green(trunk)}`
+    }`,
+  );
+  if (nextChild) {
     console.log(
-      `    ${pc.dim("⏹")} stop at ${pc.yellow(plan.stop.branch)} ${pc.dim(`(${plan.stop.reason}) — left as a stack on ${trunk}`)}`,
+      `    ${pc.dim(`then re-root ${nextChild} onto ${trunk} — the rest stays a stack`)}`,
     );
   }
   console.log();
 
-  const mergeSteps = plan.steps.filter((s) => s.action === "merge");
-  if (mergeSteps.length === 0 && !plan.steps.some((s) => s.action === "advance-only")) {
-    p.outro(
-      plan.stop
-        ? pc.yellow(`Nothing approved to merge — bottom PR is ${plan.stop.reason}.`)
-        : pc.yellow("Nothing to merge."),
-    );
-    return;
-  }
-
   if (dryRun) {
     p.outro(pc.yellow("[DRY RUN] No changes made"));
     return;
   }
 
   const confirmed = await confirmAction(
-    `Merge ${mergeSteps.length} approved PR(s) bottom-up into ${trunk} and re-root the rest?`,
+    nextChild
+      ? `Merge base PR #${basePr} into ${trunk} and re-root ${nextChild}?`
+      : `Merge base PR #${basePr} into ${trunk}?`,
   );
   if (!confirmed) {
     p.cancel("Cancelled");
@@ -763,7 +839,7 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
 
   // Snapshot first — this records every branch's pre-merge tip, which both the
   // fork-point resolver and `gh-stack undo` rely on.
-  await takeSnapshot(meta, stackName, "merge-approved");
+  await takeSnapshot(meta, stackName, "merge-base");
   // Keep a copy of the original topology to archive if the stack fully drains.
   const originalStack = structuredClone(stack);
 
@@ -797,7 +873,7 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
       if (!ready) {
         s.stop(pc.red(`PR #${prNum} is not mergeable`));
         p.log.info("Check the PR on GitHub for merge conflicts or required checks.");
-        p.log.info("Re-run with --approved to continue from where you left off.");
+        p.log.info("Re-run `gh-stack merge --base` to continue.");
         process.exit(2);
       }
 
@@ -813,7 +889,7 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
             ? "Real conflict or failing required check — resolve it on GitHub."
             : "GitHub's mergeability recompute didn't settle (transient lag).",
         );
-        p.log.info("Re-run with --approved to continue from where you left off.");
+        p.log.info("Re-run `gh-stack merge --base` to continue.");
         process.exit(2);
       }
     } else {
@@ -882,7 +958,7 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
     if (meta.current_stack === stackName) meta.current_stack = null;
     await writeMetadata(meta);
 
-    p.outro(pc.green("All approved PRs merged — stack drained & archived."));
+    p.outro(pc.green(`Base PR #${basePr} merged — stack drained & archived.`));
     return;
   }
 
@@ -902,7 +978,7 @@ async function mergeApproved(deleteFlag: boolean, dryRun: boolean): Promise<void
 
   p.outro(
     pc.green(
-      `Merged ${mergeSteps.length} approved PR(s); ${remaining.length} branch(es) left as a stack on ${trunk}.`,
+      `Merged base PR #${basePr} into ${trunk}; ${remaining.length} branch(es) left as a stack.`,
     ),
   );
 }

package/src/commands/restack.ts

@@ -109,7 +109,7 @@ ALIASES
   // origin. Fail loudly (listing the stale ones) rather than reporting success
   // when a push didn't take. (#12)
   if (!dryRun) {
-    const stale = await findStaleRefs(touched);
+    const stale = await findStaleRefs(touched, meta);
     if (stale.length > 0) {
       console.log();
       p.log.error("Some branch refs are NOT in sync with origin:");
@@ -139,9 +139,15 @@ ALIASES
  * this pass report a false "un-pushed ref" and exit non-zero after a fully
  * successful run (#23). Reading the real remote state makes the signal
  * trustworthy in both directions: a genuinely un-pushed ref is still caught.
+ *
+ * A branch absent from origin is only flagged when it has a PR (it was
+ * published and should be there). A local-only branch with no PR is
+ * intentionally absent — restack/sync don't publish it — so it's not a stale
+ * ref and must not fail the run. (#24)
  */
 export async function findStaleRefs(
   branches: string[],
+  meta: StackMetadata,
 ): Promise<{ branch: string; local: string; remote: string }[]> {
   const stale: { branch: string; local: string; remote: string }[] = [];
   const seen = new Set<string>();
@@ -153,7 +159,10 @@ export async function findStaleRefs(
     const local = await git.revParse(branch);
     const remote = remoteHeads.get(branch);
     if (!remote) {
-      stale.push({ branch, local, remote: "(missing)" });
+      // Missing from origin is only a problem for a published branch.
+      if (branchHasPr(meta, branch)) {
+        stale.push({ branch, local, remote: "(missing)" });
+      }
       continue;
     }
     if (remote !== local) {
@@ -209,7 +218,7 @@ async function handleResume(
   await clearRestackState();
 
   // Prompt to push the resumed branch
-  await pushBranchRef(expectedBranch);
+  await pushBranchRef(meta, expectedBranch);
 
   // Continue with remaining branches in chain
   const stackName = state.stack_name;
@@ -297,7 +306,7 @@ async function handleFreshRestack(
       for (const baseBranch of baseBranches) {
         if (await git.localBranchExists(baseBranch)) {
           touched.push(baseBranch);
-          await pushBranchRef(baseBranch);
+          await pushBranchRef(meta, baseBranch);
         }
       }
     }
@@ -348,7 +357,9 @@ async function handleReroot(
   const stackName = findStackForBranch(meta, currentBranch);
 
   if (!stackName) {
-    p.cancel(`Branch ${pc.blue(currentBranch)} is not in any stack.`);
+    p.cancel(
+      `Branch ${pc.blue(currentBranch)} is not in any stack.\n\n  Track it first (no push/PR):\n    ${pc.green("gh-stack add")}`,
+    );
     process.exit(1);
   }
 
@@ -439,7 +450,7 @@ async function handleReroot(
 
   rebasedBranches.push(root);
   touched.push(root);
-  await pushBranchRef(root);
+  await pushBranchRef(meta, root);
 
   // Restack the children onto the moved root.
   const children = ordered.slice(1);
@@ -485,7 +496,7 @@ async function processChain(
       p.log.success("Already up to date with parent");
       if (!dryRun) {
         touched.push(branch);
-        await pushBranchRef(branch);
+        await pushBranchRef(meta, branch);
       }
       continue;
     }
@@ -583,7 +594,7 @@ async function processChain(
 
       // Push immediately (don't batch) so an interrupt can't leave later
       // branches un-pushed.
-      await pushBranchRef(branch);
+      await pushBranchRef(meta, branch);
     } else {
       // Conflict!
       console.log();
@@ -609,11 +620,36 @@ async function processChain(
  * differs from origin OR the remote branch doesn't exist yet (so a branch
  * that was never pushed still lands). No-op when already in sync. (#12)
  */
-async function pushBranchRef(branch: string): Promise<void> {
+/**
+ * Whether a branch has been published — it has a PR recorded in metadata.
+ * restack/sync keep published branches' remotes in sync after a rebase, but must
+ * NOT create a remote for an unpublished, local-only branch — publishing is
+ * `submit`'s job, not a side effect of restacking. (#24)
+ */
+function branchHasPr(meta: StackMetadata, branch: string): boolean {
+  const stackName = findStackForBranch(meta, branch);
+  if (!stackName) return false;
+  return meta.stacks[stackName]?.branches[branch]?.pr != null;
+}
+
+async function pushBranchRef(meta: StackMetadata, branch: string): Promise<void> {
   if (branch === "main" || branch === "master") return;
 
   const localSha = await git.revParse(branch);
   const hasRemote = await git.remoteBranchExists(branch);
+
+  // Don't publish an unsubmitted branch. A local-only branch (no remote AND no
+  // PR) is intentionally not on origin — restack/sync rebase it locally but
+  // leave pushing to `submit`. Skip with a note rather than creating its remote
+  // (the #24 surprise: `--yes` silently published a WIP tip). A branch that
+  // already has a remote or a PR still gets pushed below to stay in sync.
+  if (!hasRemote && !branchHasPr(meta, branch)) {
+    p.log.info(
+      `Skipping push of ${pc.yellow(branch)} — local-only (not submitted). Run ${pc.green("gh-stack submit")} to open its PR.`,
+    );
+    return;
+  }
+
   const remoteSha = hasRemote ? await git.revParse(`origin/${branch}`).catch(() => null) : null;
 
   if (hasRemote && remoteSha === localSha) return; // already in sync — nothing to do

package/src/commands/sync.ts

@@ -52,7 +52,9 @@ with the base branch included.
   const stackName = findStackForBranch(meta, currentBranch);
 
   if (!stackName) {
-    p.cancel(`Branch ${pc.blue(currentBranch)} not found in any stack`);
+    p.cancel(
+      `Branch ${pc.blue(currentBranch)} is not in any stack.\n\n  Track it first (no push/PR):\n    ${pc.green("gh-stack add")}\n\n  Or open its PR with:\n    ${pc.green("gh-stack submit")}`,
+    );
     process.exit(1);
   }
 

package/src/commands/top.ts

@@ -8,7 +8,7 @@ import {
   getChildren,
   writeMetadata,
 } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function top(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -68,7 +68,7 @@ Prompts if there are multiple leaf branches.
     return;
   }
 
-  await git.checkout(target);
+  await checkoutOrExit(target);
 
   // Update tracking
   stack.last_branch = target;

package/src/commands/up.ts

@@ -3,7 +3,7 @@ import * as p from "../lib/output.ts";
 import pc from "picocolors";
 import * as git from "../lib/git.ts";
 import { findStackForBranch, getChildren, writeMetadata } from "../lib/metadata.ts";
-import { ensureMetadata } from "../lib/safety.ts";
+import { ensureMetadata, checkoutOrExit } from "../lib/safety.ts";
 
 export default async function up(args: string[]): Promise<void> {
   if (args.includes("--help")) {
@@ -71,7 +71,7 @@ OPTIONS
     currentBranch = target;
   }
 
-  await git.checkout(currentBranch);
+  await checkoutOrExit(currentBranch);
 
   // Update tracking
   stack.last_branch = currentBranch;

package/src/index.ts

@@ -69,6 +69,10 @@ switch (command) {
     await (await import("./commands/create.ts")).default(commandArgs);
     break;
 
+  case "add":
+    await (await import("./commands/add.ts")).default(commandArgs);
+    break;
+
   case "delete":
     await (await import("./commands/delete.ts")).default(commandArgs);
     break;
@@ -178,6 +182,7 @@ ${bold("TERMS")}
 ${bold("CORE WORKFLOW")}
   ${green("init")}           Create a new stack from the current branch
   ${green("create")}         Create a new branch and add to the stack
+  ${green("add")}            Track the current local branch in a stack ${dim("(no push/PR)")}
   ${green("submit")}         Push branches and create/update PRs
   ${green("log")}            Display current stack tree ${dim("(default)")}
 

package/src/lib/git.ts

@@ -86,12 +86,25 @@ export async function isRebaseInProgress(): Promise<boolean> {
 }
 
 /**
- * Checkout a branch.
+ * Checkout a branch. Throws a raw ShellError on failure — only use this where a
+ * failure is unexpected (e.g. after ensureCleanWorkingTree). For user-facing
+ * branch switching, prefer tryCheckout so a dirty-tree refusal can be rendered
+ * as a clean message instead of a stack trace.
  */
 export async function checkout(branch: string): Promise<void> {
   await $`git checkout ${branch}`.quiet();
 }
 
+/**
+ * Attempt to checkout a branch without throwing. Returns whether it succeeded
+ * and git's stderr (which carries the "local changes would be overwritten"
+ * message and the offending file list when a dirty tree blocks the switch).
+ */
+export async function tryCheckout(branch: string): Promise<{ ok: boolean; stderr: string }> {
+  const { exitCode, stderr } = await $`git checkout ${branch}`.quiet().nothrow();
+  return { ok: exitCode === 0, stderr: stderr.toString() };
+}
+
 /**
  * Create and checkout a new branch from the current HEAD.
  */

package/src/lib/safety.ts

@@ -115,6 +115,37 @@ export async function ensureCleanWorkingTree(): Promise<void> {
   }
 }
 
+/**
+ * Switch branches for a user-facing navigation command, rendering a clean
+ * message (and exiting 1) when git refuses — most commonly because local
+ * changes would be overwritten. Avoids leaking a raw ShellError stack trace.
+ *
+ * Note: this deliberately does NOT pre-check for a clean tree. git happily
+ * carries uncommitted changes across a switch when they don't conflict with the
+ * target branch, and stack navigation often wants to bring WIP along — so we
+ * let git decide and only intervene on an actual refusal.
+ */
+export async function checkoutOrExit(branch: string): Promise<void> {
+  const { ok, stderr } = await git.tryCheckout(branch);
+  if (ok) return;
+
+  if (stderr.includes("would be overwritten by checkout")) {
+    const files = stderr
+      .split("\n")
+      .filter((line) => line.startsWith("\t"))
+      .map((line) => `    ${pc.yellow(line.trim())}`)
+      .join("\n");
+    p.cancel(
+      `Can't switch to ${pc.yellow(branch)} — local changes would be overwritten:\n\n${files}\n\n  Commit or stash them first:\n    ${pc.green("git stash")} ${pc.dim("(or git commit)")}`,
+    );
+  } else {
+    p.cancel(
+      `Can't switch to ${pc.yellow(branch)}:\n\n  ${stderr.trim() || "git checkout failed"}`,
+    );
+  }
+  process.exit(1);
+}
+
 /**
  * Ensure we're not on main.
  */

package/src/lib/using-gh-stack.md

@@ -89,6 +89,21 @@ gh-stack create kiliman/third-WEB-9012     # stack another
 
 `init` options: `--name <stack>`, `--parent <trunk>`, `--description <text>`.
 
+**Track a local WIP branch without publishing it — `gh-stack add`.** If you
+created a branch with `git checkout -b` and want to `sync`/`restack` it _before_
+opening a PR, `add` registers it in a stack (network-free — no push, no PR):
+
+```bash
+gh-stack add           # track the current branch
+gh-stack add <branch>  # track a named branch
+```
+
+It walks local ancestry: a branch sitting on top of an existing stack is adopted
+into it (parent auto-detected); otherwise a new stack is created from the chain.
+This resolves the catch-22 where `sync`/`restack` said "not in any stack" for a
+tip you hadn't submitted yet. (`submit` still auto-tracks too — `add` is just the
+no-publish path.)
+
 ### 2. Push & create PRs — `submit`
 
 `submit` is the workhorse: **idempotent, scope-aware, self-healing**. It pushes
@@ -183,16 +198,27 @@ gh-stack status --json     # structured, for agents
 ### 6. Merge & ship
 
 ```bash
-gh-stack merge             # top-down: collapse stack into one squash commit → trunk
-gh-stack merge --approved  # bottom-up: merge approved PRs (each its own commit),
-                           # re-root the unreviewed tail, leave it as a clean stack
+gh-stack merge             # collapse the WHOLE stack into one squash commit → trunk
+gh-stack merge --approved  # collapse only the approved run (base..highest-approved)
+                           # into one commit; leave the unapproved tail in place
+gh-stack merge --base      # land ONLY the bottom PR → trunk, re-root the next branch
 gh-stack merge --dry-run
 ```
 
-- **`merge`** (top-down): the whole stack is approved → lands as a unit.
-- **`merge --approved`** (bottom-up): merge PRs as they're reviewed, keep
-  stacking the rest. Stops at the first un-approved PR; auto-advances past any
-  bottom PR already merged outside gh-stack.
+Merge is **top-down everywhere** (collapse PRn → PRn-1 → … → base PR, then base → trunk):
+
+- **`merge`**: the whole stack is approved → lands as a single squash commit.
+- **`merge --approved`**: collapse the **contiguous-from-base approved run** into
+  one commit on trunk. Approval is read from the base up — the first un-approved
+  PR caps the run (unapproved PR4 stops at PR3 even if PR5 is approved). The
+  unapproved tail is left in place; after the base lands, run `gh-stack sync` to
+  re-root the tail onto trunk (it does not block on CI).
+- **`merge --base`**: squash-merge **only the bottom PR** into trunk and re-root
+  the next branch onto trunk — one PR per run, re-run for the next. Use this to
+  land reviewed PRs one at a time. Auto-advances past a bottom PR already merged
+  outside gh-stack.
+- **`--collapse`** (with `merge` or `merge --approved`): stop after collapsing
+  into the base PR — review on GitHub, then re-run `merge` to finish.
 
 ### 7. Maintenance