@senad-d/branchme 0.1.7 → 0.1.9

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -1,12 +1,12 @@
 # Project Definition Brief
 
-Approved on 2026-06-30.
+Originally approved on 2026-06-30. Updated to describe the implemented `0.1.9` package.
 
-## 1. Bootstrap
+## 1. Bootstrap history
 
 - Template source: `/Users/senad/Documents/Code/Moj_git/pi-tmp`
 - Target directory: `/Users/senad/Documents/Code/Moj_git/pi-branchme`
-- Copy status: copied; target only had `.git/` and `.pi/`, both preserved/excluded.
+- Copy status: copied; the target's existing `.git/` and `.pi/` directories were preserved and excluded from the copy.
 
 ## 2. Project identity
 
@@ -14,101 +14,153 @@ Approved on 2026-06-30.
 - Display name: `BranchMe`
 - Exported extension function: `branchMeExtension`
 - Repository URL: `https://github.com/senad-d/branchme`
-- One-sentence pitch: Minimal Pi tools for changing/creating current-repo branches, publishing the current branch, and opening a GitHub pull request.
+- One-sentence pitch: Verified current-repository Pi tools for branch, integration, linked-worktree, push, and GitHub pull request workflows.
+- Tool count: twelve strict agent-callable tools.
 
 ## 3. Users and use cases
 
-- Primary users: Pi users and CI/GitHub Actions workflows.
+- Primary users: Pi users, specialized Git subagents, orchestrators, and CI/GitHub Actions workflows.
 - Primary use cases:
-  - Check current git branch/repo status.
-  - Switch to an existing local branch after clean-worktree preflight.
-  - Create and checkout a new branch from current `HEAD`.
+  - Inspect bounded current-repository branch, upstream, working-tree, related-PR, and recent-commit state, with an optional explicit local source/target ancestry proof.
+  - Integrate one exact existing local source branch into the already-current clean local target, returning verified no-op, fast-forward, merge-commit, or restored-conflict details.
+  - List the current repository's main and linked worktrees explicitly.
+  - Create and verify a linked worktree for a new branch from current `HEAD` or an unoccupied existing local branch.
+  - Return an exact, absolute, machine-readable worktree handoff for a caller-managed separate Pi session or subagent.
+  - Remove an exact verified linked worktree only when it is clean and contains no ignored entries, while retaining its local branch.
+  - Switch to an existing local branch after a clean-worktree preflight or create a new branch from current `HEAD`.
+  - Fetch a configured upstream tracking ref, fast-forward the current branch, or explicitly rebase it.
   - Push the current branch to its configured upstream, or publish it to `origin` when no upstream exists.
-  - Create a PR in the current GitHub repo via REST API.
+  - Create a pull request in the resolved current GitHub repository through the REST API.
 - Non-goals:
-  - No commit, staging, or diff generation behavior. Optional PR title/body autofill may summarize bounded commit subjects.
-  - No GitHub CLI dependency.
-  - No cross-repository PR creation.
-  - No labels, reviewers, projects, or issue linking in v1.
+  - No staging, direct working-tree edits, user-authored commits, commit-message input/generation, diff generation, stashing, resets, or force pushes. Explicit `integrate_branch` may let Git create its standard merge commit for divergent histories.
+  - No automatic Pi cwd changes, process/session creation, or copying of `.env` and other ignored/untracked files into linked worktrees.
+  - No GitHub CLI dependency or cross-repository pull requests.
+  - No labels, reviewers, projects, or issue-linking behavior.
 
 ## 4. Pi integration surface
 
 | Surface | Name | Purpose | Notes |
 | --- | --- | --- | --- |
