gh-stack 0.15.0 → 0.16.0

package/README.md

@@ -278,6 +278,19 @@ doctor
     Migrate old (v2) metadata to the v3 layout, reconcile git branch
     config against the topology files, and flag stacks whose base
     stack appears already-merged into main. Safe to run repeatedly.
+
+learn [--skill] [--harness <name>] [--global] [--force]
+    Teach a coding agent how to drive gh-stack. By default prints the
+    canonical skill (Markdown, stamped with the running version) to
+    stdout — the text is compiled into the binary, so it never drifts
+    out of sync with the installed version. --skill installs it as a
+    skill file instead, choosing the path from the harness:
+      Claude Code  <root>/.claude/skills/using-gh-stack/SKILL.md
+      Codex        <root>/.codex/skills/using-gh-stack/SKILL.md
+      Cursor       <root>/.cursor/skills/using-gh-stack/SKILL.md
+    --harness  claude | codex | cursor (skips the interactive prompt)
+    --global   Install under ~/.<harness>/ instead of the project root
+    --force    Overwrite an existing skill file without confirming
 ```
 
 ## Global Options
@@ -460,7 +473,16 @@ gh-stack merge              # finishes base PR → main + archives the stack
 
 ## Agent/CI Usage
 
-gh-stack is designed to be used by AI agents and CI pipelines:
+gh-stack is designed to be used by AI agents and CI pipelines. The fastest way
+to onboard an agent is `gh-stack learn` — it prints a version-matched skill (or
+installs one with `--skill`) so the agent learns the current commands, flags,
+and gotchas straight from the binary:
+
+```bash
+# Teach an agent the current API (always in sync with the installed version)
+gh-stack learn                              # print the skill to stdout
+gh-stack learn --skill --harness claude     # install it for Claude Code
+```
 
 ```bash
 # Non-interactive mode — all prompts auto-resolved

package/package.json

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

package/src/commands/learn.ts

