@senad-d/branchme 0.1.8 → 0.2.0

package/docs/SMOKE_TEST.md

@@ -23,10 +23,13 @@ pi --no-extensions -e .
 ## Automated smoke behavior
 
 - `npm run smoke:pi` first runs isolated checkout Pi processes from a temporary non-Git working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
-- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, and `remove_worktree` are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata.
-- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback.
-- The Pi runtime smoke validates worktree tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree. Real-Git `list_worktrees`/`create_worktree`/`remove_worktree` lifecycle coverage runs under `npm run test` in temporary local repositories with sibling destinations under the same temporary root and no remotes.
-- `npm run smoke:worktree-handoff` loads only BranchMe into a deterministic extension host backed by real local Git, creates a new-branch linked worktree through the registered `create_worktree` tool, and launches a separate Node verification process with the returned absolute `handoff.cwd`. That process verifies its cwd, branch, full `HEAD`, and lack of remotes. The smoke then calls the registered `remove_worktree` tool, verifies the directory is absent, and verifies the retained local branch remains at the original commit.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly thirteen tools—`branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
+- Runtime schema inspection verifies that `integrate_branch` has exactly the required `sourceBranch` and `targetBranch` fields and that `retire_branch` has exactly the required `branchName`, `expectedHead`, `targetBranch`, and `force` fields with `additionalProperties: false`. It also verifies that `branch_status` has only an optional top-level `ancestry` object whose required nested `sourceBranch` and `targetBranch` fields reject additional nested or top-level properties.
+- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback. It expects all thirteen tools but forbids `retire_branch`, `integrate_branch`, and every remote or worktree mutation tool from executing.
+- The Pi runtime smoke validates worktree, integration, and retirement tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree, runs a merge, or retires a branch. Real-Git lifecycle coverage runs under `npm run test` in isolated temporary local repositories with no remote contact.
+- Isolated real-Git integration tests cover `already_integrated`, `fast_forward`, exact two-parent `merge_commit`, and conflict-path capture followed by verified automatic abort/restoration. They also cover target mismatch, dirty control state, rejection of branch-specific target merge options, unrelated histories, ignored-file overwrite protection, preserved repository hooks, and a committed source ref checked out in another dirty linked worktree. The recorded merge argv proves autostash and rerere are disabled, ignored-file protection is enabled, and `--no-verify` is absent.
+- Isolated real-Git retirement tests cover merged and explicitly forced-unmerged local-ref deletion, stale expected-`HEAD` rejection, current and linked-worktree occupancy, dirty unrelated worktrees, non-current targets, and preservation of target refs, remote-tracking refs, worktrees, working-tree files, and `branch.<name>.*` configuration without contacting a remote. Recorded argv proves retirement uses `update-ref --no-deref -d` with the captured expected commit and never uses `git branch -d/-D`, fetch, push, or a remote ref target.
+- `npm run smoke:worktree-handoff` loads only BranchMe into a deterministic extension host backed by real local Git, creates a new-branch linked worktree through the registered `create_worktree` tool, and launches a separate Node verification process with the returned absolute `handoff.cwd`. That process verifies its cwd, branch, full `HEAD`, and lack of remotes. The smoke then calls the registered `remove_worktree` tool, verifies the directory is absent, verifies the retained local branch remains at the original commit, and asserts that `retire_branch` was never invoked.
 - The handoff smoke uses only a freshly created temporary source repository and sibling worktree, an empty Git config, a minimal credential-free environment, no remotes, offline Pi flags, and a fetch guard that fails on any network request. Cleanup recursively removes the isolated temporary root even on failure.
 - `npm run validate` includes the isolated handoff smoke after package-content checks.
 - The checkout command smoke accepts either `/branchme help` text or the read-only BranchMe status fallback as equivalent non-mutating command output.
@@ -41,11 +44,11 @@ pi --no-extensions -e .
 ## Result
 
 - `npm run typecheck`, `npm run format:check`, `npm run test`, `npm run smoke:pi`, `npm run check:pack`, `npm run validate`, and `npm run smoke:pi:packed` passed.
-- `npm run smoke:worktree-handoff` returned `ok: true`, an absolute ready cwd, the expected `feature/isolated-handoff-smoke` branch and full commit ID from a separate process, `branchRetained: true` after force-free removal, zero network requests, and an isolated empty credential source.
-- `npm run smoke:pi` loaded BranchMe through Pi, verified the complete BranchMe tool set and prompt metadata through real Pi runtime APIs, and confirmed non-mutating BranchMe command output.
+- `npm run smoke:worktree-handoff` returned `ok: true`, an absolute ready cwd, the expected `feature/isolated-handoff-smoke` branch and full commit ID from a separate process, `branchRetained: true` after force-free removal, `retireBranchInvoked: false`, zero network requests, and an isolated empty credential source.
+- `npm run smoke:pi` loaded BranchMe through Pi, verified exactly thirteen BranchMe tools (including strict `integrate_branch`, `retire_branch`, and nested `branch_status.ancestry` schemas), proved merge-continuation tools absent, and confirmed non-mutating BranchMe command output.
 - The isolated Git-context prompt smoke observed the `before_agent_start` snapshot, answered branch and dirty-tree state without a tool call, refreshed a verifier-created local change through one real `branch_status` call, returned safe unavailable context without credentials or outside Git, and attempted no network request.
 - `npm run smoke:pi:packed` packed BranchMe outside the repository, installed the artifact in a temporary production workspace, loaded the installed package through Pi, and confirmed non-mutating BranchMe command output.
-- `npm run check:pack` confirmed the package contents are limited to public docs (including worktree behavior and security boundaries), images, source, license, package metadata, `.env.example`, and `tsconfig.json`; private planning specs and generated files remain excluded.
+- `npm run check:pack` confirmed the package contents are limited to public docs (including worktree, local integration, leased local branch-retirement, and security boundaries), images, source, license, package metadata, `.env.example`, and `tsconfig.json`; private planning specs and generated files remain excluded.
 - The isolated Pi smoke command loaded BranchMe and displayed BranchMe help or status output instead of template behavior.
 - The bare `pi --no-extensions -e .` smoke command exited cleanly in this non-interactive validation environment.
 - No template command or template tool output was observed.

package/docs/STRUCTURE.md

@@ -1,6 +1,6 @@
 # BranchMe Structure Guide
 
-BranchMe is a TypeScript Pi extension package for current-repository Git branch, verified linked-worktree, push, and GitHub pull request workflows.
+BranchMe is a TypeScript Pi extension package for current-repository Git branch, verified branch-integration and retirement, linked-worktree, push, and GitHub pull request workflows.
 
 ## Source layout
 
@@ -13,8 +13,10 @@ src/
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
-│   └── branchme-tools.ts         # registration for eleven branch/worktree/GitHub workflow tools
-├── git.ts                        # argv-style branch/worktree helpers and per-repo workflow queue
+│   └── branchme-tools.ts         # registration for thirteen branch/integration/retirement/worktree/GitHub tools
+├── git.ts                        # shared argv-style Git primitives and per-repo mutation queue
+├── git-integration.ts            # integration preflight, merge, cleanup, and verification state machine
+├── git-retirement.ts             # leased local-ref retirement and postcondition state machine
 ├── github.ts                     # GitHub repo resolution, env/.env tokens, branch preflight, REST calls, redaction
 └── ui/
     └── branchme-panel.ts         # compact /branchme status panel renderer
@@ -22,27 +24,29 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, eleven tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, thirteen tools, and one `before_agent_start` context hook.
 2. `src/git-context.ts` owns the shared read-only collector, escaped/bounded formatter, automatic system-prompt append, and the current-state output used by `branch_status`.
 3. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
-4. `src/tools/branchme-tools.ts` owns strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector; `list_worktrees`, `create_worktree`, and `remove_worktree` expose explicit repository inventory and verified handoff operations.
-5. `src/git.ts` owns current-repository Git behavior: root and common-Git-directory detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, PR base/commit-subject inference, branch validation and branch workflows, NUL-delimited worktree parsing/inventory, canonical worktree path validation, verified create/remove postconditions, and the per-repository workflow queue.
-6. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` and `BRANCHME_PR_AUTOFILL` process-env/hardened git-root `.env` resolution, authenticated related-open-PR lookup, PR branch-name syntax validation, GitHub branch visibility/commit preflight, PR REST calls, bounded response validation, and redacted errors.
-7. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
-8. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
-9. `src/ui/branchme-panel.ts` renders a compact status panel and clips lines to terminal width.
+4. `src/tools/branchme-tools.ts` owns strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector and optional ancestry verifier; `integrate_branch` and `retire_branch` delegate to focused mutation state machines; worktree tools expose explicit inventory and verified handoff operations.
+5. `src/git.ts` owns reusable current-repository Git primitives: root and canonical common-Git-directory identity, strict direct local-ref inspection, branch/ref validation, local commit ancestry, operation-state and working-tree inspection, complete bounded worktree occupancy, branch/upstream workflows, worktree parsing/path validation/create/remove verification, and the process-local per-repository mutation queue.
+6. `src/git-integration.ts` owns the integration preflight, one-window merge mutation, conflict-path capture, automatic abort, outcome classification, and repository/ref/worktree/ancestry postcondition verification. It never fetches, pushes, resets, switches branches, or continues merges.
+7. `src/git-retirement.ts` owns strict runtime input validation, expected-`HEAD` and target-ancestry preflight, complete worktree-occupancy rejection, expected-old-value `update-ref` deletion, cancellation-safe final inspection, merged/forced-unmerged classification, and bounded uncertain errors. It never deletes remote or remote-tracking refs, removes worktrees, edits branch configuration, or performs reset rollback.
+8. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` and `BRANCHME_PR_AUTOFILL` process-env/hardened git-root `.env` resolution, authenticated related-open-PR lookup, PR branch-name syntax validation, GitHub branch visibility/commit preflight, PR REST calls, bounded response validation, and redacted errors.
+9. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
+10. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
+11. `src/ui/branchme-panel.ts` renders a compact status panel and clips lines to terminal width.
 
 ## Pi extension conventions
 
 - No long-lived processes, watchers, timers, sockets, or background jobs start in the extension factory.
 - A single `before_agent_start` handler synchronously collects a fresh snapshot for each agent run and appends it to the existing system prompt; failures degrade to bounded unavailable context rather than blocking startup.
-- Slash commands are informational; tools perform branch, worktree, push, and PR actions. Commands never create/remove worktrees, change cwd, or start Pi sessions. There is no context command.
-- Every tool uses a strict TypeBox object schema with `additionalProperties: false`; worktree creation requires exactly `worktreePath`, `branchName`, and `branchMode`, while listing is empty and removal accepts only `worktreePath`.
+- Slash commands are informational; tools perform branch, integration, retirement, worktree, push, and PR actions. Commands never create/remove worktrees, merge or retire branches, change cwd, or start Pi sessions. There is no context command.
+- Every tool uses a strict TypeBox object schema with `additionalProperties: false`; `integrate_branch` requires exactly `sourceBranch` and `targetBranch`; `retire_branch` requires exactly `branchName`, full commit `expectedHead`, distinct `targetBranch`, and boolean `force`; worktree creation requires exactly `worktreePath`, `branchName`, and `branchMode`, listing is empty, and removal accepts only `worktreePath`.
 - Every tool defines a description, `promptSnippet`, and tool-specific `promptGuidelines` that explicitly name the tool.
-- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from verified locations and same-repository mutation/PR windows are serialized per repository.
+- Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from verified locations and same-repository mutation/PR windows are serialized per repository. Retirement uses one canonical-active-worktree-keyed queue window from preflight through final verification. The queue is process-local and does not lock a different active worktree, another Pi process, or an external Git process.
 - Worktree results expose serializable requested and verified before/after state. Create returns `handoff: { cwd: <absolute>, branch, head, ready: true, summary }`; remove returns the retained branch/HEAD with `cwd: null` and `ready: false`.
 - Tool details avoid token values, abort signals, runtime objects, and unbounded raw command/API output.
-- Automatic and explicit context include branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged/untracked entries, related open PR state, and up to 5 recent commits. Metadata values default to 512 characters and rendered context to 4,000 characters.
+- Automatic and explicit context include branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged/untracked entries, related open PR state, and up to 5 recent commits. Explicit `branch_status` may additionally verify one strict local source/target ancestry query; automatic context never does. Metadata values default to 512 characters and rendered context to 4,000 characters.
 - Pi core packages, including `@earendil-works/pi-tui` for key/width utilities, remain in `peerDependencies` with `"*"`.
 
 ## Security-sensitive areas
@@ -50,11 +54,17 @@ src/
 - Automatic context and `branch_status` share bounded, read-only collection. They run no mutations and capture repository metadata only—never diffs or file contents.
 - Repository-controlled paths, branch names, commit subjects, and PR fields are escaped, quoted, redacted, bounded, and labeled untrusted before system-prompt insertion.
 - Related-PR lookup may issue an authenticated `GET /pulls` before every agent run and on explicit refresh. It has a 4-second timeout and 64 KiB response limit, and makes no unauthenticated fallback request.
-- The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh.
+- The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh. Its optional targeted ancestry proof must run after `integrate_branch`, not in the same parallel tool batch.
 - `change_branch` mutates local HEAD and working-tree files only through `git switch <branchName>` for existing local branches after a clean-worktree preflight.
 - `fetch_branch` requires a configured upstream and runs `git fetch --no-tags --no-recurse-submodules <remote> <remote-ref>:<remote-tracking-ref>`; its explicit refspec updates only that tracking ref without changing local branches or working-tree files.
 - `pull_branch` requires a clean worktree and configured upstream, then updates only the current branch with an explicit `git pull --ff-only --no-rebase --no-autostash <remote> <remote-ref>` command; divergence fails without a rebase or merge commit.
 - `rebase_branch` requires a clean worktree and configured upstream, then rebases only the current branch with `git rebase --no-autostash --no-update-refs <upstream>`; it rewrites local commits and automatically attempts `git rebase --abort` on failure.
+- `integrate_branch` requires distinct existing local refs and a clean control worktree already on the target. It rejects non-empty target-branch `mergeOptions`, runs `git -c rerere.enabled=false merge --ff --no-edit --no-autostash --no-rerere-autoupdate --no-overwrite-ignore refs/heads/<sourceBranch>`, verifies before/after refs and ancestry, and classifies already-integrated, fast-forward, exact two-parent merge-commit, or conflict.
+- Conflict status is emitted only after bounded lossless paths are captured, `git merge --abort` succeeds, and repository identity, exact refs, target checkout, absent operation state, and clean worktree restoration are verified. Failed or uncertain postconditions throw; no reset rollback or continuation tool exists.
+- `retire_branch` requires one direct local ref, its exact full expected `HEAD`, one distinct direct local target, and a boolean force decision. It rejects complete-inventory worktree occupancy, proves ancestry against captured commits, and allows negative ancestry only with explicit `force: true` authorization.
+- Retirement deletes only `refs/heads/<branchName>` with `git update-ref --no-deref -d <fullRef> <capturedHead>`. The expected-old-value lease prevents deleting a moved ref; final repository, target, retiring-ref, and occupancy checks run with bounded timeouts after the mutation attempt even if the caller cancels. Contradictory or inconclusive state throws an uncertain error with manual-inspection guidance and no rollback ref mutation.
+- Local branch configuration, worktrees, remote refs, and remote-tracking refs remain untouched by retirement. Forced unmerged retirement may remove a commit's last local branch reference, and normal expiry/garbage collection can eventually make it unreachable.
+- Git hooks, custom merge drivers, clean/smudge filters, signing policy, and `reference-transaction` hooks stay active where Git invokes them and may execute commands or network operations outside BranchMe's direct argv boundary.
 - `create_branch` mutates local branch/HEAD only with `git switch -c`.
 - `list_worktrees` reads a bounded `git worktree list --porcelain -z` inventory and remains explicit rather than expanding automatic active-worktree context.
 - `create_worktree` requires an explicitly approved absolute destination, canonicalizes its existing parent, rejects existing or nested/common-Git-directory destinations, and creates only from current `HEAD` or an unoccupied existing local branch. It verifies canonical path, branch, `HEAD`, and cleanliness before returning a ready handoff.
@@ -62,7 +72,7 @@ src/
 - `push_branch` mutates remote refs only for the current branch and uses an explicit upstream remote/refspec instead of bare `git push` when an upstream exists.
 - `pull_request` requires resolved `headBranch` and `baseBranch` values to be distinct and exist locally, requires `headBranch` to match the GitHub-visible branch commit, queues behind already-started same-repository git mutation windows, makes GitHub REST API calls for the resolved current repository only, and rejects owner-prefixed or unsafe branch refs before the request. Omitted fields require configured autofill.
 - `pull_request` reads `GITHUB_TOKEN` or `GH_TOKEN` from process environment first; only when neither process token is set does it read those token keys from a small regular `.env` file in the verified git root as a fallback. `BRANCHME_PR_AUTOFILL` uses the same process-first, `.env`-fallback precedence and defaults off.
-- BranchMe does not force checkout/removal, move/prune/repair/lock/unlock worktrees, create detached/orphan worktrees, infer remote worktree branches, copy ignored/untracked files such as `.env`, remove linked worktrees that contain ignored entries, delete retained worktree branches, change Pi's cwd, or start Pi sessions. It also does not stash, stage, create user-authored commits, reset, force-push, create merge commits, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
+- BranchMe does not force checkout/removal, move/prune/repair/lock/unlock worktrees, create detached/orphan worktrees, infer remote worktree branches, copy ignored/untracked files such as `.env`, remove linked worktrees that contain ignored entries, delete retained worktree branches during removal, change Pi's cwd, or start Pi sessions. It also does not stash, stage, create user-authored commits, accept commit messages, reset, force-push, directly edit files, read unsupported `.env` keys, follow unsafe `.env` file types, depend on GitHub CLI, or collect telemetry. Only explicit `integrate_branch` may let Git create a standard merge commit for divergent histories; only explicit leased `retire_branch` may delete one exact local branch ref. Retirement has no bulk, inferred-target, remote, remote-tracking, rollback, or automatic worktree deletion. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
 
 ## Documentation
 
@@ -78,10 +88,12 @@ test/
 ├── command.test.mjs      # /branchme parsing, help, fallback, panel width
 ├── git-context.test.mjs  # collection, prompt hook, formatting, safety, and output bounds
 ├── git.test.mjs          # branch/worktree parsing, validation, command construction, postconditions, failures
-├── git-integration.test.mjs # isolated real-Git context, branch, and worktree lifecycle coverage
+├── git-integration.test.mjs # isolated real-Git context, branch integration, and worktree lifecycle coverage
+├── git-retirement.test.mjs # mocked retirement preflight, lease, postconditions, and failures
+├── git-retirement-integration.test.mjs # isolated real-Git local-ref retirement lifecycle coverage
 ├── github.test.mjs       # GitHub parsing, token resolution, related-PR lookup, redaction
 ├── preparation.test.mjs  # package/docs/source metadata checks
-├── schema-validation.test.mjs # strict TypeBox schema validation, including worktree fields/modes
+├── schema-validation.test.mjs # strict TypeBox schema validation, including worktree and retirement fields
 ├── tools.test.mjs        # extension registration, prompt metadata, shared refresh, tool behavior
 └── tui-capture.test.mjs  # generated text capture for TUI/help visual baselines
 ```