-| Command | `/branchme` | Simple TUI config/status/help panel | No git/GitHub mutations |
-| Command | `/branchme help` | Workflow notes | No actions |
-| Tool | `branch_status` | Read current repo/branch/upstream/dirty/push state | Read-only |
-| Tool | `change_branch` | Switch to an existing local branch | Required `branchName`; rejects dirty worktrees |
-| Tool | `create_branch` | Create + checkout new branch from current `HEAD` | Required `branchName`; fail if exists/invalid |
-| Tool | `push_branch` | Push current branch with explicit upstream target; publish with upstream if needed | No commits/staging |
-| Tool | `pull_request` | Preflight branch visibility/commit state and create PR via GitHub REST API | PR fields are explicit by default and may be omitted only with configured autofill; repo inferred from current checkout |
-| Event | `session_start/session_shutdown` | Optional status footer cleanup | No long-lived resources |
-| UI | TUI panel | Compact BranchMe workflow/config view | No persisted config assumed |
-| Resource | none | No skills/prompts/themes planned | Keep package minimal |
+| Command | `/branchme` | Compact TUI status and workflow panel | Informational; no Git or GitHub mutations |
+| Command | `/branchme help` | Runtime requirements and workflow guidance | Informational; no actions |
+| Tool | `branch_status` | Refresh bounded current-worktree Git and related-PR context; optionally prove captured local-branch ancestry | Read-only; targeted ancestry is absent from automatic context |
+| Tool | `integrate_branch` | Integrate one exact local source into the already-current clean local target | Fixed normal-merge policy; verified automatic abort/restoration on conflict |
+| Tool | `list_worktrees` | List bounded main/linked worktree inventory | Read-only and explicit |
+| Tool | `create_worktree` | Create and verify a linked worktree | Exact absolute handoff cwd; new/existing local branch modes only |
+| Tool | `remove_worktree` | Remove an exact verified clean linked worktree | Force-free; ignored entries block removal; branch retained |
+| Tool | `change_branch` | Switch to an existing local branch | Rejects dirty worktrees |
+| Tool | `fetch_branch` | Refresh the current branch's configured tracking ref | Explicit fetch refspec; no checkout change |
+| Tool | `pull_branch` | Fast-forward the clean current branch | No rebase, merge commit, or autostash |
+| Tool | `rebase_branch` | Rebase the clean current branch onto its upstream | Explicit history rewrite; automatic abort attempt on failure |
+| Tool | `create_branch` | Create and check out a new branch from current `HEAD` | Fails when invalid or already present |
+| Tool | `push_branch` | Push or publish the current branch | Explicit remote/refspec behavior |
+| Tool | `pull_request` | Preflight branch state and create a GitHub pull request | Current repository only; autofill is opt-in |
+| Event | `before_agent_start` | Append fresh bounded Git context to the system prompt | Read-only collection; no worktree inventory |
+| UI | TUI panel | Compact BranchMe workflow/configuration view | Responsive and width-bounded |
+| Resource | none | No bundled skills, prompts, or themes | Package remains extension-focused |
 
 ## 5. Architecture
 
-- Planned files:
+- Implemented source layout:
   - `src/extension.ts`
   - `src/constants.ts`
+  - `src/types.ts`
+  - `src/redaction.ts`
+  - `src/git-context.ts`
   - `src/commands/branchme-command.ts`
   - `src/tools/branchme-tools.ts`
   - `src/git.ts`
+  - `src/git-integration.ts`
   - `src/github.ts`
-  - `src/types.ts`
+  - `src/ui/branchme-panel.ts`
 - Module boundaries:
