@senad-d/branchme 0.3.4 → 0.3.5

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## 0.3.4 - Unreleased
+## 0.3.5 - Unreleased
+
+- `push_branch` never pushes onto a differently named integration branch: when the current branch's upstream is `main`, `master`, `trunk`, `develop`, or the origin default branch under another name (a feature branch created from `origin/main` with tracking), it publishes to the same-named branch on that remote with `--set-upstream`, reports `mode: "publish"`, and keeps the previous upstream in `upstream`. Previously such a branch was pushed straight onto the integration branch. Other differently named upstreams keep their explicit `HEAD:<upstream-ref>` push.
+- Added optional `remove_worktree.discardChanges` (default `false`, unchanged behavior). When `true`, the user's explicit authorization, a worktree with staged, unstaged, untracked, or unmerged changes is removed with `git worktree remove --force` and the result lists every discarded path in `discardedPaths`; without it a dirty worktree is still refused, now naming the option. Locked, detached, main, current, prunable, missing, and foreign worktrees stay rejected, and the local branch is retained.
+
+## 0.3.4 - Released
 
 - Added `fetch_remote` for tool-native discovery of unknown remote branch names: refresh one configured remote's branch cache (default `origin`) with optional, remote-tracking-only pruning (default false). Atomic explicit mappings disable configured refmaps, tags, tag pruning, submodules, and maintenance; symbolic destination checks include dangling loose refs, and unsupported non-files ref backends fail closed.
 - Extended read-only `list_branches` with optional local/remote-tracking `kind` and bounded Git branch-list glob `patterns`, applied before output limits. Documented the sequential replacement for issue branch discovery via `git fetch origin --prune` and `git branch -r --list`.

package/README.md

@@ -262,7 +262,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `branch_status` | `{ "ancestry"?: { "sourceBranch": string, "targetBranch": string } }` | Explicitly refreshes the same bounded context used at agent start. An optional strict ancestry query captures both exact HEADs and reports whether the source commit is an ancestor of the target commit; each endpoint may be an exact local branch or a remote-tracking ref such as `origin/main` (a local branch of the same name takes precedence). It is read-only and never checks out or resets remote-tracking refs; automatic Git context does not run ancestry queries. |
 | `list_worktrees` | `{}` | Runs a bounded, read-only inventory of the current repository's main and linked worktrees, including path, branch/detached state, `HEAD`, current/main, locked, prunable, and omitted-entry details. Automatic Git context does not include this inventory. |
 | `create_worktree` | `{ "worktreePath": string, "branchName": string, "branchMode": "new" \| "existing", "baseRef"?: string }` | Creates and verifies a linked worktree at an explicitly approved absolute path. `new` creates a local branch from current `HEAD`, or from the optional read-only `baseRef` (an exact local branch, remote-tracking ref such as `origin/main`, or full commit) regardless of the current checkout's branch, dirt, or staleness; `existing` requires an existing local branch not checked out elsewhere and rejects `baseRef`. It returns a ready handoff with the exact canonical absolute cwd and local branch identity. |
-| `remove_worktree` | `{ "worktreePath": string, "deleteIgnored"?: boolean }` | Force-free removal of an explicitly selected, verified clean linked worktree. Ignored residue is refused by default; `deleteIgnored: true` explicitly deletes it and reports its top-level paths. The local branch remains at the same commit. |
+| `remove_worktree` | `{ "worktreePath": string, "deleteIgnored"?: boolean, "discardChanges"?: boolean }` | Force-free removal of an explicitly selected, verified clean linked worktree. Ignored residue is refused by default; `deleteIgnored: true` explicitly deletes it and reports its top-level paths. The local branch remains at the same commit. `discardChanges: true` explicitly discards uncommitted changes and lists them in `discardedPaths`; a dirty worktree is refused without it. |
 | `retire_branch` | `{ "branchName": string, "expectedHead": string, "targetBranch": string, "force": boolean }` | Deletes only the exact unoccupied local branch ref when its direct ref matches the supplied full commit ID and its relationship to the exact local target has been verified. Unmerged retirement requires explicit `force: true`; remote and remote-tracking refs are untouched. |
 | `land_branch` | `{ "sourceBranch": string, "targetBranch": string, "remote"?: string, "worktreePath"?: string, "pullRequestNumber"?: integer }` | Post-merge fetch, ancestry or exact merged-PR proof, linked-worktree removal including ignored residue, leased local source deletion, and independent fast-forward target sync. Default remote `origin`; omitted path finds the source's linked worktree. Returns per-step receipts. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