package/docs/TUI_CAPTURE.md

@@ -31,13 +31,27 @@ Commands only show info; BranchMe tools perform actions.
 7. `push_branch` — push the current branch.
 8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.
 
+## Branch integration
+
+- `integrate_branch` — integrate an exact local source into an exact local target; the clean control worktree must already have the target checked out.
+- It never fetches or pushes; a conflict is automatically aborted after paths are captured and restoration is verified.
+- BranchMe does not resolve semantic conflicts; handle them in a separate developer workflow.
+
+## Branch retirement
+
+- `remove_worktree` and `retire_branch` are separate: removal retains the branch; retirement later deletes only the exact local branch ref.
+- `retire_branch` requires the exact local branch, its full expected `HEAD`, and an exact local target for ancestry verification.
+- Any registered worktree occupancy rejects retirement; remove an occupying linked worktree separately first.
+- Merged retirement uses `force: false`; unmerged retirement requires explicit authorization with `force: true` and may make commits unreachable.
+- It never directly deletes a remote or remote-tracking branch.
+
 ## Worktree handoff
 
 - `list_worktrees` — inspect the main and linked worktrees in the current repository.
 - `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.
 - A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.
 - `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.
-- BranchMe does not change cwd, start Pi, copy `.env`, or remove branches automatically.
+- BranchMe does not change cwd, start Pi, or copy `.env`; `remove_worktree` never removes its retained branch automatically.
 
 ## Requirements
 
