@ramon-sg/issue-flow 0.3.4 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Flujo de trabajo de issue a PR para cualquier repo, en local y en las sesiones de Claude en la nube: nombra la rama de cada issue, crea su worktree con puertos y Docker propios, abre el PR en draft y limpia cuando se mergea. Trae las skills que usan ese flujo.
 
-> **Instalar en un repo:** `npx agent-kitchen apply`, que instala este flujo con sus skills, las skills generales, `claude-cloud` y `claude-repo-guard`, y los actualiza ([agent-kitchen](https://github.com/ramon-sg/agent-kitchen)). El paquete es `@ramon-sg/issue-flow` y el comando, `issue-flow`; sin el scope, `issue-flow` en npm es otro paquete.
+> **Instalar en un repo:** `npx agent-kitchen apply`, que instala este flujo con sus skills, las skills generales, `agent-cloud-kit` y `claude-repo-guard`, y los actualiza ([agent-kitchen](https://github.com/ramon-sg/agent-kitchen)). El paquete es `@ramon-sg/issue-flow` y el comando, `issue-flow`; sin el scope, `issue-flow` en npm es otro paquete.
 
 ## Qué va a tener
 
@@ -13,7 +13,7 @@ Flujo de trabajo de issue a PR para cualquier repo, en local y en las sesiones d
 - **`issue-flow worktree setup|teardown|ports|cleanup|prune`:** prepara y limpia cada worktree con los pasos del repo, le da un bloque de puertos y borra los worktrees con el PR cerrado.
 - **`issue-flow pr worktree <n>`:** abre un PR en su propio worktree, en la rama del PR, para revisarlo sin soltar lo que estás haciendo.
 - **`issue-flow adapter setup|issue|archive`:** lo que corren Orca y Paseo al crear o borrar un worktree.
-- **`issue-flow session`:** el hook `SessionStart`; en la nube llama a [`claude-cloud`](https://github.com/ramon-sg/claude-cloud).
+- **`issue-flow session`:** el hook `SessionStart`; en la nube llama a [`agent-cloud-kit`](https://github.com/ramon-sg/agent-cloud-kit).
 - **`issue-flow hook worktree-create|worktree-remove`:** los hooks `WorktreeCreate` y `WorktreeRemove` de Claude Code, para `claude --worktree`.
 - **Skills:** `github-issues`, `start-issue`, `finish-pr`, `close-pr`, `pr-review-comments` y `pr-worktree`.
 
@@ -99,7 +99,7 @@ issue-flow worktree setup --only deps  # uno solo
 issue-flow worktree teardown           # sus pasos de limpieza, sus puertos y su Docker
 issue-flow worktree ports [--next]     # el primer puerto de su bloque, o lo pasa al siguiente
 issue-flow worktree cleanup            # el Docker de los worktrees que ya no existen
-issue-flow worktree prune              # borra los worktrees cuyo PR se mergeó o se cerró
+issue-flow worktree prune              # borra los worktrees cuyo PR se mergeó o se cerró, y pone al día la base local
 ```
 
 Lo propio de cada repo (instalar, armar la base, levantar Docker) son **pasos** en `worktrees` de `.agents/flow.json`; `issue-flow` solo los corre:
@@ -175,7 +175,7 @@ scripts:
 
 Es el hook `SessionStart` de Claude Code. Lo que imprime le llega a Claude como contexto, así que ahí van los avisos. Nunca hace fallar la sesión.
 
-1. En una sesión en la nube (`CLAUDE_CODE_REMOTE=true`), corre `claude-cloud session`. Si no está, dice qué setup script poner en claude.ai.
+1. En una sesión en la nube (`CLAUDE_CODE_REMOTE=true`), corre `agent-cloud-kit session`. Si no está, dice qué setup script poner en claude.ai.
 2. En un worktree (o en el checkout de la nube), corre los pasos de `setup`. La carpeta sale del `cwd` que manda Claude, que con `claude --worktree` es la del worktree, y si no viene, de `CLAUDE_PROJECT_DIR`.
 3. Si un worktree local está en la rama de una issue que no está en origin, avisa que la issue no quedó empezada.
 4. Borra el Docker de los worktrees que ya no existen: Claude Code no llama al hook `WorktreeRemove` de los worktrees que no hizo un hook `WorktreeCreate`.
@@ -197,7 +197,7 @@ npx @ramon-sg/issue-flow doctor                   # revisa que el repo esté com
 
 1. **`.agents/flow.json`:** si no existe, lo crea con el `$schema` de esta versión y, si el repo tiene `paseo.json`, con su plantilla de rama y sus tipos. Esa primera vez propone las recetas que sugieren los archivos del repo (con `--yes`, todas; sin terminal y sin `--yes`, no escribe nada y lo dice). Si ya existe, no pregunta: corre las migraciones de esta versión, mueve el `$schema` y suma las recetas de `--recipe`.
 2. **`package.json`:** `@ramon-sg/issue-flow` en esta versión, exacta. `@ramon-sg/github-rest` y los scripts `issue:start`, `issue:start:free`, `worktree:prune` y `pr:worktree` solo si faltan (`issue:start:free` no se agrega si el repo tiene su propio `issue:start`, que se saltaría): un `github-rest` que el repo ya tiene se queda, con un aviso si no llega a la versión que necesitan las skills.
-3. **`.claude/settings.json`:** los hooks `SessionStart`, `WorktreeCreate` y `WorktreeRemove`, fijados a esta versión y con 600 segundos. El de `SessionStart` corre `claude-cloud session` en la nube, así que un hook propio de `claude-cloud` se quita para que no corra dos veces.
+3. **`.claude/settings.json`:** los hooks `SessionStart`, `WorktreeCreate` y `WorktreeRemove`, fijados a esta versión y con 600 segundos. El de `SessionStart` corre `agent-cloud-kit session` en la nube, así que un hook propio de `agent-cloud-kit` se quita para que no corra dos veces.
 
 No consulta npm, y nunca baja de versión: si el repo ya tiene una issue-flow más nueva (por ejemplo, `package.json` subido a mano antes del `install`), o un rango como `^0.2.6`, se detiene y dice qué correr. `--json` da `{ version, changes, kept, written, next }`. Sale con 0 si aplicó o no había nada que hacer, y con 1 si se negó o tenía que preguntar y no pudo.
 

package/dist/commands/apply.js

@@ -7,7 +7,7 @@
  * to this version. It changes no other version: who updates picks the version by picking
  * which one to run (`npx @ramon-sg/issue-flow@<version> apply`). It refuses when the repo
  * already has a newer issue-flow, or a range, since the hooks need an exact one. The skills,
- * `claude-cloud` and `claude-repo-guard` are `agent-kitchen`'s, which runs this command.
+ * `agent-cloud-kit` and `claude-repo-guard` are `agent-kitchen`'s, which runs this command.
  */
 import { confirm } from "../ask.js";
 import { CONFIG_PATH, isObject } from "../config-base.js";

package/dist/commands/session.d.ts

@@ -1,7 +1,7 @@
 import type { FlowConfig } from "../config.js";
 import type { Output } from "../output.js";
-/** Where the cloud environment's setup leaves the `claude-cloud` command. */
-export declare const CLAUDE_CLOUD_BIN = "/opt/claude-cloud/bin/claude-cloud";
+/** Where the cloud environment's setup leaves the `agent-cloud-kit` command. */
+export declare const AGENT_CLOUD_KIT_BIN = "/opt/agent-cloud-kit/bin/agent-cloud-kit";
 /**
  * `issue-flow session`.
  * @param options - The config and the session's folder.

package/dist/commands/session.js

@@ -1,7 +1,7 @@
 /**
  * @file `issue-flow session`: the `SessionStart` hook of Claude Code. What it prints on
  * stdout reaches Claude as the session's context, so every warning goes there. Its steps:
- * in a cloud session, `claude-cloud session` (tools, Docker, the full history and the
+ * in a cloud session, `agent-cloud-kit session` (tools, Docker, the full history and the
  * repo's session steps); in a worktree (or the cloud's checkout), the setup steps; in a
  * local worktree whose issue branch is not published, a warning to run `start-issue`; the
  * cleanup of the Docker of deleted worktrees (Claude Code does not call `WorktreeRemove`
@@ -18,24 +18,24 @@ import { issueOfBranch } from "../issue-text.js";
 import { inPath } from "../launch.js";
 import { runSetup } from "../worktree-steps.js";
 import { stepPlace } from "./worktree.js";
-/** Where the cloud environment's setup leaves the `claude-cloud` command. */
-export const CLAUDE_CLOUD_BIN = "/opt/claude-cloud/bin/claude-cloud";
+/** Where the cloud environment's setup leaves the `agent-cloud-kit` command. */
+export const AGENT_CLOUD_KIT_BIN = "/opt/agent-cloud-kit/bin/agent-cloud-kit";
 /** The package that prepares the cloud, for the message of what to set in claude.ai. */
-const CLAUDE_CLOUD_PACKAGE = "@ramon-sg/claude-cloud";
+const AGENT_CLOUD_KIT_PACKAGE = "agent-cloud-kit";
 /**
- * In a cloud session, runs `claude-cloud session` (`CLAUDE_CLOUD_BIN` changes where it is
+ * In a cloud session, runs `agent-cloud-kit session` (`AGENT_CLOUD_KIT_BIN` changes where it is
  * looked for). Its output goes to stderr, as its steps print their own.
  * @param root - The checkout.
  * @param say - Where a message for Claude goes.
  */
 function cloudSession(root, say) {
-    const bin = process.env.CLAUDE_CLOUD_BIN ?? CLAUDE_CLOUD_BIN;
+    const bin = process.env.AGENT_CLOUD_KIT_BIN ?? AGENT_CLOUD_KIT_BIN;
     if (!existsSync(bin)) {
-        say(`the environment setup did not run (there is no ${bin}). In claude.ai, set the environment's setup script to: npx -y ${CLAUDE_CLOUD_PACKAGE}@1 setup. It applies to new sessions.`);
+        say(`the environment setup did not run (there is no ${bin}). In claude.ai, set the environment's setup script to: npx -y ${AGENT_CLOUD_KIT_PACKAGE}@1 setup. It applies to new sessions.`);
         return;
     }
     if (spawnSync(bin, ["session"], { cwd: root, stdio: ["ignore", 2, 2] }).status !== 0)
-        say(`claude-cloud session failed; run '${bin} session' in ${root} to see why.`);
+        say(`agent-cloud-kit session failed; run '${bin} session' in ${root} to see why.`);
 }
 /**
  * The issue of a local worktree whose branch has the issue's number and is not in origin:

package/dist/commands/worktree.d.ts

@@ -72,7 +72,7 @@ export declare function worktreeCleanup(options: WorktreeOptions, out: Output):
  * closed, after asking: their teardown, the folder, the local branch and the session id.
  * It never touches one with uncommitted changes, unpushed commits, or a lock (a live
  * session of `claude --worktree` or `issue start`, or by hand), and checks each again just
- * before deleting it.
+ * before deleting it. If it deleted one, it moves the local base forward to origin's.
  * @param options - The options.
  * @param out - Where to write.
  * @returns The exit code.

package/dist/commands/worktree.js

@@ -10,7 +10,7 @@ import { confirm } from "../ask.js";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { canonicalPath, dockerCleanup } from "../docker.js";
-import { checkoutRoot, git, isClean, locateRepo, safeToDelete, worktrees } from "../git.js";
+import { checkoutRoot, git, isClean, locateRepo, safeToDelete, updateBase, worktrees } from "../git.js";
 import { forgetSession } from "../launch.js";
 import { warn } from "../output.js";
 import { claimPortBase, nextPortBase, portBase } from "../ports.js";
@@ -204,7 +204,7 @@ async function pruneCandidates(options, mainRoot, out) {
  * closed, after asking: their teardown, the folder, the local branch and the session id.
  * It never touches one with uncommitted changes, unpushed commits, or a lock (a live
  * session of `claude --worktree` or `issue start`, or by hand), and checks each again just
- * before deleting it.
+ * before deleting it. If it deleted one, it moves the local base forward to origin's.
  * @param options - The options.
  * @param out - Where to write.
  * @returns The exit code.
@@ -224,6 +224,7 @@ export async function worktreePrune(options, out) {
         return 0;
     }
     const { commonDir } = locateRepo(mainRoot) ?? { commonDir: "" };
+    let deleted = 0;
     for (const item of doomed) {
         if (!unchanged(mainRoot, item)) {
             out.stdout(`changed since the check, not deleted: ${item.path}\n`);
@@ -238,6 +239,10 @@ export async function worktreePrune(options, out) {
             warn(out, `could not delete the local branch ${item.branch}.`);
         forgetSession(commonDir, item.branch);
         out.stdout(`deleted: ${item.path} (${item.branch})\n`);
+        deleted += 1;
     }
+    const stale = deleted === 0 ? null : updateBase(mainRoot, place.base);
+    if (stale !== null)
+        warn(out, stale);
     return 0;
 }

package/dist/git.d.ts

@@ -144,3 +144,15 @@ export declare function checkoutRoot(cwd: string): string | null;
  * @example safeToDelete("/repo", "feat/42-x", "")
  */
 export declare function safeToDelete(cwd: string, branch: string, head: string): boolean;
+/**
+ * Brings `origin/<base>` and moves the local base forward to it, if nothing is lost. A base
+ * not checked out anywhere moves as a ref only; one checked out is merged there with
+ * `--ff-only`, and only if that checkout has no changes. A base with commits that are not in
+ * origin is left alone.
+ * @param mainRoot - The main checkout.
+ * @param base - The base branch.
+ * @returns Null if it is up to date now (or there is no local base); else why it was not
+ *   moved.
+ * @example updateBase("/repo", "main") // null
+ */
+export declare function updateBase(mainRoot: string, base: string): string | null;

package/dist/git.js

@@ -213,3 +213,34 @@ export function safeToDelete(cwd, branch, head) {
         return true;
     return head !== "" && git(cwd, ["merge-base", "--is-ancestor", branch, head]).ok;
 }
+/**
+ * Brings `origin/<base>` and moves the local base forward to it, if nothing is lost. A base
+ * not checked out anywhere moves as a ref only; one checked out is merged there with
+ * `--ff-only`, and only if that checkout has no changes. A base with commits that are not in
+ * origin is left alone.
+ * @param mainRoot - The main checkout.
+ * @param base - The base branch.
+ * @returns Null if it is up to date now (or there is no local base); else why it was not
+ *   moved.
+ * @example updateBase("/repo", "main") // null
+ */
+export function updateBase(mainRoot, base) {
+    const remote = `refs/remotes/origin/${base}`;
+    const local = `refs/heads/${base}`;
+    if (!git(mainRoot, ["fetch", "-q", "origin", `+refs/heads/${base}:${remote}`]).ok)
+        return `could not fetch ${base} from origin; local ${base} was not updated.`;
+    if (!hasRef(mainRoot, local))
+        return null;
+    const from = git(mainRoot, ["rev-parse", local]).out;
+    const to = git(mainRoot, ["rev-parse", remote]).out;
+    if (from === to)
+        return null;
+    if (!git(mainRoot, ["merge-base", "--is-ancestor", local, remote]).ok)
+        return `local ${base} has commits that are not in origin/${base}; it was not updated.`;
+    const at = checkedOutAt(mainRoot, base);
+    if (at === null)
+        return git(mainRoot, ["update-ref", local, to, from]).ok ? null : `could not move local ${base} to origin/${base}.`;
+    if (!isClean(at, false))
+        return `${base} is checked out in ${at} with changes; it was not updated. Run 'git pull --ff-only' there.`;
+    return git(at, ["merge", "-q", "--ff-only", remote]).ok ? null : `could not update ${base} in ${at}; run 'git pull --ff-only' there.`;
+}

package/dist/settings-hooks.d.ts

@@ -10,7 +10,7 @@ export declare const HOOK_EVENTS: string[];
 export declare function hookCommand(event: string, version: string): string;
 /**
  * Registers our hooks at a version: moves the version of the ones already there and adds
- * the missing ones. In `SessionStart` it drops a `claude-cloud session` hook that is not
+ * the missing ones. In `SessionStart` it drops an `agent-cloud-kit session` hook that is not
  * ours.
  * @param settings - The settings, or null if there is no file.
  * @param version - This package's version.

package/dist/settings-hooks.js

@@ -3,16 +3,16 @@
  * (`issue-flow session`) and `WorktreeCreate` and `WorktreeRemove` (`issue-flow hook …`), each
  * pinned to this package's version. They are found again by their command, so running
  * `apply` twice changes nothing, and a new version only moves the version. The `SessionStart`
- * command names `claude-cloud session`, which `issue-flow session` runs in the cloud: that
- * way `claude-cloud init` sees it and does not add its own, and a hook of `claude-cloud`
+ * command names `agent-cloud-kit session`, which `issue-flow session` runs in the cloud: that
+ * way `agent-cloud-kit init` sees it and does not add its own, and a hook of `agent-cloud-kit`
  * already there is dropped, so it does not run twice.
  */
 import { isObject } from "./config-base.js";
 import { PACKAGE, SETTINGS_FILE, SetupError } from "./setup-files.js";
 /** Seconds each hook may take: the setup steps can install dependencies. */
 const HOOK_TIMEOUT_SECONDS = 600;
-/** What `claude-cloud init` looks for in a `SessionStart` command. */
-const CLOUD_MARKER = "claude-cloud session";
+/** What `agent-cloud-kit init` looks for in a `SessionStart` command. */
+const CLOUD_MARKER = "agent-cloud-kit session";
 /** The subcommand of each hook, and what follows it. */
 const HOOK_COMMANDS = {
     SessionStart: { sub: "session", note: ` # runs ${CLOUD_MARKER} in the cloud` },
@@ -70,7 +70,7 @@ function hooksOf(entry) {
 }
 /**
  * Registers our hooks at a version: moves the version of the ones already there and adds
- * the missing ones. In `SessionStart` it drops a `claude-cloud session` hook that is not
+ * the missing ones. In `SessionStart` it drops an `agent-cloud-kit session` hook that is not
  * ours.
  * @param settings - The settings, or null if there is no file.
  * @param version - This package's version.

package/dist/start-place.d.ts

@@ -52,8 +52,8 @@ export declare function publish(state: StartState): Promise<number>;
 export declare function copyWorktreeIncludes(from: string, to: string, out: Output): void;
 /**
  * After Claude: if the PR was merged and nothing would be lost, offers to delete the
- * worktree and the branch (or, in the main checkout, to go back to the base); if not,
- * says how to resume.
+ * worktree and the branch (or, in the main checkout, to go back to the base), and then
+ * moves the local base forward to origin's; if not, says how to resume.
  * @param state - The start.
  * @param lock - The worktree lock (shared: another session uses it).
  * @example await afterSession(state, lock)

package/dist/start-place.js

@@ -9,7 +9,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from "node:f
 import { dirname, join, relative } from "node:path";
 import { assign, createPr, findPr, getPr, updatePr } from "@ramon-sg/github-rest";
 import { confirm } from "./ask.js";
-import { checkedOutAt, currentBranch, git, gitLines, hasLocal, isClean, onOrigin, safeToDelete, trackOrigin, untracked } from "./git.js";
+import { checkedOutAt, currentBranch, git, gitLines, hasLocal, isClean, onOrigin, safeToDelete, trackOrigin, untracked, updateBase } from "./git.js";
 import { bodyToPartOf, dirName, fill, prBody } from "./issue-text.js";
 import { forgetSession } from "./launch.js";
 import { warn } from "./output.js";
@@ -262,8 +262,8 @@ function keepReason(state, lock, head) {
 }
 /**
  * After Claude: if the PR was merged and nothing would be lost, offers to delete the
- * worktree and the branch (or, in the main checkout, to go back to the base); if not,
- * says how to resume.
+ * worktree and the branch (or, in the main checkout, to go back to the base), and then
+ * moves the local base forward to origin's; if not, says how to resume.
  * @param state - The start.
  * @param lock - The worktree lock (shared: another session uses it).
  * @example await afterSession(state, lock)
@@ -296,10 +296,10 @@ export async function afterSession(state, lock) {
         if (!(await confirm(out, `The PR was merged. Go back to ${base} and delete the local branch ${branch}?`)))
             return;
         mustGit(mainRoot, ["checkout", "-q", base], `could not check out ${base}`);
-        const updated = git(mainRoot, ["fetch", "-q", "origin"]).ok && git(mainRoot, ["merge", "-q", "--ff-only", `origin/${base}`]).ok;
-        if (!updated)
-            warn(out, `could not update ${base}; do it by hand.`);
     }
     mustGit(mainRoot, ["branch", "-q", "-D", branch], `could not delete ${branch}`);
     forgetSession(commonDir, branch);
+    const stale = updateBase(mainRoot, base);
+    if (stale !== null)
+        warn(out, stale);
 }

package/dist/usage.d.ts

@@ -2,7 +2,7 @@
  * @file The usage text of the CLI, printed with `--help` and after a usage error.
  */
 /** Usage text. */
-export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free [--no-repo-deny]] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, with no sandbox nor questions with --free, and also without the repo's\ndeny rules with --free --no-repo-deny. --plan prints the branch and the prompt as JSON and\nchanges nothing. issue start --help explains each flag.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed. session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
+export declare const USAGE = "Usage:\n  issue-flow issue branch <n>... [--namer claude|title] [--json] [-R owner/repo]\n  issue-flow issue branch --missing [--limit <n>] [--namer claude|title] [--dry-run | --yes] [--json] [-R owner/repo]\n  issue-flow issue start <n> [--branch] [--dry-run | --yes] [--resume <branch> | --new] [--no-launch]\n                             [--ask-permissions | --free [--no-repo-deny]] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --plan [--ask-permissions | --free] [--namer claude|title] [-R owner/repo]\n  issue-flow issue start <n> --cloud | --here | --teleport | --adopt [...]\n  issue-flow worktree setup [--only <step>]\n  issue-flow worktree teardown [--path <dir>]\n  issue-flow worktree ports [--next]\n  issue-flow worktree cleanup [--path <dir>]\n  issue-flow worktree prune [--only <dir>] [--yes] [-R owner/repo]\n  issue-flow pr worktree <n> [--no-setup] [-R owner/repo] [-- [<command>...]]\n  issue-flow adapter setup [--only <step>] | issue [<url>] | archive [-R owner/repo]\n  issue-flow session\n  issue-flow hook worktree-create | worktree-remove\n  issue-flow apply [--yes] [--dry-run] [--json] [--recipe <name>,...]\n  issue-flow doctor [--json]\n  issue-flow labels sync [--update] [--dry-run] [--json] [-R owner/repo]\n\nThe slug comes from the issue's \"Slug de rama\" block, then from Claude, then from the title,\nand the branch from the repo's template (an older \"Rama sugerida\" block is used if it fits).\n--missing adds the slug block to every open issue without a block, after confirming.\n\nissue start makes the branch in a worktree (or, with --branch, in this checkout), the\nstart commit, the push, the draft PR and the assignment, after confirming, and opens\nClaude: in auto mode if the repo has claude-repo-guard, with your settings with\n--ask-permissions, with no sandbox nor questions with --free, and also without the repo's\ndeny rules with --free --no-repo-deny. --plan prints the branch and the prompt as JSON and\nchanges nothing. issue start --help explains each flag.\n\n--cloud confirms here and opens a Claude cloud session that starts the issue there.\n--here, inside a cloud session, starts it in this checkout and opens nothing. --teleport\nbrings the cloud session noted in the PR to the worktree. --adopt starts it in the\nworktree another tool (Orca, Paseo) just made, without asking nor opening Claude.\n\nworktree runs the steps of \"worktrees\" in .agents/flow.json: setup prepares this worktree,\nteardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block\nof ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees\nwhose PR was merged or closed, then moves the local base forward to origin's (only if\nnothing is lost: not with changes where it is checked out, nor with commits not in\norigin). session is the SessionStart hook of Claude Code.\n\npr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with\n--, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup\nwhen they make a worktree (its steps and, if it came from an issue, issue start --adopt),\nissue to start one by hand, and archive before they delete it. hook implements Claude\nCode's WorktreeCreate and WorktreeRemove for claude --worktree.\n\napply leaves the repo as this version needs it: .agents/flow.json (the first time, with\nthe recipes its files suggest), issue-flow at this version and github-rest and the scripts\nif missing in package.json, and the hooks; it changes no other version, and refuses a newer\nissue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version\nit picks, along with the skills, agent-cloud-kit and claude-repo-guard. init and upgrade still\nrun apply, with a warning, until 0.4.0.\n\nlabels sync makes in GitHub the labels the flow wants (\"labels\" in .agents/flow.json: the\nissue types and P1 to P4 by default) that the repo lacks. Names ignore case and are never\nrenamed nor deleted; --update also fixes the color and description of those that differ.";
 /** Usage text of `issue start`, printed with `issue start --help`. */
 export declare const START_USAGE = "Usage: issue-flow issue start <n> [flags]\n\nStarts issue <n>: the branch (in a worktree, or in this checkout with --branch), the empty\nstart commit, the push, the draft PR and the assignment, after confirming; then it opens\nClaude there.\n\nFlags:\n  --dry-run            show what it would do and change nothing\n  -y, --yes            do it without asking\n  --branch             in this checkout instead of a worktree\n  --resume <branch>    take that branch of the issue\n  --new                make another branch, even if the issue has one\n  --no-launch          leave everything ready and do not open Claude\n  --namer claude|title who names the branch when the issue has no slug block\n  -R owner/repo        another repo than the checkout's\n  --plan               print the branch and the prompt as JSON, and change nothing\n  --cloud              open a Claude cloud session that starts the issue there\n  --here               inside a cloud session, start it in this checkout\n  --teleport           bring the cloud session noted in the PR to the worktree\n  --adopt              start it in the worktree Orca or Paseo just made\n  -h, --help           this help\n\nPermissions of the Claude it opens (one at most):\n  (none)               auto mode if the repo has claude-repo-guard, else your settings\n  --ask-permissions    your settings: Claude asks before what they do not allow\n  --free               no sandbox and no questions, as claude:free\n  --no-repo-deny       with --free: also without the deny rules of the repo's settings\n\nWhat each one takes away, and what stays:\n  (none), --ask-permissions\n                       take nothing away: the sandbox, the questions your settings ask\n                       and every deny rule stay.\n  --free               takes away the sandbox and the questions. Every deny rule stays:\n                       yours (~/.claude), the repo's (.claude/settings.json) and the\n                       local ones (.claude/settings.local.json).\n  --free --no-repo-deny\n                       also takes the deny rules out of the worktree's\n                       .claude/settings.json while Claude runs, and puts them back when it\n                       exits; git does not see the change meanwhile. Your deny rules and the\n                       local ones stay, and so do the repo's hooks, attribution, CLAUDE.md,\n                       skills, agents and MCP servers. If Claude changes that file, the\n                       rules go back on top of its change, with a warning to review it. If\n                       the terminal closes first, the next issue start of the issue puts\n                       them back.\n\nFrom the repo's scripts (issue:start, and issue:start:free, which adds --free):\n  npm run issue:start:free 42           npm passes a number on as it is\n  npm run issue:start -- 42 --free      but keeps the flags for itself, unless after --\n  pnpm issue:start 42 --free            pnpm, bun and yarn pass everything on\n  bun run issue:start 42 --free\n  yarn issue:start 42 --free\nA -- does no harm with any of them: issue-flow drops it.\n\nissue:start:free does not go with --ask-permissions, --cloud, --here nor --adopt: use\nissue:start for those. --no-repo-deny goes after it, as any flag:\n  npm run issue:start:free -- 42 --no-repo-deny\n  pnpm issue:start:free 42 --no-repo-deny";
 /**

package/dist/usage.js

@@ -41,7 +41,9 @@ worktree another tool (Orca, Paseo) just made, without asking nor opening Claude
 worktree runs the steps of "worktrees" in .agents/flow.json: setup prepares this worktree,
 teardown cleans it before it goes (steps, ports, Docker), ports prints or moves its block
 of ports, cleanup deletes the Docker of deleted worktrees, and prune deletes the worktrees
-whose PR was merged or closed. session is the SessionStart hook of Claude Code.
+whose PR was merged or closed, then moves the local base forward to origin's (only if
+nothing is lost: not with changes where it is checked out, nor with commits not in
+origin). session is the SessionStart hook of Claude Code.
 
 pr worktree makes (or reuses) a worktree on a PR's own branch, to review and fix it; with
 --, it runs the command there (Claude if none). adapter is what Orca and Paseo run: setup
@@ -53,7 +55,7 @@ apply leaves the repo as this version needs it: .agents/flow.json (the first tim
 the recipes its files suggest), issue-flow at this version and github-rest and the scripts
 if missing in package.json, and the hooks; it changes no other version, and refuses a newer
 issue-flow or a range. doctor checks them. npx agent-kitchen apply runs apply at the version
-it picks, along with the skills, claude-cloud and claude-repo-guard. init and upgrade still
+it picks, along with the skills, agent-cloud-kit and claude-repo-guard. init and upgrade still
 run apply, with a warning, until 0.4.0.
 
 labels sync makes in GitHub the labels the flow wants ("labels" in .agents/flow.json: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramon-sg/issue-flow",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Issue-to-PR workflow for any repo: names each issue's branch, creates its worktree, opens the draft PR and launches Claude Code, locally and in Claude's cloud.",
   "license": "MIT",
   "type": "module",