@@ -0,0 +1,152 @@
+// gh-stack learn — teach agents how to drive gh-stack.
+//
+//   gh-stack learn            Print the canonical, version-stamped skill to stdout.
+//   gh-stack learn --skill    Install it as a skill file for a coding harness.
+//
+// The skill text is compiled into the binary (src/lib/skill.ts), so it's always
+// in lockstep with the installed version — no hand-maintained skill to drift.
+import { homedir } from "node:os";
+import { join } from "node:path";
+import pc from "picocolors";
+import * as p from "../lib/output.ts";
+import * as git from "../lib/git.ts";
+import { isAutoYes } from "../lib/ui.ts";
+import { SKILL_NAME, skillContent } from "../lib/skill.ts";
+
+const { version: VERSION } = await import("../../package.json");
+
+interface Harness {
+  key: string;
+  label: string;
+  dir: string; // the per-harness config dir, e.g. ".claude"
+}
+
+// Project-root install locations per harness. Global installs swap the repo
+// root for the home directory (same `<dir>/skills/<name>/SKILL.md` shape).
+const HARNESSES: Harness[] = [
+  { key: "claude", label: "Claude Code", dir: ".claude" },
+  { key: "codex", label: "Codex", dir: ".codex" },
+  { key: "cursor", label: "Cursor", dir: ".cursor" },
+];
+
+function flagValue(args: string[], name: string): string | undefined {
+  const eq = args.find((a) => a.startsWith(`${name}=`));
+  if (eq) return eq.slice(name.length + 1);
+  const i = args.indexOf(name);
+  if (i !== -1 && args[i + 1] && !args[i + 1]!.startsWith("-")) return args[i + 1];
+  return undefined;
+}
+
+export default async function learn(args: string[]): Promise<void> {
+  if (args.includes("--help")) {
+    console.log(`
+gh-stack learn — teach an agent how to use gh-stack
+
+USAGE
+  gh-stack learn [--skill] [options]
+
+By default, prints the canonical gh-stack skill (Markdown, stamped with the
+current version) to stdout. The text is compiled into the binary, so it never
+drifts out of sync with the installed version.
+
+OPTIONS
+  --skill                 Install the skill into a project (or --global) instead
+                          of printing it
+  --harness <name>        Target harness: claude | codex | cursor
+                          (skips the interactive prompt)
+  --global, -g            Install under your home dir (~/.<harness>/skills/...)
+                          instead of the project root
+  --force                 Overwrite an existing skill file without confirming
+  --help                  Show this help
+
+INSTALL PATHS
+  Claude Code   <root>/.claude/skills/${SKILL_NAME}/SKILL.md
+  Codex         <root>/.codex/skills/${SKILL_NAME}/SKILL.md
+  Cursor        <root>/.cursor/skills/${SKILL_NAME}/SKILL.md
+
+EXAMPLES
+  gh-stack learn                          # print the skill to stdout
+  gh-stack learn > AGENTS.md              # capture it however you like
+  gh-stack learn --skill                  # interactive install (pick harness)
+  gh-stack learn --skill --harness claude # install for Claude Code, no prompt
+  gh-stack learn --skill --global -g      # install into your home dir
+`);
+    return;
+  }
+
+  const content = skillContent(VERSION);
+
+  // Default: just print the skill. No chrome — pipe-friendly for agents.
+  if (!args.includes("--skill")) {
+    console.log(content);
+    return;
+  }
+
+  // ── Install mode ──
+  const global = args.includes("--global") || args.includes("-g");
+  const force = args.includes("--force");
+  const autoYes = isAutoYes();
+
+  // Resolve harness: explicit flag, else interactive prompt.
+  let harness: Harness | undefined;
+  const harnessFlag = flagValue(args, "--harness");
+  if (harnessFlag) {
+    harness = HARNESSES.find((h) => h.key === harnessFlag.toLowerCase());
+    if (!harness) {
+      p.log.error(
+        `Unknown harness "${harnessFlag}". Choose one of: ${HARNESSES.map((h) => h.key).join(", ")}.`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  } else if (autoYes) {
+    p.log.error("Non-interactive mode needs an explicit harness: --harness <claude|codex|cursor>.");
+    process.exitCode = 1;
+    return;
+  } else {
+    const selected = await p.select({
+      message: "Which harness is this skill for?",
+      options: HARNESSES.map((h) => ({
+        value: h.key,
+        label: h.label,
+        hint: `${global ? "~" : "."}/${h.dir}/skills/${SKILL_NAME}/`,
+      })),
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Cancelled.");
+      return;
+    }
+    harness = HARNESSES.find((h) => h.key === selected)!;
+  }
+
+  // Resolve install root: home dir (--global) or repo working-tree root.
+  let root: string;
+  if (global) {
+    root = homedir();
+  } else if (await git.isGitRepo()) {
+    root = await git.repoRoot();
+  } else {
+    p.log.error("Not inside a git repository. Run from a project, or use --global.");
+    process.exitCode = 1;
+    return;
+  }
+  const target = join(root, harness.dir, "skills", SKILL_NAME, "SKILL.md");
+
+  // Confirm overwrite unless --force / auto-yes.
+  if ((await Bun.file(target).exists()) && !force && !autoYes) {
+    const ok = await p.confirm({
+      message: `${pc.yellow(target)} already exists. Overwrite?`,
+    });
+    if (p.isCancel(ok) || !ok) {
+      p.cancel("Left existing skill in place.");
+      return;
+    }
+  }
+
+  await Bun.write(target, content); // creates parent dirs as needed
+
+  p.log.success(`Installed ${harness.label} skill → ${pc.cyan(target)}`);
+  p.log.info(
+    `Stamped from gh-stack v${VERSION}. Refresh after upgrading with ${pc.dim("gh-stack learn --skill")}.`,
+  );
+}

package/src/commands/restack.ts

@@ -132,24 +132,32 @@ ALIASES
  * For each branch, compare its local tip against origin. Returns the ones that
  * differ (or whose remote ref is missing), so restack can report exactly which
  * refs didn't land instead of falsely claiming success. (#12)
+ *
+ * The remote sha comes from a single authoritative `git ls-remote` (see
+ * git.remoteHeads), NOT from `rev-parse origin/<branch>`. A force-push can leave
+ * the local remote-tracking ref stale even though the push landed, which made
+ * 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.
  */
-async function findStaleRefs(
+export async function findStaleRefs(
   branches: string[],
 ): Promise<{ branch: string; local: string; remote: string }[]> {
   const stale: { branch: string; local: string; remote: string }[] = [];
   const seen = new Set<string>();
+  const remoteHeads = await git.remoteHeads();
   for (const branch of branches) {
     if (seen.has(branch) || branch === "main" || branch === "master") continue;
     seen.add(branch);
     if (!(await git.localBranchExists(branch))) continue;
     const local = await git.revParse(branch);
-    if (!(await git.remoteBranchExists(branch))) {
+    const remote = remoteHeads.get(branch);
+    if (!remote) {
       stale.push({ branch, local, remote: "(missing)" });
       continue;
     }
-    const remote = await git.revParse(`origin/${branch}`).catch(() => "");
     if (remote !== local) {
-      stale.push({ branch, local, remote: remote ? remote.slice(0, 8) : "(unknown)" });
+      stale.push({ branch, local, remote: remote.slice(0, 8) });
     }
   }
   return stale;

package/src/index.ts

@@ -46,8 +46,12 @@ if (parsed.plain) {
   setPlain(true);
 }
 
-// Ensure we're in a git repo for all commands
-await ensureGitRepo();
+// Ensure we're in a git repo for all commands — except `learn`, which just
+// emits/installs the agent skill and is useful outside any repo (e.g. an agent
+// onboarding before cloning, or `learn --skill --global`).
+if (command !== "learn") {
+  await ensureGitRepo();
+}
 
 // Route to subcommand — strip global flags from command args
 const commandArgs = parsed.commandArgs;
@@ -143,6 +147,10 @@ switch (command) {
     await (await import("./commands/bottom.ts")).default(commandArgs);
     break;
 
+  case "learn":
+    await (await import("./commands/learn.ts")).default(commandArgs);
+    break;
+
   case "--help":
   case "help":
     printHelp();
@@ -196,6 +204,7 @@ ${bold("INFO & MAINTENANCE")}
   ${green("archive")}        Manage archived stacks
   ${green("update-prs")}     Refresh stack visualization in PR descriptions
   ${green("doctor")}         Migrate & repair stack metadata
+  ${green("learn")}          Print the agent skill (--skill installs it)
 
 ${bold("GLOBAL OPTIONS")}
   --yes, -y        Skip confirmations ${dim("(for agents/CI)")}

package/src/lib/git.ts

@@ -38,6 +38,14 @@ export async function gitDir(): Promise<string> {
   return result.trim();
 }
 
+/**
+ * Get the absolute path to the repository's working-tree root.
+ */
+export async function repoRoot(): Promise<string> {
+  const result = await $`git rev-parse --show-toplevel`.text();
+  return result.trim();
+}
+
 /**
  * Check if working tree is clean (no uncommitted changes).
  * Refreshes the index first to avoid false positives from stale stat info.
@@ -149,6 +157,29 @@ export async function pushStackedBranch(branch: string): Promise<boolean> {
   return exitCode === 0;
 }
 
+/**
+ * Read the actual tip sha of every branch on origin in a single `ls-remote`
+ * call. This queries the remote directly, so it is **authoritative** — unlike
+ * `rev-parse origin/<branch>`, which reads the local remote-tracking ref that a
+ * force-push can leave stale (a fresh fetch would correct it). Use this when a
+ * correct answer about the remote's real state matters (e.g. the post-restack
+ * sync verification — #23). Returns a map of branch name → sha.
+ */
+export async function remoteHeads(): Promise<Map<string, string>> {
+  const heads = new Map<string, string>();
+  const { exitCode, stdout } = await $`git ls-remote --heads origin`.nothrow().quiet();
+  if (exitCode !== 0) return heads;
+  const prefix = "refs/heads/";
+  for (const line of stdout.toString().split("\n")) {
+    const tab = line.indexOf("\t");
+    if (tab === -1) continue;
+    const sha = line.slice(0, tab).trim();
+    const ref = line.slice(tab + 1).trim();
+    if (sha && ref.startsWith(prefix)) heads.set(ref.slice(prefix.length), sha);
+  }
+  return heads;
+}
+
 /**
  * Check if a branch exists on the remote.
  */

package/src/lib/md.d.ts

@@ -0,0 +1,7 @@
+// Bun bundles `*.md` files imported with `{ type: "text" }` into the binary as
+// their raw string contents (survives `bun build --compile`). This declaration
+// lets TypeScript type those imports.
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/lib/skill.ts

@@ -0,0 +1,22 @@
+// Canonical, version-stamped agent skill for gh-stack.
+//
+// The skill text is a plain Markdown file — `using-gh-stack.md` — bundled into
+// the binary at build time via Bun's `type: "text"` import (it survives
+// `bun build --compile`). Editing the skill means editing that .md file; this
+// module only stamps the running version into the `{{VERSION}}` placeholder.
+//
+// It is the SINGLE SOURCE OF TRUTH for "how an agent should drive gh-stack":
+// `gh-stack learn` prints it, `gh-stack learn --skill` installs it. Update the
+// .md whenever a command or flag changes and the next release ships it.
+import skillTemplate from "./using-gh-stack.md" with { type: "text" };
+
+export const SKILL_NAME = "using-gh-stack";
+
+/**
+ * Build the full skill document, stamped with the running gh-stack version so
+ * an installed copy always records which release generated it (and can be
+ * refreshed with `gh-stack learn --skill`).
+ */
+export function skillContent(version: string): string {
+  return skillTemplate.replaceAll("{{VERSION}}", version);
+}

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

@@ -0,0 +1,234 @@
+---
+name: using-gh-stack
+description: "MUST be used when working with stacked PRs. gh-stack is a CLI tool for managing stacked PR workflows in squash-merge repos (a Graphite alternative). Covers creating stacks, pushing/creating PRs with submit, navigating (up/down/top/bottom), syncing with main, restacking, merging, and agent/CI usage. Triggers on: stacked PR, gh-stack, create stack, submit stack, push stack, restack, sync stack, stack navigation, up down top bottom, PR dependencies, stack visualization, manage PRs, stacked branches."
+---
+
+# Using gh-stack
+
+> Generated by `gh-stack learn` from **gh-stack v{{VERSION}}**.
+> This file is produced by the binary — don't hand-edit it. Refresh after
+> upgrading with `gh-stack learn --skill`.
+
+`gh-stack` is a CLI for managing **stacked PRs** in squash-merge repositories
+(a Graphite/`gt` alternative). A _stack_ is a chain of dependent branches, each
+its own PR, sitting on top of the trunk (usually `main`).
+
+**Install:** `npm install -g gh-stack` (or `bun install -g gh-stack`)
+
+## Terms
+
+| Term          | Meaning                              |
+| ------------- | ------------------------------------ |
+| **trunk**     | Base branch (usually `main`)         |
+| **stack**     | A chain of dependent branches        |
+| **upstack**   | Child branches (depend on current)   |
+| **downstack** | Parent branches (current depends on) |
+
+## The current stack follows your current branch
+
+There is no "switch stack" state to manage — **gh-stack always operates on the
+stack that contains the branch you're on.** It resolves this from your current
+git branch: the branch's own stack, or (for a new branch built on top of one)
+the nearest tracked ancestor's stack. Every command (`log`, `submit`, `status`,
+`restack`, …) acts on that stack automatically.
+
+So to switch stacks, just switch branches — there's nothing gh-stack-specific to
+run:
+
+```bash
+git switch other-feature-branch   # any branch on the other stack
+gh-stack log                       # now shows that stack
+```
+
+Or use the interactive picker when you don't remember the branch names:
+
+```bash
+gh-stack checkout --stack          # pick a stack, jump to it (alias: co --stack)
+```
+
+(Plain `gh-stack checkout` picks a _branch within the current stack_; add
+`--stack` to pick a _different stack_.)
+
+## Agent/CI mode — read this first
+
+Run non-interactively with `--yes`/`-y` or `GH_STACK_YES=1` (also enables
+`--plain`: no spinners/colors/box-drawing — clean for log capture).
+
+```bash
+export GH_STACK_YES=1     # skip every confirmation, plain output
+```
+
+- **Discover topology without parsing internals:** `gh-stack stacks --json`
+  (network-free) or `gh-stack status --json` (adds PR/CI/review state).
+- **Always pass `-t`/`-b` to `submit`** so PRs get real titles/bodies instead
+  of generic auto-generated ones (see below).
+- Commands that rebase (`restack`, `sync`, `merge`) **refuse to run on a dirty
+  tree** — commit or stash first.
+
+## Core workflow
+
+### 1. Start a stack
+
+**From existing branches** (e.g. `main → feat-1 → feat-2`) — go to the TOP;
+`init` walks down and reconstructs the chain automatically:
+
+```bash
+git checkout feat-2
+gh-stack init            # detects main → feat-1 → feat-2, adopts existing PRs
+```
+
+**From scratch:**
+
+```bash
+git checkout -b kiliman/first-WEB-1234
+gh-stack init                              # create stack, add current branch
+gh-stack create kiliman/second-WEB-5678    # new branch stacked on top
+# ...work, commit...
+gh-stack create kiliman/third-WEB-9012     # stack another
+```
+
+`init` options: `--name <stack>`, `--parent <trunk>`, `--description <text>`.
+
+### 2. Push & create PRs — `submit`
+
+`submit` is the workhorse: **idempotent, scope-aware, self-healing**. It pushes
+changed branches with `--force-with-lease` (skips up-to-date ones), creates
+missing PRs with the correct base, fixes PR bases, and refreshes the stack
+visualization in every PR body.
+
+```bash
+gh-stack submit                       # push downstack + create/update PRs
+gh-stack submit -d                    # create new PRs as drafts
+gh-stack submit --dry-run             # preview, no side effects
+gh-stack submit --restack             # then propagate up to children (see below)
+gh-stack submit -t "<title>" -b "<body>"   # explicit title/body for new PRs
+gh-stack submit -t "<title>" --body-file /tmp/body.md
+gh-stack submit -n                    # auto-generate titles (generic — avoid)
+```
+
+**Agents: provide title + body explicitly.** `--title` implies `--no-edit`
+(no prompts); title/body apply to all new PRs created in scope:
+
+```bash
+gh-stack submit \
+  -t "Store raw transcription JSON and WebVTT [WEB-7409]" \
+  -b "$(cat <<'EOF'
+## Summary
+- Store raw transcription JSON alongside pre-rendered WebVTT
+
+## Test plan
+- [ ] Verify both formats persist
+EOF
+)"
+```
+
+**`submit -t`/`-b` also updates an existing PR in place** — pass them while on a
+branch that already has a PR to change just that one (visualization-safe).
+
+**`--restack`** chains a restack after submit. `submit` owns DOWNSTACK (trunk →
+current); `restack` owns UPSTACK (the children). Together they're the everyday
+downstack-fix loop in one command: _drop downstack → fix → commit →
+`gh-stack submit --restack`_ pushes the fix AND rebases the children onto it.
+
+### 3. Navigate
+
+```bash
+gh-stack log           # stack tree (default command)
+gh-stack ls            # numbered branch list
+gh-stack up [n]        # toward children (upstack)
+gh-stack down [n]      # toward parents (downstack)
+gh-stack top           # tip (leaf)
+gh-stack bottom        # base (first branch above trunk)
+gh-stack checkout      # interactive picker (alias: co)
+```
+
+### 4. Sync & restack
+
+```bash
+gh-stack sync          # fetch trunk, rebase base onto it, restack ALL children
+gh-stack restack       # rebase current branch + descendants onto their parents
+gh-stack restack --dry-run
+```
+
+**⚠️ Restack propagates UPWARD from the current branch.** Run it from the
+**lowest branch you changed**, never from the top:
+
+```bash
+gh-stack bottom        # go to the changed branch
+# ...edit, commit...
+gh-stack submit        # push it
+gh-stack restack       # propagates the change UP through children
+```
+
+**Changing multiple branches?** Finish each one fully before moving up —
+`edit → test → commit → push → restack`, then `gh-stack up` and repeat. Don't
+edit several branches then restack once at the end (only the last branch ends
+up pushed).
+
+**On rebase conflict:** resolve, `git add <files>`, `git rebase --continue`,
+then `gh-stack restack --resume` to finish the remaining branches.
+
+**`sync` is self-correcting:** if you merged the bottom PR in the GitHub UI,
+`sync` detects it and advances the stack past the merged branch (re-rooting onto
+trunk) instead of replaying squashed commits and conflicting.
+
+### 5. Status
+
+```bash
+gh-stack status            # PR dashboard: CI, reviews, merge readiness
+gh-stack status --current  # current stack only
+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 --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.
+
+### 7. Maintenance
+
+```bash
+gh-stack delete        # remove a branch from the stack (re-parents children)
+gh-stack split         # cut a stack into two at a branch
+gh-stack rename        # rename a tracked branch (keeps metadata in sync)
+gh-stack undo          # restore from the last snapshot
+gh-stack archive       # manage archived stacks
+gh-stack doctor        # migrate & repair stack metadata
+gh-stack update-prs    # refresh stack visualization in PR descriptions
+```
+
+## Stack visualization
+
+`submit` auto-maintains a `### 📚 Stacked on` footer in every PR body. **Do not
+hand-write your own stack list** — it's regenerated each run, so a manual copy
+just goes stale and contradicts the auto footer. Describe _this_ PR in its body;
+let `submit` describe the stack. Link a specific sibling inline in prose if
+needed.
+
+## Safety model
+
+- **Snapshots** before every destructive op (restack/sync/merge/remove); roll
+  back with `gh-stack undo`. Think of them as a reflog for stack operations.
+- **Squash-merge safe** — uses temporary tags for stable rebasing (handles the
+  merge-base problem squash-merge creates).
+- **Never force-pushes trunk.**
+- **Metadata is local and never committed:** per-stack files under
+  `.git/.gh-stack/` plus git branch config. Inspect it via `gh-stack stacks
+--json`, not by reading the store. (`gh-stack doctor` migrates the old v2
+  `.git/gh-stack-metadata.json` monolith.)
+
+## Don'ts
+
+- **Don't use `gt`/Graphite commands** — this is `gh-stack`.
+- **Don't restack from the top** of the stack — restack flows upward.
+- **Don't edit multiple branches then restack once** — finish each branch first.
+- **Don't hand-write a stack section** in PR bodies — `submit` owns it.