@@ -47,7 +61,7 @@ Commands only show info; BranchMe tools perform actions.
 - `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.
 - `pull_branch` and `rebase_branch` require a clean working tree.
 - `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.
-- BranchMe never stages, creates user-authored commits, force-pushes, or creates merge commits.
+- BranchMe never stages, creates user-authored commits, or force-pushes.
 ```
 
 ## Panel: Tiny mode: clean branch with token
@@ -80,7 +94,30 @@ Width: 40
 │                                      │
 │                                      │
 ├──────────────────────────────────────┤
-│ 1/3 • status • current repository on…│
+│ 1/4 • status • current repository on…│
+╰──────────────────────────────────────╯
+```
+
+## Panel: Narrow mode: Lifecycle selected
+
+Width: 40
+
+```text
+╭ BranchMe ───────────────── Lifecycle ╮
+│current repo only • informational     │
+│ ↑↓ section • q quit • /branchme help │
+├──────────────────────────────────────┤
+│ LIFECYCLE                            │
+│  integrate_branch -> exact local sou…│
+│  control target   -> checked out + c…│
+│  conflict         -> automatic verif…│
+│  semantic intent  -> separate develo…│
+│  remove_worktree  -> separate; branc…│
+│  retire_branch    -> leased local re…│
+│  retirement guard -> unoccupied + ta…│
+│  remote effects   -> never delete re…│
+├──────────────────────────────────────┤
+│ 3/4 • lifecycle • integrate → remove…│
 ╰──────────────────────────────────────╯
 ```
 