@@ -271,7 +271,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `rebase_branch` | `{}` | Requires a clean current branch with a configured upstream and runs `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure. |
 | `integrate_branch` | `{ "sourceBranch": string, "targetBranch": string }` | Integrates one exact existing local source branch into one distinct existing local target branch. The clean active control worktree must already have the target checked out. It returns `already_integrated`, `fast_forward`, `merge_commit`, or a `conflict` only after automatic abort and verified restoration. It never fetches or pushes. |
 | `create_branch` | `{ "branchName": string }` | Validates `branchName`, rejects existing local branches, and runs `git switch -c <branchName>` from current `HEAD`. |
-| `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
+| `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. A branch whose upstream is a differently named `main`, `master`, `trunk`, `develop`, or origin default branch is published to its own name instead and tracks it. |
 | `pull_request` | `{ "headBranch"?: string, "baseBranch"?: string, "title"?: string, "body"?: string, "draft"?: boolean }` | Preflights GitHub branch visibility and verifies the GitHub `headBranch` commit matches the local branch, then reuses an exact matching open PR or creates one in the resolved current repository. Existing PR metadata is preserved. Omitted fields require `BRANCHME_PR_AUTOFILL=true`; branch refs must be distinct, exist locally, and cannot use `owner:branch`. |
 
 `conclude_merge` supports only single-head merges and refuses multi-head merges before mutation. Its marker check also covers manually staged resolutions and clean-filter output. Marker-like lines (including Markdown setext underlines) are conservatively refused; configured marker sizes above 4,096 are refused. Git commits the **entire index**, including already-staged merge entries: do not stage unrelated edits during the merge. Unrelated unstaged edits remain outside the commit. A failed/lost commit response reports uncertain postconditions; inspect `HEAD`, `MERGE_HEAD`, and the index before retrying.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/git.ts

@@ -534,6 +534,26 @@ async function resolvePushTarget(
     };
   }
 
+  const sameNameRef = `refs/heads/${currentBranch}`;
+  if (
+    upstreamTarget.remoteRef !== sameNameRef &&
+    await isIntegrationBranch(pi, ctx, upstreamTarget.remote, upstreamTarget.remoteRef, signal)
+  ) {
+    // A feature branch tracking the default or an integration branch (created
+    // from origin/main with tracking) would push straight onto it. Publish to
+    // the same-named branch instead and track that; the result reports the
+    // previous upstream.
+    const refspec = `HEAD:${sameNameRef}`;
+    return {
+      upstream: upstreamTarget.upstream,
+      mode: "publish",
+      remote: upstreamTarget.remote,
+      remoteRef: sameNameRef,
+      refspec,
+      args: ["push", "--set-upstream", upstreamTarget.remote, refspec],
+    };
+  }
+
   const refspec = `HEAD:${upstreamTarget.remoteRef}`;
   return {
     ...upstreamTarget,
@@ -543,6 +563,20 @@ async function resolvePushTarget(
   };
 }
 
+const INTEGRATION_BRANCH_NAMES = ["main", "master", "trunk", "develop"];
+
+async function isIntegrationBranch(
+  pi: Pick<ExtensionAPI, "exec">,
+  ctx: GitCommandContext,
+  remote: string,
+  remoteRef: string,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const branch = remoteRef.slice("refs/heads/".length);
+  if (INTEGRATION_BRANCH_NAMES.includes(branch)) return true;
+  return remote === "origin" && branch === await getOriginDefaultBranch(pi, ctx, signal);
+}
+
 export async function hasWorkingTreeChanges(
   pi: Pick<ExtensionAPI, "exec">,
   ctx: GitCommandContext,
@@ -1762,6 +1796,7 @@ async function requirePresentWorktreeDirectory(canonicalPath: string): Promise<v
 interface WorktreeRemovalStatus {
   workingTree: WorkingTreeDetails;
   ignoredPaths: string[];
+  changedPaths: string[];
 }
 
 function compareIgnoredPaths(left: string, right: string): number {
@@ -1775,6 +1810,7 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
 
   const records = output.split(NUL_SEPARATOR);
   const ignoredPaths = new Set<string>();
+  const changedPaths: string[] = [];
   let skipNextRecord = false;
   for (const [index, record] of records.entries()) {
     if (skipNextRecord) {
@@ -1786,11 +1822,13 @@ function parseWorktreeRemovalStatus(output: string): WorktreeRemovalStatus {
     const parsed = parsePorcelainChange(records, index);
     skipNextRecord = parsed.nextIndex > index;
     if (parsed.status === "!!") ignoredPaths.add(parsed.path.split("/")[0]);
+    else changedPaths.push(parsed.path);
   }
 
   return {
     workingTree: parseWorkingTreeStatus(output).workingTree,
     ignoredPaths: [...ignoredPaths].sort(compareIgnoredPaths),
+    changedPaths: changedPaths.sort(compareIgnoredPaths),
   };
 }
 
@@ -1799,10 +1837,13 @@ async function inspectRemovableWorktree(
   canonicalPath: string,
   signal?: AbortSignal,
   allowIgnored = false,
+  allowDirty = false,
 ): Promise<WorktreeRemovalStatus> {
   const workingTree = await inspectWorktreeState(pi, canonicalPath, signal);
-  if (workingTree.state !== "clean") {
-    throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
+  if (workingTree.state !== "clean" && !allowDirty) {
+    throw new Error(
+      "The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal, or pass discardChanges: true when the user explicitly authorized discarding them.",
+    );
   }
 
   const ignoredResult = await runGit(pi, { cwd: canonicalPath }, GIT_WORKTREE_REMOVAL_IGNORED_STATUS_ARGS, {
@@ -1810,7 +1851,7 @@ async function inspectRemovableWorktree(
     timeout: GIT_STATUS_TIMEOUT_MS,
   });
   const removalStatus = parseWorktreeRemovalStatus(ignoredResult.stdout);
-  if (removalStatus.workingTree.state !== "clean") {
+  if (removalStatus.workingTree.state !== "clean" && !allowDirty) {
     throw new Error("The target worktree has staged, unstaged, untracked, or unmerged changes; clean it before removal.");
   }
   if (!allowIgnored && removalStatus.ignoredPaths.length > 0) {
@@ -1850,6 +1891,7 @@ export async function removeWorktree(
   worktreePath: unknown,
   signal?: AbortSignal,
   deleteIgnored = false,
+  discardChanges = false,
 ): Promise<RemoveWorktreeDetails> {
   const requestedWorktreePath = validateWorktreePathInput(worktreePath);
   const repoRoot = await getGitRoot(pi, ctx, signal);
@@ -1857,11 +1899,21 @@ export async function removeWorktree(
 
   return withRepositoryMutationQueue(
     repoRoot,
-    removeWorktreeWithinQueue.bind(undefined, pi, rootCtx, requestedWorktreePath, signal, deleteIgnored),
+    removeWorktreeWithinQueue.bind(
+      undefined,
+      pi,
+      rootCtx,
+      requestedWorktreePath,
+      signal,
+      deleteIgnored,
+      undefined,
+      discardChanges,
+    ),
   );
 }
 
-// Caller must hold the repository mutation queue. Ignored residue requires explicit authorization.
+// Caller must hold the repository mutation queue. Ignored residue and discarded
+// changes each require explicit authorization.
 export async function removeWorktreeWithinQueue(
   pi: Pick<ExtensionAPI, "exec">,
   rootCtx: GitCommandContext,
@@ -1869,6 +1921,7 @@ export async function removeWorktreeWithinQueue(
   signal?: AbortSignal,
   allowIgnored = false,
   expectedIdentity?: { branch: string; head: string },
+  allowDirty = false,
 ): Promise<RemoveWorktreeDetails & { deletedIgnoredPaths: string[] }> {
     const repoRoot = rootCtx.cwd;
     const resolved = await resolveWorktreeRemovalTarget(
@@ -1893,13 +1946,23 @@ export async function removeWorktreeWithinQueue(
     const verifiedCanonicalPath = requireLosslessWorktreeIdentity(resolved.canonicalPath, "cwd");
     const retainedBranch = requireLosslessWorktreeIdentity(branchName, "branch");
     await requirePresentWorktreeDirectory(verifiedCanonicalPath);
-    const { workingTree, ignoredPaths } = await inspectRemovableWorktree(pi, verifiedCanonicalPath, signal, allowIgnored);
+    const { workingTree, ignoredPaths, changedPaths } = await inspectRemovableWorktree(
+      pi,
+      verifiedCanonicalPath,
+      signal,
+      allowIgnored,
+      allowDirty,
+    );
     const branchHeadBefore = await getLocalBranchCommit(pi, rootCtx, retainedBranch, signal);
     if (branchHeadBefore.toLowerCase() !== head.toLowerCase()) {
       throw new Error("The target local branch did not match the worktree HEAD before removal.");
     }
 
-    const args = ["worktree", "remove", verifiedCanonicalPath];
+    // --force only when the user authorized discarding changes; a locked worktree
+    // is rejected before this and would need a second --force anyway.
+    const args = changedPaths.length > 0
+      ? ["worktree", "remove", "--force", verifiedCanonicalPath]
+      : ["worktree", "remove", verifiedCanonicalPath];
     try {
       await runGit(pi, rootCtx, args, {
         signal,
@@ -1927,10 +1990,12 @@ export async function removeWorktreeWithinQueue(
       return {
         action: "remove_worktree",
         deletedIgnoredPaths: ignoredPaths.map((path) => redactSecrets(path)),
+        discardedPaths: changedPaths.map((path) => redactSecrets(path)),
         repoRoot: safeWorktreeValue(repoRoot, GIT_WORKTREE_PATH_LIMIT_CHARS),
         request: {
           worktreePath: safeWorktreeValue(requestedWorktreePath, GIT_WORKTREE_PATH_LIMIT_CHARS),
           ...(allowIgnored ? { deleteIgnored: true } : {}),
+          ...(allowDirty ? { discardChanges: true } : {}),
         },
         verified: {
           before: {

package/src/tools/branchme-tools.ts

@@ -209,6 +209,9 @@ const RemoveWorktreeParametersSchema = Type.Object(
     deleteIgnored: Type.Optional(Type.Boolean({
       description: "Explicit authorization to delete ignored files and directories with the worktree; defaults to false.",
     })),
+    discardChanges: Type.Optional(Type.Boolean({
+      description: "Explicit authorization to discard staged, unstaged, untracked and unmerged changes with the worktree; defaults to false. The result lists every discarded path.",
+    })),
   },
   { additionalProperties: false },
 );
@@ -832,7 +835,7 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: PUSH_BRANCH_TOOL_NAME,
     label: "Push Branch",
-    description: "push_branch pushes the current branch to its configured upstream remote with an explicit refspec. If the current branch has no upstream, push_branch publishes it to origin with --set-upstream. push_branch never commits, stages, or edits files.",
+    description: "push_branch pushes the current branch to its configured upstream remote with an explicit refspec. If the current branch has no upstream, push_branch publishes it to origin with --set-upstream. A branch whose upstream is a differently named main, master, trunk, develop or origin default branch is never pushed onto it: push_branch publishes it to its own name on that remote, tracks it, and reports the previous upstream. push_branch never commits, stages, or edits files.",
     promptSnippet: "push_branch: push or publish the current branch only with an explicit target, without committing or staging",
     promptGuidelines: [
       "Use push_branch only after commits already exist; push_branch never commits, stages, or edits files.",
@@ -957,17 +960,25 @@ export function registerBranchMeTools(pi: Pick<ExtensionAPI, "registerTool" | "e
   pi.registerTool({
     name: REMOVE_WORKTREE_TOOL_NAME,
     label: "Remove Worktree",
-    description: "remove_worktree force-free removes one verified clean linked worktree at an explicit absolute worktreePath while retaining and returning its exact local branch identity. Ignored residue is refused by default; deleteIgnored: true explicitly authorizes deleting it with the worktree and reports its top-level paths. remove_worktree rejects main, current, dirty, detached, locked, prunable, missing, and foreign worktrees and never deletes branches.",
+    description: "remove_worktree force-free removes one verified clean linked worktree at an explicit absolute worktreePath while retaining and returning its exact local branch identity. Ignored residue is refused by default; deleteIgnored: true explicitly authorizes deleting it with the worktree and reports its top-level paths. discardChanges: true explicitly authorizes discarding uncommitted changes and reports every discarded path. remove_worktree rejects main, current, detached, locked, prunable, missing, and foreign worktrees, rejects dirty ones without discardChanges, and never deletes branches.",
     promptSnippet: "remove_worktree: force-free removal of an explicitly selected clean linked worktree, with optional explicit ignored-residue deletion, while retaining its branch",
     promptGuidelines: [
       "Use remove_worktree only when the user explicitly requests worktree removal and provides or approves the exact absolute worktreePath; remove_worktree must never infer a filesystem path silently.",
       "Use remove_worktree with worktreePath and optional deleteIgnored; set deleteIgnored: true only after the user explicitly authorizes deleting all ignored files and directories, including possible .env, .pi/, dependency, and build residue.",
+      "Set remove_worktree discardChanges: true only after the user explicitly authorizes discarding the worktree's uncommitted changes; never infer it from a dirty worktree.",
       "remove_worktree never accepts force, move, prune, repair, lock, unlock, branch deletion, remote, or refspec parameters.",
       "Do not batch remove_worktree with dependent worktree mutations; wait for remove_worktree to complete and verify its non-ready handoff before continuing.",
     ],
     parameters: RemoveWorktreeParametersSchema,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      const details = await removeWorktree(pi, ctx, params.worktreePath, signal, params.deleteIgnored === true);
+      const details = await removeWorktree(
+        pi,
+        ctx,
+        params.worktreePath,
+        signal,
+        params.deleteIgnored === true,
+        params.discardChanges === true,
+      );
       return {
         content: [{ type: "text", text: formatRemoveWorktree(details) }],
         details,

package/src/types.ts

@@ -111,6 +111,8 @@ export interface RemoveWorktreeToolInput {
   worktreePath: string;
   /** Explicitly authorizes deleting ignored files and directories with the worktree. */
   deleteIgnored?: boolean;
+  /** Explicitly authorizes discarding staged, unstaged, untracked and unmerged changes with the worktree. */
+  discardChanges?: boolean;
 }
 
 export interface WorktreeEntry {
@@ -194,6 +196,8 @@ export interface CreateWorktreeDetails {
 export interface RemoveWorktreeDetails {
   action: "remove_worktree";
   deletedIgnoredPaths: string[];
+  /** Changed paths discarded under discardChanges; empty for a clean worktree. */
+  discardedPaths: string[];
   repoRoot: string;
   request: RemoveWorktreeToolInput;
   verified: {