-  - Extension entrypoint only registers command/tools/events.
-  - Git helper owns `pi.exec("git", args)` calls and branch/repo validation.
-  - GitHub helper owns env token lookup, branch visibility/commit preflight, and REST requests.
-  - Tools expose precise TypeBox schemas and structured details.
+  - The extension entry point registers the informational command, twelve tools, and automatic context hook.
+  - The context module owns bounded read-only collection, prompt formatting, targeted ancestry rendering, and the `before_agent_start` hook; automatic context never runs ancestry queries.
+  - The command and UI modules own mode-safe informational help/status behavior and never invoke mutations.
+  - The tools module owns strict TypeBox schemas, descriptions, prompt metadata, bounded display content, and serializable result details.
+  - The general Git helper owns reusable argv-style current-repository inspection, branch/ref/ancestry and operation-state primitives, branch/upstream workflows, worktree parsing/path validation/create/remove verification, and process-local same-repository mutation serialization.
+  - The integration module owns the clean-control preflight, fixed merge mutation, automatic conflict abort, outcome classification, and repository/ref/worktree/ancestry verification without absorbing that state machine into the general helper.
+  - The GitHub helper owns repository resolution, token/autofill configuration, related-PR lookup, branch visibility and commit preflight, and pull request REST calls.
+  - The redaction module owns shared credential redaction for display and prompt-bound metadata.
+  - Shared public details remain JSON-serializable and contain no runtime objects or abort signals.
 - Dependencies:
-  - Pi core packages as peer deps with `"*"`.
-  - `@earendil-works/pi-tui` is a peer/dev dependency because the TUI panel imports width and key utilities.
-  - No Octokit; use Node 22 `fetch`.
-
-## 6. Config, state, and persistence
-
-- Config source: no separate BranchMe config file; `/branchme` displays runtime status and workflow notes. GitHub tokens and `BRANCHME_PR_AUTOFILL` may come from process environment or a small regular `.env` fallback in the verified git root.
-- Session state: none; tool results include useful `details`.
-- Files written: none by extension code, except normal git metadata changes from branch checkout/push.
-- Cleanup behavior: clear any footer/status key on `session_shutdown` if used.
-
-## 7. Security and privacy
-
-- Shell execution: only `git` via argv-style `pi.exec`, not shell strings.
-- File access/mutation: no working-tree file edits; git metadata changes only.
-- Network access: `pull_request` calls `https://api.github.com/repos/{owner}/{repo}/branches/{branch}` before `https://api.github.com/repos/{owner}/{repo}/pulls`.
-- Credentials/secrets: `GITHUB_TOKEN` / `GH_TOKEN` from process env or hardened local `.env` fallback; never log token.
-- Telemetry/retention: none.
-- User confirmations: no extra confirmation by default, to support automation; tools rely on explicit arguments.
-
-## 8. Documentation and packaging
-
-- README changes: describe implemented behavior, workflow, tools, CI env usage.
-- SECURITY changes: document git mutation, GitHub API, token behavior.
-- CHANGELOG changes: rename initial unreleased entry to BranchMe.
-- package.json changes: set package identity/URLs/keywords/peer deps.
-- npm/git distribution plan: npm package `@senad-d/branchme`, repo `senad-d/branchme`.
-
-## 9. Validation plan
+  - `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `@earendil-works/pi-tui`, and `typebox` are direct peer/development dependencies; Pi peers use `"*"` for host compatibility.
+  - `@earendil-works/pi-ai` supplies `StringEnum` for the strict `create_worktree.branchMode` schema.
+  - `@earendil-works/pi-tui` supplies panel width and key utilities.
+  - Node 22 supplies `fetch`; BranchMe does not depend on Octokit or GitHub CLI.
+
+## 6. Configuration, state, and filesystem boundary
+
+- Config source: no separate BranchMe config file. `GITHUB_TOKEN`, `GH_TOKEN`, and `BRANCHME_PR_AUTOFILL` use process-environment values first and may fall back to supported keys in a hardened regular `.env` file at the verified Git root.
+- Session state: no persisted BranchMe state. Tool calls return serializable details, and mutation/PR coordination is in-memory and process-local only; other Pi sessions and external Git processes are not locked.
+- Active-checkout mutations: explicit branch switching, creation, pull, rebase, and integration operations can update Git metadata and working-tree files through Git. Push and fetch operations can update remote or remote-tracking refs through Git.
+- Linked-worktree mutations: `create_worktree` can create a checkout directory outside the active checkout after canonical destination and repository-boundary validation. `remove_worktree` can recursively remove only an exact verified linked-worktree directory after clean and ignored-entry preflights.
+- BranchMe does not directly edit project files, stage content, create user-authored commits, accept commit messages, copy local-only files into new worktrees, delete the retained branch during removal, or mutate worktrees through slash commands. `integrate_branch` may cause Git to create a standard merge commit under the verified boundary below.
+
+## 7. Worktree handoff contract
+
+- `list_worktrees` reads bounded NUL-delimited porcelain inventory and keeps worktree discovery out of automatic active-worktree context.
+- `create_worktree` requires an explicitly approved absolute destination whose immediate parent exists. It rejects existing destinations and locations inside registered worktrees or the repository's common Git directory.
+- New mode creates a local branch from current `HEAD` only. Existing mode accepts only an existing local branch not checked out in another worktree; no remote branch is inferred.
+- Before mutation, canonical cwd and branch identity must fit documented limits and remain unchanged by redaction, escaping, Unicode handling, or truncation.
+- Successful creation verifies canonical path, local branch, full `HEAD`, and clean state, then returns the exact canonical absolute cwd and local branch in `handoff: { cwd, branch, head, ready: true, summary }`.
+- Removal accepts only an exact fresh inventory match that is linked, present, unlocked, non-prunable, non-bare, branch-attached, and neither main nor current.
+- Staged, unstaged, untracked, unmerged, and ignored entries all block removal. The bounded ignored-entry preflight does not disclose ignored paths or contents.
+- Successful force-free removal verifies that the worktree entry is absent and the retained local branch still points to its captured commit, then returns `handoff: { cwd: null, branch: <exact retained branch>, head, ready: false, summary }`.
+- BranchMe never returns a ready handoff containing `[REDACTED]`, escaped control sequences, or a BranchMe-introduced truncation ellipsis in machine-readable cwd or branch identity fields.
+
+## 8. Branch integration contract
+
+- `integrate_branch` accepts exactly `sourceBranch` and `targetBranch`. They must identify distinct existing local refs in the current repository; remote-only refs, full refs, commit IDs, paths, repositories, remotes, and owner-prefixed refs are rejected.
+- The active Pi worktree is the control worktree and must already have the target checked out, be clean, and have no merge/rebase/cherry-pick/revert/sequencer state. The source may be checked out in another dirty worktree because only its captured commit ref is read.
+- Before mutation, BranchMe rejects a non-empty `branch.<targetBranch>.mergeOptions` setting so branch-specific defaults cannot change the policy. The fixed command is `git -c rerere.enabled=false merge --ff --no-edit --no-autostash --no-rerere-autoupdate --no-overwrite-ignore refs/heads/<sourceBranch>`. It does not fetch or push, disables autostash and rerere, protects ignored files, and preserves hooks, custom merge drivers, clean/smudge filters, and signing policy.
+- Results distinguish `already_integrated`, `fast_forward`, `merge_commit`, and `conflict`. Before/after source and target commit IDs, repository/control-worktree identity, clean/operation state, and source/prior-target ancestry are verified. Merge-commit classification requires exact captured target/source parents.
+- Conflict paths are exact bounded repository-relative identities. `conflict` is returned only after `git merge --abort` succeeds and exact ref, repository, branch, operation-state, and clean-worktree restoration is verified. Failed non-conflict merges remain errors.
+- There is no reset-based rollback, `continue_merge`, `abort_merge`, custom merge message, strategy, squash, unrelated-history, signing, force, or commit control. Unexpected ref movement or inconclusive cleanup produces an uncertain error and manual inspection guidance.
+- The mutation queue covers the complete operation but is process-local. BranchMe neither starts agents nor resolves semantic conflicts; Mission or another orchestrator may separately decide whether to delegate conflict analysis to an integration agent or ask the developer about intent.
+- `branch_status` may receive `{ "ancestry": { "sourceBranch": string, "targetBranch": string } }` for an independent read-only proof. It must run after integration completes, not in the same parallel tool batch; automatic context remains unchanged.
+
+## 9. Security and privacy
+
+- Every Git command uses `pi.exec("git", args, { cwd, signal, timeout })` with an argv array rather than shell interpolation.
+- Paths, branch names, Git output, commit subjects, and pull request metadata are treated as untrusted. Display and prompt surfaces are escaped, redacted, and bounded separately from prevalidated exact handoff identities.
+- Worktree paths are canonicalized and checked against a fresh current-repository inventory or the common Git directory before mutation. User-supplied removal paths are never passed directly to Git.
+- Worktree removal has no force path and rejects dirty, ignored-entry-containing, detached, locked, prunable/missing, bare, main, current, and foreign entries before mutation.
+- Worktree tools expose no force, move, prune, repair, lock, unlock, detached, orphan, remote-inference, arbitrary refspec, or arbitrary start-point controls. Git's incomplete submodule worktree support is not bypassed with force cleanup.
+- Automatic context and `branch_status` never collect diffs or file contents. Related-PR lookup may make a bounded authenticated GitHub request only when credentials and repository identity resolve; there is no unauthenticated fallback.
+- `pull_request` uses the resolved current GitHub repository, preflights local and GitHub branch identity, and rejects cross-repository head refs. Git fetch/pull/push use the user's normal Git credentials.
+- BranchMe's direct integration command is local-only, but repository-configured hooks, merge drivers, filters, and signing policy may execute arbitrary commands or network operations under the user's identity outside BranchMe's argv guarantees.
+- Tokens are resolved from supported process or verified-root `.env` keys and redacted from prompts, errors, content, and details. BranchMe collects no telemetry.
+- Creation and removal require explicit user intent and an exact approved path. BranchMe does not silently infer worktree destinations or start a separate agent session.
+
+## 10. Documentation and packaging
+
+- `README.md` is the primary public workflow and tool reference.
+- `SECURITY.md` documents local filesystem, Git, GitHub, credential, and prompt-insertion boundaries.
+- `docs/STRUCTURE.md` describes the implemented source and test layout.
+- `docs/SMOKE_TEST.md` records isolated checkout, handoff, and installed-package smoke behavior.
+- `CHANGELOG.md` tracks the active `0.1.9` unreleased changes.
+- npm distribution uses package `@senad-d/branchme`; package-content checks exclude private specs, credentials, generated files, caches, and local state.
+
+## 11. Validation plan
 
 - Typecheck: `npm run typecheck`
-- Tests: unit and isolated integration tests for commands, tools, git/GitHub helpers, package metadata, and TUI captures.
-- Package dry-run: `npm run check:pack`
-- Formatting: `npm run format:check`
-- Full validation: `npm run validate`
-- Checkout Pi smoke test: `npm run smoke:pi` / `pi --no-extensions -e .`
-- Installed-artifact release smoke: `npm run smoke:pi:packed`
-
-## 10. Open questions and assumptions
-
-- Questions:
-  - None blocking.
-- Assumptions:
-  - `/branchme` has no persisted config in v1.
-  - `push_branch` uses `origin` when current branch has no upstream.
-  - `pull_request` infers owner/repo from current GitHub checkout or `GITHUB_REPOSITORY`, but never accepts owner/repo as tool input and requires local branch refs with `headBranch` matching GitHub.
-- Decisions:
-  - No commit functionality.
-  - Tools perform all actions; slash commands are help/config only.
-  - PR tool requires all PR fields explicitly unless `BRANCHME_PR_AUTOFILL=true`; explicit values always take precedence.
+- Formatting and documentation checks: `npm run format:check`
+- Unit and isolated real-Git integration tests: `npm run test`
+- Checkout Pi runtime/context smoke: `npm run smoke:pi`
+- Isolated specialized-agent handoff smoke: `npm run smoke:worktree-handoff`
+- Package dry-run/content boundary: `npm run check:pack`
+- Complete checkout validation: `npm run validate`
+- Installed-artifact smoke: `npm run smoke:pi:packed`
+- Canonical local and automated release gate: `npm run release:check`
+
+## 12. Current decisions
+
+- Slash commands remain informational; tools perform all Git and GitHub actions.
+- Automatic context remains focused on the active worktree; inventory is available only through `list_worktrees`.
+- `create_worktree` returns a verified target for a caller-managed session but does not change cwd or create processes.
+- `integrate_branch` is the only merge surface; it uses normal local merge semantics, automatically aborts initial conflicts, and exposes no merge continuation or semantic-resolution workflow.
+- Worktree removal remains force-free, blocks ignored entries, and preserves the local branch.
+- `push_branch` uses `origin` only when the current branch has no configured upstream.
+- `pull_request` infers owner/repository from the current checkout or matching `GITHUB_REPOSITORY`, never accepts owner/repository tool inputs, and requires local branch refs with the head matching GitHub.
+- Pull request fields remain explicit unless `BRANCHME_PR_AUTOFILL=true`; explicit values always take precedence.

package/docs/SMOKE_TEST.md

@@ -1,16 +1,21 @@
 # BranchMe Smoke Test Notes
 
-Date: 2026-07-15
+Date: 2026-08-23
 
 Validated from the repository checkout with no discovered extensions enabled.
 
 ## Commands
 
 ```bash