@@ -94,15 +131,15 @@ Width: 80
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │▶  Status            │ STATUS                                                 │
 │   Workflow          │  Current branch:    feature/current                    │
-│   Worktrees         │  GitHub repository: senad-d/branchme                   │
-│                     │  GitHub token:      present                            │
+│   Lifecycle         │  GitHub repository: senad-d/branchme                   │
+│   Worktrees         │  GitHub token:      present                            │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 1/3 • status • current repository only • tools perform actions               │
+│ 1/4 • status • current repository only • tools perform actions               │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -115,16 +152,38 @@ Width: 80
 │ ↑↓ section • q quit • /branchme help                                         │
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │   Status            │ WORKFLOW                                               │
-│▶  Workflow          │  branch_status   -> inspect                            │
-│   Worktrees         │  change_branch   -> existing local                     │
-│                     │  fetch_branch    -> upstream remote                    │
-│                     │  pull_branch     -> fast-forward                       │
-│                     │  rebase_branch   -> onto upstream                      │
-│                     │  create_branch   -> from HEAD                          │
-│                     │  push_branch     -> current branch                     │
-│                     │  pull_request    -> after push                         │
+│▶  Workflow          │  branch_status    -> inspect                           │
+│   Lifecycle         │  change_branch    -> existing local                    │
+│   Worktrees         │  fetch_branch     -> upstream remote                   │
+│                     │  pull_branch      -> fast-forward                      │
+│                     │  rebase_branch    -> onto upstream                     │
+│                     │  create_branch    -> from HEAD                         │
+│                     │  push_branch      -> current branch                    │
+│                     │  pull_request     -> after push                        │
+├─────────────────────┴────────────────────────────────────────────────────────┤
+│ 2/4 • workflow • inspect → change → fetch/pull/rebase → create → push → PR   │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+## Panel: Wide mode: Lifecycle selected
+
+Width: 80
+
+```text
+╭ BranchMe ───────────────────────────────────────────────────────── Lifecycle ╮
+│ ↑↓ section • q quit • /branchme help                                         │
+├─────────────────────┬────────────────────────────────────────────────────────┤
+│   Status            │ LIFECYCLE                                              │
+│   Workflow          │  integrate_branch -> exact local source -> target      │
+│▶  Lifecycle         │  control target   -> checked out + clean               │
+│   Worktrees         │  conflict         -> automatic verified abort          │
+│                     │  semantic intent  -> separate developer workflow       │
+│                     │  remove_worktree  -> separate; branch retained         │
+│                     │  retire_branch    -> leased local ref deletion         │
+│                     │  retirement guard -> unoccupied + target ancestry      │
+│                     │  remote effects   -> never delete remote refs          │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 2/3 • workflow • inspect → change → fetch/pull/rebase → create → push → PR   │
+│ 3/4 • lifecycle • integrate → remove worktree separately → retire local ref  │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -137,16 +196,16 @@ Width: 80
 │ ↑↓ section • q quit • /branchme help                                         │
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │   Status            │ WORKTREES                                              │
-│   Workflow          │  list_worktrees  -> inspect inventory                  │
-│▶  Worktrees         │  create_worktree -> ready handoff.cwd                  │
-│                     │  remove_worktree -> clean linked; branch retained      │
+│   Workflow          │  list_worktrees   -> inspect inventory                 │
+│   Lifecycle         │  create_worktree  -> ready handoff.cwd                 │
+│▶  Worktrees         │  remove_worktree  -> clean linked; branch retained     │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 3/3 • worktrees • create → handoff cwd → next session • remove retains branch│
+│ 4/4 • worktrees • create → handoff cwd → next session • remove retains branch│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -160,15 +219,15 @@ Width: 112
 ├──────────────────────┬───────────────────────────────────────────────────────────────────────┤
 │▶  Status             │ STATUS                                                                │
 │   Workflow           │  Current branch:    main                                              │
-│   Worktrees          │  GitHub repository: senad-d/BranchMe                                  │
-│                      │  GitHub token:      not set                                           │
+│   Lifecycle          │  GitHub repository: senad-d/BranchMe                                  │
+│   Worktrees          │  GitHub token:      not set                                           │
 │                      │                                                                       │
 │                      │                                                                       │
 │                      │                                                                       │
 │                      │                                                                       │
 │                      │                                                                       │
 ├──────────────────────┴───────────────────────────────────────────────────────────────────────┤
-│ 1/3 • status • current repository only • tools perform actions                               │
+│ 1/4 • status • current repository only • tools perform actions                               │
 ╰──────────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -191,7 +250,7 @@ Width: 50
 │                                                │
 │                                                │
 ├────────────────────────────────────────────────┤
-│ 1/3 • warning • Unable to resolve a GitHub rep…│
+│ 1/4 • warning • Unable to resolve a GitHub rep…│
 ╰────────────────────────────────────────────────╯
 ```
 
@@ -205,15 +264,15 @@ Width: 80
 ├─────────────────────┬────────────────────────────────────────────────────────┤
 │▶  Status            │ STATUS                                                 │
 │   Workflow          │  Current branch:    main                               │
-│   Worktrees         │  GitHub repository: warning: Repository boundary misma…│
-│                     │  GitHub token:      present                            │
+│   Lifecycle         │  GitHub repository: warning: Repository boundary misma…│
+│   Worktrees         │  GitHub token:      present                            │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 │                     │                                                        │
 ├─────────────────────┴────────────────────────────────────────────────────────┤
-│ 1/3 • warning • Repository boundary mismatch: local origin resolves to senad…│
+│ 1/4 • warning • Repository boundary mismatch: local origin resolves to senad…│
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -227,15 +286,15 @@ Width: 72
 ├───────────────────┬──────────────────────────────────────────────────┤
 │▶  Status          │ STATUS                                           │
 │   Workflow        │  Current branch:    main                         │
-│   Worktrees       │  GitHub repository: senad-d/branchme             │
-│                   │  GitHub token:      warning: Unable to read .env…│
+│   Lifecycle       │  GitHub repository: senad-d/branchme             │
+│   Worktrees       │  GitHub token:      warning: Unable to read .env…│
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
-│ 1/3 • warning • Unable to read .env file for GitHub token fallback: …│
+│ 1/4 • warning • Unable to read .env file for GitHub token fallback: …│
 ╰──────────────────────────────────────────────────────────────────────╯
 ```
 
@@ -249,14 +308,14 @@ Width: 72
 ├───────────────────┬──────────────────────────────────────────────────┤
 │▶  Status          │ STATUS                                           │
 │   Workflow        │  Current branch:    feature/super-long-branch-na…│
-│   Worktrees       │  GitHub repository: very-long-owner-name/very-lo…│
-│                   │  GitHub token:      present                      │
+│   Lifecycle       │  GitHub repository: very-long-owner-name/very-lo…│
+│   Worktrees       │  GitHub token:      present                      │
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 │                   │                                                  │
 ├───────────────────┴──────────────────────────────────────────────────┤
-│ 1/3 • warning • This deliberately long status note is captured to de…│
+│ 1/4 • warning • This deliberately long status note is captured to de…│
 ╰──────────────────────────────────────────────────────────────────────╯
 ```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Pi extension for verified current-repository Git branch, worktree, push, and pull request workflows.",