-npm run validate
+npm run typecheck
+npm run format:check
+npm run test
 npm run smoke:pi
-npm run smoke:pi:packed
 npm run check:pack
+npm run smoke:worktree-handoff
+npm run validate
+npm run smoke:pi:packed
+npm run release:check
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 pi --no-extensions -e .
 ```
@@ -18,24 +23,31 @@ 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`, `fetch_branch`, `pull_branch`, `rebase_branch`, `create_branch`, `push_branch`, and `pull_request` are active runtime tools with strict schemas, 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 temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly twelve tools—`branch_status`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_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. 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. 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 twelve tools but forbids `integrate_branch` and every remote or worktree mutation tool from executing.
+- The Pi runtime smoke validates worktree and integration tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree and never runs a merge. 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.
+- `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 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.
 - `npm run smoke:pi:packed` creates an npm tarball under a temporary directory, installs that tarball into a separate temporary package with `npm install --omit=dev`, and runs pi against the installed package instead of the source checkout.
-- `npm run smoke:pi:packed` is the release gate for packaged runtime imports and required packaged files; `npm run release:check` and `node scripts/publish-npm.mjs` run it before publish, while everyday `npm run validate` keeps the faster checkout smoke.
-- Both smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
-- Both smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation tools, and do not contact GitHub.
-- Pi's documented `getAllTools()` metadata currently exposes parameter schemas and prompt guidelines, but not `promptSnippet`. The deterministic local smoke model exercises `branch_status` through Pi's normal model tool-call loop without provider or GitHub network access.
+- `npm run release:check` is the canonical release gate: it runs `npm run validate` and then `npm run smoke:pi:packed`. Both `node scripts/publish-npm.mjs` and the GitHub `Publish to npm` workflow run it before npm publication; a packed install/load failure stops publication and the workflow's Git tag step. Everyday `npm run validate` keeps the faster checkout smoke.
+- Both Pi smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
+- Both Pi smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation or remote tools, and do not contact GitHub.
+- Pi's documented `getAllTools()` metadata exposes parameter schemas, descriptions, prompt guidelines, and source metadata, while command context exposes active `promptSnippet` values through `getSystemPromptOptions().toolSnippets`; the runtime verifier checks both surfaces. The deterministic local smoke model exercises `branch_status` through Pi's normal model tool-call loop without provider or GitHub network access.
 - Set `BRANCHME_SKIP_PI_SMOKE=1` to skip intentionally, or `BRANCHME_PI_BIN=/path/to/pi` to test a specific Pi binary for the checkout smoke.
 - If no Pi binary is available, the checkout smoke script prints an explicit skip message; default CI installs the Pi dev dependency, so `npm run validate` exercises the real Pi loading path.
 
 ## Result
 
-- `npm run validate` passed.
-- `npm run smoke:pi` loaded BranchMe through Pi, verified all eight BranchMe tools through the real `pi.getAllTools()` runtime surface, and confirmed non-mutating BranchMe command output.
+- `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 exactly twelve BranchMe tools (including strict `integrate_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, images, source, license, package metadata, `.env.example`, and `tsconfig.json`.
+- `npm run check:pack` confirmed the package contents are limited to public docs (including worktree, local integration, 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 fetch/update/rebase, push, and GitHub pull request workflows.
+BranchMe is a TypeScript Pi extension package for current-repository Git branch, verified branch-integration, linked-worktree, push, and GitHub pull request workflows.
 
 ## Source layout
 
@@ -13,8 +13,9 @@ src/
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
-│   └── branchme-tools.ts         # registration for eight branch/GitHub workflow tools
-├── git.ts                        # argv-style git helpers and per-repo workflow queue
+│   └── branchme-tools.ts         # registration for twelve branch/integration/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
 ├── github.ts                     # GitHub repo resolution, env/.env tokens, branch preflight, REST calls, redaction
 └── ui/
     └── branchme-panel.ts         # compact /branchme status panel renderer
@@ -22,26 +23,28 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, eight tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, twelve 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 TypeBox schemas, prompt metadata, tool content, and safe structured details. `branch_status` delegates to the shared context collector for an explicit refresh.
-5. `src/git.ts` owns current-repository git behavior: root detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, PR base/commit-subject inference, branch validation, branch creation, existing-local-branch switching, configured-upstream fetch, clean-worktree preflight, fast-forward-only current-branch pull, current-branch rebase with automatic abort on failure, current-branch push/publish, 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` delegates to the focused integration state machine; 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, branch/ref validation, local commit ancestry, operation-state and working-tree inspection, 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/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.
+8. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
+9. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
+10. `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 fetch/update/rebase, push, and PR actions. There is no context command.
-- Every tool uses a strict TypeBox object schema with `additionalProperties: false`.
+- Slash commands are informational; tools perform branch, integration, worktree, push, and PR actions. Commands never create/remove worktrees, merge 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`, 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 the verified git root and same-repository mutation/PR windows are serialized per repository.
-- Tool details avoid token values 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.
+- 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. The queue is process-local and does not lock other Pi or Git processes.
+- 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. 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
@@ -49,16 +52,22 @@ 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.
+- Git hooks, custom merge drivers, clean/smudge filters, and signing policy stay active during integration 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.
+- `remove_worktree` resolves an exact fresh current-repository inventory match, rejects main/current/dirty/ignored-entry-containing/detached/locked/prunable/missing/bare entries, runs a bounded removal-specific ignored-entry scan, performs force-free removal with the verified path, and confirms that the local branch remains at the same commit.
 - `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, 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. Rebase-driven commit rewriting occurs only through explicit `rebase_branch` calls.
+- 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, 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; it does not fetch, push, continue merges, or resolve semantic conflicts. Git documents submodule worktree support as incomplete; BranchMe adds no force-based submodule cleanup.
 
 ## Documentation
 
@@ -73,11 +82,12 @@ src/
 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          # git helper command construction and failures
-├── git-integration.test.mjs # isolated real-git context and branch helper coverage
+├── git.test.mjs          # branch/worktree parsing, validation, command construction, postconditions, failures
+├── git-integration.test.mjs # isolated real-Git context, branch integration, and worktree lifecycle coverage
 ├── github.test.mjs       # GitHub parsing, token resolution, related-PR lookup, redaction
 ├── preparation.test.mjs  # package/docs/source metadata checks
-├── tools.test.mjs        # extension registration, schemas, shared refresh, tool behavior
+├── schema-validation.test.mjs # strict TypeBox schema validation, including worktree fields/modes
+├── tools.test.mjs        # extension registration, prompt metadata, shared refresh, tool behavior
 └── tui-capture.test.mjs  # generated text capture for TUI/help visual baselines
 ```