+  "description": "Pi extension for verified current-repository Git branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",
   "author": "Senad Dizdarević <112484166+senad-d@users.noreply.github.com>",
   "repository": {

package/src/commands/branchme-command.ts

@@ -40,13 +40,27 @@ export function getBranchMeHelpText(): string {
     "7. `push_branch` — push the current branch.",
     "8. `pull_request` — open a PR after `push_branch` completes and GitHub sees the branches.",
     "",
+    "## Branch integration",
+    "",
+    "- `integrate_branch` — integrate an exact local source into an exact local target; the clean control worktree must already have the target checked out.",
+    "- It never fetches or pushes; a conflict is automatically aborted after paths are captured and restoration is verified.",
+    "- BranchMe does not resolve semantic conflicts; handle them in a separate developer workflow.",
+    "",
+    "## Branch retirement",
+    "",
+    "- `remove_worktree` and `retire_branch` are separate: removal retains the branch; retirement later deletes only the exact local branch ref.",
+    "- `retire_branch` requires the exact local branch, its full expected `HEAD`, and an exact local target for ancestry verification.",
+    "- Any registered worktree occupancy rejects retirement; remove an occupying linked worktree separately first.",
+    "- Merged retirement uses `force: false`; unmerged retirement requires explicit authorization with `force: true` and may make commits unreachable.",
+    "- It never directly deletes a remote or remote-tracking branch.",
+    "",
     "## Worktree handoff",
     "",
     "- `list_worktrees` — inspect the main and linked worktrees in the current repository.",
     "- `create_worktree` — create a linked worktree and return a ready handoff with an absolute `handoff.cwd`.",
     "- A separate orchestrator starts the next Pi session or subagent in `handoff.cwd`.",
     "- `remove_worktree` — remove a verified clean linked worktree while retaining its local branch.",
-    "- BranchMe does not change cwd, start Pi, copy `.env`, or remove branches automatically.",
+    "- BranchMe does not change cwd, start Pi, or copy `.env`; `remove_worktree` never removes its retained branch automatically.",
     "",
     "## Requirements",
     "",
@@ -56,7 +70,7 @@ export function getBranchMeHelpText(): string {
     "- `fetch_branch`, `pull_branch`, and `rebase_branch` require a configured upstream.",
     "- `pull_branch` and `rebase_branch` require a clean working tree.",
     "- `rebase_branch` rewrites local commits only when explicitly requested and auto-aborts on failure.",
-    "- BranchMe never stages, creates user-authored commits, force-pushes, or creates merge commits.",
+    "- BranchMe never stages, creates user-authored commits, or force-pushes.",
   ].join("\n");
 }
 

package/src/constants.ts

@@ -12,6 +12,8 @@ export const PULL_REQUEST_TOOL_NAME = "pull_request";
 export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
 export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
+export const INTEGRATE_BRANCH_TOOL_NAME = "integrate_branch";
+export const RETIRE_BRANCH_TOOL_NAME = "retire_branch";
 export const PULL_REQUEST_AUTOFILL_ENV_NAME = "BRANCHME_PR_AUTOFILL";
 
 export const BRANCHME_TOOL_NAMES = [
@@ -21,6 +23,8 @@ export const BRANCHME_TOOL_NAMES = [
   FETCH_BRANCH_TOOL_NAME,
   PULL_BRANCH_TOOL_NAME,
   REBASE_BRANCH_TOOL_NAME,
+  INTEGRATE_BRANCH_TOOL_NAME,
+  RETIRE_BRANCH_TOOL_NAME,
   PUSH_BRANCH_TOOL_NAME,
   PULL_REQUEST_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
@@ -35,6 +39,8 @@ export const GIT_PULL_TIMEOUT_MS = 120_000;
 export const GIT_REBASE_TIMEOUT_MS = 120_000;
 export const GIT_PUSH_TIMEOUT_MS = 120_000;
 export const GIT_WORKTREE_MUTATION_TIMEOUT_MS = 120_000;
+export const GIT_INTEGRATION_TIMEOUT_MS = 120_000;
+export const GIT_RETIREMENT_MUTATION_TIMEOUT_MS = 30_000;
 export const GITHUB_RELATED_PR_TIMEOUT_MS = 4_000;
 
 export const GIT_CONTEXT_RECENT_COMMIT_LIMIT = 5;
@@ -48,6 +54,11 @@ export const GIT_WORKTREE_ENTRY_LIMIT = 100;
 export const GIT_WORKTREE_PATH_LIMIT_CHARS = 4_096;
 export const GIT_WORKTREE_REASON_LIMIT_CHARS = 512;
 export const GIT_WORKTREE_SUMMARY_LIMIT_CHARS = 4_000;
+export const GIT_INTEGRATION_CONFLICT_RAW_OUTPUT_LIMIT_BYTES = 128 * 1024;
+export const GIT_INTEGRATION_CONFLICT_ENTRY_LIMIT = 100;
+export const GIT_INTEGRATION_CONFLICT_PATH_LIMIT_CHARS = 4_096;
+export const GIT_INTEGRATION_SUMMARY_LIMIT_CHARS = 4_000;
+export const GIT_RETIREMENT_SUMMARY_LIMIT_CHARS = 4_000;
 
 export const GITHUB_API_BASE_URL = "https://api.github.com";
 export const GITHUB_API_VERSION = "2022-11-28";